Nexus: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

多 Agent 会话协调系统，由两部分组成：

• MCP Server — 中枢协调服务器，多个 Claude Code、Codex 会话通过它实现跨会话通信、状态共享、任务调度
• Coordinator Skill — .claude/skills/ 下的 canonical skill 文件，.agents/、.codex/ 提供客户端适配

技术栈

• 语言: TypeScript (strict mode)
• 运行时: Node.js 18+
• 数据库: SQLite (better-sqlite3) — 存储会话、任务、消息
• 协议: MCP (Model Context Protocol) — 官方 @modelcontextprotocol/sdk
• 构建: tsx (开发) + tsc (生产构建)
• 测试: vitest

常用命令

# 安装依赖
npm install

# 开发模式运行 MCP server
npx tsx src/server.ts

# 构建
npm run build

# 运行测试
npx vitest

# 运行单个测试文件
npx vitest run tests/session.test.ts

# 类型检查
npx tsc --noEmit

# Lint
npx eslint src/

# 运行软件研发全流程协同 8 步闭环 demo（缺陷聚合→RCA→修复→发布→复盘）
npx tsx scripts/demo-devflow.ts

架构

src/
├── server.ts          # MCP server 入口，注册所有 tools/resources
├── db.ts              # SQLite 数据库初始化和迁移
├── session.ts         # 会话管理 (register, heartbeat, status)
├── message.ts         # 消息传递 (send, get, ack)
├── task.ts            # 任务管理 (create, claim, update, list)
├── defects.ts         # 缺陷聚合与去重
├── approvals.ts       # 审批域（高风险变更强制人工审批）
├── releases.ts        # 发布与回滚（审批门禁 + 失败自动回滚）
├── retros.ts          # 复盘与知识沉淀（轻量 RAG 检索）
├── json.ts            # JSON 字段解析工具（SQLite 字符串 ↔ 对象）
├── types.ts           # 共享类型定义

.claude/skills/
├── coordinator/       # 通用多会话协调 skill（产品经理/规划师/开发/watchdog）
└── devflow/           # 软件研发全流程协同 skill
    ├── SKILL.md       # 入口：角色选择（6 个角色）
    ├── workflows.md   # 8 步闭环工作流
    └── agents/        # 每个角色的 SKILL.md（含 9 要素）

.agents/skills/
├── coordinator/
│   └── SKILL.md       # Codex 项目级适配入口
└── devflow/
    └── SKILL.md       # devflow 适配入口

scripts/
└── demo-devflow.ts    # 8 步闭环冒烟脚本（运行轨迹证据）

.codex/config.toml # Codex MCP 配置

tests/ ├── session.test.ts ├── message.test.ts └── task.test.ts

### 核心模块职责

- **session.ts** — 会话注册/注销、心跳维护、状态查询。每个客户端会话启动时调用 `register_session` 获取唯一 ID。
- **message.ts** — 异步消息队列。支持点对点消息和广播，消息有 TTL 和 ACK 机制。
- **task.ts** — 任务看板。支持创建/认领/更新/完成，任务有状态机（todo → in_progress → done/blocked），支持依赖关系和分配。
- **defects.ts** — 缺陷域。多源聚合 + 归一化 Jaccard 相似度去重（阈值可调），重复上报合并到规范缺陷并累积来源证据。
- **approvals.ts** — 审批域。高风险变更（high/critical）强制 rollback_plan；pending 超时自动 expired；approve/reject 记录审批人/时间/意见。
- **releases.ts** — 发布域。创建发布自动发起 high 风险审批；进入 testing 必须审批通过（服务端门禁）；版本唯一性强制；回滚记录 target_version/reason（幂等保护）。
- **retros.ts** — 复盘与知识域。复盘报告（根因/影响/改进措施）+ 知识条目（root-cause/fix-pattern/rule/lesson 标签），关键词+标签轻量 RAG 检索。

### MCP Tools 清单

| Tool | 说明 |
|------|------|
| `register_session` | 注册新会话，返回 session_id |
| `heartbeat` | 会话心跳，维持活跃状态 |
| `update_status` | 更新会话状态（idle/working/error） |
| `list_sessions` | 列出所有活跃会话 |
| `send_message` | 向指定会话发送消息 |
| `get_messages` | 获取待处理消息 |
| `ack_message` | 确认消息已处理 |
| `wait_for_work` | 统一等待消息/任务并自动心跳 |
| `wait_for_message` | 长轮询等待新消息 |
| `create_task` | 创建任务（含 spec/todo） |
| `claim_task` | 认领任务 |
| `update_task` | 更新任务状态/进度 |
| `list_tasks` | 按条件查询任务 |
| `watch_task` | 订阅任务变更通知 |
| `wait_for_task` | 长轮询等待指定任务变化 |
| `query_audit_logs` | watchdog/observer 查询审计日志 |
| `ingest_defect` | 录入缺陷（多源聚合），自动相似度去重合并重复上报 |
| `list_defects` | 按条件查询缺陷列表（状态/严重级别/来源） |
| `update_defect` | 更新缺陷（定级/分诊/关联 RCA/修复任务/关闭） |
| `request_approval` | 创建审批请求（高风险变更必须含回滚计划） |
| `list_approvals` | 查询审批请求（默认待审批） |
| `approve_request` / `reject_request` | 人工审批通过/拒绝（仅人工会话可调用） |
| `create_release` | 创建发布（自动发起人工审批，强制回滚计划） |
| `update_release` | 更新发布状态（testing/verifying/live/failed），含审批门禁 |
| `rollback_release` | 回滚发布（失败自动回滚，记录目标版本与原因） |
| `list_releases` | 查询发布历史 |
| `create_retro` / `list_retros` | 创建/查询复盘报告 |
| `publish_knowledge` | 沉淀知识条目到研发知识库 |
| `search_knowledge` / `list_knowledge` | 检索/查询知识库（轻量 RAG） |

## 设计原则

- **会话身份**: 每个客户端会话通过 `register_session` 获得唯一 ID，后续所有操作携带此 ID
- **消息是异步的**: 发送方不阻塞，接收方按需拉取。消息持久化在 SQLite 中
- **任务是共享真相源**: 所有会话看到同一个任务看板，状态变更原子化
- **心跳检测**: 超过 1 小时无心跳的会话标记为 stale，其持有的任务自动释放
- **客户端适配**: `.claude/skills/coordinator/` 是工作流真相源；Codex 入口只做适配，不复制业务规则