智慧农业生态 Agri-Eco

智慧农业生态 · 全球分区农业 AI 助手

以数据平台分析为基座，孵化多层级农业 AI 关键节点生态

🎯 项目目标口径（单一权威）：见 docs/CORE_OBJECTIVE.md —— 分布式农业的 Agent-native 知识基座。 一句话：把「在哪里种什么、怎么种得好」做成可被任何 AI Agent 直接调用的可执行配置（Env Recipe），以可审计的数据血缘作为可信度资产。 一级目标：让 MCP server 被外部 agent 真实调用（≥500 次 / ≥20 独立调用方）。 阶段门禁数字见 docs/north_star_and_phase_gates.md；全面扫描与提升报告见 docs/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：41 步 × Python 3.10/3.11/3.12 全绿 · 单测 956 OK · Demo 端点 14/14 · MCPB 构建确定性可复现 · GitHub 本地=远端（差异 0）· Skill 注册表 11/11 一致 · AgriRecipeBench 69/69 通过（四轴齐全：M1 目标预测 25 + M2 状态滚动 21 + M3 反事实响应 17 + M4 跨情境泛化 6，覆盖 8 分区 × 主要作物 × 边界条件）。

🏆 AgriRecipeBench（benchmarks/agri_recipe_bench/）——Env Recipe 环境配方的可复现评测基准，独立于功能回归测试。M15-B1 把用例从 11 扩到 69（四轴全部达标、覆盖 8 分区、含负例与退化检测）：

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
python scripts/expand_bench_cases.py                            # 幂等生成器（重新生成新用例）

• M1 target_prediction（25 用例）：预测值 vs 公开农艺基准，覆盖 8 分区 × 主要作物
• M2 state_rolling（21 用例）：数学边界（周期≥1 / harvest≥start / yield>0），含 adapt_score=0 / 冬季播种 / 超短周期 / 无 recipe 等 5 类边界场景
• M3 counterfactual（17 用例）：6 种扰动类型（adapt_score / growth_cycle / env_recipe_temperature / env_recipe_light / zone_climate / 组合扰动）——反事实机制内核直接证据
• M4 generalization（6 用例）：5 作物跨分区泛化，含退化实现检测（不同分区产量完全相同即失败）
• 挂钩：SNWM 神农世界模型四轴协议完整版，详见 benchmarks/agri_recipe_bench/docs/PROTOCOL.md

---

🔐 可验证 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.jws	JWS (HS256) compact serialization，零依赖；AGRI_A2A_SIGNING_KEY 环境变量提供密钥；调用方可用 scripts/verify_agent_card.py 检测篡改

# 生成 A2A Card JWS 签名
AGRI_A2A_SIGNING_KEY="your-secret" python scripts/sign_agent_card.py
# 校验（调用方 / CI 都用这条）
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.json	8 项不可进化（可信层/协议契约/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 判分数；不依赖任何外部调用，现在就能转

# 棘轮门禁（CI 硬门禁 / 本地手动跑）
python scripts/run_evolution_ratchet.py                  # 阈值 0.5，默认通过
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           # 供 CI 消费

# Köppen 栅格点查询（抽象层，不依赖真实数据）
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（同输入稳定，可独立复算）

# 完整 pipeline 会自动带 consistency_audit + orchestration_trace
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_decision_path_report（第 25 个工具，v2026-10-16 新增）	M16-B2 决策路径可视化报告：将 bp_screen 评分引擎的 decision_path 归因数据导出为结构化报告，供前端可视化或报告系统消费
AgriTrust Verified 徽章	artifacts/agritrust_badge.svg + docs/agritrust_verified.md	徽章含 signature_prefix + verification_cmd，外部消费者一步到位复算

# 1. 导出当前信任标记供外部下载
python scripts/verify_trust_mark.py current > mark.json

# 2. 用外部 mark 端到端复算（用 issued_at 严格重现 signature）
python scripts/verify_trust_mark.py from-mark mark.json

