coordinator
by MT-gar
README.md
# 星火协程 — 多Agent协同调度系统
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
> **核心能力**：跨会话协调 + 缺陷聚合 + 审批门禁 + 发布回滚 + 复盘知识沉淀
多个 Claude Code / Codex 会话通过 **MCP 协议**实现跨会话通信、状态共享、任务调度，覆盖软件研发 8 步闭环：缺陷录入 → 聚合去重 → RCA → 任务 DAG → 修复 → 审批 → 发布 → 回滚 → 复盘 → 知识沉淀。
---
## 🎯 核心能力一览
| 能力域 | 功能 | 技术亮点 |
|--------|------|----------|
| **缺陷聚合** | 多源录入 + Jaccard 去重 | 归一化相似度 0.6 阈值，重复上报自动合并证据 |
| **审批门禁** | 高风险变更强制人工审批 | rollback_plan 必填，pending 超时自动 expired |
| **发布回滚** | 审批通过才能测试，失败自动回滚 | 版本唯一性约束 + 幂等保护 + 全链路审计 |
| **复盘知识** | 根因/影响/改进措施 + 知识库 | 轻量 RAG（关键词+标签检索），可替换向量检索 |
| **任务调度** | 依赖 DAG + 自动 unblock | 任务状态机 + metadata 扩展支持学生竞赛场景 |
| **会话协调** | 心跳检测 + stale 清理 | 超 1 小时无心跳释放任务，watchdog 只读监督 |
| **消息传递** | 点对点 + 广播 + TTL + ACK | 异步队列 + 长轮询 `wait_for_work` 统一接口 |
| **审计日志** | 11 种域操作全留痕 | session/task/message/defect/approval/release/retro/knowledge 8 域 |
---
## 🚀 快速开始
### 1. 安装依赖
```bash
npm install
```
### 2. 启动 MCP Server（开发模式）
```bash
npm run dev
```
**预期输出**：
```
MCP Server (stdio): coordinator
Listening on stdio (pid 12345)
Database initialized: data.db
Available tools: 77
Available resources: 3
```
### 3. 配置客户端接入
**Claude Code** — 编辑 `~/.claude/mcp_settings.json`：
```json
{
"mcpServers": {
"coordinator": {
"command": "node",
"args": ["/path/to/nexus/dist/server.js"],
"env": {}
}
}
}
```
将 `/path/to/nexus` 替换为本项目在你本机的实际路径。开发模式可改用 `npx tsx /path/to/nexus/src/server.ts`。
**Codex** — 参考 `.codex/config.toml` 示例配置。
**项目级接入** — 复制根目录 `.mcp.json.example` 为 `.mcp.json`，按本机路径修改后即可在该项目内自动生效。
### 4. 运行 8 步闭环 Demo
```bash
npx tsx scripts/demo-devflow.ts
```
**预期输出**：完整工作流轨迹（缺陷录入 → 聚合 → RCA → 修复 → 审批 → 发布 → 回滚 → 复盘），证明 5 大域模块联动正确。
---
## 🏗 架构概览
### 设计模式：Manager-Workers
```
┌─────────────────────────────────────────────────────────┐
│ MCP Server │
│ ┌───────────┐ ┌───────────┐ ┌──────────┐ │
│ │ Session │ │ Message │ │ Task │ │
│ │ Manager │ │ Queue │ │ Scheduler│ │
│ └───────────┘ └───────────┘ └──────────┘ │
│ │
│ ┌───────────┐ ┌───────────┐ ┌──────────┐ │
│ │ Defect │ │ Approval │ │ Release │ │
│ │ Aggregate │ │ Gate │ │ Pipeline │ │
│ └───────────┘ └───────────┘ └──────────┘ │
│ │
│ ┌───────────────────────────────────────────┐ │
│ │ Retro + Knowledge (Lightweight RAG) │ │
│ └───────────────────────────────────────────┘ │
│ │
│ SQLite (WAL mode) │
└─────────────────────────────────────────────────────────┘
↑ ↑
│ │
Claude Code Codex
(Manager) (Worker)
```
### 8 大域模块职责
1. **会话域** (`session.ts`) — 注册/心跳/状态，stale 自动清理
2. **任务域** (`task.ts`) — 创建/认领/更新，依赖 DAG + auto-unblock
3. **消息域** (`message.ts`) — 点对点/广播，TTL + ACK
4. **缺陷域** (`defects.ts`) — 多源录入 + Jaccard 去重 + 定级分诊
5. **审批域** (`approvals.ts`) — 高风险变更强制回滚计划 + 人工审批
6. **发布域** (`releases.ts`) — 审批门禁 + 版本唯一性 + 失败回滚
7. **复盘域** (`retros.ts`) — 根因/影响/改进措施 + 知识沉淀
8. **知识域** (`retros.ts`) — 轻量 RAG（关键词+标签检索）
### 数据流：8 步闭环
```
缺陷录入 → 去重合并 → 分诊定级 → RCA 任务 → 修复任务 → 代码审查
↓
知识沉淀 ← 复盘报告 ← 回滚恢复 ← 发布失败 ← 审批通过 ← 人工审批
```
---
## ✅ 运行验证
```bash
npx tsx scripts/demo-devflow.ts
```
输出 STEP 1–9 完整轨迹，覆盖缺陷录入 → 聚合去重 → RCA → 修复 → 审批 → 发布 → 回滚 → 复盘 → 知识沉淀，
用于验证 8 大域模块联动正确。
---
## 🛠 开发者指南
### 本地开发
```bash
# 安装依赖
npm install
# 开发模式（自动重启）
npm run dev
# 构建生产版本
npm run build
# 运行生产版本
npm start
# 类型检查
npx tsc --noEmit
# 运行测试（watch 模式）
npx vitest
# 运行测试（单次）
npx vitest run
```
### 项目结构
```
src/
├── server.ts # MCP server 入口，注册所有 tools/resources
├── db.ts # SQLite 数据库初始化和迁移（含并发安全修复）
├── session.ts # 会话管理 (register, heartbeat, status)
├── message.ts # 消息传递 (send, get, ack, wait_for_work)
├── task.ts # 任务管理 (create, claim, update, list)
├── defects.ts # 缺陷聚合与去重（Jaccard 相似度，事务保护）
├── approvals.ts # 审批域（强制回滚计划 + 人工审批，原子更新）
├── releases.ts # 发布与回滚（审批门禁 + 版本唯一性 + 幂等保护）
├── retros.ts # 复盘与知识沉淀（轻量 RAG 检索，事务保护）
└── types.ts # 共享类型定义
.claude/skills/
├── coordinator/ # 通用多会话协调 Skill（4 角色）
└── devflow/ # 软件研发全流程协同 Skill（6 角色 + 8 步闭环）
├── SKILL.md # 入口：角色选择
├── workflows.md # 8 步闭环工作流
└── agents/ # 每个角色的 SKILL.md（9 要素完整）
.agents/skills/ # Codex 适配入口
tests/ # 单元测试（vitest）
├── session.test.ts
├── message.test.ts
├── task.test.ts
├── defects.test.ts
└── ...
scripts/
└── demo-devflow.ts # 8 步闭环冒烟脚本（输出运行轨迹）
```
### 扩展开发
**添加新 Tool**：
1. 在对应域模块（如 `task.ts`）实现业务逻辑
2. 在 `server.ts` 注册 Tool schema + handler
3. 添加单元测试到 `tests/`
4. 更新审计日志枚举（若新增域操作）
**添加新 Skill**：
1. 在 `.claude/skills/` 下创建目录
2. 编写 `SKILL.md`（9 要素：目标/角色/输入/处理/输出/校验/异常/示例/限制）
3. 若支持 Codex，在 `.agents/` 添加适配入口
4. 在 `README.md` 的核心能力一览中同步登记
---
## 🔬 技术栈对比
| 技术选型 | 当前方案 | 推荐升级方向（生产环境） |
|---------|---------|------------------------|
| **数据库** | SQLite (better-sqlite3) | PostgreSQL / MySQL（多服务器部署） |
| **消息队列** | 内存 + SQLite | Redis Streams / RabbitMQ |
| **去重算法** | Jaccard 相似度（确定性） | 向量检索（Embedding + FAISS） |
| **知识检索** | 关键词 + 标签匹配 | 语义向量检索（OpenAI Embedding + Pinecone） |
| **审计日志** | SQLite 表 | Elasticsearch / Loki |
| **监控告警** | 无（手动查询） | Prometheus + Grafana + Alertmanager |
当前实现**刻意选择零第三方依赖**（除 MCP SDK + better-sqlite3），确保 `npm install` 后即可快速启动。生产环境建议按上表升级。
---
## 📝 许可证
MIT License — 详见 [LICENSE](LICENSE)。
## 🙏 致谢
- **MCP Protocol** — [Model Context Protocol](https://modelcontextprotocol.io/) 官方规范
- **AgentTeams** — Manager-Workers 设计模式参照
- **Claude Code / Codex** — 多会话客户端支持
---
## 📮 联系方式
- **Issues**: [GitHub Issues](https://github.com/MT-gar/Nexus/issues)
- **Repository**: [github.com/MT-gar/Nexus](https://github.com/MT-gar/Nexus)
- **Documentation**: Skill 体系见 `.claude/skills/`（coordinator + devflow）
**快速上手**：运行 `npx tsx scripts/demo-devflow.ts` 验证全链路 → 查看 Skill 体系 `.claude/skills/devflow/`。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessUnresponsive