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/README.zh.md CHANGED
@@ -1,146 +1,189 @@
1
- # 深度 PTC 模式
2
-
3
- [English](README.md) · MIT · 当前版本:**1.6.1**
4
-
5
- DeepSeek Harness 的 Agent 模式(preset),工具面与内置 PTC 完全一致,只换掉「工作方式」:让模型把能力用满、全程可被打断、按任务大小决定要不要你批准、拿不准就问你,并且自己选命令在哪个环境里跑。
6
-
7
- ## 简介
8
-
9
- 内置 PTC 用起来常见五个问题,深度PTC模式逐一针对:
10
-
11
- | 你遇到的问题 | 深度PTC模式的做法 |
12
- | --- | --- |
13
- | 模型总想帮你省 token,少查、少测,结果质量打折 | 人设写明「在深度求索工作,本模式 token 预算无限,把预算花在工作上」:不为省 token 跳过读取、搜索、命令或验证;同时禁止注水、啰嗦和撑爆上下文 |
14
- | 任务跑起来后模型在 sleep 或干等,你发消息它不理 | 由代码强制:前台命令超过 30 秒自动转后台,你一发消息正在等的命令立即转后台、模型马上看到消息,长 sleep 直接拒绝;job 完成会自动唤醒模型(详见下方「代码层强制」) |
15
- | 不管大小任务都同一种开工方式 | 按预计耗时分三档:5 分钟内自己计划直接做;5–20 分钟先告诉你计划、不等审批就执行;超过 20 分钟先给计划、等你批准 |
16
- | 意思没弄懂就开干,最后返工 | 意思归用户,事实归工具:不认识的名称、多个可能目标、技术路线、范围和验收标准不确定时先问你(1–3 个带选项的问题),不靠搜索去猜你的意图;文件位置、当前行为这类事实自己查 |
17
- | 命令环境固定,Windows 上想用 WSL、Mac 上想用 Zsh 都不方便 | 设置里可选 WSL Bash、PowerShell、Zsh(macOS/Linux)或原生 Bash,只对本模式生效,不改全局 shell |
18
-
19
- 使用三步:安装插件 → 在 **设置 → 插件 → 深度 PTC** 里选执行环境 → 新建任务时在模式选择器里选「深度PTC模式」。
20
-
21
- ## 代码层强制:不休眠、随时可插话
22
-
23
- 「不 sleep、不干等」不只写在提示词里,1.5.0 起由插件代码强制执行,模型不遵守也绕不过去:
24
-
25
- | 场景 | 代码行为 |
26
- | --- | --- |
27
- | 前台命令跑得久 | 超过 **30 秒**(可配置 5–600)自动转为后台 job,命令不会被杀掉;模型请求更长的 `timeoutMs` 也会被压到这个上限 |
28
- | 命令运行中你发了消息 | 约 2 秒内结束前台等待,命令转入后台继续跑,模型立刻看到你的消息;job 完成后仍会自动唤醒模型 |
29
- | `job_output` 等待 job | 等待上限同为 30 秒;你一发消息就提前返回;你的消息未读时再次等待会被拒绝 |
30
- | 模型写 `sleep 60`、`Start-Sleep 30`、`timeout /t 20` | 前台超过 5 秒的暂停直接拒绝(`run_in_background` 的命令不受限);`sleep 1` 这类就绪循环照常 |
31
- | `run_code` 程序里 `setTimeout`/`setInterval`/`time.sleep` | 超过 5 秒、或时长不是数字字面量的等待直接拒绝;同一程序里轮询同一个运行中 job 超过 3 次也会被拒绝 |
32
- | `ask_user_question` | 改为限时模式:默认等 120 秒,最多 300 秒,`-1`(无限等)被拒绝;超时后问题变为「待回答」,你之后的回答会作为消息送达;你不点卡片、直接打字回复,也会立刻结束等待 |
33
-
34
- 这些规则只作用于「深度PTC模式」会话,不影响其他模式。前提是桌面端设置里「忙碌时回车」为**插入当前任务(steer)**;若为排队(queue),消息会等整轮结束才送达。
35
-
36
- ```yaml
37
- - id: deep-ptc-settings
38
- config:
39
- foregroundSeconds: 30 # 前台等待上限(秒),5–600
40
- ```
41
-
42
- ## 选择 WSL、PowerShell 或 macOS 工具
43
-
44
- 安装并加载后,打开 **设置 → 插件 → 深度 PTC**,选择执行环境并保存,再新建一个「深度PTC模式」会话。
45
-
46
- | 选项 | 宿主 | 实际执行方式 / 模型工具 |
47
- | --- | --- | --- |
48
- | 自动 | Windows / macOS / Linux | Windows 选 PowerShell,macOS 选 Zsh,Linux 选 Bash |
49
- | WSL Bash | Windows | `wsl.exe ... --exec bash -lc`,工具名 `bash` |
50
- | PowerShell | Windows | Harness 官方原生 PowerShell 执行器,工具名 `pwsh` |
51
- | Zsh | macOS / Linux | macOS 用 `/bin/zsh -lc`;Linux 用已安装的 `zsh`;工具名 `zsh` |
52
- | 原生 Bash | macOS / Linux | Harness 官方 Bash 执行器,工具名 `bash` |
53
-
54
- 不适用于宿主的选项会禁用,运行时配置也会拒绝这些选择。WSL 发行版留空时使用 Windows 默认发行版,也可填写 `Ubuntu` 等已安装名称。Linux 上选择 Zsh 前需要安装 Zsh。
55
-
56
- **选择会改变实际执行器和模型看到的命令语法,不只改工具名称。** 执行器隔离在本 preset 中,不修改全局 shell,也不影响其他 preset。保存设置后,新会话使用新版本;已有会话和后台任务继续使用创建时的环境。切换环境时请新建会话,避免同一任务中途换方言。
57
-
58
- WSL 命令使用 Linux/POSIX 语法;文件工具和 `workdir` 仍用 Windows 宿主路径。执行器用 `--cd` 进入目录,发行版、目录和命令分别作为 argv 传递,不额外拼接 shell 字符串。WSL 内的 PATH、代理等由所选发行版的登录 shell 配置决定,Windows 环境变量不会全部自动变成 Linux 环境变量。
59
-
60
- ### 沙箱边界
61
-
62
- 原生 PowerShell、Bash 和 Zsh 继续使用 Harness 的沙箱、审批和进程管理。WSL 跨越 Windows/Linux 边界,目前仅支持宿主已经授权的 `danger-full-access` 执行;`read-only` 或 `workspace-write` 调用在启动命令前失败。插件不会自行升权、改变默认权限或悄悄换 shell。
63
-
64
- ## 工作规则
65
-
66
- - **不为 token 省力:** 人设写明在深度求索工作、本模式 token 预算无限,按问题需要而不是成本决定读取、搜索、命令和验证的深度;同时禁止注水和啰嗦,单次上下文仍有限,靠压缩、裁剪和子代理控制。
67
- - **任务运行中随时可插话:** 由代码强制(见上文),提示词同时要求:不 sleep、不轮询、不挂长时间前台调用。构建、测试、安装、服务器等耗时命令放后台 job,期间继续做短步骤,用不阻塞的方式查看进度;没事可做就一句话说明在跑什么并结束回合,job 完成会自动唤醒模型,你的消息会被立即处理。
68
- - **按任务长短计划:** ≤5 分钟内部计划直接做,不单独告知;5–20 分钟展示计划后立即执行,不等审批;>20 分钟展示计划并等你批准再改动。估计升档时重新说明计划;显式 plan mode 的规则优先。
69
- - **意图不清先问:** 意思归用户,事实归工具。不认识的名称、多个可能目标、技术路线、权威来源、做事方式、验收标准和范围不确定时先问,不用搜索去猜你的术语;文件位置、当前行为、版本等可检查的事实自己查。每次 1–3 个带选项的问题,推荐项在前;你的回答优先于模型推断。
70
- - **进度可见:** 每次 `run_code` 前一句话说明要做什么,里程碑稍长汇报,连续两三个工具调用必须出声。
71
- - **充分验证并停止,按需委派:** 验证改动触及的行为和边界,满足验收标准后交付;只在任务确实可拆分或需要独立复核时委派,按实际工具渠道收集结果。
72
-
73
- 提示词能改变模型的工作倾向,但不改变实际的 token 上限或计费,也不保证模型每次完全遵守。真正影响思考深度的设置是模型的 `reasoningEffort`。
74
-
75
- ## 安装和升级
76
-
77
- 要求 Node `>=24`、DSH `>=0.2.1-rc.5`。1.3.0 已用 Windows 桌面端 rc.5 做 WSL/PowerShell 命令验证。macOS/Zsh 分支做了配置、工具挂载与参数测试,尚未在 macOS 真机执行。
78
-
79
- 本地目录或构建产物可通过插件管理器安装:
80
-
81
- ```js
82
- plugin_manager({ action: "install_bundle", target: "dsh-deep-ptc-mode@1.6.1" })
83
- // 也可从本地目录或安装包安装:
84
- plugin_manager({ action: "install_bundle", target: "C:\\path\\to\\dsh-deep-ptc-mode" })
85
- // 或 target: "C:\\path\\to\\dsh-deep-ptc-mode-1.6.1.tgz"
86
- ```
87
-
88
- GitHub 地址:`github:lishize20040802-rgb/dsh-deep-ptc-mode`。该地址安装远端实际内容;本地升级不会自动发布到 GitHub/npm。
89
-
90
- 已有旧版时,安装同一个 bundle 即更新。从只有 persona 的旧版切到 1.3.0,需要宿主重新加载插件;桌面端若未出现设置卡片,可重新打开应用。安装不会将其他新任务的默认模式改为深度 PTC。
91
-
92
- 设置持久化到当前 profile 的 Cordis patch:
93
-
94
- ```yaml
95
- - id: deep-ptc-settings
96
- config:
97
- environment: wsl # auto | wsl | powershell | zsh | bash
98
- wslDistribution: Ubuntu # 留空为 Windows 默认发行版
99
- ```
100
-
101
- 优先使用界面保存,宿主会处理版本冲突和原子配置写入。
102
-
103
- ## 兼容性与维护
104
-
105
- Deep PTC 在加载时依据已安装 Harness 声明的 PTC 预设(`@deepseek-ai/dsh-web-app/presets/ptc.patch.yml`)现场组合:官方行原样继承,仅替换 persona 文本、把两个互斥 shell 工具换成一个带 `shell` 隔离的执行组、加入可达性守卫,并包装官方 job 与提问工具。包装层和执行组自身不写死任何官方模块名:加载的都是官方行里写的模块(shell 执行器取自基础部署声明 `@deepseek-ai/dsh-base/cordis.patch.yml`),并沿用官方配置。官方怎么改 PTC,本模式无需发版即可继承;官方改名或删除的模块也不会留下失效行。所选执行环境无法对应到官方行时,保留官方 shell 行并在日志中说明。只有在该声明无法解析、读取或解析失败时,才退回内置的 `lib/preset.json` 快照,并在日志中说明。
106
-
107
- 官方声明通过宿主运行时解析,因此插件静态引用的宿主包都必须声明在 `peerDependencies` 中(包括 `@deepseek-ai/dsh-web-app`):对 `link:` 本地安装,宿主只有看到 peer 声明才会把这些包名路由到已安装运行时。漏声明时 `npm run check` 会失败——这正是避免本地安装静默退回快照的关键。`compatibility.json` 记录 fixture 所取自的上游版本及其哈希;`npm run check` 会验证内置回退快照与 fixture 仍组合出同一预设,并检查继承不变量。`engines` 是安装下限,不能证明之后所有宿主都经过测试,遇到新版本先用 `npm run check:upstream -- <path>` 复核。
108
-
109
- ```sh
110
- npm ci
111
- npm run check
112
- npm test
113
- npm run check:upstream -- /path/to/ptc.patch.yml
114
- npm run sync:snapshot # 从已安装声明刷新 lib/preset.json 与 lib/base-snapshot.json 回退快照
115
- PTC_RUNTIME_MODULES=/path/to/dsh/node_modules node scripts/check-preset.cjs # 用真实运行时检查每行模块可解析
116
- PTC_RUNTIME_MODULES=/path/to/dsh/node_modules node scripts/check-reachability.mjs # 用真实运行时验证可打断等待
117
- npm pack
118
- ```
119
-
120
- 检查器把 `!!js` 当数据解析,并断言派生不变量:除 persona、shell 行与两个包装行外,官方行必须原样保留(官方把它们嵌进 group 时也同样处理);行 id 唯一;九种平台/环境组合下派生结果确定。测试同时覆盖未来可能出现的组合变化(新增未知行、调整行顺序、删除 shell 行或包装行),以及平台选择、命令边界、受限 WSL 拒绝、设置表单原子保存及并发版本约束。真实任务评测仍应记录成功率、无必要提问、范围控制、后台收尾和耗时。
121
-
122
- ## 文件和卸载
123
-
124
- - `cordis.patch.yml`:宿主设置入口。
125
- - `lib/index.mjs`:配置 schema、preset 注册和版本切换。
126
- - `lib/model.mjs`:平台选择、参数、隔离配置和环境说明,以及从官方声明派生 preset。
127
- - `lib/executor.mjs`:继承基础部署声明里的官方 bash 执行器,实现 WSL/Zsh。
128
- - `lib/terminal.mjs`:运行官方声明指定的 shell 工具,等待可被用户消息打断,并提供 Zsh 方言与工具名。
129
- - `lib/jobs-tool.mjs`、`lib/ask-user.mjs`:运行官方声明指定的 job 工具与提问工具,等待可被用户消息打断。
130
- - `lib/host.mjs`:通过已安装运行时解析这些官方模块。
131
- - `lib/guard.mjs`、`lib/rules.mjs`、`lib/sleep-lint.mjs`、`lib/reachable.mjs`:拒绝长暂停与轮询的工具守卫,以及可打断等待的实现。
132
- - `lib/client.js`:中英文设置卡片。
133
- - `lib/upstream.mjs`:定位并解析已安装的 PTC 声明。
134
- - `lib/preset.json`:persona,以及仅在声明不可用时的回退快照。
135
- - `test/`、`scripts/check.mjs`、`compatibility.json`:回归与上游差异检查。
136
-
137
- 卸载使用插件管理器的 `remove_bundle`,目标为 `dsh-deep-ptc-mode`。本地 link 安装直接依赖源目录,应先卸载再删除目录。
138
-
139
- ## 作者
140
-
141
- 深度PTC模式由 [lishize20040802-rgb](https://github.com/lishize20040802-rgb) 编写与维护。
142
-
143
- - 问题与需求:[GitHub Issues](https://github.com/lishize20040802-rgb/dsh-deep-ptc-mode/issues)
144
- - 邮箱:lishize20040802@gmail.com
145
-
146
- 上游 DeepSeek Harness 本身的问题请提到 [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)。
1
+ # 深度 PTC 模式
2
+
3
+ [English](README.md) · MIT · 当前版本:**1.7.2**
4
+
5
+ **让插件协作,让当前官方 PTC 工具兜底,让任务始终可沟通。**
6
+
7
+ 深度 PTC 是面向插件生态的 DeepSeek Harness Agent 模式(preset):优先在当前可用的外部插件中寻找同功能工具,没有合适能力或插件工具故障时,再用当前官方 PTC 的工具继续完成任务。多个插件可以分工完成同一个任务,各自保留原有参数、发现方式和结果契约;深度 PTC 本身不提供新的任务工具。
8
+
9
+ 原有的工作特点完整保留:把模型能力用满,长命令交给后台 job,运行中随时回应你的插话,按任务大小规划,意图不清先问,并在你选择的 WSL / PowerShell / Zsh / Bash 环境执行。
10
+
11
+ ## 为「一切皆插件」的协作方式而设计
12
+
13
+ 兼容性有两个方向:向官方,跟随当前安装版本的 PTC 组成演进;向外部,允许工具插件参与任务,不把工具清单固定下来。这更贴合 DSH「一切皆插件」的组合理念:模式负责工作规则和故障恢复指引,工具能力由各自的插件负责。
14
+
15
+ | 分工 | 如何协作 |
16
+ | --- | --- |
17
+ | 外部能力优先 | 先按功能寻找可用的插件工具,需要时使用该插件自己的发现/SDK 加载接口 |
18
+ | 多插件相互配合 | 同一任务的不同步骤可以交给不同插件,不要求只绑定某一个增强插件 |
19
+ | 当前官方工具兜底 | 增强能力缺失或故障时,回到当前安装 Harness 的官方 PTC 能力 |
20
+ | 工作方式保持一致 | 保留后台运行、随时插话、澄清、任务规划和所选执行环境 |
21
+
22
+ 外部插件需支持当前宿主,并在 `deep-ptc` 的作用域中发布工具;支持保留官方工具的插件,应在自身配置中保留兜底能力。这是任务级的合作选择机制,不代表所有插件或整个替换执行器都能直接互换。OPS 可以作为其中一个提供者,不是内置依赖,也不表示已经完成 OPS 的实际联调。
23
+
24
+ 官方兜底沿用 1.6.1 的动态派生机制:每次加载或重建预设时读取当前安装版本的官方 PTC 声明,工具模块和配置跟随该声明;仅在声明无法读取、解析或派生时使用随包快照并记录日志。官方升级后需重载并创建使用新版预设的会话,既有会话不被强制切换。最低支持 DSH `>=0.2.2-rc.1`,不设上限;更高版本仍需验证宿主接口。
25
+
26
+ ## 1.7.2:轻量、按需、可恢复的工具调用层
27
+
28
+ 本版增加一个工具与 Skill 的目录入口 `deep_ptc_tools`,具体任务继续交给外部插件和当前官方 PTC 工具完成。
29
+
30
+ - **先搜摘要,再加载定义。** 本地元数据检索优先返回外部工具,未找到匹配项时返回官方候选。默认每页 6 项,最多 8 项;完整 schema 每次最多加载 6 个、总预算 16 KB。普通官方工具继续可用,额外工具按需进入宿主生成的 PTC SDK,最多保留 12 个近期选择。
31
+ - **一次真实故障,本对话禁用。** 由程序拦截后续调用,故障记录随对话保存;切换 agent、恢复对话或重载插件不会自动解除。调用开始时捕获来源和状态代次,用户重载前的迟到结果不会污染新状态。普通空结果、分页续读、权限拒绝、取消、参数错误和命令非零退出不会被直接判为插件损坏。
32
+ - **任务优先,不查坏工具。** 确认工具故障后尽快改用其他可用同类工具或官方工具,不探测、不重试、不查根因。仅在写入或命令可能已部分完成时核查必要的任务状态,避免重复操作。
33
+ - **完成时简报。** 模型结束任务时简短列出失败工具与已声明的插件来源;程序同时在回合结束后生成可展开的“工具适配提醒”。来源不明就列工具名,不猜插件身份或故障原因。
34
+ - **输入框下方一键重载。** “重载所有工具状态”仅清除当前对话的故障标记与按需加载选择;不调用模型,也不停止正在运行的任务。另有用户命令 `/deep-ptc-reset-tools`。
35
+ - **Skill 两阶段调用。** 目录只查询宿主已解析的技能元数据和调用权限;选中后使用官方 `skill` 工具加载正文并遵守完整指令,复用上下文中已有指令。检索不读取 Skill 正文。
36
+
37
+ ```js
38
+ // 在官方 run_code 中使用;这些操作本身不会执行搜索到的任务工具。
39
+ const matches = await tools.deep_ptc_tools({ action: 'search', query: 'search files' });
40
+ const loaded = await tools.deep_ptc_tools({ action: 'load', names: ['实际工具名'] });
41
+ const skills = await tools.deep_ptc_tools({ action: 'skills', query: 'build test' });
42
+ // 之后按返回的真实 schema 调用工具,或通过官方 skill 加载选定技能。
43
+ ```
44
+
45
+ 可在 `deep-ptc-settings` 设置 `compactToolCatalog: false` 保留完整宿主 SDK,故障禁用与重载机制仍工作。`toolCompatibility: false` 则停用整套新增调用层。`toolPreferences` 继续支持对已有工具的可选优先关系。
46
+
47
+ 精简只作用于当前官方渲染器生成且未被其他插件改写的 SDK 段;插件自建 SDK 继续由其自身加载器管理。外部插件仍须支持当前宿主并在 `deep-ptc` 作用域发布工具;本层不会绕过工具隐藏、授权或接管被卸载的整个执行器。未进行实际 OPS/在线模型端到端评测。
48
+
49
+ ## 简介
50
+
51
+ 日常 Agent 工作中常见六个问题,深度 PTC 模式逐一针对:
52
+
53
+ | 你遇到的问题 | 深度PTC模式的做法 |
54
+ | --- | --- |
55
+ | 增强工具与自定义模式难以自然配合 | 外部插件能力优先,多提供者按功能协作,故障时使用动态继承的官方 PTC 基线恢复任务 |
56
+ | 模型总想帮你省 token,少查、少测,结果质量打折 | 人设写明「在深度求索工作,本模式 token 预算无限,把预算花在工作上」:不为省 token 跳过读取、搜索、命令或验证;同时禁止注水、啰嗦和撑爆上下文 |
57
+ | 任务跑起来后模型在 sleep 或干等,你发消息它不理 | 由代码强制:前台命令超过 30 秒自动转后台,你一发消息正在等的命令立即转后台、模型马上看到消息,长 sleep 直接拒绝;job 完成会自动唤醒模型(详见下方「代码层强制」) |
58
+ | 不管大小任务都同一种开工方式 | 按预计耗时分三档:5 分钟内自己计划直接做;5–20 分钟先告诉你计划、不等审批就执行;超过 20 分钟先给计划、等你批准 |
59
+ | 意思没弄懂就开干,最后返工 | 意思归用户,事实归工具:不认识的名称、多个可能目标、技术路线、范围和验收标准不确定时先问你(1–3 个带选项的问题),不靠搜索去猜你的意图;文件位置、当前行为这类事实自己查 |
60
+ | 命令环境固定,Windows 上想用 WSL、Mac 上想用 Zsh 都不方便 | 设置里可选 WSL Bash、PowerShell、Zsh(macOS/Linux)或原生 Bash,只对本模式生效,不改全局 shell |
61
+
62
+ 使用三步:安装插件 → 在 **设置 → 插件 → 深度 PTC** 里选执行环境 → 新建任务时在模式选择器里选「深度PTC模式」。
63
+
64
+ ## 代码层强制:不休眠、随时可插话
65
+
66
+ 「不 sleep、不干等」不只写在提示词里,1.5.0 起由插件代码强制执行,模型不遵守也绕不过去:
67
+
68
+ | 场景 | 代码行为 |
69
+ | --- | --- |
70
+ | 前台命令跑得久 | 超过 **30 秒**(可配置 5–600)自动转为后台 job,命令不会被杀掉;模型请求更长的 `timeoutMs` 也会被压到这个上限 |
71
+ | 命令运行中你发了消息 | 约 2 秒内结束前台等待,命令转入后台继续跑,模型立刻看到你的消息;job 完成后仍会自动唤醒模型 |
72
+ | `job_output` 等待 job | 等待上限同为 30 秒;你一发消息就提前返回;你的消息未读时再次等待会被拒绝 |
73
+ | 模型写 `sleep 60`、`Start-Sleep 30`、`timeout /t 20` | 前台超过 5 秒的暂停直接拒绝(`run_in_background` 的命令不受限);`sleep 1` 这类就绪循环照常 |
74
+ | `run_code` 程序里 `setTimeout`/`setInterval`/`time.sleep` | 超过 5 秒、或时长不是数字字面量的等待直接拒绝;同一程序里轮询同一个运行中 job 超过 3 次也会被拒绝 |
75
+ | `ask_user_question` | 改为限时模式:默认等 120 秒,最多 300 秒,`-1`(无限等)被拒绝;超时后问题变为「待回答」,你之后的回答会作为消息送达;你不点卡片、直接打字回复,也会立刻结束等待 |
76
+
77
+ 这些规则只作用于「深度PTC模式」会话,不影响其他模式。前提是桌面端设置里「忙碌时回车」为**插入当前任务(steer)**;若为排队(queue),消息会等整轮结束才送达。
78
+
79
+ ```yaml
80
+ - id: deep-ptc-settings
81
+ config:
82
+ foregroundSeconds: 30 # 前台等待上限(秒),5–600
83
+ ```
84
+
85
+ ## 选择 WSL、PowerShell 或 macOS 工具
86
+
87
+ 安装并加载后,打开 **设置 → 插件 → 深度 PTC**,选择执行环境并保存,再新建一个「深度PTC模式」会话。
88
+
89
+ | 选项 | 宿主 | 实际执行方式 / 模型工具 |
90
+ | --- | --- | --- |
91
+ | 自动 | Windows / macOS / Linux | Windows 选 PowerShell,macOS 选 Zsh,Linux 选 Bash |
92
+ | WSL Bash | Windows | `wsl.exe ... --exec bash -lc`,工具名 `bash` |
93
+ | PowerShell | Windows | Harness 官方原生 PowerShell 执行器,工具名 `pwsh` |
94
+ | Zsh | macOS / Linux | macOS 用 `/bin/zsh -lc`;Linux 用已安装的 `zsh`;工具名 `zsh` |
95
+ | 原生 Bash | macOS / Linux | Harness 官方 Bash 执行器,工具名 `bash` |
96
+
97
+ 不适用于宿主的选项会禁用,运行时配置也会拒绝这些选择。WSL 发行版留空时使用 Windows 默认发行版,也可填写 `Ubuntu` 等已安装名称。Linux 上选择 Zsh 前需要安装 Zsh。
98
+
99
+ **选择会改变实际执行器和模型看到的命令语法,不只改工具名称。** 执行器隔离在本 preset 中,不修改全局 shell,也不影响其他 preset。保存设置后,新会话使用新版本;已有会话和后台任务继续使用创建时的环境。切换环境时请新建会话,避免同一任务中途换方言。
100
+
101
+ WSL 命令使用 Linux/POSIX 语法;文件工具和 `workdir` 仍用 Windows 宿主路径。执行器用 `--cd` 进入目录,发行版、目录和命令分别作为 argv 传递,不额外拼接 shell 字符串。WSL 内的 PATH、代理等由所选发行版的登录 shell 配置决定,Windows 环境变量不会全部自动变成 Linux 环境变量。
102
+
103
+ ### 沙箱边界
104
+
105
+ 原生 PowerShell、Bash 和 Zsh 继续使用 Harness 的沙箱、审批和进程管理。WSL 跨越 Windows/Linux 边界,目前仅支持宿主已经授权的 `danger-full-access` 执行;`read-only` 或 `workspace-write` 调用在启动命令前失败。插件不会自行升权、改变默认权限或悄悄换 shell。
106
+
107
+ ## 工作规则
108
+
109
+ - **不为 token 省力:** 人设写明在深度求索工作、本模式 token 预算无限,按问题需要而不是成本决定读取、搜索、命令和验证的深度;同时禁止注水和啰嗦,单次上下文仍有限,靠压缩、裁剪和子代理控制。
110
+ - **任务运行中随时可插话:** 由代码强制(见上文),提示词同时要求:不 sleep、不轮询、不挂长时间前台调用。构建、测试、安装、服务器等耗时命令放后台 job,期间继续做短步骤,用不阻塞的方式查看进度;没事可做就一句话说明在跑什么并结束回合,job 完成会自动唤醒模型,你的消息会被立即处理。
111
+ - **按任务长短计划:** ≤5 分钟内部计划直接做,不单独告知;5–20 分钟展示计划后立即执行,不等审批;>20 分钟展示计划并等你批准再改动。估计升档时重新说明计划;显式 plan mode 的规则优先。
112
+ - **意图不清先问:** 意思归用户,事实归工具。不认识的名称、多个可能目标、技术路线、权威来源、做事方式、验收标准和范围不确定时先问,不用搜索去猜你的术语;文件位置、当前行为、版本等可检查的事实自己查。每次 1–3 个带选项的问题,推荐项在前;你的回答优先于模型推断。
113
+ - **进度可见:** 每次 `run_code` 前一句话说明要做什么,里程碑稍长汇报,连续两三个工具调用必须出声。
114
+ - **充分验证并停止,按需委派:** 验证改动触及的行为和边界,满足验收标准后交付;只在任务确实可拆分或需要独立复核时委派,按实际工具渠道收集结果。
115
+
116
+ 提示词能改变模型的工作倾向,但不改变实际的 token 上限或计费,也不保证模型每次完全遵守。真正影响思考深度的设置是模型的 `reasoningEffort`。
117
+
118
+ ## 安装和升级
119
+
120
+ 要求 Node `>=24`、DSH `>=0.2.2-rc.1`。1.3.0 已用 Windows 桌面端 rc.5 做 WSL/PowerShell 命令验证。macOS/Zsh 分支做了配置、工具挂载与参数测试,尚未在 macOS 真机执行。
121
+
122
+ 本地目录或构建产物可通过插件管理器安装:
123
+
124
+ ```js
125
+ plugin_manager({ action: "install_bundle", target: "dsh-deep-ptc-mode@1.7.2" })
126
+ // 也可从本地目录或安装包安装:
127
+ plugin_manager({ action: "install_bundle", target: "C:\\path\\to\\dsh-deep-ptc-mode" })
128
+ // 或 target: "C:\\path\\to\\dsh-deep-ptc-mode-1.7.2.tgz"
129
+ ```
130
+
131
+ GitHub 地址:`github:lishize20040802-rgb/dsh-deep-ptc-mode`。该地址安装远端实际内容;本地升级不会自动发布到 GitHub/npm。
132
+
133
+ 已有旧版时,安装同一个 bundle 即更新。从只有 persona 的旧版切到 1.3.0,需要宿主重新加载插件;桌面端若未出现设置卡片,可重新打开应用。安装不会将其他新任务的默认模式改为深度 PTC。
134
+
135
+ 设置持久化到当前 profile 的 Cordis patch:
136
+
137
+ ```yaml
138
+ - id: deep-ptc-settings
139
+ config:
140
+ environment: wsl # auto | wsl | powershell | zsh | bash
141
+ wslDistribution: Ubuntu # 留空为 Windows 默认发行版
142
+ ```
143
+
144
+ 优先使用界面保存,宿主会处理版本冲突和原子配置写入。
145
+
146
+ ## 兼容性与维护
147
+
148
+ Deep PTC 在加载时依据已安装 Harness 声明的 PTC 预设(`@deepseek-ai/dsh-web-app/presets/ptc.patch.yml`)现场组合:官方行原样继承,仅替换 persona 文本、把两个互斥 shell 工具换成一个带 `shell` 隔离的执行组、加入可达性守卫,并包装官方 job 与提问工具。包装层和执行组自身不写死任何官方模块名:加载的都是官方行里写的模块(shell 执行器取自基础部署声明 `@deepseek-ai/dsh-base/cordis.patch.yml`),并沿用官方配置。官方怎么改 PTC,本模式无需发版即可继承;官方改名或删除的模块也不会留下失效行。所选执行环境无法对应到官方行时,保留官方 shell 行并在日志中说明。只有在该声明无法解析、读取或解析失败时,才退回内置的 `lib/preset.json` 快照,并在日志中说明。
149
+
150
+ 官方声明通过宿主运行时解析,因此插件静态引用的宿主包都必须声明在 `peerDependencies` 中(包括 `@deepseek-ai/dsh-web-app`):对 `link:` 本地安装,宿主只有看到 peer 声明才会把这些包名路由到已安装运行时。漏声明时 `npm run check` 会失败——这正是避免本地安装静默退回快照的关键。`compatibility.json` 记录 fixture 所取自的上游版本及其哈希;`npm run check` 会验证内置回退快照与 fixture 仍组合出同一预设,并检查继承不变量。`engines` 是安装下限,不能证明之后所有宿主都经过测试,遇到新版本先用 `npm run check:upstream -- <path>` 复核。
151
+
152
+ ```sh
153
+ npm ci
154
+ npm run check
155
+ npm test
156
+ npm run check:upstream -- /path/to/ptc.patch.yml
157
+ npm run sync:snapshot # 从已安装声明刷新 lib/preset.json 与 lib/base-snapshot.json 回退快照
158
+ PTC_RUNTIME_MODULES=/path/to/dsh/node_modules node scripts/check-preset.cjs # 用真实运行时检查每行模块可解析
159
+ PTC_RUNTIME_MODULES=/path/to/dsh/node_modules node scripts/check-reachability.mjs # 用真实运行时验证可打断等待
160
+ npm pack
161
+ ```
162
+
163
+ 检查器把 `!!js` 当数据解析,并断言派生不变量:除 persona、shell 行与两个包装行外,官方行必须原样保留(官方把它们嵌进 group 时也同样处理);行 id 唯一;九种平台/环境组合下派生结果确定。测试同时覆盖未来可能出现的组合变化(新增未知行、调整行顺序、删除 shell 行或包装行),以及平台选择、命令边界、受限 WSL 拒绝、设置表单原子保存及并发版本约束。真实任务评测仍应记录成功率、无必要提问、范围控制、后台收尾和耗时。
164
+
165
+ ## 文件和卸载
166
+
167
+ - `cordis.patch.yml`:宿主设置入口。
168
+ - `lib/index.mjs`:配置 schema、preset 注册和版本切换。
169
+ - `lib/model.mjs`:平台选择、参数、隔离配置和环境说明,以及从官方声明派生 preset。
170
+ - `lib/executor.mjs`:继承基础部署声明里的官方 bash 执行器,实现 WSL/Zsh。
171
+ - `lib/terminal.mjs`:运行官方声明指定的 shell 工具,等待可被用户消息打断,并提供 Zsh 方言与工具名。
172
+ - `lib/jobs-tool.mjs`、`lib/ask-user.mjs`:运行官方声明指定的 job 工具与提问工具,等待可被用户消息打断。
173
+ - `lib/host.mjs`:通过已安装运行时解析这些官方模块。
174
+ - `lib/guard.mjs`、`lib/rules.mjs`、`lib/sleep-lint.mjs`、`lib/reachable.mjs`:拒绝长暂停与轮询的工具守卫,以及可打断等待的实现。
175
+ - `lib/client.js`:中英文设置卡片。
176
+ - `lib/upstream.mjs`:定位并解析已安装的 PTC 声明。
177
+ - `lib/preset.json`:persona,以及仅在声明不可用时的回退快照。
178
+ - `test/`、`scripts/check.mjs`、`compatibility.json`:回归与上游差异检查。
179
+
180
+ 卸载使用插件管理器的 `remove_bundle`,目标为 `dsh-deep-ptc-mode`。本地 link 安装直接依赖源目录,应先卸载再删除目录。
181
+
182
+ ## 作者
183
+
184
+ 深度PTC模式由 [lishize20040802-rgb](https://github.com/lishize20040802-rgb) 编写与维护。
185
+
186
+ - 问题与需求:[GitHub Issues](https://github.com/lishize20040802-rgb/dsh-deep-ptc-mode/issues)
187
+ - 邮箱:lishize20040802@gmail.com
188
+
189
+ 上游 DeepSeek Harness 本身的问题请提到 [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)。
package/lib/adapt.mjs CHANGED
@@ -19,7 +19,7 @@ export function adaptContext(ctx, faces) {
19
19
  export function registering(tools, wrap) {
20
20
  return new Proxy(tools, {
21
21
  get(target, key) {
22
- if (key === 'register') return definition => target.register(wrap(definition));
22
+ if (key === 'register') return (definition, ...options) => target.register(wrap(definition), ...options);
23
23
  const value = Reflect.get(target, key, target);
24
24
  return typeof value === 'function' ? value.bind(target) : value;
25
25
  },
package/lib/client.js CHANGED
@@ -97,6 +97,46 @@ window.__ModuleLoader__.load({ id: 'dsh-deep-ptc-mode', factory: require => {
97
97
  );
98
98
  }
99
99
 
100
+ function ToolStateControls({ useProjection, reset, t }) {
101
+ const preset = useProjection('agentPreset');
102
+ const state = useProjection('deepPtcTools');
103
+ const [busy, setBusy] = React.useState(false);
104
+ const [message, setMessage] = React.useState('');
105
+ const generation = React.useRef(0);
106
+ React.useEffect(() => { generation.current++; setBusy(false); setMessage(''); return () => { generation.current++; }; }, [reset]);
107
+ if (preset !== 'deep-ptc' || !state) return null;
108
+ const failed = state?.report?.tools ?? [];
109
+ async function reload() {
110
+ const current = generation.current;
111
+ setBusy(true); setMessage('');
112
+ try {
113
+ const outcome = await reset();
114
+ if (current !== generation.current) return;
115
+ const result = outcome?.result ?? outcome;
116
+ if (result?.kind !== 'success') throw new Error(result?.text || t('toolResetFailed'));
117
+ setMessage(t('toolResetDone'));
118
+ } catch (error) { if (current === generation.current) setMessage(t('toolResetFailed')); }
119
+ finally { if (current === generation.current) setBusy(false); }
120
+ }
121
+ return h('div', { style: { display: 'grid', gap: '4px', padding: '4px 0', fontSize: '12px' } },
122
+ failed.length ? h('details', { role: 'status' },
123
+ h('summary', null, `${t('toolFailures')} (${failed.length})`),
124
+ h('p', null, t('toolFailureHint')),
125
+ h('ul', null, ...failed.map(row => h('li', { key: row.name }, `${row.name} — ${row.provider}`)))) : null,
126
+ h('button', { type: 'button', onClick: reload, disabled: busy, title: t('toolResetHint'),
127
+ style: { justifySelf: 'start', font: 'inherit', color: 'inherit', cursor: busy ? 'wait' : 'pointer' } }, busy ? t('toolResetBusy') : t('toolReset')),
128
+ message ? h('span', { role: 'status' }, message) : null);
129
+ }
130
+ Object.assign(dictionaries.zh, {
131
+ toolReset: '重载所有工具状态', toolResetBusy: '正在重载…', toolResetDone: '本对话工具状态已重载。',
132
+ toolResetFailed: '重载失败,请确认当前连接及操作权限。', toolResetHint: '清除本对话的故障标记和按需加载选择;正在运行的任务继续执行。',
133
+ toolFailures: '工具适配提醒', toolFailureHint: '以下外部工具调用失败,可能存在适配问题,已在本对话中禁用。任务会优先使用其他可用工具;未进一步排查故障原因。',
134
+ });
135
+ Object.assign(dictionaries.en, {
136
+ toolReset: 'Reload all tool states', toolResetBusy: 'Reloading…', toolResetDone: 'Tool states reloaded for this conversation.',
137
+ toolResetFailed: 'Reload failed. Check the connection and access permissions.', toolResetHint: 'Clear quarantine and on-demand selections in this conversation. Running jobs continue.',
138
+ toolFailures: 'Tool compatibility notice', toolFailureHint: 'These external tools failed and may have compatibility issues. They are disabled in this conversation. Continue with working alternatives; no root-cause investigation was performed.',
139
+ });
100
140
  function apply(ctx) {
101
141
  const t = ctx.locale.bind('deep-ptc');
102
142
  ctx.effect(() => ctx.locale.register('deep-ptc', dictionaries));
@@ -106,6 +146,10 @@ window.__ModuleLoader__.load({ id: 'dsh-deep-ptc-mode', factory: require => {
106
146
  name: 'plugins.item', id: 'deep-ptc', order: 41,
107
147
  label: () => t('title'), locale: 'deep-ptc',
108
148
  }, props => h(Card, { ...props, form, t })))));
149
+ ctx.inject?.(['remote.commands'], child => child.slots.inject('conversation.composer.dock', () => child.slots.register({
150
+ name: 'conversation.composer.dock', id: 'deep-ptc-tool-states', order: 90,
151
+ inject: sessionId => ({ reset: () => child.remote.commands.execute(sessionId, '/deep-ptc-reset-tools', []) }),
152
+ }, props => h(ToolStateControls, { ...props, t }))));
109
153
  }
110
154
  return { apply, inject };
111
155
  } });
package/lib/host.mjs CHANGED
@@ -4,6 +4,8 @@
4
4
  import { createRequire } from 'node:module';
5
5
  import { pathToFileURL } from 'node:url';
6
6
  import { OFFICIAL_PACKAGE } from './upstream.mjs';
7
+ import { adaptContext, registering } from './adapt.mjs';
8
+ import { markOfficialTool } from './tool-policy.mjs';
7
9
 
8
10
  function anchor() {
9
11
  try {
@@ -52,14 +54,25 @@ export function pluginOf(namespace) {
52
54
  */
53
55
  export async function applyOfficial(ctx, upstream, options, adapt) {
54
56
  const plugin = pluginOf(await importHost(upstream));
57
+ const tagged = child => adapt(adaptContext(child, {
58
+ tools: tools => registering(tools, definition => markOfficialTool(definition, upstream)),
59
+ }));
60
+ if (typeof plugin === 'function') {
61
+ if (/^\s*class\b/u.test(Function.prototype.toString.call(plugin))) {
62
+ class TaggedOfficial extends plugin { constructor(child, ...args) { super(tagged(child), ...args); } }
63
+ return ctx.plugin(TaggedOfficial, options);
64
+ }
65
+ return ctx.plugin({ ...plugin, name: plugin.name || upstream, apply: (child, config) => plugin(tagged(child), config) }, options);
66
+ }
55
67
  if (typeof plugin?.apply !== 'function') {
56
68
  ctx.logger.warn('Deep PTC: %s is not an apply-style plugin; loading it without Deep PTC wait handling', upstream);
57
69
  return ctx.plugin(plugin, options);
58
70
  }
59
71
  return ctx.plugin({
72
+ ...plugin,
60
73
  name: plugin.name ?? upstream,
61
74
  ...plugin.inject === undefined ? {} : { inject: plugin.inject },
62
75
  ...plugin.Config === undefined ? {} : { Config: plugin.Config },
63
- apply: (child, config) => plugin.apply(adapt(child), config),
76
+ apply: (child, config) => plugin.apply(tagged(child), config),
64
77
  }, options);
65
78
  }
package/lib/index.mjs CHANGED
@@ -13,6 +13,9 @@ export const Config = z.object({
13
13
  environment: z.union(availableEnvironments(process.platform)).default('auto').volatile(),
14
14
  wslDistribution: z.string().pattern(/^(?!\s*-)[^\u0000-\u001f\u007f]*$/u).default('').volatile(),
15
15
  foregroundSeconds: z.number().step(1).min(5).max(600).default(DEFAULT_FOREGROUND_SECONDS).volatile(),
16
+ toolCompatibility: z.boolean().default(true).volatile(),
17
+ toolPreferences: z.any().default([]).volatile(),
18
+ compactToolCatalog: z.boolean().default(true).volatile(),
16
19
  hostPlatform: z.const(process.platform).default(process.platform).volatile(),
17
20
  });
18
21
 
@@ -21,6 +24,9 @@ function settingsOf(config) {
21
24
  environment: config.environment.get(),
22
25
  wslDistribution: normalizeDistribution(config.wslDistribution.get()),
23
26
  foregroundSeconds: config.foregroundSeconds.get(),
27
+ toolCompatibility: config.toolCompatibility.get(),
28
+ toolPreferences: config.toolPreferences.get(),
29
+ compactToolCatalog: config.compactToolCatalog.get(),
24
30
  };
25
31
  }
26
32
 
package/lib/model.mjs CHANGED
@@ -8,6 +8,7 @@
8
8
  // never leaves a stale module name behind.
9
9
  import snapshot from './preset.json' with { type: 'json' };
10
10
  import baseSnapshot from './base-snapshot.json' with { type: 'json' };
11
+ import { normalizePreferences } from './tool-policy.mjs';
11
12
 
12
13
  export const ENVIRONMENTS = ['auto', 'wsl', 'powershell', 'zsh', 'bash'];
13
14
 
@@ -147,6 +148,13 @@ export function isShellRow(row) {
147
148
  return row.group !== true && (SHELL_ROWS.names.includes(row.name) || SHELL_ROWS.ids.includes(row.id));
148
149
  }
149
150
 
151
+ export function isOfficialCapabilityRow(row) {
152
+ return row.group !== true && !isShellRow(row) && typeof row.name === 'string'
153
+ && !row.name.startsWith('dsh-deep-ptc-mode')
154
+ && row.id !== 'persona' && row.name !== '@deepseek-ai/dsh-persona'
155
+ && row.id !== 'tool-executor-ptc' && row.name !== '@deepseek-ai/dsh-tool-executor-ptc';
156
+ }
157
+
150
158
  function findRow(rows, { ids = [], names = [] }) {
151
159
  let found;
152
160
  walkRows(rows, row => {
@@ -193,6 +201,7 @@ export function deriveDeepPtc(upstream, options = {}, platform = process.platfor
193
201
  const distribution = normalizeDistribution(options.wslDistribution);
194
202
  const foregroundSeconds = normalizeForegroundSeconds(options.foregroundSeconds);
195
203
  const foregroundMs = foregroundSeconds * 1000;
204
+ const toolPreferences = normalizePreferences(options.toolPreferences);
196
205
  const plugins = structuredClone(upstream.plugins);
197
206
  const report = {
198
207
  upstreamId: typeof upstream.id === 'string' ? upstream.id : null,
@@ -293,6 +302,22 @@ export function deriveDeepPtc(upstream, options = {}, platform = process.platfor
293
302
  report.wrapped.push(`${target.key} (${upstreamName})`);
294
303
  }
295
304
 
305
+ // Capture provenance without replacing capabilities. New official tools are still loaded from
306
+ // the installed declaration; executor selection remains wholly owned by the official PTC row.
307
+ walkRows(plugins, row => {
308
+ if (!isOfficialCapabilityRow(row)) return;
309
+ const upstreamName = row.name;
310
+ row.name = 'dsh-deep-ptc-mode/official-tools';
311
+ row.config = { upstream: upstreamName, ...row.config === undefined ? {} : { options: row.config } };
312
+ });
313
+ plugins.push({
314
+ id: uniqueRowId(plugins, 'tool-compatibility'), name: 'dsh-deep-ptc-mode/tool-compatibility',
315
+ config: { enabled: options.toolCompatibility !== false, preferences: toolPreferences,
316
+ compact: options.compactToolCatalog !== false,
317
+ sdkProvider: findRow(upstream.plugins, {ids:['tool-executor-ptc'],names:['@deepseek-ai/dsh-tool-executor-ptc']})?.name ?? '@deepseek-ai/dsh-tool-executor-ptc',
318
+ skillProvider: findRow(upstream.plugins, {ids:['tool-skill'],names:['@deepseek-ai/dsh-tool-skill']})?.name ?? '@deepseek-ai/dsh-tool-skill' },
319
+ });
320
+
296
321
  const description = `${PRESET_META.description} 当前环境:${environment}${environment === 'wsl' && distribution ? ` (${distribution})` : ''}`;
297
322
  return {
298
323
  preset: {
@@ -0,0 +1,8 @@
1
+ import z from '@deepseek-ai/schemastery';
2
+ import { applyOfficial } from './host.mjs';
3
+
4
+ export const name = 'deep-ptc-official-tools';
5
+ export const inject = [];
6
+ export const Config = z.object({ upstream: z.string().required(), options: z.any() });
7
+ // Preserve official schemas, bodies, options and lifecycle; record their provenance for recovery.
8
+ export function apply(ctx, config) { return applyOfficial(ctx, config.upstream, config.options, child => child); }
@@ -0,0 +1,45 @@
1
+ // Local metadata search only: no model calls, filesystem probing or skill-body reads.
2
+ const indexed = new WeakMap();
3
+ export const DIRECTORY_TOOL = 'deep_ptc_tools';
4
+ export const RESET_COMMAND = 'deep-ptc-reset-tools';
5
+ export const STATE_EVENT = 'plugin:dsh-deep-ptc-mode/tool-state';
6
+ export const STATE_KEY = 'deepPtcTools';
7
+ export function summary(definition) {
8
+ let row = indexed.get(definition);
9
+ if (!row) {
10
+ const name = String(definition.name);
11
+ const description = String(definition.description ?? '').slice(0, 240);
12
+ row = { name, description, text: `${name} ${description}`.toLowerCase() };
13
+ indexed.set(definition, row);
14
+ }
15
+ return row;
16
+ }
17
+ export function searchCatalog(definitions, query = '', offset = 0, limit = 6) {
18
+ const terms = String(query).slice(0, 512).toLowerCase().trim().split(/[\s,,]+/u).filter(Boolean).slice(0, 12);
19
+ const ranked = definitions.map(def => {
20
+ const row = summary(def);
21
+ const score = terms.reduce((sum, word) => sum + (row.name.toLowerCase().includes(word) ? 8 : row.text.includes(word) ? 1 : 0), 0);
22
+ return { row, score };
23
+ }).filter(entry => terms.length === 0 || entry.score > 0)
24
+ .sort((a, b) => b.score - a.score || (a.row.name < b.row.name ? -1 : a.row.name > b.row.name ? 1 : 0));
25
+ const start = Number.isSafeInteger(offset) && offset >= 0 ? offset : 0;
26
+ const count = Math.max(1, Math.min(8, Number.isSafeInteger(limit) ? limit : 6));
27
+ return { total: ranked.length, results: ranked.slice(start, start + count).map(({ row }) => ({ name: row.name, description: row.description })),
28
+ nextOffset: start + count < ranked.length ? start + count : null };
29
+ }
30
+ export function toolSchema(def) {
31
+ return { name: def.name, description: def.description ?? '', parameters: def.parameters, output: def.output.schema };
32
+ }
33
+ export function blankState() { return { v: 1, epoch: 0, blocked: [], report: null }; }
34
+ export function parseState(value) {
35
+ if (!value || value.v !== 1 || !Number.isSafeInteger(value.epoch) || value.epoch < 0 || !Array.isArray(value.blocked)) throw new Error('Invalid Deep PTC tool state');
36
+ for (const row of value.blocked) if (!row || typeof row.name !== 'string' || row.name.length > 256 || typeof row.provider !== 'string' || typeof row.kind !== 'string') throw new Error('Invalid blocked tool');
37
+ return { v: 1, epoch: value.epoch, blocked: value.blocked.map(row => ({ name: row.name, provider: row.provider, kind: row.kind })), report: value.report ?? null };
38
+ }
39
+ export function foldToolState(state, event) {
40
+ if (event.type === STATE_EVENT && event.ignorable === true) {
41
+ try { return parseState(event.data); } catch { return state; }
42
+ }
43
+ if (event.type === 'turn/end' && state.blocked.length) return { ...state, report: { turn: event.data.turn, tools: state.blocked } };
44
+ return state;
45
+ }