# 土壤评价

**Repository Path**: mzb329/soil-assessment

## Basic Information

- **Project Name**: 土壤评价
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 种植适应性评价领域 Agent 平台

基于《第三次全国土壤普查土壤农业利用适宜性评价技术规范》(2025-07-25) 的自建对话式领域 Agent 平台。

## 定位

以 LLM 对话为底座（ChatGPT 式 Web 聊天），挂载垂直领域 **system prompt + 工具(tools) + 技能(skills)**，泛化处理土壤农业利用适宜性评价任务。Agent 即产品：评价规则引擎、文档知识库、作物参考库全部是它可调用的工具；任何数值/等级/统计均由**确定性规则引擎**产出，LLM 永不参与计算。

## 三条工程原则

1. **不要回退** —— 零降级路径；缺失的硬依赖在安装期锁定，启动自检失败即拒绝服务。
2. **规则硬编码** —— 评价规则与规范条文逐条对应、纯确定性函数、可单测；每条规则带 `spec_ref` 条款号。
3. **错了就报错** —— 转录存疑/规则未核验/输入不合法 → 显式报错（`ErrRuleUnverified` / `ErrIndicatorInvalid`），不猜、不填默认值。

## 目录

- `docs/` 规范 PDF 原件
- `data/` 文档规范化产物：原始转录、校对全文、机器可读知识库（`knowledge/`）、人工核验阻断清单（`review/`）
- `engine/seval/` 纯规则评价引擎（零外部依赖，可离线）
- `.claude/skills/` 领域技能库（8 技能：单地块/批量评价、指标解释、成果导出、报告撰写、规范问答、作物建议、联网检索）
- `backend/` FastAPI + SQLite 后端（SSE 对话、上传、产物下载、知识配色接口）
- `frontend/` Vite + React 前端（ChatGPT 式聊天界面）
- `scripts/` 文档规范化流水线与校验

## 快速开始

```bash
make install        # Python 3.12 venv + 全量依赖（硬锁，GIS/文档依赖缺失即报错）
make demo           # 全流程验收：知识库校验 + 引擎/后端全部测试 + 前端构建
make run-backend    # uvicorn :8000（启动自检：依赖缺失拒绝服务）
make run-frontend   # vite dev :5173（frontend/，首次 npm install 自动走 .npmrc 镜像）
```

LLM 运行时（`backend/app/services/cc_runtime.py`，官方 Claude Agent SDK）：环境变量
`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_MODEL`。
**LLM 不可达 → 显式报错中断（不降级、不让 LLM 参与任何数值计算）。**

## 能力一览（P1–P5 已交付）

| 层 | 内容 |
|---|---|
| 文档规范 | 36 页扫描 PDF → 转录 → 人工核验；`data/knowledge/*.yaml` 知识库（2257 县 / 81 作物 / 附录 A–E）；阻断清单 `data/review/corrections.yaml` |
| 评价引擎 | `engine/seval/` 纯规则：14 指标 → 表1/2/3 → 特殊规则（重金属/现状地类）→ E.1 字段 + 统计；每条规则带 `spec_ref`；`Err*` 显式错误 |
| 底座服务 | FastAPI + SQLite：session/upload/artifacts/knowledge(colors)/chat；SSE 对话；产物 CSV/MD/图件PNG/overlay.geojson + 结构 JSON（Excel/Word 由官方 document-skills 排版渲染） |
| Agent | Claude Agent SDK 运行时（`backend/app/services/cc_runtime.py`）：PreToolUse 白名单 + 引擎 CLI 唯一放行；8 技能（`make run-backend` 下 SSE 事件翻译为中断/恢复补问）；LLM 仅意图/编排/解释 |
| 前端 | Vite+React ChatGPT 式：会话侧栏、对话流、CC 转录时间线（<code>AgentFlow</code>）、补问卡片、产物面板（Markdown/E.1表格/Leaflet+overlay/图件/下载）、配色与服务端 <code>/api/knowledge/colors</code> 同源 |

## 主要评价流程（引擎硬编码）

县域/评价单元 14 项指标（p坡度 h海拔 o坡向 e侵蚀量 l土体厚度 g砾石 r基岩 w水源 d排水 s盐碱 m质地 n有机质 a pH c重金属）
→ 附录D 分区分级表定级 → 表1 判断矩阵定限制级别（一~六级）→ 表2 定适宜类（宜耕/宜园/宜林/宜草/不适宜，优先序耕>园>林>草）
→ 表3 定适宜程度（Ⅰ/Ⅱ/Ⅲ）→ 特殊规则（重金属下调/现状地类调整）→ 表E.1 结果字段 + 统计 + 图件 + 报告。

> 标注：附录A 县名单与表1 部分单元格转录存疑，已列入 `data/review/corrections.yaml` 阻断清单，人工确认后放行。

## 测试与验收

```text
make validate-kb           知识库校验（ERROR gate）+ 黄金样例 5 个防漂移
pytest engine/tests         150 个：分级/表1全单元/表2、3组合/黄金样例/统计/分区严格匹配
pytest backend/tests         73 个：SSE 对话回放、CC 运行时白名单、上传解析、E.1/E.3 结构守卫、制图
make demo                   上面的全量验收 + 前端构建
```

浏览器演示：`make run-backend` + `make run-frontend` → http://localhost:5173
单会话聊天页真实 LLM 全流程（技能选择→工具链→流式回答/补问恢复）；Composer 支持上传附件（Excel/CSV/图片），产物面板内嵌 E.1 表格/E.2 图件/Leaflet overlay 并提供下载。

演示数据：`.venv/bin/python scripts/make_demo_batch.py` 生成 `data/instance/demo_batch.xlsx`
（6 单元覆盖宜耕Ⅰ/Ⅱ、宜园、宜林、宜草、不适宜 5 类 + 双乡镇，供统计/潜力/E.2.4 演示；运行期生成，不内置）。

## 成果产物（每评价批次）

- E.1 结果表：CSV（45 字段按附录 E.1）+ 结构 JSON（官方 document-skills:xlsx 排版渲染）
- E.3 技术报告：Markdown + 结构 JSON（官方 document-skills:docx 排版渲染 Word，含 E.3.1 表格与 E.1 附表）
- E.2 图件：土壤农业利用适宜性评价图 PNG（单元多边形按适宜类着色）+ overlay.geojson（供 Leaflet）；限制因素分级图（评价单元必须带几何，缺几何显式报错不出图）
- 统计：E.3.1 面积占比 / E.3.2 交叉表 / E.2.4 可耕地潜力（JSON，产物面板渲染）