@ifrankwang/openspec-agents 0.118.0

package/src/core/tools/types.ts

@@ -0,0 +1,129 @@
+import type { BuildPhaseTarget, ReviewLayer, ReviewVerifyStep } from "../types.ts"
+
+export interface ToolContext {
+  worktree: string
+  agent: string
+  /** 编排视角角色判定：true 表示调用者承担编排者职责（各 agent 主代理），替代 agent 名硬编码 openspec-orchestrator。 */
+  orchestrator?: boolean
+  /** 调用者 agent 身份是否显式声明：MCP 形态下为是否携带 `_agent` 参数，OpenCode 直载形态恒为 true。
+   *   false 且落入编排视角时，opx_status 视图渲染补传 `_agent` 的身份提示（MCP 子代理首查死锁兜底）。 */
+  identityDeclared?: boolean
+  remote?: boolean
+}
+
+export interface ToolResult {
+  content: string
+  isError?: boolean
+}
+
+export interface InitParams {
+  change_id: string
+  task_group_id: string
+  base_branch?: string
+  recovery?: {
+    phase: BuildPhaseTarget
+    review_layer?: ReviewLayer
+    reopenIssues?: boolean
+    /** 重置指定 verify step 的审查 tags 为 pending（仅 phase=review 时有效，与 review_layer 互斥），
+     *  恢复后 currentStep 落在第一个未全部通过的 verify step，可能早于被重置的 step。 */
+    reset_steps?: ReviewVerifyStep[]
+  }
+}
+
+export interface SetWorktreeParams {
+  change_id: string
+  worktree_path?: string
+  branch_name?: string
+}
+
+export interface UnattendedParams {
+  change_id: string
+  enabled: boolean
+}
+
+export interface StatusParams {
+  change_id: string
+}
+
+export interface AgentSubmitParams {
+  change_id: string
+  step_id: string
+  verdict: "passed" | "failed"
+  fixed_issue_ids?: string[]
+  exempt_issue_ids?: string[]
+  exempt_adjudications?: Array<{
+    issue_id: string
+    action: "dismissed" | "rejected"
+  }>
+  recheck_adjudications?: Array<{
+    issue_id: string
+    verdict: "passed" | "rejected"
+    reject_reason?: string
+  }>
+  checkpoint_decision?: "continue" | "giveup"
+  /** giveup 决策配套：对当前 step 质量门必做清单（must_do）未覆盖项逐项提供的结构化降级理由
+   * （giveup 未覆盖项缺理由则拒绝 giveup）。adjudication 取值 user_response / unattended_auto / env_unavailable。 */
+  checkpoint_skip_reasons?: Array<{
+    item: string
+    category: string
+    adjudication: string
+    note?: string
+  }>
+  new_children?: Array<{
+    id: string
+    title: string
+    description: string
+    severity?: string
+    dimension?: string
+    file?: string
+    line?: number
+    suggestion?: string
+    rule?: string
+    root_cause_guess?: string
+  }>
+  execution_boundary?: {
+    allowed_directories: string[]
+    allowed_packages: string[]
+    notes: string
+  }
+  blockers?: Array<{
+    source_role: string
+    task_id?: string
+    category: string
+    description: string
+    evidence: string
+    attempted_actions: string
+    options?: string[]
+  }>
+  blocker_updates?: Array<{
+    blocker_id: string
+    user_response: string
+  }>
+  blocker?: {
+    source_role: string
+    task_id?: string
+    category: string
+    description: string
+    evidence: string
+    attempted_actions: string
+    options?: string[]
+  }
+  self_check_results?: string
+  completed_task_ids?: string[]
+  test_results?: string
+  validation_steps?: Array<{
+    step: string
+    completed: boolean
+    evidence?: string
+    skip_reason?: string
+  }>
+  boundary_expansion?: {
+    allowed_directories?: string[]
+    allowed_packages?: string[]
+  }
+  verified_tasks?: string[]
+  failed_tasks?: Array<{
+    task_id: string
+    reason: string
+  }>
+}

package/src/core/types.ts

