{"id":"0bede2b0-cdcb-4553-8819-4e907dbabb33","entityType":"agent","slug":"clawhub-liuboacean-agent-comm-hub","name":"agent-comm-hub","canonicalUrl":"https://www.xpersona.co/agent/clawhub-liuboacean-agent-comm-hub","canonicalPath":"/agent/clawhub-liuboacean-agent-comm-hub","generatedAt":"2026-10-10T03:01:43.094Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T05:46:00.986Z","emptyReason":null},"description":"本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板 Skill: agent-comm-hub Owner: liuboacean Summary: 本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板 Tags: 2.4.0:2.4.0, 2.4.1:2.4.1, agent:3.0.19, agent-comm:3.0.20, agent-comm-hub:3.0.25, ai-agents:1.0.0, audit-log:3.0.22, backup:3.0.25, communication:3.0.25, evolution:2.2.1, heartbeat:3.0.22, hermes:1.0.0, hub:3.0.25, infrastructure:3.0.20, latest:3.0.25, mcp:3.0.25, memory:3.0.25, mess","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 4.3K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s1779brgcyhkdmz9tgjpwarx3h84vb82:agent-comm-hub","sourceUrl":"https://clawhub.ai/liuboacean/agent-comm-hub","homepage":"https://clawhub.ai/liuboacean/skills/agent-comm-hub","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/liuboacean/agent-comm-hub","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/liuboacean/skills/agent-comm-hub","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":73,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板 Skill: agent-comm-hub Owner: liuboacean Summary: 本地多智能体通信 Hub（MCP stdio / HTTP-"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:46:00.986Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:46:00.986Z","emptyReason":null},"stars":null,"forks":null,"downloads":4253,"packageName":null,"latestVersion":"3.0.25","tractionLabel":"4.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:46:00.986Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T05:46:00.986Z","lastCrawledAt":"2026-10-09T05:46:00.986Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T05:46:00.986Z","lastVerifiedAt":null,"highlights":[{"version":"3.0.25","createdAt":"2026-09-30T01:39:20.314Z","changelog":"v3.0.25 同步发布：修复 strategies/memories FTS 重建逻辑（先 DELETE 再全量 INSERT，根治 constraint failed 与索引漂移）；新增 SQLite quick_check 结构完整性 + FTS 漂移看门狗探针（scripts/cron_db_watchdog.sh，仅告警不重启）；新增凭据泄露扫描/脱敏/轮换三件套（scripts/scan|redact|rotate_leaked_credentials.py）。","fileCount":197,"zipByteSize":592279},{"version":"3.0.24","createdAt":"2026-08-17T21:44:22.463Z","changelog":"**3.0.24 is a major restructuring and distribution update.** - Migrated codebase structure: moved built sources to a new `dist/` directory and removed unneeded legacy files. - Removed deployment and monitoring scripts/configs from the main package. - Updated and streamlined documentation files (README.md, SKILL.md), reflecting the new structure and usage. - Updated build configuration and dependencies in `package.json`. - Introduced type declaration files and separated `.ts` and `.js` artifacts for clearer integration and SDK use. - Cleaned up and consolidated source code, removing outdated, duplicate, or unused modules.","fileCount":172,"zipByteSize":438084},{"version":"3.0.22","createdAt":"2026-07-23T05:19:25.064Z","changelog":"v3.0.22: 在线状态纳入 SSE 实时连接（派单/查询/指标统一判定，心跳监控不再误杀 SSE 在线 Agent）；audit_log 行数上限自动镜像归档（WORM 安全）+ 维护调度器；backup.ts 改用稳定路径 ~/agent-comm-hub/backups","fileCount":183,"zipByteSize":537678},{"version":"3.0.21","createdAt":"2026-07-23T03:14:58.168Z","changelog":"v3.0.21 P1 加固: SSE 重连竞态(connId 防误删实时连接); db busy_timeout=5000+事务(杜绝并发写静默丢数据); 认证前置限流+/mcp 在途上限(防令牌爆破/资源耗尽); FTS 按 memory_id 精确关联(消除内容相同记忆串台). P2: revoke_token 审计 target 归因; token 仅 Bearer; metrics Map 修复; 移除 dead code; 文档修正. 全量单测 280 通过.","fileCount":181,"zipByteSize":532529},{"version":"3.0.20","createdAt":"2026-07-23T01:20:57.349Z","changelog":"v3.0.20: 提交重新编译的 dist（含 P0 加固：SSE 可靠投递/激活态持久化/令牌防泄漏/对象级鉴权/ID 解析收敛）；修复启动期缺失 dist/package.json 导致崩溃的问题；版本号同步至 3.0.20","fileCount":180,"zipByteSize":523159},{"version":"3.0.19","createdAt":"2026-07-21T00:41:14.941Z","changelog":"v3.0.19 P0 工程加固：SSE 可靠投递(event_log+全局seq+Last-Event-ID 重放)、激活态持久化、令牌仅 Bearer 防泄漏、激活对象级鉴权、agent_id 精确解析(防消息错投 IDOR)；文档与版本号全链路统一至 3.0.19，MCP 工具数统一 58。","fileCount":19,"zipByteSize":78699},{"version":"3.0.18","createdAt":"2026-07-10T05:04:55.752Z","changelog":"Version 3.0.18 - Updated version number to 3.0.18 in SKILL.md and package.json. - Removed the explicit permissions block from SKILL.md for simpler configuration. - Minor clarifications in configuration and documentation. - No functional or interface changes to the skill itself.","fileCount":132,"zipByteSize":286945},{"version":"3.0.17","createdAt":"2026-07-10T04:25:27.815Z","changelog":"- Internal structure cleanup: removed legacy client-SDK, test, and doc files for a leaner codebase. - New `version.ts` module added to centralize version management. - Updated build outputs and imports to reflect new version management logic. - Documentation updated for version 3.0.17. - No changes to user-facing features or APIs.","fileCount":132,"zipByteSize":287427}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1779brgcyhkdmz9tgjpwarx3h84vb82:agent-comm-hub","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T03:01:43.090Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-liuboacean-agent-comm-hub/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T05:46:00.986Z","emptyReason":null},"readme":"Skill: agent-comm-hub\n\nOwner: liuboacean\n\nSummary: 本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板\n\nTags: 2.4.0:2.4.0, 2.4.1:2.4.1, agent:3.0.19, agent-comm:3.0.20, agent-comm-hub:3.0.25, ai-agents:1.0.0, audit-log:3.0.22, backup:3.0.25, communication:3.0.25, evolution:2.2.1, heartbeat:3.0.22, hermes:1.0.0, hub:3.0.25, infrastructure:3.0.20, latest:3.0.25, mcp:3.0.25, memory:3.0.25, message-bus:3.0.2, multi-agent:3.0.25, python-sdk:2.2.1, rbac:3.0.25, realtime:3.0.22, security:3.0.25, sqlite:3.0.25, sse:3.0.25, task-orchestration:3.0.25, task-scheduling:3.0.2, typescript-sdk:2.2.1, workbuddy:1.0.0\n\nVersion history:\n\nv3.0.25 | 2026-09-30T01:39:20.314Z | user\n\nv3.0.25 同步发布：修复 strategies/memories FTS 重建逻辑（先 DELETE 再全量 INSERT，根治 constraint failed 与索引漂移）；新增 SQLite quick_check 结构完整性 + FTS 漂移看门狗探针（scripts/cron_db_watchdog.sh，仅告警不重启）；新增凭据泄露扫描/脱敏/轮换三件套（scripts/scan|redact|rotate_leaked_credentials.py）。\n\nv3.0.24 | 2026-08-17T21:44:22.463Z | auto\n\n**3.0.24 is a major restructuring and distribution update.**\n\n- Migrated codebase structure: moved built sources to a new `dist/` directory and removed unneeded legacy files.\n- Removed deployment and monitoring scripts/configs from the main package.\n- Updated and streamlined documentation files (README.md, SKILL.md), reflecting the new structure and usage.\n- Updated build configuration and dependencies in `package.json`.\n- Introduced type declaration files and separated `.ts` and `.js` artifacts for clearer integration and SDK use.\n- Cleaned up and consolidated source code, removing outdated, duplicate, or unused modules.\n\nv3.0.22 | 2026-07-23T05:19:25.064Z | user\n\nv3.0.22: 在线状态纳入 SSE 实时连接（派单/查询/指标统一判定，心跳监控不再误杀 SSE 在线 Agent）；audit_log 行数上限自动镜像归档（WORM 安全）+ 维护调度器；backup.ts 改用稳定路径 ~/agent-comm-hub/backups\n\nv3.0.21 | 2026-07-23T03:14:58.168Z | user\n\nv3.0.21 P1 加固: SSE 重连竞态(connId 防误删实时连接); db busy_timeout=5000+事务(杜绝并发写静默丢数据); 认证前置限流+/mcp 在途上限(防令牌爆破/资源耗尽); FTS 按 memory_id 精确关联(消除内容相同记忆串台). P2: revoke_token 审计 target 归因; token 仅 Bearer; metrics Map 修复; 移除 dead code; 文档修正. 全量单测 280 通过.\n\nv3.0.20 | 2026-07-23T01:20:57.349Z | user\n\nv3.0.20: 提交重新编译的 dist（含 P0 加固：SSE 可靠投递/激活态持久化/令牌防泄漏/对象级鉴权/ID 解析收敛）；修复启动期缺失 dist/package.json 导致崩溃的问题；版本号同步至 3.0.20\n\nv3.0.19 | 2026-07-21T00:41:14.941Z | user\n\nv3.0.19 P0 工程加固：SSE 可靠投递(event_log+全局seq+Last-Event-ID 重放)、激活态持久化、令牌仅 Bearer 防泄漏、激活对象级鉴权、agent_id 精确解析(防消息错投 IDOR)；文档与版本号全链路统一至 3.0.19，MCP 工具数统一 58。\n\nv3.0.18 | 2026-07-10T05:04:55.752Z | auto\n\nVersion 3.0.18\n\n- Updated version number to 3.0.18 in SKILL.md and package.json.\n- Removed the explicit permissions block from SKILL.md for simpler configuration.\n- Minor clarifications in configuration and documentation.\n- No functional or interface changes to the skill itself.\n\nv3.0.17 | 2026-07-10T04:25:27.815Z | auto\n\n- Internal structure cleanup: removed legacy client-SDK, test, and doc files for a leaner codebase.\n- New `version.ts` module added to centralize version management.\n- Updated build outputs and imports to reflect new version management logic.\n- Documentation updated for version 3.0.17.\n- No changes to user-facing features or APIs.\n\nv3.0.16 | 2026-07-10T01:42:15.857Z | auto\n\n- Updated trigger keywords for improved flexibility and better CLI/API compatibility.\n- Bumped version to 3.0.16 in documentation and manifests.\n- Minor edits and typo fixes in documentation (SKILL.md), including clearer protocol and tool index descriptions.\n- No core logic changes to message, memory, identity, or orchestrator modules.\n- Updated package.json reflecting the new version.\n\nv3.0.15 | 2026-07-10T01:11:17.263Z | auto\n\nagent-comm-hub v3.0.15\n\n- Various updates across security, error handling, server logic, and MCP tool implementations.\n- Notable file changes to errors, security, server, and tool modules, codebase and type declarations updated.\n- Documentation (SKILL.md) now reflects version 3.0.15 and recent changes.\n- package.json updated to match the new release version.\n\nv3.0.14 | 2026-07-10T00:12:38.202Z | auto\n\n- 版本号升级为 3.0.14，SKILL.md 文档内版本信息同步更新\n- 其他功能和接口保持不变，无新增或删除的能力\n- 本次为文档维护/元数据修正版本，无业务逻辑改动\n\nv3.0.13 | 2026-07-10T00:04:26.967Z | auto\n\n**Major update: Authentication and security overhaul, env upgrades, and system cleanup.**\n\n- Replaced `HUB_KEY` with `HUB_AUTH_TOKEN` as required authentication for all stdio/REST clients; related environment variables and validation updated.\n- Expanded environment configuration, clarifying required and optional variables for setup and deployment.\n- Added skill permissions and network/filesystem binding metadata for standardized access control.\n- Removed legacy docs (`CHANGELOG.md`, `SECURITY.md`, `skill-card.md`, etc.) and reorganized local resource documentation.\n- SKILL.md now includes a quickstart workflow, explicit user confirmation checkpoints for risk operations, and updated tool descriptions.\n- General project cleanup, re-documentation, and improved onboarding flow for new agent users.\n\nv3.0.12 | 2026-07-09T08:18:17.933Z | user\n\nv3.0.12: 同步完整可运行代码（dist/src 63 文件 + src TS 源码）至 ClawHub。包含 v2.5.1 全部修复：get_db_stats ESM require 报错修复、DB 路径空库自动回退、锁定 Node 22 以匹配 better-sqlite3 原生模块、stdio/Hub Node 22 防护测试、159 单测全绿。补齐 CHANGELOG/CONTRIBUTING/HERMES-SETUP/SECURITY 文档。\n\nv3.0.10 | 2026-05-26T08:36:20.479Z | user\n\ndocs: README updates — WebSocket badge, SECURITY.md link, CHANGELOG link, 140 tests badge, project structure updated\n\nv3.0.9 | 2026-05-26T08:11:42.363Z | user\n\nFix: FTS5 JOIN NULL handling in recallMemory, remove hardcoded WorkBuddy path, reduce as any 58→45, 26 new unit tests, WebSocket transport, CHANGELOG added, metrics O(1), stdio structured logger\n\nv3.0.8 | 2026-05-26T08:08:44.685Z | user\n\nFix: FTS5 JOIN NULL handling in recallMemory, remove hardcoded WorkBuddy path, reduce as any 58→45, 26 new unit tests, WebSocket transport, CHANGELOG added, metrics O(1), stdio structured logger\n\nv3.0.7 | 2026-05-19T08:38:22.237Z | user\n\nAdd ClawScan publisher note for security review context\n\nv3.0.6 | 2026-05-19T08:36:56.117Z | user\n\nAdd ClawScan publisher note to clarify design intent for multi-agent communication\n\nv3.0.5 | 2026-05-16T06:20:44.943Z | user\n\nadd clawscan-note to explain design intent for security audit findings\n\nv3.0.3 | 2026-05-16T03:10:06.170Z | user\n\ndocs: fix final 56→53 in API reference doc link\n\nv3.0.2 | 2026-05-16T03:02:46.860Z | user\n\n统一工具数为53; 英文版新增High Availability行; SKILL.md版本号同步为2.5.5\n\nv3.0.1 | 2026-05-16T03:00:31.102Z | user\n\n统一工具数为53（6+5+8+5+8+12+4+3+2）; 英文版新增High Availability行; SKILL.md版本号同步为2.5.5\n\nv3.0.0 | 2026-05-15T06:29:26.815Z | auto\n\nNo file changes detected for this version.\n\n- No updates or modifications in code or documentation.\n- Version number updated to 3.0.0, but content remains unchanged.\n\nv2.6.0 | 2026-05-15T06:28:19.949Z | auto\n\nNo file changes detected in this release.\n\n- Version number updated to 2.6.0.\n- No feature additions, bug fixes, or documentation changes compared to 2.5.5.\n\nv2.5.6 | 2026-05-15T06:26:13.521Z | auto\n\nNo changes detected in this version.\n\n- Version number updated to 2.5.6, but no file or documentation changes were recorded.\n- No new features, bug fixes, or updates introduced.\n\nv2.5.5 | 2026-05-15T06:24:22.084Z | auto\n\n**Summary: This release adds official client SDKs, documentation improvements, new triggers, and a concise Getting Started guide.**\n\n- Added `client-sdk` directory with TypeScript, JavaScript, and Python SDKs for quick integration.\n- Introduced `HERMES-SETUP.md` and expanded `/docs` with advanced orchestration and safety guides.\n- New deployment and monitoring scripts: Docker Compose, Grafana, and Prometheus configurations.\n- README and SKILL.md now include a step-by-step 5-minute Quick Start, user confirmation checkpoints, and resource index.\n- Expanded triggers in SKILL.md to improve discoverability (`hub`, `agent-comm-hub`, `通信`, etc.).\n- Removed unused files (e.g., `stdio.js`); internal cleanup and minor bugfixes.\n\nv2.3.0 | 2026-05-15T06:15:46.351Z | auto\n\nAgent-Comm-Hub v2.3.0 introduces a comprehensive multi-agent communication and collaboration platform.\n\n- Adds real-time two-way messaging, task scheduling, shared memory, and collaborative evolution for multiple AI agents, based on MCP protocol and SSE push (<50ms latency, zero message loss).\n- Provides 51 structured MCP tools across identity, messaging, task, memory, evolution engine, orchestration, and token management, with 4-level permission control.\n- Features a clear permission and trust score system, fully documented APIs, task state machine, and SSE-based real-time event notifications with reconnect support.\n- Offers zero-dependency Python and TypeScript SDKs, built-in CLI automation scripts, and detailed guides/examples for quick integration with WorkBuddy, Hermes, QClaw, and any MCP-compatible agent.\n- Fully self-contained, requires no external dependencies; deployable via simple shell scripts.\n\nv2.5.4 | 2026-05-07T05:05:58.837Z | user\n\nFix: weaken Memory scope descriptions in README, tone down tool descriptions in SKILL.md\n\nv2.5.3 | 2026-05-07T05:00:15.034Z | user\n\nSync v2.4.5 updates: LICENSE, README, Docker, CONTRIBUTING, demo\n\nv2.5.2 | 2026-05-04T13:01:47.555Z | user\n\nInclude server code (src/*.js + package.json) in package, weaken tool descriptions, restrict permissions in docs\n\nv2.5.1 | 2026-05-04T12:32:12.961Z | user\n\nAbstracted server entry point path, declared HUB_KEY in metadata, further desensitized descriptions\n\nv2.5.0 | 2026-05-04T12:25:31.259Z | user\n\nSecurity boundary descriptions, per-agent isolation docs, memory tool desensitization, removed external repository references\n\nv2.4.9 | 2026-05-04T11:51:16.354Z | auto\n\n**v2.4.9 brings documentation and usage refinements for agent-comm-hub.**\n\n- Refined SKILL.md to clarify toolset definitions and access configuration, focusing on stdio模式优先。\n- Streamlined protocol description, removing REST API information and emphasizing MCP stdio/JSON-RPC + SSE only.\n- Updated tool categories: \"记忆\" now documented as \"上下文暂存\", with revised descriptions for context-related utilities.\n- Added clearer guidance for file structure, permission levels, and entrypoint usage (server/SDK), referencing the public GitHub repository.\n- Miscellaneous documentation cleanups, permission clarifications, and improved quickstart instructions.\n\nv2.4.8 | 2026-05-04T10:47:41.259Z | auto\n\n**Changelog for agent-comm-hub v2.4.8**\n\n- Refreshed and streamlined descriptions in SKILL.md to clarify capabilities and terminology.\n- Updated feature names and explanations for accuracy: “进化” now described as “经验积累”, and “策略” as “建议/经验”；任务模块统一为“任务协同”。\n- Synced versioning and capability lists from v2.4.5 to v2.4.8, reflecting the current set of 53 MCP tools and modernized permission model wording.\n- Removed outdated role and reputation scoring details; replaced with concise trust and permission descriptions.\n- Enhanced file structure and “快速开始” instructions for improved onboarding.\n- Minor terminology and wording alignments to match actual implementation and simplify user understanding.\n\nv2.4.7 | 2026-05-04T04:42:21.281Z | auto\n\n## agent-comm-hub v2.4.7\n\n- Updated documentation in SKILL.md and README.md.\n- File tool names in documentation were revised: `upload_file`/`download_file` are now described as `send_file`/`receive_file`.\n- No functional or code changes, only documentation improvements.\n\nv2.4.6 | 2026-05-04T04:34:03.424Z | auto\n\n- Updated description and documentation for clarity, simplifying terminology and usage scenarios.\n- Adjusted some module and variable names (如角色控制、密钥变量) for better readability and accuracy.\n- Refined SDK 接入与配置说明，反映最新推荐的环境变量命名。\n- Streamlined MCP 工具和运维工具的说明，精简能力列表条目，减少冗余。\n- 文档主版本号调整为 2.4.5，细节描述同步更新。\n\nv2.4.5 | 2026-05-04T03:45:11.718Z | auto\n\n- Major cleanup: Removed 18 internal, build, integration, and documentation files for a streamlined distribution.\n- Updated and shortened SKILL.md with revised terminology (e.g., “消息路由” for message routing, “任务编排” for task orchestration).\n- Documentation now highlights only core architecture, capabilities, usage, and structure—removing all in-depth developer, API, and troubleshooting docs.\n- File structure, tool/endpoint names, and key environment variable descriptions are clarified for consistency.\n\nv2.4.3 | 2026-05-04T02:13:53.784Z | user\n\nv2.4.3: 调整 SKILL.md 描述降低安全扫描误报，软化通信相关描述\n\nv2.4.2 | 2026-05-04T01:23:20.563Z | user\n\nv2.4.2: 移除测试文件，新增安全说明章节，明确鉴权/人工确认/数据安全最佳实践\n\nv2.4.1 | 2026-05-04T00:31:00.787Z | user\n\nv2.4.1: 完整版发布，含源码、53个MCP工具、100单元测试、CI/CD、模块化重构\n\nv2.4.0 | 2026-05-04T00:22:20.170Z | user\n\nv2.4.0: 模块化重构，53个MCP工具，类型安全\n\nv2.2.2 | 2026-04-28T02:40:42.031Z | auto\n\n- Added new CHANGELOG.md file.\n- Increased MCP工具 count from 44 to 46: `delete_memory` now listed in Memory 记忆工具, raising memory tools from 4 to 5.\n- Documentation updates across README.md, SKILL.md, and multiple guide/reference files to reflect new/updated capabilities.\n- Minor SDK (Python/TypeScript) and installer script updates for tooling and compatibility.\n- Updated file and tool listings to keep documentation accurate and in sync with implementation.\n\nv2.2.1 | 2026-04-27T14:32:33.873Z | user\n\nv2.2.1: 添加 README.md + tagline「共享记忆，共同进化」\n\nv2.2.0 | 2026-04-27T13:31:00.295Z | user\n\nv2.2.0: 轻量化改造（方案A胶水层），44个MCP工具/4级RBAC/信任评分/进化引擎/零依赖Python SDK/一键安装脚本\n\nv1.0.0 | 2026-04-17T07:22:53.575Z | user\n\nInitial release: MCP+SSE multi-agent communication & task scheduling hub with WorkBuddy and Hermes integration\n\nArchive index:\n\nArchive v3.0.25: 197 files, 592279 bytes\n\nFiles: CHANGELOG.md (7508b), client-sdk/adapters/host-executor.ts (7420b), client-sdk/adapters/host-task-bridge.ts (5340b), client-sdk/agent-client.d.ts (11889b), client-sdk/agent-client.ts (36428b), client-sdk/backoff.ts (938b), client-sdk/hermes-integration.d.ts (785b), client-sdk/hermes-integration.ts (5337b), client-sdk/hub_client.py (52007b), client-sdk/package.json (710b), client-sdk/pyproject.toml (1088b), client-sdk/README_PYPI.md (1682b), client-sdk/runtime.ts (9323b), client-sdk/types.ts (1703b), client-sdk/workbuddy-integration.d.ts (11b), client-sdk/workbuddy-integration.ts (6548b), CONTRIBUTING.md (3614b), demo/index.html (7669b), deploy/docker-compose.yml (2116b), deploy/grafana/dashboard.json (16770b), deploy/grafana/provisioning/dashboards/dashboards.yml (258b), deploy/grafana/provisioning/datasources/prometheus.yml (186b), deploy/prometheus.yml (408b), docs/adr/0001-sse-reliable-delivery.md (950b), docs/adr/0002-activation-state-persistence.md (1042b), docs/advanced-orchestration-guide.md (12047b), docs/API_REFERENCE.md (8966b), docs/design/ach-autonomous-loop-hitl-auth.md (31439b), docs/HOST_INTEGRATION.md (7399b), docs/hub-db-split-three-layer-protection.md (4450b), docs/index.md (837b), docs/README_EN.md (14289b), glama.json (93b), HERMES-SETUP.md (5618b), package-lock.json (141101b), package.json (1237b), README.md (22543b), scripts/check_db_consistency.sh (5011b), scripts/cron_db_watchdog.sh (4792b), scripts/hub_task_runner.py (6118b), scripts/hub_watcher.py (15775b), scripts/install.sh (581b), scripts/migrate_evolution_db.py (6682b), scripts/migrate_from_agent.js (2599b), scripts/redact_leaked_credentials.py (8009b), scripts/rotate_token.py (7202b), scripts/scan_leaked_credentials.py (7500b), scripts/start_hub_server.sh (1377b), scripts/test-e2e.d.ts (11b), scripts/test-e2e.js (5838b), scripts/test-e2e.sh (2258b), scripts/test-e2e.ts (5680b), scripts/wb_task_trigger.py (2220b), SECURITY.md (2328b), skill-card.md (1966b), SKILL.md (17915b), src/authorization.ts (8054b), src/backup.ts (5675b), src/db.d.ts (3783b), src/db.ts (52197b), src/dedup.d.ts (2467b), src/dedup.ts (9168b), src/errors.d.ts (1990b), src/errors.ts (3514b), src/evolution.d.ts (6751b), src/evolution.ts (34869b), src/identity.d.ts (3452b), src/identity.ts (20858b), src/logger.d.ts (1176b), src/logger.ts (3497b), src/memory.d.ts (2193b), src/memory.ts (15947b), src/metrics.d.ts (1885b), src/metrics.ts (10498b), src/orchestrator.d.ts (6291b), src/orchestrator.ts (44768b), src/ratelimit.ts (3751b), src/repo/event-log.d.ts (550b), src/repo/event-log.ts (2353b), src/repo/interfaces.d.ts (3687b)\n\nFile v3.0.25:SKILL.md\n\n---\nname: agent-comm-hub\ndescription: \"本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板\"\nversion: \"3.0.25\"\ncategory: autonomous-ai-agents\ntriggers:\n - \"agent-comm-hub\"\n - \"AgentCommHub\"\n - \"ACH\"\n - \"agent-comm\"\n - \"agent_comm_hub\"\n - \"通信hub\"\n - \"消息hub\"\n - \"workbuddy\"\n - \"QClaw\"\n - \"send_message\"\n - \"assign_task\"\n---\n\n# Agent Communication Hub\n\n> 多智能体消息转发与上下文共享中间件 — **v3.0.25**\n\n让两个或多个独立 AI 智能体之间实现**实时双向通信**和**上下文自动同步**。基于 MCP 协议 + stdio 模式，消息本地持久化，延迟 < 50ms。\n\n## 架构概览\n\n```\n┌──────────────┐ ┌──────────────────────────────┐ ┌──────────────┐\n│ Agent A │ SSE │ Agent Communication Hub │ SSE │ Agent B │\n│ (Hermes) │◄───────►│ (stdio) │◄───────►│ (WorkBuddy) │\n│ │ MCP │ │ MCP │ │\n└──────────────┘◄───────►│ SQLite WAL + 30 表 │◄───────►└──────────────┘\n │ 58 MCP 工具 + RBAC 权限 │\n │ 上下文暂存 + 建议闭环 │\n └──────────────┬──────────────┘\n │\n SQLite (WAL)\n```\n\n**三层协议**：\n\n| 层 | 协议 | 用途 | 延迟 |\n|----|------|------|------|\n| MCP 工具层 | stdio JSON-RPC | 结构化操作（发消息、分配任务、查状态） | <50ms |\n| SSE 推送层 | Server-Sent Events | 实时事件通知（新消息、新任务、建议确认） | <50ms |\n\n## 快速上手 (5 分钟)\n\n从零到完成第一次 Agent 间通信的编号流程：\n\n### Step 1: 确认 Hub 运行状态\n\n确认 Agent Communication Hub 服务器正在运行。如果通过 stdio 模式接入，检查 MCP 配置是否正确加载：\n\n```\n调用: get_online_agents()\n期望: 返回在线 Agent 列表（至少含自己）\n失败: Hub 未运行 → 先启动 Hub 服务器\n```\n\n**[检查点] 用户确认**：如果 Hub 未运行，询问用户是否要启动 Hub 服务器。\n\n### Step 2: 注册或确认身份\n\n检查自己是否已在 Hub 注册，如果没有则注册：\n\n```\n1. 调用: query_agents(status='all') → 查看所有 Agent\n2. 如果自己的 Agent ID 不在列表中\n → register_agent(invite_code, name, capabilities)\n3. 如果已注册 → 记下自己的 agent_id 供后续使用\n```\n\n**[检查点] 用户确认**：注册新 Agent 需要 invite_code，先问用户是否有可用的邀请码。\n\n### Step 3: 维持在线状态\n\n启动心跳维持在线，确保能接收实时消息推送：\n\n```\n调用: heartbeat(agent_id='你的ID')\n频率: 每 30 秒一次（超过 90 秒无心跳则自动标记为离线）\n```\n\n### Step 4: 检查未读消息\n\n上线后第一时间检查是否有离线期间缓存的消息：\n\n```\n1. 调用: search_messages(query='你的ID', limit=20)\n2. 筛选 status='unread' 的消息\n3. 按时间顺序处理，先 acknowledge_message 确认收到，再回复\n```\n\n**[检查点] 用户确认**：找到未读消息后，逐条向用户摘要汇报，请用户确认如何处理。\n\n### Step 5: 发送第一条消息\n\n向另一个 Agent 发送消息，验证双向通信：\n\n```\n调用: send_message(from='你的ID', to='目标AgentID', content='通信链路确认畅通')\n检查返回: delivered_realtime — true=对方在线, false=对方离线\n```\n\n**[检查点] 用户确认**：发送前向用户确认消息内容和目标 Agent。broadcast_message 必须逐条确认。\n\n### 完整闭环示例\n\n```\n场景：Hub 在线 → 检查 WorkBuddy 是否有未读消息 → 处理并回复\n\n1. get_online_agents() # 确认自己和对方在线\n2. search_messages(limit=10) # 查最近消息\n3. acknowledge_message(msg_id, agent_id) # 标记已读\n4. send_message(to='workbuddy', content='已收到，正在处理') # 回复\n5. mark_consumed(resource=msg_id, action='replied') # 消费水位线\n```\n\n## 核心能力\n\n### 58 个 MCP 工具（当前版本）\n\n#### Identity 身份 (6)\n\n| 工具 | 功能 |\n|------|------|\n| `register_agent` | 注册新 Agent，需提供 HUB_AUTH_TOKEN 认证 |\n| `heartbeat` | Agent 心跳上报，维持在线状态，每 3 次连续心跳记录 +1 |\n| `query_agents` | 查询 Agent 列表，支持状态/角色筛选 |\n| `get_online_agents` | 获取当前在线 Agent 列表 |\n\n#### Message 消息 (5)\n\n| 工具 | 功能 |\n|------|------|\n| `send_message` | Agent 间点对点消息，支持 Markdown，自动去重（sha256） |\n| `broadcast_message` | (需逐条确认后发送) |\n| `acknowledge_message` | 确认已读消息，防止重复出现 |\n| `search_messages` | 全文搜索消息历史 |\n| `batch_acknowledge_messages` | 批量确认消息（1-500 条/次），用于清理消息积压 |\n\n#### File 文件 (3)\n\n| 工具 | 功能 |\n|------|------|\n| `upload_file` | 发送文件附件（Base64，10MB 限制），关联到消息 |\n| `download_file` | 接收附件，返回 Base64 编码内容 |\n| `list_attachments` | 列出附件，支持按消息/Agent 筛选 |\n\n#### Task 任务 (3)\n\n| 工具 | 功能 |\n|------|------|\n| `assign_task` | 创建并分配任务，支持上下文传递 |\n| `update_task_status` | 更新任务状态（inbox→assigned→in_progress→completed/failed） |\n| `get_task_status` | 查询任务详情，含依赖、Pipeline、交接信息 |\n\n#### Context 上下文暂存 (5)\n\n| 工具 | 功能 |\n|------|------|\n| `store_memory` | 临时暂存当前任务参考信息 |\n| `recall_memory` | 检索已暂存的上下文 |\n| `list_memories` | 列出当前 Agent 的暂存条目 |\n| `delete_memory` | 删除暂存条目（仅 creator） |\n| `search_memories` | 检索当前 Agent 的暂存内容 |\n\n#### 经验记录\n\n经验记录和策略管理需特定权限配置。\n\n#### 任务协同\n\n| 工具 | 功能 |\n|------|------|\n| `add_dependency` | 添加任务依赖关系（依赖检查） |\n| `remove_dependency` | 删除任务依赖关系 |\n| `get_task_dependencies` | 查询任务上下游依赖 |\n| `create_parallel_group` | 创建并行任务组（2-10 个任务） |\n| `request_handoff` | 请求任务交接 |\n| `accept_handoff` | 接受任务交接 |\n| `reject_handoff` | 拒绝任务交接（含理由） |\n| `add_quality_gate` | 在 Pipeline 中添加质量门 |\n| `evaluate_quality_gate` | 评估质量门（passed/failed） |\n| `recalculate_trust_scores` | 按调度执行分数维护 |\n| `create_pipeline` | 创建 Pipeline 流水线 |\n| `get_pipeline` | 查询 Pipeline 详情 |\n| `list_pipelines` | 列出 Pipeline |\n| `add_task_to_pipeline` | 向 Pipeline 添加任务 |\n\n#### 运维工具 (4)\n\n| 工具 | 功能 |\n|------|------|\n| `get_db_stats` | 数据库统计信息（表行数、大小、Agent 数等） |\n| `archive_data` | 数据维护工具 |\n| （其余 2 个内部工具） | 权限验证与控制 |\n| （其余 2 个内部工具） | 权限验证与控制 |\n\n#### 消费水位线 (2)\n\n| 工具 | 功能 |\n|------|------|\n| `mark_consumed` | 标记任务/消息为已消费，防止重复处理 |\n| `check_consumed` | 查询资源是否已被消费 |\n\n> 所有工具内置 try-catch + 3 次指数退避重试（100ms → 200ms → 400ms）。v2.4.0 统一错误格式：`HubError` 错误码 + `mcpError()`/`mcpFail()` 标准返回。`check_consumed` 查询失败时降级返回 `consumed=false`（不阻塞业务）。\n\n### 任务状态机\n\n```\ninbox → assigned → [waiting] → in_progress → completed / failed / cancelled\n```\n\n## 用户确认检查点\n\n以下操作必须在执行前暂停，向用户摘要说明并等待确认：\n\n| # | 操作 | 检查点说明 | 风险 |\n|---|------|-----------|------|\n| 1 | **broadcast_message** | 广播消息会发送给多个 Agent，逐条确认内容和接收列表 | 高 |\n| 2 | **assign_task** | 分配任务前确认：描述是否清晰、目标 Agent 是否合适、Priority 正确 | 中 |\n| 3 | **batch_acknowledge_messages** | 批量确认会一次性标记多条消息为已处理，确认不会遗漏重要信息 | 中 |\n| 4 | **create_pipeline** | 创建流水线前确认任务顺序、质量门设置、参与 Agent | 中 |\n| 5 | **add_quality_gate** | 质量门失败会阻塞后续任务，确认评估标准合理 | 高 |\n| 6 | **request_handoff** | 交接任务前确认目标 Agent 有能力接手、理由充分 | 中 |\n| 7 | **archive_data** | 归档操作会移动数据到归档表，确认归档范围和天数 | 高 |\n| 8 | **store_memory(scope='group')** | 写入组内共享记忆前确认内容适当，不会泄露敏感信息 | 中 |\n| 9 | **propose_strategy** | 提议策略前确认内容准确、分类正确、有实际价值 | 低 |\n| 10 | **reject_handoff** | 拒绝交接需提供理由，确认不会导致任务阻塞 | 中 |\n\n> **规则**：LLM 遇到上表操作时，先向用户输出摘要说明，明确询问\"是否继续？\"，得到肯定答复后再执行。用户可随时跳过检查点。\n\n## 数据隔离与安全边界\n\n| 边界 | 实现方式 |\n|------|---------|\n| **接收方校验** | `send_message`/`assign_task` 中的 `to_agent` 必须为已注册 Agent，未注册 Agent 被拒绝 |\n| **Per-Agent 数据隔离** | 每个 Agent 仅可见自身消息、任务和暂存条目；跨 Agent 查询受 4 级权限控制 |\n| **暂存内容保护** | `store_memory` 创建的条目仅 creator 可检索和删除，不会自动暴露给其他 Agent |\n| **经验记录审批** | `share_experience` 提交的记录需经 `full` 权限确认后才对其他 Agent 可见 |\n\n## 接入配置（stdio 模式）\n\n在 MCP 配置文件中添加 Hub 为 stdio 服务器，提供 `HUB_AUTH_TOKEN` 环境变量进行认证。Hub 通过 stdio 传输 MCP 协议，Agent 的 LLM 可直接调用 Hub 工具。**stdio 模式必须设置 HUB_AUTH_TOKEN，缺失将拒绝启动。**\n\n```json\n{\n \"mcpServers\": {\n \"agent-comm-hub\": {\n \"command\": \"node\",\n \"args\": [\"/stdio.js\"],\n \"env\": {\n \"HUB_AUTH_TOKEN\": \"your-connection-key\"\n }\n }\n }\n}\n```\n\n## 资源索引\n\n此 skill 目录下已有 Hub 完整源码，可直接参考：\n\n### 本地源文件\n\n| 文件 | 用途 |\n|------|------|\n| `src/server.ts` | 服务端入口，Express + MCP/SSE 双通道 |\n| `src/tools.ts` | 全部 MCP 工具的 TypeScript 实现 |\n| `src/db.ts` | SQLite WAL 数据库初始化与连接 |\n| `src/identity.ts` | Agent 注册、认证、4 级权限控制 |\n| `src/dedup.ts` | SHA256 消息去重实现 |\n| `src/errors.ts` | HubError 统一错误码（v2.4.0+） |\n| `src/stdio.ts` | Stdio 模式传输层 |\n| `src/sse.ts` | SSE 推送通道 |\n| `src/orchestrator.ts` | 任务编排、Pipeline、质量门 |\n| `src/evolution.ts` | Evolution Engine：策略/经验/信任分 |\n| `src/memory.ts` | 上下文暂存与管理 |\n| `src/security.ts` | 安全验证、CORS、Token 管理 |\n| `src/metrics.ts` | 统计指标收集 |\n| `src/repo/` | 数据访问层（repository pattern） |\n| `package.json` | Node.js 依赖与版本定义 |\n\n### 参考链接\n\n- GitHub 仓库: https://github.com/liuboacean/agent-comm-hub\n- MCP 协议规范: https://spec.modelcontextprotocol.io\n\n## 权限说明（4 级）\n\n| 级别 | 说明 | 可用工具范围 |\n|------|------|----------|\n| **authenticated** | 已认证（HUB_AUTH_TOKEN） | register_agent（初始注册） |\n| **member** | 已注册 Agent | 消息 `send_message`/`acknowledge_message` + 任务 `assign_task`/`get_task_status` |\n| **group_manager** | 并行组管理 | 任务协同 + Pipeline 工具（不含暂存/经验） |\n| **full** | 完整权限 | 全部工具（含运维与建议管理） |\n\n> 部分管理类工具仅特定权限可调用，具体以实际角色配置为准。\n\n> 初始分数 50，公式：`base(50) + verified_capabilities*3 + approved_strategies*2 + positive_feedback*1 - negative_feedback*2`，clamp(0,100)。\n\n## 版本历史\n\n### v3.0.24 — 宿主执行器闭环收口（HostExecutor 注入）\n| 类别 | 内容 | 说明 |\n|------|------|------|\n| 宿主执行 | HostExecutor 契约 + 参考实现 | 新增 `client-sdk/adapters/host-executor.ts`（`LlmHostExecutor` / `HttpHostExecutor` / `defaultHostExecutor()`）；`AbstractHostTaskBridge` 可注入 `executor` |\n| 闭环 | 消灭 setTimeout 占位 | WorkBuddy / Hermes 桥 `runTask()` 委托 `this.executor.execute()`，任务到达即触发宿主真实能力 |\n\n### v3.0.25 — 跨进程 SSE 桥接 + watcher 实时解析修复\n| 类别 | 内容 | 说明 |\n|------|------|------|\n| 推送 | 跨进程 SSE 桥接（方案 B） | `pushToAgent` 在当前进程无目标 SSE 连接且配置 `SSE_BRIDGE_URL` 时，转发事件至桥接进程 `/internal/sse/push`，打通 stdio MCP 派单进程 → HTTP SSE 服务进程的实时送达 |\n| 服务端 | 桥接接收端点 | `server.ts` 新增 `POST /internal/sse/push`（鉴权保护），由持有 SSE 连接的进程本地投递 |\n| 客户端(watcher) | SSE 实时解析修复 | `hub_watcher.py` 由 `resp.read(4096)` 缓冲读改为逐行 `readline()`，消除低吞吐 SSE 流缓冲阻塞；修正事件分发（`payload.event` 取真实类型）与受保护 REST API 的 Bearer 鉴权头 |\n| 效果 | 派单→自动执行闭环 | 接收方持有 SSE 长连接（如 WorkBuddy 本地 watcher）即可实时收到 `task_assigned` 并触发宿主自动化执行 |\n\n### v3.0.x（安全加固）\n| 类别 | 内容 | 说明 |\n|------|------|------|\n| 权限模型 | fail-closed 权限矩阵 | `checkPermission` 未注册工具默认拒绝；`TOOL_PERMISSIONS` 全量登记，杜绝 fail-open |\n| 认证 | stdio 强制认证 | 缺失 `HUB_AUTH_TOKEN` 直接 `process.exit(1)`，移除 glama-ci admin 兜底 |\n| 角色护栏 | admin 校验 | 9 个 admin 类工具 handler 首行 `requireAdmin(ctx)` |\n| HTTP 中间件 | 分级放行 | `/health`、`/metrics` 仅内网/loopback 或 token 放行；`/dashboard`、`/api/*` 需 token + admin |\n| 审计 | WORM 不可篡改 | 审计日志仅归档不删源，保留 `no_delete` / `no_modify` 触发器 |\n| 数据归属 | 域隔离 | `search_messages` 强制本人收发域；记忆统计按 agent 隔离，admin 才指定他人 |\n| 对象级授权 | assertOwns 中间件 | message/attachment/task 三族工具插入 `assertOwns()` 归属校验（HUB_2004）；`/health` 收敛（删除内网 IP/路径泄露） |\n| sender 校验 | send_message 身份守卫 | broadcast_message + send_message 均强制 `from === ctx.agentId`，杜绝身份伪造 |\n| memory 降级 | search_memories 补 agent_id 过滤 | FTS5 离线回退 SQL 增加 `agent_id = ?`，防止越权泄漏 |\n| 内部函数 | setAgentRole/updateAgentTrustScore 加 admin 校验 | 底层函数不再信任 `operatorId`，显式查库验证 admin 身份 |\n| SQL 修复 | registerCapability 占位符 | 6→7 个占位符匹配实际 7 个字段值，修复运行时崩溃 |\n| triggers 收窄 | SKILL.md 触发词 | 移除 `Hub`/`通信`/`消息` 过宽泛触发词，改用具体标识\n\n### v2.4.0\n| Phase | 内容 | 变更 |\n|-------|------|------|\n| **A** | tools.ts 拆分 | 2687 行 → 8 模块 + 30 行入口 + utils.ts |\n| **B** | 单元测试 | 100 用例，role-control >= 70% / dedup branches>=60, functions>=70 / utils 100% |\n| **C** | CI/CD | GitHub Actions：typecheck + test + coverage 3 Jobs |\n| **D** | 类型健壮 | any 归零 + HubError 统一错误码 + MCP 返回格式标准化 |\n\n## 踩坑经验速查\n\n| # | 场景 | 要点 |\n|---|------|------|\n| 1 | MCP 多 Client | 必须用 Stateless 模式，Stateful 只允许一个 Client |\n| 2 | MCP Accept Header | 必须带 `Accept: application/json, text/event-stream` |\n| 3 | MCP 响应格式 | SDK 返回 SSE 格式（`data: {...}`），不是纯 JSON |\n| 4 | ESM 兼容 | 不能用 `require()`，用 `import()` 动态导入 |\n| 5 | UTF-8 块读取 | httpx `resp.read(1)` 会截断多字节字符，用 `read(4096)` |\n| 6 | SSE 心跳 | 10 秒间隔，服务端发 `: ping` |\n| 7 | MCP != SSE | MCP 是工具调用通道（Agent→Hub），SSE 是推送通道（Hub→Agent） |\n| 8 | 离线补发 | 消息/任务存 SQLite，上线后 SSE 自动批量推送 |\n| 9 | stdio 模式 | 所有日志走 stderr，stdout 保留给 JSON-RPC |\n| 10 | better-sqlite3 boolean | 绑定参数必须用 1/0，不能用 true/false |\n| 11 | HubError 错误码 | v2.4.0 统一用 mcpError()/mcpFail()，不要手动构造错误响应 |\n\n## 安全配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `HUB_AUTH_TOKEN` | stdio / REST 模式认证 Token，所有 Agent 接入必须提供，用于身份认证与消息完整性校验 |\n| 4 级权限模型 | authenticated → member → group_manager → full，逐级授权 |\n| CORS 白名单 | 默认拒绝跨域，通过 `CORS_LIST` 显式配置允许的来源 |\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `HUB_AUTH_TOKEN` | — | stdio / REST 认证 Token（必填） |\n| `DB_PATH` | ./comm_hub.db | SQLite 数据库路径 |\n| `LOG_LEVEL` | info | 日志级别：debug / info / warn / error |\n| `CORS_LIST` | (空) | CORS 白名单（逗号分隔），空=拒绝所有跨域 |\n\n## 技术依赖\n\n**Hub 服务器**：\n- Node.js 18+\n- @modelcontextprotocol/sdk ^1.10.2（支持 StdioServerTransport）\n- express ^4.19\n- better-sqlite3 ^11.9\n- zod ^3.23\n\n**Python 客户端（零外部依赖）**：\n- Python 3.9+（纯标准库：http.client / json / asyncio）\n\nFile v3.0.25:README.md\n\n

\n \n \n \"Node.js\n \n \"Python\n \"MCP\n \"288\n \"Zero\n \"Web\n \n \"CI\"\n \n \"MIT\n \n \"PyPI\"\n \n \n \"npm\"\n \n \n \"Glama\n \n \n \"Available\n \n

\n\n

\n 🤖 Agent Communication Hub\n

\n

\n 让 AI Agent 不再各自为战
\n 实时消息 · 任务调度 · 共享记忆 · 信任进化 · Web 仪表盘
\n 58 个 MCP 工具 · 零外部服务 · 5 分钟部署\n

\n\n

\n 中文 · English\n · GitHub\n

\n\n
\n\n---\n\n## 👀 一眼看明白\n\n```mermaid\ngraph LR\n A[Claude Code] <--> H((ACH Hub))\n B[WorkBuddy] <--> H\n C[OpenClaw] <--> H\n D[自定义 Agent] <--> H\n H --> DB[(SQLite)]\n H --> Web[Web 仪表盘]\n style H fill:#4f46e5,color:#fff\n style Web fill:#7c3aed,color:#fff\n```\n\n**任何 MCP 兼容的 AI Agent** → 连接 Hub → 立即获得：消息总线、任务队列、共享记忆、进化引擎。\n\n> 🚀 **5 分钟启动**：`docker run -d -p 3100:3100 ghcr.io/liuboacean/agent-comm-hub`\n\n---\n\n## 💡 为什么需要它？\n\n多个 AI Agent（Claude Code、WorkBuddy、OpenClaw、Hermes 等）天然是**信息孤岛**：\n\n| 问题 | 传统方案 | 为什么不行 |\n|------|---------|-----------|\n| ❌ Agent 间无法通信 | Webhook / 共享文件 | 脆弱、不可靠、手动维护 |\n| ❌ 无法跨 Agent 调度任务 | 各自为战 | 没人协调，任务丢失 |\n| ❌ 无法共享上下文 | 每轮对话都从零开始 | 记不住团队经验 |\n| ❌ 无法团队进化 | 每个 Agent 独自踩坑 | 同样的问题反复修 |\n\n**Agent Communication Hub（ACH）** 是它们的**共享神经中枢**——一条消息总线 + 任务调度器 + 团队记忆库 + 经验进化引擎。\n\n---\n\n## 🚀 三步上手\n\n```bash\n# 0. 安装 Python SDK（可选）\npip install agent-comm-hub\n\n# 1. 启动 Hub（一行命令）\ndocker run -d -p 3100:3100 --name ach ghcr.io/liuboacean/agent-comm-hub\n\n# 2. 注册 Agent\npython3 -c \"\nfrom hub_client import SynergyHubClient\nhub = SynergyHubClient('http://localhost:3100')\nresult = hub.register(invite_code='INVITE-001', name='my-agent')\nhub.set_token(result['api_token'])\nprint(f'✅ Agent 注册成功，ID: {result[\\\"agent_id\\\"]}')\n\"\n\n# 3. 发条消息试试\npython3 -c \"\nfrom hub_client import SynergyHubClient\nhub = SynergyHubClient('http://localhost:3100')\nhub.set_token('your-token')\nhub.send_message(to='other-agent', content='收到，任务完成。')\nprint('✅ 消息已发送')\n\"\n```\n\n> 🔗 然后打开 **http://localhost:3100/dashboard** 查看实时仪表盘\n\n---\n\n## ✨ 核心能力\n\n### 📊 数据快照\n\n| 指标 | 值 |\n|------|:--:|\n| MCP 工具 | **58 个** |\n| Python SDK 方法 | **68 个** |\n| TypeScript SDK 方法 | **35 个** |\n| 单元测试 | **288 个 ✅** |\n| 数据库表 | **32 张** |\n| client-sdk 运行时依赖 | **0（Python/TS 纯标准库）** |\n| 服务端运行时依赖 | **5 个轻量依赖**（express / better-sqlite3 / zod / eventsource / @modelcontextprotocol/sdk） |\n| 消息延迟 | **< 50ms** |\n| 部署方式 | Docker / npm / SkillHub |\n\n### 🧩 功能矩阵\n\n| 类别 | 工具 | 一句话 |\n|------|------|--------|\n| 🔐 **身份认证** | 6 | 注册 / 心跳 / RBAC / 信任评分 |\n| 💬 **消息通信** | 5 | P2P / 广播 / FTS5 搜索 / 去重 |\n| 📋 **任务调度** | 8 | 7 状态机 / Pipeline / 并行组 |\n| 🧠 **共享记忆** | 5 | 三级作用域（私密/团队/全局）|\n| 🔀 **编排协调** | 11 | 依赖链 / 质检门 / 任务交接 |\n| 📈 **进化引擎** | 12 | 经验共享 / 策略审批 / 信任闭环 |\n| 🛡️ **安全审计** | 6 | 哈希链审计 / 4 级 RBAC / CORS |\n| 📎 **文件传输** | 3 | 上传 / 下载 / 列表 |\n| 🔧 **高可用** | 3 | DB 分裂检测 / 自动合并 / 看门狗 |\n\n---\n\n## 🖥️ 内置 Web 管理面板\n\n启动 Hub 后打开 **http://localhost:3100/dashboard**，即可实时管理你的 Agent 集群：\n\n| 页面 | 能干什么 |\n|------|---------|\n| **总览仪表盘** | 一眼看清在线 Agent、Pipeline 状态、消息吞吐 |\n| **Agents** | 查看所有 Agent 列表（名称、角色、最后活跃时间、信任分）|\n| **消息吞吐** | 5 分钟消息量 + 被限流的 Agent Top |\n| **健康检查** | 版本 / 运行时间 / DB 状态 / 备份状态（本地 + 远程）|\n| **审计日志** | 全量操作追溯，谁在什么时候做了什么 |\n\n> 纯静态 HTML（零前端框架），内联 CSS+JS，启动即用。\n\n---\n\n## 🏗️ 架构\n\n```\n ┌─────────────────────────────────┐\n │ Agent Communication Hub │\n │ localhost:3100 │\n │ │\n ┌─────────┐ SSE/MCP │ ┌──────┐ ┌──────┐ ┌────────┐ │ SSE/MCP ┌─────────┐\n │ Claude │◄─────────►│ │Auth │ │Msg │ │Memory │ │◄─────────►│WorkBuddy│\n │ Code │ │ │RBAC │ │Bus │ │FTS5 │ │ │ │\n └─────────┘ │ └──────┘ └──────┘ └────────┘ │ └─────────┘\n │ ┌──────┐ ┌──────┐ ┌────────┐ │\n ┌─────────┐ │ │Task │ │Orch │ │Evol │ │ ┌─────────┐\n │OpenClaw │◄─────────►│ │Sched │ │Str │ │Engine │ │◄─────────►│ Hermes │\n └─────────┘ │ └──────┘ └──────┘ └────────┘ │ └─────────┘\n └────────────┬────────────────────┘\n │\n ┌──────▼──────┐ ┌─────────────┐\n │ SQLite │ │ Web Panel │\n │ (WAL 模式) │ │ /dashboard │\n └─────────────┘ └─────────────┘\n```\n\n---\n\n## 🔧 SDK 快速上手\n\n### Python — 零外部依赖\n\n```python\nfrom hub_client import SynergyHubClient\n\nhub = SynergyHubClient(hub_url=\"http://localhost:3100\", agent_id=\"my-agent\")\nhub.set_token(\"your-api-token\")\n\nhub.send_message(to=\"other-agent\", content=\"任务完成，交接。\") # 发消息\nhub.store_memory(content=\"用户偏好 JSON\", scope=\"collective\") # 存记忆\ntask = hub.create_task(title=\"评审 PR #42\", assignee=\"claude-code\") # 派任务\nhub.share_experience(title=\"修复方案\", content=\"...\", category=\"debug\") # 分享经验\nhub.on_message = lambda msg: print(f\"收到: {msg}\")\nhub.connect_sse() # 实时监听\n```\n\n### TypeScript — 零外部依赖\n\n```typescript\nimport { AgentClient } from \"./client-sdk/agent-client.js\";\n\nconst client = new AgentClient({\n agentId: \"my-agent\",\n hubUrl: \"http://localhost:3100\",\n token: \"your-api-token\",\n onMessage: async (msg) => { /* 处理消息 */ },\n onTaskAssigned: async (task) => { /* 处理任务 */ },\n});\nawait client.start();\nawait client.sendMessage({ to: \"other-agent\", content: \"搞定了！\" });\n```\n\n---\n\n## 🆚 对比其他方案\n\n| 特性 | ACH | 自建 Webhook | 共享数据库 | 消息队列(RabbitMQ) |\n|------|:---:|:-----------:|:----------:|:-----------------:|\n| 5 分钟部署 | ✅ | ❌ | ❌ | ❌ |\n| MCP 原生支持 | ✅ | ❌ | ❌ | ❌ |\n| 共享记忆 + FTS5 搜索 | ✅ | ❌ | ❌ | ❌ |\n| 任务调度 + Pipeline | ✅ | ❌ | ❌ | ❌ |\n| 进化引擎（经验复用） | ✅ | ❌ | ❌ | ❌ |\n| 内置 Web 面板 | ✅ | ❌ | ❌ | ❌ |\n| 审计哈希链 | ✅ | ❌ | ❌ | ❌ |\n| 零外部服务 | ✅ | ✅ | ✅ | ❌ |\n| Python + TS SDK | ✅ | ❌ | ❌ | ❌ |\n\n---\n\n## 📦 部署方式\n\n### 🐳 Docker（推荐，一键启动）\n\n```bash\ndocker run -d -p 3100:3100 --name ach ghcr.io/liuboacean/agent-comm-hub\n```\n\n### 📦 Docker Compose（含 Prometheus + Grafana 监控）\n\n```bash\ncd deploy/\ndocker compose up -d\n# Hub: http://localhost:3100 | Grafana: http://localhost:3000 (admin/admin)\n```\n\n### 🔧 源码安装\n\n```bash\ngit clone https://github.com/liuboacean/agent-comm-hub.git\ncd agent-comm-hub\nnpm install && npm run build\nnpm start # 生产模式\n# 或 npm run dev # 开发模式\n```\n\n### 🎯 作为 Skill 安装\n\n```bash\n# ClawHub\nclaw install agent-comm-hub\n\n# SkillHub（30+ 平台）\nskillhub install agent-comm-hub\n```\n\n---\n\n## ⚠️ Node 版本要求（重要）\n\n本项目依赖原生模块 **`better-sqlite3`，它是按 Node 22（NODE_MODULE_VERSION 127）编译的**。因此：\n\n- 🔒 **运行 Hub（`dist/src/server.js` 或 `dist/src/stdio.js`）必须用 Node 22 启动**。若使用 Node 24（或更高），会因 ABI 不匹配立即抛出 `ERR_DLOPEN_FAILED` 崩溃，无法启动。\n- 🧪 **CI 中的 Node 24 仅用于跑单元测试**（且涉及 stdio 启动的冒烟用例已条件化 `skip`）。运行环境必须 **Node 22**（`<23`，better-sqlite3 原生 ABI `NODE_MODULE_VERSION 127` 要求），`package.json` 的 `engines.node` 即声明为 `\">=22 <23\"`。**不要用 Node 24 跑服务**，否则 `better-sqlite3` 会因 ABI 不匹配报 `ERR_DLOPEN_FAILED` 启动崩溃。\n- ✅ **推荐做法**：用版本管理器固定 Node 22（如 `nvm use 22`），或在启动脚本/hub 配置中显式写死 Node 22 二进制绝对路径。\n\n---\n\n## 🔌 给 Agent 配置 MCP\n\n### Stdio（推荐）\n```json\n{\n \"mcpServers\": {\n \"agent-comm-hub\": {\n \"command\": \"/path/to/node22/bin/node\",\n \"args\": [\"dist/src/stdio.js\"],\n \"env\": { \"HUB_AUTH_TOKEN\": \"your-key\", \"DB_PATH\": \"./comm_hub.db\" }\n }\n }\n}\n```\n\n> ⚠️ **必须用 Node 22 二进制启动**（例如绝对路径 `/path/to/node22/bin/node`），**不要**用 Node 24。本项目原生模块 `better-sqlite3` 是按 Node 22（NODE_MODULE_VERSION 127）编译的，使用 Node 24 启动 `dist/src/stdio.js` 或 `dist/src/server.js` 会立即 `ERR_DLOPEN_FAILED` ABI 崩溃。\n\n### HTTP + SSE\n```json\n{\n \"mcpServers\": {\n \"agent-comm-hub\": { \"url\": \"http://localhost:3100/mcp\" }\n }\n}\n```\n\n---\n\n## 🛡️ 安全体系\n\n| 层级 | 措施 |\n|:----|------|\n| **认证** | Token + SHA-256 哈希存储，原始 Token 不落盘 |\n| **授权** | 4 级 RBAC：public → member → group_admin → admin |\n| **审计** | 区块链式哈希链 `prev_hash → record_hash`，DB 触发器保障 |\n| **信任** | 自动评分，0-100 分影响策略审批等级 |\n| **网络** | CORS 白名单制 / X-Frame-Options / CSP / HSTS |\n\n---\n\n## 📁 项目结构\n\n```\nagent-comm-hub/\n├── web/dist/index.html # Web 管理面板（零前端框架）\n├── src/ # 核心源码（TypeScript）\n│ ├── server.ts # Express + SSE + MCP 入口\n│ ├── db.ts # SQLite WAL 数据库\n│ ├── backup.ts # 自动备份模块\n│ ├── identity.ts # 注册 / 心跳 / RBAC\n│ ├── memory.ts # 三级记忆 + FTS5 搜索\n│ ├── orchestrator.ts # 依赖链 / Pipeline\n│ ├── evolution.ts # 经验共享 / 策略审批\n│ └── security.ts # Token / 审计 / CORS\n├── client-sdk/\n│ ├── hub_client.py # Python SDK（68 方法，零依赖）\n│ └── agent-client.ts # TypeScript SDK（35 方法）\n├── deploy/ # Docker Compose + 监控\n├── tests/ # 288 个测试\n└── docs/ # 完整文档\n```\n\n---\n\n## 📚 文档导航\n\n| 文档 | 适合谁 |\n|------|--------|\n| [API 参考](docs/API_REFERENCE.md) | 开发者（HTTP/SSE/MCP 端点 + Bearer 鉴权） |\n| [编排指南](docs/advanced-orchestration-guide.md) | 搭 Pipeline 高级玩家 |\n| 进化引擎指南 | 实验性，欢迎 PR（计划从 A 层 `evolution-guide.md` 同步） |\n| Hermes 集成指南 | 实验性，欢迎 PR（计划从 A 层 `hermes-integration-guide.md` 同步） |\n| [DB 三层防护](docs/hub-db-split-three-layer-protection.md) | 运维/稳定性保障 |\n| [Agent 协调时序图](docs/agent-coordination-flow.mermaid) | 想看清「任务从 A 到 B 全自动流转、哪里卡 HITL」的人 |\n| [English README](docs/README_EN.md) | English speakers |\n\n> 📌 **文档同步说明（B 层为权威源）**：服务端仓库（`agent-comm-hub-src`）是文档的单一权威来源。当前 `package.json` 的 `docs:sync` 脚本依赖 `scripts/sync-docs.ts`，**该文件尚未提供**，因此 A 层 Skill 分发包（`~/.workbuddy/skills/agent-comm-hub/`）需**手动同步**：将本仓库的 `docs/`、`SKILL.md`、`README.md` 复制到 A 层对应位置。后续若补充 `scripts/sync-docs.ts`，可用 `npm run docs:sync` 自动同步。\n\n---\n\n## 🆕 更新历史\n\n
\nv3.0.24 (2026-08-14) — 宿主执行器闭环收口（HostExecutor 注入）\n\n- ⚡ **真实宿主执行器（HostExecutor）** — 新增 `client-sdk/adapters/host-executor.ts`，提供 `LlmHostExecutor` / `HttpHostExecutor` 参考实现，`defaultHostExecutor()` 按环境变量自动选择；`AbstractHostTaskBridge` 新增可注入 `executor` 字段\n- 🔧 **消灭 setTimeout 占位** — WorkBuddy / Hermes 桥 `runTask()` 委托 `this.executor.execute()`，任务到达即触发宿主真实能力，自主执行闭环真正打通\n- 📝 **文档** — `docs/HOST_INTEGRATION.md` §4 重写，含 HostExecutor 注入模型与自定义执行器示例\n\n
\n\n
\nv3.0.23 (2026-08-14) — Agent 自主执行闭环 + 人在环授权\n\n- 🤖 **Feature A：Agent 自主执行闭环** — 新增 `AgentRuntime`（client-sdk/runtime.ts），自动驱动 `in_progress → execute() → completed/failed`，含 inFlight 去重 / 崩溃恢复 / loopGuard，消灭人工「传话」\n- 🔐 **Feature B：人在环授权队列** — 新增操作级授权（`auth_requests` 表 + `request_authorization`/`resolve_authorization` 工具，deny-by-default，TTL 10min）+ Web `AuthQueue` 面板，敏感操作一键批准/拒绝\n- 🧹 **清理陈旧产物** — 移除 `client-sdk/` 下 3 个 5 月旧编译 `.js`（`agent-client.js` / `hermes-integration.js` / `workbuddy-integration.js`）及其 `.map`，修正 `client-sdk/package.json` 入口引用\n\n
\n\n
\nv3.0.22 (2026-07-23) — 在线状态 / 审计归档 / 备份路径\n\n- 🟢 **在线状态统一判定** — 新增 `isAgentOnline()` =（存在 SSE 实时连接）**或**（心跳 90s 内）；`get_online_agents`、派单候选排序、`/health/detailed`、`/api/agents`、指标全部改用统一判定，SSE 连着即在线、可派单\n- 💓 **心跳监控不再误杀 SSE 在线 Agent** — 仍有 SSE 连接的 Agent 不因心跳陈旧误标离线、不再广播离线通知；SSE 连接建立即同步 `agents.status`\n- 🗂️ **`audit_log` 行数上限自动归档** — 超 `AUDIT_LOG_MAX_ROWS`（默认 3000，env 可调）自动将最旧溢出行**镜像**到 `audit_log_archive`（WORM 安全，不删源表）；新增启动即跑 + 每小时维护调度器\n- 📦 **备份路径稳定化** — `backup.ts` 的 `BACKUP_DIR` 由 `process.cwd()/backups`（易失 workspace）改为 `~/agent-comm-hub/backups`，与 launchd 备份脚本同目录，支持 `BACKUP_DIR` 覆盖\n\n
\n\n
\nv3.0.21 (2026-07-23) — 安全加固（稳定性 / 安全 / 质量）\n\n- 🔌 **P1-1 SSE 重连竞态** — `registerClient`/`removeClient` 增连接级 `connId` 校验，旧 socket 的 `close` 不再误删当前实时连接，重连后消息/任务不再静默丢失\n- 💾 **P1-2 并发写 `SQLITE_BUSY`** — `busy_timeout=5000` + `foreign_keys` + WAL 自动检查点，消除并发写静默丢数据\n- 🛡️ **P1-3 限流绕过** — 认证前置单 IP / 全局限流（防令牌爆破与未认证 `/mcp` 耗尽资源）；`/mcp` 增并发在途上限（默认 50）防 DoS\n- 🔍 **P1-4/5 FTS 值碰撞** — `memories_fts` 增 `memory_id` 精确关联键（启动迁移旧表），内容相同的两条记忆不再互相串台\n- 🔐 **P2 质量** — 信任分按 `target` 列计吊销（管理员不再误扣）；受保护端点仅接受 `Bearer`，移除 `?token=` 与 `x-api-key` 令牌泄漏面\n\n
\n\n
\nv3.0.20 (2026-07-23) — 构建产物固化\n\n- 🏗️ **构建产物固化** — `dist/package.json` 生成写入 `build` 脚本与启动脚本，消除「安装即崩溃」（`version.ts` 启动依赖 `../package.json`）\n\n
\n\n
\nv3.0.19 (2026-07-21) — 文档与版本一致性修复\n\n- 📝 **文档工具数统一为 58** — 与 `src/security.ts` 的 `TOOL_PERMISSIONS` 矩阵一致，修正 README/SKILL.md 残留的 56/53\n- 📚 **新建 `docs/API_REFERENCE.md`** — 准确的 HTTP/SSE/MCP 端点速查（含 Bearer 鉴权与 SSE `Last-Event-ID` 断线重连）；修正 README 三处死链\n- 🏷️ **SKILL.md 文件传输工具名更正** — `send_file`/`receive_file` → `upload_file`/`download_file`\n\n
\n\n
\nv3.0.18 (2026-07-14) — 安全加固集（ClawScan 67 findings + IDOR）\n\n- 🔒 **修复 ClawScan 审计 67 findings** — fail-closed 权限矩阵 + stdio 强制认证\n- 🛡️ **IDOR 对象级授权加固** — `assertOwns` + `HUB_2004` 防越权访问\n- 🧩 **版本单一真相源** — 抽离 `src/version.ts`；`/health` 收敛\n\n
\n\n
\nv3.0.12 (2026-07-08) — README 同步 + 测试卫生\n\n- 📄 **同步中英文 README** — 对齐 v2.5.1（Node 22 约束锁定 + 测试计数）\n- 🧹 **测试卫生** — 修复 unit 测试在仓库根生成 `undefined*` 游离文件\n\n
\n\n
\nv2.5.1 (2026-07-08) — 稳定性修复 + Node 22 约束锁定\n\n- 🐛 **`get_db_stats` 修复** — ESM 模块误用 `require(\"fs\")` 导致 `require is not defined`，改 `import * as fs`\n- 🔄 **DB 路径容错** — `resolveDbPath` 新增空库自动回退，修复误连空库导致的记忆库/进化引擎\"数据归零\"假象\n- 🔒 **Node 22 锁定** — 启动脚本固定 Node 22，匹配 better-sqlite3 原生模块（Node 24 会 ABI 崩溃）\n- 🧪 **防护测试** — 新增 stdio/Hub 必须用 Node 22 的契约测试，防止被误改回 Node 24\n- 🧹 **测试卫生** — 修复 unit 测试在仓库根生成 `undefined*` 游离文件（`isValidDbPath` 守卫）\n\n
\n\n
\nv2.5.0 (2026-07-07) — Web 管理面板 + 备份模块\n\n- 🖥️ **Web 管理面板** — 纯静态 HTML 仪表盘，6 个实时页面\n- 🔄 **在线状态改进** — 二元标签 → 最后活跃时间，不再跳变\n- 📦 **备份模块** — 本地 + 远程 rsync 备份状态展示\n- ⏱️ **持久化运行时间** — 重启不归零\n- 📊 **新增 API** — `GET /api/agents`\n- 🔧 **`.gitignore` 清理** — 移除已跟踪的编译产物\n\n
\n\n
\nv2.4.7 (2026-06-09) — 标签分词修复 + 全链路日志\n\n- 🔍 FTS5 标签分词修复（空格拼接替代 JSON）\n- 📊 12 处静默吞异常 → logError 全链路可观测\n- 🔐 `authed()` 统一认证中间件重构\n\n
\n\n
\nv2.4.6 (2026-06-09) — FTS5 索引守护 + 外部化路径\n\n- 🔒 FTS5 索引每次存储后自动校验\n- 🛣️ 支持 `HUB_ROOT` 环境变量\n- 📨 新增 `generate_invite` 邀请码工具\n- 🧪 新增 19 个测试用例\n\n
\n\n---\n\n## 🤝 参与贡献\n\n- 🐛 发现 bug → [提 Issue](https://github.com/liuboacean/agent-comm-hub/issues)\n- ✨ 有新想法 → [Feature Request](https://github.com/liuboacean/agent-comm-hub/issues)\n- 📖 改进文档 → PR 欢迎\n- 🔧 贡献代码 → Fork + PR\n\n---\n\n## 📄 许可证\n\nMIT — 可自由用于个人和商业项目。\n\n---\n\n

\n 基于 MCP 协议 + SSE · 零外部服务 · 零厂商锁定
\n 让每一个 AI Agent 都拥有团队协作能力 🤖✨\n

\n\nFile v3.0.25:_meta.json\n\n{\n \"ownerId\": \"kn73qbrbqs4s8t2nh8pm22wxbd84vm7r\",\n \"slug\": \"agent-comm-hub\",\n \"version\": \"3.0.25\",\n \"publishedAt\": 1790732360314\n}\n\nFile v3.0.25:CHANGELOG.md\n\n# Changelog\n\n## [3.0.24] - 2026-08-14 — 宿主执行器闭环收口（HostExecutor 注入）\n\n### Changed (宿主接入收口)\n- **真实宿主执行器（HostExecutor）**：新增 `client-sdk/adapters/host-executor.ts`，提供 `LlmHostExecutor`（直连 Anthropic/OpenAI，需 `HOST_LLM_API_KEY`）与 `HttpHostExecutor`（POST 到 `HOST_EXEC_ENDPOINT`）两套参考实现；`defaultHostExecutor()` 按环境变量自动二选一；`AbstractHostTaskBridge` 新增可注入 `executor` 字段（默认 `defaultHostExecutor()`）\n- **消灭 setTimeout 占位**：WorkBuddy / Hermes 桥的 `runTask()` 改为委托 `this.executor.execute(task, report)`，任务到达即触发宿主真实能力，「任务派发 → Agent 自动干活 → 回写结果」真正闭环\n- **文档**：`docs/HOST_INTEGRATION.md` §4 重写为 HostExecutor 注入模型 + 环境变量表 + 自定义执行器示例\n\n## [3.0.23] - 2026-08-14 — Agent 自主执行闭环 + 人在环授权\n\n### Added (Feature A — Agent 自主执行闭环)\n- **`AgentRuntime` 运行时原语**（`client-sdk/runtime.ts`）：包裹 `AgentClient`，自动驱动 `in_progress → execute() → completed/failed`，内置 inFlight 去重、崩溃恢复、loopGuard，消灭 Agent 间人工「传话」\n- **`runAutonomousLoop` 工厂**：宿主一行接入即可让 Agent 自动消费任务事件并自循环\n\n### Added (Feature B — 人在环授权队列)\n- **操作级授权**：`auth_requests` 表 + `request_authorization` / `resolve_authorization` / `list_authorization_requests` 工具，deny-by-default，TTL 10min\n- **Web `AuthQueue` 面板**：待授权操作实时队列，用户一键批准 / 拒绝\n- **SSE 事件推送**授权请求；宿主侧 `AgentClient.requestAuthorization(op)` 阻塞等待决议\n\n### Chore\n- 清理 `client-sdk/` 下 3 个 5 月陈旧编译产物（`agent-client.js` / `hermes-integration.js` / `workbuddy-integration.js`）及其 `.map`，修正 `client-sdk/package.json` 的 `main` / `files` 入口引用；vitest 的 `.js→.ts` 别名已旁路这些文件，移除不影响构建与 312 项测试\n\n## [3.0.22] - 2026-07-23 — 在线状态 / 审计归档 / 备份路径\n\n### Changed (在线状态判定)\n- **SSE 实时连接纳入「在线」判定**：新增统一判定 `isAgentOnline()` / `getOnlineAgentIds()` =（存在 SSE 连接）**或**（心跳在 90s 阈值内）。`get_online_agents` 工具、派单候选排序（`orchestrator`）、`/health/detailed`、`/api/agents`、`hub_agents_online` 指标全部改用统一判定\n- **心跳监控不再误杀 SSE 在线 Agent**：`startHeartbeatMonitor` 对仍有 SSE 连接的 Agent 不再因心跳陈旧标记离线、也不再广播离线通知\n- **SSE 连接同步 `agents.status`**：连接建立即标记 `online`、断开且心跳陈旧才标 `offline`，数据库与「SSE 已连」事实一致\n\n### Changed (审计日志归档)\n- **`enforceAuditLogCap(maxRows)`**：`audit_log` 超过 `AUDIT_LOG_MAX_ROWS`（默认 3000，env 可调）行时，将最旧溢出行自动**镜像**到 `audit_log_archive`（WORM 安全，不删源表）\n- **维护调度器**：`server` 启动即跑、之后每小时执行「90 天时间归档 + 行数上限镜像」，解决「audit_log 无限增长、归档机制空转」\n\n### Changed (备份路径)\n- **`backup.ts` 改用稳定路径**：`BACKUP_DIR` 从 `process.cwd()/backups`（易失 workspace）改为 `~/agent-comm-hub/backups`，与 launchd 备份脚本同目录；支持 `BACKUP_DIR` 环境变量覆盖\n\n## [3.0.21] - 2026-07-23 — 审计修复（稳定性 / 安全 / 质量）\n\n### Fixed (P1 — 稳定性 / 安全)\n- **P1-1 SSE 重连竞态**：`registerClient`/`removeClient` 增加连接级 `connId` 校验，旧 socket 的 `close` 事件不再误删「当前」实时连接，重连后消息 / 任务 / 激活通知不再静默丢失\n- **P1-2 并发写 `SQLITE_BUSY`**：`db` 初始化增加 `busy_timeout=5000` + `foreign_keys=ON` + `wal_autocheckpoint`，消除 HTTP handler / SSE push / 后台调度并发写导致的静默丢数据\n- **P1-3 限流绕过**：认证前置 IP / 全局限流（防令牌爆破与未认证 `/mcp` 耗尽资源）；`/mcp` 增加并发在途上限（默认 50）防 DoS\n- **P1-4 / P1-5 FTS 值碰撞**：`memories_fts` 增加 `memory_id` 精确关联键（启动迁移旧表），召回按 `id` 关联、删除按 `id` 命中，内容相同的两条记忆不再互相串台（删除一条误伤另一条）\n\n### Fixed (P2 — 质量 / 文档)\n- **P2-1 信任分误扣**：`revoke_token` 审计将「被吊销者」写入 `target` 列，信任分公式改按 `target` 统计，管理员不再被误扣、被吊销者正确扣分\n- **P2-2 metrics 无界数组**：`counters` 改为 keyed `Map`，消除高基数标签下的 O(N) 扫描与内存增长\n- **P2-3 对象级授权**：并行组内跨任务访问保持协作语义（by-design）；资源不存在时正确交由调用方 404\n- **P2-4 优雅关闭顺序**：`await httpServer.close()` 后再关 DB，避免 WAL 写后关\n- **P2-5 SSE 写后关保护**：`pushToAgent` / `writeStoredEvent` 写前校验 `res` 可写\n- **P2-6 令牌泄漏**：受保护端点移除 `?token=` 与 `x-api-key` 接受，仅保留 Bearer\n- **P2-7 死代码清理**：移除 `RateLimiter.getTopLimited` 死桩；`version.ts` 增加 `readFileSync`/`JSON.parse` 的 `try/catch` 防启动崩溃\n- **P2-8 文档漂移**：README 修正 `engines.node` 声明（实际为 `>=22 <23`）；补齐 CHANGELOG；SKILL.md 版本号同步\n\n## [3.0.20] - 2026-07-23 — 构建产物固化\n\n### Fixed\n- 固化 `dist/package.json` 生成到 `build` 脚本与启动脚本，消除「安装即崩溃」类问题（`version.ts` 启动依赖 `../package.json`）\n\n## [3.0.19] - 2026-07-23 — 文档与版本一致性修复 (D10)\n\n### Fixed\n- 文档工具数统一为 **58**（与 `src/security.ts` 的 `TOOL_PERMISSIONS` 矩阵一致）：README 与 SKILL.md 中残留的 56 / 53 全部更正\n- 新建 `docs/API_REFERENCE.md`：准确的 HTTP / SSE / MCP 端点速查，含 Bearer 鉴权与 SSE `Last-Event-ID` 断线重连说明\n- 修复 README 三处死链：`API_REFERENCE.md`（已新建）、`evolution-engine-guide.md` 与 `hermes-integration-guide.md`（标注 TODO，计划从 A 层同步）\n- SKILL.md 文件传输工具名更正：`send_file` / `receive_file` → `upload_file` / `download_file`\n- A 层 `install.sh`：构建产物路径 `dist/server.js` → `dist/src/server.js`；新增版本固定（从 `package.json` 读取 version 并 `git checkout v`）\n- 在 README 注明 B 层为文档权威源；因 `scripts/sync-docs.ts` 暂缺，A 层 Skill 分发包需手动同步\n\n## [2.5.0] - 2026-07-07\n\n### Added\n- P1-4 激活编排层：Agent 状态机 (registered/active/suspended/retired) + Pipeline 状态机 (draft/active/paused/completed/cancelled) + ActivationOrchestrator\n- P1-4 MCP 工具：activate_agent / deactivate_agent / pause_pipeline / resume_pipeline\n- P2-8 令牌桶限流：RateLimiter（单 Agent 100/min + 全局 1000/min，env 可配）\n- P2-8 Backoff 指数退避：client-sdk/backoff.ts（base 200ms, cap 10s, jitter）\n- P2-8 send_message 限流接入：超限返回 429 + Retry-After\n- P2-7 Web 管理面板：Vite + React + MUI + Tailwind 运维仪表盘\n- P2-7 面板后端端点：GET /api/status + GET /api/audit/tail + /dashboard 静态托管\n- Metrics 增强：getTopLimited() 限流 Top N 查询\n- SSE 增强：broadcastToAll() 全连接广播\n- 版本同步：CHANGELOG.md 变更日志\n\nFile v3.0.25:client-sdk/README_PYPI.md\n\n# Agent Communication Hub — Python SDK\n\nZero-dependency Python client for [Agent Communication Hub](https://github.com/liuboacean/agent-comm-hub) — production-grade multi-agent infrastructure for real-time messaging, task scheduling, and shared memory.\n\n```python\nfrom hub_client import SynergyHubClient\n\nhub = SynergyHubClient(\"http://localhost:3100\")\nhub.set_token(\"your-token\")\nhub.send_message(to=\"other-agent\", content=\"Hello!\")\n```\n\n## Features\n\n- **P2P Messaging** — Real-time communication between agents via SSE\n- **Task Scheduling** — Create, assign, and track tasks across agents\n- **Shared Memory** — Three scopes: private, team, collective\n- **Zero External Dependencies** — Only Python stdlib required\n- **Auto-Reconnect** — Exponential backoff SSE reconnection\n- **Client-Side Dedup** — Built-in event deduplication\n\n## Install\n\n```bash\npip install agent-comm-hub\n```\n\n## Quick Start\n\n```python\nfrom hub_client import SynergyHubClient, create_client\n\n# Connect to a running Hub\nhub = SynergyHubClient(\"http://localhost:3100\")\n\n# Register (requires invite code from Hub admin)\nresult = hub.register(invite_code=\"YOUR_INVITE_CODE\", name=\"my-agent\")\nhub.set_token(result[\"api_token\"])\n\n# Send a message\nhub.send_message(to=\"other-agent\", content=\"Hello from Python!\")\n\n# Store collective memory\nhub.store_memory(\n content=\"User prefers JSON responses\",\n scope=\"collective\"\n)\n\n# Real-time SSE listener (blocking)\nhub.on_message = lambda msg: print(f\"Received: {msg}\")\nhub.connect_sse()\n```\n\n## Requirements\n\n- Python 3.9+\n- An [Agent Communication Hub](https://github.com/liuboacean/agent-comm-hub) server running (local or remote)\n\n## License\n\nMIT\n\nFile v3.0.25:CONTRIBUTING.md\n\n# Contributing to Agent Communication Hub\n\nThank you for your interest in contributing! This project is the shared nervous system for multi-agent AI infrastructure — every improvement benefits every agent that runs on the Hub.\n\n---\n\n## Ways to Contribute\n\n- 🐛 **Report bugs** — Open an issue with the bug report template\n- ✨ **Feature requests** — Open an issue with the feature request template\n- 📖 **Improve docs** — Submit a PR to fix typos, add examples, or translate\n- 🔧 **Code contributions** — Fix bugs, add tools, improve SDKs\n- 🧪 **Add tests** — Increase test coverage for untested modules\n- 📣 **Share the project** — Star the repo, write about it, tell a friend\n\n---\n\n## Development Setup\n\n### Prerequisites\n\n- Node.js 18+ (for Hub server)\n- Python 3.9+ (for Python SDK)\n- SQLite 3 (usually pre-installed)\n\n### Install dependencies\n\n```bash\ngit clone https://github.com/liuboacean/agent-comm-hub.git\ncd agent-comm-hub\nnpm install\nnpm run build\n```\n\n### Start the Hub\n\n```bash\nnpm start\n# or for development with hot reload:\nnpm run dev\n```\n\n### Run tests\n\n```bash\n# Unit tests with coverage\nnpm run test:unit\n\n# End-to-end tests (requires Hub running)\nnpm run test:e2e\n```\n\n### Code style\n\n- TypeScript: follow the project's `tsconfig.json` settings\n- Python: follow PEP 8 (max line length 120)\n- Commit messages: use [Conventional Commits](https://www.conventionalcommits.org/)\n\n---\n\n## Project Structure\n\n```\nsrc/\n server.ts — Express + SSE + MCP entry point\n db.ts — SQLite WAL schema and queries\n identity.ts — Agent registration, heartbeat, RBAC\n memory.ts — 3-scope memory layer with FTS5\n task.ts — Task scheduler, 7-state machine\n orchestrator.ts — Dependency chains, pipelines, quality gates\n evolution.ts — Strategy engine, trust scoring\n security.ts — Token auth, RBAC, audit hash chain\n\nclient-sdk/\n hub_client.py — Python SDK (no external deps)\n agent-client.ts — TypeScript SDK\n\ndocs/ — Architecture & integration guides\nscripts/ — Install, test, migration scripts\ndeploy/ — Docker Compose, Prometheus, Grafana\n```\n\n---\n\n## Pull Request Process\n\n1. **Fork** the repository and create a branch from `main`:\n ```bash\n git checkout -b feat/your-feature-name\n # or\n git checkout -b fix/your-bug-description\n ```\n\n2. **Make your changes.** Follow the code style guidelines above.\n\n3. **Add tests** for any new functionality. The project uses vitest for unit tests.\n\n4. **Ensure tests pass:**\n ```bash\n npm run test:unit\n npx tsc --noEmit\n ```\n\n5. **Commit** using Conventional Commits format:\n ```bash\n git commit -m \"feat(memory): add FTS5 search for collective memories\"\n git commit -m \"fix(task): prevent duplicate state transitions\"\n ```\n\n6. **Push and open a Pull Request.** Fill out the PR template.\n\n7. A maintainer will review within 48 hours. Be responsive to feedback.\n\n---\n\n## Releasing a Version\n\nVersions are released by tagging on `main`:\n\n```bash\n# Update version in package.json\nnpm version patch # 2.4.1 → 2.4.2\n# or\nnpm version minor # 2.4.1 → 2.5.0\n# or\nnpm version major # 2.4.1 → 3.0.0\n\ngit push --follow-tags\n```\n\nThis triggers the `docker.yml` workflow, which builds and publishes the Docker image automatically.\n\n---\n\n## Code of Conduct\n\nBe respectful and constructive. We welcome contributors from all backgrounds. This project follows the [Contributor Covenant](https://www.contributor-covenant.org/).\n\n---\n\n## Questions?\n\nOpen a GitHub Discussion or ping the maintainer. We respond within 48 hours.\n\nFile v3.0.25:docs/adr/0001-sse-reliable-delivery.md\n\n# ADR-0001: SSE 可靠投递\n\n**状态:** Accepted · **日期:** 2026-07-21 · **修复:** D1（v3.0.19）\n\n## 背景 / 问题\n`sse.ts` 的 `event_id` 是 per-connection 内存计数器，重连归零；事件不持久化，离线补发不可行；`Last-Event-ID` 与 `_hub_event_id` 脱钩，致首连丢消息、重连无法补发。\n\n## 考虑过的方案\n- **A** 毫秒时间戳 + 固定窗口；**B** 持久化 `event_log` + 全局 `event_seq`（采用）。\n\n## 决策\n新增 `event_log` 表（`event_seq` 全局单调、`delivered` 标记）。服务端以 `event_seq` 作 SSE `id`；客户端以其作 `Last-Event-ID`。重连仅重放 `seq > Last-Event-ID` 的 event（覆盖全部类型），仅推送成功才标 `delivered`。\n\n## 后果 / 权衡\n不用 A：同毫秒乱序、跨进程不单调、窗口外永久丢失。持久化使服务端成重放权威源；代价为写开销 + 需归档（参考 `messages_archive`）防膨胀。\n\nFile v3.0.25:docs/adr/0002-activation-state-persistence.md\n\n# ADR-0002: 激活态持久化\n\n**状态:** Accepted · **日期:** 2026-07-21 · **修复:** D2（v3.0.19）\n\n## 背景 / 问题\n`ActivationOrchestrator` 用内存 `Map` 维护激活态，启动靠 `replayFromAudit` 从 `audit_log` 重放。未审计的 registered Agent 内存缺失，`activateAgent` 返回 `AGENT_NOT_FOUND`，编排层不可用（D2）；内存态与 DB 无权威一致。\n\n## 考虑过的方案\n- **A** 纯内存 + 仅审计重放（现状）；**B** DB 权威 + 内存热缓存（采用）。\n\n## 决策\n启动从 `agents` 表 seed registered 态进编排器；`activateAgent` 内存未命中回查 `agents.status` 并载入；激活态落库 `agents.status`（`registered/active/suspended/retired`），写先 DB 后内存，重启从 DB 重载。\n\n## 后果 / 权衡\nDB 权威、内存热缓存，激活低频可接受。必配 D8 对象级鉴权：激活态写 `agents.status` 驱动授权，缺 D8 则任意方可篡改 → 越权。`agents.status` 原表 `online/offline`，实现须区分在线态与激活态。\n\nFile v3.0.25:docs/advanced-orchestration-guide.md\n\n# 进阶编排使用指南\n\n> **版本**：v1.0 | **日期**：2026-04-25\n> **所属**：Agent Synergy Framework Phase 4b\n> **Hub 版本**：v2.0.0+（含 Task Orchestrator 进阶能力）\n\n---\n\n## 概述\n\nPhase 4b 在 Phase 4a 线性 Pipeline 基础上，引入了四种进阶编排能力：\n\n| 能力 | 解决的问题 | 核心工具 |\n|------|-----------|---------|\n| **依赖链** | 任务有前后顺序（B 必须等 A 完成） | `add_dependency` / `remove_dependency` / `get_task_dependencies` |\n| **并行组** | 多个任务可同时执行（A、B、C 互不依赖） | `create_parallel_group` |\n| **质量门** | Pipeline 阶段检查点（代码 review 后才能继续） | `add_quality_gate` / `evaluate_quality_gate` |\n| **交接协议** | 任务负责人变更（双向握手确认） | `request_handoff` / `accept_handoff` / `reject_handoff` |\n\n---\n\n## 1. 依赖链\n\n### 1.1 概念\n\n依赖链定义任务间的执行顺序。当任务 B 依赖任务 A 时：\n- A 未完成 → B 处于 `waiting` 状态\n- A 完成 → B 自动从 `waiting` 变为可执行\n- 如果 A→B→C→A 形成环 → 自动拒绝（DFS 环检测）\n\n### 1.2 依赖类型\n\n| 类型 | 说明 | 触发时机 |\n|------|------|---------|\n| `finish_to_start` | 上游**完成后**下游可开始（默认） | 上游 status = completed |\n| `start_to_start` | 上游**开始后**下游可开始 | 上游 status = in_progress |\n| `finish_to_finish` | 上游**完成后**下游可完成 | 上游 status = completed |\n\n### 1.3 使用示例\n\n```json\n// 1. 创建三个任务\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"design\", \"title\": \"UI设计\", \"assigned_to\": \"designer\", \"operator_id\": \"pm\" } }\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"frontend\", \"title\": \"前端开发\", \"assigned_to\": \"dev1\", \"operator_id\": \"pm\" } }\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"test\", \"title\": \"测试\", \"assigned_to\": \"qa\", \"operator_id\": \"pm\" } }\n\n// 2. 建立依赖：design → frontend → test\n{ \"tool\": \"add_dependency\", \"args\": { \"upstream_id\": \"design\", \"downstream_id\": \"frontend\" } }\n{ \"tool\": \"add_dependency\", \"args\": { \"upstream_id\": \"frontend\", \"downstream_id\": \"test\" } }\n\n// 3. 此时 frontend 和 test 自动变为 waiting 状态\n// 4. designer 完成 design → frontend 自动解除 waiting → dev1 可以开始\n```\n\n### 1.4 工具参数\n\n#### add_dependency\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `upstream_id` | string | ✅ | 上游任务 ID（需先完成） |\n| `downstream_id` | string | ✅ | 下游任务 ID（依赖上游完成后才能开始） |\n| `dep_type` | enum | ❌ | 依赖类型，默认 `finish_to_start` |\n\n**返回**：依赖创建结果 + 自动评估下游任务状态\n\n**错误**：循环依赖 → `\"Circular dependency detected\"` / 任务不存在 → `\"Task not found\"`\n\n#### get_task_dependencies\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `task_id` | string | ✅ | 要查询的任务 ID |\n\n**返回**：\n\n```json\n{\n \"task_id\": \"frontend\",\n \"upstreams\": [\n { \"task_id\": \"design\", \"status\": \"completed\", \"dep_type\": \"finish_to_start\", \"dep_status\": \"satisfied\" }\n ],\n \"downstreams\": [\n { \"task_id\": \"test\", \"status\": \"waiting\", \"dep_type\": \"finish_to_start\", \"dep_status\": \"pending\" }\n ]\n}\n```\n\n### 1.5 状态机扩展\n\n```\n原始状态机：\ninbox → assigned → in_progress → completed\n ↓ ↓\n cancelled failed\n\nPhase 4b 扩展：\ninbox → assigned → waiting → in_progress → completed\n ↓ ↓ ↓\n cancelled cancelled failed\n```\n\n`waiting` 状态：任务有未满足的上游依赖，自动进入。所有上游依赖满足后自动解除。\n\n---\n\n## 2. 并行组\n\n### 2.1 概念\n\n并行组标记一组可以同时执行的任务。同一 `parallel_group` 内的任务互不依赖，可由不同 Agent 并行处理。\n\n### 2.2 使用示例\n\n```json\n// 1. 创建多个独立任务\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"api-dev\", \"title\": \"API开发\", \"assigned_to\": \"backend-dev\" } }\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"ui-dev\", \"title\": \"UI开发\", \"assigned_to\": \"frontend-dev\" } }\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"doc-dev\", \"title\": \"文档编写\", \"assigned_to\": \"tech-writer\" } }\n\n// 2. 标记为并行组\n{ \"tool\": \"create_parallel_group\", \"args\": {\n \"task_ids\": [\"api-dev\", \"ui-dev\", \"doc-dev\"],\n \"group_name\": \"v2-parallel-sprint\"\n}}\n\n// 3. 三个任务可以同时执行\n// 4. 查看并行组信息（通过 get_task_status 或直接查询）\n```\n\n### 2.3 工具参数\n\n#### create_parallel_group\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `task_ids` | string[] | ✅ | 并行任务 ID 列表（2-10 个） |\n| `group_name` | string | ❌ | 并行组名称（便于识别） |\n\n**约束**：最少 2 个，最多 10 个任务\n\n### 2.4 与依赖链组合\n\n并行组常与依赖链组合使用，形成 DAG 工作流：\n\n```\n[design] ──完成──→ [并行组: api-dev + ui-dev + doc-dev] ──全部完成──→ [integration-test]\n ↑ ↑ ↑\n 互不依赖，可并行 三个都完成后 最后集成\n```\n\n---\n\n## 3. 质量门\n\n### 3.1 概念\n\n质量门是 Pipeline 阶段的检查点。只有通过质量门后，后续任务才能继续。适用于代码 review、测试验收等场景。\n\n### 3.2 使用示例\n\n```json\n// 1. 创建质量门（代码 review）\n{ \"tool\": \"add_quality_gate\", \"args\": {\n \"pipeline_id\": \"release-pipeline\",\n \"gate_name\": \"code_review\",\n \"criteria\": \"{\\\"type\\\":\\\"all_completed\\\",\\\"threshold\\\":1}\",\n \"after_order\": 3\n}}\n\n// 2. 前面 3 个任务完成后，QA 评估质量门\n{ \"tool\": \"evaluate_quality_gate\", \"args\": {\n \"gate_id\": \"\",\n \"agent_id\": \"senior-dev\",\n \"passed\": true,\n \"result\": \"代码质量良好，无重大问题\"\n}}\n\n// 3. 如果 passed=false，后续任务被阻塞\n// 4. 修复后重新评估\n```\n\n### 3.3 工具参数\n\n#### add_quality_gate\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `pipeline_id` | string | ✅ | Pipeline ID |\n| `gate_name` | string | ✅ | 阶段名称（2-100 字符） |\n| `criteria` | string | ✅ | JSON 判定条件 |\n| `after_order` | number | ❌ | 在 order_index > 此值的任务开始前检查 |\n\n**criteria 格式**：\n\n```json\n// 方式1：所有前置任务完成\n{ \"type\": \"all_completed\" }\n\n// 方式2：最低成功率\n{ \"type\": \"min_success_rate\", \"threshold\": 0.8 }\n\n// 方式3：自定义检查表达式\n{ \"type\": \"custom\", \"check_expr\": \"test_coverage > 0.9\" }\n```\n\n#### evaluate_quality_gate\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `gate_id` | string | ✅ | 质量门 ID |\n| `agent_id` | string | ✅ | 评估者 Agent ID |\n| `passed` | boolean | ✅ | 是否通过 |\n| `result` | string | ❌ | 评估结果说明 |\n\n### 3.4 质量门状态\n\n```\npending → passed / failed\n```\n\n- `pending`：等待评估\n- `passed`：门已通过，后续任务可继续\n- `failed`：门未通过，后续任务被阻塞（需修复后重新评估）\n\n### 3.5 SSE 事件\n\n| 事件 | 触发时机 | 推送目标 |\n|------|---------|---------|\n| `quality_gate_passed` | 门通过 | Pipeline 参与者 |\n| `quality_gate_failed` | 门未通过 | Pipeline 参与者 + 管理员 |\n\n---\n\n## 4. 交接协议\n\n### 4.1 概念\n\n交接协议是任务负责人的变更流程，采用双向握手模式：\n\n```\n发起方(A) 接收方(B)\n | |\n |-- request_handoff -------->|\n | |\n |<-- accept_handoff ---------| 或 |-- reject_handoff -------->|\n | | (任务仍归 A)\n |-- assigned_to 更新为 B -->|\n```\n\n### 4.2 使用示例\n\n```json\n// 1. A 请求交接\n{ \"tool\": \"request_handoff\", \"args\": {\n \"task_id\": \"bugfix-123\",\n \"from\": \"dev-a\",\n \"to\": \"dev-b\",\n \"reason\": \"需要前端专家处理\",\n \"context\": \"已完成初步排查，CSS 兼容性问题，需要 Chrome 特定调试\"\n}}\n\n// 2. B 接受（任务转移）\n{ \"tool\": \"accept_handoff\", \"args\": {\n \"task_id\": \"bugfix-123\",\n \"agent_id\": \"dev-b\"\n}}\n\n// 或者 B 拒绝（任务仍归 A）\n{ \"tool\": \"reject_handoff\", \"args\": {\n \"task_id\": \"bugfix-123\",\n \"agent_id\": \"dev-b\",\n \"reason\": \"当前排期已满\"\n}}\n```\n\n### 4.3 工具参数\n\n#### request_handoff\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `task_id` | string | ✅ | 要交接的任务 ID |\n| `from` | string | ✅ | 当前负责人 Agent ID |\n| `to` | string | ✅ | 目标接收人 Agent ID |\n| `reason` | string | ❌ | 交接原因 |\n| `context` | string | ❌ | 交接说明（进度、注意事项等） |\n\n**约束**：\n- 只有任务当前负责人才能发起交接\n- 已终态（completed/failed/cancelled）的任务不能交接\n\n#### accept_handoff / reject_handoff\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `task_id` | string | ✅ | 任务 ID |\n| `agent_id` | string | ✅ | 操作者 Agent ID |\n| `reason` | string | ❌ | 拒绝原因（仅 reject） |\n\n### 4.4 SSE 事件\n\n| 事件 | 触发时机 | 推送目标 |\n|------|---------|---------|\n| `handoff_requested` | 交接请求发出 | 接收方 |\n| `handoff_accepted` | 接收方接受 | 原负责人 |\n| `handoff_rejected` | 接收方拒绝 | 原负责人 |\n\n### 4.5 交接状态\n\n```\nnone → requested → accepted\n → rejected → (可重新请求)\n```\n\n---\n\n## 5. 组合工作流示例\n\n一个完整的 DAG 工作流，组合依赖链 + 并行组 + 质量门 + 交接：\n\n```\n┌──────────────┐\n│ 需求分析 │ (PM)\n└──────┬───────┘\n │ finish_to_start\n ▼\n┌──────────────┐\n│ 架构设计 │ (Architect)\n└──────┬───────┘\n │ finish_to_start\n ▼\n┌──────────────┐\n│ 设计 Review │ ← 质量门（code_review，必须通过）\n└──────┬───────┘\n │ 门通过\n ▼\n┌─────┴─────┐\n│ 并行组 │\n│ ┌───────┐ │\n│ │API开发 │ │ (Backend Dev)\n│ ├───────┤ │\n│ │前端开发│ │ (Frontend Dev)\n│ ├───────┤ │\n│ │文档编写│ │ (Tech Writer)\n│ └───────┘ │\n└─────┬─────┘\n │ 全部完成\n ▼\n┌──────────────┐\n│ 集成测试 │ (QA)\n└──────┬───────┘\n │ 测试通过\n ▼\n┌──────────────┐\n│ 发布交接 │ (Dev → SRE) ← 交接协议\n└──────────────┘\n```\n\n---\n\n## 6. 数据模型\n\n### task_dependencies 表\n\n| 列 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT PK | 依赖关系 ID |\n| upstream_id | TEXT FK→tasks | 上游任务 |\n| downstream_id | TEXT FK→tasks | 下游任务 |\n| dep_type | TEXT | finish_to_start / start_to_start / finish_to_finish |\n| status | TEXT | pending / satisfied / failed |\n| created_at | INTEGER | 创建时间戳 |\n\n**索引**：`idx_deps_downstream(downstream_id, status)`、`idx_deps_upstream(upstream_id, status)`\n\n### quality_gates 表\n\n| 列 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT PK | 质量门 ID |\n| pipeline_id | TEXT FK→pipelines | 所属 Pipeline |\n| gate_name | TEXT | 阶段名称 |\n| criteria | TEXT | JSON 判定条件 |\n| after_order | INTEGER | 在此 order_index 后检查 |\n| status | TEXT | pending / passed / failed |\n| evaluator_id | TEXT | 评估者 |\n| result | TEXT | 评估结果详情 |\n| evaluated_at | INTEGER | 评估时间 |\n\n---\n\n*文档版本：v1.0 | 最后更新：2026-04-25*\n\nFile v3.0.25:docs/API_REFERENCE.md\n\n# Agent Communication Hub — API 参考（v3.0.19）\n\n> 本文档描述 Hub 服务端暴露的 **HTTP / SSE / MCP 端点**与鉴权方式，对应源码 `src/server.ts`、`src/security.ts`、`src/sse.ts`。\n>\n> - 当前版本：`3.0.19`（由 `src/version.ts` 从 `package.json` 读取，单一真相源）\n> - 通过 `/mcp` 暴露 **58 个 MCP 工具**（完整工具权限矩阵见 `src/security.ts` 的 `TOOL_PERMISSIONS`）\n> - 存储：SQLite（WAL 模式）\n\n---\n\n## 1. 基础信息\n\n| 项 | 值 |\n|----|----|\n| 默认监听地址 | `http://localhost:3100` |\n| 协议 | HTTP + SSE + MCP（StreamableHTTP） |\n| 当前版本 | `3.0.19` |\n| MCP 工具数 | 58 |\n| 数据库 | SQLite（WAL） |\n\n---\n\n## 2. 认证（Authentication）\n\n所有需要认证的端点通过 **Bearer Token** 鉴权：\n\n```http\nAuthorization: Bearer \n```\n\n- Token 在 `register_agent` 时一次性返回；服务端以 SHA-256 哈希存储，明文不落盘。\n- 服务端按以下顺序提取 Token（见 `src/security.ts` 的 `extractToken`）：\n 1. 请求头 `Authorization: Bearer `\n 2. 查询参数 `?token=`（仅 SSE 等少数场景使用，**不建议**用于 REST/MCP）\n 3. 请求头 `x-api-key: `\n- 缺失或无效 Token → `401`；`/dashboard` 与 `/api/*` 还要求 `role === 'admin'`，否则 `403`。\n- 限流：每个 Agent **10 请求/秒**，超出 → `429 { error: \"Rate limit exceeded (10 req/s)\" }`。\n\n> ⚠️ **安全建议**：Token 不要放在 URL 查询串中（会被访问日志 / 反向代理记录）。REST 与 MCP 一律使用 `Authorization: Bearer`。\n\n### 中间件分级\n\n| 中间件 | 用于端点 | 规则 |\n|--------|----------|------|\n| `authMiddleware` | `/api/tasks`、`/api/messages`、`/api/consumed`、`/admin/invite/generate` | 必须携带有效 Token（含限流） |\n| `internalMonitorAuth` | `/health`、`/health/detailed`、`/metrics` | loopback（127.0.0.1 / ::1）或有效 Token |\n| `requireAdminApi` | `/dashboard`、`/api/status`、`/api/agents`、`/api/audit/tail` | 有效 Token **且** `role === 'admin'` |\n| `optionalAuthMiddleware` | `/events/:agent_id`、`/mcp` | 有 Token 则校验，无则匿名（auth 置为 undefined） |\n\n---\n\n## 3. 端点速查\n\n### 3.1 健康检查与指标（internalMonitorAuth）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/health` | internalMonitorAuth | 返回 `status` / `version` / `uptime` / 内存占用（rss、heap） |\n| GET | `/health/detailed` | internalMonitorAuth | DB 表统计、FTS5 一致性、24h 积压消息数、在线 Agent 列表 |\n| GET | `/metrics` | internalMonitorAuth | Prometheus 格式指标（`text/plain; version=0.0.4`） |\n\n> loopback 探针或 Prometheus scraper 同源可直接访问；跨机需带有效 Token。\n\n### 3.2 REST API（authMiddleware，供自动化脚本轮询）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/api/tasks?agent_id=&status=` | authMiddleware | 列出指定 Agent 的任务；`status` ∈ `pending`/`in_progress`/`completed`/`failed` |\n| GET | `/api/messages?agent_id=&status=` | authMiddleware | 列出消息；`status` ∈ `unread`/`delivered`/`read`/`acknowledged` |\n| PATCH | `/api/tasks/:id/status` | authMiddleware | body：`status`(`in_progress`/`completed`/`failed`)、`result`、`progress`；成功后 SSE 通知发起方 |\n| PATCH | `/api/messages/:id/status` | authMiddleware | body：`status` ∈ `read`/`delivered`/`acknowledged` |\n| GET | `/api/consumed?agent_id=&resource=` | authMiddleware | 查询消费水位线（防重复处理）；带 `resource` 查单条，否则列最近 50 条 |\n| POST | `/admin/invite/generate` | authMiddleware + admin | 生成邀请码（24h 有效），body：`role`(`admin`/`member`)；返回 `invite_code` |\n\n### 3.3 管理端点（requireAdminApi）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/api/status` | requireAdminApi | 面板总览：Agent / Pipeline 状态分布、近 5 分钟吞吐、FTS5 状态、限流 Top 10 |\n| GET | `/api/agents` | requireAdminApi | 全部 Agent 详情（角色、信任分、最后活跃、在线状态） |\n| GET | `/api/audit/tail?n=<50>` | requireAdminApi | 审计日志尾部（最多 500 条） |\n\n### 3.4 MCP 端点（StreamableHTTP，Stateless）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| POST | `/mcp` | optionalAuthMiddleware | JSON-RPC：`tools/call`、`tools/list`、`initialize` 等 |\n| GET | `/mcp` | optionalAuthMiddleware | 建立 MCP 流（SSE 格式响应） |\n| DELETE | `/mcp` | optionalAuthMiddleware | 终止 MCP 会话 |\n\n- **无状态（Stateless）模式**：`sessionIdGenerator: undefined`，每次请求独立，不维护服务端 session。**多 Client 必须走 Stateless**。\n- 调用时请求头需带 `Accept: application/json, text/event-stream`。\n- 权限：`register_agent` 为 `public`（免 Token），其余 57 个工具需先注册并携带 Token（fail-closed：未登记工具一律拒绝）。\n- 认证失败（限流/无效 Token）返回 JSON-RPC 错误：`{ jsonrpc:\"2.0\", error:{ code:-32001, message:\"Rate limit exceeded (10 req/s)\" }, id:null }`。\n\n### 3.5 SSE 实时推送（optionalAuthMiddleware）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/events/:agent_id` | optionalAuthMiddleware | 长连接，实时推送新消息 / 任务 / 策略 / 交接等事件 |\n\n- 连接示例：\n ```bash\n curl -N \\\n -H \"Authorization: Bearer \" \\\n -H \"Last-Event-ID: <上次事件毫秒时间戳>\" \\\n http://localhost:3100/events/\n ```\n- 每条事件格式（`src/sse.ts` 的 `pushToAgent`）：\n ```\n id: <每连接递增整数>\n event: message\n data: {\"event\":\"new_message\",\"message\":{...},\"_hub_event_id\":,\"_hub_dedup_id\":<可选>}\n\n ```\n- **断线重连**：客户端在请求头带 `Last-Event-ID`（毫秒时间戳）。服务端解析为整数作为 `since`，调用 `messageRepo.listSince(agent_id, since)` 回放该时间戳之后的消息；回放窗口 `SSE_REPLAY_WINDOW`（默认 3600 秒），超出窗口的部分不补发。\n- 首次连接（无 `Last-Event-ID`）：服务端补发离线期间的未读消息与待执行任务。\n- 心跳：每 `SSE_HEARTBEAT_INTERVAL`（默认 10000ms）发送 `: ping`。\n\n> ⚠️ **注意区分两种 id**：SSE 事件体的 `id:` 字段是**每连接递增整数**（`_hub_event_id`，用于客户端去重）；而断线重连的 `Last-Event-ID` 请求头被服务端当作**毫秒时间戳**处理（用于 `listSince` 回放）。客户端重连时应记录并回传最近一次事件的**毫秒时间戳**，而非递增 `id`。\n\n### 3.6 Web 管理面板（requireAdminApi）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/dashboard` | requireAdminApi | 纯静态仪表盘（总览 / Agents / 吞吐 / 健康 / 审计日志） |\n| GET | `/` | 重定向 | → `/dashboard` |\n\n---\n\n## 4. 统一错误格式\n\n- 未匹配路由 → `404 { error:true, message:\"Not Found\", traceId }`\n- 未捕获异常 → `500 { error:true, message, traceId }`（非开发环境隐藏原始 message）\n- 每个响应均带 `X-Trace-Id` 响应头，便于跨服务追踪。\n\n---\n\n## 5. CORS 与安全响应头\n\n- **CORS**：仅放行 `CORS_ORIGINS`（逗号分隔）中的来源，空 = 拒绝所有跨域；`OPTIONS` 预检返回 `204`。允许的请求头：`Content-Type, Authorization, X-Trace-Id, X-Api-Key`。\n- **安全响应头**：`X-Frame-Options: DENY`、`X-Content-Type-Options: nosniff`、`X-XSS-Protection: 1; mode=block`、`Strict-Transport-Security: max-age=31536000; includeSubDomains`、`Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'`。\n\n---\n\n## 6. 端点汇总\n\n| # | 方法 | 路径 | 鉴权 |\n|---|------|------|------|\n| 1 | GET | `/health` | internalMonitorAuth |\n| 2 | GET | `/health/detailed` | internalMonitorAuth |\n| 3 | GET | `/metrics` | internalMonitorAuth |\n| 4 | POST | `/admin/invite/generate` | authMiddleware + admin |\n| 5 | GET | `/api/tasks` | authMiddleware |\n| 6 | GET | `/api/messages` | authMiddleware |\n| 7 | PATCH | `/api/tasks/:id/status` | authMiddleware |\n| 8 | PATCH | `/api/messages/:id/status` | authMiddleware |\n| 9 | GET | `/api/consumed` | authMiddleware |\n| 10 | GET | `/api/status` | requireAdminApi |\n| 11 | GET | `/api/agents` | requireAdminApi |\n| 12 | GET | `/api/audit/tail` | requireAdminApi |\n| 13 | GET | `/events/:agent_id`（SSE） | optionalAuthMiddleware |\n| 14 | POST | `/mcp` | optionalAuthMiddleware |\n| 15 | GET | `/mcp` | optionalAuthMiddleware |\n| 16 | DELETE | `/mcp` | optionalAuthMiddleware |\n| 17 | GET | `/dashboard` | requireAdminApi |\n| 18 | GET | `/` | 重定向 |\n\n> 共 16 个端点路由，其中 `/mcp` 含 POST / GET / DELETE 三方法（共 18 个方法级端点）。58 个 MCP 工具均经 `/mcp` 暴露。\n\nFile v3.0.25:docs/design/ach-autonomous-loop-hitl-auth.md\n\n# ACH 增量架构设计：自主 Agent 执行闭环 + 操作级人在环授权队列\n\n> 版本：设计稿 v1（design only，待用户确认后交付工程师实现）\n> 仓库：`agent-comm-hub`（当前 v3.0.23，TS + better-sqlite3 + SSE + Express + MUI 前端，零外部服务）\n> 设计依据：已逐项核对真实代码（`client-sdk/agent-client.ts`、`src/orchestrator.ts`、`src/sse.ts`、`src/tools.ts`、`src/db.ts`、`src/security.ts`、`web/src/App.tsx`、`client-sdk/*-integration.ts`）。\n\n---\n\n## 1. TL;DR\n\n> **在客户端 SDK 新增一个运行时原语 `AgentRuntime`（包裹现有 `AgentClient`），让 Agent 收到任务后自动「标记进行中 → 执行宿主注入的 `execute()` → 回写完成/失败」，从而消灭人工中转；同时新增一条「操作级授权」闭环——Agent 执行中遇到敏感操作就调 `requestAuthorization(op)` 挂起等待，用户在 Web 仪表盘「待授权」面板批准/拒绝，Hub 经 SSE 把结果回推，Agent 继续或优雅中止。Hub 始终只是纯协调层，零新增依赖。**\n\n两条特性正交：Feature A 解决「收到任务后是否自主执行」，Feature B 解决「执行中敏感操作是否放行」。Feature B 通过 `AgentRuntime` 暴露的 `requestAuthorization()` 接入 Feature A 的 `execute()`。\n\n---\n\n## 2. 实现方案 + 框架选型\n\n### 2.1 总体原则（增量、零新依赖）\n\n| 维度 | 现状（已具备） | 本次增量 | 是否引入新依赖 |\n|---|---|---|---|\n| 传输层 | `AgentClient` SSE 长连接 + 自动重连，`pushToAgent` 实时推 | 复用；仅新增 2 个事件类型 | 否 |\n| 任务状态机 | `orchestrator.ts` `assigned→in_progress→completed/failed` | 复用，`AgentRuntime` 只驱动既有转换 | 否 |\n| 工具层 | `server.tool(name, desc, zodSchema, authed(...))` | 新增 2 个 MCP 工具（注册即接入） | 否（复用 zod） |\n| 持久化 | `better-sqlite3` + `CREATE TABLE IF NOT EXISTS` 迁移 | 新增 `auth_requests`(+可选`auth_grants`) 表 | 否 |\n| 审计 | `auditLog()` 哈希链（`prev_hash`/`record_hash`） | 授权创建/决议写入同一条链 | 否 |\n| 鉴权 | 4 级 RBAC + 激活态鉴权 | 复用；决议动作走仪表盘登录态 | 否 |\n| 前端 | React + MUI + react-router（`App.tsx` 路由） | 新增 `AuthQueue.tsx` 路由 + 2 个 REST 端点 | 否（复用 MUI/react-router） |\n\n**结论：零新增第三方依赖。** 所有能力均建立在既有原语之上。\n\n### 2.2 Feature A — 自主执行闭环（落点拍板：SDK 原语）\n\n- **落点：在 `client-sdk` 新增 `AgentRuntime` 运行时原语**，包裹现有 `AgentClient`。\n - 监听 `onTaskAssigned` → 自动 `updateTaskStatus(in_progress)` → 调宿主注入的 `execute(task)` → `updateTaskStatus(completed, {result})`（异常→`failed`）。\n - `new_message` 指向自己时触发可选 `onSelfMessage` 反应。\n - `execute()` 由宿主实现（WorkBuddy/Hermes 各自注入），Hub 完全不感知执行内容——**Hub 仍是纯协调层**。\n- **为何 SDK 原语而非各宿主自实现**：\n 1. 闭环里最容易出错的「状态机驱动、幂等去重、崩溃恢复、并发上限、防自杀式循环、授权挂起/超时」等护栏是**通用逻辑**，放一处即可被所有宿主复用，避免 WorkBuddy/Hermes 各写一套导致行为不一致。\n 2. **多宿主兼容**：任何新宿主只要 `new AgentRuntime(client, execute)` 一行即可获得自主执行能力；Hub 端零改动。\n 3. 现有 `workbuddy-integration.ts` / `hermes-integration.ts` 已经在 `onTaskAssigned` 里手写这套闭环（见代码第 19–37 / 36–60 行），证明模式成立——本次只是把它抽成可复用原语，并补上缺失的护栏。\n\n### 2.3 Feature B — 操作级人在环授权队列（落点拍板：Hub 侧服务 + SDK 客户端方法）\n\n- **Hub 侧**：新增 `src/authorization.ts` 服务（建表/建请求/决议/过期清扫）+ `src/tools/authorization.ts` 注册 `request_authorization` / `resolve_authorization`(可选 MCP) 工具 + `server.ts` 新增 2 个 REST 端点（供仪表盘）。\n- **SDK 侧**：`AgentClient` 新增 `requestAuthorization(op)`，返回 `Promise`；`routeEvent` 新增 `authorization_requested` / `authorization_resolved` 两个分支，用 `reqId→{resolve,reject}` 映射表 resolve/reject 该 Promise；内置 TTL 超时 reject。\n- **仪表盘侧**：`web/src/components/AuthQueue.tsx` 新面板，轮询 `GET /api/auth-requests?status=pending`，按钮调 `POST /api/auth-requests/:id/resolve`。\n- **关键点**：授权是「操作级、本次具体敏感操作批不批」，与既有「角色级 RBAC」互补——RBAC 管“你能不能调这类工具”，授权队列管“你这次要做的这件具体事放不放行”。\n\n---\n\n## 3. 文件清单（新增 / 修改，相对仓库根）\n\n### Feature A\n| 操作 | 路径 | 说明 |\n|---|---|---|\n| 新增 | `client-sdk/runtime.ts` | `AgentRuntime` 类 + `runAutonomousLoop()` 工厂 + 循环护栏/崩溃恢复 |\n| 修改 | `client-sdk/agent-client.ts` | 新增 `requestAuthorization(op)` 方法；`routeEvent` 增加 `authorization_resolved` 分支（用于解锁 Promise）；`TaskEvent` 字段对齐 |\n| 修改（示例） | `client-sdk/workbuddy-integration.ts` | 用 `AgentRuntime` 改写 `onTaskAssigned`（注入 `executeWorkBuddyTask`） |\n| 修改（示例） | `client-sdk/hermes-integration.ts` | 同上，注入 `executeHermesTask` |\n\n### Feature B\n| 操作 | 路径 | 说明 |\n|---|---|---|\n| 新增 | `src/authorization.ts` | 授权服务：建请求 / 决议 / 过期清扫 / 信任窗口(`auth_grants`) |\n| 新增 | `src/tools/authorization.ts` | 注册 `request_authorization` / `resolve_authorization` / `list_authorization_requests` |\n| 修改 | `src/tools.ts` | `registerTools` 增加 `registerAuthorizationTools(...)` |\n| 修改 | `src/db.ts` | 新增 `auth_requests`（+可选 `auth_grants`）建表与迁移 |\n| 修改 | `src/server.ts` | 新增 REST：`GET /api/auth-requests`、`POST /api/auth-requests/:id/resolve`；SSE 推 `authorization_requested`/`authorization_resolved` |\n| 修改 | `client-sdk/agent-client.ts` | `requestAuthorization()` + `routeEvent` 的 `authorization_requested`/`authorization_resolved` 分支 + Promise 映射 |\n| 新增 | `web/src/components/AuthQueue.tsx` | 「待授权」面板（列表 + 批准/拒绝 + 信任窗口勾选） |\n| 修改 | `web/src/App.tsx` | 增加 `/auth` 路由与侧边栏入口 |\n| 修改 | `web/src/api.ts` | 增加 `fetchAuthRequests()` / `resolveAuthRequest()` |\n\n### 共享\n| 修改 | `src/config`(见 `server.ts` config 对象) | 新增 `AUTH_REQUEST_TTL_MS` / `AUTH_AUTO_APPROVE` / `RUNTIME_MAX_CONCURRENT` / `RUNTIME_LOOP_GUARD_MS` 等环境变量默认值 |\n| 修改 | `src/db.ts`（清理项） | **建议**：将 `assignTask` 推送负载统一为 `{ event: \"task_assigned\", task: {...} }`（与 SSE 补发路径一致），消除 `type` vs `event` 历史不一致（见 §9 / §10）。 |\n\n---\n\n## 4. 数据结构与接口\n\n### 4.1 `AgentRuntime` / `runAutonomousLoop` 接口与生命周期\n\n```ts\n// client-sdk/runtime.ts\nimport { AgentClient, TaskEvent } from \"./agent-client.js\";\n\n/** 敏感操作描述（传入 requestAuthorization） */\nexport interface SensitiveOp {\n type: string; // 操作类目，见 §4.5 共享常量 AUTH_OP_TYPES\n description: string; // 人类可读的“将要做什么”\n payload?: unknown; // 供人类判定的具体参数（JSON 序列化后入库）\n taskId?: string; // 关联任务（可选）\n}\n\nexport interface AgentRuntimeOptions {\n maxConcurrent?: number; // 并发执行上限，默认 4\n requeueIncomplete?: boolean; // 启动时重跑 in_progress/assigned 的崩溃恢复，默认 true\n loopGuard?: { // 防自杀式循环\n windowMs?: number; // 相同 description 重分配的判定窗口，默认 30000\n maxIdentical?: number; // 窗口内最多允许几次，超过则跳过，默认 2\n };\n onSelfMessage?: (msg: MessageEvent) => Promise; // 指向自己的 new_message 可选反应\n onError?: (taskId: string, err: unknown) => void;\n}\n\nexport class AgentRuntime {\n constructor(\n private client: AgentClient,\n private execute: (task: TaskEvent) => Promise, // 宿主注入的执行逻辑\n private opts: AgentRuntimeOptions = {}\n );\n start(): Promise; // 接线 onTaskAssigned / onMessage；可选崩溃恢复重跑\n stop(): void; // 拒绝所有挂起的授权 Promise；停止接收\n /** 在 execute() 内部调用：提交授权请求并挂起，批准后 resolve，拒绝/过期 reject */\n requestAuthorization(op: SensitiveOp): Promise;\n}\n\n/** 便捷工厂 */\nexport function runAutonomousLoop(\n client: AgentClient,\n execute: (task: TaskEvent) => Promise,\n opts?: AgentRuntimeOptions\n): AgentRuntime;\n```\n\n**生命周期（状态）**：`Idle → Starting（接线回调 + 崩溃恢复）→ Running（监听 task_assigned/new_message）→ Stopping（拒绝挂起 Promise）→ Stopped`。\n\n**`handleAssigned(task)` 内部流程（护栏）**：\n1. 若 `task.id` 已在 `inFlight` 集合 → 跳过（幂等去重，防止实时推 + 补发重复执行）。\n2. 若 `loopGuard` 命中（窗口内相同 `description` 重分配超阈值）→ 跳过并 `auditLog('loop_guard_skip', agentId, task.id)`。\n3. 标记 `in_progress`（progress 5）；写入 `inFlight`。\n4. `try { result = await execute(task) }`：\n - 成功 → `updateTaskStatus(completed, result, 100)`。\n - 捕获 `AuthorizationRejected` / `AuthorizationExpired` → `updateTaskStatus(failed, \"授权被拒/过期: \")` + `auditLog`。\n - 其他异常 → `updateTaskStatus(failed, err.message)`。\n5. 从 `inFlight` 移除；若 `inFlight.size >= maxConcurrent` 则不主动拉取更多（Hub 补发/重分配自然节流）。\n\n### 4.2 `auth_requests` 表 Schema（SQL DDL）\n\n```sql\n-- src/db.ts 内新增（CREATE TABLE IF NOT EXISTS，幂等）\nCREATE TABLE IF NOT EXISTS auth_requests (\n id TEXT PRIMARY KEY, -- req__\n agent_id TEXT NOT NULL, -- 请求方 Agent\n task_id TEXT, -- 关联任务（可空）\n op_type TEXT NOT NULL, -- 见 AUTH_OP_TYPES\n op_payload TEXT, -- JSON：具体操作参数，供人类判定\n status TEXT NOT NULL DEFAULT 'pending', -- pending|approved|rejected|expired\n created_at INTEGER NOT NULL,\n expires_at INTEGER NOT NULL, -- created_at + AUTH_REQUEST_TTL_MS\n resolved_by TEXT, -- 决议人（人类操作者 ID / admin）\n resolved_at INTEGER,\n decision_reason TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_auth_status ON auth_requests(status);\nCREATE INDEX IF NOT EXISTS idx_auth_agent ON auth_requests(agent_id);\n\n-- 可选：信任窗口（时间窗口信任粒度，见 §9 决策 3）\nCREATE TABLE IF NOT EXISTS auth_grants (\n id TEXT PRIMARY KEY,\n agent_id TEXT NOT NULL,\n op_category TEXT NOT NULL, -- 类目级信任（如 'external_api'）\n granted_by TEXT NOT NULL,\n granted_at INTEGER NOT NULL,\n expires_at INTEGER NOT NULL\n);\nCREATE INDEX IF NOT EXISTS idx_grant_agent_cat ON auth_grants(agent_id, op_category);\n```\n\n### 4.3 新增 MCP 工具参数 / 返回 Schema\n\n**`request_authorization`**（Agent 经 SDK 调用；`agent_id` 取自 `authed` 上下文）\n\n```\n入参 (zod):\n op_type : enum(AUTH_OP_TYPES) // 必填，操作类目\n description : string // 必填，人类可读\n op_payload : string (JSON).optional() // 具体参数\n task_id : string.optional()\n出参:\n { request_id: string, status: \"pending\" | \"approved\", decision?: \"approved\" }\n说明: 默认创建 pending 行并推 authorization_requested；\n 若开启 AUTH_AUTO_APPROVE 且存在有效 auth_grant 或信任分阈值命中，则直接 approved\n 并推 authorization_resolved（SDK Promise 立即 resolve）。\n```\n\n**`resolve_authorization`**（MCP 版，admin 可选；主路径为 REST，见 §4.4）\n\n```\n入参 (zod):\n request_id : string\n decision : enum(\"approved\",\"rejected\")\n reason : string.optional()\n grant_window_ms?: number // 若批准且填此值 → 建 auth_grants 信任窗口（决策 3 高级项）\n出参:\n { request_id, status, decision }\n```\n\n**`list_authorization_requests`**（仪表盘/调试用，可选）\n\n```\n入参: status?: enum(\"pending\",\"approved\",\"rejected\",\"expired\")\n出参: { requests: AuthRequest[] }\n```\n\n### 4.4 仪表盘 REST 端点（人类操作者主路径）\n\n| 方法 | 路径 | 说明 | 鉴权 |\n|---|---|---|---|\n| `GET` | `/api/auth-requests?status=pending` | 列出待授权（仪表盘轮询，3–5s 一次） | 仪表盘登录态 |\n| `POST` | `/api/auth-requests/:id/resolve` | 批准/拒绝；body `{decision, reason?, grant_window_ms?}` | 仪表盘登录态 |\n\n> 注：仪表盘是浏览器，非 Agent，因此不走 `/events/:agent_id` SSE，采用 REST 轮询（人类 UI 可接受；零轮询约束仅针对 Agent↔Hub）。`authorization_resolved` 仍经 SSE 回推**请求方 Agent** 以解锁其 Promise。\n\n### 4.5 新增 SSE 事件 Payload 结构\n\n```ts\n// authorization_requested —— 推给请求方 Agent（透明记录“已挂起”），仪表盘经 REST 轮询获取\n{\n event: \"authorization_requested\",\n request: {\n id: string; agent_id: string; task_id?: string;\n op_type: string; op_payload?: unknown;\n status: \"pending\"; created_at: number; expires_at: number;\n }\n}\n\n// authorization_resolved —— 推给请求方 Agent（解锁 Promise；必填）\n{\n event: \"authorization_resolved\",\n request_id: string; agent_id: string; task_id?: string;\n decision: \"approved\" | \"rejected\" | \"expired\";\n reason?: string;\n}\n```\n\n### 4.6 类图（Mermaid）\n\n```mermaid\nclassDiagram\n class AgentClient {\n +agentId: string\n +start() Promise~void~\n +stop() void\n +updateTaskStatus(taskId, status, result?, progress?) Promise~any~\n +assignTask(to, desc, ctx?, prio?) Promise~any~\n +requestAuthorization(op: SensitiveOp) Promise~void~\n -routeEvent(data) void\n }\n class AgentRuntime {\n -client: AgentClient\n -execute: (task: TaskEvent) => Promise~string~\n -inFlight: Set~string~\n -maxConcurrent: number\n +start() Promise~void~\n +stop() void\n +requestAuthorization(op: SensitiveOp) Promise~void~\n -handleAssigned(task: TaskEvent) void\n -handleSelfMessage(msg) void\n }\n class SensitiveOp {\n +type: string\n +description: string\n +payload: unknown\n +taskId: string\n }\n class AuthorizationService {\n +createRequest(agentId, op) AuthRequest\n +resolve(reqId, decision, by, reason?, grantMs?) AuthRequest\n +list(status?) AuthRequest[]\n +sweepExpired() void\n }\n class AuthRequest {\n +id: string\n +agent_id: string\n +task_id: string\n +op_type: string\n +op_payload: string\n +status: \"pending\"|\"approved\"|\"rejected\"|\"expired\"\n +created_at: number\n +expires_at: number\n +resolved_by: string\n +resolved_at: number\n }\n class AuthGrant {\n +id: string\n +agent_id: string\n +op_category: string\n +granted_by: string\n +expires_at: number\n }\n\n AgentRuntime \"1\" *-- \"1\" AgentClient : 包裹\n AgentRuntime ..> SensitiveOp : execute 内调用\n AgentClient ..> AuthorizationService : MCP request_authorization\n AuthorizationService \"1\" o-- \"0..*\" AuthRequest : 持久化\n AuthorizationService \"1\" o-- \"0..*\" AuthGrant : 信任窗口\n AuthorizationService ..> AuthRequest : 推 SSE authorization_resolved\n```\n\n---\n\n## 5. 程序调用流程（时序图）\n\n### 5.1 自主 loop 执行流（task_assigned → in_progress → execute → completed）\n\n```mermaid\nsequenceDiagram\n participant Hub as Orchestrator/Hub\n participant SSE as SSE(pushToAgent)\n participant SDK as AgentClient\n participant RT as AgentRuntime\n participant Host as execute()(宿主)\n\n Hub->>SSE: assignTask → pushToAgent(agent, {event:\"task_assigned\", task})\n SSE-->>SDK: SSE data: {event:\"task_assigned\", task}\n SDK->>RT: onTaskAssigned(task) 路由→handleAssigned\n RT->>RT: 去重/loopGuard 校验（inFlight）\n RT->>SDK: updateTaskStatus(task.id, \"in_progress\", _, 5)\n SDK->>Hub: MCP update_task_status\n RT->>Host: result = await execute(task)\n alt 无敏感操作\n Host-->>RT: result string\n RT->>SDK: updateTaskStatus(task.id, \"completed\", result, 100)\n SDK->>Hub: MCP update_task_status\n else execute 内请求授权\n Host->>RT: await requestAuthorization(op)\n Note over RT,Hub: 见 5.2 / 5.3\n RT->>SDK: updateTaskStatus(task.id, \"completed\", result, 100)\n else 执行抛错\n Host-->>RT: throw err\n RT->>SDK: updateTaskStatus(task.id, \"failed\", err.message)\n end\n```\n\n### 5.2 授权请求 → 批准 → 回推（Agent 继续）\n\n```mermaid\nsequenceDiagram\n participant Host as execute()(宿主)\n participant RT as AgentRuntime\n participant SDK as AgentClient\n participant Hub as AuthorizationService\n participant DB as auth_requests\n participant Dash as Web 仪表盘\n\n Host->>RT: await requestAuthorization(op)\n RT->>SDK: requestAuthorization(op)\n SDK->>Hub: MCP request_authorization(op)\n Hub->>DB: INSERT pending (expires_at=now+TTL)\n Hub-->>SDK: {request_id, status:\"pending\"}\n Hub->>Dash: SSE authorization_requested（仪表盘轮询亦可看到）\n Dash->>Dash: 人类在「待授权」面板看到请求\n Dash->>Hub: POST /api/auth-requests/:id/resolve {decision:\"approved\"}\n Hub->>DB: UPDATE → approved + auditLog(\"auth_resolve\", by, reqId, \"approved\")\n Hub->>SDK: SSE authorization_resolved {decision:\"approved\"}\n SDK->>RT: resolve(reqId) → Promise resolve\n RT-->>Host: requestAuthorization 返回（继续）\n Host->>RT: 执行敏感操作 → 返回 result\n RT->>SDK: updateTaskStatus(task.id, \"completed\", result, 100)\n```\n\n### 5.3 授权被拒流（Agent 优雅中止）\n\n```mermaid\nsequenceDiagram\n participant Host as execute()(宿主)\n participant RT as AgentRuntime\n participant SDK as AgentClient\n participant Hub as AuthorizationService\n participant DB as auth_requests\n participant Dash as Web 仪表盘\n\n Host->>RT: await requestAuthorization(op)\n RT->>SDK: requestAuthorization(op)\n SDK->>Hub: MCP request_authorization(op)\n Hub->>DB: INSERT pending\n Dash->>Hub: POST /api/auth-requests/:id/resolve {decision:\"rejected\", reason}\n Hub->>DB: UPDATE → rejected + auditLog(\"auth_resolve\", by, reqId, \"rejected:reason\")\n Hub->>SDK: SSE authorization_resolved {decision:\"rejected\", reason}\n SDK->>RT: reject(reqId, AuthorizationRejected)\n RT-->>Host: requestAuthorization 抛 AuthorizationRejected\n Host->>RT: catch → 不执行该敏感操作\n RT->>SDK: updateTaskStatus(task.id, \"failed\", \"授权被拒: - \")\n Note over RT,Hub: 不重试同操作；任务整体标记 failed；写审计\n```\n\n### 5.4 授权过期流（默认失败即拒绝）\n\n```mermaid\nsequenceDiagram\n participant Timer as sweepExpired(周期)\n participant Hub as AuthorizationService\n participant DB as auth_requests\n participant SDK as AgentClient\n participant RT as AgentRuntime\n\n Timer->>Hub: 扫描 expires_at < now 且 status=pending\n Hub->>DB: UPDATE → expired + auditLog(\"auth_expire\", \"system\", reqId)\n Hub->>SDK: SSE authorization_resolved {decision:\"expired\"}\n SDK->>RT: reject(reqId, AuthorizationExpired)\n RT-->>Host: requestAuthorization 抛 AuthorizationExpired\n RT->>SDK: updateTaskStatus(task.id, \"failed\", \"授权过期未处理: \")\n```\n\n---\n\n## 6. 任务列表（有序、依赖、按 Feature 分组）\n\n实现顺序遵循「先 Hub 数据底座 → 再 SDK 原语 → 再接线 → 最后前端」。Feature A 与 Feature B 在第 1 步（数据/事件底座）之后可并行推进。\n\n| ID | 任务 | Feature | 源文件 | 依赖 | 优先级 |\n|---|---|---|---|---|---|\n| **T1** | 数据底座：新增 `auth_requests`(+`auth_grants`) 表与迁移；统一 `task_assigned` 推送为 `{event, task}`（清理 `type`/`event` 不一致）；补充 config 默认值 | 共享/Hub | `src/db.ts`, `src/orchestrator.ts`, `src/server.ts`(config) | — | P0 |\n| **T2** | Feature A — SDK 运行时原语：`AgentRuntime` + `runAutonomousLoop`，含并发上限、inFlight 去重、崩溃恢复重跑、loopGuard 防自杀循环、可选 `onSelfMessage` | A / SDK | `client-sdk/runtime.ts` | T1（依赖一致事件契约） | P0 |\n| **T3** | Feature B — Hub 授权服务 + MCP 工具：`src/authorization.ts` 服务（建/决/清扫/信任窗口）、`src/tools/authorization.ts` 注册 `request_authorization`/`resolve_authorization`/`list_authorization_requests`、`registerTools` 接线 | B / Hub | `src/authorization.ts`, `src/tools/authorization.ts`, `src/tools.ts` | T1 | P0 |\n| **T4** | Feature B — SDK 客户端方法：`AgentClient.requestAuthorization(op)`（Promise + TTL 超时 reject）、`routeEvent` 新增 `authorization_requested`/`authorization_resolved` 分支与 `reqId→{resolve,reject}` 映射 | B / SDK | `client-sdk/agent-client.ts` | T3（依赖工具契约） | P0 |\n| **T5** | Feature B — Web 仪表盘「待授权」面板：`server.ts` 新增 REST（`GET /api/auth-requests`、`POST /api/auth-requests/:id/resolve`，走登录态）、`AuthQueue.tsx` + `App.tsx` 路由 + `api.ts` 助手 | B / Web | `src/server.ts`, `web/src/components/AuthQueue.tsx`, `web/src/App.tsx`, `web/src/api.ts` | T3 | P1 |\n| **T6** | Feature A — 宿主示例改造：用 `AgentRuntime` 重写 `workbuddy-integration.ts` / `hermes-integration.ts`（注入各自 `execute`，演示 `requestAuthorization` 用法） | A / 示例 | `client-sdk/workbuddy-integration.ts`, `client-sdk/hermes-integration.ts` | T2, T4 | P2（示例，非阻塞） |\n\n**依赖图**：\n\n```mermaid\ngraph TD\n T1[T1 数据底座] --> T2[T2 AgentRuntime]\n T1 --> T3[T3 授权服务+工具]\n T3 --> T4[T4 SDK requestAuthorization]\n T3 --> T5[T5 仪表盘面板]\n T2 --> T6[T6 宿主示例]\n T4 --> T6\n```\n\n---\n\n## 7. 依赖包列表\n\n**目标：零新增依赖。** 全部复用既有栈：\n\n| 包 | 用途 | 状态 |\n|---|---|---|\n| `zod` | MCP 工具入参校验（T3） | 已存在 |\n| `better-sqlite3` | `auth_requests` 持久化（T1） | 已存在 |\n| `@modelcontextprotocol/sdk` | MCP 工具注册（T3） | 已存在 |\n| `express` | REST 端点（T5） | 已存在 |\n| `@mui/material` / `react-router-dom` | 仪表盘面板（T5） | 已存在 |\n| `eventsource` | Node 端 SSE（仅 Hermes 回退，已存在） | 已存在 |\n\n无任何 `npm install` 新增。\n\n---\n\n## 8. 共享知识（跨文件约定）\n\n1. **SSE 事件命名规范**：payload 顶层用 `event` 字段（snake_case），`routeEvent` 按 `data.event` 分支；所有 payload 自动附带 `_hub_event_id`（全局单调 seq）用于去重/重连补发（由 `pushToAgent` 统一注入，无需各模块处理）。\n2. **授权状态枚举**（Hub 与 SDK 必须一致）：`pending | approved | rejected | expired`。SDK 侧 `requestAuthorization` 的 Promise：仅 `approved` resolve；`rejected`/`expired` reject（分别抛 `AuthorizationRejected` / `AuthorizationExpired`）。\n3. **操作类目常量 `AUTH_OP_TYPES`**（Hub 与 SDK 共享一份定义，建议置于 `client-sdk/types.ts` 与 `src/authorization.ts` 同步）：如 `delete_data` / `external_api` / `send_external_email` / `paid_api` / `cross_agent_delete` / `schema_change` / `revoke_token` / `cancel_task`。\n4. **审计哈希链挂授权决策**：每次「建请求」「决议」「过期」均调 `auditLog(action, agentId, target, details)`：\n - `auditLog(\"auth_request\", agentId, request_id, op_type)`\n - `auditLog(\"auth_resolve\", resolved_by, request_id, decision + \"|\" + reason)`\n - `auditLog(\"auth_expire\", \"system\", request_id, op_type)`\n 这样授权决策被锚定进既有防篡改哈希链（`prev_hash`/`record_hash`），可供事后溯源。\n5. **授权 TTL 与环境变量**：`AUTH_REQUEST_TTL_MS`（默认 `600000`=10min）；`AUTH_AUTO_APPROVE`（默认 `false`，见 §9 决策 4）；`RUNTIME_MAX_CONCURRENT`（默认 `4`）；`RUNTIME_LOOP_GUARD_MS`（默认 `30000`）。\n6. **崩溃恢复约定**：`AgentRuntime.start()` 在接线后调用 `client.getTasks('in_progress')` 与 `client.getTasks('assigned')`，对未完成的任务重新入队执行（防 Agent 崩溃后任务卡在 `in_progress`）。\n7. **去重约定**：以 `task.id` 为键维护 `inFlight` 集合；同一任务因「实时推 + 重连补发」被推多次时只执行一次（状态机 `in_progress→in_progress` 非法，也会兜底抛错，故必须前置去重）。\n8. **与 RBAC 的关系**：`request_authorization` 由已认证 Agent（member 即可）调用；**人类批准/拒绝**是真正的 RBAC 敏感动作，走仪表盘登录态（等同现有 `requireAdminApi`/登录守卫）；可选 MCP `resolve_authorization` 限定 admin。信任窗口 `auth_grants` 仅由人类在批准时显式授予。\n\n---\n\n## 9. 待明确事项（5 个产品决策 — 附推荐，需用户确认）\n\n| # | 决策点 | 我的推荐 | 理由 |\n|---|---|---|---|\n| **1** | **loop 落点**：SDK 原语 vs 各宿主自实现 | **SDK 原语 `AgentRuntime`** | 闭环护栏（去重/并发/崩溃恢复/防循环/授权挂起）是通用逻辑，放一处复用，保证多宿主行为一致；Hub 零改动，符合“Hub 是纯协调层”定位。各宿主仅需注入 `execute()`。 |\n| **2** | **什么算敏感操作需授权**（判定规则 + 默认清单） | **判定规则**：宿主 `execute()` 在“将产生外部副作用/不可逆写/花费/跨主体影响”前主动调 `requestAuthorization(op)`；SDK 提供 `SensitiveOpPolicy` 默认策略对象供宿主参考。**默认进队列**：`delete_data`(删记忆/消息/记忆库)、`cancel_task`、`revoke_token`、`cross_agent_delete`(删他人任务/记忆)、`send_external_email`/`external_api`(POST 类外部副作用)、`paid_api`(付费/限额)、`schema_change`(迁移/DDL)。**默认直接放行**：只读查询、Agent 间内部 `send_message`/`assign_task`、`store_memory`、`share_experience`、`recall_memory`。 | 以“外部副作用 + 不可逆 + 花费 + 跨主体”四维度判定，最贴合用户“需要我授权的操作”直觉；读与内部协作默认放行以保流畅。 |\n| **3** | **授权粒度**：单次 / 同类批量信任 / 时间窗口信任 | **默认单次批准**；**时间窗口信任为可选高级项**（批准时勾选“信任该 Agent N 分钟 / 该类操作 N 分钟”→ 写 `auth_grants`）。不推荐“同类批量一次性信任”（粒度粗、易误放）。 | 单次最安全、最可解释；时间窗口满足“重复同类操作别烦我”的体验，且有明确过期边界；批量信任一旦误批风险面大。 |\n| **4** | **授权超时/过期策略** | 默认 **TTL=10min**；过期 → `status=expired` + 推 `authorization_resolved(decision:\"expired\")`；**默认失败即拒绝（deny-by-default），不自动批准**；Agent 侧 Promise reject → 任务标记 `failed`（原因：授权过期）。提供后台 `sweepExpired` 周期清扫。 | 安全默认必须“不响应=不批准”；否则会被沉默滥用。过期仍回推事件，避免 Agent Promise 永久悬挂。 |\n| **5** | **授权被拒后 Agent 行为** | **优雅中止**：`execute()` 捕获 `AuthorizationRejected` → **不执行该敏感操作** → 任务整体 `updateTaskStatus(failed, \"授权被拒: - \")` + `auditLog`；**不自动重试同操作**；可选经 `sendMessage` 向任务发起方回报“因授权被拒未能完成”。 | 与用户“我去授权，不批就别做”一致；整体 failed 让编排层可见且可重派；不重试避免绕过人类。 |\n\n> 上述推荐均可在 `server.ts` 的 `config` 中以环境变量覆盖（如 `AUTH_AUTO_APPROVE=true` 开启信任分快路径，但**默认关闭**以尊重用户意图）。\n\n---\n\n## 10. 风险与权衡\n\n| 风险 | 说明 | 缓解 |\n|---|---|---|\n| **Loop 失控 / 自杀式循环** | 宿主 `execute()` 若无条件地把相同任务再 `assignTask` 给自己，会无限触发 | SDK 内置 `loopGuard`（窗口内相同 `description` 重分配超阈值即跳过并审计）；`maxConcurrent` 限流；`execute()` 为宿主代码，文档明确禁止“自指派相同任务”。Hub 侧 `rateLimiter` 对 MCP 调用兜底。 |\n| **授权 DoS** | 恶意/失常 Agent 高频提交 pending 授权，淹没人类面板 | `request_authorization` 走既有 `rateLimiter`（per-agent）；仪表盘显示待办计数；TTL 自动过期；可选“同 Agent 待办超阈值自动拒绝”。 |\n| **与现有 RBAC 的交互** | 角色级 RBAC 与操作级授权职责重叠/冲突 | 明确分层：RBAC 管“能不能调工具”，授权队列管“这次具体事放不放行”；`request_authorization` member 可调用，批准动作走仪表盘登录态（敏感）。信任分快路径(`AUTH_AUTO_APPROVE`)默认关闭，避免绕过人类。 |\n| **`type` vs `event` 历史不一致** | `assignTask` 现推 `{type:\"task_assigned\", content:...}`，而 SDK `routeEvent` 按 `data.event` 分支、补发路径用 `event` 字段——存在字段名不一致隐患 | T1 中统一 `assignTask` 推送为 `{event:\"task_assigned\", task:{...}}`（与 SSE 补发路径一致），`AgentRuntime` 以 `TaskEvent` 契约消费；SDK 同步对齐。 |\n| **Promise 悬挂 / 泄漏** | Agent 断线或 `stop()` 时，挂起的 `requestAuthorization` Promise 不回收 | `AgentRuntime.stop()` 与 `AgentClient.stop()` 拒绝所有在途 Promise；过期事件 `authorization_resolved(expired)` 保证解锁；`reqId→{resolve,reject}` 映射在决议后立即清理。 |\n| **崩溃后任务卡死** | Agent 在 `in_progress` 中崩溃，任务永久停留 | `start()` 崩溃恢复：重跑 `in_progress`/`assigned` 任务（去重保护防双跑）。 |\n| **多宿主并发** | 同一 Agent 在多个宿主各跑一个 `AgentRuntime` | 每个 `AgentClient` 以 `agentId` 唯一标识，SSE 单连接（重连时旧连接被替换）；`inFlight` 在单进程内，故同一 Agent 只应在一个宿主运行（文档约定；如需多实例再由 Hub 侧 agent 锁保证）。 |\n| **仪表盘轮询开销** | 待授权面板每 3–5s 拉一次 | 人类 UI 量级极小（pending 通常个位数）；列表带 `status=pending` 过滤与索引；不进 Agent 零轮询约束范围。 |\n\n---\n\n## 附：与既有能力的接缝核对（已验证）\n\n- `AgentClient.updateTaskStatus(taskId, \"in_progress\"|\"completed\"|\"failed\", result?, progress?)` —— Feature A 直接复用，状态机由 `orchestrator.ts` 校验（`assigned→in_progress→completed/failed`）。\n- `pushToAgent(agentId, {event, ...})` —— Feature B 的 `authorization_resolved` 直接复用，零轮询。\n- `server.tool(name, desc, zodSchema, authed(ctx, perm, async (ctx,args)=>{}))` —— Feature B 工具按此注册，权限用 `authed` 包裹。\n- `auditLog(action, agentId, target?, details?)` —— 授权决策锚定进哈希链，无需新增审计表。\n- React + MUI + `react-router-dom`（`App.tsx` ``）—— `AuthQueue.tsx` 依同样模式新增 `/auth` 路由。\n\nFile v3.0.25:docs/HOST_INTEGRATION.md\n\n# 宿主接入指南（Host Integration）\n\n> 版本：v3.0.23 ｜ 关联特性：Feature A（AgentRuntime 自主执行闭环）、Feature B（人类在环授权 HITL）\n\n本文说明任意宿主（WorkBuddy / Hermes / 你自己的 Agent）如何接入 **agent-comm-hub**，\n让 Agent 收到任务后**自动**执行并回写结果，无需人工中转。\n\n---\n\n## 1. 核心思想\n\n`AgentRuntime` 只负责**状态机 + 护栏**，不关心宿主如何真正完成任务：\n\n| 职责 | 由谁负责 |\n|------|---------|\n| `in_progress → execute() → completed/failed` 状态机 | `AgentRuntime` |\n| 幂等去重 / 并发上限 / 崩溃恢复 / 防自杀循环 | `AgentRuntime` |\n| 敏感操作授权挂起（Feature B） | `AgentRuntime.requestAuthorization` |\n| **宿主到底怎么干活** | `HostTaskBridge.runTask()` ← 你来实现 |\n\n把所有「宿主专属」的逻辑收敛到 **一个 override 点** `runTask()`，\n进度回报与授权判定由 `AbstractHostTaskBridge` 统一处理。\n\n---\n\n## 2. 最小接入（4 步）\n\n```ts\nimport { AgentClient } from \"../client-sdk/agent-client.js\";\nimport { runAutonomousLoop, type AgentRuntime } from \"../client-sdk/runtime.js\";\nimport { AbstractHostTaskBridge, type ProgressReporter } from \"./adapters/host-task-bridge.js\";\n\n// ① 创建客户端\nconst client = new AgentClient({ agentId: \"my-host\", hubUrl: \"http://localhost:3100\" });\n\n// ② 实现你的执行桥（只写 runTask）\nclass MyBridge extends AbstractHostTaskBridge {\n protected async runTask(task, report: ProgressReporter): Promise {\n report(30, \"解析任务\");\n const out = await myRealExecutor(task); // ← 接入宿主真实能力\n report(90, \"汇总\");\n return JSON.stringify(out);\n }\n}\n\n// ③ 用 AgentRuntime 包裹（runtime 需先声明，供 requestAuth 闭包引用）\nlet runtime: AgentRuntime;\nconst bridge = new MyBridge({ client, requestAuth: (op) => runtime.requestAuthorization(op) });\nruntime = runAutonomousLoop(client, (t) => bridge.execute(t), { maxConcurrent: 4 });\n\n// ④ 启动\nclient.start();\nruntime.start();\n```\n\n---\n\n## 3. `HostTaskBridge` API\n\n### `AbstractHostTaskBridge` 构造函数选项\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `client` | `AgentClient` | 必填，用于回报进度 / 发消息 |\n| `requestAuth` | `(op: SensitiveOp) => Promise` | 必填，转发到 `runtime.requestAuthorization(op)` |\n| `sensitivePattern` | `RegExp` | 可选，命中即走授权流程，默认包含 删除/撤销/付费/revoke/delete/cancel/schema/drop… |\n| `sensitiveOpType` | `string` | 可选，写入 `auth_requests.type`，默认 `\"delete_data\"`（参见 `types.ts` 的 `AUTH_OP_TYPES`） |\n\n### `execute(task)` —— 由 `AgentRuntime` 调用（基类已实现，勿覆盖）\n\n1. 若 `description` 命中 `sensitivePattern` → 调 `requestAuth()` 挂起，等人类批准；\n 拒绝 / 超时抛 `AuthorizationRejected` / `AuthorizationExpired`，任务被标记 `failed`。\n2. 回报 `in_progress @ 10%`。\n3. 调 `runTask(task, report)` 拿到结果字符串 → 返回给 `AgentRuntime` 回写 `completed`。\n\n### `runTask(task, report)` —— 你唯一要实现的钩子\n\n```ts\nprotected abstract runTask(task: TaskEvent, report: ProgressReporter): Promise;\n```\n\n- `task: TaskEvent` —— 任务详情（`id` / `description` / `context` / `priority` …）\n- `report: (progress: number, message?: string) => Promise` —— 在关键阶段回报进度\n- 返回**结果字符串**，将被 Hub 持久化并回传给任务发起方\n\n---\n\n## 4. 接入宿主真实能力的接缝\n\n「宿主到底怎么干活」被抽象为一个统一的 `HostExecutor` 契约（见\n`client-sdk/adapters/host-task-bridge.ts`），由宿主在构造桥时**注入**。\n基座 `AbstractHostTaskBridge` 默认使用 `defaultHostExecutor()`，因此开箱即可真实执行，\n不再是 `setTimeout` 占位。\n\n```ts\nexport interface HostExecutor {\n execute(task: TaskEvent, report: ProgressReporter): Promise;\n}\n```\n\n`runTask()` 只需把任务交给注入的执行器：\n\n```ts\n// client-sdk/workbuddy-integration.ts / hermes-integration.ts\nprotected async runTask(task: TaskEvent, report: ProgressReporter): Promise {\n report(30, \"解析任务并规划\");\n report(50, \"调用宿主执行器\");\n const output = await this.executor.execute(task, report); // ← 真实干活\n report(90, \"汇总结果\");\n return output;\n}\n```\n\n### 开箱即用的参考实现（`client-sdk/adapters/host-executor.ts`）\n\n| 实现 | 触发条件 | 说明 |\n|------|---------|------|\n| `HttpHostExecutor` | 设置了 `HOST_EXEC_ENDPOINT` | POST `{ task }` 到宿主自身暴露的 HTTP 任务端点（适配 Hermes 这类自带 API 的宿主） |\n| `LlmHostExecutor` | 未设置 `HOST_EXEC_ENDPOINT` | 直接调 LLM（Anthropic / OpenAI 兼容），需 `HOST_LLM_API_KEY` |\n\n`defaultHostExecutor()` 的选择优先级：有 `HOST_EXEC_ENDPOINT` → `HttpHostExecutor`，否则 → `LlmHostExecutor`。\n\n### 相关环境变量\n\n| 变量 | 用途 |\n|------|------|\n| `HOST_EXEC_ENDPOINT` | HTTP 执行器端点；设置后即走 HTTP 模式 |\n| `HOST_LLM_PROVIDER` | `anthropic`（默认）/ `openai` |\n| `HOST_LLM_BASE_URL` | LLM 接口地址（不填则用官方默认） |\n| `HOST_LLM_API_KEY` | LLM 调用密钥（必填，否则 `LlmHostExecutor` 抛错） |\n| `HOST_LLM_MODEL` | 模型名（不填则用各 provider 默认值） |\n\n### 自定义执行器\n\n想接入宿主的真实运行时（内部 LLM / MCP 工具 / 脚本引擎），实现 `HostExecutor`\n并在构造桥时传入即可，无需改动基座：\n\n```ts\nconst bridge = new WorkBuddyTaskBridge({\n client,\n requestAuth: (op) => runtime.requestAuthorization(op),\n executor: myCustomExecutor, // 注入你自己的真实能力\n});\n```\n\n> ✅ 当前仓库内的 WorkBuddy / Hermes 接入示例均已切换到 `HostExecutor` 委托，\n> 默认通过 LLM 直接产出结果，真正实现「任务到达 → Agent 自动干活」。\n> 仅在你未配置任何执行器环境变量时，LLM 模式会因缺 `HOST_LLM_API_KEY` 而抛错——届时注入自定义执行器或配置密钥即可。\n\n---\n\n## 5. 授权（Feature B）示例\n\n```ts\n// 无需手写判定 —— AbstractHostTaskBridge 已内置：\n// 命中 sensitivePattern 的任务会自动 requestAuthorization 并挂起，\n// 人类在 Web 端的 AuthQueue 面板批准/拒绝后，任务才继续或中止。\n//\n// 自定义敏感类目示例：\nnew MyBridge({\n client,\n requestAuth: (op) => runtime.requestAuthorization(op),\n sensitivePattern: /发布|deploy|上线|publish/i,\n sensitiveOpType: \"external_api\",\n});\n```\n\n可用 `op.type` 见 `client-sdk/types.ts` 的 `AUTH_OP_TYPES`：\n`delete_data` / `cancel_task` / `revoke_token` / `cross_agent_delete` /\n`send_external_email` / `external_api` / `paid_api` / `schema_change`。\n\n---\n\n## 6. 参考实现\n\n| 文件 | 说明 |\n|------|------|\n| `client-sdk/adapters/host-task-bridge.ts` | `HostTaskBridge` 接口 + `AbstractHostTaskBridge` 基类 |\n| `client-sdk/workbuddy-integration.ts` | WorkBuddy 接入示例（`WorkBuddyTaskBridge`） |\n| `client-sdk/hermes-integration.ts` | Hermes 接入示例（`HermesTaskBridge`） |\n| `client-sdk/runtime.ts` | `AgentRuntime` 与 `runAutonomousLoop` 工厂 |\n| `docs/design/ach-autonomous-loop-hitl-auth.md` | 设计文档（自主闭环 + HITL 授权） |\n\nArchive v3.0.24: 172 files, 438084 bytes\n\nFiles: CONTRIBUTING.md (3614b), dist/client-sdk/adapters/host-executor.d.ts (2541b), dist/client-sdk/adapters/host-executor.js (5770b), dist/client-sdk/adapters/host-task-bridge.d.ts (3943b), dist/client-sdk/adapters/host-task-bridge.js (3551b), dist/client-sdk/agent-client.d.ts (13871b), dist/client-sdk/agent-client.js (35123b), dist/client-sdk/backoff.d.ts (628b), dist/client-sdk/backoff.js (954b), dist/client-sdk/hermes-integration.d.ts (1942b), dist/client-sdk/hermes-integration.js (5245b), dist/client-sdk/runtime.d.ts (3081b), dist/client-sdk/runtime.js (8437b), dist/client-sdk/types.d.ts (1572b), dist/client-sdk/types.js (711b), dist/client-sdk/workbuddy-integration.d.ts (2046b), dist/client-sdk/workbuddy-integration.js (6550b), dist/package.json (1237b), dist/scripts/test-e2e.d.ts (11b), dist/scripts/test-e2e.js (5838b), dist/src/authorization.d.ts (2221b), dist/src/authorization.js (7381b), dist/src/backup.d.ts (513b), dist/src/backup.js (5937b), dist/src/db.d.ts (4508b), dist/src/db.js (47715b), dist/src/dedup.d.ts (2467b), dist/src/dedup.js (8961b), dist/src/errors.d.ts (2029b), dist/src/errors.js (3716b), dist/src/evolution.d.ts (6942b), dist/src/evolution.js (30016b), dist/src/identity.d.ts (4533b), dist/src/identity.js (19638b), dist/src/logger.d.ts (1197b), dist/src/logger.js (2719b), dist/src/memory.d.ts (2547b), dist/src/memory.js (14580b), dist/src/metrics.d.ts (2127b), dist/src/metrics.js (9646b), dist/src/orchestrator.d.ts (9029b), dist/src/orchestrator.js (41885b), dist/src/ratelimit.d.ts (899b), dist/src/ratelimit.js (3609b), dist/src/repo/event-log.d.ts (1050b), dist/src/repo/event-log.js (2101b), dist/src/repo/interfaces.d.ts (3687b), dist/src/repo/interfaces.js (49b), dist/src/repo/sqlite-impl.d.ts (225b), dist/src/repo/sqlite-impl.js (7836b), dist/src/repo/types.d.ts (1021b), dist/src/repo/types.js (116b), dist/src/security.d.ts (5075b), dist/src/security.js (23967b), dist/src/server.d.ts (11b), dist/src/server.js (45639b), dist/src/sse.d.ts (3608b), dist/src/sse.js (9146b), dist/src/state-machine.d.ts (1120b), dist/src/state-machine.js (1373b), dist/src/stdio.d.ts (193b), dist/src/stdio.js (2441b), dist/src/tokenizer.d.ts (1321b), dist/src/tokenizer.js (3450b), dist/src/tools.d.ts (474b), dist/src/tools.js (1216b), dist/src/tools/authorization.d.ts (604b), dist/src/tools/authorization.js (5565b), dist/src/tools/consumed.d.ts (361b), dist/src/tools/consumed.js (5628b), dist/src/tools/evolution.d.ts (660b), dist/src/tools/evolution.js (19322b), dist/src/tools/file.d.ts (348b), dist/src/tools/file.js (7538b), dist/src/tools/identity.d.ts (438b), dist/src/tools/identity.js (12149b), dist/src/tools/memory.d.ts (410b), dist/src/tools/memory.js (13451b), dist/src/tools/message.d.ts (711b), dist/src/tools/message.js (19767b)\n\nFile v3.0.24:SKILL.md\n\n---\nname: agent-comm-hub\ndescription: \"本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板\"\nversion: \"3.0.24\"\ncategory: autonomous-ai-agents\ntriggers:\n - \"agent-comm-hub\"\n - \"AgentCommHub\"\n - \"ACH\"\n - \"agent-comm\"\n - \"agent_comm_hub\"\n - \"通信hub\"\n - \"消息hub\"\n - \"workbuddy\"\n - \"QClaw\"\n - \"send_message\"\n - \"assign_task\"\n---\n\n# Agent Communication Hub\n\n> 多智能体消息转发与上下文共享中间件 — **v3.0.24**\n\n让两个或多个独立 AI 智能体之间实现**实时双向通信**和**上下文自动同步**。基于 MCP 协议 + stdio 模式，消息本地持久化，延迟 < 50ms。\n\n## 架构概览\n\n```\n┌──────────────┐ ┌──────────────────────────────┐ ┌──────────────┐\n│ Agent A │ SSE │ Agent Communication Hub │ SSE │ Agent B │\n│ (Hermes) │◄───────►│ (stdio) │◄───────►│ (WorkBuddy) │\n│ │ MCP │ │ MCP │ │\n└──────────────┘◄───────►│ SQLite WAL + 30 表 │◄───────►└──────────────┘\n │ 58 MCP 工具 + RBAC 权限 │\n │ 上下文暂存 + 建议闭环 │\n └──────────────┬──────────────┘\n │\n SQLite (WAL)\n```\n\n**三层协议**：\n\n| 层 | 协议 | 用途 | 延迟 |\n|----|------|------|------|\n| MCP 工具层 | stdio JSON-RPC | 结构化操作（发消息、分配任务、查状态） | <50ms |\n| SSE 推送层 | Server-Sent Events | 实时事件通知（新消息、新任务、建议确认） | <50ms |\n\n## 快速上手 (5 分钟)\n\n从零到完成第一次 Agent 间通信的编号流程：\n\n### Step 1: 确认 Hub 运行状态\n\n确认 Agent Communication Hub 服务器正在运行。如果通过 stdio 模式接入，检查 MCP 配置是否正确加载：\n\n```\n调用: get_online_agents()\n期望: 返回在线 Agent 列表（至少含自己）\n失败: Hub 未运行 → 先启动 Hub 服务器\n```\n\n**[检查点] 用户确认**：如果 Hub 未运行，询问用户是否要启动 Hub 服务器。\n\n### Step 2: 注册或确认身份\n\n检查自己是否已在 Hub 注册，如果没有则注册：\n\n```\n1. 调用: query_agents(status='all') → 查看所有 Agent\n2. 如果自己的 Agent ID 不在列表中\n → register_agent(invite_code, name, capabilities)\n3. 如果已注册 → 记下自己的 agent_id 供后续使用\n```\n\n**[检查点] 用户确认**：注册新 Agent 需要 invite_code，先问用户是否有可用的邀请码。\n\n### Step 3: 维持在线状态\n\n启动心跳维持在线，确保能接收实时消息推送：\n\n```\n调用: heartbeat(agent_id='你的ID')\n频率: 每 30 秒一次（超过 90 秒无心跳则自动标记为离线）\n```\n\n### Step 4: 检查未读消息\n\n上线后第一时间检查是否有离线期间缓存的消息：\n\n```\n1. 调用: search_messages(query='你的ID', limit=20)\n2. 筛选 status='unread' 的消息\n3. 按时间顺序处理，先 acknowledge_message 确认收到，再回复\n```\n\n**[检查点] 用户确认**：找到未读消息后，逐条向用户摘要汇报，请用户确认如何处理。\n\n### Step 5: 发送第一条消息\n\n向另一个 Agent 发送消息，验证双向通信：\n\n```\n调用: send_message(from='你的ID', to='目标AgentID', content='通信链路确认畅通')\n检查返回: delivered_realtime — true=对方在线, false=对方离线\n```\n\n**[检查点] 用户确认**：发送前向用户确认消息内容和目标 Agent。broadcast_message 必须逐条确认。\n\n### 完整闭环示例\n\n```\n场景：Hub 在线 → 检查 WorkBuddy 是否有未读消息 → 处理并回复\n\n1. get_online_agents() # 确认自己和对方在线\n2. search_messages(limit=10) # 查最近消息\n3. acknowledge_message(msg_id, agent_id) # 标记已读\n4. send_message(to='workbuddy', content='已收到，正在处理') # 回复\n5. mark_consumed(resource=msg_id, action='replied') # 消费水位线\n```\n\n## 核心能力\n\n### 58 个 MCP 工具（当前版本）\n\n#### Identity 身份 (6)\n\n| 工具 | 功能 |\n|------|------|\n| `register_agent` | 注册新 Agent，需提供 HUB_AUTH_TOKEN 认证 |\n| `heartbeat` | Agent 心跳上报，维持在线状态，每 3 次连续心跳记录 +1 |\n| `query_agents` | 查询 Agent 列表，支持状态/角色筛选 |\n| `get_online_agents` | 获取当前在线 Agent 列表 |\n\n#### Message 消息 (5)\n\n| 工具 | 功能 |\n|------|------|\n| `send_message` | Agent 间点对点消息，支持 Markdown，自动去重（sha256） |\n| `broadcast_message` | (需逐条确认后发送) |\n| `acknowledge_message` | 确认已读消息，防止重复出现 |\n| `search_messages` | 全文搜索消息历史 |\n| `batch_acknowledge_messages` | 批量确认消息（1-500 条/次），用于清理消息积压 |\n\n#### File 文件 (3)\n\n| 工具 | 功能 |\n|------|------|\n| `upload_file` | 发送文件附件（Base64，10MB 限制），关联到消息 |\n| `download_file` | 接收附件，返回 Base64 编码内容 |\n| `list_attachments` | 列出附件，支持按消息/Agent 筛选 |\n\n#### Task 任务 (3)\n\n| 工具 | 功能 |\n|------|------|\n| `assign_task` | 创建并分配任务，支持上下文传递 |\n| `update_task_status` | 更新任务状态（inbox→assigned→in_progress→completed/failed） |\n| `get_task_status` | 查询任务详情，含依赖、Pipeline、交接信息 |\n\n#### Context 上下文暂存 (5)\n\n| 工具 | 功能 |\n|------|------|\n| `store_memory` | 临时暂存当前任务参考信息 |\n| `recall_memory` | 检索已暂存的上下文 |\n| `list_memories` | 列出当前 Agent 的暂存条目 |\n| `delete_memory` | 删除暂存条目（仅 creator） |\n| `search_memories` | 检索当前 Agent 的暂存内容 |\n\n#### 经验记录\n\n经验记录和策略管理需特定权限配置。\n\n#### 任务协同\n\n| 工具 | 功能 |\n|------|------|\n| `add_dependency` | 添加任务依赖关系（依赖检查） |\n| `remove_dependency` | 删除任务依赖关系 |\n| `get_task_dependencies` | 查询任务上下游依赖 |\n| `create_parallel_group` | 创建并行任务组（2-10 个任务） |\n| `request_handoff` | 请求任务交接 |\n| `accept_handoff` | 接受任务交接 |\n| `reject_handoff` | 拒绝任务交接（含理由） |\n| `add_quality_gate` | 在 Pipeline 中添加质量门 |\n| `evaluate_quality_gate` | 评估质量门（passed/failed） |\n| `recalculate_trust_scores` | 按调度执行分数维护 |\n| `create_pipeline` | 创建 Pipeline 流水线 |\n| `get_pipeline` | 查询 Pipeline 详情 |\n| `list_pipelines` | 列出 Pipeline |\n| `add_task_to_pipeline` | 向 Pipeline 添加任务 |\n\n#### 运维工具 (4)\n\n| 工具 | 功能 |\n|------|------|\n| `get_db_stats` | 数据库统计信息（表行数、大小、Agent 数等） |\n| `archive_data` | 数据维护工具 |\n| （其余 2 个内部工具） | 权限验证与控制 |\n| （其余 2 个内部工具） | 权限验证与控制 |\n\n#### 消费水位线 (2)\n\n| 工具 | 功能 |\n|------|------|\n| `mark_consumed` | 标记任务/消息为已消费，防止重复处理 |\n| `check_consumed` | 查询资源是否已被消费 |\n\n> 所有工具内置 try-catch + 3 次指数退避重试（100ms → 200ms → 400ms）。v2.4.0 统一错误格式：`HubError` 错误码 + `mcpError()`/`mcpFail()` 标准返回。`check_consumed` 查询失败时降级返回 `consumed=false`（不阻塞业务）。\n\n### 任务状态机\n\n```\ninbox → assigned → [waiting] → in_progress → completed / failed / cancelled\n```\n\n## 用户确认检查点\n\n以下操作必须在执行前暂停，向用户摘要说明并等待确认：\n\n| # | 操作 | 检查点说明 | 风险 |\n|---|------|-----------|------|\n| 1 | **broadcast_message** | 广播消息会发送给多个 Agent，逐条确认内容和接收列表 | 高 |\n| 2 | **assign_task** | 分配任务前确认：描述是否清晰、目标 Agent 是否合适、Priority 正确 | 中 |\n| 3 | **batch_acknowledge_messages** | 批量确认会一次性标记多条消息为已处理，确认不会遗漏重要信息 | 中 |\n| 4 | **create_pipeline** | 创建流水线前确认任务顺序、质量门设置、参与 Agent | 中 |\n| 5 | **add_quality_gate** | 质量门失败会阻塞后续任务，确认评估标准合理 | 高 |\n| 6 | **request_handoff** | 交接任务前确认目标 Agent 有能力接手、理由充分 | 中 |\n| 7 | **archive_data** | 归档操作会移动数据到归档表，确认归档范围和天数 | 高 |\n| 8 | **store_memory(scope='group')** | 写入组内共享记忆前确认内容适当，不会泄露敏感信息 | 中 |\n| 9 | **propose_strategy** | 提议策略前确认内容准确、分类正确、有实际价值 | 低 |\n| 10 | **reject_handoff** | 拒绝交接需提供理由，确认不会导致任务阻塞 | 中 |\n\n> **规则**：LLM 遇到上表操作时，先向用户输出摘要说明，明确询问\"是否继续？\"，得到肯定答复后再执行。用户可随时跳过检查点。\n\n## 数据隔离与安全边界\n\n| 边界 | 实现方式 |\n|------|---------|\n| **接收方校验** | `send_message`/`assign_task` 中的 `to_agent` 必须为已注册 Agent，未注册 Agent 被拒绝 |\n| **Per-Agent 数据隔离** | 每个 Agent 仅可见自身消息、任务和暂存条目；跨 Agent 查询受 4 级权限控制 |\n| **暂存内容保护** | `store_memory` 创建的条目仅 creator 可检索和删除，不会自动暴露给其他 Agent |\n| **经验记录审批** | `share_experience` 提交的记录需经 `full` 权限确认后才对其他 Agent 可见 |\n\n## 接入配置（stdio 模式）\n\n在 MCP 配置文件中添加 Hub 为 stdio 服务器，提供 `HUB_AUTH_TOKEN` 环境变量进行认证。Hub 通过 stdio 传输 MCP 协议，Agent 的 LLM 可直接调用 Hub 工具。**stdio 模式必须设置 HUB_AUTH_TOKEN，缺失将拒绝启动。**\n\n```json\n{\n \"mcpServers\": {\n \"agent-comm-hub\": {\n \"command\": \"node\",\n \"args\": [\"/stdio.js\"],\n \"env\": {\n \"HUB_AUTH_TOKEN\": \"your-connection-key\"\n }\n }\n }\n}\n```\n\n## 资源索引\n\n此 skill 目录下已有 Hub 完整源码，可直接参考：\n\n### 本地源文件\n\n| 文件 | 用途 |\n|------|------|\n| `src/server.ts` | 服务端入口，Express + MCP/SSE 双通道 |\n| `src/tools.ts` | 全部 MCP 工具的 TypeScript 实现 |\n| `src/db.ts` | SQLite WAL 数据库初始化与连接 |\n| `src/identity.ts` | Agent 注册、认证、4 级权限控制 |\n| `src/dedup.ts` | SHA256 消息去重实现 |\n| `src/errors.ts` | HubError 统一错误码（v2.4.0+） |\n| `src/stdio.ts` | Stdio 模式传输层 |\n| `src/sse.ts` | SSE 推送通道 |\n| `src/orchestrator.ts` | 任务编排、Pipeline、质量门 |\n| `src/evolution.ts` | Evolution Engine：策略/经验/信任分 |\n| `src/memory.ts` | 上下文暂存与管理 |\n| `src/security.ts` | 安全验证、CORS、Token 管理 |\n| `src/metrics.ts` | 统计指标收集 |\n| `src/repo/` | 数据访问层（repository pattern） |\n| `package.json` | Node.js 依赖与版本定义 |\n\n### 参考链接\n\n- GitHub 仓库: https://github.com/liuboacean/agent-comm-hub\n- MCP 协议规范: https://spec.modelcontextprotocol.io\n\n## 权限说明（4 级）\n\n| 级别 | 说明 | 可用工具范围 |\n|------|------|----------|\n| **authenticated** | 已认证（HUB_AUTH_TOKEN） | register_agent（初始注册） |\n| **member** | 已注册 Agent | 消息 `send_message`/`acknowledge_message` + 任务 `assign_task`/`get_task_status` |\n| **group_manager** | 并行组管理 | 任务协同 + Pipeline 工具（不含暂存/经验） |\n| **full** | 完整权限 | 全部工具（含运维与建议管理） |\n\n> 部分管理类工具仅特定权限可调用，具体以实际角色配置为准。\n\n> 初始分数 50，公式：`base(50) + verified_capabilities*3 + approved_strategies*2 + positive_feedback*1 - negative_feedback*2`，clamp(0,100)。\n\n## 版本历史\n\n### v3.0.24 — 宿主执行器闭环收口（HostExecutor 注入）\n| 类别 | 内容 | 说明 |\n|------|------|------|\n| 宿主执行 | HostExecutor 契约 + 参考实现 | 新增 `client-sdk/adapters/host-executor.ts`（`LlmHostExecutor` / `HttpHostExecutor` / `defaultHostExecutor()`）；`AbstractHostTaskBridge` 可注入 `executor` |\n| 闭环 | 消灭 setTimeout 占位 | WorkBuddy / Hermes 桥 `runTask()` 委托 `this.executor.execute()`，任务到达即触发宿主真实能力 |\n\n### v3.0.x（安全加固）\n| 类别 | 内容 | 说明 |\n|------|------|------|\n| 权限模型 | fail-closed 权限矩阵 | `checkPermission` 未注册工具默认拒绝；`TOOL_PERMISSIONS` 全量登记，杜绝 fail-open |\n| 认证 | stdio 强制认证 | 缺失 `HUB_AUTH_TOKEN` 直接 `process.exit(1)`，移除 glama-ci admin 兜底 |\n| 角色护栏 | admin 校验 | 9 个 admin 类工具 handler 首行 `requireAdmin(ctx)` |\n| HTTP 中间件 | 分级放行 | `/health`、`/metrics` 仅内网/loopback 或 token 放行；`/dashboard`、`/api/*` 需 token + admin |\n| 审计 | WORM 不可篡改 | 审计日志仅归档不删源，保留 `no_delete` / `no_modify` 触发器 |\n| 数据归属 | 域隔离 | `search_messages` 强制本人收发域；记忆统计按 agent 隔离，admin 才指定他人 |\n| 对象级授权 | assertOwns 中间件 | message/attachment/task 三族工具插入 `assertOwns()` 归属校验（HUB_2004）；`/health` 收敛（删除内网 IP/路径泄露） |\n| sender 校验 | send_message 身份守卫 | broadcast_message + send_message 均强制 `from === ctx.agentId`，杜绝身份伪造 |\n| memory 降级 | search_memories 补 agent_id 过滤 | FTS5 离线回退 SQL 增加 `agent_id = ?`，防止越权泄漏 |\n| 内部函数 | setAgentRole/updateAgentTrustScore 加 admin 校验 | 底层函数不再信任 `operatorId`，显式查库验证 admin 身份 |\n| SQL 修复 | registerCapability 占位符 | 6→7 个占位符匹配实际 7 个字段值，修复运行时崩溃 |\n| triggers 收窄 | SKILL.md 触发词 | 移除 `Hub`/`通信`/`消息` 过宽泛触发词，改用具体标识\n\n### v2.4.0\n| Phase | 内容 | 变更 |\n|-------|------|------|\n| **A** | tools.ts 拆分 | 2687 行 → 8 模块 + 30 行入口 + utils.ts |\n| **B** | 单元测试 | 100 用例，role-control >= 70% / dedup branches>=60, functions>=70 / utils 100% |\n| **C** | CI/CD | GitHub Actions：typecheck + test + coverage 3 Jobs |\n| **D** | 类型健壮 | any 归零 + HubError 统一错误码 + MCP 返回格式标准化 |\n\n## 踩坑经验速查\n\n| # | 场景 | 要点 |\n|---|------|------|\n| 1 | MCP 多 Client | 必须用 Stateless 模式，Stateful 只允许一个 Client |\n| 2 | MCP Accept Header | 必须带 `Accept: application/json, text/event-stream` |\n| 3 | MCP 响应格式 | SDK 返回 SSE 格式（`data: {...}`），不是纯 JSON |\n| 4 | ESM 兼容 | 不能用 `require()`，用 `import()` 动态导入 |\n| 5 | UTF-8 块读取 | httpx `resp.read(1)` 会截断多字节字符，用 `read(4096)` |\n| 6 | SSE 心跳 | 10 秒间隔，服务端发 `: ping` |\n| 7 | MCP != SSE | MCP 是工具调用通道（Agent→Hub），SSE 是推送通道（Hub→Agent） |\n| 8 | 离线补发 | 消息/任务存 SQLite，上线后 SSE 自动批量推送 |\n| 9 | stdio 模式 | 所有日志走 stderr，stdout 保留给 JSON-RPC |\n| 10 | better-sqlite3 boolean | 绑定参数必须用 1/0，不能用 true/false |\n| 11 | HubError 错误码 | v2.4.0 统一用 mcpError()/mcpFail()，不要手动构造错误响应 |\n\n## 安全配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `HUB_AUTH_TOKEN` | stdio / REST 模式认证 Token，所有 Agent 接入必须提供，用于身份认证与消息完整性校验 |\n| 4 级权限模型 | authenticated → member → group_manager → full，逐级授权 |\n| CORS 白名单 | 默认拒绝跨域，通过 `CORS_LIST` 显式配置允许的来源 |\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `HUB_AUTH_TOKEN` | — | stdio / REST 认证 Token（必填） |\n| `DB_PATH` | ./comm_hub.db | SQLite 数据库路径 |\n| `LOG_LEVEL` | info | 日志级别：debug / info / warn / error |\n| `CORS_LIST` | (空) | CORS 白名单（逗号分隔），空=拒绝所有跨域 |\n\n## 技术依赖\n\n**Hub 服务器**：\n- Node.js 18+\n- @modelcontextprotocol/sdk ^1.10.2（支持 StdioServerTransport）\n- express ^4.19\n- better-sqlite3 ^11.9\n- zod ^3.23\n\n**Python 客户端（零外部依赖）**：\n- Python 3.9+（纯标准库：http.client / json / asyncio）\n\nFile v3.0.24:README.md\n\n

\n \n \n \"Node.js\n \n \"Python\n \"MCP\n \"288\n \"Zero\n \"Web\n \n \"CI\"\n \n \"MIT\n \n \"PyPI\"\n \n \n \"npm\"\n \n \n \"Glama\n \n \n \"Available\n \n

\n\n

\n 🤖 Agent Communication Hub\n

\n

\n 让 AI Agent 不再各自为战
\n 实时消息 · 任务调度 · 共享记忆 · 信任进化 · Web 仪表盘
\n 58 个 MCP 工具 · 零外部服务 · 5 分钟部署\n

\n\n

\n 中文 · English\n · GitHub\n

\n\n
\n\n---\n\n## 👀 一眼看明白\n\n```mermaid\ngraph LR\n A[Claude Code] <--> H((ACH Hub))\n B[WorkBuddy] <--> H\n C[OpenClaw] <--> H\n D[自定义 Agent] <--> H\n H --> DB[(SQLite)]\n H --> Web[Web 仪表盘]\n style H fill:#4f46e5,color:#fff\n style Web fill:#7c3aed,color:#fff\n```\n\n**任何 MCP 兼容的 AI Agent** → 连接 Hub → 立即获得：消息总线、任务队列、共享记忆、进化引擎。\n\n> 🚀 **5 分钟启动**：`docker run -d -p 3100:3100 ghcr.io/liuboacean/agent-comm-hub`\n\n---\n\n## 💡 为什么需要它？\n\n多个 AI Agent（Claude Code、WorkBuddy、OpenClaw、Hermes 等）天然是**信息孤岛**：\n\n| 问题 | 传统方案 | 为什么不行 |\n|------|---------|-----------|\n| ❌ Agent 间无法通信 | Webhook / 共享文件 | 脆弱、不可靠、手动维护 |\n| ❌ 无法跨 Agent 调度任务 | 各自为战 | 没人协调，任务丢失 |\n| ❌ 无法共享上下文 | 每轮对话都从零开始 | 记不住团队经验 |\n| ❌ 无法团队进化 | 每个 Agent 独自踩坑 | 同样的问题反复修 |\n\n**Agent Communication Hub（ACH）** 是它们的**共享神经中枢**——一条消息总线 + 任务调度器 + 团队记忆库 + 经验进化引擎。\n\n---\n\n## 🚀 三步上手\n\n```bash\n# 0. 安装 Python SDK（可选）\npip install agent-comm-hub\n\n# 1. 启动 Hub（一行命令）\ndocker run -d -p 3100:3100 --name ach ghcr.io/liuboacean/agent-comm-hub\n\n# 2. 注册 Agent\npython3 -c \"\nfrom hub_client import SynergyHubClient\nhub = SynergyHubClient('http://localhost:3100')\nresult = hub.register(invite_code='INVITE-001', name='my-agent')\nhub.set_token(result['api_token'])\nprint(f'✅ Agent 注册成功，ID: {result[\\\"agent_id\\\"]}')\n\"\n\n# 3. 发条消息试试\npython3 -c \"\nfrom hub_client import SynergyHubClient\nhub = SynergyHubClient('http://localhost:3100')\nhub.set_token('your-token')\nhub.send_message(to='other-agent', content='收到，任务完成。')\nprint('✅ 消息已发送')\n\"\n```\n\n> 🔗 然后打开 **http://localhost:3100/dashboard** 查看实时仪表盘\n\n---\n\n## ✨ 核心能力\n\n### 📊 数据快照\n\n| 指标 | 值 |\n|------|:--:|\n| MCP 工具 | **58 个** |\n| Python SDK 方法 | **68 个** |\n| TypeScript SDK 方法 | **35 个** |\n| 单元测试 | **288 个 ✅** |\n| 数据库表 | **32 张** |\n| client-sdk 运行时依赖 | **0（Python/TS 纯标准库）** |\n| 服务端运行时依赖 | **5 个轻量依赖**（express / better-sqlite3 / zod / eventsource / @modelcontextprotocol/sdk） |\n| 消息延迟 | **< 50ms** |\n| 部署方式 | Docker / npm / SkillHub |\n\n### 🧩 功能矩阵\n\n| 类别 | 工具 | 一句话 |\n|------|------|--------|\n| 🔐 **身份认证** | 6 | 注册 / 心跳 / RBAC / 信任评分 |\n| 💬 **消息通信** | 5 | P2P / 广播 / FTS5 搜索 / 去重 |\n| 📋 **任务调度** | 8 | 7 状态机 / Pipeline / 并行组 |\n| 🧠 **共享记忆** | 5 | 三级作用域（私密/团队/全局）|\n| 🔀 **编排协调** | 11 | 依赖链 / 质检门 / 任务交接 |\n| 📈 **进化引擎** | 12 | 经验共享 / 策略审批 / 信任闭环 |\n| 🛡️ **安全审计** | 6 | 哈希链审计 / 4 级 RBAC / CORS |\n| 📎 **文件传输** | 3 | 上传 / 下载 / 列表 |\n| 🔧 **高可用** | 3 | DB 分裂检测 / 自动合并 / 看门狗 |\n\n---\n\n## 🖥️ 内置 Web 管理面板\n\n启动 Hub 后打开 **http://localhost:3100/dashboard**，即可实时管理你的 Agent 集群：\n\n| 页面 | 能干什么 |\n|------|---------|\n| **总览仪表盘** | 一眼看清在线 Agent、Pipeline 状态、消息吞吐 |\n| **Agents** | 查看所有 Agent 列表（名称、角色、最后活跃时间、信任分）|\n| **消息吞吐** | 5 分钟消息量 + 被限流的 Agent Top |\n| **健康检查** | 版本 / 运行时间 / DB 状态 / 备份状态（本地 + 远程）|\n| **审计日志** | 全量操作追溯，谁在什么时候做了什么 |\n\n> 纯静态 HTML（零前端框架），内联 CSS+JS，启动即用。\n\n---\n\n## 🏗️ 架构\n\n```\n ┌─────────────────────────────────┐\n │ Agent Communication Hub │\n │ localhost:3100 │\n │ │\n ┌─────────┐ SSE/MCP │ ┌──────┐ ┌──────┐ ┌────────┐ │ SSE/MCP ┌─────────┐\n │ Claude │◄─────────►│ │Auth │ │Msg │ │Memory │ │◄─────────►│WorkBuddy│\n │ Code │ │ │RBAC │ │Bus │ │FTS5 │ │ │ │\n └─────────┘ │ └──────┘ └──────┘ └────────┘ │ └─────────┘\n │ ┌──────┐ ┌──────┐ ┌────────┐ │\n ┌─────────┐ │ │Task │ │Orch │ │Evol │ │ ┌─────────┐\n │OpenClaw │◄─────────►│ │Sched │ │Str │ │Engine │ │◄─────────►│ Hermes │\n └─────────┘ │ └──────┘ └──────┘ └────────┘ │ └─────────┘\n └────────────┬────────────────────┘\n │\n ┌──────▼──────┐ ┌─────────────┐\n │ SQLite │ │ Web Panel │\n │ (WAL 模式) │ │ /dashboard │\n └─────────────┘ └─────────────┘\n```\n\n---\n\n## 🔧 SDK 快速上手\n\n### Python — 零外部依赖\n\n```python\nfrom hub_client import SynergyHubClient\n\nhub = SynergyHubClient(hub_url=\"http://localhost:3100\", agent_id=\"my-agent\")\nhub.set_token(\"your-api-token\")\n\nhub.send_message(to=\"other-agent\", content=\"任务完成，交接。\") # 发消息\nhub.store_memory(content=\"用户偏好 JSON\", scope=\"collective\") # 存记忆\ntask = hub.create_task(title=\"评审 PR #42\", assignee=\"claude-code\") # 派任务\nhub.share_experience(title=\"修复方案\", content=\"...\", category=\"debug\") # 分享经验\nhub.on_message = lambda msg: print(f\"收到: {msg}\")\nhub.connect_sse() # 实时监听\n```\n\n### TypeScript — 零外部依赖\n\n```typescript\nimport { AgentClient } from \"./client-sdk/agent-client.js\";\n\nconst client = new AgentClient({\n agentId: \"my-agent\",\n hubUrl: \"http://localhost:3100\",\n token: \"your-api-token\",\n onMessage: async (msg) => { /* 处理消息 */ },\n onTaskAssigned: async (task) => { /* 处理任务 */ },\n});\nawait client.start();\nawait client.sendMessage({ to: \"other-agent\", content: \"搞定了！\" });\n```\n\n---\n\n## 🆚 对比其他方案\n\n| 特性 | ACH | 自建 Webhook | 共享数据库 | 消息队列(RabbitMQ) |\n|------|:---:|:-----------:|:----------:|:-----------------:|\n| 5 分钟部署 | ✅ | ❌ | ❌ | ❌ |\n| MCP 原生支持 | ✅ | ❌ | ❌ | ❌ |\n| 共享记忆 + FTS5 搜索 | ✅ | ❌ | ❌ | ❌ |\n| 任务调度 + Pipeline | ✅ | ❌ | ❌ | ❌ |\n| 进化引擎（经验复用） | ✅ | ❌ | ❌ | ❌ |\n| 内置 Web 面板 | ✅ | ❌ | ❌ | ❌ |\n| 审计哈希链 | ✅ | ❌ | ❌ | ❌ |\n| 零外部服务 | ✅ | ✅ | ✅ | ❌ |\n| Python + TS SDK | ✅ | ❌ | ❌ | ❌ |\n\n---\n\n## 📦 部署方式\n\n### 🐳 Docker（推荐，一键启动）\n\n```bash\ndocker run -d -p 3100:3100 --name ach ghcr.io/liuboacean/agent-comm-hub\n```\n\n### 📦 Docker Compose（含 Prometheus + Grafana 监控）\n\n```bash\ncd deploy/\ndocker compose up -d\n# Hub: http://localhost:3100 | Grafana: http://localhost:3000 (admin/admin)\n```\n\n### 🔧 源码安装\n\n```bash\ngit clone https://github.com/liuboacean/agent-comm-hub.git\ncd agent-comm-hub\nnpm install && npm run build\nnpm start # 生产模式\n# 或 npm run dev # 开发模式\n```\n\n### 🎯 作为 Skill 安装\n\n```bash\n# ClawHub\nclaw install agent-comm-hub\n\n# SkillHub（30+ 平台）\nskillhub install agent-comm-hub\n```\n\n---\n\n## ⚠️ Node 版本要求（重要）\n\n本项目依赖原生模块 **`better-sqlite3`，它是按 Node 22（NODE_MODULE_VERSION 127）编译的**。因此：\n\n- 🔒 **运行 Hub（`dist/src/server.js` 或 `dist/src/stdio.js`）必须用 Node 22 启动**。若使用 Node 24（或更高），会因 ABI 不匹配立即抛出 `ERR_DLOPEN_FAILED` 崩溃，无法启动。\n- 🧪 **CI 中的 Node 24 仅用于跑单元测试**（且涉及 stdio 启动的冒烟用例已条件化 `skip`）。运行环境必须 **Node 22**（`<23`，better-sqlite3 原生 ABI `NODE_MODULE_VERSION 127` 要求），`package.json` 的 `engines.node` 即声明为 `\">=22 <23\"`。**不要用 Node 24 跑服务**，否则 `better-sqlite3` 会因 ABI 不匹配报 `ERR_DLOPEN_FAILED` 启动崩溃。\n- ✅ **推荐做法**：用版本管理器固定 Node 22（如 `nvm use 22`），或在启动脚本/hub 配置中显式写死 Node 22 二进制绝对路径。\n\n---\n\n## 🔌 给 Agent 配置 MCP\n\n### Stdio（推荐）\n```json\n{\n \"mcpServers\": {\n \"agent-comm-hub\": {\n \"command\": \"/path/to/node22/bin/node\",\n \"args\": [\"dist/src/stdio.js\"],\n \"env\": { \"HUB_AUTH_TOKEN\": \"your-key\", \"DB_PATH\": \"./comm_hub.db\" }\n }\n }\n}\n```\n\n> ⚠️ **必须用 Node 22 二进制启动**（例如绝对路径 `/path/to/node22/bin/node`），**不要**用 Node 24。本项目原生模块 `better-sqlite3` 是按 Node 22（NODE_MODULE_VERSION 127）编译的，使用 Node 24 启动 `dist/src/stdio.js` 或 `dist/src/server.js` 会立即 `ERR_DLOPEN_FAILED` ABI 崩溃。\n\n### HTTP + SSE\n```json\n{\n \"mcpServers\": {\n \"agent-comm-hub\": { \"url\": \"http://localhost:3100/mcp\" }\n }\n}\n```\n\n---\n\n## 🛡️ 安全体系\n\n| 层级 | 措施 |\n|:----|------|\n| **认证** | Token + SHA-256 哈希存储，原始 Token 不落盘 |\n| **授权** | 4 级 RBAC：public → member → group_admin → admin |\n| **审计** | 区块链式哈希链 `prev_hash → record_hash`，DB 触发器保障 |\n| **信任** | 自动评分，0-100 分影响策略审批等级 |\n| **网络** | CORS 白名单制 / X-Frame-Options / CSP / HSTS |\n\n---\n\n## 📁 项目结构\n\n```\nagent-comm-hub/\n├── web/dist/index.html # Web 管理面板（零前端框架）\n├── src/ # 核心源码（TypeScript）\n│ ├── server.ts # Express + SSE + MCP 入口\n│ ├── db.ts # SQLite WAL 数据库\n│ ├── backup.ts # 自动备份模块\n│ ├── identity.ts # 注册 / 心跳 / RBAC\n│ ├── memory.ts # 三级记忆 + FTS5 搜索\n│ ├── orchestrator.ts # 依赖链 / Pipeline\n│ ├── evolution.ts # 经验共享 / 策略审批\n│ └── security.ts # Token / 审计 / CORS\n├── client-sdk/\n│ ├── hub_client.py # Python SDK（68 方法，零依赖）\n│ └── agent-client.ts # TypeScript SDK（35 方法）\n├── deploy/ # Docker Compose + 监控\n├── tests/ # 288 个测试\n└── docs/ # 完整文档\n```\n\n---\n\n## 📚 文档导航\n\n| 文档 | 适合谁 |\n|------|--------|\n| [API 参考](docs/API_REFERENCE.md) | 开发者（HTTP/SSE/MCP 端点 + Bearer 鉴权） |\n| [编排指南](docs/advanced-orchestration-guide.md) | 搭 Pipeline 高级玩家 |\n| 进化引擎指南 | 实验性，欢迎 PR（计划从 A 层 `evolution-guide.md` 同步） |\n| Hermes 集成指南 | 实验性，欢迎 PR（计划从 A 层 `hermes-integration-guide.md` 同步） |\n| [DB 三层防护](docs/hub-db-split-three-layer-protection.md) | 运维/稳定性保障 |\n| [English README](docs/README_EN.md) | English speakers |\n\n> 📌 **文档同步说明（B 层为权威源）**：服务端仓库（`agent-comm-hub-src`）是文档的单一权威来源。当前 `package.json` 的 `docs:sync` 脚本依赖 `scripts/sync-docs.ts`，**该文件尚未提供**，因此 A 层 Skill 分发包（`~/.workbuddy/skills/agent-comm-hub/`）需**手动同步**：将本仓库的 `docs/`、`SKILL.md`、`README.md` 复制到 A 层对应位置。后续若补充 `scripts/sync-docs.ts`，可用 `npm run docs:sync` 自动同步。\n\n---\n\n## 🆕 更新历史\n\n
\nv3.0.24 (2026-08-14) — 宿主执行器闭环收口（HostExecutor 注入）\n\n- ⚡ **真实宿主执行器（HostExecutor）** — 新增 `client-sdk/adapters/host-executor.ts`，提供 `LlmHostExecutor` / `HttpHostExecutor` 参考实现，`defaultHostExecutor()` 按环境变量自动选择；`AbstractHostTaskBridge` 新增可注入 `executor` 字段\n- 🔧 **消灭 setTimeout 占位** — WorkBuddy / Hermes 桥 `runTask()` 委托 `this.executor.execute()`，任务到达即触发宿主真实能力，自主执行闭环真正打通\n- 📝 **文档** — `docs/HOST_INTEGRATION.md` §4 重写，含 HostExecutor 注入模型与自定义执行器示例\n\n
\n\n
\nv3.0.23 (2026-08-14) — Agent 自主执行闭环 + 人在环授权\n\n- 🤖 **Feature A：Agent 自主执行闭环** — 新增 `AgentRuntime`（client-sdk/runtime.ts），自动驱动 `in_progress → execute() → completed/failed`，含 inFlight 去重 / 崩溃恢复 / loopGuard，消灭人工「传话」\n- 🔐 **Feature B：人在环授权队列** — 新增操作级授权（`auth_requests` 表 + `request_authorization`/`resolve_authorization` 工具，deny-by-default，TTL 10min）+ Web `AuthQueue` 面板，敏感操作一键批准/拒绝\n- 🧹 **清理陈旧产物** — 移除 `client-sdk/` 下 3 个 5 月旧编译 `.js`（`agent-client.js` / `hermes-integration.js` / `workbuddy-integration.js`）及其 `.map`，修正 `client-sdk/package.json` 入口引用\n\n
\n\n
\nv3.0.22 (2026-07-23) — 在线状态 / 审计归档 / 备份路径\n\n- 🟢 **在线状态统一判定** — 新增 `isAgentOnline()` =（存在 SSE 实时连接）**或**（心跳 90s 内）；`get_online_agents`、派单候选排序、`/health/detailed`、`/api/agents`、指标全部改用统一判定，SSE 连着即在线、可派单\n- 💓 **心跳监控不再误杀 SSE 在线 Agent** — 仍有 SSE 连接的 Agent 不因心跳陈旧误标离线、不再广播离线通知；SSE 连接建立即同步 `agents.status`\n- 🗂️ **`audit_log` 行数上限自动归档** — 超 `AUDIT_LOG_MAX_ROWS`（默认 3000，env 可调）自动将最旧溢出行**镜像**到 `audit_log_archive`（WORM 安全，不删源表）；新增启动即跑 + 每小时维护调度器\n- 📦 **备份路径稳定化** — `backup.ts` 的 `BACKUP_DIR` 由 `process.cwd()/backups`（易失 workspace）改为 `~/agent-comm-hub/backups`，与 launchd 备份脚本同目录，支持 `BACKUP_DIR` 覆盖\n\n
\n\n
\nv3.0.21 (2026-07-23) — 安全加固（稳定性 / 安全 / 质量）\n\n- 🔌 **P1-1 SSE 重连竞态** — `registerClient`/`removeClient` 增连接级 `connId` 校验，旧 socket 的 `close` 不再误删当前实时连接，重连后消息/任务不再静默丢失\n- 💾 **P1-2 并发写 `SQLITE_BUSY`** — `busy_timeout=5000` + `foreign_keys` + WAL 自动检查点，消除并发写静默丢数据\n- 🛡️ **P1-3 限流绕过** — 认证前置单 IP / 全局限流（防令牌爆破与未认证 `/mcp` 耗尽资源）；`/mcp` 增并发在途上限（默认 50）防 DoS\n- 🔍 **P1-4/5 FTS 值碰撞** — `memories_fts` 增 `memory_id` 精确关联键（启动迁移旧表），内容相同的两条记忆不再互相串台\n- 🔐 **P2 质量** — 信任分按 `target` 列计吊销（管理员不再误扣）；受保护端点仅接受 `Bearer`，移除 `?token=` 与 `x-api-key` 令牌泄漏面\n\n
\n\n
\nv3.0.20 (2026-07-23) — 构建产物固化\n\n- 🏗️ **构建产物固化** — `dist/package.json` 生成写入 `build` 脚本与启动脚本，消除「安装即崩溃」（`version.ts` 启动依赖 `../package.json`）\n\n
\n\n
\nv3.0.19 (2026-07-21) — 文档与版本一致性修复\n\n- 📝 **文档工具数统一为 58** — 与 `src/security.ts` 的 `TOOL_PERMISSIONS` 矩阵一致，修正 README/SKILL.md 残留的 56/53\n- 📚 **新建 `docs/API_REFERENCE.md`** — 准确的 HTTP/SSE/MCP 端点速查（含 Bearer 鉴权与 SSE `Last-Event-ID` 断线重连）；修正 README 三处死链\n- 🏷️ **SKILL.md 文件传输工具名更正** — `send_file`/`receive_file` → `upload_file`/`download_file`\n\n
\n\n
\nv3.0.18 (2026-07-14) — 安全加固集（ClawScan 67 findings + IDOR）\n\n- 🔒 **修复 ClawScan 审计 67 findings** — fail-closed 权限矩阵 + stdio 强制认证\n- 🛡️ **IDOR 对象级授权加固** — `assertOwns` + `HUB_2004` 防越权访问\n- 🧩 **版本单一真相源** — 抽离 `src/version.ts`；`/health` 收敛\n\n
\n\n
\nv3.0.12 (2026-07-08) — README 同步 + 测试卫生\n\n- 📄 **同步中英文 README** — 对齐 v2.5.1（Node 22 约束锁定 + 测试计数）\n- 🧹 **测试卫生** — 修复 unit 测试在仓库根生成 `undefined*` 游离文件\n\n
\n\n
\nv2.5.1 (2026-07-08) — 稳定性修复 + Node 22 约束锁定\n\n- 🐛 **`get_db_stats` 修复** — ESM 模块误用 `require(\"fs\")` 导致 `require is not defined`，改 `import * as fs`\n- 🔄 **DB 路径容错** — `resolveDbPath` 新增空库自动回退，修复误连空库导致的记忆库/进化引擎\"数据归零\"假象\n- 🔒 **Node 22 锁定** — 启动脚本固定 Node 22，匹配 better-sqlite3 原生模块（Node 24 会 ABI 崩溃）\n- 🧪 **防护测试** — 新增 stdio/Hub 必须用 Node 22 的契约测试，防止被误改回 Node 24\n- 🧹 **测试卫生** — 修复 unit 测试在仓库根生成 `undefined*` 游离文件（`isValidDbPath` 守卫）\n\n
\n\n
\nv2.5.0 (2026-07-07) — Web 管理面板 + 备份模块\n\n- 🖥️ **Web 管理面板** — 纯静态 HTML 仪表盘，6 个实时页面\n- 🔄 **在线状态改进** — 二元标签 → 最后活跃时间，不再跳变\n- 📦 **备份模块** — 本地 + 远程 rsync 备份状态展示\n- ⏱️ **持久化运行时间** — 重启不归零\n- 📊 **新增 API** — `GET /api/agents`\n- 🔧 **`.gitignore` 清理** — 移除已跟踪的编译产物\n\n
\n\n
\nv2.4.7 (2026-06-09) — 标签分词修复 + 全链路日志\n\n- 🔍 FTS5 标签分词修复（空格拼接替代 JSON）\n- 📊 12 处静默吞异常 → logError 全链路可观测\n- 🔐 `authed()` 统一认证中间件重构\n\n
\n\n
\nv2.4.6 (2026-06-09) — FTS5 索引守护 + 外部化路径\n\n- 🔒 FTS5 索引每次存储后自动校验\n- 🛣️ 支持 `HUB_ROOT` 环境变量\n- 📨 新增 `generate_invite` 邀请码工具\n- 🧪 新增 19 个测试用例\n\n
\n\n---\n\n## 🤝 参与贡献\n\n- 🐛 发现 bug → [提 Issue](https://github.com/liuboacean/agent-comm-hub/issues)\n- ✨ 有新想法 → [Feature Request](https://github.com/liuboacean/agent-comm-hub/issues)\n- 📖 改进文档 → PR 欢迎\n- 🔧 贡献代码 → Fork + PR\n\n---\n\n## 📄 许可证\n\nMIT — 可自由用于个人和商业项目。\n\n---\n\n

\n 基于 MCP 协议 + SSE · 零外部服务 · 零厂商锁定
\n 让每一个 AI Agent 都拥有团队协作能力 🤖✨\n

\n\nFile v3.0.24:_meta.json\n\n{\n \"ownerId\": \"kn73qbrbqs4s8t2nh8pm22wxbd84vm7r\",\n \"slug\": \"agent-comm-hub\",\n \"version\": \"3.0.24\",\n \"publishedAt\": 1787003062463\n}\n\nFile v3.0.24:CONTRIBUTING.md\n\n# Contributing to Agent Communication Hub\n\nThank you for your interest in contributing! This project is the shared nervous system for multi-agent AI infrastructure — every improvement benefits every agent that runs on the Hub.\n\n---\n\n## Ways to Contribute\n\n- 🐛 **Report bugs** — Open an issue with the bug report template\n- ✨ **Feature requests** — Open an issue with the feature request template\n- 📖 **Improve docs** — Submit a PR to fix typos, add examples, or translate\n- 🔧 **Code contributions** — Fix bugs, add tools, improve SDKs\n- 🧪 **Add tests** — Increase test coverage for untested modules\n- 📣 **Share the project** — Star the repo, write about it, tell a friend\n\n---\n\n## Development Setup\n\n### Prerequisites\n\n- Node.js 18+ (for Hub server)\n- Python 3.9+ (for Python SDK)\n- SQLite 3 (usually pre-installed)\n\n### Install dependencies\n\n```bash\ngit clone https://github.com/liuboacean/agent-comm-hub.git\ncd agent-comm-hub\nnpm install\nnpm run build\n```\n\n### Start the Hub\n\n```bash\nnpm start\n# or for development with hot reload:\nnpm run dev\n```\n\n### Run tests\n\n```bash\n# Unit tests with coverage\nnpm run test:unit\n\n# End-to-end tests (requires Hub running)\nnpm run test:e2e\n```\n\n### Code style\n\n- TypeScript: follow the project's `tsconfig.json` settings\n- Python: follow PEP 8 (max line length 120)\n- Commit messages: use [Conventional Commits](https://www.conventionalcommits.org/)\n\n---\n\n## Project Structure\n\n```\nsrc/\n server.ts — Express + SSE + MCP entry point\n db.ts — SQLite WAL schema and queries\n identity.ts — Agent registration, heartbeat, RBAC\n memory.ts — 3-scope memory layer with FTS5\n task.ts — Task scheduler, 7-state machine\n orchestrator.ts — Dependency chains, pipelines, quality gates\n evolution.ts — Strategy engine, trust scoring\n security.ts — Token auth, RBAC, audit hash chain\n\nclient-sdk/\n hub_client.py — Python SDK (no external deps)\n agent-client.ts — TypeScript SDK\n\ndocs/ — Architecture & integration guides\nscripts/ — Install, test, migration scripts\ndeploy/ — Docker Compose, Prometheus, Grafana\n```\n\n---\n\n## Pull Request Process\n\n1. **Fork** the repository and create a branch from `main`:\n ```bash\n git checkout -b feat/your-feature-name\n # or\n git checkout -b fix/your-bug-description\n ```\n\n2. **Make your changes.** Follow the code style guidelines above.\n\n3. **Add tests** for any new functionality. The project uses vitest for unit tests.\n\n4. **Ensure tests pass:**\n ```bash\n npm run test:unit\n npx tsc --noEmit\n ```\n\n5. **Commit** using Conventional Commits format:\n ```bash\n git commit -m \"feat(memory): add FTS5 search for collective memories\"\n git commit -m \"fix(task): prevent duplicate state transitions\"\n ```\n\n6. **Push and open a Pull Request.** Fill out the PR template.\n\n7. A maintainer will review within 48 hours. Be responsive to feedback.\n\n---\n\n## Releasing a Version\n\nVersions are released by tagging on `main`:\n\n```bash\n# Update version in package.json\nnpm version patch # 2.4.1 → 2.4.2\n# or\nnpm version minor # 2.4.1 → 2.5.0\n# or\nnpm version major # 2.4.1 → 3.0.0\n\ngit push --follow-tags\n```\n\nThis triggers the `docker.yml` workflow, which builds and publishes the Docker image automatically.\n\n---\n\n## Code of Conduct\n\nBe respectful and constructive. We welcome contributors from all backgrounds. This project follows the [Contributor Covenant](https://www.contributor-covenant.org/).\n\n---\n\n## Questions?\n\nOpen a GitHub Discussion or ping the maintainer. We respond within 48 hours.\n\nFile v3.0.24:docs/adr/0001-sse-reliable-delivery.md\n\n# ADR-0001: SSE 可靠投递\n\n**状态:** Accepted · **日期:** 2026-07-21 · **修复:** D1（v3.0.19）\n\n## 背景 / 问题\n`sse.ts` 的 `event_id` 是 per-connection 内存计数器，重连归零；事件不持久化，离线补发不可行；`Last-Event-ID` 与 `_hub_event_id` 脱钩，致首连丢消息、重连无法补发。\n\n## 考虑过的方案\n- **A** 毫秒时间戳 + 固定窗口；**B** 持久化 `event_log` + 全局 `event_seq`（采用）。\n\n## 决策\n新增 `event_log` 表（`event_seq` 全局单调、`delivered` 标记）。服务端以 `event_seq` 作 SSE `id`；客户端以其作 `Last-Event-ID`。重连仅重放 `seq > Last-Event-ID` 的 event（覆盖全部类型），仅推送成功才标 `delivered`。\n\n## 后果 / 权衡\n不用 A：同毫秒乱序、跨进程不单调、窗口外永久丢失。持久化使服务端成重放权威源；代价为写开销 + 需归档（参考 `messages_archive`）防膨胀。\n\nFile v3.0.24:docs/adr/0002-activation-state-persistence.md\n\n# ADR-0002: 激活态持久化\n\n**状态:** Accepted · **日期:** 2026-07-21 · **修复:** D2（v3.0.19）\n\n## 背景 / 问题\n`ActivationOrchestrator` 用内存 `Map` 维护激活态，启动靠 `replayFromAudit` 从 `audit_log` 重放。未审计的 registered Agent 内存缺失，`activateAgent` 返回 `AGENT_NOT_FOUND`，编排层不可用（D2）；内存态与 DB 无权威一致。\n\n## 考虑过的方案\n- **A** 纯内存 + 仅审计重放（现状）；**B** DB 权威 + 内存热缓存（采用）。\n\n## 决策\n启动从 `agents` 表 seed registered 态进编排器；`activateAgent` 内存未命中回查 `agents.status` 并载入；激活态落库 `agents.status`（`registered/active/suspended/retired`），写先 DB 后内存，重启从 DB 重载。\n\n## 后果 / 权衡\nDB 权威、内存热缓存，激活低频可接受。必配 D8 对象级鉴权：激活态写 `agents.status` 驱动授权，缺 D8 则任意方可篡改 → 越权。`agents.status` 原表 `online/offline`，实现须区分在线态与激活态。\n\nFile v3.0.24:docs/advanced-orchestration-guide.md\n\n# 进阶编排使用指南\n\n> **版本**：v1.0 | **日期**：2026-04-25\n> **所属**：Agent Synergy Framework Phase 4b\n> **Hub 版本**：v2.0.0+（含 Task Orchestrator 进阶能力）\n\n---\n\n## 概述\n\nPhase 4b 在 Phase 4a 线性 Pipeline 基础上，引入了四种进阶编排能力：\n\n| 能力 | 解决的问题 | 核心工具 |\n|------|-----------|---------|\n| **依赖链** | 任务有前后顺序（B 必须等 A 完成） | `add_dependency` / `remove_dependency` / `get_task_dependencies` |\n| **并行组** | 多个任务可同时执行（A、B、C 互不依赖） | `create_parallel_group` |\n| **质量门** | Pipeline 阶段检查点（代码 review 后才能继续） | `add_quality_gate` / `evaluate_quality_gate` |\n| **交接协议** | 任务负责人变更（双向握手确认） | `request_handoff` / `accept_handoff` / `reject_handoff` |\n\n---\n\n## 1. 依赖链\n\n### 1.1 概念\n\n依赖链定义任务间的执行顺序。当任务 B 依赖任务 A 时：\n- A 未完成 → B 处于 `waiting` 状态\n- A 完成 → B 自动从 `waiting` 变为可执行\n- 如果 A→B→C→A 形成环 → 自动拒绝（DFS 环检测）\n\n### 1.2 依赖类型\n\n| 类型 | 说明 | 触发时机 |\n|------|------|---------|\n| `finish_to_start` | 上游**完成后**下游可开始（默认） | 上游 status = completed |\n| `start_to_start` | 上游**开始后**下游可开始 | 上游 status = in_progress |\n| `finish_to_finish` | 上游**完成后**下游可完成 | 上游 status = completed |\n\n### 1.3 使用示例\n\n```json\n// 1. 创建三个任务\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"design\", \"title\": \"UI设计\", \"assigned_to\": \"designer\", \"operator_id\": \"pm\" } }\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"frontend\", \"title\": \"前端开发\", \"assigned_to\": \"dev1\", \"operator_id\": \"pm\" } }\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"test\", \"title\": \"测试\", \"assigned_to\": \"qa\", \"operator_id\": \"pm\" } }\n\n// 2. 建立依赖：design → frontend → test\n{ \"tool\": \"add_dependency\", \"args\": { \"upstream_id\": \"design\", \"downstream_id\": \"frontend\" } }\n{ \"tool\": \"add_dependency\", \"args\": { \"upstream_id\": \"frontend\", \"downstream_id\": \"test\" } }\n\n// 3. 此时 frontend 和 test 自动变为 waiting 状态\n// 4. designer 完成 design → frontend 自动解除 waiting → dev1 可以开始\n```\n\n### 1.4 工具参数\n\n#### add_dependency\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `upstream_id` | string | ✅ | 上游任务 ID（需先完成） |\n| `downstream_id` | string | ✅ | 下游任务 ID（依赖上游完成后才能开始） |\n| `dep_type` | enum | ❌ | 依赖类型，默认 `finish_to_start` |\n\n**返回**：依赖创建结果 + 自动评估下游任务状态\n\n**错误**：循环依赖 → `\"Circular dependency detected\"` / 任务不存在 → `\"Task not found\"`\n\n#### get_task_dependencies\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `task_id` | string | ✅ | 要查询的任务 ID |\n\n**返回**：\n\n```json\n{\n \"task_id\": \"frontend\",\n \"upstreams\": [\n { \"task_id\": \"design\", \"status\": \"completed\", \"dep_type\": \"finish_to_start\", \"dep_status\": \"satisfied\" }\n ],\n \"downstreams\": [\n { \"task_id\": \"test\", \"status\": \"waiting\", \"dep_type\": \"finish_to_start\", \"dep_status\": \"pending\" }\n ]\n}\n```\n\n### 1.5 状态机扩展\n\n```\n原始状态机：\ninbox → assigned → in_progress → completed\n ↓ ↓\n cancelled failed\n\nPhase 4b 扩展：\ninbox → assigned → waiting → in_progress → completed\n ↓ ↓ ↓\n cancelled cancelled failed\n```\n\n`waiting` 状态：任务有未满足的上游依赖，自动进入。所有上游依赖满足后自动解除。\n\n---\n\n## 2. 并行组\n\n### 2.1 概念\n\n并行组标记一组可以同时执行的任务。同一 `parallel_group` 内的任务互不依赖，可由不同 Agent 并行处理。\n\n### 2.2 使用示例\n\n```json\n// 1. 创建多个独立任务\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"api-dev\", \"title\": \"API开发\", \"assigned_to\": \"backend-dev\" } }\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"ui-dev\", \"title\": \"UI开发\", \"assigned_to\": \"frontend-dev\" } }\n{ \"tool\": \"assign_task\", \"args\": { \"task_id\": \"doc-dev\", \"title\": \"文档编写\", \"assigned_to\": \"tech-writer\" } }\n\n// 2. 标记为并行组\n{ \"tool\": \"create_parallel_group\", \"args\": {\n \"task_ids\": [\"api-dev\", \"ui-dev\", \"doc-dev\"],\n \"group_name\": \"v2-parallel-sprint\"\n}}\n\n// 3. 三个任务可以同时执行\n// 4. 查看并行组信息（通过 get_task_status 或直接查询）\n```\n\n### 2.3 工具参数\n\n#### create_parallel_group\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `task_ids` | string[] | ✅ | 并行任务 ID 列表（2-10 个） |\n| `group_name` | string | ❌ | 并行组名称（便于识别） |\n\n**约束**：最少 2 个，最多 10 个任务\n\n### 2.4 与依赖链组合\n\n并行组常与依赖链组合使用，形成 DAG 工作流：\n\n```\n[design] ──完成──→ [并行组: api-dev + ui-dev + doc-dev] ──全部完成──→ [integration-test]\n ↑ ↑ ↑\n 互不依赖，可并行 三个都完成后 最后集成\n```\n\n---\n\n## 3. 质量门\n\n### 3.1 概念\n\n质量门是 Pipeline 阶段的检查点。只有通过质量门后，后续任务才能继续。适用于代码 review、测试验收等场景。\n\n### 3.2 使用示例\n\n```json\n// 1. 创建质量门（代码 review）\n{ \"tool\": \"add_quality_gate\", \"args\": {\n \"pipeline_id\": \"release-pipeline\",\n \"gate_name\": \"code_review\",\n \"criteria\": \"{\\\"type\\\":\\\"all_completed\\\",\\\"threshold\\\":1}\",\n \"after_order\": 3\n}}\n\n// 2. 前面 3 个任务完成后，QA 评估质量门\n{ \"tool\": \"evaluate_quality_gate\", \"args\": {\n \"gate_id\": \"\",\n \"agent_id\": \"senior-dev\",\n \"passed\": true,\n \"result\": \"代码质量良好，无重大问题\"\n}}\n\n// 3. 如果 passed=false，后续任务被阻塞\n// 4. 修复后重新评估\n```\n\n### 3.3 工具参数\n\n#### add_quality_gate\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `pipeline_id` | string | ✅ | Pipeline ID |\n| `gate_name` | string | ✅ | 阶段名称（2-100 字符） |\n| `criteria` | string | ✅ | JSON 判定条件 |\n| `after_order` | number | ❌ | 在 order_index > 此值的任务开始前检查 |\n\n**criteria 格式**：\n\n```json\n// 方式1：所有前置任务完成\n{ \"type\": \"all_completed\" }\n\n// 方式2：最低成功率\n{ \"type\": \"min_success_rate\", \"threshold\": 0.8 }\n\n// 方式3：自定义检查表达式\n{ \"type\": \"custom\", \"check_expr\": \"test_coverage > 0.9\" }\n```\n\n#### evaluate_quality_gate\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `gate_id` | string | ✅ | 质量门 ID |\n| `agent_id` | string | ✅ | 评估者 Agent ID |\n| `passed` | boolean | ✅ | 是否通过 |\n| `result` | string | ❌ | 评估结果说明 |\n\n### 3.4 质量门状态\n\n```\npending → passed / failed\n```\n\n- `pending`：等待评估\n- `passed`：门已通过，后续任务可继续\n- `failed`：门未通过，后续任务被阻塞（需修复后重新评估）\n\n### 3.5 SSE 事件\n\n| 事件 | 触发时机 | 推送目标 |\n|------|---------|---------|\n| `quality_gate_passed` | 门通过 | Pipeline 参与者 |\n| `quality_gate_failed` | 门未通过 | Pipeline 参与者 + 管理员 |\n\n---\n\n## 4. 交接协议\n\n### 4.1 概念\n\n交接协议是任务负责人的变更流程，采用双向握手模式：\n\n```\n发起方(A) 接收方(B)\n | |\n |-- request_handoff -------->|\n | |\n |<-- accept_handoff ---------| 或 |-- reject_handoff -------->|\n | | (任务仍归 A)\n |-- assigned_to 更新为 B -->|\n```\n\n### 4.2 使用示例\n\n```json\n// 1. A 请求交接\n{ \"tool\": \"request_handoff\", \"args\": {\n \"task_id\": \"bugfix-123\",\n \"from\": \"dev-a\",\n \"to\": \"dev-b\",\n \"reason\": \"需要前端专家处理\",\n \"context\": \"已完成初步排查，CSS 兼容性问题，需要 Chrome 特定调试\"\n}}\n\n// 2. B 接受（任务转移）\n{ \"tool\": \"accept_handoff\", \"args\": {\n \"task_id\": \"bugfix-123\",\n \"agent_id\": \"dev-b\"\n}}\n\n// 或者 B 拒绝（任务仍归 A）\n{ \"tool\": \"reject_handoff\", \"args\": {\n \"task_id\": \"bugfix-123\",\n \"agent_id\": \"dev-b\",\n \"reason\": \"当前排期已满\"\n}}\n```\n\n### 4.3 工具参数\n\n#### request_handoff\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `task_id` | string | ✅ | 要交接的任务 ID |\n| `from` | string | ✅ | 当前负责人 Agent ID |\n| `to` | string | ✅ | 目标接收人 Agent ID |\n| `reason` | string | ❌ | 交接原因 |\n| `context` | string | ❌ | 交接说明（进度、注意事项等） |\n\n**约束**：\n- 只有任务当前负责人才能发起交接\n- 已终态（completed/failed/cancelled）的任务不能交接\n\n#### accept_handoff / reject_handoff\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `task_id` | string | ✅ | 任务 ID |\n| `agent_id` | string | ✅ | 操作者 Agent ID |\n| `reason` | string | ❌ | 拒绝原因（仅 reject） |\n\n### 4.4 SSE 事件\n\n| 事件 | 触发时机 | 推送目标 |\n|------|---------|---------|\n| `handoff_requested` | 交接请求发出 | 接收方 |\n| `handoff_accepted` | 接收方接受 | 原负责人 |\n| `handoff_rejected` | 接收方拒绝 | 原负责人 |\n\n### 4.5 交接状态\n\n```\nnone → requested → accepted\n → rejected → (可重新请求)\n```\n\n---\n\n## 5. 组合工作流示例\n\n一个完整的 DAG 工作流，组合依赖链 + 并行组 + 质量门 + 交接：\n\n```\n┌──────────────┐\n│ 需求分析 │ (PM)\n└──────┬───────┘\n │ finish_to_start\n ▼\n┌──────────────┐\n│ 架构设计 │ (Architect)\n└──────┬───────┘\n │ finish_to_start\n ▼\n┌──────────────┐\n│ 设计 Review │ ← 质量门（code_review，必须通过）\n└──────┬───────┘\n │ 门通过\n ▼\n┌─────┴─────┐\n│ 并行组 │\n│ ┌───────┐ │\n│ │API开发 │ │ (Backend Dev)\n│ ├───────┤ │\n│ │前端开发│ │ (Frontend Dev)\n│ ├───────┤ │\n│ │文档编写│ │ (Tech Writer)\n│ └───────┘ │\n└─────┬─────┘\n │ 全部完成\n ▼\n┌──────────────┐\n│ 集成测试 │ (QA)\n└──────┬───────┘\n │ 测试通过\n ▼\n┌──────────────┐\n│ 发布交接 │ (Dev → SRE) ← 交接协议\n└──────────────┘\n```\n\n---\n\n## 6. 数据模型\n\n### task_dependencies 表\n\n| 列 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT PK | 依赖关系 ID |\n| upstream_id | TEXT FK→tasks | 上游任务 |\n| downstream_id | TEXT FK→tasks | 下游任务 |\n| dep_type | TEXT | finish_to_start / start_to_start / finish_to_finish |\n| status | TEXT | pending / satisfied / failed |\n| created_at | INTEGER | 创建时间戳 |\n\n**索引**：`idx_deps_downstream(downstream_id, status)`、`idx_deps_upstream(upstream_id, status)`\n\n### quality_gates 表\n\n| 列 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT PK | 质量门 ID |\n| pipeline_id | TEXT FK→pipelines | 所属 Pipeline |\n| gate_name | TEXT | 阶段名称 |\n| criteria | TEXT | JSON 判定条件 |\n| after_order | INTEGER | 在此 order_index 后检查 |\n| status | TEXT | pending / passed / failed |\n| evaluator_id | TEXT | 评估者 |\n| result | TEXT | 评估结果详情 |\n| evaluated_at | INTEGER | 评估时间 |\n\n---\n\n*文档版本：v1.0 | 最后更新：2026-04-25*\n\nFile v3.0.24:docs/API_REFERENCE.md\n\n# Agent Communication Hub — API 参考（v3.0.19）\n\n> 本文档描述 Hub 服务端暴露的 **HTTP / SSE / MCP 端点**与鉴权方式，对应源码 `src/server.ts`、`src/security.ts`、`src/sse.ts`。\n>\n> - 当前版本：`3.0.19`（由 `src/version.ts` 从 `package.json` 读取，单一真相源）\n> - 通过 `/mcp` 暴露 **58 个 MCP 工具**（完整工具权限矩阵见 `src/security.ts` 的 `TOOL_PERMISSIONS`）\n> - 存储：SQLite（WAL 模式）\n\n---\n\n## 1. 基础信息\n\n| 项 | 值 |\n|----|----|\n| 默认监听地址 | `http://localhost:3100` |\n| 协议 | HTTP + SSE + MCP（StreamableHTTP） |\n| 当前版本 | `3.0.19` |\n| MCP 工具数 | 58 |\n| 数据库 | SQLite（WAL） |\n\n---\n\n## 2. 认证（Authentication）\n\n所有需要认证的端点通过 **Bearer Token** 鉴权：\n\n```http\nAuthorization: Bearer \n```\n\n- Token 在 `register_agent` 时一次性返回；服务端以 SHA-256 哈希存储，明文不落盘。\n- 服务端按以下顺序提取 Token（见 `src/security.ts` 的 `extractToken`）：\n 1. 请求头 `Authorization: Bearer `\n 2. 查询参数 `?token=`（仅 SSE 等少数场景使用，**不建议**用于 REST/MCP）\n 3. 请求头 `x-api-key: `\n- 缺失或无效 Token → `401`；`/dashboard` 与 `/api/*` 还要求 `role === 'admin'`，否则 `403`。\n- 限流：每个 Agent **10 请求/秒**，超出 → `429 { error: \"Rate limit exceeded (10 req/s)\" }`。\n\n> ⚠️ **安全建议**：Token 不要放在 URL 查询串中（会被访问日志 / 反向代理记录）。REST 与 MCP 一律使用 `Authorization: Bearer`。\n\n### 中间件分级\n\n| 中间件 | 用于端点 | 规则 |\n|--------|----------|------|\n| `authMiddleware` | `/api/tasks`、`/api/messages`、`/api/consumed`、`/admin/invite/generate` | 必须携带有效 Token（含限流） |\n| `internalMonitorAuth` | `/health`、`/health/detailed`、`/metrics` | loopback（127.0.0.1 / ::1）或有效 Token |\n| `requireAdminApi` | `/dashboard`、`/api/status`、`/api/agents`、`/api/audit/tail` | 有效 Token **且** `role === 'admin'` |\n| `optionalAuthMiddleware` | `/events/:agent_id`、`/mcp` | 有 Token 则校验，无则匿名（auth 置为 undefined） |\n\n---\n\n## 3. 端点速查\n\n### 3.1 健康检查与指标（internalMonitorAuth）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/health` | internalMonitorAuth | 返回 `status` / `version` / `uptime` / 内存占用（rss、heap） |\n| GET | `/health/detailed` | internalMonitorAuth | DB 表统计、FTS5 一致性、24h 积压消息数、在线 Agent 列表 |\n| GET | `/metrics` | internalMonitorAuth | Prometheus 格式指标（`text/plain; version=0.0.4`） |\n\n> loopback 探针或 Prometheus scraper 同源可直接访问；跨机需带有效 Token。\n\n### 3.2 REST API（authMiddleware，供自动化脚本轮询）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/api/tasks?agent_id=&status=` | authMiddleware | 列出指定 Agent 的任务；`status` ∈ `pending`/`in_progress`/`completed`/`failed` |\n| GET | `/api/messages?agent_id=&status=` | authMiddleware | 列出消息；`status` ∈ `unread`/`delivered`/`read`/`acknowledged` |\n| PATCH | `/api/tasks/:id/status` | authMiddleware | body：`status`(`in_progress`/`completed`/`failed`)、`result`、`progress`；成功后 SSE 通知发起方 |\n| PATCH | `/api/messages/:id/status` | authMiddleware | body：`status` ∈ `read`/`delivered`/`acknowledged` |\n| GET | `/api/consumed?agent_id=&resource=` | authMiddleware | 查询消费水位线（防重复处理）；带 `resource` 查单条，否则列最近 50 条 |\n| POST | `/admin/invite/generate` | authMiddleware + admin | 生成邀请码（24h 有效），body：`role`(`admin`/`member`)；返回 `invite_code` |\n\n### 3.3 管理端点（requireAdminApi）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/api/status` | requireAdminApi | 面板总览：Agent / Pipeline 状态分布、近 5 分钟吞吐、FTS5 状态、限流 Top 10 |\n| GET | `/api/agents` | requireAdminApi | 全部 Agent 详情（角色、信任分、最后活跃、在线状态） |\n| GET | `/api/audit/tail?n=<50>` | requireAdminApi | 审计日志尾部（最多 500 条） |\n\n### 3.4 MCP 端点（StreamableHTTP，Stateless）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| POST | `/mcp` | optionalAuthMiddleware | JSON-RPC：`tools/call`、`tools/list`、`initialize` 等 |\n| GET | `/mcp` | optionalAuthMiddleware | 建立 MCP 流（SSE 格式响应） |\n| DELETE | `/mcp` | optionalAuthMiddleware | 终止 MCP 会话 |\n\n- **无状态（Stateless）模式**：`sessionIdGenerator: undefined`，每次请求独立，不维护服务端 session。**多 Client 必须走 Stateless**。\n- 调用时请求头需带 `Accept: application/json, text/event-stream`。\n- 权限：`register_agent` 为 `public`（免 Token），其余 57 个工具需先注册并携带 Token（fail-closed：未登记工具一律拒绝）。\n- 认证失败（限流/无效 Token）返回 JSON-RPC 错误：`{ jsonrpc:\"2.0\", error:{ code:-32001, message:\"Rate limit exceeded (10 req/s)\" }, id:null }`。\n\n### 3.5 SSE 实时推送（optionalAuthMiddleware）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/events/:agent_id` | optionalAuthMiddleware | 长连接，实时推送新消息 / 任务 / 策略 / 交接等事件 |\n\n- 连接示例：\n ```bash\n curl -N \\\n -H \"Authorization: Bearer \" \\\n -H \"Last-Event-ID: <上次事件毫秒时间戳>\" \\\n http://localhost:3100/events/\n ```\n- 每条事件格式（`src/sse.ts` 的 `pushToAgent`）：\n ```\n id: <每连接递增整数>\n event: message\n data: {\"event\":\"new_message\",\"message\":{...},\"_hub_event_id\":,\"_hub_dedup_id\":<可选>}\n\n ```\n- **断线重连**：客户端在请求头带 `Last-Event-ID`（毫秒时间戳）。服务端解析为整数作为 `since`，调用 `messageRepo.listSince(agent_id, since)` 回放该时间戳之后的消息；回放窗口 `SSE_REPLAY_WINDOW`（默认 3600 秒），超出窗口的部分不补发。\n- 首次连接（无 `Last-Event-ID`）：服务端补发离线期间的未读消息与待执行任务。\n- 心跳：每 `SSE_HEARTBEAT_INTERVAL`（默认 10000ms）发送 `: ping`。\n\n> ⚠️ **注意区分两种 id**：SSE 事件体的 `id:` 字段是**每连接递增整数**（`_hub_event_id`，用于客户端去重）；而断线重连的 `Last-Event-ID` 请求头被服务端当作**毫秒时间戳**处理（用于 `listSince` 回放）。客户端重连时应记录并回传最近一次事件的**毫秒时间戳**，而非递增 `id`。\n\n### 3.6 Web 管理面板（requireAdminApi）\n\n| 方法 | 路径 | 鉴权 | 说明 |\n|------|------|------|------|\n| GET | `/dashboard` | requireAdminApi | 纯静态仪表盘（总览 / Agents / 吞吐 / 健康 / 审计日志） |\n| GET | `/` | 重定向 | → `/dashboard` |\n\n---\n\n## 4. 统一错误格式\n\n- 未匹配路由 → `404 { error:true, message:\"Not Found\", traceId }`\n- 未捕获异常 → `500 { error:true, message, traceId }`（非开发环境隐藏原始 message）\n- 每个响应均带 `X-Trace-Id` 响应头，便于跨服务追踪。\n\n---\n\n## 5. CORS 与安全响应头\n\n- **CORS**：仅放行 `CORS_ORIGINS`（逗号分隔）中的来源，空 = 拒绝所有跨域；`OPTIONS` 预检返回 `204`。允许的请求头：`Content-Type, Authorization, X-Trace-Id, X-Api-Key`。\n- **安全响应头**：`X-Frame-Options: DENY`、`X-Content-Type-Options: nosniff`、`X-XSS-Protection: 1; mode=block`、`Strict-Transport-Security: max-age=31536000; includeSubDomains`、`Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'`。\n\n---\n\n## 6. 端点汇总\n\n| # | 方法 | 路径 | 鉴权 |\n|---|------|------|------|\n| 1 | GET | `/health` | internalMonitorAuth |\n| 2 | GET | `/health/detailed` | internalMonitorAuth |\n| 3 | GET | `/metrics` | internalMonitorAuth |\n| 4 | POST | `/admin/invite/generate` | authMiddleware + admin |\n| 5 | GET | `/api/tasks` | authMiddleware |\n| 6 | GET | `/api/messages` | authMiddleware |\n| 7 | PATCH | `/api/tasks/:id/status` | authMiddleware |\n| 8 | PATCH | `/api/messages/:id/status` | authMiddleware |\n| 9 | GET | `/api/consumed` | authMiddleware |\n| 10 | GET | `/api/status` | requireAdminApi |\n| 11 | GET | `/api/agents` | requireAdminApi |\n| 12 | GET | `/api/audit/tail` | requireAdminApi |\n| 13 | GET | `/events/:agent_id`（SSE） | optionalAuthMiddleware |\n| 14 | POST | `/mcp` | optionalAuthMiddleware |\n| 15 | GET | `/mcp` | optionalAuthMiddleware |\n| 16 | DELETE | `/mcp` | optionalAuthMiddleware |\n| 17 | GET | `/dashboard` | requireAdminApi |\n| 18 | GET | `/` | 重定向 |\n\n> 共 16 个端点路由，其中 `/mcp` 含 POST / GET / DELETE 三方法（共 18 个方法级端点）。58 个 MCP 工具均经 `/mcp` 暴露。\n\nFile v3.0.24:docs/design/ach-autonomous-loop-hitl-auth.md\n\n# ACH 增量架构设计：自主 Agent 执行闭环 + 操作级人在环授权队列\n\n> 版本：设计稿 v1（design only，待用户确认后交付工程师实现）\n> 仓库：`agent-comm-hub`（当前 v3.0.23，TS + better-sqlite3 + SSE + Express + MUI 前端，零外部服务）\n> 设计依据：已逐项核对真实代码（`client-sdk/agent-client.ts`、`src/orchestrator.ts`、`src/sse.ts`、`src/tools.ts`、`src/db.ts`、`src/security.ts`、`web/src/App.tsx`、`client-sdk/*-integration.ts`）。\n\n---\n\n## 1. TL;DR\n\n> **在客户端 SDK 新增一个运行时原语 `AgentRuntime`（包裹现有 `AgentClient`），让 Agent 收到任务后自动「标记进行中 → 执行宿主注入的 `execute()` → 回写完成/失败」，从而消灭人工中转；同时新增一条「操作级授权」闭环——Agent 执行中遇到敏感操作就调 `requestAuthorization(op)` 挂起等待，用户在 Web 仪表盘「待授权」面板批准/拒绝，Hub 经 SSE 把结果回推，Agent 继续或优雅中止。Hub 始终只是纯协调层，零新增依赖。**\n\n两条特性正交：Feature A 解决「收到任务后是否自主执行」，Feature B 解决「执行中敏感操作是否放行」。Feature B 通过 `AgentRuntime` 暴露的 `requestAuthorization()` 接入 Feature A 的 `execute()`。\n\n---\n\n## 2. 实现方案 + 框架选型\n\n### 2.1 总体原则（增量、零新依赖）\n\n| 维度 | 现状（已具备） | 本次增量 | 是否引入新依赖 |\n|---|---|---|---|\n| 传输层 | `AgentClient` SSE 长连接 + 自动重连，`pushToAgent` 实时推 | 复用；仅新增 2 个事件类型 | 否 |\n| 任务状态机 | `orchestrator.ts` `assigned→in_progress→completed/failed` | 复用，`AgentRuntime` 只驱动既有转换 | 否 |\n| 工具层 | `server.tool(name, desc, zodSchema, authed(...))` | 新增 2 个 MCP 工具（注册即接入） | 否（复用 zod） |\n| 持久化 | `better-sqlite3` + `CREATE TABLE IF NOT EXISTS` 迁移 | 新增 `auth_requests`(+可选`auth_grants`) 表 | 否 |\n| 审计 | `auditLog()` 哈希链（`prev_hash`/`record_hash`） | 授权创建/决议写入同一条链 | 否 |\n| 鉴权 | 4 级 RBAC + 激活态鉴权 | 复用；决议动作走仪表盘登录态 | 否 |\n| 前端 | React + MUI + react-router（`App.tsx` 路由） | 新增 `AuthQueue.tsx` 路由 + 2 个 REST 端点 | 否（复用 MUI/react-router） |\n\n**结论：零新增第三方依赖。** 所有能力均建立在既有原语之上。\n\n### 2.2 Feature A — 自主执行闭环（落点拍板：SDK 原语）\n\n- **落点：在 `client-sdk` 新增 `AgentRuntime` 运行时原语**，包裹现有 `AgentClient`。\n - 监听 `onTaskAssigned` → 自动 `updateTaskStatus(in_progress)` → 调宿主注入的 `execute(task)` → `updateTaskStatus(completed, {result})`（异常→`failed`）。\n - `new_message` 指向自己时触发可选 `onSelfMessage` 反应。\n - `execute()` 由宿主实现（WorkBuddy/Hermes 各自注入），Hub 完全不感知执行内容——**Hub 仍是纯协调层**。\n- **为何 SDK 原语而非各宿主自实现**：\n 1. 闭环里最容易出错的「状态机驱动、幂等去重、崩溃恢复、并发上限、防自杀式循环、授权挂起/超时」等护栏是**通用逻辑**，放一处即可被所有宿主复用，避免 WorkBuddy/Hermes 各写一套导致行为不一致。\n 2. **多宿主兼容**：任何新宿主只要 `new AgentRuntime(client, execute)` 一行即可获得自主执行能力；Hub 端零改动。\n 3. 现有 `workbuddy-integration.ts` / `hermes-integration.ts` 已经在 `onTaskAssigned` 里手写这套闭环（见代码第 19–37 / 36–60 行），证明模式成立——本次只是把它抽成可复用原语，并补上缺失的护栏。\n\n### 2.3 Feature B — 操作级人在环授权队列（落点拍板：Hub 侧服务 + SDK 客户端方法）\n\n- **Hub 侧**：新增 `src/authorization.ts` 服务（建表/建请求/决议/过期清扫）+ `src/tools/authorization.ts` 注册 `request_authorization` / `resolve_authorization`(可选 MCP) 工具 + `server.ts` 新增 2 个 REST 端点（供仪表盘）。\n- **SDK 侧**：`AgentClient` 新增 `requestAuthorization(op)`，返回 `Promise`；`routeEvent` 新增 `authorization_requested` / `authorization_resolved` 两个分支，用 `reqId→{resolve,reject}` 映射表 resolve/reject 该 Promise；内置 TTL 超时 reject。\n- **仪表盘侧**：`web/src/components/AuthQueue.tsx` 新面板，轮询 `GET /api/auth-requests?status=pending`，按钮调 `POST /api/auth-requests/:id/resolve`。\n- **关键点**：授权是「操作级、本次具体敏感操作批不批」，与既有「角色级 RBAC」互补——RBAC 管“你能不能调这类工具”，授权队列管“你这次要做的这件具体事放不放行”。\n\n---\n\n## 3. 文件清单（新增 / 修改，相对仓库根）\n\n### Feature A\n| 操作 | 路径 | 说明 |\n|---|---|---|\n| 新增 | `client-sdk/runtime.ts` | `AgentRuntime` 类 + `runAutonomousLoop()` 工厂 + 循环护栏/崩溃恢复 |\n| 修改 | `client-sdk/agent-client.ts` | 新增 `requestAuthorization(op)` 方法；`routeEvent` 增加 `authorization_resolved` 分支（用于解锁 Promise）；`TaskEvent` 字段对齐 |\n| 修改（示例） | `client-sdk/workbuddy-integration.ts` | 用 `AgentRuntime` 改写 `onTaskAssigned`（注入 `executeWorkBuddyTask`） |\n| 修改（示例） | `client-sdk/hermes-integration.ts` | 同上，注入 `executeHermesTask` |\n\n### Feature B\n| 操作 | 路径 | 说明 |\n|---|---|---|\n| 新增 | `src/authorization.ts` | 授权服务：建请求 / 决议 / 过期清扫 / 信任窗口(`auth_grants`) |\n| 新增 | `src/tools/authorization.ts` | 注册 `request_authorization` / `resolve_authorization` / `list_authorization_requests` |\n| 修改 | `src/tools.ts` | `registerTools` 增加 `registerAuthorizationTools(...)` |\n| 修改 | `src/db.ts` | 新增 `auth_requests`（+可选 `auth_grants`）建表与迁移 |\n| 修改 | `src/server.ts` | 新增 REST：`GET /api/auth-requests`、`POST /api/auth-requests/:id/resolve`；SSE 推 `authorization_requested`/`authorization_resolved` |\n| 修改 | `client-sdk/agent-client.ts` | `requestAuthorization()` + `routeEvent` 的 `authorization_requested`/`authorization_resolved` 分支 + Promise 映射 |\n| 新增 | `web/src/components/AuthQueue.tsx` | 「待授权」面板（列表 + 批准/拒绝 + 信任窗口勾选） |\n| 修改 | `web/src/App.tsx` | 增加 `/auth` 路由与侧边栏入口 |\n| 修改 | `web/src/api.ts` | 增加 `fetchAuthRequests()` / `resolveAuthRequest()` |\n\n### 共享\n| 修改 | `src/config`(见 `server.ts` config 对象) | 新增 `AUTH_REQUEST_TTL_MS` / `AUTH_AUTO_APPROVE` / `RUNTIME_MAX_CONCURRENT` / `RUNTIME_LOOP_GUARD_MS` 等环境变量默认值 |\n| 修改 | `src/db.ts`（清理项） | **建议**：将 `assignTask` 推送负载统一为 `{ event: \"task_assigned\", task: {...} }`（与 SSE 补发路径一致），消除 `type` vs `event` 历史不一致（见 §9 / §10）。 |\n\n---\n\n## 4. 数据结构与接口\n\n### 4.1 `AgentRuntime` / `runAutonomousLoop` 接口与生命周期\n\n```ts\n// client-sdk/runtime.ts\nimport { AgentClient, TaskEvent } from \"./agent-client.js\";\n\n/** 敏感操作描述（传入 requestAuthorization） */\nexport interface SensitiveOp {\n type: string; // 操作类目，见 §4.5 共享常量 AUTH_OP_TYPES\n description: string; // 人类可读的“将要做什么”\n payload?: unknown; // 供人类判定的具体参数（JSON 序列化后入库）\n taskId?: string; // 关联任务（可选）\n}\n\nexport interface AgentRuntimeOptions {\n maxConcurrent?: number; // 并发执行上限，默认 4\n requeueIncomplete?: boolean; // 启动时重跑 in_progress/assigned 的崩溃恢复，默认 true\n loopGuard?: { // 防自杀式循环\n windowMs?: number; // 相同 description 重分配的判定窗口，默认 30000\n maxIdentical?: number; // 窗口内最多允许几次，超过则跳过，默认 2\n };\n onSelfMessage?: (msg: MessageEvent) => Promise; // 指向自己的 new_message 可选反应\n onError?: (taskId: string, err: unknown) => void;\n}\n\nexport class AgentRuntime {\n constructor(\n private client: AgentClient,\n private execute: (task: TaskEvent) => Promise, // 宿主注入的执行逻辑\n private opts: AgentRuntimeOptions = {}\n );\n start(): Promise; // 接线 onTaskAssigned / onMessage；可选崩溃恢复重跑\n stop(): void; // 拒绝所有挂起的授权 Promise；停止接收\n /** 在 execute() 内部调用：提交授权请求并挂起，批准后 resolve，拒绝/过期 reject */\n requestAuthorization(op: SensitiveOp): Promise;\n}\n\n/** 便捷工厂 */\nexport function runAutonomousLoop(\n client: AgentClient,\n execute: (task: TaskEvent) => Promise,\n opts?: AgentRuntimeOptions\n): AgentRuntime;\n```\n\n**生命周期（状态）**：`Idle → Starting（接线回调 + 崩溃恢复）→ Running（监听 task_assigned/new_message）→ Stopping（拒绝挂起 Promise）→ Stopped`。\n\n**`handleAssigned(task)` 内部流程（护栏）**：\n1. 若 `task.id` 已在 `inFlight` 集合 → 跳过（幂等去重，防止实时推 + 补发重复执行）。\n2. 若 `loopGuard` 命中（窗口内相同 `description` 重分配超阈值）→ 跳过并 `auditLog('loop_guard_skip', agentId, task.id)`。\n3. 标记 `in_progress`（progress 5）；写入 `inFlight`。\n4. `try { result = await execute(task) }`：\n - 成功 → `updateTaskStatus(completed, result, 100)`。\n - 捕获 `AuthorizationRejected` / `AuthorizationExpired` → `updateTaskStatus(failed, \"授权被拒/过期: \")` + `auditLog`。\n - 其他异常 → `updateTaskStatus(failed, err.message)`。\n5. 从 `inFlight` 移除；若 `inFlight.size >= maxConcurrent` 则不主动拉取更多（Hub 补发/重分配自然节流）。\n\n### 4.2 `auth_requests` 表 Schema（SQL DDL）\n\n```sql\n-- src/db.ts 内新增（CREATE TABLE IF NOT EXISTS，幂等）\nCREATE TABLE IF NOT EXISTS auth_requests (\n id TEXT PRIMARY KEY, -- req__\n agent_id TEXT NOT NULL, -- 请求方 Agent\n task_id TEXT, -- 关联任务（可空）\n op_type TEXT NOT NULL, -- 见 AUTH_OP_TYPES\n op_payload TEXT, -- JSON：具体操作参数，供人类判定\n status TEXT NOT NULL DEFAULT 'pending', -- pending|approved|rejected|expired\n created_at INTEGER NOT NULL,\n expires_at INTEGER NOT NULL, -- created_at + AUTH_REQUEST_TTL_MS\n resolved_by TEXT, -- 决议人（人类操作者 ID / admin）\n resolved_at INTEGER,\n decision_reason TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_auth_status ON auth_requests(status);\nCREATE INDEX IF NOT EXISTS idx_auth_agent ON auth_requests(agent_id);\n\n-- 可选：信任窗口（时间窗口信任粒度，见 §9 决策 3）\nCREATE TABLE IF NOT EXISTS auth_grants (\n id TEXT PRIMARY KEY,\n agent_id TEXT NOT NULL,\n op_category TEXT NOT NULL, -- 类目级信任（如 'external_api'）\n granted_by TEXT NOT NULL,\n granted_at INTEGER NOT NULL,\n expires_at INTEGER NOT NULL\n);\nCREATE INDEX IF NOT EXISTS idx_grant_agent_cat ON auth_grants(agent_id, op_category);\n```\n\n### 4.3 新增 MCP 工具参数 / 返回 Schema\n\n**`request_authorization`**（Agent 经 SDK 调用；`agent_id` 取自 `authed` 上下文）\n\n```\n入参 (zod):\n op_type : enum(AUTH_OP_TYPES) // 必填，操作类目\n description : string // 必填，人类可读\n op_payl\n\nArchive v3.0.22: 183 files, 537678 bytes\n\nFiles: CHANGELOG.md (5420b), client-sdk/agent-client.d.ts (11889b), client-sdk/agent-client.js (29247b), client-sdk/agent-client.ts (30504b), client-sdk/backoff.ts...","readmeExcerpt":"Skill: agent-comm-hub Owner: liuboacean Summary: 本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板 Tags: 2.4.0:2.4.0, 2.4.1:2.4.1, agent:3.0.19, agent-comm:3.0.20, agent-comm-hub:3.0.25, ai-agents:1.0.0, audit-log:3.0.22, backup:3.0.25, communication:3.0.25, evolution:2.2.1, heartbeat:3.0.22, hermes:1.0.0, hub:3.0.25, infrastructure:3.0.20, latest:3.0.25, mcp:3.0.25, memory:3.0.25, mess","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"┌──────────────┐ ┌──────────────────────────────┐ ┌──────────────┐\n│ Agent A │ SSE │ Agent Communication Hub │ SSE │ Agent B │\n│ (Hermes) │◄───────►│ (stdio) │◄───────►│ (WorkBuddy) │\n│ │ MCP │ │ MCP │ │\n└──────────────┘◄───────►│ SQLite WAL + 30 表 │◄───────►└──────────────┘\n │ 58 MCP 工具 + RBAC 权限 │\n │ 上下文暂存 + 建议闭环 │\n └──────────────┬──────────────┘\n │\n SQLite (WAL)"},{"language":"text","snippet":"调用: get_online_agents()\n期望: 返回在线 Agent 列表（至少含自己）\n失败: Hub 未运行 → 先启动 Hub 服务器"},{"language":"text","snippet":"1. 调用: query_agents(status='all') → 查看所有 Agent\n2. 如果自己的 Agent ID 不在列表中\n → register_agent(invite_code, name, capabilities)\n3. 如果已注册 → 记下自己的 agent_id 供后续使用"},{"language":"text","snippet":"调用: heartbeat(agent_id='你的ID')\n频率: 每 30 秒一次（超过 90 秒无心跳则自动标记为离线）"},{"language":"text","snippet":"1. 调用: search_messages(query='你的ID', limit=20)\n2. 筛选 status='unread' 的消息\n3. 按时间顺序处理，先 acknowledge_message 确认收到，再回复"},{"language":"text","snippet":"调用: send_message(from='你的ID', to='目标AgentID', content='通信链路确认畅通')\n检查返回: delivered_realtime — true=对方在线, false=对方离线"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: agent-comm-hub\ndescription: \"本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板\"\nversion: \"3.0.25\"\ncategory: autonomous-ai-agents\ntriggers:\n - \"agent-comm-hub\"\n - \"AgentCommHub\"\n - \"ACH\"\n - \"agent-comm\"\n - \"agent_comm_hub\"\n - \"通信hub\"\n - \"消息hub\"\n - \"workbuddy\"\n - \"QClaw\"\n - \"send_message\"\n - \"assign_task\"\n---\n\n# Agent Communication Hub\n\n> 多智能体消息转发与上下文共享中间件 — **v3.0.25**\n\n让两个或多个独立 AI 智能体之间实现**实时双向通信**和**上下文自动同步**。基于 MCP 协议 + stdio 模式，消息本地持久化，延迟 < 50ms。\n\n## 架构概览\n\n```\n┌──────────────┐ ┌──────────────────────────────┐ ┌──────────────┐\n│ Agent A │ SSE │ Agent Communication Hub │ SSE │ Agent B │\n│ (Hermes) │◄───────►│ (stdio) │◄───────►│ (WorkBuddy) │\n│ │ MCP │ │ MCP │ │\n└──────────────┘◄───────►│ SQLite WAL + 30 表 │◄───────►└──────────────┘\n │ 58 MCP 工具 + RBAC 权限 │\n │ 上下文暂存 + 建议闭环 │\n └──────────────┬──────────────┘\n │\n SQLite (WAL)\n```\n\n**三层协议**：\n\n| 层 | 协议 | 用途 | 延迟 |\n|----|------|------|------|\n| MCP 工具层 | stdio JSON-RPC | 结构化操作（发消息、分配任务、查状态） | <50ms |\n| SSE 推送层 | Server-Sent Events | 实时事件通知（新消息、新任务、建议确认） | <50ms |\n\n## 快速上手 (5 分钟)\n\n从零到完成第一次 Agent 间通信的编号流程：\n\n### Step 1: 确认 Hub 运行状态\n\n确认 Agent Communication Hub 服务器正在运行。如果通过 stdio 模式接入，检查 MCP 配置是否正确加载：\n\n```\n调用: get_online_agents()\n期望: 返回在线 Agent 列表（至少含自己）\n失败: Hub 未运行 → 先启动 Hub 服务器\n```\n\n**[检查点] 用户确认**：如果 Hub 未运行，询问用户是否要启动 Hub 服务器。\n\n### Step 2: 注册或确认身份\n\n检查自己是否已在 Hub 注册，如果没有则注册：\n\n```\n1. 调用: query_agents(status='all') → 查看所有 Agent\n2. 如果自己的 Agent ID 不在列表中\n → register_agent(invite_code, name, capabilities)\n3. 如果已注册 → 记下自己的 agent_id 供后续使用\n```\n\n**[检查点] 用户确认**：注册新 Agent 需要 invite_code，先问用户是否有可用的邀请码。\n\n### Step 3: 维持在线状态\n\n启动心跳维持在线，确保能接收实时消息推送：\n\n```\n调用: heartbeat(agent_id='你的ID')\n频率: 每 30 秒一次（超过 90 秒无心跳则自动标记为离线）\n```\n\n### Step 4: 检查未读消息\n\n上线后第一时间检查是否有离线期间缓存的消息：\n\n```\n1. 调用: search_messages(query='你的ID', limit=20)\n2. 筛选 status='unread' 的消息\n3. 按时间顺序处理，先 acknowledge_message 确认收到，再回复\n```\n\n**[检查点] 用户确认**：找到未读消息后，逐条向用户摘要汇报，请用户确认如何处理。\n\n### Step 5: 发送第一条消息\n\n向另一个 Agent 发送消息，验证双向通信：\n\n```\n调用: send_message(from='你的ID', to='目标AgentID', content='通信链路确认畅通')\n检查返回: delivered_realtime — true=对方在线, false=对方离线\n```\n\n**[检查点] 用户确认**：发送前向用户确认消息内容和目标 Agent。broadcast_message 必须逐条确认。\n\n### 完整闭环示例\n\n```\n场景：Hub 在线 → 检查 WorkBuddy 是否有未读消息 → 处理并回复\n\n1. get_online_agents() # 确认自己和对方在线\n2. search_messages(limit=10) # 查最近消息\n3. acknowledge_message(msg_id, agent_id) # 标记已读\n4. send_message(to='workbuddy', content='已收到，正在处理') # 回复\n5. mark_consumed(resource=msg_id, action='replied') # 消费水位线\n```\n\n## 核心能力\n\n### 58 个 MCP 工具（当前版本）\n\n#### Identity 身份 (6)\n\n| 工具 | 功能 |\n|------|------|\n| `register_agent` | 注册新 Agent，需提供 HUB_AUTH_TOKEN 认证 |\n| `heartbeat` | Agent 心跳上报，维持在线状态，每 3 次连续心跳记录 +1 |\n| `"},{"path":"README.md","content":"

\n \n \n \"Node.js\n \n \"Python\n \"MCP\n \"288\n \"Zero\n \"Web\n \n \"CI\"\n \n \"MIT\n \n \"PyPI\"\n \n \n \"npm\"\n \n \n \"Glama\n \n \n \"Available\n \n

\n\n

\n 🤖 Agent Communication Hub\n

\n

\n 让 AI Agent 不再各自为战
\n 实时消息 · 任务调度 · 共享记忆 · 信任进化 · Web 仪表盘
\n 58 个 MCP 工具 · 零外部服务 · 5 分钟部署\n

\n\n

\n 中文 · English\n · GitHub\n

\n\n
\n\n---\n\n## 👀 一眼看明白\n\n```mermaid\ngraph LR\n A[Claude Code] <--> H((ACH Hub))\n B[WorkBuddy] <--> H\n C[OpenClaw] <--> H\n D[自定义 Agent] <--> H\n H --> DB[(SQLite)]\n H --> Web[Web 仪表盘]\n style H fill:#4f46e5,color:#fff\n style Web fill:#7c3aed,color:#fff\n```\n\n**任何 MCP 兼容的 AI Agent** → 连接 Hub → 立即获得：消息总线、任务队列、共享记忆、进化引擎。\n\n> 🚀 **5 分钟启动**：`docker run -d -p 3100:3100 ghcr.io/liuboacean/agent-comm-hub`\n\n---\n\n## 💡 为什么需要它？\n\n多个 AI Agent（Claude Code、WorkBuddy、OpenClaw、Hermes 等）天然是**信息孤岛**：\n\n| 问题 | 传统方案 | 为什么不行 |\n|------|---------|-----------|\n| ❌ Agent 间无法通信 | Webhook / 共享文件 | 脆弱、不可靠、手动维护 |\n| ❌ 无法跨 Agent 调度任务 | 各自为战 | 没人协调，任务丢失 |\n| ❌ 无法共享上下文 | 每轮对话都从零开始 | 记不住团队经验 |\n| ❌ 无法团队进化 | 每个 Agent 独自踩坑 | 同样的问题反复修 |\n\n**Agent Communication Hub（ACH）** 是它们的**共享神经中枢**——一条消息总线 + 任务调度器 + 团队记忆库 + 经验进化引擎。\n\n---\n\n## 🚀 三步上手\n\n```bash\n# 0. 安装 Python SDK（可选）\npip install agent-comm-hub\n\n# 1. 启动 Hub（一行命令）\n"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn73qbrbqs4s8t2nh8pm22wxbd84vm7r\",\n \"slug\": \"agent-comm-hub\",\n \"version\": \"3.0.25\",\n \"publishedAt\": 1790732360314\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\n## [3.0.24] - 2026-08-14 — 宿主执行器闭环收口（HostExecutor 注入）\n\n### Changed (宿主接入收口)\n- **真实宿主执行器（HostExecutor）**：新增 `client-sdk/adapters/host-executor.ts`，提供 `LlmHostExecutor`（直连 Anthropic/OpenAI，需 `HOST_LLM_API_KEY`）与 `HttpHostExecutor`（POST 到 `HOST_EXEC_ENDPOINT`）两套参考实现；`defaultHostExecutor()` 按环境变量自动二选一；`AbstractHostTaskBridge` 新增可注入 `executor` 字段（默认 `defaultHostExecutor()`）\n- **消灭 setTimeout 占位**：WorkBuddy / Hermes 桥的 `runTask()` 改为委托 `this.executor.execute(task, report)`，任务到达即触发宿主真实能力，「任务派发 → Agent 自动干活 → 回写结果」真正闭环\n- **文档**：`docs/HOST_INTEGRATION.md` §4 重写为 HostExecutor 注入模型 + 环境变量表 + 自定义执行器示例\n\n## [3.0.23] - 2026-08-14 — Agent 自主执行闭环 + 人在环授权\n\n### Added (Feature A — Agent 自主执行闭环)\n- **`AgentRuntime` 运行时原语**（`client-sdk/runtime.ts`）：包裹 `AgentClient`，自动驱动 `in_progress → execute() → completed/failed`，内置 inFlight 去重、崩溃恢复、loopGuard，消灭 Agent 间人工「传话」\n- **`runAutonomousLoop` 工厂**：宿主一行接入即可让 Agent 自动消费任务事件并自循环\n\n### Added (Feature B — 人在环授权队列)\n- **操作级授权**：`auth_requests` 表 + `request_authorization` / `resolve_authorization` / `list_authorization_requests` 工具，deny-by-default，TTL 10min\n- **Web `AuthQueue` 面板**：待授权操作实时队列，用户一键批准 / 拒绝\n- **SSE 事件推送**授权请求；宿主侧 `AgentClient.requestAuthorization(op)` 阻塞等待决议\n\n### Chore\n- 清理 `client-sdk/` 下 3 个 5 月陈旧编译产物（`agent-client.js` / `hermes-integration.js` / `workbuddy-integration.js`）及其 `.map`，修正 `client-sdk/package.json` 的 `main` / `files` 入口引用；vitest 的 `.js→.ts` 别名已旁路这些文件，移除不影响构建与 312 项测试\n\n## [3.0.22] - 2026-07-23 — 在线状态 / 审计归档 / 备份路径\n\n### Changed (在线状态判定)\n- **SSE 实时连接纳入「在线」判定**：新增统一判定 `isAgentOnline()` / `getOnlineAgentIds()` =（存在 SSE 连接）**或**（心跳在 90s 阈值内）。`get_online_agents` 工具、派单候选排序（`orchestrator`）、`/health/detailed`、`/api/agents`、`hub_agents_online` 指标全部改用统一判定\n- **心跳监控不再误杀 SSE 在线 Agent**：`startHeartbeatMonitor` 对仍有 SSE 连接的 Agent 不再因心跳陈旧标记离线、也不再广播离线通知\n- **SSE 连接同步 `agents.status`**：连接建立即标记 `online`、断开且心跳陈旧才标 `offline`，数据库与「SSE 已连」事实一致\n\n### Changed (审计日志归档)\n- **`enforceAuditLogCap(maxRows)`**：`audit_log` 超过 `AUDIT_LOG_MAX_ROWS`（默认 3000，env 可调）行时，将最旧溢出行自动**镜像**到 `audit_log_archive`（WORM 安全，不删源表）\n- **维护调度器**：`server` 启动即跑、之后每小时执行「90 天时间归档 + 行数上限镜像」，解决「audit_log 无限增长、归档机制空转」\n\n### Changed (备份路径)\n- **`backup.ts` 改用稳定路径**：`BACKUP_DIR` 从 `process.cwd()/backups`（易失 workspace）改为 `~/agent-comm-hub/backups`，与 launchd 备份脚本同目录；支持 `BACKUP_DIR` 环境变量覆盖\n\n## [3.0.21] - 2026-07-23 — 审计修复（稳定性 / 安全 / 质量）\n\n### Fixed (P1 — 稳定性 / 安全)\n- **P1-1 SSE 重连竞态**：`registerClient`/`removeClient` 增加连接级 `connId` 校验，旧 socket 的 `close` 事件不再误删「当前」实时连接，重连后消息 / 任务 / 激活通知不再静默丢失\n- **P1-2 并发写 `SQLITE_BUSY`**：`db` 初始化增加 `busy_timeout=5000` + `foreign_keys=ON` + `wal_autocheckpoint`，消除 HTTP handler / SSE push / 后台调度并发写导致的静默丢数据\n- **P1-3 限流绕过**：认证前置 IP / 全局限流（防令牌爆破与未认证 `/mcp` 耗尽资源）；`/mcp` 增加并发在途上限（默认 50）防 DoS\n- **P1-4 / P1-5 FTS 值碰撞**：`memories_fts` 增加 `memory_id` 精确关联键（启动迁移旧表），召回按 `id` 关联、删除按 `id` 命中，内容相同的两条记忆不再互相串台（删除一条误伤另一条）\n\n### Fixed (P2 — 质量 / 文档)\n- **P2-1 信任分误扣**：`revoke_token` 审计将「被吊销者」写入 `target` 列，信任分公式改按 `target` 统计，管理员不再被误扣、被吊销者正确扣分\n- **P2-2 metrics 无"},{"path":"client-sdk/README_PYPI.md","content":"# Agent Communication Hub — Python SDK\n\nZero-dependency Python client for [Agent Communication Hub](https://github.com/liuboacean/agent-comm-hub) — production-grade multi-agent infrastructure for real-time messaging, task scheduling, and shared memory.\n\n```python\nfrom hub_client import SynergyHubClient\n\nhub = SynergyHubClient(\"http://localhost:3100\")\nhub.set_token(\"your-token\")\nhub.send_message(to=\"other-agent\", content=\"Hello!\")\n```\n\n## Features\n\n- **P2P Messaging** — Real-time communication between agents via SSE\n- **Task Scheduling** — Create, assign, and track tasks across agents\n- **Shared Memory** — Three scopes: private, team, collective\n- **Zero External Dependencies** — Only Python stdlib required\n- **Auto-Reconnect** — Exponential backoff SSE reconnection\n- **Client-Side Dedup** — Built-in event deduplication\n\n## Install\n\n```bash\npip install agent-comm-hub\n```\n\n## Quick Start\n\n```python\nfrom hub_client import SynergyHubClient, create_client\n\n# Connect to a running Hub\nhub = SynergyHubClient(\"http://localhost:3100\")\n\n# Register (requires invite code from Hub admin)\nresult = hub.register(invite_code=\"YOUR_INVITE_CODE\", name=\"my-agent\")\nhub.set_token(result[\"api_token\"])\n\n# Send a message\nhub.send_message(to=\"other-agent\", content=\"Hello from Python!\")\n\n# Store collective memory\nhub.store_memory(\n content=\"User prefers JSON responses\",\n scope=\"collective\"\n)\n\n# Real-time SSE listener (blocking)\nhub.on_message = lambda msg: print(f\"Received: {msg}\")\nhub.connect_sse()\n```\n\n## Requirements\n\n- Python 3.9+\n- An [Agent Communication Hub](https://github.com/liuboacean/agent-comm-hub) server running (local or remote)\n\n## License\n\nMIT"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板 Skill: agent-comm-hub Owner: liuboacean Summary: 本地多智能体通信 Hub（MCP stdio / HTTP-SSE），提供消息、任务编排、共享记忆、进化引擎，暴露 58 个 MCP 工具 + Web 管理面板 Tags: 2.4.0:2.4.0, 2.4.1:2.4.1, agent:3.0.19, agent-comm:3.0.20, agent-comm-hub:3.0.25, ai-agents:1.0.0, audit-log:3.0.22, backup:3.0.25, communication:3.0.25, evolution:2.2.1, heartbeat:3.0.22, hermes:1.0.0, hub:3.0.25, infrastructure:3.0.20, latest:3.0.25, mcp:3.0.25, memory:3.0.25, mess","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1193,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T05:46:00.986Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T05:46:00.986Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T03:01:43.094Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}