2.8 KiB
2.8 KiB
AGENTS.md — Agent 仓库导读
面向在此仓库工作的 AI Agent。人类开发者也可参考。
当前权威规划（先读这个）
《实现方案_v2_端云协同LLM协作系统.md》（仓库根目录）是当前唯一权威实施方案： 大模型（API）任务分析/决策/终审 ＋ 小模型（本地 llama.cpp）实现/自验证 ＋「交流文本」结构化共享工作区 ＋ 人工检验队列。
- 实现前必读其第 3 节（不得推翻的设计决策 D1–D11）与第 8 节（工程规约）。
- 任务按其第 7 节 T1–T14 顺序执行；每完成一个任务，在《任务拆解与执行计划.md》登记一行。
- v1 的 L0 专家系统内核不删除，保留为 legacy 路由（
POST /chat/legacy）与离线降级模式； v1 测试套件（126 项）必须保持全绿。
环境事实
- Windows 11，shell 为 Git Bash；Python venv 在
.venv（Python 3.14）。 - 测试：
.venv/Scripts/python.exe -m pytest tests -q（基线 126 passed，2026-08-30）。 - 运行 demo / 评测 / 网关的命令见 README「快速开始」。
硬性约束（违反即返工）
router_system/核心包零第三方依赖（纯标准库）；runtime/、gateway/可用 httpx / fastapi / pydantic / uvicorn；新增任何依赖需说明理由并登记 requirements*.txt。- 所有 LLM 结构化输出必须过 JSON Schema 校验；解析失败重试一次后降级，禁止带病继续。
- Architect（大模型 API）输入永不包含工件全文，只用锚点＋片段（方案 5.1 / D7）。
- 一切 LLM 调用在测试中用
httpx.MockTransport注入，测试不依赖真实模型或 API key。 - 不修改 llama.cpp 源码；只捆绑上游 release 二进制（
bin/，gitignore）。 - Windows 兼容：
pathlib路径、CLI 出口 UTF-8 reconfigure（先例scripts/eval.py）、 子进程 terminate→kill 兜底。 - 金额敏感：API 调用必须计量并受
api_token_cap熔断约束。
代码风格
- 中文 docstring；配置构造用
build_xxx(cfg)工厂；与现有文件排版/命名一致。 - 每任务一个 commit，格式
feat(v2): Tn 描述。
文档地图
| 文档 | 用途 |
|---|---|
| 实现方案_v2_端云协同LLM协作系统.md | 当前权威规划（架构/协议/任务分解/实验设计） |
| 任务拆解与执行计划.md | 任务状态登记表（v1 历史任务 + v2 新任务追加处） |
| 实现方案_多专业小模型+路由模型.md | v1 方案（已被 v2 取代方向，作历史参考） |
| 可行性调研与落地实现路线报告.md | v1 期可行性论证（历史参考） |
| research/2026_papers_survey.md | 文献调研（LLM 路由/级联/验证器） |
| research/routerarena/01_results_and_gap_analysis.md | v1 实测数据（74.4% 准确率、68.9% 升级率——v2 转向依据） |