@@ -0,0 +1,135 @@
+import type { WorkItem } from "./workflow/types.ts"
+
+export const CODE_DIMENSIONS = ["style", "architecture", "performance", "security", "maintainability"] as const
+export const REVIEW_DIMENSIONS = [...CODE_DIMENSIONS] as const
+export type ReviewDimension = typeof REVIEW_DIMENSIONS[number]
+export type Dimension = ReviewDimension
+
+export const TASK_STATUSES = ["open", "submitted", "rejected", "verified"] as const
+export type TaskStatus = typeof TASK_STATUSES[number]
+export const ISSUE_STATUSES = ["open", "submitted", "rejected", "verified", "exemption_requested", "exempted"] as const
+export type IssueStatus = typeof ISSUE_STATUSES[number]
+
+export type Phase = "task_analysis" | "dev_impl" | "review" | "completed"
+
+/** 恢复（recovery）可恢复的阶段合法值，与 InitParams.recovery.phase 值域一致。 */
+export const BUILD_PHASE_TARGETS = ["task_analysis", "dev_impl", "review"] as const
+export type BuildPhaseTarget = typeof BUILD_PHASE_TARGETS[number]
+
+/** review 内子层合法值（review_layer / issue 报源层共用同一三元组）。 */
+export const REVIEW_LAYERS = ["tool", "task", "quality"] as const
+export type ReviewLayer = typeof REVIEW_LAYERS[number]
+
+/** review 三个验证 step 合法值（recovery.reset_steps 值域）。 */
+export const REVIEW_VERIFY_STEPS = ["verify_tool", "verify_task", "verify_quality"] as const
+export type ReviewVerifyStep = typeof REVIEW_VERIFY_STEPS[number]
+export type OrchestrateStatus = "not_started" | "in_progress" | "completed"
+export type DimensionVerdict = "pending" | "passed" | "failed"
+export type QualityLayerProgress = Record<ReviewDimension, DimensionVerdict>
+
+export interface ExecutionBoundary {
+  allowed_directories: string[]
+  allowed_packages: string[]
+  notes: string
+}
+
+export interface TaskItem {
+  id: string
+  specTrace: string
+  title: string
+  status: TaskStatus
+  taskNumber: string
+  rejectReason: string | null
+}
+
+export interface IssueItem {
+  id: string
+  dimension: Dimension
+  sourcePhase: ReviewLayer
+  severity: string
+  file: string
+  line: number
+  description: string
+  suggestion: string
+  status: IssueStatus
+  refixCount: number
+  rootCauseGuess: string | null
+  exemptReason: string | null
+  rejectReason: string | null
+  rule?: string   // 工具规则名（如 PMD Rule / SonarQube rule），非工具来源可为空
+}
+
+export type BlockerStatus = "awaiting_user" | "resolved"
+
+export interface BlockerItem {
+  id: string
+  sourceRole: string
+  taskId: string | null
+  category: string
+  description: string
+  evidence: string
+  attemptedActions: string
+  options: string[]
+  status: BlockerStatus
+  userResponse: string | null
+  architectConclusion: string | null
+}
+
+export interface ValidationStep {
+  step: string
+  completed: boolean
+  evidence: string
+  skip_reason: string | null
+}
+
+export interface ReviewLayerData {
+  completed: boolean
+  testResults?: string
+  validationSteps?: ValidationStep[]
+}
+
+export interface ReviewPhaseData {
+  retryCount: number
+  lastResolvedRetryCount: number
+  tool: ReviewLayerData
+  task: ReviewLayerData
+  quality: { progress: QualityLayerProgress }
+}
+
+export interface SimplePhaseData {
+  completed: boolean
+}
+
+export interface Phases {
+  architect_review: SimplePhaseData
+  review: ReviewPhaseData
+}
+
+export interface TaskGroupState {
+  id: string
+  name: string
+  taskCount: number
+  worktreePath: string | null
+  branchName: string | null
+  baseRef: string | null
+  executionBoundary: ExecutionBoundary | null
+  relevantSpecs: string[]
+  devSelfCheckResults?: string
+  status: Phase
+  phases: Phases
+  tasks: TaskItem[]
+  issues: IssueItem[]
+  blockers: BlockerItem[]
+  agentSummaries?: Record<string, string>   // agent 名 → 最近一次提交摘要（单值覆盖）
+}
+
+export interface OrchestrateState {
+  changeId: string
+  isolationNamespace: string
+  taskGroupId: string
+  baseBranch: string
+  workItems: WorkItem[]   // 工作流引擎原生持久化（单轨事实源）
+  createdAt: string
+  updatedAt: string
+  unattended?: boolean
+}

package/src/core/views.ts

