openclaw-agent-orchestration

openclaw-agent-orchestration 是小智 Claw 体系里的共享纯编排层，承载 provider 无关的 agent orchestration 语义。

它当前不是运行时，不是 Hub/Gateway side-effect 壳，也不是 provider SDK 适配层；它的职责是把多个消费者都需要的纯函数策略沉淀成稳定 contract。

当前职责

1. Tool schema normalization 与 function tool definition 转换。
2. Tool choice policy 与 provider compatibility downgrade。
3. Conversation repair，包括 chat replay、Responses replay、forced-stop cleanup、dangling tool-result repair。
4. Parallel tool-call normalization 与 approval-aware scheduling batches。
5. Tool Loop State 的纯数据模型、recovery 与 replay coordination。
6. Bounded retry-loop orchestration 与 retry-budget scaling。
7. Memory flush transcript read-plan、token projection 与 compaction flush gating policy。
8. Embedded run prompt-error、assistant-failure 与 auth-profile failover decision policy。
9. Failover error normalization、timeout detection 与 failover-status projection 纯语义。

明确不负责

1. Planner state。
2. Todo state。
3. Session persistence。
4. Runtime registries。
5. Subagent registries。
6. Transport clients。
7. Hub / Gateway / Admin side effects。
8. Provider API 发包逻辑。
9. 鉴权、计费、配额、审计。

文档入口

项目内 canonical 文档：

1. docs/package-contract.md
2. docs/api-surface-map.md
3. CONTRIBUTING.md
4. docs/releasing.md

说明：

1. 该包的 contract 真源已经迁入本子项目 docs，不再以父仓 steup/docs 正文为准。
2. 父仓保留的同名文档只作为跨项目导航入口，不再承担正文真源职责。
3. 导出面、breaking-change 规则、开发边界都应以本目录文档为准。

导入规则

允许：

import {
  applyToolChoicePolicy,
  repairOpenAiResponsesItems,
  resolveParallelToolCallScheduling,
} from "openclaw-agent-orchestration";

禁止把以下路径当作稳定 contract：

import { applyToolChoicePolicy } from "openclaw-agent-orchestration/src/tool-choice-policy.js";
import { applyToolChoicePolicy } from "openclaw-agent-orchestration/dist/index.js";

开发命令

1. 安装：npm install
2. 构建：npm run build
3. 类型检查：npm run check
4. 打包检查：npm run pack:check

本地开发说明

1. 消费方当前通过本仓本地依赖消费该包。
2. package contract 以 dist/index.js 与 dist/index.d.ts 为准，因此改动共享代码后要先在本包执行 build。
3. 推荐顺序：先在本包执行 npm run build 或 npm run check，再回到消费者工程刷新依赖并执行 build/typecheck。
4. openclaw 里存在少量 TypeScript path fallback 仅用于仓内开发便利，不属于本包对外 contract。

AI Coding 规则

项目级 AI coding 规则位于：

1. .github/copilot-instructions.md

核心要求：

1. 只在本包沉淀纯函数/纯数据 contract，不引入运行时副作用。
2. 不修改 dist/ 产物，始终改 src/ 并重新构建。
3. 导出面变化必须同步更新 package contract、surface map 与 CHANGELOG。

仓库维护基线

1. CI 位于 .github/workflows/ci.yml，默认执行 npm ci、npm run check、npm run build、npm run pack:check。
2. GitHub tag release workflow 位于 .github/workflows/release.yml。
3. Gitee tag release workflow 位于 .gitee/workflows/release.yml，使用 Gitee Go 原生 build@nodejs 与 release@gitee 插件自动构建并发布 release。
4. 已于 2026-04-23 在 Gitee Go 实测跑通 v0.1.0 发布链，release 页面已生成并挂出 release-package.tgz 附件。
5. Issue 模板位于 .github/ISSUE_TEMPLATE，用于 bug 与能力请求收口。
6. 发布说明位于 docs/releasing.md，用于约束版本、变更说明和消费者联动验证。