@ifrankwang/openspec-agents 0.119.1 → 0.120.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.119.1",
+  "version": "0.120.1",
   "type": "module",
   "main": "./src/core/index.ts",
   "exports": {
@@ -36,6 +36,14 @@
       "import": "./src/adapters/zcode/index.ts",
       "types": "./src/adapters/zcode/index.ts"
     },
+    "./deepseek-harness": {
+      "import": "./src/adapters/deepseek-harness/index.ts",
+      "types": "./src/adapters/deepseek-harness/index.ts"
+    },
+    "./dsh": {
+      "import": "./src/adapters/deepseek-harness/index.ts",
+      "types": "./src/adapters/deepseek-harness/index.ts"
+    },
     "./mcp": {
       "import": "./src/adapters/mcp-common/index.ts",
       "types": "./src/adapters/mcp-common/index.ts"
@@ -47,11 +55,15 @@
   },
   "files": [
     "src",
-    "assets"
+    "assets",
+    "dsh",
+    ".mcp-server"
   ],
   "scripts": {
     "sync": "bun scripts/sync.ts",
     "build:plugins": "bun scripts/build-plugins.ts",
+    "build:dsh": "bun scripts/build-dsh-root.ts",
+    "prepack": "bun run build:dsh",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
@@ -65,6 +77,11 @@
     "js-yaml": "^4.1.0",
     "@opencode-ai/plugin": "^1.17.0"
   },
