dsh-plugin-prompt-tool 0.4.2 → 0.6.0

package/README.md

@@ -1,222 +1,131 @@
-# 提示词工具（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`，身份类提示词可只注入子代理
+- 🗂️ **内容与执行分离**：每条提示词配置渲染为 `~/.dsh/.agent-presets/<预设>/prompt-configs/` 下的 yml，引擎按文件名数字前缀顺序扫描
+- 🧩 **三层合并**：引擎默认（按 params 生成）< 模板默认 promptConfigs < 预设 promptConfigs，同名 `id` 覆盖
+- 🖥️ **独立工作台**：侧边栏「提示词工具」入口（主会话/子代理/注入层/技能设置/预设配置五页）+ 设置面板提示词配置页（列表/表单/模板插入/保存前校验）
+- 🧪 **七种内容策略**：`static / first-turn-anchor / guide-auto / custom-fallback / instruction-hint / placeholder / world-book`（world-book 支持 ST selectiveLogic 选择性触发：任一/副键全中/排除）
+- 🛡️ **失败不伤会话**：单条失败跳过 + `warnOnce`；配置错误挂载时 fail loud；`dedupe: session` 持久幂等
+- 🎭 **SillyTavern 导入**：JSON 预设卡片一键转换为本地预设——`prompts[]` 映射提示词配置、setvar/getvar 收集进顶层 `variables`（未定义自定义宏自动登记空值占位）、`enable_web_search` 按开关装配工具；采样参数剥离（模型设置 UI 管理）
+- 🎴 **角色卡库**：SillyTavern 角色卡（PNG tEXt chunk `ccv3`/`chara`，或 chara_card JSON）导入独立库（`.characters/<id>/`，含原图/转换参数/角色记忆），按需「导入到当前预设」（`chara-<卡>-` 前缀合并、幂等可移除），多文件自动合并
+- 📚 **世界书**：`character_book` 转 world-book 策略配置（`keys` 命中触发 / `constant` 常驻 / `useRegex` 正则 / `selectiveLogic` 组合逻辑），与模块卡片同一存储与编辑（模块列表「世界书」过滤 + 批量启用/禁用）
+- 🧩 **模板变量**：预设级 `variables` 段（`{{key}}` 插值源）——模块列表顶部「模板变量」卡片统一编辑（可折叠/清空/停用/失焦自动保存）；锚定匹配引擎（anchor-match）统一 custom-fallback 与 world-book 的匹配语义
+- 💬 **会话变量工具**：`session_var`（list/get/set/clear）——模型维护角色状态（`{{心情}}` 等），会话级覆盖预设默认；ST 运行时宏（`{{lastusermessage}}` / `{{lastcharmessage}}`）从会话事件提取
+
+## 预设参数体系
+
+预设行为由一份 `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` |
+| 人设 | 模块列表的 `persona-main`（system-section + `deployment:persona`，complete 互斥 + suppressRuntimeContext）；`subagentPersona`（子代理显式，缺省经 scope 链继承主会话） |
+| 工具集 | `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` 组内拼接顺序
+- 文本插值：`{{key}}` 全层支持——配置/预设 `variables` 优先，ST 运行时宏（lastusermessage 等）次之，内置 `{{DSH_HOME}}/{{WORKSPACE}}/{{CWD}}` 兜底，未注册保留字面（system-section 注册期无会话时运行时宏替换为空，不残留）
+
+
+## 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` 原样保留
+- 采样参数（`temperature` / `openai_max_tokens` / `reasoning_effort`）**剥离**——模型参数统一由「模型设置」UI / 宿主默认管理
+- ST 变量：`setvar`/`getvar`（含默认值）收集进顶层 `variables`；未定义自定义宏自动登记空值占位（不留字面）
+- `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` → 角色设定；采样参数剥离（模型设置 UI 管理）
+- **导入到当前预设**：参数合并进当前预设 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`/`getvar` 收集进顶层 `variables`、未定义自定义宏自动登记空值占位；
+  `trim`/注释/ERA 剥离，`{{user}}`/`{{char}}` 替换；运行时宏（lastusermessage/lastcharmessage）
+  从会话事件提取；TavernHelper 扩展注入物自动剥离
+- **会话变量**：`session_var` 工具（list/get/set/clear）维护角色状态（会话级覆盖预设默认，
+  结束即失）；跨会话长期记忆用 `world_book` note（持久 memory.md 跟随角色卡）
+
+详细转换规则见 [SillyTavern.md](SillyTavern.md)。
+
+## 开发与验证
+
+```sh
+pnpm install && pnpm build
+pnpm test          # 287 单测：渲染/合并/六层接线/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/anchor-match.mjs

