dsh-deep-ptc-mode 1.6.1 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,49 +1,71 @@
1
- # Changelog
2
-
3
- ## 1.6.1 — 2026-11-04
4
-
5
- - Follow the official modules instead of naming them. The shell, job and question wrappers no longer import `@deepseek-ai/dsh-tool-bash`, `dsh-tool-pwsh`, `dsh-tool-jobs` or `dsh-tool-ask-user`: each derived row carries the module name and options of the official row it replaces (`upstream`, `options`), and the wrapper loads that module through the installed runtime's module graph with the official plugin's own `inject` and `Config`. A renamed or replaced official tool is followed rather than breaking the mount.
6
- - Read the shell executors from the base deployment declaration (`@deepseek-ai/dsh-base/cordis.patch.yml`, rows `bash-sandbox` and `pwsh-sandbox`), including their official options; only the foreground cap is added. The WSL/Zsh executor extends the official bash executor class named there instead of importing `dsh-bash-local`/`dsh-bash-sandbox`.
7
- - Fall back to the official shell rows when the chosen environment cannot be mapped: no official shell tool row, no declared executor, or an official bash executor whose API WSL/Zsh can no longer extend (probed before the preset is published). The reachability guard still applies; the preset never publishes rows that cannot mount.
8
- - Keep `lib/base-snapshot.json` as the executor fallback beside `lib/preset.json`; `npm run sync:snapshot` regenerates both. Drop the official tool and executor packages from `peerDependencies` and add `@deepseek-ai/dsh-base`.
9
- - `scripts/check-preset.cjs` also resolves the official modules the wrappers name. The runtime checks (`check-reachability.mjs`, `check-host.cjs`) now also run on `0.2.2-rc.1`, whose tool batches go through a selected executor and whose preset registry requires the agent registry.
10
-
11
- ## 1.6.0 — 2026-11-04
12
-
13
- - Derive the preset from the PTC preset the installed Harness declares (`@deepseek-ai/dsh-web-app/presets/ptc.patch.yml`) instead of freezing a copy. Official rows, settings and additions are inherited; Deep PTC still replaces only its persona, execution environment, reachability guard, and the official job/question wrappers.
14
- - Fix the failure after the DSH `0.2.2-rc.1` update: the frozen 1.5.0 snapshot still named the `@deepseek-ai/dsh-tool-subagent-control/list-agents` subpath, which `0.2.2-rc.1` removed, so the preset could not mount and existing Deep PTC sessions were reported as unusable. Sessions were never migrated or rewritten; they open again once the preset mounts.
15
- - Keep `lib/preset.json` only as a fallback snapshot and refresh it to `0.2.2-rc.1`; `npm run sync:snapshot` regenerates it from the installed declaration.
16
- - Declare every imported host package in `peerDependencies`, including `@deepseek-ai/dsh-web-app`: the host only routes a linked plugin's bare specifier to the installation when the name is peer-declared, so without it a `link:` install silently fell back to the snapshot. `npm run check` now fails if a peer is missing.
17
- - Match official rows recursively (persona, shell/executor rows, job and question rows may move into a group) and accept only a declaration whose id is `ptc`. Tests cover nested groups, a non-PTC declaration, and the peer-declaration guard.
18
- - `compatibility.json` now records the checked upstream release plus fixture hash; `scripts/check.mjs` verifies inheritance invariants and fallback/dedaration parity instead of exact-snapshot equality.
19
- - Add derivation tests for future compositions (unknown rows, reordering, missing shell or wrapped rows) and `scripts/check-preset.cjs`, a live-runtime check that every derived row resolves through the installed module graph.
20
-
21
- ## 1.5.0 — 2026-10-31
22
-
23
- - Enforce reachability in code. Foreground shell commands move to background jobs after `foregroundSeconds` (default 30, configurable 5–600); a larger requested timeout is capped. Commands still run; only the wait ends.
24
- - A user message steered into the turn ends the current foreground wait within about 2 s: shell commands move to the background, `job_output` returns, and a timed question becomes pending. Waiting again with job_output while the message is unread is refused.
25
- - Refuse foreground pauses over 5 s (`sleep`, `Start-Sleep`, `timeout /t`), `run_code` programs that wait on long or non-literal timers, `setInterval` and `Atomics.wait`, and more than 3 polls of one running job inside a program.
26
- - Run `ask_user_question` in timed mode (120 s default, 300 s cap, `-1` refused) and fix the persona, which named a non-existent `timeoutMs` parameter.
27
- - Wrap the official bash, pwsh, job and question tools instead of replacing them; the upstream check verifies exactly which rows are wrapped.
28
- - Add `scripts/check-reachability.mjs`, an integration check on a real DSH runtime, and extend the Windows host check to activate the guard.
29
-
30
- ## 1.4.0 — 2026-10-31
31
-
32
- - Restore the 1.2.0 intent in the persona while keeping 1.3.0's execution environments: the DeepSeek identity and unlimited-budget contract with anti-padding guardrails; size-based planning (internal up to five minutes, shown without approval up to twenty, approved beyond); asking about meaning instead of searching for it.
33
- - Make waiting reachable: background jobs, non-blocking progress checks, ending the turn when idle, and handling mid-task user messages first, based on the runtime's step-boundary steering and job wakeups.
34
- - Restore one-sentence progress before each run_code and a stated "not doing" list in plans.
35
-
36
- ## 1.3.0 — 2026-10-30
37
-
38
- - Add bilingual settings for Automatic, WSL Bash, Windows PowerShell, native Zsh and native Bash. WSL distribution is optional. Unsupported choices are disabled according to the host platform.
39
- - Isolate executors inside the preset. Settings apply to new sessions; existing sessions and jobs retain their revision. Global shell configuration stays independent.
40
- - Launch WSL explicitly with separate argv entries. Reuse official process, terminal and approval implementations. Refuse confined WSL execution before spawning.
41
- - Allow focused fact lookup before semantic questions, preserve authorization when work takes longer, and distinguish finite jobs from servers and unregistered external tasks.
42
- - Add verification stopping conditions and collect delegated results through the actual tool's channel.
43
- - Remove unsupported unlimited-budget and DeepSeek-employment claims. Reduce the persona from about 2,203 to 1,091 English words.
44
- - Add upstream composition checks, platform/argv tests, revision lifecycle tests and rendered settings-form tests.
45
- - Raise the minimum DSH version to `0.2.1-rc.5`, the runtime used for integration verification.
46
-
47
- ## 1.2.0
48
-
49
- Previous persona-only PTC preset with semantic questions, duration-based planning, progress updates and delegation instructions.
1
+ # Changelog
2
+
3
+ ## 1.7.2 — 2026-11-05
4
+
5
+ - Add local tool/skill discovery and complete-schema loading with bounded pages, byte budgets and recent selections. Reuse the installed official PTC SDK renderer, reducing only its untouched generated section. Skill discovery reads metadata and invocation controls; the official loader owns skill bodies.
6
+ - Quarantine failed external tools in durable conversation state. Block subsequent calls until the user resets; no automatic probing, retries or root-cause analysis. Capture provenance/reset generation before dispatch; keep cancellation, permission decisions and normal pagination intact.
7
+ - Add a bilingual Reload all tool states button below the composer and a user-only host command. Preserve running jobs. Project failed tool/provider lists at turn completion and request concise final-task reporting.
8
+ - Identify baseline registrations from the inherited composition rather than package naming patterns; support class-style official plugins while retaining their metadata.
9
+ - Preserve the original execution, reachability, question, planning and shell policies. Add regression coverage for quarantine persistence, reset races, SDK disclosure, skill metadata and UI actions.
10
+
11
+ ## 1.7.1 — 2026-11-05
12
+
13
+ - Publish the plugin-cooperation release with bilingual README introductions and package/repository descriptions: external capabilities first, multiple providers working together, and the current official PTC composition as fallback, following the “everything is a plugin” composition model. Preserve the original interruptible background-work behavior and document integration boundaries.
14
+ - Set the DSH engine and DSH peer-package minimum to `>=0.2.2-rc.1`, matching the currently installed runtime, with no upper bound. Synchronize the lockfile and install documentation.
15
+ - Clarify that official fallback capabilities still derive from the installed PTC declaration at load/rebuild time, following the 1.6.1 mechanism; snapshots remain a logged fallback. No tool-selection, reachability, execution or planning code changes.
16
+
17
+ ## 1.7.0 — 2026-11-05
18
+
19
+ - Add two-layer task-level tool cooperation: search and prefer an available extension capability for the function, then use an admitted inherited official PTC capability if no enhancement fits or a provider fails. No new capability, alias, argument translation, result conversion or silent replay is registered.
20
+ - Observe final host results and publish bounded, agent-local recovery context. Preserve denials, cancellation, code-less pre-dispatch guard failures, partial effects and active background jobs; retain original tool schemas, output contracts, conditions and execution ownership. Successful calls and provider replacement clear stale failure evidence.
21
+ - Tag official capability registrations by provenance while loading their actual upstream modules/config. Keep activation options (`when`) and exact registration disposers when adapting the tool registry. Official web search/fetch remain official and retain provider-readiness gating.
22
+ - Add optional `toolCompatibility` (default true) and `toolPreferences` settings. Explicit preferences describe choices between existing tools, not a dispatch mapping. Hidden/removed fallbacks and a replaced/unloaded whole executor are not bypassed.
23
+ - Keep persona, task planning, WSL/PowerShell/Zsh/Bash selection, foreground cap, steering, managed jobs, completion wakeups and timed questions unchanged. Add offline unit coverage and an actual-host compatibility harness; run the existing reachability integration with the compatibility observer enabled.
24
+
25
+ ## 1.6.1 — 2026-11-04
26
+
27
+ - Follow the official modules instead of naming them. The shell, job and question wrappers no longer import `@deepseek-ai/dsh-tool-bash`, `dsh-tool-pwsh`, `dsh-tool-jobs` or `dsh-tool-ask-user`: each derived row carries the module name and options of the official row it replaces (`upstream`, `options`), and the wrapper loads that module through the installed runtime's module graph with the official plugin's own `inject` and `Config`. A renamed or replaced official tool is followed rather than breaking the mount.
28
+ - Read the shell executors from the base deployment declaration (`@deepseek-ai/dsh-base/cordis.patch.yml`, rows `bash-sandbox` and `pwsh-sandbox`), including their official options; only the foreground cap is added. The WSL/Zsh executor extends the official bash executor class named there instead of importing `dsh-bash-local`/`dsh-bash-sandbox`.
29
+ - Fall back to the official shell rows when the chosen environment cannot be mapped: no official shell tool row, no declared executor, or an official bash executor whose API WSL/Zsh can no longer extend (probed before the preset is published). The reachability guard still applies; the preset never publishes rows that cannot mount.
30
+ - Keep `lib/base-snapshot.json` as the executor fallback beside `lib/preset.json`; `npm run sync:snapshot` regenerates both. Drop the official tool and executor packages from `peerDependencies` and add `@deepseek-ai/dsh-base`.
31
+ - `scripts/check-preset.cjs` also resolves the official modules the wrappers name. The runtime checks (`check-reachability.mjs`, `check-host.cjs`) now also run on `0.2.2-rc.1`, whose tool batches go through a selected executor and whose preset registry requires the agent registry.
32
+
33
+ ## 1.6.0 — 2026-11-04
34
+
35
+ - Derive the preset from the PTC preset the installed Harness declares (`@deepseek-ai/dsh-web-app/presets/ptc.patch.yml`) instead of freezing a copy. Official rows, settings and additions are inherited; Deep PTC still replaces only its persona, execution environment, reachability guard, and the official job/question wrappers.
36
+ - Fix the failure after the DSH `0.2.2-rc.1` update: the frozen 1.5.0 snapshot still named the `@deepseek-ai/dsh-tool-subagent-control/list-agents` subpath, which `0.2.2-rc.1` removed, so the preset could not mount and existing Deep PTC sessions were reported as unusable. Sessions were never migrated or rewritten; they open again once the preset mounts.
37
+ - Keep `lib/preset.json` only as a fallback snapshot and refresh it to `0.2.2-rc.1`; `npm run sync:snapshot` regenerates it from the installed declaration.
38
+ - Declare every imported host package in `peerDependencies`, including `@deepseek-ai/dsh-web-app`: the host only routes a linked plugin's bare specifier to the installation when the name is peer-declared, so without it a `link:` install silently fell back to the snapshot. `npm run check` now fails if a peer is missing.
39
+ - Match official rows recursively (persona, shell/executor rows, job and question rows may move into a group) and accept only a declaration whose id is `ptc`. Tests cover nested groups, a non-PTC declaration, and the peer-declaration guard.
40
+ - `compatibility.json` now records the checked upstream release plus fixture hash; `scripts/check.mjs` verifies inheritance invariants and fallback/dedaration parity instead of exact-snapshot equality.
41
+ - Add derivation tests for future compositions (unknown rows, reordering, missing shell or wrapped rows) and `scripts/check-preset.cjs`, a live-runtime check that every derived row resolves through the installed module graph.
42
+
43
+ ## 1.5.0 — 2026-10-31
44
+
45
+ - Enforce reachability in code. Foreground shell commands move to background jobs after `foregroundSeconds` (default 30, configurable 5–600); a larger requested timeout is capped. Commands still run; only the wait ends.
46
+ - A user message steered into the turn ends the current foreground wait within about 2 s: shell commands move to the background, `job_output` returns, and a timed question becomes pending. Waiting again with job_output while the message is unread is refused.
47
+ - Refuse foreground pauses over 5 s (`sleep`, `Start-Sleep`, `timeout /t`), `run_code` programs that wait on long or non-literal timers, `setInterval` and `Atomics.wait`, and more than 3 polls of one running job inside a program.
48
+ - Run `ask_user_question` in timed mode (120 s default, 300 s cap, `-1` refused) and fix the persona, which named a non-existent `timeoutMs` parameter.
49
+ - Wrap the official bash, pwsh, job and question tools instead of replacing them; the upstream check verifies exactly which rows are wrapped.
50
+ - Add `scripts/check-reachability.mjs`, an integration check on a real DSH runtime, and extend the Windows host check to activate the guard.
51
+
52
+ ## 1.4.0 — 2026-10-31
53
+
54
+ - Restore the 1.2.0 intent in the persona while keeping 1.3.0's execution environments: the DeepSeek identity and unlimited-budget contract with anti-padding guardrails; size-based planning (internal up to five minutes, shown without approval up to twenty, approved beyond); asking about meaning instead of searching for it.
55
+ - Make waiting reachable: background jobs, non-blocking progress checks, ending the turn when idle, and handling mid-task user messages first, based on the runtime's step-boundary steering and job wakeups.
56
+ - Restore one-sentence progress before each run_code and a stated "not doing" list in plans.
57
+
58
+ ## 1.3.0 — 2026-10-30
59
+
60
+ - Add bilingual settings for Automatic, WSL Bash, Windows PowerShell, native Zsh and native Bash. WSL distribution is optional. Unsupported choices are disabled according to the host platform.
61
+ - Isolate executors inside the preset. Settings apply to new sessions; existing sessions and jobs retain their revision. Global shell configuration stays independent.
62
+ - Launch WSL explicitly with separate argv entries. Reuse official process, terminal and approval implementations. Refuse confined WSL execution before spawning.
63
+ - Allow focused fact lookup before semantic questions, preserve authorization when work takes longer, and distinguish finite jobs from servers and unregistered external tasks.
64
+ - Add verification stopping conditions and collect delegated results through the actual tool's channel.
65
+ - Remove unsupported unlimited-budget and DeepSeek-employment claims. Reduce the persona from about 2,203 to 1,091 English words.
66
+ - Add upstream composition checks, platform/argv tests, revision lifecycle tests and rendered settings-form tests.
67
+ - Raise the minimum DSH version to `0.2.1-rc.5`, the runtime used for integration verification.
68
+
69
+ ## 1.2.0
70
+
71
+ Previous persona-only PTC preset with semantic questions, duration-based planning, progress updates and delegation instructions.
package/README.md CHANGED
@@ -1,131 +1,174 @@
1
- # Deep PTC mode
2
-
3
- [中文](README.zh.md) · MIT · **1.6.1**
4
-
5
- A DeepSeek Harness agent preset with exactly the built-in PTC tool surface and a different way of working: the model uses its full capability, stays interruptible while work runs, asks for approval only when a task is long, asks you instead of guessing, and runs commands in the environment you choose.
6
-
7
- ## Overview
8
-
9
- Deep PTC targets five common problems with the built-in PTC mode:
10
-
11
- | Problem | What Deep PTC does |
12
- | --- | --- |
13
- | The model rations tokens, skipping reads and tests, and quality suffers | The persona states that it works at DeepSeek with an unlimited token budget in this mode: never skip a read, search, command or check to save tokens. Guardrails forbid padding, verbosity and context blow-ups |
14
- | Once work starts, the model sleeps or waits and ignores your messages | Enforced in code: foreground commands move to the background after 30 s, a message from you moves the waiting command to the background at once so the model reads it, and long sleeps are refused; job completion wakes the model (see "Enforced reachability" below) |
15
- | Every task starts the same way regardless of size | Three bands by estimated time: up to 5 minutes, plan internally and act; 5–20 minutes, show the plan and start without approval; over 20 minutes, show the plan and wait for approval |
16
- | It starts before understanding what you meant, then redoes the work | Meaning belongs to you, facts to the tools: unfamiliar names, competing targets or routes, scope and acceptance criteria are asked about (one to three questions with options), never guessed by searching; file locations and current behavior are looked up |
17
- | The command environment is fixed | Choose WSL Bash, PowerShell, Zsh (macOS/Linux) or native Bash in settings; the choice applies to this preset only and leaves the global shell alone |
18
-
19
- Three steps: install the plugin → pick an environment under **Settings → Plugins → Deep PTC** → choose **深度PTC模式** in the mode picker for a new task.
20
-
21
- ## Enforced reachability: no sleeping, always interruptible
22
-
23
- From 1.5.0, "don't sleep or wait" is enforced by plugin code, not just requested in the prompt:
24
-
25
- | Situation | What the code does |
26
- | --- | --- |
27
- | A foreground command runs long | After **30 s** (configurable, 5–600) it moves to a background job and keeps running; a larger requested `timeoutMs` is capped |
28
- | You send a message while a command runs | The foreground wait ends within about 2 s, the command continues in the background, and the model reads your message; job completion still wakes it |
29
- | `job_output` waits on a job | Capped at 30 s, ends early when you send a message, and waiting again while your message is unread is refused |
30
- | The model writes `sleep 60`, `Start-Sleep 30` or `timeout /t 20` | Foreground pauses over 5 s are refused (`run_in_background` commands are exempt); short readiness loops such as `sleep 1` still work |
31
- | `setTimeout`, `setInterval` or `time.sleep` in a `run_code` program | Waits over 5 s, or with a non-literal duration, are refused; polling one running job more than 3 times in one program is refused |
32
- | `ask_user_question` | Runs in timed mode: 120 s by default, at most 300 s, `-1` refused. An unanswered question becomes pending and your later answer arrives as a message; typing a reply instead of using the card ends the wait at once |
33
-
34
- These rules apply only to Deep PTC sessions. They rely on the desktop "busy Enter" setting being **steer**; with **queue**, messages wait for the whole turn to end.
35
-
36
- ```yaml
37
- - id: deep-ptc-settings
38
- config:
39
- foregroundSeconds: 30 # foreground wait cap in seconds, 5-600
40
- ```
41
-
42
- ## Choose an execution environment
43
-
44
- Open **Settings → Plugins → Deep PTC**, choose an environment, save, and create a new **深度PTC模式** session.
45
-
46
- | Selection | Host | Executor / tool |
47
- | --- | --- | --- |
48
- | Automatic | Windows / macOS / Linux | PowerShell on Windows, Zsh on macOS, Bash on Linux |
49
- | WSL Bash | Windows | Explicit `wsl.exe ... --exec bash -lc`, tool `bash` |
50
- | PowerShell | Windows | Official native PowerShell executor, tool `pwsh` |
51
- | Zsh | macOS / Linux | `/bin/zsh -lc` on macOS; installed `zsh` on Linux; tool `zsh` |
52
- | Native Bash | macOS / Linux | Official Bash executor, tool `bash` |
53
-
54
- Unsupported choices are disabled according to the Host, not the browser OS, and rejected by the Host schema. Leave the WSL distribution blank for the Windows default or enter an installed name such as `Ubuntu`. Zsh must be installed when selected on Linux.
55
-
56
- The selection changes the real executor, tool contract and environment instructions. Executors live in a preset-local `shell` realm, independent of the global shell and other presets. Settings register a new preset revision for new sessions. Existing sessions and background jobs retain their revision: create a new session to change environment safely.
57
-
58
- WSL source uses Linux/POSIX syntax, while file tools and `workdir` use Windows host paths. Distribution, cwd and source are distinct argv entries passed through `wsl.exe --cd`; no surrounding shell string is assembled. Login-shell configuration in the selected distribution controls Linux PATH and proxy setup. Windows environment variables are not all automatically exported into Linux.
59
-
60
- ### Sandbox behavior
61
-
62
- Native PowerShell, Bash and Zsh use Harness sandbox, approval and process management. WSL currently supports only execution already authorized as `danger-full-access`. Confined Windows policies are refused before execution, without fallback or permission changes. The plugin does not authorize escalation.
63
-
64
- ## Working contract
65
-
66
- - Spend the budget on the work: the persona states that the model works at DeepSeek with an unlimited token budget in this mode, so it does not skip reads, searches, commands or checks to save tokens. Guardrails forbid padding, and compaction, pruning and subagents keep each request inside its finite context window.
67
- - Stay reachable while work runs: no sleeps, busy-polls or long foreground calls. Long commands run as background jobs while the model continues short steps and checks progress without blocking; with nothing left to do it states what is running and ends the turn. Job completion wakes it, and user messages are handled immediately.
68
- - Plan by expected size: five minutes or less, plan internally and act; five to twenty minutes, show the plan and start without approval; more than twenty minutes, show the plan and wait for approval. Re-plan when the estimate moves up a band. Explicit plan mode always wins.
69
- - Ask instead of guessing intent: meaning belongs to the user, facts to the tools. Unfamiliar names, competing targets or routes, authoritative sources, expected process, acceptance criteria and scope are asked about rather than guessed or searched for; inspectable facts are looked up. One to three questions with options, recommended first; the user's answer wins.
70
- - Work visibly: one sentence before each `run_code`, longer updates at milestones, never more than two or three silent tool calls.
71
- - Verify changed behavior and stop when criteria are met; delegate only genuinely independent work and collect results through the actual tool's channel.
72
-
73
- A prompt changes the model's working tendency, not the real token limit or billing, and compliance is not guaranteed. The setting that actually controls thinking depth is the model's `reasoningEffort`.
74
-
75
- ## Install or upgrade
76
-
77
- Requires Node `>=24` and DSH `>=0.2.1-rc.5`. Windows desktop rc.5 was used for real WSL/PowerShell command checks. macOS/Zsh configuration, argv and tool mounting were checked; native macOS execution has not been verified on this Windows host.
78
-
79
- ```js
80
- plugin_manager({ action: "install_bundle", target: "dsh-deep-ptc-mode@1.6.1" })
81
- // Or from a local checkout or archive:
82
- plugin_manager({ action: "install_bundle", target: "C:\\path\\to\\dsh-deep-ptc-mode" })
83
- // Or target: "C:\\path\\to\\dsh-deep-ptc-mode-1.6.1.tgz"
84
- ```
85
-
86
- Repository locator: `github:lishize20040802-rgb/dsh-deep-ptc-mode`. It installs content actually published there; a local upgrade does not publish to GitHub or npm.
87
-
88
- Installing the same bundle updates it. Upgrading from the persona-only release requires a Host plugin reload; reopen the app if the settings card has not appeared. Installation does not change the default mode for unrelated new sessions.
89
-
90
- Settings persist through the active profile's Cordis patch:
91
-
92
- ```yaml
93
- - id: deep-ptc-settings
94
- config:
95
- environment: auto # auto | wsl | powershell | zsh | bash
96
- wslDistribution: '' # blank uses the Windows default
97
- ```
98
-
99
- Prefer the UI, which uses revisioned, atomic Host form writes.
100
-
101
- ## Compatibility and development
102
-
103
- Deep PTC is composed at load time from the PTC preset the installed Harness declares (`@deepseek-ai/dsh-web-app/presets/ptc.patch.yml`). Every official row is inherited as-is; Deep PTC replaces only its persona text, swaps the two platform-switched shell tools for one isolated execution group, adds the reachability guard, and wraps the official job and question tools. The wrappers and the execution group never name an official module themselves: they load the module the official row names (and the shell executors the base deployment declares in `@deepseek-ai/dsh-base/cordis.patch.yml`), with the official options. An official PTC change therefore reaches this mode without a plugin release, and a removed or renamed upstream module cannot leave a stale row behind. When the chosen execution environment cannot be mapped onto the official rows, those rows are kept and the change is logged. If the declaration cannot be resolved, read or parsed, the bundled `lib/preset.json` snapshot is used as a fallback and the fallback is logged.
104
-
105
- Because the declarations are resolved through the host runtime, every host package the plugin imports statically is declared in `peerDependencies` — including `@deepseek-ai/dsh-web-app`. The host routes those names to the installation for a linked plugin; `npm run check` fails if one is missing, which is what keeps a `link:` installation on the live declaration instead of silently using the fallback snapshot. `compatibility.json` records the upstream release the checked fixture was taken from and its hash; `npm run check` verifies that the bundled fallback still derives the same preset as that fixture and that the inheritance invariants hold. The engines range is an installation floor, not proof that every future release was tested, so run `npm run check:upstream -- <path>` against a new release before trusting it.
106
-
107
- ```sh
108
- npm ci
109
- npm run check
110
- npm test
111
- npm run check:upstream -- /path/to/the/new/upstream/ptc.patch.yml
112
- npm run sync:snapshot # refresh lib/preset.json and lib/base-snapshot.json from the installed declarations
113
- PTC_RUNTIME_MODULES=/path/to/dsh/node_modules node scripts/check-preset.cjs # loader-level row resolution on a real runtime
114
- PTC_RUNTIME_MODULES=/path/to/dsh/node_modules node scripts/check-reachability.mjs # interruptible waits on a real runtime
115
- npm pack
116
- ```
117
-
118
- The checker parses `!!js` as data and asserts the derivation invariants: every official row survives unchanged except the persona, the shell rows and the two wrapped tools (including when the official preset nests them in a group); row ids stay unique; derivation is deterministic across nine platform/environment pairs. Tests cover future compositions as well (unknown rows, reordered rows, removed shell or wrapped rows), plus platforms, argv boundaries, confined WSL refusal, atomic settings writes and stale revisions. Real-task evaluations should measure successful completion, unnecessary questions, scope expansion, background-work collection and latency.
119
-
120
- Main files: `cordis.patch.yml` is the settings entry; `lib/index.mjs` manages revisions; `lib/model.mjs` builds isolated execution configurations; `lib/executor.mjs` extends the official bash executor for WSL/Zsh; `lib/terminal.mjs` runs the official shell tool the declaration names, with interruptible waits and the Zsh dialect; `lib/jobs-tool.mjs` and `lib/ask-user.mjs` run the official job and question tools the declaration names; `lib/host.mjs` resolves those official modules through the installed runtime; `lib/guard.mjs`, `lib/rules.mjs`, `lib/sleep-lint.mjs` and `lib/reachable.mjs` implement the pause/polling guard and interruptible waits; `lib/client.js` owns the bilingual settings card; `lib/upstream.mjs` locates and parses the installed PTC declaration; `lib/preset.json` holds the persona and the fallback snapshot used only when that declaration is unavailable.
121
-
122
- Uninstall with `plugin_manager` action `remove_bundle`, target `dsh-deep-ptc-mode`. Local link installations depend on their source directory: uninstall before deleting it.
123
-
124
- ## Author
125
-
126
- Deep PTC mode is written and maintained by [lishize20040802-rgb](https://github.com/lishize20040802-rgb).
127
-
128
- - Issues and feature requests: [GitHub issues](https://github.com/lishize20040802-rgb/dsh-deep-ptc-mode/issues)
129
- - Email: lishize20040802@gmail.com
130
-
131
- Bugs in DeepSeek Harness itself belong upstream, at [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness).
1
+ # Deep PTC mode
2
+
3
+ [中文](README.zh.md) · MIT · **1.7.2**
4
+
5
+ **Let plugins cooperate. Keep current official PTC tools as the fallback. Stay interruptible while work runs.**
6
+
7
+ Deep PTC is a DeepSeek Harness agent preset built for a plugin ecosystem. It first looks for a suitable tool among the available external plugins, then continues with the current official PTC capability when no enhancement fits or a provider fails. Multiple plugins can contribute different parts of a task, each using its own schemas, discovery and result contracts. Deep PTC adds no task tools of its own.
8
+
9
+ The same working rules remain: use the model's capability thoroughly, move long commands into managed background jobs, respond to your messages while work runs, plan by task size, clarify intent, and execute in your selected WSL / PowerShell / Zsh / Bash environment.
10
+
11
+ ## A mode for “everything is a plugin”
12
+
13
+ Compatibility has two directions: follow the installed official PTC composition as it evolves, and cooperate with external tool plugins instead of assuming a fixed tool inventory. This follows DSH's composable, “everything is a plugin” approach: the mode supplies working rules and recovery guidance, while tool providers retain ownership of their capabilities.
14
+
15
+ | Responsibility | How the plugins cooperate |
16
+ | --- | --- |
17
+ | External capabilities first | Search the available plugin capabilities for the needed function; use a provider's own discovery/SDK loader when appropriate |
18
+ | Multiple providers together | Use different plugins for different operations in the same task; no single enhancement plugin is required |
19
+ | Current official fallback | Continue through the installed Harness's official PTC tools if an enhancement is absent or fails |
20
+ | Shared task discipline | Preserve interruptible background work, clarification, planning and the selected execution environment |
21
+
22
+ An extension must publish into the `deep-ptc` scope and support the installed host. Keep official fallbacks visible in the provider's own configuration where supported. This is cooperative task-level selection, not a guarantee that every plugin or replacement executor is interchangeable. OPS is one possible provider, not a bundled dependency or a completed integration claim.
23
+
24
+ The official fallback retains the 1.6.1 derivation mechanism: each preset load or rebuild reads the PTC declaration from the currently installed Harness and follows its module names and configuration. The bundled snapshot is used only if loading, parsing or derivation fails, with a warning. Reload after an official upgrade and use a new preset revision; existing sessions are not forcibly switched. DSH support starts at `>=0.2.2-rc.1` with no upper bound; future host APIs still require verification.
25
+
26
+ ## 1.7.2: lightweight, on-demand tool orchestration
27
+
28
+ One tool/skill directory, `deep_ptc_tools`, coordinates discovery. Task operations still belong to external providers and the current official PTC tools.
29
+
30
+ - **Search summaries, then load definitions.** Local metadata search prefers external tools, then returns official candidates when no extension matches. Pages default to six entries (maximum eight); disclose up to six complete schemas within a 16 KB budget per load. Official tools stay available; up to twelve recent extension selections enter the host-generated PTC SDK on demand.
31
+ - **One actual failure quarantines the tool for this conversation.** Subsequent execution is blocked in code and state persists with the session. Agent recreation, conversation restore and provider reload do not lift quarantine. Capture provenance and reset generation before dispatch; late pre-reset results cannot contaminate the new state. Empty results, normal pagination, denial, cancellation, invalid arguments and ordinary nonzero command exits are not automatically treated as broken plugins.
32
+ - **Finish the task; do not diagnose failed providers.** Move promptly to a working equivalent or official fallback. No probing, retrying or root-cause investigation. Read back only the task state necessary to avoid duplicate effects after a potentially partial mutation.
33
+ - **Brief completion reporting.** The model lists failed tools and declared provider names at completion. The runtime also projects an expandable compatibility notice after a turn ends. Unknown ownership is reported as unknown, never inferred from a tool name.
34
+ - **Reload from below the composer.** “Reload all tool states” clears quarantine and on-demand selections for the current conversation without a model call or stopping running jobs. The user slash command `/deep-ptc-reset-tools` provides the same action.
35
+ - **Two-stage skill use.** Search the host's resolved, model-invocable skill metadata, then load the exact name with the official `skill` tool and follow its full instructions. Reuse instructions already in context. Discovery never reads skill bodies.
36
+
37
+ ```js
38
+ // Inside the official run_code tool; discovery itself never executes a found task tool.
39
+ const matches = await tools.deep_ptc_tools({ action: 'search', query: 'search files' });
40
+ const loaded = await tools.deep_ptc_tools({ action: 'load', names: ['actual_tool_name'] });
41
+ const skills = await tools.deep_ptc_tools({ action: 'skills', query: 'build test' });
42
+ // Next use each actual tool schema, or the official skill loader for a selected skill.
43
+ ```
44
+
45
+ Set `compactToolCatalog: false` under `deep-ptc-settings` to retain the full host SDK while keeping quarantine and reset. `toolCompatibility: false` disables the entire new layer. Optional `toolPreferences` still guide choices between existing tools.
46
+
47
+ Compaction only changes an untouched SDK section generated by the installed official renderer. Provider-owned/custom SDKs keep their own loaders. Extensions must support the host and publish into `deep-ptc`; this layer does not override hidden tools, authorization or an unloaded whole executor. Actual OPS/online-model end-to-end integration has not been performed.
48
+
49
+ ## Overview
50
+
51
+ Deep PTC targets six common problems in everyday agent work:
52
+
53
+ | Problem | What Deep PTC does |
54
+ | --- | --- |
55
+ | Enhanced tools and presets do not naturally cooperate | Search external plugin capabilities first, combine suitable providers, and recover through the dynamically inherited official PTC baseline |
56
+ | The model rations tokens, skipping reads and tests, and quality suffers | The persona states that it works at DeepSeek with an unlimited token budget in this mode: never skip a read, search, command or check to save tokens. Guardrails forbid padding, verbosity and context blow-ups |
57
+ | Once work starts, the model sleeps or waits and ignores your messages | Enforced in code: foreground commands move to the background after 30 s, a message from you moves the waiting command to the background at once so the model reads it, and long sleeps are refused; job completion wakes the model (see "Enforced reachability" below) |
58
+ | Every task starts the same way regardless of size | Three bands by estimated time: up to 5 minutes, plan internally and act; 5–20 minutes, show the plan and start without approval; over 20 minutes, show the plan and wait for approval |
59
+ | It starts before understanding what you meant, then redoes the work | Meaning belongs to you, facts to the tools: unfamiliar names, competing targets or routes, scope and acceptance criteria are asked about (one to three questions with options), never guessed by searching; file locations and current behavior are looked up |
60
+ | The command environment is fixed | Choose WSL Bash, PowerShell, Zsh (macOS/Linux) or native Bash in settings; the choice applies to this preset only and leaves the global shell alone |
61
+
62
+ Three steps: install the plugin → pick an environment under **Settings → Plugins → Deep PTC** → choose **深度PTC模式** in the mode picker for a new task.
63
+
64
+ ## Enforced reachability: no sleeping, always interruptible
65
+
66
+ From 1.5.0, "don't sleep or wait" is enforced by plugin code, not just requested in the prompt:
67
+
68
+ | Situation | What the code does |
69
+ | --- | --- |
70
+ | A foreground command runs long | After **30 s** (configurable, 5–600) it moves to a background job and keeps running; a larger requested `timeoutMs` is capped |
71
+ | You send a message while a command runs | The foreground wait ends within about 2 s, the command continues in the background, and the model reads your message; job completion still wakes it |
72
+ | `job_output` waits on a job | Capped at 30 s, ends early when you send a message, and waiting again while your message is unread is refused |
73
+ | The model writes `sleep 60`, `Start-Sleep 30` or `timeout /t 20` | Foreground pauses over 5 s are refused (`run_in_background` commands are exempt); short readiness loops such as `sleep 1` still work |
74
+ | `setTimeout`, `setInterval` or `time.sleep` in a `run_code` program | Waits over 5 s, or with a non-literal duration, are refused; polling one running job more than 3 times in one program is refused |
75
+ | `ask_user_question` | Runs in timed mode: 120 s by default, at most 300 s, `-1` refused. An unanswered question becomes pending and your later answer arrives as a message; typing a reply instead of using the card ends the wait at once |
76
+
77
+ These rules apply only to Deep PTC sessions. They rely on the desktop "busy Enter" setting being **steer**; with **queue**, messages wait for the whole turn to end.
78
+
79
+ ```yaml
80
+ - id: deep-ptc-settings
81
+ config:
82
+ foregroundSeconds: 30 # foreground wait cap in seconds, 5-600
83
+ ```
84
+
85
+ ## Choose an execution environment
86
+
87
+ Open **Settings → Plugins → Deep PTC**, choose an environment, save, and create a new **深度PTC模式** session.
88
+
89
+ | Selection | Host | Executor / tool |
90
+ | --- | --- | --- |
91
+ | Automatic | Windows / macOS / Linux | PowerShell on Windows, Zsh on macOS, Bash on Linux |
92
+ | WSL Bash | Windows | Explicit `wsl.exe ... --exec bash -lc`, tool `bash` |
93
+ | PowerShell | Windows | Official native PowerShell executor, tool `pwsh` |
94
+ | Zsh | macOS / Linux | `/bin/zsh -lc` on macOS; installed `zsh` on Linux; tool `zsh` |
95
+ | Native Bash | macOS / Linux | Official Bash executor, tool `bash` |
96
+
97
+ Unsupported choices are disabled according to the Host, not the browser OS, and rejected by the Host schema. Leave the WSL distribution blank for the Windows default or enter an installed name such as `Ubuntu`. Zsh must be installed when selected on Linux.
98
+
99
+ The selection changes the real executor, tool contract and environment instructions. Executors live in a preset-local `shell` realm, independent of the global shell and other presets. Settings register a new preset revision for new sessions. Existing sessions and background jobs retain their revision: create a new session to change environment safely.
100
+
101
+ WSL source uses Linux/POSIX syntax, while file tools and `workdir` use Windows host paths. Distribution, cwd and source are distinct argv entries passed through `wsl.exe --cd`; no surrounding shell string is assembled. Login-shell configuration in the selected distribution controls Linux PATH and proxy setup. Windows environment variables are not all automatically exported into Linux.
102
+
103
+ ### Sandbox behavior
104
+
105
+ Native PowerShell, Bash and Zsh use Harness sandbox, approval and process management. WSL currently supports only execution already authorized as `danger-full-access`. Confined Windows policies are refused before execution, without fallback or permission changes. The plugin does not authorize escalation.
106
+
107
+ ## Working contract
108
+
109
+ - Spend the budget on the work: the persona states that the model works at DeepSeek with an unlimited token budget in this mode, so it does not skip reads, searches, commands or checks to save tokens. Guardrails forbid padding, and compaction, pruning and subagents keep each request inside its finite context window.
110
+ - Stay reachable while work runs: no sleeps, busy-polls or long foreground calls. Long commands run as background jobs while the model continues short steps and checks progress without blocking; with nothing left to do it states what is running and ends the turn. Job completion wakes it, and user messages are handled immediately.
111
+ - Plan by expected size: five minutes or less, plan internally and act; five to twenty minutes, show the plan and start without approval; more than twenty minutes, show the plan and wait for approval. Re-plan when the estimate moves up a band. Explicit plan mode always wins.
112
+ - Ask instead of guessing intent: meaning belongs to the user, facts to the tools. Unfamiliar names, competing targets or routes, authoritative sources, expected process, acceptance criteria and scope are asked about rather than guessed or searched for; inspectable facts are looked up. One to three questions with options, recommended first; the user's answer wins.
113
+ - Work visibly: one sentence before each `run_code`, longer updates at milestones, never more than two or three silent tool calls.
114
+ - Verify changed behavior and stop when criteria are met; delegate only genuinely independent work and collect results through the actual tool's channel.
115
+
116
+ A prompt changes the model's working tendency, not the real token limit or billing, and compliance is not guaranteed. The setting that actually controls thinking depth is the model's `reasoningEffort`.
117
+
118
+ ## Install or upgrade
119
+
120
+ Requires Node `>=24` and DSH `>=0.2.2-rc.1`. Windows desktop rc.5 was used for real WSL/PowerShell command checks. macOS/Zsh configuration, argv and tool mounting were checked; native macOS execution has not been verified on this Windows host.
121
+
122
+ ```js
123
+ plugin_manager({ action: "install_bundle", target: "dsh-deep-ptc-mode@1.7.2" })
124
+ // Or from a local checkout or archive:
125
+ plugin_manager({ action: "install_bundle", target: "C:\\path\\to\\dsh-deep-ptc-mode" })
126
+ // Or target: "C:\\path\\to\\dsh-deep-ptc-mode-1.7.2.tgz"
127
+ ```
128
+
129
+ Repository locator: `github:lishize20040802-rgb/dsh-deep-ptc-mode`. It installs content actually published there; a local upgrade does not publish to GitHub or npm.
130
+
131
+ Installing the same bundle updates it. Upgrading from the persona-only release requires a Host plugin reload; reopen the app if the settings card has not appeared. Installation does not change the default mode for unrelated new sessions.
132
+
133
+ Settings persist through the active profile's Cordis patch:
134
+
135
+ ```yaml
136
+ - id: deep-ptc-settings
137
+ config:
138
+ environment: auto # auto | wsl | powershell | zsh | bash
139
+ wslDistribution: '' # blank uses the Windows default
140
+ ```
141
+
142
+ Prefer the UI, which uses revisioned, atomic Host form writes.
143
+
144
+ ## Compatibility and development
145
+
146
+ Deep PTC is composed at load time from the PTC preset the installed Harness declares (`@deepseek-ai/dsh-web-app/presets/ptc.patch.yml`). Every official row is inherited as-is; Deep PTC replaces only its persona text, swaps the two platform-switched shell tools for one isolated execution group, adds the reachability guard, and wraps the official job and question tools. The wrappers and the execution group never name an official module themselves: they load the module the official row names (and the shell executors the base deployment declares in `@deepseek-ai/dsh-base/cordis.patch.yml`), with the official options. An official PTC change therefore reaches this mode without a plugin release, and a removed or renamed upstream module cannot leave a stale row behind. When the chosen execution environment cannot be mapped onto the official rows, those rows are kept and the change is logged. If the declaration cannot be resolved, read or parsed, the bundled `lib/preset.json` snapshot is used as a fallback and the fallback is logged.
147
+
148
+ Because the declarations are resolved through the host runtime, every host package the plugin imports statically is declared in `peerDependencies` — including `@deepseek-ai/dsh-web-app`. The host routes those names to the installation for a linked plugin; `npm run check` fails if one is missing, which is what keeps a `link:` installation on the live declaration instead of silently using the fallback snapshot. `compatibility.json` records the upstream release the checked fixture was taken from and its hash; `npm run check` verifies that the bundled fallback still derives the same preset as that fixture and that the inheritance invariants hold. The engines range is an installation floor, not proof that every future release was tested, so run `npm run check:upstream -- <path>` against a new release before trusting it.
149
+
150
+ ```sh
151
+ npm ci
152
+ npm run check
153
+ npm test
154
+ npm run check:upstream -- /path/to/the/new/upstream/ptc.patch.yml
155
+ npm run sync:snapshot # refresh lib/preset.json and lib/base-snapshot.json from the installed declarations
156
+ PTC_RUNTIME_MODULES=/path/to/dsh/node_modules node scripts/check-preset.cjs # loader-level row resolution on a real runtime
157
+ PTC_RUNTIME_MODULES=/path/to/dsh/node_modules node scripts/check-reachability.mjs # interruptible waits on a real runtime
158
+ npm pack
159
+ ```
160
+
161
+ The checker parses `!!js` as data and asserts the derivation invariants: every official row survives unchanged except the persona, the shell rows and the two wrapped tools (including when the official preset nests them in a group); row ids stay unique; derivation is deterministic across nine platform/environment pairs. Tests cover future compositions as well (unknown rows, reordered rows, removed shell or wrapped rows), plus platforms, argv boundaries, confined WSL refusal, atomic settings writes and stale revisions. Real-task evaluations should measure successful completion, unnecessary questions, scope expansion, background-work collection and latency.
162
+
163
+ Main files: `cordis.patch.yml` is the settings entry; `lib/index.mjs` manages revisions; `lib/model.mjs` builds isolated execution configurations; `lib/executor.mjs` extends the official bash executor for WSL/Zsh; `lib/terminal.mjs` runs the official shell tool the declaration names, with interruptible waits and the Zsh dialect; `lib/jobs-tool.mjs` and `lib/ask-user.mjs` run the official job and question tools the declaration names; `lib/host.mjs` resolves those official modules through the installed runtime; `lib/guard.mjs`, `lib/rules.mjs`, `lib/sleep-lint.mjs` and `lib/reachable.mjs` implement the pause/polling guard and interruptible waits; `lib/client.js` owns the bilingual settings card; `lib/upstream.mjs` locates and parses the installed PTC declaration; `lib/preset.json` holds the persona and the fallback snapshot used only when that declaration is unavailable.
164
+
165
+ Uninstall with `plugin_manager` action `remove_bundle`, target `dsh-deep-ptc-mode`. Local link installations depend on their source directory: uninstall before deleting it.
166
+
167
+ ## Author
168
+
169
+ Deep PTC mode is written and maintained by [lishize20040802-rgb](https://github.com/lishize20040802-rgb).
170
+
171
+ - Issues and feature requests: [GitHub issues](https://github.com/lishize20040802-rgb/dsh-deep-ptc-mode/issues)
172
+ - Email: lishize20040802@gmail.com
173
+
174
+ Bugs in DeepSeek Harness itself belong upstream, at [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness).