@ifrankwang/openspec-agents 0.149.1 → 0.150.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.149.1",
+  "version": "0.150.1",
   "description": "OpenSpec companion plugin for AI coding agents (Claude Code, Codex, ZCode, DeepSeek Harness, OpenCode): a stricter proposal standard plus multi-agent implementation and review, gated to production-grade standards",
   "author": "ifrankwang",
   "license": "MIT",

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

@@ -10,9 +10,12 @@
  * - 本包自有的 `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。
+ * - DSH 官方能力：`@deepseek-ai/dsh-skill-filesystem`（skill 根）、子代理委派。
+ *   子代理的角色提示词与工具集由 `@deepseek-ai/dsh-agent-preset` 声明承载，每个物理子代理
+ *   一行 preset + 一行 `@deepseek-ai/dsh-tool-subagent`（以 `agentPreset` 引用前者）——
+ *   DSH 0.2.1 起 `dsh-tool-subagent` 移除了 `persona` / `toolFilter` / 后台模式配置，
+ *   角色与工具组合改由 preset 表达。opx_* 工具不再经 `@deepseek-ai/dsh-mcp-client` 桥接——
+ *   原生插件已直接注册工具，patch 内不挂 MCP client。
  */
 import { writeFileSync, mkdirSync, rmSync, readFileSync, readdirSync } from "node:fs"
 import { join } from "node:path"
@@ -65,7 +68,14 @@ export const DSH_NATIVE_TOOLS_ROW_ID = "openspec-opx-tools"
  */
 export const DSH_SKILLS_DIR_SEGMENTS = ["assets", "skills"] as const
 
-/** 原生工具插件与 skill 根的基础 patch；子代理工具行由 buildDshPatchContent 动态追加。 */
+/**
+ * 原生工具插件与 skill 根的基础 patch。
+ *
+ * 子代理委派工具**不写成静态 patch 行**：DSH 加载器对同一层的条目并行激活，静态工具行会在
+ * preset 声明行注册完成之前校验 `agentPreset`，报 `Unknown agent preset`。改为把
+ * toolName ↔ preset id 清单放进插件配置，由插件在 preset 就绪后动态挂载委派工具
+ * （见 plugin.ts 的 mountSubagentTools），顺序由代码保证。
+ */
 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 下，
@@ -95,6 +105,25 @@ interface DshSubagentEntry {
   config: Record<string, unknown>
 }
 
+/**
+ * YAML `!!js` 表达式节点。
+ *
+ * DSH 的 entry-list 方言把 `!!js <expr>` 解析为延迟求值的表达式（官方 preset 用它做平台分支）。
+ * js-yaml 默认 schema 不认识该标签，故以自定义 Type 承载：dump 时输出 `!!js <expr>` 原文。
+ */
+class DshJsExpression {
+  constructor(readonly expr: string) {}
+}
+
+/** 带 `!!js` 标签的 YAML schema（仅 DSH patch 生成使用）。 */
+const DSH_YAML_SCHEMA = yaml.DEFAULT_SCHEMA.extend([
+  new yaml.Type("tag:yaml.org,2002:js", {
+    kind: "scalar",
+    instanceOf: DshJsExpression,
+    represent: (value: unknown) => (value as DshJsExpression).expr,
+  }),
+])
+
 /** 将 openspec-architect 转换为 openspec_architect 这类 DSH 工具名后缀。 */
 function dshAgentSuffix(name: string): string {
   return name.replace(/^openspec-/, "").replace(/-/g, "_")
@@ -120,19 +149,88 @@ const DSH_SUBAGENT_TOOL_ACCESS_PREAMBLE = `## DSH 工具接入（必读）
   - \`opx_status\`
   - \`opx_agent_submit\`
 - 调用工具时必须携带 \`_agent\` 参数传自身角色名（如 \`openspec-developer\`），否则身份无法判定、会被按编排主代理视角处理。
-- 如果当前工具列表中没有这些工具，请立即调用 \`dev_tool_search\` 搜索 \`opx\`，或一次性解锁：
-  \`\`\`json
-  {"toolNames": ["opx_status", "opx_agent_submit"]}
-  \`\`\`
-  如果计划使用 \`todo_write\` 跟踪任务，也请在同一轮一并解锁。
-- 严禁使用 \`find\` / \`which\` / \`grep\` 等 shell 命令搜索 \`opx\`、\`openspec\`、MCP 配置或安装路径；工具未出现是因为尚未解锁，不是未安装。
-- 解锁后第一件事是调用 \`opx_status\` 获取上下文，不要先探查仓库或读取状态文件。
+- 若工具列表中没有这些工具，不要用 shell 搜索 \`opx\`、\`openspec\`、MCP 配置或安装路径——它们不是被隐藏，而是插件未加载成功，直接向编排者报告。
+- 开始工作前第一件事是调用 \`opx_status\` 获取上下文，不要先探查仓库或读取状态文件。
 `
 
