lgf 和 小wt 的第一个 iOS 小项目
一款基于 AI 的农业病虫害识别 App,帮助用户拍照识别植物病虫害,提供社区交流和 AI 助手功能。
本文维护产品概览、运行操作与验证边界。详细工作区审阅、交接笔记和历史材料不随源码发布;开发与协作流程见 CONTRIBUTING.md。
- 短信验证码登录 / 密码登录
- 微信绑定页面占位(正式登录页无真实微信授权 SDK 接入)
- 新用户偏好设置引导(适老模式、作物类型选择)
- 首页当前是
UITableView:预警、识别/记录/AI 功能卡、创建作物卡和作物管理卡;不是资讯瀑布流
- 相机实时预览、闪光灯切换、拍照 / 相册选图
- 云端主识别:图片压缩并上传 URL 后调用 AgriPestClient
/chat - 本地 Core ML 兜底:Vision 三种 crop 策略聚合,云端失败或结果无效时使用
- WCDB 中存在识别记录表和 CRUD API;当前未发现识别页面或记录页面实际写入该表,记录页读取远端 history
- 识别结果详情:病害名、置信度和防治方案;“依据”字段的实际展示未由当前结果 View 确认
- 详情页一键跳转 AI 助手并自动发送病害名
- 社区为自定义单/双列瀑布流,包含分页、结构更新、封面加载/预取、详情回刷与确认后发布。布局、数据、图片是独立链路;尚无 postId 去重,Cell 复用未显式取消远图,预取无引用计数,不宣称无错图或已量化性能提升
- 帖子详情页:图文展示、评论、点赞、收藏
- 语音搜索(Apple Speech),不是评论输入
- 发布页负责图片上传与创建帖子;收到业务成功及有效服务端帖子 ID 后,才通过
onPublished更新列表和提示成功。请求中禁用重复发布;上传或业务失败保留当前页面输入。提交后断网/超时会提示先核实“我的发布”,不会自动重复提交;这不是持久草稿功能
- 支持文字与单图 URL 问诊、原生增量 Markdown、停止与部分回复保留;正式会话按用户本地保存,并附带有预算的历史上下文
- Markdown 展示分离 Turn 有界语法暂存与 BodyView 唯一分块解析;稳定块复用,变化段落生成富文本后计算文字/属性 Render Patch,通过 NSTextStorage 更新已有 UITextView,并按整行实测高度变化合并提交布局。仍会重算变化长段落,不宣称字符级单次解析或已量化提速
- 文字流、Apple Speech 输入和 Dialog 实时通话是不同链路,生命周期和异常处理不能相互替代
- 客户端显式 job 恢复已实现,正式新问诊仍使用旧流,共享后端尚未接入;「重新生成」与「继续接收」不同
- 输入、传输、解析、状态、展示和存储分层实现;正式旧流不自动重发 POST,客户端恢复能力不代表共享后端已部署对应协议
- 定位页展示当前城市、推荐城市、城市字母分组列表
- 点击搜索框跳转独立搜索页(
TLWLocationSearchController) - 搜索页以约 250ms debounce 调用 MapKit 的
MKLocalSearch,结果展示距离和地址;不是本地城市数组的实时过滤 - 点击结果直接选中城市并返回;手动选择的城市名与最近系统定位坐标目前可能不一致,天气仍使用最近系统坐标
- 编辑资料页(Figma 1:1 还原,独立毛玻璃卡片设计)
- 头像更换(相册选图 + 圆形裁剪)
- 昵称修改
- 换绑手机号(页面有验证码输入框和发送方法,但输入框隐藏且禁用;确认请求只提交新手机号,不校验验证码)
- 修改密码(当前不展示自动注册原始密码;
generatedPasswordgetter 未形成可用链路) - 我的收藏列表(分页加载 + 下拉刷新)
- 设置页:系统通知权限开关、合规页面(隐私政策 / 用户协议,WebView 内展示)
- 双 Token 与身份采用单条 Keychain 记录保存,具备并发 refresh 排队及按用户数据库切换;单记录原子保存不等于全系统跨存储事务
- 单记录保存失败不发布新会话;旧凭据迁移、并发刷新及调用者重试仍有边界,不能将局部接口的一次重试扩大为全站账号隔离保障
- 当前不具备完整第三方登录/运营商一键认证;不能将某个接口的鉴权重试描述成全站自动覆盖
- 统一 Toast 组件(TLWToast,白色居中 + 半透明遮罩)
- 部分关键按钮在请求期间禁用或由业务状态防重;当前没有统一的全站防抖组件
App 启动
└── TLWPasswordLoginController(登录页)
└── 登录成功
└── TLWMainTabBarController(主 TabBar)
├── Tab 1: TLWHomePageController 首页
├── Tab 2: TLWCommunityController 社区
├── Tab 3: TLWMessageController 消息
└── Tab 4: TLWMyController 我的
TabBar 由自定义
UIViewController容器手动管理四个UINavigationController;TLWTabBar作为子视图嵌入,虽是UITabBar子类,但不使用UITabBarController的系统 Tab 管理逻辑。所有页面均隐藏系统导航栏,使用自定义导航栏 + 右滑返回手势。
TL-PestIdentify/
├── TL-PestIdentify/ # 核心壳:AppDelegate、SceneDelegate、TabBar
│ └── TL-TabBar/ # TLWMainTabBarController、TLWTabBar
├── TL_Login/ # 登录模块
│ ├── login/ # 短信登录、密码登录
│ ├── wechat/ # 微信绑定
│ └── guide/ # 引导页、偏好选择、头像裁剪
├── TL_HomePage/ # 首页
│ ├── Models/ # 首页模型
│ └── Resources/Images/ # 首页图片资源
├── TL_PhotoIdentify/ # 拍照识别页
│ └── Resources/Images/ # 识别页图片资源
├── TL_Community/ # 社区
│ └── Resources/Images/ # 社区图片资源
├── TL_Publish/ # 发布帖子
├── TL_My/ # 我的
│ ├── Avatar/ # 相册选图、头像裁剪
│ ├── EditProfile/ # 编辑资料(Figma 还原)
│ ├── EditNickname/ # 修改昵称
│ ├── ChangePhone/ # 换绑手机号
│ ├── ChangePassword/ # 修改密码
│ ├── Favorite/ # 我的收藏
│ └── Setting/ # 设置
├── TL_Record/ # 识别记录列表
│ └── TL_RecordDetail/ # 识别记录详情
├── TL_AIAssistant/ # AI 助手
├── TL_Message/ # 消息
│ ├── Controllers/
│ ├── Views/
│ ├── Models/
│ └── Components/
├── TL_Notification/ # 通知
│ ├── Controllers/
│ ├── Views/
│ ├── Models/
│ └── Components/
└── TL_Common/ # 公共工具
├── UI/ # Toast、PhotoCell 等通用 UI
├── Media/ # 相机、相册、语音
├── Network/ # TLWSDKManager(统一 API 封装)
└── TLWWCDB/ # 本地数据库
- 语言: Objective-C(少量
.mm用于 WCDB/C++) - 最低系统: iOS 15.0(以当前 Podfile、target 和 post_install 为准)
- UI: 纯代码布局(Masonry);实际页面由代码构造,SceneDelegate 显式设置 root
- 架构: MVC;AI 助手由 Controller 编排,Session/Store/Persistence 管会话,Turn 管一轮生命周期,StreamClient/Parser 管传输,FramePacer/IncrementalMarkdown/原生块视图管展示
- 依赖管理: CocoaPods
| Pod | 版本/来源 | 用途 |
|---|---|---|
| AFNetworking | 3.2.1(AgriPestClient 间接依赖) | HTTP 网络请求 |
| YYModel | 1.0.4 | JSON 解析映射 |
| WCDB.objc | 2.1.16,git master 锁定 commit | 本地 SQLite 数据库 |
| Masonry | Podfile 未固定小版本 | AutoLayout DSL |
| SDWebImage | 5.21.7(~> 5.0) |
异步图片加载缓存 |
| AgriPestClient | git tag v1.0.110 |
后端 OpenAPI 生成 SDK |
| SpeechEngineToB | 0.0.14.2-bugfix |
AI 通话/Dialog 语音 |
| LookinServer | Debug only | UI 层级调试 |
# 1. 克隆仓库
git clone https://github.com/pop-xiaoli-hub/TL-PestIdentifyProject.git
cd TL-PestIdentifyProject
# 2. 安装 CocoaPods 依赖(在 TL-PestIdentify 目录下)
cd TL-PestIdentify && pod install
# 3. 打开工作区(必须用 .xcworkspace,不要直接开 .xcodeproj)
open TL-PestIdentify.xcworkspace在 Xcode 中选择目标设备或模拟器,Command + R 运行。
仅 Debug 显式启用,不修改 SDK 全局后端地址。客户端仍走真实 NSURLSession → SSE parser → turn → 增量刷新 → 聊天页面,不是直接向气泡塞文字。
测试服务不会随 Xcode 的 Run 自动启动。先在仓库根目录单独运行(Python 3.9+,无第三方依赖;本机防火墙已允许 /usr/bin/python3 入站):
/usr/bin/python3 -u scripts/ai_sse_server.py --host 0.0.0.0 --port 8765 --scenario normal --speed slow0.0.0.0:8765 用于允许可信局域网内的真机访问;只在可信网络运行,不把端口暴露到公网。服务不记录提问、请求头或凭据;若误收到 Authorization/Cookie 会拒绝请求,绝不回显值。
Xcode 选择共享 Scheme TL-PestIdentify-LocalSSE(不是普通 TL-PestIdentify),目标选真机后直接 Run。该 Scheme 已固定:
| 名称 | 值 |
|---|---|
TLW_AI_STREAM_TEST_URL |
http://192.168.1.61:8765/api/v1/agent/chat/stream |
这是当前 Mac Wi-Fi 地址。换网络后用 ipconfig getifaddr en0 核对,并在该 Scheme 的 Run 环境变量里更新;真机不能用 127.0.0.1 指代 Mac。普通 Scheme 与 Release 不带这个变量,仍走真实后台。
重新运行 Debug App,会直接打开标题带「本地测试」的 AI 助手,不依赖正式登录/启动资料接口;返回会退出测试页到登录导航根页,重新运行可再进入。输入任意非空文字发送。预置六轮本地历史,最后一条可直接预览列表、长代码和表格;每次回答固定,开头即包含 Markdown/emoji 样本,随后有 24 个阅读锚点和长链接。代码、表格是真实原生横向容器,不是管道字符排版。正常完整回复只出现一次 TLW_STREAM_END_2026;手动提前完成、错误和 EOF 不要求出现尾标。
在运行服务的同一个终端输入命令并回车:
| 命令 | 行为 |
|---|---|
pause / resume |
暂停/继续正文;暂停期间每 0.5 秒发注释心跳,不等于模拟网络空闲超时 |
done |
立即用已发送正文形成最终快照,再发送完成事件 |
error |
保留已发正文,再发送本地模拟错误 |
disconnect |
不发 done,直接关闭连接,验证未完成 EOF |
scenario normal / split / error / eof / hold |
切换后续请求剧本;输入时保留 scenario 前缀,例如 scenario split |
speed slow / normal / fast |
切换后续请求速度,例如 speed fast |
status / quit |
查看活动流数量 / 关闭服务 |
暂停和终态命令作用于当前所有活动流,不会预先影响下一轮。split 使用 CRLF/LF、多事件批量写入,并把 UTF-8 字节切成小块;TCP/URLSession 可以重新合并这些块,一次服务端写入不等于一次接收回调。error/eof 在部分正文后结束;hold 在第 50 个增量后自动暂停,适合手动触发收尾。App 点击停止会取消真实连接,不会自动重发。
验收时用 slow 或 hold,不要只看快速完整回复:
- 生成时点击正文收起键盘;输入框、按钮和已有文字选区不被背景收键盘手势拦截。
- 普通长正文由外层列表纵向滚动,不再出现 240pt 正文视口或固定 300pt 生成行。
- 灰色识别卡内部先消费纵向位移,到顶/底再接力外层;从卡外拖动不改卡内位置。
- 代码/宽表格/图片条左右滑动,纵向起手则交给外层;停在历史时新增内容不强行追底。距底超过 24pt 时,输入区上方居中显示回底部箭头;点击后按最后一行的测得高度回到底部,而不是停在估算行高。
- 拖动期间输入
done,检查完成收尾不突然解除限高或重建已闭合块,并保留阅读锚点。 - 完成后长按选区、复制 emoji/代码、点击链接,检查文本、换行和手势仲裁。
- 停止后立即发送下一轮、离页后重进,检查旧流不续写、测试消息不恢复。
- 在内容区右划不退出;从左边缘返回并中途取消,回复仍继续。真正返回后旧流不得继续写入。
- 真断网/超时或
disconnect后保留部分回复;点「重新生成」产生新任务,旧的部分回复不被覆盖。pause持续发心跳,不能用来证明 8 秒网络静默提示。
隔离边界:本地请求不发送真实 Token/Cookie/共享凭据,不附带定位,不调用正式鉴权刷新、profile 对比或图片上传。选中图片仅用于内存预览,不写正式图片归档;测试回答另附 4 张可横滑图片和可内滚识别卡。生成中已增量渲染 Markdown,完成后开放正文选择。测试会话只在内存。其他业务接口不受这个开关影响。非法/空测试地址直接报错,不回退线上。取消环境变量并重新运行即可恢复正式模式;Release 无法启用该覆盖。
服务回归:python3 -m unittest discover -s scripts -p 'test_*.py' -v。本地服务与网络解析验证不代替真机手势、生产鉴权、代理缓冲及上游模型联调。
同一服务也提供本地 stream-job.v1 fixture。验证客户端同任务恢复时,在 Debug Run 环境中显式将 TLW_AI_STREAM_TEST_URL 的路径改为 /api/v1/agent/jobs,主机与端口沿用当前可信局域网服务地址;不要改 SDK 生产地址或 Release 开关。启动输出 JOB_PROTOCOL 给出端点;scenario reconnect / duplicate / gap / expired / lost-ack / retry-exhausted 选择后续 job 的故障剧本,status 区分活动订阅与创建任务数。普通 /chat/stream 不具备这些 job 语义;Debug 测试会话仍仅在内存,不能用这条路径证明崩溃后正式 WCDB 恢复。
鉴权/资料单测通过 TLWAuthStatePreservingTestCase 在内存保存并于正常 tearDown 恢复原有 Defaults、Keychain、SDK 运行时 Token 与共享用户上下文,不记录凭据;2026-10-25 已将新增的 auth_session 记录纳入保护。旧版状态恢复回归曾在真机通过,不代表新版单记录迁移已通过真机验收;此前被旧用例删除的凭据无法追回,正式模式仍可能需要重新登录。
验证应分别记录构建、组件测试、本地真实 HTTP/SSE、真机和生产后端结果。仓库提供 TL-PestIdentify-UnitTests 与本地 fixture;本地固定回复不证明生产模型、真实上传/鉴权或完整恢复协议可用,历史通过结果也不替代当前版本复验。
| 项目 | 说明 |
|---|---|
| 后端仓库 | https://github.com/lukecc00/AgroAiServer |
| 后端地址 | 由受控环境配置提供;本仓库文档不记录具体服务器地址 |
| 部署方式 | Docker |
# 查看后端最新提交
gh api 'repos/lukecc00/AgroAiServer/commits?sha=master&per_page=20' \
--jq '.[] | "\(.commit.author.date) | \(.commit.author.name) | \(.commit.message)"'- 云端主识别 + 本地 Core ML 兜底
- AI 助手 SSE 领域事件解析、客户端注释心跳、增量输出、停止回复、图片 URL 输入
- 社区分页、下拉刷新、超时保护、自定义双列瀑布流、封面预取、真实图片比例、按帖高度缓存
- WCDB 收藏、我的发布按用户隔离;识别记录表和 CRUD 已实现,但当前未发现识别业务页面写入该表
- AI 会话按用户持久化、上下文预算与连接代际隔离;Debug 本地 SSE 测试使用独立内存会话
- 显式 job 协议的客户端恢复、事务检查点及本地 fixture;正式旧流和共享后端尚未切换
- 识别页流式化 — 当前主识别路径仍是一次性
/chat,可复用TLWAIStreamClient先展示病害再流式输出方案 - SSE 端到端验收 — 既有组件、fixture 和 iPhone 定向单测不等于整套产品验收;当前复杂手势、长文/低电量性能、最后修补后的完整传输场景,以及共享后端 job 联调仍待验证
- 社区差分数据源 — 当前分页追加使用 batch insert,Diffable Data Source/稳定 ID 合并仍未引入
- 发布异常场景验收 — 成功提示和列表回调已等待服务端确认;失败保留页面输入、结果未知先核实,仍需真实后端场景验证,不自动重复提交
- 发布草稿回显 —
tl_applyDraftIfNeeded仍为空 - 发布页图片预览/删除
- 个人主页背景图与分享功能 — 分享按钮当前为占位
- 微信登录 / QQ 登录 — 第三方授权 SDK 尚未接入
- 推送闭环 — 系统授权与注册调用存在;当前未发现 device token 上报或收到/点击推送的完整处理链路
AI 助手的状态、协议和展示实现位于 TL-PestIdentify/TL_AIAssistant/,回归用例位于 TL-PestIdentify/TL-PestIdentifyTests/。社区和登录分别位于 TL_Community/ 与 TL_Common/Network/。以当前源码和可复现运行结果为准,不将规划、客户端协议或本地 fixture 描述成已上线能力。
植小保 — 让每一位农人都有随身的植保专家