智慧农业生态 · 全球分区农业 AI 助手
以数据平台分析为基座，孵化多层级农业 AI 关键节点生态
🎯 项目目标口径（单一权威） ：见 docs/CORE_OBJECTIVE.mdAgent-native 知识基座 。
一句话：把「在哪里种什么、怎么种得好」做成可被任何 AI Agent 直接调用 的可执行配置（Env Recipe），以可审计的数据血缘 作为可信度资产。
一级目标 ：让 MCP server 被外部 agent 真实调用（≥500 次 / ≥20 独立调用方）。
阶段门禁数字见 docs/north_star_and_phase_gates.mddocs/full_liftup_assessment_2026-10-08.md
🚀 已上架官方 MCP Registry ：io.github.lm203688/agri-eco v1.1.0（2026-10-08）
curl -s "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.lm203688/agri-eco"
🔎 市场入口（4 家全覆盖） ：
官方 MCP Registry：io.github.lm203688/agri-eco v1.1.0 ✅
Smithery：smithery.yaml 已就绪，仓库自动发现（搜索入口 ）✅
Glama：已提交（2026-10-11，POST /api/mcp/servers/submit.data 200），等 Glama 审批邮件补 Dockerfile 后索引（目录入口 ）🟡
LobeHub：lm203688-smart-agri-eco（2026-10-08 自动发现）✅
📋 分发就绪度自检 （每次评审/发布前跑一次）：
python scripts/check_distribution_readiness.py
一次性验证 10 类分发入口：MCP server / A2A Card / Agent Plugin / Smithery / 官方 Registry /
MCPB 包 / CI workflow / Demo 部署 / 市场材料 / GitHub 同步。
CI：28 步 × Python 3.10/3.11/3.12 全绿 · 单测 614 OK · Demo 端点 14/14 · MCPB 构建确定性可复现 · GitHub 本地=远端（393 文件差异 0）· Skill 注册表 11/11 一致 · AgriRecipeBench 5/5 通过 （M1 目标预测 3/3 + M2 状态滚动 2/2）。
🏆 AgriRecipeBench （benchmarks/agri_recipe_bench/可复现评测基准 ，独立于功能回归测试：
python benchmarks/agri_recipe_bench/run_bench.py
python benchmarks/agri_recipe_bench/run_bench.py --axis target_prediction --strict
python benchmarks/agri_recipe_bench/run_bench.py --case case_luobo_mediterranean --json
🔐 可验证 AI 三件套 （2026-10-11 新增，对标 SNWM 可验证协议与 MCP 2026-08 路线图）：
能力 响应字段 用途 T-3 置信区间 recommendation.prediction_interval.{p10,p50,p90}产量 / 采收期 / 周期从单点估计变区间；输入越少区间越宽；confidence.uncertainty 显式声明散布系数与惩罚项 T-1 可信标记 _trust_mark.{cert_id, signature, verification_cmd}所有 MCP 工具输出内嵌 SHA256 证书指纹；外部消费者可 python -m core.trust_layer 独立复算 D-4 A2A Card 签名 .well-known/agent.json.jwsJWS (HS256) compact serialization，零依赖；AGRI_A2A_SIGNING_KEY 环境变量提供密钥；调用方可用 scripts/verify_agent_card.py 检测篡改
AGRI_A2A_SIGNING_KEY="your-secret" python scripts/sign_agent_card.py
AGRI_A2A_SIGNING_KEY="your-secret" python scripts/verify_agent_card.py
🌱 受控自进化系统（Bounded Self-Evolution） （2026-10-13 新增，对标 SNWM 可验证协议 + Theseus Labs RSI 五级框架 + PenguinHarness 棘轮门禁）：
能力 实现 用途 S1 不可进化区/可进化区 .well-known/evolution_zones.json8 项不可进化（可信层/协议契约/schema）+ 7 项可进化（气候/预测/物候/营养/技能）；防止自进化侵蚀诚实性 A1 Köppen 栅格抽象（F5） core/climate_grid.py标准库栅格点查询：最近邻 + 3×3 邻居 + 1/d² 权重归一化 → 概率分布 （不是单点分类）；climate_agent 双后端接入（栅格优先，无栅格显式降级为启发式，evidence.classification_backend 显式标注） S2/E1 棘轮 CI 硬门禁 scripts/run_evolution_ratchet.py内回路飞轮：读 .well-known/evolution_zones.json 的棘轮白名单，跑 evolution benchmark 判分数；不依赖任何外部调用，现在就能转
python scripts/run_evolution_ratchet.py
python scripts/run_evolution_ratchet.py --min-score 0.9
python scripts/run_evolution_ratchet.py --check-files
python scripts/run_evolution_ratchet.py --json
python -c "from core.climate_grid import build_synthetic_grid_dict, KoppenGrid; \
g = KoppenGrid(cells=build_synthetic_grid_dict()['cells'], ...); \
print(g.query(40.0, 116.0))"
关键设计原则 ：自进化必须先有"不可进化区"，再有"可进化区"——否则"自我改进"会侵蚀项目唯一真实的资产（诚实性与可复现性）。内回路（离线棘轮）是唯一不依赖任何外部条件、现在就能转起来的飞轮 ，同时服务三个目的：①保证科学改进不退步；②产出对外可引用的评测资产；③喂养 RSI 度量。
🔍 编排层可审计性（Orchestration Audit） （2026-10-14 新增，agent/orchestration_audit.py，29 项单测守卫）：
把「诚实暴露不确定性」的元层能力从单点输出 （M11 可信层）扩展到多 Agent 协作层 （M10 编排层）。落地 per_module_deep_assessment_2026-10-13.md §M10-O2「跨 Agent 一致性检查」+ §M10-O4「编排 trace 可导出」：
能力 实现 用途 M10-O2 跨 Agent 一致性检查 check_cross_agent_consistency()，5 条规则检查 Climate/Crop/Growth/Eco 四个 Agent 之间的结论是否自洽（预算超支、季节冲突、设备无匹配等），冲突显式标注严重度 （error/warning/info）而非静默消解 M10-O4 编排 trace 可导出 TraceRecord + export_trace_dict/json()每次 pipeline 生成完整调用图（agent/耗时/输入摘要/输出摘要/verify_report）+ SHA256 summary_hash（同输入稳定，可独立复算）
python -c "
from agent.orchestrator import AgriOrchestrator
r = AgriOrchestrator().run_pipeline(
{'lat':30.0,'lon':120.0,'scene':'balcony','budget_cny':300},
verify=True, record_memory=False)
print(r['consistency_audit'])
print(r['orchestration_trace']['trace_id'], r['orchestration_trace']['summary_hash'])"
python -c "
from agent.orchestration_audit import check_cross_agent_consistency
# 传入 pipeline result 会得到冲突列表与严重度分级"
关键设计原则 ：advisory only ——审计不阻断流水线、不写回任何 Agent 输出（与 JEV 门控纪律同构）；冲突显式暴露给用户，让用户判断严重程度，而不是让系统自作主张「消解」矛盾。这是本项目对多 Agent 编排层 的诚实性承诺，与单点输出的 T-1/T-3 证书形成同构。
🛡️ AgriTrust Verified 公共复算 API （2026-10-14 新增，scripts/verify_trust_mark.py + MCP 工具 agri_verify_trust，34 项单测守卫）：
把 T-1 可信标记从内部纪律 升级为对外公共复算资产 。落地 per_module_deep_assessment_2026-10-13.md §M11-T1「可信标记产品化」——外部消费者可独立验证任何 AgriTrust 输出，无需依赖私有代码。
能力 实现 用途 公共复算 CLI python scripts/verify_trust_mark.py <mode>4 种验证模式：current（导出）/ check-prefix（结构完整性）/ from-mark（端到端）/ from-certificate（内容一致性 + 可选 --verify-artifacts 磁盘哈希） MCP 工具 agri_verify_trust（第 19 个工具）让 MCP 客户端不必跑核心引擎也能独立验证 trust_mark AgriTrust Verified 徽章 artifacts/agritrust_badge.svg + docs/agritrust_verified.md徽章含 signature_prefix + verification_cmd，外部消费者一步到位复算
python scripts/verify_trust_mark.py current > mark.json
python scripts/verify_trust_mark.py from-mark mark.json
python scripts/verify_trust_mark.py current --certificate > cert.json
python scripts/verify_trust_mark.py from-certificate cert.json --verify-artifacts
诚实边界 ：signature 是内容一致性 SHA256，非密码学签名（无密钥） ——它证明"数据未被修改"，不 证明"我们就是签发者"。这一边界写进 schema 与 verify API 输出，不静默通过，任何降级/缺失都返回 verified=False + 具体原因。这是本项目"可验证 AI"三件套（T-1/T-3/D-4）在对外接口 上的延伸。
项目定位
一句话 ：做分布式农业的 AI 操作系统与数据网络——回答「在哪里种什么、怎么种得好、怎么送到消费者」。
核心架构（对标 SwarmLabs 科研 Agent Infra 的工程路径） ：
输入（地块信息 / 种植者需求 / 环境参数）
│
▼
┌──────────────────────────────────────────────────────────┐
│ L0 数据底座层 全球分区气候/土壤/水文元数据 │
│ └─ data/zone_meta/ (Köppen 气候带 + FAO 农业分区) │
├──────────────────────────────────────────────────────────┤
│ L1 多 Agent 协同层（含 L2/L3 专项 Agent） │
│ ├─ ClimateAgent 气候/水文/土壤分区匹配 │
│ ├─ CropAgent 作物-分区适配推荐 │
│ ├─ GrowthAgent 生长周期管理 + 病虫害诊断 │
│ ├─ EcoAgent 多层级生态撮合（供需/社区/设备） │
│ ├─ PestAgent / NutritionAgent / SeasonAgent 按需调用 │
│ ├─ ForecastAgent(L2) 采收期 / 产量 / 风险预测 │
│ └─ ControlAgent(L3) 生长计划→执行指令 + 执行补偿 │
├──────────────────────────────────────────────────────────┤
│ L2 Skill 注册表 可复用能力模块 │
│ └─ skills/registry/ (climate_match / crop_adapt / ...) │
├──────────────────────────────────────────────────────────┤
│ L3 可信输出层 evidence + confidence + constraints │
│ └─ docs/agent_output_contract.md │
└──────────────────────────────────────────────────────────┘
覆盖边界（已闭环） ：分区库现建模 8 个气候带 （含 v1.1 新增的热漠 hot_arid 与高原 highland ）。
迪拜（波斯湾热漠）→ hot_arid、拉萨（青藏高原）→ highland 现由 ClimateAgent 正确路由（rubric 0.95、给出真实作物推荐），
不再静默归入「亚热带湿润」给出错误方案；v1.1 之前的「显式拒答」降级路径已随分区补齐而关闭。
两新分区的 Env Recipe 与 P3 校准作物已于 2026-10-06 回填，详见 outputs/zone_coverage_decision_2026-09-23.md（历史背景）。
两个诚实性约定（2026-09-23 起生效，均有测试锁死） ：
monthly_precip_mm 虽是月度序列，但每个元素是月内日均降水（mm/day），不是月累计量 。
NASA POWER 与 Open-Meteo 两条路径口径一致，agent/climate_data.py 统一以 PRECIP_UNITS 声明并透传
monthly_precip_mm_units。生态位校准的降水通道依赖「同口径区间命中」，不得 对该字段乘天数换算。预设城市清单的唯一数据源 是 data/preset_cities.json，前端与 MCP Server 均经
agent/preset_cities.py 读取；拉萨/迪拜随 v1.1 已建模（modeled: true），12 城全部有对应分区。
七层生态架构（来自项目战略指引）
⚠️ 口径已修订（2026-10-08） ：七层是分析框架 ，不是交付清单。当前阶段只交付 L0-L3 ；L4/L5/L6 已正式暂缓 （判定依据与重新打开条件见 docs/CORE_OBJECTIVE.md实测 校正，此前"已落地/进行中"的表述存在与代码不符之处，此处一并修正。
层级 名称 关键节点 本项目状态（实测校正） L6 运营生态 社区/城市合伙人/数据市场 ⏸ 正式暂缓 （无实现） L5 消费服务 采摘即食/本地撮合/认证溯源 ⏸ 正式暂缓 （仅溯源字段留位，无服务实现） L4 业务支撑 链路数据/鲜度中枢/损耗预测 ⏸ 正式暂缓 （仅 data/linkage_protocol.schema.json 一个 Schema，0 行实现 ；此前标注"已落地"有误） L3 执行控制 水肥一体化/环境调控/执行补偿 ✅ 已落地（NutritionAgent 水肥 + ControlAgent L3：生长计划→硬件无关 actuator 指令 + 车载/开放环境/设备故障执行补偿）。缺口 ：execution_log 0 条，闭环未真实验证；needs_gateway 网关未实现 L2 模型 AI 生长模型/病虫害/决策引擎/世界模型 🟡 部分落地（ForecastAgent L2：采收期/产量/风险预测，诚实标注 model=heuristic + WOFOST 物候 + 病虫害规则诊断）。缺口 ：世界模型未做；eval_pest_diagnosis_topk / eval_recipe_expert_adoption 两项核心 eval pending L1 感知层 传感器/摄像头/边缘AI 🟡 最弱环节（agent/vision.py 63 行 可插拔后端，未配置即规则降级）。注意 ：PlantVillage 无 license （原仓库无 LICENSE 文件），不可商用；合规替代为 PlantDoc (CC BY 4.0)。传感接入协议 0 行代码 L0 数据底座 气候/土壤/水文/光照 ★ 当前重点（8 分区已闭环 / 152 配方 / 113 双源校准 / 8 源血缘）。缺口 ：微气候选址未做；CMIP7 未接入；第三源未融合
核心模块
模块 路径 用途 多 Agent 协同框架 agent/气候/作物/生长/生态四 Agent + 病虫害(PestAgent) + 养分(NutritionAgent) 按需调用 统一编排器 agent/orchestrator.py四 Agent 流水线（run_pipeline）+ call_skill 按需技能路由 + 技能目录（list_skills） 农业分区数据 data/zone_meta/全球农业分区元数据 Skill 注册表 skills/registry/可复用农业 AI 能力 可信输出契约 docs/agent_output_contract.md每条建议的证据/置信度/适用条件 项目评估 docs/project_evaluation.md评审维度逐项自评 战略指引 docs/planning/项目战略指引.md七层架构与商业设计 执行方案 docs/planning/项目执行方案.md分阶段路线图 规划/战略/GOAI 合集 docs/planning/10 份早期规划、战略与 GOAI 竞品分析（已归档归类，便于溯源） 开源生态对接 docs/OPEN_SOURCE_INTEGRATION.md七层架构生态位补全映射（扫描→对接）+ 用户分步操作指引（启用 cropgraph MCP / 配置视觉后端 / 提供 PAT 推送） 反馈闭环引擎 engine/flywheel.py种植结果回流 → 适配评分校准（主动学习） 交互式 Demo app/零依赖 http.server 站点：坐标 → 四 Agent 方案 + AgriTrust 证书 数据扩展脚本 scripts/enrich_crop_data.py每气候带补充适生作物至 ≥18 种 端到端验证 scripts/verify_all.py多城市 pipeline + Trust 证书 PASS/FAIL Skill 自动生成 engine/skill_factory.py新作物/能力点 → 自动生成符合 Schema 的 Skill 单元测试 scripts/test_*.py 系列700+ 项 unittest（零依赖），覆盖四 Agent + PestAgent + NutritionAgent + SeasonAgent + SoilProfile + ForecastAgent(L2) + ControlAgent(L3) + Orchestrator 统一路由 + 视觉后端降级 + Trust + flywheel + Env Recipe 契约 + 数据完整性守卫 + MCP 19 工具 + A2A Card + Skills Registry 11 项一致 + 编排层可审计性 29 项 + 可信标记公共复算 API 34 项MCP server（Agent-native 分发） mcp/零依赖 JSON-RPC over stdio，暴露 19 个 agri 工具（分区匹配/作物推荐/种植计划/病虫害诊断/养分管理/Env Recipe 配方/物候播期/土壤剖面/BP 投资初筛/多源气候调和/地理编码→配方/数据血缘查询/预设城市/生态对接清单 + 知识检索 agri_search + 知识图谱 agri_knowledge_query （M12-K1 接入）+ 可信标记公共复算 agri_verify_trust （M11-T1 产品化））；协议版本 2026-07-28（无状态） ，兼容 2025-06-18 / 2024-11-05；已适配 SEP-2575（免握手）/ SEP-2567（无 session）/ SEP-2243（Mcp-Method）/ SEP-2549（ttlMs 缓存）/ SEP-414（W3C traceparent）；注册与投递见 mcp/README.md A2A Agent Card .well-known/agent.jsonA2A v1.0 标准发现入口：声明 14 个 skill（与 MCP 工具一一对应）、securitySchemes={}、输入输出模式与许可红线（NC 来源不得转售）；校验 scripts/check_agent_card.py Agent Plugins 打包 plugin/Agent Plugins 1.0.0 标准：plugin.json + mcp.json + skills/<id>/SKILL.md × 11（含 Anthropic Agent Skills YAML frontmatter）；由注册表生成，禁止手改 ，scripts/build_agent_plugin.py 为唯一入口，CI 用 --check 防漂移 Env Recipe 协议 schemas/env_recipe.schema.json + docs/env_recipe_protocol_v1.md配置协议 v1：作物×阶段×箱体 → 可执行环境参数；day-1 留位 execution_log/outcome/image_consent 独占数据字段；校验 scripts/validate_env_recipe.py AI 评测基线 engine/eval.py + scripts/run_eval.pyP0-H：分区分类一致率（真实基线）+ 4 个脚手架项（绝不谎报）；评测集 data/eval/zone_checks.json 预览残留清理 scripts/clean_preview_artifacts.py清除预览工具注入 HTML 的 data-page-node-id 属性（曾一次性注入 115 处） 演示数据重置 scripts/clean_demo_data.py清空 demo/单测污染的 feedback_log + 剥离作物库假校准标记 Demo 端点冒烟 scripts/check_demo_endpoints.py零依赖端到端自检：自动选空闲端口拉起 app/demo_server.py，打 14 个端点 （8 GET + 6 POST），校验状态码 / 体积下限 / 响应契约键，部署前先在本机消除哑端点风险；已入 CI 同步状态检查 scripts/sync_check.py本地工作区 vs GitHub main 逐文件 blob sha 比对（本仓非 git clone，无法用 git status） 反馈回流 CLI scripts/submit_feedback.py内测用户提交种植结果 → 校准 adapt_score 物候/播期层 agent/phenology.py + agent/plant_calendar.py + agent/season_agent.pyWOFOST 积温物候（7 作物，EUPL 1.2 署名）+ 霜冻锚定播期窗口；技能 season_advisory L3 执行控制 Agent agent/control_agent.py生长计划 → 硬件无关 actuator intents（灌溉/施肥/补光/气候/CO₂/风机）+ needs_gateway 网关标记 + 车载颠簸/开放环境/设备故障执行补偿；技能 control_commands L2 预测 Agent agent/forecast_agent.py采收期（GDD-lite 积温）/ 产量（基准×气候×适配×光照）/ 风险（霜冻/高温/计划）预测，诚实标注 model=heuristic、未知作物安全回退；技能 harvest_forecast L4 链路数据协议 data/linkage_protocol.schema.json开源标准链路数据（batch→product→7 环节三元组 + 鲜度/损耗/货架期模型），支撑 L5 认证溯源 土壤剖面（降级源） agent/soil_profile.py在线 SoilGrids 优先 → 离线分区均值降级；resolution=zone / confidence=low，不虚构指标 文档死链扫描 scripts/check_doc_links.py全量 md 外链四态判定（ALIVE / DEAD_CONFIRMED / UNREACHABLE / UNPROBEABLE） 回流通路自检 scripts/check_feedback_loop.py用 AGRI_FEEDBACK_LOG 隔离，13 项验证 record → calibrate → report 全链路，零污染真实数据 巡检报告 diff scripts/diff_daily_loop.py报告跨日 diff（--selftest 守护解析器） 生产部署 deploy/一键部署（deploy_local.sh 上传 + setup_ecs.sh 远端构建启动）+ nginx 反代 + DEPLOY.md CI .github/workflows/ci.ymlpush 自动跑单测/verify/trust/flywheel/数据自检，Python 3.10-3.12 矩阵
工程路径（对标 SwarmLabs）
SwarmLabs 做法 农业项目映射 traceability.py（可追溯层）每条种植建议的溯源链（数据来源+分区依据+作物研究） trust_layer.py（可复现证书）农业建议的可信度评分（rubric + 数据覆盖度） skills/registry/（机读注册表）农业 Skill 的 JSON Schema 注册表 docs/agent_output_contract.md农业可信输出契约 engine/flywheel.py（飞轮主循环）✅ 已落地：record_feedback() 校准 adapt_score，闭环生效
快速验证
工程化入口见 docs/DEVELOPMENT.mdmake（如 make gate = 单测+端到端+数据质量三件套）。
python -c "import json; d=json.load(open('data/zone_meta/global_zones.json')); print(len(d))"
for f in skills/registry/*.json; do python -c "import json; s=json.load(open('$f ')); print(s['id'])" ; done
v2.1 提升项落地（Agent-native 分发 + 配置协议 + 评测）
依据 docs/planning/项目方案评审-商业模式与AI专业分析.md：商业主线重排为「免费资产 → 免费入口换数据 → 产业端收钱」；
模块⑤生成箱降级为「配方大脑授权硬件厂/存量设备」；Env Recipe 协议与 MCP 分发为近期最高优先。
提升项 交付物 验证 P0-G Env Recipe v1 协议 schemas/env_recipe.schema.json（schema v1.1.0）+ docs/env_recipe_protocol_v1.md + data/examples/sample_env_recipe.jsonpython scripts/validate_env_recipe.py data/env_recipesP0-E/F 零依赖 MCP server mcp/server.py（19 工具）+ mcp/README.md（含外部投递模板，对标 aishield 上架 Glama/npm）python scripts/test_mcp_server.pyP0-H 评测基线 engine/eval.py + scripts/run_eval.py + data/eval/zone_checks.jsonpython scripts/run_eval.py
决策门 （评审 §3.5）：P0-F/G 若 3 个月内零外部调用 / 零社区响应 → 降级为个人知识库项目，停止对外投入。
v2.2 提升项落地（分发协议适配，2026-10-08）
依据 docs/full_liftup_assessment_2026-10-08.md §8 P0 路线图；判定铁律——凡是能产生第一次真实外部调用的动作，优先级高于一切新增功能 。
权威目标口径见 docs/CORE_OBJECTIVE.md（本项目唯一战略来源）。
提升项 交付物 验证 P0-1 MCP 2026-07-28 无状态适配 mcp/server.py：免 initialize 握手（SEP-2575）、显式 stateless（SEP-2567）、Mcp-Method/Mcp-Name 头校验（SEP-2243，HTTP 形态生效）、ttlMs/cacheScope 缓存提示（SEP-2549）、W3C traceparent 透传与回写（SEP-414）python scripts/test_mcp_server.pyP0-2 A2A Agent Card .well-known/agent.json（A2A v1.0）：14 skill 声明 + 输入输出模式 + 许可红线python scripts/check_agent_card.pyP0-3 Agent Plugins 打包 plugin/plugin.json + plugin/mcp.json + plugin/skills/*/SKILL.md × 11python scripts/build_agent_plugin.py --checkP0-7 消除硬编码密钥 agent/finance_agent.py / market_agent.py 的 secret_key 占位随模块一并移出主链路grep -rn "secret_key" --include=*.py . = 0 命中
P0 出口指标：出现第 1 次非本人外部调用。
数据卫生（重要）
engine/flywheel.py 的 record_feedback() 真的会写盘 ——这是为了让反馈闭环真实生效。
代价是：demo 与单测如果不隔离，就会把合成样本混进真实数据。本项目已踩过的两类事故及防护：
事故 现象 防护 单测污染反馈日志 data/feedback_log.json 累积 12 条 unittest/smoke 样本，制造「已有真实数据回流」的假象单测把 AGRI_FEEDBACK_LOG 重定向到临时文件 作物库假校准标记 34 个作物只有 calibrated: true 却零校准证据 ，被可信层当成实测数据透出 scripts/clean_demo_data.py 清洗 + CI/单测双门禁
规则：
data/feedback_log.json 只允许真实用户反馈[demo] 前缀，门禁会拦截未标注的合成数据。python -m engine.flywheel 跑过之后python scripts/clean_demo_data.py --dry-run
python scripts/clean_demo_data.py
隔离运行 （不碰仓库数据）：
AGRI_CROP_DB=<绝对路径>/crop.json AGRI_FEEDBACK_LOG=<绝对路径>/fb.json python -m engine.flywheel
/tmp 映射到 %LOCALAPPDATA%\Temp，Python 按 C:\tmp 解析，
必须用 Windows 风格绝对路径 ，否则 AGRI_CROP_DB 找不到文件会直接报错（故意 fail fast，避免静默输出全 None）。CI 中的 flywheel 步骤已改为写入 $RUNNER_TEMP 隔离目录，并加了数据完整性门禁。
快速启动
1. 交互式 Demo 站点（零依赖，仅标准库）
python app/demo_server.py
2. 端到端验证
python scripts/verify_all.py
python -m engine.flywheel
python scripts/enrich_crop_data.py
3. Docker 部署
docker compose up --build
docker compose -f deploy/docker-compose.prod.yml up -d --build
3b. 公网部署（一条命令）
cp deploy/deploy_config.example.sh deploy/deploy_config.sh
bash deploy/deploy_local.sh
3b-2. 视觉诊断后端（可选，接 ATEX 多模态网关）
PestAgent 的视觉诊断走可插拔后端：配置以下环境变量（读 agent/vision.py）即启用，未配置则规则降级。
密钥放仓库外的 .env（已被 .gitignore 忽略，部署时由 deploy_local.sh 同步到 ECS，不进 GitHub）：
AGRI_VISION_URL=http://host.docker.internal:8420/v1
AGRI_VISION_KEY=<你的 ATEX 网关 Key>
AGRI_VISION_MODEL=gpt-4o
deploy/docker-compose.prod.yml 已默认读取这三个变量；若 ATEX 仅监听 127.0.0.1，可把 AGRI_VISION_URL 改为宿主内网 IP。
3c. CI（push 自动验证）
push 到 main 后自动跑：单测 → verify_all → trust_layer → flywheel（隔离到 $RUNNER_TEMP）→ 数据完整性门禁 （禁假校准标记、禁合成反馈样本）→ Skill 注册表合法性 → 数据自检（每带 ≥18 种作物），Python 3.10/3.11/3.12 矩阵。
状态：GitHub Actions 已验证可用（fine-grained PAT 含 Workflows:write，push 后 CI 自动跑通，最近一次 run 结论 success）。
3d. 本地 → GitHub 同步（无 git push 环境）
本机 github.com:443 不可达，且本地目录不是 git clone，不能用 git push / git status 。
统一走这两个脚本：
python scripts/sync_check.py
python scripts/gh_push.py <token临时文件> "<提交信息>" file1 file2 ...
需要 fine-grained PAT（Contents: read/write），建议含 Workflows:write 以便改 CI
token 放临时文件、用完即删，不要留在命令行历史里
推送后 CI 会自动跑；确认 success 再关掉本地改动
4. 单元测试（零依赖）
python -m unittest discover -s scripts -p "test_*.py" -v
4b. MCP / 协议 / 评测（v2.1 提升项）
python scripts/test_mcp_server.py
python scripts/validate_env_recipe.py data/examples/sample_env_recipe.json
python scripts/run_eval.py
注册到 Claude Desktop（stdio）：见 mcp/README.md。Env Recipe 协议说明与 AeroGarden 孤儿设备接入路径：见 docs/env_recipe_protocol_v1.md。
5. Skill 自动生成（闭环触发）
python -m engine.skill_factory
python -m engine.skill_factory --list
6. 提交种植反馈（内测回流 → flywheel 校准）
python scripts/submit_feedback.py --zone subtropical_wet --crop 生菜 \
--survival 0.92 --yield 4.5 --rating 5 --issues "梅雨季霜霉病" --note "杭州阳台春播"
自动化定时闭环（每日单口巡检）
本仓的每日治理巡检由专属 Automation 承担：「智慧农业生态 每日治理校验」 （id c8668b59-2488-4e21-9962-ab3fa7d69d26，每日 05:00，ACTIVE）。
注：列表里另有一个同名风格、名为「AOCI 每日治理校验」（1db296e6）的自动化，实际是 aoci-code 工具对 swarmlabs / 算力共享平台 两个其他仓库 的校验（每日 03:00），并非本仓任务——其命名易混淆但职责不属本项目，此处仅说明、不做改动。
闭环 频率 产出文件 作用 智慧农业生态 每日治理校验 每日 05:00 outputs/daily_loop_<YYYY-MM-DD>.mdverify_all + data_quality_gate + 全量单测三件套，非零退出即暴露漂移，只读巡检
执行内容（全部只读，禁改代码 / 禁 git / 禁推送）：
回归十八项（556 项单测 + MCP 自测） ：test_engine_v4.py（137 项）、test_engine_v3.py（43 项）、test_engine_v2.py（59 项）、test_agents.py（66 项）、test_engine_v5.py（94 项，BP 初筛引擎）、test_climate_data.py（19 项）、test_climate_reconcile.py（14 项）、test_data_lineage.py（25 项）、test_geo_recipe.py（7 项）、test_audit_analyzer.py（16 项）、test_jev_gate.py（15 项）、test_jev_decision.py（10 项）、test_jev_attribution.py（8 项）、test_mcp_server.py（14 工具）、test_dist_readiness.py（5 项）、test_env_derived_v12.py（8 项）、test_source_provenance.py（5 项）、test_mcp_server_unit.py（3 项）、test_mcp_namespace.py（4 项）、verify_all.py（5 城 PLACEHOLDER=0）、diff_daily_loop.py --selftest数据源存活探测 ：GAEZ / WorldClim / SoilGrids(rest.isric.org) / PlantVillage / EPPO / GitHub 等 7 个外部源 —— 防止引用死数据源（Ecocrop / OpenFarm / @pondlog 三次教训）回流通路健康检查 ：跑 check_feedback_loop.py，区分「通路故障（≠0 报警）」与「数据量缺口（=0 条、不报警）」 （JSON 字段 snapshot.feedback_path = ok/broken）状态快照 + 跨日 diff ：feedback 条数 / recipes 数 / wofost 作物数；与昨日报告对比，零漂移即静默，漂移即暴露
已知长期缺口 ：data/feedback_log.json 持续 0 条 = 通路可用但无真实用户回流数据（属产品/增长问题，非代码缺陷——不得以合成数据充数）。
开源协议
待确定。核心数据标准与协议倾向开源（抢生态话语权），应用层与决策引擎闭源（保利润）。