@ifrankwang/openspec-agents 0.118.0

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

@@ -0,0 +1,157 @@
+/**
+ * 通用 MCP Server 承载层：6 个 opx_* 工具由 agent 无关的 MCP Server（HTTP transport）承载，
+ * 参数采用 P1 纯 JSON Schema。任意支持 MCP client 的 agent（opencode / claude code / codex / zcode）
+ * 均可发现与调用同一套工具。
+ *
+ * 身份约定（适配层职责，不污染 P1 契约）：
+ * - 每个工具在 P1 schema 基础上附加可选 `_agent` 参数：子代理调用时传自身角色名
+ *   （如 openspec-reviewer-tool），主代理调用缺省即编排视角（orchestrator: true）；
+ * - `_agent` 缺省/为空视为编排主代理视角。
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import type { JSONSchema } from "../../core/provider.ts"
+import type { ToolContext } from "../../core/tools/types.ts"
+import {
+  initExecute, setWorktreeExecute, statusExecute,
+  completeTaskGroupExecute, setUnattendedExecute,
+} from "../../core/tools/lifecycle.ts"
+import { agentSubmitExecute } from "../../core/tools/submit.ts"
+import {
+  orchInitSchema, setWorktreeSchema, statusSchema,
+  completeTaskGroupSchema, setUnattendedSchema, agentSubmitSchema,
+} from "../../core/tools/schemas.ts"
+import { readStateByWorktree, writeState } from "../../core/state.ts"
+import { jsonSchemaToZod } from "./json-schema.ts"
+
+/** 私有身份参数：附加到每个工具的 MCP 暴露 schema（下划线前缀表示非业务参数）。 */
+const AGENT_ARG = "_agent"
+
+interface ToolSpec {
+  description: string
+  schema: JSONSchema
+  execute(args: Record<string, unknown>, ctx: ToolContext): Promise<string>
+}
+
+const TOOL_SPECS: Record<string, ToolSpec> = {
+  opx_orch_init: {
+    description:
+      "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。",
+    schema: orchInitSchema,
+    execute: (args, ctx) => initExecute(args as any, ctx),
+  },
+  opx_orch_set_worktree: {
+    description:
+      "确保目标组的 git worktree 就绪。若已存在则复用，否则按规范自动创建（分支 task-group/{changeId}/{taskGroupId}，路径 .worktree/{changeId}/task-group-{taskGroupId}）。只补齐资源，不改变阶段。",
+    schema: setWorktreeSchema,
+    execute: (args, ctx) => setWorktreeExecute(args as any, ctx),
+  },
+  opx_status: {
+    description:
+      "统一状态/上下文查询（只读为主）。按调用者角色路由：编排视角→统计+worktree；architect→spec/blocker；developer→worktree/boundary/task/issue；reviewer-tool→tool 层控件 issue；reviewer-task→task 验证状态；quality reviewer→自维度既有 issue。",
+    schema: statusSchema,
+    execute: (args, ctx) => statusExecute({ change_id: (args as any).change_id }, ctx),
+  },
+  opx_orch_complete_task_group: {
+    description:
+      "完成任务组收尾：合并 task-group 分支到 baseBranch → 清理 worktree 与分支。须在收尾验证（verify_cleanup）通过后调用。合并冲突时中止并返回 blocked（保留 worktree/分支）。",
+    schema: completeTaskGroupSchema,
+    execute: (args, ctx) => completeTaskGroupExecute(args as any, ctx),
+  },
+  opx_orch_set_unattended: {
+    description:
+      "开启/关闭无人值守模式。开启后编排流程不再向用户提问：analyze 确认模式由架构师自行裁决（不确认用户）；重试检查点、状态异常、blocker 处理等需拍板事项由主代理按编排行为准则自行决策并提交——检查点决策是 opx_agent_submit 工具调用，主代理可自行执行，不因无人值守而抑制。",
+    schema: setUnattendedSchema,
+    execute: (args, ctx) => setUnattendedExecute(args as any, ctx),
+  },
+  opx_agent_submit: {
+    description:
+      "通用 step 提交，按 step_id 路由到 workflow 对应 step。校验调用者属于该 step 的 agents（越权直接拒绝），提交后推进 workflow 状态机并写回编排状态。可通过 exempt_adjudications 对已申请豁免的 issue 进行裁定（dismissed→cancelled、rejected→回 todo）；可通过 recheck_adjudications 复核已修复待复核（review 态）的 issue（passed→done、rejected→回 todo 并记 refix_count 与 reject_reason，谁提谁裁定）。",
+    schema: agentSubmitSchema,
+    execute: (args, ctx) => agentSubmitExecute(args as any, ctx),
+  },
+}
+
+/** 附加 _agent 身份参数到 P1 schema（仅 MCP 暴露层；OpenCode 直载形态无此参数）。 */
+function withAgentArg(schema: JSONSchema): JSONSchema {
+  return {
+    ...schema,
+    properties: {
+      ...(schema.properties ?? {}),
+      [AGENT_ARG]: {
+        type: "string",
+        description: "调用者 agent 标识（子代理调用时传自身角色名，如 openspec-reviewer-tool；缺省为编排主代理视角）",
+      },
+    },
+    required: schema.required ?? [],
+  }
+}
+
+/** 解析调用上下文：_agent 缺省/空 → 编排主代理视角（orchestrator: true）。 */
+function resolveContext(args: Record<string, unknown>, worktree: string): ToolContext {
+  const declared = typeof args[AGENT_ARG] === "string" && args[AGENT_ARG] !== ""
+  const agent = declared ? (args[AGENT_ARG] as string) : "primary"
+  return { worktree, agent, orchestrator: agent === "primary", identityDeclared: declared }
+}
+
+/**
+ * 默认无人值守：server 启动时声明（claude code / codex / zcode 适配器分发），
+ * 会话已初始化（有 changeId 与状态）且 state.unattended 未设置时自动置 true。
+ * 幂等：已设置过则跳过，不覆盖用户显式关闭的会话。
+ */
+async function ensureDefaultUnattended(
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<void> {
+  const changeId = typeof (args as any).change_id === "string" ? (args as any).change_id : undefined
+  if (!changeId) return
+  try {
+    const state = await readStateByWorktree(ctx.worktree, changeId)
+    if (state && state.unattended === undefined) {
+      state.unattended = true
+      await writeState(ctx.worktree, state)
+    }
+  } catch {
+    // 状态不可读/不可写时静默跳过（不阻断工具主流程）
+  }
+}
+
+declare const __OPX_PKG_VERSION__: string | undefined
+/** 版本号单一来源：package.json（发布时仅需改一处）；bundle 形态（ZCode 插件包）由构建期 --define 注入常量，避免运行时读文件。 */
+const PKG_VERSION =
+  typeof __OPX_PKG_VERSION__ === "string"
+    ? __OPX_PKG_VERSION__
+    : (JSON.parse(
+        readFileSync(fileURLToPath(new URL("../../../package.json", import.meta.url)), "utf-8"),
+      ) as { version: string }).version
+
+/** 构建承载 6 个 opx_* 工具的 MCP server。unattended=true 时启用默认无人值守（spec: unattended-default）。 */
+export function buildMcpServer(worktree: string, opts: { unattended?: boolean } = {}): McpServer {
+  const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION })
+  for (const [name, spec] of Object.entries(TOOL_SPECS)) {
+    mcp.registerTool<any, any>(
+      name,
+      {
+        title: name,
+        description: spec.description,
+        inputSchema: jsonSchemaToZod(withAgentArg(spec.schema)),
+      },
+      async (args: any, _extra: any) => {
+        const cleanArgs = { ...(args as Record<string, unknown>) }
+        delete cleanArgs[AGENT_ARG]
+        const ctx = resolveContext(args as Record<string, unknown>, worktree)
+        if (opts.unattended) {
+          // 执行前（存量会话）+ 执行后（opx_orch_init 新建会话）各补一次：幂等，已设置则跳过
+          await ensureDefaultUnattended(cleanArgs, ctx)
+        }
+        const result = await spec.execute(cleanArgs, ctx)
+        if (opts.unattended) {
+          await ensureDefaultUnattended(cleanArgs, ctx)
+        }
+        return { content: [{ type: "text" as const, text: result }] }
+      },
+    )
+  }
+  return mcp
+}