# 3. 最强验证：不仅证书对象一致，其引用的数据文件也未被修改
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 起生效，均有测试锁死）：

1. monthly_precip_mm 虽是月度序列，但每个元素是月内日均降水（mm/day），不是月累计量。 NASA POWER 与 Open-Meteo 两条路径口径一致，agent/climate_data.py 统一以 PRECIP_UNITS 声明并透传 monthly_precip_mm_units。生态位校准的降水通道依赖「同口径区间命中」，不得对该字段乘天数换算。
2. 预设城市清单的唯一数据源是 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 §三 N6/N7、§六）。 下表"本项目状态"列已按实测校正，此前"已落地/进行中"的表述存在与代码不符之处，此处一并修正。

层级	名称	关键节点	本项目状态（实测校正）
L6	运营生态	社区/城市合伙人/数据市场	⏸ 正式暂缓（无实现）
L5	消费服务	采摘即食/本地撮合/认证溯源	⏸ 正式暂缓（仅溯源字段留位，无服务实现）
L4	业务支撑	链路数据/鲜度中枢/损耗预测	⏸ 正式暂缓（仅 schemas/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/	気候／作物／生育／生態の4つのエージェントに加え、病害虫（PestAgent）と養分（NutritionAgent）を必要に応じて呼び出します
統合オーケストレーター	agent/orchestrator.py	4つのエージェントによるパイプライン（run_pipeline）＋必要に応じた call_skill によるスキルルーティング＋スキル一覧（list_skills）
農業ゾーンデータ	data/zone_meta/	世界の農業ゾーンのメタデータ
Skill レジストリ	skills/registry/	再利用可能な農業 AI 能力
信頼できる出力の契約	docs/agent_output_contract.md	各提案の根拠／信頼度／適用条件
プロジェクト評価	docs/project_evaluation.md	評価基準ごとの自己評価
戦略指針（過去アーカイブ）	_archive/planning_20261020/项目战略指引.md	2026-08 の戦略構想スナップショット（現在のライセンスポリシーは含みません）
実行計画（過去アーカイブ）	_archive/planning_20261020/项目执行方案.md	2026-09 の段階的ロードマップ（過去アーカイブ）
計画／戦略／GOAI 集約	_archive/planning_20261020/	2026-08〜10 の初期計画10件（アーカイブ済み。プロジェクトの変遷をたどる目的に限り参照可能で、現在の事実を示すものではありません）
オープンソースエコシステム連携	docs/OPEN_SOURCE_INTEGRATION.md	7層アーキテクチャのエコシステム上の不足部分を補完するマッピング（スキャン→連携）＋ユーザー向け段階的操作ガイド（cropgraph MCP の有効化／ビジュアルバックエンドの設定／PAT の提供によるプッシュ）
フィードバックループエンジン	engine/flywheel.py	栽培結果のフィードバック → 適応スコアの調整（能動学習）
インタラクティブデモ	app/	依存関係ゼロの http.server サイト：座標 → 4つのエージェントによるプラン＋AgriTrust 証明書
データ拡張スクリプト	scripts/enrich_crop_data.py	各気候帯に適した作物を補完し、種類数を ≥18 にします
エンドツーエンド検証	scripts/verify_all.py	複数都市のパイプライン＋Trust 証明書の PASS/FAIL
Skill 自動生成	engine/skill_factory.py	新しい作物／能力項目 → Schema に準拠した Skill を自動生成
単体テスト	scripts/test_*.py 系列	700件以上の unittest（依存関係ゼロ）。4つのエージェント＋PestAgent＋NutritionAgent＋SeasonAgent＋SoilProfile＋ForecastAgent(L2)＋ControlAgent(L3)＋Orchestrator の統合ルーティング＋ビジュアルバックエンドのフォールバック＋Trust＋flywheel＋Env Recipe 契約＋データ完全性ガード＋MCP 25ツール＋A2A Card＋Skills Registry 11項目の整合性＋オーケストレーション層の監査可能性29項目＋信頼マークの公開再計算 API 34項目を網羅します
MCP サーバー（Agent-native 配布）	mcp/	依存関係ゼロの stdio 経由 JSON-RPC。30個の農業ツールを公開（ゾーン照合／作物推薦／栽培計画／病害虫診断／養分管理／Env Recipe 配合／物候・播種時期／土壌プロファイル／BP 投資初期審査／複数ソースの気候調整／ジオコーディング→配合／データリネージ照会／プリセット都市／エコシステム連携リスト＋ナレッジ検索 agri_search＋ナレッジグラフ agri_knowledge_query（M12-K1 接続）＋信頼マーク公開再計算 agri_verify_trust（M11-T1 製品化）＋Server Card agri_server_card（M13-P3 ETags キャッシュ）＋意思決定経路レポート agri_decision_path_report（M16-B2 ビジュアルエクスポート）＋農業経済 agri_economics＋収穫後処理 agri_postharvest（Stage 2.3/2.6）＋バッチオブジェクト MVP agri_grow_batch_*（P0 作業パッケージ。Plot/GrowBatch/Observation/Action/Outcome の5種類のオブジェクト））。プロトコルバージョン 2026-07-28（ステートレス）。2025-06-18 / 2024-11-05 と互換。SEP-2575（ハンドシェイク不要）／SEP-2567（セッションなし）／SEP-2243（Mcp-Method）／SEP-2549（ttlMs キャッシュ）／SEP-414（W3C traceparent）に対応済み。登録と配布については mcp/README.md を参照してください
A2A Agent Card	.well-known/agent.json	A2A v1.0 標準のディスカバリーエントリーポイント：標準の skills[] で**30個のスキル（MCP ツールと1対1で対応し、skill.id == MCP ツール名）を宣言します。拡張フィールド x-agri-registry-skills[] で11個のドメインスキル定義（skills/registry/ に対応する内部ナレッジベース。A2A ディスカバリーには含まれません）**を宣言します。securitySchemes={}、入出力スキーマ、ライセンス上の制限（NC のソースを転売しない）を含みます。scripts/gen_agent_card.py が mcp/server.py の TOOLS と skills/registry/*.json からプログラムで生成します。検証には 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.py	P0-H：ゾーン分類の一致率（実測ベースライン）＋4つのスキャフォールディング項目（決して虚偽の報告をしません）。評価セットは data/eval/zone_checks.json です
プレビュー残存物のクリーンアップ	scripts/clean_preview_artifacts.py	プレビューツールが HTML に挿入した data-page-node-id 属性を削除します（一度に115箇所へ挿入されたことがあります）
デモデータのリセット	scripts/clean_demo_data.py	デモ／単体テストによる汚染を受けた feedback_log をクリアし、作物データベースから偽の校正マークを除去します
デモエンドポイントのスモークテスト	scripts/check_demo_endpoints.py	依存関係ゼロのエンドツーエンド自己診断：空きポートを自動選択して app/demo_server.py を起動し、14個のエンドポイント（GET 8件＋POST 6件）を呼び出して、ステータスコード／容量の下限／レスポンス契約のキーを検証します。デプロイ前にローカルでダミーエンドポイントのリスクを解消します。CI に追加済みです
同期状態チェック	scripts/sync_check.py	ローカルワークスペースと 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.py	WOFOST の積算温度に基づく物候（7作物、EUPL 1.2 の帰属表示）＋霜害を基準とする播種時期ウィンドウ。スキルは season_advisory
L3 実行制御エージェント	agent/control_agent.py	生育計画 → ハードウェア非依存の actuator intents（灌漑／施肥／補光／気候／CO₂／ファン）＋needs_gateway ゲートウェイマーク＋車載時の振動／開放環境／機器故障に対する実行補償。スキルは control_commands
L2 予測エージェント	agent/forecast_agent.py	収穫時期（GDD-lite の積算温度）／収量（ベースライン×気候×適応×光量）／リスク（霜害／高温／計画）を予測し、model=heuristic を正直に表示します。未知の作物には安全にフォールバックします。スキルは harvest_forecast
L4 リンクデータプロトコル	schemas/linkage_protocol.schema.json	オープンソースの標準リンクデータ（batch→product→7工程のトリプレット＋鮮度／損失／賞味期間モデル）。L5 認証トレーサビリティを支えます
土壌プロファイル（フォールバックソース）	agent/soil_profile.py	オンラインの SoilGrids を優先 → オフラインではゾーン平均にフォールバックします。resolution=zone／confidence=low とし、指標を捏造しません
ドキュメントのリンク切れスキャン	scripts/check_doc_links.py	すべての md 外部リンクを4状態（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.yml	push 時に単体テスト／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.md を参照してください。よく使うコマンドは make で実行できます（例：make gate = 単体テスト＋エンドツーエンド＋データ品質の3点セット）。

# 查看农业分区数据
python -c "import json; d=json.load(open('data/zone_meta/global_zones.json')); print(len(d))"

# 查看 Skill 注册表
for f in skills/registry/*.json; do python -c "import json; s=json.load(open('$f')); print(s['id'])"; done

---

v2.1 の改善項目を実装（Agent-native 配布 + 設定プロトコル + 評価）

_archive/planning_20261020/项目方案评审-商业模式与AI专业分析.md に基づいています（2026-09 の戦略構想スナップショット。商業的な表現は CORE_OBJECTIVE により廃止済み）。v2.1 の実装は Agent-native 配布 + Env Recipe プロトコル + MCP 配布に注力します。 商業上の主軸に関する記述は履歴の追跡のみを目的とし、現在の実装は docs/CORE_OBJECTIVE.md に準拠します。

改善項目	成果物	検証
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.json	python scripts/validate_env_recipe.py data/env_recipes
P0-E/F 依存関係ゼロの MCP サーバー	mcp/server.py（30 ツール）+ mcp/README.md（外部提出用テンプレートを含む。aishield の Glama/npm への掲載を参考）	python scripts/test_mcp_server.py
P0-H 評価ベースライン	engine/eval.py + scripts/run_eval.py + data/eval/zone_checks.json	python 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.py
P0-2 A2A Agent Card	.well-known/agent.json（A2A v1.0）：skills[] 30 個の skill が MCP ツールと一対一で対応 + x-agri-registry-skills[] 11 個の分野別スキル定義（skills/registry/ に対応）	python scripts/check_agent_card.py
P0-3 Agent Plugins のパッケージ化	plugin/plugin.json + plugin/mcp.json + plugin/skills/*/SKILL.md × 11	python scripts/build_agent_plugin.py --check
P0-7 ハードコードされたキーを排除	agent/finance_agent.py / market_agent.py の secret_key プレースホルダーを、モジュールとともにメインの処理経路から除外	grep -rn "secret_key" --include=*.py . = 0 件

