@ifrankwang/openspec-agents 0.118.0

package/src/core/workflow/submit.ts

@@ -0,0 +1,331 @@
+import type { WorkItem, WorkItemPhase, StepConfig, StepAdjudication } from "./types.ts"
+import { stepAgentIds, EXEMPT_REQUEST_KEY } from "./types.ts"
+import type { LoadedWorkflow } from "./loader.ts"
+import { applyAgentVerdict, adjudicateStep, stepCanPass, applyTransition, getStepVerdict, isTerminalPhase, isInfoSeverity } from "./engine.ts"
+import { issueChildrenOf, taskChildrenOf } from "../task-children.ts"
+import { readIssueSource } from "../constants.ts"
+
+/** 豁免申请标记键单一事实源在 types.ts（engine 与 submit 共用免循环引用）；本模块 re-export 兼容既有消费方。 */
+export { EXEMPT_REQUEST_KEY } from "./types.ts"
+
+export interface SubmitInput {
+  stepId: string
+  agentKey: string
+  verdict: "passed" | "failed"
+  fixedIds?: string[]
+  exemptIds?: string[]
+  newChildren?: WorkItem[]
+}
+
+export interface SubmitResult {
+  stepId: string
+  agentKey: string
+  verdict: "passed" | "failed"
+  stepAdjudication: StepAdjudication
+  advanced: boolean
+  transitionTarget?: string
+  childrenUpdated: string[]
+  /** 推进失败（applyTransition 拦截）的原因；推进成功时不返回。 */
+  reason?: string
+}
+
+export interface AdjudicationResult {
+  issueId: string
+  action: "dismissed" | "rejected"
+  childPhase: WorkItemPhase
+}
+
+/** 报源 agent 属于哪个 review step 的 agents 就由谁裁定（固定逻辑，非可配置），未命中返回 null */
+function resolveReviewStepForSource(workflow: LoadedWorkflow, source: string): StepConfig | null {
+  for (const phase of workflow.phases) {
+    if (phase.name !== "review") continue
+    for (const step of phase.steps) {
+      if (stepAgentIds(step).includes(source)) return step
+    }
+  }
+  return null
+}
+
+/**
+ * 校验 issue 裁定者权限（谁提谁裁定）：裁定者恒为报 issue 的 agent（child.metadata.source），
+ * 供豁免裁定（adjudicateExempt）与复核（adjudicateRecheck）复用：
+ * - 报源缺失或不属于任何 review step 的 agents（非合法 review agent）→ 抛错（畸形数据拒绝，零副作用）；
+ * - 裁定者 ≠ 报源 → 抛错（tool/task/quality 一律按报源收敛，无 step 白名单）；
+ * 校验在一切状态写入之前执行，越权抛错不产生状态变更。返回报源对应 review step 供调用方使用。
+ */
+function resolveAdjudicatorStepForIssue(
+  workflow: LoadedWorkflow,
+  child: WorkItem,
+  agentKey: string,
+  role: "裁定" | "复核",
+): StepConfig {
+  const prefix = role === "裁定" ? "豁免裁定失败" : "复核失败"
+  const source = readIssueSource(child)
+  const step = source ? resolveReviewStepForSource(workflow, source) : null
+  if (!step) {
+    throw new Error(
+      `${prefix}：issue "${child.id}" 的报源 "${source ?? "缺失"}" 不是合法 review agent（不属于任何 review step 的 agents），无法确定裁定者。`
+    )
+  }
+  if (agentKey !== source) {
+    throw new Error(
+      `${prefix}：issue "${child.id}" 由报源 "${source}" 裁定（谁提谁裁定），${role}者必须为 "${source}"，拒绝 "${agentKey}" ${role}。`
+    )
+  }
+  return step
+}
+
+/**
+ * 提交路由与归属校验（submitForStep 与 agentSubmitExecute 共用）：
+ * step 声明存在、agent 属于 step.agents、提交 step 与当前 step 一致、step 归属 phase 与 item.phase 一致，
+ * 任一不满足即抛错且零状态变更。
+ */
+export function assertSubmitRouting(workflow: LoadedWorkflow, item: WorkItem, stepId: string, agentKey: string): StepConfig {
+  const entry = workflow.stepMap.get(stepId)
+  if (!entry) {
+    throw new Error(`submit 路由失败：step "${stepId}" 未在 workflow "${workflow.id}" 中声明。`)
+  }
+  const step = entry.step
+  if (!stepAgentIds(step).includes(agentKey)) {
+    throw new Error(`submit 越权：agent "${agentKey}" 不属于 step "${stepId}" 的 agents，拒绝提交且不产生任何状态变更。`)
+  }
+  if (item.currentStep !== null && item.currentStep !== stepId) {
+    throw new Error(`submit 校验失败：item "${item.id}" 当前 step 为 "${item.currentStep}"，与提交的 step "${stepId}" 不一致，拒绝提交且不产生任何状态变更。`)
+  }
+  // phase↔step 归属校验：currentStep 为 null（todo 初始态 / 终态）显式跳过，错位态拒绝提交零状态变更。
+  if (item.currentStep !== null && entry.phase.name !== item.phase) {
+    throw new Error(`submit 校验失败：item "${item.id}" 的 phase "${item.phase}" 与 step "${stepId}" 归属阶段 "${entry.phase.name}" 不一致（phase ↔ step 错位），拒绝提交且不产生任何状态变更。`)
+  }
+  return step
+}
+
+/**
+ * 链式推进：submitForStep 的 applyTransition(pass) 成功后，若新 step 已全 passed 且
+ * stepCanPass 满足，继续沿 on_pass 穿越（等价 main 的 task 自动跳过语义），
+ * 一次提交可带过多个已通过的 step。循环在每一步重算 adjudicateStep 与 stepCanPass，
+ * 停在需要 agent 动作的 step（pending/failed 裁决）或终态（done/halt）。
+ * 返回最终落点 target（"done"/"halt"/step id），无推进则返回 initialTarget。
+ * 有限性：每轮推进都改变 currentStep（终态置 null）且 on_pass 构成无环 DAG，
+ * 另加 stepMap 规模上限防护，不可能无限循环。
+ */
+export function chainPassAdvance(item: WorkItem, workflow: LoadedWorkflow, initialTarget: string | undefined): string | undefined {
+  let target = initialTarget
+  const maxIterations = workflow.stepMap.size * 2 + 1
+  for (let i = 0; i < maxIterations; i++) {
+    if (item.suspended || isTerminalPhase(item.phase) || item.currentStep === null) break
+    const entry = workflow.stepMap.get(item.currentStep)
+    if (!entry) break
+    const step = entry.step
+    if (step.always_run) break
+    if (adjudicateStep(item, step) !== "passed") break
+    if (!stepCanPass(item, step)) break
+    const r = applyTransition(item, workflow, "pass")
+    if (!r.advanced) break
+    if (r.target !== undefined) target = r.target
+  }
+  return target
+}
+
+/**
+ * 通用提交入口：写 tag → children 更新 → 裁决与推进。
+ * 路由/归属校验在一切状态变更之前完成，越权提交不产生任何副作用。
+ */
+export function submitForStep(item: WorkItem, workflow: LoadedWorkflow, input: SubmitInput): SubmitResult {
+  const step = assertSubmitRouting(workflow, item, input.stepId, input.agentKey)
+
+  const childById = new Map<string, WorkItem>()
+  // issue children 优先入 map：fixed/exempt 解析须优先命中 issue child。
+  // task child 短数字 id（"1"）可能与 issue 的 externalId 撞车，且数组序不保证 issue 在前（reopen/recovery 重排）。
+  for (const c of issueChildrenOf(item)) {
+    childById.set(c.id, c)
+    // 兼容外部以原始 issue id 引用 child（child.id 可能带 issue: 前缀，externalId 为原始 id）
+    if (c.externalId) childById.set(c.externalId, c)
+  }
+  // task children 后入且撞车跳过：仅登记未被 issue child 占用的键，保证 issue 优先语义不被打乱
+  for (const c of taskChildrenOf(item)) {
+    if (!childById.has(c.id)) childById.set(c.id, c)
+    if (c.externalId && !childById.has(c.externalId)) childById.set(c.externalId, c)
+  }
+
+  // 终态 issue 豁免守卫：done/cancelled 已终态的 issue 不允许重新申请豁免（防止已 cancelled 的 issue
+  // 被重复申请豁免、rejected 复活已豁免 issue）。校验在一切状态写入（applyAgentVerdict）之前，抛错零副作用。
+  // Info 级 issue 豁免守卫（纵深防御，与 agentSubmitExecute 入口校验同语义）：Info 级不阻塞任何流程，
+  // 豁免无意义。本分支仅处理「新申请」（写入 exempt_request 标记），不触及存量带 exempt_request 标记的
+  // Info issue 裁定路径（adjudicateExempt 不受影响）。
+  for (const id of input.exemptIds ?? []) {
+    const child = childById.get(id)
+    if (child && isTerminalPhase(child.phase)) {
+      throw new Error(
+        `豁免申请失败：issue "${child.id}" 当前 phase 为 "${child.phase}"（终态），不允许对已终态的 issue 重新申请豁免。`
+      )
+    }
+    if (child && isInfoSeverity(child.severity)) {
+      throw new Error(`豁免申请失败：issue "${child.id}" 为 Info 级 issue，不阻塞提交，无需申请豁免。`)
+    }
+  }
+
+  applyAgentVerdict(item, input.stepId, input.agentKey, input.verdict)
+
+  const updated = new Set<string>()
+
+  for (const id of input.fixedIds ?? []) {
+    const child = childById.get(id)
+    if (child) {
+      // issue child 修复后进入 review（待对应 reviewer 复核），终态由复核裁定；
+      // task child 维持 done 语义（子任务完成态由 verify_task 验证路径处理，不进入复核）。
+      child.phase = child.type === "task" ? "done" : "review"
+      // 记录 canonical child.id（task child 短数字 id 可能与 issue externalId 撞车，
+      // 原始引用 id 渲染时歧义，统一用 child.id 回指）
+      updated.add(child.id)
+    }
+  }
+
+  for (const id of input.exemptIds ?? []) {
+    const child = childById.get(id)
+    if (child) {
+      child.metadata[EXEMPT_REQUEST_KEY] = { requestedBy: input.agentKey }
+      // 豁免申请进入 review（待裁定），与 fixed 的 fixed→review 对称：exempt 子项不再以 todo 态
+      // 滞留（todo 态被 implement 门禁计为阻塞，dev 无法推进、reviewer 又因 currentStep 停在
+      // implement 无法补交，形成死锁）。进入 review 后 implement 门禁 carve-out（review 态
+      // blocking 不阻塞）与 forwardGatePassed 天然放行，由报源 reviewer 在 review 轮次或补交中
+      // 裁定（dismissed→cancelled / rejected→todo 回退收敛）。task child 无豁免语义，保持原行为。
+      if (child.type === "issue") child.phase = "review"
+      updated.add(child.id)
+    }
+  }
+
+  for (const nc of input.newChildren ?? []) {
+    if (!childById.has(nc.id)) {
+      item.children.push(nc)
+      childById.set(nc.id, nc)
+      updated.add(nc.id)
+    }
+  }
+
+  const adjudication = adjudicateStep(item, step)
+  // 多 agent step（verify_quality 5 维并行）聚合判定：须全部 agent 非 pending 才允许触发迁移。
+  // passed 天然意味着全提交；failed 须等最后一维提交后才回退，避免单维失败过早回退阻断其余维度提交。
+  const allAdjudicated = step.agents.every((a) => getStepVerdict(item, step.id, a.id) !== "pending")
+  let advanced = false
+  let transitionTarget: string | undefined
+  let advanceBlockReason: string | undefined
+  if (adjudication === "passed" && stepCanPass(item, step)) {
+    const r = applyTransition(item, workflow, "pass")
+    advanced = r.advanced
+    if (r.advanced) {
+      // 成功推进后清理历史阻塞原因，避免状态视图展示过期信息
+      delete item.metadata["_advance_block_reason"]
+      // 链式推进：迁移后若新 step 已全 passed 且 stepCanPass 满足，继续沿 on_pass 穿越
+      // （等价 main 的 task 自动跳过语义），一次提交可带过多个已通过的 step，
+      // 停在需要 agent 动作的 step 或终态（done/halt）。
+      transitionTarget = chainPassAdvance(item, workflow, r.target)
+    } else {
+      // 推进被跨 phase 门禁/done 终态检查拦截：把原因写入 item 状态供 opx_status 展示，并随结果返回
+      advanceBlockReason = r.reason
+      item.metadata["_advance_block_reason"] = r.reason
+    }
+  } else if (adjudication === "failed" && allAdjudicated) {
+    const r = applyTransition(item, workflow, "fail")
+    advanced = r.advanced
+    if (r.advanced) {
+      delete item.metadata["_advance_block_reason"]
+      if (r.target !== undefined) transitionTarget = r.target
+    } else {
+      advanceBlockReason = r.reason
+      item.metadata["_advance_block_reason"] = r.reason
+    }
+  }
+
+  return {
+    stepId: input.stepId,
+    agentKey: input.agentKey,
+    verdict: input.verdict,
+    stepAdjudication: adjudication,
+    advanced,
+    transitionTarget,
+    childrenUpdated: [...updated],
+    reason: advanceBlockReason,
+  }
+}
+
+/**
+ * 裁定豁免申请：dismissed → cancelled；rejected → todo；两种结果均清除 exempt_request 标记。
+ * 仅带 exempt_request 标记（已申请豁免）的 issue 可被裁定；裁定者必须属于对应 review step 的 agents。
+ */
+export function adjudicateExempt(
+  item: WorkItem,
+  workflow: LoadedWorkflow,
+  input: { issueId: string; agentKey: string; action: "dismissed" | "rejected" },
+): AdjudicationResult {
+  const child =
+    issueChildrenOf(item).find((c) => c.id === input.issueId) ??
+    taskChildrenOf(item).find((c) => c.id === input.issueId)
+  if (!child) {
+    throw new Error(`豁免裁定失败：issue "${input.issueId}" 不存在于 item "${item.id}" 的 children 中。`)
+  }
+  if (child.metadata[EXEMPT_REQUEST_KEY] === undefined) {
+    throw new Error(
+      `豁免裁定失败：issue "${input.issueId}" 未申请豁免（无 exempt_request 标记），仅可裁定带豁免申请标记的 issue。`
+    )
+  }
+  // 谁提谁裁定：解析报源 review step 并校验裁定者权限（与复核同源，复用公共裁定权校验）。
+  resolveAdjudicatorStepForIssue(workflow, child, input.agentKey, "裁定")
+
+  if (input.action === "dismissed") {
+    child.phase = "cancelled"
+  } else {
+    child.phase = "todo"
+  }
+  delete child.metadata[EXEMPT_REQUEST_KEY]
+  return { issueId: input.issueId, action: input.action, childPhase: child.phase }
+}
+
+export interface RecheckAdjudicationResult {
+  issueId: string
+  verdict: "passed" | "rejected"
+  childPhase: WorkItemPhase
+}
+
+/**
+ * 复核已修复（review 态）issue：verdict=passed → done；verdict=rejected → 回 todo 并
+ * 递增 metadata.refix_count、写入 metadata.reject_reason（给 dev 驳回原因）。
+ * 仅 review 态 issue 可复核；裁定者必须为报 issue 的对应 review step（谁提谁裁定，与豁免裁定同源归因）。
+ * 越权/非法状态抛错，不产生任何状态变更。
+ */
+export function adjudicateRecheck(
+  item: WorkItem,
+  workflow: LoadedWorkflow,
+  input: { issueId: string; agentKey: string; verdict: "passed" | "rejected"; rejectReason?: string },
+): RecheckAdjudicationResult {
+  const child = issueChildrenOf(item).find((c) => c.id === input.issueId)
+  if (!child) {
+    throw new Error(`复核失败：issue "${input.issueId}" 不存在于 item "${item.id}" 的 issue children 中。`)
+  }
+  if (child.phase !== "review") {
+    throw new Error(
+      `复核失败：issue "${input.issueId}" 当前 phase 为 "${child.phase}"，仅 review 态（已修复待复核）issue 可复核。`
+    )
+  }
+  // 带 exempt_request 标记的 issue 处于豁免待裁定态，须由报源 reviewer 经 exempt_adjudications 裁定，
+  // recheck 复核会绕过豁免裁定语义（passed 直接置 done 且残留标记）；校验在一切状态写入之前，抛错零变更。
+  if (child.metadata[EXEMPT_REQUEST_KEY] !== undefined) {
+    throw new Error(
+      `复核失败：issue "${input.issueId}" 已申请豁免（exempt_request 标记），待裁定豁免申请应经 exempt_adjudications 裁定，不接受 recheck_adjudications 复核。`
+    )
+  }
+  // 谁提谁裁定：解析报源 review step 并校验复核者权限（与豁免裁定同源，复用公共裁定权校验）。
+  resolveAdjudicatorStepForIssue(workflow, child, input.agentKey, "复核")
+
+  if (input.verdict === "passed") {
+    child.phase = "done"
+    delete child.metadata["reject_reason"]
+  } else {
+    if (!input.rejectReason) {
+      throw new Error(`复核失败：issue "${input.issueId}" 驳回（verdict=rejected）必须提供 reject_reason。`)
+    }
+    child.phase = "todo"
+    child.metadata["refix_count"] = (typeof child.metadata["refix_count"] === "number" ? child.metadata["refix_count"] : 0) + 1
+    child.metadata["reject_reason"] = input.rejectReason
+  }
+  return { issueId: input.issueId, verdict: input.verdict, childPhase: child.phase }
+}