package/src/adapters/opencode/agents.ts

@@ -0,0 +1,80 @@
+import { readFileSync, existsSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import type { AgentConfig } from "@opencode-ai/sdk"
+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
+}
+
+const AGENTS_ROOT = resolve("assets", "agents")
+
+/** 已知主代理名集合：注入的 openspec-main + 用户既有 primary agent + opencode 默认主代理 "primary"。 */
+const primaryAgents = new Set<string>(["primary"])
+
+/** 编排视角角色判定：调用者是否为主代理（承担编排者职责），替代 agent 名硬编码。 */
+export function isPrimaryAgent(agent: string): boolean {
+  return primaryAgents.has(agent)
+}
+
+export function injectAgents(config: Record<string, unknown>): void {
+  // 探测主代理名：config.agent 中 mode=primary 的条目（用户自定义 + 注入的主代理模板）
+  const existingAgents = (config.agent as Record<string, unknown>) ?? {}
+  for (const [name, cfg] of Object.entries(existingAgents)) {
+    if (typeof cfg === "object" && cfg !== null && (cfg as Record<string, unknown>).mode === "primary") {
+      primaryAgents.add(name)
+    }
+  }
+  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 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
+
+      if (frontmatter.mode === "primary") {
+        primaryAgents.add(name)
+      }
+
+      const existingAgentsMap = (config.agent as Record<string, unknown>) ?? {}
+      const existingAgent = existingAgentsMap[name] as Record<string, unknown> | undefined
+      config.agent = {
+        ...existingAgentsMap,
+        [name]: { ...agentConfig, ...existingAgent },
+      }
+    }
+  }
+}
+
+function pathToName(filename: string): string | null {
+  const base = filename.replace(/\.md$/i, "")
+  return base || null
+}

