@ifrankwang/openspec-agents 0.118.0

package/src/adapters/zcode/index.ts

@@ -0,0 +1,32 @@
+/**
+ * zcode 适配器：ZCode 官方插件包生成（Plugin 机制，zcode.z.ai/en/docs/plugin）。
+ * 复用共享生成器 src/adapters/plugin-common/，差异参数：清单目录 .zcode-plugin/。
+ *
+ * 与 claude code / codex 的文件分发形态不同：zcode 不再写 ~/.zcode 与项目 .zcode/config.json，
+ * 插件安装/启用/禁用/卸载均为 GUI 动作，子代理为插件只读形态。
+ *
+ * 已知限制（接入文档注明）：
+ * - zcode 自定义子代理为 Beta，子代理提问能力未经官方确认——默认无人值守规避；
+ * - GUI 安装动作为人工步骤，本适配器仅保证生成结构与官方 schema 一致。
+ */
+import { resolve } from "../agent-md.ts"
+import {
+  buildPluginPackage,
+  type PluginPackageResult,
+} from "../plugin-common/index.ts"
+
+/** 默认插件包输出目录（dist/ 已 gitignore，生成物不入库）。 */
+export const ZCODE_PLUGIN_DIR = resolve("dist", "zcode-plugin")
+const MANIFEST_DIR_NAME = ".zcode-plugin"
+
+export type ZcodePluginBuildResult = PluginPackageResult
+
+/**
+ * 生成 ZCode 官方插件包到 outDir（默认 dist/zcode-plugin/）：
+ * .zcode-plugin/plugin.json 清单、agents/*.md、skills/<名>/、assets/workflows/、.mcp.json、
+ * .mcp-server/cli.mjs bundle。
+ * 返回生成的组件清单供调用方/测试断言。
+ */
+export function buildZcodePlugin(outDir: string = ZCODE_PLUGIN_DIR): ZcodePluginBuildResult {
+  return buildPluginPackage({ outDir, manifestDirName: MANIFEST_DIR_NAME })
+}

package/src/core/constants.ts

@@ -0,0 +1,46 @@
+import type { ReviewDimension, ReviewLayer } from "./types.ts"
+import type { WorkItem } from "./workflow/types.ts"
+
+export const STATE_DIR_NAME = "openspec"
+export const STATE_SUBDIR_NAME = "states"
+/** 旧布局 .opencode/.orchestrate_state（读取兼容 + 首次新目录写入时幂等迁移）。 */
+export const LEGACY_STATE_DIR_NAME = ".opencode"
+export const LEGACY_STATE_SUBDIR_NAME = ".orchestrate_state"
+export const SEVERITY_LEVELS = ["Critical", "High", "Medium", "Low", "Info"] as const
+export const BLOCKING_SEVERITIES = ["Critical", "High", "Medium", "Low"] as const
+
+export const DIMENSION_AGENT_MAP: Record<ReviewDimension, string> = {
+  style: "openspec-reviewer-style",
+  architecture: "openspec-reviewer-architecture",
+  performance: "openspec-reviewer-performance",
+  security: "openspec-reviewer-security",
+  maintainability: "openspec-reviewer-maintainability",
+}
+
+/** agent → quality 维度反查（DIMENSION_AGENT_MAP 值反向映射），未命中返回 undefined。 */
+export function agentToReviewDimension(agent: string): ReviewDimension | undefined {
+  return (Object.keys(DIMENSION_AGENT_MAP) as ReviewDimension[]).find((d) => DIMENSION_AGENT_MAP[d] === agent)
+}
+
+/** agent → issue 报源层（tool/task/quality）：tool/task reviewer 直接映射，quality reviewer 经维度反查命中即 quality。其余 agent 返回 undefined。 */
+export function agentToReviewLayer(agent: string | undefined): ReviewLayer | undefined {
+  if (!agent) return undefined
+  if (agent === "openspec-reviewer-tool") return "tool"
+  if (agent === "openspec-reviewer-task") return "task"
+  if (agentToReviewDimension(agent)) return "quality"
+  return undefined
+}
+
+/** 安全读取 issue child 的报源 agent（metadata.source），非 string 返回 undefined。 */
+export function readIssueSource(child: WorkItem): string | undefined {
+  return typeof child.metadata["source"] === "string" ? child.metadata["source"] : undefined
+}
+
+/** 从 child.metadata 解析 issue 报源层：source 反推 → 旧 source_phase 兼容历史 state → 缺省 tool。 */
+export function reviewLayerFromMetadata(child: WorkItem): ReviewLayer {
+  const source = readIssueSource(child)
+  const bySource = agentToReviewLayer(source)
+  if (bySource) return bySource
+  const rawPhase = child.metadata["source_phase"]
+  return rawPhase === "tool" || rawPhase === "task" || rawPhase === "quality" ? rawPhase : "tool"
+}

