@ifrankwang/openspec-agents 0.118.0

package/src/core/workflow/loader.ts

@@ -0,0 +1,277 @@
+import { readFileSync, existsSync } from "node:fs"
+import { join, dirname, resolve as pathResolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import yaml from "js-yaml"
+import type {
+  WorkflowConfig,
+  PhaseConfig,
+  StepConfig,
+  StepAgent,
+  StepTransitions,
+  WorkItemPhase,
+  WorkflowCommon,
+} from "./types.ts"
+import { WORK_ITEM_PHASES, stepAgentIds } from "./types.ts"
+import { DIMENSION_AGENT_MAP } from "../constants.ts"
+
+const SPECIAL_TRANSITIONS = ["done", "halt"] as const
+const PHASE_NAMES = new Set<string>(WORK_ITEM_PHASES)
+const QUALITY_REVIEW_STEP_ID = "verify_quality"
+
+export interface LoadedWorkflow extends WorkflowConfig {
+  stepMap: Map<string, { step: StepConfig; phase: PhaseConfig }>
+}
+
+/**
+ * 定位 task.yaml：源码（src/core/workflow/ 上溯 3 级=仓库根）、插件包 dist 形态
+ * （dist/zcode-plugin/.mcp-server/ 上溯 1 级=插件根）与 ZCode 缓存嵌套形态
+ * （cache/<marketplace>/<plugin>/<version>/.mcp-server/ 上溯 1 级=版本目录）部署深度不同，
+ * 故从模块所在目录逐级上溯探测 assets/workflows/task.yaml，首个命中即采用（首中即用）。
+ * bundle 单文件合并后 import.meta.url 指向部署位置（cli.mjs），源码形态指向本文件自身，两者自然成立。
+ */
+export function resolveTaskWorkflowPath(moduleUrl: string): string {
+  const startDir = dirname(fileURLToPath(moduleUrl))
+  let dir = startDir
+  let probed = 0
+  for (;;) {
+    const candidate = pathResolve(dir, "assets", "workflows", "task.yaml")
+    if (existsSync(candidate)) return candidate
+    probed++
+    const parent = dirname(dir)
+    if (parent === dir) break // 到达文件系统根
+    dir = parent
+  }
+  throw new Error(`workflow 文件缺失：从 ${startDir} 上溯 ${probed} 级未找到 assets/workflows/task.yaml`)
+}
+
+// 模块加载期求值，workflow 缺失即启动抛错（fail-fast）：opx_* 工具全部依赖 workflow，缺失时
+// server 无可用性，启动即抛比首次调用才报错更早且可读（可读错误替代原生 ENOENT）。
+export const TASK_WORKFLOW_PATH = resolveTaskWorkflowPath(import.meta.url)
+
+const workflowFileCache = new Map<string, LoadedWorkflow>()
+
+/** 读取 workflow YAML 文件并解析，进程内按路径缓存（submit / status 共用）。 */
+export function loadWorkflowFile(filePath: string): LoadedWorkflow {
+  let wf = workflowFileCache.get(filePath)
+  if (!wf) {
+    wf = loadWorkflow(readFileSync(filePath, "utf-8"))
+    workflowFileCache.set(filePath, wf)
+  }
+  return wf
+}
+
+interface RawStep {
+  id?: unknown
+  agents?: unknown
+  always_run?: unknown
+  max_retries?: unknown
+  instructions?: unknown
+  constraints?: unknown
+  transitions?: unknown
+}
+
+interface RawPhase {
+  name?: unknown
+  steps?: unknown
+}
+
+interface RawWorkflow {
+  id?: unknown
+  name?: unknown
+  max_retries?: unknown
+  phases?: unknown
+  common?: unknown
+}
+
+function fail(message: string): never {
+  throw new Error(message)
+}
+
+function expectString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    fail(`workflow 配置非法：${path} 必须是非空字符串，收到 ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+function expectPositiveInt(value: unknown, path: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    fail(`workflow 配置非法：${path} 必须是正整数，收到 ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+function expectStringArray(value: unknown, path: string): string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== "string")) {
+    fail(`workflow 配置非法：${path} 必须是非空字符串数组，收到 ${JSON.stringify(value)}`)
+  }
+  return value as string[]
+}
+
+/** agents 对象数组解析：每个元素须含非空 id 与非空字符串数组 capability_tags（agent 级 capability_tags 必填）。 */
+function expectAgentList(value: unknown, path: string): StepAgent[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    fail(`workflow 配置非法：${path} 必须是非空对象数组（每个元素含 id 与 capability_tags），收到 ${JSON.stringify(value)}`)
+  }
+  return value.map((v, i) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v)) {
+      fail(`workflow 配置非法：${path}[${i}] 必须是对象（含 id 与 capability_tags），收到 ${JSON.stringify(v)}`)
+    }
+    const a = v as { id?: unknown; capability_tags?: unknown }
+    return {
+      id: expectString(a.id, `${path}[${i}].id`),
+      capability_tags: expectStringArray(a.capability_tags, `${path}[${i}].capability_tags`),
+    }
+  })
+}
+
+function expectOptionalPositiveInt(value: unknown, path: string): number | undefined {
+  if (value === undefined) return undefined
+  return expectPositiveInt(value, path)
+}
+
+function expectOptionalNonEmptyStringArray(value: unknown, path: string): string[] | undefined {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== "string" || v.trim() === "")) {
+    fail(`workflow 配置非法：${path} 必须是非空字符串数组，收到 ${JSON.stringify(value)}`)
+  }
+  return value as string[]
+}
+
+/** common 块解析：instructions / constraints 可选非空字符串数组（全缺省时降级 undefined）。 */
+function parseCommon(raw: unknown, workflowId: string): WorkflowCommon | undefined {
+  if (raw === undefined) return undefined
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    fail(`workflow "${workflowId}" 配置非法：common 必须是对象`)
+  }
+  const c = raw as { instructions?: unknown; constraints?: unknown }
+  const instructions = expectOptionalNonEmptyStringArray(c.instructions, "common.instructions")
+  const constraints = expectOptionalNonEmptyStringArray(c.constraints, "common.constraints")
+  if (instructions === undefined && constraints === undefined) return undefined
+  return { instructions, constraints }
+}
+
+/** verify_quality 双源一致性校验：存在该 step 时，agents 的 id 集合须等于质量维度 agent 映射值集合（改一处不同步即不一致）。 */
+function assertQualityAgentsConsistent(workflowId: string, stepMap: Map<string, { step: StepConfig; phase: PhaseConfig }>): void {
+  const qualityStep = stepMap.get(QUALITY_REVIEW_STEP_ID)
+  if (!qualityStep) return
+  const declared = new Set(stepAgentIds(qualityStep.step))
+  const expected = new Set(Object.values(DIMENSION_AGENT_MAP))
+  if (declared.size !== expected.size || ![...expected].every((a) => declared.has(a))) {
+    fail(
+      `workflow "${workflowId}" 配置非法：${QUALITY_REVIEW_STEP_ID}.agents（${JSON.stringify([...declared])}）与质量维度 agent 映射（${JSON.stringify([...expected])}）不一致，两处须保持同一集合`
+    )
+  }
+}
+
+function parseTransitions(raw: unknown, stepId: string, validStepIds: Set<string>): StepTransitions {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    fail(`workflow 配置非法：step "${stepId}" 的 transitions 必须是对象`)
+  }
+  const t = raw as Record<string, unknown>
+  const out: Partial<StepTransitions> = {}
+  for (const key of ["on_pass", "on_fail"] as const) {
+    const target = t[key]
+    if (typeof target !== "string" || target === "") {
+      fail(`workflow 配置非法：step "${stepId}" 的 transitions.${key} 必须是非空字符串`)
+    }
+    if (!SPECIAL_TRANSITIONS.includes(target as (typeof SPECIAL_TRANSITIONS)[number]) && !validStepIds.has(target)) {
+      fail(
+        `workflow 配置非法：step "${stepId}" 的 transitions.${key} 目标 "${target}" 不存在（既非已声明 step id，也非 done/halt 特殊值）`
+      )
+    }
+    out[key] = target as StepTransitions[typeof key]
+  }
+  return out as StepTransitions
+}
+
+export function loadWorkflow(yamlText: string): LoadedWorkflow {
+  let raw: unknown
+  try {
+    raw = yaml.load(yamlText)
+  } catch (err) {
+    fail(`workflow YAML 解析失败：${(err as Error).message}`)
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    fail("workflow 配置非法：顶层必须是 YAML 映射对象")
+  }
+  const wf = raw as RawWorkflow
+  const id = expectString(wf.id, "id")
+  const maxRetries = expectPositiveInt(wf.max_retries, "max_retries")
+  const name = typeof wf.name === "string" && wf.name.trim() !== "" ? wf.name : undefined
+
+  if (!Array.isArray(wf.phases) || wf.phases.length === 0) {
+    fail(`workflow "${id}" 配置非法：phases 必须是非空数组`)
+  }
+
+  const phases: PhaseConfig[] = []
+  const stepMap = new Map<string, { step: StepConfig; phase: PhaseConfig }>()
+  const rawTransitions = new Map<string, unknown>()
+  const seenPhaseNames = new Set<string>()
+  const allStepIds = new Set<string>()
+
+  for (const [phaseIdx, rawPhase] of wf.phases.entries()) {
+    if (typeof rawPhase !== "object" || rawPhase === null || Array.isArray(rawPhase)) {
+      fail(`workflow "${id}" 配置非法：phases[${phaseIdx}] 必须是对象`)
+    }
+    const rp = rawPhase as RawPhase
+    const phaseName = expectString(rp.name, `phases[${phaseIdx}].name`)
+    if (!PHASE_NAMES.has(phaseName)) {
+      fail(
+        `workflow "${id}" 配置非法：phases[${phaseIdx}].name "${phaseName}" 不是合法 phase（合法值：${WORK_ITEM_PHASES.join(", ")}）`
+      )
+    }
+    if (seenPhaseNames.has(phaseName)) {
+      fail(`workflow "${id}" 配置非法：phase "${phaseName}" 重复声明`)
+    }
+    seenPhaseNames.add(phaseName)
+    const phase: PhaseConfig = { name: phaseName as WorkItemPhase, steps: [] }
+
+    if (!Array.isArray(rp.steps) || rp.steps.length === 0) {
+      fail(`workflow "${id}" 配置非法：phase "${phaseName}" 的 steps 必须是非空数组`)
+    }
+    for (const [stepIdx, rawStep] of rp.steps.entries()) {
+      if (typeof rawStep !== "object" || rawStep === null || Array.isArray(rawStep)) {
+        fail(`workflow "${id}" 配置非法：phase "${phaseName}" steps[${stepIdx}] 必须是对象`)
+      }
+      const rs = rawStep as RawStep
+      const stepId = expectString(rs.id, `phase "${phaseName}" steps[${stepIdx}].id`)
+      if (allStepIds.has(stepId)) {
+        fail(`workflow "${id}" 配置非法：step id "${stepId}" 重复声明`)
+      }
+      allStepIds.add(stepId)
+      rawTransitions.set(stepId, rs.transitions)
+      const agents = expectAgentList(rs.agents, `step "${stepId}" 的 agents`)
+      const step: StepConfig = {
+        id: stepId,
+        agents,
+        always_run: typeof rs.always_run === "boolean" ? rs.always_run : undefined,
+        max_retries: expectOptionalPositiveInt(rs.max_retries, `step "${stepId}" 的 max_retries`),
+        instructions: expectOptionalNonEmptyStringArray(rs.instructions, `step "${stepId}" 的 instructions`),
+        constraints: expectOptionalNonEmptyStringArray(rs.constraints, `step "${stepId}" 的 constraints`),
+        transitions: { on_pass: "done", on_fail: "halt" },
+      }
+      phase.steps.push(step)
+      stepMap.set(stepId, { step, phase })
+    }
+    phases.push(phase)
+  }
+
+  for (const { step } of stepMap.values()) {
+    step.transitions = parseTransitions(rawTransitions.get(step.id), step.id, allStepIds)
+  }
+
+  assertQualityAgentsConsistent(id, stepMap)
+
+  return { id, name, max_retries: maxRetries, phases, stepMap, common: parseCommon(wf.common, id) }
+}
+
+export function findStepByWorkItemPhase(
+  workflow: LoadedWorkflow,
+  phase: WorkItemPhase,
+): { step: StepConfig; phase: PhaseConfig } | null {
+  for (const entry of workflow.stepMap.values()) {
+    if (entry.phase.name === phase) return entry
+  }
+  return null
+}

