@botbotgo/agent-harness 0.0.57 → 0.0.59

package/README.md

@@ -1,24 +1,27 @@
 <p align="center">
-  <img src="./docs/assets/readme-icon.png" width="120" alt="botbotgo runtime icon" />
+  <img src="./docs/assets/readme-banner.png" alt="botbotgo runtime banner" />
 </p>
 
 <p align="center">
-  <img src="./docs/assets/readme-banner.png" alt="botbotgo runtime banner" />
+  <strong>English</strong> · <a href="./README.zh.md">中文</a>
 </p>
 
 # @botbotgo/agent-harness
 
 <p align="center">
-  <strong>A workspace-shaped runtime for agent systems that need to keep running after the demo.</strong>
+  <strong>The product runtime that gets multi-agent systems into production and keeps them running.</strong>
 </p>
 
 <p align="center">
-  <strong>botbotgo</strong> is the brand. <strong>agent-harness</strong> is the product.
+  <a href="https://botbotgo.github.io/agent-harness/">Product website</a>
+  (static page in <code>docs/</code>, publish with GitHub Pages; EN / 中文 toggle)
 </p>
 
 <p align="center">
-  <a href="https://botbotgo.github.io/agent-harness/">Product website</a>
-  (static page in <code>docs/</code>, publish with GitHub Pages)
+  <em
+    >We specialize in AI solutions. If you have a product idea you want to ship,
+    <a href="mailto:info@easynet.world">info@easynet.world</a>.</em
+  >
 </p>
 
 ## Product Overview

package/README.zh.md

