git:20261023.dd5a6e4 to git:20261024.9b44441

- > **本文件是 Agent 理解仓库和进行开发的标准指南。** 所有 Agent 在操作此仓库前必须先阅读本文件。

- > 本文件描述的是当前代码的真实状态（核对时间 2026-10-19：**仓库蓝图 R1–R6 全部落地**

- > （`docs/repo-blueprint-design.md` §21 实施记录）—— `internal/blueprint` 从零 LLM 扫描器一路做到

- > 派生快照（`atomic.Pointer` 唯一写者 + 150ms 成本自适应）、形状②常驻注入（token 硬顶 + 四态必显）、

- > `read_blueprint` 读通道、`agent_exit.blueprint[]` 写通道、五道校验 + 幂等 fold + 乐观 CAS +

- > `revisions/` 归档 + 孤儿子节老化；**验收断言就是"文件出现"**（`e2e_blueprint_test.go`：真实 Repo

- > 循环 + 真实扫描器 + 真实 guard，脚本化一轮 → `~/.yagent/data/blueprint/{projectID}/blueprint.md`）。

- > R2 的 1965 行曾经只活在两条 `agent/coding-*` 委派分支上（便签里"已落地并全绿"是真的，只是不在

- > 任何主战分支），本轮接回。仍待办：R8 导出层与

- > `/blueprint`（`[blueprint] export_path` 至今没有消费者，别写进配置指南）。

- > 2026-10-23：**外部能力接入落地**（`docs/skills-and-mcp-design.md` + 实施文档）——

- > `internal/mcp` 从"只对着 codeseek 说话的单例"升级成多 server `Manager`（`tools/list` 分页、`instructions`、

- > annotations、重连退避、四态状态账）；codeseek 成为第一个内建 server，6 个手写桥经 curated 名单保留、

- > 漏掉的 3 个工具走通用通道；外部工具以 `mcp__<server>__<tool>` 动态进 `Deps.ExternalSpecs`（一律 Cold，

- > 走既有 deferred 目录；**不进**全局注册表、golden、Meta 工具池），没 annotations 一律按写处理；

- > `internal/skills` 重写成"目录式 + front-matter + 合并语义 + 逐条账"，目录进 system prompt 稳定前缀、

- > 正文由新工具 `use_skill` 按需取回（声明面 49 → 50）；`[mcp]` / `[[mcp.servers]]` / `[skills]` 三段配置；

- > 启动期第一次真的跑 `toolspec.Validate()`；TUI 新增 `/skills`、`/mcp` 面板与类型化斜杠补全（手打

- > `/name args` 直接执行技能）。

- > 上一轮 2026-10-22：**R7 以删除收场——知识整理机制整体下架，仓库级持久知识只剩蓝图一个 sink**

- > （`internal/agents/consolidation_worker.go`、`repo_memory.go`、`knowledge_hook.go`、`internal/knowledge/`、

- > `internal/memory/{shared,local}.go`、`internal/mcp/knowledge.go`、`internal/tools/{knowledge,specs_knowledge}.go`

- > 全部删除；`consolidate_knowledge`/`prune_history` 两个工具随之从 `schemas.json` 摘掉，声明面 51 → 49，

- > 画像不再 Grant `EffectKnowledge*`；`knowledge_injected` 事件再无发布方，TUI 的消费分支一并删除）。

- > 删除的判据是"写入端活着、读取端硬关闭"——注入器 `Inject` 一直是恒真 if 提前返回，

- > 于是知识库里的东西从来进不了任何一次上下文；蓝图 + 便签已是完整闭环。

- > 自扫 golden 因此从 45 片/144 条边变成 **44 片/134 条边**（逐条归因写在 `scan_golden_test.go` 头上）。

- > 上一轮 2026-10-18：**结构化并发 C1–C6 全部落地**

- > （`docs/structured-concurrency-design.md`）—— 新增叶子包 `internal/supervise`（全仓 goroutine 的

- > 唯一落脚点：具名 + recover + 可等待），裸 `go` 由 `check_no_bare_go.sh` 硬禁；rollout 改流入队 +

- > 停点 drain；并行委派的死锁根因（executor 的并发谓词扫一份生产恒空的 `Adapters`）连根拔掉，

- > 判据收成 `toolCallIsParallelizable` 一个函数；每次委派新建 Agent 实例（`SpawnForDelegation`）

- > 并取消单槽交接；`ConversationMemory` 封装成"字段不导出、只走方法"；事件信封带上

- > `Seq` + `delegation_id` 两个坐标，TUI 流式槽按委派分。C6 才真的放量：`[llm] max_in_flight_requests`

- > 进程级在飞闸门、`[agent] max_parallel_delegations` 每轮 Run 一条委派池、

- > `YAGENT_CONCURRENCY=0` 一键回串行，外加六处"锁内 IO / 静默失效"的清理（MCP 请求 deadline、

- > 熔断 half-open 单探针、TaskManager 投递移出锁 + 终态过期、consolidation `Submit` 不再

- > send-on-closed、`FlushAll` 锁外刷、TUI 覆盖 cancel 前先释放旧值）。

- > 上一轮 2026-10-16：**配置面连根拔 + 首次使用引导**

- > （`docs/config-trim-onboarding-design.md`）—— 删掉 13 组"解析了但没人读"的键并留下

- > `removedKeyHints` 逐条点名；把 6 处"文档与代码不符"的键补成真语义（第三档真能关、压缩只剩

- > 一个开关、`step_retries` 下发到六个子 Agent、Coding 侧 `keep_plans` 取配置、补

- > `[agents.llm.browser]`、TUI 键位从"追加别名"改成"替换+释放"）；新增注释安全的 provider

- > 写回层与 `api_key_env`；`yagent setup` / TUI `/setup` / 首启自动进入的引导向导；配置坏了

- > 不再静默 `os.Exit(1)` 而是打 stderr 人话。

- > 上一轮 2026-10-15 落地"停止/继续"三层（`docs/pause-resume-design.md`）—— P1 活暂停

- > （`internal/pause` 闸门、`activity` 计时冻结、两个循环的 step 边界接入点、`paused` 停止原因、

- > TUI `/pause` `/continue` 与 HTTP pause/continue）；P2 检查点重放 B 层（`delegation_id` 串父子

- > rollout、`agent_checkpoint` 记录、`ReadRolloutForReplay`、executor 的 `ResumeState` 接缝、

- > planner 的 `PendingResumption`、八条降级判据、`[resume]` 配置）；P3 交接报告 C 层

- > （不叫 LLM 的降级报告 + `status=degraded` 便签）；再上一轮 2026-10-14 补齐核心系统单测基线，

- > 并修掉三处"错了不报错"的静默失效 —— Bedrock 配置归一化、Anthropic thinking budget、

- > 流式 tool_use 装配）。

- > 文件末尾由 codeseek 自动维护的注入区块除外。