P0 の出口指標：本人以外による初回の外部呼び出しが発生すること。

---

データの衛生管理（重要）

engine/flywheel.py の record_feedback() は実際にディスクへ書き込みます。フィードバックループを実際に機能させるためです。 その代償として、デモと単体テストを分離しないと、合成サンプルが実データに混入します。本プロジェクトではすでに発生した2種類の事故と、その対策を以下に示します。

事故	現象	対策
単体テストによるフィードバックログの汚染	data/feedback_log.json に unittest/smoke のサンプルが12件蓄積し、「実データがすでに戻ってきている」という誤った印象を生む	単体テストでは AGRI_FEEDBACK_LOG を一時ファイルにリダイレクト
作物データベースの偽の校正マーク	34 種の作物に calibrated: true が設定されているだけで校正の証拠がゼロなのに、信頼性レイヤーが実測データとして出力	scripts/clean_demo_data.py によるクリーンアップ + CI/単体テストの二重ゲート

ルール：

1. data/feedback_log.json に記録できるのは実際のユーザーフィードバックのみです。デモ記録には [demo] プレフィックスを付けてください。ゲートにより、未標識の合成データはブロックされます。
2. python -m engine.flywheel を実行した後は、コミット前に次を実行してください：

   python scripts/clean_demo_data.py --dry-run   # 先看会清多少
   python scripts/clean_demo_data.py             # 实际清理
   