package/src/core/workflow/poller.ts

@@ -0,0 +1,159 @@
+import { readStateByWorktree, writeState } from "../state.ts"
+import { getCollectors, type CollectorAdapter } from "./collector.ts"
+import type { WorkItem } from "./types.ts"
+
+const DEFAULT_TICK_MS = 1_000
+
+export interface PollOnceResult {
+  added: string[]
+  skipped: string[]
+  errors: string[]
+}
+
+export interface PollAdapterResult {
+  added: string[]
+  skipped: string[]
+  error?: string
+}
+
+/** 去重键：source + externalId，跨 adapter 来源隔离。 */
+function dedupeKey(item: WorkItem): string {
+  return `${item.source}:${item.externalId ?? item.id}`
+}
+
+/**
+ * 拉取单个 adapter：pull → transform → 按 source+externalId 去重写入 state.workItems，
+ * 并对新增项执行 writeback（失败在 item.writeback 记录 lastAttempt/error，不阻塞调度）。
+ */
+export async function pollAdapter(
+  worktree: string,
+  adapter: CollectorAdapter,
+  changeId?: string,
+): Promise<PollAdapterResult> {
+  let raw: unknown[]
+  try {
+    raw = await adapter.pull()
+  } catch (err) {
+    return { added: [], skipped: [], error: `[poller] adapter "${adapter.name}" pull 失败：${(err as Error).message}` }
+  }
+
+  let items: WorkItem[]
+  try {
+    items = adapter.transform(raw)
+  } catch (err) {
+    return { added: [], skipped: [], error: `[poller] adapter "${adapter.name}" transform 失败：${(err as Error).message}` }
+  }
+
+  let state
+  try {
+    state = await readStateByWorktree(worktree, changeId)
+  } catch (err) {
+    return { added: [], skipped: [], error: `[poller] adapter "${adapter.name}" 读取编排状态失败：${(err as Error).message}` }
+  }
+  if (!state) {
+    // 无可用编排会话：静默跳过，不产生 error（避免 poller 每 tick 刷 console.error 噪音）
+    return { added: [], skipped: [] }
+  }
+  state.workItems ??= []
+  const existing = new Set<string>(state.workItems.map(dedupeKey))
+
+  const added: string[] = []
+  const skipped: string[] = []
+  for (const item of items) {
+    const key = dedupeKey(item)
+    if (existing.has(key)) {
+      skipped.push(item.id)
+      continue
+    }
+    state.workItems.push(item)
+    existing.add(key)
+    added.push(item.id)
+
+    try {
+      const result = await adapter.writeback(item, item)
+      if (result.success) {
+        item.writeback = { ...item.writeback, lastAttempt: new Date().toISOString(), lastSuccess: new Date().toISOString() }
+      } else {
+        item.writeback = { ...item.writeback, lastAttempt: new Date().toISOString(), error: result.error ?? "writeback 失败" }
+      }
+    } catch (err) {
+      item.writeback = { ...item.writeback, lastAttempt: new Date().toISOString(), error: (err as Error).message }
+    }
+  }
+
+  // 仅在本次有新增项（added 会触发 writeback 状态变更）时才写盘，全量 skipped 时跳过
+  // 避免无意义 I/O。read-modify-write 的无锁并发问题本阶段保持现状（单实例部署，
+  // 多实例并发场景见后续设计，此处不引入锁）。
+  if (added.length > 0) {
+    await writeState(worktree, state)
+  }
+  return { added, skipped }
+}
+
+/**
+ * 单次全量拉取：遍历所有已注册 adapter 执行 pollAdapter，聚合结果。
+ * 单个 adapter 失败不阻塞其余 adapter。
+ */
+export async function pollOnce(worktree: string, changeId?: string): Promise<PollOnceResult> {
+  const result: PollOnceResult = { added: [], skipped: [], errors: [] }
+  for (const adapter of getCollectors()) {
+    const r = await pollAdapter(worktree, adapter, changeId)
+    result.added.push(...r.added)
+    result.skipped.push(...r.skipped)
+    if (r.error) {
+      result.errors.push(r.error)
+      console.error(r.error)
+    }
+  }
+  return result
+}
+
+/** 活跃轮询器注册表（按 worktree 去重，插件热重载不累积定时器）。 */
+const activePollers = new Map<string, { stop: () => void }>()
+
+/**
+ * 启动定时拉取：按全局 tick（intervalMs）轮询各已注册 collector，每个 adapter
+ * 按自身 pollIntervalMs 到期后执行单次拉取（拉取失败仅记录不阻塞后续）。
+ * worktree 为动态上下文，由插件启动时注入。
+ * 同 worktree 重复调用幂等：复用已注册的轮询器，不新建定时器。
+ */
+export function startPolling(
+  worktree: string,
+  options?: { intervalMs?: number; changeId?: string },
+): { stop(): void } {
+  const existing = activePollers.get(worktree)
+  if (existing) return existing
+
+  const tickMs = options?.intervalMs ?? DEFAULT_TICK_MS
+  const changeId = options?.changeId
+  const lastRun = new Map<string, number>()
+
+  const timer = setInterval(() => {
+    const now = Date.now()
+    for (const adapter of getCollectors()) {
+      const last = lastRun.get(adapter.name) ?? 0
+      if (now - last < adapter.pollIntervalMs) continue
+      lastRun.set(adapter.name, now)
+      // pollAdapter 不 reject（错误以 {error} 返回），此处消费并记录，避免调度错误静默。
+      pollAdapter(worktree, adapter, changeId).then((r) => {
+        if (r.error) console.error(r.error)
+      })
+    }
+  }, tickMs)
+  timer.unref?.()
+
+  const handle: { stop(): void } = {
+    stop: () => {
+      clearInterval(timer)
+      if (activePollers.get(worktree) === handle) activePollers.delete(worktree)
+    },
+  }
+  activePollers.set(worktree, handle)
+  return handle
+}
+
+/** 清理全部活跃轮询器（测试隔离用，非编排业务接口）。 */
+export function __resetPoller(): void {
+  for (const { stop } of activePollers.values()) stop()
+  activePollers.clear()
+}

