@gong-ym/ai-spec-auto 0.2.17 → 0.2.19

package/.agents/orchestration/runtime-state-handoff-spec.md

@@ -237,7 +237,99 @@ frontend-implementer（前端实现专家）
 - 追加一条 `run-cancelled` 事件
 - 记录 `timestamps.finished_at`
 
-## 7. 当前阶段边界
+## 7. 上下文传递优化（Context Pass-through）
+
+### 7.1 问题背景
+
+当前每个专家都需要独立加载以下上下文：
+
+- `context/PROJECT.md`
+- `.agents/rules/` 下的项目规则
+- `openspec/changes/<change-id>/` 下的变更文档
+- 前序专家的分析产物
+
+这导致：
+
+- 重复读取相同文件
+- 每个专家都要重新解析项目规则
+- 上下文信息在多轮对话中逐渐稀释
+
+### 7.2 上下文传递机制
+
+当发生专家交接时，handoff payload 应携带 `context_payload`：
+
+```json
+{
+  "context_payload": {
+    "project_facts": {
+      "tech_stack": "Vue 3 + TypeScript + Vite",
+      "directory_structure": "src/views/, src/components/",
+      "api_pattern": "@/utils/request",
+      "style_pattern": "主题变量 + Tailwind"
+    },
+    "current_change": {
+      "change_id": "add-product-delete",
+      "proposal_path": "openspec/changes/add-product-delete/proposal.md",
+      "tasks_path": "openspec/changes/add-product-delete/tasks.md",
+      "specs_dir": "openspec/changes/add-product-delete/specs/"
+    },
+    "previous_analysis": {
+      "requirement_summary": "给商品卡片加删除按钮，点击后调用 DELETE API",
+      "key_decisions": ["沿用项目 Button 组件", "删除前弹确认框"],
+      "open_questions": []
+    },
+    "rules_snapshot": {
+      "loaded_rules": ["01-项目概述.md", "03-项目结构.md", "05-API规范.md", "09-样式规范.md"],
+      "key_constraints": ["API 必须使用 @/utils/request 封装", "样式必须使用主题变量"]
+    }
+  }
+}
+```
+
+### 7.3 下游专家行为
+
+当收到 `context_payload` 时，下游专家应：
+
+1. **优先使用传递的上下文**：不再重复读取已包含的文件
+2. **按需补充读取**：只读取 `context_payload` 中未覆盖的规则
+3. **继承前序分析**：直接引用 `previous_analysis` 中的结论，不重新分析
+
+### 7.4 简单需求直接交接
+
+当 `delivery_profile = micro` 且 `complexity = low` 时，允许：
+
+- `requirement-analyst` 完成后直接产出 `frontend-implementer` 的执行载荷
+- `task-orchestrator` 只做状态记录，不做额外干预
+- 实现专家直接读取 `context_payload` 进入编码
+
+## 8. 并行分析阶段（可选）
+
+### 8.1 适用场景
+
+当复杂需求同时触发多个可选专家时：
+
+- `requirement-analyst` 完成基础分析
+- `design-collaborator` 分析设计约束
+- `api-contract-specialist` 分析接口契约
+
+### 8.2 并行执行模式
+
+```
+requirement-analyst（完成基础分析）
+    ↓
+    ├─ design-collaborator（并行分析）
+    └─ api-contract-specialist（并行分析）
+    ↓
+frontend-implementer（合并分析结果后进入实现）
+```
+
+### 8.3 实现约束
+
+- 并行专家必须基于同一份 `context_payload`
+- 各专家产出独立文档，不互相依赖
+- `task-orchestrator` 在所有并行专家完成后合并结果
+
+## 9. 当前阶段边界
 
 当前最小实现只解决：
 

package/.agents/orchestration/task-orchestrator-run-plan-template.md

@@ -211,7 +211,34 @@ description: 定义 task-orchestrator 在首次识别任务时必须输出的最
   - 多状态联动、真实接口、复杂业务规则、核心模块改造
   - 使用完整产物与完整门禁
 
