记录一下基于cursor 专家系统的构成
背景： 前面使用mcp 构建的专家系统，存在上下文填充过快、且记忆能力不及预期、复用的时候比较繁琐的问题。再学习了一些AI流水线的写法之后，尝试优化一下，后续在工作中使用。
Cursor 多专家协作系统
一套运行在 Cursor IDE 中的多智能体协作框架，让 AI 在复杂任务中像专业团队一样分工、协作、互审。
一、设计理念
传统 AI 编程助手面临两个根本问题：
- 单点失效：一个 AI 同时负责需求理解、架构设计、代码实现、质量审查，容易在某个环节出现盲点却无人纠偏
- 上下文遗忘：对话越长越失控，跨会话几乎无法继续复杂任务
本系统的核心思路：专家分工 + 文件持久化 + 置信度门控。
- 每个专家只做自己擅长的一件事，不越界
- 所有中间产物写入文件，跨会话可恢复
- 每个环节输出置信度分数，低于阈值自动触发补救机制
二、系统架构全貌
用户指令
│
▼
┌─────────────────────────────────────────────────────────┐
│ [前置工具层] │
│ analyze-mode（并行上下文收集 + 路由建议） │
└─────────────────────┬───────────────────────────────────┘
│ analyze_summary（可选，自动消费）
▼
┌─────────────────────────────────────────────────────────┐
│ [统筹专家 Orchestrator] │
│ │
│ Step 1.5 路由判断（自动门控） │
│ 全部低 → 路径A: 直接实施 │
│ 1项高 → 路径B: 方案+实施 │
│ 2+项高 → 路径C: 完整流程 │
│ │
│ Brief 生成 → Task 派发 → Report 收集 → 产物整合 │
└──┬──────────┬──────────┬──────────┬─────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
[需求专家] [方案专家] [实施专家] [审查专家]
│ │ │ │
│ discussion_mode │ Step 4.5
│ 自我质疑循环 │ 修复闭环
│ │ │ (Critical→修复→重审)
│ │ [Git专家] │
│ │ 每步提交 │
▼ ▼ ▼ ▼
PRD 方案文档 代码变更 审查报告
└──────────┴──────────┴──────────┘
│
.expert/ 文件系统
│
cursor-mem 持久记忆
三、核心组件
3.1 专家角色一览
| 专家 | 文件 | 职责 | 输出产物 |
|---|---|---|---|
| 统筹专家 | orchestrator | 路由判断、任务分解、Brief 派发、进度汇报 | plan.json、status.json、checkpoint.md |
| 需求专家 | requirements-expert | 需求分析、PRD 编写、验收标准制定 | prd-v{N}.md |
| 方案专家 | solution-expert | 技术方案设计、自评迭代、架构决策 | solution-v{N}.md |
| 实施专家 | impl-expert | 原子步骤执行、逐步验证、修复 | 代码文件 |
| 审查专家 | review-expert | 代码审查、PRD 验收、问题分级 | review-report.md |
| Git 专家 | git-expert | 临时分支管理、每步提交、变更溯源 | expert/* 分支 |
| UI 专家 | ui-expert | 界面一致性检查、组件规范审查 | UI 审查报告 |
| 前置分析 | analyze-mode | 并行上下文收集、复杂度评估、路由建议 | analyze_summary |
| 会话恢复 | resume-session | 从检查点重建上下文、无缝继续任务 | — |
| 系统初始化 | init-expert | 创建 .expert/ 目录结构和项目规则模板 | .expert/ 目录 |
3.2 统筹专家（Orchestrator）——控制中枢
统筹专家是整个系统的大脑，负责把用户的一句话变成多专家的协作任务。
工作流程：
Step 1 读取项目上下文（CONTEXT.md、registry.json、global.md）
↓
Step 1.5 轻量路由判断（改动范围 × 需求清晰度 × 架构影响）
↓
Step 2 任务分解（按路由结果选择专家组合）
↓
Step 2.5 双轨 Skill 探测（本地流程专家 + 社区技术增强）
↓
Step 3 生成 Brief 文件，通过 Task 工具派发专家
↓
Step 4 监控进度，定期汇报 status.json
↓
Step 4.5 审查闭环（若有 Critical，触发修复循环，最多 2 轮）
↓
Step 5 整合产物，更新 CONTEXT.md，写入最终检查点
路由判断示例：
路由判断：路径 B（1 项高：架构影响）
计划专家：方案专家 → 实施专家
3.3 方案专家（Solution Expert）——自我质疑机制
方案专家有两种工作模式：
标准模式：输出方案 → 四维自评（可行性/完整性/风险控制/可维护性）→ 低于 75 分自动修订（最多 2 轮）
Discussion Mode（高架构影响任务自动开启）：
初稿
↓
从反对角度提出 3 个最强质疑
↓
逐一答辩并修订
↓
终稿（质量显著提升）
Discussion Mode 不需要第二个 AI，同一个专家用不同角色质疑自己，是成本最低的质量保障机制。
3.4 审查闭环（Step 4.5）
审查专家发现 🔴 Critical 问题后，系统自动进入修复循环：
审查专家 Report（有 Critical）
↓
生成修复 Brief → 实施专家修复
↓
重审 Brief → 审查专家重新验证
↓
若无 Critical → 通过
若仍有 Critical 且已达 2 轮 → 上报用户决策
问题严重程度分级：
| 级别 | 含义 | 处理要求 |
|---|---|---|
| 🔴 Critical | 功能缺失/逻辑错误/安全漏洞 | 必须修复，触发闭环 |
| 🟡 Warning | 质量问题/边界未处理/潜在风险 | 记录 issues，建议修复 |
| 🟢 Suggestion | 可读性/性能优化/最佳实践 | 可选 |
3.5 Git 专家——安全边界
Git 专家有一条不可逾越的核心原则：
所有变更只落到
expert/临时分支，绝不直接提交到主分支。
工作时机：
- 任务开始 → 创建
expert/YYYYMMDD-task-slug分支 - 每个实施步骤验证通过 → 立即提交（可溯源到原子步骤）
- 任务完成 → 输出分支摘要，提示用户选择后续操作
绝对禁止：
--no-verify（跳过 pre-commit hook）push --force- 自动合并到主分支
四、通信协议
4.1 Brief / Report 文件系统
专家之间通过文件传递任务和结果，不依赖对话上下文：
.expert/sessions/{session_id}/
├── plan.json ← 统筹专家的任务计划
├── status.json ← 实时进度状态
├── checkpoint.md ← 最新检查点（每次覆盖）
├── briefs/
│ ├── requirements-expert.json
│ ├── solution-expert.json
│ └── impl-expert.json
└── reports/
├── requirements-expert.json
├── solution-expert.json
└── review-report.md
Brief 关键字段：
{
"objective": "任务目标",
"context_brief": "项目背景摘要（来自 analyze-mode 或 CONTEXT.md）",
"input_artifacts": ["输入文件路径列表"],
"suggested_skills": ["推荐加载的 SKILL.md 路径"],
"project_rules": {
"global": "global.md 内容",
"expert_specific": "专家专属规则内容"
},
"constraints": {
"discussion_mode": true
},
"output_spec": { "path": "产物输出路径" }
}
Report 关键字段：
{
"expert": "solution-expert",
"status": "completed | needs_review | failed",
"confidence": 82,
"artifacts": ["方案文档路径"],
"issues": ["遗留问题描述"]
}
4.2 置信度（Confidence）处理规则
| 专家 | 置信度 < 阈值 | 处理方式 |
|---|---|---|
| 方案专家 | < 75 | 自动触发修订，最多 2 轮；仍低则开启 discussion_mode |
| 实施专家 | < 70 | 统筹专家派发修复任务 |
| 审查专家 | < 60 | 触发 Step 4.5 修复闭环 |
五、双轨 Skill 系统
这是本系统的独特设计，两类 Skill 定位不同：
┌─────────────────────────────────────────────────────┐
│ Track A：流程控制层（~/.cursor/skills/） │
│ 专家系统角色：需求专家、方案专家、实施专家... │
│ 作用：定义谁在什么时候做什么 │
│ 管理：Cursor 原生，Glob 工具扫描 │
├─────────────────────────────────────────────────────┤
│ Track B：技术增强层（~/.claude/skills/） │
│ 社区最佳实践：Next.js 规范、测试标准、API 设计... │
│ 作用：增强专家在特定技术域的能力 │
│ 管理：npx openskills CLI │
└─────────────────────────────────────────────────────┘
统筹专家在派发任务前，会同时扫描两个轨道，将匹配结果写入 Brief 的 suggested_skills 字段，让执行专家按需加载。
六、持久化记忆层
系统通过三层机制保证跨会话连续性：
┌──────────────────────────────────────────┐
│ cursor-mem MCP │
│ 存储：关键决策、错误记录、重要观察 │
│ 特点：语义检索，轻量，适合小型状态 │
├──────────────────────────────────────────┤
│ CONTEXT.md │
│ 存储：项目背景、技术栈、完成任务历史 │
│ 特点：人类可读，Git 追踪，项目级 │
├──────────────────────────────────────────┤
│ .expert/sessions/*/checkpoint.md │
│ 存储：任务进度、待办、中断位置 │
│ 特点：精确到步骤，/resume 时直接恢复 │
└──────────────────────────────────────────┘
自动写入检查点的时机：
- 每个专家任务完成后
- 对话轮次超过 15 轮
- 遇到大量工具输出（预防上下文爆满）
- 用户说"暂停"、"先记一下"
七、项目文件结构
{your-project}/
├── CONTEXT.md ← 项目记忆锚点（手动维护）
├── .expert/
│ ├── registry.json ← 可用专家注册表
│ ├── rules/
│ │ ├── global.md ← 所有专家共用的项目规则
│ │ ├── impl-expert.md ← 实施专家专属规则
│ │ ├── ui-expert.md ← UI 专家专属规则
│ │ └── review-expert.md ← 审查专家专属规则
│ ├── materials/ ← 放需求文档、设计稿等输入物料
│ ├── sessions/ ← 运行时状态（.gitignore 忽略）
│ └── reports/ ← 专家输出产物
└── .gitignore ← 已自动添加 .expert/sessions/
八、快速上手
8.1 初始化
/init-expert
自动检测项目信息，创建 .expert/ 目录结构和规则模板。
8.2 启动任务
启动专家，帮我实现用户登录功能
统筹专家自动完成路由判断 → 选择专家组合 → 开始协作。
8.3 查看进度
/status
展示当前所有专家的状态和置信度。
8.4 恢复会话
/resume
从最新检查点重建上下文，继续中断的任务。
8.5 手动分析（可选前置）
[analyze-mode] 帮我重构数据层
并行收集上下文，输出复杂度评估和执行路径建议，统筹专家启动时自动消费此结果。
九、核心设计原则
| 原则 | 体现 |
|---|---|
| 单一职责 | 每个专家只做一件事，边界在 SKILL.md 的"不做"列表中明确声明 |
| 最小信任 | Git 专家只操作 expert/ 分支，从不自动合并；合并需用户授权 |
| 可观测性 | 每步有置信度分数，每个会话有 checkpoint，全程可追溯 |
| 优雅降级 | 无检查点用 CONTEXT.md，无 CONTEXT.md 用 cursor-mem，三者均无提示用户 |
| 规则优先级 | project_rules > SKILL.md 全局规则，项目级约束始终生效 |
| 并行优化 | 只读的分析/搜索任务并行，写文件的实施任务串行，避免冲突 |
十、与 Claude Code 的设计差异
| 维度 | Claude Code | 本系统（Cursor） |
|---|---|---|
| 并行机制 | 真正后台 agent（run_in_background） | 同一轮多工具调用 |
| 并发写文件 | worktree 物理隔离 | 串行实施，避免冲突 |
| 工具调用 | 完整 bash 环境 | Cursor Tool 套件 |
| 记忆持久化 | 无内置机制 | cursor-mem + 文件系统双保险 |
| 自我质疑 | 需要两个 LLM | discussion_mode 单 LLM 自我质疑 |