package/src/core/dashboard.ts

@@ -0,0 +1,101 @@
+import type { OrchestrateState } from "./types.ts"
+import { readStateByWorktree, readStateByChangeId, getStateDir } from "./state.ts"
+import { readdirSync, existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import path from "path"
+import type { WorkItem, WorkItemType, WorkItemPhase, Verdict } from "./workflow/types.ts"
+
+/** 看板卡片投影：WorkItem → 前端可渲染结构。 */
+export interface WorkItemCard {
+  id: string
+  type: WorkItemType
+  title: string
+  description: string
+  phase: WorkItemPhase
+  suspended: boolean
+  suspendReason?: string
+  currentStep: string | null
+  labels: string[]
+  source: string
+  severity?: string
+  agentVerdicts: Array<{ stepId: string; agentKey: string; verdict: Verdict }>
+  children: Array<{ id: string; type: WorkItemType; title: string; phase: WorkItemPhase; severity?: string }>
+}
+
+/** taskGroup → 看板投影（旧三面板视图已随单轨化移除）。 */
+
+/**
+ * WorkItem → 看板卡片。
+ * tags 键为 `${stepId}:${agentKey}`，拆解为可渲染的 agent 裁决数组；
+ * metadata 仅暴露无下划线前缀的业务字段（suspend_reason），内部字段（_ 前缀）不泄露。
+ */
+function toWorkItemCard(item: WorkItem): WorkItemCard {
+  const agentVerdicts = Object.entries(item.tags).map(([key, verdict]) => {
+    const sep = key.indexOf(":")
+    return {
+      stepId: sep === -1 ? key : key.slice(0, sep),
+      agentKey: sep === -1 ? key : key.slice(sep + 1),
+      verdict,
+    }
+  })
+  const suspendReason =
+    typeof item.metadata["suspend_reason"] === "string" ? (item.metadata["suspend_reason"] as string) : undefined
+  return {
+    id: item.id,
+    type: item.type,
+    title: item.title,
+    description: item.description,
+    phase: item.phase,
+    suspended: item.suspended,
+    suspendReason,
+    currentStep: item.currentStep,
+    labels: item.labels,
+    source: item.source,
+    severity: item.severity,
+    agentVerdicts,
+    children: item.children.map((child) => ({
+      id: child.id,
+      type: child.type,
+      title: child.title,
+      phase: child.phase,
+      severity: child.severity,
+    })),
+  }
+}
+
+/** OrchestrateState → 看板投影（workItems 单轨 + workItemCards 5 列视图）。 */
+function projectState(state: OrchestrateState) {
+  return {
+    active: true,
+    changeId: state.changeId,
+    currentTaskGroupId: state.taskGroupId,
+    baseBranch: state.baseBranch,
+    createdAt: state.createdAt,
+    updatedAt: state.updatedAt,
+    workItems: state.workItems,
+    workItemCards: state.workItems.map(toWorkItemCard),
+  }
+}
+
+export async function readDashboardState(worktree: string, changeId?: string) {
+  if (changeId) {
+    const state = await readStateByWorktree(worktree, changeId)
+    if (!state) return null
+    return projectState(state)
+  }
+
+  const stateDir = getStateDir(worktree)
+  if (!existsSync(stateDir)) return null
+  const files = readdirSync(stateDir).filter(f => f.endsWith(".json"))
+  const results: ReturnType<typeof projectState>[] = []
+  for (const f of files) {
+    try {
+      const raw = await readFile(path.join(stateDir, f), "utf-8")
+      const state = JSON.parse(raw) as OrchestrateState
+      if (!state.changeId) continue
+      results.push(projectState(state))
+    } catch { /* skip unreadable */ }
+  }
+  if (results.length === 1) return results[0]
+  return results.length > 0 ? results : null
+}

package/src/core/derive.ts

@@ -0,0 +1,146 @@
+import type { TaskGroupState, IssueItem, OrchestrateState, Phase, QualityLayerProgress, ExecutionBoundary, BlockerItem } from "./types.ts"
+import { BLOCKING_SEVERITIES } from "./constants.ts"
+import type { WorkItem, WorkItemPhase } from "./workflow/types.ts"
+import type { ToolContext } from "./tools/types.ts"
+import { EXEMPT_REQUEST_KEY } from "./workflow/types.ts"
+import { resolveChildIssueFields } from "./workflow/reset.ts"
+import { taskListOf, issueChildrenOf } from "./task-children.ts"
+
+export function createEmptyQualityProgress(): QualityLayerProgress {
+  return {
+    style: "pending",
+    architecture: "pending",
+    performance: "pending",
+    security: "pending",
+    maintainability: "pending",
+  }
+}
+
+export function blockingIssues<T extends { severity: string; status?: string; sourcePhase?: string; dimension?: string }>(
+  issues: T[],
+  sourcePhase?: string,
+  dimension?: string,
+): T[] {
+  return issues.filter(
+    (i) =>
+      (!sourcePhase || i.sourcePhase === sourcePhase) &&
+      (!dimension || i.dimension === dimension) &&
+      isStatusUnresolved(i.status) &&
+      isBlockingIssue(i)
+  )
+}
+
+export function hasBlockingIssues(issues: Array<{ severity: string; status?: string; sourcePhase?: string; dimension?: string }>, sourcePhase?: string, dimension?: string): boolean {
+  return blockingIssues(issues, sourcePhase, dimension).length > 0
+}
+
+export function isBlockingIssue(i: { severity: string }): boolean {
+  return (BLOCKING_SEVERITIES as readonly string[]).includes(i.severity)
+}
+
+export const ISSUE_UNRESOLVED_STATUSES = ["open", "rejected", "submitted", "exemption_requested"] as const
+
+export function isStatusUnresolved(status?: string): boolean {
+  return !status || (ISSUE_UNRESOLVED_STATUSES as readonly string[]).includes(status)
+}
+
+/** 独占工具权限校验：仅「编排视角」调用者（各 agent 主代理）可调用。 */
+export function assertOrchestrator(ctx: ToolContext, toolName: string): void {
+  if (!ctx.orchestrator) {
+    throw new Error(`工具 "${toolName}" 仅限编排者（主代理）调用，当前调用者为 "${ctx.agent}"。`)
+  }
+}
+
+export function assertAgent(agent: string, toolName: string, allowedAgents: string[]): void {
+  if (!allowedAgents.includes(agent)) {
+    throw new Error(`工具 "${toolName}" 仅限 [${allowedAgents.join(", ")}] 调用，当前调用者为 "${agent}"。`)
+  }
+}
+
+export function findTaskGroup(state: OrchestrateState, id: string): TaskGroupState {
+  const item = state.workItems.find((w) => w.id === `task:${id}`)
+  if (!item) throw new Error(`任务组 "${id}" 不在任务清单中。`)
+  return taskGroupFromWorkItem(item)
+}
+
+// ─── 单轨只读投影：workItems（事实源）→ TaskGroupState（旧流工具/视图读侧兼容）───
+
+function childPhaseToIssueStatus(phase: WorkItemPhase): IssueItem["status"] {
+  switch (phase) {
+    case "done": return "verified"
+    case "cancelled": return "exempted"
+    case "review": return "submitted"
+    default: return "open"
+  }
+}
+
+/** child → IssueItem 投影（旧流工具/视图读侧兼容，children 为事实源）。 */
+function projectIssueFromChild(child: WorkItem): IssueItem {
+  const f = resolveChildIssueFields(child)
+  const baseStatus = childPhaseToIssueStatus(child.phase)
+  const hasExemptRequest = child.metadata[EXEMPT_REQUEST_KEY] !== undefined
+  return {
+    id: child.externalId ?? child.id.replace(/^issue:/, ""),
+    dimension: f.dimension,
+    sourcePhase: f.sourcePhase,
+    severity: child.severity ?? "Info",
+    file: f.file,
+    line: f.line,
+    description: child.description,
+    suggestion: typeof child.metadata["suggestion"] === "string" ? child.metadata["suggestion"] : "",
+    // 待裁定豁免项（exempt_request 标记）无条件投影 exemption_requested：申请豁免的 issue 已进入
+    // review（待裁定）态，baseStatus 为 submitted，若限定 open 态会丢失豁免申请语义（被误标为待复核）。
+    status: hasExemptRequest ? "exemption_requested" : baseStatus,
+    refixCount: typeof child.metadata["refix_count"] === "number" ? child.metadata["refix_count"] : 0,
+    rootCauseGuess: typeof child.metadata["root_cause_guess"] === "string" ? child.metadata["root_cause_guess"] : null,
+    exemptReason: typeof child.metadata["exempt_reason"] === "string" ? child.metadata["exempt_reason"] : null,
+    rejectReason: typeof child.metadata["reject_reason"] === "string" ? child.metadata["reject_reason"] : null,
+    rule: typeof child.metadata["rule"] === "string" ? child.metadata["rule"] : undefined,
+  }
+}
+
+/** WorkItem phase → 旧 tg.status（投影用；done 归 review 待收尾，cancelled 归 completed）。 */
+function workItemPhaseToTaskGroupStatus(phase: WorkItemPhase): Phase {
+  switch (phase) {
+    case "todo": return "task_analysis"
+    case "in_progress": return "dev_impl"
+    case "review":
+    case "done": return "review"
+    default: return "completed"
+  }
+}
+
+/**
+ * workItems（单轨事实源）→ TaskGroupState 只读投影。
+ * 供旧流工具（arch_submit 等）与旧视图读侧兼容：字段全部由 WorkItem.metadata/children 派生，
+ * 变更不写回（单轨下 workItems 为唯一事实源）。reviews/phases 等旧结构无对应新流数据时给空值。
+ */
+export function taskGroupFromWorkItem(item: WorkItem): TaskGroupState {
+  const m = item.metadata
+  const tasks = taskListOf(item)
+  return {
+    id: item.externalId ?? item.id.replace(/^task:/, ""),
+    name: typeof m["name"] === "string" ? m["name"] : item.title,
+    taskCount: typeof m["task_count"] === "number" ? m["task_count"] : tasks.length,
+    worktreePath: typeof m["worktree_path"] === "string" ? m["worktree_path"] : null,
+    branchName: typeof m["branch_name"] === "string" ? m["branch_name"] : null,
+    baseRef: typeof m["base_ref"] === "string" ? m["base_ref"] : null,
+    executionBoundary: (m["execution_boundary"] as ExecutionBoundary) ?? null,
+    relevantSpecs: Array.isArray(m["relevant_specs"]) ? (m["relevant_specs"] as string[]) : [],
+    status: workItemPhaseToTaskGroupStatus(item.phase),
+    phases: {
+      architect_review: { completed: false },
+      review: {
+        retryCount: 0,
+        lastResolvedRetryCount: 0,
+        tool: { completed: false },
+        task: { completed: false },
+        quality: { progress: createEmptyQualityProgress() },
+      },
+    },
+    tasks,
+    issues: issueChildrenOf(item).map(projectIssueFromChild),
+    blockers: Array.isArray(m["blockers"]) ? (m["blockers"] as BlockerItem[]) : [],
+    agentSummaries: typeof m["agent_summaries"] === "object" ? (m["agent_summaries"] as Record<string, string>) : undefined,
+  }
+}

package/src/core/exemptions.ts

@@ -0,0 +1,168 @@
+import path from "path"
+import { mkdirSync, writeFileSync, renameSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import type { WorkItem } from "./workflow/types.ts"
+import { resolveChildIssueFields } from "./workflow/reset.ts"
+import { getStateDir, resolveStateRoot, acquireLock, releaseLock } from "./state.ts"
+import type { Dimension, ReviewLayer } from "./types.ts"
+
+/**
+ * 项目级跨 change 豁免清单（跨 change 共享，写主仓库根的状态目录）。
+ *
+ * 痛点背景：worktree 模式下每个新 change 是全新状态账本 + 全新 Sonar 项目，tool review 全量扫描
+ * 会把存量已裁定豁免的安全问题重新报为阻塞 issue，dev 每轮重新豁免。此模块把「裁定认可（dismissed）」
+ * 的豁免结论落为 (rule+file+line) 清单，后续 change 的 tool review 提报命中清单时降为 Info 级，
+ * 不阻塞、无需重复豁免。
+ *
+ * 设计约束（AGENTS.md）：
+ * - 持久化归属工具/状态层，匹配语义归属 skill 层，展示归属视图层；
+ * - 并发安全：专用锁（exemptions.lock 目录锁）包住读-改-写，不能用 per-change 的 review 锁；
+ * - 原子写：临时文件 + rename 覆盖，防崩溃损坏共享清单；
+ * - key 构造只在此定义（DRY），rule 缺失时宁漏勿误（不匹配、不写清单）。
+ */
+
+export const EXEMPTIONS_FILE = "exemptions.json"
+export const EXEMPTIONS_LOCK = "exemptions.lock"
+export const EXEMPTIONS_SCHEMA_VERSION = 1
+/** 命中项目级豁免清单的标记键（写入 child.metadata，供视图统计与标注；不参与匹配）。 */
+export const EXEMPTED_HIT_KEY = "exempted_hit"
+
+export interface ExemptionRecord {
+  key: string
+  rule?: string
+  file?: string
+  line?: number
+  sourcePhase: ReviewLayer
+  dimension: Dimension
+  severity: string
+  description: string
+  exemptedAt: string
+  exemptedBy: string
+  changeId: string
+}
+
+export interface ExemptionStore {
+  version: number
+  items: ExemptionRecord[]
+}
+
+/** 豁免 key 单一事实源：rule+file+line 拼接。rule 缺失时返回 null（宁漏勿误：不匹配、不写清单）。 */
+export function exemptionKeyOf(rule: string | undefined, file: string, line: number): string | null {
+  if (rule === undefined || rule === "") return null
+  return [rule, file, line].join("\u0000")
+}
+
+function emptyStore(): ExemptionStore {
+  return { version: EXEMPTIONS_SCHEMA_VERSION, items: [] }
+}
+
+async function exemptionsDir(worktree: string): Promise<string> {
+  const root = await resolveStateRoot(worktree)
+  return getStateDir(root)
+}
+
+/** 读取跨 change 豁免清单。文件缺失/损坏返回空清单；写侧原子写保证读到完整文件，读不持锁。 */
+export async function readExemptions(worktree: string): Promise<ExemptionStore> {
+  const fp = path.join(await exemptionsDir(worktree), EXEMPTIONS_FILE)
+  try {
+    const parsed = JSON.parse(await readFile(fp, "utf-8")) as Partial<ExemptionStore>
+    if (parsed && Array.isArray(parsed.items)) {
+      return { version: parsed.version ?? EXEMPTIONS_SCHEMA_VERSION, items: parsed.items }
+    }
+    return emptyStore()
+  } catch {
+    return emptyStore()
+  }
+}
+
+/** 原子写豁免清单：临时文件 + rename 覆盖（不能裸 writeFile 整文件覆盖，防崩溃损坏共享清单）。 */
+export async function writeExemptions(worktree: string, store: ExemptionStore): Promise<void> {
+  const dir = await exemptionsDir(worktree)
+  mkdirSync(dir, { recursive: true })
+  const target = path.join(dir, EXEMPTIONS_FILE)
+  const tmp = path.join(dir, `${EXEMPTIONS_FILE}.tmp`)
+  writeFileSync(tmp, JSON.stringify(store, null, 2))
+  renameSync(tmp, target)
+}
+
+/** 幂等 upsert：同 key 命中即整体刷新（不重复累积）；专用锁包住读-改-写，多 change 并行写不丢更新。 */
+export async function upsertExemption(worktree: string, record: ExemptionRecord): Promise<void> {
+  const dir = await exemptionsDir(worktree)
+  mkdirSync(dir, { recursive: true })
+  const lockPath = path.join(dir, EXEMPTIONS_LOCK)
+  await acquireLock(lockPath)
+  try {
+    const store = await readExemptions(worktree)
+    const idx = store.items.findIndex((i) => i.key === record.key)
+    if (idx >= 0) {
+      store.items[idx] = record
+    } else {
+      store.items.push(record)
+    }
+    await writeExemptions(worktree, store)
+  } finally {
+    releaseLock(lockPath)
+  }
+}
+
+/** 由被裁定（dismissed）的 issue child 组装豁免记录；rule 缺失时返回 null（不参与匹配）。 */
+export function buildExemptionRecord(
+  child: WorkItem,
+  opts: { changeId: string; exemptedBy: string },
+): ExemptionRecord | null {
+  const rule = typeof child.metadata["rule"] === "string" ? child.metadata["rule"] : undefined
+  const f = resolveChildIssueFields(child)
+  const key = exemptionKeyOf(rule, f.file, f.line)
+  if (!key) return null
+  return {
+    key,
+    rule,
+    file: f.file,
+    line: f.line,
+    sourcePhase: f.sourcePhase,
+    dimension: f.dimension,
+    severity: child.severity ?? "",
+    description: child.description,
+    exemptedAt: new Date().toISOString(),
+    exemptedBy: opts.exemptedBy,
+    changeId: opts.changeId,
+  }
+}
+
+/** dismissed 裁定落库容错入口：清单写入失败仅告警，不阻断裁定主流程。 */
+export async function writeDismissedExemption(
+  worktree: string,
+  child: WorkItem,
+  opts: { changeId: string; exemptedBy: string },
+): Promise<void> {
+  const record = buildExemptionRecord(child, opts)
+  if (!record) return
+  try {
+    await upsertExemption(worktree, record)
+  } catch (err) {
+    console.warn(`[exemptions] 项目级豁免清单写入失败（不影响裁定主流程）：${(err as Error).message}`)
+  }
+}
+
+/**
+ * 命中降级：new_children 中 (rule+file+line) 命中清单的 issue 降为 Info 级并追加中性描述，
+ * 返回降级条数。必须在 assertFailedHasReason 之前调用——否则仅含存量豁免问题的 change 里
+ * reviewer 能 failed 却无真实待办，形成死锁。
+ */
+export function applyExemptionDowngrade(children: WorkItem[], store: ExemptionStore): number {
+  const keys = new Set(store.items.map((i) => i.key))
+  let downgraded = 0
+  for (const c of children) {
+    const rule = typeof c.metadata["rule"] === "string" ? c.metadata["rule"] : undefined
+    const file = typeof c.metadata["file"] === "string" ? c.metadata["file"] : ""
+    const line = typeof c.metadata["line"] === "number" ? c.metadata["line"] : 0
+    const key = exemptionKeyOf(rule, file, line)
+    if (key && keys.has(key)) {
+      c.severity = "Info"
+      c.metadata[EXEMPTED_HIT_KEY] = rule ?? true
+      c.description = `${c.description}\n\n> 命中项目级豁免清单${rule ? `（rule=${rule}）` : ""}，保持现状。`
+      downgraded++
+    }
+  }
+  return downgraded
+}