dsh-plugin-prompt-tool 0.4.2 → 0.5.0

package/README.md

@@ -1,222 +1,125 @@
-# 提示词工具（dsh-plugin-prompt-tool）
-
-把「Anchored Standard + dsh-router-standard 最优组合」做成 DSH 全家桶里的一键安装插件：插件启动时生成并维护 `~/.dsh/.agent-presets/prompt-tool/` 预设，首轮模型请求只看到官方 Minimal 精确双工具——持久 `bash` 与 `str_replace_editor`——和正确的 persona，没有运行时上下文与指令注入；锚定建立后进入 resident 目录，恢复常规注入，并在确认轨迹后注入 `preset.md`。同时提供 Web 界面在线编辑 `preset.md` / `AGENTS.md`、切换全部开关，以及可开关的 skills 技能层（含一键打开技能目录、设置自定义技能目录）。全部通过官方插件接口实现，不修改 DSH 源码。
-
-## 原理
-
-DeepSeek V4 会强烈依赖 API 中可见的**首轮工具目录与 persona** 选择执行轨迹。完整 Standard 目录与自动注入在场会破坏 Minimal 轨迹，而全程 Minimal 又会失去重型工具。本项目把「首次轨迹选择」与「后续完整工具能力」拆开：
-
-1. **干净首轮**：`context-gate` 清空首轮 runtime-context 并剥离自动注入；`tool-bootstrap` 只暴露 Minimal 双工具；`router-first-turn` 按主会话模型替换 persona——Pro 使用训练原句，Flash 自动采用 dsh-router-standard 的 Flash 弱路由人设（build/fix 分类 + 回顾锚 + 反跑题锚 + 先深想再产出）。
-2. **晋升**：首次持久 `tool/call` 或 `assistant/message`（先到者为准）落地后，按 `usePtcMode` 开关选择 wire 形态——默认开启时切换为 Code Mode（PTC，单一 `run_code`），完整插件工具经生成 SDK 调用；关闭时恢复原生完整工具目录。
-3. **任务引导**：可选 `near-anchor` 在首条真实用户消息后追加一次近距离首句引导（we/let 按任务自动选择）；Flash 主会话晋升后 `router-guide` 按任务复杂度追加每轮深度引导。
-4. **提示词注入**：we 锚定确认后把 `preset.md` 作为用户消息注入一次；we 未确认最多等一轮兜底，绝不卡死。
-5. **子代理**：目录直接全量放行（仍受调用方工具白名单过滤）；可选 `subagentFlash` 固定 Flash 路由 + 任务分类人设 + 三锚。
-
-阶段全部从持久 session events 推导，resume / reload 不丢失状态。
-
-## 稳定化控制
-
-全部在生成 preset 的 `agent.cordis.yml` 行中配置：
-
-- `bootstrapMaxTokens`：首轮输出封顶。`0` = 本项目默认不设封顶（Web 界面显示 256000，即不设上限）；正整数 = 请求 #1 的 `maxTokens`，晋升后自动剥离，不会焊进后续请求。不锁定 1024，任意正整数均可。
-- `context-gate`：未晋升期间关闭两条统一注入路径，pre-step 只保留 claimed 批次 + `allowKinds`（放行用户技能手势与 `near-anchor` / `router-guide`）；晋升后差分恢复一条 runtime-context 消息。
-- `tool-bootstrap`：`promoteOn: either` 避免纯文字首答永久困在双工具；compaction 后回到 bootstrap + `compactionTools` 受控阶段。
-- `usePtcMode`（默认开启）：晋升后把 wire 切换为 Code Mode（PTC，单一 `run_code`），完整插件工具经生成 SDK 调用；关闭时恢复原生完整工具目录。两种模式都不再依赖 `dev_tool_search`，生成 preset 时直接移除该行且不复制 `dev-tool-search.mjs`。
-- `router-first-turn`：只替换 persona 段，保留 plan-mode 段与第三方 section；首轮隐藏 `mnemon:*` 自动注入段，晋升后恢复。
-- `near-anchor`：行为引导放在真实用户消息之后（近距离零衰减），只要求首句一次；复杂规划任务放行 Let 深度路径，日常任务锚 We。
-- `router-guide`：简单任务快速收敛，复杂任务深度引导；子代理不注入，首轮不注入。
-- `prompt-injector`：注入状态以持久事件为准，跨进程重启 / 插件热重载不重复注入。
-- `injectAgentsPrompt`：开启时用 `AGENTS.md` 内容替换本地 instruction-hint 的默认提示文本；关闭时使用本地默认 hint（列出参考文件、按需读取）。
-- `skillSwitches`：扫描 `skills/*/SKILL.md` 注册可开关技能，未列出的技能默认开启。
-- `subagentFlash`：检测不到 DeepSeek 模型路由时 Web/TUI 禁用并强制降级为关闭。
-
-## 安装
-
-依据官方[《打包与安装插件》](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish)准则：
-`dsh plugin add` 只把**声明了 `dsh.bundle` 的直接依赖**追加进
-`dsh.profile.bundles`；`@deepseek-ai/dsh-web-app` 是随 DSH 安装自带的 in-box
-bundle（从 dsh 安装目录解析，不需要也不应写进 `dependencies`）。
-
-### npm 安装与源码安装
-
-两种安装源等价，后续初始化流程相同：
-
-```sh
-# 方式 A：npm / registry 安装
-dsh plugin --profile prompt-tool add dsh-plugin-prompt-tool
-
-# 方式 B：本地源码安装（link 会覆盖 registry 依赖）
-dsh plugin --profile prompt-tool add link:<本仓库绝对路径>
-```
-
-### 初始化：启动一次即可
-
-```sh
-dsh --profile prompt-tool
-```
-
-第一次启动只负责完成初始化。首次进程尚未挂载 Web 表面，这是预期行为；
-自愈完成后**插件会自动退出（exit 0）**，无需手动停止：
-
-```text
-prompt-tool: auto-added @deepseek-ai/dsh-web-app to dsh.profile.bundles for profile "prompt-tool"; next launch will mount the Web surface ...
-prompt-tool: initialization complete — exiting so the repaired profile can be launched
-```
-
-这一次启动会自动完成：
-
-1. **prompt-tool profile**：把 `@deepseek-ai/dsh-web-app` 补进
-   `dsh.profile.bundles`，最终为
-   `base → web-app → dsh-plugin-prompt-tool`；
-2. **web profile**：若存在，把 `dsh-plugin-prompt-tool` 写进它的
-   `dependencies` + `bundles`（dependency 写法复用当前 profile 的安装
-   spec）。**只写 package.json，不手工创建 node_modules 链接**；
-3. **dsh-tui profile**：若存在且确实装有
-   `@deepseek-harness-tui/dsh-tui`，同样写进 `dsh-plugin-prompt-tool`；
-   **没有 dsh-tui 则整体跳过，不写入本插件**。dsh-tui 不需要
-   `@deepseek-ai/dsh-web-app`，因此不会给它补 web-app。
-
-所有写入幂等：文件已正确时不做任何改动。
-
-### 初始化之后直接使用
-
-```sh
-# Web：官方内置 profile，本插件已自动写入
-dsh web
-
-# TUI：dsh-tui 的安装流程已经物化过其 profile 依赖
-dsh-tui
-```
-
-`dsh web` 随 dsh 安装必然存在；`dsh-tui` 则在其自身安装说明中已经执行过
-profile 依赖物化。因此初始化只需写入 package.json，不需要额外 `install`。
-
-如果还想直接使用 `prompt-tool` 这个 profile 本身，再运行一次即可
-（第二次启动时 web-app 已由官方装配路径加载）：
-
-```sh
-dsh --profile prompt-tool
-```
-
-> TUI 前提：先安装/初始化过 `@deepseek-harness-tui/dsh-tui` 并已生成
-> `dsh-tui` profile，再执行上面的初始化启动；否则按设计会跳过 dsh-tui
-> profile。之后补装 dsh-tui 时，重新执行一次
-> `dsh --profile prompt-tool` 即可把本插件补进 dsh-tui profile。
-
-### 备选：直接把本插件装进官方 `web` 模板 profile
-
-`web` 是官方内置模板，初始 bundles 已含
-`@deepseek-ai/dsh-base` + `@deepseek-ai/dsh-web-app`：
-
-```sh
-# registry 安装
-dsh plugin --profile web add dsh-plugin-prompt-tool
-# 本地开发安装
-dsh plugin --profile web add link:<本仓库绝对路径>
-
-# 启动
-dsh --profile web
-```
-
-完成初始化后，用 `dsh web`、`dsh-tui` 或 `dsh --profile prompt-tool` 启动，
-新建空 session，预设选择 **prompt-tool**。插件会在启动时生成并刷新
-`~/.dsh/.agent-presets/prompt-tool/`（升级插件后重启即自动更新）。
-
-### 卸载
-
-```sh
-dsh plugin --profile prompt-tool remove dsh-plugin-prompt-tool
-```
-
-首次启动还会把包内 `skills/` 增量复制到**本插件自己的 profile** 目录下的
-`$DSH_HOME/profiles/prompt-tool/skills`，并优先使用这份副本（从 `dsh web`
-或 `dsh-tui` 启动也一样写这里，不会写到 web/dsh-tui profile）：已有同名文件不覆盖，
-用户对副本的编辑会保留；包内新增技能文件会在下次启动补齐。想改回包内原始
-skills，删除该 `skills` 目录后重启即可（或在配置里显式设置 `skillsDir`）。
-
-## 验证
-
-导出 session JSONL，检查 `request/header`：
-
-- 第一份 header 的 `tools` 应恰好是 `["bash", "str_replace_editor"]`；
-- 第一轮只包含用户消息与首句锚点：没有 workspace 指令 baseline、运行时快照、skill 目录消息；
-- 首次工具调用或首次助手回复后，下一份变更 header 应包含 resident 目录：bootstrap 双工具 + `dev_tool_search` / `skill_search` / `skill_load` + 已解锁工具；
-- 此后的请求保持 resident 集，只经 `dev_tool_search` 显式解锁增长；
-- `we` 锚定确认后，事件流出现一次 `source.plugin === 'prompt-injector'` 的消息；未确认时最多等一轮兜底。
-
-本项目测试：
-
-```sh
-pnpm test        # pnpm build + node --test
-pnpm typecheck   # Host 与 Client 两个 tsc program
-pnpm lint        # oxlint
-```
-
-## 行为与限制
-
-- Windows：DSH 的 PTY 后端仅支持 linux/darwin，持久 shell 组禁用；phase-1 的 `bash` 切换为 `custom-bash`——同名且 schema 与 Minimal 兼容，经普通跨平台子进程通道调起 Git Bash（运行时探测安装路径，不硬编码）。
-- Linux/macOS：持久 shell 的 `shellPath` 自适应——`/bin/bash` 存在时保持默认，不存在（如 NixOS）回退 PATH 里的 `bash`。
-- 首轮能力类提问可能基于被裁剪的双工具视图作答，晋升后由后续工具纠正；需要时可开启任务引导或直接首轮问任务类问题。
-- 工具目录只变化一次（晋升点），因此第一、二次请求之间发生一次前缀缓存变化；之后每次 `dev_tool_search` 解锁再变化。
-- preset 与 shell 访问具有相同信任等级，安装前可自行审阅 `upstream/` 与生成目录。
-- 插件只监听本机回环设置桥，不发起网络请求，也不增加遥测。
-- 不要在已经产生内容的会话中途切换 preset。
-- 需要 DSH 0.1.0-rc.7+（preset 机制、`system-prompt/assemble` 钩子与 keyed `settings.plugin.item` 插槽）。
-
-## 构建与上游管理
-
-```sh
-pnpm install
-pnpm build          # 生成 lib/
-pnpm prepare        # npm publish / git install 前自动触发
-pnpm sync:anchored  # 从上游 main 刷新内联快照（可加 ref 参数）
-```
-
-上游 `dsh-anchored-standard` 以内联快照形式固化在 `upstream/dsh-anchored-standard/`（含 `LICENSE`、`NOTICE`、`REVISION`），对应提交见 `REVISION`。本项目运行时不直读上游任何文件：`preset/` 已自有化全部 `agent.cordis.yml` 与预设 JS 脚本（shared / context-gate / compaction-epoch / custom-bash / instruction-hint / skill-search / tool-bootstrap），生成时只注入 `usePtcMode` / `bootstrapMaxTokens` / `subagentFlash` 动态项；`upstream/` 仅用于溯源与 sync 对照。上游已转入维护期（2026-08-17）；其 Project2 的 98/99/99 成绩来自当前实现之前的旧配置（issue #60），轨迹锚定有独立复现（#65），能力增益在小样本下未决（#51）。
-
-## 许可
-
-插件本体 MIT（Czerror）。首轮锚定机制源自 [xiaobright/dsh-anchored-standard](https://github.com/xiaobright/dsh-anchored-standard)（MIT），任务引导与 Flash 方案参考 [yjh051108/dsh-router-standard](https://github.com/yjh051108/dsh-router-standard)（MIT），缓存与工具面成本原则参考 [yjh051108/dsh-super-injector](https://github.com/yjh051108/dsh-super-injector)（MIT）。本地 `preset/` 下的 cordis 模板与 JS 脚本基于 DeepSeek Harness Standard 预设与上游 anchored-standard 修改，原始 DeepSeek 版权与 MIT 声明保留在 `upstream/dsh-anchored-standard/NOTICE` 与 `LICENSE`。
-
-## 配置参考
-
-挂载配置（cordis.patch.yml / profile patch）：
-
-```yaml
-- insert:
-    - id: prompt-tool
-      name: dsh-plugin-prompt-tool
-      config:
-        text: ''            # 覆盖 preset.md 文本；默认读项目文件
-        agentsText: ''      # 覆盖 AGENTS.md 文本；默认读项目文件
-        injectAgentsPrompt: false  # 用 AGENTS.md 替换 instruction-hint 提示文本
-        writeAgents: true   # 写 ~/.dsh/AGENTS.md 受管块
-        writePreset: true   # 启用锚定预设（总开关）
-        injectPrompt: true  # we 确认后注入 preset.md
-        skillSwitches: {}   # 按 skills/* 目录名开关，未列出默认开启
-        anchorFirstTurn: false  # 追加任务引导
-        anchorText: ''      # 自定义引导文本（首句）
-        anchorCustom: false # 使用自定义引导（首句）
-        guideText: ''       # 自定义引导文本（每轮）
-        guideCustom: false  # 使用自定义引导（每轮）
-        subagentFlash: false    # 子代理固定 Flash 模型
-        subagentFlashProvider: 'deepseek-official'
-        subagentFlashModel: 'deepseek-v4-flash'
-        bootstrapMaxTokens: 0   # 首轮输出封顶：0=关闭；正整数=请求 #1 maxTokens
-        usePtcMode: true  # 使用 PTC 模式：true=晋升后切换为 Code Mode（run_code）；false=恢复原生完整目录
-        skillsDir: ''       # 用户自定义技能目录；空 = 自动使用 prompt-tool profile 下 skills/ 副本
-        skillRankBase: 250  # 技能候选排序基数
-        residentAgentsPath: ''  # 默认 ~/.dsh/AGENTS.md
-        presetDir: ''       # 默认 ~/.dsh/.agent-presets/prompt-tool/
-        presetOrder: 5      # preset 显示顺序
-        fallbackText: ''    # preset.md 缺失或不可读时的回退文本
-```
-
-TUI 命令：
-
-```text
-/prompt-tool status
-/prompt-tool on|off|toggle <开关>
-/prompt-tool skill <技能目录名> on|off|toggle
-/prompt-tool bootstrapMaxTokens <正整数|0>
-```
+# dsh-plugin-prompt-tool — 层级提示词注入器
+
+> 一切皆可注入：把 DSH 官方开放的全部注入层级收敛为一个可配置提示词注入引擎——注入什么、注入到哪一层、何时注入，全由提示词配置决定。
+
+DSH 生态的提示词注入标准层：一个 `prompt-config-engine.mjs` 接线官方六个注入层级（`agent/pre-step`、`systemPrompt.section`、`systemPrompt.context`、`agent/request`、`llm/stream`、`tools/*`），内置 anchored 默认预设，开箱即用。
+
+> 策略来源：工具目录锚定 [dsh-anchored-standard](https://github.com/xiaobright/dsh-anchored-standard)、近距离引导 [dsh-router-standard](https://github.com/yjh051108/dsh-router-standard)、缓存铁律 [dsh-super-injector](https://github.com/yjh051108/dsh-super-injector)。
+
+## 安装
+
+```bash
+dsh plugin --profile prompt-tool add dsh-plugin-prompt-tool        # npm 安装
+dsh plugin --profile prompt-tool add link:<本仓库绝对路径>          # 本地源码（link 覆盖 registry）
+dsh --profile prompt-tool                                          # 首次启动自动补 dsh-web-app，二次启动生效
+```
+
+需要 DSH `0.1.1-rc.1+`。
+
+## 特性
+
+- 🔌 **六层一次接线**：一个引擎注册全部可注入层级，共享同一套过滤与降级语义
+- ✍️ **一切皆可配置**：`layer / strategy / position / promotion / subagents / modelScope / mergeMode / order / text / texts / fill / variables / params` 全开放
+- 🧑‍🤝‍🧑 **子代理三态**：`subagents: none / inherit / only`，身份类提示词可只注入子代理
+- 🗂️ **内容与执行分离**：每条提示词配置一个 yml/json 放 `prompt-configs/`，引擎按文件名数字前缀顺序扫描
+- 🧩 **三源合并**：默认提示词配置 < 目录文件 < settings 数组，同名 `id` 覆盖
+- 🖥️ **独立工作台**：侧边栏「提示词工具」入口（主会话/子代理/注入层/技能设置/预设配置五页）+ 设置面板提示词配置页（列表/表单/模板插入/保存前校验）
+- 🧪 **七种内容策略**：`static / first-turn-anchor / guide-auto / custom-fallback / instruction-hint / placeholder / world-book`
+- 🛡️ **失败不伤会话**：单条失败跳过 + `warnOnce`；配置错误挂载时 fail loud；`dedupe: session` 持久幂等
+- 🎭 **SillyTavern 导入**：JSON 预设卡片一键转换为本地预设——`prompts[]` 映射提示词配置、采样参数进 `params.model*`、`enable_web_search` 按开关装配工具
+- 🎴 **角色卡库**：SillyTavern 角色卡（PNG tEXt chunk `ccv3`/`chara`，或 chara_card JSON）导入独立库（`.characters/<id>/`，含原图/转换参数/角色记忆），按需「导入到当前预设」（`chara-<卡>-` 前缀合并、幂等可移除），多文件自动合并
+- 📚 **世界书**：`character_book` 转 world-book 策略配置（`keys` 命中触发 / `constant` 常驻 / `useRegex` 正则），与模块卡片同一存储与编辑（模块列表「世界书」过滤 + 批量启用/禁用）；ST 变量规则（`setvar`/`getvar` 含默认值）由 params fallback 插值承载
+
+## 预设参数体系
+
+预设行为由一份 `preset.yml` 单一配置源下发，共四层默认值，各层职责不重叠：
+
+| 层 | 职责 |
+|---|---|
+| `hostDefaults` | settings 层默认值（开关/路径），被用户 settings 覆盖 |
+| `params` | 引擎行为默认（锚定/引导/PTC/门控/模型/工具），被运行时 settings 覆盖 |
+| `moduleConfigs` | 引擎组合行级 config（persona 文本/超时/白名单） |
+| `promptConfigs` | 注入提示词配置（策略/层/位置/时机），与目录、settings 三源合并 |
+
+### params 一览（全部可选，缺省 = 官方默认）
+
+| 分类 | 键 |
+|---|---|
+| 锚定 | `firstTurnAnchor` `firstTurnCustom` `firstTurnText` `firstTurnWord` `firstTurnBuild` `firstTurnInspect` `firstTurnDeep` |
+| 引导 | `guideCustom` `guideText` `guideComplexPattern` `guideWeak` `guideDeep` `buildPattern` `complexPattern` |
+| PTC/门控 | `usePtcMode` `bootstrapMaxTokens` `injectPrompt` `allowKinds` |
+| 主对话模型 | `modelProvider` `modelName` `modelReasoningEffort` `modelTemperature` `modelMaxTokens` |
+| 子代理模型 | `subagentModelProvider` `subagentModelName` `subagentReasoningEffort` `subagentTemperature` `subagentMaxTokens` |
+| 人设 | `mainPersona`（主对话 Flash 档）`subagentPersona`（子代理，回退 `mainPersona` → 继承主会话） |
+| 工具集 | `toolFilterAllow` `toolFilterDeny`（子代理 toolFilter；主对话 tool-filter 模块共用） |
+| 深度 | `maxDepth`（0 禁止委派 / `provider-managed` / 正整数） |
+
+> 根目录 **`preset.yml`** 是配置参数齐全、逐项注释的完整模板，复制即得自定义预设起点。
+
+## 提示词配置（六层全家桶）
+
+| `layer` | 官方通道 | 关键参数 |
+|---|---|---|
+| `pre-step` | `agent/pre-step` 消息批（默认层） | `position / dedupe / promotion / subagents / modelScope / strategy` |
+| `system-section` | `ctx.systemPrompt.section` 静态段 | `order / text / templateFile / variables / params.complete / params.sectionName` |
+| `runtime-context` | `ctx.systemPrompt.context` 动态快照 | `order / text / variables / params.contextName` |
+| `agent-request` | `agent/request`（LlmCallConfig） | `params.patch`（浅合并）/ `params.replace`（整体替换） |
+| `llm-stream` | `llm/stream`（流包装） | `params.mode=pass\|replace` |
+| `tool-pipeline` | `tools/*`（pre/execute/post） | `params.toolNames`、`preDecision=allow\|deny\|ask`、`postAction=accept\|replace\|block` |
+
+默认四条：`00-near-anchor`（首句锚点）、`10-router-guide`（每轮引导）、`20-prompt-injector`（we 确认后注入 preset.md 一次）、`30-instruction-hint`（指令文件提示）。
+
+- `mergeMode`：`separate`（默认）同位置多条为独立消息；`merged` 同位置拼接为一条
+- `order`：数值小者更靠近插入锚点，同时决定 `merged` 组内拼接顺序
+- 文本插值：仅 `pre-step` 支持内置环境变量与 filler 变量；`system-section` 额外走官方 `{{variable}}` 渲染
+
+
+## SillyTavern 导入
+
+工作台「预设配置」页导入 SillyTavern JSON 预设卡片（导入包无定义文件、仅含单个 `.json` 时自动识别转换），按注入层级映射为本地预设：
+
+- `prompts[]` → `promptConfigs`：`system_prompt + role=system` → `system-section`（多条可 `mergeMode: merged` 拼接）；其余 → `pre-step`（`injection_position=0` → `before-all`，否则 `after-user`）；OFF 状态与 `injection_order` 原样保留
+- 采样参数 → 顶层 `params.model*`：`temperature` / `openai_max_tokens` / `reasoning_effort`
+- `enable_web_search`：`true` → 组装 `tool-web`（fetch 启用）；`false` → 不组装，改加 `tool-filter` 黑名单 `web_search / web_fetch`
+- `modules` 按需装配：`prompt-config-engine` 始终；含 system-section 时补 `persona`（`complete: false` 允许 system 段生效）
+
+转换结果是一个普通预设（id 由文件名生成），可在工作台预设切换器中直接使用。字段级参数对照与完整示例见 [SillyTavern.md](SillyTavern.md)。
+
+### 角色卡（PNG / JSON）与角色卡库
+
+工作台「角色管理」页导入角色卡到**角色卡库**（`~/.dsh/.agent-presets/.characters/<id>/`）：
+
+- **PNG**：tEXt chunk（`ccv3` 优先 / `chara` 兜底）base64 解析，原图存 `avatar.png`（字节无损）
+- **JSON**：chara_card_v2/v3 直接转换；多文件（角色卡 × 响应预设）自动合并
+- 正文映射：`first_mes` → 开场白（`dedupe: session`）、`alternate_greetings` → 备用开场白、
+  `description/personality/scenario` → 角色设定、采样参数 → `params.model*`
+- **导入到当前预设**：参数合并进当前预设 promptConfigs（`chara-<卡>-` 前缀、幂等）；可一键移除
+- **角色记忆**：`memory.md` 跟随角色卡跨预设，应用时合并为 world-book constant 配置注入
+
+### 世界书（world-book 策略）
+
+`character_book` 条目转 world-book 策略配置（与普通模块同一存储/编辑）：
+
+- **注入语义**：`constant` 常驻注入；有 `keys` 命中聊天内容才注入；无 keys 全局每次注入
+- **匹配选项**：`caseSensitive` / `wholeWords` / `useRegex`（keys 按正则）
+- **管理**：模块列表顶部下拉选「世界书」过滤（完整模块卡片编辑 + 批量启用/禁用）；
+  模型工具 `world_book_list/upsert/delete`（`note` 写入角色卡记忆）
+- **ST 变量**：`setvar` 收集进 params、`getvar`（含默认值）改写为 `{{key}}` 由引擎插值兜底；
+  `trim`/注释/ERA 剥离，`{{user}}`/`{{char}}` 替换；TavernHelper 扩展注入物自动剥离
+
+详细转换规则见 [SillyTavern.md](SillyTavern.md)。
+
+## 开发与验证
+
+```sh
+pnpm install && pnpm build
+pnpm test          # 235 单测：渲染/合并/六层接线/preset 生成
+pnpm typecheck && pnpm lint
+pnpm sync:anchored       # 刷新 upstream/dsh-anchored-standard 内联快照
+pnpm sync:yaml           # 刷新 engine/vendor/yaml（生成目录运行时 YAML 解析器）
+pnpm rebuild:composition # 从官方内置预设源码重建组合模块
+```
+
+## 许可
+
+插件本体 MIT（Czerror）。默认预设策略来源见顶部引用；`preset/` 下 cordis 模板与脚本基于 DeepSeek Harness 官方 Standard 预设修改，版权声明见 `upstream/dsh-anchored-standard/`。

package/engine/compaction-epoch.mjs

@@ -0,0 +1,139 @@
+/**
+ * Epoch-aware promotion tracker shared by the bootstrap and baseline-gate
+ * plugins of the anchored presets.
+ *
+ * A compaction rewrites the model-visible surface: the pre-compaction
+ * conversation collapses into one synthetic summary message, and the
+ * workspace-instruction baseline is re-injected from scratch. The first
+ * post-compaction request is therefore a "second first request" — the same
+ * first-token conditions the anchored presets exist to control. Promotion is
+ * epoch-aware: only a durable promotion signal (`tool/call` and/or
+ * `assistant/message`, per the caller's `promoteEvents`) recorded AFTER the
+ * last `compaction/end` boundary counts as promoted. Before any compaction
+ * the boundary is -1, which preserves the original one-shot semantics.
+ *
+ * State is memoized per session id and maintained incrementally through
+ * `observe()`; a cold session scans its durable log once (so resume and
+ * reload reconstruct the same phase), then O(1).
+ *
+ * By default subagents (`delegationDepth > 0`) are treated as already
+ * promoted so their first request can use tools. Set `includeSubagents: true`
+ * to make subagents follow the same bootstrap/anchor phase as top-level
+ * sessions.
+ *
+ * GATE MODE (liangshen 稳定化扩展, source: xiaobright/dsh-anchored-standard
+ * MIT + phase-1 quarantine): `promoteGate: true` gates the promotion on the
+ * first reasoning block classifying minimal-like (`we` present, no `let me`),
+ * with a `maxPromoteSteps` (default 4) fallback; `promoteAfterFirstResponse:
+ * true` promotes a tool-less first response once it has responded, and also
+ * releases an anchor-gated session when its first turn ends. Gate mode uses
+ * the durable-event state machine below and ignores `promoteEvents` (fixed
+ * either semantics: `tool/call` and `assistant/message` are both tracked).
+ * Non-gate mode keeps the original event-set semantics byte-for-byte.
+ */
+
+/** 首段 reasoning 块分类（liangshen 移植）：we 且无 let me = minimal-like。 */
+export function classifyReasoning(text) {
+  const trimmed = String(text ?? '').trim()
+  const we = [...trimmed.matchAll(/\bwe\b/gi)].length
+  const letMe = [...trimmed.matchAll(/\blet me\b/gi)].length
+  const metrics = { we, letMe }
+  if (we > 0 && letMe === 0) return { label: 'minimal-like', score: 4, metrics }
+  if (letMe > 0) return { label: 'standard-like', score: -4, metrics }
+  return { label: 'ambiguous', score: 0, metrics }
+}
+
+/** 首段 reasoning 块是否为 minimal-like（后续块不覆盖首个标准样块）。 */
+export function hasAnchoredReasoning(content) {
+  if (!Array.isArray(content)) return false
+  const first = content.find((block) => block?.type === 'reasoning')
+  return first !== undefined && classifyReasoning(first.text).label === 'minimal-like'
+}
+
+/** Build one epoch-aware promotion tracker. */
+export function createEpochPromotion(promoteEvents, options = {}) {
+  const includeSubagents = options.includeSubagents === true
+  const promoteGate = options.promoteGate === true
+  const promoteAfterFirstResponse = options.promoteAfterFirstResponse === true
+  const maxPromoteSteps = Number.isSafeInteger(options.maxPromoteSteps) && options.maxPromoteSteps > 0
+    ? options.maxPromoteSteps
+    : 4
+  const promote = new Set(promoteEvents)
+  const gated = promoteGate || promoteAfterFirstResponse
+  /** sessionId -> entry（boundary/promoted + 门控字段） */
+  const state = new Map()
+
+  const freshEntry = (boundary) => ({
+    boundary,
+    promoted: false,
+    toolCalled: false,
+    responded: false,
+    anchored: false,
+    turnEnded: false,
+    steps: 0,
+  })
+
+  /** 门控晋升判定（liangshen decidePromotion 移植）。 */
+  const decideGate = (entry) => {
+    if (entry.promoted) return true
+    if (entry.toolCalled && !promoteGate) return true
+    if (entry.toolCalled && promoteGate && (entry.anchored || entry.steps >= maxPromoteSteps)) return true
+    if (entry.toolCalled && promoteGate && promoteAfterFirstResponse && entry.turnEnded) return true
+    if (!entry.toolCalled && entry.responded && promoteAfterFirstResponse) return true
+    return false
+  }
+
+  /** 应用一个事件；compaction/end 返回新 entry（旧状态清零、boundary 前推）。 */
+  const applyEvent = (entry, event) => {
+    const seq = event.seq ?? 0
+    if (event.type === 'compaction/end') return freshEntry(seq)
+    if (seq <= entry.boundary) return entry
+    if (gated) {
+      if (event.type === 'tool/call') entry.toolCalled = true
+      else if (event.type === 'step/start') entry.steps += 1
+      else if (event.type === 'turn/end') entry.turnEnded = true
+      else if (event.type === 'assistant/message') {
+        entry.responded = true
+        if (!entry.anchored) entry.anchored = hasAnchoredReasoning(event.data?.message?.content)
+      }
+      if (decideGate(entry)) entry.promoted = true
+      return entry
+    }
+    if (promote.has(event.type)) entry.promoted = true
+    return entry
+  }
+
+  /** Scan a session's durable log from scratch (cold start / resume). */
+  const scan = (session) => {
+    let entry = freshEntry(-1)
+    for (const event of session.events) entry = applyEvent(entry, event)
+    state.set(session.id, entry)
+    return entry
+  }
+
+  return {
+    /**
+     * Current phase of the agent's session.
+     * @param agent - the assembly/pre-step agent, or undefined outside an agent.
+     * @returns { boundary, promoted } — `boundary` is the last compaction/end
+     *   seq (-1 before any compaction); `promoted` is true when a durable
+     *   promotion signal exists after that boundary.
+     */
+    status(agent) {
+      if (agent === undefined) return { boundary: -1, promoted: true }
+      const session = agent.session
+      if (session === undefined) return { boundary: -1, promoted: true }
+      // By default subagents keep the full catalog from their very first
+      // request; includeSubagents makes them follow the normal bootstrap phase.
+      if (!includeSubagents && (session.header?.delegationDepth ?? 0) > 0) return { boundary: -1, promoted: true }
+      return state.get(session.id) ?? scan(session)
+    },
+    /** Incremental feed: call on every `session/event`. */
+    observe(session, event) {
+      const entry = state.get(session.id)
+      if (entry === undefined) return
+      const next = applyEvent(entry, event)
+      if (next !== entry) state.set(session.id, next)
+    },
+  }
+}

package/engine/compositions/library/bootstrap-filesystem.yml

@@ -0,0 +1,19 @@
+# module: bootstrap-filesystem
+# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/minimal/agent.cordis.yml
+# local patches: 1
+
+- id: bootstrap-filesystem
+  name: cordis:group
+  group: true
+  isolate:
+    fs: true
+  config:
+    - id: fs-local
+      name: '@deepseek-ai/dsh-fs-local'
+      config:
+        cwd: !!js process.env.DSH_CWD ?? process.cwd()
+
+    - id: str-replace-editor
+      name: '@deepseek-ai/dsh-tool-str-replace-editor'
+      config:
+        maxOutputChars: 16000

package/engine/compositions/library/compaction.yml

@@ -0,0 +1,52 @@
+# module: compaction
+# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/standard/agent.cordis.yml
+# local patches: 0
+
+# ── compaction ──────────────────────────────────────────────────────────────
+
+# `compaction-basic` reads `toolResultPrune` through `ctx.get`, so the pruner must
+# share this realm rather than sit outside it.
+#
+# `tokenMeter` is deliberately NOT in this realm: the meter stays on the HOST
+# plane, and the rows here resolve that one instance. It takes no configuration,
+# keys every fold by Session, and owns the context-meter projection units the
+# browser reads for every session — behind a realm those units would come and go
+# with whichever presets happen to be mounted. What a preset chooses is whether
+# its agent compacts at all, which is `compaction-basic` below.
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    compaction: true
+    toolResultPruner: true
+  config:
+    - id: compaction-basic
+      name: '@deepseek-ai/dsh-compaction-basic'
+
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+
+    - id: tool-result-pruner
+      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+# ── delegation and workflows ────────────────────────────────────────────────
+
+# The `subagents` registry and its spawn/fork backends live in the HOST
+# composition: the registry is a process singleton whose cross-session queries
+# the api-proxy serves to the browser, and a provider name may only be
+# registered once. This preset contributes the delegation TOOLS, which resolve
+# that host registry.
+#
+# `workflows` is different — nothing outside an agent reads it — so every row
+# that reaches it shares one entry-local realm here, and a consumer left
+# outside would resolve a host registry this preset does not populate.
+#
+# `tool-subagent-report` is host-plane for the same reason as the registry,
+# not because a preset may not want it: it registers a CONTINUABLE SETUP on
+# that singleton rather than a tool this agent calls, and the setup list is
+# not scope-aware — one copy per mounted preset means every child gets
+# `report` registered once per live session, which throws on the second.

package/engine/compositions/library/context-gate.yml

@@ -0,0 +1,40 @@
+# module: context-gate
+# source: preset/engine/compositions/source/local/context-gate.yml (本地附加,非官方模块)
+
+- id: context-gate
+  name: ./engine/context-gate.mjs
+  config:
+    promoteOn: either
+    includeSubagents: false
+    allowKinds: __ALLOW_KINDS__
+
+# ── bootstrap ───────────────────────────────────────────────────────────────
+
+# Tool catalog control (mode-owned tool-bootstrap.mjs). V4 Pro conditions
+# strongly on the API tool catalog AND the first request output budget:
+# request #1 exposes the OFFICIAL Minimal preset's real tool pair —
+# persistent `bash` + `str_replace_editor` — which anchors at the
+# adapter-default maxTokens (256000) with no output cap needed (issue #11:
+# 5/5 anchored vs 11/11 standard-like for every standard-family schema);
+# after the session records its first durable promotion signal (a tool call OR
+# the first assistant message, default `promoteOn: either`), later steps keep
+# the assembled catalog and usePtcMode optionally switches the wire to Code
+# Mode (PTC). `bootstrapMaxTokens` is
+# opt-in for standard-schema bootstraps; unset, the adapter default flows. See
+# tool-bootstrap.mjs for the other triggers. Context stripping is NOT here —
+# the context-gate row above owns it.
+#
+# POST-PROMOTION (prompt-tool local addition): both modes keep the assembled
+# catalog after promotion. `usePtcMode` switches the wire presentation to Code
+# Mode (PTC, a single run_code backed by the full registry SDK) instead of
+# narrowing the resident set; the pre-promotion and post-compaction controlled
+# phase below still stays on the bootstrap pair + `compactionTools`.
+#
+# COMPACTION (local addition): after `compaction/end` the session falls back
+# to the controlled phase — bootstrap pair + `compactionTools` — until a NEW
+# durable promotion signal exists past the boundary (epoch-aware, see
+# compaction-epoch.mjs).
+#
+# `includeSubagents: true` keeps the subagent phase in sync with the
+# context-gate row: a subagent's first request sees the bootstrap pair, then
+# its own first reply or tool call promotes it to the assembled catalog.

package/engine/compositions/library/custom-bash.yml

@@ -0,0 +1,14 @@
+# module: custom-bash
+# source: preset/engine/compositions/source/local/custom-bash.yml (本地附加,非官方模块)
+
+- id: custom-bash
+  name: ./engine/custom-bash.mjs
+  disabled: !!js process.platform !== 'win32'
+  config:
+    timeoutMs: 120000
+    maxOutputBytes: 64000
+
+# ── filesystem ──────────────────────────────────────────────────────────────
+
+# Both register into the host `tools` registry and provide nothing, so
+# they need no realm. The `fs` service and its policy stay in the host.