-### 5.6 micro 的产物规格
+### 5.6 简单需求快速通道
+
+当 `delivery_profile = micro` 且 `complexity = low` 时，启用快速通道：
+
+**简单需求判断标准**（满足全部）：
+- 单文件或 2-3 个文件的修改
+- 任务明确（如"加个按钮"、"改个样式"、"加个校验"）
+- 不涉及新模块、新路由、新接口
+- 无需设计稿或复杂交互
+- 项目规则中已有明确实现模式
+
+**快速通道行为**：
+1. `requirement-analyst` 跳过 `design-analysis` 调用
+2. `proposal.md` 使用极简版（目标、范围、假设，各 1-2 行）
+3. `specs/` 使用极简版（只写变更点，不写完整场景）
+4. `tasks.md` 使用极简版（3-5 条直接可执行任务）
+5. 快速进入实现，不做详细澄清
+
+**复杂需求**（命中任一）：
+- 涉及多个模块或系统级变更
+- 需要新接口、新状态管理、新路由设计
+- 有设计稿或复杂交互需求
+- 存在技术选型或架构决策
+- 规则不明确，需要大量澄清
+
+复杂需求按完整流程执行，不做快速通道优化。
+
+### 5.7 micro 的产物规格
 
 当 `delivery_profile = micro` 时：
 
@@ -219,7 +246,8 @@ description: 定义 task-orchestrator 在首次识别任务时必须输出的最
 - `tasks.md` 使用短版：3-5 条可执行任务
 - `checklist.md` 使用短版：关键检查项、阻断项、是否建议通过
 - `iterations.md` 使用短版：问题、修正动作、残留风险
-- 不允许因为是 `micro` 而跳过专家或跳过 OpenSpec 落盘
+- 对于简单需求（见 5.6），`requirement-analyst` 可采用快速通道行为
+- 不允许因为 `micro` 而跳过 OpenSpec 落盘
 
 ### 5.7 page-development 任务的缺口分类
 
