@ifrankwang/openspec-agents 0.121.1 → 0.122.1

package/.mcp-server/cli.mjs

@@ -34170,28 +34170,6 @@ var SIMPLE_WORKFLOW_PATH = resolveWorkflowFilePath(import.meta.url, "task-simple
 function resolveWorkflowPath(state) {
   return state.mode === "simple" ? SIMPLE_WORKFLOW_PATH : TASK_WORKFLOW_PATH;
 }
-var WORKFLOW_MODE_CONFIG_FILE = "openspec/workflow.yaml";
-function readWorkflowModeConfig(worktree) {
-  const configPath = pathResolve(worktree, WORKFLOW_MODE_CONFIG_FILE);
-  if (!existsSync2(configPath))
-    return "full";
-  let raw;
-  try {
-    raw = yaml.load(readFileSync2(configPath, "utf-8"));
-  } catch (err) {
-    fail(`${WORKFLOW_MODE_CONFIG_FILE} 解析失败：${err.message}`);
-  }
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    fail(`${WORKFLOW_MODE_CONFIG_FILE} 配置非法：顶层必须是 YAML 映射对象`);
-  }
-  const mode = raw.mode;
-  if (mode === undefined)
-    return "full";
-  if (mode !== "full" && mode !== "simple") {
-    fail(`${WORKFLOW_MODE_CONFIG_FILE} 配置非法：mode 值域为 full/simple，收到 ${JSON.stringify(mode)}`);
-  }
-  return mode;
-}
 var workflowFileCache = new Map;
 function loadWorkflowFile(filePath) {
   let wf = workflowFileCache.get(filePath);
@@ -34367,21 +34345,43 @@ function loadWorkflow(yamlText) {
 import { readFileSync as readFileSync4 } from "node:fs";
 
 // src/skills/scan.ts
-import { existsSync as existsSync3 } from "node:fs";
+import { existsSync as existsSync3, readdirSync as readdirSync2 } from "node:fs";
 import { resolve, dirname as dirname2, join as join2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { homedir } from "node:os";
 var projectRoot = resolve(dirname2(fileURLToPath2(import.meta.url)), "..", "..");
+function resolveSkillScanRoot(moduleUrl) {
+  const startDir = dirname2(fileURLToPath2(moduleUrl));
+  let dir = startDir;
+  for (;; ) {
+    for (const candidate of [resolve(dir, "assets", "skills"), resolve(dir, "skills")]) {
+      if (isSkillRoot(candidate))
+        return candidate;
+    }
+    const parent = dirname2(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
+function isSkillRoot(candidate) {
+  if (!existsSync3(candidate))
+    return false;
+  try {
+    return readdirSync2(candidate, { withFileTypes: true }).some((entry) => entry.isDirectory() && existsSync3(join2(candidate, entry.name, "SKILL.md")));
+  } catch {
+    return false;
+  }
+}
+var scanRoot = resolveSkillScanRoot(import.meta.url);
 var SKILL_SCAN_ROOTS = [
-  resolve(projectRoot, "assets", "skills"),
+  ...scanRoot ? [scanRoot] : [],
   resolve(projectRoot, ".agents", "skills"),
   resolve(projectRoot, ".opencode", "skills"),
   join2(homedir(), ".agents", "skills"),
   join2(homedir(), ".config", "opencode", "skills")
 ];
-var DISTRIBUTED_SKILL_ROOTS = [
-  resolve(projectRoot, "assets", "skills")
-];
 function findSkillPath(name) {
   for (const root of SKILL_SCAN_ROOTS) {
     const p = resolve(root, name, "SKILL.md");
@@ -34392,7 +34392,7 @@ function findSkillPath(name) {
 }
 
 // src/skills/resolve.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync3, existsSync as existsSync4 } from "node:fs";
+import { readdirSync as readdirSync3, readFileSync as readFileSync3, existsSync as existsSync4 } from "node:fs";
 import { resolve as resolve2 } from "node:path";
 var cacheKey = null;
 var cacheIndex = null;
@@ -34407,7 +34407,7 @@ function scanSkillTags(roots = SKILL_SCAN_ROOTS) {
   for (const root of roots) {
     if (!existsSync4(root))
       continue;
-    for (const entry of readdirSync2(root, { withFileTypes: true })) {
+    for (const entry of readdirSync3(root, { withFileTypes: true })) {
       if (!entry.isDirectory())
         continue;
       if (seen.has(entry.name))
@@ -35752,6 +35752,9 @@ async function initExecute(params, ctx) {
     args.recovery = parsed;
   }
   assertValidRecovery(args.recovery);
+  if (args.mode !== undefined && args.mode !== "full" && args.mode !== "simple") {
+    throw new Error(`mode 参数不合法，合法值：full、simple。传入值："${String(args.mode)}"。`);
+  }
   const parsedGroups = await parseAllTaskGroupsFromMd(ctx.worktree, args.change_id);
   if (parsedGroups.length === 0) {
     throw new Error(`无法从 tasks.md 解析出任务组，请检查文件 openspec/changes/${args.change_id}/tasks.md。`);
@@ -35784,7 +35787,7 @@ async function initExecute(params, ctx) {
       workItems: [],
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
-      mode: readWorkflowModeConfig(ctx.worktree)
+      mode: args.mode ?? "simple"
     };
   } else {
     state.baseBranch = state.baseBranch || baseBranch;
@@ -36833,7 +36836,12 @@ var orchInitSchema = {
       type: "string",
       description: "基准分支名（如 main、develop），用于计算 merge-base 和 worktree fork 源。未传则自动从当前 git 分支推导。"
     },
-    recovery: recoverySchema
+    recovery: recoverySchema,
+    mode: {
+      type: "string",
+      enum: ["full", "simple"],
+      description: "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。仅新建编排状态（首次 opx_orch_init）时生效；已开始的变更沿用固化模式，不支持中途切换。"
+    }
   },
   required: ["change_id", "task_group_id"],
   additionalProperties: false
@@ -37024,7 +37032,7 @@ function jsonSchemaToZod(schema2) {
 var AGENT_ARG = "_agent";
 var TOOL_SPECS = {
   opx_orch_init: {
-    description: "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。",
+    description: "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式，仅新建状态生效。",
     schema: orchInitSchema,
     execute: (args, ctx) => initExecute(args, ctx)
   },
@@ -37084,7 +37092,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.121.1";
+var PKG_VERSION = "0.122.1";
 function buildMcpServer(worktree, opts = {}) {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION });
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {
@@ -39225,7 +39233,7 @@ class StreamableHTTPServerTransport {
 import { createServer } from "node:http";
 
 // src/core/dashboard.ts
-import { readdirSync as readdirSync3, existsSync as existsSync5 } from "node:fs";
+import { readdirSync as readdirSync4, existsSync as existsSync5 } from "node:fs";
 import { readFile as readFile5 } from "node:fs/promises";
 import path7 from "path";
 function toWorkItemCard(item) {
@@ -39282,7 +39290,7 @@ async function readDashboardState(worktree, changeId) {
   const stateDir = getStateDir(worktree);
   if (!existsSync5(stateDir))
     return null;
-  const files = readdirSync3(stateDir).filter((f) => f.endsWith(".json"));
+  const files = readdirSync4(stateDir).filter((f) => f.endsWith(".json"));
   const results = [];
   for (const f of files) {
     try {
@@ -39370,7 +39378,7 @@ async function startDashboard(worktree) {
   console.error(`[dashboard] 无法启动编排进度看板：端口 ${BASE_PORT}-${BASE_PORT + MAX_ATTEMPTS - 1} 均被占用`);
 }
 // src/core/workflow/collector.ts
-import { readdirSync as readdirSync4, readFileSync as readFileSync6 } from "node:fs";
+import { readdirSync as readdirSync5, readFileSync as readFileSync6 } from "node:fs";
 import { join as join4 } from "node:path";
 var DEFAULT_POLL_INTERVAL_MS = 30000;
 var SOURCE = "openspec";
@@ -39408,7 +39416,7 @@ class OpenSpecCollector {
     const changesDir = join4(this.openspecDir, "changes");
     let entries;
     try {
-      entries = readdirSync4(changesDir, { withFileTypes: true });
+      entries = readdirSync5(changesDir, { withFileTypes: true });
     } catch {
       return [];
     }

package/README.md

@@ -15,7 +15,7 @@ OpenSpec 把需求、设计、任务拆解成规范文档后，实施阶段仍
 
 ## 编排流程
 
-实施流程按变更开始时固化的模式执行，配置源为仓库根 `openspec/workflow.yaml`（`mode: full | simple`，缺省 full）。模式在变更开始时由 `opx_orch_init` 固化存档：已开始的变更不受后续配置改动影响，恢复（recovery）沿用固化模式，旧变更（状态无模式存档）一律按 full 处理，不支持中途切换。
+实施流程按变更开始时固化的模式执行：模式经 `opx_orch_init` 的 `mode` 参数在变更开始时固化（`full` 完整流程 / `simple` 精简流程，不传缺省 simple）。已开始的变更不受后续参数影响；恢复（recovery）沿用固化模式；旧变更（状态无模式存档）一律按 full 处理，不支持中途切换。
 
 ### full 模式
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.121.1",
+  "version": "0.122.1",
   "type": "module",
   "main": "./src/core/index.ts",
   "exports": {

package/src/adapters/mcp-common/server.ts

@@ -37,7 +37,7 @@ interface ToolSpec {
 const TOOL_SPECS: Record<string, ToolSpec> = {
   opx_orch_init: {
     description:
-      "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。",
+      "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式，仅新建状态生效。",
     schema: orchInitSchema,
     execute: (args, ctx) => initExecute(args as any, ctx),
   },

package/src/core/tools/lifecycle.ts

@@ -10,7 +10,7 @@ import { parseAllTaskGroupsFromMd, parseTasksMdForGroup, extractRelevantSpecsFro
 import type { ParsedTask } from "../tasks-md.ts"
 import { assertOrchestrator, findTaskGroup } from "../derive.ts"
 import { assertPathWithin } from "../paths.ts"
-import { loadWorkflowFile, resolveWorkflowPath, readWorkflowModeConfig, type LoadedWorkflow } from "../workflow/loader.ts"
+import { loadWorkflowFile, resolveWorkflowPath, type LoadedWorkflow } from "../workflow/loader.ts"
 import { createInitialWorkItem, isBlockingSeverity, isTerminalPhase, recommendForItem, resetInternalRetryCount, adjudicateStep, clearStepTags } from "../workflow/engine.ts"
 import { renderWorkflowStatusView } from "../workflow/status.ts"
 import { taskChildrenOf } from "../task-children.ts"
@@ -293,6 +293,10 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
     (args as any).recovery = parsed
   }
   assertValidRecovery(args.recovery)
+  // mode 值域校验：值域外一律拒绝（无论 state 是否已存在），错误早于任何状态变更且不落盘
+  if (args.mode !== undefined && args.mode !== "full" && args.mode !== "simple") {
+    throw new Error(`mode 参数不合法，合法值：full、simple。传入值："${String(args.mode)}"。`)
+  }
 
   const parsedGroups = await parseAllTaskGroupsFromMd(ctx.worktree, args.change_id)
   if (parsedGroups.length === 0) {
@@ -331,10 +335,9 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
       workItems: [],
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
-      // 新建 state 时固化模式：读取 <worktree>/openspec/workflow.yaml（缺失视为 full，
-      // 值域外 / YAML 解析失败抛错）；state 已存在（recovery/重复初始化/切换任务组）不读配置，
+      // 新建 state 时固化模式：取 init 参数 mode（缺省 simple）；state 已存在不读参数，
       // 沿用 state 既有 mode；旧 state 缺 mode 由消费端读时兜底 full，不写回。
-      mode: readWorkflowModeConfig(ctx.worktree),
+      mode: args.mode ?? "simple",
     }
   } else {
     state.baseBranch = state.baseBranch || baseBranch

package/src/core/tools/schemas.ts

@@ -213,6 +213,12 @@ export const orchInitSchema: JSONSchema = {
       description: "基准分支名（如 main、develop），用于计算 merge-base 和 worktree fork 源。未传则自动从当前 git 分支推导。",
     },
     recovery: recoverySchema,
+    mode: {
+      type: "string",
+      enum: ["full", "simple"],
+      description:
+        "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。仅新建编排状态（首次 opx_orch_init）时生效；已开始的变更沿用固化模式，不支持中途切换。",
+    },
   },
   required: ["change_id", "task_group_id"],
   additionalProperties: false,

package/src/core/tools/types.ts

@@ -1,4 +1,4 @@
-import type { BuildPhaseTarget, ReviewLayer, ReviewVerifyStep } from "../types.ts"
+import type { BuildPhaseTarget, ReviewLayer, ReviewVerifyStep, WorkflowMode } from "../types.ts"
 
 export interface ToolContext {
   worktree: string
@@ -28,6 +28,8 @@ export interface InitParams {
      *  恢复后 currentStep 落在第一个未全部通过的 verify step，可能早于被重置的 step。 */
     reset_steps?: ReviewVerifyStep[]
   }
+  /** 流程模式（full/simple），仅新建编排状态时生效；已开始的变更沿用固化模式，不支持中途切换。 */
+  mode?: WorkflowMode
 }
 
 export interface SetWorktreeParams {

package/src/core/types.ts

@@ -135,7 +135,7 @@ export interface OrchestrateState {
   createdAt: string
   updatedAt: string
   unattended?: boolean
-  /** 变更开始时固化的流程模式（opx_orch_init 从 <repo>/openspec/workflow.yaml 读取后写入）。
-   *  缺失即旧变更，一律按 full 处理（读时兜底，不写回）；已存在的 state 不再被配置改动覆盖。 */
+  /** 变更开始时固化的流程模式（经 opx_orch_init 的 mode 参数写入，缺省 simple）。
+   *  缺失即旧变更，一律按 full 处理（读时兜底，不写回）；已存在的 state 不再被参数改动覆盖。 */
   mode?: WorkflowMode
 }

package/src/core/workflow/loader.ts

@@ -13,7 +13,7 @@ import type {
 } from "./types.ts"
 import { WORK_ITEM_PHASES, stepAgentIds } from "./types.ts"
 import { DIMENSION_AGENT_MAP } from "../constants.ts"
-import type { OrchestrateState, WorkflowMode } from "../types.ts"
+import type { OrchestrateState } from "../types.ts"
 
 const SPECIAL_TRANSITIONS = ["done", "halt"] as const
 const PHASE_NAMES = new Set<string>(WORK_ITEM_PHASES)
@@ -63,38 +63,6 @@ export function resolveWorkflowPath(state: Pick<OrchestrateState, "mode">): stri
   return state.mode === "simple" ? SIMPLE_WORKFLOW_PATH : TASK_WORKFLOW_PATH
 }
 
-/** 项目级模式配置文件路径（<worktree>/openspec/workflow.yaml，与 openspec/config.yaml 同级）。 */
-const WORKFLOW_MODE_CONFIG_FILE = "openspec/workflow.yaml"
-
-/**
- * 读取项目级流程模式配置（<worktree>/openspec/workflow.yaml）：
- * - 文件缺失 → "full"（缺省）
- * - YAML 解析失败 → 抛错
- * - 顶层非 YAML 映射对象 → 抛错
- * - mode 字段缺失 → "full"（缺省）
- * - mode 值域外（非 full/simple）→ 抛错
- * 仅由 opx_orch_init 新建 state 时调用；已存在的 state 不读配置，沿用既有 mode。
- */
-export function readWorkflowModeConfig(worktree: string): WorkflowMode {
-  const configPath = pathResolve(worktree, WORKFLOW_MODE_CONFIG_FILE)
-  if (!existsSync(configPath)) return "full"
-  let raw: unknown
-  try {
-    raw = yaml.load(readFileSync(configPath, "utf-8"))
-  } catch (err) {
-    fail(`${WORKFLOW_MODE_CONFIG_FILE} 解析失败：${(err as Error).message}`)
-  }
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    fail(`${WORKFLOW_MODE_CONFIG_FILE} 配置非法：顶层必须是 YAML 映射对象`)
-  }
-  const mode = (raw as { mode?: unknown }).mode
-  if (mode === undefined) return "full"
-  if (mode !== "full" && mode !== "simple") {
-    fail(`${WORKFLOW_MODE_CONFIG_FILE} 配置非法：mode 值域为 full/simple，收到 ${JSON.stringify(mode)}`)
-  }
-  return mode
-}
-
 const workflowFileCache = new Map<string, LoadedWorkflow>()
 
 /** 读取 workflow YAML 文件并解析，进程内按路径缓存（submit / status 共用）。 */

package/src/skills/scan.ts

@@ -1,12 +1,52 @@
-import { existsSync } from "node:fs"
+import { existsSync, readdirSync } 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)), "..", "..")
 
+/**
+ * 定位随包分发的 skill 根目录：源码（src/skills/ 上溯 2 级=仓库根 assets/skills）、插件包 dist 形态
+ * （<插件根>/.mcp-server/ 上溯 1 级=插件根 skills/，plugin-common buildSkills 输出）与 ZCode 缓存嵌套形态
+ * （cache/<marketplace>/<plugin>/<version>/.mcp-server/ 上溯 1 级=版本目录 skills/）部署深度不同，
+ * 故从模块所在目录逐级上溯探测（与 resolveWorkflowFilePath 同范式）。每级按固定顺序探测两个候选：
+ * assets/skills 优先、skills 其次；命中要求目录下至少有一个子目录含 SKILL.md（防御空骨架目录，
+ * 如仓库根遗留的空 skills/）。首个命中即采用（首中即用，不做多根收集——避免 npm 形态上溯越过
+ * 包根误收消费方项目根）。bundle 单文件合并后 import.meta.url 指向部署位置（cli.mjs），源码形态
+ * 指向本文件自身，两者自然成立。
+ */
+export function resolveSkillScanRoot(moduleUrl: string): string | null {
+  const startDir = dirname(fileURLToPath(moduleUrl))
+  let dir = startDir
+  for (;;) {
+    for (const candidate of [resolve(dir, "assets", "skills"), resolve(dir, "skills")]) {
+      if (isSkillRoot(candidate)) return candidate
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break // 到达文件系统根
+    dir = parent
+  }
+  return null
+}
+
+/** 目录存在且至少有一个子目录含 SKILL.md 才算 skill 根；空骨架目录（子目录无 SKILL.md）不命中。 */
+function isSkillRoot(candidate: string): boolean {
+  if (!existsSync(candidate)) return false
+  try {
+    return readdirSync(candidate, { withFileTypes: true }).some(
+      (entry) => entry.isDirectory() && existsSync(join(candidate, entry.name, "SKILL.md")),
+    )
+  } catch {
+    return false // 不可读目录按未命中处理（优雅降级，不阻断扫描）
+  }
+}
+
+// 随包分发 skill 缺失时优雅降级（返回 null）：只影响视图加载建议与门禁索引，不阻断 server 启动；
+// 与 loader 的 workflow 缺失即抛错差异是有意为之——opx_* 工具全部依赖 workflow，缺失时 server 无可用性。
+const scanRoot = resolveSkillScanRoot(import.meta.url)
+
 export const SKILL_SCAN_ROOTS: string[] = [
-  resolve(projectRoot, "assets", "skills"),
+  ...(scanRoot ? [scanRoot] : []),
   resolve(projectRoot, ".agents", "skills"),
   resolve(projectRoot, ".opencode", "skills"),
   join(homedir(), ".agents", "skills"),
@@ -14,9 +54,8 @@ export const SKILL_SCAN_ROOTS: string[] = [
 ]
 
 // 仅随插件分发注入 opencode 的 skill 根目录。.agents/skills 靠 opencode 标准发现对本仓库自用生效，非插件注入职责。
-export const DISTRIBUTED_SKILL_ROOTS: string[] = [
-  resolve(projectRoot, "assets", "skills"),
-]
+// 源码形态探测根即仓库根 assets/skills（与改动前行为一致）；插件形态为插件根 skills/。
+export const DISTRIBUTED_SKILL_ROOTS: string[] = scanRoot ? [scanRoot] : []
 
 export function findSkillPath(name: string): string | null {
   for (const root of SKILL_SCAN_ROOTS) {
@@ -25,5 +64,3 @@ export function findSkillPath(name: string): string | null {
   }
   return null
 }
-
-