@ifrankwang/openspec-agents 0.145.0 → 0.146.0

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

@@ -3,17 +3,16 @@
  *
  * 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 包。
+ * plugin-common 的 assets 构建，生成一个可直接用 `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 子代理体系。
+ * 生成的 patch 挂载两类能力：
+ * - 本包自有的 `openspec-opx-tools` cordis 插件：6 个 opx_* 编排工具注册为 DSH 原生工具，
+ *   每次调用从 `exec.agent.session.header.cwd` 取会话项目目录。多项目共用同一插件进程时
+ *   各自作用于各自项目（MCP 形态因 worktree 固定在进程启动参数上而做不到，见 patch 注释）。
+ * - DSH 官方能力：`@deepseek-ai/dsh-skill-filesystem`（skill 根）、`@deepseek-ai/dsh-tool-subagent`
+ *   （每个 assets/agents 子代理一个 DSH 原生 subagent 工具）。opx_* 工具不再经
+ *   `@deepseek-ai/dsh-mcp-client` 桥接——原生插件已直接注册工具，patch 内不挂 MCP client。
  */
 import { writeFileSync, mkdirSync, rmSync, readFileSync, readdirSync } from "node:fs"
 import { join } from "node:path"
@@ -21,7 +20,7 @@ import * as yaml from "js-yaml"
 import { parseAgentMd, resolve, EXCLUDED_AGENTS } from "../agent-md.ts"
 import {
   PLUGIN_DESCRIPTION,
-  bundleMcpServer,
+  bundleDshNativeTools,
   buildAgents,
   buildSkills,
   copyWorkflows,
@@ -43,34 +42,43 @@ 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.
+/** DSH 原生工具插件 bundle 在包内的相对路径（bundle 产物目录 + 文件名）。 */
+export const DSH_NATIVE_TOOLS_RELATIVE_PATH = ".dsh-plugin/opx-tools.mjs"
+/**
+ * bundle package.json 中声明的 exports 子路径（Node 要求深层路径显式导出，
+ * 直接 import 深层路径报 ERR_PACKAGE_PATH_NOT_EXPORTED）。
+ */
+export const DSH_NATIVE_TOOLS_EXPORTS_KEY = "./.dsh-plugin/opx-tools.mjs"
+/**
+ * cordis patch 的 insert.name：裸包名 + 子路径，二者之间是 `/` 而非 `./`——
+ * loader 走 Node 的裸包名解析，`pkg./x` 会被当成包名 `pkg.` 而 ERR_MODULE_NOT_FOUND。
+ */
+export const DSH_NATIVE_TOOLS_ROW_NAME = `${DSH_PLUGIN_NAME}${DSH_NATIVE_TOOLS_EXPORTS_KEY.slice(1)}`
+/** cordis patch 中挂载原生工具插件的 insert 行 id。 */
+export const DSH_NATIVE_TOOLS_ROW_ID = "openspec-opx-tools"
+
+/** 原生工具插件与 skill 根的基础 patch；子代理工具行由 buildDshPatchContent 动态追加。 */
+const DSH_BASE_PATCH_YAML = `# DeepSeek Harness (DSH) bundle patch: expose OpenSpec orchestration 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/... 是稳定的。
+#
+# openspec-opx-tools：本包自有的 cordis 插件，把 6 个 opx_* 编排工具注册为 DSH 原生工具。
+# 工具在 DSH 进程内执行，每次调用从 exec.agent.session.header.cwd 取会话项目目录，
+# 因此「单 profile 装一份插件、多项目共用同一进程」下各项目互不干扰——这正是 MCP 形态做不到的
+# （MCP server 是子进程，worktree 只能由启动参数固定一份，与用户打开的项目无关）。
 - insert:
-    - id: openspec-mcp
-      name: '@deepseek-ai/dsh-mcp-client'
+    - id: ${DSH_NATIVE_TOOLS_ROW_ID}
+      name: '${DSH_NATIVE_TOOLS_ROW_NAME}'
       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))"
+        unattended: true
     - 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))"