3. 隔離して実行する場合（リポジトリ内のデータに触れない）：

   AGRI_CROP_DB=<绝对路径>/crop.json AGRI_FEEDBACK_LOG=<绝对路径>/fb.json python -m engine.flywheel
   

   ⚠️ Windows での注意：Git Bash の /tmp は %LOCALAPPDATA%\Temp にマッピングされますが、Python は C:\tmp として解釈します。 必ず Windows 形式の絶対パスを使ってください。そうしないと、AGRI_CROP_DB がファイルを見つけられず、エラーが発生します（意図的に fail fast し、全件 None の出力を黙って返すことを防ぎます）。
4. CI の flywheel ステップは $RUNNER_TEMP の隔離ディレクトリに書き込むよう変更済みで、データ整合性ゲートも追加されています。

---

クイックスタート

1. インタラクティブなデモサイト（依存関係ゼロ、標準ライブラリのみ）

python app/demo_server.py
# 浏览器打开 http://127.0.0.1:8000
# 选择城市 / 场景 / 预算 → 四 Agent 协同方案 + 可点击 AgriTrust 证书

2. エンドツーエンド検証

python scripts/verify_all.py          # 五城市 pipeline + Trust 证书，输出 PASS/FAIL
python -m engine.flywheel              # 跑一次反馈闭环示例，校准「生菜」adapt_score
python scripts/enrich_crop_data.py     # 扩展作物数据密度至每带 ≥18 种

