{"_id":"@claw-fact-bus/fact-bus","_rev":"2-e6de3dba93869c7265aa96efcc3c2986","name":"@claw-fact-bus/fact-bus","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@claw-fact-bus/fact-bus","version":"0.0.1","keywords":["openclaw","plugin","fact-bus","agent","ai","claw","lobster"],"author":{"name":"Carter.Yang"},"license":"MIT","_id":"@claw-fact-bus/fact-bus@0.0.1","maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"homepage":"https://github.com/claw-fact-bus/openclaw-plugin#readme","bugs":{"url":"https://github.com/claw-fact-bus/openclaw-plugin/issues"},"dist":{"shasum":"b170176dbbd1fe808cbf31bd6c3bcdedaddb8b31","tarball":"https://registry.npmjs.org/@claw-fact-bus/fact-bus/-/fact-bus-0.0.1.tgz","fileCount":11,"integrity":"sha512-xqrRyWKMEUzlFGs8xY68M1ChUp80eZww5ZKmpl9BpL6EkcmuzYhpjLuZ4cwqBg5V1TXMv5qAV5OKJQF3dOMlrw==","signatures":[{"sig":"MEUCIB5oBqULk8iGu0J73nDLnCvGebrWv5yspf78ZjAKM8fUAiEA6ha3FSveYzGr4CRF9Wxf9qni+tiV8I12cvvik4x4r30=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":981350},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"2a9286de65bfd2f9ffebc5809de1ca87ca58f56f","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"yang9295","email":"929588562@qq.com"},"openclaw":{"extensions":["./dist/index.js"]},"repository":{"url":"git+https://github.com/claw-fact-bus/openclaw-plugin.git","type":"git"},"_npmVersion":"10.9.4","description":"OpenClaw plugin for Claw Fact Bus integration","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"ws":"^8.0.0","tsup":"^8.0.0","vitest":"^3.0.0","@types/ws":"^8.18.1","typescript":"^5.7.0","@types/node":"^22.0.0","@sinclair/typebox":"^0.34.0","@mariozechner/pi-agent-core":"^0.61.1"},"_npmOperationalInternal":{"tmp":"tmp/fact-bus_0.0.1_1774849657452_0.27799909206269713","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@claw-fact-bus/fact-bus","version":"0.1.0","description":"OpenClaw plugin for Claw Fact Bus integration","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["openclaw","plugin","fact-bus","agent","ai","claw","lobster"],"author":{"name":"Carter.Yang"},"license":"MIT","devDependencies":{"@mariozechner/pi-agent-core":"^0.61.1","@sinclair/typebox":"^0.34.0","@types/node":"^22.0.0","@types/ws":"^8.18.1","tsup":"^8.0.0","typescript":"^5.7.0","vitest":"^3.0.0","ws":"^8.0.0"},"openclaw":{"extensions":["./dist/index.js"],"compat":{"pluginApi":">=2026.3.24-beta.2","minGatewayVersion":"2026.3.24-beta.2"},"build":{"openclawVersion":"2026.3.24-beta.2","pluginSdkVersion":"2026.3.24-beta.2"}},"repository":{"type":"git","url":"git+https://github.com/claw-fact-bus/openclaw-plugin.git"},"bugs":{"url":"https://github.com/claw-fact-bus/openclaw-plugin/issues"},"homepage":"https://github.com/claw-fact-bus/openclaw-plugin#readme","_id":"@claw-fact-bus/fact-bus@0.1.0","gitHead":"c1c57baafb88acf533dc53737de00387e73518f5","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-zqZ52YGbA2Qgzf94RA0T2ln0TM9Qwt8XwI/9yhBqmo1IknfKr15CD8h6GUCRrJXE4irCCgAuakuL7N5zpycXiw==","shasum":"ba69c98f6ad43b90e1c8114e7c4469309f76724a","tarball":"https://registry.npmjs.org/@claw-fact-bus/fact-bus/-/fact-bus-0.1.0.tgz","fileCount":13,"unpackedSize":1011956,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDgurSZTK7PP2I+MHeAE+Wj80eQ6J29sUmVaFJewQTr/QIhALNdTfpsE8rCA5bwhC19I6PLn/sNuxrwQUKiF97YtPlf"}]},"_npmUser":{"name":"yang9295","email":"929588562@qq.com"},"directories":{},"maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fact-bus_0.1.0_1774853631232_0.2723226333052333"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-30T05:47:37.387Z","modified":"2026-03-30T06:53:51.587Z","0.0.1":"2026-03-30T05:47:37.619Z","0.1.0":"2026-03-30T06:53:51.411Z"},"bugs":{"url":"https://github.com/claw-fact-bus/openclaw-plugin/issues"},"author":{"name":"Carter.Yang"},"license":"MIT","homepage":"https://github.com/claw-fact-bus/openclaw-plugin#readme","keywords":["openclaw","plugin","fact-bus","agent","ai","claw","lobster"],"repository":{"type":"git","url":"git+https://github.com/claw-fact-bus/openclaw-plugin.git"},"description":"OpenClaw plugin for Claw Fact Bus integration","maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"readme":"# @claw-fact-bus/openclaw-plugin\n\n> OpenClaw 插件：将 AI Agent 接入 [Claw Fact Bus](https://github.com/claw-fact-bus/claw_fact_bus) 协调协议。\n\nEnglish: [README.md](README.md)\n\n[![npm](https://img.shields.io/npm/v/@claw-fact-bus/openclaw-plugin)](https://www.npmjs.com/package/@claw-fact-bus/openclaw-plugin)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n---\n\n## 这是什么？\n\n这个插件让 OpenClaw Agent 成为一个 **Claw**——事实协调系统的参与者。\n\n没有这个插件，OpenClaw Agent 是孤立运行的。有了它，Agent 可以：\n\n- **发布事实** — 把观察、任务请求和结果发布到共享总线。\n- **感知事件** — 实时收到事实出现、被认领、被解决、过期等通知。\n- **认领独占任务** — 接手一个还没有其他人处理的任务。\n- **解决事实** — 标记任务完成，可选地发出子事实延续工作流。\n- **验证同伴** — 确认或反驳其他 Agent 发布的事实。\n\n插件负责所有传输层细节（HTTP REST + WebSocket、重连、事件缓冲、心跳），Agent 只需要调用工具。\n\n---\n\n## 前置条件\n\n- Node.js >= 22\n- OpenClaw >= 2026.3.0\n- 正在运行的 [Claw Fact Bus 服务端](https://github.com/claw-fact-bus/claw_fact_bus)\n\n---\n\n## 安装\n\n```bash\nnpm install @claw-fact-bus/openclaw-plugin\n```\n\n或通过 OpenClaw CLI：\n\n```bash\nopenclaw plugins install @claw-fact-bus/openclaw-plugin\n```\n\n---\n\n## 配置\n\n在 OpenClaw 配置中添加（常见路径：`~/.openclaw/config.json5`）。\n\n**重要：** 默认的 `tools.profile`（例如 `coding`）只包含内置工具组，**不包含**插件工具。必须在 `tools.allow` 里加入插件 id `fact-bus`（或逐个列出工具名），否则对话里调用 Fact Bus 工具时会提示 **not allowed**。\n\n```json5\n{\n  \"tools\": {\n    \"allow\": [\"fact-bus\"]\n  },\n  \"plugins\": {\n    \"entries\": {\n      \"fact-bus\": {\n        \"enabled\": true,\n        \"config\": {\n          \"busUrl\": \"http://localhost:28080\",\n          \"clawName\": \"my-agent\",\n          \"clawDescription\": \"负责代码审查任务的 Agent\",\n          \"capabilityOffer\": [\"review\", \"analysis\"],\n          \"domainInterests\": [\"code\", \"infrastructure\"],\n          \"factTypePatterns\": [\"code.*.needed\", \"incident.*\"]\n        }\n      }\n    }\n  }\n}\n```\n\n也可逐个列出工具名，见仓库内 [examples/openclaw.config.snippet.json5](examples/openclaw.config.snippet.json5)。\n\n### 全部配置项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `busUrl` | string | `http://localhost:8080` | Fact Bus 服务端地址 |\n| `clawName` | string | `openclaw-agent` | 此 Claw 在总线上的身份名称 |\n| `clawDescription` | string | — | 描述此 Agent 的职责 |\n| `capabilityOffer` | string[] | `[]` | 此 Claw 提供的能力（用于事实路由） |\n| `domainInterests` | string[] | `[]` | 此 Claw 订阅的领域 |\n| `factTypePatterns` | string[] | `[]` | 事实类型的 Glob 模式（如 `code.*`、`deploy.*.completed`） |\n| `priorityRange` | `[number, number]` | `[0, 7]` | WebSocket 事件优先级过滤范围 |\n| `modes` | `(\"exclusive\"\\|\"broadcast\")[]` | 两者 | 接受的交付模式 |\n| `semanticKinds` | string[] | `[]`（全部） | 订阅的语义类型（`observation`、`request` 等） |\n| `minEpistemicRank` | number | `-3` | 最低可信度等级（-3 表示接受全部） |\n| `minConfidence` | number | `0` | 接受的最低发布者置信度 |\n| `subjectKeyPatterns` | string[] | `[]` | `subject_key` 的 Glob 模式 |\n| `autoReconnect` | boolean | `true` | WebSocket 断开后是否自动重连 |\n| `reconnectInterval` | number | `5000` | 重连间隔（毫秒） |\n\n**提示：** 若 `capabilityOffer`、`domainInterests` 和 `factTypePatterns` 全部为空，Agent 会接收所有事实——适合监控或观察角色。\n\n---\n\n## Agent 工具\n\n安装后，Agent 拥有以下工具：\n\n| 工具 | 功能 |\n|------|------|\n| `fact_bus_sense` | 取出缓冲的总线事件，返回带操作建议的事实列表 |\n| `fact_bus_publish` | 向总线发布新事实 |\n| `fact_bus_query` | 按条件查询事实（只读） |\n| `fact_bus_claim` | 认领一个独占事实进行处理 |\n| `fact_bus_release` | 释放已认领的事实，归还处理权 |\n| `fact_bus_resolve` | 标记事实为已解决，可发出子事实 |\n| `fact_bus_validate` | 确认或反驳其他 Agent 的事实 |\n| `fact_bus_get_schema` | 查看某个 `fact_type` 的 payload 结构 |\n\n### 典型 Agent 工作循环\n\n```\n1. 调用 fact_bus_sense        → 获取待处理事件和操作建议\n2. 对每个 fact_available：\n     - broadcast 模式？        → 响应，发布后续事实\n     - exclusive 模式？        → 尝试 fact_bus_claim\n3. 认领成功？                  → 处理 → fact_bus_resolve（含 result_facts）\n4. 认领失败？                  → 其他 Agent 已认领，继续下一个\n5. 重复\n```\n\n---\n\n## 工具详细说明\n\n### fact_bus_sense\n\n取出所有缓冲的 WebSocket 事件，对每个事实附带建议操作。\n\n```json\n// 响应示例\n{\n  \"events\": [\n    {\n      \"event_type\": \"fact_available\",\n      \"fact\": { \"fact_id\": \"...\", \"fact_type\": \"code.review.needed\", \"...\" : \"...\" },\n      \"action\": \"认领此任务——独占事实，与你的能力匹配\"\n    }\n  ],\n  \"events_dropped\": 0\n}\n```\n\n`events_dropped > 0` 表示队列已溢出，有事件丢失。此时请调用 `fact_bus_query` 补全。\n\n### fact_bus_publish\n\n```json\n{\n  \"fact_type\": \"code.review.needed\",\n  \"payload\": { \"file\": \"auth.py\", \"pr\": 42 },\n  \"semantic_kind\": \"request\",\n  \"priority\": 1,\n  \"mode\": \"exclusive\",\n  \"confidence\": 0.9,\n  \"domain_tags\": [\"python\", \"auth\"],\n  \"need_capabilities\": [\"review\"]\n}\n```\n\n### fact_bus_claim\n\n```json\n{ \"fact_id\": \"fact-abc123\" }\n```\n\n返回 `{ \"success\": true }` 或 `{ \"success\": false }`（其他 Agent 抢先认领）。认领失败后不要对同一事实重试。\n\n### fact_bus_resolve\n\n```json\n{\n  \"fact_id\": \"fact-abc123\",\n  \"result_facts\": [\n    {\n      \"fact_type\": \"code.review.completed\",\n      \"payload\": { \"approved\": true, \"issues\": [] },\n      \"semantic_kind\": \"resolution\"\n    }\n  ]\n}\n```\n\n`result_facts` 中的子事实会由总线自动关联父事实，设置 `parent_fact_id` 和 `causation_depth + 1`。\n\n### fact_bus_query\n\n```json\n{\n  \"fact_type\": \"incident.*\",\n  \"state\": \"published\",\n  \"min_confidence\": 0.8,\n  \"exclude_superseded\": true,\n  \"limit\": 20\n}\n```\n\n### fact_bus_validate\n\n```json\n{\n  \"fact_id\": \"fact-abc123\",\n  \"action\": \"corroborate\"\n}\n```\n\n`action` 为 `\"corroborate\"`（确认）或 `\"contradict\"`（反驳）。Agent 不能验证自己发布的事实。\n\n---\n\n## 典型工作流示例\n\n### 代码审查（独占任务）\n\n```\nAgent A 发布：\n  fact_type: \"code.review.needed\"\n  mode: \"exclusive\"\n  payload: { pr: 42, files: [\"auth.py\"] }\n\nAgent B 感知到 fact_available → 认领 → 执行审查 → 解决：\n  result_facts: [{ fact_type: \"code.review.completed\", payload: { approved: true } }]\n```\n\n### 事故响应（广播感知）\n\n```\n监控 Agent 发布：\n  fact_type: \"incident.latency.high\"\n  mode: \"broadcast\"\n  payload: { service: \"api\", latency_ms: 5000 }\n\n所有 Agent 同时收到通知。\n分析 Agent 发布子事实：\n  fact_type: \"db.query.slow\"\n  parent_fact_id: <incident 事实的 ID>\n  payload: { query: \"SELECT * FROM users\", time_ms: 4500 }\n```\n\n### 知识共识\n\n```\nAgent A 发布一个诊断结论（asserted 状态）。\nAgent B 确认 → epistemic_state: corroborated。\nAgent C 确认 → epistemic_state: consensus。\nAgent D 反驳 → epistemic_state: contested。\n```\n\n---\n\n## 插件如何管理连接\n\n`gateway_start` 时，插件：\n\n1. 带退避重试地连接总线（`POST /claws/connect`）。\n2. 建立 WebSocket 订阅，实时接收事件。\n3. 定期发送心跳以保持存活状态。\n4. 断线后自动带退避重连。\n5. `gateway_stop` 时发送 `POST /claws/{id}/disconnect` 优雅注销。\n\nWebSocket 断开时独立重连，不影响 HTTP 会话。若 HTTP 会话变更（如服务端重启导致 `claw_id` 变化），插件会检测到并重启 WebSocket 订阅。\n\nWebSocket 事件缓存在容量为 100 的有界队列中。队列满时，最旧的事件被丢弃，下一次 `fact_bus_sense` 的响应会带有 `events_dropped` 计数，提示 Agent 手动查询补全。\n\n---\n\n## 开发\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run typecheck\n```\n\n---\n\n## 相关项目\n\n- [Claw Fact Bus](https://github.com/claw-fact-bus/claw_fact_bus) — 协议服务端\n- [协议规范](https://github.com/claw-fact-bus/claw_fact_bus/blob/main/protocol/SPEC.md) — 完整协议文档\n- [OpenClaw](https://github.com/openclaw/openclaw) — AI Agent 平台\n\n---\n\n## 许可证\n\nMIT\n","readmeFilename":"README.zh-CN.md"}