全局提示词 YMRwithNoworry/dsh-global-system-prompt

dsh-global-system-prompt

npm version
license
topic: dsh-plugin

概述

dsh-global-system-prompt 给 DeepSeek Harness 补上 cc-switch 那个「全局提示词」：一段你自己写的文字，每一次对话都会带上，在 Web 设置面板里直接编辑，保存后下一轮对话即生效。

它的做法有两条通道：把这段文字注册成系统提示词里的一个独立段落（section），同时写进当前会话所在项目的 AGENTS.md。系统提示词那条保证 dsh 每一轮都带上；AGENTS.md 那条保证别的工具（Claude Code、Codex、Cursor、Zed……）和以后的会话也带上，并且跟着仓库走：

- 进的是系统提示词，位置固定可调，默认紧跟在 harness 身份行之后、persona 之前（order -900）。
- 对所有会话生效：根会话、preset 挂载的 agent、进程内 subagent 都会带上（外部 CLI 子代理如 Codex/Claude Code 有自己的提示词，不受影响）。
- 不会被 preset 遮蔽：段落名 user:global-prompt 是插件独占的，agent preset 的 persona 只会覆盖 deployment:persona-prefix，覆盖不到它。
- 改完即生效：每个 step 重新渲染时都会重新读文件，所以保存后下一次请求就带上新内容，不用重启 dsh。
- 消耗固定：内容不变就不会污染 prompt 前缀缓存；内容变了（或清空）只改变这一段。
- 告诉模型全局文件在哪：注入内容末尾会自动附一段文件位置说明，写出下面两个文件的绝对路径。dsh 自己注入的运行时上下文只把用户全局指令说成一句「AGENTS.md」（不给路径），模型为此经常满硬盘找；这段说明就是治这个的。
- 同时写进项目：每个会话开始时，它所在项目根目录的 AGENTS.md 会被维护一段带标记的区块，正文与系统提示词那段完全一致（见下）。区块之外的内容插件的字节都不动。

Harness file locations (exact paths — read or edit these directly instead of searching for them):
- global prompt (injected by the dsh-global-system-prompt plugin): C:\Users\me\.dsh\global-prompt.md
- user-global instructions (the "AGENTS.md" the runtime context mentions): C:\Users\me\.dsh\AGENTS.md

于是模型（以及你自己）不用再猜「全局 AGENTS.md 到底是哪个」：要读要改，直接照这个路径操作即可。想关掉就 announcePaths: false；想换文案就 pathsNote。

两条通道可以各关各的：enabled: false 整行停用，syncProjectAgents: false 只停项目 AGENTS.md（系统提示词照旧）、announcePaths: false 只去掉文件位置说明。

目录

- 安装
- 使用
- 同步到项目 AGENTS.md
- 配置
- 与 AGENTS.md / dsh-global-rules 的关系
- 实现
- 开发

安装

从 npm 装（正式方式）：

Web 面板用的 profile
dsh plugin --profile web add dsh-global-system-prompt

TUI profile 也可以装（没有 Web 服务器，只有注入与项目同步生效）
dsh plugin --profile dsh-tui add dsh-global-system-prompt

从 GitHub 装（想直接跟仓库走，或者钉住某个提交）：

dsh plugin --profile web add github:YMRwithNoworry/dsh-global-system-prompt

钉住提交：仓库名后面接 #
dsh plugin --profile web add github:YMRwithNoworry/dsh-global-system-prompt#

从本地 checkout 装（开发/自用）：

复制一份进 profile：改完源码要重装一次
dsh plugin --profile web add file:

或者软链一份：改完源码直接重启 dsh
dsh plugin --profile web add link:

包名是 dsh-global-system-prompt。npm 上另有一个别人的 dsh-global-prompt（同名不同包，与本包无关），别装错了。

