From 033e549a2eb6cb17a0c7396d8c0ec0b50e24ee57 Mon Sep 17 00:00:00 2001 From: "liqiankun.1111" Date: Tue, 11 Aug 2026 19:15:43 +0800 Subject: [PATCH 1/3] docs: add simplified kernel pipeline v3 Distill the latest coordination model into a readable view of Human, Harness, Plugin, Core, and external-system boundaries. Switch both READMEs to the V3 diagram and bump the internal version. --- README.md | 4 +- README.zh-CN.md | 4 +- VERSION | 2 +- docs/kernel-pipeline_v3.svg | 126 ++++++++++++++++++++++++++++++++++++ 4 files changed, 131 insertions(+), 5 deletions(-) create mode 100644 docs/kernel-pipeline_v3.svg diff --git a/README.md b/README.md index cf788fe..871368d 100644 --- a/README.md +++ b/README.md @@ -40,9 +40,9 @@ Start with the stable kernel: baton is one bidirectional pipeline. chat-tui carr ![baton kernel: one bidirectional pipeline](docs/kernel-pipeline_v1.svg) -v2 keeps that pipeline and makes baton a durable coordination kernel among humans, Harnesses, and Baton Plugins. Each participant keeps its own semantics and enters Core through typed ports: human intent becomes Input or an Interaction result, Harness-native verbs become Interaction drafts through Adapters, and every operation-producing Plugin reconcile verb first becomes an Interaction through the host. An approved execution gate then becomes a HarnessInvocation. Every Plugin-initiated Turn returns to the same Input, context, permission, and routing path. +v3 distills that pipeline to one stable boundary: humans, Harnesses, and Baton Plugins keep their own semantics and resources while coordinating through Core-owned Input, Interaction, HarnessInvocation, and Event facts. Plugins reach external systems through Connectors; every Plugin-initiated Turn still follows the same Input, context, permission, and routing path. -![Baton, Plugin, and Harness relationship](docs/kernel-pipeline_v2.svg) +![Baton v3 coordination kernel](docs/kernel-pipeline_v3.svg) The terminal has one focus and one host event loop; chat-tui isolates updates by surface, while Baton isolates third-party Package code in one Runner process per active Binding. A blocked or crashed Plugin therefore cannot occupy composer input, and its registrations are withdrawn as one unit. diff --git a/README.zh-CN.md b/README.zh-CN.md index a80ea16..cc5b07e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -40,9 +40,9 @@ Plugin host 又增加了一条原则： ![baton 内核：一条双向流水线](docs/kernel-pipeline_v1.svg) -v2 保留这条流水线，并让 baton 成为人、Harness 与 Baton Plugin 之间的持久协作内核。三方保留各自语义，通过 typed port 进入 Core：人的 intent 成为 Input 或 Interaction result，Harness 原生 verb 经 Adapter 成为 Interaction draft，Plugin reconcile verb 经 host 成为 Interaction 或 HarnessInvocation。所有 Plugin 发起的 Turn 都回到同一条 Input、Context、Permission 与 routing 路径。 +v3 将这条流水线收敛成一个稳定边界：人、Harness 与 Baton Plugin 保留各自语义和资源，通过 Core 持有的 Input、Interaction、HarnessInvocation 与 Event 事实协作。Plugin 通过 Connector 连接外部系统；所有 Plugin 发起的 Turn 仍回到同一条 Input、Context、Permission 与 routing 路径。 -![Baton、Plugin 与 Harness 的关系](docs/kernel-pipeline_v2.svg) +![Baton v3 协作内核](docs/kernel-pipeline_v3.svg) 终端只有一个焦点和一个宿主事件循环；chat-tui 按 surface 隔离订阅与重绘，Baton 则让每个活动的三方 Plugin Binding 进入独立 Runner 进程。某个 Plugin 阻塞或崩溃不会占住 composer，它的注册会作为一个整体撤销。 diff --git a/VERSION b/VERSION index e7ccda1..d4ca806 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.2.35 +0.2.36 diff --git a/docs/kernel-pipeline_v3.svg b/docs/kernel-pipeline_v3.svg new file mode 100644 index 0000000..2b540a4 --- /dev/null +++ b/docs/kernel-pipeline_v3.svg @@ -0,0 +1,126 @@ + + Baton Coordination Kernel + Human, Harness, and Baton Plugin coordinate through one durable Baton Core. Plugins connect to external systems while every participant keeps its own semantics and resources. + + + + + + + + + + + + + + + + + Baton Coordination Kernel + One core, three participants, typed coordination. + + + + Human + intent · prompt · decision + + + Harness + native session · model · sandbox + + + Baton Plugin + resource · controller · connector + + + External + system + + + + + observe · act + + + + + Input · Interaction + + + + Turn · Interaction · Event + + + + Reconcile verbs · result + + + + Baton Core + typed coordination · durable facts · controlled execution + + + Input + + + Interaction + + + HarnessInvocation + + + Event + + + durable coordination history + BatonSession · Lane · Event Ledger + + Core owns coordination facts; participants keep their own semantics and resources. + From cbcc68eb37dd46d4c727fe8ee0ea2944801f8f20 Mon Sep 17 00:00:00 2001 From: "liqiankun.1111" Date: Tue, 11 Aug 2026 19:20:08 +0800 Subject: [PATCH 2/3] docs: show plugin reconcile model in pipeline v3 Make the Plugin's Spec to Reconcile to Status loop explicit and label its Core boundary as ReconcileContext. --- docs/kernel-pipeline_v3.svg | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/kernel-pipeline_v3.svg b/docs/kernel-pipeline_v3.svg index 2b540a4..271b40f 100644 --- a/docs/kernel-pipeline_v3.svg +++ b/docs/kernel-pipeline_v3.svg @@ -1,6 +1,6 @@ Baton Coordination Kernel - Human, Harness, and Baton Plugin coordinate through one durable Baton Core. Plugins connect to external systems while every participant keeps its own semantics and resources. + Human, Harness, and Baton Plugin coordinate through one durable Baton Core. A Plugin reconciles Resource spec into status while connecting to external systems. @@ -77,7 +77,13 @@ Baton Plugin - resource · controller · connector + + Spec + → + Reconcile + → + Status + External @@ -99,7 +105,7 @@ - Reconcile verbs · result + ReconcileContext · result From 461ed9b542582cc8a1044c6098e8dc4ef9e79ace Mon Sep 17 00:00:00 2001 From: "liqiankun.1111" Date: Tue, 11 Aug 2026 19:31:18 +0800 Subject: [PATCH 3/3] docs: clarify plugin model and lane ledger wording Refocus the Plugin guide on Resource, reconcile, scoped verbs, and the authoring flow while keeping Core details local to concrete contracts. Describe BatonSession history as a cross-Harness, cross-Lane Event Ledger. --- VERSION | 2 +- docs/kernel.md | 4 +- docs/plugin.md | 119 +++++++++++++++++++++++++------------------------ 3 files changed, 64 insertions(+), 61 deletions(-) diff --git a/VERSION b/VERSION index d4ca806..aa04999 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.2.36 +0.2.37 diff --git a/docs/kernel.md b/docs/kernel.md index 86f6f39..aaaf1f4 100644 --- a/docs/kernel.md +++ b/docs/kernel.md @@ -13,7 +13,7 @@ Codex、Claude Code 等原生会话用于执行与加速恢复，不能成为逻 Baton core 位于三类参与者之间： -1. **人** 提交目标、编辑工作、回答问题与作出授权决定，并拥有 BatonSession 的正典历史。 +1. **人** 提交目标、编辑工作、回答问题与作出授权决定，并拥有 BatonSession 的 Event Ledger。 2. **Harness** 提供推理、工具调用与原生执行能力，Adapter 把各家协议归一成稳定契约。 3. **Baton Plugin** 以 Resource 的 `spec/status` 表达长期领域 loop，由 Controller reconcile； 通过 `ReconcileContext` 请求人的决定、准备草稿或发起 Harness Turn，不能直接调用 Harness。 @@ -54,7 +54,7 @@ Core 直接改变另一方状态。 | 概念 | 语义与 owner | |---|---| | **Project** | 按 cwd 组织和发现 BatonSession，并承载同 workspace 跨 Session 的 Plugin 私有数据；不拥有 Session 历史 | -| **BatonSession** | 用户拥有的正典逻辑历史和 session-scoped Plugin 数据；跨 Harness 的唯一时间线 | +| **BatonSession** | 用户拥有的跨 Harness、跨 Lane Event Ledger，以及 session-scoped Plugin 数据 | | **HarnessTarget** | Baton 配置、调度和状态查询侧的一份具体执行目标；同一 Harness 可有多个 Target，状态必须按 Target 隔离 | | **Lane** | BatonSession 原生的持久串行任务线；主线 identity 为保留值 `main`，支线使用 `hl_` identity，可由人或 Plugin 发起，并可跨多个 HarnessTarget 接力 | | **HarnessSession** | Harness 在某个 `Lane × HarnessTarget` 下持有的持久原生执行会话；缺失只影响恢复优化，不阻止 Lane 继续 | diff --git a/docs/plugin.md b/docs/plugin.md index ef65781..21aa110 100644 --- a/docs/plugin.md +++ b/docs/plugin.md @@ -1,16 +1,14 @@ # Baton Plugin -Plugin 让长期领域 loop 在不进入 Baton core 的前提下拥有自己的 Resource、Controller、Connector -和用户入口。本文定义 Plugin 的理念、运行模型和主流程；公共 TypeScript API 与最短示例见 +Plugin 让长期领域 loop 拥有自己的 Resource、Controller、Connector 和用户入口，而不把领域模型 +固化在 Baton 中。本文定义 Plugin 的理念、运行模型和主流程；公共 TypeScript API 与最短示例见 [`packages/plugin/README.md`](../packages/plugin/README.md)，Resource 删除等细节见 [Resource 生命周期](./resource-lifecycle.md)。 ## 1. 理念与边界 -Baton core 不理解 Requirement、Deployment、Review 等领域语义，但它不是透明消息总线：Core -拥有 Interaction、HarnessInvocation、Input 与 Event 的 identity、状态机、权限、调度和恢复。 -Plugin 作为三类参与者之一，通过 typed reconcile verbs 使用这些能力，可以封装完整 loop，也可以 -提供能独立演进的领域能力或本地自动化。 +Baton Plugin 是 Baton 的领域扩展机制。它用 Resource `spec/status` 保存长期目标与观测，由 Controller +执行 level-based reconcile，并通过 Connector 适配外部系统。 ```text 领域 loop = Resource(spec + status) + level-based reconcile @@ -21,21 +19,27 @@ Plugin 作为三类参与者之一，通过 typed reconcile verbs 使用这些 - `spec` 是用户认可的期望与 Contract； - `status` 是 Controller 重新观察或计算的当前状态； - signal 只提示“可能变化”，reconcile 每次读取最新事实； -- 智能判断通过 `ask/confirm/draft/harness` 组合人机步骤与 Harness 执行，不要求先把业务穷举成 DSL。 +- `ask/confirm/draft/harness` 让 reconcile 可以请求人的决定或 Harness 执行，不要求先把业务穷举成 + DSL。 + +这些 verbs 扩展的是 reconcile 作用域内的行动方式，不改变 Plugin 的稳定状态模型。Plugin 可以等待 +当前调用的终态并组合后续步骤，但不能直接持有 Harness，也不能把进程内调用栈当成恢复状态；长期 +loop 仍由 Resource facts 与下一次 level-based reconcile 推进。 ### 1.1 三种扩展边界 | 边界 | 职责 | |---|---| -| **Baton Plugin** | 运行在 Harness 之上的控制面，观察和推进跨 Session、跨系统的长期 loop | +| **Baton Plugin** | 定义领域 Resource、Controller 与 Connector，观察和推进跨 Session、跨系统的长期 loop | | **Harness** | Codex、Claude Code 等智能执行协议，负责推理、工具调用和原生 Session | | **Harness Plugin** | skill、hook、command 等 Harness 内扩展，约束当前 agent 小闭环 | devloop 属于 Harness Plugin：它规范开发、lint/test、commit 和 PR/MR，不注册为 Baton Plugin。 -reqloop 属于 Baton Plugin/Marketplace：它拥有 Requirement、Deployment、Evaluation 等领域模型 -与 Connector。外部系统适配留在 Plugin 内部，不提升为 Baton 的另一种顶层运行角色。 +reqloop 是独立仓库中的 Requirement Loop 项目，也是 Baton Plugin/Marketplace 的一个示例：它拥有 +Requirement、Deployment、Evaluation 等领域模型与 Connector。外部系统适配留在 Plugin 内部， +不提升为 Baton 的另一种顶层运行角色。 -## 2. 共同模型 +## 2. 共同模型与事实边界 ```text PluginPackage（不可变交付物） @@ -63,44 +67,9 @@ PluginPackage（不可变交付物） 它们可以通过 reference 和 reconcile 关联，但不能复制成可独立修改的第二真相源。 -## 3. Host 与进程边界 - -```text -Baton host process - ├── Interaction / Input / HarnessInvocation core - └── Plugin Manager - ├── Instance / Resource stores - ├── reconcile continuation / invocation correlation - ├── keyed reconcile queues / Sources / Watches / Board cache - └── Supervisor - └── Runner process × active Binding - └── third-party Package + Connector -``` - -**Manager** 是 Plugin 侧唯一装配入口，负责恢复 Instance、创建 Binding、安装注册、持久化 Resource、 -把 reconcile verbs 先 lowering 到 Core-owned Interaction、再把批准的执行 gate lowering 到 -HarnessInvocation，并控制 reconcile 容量和维护 Board cache。 - -**Supervisor** 只负责 Runner 子进程的启动、deadline、退出和回收，不理解 Resource 或领域策略。 - -**Runner** 加载一份 Package，保存 Plugin 回调，通过 IPC 执行 activate、Command、ContextProvider、 -Source、Watch、reconcile、present 和 cleanup。Runner 不直接访问 Baton Store、Controller、Harness -或 TUI。 - -隔离粒度选择 Binding，因为它同时是注册撤销、局部连接共享和故障回收的原子边界。同一 Package -在不同 Session 的可变状态不能共享；单次调用起进程又会破坏 Source/Connector 生命周期。 -进程隔离是故障和调度边界，不是安全沙箱：Plugin 仍以当前用户身份访问文件、网络和子进程。 - -IPC 只传可结构化克隆的数据。激活完成后注册表封口，避免异步偷注册留下半个 Binding。调用 -timeout、非法信封或进程退出时，Manager 撤销 Binding 的 Command、ContextProvider、Controller、 -Source 和 Board，并把该 Runner 尚未完成的 verb 以 `failure` 收口。Resource、Interaction、 -HarnessInvocation 和日志保留为事实，但进程内 continuation 不恢复。当前不自动重启失败 Runner， -因为外部副作用可能已经生效却没有回执。Runner 的一般调用 watchdog 在 verb 等待期间暂停；该段 -等待由 verb 自己的必填 timeout 约束。 - -## 4. Resource 与 reconcile 流程 +## 3. Resource 与 reconcile 流程 -### 4.1 Resource +### 3.1 Resource Plugin Resource 使用版本化类型身份： @@ -121,7 +90,7 @@ Resource 删除是 reconcile 生命周期，不是立即移除：Baton 先设置 后代级联删除请求，并在 terminating reconcile 成功后最终移除。完整契约见 [Resource 生命周期](./resource-lifecycle.md)。 -### 4.2 统一唤醒 +### 3.2 统一唤醒 ```text Resource change / startup / Source / Watch / cron / requeueAfter @@ -150,12 +119,12 @@ Plugin 对外部系统写入时仍应使用领域自己的幂等键。无法确 Baton-owned Resource 是 Event Ledger 的只读派生视图。当前 `baton.dev/v1alpha1, Kind=Turn` 让 Plugin 用同一 level-based 模型观察 Baton 行为；Plugin 不能修改或重新声明 Baton-owned type。 -## 5. Reconcile Context、Board 与 Context +## 4. ReconcileContext、Board 与 Context -### 5.1 Reconcile 作用域能力 +### 4.1 Reconcile 作用域能力 Controller 的第一个参数是 `ReconcileContext`：`snapshot` 提供冻结只读视图，其余方法是 -Plugin-facing typed Core verbs： +Plugin-facing typed verbs： - `ask`：请求一个选项或自由文本答案； - `confirm`：请求 accept / decline 决定； @@ -167,7 +136,7 @@ Plugin-facing typed Core verbs： 这些方法不是通用 `send(type, payload)`：`ask/confirm/draft/harness` 都先物化为 Interaction； `draft/harness` 只有在 对应 Interaction 提交或批准后才能继续物化为 HarnessInvocation。即使宿主策略自动批准 `harness`， -也必须先持久化 Interaction 的 requested/answered 事实。identity、准入和终态由 Core 决定；Plugin +也必须先持久化 Interaction 的 requested/answered 事实。identity、准入和终态由 Baton 决定；Plugin 不能提供 topic、路由 callback 或 Harness 原生 DTO。 每次能力调用都必须带正整数 `timeoutMs`，并真实 await 到 `success / dismissed / timeout / @@ -182,9 +151,8 @@ Interaction 后按 Esc 或关闭卡片返回 `dismissed`；总 deadline 到期 Interaction gate 与后续整个 HarnessInvocation，不在 gate 通过后重置。 Plugin 可以自由组合这些 primitives：有的 gate 由策略自动批准，有的等待用户，再按结果进入 -draft、主 Lane 或新 Lane。这个策略属于领域编排和宿主 policy，不由 Core 从 Plugin 类型推断。 -Core 始终拥有 -Interaction、Harness routing、权限、并发、取消、Context、ledger 和恢复。完整契约见 +draft、主 Lane 或新 Lane。这个策略属于领域逻辑和宿主 policy，不由 Baton 从 Plugin 类型推断； +Interaction、Harness routing、权限、并发、取消和恢复仍由 Baton 承接。完整契约见 [`@compforge/baton-plugin` README](../packages/plugin/README.md)。 Resource 删除不会替 live Plugin execution 决定 verb 终态；当前调用仍由回答、Esc、timeout 或 @@ -195,7 +163,7 @@ Lane 参数与 Input source 正交：`laneId:"main"` 继续主线，`newLane:tru 边界，不是 Plugin 私有对象、worktree 策略或“前台/后台”标签。`createdFor` 仅记录创建事实， 不会阻止其它 invocation 继续该 Lane。 -### 5.2 Board +### 4.2 Board Controller 的 `present(resource)` 把一份 Resource 派生为至多一个 Board 条目。Baton 补齐 owner、 Resource reference 和身份，再生成面向用户的 Board view。`present` 只读、可重复，不能修改 @@ -205,7 +173,7 @@ Board 是共享协作读模型，但不是 Event、Resource 或外部系统的 和 Resource Type 分组排序，每组只展示有限条目，避免一个 Plugin 占满侧栏。持续状态进入 Resource status/Board；toast 只用于一次操作或状态边沿的短寿命反馈。 -### 5.3 Context +### 4.3 Context ContextProvider 提供用户通过 `@` 明确选择的只读 Context。`search` 无副作用，`provide` 遵守 `maxChars`，不能返回 secret。Binding 关闭时注册整体撤销。 @@ -217,6 +185,41 @@ ContextProvider 提供用户通过 `@` 明确选择的只读 Context。`search` Plugin presentation 变化只更新读模型；只有用户提交 Input 或 HarnessInvocation 准备执行时，Baton 才组装 Context，并以 DeliveryReceipt 记录 transport 已接受。 +## 5. Host 与进程边界 + +```text +Baton host process + ├── Interaction / Input / HarnessInvocation + └── Plugin Manager + ├── Instance / Resource stores + ├── reconcile continuation / invocation correlation + ├── keyed reconcile queues / Sources / Watches / Board cache + └── Supervisor + └── Runner process × active Binding + └── third-party Package + Connector +``` + +**Manager** 是 Plugin 侧唯一装配入口，负责恢复 Instance、创建 Binding、安装注册、持久化 Resource、 +把 reconcile verbs 先 lowering 到 Baton-owned Interaction、再把批准的执行 gate lowering 到 +HarnessInvocation，并控制 reconcile 容量和维护 Board cache。 + +**Supervisor** 只负责 Runner 子进程的启动、deadline、退出和回收，不理解 Resource 或领域策略。 + +**Runner** 加载一份 Package，保存 Plugin 回调，通过 IPC 执行 activate、Command、ContextProvider、 +Source、Watch、reconcile、present 和 cleanup。Runner 不直接访问 Baton Store、Controller、Harness +或 TUI。 + +隔离粒度选择 Binding，因为它同时是注册撤销、局部连接共享和故障回收的原子边界。同一 Package +在不同 Session 的可变状态不能共享；单次调用起进程又会破坏 Source/Connector 生命周期。 +进程隔离是故障和调度边界，不是安全沙箱：Plugin 仍以当前用户身份访问文件、网络和子进程。 + +IPC 只传可结构化克隆的数据。激活完成后注册表封口，避免异步偷注册留下半个 Binding。调用 +timeout、非法信封或进程退出时，Manager 撤销 Binding 的 Command、ContextProvider、Controller、 +Source 和 Board，并把该 Runner 尚未完成的 verb 以 `failure` 收口。Resource、Interaction、 +HarnessInvocation 和日志保留为事实，但进程内 continuation 不恢复。当前不自动重启失败 Runner， +因为外部副作用可能已经生效却没有回执。Runner 的一般调用 watchdog 在 verb 等待期间暂停；该段 +等待由 verb 自己的必填 timeout 约束。 + ## 6. Plugin authoring 约束 Plugin 只能依赖公共类型包：