@botbotgo/agent-harness 0.0.474 → 0.0.476

package/README.zh.md

@@ -1,1203 +1,15 @@
-<p align="center">
-  <img
-    src="https://agent-harness.easynet.world/assets/readme-banner.png"
-    alt="botbotgo runtime banner"
-    width="1100"
-    height="495"
-  />
-</p>
-
-<p align="center">
-  <a href="./README.md">English</a> · <strong>中文</strong>
-</p>
-
 # @botbotgo/agent-harness
 
-<p align="center">
-  <strong>快速搭建可上线、可运维的企业级多智能体运行时。</strong>
-</p>
-
-<p align="center">
-  <strong>一个工作区即可装配成面向生产的运行时（产品级能力）。</strong>
-</p>
-
-<p align="center">
-  <a href="https://agent-harness.easynet.world/">产品网站</a>
-  （<code>docs/</code> 中的静态页，走自托管文档站；支持中英文切换）
-</p>
-
-<p align="center">
-  <a href="https://agent-harness.easynet.world/development/zh/">开发文档</a>
-  （多页面静态文档位于 <code>docs/development/</code>，支持 English / 中文）
-</p>
-
-<p align="center">
-  <a href="./LICENSE">许可证</a> · <a href="./CONTRIBUTING.md">贡献指南</a> ·
-  <a href="./SECURITY.md">安全说明</a> · <a href="./CODE_OF_CONDUCT.md">行为准则</a>
-  · <a href="https://github.com/sponsors/botbotgo">赞助支持</a>
-</p>
-
-<p align="center">
-  <em
-    >如需 AI 解决方案或产品落地支持，欢迎来信
-    <a href="mailto:info@easynet.world">info@easynet.world</a>。</em
-  >
-</p>
-
-<a id="readme-zh-start"></a>
-
-## 几行代码启动
-
-几行代码即可把工作区跑成智能体运行时：
-
-```ts
-import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
-
-const runtime = await createAgentHarness("/absolute/path/to/workspace");
-
-try {
-  const result = await request(runtime, {
-    agentId: "auto",
-    input: "Explain what this workspace is for.",
-  });
-
-  console.log(result.output);
-} finally {
-  await stop(runtime);
-}
-```
-
-目标是交付<strong>可运维</strong>的运行时：审批、恢复、可观测与治理默认就绪。`agent-harness` 在你现有的 agents、tools 与 workflows 外补齐产品级运行时层，无需推倒重来。
-
-仓库默认工作区也不是空壳，而是一套可直接体验的 starter runtime：
-
-- 一个默认 host agent：`orchestra`
-- 一条放在 `resources/tools/` 下的 runtime-owned 工具路径，适合承载文件检查、运行时检查、审批与 schedule 这类产品工具
-- 默认 host 不再预加载 bootstrap memory 或行为 SKILL，这样 first-run 本地 chat 会更轻、更快；当你的 runtime 真正需要时，再显式添加 `memory:` 文件与 `skills:` 引用
-
-如果你想最快感受 first-run 体验，直接启动 chat shell，然后试下面这些真实请求：
-
-```bash
-botbotgo
-# 或
-botbotgo "Inspect this workspace and explain the main entry points."
-# 或
-agent-harness "Inspect this workspace and explain the main entry points."
-```
-
-- `Inspect this workspace and explain the main entry points.`
-- `Review this project structure before making any edits.`
-- `Update README.md to make the setup steps clearer.`
-- `Find the likeliest config issue in this workspace and propose the smallest fix.`
-
-当 runtime 发出 request 级 `plan-state` 更新以及安全的 `progress.commentary` 增量时，chat shell 现在会直接在终端里渲染实时 todo board 和进度播报，因此你可以在执行过程中看到规划和状态变化，而不必等到最终回复。
-这些进度播报现在会继续绑定在稳定的 runtime surface 上，例如 plan-state、tool 开始/完成、memory recall 与 agent delegation，因此 operator 可以看到类似 Codex 的清晰中间状态，但不会暴露私有模型推理。
-Streaming data listener 也会收到结构化的 `plan.state`、逐条 `plan.step` 和归一化的 `execution.step` 事件，因此应用可以渲染所有 plan / execution 转折，而不必解析 assistant 文本或 raw upstream debug event。
-随包 runtime 现在也提供通用的 `response-format/default-report` 作为 agent structured-output 默认值；workspace 可以通过 `Runtime.spec.defaults.agent.config.responseFormatRef` 替换它，单个 agent 可以用 inline `responseFormat` 扩展、用 `responseFormatRef` 替换，或设置 `responseFormat: null` 关闭。
-仓库默认的 `orchestra` host 现在也会被明确要求：对已经给清楚的多步任务不要再反问，而是直接开始执行；在非平凡工具工作前先调用 `write_todos`，并在运行过程中持续维护这块 todo board。
-durable memory 的写入现在也会在模型做 mutation reconciliation 之前，先通过配置好的 vector store 检索相关旧知识，再和确定性匹配结果合并，因此 update / delete 更容易命中正确的 knowledge identity，而不是生成几条相近但彼此独立的 fact。
-
-<a id="readme-zh-docs-path"></a>
-
-## 阅读路径
-
-按你的目标选入口即可：
-
-- **想尽快接入：** 从[开发文档](./docs/development/zh/index.html)起步，再按需打开 API、协议与 Cookbook。
-- **想弄清边界：** 读[并列对比](./docs/development/zh/comparison.html)，区分运行时产品与上游执行框架。
-- **需要部署、加固或交接支持：** 查看[商业服务](./docs/commercial-pricing.md)与[合作流程](./docs/enterprise-process.md)。
-
-推荐入口：
-
-- [开发文档入口](./docs/development/zh/index.html)
-- [并列对比页](./docs/development/zh/comparison.html)
-- [API 参考](./docs/development/zh/api-reference.html)
-- [协议接入说明](./docs/development/zh/protocol-surfaces.html)
-- [发行说明](./docs/development/zh/release-notes.html)（正文来自 `RELEASE_NOTES.zh.md`，与英文 `RELEASE_NOTES.md` 对应维护）
-- [商业服务价格说明](./docs/commercial-pricing.md)
-- [专题 Markdown 索引](./docs/README.md)（`docs/*.md` 一览表）
-
-### 如何阅读本 README
-
-下文既是快速上手也是参考手册，**不必从头到尾通读**。
-
-| 可用时间 / 目标 | 建议先看 | 然后 |
-| --- | --- | --- |
-| **约 5 分钟** | [几行代码启动](#readme-zh-start) 与 [阅读路径](#readme-zh-docs-path) | 打开中文[开发文档 · 起步](./docs/development/zh/getting-started.html)。 |
-| **第一次接入** | [快速开始](#readme-zh-quickstart) → [如何配置](#readme-zh-config) | [Workspace 与 YAML](./docs/development/zh/workspace-and-yaml.html) · [`docs/` 专题索引](./docs/README.md) |
-| **运维 / 治理** | [运行时能力速览](#readme-zh-runtime-glance) → [典型应用场景](#readme-zh-use-cases) | [运行时运维](./docs/development/zh/runtime-operations.html) 与 [`docs/tool-execution-policy.md`](./docs/tool-execution-policy.md)。 |
-| **查 API** | 跳转到文末 [API 摘要](#readme-zh-api-summary) | 日常以[API 参考](./docs/development/zh/api-reference.html)为准。 |
-
-## 仓库源码分层
-
-如果你维护的是这个开源包本身，请把 `src/` 当成分层目录，而不是平铺文件夹：
-
-- `src/*.ts` 顶层文件尽量只保留稳定公共入口或兼容 shim
-- 公共 API 实现放进 `src/public/`
-- 协议服务与传输实现放进 `src/protocol/**`
-- 终端、事件投影与渲染辅助放进 `src/surface/` 或 `src/cli/`
-- 脚手架与项目初始化逻辑放进 `src/scaffold/`
-- 扩展注册、工具定义与模块装载放进 `src/tooling/`
-- runtime 内部继续放在 `src/runtime/`，持久化放在 `src/persistence/`，workspace 装配放在 `src/workspace/`
-
-新增实现代码时，优先进入对应 domain 子目录。只有当一个文件本来就属于包的公开入口面时，才新增顶层 `src/*.ts`。
-
-## 许可证与商业支持
-
-本项目采用 **Apache License 2.0** 开源许可。[查看 LICENSE](./LICENSE)
-
-核心运行时开源，可自由查看与试用。
-商业支持侧重帮助团队完成生产落地与交接，例如：
-
-- 部署与接入咨询（面向你的环境）
-- 初期环境搭建与上线协助
-- 优先故障响应与问题排查
-- 运行时治理、审批流和恢复能力加固支持
-- 定制工具、连接器与协议接入开发
-- 操作手册与交接说明（面向接手团队）
-
-正式生产运维、托管、值班与长期代运营不在默认范围内。
-若需要我方承担上述职责，将按环境与 SLA 单独评估与报价。
-
-企业级合作请联络：**[info@easynet.world](mailto:info@easynet.world)**。
-
-相关资料：
-
-- [商业服务价格说明](./docs/commercial-pricing.md)
-- [商业合作流程](./docs/enterprise-process.md)
-
-## 容易上手 · 能力齐全 · 配置与扩展
-
-**一句话：** 对外接口保持精简、运行时能力一次备齐，日常工作落在 **YAML 配置** 与 **扩展**（本地工具、SKILL、MCP）上，而不是反复搭建运行时底座。
-
-- **容易上手：** `createAgentHarness` → `request` → `stop`，以及 `subscribe`、`listSessions`、`listApprovals`、`resolveApproval` 等查询与控制能力。
-- **可复用 client 接入层：** `createAgentHarnessClient` / `createInProcessHarnessClient` 会把同一套 runtime-owned request、session、approval 与事件 API 绑定成统一的前端 client 契约，terminal、桌面壳和其他嵌入式 UI 可以共用这一层。
-- **面向跨进程 UI 的 ACP client 路径：** `createAcpHarnessClient`、`createAcpStdioHarnessClient` 与 `createAcpHttpHarnessClient` 让 UI 与 runtime 不在同一进程时，仍然可以通过 ACP 复用同一份 `HarnessClient` 契约，并保持 `request(...)` 作为唯一的请求入口，向 UI 提供完整 request snapshot 与增量 data。
-- **配置：** 路由、模型、工具、存储、后端、MCP、恢复与维护写在声明式工作区 YAML 里（见[快速开始](#readme-zh-quickstart)与[如何配置](#readme-zh-config)）。
-- **扩展：** 在 `resources/` 下放置 `tool({...})` 模块与 SKILL 包；共享工具与 MCP 写在 `config/catalogs/` 等 YAML 目录里，各 agent 再按名称白名单引用。
-- **内建运行时：** 持久化 `requests`、`sessions`、`approvals` 与 `events`；恢复与排队；流式监听；MCP 接入与对外暴露；以及后端适配——避免每个应用重复造这一层。
-
-<a id="readme-zh-runtime-glance"></a>
-
-## 运行时能力速览
-
-若你想先看「今天能直接用到什么」，可从本节读起。`agent-harness` 提供完整的产品级运行时能力，而不只是「能启动」的脚手架。
-
-- **核心 runtime API：** `createAgentHarness`、`request`、`subscribe`、`resolveApproval`、`recordArtifact`、各类查询与检查辅助 API，以及稳定持久化的 `requests`、`sessions`、`approvals`、`events` 与 artifacts 记录。
-- **前端/client 入口：** `createAgentHarnessClient`、`createInProcessHarnessClient`、`createAcpHarnessClient`、`createAcpStdioHarnessClient`、`createAcpHttpHarnessClient` 与 `HarnessClient` 让产品壳层可以复用同一套 runtime 接入层，而不是每个 UI 各自重新绑定运行时调用。`request(...)` 负责流式 request；`subscribe(...)` 负责 runtime 生命周期事件。
-- **运行时 memory 与证据能力：** `memorize`、`recall`、`listMemories`、memory policy hooks、`recordArtifact`、`listArtifacts`、`getArtifact`、`exportEvaluationBundle`、`replayEvaluationBundle`，以及 request / session 级证据导出辅助函数。
-- **协议与传输层：** `createAcpServer`、`createAcpStdioClient`、`serveAcpStdio`、`serveAcpHttp`、`serveA2aHttp`、`serveAgUiHttp`，以及 `createRuntimeMcpServer` / `serveRuntimeMcpOverStdio`。
-- **受治理的工作区运行时：** 由 YAML 持有的路由、并发、维护、MCP 策略、runtime governance bundles，以及针对敏感 memory 或声明了写入访问的 MCP 工具的默认审批门槛。
-- **策略化审批：** 受治理工具现在既可以走人工审批，也可以走 `auto-approve`、`auto-reject` 或 `deny-and-continue`，同时继续保留统一可检查的治理决策面。
-
-若你的产品需要对接外部客户端，可从本节理解边界：`deepagents-acp` 是主要的外部协议接入方向；持久化、恢复、审批与运行控制仍由 `agent-harness` 在运行时侧承担。
-协议栈分工也要保持明确：MCP 连接资源和工具，A2A 承接 agent 平台之间的 task exchange，ACP 是 client-to-runtime 边界，AG-UI 是 UI 事件面，runtime MCP 则把 operator control plane 以 MCP tools 暴露出去。
-
-## 这能解决什么问题
-
-一句话概括：`agent-harness` 把通常在 demo 之后才不得不补上的运行时工作，提前做成产品运行时的一部分。
-
-如果团队已经有 agents、prompts、tools 和 workflows，真正缺的通常不是再多一层执行，而是把这些能力沉淀成**可长期运维的软件**所需的运行时层。
-
-第一天就能直接拿到的东西：
-
-- 把 `requests`、`sessions`、`approvals`、`events` 作为可查询产品记录保存下来的 runtime
-- 能跨中断、重启和人工决策继续推进的恢复路径
-- 稳定的 request 关联与连续性元数据，让一次持久化请求能和日志、trace、fallback 过程对齐
-- 对敏感 durable memory 写入和声明了写入访问的 MCP 工具默认走审批，而不是从工具名称或 description 里推断治理责任
-- 一个工作区形态的装配模型，而不是每个应用各写一套运行时胶水
-- 即使底层 execution backend 变化，也尽量保持稳定的 runtime 契约
-
-AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更难的是运行时运维。
-
-当 demo 跑起来之后，真正的软件问题会换一种形状出现：
-
-- 更多生成式逻辑，意味着更多要观测、打断、重试和恢复的执行路径
-- 自然语言入口让审批与策略边界变成运行时要求，而不是事后补丁
-- backend、prompt 和工具变化更快了，但面向产品的控制面仍然必须稳定
-- MCP 与 provider 原生工具扩展了 agent 的可触达范围，也同步抬高了治理要求
-
-团队仍然要正面回答这些运行时问题：
-
-- 审批怎么决策、怎么审计
-- requests、sessions、events 怎么稳定可查
-- 执行被打断、失败或进程重启后怎么恢复
-- 路由、并发和维护策略怎么保持一致
-- 后端频繁变化时，怎么不让产品模型跟着漂移
-
-`agent-harness` 解决的就是这一层。它把 agent 执行留在上游，同时把应用运行时做成真正可运维、可恢复、可治理的系统。
-
-换成更直接的产品语言，就是：
-
-- 你负责工作区、agents、tools 和 prompts
-- `agent-harness` 负责持久化 `requests`、`sessions`、`approvals`、`events`、恢复能力与运维可见性
-- 你的应用拿到的是一个稳定的 runtime 契约，而不是一堆 backend 专属的运行时胶水代码
-
-具体来说，就是把这些能力沉到运行时里：
-
-- 面向产品的审批与运维控制面，而不是 backend 专属的中间件状态
-- 稳定持久化的 `requests`、`sessions`、`approvals` 与 `events` 记录
-- 由运行时持有的 tracing correlation id 与 continuity metadata，而不是 provider 私有观测句柄
-- 由系统托管的重启恢复与中断续跑
-- 面向高风险 memory / MCP 副作用的默认治理策略
-- 由 YAML 持有的路由、并发、维护与恢复策略
-- 通过适配器隔离 backend 变化，不让公共运行时模型漂移
-
-## 产品概览
-
-`@botbotgo/agent-harness` 是面向真实多 agent 产品的、工作区形态的应用运行时。
-
-它不是又一个 agent 框架，而是围绕现有执行栈的运行时层：把一个工作区变成一套可运维的应用运行时。
-
-产品定位可以概括为：
-
-- Codex、Claude Code、Cursor 是「人用 agent」的产品
-- 执行框架负责定义 agent 执行语义
-- `agent-harness` 是负责运维、恢复、审批与治理多 agent 应用的运行时产品层
-
-产品边界是清晰的：
-
-- 执行后端拥有 agent 执行语义
-- 应用级编排与生命周期管理留在 harness 中
-
-因此：
-
-- 对外 API 保持精简
-- 复杂装配与运行策略放在 YAML
-- 后端实现可换时，运行时生命周期模型仍保持稳定
-- 后端细节藏在适配器之后
-
-运行时提供：
-
-- `createAgentHarness(workspaceRoot)`、`request(...)`、`memorize(...)`、`recall(...)`、`listMemories(...)`、`updateMemory(...)`、`removeMemory(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
-- 以 YAML 描述的工作区装配：路由、模型、工具、存储、后端、MCP、恢复与维护等
-- 通过适配器对接当前执行后端，并把对外运行时契约保持稳定
-- 本地 `resources/tools/` 中 `tool({...})` 工具模块与 `resources/skills/` 的发现
-- 持久化的会话、请求、审批、事件、队列状态与恢复元数据
-
-落到实际系统里，harness 主要解决那些每个 agent 应用都不应该重复造一遍的运行时难题：
-
-- 审批收件箱与人工决策流
-- 持久化的 requests、sessions 与可查询事件历史
-- 即使发生 stream fallback 或进程重启也还能成立的 request 关联、连续性与恢复观测
-- 中断、失败或进程重启后的运行时托管恢复
-- 队列、并发、维护与运维策略
-- 即使后端变更也保持稳定的运行时记录模型
-
-本包附带的默认工作区配置刻意做成「形状完整」。随发行版提供的 YAML 对关键运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
-
-默认原则是：
-
-- 若执行后端已具备某项能力，则在 YAML 中映射并在内部适配
-- 除非问题确实属于运行时职责，否则不增加新的公共运行时 API
-
-建议从这些面向用户的文档开始（中文多页面在 `docs/development/zh/`）：
-
-- `docs/development/zh/index.html`
-- `docs/development/zh/getting-started.html`
-- `docs/development/zh/comparison.html`
-- `docs/development/zh/api-reference.html`
-- `docs/development/zh/protocol-surfaces.html`
-- `docs/development/zh/cookbook.html`
-- `docs/development/zh/release-notes.html`
-- `docs/runtime-inspection-contract.md`
-- `docs/tool-execution-policy.md`
-- `docs/long-running-coding.md`
-- `docs/long-term-memory.md`
-- `docs/memory-policy-reference.md`
-
-项目内还包含面向进阶读者与贡献者的设计说明与边界讨论；日常接入与运维以 README、开发文档与上文专题为准即可。
-
-当外部工具需要标准运行时边界时，`deepagents-acp` 是必须遵循的外部协议方向。`agent-harness` 应在该边界上严格契合 `deepagents-acp` 语义，同时继续把运行时生命周期、持久化、恢复与治理保留在 harness 内部。
-
-长链路编排的推荐形态：
-
-- 尽量由调用方显式指定要运行的 host agent
-- 想用高层执行语义、少写应用编排时，优先选择 `backend: deepagent`
-- 轻量 direct-response 或明确需要 V1 agent 语义时，使用 `backend: langchain-v1`
-
-## 有何不同
-
-- 将 `requests`、`sessions`、`approvals`、`events` 与恢复视为核心产品数据（长期可查、可治理）
-- 给运维侧提供运行时控制面，而不是把原始后端内部结构直接暴露出去
-- 将可观测性与治理留在运行时：包括 trace correlation、continuity metadata，以及高风险副作用的默认审批
-- 将 checkpoint 恢复作为系统管理的行为，而不是把 checkpoint 细节抬成主 API
-- 复杂装配与运行策略交给 YAML，代码面保持小而稳
-- 在上游库未充分产品化的运行时问题上做深做透
-
-<a id="readme-zh-use-cases"></a>
-
-## 典型应用场景
-
-下面三类用法与 runtime 的设计目标最直接对应：
-
-- 企业内部智能体运行时：审批、重启恢复、运维侧证据链，以及由策略约束的 MCP 访问控制。
-- 代码现代化运行时：长链路 coding flow、审批检查点、可恢复 requests，以及可导出的运行证据包。
-- Agent ops 与 remediation workflow runtime：并行 agent 尝试、人工 review gate、持久证据包，以及面向安全或维护任务的 operator visibility。
-- 协议桥接运行时：ACP、A2A、AG-UI 与 runtime MCP 共用一套稳定控制面，而不是为每个对外入口各写一层集成胶水。
-
-一套常见的 runtime 治理默认值大致如下：
-
-```yaml
-governance:
-  remoteMcp:
-    denyTrustTiers: ["untrusted"]
-    denyTenantScopes: ["cross-tenant"]
-    denyPromptInjectionRisks: ["high"]
-    requireApprovalTransports: ["websocket"]
-```
-
-## 什么时候该用
-
-下面这些场景适合用 `agent-harness`：
-
-- 你已经确定产品需要 agents、tools、prompts 或 MCP，但真正缺的是运行时运维层
-- 你需要把审批、重启恢复、排队调度或可查询请求记录一起作为产品能力交付出去
-- 你希望用一个 workspace 形态的装配模型取代每个应用各写一套启动和运行时胶水
-- 你想把 backend 的执行语义留在上游，同时把产品契约稳定下来
-
-下面这些场景通常不需要优先选择它：
-
-- 你只需要一次短生命周期的 agent 调用，不需要审批、持久化或运维控制面
-- 你要的是工作流搭建器或低代码自动化画布
-- 你想替代执行后端的语义，而不是围绕它们做运行时
-
-<a id="readme-zh-quickstart"></a>
-
-## 快速开始
-
 安装：
 
 ```bash
 npm install @botbotgo/agent-harness
 ```
 
-如果你希望 CLI 直接出现在 `PATH` 里，可以全局安装，然后在你自己的 workspace 根目录里运行：
+使用：
 
 ```bash
-npm install -g @botbotgo/agent-harness
-cd /path/to/your-workspace
-botbotgo
-botbotgo "Inspect this workspace and explain the main entry points."
-botbotgo -w /path/to/another-workspace "Summarize this project."
+botbotgo --help
 ```
 
-`botbotgo` 会把当前目录当作 workspace root。现在你可以直接在任意目录运行它：如果 `./config/` 不存在，CLI 会回退到内置的系统默认配置和内置资源；如果工作区里存在 `./config/` 或 `./resources/`，runtime 就会在系统默认值之上叠加你自己的配置与资源定义。
-
-开发时如果要把仓库自带的 Ollama workspace 切到共享远端，只需要在启动前设置环境变量即可：发布默认仍会回到 `http://127.0.0.1:11434` 这种本地 endpoint，而开发阶段可以通过 `AGENT_HARNESS_OLLAMA_BASE_URL=https://ollama-rtx-4070.easynet.world` 或 `AGENT_HARNESS_OPENAI_COMPATIBLE_BASE_URL=https://ollama-rtx-4070.easynet.world/v1` 覆盖到远端。
-
-如果目标机器没有 GPU 但内存很大，可以单独启动 `llama.cpp` 的 OpenAI-compatible server，并继续使用已有的 `openai-compatible` provider：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Models
-spec:
-  - name: default
-    provider: openai-compatible
-    model: local-model
-    baseUrl: ${env:AGENT_HARNESS_LLAMA_CPP_BASE_URL:-http://127.0.0.1:8080/v1}
-    apiKey: dummy
-    toolCallingMode: prompted-json
-```
-
-模型进程用 `llama-server -m /path/to/model.gguf --host 127.0.0.1 --port 8080` 单独启动。`apiKey: dummy` 会复用现有 OpenAI-compatible 的 auth omission 路径，因此 runtime 不会向本地 `llama-server` 发送 bearer auth。
-
-工作区布局：
-
-```text
-your-workspace/
-  config/
-    models.yaml
-    agent-context.md
-    runtime/
-      workspace.yaml
-      runtime-memory.yaml
-    catalogs/
-      embedding-models.yaml
-      vector-stores.yaml
-      stores.yaml
-      backends.yaml
-      tools.yaml
-      mcp.yaml
-    agents/
-      direct.yaml
-      orchestra.yaml
-  resources/
-    package.json
-    tools/
-    skills/
-```
-
-最小用法：
-
-```ts
-import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
-
-const runtime = await createAgentHarness("/absolute/path/to/workspace");
-
-try {
-  const result = await request(runtime, {
-    agentId: "auto",
-    input: "Explain what this workspace is for.",
-  });
-
-  console.log(result.output);
-} finally {
-  await stop(runtime);
-}
-```
-
-三分钟心智模型：
-
-1. 用 `createAgentHarness(...)` 指向一个 workspace root。
-2. 用 `request(runtime, { ... })` 执行一次请求。
-3. 把持久化的运行时记录当成产品资产，而不是只盯着最终回答。
-
-一句话概括：
-
-- 你的团队负责构建 agent app
-- `agent-harness` 负责让这个 app 可运维
-
-最短心智模型：
-
-- 一个工作区对应一个运行时
-- YAML 定义装配与策略
-- `request(runtime, { ... })` 在该运行时上执行请求
-- 运行时负责生命周期、可观测性与恢复
-
-## 功能列表
-
-- 多 agent 应用的工作区运行时
-- 精简的公共运行时契约
-- YAML 定义的主机路由与运行时策略
-- 在统一运行时契约之后做后端适配
-- 自动发现本地工具与 SKILL 包
-- 原生 provider 工具、MCP 工具与工作区本地工具模块
-- 持久化会话、请求、审批、生命周期事件与排队请求
-- 运行时管理的恢复与 checkpoint 维护
-- 运行结果中的结构化输出与多模态内容保留
-- 将 agent 声明的 MCP 服务桥接进来
-- 将 harness 工具对外暴露为 MCP 服务
-
-### 运行时优势
-
-- 后端细节演进时，面向产品的 API 仍可保持稳定
-- 公共运行时契约与后端适配契约分离清晰
-- 路由、拓扑、策略与基础设施对象由 YAML 明确拥有
-- 相较薄封装 agent 循环，更适合长运行、重审批、多 agent 产品
-
-## 使用方式
-
-### 创建运行时
-
-```ts
-import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness";
-
-const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
-```
-
-`createAgentHarness(...)` 会加载工作区、解析工作区 source、在 `runtimeRoot` 下初始化持久化，并启动运行时维护任务。
-
-`runtime.spec.sources` 现在是本地工具、npm 工具包与 skill package 的主公开发现入口。
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Runtime
-metadata:
-  name: default
-spec:
-  sources:
-    tools:
-      - file://./resources/tools
-      - file://../shared-tools
-      - npm://@acme/agent-tools
-    skills:
-      - file://./resources/skills
-      - npm://@acme/agent-skills
-      - https://example.com/skills/review/SKILL.md
-```
-
-tool source 规则：
-
-- `file://...` 只扫描显式配置的目录
-- `npm://...` 只解析单个包；本地缺失时会自动安装，再从 `package/tools/` 发现工具
-- tool 发现永远不会遍历 `node_modules/**`
-
-skill source 规则：
-
-- `file://...` 可以指向 skill 集合目录、单个 skill root，或直接指向 `SKILL.md`
-- `npm://...` 只解析单个包；本地缺失时会自动安装，再从 `package/skills/` 发现 skills
-- `http://...` 与 `https://...` 当前只支持一个远程 `SKILL.md`
-
-`runtime.spec.resources` 仍保留为兼容旧 attached resource package 的路径。
-
-`createAgentHarness(..., { load })` 支持工作区加载控制。
-
-合并顺序是确定性的：
-
-- 框架默认配置
-- 每个 `overlayRoots` 条目（按数组顺序）
-- workspace 根目录
-
-后者会覆盖前者；数组会被直接替换，普通对象会执行深度合并。
-
-```ts
-import { createAgentHarness } from "@botbotgo/agent-harness";
-
-const runtime = await createAgentHarness("/path/to/workspace", {
-  load: {
-    overlayRoots: ["/path/to/framework-defaults", "/path/to/product-overrides"],
-  },
-});
-```
-
-### 发起一次运行
-
-```ts
-import { request } from "@botbotgo/agent-harness";
-
-const result = await request(runtime, {
-  agentId: "orchestra",
-  input: "Summarize the runtime design.",
-  invocation: {
-    context: {
-      requestId: "req-123",
-    },
-    inputs: {
-      visitCount: 1,
-    },
-    attachments: {
-      "/tmp/spec.md": { content: "draft" },
-    },
-  },
-});
-```
-
-`request(runtime, { ... })` 会创建或延续持久化会话，并返回 `sessionId`、`requestId`、`state` 以及紧凑文本 `output`。更丰富的上游结果形态仍可通过 `outputContent`、`contentBlocks`、`structuredResponse` 等获得。
-
-如果产品需要 request 视角的操作界面，例如 review queue 或执行看板，可使用 `listRequests(runtime)` 与 `getRequest(runtime, requestId)`。
-
-将 `invocation` 作为面向运行时的请求信封：
-
-- `invocation.context`：请求级执行上下文
-- `invocation.inputs`：结构化运行时输入
-- `invocation.attachments`：当前后端可解释的类附件负载
-
-可选地，runtime memory 还可以在 SQLite 持久化记忆之上叠加 `mem0` 语义召回增强，用于提升长期知识命中能力，同时不改变正式知识记录的接口。
-
-### 写入与召回 durable runtime memory
-
-```ts
-import { memorize, recall } from "@botbotgo/agent-harness";
-
-await memorize(runtime, {
-  sessionId: "session-123",
-  records: [
-    {
-      content: "The release checklist requires a smoke test before publish.",
-      summary: "Run a smoke test before publish",
-      scope: "workspace",
-      kind: "procedural",
-      sourceRef: "docs/release-checklist.md",
-    },
-  ],
-});
-
-const recalled = await recall(runtime, {
-  query: "What does the release checklist require?",
-  scopes: ["workspace"],
-});
-```
-
-当应用需要稳定的公开 runtime memory 接口，而不想依赖内部 `runtime/harness/system/*` 模块时，使用 `memorize(...)`、`recall(...)`、`listMemories(...)`、`updateMemory(...)` 与 `removeMemory(...)`。
-
-- `memorize(...)` 返回稳定的 `MemoryRecord` 与 `MemoryDecision` 结果，而 merge、review、archive 与存储布局仍由 runtime 内部托管
-- `recall(...)` 返回按相关性排序、并按 scope / kind 过滤后的 `MemoryRecord`
-- `listMemories(...)` 返回稳定的 `MemoryRecord`，用于排查与管理场景；如果不传 status 过滤器，默认只返回 `active`
-- `updateMemory(...)` 通过 `memoryId` 更新单条 durable memory，而不暴露内部 store namespace
-- `removeMemory(...)` 通过 `memoryId` 删除单条 durable memory，并重建运行时托管的 projection
-- 业务知识分类、review UI 与管理后台仍应留在应用层
-
-### 由运行时路由
-
-```ts
-const result = await request(runtime, {
-  agentId: "auto",
-  input: "Inspect the repository and explain the release flow.",
-});
-```
-
-`agentId: "auto"` 会按顺序评估 `config/runtime/workspace.yaml` 中的路由规则，再使用 `routing.defaultAgentId`，且仅当 `routing.modelRouting: true` 时才回退到模型路由。
-
-### 流式输出与事件
-
-```ts
-const result = await request(runtime, {
-  agentId: "orchestra",
-  input: "Inspect the workspace and explain the available tools.",
-  eventListener(snapshot) {
-    console.log(snapshot.state, snapshot.plan.items);
-  },
-  dataListener(event) {
-    if (event.type === "output.text.delta") {
-      process.stdout.write(event.text);
-    }
-    if (event.type === "tool.result") {
-      console.log(event.toolName, event.output);
-    }
-  },
-});
-```
-
-`eventListener(...)` 会收到最新的完整 request snapshot，包括 request 状态、todo board、approval 状态与当前输出。
-`dataListener(...)` 会收到 append-only 的增量数据，例如文本输出、进度播报、content blocks、tool results 与 upstream debug items。
-
-`subscribe(...)` 是对已存储生命周期事件的只读观察者接口。
-
-运行时事件流包括：
-
-- `request.created`
-- `request.queued`
-- `request.dequeued`
-- `request.state.changed`
-- `approval.requested`
-- `approval.resolved`
-- `output.delta`
-
-### 检查线程与审批
-
-```ts
-import {
-  deleteSession,
-  getApproval,
-  getSession,
-  listApprovals,
-  listSessions,
-  resolveApproval,
-} from "@botbotgo/agent-harness";
-
-const sessions = await listSessions(runtime);
-const session = await getSession(runtime, sessions[0]!.sessionId);
-const approvals = await listApprovals(runtime, { status: "pending" });
-const approval = approvals[0] ? await getApproval(runtime, approvals[0].approvalId) : null;
-
-if (approval) {
-  await resolveApproval(runtime, {
-    approvalId: approval.approvalId,
-    decision: "approve",
-  });
-}
-
-if (session && session.currentState === "completed") {
-  await deleteSession(runtime, session.sessionId);
-}
-```
-
-这些方法返回面向运行时的记录，而非原始 checkpoint 或后端对象。
-
-### 接入与暴露 MCP
-
-将 MCP 服务桥接到 agent：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Agent
-metadata:
-  name: orchestra
-spec:
-  backend: deepagent
-  modelRef: model/default
-  mcpServers:
-    - name: browser
-      command: node
-      args: ["./mcp-browser-server.mjs"]
-```
-
-将 harness 工具作为 MCP 服务对外暴露：
-
-```ts
-import { createToolMcpServer, serveToolsOverStdio } from "@botbotgo/agent-harness";
-
-const server = await createToolMcpServer(runtime, { agentId: "orchestra" });
-await serveToolsOverStdio(runtime, { agentId: "orchestra" });
-```
-
-### 停止运行时
-
-```ts
-import { stop } from "@botbotgo/agent-harness";
-
-await stop(runtime);
-```
-
-<a id="readme-zh-config"></a>
-
-## 如何配置
-
-使用 Kubernetes 风格的 YAML：
-
-- 集合类文件使用 `apiVersion`、复数 `kind` 与 `spec: []`
-- 单例文件使用 `apiVersion`、单数 `kind`、`metadata` 与 `spec`
-
-核心工作区文件：
-
-- `config/runtime/workspace.yaml`
-- `config/agent-context.md`
-- `config/models.yaml`
-- `config/catalogs/embedding-models.yaml`
-- `config/catalogs/vector-stores.yaml`
-- `config/catalogs/stores.yaml`
-- `config/knowledge/knowledge-runtime.yaml`
-- `config/knowledge/procedural-memory-runtime.yaml`
-- `config/runtime/runtime-memory.yaml`
-- `config/catalogs/backends.yaml`
-- `config/catalogs/tools.yaml`
-- `config/catalogs/mcp.yaml`
-- `config/agents/direct.yaml`
-- `config/agents/orchestra.yaml`
-- `resources/tools/`
-- `resources/skills/`
-
-发现规则：
-
-- `config/**` 下的所有 YAML 文档都会被递归发现；文件名与子目录只用于组织，不参与语义
-- YAML 对象语义由 `kind`、`metadata.name` 或 `id` 以及对象内容决定，而不是由文件路径决定
-- `Runtime.spec.sources.tools` 默认值是 `file://./resources/tools`
-- `Runtime.spec.sources.skills` 默认值是 `file://./resources/skills`
-- file-based 工具会从每个声明的 tool source 自动发现，前提是模块导出 `tool({...})`
-- file-based skills 会从每个声明的 skill source 自动发现
-- 一个最小工作区只放 `config/models.yaml` 也可以启动；仓库默认值会补上 `Runtime`、默认 `orchestra` host，以及默认开启的 runtime-managed durable memory
-- 如果不显式覆盖 runtime 放置位置，harness 生成的数据默认写到 `./.botbotgo/`
-
-示例工作区：
-
-- 前缀表示复杂度顺序，`00_` 是最简单的起点
-- `examples/00_local-tools-and-skills/` 是 Local Tools and Skills Example：最小的本地 tool + skill 工作区
-- `examples/01_multimodal-request/` 是 Multimodal Request Example：最小的图片 + PDF 请求流
-- `examples/02_subagent-planning/` 是 Subagent Planning Example：带一个 subagent、工具和 trace 输出的紧凑规划流程
-- `examples/03_protocol-surfaces/` 是 Protocol Surfaces Example：同一个最小 direct agent 的 ACP、ACP stdio、A2A、AG-UI 和 runtime MCP 示例
-- `examples/04_local-model-tool-calling/` 是 Local Model Tool Calling Example：一个本地 GGUF task loop 加一个本地 tool
-- `examples/05_runtime-trace-export/` 是 Runtime Trace Export Example：一次真实运行，加上 runtime 与 upstream events 的 Mermaid 导出
-- `examples/06_repository-analysis/` 是 Repository Analysis Example：围绕一个工作区本地 tool 和 embedding 索引的仓库分析示例
-- `examples/07_multi-agent-research/` 是 Multi-Agent Research Example：最完整的多 agent 研究工作区，包含可复用 backend、skill 和本地 tool
-- `examples/08_long-term-memory-learning/` 是 Long-Term Memory Learning Example：通过多次 request 写入 durable memory、检查 recall，并让后续回答更懂上下文
-- `examples/09_long-running-coding-harness/` 是 Long-Running Coding Harness Example：用 host agent 加 app-owned planning/evaluation 角色，结合 Playwright MCP 与 evaluation bundle 承载长时 coding 会话
-- `examples/10_playwright-mcp-browser/` 是 Playwright CLI Browser Example：最小的浏览器能力工作区，对齐 Playwright 面向 coding agent 的官方推荐方式：`playwright-cli` 加本地 skill
-
-`resources/tools/` 下的工作区本地工具模块应统一用 `tool({...})` 导出。
-不支持历史/兼容写法，任何不带该导出形式的工具模块都会在工作区加载时被拒绝。
-本地 function tool 如果在模块里声明了 schema，runtime governance 会直接把该模块 schema 视为事实来源；不需要为了 schema-bound 元数据再额外复制一份 YAML `inputSchema.ref`。
-若本地工具使用 Zod schema，请让工作区或隔离的 `resources` 包统一使用 `zod@^4`，避免 raw shape validator 与 runtime 解析落在不同 major 版本上。
-如果你要提供 `list_files`、`search_files`、`run_command`、`schedule_task`、request/approval/artifact inspection 这类 runtime-owned 产品工具，请把它们当成普通工作区工具写进 `resources/tools/*.mjs`，再由 agent YAML 按名称白名单启用。
-对于 `backend: deepagent` 的 agent，runtime 仍会保留一层内部 compatibility tools，补齐上游 DeepAgents 在长链路执行时默认依赖的 helper tools。目前这组兼容工具包括 `write_todos`、`read_todos`、`ls`、`read_file`、`write_file`、`edit_file`、`glob`、`grep`、`task`，以及在所选 backend 支持 sandbox command execution 时才会出现的 `execute`。应当把这些 helper 名视为 adapter 内部执行兼容层，而不是主要的产品级工作区工具面。
-如果想准确理解这里的“TODO 支持”边界，请看 [`docs/todo-support-matrix.zh.md`](./docs/todo-support-matrix.zh.md)。当前契约是：对 DeepAgents todo helper flow 提供完整支持，并把结果投影成 request 级可持久化的 plan state；它不是一套 backend-neutral 的 TODO 产品本体。
-
-配置大致分这几层（由下至上叠加）：
-
-- 先由 `Runtime.spec.sources` 声明工作区实际拥有的 tool / skill 来源
-- workspace 启动时只扫描这些显式声明的 source，并建立统一 registry
-- workspace 启动时扫描本地与附加的 `resources` 包，建立统一 registry；这条兼容路径仍可继续工作
-- 各 agent 再按名称白名单选用 tools 与 skills
-- `config/runtime/workspace.yaml` 承载运行时策略
-- `config/catalogs/*.yaml` 承载可复用对象目录
-- `config/**/*.yaml` 中的 agent 装配
-
-### Backend 选择建议
-
-当前对于复杂、生产化风格的运行链路，最稳定的路径仍然是 `backend: deepagent`。
-
-目前 `backend: langchain-v1` 这条路径的暂时限制是：
-
-- 在真实远端模型下，带 approval 的副作用工具调用稳定性弱于轻量 direct-response 路径
-- 不建议把它作为长链路、多 agent、重 orchestration 流程的默认执行路径
-- 本包当前已把规划优先后端作为复杂运行时覆盖的默认主路径；只有在工作区明确需要轻量 direct-response 行为时，才应显式选择另一条后端路径
-
-实际建议：
-
-- approvals、resume、多 agent orchestration、复杂 memory 流、重工具链，优先使用 `backend: deepagent`
-- `backend: langchain-v1` 先保留给轻量 direct-response 场景，或明确需要 V1 agent 语义的工作区
-
-本地 GGUF 补充说明：
-
-- `provider: node-llama-cpp` 现在带有一层 LangChain 风格的 tool-binding shim，因此本地 GGUF 模型可以进入标准 tool-calling 路径，而不需要应用自己包一层 model wrapper
-- `provider: openai-compatible` 可以指向外部 `llama-server` endpoint；当模型进程需要在 Node.js 外部单独调参、守护或部署时，继续复用这条已有路径
-- 对 `node-llama-cpp` 来说，`backend: langchain-v1` 仍然是更直接、当前已验证的本地 tool use 路径
-- `backend: deepagent` 也可以走到同一条 tool-calling 路径，但最终稳定性仍取决于所选模型是否能正确遵守 upstream tool schema
-- `agent-harness` 不会为每个模型的参数漂移或畸形 tool payload 做无限兼容；runtime 把调用交给 upstream tools 之后，schema fidelity 就属于模型责任
-
-### `config/runtime/workspace.yaml`
-
-用于工作区范围的运行时策略。
-
-重要字段：
-
-- `runtimeRoot`
-- `concurrency.maxConcurrentRequests`
-- `sources.tools`
-- `sources.skills`
-- `routing.defaultAgentId`
-- `routing.rules`
-- `routing.systemPrompt`
-- `routing.modelRouting`
-- `maintenance.checkpoints`
-- `maintenance.records`
-- `recovery.enabled`
-- `recovery.resumeResumingRequestsOnStartup`
-- `recovery.maxRecoveryAttempts`
-
-`recovery.resumeResumingRequestsOnStartup` 将 checkpoint 恢复保持为运行时拥有的生命周期行为，而不是把 checkpoint 编排暴露为主 API。
-
-`maintenance.checkpoints` 与 `maintenance.records` 是两层独立的保留策略：
-
-- `maintenance.checkpoints` 清理后端用于 resume/recovery 的 checkpoint 状态
-- `maintenance.records` 清理 harness 自己保存在 `runtime.sqlite` 中、已结束的 session/request 记录
-
-`sources.tools` 用来声明哪些 tool root 或 package 参与工作区发现：
-
-- `file://...` 用于目录扫描
-- `npm://...` 用于 `tools/` 目录发现；本地缺失时自动安装
-
-`sources.skills` 用来声明哪些 skill 目录或 skill 文档参与工作区发现：
-
-- `file://...` 用于本地目录、skill root 或直接 `SKILL.md`
-- `npm://...` 用于 `skills/` 目录发现；本地缺失时自动安装
-- `http://...` / `https://...` 用于单个远程 `SKILL.md`
-
-`toolModuleDiscovery.scope` 用来控制本地 `resources/tools/` 风格 file source 的发现范围：
-
-- `recursive` 是默认值，会继续扫描嵌套目录
-- `top-level` 只发现每个工具根目录下一层文件，同时保留 YAML catalog 的递归发现
-
-当 libSQL 对 harness 运行时持久化报错时，错误信息会带上 `runtime.sqlite` 的绝对路径。对约束类错误（或设置环境变量 `AGENT_HARNESS_RUNTIME_SQLITE_DEBUG=1` 时），信息中还会包含被截断的失败 SQL，便于在同一进程里区分 harness 与其它 SQLite 数据库。
-
-示例：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Runtime
-metadata:
-  name: default
-spec:
-  dataRoot: ./.botbotgo
-  toolModuleDiscovery:
-    scope: top-level
-  concurrency:
-    maxConcurrentRuns: 3
-  routing:
-    defaultAgentId: orchestra
-    modelRouting: false
-  maintenance:
-    checkpoints:
-      enabled: true
-    records:
-      enabled: false
-  recovery:
-    enabled: true
-    resumeResumingRequestsOnStartup: true
-    maxRecoveryAttempts: 3
-```
-
-### `config/agent-context.md`
-
-用于在构建 agent 时加载的共享启动记忆。
-
-在此放置稳定的项目上下文；视为启动上下文，而非可变长期记忆。
-
-### `config/**` 下的 Models Catalog
-
-命名聊天模型预设：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Models
-spec:
-  - name: default
-    provider: openai
-    model: gpt-4.1
-    temperature: 0.2
-```
-
-加载为 `model/default`。
-
-`kind: Models` catalog 可以放在 `config/` 下任意位置；仓库默认值现在把 `models.yaml` 放在 `config/` 根目录，而文件路径本身只是一种组织方式。
-
-### `config/**` 下的 Embedding Model Catalog
-
-面向检索类工具的命名嵌入模型预设。
-
-### `config/catalogs/vector-stores.yaml`
-
-检索工具引用的命名向量库预设。
-
-### `config/catalogs/stores.yaml`
-
-可复用的存储与 checkpointer 预设：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Stores
-spec:
-  - kind: Store
-    name: default
-    storeKind: SqliteStore
-    path: store.sqlite
-  - kind: Checkpointer
-    name: default
-    checkpointerKind: SqliteSaver
-    path: runtime/checkpoints.sqlite
-```
-
-### `config/runtime/runtime-memory.yaml`
-
-这个单例文件用于配置 runtime 持有的 durable long-term memory 默认值。
-
-把稳定启动上下文放在 `config/agent-context.md`，把可恢复执行状态留给 checkpointer，把长期记忆策略与检索默认值放在 `RuntimeMemory`。
-
-`RuntimeMemory` 也承载 LangMem 风格的 formation 默认值：
-
-- `formation.hotPath`：运行中的即时捕获
-- `formation.manager`：持久化前的规则式或模型式 candidate 归一化
-- `formation.background`：在 run 完成或 approval resolve 后做 reflection
-
-### `config/knowledge/knowledge-runtime.yaml`
-
-当同一套 durable-memory policy 还需要运行在 `AgentHarnessRuntime` 之外，例如独立 knowledge worker 或 knowledge server 时，使用这个单例对象。
-
-`KnowledgeRuntime` 故意镜像 durable policy 的主形状。`RuntimeMemory` 继续承载 runtime 内部默认值；而当外部 knowledge service 也需要同一套 memorize/recall policy 时，再保留 `KnowledgeRuntime` 作为可外置的镜像对象。它适合继续承担快速显式写入，以及 durable knowledge 的后台整理和长期养护。
-
-### `config/knowledge/procedural-memory-runtime.yaml`
-
-当工作区需要一层独立的后台经验记忆，例如 ReMe 驱动的 procedural memory 池时，使用这个单例对象。
-
-`ProceduralMemoryRuntime` 会刻意和 `KnowledgeRuntime` 分开：
-
-- `KnowledgeRuntime` 继续放 durable facts、preferences、rules 和 confirmed decisions
-- `ProceduralMemoryRuntime` 继续放 workflows、debugging lessons、tactics 和 reusable procedures
-- 两者都落在同一个 `knowledge/` 目录下，但不强行共用一个逻辑 store
-
-仓库默认建议是：
-
-- `KnowledgeRuntime`：hot path + 后台形成 + 长期养护
-- `ProceduralMemoryRuntime`：后台形成 + 定时或空闲整理
-
-在当前已发布的 runtime 里，像“请记住我最近搬到了美国”这种显式 durable fact 仍然走 `KnowledgeRuntime`，并写入 `knowledge/knowledge.sqlite`。后台 procedural learning 会在同一个 data root 下单独写自己的 store 与 state 文件，例如 `knowledge/procedural-memory.sqlite` 和 `knowledge/procedural-memory-state.json`。
-
-对于 `backend: deepagent` 的工作区，应继续把 context compaction 留给上游 DeepAgents，只把 procedural memory 当作后台学习层使用。
-
-### `config/catalogs/backends.yaml`
-
-可复用的后端预设，使文件系统与 `/memories/*` 拓扑保留在 YAML 中：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Backends
-spec:
-  - kind: Backend
-    name: default
-    backendKind: CompositeBackend
-    state:
-      kind: VfsSandbox
-      rootDir: .
-      virtualMode: true
-      timeout: 600
-    routes:
-      /memories/:
-        kind: StoreBackend
-```
-
-### `config/catalogs/tools.yaml`
-
-可复用工具对象。
-
-内置工具族包括函数工具、后端工具、MCP 工具、bundle 与原生 provider 工具。原生 provider 工具在 YAML 中声明并直接解析到上游工厂。
-
-`config/catalogs/tools.yaml` 更适合放可复用共享工具对象，而不应成为每个本地工具的默认入口。工作区自有函数工具通常应从 `resources/tools/` 发现，再由各 agent 按名字白名单启用。
-
-### `config/catalogs/mcp.yaml`
-
-命名 MCP 服务预设。
-
-示例：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: McpServers
-spec:
-  - name: browser
-    transport: stdio
-    command: node
-    args:
-      - ./mcp-browser-server.mjs
-```
-
-这里可以省略 `spec[].kind`；catalog 项会默认按 `McpServer` 处理。
-
-### `config/**` 下的 Agent YAML
-
-Agent 始终使用 `kind: Agent` 以及 `spec.backend`。
-
-Agent YAML 可以放在 `config/` 下任意位置；`config/agents/*.yaml` 是推荐布局，不是 loader 的硬性要求。
-
-两个区块：
-
-- `spec.runtime`：agent 级 runtime 放置覆盖，例如 `spec.runtime.runtimeRoot`
-- `spec` 顶层字段：上游执行语义与面向适配器的配置
-
-direct 主机示例：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Agent
-metadata:
-  name: direct
-spec:
-  backend: langchain-v1
-  modelRef: model/default
-  tools:
-    - write_file:
-        subprocess: true
-  skills:
-    - code-review
-  memory: []
-  subagents: []
-  mcpServers: []
-  config:
-    checkpointer: default
-    store: default
-    interruptOn: {}
-    filesystem:
-      rootDir: .
-      virtualMode: true
-      maxFileSizeMb: 10
-      sessionStorage:
-        enabled: true
-        rootDir: "{runtimeRoot}/sessions/{sessionId}/filesystem"
-    middleware: []
-    systemPrompt:
-      path: ../prompts/direct-system.md
-```
-
-较长的 prompt 建议放在受版本控制的文件里，例如 `config/prompts/*.md`，再通过相对于 agent YAML 的 `systemPrompt.path` 引用。这样 prompt 文本不会散落在 source code 里，评审时也能把它当作普通内容变更来检查。
-
-当 LangChain 绑定启用 `config.filesystem.sessionStorage.enabled: true` 时，runtime 会为每个持久化 session 维护独立的 filesystem 根目录，并按 session 复用 runnable cache，而不是把所有请求都压到同一个共享工作目录里。
-
-orchestra 主机示例：
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Agent
-metadata:
-  name: orchestra
-spec:
-  backend: deepagent
-  modelRef: model/default
-  memory:
-    - path: config/agent-context.md
-  tools:
-    - stock_snapshot
-  skills:
-    - stock-research
-  subagents: []
-  mcpServers: []
-  config:
-    store: default
-    checkpointer: default
-    backend: default
-    interruptOn: {}
-    middleware: []
-```
-
-后端相关选项优先直接写在 `spec.config` 中沿用上游概念。日常接入时，以开发者文档与 API 参考为准即可。
-
-## 设计说明
-
-- `agent-harness` 不是第三个 agent 框架
-- 公共运行时契约保持通用且精简
-- 应用级编排与生命周期管理留在 harness 中
-- 外部协议边界应严格契合 `deepagents-acp`，而不是再做一套并行的 harness 私有协议
-- 应尽量在 YAML 中直接表达执行后端的概念
-- 能用 YAML 表达的能力，优先 YAML 而非扩张公共 API
-- 恢复、审批、线程、运行与事件是运行时概念，不是后端逃生舱
-- 应用里的 task center 应基于现有 store 与 runtime id 建模，而不是把 task 扩成公共运行时契约
-- 新的后端配置应先落在 YAML 映射与测试中，再考虑公共运行时 API
-
-简言之：产品模型稳定，执行语义仍归上游。
-
-<a id="readme-zh-api-summary"></a>
-
-## API 摘要
-
-主要导出：
-
-- `createAgentHarness`
-- `AgentHarnessRuntime`
-- `request`
-- `resolveApproval`
-- `subscribe`
-- `listRequests`
-- `getRequest`
-- `listSessions`
-- `getSession`
-- `deleteSession`
-- `listApprovals`
-- `getApproval`
-- `listArtifacts`
-- `getArtifact`
-- `listRequestEvents`
-- `listRequestTraceItems`
-- `exportRequestPackage`
-- `exportSessionPackage`
-- `exportEvaluationBundle`
-- `replayEvaluationBundle`
-- `createAcpServer`
-- `createAcpStdioClient`
-- `serveAcpHttp`
-- `serveAcpStdio`
-- `serveA2aHttp`
-- `serveAgUiHttp`
-- `createRuntimeMcpServer`
-- `serveRuntimeMcpOverStdio`
-- `createToolMcpServer`
-- `serveToolsOverStdio`
-- `stop`
-- `createUpstreamTimelineReducer`
-- `exportFlow`
-- `exportSequence`
-
-Inspection 辅助工具：
-
-- `createUpstreamTimelineReducer()` 可把上游 model/tool/chain 原始事件归约成有序的 step-like 投影，便于检查和可视化。
-- `listRequestTraceItems(runtime, { sessionId, requestId })` 可直接读取持久化的 request trace items。这些 trace item 是运行图和运行后检查的基础数据，每条记录都同时带有规范化后的 runtime surface 与来源 upstream event。
-- `exportFlow(runtime, { sessionId, requestId })` 可直接从 runtime 读取单个持久化 request record，并导出成 Mermaid flowchart 文本。它内建产品视图默认值，直接固定方向、分组与可见 kind，调用方不需要再额外传一套可视化参数。
-- `exportSequence(runtime, { sessionId, requestId })` 可从同一份持久化 request record 导出 Mermaid sequence diagram，并与同一份持久化 trace 对齐。
-
-这些 helper 只用于可视化与检查，不代表新的 harness 官方执行协议。
-
-ACP transport 说明：
-
-- `serveAcpStdio(runtime)` 提供基于 stdio 的 newline-delimited JSON-RPC，适合本地 IDE、CLI 或子进程客户端。
-- `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程界面或独立控制面接入。
-- ACP transport 现已覆盖核心参考客户端流程验证：capability discovery、request submit、session lookup、request lookup、invalid JSON 处理、无 id notification 不返回响应，以及 stdio JSON-RPC 与 HTTP + SSE runtime notifications。
-- 现在还额外有一条跨协议一致性回归门：ACP 发起的 request、A2A 读取或继续的 task，以及 runtime MCP 暴露的检查结果，必须始终指向同一组持久化 `sessionId` / `requestId` 运行时记录，不能漂移成各协议各自维护的标识体系。
-- 如果要从最薄的一层 editor / CLI starter 开始，优先用 `agent-harness acp serve --workspace . --transport stdio`，并直接参考 `examples/03_protocol-surfaces/app/acp-stdio/main.mjs` 的 wire shape。需要在应用内使用 reference client 时，可直接用 `createAcpStdioClient(...)` 发起 JSON-RPC 请求并分流 runtime notifications，避免每个 sidecar 自己重写 line parsing。
-- 如果想用最短的本地运维命令把整套协议面一起拉起，现在可以直接运行 `botbotgo start --workspace .`，它会把 ACP、A2A、runtime MCP 与 AG-UI 一起作为受管本地服务启动；`botbotgo stop --workspace .` 会按同一组服务统一停止。若只需要其中一部分，可用 `--services acp,mcp` 收窄启动集合。
-- 如果本地 ACP HTTP endpoint 需要在前台 shell 之外持续运行，可使用 `botbotgo acp start --workspace . --host 127.0.0.1 --port 8787`，之后再用 `botbotgo acp stop --workspace .` 停止。CLI 会把受管进程记录到 `.botbotgo/services/` 下，因此本地运维不必再额外引入第二套进程管理器。
-- 对发布后的安装包来说，`botbotgo` 是最短的本地终端入口。它会默认把当前目录当作 workspace，所以团队只需要 `cd` 到自己的 runtime workspace，然后直接运行 `botbotgo` 或 `botbotgo "..."`。`agent-harness` 也保留同样的隐式 chat 行为；如果要从同一个 shell 指向别的 workspace，继续用 `-w/--workspace` 即可。
-- `agent-harness chat --workspace .` 则继续保留为显式子命令形式的本地终端壳：默认 `stdio` 路径会直接在当前进程里连接 workspace runtime，而 `--transport http --host <host> --port <port>` 仍然可以直连已运行的 ACP HTTP endpoint。一次性调用可用 `--message`，交互模式则支持 `/context`、`/new`、`/agent <agentId>`、`/sessions`、`/requests`、`/resume <sessionId>`、`/approvals`、`/approve`、`/reject`、`/cancel`、`/events`、`/trace`、`/health`、`/overview`、`/session`、`/request [requestId]` 与 `/exit`。`/resume` 现在会先校验目标 session，恢复它的 latest request id，并同步 active agent context；`/request <requestId>` 可以把当前上下文切到某个已持久化 request；`/new` 则会在不退出 shell 的情况下清空当前 session/request context。终端 chat 现在统一走一条面向 operator 的输出路径：tool 和进度事件会实时打印，最终完整答复也会继续输出，而不再切到单独的 request-tree-only 模式。
-- 如果是在仓库源码目录里直接运行，请使用 `npm run chat -- --workspace ./config`，或者 `npm run agent-harness -- chat --workspace ./config`。这里额外的 `--` 不能省略，否则 npm 会把 `--workspace` 当成它自己的 workspace 参数。只有在包已经被安装或 `npm link` 到系统环境后，`agent-harness ...` 这个独立命令才会出现在 `PATH` 里。
-- 交互式 chat 现在还会先显示一块更大的 ASCII 启动画面，明确打印当前 workspace、transport 和上下文覆盖信息，再进入命令帮助，因此终端壳更像一个完整的 runtime console，而不只是裸 REPL。
-- 当 workspace 配置的模型/provider 无法连通时，chat 现在会把 `runtime_error=fetch failed` 这类泛化失败展开成可操作的诊断信息，明确打印当前 provider、model、endpoint 以及具体修复提示，而不再只留下一个不透明的传输层错误。
-- chat 启动时现在还会对本地 Ollama 路径做一次轻量 preflight。如果当前 endpoint 不可达，或者直接返回 `404 page not found`，shell 会在第一条 prompt 之前先打印这条告警，这样 endpoint 配错的问题会在启动时立即暴露，而不必等第一条消息失败后才知道。
-- 交互式 prompt 现在会同时显示当前 `agent`、`session` 和短 `request` 标识，因此每轮回复之后以及使用 shell 历史记录时，用户都还能清楚地看到自己正处在哪个 runtime turn 上，而不会掉回一个没有上下文的裸输入提示。
-- `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetAgentCard`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、在 agent card 路径上响应 `HEAD` / `OPTIONS` discovery、写出支持版本的 discovery headers、可选暴露 registry URL 与 detached signed-card metadata 供外围发现系统使用、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 v1 streaming 方法上先通过 SSE 输出 `{ task }` 初始快照，再输出 `{ statusUpdate }` 增量状态，并可向已配置的 webhook receiver 发送 best-effort task push notifications。
-- 如果要把本地 A2A bridge 作为受管后台服务运行，可使用 `botbotgo a2a start --workspace . --host 127.0.0.1 --port 8080`，之后再用 `botbotgo a2a stop --workspace .` 停止。它与 ACP 共用 `.botbotgo/services/` 状态目录，因此两个本地协议桥都可以沿用同一套终端优先运维流程。
-- `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、安全进度播报、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`STATUS_UPDATE`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。`botbotgo ag-ui start|stop` 现在也会把这条 HTTP bridge 托管进与 ACP、A2A、runtime MCP 相同的 workspace 本地服务注册表中。
-- `createRuntimeMcpServer(runtime)`、`serveRuntimeMcpOverStdio(runtime)` 与 `serveRuntimeMcpOverStreamableHttp(runtime)` 会把持久化 runtime 控制面本身暴露成 MCP tools，包括 sessions、requests、approvals、artifacts、events 与 package export helpers。`botbotgo mcp serve --transport streamable-http --host 127.0.0.1 --port 8090` 会把同一套控制面作为 Streamable HTTP 暴露出去，而 `botbotgo mcp start|stop` 可直接托管该后台 endpoint。
-- `listRequestEvents(...)`、`listRequestTraceItems(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。
-- `analyzeBoundaries(runtime)` 会返回 workspace boundary report，覆盖 agent、subagent、tool 与 skill 的可见边界，并指出缺失 subagent 引用、未被引用的 tools/skills、以及 skill allow-list 与所属 agent 暴露工具不匹配等结构性问题。
-- `exportRequestPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events、artifacts 与 governance evidence 一起打包给管理工具，而不必直接访问 persistence 内部实现。
-- `runtime/default.governance.remoteMcp` 现在可以按 MCP server 或 transport 做 allow/deny、审批升级，并把 transport 风险等级写进 runtime governance bundles。MCP server catalog 也可以声明 trust tier、access mode、tenant scope、approval policy、prompt-injection risk 与 OAuth scope 元数据，让治理快照能解释为什么某个远端工具被视为高风险。tool policy override 也可以声明 `decisionMode: manual | auto-approve | auto-reject | deny-and-continue`，让治理快照与实际执行路径保持一致。
-- 协议分工要继续保持清晰：ACP 是 editor / client 的主运行时边界，A2A 是支持 streaming 且兼容轮询的 agent-platform bridge，AG-UI 是 UI 事件面，runtime MCP 是以 MCP tools 暴露的 operator control plane。
-- `runtime/default.observability.tracing` 现在可描述 OTLP endpoint 和 propagation mode 这类 exporter 元数据，使冻结的 runtime snapshot 在保留 trace correlation 的同时，也能保留有用的导出上下文，而不暴露 backend 私有 span 细节。
-- `agent-harness runtime overview`、`agent-harness runtime boundaries`、`agent-harness runtime health`、`agent-harness runtime approvals list|watch`、`agent-harness runtime requests list|tail` 与 `agent-harness runtime export request|session` 提供了一层轻量 CLI，可直接查看 workspace boundary analysis、runtime health、queue pressure、governance risk、审批队列、运行状态与可审计证据包。
-- 更详细的 A2A 适配层开发说明见 [`docs/a2a-bridge.md`](docs/a2a-bridge.md)
+文档：https://agent-harness.easynet.world/