dsh plugin add 会把包加进 profile 的 dependencies，并把声明了 dsh.bundle 的包追加到 dsh.profile.bundles。新增 bundle 是启动边界，装完要重启一次 dsh；之后改提示词内容就完全不用重启了。

装完可以先不启动、只验证层是否合入：

bash
dsh --profile web --dump-config | Select-String -Context 0,8 'global-system-prompt'

应该能看到一行 # == dsh-global-system-prompt 以及插入的行： yaml
- id: global-prompt
name: dsh-global-system-prompt
config:
enabled: true
order: -900
...

使用

打开 设置 → 全局提示词，在文本框里写内容，保存。

- 保存后下一次请求（下一轮对话）生效，当前已经发出的那一轮不变。
- 文件默认是 ~/.dsh/global-prompt.md（即 $DSH_HOME/global-prompt.md），也可以直接用任何编辑器改它——面板上的「重新读取」按钮会重新拉取。
- 文件存在但内容为空 = 不注入提示词正文（文件位置说明仍会附加，见 announcePaths），这也是临时静音的办法；删掉文件则回到配置里的 text 兜底（默认为空）。
- 面板会显示提示词文件路径、用户全局指令文件路径与状态、段落位置 order、实际注入字节数，还有一个「实际注入预览」可以展开看模型读到的原文；文件超过 maxBytes（默认 64 KiB）时超出部分不会注入。
- 面板底部还有两行关于项目 AGENTS.md 的状态：本进程同步过哪些项目、最近一次动作（已创建 / 已更新 / 已是最新 / 已移除 / 已跳过 / 失败），以及「写入项目的区块」预览。

同步到项目 AGENTS.md

系统提示词只影响 dsh。同一个仓库你还可能用别的工具打开，它们读的是项目里的 AGENTS.md；换个工具、换个终端、交给同事，规则就没了。所以插件把同一段提示词同时写进当前会话所在项目的 AGENTS.md：写一次，项目里所有工具都读得到，还跟着 git 走。
markdown

Global rules — follow these in every task in this project:

（这里是全局提示词的原文）

| 问题 | 行为 |
| 写哪个文件 | 从会话工作目录向上找到第一个带 .git 的目录当项目根，写它的 AGENTS.md；一路到盘符根都没有标记，就退回到会话工作目录本身（projectAgentsFallback: 'skip' 可改成"找不到就不写"） |
| 文件不存在 | 自动创建（连同缺失的目录） |
| 已经有别人的内容 | 原样保留，区块追加在末尾；区块之外的内容插件一个字节都不动 |
| 什么时候写 | 会话开始写一次（agent/session-start——harness 保证它在首次组装提示词之前，所以第一个 step 就读得到），之后每个 step 复查一次（内容没变时只花一次 stat） |
| 提示词改了 | 下一次复查时换成新内容，不用重启 |
| 区块被手删 / 被合并冲突吃掉 | 下一步写回；想彻底停就删掉区块后把 syncProjectAgents 设为 false |
| 提示词被清空 | 区块被摘掉；如果那个 AGENTS.md 除了这个区块什么都没有（也就是它是插件建的），文件本身也会删掉 |
| 写不了 | 文件超过 1 MiB、标记只剩一半（被手改坏）、读写报错——都只记一条 warning 并保持文件原样，系统提示词照常注入，回合不会中断 |

几点说明：

- 指令性：区块开头那行 Global rules — follow these in every task in this project: 由 projectAgentsPreamble 控制，用你自己的话写也行，比如 projectAgentsPreamble: '全局规则，本项目所有任务都必须遵守：'；设成 '' 则只留正文。写进 AGENTS.md 的正文是未转义的原文（escapeBraces 只作用于系统提示词段落那条通道），所以 JSON、{{placeholder}} 这类内容在项目文件里长什么样就是什么样。
- 会有两份：在 dsh 会话里同一段规则会出现两次——一次在系统提示词，一次是 AGENTS.md 作为工作区指令注入的上下文（dsh-agent-instructions 在首次组装时读它，之后按文件变更重投影）。这是刻意的：前者是 dsh 的实时通道，后者是跨工具通道。不想在项目里留痕就 syncProjectAgents: false。
- 不碰用户的全局文件：$DSH_HOME/AGENTS.md 是 dsh 自己和 dsh-global-rules 的地盘，插件只声明它的位置、绝不写它；万一项目根正好解析到它，插件会跳过并记一条 warning。
- 写入是原子的：先写同目录的临时文件再 rename，harness 正在读 AGENTS.md 时不会读到半截内容；有多个 dsh 进程时也不会互相截断。

