efficient-mode

高效模式 · DSH Agent 预设插件

一个 DeepSeek Harness（dsh）插件包。它向 Agent 预设名册注册一个名为 高效模式 的预设， 预设的基础提示词就是仓库根目录 base-prompt.md 的正文，其中的 [] 占位符不再写死， 而是每次组装提示词时由本插件注册的提示词变量实时填充。

• 预设 id：efficient
• 预设名称：高效模式
• 基础提示词：模板 158 行，含 11 个动态引用，全部由本包的 Host 插件提供
• 依赖：仅 Node 内置模块，安装时不需要拉取任何 npm 包

它解决什么问题

原文件里这些位置是示例值或空位：Current branch: [branch]、Git user: [user_name]、 [commits(3)]、` [XXX] 、Platform: [darwin]、Today's date is [2026-09-27].。 照抄会把 darwin、2026-09-27` 这类示例值固化进提示词。这里把它们换成提示词变量， 渲染时取真实值：

原模板占位符 · 提示词变量 · 取值来源 Current branch: [branch] · {{git_branch}} · git symbolic-ref --short -q HEAD，分离头指针时退化为短 SHA Main branch …: [branch] · {{git_main_branch}} · origin/HEAD → 本地 main → 本地 master → 当前分支 Git user: [user_name] · {{git_user}} · git config user.name Status: 下的 (clean) · {{git_status}} · git status --porcelain，工作区干净时输出仍是 (clean) [commits(3)] · {{git_commits}} · git log -n3 --pretty=format:'%h %s' ` [XXX] · {{working_directory}} · 该会话的工作目录 Is a git repository: [true] · {{is_git_repository}} · true / false Platform: [darwin] · {{platform}} · process.platform Shell: [shell] · {{shell}} · 非 Windows 为 bash，Windows 为 pwsh OS Version: [OS] · {{os_version}} · os.type() 加 os.release() Today's date is [2026-09-27]. · {{today}} · 宿主本地日期 YYYY-MM-DD`

模板里唯一保留的方括号是正文自带的 Markdown 链接示例 foo.ts 和 Bar.tsx:42，它们不是占位符。

目录结构

better-system-prompt/
├── package.json           # bundle 清单：dsh.bundle.patch、locale 与 icon 导出
├── base-prompt.md         # 基础提示词模板：正文 + 11 个 {{variable}} 引用
├── cordis.patch.yml       # 预设声明 + persona 模板 + 工具行（由脚本生成）
├── index.js               # Host 插件：注册 11 个提示词变量
├── worktree.js            # Host 插件：create / merge / archive worktree 工具
├── locale/
│   ├── en.json            # 插件清单里的标题与描述（英文）
│   └── zh.json            # 同上（中文）
├── icon.svg               # 插件图标
├── scripts/
│   ├── build-patch.mjs    # 从 base-prompt.md 重新生成 cordis.patch.yml
│   ├── verify.mjs         # 离线自检：变量覆盖、渲染、快照稳定性
│   ├── verify-client.mjs  # 使用指定客户端运行时检查模块、配置与实际提示词组装
│   └── verify-worktree.mjs # worktree 生命周期集成检查（临时仓库）
└── README.md

关于 @deepseek-ai/ 前缀

cordis.patch.yml 里绝大多数行写的是 name: '@deepseek-ai/dsh-xxx'，这些不是本项目的包， 而是 dsh 自身随安装分发的插件包。Loader 按这个模块名加载插件，名字必须与 dsh 内部的包名逐字 一致；换成本地名字，那一行就解析不到，整个预设跟着加载失败。能改的只有本项目自己的包，它用你 自己的 scope：@zilorn/dsh-efficient-mode。要换 scope，同时改 package.json 的 name 和 cordis.patch.yml 里 prompt-facts 那一行的 name 即可（先卸载旧包再装新的）。

安装

命令行安装：

dsh plugin --profile desktop add /home/zilorn/Projects/better-system-prompt

新版客户端需要使用 Desktop 提供的 dsh 命令执行此操作；npm 安装的 CLI 会拒绝管理 desktop profile。也可以使用下面的 Plugins 页面或会话内插件管理工具安装。