- - [1. 项目概述](#1-项目概述)

- - [2. 技术栈](#2-技术栈)

- - [3. 模块地图](#3-模块地图)

- - [4. Agent 角色定义](#4-agent-角色定义)

- - [5. 核心工具](#5-核心工具)

- - [6. 系统架构](#6-系统架构)

- - [7. 配置系统](#7-配置系统)

- - [8. 开发与构建](#8-开发与构建)

- - [9. 编码规范与架构不变量](#9-编码规范与架构不变量)

- - [10. Director 行为准则](#10-director-行为准则)

- - [11. 已知坑](#11-已知坑)

- **Yagent** 是 Go 语言编写的多智能体 AI 编程助手，采用 **Hub-and-Spoke（中枢-辐条）** 架构：

- **Director Agent** 是唯一与用户交互的 Agent，负责分析、委派、评审；具体读写由专用子 Agent 完成。

-

- | 维度 | 描述 |

- |------|------|

- | **系统类型** | 多智能体 AI 编程助手 |

- | **架构模式** | Hub-and-Spoke + 三档上下文压缩 + Pub-Sub 事件总线 |

- | **核心原则** | 职责分离、强制委派、验证优先、可恢复 |

- | **用户接口** | TUI (Bubble Tea v2) / HTTP+WebSocket (gin+melody) / 非交互 `--prompt` |

- | **代码引擎** | `codeseek`（Rust，git submodule，经 MCP stdio 调用，二进制随 Go 程序 `go:embed` 分发） |

-

- ### 设计原则

-

- 1. **单一交互点** — Director 是唯一直接面向用户的 Agent。

- 2. **职责分离** — 每个子 Agent 有明确职责边界与权限（只读 / 可写 / 仅 Shell）。

- 3. **强制委派** — 文件与代码修改必须经 Coding-Agent，仓库探索必须经 Repo-Agent。

- 4. **验证优先** — 用 `go build` / 测试验证，不启动长驻进程。

- 5. **可追溯与可恢复** — 任务记忆（JSONL）+ 同步 rollout 日志双写，支持 `/resume` 断点续跑。

- ---

- ### 2.1 主要依赖（`go.mod`，Go **1.25.8**，模块名 `yagent`）

- | 类别 | 技术 | 用途 |

- |------|------|------|

- | CLI | `spf13/cobra` | 子命令与全局 flag |

- | LLM 抽象 | `openai/openai-go/v3` | OpenAI-compatible 协议；另有自研 Anthropic Messages 引擎 |

- | HTTP | `gin-gonic/gin` + `olahol/melody` | REST + WebSocket |

- | TUI | `charm.land/bubbletea/v2`、`bubbles/v2`、`lipgloss/v2`、`glamour/v2` | 终端界面（注意是 **v2**） |

- | 浏览器 | `go-rod/rod`（go.mod 仍声明，代码已无引用） | Browser-Agent 重构时的候选依赖 |

- | Token | `pkoukk/tiktoken-go` | cl100k_base 计数（`internal/tokenutil`） |

- | 配置 | `BurntSushi/toml` | 配置解析。**`fsnotify` 只活在 `go.mod`，Go 代码里零引用**：词典与配置都没有热加载（见 `internal/AGENTS.md` 的 dict 一节） |

- | Diff | `aymanbagabas/go-udiff` | `search_replace_in_file` 返回 unified diff |

- | 其他 | `google/uuid`、`lucasb-eyer/go-colorful`、`rivo/uniseg` | ID、配色、字宽 |

- `ripgrep`（**git 树里没有内嵌**：`dist/bin` 只跟踪一个占位文件，`internal/tools/search_operations.go:16-23`

- 回落系统 PATH；release 构建才把 rg 放进 `dist/bin`）、`fzf`（模糊搜索）、`codeseek` 二进制（默认从 `dist/bin` 解出到 `~/.yagent/bin`）、

- `browser-control`（Rust CLI，随 release 构建内嵌 `dist/bin`、启动时解出到 `~/.yagent/bin`；查找顺序 `[browser] binary_path` → `~/.yagent/bin/browser-control` → `$PATH` 不变）

- 与 Chrome/Chromium —— 两者缺一，Browser-Agent 即不可用（`delegate_browser` 描述会自动降级）。

- 两种 `api_format`：**openai**（默认，OpenAI-compatible）与 **anthropic**（原生 Messages，支持 Extended Thinking）。

- Provider 只是 base_url + api_key 的组合，因此小米 MiMo、百炼、硅基流动、DeepSeek、Moonshot、Mistral、Z.ai、OpenRouter、Anthropic 官方均可用。**没有 Bedrock 专用客户端**：`api_base_url` + `api_key` 对每个 provider 一视同仁地必填，所谓 Bedrock 配置也得指向一个 OpenAI-compatible 网关（以前按 provider 名字前缀豁免那两项，只会把失败推迟到第一次调用，见 §11 坑 14）。密钥也可以来自环境变量：`api_key_env = "DASHSCOPE_API_KEY"` 在 `validate()` 里一次性展开进 `APIKey`，之后所有消费方读的都是同一个字段。

-

- `reasoning_effort` 在两侧含义不同：**openai** 侧原样透传 `reasoning_effort` 并额外发

- `thinking={type:enabled}`（DeepSeek 思考模式要求两者都在）；**anthropic** 侧映射成 `thinking.budget_tokens`

- —— `low|medium|high|max` = 1024/8192/24576/32000，同时把 `max_tokens` 顶到 `budget+4096`、

- `temperature` 强制 1.0（provider 在思考模式下拒绝其它值）。**认不出的取值一律当作"没开思考"**：

- 以前会把 `budget_tokens: 0` 发出去，而 provider 要求 ≥1024，一个拼错的 effort 就让此后每次调用都 400。

-

- provider 的 `max_tokens` / `temperature` 是**引擎级默认**，优先级为

- `单次 CallOptions > provider 配置 > 不发这个字段`（anthropic 侧未配时兜底 8192，因为 Messages API 必填）。

- 两个引擎的构造函数收的是 `*config.ProviderConfig` 而不是散参数——散参数时每往 `ProviderConfig`

- 加一个键就多一处"配置写了但没人读"，而 `max_tokens` 曾经正是这样失效的（请求体里根本没有它，

- thinking 模型因此能一口气生成 39k token）。**`0` 一律按"没配"处理**：`ProviderConfig.Temperature`

- 是裸 `float64`，分不清"写了 0.0"和"没写"，而显式发 `temperature: 0` 会把服务端默认采样顶成贪心解码。

- 钉住这套形状的是 `engine_openai_test.go:TestOpenAIEngine_ProviderDefaultsReachWire` 与

- `engine_anthropic_test.go:TestAnthropicBuildRequest_ProviderDefaults`。

-

- ---

-

- ## 3. 模块地图

-

- ```

- yagent/

- ├── main.go # cobra 入口：tui(默认) / http；--prompt -f -p -d -c -y -Y -Q

- ├── embed.go # //go:embed dist/bin/* + dist/data/models.json

- ├── build.sh # Rust(codeseek) + Go 一体构建（release 默认）

- ├── internal/

- │ ├── agents/ # Agent 实现（根包 = 具体 Agent + 通用循环）

- │ │ ├── director.go # Director（门面；编排逻辑在 director/ 子包）

- │ │ ├── coding.go repo.go chat.go devops.go browser_agent.go meta.go

- │ │ ├── executor.go # RunAgentLoop：所有子 Agent 共享的 LLM-工具循环

- │ │ ├── specs.go # Agent 侧工具的注册表声明（checkpoint/delegate_*/read_*）

- │ │ ├── ports.go # 窄接口：切断 agents ↔ 子系统的循环依赖

- │ │ ├── result.go # 子 Agent 结果 finalize / FormatForDirector

- │ │ ├── activity/ # 活动感知 idle/total timeout（Heartbeat / WithIdleTimeout / Pause / Resume）

- │ │ ├── director/ # Planner、Meta 注册表、项目上下文加载、熔断状态、指标

- │ │ ├── toolbatch/ # 只读工具并行分批调度（无业务依赖的叶子包）

- │ │ ├── git_checkpoint.go # 每个编码子任务的 git 快照/回滚

- │ │ ├── resume_state.go # 重放接缝（B 层）：WithResumeState(ctx) → RunAgentLoop 从第 N 步续跑

- │ │ ├── checkpoint.go # 子 Agent 停止时落 agent_checkpoint 的薄封装

- │ │ ├── resume_delegation.go # 恢复侧编排（B+C）：delegation_id 扫描、八条判据、降级交接报告

- │ │ └── *.prompt.md # 各 Agent 的 System Prompt

- │ ├── app/app.go # Yagent：一次性装配 MCP/工具引擎/守卫/子 Agent/Director

- │ ├── browserctl/ # 浏览器执行层：外部 browser-control CLI 的进程/工作区/URL 策略/渲染

- │ ├── blackboard/ # 跨 Agent 便签：note(存储) / handoff(结构化交接) / index(派生索引)

- │ │ # resolve(ContextPack) / gc(生命周期) / board(路径与原子写)

- │ ├── blueprint/ # 仓库蓝图（R1–R6 已落地，docs/repo-blueprint-design.md v4 + §21 实施记录）：

- │ │ # scan*.go 零 LLM 扫描器（43 片/137 条边的自扫 golden）；derive.go 的

- │ │ # 派生快照（atomic.Pointer 唯一写者 + 成本自适应）；index.go 形状②渲染

- │ │ # （token 硬顶 + stale/unannotated/TRUNC/oversize 四态）；prose.go 按需视图；

- │ │ # fold.go/merge.go/commit.go 五道校验 + 幂等 fold + 乐观 CAS + revisions/；

- │ │ # freshness.go 结构指纹与三态锚点；gc.go 孤儿子节老化。

- │ │ # 叶子包（只用标准库 + util + projectid，check_blueprint_leaf.sh 守：

- │ │ # gitinfo/tokenutil 由装配层做成参数传进来，不 import）；

- │ │ # 启用判据是 config.BlueprintEnabled()（本包不读环境变量）

- │ ├── projectid/ # 项目绝对路径 → 文件系统安全的目录名（rollout / artifact / 蓝图共用一把主键；

- │ │ # director.ComputeProjectID 现在只是转发，TestComputeProjectID 仍钉着具体串）

- │ ├── artifact/ # 超预算委派结果的落盘存储 + 摘要

- │ ├── compression/ # 三档上下文压缩（rule / emergency / ultimate）

- │ ├── config/ # TOML 加载 + 三级 provider 解析；persist.go 的 SetKeyInSection 是

- │ │ # 唯一写回内核（文本级保注释），setup.go 是 provider 写/删 +

- │ │ # 首启判据（NeedsSetup / IsPlaceholderKey / api_key_env 展开）

- │ ├── datamanager/ # 任务记忆 JSONL（5s 防抖）+ 索引

- │ ├── dict/ # 补全词典（只在 TUI 构造时加载一次，无热加载）

- │ ├── diff/ # unified diff

- │ ├── embedbin/ # 从 embed FS 解出二进制（MD5 校验，版本化）

- │ ├── globalctx/ # 全局上下文（EnvView / RepoContextStore 两个并发视图）。

- │ │ # 没有 Version/BuildTime/GitCommit 三个字段——build.sh 的 -X 注入的是空气

- │ ├── http/ # gin REST + melody WebSocket + TaskManager

- │ ├── llm/ # Engine 接口、OpenAI/Anthropic 引擎、Fallback、Router

- │ ├── logging/ # slog 全局日志 + 按任务分目录

- │ ├── mcp/ # stdio JSON-RPC 客户端 + 多 server Manager（tools/list 发现、重连、状态账）

- │ ├── memory/ # ConversationMemory、rollout 读写（断点续跑的数据源）

- │ │ # rollout_replay.go(重放+指纹) / rollout_checkpoint.go(坐标+工作区) / rollout_ctx.go(delegation_id)

- │ ├── messaging/ # 事件总线（Dispatcher / Publisher / consumers/）

- │ ├── models/ # 模型目录（dist/data/models.json）：context window + benchmark

- │ ├── protocol/ # 由 protocol/agent-events.yaml 生成的事件类型

- │ ├── pause/ # 暂停闸门（A 层）：Gate + ctx value + AbandonedError，只依赖 activity

- │ ├── recovery/ # LLM 熔断器

- │ ├── skills/ # 技能注册表：目录式/扁平 SKILL.md、front-matter、合并语义、use_skill 读通道

- │ ├── supervise/ # 全仓 goroutine 的唯一落脚点：具名 + recover + 有人等（C1，

- │ │ # docs/structured-concurrency-design.md）。叶子包（只依赖标准库，

- │ │ # check_supervise_leaf.sh 守）；裸 `go` 由 check_no_bare_go.sh 禁掉

- │ ├── thinklink/ # 结构化 <thought> 解析 + 思维日志（驱动 ultimate 压缩）

- │ ├── tokenutil/ # tiktoken 封装（EstimateTokens）

- │ ├── tools/ # 工具 Adapter 实现 + workspace_guard + user_confirm

- │ ├── tui/ # Bubble Tea v2 界面（82 个文件）

- │ │ ├── setup*.go # 引导向导：状态机+落盘队列 / 按键与表单行规格 / 外壳 / 七屏正文 /

- │ │ │ # 端点预设 / 嵌入主 model（docs/setup-wizard-ui-design.md）

- │ │ ├── tui_keymap.go # [tui.keybindings] → 按键翻译表（替换语义，见 §11 坑 29）

- │ │ ├── anim/ common/ components/ layout/

- │ └── util/ # 崩溃上报等；atomic.go 是全仓唯一的 tmp+rename 落盘内核（I21）

- ├── protocol/ # agent-events.yaml（SSOT）+ 生成的 go/ 与 ts/ 副本

- ├── scripts/ # build-centos7 / build-extension / protoc-gen-yagent

- │ # + 九把守卫（check_*.sh），其中 check_all.sh 是一条命令的本地闸门

- ├── patches/ # CI 用的 vendored-openssl 补丁

- ├── dist/ # 构建产物 + 被跟踪的 models.json（见 §11 坑 2）

- ├── codeseek/ # git submodule → iohub/codeseek（Rust 代码智能引擎）

- └── docs/ # ARCHITECTURE.md / config-guide.md / 设计稿

- ```

- ### 3.1 模块知识文档（嵌套 `AGENTS.md`）

- `internal/` 下 15 个模块目录各有一份**局部** `AGENTS.md`，加上导览 `internal/AGENTS.md` 共 16 份。

- 局部文档写的是"在这个目录里改代码之前必须知道、而又派生不出来"的东西：职责边界（尤其不负责什么）、

- 硬约束、历史坑、入口文件、钉住不变量的测试函数名。

- 新增这类文档会让蓝图扫描器把它们计入所在目录的 md 文件数（**只数不读**，`agents.md` 出现在

- `internal/blueprint/freshness.go:47` 只是"这个 token 像路径"的词表，没有特殊处理）。

- | 约定 | 内容 |

- |------|------|

- | **什么时候读** | 进任何目录动手之前先看它有没有 `AGENTS.md`；没有局部文档 = 该目录没有不可派生的知识，直接读代码。导览表在 `internal/AGENTS.md` |

- | **写什么** | 只写机器派生不出的：边界、禁令、坑、入口、闸门 |

- | **不写什么** | 模块列表 / 文件计数 / 依赖边 / 每个模块有哪些文件——这些由 `internal/blueprint` 每轮派生，抄进文档就是第二份会漂走的事实 |

- | **与根文件的分工** | 根 `AGENTS.md`（本文件）讲跨模块的架构、流程与全局不变量；局部 `AGENTS.md` 讲"在这个包里怎么做会静默坏掉"。**同一句话不要同时写在两处** |

- | **引用格式** | 每条约束带 `internal/<包>/<文件>.go:行` 或测试函数名，让读者能跳过去核实；仓库根文件（`main.go`、`embed.go`、`build.sh`）按根路径写 |

- | **谁加载它** | yagent 运行时的 `internal/agents/director/project_context.go:53` 只读工作区根的 `YAGENT.md`/`CLAUDE.md`/`AGENTS.md`，**不递归**——所以嵌套文档今天只服务于读代码的人与 coding agent，运行时子 Agent 读不到 |

- > 2026-10-21 随这批文档一起做了一次事实核对，顺手改掉了根文件里五处与代码不符的描述：

- > `fsnotify` 热加载（Go 代码零引用）、`globalctx` 的三个版本字段（不存在，但 build.sh 还在 `-X` 注入）、

- > "ripgrep 已内嵌"（git 树里只有占位文件）、注入器硬关闭的位置（当时是 `internal/knowledge/injector.go:74-78`，

- > 不是 `:67-71`；整个包已于 2026-10-22 随知识机制删除）、

- > 行数棘轮的 PENDING 上限（`planner_run.go` 是 **572 行**，不是 658）。

- > 旧的 `pkg/messaging/` 已迁到 `internal/messaging/`；`internal/compact/` 已重构为 `internal/compression/`。

- ---

- 所有 Agent 实现 `Agent` 接口（`internal/agents/types.go:39`），由 `internal/app/app.go:398-522` 统一构造。

- 每个 Agent 的 System Prompt 是同目录的 `<name>.prompt.md`，改动行为请同时改 prompt 与代码。

-

- | Agent | 文件 | 定位 | 权限 | Max Steps 默认 |

- |-------|------|------|------|----------------|

- | **Director** | `director.go` + `director/` | 项目经理/技术主管，唯一对话入口 | 只读 + 委派 | 100 |

- | **Coding** | `coding.go` | 高级开发工程师 | 完整读写 + Shell | 150 |

- | **Repo** | `repo.go` | 架构师/审计员 | 只读 + 可委派 DevOps | 50 |

- | **Chat** | `chat.go` | 通用问答 | 无文件系统访问 | 50 |

- | **DevOps** | `devops.go` | 系统管理员 | 只读 + Shell | 50 |

- | **Browser** | `browser_agent.go` | 网页操作：经外部 `browser-control` CLI 驱动真实 Chrome | 浏览器动作 + 会话工作区产物（无 Shell、无文件写工具） | 200 |

- | **Meta** | `meta.go` | 自定义 Agent 设计器 | 无工具，单次 LLM 出 JSON | —（无 step 循环；重试 5） |

- | **Custom** | `internal/agents/director/types.go:60` | Meta 设计后运行时注册 | 由 LLM 选择的子集 | 15 |

-

- **Director 工具**：由画像 `toolspec.ProfileDirector` 派生（`internal/toolspec/profiles.go:24-39`，

- 装配点 `internal/agents/director_surface.go:97-98`）——`delegate_*` + `agent_exit`、`read_artifact`、`read_note`、`list_notes`、`deepthinking`、`ask_user_for_help`，

- 以及只读分析工具（`read_file`、`search_by_regex`、`list_dir`、`print_dir_tree`）。

- `Deny: EffectFSWrite | EffectShell` 是"Director 绝不直接写文件"的机械保证，不再依赖一份手写的工具清单。

-

- **Coding 工具**：`create_file`、`search_replace_in_file`、`delete_file`、`rename_file`、`list_dir`、`print_dir_tree`、

- `read_file`、`search_by_regex`、`run_bash`、`thinking`/`micro_agent`/`deepthinking`/`design`、

- `semantic_search`/`query_code_skeleton`/`query_code_snippet`/`find_function_callee`/`find_function_caller`、

- `git_checkpoint_*`（仓库+配置开启时）、`delegate_browser`、`agent_exit`、`ask_user_for_help`。

-

- **Repo 工具**（只读，含调用图）：`read_file`、`search_by_regex`、`list_dir`、`print_dir_tree`、

- `semantic_search`、`query_code_skeleton`、`query_code_snippet`、`find_function_callee`、`find_function_caller`、

- `query_call_graph`、`deepthinking`、`delegate_devops`、`agent_exit`。

-

- **Browser 工具**（14 个，能力标签在注册表、argv/render 在 `tools/browser_operations.go` 的 spec 表，schema 在 schemas.json）：

- `browser_status`、`browser_open`、`browser_inspect`、`browser_snapshot`、`browser_click`、`browser_fill`、

- `browser_type`、`browser_press`、`browser_scroll`、`browser_select`、`browser_tabs`、`browser_wait`、

- `browser_screenshot`、`browser_eval`，外加 `agent_exit` / `ask_user_for_help`。

- `browser_eval` 仅对敏感 JS（cookie/存储/网络请求/提交表单/动态执行）要求授权；截图路径由工具层收敛到会话工作区。

- 能力不可用时 `delegate_browser` 的描述会降级为"不可用 + 原因 + 修复方式"（见 `browserDelegateDescription`）。

- 完整设计见 `docs/browser-agent-design.md`。

-

- > **工具注册已收归注册表**（`internal/toolspec`，见 `docs/tool-registry-design.md`）：每个工具在实现旁边

- > `MustRegister(Spec{...})` 声明能力标签/频率档/授权要求/执行器，Agent 侧只写一份**能力画像**

- > （`toolspec/profiles.go`），装配统一走 `tools.NewSurface(profile, deps)`。

- > 七个 Agent（Director + 六个子 Agent）**全部**走这条路，`lookupToolFunc`/`getToolFunc` 已删除；

- > `scripts/check_no_manual_lookup.sh` 是棘轮守卫（PENDING 名单已清空，往里加条目必须评审）。

-

- ### Meta / 自定义 Agent 注册流程

-

- ```

- delegate_meta → MetaAgent 单次 LLM 出 JSON → ParseMetaAgentOutput (internal/agents/director/meta_handler.go:100)

- → 校验必填字段 → 按名字建 delegate_<snake_name>（registerCustomAgent，internal/agents/director_surface.go:284；

- 工具子集由 ProfileDirector.Palette 选，同文件 :263）并追加到 Director 工具表

- → 立即以 MaxSteps=15 执行一次 → 新 Agent 在本任务内永久可用（写进 system prompt 的清单）

- ```

- ---

- ## 5. 核心工具

- ### 5.1 Adapter 模式

- ```go

- type ToolFunc func(ctx context.Context, params map[string]interface{}) (interface{}, error)

- type Adapter struct { name, description string; fn ToolFunc

- schema map[string]interface{}; guard *WorkspaceGuard; readOnly bool }

- ```

- `internal/tools/adapter.go`：`NewAdapter` + `WithSchema` / `WithReadOnly` / `WithReadOnlyIfKnown`；

- `Call()` 依次做 JSON 解析 → 工作区边界检查 → 危险操作授权 → 执行；`ToToolDef()` 产出 `llm.ToolDef`。

- `SortToolDefs` / `ComputeToolDefsHash` 保证工具顺序稳定（利于 provider 端 prompt 缓存）。

- **并行性判定**：`Adapter.IsReadOnly()`（由 `Spec` 的 `!Mutates && !Serial` 派生）为真、且不在

- `toolspec.IsSerial` 名单里的工具，

- 可由 `toolbatch` 分批并行执行（默认并发 4，上限 8，`[agent] max_parallel_readonly_tools`）。

- `read_note` / `read_artifact` / `list_notes` 与认知类、调用图工具都走这条派生路径。

- **委派是另一道闸门**：`delegate_*` 在子 Agent 侧一律 `Serial`（所以一次只跑一个），

- Director 侧的只读委派可以并发，但同时跑几个由 `[agent] max_parallel_delegations` 决定 ——

- 池子建在**这一轮 Run 的 `directorToolRunner`** 上（`newDirectorToolRunner` 是唯一构造方式），

- 不是进程级：嵌套委派（Repo→`delegate_devops`）用的是自己那一轮的池，

- 于是"父占一格、子在同一格里排队"的死锁形状从结构上不存在。

- 判据是**一个函数**：`agents.toolCallIsParallelizable(surface, name)`（`executor.go`），

- Director 的 `isToolParallelizable` 与子 Agent 循环都调它 —— 两份同形判据的历史代价见 §11 坑 33。

- 冷工具（还没取回 schema）也算可并行：它在这一批里只收到 teach 回执、不执行副作用。

- 闸门是 `TestDerivedMetadataMatchesLegacyTables`：新增可并发工具必须进 `signedReadOnlyAdditions` 或 `newTools`

- 集合并写明理由，否则测试直接红 —— 那两处集合就是"公开承认我扩大了并发面"的地方。

- 另外 `TestParallelAdmission_*`（`parallel_admission_test.go`）是拿**真实画像**

- （`ProfileRepo` / `ProfileCoding` / `ProfileChat`）问这个判据的，所以画像或能力标签漂走时会红；

- 自己拼一个工具列表来测等于重犯坑 33。

- ### 5.2 工具总览（schema 见 `internal/toolspec/schemas.json`，50 条 + 运行期动态外部工具）

- > 每个工具的完整契约 = `schemas.json` 的 description/parameters + `Spec` 的能力标签。

- > 派生查询：`IsReadOnly` / `IsSerial` / `NeedsAuth` / `PathParams` / `TruncationPriority` /

- > `IsInteractive` / `IsCompactDisplay` / `ModelSlot`。

- | 工具 | 类别 | 说明 |

- |------|------|------|

- | `read_file` `list_dir` `print_dir_tree` `search_by_regex` | R | 只读文件与 ripgrep 搜索 |

- | `create_file` `delete_file` `rename_file` `search_replace_in_file` | W/D/M/E | 文件写；替换强制唯一匹配并返回 diff |

- | `run_bash` | S | Shell；`is_background` / `is_dangerous` |

- | `semantic_search` `query_code_skeleton` `query_code_snippet` | R | codeseek MCP 桥 |

- | `find_function_callee` `find_function_caller` `query_call_graph` | R | 调用图；改函数前**必须**先查 callers |

- | `thinking` `micro_agent` `deepthinking` `design` | C | 反思 / 隔离子 LLM 推理 / 多步深度思考 / 编码前设计闸门 |

- | `agent_exit` `ask_user_for_help` | P | 结束任务（可带 `handoff{conclusion,facts[],open_questions,status}`，见 §6.4；另有 `blueprint[]` 写入通道，只有 Repo 的完成接缝会落盘，见 §6.4）/ 反问用户（confirm、select、input 三种交互） |

- | `git_checkpoint_create` `git_checkpoint_list` `git_checkpoint_rollback` | G | 编码子任务快照 |

- | `read_note` `read_artifact` `list_notes` | R | 读跨 Agent 便签（handoff 块 + 分页正文）/ 超预算产物全文 / 枚举整块板上有哪些结论（boardID 存在时自动注入，`list_notes` 刻意不含正文） |

- | `use_skill` | R | 按名取回用户技能的完整正文（front-matter 事实 + 分页），skill 目录在 system prompt 里常驻。没有技能时回执自带"放哪儿"的修复指引，不从工具面消失 |

- | `read_blueprint` | R | 读仓库蓝图：`section/module/field/state` 收窄 + `offset/limit` 分页。**六个画像**都拿得到（`EffectContext` 已 Grant），没有蓝图时回执自带原因与修复方式（不静默摘工具）。目录→目录归它，符号→符号归 codeseek |

- | `browser_status` `browser_open` `browser_inspect` `browser_snapshot` `browser_click` `browser_fill` `browser_type` `browser_press` `browser_scroll` `browser_select` `browser_tabs` `browser_wait` `browser_screenshot` `browser_eval` | 浏览器 | 经外部 `browser-control` CLI 驱动真实 Chrome；Browser-Agent 持有（详见 `docs/browser-agent-design.md`） |

- | `delegate_repo/coding/chat/devops/browser/meta` | 委派 | Director 持有；`delegate_browser` 也在 Coding 上（能力不可用时描述自动降级） |

- > **不存在** 名为 `flow_control` 的工具（旧文档有误）；流控制由 `agent_exit` 与 `ask_user_for_help` 承担。

- ### 5.3 MCP、外部工具与 codeseek

- - `internal/mcp` 是自研 stdio JSON-RPC 2.0 客户端 + **多 server `Manager`**：`tools/list`（跟随

- `nextCursor` 分页）、`initialize.instructions`、`tools/call`、重连退避、状态账四件事都在这一层。

- 传输层（`client.go` 的 `sendJSON`/`doRequest`/`readLoop`/`IsAlive`）没有改。

- - **codeseek 是第一个内建 server**。6 个手写桥（`semantic_search` 等）原样保留（结果整形 + `ErrIndexBuilding`

- 降级文案），服务端名进 curated 名单，不再以 `mcp__codeseek__*` 重复注册；`codeseek_init/status/list`

- 经通用 `tools/list` 成为动态工具。

- - **外部工具不进全局注册表**（`toolspec` 仍是 `init()` 期写入的只读事实）：它们从

- `Deps.ExternalSpecs` 进 `Surface.rebuild()`，名字是 `mcp__<server>__<tool>`，一律 Cold（走既有

- deferred 目录 + `load_tool`）。三条理由见 §11 坑 44。

- - 副作用判定：`readOnlyHint=true`（或配置 `read_only` 名单）⇒ 只读可并发；明确 false/destructive ⇒ 写；

- **没有 annotations 一律按写处理**（`Mutates`+`Serial`+`NeedsAuth`），写类默认不注册，除非 `allow_write = true`。

- - 状态五档 starting / ready / degraded（进程活着但没拿到清单）/ offline / disabled，一段文本三处出口

- （启动日志、`/mcp` 面板、Director 的 system prompt），由 `mcp.RenderStatusLines` 单源渲染。

- - **启动不等 MCP**：`Manager.Start` 只同步 spawn 子进程（`Client("codeseek")` 当场可取，

- 手写桥捕获的就是这个指针），initialize 与 `tools/list` 在后台跑。initialize 的预算是 15 分钟

- 而不是 `startup_timeout` —— 判死并重开等于让冷索引从头再建。

- | 机制 | 位置 | 实际行为 |

- |------|------|----------|

- | **WorkspaceGuard** | `tools/workspace_guard.go` | 危险工具（create/edit/delete/rename/run_bash）路径必须落在工作区内；会话/项目级放行记录在 `~/.yagent/settings.json` |

- | **UserConfirmManager** | `tools/user_confirm.go` | 走事件总线的 pub-sub 授权：发 `user_help_needed`，等待 `user_help_response`（按 `request_id` 配对） |

- | **run_bash 纵深防御** | 同上 | 无黑名单；信任 LLM 的 `is_dangerous` + 任何指向工作区外的绝对路径 token 都要求授权（`safeSystemPaths` 例外） |

- | **大小限制** | `tools/file_*` | 编辑双向 10MB；整读 10MB、软警告 2MB、单次 1000 行 |

- | **YOLO** | `-y` / `-Y` | `--yolo` 跳过工作区内授权；`--full-yolo` 连工作区外路径也放行，并移除 `ask_user_for_help` |

- | **分层守卫** | `agents/ports.go` + `scripts/` | 子 Agent 需要的依赖经窄接口注入；`director/` 子包禁止 import `internal/agents`（防循环） |

-

- ---

- ### 6.2 执行循环

- - **子 Agent**：`RunAgentLoop(ctx, ExecutorConfig)`（`internal/agents/executor.go:219`）。

- 每步：LLM 重试（指数退避 ≤30s）→ 三档压缩检查 → 带 `llmTimeout` 的 LLM 调用 → 抽取 `<thought>` →

- 纯文本回复则注入提醒或结束 → 工具调用交给 `toolbatch` 分批并行 → `agent_exit` 立即返回；

- 步数耗尽报错，panic 被 recover 并写 `turn_aborted` rollout。

- `ExecutorConfig` 关键字段：`SystemPrompt / UserInput / Surface / LLM / MaxSteps / Publisher / StopOnFinish /

- LLMTimeout / StepRetries / SystemAsHuman / NoActionRetryLimit / MaxParallelReadOnlyTools / OnAgentStart / OnAgentExit`。

- `Surface` 是**唯一**的工具来源（`Adapters` 字段已删除，见 §11 坑 33）：工具声明、按名解析、并发准入都只问它。

- `StepRetries` 现在由各 Agent 从 `[llm] step_retries` 带进来（以前全仓无写入点，六个子 Agent 恒为 0）。

- 纯文本收尾的提醒有**两条文案**：通用那条（"立刻调用工具去 explore/edit/run/verify"，Coding 那类

- 执行型 Agent）与 `cfg.NoActionReminder` 覆盖版（Repo 用收尾契约"Call `agent_exit` now + 填 handoff +

- 本轮打开过的目录补 blueprint[]"）。理由见 §11 坑 41：对以报告为交付物的分析型 Agent，

- 催它"再去执行一轮"是把已经做完的分析重做一遍。`NoActionRetryLimit` 历史上只有 Coding 设（2），

- Repo 现在设 1。

- `OnStepEnd` 已删除：自动检查点的钩子早没了，它唯一的作用是在 `AutoCheckpoint=true` 时

- 每步打一条 deprecation 警告。顺带修好一件事 —— `sub_agent_activity` 这条 rollout 记录以前

- 挂在那个钩子里，于是**只有"Coding + git checkpoint"那一条路径**会写步数事实，

- 其余子 Agent 的 `/resume` 步数只能靠 assistant 轮次猜；现在它在每个有工具调用的 step 都写。

- - **Director**：自己的 `director.Planner`（`director/planner_run.go`），额外有熔断器、

- 未委派提醒（最多 3 次强制委派 nudges）、`activity.WithIdleTimeout` 包裹的委派超时

- （`[agent] delegate_idle_timeout` / `delegate_total_timeout`）。

- - **暂停闸门（A 层，`docs/pause-resume-design.md`）**：两个循环的 step 边界各有一行

- `pause.From(ctx).Wait(ctx)` —— 子 Agent 在 `executor.go` 循环体开头（`stepNumber++` 之前），

- Director 在 `planner_run.go` 循环体开头（`p.state.Step = i + 1` 之前）。闸门挂在任务 ctx 上

- （`internal/pause`，`http.NewTaskContext` 建、`http.Task.Gate()` 读回），嵌套委派自动继承。

- `Wait` 对 nil receiver 安全：没有闸门的调用点（测试、`--prompt`）一行都不用改。

- 与取消的区别：闸门**不取消** ctx，所以恢复后是从阻塞点原地继续，而不是"一次失败的委派"

- （`AGENTS.md` §11 坑 17）。暂停期间 `activity` 的 idle 与 total 计时都被冻结

- （`Heartbeat` 只能续 idle —— total 的起点是创建时固定的）。

- - **检查点（B 层，`memory/rollout_checkpoint.go` + `agents/checkpoint.go`）**：两个循环各自在

- **终止路径**上落一条 `agent_checkpoint`（子 Agent 在 `executor.go` 的 deferred 终止块里、

- Director 在 `director/planner_rollout.go` 的 `aborted`/`checkpoint`），**不是每步一条** ——

- 每步一条会把 200 步的会话写成 200 条坐标，而重放只需要最后一个停点。

- 坐标里只存派生不出来的东西（step 游标、指纹、模型/档位、工作区 sha+dirty、`delegation_id`）；

- 消息正文、已取回的冷工具、thinklink T&P 块**刻意不存**，因为存了就会与代码漂移

- （见 `rollout_types.go` 的 `AgentCheckpoint` 注释）。写与读共用 `memory.WriteCheckpoint`，

- 父子两个写入包不能互相 import，所以这里只留一份实现。

- - **重放接缝（B 层，`agents/resume_state.go`）**：`memory.WithDelegationID` 把 Director 那次

- `delegate_*` 的 `tool_call_id` 挂到委派 ctx，子 Agent 的 rollout 文件名带 `_{agent}` 后缀、

- `session_meta` 带 `delegation_id` + `parent_session_id`，父子就此串起来（`ScanDelegationStops` 反查）。

- `ReadRolloutForReplay` 从子文件忠实重建（含 `Reasoning` 与工具全文，`compacted` 记录会替换被压过的前缀），

- 再以 `WithResumeState(ctx, *ResumeState)` 交回 `RunAgentLoop`：起点是 `StartStep` 而不是 0，

- **不重写 system/user rollout**（续写会开新文件，靠 delegation_id 认亲），`Materialized` 回填

- `Surface.RestoreMaterialized`（模型不必再 `load_tool` 一次），thinklink 经 `Seed` 复原（否则第三档压缩

- 只能拿原始任务输入重建）。走 ctx 而不是给 `ExecutorConfig` 加字段：六个子 Agent 一行都不用改，

- 也就不存在"漏改一个 Agent、那条路径的恢复静默失效"。

- - **恢复不经过模型（D7）**：`Director.Run` 在 `planner.Run` **之前**处理 `pendingResumption`，

- 把结果作为**第二条 tool output（同一个 `call_id`，last-wins）**交回（`planner_run.go` 的

- `PendingResumption` 提交块），零 token、确定性。让模型决定怎么恢复的后果是"同样的停点有时重做、

- 有时接着跑"，不可复现比不能恢复更难排查。

- - **降级交接报告（C 层，`agents/resume_delegation.go`）**：`assessReplay` 是"不需要真跑一次就能判"的判据

- （无子 rollout / 重读失败 / 无检查点 / 指纹不符 / 消息数不符 / 重放即超预算 / 工作区移动 / browser 委派 /

- max_steps 耗尽 / 超时停的），任一命中就改用**程序生成的**降级报告（不叫 LLM）交回 Director，

- 并写一张 `status=degraded` 的便签把降级原因留在板上。报告分三段来自账目本身：已完成、未完成的计划项、下一步建议。

- ### 6.3 路由（auto-routing）

- `internal/llm/router.go` 的 **RoutingEngine** 包裹每个 Agent 的引擎，按任务难度把调用路由到

- **fast / balanced / high** 三档模型之一：`Client.BuildRouter` 用模型目录里的 benchmark 分数为每个 provider

- 建三档引擎；`Classify` 用 fast 模型输出 `{"tier": ...}`（30s 上限，失败回落到该角色的 baseline）；

- 档位通过 context 传递，在 `RunAgentLoop` 里由 `ResolveTierEngine` 解析。

- `[routing] mode = "auto" | "fixed"`，`baselines` 可为 director/coding/repo/chat/devops/browser/meta 指定默认档。

- **优先级：TUI 运行时覆盖 > 路由档位 > 配置里的 `[agents.llm.*].use_provider`。** 手动选过一次模型是显式意图，

- `RoutingEngine.resolve` 先查覆盖表再查档位；`routeCtx` 据此跳过 `Classify`（省一次 LLM 调用）也不发那条描述未使用档位的

- `model_routed`。配置的静态 use_provider 仍让位给档位。

- **运行中换模型不需要任务空闲**（`Alt+M` / `:model`）：`RunAgentLoop` 在入口就把 `RoutingEngine` 解成具体引擎，

- 所以子 Agent 在**下一次委派**换新引擎，Director 每次调用现场解析（下一个 step 即生效），正在飞的那次调用不变。

- 代价是几个引擎指针现在会被并发替换：`Client.Engine` 只能经 `DefaultEngine()` 读、`Yagent.engine` 只能经

- `defaultEngine()/setEngine()` 读写、deepthinking/design 的引擎只能经 `SetEngine()` 换。

- > 坑：任何重建 Agent 引擎的地方都必须保留 `*RoutingEngine` 包装，否则 auto-routing 静默失效（commit 0c87c8a）。

- > 这条契约由 `internal/app/assembly_test.go:TestAgentEngineAlwaysWrapsWithRoutingEngine` 钉住 ——

- > 它只看返回类型，不驱动 `resolve()`（后者要真实 provider，属于 `internal/llm` 的测试范围）。

- - **Blackboard**（`internal/blackboard`，完整设计见 `docs/blackboard-handoff-design.md`）：每次委派的结果写成一张便签

- `~/.yagent/notes/{boardID}/{agent}/{stem}.md`，**正文是交付物全文**（以 `agent_exit` 收尾的 Agent，全文取最后一条 assistant 消息，

- 不是那句 reason）。front-matter 带 `Handoff`（`conclusion` / `facts[]{claim,where}` / `open_questions` / `status`），

- schema v2；读 v1 存量便签时自动从 `Summary` 合成并标 `degraded: v1`。

- - **索引是派生态**：`BuildIndex` 每轮从磁盘重扫，注入 Director 的**每一轮**上下文与每次委派的任务前缀；

- 它**只进 LLM 调用的 messages**，绝不写进 `ConversationMemory` 或 rollout —— 这是它能扛住上下文压缩的唯一原因

- （压缩动的是会话历史里的 tool 消息，`note:`/`artifact:` 引用以前就是这么蒸发掉的）。

- - `context_refs` 的语义是**强调**（额外内联全文），不是准入：不传也能从索引发现。`agent:` 前缀认 `repo` 与 `repo_agent` 两种写法，

- 取不到必须计入 `unresolved` 并在结果头显示。

- - **board 作用域 = session**（`SetBoardScope(sessionID, taskID)`）：同一 TUI tab / 同一 HTTP chat session 内多次任务共享一块板；

- `/resume` 靠 `session_meta.board_id` 重连旧板，存量 rollout 回落 taskID。

- - 三个读回工具：`read_note`（handoff 块 + 分页正文）、`read_artifact`（分页全文）、`list_notes`（整板目录，只给一行结论不含正文）。

- - `handoff.status` 词表 `ok | error | degraded`（+ LLM 可自报的 `partial`）。**只有 `ok`/`partial`/`error`

- 出现在 `agent_exit` 的枚举里**：`error` 由委派错误判定、`degraded` 由重放侧按降级判据判定，

- 让模型自报"我这份是降级的"等于把判断交给自己看不到判据的一方 —— 所以 `toolspec` golden 没动。

- 词表里**刻意没有 `paused`**：被闸门 abandon 的委派零交付物，`writeDelegateNote` 在那条路径上

- **什么都不写**（写了就是一张空正文便签，还会占住每轮重扫的索引位去冒充一条结论），

- "停在第几步"由 rollout 的 `stop_reason` + `agent_checkpoint` 记账，恢复成功后才落便签。

- - 预算与 GC 在 `[blackboard]`。三个阀门靠**键的存在性**判定（不是零值）：`index_max_notes = 0` 关索引、

- `index_line_chars = 0` 不裁剪行、`ttl = "0"` 不清理；`summary_max_runes` 与 `max_notes_per_board` 的 0/负数一律归默认

- （它们没有"关"的语义，放宽就写大数字）。整体关闭仍是 `YAGENT_BLACKBOARD=0`（`blackboard.Enabled()` 是唯一判据，

- 写/读/注入/清理四处共用）。

- - **Artifact**（`internal/artifact`）：超过预算（默认 500 token）的委派全文落盘 `~/.yagent/data/artifacts`，

- 上下文里只留摘要 + ID（摘要优先来自 handoff，缺 handoff 时逐字回落到正文前缀），Director 用 `read_artifact` 分页取回。`YAGENT_ARTIFACT_DISABLE=1` 关闭。

- - **Blueprint**（`internal/blueprint`，设计稿 `docs/repo-blueprint-design.md` v4 + §21 实施记录）：仓库级导航知识的

- **唯一有机械新鲜度判据**的一套，也是**唯一**的仓库级持久知识 sink（2026-10-22 起：KV 仓库记忆与

- codeseek 知识注入/沉淀整体删除）。两层内容、一份文档：**派生的不落盘，落盘的不派生**。

- - 派生层（内存，每次现算，本仓实测 6.6ms）= 模块集合 / 文件计数 / `go/parser` 验过的模块级边 / 入口与

- manifest 事实 / 每片一个结构指纹。**结构层不落盘 ⇒ 模型没有任何途径写坏它**（§3.4）。

- - 持久层 = `~/.yagent/data/blueprint/{projectID}/blueprint.md`（front-matter 是 JSON，与便签同形）

- + `revisions/`（fold 前整档，滚动 5 份 —— "删错了"要有 Undo）。原子写走 `util.AtomicWrite`（I21）。

- - 三条新鲜度判据全部机械：**(a) 结构指纹**不符 → 该片整节标 `stale` 但**散文保留**（清空会把可用信息

- 变成不可用）；**(b) 出处锚点**三态（`path` / `path:line` 越界 / `path:symbol` 词边界匹配 / 非路径形态

- = `unverifiable` 不谎称验过）；**(c) 孤儿**：可见集合 == 派生集合，改名/删除的旧片既渲染不出来也

- 读不到，超过 90 天才从文件里摘除。

- - **stale 是粘滞的**：没有后台进程会补写，一片过期之后只有下一次 Repo 真的覆盖它才修 —— 所以索引行写成

- 行动理由（`N modules annotated but stale (delegate_repo to refresh)`），把"值不值得为新鲜度花一次委派"

- 留给有任务上下文的一方。

- - 读通道 `read_blueprint`；写通道是 `agent_exit` 的 **`blueprint[]`**（`section/module/field/claim/where/supersedes`，

- 一次最多 8 条）。落盘只发生在 **Repo 完成接缝**（`repo.go` 里 `FinalizeResultFull` 之后的那一步）；

- **Director 侧不需要知道这个参数存在**，Coding prompt 明确写"你不写蓝图"。

- 提交采集在 `result.go`（与 `collectHandoff` 并排，executor 不认识蓝图），落在 `AgentResult.Blueprint`

- 而**不是** `Handoff` —— 同一些句子不该同时是便签头和蓝图正文（§2 R4 的病）。

- fold 的**账目**（提交几条 / 写入几条 / 拒收原因逐条归堆 / 证据覆盖几片）走 `AgentResult.BlueprintAccount`，

- 由 `FormatForDirector` 与便签正文的 `> [blueprint]` 尾注各渲染一次（同一个字符串，两处出口），

- **不进 `conclusion`** —— 索引每轮重扫，程序的账混进去就是替模型下结论（坑 43）。

- - fold 是**确定性纯函数**：短 ID 由内容派生 ⇒ 幂等 + 乱序输入产出同一份字节；段内按 `(where, claim)` 稳定排序

- （每次 fold 只动那一行，否则人类 review 与 provider 前缀缓存同时失效）；同 `module+field` 非空才覆盖；

- `supersedes` 指认错 ID 时记账但不失败。**正文逐字没变就不算一次 fold**（`NoOp`），否则 I20 的"字节不变"

- 与 I18 的"没更新 ≠ 更新失败"会打架。

- - 五道校验各有一条能读出来的拒收账（I18）；证据集 = 本次 run 真打开过的文件所属模块，

- **入参侧 ∪ 出参侧**（只认入参会误伤"检索到 8 个、读了 3 个"那一轮）。

- 哪些工具的结果算"读过"是 `toolspec.Spec.ResultPaths`（`json`/`rg`/`bare`）—— `list_dir` 的裸文件名必须排除。

- I14 的散文路径归属只问"它到底指哪儿 / 仓库里有没有它"，**判不了就弃权不拒收**（一条拒收丢整条 claim，

- 全丢就是 NoOp ⇒ 文件永不出现，见坑 42）；写短的前缀与裸文件名都算，存在性交给 `where` 锚点。

- - 注入只有**形状②**（模块 + 边，`index_max_tokens` 硬顶、截断写进 header），三处 system prompt 由

- `[blueprint] inject_into` 决定；`purpose` 这类不可验证的散文永不进常驻。委派前缀会带上目标模块的

- 现有散文（判据是"派生集合里的片路径逐字出现在任务里"，不是猜路径 —— §6.3 否决的是后者）。

- - 启用判据只有 `config.BlueprintEnabled()`（I8，吞下 `enable` 与 `YAGENT_BLUEPRINT=0`）；

- `internal/blueprint` 自己不读环境变量，也不 import `config`/`gitinfo`/`tokenutil` ——

- 仓库读数与 token 计数器由装配层做成参数传进来。

- - **仍然没做**：`export_path` 的导出层（R8）、`/blueprint` 的 TUI/CLI 入口、

- 以及 §8 纪律 1 里"每种拒收再记一条 rollout `event_msg`"（钩子那里没有 writer）。

- （R7 已了结，但方式不是"收编"而是把 KV 仓库记忆整套删掉——见本文件开头的 2026-10-22 记录。）

- - **Skills**（`internal/skills`）：用户写的可复用流程。磁盘约定两种都认 —— `<dir>/<name>/SKILL.md`

- （目录式，胜）与 `<dir>/<name>.md`（扁平，兼容）；front-matter **JSON 优先**，容错扁平

- `key: value` 子集，都没有时沿用"正文首行去 `#`"当描述。作用域是**合并**：user → project →

- `[skills] dirs`，后者覆盖前者，覆盖与拒收都进 `LoadAccount` 的账（启动日志与 `/skills` 面板同源）。

- 目录（`## Skills`，一行一个 name: description，截断标记写进正文）进 system prompt 的稳定前缀；

- 正文由 `use_skill` 按需取回（**Hot** 工具，没有技能时仍在场并解释"放哪儿"）。`allowed-tools`

- 只是回吐给模型看的咨询信息，**不强制**。`Load` 永不返回 nil 注册表 —— 目录读不出只记一条 Rejected。

- - **Thinklink**（`internal/thinklink`）：append-only 的思维日志（用户输入 + T&P 块），是 ultimate 压缩重建上下文的原料。

- ### 6.5 三档上下文压缩（`internal/compression`）

- 阈值 = `min(模型目录收录的 limit.context × 0.75, [enhanced_commander] context_compression_threshold)` ——

- 两个来源都是上限，配置没写（或写 0/负数）就纯按目录推导，都没值才是 120000；

- **provider 的 `context_window` 不参与**（见 §11 坑 3）。每步检查，`enhanced_commander.enable_context_compression` 总开关。

- 调试例外：`YAGENT_COMPRESS_THRESHOLD` 一旦设了就**直接当阈值**，压过目录与配置。

- 判定口径是 `compression.Prefix`：上一步 provider 报的 `Usage.TotalInputTokens` 打底，加上此后新增消息的

- 本地估算（本地估算从不计工具声明，且每步扫两遍全量 tiktoken）。计量缺失、还没跑过一步、或列表被

- 第二/三档整段重写时必须作废 —— 作废后逐字回落到全量本地估算，就是改动前的行为。

- 判定只有一处实现：`compression.OverThreshold(messages, prefix, threshold)`，两个循环各两处调用点，

- 不要再抄 `EstimateMessagesTokens(messages) > threshold`。Director 侧的三档整段在

- `agents/director/planner_compress.go`（从 `planner_run.go` 搬出，该文件行数上限同步下调）。

- 取小的代价是压缩会在更低的位置触发，所以第一档是**增量记账**：达标判定每截一条只重算那一条，

- 不再对整份消息跑 tiktoken（旧写法 200 条工具结果的会话要 9.3s）；`stats` 一律保持本地口径，

- 否则 TUI ⧉ 面板的百分比两个基数混在一起。完整规格与实测数据（含"为什么压缩不是延迟主因"）

- 见 `docs/compression-trigger-design.md`。

- 1. **Rule**：`TruncateToolResultsToBudget` — 按优先级先截低价值工具结果（`deepthinking`/`design` 结果受保护），保留最近 `tool_result_keep_tokens`（默认 200）。

- 2. **Emergency**：抽取 T&P 块进 thinklink，最近 3 条保留原文，其余 LLM 摘要，记忆整体重写为 `[system, one user]`。

- 3. **Ultimate**：仍超阈值时，用 thinklink 日志重建上下文（保留最近 N 个 T&P，N 由 `ultimate_compression_keep_plans` 决定，0=全部），最后硬截断到预算。

- 三档都会发 `context_*_compressed` 事件并写 `compacted` rollout 记录。

- > `enable_ultimate_compression` **现在真的能关**：`validate()` 不再"见 false 就写回 true"。

- > 因为它的缺省语义是"开"而 Go 零值是 false，区分靠的是 **TOML 键的存在性**

- > （`config.ultimateCompressionKeyDefined`，由 `md.IsDefined` 得出）：没写 → 开；显式写 false → 真的关。

- > 与 `[blackboard]` 三个阀门、`[git_checkpoint]` 段级判定是同一套办法（§11 坑 13）。

- > 现状由 `internal/config/validate_test.go:TestLoadFromFile_UltimateCompressionRespectsFalse` 钉住。

- >

- > **压缩只有一个开关**：`enable_context_compression`。以前它还要与 `[enhanced_commander] enable`

- > 同时为真才生效（5 个 AND 点：`coding.go` / `repo.go` / `devops.go` / `browser_agent.go` / `director.go`），

- > 而模板把两个都写成 false —— 那个 `enable` 键已删除，旧配置里残留它会走 `removedKeyHints` 点名告警。

- >

- > **子 Agent 的第三档需要两个条件同时成立**：`ExecutorConfig.EnableUltimateCompression`（来自

- > `enable_ultimate_compression`）与非空的 `UltimateThinkLink`，与 Director Planner 同语义

- > （`executor.go` 的 T3 分支）。Browser/Repo/DevOps 的 store 在 `Run()` 内按委派创建——

- > `RebuildPrompt` 会保留全部用户输入，放构造期会让历次委派的任务串进同一次重建。

- > **Coding 曾是唯一一个把 store 挂在单例上的**（`coding.go` 构造期 `thinkLink: thinklink.NewStore(0)`），

- > 现在由 `CodingAgent.SpawnForDelegation` 每次委派换一份新 store（`agents/spawn.go`，C4/D2）：

- > 挂在单例上不仅会串味，委派一旦并行化就直接是数据竞态。

- > 其余四家今天没有可变自身状态（五家 `Run()` 逐个核过：一处都不写 `a.<field>`），

- > 克隆看起来是空动作，仍统一做，是为了把"委派从不碰共享实例"变成不需要记住的不变量——

- > 以后谁往结构体上加可变字段，默认就是每委派一份。嵌套调用（Repo→`delegate_devops`、

- > Coding→`delegate_browser`）也各自 `Spawn` 一次，否则拷来的仍是同一个共享单例。

- > `ultimate_compression_keep_plans` 现在也真的到达 Coding（`coding.go` 曾硬编码 0，即"永远全部保留"）。

- > token 估算（`EstimateMessagesTokens`）**包含 `Reasoning`**：thinking/reasoning_content 会被回灌给

- > provider，漏算会让压缩触发时机系统性偏晚。

- `Event{ID,Type,Source,Target,Content,Priority,Timestamp,Deadline,TraceID,Metadata,Seq,DelegationID}` →

- `MessageDispatcher`（每个 consumer 一条 1000 容量队列 + 独立 goroutine）。

- 普通事件队列满则**丢弃并限流告警**；`user_help_needed` / `user_help_response` 走 **critical 旁路队列**（永不丢弃，FIFO，满则丢最旧）。

- Consumer 有两种：旧版 `MessageConsumer`（广播）与新版 `Consumer{Types()}`（过滤订阅）。

-

- **两个并行必需的坐标**（C5）：

- `Seq` 由 dispatcher 在 `Publish` 里盖（每个 dispatcher 一条单调序列），所以"界面少了字"第一次

- 变成可回答的问题——消费者看见 7→9 就知道少了一条。`DelegationID` 是产生这条事件的那一次委派

- （`delegate_*` 的 tool_call_id）：**`Source` 在并行委派下不再唯一**，两个 Coding 同时输出时

- 只按名字分槽会把两股流粘成一段文字。

- 它由 `RunAgentLoop` 入口**一次**绑定（`Publisher.ForDelegation(memory.DelegationIDFrom(ctx))`），

- 不是在 10 个发布点各传一遍——漏一处的事件不报错，只会留下没人能解释的现象。

- 绑定用能力断言而非 `EventBus` 接口方法：没绑定的正确后果是少一个坐标，不该逼 5 个测试 mock 各写一个假方法。

-

- 满载丢弃必须**可被知道**：`Dropped()` 是总数，任务收尾调 `WarnDropped(scope)`

- （HTTP 任务 / 两个 TUI 闭包 / WS 会话各自报告）。另外 6 个建调度器的地方原本都手写

- `NewMessageDispatcher(100)`，把文档承诺的"默认 1000"压成了十分之一——现在统一走

- `NewDefaultMessageDispatcher()`，容量只有一处定义。

-

- Web 侧坐标放在 `realtime` 信封的 `Data` map 里（`seq` / `delegation_id`），**不动

- `protocol.AgentEventEnvelope`**：那是生成物，AGENTS.md 下面那条"重跑生成器会冲掉手工修复"的

- 警告仍然成立，而加字段不需要经过它。

-

- 当前总线上的事件类型（约 20 个，SSOT 是 `protocol/agent-events.yaml`，由 `scripts/protoc-gen-yagent` 生成 Go/TS/JSON-Schema）：

- `ai_stream_start` · `ai_chunk` · `ai_stream_end` · `ai_response` · `thinking` ·

- `llm_call_start` · `llm_call_end` · `model_info` · `model_routed` ·

- `tool_call_start` · `tool_call_result` · `user_help_needed` · `user_help_response` ·

- `context_loaded` · `commit_context_loaded` · `context_compressed` · `context_emergency_compressed` ·

- `context_ultimate_compressed` · `thinklink_entry` · `conversation_error` / `conversation_result` ·

- `task_paused` / `task_resumed`（暂停闸门，由 `TaskManager.PauseTask/ContinueTask` 经 melody 广播）

- > **新增事件类型要改 `protocol/agent-events.yaml` 再重新生成**，不要手改 `internal/protocol/agent_events.go`（文件头写着 DO NOT EDIT）。

- > **但"重新生成"今天不能无脑跑**：`scripts/protoc-gen-yagent` 的输出与仓库里两份 Go 产物已经漂移

- > （`protocol/go/agent-events.go` 的 `ParseEventPayload` 被手工修成走 `json.RawMessage`，生成器还在走

- > `interface{}` 类型断言；`internal/protocol/agent_events.go` 与它差约 445 行）。整体重跑会把那个手工修复

- > 冲掉。当前可行做法是：改 yaml → 只覆盖 `ts/agent-events.ts`、`ts/render-mapping.ts`、

- > `agent-events.schema.json`（这三个与生成器输出逐字节相同）→ 把生成器**新增的那几块**逐字粘进两份 Go 产物。

- > 想恢复"一条命令生成"，先把生成器追上现状。详见 `docs/pause-resume-design.md` §15.3 第 7 条。

- > 生成器与 schema 目前落后于实际总线（`model_routed`、`context_*_compressed`、`thinklink_entry` 等未入 schema）。

- → TUI 建 Task(uuid + ConversationMemory) 并每轮新建 Dispatcher(100) + tuiEventConsumer

- | 任务记忆 | `~/.yagent/tasks/{taskID}.jsonl` | **5 秒防抖**、增量追加（条数变少则全量重写） |

- | **Rollout（断点续跑的事实来源）** | `~/.yagent/data/rollout/{projectID}/{ts}_{session}[_{agent}].jsonl` | **入队即返回、攒批落盘**（C2：每个 writer 一条写循环，32 条或 20ms 刷一次，`Close` 会 join），类型含 `session_meta/turn_context/response_item/event_msg/compacted/agent_checkpoint`（`world_state` 已于 2026-10-14 删除）；`session_meta` 带 git 身份 + `delegation_id` + `parent_session_id`，终止事件带 `stop_reason`（词表在 `memory/rollout_types.go`：`paused/cancelled/idle_timeout/total_timeout/max_steps/llm_error/circuit_breaker_open/panic/plain_text/agent_exit/unaccounted`）。子 Agent 的文件名后缀 `_{agent}` 就是"这次委派是哪一个"的凭据。**读回自己写过的文件之前必须排干**：`WriteCheckpoint` 走 `(*RolloutWriter).FinalizeCheckpoint`（先 Flush 再按整份文件算指纹，写完再 Flush 让坐标本身落地），自己拼 `Flush + FinalizeCheckpoint(path)` 的调用点一定会拿到"少几条"的指纹 —— 它不报错，只是把能重放的会话判成损坏 |

- | **仓库蓝图** | `~/.yagent/data/blueprint/{projectID}/blueprint.md` + `revisions/*.md` | **fold 前整档先落 `revisions/`（滚动 5）**；tmp+rename 走 `util.AtomicWrite`（0700/0600）；多进程用**乐观 CAS 重放**而不是锁文件；根护栏拒绝 `$HOME`/`/`/无 manifest 且非 git，存储根落进项目内也拒绝。**取代了原先的 `~/.yagent/data/shared_memory/`（2026-10-22 删除，老目录不迁移、不再写）** |

- | 浏览器工作区 | `~/.yagent/data/browser/{delegation}/.browser-control/` | 由 `cmd.Dir` 决定落点（上游状态路径是 CWD 相对）；含 current-tab、chrome.pid、traces、截图；`[browser] workspace_ttl` 清理 |

- | 日志 | `~/.yagent/logs/`（`app-`、`llm-`、`llm-error-`、`tool-`、`delegate-`，按任务分子目录） | 追加 |

-

- **`/resume` 有两层落点**，共用同一份账本：

- - **会话级**（旧有的）：列出 rollout 会话 → `ReadRolloutMemory` 重建 Memory → 恢复 thinklink 条目，

- 下一轮以 `resumed=true` 强制重注入项目上下文。工具调用配对按 **last-wins** 修复（同一 `call_id`

- 出现第二条 output 时原位覆盖并计入 `SupersededOutputs`）—— 这与 LLM 侧 `llm.repairToolCallPairs`

- 的语义一致，两边不一致的表现是"进程内喂给模型的和 /resume 后喂给模型的不是同一份"

- （`TestToolPairingNormalizersAgree` 钉住）。终止事件带 `stop_reason`，

- `ScanResumeCandidates` 据此判定能否原样继续：**默认拒绝**，只有 `paused` 与 `cancelled`

- 可重放（前者必然停在 step 边界，后者可能停在工具中间）；不可重放的候选照样返回并说明原因，

- 不静默过滤。

- - **委派级**（B 层，`docs/pause-resume-design.md` §6）：会话恢复后 `app.ResumableDelegation(路径)`

- 反问"这次会话是不是停在一次 `delegate_*` 上"，能就给恢复对话框加第三个选项

- "从 <agent> step <n> 继续"；TUI 只交出**那份 Director rollout 的路径**（`internal/tui` 不许依赖

- `internal/agents`，落点由 `app.resolveResumption` 在提交时算）。执行侧见 §6.2 的重放接缝与降级报告。

- ### 6.8 TUI（`internal/tui`，Bubble Tea **v2**）

- - **状态**：`tui_model.go`（logEntry + 渲染缓存 + keymap + `eventCh(1000)`）；更新逻辑按 `tui_update_*.go` 拆分；

- 渲染按 `tui_view.go` / `tui_render.go` / `render.go` / `tui_chrome.go` / `tui_tabs.go` / `tui_dashboard.go`。

- token 消耗展示是**单一渲染器**：`token_panel.go` 的 `buildTokenPanel` 同时产出侧栏 dashboard、底部面板与 `alt+t` 折叠行，

- 所有口径只在 `(*model).tokenSnapshot()` 里算一次（输入量一律用 provider 归一化的 `TotalInputTokens` ——

- OpenAI 的 `prompt_tokens` 含缓存、Anthropic 的 `input_tokens` 不含，混用会让同一标签出两个数）。

- 不要在任何表面里另取计数器直接格式化；完整规格见 `docs/token-dashboard-design.md`。

- - **⧉ 压缩段**：`compress_panel.go` 的 `buildCompressBlock` 排在侧栏 Activity **之下**（底部面板只给 1 行摘要，折叠态不给行），

- 数字只在 `(*model).compressSnapshot()` 里算一次；`pct = Σsaved / max(original_tokens)` 且**显示层封顶 100%**

- —— 三档串行嵌套，用 Σoriginal 当分母会重复计算同一批 token；而压缩是**每个 step 独立触发**的，

- 多轮任务的 Σsaved 会合法地超过任何单次 original。没触发过压缩时区块**不消失**，而是退到常驻的

- 2 行空闲形态（`⧉ COMPRESS 0 (0%) T0`）。完整规格见 `docs/token-compress-panel-design.md`。

- - **叠加模式**：timeline 全屏、thinklink 全屏、history、resume、dialog 栈、主页面——按此优先级渲染。

- 每层都必须正常消费 `taskEventMsg` 并重新武装 `listenForEvents`（该 cmd 是一次性的，事件没有重放队列）。

- 叠加层还必须把 `taskCompleteMsg` 透传给 `handleTaskCompleteMsg`：它是 `taskRunning` 唯一的清零点，

- 吞掉的表现是界面永久卡在"运行中"且最终答案不落地（dialog 守卫曾经就这么吞过，弹窗打开时任务一完成就锁死）。

- - **thinklink 全屏**：条目来自 `thinklink_entry` 事件（payload 的 `agent` 字段 = 发布方 Agent 名），

- `f` 在 All ↔ 各 Agent 间过滤（`RebuildPrompt` 之外，一次委派里 Director/Coding/Browser 的块会混排，

- Browser 一轮可贡献上百条）。`/resume` 恢复的旧 rollout 没有 Agent 标记，只在 All 视图出现。

- - **Dialog**：`components.DialogStack`（Push/Pop/ReplaceTop/Overlay），10 个对话框；

- 弹窗打开时全局守卫只放行 KeyMsg/taskEventMsg/taskCompleteMsg/tickMsg，新增消息类型必须显式放行（`tea.PasteMsg` 的坑已踩过）。

- - **模态编辑**：Esc→NORMAL、`i`→INSERT、`:` 命令行、`/` 真搜索、textarea 用 `SetVirtualCursor(true)`、支持 `10j` 数字前缀。

- - **快捷键提示**只出现在 tab 行右侧与各面板底边框，**状态栏不含任何键帽**。

- - **列表/表单表面的共用原语在 `common/list_metrics.go`**（`PanelWidths` / `ListBudget` /

- `WindowRange` / `MoreLine` / `AllocateColumns` / `Ellipsize` / `PadLeft`）：`components` 的十个对话框

- 与引导向导共用同一份，两边都只留别名。**不要在任何一边再写一份** —— 同形两份实现只有一边会漂走

- （§11 坑 18）。输入框视觉令牌同理：`applyTextareaTokens`（`tui_model.go`）是主输入框与向导字段的唯一来源。

- - **设计语言**：圆角手绘边框（`tui_chrome.go` 的 `╭╮╰╯─▌`），配色令牌集中在

- `common/styles.go`（`Styles` 与 `ColorTokens`，**只有一套深色**；终端背景只切 glamour

- markdown 渲染，不切这些令牌）、`styles.go`（工具背景 16 色哈希、Agent 前景色）、

- `common/grad.go`（渐变）。强调色：`141`（lavender，活动 tab / thinklink / LLM 调用）、`62`（INSERT、滚动条、面板边框）、

- `214`（命令）、`39`（搜索）、`76`（运行中）、`235/250`（键帽）。

- - **i18n**：`i18n.go` 一张 ~120 字段翻译表，zh/en，默认英文，仅通过 TUI 内切换（无配置项）。

- - **测试约定**：断言**精确单元格宽度**而非子串；宽度矩阵 `{30..240}`、终端尺寸矩阵 `{20..240}`；

- 共享 fixture `newTestModel()` / `chromeTestModel(t,w,h)`；主要闸门是 `tui_chrome_test.go`、

- `tui_paste_test.go`、`components/user_help_dialog_render_test.go`、`tui_resume_restore_test.go`。

- `POST /api/start_task`、`GET /api/task_status`、`GET|DELETE /api/memory`、`GET /api/memory/:type`、

- `GET /api/history`、`POST /api/load_task`、`POST /api/cancel_task`、

- `POST /api/pause_task`、`POST /api/continue_task`、`GET /ws`。

- 任务状态四档不变，另加 **`paused`**（`TaskStatusPaused`）：暂停闸门不产生 task_complete，

- 所以旧四档里没有一个能表达"停住但可继续"。`http.Task.Gate()` 从 ctx 读回闸门，

- 不在结构体里另存一份（两份状态 = 一处忘了换 = `/pause` 停错对象且不报错）。

- WebSocket 用 melody，每个任务一个 Dispatcher + `WebSocketConsumer`，向所有连接广播 `realtime` envelope（无按会话过滤）。

-

- ---

- **解析顺序**：`--config` 指定路径（原样使用，**绝不自动创建**）→ `~/.yagent/config/config.toml`（不存在则用内嵌模板生成，权限 0600）。`./config/config.toml` **不是第二级查找**：只有 `os.UserHomeDir()` 失败时才会走到 CWD 相对路径，仓库里那份是注释参考。模板由 `config.EnsureConfigExists` 生成并返回 `created`，这个信号是首启判据之一（见下面的"引导"段）。

-

- **顶层表**：`[global.llm]`、`[agents.llm]`、`[tools.llm]`（含 `[tools.deferred]`）、`[agent]`、`[llm]`、`[routing]`、

- `[keywords]`、`[git_checkpoint]`、`[codeseek]`、`[browser]`、`[blackboard]`、`[resume]`、`[enhanced_commander]`、`[tui]`，

- `[blueprint]`（仓库蓝图：`enable` / `inject_into` / `index_max_tokens` /

- `prose_budget_tokens` / `export_path`；启用判据 `config.BlueprintEnabled()` 同时吞下环境变量

- `YAGENT_BLUEPRINT=0` 与 `enable` 键。**五个键里四个已有真实消费者**（`enable`→`app.buildBlueprint`

- 一处读取、五处共问；`index_max_tokens`→形状②硬顶；`inject_into`→三处 system prompt；

- `prose_budget_tokens`→`read_blueprint` 与委派前缀），**`export_path` 仍无消费者**（导出层是 R8，

- `docs/config-guide.md` 里先不要写它）。默认值与 `internal/blueprint` 的渲染兜底常数由

- `internal/config/blueprint_defaults_test.go` 钉成同源（同 §11 坑 18 那类"两份同形实现"），

- 以及顶层 `task_timeout`。**`[app]` 与 `[codeseek.knowledge]` 已整体删除**（前者唯一的键只进 `slog.Debug`，后者五个键全部不可达 —— `enabled` 会被写回 true，其余四个读点在注入器的 early return 之后；那套注入器连同 `consolidate_knowledge`/`prune_history` 已在 2026-10-22 整体删除）。

-

- > 工具声明面的 schema 条数基线：`read_blueprint` 把它从 50 → 51，2026-10-22 随知识机制删除回到 49，

- > 2026-10-23 技能读通道 `use_skill` 加到 **50**；改动必须显式改数字

- > （`internal/toolspec/registry_test.go:TestSchemasLoadAndDescribeEveryEntry`）。

- > MCP 外部工具**不计入**这个基线：它们走 `Deps.ExternalSpecs` 的动态通道。

-

- **运行时写回**：`config/persist.go` 只有一个内核 `SetKeyInSection(path, section, key, renderedValue)`

- （段缺失→末尾追加，键缺失→段内插入，存在→就地替换且保留行内注释与等号两侧空白；永不整文件重编码，

- 那会蒸发用户注释），另有 `RemoveKeyInSection` / `RemoveSection`。

- `PersistUseProvider` / `PersistRoutingMode` / `PersistLLMTimeout` 是它的三个薄封装。

- provider 块的写/删在 `config/setup.go`（`WriteProvider` / `DeleteProvider` / `ProviderRefs` / `WriteFirstRun`），

- 被任何 `use_provider`/`fallback_providers` 引用的 provider 拒绝删除 —— 留下一个"加载即失败"的文件比拒绝更糟。

- **首次使用引导**（`docs/config-trim-onboarding-design.md`）：手写 config.toml 不友好，而模板自带

- `api_key = "your-key"`、校验只查非空，于是全新机器"启动成功"、第一次任务才炸。现在：

- - 入口三个 —— `yagent setup` 子命令（不装配 Agent/MCP，配置坏了也能跑）、TUI `/setup`

- （任务运行中或弹窗打开时拒绝，避免抢键盘；写完要重启才对新引擎生效）、以及 `main.go` 在

- `config.NeedsSetup` 判出 `SetupFreshInstall / SetupPlaceholderKey / SetupBroken` 时自动进入。

- - 判据全部从配置本身推导，**没有"看过一次就不再问"的标记文件**（那是会漂移的第二份事实）。

- - 向导内容是 provider 全生命周期 + 一次真实连通性探测 + 五个首选项（`lang` / yolo 档位 /

- `[routing] mode` / `[browser] enabled` / `[llm] timeout`）。排队到摘要屏才落盘，之前放弃 = 文件没动过。

- - 表单**必填只有 4 格**（name / api_base_url / 密钥 / model），其余 4 格收在 `ctrl+o` 才展开的可选区；

- `ctrl+p` 是端点预设（**只填空字段**，`setup_presets.go` 那份手写的 URL 表不是权威，探测屏才是）；

- `f2` 把 `api_key` 与 `api_key_env` 合并成一行两态（`config.WriteProvider` 本来就删另一行，

- 分成两格只会留下"两个都填了谁赢"这条只能靠 hint 说明的隐式规则）。

- `model` 命中内嵌目录时自动回填 `context_window`，但**只在该格为空或仍是上一次自动填的那个值**时回填——

- 手输过的数不会被覆盖。校验集合与必填集合是同一份（`TestWizardRequiredGroupMatchesValidator` 双向钉），

- 其中 `api_base_url` 是本轮补的：`WriteProvider` 只要求"URL 与密钥不全空"，而 `validate()` 要求每个

- provider 都有 URL —— 旧表单会放行出一份"下次启动直接加载失败"的文件。

- - 进度是**四段阶段轨**（PROVIDER / DEFAULT / CHOICES / REVIEW），判据来自账本（op 队列 + 文件现状），

- **不是"走到第几屏"**：真实路径 `providers→form→probe→providers→default` 里游标会来回跳，

- 而"已经配完了"这个事实不会倒退。旧的 `4/7` 编号因此是假信息（见 §11 坑 30）。

- - 摘要屏是人话 diff（`+ 新增 / − 删除 / → 改默认 / ~ 改值 old → new / = 不变`），

- 每条 op 的 `note` 原文作为次级 dim 行**保留**——`applyOps` 失败时报的就是它；写失败还会带上

- "已写入 N/M 条"（它不是事务，§11 坑 28）。

- - 实现是 `internal/tui/setup*.go` 的状态机 `setupWizard`（`setup.go` 状态与落盘队列、

- `setup_keys.go` 按键与表单行规格、`setup_render.go` 外壳、`setup_screens.go` 七屏正文、

- `setup_presets.go` 端点预设、`setup_embed.go` 主 TUI 宿主），既能独立跑（`RunSetup`）也能当主 TUI 的全屏模式；

- View/Update 优先级最高，且必须把 `taskEventMsg` / `taskCompleteMsg` 透传给原 handler。

- - **仍未兑现**：写完不会让运行中的进程生效（原方案 §6.2 要求复用 `SwitchProvider`/`SetLLMTimeout`/

- `SetRoutingMode`），所以 `/setup` 之后要重启 yagent。

- - 非 TTY 的失败路径改成 stderr 三行人话（哪一项坏了 / 文件在哪 / `run yagent setup`）+ 退出码 2，

- 不再 `slog.Error` 进日志文件后静默 `os.Exit(1)`。

- **已删除的键**：残留它们的旧配置会命中 `config.go` 的 `removedKeyHints` / `removedProviderKeyHints`，

- 启动时 `slog.Warn` **逐条点名并给出替代写法**（`removed_keys_test.go` 要求登记表与夹具互为镜像，

- 所以这条承诺本身有测试）。

- **三级 Provider 覆盖（仍存在）**：`ResolveProvider(agent, tool)` = 工具指定 → `tools.llm.use_provider` →

- Agent 指定 → `agents.llm.use_provider` → `global.llm.use_provider`。Agent 名现在有**七个**：

- `director / coding / repo / chat / devops / browser / meta`（`[agents.llm.browser]` 以前是 undecoded 键，

- 被静默忽略）。

- model = "qwen3-coder" # 必填

- api_base_url = "https://..." # 与 api_key 一样对每个 provider 必填（无 Bedrock 豁免，见 §11 坑 14）

- api_key_env = "BAILIAN_KEY" # 或者由环境变量供给；变量没设 → 生效 provider 启动即失败并点名

- context_window = 262144 # 只影响 TUI 上下文进度条；压缩阈值走模型目录（见 §11 坑 3）

- temperature = 0.3

- reasoning_effort = "high" # openai 原样透传(+thinking 扩展字段)；anthropic 映射为 budget 1024/8192/24576/32000

- [tools.llm] micro_agent.use_provider = "local" # 另有 thinking / deepthinking / design

- max_parallel_readonly_tools = 4

- max_parallel_delegations = 2 # 一次 Director 运行里同时跑几个子 Agent

- lang = "Chinese"

-

- [llm] timeout / max_retries(5) / step_retries / enable_fallback / fallback_max_retries(2)

- max_in_flight_requests(8) # 全进程同时在飞的 provider 调用上限

- step_retries 现在下发到**六个子 Agent**（以前 ExecutorConfig.StepRetries 全仓无写入点，只有 Director 和 Meta 生效）

- circuit_breaker_threshold = 0 意为**不启用**（仓库模板与 defaults.go 都是 0）；

- 只有 > 0 才创建熔断器，此时 reset_timeout 缺省补 60s

- [routing] mode = "auto" [routing.baselines] coding = "high" repo = "balanced"

- [enhanced_commander] enable_context_compression（唯一开关）

- context_compression_threshold / tool_result_keep_tokens(200) / enable_ultimate_compression / ultimate_compression_keep_plans

- [browser] enabled / binary_path / chrome_path / mode(headless|headful|attach) / cdp_url / cdp_port_base(9333)

- cdp_timeout(65s) / command_timeout(75s) / idle_ttl(15m) / max_chrome(1) / workspace_root / workspace_ttl(72h)

- max_output_bytes(24000) / dialog_policy(accept) / allowed_domains / denied_domains / profile_dir

- [git_checkpoint] enabled / agent_branch_prefix / checkpoint_tag_prefix / stash_dirty_worktree / squash_on_exit

- auto_merge_on_exit / cleanup_agent_branch / cleanup_checkpoint_tags / generate_commit_message

- ```

- > `[browser]` **整表缺省**（老配置没有这一段，或只剩旧浏览器栈的失效键 `headless` / `browser_path`）时，

- > 按 `config.DefaultBrowserConfig()` 填默认值。判据是段内是否存在**至少一个被新 schema 认识的键**

- > （`config.go` 的 `browserSectionConfigured`），不能用 `enabled` 的零值判断——它缺省就是 false，

- > 会把新能力静默关掉；失效键会被 `slog.Warn` 点名提示改写。

- > **并发那三个旋钮的取值约定是两套，而且各有理由**：

- > `max_parallel_readonly_tools` 与 `max_parallel_delegations` 用 **1 = 严格串行**、≤0 = 取默认（4 / 2）、>8 钳到 8；

- > 而 `[llm] max_in_flight_requests` 的 **0 有语义（不限流）**，所以它必须靠**键的存在性**

- > （`md.IsDefined("llm", "max_in_flight_requests")`）区分"没写 → 8"与"写了 0 → 不限"（坑 26）。

- > 别把后者的"串行"写成 0 —— 那两个 0 含义不同，而邻居那套（1 = 串行）已经是既有约定。

- > 急停开关是环境变量 `YAGENT_CONCURRENCY=0`，唯一判据 `config.ConcurrencyEnabled()`，

- > **写在两个 `Normalize*` 函数内部**而不是调用点：两个循环都只经这两个函数取值，

- > 判据写两处就会有一处忘，而漏掉那处的表现只是"还是并发"。只认精确的 `"0"`。

- > 在飞闸门的排队发生在 `llm.timeout` **之前**（等一个格子不是"provider 慢"），

- > 重试与流式在格子内完成（一次逻辑请求只占一格）。

- ```toml

- index_max_notes = 12 # 索引条数上限；**0 = 关掉索引注入**，负数/没写 = 默认 12

- index_line_chars = 160 # 索引单行 rune 预算；**显式 0 = 不裁剪行**，负数/没写 = 默认

- summary_max_runes = 1200 # Director 侧 handoff 摘要预算；<=0 = 默认

- ttl = "168h" # board 目录多久没动就整板清理；"0" 或 0 = 不清理

- max_notes_per_board = 200 # 每 board 保留的最新便签数；0/负数 = 默认（放宽请写大数字）

- ```

-

- > 与 `[browser]` 同构的整表缺省判定在 `blackboardSectionDefined`；但本表有**三个键的 0 是有意义的**

- > （关索引 / 不裁剪行 / 不清理），所以除段级判定外还要看**单个键的存在性**（`md.IsDefined`）——

- > 只看零值会把用户的"关掉"当成"没写"，或反过来把"没写"当成"关掉"。

- > 整体关闭不设 `enabled` 键：kill-switch 是环境变量 `YAGENT_BLACKBOARD=0`（`blackboard.Enabled()` 唯一判据）。

- > 索引的 token 成本上限 = `index_max_notes × index_line_chars`，且它是**每轮**都注入（Director 自己 + 每次委派）。

- ```toml

- enable = true # 总开关；false = 不写检查点、不重放（停住的任务只能从 Director 继续）

- replay_token_budget = 0 # 重放上下文 token 上限；0 = 用模型目录阈值，超预算**降级成交接报告**而不是报错

- max_replay_messages = 2000 # 重建消息条数上限；**显式 0 = 不限**，负数或没写 = 默认 2000

- degrade_on_workspace_change = "warn" # warn = 工作区 HEAD 变了仍重放并记一条降级；block = 拒绝重放走交接报告

- checkpoint_workspace = true # 停止时跑一次 git status 把工作区事实写进检查点（超大仓库可关）

- ```

- > 与 `[blackboard]` 同一套存在性判定：整段缺省走 `sectionHasDecodedKey(md, "resume")`（结果记在

- > `cfg.resumeSectionDefined`），单键走 `md.IsDefined("resume", …)`。`max_replay_messages`

- > 的 **0 是有意义的**（不限），所以它不能被零值兜底成默认；认不出的 `degrade_on_workspace_change`

- > 会 `slog.Warn` 后回落 `warn`（静默按另一种策略走 = 用户写了 `block` 却以为挡住了危险重放）。

- > 缺省是 `warn` 而不是 `block`：换机器/pull 之后 HEAD 必然变，默认 block 会让 B 层在最主要的场景里失效。

- > 整体退出这套机制是环境变量 `YAGENT_RESUME=0`（`config.ResumeEnabled()` 是写检查点、重放、UI 入口

- > 三处共用的唯一判据）—— 关掉是**连写都不写**，留半套开关的后果是"这份 rollout 为什么没有检查点"

- > 变成没人能回答的新问题。

- ---

- ./build.sh # Rust(codeseek release) + Go，产物 dist/bin/codeseek 与 ./yagent

- ./build.sh -j 8 # 调 cargo 并行度

- ./build.sh clean | release | help

- SKIP_RUST=true ./build.sh # 只构建 Go（复用已存在的 dist/bin）；dist/bin 为空时二进制里不嵌任何引擎

- SKIP_GO=true ./build.sh

- BUILD_TYPE=debug ./build.sh

- 只想快速验证 Go 侧改动：`go build -o yagent .`（`dist/bin` 已有文件时可用）。

- 版本号通过 ldflags 注入 `internal/globalctx.{Version,BuildTime,GitCommit}`。

-

- ./yagent # 默认 TUI

- ./yagent tui --taskfile TASK.md

- ./yagent -p "问题" # 非交互单轮

- ./yagent http --port 9080 # 注意：--port 0 表示系统分配端口

- 工作目录即项目根（`os.Getwd()`），没有 `--cwd` 类参数。

- bash scripts/check_all.sh # 一条命令的本地闸门：build + vet + 九把守卫 + 全量单测

- RACE=true bash scripts/check_all.sh # 同上，再对并发包跑 -race（慢 3-8 倍，改到并发时手动跑）

- bash scripts/check_all.sh --fast # 只跑 ./internal/... 的全量单测，跳过 ./... 与守卫之外的部分

- go test ./... -count=1 -timeout 600s # 全仓 26 个测试包，墙钟约 12s（包间并行；2026-10-15 实测）

- go test ./internal/tui/... ./internal/messaging/... -count=1 # 快循环，亚秒级

- go test ./internal/agents/... -count=1 -timeout 300s # 最慢的一档，约 10.5s

- go test ./internal/agents/ -count=1 -skip 'TestPause...' # 用 -skip 做耗时归因，别猜

- bash scripts/check_test_hygiene.sh # 单测卫生棘轮（见 §9.2）

- go vet ./... # 必须干净

- - 共 124 个测试文件、约 952 个 `Test*`（2026-10-14 两轮整理：先 966→805 清掉"永远不会失败"的

- 用例并把全仓墙钟 80s→7s；同日补齐核心系统契约后 805→952。加了 147 个用例而墙钟没涨（并行下

- 仍约 6-7s），因为新增的都自带计时 seam 或走假服务端，没有一个是靠 sleep 等出来的。

- - **核心包覆盖率基线**（`go test -cover`，2026-10-14）：recovery 97.6%、toolspec 87.3%、

- config 84.2%、messaging 80.4%、datamanager 65.2%、memory 64.3%、llm 61.6%、mcp 62.1%、

- agents 59.5%、app 16.9%。`app`/`toolspec`/`mcp`/`llm` 原本分别只有 0%/8.5%/8.6%/18.6% ——

- 低覆盖率的共性是"错了不报错，只是静默换模型/静默丢工具"，所以补的是**契约**而不是行数。

- - **链路级 E2E 只 mock 模型，不 mock 被测组件**：`internal/agents/e2e_*_test.go` 钉五条

- 核心链路 —— 授权回路（`e2e_authorization_test.go`）、跨委派交接（`e2e_handoff_test.go`：

- 便签 + artifact + deferred schema 重试）、委派生命周期（`e2e_lifecycle_test.go`：idle/total

- 超时与取消传播）、`/resume`（`e2e_resume_test.go`）、**委派级重放**（`e2e_replay_test.go`：

- 恢复后喂给模型的消息必须与暂停前**逐条同形**、取消路径也要写出可用检查点、

- `delegation_id` 真的落进了子 rollout）。它们用的是**真实** dispatcher、真实

- `WorkspaceGuard`、真实便签盘（`TestMain` 已把 `$HOME` 隔离到临时目录）、真实 rollout 文件，

- 只把 LLM 换成脚本。harness 的接线顺序照抄 `internal/app/app.go:112-292` —— 换顺序会测到一条生产不存在的路。

- - **脚本引擎按 Agent 身份分派，不按全局调用序号**（`e2e_engine_test.go`）：序号会被循环里的

- 补偿动作打断（纯文本触发 NoActionRetryLimit、Director 未委派触发强制委派提醒、超时后的重试），

- 一个无关的 +1 就让整条脚本错位，失败看起来像产品 bug。身份靠各家 System Prompt 的首行措辞识别，

- prompt 改了会失败在"认不出是谁"。脚本引擎**必须先看 ctx**：忽略 ctx 的 mock 会把

- "取消没传播"这类缺陷直接掩盖掉。

- - **协议层用 `httptest` 假服务端钉字节形状**：`internal/llm/engine_openai_test.go` 与

- `engine_anthropic_test.go` 断言的是发出去的 JSON（`system` 顶层字段、`tool_result` 块、

- `reasoning_content` 回灌、`stream_options.include_usage`）与读回来的账目

- （OpenAI 的 `prompt_tokens` 已含缓存、Anthropic 的 `input_tokens` 不含 —— 两边口径相反）。

- - **MCP 客户端的假服务器 = 重新执行测试二进制**：`internal/mcp/client_process_test.go` 的

- `TestMain` 认 `YAGENT_TEST_FAKE_MCP_SERVER=<模式>` 环境变量，子进程直接跑假服务器而不是

- `m.Run()`。不要改成 `go run` 或外部脚本：那会把编译时间算进单测，也会让 `-race` 下起不了进程。

- - **计时类 seam**：`datamanager.taskFlushDebounce`（5s 防抖窗口）与 `agents.stepRetryBackoffBase`

- （步级 LLM 重试退避基数）。凡是"等 timer / 等退避"的

- 测试都必须走这两个变量而不是 `time.Sleep`，同 `tools.defaultToolTimeout` 一个道理。

- 新增 timer 请先加 seam，再让测试自己负责耗时。

- - **耗时必须由测试自己负责**：历史上 `internal/compression` 的 28s 全部来自五个用

- `strings.Repeat("x", 50000)` 造工具结果的截断测试（tiktoken 反复编几百 KB）——payload 缩到

- 1-2k 并等比缩预算后整包 0.17s，断言语义不变（今天 0.55s：`TestTruncateCostScalesLinearly` 是故意留下的

- 一条计时用例，用来钉住"每截一条全量重算"不许回来，见 `docs/compression-trigger-design.md` R2）。`internal/agents` 的 30s 来自

- `TestRunAgentLoop_MultipleToolCalls` 把工具阻塞到 **父 ctx 的 30s 超时**；现在统一用

- `restoreToolTimeout(t, …)`（改 `defaultToolTimeout` 这个已有 seam）+ `context.Background()`。

- LLM 引擎的退避（baseDelay 10s）**不要**试图跑完整重试序列：用短 `cfg.Timeout` 把退避钳制到

- 剩余预算，然后断言"服务端只收到 1 次请求"——这条断言同时钉住 SDK 自带重试被

- `option.WithMaxRetries(0)` 关掉了。

- - **不要写"永远不会失败"的测试**。整理前的基线里有 16 个用例没有任何断言能力

- （只有 `t.Logf`、整函数体只有一行 `t.Skip`、或恒真断言）。三类典型坑：

- - 断言在异步完成之前：`callConsolidationLLM` 失败要睡 1s+2s 真实退避，而测试只睡 2s，

- 于是"LLM 失败后保留旧记忆"这条断言在重试跑完之前就检查了 —— 无论实现对错都通过。

- 改法是等确定性信号（`Stop()` 会排干队列），不是等更久。

- - fixture 小到根本没触发被测分支：`TestEnforceTokenBudget_TruncatesAtSectionBoundary`

- 的夹具只有 643 token < 上限 1500，从未截断过。现在每条这类测试都自带

- `t.Fatalf` 前置条件（"夹具必须超预算"）。

- - 去重先把数量吃掉：`TestResolveRefsMaxLimit` 用 20 条**相同** ref 去测上限 10，

- 去重后必然剩 1 条，上限断言永远为真。

- - 反向的坑同样致命：**校验规则本身也可能不可触发**。`toolspec.Validate()` 里那条

- "Serial 与 IsReadOnly 冲突"永远为假（`IsReadOnly()` 的定义含 `!Serial`），

- 而它与 `Serial` 字段"无副作用也必须串行"的文档直接矛盾 —— 已删除，由

- `registry_test.go` 的 `TestValidate_ReportsEachRule` 保证每条规则都有能响的夹具。

- 新写校验时，请同时写一个"它必须报"的夹具用例。

- - 历史上 `TestRunAgentLoop_ParentCancel_AllCallsAccounted` 会卡在 `toolbatch.Run`：它把 `cancel()`

- 放在批次内的第一个工具里，而 `toolbatch` **不保证组内启动顺序**，负责取消的工具一旦排在信号量队列里，

- 在飞调用就无人可取消，只能等 `defaultToolTimeout`(180s) 逐波解开。现在改成从批次外部取消

- （`time.AfterFunc`），写并发工具测试时不要重现这个假设。

- - **没有 CI 质量闸门**：`.github/workflows/release.yml` 只做跨平台构建 + 发布，不跑测试/lint；也没有 Makefile/golangci。

- 验证靠本地 `go build` + `go vet` + 相关包测试 + `scripts/` 下的守卫。

- `-race` 不在默认流程里；改动并发/事件总线相关测试时手动跑一次。

- - TUI 改动必须跑渲染/尺寸矩阵测试（见 §6.8）。

- ---

- - 导入路径 `yagent/internal/...`（已无 `yagent/pkg/...`）。

- - `gofmt` 为准，但**存量文件有对齐漂移**（`internal/tui` 若干）；改到被 `gofmt -l` 报出的文件时先用 `gofmt -d`

- 区分"我写的"和"历史遗留"，不要顺手全量重排。新建/大改的文件必须干净。

- - 错误用 `fmt.Errorf("context: %w", err)` 包装，不吞错误；长任务必须响应 `ctx` 取消。

- - 注释默认不写；只写"为什么"，且不超过一行。

-

- ### 9.2 工具/规模守卫

- ```bash

- bash scripts/check_all.sh # 上面九把守卫 + build + vet + 全量单测，一条命令跑完

- bash scripts/check_file_sizes.sh # internal/agents/director/ 下非测试文件 ≤300 行（存量按 PENDING 冻结）

- bash scripts/check_no_agents_import.sh # director/ 子包不得 import yagent/internal/agents（防循环依赖）

- bash scripts/check_toolspec_leaf.sh # toolspec 不得反向依赖 agents/tools

- bash scripts/check_no_manual_lookup.sh # 不许重新出现按名字查工具的 lookupToolFunc/getToolFunc

- bash scripts/check_test_hygiene.sh # 单测卫生棘轮，见下

- bash scripts/check_blueprint_leaf.sh # internal/blueprint 只准依赖标准库 + util + projectid

- bash scripts/check_supervise_leaf.sh # internal/supervise 只准依赖标准库

- bash scripts/check_no_bare_go.sh # 全仓不许出现裸 go（唯一例外：internal/supervise 自己）

- bash scripts/check_no_inline_atomic_write.sh # tmp+rename 只准有 internal/util/atomic.go 一处（I21）

- ```

- - `check_file_sizes.sh` 现在是**棘轮而不是硬门**：存量超限项在脚本顶部的 `PENDING` 里

- 点名并记下"允许的最大行数"作为冻结上限（今天只有 `director/planner_run.go`，上限 **572 行**——

- 压缩段 96 行已抽到 `planner_compress.go`，657 → 572；剩下主循环 + 委派编排两段职责，拆分是独立一次改动）。规则：新文件超 300 行直接红；

- 存量文件长回去也红；**改小了必须同步下调 PENDING 里的数字**，否则脚本会主动报失步。

- 以前它无条件红灯，结果所有人对它视而不见 —— 一条常红的守卫等于没有守卫。

- - `check_test_hygiene.sh` 守的是**测试自己**：① 每个 `Test*` 必须能失败（自身有 `t.Error*/t.Fatal*`，

- 或调用 `assert*/check*/verify*/expect*/require*` 辅助，或写明 `hygiene:panic-guard` 豁免标记）；

- ② 函数体第一层不得出现裸 `t.Skip*`（按环境跳过必须带条件）；③ 同一个包只允许一个

- `string→string` 的 ANSI 剥离辅助函数。脚本自己也会报"只扫到 N 个函数"的失步异常，

- 不会静默放行 —— 2026-10-14 整理前的基线是 882 个 `Test*`，其中 16 个没有任何失败能力

- （`t.Logf` dump、只有一行 `t.Skip` 的空壳、恒真断言如"发布 1000 条却断言 count>1000"）。

- 唯一豁免途径是 `hygiene:panic-guard`：去掉某条 nil 守卫后测试会 panic 而失败的那类用例。

- 注意它按**名字**认断言：自定义等待辅助（如 messaging 的 `waitFor`）不算断言，

- 所以"等异步"的用例仍必须补一条直接的 `t.Errorf`。

- - **goroutine 只能经 `internal/supervise` 起**（C1，`docs/structured-concurrency-design.md`）：

- `supervise.From(ctx).Go("名字", fn)` / `supervise.New(ctx, 域名)` 给出**名字 + recover + 可等待**，

- `Drain(timeout)` 返回的是"哪几条还没退"的名字清单，不是一句超时。裸 `go` 由

- `check_no_bare_go.sh` 硬禁（**没有 PENDING 名单** —— 一条常红的守卫等于没有守卫，

- 而带名单的棘轮会变成第二个会漂走的事实）。两条纪律：

- ① **需要"等这一批"的地方仍用本地 WaitGroup**（`toolbatch`、`tui_resume_stop`）—— Drain 等的是

- 整条域，把"批次"当成"域"会把不相关的后台工作一起算进来，甚至等自己（见 ②）。

- ② **跑任务的那条 goroutine 不进任务自己的域**：域由 `http.NewTaskContext` 挂在 ctx 上，

- 任务收尾时 `Drain` 它；把执行体自己也算进去就是收尾时等自己，会死锁。

- - **`memory.ConversationMemory` 的 `messages` 字段不导出，读写只走方法**（C4/D6）：

- `Snapshot()` 拿一份拷贝、`Append(...)`/`Add*` 写、`Replace()` 整体装载（从磁盘/rollout 重建时用，

- **不**触发 MaxSize 截断）、`Size()`、`LastMessage()` 返回**拷贝**。

- 三条理由都要记住：① 并行委派的注入跑在工作线程上，planner 在主线程写同一份；

- ② `GetMessages()` 的注释早就写着 "thread-safe copy" 而它返回的是内部 slice 本身——

- 注释与实现不符比没注释更糟，现在名副其实；③ 旧版 `GetLastMessage()` 返回

- `*ChatMessage` 指向 slice 内部，拿着指针的人绕过锁还能改写它。

- JSON 线上形态（`{"messages":[…],"max_size":n}`）由 `MarshalJSON/UnmarshalJSON` 原样保住，

- 封装不许改协议。

- - **把指针装进 interface 的那一瞬间就再也不等于 `nil`**（C4 顺手修的既有洞）：

- `func() builtinAgent { return a.RepoAgent }` 在 `a.RepoAgent == nil` 时返回的是

- "装着 nil 的 interface"，于是 `agent == nil` 那条"not wired"守卫永远不成立，

- 未装配的子 Agent 会一路走到 nil 解引用。凡"具体类型指针 → interface"的返回，

- 必须在**具体类型**上先判 nil（见 `director_surface.go` 的 `delegateTargets` 注释）。

- - **锁不许跨过 IO；投递一律"锁内装配、锁外写"**（C6-d）：`internal/http` 的 6 个状态点

- （三个 setter + pause/continue/cancel）在 `tm.lock` 内只编字节，`taskAction.deliver` 在

- Unlock 之后做 `Socket.Write`/`Broadcast`；`DataManager.FlushAll` 先拿一份 writer 快照就放掉

- `dm.mu`，且**首错不再提前 return**（退出时"第一条刷失败"不该让后面 N-1 条任务记忆蒸发）。

- 要测这类不变量得能把 IO 卡住，所以有 `writeSession` / `melodyBroadcast` / `flushHook` 三个

- seam —— 探针必须用**不需要投递**的路径，否则带 socket 的 setter 会停在它自己的慢客户端上，

- 那不是"别人的锁压着"。

- - **排在闸门上的调用要替 ctx 让路，而且照样产出结果**（C6-a/C6-c）：在飞闸门

- （`llm.acquireInFlight`）与委派池（`acquireDelegateSlot`）都是 `select` 上 `ctx.Done()`，

- 取不到格子时返回错误而不是硬等；`toolbatch.Run` 的既有纪律是"已取消的元素照样启动、

- 照样 commit"，为的都是同一条不变量：**每个 tool_call 必有一条 tool 结果**，少一条就是

- provider 400（§11 坑 5）。从未取得的一格绝不去做 `<-sem` 接收 —— 那会和其他释放方的

- 接收互相吃掉，把整批卡在 WaitGroup 上。

- - **MCP 客户端的 `IsAlive()` 只读两个原子位**（C6-b）：`cmd.ProcessState` 由 `cmd.Wait()` 写，

- 而查活的线程可能在 Wait 落笔的同一瞬间读它（拿到"非空但还没填完"的指针不是不可能）。

- 进程真的没了这件事由 readLoop 的 stdout EOF 兜进 `alive`，所以删掉那次读不丢信息。

- `doRequest` 给每条请求套 `context.WithTimeout(ctx, c.cfg.RequestTimeout)` —— **取调用方 ctx 的较小值**，

- 兜底 30s 只在 `NewMCPClient` 一处，别再往上游抄一份默认值。

- - Director 采用**门面 + 子包**结构：`internal/agents/director.go` 只做装配与 delegate 注册，

- 编排逻辑进 `internal/agents/director/`，跨子系统依赖一律经 `internal/agents/ports.go` 的窄接口注入。

- - `toolbatch` 是无业务依赖的叶子包，不要往里加业务。

- ### 9.3 新增一个工具的正确步骤

- 1. 在 `internal/tools/` 实现 `Execute*`（或独立 `*Tool` 结构）。

- 2. 在 `internal/toolspec/schemas.json` 加 name/description/JSON Schema。

- 3. 在实现旁边 `toolspec.MustRegister(Spec{Name, Effect, Frequency, Mutates, Serial, NeedsAuth,

- PathParams, Trunc, Display, Brief, Build})` —— **这一条取代了旧的第 3、4 步**：

- 并发/授权/截断/展示全部从 `Effect` + 显式字段派生，不再往任何名字表里加条目。

- 4. 让该工具进入某个 Agent 的工具面：优先靠已有的能力标签（画像会自动匹配，无需改 Agent）；

- 仅当它是委派类工具时才在 Spec 上写 `Audience`。

- ⤷ 改完必须跑 `go test ./internal/agents -run TestAgentSurfacesGolden -update` 之前先看清 diff，

- 工具面变化必须以显式改写 golden 的方式被评审。

- 5. 用 `client.GetToolEngine("<name>")` + `[tools.llm.<name>]` 取工具级引擎；构造期依赖从 `globalctx` 拿。

- 6. 加 `internal/tools/*_test.go`；涉及循环则补 `agents` 的执行循环测试。

- > **外部工具走另一条通道**：MCP 工具由 `tools.BuildExternalSpecs` 在运行期构造 Spec，经

- > `Deps.ExternalSpecs` 进 `Surface.rebuild()`，**不进** `schemas.json`、不进全局注册表、不进 golden。

- > 判据见 §5.3 与 §11 坑 44。

- ---

- ### 10.1 核心约束

-

- ### 10.2 `<thought>` 格式契约（`internal/thinklink/thoughtplan.go`）

-

- ```

- <thought>

- goal: [当前高层目标]

- step: [上一步及结果]

- reason: [为什么执行下一步]

- plan:

- - [x] [已完成]

- - [>] [当前 — 即将委派]

- - [ ] [待处理]

- </thought>

- ```

-

- - `<thought>`/`</thought>` 为字面定界符；每轮回复恰好一个块，置于工具调用之前。

- - `goal`/`step`/`reason`/`plan` 为固定小写 key，各占一行（`current goal`/`reasoning`/`plan update` 等别名会被归一）。

- - `Validate()` 要求 `goal` 与 `reason` 非空，且**至多一条** `[>]` 进行中项。

- - 状态标记支持 `[x]` 已完成、`[>]` 进行中、`[ ]` 待处理（解析器也容忍 `X`、`-`、`1.` 等写法）。

- - 字段**值**用配置语言（`[agent] lang`）书写；key、标记、标签保持英文。

- - 该块同时是 TUI thinklink 面板的显示内容和 ultimate 压缩的重建原料；**解析失败不会报错，只会静默丢失**，所以格式必须严格遵守。

- - 目前 Director、Coding、Browser 的 prompt 强制该格式（`browser.prompt.md` 的 Thought Block Contract）；Repo/Chat/DevOps/Meta 未要求——这三个子 Agent 虽然也建了 per-Run thinklink store，但没有 T&P 块，ultimate 重建只剩原始任务输入。

-

- ---

-

- ## 11. 已知坑

- 1. **本文档之外的旧资料普遍过期**：`docs/ARCHITECTURE.md` 与 `README.md` 里的部分描述（模块图、`pkg/`、工具数）落后于代码；以本文件和源码为准。

- 2. **`dist/` 被 `.gitignore` 忽略，但 `dist/data/models.json` 与 `dist/bin` 里的文件是被跟踪的**。改目录后 `git add -f dist/...`，否则 `go:embed` 编不过、或二进制继续用旧数据。

- 3. **模型目录与配置里的 `context_window` 是两个消费者的不同口径**：

- - 压缩阈值（`compression/threshold.go` 的 `ResolveThreshold`）= 目录命中值（`limit.context × 0.75`）与

- `[enhanced_commander] context_compression_threshold` **取小**（两者都是上限）；没写配置就纯按目录推导；

- **provider 的 `context_window` 完全不参与**。

- - TUI 上下文进度条（`tui/tui_model.go` 的 `contextWindowFromCfg`）= **provider 的 `context_window` 优先** → 未设置才查目录。

- 所以给目录里已收录的模型手写一个不同的 `context_window`，只影响进度条，不影响压缩时机。

- **想临时压低阈值做验收**有两条路：写一个小的 `context_compression_threshold`（会被 min 采纳），

- 或设 `YAGENT_COMPRESS_THRESHOLD`（跳过目录与配置、且不缓存取值，非法值原样回落）。

- 生产配置不要用后者 —— 它绕过一切，会让压缩早于模型真实容量触发，白丢上下文。

- 4. **压缩的配置历史上写过两次假开关**：模板里曾经既有 `[enhanced_commander] enable`（必须与

- `enable_context_compression` 同时为真）又有 `enable_ultimate_compression`（见 false 就被写回 true）。

- 两个坑在 2026-10-16 一并修掉：压缩现在只有一个键，第三档靠**键的存在性**决定默认开、显式 false 就真关。

- （更早那条"`default_config.toml` 里有一段 `[context]` 表 `Config` 不解析"已经名不副实 —— 那段没了。）

- 5. **声明 ≠ 可用（已消解）**：`Registry.Validate()` 双向对账 schemas.json 与 Spec，"声明了没人实现"

- 是启动错误；工具面由画像派生，golden 基线（`internal/agents/testdata/tool_surfaces.golden`）钉住

- 每个 Agent 实际拿到什么。加工具若只改 schemas.json 不改 Spec，`check_no_manual_lookup.sh` 与

- `TestRegistryMatchesSchemas` 会立刻报。

- 另：`mcp` 客户端的 `sendJSON` 已加写锁 —— 并发只读工具（codeseek 桥接那批现在可并发了）依赖它。

- 6. **TUI 事件通道无重放**：`listenForEvents` 是一次性 cmd，谁消费了事件不重新武装监听器就会永久断流；

- 弹窗守卫只放行少数消息类型（`tea.PasteMsg` 不是 KeyMsg）。任何新增叠加模式/守卫都必须显式放行需要的消息类型并 re-arm。

- 7. **布局高度必须自洽**：`computeFooterHeight` 与 `View()` 的 footer 组装顺序要完全一致，差一个空行整屏抖动；

- `viewport.SetHighlights` 在我们的重着色日志上会算错偏移，改用 `StyleLineFunc`。

- 另：`lipgloss.Style.Height(h)` 是**含上下边框**的总高（实测 `Height(5)` 装 3 行内容 → 输出 5 行，内容多了就撑破），

- 所以给一个面板里的若干段分配行预算时要按 `height-2` 算；按 `height` 算会多要 2 行，

- 被 `renderDashboard` 末尾的"行数收敛 + 补边框"悄悄截掉，表现是最后一段莫名少两行而不报错。

- 8. **browser-control 的状态目录是进程 CWD 相对路径**（`.browser-control/`），上游没有任何环境变量可改这个根：

- 所有调用必须带 `cmd.Dir`（指向 `~/.yagent/data/browser/{delegation}`）。漏设就会在用户仓库里长出该目录——

- `internal/browserctl` 已把它固化成唯一入口，新增调用点不要自己拼路径。

- 9. **上游 `reload` 实际等于 `stop`**（README 写 "minimal lifecycle reset"，但 `src/main.rs` 里

- `Cmd::Stop | Cmd::Reload => lifecycle::stop()`），刷新页面要用 `eval 'location.reload()'`；

- 上游也**没有** `hover` / `back`，需要用 `browser_eval` 派发 `mouseover` / 调 `history.back()`。

- 10. **无 CDP 环境变量时上游会硬扫 9222/9223**：必须显式注入 `BROWSER_CONTROL_CDP_URL`，

- 自启端口从 `cdp_port_base`(9333) 递增且跳过 9222/9223，否则会连到用户自己的调试浏览器或另一个任务。

- 另外上游内部 CDP 超时默认仅 15s，`browserctl` 会按最长 wait 把它抬到 ≥65s，别在别处重复注入这个变量。

- 11. **便签索引必须是派生态、且瞬态**：`messagesForLLMCall` 只在**这次 LLM 调用**的消息上附加索引，

- 返回值绝不写回外层 `messages`（`planner_run.go` 传的就是返回值）。

- 一旦漏回，下一步的压缩预算会把目录算进正文、紧急压缩还会把它当成一条用户输入折叠进摘要 ——

- 那正好是它要解决的病（`note:`/`artifact:` 引用消失在 tool 消息里）。

- `TestMessagesForLLMCallIsIdempotent` 与 `TestIndexSurvivesEmergencyCompressionShape` 钉住这条不变量。

- 12. **`agent_exit` 收尾的 Agent，交付物不在 `Text` 里**：`RunAgentLoop` 在这条路径上把 `Text` 设成

- `{"finished":true,"reason":...}`（`executor.go` 的 stop 分支），真实分析在最后一条 assistant 消息。

- 便签正文与 artifact 全文一律经 `deliverableText()` 取，判据是"JSON 里有 `finished:true` + `reason` 键"

- 这个**形态**而不是 Agent 名字；`AgentResult.Text` 的既有语义没动（超预算时仍是摘要），

- 需要全文的下游读 `AgentResult.Deliverable`。

- 13. **`[blackboard]` 的三个阀门靠"键存在性"而非零值**（`md.IsDefined`）：`index_max_notes = 0` = 关索引、

- `index_line_chars = 0` = 不裁剪行、`ttl = "0"` = 不清理；"没写这一段"解析出来同样是 0，

- 只看零值会把用户的关闭意图当成没写（或反之静默关掉新能力）。不设 `enabled` 键，

- 整体关闭是 `YAGENT_BLACKBOARD=0`（`blackboard.Enabled()` 是写/读/注入/清理四处共用的唯一判据）。

- 14. **Bedrock 豁免已整体删除**：以前 `config.validate()` 用 `strings.HasPrefix(effectiveProvider, "bedrock")`

- 跳过 `api_key`/`api_base_url` 并要求 `aws_region` —— 而本仓库没有 Bedrock 专用客户端，豁免只会把失败

- 推迟到第一次调用（空 base_url），同时"名字不带 bedrock 的真 Bedrock"反而被要求填密钥。

- 现在所有 provider 一视同仁，`aws_region/aws_profile/model_provider` 三个键连字段一起删了。

- **仍然成立的教训**：这段豁免和**整段缺省归一化**挤在同一个函数里，以前它写成 `return nil`，于是

- max steps、`[browser]` 缺省、TUI 键位、压缩参数全部停在零值（表现不是报错，是能力静默缺失）。

- 往 `validate()` 里加提前 return 之前，先确认下面的归一化段还会被执行；

- 回归由 `internal/config/validate_test.go:TestLoadFromFile_BedrockNoLongerExempted` 钉住

- （它同时断言"归一化照常发生"，就是因为那条历史教训）。

- 15. **`toolspec.Validate()` 的每条规则都必须有能触发它的夹具**：`IsReadOnly()` 的定义含 `!Serial`，

- 所以曾经那条 "Serial 与 IsReadOnly 冲突" 在数学上不可能成立 —— 它既不会响，又与 `Serial`

- 字段"无副作用也必须串行"的文档承诺矛盾，已删除。教训：只测"生产注册表没有 problems"等于

- 没测，删掉任何一条规则都不会有人发现。见 `registry_test.go:TestValidate_ReportsEachRule`。

- 16. **子 Agent 的 `agent_exit` 会不会真的收尾，取决于 `cfg.StopOnFinish`**：`RunAgentLoop` 的判据是

- `cfg.StopOnFinish && tc.Function.Name == "agent_exit"`，而这个标志是各 Agent 自己在

- `ExecutorConfig` 上逐个设的。`repo.go` 曾漏掉它 —— Repo 的 prompt 明确指示"以 agent_exit 收尾"，

- 于是收尾信号只是"又执行了一次工具"，循环继续烧到 MaxSteps，交付物变成后续那几轮的文本。

- 连带后果在便签/artifact 上：`deliverableText()` 取的是最后一条 assistant 消息，

- 所以便签正文与 artifact 全文存的都不是那份交付。现在由

- `internal/agents/e2e_{handoff,lifecycle}_test.go` 钉住（委派只花 1 次 LLM 调用），

- 新增子 Agent 时漏设 StopOnFinish 会直接红。

- 17. **暂停不是取消，两者弄混会静默丢工作**：A 层的闸门（`internal/pause`）**不取消 ctx**，只在

- step 边界阻塞；取消会解开调用栈，并把那次委派的工具结果写成 `"Error: context canceled"`，

- Director 于是以为"委派失败了"并自行重做或收尾。三条必须记住的推论：

- ① 暂停期间必须显式冻结 `activity` 的 idle **和** total —— `Heartbeat` 只能续 idle

- （`totalElapsed` 取自创建时固定的 `startTime`），只处理 idle 的表现是"暂停 20m 后被总超时杀掉"；

- ② `activity.Resume` 必须把空闲基准推到恢复时刻，否则第一个 tick 就算出

- `idleFor = 暂停时长`，**刚恢复的任务立刻被杀**；

- ③ 暂停态绝不能走 `handleTaskCompleteMsg` 的换 ctx 分支（它会丢掉闸门所在的那棵 ctx）。

- 另外：`/` 前缀在 TUI 里默认是**搜索**，新命令必须显式列进 `processCommand` 的斜杠分支，

- 否则 `/pause` 是在搜字符串 "pause"，界面上什么都没发生。

- 18. **"两份同形实现"必须各自有输入进聚合测试**：`agents.classifyStop` 与

- `director.StopKindOf` 因分层守卫（`check_no_agents_import.sh`）只能各写一份，取值靠

- `memory.StopKind*` 对齐、行为靠 `TestStopKindClassifiersAgree` 对齐。P1 加 `paused` 时，

- 值表先加了 abandoned 输入而聚合表没有 —— 结果**只有一边漂走**时聚合测试是绿的，

- 补上输入才红得出来。加词表值时的正确顺序：先给聚合测试喂一个新输入，再让两边实现去追它。

- 19. **检查点指纹只能由读侧计算**：`agent_checkpoint.digest` 存的是写侧那一刻对**整个文件重建成**的

- 消息序列算出的 sha256，但比较发生在 `ReadRolloutForReplay` 用**同一套规则**重算之后 ——

- 而这套规则包括"用 `compacted` 记录替换被压过的前缀"。如果指纹是写侧按内存里那份消息算的，

- 任何触发过压缩的会话（=每一个长任务）都会在自己的检查点上对不上号，B 层恰好死在它

- 最该起作用的地方。`TestWriteCheckpointDigestMatchesReplay` 钉的就是两侧规则同源。

- 20. **`Reasoning` 从此才真的进 rollout**：`memory/rollout_convert.go` 现在会为 thinking /

- `reasoning_content` 发一条 `reasoning` item。此前它**从来没有被持久化**，

- 于是"重放出的消息与暂停前逐条同形"这条承诺缺一大块（token 估算与 ultimate 压缩都算它）。

- 改任何一边的转换都要记得 `DigestMessages` 把 `Reasoning` 算进指纹：漏算不是"少几个 token"，

- 是"整次重放被判成不可信、静默降级成交接报告"。

- 21. **检查点写在终止路径，不写每步**：两个循环各只在终止/deadfer 块里落一条 `agent_checkpoint`

- （`executor.go` 的 `writeExecutorCheckpoint`、`director/planner_rollout.go` 的 `aborted`）。

- 每步一条会让 150 步的会话多出 150 条记录，而重放永远只关心最后一个停点；

- `TestNoPerStepCheckpointWritten` 钉住这条。想加"每步检查点"前先想清楚恢复侧怎么选。

- 22. **降级不是错误**：`assessReplay` 命中判据时 `resumeDelegation` 返回的是一份**报告文本 + 理由列表**，

- 不是 `error`。把它写成 error 的表现与 §11 坑 17 同类 —— Director 认为"这次委派失败了"，

- 于是把已经做完的工作重做一遍。同理，重放成功后交回的是**同一个 `call_id` 的第二条 tool output**

- （last-wins 覆盖），模型看到的是"那次委派成功返回了"，而不是一条新消息。

- 23. **"扫目录再计数"的测试必须拥有那个目录**：`internal/memory` 的测试**不像 `internal/agents` 那样

- 把 `$HOME` 隔离到临时目录**，所以 `TestScanResumeCandidates_ClassifiesEveryStopKind` 这类

- "往 `~/.yagent` 写夹具再扫"的用例在 `-count=4 -parallel 8` 下会把候选累加（24/36/48 条），

- 断言 `>=1` 恒真 —— 门禁当场失效。每个 run 生成唯一 projectID（或 `t.Setenv("HOME", t.TempDir())`）。

- 24. **`pause` 的 `AbandonedError` 要 `errors.Is` 到 `context.Canceled`**：toolbatch 的取消短路、

- `delegateTo` 的错误分类、`looksLikeCancelledContext` 的文本匹配都认它。

- 换成孤立新错误的表现是"取消了但没人认为是取消"，Director 把它当成一次失败的委派继续往下跑。

- 反过来，便签侧要区分"停住"与"失败"用的是 `errors.As`（`writeDelegateNote` 对 abandoned

- **什么都不写**，词表里因此没有 `paused`），两件事都要保留。

- 25. **"配置项存在"不等于"配置项生效"**：本轮删掉的 13 组键里，大多数不是没人读，而是**读了也没用**

- （`enable_streaming` 只进 `slog.Debug`；`auto_checkpoint` 只打一条每步 deprecation 警告；

- `[codeseek.knowledge] enabled` 被 `validate()` 写回 true，因此连"关掉"这个动作都不成立）。

- 判断标准只能是"改这个值，有没有一条用户可观察的行为会变"。新增配置项时请同时新增

- 一个**能因为改值而失败**的测试；`removed_keys_test.go` 要求登记表与夹具互为镜像，

- 就是为了不让"承诺会点名"变成第二句空话。

- 26. **布尔键的"缺省为真"必须靠键的存在性实现**（`md.IsDefined` / `sectionHasDecodedKey`）：

- Go 零值是 false，直接看值就分不清"没写"与"写了 false"。`enable_ultimate_compression` 之前

- 用"见 false 就写回 true"绕过，结果那个键永远关不掉；`[git_checkpoint]` 之前用

- "前缀为空就整段换默认值"绕过，结果只写 `enabled = false` 会被顶回 true。

- 正确形状见 §6.5 的第三档与 §11 坑 13。

- 27. **写 config.toml 只能文本级替换**：`persist.go` 的内核是 `SetKeyInSection`，

- 用 `toml.NewEncoder` 整份重编码会把用户注释全部蒸发（模板里每个键都靠注释自我说明）。

- 两个例外规则也要记得：值一律 `tomlBasicString` 转义，且"删一个 provider"前必须查引用

- （`ProviderRefs`），否则会写出一份"下次启动加载失败"的文件。

- 28. **向导既能独立跑也能嵌进主 TUI，所以它不碰 Yagent/Dispatcher/MCP**：`setupWizard` 只读

- 配置文件文本（`config.DecodeRaw`，故意绕开 `LoadFromFile` —— 配置坏的时候正是最需要它的时候）、

- 写文件、最多发一次最小 LLM 请求。`/setup` 在任务运行中直接拒绝，因为它独占键盘而

- `listenForEvents` 没有重放队列（坑 6）；`applyOps` 是逐条落盘、**不是事务**，

- 所以失败信息必须带上"哪一条 note 失败了"。

- 29. **TUI 键位是"替换"不是"追加别名"**：翻译表把按下的键映射到**规范键名**（各 switch 分支的字面量），

- 所以自定义键 → 规范键，而被换掉的默认键 → 空串 = 解绑，消费点经 `translateKey` 换成

- `keyUnbound` 哨兵落到 default 分支。旧实现只有 `editKeyMap[custom] = default` 这一半，

- 于是"把 quit 挪走"之后 `ctrl+c` 仍然退程序，而且默认键永远释放不掉。

- 两个附带约束：抢同一个键时**保留先声明的动作**并 `slog.Warn`；`keyUnbound` 绝不能长得像真按键

- （`TestUnboundSentinelMatchesNothing`）。表单屏还在 `tab/enter` 之后把字符交给 textarea ——

- 字段自己得吃掉按键。

- 30. **TUI 的行数预算必须按"渲染后的行数"算**：`lipgloss.Style.Width()` 会把超宽的行**再折一次**，

- 所以"我数过 body 有 13 行"和屏上真正的 16 行不是一个数，面板因此能超出终端高度 ——

- 在 AltScreen 里多出来的行看不见也滚不回去，表现是"最后一屏莫名少几行"。

- 三道闸门都在计数之前做，缺一个就会复现：① `fitLines` 先把越宽的行剪断（宽度用 `lipgloss.Width`，

- 样式串里的 ANSI 不占列）；② `wrapPlain` 必须**硬切超长单词**（provider 错误原文里全是 URL、

- base64 密钥、JSON 片段，只按空白折行等于没折）；③ 状态条（错误原文）自己有预算 `capStatus`，

- 否则"正文 = 高 - 2 - 状态行"会算出负数并夹到最小值，总高反而超出终端。

- 同理，卡片/表格每一行的列宽要**正好加到容器内宽**（分隔符数量按真正拼出的列数算，

- 徽章还要算上 `BadgeStyle` 的 `Padding(0,1)`）。闸门是 `TestWizardRenderWidthMatrix`

- （宽度 {40..240} × 高度 {18,24,40} × 七屏 × 折叠/预设子模式，断言行数 ≤ 终端高度）。

- 31. **表单屏的模态键必须带修饰符**：向导的表单每一格都是活的 textarea，裸字母要先送进输入框。

- 曾经用裸 `p`（端点预设）和裸 `o`（展开可选区），于是填 `https://…` 会吃掉 `ps`、

- 并莫名打开预设列表 —— 用户看到的是"我打的字少了两个字母"。正确形状：`ctrl+p` / `ctrl+o` / `f2`

- （与主 TUI 用 `alt+s` 提交同理），只有在**没有 textarea 活着**的屏（列表、摘要、预设选择中）

- 才可以用裸键。`TestWizardHintsAreNotDecoration` 还反向钉住另一半：底栏键帽上写的每个单键

- 都必须真的能改状态，因为键帽比裸串更容易被相信。

- 32. **向导的 `done` 不等于退出，退出是宿主的决定**：`setupWizard` 同一个状态机跑在两个宿主里，

- `q` / `ctrl+c` / 摘要落盘只置 `done=true`，而 bubbletea 只认 `tea.Quit`。独立跑（`RunSetup`）

- 时必须把它翻成 `tea.Quit`（`w.standalone` + `Update` 里单点收口），否则进程停在最后一屏 ——

- 用户看到的症状是"按 q 没反应"；嵌在主 TUI 时反过来必须**不**翻，那会把整个 yagent 退掉，

- 交还键盘由 `updateSetupMode` 的 `Done()` 分支负责。闸门是 `TestRunSetupProgramActuallyExits`：

- 它用 `tea.WithInput(strings.NewReader("q"))` 真跑一次程序断言 `Run` 返回，不是只查 cmd 形状。

- 33. **测试与生产必须共用同一个载体，否则测试会钉住一条不存在的路**：子 Agent 的并行曾经完全没生效 ——

- `executor.go` 的并发谓词扫 `cfg.Adapters`，而五个子 Agent 全部只填 `cfg.Surface`，于是谓词恒 false、

- `toolbatch` 被调用却一个 goroutine 都不开；同时 `executor_parallel_test.go` 的 8 个用例都往 `Adapters`

- 里塞夹具，**所以测试全绿**。同一文件里 `resolveAdapter`/`defsForStep` 都正确"Surface 优先"，

- 只有这个谓词漏了 —— 工具注册表迁移时没跟上，而两边不对称本身就是证据。

- 修法不是补一个分支，是把 `ExecutorConfig.Adapters` 与 `DirectorAgent.Adapters` **连根删掉**

- （`resolveAdapter` 只认 Surface，判据收成 `toolCallIsParallelizable` 一个函数、两个循环共用），

- 测试改用 `tools.NewSurfaceFromAdapters`；`parallel_admission_test.go` 更进一步直接拿真实画像

- （`ProfileRepo`/`ProfileCoding`）问判据。闸门是 `TestRunAgentLoop_ReadOnlyBatch_ParallelEvidence`

- （+ 一条 `max_parallel_readonly_tools=1` 的对照臂，证明"并发峰值 ≥2"不是计量器自己的毛病）：

- 把谓词改回恒 false，它立刻红 `expected max concurrency >= 2, got 1`。

- **教训通用**：新增一个"生产只填 A、测试却填 B"的字段对，就等于埋下一个永远不会红的测试。

- 34. **流式槽的键不等于显示名**：TUI 的 `aiChunkBuffers` / `aiStreamActiveEntries` /

- `aiStreamCompletedEntries` 现在按 `streamSlotKey(event, agentName)`（`agent#delegationID`）分槽，

- 而 `le.from` / `m.currentAgent` / token 归集**必须继续用裸 Agent 名** —— 把组合键当名字用的那一刻，

- 界面标签就变成 `Coding#call_3`。两者在同一个 handler 里挨着写，是顺手会搞混的地方。

- 坐标为空时键退回裸名字，于是 Director 自己的输出与 `/resume` 恢复的存量 rollout 行为逐字不变

- （`TestLegacyStreamsWithoutDelegationKeepOldBehavior` 钉的就是"没有坐标时不许变新"）。

- 变异验证：让 `streamSlotKey` 忽略 `DelegationID` → `TestParallelStreamsSameAgentDoNotMerge` 红，

- 症状正是当年的 `"AAABBBAAABBB"` 粘成一条。

- 35. **"默认值"必须有人真的用它的默认值**：调度器文档写着"每消费者 1000 容量"，而 6 个建

- dispatcher 的地方全都手写 `NewMessageDispatcher(100)` —— 那个 1000 从来没生效过，

- 于是满载丢弃比设计早一个数量级发生，表现是"界面偶尔少字"而日志只有一条限频 warn。

- 现在统一走 `NewDefaultMessageDispatcher()`；配套的可见性是 `Dropped()` / `WarnDropped(scope)`。

- 判断一个默认值是不是活的，别看文档，看有没有调用点真的走它。

- 36. **熔断器的"查询"本身就是那次试探**（C6-d 改了这里的语义）：

- `RecoveryHandler.IsCircuitBreakerOpen() == !breaker.Allow()`，而 `Allow()` 带着

- open→half-open 的迁移副作用。half-open 现在只放**一个**探针（`probeAt` 记账），

- 于是"先查一下再决定要不要调用"的代码会**消费掉**那次试探 —— 生产安全的前提是 Director

- 每一步都在同一次迭代里"查询 → 调用 → 回报 Success/Failure"（`planner_run.go` 的

- 198/319/324 三行）；探针万一没人回报（调用方死在半路），过 `resetTimeout` 后重新放行一次，

- 所以最坏是多等一个周期而不是永久锁死。要加新的查询点之前先数一遍有几个调用点在读它，

- 并把"第二个调用者在试探回报之前必须被拒绝"这条测试一起改掉 ——

- 旧用例 `TestCircuitBreaker_HalfOpenAdmitsEveryRequest` 的注释就明确要求改写而不是删掉。

- 37. **`[llm] timeout` 与"排队"的先后是能看出来的**：在飞闸门（`llm.SetInFlightLimit`）

- 与委派池都在**建这轮 ctx 链 / 套调用超时之前**取格子。放错顺序的后果不是崩溃，而是两件

- 很难查的事：①排队时间被算进 `llm.timeout`，一次正常的排队在真正发出去之前就被判成

- "provider 慢"；②排队时间被算进 `activity` 的 idle 计时，一次"前面有人"的等待把子 Agent

- 的看门狗顶成超时。同一条理由也解释了 `MCP doRequest` 的 deadline 为什么必须

- `WithTimeout(ctx, …)` 而不是 `WithTimeout(context.Background(), …)` —— 后者会整条丢掉

- 调用方的取消链，表现就是坑 17 那一类"取消了但没人认为被取消"。

- 38. **工具回显少一个键，提交就在离开循环的那一刻静默消失**：`ExecuteAgentExit`

- （`tools/flow_control.go`）把 `handoff` 透传进返回值，Agent 侧的采集点读的就是**返回值**

- —— 而它当初没有透传 `blueprint`，于是蓝图永远不落盘、不报错、不丢日志（R6 落地时

- 由 `TestE2ERepoRunWritesBlueprintFile` 抓出，变异 M2 把它改回去立刻红）。

- **通用教训**：任何"工具层只回显、Agent 层才解读"的参数，加参数时必须同时改两处；

- 只改 schema 与解析侧，得到的是一条永远绿的路径。同类历史坑见 §11 坑 16（StopOnFinish）。

- 39. **探针 Deps 必须与生产同形，否则 golden 在钉一条不存在的路**：`read_blueprint` 注册后

- 工具面 golden 一动不动 —— 因为 golden 走 `Profile.ProbeDeps()`，而生产的 `depsFor` 恒绑

- `Blueprint` 执行器；探针没绑 → `Available` 为假 → 六个画像都"没有"这个工具。

- 这与 §11 坑 33（并发谓词扫 `Adapters`、测试自己填 `Adapters`）是同一类失效：

- **两边不对称本身就是证据**。修法是把能力加进 `testDeps()`（`toolspec/profile.go`），

- 而不是在测试里另搭一套夹具；`TestProbeDepsIsCapabilityComplete` 是那道的兜底。

- 40. **写通道挂在 `agent_exit` 上，就必须有人保证它真的被调用**：蓝图的 `blueprint[]` 与便签的

- `handoff` 都只在 `agent_exit` 那一刻被采集，而 `repo.prompt.md` 开头三档 Mode Selection 全在教模型

- "用文本返回答案"，全文一度没有一句要求以 `agent_exit` 收尾。实测 10-17~10-19 的 10 份 Repo rollout：

- **7 份 `stop_reason=plain_text`、3 份 `agent_exit`** —— 前者 handoff 与蓝图一起消失，而且不报错

- （只有 `派生起跑` 一条日志，用户看到的是"目录建了、文件没有"）。两道修复：Repo 的 prompt 加

- Output Contract（答案写完，同一轮调 `agent_exit`）+ 循环补一次收尾提醒（`NoActionRetryLimit=1` +

- `NoActionReminder`，见 §6.2）。闸门是 `TestE2EPlainTextRepoRunIsNudgedIntoSubmitting` 与

- `TestNoSubmissionNote*`（"零提交"现在必须留下一句可区分的话）；变异：把 limit 调回 0，蓝图当场不落盘。

- **通用教训**：把交付押在一个可选工具参数上时，要同时回答"模型不调它会发生什么"，

- 并且让那次"没发生"在日志里可读。

- 41. **`testdata/` 是 Go 工具链的盲区**：R2 的 8 个 fixture 写着 `const F08 = 08`（非法八进制），

- 而 `go build ./...` / `go vet ./...` / `go test ./...` **全都不看** `testdata/` 里的文件 ——

- 只有 `gofmt -l <目录>` 会报（它按目录走，不按包）。所以扫描器/树遍历类的 fixture

- 落地后请顺手跑一次 `gofmt -l`；"编译过了"不等于"夹具是能编译的 Go"。

- 42. **"像路径"不等于"是路径断言"**：I14 的散文成员校验原本对任何含 `/` 的 token 要求归属，

- 而中文技术散文里的斜杠多半是标识符列表（`Name/Brief/Effect/Frequency`、`Cold/Hot`），

- 少写前缀的真路径（`toolspec/schemas.json`、裸 `schemas.json`）又因为 `ModuleOf` 只沿目录前缀上溯

- 而永远落到根片 —— 三条提交全被判成 `path-not-in-module`，一条被拒就丢整条 claim，

- 全丢 ⇒ fold `NoOp` ⇒ **蓝图文件从未出现**（`app-2026-10-19.log:179-182` 就是这个形状）。

- 最坏的地方在于症状与"模型根本没提交"（坑 40）**逐字相同**：目录建了、文件没有，

- 差别只在日志里那两行 WARN 有没有出现。修法见 `internal/blueprint/prosepath.go`：

- 先问"它到底指哪儿"（含写短的前缀与裸文件名），再问"仓库里有没有这个东西"，

- 两者都判不了就**弃权**（同名多处、凭空路径 —— 存在性由 `where` 锚点管，那是第 5 条的活）。

- **通用教训**：任何"按形状识别 + 违规即丢弃"的校验，夹具里必须放一条**与违规串同形的正常散文**，

- 否则它只会在一堆永远不会出现在生产里的路径上绿灯（`TestProsePathMustBelongToModule` 原本三条

- 全是空格分隔英文 + 从根写全的路径，假阳性形态一条都没触发过）。闸门：`fold_prose_test.go` 四形

- + `TestE2ERepoRunWritesBlueprintFile`（散文形状照生产那轮）；三条变异见设计稿 §21.5。

- 43. **防线生效过但没人知道它生效过，和静默丢失只差一步**：修完坑 42 再跑一轮，症状一模一样

- （目录建了、文件没有），账目却换成了 `outside-evidence-set` ×4 —— 那轮"快速架构讲解"一次文件

- 都没读，模型照着注入的 45 片目录名编了 4 句 `purpose`，I17 拦它是**对的**。要修的是下一环：

- `agent_exit` 是终止点，fold 的拒收只进 `slog`，所以 Director 看到的仍是一次成功的委派，

- 模型也不知道自己白交了，下一轮还会这么干。现在 `BlueprintCommit.Commit` 返回一行账目，

- 经 `AgentResult.BlueprintAccount` 同时到 `FormatForDirector`（这次决策看的地方）与便签正文的

- `> [blueprint]` 尾注（下次委派与索引重扫看的地方），**不进 conclusion**（程序的账目混进结论

- = 替模型下了一句架构判断）。两处都得写：工具输出会被压缩卷走，便签正文不进索引，

- 只修一边另一边就是新的静默。三条变异见设计稿 §21.6。

- **通用教训**：任何"可选写通道 + 终止型工具"的组合，都要问"被拦下来的那一次，谁看得见"。

- 44. **动态规格不进全局注册表**：`toolspec.registry` 写着"init() 期写入，之后只读"，把 MCP 工具塞进去会同时

- 打穿三处 ——（a）`TestAgentSurfacesGolden` 走 `ProbeDeps()`，探针不知道有哪些 server，golden 会钉一条

- 生产不存在的路径（坑 39 的变体）；（b）`renderCustomAgentToolPool` 遍历 `toolspec.Specs()`，Custom Agent

- 于是拿到第三方能力，而 `Palette` 的全部意义就是"拿不到 Director 没有的能力"；（c）`Validate()` 的

- 双向 1:1 会对每个外部工具报"schemas.json 里没有对应声明"。修法不是放宽校验，是让动态规格走

- `Deps.ExternalSpecs`，在 `Surface.rebuild()` 汇合（`TestStaticRegistryNeverCarriesExternalTools` 钉住）。

- **没 annotations 一律按写处理**是同一条纪律的安全侧：判错只是多问一次授权，判对则是第三方拿到一个

- 不受守卫的写入口 —— 放宽必须写配置（`read_only` / `allow_write`），不能靠猜。

- 45. **"连接落定前收到的通知"必须补一次**：`tools/list_changed` 可能在 `initialize` 与 `markConnected` 之间到达，

- 而这时 Manager 的 `entry.client` 还是 nil，重发现会被守卫丢掉。`MCPClient` 用

- `listChangedPending` 记住它、`markConnected` 事后补一次。另外通知回调**不能**在 readLoop 里同步调用

- （回调里会发 `tools/list`，要等 readLoop 读响应 —— 那就是"读循环等自己"的死锁，表现是重发现永远超时）。