package/src/core/workflow/reset.ts

@@ -0,0 +1,93 @@
+import type { WorkItem } from "./types.ts"
+import { tagKey } from "./types.ts"
+import { clearStepTags, isTerminalPhase } from "./engine.ts"
+import { DIMENSION_AGENT_MAP, reviewLayerFromMetadata } from "../constants.ts"
+import { REVIEW_DIMENSIONS } from "../types.ts"
+import type { Dimension, ReviewLayer } from "../types.ts"
+import { issueChildrenOf } from "../task-children.ts"
+
+export interface ResetReviewTagsInput {
+  fixedSourcePhases: string[]
+  exemptSourcePhases: string[]
+  touchedQualityDims: string[]
+}
+
+/** 解析 child 的 issue 归因字段（报源层/dimension/file/line），缺省 tool/style/""/0。
+ *  报源层由 metadata.source 经 agentToReviewLayer 反推，source_phase 仅作历史 state 兜底。 */
+export function resolveChildIssueFields(child: WorkItem): {
+  sourcePhase: ReviewLayer
+  dimension: Dimension
+  file: string
+  line: number
+} {
+  const sourcePhase = reviewLayerFromMetadata(child)
+  const dimension = (REVIEW_DIMENSIONS as readonly string[]).includes(child.metadata["dimension"] as string)
+    ? (child.metadata["dimension"] as Dimension)
+    : "style"
+  return {
+    sourcePhase,
+    dimension,
+    file: typeof child.metadata["file"] === "string" ? child.metadata["file"] : "",
+    line: typeof child.metadata["line"] === "number" ? child.metadata["line"] : 0,
+  }
+}
+
+/**
+ * dev 提交后按 issue 归因分层重置 review 验证标记（旧 review.ts devSubmitExecute:298-318 分层重置的精确复刻）。
+ * - 任一 fixed（代码变更）→ 清 verify_tool（tool 层确定性检查须基于最新代码重跑）
+ * - fixed 中属 task 层 → 额外清 verify_task
+ * - exempt 属 task 层 → 清 verify_tool + verify_task
+ * - exempt 属 tool 层 → 清 verify_tool
+ * - fixed 中属 quality 层且维度 dim → 只清 verify_quality 中 DIMENSION_AGENT_MAP[dim] 对应 agent 的 tag
+ * - exempt 不清 quality 维度 tag：豁免=接受现状、不修改代码，已 passed 维度无需重审
+ * - 豁免不改代码（exempt 无 tool/task 层）→ 不清 verify_tool/verify_task
+ */
+export function resetReviewTagsOnFix(item: WorkItem, input: ResetReviewTagsInput): void {
+  const fixed = new Set(input.fixedSourcePhases)
+  const exempt = new Set(input.exemptSourcePhases)
+
+  if (fixed.size > 0) {
+    clearStepTags(item, "verify_tool")
+    if (fixed.has("task")) clearStepTags(item, "verify_task")
+  }
+
+  if (exempt.has("task")) {
+    clearStepTags(item, "verify_tool")
+    clearStepTags(item, "verify_task")
+  } else if (exempt.has("tool")) {
+    clearStepTags(item, "verify_tool")
+  }
+
+  for (const d of input.touchedQualityDims) {
+    const agent = DIMENSION_AGENT_MAP[d as Dimension]
+    if (agent) {
+      delete item.tags[tagKey("verify_quality", agent)]
+    }
+  }
+}
+
+/**
+ * new_children 入库前去重（旧 deduplicateAndAddIssues 语义）：
+ * 与「未终结态（非 done/cancelled）」的既有 issue child 按 (报源层/dimension/file/line/description) 比对，
+ * 命中即丢弃并计数；已终态 child 不参与判重（允许 reviewer 重报已关闭问题）。
+ * 比对集仅限 issue child——task child 的 description 可能与新 issue 恰好相同，混入会误吞新报。
+ */
+export function dedupeNewChildren(item: WorkItem, newChildren: WorkItem[]): { accepted: WorkItem[]; dedupedCount: number } {
+  const keyOf = (child: WorkItem): string => {
+    const f = resolveChildIssueFields(child)
+    return [f.sourcePhase, f.dimension, f.file, f.line, child.description].join("\u0000")
+  }
+  const accepted: WorkItem[] = []
+  let dedupedCount = 0
+  const existing = issueChildrenOf(item)
+  for (const nc of newChildren) {
+    const key = keyOf(nc)
+    const duplicate = existing.some((child) => !isTerminalPhase(child.phase) && keyOf(child) === key)
+    if (duplicate) {
+      dedupedCount++
+      continue
+    }
+    accepted.push(nc)
+  }
+  return { accepted, dedupedCount }
+}