Skip to content

Commit 5184c10

Browse files
Cyning12CyningMMcursoragent
authored
docs(governance): docs-noise P0 fix C1-C3 README pointers (#121)
* docs(governance): add docs-noise-inventory spec with map README Land the docs/ noise audit as a dedicated governance subdirectory so agents read the map by default and open the full SPEC only for tasks. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(diary): add Plan Agent analysis and link to docs-noise governance Mirror the 2026-06-05 Plan Agent comparison experiment as diary evidence for navigation/read-path issues, and cross-link it from docs-noise-inventory. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(task): add gov-docs-noise P0 task with human gates approved Human signed HG-TASK-DRAFT and HG-GOV-P0-EXEC for Cursor Task-chain T1 pilot (C1–C3 README fixes). Co-authored-by: Cursor <cursoragent@cursor.com> * docs(harness): add Cursor Task-chain PROMPT template and T1 P0 invoke Freeze serial subagent orchestration prompt; T1 instance covers explore→22→30→40→CLOSE for gov-docs-noise-p0. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(harness): explore C1-C3 差分报告与 invoke 落盘 只读核对 docs-noise P0 三处冲突；无阻塞，建议 30 帽开工。 Co-authored-by: Cursor <cursoragent@cursor.com> * docs(harness): 22 R1 任务审核落盘 gov-docs-noise P0 零阻塞；test_strategy not_applicable 充分；建议 30 帽开工。 Co-authored-by: Cursor <cursoragent@cursor.com> * docs(governance): P0 修 C1-C3 README 指针 更正 invokes/reviews 分工；docs/README 推 _tech_graph；新建 tech_graph POINTER。 Co-authored-by: Cursor <cursoragent@cursor.com> * docs(harness): 40 自检回填 gov-docs-noise P0 验收 C1-C3 通过；建议 CLOSE + PR。 Co-authored-by: Cursor <cursoragent@cursor.com> * docs(harness): CLOSE invoke gov-docs-noise P0 Round T1 串行帽链 explore→22→30→40 完成；待 PR + CI。 Co-authored-by: Cursor <cursoragent@cursor.com> * fix(task): failure_paths 补 Scenario ID 列通过 validate harness_task_validate 要求 F# + Scenario ID 格式。 Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: cyning <cyning12@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 5888ec1 commit 5184c10

29 files changed

Lines changed: 2878 additions & 4 deletions

‎docs/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,9 @@
99
## 1. 你应该从哪里开始读
1010

1111
- **如果你要改代码/环境变量/接口边界**：先读 `docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`
12+
- **如果你要理解架构与端到端流程（L0 真值）**：读 [`docs/_tech_graph/`](_tech_graph/)（改拓扑用 `python tools/tech_graph_graph_query.py` 按需；**禁止**默认整包 `graph.json`）
1213
- **如果你要做任务实现/验收**：从 [`docs/tasks/_views/`](tasks/_views/) 按状态进入，或直接在 `docs/tasks/active/`、`docs/tasks/done/` 找 `task_*.md`（每个 Task 需要写明 `状态`）
13-
- **如果你要理解“端到端怎么跑”**：读 `docs/flows/` 的版本化流程快照
14+
- **如果你要查历史流程快照（Legacy · 非 L0）**：读 `docs/flows/` 的版本化流程快照（已被 `docs/_tech_graph/` 取代；仅做历史对比时打开）
1415
- **如果你要做 UI 协议对齐（SSE、events、timeline）**：读 `docs/UI/`
1516
- **如果你要做 Text2SQL**：读 `docs/text2sql/`
1617
- **如果你要做可复现交付（SDD/TDD/Harness）**：读 [`docs/harness/README.md`](harness/README.md) → [`docs/harness/ACCEPTANCE_LANDING.md`](harness/ACCEPTANCE_LANDING.md)（含 **50 三方复检** 落盘 `docs/tasks/reinspect_results/`），辅以 `docs/delivery/`
@@ -137,4 +138,5 @@
137138
- [x] `docs/tasks/_views/done.md`
138139
- [ ] **为 `UI/`、`flows/`、`delivery/` 建索引页**（同样只新增入口文件，不移动原文档）
139140
- [ ] **补齐跨仓引用规则**：Task/Flow/UI 文档中引用前端仓文件时，统一写相对仓库路径并避免本地绝对路径
141+
- [ ] **docs 噪音治理（P0～P3）**：见 [`docs/spec/governance/docs-noise-inventory/README.md`](spec/governance/docs-noise-inventory/README.md)（**只读导图**；正文 SPEC 开 task 时再开）
140142

‎docs/diary/2026-06-05-plan-agent-analysis/00_README.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Plan Agent 对比实验 · 文档索引
2+
3+
> **日期**：2026-06-05
4+
> **项目**：`ai-ink-brain-api-python`
5+
> **触发命令**：「启动 Plan Agent，制定升级计划」
6+
> **模型**：Claude Code 与 Kimi Code 均使用 `kimi-for-coding`
7+
8+
---
9+
10+
## 1. 背景（发生了什么）
11+
12+
在本项目启动后，Claude Code 与 Kimi Code 分别尝试读取项目概况与任务排期，并调用 **Plan Agent** 制定升级计划。两者使用**相同模型、相同项目、相近命令**，结果却出现明显差距：
13+
14+
| 工具 | Plan Agent 结果 | 根 Agent 补救 |
15+
|------|----------------|---------------|
16+
| **Claude Code** | ✅ 成功（约 30.3k tokens，37 次工具调用） | 无需补救 |
17+
| **Kimi Code** | ❌ 300s 超时失败 | 根 Agent 手写 `artifacts/kimi/upgrade_plan_fallback.md` |
18+
19+
差距不在项目文档缺失，而在 **子 Agent 如何发现与继承项目导航上下文**：
20+
21+
- Claude Code：自动按 `AGENTS.md` → `.cursor/rules/` → `_tech_graph/` → `tasks/` 分层读取
22+
- Kimi Code Plan Agent：零上下文启动，按平铺文件列表深读 V3 SPEC 与巨型源码，跳过图谱与规则
23+
24+
本目录完整留证上述对比过程、阅读路径、根因分析与对外 Issue 草稿。
25+
26+
---
27+
28+
## 2. 目录结构
29+
30+
```
31+
2026-06-05-plan-agent-analysis/
32+
├── 00_README.md ← 本索引
33+
├── artifacts/ ← 两侧实际产出（客观证据）
34+
│ ├── claude/ ← Claude Code 成功路径产出
35+
│ │ ├── project_reading_path.md
36+
│ │ ├── explore_codebase_structure.md
37+
│ │ └── upgrade_plan.md
38+
│ └── kimi/ ← Kimi Code 超时后的补救产出
39+
│ └── upgrade_plan_fallback.md
40+
├── analysis/ ← 对比分析与根因
41+
│ ├── 01_root_cause_and_paths.md
42+
│ ├── 02_agent_design_comparison.md
43+
│ ├── 03_reading_path_comparison.md
44+
│ └── 04_issue_reply_analysis.md
45+
└── outbound/ ← 对外提交材料
46+
└── kimi_code_issue_draft.md
47+
```
48+
49+
---
50+
51+
## 3. 推荐阅读顺序
52+
53+
| 顺序 | 文件 | 用途 |
54+
|------|------|------|
55+
| 1 | 本文件 | 建立全局上下文 |
56+
| 2 | `artifacts/claude/project_reading_path.md` | Claude Code 的 6 层阅读策略（对照基准） |
57+
| 3 | `analysis/01_root_cause_and_paths.md` | Kimi Plan Agent 实际读了什么、漏了什么 |
58+
| 4 | `analysis/03_reading_path_comparison.md` | 两侧阅读路径逐项对比表 |
59+
| 5 | `analysis/02_agent_design_comparison.md` | 子 Agent 零上下文 vs Claude 自动注入 |
60+
| 6 | `artifacts/claude/upgrade_plan.md` vs `artifacts/kimi/upgrade_plan_fallback.md` | 成功计划 vs 补救计划的内容差异 |
61+
| 7 | `outbound/kimi_code_issue_draft.md` | 提交 Kimi 官方的 Issue 草稿 |
62+
| 8 | `analysis/04_issue_reply_analysis.md` | Issue #489 第三方回复（AgentRelay）解读 |
63+
64+
---
65+
66+
## 4. 核心结论（TL;DR）
67+
68+
1. **项目侧无责**：`AGENTS.md`、`.cursor/rules/`、`docs/_tech_graph/` 导航体系完备。
69+
2. **Kimi 侧双重因素**：
70+
- **产品机制**：`Agent` 工具子 Agent 零上下文，不自动注入 `AGENTS.md` / `.cursor/rules/`
71+
- **Prompt 质量**：根 Agent 给子 Agent 的文件列表平铺、未禁读 SPEC、未强制图谱优先
72+
3. **Claude Code 优势**：子 Agent 能感知项目导航与工程约束，形成 6 层递进阅读，Plan 任务一次成功。
73+
4. **短期 workaround**：在 `Agent(...)` 的 prompt 中显式写明导航顺序与禁止项（见 `analysis/02` §5、`outbound/` 草稿）。
74+
5. **长期建议**：Kimi Code 产品侧增加子 Agent 自动注入 `AGENTS.md` + `.cursor/rules/`（Issue 草稿已写）。
75+
76+
---
77+
78+
## 5. 两份升级计划的差异说明
79+
80+
| 维度 | Claude 版 | Kimi 补救版 |
81+
|------|-----------|-------------|
82+
| 路径 | `artifacts/claude/upgrade_plan.md` | `artifacts/kimi/upgrade_plan_fallback.md` |
83+
| 来源 | Plan Agent 成功产出 | 子 Agent 超时后根 Agent 基于排期手写 |
84+
| 结构 | 5 阶段（P0–P4）：加固 → 解耦 → 性能 → 测试 → DX | 5 Phase：债务清偿 → 架构演进 → …（对齐 `RECENT_TASK_SCHEDULE`） |
85+
| 侧重点 | 工程现代化（路由拆分、服务层、OTel、Redis 限流） | 任务驱动关账（active task 进 `done/`、Intent/Graph 演进） |
86+
87+
两者互补：Claude 版偏架构与工程体验；Kimi 版更贴本仓 Harness 任务排期。**均非 L0 真值**，实施前须对照 `docs/tasks/` 与 `docs/_tech_graph/`。
88+
89+
---
90+
91+
## 6. 关联链接
92+
93+
- Kimi 官方 Issue：https://github.com/MoonshotAI/kimi-code/issues/489
94+
- 项目导航真值：`AGENTS.md`、`docs/_tech_graph/00_main.md`
95+
96+
---
97+
98+
99+
---
100+
101+
## 6.1 落盘位置
102+
103+
- **草稿轨（本机）**：`tmp/diary/2026-06-05-plan-agent-analysis/`（Git 不跟踪）
104+
- **留证轨（可提交）**：`docs/diary/2026-06-05-plan-agent-analysis/`（与 tmp 内容同步，2026-06-06 整理后镜像）
105+
106+
## 7. 修订记录
107+
108+
| 日期 | 说明 |
109+
|------|------|
110+
| 2026-06-05 | 初稿：Plan Agent 超时分析与 Kimi vs Claude 对比 |
111+
| 2026-06-06 | 整理目录：按 artifacts / analysis / outbound 分层，重写本索引 |

‎docs/diary/2026-06-05-plan-agent-analysis/analysis/01_root_cause_and_paths.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Plan Agent 超时 · 根因与阅读路径
2+
3+
> **日期**：2026-06-05
4+
> **所属**：`analysis/01` · 完整索引见 [`00_README.md`](../00_README.md)
5+
6+
> **事件**：Plan Agent（`Create upgrade plan`）执行超时（300s）失败
7+
> **分析目标**：记录完整读取路径、改动路径、根因定位
8+
9+
---
10+
11+
## 1. 本次会话中 Plan Agent 实际读取的文件路径（完整）
12+
13+
Plan Agent 在超时前读取了以下文件（按工具调用顺序）：
14+
15+
16+
| # | 文件路径 | 类型 | 说明 |
17+
| --- | ------------------------------------------------------ | ---- | --------------------- |
18+
| 1 | `AGENTS.md` | 导航 | Agent 指引（正确） |
19+
| 2 | `docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md` | 配置 | 环境变量/契约真值（正确） |
20+
| 3 | `docs/tasks/RECENT_TASK_SCHEDULE.md` | 排期 | 任务状态与优先级（正确） |
21+
| 4 | `docs/harness/README.md` | 流程 | Harness 关账流程（正确） |
22+
| 5 | `docs/coding_wiki/index.md` | 索引 | Coding Wiki L2 导航（正确） |
23+
| 6 | `main.py` | 源码 | 入口转发（正确） |
24+
| 7 | `api/index.py` | 源码 | 主 FastAPI 应用（正确） |
25+
| 8 | `api/unified_chat.py` | 源码 | Unified Chat 实现（正确） |
26+
| 9 | `requirements.txt` | 配置 | 依赖列表（正确） |
27+
| 10 | `pytest.ini` | 配置 | 测试配置（正确） |
28+
| 11 | `docs/spec/v3-agent/SPEC-ChatBI-V3-Resilience-Ops.md` | SPEC | **V3 实现细节**（过度深入） |
29+
| 12 | `docs/spec/v3-agent/SPEC-ChatBI-V3-Evaluation.md` | SPEC | **V3 实现细节**（过度深入） |
30+
| 13 | `docs/spec/v3-agent/SPEC-ChatBI-V3-Security.md` | SPEC | **V3 实现细节**（过度深入） |
31+
| 14 | `docs/spec/v3-agent/SPEC-ChatBI-V3-Identity-Access.md` | SPEC | **V3 实现细节**（过度深入） |
32+
33+
34+
**未读取的关键文件**（项目图谱入口，本应先读）：
35+
36+
- ❌ `docs/_tech_graph/00_main.md` — 架构总览 Mermaid
37+
- ❌ `docs/_tech_graph/99_spec.md` — 规格总索引
38+
- ❌ `docs/_tech_graph/_manifest.json` — 图谱 manifest
39+
- ❌ `docs/_tech_graph/graph.json` — 机器可读图谱
40+
41+
---
42+
43+
## 2. 本次会话中产生的改动文件路径（完整）
44+
45+
> **注（2026-06-06 整理）**：下表为当时会话落盘路径；整理后统一迁入本目录子树，见 [`00_README.md`](../00_README.md) §2。
46+
47+
48+
49+
| # | 文件路径 | 操作 | 说明 |
50+
| --- | -------------------------------------------------------- | -------- | --------------------------------- |
51+
| 1 | `artifacts/kimi/upgrade_plan_fallback.md` | **新建** | Plan Agent 失败后，由根 Agent 手动制定的升级计划 |
52+
| 2 | `artifacts/kimi/` | **新建目录** | 存放升级计划 |
53+
| 3 | `00_README.md` | **新建** | 本分析落盘文件 |
54+
| 4 | `analysis/` | **新建目录** | 分析落盘目录 |
55+
56+
57+
---
58+
59+
## 3. 根因：Prompt 设计问题归属
60+
61+
### 3.1 结论：**Kimi Code 侧（我）的 Prompt 设计问题**，不是项目的问题
62+
63+
64+
| 维度 | 项目侧 | Kimi Code 侧（我） |
65+
| ------------- | ------------------------------------------------ | --------------------------------------- |
66+
| 知识组织 | ✅ 已建立完整图谱体系（`_tech_graph/`、`AGENTS.md` 导航） | — |
67+
| 读取指引 | ✅ `AGENTS.md` 明确写了"必读按顺序"，第 3 条就是 `_tech_graph/` | — |
68+
| 快速入口 | ✅ `00_main.md` 一张图展示全架构 | — |
69+
| **Prompt 约束** | — | ❌ **未在 prompt 中强制要求按 `AGENTS.md` 顺序读取** |
70+
| **深度控制** | — | ❌ **未禁止读取 `docs/spec/v3-agent/` 细节** |
71+
| **路径白名单** | — | ❌ **未指定"先读图谱，再读排期，最后读源码"的优先级** |
72+
73+
74+
### 3.2 具体错误
75+
76+
我发给 Plan Agent 的 prompt 是：
77+
78+
> "请读以下关键文件... 1. `AGENTS.md` ... 7. `main.py`, `api/index.py`, `api/unified_chat.py` ..."
79+
80+
**问题**：
81+
82+
1. **列表式平铺，无优先级分层** — 所有文件同等重要，Agent 会按顺序逐个深读
83+
2. **未引用 `_tech_graph/`** — 完全遗漏了项目设计的"快速通道"
84+
3. **未设边界** — 没有说"不要读 SPEC 细节"，Agent 自行决定深入 V3 SPEC
85+
4. **任务描述模糊** — "制定升级计划"没有定义"升级"的范围边界，Agent 试图全面理解所有 V3 功能
86+
87+
### 3.3 正确的 Prompt 应该怎么写
88+
89+
```
90+
你是 plan mode。请按以下**严格顺序**读取文件，**不要跳过步骤**：
91+
92+
【步骤 1：导航与架构（必读，不超过 5 分钟）】
93+
1. AGENTS.md — 获取项目导航规则
94+
2. docs/_tech_graph/00_main.md — 架构总览（一张 Mermaid 图）
95+
3. docs/_tech_graph/99_spec.md — 规格索引
96+
97+
【步骤 2：任务状态（必读，不超过 3 分钟）】
98+
4. docs/tasks/RECENT_TASK_SCHEDULE.md — 当前排期与 active 任务
99+
100+
【步骤 3：边界与配置（选读，不超过 3 分钟）】
101+
5. docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md — 环境变量与契约
102+
103+
【禁止读取】
104+
- docs/spec/v3-agent/ 下的任何 SPEC 文件（这些是实现细节，非计划所需）
105+
- 任何源码文件超过前 50 行（除非图谱明确指向）
106+
107+
基于以上信息，制定宏观升级计划，写入 artifacts/kimi/upgrade_plan_fallback.md。
108+
```
109+
110+
---
111+
112+
## 4. 项目文档体系的验证
113+
114+
为验证"项目侧无问题"，检查项目已有的导航设计：
115+
116+
117+
| 检查项 | 结果 | 证据 |
118+
| ---------------------------------- | --- | ----------------------------------------------- |
119+
| `AGENTS.md` 是否指引 `_tech_graph/`？ | ✅ 是 | AGENTS.md 第 1 条："3. `docs/_tech_graph/` — 架构真值" |
120+
| `_tech_graph/00_main.md` 是否存在？ | ✅ 是 | 61 行，含完整 Mermaid 架构图 |
121+
| `_tech_graph/` 是否有机器轨？ | ✅ 是 | `graph.json`（61KB）+ `_manifest.json` |
122+
| `RECENT_TASK_SCHEDULE.md` 是否含升级线索？ | ✅ 是 | §4.2 "纯后端线" 已给出执行顺序 |
123+
| 是否有规则禁止 Agent 乱读？ | ✅ 是 | `.cursor/rules/00-core.mdc` 含"修改前确认"约束 |
124+
125+
126+
**结论**：项目已经建立了"图谱优先 → 任务驱动 → 源码实现"的三层知识架构，且文档完备。Plan Agent 的失败纯粹是因为我的 prompt 没有利用这个体系。
127+
128+
---
129+
130+
## 5. 改进建议（Kimi Code 侧）
131+
132+
1. **Plan Agent 的默认 prompt 模板应强制引用 `AGENTS.md`**
133+
2. **增加"项目图谱优先"的元规则** — 类似 `tree-sitter` 的符号索引，Agent 应先查图谱再读源码
134+
3. **支持读取路径白名单/黑名单** — 如 `DO_NOT_READ: docs/spec/v3-agent/`*
135+
4. **Plan Agent 应限制单文件读取深度** — 默认只读前 N 行，除非显式需要全文
136+
137+
---
138+
139+
## 6. 修订记录
140+
141+
142+
| 日期 | 说明 |
143+
| ---------- | ---------------------------- |
144+
| 2026-06-05 | 初稿：分析 Plan Agent 超时根因，落盘完整路径 |
145+
146+

0 commit comments

Comments
 (0)