package/src/adapters/opencode/dashboard.ts

@@ -0,0 +1,64 @@
+import { createServer } from "node:http"
+import type { Server } from "node:http"
+import { readDashboardState } from "../../core/dashboard.ts"
+import { getDashboardPage } from "../../dashboard/page.ts"
+
+const BASE_PORT = 4519
+const MAX_ATTEMPTS = 20
+
+const servers = new Map<string, Server>()
+
+export async function startDashboard(worktree: string): Promise<void> {
+  if (servers.has(worktree)) return
+
+  const pageHtml = getDashboardPage()
+
+  // 端口占用自动递增：EADDRINUSE 走 server error 事件（异步），经 once("error") + await listen
+  // 判定重试；其余启动期错误仅记录不中断。修复前 try/catch 同步捕获永不触发，换端口失效。
+  for (let port = BASE_PORT; port < BASE_PORT + MAX_ATTEMPTS; port++) {
+    try {
+      const server = createServer(async (req, res) => {
+        try {
+          const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "127.0.0.1"}`)
+          if (url.pathname === "/api/state") {
+            try {
+              const data = await readDashboardState(worktree)
+              res.writeHead(200, { "content-type": "application/json;charset=utf-8" })
+              res.end(JSON.stringify(data ?? { active: false }))
+            } catch (err) {
+              res.writeHead(500, { "content-type": "application/json;charset=utf-8" })
+              res.end(JSON.stringify({ active: false, error: String(err) }))
+            }
+            return
+          }
+          res.writeHead(200, { "content-type": "text/html;charset=utf-8" })
+          res.end(pageHtml)
+        } catch (err) {
+          console.error("[dashboard]", (err as Error).message)
+          res.writeHead(500, { "content-type": "text/plain;charset=utf-8" })
+          res.end("internal error")
+        }
+      })
+      await new Promise<void>((resolve, reject) => {
+        server.once("error", (err: NodeJS.ErrnoException) => {
+          if (err.code === "EADDRINUSE") {
+            reject(err)
+          } else {
+            console.error("[dashboard]", err.message)
+            resolve()
+          }
+        })
+        server.listen(port, "127.0.0.1", () => resolve())
+      })
+      servers.set(worktree, server)
+      console.log(`[dashboard] 编排进度看板 http://127.0.0.1:${port}`)
+      return
+    } catch {
+      continue
+    }
+  }
+
+  console.error(
+    `[dashboard] 无法启动编排进度看板：端口 ${BASE_PORT}-${BASE_PORT + MAX_ATTEMPTS - 1} 均被占用`
+  )
+}

package/src/adapters/opencode/index.ts

@@ -0,0 +1,34 @@
+import { type Plugin } from "@opencode-ai/plugin"
+import { injectSkills } from "./skills.ts"
+import { injectAgents } from "./agents.ts"
+
+import {
+  init,
+  set_worktree,
+  status,
+  complete_task_group,
+  set_unattended,
+  agent_submit,
+} from "./tools.ts"
+
+/**
+ * OpenCode 插件壳（兼容过渡入口）：配置注入（agent/skill）+ 工具直载。
+ * dashboard/collector/poller 副作用已迁移至 MCP server 进程（src/adapters/mcp-common/），
+ * OpenCode 建议切换为 MCP client 形态接入；插件壳保留兼容直到双轨验证完成。
+ */
+export const OpenspecOrchestratePlugin: Plugin = async (input) => {
+  return {
+    config: async (config) => {
+      injectAgents(config)
+      injectSkills(config)
+    },
+    tool: {
+      opx_orch_init: init,
+      opx_orch_set_worktree: set_worktree,
+      opx_status: status,
+      opx_orch_complete_task_group: complete_task_group,
+      opx_orch_set_unattended: set_unattended,
+      opx_agent_submit: agent_submit,
+    },
+  }
+}

package/src/adapters/opencode/json-schema.ts

@@ -0,0 +1,60 @@
+/**
+ * 纯 JSON Schema → zod（OpenCode 链式 schema）转换器。
+ * 适配层专用：工具参数定义以 P1 纯 JSON Schema 为单一事实源（src/core/tools/schemas.ts），
+ * OpenCode 链式 API 仅作为转换目标，工具定义本身不依赖任何 agent 专有 API。
+ */
+import { tool } from "@opencode-ai/plugin"
+import type { JSONSchema } from "../../core/provider.ts"
+
+function convert(schema: JSONSchema): any {
+  switch (schema.type) {
+    case "object": {
+      const shape: Record<string, any> = {}
+      const properties = schema.properties ?? {}
+      for (const [key, sub] of Object.entries(properties)) {
+        const converted = convert(sub)
+        shape[key] = (schema.required ?? []).includes(key) ? converted : tool.schema.optional(converted)
+      }
+      if (Object.keys(shape).length === 0) return tool.schema.object({})
+      return tool.schema.object(shape)
+    }
+    case "array": {
+      const items = schema.items ?? { type: "string" }
+      let arr = tool.schema.array(convert(items))
+      if (typeof schema.minItems === "number" && schema.minItems > 0) arr = arr.min(schema.minItems)
+      return arr
+    }
+    case "string": {
+      if (Array.isArray(schema.enum)) {
+        const values = schema.enum as string[]
+        return values.length === 0 ? tool.schema.string() : tool.schema.enum(values)
+      }
+      let s = tool.schema.string()
+      if (typeof schema.minLength === "number" && schema.minLength > 0) s = s.min(schema.minLength)
+      return s
+    }
+    case "number":
+    case "integer": {
+      let n = schema.type === "integer" ? tool.schema.number().int() : tool.schema.number()
+      if (typeof schema.minimum === "number") n = n.min(schema.minimum)
+      if (typeof schema.maximum === "number") n = n.max(schema.maximum)
+      return n
+    }
+    case "boolean": {
+      let b: any = tool.schema.boolean()
+      if (schema.default !== undefined) b = b.default(schema.default as boolean)
+      return b
+    }
+    case "null":
+      return tool.schema.null()
+    default:
+      return tool.schema.any()
+  }
+}
+
+/** JSON Schema → zod schema（description 注入）。 */
+export function jsonSchemaToZod(schema: JSONSchema): any {
+  const base = convert(schema)
+  if (schema.description) base.describe(schema.description)
+  return base
+}

package/src/adapters/opencode/skills.ts

@@ -0,0 +1,19 @@
+import { existsSync } from "node:fs"
+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[]
+
+  for (const root of DISTRIBUTED_SKILL_ROOTS) {
+    if (!existsSync(root)) continue
+    if (!paths.includes(root)) {
+      paths.push(root)
+    }
+  }
+
+  if (paths.length > 0) {
+    skillsCfg.paths = paths
+    config.skills = skillsCfg
+  }
+}

package/src/adapters/opencode/tools.ts

@@ -0,0 +1,78 @@
+import { tool } from "@opencode-ai/plugin"
+import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS } from "../../core/types.ts"
+import {
+  initExecute, setWorktreeExecute, statusExecute,
+  completeTaskGroupExecute, setUnattendedExecute,
+} from "../../core/tools/lifecycle.ts"
+import { agentSubmitExecute } from "../../core/tools/submit.ts"
+import {
+  orchInitSchema, setWorktreeSchema, statusSchema,
+  completeTaskGroupSchema, setUnattendedSchema, agentSubmitSchema,
+} from "../../core/tools/schemas.ts"
+import { jsonSchemaToZod } from "./json-schema.ts"
+import { isPrimaryAgent } from "./agents.ts"
+import type { ToolContext } from "../../core/tools/types.ts"
+
+/** 直载形态调用上下文：agent 身份由会话运行时推导（恒显式声明），编排视角按主代理名判定。 */
+function makeCtx(context: { worktree: string; agent: string }): ToolContext {
+  return {
+    worktree: context.worktree,
+    agent: context.agent,
+    orchestrator: isPrimaryAgent(context.agent),
+    identityDeclared: true,
+  }
+}
+
+export const init = tool({
+  description:
+    "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。",
+  args: jsonSchemaToZod(orchInitSchema).shape as any,
+  async execute(args, context) {
+    return initExecute(args as any, makeCtx(context))
+  },
+})
+
+export const set_worktree = tool({
+  description:
+    "确保目标组的 git worktree 就绪。若已存在则复用，否则按规范自动创建（分支 task-group/{changeId}/{taskGroupId}，路径 .worktree/{changeId}/task-group-{taskGroupId}）。只补齐资源，不改变阶段。",
+  args: jsonSchemaToZod(setWorktreeSchema).shape as any,
+  async execute(args, context) {
+    return setWorktreeExecute(args as any, makeCtx(context))
+  },
+})
+
+export const status = tool({
+  description:
+    "统一状态/上下文查询（只读为主）。按调用者角色路由：编排视角→统计+worktree；architect→spec/blocker；developer→worktree/boundary/task/issue；reviewer-tool→tool 层控件 issue；reviewer-task→task 验证状态；quality reviewer→自维度既有 issue。",
+  args: jsonSchemaToZod(statusSchema).shape as any,
+  async execute(args, context) {
+    return statusExecute({ change_id: args.change_id as string }, makeCtx(context))
+  },
+})
+
+export const complete_task_group = tool({
+  description:
+    "完成任务组收尾：合并 task-group 分支到 baseBranch → 清理 worktree 与分支。须在收尾验证（verify_cleanup）通过后调用。合并冲突时中止并返回 blocked（保留 worktree/分支）。",
+  args: jsonSchemaToZod(completeTaskGroupSchema).shape as any,
+  async execute(args, context) {
+    return completeTaskGroupExecute({ change_id: args.change_id as string }, makeCtx(context))
+  },
+})
+
+export const set_unattended = tool({
+  description:
+    "开启/关闭无人值守模式。开启后编排流程不再向用户提问：analyze 确认模式由架构师自行裁决（不确认用户）；重试检查点、状态异常、blocker 处理等需拍板事项由主代理按编排行为准则自行决策并提交——检查点决策是 opx_agent_submit 工具调用，主代理可自行执行，不因无人值守而抑制。",
+  args: jsonSchemaToZod(setUnattendedSchema).shape as any,
+  async execute(args, context) {
+    return setUnattendedExecute(args as any, makeCtx(context))
+  },
+})
+
+export const agent_submit = tool({
+  description:
+    "通用 step 提交，按 step_id 路由到 workflow 对应 step。校验调用者属于该 step 的 agents（越权直接拒绝），提交后推进 workflow 状态机并写回编排状态。可通过 exempt_adjudications 对已申请豁免的 issue 进行裁定（dismissed→cancelled、rejected→回 todo）；可通过 recheck_adjudications 复核已修复待复核（review 态）的 issue（passed→done、rejected→回 todo 并记 refix_count 与 reject_reason，谁提谁裁定）。",
+  args: jsonSchemaToZod(agentSubmitSchema).shape as any,
+  async execute(args, context) {
+    return agentSubmitExecute(args as any, makeCtx(context))
+  },
+})

