dsh-minimal-ptc 0.5.5 → 0.5.6

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.5.6 (2026-10-17)
+
+- 修复固定完整提示词覆盖 PTC 工具清单与执行说明的问题：保留极简人格，调用宿主官方 SDK 生成器，模型能看到当前可调用工具的参数和返回类型。
+- 按宿主执行模式切换默认函数体与持久 REPL 指引；工具启停后重新生成，不捆绑额外核心运行时，也不增加模型调用。
+- 完整提示词不对工具说明中的花括号进行变量插值，继续关闭工作区与可选运行时上下文。验证范围见 [本次记录](docs/validation-0.5.6.md)。
+
 ## 0.5.5 (2026-10-15)
 
 - 修复 DSH 0.2.1-alpha.3 移除子代理 `toolFilter` 后预设挂载失败；子代理仍由官方定时工具拒绝使用提醒，主代理保持定时能力。

package/README.en.md

@@ -13,6 +13,7 @@ Feedback and contributions are welcome: report [issues](https://github.com/STARD
 ## What it does
 
 - Use the official run_code entry for multi-step tool calls.
+- Keep the minimal identity and generate the official SDK for the current tools and runtime mode.
 - Keep files, search, skills, plans, goals and subagent tools.
 - Offer Git Bash and the official persistent PowerShell on Windows.
 

package/README.md

@@ -13,6 +13,7 @@
 ## 功能
 
 - 以官方 run_code 入口编排多步工具调用。
+- 保留极简人格，按当前工具和执行模式生成官方 SDK 说明。
 - 保留文件、检索、技能、计划、目标和子代理能力。
 - Windows 提供 Git Bash 与官方持久 PowerShell。
 

package/docs/USAGE.en.md

@@ -10,7 +10,7 @@ Scheduling tools wait for the host's `schedule` service to activate, avoiding pr
 
 ## Install and use
 
-Version 0.5.x requires **Harness 0.1.7 or later**. This iteration compares the official **0.2.1-alpha.3** source. Use `dsh-minimal-ptc@0.4.7` on Harness 0.1.5/0.1.6.
+Version 0.5.x requires **Harness 0.1.7 or later**. The current comparison uses official **0.2.1-alpha.5** source. Use `dsh-minimal-ptc@0.4.7` on Harness 0.1.5/0.1.6.
 
 ```bash
 dsh plugin --profile web add dsh-minimal-ptc
@@ -22,7 +22,9 @@ For example: “Run this project’s tests, find the failures and fix them.” E
 
 ## Official presets and extensions
 
-The core prompt matches the official Minimal preset. PTC presentation and the `run_code` entry follow the official PTC preset, registered through the host's declarative preset service. Compare [Minimal](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.3/packages/bundle/web-app/presets/minimal.patch.yml) and [PTC](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.3/packages/bundle/web-app/presets/ptc.patch.yml).
+The identity keeps the official Minimal sentence and adds the SDK needed to execute PTC programs. The host's official generator renders the currently visible tools, argument types and return types for the active execution mode. Per-call programs can use `return` and `console.log`; persistent programs use the host's REPL instructions. Compare [Minimal](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.5/packages/bundle/web-app/presets/minimal.patch.yml) and [PTC](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.5/packages/bundle/web-app/presets/ptc.patch.yml).
+
+Version 0.5.6 fixes the old complete persona dropping the SDK. The minimal identity and required SDK now form the complete prompt, while unrelated workspace and optional runtime guidance stay excluded. SDK size grows with the enabled tools, so this is larger than the plain one-line Minimal prompt.
 
 The following extensions make its defaults differ from the stock PTC preset:
 

package/docs/USAGE.md

@@ -10,7 +10,7 @@
 
 ## 安装和使用
 
-0.5.x 需要 **Harness 0.1.7 及以上**，本次对照 **0.2.1-alpha.3** 的官方源码。仍使用 Harness 0.1.5/0.1.6 时，请安装 `dsh-minimal-ptc@0.4.7`。
+0.5.x 需要 **Harness 0.1.7 及以上**，当前对照 **0.2.1-alpha.5** 的官方源码。仍使用 Harness 0.1.5/0.1.6 时，请安装 `dsh-minimal-ptc@0.4.7`。
 
 ```bash
 dsh plugin --profile web add dsh-minimal-ptc
@@ -22,7 +22,11 @@ dsh plugin --profile web add dsh-minimal-ptc
 
 ## 官方预设与扩展
 
-核心提示词与官方 Minimal 一致，PTC 工具展示与 `run_code` 入口沿用官方 PTC，通过官方声明式预设服务注册。对照源码：[Minimal](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.3/packages/bundle/web-app/presets/minimal.patch.yml)、[PTC](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.3/packages/bundle/web-app/presets/ptc.patch.yml)。
+人格保留官方 Minimal 的一句身份说明，另附 PTC 执行必需的工具 SDK；通过官方声明式预设服务注册。SDK 从宿主按当前可见工具和执行模式动态生成，包含工具参数和返回类型。默认执行可使用 `return` / `console.log`；持久执行采用宿主的 REPL 指引。对照源码：[Minimal](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.5/packages/bundle/web-app/presets/minimal.patch.yml)、[PTC](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.5/packages/bundle/web-app/presets/ptc.patch.yml)。
+
+0.5.6 修复了旧的固定完整提示词会覆盖 SDK 的问题。极简人格与必需的 SDK 一起组成完整提示词，其他工作区和运行时指引仍不自动追加。
+
+SDK 大小随启用的工具数量增长，因此会比纯粹一句话的 Minimal 占用更多上下文。保留所需的插件即可缩小工具清单。
 
 本插件保留以下扩展，因此与官方 PTC 的默认开关并非完全相同：
 

package/docs/VALIDATION.md

@@ -2,6 +2,10 @@
 
 本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
 
+## 2026-10-17：0.5.6 工具 SDK 修复
+
+真实宿主复现旧版只有身份句、没有工具 SDK 的问题。新版保留极简身份与必需的官方 SDK，按作用域和运行格式生成；默认和持久模式的真实桥接执行通过。25 项本地测试通过、1 项 Windows 平台跳过，详见 [本次记录](validation-0.5.6.md)。模型自主选工具与原生桌面仍未测。
+
 ## 2026-10-05：0.5.4 启动与可见操作
 
 - Windows 自动测试：22 通过、1 按环境跳过。覆盖旧宿主不导入定时模块、服务延迟到达及模块失败的回报。

package/docs/validation-0.5.6.md

@@ -0,0 +1,23 @@
+# 0.5.6 验证记录
+
+2026-10-17，Windows / Node 24.16.0，官方 DSH 0.2.1-alpha.5。
+
+## 修复的问题
+
+从公开 npm 安装 0.5.5 后，真实 Agent 的模型入口为 `run_code`，但完整提示词只有极简身份句，缺少可调用工具 SDK。直接注册、挂载预设及脚本知道工具名时的执行均可通过，因此只检查工具数量不能证明模型能使用它们。
+
+0.5.6 将极简身份句和宿主实时生成的 PTC SDK 合并为完整提示词。通过宿主 Loader 读取官方生成器，以当前作用域的公开工具清单和输出契约生成参数、返回值与执行说明；没有调用宿主私有方法，也没有复制另一份核心依赖。仍不附加工作区指令和可选运行时上下文。
+
+SDK 占用的上下文随工具清单增长；修复后的提示词不再只有一句话。SDK 中的文字不进行模板变量插值。
+
+## 已验证
+
+- 本地 26 项测试：25 通过，1 项 POSIX 执行测试在 Windows 跳过。新增用例覆盖动态工具启停、作用域、运行格式、输出类型、模板字面量、缺少契约和资源清理。
+- 公开旧版基线：模型提示词缺少 SDK，验收明确失败；合成脚本已知工具名时仍能执行并返回 42，说明“能执行”和“模型看得到声明”是两项证据。
+- 修复后真实 DSH Agent 的模型入口仍只有 `run_code`；提示词含当前工具 SDK，能看见合成工具声明。
+- 默认函数体执行：TypeScript 类型标注、嵌套工具调用、`console.log` 与 `return` 均成功，返回值为 42；下一次执行不保留前一次局部变量。
+- 可选持久模式：实际调用得到 41 → 42；不同 owner 的变量隔离，释放后清空；SDK 没有误写成函数体的 `return` 指引。
+- alpha.4 的默认与持久执行复测通过，沿用该宿主原有的 SDK 文案；alpha.5 使用新版按执行格式区分的指引。
+- 发布前从本地 tarball 经官方 CLI 独立安装，默认与持久桥接均通过；实际网页可在模式菜单中选择极简 PTC，无页面或控制台错误。
+
+上述实际执行使用隔离的合成会话和 Full 权限，未更改用户会话或系统权限。没有调用真实模型，不能据此宣称模型自主选工具已经验收；原生桌面窗口也未操作。源码回归、CI、最终 npm 包与安装验收分别核对。

package/lib/index.js

@@ -60,7 +60,7 @@ function materialize(logger, modernRuntime) {
     return
   }
 
-  for (const file of ['agent.cordis.yml', 'preset.yml', 'gitbash-executor.mjs', 'schedule-tools.mjs']) {
+  for (const file of ['agent.cordis.yml', 'preset.yml', 'gitbash-executor.mjs', 'schedule-tools.mjs', 'ptc-persona.mjs']) {
     let content = readFileSync(join(presetSourceDir, file), 'utf8')
     if (modernRuntime && file === 'agent.cordis.yml') {
       content = content.replaceAll('workflow-worker-thread', 'workflow-ptc')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-minimal-ptc",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "把官方极简提示词与 PTC 编排组合起来，提供完整插件工具和 Windows 终端适配。",
   "type": "module",
   "main": "lib/index.js",
@@ -12,6 +12,7 @@
     "./package.json": "./package.json",
     "./gitbash-executor": "./presets/ptc-minimal/gitbash-executor.mjs",
     "./schedule-tools": "./presets/ptc-minimal/schedule-tools.mjs",
+    "./ptc-persona": "./presets/ptc-minimal/ptc-persona.mjs",
     "./persistent-node.patch.yml": "./presets/ptc-minimal/persistent-node.patch.yml"
   },
   "files": [

package/presets/ptc-minimal/agent.cordis.yml

@@ -5,10 +5,10 @@
 # PTC tool presentation (`tool-presentation` with `mode: ptc`), where the
 # model composes a TypeScript program against a generated SDK and `run_code`
 # executes it. What differs is the persona row, taken verbatim from `minimal`:
-# a fixed one-line persona marked `complete: true` with
-# `includeRuntimeContext: false`, so global identity, Web orientation, tool
-# guidance, and later assembly listeners cannot add prompt text, and runtime
-# context snapshots are suppressed. The `agent-instructions` row from `ptc` is
+# a fixed one-line identity plus the Host-generated PTC SDK, marked complete
+# with `includeRuntimeContext: false`. Other identity and workspace guidance
+# cannot add prompt text, and runtime context snapshots are suppressed.
+# The `agent-instructions` row from `ptc` is
 # dropped for the same reason — its workspace instruction baselines would add
 # user-role text the minimal prompt policy excludes.
 #
@@ -18,10 +18,9 @@
 
 # ── identity ────────────────────────────────────────────────────────────────
 
-# The persona is the complete system prompt (minimal-mode prompt policy).
-# dsh 0.1.3 renamed the persona config field `text` to `prefix` (required).
+# The complete prompt keeps the minimal identity and the callable tool SDK.
 - id: persona
-  name: '@deepseek-ai/dsh-persona'
+  name: ./ptc-persona.mjs
   config:
     prefix: You are a helpful software engineer assistant.
     complete: true

package/presets/ptc-minimal/preset.yml

@@ -1,2 +1,2 @@
 name: 极简 PTC 模式
-description: 一句固定人格，无运行时上下文与附加指令，保留官方 PTC 的文件、Shell、检索、Skills、计划、目标、定时任务、子代理和工作流能力。Windows 提供持久 PowerShell 与 Git Bash；定时任务仅主代理可用。兼容 Harness 0.1.5 至 0.2.1-alpha.1。
+description: 官方极简人格与动态 PTC 工具说明，不附加工作区和运行时上下文。保留文件、Shell、检索、Skills、计划、目标、定时任务及子代理；Windows 支持 Git Bash 和持久 PowerShell。兼容版本与验证范围见插件说明。

package/presets/ptc-minimal/ptc-persona.mjs

@@ -0,0 +1,32 @@
+// Keep the minimal identity while rendering the callable SDK through the Host.
+// A static complete persona discards tools:sdk, leaving only run_code visible
+// without the declarations its programs need. Do not bundle another core copy.
+export const name = 'ptc-minimal-persona'
+export const inject = ['systemPrompt', 'tools', 'loader']
+
+export async function apply(ctx, config = {}) {
+  const host = await ctx.loader.import('@deepseek-ai/dsh-tools')
+  const prefix = config.prefix ?? 'You are a helpful software engineer assistant.'
+  if (typeof prefix !== 'string') throw new Error('dsh-minimal-ptc: persona prefix must be a string')
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: 'deployment:persona-prefix',
+    order: ctx.systemPrompt.getSectionOrder('DEPLOYMENT_PERSONA_PREFIX'),
+    complete: true,
+    interpolate: false,
+    text: ({ scope }) => {
+      const runtime = ctx.get('ptcRuntime') ?? ctx.get('codeRuntime')
+      const language = runtime?.language ?? 'typescript'
+      const render = language === 'typescript' ? host.renderToolsSdk
+        : language === 'python' ? host.renderToolsSdkPy : undefined
+      if (typeof render !== 'function') throw new Error(`dsh-minimal-ptc: no Host SDK renderer for ${language}`)
+      const schemas = ctx.tools.schemas(scope).filter(tool => tool.name !== 'run_code').map(tool => {
+        const definition = ctx.tools.get(tool.name, scope)
+        if (definition?.output?.schema === undefined) throw new Error(`dsh-minimal-ptc: missing output schema for ${tool.name}`)
+        return { name: tool.name, description: tool.description, parameters: tool.parameters, output: definition.output.schema }
+      })
+      const sdk = render(schemas, runtime?.programFormat ?? 'function-body')
+      return `${prefix}\n\nOnly run_code may be called directly. Call the tools declared below from inside its program.\n\n${sdk}`
+    },
+  }), 'minimal persona with Host PTC SDK')
+  if (!(config.includeRuntimeContext ?? false)) ctx.systemPrompt.suppressRuntimeContext()
+}

package/ptc-minimal.patch.yml

@@ -15,10 +15,10 @@
           # PTC tool presentation (`tool-presentation` with `mode: ptc`), where the
           # model composes a TypeScript program against a generated SDK and `run_code`
           # executes it. What differs is the persona row, taken verbatim from `minimal`:
-          # a fixed one-line persona marked `complete: true` with
-          # `includeRuntimeContext: false`, so global identity, Web orientation, tool
-          # guidance, and later assembly listeners cannot add prompt text, and runtime
-          # context snapshots are suppressed. The `agent-instructions` row from `ptc` is
+          # a fixed one-line identity plus the Host-generated PTC SDK, marked complete
+          # with `includeRuntimeContext: false`. Other identity and workspace guidance
+          # cannot add prompt text, and runtime context snapshots are suppressed.
+          # The `agent-instructions` row from `ptc` is
           # dropped for the same reason — its workspace instruction baselines would add
           # user-role text the minimal prompt policy excludes.
           #
@@ -28,10 +28,9 @@
 
           # ── identity ────────────────────────────────────────────────────────────────
 
-          # The persona is the complete system prompt (minimal-mode prompt policy).
-          # dsh 0.1.3 renamed the persona config field `text` to `prefix` (required).
+          # The complete prompt keeps the minimal identity and the callable tool SDK.
           - id: persona
-            name: '@deepseek-ai/dsh-persona'
+            name: dsh-minimal-ptc/ptc-persona
             config:
               prefix: You are a helpful software engineer assistant.
               complete: true