@ifrankwang/openspec-agents 0.144.0 → 0.146.0

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

@@ -29,8 +29,10 @@ export function readPkgVersion(): string {
 /**
  * 构建 MCP server 自包含 bundle（node cli.ts 直跑依赖 node_modules，插件安装后无此环境，
  * 故 bundle 单文件至插件包内，node 直接执行）。打包依赖本机 bun CLI（spawnSync("bun")）。
+ *
+ * 返回 bundle 入口的绝对路径，供调用方记录/断言实际产出位置（各 harness 的 MCP 入口即此文件）。
  */
-export function bundleMcpServer(pluginDir: string): void {
+export function bundleMcpServer(pluginDir: string): string {
   const out = join(pluginDir, ".mcp-server", "cli.mjs")
   mkdirSync(join(pluginDir, ".mcp-server"), { recursive: true })
   // dashboard 页面资源随 bundle 同目录放置（page.ts 按此布局探测）
@@ -52,6 +54,38 @@ export function bundleMcpServer(pluginDir: string): void {
   if (result.status !== 0) {
     throw new Error(`MCP server bundle 失败：${result.stderr ?? result.error?.message ?? "未知错误"}`)
   }
+  return out
+}
+
+/**
+ * 构建 DSH 原生工具插件 bundle（node 直接被 cordis import，不依赖 node_modules）。
+ *
+ * 与 bundleMcpServer 的差异：DSH 官方包（@deepseek-ai/*）必须保持 external——它们由 DSH 安装目录
+ * 提供，插件在 profile 的 node_modules 下被 import 时由 DSH 进程自身解析；本项目内核与其余依赖
+ * 全部内联，使插件包无需附带任何 node_modules。
+ */
+export function bundleDshNativeTools(pluginDir: string): void {
+  const outDir = join(pluginDir, ".dsh-plugin")
+  mkdirSync(outDir, { recursive: true })
+  const result = spawnSync(
+    "bun",
+    [
+      "build",
+      resolve("src", "adapters", "deepseek-harness", "plugin.ts"),
+      "--outfile",
+      join(outDir, "opx-tools.mjs"),
+      "--target",
+      "node",
+      "--external",
+      "@deepseek-ai/*",
+      "--define",
+      `__OPX_PKG_VERSION__="${readPkgVersion()}"`,
+    ],
+    { encoding: "utf-8", stdio: ["ignore", "ignore", "pipe"] },
+  )
+  if (result.status !== 0) {
+    throw new Error(`DSH 原生工具插件 bundle 失败：${result.stderr ?? result.error?.message ?? "未知错误"}`)
+  }
 }
 
 /** 转换 agents：从 assets/agents/*.md 取子代理（排除主代理模板），frontmatter 仅保留 name/description。 */

package/src/adapters/tool-specs.ts

@@ -0,0 +1,75 @@
+/**
+ * 6 个 opx_* 工具的名称、描述与参数 schema 单一事实源（DRY）。
+ *
+ * MCP 形态（claude-code / codex / zcode / opencode 外的各 harness）与 DSH 原生工具形态
+ * 消费同一张表：描述文案与参数 schema 只在此定义一次，任一形态改动不会与另一形态漂移。
+ * 两种承载的差异只在参数投影与上下文注入（见各自 adapter）。
+ */
+import type { JSONSchema } from "../core/provider.ts"
+import {
+  orchInitSchema, setWorktreeSchema, statusSchema,
+  completeTaskGroupSchema, setUnattendedSchema, agentSubmitSchema,
+} from "../core/tools/schemas.ts"
+
+export interface OpxToolSpec {
+  /** 工具注册名（DSH 原生与 MCP 一律 opx_ 前缀）。 */
+  name: string
+  description: string
+  schema: JSONSchema
+}
+
+export const OPX_TOOL_NAMES = [
+  "opx_orch_init",
+  "opx_orch_set_worktree",
+  "opx_status",
+  "opx_orch_complete_task_group",
+  "opx_orch_set_unattended",
+  "opx_agent_submit",
+] as const
+
+/** 6 个工具的规格表，顺序即注册顺序。 */
+export const OPX_TOOL_SPECS: readonly OpxToolSpec[] = [
+  {
+    name: "opx_orch_init",
+    description:
+      "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式：首次新建状态时固化；已开始的变更仅切组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）时可更新，其余场景传不同 mode 报错。",
+    schema: orchInitSchema,
+  },
+  {
+    name: "opx_orch_set_worktree",
+    description:
+      "确保目标组的 git worktree 就绪。change 会话按 change 模型 create-or-reuse：分支 change/{changeId} 不存在时从基准分支 tip 创建，worktree 常驻于 .worktree/{changeId}/ws，全部任务组串行复用（复用校验：目录缺失自愈重建、openspec 文档脏自动提交、代码文件脏拒绝）。只补齐资源，不改变阶段。",
+    schema: setWorktreeSchema,
+  },
+  {
+    name: "opx_status",
+    description:
+      "统一状态/上下文查询（只读为主）。按调用者角色路由：编排视角→统计+worktree；architect→spec/blocker；developer→worktree/boundary/task/issue；reviewer-tool→tool 层控件 issue；reviewer-task→task 验证状态；quality reviewer→自维度既有 issue。",
+    schema: statusSchema,
+  },
+  {
+    name: "opx_orch_complete_task_group",
+    description:
+      "完成任务组收尾。非最后任务组仅做门禁与范围标记（不合并、不销毁）；最后一个任务组收口时把 change 分支（change/{changeId}）一次性合并回 baseBranch（漂移无害——文档、openspec 规划路径或仅版本号变更的 package.json——时直接合并收口；漂移含任一其他文件或文本冲突时回退到收尾验证 verify_cleanup 并返回 blocked），成功后销毁 worktree 并删分支。须在收尾验证（verify_cleanup）通过后调用。主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
+    schema: completeTaskGroupSchema,
+  },
+  {
+    name: "opx_orch_set_unattended",
+    description:
+      "开启/关闭无人值守模式。开启后编排流程不再向用户提问：analyze 确认模式由架构师自行裁决（不确认用户）；重试检查点、状态异常、blocker 处理等需拍板事项由主代理按编排行为准则自行决策并提交——检查点决策是 opx_agent_submit 工具调用，主代理可自行执行，不因无人值守而抑制。",
+    schema: setUnattendedSchema,
+  },
+  {
+    name: "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,
+  },
+]
+
+/** 规格表查表。 */
+export function opxToolSpec(name: string): OpxToolSpec {
+  const spec = OPX_TOOL_SPECS.find((s) => s.name === name)
+  if (!spec) throw new Error(`未注册的 opx 工具：${name}`)
+  return spec
+}

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

@@ -0,0 +1,162 @@
+/**
+ * DSH 运行时包的类型声明（ambient）。
+ *
+ * `@deepseek-ai/*` 由 DSH 安装目录在运行时提供（DSH 进程自身解析 node_modules），本项目
+ * 不把它们作为运行期/打包依赖——原生工具插件 bundle 把它们标记为 external，打包后仍从 DSH 进程解析。
+ * 例外：`@deepseek-ai/schemastery` 另以 devDependency 固定为 DSH 运行时同版本，供插件测试用
+ * 真实 Standard Schema 实现校验 Config；它同样不参与打包（仅在测试进程内解析）。
+ * 此处只按官方公开的类型形状声明本地所需的最小子集，使 typecheck 可在无 DSH 安装的环境通过。
+ *
+ * 本文件不写任何顶层 export/import（保持为全局脚本文件），否则其中的 `declare module`
+ * 会被 TypeScript 当作模块增强而非 ambient 声明。
+ *
+ * 形状依据（DSH 0.2.0-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/
+ *   agent/parent/schema/arguments）
+ * - Agent：dsh-agent 的 Agent 接口声明（id/options/session/inbox/status/ctx）
+ * - SessionHeader：dsh-session 的 SessionHeader 声明（id/cwd/parentSession/origin/agentPreset/...）
+ * - schemastery 的 Standard Schema 接口：schemastery/src/index.ts:154、290（`~standard` getter）
+ */
+
+declare module "@deepseek-ai/schemastery" {
+  /** Standard Schema 的校验问题项（失败时返回）。 */
+  export interface SchemaIssue {
+    readonly message: string
+    readonly path?: readonly unknown[]
+  }
+
+  /** Standard Schema v1 的校验结果：成功带 value，失败带 issues。 */
+  export interface SchemaResult<T = any> {
+    readonly value?: T
+    readonly issues?: readonly SchemaIssue[]
+  }
+
+  /**
+   * schemastery schema 节点。本项目只消费两处：
+   * - `~standard`：cordis 校验插件 Config 的唯一入口（cordis/lib/index.js:956-962 取
+   *   `Config["~standard"].validate`，故 Config 必须是本类型而非普通对象）；
+   * - 链式约束 `default`：给未提供的配置项注入默认值。
+   */
+  export interface Schema<T = any> {
+    readonly "~standard": {
+      readonly version: 1
+      readonly vendor: "schemastery"
+      validate(value: unknown): SchemaResult<T>
+    }
+    default(value: T): Schema<T>
+    required(): Schema<T>
+    description(text: string): Schema<T>
+  }
+
+  /**
+   * 根导出即 schemastery 的 `Schema` 本身（可调用/可 new，带 schema 工厂静态方法）。
+   * 这里以工厂对象表达本项目用到的最小集合。
+   */
+  export const Schema: {
+    object<T extends Record<string, any> = Record<string, any>>(dict: { [K in keyof T]: Schema<T[K]> }): Schema<T>
+    boolean(): Schema<boolean>
+    number(): Schema<number>
+    string(): Schema<string>
+    array<T>(inner: Schema<T>): Schema<T[]>
+    dict<T>(inner: Schema<T>): Schema<Record<string, T>>
+    any<T = any>(): Schema<T>
+    const<T>(value: T): Schema<T>
+  }
+  export default Schema
+}
+
+declare module "@deepseek-ai/dsh-tools" {
+  /** DSH 会话头（dsh-session 的 SessionHeader）。 */
+  export interface DshSessionHeader {
+    readonly id: string
+    readonly cwd?: string
+    readonly parentSession?: string
+    readonly origin?: "subagent"
+    readonly delegationDepth?: number
+    readonly agentPreset?: string
+  }
+
+  export interface DshSession {
+    readonly id: string
+    readonly header: DshSessionHeader
+  }
+
+  /** DSH 运行时 Agent（本项目只读 id 与 session）。 */
+  export interface DshAgent {
+    readonly id: string
+    readonly session: DshSession
+  }
+
+  /**
+   * 工具执行上下文。本项目只消费 `signal` 与 `agent` 两处：
+   * - agent.session.header.cwd 是会话项目目录的唯一来源（原生工具解析 worktree 的依据）。
+   * - signal 是协作式取消信号。
+   */
+  export interface ToolExecution {
+    token: symbol
+    callId: string
+    rootCallId?: string
+    name: string
+    signal: AbortSignal
+    agent?: DshAgent
+    parent?: DshAgent
+    arguments?: unknown
+  }
+
+  /** DSH 工具内容块（模型可见的返回体）。 */
+  export interface ToolContentBlock {
+    type: "text"
+    text: string
+  }
+
+  /**
+   * DSH 统一 schema DSL 的 value schema / 参数 schema 根。
+   * 官方按「未知 key 即作者错误」的封闭词汇编译，这里以开放索引签名表达，
+   * 使本项目投影出的强类型 value schema 可直接赋值。
+   */
+  export interface ValueSchemaSpec {
+    [key: string]: unknown
+  }
+  export type ParameterSchemaSpec = Record<string, ValueSchemaSpec>
+
+  export interface ToolOutput<Args = any> {
+    schema: ValueSchemaSpec
+    render: (args: Args, value: any) => ToolContentBlock[]
+  }
+
+  export interface ToolDefinition<Args = any> {
+    name: string
+    description: string
+    parameters: ParameterSchemaSpec
+    output: ToolOutput<Args>
+    execute(args: Args, exec: ToolExecution): unknown
+  }
+
+  export function defineTool<Args = any>(options: {
+    name: string
+    description: string
+    parameters: ParameterSchemaSpec
+    output: ToolOutput<Args>
+    execute(args: Args, exec: ToolExecution): unknown
+    timeoutMs?: number
+    deferLoading?: boolean
+    presentCall?: (args: Args) => unknown
+    presentResult?: (args: Args, result: unknown) => unknown
+    isConcurrencySafe?: (args: Args) => boolean
+  }): ToolDefinition<Args>
+
+  /** 工具注册表服务（本项目只用 register）。 */
+  export interface ToolRegistry {
+    register(definition: ToolDefinition): unknown
+  }
+}
+
+declare module "@deepseek-ai/cordis" {
+  /** 本项目插件只用到 ctx.tools；其余 cordis 服务不消费。 */
+  export interface Context {
+    tools: import("@deepseek-ai/dsh-tools").ToolRegistry
+    [key: string]: any
+  }
+}