第 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 章的 2025-11-25 快照：能力协商、stdio 或 Streamable HTTP，以及仅在双方声明后使用的实验性 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 OSS Lab

阅读 Kocoro 公开 README，找出 TUI、Daemon、Schedule 与 MCP 的共享核心。
为一个合成任务设计只有最小工具权限的 Named Agent。
编写只读成功、破坏性操作被拒绝、外部调用期间取消三个契约测试。
创建一条合成 Golden Trace 并定义后置条件。
说明哪些是公开概念，哪些必须私有。

划重点

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

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

Kocoro · 本地 Agent 运行时

把公开 Kocoro 引擎与 Daemon 作为 Agent Harness 参考，再用合成测试验证这些概念。

了解 Kocoro →