dsh-prompt-manager

DeepSeek Harness 的提示词管理插件：把可复用的提示词模板当作一等公民管理——文件即数据、三端可用（Web GUI / 斜杠命令 / Agent 工具）、支持变量插值。

• 数据格式：每个提示词一个 Markdown 文件（<name>.prompt.md，YAML frontmatter），可以用 git 管理、用任何编辑器修改
• Web GUI：输入框工具行的「提示词库」按钮（搜索 → 填变量 → 一键填入输入框）+ 设置页的完整管理界面（新建/编辑/删除/置顶/收藏/分类过滤）
• 斜杠命令：/prompt list、/prompt search <关键词>、/prompt <名称> [变量=值 …]
• Agent 工具：模型可调用 prompt_search / prompt_get，自己找到并套用提示词模板
• 零依赖运行时：存储与索引完全基于文件系统，不引入数据库

安装

1. 安装插件包

# 进入你的 DSH profile（npx 方式安装的 harness 同理）
dsh plugin add dsh-prompt-manager
# 或者：在你的 profile 目录下
# pnpm add dsh-prompt-manager

无 pnpm 环境（或本地开发）的替代方式——junction 安装（Windows，已实测）：

# profile 的 node_modules 是一个 junction 农场，直接加一个入口即可，
# 所有 profile（web / headless / …）都能解析到：
New-Item -ItemType Junction `
  -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-prompt-manager" `
  -Target "E:\path\to\dsh-prompt-manager"

junction 指向包目录本身，因此重新构建（pnpm build）后无需重新安装即可生效。

注意：dsh plugin add 只会把声明了 dsh.bundle 的依赖纳入 bundle 层；普通插件（如本插件）安装后仍需手动执行第 2 步的 patch 挂载。

2. 挂载插件

在 $DSH_HOME/profiles/<name>/cordis.patch.yml 中加入一行（dsh plugin add 通常会自动追加）：

- insert:
    - id: prompt-manager
      name: dsh-prompt-manager

也可以只启用部分能力（无界面环境）：

- insert:
    - id: prompt-manager
      name: dsh-prompt-manager
      config:
        enableRpc: false      # 关闭 Web GUI 数据通道
        # enableTools: false  # 关闭 Agent 工具
        # enableCommands: false

3. 放入示例提示词

