dsh-minimal-ptc 0.4.4 → 0.4.7

package/README.en.md

@@ -3,7 +3,7 @@
 ![npm](https://img.shields.io/npm/v/dsh-minimal-ptc) ![downloads](https://img.shields.io/npm/dm/dsh-minimal-ptc) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-minimal-ptc) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-minimal-ptc?style=social)
 
 > Minimal prompt x full PTC capabilities — a cleaner coding agent.
-> Installing gives you a new agent mode: **Minimal PTC**, with Git Bash and persistent PowerShell on Windows, aligned with `dsh-v0.1.2-alpha.4`.
+> Installing gives you a new agent mode: **Minimal PTC**, with Git Bash and persistent PowerShell on Windows, compatible with Harness 0.1.5-rc.2 and 0.1.6-alpha.1.
 
 ## Highlights
 
@@ -11,11 +11,15 @@
 - **Complete PTC surface**: provides `run_code` SDK orchestration, files and search, Shell, Skills, plan mode, goals, subagents, Ralph, and web search/fetch; the general-purpose workflow tool stays hidden as in alpha.4.
 - **We / Let's reasoning**: the PTC SDK packs thinking and doing into one TypeScript program, orchestrating multi-step operations before executing them once. This matches the high-scoring Minimal trajectory in DeepSeek's official Project2 V4.1b runs (99/96), where reasoning is dominated by `we` / `let's` instead of the standard-like `let me` / `I` blocks seen at 91/92.
 - **Git Bash on Windows**: ships a preset-local Git Bash executor (GIT_BASH -> Program Files\Git -> LOCALAPPDATA\Git -> PATH). The bash tool is no longer disabled on Windows.
-- **Persistent PowerShell on Windows**: mirrors the `dsh-v0.1.2-alpha.4` minimal preset; `pwsh` runs as a persistent PTY session, so cwd, variables, and functions survive across calls.
+- **Persistent PowerShell on Windows**: mirrors the `dsh-v0.1.5-rc.1` minimal preset; `pwsh` runs as a persistent PTY session, so cwd, variables, and functions survive across calls.
 
 ## Compatibility
 
-Verified against source-run `@deepseek-ai/dsh@0.1.2-alpha.4` on 2026-09-02. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Verified with official source builds of Harness `0.1.5-rc.2` and `0.1.6-alpha.1` on 2026-09-16: all 18 components load alongside ModLens, with passing tool schemas, skill registration, offline read-only calls, real Agent preset mounting, and plugin calls through `run_code`. Uses the `cordis.patch.yml` + `dsh.bundle.patch` bundle model. Node requirements are 22.19 or later within 22.x, or 24 or later. Live external-service workflows require separate configuration and validation.
+
+Since 0.4.6, the plugin selects the workflow provider after host startup: `workflow-ptc` on 0.1.6 and `workflow-worker-thread` on 0.1.5. Managed presets refresh when the plugin version or host runtime family changes. Local edits on the same version and runtime, and user-created presets without a marker, remain untouched. Since 0.4.7, the preset restores the official 0.1.6 `ptc` rows `present` / `command-goal` / `tool-plugin-manager` (disabled) plus `modelSelectionSettings` on subagent spawn, and a startup health check guards the `reading 'prepare'` failure modes (see Troubleshooting).
+
+The Minimal PTC preset also mounts in a real agent and assembles `run_code` as the model-facing tool while retaining installed plugin tools and Windows Git Bash. Uses the persona `prefix` field introduced in Harness 0.1.3; use plugin 0.4.3 with older Harness versions. Since 0.4.5, the preset update marker reads the package version automatically so upgrades cannot leave an older preset because of a stale hard-coded version.
 
 ## Installation
 
@@ -34,6 +38,29 @@ Verified against source-run `@deepseek-ai/dsh@0.1.2-alpha.4` on 2026-09-02. Buil
 
 4. Select **Minimal PTC** when starting a new session.
 
+## Troubleshooting: `Cannot read properties of undefined (reading 'prepare')`
+
+When every tool call (including `run_code`) fails with this error while sessions mount fine, the root cause is **two identities of the dsh-tools scheduler key (a Symbol) inside one process**. Two confirmed triggers:
+
+1. **A duplicate core package inside a profile**: a third-party plugin lists `@deepseek-ai/*` under `dependencies` (it belongs in `peerDependencies`), a tarball install drags in transitive copies, or stale `node_modules` linger. Check:
+
+   ```bash
+   # Any output means trouble (should be empty)
+   ls ~/.dsh/profiles/*/node_modules/@deepseek-ai 2>/dev/null
+   ```
+
+   Fix: move the `@deepseek-ai` directory out of that profile's `node_modules` (or fix the offending plugin's dependencies and reinstall), then restart dsh.
+
+2. **The 0.1.6-alpha host's own dual build outputs**: the `@deepseek-ai/dsh-tools` exports map routes `./types` and `./presentation` to a second compiled tree (`lib/types/*.js`) next to the bundle (`lib/index.js`) — the key splits even with zero extra copies. The root fix, in `packages/core/tools/src/index.ts`:
+
+   ```ts
+   Symbol('@deepseek-ai/dsh-tools.scheduler')  →  Symbol.for('@deepseek-ai/dsh-tools.scheduler')
+   ```
+
+   `Symbol.for` uses the global symbol registry, so the key stays identical across module instances and both triggers are disarmed.
+
+**Since 0.4.7 this plugin self-checks at startup**: if a profile holds core-package copies, or the host still uses a module-local Symbol key (unpatched), it logs a warning with the matching remediation. Warnings never block startup.
+
 ## Uninstall
 
 ```bash
@@ -67,9 +94,9 @@ Detection order: `GIT_BASH` -> `Program Files\\Git` -> `Program Files (x86)\\Git
 ## Materialization policy
 
 - No target directory -> write all preset files and a version marker.