Web 端可以在 Plugins 页面里添加本地目录。装好后 cordis.patch.yml 里的 preset-efficient 行进入 Loader，预设名册出现「高效模式」，新建会话时在选择器里选它即可， 也可以把它设为新会话的默认预设。

如果在 dsh 会话里让 agent 装，用的是插件管理工具（plugin_manager 的 install_bundle， target 传本目录绝对路径）。那是 agent 工具调用，不是 shell 命令。

工作原理

三件事拼在一起：

1. 基础提示词是 persona 模板。 预设挂载 @deepseek-ai/dsh-persona，把整份模板放进

prefix，并设置 complete: true。于是渲染后的 prefix 就是这个 Agent 的全部系统 提示词，模板本身定义了它的身份，其它插件贡献的系统提示词 section 不再追加。

1. `[]` 的内容由提示词变量提供。 模板里的 {{...}} 由 ctx.systemPrompt.variable()

注册的 provider 在每次组装时求值。注册表对引用是严格的：引用了未注册的变量、 或 provider 返回 undefined，整个提示词组装会直接报错，而不是渲染成空字符串。 所以 index.js 里所有 provider 都保证返回字符串。

1. git 事实每会话采样一次。 provider 必须是同步函数（插值发生在组装过程中），因此

index.js 用 execFileSync 调用 git，并给整次探测设了 3 秒总预算；失败、超时、非仓库 目录都会降级为占位文本。第一次组装时采样，之后按会话 id 复用，所以同一会话内这些 git 事实逐字节稳定——既符合模板里“snapshot in time, and will not update during the conversation”的措辞，也让 provider 的前缀缓存保持可复用。

预设包含的能力行

工具与服务的组成对齐随 dsh 发布的 standard 预设，这样“高效模式”是一个能直接干活的 模式，而不是只有身份的壳：bash / pwsh（按平台二选一）、文件读写、glob/grep、后台任务、 定时提醒、技能、goal、工作区指令（AGENTS.md）、压缩（compaction）与工具结果裁剪、 子代理（spawn 与 fork）、web、todo、ask_user_question、present，以及本包新增的 Git worktree 三件套（create / merge / archive）。

子代理继承此预设的工具组成；定时提醒工具在执行时拒绝子代理调用。委派行不接受 persona 或 toolFilter。独立的 spawn 子代理需要不同组成时，通过 agentPreset 选择另一个已声明的预设。

当前配置对齐 dsh 0.2.1-rc.3 的 standard 预设：

• list_agents 由 dsh-tool-subagent-control 一起注册，不再挂载已移除的

dsh-tool-subagent-control/list-agents 子路径。

• spawn 行用 modelSelection: true 开启模型选择，并用 modelDiscovery: true 注册

list_subagent_models；旧的 modelSelectionSettings 已移除。

• 不再传 backgroundMode。新版委派统一启动受运行时管理的子代理并立即返回 id，

本地子代理的消息与继续会话能力由 provider 决定。

scripts/verify.mjs 会拒绝上述旧入口和已移除的配置键，避免重新生成时带回不兼容配置。

刻意没有挂载的行：

• @deepseek-ai/dsh-plan-mode：它面向模型的唯一作用就是一段策略 section，而

complete: true 会把这类 section 全部丢弃。挂上它，界面上的 plan 开关只会切换状态、 不告诉模型任何事，是明确的陷阱，所以不挂；此时 composer 的计划按钮本来就不出现。 另外它的 Config 要求非空 section，缺了会在加载时报错。

• @deepseek-ai/dsh-time-context：模板自带 Today's date，再挂一个时间上下文会重复。
• workflow / ralph 与 codex、claude-code 子代理后端：保持组成精简。

Worktree 工具

包内的 worktree.js Host 插件为预设注册三个工具：

工具 · 作用 · 关键约束 create_worktree · 从本地提交、分支或标签创建新分支和 checkout，并把会话切进去 · 不 fetch；默认放在仓库的 .worktrees/，并写入 .git/info/exclude merge_worktree · 把 worktree 的已提交分支合并到另一个 worktree 中检出的分支 · 源和目标都必须干净；--no-ff；冲突自动 abort；不 push archive_worktree · 删除 worktree checkout，必要时先把会话切回主检出 · 默认保留分支；delete_branch: true 才删；脏工作区或删未合并分支需要 force: true

