@ifrankwang/openspec-agents 0.142.0 → 0.144.0

package/.mcp-server/cli.mjs

@@ -19408,6 +19408,9 @@ class Protocol {
       this.setRequestHandler(GetTaskPayloadRequestSchema, async (request, extra) => {
         const handleTaskResult = async () => {
           const taskId = request.params.taskId;
+          if (!await this._taskStore.getTask(taskId, extra.sessionId)) {
+            throw new McpError(ErrorCode.InvalidParams, `Task not found: ${taskId}`);
+          }
           if (this._taskMessageQueue) {
             let queuedMessage;
             while (queuedMessage = await this._taskMessageQueue.dequeue(taskId, extra.sessionId)) {
@@ -19438,12 +19441,12 @@ class Protocol {
             throw new McpError(ErrorCode.InvalidParams, `Task not found: ${taskId}`);
           }
           if (!isTerminal(task.status)) {
-            await this._waitForTaskUpdate(taskId, extra.signal);
+            await this._waitForTaskUpdate(taskId, extra.signal, extra.sessionId);
             return await handleTaskResult();
           }
           if (isTerminal(task.status)) {
             const result = await this._taskStore.getTaskResult(taskId, extra.sessionId);
-            this._clearTaskQueue(taskId);
+            this._clearTaskQueue(taskId, extra.sessionId);
             return {
               ...result,
               _meta: {
@@ -19480,7 +19483,7 @@ class Protocol {
             throw new McpError(ErrorCode.InvalidParams, `Cannot cancel task in terminal status: ${task.status}`);
           }
           await this._taskStore.updateTaskStatus(request.params.taskId, "cancelled", "Client cancelled task execution.", extra.sessionId);
-          this._clearTaskQueue(request.params.taskId);
+          this._clearTaskQueue(request.params.taskId, extra.sessionId);
           const cancelledTask = await this._taskStore.getTask(request.params.taskId, extra.sessionId);
           if (!cancelledTask) {
             throw new McpError(ErrorCode.InvalidParams, `Task not found after cancellation: ${request.params.taskId}`);
@@ -19603,6 +19606,19 @@ class Protocol {
     const handler = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
     const capturedTransport = this._transport;
     const relatedTaskId = request.params?._meta?.[RELATED_TASK_META_KEY]?.taskId;
+    const sessionId = capturedTransport?.sessionId;
+    const store = this._taskStore;
+    let relatedTaskFound = true;
+    let relatedTaskLookup;
+    if (relatedTaskId && store && this._taskMessageQueue && sessionId !== undefined) {
+      relatedTaskFound = false;
+      relatedTaskLookup = (async () => {
+        if (!await store.getTask(relatedTaskId, sessionId)) {
+          throw new McpError(ErrorCode.InvalidParams, `Task not found: ${relatedTaskId}`);
+        }
+        relatedTaskFound = true;
+      })();
+    }
     if (handler === undefined) {
       const errorResponse = {
         jsonrpc: "2.0",
@@ -19612,7 +19628,10 @@ class Protocol {
           message: "Method not found"
         }
       };
-      if (relatedTaskId && this._taskMessageQueue) {
+      if (relatedTaskId && relatedTaskLookup) {
+        const queuedError = { type: "error", message: errorResponse, timestamp: Date.now() };
+        relatedTaskLookup.then(() => this._enqueueTaskMessage(relatedTaskId, queuedError, sessionId), () => capturedTransport?.send(errorResponse)).catch((error) => this._onerror(new Error(`Failed to send an error response: ${error}`)));
+      } else if (relatedTaskId && this._taskMessageQueue) {
         this._enqueueTaskMessage(relatedTaskId, {
           type: "error",
           message: errorResponse,
@@ -19663,7 +19682,10 @@ class Protocol {
       closeSSEStream: extra?.closeSSEStream,
       closeStandaloneSSEStream: extra?.closeStandaloneSSEStream
     };
-    Promise.resolve().then(() => {
+    (relatedTaskLookup ?? Promise.resolve()).then(() => {
+      if (relatedTaskLookup && abortController.signal.aborted) {
+        throw new McpError(ErrorCode.ConnectionClosed, "Request was cancelled");
+      }
       if (taskCreationParams) {
         this.assertTaskHandlerCapability(request.method);
       }
@@ -19698,7 +19720,7 @@ class Protocol {
           ...error["data"] !== undefined && { data: error["data"] }
         }
       };
-      if (relatedTaskId && this._taskMessageQueue) {
+      if (relatedTaskId && this._taskMessageQueue && relatedTaskFound) {
         await this._enqueueTaskMessage(relatedTaskId, {
           type: "error",
           message: errorResponse,
@@ -20086,7 +20108,7 @@ class Protocol {
       throw new Error("Cannot enqueue task message: taskStore and taskMessageQueue are not configured");
     }
     const maxQueueSize = this._options?.maxTaskQueueSize;
-    await this._taskMessageQueue.enqueue(taskId, message, sessionId, maxQueueSize);
+    await this._taskMessageQueue.enqueue(taskId, message, sessionId ?? this._transport?.sessionId, maxQueueSize);
   }
   async _clearTaskQueue(taskId, sessionId) {
     if (this._taskMessageQueue) {
@@ -20105,10 +20127,10 @@ class Protocol {
       }
     }
   }
-  async _waitForTaskUpdate(taskId, signal) {
+  async _waitForTaskUpdate(taskId, signal, sessionId) {
     let interval = this._options?.defaultTaskPollInterval ?? 1000;
     try {
-      const task = await this._taskStore?.getTask(taskId);
+      const task = await this._taskStore?.getTask(taskId, sessionId);
       if (task?.pollInterval) {
         interval = task.pollInterval;
       }
@@ -20775,6 +20797,43 @@ class ExperimentalMcpServerTasks {
   }
 }
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js
+function toolInputElementCount(value, max) {
+  let count = 0;
+  const stack = [value];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node === null || typeof node !== "object")
+      continue;
+    if (Array.isArray(node)) {
+      for (const child of node) {
+        if (++count > max)
+          return count;
+        if (child !== null && typeof child === "object")
+          stack.push(child);
+      }
+    } else {
+      for (const key in node) {
+        if (!Object.prototype.hasOwnProperty.call(node, key))
+          continue;
+        if (++count > max)
+          return count;
+        const child = node[key];
+        if (child !== null && typeof child === "object")
+          stack.push(child);
+      }
+    }
+  }
+  return count;
+}
+function resolveMaxToolInputElements(value) {
+  if (value === undefined || value === Infinity)
+    return;
+  if (typeof value !== "number" || Number.isNaN(value) || value < 1) {
+    throw new RangeError(`maxToolInputElements must be a number of at least 1, or Infinity, got ${String(value)}`);
+  }
+  return value;
+}
+
 class McpServer {
   constructor(serverInfo, options) {
     this._registeredResources = {};
@@ -20786,6 +20845,7 @@ class McpServer {
     this._resourceHandlersInitialized = false;
     this._promptHandlersInitialized = false;
     this.server = new Server(serverInfo, options);
+    this._maxToolInputElements = resolveMaxToolInputElements(options?.maxToolInputElements);
   }
   get experimental() {
     if (!this._experimental) {
@@ -20892,12 +20952,15 @@ class McpServer {
     };
   }
   async validateToolInput(tool, args, toolName) {
+    if (this._maxToolInputElements !== undefined && toolInputElementCount(args, this._maxToolInputElements) > this._maxToolInputElements) {
+      throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for tool ${toolName}: arguments contain more than the maximum of ${this._maxToolInputElements} elements`);
+    }
     if (!tool.inputSchema) {
       return;
     }
     const inputObj = normalizeObjectSchema(tool.inputSchema);
     const schemaToParse = inputObj ?? tool.inputSchema;
-    const parseResult = await safeParseAsync3(schemaToParse, args);
+    const parseResult = await safeParseAsync3(schemaToParse, args ?? {});
     if (!parseResult.success) {
       const error = "error" in parseResult ? parseResult.error : "Unknown error";
       const errorMessage = getParseErrorMessage(error);
@@ -21122,7 +21185,7 @@ class McpServer {
       }
       if (prompt.argsSchema) {
         const argsObj = normalizeObjectSchema(prompt.argsSchema);
-        const parseResult = await safeParseAsync3(argsObj, request.params.arguments);
+        const parseResult = await safeParseAsync3(argsObj, request.params.arguments ?? {});
         if (!parseResult.success) {
           const error = "error" in parseResult ? parseResult.error : "Unknown error";
           const errorMessage = getParseErrorMessage(error);
@@ -30459,7 +30522,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.142.0";
+var PKG_VERSION = "0.144.0";
 function buildMcpServer(worktree, opts = {}) {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION });
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {
@@ -30486,7 +30549,7 @@ function buildMcpServer(worktree, opts = {}) {
 }
 
 // src/adapters/mcp-common/index.ts
-import { createServer as createServer2 } from "node:http";
+import { createServer as createServer3 } from "node:http";
 import { randomUUID } from "node:crypto";
 import { join as join5 } from "node:path";
 
@@ -30494,6 +30557,7 @@ import { join as join5 } from "node:path";
 var X_ALREADY_SENT = "x-hono-already-sent";
 
 // node_modules/@hono/node-server/dist/index.mjs
+import { STATUS_CODES, ServerResponse, createServer } from "node:http";
 import { Http2ServerRequest, constants } from "node:http2";
 import { Readable } from "node:stream";
 
@@ -30503,20 +30567,17 @@ var defineWebSocketHelper = (handler) => {
     if (typeof args[0] === "function") {
       const [createEvents, options] = args;
       return async function upgradeWebSocket(c, next) {
-        const events = await createEvents(c);
-        const result = await handler(c, events, options);
-        if (result) {
+        const result = await handler(c, await createEvents(c), options);
+        if (result)
           return result;
-        }
         await next();
       };
     } else {
       const [c, events, options] = args;
       return (async () => {
         const upgraded = await handler(c, events, options);
-        if (!upgraded) {
+        if (!upgraded)
           throw new Error("Failed to upgrade WebSocket");
-        }
         return upgraded;
       })();
     }
@@ -31479,8 +31540,11 @@ var handleResponseError = (e, outgoing) => {
     console.info("The user aborted a request.");
   else {
     console.error(e);
-    if (!outgoing.headersSent)
+    if (!outgoing.headersSent) {
+      if (outgoing instanceof ServerResponse)
+        outgoing._contentLength = null;
       outgoing.writeHead(500, { "Content-Type": "text/plain" });
+    }
     outgoing.end(`Error: ${err.message}`);
     outgoing.destroy(err);
   }
@@ -31489,6 +31553,23 @@ var flushHeaders = (outgoing) => {
   if ("flushHeaders" in outgoing && outgoing.writable)
     outgoing.flushHeaders();
 };
+var trySetContentLength = (outgoing, status, length) => {
+  const http1 = outgoing;
+  if (http1._contentLength === null && http1._hasBody && http1.useChunkedEncodingByDefault && !http1._removedContLen && status >= 200 && status !== 204 && status !== 304 && !outgoing.hasHeader("content-length") && !outgoing.hasHeader("transfer-encoding") && !outgoing.hasHeader("trailer")) {
+    http1._contentLength = length;
+    return true;
+  }
+  return false;
+};
+var writeDefaultHeaders = (outgoing, status, length) => {
+  if (trySetContentLength(outgoing, status, length))
+    outgoing.writeHead(status, { "Content-Type": defaultContentType });
+  else
+    outgoing.writeHead(status, {
+      "Content-Type": defaultContentType,
+      "Content-Length": length
+    });
+};
 var responseViaCache = async (res, outgoing) => {
   let [status, body, header] = res[cacheKey2];
   if (!header) {
@@ -31496,22 +31577,13 @@ var responseViaCache = async (res, outgoing) => {
       outgoing.writeHead(status);
       outgoing.end();
     } else if (typeof body === "string") {
-      outgoing.writeHead(status, {
-        "Content-Type": defaultContentType,
-        "Content-Length": Buffer.byteLength(body)
-      });
+      writeDefaultHeaders(outgoing, status, Buffer.byteLength(body));
       outgoing.end(body);
     } else if (body instanceof Uint8Array) {
-      outgoing.writeHead(status, {
-        "Content-Type": defaultContentType,
-        "Content-Length": body.byteLength
-      });
+      writeDefaultHeaders(outgoing, status, body.byteLength);
       outgoing.end(body);
     } else if (body instanceof Blob) {
-      outgoing.writeHead(status, {
-        "Content-Type": defaultContentType,
-        "Content-Length": body.size
-      });
+      writeDefaultHeaders(outgoing, status, body.size);
       outgoing.end(new Uint8Array(await body.arrayBuffer()));
     } else {
       outgoing.writeHead(status, { "Content-Type": defaultContentType });
@@ -31522,6 +31594,8 @@ var responseViaCache = async (res, outgoing) => {
     return;
   }
   let hasContentLength = false;
+  let plainHeaders = false;
+  let canAutoLength = true;
   if (header instanceof Headers) {
     hasContentLength = header.has("content-length");
     header = buildOutgoingHttpHeaders(header, body === null ? undefined : defaultContentType);
@@ -31529,19 +31603,30 @@ var responseViaCache = async (res, outgoing) => {
     const headerObj = new Headers(header);
     hasContentLength = headerObj.has("content-length");
     header = buildOutgoingHttpHeaders(headerObj, body === null ? undefined : defaultContentType);
-  } else
-    for (const key in header)
+  } else {
+    plainHeaders = true;
+    for (const key in header) {
       if (key.length === 14 && key.toLowerCase() === "content-length") {
         hasContentLength = true;
         break;
       }
+      if (key.length === 17 && key.toLowerCase() === "transfer-encoding" || key.length === 7 && key.toLowerCase() === "trailer")
+        canAutoLength = false;
+    }
+  }
   if (!hasContentLength) {
+    let length;
     if (typeof body === "string")
-      header["Content-Length"] = Buffer.byteLength(body);
+      length = Buffer.byteLength(body);
     else if (body instanceof Uint8Array)
-      header["Content-Length"] = body.byteLength;
+      length = body.byteLength;
     else if (body instanceof Blob)
-      header["Content-Length"] = body.size;
+      length = body.size;
+    if (length !== undefined && (!plainHeaders || !canAutoLength || !trySetContentLength(outgoing, status, length))) {
+      if (plainHeaders)
+        header = { ...header };
+      header["Content-Length"] = length;
+    }
   }
   outgoing.writeHead(status, header);
   if (body == null)
@@ -31910,6 +31995,50 @@ function isJsonContentType(header) {
   return mediaTypeEssence(header) === "application/json";
 }
 
+// node_modules/@modelcontextprotocol/sdk/dist/esm/server/requestBody.js
+var DEFAULT_MAX_REQUEST_BODY_SIZE = 4 * 1024 * 1024;
+var MAX_BATCH_SIZE = 100;
+function requestBodyTooLargeMessage(maxBytes) {
+  return `Payload Too Large: Request body must not exceed ${maxBytes} bytes`;
+}
+function resolveMaxRequestBodySize(value) {
+  if (value === undefined) {
+    return DEFAULT_MAX_REQUEST_BODY_SIZE;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`maxRequestBodySize must be a positive number of bytes, got ${String(value)}`);
+  }
+  return value;
+}
+async function readRequestBody(request, maxBytes = DEFAULT_MAX_REQUEST_BODY_SIZE) {
+  if (Number(request.headers.get("content-length")) > maxBytes) {
+    return { tooLarge: true };
+  }
+  if (request.body === null) {
+    return { tooLarge: false, text: "" };
+  }
+  const reader = request.body.getReader();
+  const decoder = new TextDecoder;
+  let received = 0;
+  let text = "";
+  try {
+    for (;; ) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      received += value.byteLength;
+      if (received > maxBytes) {
+        return { tooLarge: true };
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return { tooLarge: false, text: text + decoder.decode() };
+}
+
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/sseKeepAlive.js
 var DEFAULT_SSE_KEEP_ALIVE_MS = 15000;
 var MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
@@ -31945,6 +32074,7 @@ class WebStandardStreamableHTTPServerTransport {
     this._enableDnsRebindingProtection = options.enableDnsRebindingProtection ?? false;
     this._retryInterval = options.retryInterval;
     this._keepAliveMs = options.keepAliveMs ?? DEFAULT_SSE_KEEP_ALIVE_MS;
+    this._maxRequestBodySize = resolveMaxRequestBodySize(options.maxRequestBodySize);
   }
   startKeepAlive(controller, encoder) {
     if (this._closed)
@@ -32261,12 +32391,22 @@ data:
         rawMessage = options.parsedBody;
       } else {
         try {
-          rawMessage = await req.json();
+          const body = await readRequestBody(req, this._maxRequestBodySize);
+          if (body.tooLarge) {
+            const message = requestBodyTooLargeMessage(this._maxRequestBodySize);
+            this.onerror?.(new Error(message));
+            return this.createJsonErrorResponse(413, -32000, message);
+          }
+          rawMessage = JSON.parse(body.text);
         } catch {
           this.onerror?.(new Error("Parse error: Invalid JSON"));
           return this.createJsonErrorResponse(400, -32700, "Parse error: Invalid JSON");
         }
       }
+      if (Array.isArray(rawMessage) && rawMessage.length > MAX_BATCH_SIZE) {
+        this.onerror?.(new Error(`Invalid Request: Batch must not exceed ${MAX_BATCH_SIZE} messages`));
+        return this.createJsonErrorResponse(400, -32600, `Invalid Request: Batch must not exceed ${MAX_BATCH_SIZE} messages`);
+      }
       let messages;
       try {
         if (Array.isArray(rawMessage)) {
@@ -32641,7 +32781,7 @@ class StreamableHTTPServerTransport {
 }
 
 // src/adapters/opencode/dashboard.ts
-import { createServer } from "node:http";
+import { createServer as createServer2 } from "node:http";
 
 // src/core/dashboard.ts
 import { readdirSync as readdirSync4, existsSync as existsSync5 } from "node:fs";
@@ -32746,7 +32886,7 @@ async function startDashboard(worktree) {
   const pageHtml = getDashboardPage();
   for (let port = BASE_PORT;port < BASE_PORT + MAX_ATTEMPTS; port++) {
     try {
-      const server = createServer(async (req, res) => {
+      const server = createServer2(async (req, res) => {
         try {
           const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "127.0.0.1"}`);
           if (url.pathname === "/api/state") {
@@ -32994,7 +33134,7 @@ async function startMcpServer(opts) {
   const port = opts.port ?? DEFAULT_PORT;
   const hostname = opts.hostname ?? "127.0.0.1";
   const transports = new Map;
-  const server = createServer2(async (req, res) => {
+  const server = createServer3(async (req, res) => {
     const url = new URL(req.url ?? "/", `http://${req.headers.host ?? hostname}`);
     if (url.pathname === "/mcp") {
       const sessionId = Array.isArray(req.headers["mcp-session-id"]) ? req.headers["mcp-session-id"][0] : req.headers["mcp-session-id"];

package/README.md

@@ -55,11 +55,25 @@ dsh plugin --profile web add @ifrankwang/openspec-agents
 
 ### OpenCode
 
+要求 OpenCode 2.x（1.x 的插件接口不兼容，本插件只支持 2.x）。
+
 ```bash
 npm install -D @ifrankwang/openspec-agents
 ```
 
-然后在 OpenCode 配置中加载 `@ifrankwang/openspec-agents` 插件，重启 OpenCode。
+然后在 OpenCode 配置的 `plugins` 中登记 `@ifrankwang/openspec-agents`，重启 OpenCode：
+
+```jsonc
+// opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["@ifrankwang/openspec-agents"]
+}
+```
+
+首次加载时，插件会在项目 `.opencode/agents/` 下生成三个子代理定义文件
+（`openspec-main` / `openspec-developer` / `openspec-reviewer`）。这些文件带
+`generated-by` 标记：插件升级后随版本刷新，你手工改过的同名文件不会被覆盖。
 
 ## 让 AI 帮你接入（一句话）
 

package/assets/skills/openspec-standard/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: openspec-standard
-description: OpenSpec 提案标准初始化与升级——把标准版提案规则（openspec/config.yaml + spec-driven-standard schema 全套）安装到当前项目，统一后续提 change 的质量门槛（关联场景清点、契约变更详列、人话实施逻辑、结构化方案摘要、动笔前访谈与用户确认）。当用户要求初始化、升级或标准化 openspec 提案标准/提案规范时使用。
+description: OpenSpec 提案标准初始化与升级——把标准版提案规则（openspec/config.yaml + spec-driven-standard schema 全套）安装到当前项目，统一后续提 change 的质量门槛（关联场景清点、契约变更详列、人话变更清单与实施逻辑、结构化方案摘要、动笔前访谈与用户确认）。当用户要求初始化、升级或标准化 openspec 提案标准/提案规范时使用。
 capabilities: ["openspec-standard"]
 ---
 
 ## 职责
 
-把本 skill 目录 `templates/` 下的标准文件安装到当前项目的 `openspec/` 目录，使该项目此后用 openspec 提 change 时自动遵循统一标准：关联场景清点（共享处理逻辑的变更须与其全部消费入口同一 change 统一适配，同一数据多条落库路径的校验一致性为访谈必问分支）、契约变更详列、实施逻辑人话分步（proposal 单列实施逻辑小节，禁代码级名词）、结构化方案摘要（访谈穷尽后才给出、以普通消息确认）、动笔前访谈门与用户确认门、任务组实质变更主体等。幂等：重跑即把标准升级到插件当前版本，项目自定义内容按下方合并策略保留。
+把本 skill 目录 `templates/` 下的标准文件安装到当前项目的 `openspec/` 目录，使该项目此后用 openspec 提 change 时自动遵循统一标准：关联场景清点（共享处理逻辑的变更须与其全部消费入口同一 change 统一适配，同一数据多条落库路径的校验一致性为访谈必问分支）、契约变更详列、实施逻辑人话分步（proposal 单列实施逻辑小节，禁代码级名词）、结构化方案摘要（访谈穷尽后才给出，一句话做什么、变更内容人话逐条列明并禁代码级名词，以普通消息确认）、动笔前访谈门与用户确认门、任务组实质变更主体等。幂等：重跑即把标准升级到插件当前版本，项目自定义内容按下方合并策略保留。
 
 ## 前置检查
 

package/assets/skills/openspec-standard/templates/openspec/config.yaml

@@ -15,7 +15,7 @@ rules:
     - "关联场景清点（强制）：proposal 动笔前必须完成「关联场景清点」并以代码检索为证据记入 clarify.md 的「关联场景清点（Related-Surface Survey）」小节：枚举本变更触及能力的全部消费方与关联面——功能入口（API 端点、导入/导出入口、定时任务、消息消费、前端调用等）、共享处理逻辑（被多个入口复用的处理链路）、数据模型与数据流下游（表/字段/事件/导出产物的读写双方），每条附代码位置证据（文件/类/方法）。凡共享处理逻辑发生变更，其全部消费入口必须在同一 change 内统一适配，禁止按入口分别提 change 导致共享逻辑两边割裂维护；确需拆分时必须在 proposal.md 单列「拆分边界」小节论证（每个 change 覆盖哪些入口、共享逻辑变更归属哪个 change、入口间契约），并经用户确认。proposal.md 必须单列「关联场景（Related Surface）」小节逐条列出清点结论与划界结论；泛写「无关联影响」而不附检索证据视为 proposal 未完成。"
     - "契约变更详列（强制）：凡变更涉及 DDL（建表/加列/索引/约束）或接口契约（新增/修改端点、请求响应结构、错误码），proposal.md 必须单列「契约变更点」小节逐条列出——DDL 逐表逐列给全表名、列名、类型、可空性、默认值与用途；API 逐端点给全方法+路径、请求/响应结构变化、新增/修改标记与兼容性影响。泛写「有契约变更」不逐条展开视为 proposal 未完成。"
     - "动笔前访谈门（强制）：proposal/specs/design/tasks 任一文档动笔前，必须已按 spec-driven-standard schema clarify 指令的决策树访谈方法论完成对用户的访谈——把方案建模为决策树逐轮穷尽疑点：每轮将前提已落定、当前可回答的问题一次性编号抛出并逐题附推荐答案，用户答复后重算下一轮前沿，直到决策树所有分支走完、无未决疑点、无静默假设、关联场景清点每个条目均经用户划界确认（纳入/排除+理由）；访谈问答全程记入 clarify.md（Open Questions / User Answers / 关联场景清点）。事实类问题必须自行查代码与 spec 求证，不抛给用户；疑点未穷尽时禁止写任何文档，不得以「需求简单」等理由跳过。访谈未穷尽（含关联场景清点尚有未经用户划界确认的条目）时同样禁止呈现方案或方案摘要请求确认——轮次中每题附的推荐答案不视为方案，不得把方案确认合并进任何一轮提问；用户中途索要方案时说明访谈未完并继续提问，不得提前收口。"
-    - "实施逻辑与方案摘要结构（强制）：proposal.md 必须单列「实施逻辑（Implementation Outline）」小节，按步骤用业务语言（人话）讲清具体怎么做——数据从哪来、经过什么校验与处理、落到哪、关联场景小节划入的每条链路怎么适配；禁止出现类名/方法名/内部函数名等代码级名词（用户明确要求技术深度时除外；契约变更点小节的表名/列名/端点路径等契约事实不受此限、保持精确）。方案摘要必须按 spec-driven-standard schema clarify 指令 Plan confirmation gate 的要素清单结构化逐项展开（含人话分步实施逻辑与关联链路划界结论），两三句话的摘要视为未完成。"
+    - "实施逻辑与方案摘要结构（强制）：proposal.md 必须单列「实施逻辑（Implementation Outline）」小节，按步骤用业务语言（人话）讲清具体怎么做——数据从哪来、经过什么校验与处理、落到哪、关联场景小节划入的每条链路怎么适配；禁止出现类名/方法名/内部函数名等代码级名词（用户明确要求技术深度时除外；契约变更点小节的表名/列名/端点路径等契约事实不受此限、保持精确）。方案摘要必须按 spec-driven-standard schema clarify 指令 Plan confirmation gate 的要素清单结构化逐项展开——先用一句话说明本次变更做什么，变更内容再用自然语言（人话）逐条列出，每条形如「导出功能新增「状态」字段」并视需要展开必要背景（如该字段的来源、用途），禁止掺杂类名/方法名等代码级名词（限制口径同实施逻辑小节）；摘要含人话分步实施逻辑与关联链路划界结论，两三句话的摘要视为未完成。"
     - "动笔前用户确认门（强制）：proposal/specs/design/tasks 任一文档动笔前，clarify.md 的 Architecture Direction 必须已记录用户对方案摘要的明确确认；确认必须以普通消息直接列出方案摘要要素点（要素清单见 spec-driven-standard schema clarify 指令的 Plan confirmation gate）并停下等待用户直接文字回复，禁止通过提问工具发起确认，提问工具的选项点击不视为确认；未记录时禁止写任何文档——主代理亲自写时先停下向用户补确认，生成子代理则立即终止并向编排方报告，不得以「需求简单」等理由跳过或代用户确认。"
   specs:
     - "数据行为需求（如\"系统 SHALL 持久化 X 含审计字段\"）放 spec；物理 DDL 放 design.md。"

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/README.md

@@ -8,9 +8,10 @@
    change 统一适配或排除附理由；同一数据存在多条落库路径时各路径校验与
    处理逻辑的一致性为必问分支；共享处理逻辑变更须与其全部消费入口同一
    change 统一适配）；访谈穷尽后、写任何文档之前，主代理必须先向用户汇报
-   结构化方案摘要（按要素清单逐项编号展开：一句话做什么 + 是否动契约 +
-   选定方案与备选取舍 + 人话分步实施逻辑 + 关联链路划界结论 + 影响的能力
-   面）并取得用户明确确认（HARD-GATE：摘要须以普通消息呈现，禁止用提问
+   结构化方案摘要（按要素清单逐项编号展开：一句话做什么 + 变更内容人话
+   逐条列明（形如「导出功能新增「状态」字段」，视需要说明字段来源等
+   背景）+ 是否动契约 + 选定方案与备选取舍 + 人话分步实施逻辑 +
+   关联链路划界结论 + 影响的能力面）并取得用户明确确认（HARD-GATE：摘要须以普通消息呈现，禁止用提问
    工具发起确认，访谈中的问答不视为确认；访谈未穷尽禁止呈现方案求确认，
    轮次中每题附的推荐答案不视为方案），确认记录落在 clarify.md，后续文档
    不得偏离。proposal.md 单列「实施逻辑」小节，以人话分步讲清怎么做（禁

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/schema.yaml

@@ -165,7 +165,14 @@ artifacts:
         number each element below and give it real substance — a
         two-or-three-sentence blob is an invalid summary, expand it before
         presenting. The elements:
-        1. what the change does, in one sentence;
+        1. what the change does, in one sentence, THEN the change
+           contents itemized one item per line in plain business
+           language: each item is a natural-language sentence of the
+           form 「导出功能新增「状态」字段」, expanded as far as it helps
+           the user judge the change (e.g. where the new field comes
+           from, what it gives the user) rather than a bare label. No
+           code-level identifiers — same language rule as element 4
+           below;
         2. whether it touches contracts (API parameters or DDL);
         3. the chosen approach and its key trade-offs versus the
            alternatives;
@@ -204,8 +211,9 @@ artifacts:
         alternatives considered, and the confirmed plan summary with
         the user's explicit confirmation — the summary structured per the
         six elements of the plan confirmation gate (including the
-        plain-language implementation outline and the related-surface
-        verdicts), presented as a plain message only after the interview
+        itemized plain-language change list, the plain-language
+        implementation outline and the related-surface verdicts),
+        presented as a plain message only after the interview
         was exhausted. This is the HARD-GATE output.
       - **Initial Capabilities**: preliminary guess of which specs will be touched
         (kebab-case). Finalized in proposal.md.

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/templates/clarify.md

@@ -37,7 +37,8 @@
      considered with tradeoffs, and the plan summary the user explicitly confirmed
      (interview answers alone do not count as confirmation; the summary must be
      structured per the six elements of the plan confirmation gate — including
-     the plain-language implementation outline and the related-surface verdicts —
+     the itemized plain-language change list, the plain-language
+     implementation outline and the related-surface verdicts —
      presented as a plain message listing the key points, never a question-tool
      prompt, and only AFTER the interview was exhausted: presenting the plan or
      asking for its confirmation mid-interview is forbidden, and the recommended

package/dsh/cordis.patch.yml

@@ -25,6 +25,47 @@
         includeDefaultRoots: false
         customSkillDirs:
           - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('./node_modules/@ifrankwang/openspec-agents/assets/skills', baseUrl))"
+    - id: openspec-subagent-developer
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: openspec_developer
+        persona: |-
+          ## DSH 工具接入（必读）
+
+          - 本流程的 opx_* 工具在 DSH 中以 `mcp__opx__*` 形式出现，子代理通常只需要：
+            - `mcp__opx__status`
+            - `mcp__opx__agent_submit`
+          - 如果当前工具列表中没有这些工具，请立即调用 `dev_tool_search` 搜索 `opx`，或一次性解锁：
+            ```json
+            {"toolNames": ["mcp__opx__status", "mcp__opx__agent_submit"]}
+            ```
+            如果计划使用 `todo_write` 跟踪任务，也请在同一轮一并解锁。
+          - 严禁使用 `find` / `which` / `grep` 等 shell 命令搜索 `opx`、`openspec`、MCP 配置或安装路径；工具未出现是因为尚未解锁，不是未安装。
+          - 解锁后第一件事是调用 `mcp__opx__status` 获取上下文，不要先探查仓库或读取状态文件。
+
+
+          OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者逻辑身份）。遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
+
+          ## 角色（开发者身份）
+
+          你是后端开发工程师，专注于实现 OpenSpec 任务组中的代码开发任务，同时是质量门与接口测试的执行责任人：确定性检查与接口测试由你执行并经自检申报留痕，自检申报是 reviewer 分级复验的事实输入。
+
+          提交前按已加载 skill（含质量维度规范类）完成自检，审查兜底与终局裁定仍由对应 reviewer 承担（自检不替代 reviewer 裁定）。
+
+          自证/验证启动的服务与基础设施一律隔离启动、用后即停，自证完成即清理，不留残留。隔离对象不限于数据库（mock 服务、消息队列/缓存等中间件、扫描分析平台均按隔离标识隔离）。
+
+          任务执行与提交约束（Task/Issue 清单处理、环境问题处置、blocker 提交、文档读取范围、工具调用边界）以 opx_status 操作指引与约束区块为准，此处不重复描述。
+
+          修复的 issue 进入待复核，终态由提出者（对应 reviewer）裁定；被驳回后按修复未过次数门槛处理。
+
+          收尾阶段承担基准分支同步、合并冲突解决、回归复验与隔离环境清理职责；收尾验证中自报 issue 由自己复核收敛（区别于「修复的 issue 进入待复核，终态由提出者裁定」的常规路径）。
+
+          ## 压制处理（开发者身份）
+
+          确定性质量工具检查出的问题若以压制手段解决（压制注解、注释抑制、规则排除配置、平台状态标注、构建跳过开关等），属豁免申请范畴：必须在压制处代码注释说明清楚理由（commit message 可补充），交由报源审查者判定合理性；不得以压制手段冒充修复。豁免被驳回后，须移除压制并真实修复。
+        enableRunInBackground: false
+        backgroundMode: one-shot
     - id: openspec-subagent-reviewer
       name: '@deepseek-ai/dsh-tool-subagent'
       config:
@@ -241,45 +282,4 @@
           确定性质量工具检查出的问题若以压制手段解决（压制注解、注释抑制、规则排除配置、平台状态标注、构建跳过开关等），一律视为豁免申请，须判定其合理性：可接受情形（无法消除的框架/第三方限制、有证据的误报，且风险可控、理由充分）→ 认可豁免；不可接受情形（真实缺陷被压制规避、仅图省事、无理由或理由不成立）→ 不认可，须要求移除压制并真实修复。判定时核验压制处的理由（代码注释、commit message）；不认可时须给出可见的判定理由（写入问题描述/建议或驳回说明）。此判定适用于承担工具检查的审查身份（工具审查者、simple 合并审查者）。
         enableRunInBackground: false
         backgroundMode: one-shot
-    - id: openspec-subagent-developer
-      name: '@deepseek-ai/dsh-tool-subagent'
-      config:
-        provider: spawn
-        toolName: openspec_developer
-        persona: |-
-          ## DSH 工具接入（必读）
-
-          - 本流程的 opx_* 工具在 DSH 中以 `mcp__opx__*` 形式出现，子代理通常只需要：
-            - `mcp__opx__status`
-            - `mcp__opx__agent_submit`
-          - 如果当前工具列表中没有这些工具，请立即调用 `dev_tool_search` 搜索 `opx`，或一次性解锁：
-            ```json
-            {"toolNames": ["mcp__opx__status", "mcp__opx__agent_submit"]}
-            ```
-            如果计划使用 `todo_write` 跟踪任务，也请在同一轮一并解锁。
-          - 严禁使用 `find` / `which` / `grep` 等 shell 命令搜索 `opx`、`openspec`、MCP 配置或安装路径；工具未出现是因为尚未解锁，不是未安装。
-          - 解锁后第一件事是调用 `mcp__opx__status` 获取上下文，不要先探查仓库或读取状态文件。
-
-
-          OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者逻辑身份）。遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
-
-          ## 角色（开发者身份）
-
-          你是后端开发工程师，专注于实现 OpenSpec 任务组中的代码开发任务，同时是质量门与接口测试的执行责任人：确定性检查与接口测试由你执行并经自检申报留痕，自检申报是 reviewer 分级复验的事实输入。
-
-          提交前按已加载 skill（含质量维度规范类）完成自检，审查兜底与终局裁定仍由对应 reviewer 承担（自检不替代 reviewer 裁定）。
-
-          自证/验证启动的服务与基础设施一律隔离启动、用后即停，自证完成即清理，不留残留。隔离对象不限于数据库（mock 服务、消息队列/缓存等中间件、扫描分析平台均按隔离标识隔离）。
-
-          任务执行与提交约束（Task/Issue 清单处理、环境问题处置、blocker 提交、文档读取范围、工具调用边界）以 opx_status 操作指引与约束区块为准，此处不重复描述。
-
-          修复的 issue 进入待复核，终态由提出者（对应 reviewer）裁定；被驳回后按修复未过次数门槛处理。
-
-          收尾阶段承担基准分支同步、合并冲突解决、回归复验与隔离环境清理职责；收尾验证中自报 issue 由自己复核收敛（区别于「修复的 issue 进入待复核，终态由提出者裁定」的常规路径）。
-
-          ## 压制处理（开发者身份）
-
-          确定性质量工具检查出的问题若以压制手段解决（压制注解、注释抑制、规则排除配置、平台状态标注、构建跳过开关等），属豁免申请范畴：必须在压制处代码注释说明清楚理由（commit message 可补充），交由报源审查者判定合理性；不得以压制手段冒充修复。豁免被驳回后，须移除压制并真实修复。
-        enableRunInBackground: false
-        backgroundMode: one-shot
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.142.0",
+  "version": "0.144.0",
   "description": "OpenSpec change orchestration plugin for AI coding agents (Claude Code, Codex, ZCode, DeepSeek Harness, OpenCode)",
   "author": "ifrankwang",
   "license": "MIT",
@@ -75,14 +75,14 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
+    "@opencode/plugin": "^2.0.26",
     "@types/bun": "^1.3.0",
     "@types/js-yaml": "^4.0.9",
     "typescript": "^5.9.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "js-yaml": "^4.1.0",
-    "@opencode-ai/plugin": "^1.17.0"
+    "js-yaml": "^4.1.0"
   },
   "dsh": {
     "bundle": {

package/src/adapters/opencode/agents.ts

@@ -1,61 +1,71 @@
-import { readFileSync, existsSync, readdirSync } from "node:fs"
+/**
+ * 子代理定义投放：assets/agents/*.md 转成 OpenCode V2 原生 agent 文件，写入目标项目
+ * `.opencode/agents/<名>.md`——V2 发现项目级 agent 的位置。
+ *
+ * V2 插件接口的 agent 编辑器只提供 update/remove，没有新增能力，而 V2 也不从插件包目录发现
+ * agent，因此新增子代理只能走文件投放，与 codex 适配器把 agent 写进目标仓库 `.codex/agents/`
+ * 的做法同构。
+ *
+ * frontmatter 按 V2 字段落地：mode/steps/hidden 沿用同名，permission 对象展开为 permissions
+ * 有序数组（见 permissions.ts）。文件正文首行带生成标记：已存在且带标记的文件随插件版本刷新，
+ * 用户手工改写过的同名文件保留不动。
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs"
 import { join } from "node:path"
-import type { AgentConfig } from "@opencode-ai/sdk"
+import * as yaml from "js-yaml"
 import { parseAgentMd, resolve } from "../agent-md.ts"
-
-function mapPermission(
-  fm: Record<string, unknown>
-): AgentConfig["permission"] | undefined {
-  const raw = fm.permission as Record<string, unknown> | undefined
-  if (!raw) return undefined
-  const permission: AgentConfig["permission"] = {}
-  for (const [key, val] of Object.entries(raw)) {
-    if (typeof val === "string" && ["ask", "allow", "deny"].includes(val)) {
-      ;(permission as any)[key] = val
-    } else if (typeof val === "object" && val !== null) {
-      ;(permission as any)[key] = val
-    }
-  }
-  return permission
-}
+import { toV2Permissions } from "./permissions.ts"
 
 const AGENTS_ROOT = resolve("assets", "agents")
 
-export function injectAgents(config: Record<string, unknown>): void {
-  if (existsSync(AGENTS_ROOT)) {
-    const files = readdirSync(AGENTS_ROOT).filter((f) => f.endsWith(".md"))
-    for (const file of files) {
-      const md = readFileSync(join(AGENTS_ROOT, file), "utf-8")
-      const { frontmatter, body } = parseAgentMd(md)
-      const name = pathToName(file) ?? (frontmatter.name as string)
-      if (!name) continue
+/** 生成标记：正文首行。用于识别「本文件由插件生成、允许随版本刷新」。 */
+const GENERATED_MARKER = "<!-- generated-by: openspec-agents -->"
 
-      const agentConfig: Record<string, unknown> = {
-        description: frontmatter.description ?? "",
-        mode: frontmatter.mode ?? "subagent",
-        prompt: body,
-      }
-      if (frontmatter.hidden !== undefined) {
-        agentConfig.hidden = frontmatter.hidden
-      }
-      const maxSteps = (frontmatter.maxSteps ?? frontmatter.steps) as number | undefined
-      if (maxSteps !== undefined) {
-        agentConfig.maxSteps = maxSteps
-      }
-      const perm = mapPermission(frontmatter)
-      if (perm) agentConfig.permission = perm
+/** 项目内 agent 投放目录（V2 发现位置）。 */
+export function agentsTargetDir(projectRoot: string): string {
+  return join(projectRoot, ".opencode", "agents")
+}
 
-      const existingAgentsMap = (config.agent as Record<string, unknown>) ?? {}
-      const existingAgent = existingAgentsMap[name] as Record<string, unknown> | undefined
-      config.agent = {
-        ...existingAgentsMap,
-        [name]: { ...agentConfig, ...existingAgent },
-      }
-    }
+/**
+ * 把随包分发的子代理写入目标项目，返回本次实际写入的 agent 名列表。
+ * assets/agents 缺失（分发形态裁剪）时返回空列表，不阻断插件启动。
+ */
+export function writeAgents(projectRoot: string): string[] {
+  const written: string[] = []
+  if (!existsSync(AGENTS_ROOT)) return written
+  const targetDir = agentsTargetDir(projectRoot)
+  for (const file of readdirSync(AGENTS_ROOT)) {
+    if (!file.endsWith(".md")) continue
+    const { frontmatter, body } = parseAgentMd(readFileSync(join(AGENTS_ROOT, file), "utf-8"))
+    const name = (frontmatter.name as string) ?? file.replace(/\.md$/, "")
+    if (!name) continue
+    const target = join(targetDir, `${name}.md`)
+    if (!isOverwritable(target)) continue
+    mkdirSync(targetDir, { recursive: true })
+    writeFileSync(target, renderAgentFile(frontmatter, body), "utf-8")
+    written.push(name)
   }
+  return written
 }
 
-function pathToName(filename: string): string | null {
-  const base = filename.replace(/\.md$/i, "")
-  return base || null
+/** 未投放过、或上次由本插件生成的文件可覆盖；用户手工维护的文件一律保留。 */
+function isOverwritable(target: string): boolean {
+  if (!existsSync(target)) return true
+  try {
+    return readFileSync(target, "utf-8").includes(GENERATED_MARKER)
+  } catch {
+    return false
+  }
 }
+
+function renderAgentFile(fm: Record<string, unknown>, body: string): string {
+  const frontmatter: Record<string, unknown> = {}
+  if (fm.description !== undefined) frontmatter.description = fm.description
+  if (fm.mode !== undefined) frontmatter.mode = fm.mode
+  if (fm.hidden !== undefined) frontmatter.hidden = fm.hidden
+  const steps = (fm.steps ?? fm.maxSteps) as number | undefined
+  if (steps !== undefined) frontmatter.steps = steps
+  const permissions = toV2Permissions(fm.permission)
+  if (permissions.length > 0) frontmatter.permissions = permissions
+  return `---\n${yaml.dump(frontmatter)}---\n\n${GENERATED_MARKER}\n\n${body.trim()}\n`
+}

package/src/adapters/opencode/index.ts

@@ -1,41 +1,63 @@
-import { type Plugin } from "@opencode-ai/plugin"
-import { injectSkills } from "./skills.ts"
-import { injectAgents } from "./agents.ts"
+import type { Plugin } from "@opencode/plugin"
 import { resolve } from "../agent-md.ts"
+import { collectSkills, type SkillRegistration } from "./skills.ts"
+import { writeAgents } from "./agents.ts"
 
 /**
- * OpenCode 插件壳（MCP 形态）：配置注入（agent/skill）+ MCP server 配置注入（config.mcp）。
- * 直载工具注册已移除（BREAKING，change agent-merge-and-mode-config 组 5.1）：
- * - opx_* 工具统一经 MCP server 暴露（stdio bundle，--worktree 指向当前项目根），
- *   与 claude-code / zcode / codex 插件的 .mcp.json 形态一致；
- * - 身份不再由会话运行时推导，统一走 mcp-common 的 `_agent` 参数解析（缺省视为编排视角）。
- * dashboard/collector/poller 副作用已迁移至 MCP server 进程（src/adapters/mcp-common/）。
+ * OpenCode V2 插件壳：MCP server 注册 + skill 注册 + 子代理文件投放。
+ *
+ * V2 插件以默认导出 { id, setup } 生效，setup 内按域注册，不再持有全局配置对象：
+ * - MCP server 走 mcp 域 transform 声明（local + stdio command 数组），opx_* 工具由此暴露，
+ *   身份统一由 mcp-common 的 `_agent` 参数解析（缺省视为编排视角）；
+ * - 随包 skill 走 skill 域 transform 逐项注册，path 指向包内 SKILL.md 以保留附属文件基准；
+ * - 子代理以文件形式投放至项目 `.opencode/agents/`（V2 插件接口无新增 agent 的能力）。
+ *
+ * dashboard/collector/poller 副作用由 MCP server 进程承担（src/adapters/mcp-common/），
+ * 插件壳不启动任何后台任务。
+ *
+ * 插件 ID 稳定为 openspec-agents：V2 以该 ID 标识插件、隔离其持久化存储，并用于配置中的
+ * 启用/禁用前缀匹配。
  */
-export const OpenspecOrchestratePlugin: Plugin = async (input) => {
+export const OPENCODE_PLUGIN_ID = "openspec-agents"
+
+/**
+ * 构造 opx MCP server 配置。入口为包内 .mcp-server/cli.mjs（prepack 构建的自包含 bundle），
+ * --worktree 指向当前加载本插件的项目根（ctx.location.directory），dashboard/collector 副作用
+ * 与状态读写均以此为根。
+ */
+function mcpServerConfig(projectRoot: string) {
   return {
-    config: async (config) => {
-      injectAgents(config)
-      injectSkills(config)
-      // MCP server 声明：opencode config 的 mcp 段（官方形态
-      // { mcp: { <server>: { type: "local", command: [...] } } }，见 opencode docs/mcp-servers）。
-      // 入口为包内 .mcp-server/cli.mjs（prepack 构建的 MCP server 自包含 bundle），
-      // --worktree 指向当前项目根（input.worktree 即 opencode 打开的 git worktree 路径）。
-      config.mcp = {
-        ...(config.mcp ?? {}),
-        opx: {
-          type: "local",
-          command: [
-            "node",
-            resolve(".mcp-server", "cli.mjs"),
-            "--transport",
-            "stdio",
-            "--worktree",
-            input.worktree,
-            "--unattended",
-            "--strip-opx-prefix",
-          ],
-        },
-      }
-    },
+    type: "local" as const,
+    command: [
+      "node",
+      resolve(".mcp-server", "cli.mjs"),
+      "--transport",
+      "stdio",
+      "--worktree",
+      projectRoot,
+      "--unattended",
+      "--strip-opx-prefix",
+    ],
   }
 }
+
+const plugin: Plugin.Plugin = {
+  id: OPENCODE_PLUGIN_ID,
+  async setup(ctx) {
+    const projectRoot = ctx.location.directory
+
+    await ctx.mcp.transform((editor) => {
+      editor.set("opx", mcpServerConfig(projectRoot))
+    })
+
+    await ctx.skill.transform((editor) => {
+      for (const skill of collectSkills()) {
+        editor.add(skill)
+      }
+    })
+
+    writeAgents(projectRoot)
+  },
+}
+
+export default plugin

package/src/adapters/opencode/skills.ts

@@ -1,19 +1,57 @@
-import { existsSync } from "node:fs"
+/**
+ * skill 投放：收集随包分发的 skill，交由 V2 skill 域的 transform 逐个注册。
+ *
+ * V1 形态把 skill 根目录追加进 config.skills.paths，由 opencode 自行发现；V2 插件不持有全局
+ * 配置对象，skill 改由 skill 域显式注册。注册项的 path 指向包内 SKILL.md，使 skill 加载时
+ * 仍以该目录为附属文件（reference/、scripts/ 等）的相对引用基准。
+ *
+ * ID 取目录名（V2 以路径派生 ID 为准），name/description 取 SKILL.md frontmatter，
+ * content 取去 frontmatter 的正文——与 V2 加载时「加入去掉 frontmatter 的正文」一致。
+ */
+import { readFileSync, existsSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import type { Skill } from "@opencode/plugin"
+import { parseAgentMd } from "../agent-md.ts"
 import { DISTRIBUTED_SKILL_ROOTS } from "../../skills/scan.ts"
 
-export function injectSkills(config: Record<string, unknown>): void {
-  const skillsCfg = (config.skills ?? {}) as Record<string, unknown>
-  const paths = (skillsCfg.paths ?? []) as string[]
+/**
+ * 注册一项 skill 所需的字段（对齐 V2 Skill.Info 中由插件负责提供的部分）。
+ * id/name/path 在 V2 schema 中为品牌化字符串（编译期约束，运行时即普通 string），
+ * 构造处统一以断言完成品牌化，避免引入 @opencode/plugin 的运行时依赖
+ * （Plugin.define 为恒等函数，插件壳不需要该包的运行时实例）。
+ */
+export interface SkillRegistration {
+  id: Skill.Info["id"]
+  name: Skill.Info["name"]
+  description?: string
+  path: Skill.Info["path"]
+  content: string
+}
 
+/** 收集随包分发的全部 skill；随包 skill 缺失（分发形态裁剪）时返回空数组。 */
+export function collectSkills(): SkillRegistration[] {
+  const out: SkillRegistration[] = []
+  const seen = new Set<string>()
   for (const root of DISTRIBUTED_SKILL_ROOTS) {
     if (!existsSync(root)) continue
-    if (!paths.includes(root)) {
-      paths.push(root)
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const skillFile = join(root, entry.name, "SKILL.md")
+      if (!existsSync(skillFile)) continue
+      // 多根场景下同名 skill 只注册一次（V2 按 ID 选择，后注册者覆盖前者）。
+      if (seen.has(entry.name)) continue
+      seen.add(entry.name)
+      const { frontmatter, body } = parseAgentMd(readFileSync(skillFile, "utf-8"))
+      // id 由目录名派生（V2 以路径派生 ID 为准），name 为展示名，缺失时回落 id。
+      const name = (frontmatter.name as string) ?? entry.name
+      out.push({
+        id: entry.name as Skill.Info["id"],
+        name: name as Skill.Info["name"],
+        description: frontmatter.description as string | undefined,
+        path: skillFile as Skill.Info["path"],
+        content: body,
+      })
     }
   }
-
-  if (paths.length > 0) {
-    skillsCfg.paths = paths
-    config.skills = skillsCfg
-  }
-}
+  return out
+}

package/src/index.ts

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