+          - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('./node_modules/${DSH_PLUGIN_NAME}/assets/skills', baseUrl))"
 `
 
 interface DshSubagentEntry {
@@ -100,16 +108,17 @@ function denyEditTools(frontmatter: Record<string, unknown>): boolean {
 /** DSH 子代理 persona 前置的工具接入说明，避免子代理在首次 opx_status 前用 shell 全盘搜索工具。 */
 const DSH_SUBAGENT_TOOL_ACCESS_PREAMBLE = `## DSH 工具接入（必读）
 
-- 本流程的 opx_* 工具在 DSH 中以 \`mcp__opx__*\` 形式出现，子代理通常只需要：
-  - \`mcp__opx__status\`
-  - \`mcp__opx__agent_submit\`
+- 本流程的 opx_* 工具在 DSH 中以 \`opx_*\` 原生工具形式出现（注册在本插件包内，无 \`mcp__\` 前缀），子代理通常只需要：
+  - \`opx_status\`
+  - \`opx_agent_submit\`
+- 调用工具时必须携带 \`_agent\` 参数传自身角色名（如 \`openspec-developer\`），否则身份无法判定、会被按编排主代理视角处理。
 - 如果当前工具列表中没有这些工具，请立即调用 \`dev_tool_search\` 搜索 \`opx\`，或一次性解锁：
   \`\`\`json
-  {"toolNames": ["mcp__opx__status", "mcp__opx__agent_submit"]}
+  {"toolNames": ["opx_status", "opx_agent_submit"]}
   \`\`\`
   如果计划使用 \`todo_write\` 跟踪任务，也请在同一轮一并解锁。
 - 严禁使用 \`find\` / \`which\` / \`grep\` 等 shell 命令搜索 \`opx\`、\`openspec\`、MCP 配置或安装路径；工具未出现是因为尚未解锁，不是未安装。
-- 解锁后第一件事是调用 \`mcp__opx__status\` 获取上下文，不要先探查仓库或读取状态文件。
+- 解锁后第一件事是调用 \`opx_status\` 获取上下文，不要先探查仓库或读取状态文件。
 `
 
 /** 从 assets/agents/*.md 收集 DSH 子代理工具（跳过主代理模板）。 */
@@ -143,7 +152,7 @@ function collectDshSubagentEntries(): DshSubagentEntry[] {
   return entries
 }
 
-/** 生成完整的 DSH cordis patch 内容：基础 MCP/skills + 每个子代理一个 DSH 原生 subagent 工具。 */
+/** 生成完整的 DSH cordis patch 内容：基础原生工具插件行 + skill 根 + 每个子代理一个 DSH 原生 subagent 工具。 */
 export function buildDshPatchContent(): string {
   const subagents = collectDshSubagentEntries()
   if (subagents.length === 0) return DSH_BASE_PATCH_YAML
@@ -159,7 +168,7 @@ 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、
+ * package.json（含 dsh.bundle.patch）、cordis.patch.yml、.dsh-plugin/opx-tools.mjs bundle、
  * assets/skills/、assets/workflows/。
  *
  * 返回生成的组件清单供调用方/测试断言；DSH 原生不消费 Markdown agent 文件，
@@ -170,13 +179,13 @@ export function buildDeepSeekHarnessPlugin(outDir: string = DEEP_SEEK_HARNESS_PL
   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 })
+  mkdirSync(join(outDir, ".dsh-plugin"), { recursive: true })
 
   const version = readPkgVersion()
   // DSH 通过上方 subagent 工具消费 agent 定义；agents/ 目录仍保留原始 markdown 供参考/审计。
   const agents = buildAgents(join(outDir, "agents"))
   const skills = buildSkills(join(outDir, "skills"))
-  bundleMcpServer(outDir)
+  bundleDshNativeTools(outDir)
   copyWorkflows(outDir)
   copyLicense(outDir)
 