3. Docker デプロイ

docker compose up --build                                  # 本地 verify 模式（跑端到端验证即退出）
docker compose -f deploy/docker-compose.prod.yml up -d --build   # 生产 serving 模式（宿主机 :8001 → 容器 :8000）

3b. 公開環境へのデプロイ（コマンド1つ）

cp deploy/deploy_config.example.sh deploy/deploy_config.sh   # 一次性：按需改 IP/端口
bash deploy/deploy_local.sh                                   # 同步代码 + 远端构建 + 启动 + 验证
# 站点：http://<ECS_IP>:8001   详细流程见 deploy/DEPLOY.md

3b-2. 視覚診断バックエンド（任意、ATEX マルチモーダルゲートウェイに接続）

PestAgent の視覚診断は、プラグイン可能なバックエンドを使用します。以下の環境変数を設定すると有効になります（agent/vision.py を参照）。未設定の場合はルールベースのフォールバックに切り替わります。 キーはリポジトリ外の .env に保存してください（.gitignore で無視されます。デプロイ時に deploy_local.sh が ECS に同期し、GitHub には入りません）。

# .env（项目根目录，不要提交）
AGRI_VISION_URL=http://host.docker.internal:8420/v1   # ATEX 网关，容器内用 host 网桥访问
AGRI_VISION_KEY=<你的 ATEX 网关 Key>
AGRI_VISION_MODEL=gpt-4o                              # 须为多模态模型

deploy/docker-compose.prod.yml は、これら3つの変数をデフォルトで読み込みます。ATEX が 127.0.0.1 でのみ待ち受けている場合は、AGRI_VISION_URL をホストのプライベートネットワーク IP に変更できます。

3c. CI（push 時に自動検証）

.github/workflows/ci.yml

main に push すると、単体テスト → verify_all → trust_layer → flywheel（$RUNNER_TEMP に隔離）→ データ整合性ゲート（偽の校正マークと合成フィードバックサンプルを禁止）→ Skill レジストリの妥当性確認 → データのセルフチェック（各バッチに18種類以上の作物）を自動実行します。Python 3.10/3.11/3.12 のマトリックスで実行されます。 ステータス：GitHub Actions が正常に動作することを検証済みです（Workflows:write 権限を含む fine-grained PAT を使用。push 後に CI が自動実行され、直近の run の結果は success）。