@@ -0,0 +1,574 @@
+<p align="center">
+  <img src="./docs/assets/readme-banner.png" alt="botbotgo runtime banner" />
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <strong>中文</strong>
+</p>
+
+# @botbotgo/agent-harness
+
+<p align="center">
+  <strong>让多 agent 系统真正上线并持续运行的产品运行时。</strong>
+</p>
+
+<p align="center">
+  <a href="https://botbotgo.github.io/agent-harness/">产品网站</a>
+  （<code>docs/</code> 中的静态页，通过 GitHub Pages 发布；支持中英文切换）
+</p>
+
+<p align="center">
+  <em
+    >我们专注于 AI 解决方案。若有希望落地的产品想法，欢迎来信
+    <a href="mailto:info@easynet.world">info@easynet.world</a>。</em
+  >
+</p>
+
+## 产品概览
+
+`@botbotgo/agent-harness` 是面向真实 agent 产品的、工作区形态的应用运行时。
+
+它不是又一个 agent 框架，而是围绕 LangChain v1 与 DeepAgents 的运行时层：把一个工作区变成一套可运维的应用运行时。
+
+关系可以概括为：
+
+- Codex、Claude Code、Cursor 是「人用 agent」的产品
+- LangChain v1 与 DeepAgents 是定义 agent 执行语义的框架
+- `agent-harness` 是交付、运维、恢复与治理多 agent 应用的运行时产品层
+
+产品边界是清晰的：
+
+- LangChain v1 与 DeepAgents 拥有 agent 执行语义
+- 应用级编排与生命周期管理留在 harness 中
+
+因此：
+
+- 对外 API 保持精简
+- 复杂装配与运行策略放在 YAML
+- 后端实现可换时，运行时生命周期模型仍保持稳定
+- 后端细节藏在适配器之后
+
+运行时提供：
+
+- `createAgentHarness(workspaceRoot)`、`run(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
+- 以 YAML 描述的工作区装配：路由、模型、工具、存储、后端、MCP、恢复与维护等
+- 通过适配器对接当前的 LangChain v1 与 DeepAgents 执行
+- 本地 `resources/tools/` 与 `resources/skills/` 的发现
+- 持久化的线程、运行、审批、事件、队列状态与恢复元数据
+
+仓库自带的默认配置刻意做成「形状完整」。随仓库提供的 YAML 对重要的运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
+
+默认原则是：
+
+- 若 LangChain v1 或 DeepAgents 已有能力，则在 YAML 中映射并在内部适配
+- 除非问题确实属于运行时职责，否则不增加新的公共运行时 API
+
+边界说明见：
+
+- `docs/upstream-feature-matrix.md`
+- `docs/product-boundary.md`
+- `docs/feature-checklist.md`
+
+## 为何需要它
+
+多数 agent 演示停在「能跑」。
+
+真实产品需要能回答更难问题的运行时：
+
+- 运行（runs）存在哪里？
+- 审批如何闭环？
+- 进程重启后什么还在？
+- 如何在不暴露原始后端状态的前提下检查线程与事件？
+- 如何在不大改产品模型的前提下替换后端实现？
+
+`agent-harness` 在不把应用 API 变成 LangChain v1 / DeepAgents 翻版的前提下，回答这些问题。
+
+## 有何不同
+
+- 将 `runs`、`threads`、`approvals`、`events` 与恢复视为产品概念
+- 将 checkpoint 恢复作为系统管理的行为，而不是把 checkpoint 细节抬成主 API
+- 复杂装配交给 YAML，代码面保持极小
+- 在上游库未充分产品化的运行时时，做深做透
+
+## 快速开始
+
+安装：
+
+```bash
+npm install @botbotgo/agent-harness
+```
+
+工作区布局：
+
+```text
+your-workspace/
+  config/
+    workspace.yaml
+    agent-context.md
+    models.yaml
+    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, run, stop } from "@botbotgo/agent-harness";
+
+const runtime = await createAgentHarness("/absolute/path/to/workspace");
+
+try {
+  const result = await run(runtime, {
+    agentId: "auto",
+    input: "Explain what this workspace is for.",
+  });
+
+  console.log(result.output);
+} finally {
+  await stop(runtime);
+}
+```
+
+最短心智模型：
+
+- 一个工作区对应一个运行时
+- YAML 定义装配与策略
+- `run(runtime, { ... })` 在该运行时上执行请求
+- 运行时负责生命周期、可观测性与恢复
+
+## 功能列表
+
+- 多 agent 应用的工作区运行时
+- 精简的公共运行时契约
+- YAML 定义的主机路由与运行时策略
+- LangChain v1 与 DeepAgents 后端适配
+- 自动发现本地工具与 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(...)` 会加载工作区、解析 `resources/`、在 `runRoot` 下初始化持久化，并启动运行时维护任务。
+
+### 发起一次运行
+
+```ts
+import { run } from "@botbotgo/agent-harness";
+
+const result = await run(runtime, {
+  agentId: "orchestra",
+  input: "Summarize the runtime design.",
+  invocation: {
+    context: {
+      requestId: "req-123",
+    },
+    inputs: {
+      visitCount: 1,
+    },
+    attachments: {
+      "/tmp/spec.md": { content: "draft" },
+    },
+  },
+});
+```
+
+`run(runtime, { ... })` 会创建或延续持久化线程，并返回 `threadId`、`runId`、`state` 以及紧凑文本 `output`。更丰富的上游结果形态仍可通过 `outputContent`、`contentBlocks`、`structuredResponse` 等获得。
+
+将 `invocation` 作为面向运行时的请求信封：
+
+- `invocation.context`：请求级执行上下文
+- `invocation.inputs`：结构化运行时输入
+- `invocation.attachments`：当前后端可解释的类附件负载
+
+### 由运行时路由
+
+```ts
+const result = await run(runtime, {
+  agentId: "auto",
+  input: "Inspect the repository and explain the release flow.",
+});
+```
+
+`agentId: "auto"` 会按顺序评估 `config/workspace.yaml` 中的路由规则，再使用 `routing.defaultAgentId`，且仅当 `routing.modelRouting: true` 时才回退到模型路由。
+
+### 流式输出与事件
+
+```ts
+const result = await run(runtime, {
+  agentId: "orchestra",
+  input: "Inspect the workspace and explain the available tools.",
+  listeners: {
+    onChunk(chunk) {
+      process.stdout.write(chunk);
+    },
+    onContentBlocks(blocks) {
+      console.log(blocks);
+    },
+    onEvent(event) {
+      console.log(event.eventType, event.payload);
+    },
+  },
+});
+```
+
+`subscribe(...)` 是对已存储生命周期事件的只读观察者接口。
+
+运行时事件流包括：
+
+- `run.created`
+- `run.queued`
+- `run.dequeued`
+- `run.state.changed`
+- `approval.requested`
+- `approval.resolved`
+- `output.delta`
+
+### 检查线程与审批
+
+```ts
+import {
+  getApproval,
+  getThread,
+  listApprovals,
+  listThreads,
+  resolveApproval,
+} from "@botbotgo/agent-harness";
+
+const threads = await listThreads(runtime);
+const thread = await getThread(runtime, threads[0]!.threadId);
+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",
+  });
+}
+```
+
+这些方法返回面向运行时的记录，而非原始 checkpoint 或后端对象。
+
+### 接入与暴露 MCP
+
+将 MCP 服务桥接到 agent：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: orchestra
+spec:
+  execution:
+    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);
+```
+
+## 如何配置
+
+使用 Kubernetes 风格的 YAML：
+
+- 集合类文件使用 `apiVersion`、复数 `kind` 与 `spec: []`
+- 单例文件使用 `apiVersion`、单数 `kind`、`metadata` 与 `spec`
+
+核心工作区文件：
+
+- `config/workspace.yaml`
+- `config/agent-context.md`
+- `config/models.yaml`
+- `config/embedding-models.yaml`
+- `config/vector-stores.yaml`
+- `config/stores.yaml`
+- `config/backends.yaml`
+- `config/tools.yaml`
+- `config/mcp.yaml`
+- `config/agents/direct.yaml`
+- `config/agents/orchestra.yaml`
+- `resources/tools/`
+- `resources/skills/`
+
+主要有三层配置：
+
+- `config/workspace.yaml` 中的运行时策略
+- `config/*.yaml` 中的可复用对象目录
+- `config/agents/*.yaml` 中的 agent 装配
+
+### `config/workspace.yaml`
+
+用于工作区范围的运行时策略。
+
+重要字段：
+
+- `runRoot`
+- `concurrency.maxConcurrentRuns`
+- `routing.defaultAgentId`
+- `routing.rules`
+- `routing.systemPrompt`
+- `routing.modelRouting`
+- `maintenance.checkpoints`
+- `recovery.enabled`
+- `recovery.resumeResumingRunsOnStartup`
+- `recovery.maxRecoveryAttempts`
+
+`recovery.resumeResumingRunsOnStartup` 将 checkpoint 恢复保持为运行时拥有的生命周期行为，而不是把 checkpoint 编排暴露为主 API。
+
+示例：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Runtime
+metadata:
+  name: default
+spec:
+  runRoot: ./.agent
+  concurrency:
+    maxConcurrentRuns: 3
+  routing:
+    defaultAgentId: orchestra
+    modelRouting: false
+  maintenance:
+    checkpoints:
+      enabled: true
+  recovery:
+    enabled: true
+    resumeResumingRunsOnStartup: true
+    maxRecoveryAttempts: 3
+```
+
+### `config/agent-context.md`
+
+用于在构建 agent 时加载的共享启动记忆。
+
+在此放置稳定的项目上下文；视为启动上下文，而非可变长期记忆。
+
+### `config/models.yaml`
+
+命名聊天模型预设：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Models
+spec:
+  - name: default
+    provider: openai
+    model: gpt-4.1
+    temperature: 0.2
+```
+
+加载为 `model/default`。
+
+### `config/embedding-models.yaml`
+
+面向检索类工具的命名嵌入模型预设。
+
+### `config/vector-stores.yaml`
+
+检索工具引用的命名向量库预设。
+
+### `config/stores.yaml`
+
+可复用的存储与 checkpointer 预设：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Stores
+spec:
+  - kind: Store
+    name: default
+    storeKind: FileStore
+    path: store.json
+  - kind: Checkpointer
+    name: default
+    checkpointerKind: MemorySaver
+  - kind: Checkpointer
+    name: sqlite
+    checkpointerKind: SqliteSaver
+    path: checkpoints.sqlite
+```
+
+### `config/backends.yaml`
+
+可复用的 DeepAgents 后端预设，使文件系统与 `/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/tools.yaml`
+
+可复用工具对象。
+
+内置工具族包括函数工具、后端工具、MCP 工具、bundle 与原生 provider 工具。原生 provider 工具在 YAML 中声明并直接解析到上游工厂。
+
+### `config/mcp.yaml`
+
+命名 MCP 服务预设。
+
+### `config/agents/*.yaml`
+
+Agent 始终使用 `kind: Agent` 以及 `spec.execution.backend`。
+
+两个嵌套区块：
+
+- `spec.runtime`：harness 侧运行时放置，例如 `spec.runtime.runRoot`
+- `spec.execution`：上游执行语义与面向适配器的配置
+
+direct 主机示例：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: direct
+spec:
+  runtime:
+    runRoot: ./.agent
+  execution:
+    backend: langchain-v1
+    modelRef: model/default
+    tools: []
+    skills: []
+    memory: []
+    subagents: []
+    mcpServers: []
+    config:
+      checkpointer:
+        ref: checkpointer/default
+      store:
+        ref: store/default
+      interruptOn: {}
+      filesystem:
+        rootDir: .
+        virtualMode: true
+        maxFileSizeMb: 10
+      middleware: []
+      systemPrompt: Answer simple requests directly.
+```
+
+orchestra 主机示例：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: orchestra
+spec:
+  runtime:
+    runRoot: ./.agent
+  execution:
+    backend: deepagent
+    modelRef: model/default
+    memory:
+      - path: config/agent-context.md
+    tools: []
+    skills: []
+    subagents: []
+    mcpServers: []
+    config:
+      store:
+        ref: store/default
+      checkpointer:
+        ref: checkpointer/default
+      backend:
+        ref: backend/default
+      interruptOn: {}
+      middleware: []
+      generalPurposeAgent: true
+      taskDescription: Complete delegated sidecar work and return concise results without bloating the parent context.
+```
+
+后端相关选项优先直接写在 `spec.execution.config` 中沿用上游概念。上游能力覆盖见 [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md)。
+
+## 设计说明
+
+- `agent-harness` 不是第三个 agent 框架
+- 公共运行时契约保持通用且精简
+- 应用级编排与生命周期管理留在 harness 中
+- 应尽量在 YAML 中直接表达 LangChain v1 与 DeepAgents 的概念
+- 能用 YAML 表达的能力，优先 YAML 而非扩张公共 API
+- 恢复、审批、线程、运行与事件是运行时概念，不是后端逃生舱
+- 新的 LangChain v1 或 DeepAgents 配置应先落在 YAML 映射与测试中，再考虑公共运行时 API
+
+简言之：产品模型稳定，执行语义仍归上游。
+
+## API 摘要
+
+主要导出：
+
+- `createAgentHarness`
+- `AgentHarnessRuntime`
+- `run`
+- `resolveApproval`
+- `subscribe`
+- `listThreads`
+- `getThread`
+- `deleteThread`
+- `listApprovals`
+- `getApproval`
+- `createToolMcpServer`
+- `serveToolsOverStdio`
+- `stop`

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.56";
+export declare const AGENT_HARNESS_VERSION = "0.0.58";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.56";
+export const AGENT_HARNESS_VERSION = "0.0.58";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",