package/src/core/workflow/types.ts

@@ -0,0 +1,100 @@
+import { SEVERITY_LEVELS, BLOCKING_SEVERITIES } from "../constants.ts"
+export { SEVERITY_LEVELS, BLOCKING_SEVERITIES }
+
+export const WORK_ITEM_PHASES = ["todo", "in_progress", "review", "done", "cancelled"] as const
+export type WorkItemPhase = typeof WORK_ITEM_PHASES[number]
+
+export const WORK_ITEM_TYPES = ["task", "issue"] as const
+export type WorkItemType = typeof WORK_ITEM_TYPES[number]
+
+export const VERDICTS = ["pending", "passed", "failed"] as const
+export type Verdict = typeof VERDICTS[number]
+
+export type Severity = typeof SEVERITY_LEVELS[number]
+
+export interface WorkItemWriteback {
+  lastAttempt?: string
+  lastSuccess?: string
+  error?: string
+}
+
+export interface WorkItem {
+  id: string
+  source: string
+  externalId?: string
+  type: WorkItemType
+  title: string
+  description: string
+  phase: WorkItemPhase
+  suspended: boolean
+  currentStep: string | null
+  tags: Record<string, Verdict>
+  metadata: Record<string, unknown>
+  children: WorkItem[]
+  labels: string[]
+  severity?: Severity
+  writeback?: WorkItemWriteback
+}
+
+export const INTERNAL_METADATA_PREFIX = "_"
+
+/** 豁免申请标记键（非内部下划线前缀，属于业务语义字段）。定义在本模块使 engine 与 submit 均可
+ *  免循环引用（submit 依赖 engine，engine 依赖本模块，不产生新环）。 */
+export const EXEMPT_REQUEST_KEY = "exempt_request"
+
+export function isInternalMetadataKey(key: string): boolean {
+  return key.startsWith(INTERNAL_METADATA_PREFIX)
+}
+
+export function tagKey(stepId: string, agentKey: string): string {
+  return `${stepId}:${agentKey}`
+}
+
+export interface StepTransitions {
+  on_pass: string | "done" | "halt"
+  on_fail: string | "done" | "halt"
+}
+
+export interface StepAgent {
+  id: string
+  capability_tags: string[]
+}
+
+export interface StepConfig {
+  id: string
+  agents: StepAgent[]
+  always_run?: boolean
+  max_retries?: number
+  instructions?: string[]
+  constraints?: string[]
+  transitions: StepTransitions
+}
+
+/** step.agents 的 id 投影：状态机/视图消费点统一从对象数组归一化为 id 字符串数组。 */
+export function stepAgentIds(step: { agents: StepAgent[] }): string[] {
+  return step.agents.map((a) => a.id)
+}
+
+export interface PhaseConfig {
+  name: WorkItemPhase
+  steps: StepConfig[]
+}
+
+/** 跨所有 step 共享的通用指引/约束（step 自动继承，渲染时合并进对应视图区块），缺省 undefined。 */
+export interface WorkflowCommon {
+  /** 通用操作指引（所有 step 的操作指引均前置追加）。 */
+  instructions?: string[]
+  /** 通用约束（所有 step 的约束区块均前置追加）。 */
+  constraints?: string[]
+}
+
+export interface WorkflowConfig {
+  id: string
+  name?: string
+  max_retries: number
+  phases: PhaseConfig[]
+  /** 跨 step 共享的通用语义（step 自动继承），缺省 undefined。 */
+  common?: WorkflowCommon
+}
+
+export type StepAdjudication = "passed" | "failed" | "pending"

