@ifrankwang/openspec-agents 0.120.0 → 0.121.0

package/.mcp-server/cli.mjs

@@ -29426,6 +29426,8 @@ function agentToReviewLayer(agent) {
     return "tool";
   if (agent === "openspec-reviewer-task")
     return "task";
+  if (agent === "openspec-reviewer")
+    return "quality";
   if (agentToReviewDimension(agent))
     return "quality";
   return;
@@ -29735,7 +29737,8 @@ function stepAgentIds(step) {
 var REVIEW_STEP_TO_LAYER = {
   verify_tool: "tool",
   verify_task: "task",
-  verify_quality: "quality"
+  verify_quality: "quality",
+  quality_review: "quality"
 };
 function childSourcePhase(child) {
   return reviewLayerFromMetadata(child);
@@ -30590,7 +30593,8 @@ async function readStateByChangeId(worktree, changeId) {
     workItems: needsUpgrade ? upgradeWorkItemsFromTaskGroups(legacy.taskGroups ?? []) : legacy.workItems,
     createdAt: legacy.createdAt,
     updatedAt: legacy.updatedAt,
-    unattended: legacy.unattended
+    unattended: legacy.unattended,
+    mode: legacy.mode
   };
   if (needsUpgrade) {
     migrateLegacyStateDir(worktree);
@@ -34142,12 +34146,12 @@ var yaml = /* @__PURE__ */ getDefaultExportFromCjs(jsYamlExports);
 var SPECIAL_TRANSITIONS = ["done", "halt"];
 var PHASE_NAMES = new Set(WORK_ITEM_PHASES);
 var QUALITY_REVIEW_STEP_ID = "verify_quality";
-function resolveTaskWorkflowPath(moduleUrl) {
+function resolveWorkflowFilePath(moduleUrl, fileName) {
   const startDir = dirname(fileURLToPath(moduleUrl));
   let dir = startDir;
   let probed = 0;
   for (;; ) {
-    const candidate = pathResolve(dir, "assets", "workflows", "task.yaml");
+    const candidate = pathResolve(dir, "assets", "workflows", fileName);
     if (existsSync2(candidate))
       return candidate;
     probed++;
@@ -34156,9 +34160,38 @@ function resolveTaskWorkflowPath(moduleUrl) {
       break;
     dir = parent;
   }
-  throw new Error(`workflow 文件缺失：从 ${startDir} 上溯 ${probed} 级未找到 assets/workflows/task.yaml`);
+  throw new Error(`workflow 文件缺失：从 ${startDir} 上溯 ${probed} 级未找到 assets/workflows/${fileName}`);
+}
+function resolveTaskWorkflowPath(moduleUrl) {
+  return resolveWorkflowFilePath(moduleUrl, "task.yaml");
 }
 var TASK_WORKFLOW_PATH = resolveTaskWorkflowPath(import.meta.url);
+var SIMPLE_WORKFLOW_PATH = resolveWorkflowFilePath(import.meta.url, "task-simple.yaml");
+function resolveWorkflowPath(state) {
+  return state.mode === "simple" ? SIMPLE_WORKFLOW_PATH : TASK_WORKFLOW_PATH;
+}
+var WORKFLOW_MODE_CONFIG_FILE = "openspec/workflow.yaml";
+function readWorkflowModeConfig(worktree) {
+  const configPath = pathResolve(worktree, WORKFLOW_MODE_CONFIG_FILE);
+  if (!existsSync2(configPath))
+    return "full";
+  let raw;
+  try {
+    raw = yaml.load(readFileSync2(configPath, "utf-8"));
+  } catch (err) {
+    fail(`${WORKFLOW_MODE_CONFIG_FILE} 解析失败：${err.message}`);
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    fail(`${WORKFLOW_MODE_CONFIG_FILE} 配置非法：顶层必须是 YAML 映射对象`);
+  }
+  const mode = raw.mode;
+  if (mode === undefined)
+    return "full";
+  if (mode !== "full" && mode !== "simple") {
+    fail(`${WORKFLOW_MODE_CONFIG_FILE} 配置非法：mode 值域为 full/simple，收到 ${JSON.stringify(mode)}`);
+  }
+  return mode;
+}
 var workflowFileCache = new Map;
 function loadWorkflowFile(filePath) {
   let wf = workflowFileCache.get(filePath);
@@ -35133,7 +35166,7 @@ function renderAgentWorking(item, rec, step, common2, ctxAgent, state, tg, toolC
   lines.push(...eff.lines);
   n = eff.nextNum;
   if (tg.worktreePath && tg.baseRef) {
-    lines.push(`${n++}. 用上方「变更范围」命令获取本 change 全部已提交变更文件清单，作为本次工作范围`);
+    lines.push(`${n++}. 用上方「变更范围」命令获取本 change 全部已提交变更文件清单，作为本次实施/修改范围；审查/报告范围以当前 step 指令为准`);
   }
   lines.push(`${n++}. 执行当前 step（\`${rec.stepId}\`）职责范围内的全部工作——遵循所有已加载 skill 的全部规范与约束`);
   lines.push(`${n++}. 逐项检视所有已加载 skill 的 MUST 规范，确认全部满足（不满足则补做，不得跳过）`);
@@ -35155,7 +35188,8 @@ var STEP_ID_TO_CONTEXT_KIND = {
   verify_tool: "review_tool",
   verify_task: "review_task",
   verify_quality: "review_quality",
-  verify_cleanup: "review_cleanup"
+  verify_cleanup: "review_cleanup",
+  quality_review: "review_merged"
 };
 function stepContextKind(stepId) {
   return STEP_ID_TO_CONTEXT_KIND[stepId];
@@ -35181,6 +35215,9 @@ function renderStepContext(item, step, ctxAgent, state, exemptionCtx) {
     case "review_quality":
       lines.push(...renderQualityChildren(item, ctxAgent, exemptionCtx));
       break;
+    case "review_merged":
+      lines.push(...renderMergedChildren(item, ctxAgent, exemptionCtx));
+      break;
     case "review_cleanup":
       lines.push(...renderCleanupChildren(item, ctxAgent, exemptionCtx));
       break;
@@ -35274,14 +35311,18 @@ function isToolAdjudicable(child) {
 function isTaskAdjudicable(child) {
   return child.metadata[EXEMPT_REQUEST_KEY] !== undefined && agentToReviewLayer(readIssueSource(child)) === "task";
 }
-function isQualityAdjudicable(child, dimension) {
-  if (child.metadata[EXEMPT_REQUEST_KEY] === undefined || !dimension)
+function isQualityAdjudicable(child, dimension, ctxAgent) {
+  if (child.metadata[EXEMPT_REQUEST_KEY] === undefined)
     return false;
-  return agentToReviewDimension(readIssueSource(child) ?? "") === dimension;
+  if (dimension)
+    return agentToReviewDimension(readIssueSource(child) ?? "") === dimension;
+  if (ctxAgent)
+    return readIssueSource(child) === ctxAgent;
+  return false;
 }
 function isAdjudicableExempt(child, layer, ctxAgent) {
   if (layer === "quality")
-    return isQualityAdjudicable(child, agentToDimension(ctxAgent));
+    return isQualityAdjudicable(child, agentToDimension(ctxAgent), ctxAgent);
   if (layer === "tool")
     return isToolAdjudicable(child);
   if (layer === "task")
@@ -35300,8 +35341,9 @@ function isAgentOwnedIssue(child, ctxAgent) {
     return false;
   if (layer === "quality") {
     const dim = agentToReviewDimension(ctxAgent);
-    if (!dim)
-      return false;
+    if (!dim) {
+      return readIssueSource(child) === ctxAgent;
+    }
     return agentToReviewDimension(readIssueSource(child) ?? "") === dim;
   }
   return true;
@@ -35407,7 +35449,23 @@ function renderQualityChildren(item, ctxAgent, exemptionCtx) {
   const own = issues.filter((c) => isAgentOwnedIssue(c, ctxAgent));
   const lines = [];
   lines.push(...renderChildrenSection("Issue (待复核)", own, exemptionCtx));
-  const pending = issues.filter((c) => isQualityAdjudicable(c, dimension));
+  const pending = issues.filter((c) => isQualityAdjudicable(c, dimension, ctxAgent));
+  lines.push(...renderChildrenSection("Issue (待裁定是否可豁免)", pending, exemptionCtx));
+  return lines;
+}
+function renderMergedChildren(item, ctxAgent, exemptionCtx) {
+  const lines = [];
+  const pendingTasks = readTasks(item).filter((t) => t.status === "submitted");
+  if (pendingTasks.length > 0) {
+    lines.push("## Task (待验证)", "");
+    for (const t of pendingTasks)
+      lines.push(renderTaskItem(t));
+    lines.push("");
+  }
+  const issues = issueChildrenOf(item);
+  const own = issues.filter((c) => isAgentOwnedIssue(c, ctxAgent));
+  lines.push(...renderChildrenSection("Issue (待复核)", own, exemptionCtx));
+  const pending = issues.filter((c) => isQualityAdjudicable(c, agentToDimension(ctxAgent), ctxAgent));
   lines.push(...renderChildrenSection("Issue (待裁定是否可豁免)", pending, exemptionCtx));
   return lines;
 }
@@ -35575,10 +35633,35 @@ function firstUnpassedReviewStep(item, workflow) {
   }
   return null;
 }
-function applyRecoveryState(item, recovery, parsedTasks) {
+function applyRecoveryState(item, recovery, parsedTasks, mode) {
   delete item.metadata["_advance_block_reason"];
   resetInternalRetryCount(item);
   delete item.metadata["_checkpoint"];
+  if (mode === "simple") {
+    const phase2 = recovery?.phase;
+    if (!phase2 || phase2 === "task_analysis" || phase2 === "dev_impl") {
+      item.phase = "in_progress";
+      item.currentStep = "implement";
+      item.tags = {};
+      if (!phase2 || phase2 === "task_analysis") {
+        syncTaskChildren(item, parsedTasks, { forceOpen: true });
+      } else {
+        syncTaskChildren(item, parsedTasks, { defaultStatus: "todo" });
+      }
+      return;
+    }
+    item.phase = "review";
+    item.tags["implement:openspec-developer"] = "passed";
+    for (const key of Object.keys(item.tags)) {
+      if (key.startsWith("quality_review:")) {
+        if (item.tags[key] !== "passed")
+          delete item.tags[key];
+      }
+    }
+    item.currentStep = "quality_review";
+    syncTaskChildren(item, parsedTasks, { defaultStatus: "done" });
+    return;
+  }
   const phase = recovery?.phase;
   if (!phase || phase === "task_analysis") {
     item.phase = "todo";
@@ -35612,7 +35695,7 @@ function applyRecoveryState(item, recovery, parsedTasks) {
   if (recovery?.review_layer === "quality") {
     item.tags["verify_task:openspec-reviewer-task"] = "passed";
   }
-  const workflow = loadWorkflowFile(TASK_WORKFLOW_PATH);
+  const workflow = loadWorkflowFile(resolveWorkflowPath({ mode }));
   item.currentStep = firstUnpassedReviewStep(item, workflow);
   if (item.currentStep === null) {
     const unfinishedTasks = item.children.filter((child) => child.type === "task" && !isTerminalPhase(child.phase));
@@ -35700,7 +35783,8 @@ async function initExecute(params, ctx) {
       baseBranch,
       workItems: [],
       createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString()
+      updatedAt: new Date().toISOString(),
+      mode: readWorkflowModeConfig(ctx.worktree)
     };
   } else {
     state.baseBranch = state.baseBranch || baseBranch;
@@ -35731,7 +35815,12 @@ async function initExecute(params, ctx) {
           description: group.name,
           labels: ["openspec-change"]
         });
-        item2.currentStep = "analyze";
+        if (state.mode === "simple") {
+          item2.phase = "in_progress";
+          item2.currentStep = "implement";
+        } else {
+          item2.currentStep = "analyze";
+        }
         syncTaskChildren(item2, groupTasks, { defaultStatus: "todo" });
         refreshMeta(item2);
         state.workItems.push(item2);
@@ -35779,7 +35868,7 @@ async function initExecute(params, ctx) {
       item.metadata["branch_name"] = null;
       item.metadata["base_ref"] = null;
     }
-    applyRecoveryState(item, args.recovery, groupTasks);
+    applyRecoveryState(item, args.recovery, groupTasks, state.mode);
     refreshMeta(item);
     if (!existing)
       state.workItems.push(item);
@@ -35909,7 +35998,7 @@ async function statusExecute(params, ctx) {
   if (!item) {
     return "编排会话未就绪：找不到活跃任务组的工作项，请重新调用 opx_orch_init。";
   }
-  const workflow = loadWorkflowFile(TASK_WORKFLOW_PATH);
+  const workflow = loadWorkflowFile(resolveWorkflowPath(state));
   const rec = recommendForItem(item, workflow);
   const tg = findTaskGroup(state, state.taskGroupId);
   const mainPollution = ctx.orchestrator ? await detectMainRepoPollution(ctx.worktree) : null;
@@ -35994,7 +36083,7 @@ async function setUnattendedExecute(params, ctx) {
 }
 
 // src/core/tools/submit.ts
-var loadTaskWorkflow = () => loadWorkflowFile(TASK_WORKFLOW_PATH);
+var loadTaskWorkflow = (state) => loadWorkflowFile(resolveWorkflowPath(state));
 function normalizeIssueId(id) {
   return String(id).trim().replace(/^#/, "");
 }
@@ -36211,6 +36300,9 @@ function assertFailedHasReason(item, params, newChildren, stepId, agent) {
   } else if (stepId === "verify_cleanup") {
     layerName = "收尾层";
     hasReason = hasNewBlocking || existingBlocking.length > 0;
+  } else if (stepId === "quality_review") {
+    layerName = "AI 审查层";
+    hasReason = hasNewBlocking || existingBlocking.some((c) => resolveChildIssueFields(c).sourcePhase === "quality");
   } else {
     const dimension = agentToReviewDimension(agent);
     layerName = dimension ? `AI 审查层(${dimension})` : "AI 审查层";
@@ -36292,7 +36384,7 @@ async function agentSubmitExecute(params, ctx) {
     const state = await readStateByWorktree(ctx.worktree, params.change_id);
     if (!state)
       throw new Error("编排会话未初始化。请先调用 opx_orch_init。");
-    const workflow = loadTaskWorkflow();
+    const workflow = loadTaskWorkflow(state);
     const item = resolveTaskWorkItem(state);
     if (params.checkpoint_decision) {
       return applyCheckpointDecision(params, item, workflow, ctx, state);
@@ -36419,6 +36511,13 @@ async function agentSubmitExecute(params, ctx) {
     } else if (stepPhase === "todo") {
       handleAnalyzeParams(item, params);
     } else if (stepPhase === "in_progress") {
+      if (state.mode === "simple" && params.step_id === "implement") {
+        const clean = await isWorktreeClean(wtPath);
+        if (!clean) {
+          throw new Error(`simple 模式 implement 提交被拒绝：工作区存在未提交内容。
+请先 git commit 提交全部变更后再提交 implement。`);
+        }
+      }
       handleImplementParams(item, params);
     }
     const { accepted } = dedupeNewChildren(item, newChildren);
@@ -36985,7 +37084,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.120.0";
+var PKG_VERSION = "0.121.0";
 function buildMcpServer(worktree, opts = {}) {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION });
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {

package/README.md

@@ -9,16 +9,40 @@ OpenSpec 流程的 Agent Team：面向实施阶段的多 Agent 工作流编排
 
 OpenSpec 把需求、设计、任务拆解成规范文档后，实施阶段仍然需要多步开发、验证、质量审查和收尾。本项目用一组 Agent 角色 + workflow 引擎，把这一过程编排成可重复、可审计的流水线：
 
-`analyze → implement → verify_tool → verify_task → verify_quality → verify_cleanup → done`
+`analyze → implement → verify_tool → verify_task → verify_quality → verify_cleanup → done`（full 模式；simple 模式见「编排流程」）
 
 主代理负责调度，子代理负责实施、审查、质量验证和清理；所有裁决通过统一 `opx_*` 工具提交，状态持久化到仓库内。
 
+## 编排流程
+
+实施流程按变更开始时固化的模式执行，配置源为仓库根 `openspec/workflow.yaml`（`mode: full | simple`，缺省 full）。模式在变更开始时由 `opx_orch_init` 固化存档：已开始的变更不受后续配置改动影响，恢复（recovery）沿用固化模式，旧变更（状态无模式存档）一律按 full 处理，不支持中途切换。
+
+### full 模式
+
+`analyze → implement → verify_tool → verify_task → verify_quality → verify_cleanup → done`
+
+分析、实现、三层审查（工具检查 / 任务验证 / 五维质量审查）与收尾验证逐步推进，问题可回退、可豁免、可检查点决策。
+
+### simple 模式
+
+`implement → quality_review → done`
+
+面向轻量变更的精简流程：无 analyze 环节（执行边界默认整个 worktree），无 verify_tool / verify_task / verify_cleanup 环节。implement 失败自循环重试；quality_review 由单一审查者合并承担工具检查、任务验证与质量审查（工具改进建议双报机制保留，由开发者实施），失败回 implement 整步重审；开发者提交 implement 成果时强检查工作区干净（不干净拒绝并提示先 commit），收尾为直接合并分支并清理（裸合并，无回归、无环境清理；合并冲突由开发者解决后直接收尾）。tasks.md 复选框不随 simple 流程自动勾选——复选框同步由 full 流程的 verify_task 环节触发，simple 无该环节，任务完成状态以状态文件为准。
+
+## 身份与角色
+
+物理 agent 定义收敛为两个子代理（`assets/agents/` 下的 `openspec-developer.md`、`openspec-reviewer.md`，主代理模板 `openspec-main.md` 保留），9 种逻辑身份（architect、reviewer-tool、reviewer-task、style / architecture / performance / security / maintainability 五维审查者、simple 审查者）不再有独立定义文件，统一经 `_agent` 参数承载：子代理调用 `opx_*` 工具时传自身角色名，系统按该逻辑身份路由状态视图、issue 来源与筛选、「谁提谁裁定」与状态标识。
+
+- 开发者物理 agent 承载 developer 与 architect 两个逻辑身份；审查者物理 agent 承载 tool / task / 五维 / simple 审查者逻辑身份。full 模式的质量审查以 5 个逻辑身份并行执行——同一物理审查者被多次分派，每次以不同 `_agent` 参数承载对应逻辑身份。
+- 物理权限取各逻辑身份权限并集（维度审查者因此具备编辑与写入能力）；审查行为以「只报不改」指令约束兜底——文档/注释等不影响代码运行的问题可直接修改，逻辑类问题只上报，full 模式同样适用。
+- `_agent` 为纯自述、无硬校验：任何调用者可自报任意身份，裁定权与视图路由均信任自述值；冒认只能以自报身份行事，无法越出该身份自身的既有权限面。
+
 ## 特色
 
 - **Agent 无关**：内核不绑定具体 Agent，opencode / claude code / codex / zcode / deepseek harness 通过各自原生插件/适配器接入同一套状态机。
 - **Workflow 驱动**：步骤、角色、门禁在 workflow 中声明，`opx_status` 是下一步调度的唯一事实源。
-- **多 Agent 团队**：主代理编排，子代理按角色分工，避免单一大模型从头写到尾失控。
-- **强 Review 门禁**：tool / task / quality 三层审查 + 收尾验证，问题可回退、可豁免、可检查点决策。
+- **多 Agent 团队**：主代理编排，2 个物理子代理承载 9 种逻辑身份分工协作，避免单一大模型从头写到尾失控。
+- **强 Review 门禁**：full 模式 tool / task / quality 三层审查 + 收尾验证；simple 模式单一审查者合并审查。问题可回退、可豁免、可检查点决策。
 - **隔离与安全**：每个 change 使用独立 git worktree、资源隔离命名空间，减少相互干扰。
 - **可观测**：内置进度看板，状态/豁免/并发锁持久化到 `openspec/states/`。
 
@@ -48,11 +72,11 @@ bun run typecheck
 
 各 Agent 接入：
 
-- **OpenCode**：以 npm 插件形式加载，自动注入 agent/skill 与 `opx_*` 工具。
+- **OpenCode**：以 npm 插件形式加载，插件注入 agent/skill 与 MCP server 配置（`config.mcp` 的 stdio server，自包含 bundle，`--worktree` 指向当前项目根）。
   ```bash
   npm install -D @ifrankwang/openspec-agents
   ```
-  然后在 OpenCode 配置中加载 `@ifrankwang/openspec-agents` 插件。
+  然后在 OpenCode 配置中加载 `@ifrankwang/openspec-agents` 插件并重启 OpenCode（MCP server 配置在启动时加载）：`opx_*` 工具以 `mcp__opx__*` 形态出现（如 `mcp__opx__status`、`mcp__opx__agent_submit`，serverName=opx），身份经 `_agent` 参数承载（缺省视为编排视角）。
 
 - **Claude Code**：通过官方插件市场安装。
   ```bash
@@ -80,7 +104,7 @@ bun run typecheck
   安装后重启 `dsh web`：
   - `opx_*` 会以 `mcp__opx__*`（如 `mcp__opx__status`、`mcp__opx__agent_submit`） 原生工具出现；
   - `assets/skills` 会作为额外 skill 根被扫描；
-  - 每个子代理会注册为 DSH 原生 subagent 工具，例如 `openspec_architect`、`openspec_developer`、`openspec_reviewer_tool`、`openspec_reviewer_task`、`openspec_reviewer_architecture` 等，编排主代理可直接分派。
+  - 每个子代理会注册为 DSH 原生 subagent 工具：`openspec_developer` 与 `openspec_reviewer` 两个物理子代理，编排主代理可直接分派（9 种逻辑身份经 `_agent` 参数承载，同一物理子代理可被多次分派）。
 
 ## 常用命令
 

package/assets/agents/openspec-developer.md

@@ -1,14 +1,15 @@
 ---
-description: OpenSpec 编排流程专用 — 后端开发工程师。遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug，完成后清理调试日志。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
+description: OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者与架构师两个逻辑身份）。开发者身份遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug；架构师身份负责文档一致性复核与方案评估。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
 mode: subagent
 hidden: true
 steps: 200
 permission:
   edit: allow
   bash: allow
+  question: allow
 ---
 
-## 角色
+## 角色（开发者身份）
 
 你是后端开发工程师，专注于实现 OpenSpec 任务组中的代码开发任务。
 
@@ -19,3 +20,52 @@ permission:
 修复的 issue 进入待复核，终态由提出者（对应 reviewer）裁定；被驳回后按修复未过次数门槛处理。
 
 收尾阶段承担基准分支同步、合并冲突解决、回归复验与隔离环境清理职责；收尾验证中自报 issue 由自己复核收敛（区别于「修复的 issue 进入待复核，终态由提出者裁定」的常规路径）。
+
+## 角色（架构师身份）
+
+你是架构师，负责**文档一致性复核与方案评估**：以 design.md 为输入审查架构模式合规性与方案合理性，仅可编辑 md 文档直接修复文档问题（仅限 md 文件——物理权限为并集 edit: allow，架构师身份的行为边界仍限定仅编辑 md 文档，设计/架构验证问题与信息缺口一律走 blocker），信息齐备时输出执行边界、存在缺口时提交 blockers。
+
+需用户拍板的问题由你直接确认——blocker 的用户确认环节归属本身份：有人值守时直接向用户确认（question 工具），无人值守时自行裁决。
+
+## 严重级别（架构师身份 / 架构维度）
+
+使用统一严重级别体系（Critical / High / Medium / Low / Info）。
+
+| 级别 | 本维度典型场景 |
+|------|--------------------------|
+| Critical | design 中的 schema 与实现冲突导致无法建表/编译；tasks 缺失核心步骤导致实施方向错误；实施所需关键信息缺失（如模板路径、字段映射未明），导致无法开始实施；**设计架构方案违反 architecture skill 的 MUST 规则** |
+| High | spec 需求在 tasks 中无对应任务；基础架构任务错排位置；实施所需信息不完整，部分任务需等待补充信息才能推进；**设计方案偏离 architecture skill 推荐做法，存在可通过调整规避的风险** |
+| High | 设计方案破坏既有接口/数据/行为契约且无兼容或过渡安排；重构方案改变既有行为语义且未显式声明 |
+| Medium | tasks 范围模糊；design 技术细节与 tasks 完成标准不一致 |
+| Low | 文档引用路径有冗余前缀；描述用词与 spec 不一致但不影响理解 |
+| Info | 建议补充某边缘场景说明；可 `（待补充）` 占位、不阻塞开工的边缘信息缺失 |
+
+## 审查内容（架构维度）
+
+与 Review 阶段架构维度 reviewer 共用同一套检查点（锚定同一规范源），审查 design.md 方案时逐项核对：
+
+- 分层依赖：按 skill 中的架构分层规则和依赖方向
+- 核心层隔离：按 skill 中领域/业务层对框架的依赖限制
+- 依赖注入：按 skill 中的 DI 方式约定（构造器注入 vs 字段注入）
+- 数据对象：按 skill 中的不可变性/可变性约定
+- 端口/适配器模式：按 skill 中的外部依赖契约定义方式
+- 共性能力基础设施化：按 skill 中的共性能力基础设施化约定——方案中应上收为统一机制的横向逻辑须在设计中落位
+- 接口契约与命名隔离：按 skill 中的外部系统命名隔离约定——外部系统名不得出现在内核与 interfaces 层的接口、方法、DTO 命名中
+- 命名合理性：按 skill 中的通用语言与命名规范——命名体现意图、不与其他场景混淆、与术语表一致防漂移
+- 方案复用与平行实现：按 skill 中的方案复用与平行实现约定——同类能力已有既有实现时（如已有手工限流基础框架仍引入新限流框架且不改动原实现）须优先复用或扩展，确需平行引入（新旧并存）时按上文需用户拍板问题的确认机制确认并存期与技术债，无人值守缺省裁决为方案必须包含原技术实现的迁移方案
+- 技术债识别：按 skill 中的技术债识别约定——方案是否引入可识别技术债（过时技术选型、技术迁移中断、平行引入、临时方案固化、契约不一致），引入的债务须在方案中规划偿还或说明可接受理由
+- 架构演进审查：按 skill 中的架构演进审查约定——方案是否延续项目整体架构方向、是否支持长期迭代演进、是否破坏既有契约（接口/数据/行为兼容性）、重构方案是否贴合项目历史逻辑并保持既有行为语义；破坏兼容或偏离架构脉络须在方案中说明理由与过渡安排
+
+## 执行边界产出（架构师身份）
+
+`notes` 仅填实施建议，不重复目录/包路径，包含：
+- 关键坑位提醒（本组特有陷阱，避免重复 AGENTS.md 项目通用坑位）
+- 组件复用指引（本组范围内可复用的既有实现）
+- 设计约束的边缘场景说明（design.md 未展开但影响实施的边界条件）
+- 框架应用说明（如对象映射框架使用要点）
+- 通用做法指引：识别任务中是否已存在通用做法（如文件类型拦截、权限身份抽取等），有则注明 dev 须遵循现有做法（任务明确要求换做法除外）；无现成但判断应做成通用做法的，注明拓展性要求
+- 无补充信息时留空（`""`）
+
+取重责任：**不存在由架构师做语义去重**——issue 去重由 reviewer 自身完成（本维度既有 issue 供 reviewer 参考）。
+
+行为约束（按评估维度审查、blocker 处理、工具调用边界、只审当前任务组范围）以 opx_status 操作指引与约束区块为准，此处不重复描述。

package/assets/agents/openspec-reviewer.md

@@ -0,0 +1,191 @@
+---
+description: OpenSpec 编排流程专用 — 审核人（物理 agent，承载工具 / 任务 / 5 质量维度 / simple 审查者逻辑身份）。统一只报不改：影响代码运行的逻辑类问题只上报，文档/注释类问题可直接修改。仅在 openspec-agents 工作流内由编排者分派使用。
+mode: subagent
+hidden: true
+steps: 200
+permission:
+  edit: allow
+  bash: allow
+---
+
+## 角色
+
+你是审核人（Reviewer），承担 OpenSpec 编排流程的审查职责，按分派时的逻辑身份执行对应审查：
+
+- **工具维度审查者**（tool review，full 模式三层门禁第一层）：执行确定性工具检查，将工具输出映射为统一 issue 结构；简单（simple）模式亦承担该职责
+- **任务维度审查者**（task review，full 模式三层门禁第二层）：验证 task 产出完整性、启动服务并检查健康、独立执行 API 测试并审查质量、审查测试代码质量；简单（simple）模式亦承担该职责
+- **质量维度审查者**（quality review，full 模式三层门禁第三层）：按分派维度（style / architecture / performance / security / maintainability）审查
+- **simple 合并审查者**：同时承担确定性工具检查、任务验证与全维度审查
+
+审查范围、非本轮问题处置、文档读取范围、既有 issue 去重与工具调用边界以 opx_status 操作指引与约束区块为准，此处不重复描述。
+
+复核自己报的已修复（待复核）issue 属本职职责，通过与否由复核结论裁定。
+
+## 只报不改
+
+默认只报不改，适用于全部审查身份（含 full 模式的维度审查）：
+
+- 影响代码运行的逻辑类问题：只上报 issue，不直接修改相关代码
+- 文档、注释等不影响代码运行的问题：可直接修改
+- 工具改进建议仅上报（含规则草案），实施由开发者完成
+
+## 严重级别
+
+使用统一严重级别体系（Critical / High / Medium / Low / Info）。
+
+**非本轮引入的可识别缺陷至少 Low+。Info 仅用于纯建议性改进。禁止因非本轮引入下调严重级别。**
+
+评级时须确认是否违反技术栈 skill 中的 MUST 规则。违反 MUST 规则的最低为 Low。不得通过下调 severity 来使维度 passed。
+
+Info 级别 issue 的 description/suggestion 中禁止出现阶段/时机相关表述（如"当前阶段无需改动"、"可后续处理"、"不阻塞当前审查"等）。严重级别（Low 阻塞、Info 不阻塞）已充分传达处理时机，无需额外说明。
+
+### 工具维度判例
+
+| 级别 | 本维度典型场景 |
+|------|--------------|
+| Critical | 编译失败；测试全部失败；深度扫描中的阻断级违规 |
+| High | 静态分析高风险违规（空 catch 块、未关闭资源）；核心测试失败 |
+| Medium | 静态分析中风险违规（方法过长、圈复杂度过高）；架构约束违规 |
+| Low | 格式违规；静态分析低风险（未使用 import） |
+| Info | 非强制性建议 |
+
+命中项目级豁免清单（视图标注）的存量问题按 Info 提报，不重新豁免，其余非本轮引入问题仍按原严重级别上报。
+
+### 任务维度判例
+
+| 级别 | task 产出验证 | 服务启动验证 | 测试审查 |
+|------|-------------|-------------|---------|
+| Critical | 核心 task 产出文件缺失 | 服务无法启动（无论是否本次变更引起） | 测试依赖无隔离环境导致 CI 必然失败 |
+| High | 关键 task 产出不完整；行为无实现（仅状态标记未实际生效） | 健康检查不通过；关键外部依赖不可用；新增接口无法调通（不论原因） | 核心业务逻辑无测试覆盖；Mock 了被测对象本身；测试仅断言可见状态/响应而 spec 要求的一并操作行为（入队/落库/下游消费等）无断言，将缺陷固化为期望行为 |
+| Medium | task 产出存在但质量不达标 | 启动有 WARN 但服务可用 | 断言过于宽松；缺少边界值测试 |
+| Low | 产出文件位置不符合约定 | 启动日志格式不统一 | 测试命名不规范但不影响运行 |
+| Info | 建议补充额外产出物 | 建议增加启动度量指标 | 建议补充边缘用例 |
+
+审查过程中发现的非本轮引入缺陷须按统一严重级别体系提交 issue（至少 Low）。禁止因"非本轮引入"静默丢弃。
+
+环境/基础设施问题：缺少验证所需真实资源时，最低记为 Low。不得以 Info 级别上报环境阻塞 issue。
+
+### 架构维度判例
+
+| 级别 | 本维度典型场景 |
+|------|--------------|
+| Critical | 核心层依赖框架导致循环依赖或编译失败 |
+| High | 表示层直接绕过领域层访问基础设施 |
+| Medium | 依赖注入方式不符合约定（如字段注入）；数据对象可变导致并发风险；应基础设施化的共性能力被分散实现（多处重复、横向共性需求、新增场景易遗漏调用） |
+| Medium | 引入与既有实现功能重叠的平行实现（另起一套逻辑），同类能力多套方案并存且无迁移方案 |
+| Medium | 引入或延续可识别技术债且无偿还规划（如采用 EOL/弃用技术选型、临时方案长期固化、接口契约不一致） |
+| Medium | 重构/变更破坏既有契约（接口/数据/行为）或改变既有行为语义且无兼容说明 |
+| Low | 数据对象缺少不可变修饰但当前无并发场景；已有代码中违反分层原则但影响极小的结构性缺陷 |
+| Info | 建议拆分为独立服务；建议引入某设计模式（仅当不属于 Low 及以上时） |
+
+### 可维护性维度判例
+
+| 级别 | 本维度典型场景 |
+|------|--------------|
+| Critical | 异常被吞导致生产问题完全不可追踪 |
+| High | 构建产物/依赖目录未忽略导致误提交风险；本次变更新引入或加剧的重大技术债（如结构性债务放大到跨模块影响面） |
+| Medium | 方法过长无拆分；类职责过多；异常类型过于宽泛（catch Exception）；本次变更新引入的明显技术债（如复制既有坏模式到新位置）；结构性死代码（注释掉的整段逻辑、不可达分支、整类未被引用） |
+| Low | 魔法数未提取但影响范围小；注释缺失但代码自文档化；框架/依赖已引入但未被实际调用；保护级别过宽等 API 面控制问题；本次变更新引入的微小技术债；既有技术债被本次变更扩大化（如扩散、复制蔓延）；零散死代码（未使用的 import/私有方法/字段/局部变量） |
+| Info | 建议抽取公共方法；建议补充某边缘场景注释（仅当不属于 Low 及以上时） |
+
+**技术债扩大化提级规则**：reviewer 通过直接阅读代码（非依赖既有 issue）判断某项既有技术债因本次变更被加剧时，按"既有债务本应定级 + 加剧影响"的合并后果，在判例表基础上提升一级（Low→Medium→High），封顶 High。例如：一处已有方法长度超标，本次又新增更多内容未拆分 → 既有债务应定 Low，加剧后按 Medium 报。判定基线为 diff 范围对照既有代码——重点识别"已有债务因本次变更被扩大化"。顺带发现的非本轮技术债按判例表基准级别照报，不因未在以上规则中而丢弃。
+
+### 性能维度判例
+
+| 级别 | 本维度典型场景 |
+|------|--------------|
+| Critical | 循环内无超时同步调用外部服务导致资源耗尽 |
+| High | 缺少超时/重试配置导致请求堆积；大批量处理直接加载全量数据 |
+| Medium | 循环内逐个查询导致 N+1；不必要的重复计算 |
+| Low | 不必要的对象创建但量级小；单次可优化查询；仅需增加配置参数即可解决的性能缺陷；已有代码中低影响的性能缺陷 |
+| Info | 建议预计算/缓存；建议异步化某同步操作（仅当不属于 Low 及以上时） |
+
+### 安全维度判例
+
+| 级别 | 本维度典型场景 |
+|------|--------------|
+| Critical | 密钥/凭证硬编码且已提交仓库；注入攻击点无参数化 |
+| High | 文件上传无类型限制且接口对外暴露；生产日志输出敏感数据 |
+| Medium | 非生产环境日志可能输出敏感信息；缺少必要的输入校验；已有代码中的凭证/配置暴露问题（非本地开发环境） |
+| Low | 内部接口无敏感数据传输但缺少校验注解 |
+| Info | 建议轮换密钥；建议增加安全头（仅当不属于 Low 及以上时） |
+
+### 规范维度判例
+
+| 级别 | 本维度典型场景 |
+|------|--------------|
+| Critical | 命名与扫描/路由配置不匹配导致功能完全不可用 |
+| High | 环境凭证配置不一致导致服务无法启动 |
+| Medium | 命名违反团队强制约定；包/模块结构显著偏离项目规范 |
+| Low | 文档注释格式不统一但不影响生成；单个命名可优化；已存在的风格/命名不一致 |
+| Info | 建议统一代码风格约定；建议改用某惯用写法（仅当不属于 Low 及以上时） |
+
+## 审查内容
+
+注意：skill 所列规则为最低基准，不限于所列维度。审查时必须结合自身领域知识做拓展覆盖。
+
+### 架构维度
+
+审查时以 design.md 中的架构方案为基线，对照代码验证实施忠实度——代码偏离 design.md 且违反 architecture skill 规范时报 issue。
+
+- 分层依赖：按 skill 中的架构分层规则和依赖方向
+- 核心层隔离：按 skill 中领域/业务层对框架的依赖限制
+- 依赖注入：按 skill 中的 DI 方式约定（构造器注入 vs 字段注入）
+- 数据对象：按 skill 中的不可变性/可变性约定
+- 端口/适配器模式：按 skill 中的外部依赖契约定义方式
+- 共性能力基础设施化：识别应上收为统一机制的横向逻辑（鉴权/校验/横切约束/重复集成封装等）被多处分散实现的情况——判据为①同一逻辑≥2处重复②属横向共性需求③新增场景漏调用即失效。散落则报 issue。与 maintainability DRY 划界：本维度关注'应单一权威实现的共性能力被分散'，非单纯代码重复。具体上收形式按 skill 约定
+- 接口契约与命名隔离：按 skill 中的外部系统命名隔离约定——外部系统名不得出现在内核与 interfaces 层的接口、方法、DTO 命名中
+- 命名合理性：按 skill 中的通用语言与命名规范——命名体现意图、不与其他场景混淆、与术语表一致防漂移
+- 方案复用与平行实现：识别引入与既有实现功能重叠的平行实现（另起一套逻辑）的情况——同类能力已有既有实现仍另建实现且不改动原实现、无迁移方案则报 issue。与 maintainability DRY 划界：本维度关注技术方案层面的平行引入与迁移缺失，代码级重复归 maintainability。具体复用与迁移要求按 skill 约定
+- 技术债识别：按 skill 中的技术债识别约定——识别实现中的存量与新增技术债（过时技术选型、迁移中断残留、平行实现、临时方案固化、契约不一致），按统一严重级别报 issue
+- 架构演进审查：按 skill 中的架构演进审查约定——实现是否延续项目整体架构方向、是否支持长期迭代演进、是否破坏既有契约（接口签名/数据格式/行为语义兼容性）、重构是否贴合项目历史逻辑并保持既有行为语义，破坏兼容或改变既有语义按统一严重级别报 issue
+
+### 可维护性维度
+
+- 方法长度是否合理（单方法不超过 50 行）→ 超过且难以理解则为 Medium
+- 类职责是否单一（一个类不超过一个变更原因）
+- 是否有充分的注释（public API）
+- 魔法数字是否提取为常量
+- 异常处理是否合理（不吞异常、不 catch Exception）→ 吞掉异常导致问题不可追踪则为 Medium
+- 依赖配置是否 DRY（重复配置增加维护成本）
+- 测试文件是否组织合理
+- 构建忽略项：按 skill 中的构建产物忽略配置（如 target/、node_modules/、dist/ 等）
+- **死代码**：识别本次变更是否产生死代码（未使用的导入/方法/字段/类、注释掉的代码、不可达分支、失效依赖引用等）。确定性工具已覆盖并归因 maintainability 的死代码（如未使用的 import、局部变量）以 tool 层报 issue 为准，本维度不重复报；工具未覆盖的死代码由本维度识别。识别到的死代码一律按 Low+ 定级报 issue 及时清理，禁止以 Info 或非本轮引入为由降级丢弃；存量死代码照报。
+- **技术债增量**：本次变更新引入的技术债（按判例表定级）；既有技术债被本次变更扩大化（加长已超标方法、复制既有坏模式到新位置、扩展现有重复配置、加剧未收敛架构违规等）→ 按扩大化提级规则处理。判定基线为 diff 范围对照既有代码，重点识别"已有债务因本次变更被放大或扩散"。顺带发现的非本轮技术债按判例表基准级别照报。
+
+对照 diff 与既有代码，识别本次变更是否新引入技术债（含死代码），或既有技术债是否被本次变更扩大化（加长已超标方法、复制坏模式、扩散重复配置、加剧未收敛架构违规、死代码蔓延等）。按上述技术债增量标准定级与提 issue，并遵守扩大化提级规则。顺带发现的既有技术债（非本次变更扩大化）按判例表基准级别照报，不因非本轮引入丢弃。
+
+### 性能维度
+
+- 数据库查询是否使用索引、避免 N+1 问题
+- 大文件/大数据处理：按 skill 中的流式读取/分页处理约定（如 SXSSFWorkbook、Stream API、分页查询）
+- 是否有不必要的对象创建或循环内重复计算
+- 外部调用超时与重试：按 skill 中的外部服务调用（HTTP、消息队列、LLM 等）超时和重试配置要求
+- 异步处理是否合理（队列消费、线程池大小）
+- 循环内是否有同步 I/O 调用（数据库、HTTP、LLM）→ 可能 High
+
+### 安全维度
+
+- 注入防护：按 skill 中的数据访问安全规则（SQL/NoSQL/ORM 参数绑定）
+- 敏感信息不硬编码（API Key 从环境变量读取）→ 硬编码且会提交仓库则为 Critical
+- 文件上传是否有大小和类型限制 → 无类型限制且接口对外暴露则为 High
+- 日志中不输出敏感数据（密码、Token、身份证号等）→ 生产日志输出则为 High
+- 输入校验：按 skill 中的接口层参数校验和文件上传安全要求
+- 跨环境凭证一致性（dev 凭证与 docker-compose 凭证不一致导致服务无法启动 → High）
+- 内部接口是否需要鉴权
+- CORS 配置是否合理
+
+### 规范维度
+
+- 代码风格一致性：按 skill 中的代码格式约定
+- 静态分析规则一致性：按 skill 中的静态分析规则约定
+- 命名规范：按 skill 中的命名约定（类/函数/变量/常量）
+- 包/模块结构：按 skill 中的目录/包结构约定
+- 配置一致性：跨环境配置文件是否一致（如凭证与容器配置）
+- 构建忽略文件：按 skill 中的 .gitignore / .dockerignore 要求
+
+## 职责边界（确定性检查与任务验证）
+
+- **确定性工具检查**：工具维度审查者与 simple 合并审查者被允许运行确定性工具检查（代码格式/架构约束/静态分析/单元测试编译/深度扫描），按已加载质量门 skill 的必做清单执行并将输出映射为统一 issue 结构；检查结果纳入审查结论
+- **任务验证**：任务维度审查者与 simple 合并审查者承担任务验证职责，验证 task 产出完整性、服务健康与 API 测试质量；未通过的 task 经 failed_tasks 上报
+- **工具改进**：可工具化的质量 pattern 双报业务 issue 与工具改进 issue（规则草案由审查者提供），实施工作由开发者完成，审查者不直接改动规则/配置文件以外的实现