@botbotgo/agent-harness 0.0.234 → 0.0.235

package/README.md

@@ -44,6 +44,8 @@
   >
 </p>
 
+<a id="readme-en-start"></a>
+
 ## Start in a few lines
 
 You can boot an agent runtime in a few lines of code:
@@ -69,6 +71,8 @@ The goal is an **operable** runtime: approvals, recovery, inspection, and govern
 Where you already use LangChain v1 or DeepAgents for execution, agent-harness adds the product runtime layer around
 them without forcing a rewrite.
 
+<a id="readme-en-docs-path"></a>
+
 ## Documentation Paths
 
 Choose an entry point that matches what you need:
@@ -83,7 +87,20 @@ Recommended entry points:
 - [Side-by-side comparison](./docs/development/comparison.html)
 - [API reference](./docs/development/api-reference.html)
 - [Protocol surfaces](./docs/development/protocol-surfaces.html)
+- [Release notes](./docs/development/release-notes.html) (English: `RELEASE_NOTES.md`; Chinese: [`zh/release-notes`](./docs/development/zh/release-notes.html) / `RELEASE_NOTES.zh.md`)
 - [Commercial service offerings](./docs/commercial-pricing.md)
+- [Topical docs index](./docs/README.md) (all `docs/*.md` in one table)
+
+### How to use this README
+
+This file is both a quickstart and a long reference—you do not need to read it top to bottom.
+
+| If you have… | Read this first | Then |
+| --- | --- | --- |
+| **~5 minutes** | [Start in a few lines](#readme-en-start) and [Documentation Paths](#readme-en-docs-path) | Open [Getting started](./docs/development/getting-started.html) in the developer docs. |
+| **First real integration** | [Quick Start](#readme-en-quickstart) → [How To Configure](#readme-en-config) | [Workspace and YAML](./docs/development/workspace-and-yaml.html) · [Topic index](./docs/README.md) · feature guides under [`docs/`](./docs/) |
+| **Operations / governance** | [Runtime capabilities at a glance](#readme-en-runtime-glance) → [Primary use cases](#readme-en-use-cases) | [Runtime operations](./docs/development/runtime-operations.html) and [`docs/tool-execution-policy.md`](./docs/tool-execution-policy.md). |
+| **API lookup** | Skip to [API Summary](#readme-en-api-summary) | Use it as a bookmarked index; the [API reference](./docs/development/api-reference.html) has fuller detail. |
 
 ## License & Commercial Support
 
@@ -116,10 +133,12 @@ Additional docs:
 **At a glance:** onboarding stays thin, the runtime ships as a full layer, and day-to-day work lives in **YAML** plus **extensions** (local tools, SKILL packages, MCP)—not bespoke runtime plumbing.
 
 - **Easy to start:** `createAgentHarness` → `request` → `stop`, plus inspection helpers such as `subscribe`, `listSessions`, `listApprovals`, and `resolveApproval`.
-- **Configure:** routing, models, tools, stores, backends, MCP, recovery, and maintenance in declarative workspace YAML (see [Quick Start](#quick-start) and [How To Configure](#how-to-configure)).
+- **Configure:** routing, models, tools, stores, backends, MCP, recovery, and maintenance in declarative workspace YAML (see [Quick Start](#readme-en-quickstart) and [How To Configure](#readme-en-config)).
 - **Extend:** drop `tool({...})` modules and SKILL trees under `resources/`, wire shared tools and MCP in catalogs, and let agents whitelist what they use.
 - **Built into the runtime:** persisted `requests`, `sessions`, `approvals`, and `events`; recovery and queueing; streaming listeners; MCP in/out; LangChain v1 and DeepAgents adapters—so you do not rebuild that layer per app.
 
+<a id="readme-en-runtime-glance"></a>
+
 ## Runtime capabilities at a glance
 
 The public API spans a full product runtime—persistent records, memory and evidence, protocol surfaces, and governance—not only a thin bootstrap around YAML and tools.
@@ -238,6 +257,7 @@ Start with these user-facing docs:
 - `docs/development/api-reference.html`
 - `docs/development/protocol-surfaces.html`
 - `docs/development/cookbook.html`
+- `docs/development/release-notes.html`
 - `docs/runtime-inspection-contract.md`
 - `docs/tool-execution-policy.md`
 - `docs/long-term-memory.md`
@@ -262,6 +282,8 @@ Recommended orchestration shape for long-running flows:
 - It lets YAML own assembly and operating policy while code keeps a small, stable surface
 - It goes deep on runtime concerns that upstream libraries do not fully productize
 
+<a id="readme-en-use-cases"></a>
+
 ## Primary use cases
 
 These scenarios map most directly to what the runtime is built for:
@@ -297,6 +319,8 @@ Do not reach for it when:
 - you are looking for a workflow builder or low-code automation canvas
 - you want to replace LangChain v1 or DeepAgents execution semantics rather than operate around them
 
+<a id="readme-en-quickstart"></a>
+
 ## Quick Start
 
 Install:
@@ -643,6 +667,8 @@ import { stop } from "@botbotgo/agent-harness";
 await stop(runtime);
 ```
 
+<a id="readme-en-config"></a>
+
 ## How To Configure
 
 Use Kubernetes-style YAML:
@@ -970,6 +996,8 @@ For backend-specific options, prefer the upstream concept directly inside `spec.
 
 In short, the product model stays stable while the execution semantics remain upstream-owned.
 
+<a id="readme-en-api-summary"></a>
+
 ## API Summary
 
 Primary exports:

package/README.zh.md

@@ -44,6 +44,8 @@
   >
 </p>
 
+<a id="readme-zh-start"></a>
+
 ## 几行代码启动
 
 几行代码即可把工作区跑成智能体运行时：
@@ -67,6 +69,8 @@ try {
 
 目标是交付<strong>可运维</strong>的运行时：审批、恢复、可观测与治理默认就绪。若执行层已采用 LangChain v1 或 DeepAgents，可在其之上衔接产品级运行时，无需推倒重来。
 
+<a id="readme-zh-docs-path"></a>
+
 ## 阅读路径
 
 按你的目标选入口即可：
@@ -81,7 +85,20 @@ try {
 - [并列对比页](./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)为准。 |
 
 ## 许可证与商业支持
 
@@ -112,10 +129,12 @@ try {
 **一句话：** 对外接口保持精简、运行时能力一次备齐，日常工作落在 **YAML 配置** 与 **扩展**（本地工具、SKILL、MCP）上，而不是反复搭建运行时底座。
 
 - **容易上手：** `createAgentHarness` → `request` → `stop`，以及 `subscribe`、`listSessions`、`listApprovals`、`resolveApproval` 等查询与控制能力。
-- **配置：** 路由、模型、工具、存储、后端、MCP、恢复与维护写在声明式工作区 YAML 里（见[快速开始](#快速开始)与[如何配置](#如何配置)）。
-- **扩展：** 在 `resources/` 下放置 `tool({...})` 模块与 SKILL 目录，在目录里声明共享工具与 MCP，再由各 agent 按名字白名单启用。
+- **配置：** 路由、模型、工具、存储、后端、MCP、恢复与维护写在声明式工作区 YAML 里（见[快速开始](#readme-zh-quickstart)与[如何配置](#readme-zh-config)）。
+- **扩展：** 在 `resources/` 下放置 `tool({...})` 模块与 SKILL 包；共享工具与 MCP 写在 `config/catalogs/` 等 YAML 目录里，各 agent 再按名称白名单引用。
 - **内建运行时：** 持久化 `requests`、`sessions`、`approvals` 与 `events`；恢复与排队；流式监听；MCP 接入与对外暴露；LangChain v1 与 DeepAgents 适配——避免每个应用重复造这一层。
 
+<a id="readme-zh-runtime-glance"></a>
+
 ## 运行时能力速览
 
 若你想先看「今天能直接用到什么」，可从本节读起。`agent-harness` 提供完整的产品级运行时能力，而不只是「能启动」的脚手架。
@@ -234,6 +253,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - `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-term-memory.md`
@@ -258,6 +278,8 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - 复杂装配与运行策略交给 YAML，代码面保持小而稳
 - 在上游库未充分产品化的运行时问题上做深做透
 
+<a id="readme-zh-use-cases"></a>
+
 ## 典型应用场景
 
 下面三类用法与 runtime 的设计目标最直接对应：
@@ -293,6 +315,8 @@ governance:
 - 你要的是工作流搭建器或低代码自动化画布
 - 你想替代 LangChain v1 或 DeepAgents 的执行语义，而不是围绕它们做运行时
 
+<a id="readme-zh-quickstart"></a>
+
 ## 快速开始
 
 安装：
@@ -606,6 +630,8 @@ import { stop } from "@botbotgo/agent-harness";
 await stop(runtime);
 ```
 
+<a id="readme-zh-config"></a>
+
 ## 如何配置
 
 使用 Kubernetes 风格的 YAML：
@@ -928,6 +954,8 @@ spec:
 
 简言之：产品模型稳定，执行语义仍归上游。
 
+<a id="readme-zh-api-summary"></a>
+
 ## API 摘要
 
 主要导出：

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.233";
+export declare const AGENT_HARNESS_VERSION = "0.0.234";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.233";
+export const AGENT_HARNESS_VERSION = "0.0.234";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.234",
+  "version": "0.0.235",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",
@@ -71,6 +71,8 @@
     "security:ci": "npm audit --omit=dev --audit-level=high",
     "security:report": "npm audit --omit=dev --json > security-audit-report.json || true",
     "docs:sync-dev-nav": "node ./scripts/sync-developer-docs-nav.mjs",
+    "docs:sync-release-notes": "node ./scripts/sync-release-notes-html.mjs",
+    "docs:sync-docs-html": "node ./scripts/sync-release-notes-html.mjs && node ./scripts/sync-developer-docs-nav.mjs",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",
     "release:publish": "npm publish --access public --registry https://registry.npmjs.org/"