@@ -0,0 +1,195 @@
+import type { TaskGroupState, OrchestrateState, TaskItem } from "./types.ts"
+import { derivePortFromNamespace } from "./namespace.ts"
+import { readFileSync } from "node:fs"
+import { findSkillPath } from "../skills/scan.ts"
+import { scanSkillTags, resolveSkillsForCapabilities, getEfficiencySkills } from "../skills/resolve.ts"
+
+export function renderSkillSuggestions(agent: string, caps: string[]): string[] {
+  if (caps.length === 0) return []
+  const index = scanSkillTags()
+  const { skillNames, generic, techStackOnly } = resolveSkillsForCapabilities(caps, index)
+
+  const lines: string[] = []
+  if (skillNames.length === 0) return lines
+
+  lines.push("## Skill 加载清单", "")
+  lines.push("必须加载（逐项用 Skill tool 加载，未找到时跳过）：", "")
+
+  for (const name of generic) {
+    lines.push(`- \`${name}\``)
+  }
+  lines.push("")
+  if (techStackOnly.length > 0) {
+    lines.push("仅当技术栈匹配时加载：", "")
+    const byStack = new Map<string, string[]>()
+    for (const name of techStackOnly) {
+      const tags = index.skillTags.get(name) || []
+      const stackTag = tags.find((t) => t.startsWith("tech-stack-"))
+      if (!stackTag) continue
+      const arr = byStack.get(stackTag) || []
+      arr.push(name)
+      byStack.set(stackTag, arr)
+    }
+    for (const names of byStack.values()) {
+      for (const name of names) {
+        lines.push(`- \`${name}\``)
+      }
+    }
+    lines.push("")
+  }
+  lines.push("（其他 available_skills 中未列举的相关 skill，按需加载）")
+  lines.push("")
+
+  const hinted: string[] = []
+  for (const name of skillNames) {
+    const mdPath = findSkillPath(name)
+    if (!mdPath) continue
+    try {
+      const raw = readFileSync(mdPath, "utf-8")
+      if (!raw.includes("boundary_hints:")) continue
+      const dm = raw.match(/directories:\s*\[([^\]]*)\]/)
+      if (dm) for (const d of dm[1].split(",").map((s: string) => s.trim().replace(/["']/g, ""))) {
+        hinted.push(`- \`${name}\` → \`${d}\``)
+      }
+    } catch { /* skip */ }
+  }
+
+  if (hinted.length > 0) {
+    lines.push("## 路径提示（skill 声明的 boundary_hints）", "")
+    lines.push("以下目录不受执行边界限制：", "")
+    lines.push(...hinted)
+    lines.push("")
+  }
+
+  return lines
+}
+
+export function renderEfficiencySteps(startNum: number): { lines: string[], nextNum: number } {
+  const lines: string[] = []
+  let n = startNum
+  if (getEfficiencySkills().length > 0) {
+    lines.push(`${n++}. 按已加载的效率 skill 中的工具可用性检测步骤确认代码探索工具就绪（含索引初始化）`)
+    lines.push(`${n++}. 初始化仅是前置——本 session 后续所有代码探索操作须持续遵循已加载效率 skill 中的工具选择规则，不可将初始化视为终点而恢复默认工具习惯`)
+    lines.push(`${n++}. 提交前自查：本 step 涉及的代码探索（符号定位/调用关系/影响评估）是否遵循已加载效率 skill 的工具选择规则，未遵循须补做`)
+  }
+  return { lines, nextNum: n }
+}
+
+/** worktree 就绪判定：taskGroup 投影的 worktreePath 非空即就绪（与 submit 硬门禁的 metadata.worktree_path 同源）。 */
+export function isWorktreeReady(tg: TaskGroupState): boolean {
+  return Boolean(tg.worktreePath)
+}
+
+/** 统一 worktree 未就绪提示文案（renderWorktreeSection / orchestrator 分派视图 / 子代理拒绝执行视图共用）。 */
+export function renderWorktreeNotReady(): string[] {
+  return ["- (worktree 未就绪 — 请编排者先调用 opx_orch_set_worktree)"]
+}
+
+/** 状态异常（phase ↔ step 归属错位）诊断行：subagent 拒绝视图与 orchestrator 分派视图共用。 */
+export function renderStateMismatchDiagnostic(
+  phase: string,
+  currentStep: string | null,
+  expectedPhase: string | null,
+): string[] {
+  return [
+    `- **当前阶段 (phase)**: \`${phase}\``,
+    `- **当前 step**: \`${currentStep ?? "(无)"}\``,
+    `- **step 预期归属阶段**: \`${expectedPhase ?? "(未知)"}\``,
+  ]
+}
+
+export function renderWorktreeSection(
+  state: OrchestrateState,
+  tg: TaskGroupState,
+  opts?: { showNamespace?: boolean; showPort?: boolean },
+): string[] {
+  const lines: string[] = []
+  lines.push("## Worktree", "")
+  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 全部已提交变更文件`)
+    lines.push("- **⚠️ 约束**: 所有读写和 git 操作均在此目录下进行；严禁直接修改主仓库/主分支路径下的文件（如 `<repo>/openspec/...`）")
+    lines.push("- **路径解析**: 推荐阅读文档均为相对 worktree 路径的引用，一律以 worktree 路径为基准解析，禁止从主仓库根目录解析")
+  } else {
+    lines.push(...renderWorktreeNotReady())
+  }
+  if (opts?.showNamespace) {
+    lines.push(`- **隔离标识**: \`${state.isolationNamespace}\``)
+    if (opts?.showPort) {
+      lines.push(`  - 建议端口: ${derivePortFromNamespace(state.isolationNamespace)}`)
+    }
+  }
+  lines.push("")
+  return lines
+}
+
+export function formatFilePath(file: string, line: number, maxLen = 60): string {
+  const suffix = line > 0 ? `:${line}` : ""
+  const full = `${file}${suffix}`
+  if (full.length <= maxLen) return full
+  const parts = file.split("/")
+  if (parts.length <= 1) return full.slice(0, maxLen - 3) + "..."
+  const base = parts[parts.length - 1]
+  const parent = parts[parts.length - 2]
+  const tryTwo = `.../${parent}/${base}${suffix}`
+  if (tryTwo.length <= maxLen) return tryTwo
+  const lastSeg = `${base}${suffix}`
+  if (lastSeg.length <= maxLen) return lastSeg
+  return lastSeg.slice(0, maxLen - 3) + "..."
+}
+
+export function renderTaskItem(t: TaskItem): string {
+  const trace = t.specTrace ? ` [spec:${t.specTrace}]` : ""
+  return `- Task id=${t.id} ｜ ${t.title}${trace}`
+}
+
+export function formatSeverity(severity: string): string {
+  switch (severity) {
+    case "Critical": return `**${severity}**`
+    case "High": return `**${severity}**`
+    case "Medium": return `*${severity}*`
+    case "Low": return severity
+    case "Info": return `\`${severity}\``
+    default: return severity
+  }
+}
+
+/** 上轮会话摘要渲染。参数为 agentSummaries 记录（workItems 单轨下直接读 item.metadata["agent_summaries"]）。
+ *  按调用者角色隔离（409c411 意图）：只渲染当前 agent 自己的摘要，不跨 agent 传递。 */
+export function renderAgentSummaries(agentSummaries: Record<string, string> | undefined, agentName: string): string[] {
+  if (!agentSummaries || !agentSummaries[agentName]) return []
+  const lines: string[] = ["## 上轮会话摘要", ""]
+  lines.push(`- **${agentName}**：${agentSummaries[agentName]}`)
+  lines.push("")
+  return lines
+}
+
+// ─── 占位符插值层 ───
+
+/** 插值白名单：仅这些 key 可被 {{key}} 占位符引用，其余一律保留原文（防配置注入任意动态值）。 */
+const INTERPOLATION_ALLOWED_KEYS = new Set([
+  "worktree_path",
+  "change_id",
+  "step_id",
+  "phase",
+  "agent",
+  "allowed_directories",
+  "allowed_packages",
+  "notes",
+  "base_branch",
+])
+
+/**
+ * 占位符插值：将 text 中的 `{{key}}` 替换为 ctx[key]。
+ * - key 不在白名单：保留原文（原样返回占位符）
+ * - ctx 缺值：保留原文（降级，不抛错、不阻断渲染）
+ */
+export function interpolateText(text: string, ctx: Record<string, string>): string {
+  return text.replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (raw, key: string) => {
+    if (!INTERPOLATION_ALLOWED_KEYS.has(key)) return raw
+    const value = ctx[key]
+    return value === undefined ? raw : value
+  })
+}
+

