sinapse-ai 5.0.8 → 6.0.1

package/docs/zh/guides/agent-selection-guide.md

@@ -1,289 +0,0 @@
-# 代理选择指南
-
-> **EN** | [PT](../pt/guides/agent-selection-guide.md) | [ES](../es/guides/agent-selection-guide.md)
-
----
-
-## 选择正确代理的快速参考
-
-**最后更新:** 2026-01-29 (ADE v2.2.0)
-
----
-
-## 快速决策树
-
-```
-需要研究/分析? → @analyst
-   ↓
-需要PRD/史诗? → @pm
-   ↓
-需要架构? → @architect
-   ↓
-需要数据库? → @data-engineer
-   ↓
-需要故事? → @sm
-   ↓
-需要实现? → @dev
-   ↓
-需要测试/QA? → @qa
-   ↓
-需要部署? → @devops
-```
-
----
-
-## 代理快速参考
-
-| 代理 | 图标 | 用于 | 不用于 |
-|------|------|------|--------|
-| **@analyst** (Atlas) | 🔍 | 市场研究、竞争分析、头脑风暴、模式提取 | PRD创建、架构、故事 |
-| **@pm** (Morgan) | 📋 | PRD、史诗、产品战略、需求收集、规范编写 | 研究、架构、详细故事 |
-| **@architect** (Aria) | 🏛️ | 系统架构、API设计、技术栈、复杂度评估、实现规划 | 研究、PRD、数据库架构 |
-| **@data-engineer** (Dara) | 📊 | 数据库架构、RLS、迁移、查询优化 | 应用架构、DB技术选择 |
-| **@sm** (River) | 🌊 | 用户故事、冲刺规划、待办事项整理 | PRD、史诗、研究、实现 |
-| **@dev** (Dex) | 💻 | 故事实现、编码、测试、子任务执行、恢复 | 故事创建、部署 |
-| **@qa** (Quinn) | 🧪 | 代码审查、测试、质量保证、规范批评、结构化审查 | 实现 |
-| **@po** (Pax) | 🎯 | 待办事项管理、验收标准、优先级排序 | 史诗创建、架构 |
-| **@ux-design-expert** (Nova) | 🎨 | UI/UX设计、线框图、设计系统 | 实现 |
-| **@devops** (Gage) | ⚙️ | Git操作、PR创建、部署、CI/CD、工作树管理、迁移 | 本地Git、实现 |
-| **@sinapse-master** (Orion) | 👑 | 框架开发、多代理编排 | 日常任务（使用专门代理） |
-
----
-
-## 🤖 ADE命令按代理 (v2.2.0)
-
-### @devops (Gage) - 基础设施与运营
-
-**工作树管理:**
-| 命令 | 描述 |
-|------|------|
-| `*create-worktree {story}` | 为故事开发创建隔离的Git工作树 |
-| `*list-worktrees` | 列出所有活跃工作树及状态 |
-| `*merge-worktree {story}` | 合并已完成的工作树回到主分支 |
-| `*cleanup-worktrees` | 删除陈旧/已合并的工作树 |
-
-**迁移管理:**
-| 命令 | 描述 |
-|------|------|
-| `*inventory-assets` | 从V2资产生成迁移清单 |
-| `*analyze-paths` | 分析路径依赖和迁移影响 |
-| `*migrate-agent` | 将单个代理从V2迁移到V3格式 |
-| `*migrate-batch` | 批量迁移所有代理并验证 |
-
----
-
-### @pm (Morgan) - 产品管理
-
-**规范管道:**
-| 命令 | 描述 |
-|------|------|
-| `*gather-requirements` | 从利益相关者获取和文档化需求 |
-| `*write-spec` | 从需求生成正式规范文档 |
-
----
-
-### @architect (Aria) - 系统架构
-
-**规范管道:**
-| 命令 | 描述 |
-|------|------|
-| `*assess-complexity` | 评估故事复杂度和估计工作量 |
-
-**执行引擎:**
-| 命令 | 描述 |
-|------|------|
-| `*create-plan` | 创建包含阶段和子任务的实现计划 |
-| `*create-context` | 为故事生成项目和文件上下文 |
-
-**内存层:**
-| 命令 | 描述 |
-|------|------|
-| `*map-codebase` | 生成代码库地图（结构、服务、模式） |
-
----
-
-### @analyst (Atlas) - 研究与分析
-
-**规范管道:**
-| 命令 | 描述 |
-|------|------|
-| `*research-deps` | 研究依赖和技术约束 |
-
-**内存层:**
-| 命令 | 描述 |
-|------|------|
-| `*extract-patterns` | 提取和文档化代码库中的代码模式 |
-
----
-
-### @qa (Quinn) - 质量保证
-
-**规范管道:**
-| 命令 | 描述 |
-|------|------|
-| `*critique-spec {story}` | 审查和批评规范的完整性 |
-
-**QA演进（10阶段审查）:**
-| 命令 | 描述 |
-|------|------|
-| `*review-build {story}` | 10阶段结构化QA审查 - 输出qa_report.md |
-| `*request-fix {issue}` | 从@dev请求特定修复及上下文 |
-| `*verify-fix {issue}` | 验证修复是否正确实现 |
-
----
-
-### @dev (Dex) - 开发
-
-**执行引擎:**
-| 命令 | 描述 |
-|------|------|
-| `*execute-subtask` | 执行子任务，遵循13步工作流和自我批评 |
-
-**恢复系统:**
-| 命令 | 描述 |
-|------|------|
-| `*track-attempt` | 跟踪实现尝试（在recovery/attempts.json中注册） |
-| `*rollback` | 回滚到最后良好状态（--hard跳过确认） |
-
-**QA循环:**
-| 命令 | 描述 |
-|------|------|
-| `*apply-qa-fix` | 应用QA请求的修复（从qa_report.md读取上下文） |
-
-**内存层:**
-| 命令 | 描述 |
-|------|------|
-| `*capture-insights` | 捕获会话洞察（发现、模式、陷阱） |
-| `*list-gotchas` | 列出.sinapse/gotchas.md中的已知陷阱 |
-
----
-
-## 常见场景
-
-### "我想构建一个新功能"（传统方式）
-
-```
-1. @analyst *brainstorm - 构思
-2. @pm *create-prd - 产品需求
-3. @architect *create-architecture - 技术设计
-4. @data-engineer *create-schema - 数据库设计
-5. @sm *create-next-story - 用户故事
-6. @dev *develop - 实现
-7. @qa *review - 质量检查
-8. @devops *create-pr - 部署
-```
-
-### "我想使用ADE规范管道"（自主方式）
-
-```
-1. @pm *gather-requirements - 收集和结构化需求
-2. @architect *assess-complexity - 评估复杂度
-3. @analyst *research-deps - 研究库/API
-4. @pm *write-spec - 生成规范
-5. @qa *critique-spec - 验证规范质量
-   ↓
-[规范已批准]
-   ↓
-6. @architect *create-plan - 创建实现计划
-7. @architect *create-context - 生成上下文文件
-8. @dev *execute-subtask 1.1 - 执行13步+自我批评
-9. @qa *review-build - 10阶段QA审查
-   ↓
-[如果发现问题]
-   ↓
-10. @qa *request-fix - 请求修复
-11. @dev *apply-qa-fix - 应用修复
-12. @qa *verify-fix - 验证
-```
-
-### "我在实现上卡住了"
-
-```
-1. @dev *track-attempt - 记录失败的尝试
-2. @dev *rollback - 恢复到最后良好状态
-3. @dev *list-gotchas - 检查已知陷阱
-4. @dev *execute-subtask --approach alternative - 尝试不同方法
-```
-
-### "我需要理解现有代码库"
-
-```
-1. @architect *map-codebase - 生成结构/服务/模式地图
-2. @analyst *extract-patterns - 文档化代码模式
-3. @dev *capture-insights - 记录发现
-```
-
-### "我需要并行故事开发"
-
-```
-1. @devops *create-worktree STORY-42 - 隔离分支
-2. @dev *execute-subtask - 在隔离环境中工作
-3. @devops *merge-worktree STORY-42 - 完成时合并
-4. @devops *cleanup-worktrees - 清理陈旧分支
-```
-
----
-
-## 委派模式
-
-### 规范管道流
-
-```
-@pm *gather-requirements
-    ↓
-@architect *assess-complexity
-    ↓
-@analyst *research-deps
-    ↓
-@pm *write-spec
-    ↓
-@qa *critique-spec
-```
-
-### 执行流
-
-```
-@architect *create-plan
-    ↓
-@architect *create-context
-    ↓
-@dev *execute-subtask (循环)
-    ↓
-@qa *review-build
-```
-
-### QA循环
-
-```
-@qa *review-build
-    ↓ (发现问题)
-@qa *request-fix
-    ↓
-@dev *apply-qa-fix
-    ↓
-@qa *verify-fix
-    ↓ (循环直到清洁)
-```
-
-### 恢复流
-
-```
-@dev 失败子任务
-    ↓
-@dev *track-attempt
-    ↓
-重试 < 3? → @dev用变化重试
-    ↓
-@dev *rollback → 尝试不同方法
-```
-
----
-
-## 完整文档
-
-- **[ADE完整指南](./ade-guide.md)** - 自主开发引擎完整教程
-- **[代理责任矩阵](../architecture/agent-responsibility-matrix.md)** - 完整的边界定义
-
----
-
-**版本:** 2.0 | **ADE:** v2.2.0 | **日期:** 2026-01-29

