# 24 工具与执行环境

平面：执行
governed_by：D-005、D-008、D-020、D-047、D-055
用途：定义执行者能对世界做什么——工具接口本身、能力目录、可隔离可观察的执行环境，以及外部动作的结果凭什么算数。

## 1. 最小职责与接口

- **它必须做到的**
  - 把工具接口当一等设计对象：名称与参数表达用途、副作用与不适用场景。
  - 维护能力目录——可调用的动作及其副作用声明——并与权限边界分开维护。
  - 提供隔离的工作区与可观察的环境反馈，让动作后的实际状态可被重新读取。
  - 把确定性判断交给程序，模型只补判残余。
  - 为长时与异步动作提供可重读的持久完成标记。
  - 让外部写入可幂等重试，并把结果的第三态表达出来。
  - 为每个工具标注内部或外部；标为外部的适用第六条不变量（写限阶段窗口、幂等、留回执、可用性不保证），见[架构确定 §5.3](架构确定.md#invariants)。
- **从别的部件拿什么**：从[31 守卫与权限边界](31-守卫与权限边界.md)拿本次运行的权限上限、需要授权的动作与不可逆动作清单；从[10 意图与验收](10-意图与验收.md)拿"目标是否绝对可校验"所依据的验收标识；从[33 评估与演进](33-评估与演进.md)拿工具选择与调用在真实任务上的评估结论；从[40 人的检查点与授权](40-人的检查点与授权.md)拿不可逆动作的授权。
- **给别的部件什么**：给[25 执行者与模型](25-执行者与模型.md)可调用动作及其副作用声明；给[22 上下文装配](22-上下文装配.md)工具返回的形态与大小上限（返回内容的进出策略在该章）；给[30 验证与测试](30-验证与测试.md)环境回读与持久完成标记，作为独立于生产者的观察；给[32 证据与追踪](32-证据与追踪.md)调用记录、产物清单与回执；给[20 状态工件](20-状态工件.md)外部写入的三态结果与待补偿项。
- **它自己维护什么**：工具接口定义与副作用声明、能力目录与其中每项在跨边界关系中的角色标注及该关系的三项可执行前提（见[架构确定 §5.3](架构确定.md#invariants)）、隔离工作区的配置、幂等标识与回执、持久完成标记的约定。
- **未决**：无。原"外部系统交接"待定节已由 D-047 裁决删除，纪律并入第六条不变量。

<a id="aci"></a>

## 2. 原则

- **P1 工具接口是一等设计对象，值得与提示同等的投入。** 名称与参数直接表达用途、副作用与不适用场景；相似工具之间边界清楚，模型不必猜该用哪个；目标绝对可校验，不留"大概是这个对象"的相对指代；错误返回含下一步诊断而不只是失败。用真实任务测试模型能否正确选择与调用。工具自身的输出最小、结构化、高信号；这与事后对输出做有损压缩是两件事，后者另受[22 上下文装配](22-上下文装配.md)的有损观察压缩条款约束，不能用来替代接口设计。｜防的失败：模型选错工具或在同一处反复试错；接口歧义被误诊成模型能力问题；把接口设计问题当成上下文问题去压缩，反而把线索滤掉 ｜删除条件：写不出（责任结构型：接口是人与组织的设计产物）；其中"输出最小、结构化、高信号"属能力补偿类，模型不再受输出长度影响时可收窄
- **P2 更多工具不等于更强能力。** 每增加一个工具都增加选择与维护成本；能力目录的增长须能说明它解决哪个已登记的失败，接入数量本身不是成果。｜防的失败：接入清单越来越长而任务成功率不动 ｜删除条件：模型在大规模工具集上的选择精度不随规模退化
- **P3 能力目录与权限边界是两回事。** 能力目录回答"有哪些动作、各自有什么副作用"；权限边界回答"这一次允许做什么"。可见性过滤不是安全边界——看不见不等于做不到，而"目录里没有登记"也不等于被拒绝。边界的判据、分档、对未登记动作的默认处置与失败语义见[31 守卫与权限边界](31-守卫与权限边界.md)。｜防的失败：把可见性当授权；未登记的动作被默认放行 ｜删除条件：写不出（责任结构型：可见性由装配决定、权限由授权决定，两者混同时误放行的后果由授权方承担而装配方不承担。**不标起始档**：即使 L0/L1 只有一份命令清单，"看不见不等于做不到"仍然成立，标晚会放行本该拦住的东西）
- **P4 确定性判断先由程序做，模型只判残余。** 同输入应同输出、规则可完整表达的问题用普通程序，不每次调用模型重新判断；模型只补判程序标记为不确定的部分，且不得推翻程序已判的项。可确定的规则下沉到程序、检查器、权限或闸门，下沉的时机由观察到的违规触发而不是一开始就全下沉。｜防的失败：确定性步骤产生随机错误与无谓消耗 ｜删除条件：模型对同一输入给出可证明一致的输出、且其单位成本不高于等价程序时，"先由程序做"退化为一次成本选择（能力补偿类）；"不得推翻程序已判的项"写不出（责任结构型：判定权的归属不因谁更准而转移）
- **P5 长时或异步执行的成功判据是可重读的持久状态。** 执行通道的即时输出只说明动作曾被发起；带任务标识的完成标记，或目标状态出现预期变化，才是观察。自动化运行须记录它实际消费的输入版本，"已生效"只对照该记录判定——工作副本领先于运行实际消费的输入时，"修复已生效"不成立。工具的副作用由系统直接观察或由工具自己声明，不由模型转述。｜防的失败：长动作被置于后台后误判失败并重发；产生了产物却不汇报；改了东西不查下游 ｜删除条件：执行通道保证同步且不截断、工具声明副作用时，探测形态可删；"回读持久状态"作为证据要求不删
- **P6 外部写入在回读前是未定，重试须幂等，更新类动作先读后写。** 写入结果允许第三态未定（UNDETERMINED，结果未知），不得记为成功或失败；解除未定只能靠回读。重试须带幂等标识，未定状态下不得无幂等标识地重试。更新类动作在参数不完整时先回读当前对象状态再提交，不得整体覆盖。未成功的写入进入待补偿记录，依赖它的状态在补偿完成前不得宣告；记录形态与恢复语义见[20 状态工件](20-状态工件.md)。｜防的失败：中断后重复写入或误报完成；残缺参数覆盖完整数据 ｜删除条件：执行环境对外部写提供恰好一次语义并同步返回确定结果时，幂等标识与待补偿记录的机制形态可删（能力补偿类）；"结果未知不得记为成功或失败"写不出（责任结构型：它约束的是宣告完成的权利，见[30 验证与测试](30-验证与测试.md) §2 P1）
- **P7 隔离工作区是环境能力，不是纪律。** 动作的影响范围由环境限定，而不是靠指令要求执行者别越界；环境须提供可观察的反馈——动作之后的实际状态可以被重新读取，否则只能听模型自述。自治程度应随可读性、测试、权限与恢复能力提升，而不只随模型能力提升。｜防的失败：越界修改靠自觉；无法观察结果的动作只能由模型自证 ｜删除条件：写不出（责任结构型：把越界的防止交给指令，等于把后果留给没有拦截能力的一侧，与[23 方法库](23-方法库.md) §2 P1 同构）

## 3. 从 L0 到 L3

| 档 | 形态 |
|---|---|
| L0 一人一工具 | 命令行加一份工作副本；"工具"就是几条命令，关键是每条命令的结果能被重新读出来。 |
| L1 一人多会话 | 工具定义写清用途、副作用与不适用场景；长动作留下带任务标识的完成标记，而不是靠盯屏幕输出。 |
| L2 团队 | 能力目录与权限边界分开维护；确定性检查已下沉为程序；外部写入带幂等标识与回执，未定结果显式登记。 |
| L3 无人值守 | 隔离工作区与可观察反馈是运行前提；未定的写入结果不得被折算为成功；待补偿记录非空即不得宣告完成。 |

## 4. 追溯

本章的写作期内容——它解决什么问题、源章节与主题综合的映射、每条原则的证据强度——在[追溯账本](追溯账本.md#ch-24)，效力为零。