package/src/core/workflow/collector.ts

@@ -0,0 +1,150 @@
+import { readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import type { WorkItem } from "./types.ts"
+import { createInitialWorkItem } from "./engine.ts"
+
+/**
+ * 收集器统一接入接口（spec workflow-collectors）。
+ * 生命周期：pull 拉取外部原始项 → transform 产出初始 WorkItem（phase=todo、
+ * suspended=false、children 为空、tags 为空）→ writeback 将处理结果回写外部源。
+ */
+export interface CollectorAdapter {
+  readonly name: string
+  pollIntervalMs: number
+  pull(): Promise<unknown[]>
+  transform(raw: unknown[]): WorkItem[]
+  writeback(item: WorkItem, payload: unknown): Promise<{ success: boolean; error?: string }>
+}
+
+export interface OpenSpecCollectorOptions {
+  openspecDir: string
+  pollIntervalMs?: number
+}
+
+/** OpenSpec change 原始扫描项：change 目录名 + proposal.md 全文。 */
+export interface OpenSpecChangeRef {
+  changeName: string
+  proposalText: string
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 30_000
+const SOURCE = "openspec"
+const CHANGE_LABEL = "openspec-change"
+
+/** 提取 proposal.md 一级标题作为 title；无一级标题时回退到 change 目录名。 */
+function extractTitle(proposalText: string, fallback: string): string {
+  const heading = /^#\s+(.+)$/m.exec(proposalText)
+  const title = heading?.[1]?.trim()
+  return title ? title : fallback
+}
+
+/** 提取 proposal.md 的 Why 段正文作为摘要；无 Why 段时返回空串。 */
+function extractSummary(proposalText: string): string {
+  const lines = proposalText.split(/\r?\n/)
+  const whyIndex = lines.findIndex((line) => /^##\s+Why\s*$/.test(line.trim()))
+  if (whyIndex === -1) return ""
+  const body: string[] = []
+  for (let i = whyIndex + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break
+    const trimmed = lines[i].trim()
+    if (trimmed !== "") body.push(trimmed)
+  }
+  return body.join(" ")
+}
+
+/**
+ * OpenSpec 收集器：pull 扫描 {openspecDir}/changes 下含 proposal.md 的 change 子目录
+ * 返回原始 ref，transform 将其转为 task WorkItem。每次 pull 重新扫描磁盘，幂等且不抛错。
+ */
+export class OpenSpecCollector implements CollectorAdapter {
+  readonly name = SOURCE
+  readonly openspecDir: string
+  readonly pollIntervalMs: number
+
+  constructor(options: OpenSpecCollectorOptions) {
+    this.openspecDir = options.openspecDir
+    this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
+  }
+
+  async pull(): Promise<OpenSpecChangeRef[]> {
+    const changesDir = join(this.openspecDir, "changes")
+    let entries
+    try {
+      entries = readdirSync(changesDir, { withFileTypes: true })
+    } catch {
+      return []
+    }
+
+    const refs: OpenSpecChangeRef[] = []
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      try {
+        const proposalText = readFileSync(join(changesDir, entry.name, "proposal.md"), "utf8")
+        refs.push({ changeName: entry.name, proposalText })
+      } catch {
+        continue
+      }
+    }
+    return refs
+  }
+
+  transform(raw: unknown[]): WorkItem[] {
+    return raw.map((ref) => {
+      const { changeName, proposalText } = ref as OpenSpecChangeRef
+      return createInitialWorkItem({
+        id: `${SOURCE}:${changeName}`,
+        source: SOURCE,
+        externalId: changeName,
+        type: "task",
+        title: extractTitle(proposalText, changeName),
+        description: extractSummary(proposalText) || changeName,
+        labels: [CHANGE_LABEL],
+      })
+    })
+  }
+
+  async writeback(_item: WorkItem, _payload: unknown): Promise<{ success: boolean; error?: string }> {
+    return { success: true }
+  }
+}
+
+/**
+ * ADO 收集器占位实现（spec workflow-collectors：占位拉取不报错）。
+ * pull/transform 返回空，为后续接入真实 ADO 预留接口，引擎调度不受影响。
+ */
+export class AdoCollector implements CollectorAdapter {
+  readonly name = "ado"
+  readonly pollIntervalMs = DEFAULT_POLL_INTERVAL_MS
+
+  async pull(): Promise<unknown[]> {
+    return []
+  }
+
+  transform(_raw: unknown[]): WorkItem[] {
+    return []
+  }
+
+  async writeback(_item: WorkItem, _payload: unknown): Promise<{ success: boolean; error?: string }> {
+    return { success: true }
+  }
+}
+
+// ─── 自定义 adapter 注册表（静态注册，spec 设计决策取静态而非目录扫描）───
+
+const registry: CollectorAdapter[] = []
+
+/** 注册自定义收集器；同名 adapter 重复注册幂等跳过。 */
+export function registerCollector(adapter: CollectorAdapter): void {
+  if (registry.some((a) => a.name === adapter.name)) return
+  registry.push(adapter)
+}
+
+/** 返回已注册收集器副本（含内置 openspec/ado 占位）。 */
+export function getCollectors(): CollectorAdapter[] {
+  return [...registry]
+}
+
+/** 清空注册表（测试隔离用，非编排业务接口）。 */
+export function __resetCollectors(): void {
+  registry.length = 0
+}