package/src/adapters/plugin-common/index.ts

@@ -0,0 +1,173 @@
+/**
+ * 多 agent 插件包共享生成器（DRY）：zcode 与 claude code 的官方插件机制格式同构——
+ * 插件目录 + 清单目录内 plugin.json（组件目录 agents/skills/.mcp.json 等与清单目录同级，
+ * 仅 plugin.json 放清单目录内）、MCP 模板变量 ${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PROJECT_DIR}。
+ * 差异仅为清单目录名，由各适配器以参数声明（manifestDirName）。
+ *
+ * 生成产物为一个完整插件目录：plugin.json 清单 + agents/*.md（从 assets/agents 转换、
+ * 排除主代理模板、frontmatter 仅保留 name/description）+ skills/<名>/（含 orchestrator 与
+ * reference/ 附属文件）+ assets/workflows/（task.yaml workflow 定义，bundle 内按部署深度
+ * 逐级上溯探测读取）+ .mcp.json（stdio + 自包含 bundle 入口 + 当前项目 worktree + 默认
+ * 无人值守）+ .mcp-server/cli.mjs 自包含 bundle（node 直接执行，不依赖 node_modules）。
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync, cpSync } from "node:fs"
+import { join } from "node:path"
+import { spawnSync } from "node:child_process"
+import * as yaml from "js-yaml"
+import { parseAgentMd, resolve, EXCLUDED_AGENTS } from "../agent-md.ts"
+
+export const PLUGIN_NAME = "openspec-agents"
+export const PLUGIN_DESCRIPTION =
+  "OpenSpec change 编排：opx_* 编排工具（MCP）+ 编排子代理 + orchestrator skill，非 OpenCode agent 默认无人值守"
+/** plugin.json author（package.json 无 author 字段，取固定值）。 */
+export const PLUGIN_AUTHOR = "openspec-agents maintainers"
+
+function readPkgVersion(): string {
+  return (JSON.parse(readFileSync(resolve("package.json"), "utf-8")) as { version: string }).version
+}
+
+/**
+ * 构建 MCP server 自包含 bundle（node cli.ts 直跑依赖 node_modules，插件安装后无此环境，
+ * 故 bundle 单文件至插件包内，node 直接执行）。打包依赖本机 bun CLI（spawnSync("bun")）。
+ */
+function bundleMcpServer(pluginDir: string): void {
+  const out = join(pluginDir, ".mcp-server", "cli.mjs")
+  mkdirSync(join(pluginDir, ".mcp-server"), { recursive: true })
+  // dashboard 页面资源随 bundle 同目录放置（page.ts 按此布局探测）
+  cpSync(resolve("assets", "dashboard"), join(pluginDir, ".mcp-server", "dashboard"), { recursive: true })
+  const result = spawnSync(
+    "bun",
+    [
+      "build",
+      resolve("src", "adapters", "mcp-common", "cli.ts"),
+      "--outfile",
+      out,
+      "--target",
+      "node",
+      "--define",
+      `__OPX_PKG_VERSION__="${readPkgVersion()}"`,
+    ],
+    { encoding: "utf-8", stdio: ["ignore", "ignore", "pipe"] },
+  )
+  if (result.status !== 0) {
+    throw new Error(`MCP server bundle 失败：${result.stderr ?? result.error?.message ?? "未知错误"}`)
+  }
+}
+
+/** 转换 agents：从 assets/agents/*.md 取子代理（排除主代理模板），frontmatter 仅保留 name/description。 */
+function buildAgents(targetDir: string): string[] {
+  const agentsRoot = resolve("assets", "agents")
+  const injected: string[] = []
+  for (const file of readdirSync(agentsRoot)) {
+    if (!file.endsWith(".md")) continue
+    if (EXCLUDED_AGENTS.has(file)) continue
+    const { frontmatter, body } = parseAgentMd(readFileSync(join(agentsRoot, file), "utf-8"))
+    const name = (frontmatter.name as string) ?? file.replace(/\.md$/, "")
+    if (!name) continue
+    const pluginFrontmatter: Record<string, unknown> = { name, description: frontmatter.description ?? "" }
+  // plugin.json 省略 agents/skills/mcpServers 字段：官方按约定位置自动发现组件
+  // （插件根 agents/、skills/、.mcp.json），省略后 `claude plugin validate` 通过且
+  // `claude plugin details` 能发现全部组件；显式声明字符串字段反而报 Invalid input
+  // （`./` 前缀写法实测对 agents 同样报错），故不声明。
+  writeFileSync(
+      join(targetDir, `${name}.md`),
+      `---\n${yaml.dump(pluginFrontmatter)}---\n\n${body.trim()}\n`,
+      "utf-8",
+    )
+    injected.push(name)
+  }
+  return injected
+}
+
+/** 复制 skills：整个 skill 目录（SKILL.md + reference/ 等附属文件），含 orchestrator skill。 */
+function buildSkills(targetDir: string): string[] {
+  const skillsRoot = resolve("assets", "skills")
+  const injected: string[] = []
+  for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const src = join(skillsRoot, entry.name)
+    if (!existsSync(join(src, "SKILL.md"))) continue
+    cpSync(src, join(targetDir, entry.name), { recursive: true })
+    injected.push(entry.name)
+  }
+  return injected
+}
+
+export interface PluginPackageParams {
+  /** 输出目录（如 dist/zcode-plugin/） */
+  outDir: string
+  /** 清单目录名（".zcode-plugin" | ".claude-plugin"），组件目录与清单目录同级 */
+  manifestDirName: string
+}
+
+export interface PluginPackageResult {
+  pluginDir: string
+  version: string
+  agents: string[]
+  skills: string[]
+}
+
+/**
+ * 生成官方插件包到 outDir：<manifestDirName>/plugin.json 清单、agents/*.md、skills/<名>/、
+ * assets/workflows/、.mcp.json、.mcp-server/cli.mjs bundle。返回生成的组件清单供调用方/测试断言。
+ */
+export function buildPluginPackage({ outDir, manifestDirName }: PluginPackageParams): PluginPackageResult {
+  rmSync(outDir, { recursive: true, force: true })
+  mkdirSync(join(outDir, manifestDirName), { recursive: true })
+  mkdirSync(join(outDir, "agents"), { recursive: true })
+  mkdirSync(join(outDir, "skills"), { recursive: true })
+
+  const version = readPkgVersion()
+  const agents = buildAgents(join(outDir, "agents"))
+  const skills = buildSkills(join(outDir, "skills"))
+  bundleMcpServer(outDir)
+  // workflow 定义随包分发：bundle 内 TASK_WORKFLOW_PATH 按部署深度逐级上溯探测
+  // assets/workflows/task.yaml，插件根（dist/cache 形态）上溯 1 级即命中
+  cpSync(resolve("assets", "workflows"), join(outDir, "assets", "workflows"), { recursive: true })
+
+  writeFileSync(
+    join(outDir, manifestDirName, "plugin.json"),
+    JSON.stringify(
+      {
+        name: PLUGIN_NAME,
+        version,
+        description: PLUGIN_DESCRIPTION,
+        license: "MIT",
+        author: { name: PLUGIN_AUTHOR },
+      },
+      null,
+      2,
+    ) + "\n",
+    "utf-8",
+  )
+
+  // MCP server 声明：stdio + 默认无人值守；--worktree 指向当前打开项目根（官方模板变量
+  // ${CLAUDE_PROJECT_DIR}，插件用户级安装后跨项目生效，不依赖进程 cwd 约定）；
+  // server 入口为插件内自包含 bundle（${CLAUDE_PLUGIN_ROOT} 解析到安装后插件根）。
+  writeFileSync(
+    join(outDir, ".mcp.json"),
+    JSON.stringify(
+      {
+        mcpServers: {
+          [PLUGIN_NAME]: {
+            type: "stdio",
+            command: "node",
+            args: [
+              "${CLAUDE_PLUGIN_ROOT}/.mcp-server/cli.mjs",
+              "--transport",
+              "stdio",
+              "--worktree",
+              "${CLAUDE_PROJECT_DIR}",
+              "--unattended",
+            ],
+          },
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+    "utf-8",
+  )
+
+  return { pluginDir: outDir, version, agents, skills }
+}