aiox-core 5.0.0

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

@@ -0,0 +1,289 @@
+# 代理选择指南
+
+> **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、实现 |
+| **@aiox-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` | 列出.aiox/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

@@ -0,0 +1,427 @@
+# AIOX API 参考
+
+> **[EN](../../guides/api-reference.md)** | **[PT](../../pt/guides/api-reference.md)** | **[ES](../../es/guides/api-reference.md)** | **ZH**
+
+---
+
+Synkra AIOX 完整 API 参考 - AI 编排全栈开发系统。
+
+**版本：** 2.1.0
+**最后更新：** 2026-01-29
+
+---
+
+## 目录
+
+1. [概述](#概述)
+2. [代理激活](#代理激活)
+3. [命令参考](#命令参考)
+4. [代理特定命令](#代理特定命令)
+5. [工作流 API](#工作流-api)
+6. [参数和选项](#参数和选项)
+7. [返回代码和错误](#返回代码和错误)
+8. [IDE 集成](#ide-集成)
+9. [示例](#示例)
+
+---
+
+## 概述
+
+### API 架构
+
+AIOX 通过两个主要机制提供统一 API 来与专业 AI 代理交互：
+
+1. **代理激活** - 使用 `@` 前缀激活专业代理
+2. **命令执行** - 使用 `*` 前缀执行代理命令
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      AIOX API 层                             │
+├─────────────────────────────────────────────────────────────┤
+│  @agent         →  激活代理角色                               │
+│  *command       →  执行代理命令                               │
+│  *command args  →  使用参数执行命令                           │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    代理解析                                  │
+├─────────────────────────────────────────────────────────────┤
+│  .aiox-core/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 设计、线框图                 |
+| `@aiox-master`   | Orion  | Orchestrator| 框架编排、元操作             |
+
+### 激活行为
+
+激活代理时：
+
+1. 从 `.aiox-core/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
+    │
+    ▼
+.aiox-core/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
+# 启动工作流
+@aiox-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`    | 缺少代理定义                 | 检查 `.aiox-core/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 代理
+/aiox-master  → 激活 @aiox-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
+```
+
+---
+
+_Synkra AIOX API 参考 v4.0.4_