3d. 本地 → GitHub 同步（无 git push 环境）

本机 github.com:443 不可达，且本地目录不是 git clone，不能用 git push / git status。 统一走这两个脚本：

# 1) 查看待推差异（只读，公开仓库可匿名）
python scripts/sync_check.py

# 2) 推送（单 commit，推送后自动回读校验）
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     # 836 项用例全过

4b. MCP / 协议 / 评测（v2.1 提升项）

python scripts/test_mcp_server.py                  # MCP server 自测：initialize/tools/list/tools/call
python scripts/validate_env_recipe.py data/examples/sample_env_recipe.json  # Env Recipe v1 Schema 校验
python scripts/run_eval.py                          # AI 评测基线（分区一致率真实数字 + 脚手架项）

注册到 Claude Desktop（stdio）：见 mcp/README.md。Env Recipe 协议说明与 AeroGarden 孤儿设备接入路径：见 docs/env_recipe_protocol_v1.md。

5. Skill 自动生成（闭环触发）

python -m engine.skill_factory            # 演示：新作物冰菜 → 自动 Skill
python -m engine.skill_factory --list     # 列出当前所有 Skill

6. 提交种植反馈（内测回流 → flywheel 校准）

python scripts/submit_feedback.py --zone subtropical_wet --crop 生菜 \
  --survival 0.92 --yield 4.5 --rating 5 --issues "梅雨季霜霉病" --note "杭州阳台春播"
# 或直接调用 Demo 站点 POST /api/feedback

---

自动化定时闭环（每日单口巡检）

本仓的每日治理巡检由专属 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>.md	verify_all + data_quality_gate + 全量单测三件套，非零退出即暴露漂移，只读巡检

执行内容（全部只读，禁改代码 / 禁 git / 禁推送）：

1. 回归十八项（836 项单测 + 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（25 工具）、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
2. 数据源存活探测：GAEZ / WorldClim / SoilGrids(rest.isric.org) / PlantVillage / EPPO / GitHub 等 7 个外部源 —— 防止引用死数据源（Ecocrop / OpenFarm / @pondlog 三次教训）
3. 回流通路健康检查：跑 check_feedback_loop.py，区分「通路故障（≠0 报警）」与「数据量缺口（=0 条、不报警）」（JSON 字段 snapshot.feedback_path = ok/broken）
4. 状态快照 + 跨日 diff：feedback 条数 / recipes 数 / wofost 作物数；与昨日报告对比，零漂移即静默，漂移即暴露

已知长期缺口：data/feedback_log.json 持续 0 条 = 通路可用但无真实用户回流数据（属产品/增长问题，非代码缺陷——不得以合成数据充数）。

---

开源协议

本仓库全栈 MIT 开源：engine/（机理内核，含 AgriWorld-Lite 状态机、@bounded 装饰器、WOFOST 物候）、agent/（forecast / conformal / causal attribution / bayesian calibration / knowledge loop）、core/（numeric domain / trust layer / crop registry）、mcp/（21 工具适配器）、benchmarks/（AgriRecipeBench 89 用例 + 20 负例 + AgriWorld-Arena 35 entries）、scripts/、data/、schemas/、.well-known/（含 JWS 签名）、docs/ 均随仓库发布。

MCP server 的完整实现位于 mcp/server.py（含 TOOLS 注册表 + stdio/SSE 双模式 + server card + ETags + 渐进式发现 kind=search / mode=brief|full），与 CLI 共用同一批 Python 函数，无云端副本、无独立后端。

_archive/planning_20261020/ 目录下的历史战略文档（2026-08 至 2026-10-10 项目构想快照）中的商业利润模型措辞已被 docs/CORE_OBJECTIVE.md 明确废除，仅作项目演进证据链保留，不代表当前许可策略或实现事实。当前事实以本节 + LICENSE + docs/CORE_OBJECTIVE.md 为准。

MCP 工具全表（30 个）