@@ -289,6 +317,59 @@ description: 定义 task-orchestrator 在首次识别任务时必须输出的最
 - 先按默认假设进入 requirement-analyst（需求解析专家）；若需求收敛阶段发现高风险冲突，再转 suggest 或 manual
 ```
 
+### 简单需求示例（快速通道）
+
+#### 输入
+
+```text
+@task-orchestrator（任务主代理） 给商品卡片加个删除按钮
+```
+
+#### 输出
+
+```md
+## 任务识别
+- 类型：组件增强
+- 当前输入：给商品卡片加个删除按钮
+- 风险级别：low
+- 复杂度：low（单文件修改，任务明确）
+
+## 推荐流程模板
+- `selected_flow（选中的流程模板）`：prd-to-delivery
+- 原因：简单增强任务，适合快速通道
+
+## 运行模式
+- `mode（运行模式）`：auto
+
+## 交付档位
+- `delivery_profile（交付档位）`：micro
+- `artifact_profile（产物规格）`：compact
+- `complexity（复杂度）`：low
+
+## 快速通道
+- 已识别为简单需求，启用快速通道
+- requirement-analyst 跳过 design-analysis
+- 文档采用极简版
+
+## 推荐专家
+- 必选：frontend-implementer（前端实现专家）、code-guardian（规范守护者）
+- 可选：requirement-analyst（需求解析专家）
+- 第一跳：requirement-analyst（需求解析专家）
+
+## 默认假设
+- 沿用项目现有组件结构和样式规范
+- 删除按钮样式沿用项目 Button 组件
+
+## 缺失输入
+- 无
+
+## 审批点
+- 暂无
+
+## 下一步
+- 直接进入快速通道，requirement-analyst 生成极简文档后快速进入实现
+```
+
 ## 7. 一句话约束
 
 > `task-orchestrator（任务主代理）` 的首轮输出必须先形成结构化 `run-plan（运行计划）`；在 `auto（自动）` 模式下，应先做仓库推断并记录 `assumptions（默认假设）`，不默认回问用户，只有高风险关键分歧才转 `suggest（建议）` 或 `manual（手动）`。

package/.agents/roles/common/requirement-analyst.md

@@ -43,6 +43,31 @@ handoff_to:
 - 输出必须服务后续实现与验收，不写空泛汇报材料
 - 专家不是发明新方案，而是通过 `rules + skills + OpenSpec` 收敛到当前项目可实施方案
 
+## 复杂度快速判断
+
+**简单需求（快速通道）** - 满足以下全部条件：
+- 单文件或 2-3 个文件的修改
+- 任务明确（如"加个按钮"、"改个样式"、"加个校验"）
+- 不涉及新模块、新路由、新接口
+- 无需设计稿或复杂交互
+- 项目规则中已有明确实现模式
+
+**快速通道行为**：
+1. 跳过 `design-analysis` 调用
+2. `proposal.md` 使用短版（目标、范围、假设，各 1-2 行）
+3. `specs/` 使用短版（只写变更点，不写完整场景）
+4. `tasks.md` 使用短版（3-5 条直接可执行任务）
+5. 直接进入实现，不做详细澄清
+
+**复杂需求（完整分析）** - 命中以下任一条件：
+- 涉及多个模块或系统级变更
+- 需要新接口、新状态管理、新路由设计
+- 有设计稿或复杂交互需求
+- 存在技术选型或架构决策
+- 规则不明确，需要大量澄清
+
+**完整分析行为**：按下方"必做步骤"执行完整流程。
+
 ## 必做步骤
 
 1. 读取任务输入、项目背景、`role_rule_contract`、`repo_conventions`

package/bin/protocol-workflow.js

@@ -431,7 +431,12 @@ async function main(mode, argv) {
   }
 
   if (options.json) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    const output = `${JSON.stringify(result, null, 2)}\n`;
+    // 确保 stdout 完整写入后再退出，避免 spawnSync 截断
+    process.stdout.write(output);
+    if (process.stdout.writableLength > 0) {
+      await new Promise((resolve) => process.stdout.once('drain', resolve));
+    }
   } else {
     if (mode === 'advance') {
       printStep(result);

package/bin/refresh-command.js

@@ -115,56 +115,29 @@ function refresh(targetDir, pkgRoot) {
     updated.push('openspec/config.yaml.template');
   }
 
-  // 4. 同步 IDE 命令文件
+  // 4. 同步 IDE 配置文件（跳过指针文件，只同步实际目录）
+  // IDE 的 commands/rules/skills 可能是指向 .agents/ 的指针文件（非目录），
+  // 这些指针文件不需要替换，因为 .agents/ 已经在步骤 1 中同步过了。
   const ides = ['cursor', 'claude', 'qoder', 'trae', 'opencode'];
   for (const ide of ides) {
     const sourceIdeDir = path.join(sourceDir, `.${ide}`);
     const targetIdeDir = path.join(targetDir, `.${ide}`);
     if (!fs.existsSync(sourceIdeDir) || !fs.existsSync(targetIdeDir)) continue;
 
-    // 同步 commands
-    const srcCmdDir = path.join(sourceIdeDir, 'commands');
-    const destCmdDir = path.join(targetIdeDir, 'commands');
-    if (fs.existsSync(srcCmdDir)) {
-      try {
-        if (fs.existsSync(destCmdDir)) {
-          fs.rmSync(destCmdDir, { recursive: true, force: true });
-        }
-        copyDirSync(srcCmdDir, destCmdDir);
-        updated.push(`.${ide}/commands/`);
-      } catch (error) {
-        skipped.push({ path: `.${ide}/commands/`, reason: error.message });
-      }
-    }
-
-    // 同步 rules（如果是实际文件而非 symlink）
-    const srcRulesDir = path.join(sourceIdeDir, 'rules');
-    const destRulesDir = path.join(targetIdeDir, 'rules');
-    if (fs.existsSync(srcRulesDir) && !isSymlink(destRulesDir)) {
-      try {
-        if (fs.existsSync(destRulesDir)) {
-          fs.rmSync(destRulesDir, { recursive: true, force: true });
-        }
-        copyDirSync(srcRulesDir, destRulesDir);
-        updated.push(`.${ide}/rules/`);
-      } catch (error) {
-        skipped.push({ path: `.${ide}/rules/`, reason: error.message });
-      }
-    }
-
-    // 同步 skills
-    const srcSkillsDir = path.join(sourceIdeDir, 'skills');
-    const destSkillsDir = path.join(targetIdeDir, 'skills');
-    if (fs.existsSync(srcSkillsDir)) {
-      try {
-        if (fs.existsSync(destSkillsDir)) {
-          fs.rmSync(destSkillsDir, { recursive: true, force: true });
+    // 同步 IDE 特有配置文件（如 mcp.json）
+    try {
+      const sourceEntries = fs.readdirSync(sourceIdeDir);
+      for (const entry of sourceEntries) {
+        const srcPath = path.join(sourceIdeDir, entry);
+        const destPath = path.join(targetIdeDir, entry);
+        // 只同步文件，不同步目录（commands/rules/skills 目录由 .agents/ 指针管理）
+        if (fs.statSync(srcPath).isFile()) {
+          fs.copyFileSync(srcPath, destPath);
+          updated.push(`.${ide}/${entry}`);
         }
-        copyDirSync(srcSkillsDir, destSkillsDir);
-        updated.push(`.${ide}/skills/`);
-      } catch (error) {
-        skipped.push({ path: `.${ide}/skills/`, reason: error.message });
       }
+    } catch (error) {
+      skipped.push({ path: `.${ide}/`, reason: error.message });
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gong-ym/ai-spec-auto",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "AI Coding 团队规范驱动开发 CLI — 一键安装规范、技能与工具配置",
   "homepage": "https://github.com/gong-chick/engineered-spec#readme",
   "repository": {