AGENTS.md@internal/agents/director git:20261021.9f5bf87A

Immutable. This exact content never changes and is served at /api/v1/blob/9e23dd871d214ad6.

# internal/agents/director — Director 编排内核

> 范围：本目录内不可派生的约束。全局见仓库根 `AGENTS.md` §6.2。
> **本包禁止 import `yagent/internal/agents`**（`scripts/check_no_agents_import.sh`）。

## 边界

Director 的编排内核：Planner 主循环、熔断与恢复、指标、便签索引注入、项目上下文加载、Meta 注册表。
不负责子 Agent 实例与委派执行（经 `ToolRunner` 回调交给门面层）、不面向用户。

## 硬约束

**1. 依赖守卫扫的是整条传递依赖闭包，且必须整行匹配**（`scripts/check_no_agents_import.sh:15-23`）——
子包路径含父串，子串匹配会误伤。跨子系统的依赖一律经 `internal/agents/ports.go` 的窄接口注入。

**2. 非测试 `.go` ≤ 300 行，存量按 PENDING 冻结。** PENDING 条目的格式是
`<相对路径>:<允许的最大行数>`（`scripts/check_file_sizes.sh:25,33`），今天只有一项：
`planner_run.go` 的上限 **572 行**（三段职责——主循环 + 压缩 + 委派编排——里只搬走了压缩那段，
657 → 572）。规则：新文件超限直接红；**改小了必须同步下调 PENDING 里的数字**，否则脚本主动报
"棘轮失步"并红。一条常红的守卫等于没有守卫。

**3. 便签索引是派生态且瞬态。** `messagesForLLMCall` 返回**新切片**，外层 `messages` 必须保持无索引
（`board_index.go:11-22`）：一旦漏回，下一步的压缩预算会把目录算进正文，紧急压缩还会把它当成一条
用户输入折叠进摘要——那正是它要解决的病。同一步重试必须幂等（`:37`）。

**4. 恢复决策不许交给模型。** `PendingResumption` 在进 LLM 循环**之前**处理，结果作为**同一个
`call_id` 的第二条 tool output**（last-wins）交回（`planner_run.go:100-110`），零 token、确定性。
让模型决定怎么恢复的后果是"同样的停点有时重做、有时接着跑"。`DelegationID` 为空时必须整份忽略，
不许塞一条没配对的 tool 消息（`:105`，`planner_resumption_test.go:127`）。

**5. 暂停闸门在 `p.state.Step = i + 1` 之前**（`planner_run.go:188-196`）：这一步根本没跑过，
推进游标会让恢复侧多算一步。

**6. 检查点只在终止路径写**（`planner_rollout.go:10-12,49-59`），与子 Agent 共用
`memory.WriteCheckpoint`——父子两个写入包不能互相 import，抄一份必然分叉。

**7. 两个"看起来更方便"的签名决定是刻意的。** `EventPublisher` 刻意**不含** `ForDelegation`
（`planner.go:14-16`，Director 每任务只有一个，不会与自己混流）；`ToolRunner.Call` 的 `callID`
必须是显式参数而不是塞进 ctx（`:30-34`）——接口漂移要在编译期炸，ctx 里悄悄传的后果是恢复侧拿到空
`delegation_id`、把能救的会话判成不可重放。

**8. 熔断开不了就永远不建。** 阈值 0 = 不创建 breaker（`recovery.go:46-49`），"Director 绝不能因为
网络抖动停摆"。熔断器的"查询即试探"语义见 `internal/AGENTS.md` 的 recovery 一节。

**9. `StopKindOf` 的词表顺序是硬约束**（`stop_kind.go:42-49`）：`DeadlineExceeded` 与 `abandoned`
都必须排在 `cancelled` **之前**，因为 `AbandonedError` 能 `errors.Is` 到 `context.Canceled`。
本包与 `agents.classifyStop` 是两份同形实现（分层守卫逼出来的），靠
`TestStopKindClassifiersAgree` 对齐；加词表值时的正确顺序是**先给聚合测试喂新输入**，再让两边实现追它
（根 AGENTS.md §11 坑 18）。

**10. 强制委派提醒的次数上限必须导出**（`MaxNonDelegationPrompts`，`planner_run.go:19-21`）：
曾经 `agents` 侧有一份只有测试在读的同名常量。

## 入口

`planner.go`（全部窄接口契约）、`planner_run.go`（主循环，行数债所在）、`board_index.go`
（最短的不变量读法）、`stop_kind.go`（词表与顺序）。

## 闸门

- `TestMessagesForLLMCallIsIdempotent`（`board_index_test.go:70`）、
  `TestIndexSurvivesEmergencyCompressionShape`（`:106`）。
- `TestPlannerCommitsResumedDelegationWithoutCallingLLM`（`planner_resumption_test.go:22`）、
  `TestPlannerWithoutResumptionIsUnchanged`（`:112`，钉"没有落点时不许凭空塞 tool 消息"）、
  `TestPlannerIgnoresResumptionWithoutCallID`（`:130`）。
- `TestPlannerReadOnlyBatchParallelism` / `TestPlannerMixedBatchSegmentation` /
  `TestPlannerParallelKillSwitch`（`planner_parallel_test.go:210,245,266`）：混合批断言的是
  "写类元素执行窗口内没有任何只读元素在飞"。
- `TestPlannerRun_TriggerUsesProviderMeasurement` / `_MeasurementInvalidatedAfterRewrite`
  （`planner_prefix_trigger_test.go:52,116`）：第二/三档整段重写消息后 `measured` 必须作废，
  否则同一步下一档判定拿着不存在的规模做决定（`planner_compress.go:17-19`）。
- `TestComputeProjectID`（`project_context_test.go:103`）钉具体串；
  `TestProjectContextLoaderCacheHit`（`:59`）钉"同一实例只加载一次"。
  `project_context.go:53` 是"只读工作区根的 `YAGENT.md`/`CLAUDE.md`/`AGENTS.md`、不递归"这条
  加载契约的唯一实现。