mkdir -p ~/.dsh/prompts
cp -r node_modules/dsh-prompt-manager/prompts/* ~/.dsh/prompts/

重启 DSH 后即可使用。

数据目录

优先级	来源	路径	说明
高	项目级	<项目根>/.dsh/prompts	项目根 = 最近的含 .git 或 .dsh 的祖先目录；随仓库共享
中	自定义	配置的 customPromptDirs	插件配置中追加的目录
低	用户级	~/.dsh/prompts（或 $DSH_HOME/prompts）	全局个人提示词库

同名提示词：优先级高的目录胜出（项目覆盖用户）。新建提示词默认写入项目目录（存在项目根时），否则写入用户目录。

文件格式

---
name: code-review            # 必填：kebab-case 唯一标识（即文件名 <name>.prompt.md）
title: 代码评审               # 可选：显示标题
description: 评审代码质量     # 可选：一句话描述
category: engineering        # 可选：分类（GUI 中可过滤）
tags: [review, quality]      # 可选：标签（小写）
variables:                   # 可选：变量声明（可带默认值与说明）
  - name: language
    description: 目标语言
    default: typescript
favorite: true               # 可选：收藏
pinned: false                # 可选：置顶
---
请评审下面的 {{language}} 代码：

{{code}}

• 正文中的 {{变量}} 会被自动识别为变量；variables 里的声明可以补充默认值与说明
• 有默认值的变量可选；没有默认值的变量在 GUI 中必须填写后才能「填入输入框」
• 未识别的 frontmatter 字段在编辑时会被原样保留

使用方式

Web GUI

1. 快速使用：输入框工具行点击「🔍 提示词库」→ 搜索/浏览 → 点击条目 → 填写变量 → 「填入输入框」。
2. 管理：设置 → 提示词库 → 新建/编辑/删除/置顶/收藏，编辑器中可直接维护分类、标签与变量声明。

斜杠命令

/prompt                              # 用法帮助
/prompt list                         # 列出提示词（置顶在前）
/prompt search 代码评审               # 关键词搜索
/prompt code-review language=go      # 渲染模板（变量=值）

Agent 工具

模型在需要时可以自己调用：

• prompt_search(query?, limit?) — 检索提示词库，返回条目元信息与所需变量
• prompt_get(name, variables?) — 加载模板、代入变量，返回渲染后的文本与缺失变量

配置

配置写在插件 entry 的 config 中（即 cordis.patch.yml 里该插件的行内配置，见上文示例）：

字段	默认值	说明
providerName	filesystem	在 ctx.prompts 上注册的提供者名称
dshHome	$DSH_HOME / ~/.dsh	DSH 配置根目录
customPromptDirs	[]	额外的提示词目录
watch	true	监听目录变化并实时刷新目录
watchUsePolling	false	使用轮询而非原生文件事件
watchStabilityThresholdMs	200	文件事件防抖窗口
maxSearchResults	10	单次 prompt_search 返回上限
maxListEntries	50	/prompt list 显示上限
collectCacheMaxEntries	128	目录缓存条目上限
enableTools / enableCommands / enableRpc	true	三个能力面的开关

开发者 API

import type { Context } from '@deepseek-ai/cordis'

// ctx.prompts 由本插件提供（declare module '@deepseek-ai/cordis' 已增强）
const summaries = await ctx.prompts.list({ cwd })
const definition = await ctx.prompts.get('code-review')
const hits = await ctx.prompts.search('评审')
await ctx.prompts.create({ name: 'new-prompt', content: '...' })
await ctx.prompts.update('new-prompt', { pinned: true })
await ctx.prompts.remove('new-prompt')

// 注册自定义提供者（例如远程提示词库）
ctx.prompts.registerProvider((control) => ({
  name: 'my-remote',
  writable: false,
  async list() { /* … */ },
  async get(candidate) { /* … */ },
}))

纯函数工具（无需 DSH 环境）：

import { renderPrompt, extractVariables, searchPrompts } from 'dsh-prompt-manager'

const { text, missing } = renderPrompt('hi {{name}}', [], { name: 'world' })

事件：prompts/change（目录或提供者变化，消费者应重新拉取目录）。

开发与构建

pnpm install
pnpm typecheck          # 服务端 + 客户端类型检查
pnpm test               # 单元 + 集成测试（临时目录，不触碰真实数据）
pnpm build              # 构建浏览器 bundle（lib/client.js）+ 编译 TypeScript

• src/ — 服务端插件（registry、文件系统提供者、工具、命令、RPC）
• src/client/ — 浏览器插件（输入框按钮 + 设置管理页）
• scripts/build-client.mjs — 将客户端打包为 DSH 要求的 window.__ModuleLoader__.load(...) 形式

架构

dsh-prompt-manager (host 插件)
├── PromptRegistry (ctx.prompts, Service 定义)
│   ├── FileSystemPromptProvider   ← 发现/解析/写入 <name>.prompt.md
│   └── (可扩展) 自定义 PromptProvider
├── prompt_search / prompt_get     ← ctx.tools（Agent 工具）
├── /prompt                        ← ctx.commands（斜杠命令）
└── /prompts RPC 通道              ← ctx.connection.rpc（Web GUI 数据面）

dsh-prompt-manager/client (浏览器插件, dsh.client)
├── conversation.input.left  — 输入框工具行「提示词库」按钮 + 悬浮面板
└── settings.section         — 设置页完整管理界面

与 @deepseek-ai/dsh-skill 的架构同构（borrowed provider + rank 合并 + 缓存 + 变更事件），额外增加了技能系统没有的写入路径（create/update/remove 路由到可写提供者）。