@ifrankwang/openspec-agents 0.132.1 → 0.133.1

package/src/core/tools/schemas.ts

@@ -202,25 +202,58 @@ export const recoverySchema: JSONSchema = {
 export const orchInitSchema: JSONSchema = {
   type: "object",
   properties: {
-    change_id: { type: "string", minLength: 1, description: "OpenSpec 变更 ID" },
+    change_id: { type: "string", minLength: 1, description: "OpenSpec 变更 ID（change 会话入口；与 review_scope 二选一）" },
     task_group_id: {
       type: "string",
       minLength: 1,
-      description: "要初始化的任务组 ID。无 recovery 重复调用当前组时保留进度；切换任务组时仅初始化目标组。",
+      description: "要初始化的任务组 ID（change 会话入口）。无 recovery 重复调用当前组时保留进度；切换任务组时仅初始化目标组。独立审查会话恢复时可不传。",
     },
     base_branch: {
       type: "string",
-      description: "基准分支名（如 main、develop），用于计算 merge-base 和 worktree fork 源。未传则自动从当前 git 分支推导。",
+      description: "基准分支名（如 main、develop），用于计算 merge-base 和 worktree fork 源。未传则自动从当前 git 分支推导。仅 change 会话入口有效。",
     },
     recovery: recoverySchema,
     mode: {
       type: "string",
       enum: ["full", "simple"],
       description:
-        "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。首次新建编排状态时固化；已开始的变更仅在允许窗口内可更新：切换任务组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）；其余场景传不同 mode 将报错。",
+        "流程模式选择（仅 change 会话入口有效，独立审查会话不使用）：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。首次新建编排状态时固化；已开始的变更仅在允许窗口内可更新：切换任务组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）；其余场景传不同 mode 将报错。",
+    },
+    review_scope: {
+      type: "object",
+      description:
+        "独立审查会话入口（不绑定 OpenSpec change）：与 change_id/task_group_id 互斥——同传报错、都不传报错，两种入口二选一。会话 id 由审查范围确定性推导并在返回体回传，后续所有工具以 change_id 形式传入该会话 id。",
+      properties: {
+        scope_type: {
+          type: "string",
+          enum: ["pr", "full"],
+          description: "审查范围：pr=按 base_ref..head_ref 本地分支区间审查；full=全量代码库审查",
+        },
+        base_ref: {
+          type: "string",
+          minLength: 1,
+          description: "pr 形态的基准本地分支。缺省自动推导（优先 main、其次 master）。须为本地分支（origin/* 等远端 ref 不受支持——收尾合并只推进本地分支引用）",
+        },
+        head_ref: {
+          type: "string",
+          minLength: 1,
+          description: "pr 形态的头部本地分支（审查目标分支，pr 必传）。须为本地分支（origin/* 等远端 ref 不受支持）",
+        },
+        granularity: {
+          type: "string",
+          enum: ["simple", "thorough"],
+          description: "审查颗粒度：simple=单层合并审查；thorough=三层审查（工具检查→回归验证→五维度质量审查）",
+        },
+        fix: {
+          type: "string",
+          enum: ["none", "fix"],
+          description: "修复策略：none=只审不修（issue 报告即交付物，审查失败直接收口出报告）；fix=审并修（审查失败回退修复，修复后重审）",
+        },
+      },
+      required: ["scope_type", "granularity", "fix"],
+      additionalProperties: false,
     },
   },
-  required: ["change_id", "task_group_id"],
   additionalProperties: false,
 }
 

package/src/core/tools/types.ts

@@ -17,8 +17,18 @@ export interface ToolResult {
 }
 
 export interface InitParams {
-  change_id: string
-  task_group_id: string
+  /** change 会话入口必传；独立审查入口（review_scope）不传（会话 id 由 review_scope 推导并在返回体回传）。 */
+  change_id?: string
+  /** change 会话入口必传；独立审查会话用固定虚拟组 review（recovery 时可缺省）。 */
+  task_group_id?: string
+  /** 独立审查会话入口：与 change_id/task_group_id 互斥（同传报错、都不传报错）。 */
+  review_scope?: {
+    scope_type: "pr" | "full"
+    base_ref?: string
+    head_ref?: string
+    granularity: "simple" | "thorough"
+    fix: "none" | "fix"
+  }
   base_branch?: string
   recovery?: {
     phase: BuildPhaseTarget

package/src/core/types.ts

@@ -34,6 +34,27 @@ export type QualityLayerProgress = Record<ReviewDimension, DimensionVerdict>
 /** 流程模式：full（默认，analyze → implement → 三重审查+收尾验证）或 simple（implement → quality_review → done）。 */
 export type WorkflowMode = "full" | "simple"
 
+/** 独立审查会话的审查范围类型：pr=按 base..head 分支区间审查，full=全量代码库审查。 */
+export type ReviewScopeType = "pr" | "full"
+/** 独立审查颗粒度：thorough=三层审查（verify_tool → verify_task → verify_quality），simple=单层合并审查（quality_review）。 */
+export type ReviewGranularity = "simple" | "thorough"
+/** 独立审查修复策略：none=只审不修（issue 报告即交付物），fix=审并修（失败回 implement 修复闭环）。 */
+export type ReviewFixPolicy = "none" | "fix"
+
+/** 独立审查会话的审查范围（opx_orch_init 的 review_scope 参数固化，不绑定 OpenSpec change）。 */
+export interface ReviewScope {
+  scopeType: ReviewScopeType
+  /** pr 形态的基准本地分支（init 推导后固化；full 形态缺省）。 */
+  baseRef?: string
+  /** pr 形态的头部本地分支（审查目标分支；full 形态缺省）。 */
+  headRef?: string
+  granularity: ReviewGranularity
+  fix: ReviewFixPolicy
+}
+
+/** 独立审查会话的固定虚拟任务组 id（workItem id 为 task:review，无 tasks.md / task children）。 */
+export const REVIEW_TASK_GROUP_ID = "review"
+
 export interface ExecutionBoundary {
   allowed_directories: string[]
   allowed_packages: string[]
@@ -144,4 +165,9 @@ export interface OrchestrateState {
    *  （切组且其他任务组均已完成或从未激活，或 recovery.phase=task_analysis 重制当前组）内
    *  可被 mode 参数更新。 */
   mode?: WorkflowMode
+  /** 会话形态：review=独立审查会话（不绑定 OpenSpec change，无 tasks.md 解析 / mode 字段）；
+   *  缺省视为 change 会话（读时兜底，不写回旧 state）。workflow 选择按 kind 优先于 mode。 */
+  kind?: "review"
+  /** kind=review 时的审查范围（granularity 决定 workflow 文件、fix 决定 fail 方向转移策略）。 */
+  reviewScope?: ReviewScope
 }

package/src/core/views.ts

@@ -108,7 +108,20 @@ export function renderWorktreeSection(
   if (tg.worktreePath) {
     lines.push(`- **路径**: \`${tg.worktreePath}\``)
     lines.push(`- **分支**: \`${tg.branchName || "(none)"}\``)
-    if (tg.baseRef) lines.push(`- **变更范围**: 用 \`git -C ${tg.worktreePath} diff --name-only ${tg.baseRef}..HEAD\` 查询本 change 全部已提交变更文件`)
+    if (state.kind === "review") {
+      // 独立审查会话：渲染「审查范围」锚点——pr 形态为 base..head 区间（base_ref 存 merge-base 锚点），
+      // full 形态为全量代码库（base_ref 不设，不得渲染为「未检出变更」）
+      if (state.reviewScope?.scopeType === "pr" && tg.baseRef) {
+        lines.push(
+          `- **审查范围**: PR 区间审查（${state.reviewScope.baseRef}..${state.reviewScope.headRef}）——` +
+            `用 \`git -C ${tg.worktreePath} diff --name-only ${tg.baseRef}..HEAD\` 查询本区间已提交变更文件`,
+        )
+      } else {
+        lines.push("- **审查范围**: 全量代码库审查（无区间界定，工具检查与审查覆盖整个代码库）")
+      }
+    } else if (tg.baseRef) {
+      lines.push(`- **变更范围**: 用 \`git -C ${tg.worktreePath} diff --name-only ${tg.baseRef}..HEAD\` 查询本 change 全部已提交变更文件`)
+    }
     lines.push("- **⚠️ 约束**: 所有读写和 git 操作均在此目录下进行；严禁直接修改主仓库/主分支路径下的文件（如 `<repo>/openspec/...`）")
     lines.push("- **路径解析**: 推荐阅读文档均为相对 worktree 路径的引用，一律以 worktree 路径为基准解析，禁止从主仓库根目录解析")
   } else {

package/src/core/workflow/engine.ts

@@ -310,6 +310,16 @@ export function suspendItem(item: WorkItem, reason: string): void {
 
 export type TransitionDirection = "pass" | "fail"
 
+/** fix=none 只审会话的修复策略 metadata 键（引擎无 state 访问，item.metadata 为引擎消费单一事实源，
+ *  由 init 从 state.reviewScope.fix 写入）。 */
+export const REVIEW_FIX_POLICY_KEY = "review_fix_policy"
+
+/** 读取 item 的独立审查修复策略（非 review 会话返回 undefined）。 */
+export function reviewFixPolicyOf(item: WorkItem): "none" | "fix" | undefined {
+  const v = item.metadata[REVIEW_FIX_POLICY_KEY]
+  return v === "none" || v === "fix" ? v : undefined
+}
+
 export interface TransitionResult {
   advanced: boolean
   reason?: string
@@ -326,6 +336,18 @@ function phaseOrderIndex(phase: WorkItemPhase): number {
   return WORK_ITEM_PHASES.indexOf(phase)
 }
 
+/** done 转移的统一收口：不走 forwardGatePassed（短路），置 done 前显式检查 task children 全部终态
+ *  （未完成子任务不得收尾；issue blocking 检查已在 stepCanPass 处理；review 会话无 task children 天然通过）。 */
+function applyDoneTransition(item: WorkItem): TransitionResult {
+  const unfinishedTasks = item.children.filter((child) => child.type === "task" && !isTerminalPhase(child.phase))
+  if (unfinishedTasks.length > 0) {
+    return { advanced: false, reason: "存在未完成的子任务（task children 未达终态），无法进入 done。" }
+  }
+  item.phase = "done"
+  item.currentStep = null
+  return { advanced: true, target: "done" }
+}
+
 /**
  * 沿当前 step 的 transition 推进状态机。
  * - done: item 进入终态（phase=done）并触发写回
@@ -346,16 +368,15 @@ export function applyTransition(
 
   const target = direction === "pass" ? current.step.transitions.on_pass : current.step.transitions.on_fail
 
+  // fix=none 只审会话：fail 方向转移目标 implement 为拓扑统一声明的死 step（review workflow 的
+  // on_fail 一律写 implement），策略短路直达 done——不可拦截转移：failed tag 滞留会让审查者被
+  // 无限重派死锁。done 收口只检查 task children 终态，review 会话无 task children 天然通过，
+  // issue 报告即交付物（收尾 openIssues 门禁对 fix=none 放宽）。
+  if (direction === "fail" && target === "implement" && reviewFixPolicyOf(item) === "none") {
+    return applyDoneTransition(item)
+  }
   if (target === "done") {
-    // done 转移不走 forwardGatePassed（短路），置 done 前须显式检查 task children 全部终态
-    // （未完成子任务不得收尾；issue blocking 检查已在 stepCanPass 处理）。
-    const unfinishedTasks = item.children.filter((child) => child.type === "task" && !isTerminalPhase(child.phase))
-    if (unfinishedTasks.length > 0) {
-      return { advanced: false, reason: "存在未完成的子任务（task children 未达终态），无法进入 done。" }
-    }
-    item.phase = "done"
-    item.currentStep = null
-    return { advanced: true, target: "done" }
+    return applyDoneTransition(item)
   }
   if (target === "halt") {
     suspendItem(item, "halt")
@@ -510,6 +531,17 @@ export function recommendForItem(item: WorkItem, workflow: LoadedWorkflow): Engi
     }
   }
 
+  // fix=none 只审会话防御：fail 方向已被策略短路映射 done，implement 逻辑上不可达；
+  // 若因状态异常（如 recovery 误置）落进 implement，不推荐分派（否则只审会话出现修复动作）。
+  if (current.step.id === "implement" && reviewFixPolicyOf(item) === "none") {
+    return {
+      status: "blocked",
+      stepId: current.step.id,
+      agents: [],
+      blockedReason: "只审（fix=none）会话不可进入 implement（修复步骤逻辑上不可达），请核对 state 后按需调用 opx_orch_init(recovery=...) 恢复。",
+    }
+  }
+
   if (checkpointTriggered(item, workflow, current.step)) {
     return {
       status: "checkpoint",

package/src/core/workflow/loader.ts

@@ -54,12 +54,21 @@ export function resolveTaskWorkflowPath(moduleUrl: string): string {
 export const TASK_WORKFLOW_PATH = resolveTaskWorkflowPath(import.meta.url)
 /** simple 流程文件（implement → quality_review → done），与 task.yaml 同目录随插件 bundle 分发。 */
 export const SIMPLE_WORKFLOW_PATH = resolveWorkflowFilePath(import.meta.url, "task-simple.yaml")
+/** 独立审查会话（thorough 颗粒度）流程文件：三层审查 + implement 修复闭环。 */
+export const REVIEW_WORKFLOW_PATH = resolveWorkflowFilePath(import.meta.url, "review.yaml")
+/** 独立审查会话（simple 颗粒度）流程文件：单层合并审查 + implement 修复闭环。 */
+export const REVIEW_SIMPLE_WORKFLOW_PATH = resolveWorkflowFilePath(import.meta.url, "review-simple.yaml")
 
 /**
- * 按 state.mode 选择 workflow 文件：simple → task-simple.yaml，其余（full 或旧 state 缺 mode）→ task.yaml。
- * 旧 state 无 mode 字段一律按 full 处理（读时兜底，不写回），与 D2 固化语义一致。
+ * 选择 workflow 文件：kind 优先于 mode——
+ * - kind=review（独立审查会话，无 mode 字段）：按 reviewScope.granularity 选 review.yaml / review-simple.yaml；
+ * - change 会话：mode=simple → task-simple.yaml，其余（full 或旧 state 缺 mode）→ task.yaml。
+ * 旧 state 无 mode 一律按 full 处理（读时兜底，不写回），与 D2 固化语义一致。
  */
-export function resolveWorkflowPath(state: Pick<OrchestrateState, "mode">): string {
+export function resolveWorkflowPath(state: Pick<OrchestrateState, "mode" | "kind" | "reviewScope">): string {
+  if (state.kind === "review") {
+    return state.reviewScope?.granularity === "simple" ? REVIEW_SIMPLE_WORKFLOW_PATH : REVIEW_WORKFLOW_PATH
+  }
   return state.mode === "simple" ? SIMPLE_WORKFLOW_PATH : TASK_WORKFLOW_PATH
 }
 

package/src/core/workflow/status.ts

@@ -71,7 +71,7 @@ export function renderWorkflowStatusView(
     return renderSuspended(item)
   }
   if (item.phase === "done" || item.phase === "cancelled") {
-    return renderTerminalPhase(item)
+    return renderTerminalPhase(item, options.state)
   }
   if (rec.status === "blocked") {
     if (caller.orchestrator) {
@@ -155,8 +155,11 @@ function renderSuspended(item: WorkItem): string {
   ].join("\n")
 }
 
-/** 终态渲染：done 区分已完成（completed_at 已写）与待收尾；cancelled 呈现已取消。 */
-function renderTerminalPhase(item: WorkItem): string {
+/** 终态渲染：done 区分已完成（completed_at 已写）与待收尾；cancelled 呈现已取消。
+ *  独立审查会话（kind=review）待收口时渲染审查结果报告视图（issue 按严重级别/维度/文件位置归并，
+ *  只审模式的交付物）——fix=none 下 issue 停留 todo 态、step tag=failed、item=done 为合法组合，
+ *  报告视图不渲染豁免/复核操作提示（该通道在只审模式下是死路，无修复者消费裁定结论）。 */
+function renderTerminalPhase(item: WorkItem, state?: OrchestrateState): string {
   if (item.phase === "cancelled") {
     return [
       "# 🚫 任务组已取消",
@@ -165,6 +168,27 @@ function renderTerminalPhase(item: WorkItem): string {
       "",
     ].join("\n")
   }
+  if (state?.kind === "review") {
+    if (item.metadata["completed_at"] !== undefined) {
+      return [
+        "# ✅ 独立审查会话已完成",
+        "",
+        `- **完成时间**: ${item.metadata["completed_at"]}`,
+        "",
+        "审查结果摘要见收尾返回体（opx_orch_complete_task_group）。",
+        "",
+      ].join("\n")
+    }
+    const lines = [
+      "# 🏁 独立审查已完成，待收尾",
+      "",
+      renderReviewReport(item),
+      "",
+      "全部审查层已收口。调用 `opx_orch_complete_task_group` 完成收尾（只审模式销毁 worktree 不合并，审并修模式合并回目标分支）。",
+      "",
+    ]
+    return lines.join("\n")
+  }
   if (item.metadata["completed_at"] !== undefined) {
     return [
       "# ✅ 任务组已完成",
@@ -183,6 +207,42 @@ function renderTerminalPhase(item: WorkItem): string {
   ].join("\n")
 }
 
+/** 独立审查报告视图：issue 按严重级别/维度/文件位置归并的最终报告形态（views 同构渲染共享）。 */
+function renderReviewReport(item: WorkItem): string {
+  const issues = issueChildrenOf(item)
+  if (issues.length === 0) return "未报出任何 issue。"
+  const bySeverity = new Map<string, number>()
+  const byDimension = new Map<string, number>()
+  for (const c of issues) {
+    const sev = c.severity ?? "Info"
+    const f = resolveChildIssueFields(c)
+    bySeverity.set(sev, (bySeverity.get(sev) ?? 0) + 1)
+    byDimension.set(f.dimension, (byDimension.get(f.dimension) ?? 0) + 1)
+  }
+  const lines = [
+    "## 审查结果报告",
+    "",
+    `- **issue 总数**: ${issues.length}`,
+    `- **按严重级别**: ${[...bySeverity.entries()].map(([k, v]) => `${k}=${v}`).join("、")}`,
+    `- **按维度**: ${[...byDimension.entries()].map(([k, v]) => `${k}=${v}`).join("、")}`,
+    "",
+  ]
+  for (const sev of ["Critical", "High", "Medium", "Low", "Info"]) {
+    const group = issues.filter((c) => (c.severity ?? "Info") === sev)
+    if (group.length === 0) continue
+    lines.push(`### ${sev}（${group.length} 个）`, "")
+    for (const c of group) {
+      const id = c.externalId ?? c.id.replace(/^issue:/, "")
+      const f = resolveChildIssueFields(c)
+      lines.push(`- Issue #${id} | 维度:${f.dimension}${f.file ? ` | \`${formatFilePath(f.file, f.line)}\`` : ""}`)
+      lines.push(`  - 描述：${c.description}`)
+      if (typeof c.metadata["suggestion"] === "string") lines.push(`  - 建议：${c.metadata["suggestion"]}`)
+    }
+    lines.push("")
+  }
+  return lines.join("\n")
+}
+
 /** blocked 视图：调用者若为当前 step 轮次 agent 用 blocked_agent 文案，否则用通用 blocked 文案。
  *  verify_* 层当前 agent 且存在本层待复核（review 态）blocking issue 时，列出待复核清单并给出
  *  recheck_adjudications 自助恢复指引（上次提交漏带复核导致门禁阻塞的可补交解除）；
@@ -499,7 +559,8 @@ function renderAgentWorking(
 
   // tool review 检查点增量三分支（A4）：仅 verify_tool 的 reviewer-tool 且提供了变更检测结果时生效；
   // toolChanges 缺省（未预计算）时维持既有全量渲染，不误伤其他 agent/step 的通用渲染。
-  if (step?.id === "verify_tool" && agentToReviewLayer(ctxAgent) === "tool" && toolChanges) {
+  // 独立审查 full 形态（scopeFull 哨兵）不走三分支——审查锚点为全量代码库，非「未检出变更」。
+  if (step?.id === "verify_tool" && agentToReviewLayer(ctxAgent) === "tool" && toolChanges && !toolChanges.scopeFull) {
     const { active, pending } = toolPendingChildren(item, ctxAgent)
     if (!toolChanges.hasNonDocChange && active.length === 0 && pending.length === 0) {
       return renderToolDirectSubmit(exemptedHits)
@@ -564,7 +625,9 @@ function renderAgentWorking(
   // test_results），作为分级复验的事实输入——低成本实跑对照、高成本项核验申报+抽样重放均以该申报为
   // 证据源。仅 quality_review step 渲染（消费方是 reviewer）；implement 视图与其余 step 视图不受影响
   //（dev 自己刚产出该申报，无需回显）。
-  if (step?.id === "quality_review") {
+  // 开发者自检申报区块仅 change 会话渲染（simple 模式 quality_review 的分级复验事实输入）；
+  // 独立审查会话无该数据源（无 dev 实施申报语义），不渲染空区块。
+  if (step?.id === "quality_review" && state.kind !== "review") {
     lines.push(...renderDevSelfCheckDeclaration(item.metadata))
   }
   lines.push(...renderAgentSummaries(readAgentSummaries(item), ctxAgent))
@@ -843,6 +906,14 @@ function renderToolChangesEvidence(
   const baseRef = tg.baseRef ?? undefined
   const rangeRef = checkpoint ?? baseRef
   const lines = [`## 本次变更证据（${label.title}）`, ""]
+  // 独立审查 full 形态哨兵：审查锚点为全量代码库（无区间可界定），不渲染「未检出变更」误报
+  if (toolChanges.scopeFull) {
+    lines.push(
+      "- **口径**: 全量代码库审查（独立审查 full 形态）——无区间界定，工具检查与审查覆盖整个代码库",
+      "",
+    )
+    return [lines.join("\n")]
+  }
   if (checkpoint) {
     lines.push(
       `- **口径**: 本次为「${label.title}（${checkpoint}..HEAD）」的增量区间（含已提交与未提交的非 openspec 变更）；` +