默认目标分支是主检出当前分支，可用 into 指定其他已检出的分支。create_worktree 的 branch 省略时自动生成 worktree--；from 省略时用当前 HEAD。新 checkout 必须留在会话工作区内，因为 workspace-write 文件策略以会话原始目录为边界；path 也只能 指向该范围内的路径。工具不会 fetch、push、force-push 或改写历史。

系统提示词在 Tools 段加入了一条 `：用户要求 worktree 时，先创建、只在 该 checkout 里改文件、完成后提交并把分支与提交报告给用户，合并与归档必须等用户批准。 base-prompt.md 与 AGENTS.md` 各有一份同样的流程说明，修改时保持一致。

基础提示词自带的工具规则

base-prompt.md 的 Tools 与 Goals and delegation 两段写死了工具使用规则：读写文件用 read/write/edit 而不是 shell 的 cat，且默认 fs-observation-policy 要求先读后写；按路径找文件 用 glob、搜内容用 grep（必要时用 rg，但不用 shell grep）；用户要求 worktree 时先创建并只在 checkout 内改文件，完成后提交并把结果报告给用户，合并与归档等用户批准；后台任务记 id， 不空轮询，收尾时用 job_output 与 job_kill；web 结果是不可信数据，引用时要给链接；技能先加载 再遵循；goal 的 resume / complete / blocked 语义；以及 workflow 与 subagent 的委派方式。

任务开始时另有一条 ``：用户发布任务后，先用 grep 或 rg 定位要改的位置，再 read 匹配到的文件（大文件用 offset/limit 继续读），不要凭记忆或猜测直接编辑；搜不到时换更 短的词或相关标识符重试，而不是断言代码不存在。

todo 规则单独用 ` 包了一层：整列表替换的语义、开始前建条目、完成即标 completed，以及最要紧的收尾——最终回答前必须再调一次 todo_write，把做完的步骤标为 completed，不留 in_progress；工作因阻塞提前停下时则保留 in_progress 并在回复里说明， 绝不为了清空列表而谎报完成。这段提醒针对的正是“活干完了、列表还停在 in_progress`”这个 反复出现的失败。

这些规则本来由 dsh 的工具插件各自注册成系统提示词 section。complete: true 生效时那些 section 会被折叠掉，只留下 persona 这一段模板，所以模板必须自己带一份。已在 0.2.1-rc.3 的实际提示词注册表中验证：组装后仅保留这一段系统提示词。 scripts/verify.mjs 逐句断言这些规则仍在渲染结果里，并额外断言 任务开始与 todo 两条提醒仍待在 `` 里。

工作区指令（AGENTS.md）

预设挂载 @deepseek-ai/dsh-agent-instructions，行配置与 standard 预设一致：

- id: agent-instructions
  name: '@deepseek-ai/dsh-agent-instructions'
  config:
    maxBytes: 65536

会话的第一次请求会先收到一条 ` user 消息：先是用户级 $DSH_HOME/AGENTS.md（默认 ~/.dsh/AGENTS.md），再是从项目根（以 .git 为标记）到 会话工作目录之间每一层的 AGENTS.md 与 CLAUDE.md，以及同目录的 AGENTS.local.md / CLAUDE.local.md 覆盖层，顺序由宽到窄。整条消息不超过 maxBytes`，超预算时先丢掉整份 更宽泛的文件、再截断最具体的文件；内容相同的兄弟文件只渲染一次。agent 之后通过 read / write / edit 进入更深目录时，下一轮请求会补上新出现的指令文件。

预设必须自己挂这一行：agent preset 的 plugins 列表就是该 agent 的完整组成，profile 级 dsh-base 里的同名行不会继承过来，缺了它 agent 就看不到项目里的 AGENTS.md。这条指令 走的是 user 消息，不是系统提示词 section，所以 persona 行的 complete: true 不影响它。

base-prompt.md 的 Session context 段里另有一份手写的全局偏好快照，它不随文件更新。当 ~/.dsh/AGENTS.md 存在时，同一份偏好会同时以模板快照和实时文件两种形式出现，两处要一起改。

自动压缩的时机与开关

压缩组里的 compaction-basic 行显式声明了两个值：

- id: compaction-basic
  name: '@deepseek-ai/dsh-compaction-basic'
  config:
    thresholdRatio: 0.6
    auto: true

