第 33 章：Building on the Harness — Kocoro

只有把身份、状态、权限、集成、自动化与验证写成明确契约，模型循环才会成为产品。

公开来源边界：本章只使用 Kocoro 公开仓库记录的概念与命令。该仓库包含开源引擎、CLI 与 Daemon；原生 GUI 产品 Kocoro Desktop 是独立闭源产品。本章不使用私有代码、生产配置、事故、客户数据或专有资产。

33.1 从循环到运行时

持久运行时在执行循环外增加独立契约：

层	契约
身份	哪个 Named Agent、指令、模型策略与工具生效？
Session 状态	哪些消息、事件和远程任务属于同一次工作？
Memory	哪些事实可跨 Session 保存，来源与作用域是什么？
权限	什么被封锁、允许或必须人工决定？
集成	本地工具、MCP Server 与渠道如何连接？
自动化	用户不在终端时，什么会触发工作？
验证	什么证据证明成功、安全失败或取消？

切换 Agent 或触发来源不能绕过共享权限与执行核心。

33.2 当前公开入口

shan                              # 交互式 TUI
shan "review this directory"      # 一次性任务
shan --agent ops-bot "check it"   # Named Agent
shan daemon start                 # 本地 Daemon
shan mcp serve                    # stdio MCP Server
shan schedule list                # 查看 Schedule

命令会演进，因此公开 README 与 CLI help 才是操作事实来源。稳定原则是 TUI、Daemon、Schedule 与 MCP 工作汇入同一个 Harness。

33.3 Named Agents 与状态边界

Named Agent 组合指令、模型策略、工具范围、MCP 范围、Sessions、Memory 以及可选命令或 Skills。安全配置遵循：

最小权限：只给任务所需工具和网络目标。
来源可见：运行时能解释每个最终配置值的来源。
避免意外继承：切换 Agent 时重建工具与集成范围。

工作 Context、可恢复 Session 记录与持久 Memory 必须分离。压缩是有损的，只保留有证据、时间和作用域的持久事实。Small 模型抽取是成本选择，不是正确性保证；结果仍需去重、矛盾处理、隐私过滤与评估。

33.4 权限与不可信结果

授权属于运行时，不属于模型。稳健路径包括不可覆盖的破坏性操作封锁、操作者拒绝规则、复合命令分析、高风险参数特殊处理、有作用域的允许规则和其他操作的显式审批。

自动审批不是全局信任开关，必须受工具、参数、路径、目标和触发来源约束。

工具输出是不可信数据。限制大小，必要时把完整结果保存在 Prompt 外，标记截断，绝不能把网页或 MCP 结果里的文字重新解释为系统指令。

33.5 Daemon、渠道与人工介入

消息到达
  → 验证并识别来源
  → 选择 Agent 与 Session
  → 通过共享 Harness 执行
  → 必要时等待审批或用户输入
  → 流式输出事件
  → 持久化明确终态

渠道元数据只是数据，不是权限。Slack、Webhook、浏览器页面或 Desktop 事件不能自行扩大权限。需要人工输入时，应保存可恢复的 Pending 状态。取消、超时、重启和重复投递都要有定义。

33.6 双向 MCP

公开 Kocoro 运行时记录了两个角色：

MCP Server：通过当前 shan mcp serve 命令暴露已批准的本地工具。
MCP Client：把 Agent 连接到配置好的外部 MCP Server。

两者都保持与交互模式相同的权限、审计和不可信输出边界。遵循第 4 章的 2026-07-28 现行模型：协议核心无状态、每次请求自描述，stdio 仍适合本地子进程；远程集成以独立 HTTP 请求设计。Tasks 是确认支持后才使用的可选扩展，而不是协议核心的全局任务系统。这里必须核对具体实现：稳定版 Python SDK v2.0.0 已实现新核心，但 release note 明确说当时尚未实现 Tasks。

33.7 Schedule、Watcher 与 Heartbeat

触发器	适合	主要风险
Schedule	固定时间工作	重复或漏执行
File Watcher	响应状态变化	事件风暴与半写入
Heartbeat	定期判断是否需关注	噪音告警与 Token 浪费

它们都需要防重叠、有限重试、幂等键、静默成功、可见失败和禁用方式。自动触发通常应比交互用户拥有更少权限。

33.8 Agent 评估与发布工程

Demo 问“能否成功一次”；发布关卡问“变更后能否持续、安全地成功”。

契约测试

校验工具 Schema 与代表性错误；
用精确参数边界测试允许、拒绝和审批；
验证 Session、Agent 与工作目录隔离；
断言取消和超时终态；
验证重试不会重复副作用。

Golden Trace 与回放

保存合成、无敏感信息的轨迹，包含意图、选中工具、归一化结果、审批和最终后置条件。Prompt、模型、工具或策略变化后回放，比较语义与安全决策，不比较逐字文案。

故障注入

测试模型不可用、MCP 响应畸形、结果过大、Daemon 断连、消息重复、文件半写入、Session 过期与审批期间重启。安全失败可以是正确结果；挂起或伪造成功不可以。

质量与发布关卡

测量任务验收、无证据论断、引用质量、权限违规、Prompt Injection 抵抗、恢复率、延迟与总成本，并区分确定性后置条件、校准后的模型评分和人工审查。

单元与契约测试
  → Golden Trace 回放
  → 对抗与故障注入
  → 隔离 Canary 或 Shadow Run
  → 受监控发布
  → 回滚证据

回滚、取消和审计检索也实际演练后，发布才算完成。

33.9 安全公开边界

可进入本书	必须私有
公开 README 命令与架构概念	私有源码或未发布 API
通用状态机与权限模式	生产拓扑与凭据
合成轨迹与示意值	客户 Prompt、文件与消息
公开 OSS 链接	内部事故与识别指纹
通用评估方法	专有 Prompt、阈值、数据集与结果

把私有经验改写成厂商无关的不变量和合成示例。不要保留能重建原系统的标识符、精确值、时间线或拓扑。

划重点

平台在循环外加入身份、状态、权限、集成、自动化和验证契约。
Kocoro 引擎、CLI 与 Daemon 是公开 OSS；Kocoro Desktop 是独立闭源产品。
Named Agent 缩小作用域，不能意外继承权限。
交互、Daemon、Schedule 与 MCP 共享一个策略和执行核心。
评估需要契约、回放、故障注入、Canary 与回滚。
只发布概念经验与合成示例，绝不泄露私有实现资产。

本章说明了为什么循环外需要一层 Agent Harness。Part 10接下来会进入这层边界内部，讨论长上下文、进程重启、运行中追问、超时与并行工具出现时，怎样让循环继续保持连贯。