# 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「快速开始」。

## 硬性约束（违反即返工）

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_端云协同编程智能体系统.md | v2 基础方案（交流文本协议/任务分解/实验设计） |
| 实现方案_v3_Web应用化.md | v3 Web 应用化（Vue3 SPA + SSE 实时协作可视化） |
| 实现方案_v4_模型池与工具智能体.md | v4 增补（多价位模型池 + 工具智能体） |
| AI代理功能开发/方案_校园AI代理层.md | 校园 AI 代理层设计（缓存经济学/规模测算/合规红线） |
| AI代理功能开发/实施方案_代理层与缓存层.md | 代理层执行方案（T-P0–T-P8：文件级/DDL/接口/验收） |
| 任务拆解与执行计划.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 转向依据） |