本表由 scripts/gen_tool_table.py 从 mcp/server.py 的 TOOLS 注册表程序化生成，禁止手写。工具总数 30。

#	工具名	分类	一句话说明	必填参数	返回类型
1	agri_list_cities	climate	列出预设城市（经纬度 + 气候带），供 Agent 选点或核对分区。	无	[City] JSON
2	agri_match_zone	climate	输入经纬度，返回气候分区匹配结果（含证据与限制因子）。	lat — 纬度 lon — 经度	Zone Match JSON
3	agri_recommend_crops	crop	根据分区（lat/lon 或 city）与偏好（用途/空间/难度）推荐作物。	见参数详情	JSON
4	agri_growth_plan	phenology	作物 + 场景 + 分区 → 生成种植计划（含微气候修正）。	crop — 作物名，如 番茄	Plan JSON（阶段化）
5	agri_diagnose_pest	pest	病虫害与营养缺乏诊断：输入作物、症状描述（可选图像引用、生长阶段、环境）。	crop	JSON
6	agri_nutrition_plan	nutrition	养分管理：作物 + 阶段 → 阶段化施肥方案。	crop	Plan JSON（阶段化）
7	agri_env_recipe	recipe	（P0-G）作物 + 生长阶段 + 设备类别 → 返回一份 Env Recipe v1 合规配方 JSON。	无	Env Recipe v1 JSON
8	agri_season_advisory	meta	（B1+B2）物候与播期：mode=planting_window 时给 12 个月均温返回无霜期与各作物最早/最晚安全播种日；mode=stage_days 时给作物+日均温返回…	见参数详情	JSON
9	agri_soil_profile	soil	（土壤降级路径）经纬度或分区 → 土壤剖面。优先查 ISRIC SoilGrids v2.0（在线点数据），不可用时降级为离线分区均值并明确标注 resolution=zone、c…	见参数详情	SoilProfile JSON
10	agri_bp_screen	business	（投资初筛）农业项目投资初筛系统：传入 BP/审计/流水文本（text）或已抽取字段（fields），跑九层管线 → 六分类（种业/农机/数字农业/生物投入品/供应链/养殖）+ 五…	见参数详情	BPScreenReport JSON
11	agri_reconcile_climate	climate	（多源气候校准）给定经纬度，并行拉 NASA POWER + Open-Meteo，逐月平均得调和月均温基线，并计算逐月一致度（多源标准差）与分歧月份告警（标准差超 3℃ 标记）。…	lat — 纬度 lon — 经度	Climate Reconcile JSON
12	agri_resolve_recipe	recipe	（地理编码→配方）城市名（中文/英文）或经纬度 → 匹配气候分区 → 检索该分区的 Env Recipe 清单。返回 zone_id / zone_name / 坐标 / 匹配配方…	见参数详情	Env Recipe v1 JSON
13	agri_query_lineage	meta	（数据血缘查询）按作物/分区查配方的数据溯源：外部 API 参与情况 + 本地权威文件 SHA256 指纹 + 校准实证（壁垒④）。传入 crop+zone_id 做单点追踪；仅 …	见参数详情	Lineage JSON
14	agri_list_ecosystem	meta	（生态对接清单）返回智慧农业生态对接的开源/商业生态清单（config/ecosystem.json），含对接状态（integrated/partial/planned_mappi…	见参数详情	[Ecosystem] JSON
15	agri_search	knowledge	（知识检索 M12-K1）跨 4 语料（crops/zones/pests/recipes，共 335 条）做词法+向量混合检索，底层是 stdlib-only 的 char n-…	query — 查询串（必填）	SearchResult JSON
16	agri_knowledge_query	knowledge	（知识图谱查询 M12-K1）查 261 实体 / 446 边的农业知识图谱（engine/knowledge_graph.py）。支持 5 种 kind：summary=整体统计…	见参数详情	KnowledgeGraph JSON
17	agri_forecast	forecast	（独立预测 M13-P1）产量/采收期预测，含 T-3 置信区间（P10/P50/P90）。底层与 agri_growth_plan 内的推荐部分同源（ForecastAgent）…	crop — 作物中文名（必填）	Forecast JSON（含 P10/P50/P90）
18	agri_recipe_profile	recipe	（配方 profile 五件套 M8-R2 + M13-P2）152 份 Env Recipe 资产的浏览、检索、比对、导出、加载。支持 6 种 kind：list=列出所有配方元…	见参数详情	Profile JSON（多 mode）
19	agri_verify_trust	meta	（可信标记公共复算 API M11-T1）外部独立验证 AgriTrust 可信标记 / 证书。支持 3 种 mode：current=返回当前信任标记（含 signature 与…	mode — 验证模式：current/check_prefi	Verification JSON（含 signature 校验）
20	agri_server_card	meta	（Server Card + ETags M13-P3）返回 MCP 服务元数据卡（能力/分类/协议/URL 等），带稳定 ETag（sha256 前 16 hex）。客户端可缓存…	见参数详情	ServerCard JSON（含 ETag）
21	agri_decision_path_report	bp_screen	（决策路径可视化报告 M16-B2）将 bp_screen 评分引擎的 decision_path 归因数据导出为可视化报告。返回结构化 JSON：每个案例含 verdict/de…	见参数详情	DecisionPathReport JSON
22	agri_counterfactual_trajectory	counterfactual	（反事实轨迹 API · Phase N+1 #6）给定作物与基线动作序列，用 AgriWorld-Lite 机理内核（光截获 Beer-Lambert + CO2 同化 + Q1…	crop — 作物名，如 potato/番茄/生菜	Trajectory JSON（数组 + CI）
23	agri_verify_recommendation	verify	（Verify-as-a-Service · Phase N+3 #14 · 支柱五）作为「农业 Agent 的裁判」验证第三方（另一个 Agent、大模型、BP、农艺师）给出的农…	claim — 被验证主张，如 {crop, yield_g_m context — 上下文，如 {dli_mj_m2_d, days	Verdict JSON（含 trust_mark）
24	agri_economics	business	（Stage 2.3 · 2026-10-24 新增）农业经济测算：输入 crop / zone / area_sqm / 投入参数，输出投入成本 CNY / 预期产量 kg / …	crop — 作物中文名	JSON
25	agri_postharvest	nutrition	（Stage 2.6 · 2026-10-24 新增）采后处理/储藏：输入 crop，返回最佳储藏温湿度 / 损耗率 / 保鲜期 / 采后病害风险。诚实边界：数据来自 FAO Co…	crop — 作物中文名	JSON
26	agri_grow_batch_create	batch	（批次对象 MVP · 2026-10-27 新增）建立 Plot + GrowBatch：把 MCP/UI/校准/审计的局部上下文收束到批次对象链。MVP 阶段可建立并回放一个模…	plot — Plot 对象（grow_batch.schem batch — GrowBatch 对象（grow_batch.	JSON
27	agri_grow_batch_observe	batch	（批次对象 MVP · 2026-10-27 新增）追加 Observation：批次生命周期内的一次观察（传感自动或人工/图像补充）。输入 observation（observa…	observation — Observation 对象（grow_batc	JSON
28	agri_grow_batch_action	batch	（批次对象 MVP · 2026-10-27 新增）记录 Action：一次建议→审批→执行→确认的动作链。MVP 默认 shadow/dry_run，不真实执行；真实执行（exe…	action — Action 对象（grow_batch.sch	JSON
29	agri_grow_batch_status	batch	（批次对象 MVP · 2026-10-27 新增）查询批次状态 + 关联对象（Plot/Observation/Action/Outcome）。可选 include_events…	batch_id — 批次唯一 ID	JSON
30	agri_grow_batch_replay	batch	（批次对象 MVP · 2026-10-27 新增）按时间线回放批次事件：重建事件序列，不触发任何真实执行或副作用（诚实标注）。	batch_id — 批次唯一 ID	JSON

每个工具的详细参数说明见 mcp/README.md 对应章节。