配置

配置写在行里。默认值如下（也就是本包的 cordis.patch.yml）： yaml
- id: global-prompt
config:
enabled: true
file: ~/.dsh/global-prompt.md # 默认 $DSH_HOME/global-prompt.md；支持 ~ / ~/ / ~\
order: -900
text: ''
maxBytes: 65536
escapeBraces: true
announcePaths: true
instructionsFile: ~/.dsh/AGENTS.md # 默认 $DSH_HOME/AGENTS.md；'' 表示不提 includeInstructions: false pathsNote: '' syncProjectAgents: true projectAgentsFileName: AGENTS.md # 写进项目根的这个文件；只能是文件名
projectRootMarkers: ['.git'] # 向上找项目根用的标记
projectAgentsFallback: cwd # 找不到标记：cwd 写会话目录本身 / skip 不写 projectAgentsPreamble: 'Global rules — follow these in every task in this project:'

| 字段 | 默认值 | 含义 |
| enabled | true | 总开关。false 时不注册段落、也不写项目 AGENTS.md（面板路由仍在，方便你先写好内容再打开） |
| file | $DSH_HOME/global-prompt.md | 提示词文件；相对路径按进程工作目录解析 |
| order | -900 | 段落位置。-1000 是 harness 身份行，0 是部署 persona 前缀，500 是 plan 策略；越小越靠前 |
| text | '' | 仅当文件不存在时使用的兜底文本 |
| maxBytes | 65536 | 注入内容的 UTF-8 字节上限，超出部分截断（面板会提示） |
| escapeBraces | true | 中和文本里的 {{（见下）；只影响系统提示词那条通道 |
| announcePaths | true | 在末尾附加「文件位置说明」，写出下面两个文件的绝对路径（模型不必再找） |
| instructionsFile | $DSH_HOME/AGENTS.md | dsh 自己的用户全局指令文件；用于位置说明。设为 '' 则完全不提它 |
| includeInstructions | false | 把该文件的内容也并进这一段。默认关闭，因为 base 系 profile 里 dsh-agent-instructions 已经它会作为上下文注入；只有在没有挂那个插件的组装（比如自建 sdk-minimal）里才需要打开 |
| pathsNote | '' | 自定义位置说明文案（原样使用、不支持占位符）。留空则用生成的英文说明 |
| syncProjectAgents | true | 把提示词同步进会话项目的 AGENTS.md（见上）。false 只保留系统提示词那条通道 |
| projectAgentsFileName | AGENTS.md | 项目文件的名字，只能是裸文件名（想写 CLAUDE.md 就改这里） |
| projectRootMarkers | ['.git'] | 向上找项目根时的标记名；标记文件或目录都算 |
| projectAgentsFallback | cwd | 一路没找到标记时：cwd 用会话工作目录本身，skip 干脆不写 |
| projectAgentsPreamble | Global rules — follow these in every task in this project: | 区块开头那行给模型看的指令，原样写入；'' 只留正文 |

想覆盖某项时，在 profile 的 ~/.dsh/profiles//cordis.patch.yml 里按 id 改——patch 会整体替换该行的 config，所以要写全： yaml
- id: global-prompt
config:
enabled: true
order: -1100 # 放到身份行之前 file: ~/.dsh/my-global-prompt.md text: '' maxBytes: 65536 escapeBraces: true syncProjectAgents: true projectAgentsPreamble: '全局规则，本项目所有任务都必须遵守：'

关于 escapeBraces（重要）

系统提示词段落会把 {{name}} 当作变量插值，遇到未注册的变量名会抛错并中断这一轮，而且没有转义语法。所以如果你会在全局提示词里写 JSON、模板、{{placeholder}} 这类内容，保持 escapeBraces: true（默认）：插件会把每个 {{ 中间插入一个零宽空格（模型看不到，人眼也看不到），插值就不会命中。确实需要原样注入时才设为 false。

与 AGENTS.md / dsh-global-rules 的关系

dsh 内置的 dsh-agent-instructions 已经把 ~/.dsh/AGENTS.md 注入到每个会话——但那是用户消息形式的上下文（durable context），不是系统提示词；dsh-global-rules 正是那个文件的可视化编辑器。本插件是另一条通道：

| | ~/.dsh/AGENTS.md（内置 + dsh-global-rules） | 本插件 |
| 注入形式 | 用户消息（runtime context） | 系统提示词段落 |
| 位置 | 首批请求前的 durable 消息 | order -900，紧跟身份行 |
| 生效时机 | 新会话立即；当前会话要等文件操作后的重投影 | 下一个 step（不用重启，也不用等文件操作） |
| 与压缩/历史 | 参与消息历史的协调 | 每步重新渲染，不受历史压缩影响 |
| 编辑界面 | 「全局规则」 | 「全局提示词」 |
| 告诉模型文件在哪 | 只说「存在 AGENTS.md」，不给路径 | 直接写出绝对路径（announcePaths） |

两者可以并存互不冲突（段落名不同）。只用其中一个也完全可以。
项目里的 AGENTS.md 是第三条通道，也是唯一跨工具的那条：它是 dsh-agent-instructions 的工作区指令来源（从项目根一路读到 cwd，AGENTS.md / CLAUDE.md 都认），别的 AI 工具也按同一套约定读它。本插件的 syncProjectAgents 把提示词写进这个文件的一个托管区块里——于是在 dsh 里这段规则会出现两次（系统提示词 + 工作区指令），在别的工具里也照样生效。

为什么需要「告诉模型文件在哪」：dsh 注入的那句运行时提示是 A user-global instruction file exists: AGENTS.md. Do NOT assume their content.——名字有了、路径没给。模型于是会去猜 ~/AGENTS.md、.agents/AGENTS.md、工作区根……
找不到就乱读一通。本插件的 announcePaths 把那两个真实路径直接摆进系统提示词。

实现

dsh-global-system-prompt/
├── package.json # dsh.bundle.patch + dsh.client(web)
├── cordis.patch.yml # 插入 global-prompt 行 ├── lib/ │ ├── index.js # Cordis 插件：注册 system prompt 段落 + 挂 webServer 路由 + 接会话生命周期 │ ├── config.js # 配置校验/归一化，harness home 解析 │ ├── prompt.js # 文件读取（mtime 缓存、限额截断）、{{ 中和、原子写入 │ ├── project.js # 项目 AGENTS.md：找项目根、托管区块增删改、每步复查 │ ├── route.js # GET/POST /global-prompt（同源校验、体积上限） │ └── client.js # 浏览器侧 __ModuleLoader__ bundle（无构建步骤） ├── dev/ │ └── e2e-installed.mjs # 对着已安装的 dsh 跑端到端校验 ├── test/ # node --test └── examples/

要点：

- 段落注册：ctx.systemPrompt.section({ name: 'user:global-prompt', order, text })，text 是函数，每次 assemble 时求值——这是「改完即生效」的实现方式。段落名必须唯一：deployment:persona-prefix 由提示词注册表自己占用，重名会直接抛错。
- 可选依赖：插件顶层只声明 inject = ['systemPrompt']；webServer 用 ctx.inject(['webServer'], …) 等——如果声明在顶层，没有 Web 服务器的 profile 会让整个插件停在 pending，提示词就永远不注入了。会话生命周期（agent/session-start、agent/pre-step）是事件不是服务，ctx.on 直接接，不需要 inject。
- 失败不炸回合：读文件失败只记一条 warning 并退回落兜底文本，绝不从 text() 抛错；project.js 同理，任何异常都吞成 warning + 一条状态记录。
- 文件位置说明：prompt.js 的 pathsNote() 生成那段 footer，两个文件各读一次 stat（同样带 mtime 缓存），所以「已存在 / 尚未创建」是实时状态。
- 项目同步的时机：agent/session-start 是 harness 保证在首次组装提示词之前发出的同步通知（agent.session.header.cwd 此时已就绪），所以第一个 step 就能读到写好的 AGENTS.md；agent/pre-step 是 waterfall，插件 await next() 之后才复查，绝不改动 PreStepDecision。稳态下每次复查只做一次 statSync（记住「我写的区块 + 文件当时的 mtime/size」），不匹配才读文件。
- 只在标记之间动手：upsertManagedBlock 认标记不认位置，能在文件任意位置替换、把重复区块收敛成一个、保留 CRLF 与 BOM；标记只剩一半（被手改坏）时拒绝写入并 warning，宁可不同步也不吃用户的内容。
- 面板路由：GET /global-prompt 返回文件内容、两个文件的路径与状态、本回合实际注入的原文、以及项目同步状态与要写入的区块原文（面板据此预览），POST 校验同源后原子写入（临时文件 + rename）。

开发 powershell cd
node --test test/ # 111 个用例
node --check lib/client.js # client bundle 语法检查（未构建，手写 __ModuleLoader__ 工厂）

改完源码后重新装一次即可让 profile 用上新代码： powershell
dsh plugin --profile web add file:

或者用 link: 装一份链接，改完直接重启 dsh： powershell
dsh plugin --profile web add link:

改包名 / 发到自己的 scope

包名散落在四个有加载语义的地方（package.json、cordis.patch.yml 的行 name、lib/client.js 的 __ModuleLoader__.load({ id })、日志与报错前缀），漏改其中任何一个都不会立刻报错但会静默失效。用带改名工具一次改完： powershell
node dev/rename-package.mjs # 看当前名字都被哪些文件携带
node dev/rename-package.mjs @你的用户名/dsh-global-system-prompt # 改（先 --dry-run 预览）
node --test test/ # 改完自测

工具只替换「完整包名」这个 token，不会动 Cordis 插件名（global-prompt）和段落名（user:global-prompt）——这两者是运行时身份，与包名无关。

发布：

npm login # 需要你自己的 npm 凭证
npm publish # publishConfig.access 已设为 public（scoped 包必须）

prepublishOnly 会先跑一遍测试，测不过发不出去。

已知限制

- 只在 dsh 0.1.5 系列验证过；段落插值规则、settings.section 槽位契约、agent/session-start / agent/pre-step 的载荷若在未来版本变化，需要跟着改。
- 面板是全局一段，没有 cc-switch 那种「按 provider 分别配置」的多档位；需要多份就装多份（改 file 与 order）或直接用行配置切。
- 注入的是提示词文本，不做权限/沙箱方面的任何事。
- syncProjectAgents 会真的改你的工作区：会在项目里新建/修改 AGENTS.md（git diff 里会看到它），这是它的目的。不想要就 syncProjectAgents: false，或在 projectAgentsFallback: 'skip' 下让没有 .git 的目录被跳过。
- 项目同步以会话工作目录为准：一个进程里不同会话开着不同项目，就各写各的；cwd 变化的会话（理论上没有）不会重挑项目根。
- 面板上的项目同步状态是进程内的：重启 dsh 后列表从空开始，文件里的区块不受影响。