@@ -191,6 +200,11 @@ export function buildDeepSeekHarnessPlugin(outDir: string = DEEP_SEEK_HARNESS_PL
         private: true,
         author: PLUGIN_AUTHOR_STRING,
         license: "MIT",
+        // cordis 以裸包名 + 子路径 import 原生工具插件；Node 要求该子路径在 exports 中显式声明
+        // （深层路径直接 import 报 ERR_PACKAGE_PATH_NOT_EXPORTED）。
+        exports: {
+          [DSH_NATIVE_TOOLS_EXPORTS_KEY]: `./${DSH_NATIVE_TOOLS_RELATIVE_PATH}`,
+        },
         dsh: {
           bundle: {
             patch: `./${MANIFEST_PATCH_FILENAME}`,

package/src/adapters/deepseek-harness/native-tools.ts

@@ -0,0 +1,196 @@
+/**
+ * DeepSeek Harness 原生工具插件：把 6 个 opx_* 编排工具注册为 DSH 原生工具。
+ *
+ * 与 MCP 形态的根本差异（本次改造的核心）：
+ * - MCP server 是常驻子进程，启动时只能拿到一份固定的 `--worktree`，与用户当前打开的项目无关；
+ *   DSH 是「单 profile 全局装一份插件、多项目共用同一 MCP server 进程」，该固定目录指向
+ *   `~/.dsh/profiles/desktop`，工具因此报「无法从 tasks.md 解析出任务组」。
+ * - 原生工具在进程内执行，每次调用都能从 `exec.agent.session.header.cwd` 取到本次会话的项目目录，
+ *   目录错配从根上消失（与官方文件工具同一机制，见 dsh-tool-fs/lib/index.js 的 sessionCwd）。
+ *
+ * 业务逻辑不重写：所有编排行为继续由 src/core/tools 下的 *Execute 承担，本文件只做三件事：
+ * 注册名、参数 schema 投影、上下文注入。
+ */
+import type { ToolExecution } from "@deepseek-ai/dsh-tools"
+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 { readStateByWorktree, writeState } from "../../core/state.ts"
+import { jsonSchemaToToolParameters, type ToolParameters } from "./schema-dsl.ts"
+import { OPX_TOOL_SPECS, OPX_TOOL_NAMES } from "../tool-specs.ts"
+
+/**
+ * DSH 工具执行上下文（本插件只消费三处，均已在 DSH 0.2.0-rc.2 源码中核实）：
+ * - agent.session.header.cwd：本次会话的项目目录（会话目录，非进程启动目录）；
+ *   官方文件工具同机制，见 dsh-tool-fs/lib/index.js:161-173 的 sessionCwd。
+ * - agent.id：与 agent.session.id 同值（dsh-agent/lib/index.js:510 的 enter() 校验）。
+ * - signal：协作式取消信号。
+ * 结构用 ambient 声明（src/types/dsh-runtime.d.ts）而非本地手写，避免与官方形状漂移。
+ */
+export type DshToolExec = Pick<ToolExecution, "agent" | "signal">
+
+/** 编排主代理视角的固定身份（与 MCP 侧 resolveContext 缺省口径一致）。 */
+export const PRIMARY_AGENT = "primary"
+
+/**
+ * 解析调用上下文。
+ *
+ * worktree 取会话项目目录：原生工具每次调用都拿到本次会话自己的 cwd，多项目共用同一插件进程时
+ * 各自作用于各自的项目。
+ *
+ * 会话目录缺失时**不静默降级**：DSH 进程的 cwd 正是 profile 目录（如 ~/.dsh/profiles/desktop），
+ * 恰是本次改造要消灭的那个错误目录——静默降级等于把原缺陷（状态写进错误目录且返回成功）以
+ * 无人察觉的方式复现。故 agent 调用路径下取不到会话目录即明确报错，调用方无从「不知情地作用于
+ * 错误目录」；唯一的例外是无 agent 上下文的非 agent 调用（DSH 运行时不会这样调用本工具），
+ * 与官方 dsh-tool-fs 一样不在工具边界读进程 cwd 由后端兜底，此处后端即进程 cwd。
+ *
+ * agent 身份：DSH 未把子代理的注册名（如 openspec_architect）写入 Agent 或 session header——
+ * Agent 只有 { id, options, session, inbox, status, ctx }（见 dsh-agent 的 Agent 接口声明），
+ * subagent/descriptor 事件的 label 来自模型自填的 description（dsh-tool-subagent/lib/index.js:510），
+ * 都不是稳定角色标识。因此按官方可判定的口径分流：
+ * - 调用方通过 `_agent` 显式声明角色名（分派 prompt 中携带，与 MCP 形态同一范式）→ 采用声明值；
+ * - 顶层会话未声明（orchestrator 的正常形态）→ 编排主代理视角（orchestrator: true），
+ *   与 MCP 侧 `_agent` 缺省口径一致；
+ * - 子会话未声明 → 无法判定角色，按编排视角放行但标记身份未声明，
+ *   由 opx_status 视图输出身份补传提示（与 MCP 侧 identityDeclared 兜底同一机制）。
+ */
+export function resolveToolContext(
+  exec: DshToolExec,
+  args: Record<string, unknown>,
+  opts: { processCwd: string },
+): ToolContext {
+  const worktree = resolveSessionWorktree(exec, opts.processCwd)
+  const raw = args[AGENT_ARG]
+  const declared = typeof raw === "string" ? raw : ""
+  const agent = declared !== "" ? declared : PRIMARY_AGENT
+  return {
+    worktree,
+    agent,
+    orchestrator: agent === PRIMARY_AGENT,
+    // 身份未显式声明时置 false：子代理首次查状态会落入编排视角，视图据此追加身份补传提示。
+    // DSH 不暴露子代理的注册名给工具（见上），故此处只能声明「未声明」，无法替其推断角色。
+    identityDeclared: declared !== "",
+  }
+}
+
+/**
+ * 解析本次调用的项目目录。
+ * - 有 agent 上下文：只认 `agent.session.header.cwd`；缺失（undefined / 空串）即报错，
+ *   绝不回落到进程 cwd（进程 cwd 是 DSH profile 目录，回落会把状态写进错误目录）。
+ * - 无 agent 上下文（非 agent 调用）：回落进程 cwd，与官方 dsh-tool-fs 一样把兜底交给后端
+ *   （本工具的后端就是进程自身）。
+ */
+export function resolveSessionWorktree(exec: DshToolExec, processCwd: string): string {
+  const sessionCwd = exec.agent?.session.header.cwd
+  if (typeof sessionCwd === "string" && sessionCwd !== "") return sessionCwd
+  if (exec.agent) {
+    throw new Error(
+      "无法确定本次调用所属的项目目录：DSH 执行上下文未提供 agent.session.header.cwd（会话项目目录）。" +
+        "进程启动目录是 DSH profile 目录（如 ~/.dsh/profiles/desktop），不是任何项目，继续执行会把编排状态写进错误目录，" +
+        "因此本工具拒绝在缺会话目录时执行。请在项目会话中重新调用本工具。",
+    )
+  }
+  return processCwd
+}
+
+/** 私有身份参数：下划线前缀表示非业务参数，与 MCP 形态的 `_agent` 同名同义。 */
+export const AGENT_ARG = "_agent"
+
+/**
+ * 默认无人值守：DSH 形态保持与 MCP 侧一致的默认（DSH patch 分发时开启）。
+ * 会话已初始化且 state.unattended 未设置时自动置 true；幂等，不覆盖用户显式关闭的会话。
+ */
+async function ensureDefaultUnattended(args: Record<string, unknown>, ctx: ToolContext): Promise<void> {
+  const changeId = typeof args.change_id === "string" ? args.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 {
+    // 状态不可读/不可写时静默跳过（不阻断工具主流程）
+  }
+}
+
+/**
+ * 构造 6 个工具的 execute 包装：注入会话上下文与取消信号，业务逻辑直接委托给内核 *Execute。
+ * @param unattended - 是否启用默认无人值守（DSH 分发形态为 true）
+ * @param processCwd - 无 agent 上下文的非 agent 调用时的兜底目录（agent 调用缺会话目录即报错，不兜底）
+ */
+export function buildNativeToolExecutes(
+  unattended: boolean,
+  processCwd: string,
+): Record<string, (args: Record<string, unknown>, exec: DshToolExec) => Promise<string>> {
+  const wrap = (execute: (args: any, ctx: ToolContext) => Promise<string>) =>
+    async (args: Record<string, unknown>, exec: DshToolExec): Promise<string> => {
+      // 取消采用协作式：调度前已取消的调用不进入内核（与 DSH 官方工具一致的 ABORTED_BEFORE_DISPATCH 语义）。
+      exec.signal?.throwIfAborted?.()
+      const ctx = resolveToolContext(exec, args, { processCwd })
+      // 私有身份参数不进入内核参数（内核校验的是纯业务 schema）。
+      const cleanArgs: Record<string, unknown> = { ...args }
+      delete cleanArgs[AGENT_ARG]
+      if (unattended) await ensureDefaultUnattended(cleanArgs, ctx)
+      const result = await execute(cleanArgs, ctx)
+      if (unattended) await ensureDefaultUnattended(cleanArgs, ctx)
+      return result
+    }
+
+  return {
+    opx_orch_init: wrap((args, ctx) => initExecute(args, ctx)),
+    opx_orch_set_worktree: wrap((args, ctx) => setWorktreeExecute(args, ctx)),
+    opx_status: wrap((args, ctx) => statusExecute({ change_id: args.change_id as string }, ctx)),
+    opx_orch_complete_task_group: wrap((args, ctx) => completeTaskGroupExecute(args, ctx)),
+    opx_orch_set_unattended: wrap((args, ctx) => setUnattendedExecute(args, ctx)),
+    opx_agent_submit: wrap((args, ctx) => agentSubmitExecute(args, ctx)),
+  }
+}
+
+export interface NativeToolDefinition {
+  name: string
+  description: string
+  parameters: ToolParameters
+  output: { schema: { type: "string" }; render: (args: any, value: string) => { type: "text"; text: string }[] }
+  execute: (args: Record<string, unknown>, exec: DshToolExec) => Promise<string>
+}
+
+/**
+ * 组装 6 个 DSH 原生工具的完整定义（可直接交给 defineTool）。
+ * 参数定义来自内核纯 JSON Schema（src/core/tools/schemas.ts），只做协议形态投影，不复制参数语义。
+ */
+export function buildNativeToolDefinitions(
+  unattended: boolean,
+  processCwd: string,
+): NativeToolDefinition[] {
+  const executes = buildNativeToolExecutes(unattended, processCwd)
+  return OPX_TOOL_SPECS.map((spec) => ({
+    name: spec.name,
+    description: spec.description,
+    // 附加 _agent 身份参数，与 MCP 形态对齐（子代理显式声明自身角色名）。
+    parameters: withAgentArg(jsonSchemaToToolParameters(spec.schema)),
+    output: {
+      // 工具返回体一律 markdown 文本（见 AGENTS.md「工具返回体须为 markdown 格式」）。
+      schema: { type: "string" as const },
+      render: (_args: any, value: string) => [{ type: "text" as const, text: value }],
+    },
+    execute: executes[spec.name]!,
+  }))
+}
+
+/** 附加 _agent 身份参数（仅暴露层，模型侧可见；内核执行前会剔除）。 */
+function withAgentArg(parameters: ToolParameters): ToolParameters {
+  return {
+    ...parameters,
+    [AGENT_ARG]: {
+      type: "string",
+      description:
+        "调用者 agent 标识（子代理调用时传自身角色名，如 openspec-reviewer-tool；缺省为编排主代理视角）",
+    },
+  }
+}
+
+export { OPX_TOOL_NAMES }

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

@@ -0,0 +1,61 @@
+/**
+ * DSH cordis 插件入口：把 6 个 opx_* 编排工具注册进 DSH 原生工具注册表。
+ *
+ * 挂载方式：bundle 的 cordis.patch.yml 以 `insert` 插入本包（与官方 dsh-skill-filesystem 等行同构）。
+ * 本文件由 `bun build --target node` 打成单文件 `.dsh-plugin/opx-tools.mjs` 随包分发，
+ * `@deepseek-ai/*` 保持 external——插件在 profile 的 node_modules 下被 cordis import 时，
+ * 这些官方包由 DSH 安装目录的 node_modules 提供，不随本包分发。
+ *
+ * cordis 插件契约三处缺一不可（官方 dsh-tool-skill / dsh-tool-fs / dsh-mcp-client 同形）：
+ * - `Config` 必须是 Standard Schema（schemastery 构造）——cordis 直接取 `Config["~standard"].validate`，
+ *   普通对象会在加载期崩于 `Cannot read properties of undefined (reading 'validate')`；
+ * - `inject` 必须声明 apply 内访问的服务——fiber 的上下文代理对未 inject 的属性访问抛
+ *   `cannot get property "tools" without inject`；
+ * - 导出形态为命名导出 `{ Config, apply, inject, name }`，由 loaders 的 unwrapExports 直接取插件对象。
+ *
+ * 与 MCP 形态的差异只有「工具在谁进程里跑」：
+ * - MCP：常驻子进程，worktree 与身份都靠启动参数/入参传入，多项目共用一个进程 → 目录与项目无关；
+ * - 原生：本进程，每次调用从 exec 注入的会话上下文取 worktree 与取消信号，多项目天然隔离。
+ */
+import z from "@deepseek-ai/schemastery"
+import { defineTool, type ToolExecution } from "@deepseek-ai/dsh-tools"
+import { buildNativeToolDefinitions, type DshToolExec } from "./native-tools.ts"
+
+/** DSH 插件配置：cordis 按 Standard Schema 校验并注入默认值。默认无人值守与 MCP 侧 --unattended 同口径。 */
+const Config = z.object({
+  /** 默认无人值守：会话已初始化且未显式设置时自动开启。默认 true，与 MCP 侧 --unattended 同口径。 */
+  unattended: z.boolean().default(true),
+})
+
+/** cordis 插件名。 */
+const name = "openspec-opx-tools"
+
+/** cordis 依赖声明：apply 内访问 ctx.tools，未声明即抛「cannot get property "tools" without inject」。 */
+const inject = ["tools"]
+
+/**
+ * 插件主体：注册 6 个 opx_* 原生工具。
+ *
+ * worktree 每次调用从 `exec.agent.session.header.cwd` 取会话项目目录（该字段缺失即报错，不静默回落进程 cwd）；
+ * `exec.signal` 在每次调用入口检查取消；调用者身份由 `_agent` 入参声明（缺省=编排主代理视角）。
+ */
+function apply(ctx: any, config: { unattended?: boolean } = {}): void {
+  const unattended = config.unattended !== false
+  // 进程 cwd 仅用于「无 agent 上下文的非 agent 调用」兜底；agent 调用缺会话目录时工具直接报错。
+  const processCwd = process.cwd()
+  for (const spec of buildNativeToolDefinitions(unattended, processCwd)) {
+    ctx.tools.register(
+      defineTool({
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.parameters,
+        output: spec.output,
+        async execute(args: any, exec: ToolExecution) {
+          return await spec.execute(args as Record<string, unknown>, exec as unknown as DshToolExec)
+        },
+      }),
+    )
+  }
+}
+
+export { Config, apply, inject, name }

package/src/adapters/deepseek-harness/schema-dsl.ts

@@ -0,0 +1,129 @@
+/**
+ * 内核纯 JSON Schema → DSH 原生工具 schema DSL 的投影。
+ *
+ * DSH 的 `defineTool` 参数不是 draft-07 JSON Schema，而是它自己的统一 schema DSL
+ * （见 dsh-tools/lib/types/schema.js 的 parameterSchemaSpecToJsonSchema）：
+ * - 参数根是「隐式对象」——每个 key 是一个 value schema，必填用 `required: true` 标注在属性上，
+ *   而不是 JSON Schema 的 `required: string[]`；
+ * - value schema 只接受 type(string/number/integer/boolean/null/array/object/json)、properties、
+ *   items、enum、const、oneOf 与注解(description/title/default/examples)。
+ *
+ * DSH 强制执行的 raw JSON Schema 子集不含 minLength / minItems / minimum / maximum
+ * （见 dsh-tools/lib/types/json-schema.js 的 CONSTRAINT_KEYWORDS），这些约束无法在该层表达，
+ * 故按 DSH 官方口径丢弃并降级为描述文本：参数的业务语义与运行时校验仍以内核 *Execute 为准
+ * （内核对同一份 JSON Schema 定义的必填/取值做二次校验）。
+ */
+
+/**
+ * DSH schema DSL 的 value schema。
+ *
+ * 形态与 DSH 官方 dsh-tools 的 ValueSchemaSpec 对齐（见 dsh-tools/lib/types/schema.js 的
+ * runSchemaCompiler）：类型用 `type`，必填用属性上的 `required: true`（而非 required 数组），
+ * 并且只接受 type/properties/items/enum/const/oneOf 与注解字段——多一个 key 即报作者错误。
+ *
+ * 声明为 type alias 而非 interface：type alias 的隐式索引签名使其可直接赋给
+ * `ParameterSchemaSpec`（官方形状为开放记录），interface 则不满足索引签名约束。
+ */
+export type DshValueSchema = {
+  type: "string" | "number" | "integer" | "boolean" | "null" | "array" | "object" | "json"
+  description?: string
+  default?: unknown
+  properties?: Record<string, DshValueSchema>
+  /** 必填标注：DSH DSL 用属性上的 `required: true`，内核 JSON Schema 用根上的 required 数组。 */
+  required?: true
+  items?: DshValueSchema
+  enum?: readonly (string | number | boolean)[]
+  additionalProperties?: boolean
+}
+
+/** DSH 工具的 parameters：一个隐式对象根的「属性名 → value schema」映射。 */
+export type ToolParameters = Record<string, DshValueSchema>
+
+/** 内核纯 JSON Schema（draft-07 子集），与 src/core/provider.ts 的 JSONSchema 同形。 */
+export interface CoreJsonSchema {
+  type?: string
+  description?: string
+  properties?: Record<string, CoreJsonSchema>
+  items?: CoreJsonSchema
+  required?: readonly string[]
+  enum?: readonly (string | number | boolean)[]
+  default?: unknown
+  additionalProperties?: boolean
+}
+
+/** DSH 原生不支持的约束关键字（丢弃并降级为描述，避免模型看不到约束）。 */
+const UNSUPPORTED_CONSTRAINTS = [
+  { key: "minLength", suffix: "（不得为空）" },
+  { key: "minItems", suffix: "（至少含 1 项）" },
+  { key: "minimum", suffix: "（不小于该值）" },
+  { key: "maximum", suffix: "（不大于该值）" },
+] as const
+
+/** 拼接降级后的描述文本：把无法在 DSH 层表达的约束以自然语言形式追加到 description。 */
+function describeWithDroppedConstraints(schema: CoreJsonSchema): string | undefined {
+  const parts: string[] = []
+  if (typeof schema.description === "string" && schema.description !== "") parts.push(schema.description)
+  for (const { key, suffix } of UNSUPPORTED_CONSTRAINTS) {
+    const value = (schema as Record<string, unknown>)[key]
+    if (typeof value === "number") parts.push(`${key}=${value}${suffix}`)
+  }
+  return parts.length > 0 ? parts.join(" ") : undefined
+}
+
+/** 把一个内核 JSON Schema 节点投影为 DSH value schema。 */
+function projectValueSchema(schema: CoreJsonSchema): DshValueSchema {
+  const description = describeWithDroppedConstraints(schema)
+  const annotation = description !== undefined ? { description } : {}
+  switch (schema.type) {
+    case "object": {
+      const properties = projectProperties(schema)
+      return {
+        type: "object",
+        ...annotation,
+        ...properties,
+        additionalProperties: schema.additionalProperties === true,
+      }
+    }
+    case "array":
+      return {
+        type: "array",
+        ...annotation,
+        // DSH 的 array 节点要求 items；内核允许省略（等价于 string），此处按 DSH 口径补齐。
+        items: schema.items !== undefined ? projectValueSchema(schema.items) : { type: "string" },
+      }
+    case "string":
+    case "number":
+    case "integer":
+    case "boolean":
+    case "null":
+      return {
+        type: schema.type,
+        ...annotation,
+        ...(Array.isArray(schema.enum) ? { enum: [...schema.enum] } : {}),
+        ...(schema.default !== undefined ? { default: schema.default } : {}),
+      }
+    default:
+      // 内核 schema 未声明 type（无约束对象）时按 DSH 的无约束 JSON 节点投影。
+      return { type: "json", ...annotation }
+  }
+}
+
+/** 投影对象节点的 properties，并按内核 required 列表把必填项标注为 `required: true`。 */
+function projectProperties(schema: CoreJsonSchema): { properties: Record<string, DshValueSchema> } | Record<string, never> {
+  const source = schema.properties ?? {}
+  const required = new Set(schema.required ?? [])
+  const properties: Record<string, DshValueSchema> = {}
+  for (const [key, sub] of Object.entries(source)) {
+    const projected = projectValueSchema(sub)
+    properties[key] = required.has(key) ? { ...projected, required: true } : projected
+  }
+  return Object.keys(properties).length > 0 ? { properties } : {}
+}
+
+/**
+ * 把一份内核纯 JSON Schema（工具参数根）投影为 DSH 工具 parameters。
+ * 参数根恒为对象：DSH 的 parameters 就是属性映射本身，不再额外包一层 object。
+ */
+export function jsonSchemaToToolParameters(schema: CoreJsonSchema): ToolParameters {
+  return projectProperties(schema).properties ?? {}
+}

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

@@ -4,7 +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 这类短名）
+ * - --strip-opx-prefix 去掉 MCP 工具名的 opx_ 前缀（得到 status 这类短名，供 MCP client 桥接形态使用）
  *
  * 运行：node <entry> --transport stdio --worktree . --unattended
  */

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

@@ -18,12 +18,9 @@ import {
   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"
+import { OPX_TOOL_SPECS } from "../tool-specs.ts"
 
 /** 私有身份参数：附加到每个工具的 MCP 暴露 schema（下划线前缀表示非业务参数）。 */
 const AGENT_ARG = "_agent"
@@ -34,45 +31,21 @@ interface ToolSpec {
   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 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式：首次新建状态时固化；已开始的变更仅切组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）时可更新，其余场景传不同 mode 报错。",
-    schema: orchInitSchema,
-    execute: (args, ctx) => initExecute(args as any, ctx),
-  },
-  opx_orch_set_worktree: {
-    description:
-      "确保目标组的 git worktree 就绪。change 会话按 change 模型 create-or-reuse：分支 change/{changeId} 不存在时从基准分支 tip 创建，worktree 常驻于 .worktree/{changeId}/ws，全部任务组串行复用（复用校验：目录缺失自愈重建、openspec 文档脏自动提交、代码文件脏拒绝）。只补齐资源，不改变阶段。",
-    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:
-      "完成任务组收尾。非最后任务组仅做门禁与范围标记（不合并、不销毁）；最后一个任务组收口时把 change 分支（change/{changeId}）一次性合并回 baseBranch（漂移无害——文档、openspec 规划路径或仅版本号变更的 package.json——时直接合并收口；漂移含任一其他文件或文本冲突时回退到收尾验证 verify_cleanup 并返回 blocked），成功后销毁 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),
-  },
+/** 工具名 → 内核执行器；名称与描述取自共享规格表（src/adapters/tool-specs.ts）。 */
+const TOOL_EXECUTORS: Record<string, (args: any, ctx: ToolContext) => Promise<string>> = {
+  opx_orch_init: (args, ctx) => initExecute(args, ctx),
+  opx_orch_set_worktree: (args, ctx) => setWorktreeExecute(args, ctx),
+  opx_status: (args, ctx) => statusExecute({ change_id: args.change_id }, ctx),
+  opx_orch_complete_task_group: (args, ctx) => completeTaskGroupExecute(args, ctx),
+  opx_orch_set_unattended: (args, ctx) => setUnattendedExecute(args, ctx),
+  opx_agent_submit: (args, ctx) => agentSubmitExecute(args, ctx),
 }
 
+/** 规格表与执行器的合并视图，保持 buildMcpServer 的注册遍历不变。 */
+const TOOL_SPECS: Record<string, ToolSpec> = Object.fromEntries(
+  OPX_TOOL_SPECS.map((spec) => [spec.name, { description: spec.description, schema: spec.schema, execute: TOOL_EXECUTORS[spec.name]! }]),
+)
+
 /** 附加 _agent 身份参数到 P1 schema（仅 MCP 暴露层）。 */
 function withAgentArg(schema: JSONSchema): JSONSchema {
   return {