用途
Network-AI 是一个基于 TypeScript/Node.js 的多智能体编排器，用于为任意 AI 智能体栈添加协调、护栏和治理。它解决的核心问题是多智能体系统中的“静默失败模式”：并行智能体默认按“最后写入胜出”的方式写入同一个键，一个智能体的结果会静默覆盖另一个智能体的结果，导致脑裂状态——重复支出、决策矛盾、上下文损坏，且不抛出任何错误。Network-AI 通过 propose → validate → commit 互斥机制，在协调层、任何写入到达共享状态之前就阻止这种情况。
主要能力
- 带锁的共享黑板：原子化的 propose → validate → commit 流程，防止并行智能体之间的竞态条件和脑裂故障。
- 护栏与预算：FSM 治理、按智能体的 token 上限、HMAC / Ed25519 审计追踪、权限门控。
- 上下文信号降噪（v5.15）：ContextComposer 组装按 token 预算、相关性排序的上下文包（语义/词汇 × 近期衰减 × 作用域亲和度，位置感知布局）；context_pack + blackboard_search MCP 工具让智能体拉取整理好的状态，而不是把整个黑板倒进窗口。
- 32 个适配器：LangChain（+ 流式）、AutoGen、CrewAI、OpenAI Assistants、OpenAI Responses、LlamaIndex、Semantic Kernel、Haystack、DSPy、Agno、MCP、Custom（+ 流式）、OpenClaw、A2A、Codex、MiniMax、NemoClaw、APS、Copilot、LangGraph、Anthropic Computer Use、Claude Agent SDK（智能体循环）、OpenAI Agents SDK、Vertex AI、Gemini（Developer API）、Pydantic AI、Browser Agent、Hermes、Orchestrator（分层多编排器）、RLM（递归语言模型 / 任何 RLM 兼容的 HTTP 端点）——无需胶水代码、无锁定。
- 持久项目记忆（Layer 3）：context_manager.py 将决策、目标、技术栈、里程碑和禁用模式注入每个系统提示，使智能体始终拥有完整的项目上下文。
- v5.0 模块：Agent VCR（录制/回放）、对比运行器、覆盖率报告器、目标 DSL、审批收件箱、作业队列、gRPC/HTTP 传输、playground REPL、适配器测试框架等。
- 模型交互生命周期治理（v5.13）：GovernedModelGateway 将模型拒绝 → 回退 → 计费链吸收到一次受治理、受预算约束、可审计的调用背后（跨模型回退、回退信用重定价、努力治理、思考块交接）。
使用方式
可将 Network-AI 作为以下形态使用：
- TypeScript/Node.js 库：
import { createSwarmOrchestrator } from 'network-ai' - MCP 服务器：
npx network-ai-server --port 3001 - CLI：
network-ai bb get status/network-ai audit tail - Claude Code 插件：
/plugin install network-ai@network-ai - Gemini CLI 扩展：
gemini extensions install https://github.com/Jovancoding/Network-AI - OpenClaw 技能：
clawhub install network-ai
作为 MCP 服务器启动（无需配置、零依赖）：npx network-ai-server --port 3001，然后将任意 MCP 兼容客户端接入。支持的 MCP 工具包括：blackboard_read / blackboard_write / blackboard_list / blackboard_delete / blackboard_exists、context_pack、blackboard_search、budget_status / budget_spend / budget_reset、token_create / token_validate / token_revoke、audit_query、config_get / config_set、agent_list / agent_spawn / agent_stop、fsm_transition。每个工具接受一个 agent_id 参数，记录为每次写入的来源智能体。
MCP 服务器选项：--no-budget、--no-token、--no-control、--ceiling <n>、--board <name>、--audit-log <path>。
Claude Code 插件：从自托管市场安装（无需审批）：/plugin install network-ai@network-ai。插件底层运行 npx -y -p network-ai network-ai-server --stdio（stdio MCP 传输），因此始终使用已发布的 npm 包。可用 claude plugin validate . 在本地验证清单。
OpenAI Codex：使用一条命令添加（使用已发布的 npm 包）。仓库根目录附带 .codex/config.toml，任何受信任的检出都会自动拾取该服务器；也可放入 ~/.codex/config.toml 全局注册。在 Codex TUI 中运行 /mcp 确认 network-ai 已连接。
Gemini CLI：仓库根目录附带 gemini-extension.json，自动接入 stdio MCP 服务器和 GEMINI.md 上下文文件。在 Gemini CLI 中运行 /mcp 确认工具已加载。
CLI：全局标志包括 --data <path>（数据目录，默认 ./data）、--env <name>（环境）、--json（机器可读输出）、--minimal（跳过 WAL 重放 + 清扫，用于 CI/测试快速启动）。
Claude / ChatGPT / Codex：仓库根目录包含三个集成文件。Custom GPT Actions 可在 GPT 编辑器 → Actions → Import from URL，或粘贴 openapi.yaml 内容，将服务器 URL 设为运行中的 npx network-ai-server --port 3001 实例。Claude Projects 可将 claude-project-prompt.md（水平规则下方）内容复制到 Claude Project 的 Custom Instructions 字段，指令模式无需服务器。
适用场景
- 需要在同一共享状态上协调多个并行智能体、避免竞态条件的团队。
- 在现有 LangChain 链、CrewAI 团队和 AutoGen 智能体之上添加共享状态、治理和预算——Network-AI 是叠加在现有栈之上的协调层，无需替换现有框架。
- 需要按智能体 token 预算、权限门控和审计追踪的多智能体应用。
- 需要跨模型回退、拒绝处理、努力策略和思考块管理的模型交互治理。
- 将编排器作为可发现的 A2A 智能体暴露给 Google Agent2Agent 生态。
限制
- 作为 MCP 服务器时，信任边界是传输认证（SSE/HTTP 上的 bearer secret，或本地 stdio）：一旦客户端被接纳，服务器以服务器持有的随机身份代表其写入，因此任意 agent_id 均可用，无需知晓共享 token。通过 MCP 时调用方提供的 agent_token 值会被忽略。进程内 TypeScript 代码通过 registerAgent() 保留按智能体的 token 和命名空间。
- 适配器无依赖（BYOC——自带客户端），需要用户提供自己的 SDK 对象。
- 无原生依赖、无构建步骤。
- 对 Claude Code 的 AuthGuardian 钩子支持 --mode observe（默认，审计而不阻断）与 --mode enforce（将工具映射到资源类型，需要 AuthGuardian 授权，被拒绝的调用会升级为交互式提示）。--deny 模式在两种模式下均硬阻断，并匹配工具名称及工具输入的每个字符串字段。--allow 模式仅匹配工具名称和主目标。无效或易回溯的模式会使钩子以退出码 2 退出，Claude Code 将其视为阻断，因此坏规则会失败关闭而非静默禁用拒绝列表。
- 包含 3,679 个通过断言，跨 41 个测试套件（
npm run test:all）。 - 许可证为 MIT。