-- Marker version lower than the plugin version -> refresh from the bundled files.
+- Plugin version or host runtime family changes -> refresh managed files.
 - Directory exists without a marker (treated as user-created) -> leave it untouched.
-- Upgrading: bump `version` in `package.json` and the `VERSION` constant in `lib/index.js`.
+- Upgrading: bump `version` in `package.json`; the marker reads it automatically.
 
 ## License
 

package/README.md

@@ -3,7 +3,7 @@
 ![npm](https://img.shields.io/npm/v/dsh-minimal-ptc) ![downloads](https://img.shields.io/npm/dm/dsh-minimal-ptc) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-minimal-ptc) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-minimal-ptc?style=social)
 
 > 极简提示词 × PTC 全能力 —— 一个更"干净"的编码 Agent。
-> 安装即获得新的 Agent 模式：**极简 PTC 模式**；Windows 自动启用 Git Bash 与持久 PowerShell（对齐 dsh-v0.1.2-alpha.4）。
+> 安装即获得新的 Agent 模式：**极简 PTC 模式**；Windows 自动启用 Git Bash 与持久 PowerShell，兼容 Harness 0.1.5-rc.2 和 0.1.6-alpha.1。
 
 ## 卖点
 
@@ -17,11 +17,15 @@
   Minimal 高分轨迹一致：99/96 的两跑以 `we` / `let's` 为主，而不是
   Standard/PTC 常见的 `let me` / `I` 长块。
 - **Windows 保持 bash**：预设内置 Git Bash executor（自动探测 GIT_BASH → Program Files\Git → LOCALAPPDATA\Git → PATH），`bash` 工具不再在 Windows 上被禁用。
-- **Windows 持久 PowerShell**：对齐 `dsh-v0.1.2-alpha.4` 的 minimal 预设，`pwsh` 使用持久 PTY 会话，cwd、变量、函数跨调用保留。
+- **Windows 持久 PowerShell**：对齐 `dsh-v0.1.5-rc.1` 的 minimal 预设，`pwsh` 使用持久 PTY 会话，cwd、变量、函数跨调用保留。
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.3-alpha.2` 源码模式下验证（2026-09-08；0.4.4 适配 0.1.3 的 persona `text`→`prefix` 字段改名，旧版 dsh 请用 0.4.3）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+已在官方源码构建的 Harness `0.1.5-rc.2` 和 `0.1.6-alpha.1` 上验证（2026-09-16）：18 个组件与 ModLens 同载，工具 schema、技能注册、离线只读调用、真实 Agent 预设挂载及 `run_code` 调用插件工具通过。采用 `cordis.patch.yml` + `dsh.bundle.patch` 组合包模型。Node 要求为 22.19 及以上的 22.x，或 24 及以上。外部服务的实际业务操作需按各组件配置单独验证。
+
+0.4.6 起，插件等待宿主启动完成后选择工作流运行时：0.1.6 使用 `workflow-ptc`，0.1.5 保留 `workflow-worker-thread`。受管理的预设会在插件版本或运行时种类变化时刷新；同版本、同运行时的本地修改以及无版本标记的自建预设保持不变。0.4.7 起预设补齐官方 0.1.6 `ptc` 的 `present` / `command-goal` / `tool-plugin-manager`（默认关闭）行与 subagent 的 `modelSelectionSettings`，并新增启动健康检查（见下文故障排查）。
+
+另已在真实 agent 中挂载极简 PTC 预设并组装模型工具：模型入口为 `run_code`，安装的插件工具和 Windows Git Bash 均可用。沿用 0.1.3 起的 persona `prefix` 字段；更旧的 Harness 请使用插件 0.4.3。0.4.5 起，预设更新标记自动读取包版本，避免升级后仍保留旧预设。
 
 ## 安装
 
@@ -41,6 +45,29 @@
 
 4. 新建会话时选择 **极简 PTC 模式**。
 
+## 故障排查：`Cannot read properties of undefined (reading 'prepare')`
+
+每次工具调用（含 `run_code`）都以这个错误失败、且会话在挂载期一切正常时，根因是 **dsh-tools 的调度器键（一个 Symbol）在进程内出现了两个身份**。两个已确认的触发路径：
+
+1. **profile 里多装了一份核心包**：某个第三方插件把 `@deepseek-ai/*` 写进了 `dependencies`（应为 `peerDependencies`）、tarball 安装拖入传递副本，或旧 `node_modules` 残留。检查：
+
+   ```bash
+   # 任一命令有输出即为中招（应为空）
+   ls ~/.dsh/profiles/*/node_modules/@deepseek-ai 2>/dev/null
+   ```
+
+   修复：把该 profile `node_modules` 下的 `@deepseek-ai` 目录移走（或整改插件依赖后重装），重启 dsh。
+
+2. **0.1.6-alpha 宿主自身的双构建产物**：`@deepseek-ai/dsh-tools` 的 exports 把 `./types`、`./presentation` 子路径指向第二套编译输出（`lib/types/*.js`），与打包产物 `lib/index.js` 并存时调度器键同样分裂——即使没有装任何多余副本也会中招。根治办法是把 `packages/core/tools/src/index.ts` 里的
+
+   ```ts
+   Symbol('@deepseek-ai/dsh-tools.scheduler')  →  Symbol.for('@deepseek-ai/dsh-tools.scheduler')
+   ```
+
+   `Symbol.for` 走全局符号注册表，跨模块实例恒等，两类触发路径同时免疫。
+
+**本插件自 0.4.7 起在启动时自动体检**：发现 profile 内核心包副本、或宿主仍使用模块本地 Symbol 键（未打上述补丁）时，会在日志里给出对应警告与修复指引（只警告，不阻断启动）。
+
 ## 卸载
 
 ```bash
@@ -79,10 +106,8 @@ dsh-minimal-ptc/
 
 ## 说明
 
-- 物化策略：目标目录不存在 → 写入全部文件并留版本标记；版本标记低于当前
-  版本 → 刷新；目录存在但无标记（用户自建）→ 不覆盖。
-- 升级插件：改 `version` 并同步 `lib/index.js` 里的 `VERSION` 常量即可刷新
-  用户根目录里的预设文件。
+- 物化策略：目标目录不存在时写入全部文件；插件版本或宿主运行时种类变化时刷新受管理文件；无标记的自建预设不覆盖。
+- 升级插件只需更新 `package.json` 的版本；预设标记自动读取该版本。
 
 ## 许可证
 

package/lib/index.js

@@ -9,17 +9,26 @@
 //
 // 零运行时依赖：harness home 的解析逻辑内置（DSH_HOME 环境变量优先，
 // 否则 ~/.dsh），与 dsh 官方规则一致。
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import pkg from '../package.json' with { type: 'json' }
 
 export const name = 'ptc-minimal-preset'
+export const inject = ['appReady']
 
-const VERSION = '0.4.4'
+const VERSION = pkg.version
 const PRESET_ID = 'ptc-minimal'
 const MARKER = '.dsh-ptc-minimal.version'
 
+// dsh-tools keys its tool scheduler with this symbol description. On stock
+// hosts it is a module-local Symbol(), so any second dsh-tools instance
+// (duplicate profile copy, or the package's own dual build outputs on
+// 0.1.6-alpha) breaks the agent-loop lookup: every tool call then fails with
+// "Cannot read properties of undefined (reading 'prepare')".
+const SCHEDULER_SYMBOL_DESC = '@deepseek-ai/dsh-tools.scheduler'
+
 const packageDir = fileURLToPath(new URL('..', import.meta.url))
 const presetSourceDir = join(packageDir, 'presets', PRESET_ID)
 
@@ -33,9 +42,10 @@ function dshHomePath(...segments) {
   return resolve(base, ...segments)
 }
 
-function materialize(logger) {
+function materialize(logger, modernRuntime) {
   const dir = dshHomePath('.agent-presets', PRESET_ID)
   mkdirSync(dir, { recursive: true })
+  const revision = modernRuntime ? `${VERSION}:ptc-runtime` : VERSION
 
   let marker = null
   try {
@@ -44,23 +54,114 @@ function materialize(logger) {
     // 无标记：可能是首次安装，也可能是用户自建目录
   }
 
-  if (marker === VERSION) return
+  if (marker === revision) return
   if (marker === null && existsSync(join(dir, 'agent.cordis.yml'))) {
     logger?.warn(`dsh-minimal-ptc: ${dir} exists without our marker; leaving it alone`)
     return
   }
 
   for (const file of ['agent.cordis.yml', 'preset.yml', 'gitbash-executor.mjs']) {
-    writeFileSync(join(dir, file), readFileSync(join(presetSourceDir, file)))
+    let content = readFileSync(join(presetSourceDir, file), 'utf8')
+    if (modernRuntime && file === 'agent.cordis.yml') {
+      content = content.replaceAll('workflow-worker-thread', 'workflow-ptc')
+        .replaceAll('`codeRuntime`', '`ptcRuntime`')
+    }
+    writeFileSync(join(dir, file), content)
   }
-  writeFileSync(join(dir, MARKER), VERSION + '\n')
+  writeFileSync(join(dir, MARKER), revision + '\n')
   logger?.info(`dsh-minimal-ptc: materialized agent preset "${PRESET_ID}" into ${dir}`)
 }
 
 export function apply(ctx) {
+  ctx.effect(() => ctx.appReady.onReady(() => {
+    try {
+      materialize(ctx.logger, ctx.get('ptcRuntime') !== undefined)
+    } catch (error) {
+      ctx.logger?.warn(`dsh-minimal-ptc: preset materialization failed: ${String(error)}`)
+    }
+    try {
+      healthCheck(ctx)
+    } catch (error) {
+      ctx.logger?.warn(`dsh-minimal-ptc: health check failed: ${String(error)}`)
+    }
+  }))
+}
+
+/**
+ * Warn about the two known causes of "Cannot read properties of undefined
+ * (reading 'prepare')" before the first session hits them. Warnings only —
+ * nothing here blocks startup.
+ */
+function healthCheck(ctx) {
+  const logger = ctx.logger
+
+  // Cause 1 (most common in the wild): a plugin or stale install left a
+  // physical copy of @deepseek-ai/* inside some profile's node_modules. The
+  // core must come from the CLI's own dependency tree only.
+  for (const hit of findProfileCoreCopies()) {
+    logger?.warn(
+      `dsh-minimal-ptc: duplicate core package in profile: ${hit}\n`
+      + '  A second @deepseek-ai copy breaks the tool scheduler key (module-local Symbol) '
+      + 'and every tool call fails with "reading \'prepare\'".\n'
+      + '  Fix: remove the @deepseek-ai directory from that profile\'s node_modules '
+      + '(and reinstall the offending plugin with core packages in peerDependencies), then restart.',
+    )
+  }
+
+  // Cause 2 (seen on stock 0.1.6-alpha): the host itself can load two dsh-tools
+  // instances (bundled lib/index.js vs per-module lib/types/*.js). It is safe
+  // only when the scheduler key survives multiple instances, i.e. the host was
+  // built with Symbol.for. Probe exactly that.
+  const status = schedulerKeyStatus(ctx.tools)
+  if (status === 'module-local') {
+    logger?.warn(
+      'dsh-minimal-ptc: this host keys the tool scheduler with a module-local Symbol '
+      + '(unpatched dsh-tools). PTC sessions break with "reading \'prepare\'" '
+      + 'whenever a second dsh-tools instance loads in this process.\n'
+      + '  Fix: rebuild dsh-tools with `Symbol.for(\'@deepseek-ai/dsh-tools.scheduler\')` '
+      + 'in packages/core/tools/src/index.ts, or keep a single dsh-tools copy.',
+    )
+  }
+}
+
+/**
+ * Physical @deepseek-ai copies under any profile's node_modules.
+ * @returns {string[]} paths like "<profile>/node_modules/@deepseek-ai/<pkg>"
+ */
+export function findProfileCoreCopies(home = dshHomePath('profiles')) {
+  const hits = []
+  let profiles = []
   try {
-    materialize(ctx.logger)
-  } catch (error) {
-    ctx.logger?.warn(`dsh-minimal-ptc: preset materialization failed: ${String(error)}`)
+    profiles = readdirSync(home, { withFileTypes: true })
+  } catch {
+    return hits
   }
+  for (const profile of profiles) {
+    if (!profile.isDirectory()) continue
+    const scopeDir = join(home, profile.name, 'node_modules', '@deepseek-ai')
+    let entries = []
+    try {
+      entries = readdirSync(scopeDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) hits.push(join(scopeDir, entry.name))
+    }
+  }
+  return hits
+}
+
+/**
+ * How the host's tool registry exposes the scheduler key:
+ * - 'global'       — Symbol.for key works; safe across duplicate instances.
+ * - 'module-local' — registry carries a same-description local Symbol; the
+ *                    agent loop breaks if a second dsh-tools instance loads.
+ * - 'absent'       — no tools registry / no scheduler mounted (nothing to say).
+ */
+export function schedulerKeyStatus(tools) {
+  if (tools == null || (typeof tools !== 'object' && typeof tools !== 'function')) return 'absent'
+  if (tools[Symbol.for(SCHEDULER_SYMBOL_DESC)] !== undefined) return 'global'
+  const local = Object.getOwnPropertySymbols(tools).some(s => s.description === SCHEDULER_SYMBOL_DESC)
+  return local ? 'module-local' : 'absent'
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-minimal-ptc",
-  "version": "0.4.4",
-  "description": "Minimal prompt x full PTC tools for DeepSeek Harness - aligned with the Project2 we/let's trajectory (Minimal 99/96).",
+  "version": "0.4.7",
+  "description": "DeepSeek Harness 极简 PTC 预设：简洁提示词、run_code 工具编排、完整插件工具，以及 Windows Git Bash 和持久 PowerShell。",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -48,7 +48,7 @@
   },
   "homepage": "https://github.com/STARDUSTLC666/dsh-minimal-ptc#readme",
   "engines": {
-    "node": ">=22"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "scripts": {
     "test": "node --test"

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

@@ -68,7 +68,7 @@
         description: |-
           Run commands in a PowerShell shell
           * When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.
-          * You don't have access to the internet via this tool.
+          * Network access depends on the host environment.
           * State is persistent across command calls and discussions with the user.
           * Use native Windows paths (C:\...) and $env:NAME variables; this is PowerShell, not bash.
           * Please avoid commands that may produce a very large amount of output.
@@ -131,8 +131,11 @@
 
 # ── goals ───────────────────────────────────────────────────────────────────
 
-# Only the model-facing tool. The goal SERVICE, its session driver, and the
-# `/goal` command stay on the host plane.
+# Only the model-facing tool plus the human command. The goal SERVICE, its
+# session driver stay on the host plane.
+- id: command-goal
+  name: '@deepseek-ai/dsh-command-goal'
+
 - id: tool-goal
   name: '@deepseek-ai/dsh-tool-goal'
 
@@ -209,6 +212,7 @@
       config:
         provider: spawn
         toolName: subagent
+        modelSelectionSettings: true
         backgroundMode: continuable
 
     - id: tool-subagent-fork
@@ -282,3 +286,12 @@
   name: '@deepseek-ai/dsh-agent-tool-presentation'
   config:
     mode: ptc
+
+# Official `ptc` parity rows (0.1.6): the deliverables presenter and the
+# plugin-manager tools (off by default, mirroring the official preset).
+- id: present
+  name: '@deepseek-ai/dsh-tool-present'
+
+- id: tool-plugin-manager
+  name: '@deepseek-ai/dsh-plugin-manager/tools'
+  disabled: true

package/presets/ptc-minimal/preset.yml

@@ -1,2 +1,2 @@
 name: 极简 PTC 模式
-description: 提示词与极简模式一致（一句固定人格，无运行时上下文与附加指令），保留 PTC 模式的全部能力：PTC SDK 多步工具编排，以及文件、Shell、检索、Skills、计划、目标、子代理和工作流。Windows 上 Shell 为持久 PowerShell + Git Bash，并对齐 dsh-v0.1.2-alpha.2 子代理配置。
+description: 一句固定人格，无运行时上下文与附加指令，保留 PTC SDK 多步工具编排、文件、Shell、检索、Skills、计划、目标、子代理和工作流。Windows 上提供持久 PowerShell 与 Git Bash，自动适配 Harness 0.1.5 和 0.1.6 的工作流运行时。