-/** 从 assets/agents/*.md 收集 DSH 子代理工具（跳过主代理模板）。 */
-function collectDshSubagentEntries(): DshSubagentEntry[] {
+/**
+ * 每个子代理的 Agent Preset 组合（DSH 0.2.1 起子代理的角色提示词与工具集由 preset 声明，
+ * `@deepseek-ai/dsh-tool-subagent` 的 `persona` / `toolFilter` 已移除）。
+ *
+ * 该组合是子代理可见的完整工具面：opx_* 原生工具由本包在宿主层全局注册，无需在此重复挂载。
+ */
+function dshSubagentPresetPlugins(editAllowed: boolean): Record<string, unknown>[] {
+  return [
+    {
+      id: "agent-instructions",
+      name: "@deepseek-ai/dsh-agent-instructions",
+      config: { maxBytes: 65536 },
+    },
+    {
+      id: "tool-fs",
+      name: "@deepseek-ai/dsh-tool-fs",
+      ...(editAllowed ? {} : { config: { write: false, edit: false } }),
+    },
+    {
+      id: "tool-fs-search",
+      name: "@deepseek-ai/dsh-tool-fs-search",
+      config: { sampleOverCapGlobResults: false },
+    },
+    {
+      id: "tool-bash",
+      name: "@deepseek-ai/dsh-tool-bash",
+      disabled: new DshJsExpression("process.platform === 'win32'"),
+    },
+    {
+      id: "tool-pwsh",
+      name: "@deepseek-ai/dsh-tool-pwsh",
+      disabled: new DshJsExpression("process.platform !== 'win32'"),
+    },
+    { id: "skill-filesystem", name: "@deepseek-ai/dsh-skill-filesystem" },
+    { id: "tool-skill", name: "@deepseek-ai/dsh-tool-skill" },
+    {
+      id: "tool-todo",
+      name: "@deepseek-ai/dsh-tool-todo",
+      config: { allowParallelInProgress: true },
+    },
+    { id: "tool-ask-user", name: "@deepseek-ai/dsh-tool-ask-user" },
+    { id: "tool-web", name: "@deepseek-ai/dsh-tool-web", config: { fetch: true, searchTimeoutMs: 60000 } },
+    {
+      id: "compaction",
+      name: "cordis:group",
+      group: true,
+      isolate: { compaction: true, toolResultPruner: true },
+      config: [
+        { id: "compaction-basic", name: "@deepseek-ai/dsh-compaction-basic" },
+        {
+          id: "tool-result-pruner",
+          name: "@deepseek-ai/dsh-compaction-tool-result-pruner",
+          config: { thresholdChars: 8192, headChars: 4096, tailChars: 1024 },
+        },
+      ],
+    },
+  ]
+}
+
+/** 子代理委派规格：工具名 + 引用的 preset id（写入插件配置，供动态挂载使用）。 */
+export interface DshSubagentSpec {
+  toolName: string
+  agentPreset: string
+}
+
+/** 解析一个子代理的 preset 声明与委派规格。 */
+interface DshSubagentDefinition {
+  spec: DshSubagentSpec
+  presetEntry: DshSubagentEntry
+}
+
+/**
+ * 从 assets/agents/*.md 收集 DSH 子代理：每个物理子代理生成一个 Agent Preset 声明行，
+ * 以及一份「工具名 + preset id」规格（交给插件动态挂载委派工具）。
+ */
+function collectDshSubagents(): DshSubagentDefinition[] {
   const agentsRoot = resolve("assets", "agents")
-  const entries: DshSubagentEntry[] = []
+  const definitions: DshSubagentDefinition[] = []
   for (const file of readdirSync(agentsRoot)) {
     if (!file.endsWith(".md")) continue
     if (EXCLUDED_AGENTS.has(file)) continue
@@ -142,34 +240,53 @@ function collectDshSubagentEntries(): DshSubagentEntry[] {
     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"] } }
-          : {}),
+    const presetId = `openspec-${suffix.replace(/_/g, "-")}`
+    definitions.push({
+      spec: { toolName: `openspec_${suffix}`, agentPreset: presetId },
+      presetEntry: {
+        id: `openspec-preset-${suffix}`,
+        name: "@deepseek-ai/dsh-agent-preset",
+        config: {
+          id: presetId,
+          name,
+          description,
+          plugins: [
+            { id: "persona", name: "@deepseek-ai/dsh-persona", config: { prefix: persona } },
+            ...dshSubagentPresetPlugins(!denyEditTools(frontmatter)),
+          ],
+        },
       },
     })
   }
-  return entries
+  return definitions
+}
+
+/** 把子代理规格投影为插件配置里的 `subagents` 块（缩进对齐 openspec-opx-tools 行的 config）。 */
+function subagentsConfigYaml(specs: DshSubagentSpec[]): string {
+  if (specs.length === 0) return "        subagents: []"
+  const dumped = yaml.dump(specs, { lineWidth: -1 }).trimEnd().split("\n")
+  return ["        subagents:", ...dumped.map((line) => `          ${line}`)].join("\n")
+}
+
+/** 基础 patch：原生工具插件行带上子代理委派规格，供插件在 preset 就绪后动态挂载。 */
+function buildBasePatchYaml(specs: DshSubagentSpec[]): string {
+  return DSH_BASE_PATCH_YAML.replace(
+    "        unattended: true",
+    `        unattended: true\n${subagentsConfigYaml(specs)}`,
+  )
 }
 
-/** 生成完整的 DSH cordis patch 内容：基础原生工具插件行 + skill 根 + 每个子代理一个 DSH 原生 subagent 工具。 */
+/** 生成完整的 DSH cordis patch 内容：基础原生工具插件行 + skill 根 + 每个子代理的 preset 声明。 */
 export function buildDshPatchContent(): string {
-  const subagents = collectDshSubagentEntries()
-  if (subagents.length === 0) return DSH_BASE_PATCH_YAML
-  const subagentsYaml = yaml
-    .dump(subagents, { lineWidth: -1 })
+  const definitions = collectDshSubagents()
+  const base = buildBasePatchYaml(definitions.map((definition) => definition.spec))
+  if (definitions.length === 0) return base
+  const presetsYaml = yaml
+    .dump(definitions.map((definition) => definition.presetEntry), { schema: DSH_YAML_SCHEMA, lineWidth: -1 })
     .split("\n")
     .map((line) => (line ? `    ${line}` : line))
     .join("\n")
-  return `${DSH_BASE_PATCH_YAML.trimEnd()}\n${subagentsYaml}\n`
+  return `${base.trimEnd()}\n${presetsYaml}\n`
 }
 
 export type DeepSeekHarnessPluginBuildResult = PluginPackageResult

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

@@ -23,9 +23,9 @@ 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。
+ * DSH 工具执行上下文（本插件只消费三处，均已在 DSH 0.2.1-rc.2 源码中核实）：
+ * - agent.session.header.cwd：本次会话的项目目录（会话目录，非进程启动目录）。DSH 0.2.1 起官方
+ *   文件工具改用 `ctx.workingDirectory`（会话内可 cd），编排状态按项目根落盘，故仍取 header.cwd。
  * - agent.id：与 agent.session.id 同值（dsh-agent/lib/index.js:510 的 enter() 校验）。
  * - signal：协作式取消信号。
  * 结构用 ambient 声明（src/types/dsh-runtime.d.ts）而非本地手写，避免与官方形状漂移。

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

@@ -25,6 +25,19 @@ import { buildNativeToolDefinitions, type DshToolExec } from "./native-tools.ts"
 const Config = z.object({
   /** 默认无人值守：会话已初始化且未显式设置时自动开启。默认 true，与 MCP 侧 --unattended 同口径。 */
   unattended: z.boolean().default(true),
+  /**
+   * 子代理委派规格（工具名 + 引用的 preset id），由构建期写入 patch。
+   * 委派工具不写成静态 patch 行：DSH 加载器并行激活同层条目，静态工具行会在 preset 注册前
+   * 校验 `agentPreset` 报 Unknown agent preset；改由插件在 preset 就绪后动态挂载。
+   */
+  subagents: z
+    .array(
+      z.object({
+        toolName: z.string(),
+        agentPreset: z.string(),
+      }),
+    )
+    .default([]),
 })
 
 /** cordis 插件名。 */
@@ -39,7 +52,10 @@ const inject = ["tools"]
  * worktree 每次调用从 `exec.agent.session.header.cwd` 取会话项目目录（该字段缺失即报错，不静默回落进程 cwd）；
  * `exec.signal` 在每次调用入口检查取消；调用者身份由 `_agent` 入参声明（缺省=编排主代理视角）。
  */
-function apply(ctx: any, config: { unattended?: boolean } = {}): void {
+function apply(
+  ctx: any,
+  config: { unattended?: boolean; subagents?: Array<{ toolName: string; agentPreset: string }> } = {},
+): void {
   const unattended = config.unattended !== false
   // 进程 cwd 仅用于「无 agent 上下文的非 agent 调用」兜底；agent 调用缺会话目录时工具直接报错。
   const processCwd = process.cwd()
@@ -56,6 +72,70 @@ function apply(ctx: any, config: { unattended?: boolean } = {}): void {
       }),
     )
   }