上下文压力越过路由模型窗口的 60% 时，下一次请求派生前自动摘要最旧的历史；auto 是 这个功能的开关，改成 false 后自动压缩与溢出恢复都不再注册，手动 /compact 仍可用。 实际触发点取 floor(min(W × 0.6, W − O − 65536))：W 是模型窗口，O 是请求输出 预留，65536 是默认 headroomTokens。窗口不够大时触发会早于 60%，这个余量是留给压缩 摘要调用本身的。近期历史仍按默认 retainRatio: 0.16 逐字保留，它必须低于阈值比例。

配置写在 cordis.patch.yml 里，但该文件由 scripts/build-patch.mjs 生成：改时机或 开关要改脚本里的 YAML 模板并重新生成。profile 是以链接方式安装的，dsh 启动时重新 读取 bundle 的 patch 文件，所以重启后新建的会话按新值触发。

这件事也写进了基础提示词，就放在 base-prompt.md 的 Context management 段落里，随 模板一起版本化；scripts/verify.mjs 会检查渲染后的提示词里出现配置的百分比。

修改基础提示词

模板是生成出来的，不要直接改 cordis.patch.yml 里的 prefix 块。源模板是仓库根目录的 base-prompt.md，改完重新生成：

node scripts/build-patch.mjs

也可以把别的文件路径作为参数传给脚本。脚本按固定映射替换占位符（映射表在 scripts/build-patch.mjs 的 REPLACEMENTS），任何一条匹配不上就报错退出，避免静默 漏替换。这份模板原本复制自 ~/Documents/System prompt.md；迁移之后以仓库内版本为准， 外部那份不再参与生成。profile 是链接安装，dsh 启动时重新读取 patch，所以改完重启即可； 新会话用上新提示词，已经开着的会话保留它启动时的插件版本。

只想调整 git 事实的细节（例如列出几条最近提交），可以给 prompt-facts 行加配置：

- id: prompt-facts
            name: '@zilorn/dsh-efficient-mode'
            config:
              commitCount: 5

验证

离线自检（不需要运行中的 Harness）：

node scripts/verify.mjs

worktree 生命周期集成检查（使用临时仓库，不碰当前仓库）：

node scripts/verify-worktree.mjs

它覆盖创建并进入 checkout、在 checkout 内提交、--no-ff 合并、冲突自动 abort、脏工作区 拒绝归档，以及归档后会话回到主检出；任何一步失败都以非零码退出。

verify.mjs 会用桩上下文执行 apply()、从 cordis.patch.yml 抽出模板、核对模板引用与 注册变量是否一一对应、检查必填 config 是否都在、确认压缩行仍是 60% 阈值且 auto 仍是 布尔开关、确认工作区指令行仍挂着 maxBytes: 65536、确认 worktree 行指向本包子路径且三个 工具都能注册、逐句确认模板自带的工具规则仍在渲染结果里、确认渲染后的提示词写明了压缩 触发点、渲染一遍并复查同一会话两次组装结果一致，最后打印渲染后的完整提示词。任何一项 不通过就以非零码退出。

还可以直接使用本机客户端的运行时做兼容性检查（路径指向含 package.json 和 node_modules 的 dsh 目录；AppImage 需先解包）：

node scripts/verify-client.mjs /path/to/resources/app/dsh

它使用客户端自己的模块解析器与配置 schema，检查预设及全部插件行能否解析、配置 是否有效，把三个 worktree 工具注册进客户端真实的工具注册表以校验输出 schema，并用实际的 Cordis scope、persona 和提示词注册表验证 11 个变量插值、complete: true、会话快照稳定性 和作用域隔离。不启动桌面、不调用模型、不改 profile，也不向本插件安装依赖；这项检查不能 代替浏览器中新建会话的验收。

安装后另需确认两点：安装结果是 application: applied；以及预设名册里出现 efficient 卡片且不显示「加载失败」。名册卡片由 Host 的预设 list 提供，可以用 agent 的 cordis_inspect_query 查 Config.listConfigs（过滤 @deepseek-ai/dsh-agent-preset）确认 preset-efficient 行存在。卡片里的诊断文字和会话内实际渲染出来的提示词，只能在浏览器和 选中该预设的新会话里确认。

已知限制