weichenandCursor
e4b4e0dde8
Use the record tables when migration 00059 is present, and hide statements from documents the caller cannot see. Co-authored-by: Cursor <cursoragent@cursor.com>
系统设计文档索引
项目：项目对话与任务协同系统（基于 PI-agent 的智能体小队协作系统）
范围：核心架构组件的技术报告
📋 报告清单
1. 意图识别框架
| 项 | 链接 |
|---|---|
| 主报告 | intent-recognition/01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md |
| 一句话总结 | 纯规则 + 四级漏斗 + 三分支消解的 L1 协作对话层 |
核心要点：
- 18 类 IntentType：业务核心（6）+ 法定文档治理（7）+ 决策与合规查询（4）+ 安全红线（1）
- 三分支柔性消解：EXPECTATION_HIT（极速兑现）/ NEW_INTENT_PREEMPT（新意抢占）/ AMBIGUOUS_FALLBACK（模糊分忧）
- 复合打补丁（Patch Merge）：把"好，但 X 改成 Y" 这类中文复合输入正确解析为"肯定上轮 + 增量事实"
- 法定文档治理完整覆盖：审核驳回、终审批准、认领、送审、提案裁决，附带角色-状态-动作三元约束
- 多输出策略：top-1 + 完整 candidates 列表，由 L2 协调层做终审兜底
- 完全可重放：纯规则实现，无 LLM 调用，无随机性，27K 行测试代码
2. 智能体小队编排
| 项 | 链接 |
|---|---|
| 主报告 | agent-squad/02-智能体小队编排-设计-思路-架构-实现-难点-解决方案-亮点与优势.md |
| 一句话总结 | 角色-任务-工作区-黑板四元模型 + 沙箱化执行 + 动态工作流 + 三层质量门禁 |
核心要点：
- 8 大标准专员 + 任意派生特设专员：organizer / searcher / regulatory / engineer / market / finance / writer / leader
- 角色-任务-工作区-黑板四元模型：职责清晰、解耦彻底、状态可恢复
- 任务级沙箱隔离：每个任务一个独立目录，并发安全、可重放、可审计
- 动态工作流 + 材料嗅探：识别"牛心包"自动追加生物相容性专员；识别"射频+EMC"自动追加 EMC 专项
- Backend 抽象层：PI-agent / Cursor CLI / Stub 三种实现 + 并发限流包装器
- SSE 步骤事件流：实时推送步骤进度，前端可视化
- 三层质量门禁：章节完整度 + 禁用词 + 模板占位符 + sha256 防篡改清单
- 零外部依赖：仅 Go 标准库，纯文件持久化，可 git 管理
3. 多轮对话优化
| 项 | 链接 |
|---|---|
| 主报告 | multi-turn-dialogue/03-多轮对话优化-设计-架构-实现-难点-解决方案-亮点与优势.md |
| 一句话总结 | 断链修复 + 三层记忆（工作/短期/长期）+ 滑动窗口双预算 + 滚动摘要 + DST 状态跟踪 + 对话向量库按需召回 + 规则查询改写 + 十段式 Prompt + 多级缓存 |
核心要点：
- P0 断链修复：
RecentDialogue/PersonalizedGuidance生产链路从未填充、RestoreSessionContext零调用——三大断点先接线，既有部件（三分支/黑板/偏好反射/pgvector）即刻协同 - 三层记忆模型：工作记忆（
task_stateDST）/ 短期记忆（轮数+token 双预算滑动窗口）/ 长期记忆（用户画像 +chat_history向量域） - 历史压缩：滚动摘要（LLM 生成 + 规则降级），硬事实区永不压缩，黑板 SSOT 优先级兜底
- 按需检索：意图触发的记忆召回（TopK≤3 + 篇幅闸门），SQL 权限过滤 + Prompt 隐私条款双闸门
- 查询改写：5 条确定性规则（省略补全/代词消解/主题合并/槽位补全/概念合成），永不进入意图识别链路
- 十段式 Prompt 规范：分段硬分隔 + 逐轮编号 + 来源标注 + 优先级声明 + CiteKey 引用回溯闭环
- 多级缓存 C1~C5：检索/改写/embedding/上下文组装/摘要，写入口主动失效，一键可关
- 五阶段渐进路线：P0 修复 → P1 上下文 → P2 检索 → P3 改写 → P4 系统层，全部可独立回滚
4. 文档修改、智能体版本与差异认知
| 项 | 链接 |
|---|---|
| 主报告 | document-revision-management.md |
| 一句话总结 | 智能体/模板定义 Version、人工保存定义 Revision，以不可变快照支撑人工高亮、任意版本比较、AI 变更报告和负责人通知 |
核心要点：
- 当前右侧文档只标记 latest agent baseline → current head 的人工修改；
- 下次智能体提交原子封存旧版本并开启新版本，人工高亮随 baseline 前移而归零；
- 真实 diff、血缘影响和风险下限由服务端确定，LLM 提供可读解释但不能改写事实；
- 人、单智能体和智能体小队均保存不可变 actor snapshot；
- 版本、报告、lineage/stale 和通知 outbox 同事务提交。
5. 纯软件项目自举工作流
| 项 | 链接 |
|---|---|
| 主报告 | 2026-09-14-software-project-bootstrap-workflow.md |
| 一句话总结 | 一次性 Bootstrap 建立可信基线，可重复 Delivery 承接迭代；复用治理引擎，隔离医疗语义和代码执行权限 |
核心要点：
- 七步项目创建向导，分离 product domain、project type、compliance、governance 和 execution mode；
software_bootstrap与software_delivery两条工作流串联，创建者确认推进；- 复用通用智能体角色和小队治理，通过软件领域 profile 增强；
- 单人模式不伪造三权，持续标记“未独立评审”；
- 首期 docs-only/read-only，后续代码执行必须隔离 worktree 并分段审批。
6. 模块化单体解耦架构
| 项 | 链接 |
|---|---|
| 主报告 | 2026-09-14-module-decoupling-architecture.md |
| ADR | ../adr/2026-09-14-modular-monolith-decoupling.md |
| 开发规范（入口） | 2026-09-20-module-development-standards.md |
| 耦合审计 | ../audit/2026-09-20-module-coupling-audit.md |
| 整改计划 | ../remediation/2026-09-14-module-decoupling-refactor-plan.md |
| 一句话总结 | 先以文档可靠性纵向试点验证事务、锁、授权、事件与 FAV，再按证据扩展模块边界 |
核心要点：
- 单一写者负责 SQL 和不变量，应用 UnitOfWork 负责跨属主原子提交；
- 数据库行锁、事务级 advisory lock、唯一约束和 fencing token 支撑多副本并发；
- workspace 是可清理投影，FAV 只保存已确认终态成果；
- 事件采用逐消费者 delivery、幂等 inbox、租约、重试和 dead letter；
- HTTP、CLI、worker、subscriber 和恢复工具使用同一逐动作授权模型；
- 先原地端口化，行为稳定后才物理搬包。
7. 多意图持久计划与 HITL
硬边界：确认不等于授权；PG 是计划真相，卡片/SSE 是投影；写动作按 owner 端口逐项接入；LLM 只能提出不可信分段建议。
8. 个人中控台（已移出本仓库）
项目开发进度由独立的统一管理系统负责，不再是本仓库功能。本仓库只保留智能体系统。旧只读工程中控台的历史设计仍在 ../archive/design/2026-09-17-personal-engineering-control-center-plan.md，代码不恢复。
9. 阶段回溯与影响闭环
| 项 | 链接 |
|---|---|
| 主设计 | 2026-09-20-stage-backtrack-and-impact-loop-design.md |
| 追踪索引基线 | ../remediation/2026-09-20-capability-enablement-impact-plan.md |
| 一句话总结 | 修改自动产生影响报告；默认只修订文档，必要时再打开已完成阶段；未复核不拦截推进 |
核心要点：
- 沿用五表追踪索引，不另建一套需求表。
- L1 保持阶段
completed；L2 只解锁勾选文档，并允许与后面的活动阶段并存。 - 不占用实例状态
awaiting_stage_confirmation。 - 待复核标记只能人关；推进前必须知悉，知悉不等于闭环。
- 候选边由下游编制人裁决。追踪数据留存类别是
record。
🏗️ 在整体架构中的位置
┌──────────────────────────────────────────────────────────────┐
│ L1 协作对话层 (internal/chat, internal/intent) │
│ ↓ │
│ 意图识别框架（本报告 #1） │
│ ↓ │
│ 候选意图 + 置信度 │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ L2 项目协调层 (internal/coordinator) │
│ ↓ │
│ 校验权限、状态、依赖 │
│ 决定接受 / 拒绝 / 排队 / 追问 │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ L3 任务执行层 (internal/squad + internal/agent) │
│ ↓ │
│ 智能体小队编排（本报告 #2） │
│ ↓ │
│ Markdown / Excel / 结构化字段 │
└──────────────────────────────────────────────────────────────┘
📊 两份报告的对比
| 维度 | 意图识别框架 | 智能体小队编排 |
|---|---|---|
| 层级 | L1 协作对话层 | L3 任务执行层 |
| 核心职责 | 把自然语言分类为业务意图 | 把业务意图执行为结构化产出 |
| 关键模块 | internal/intent/ (~1500 行) |
internal/squad/ + internal/agent/ (~3250 行) |
| 设计哲学 | 纯规则、四级漏斗、三分支 | 四元模型、沙箱化、自适应 |
| 亮点 | 复合打补丁 / 多分支消解 / 反歧义 | 角色派生 / 动态规划 / 质量门禁 |
| 可解释性 | 100%（规则+佐证） | 100%（规则+文件落盘） |
| 测试覆盖 | 24 个 TestXxx 函数 | 单元测试 + 集成测试 |
| 依赖 | 零 | 仅 Go 标准库 |
| 是否需要 LLM | 否（纯规则） | 是（Backend 抽象层调用） |
📁 目录结构
.doc/system-design/
├── README.md ← 本文件（顶层索引）
├── document-revision-management.md ← 文档版本、修订、差异、报告与通知
├── intent-recognition/
│ └── 01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md
├── agent-squad/
│ └── 02-智能体小队编排-设计-思路-架构-实现-难点-解决方案-亮点与优势.md
├── multi-turn-dialogue/
│ └── 03-多轮对话优化-设计-架构-实现-难点-解决方案-亮点与优势.md
└── project-workflow/
├── 03-项目多工作流与智能产品经理-测试经理工作流-设计方案.md
├── 04-项目多工作流与智能产品经理-测试经理工作流-实施计划.md
├── 05-Phase0-基线确认与契约冻结.md
└── 06-Phase7-全链路验收与发布基线.md
├── 2026-09-14-module-decoupling-architecture.md ← 模块化单体解耦
├── 2026-09-20-module-development-standards.md ← 开发者入口：契约 / 接口 / 故障隔离
├── 2026-09-20-stage-backtrack-and-impact-loop-design.md ← 阶段回溯与影响闭环
.tmp/ ← 中间分析文件
├── intent-recognition/
│ ├── README.md
│ ├── code-inventory.md
│ ├── intent-types-anatomy.md
│ ├── three-branch-flow.md
│ └── test-coverage-matrix.md
└── agent-squad/
├── README.md
├── code-inventory.md
├── role-registry-anatomy.md
├── workflow-execution-flow.md
├── blackboard-pattern.md
├── dynamic-adjustment-rules.md
└── quality-gate-rules.md
🔗 相关资源
- 架构总览：.doc/system-design/architecture-design.md（已有的项目骨架设计文档）
- 测试报告：.doc/test-reports/（多轮多角色端到端测试报告）
- 历史功能设计：.doc/archive/design/superpowers/