package/docs/zh/guides/api-reference.md

@@ -1,427 +0,0 @@
-# SINAPSE API 参考
-
-> **[EN](../../guides/api-reference.md)** | **[PT](../../pt/guides/api-reference.md)** | **[ES](../../es/guides/api-reference.md)** | **ZH**
-
----
-
-SINAPSE 完整 API 参考 - AI 编排全栈开发系统。
-
-**版本：** 2.1.0
-**最后更新：** 2026-01-29
-
----
-
-## 目录
-
-1. [概述](#概述)
-2. [代理激活](#代理激活)
-3. [命令参考](#命令参考)
-4. [代理特定命令](#代理特定命令)
-5. [工作流 API](#工作流-api)
-6. [参数和选项](#参数和选项)
-7. [返回代码和错误](#返回代码和错误)
-8. [IDE 集成](#ide-集成)
-9. [示例](#示例)
-
----
-
-## 概述
-
-### API 架构
-
-SINAPSE 通过两个主要机制提供统一 API 来与专业 AI 代理交互：
-
-1. **代理激活** - 使用 `@` 前缀激活专业代理
-2. **命令执行** - 使用 `*` 前缀执行代理命令
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      SINAPSE API 层                             │
-├─────────────────────────────────────────────────────────────┤
-│  @agent         →  激活代理角色                               │
-│  *command       →  执行代理命令                               │
-│  *command args  →  使用参数执行命令                           │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    代理解析                                  │
-├─────────────────────────────────────────────────────────────┤
-│  .sinapse-ai/development/agents/{agent-id}.md                 │
-│  依赖项：任务、模板、检查清单、脚本                           │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 核心原则
-
-| 原则                   | 描述                                              |
-| ---------------------- | ------------------------------------------------- |
-| **任务优先**           | 一切都是任务。用户请求解析为任务执行。           |
-| **代理专业化**         | 每个代理都有明确定义的范围和责任                 |
-| **声明性命令**         | 命令描述意图，代理处理执行                       |
-| **渐进式增强**         | 简单命令扩展为复杂工作流                         |
-
----
-
-## 代理激活
-
-### 语法
-
-```
-@{agent-id}
-@{agent-id} *{command}
-@{agent-id} *{command} {arguments}
-```
-
-### 可用代理
-
-| 代理 ID          | 名称   | 原型    | 主要责任                           |
-| ---------------- | ------ | ------- | ---------------------------------- |
-| `@dev`           | Dex    | Builder | 代码实现、调试、测试               |
-| `@qa`            | Quinn  | Guardian| 质量保证、代码审查、测试           |
-| `@architect`     | Aria   | Visionary| 系统架构、API 设计                |
-| `@pm`            | Morgan | Strategist| 产品需求、史诗、战略            |
-| `@po`            | Pax    | Champion| 待办事项管理、验收标准             |
-| `@sm`            | River  | Facilitator| 冲刺规划、故事创建             |
-| `@analyst`       | Atlas  | Explorer| 市场研究、竞争分析                 |
-| `@data-engineer` | Dara   | Architect| 数据库架构、迁移、查询           |
-| `@devops`        | Gage   | Optimizer| CI/CD、部署、git 操作             |
-| `@ux-expert`     | Uma    | Creator | UI/UX 设计、线框图                 |
-| `@sinapse-master`   | Orion  | Orchestrator| 框架编排、元操作             |
-
-### 激活行为
-
-激活代理时：
-
-1. 从 `.sinapse-ai/development/agents/{id}.md` 加载代理定义文件
-2. 采用角色（语气、词汇、问候）
-3. 基于会话类型显示上下文问候
-4. 代理停止并等待用户输入
-
-```bash
-# 激活开发者代理
-@dev
-
-# 输出：
-# 💻 Dex (Builder) 已就绪。让我们创造伟大的东西！
-#
-# **快速命令：**
-# - *develop {story-id} - 实现故事任务
-# - *run-tests - 执行 linting 和测试
-# - *help - 显示所有命令
-```
-
-### 使用命令激活
-
-您可以在一个步骤中激活代理并执行命令：
-
-```bash
-@dev *develop story-1.2.3
-@qa *review story-1.2.3
-@architect *create-full-stack-architecture
-```
-
----
-
-## 命令参考
-
-### 通用命令
-
-这些命令在所有代理中可用：
-
-| 命令            | 描述                    | 示例            |
-| --------------- | ----------------------- | --------------- |
-| `*help`         | 显示所有可用命令        | `*help`         |
-| `*guide`        | 显示综合使用指南        | `*guide`        |
-| `*session-info` | 显示当前会话详情        | `*session-info` |
-| `*exit`         | 退出当前代理模式        | `*exit`         |
-| `*yolo`         | 切换确认跳过            | `*yolo`         |
-
-### 命令语法
-
-```
-*{command}
-*{command} {positional-argument}
-*{command} {arg1} {arg2}
-*{command} --{flag}
-*{command} --{option}={value}
-```
-
-### 命令解析
-
-命令解析为代理依赖项中的任务文件：
-
-```
-*develop story-1.2.3
-    │
-    ▼
-.sinapse-ai/development/tasks/dev-develop-story.md
-    │
-    ▼
-带参数的任务执行：{ story: "story-1.2.3" }
-```
-
----
-
-## 代理特定命令
-
-### @dev (开发者)
-
-**故事开发：**
-
-| 命令                  | 参数          | 描述                                          |
-| --------------------- | ------------- | --------------------------------------------- |
-| `*develop`            | `{story-id}`  | 实现故事任务（模式：yolo、交互、预检）       |
-| `*develop-yolo`       | `{story-id}`  | 自主开发模式                                 |
-| `*develop-interactive`| `{story-id}`  | 交互开发模式（默认）                         |
-| `*develop-preflight`  | `{story-id}`  | 实现前规划模式                               |
-
-**子任务执行（ADE）：**
-
-| 命令              | 参数            | 描述                                  |
-| ----------------- | --------------- | ------------------------------------- |
-| `*execute-subtask`| `{subtask-id}`  | 执行单个子任务（13 步代码代理工作流）|
-| `*verify-subtask` | `{subtask-id}`  | 验证子任务完成                       |
-
-**恢复系统：**
-
-| 命令            | 参数            | 描述                 |
-| --------------- | --------------- | -------------------- |
-| `*track-attempt`| `{subtask-id}`  | 跟踪实现尝试         |
-| `*rollback`     | `[--hard]`      | 回滚到最后良好状态   |
-
-**构建操作：**
-
-| 命令                | 参数          | 描述                         |
-| ------------------- | ------------- | ---------------------------- |
-| `*build`            | `{story-id}`  | 完整自主构建管道             |
-| `*build-autonomous` | `{story-id}`  | 启动自主构建循环             |
-| `*build-resume`     | `{story-id}`  | 从检查点恢复构建             |
-| `*build-status`     | `[--all]`     | 显示构建状态                 |
-| `*build-log`        | `{story-id}`  | 查看构建尝试日志             |
-
-**质量和技术债：**
-
-| 命令              | 参数      | 描述                      |
-| ----------------- | --------- | ------------------------- |
-| `*run-tests`      | -         | 执行 linting 和所有测试   |
-| `*apply-qa-fixes` | -         | 应用 QA 反馈和修复        |
-| `*backlog-debt`   | `{title}` | 注册技术债务项目          |
-
-**Worktree 隔离：**
-
-| 命令                | 参数          | 描述                 |
-| ------------------- | ------------- | -------------------- |
-| `*worktree-create`  | `{story-id}`  | 创建隔离的 worktree  |
-| `*worktree-list`    | -             | 列出活跃的 worktree  |
-| `*worktree-merge`   | `{story-id}`  | 将 worktree 合并回基础 |
-| `*worktree-cleanup` | -             | 删除完成的 worktree  |
-
-**内存层：**
-
-| 命令                | 参数                              | 描述                |
-| ------------------- | --------------------------------- | ------------------- |
-| `*capture-insights` | -                                 | 捕获会话见解        |
-| `*list-gotchas`     | -                                 | 列出已知陷阱        |
-| `*gotcha`           | `{title} - {description}`         | 手动添加陷阱        |
-| `*gotchas`          | `[--category X] [--severity Y]`   | 列出和搜索陷阱      |
-
----
-
-## 工作流 API
-
-### 可用工作流
-
-| 工作流                 | 描述                 | 参与代理           |
-| ---------------------- | -------------------- | ------------------ |
-| `greenfield-fullstack` | 新的全栈项目         | 所有代理           |
-| `greenfield-service`   | 新微服务             | architect、dev、qa |
-| `greenfield-ui`        | 新前端项目           | architect、ux、dev |
-| `brownfield-fullstack` | 向现有项目添加功能   | architect、dev、qa |
-| `brownfield-service`   | 扩展现有服务         | dev、qa            |
-| `brownfield-ui`        | 扩展现有前端         | ux、dev、qa        |
-
-### 工作流执行
-
-```bash
-# 启动工作流
-@sinapse-master *workflow greenfield-fullstack
-
-# 带参数
-*workflow brownfield-service --target=./services/auth
-```
-
-### 工作流结构
-
-```yaml
-# 工作流定义示例
-name: greenfield-fullstack
-phases:
-  - name: research
-    agent: analyst
-    tasks:
-      - brainstorm
-      - competitive-analysis
-  - name: planning
-    agent: pm
-    tasks:
-      - create-prd
-  - name: architecture
-    agent: architect
-    tasks:
-      - create-full-stack-architecture
-  - name: implementation
-    agent: dev
-    tasks:
-      - develop
-```
-
----
-
-## 参数和选项
-
-### 全局选项
-
-| 选项         | 类型    | 描述                 |
-| ------------ | ------- | -------------------- |
-| `--verbose`  | boolean | 启用详细输出         |
-| `--dry-run`  | boolean | 预览而不执行         |
-| `--force`    | boolean | 强制操作             |
-| `--help`     | boolean | 显示命令帮助         |
-
-### 故事参数
-
-| 参数          | 类型   | 描述          | 示例                         |
-| ------------- | ------ | ------------- | ---------------------------- |
-| `{story-id}`  | string | 故事标识符    | `story-1.2.3`、`STORY-42`    |
-| `--status`    | enum   | 故事状态过滤器| `draft`、`ready`、`complete` |
-| `--epic`      | string | 按史诗过滤    | `--epic=AUTH`                |
-
-### 构建参数
-
-| 参数            | 类型   | 描述              | 示例                           |
-| --------------- | ------ | ----------------- | ------------------------------ |
-| `--mode`        | enum   | 构建模式          | `yolo`、`interactive`、`preflight` |
-| `--retry`       | number | 最大重试次数      | `--retry=3`                    |
-| `--checkpoint`  | string | 从检查点恢复      | `--checkpoint=build-001`       |
-
-### 审查参数
-
-| 参数            | 类型   | 描述          | 示例                         |
-| --------------- | ------ | ------------- | ---------------------------- |
-| `--scope`       | enum   | 审查范围      | `uncommitted`、`committed`   |
-| `--base`        | string | 基础分支      | `--base=main`                |
-| `--severity`    | enum   | 最小严重级别  | `critical`、`high`、`medium` |
-
----
-
-## 返回代码和错误
-
-### 标准返回代码
-
-| 代码 | 状态     | 描述                               |
-| ---- | -------- | ---------------------------------- |
-| `0`  | SUCCESS  | 操作成功完成                       |
-| `1`  | ERROR    | 常规错误                           |
-| `2`  | BLOCKED  | 操作被阻止（需要批准）             |
-| `3`  | HALTED   | 操作停止（需要用户干预）           |
-| `4`  | SKIP     | 操作跳过                           |
-| `5`  | TIMEOUT  | 操作超时                           |
-
-### 错误类别
-
-| 类别                 | 描述                         | 解决方案                           |
-| -------------------- | ---------------------------- | ---------------------------------- |
-| `AGENT_NOT_FOUND`    | 缺少代理定义                 | 检查 `.sinapse-ai/development/agents/` |
-| `TASK_NOT_FOUND`     | 缺少任务定义                 | 检查代理依赖项                     |
-| `STORY_NOT_FOUND`    | 找不到故事文件               | 验证 `docs/stories/` 路径          |
-| `VALIDATION_FAILED`  | 前提条件不符                 | 检查先决条件                       |
-| `PERMISSION_DENIED`  | 不允许的操作                 | 检查代理限制                       |
-| `DEPENDENCY_MISSING` | 缺少必需依赖项               | 安装或配置依赖项                   |
-
-### 错误响应格式
-
-```json
-{
-  "status": "error",
-  "code": "VALIDATION_FAILED",
-  "message": "故事状态必须是 'Ready for Dev' 才能开始实现",
-  "context": {
-    "story": "story-1.2.3",
-    "currentStatus": "Draft",
-    "requiredStatus": "Ready for Dev"
-  },
-  "suggestions": ["更新故事状态为 'Ready for Dev'", "联系 @pm 批准故事"]
-}
-```
-
-### 质量门控决定
-
-| 决定       | 描述                         | 操作                  |
-| ---------- | ---------------------------- | --------------------- |
-| `PASS`     | 所有标准都符合               | 继续到下一阶段        |
-| `CONCERNS` | 发现次要问题                 | 记录并谨慎继续        |
-| `FAIL`     | 发现关键问题                 | 必须在继续前修复      |
-| `WAIVED`   | 已确认问题，继续进行         | 记录豁免原因          |
-
----
-
-## IDE 集成
-
-### 支持的 IDE
-
-| IDE         | 目录      | 格式            | 支持级别 |
-| ----------- | --------- | --------------- | -------- |
-| Claude Code | `.claude/`| Markdown        | 完整     |
-| Cursor      | `.cursor/ `| MDC (frontmatter)| 完整    |
-| VS Code     | `.vscode/ `| JSON            | 部分     |
-| Gemini      | `.gemini/ `| Markdown        | 基础     |
-
-### Claude Code 集成
-
-Claude Code 是主要支持的 IDE，拥有完整集成：
-
-**代理命令（斜杠命令）：**
-
-```
-/dev          → 激活 @dev 代理
-/qa           → 激活 @qa 代理
-/architect    → 激活 @architect 代理
-/sinapse-master  → 激活 @sinapse-master 代理
-```
-
----
-
-## 示例
-
-### 示例 1：完整故事实现
-
-```bash
-# 1. 激活开发者代理
-@dev
-
-# 2. 开始故事实现
-*develop story-1.2.3
-
-# 3. 运行测试
-*run-tests
-
-# 4. 检查已知陷阱
-*list-gotchas
-
-# 5. 退出开发者模式
-*exit
-
-# 6. 切换到 QA
-@qa
-
-# 7. 审查故事
-*review story-1.2.3
-
-# 8. 创建质量门控
-*gate story-1.2.3
-```
-
----
-
-_SINAPSE API 参考 v4.0.4_