@@ -0,0 +1,117 @@
+/**
+ * anchor-match — 关键词锚定匹配引擎（纯函数，无状态，无依赖）。
+ *
+ * 从 strategies 拆解：custom-fallback（自定义锚定词）与 world-book（关键词触发）
+ * 共用同一套匹配语义——主键/副键、大小写、整词、正则、组合逻辑。
+ *
+ * 逻辑对齐 ST world_info_logic：
+ *   any  = AND_ANY(0)：主键或副键任一命中即激活（world-book 默认 / custom-fallback 单锚）；
+ *   all     = AND_ALL(3)：主键命中且副键全部命中；
+ *   not     = NOT_ALL(1)：主键命中且副键全部未命中（排除）；
+ *   notAny  = NOT_ANY(2)：主键命中且至少一个副键未命中（部分排除）。
+ *
+ * 模式：
+ *   scan   = 全文扫描（world-book 消息批匹配）；
+ *   prefix = 文本开头匹配（custom-fallback 首轮 reasoning 锚定确认：ASCII 词边界前缀，
+ *            非 ASCII 直 prefix）。
+ */
+
+/** 组合逻辑（ST world_info_logic 映射）。 */
+export const MATCH_LOGIC = {
+  ANY: 'any',
+  ALL: 'all',
+  NOT: 'not',
+  NOT_ANY: 'notAny',
+}
+
+/** 正则转义（关键词原样匹配时用）。 */
+export function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** 单键正则编译（逐键匹配：any/all/not 需要精确的命中键数，捕获组会干扰 match 计数）。 */
+function compileSingle(key, { caseSensitive, wholeWords, useRegex }) {
+  const flags = caseSensitive ? '' : 'i'
+  if (useRegex) {
+    // ST use_regex=true：键原样作为正则（作者负责合法性）。
+    return new RegExp(key, flags)
+  }
+  if (wholeWords) {
+    return new RegExp(`(^|[^\\p{L}\\p{N}])(${escapeRegExp(key)})(?![\\p{L}\\p{N}])`, `${flags}u`)
+  }
+  return new RegExp(escapeRegExp(key), flags)
+}
+
+/** 编译键列表 → [{ key, re }]（剔除空键）。 */
+function compileKeyList(list, options) {
+  return (Array.isArray(list) ? list : [])
+    .map((key) => String(key).trim())
+    .filter((key) => key.length > 0)
+    .map((key) => ({ key, re: compileSingle(key, options) }))
+}
+
+/**
+ * 创建锚定匹配器。
+ * @param {object} options
+ * @param {string[]} options.keys 主键
+ * @param {string[]} [options.secondaryKeys] 副键
+ * @param {boolean} [options.caseSensitive]
+ * @param {boolean} [options.wholeWords]
+ * @param {boolean} [options.useRegex]
+ * @param {'any'|'all'|'not'|'notAny'} [options.logic] 组合逻辑（缺省 any）
+ * @param {'scan'|'prefix'} [options.mode] 匹配模式（缺省 scan）
+ * @returns {{ scan: (text: string) => { primary: number, secondary: number, active: boolean } }}
+ */
+export function createAnchorMatcher(options = {}) {
+  const {
+    keys = [],
+    secondaryKeys = [],
+    caseSensitive = false,
+    wholeWords = false,
+    useRegex = false,
+    logic = MATCH_LOGIC.ANY,
+    mode = 'scan',
+  } = options
+  const primaryList = compileKeyList(keys, { caseSensitive, wholeWords, useRegex })
+  const secondaryList = compileKeyList(secondaryKeys, { caseSensitive, wholeWords, useRegex })
+
+  const scan = (raw) => {
+    const text = String(raw ?? '')
+    if (mode === 'prefix') {
+      // custom-fallback 锚定确认：仅主键首词，文本开头匹配。
+      const word = (Array.isArray(keys) ? keys : []).map((key) => String(key).trim())
+        .find((key) => key.length > 0)
+      if (word === undefined || text.length === 0) return { primary: 0, secondary: 0, active: false }
+      const hit = /^[\x20-\x7E]+$/.test(word)
+        ? new RegExp(`^${escapeRegExp(word.toLowerCase())}\\b`, 'i').test(text)
+        : text.startsWith(word)
+      return { primary: hit ? 1 : 0, secondary: 0, active: hit }
+    }
+    if (primaryList.length === 0 && secondaryList.length === 0) {
+      return { primary: 0, secondary: 0, active: false }
+    }
+    const countHits = (list) => {
+      let hits = 0
+      for (const { re } of list) {
+        re.lastIndex = 0
+        if (re.test(text)) hits += 1
+      }
+      return hits
+    }
+    const primary = countHits(primaryList)
+    const secondary = countHits(secondaryList)
+    let active = false
+    if (logic === MATCH_LOGIC.ALL) {
+      active = primary > 0 && (secondaryList.length === 0 || secondary === secondaryList.length)
+    } else if (logic === MATCH_LOGIC.NOT) {
+      active = primary > 0 && secondary === 0
+    } else if (logic === MATCH_LOGIC.NOT_ANY) {
+      active = primary > 0 && secondaryList.length > 0 && secondary < secondaryList.length
+    } else {
+      active = primary > 0 || secondary > 0
+    }
+    return { primary, secondary, active }
+  }
+
+  return { scan }
+}

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