Vue 3 + TypeScript · FastAPI · RAG/KG · Rich TUI 农业问题输入 → 知识检索 → 决策评估 → 诊断报告与全过程 Trace
ACIS(Agricultural Cognitive Intelligence System)是一个面向温室作物病害咨询的 多阶段 AI 系统工程原型:把一次自然语言问诊拆成 “感知 → 记忆 → 专家 → 辩论 → Critic → Judge → 审计”的可追溯流程, 输出诊断、置信度、风险等级、行动建议与证据链。默认使用规则裁决,可选接入 OpenAI-compatible LLM;外部模型不可用时自动回退规则链路。Web 端采用 Vue 3 + TypeScript,开发时由 Vite 提供服务,生产环境由 FastAPI 同源托管静态构建产物。
本项目是单机、离线可运行的工程原型,不是生产系统,也没有经过真实田间验证。 传感器/天气为模拟数据,图片识别默认 mock;这些边界在本文中逐项标明。
温室/大棚种植者在病害早期缺少“可解释、可追溯”的诊断建议:单一模型输出往往 无法说明依据了哪些环境、知识库或历史案例证据,也不清楚何时应弃权或转人工。
ACIS 将问诊拆成可审计的多阶段流程,输出:
- 首选病害 + 置信度 + 风险等级;
- 是否建议人工复核;
- 6 条左右的行动建议;
- 辩论共识/冲突、知识图谱校验、推理摘要;
- 可导出的 10 阶段 Trace 与 SQLite 决策审计记录。
覆盖 4 种作物、7 类病害知识(番茄叶霉病/早疫病,黄瓜霜霉病,甜菜褐斑病/根腐病, 棉花黄萎病/枯萎病);黄瓜保留兼容。
| 类别 | 当前实现 |
|---|---|
| 真实实现 | LangGraph 主图与规则回退编排;感知/记忆/专家/Debate/Critic/Judge 分层;RAG(Qdrant 优先、内存回退);知识图谱(Neo4j 优先、内置 DISEASE_DB 回退);SQLite 决策/反馈/结果存储;统一 Trace(10 阶段);CLI、Rich TUI、FastAPI 与 Vue Web 共用诊断服务;规则裁决与失败回退。 |
| 模拟数据 | 传感器读数与异常检测输入为确定性模拟;天气为模拟/随机生成;不是真实 IoT 或气象接入。 |
| mock / 可选模型 | 图片识别默认 mock(可选 transformers 模型,但真实视觉效果未验证,离线不下载模型);LLM Judge/Critic 为可选增强,需要 API key,规则路径不依赖。 |
| 可选/默认关闭 | Planner 默认关闭(ACIS_ENABLE_PLANNER=0);开启后只生成计划,不自动执行。 |
| 未实现/未验证 | 工具执行(ToolRouter 只生成请求,不执行施药/灌溉);真实田间/生产并发/SLA;真实 LLM 质量只做过单次连通性验证。Docker 本地验收结果及知识库为空时的回退边界见第 8 节。 |
flowchart TD
CLI["CLI: orchestrator.py"] --> ORCH["AgentOrchestrator.run"]
TUI["TUI: ui/tui.py"] --> ORCH
WEB["Vue 3 + TypeScript Web"] --> API["FastAPI: gateway/app.py"]
API --> ORCH
ORCH --> LG{"LangGraph 可用?"}
LG -- "是" --> WF["workflow.py:context→perception→memory→experts→debate→critic→judge"]
LG -- "否 / 异常" --> RULES["run_rules 规则编排"]
WF --> PER["感知:视觉(可选/跳过) + 传感器(模拟) + 天气(模拟)"]
RULES --> PER
PER --> MEM["记忆:RAG(Qdrant/内存) + KG(Neo4j/DISEASE_DB) + 案例/经验(SQLite)"]
MEM --> EXP["专家:病理(规则+知识库) + 气象/栽培/经济/生态"]
EXP --> DEB["Debate:共识/冲突"]
DEB --> CRI["Critic:规则/可选 LLM 降权"]
CRI --> JUD["Judge:规则/可选 LLM + 置信度策略"]
JUD --> OUT["DecisionOutput:裁决/置信度/风险/建议/证据"]
OUT --> DB[("SQLite decisions 审计")]
OUT --> TR["Unified Trace(10 阶段)"]
JUD -. "Planner 可选(默认关)" .-> PLAN["Planner"] --> ROUTER["ToolRouter:只生成请求,不执行"]
关键数据流:用户输入 → 上下文解析 → 感知/记忆/专家证据 → Debate/Critic → Judge → 决策落库 + Trace → CLI/API 输出。need_human_review 在低置信、专家冲突、Critic
升级、KG 硬约束冲突时置真;反馈/结果通过 API 回灌到 SQLite,供后续案例/经验召回。
依赖与实现位置均可在仓库中核对(requirements.txt、对应源码行号)。
| 层 | 选型 |
|---|---|
| 语言 / 运行时 | Python 3.13(开发环境 3.13.3);Windows 与 Linux 均可运行核心文本链路 |
| 工作流编排 | LangGraph StateGraph(workflow.py:37),异常时自动回退自研规则编排(orchestrator.py:172) |
| API | FastAPI + uvicorn + pydantic(gateway/app.py:25) |
| 模型接入 | OpenAI-compatible(openai SDK);Judge/Critic 可选,无 key 自动回退规则 |
| 检索 / 知识 | Qdrant 优先 + 内存回退;Neo4j 优先 + 内置 DISEASE_DB 回退 |
| 持久化 | SQLite(标准库 sqlite3,storage/db.py) |
| 终端 8000 UI | Rich(ui/tui.py) |
| Web UI | Vue 3 + Vite + TypeScript;Vitest + vue-tsc |
| 测试 | pytest(27 个测试文件、366 个收集项;见第 8 节实际结果) |
| 可选 Python 依赖 | transformers/torch(视觉可选路径)、scikit-learn(异常检测基线);不参与 Vue 构建 |
本项目重点不是堆叠 Agent 名称,而是下面几处可核对的工程决策:
- 工作流编排与规则回退:LangGraph 主图抛错或不可用时回退
run_rules(orchestrator.py:172-178),--rules-only可强制跳过;两条路径共享同一输出契约,回退对调用方透明。 - LLM 故障分类与留痕:
agents/judge_agent.py:73记录fallback_reason_code(连接失败 / 超时 / 非 JSON / 5xx 等),:142在缺失证据里标注回退原因,:146打印脱敏日志(不输出 key);回退后judge_mode=rules,不与真实模型结果混淆。 - 统一 10 阶段 Trace:
trace/types.py:36-47定义固定阶段序列(request → … → metrics),trace/exporter.py:37导出 JSON;CLI--trace-out一条命令产出。 - SQLite 决策审计:
storage/db.py:16的decisions表记录裁决、置信度、风险、judge_mode与 Trace;GET /decisions、GET /decisions/{id}可直接查询。 - 多入口同链路:CLI、TUI 与 FastAPI 复用同一个
AgentOrchestrator;Vue Web 只调用受保护的 FastAPI API,不复制诊断逻辑。 - 离线测试与固定评测:
tests/覆盖契约、回退、Trace 与 CLI 端到端;scripts/run_delivery_eval.py以 12 例固定夹具做零 API 回归。 - Windows 编码兼容:窄编码控制台(GBK)下
orchestrator.py的_print_safe降级输出,避免UnicodeEncodeError把诊断结果顶掉。
环境:Python 3.13(开发环境 3.13.3),Windows/Linux 均可;无 Neo4j/Qdrant/API key 也可运行核心文本链路。
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env # 可选;不填 key 时自动走规则
$env:PYTHONIOENCODING='utf-8'; $env:PYTHONPATH='.'
python orchestrator.py --rules-only --seed 7 "温室A番茄叶片出现黄斑,叶背有灰色霉层,如何处理?"--rules-only:跳过 LangGraph,直接规则编排;--seed固定模拟层随机部分;--trace-out logs/trace.json:导出 10 阶段 Trace;--json输出结构化结果;- TUI:
python -m ui.tui(9 个场景,含 3 个固定案例); - API:
uvicorn gateway.app:app --port 8000,先设置ACIS_API_KEY;GET /health为公开健康检查,其余 API 路由需要X-API-Key; - LLM Judge/Critic:设置
AGRI_AI_JUDGE_*(或DEEPSEEK_API_KEY等兼容变量), 无 key/网络失败自动回退规则,并在judge_runtime.fallback_reason_code记录原因。
要求 Node.js 22 LTS(Docker 构建固定 Node 22.22.2)。在两个终端分别启动 API 和前端:
# 终端一:本地 API。将示例值替换为本机专用、至少 32 个 ASCII 字符的随机 Key
$env:ACIS_API_KEY='replace-with-a-private-key-of-at-least-32-characters'
uvicorn gateway.app:app --host 127.0.0.1 --port 8000
# 终端二:安装并启动 Vue 开发服务器
npm ci --prefix web
npm --prefix web run dev打开 http://127.0.0.1:5173,在侧栏输入与 API 环境变量相同的 Key。Vite 将 /health、/diagnose、/images 和 /decisions 代理到本地 API;成功连接后密钥保存在当前标签页会话中,关闭标签页后清除。未配置模型时使用规则 Judge;固定案例会显示 DEMO / FIXTURE MODE,其报告仍由当前 API 实时生成。开发服务器与 API 分别按 Ctrl+C 停止。
先准备 Python 3.11+ 环境(推荐复用项目 .venv),并在前端源码更新后构建一次生产资源:
npm ci --prefix web
npm --prefix web run build之后双击仓库根目录 start_acis.bat,脚本检查 Python、依赖导入与 web/dist,为本次本地服务生成强随机 API Key,通过进程环境变量传给 FastAPI,并在健康检查成功后自动打开浏览器、完成 Web 连接。密钥不写入 .env 或日志;重复运行启动器时,恢复密钥以当前 Windows 用户 DPAPI 加密保存在 %LOCALAPPDATA% 的启动状态文件中。浏览器读取 URL 片段后立即清除地址栏,并将密钥限制在当前标签页会话。双击 stop_acis.bat 停止本启动器管理的进程并移除加密状态。启动器不创建或覆盖虚拟环境、不改 .env、不杀占用端口的进程;启停操作串行化,停止前校验 PID、可执行路径、启动时间、app-dir 与端口。日志位于 logs/acis-local-*.out.log 和 logs/acis-local-*.err.log。默认端口为 8000,可用 $env:ACIS_LOCAL_PORT='8010' 改端口;模型或外部知识服务仍按相应配置项提供凭据。日常启动不需要运行 Node/Vite。
使用 Node.js 22 LTS、项目 Python 环境和已安装的 Chromium:
npm ci --prefix web
npm --prefix web run build
npx --prefix web playwright install chromium
npm --prefix web run test:e2ePlaywright 会启动隔离的真实 FastAPI + Vue production build,执行 11 个 Chromium 场景;报告与截图写入新的 reports/web-e2e-<run-id>/,自定义 ACIS_E2E_ARTIFACT_DIR 时写入新建的 run-* 子目录。诊断案例运行真实 API 链路,但使用 rules Judge 与 memory RAG/KG;API 故障、空历史等场景使用显式浏览器网络拦截,不代表真实 LLM 或外部知识库效果。
Docker 生产模式会先构建 Vue 静态资源,再由 FastAPI 在同源根路径提供页面;不需要额外运行 Node 服务。
Copy-Item .env.example .env
# 在本机 .env 中设置唯一的 ACIS_API_KEY 和 NEO4J_PASSWORD
docker compose config -q
docker compose up --build -d
docker compose psAPI、Qdrant 和 Neo4j 默认仅绑定 127.0.0.1;健康检查 /health 可匿名访问,诊断及审计接口必须携带至少 32 个字符的 X-API-Key。SQLite 使用 ACIS_API_DATA_DIR(默认 ./data),Qdrant 与 Neo4j 使用命名卷;docker compose down 保留数据,勿在需要保留数据时运行 down -v。已验收镜像为 Python 3.11.14-slim-bookworm、Qdrant v1.18.2 和 Neo4j 2026.05.0-community。
旧版本曾在代码中公开 Neo4j 凭据,应按泄露处理:仍在使用的数据库必须先轮换其数据库密码,再更新本地 .env。NEO4J_AUTH 只初始化新卷的密码,不会轮换已有卷;部署到既有卷前,确认 NEO4J_PASSWORD 与数据库当前密码一致。升级前备份数据卷;不要提交 .env 或将本机端口改绑到公网;公网部署还需经受控 HTTPS 反向代理。
依赖锁 requirements-lock.txt 由 Windows + Python 3.13.3 + 当前 .venv 的
pip freeze 生成,包含平台相关包;它不是跨平台锁,其他平台请用 requirements.txt
重新解析。.env.example 是配置模板,不包含真实密钥。
以下为本机真实运行节选(--rules-only --seed 7,规则链路,未调用任何模型):
============================================================
农业 Agent v4 — Orchestrator / Debate / Judge
============================================================
【总结】Orchestrator 已完成 gh-a/tomato 的diagnose 工作流:病理判断首选:番茄叶霉病。风险等级:medium。
【裁决】病理判断首选:番茄叶霉病
【Judge】rules
【置信度】72%
【风险等级】medium
【人工复核】否
【Debate 共识】
- 病理诊断与记忆层(RAG/历史案例)结论一致,诊断可信度升高
【缺失证据】
- 缺少有效图像证据,视觉 Agent 未参与确认
【裁决推理】
KG参照疾病:番茄叶霉病、番茄早疫病;未触发KG硬约束否决;风险等级=medium,置信度=0.72
【行动建议】
1. 对异常传感器复测,并查看最近 24 小时趋势
2. 围绕最高匹配病害核对关键症状
3. 优先排查通风不足、叶面结露和下部老叶发病
4. 维持当前环境管理
5. 密切观察症状变化,记录发展过程
同一次运行还会输出 Trace 行、并在 SQLite 写入一条审计记录:
【Trace】<32 位 trace_id> | 10 stages | events=19
| decisions 行(节选字段) | 值 |
|---|---|
judge_mode |
rules(规则回退,不是 LLM 裁决) |
confidence |
0.72 |
need_human_review |
0 |
说明:
【Judge】rules表示本次走规则裁决。若启用--llm-judge且调用成功,同一字段为deepseek;两者不可混报。本仓未提供伪截图,全部示例均为终端真实输出。
| 项目 | 结果 | 说明 |
|---|---|---|
| 测试套件 | 30 个测试文件 / 397 个收集项 | 本轮 pytest -q 实测;含 2 个显式 skip |
| 全量 pytest(Windows + Python 3.13.3) | 395 passed / 2 skipped / 30 warnings,311.94s,exit 0 | 两个 skip 因仓库外 Phase 4 harness 缺失;warning 为 1 条 Starlette 弃用提示与 29 条 Qdrant 服务版本探测告警 |
| 交付诊断测试 | 38 passed / 8 warnings | tests/test_delivery_cases_v1.py + tests/test_delivery_contract.py;包含实际诊断输出与 Trace 断言 |
| Vue 前端 | 9 passed;Node.js 22.22.2 下 npm run build 通过 |
Vitest;build 同时运行 Vue 与 Playwright E2E TypeScript 检查及 Vite production build |
| Vue 浏览器 E2E | 11 passed / 0 failed / 0 skipped | Chromium + FastAPI + Vue production build;诊断使用 rules Judge / memory RAG-KG,受控故障由浏览器 route 注入;截图和 JSON 在 reports/web-e2e-20261119064633-515c7dd4-9781-413a-a028-2887c3e6c9d6/ |
| Web 依赖审计 | production 依赖 0 项;开发依赖 10 项(1 low / 6 moderate / 1 high / 2 critical) | npm audit --registry=https://registry.npmjs.org/;含 Vite/Vitest 测试工具链,尚未升级修复 |
| Rich TUI 固定案例 | 3/3 完成 | 菜单 7–9;实际报告均落入隔离 SQLite smoke DB |
| Compose 配置 | 通过:docker compose config --quiet |
仅以进程级非密钥占位值做静态解析;未启动、停止或修改容器与数据卷 |
| 当前 Docker 镜像构建 | 未验证 | Docker daemon 不可用;本轮未执行 docker build。2026-10-24 容器验收是 Vue 多阶段构建前的历史记录 |
| 历史 Docker Compose 验收(2026-10-24) | 三个容器 healthy;API 鉴权、玉米诊断、22 个 Trace 事件、SQLite 重启读取通过 | Linux Python 3.11.14、Qdrant v1.18.2、Neo4j 2026.05.0-community;不能证明当前 Vue 镜像可构建 |
| 外部知识服务状态 | Qdrant 0 collections;Neo4j 可连接但 0 nodes | 仅历史 Docker 验收;当前浏览器案例使用 memory 后端,真实外部语料检索未验证 |
| 离线固定夹具(历史评测) | 12/12 符合预期行为,2 例 Critic,平均置信度 0.655 | scripts/run_delivery_eval.py,seed 7;这是夹具回归命中,不是农业诊断准确率 |
| 真实 LLM 单次调用(历史连通性) | 34.56s、10,354 tokens | 不是当前浏览器联调,也不是质量评测;规则路径默认不需要 |
实验证据摘要(详见 reports/experiment_audit_20261024.md) |
- Phase 6 baseline(seed42,24 例 × C0/C1/C2,真实 Judge):72/72 次调用成功、0 回退; label accuracy:C0 20/24、C1 19/24、C2 24/24。单 seed、n=24,不能证明完整架构 优于裸基线,也不能据此宣称“关记忆更好”。
- 自一致性(C1):seed42 仅 13/24 可评(11 次连接失败回退),seed43 24/24; ECE 约 0.071–0.077、corr 0.538–0.778(基于 trace 中的 agreement), 只是 C1 两个 seed 的描述性结果,不是普遍校准结论。
- Phase 4.2-R:216 次真实链路调用中 191 次规则回退;服务仍可用,但该条件不能 用于评价模型效果。
- 历史报告中的
accuracy需注意口径:reports/archive/phase4/phase4_evaluation_pilot.md、 Phase 4.2-R/R3 稳定性报告中的 “accuracy” 在原始报告中指 factor coverage (因子覆盖度),不是诊断准确率;scripts/generate_stability_report.py:66-75有明确映射。引用前请先读实验审计。
- 传感器/天气为模拟;图片识别默认 mock,真实视觉模型未验证;
- 规则 Judge 是默认路径,LLM Judge/Critic 可选且真实质量未做多 seed 评测;
- Phase 6/Phase 4.2 实验为单 seed 或少量有效样本,不能外推为泛化能力;
- 工具执行与 MCP 服务未纳入本轮验证;本轮 Vue 浏览器 E2E 使用 rules Judge 与 memory RAG/KG,真实外部知识语料和 LLM 推理未验证;Compose 仅以非密钥占位环境变量通过静态解析,Docker daemon 不可用,镜像构建/运行未验证;2026-10-24 的容器验收不代表当前 Vue 镜像;
- 农业诊断准确率、Macro-F1、Top-3、人工因子覆盖、弃权质量、置信度校准、Recall@K、泛化 fallback rate 和本次 Token Cost 均未测量;固定夹具命中率不可替代这些指标;
- 全量测试本次结果为
pytest -q→ 395 passed, 2 skipped, 30 warnings(311.94s);两个 skip 因 Phase 4 评测 harness 不在本仓库中,由importorskip显式标记; - 没有真实田间数据、用户规模或生产运维经验。
| 文档 | 内容 |
|---|---|
| docs/DEMO_RUNBOOK.md | 3–5 分钟演示流程与故障注入 |
| docs/ARCHITECTURE_DECISIONS.md | ADR-005 等仍有效的技术决策 |
| docs/rfc/RFC001-System Architecture.md | 完整架构规格(实现子集见上文边界) |
| reports/experiment_audit_20261024.md | C0/C1/C2 实验与指标口径审计 |
| reports/acceptance_20261024.md | 端到端验收记录与限制 |
| reports/delivery_eval/summary.md | 12 例固定离线评测结果 |
| docs/archive/ | 历史 Sprint/RFC/状态文档(非当前事实源) |
见 LICENSE。