package/src/core/workflow/writeback.ts

@@ -0,0 +1,48 @@
+import type { WorkItem } from "./types.ts"
+
+export type WritebackHandler = (item: WorkItem, action: string, payload: unknown) => Promise<void> | void
+
+interface WritebackTask {
+  item: WorkItem
+  action: string
+  payload: unknown
+}
+
+let handler: WritebackHandler = async () => {}
+let queue: WritebackTask[] = []
+
+/** 注册写回处理器（模拟外部源，默认直接成功） */
+export function setWritebackHandler(next: WritebackHandler): void {
+  handler = next
+}
+
+/** 非阻塞入队：仅推进队列并记录 lastAttempt，不等待外部 I/O */
+export function enqueueWriteback(item: WorkItem, action: string, payload: unknown): void {
+  queue.push({ item, action, payload })
+  item.writeback = { ...item.writeback, lastAttempt: new Date().toISOString() }
+}
+
+/** 排空队列执行写回：成功记录 lastSuccess，失败记录 error（保留 lastAttempt） */
+export async function flushWritebacks(): Promise<{ succeeded: string[]; failed: string[] }> {
+  const succeeded: string[] = []
+  const failed: string[] = []
+  const pending = queue
+  queue = []
+  for (const task of pending) {
+    try {
+      await handler(task.item, task.action, task.payload)
+      const { error: _staleError, ...writeback } = task.item.writeback ?? {}
+      task.item.writeback = { ...writeback, lastSuccess: new Date().toISOString() }
+      succeeded.push(task.item.id)
+    } catch (err) {
+      task.item.writeback = { ...task.item.writeback, error: (err as Error).message }
+      failed.push(task.item.id)
+    }
+  }
+  return { succeeded, failed }
+}
+
+/** 上次写回失败则返回 true，提示下次状态变更应重试（重试动作由后续 flush 承担） */
+export function retryPendingWritebacks(item: WorkItem): boolean {
+  return item.writeback?.error !== undefined
+}