+  mountSubagentTools(ctx, config.subagents ?? [])
+}
+
+/** 子代理委派工具所属的官方包（保持 external，由 DSH 安装目录在运行时解析）。 */
+const SUBAGENT_TOOL_PACKAGE = "@deepseek-ai/dsh-tool-subagent"
+
+/** 等待 preset 声明注册完成的上限：注册在启动阶段完成，正常在毫秒级。 */
+const PRESET_READY_TIMEOUT_MS = 3000
+const PRESET_READY_POLL_MS = 50
+
+/**
+ * 轮询等待 preset 声明注册完成。
+ *
+ * `agentPresets.readDocument(id)` 直接读内存声明表：返回成功即表示 preset 行已激活，
+ * 此时再挂载委派工具，工具行的加载期校验必然通过。
+ */
+async function waitForPreset(registry: any, presetId: string, timeoutMs = PRESET_READY_TIMEOUT_MS): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    try {
+      await registry.readDocument(presetId)
+      return true
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, PRESET_READY_POLL_MS))
+    }
+  }
+  return false
+}
+
+/**
+ * 在 preset 就绪后动态挂载子代理委派工具。
+ *
+ * 与静态 patch 行的差异只有挂载时机：本函数先等 `agentPresets` 服务可用、再逐个确认 preset
+ * 已注册，最后才挂 `@deepseek-ai/dsh-tool-subagent` 实例——消除「工具行先于 preset 行激活」
+ * 的加载竞态（DSH 对同层条目并行激活，desktop 多插件下稳定触发）。
+ */
+function mountSubagentTools(ctx: any, specs: Array<{ toolName: string; agentPreset: string }>): void {
+  if (specs.length === 0 || typeof ctx.inject !== "function") return
+  ctx.inject(["agentPresets"], async (injected: any) => {
+    let subagentTool: any
+    try {
+      subagentTool = await import(SUBAGENT_TOOL_PACKAGE)
+    } catch (error) {
+      injected.logger?.warn?.(`openspec: 无法加载 ${SUBAGENT_TOOL_PACKAGE}，子代理委派工具未挂载：${String(error)}`)
+      return
+    }
+    for (const spec of specs) {
+      if (!(await waitForPreset(injected.agentPresets, spec.agentPreset))) {
+        injected.logger?.warn?.(
+          `openspec: agent preset "${spec.agentPreset}" 未在 ${PRESET_READY_TIMEOUT_MS}ms 内注册，跳过子代理工具 ${spec.toolName}`,
+        )
+        continue
+      }
+      try {
+        await injected.plugin(subagentTool, {
+          provider: "spawn",
+          toolName: spec.toolName,
+          agentPreset: spec.agentPreset,
+        })
+      } catch (error) {
+        injected.logger?.warn?.(`openspec: 子代理工具 ${spec.toolName} 挂载失败：${String(error)}`)
+      }
+    }
+  })
 }
 
 export { Config, apply, inject, name }

