48 lines
2.8 KiB
Markdown
48 lines
2.8 KiB
Markdown
# 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「快速开始」。
|
||
|
||
## 硬性约束（违反即返工）
|
||
|
||
1. `router_system/` 核心包零第三方依赖（纯标准库）；`runtime/`、`gateway/` 可用
|
||
httpx / fastapi / pydantic / uvicorn；新增任何依赖需说明理由并登记 requirements*.txt。
|
||
2. 所有 LLM 结构化输出必须过 JSON Schema 校验；解析失败重试一次后降级，禁止带病继续。
|
||
3. Architect（大模型 API）输入永不包含工件全文，只用锚点＋片段（方案 5.1 / D7）。
|
||
4. 一切 LLM 调用在测试中用 `httpx.MockTransport` 注入，测试不依赖真实模型或 API key。
|
||
5. 不修改 llama.cpp 源码；只捆绑上游 release 二进制（`bin/`，gitignore）。
|
||
6. Windows 兼容：`pathlib` 路径、CLI 出口 UTF-8 reconfigure（先例 `scripts/eval.py`）、
|
||
子进程 terminate→kill 兜底。
|
||
7. 金额敏感：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 转向依据） |
|