用途
AgentNexus 是一个协调异构 LLM 编程智能体的 MCP 服务器。它面向的真实场景是：产品并不是单一代码库，而是由后端、前端、基础设施、测试套件等多个独立仓库、技术栈与智能体组成。当后端改变 API 时，前端必须适配；传统做法要么靠人把规格复制进聊天，要么维护手写的 CLAUDE.md / AGENTS.md 文件，一旦服务变化就会过时。
该项目强调协调发生在“服务边界”（service boundary）这一真实系统的构建单元上，而非假设所有智能体处于同一模拟组织、同一代码库的角色扮演式多智能体框架。
主要能力
- 版本化文档存储：SHA-256 去重、完整版本历史、按边界命名空间隔离。
- 发布订阅通知：可按精确文档 ID 或文档类型订阅。
- 差分感知更新：get_my_updates_with_context 一次调用返回统一差分（unified diff）与完整最新内容，便于智能体做针对性修改、无需人工介入。
- 控制面 / 数据面分离：协调信号（什么变了、谁该响应）通过 MCP 传递；文档正文通过普通 HTTP POST /api/documents 带外传输，正文从不作为 MCP 工具参数传入，因此任意大小的文档在写入路径上零模型 token 成本——token 只花在协调上，不花在内容上。
- SDAOP（服务驱动智能体接入协议）：由服务在连接时生成并交付客户端专属的接入文件，而非由人维护静态文件。按客户端类型生成对应产物——.kiro/steering/、CLAUDE.md、AGENTS.md 或 .cursor/rules/——并附带已写入服务器 URL 的推送工具脚本。每份产物按内容哈希版本化；服务器约定变化或服务器迁移到新 URL 时版本递增，已连接的工作区检测到漂移后会重新接入。支持客户端：kiro、claude、codex、cursor。
- Planner：只读、跨边界的观察者，提供 planner_chat、planner_plan、planner_overview，回答任何单一智能体无法回答的跨边界问题。
- MCP HTTP 服务器：streamable-HTTP 传输，多个智能体可同时连接。
- FTS5 全文搜索：search_documents 支持 BM25 排序、短语 / 前缀 / 布尔查询。
- Web 仪表盘 + AI Chat：在浏览器中浏览空间、子项目与文档，运行全文搜索，并使用内置 AI Chat 进行对话式文档问答与服务规划。
- 337 个测试：单元测试 + 基于属性的测试（Hypothesis）。
使用方式
启动后打开 http://localhost:10086/ 即可浏览空间、子项目与文档、运行全文搜索，并使用内置 AI Chat。入门无需单独的数据库迁移或 .env：一切都有合理默认值；仅当需要改端口、指向 Postgres 或启用 Planner LLM 时，才把 .env.example 复制为 .env。
文档写入的主路径是带外写入端点：内容通过 HTTP body 传输，从不进入 LLM 上下文。支持可选的 base_version 用于乐观并发控制（快进检查）。
从 Kiro 或任意 MCP 客户端连接。仓库同时提供 Docker 运行方式；为在重启后保留文档与数据库，需挂载卷（具体命令与配置详见仓库说明，此处不展开）。
LLM 配置：AI Chat 需要 PLANNER_LLM_API_KEY。可设置 PLANNER_LLM_PROVIDER（openai 或 anthropic）、PLANNER_LLM_MODEL，以及可选的 PLANNER_LLM_BASE_URL（Azure / Ollama / 兼容 API）。不设置该 key 时 AI 功能禁用，浏览 / 搜索功能仍保留。
适用场景
- 多个独立仓库 / 服务由不同智能体（后端、前端、基础设施等）分别维护，且存在跨服务的接口依赖。
- 运行在不同 IDE、不同模型上的智能体需要自动保持同步，避免手写粘合代码。
- 希望通过版本化文档、结构化差分与订阅机制替代易过期的静态接入文件。
- 需要跨边界问答与规划（如“某接口变更会影响哪些子项目”）。
限制与说明
- 与 MIT Lincoln Laboratory 的同名项目无关联。
- 角色扮演式多智能体框架（ChatDev、MetaGPT）的假设（同一模拟组织、同一代码库）不适用于本工具针对的真实分布式系统场景。
- 文档中给出的具体端口（如 10086）与默认值以仓库实际内容为准；Docker 运行的具体命令、卷挂载方式原文未完整展开，此处不编造。
- AI Chat 依赖外部 LLM API key，未配置时相关 AI 功能不可用。
- 项目附带研究论文位于 paper/ 目录，包括 agentnexus-v4.md（当前版，将协调单元从服务泛化为所有权边界，并引入控制 / 数据面分离与 Planner）、agentnexus-v3.md（引入 SDAOP）、agentnexus.md（v2）。引用：dugubuyan. AgentNexus: A Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents (v4). Zenodo, 2026. https://doi.org/10.5281/zenodo.21257426
