@ifrankwang/openspec-agents 0.118.0

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@ifrankwang/openspec-agents",
+  "version": "0.118.0",
+  "type": "module",
+  "main": "./src/core/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/core/index.ts",
+      "types": "./src/core/index.ts"
+    },
+    "./core": {
+      "import": "./src/core/index.ts",
+      "types": "./src/core/index.ts"
+    },
+    "./provider": {
+      "import": "./src/core/provider.ts",
+      "types": "./src/core/provider.ts"
+    },
+    "./opencode": {
+      "import": "./src/adapters/opencode/index.ts",
+      "types": "./src/adapters/opencode/index.ts"
+    },
+    "./server": {
+      "import": "./src/adapters/opencode/index.ts",
+      "types": "./src/adapters/opencode/index.ts"
+    },
+    "./claude-code": {
+      "import": "./src/adapters/claude-code/index.ts",
+      "types": "./src/adapters/claude-code/index.ts"
+    },
+    "./codex": {
+      "import": "./src/adapters/codex/index.ts",
+      "types": "./src/adapters/codex/index.ts"
+    },
+    "./zcode": {
+      "import": "./src/adapters/zcode/index.ts",
+      "types": "./src/adapters/zcode/index.ts"
+    },
+    "./mcp": {
+      "import": "./src/adapters/mcp-common/index.ts",
+      "types": "./src/adapters/mcp-common/index.ts"
+    },
+    "./mcp/cli": {
+      "import": "./src/adapters/mcp-common/cli.ts",
+      "types": "./src/adapters/mcp-common/cli.ts"
+    }
+  },
+  "files": [
+    "src",
+    "assets"
+  ],
+  "scripts": {
+    "sync": "bun scripts/sync.ts",
+    "build:plugins": "bun scripts/build-plugins.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.17.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.0",
+    "@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"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapters/agent-md.ts

@@ -0,0 +1,37 @@
+/**
+ * 多适配器共享的 agent 定义解析工具（DRY）：agent.md frontmatter/body 解析、项目根路径解析、
+ * 非主代理形态注入排除清单。opencode / claude-code / codex / zcode 适配器统一引用。
+ */
+import { dirname, resolve as pathResolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import * as yaml from "js-yaml"
+
+export interface ParsedAgent {
+  frontmatter: Record<string, unknown>
+  body: string
+}
+
+export function parseAgentMd(content: string): ParsedAgent {
+  const result: ParsedAgent = { frontmatter: {}, body: content }
+  if (!content.startsWith("---")) return result
+  const end = content.indexOf("---", 3)
+  if (end === -1) return result
+  const fmText = content.slice(3, end).trim()
+  result.body = content.slice(end + 3).trim()
+  try {
+    result.frontmatter = (yaml.load(fmText) as Record<string, unknown>) ?? {}
+  } catch {
+    result.body = content
+  }
+  return result
+}
+
+/** 项目根（assets/ 等资源所在目录）。 */
+export const PROJECT_ROOT = pathResolve(dirname(fileURLToPath(import.meta.url)), "..", "..")
+
+export function resolve(...p: string[]): string {
+  return pathResolve(PROJECT_ROOT, ...p)
+}
+
+/** 主代理模板（opencode 用）不在 claude code / codex / zcode 注入：主代理即本体，子代理定义全部注入。 */
+export const EXCLUDED_AGENTS = new Set(["openspec-main.md"])

package/src/adapters/claude-code/index.ts

@@ -0,0 +1,35 @@
+/**
+ * claude code 适配器：Claude Code 官方插件包生成（Plugin 机制，code.claude.com/docs/en/plugins）。
+ * 复用共享生成器 src/adapters/plugin-common/，差异参数：清单目录 .claude-plugin/。
+ *
+ * 与 zcode 同构的官方插件形态：安装/启用/禁用/卸载均为 CLI 或会话内命令
+ * （claude plugin marketplace add + claude plugin install，或 /plugin marketplace add + /plugin install），
+ * 插件安装后复制到本地缓存，子代理为插件只读形态。
+ *
+ * 已知限制（接入文档注明）：
+ * - 插件子代理为 read-only，不支持 hooks/mcpServers/permissionMode frontmatter（本项目子代理
+ *   本就只读，无冲突）；
+ * - claude plugin install / 会话内 /plugin install 为人工步骤，本适配器仅保证生成结构与官方
+ *   schema 一致。
+ */
+import { resolve } from "../agent-md.ts"
+import {
+  buildPluginPackage,
+  type PluginPackageResult,
+} from "../plugin-common/index.ts"
+
+/** 默认插件包输出目录（dist/ 已 gitignore，生成物不入库）。 */
+export const CLAUDE_CODE_PLUGIN_DIR = resolve("dist", "claude-code-plugin")
+const MANIFEST_DIR_NAME = ".claude-plugin"
+
+export type ClaudeCodePluginBuildResult = PluginPackageResult
+
+/**
+ * 生成 Claude Code 官方插件包到 outDir（默认 dist/claude-code-plugin/）：
+ * .claude-plugin/plugin.json 清单、agents/*.md、skills/<名>/、assets/workflows/、.mcp.json、
+ * .mcp-server/cli.mjs bundle。
+ * 返回生成的组件清单供调用方/测试断言。
+ */
+export function buildClaudeCodePlugin(outDir: string = CLAUDE_CODE_PLUGIN_DIR): ClaudeCodePluginBuildResult {
+  return buildPluginPackage({ outDir, manifestDirName: MANIFEST_DIR_NAME })
+}

package/src/adapters/codex/index.ts

@@ -0,0 +1,161 @@
+/**
+ * codex 适配器：官方插件包生成（.codex-plugin/plugin.json + agents/skills/.mcp.json），
+ * 以及兼容手动 agent 定义注入（.codex/agents/*.toml）、MCP 配置分发（config.toml，TOML 格式）、
+ * 默认无人值守（MCP server 启动参数 --unattended）。
+ *
+ * 已知限制（接入文档注明）：
+ * - codex 的 request_user_input 工具仅根线程（主代理）可用，且普通模式需 feature flag
+ *   （--experimental-auto-plan / request_user_input 相关 flag）开启，codex exec 不可用；
+ * - 子代理无法向用户提问 → 默认无人值守，需拍板事项由主代理依据 orchestrator skill 自行裁决。
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { parseAgentMd, resolve, EXCLUDED_AGENTS } from "../agent-md.ts"
+import { buildPluginPackage, PLUGIN_NAME, PLUGIN_DESCRIPTION, PLUGIN_AUTHOR, type PluginPackageResult } from "../plugin-common/index.ts"
+
+/** codex agent 工具白名单（按职责收敛，审查/分析角色不含写文件工具）。 */
+const AGENT_TOOLS: Record<string, string[]> = {
+  "openspec-architect": ["read", "grep", "glob", "ls", "bash", "web"],
+  "openspec-developer": ["read", "grep", "glob", "ls", "bash", "apply_patch", "web"],
+  default: ["read", "grep", "glob", "ls", "bash"],
+}
+
+function tomlEscape(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+}
+
+/** 生成 codex agent TOML（.codex/agents/*.toml）。 */
+function toAgentToml(name: string, description: string, body: string, tools: string[]): string {
+  const lines: string[] = [
+    `description = "${tomlEscape(description)}"`,
+    `tools = [${tools.map((t) => `"${t}"`).join(", ")}]`,
+    "",
+    "[instructions]",
+    `body = """`,
+    body.trim(),
+    `"""`,
+    "",
+  ]
+  return lines.join("\n")
+}
+
+/** 注入子代理定义到 .codex/agents/*.toml（目标仓库根目录）。返回注入的 agent 名列表。 */
+export function injectCodexAgents(repoRoot: string): string[] {
+  const agentsRoot = resolve("assets", "agents")
+  if (!existsSync(agentsRoot)) return []
+  const targetDir = join(repoRoot, ".codex", "agents")
+  mkdirSync(targetDir, { recursive: true })
+  const injected: string[] = []
+  for (const file of readdirSync(agentsRoot)) {
+    if (!file.endsWith(".md")) continue
+    if (EXCLUDED_AGENTS.has(file)) continue
+    const md = readFileSync(join(agentsRoot, file), "utf-8")
+    const { frontmatter, body } = parseAgentMd(md)
+    const name = (frontmatter.name as string) ?? file.replace(/\.md$/, "")
+    if (!name) continue
+    const tools = AGENT_TOOLS[name] ?? AGENT_TOOLS.default
+    writeFileSync(
+      join(targetDir, `${name}.toml`),
+      toAgentToml(name, (frontmatter.description as string) ?? "", body, tools),
+      "utf-8",
+    )
+    injected.push(name)
+  }
+  return injected
+}
+
+/**
+ * 分发 MCP 注册配置到 .codex/config.toml（TOML，合并既有配置）。
+ * serverEntry 为 MCP server 可执行入口（node 脚本路径），stdio transport + 默认无人值守。
+ */
+export function injectCodexMcp(repoRoot: string, serverEntry: string): void {
+  const target = join(repoRoot, ".codex", "config.toml")
+  mkdirSync(dirname(target), { recursive: true })
+  const existing = existsSync(target) ? readFileSync(target, "utf-8") : ""
+  const block = [
+    `[mcp_servers.openspec-agents]`,
+    `command = "node"`,
+    `args = ["${tomlEscape(serverEntry)}", "--transport", "stdio", "--worktree", ".", "--unattended"]`,
+  ].join("\n")
+  // 已存在同名 server 块则整体替换，否则追加
+  const re = /\[mcp_servers\.openspec-agents\][\s\S]*?(?=\n\[|\n*$)/m
+  const next = re.test(existing) ? existing.replace(re, block) : `${existing.trimEnd()}\n\n${block}\n`
+  writeFileSync(target, next, "utf-8")
+}
+
+/** 清理注入产物（测试/卸载用）。 */
+export function removeCodexInjection(repoRoot: string): void {
+  try { rmSync(join(repoRoot, ".codex", "agents"), { recursive: true, force: true }) } catch {}
+  try { rmSync(join(repoRoot, ".codex", "config.toml"), { recursive: true, force: true }) } catch {}
+}
+
+/** Codex 官方插件包默认输出目录（dist/ 已 gitignore，生成物不入库）。 */
+export const CODEX_PLUGIN_DIR = resolve("dist", "codex-plugin")
+
+/**
+ * 生成 Codex 官方插件包到 outDir（默认 dist/codex-plugin/）：
+ * .codex-plugin/plugin.json 清单、agents/*.md、skills/<名>/、assets/workflows/、
+ * .mcp.json、.mcp-server/cli.mjs bundle。
+ *
+ * 与 Claude/ZCode 插件包共用 plugin-common 的组件复制与 MCP bundle 构建，
+ * 差异仅在清单目录名、plugin.json 字段和 .mcp.json 的路径/模板变量。
+ */
+export function buildCodexPlugin(outDir: string = CODEX_PLUGIN_DIR): PluginPackageResult {
+  const result = buildPluginPackage({ outDir, manifestDirName: ".codex-plugin" })
+
+  // Codex 官方 plugin.json：可声明 skills/mcpServers，interface 用于商店展示。
+  writeFileSync(
+    join(outDir, ".codex-plugin", "plugin.json"),
+    JSON.stringify(
+      {
+        name: PLUGIN_NAME,
+        version: result.version,
+        description: PLUGIN_DESCRIPTION,
+        author: { name: PLUGIN_AUTHOR },
+        license: "MIT",
+        skills: "./skills/",
+        mcpServers: "./.mcp.json",
+        interface: {
+          displayName: "OpenSpec Agents",
+          shortDescription: "OpenSpec change orchestration for Codex",
+          longDescription: PLUGIN_DESCRIPTION,
+          developerName: "ifrankwang",
+          category: "Developer Tools",
+          capabilities: ["Read", "Write"],
+          defaultPrompt: ["Run the OpenSpec change orchestration workflow."],
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+    "utf-8",
+  )
+
+  // Codex 插件 MCP 使用相对插件根的路径；--worktree . 指向 Codex 当前工作区。
+  writeFileSync(
+    join(outDir, ".mcp.json"),
+    JSON.stringify(
+      {
+        mcpServers: {
+          [PLUGIN_NAME]: {
+            command: "node",
+            args: [
+              "./.mcp-server/cli.mjs",
+              "--transport",
+              "stdio",
+              "--worktree",
+              ".",
+              "--unattended",
+            ],
+            cwd: ".",
+          },
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+    "utf-8",
+  )
+
+  return result
+}

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

@@ -0,0 +1,64 @@
+/**
+ * MCP server 可执行入口（CLI）：
+ * - --worktree <path> 主仓库根（默认 process.cwd()）
+ * - --port <n> HTTP transport 端口（默认 4525）
+ * - --transport http|stdio（默认 http）
+ * - --unattended 默认无人值守（claude code / codex / zcode 适配器分发时开启）
+ *
+ * 运行：node <entry> --transport stdio --worktree . --unattended
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { buildMcpServer } from "./server.ts"
+import { startMcpServer, DEFAULT_PORT } from "./index.ts"
+import { fileURLToPath } from "node:url"
+import { realpathSync } from "node:fs"
+
+interface CliOptions {
+  worktree: string
+  port: number
+  transport: "http" | "stdio"
+  unattended: boolean
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const args = new Map<string, string>()
+  const flags = new Set<string>()
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith("--")) {
+      const key = argv[i].slice(2)
+      const val = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : ""
+      if (val !== "") {
+        args.set(key, val)
+        i++
+      } else {
+        flags.add(key)
+      }
+    }
+  }
+  const transport = args.get("transport") === "stdio" ? "stdio" : "http"
+  return {
+    worktree: args.get("worktree") ?? process.cwd(),
+    port: args.get("port") ? Number(args.get("port")) : DEFAULT_PORT,
+    transport,
+    unattended: flags.has("unattended"),
+  }
+}
+
+export async function main(argv: string[]): Promise<void> {
+  const opts = parseArgs(argv)
+  if (opts.transport === "stdio") {
+    const mcp = buildMcpServer(opts.worktree, { unattended: opts.unattended })
+    await mcp.connect(new StdioServerTransport())
+    return
+  }
+  startMcpServer(opts)
+}
+
+// 直接执行判定：realpath 归一化（macOS /tmp 与 /private/tmp 符号链接场景）
+try {
+  if (realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1] ?? "")) {
+    void main(process.argv.slice(2))
+  }
+} catch {
+  // 路径不可解析时静默跳过入口（作为库导入场景）
+}

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

@@ -0,0 +1,137 @@
+/**
+ * MCP Server 启动入口：HTTP transport（node:http）承载 6 个 opx_* 工具，
+ * 并承载 dashboard/collector/poller 副作用（原 OpenCode 插件壳职责迁移至此）。
+ * 非 OpenCode agent（claude code / codex / zcode）经 MCP client 接入同一套编排状态机。
+ */
+import { createServer, type Server } from "node:http"
+import { randomUUID } from "node:crypto"
+import { join } from "node:path"
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
+import { buildMcpServer } from "./server.ts"
+import { startDashboard } from "../opencode/dashboard.ts"
+import { OpenSpecCollector, AdoCollector, registerCollector, startPolling } from "../../core/workflow/index.ts"
+import { readContextFromWorktree } from "../../core/state.ts"
+
+export interface McpServerOptions {
+  worktree: string
+  port?: number
+  hostname?: string
+  /** 默认无人值守（非 OpenCode agent 默认开启，spec: unattended-default）。 */
+  unattended?: boolean
+}
+
+export const DEFAULT_PORT = 4525
+const MAX_PORT_ATTEMPTS = 20
+
+/** 启动 dashboard/collector/poller 副作用（原插件壳职责，单一宿主 = MCP server 进程）。 */
+function startSideEffects(worktree: string): void {
+  try {
+    void startDashboard(worktree)
+    // 注册内置收集器（OpenSpec + ADO 占位）并启动定时拉取；worktree 为动态上下文在此注入。
+    registerCollector(new OpenSpecCollector({ openspecDir: join(worktree, "openspec") }))
+    registerCollector(new AdoCollector())
+    // 仅已初始化（存在 context.json 上下文指针）的 worktree 启动轮询
+    void readContextFromWorktree(worktree).then((ctx) => {
+      if (ctx?.changeId && ctx?.taskGroupId) {
+        startPolling(worktree)
+      }
+    })
+  } catch {
+    // dashboard/调度启动失败不影响编排功能
+  }
+}
+
+/**
+ * 启动 MCP server（Streamable HTTP）。会话管理：mcp-session-id 关联 transport（官方推荐模式）。
+ * unattended=true 时默认开启无人值守（非 OpenCode agent 适配器分发）。
+ * 返回实际绑定端口（server.address().port，port 为 0 或端口被占用换绑时以返回值为准）。
+ */
+export async function startMcpServer(opts: McpServerOptions): Promise<{ server: Server; port: number }> {
+  const mcp = buildMcpServer(opts.worktree, { unattended: opts.unattended })
+  startSideEffects(opts.worktree)
+
+  const port = opts.port ?? DEFAULT_PORT
+  const hostname = opts.hostname ?? "127.0.0.1"
+  const transports = new Map<string, StreamableHTTPServerTransport>()
+
+  const server = createServer(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"]
+      let transport = typeof sessionId === "string" ? transports.get(sessionId) : undefined
+      if (!transport) {
+        transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() })
+        try {
+          await mcp.connect(transport)
+        } catch (err) {
+          res.writeHead(500, { "content-type": "text/plain;charset=utf-8" })
+          res.end(`MCP transport connect 失败：${(err as Error).message}`)
+          return
+        }
+      }
+      await transport.handleRequest(req, res)
+      // session id 在首次 handleRequest 时才生成：生成后注册映射，后续请求复用同一 transport
+      if (transport.sessionId && !transports.has(transport.sessionId)) {
+        transports.set(transport.sessionId, transport)
+        transport.onclose = () => {
+          transports.delete(transport.sessionId ?? "")
+        }
+      }
+      return
+    }
+    if (req.method === "GET") {
+      res.writeHead(200, { "content-type": "application/json;charset=utf-8" })
+      res.end(JSON.stringify({ name: "openspec-agents", status: "ok" }))
+      return
+    }
+    res.writeHead(405, { "content-type": "text/plain;charset=utf-8" })
+    res.end("Method Not Allowed")
+  })
+
+  let started = false
+  for (let p = port; p < port + MAX_PORT_ATTEMPTS; p++) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        server.once("error", (err: NodeJS.ErrnoException) => {
+          if (err.code === "EADDRINUSE") {
+            reject(err)
+          } else {
+            console.error("[mcp]", err.message)
+            resolve()
+          }
+        })
+        server.listen(p, hostname, () => resolve())
+      })
+      started = true
+      console.log(`[mcp] openspec-agents MCP server http://${hostname}:${p}/mcp（worktree: ${opts.worktree}）`)
+      break
+    } catch {
+      continue
+    }
+  }
+  if (!started) {
+    throw new Error(`无法启动 MCP server：端口 ${port}-${port + MAX_PORT_ATTEMPTS - 1} 均被占用`)
+  }
+  const addr = server.address()
+  const actualPort = typeof addr === "object" && addr !== null ? addr.port : 0
+  return { server, port: actualPort }
+}
+
+/** 命令行入口：node dist/... --worktree <path> [--port <n>] */
+export function runCli(argv: string[]): void {
+  const args = new Map<string, string>()
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith("--")) {
+      const key = argv[i].slice(2)
+      const val = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : ""
+      args.set(key, val)
+      if (val !== "") i++
+    }
+  }
+  const worktree = args.get("worktree") ?? process.cwd()
+  const port = args.get("port") ? Number(args.get("port")) : DEFAULT_PORT
+  const unattended = args.has("unattended")
+  startMcpServer({ worktree, port, unattended })
+}

package/src/adapters/mcp-common/json-schema.ts

@@ -0,0 +1,53 @@
+/**
+ * 纯 JSON Schema → zod 转换（MCP SDK 工具 inputSchema 校验用）。
+ * 与 opencode 适配层转换器职责相同但独立实现（不依赖 @opencode-ai/plugin），
+ * 转换语义与 P1 纯 JSON Schema 契约一致。
+ */
+import { z } from "zod"
+import type { JSONSchema } from "../../core/provider.ts"
+
+export function jsonSchemaToZod(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 = jsonSchemaToZod(sub)
+        shape[key] = (schema.required ?? []).includes(key) ? converted : converted.optional()
+      }
+      if (Object.keys(shape).length === 0) return z.object({})
+      return z.object(shape)
+    }
+    case "array": {
+      const items = schema.items ?? { type: "string" }
+      let arr = z.array(jsonSchemaToZod(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 ? z.string() : z.enum(values as [string, ...string[]])
+      }
+      let s = z.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" ? z.number().int() : z.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 = z.boolean()
+      if (schema.default !== undefined) b = b.default(schema.default as boolean)
+      return b
+    }
+    case "null":
+      return z.null()
+    default:
+      return z.any()
+  }
+}