package/src/dashboard/page.ts

@@ -0,0 +1,19 @@
+import { fileURLToPath } from "node:url"
+import { readFileSync, existsSync } from "node:fs"
+import { join } from "node:path"
+
+let _html: string | null = null
+
+/** 页面资源定位：bundle 形态（ZCode 插件包）资源随 bundle 同目录放置；源码/包形态位于 ../../assets/dashboard/。 */
+function resolveDashboardHtml(): string {
+  const __dirname = fileURLToPath(new URL(".", import.meta.url))
+  const bundled = join(__dirname, "dashboard", "index.html")
+  if (existsSync(bundled)) return bundled
+  return join(__dirname, "../../assets/dashboard/index.html")
+}
+
+export function getDashboardPage(): string {
+  if (_html) return _html
+  _html = readFileSync(resolveDashboardHtml(), "utf-8")
+  return _html
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+// 旧入口保留向后兼容
+export { OpenspecOrchestratePlugin } from "./adapters/opencode/index.ts"

package/src/skills/resolve.ts

@@ -0,0 +1,95 @@
+import { readdirSync, readFileSync, existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { SKILL_SCAN_ROOTS } from "./scan.ts"
+
+export interface SkillTagIndex {
+  tagMap: Map<string, string[]>
+  skillTags: Map<string, string[]>
+  /** skill 名 → frontmatter 声明的机器可读必做清单（must_do），未声明则无键。 */
+  skillMustDo: Map<string, string[]>
+}
+
+let cacheKey: string | null = null
+let cacheIndex: SkillTagIndex | null = null
+
+/**
+ * 扫描 skill 目录的 capabilities frontmatter，建立 tag → skill 名 与 skill 名 → tags 双向索引。
+ * 进程内缓存：roots 不变时返回同一实例，roots 变化时重建。
+ */
+export function scanSkillTags(roots: string[] = SKILL_SCAN_ROOTS): SkillTagIndex {
+  const key = roots.join("\u0000")
+  if (cacheKey === key && cacheIndex) return cacheIndex
+  const tagMap = new Map<string, string[]>()
+  const skillTags = new Map<string, string[]>()
+  const skillMustDo = new Map<string, string[]>()
+  const seen = new Set<string>()
+  for (const root of roots) {
+    if (!existsSync(root)) continue
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      if (seen.has(entry.name)) continue
+      const mdPath = resolve(root, entry.name, "SKILL.md")
+      if (!existsSync(mdPath)) continue
+      try {
+        const raw = readFileSync(mdPath, "utf-8")
+        const m = raw.match(/capabilities:\s*\[([^\]]*)\]/)
+        if (!m) continue
+        const tags = m[1].split(",").map((s: string) => s.trim().replace(/["']/g, "")).filter(Boolean)
+        skillTags.set(entry.name, tags)
+        for (const tag of tags) {
+          const arr = tagMap.get(tag) || []
+          arr.push(entry.name)
+          tagMap.set(tag, arr)
+        }
+        // 可选约定：must_do 必做清单（机器可读）。单行数组形态，与 capabilities 解析同机制；
+        // 未声明的 skill 不参与必做清单覆盖度门禁（优雅降级，缺失不报错）。
+        const mdo = raw.match(/must_do:\s*\[([^\]]*)\]/)
+        if (mdo) {
+          const items = mdo[1].split(",").map((s: string) => s.trim().replace(/["']/g, "")).filter(Boolean)
+          if (items.length > 0) skillMustDo.set(entry.name, items)
+        }
+        seen.add(entry.name)
+      } catch { /* skip unreadable */ }
+    }
+  }
+  cacheKey = key
+  cacheIndex = { tagMap, skillTags, skillMustDo }
+  return cacheIndex
+}
+
+/**
+ * 按 capability tag 语义匹配 skill：skill 含 tech-stack- 前缀 tag 归 techStackOnly，否则归 generic。
+ * caps 为空/undefined 返回空。
+ */
+export function resolveSkillsForCapabilities(
+  caps: string[] | undefined,
+  index?: SkillTagIndex,
+): { skillNames: string[]; techStackOnly: string[]; generic: string[] } {
+  if (!caps || caps.length === 0) return { skillNames: [], techStackOnly: [], generic: [] }
+  const idx = index ?? scanSkillTags()
+  const { tagMap, skillTags } = idx
+  const matched = new Set<string>()
+  for (const cap of caps) {
+    for (const n of tagMap.get(cap) || []) matched.add(n)
+  }
+  const skillNames: string[] = []
+  const generic: string[] = []
+  const techStackOnly: string[] = []
+  for (const name of matched) {
+    skillNames.push(name)
+    const tags = skillTags.get(name) || []
+    if (tags.some((t) => t.startsWith("tech-stack-"))) techStackOnly.push(name)
+    else generic.push(name)
+  }
+  return { skillNames, techStackOnly, generic }
+}
+
+/** efficiency tag 命中的效率类 skill 名 */
+export function getEfficiencySkills(index: SkillTagIndex = scanSkillTags()): string[] {
+  return index.tagMap.get("efficiency") || []
+}
+
+/** 取 skill 声明的机器可读必做清单（must_do）；未声明返回 null（该 skill 不参与覆盖度门禁）。 */
+export function getSkillMustDo(name: string, index: SkillTagIndex = scanSkillTags()): string[] | null {
+  return index.skillMustDo.get(name) ?? null
+}

package/src/skills/scan.ts

@@ -0,0 +1,29 @@
+import { existsSync } from "node:fs"
+import { resolve, dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { homedir } from "node:os"
+
+const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..")
+
+export const SKILL_SCAN_ROOTS: string[] = [
+  resolve(projectRoot, "assets", "skills"),
+  resolve(projectRoot, ".agents", "skills"),
+  resolve(projectRoot, ".opencode", "skills"),
+  join(homedir(), ".agents", "skills"),
+  join(homedir(), ".config", "opencode", "skills"),
+]
+
+// 仅随插件分发注入 opencode 的 skill 根目录。.agents/skills 靠 opencode 标准发现对本仓库自用生效，非插件注入职责。
+export const DISTRIBUTED_SKILL_ROOTS: string[] = [
+  resolve(projectRoot, "assets", "skills"),
+]
+
+export function findSkillPath(name: string): string | null {
+  for (const root of SKILL_SCAN_ROOTS) {
+    const p = resolve(root, name, "SKILL.md")
+    if (existsSync(p)) return p
+  }
+  return null
+}
+
+