dsh-project-prompt
English | 中文
DeepSeek Harness（DSH）的私有项目级提示词插件。
有些指引属于你的机器，而不属于仓库：与环境绑定的端到端测试方法、仅内网可达的入口、个人工作流偏好。AGENTS.md 是要提交共享的，放这些内容不合适。本插件把这类文本放在 $DSH_HOME，绝不进仓库，并在工作区命中规则的每个会话中注入——包括所有子代理和该仓库的任意 git worktree。
flowchart LR
subgraph repo["git 仓库（任意 clone / worktree / 子目录）"]
wt1["主检出"]
wt2["linked worktree A"]
wt3["worktree B"]
end
cfg["$DSH_HOME/cordis.patch.yml\nrules（机器本地，私有）"]
plugin["dsh-project-prompt\nagent 生命周期监听器"]
sp["会话系统提示词\n（或首条注入消息）"]
cfg --> plugin
wt1 & wt2 & wt3 -->|按 remote / repo / path 匹配| plugin
plugin -->|section / inject| sp
特性
- 三种匹配键 —— 按 git
remoteURL（任意位置的 clone 都命中）、本地主仓库路径、或 cwd 前缀匹配；同一规则内多键为「或」关系。 - 感知 worktree —— linked worktree 经
.git文件的gitdir:指针回溯主仓库，规则写一次，之后新建的 worktree 及其子目录全部命中。 - 两种注入模式 ——
section（稳定的系统提示词段，KV cache 友好，支持{{cwd}}/{{model}}）与inject（首条上下文消息，不做模板插值——文本含字面量{{...}}花括号（如 Helm/Go 模板）时使用）。 - 覆盖子代理 —— 子代理继承会话 cwd，委派出去的工作同样遵守规则。
- 加载期快速失败 —— 规则写错（缺
text、section 模式出现未知{{var}}）在插件加载时抛错，而不是每个请求都炸。 - 零依赖 —— 单个 ESM 文件，只 import Node 内置模块；无构建、无产物。
环境要求
- DeepSeek Harness ≥
0.1.1-rc.2（已在0.1.5-rc.2与0.1.7-rc.1上验证）。依赖 agent 生命周期边：0.1.5 及以前是agent/session-start，0.1.7 起是agent/created；另用systemPrompt.section与agent.inject。 - Node.js ≥ 18（DSH 本身当前要求 ≥ 22）。
安装
用 DSH 的插件命令安装到某个 profile：
dsh plugin --profile web add dsh-project-prompt
# 或直接从 GitHub 仓库安装：
dsh plugin --profile web add github:imroc/dsh-project-prompt
安装后重启 DSH —— bundle 在启动时参与组合。
卸载：
dsh plugin --profile web remove dsh-project-prompt
配置
规则写在 $DSH_HOME/cordis.patch.yml（默认 ~/.dsh/cordis.patch.yml）——机器本地层，对本机所有 profile 生效。覆盖 bundle 安装的行：
- id: project-prompt
config:
rules:
# 该仓库不管 clone 到哪、开多少 worktree 都命中
- remote: github.com/my-org/my-project
text: |
## 本项目 E2E 测试方法（环境相关，私有）
1. 测试环境入口：http://e2e.internal.example.net（仅内网可达）
2. 首次跑 E2E 前先执行 `make e2e-prepare`。
3. 用例失败时优先排查 ……
# 按本地主仓库路径匹配；文本含字面量 {{...}} 花括号，须用 inject 模式
- repo: /home/me/dev/another-project
mode: inject
text: |
{{ .Values.replicas }} 这类字面量在这里原样保留。
# 按目录前缀匹配
- path: /home/me/dev
text: |
...
该文件受监听——保存即热重载插件行（对之后新开的会话生效）。
规则参考
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
remote |
string | — | 匹配 git remote URL（origin）。比较前做归一化：忽略协议、user@、scp 风格 : 分隔符、尾部 .git 与斜杠、大小写。[email protected]:u/r.git ≡ https://github.com/u/r。也支持 host/org/repo 后缀形式。 |
repo |
string | — | git 主仓库的本地绝对路径。其任意 linked worktree 与任意层级子目录都命中（worktree 经 .git gitdir 指针回溯）。 |
path |
string | — | cwd 前缀：会话工作区等于该目录或位于其下。 |
text |
string | 必填 | 要注入的提示词文本。 |
mode |
section | inject |
section |
注入模式，见下。 |
sectionName |
string | project-prompt（同一会话命中多条 section 规则时自动递增） |
系统提示词段名。 |
order |
number | 50 |
系统提示词段顺序（DSH 惯例：0 人设，100–199 工具指引）。 |
一条规则至少需要 remote / repo / path 三者之一；命中的多条规则全部生效。
注入模式
section（默认） |
inject |
|
|---|---|---|
| 落点 | agent 作用域 systemPrompt 服务上的系统提示词段 |
首条 user 侧上下文消息（AGENTS.md 内容走的同一条路） |
| 可见性 | 该会话每次请求 | 该会话每次请求 |
| 模板插值 | 有 —— {{cwd}}、{{model}} 会解析；其它完整的 {{...}} 组会抛错 |
无 —— 花括号按字面量保留 |
| 适用 | 稳定指引；KV cache 友好 | 含字面量 {{...}} 的文本（Helm/Go 模板、Terraform 等） |
插件在加载期校验 section 文本：未知 {{var}} 会让加载失败，错误信息会提示把该规则改为 mode: inject。
工作原理
- 每个新会话（新建、恢复、clear/compact 之后——每次 publish 都产生新的 agent 作用域）在首个模型请求之前走 agent 生命周期边：0.1.5 及以前是 emit 模式的
agent/session-start，0.1.7 起是 serial 并会被首个请求 await 的agent/created。插件两边都订阅，只做一次。 - 插件读取
agent.session.header.cwd并逐条匹配规则；git 仓库身份通过从 cwd 向上找.git得出（.git是文件说明是 linked worktree，其gitdir:指针回溯主仓库根与 remote URL）。 - 命中后，规则文本注册在
agent.ctx——agent 作用域上下文——只对该 agent 生效、随其销毁自动撤销。 - 该会话的每次模型请求都会重新组装系统提示词（或重读注入消息），规则文本全程在场。
「模型可见⟺已记录」：注入的 section 会出现在会话日志（$DSH_HOME/sessions/…）记录的请求头里，这也是验证规则是否生效的方法。
验证安装
- 确认行已组合：
dsh --profile web --dump-config | grep -A3 project-prompt。 - 在命中目录新开会话，问一个规则文本应当影响回答的问题。
- 或检查会话日志：该会话的
session.jsonl.zstd中记录了含你 section 的完整系统提示词。
限制
- 匹配依据是路径/remote 身份而非内容：同一 remote 的不同 clone 都会命中
remote规则（这通常正是目的）。 - 子模块目录（
.git指向.git/modules/…）不做回溯；请用path规则。 - 规则是静态配置——本插件刻意不从仓库内读文件（那会重新引入共享状态）。工作区内的文件请用 DSH 内建的
AGENTS.md/CLAUDE.md加载机制。
开发
git clone github:imroc/dsh-project-prompt && cd dsh-project-prompt
npm test # node --test；git fixture 在临时目录中自建
node --check index.js
插件是单个零依赖 ESM 文件；提交的源码即发布产物（无构建、无 prepare 脚本——这也是 git 安装无需 pnpm allowBuilds 的原因）。保持这一点的约束说明见 AGENTS.md。
