feat(v2): T14 README v2 改写(架构/快速开始/指标)

This commit is contained in:
tzt
2026-08-30 21:21:00 +08:00
parent b900082c6d
commit 0ec7a9d034
3 changed files with 160 additions and 98 deletions
+47
View File
@@ -0,0 +1,47 @@
# 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 11shell 为 Git BashPython venv 在 `.venv`Python 3.14)。
- 测试:`.venv/Scripts/python.exe -m pytest tests -q`(基线 126 passed2026-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 转向依据) |