+  "dsh": {
+    "bundle": {
+      "patch": "./dsh/cordis.patch.yml"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/adapters/codex/index.ts

@@ -73,12 +73,12 @@ export function injectCodexMcp(repoRoot: string, serverEntry: string): void {
   mkdirSync(dirname(target), { recursive: true })
   const existing = existsSync(target) ? readFileSync(target, "utf-8") : ""
   const block = [
-    `[mcp_servers.openspec-agents]`,
+    `[mcp_servers.opx]`,
     `command = "node"`,
-    `args = ["${tomlEscape(serverEntry)}", "--transport", "stdio", "--worktree", ".", "--unattended"]`,
+    `args = ["${tomlEscape(serverEntry)}", "--transport", "stdio", "--worktree", ".", "--unattended", "--strip-opx-prefix"]`,
   ].join("\n")
   // 已存在同名 server 块则整体替换，否则追加
-  const re = /\[mcp_servers\.openspec-agents\][\s\S]*?(?=\n\[|\n*$)/m
+  const re = /\[mcp_servers\.opx\][\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")
 }
@@ -137,7 +137,7 @@ export function buildCodexPlugin(outDir: string = CODEX_PLUGIN_DIR): PluginPacka
     JSON.stringify(
       {
         mcpServers: {
-          [PLUGIN_NAME]: {
+          opx: {
             command: "node",
             args: [
               "./.mcp-server/cli.mjs",
@@ -146,6 +146,7 @@ export function buildCodexPlugin(outDir: string = CODEX_PLUGIN_DIR): PluginPacka
               "--worktree",
               ".",
               "--unattended",
+              "--strip-opx-prefix",
             ],
             cwd: ".",
           },

package/src/adapters/deepseek-harness/index.ts

@@ -0,0 +1,205 @@
+/**
+ * DeepSeek Harness (DSH) 适配器：生成 DSH bundle 插件包。
+ *
+ * DSH 的插件形态不是 Claude/Codex/ZCode 的 plugin.json，而是 npm 包 +
+ * package.json 中 `dsh.bundle.patch` 指向的 cordis patch 文件。本适配器复用
+ * plugin-common 的 MCP server bundle / skills / workflows 资产构建，生成一个
+ * 可直接用 `dsh plugin --profile <name> add <dir>` 安装的 bundle 包。
+ *
+ * 生成的 patch 不引入自研 Cordis 插件，而是直接插入 DSH 官方能力：
+ * - `@deepseek-ai/dsh-mcp-client`：把本项目 MCP server（opx_* 工具）桥接为
+ *   DSH 原生工具（mcp__opx__*）。
+ * - `@deepseek-ai/dsh-skill-filesystem`：把 assets/skills 注册为额外 skill 根，
+ *   使 orchestrator 与各质量维度 skill 可被 DSH agent 发现/加载。
+ * - `@deepseek-ai/dsh-tool-subagent`：为每个 assets/agents 子代理生成一个
+ *   DSH 原生 subagent 工具（如 openspec_architect / openspec_developer），
+ *   子代理 persona 取自对应 agent.md，真正接入 DSH 子代理体系。
+ */
+import { writeFileSync, mkdirSync, rmSync, readFileSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import * as yaml from "js-yaml"
+import { parseAgentMd, resolve, EXCLUDED_AGENTS } from "../agent-md.ts"
+import {
+  PLUGIN_DESCRIPTION,
+  bundleMcpServer,
+  buildAgents,
+  buildSkills,
+  copyWorkflows,
+  readPkgVersion,
+  type PluginPackageResult,
+} from "../plugin-common/index.ts"
+
+/** DSH bundle 的 npm 包名（与项目发布包一致，便于 `dsh plugin add` 与 sync 识别）。 */
+export const DSH_PLUGIN_NAME = "@ifrankwang/openspec-agents"
+
+/** 默认插件包输出目录（dist/ 已 gitignore，生成物不入库）。 */
+export const DEEP_SEEK_HARNESS_PLUGIN_DIR = resolve("dist", "deepseek-harness-plugin")
+/** 简写别名，便于与 `dsh` 缩写保持一致。 */
+export const DSH_PLUGIN_DIR = DEEP_SEEK_HARNESS_PLUGIN_DIR
+
+const MANIFEST_PATCH_FILENAME = "cordis.patch.yml"
+
+/** MCP client 与 skill 根的基础 patch；子代理工具行由 buildDshPatchContent 动态追加。 */
+const DSH_BASE_PATCH_YAML = `# DeepSeek Harness (DSH) bundle patch: expose OpenSpec MCP tools and skills.
+# The patch is applied as a bundle layer under dsh.profile.bundles.
+# baseUrl 指向 profile 根目录；bundle 安装后位于 profile 的 node_modules 下，
+# 因此从这里引用 node_modules/@ifrankwang/openspec-agents/... 是稳定的。
+- insert:
+    - id: openspec-mcp
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: opx
+        transport: stdio
+        command: node
+        args:
+          - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('./node_modules/@ifrankwang/openspec-agents/.mcp-server/cli.mjs', baseUrl))"
+          - '--transport'
+          - 'stdio'
+          - '--worktree'
+          - !!js "process.cwd()"
+          - '--unattended'
+          - '--strip-opx-prefix'
+        cwd: !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('./node_modules/@ifrankwang/openspec-agents', baseUrl))"
+    - id: openspec-skills
+      name: '@deepseek-ai/dsh-skill-filesystem'
+      config:
+        providerName: openspec-filesystem
+        includeDefaultRoots: false
+        customSkillDirs:
+          - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('./node_modules/@ifrankwang/openspec-agents/assets/skills', baseUrl))"
+`
+
+interface DshSubagentEntry {
+  id: string
+  name: string
+  config: Record<string, unknown>
+}
+
+/** 将 openspec-architect 转换为 openspec_architect 这类 DSH 工具名后缀。 */
+function dshAgentSuffix(name: string): string {
+  return name.replace(/^openspec-/, "").replace(/-/g, "_")
+}
+
+/** 根据 agent.md frontmatter 判断是否应禁止 DSH 子代理的写文件类工具。 */
+function denyEditTools(frontmatter: Record<string, unknown>): boolean {
+  const permission = frontmatter.permission as Record<string, unknown> | undefined
+  const edit = permission?.edit
+  if (edit === "deny") return true
+  if (edit && typeof edit === "object") {
+    const rule = edit as Record<string, unknown>
+    // architect 允许编辑 md，不能整体禁止写工具
+    return rule["*"] === "deny" && rule["*.md"] !== "allow"
+  }
+  return false
+}
+
+/** DSH 子代理 persona 前置的工具接入说明，避免子代理在首次 opx_status 前用 shell 全盘搜索工具。 */
+const DSH_SUBAGENT_TOOL_ACCESS_PREAMBLE = `## 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\` 获取上下文，不要先探查仓库或读取状态文件。
+`
+
+/** 从 assets/agents/*.md 收集 DSH 子代理工具（跳过主代理模板）。 */
+function collectDshSubagentEntries(): DshSubagentEntry[] {
+  const agentsRoot = resolve("assets", "agents")
+  const entries: DshSubagentEntry[] = []
+  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 description = (frontmatter.description as string) ?? ""
+    const persona = [DSH_SUBAGENT_TOOL_ACCESS_PREAMBLE, description, body.trim()].filter(Boolean).join("\n\n")
+    const suffix = dshAgentSuffix(name)
+    entries.push({
+      id: `openspec-subagent-${suffix}`,
+      name: "@deepseek-ai/dsh-tool-subagent",
+      config: {
+        provider: "spawn",
+        toolName: `openspec_${suffix}`,
+        persona,
+        enableRunInBackground: false,
+        backgroundMode: "one-shot",
+        ...(denyEditTools(frontmatter)
+          ? { toolFilter: { deny: ["write", "edit", "apply_patch", "str_replace_editor"] } }
+          : {}),
+      },
+    })
+  }
+  return entries
+}
+
+/** 生成完整的 DSH cordis patch 内容：基础 MCP/skills + 每个子代理一个 DSH 原生 subagent 工具。 */
+export function buildDshPatchContent(): string {
+  const subagents = collectDshSubagentEntries()
+  if (subagents.length === 0) return DSH_BASE_PATCH_YAML
+  const subagentsYaml = yaml
+    .dump(subagents, { lineWidth: -1 })
+    .split("\n")
+    .map((line) => (line ? `    ${line}` : line))
+    .join("\n")
+  return `${DSH_BASE_PATCH_YAML.trimEnd()}\n${subagentsYaml}\n`
+}
+
+export type DeepSeekHarnessPluginBuildResult = PluginPackageResult
+
+/**
+ * 生成 DeepSeek Harness bundle 插件包到 outDir（默认 dist/deepseek-harness-plugin/）：
+ * package.json（含 dsh.bundle.patch）、cordis.patch.yml、.mcp-server/cli.mjs bundle、
+ * assets/skills/、assets/workflows/。
+ *
+ * 返回生成的组件清单供调用方/测试断言；DSH 原生不消费 Markdown agent 文件，
+ * 但为保持与其它插件包一致仍会复制 agents/ 目录。
+ */
+export function buildDeepSeekHarnessPlugin(outDir: string = DEEP_SEEK_HARNESS_PLUGIN_DIR): DeepSeekHarnessPluginBuildResult {
+  rmSync(outDir, { recursive: true, force: true })
+  mkdirSync(join(outDir, "agents"), { recursive: true })
+  mkdirSync(join(outDir, "skills"), { recursive: true })
+  mkdirSync(join(outDir, "assets"), { recursive: true })
+  mkdirSync(join(outDir, ".mcp-server"), { recursive: true })
+
+  const version = readPkgVersion()
+  // DSH 通过上方 subagent 工具消费 agent 定义；agents/ 目录仍保留原始 markdown 供参考/审计。
+  const agents = buildAgents(join(outDir, "agents"))
+  const skills = buildSkills(join(outDir, "skills"))
+  bundleMcpServer(outDir)
+  copyWorkflows(outDir)
+
+  writeFileSync(
+    join(outDir, "package.json"),
+    JSON.stringify(
+      {
+        name: DSH_PLUGIN_NAME,
+        version,
+        description: PLUGIN_DESCRIPTION,
+        type: "module",
+        private: true,
+        dsh: {
+          bundle: {
+            patch: `./${MANIFEST_PATCH_FILENAME}`,
+          },
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+    "utf-8",
+  )
+
+  writeFileSync(join(outDir, MANIFEST_PATCH_FILENAME), buildDshPatchContent(), "utf-8")
+
+  return { pluginDir: outDir, version, agents, skills }
+}
+
+/** `dsh` 缩写的构建函数别名。 */
+export const buildDshPlugin = buildDeepSeekHarnessPlugin

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

@@ -4,6 +4,7 @@
  * - --port <n> HTTP transport 端口（默认 4525）
  * - --transport http|stdio（默认 http）
  * - --unattended 默认无人值守（claude code / codex / zcode 适配器分发时开启）
+ * - --strip-opx-prefix 去掉 MCP 工具名的 opx_ 前缀（DSH 使用，得到 mcp__opx__status 这类短名）
  *
  * 运行：node <entry> --transport stdio --worktree . --unattended
  */
@@ -18,6 +19,7 @@ interface CliOptions {
   port: number
   transport: "http" | "stdio"
   unattended: boolean
+  stripOpxPrefix: boolean
 }
 
 function parseArgs(argv: string[]): CliOptions {
@@ -41,13 +43,14 @@ function parseArgs(argv: string[]): CliOptions {
     port: args.get("port") ? Number(args.get("port")) : DEFAULT_PORT,
     transport,
     unattended: flags.has("unattended"),
+    stripOpxPrefix: flags.has("strip-opx-prefix"),
   }
 }
 
 export async function main(argv: string[]): Promise<void> {
   const opts = parseArgs(argv)
   if (opts.transport === "stdio") {
-    const mcp = buildMcpServer(opts.worktree, { unattended: opts.unattended })
+    const mcp = buildMcpServer(opts.worktree, { unattended: opts.unattended, stripOpxPrefix: opts.stripOpxPrefix })
     await mcp.connect(new StdioServerTransport())
     return
   }

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

@@ -127,13 +127,14 @@ const PKG_VERSION =
       ) as { version: string }).version
 
 /** 构建承载 6 个 opx_* 工具的 MCP server。unattended=true 时启用默认无人值守（spec: unattended-default）。 */
-export function buildMcpServer(worktree: string, opts: { unattended?: boolean } = {}): McpServer {
+export function buildMcpServer(worktree: string, opts: { unattended?: boolean; stripOpxPrefix?: boolean } = {}): McpServer {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION })
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {
+    const toolName = opts.stripOpxPrefix ? name.replace(/^opx_/, "") : name
     mcp.registerTool<any, any>(
-      name,
+      toolName,
       {
-        title: name,
+        title: toolName,
         description: spec.description,
         inputSchema: jsonSchemaToZod(withAgentArg(spec.schema)),
       },

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

@@ -22,7 +22,7 @@ export const PLUGIN_DESCRIPTION =
 /** plugin.json author（package.json 无 author 字段，取固定值）。 */
 export const PLUGIN_AUTHOR = "openspec-agents maintainers"
 
-function readPkgVersion(): string {
+export function readPkgVersion(): string {
   return (JSON.parse(readFileSync(resolve("package.json"), "utf-8")) as { version: string }).version
 }
 
@@ -30,7 +30,7 @@ function readPkgVersion(): string {
  * 构建 MCP server 自包含 bundle（node cli.ts 直跑依赖 node_modules，插件安装后无此环境，
  * 故 bundle 单文件至插件包内，node 直接执行）。打包依赖本机 bun CLI（spawnSync("bun")）。
  */
-function bundleMcpServer(pluginDir: string): void {
+export function bundleMcpServer(pluginDir: string): void {
   const out = join(pluginDir, ".mcp-server", "cli.mjs")
   mkdirSync(join(pluginDir, ".mcp-server"), { recursive: true })
   // dashboard 页面资源随 bundle 同目录放置（page.ts 按此布局探测）
@@ -55,7 +55,7 @@ function bundleMcpServer(pluginDir: string): void {
 }
 
 /** 转换 agents：从 assets/agents/*.md 取子代理（排除主代理模板），frontmatter 仅保留 name/description。 */
-function buildAgents(targetDir: string): string[] {
+export function buildAgents(targetDir: string): string[] {
   const agentsRoot = resolve("assets", "agents")
   const injected: string[] = []
   for (const file of readdirSync(agentsRoot)) {
@@ -80,7 +80,7 @@ function buildAgents(targetDir: string): string[] {
 }
 
 /** 复制 skills：整个 skill 目录（SKILL.md + reference/ 等附属文件），含 orchestrator skill。 */
-function buildSkills(targetDir: string): string[] {
+export function buildSkills(targetDir: string): string[] {
   const skillsRoot = resolve("assets", "skills")
   const injected: string[] = []
   for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
@@ -93,6 +93,11 @@ function buildSkills(targetDir: string): string[] {
   return injected
 }
 
+/** 复制 workflow 定义到插件包（bundle 内按部署深度逐级上溯探测读取）。 */
+export function copyWorkflows(targetDir: string): void {
+  cpSync(resolve("assets", "workflows"), join(targetDir, "assets", "workflows"), { recursive: true })
+}
+
 export interface PluginPackageParams {
   /** 输出目录（如 dist/zcode-plugin/） */
   outDir: string
@@ -123,7 +128,7 @@ export function buildPluginPackage({ outDir, manifestDirName }: PluginPackagePar
   bundleMcpServer(outDir)
   // workflow 定义随包分发：bundle 内 TASK_WORKFLOW_PATH 按部署深度逐级上溯探测
   // assets/workflows/task.yaml，插件根（dist/cache 形态）上溯 1 级即命中
-  cpSync(resolve("assets", "workflows"), join(outDir, "assets", "workflows"), { recursive: true })
+  copyWorkflows(outDir)
 
   writeFileSync(
     join(outDir, manifestDirName, "plugin.json"),
@@ -149,7 +154,7 @@ export function buildPluginPackage({ outDir, manifestDirName }: PluginPackagePar
     JSON.stringify(
       {
         mcpServers: {
-          [PLUGIN_NAME]: {
+          opx: {
             type: "stdio",
             command: "node",
             args: [
@@ -159,6 +164,7 @@ export function buildPluginPackage({ outDir, manifestDirName }: PluginPackagePar
               "--worktree",
               "${CLAUDE_PROJECT_DIR}",
               "--unattended",
+              "--strip-opx-prefix",
             ],
           },
         },

package/src/core/workflow/status.ts

@@ -565,7 +565,7 @@ function renderAgentWorking(
   lines.push(...eff.lines)
   n = eff.nextNum
   if (tg.worktreePath && tg.baseRef) {
-    lines.push(`${n++}. 用上方「变更范围」命令获取本 change 全部已提交变更文件清单，作为本次工作范围`)
+    lines.push(`${n++}. 用上方「变更范围」命令获取本 change 全部已提交变更文件清单，作为本次实施/修改范围；审查/报告范围以当前 step 指令为准`)
   }
   lines.push(`${n++}. 执行当前 step（\`${rec.stepId}\`）职责范围内的全部工作——遵循所有已加载 skill 的全部规范与约束`)
   lines.push(`${n++}. 逐项检视所有已加载 skill 的 MUST 规范，确认全部满足（不满足则补做，不得跳过）`)