package/src/types/dsh-runtime.d.ts

@@ -10,7 +10,7 @@
  * 本文件不写任何顶层 export/import（保持为全局脚本文件），否则其中的 `declare module`
  * 会被 TypeScript 当作模块增强而非 ambient 声明。
  *
- * 形状依据（DSH 0.2.0-rc.2 源码）：
+ * 形状依据（DSH 0.2.1-rc.2 源码）：
  * - defineTool 与 schema DSL：dsh-tools/lib/types/schema.js:274
  * - ctx.tools.register：dsh-tools/README.zh.md:41-57
  * - exec 上下文字段：dsh-tools/lib/types/index.js:790-802（token/callId/rootCallId/name/signal/
@@ -154,9 +154,27 @@ declare module "@deepseek-ai/dsh-tools" {
 }
 
 declare module "@deepseek-ai/cordis" {
-  /** 本项目插件只用到 ctx.tools；其余 cordis 服务不消费。 */
+  /** 本项目插件用到的 cordis 能力：工具注册表、依赖注入与子插件挂载；其余服务不消费。 */
   export interface Context {
     tools: import("@deepseek-ai/dsh-tools").ToolRegistry
+    /**
+     * 依赖就绪后执行回调。本插件用它等 `agentPresets` 服务可用，再动态挂载子代理委派工具
+     * （DSH 对同层 patch 条目并行激活，静态工具行会先于 preset 声明校验而失败）。
+     */
+    inject(deps: readonly string[], callback: (ctx: Context) => unknown): unknown
+    /** 挂载子插件。本插件用它挂载官方 `@deepseek-ai/dsh-tool-subagent` 实例。 */
+    plugin(plugin: unknown, config?: unknown): unknown
     [key: string]: any
   }
+}
+
+declare module "@deepseek-ai/dsh-tool-subagent" {
+  /**
+   * 官方子代理委派工具插件（cordis 插件形态：命名导出 name/inject/Config/apply）。
+   * 本插件在 preset 就绪后动态挂载它，故只需声明挂载所需的公开形状。
+   */
+  export const name: string
+  export const inject: readonly string[]
+  export const Config: unknown
+  export function apply(ctx: unknown, config?: unknown): void
 }