3.6 KiB
3.6 KiB
AGENTS.md — Agent 仓库导读
面向在此仓库工作的 AI Agent。人类开发者也可参考。
当前权威规划（先读这个）
《实现方案_v2_端云协同编程智能体系统.md》（仓库根目录）是 v2 基础权威方案， v3（Web 应用化）、v4（模型池与工具智能体）为其增量权威方案（均已落地）： 大模型（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_端云协同编程智能体系统.md | v2 基础方案（交流文本协议/任务分解/实验设计） |
| 实现方案_v3_Web应用化.md | v3 Web 应用化（Vue3 SPA + SSE 实时协作可视化） |
| 实现方案_v4_模型池与工具智能体.md | v4 增补（多价位模型池 + 工具智能体） |
| AI代理功能开发/方案_校园AI代理层.md | 校园 AI 代理层设计（缓存经济学/规模测算/合规红线） |
| AI代理功能开发/实施方案_代理层与缓存层.md | 代理层执行方案（T-P0–T-P8：文件级/DDL/接口/验收） |
| AI代理功能开发/实施方案_语义分析器与三级分级.md | 语义分析器执行方案（T-G0–G8：三级分级/共享Embedding/conformal/灰度） |
| 任务拆解与执行计划.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 转向依据） |