dsh-prompt-studio Prompt Studio 的 DeepSeek Harness 插件分发形态。插件在对话页注册 Prompt Studio 标签页，以同一组件列表展示运行时原生提示词和用户补充，并提供编辑、原生覆盖与完整请求预览。 ## 组件模型 每个编排项使用同一结构： ts interface PromptComponent { id: string kind: 'native' | 'supplement' role: 'system' | 'user' | 'assistant' position?: 'after_system' | 'anchored' | 'tail' order: number enabled: boolean template: string origin?: string } 这些字段分别描述不同维度，不以 kind 代替角色或用途： - kind 只区分来源：native 是 Host 在运行时发现的只读组件；supplement 是用户可编排并持久化的补充组件。 - role 决定内容归宿： - system 一律注册为有序 system section，最终与原生 sections 合并到全局唯一的 system 字段；此时不得设置 position； - user、assistant 进入消息序列，必须设置 position。 - position 只描述 user/assistant 消息所处的间隙： - after_system：全局 system 字段之后、第一条原生会话消息之前； - anchored：最后一条真实用户消息之后，找不到锚点时跳过； - tail：原生消息序列末尾。 > anchored 与 tail 的区别：简单对话中最后一条消息往往就是用户输入，两者重叠；但存在工具调用流（user → tool_call → tool_result → assistant）时完全不同——anchored 插在用户输入之后、工具调用流之前，tail 插在整个序列最末尾（工具结果与助手回复之后）。需要紧贴用户问题补充指令用 anchored，需要模型读完完整上下文再看到的内容用 tail。 - order 有两种与归宿对应的含义： - system 组件的 order 是 system section 的全局混排层级，和原生 sections 一起升序排列；约定 -100 是身份区、0 是 persona、100–199 是工具区，其他负值也在 persona 之前； - user/assistant 组件的 order 只在同一个 position 间隙内排序，不参与跨间隙比较。 - origin 只用于覆盖。补充组件未设置 origin 时是普通注入；设置为某个原生组件 id 时，同一个补充组件即覆盖该原生组件，不存在单独的覆盖 kind。 同一消息间隙的补充组件按 (order, 声明顺序) 排列。system sections 由 Host 依 order 与原生 sections 全局混排。 ## 内容合并 所有 system sections 最终渲染为同一个 system 字符串，补充内容以纯文本直接并入，不加任何包装标记。 user/assistant 补充先进入选定间隙。若补充组与间隙左侧或右侧的相邻原生消息 role 相同，补充内容会按先后关系合并进该原生消息的 content；若角色不同，则在该间隙创建新消息。相邻且同角色的补充也合并为一条消息。 ## 原生覆盖 覆盖仍使用有序 marker section 和 system-prompt/assemble waterfall，不依赖静态原生目录： 1. origin 指向当前组装中存在的原生组件时，waterfall 移除原始组件。 2. 覆盖组件启用时，其替换文本按自身 role 归宿：system 覆盖保留 marker 的全局 order 并进入唯一 system 字段；user/assistant 覆盖按 position 进入消息间隙。 3. 覆盖组件设为 enabled=false 时只移除原始组件，相当于关闭该原生组件。 4. origin 在本次组装中不存在时，不会凭空生成替换内容。 ## 运行时组装 配置集合由 ComponentPipeline 激活。每次设置变更先调用旧组合效果的 disposer，再把新集合施加为一个 Cordis 生成器效果；marker、覆盖映射与补充消息映射分别返回原子逆，组合逆由 ctx.effect() 按结构生成。 原生目录在运行时动态发现。插件监听 system-prompt/change 并重新执行真实 systemPrompt.assemble()；waterfall 在覆盖前捕获原生 name、text 与组装次序，在覆盖后捕获实际 system 槽序列。浏览器通过同源 GET /prompt-studio/state 读取该单值快照。 system 补充直接通过 systemPrompt.section() 参与真实组装，不进入消息计划。user/assistant 补充在会话创建时折叠为一条种子回合（turn 0），经 session/created 接缝写入会话日志：用户侧内容合并为一条带普通 user 来源的消息，助手侧内容合并为一条带插件来源的消息，位于智能体第一个真实回合之前。消息补充因此成为会话历史的一部分，随会话重建与继续保留。 ## 自动捕获注入上下文 请求发出前，插件扫描完整消息序列，自动识别所有「非对话」消息——即生产者注入的上下文（MessageSource.kind 既不是 user/model/tool，也不是本插件自己的消息）——并纳入 Prompt Studio 视野，无需预知注入者是谁。任何插件将来注入的新上下文都会自动出现，不需要为它单独加桥。 捕获按消息来源分类（form：instructions / catalog / snapshot / notice / relay / recall）。workspace-context 注入的指令（AGENTS.md 基线及其动态增量）会进一步展开为资源条目：每个文件显示路径、动作（set/replace/remove）与内容摘要，remove 之外的资源可打开编辑。编辑通过资源读写接口写回文件系统，写回带版本冲突检测——文件在捕获后被修改时会拒绝覆盖并返回冲突，避免与 workspace-context 自身的状态协调（版本缓存、reconcile、字节预算）打架。 捕获是请求级快照：仅当会话发生过模型请求时，面板中才出现捕获条目。 ## 模板变量 system 组件模板支持 {{user_input}} 引用，即当前会话最后一条真实用户输入。该值在每次组装时从 AssembleContext.agent 读取，不是保存时快照。 ## 设置 settings.yaml 中只持久化用户补充组件： yaml prompt-studio: components: - id: supplement:identity kind: supplement role: system order: -200 enabled: true template: 你是一个严谨的工程助手。 - id: supplement:message kind: supplement role: user position: tail order: 100 enabled: true template: 请先复述当前目标。 运行时原生组件不写入设置。 ## 使用 1. 打开任意对话，选择 Prompt Studio 标签页。 2. 选择 新增补充，分别编辑标识、角色、顺序、可选覆盖目标与模板；只有 user/assistant 角色显示消息间隙选择器。 3. 如需覆盖原生组件，也可在对应原生行选择 创建覆盖；生成的仍是 kind=supplement 组件，只是带有 origin。 4. 在 完整预览 中检查合并后的完整 system 内容及各消息间隙的补充内容。模型内容预览不插入 [位置 · role · id] 一类展示标签，补充内容以纯文本直接注入。 5. 选择 保存更改。设置保存后立即撤销旧组合并施加新组合。 ## 安装与启用 Prompt Studio 以**组合包（bundle）**分发：package.json 的 dsh.bundle.patch 指向 cordis.patch.yml，dsh.client 声明浏览器端注入面。安装进一个 profile： sh # 先完成构建（见下），再安装到 profile（profile 名可自取，例如 web） dsh plugin --profile web add /path/to/dsh-prompt-studio dsh --profile web --dump-config # 应能看到 "# == dsh-prompt-studio" 层 dsh web # 或 dsh --profile web dsh plugin --profile <name> add <path> 会把包链接进 profile 并把包名追加进 dsh.profile.bundles。已安装的 bundle 通过 dsh plugin --profile <name> remove dsh-prompt-studio 移除。命令行与已经运行的 Web 进程不共享内存，因此替换插件产物后需重启 dsh web 并刷新浏览器。 ## 构建 构建依赖一个已安装依赖并完成构建的 DSH 源码树： sh DSH_ROOT=/path/to/dsh node scripts/build.mjs 构建先运行 TypeScript 项目检查，再由 tsdown 生成自包含的服务端 ESM 与浏览器端 bundle，最后写入插件根目录： - index.mjs - client.js - client.js.map ## 文件 | 文件 | 作用 | |---|---| | package.json | 包名（唯一权威 id）、dsh.bundle.patch 与 dsh.client 声明 | | cordis.patch.yml | 组合层：把包名插入 profile 的 patch 列表 | | src/index.ts | 效果管线、动态目录、原生覆盖与种子回合注入 | | src/shared.ts | 二分组件模型、校验、覆盖判定与预览函数 | | src/config.ts | 仅含 components 的 settings schema | | src/client/ | 统一列表编辑器、运行时目录读取与设置保存 | | scripts/build.mjs | 类型检查和双端构建 | ## 已知前提 - 设置命名空间 prompt-studio 由插件在加载时自行注册（applies: 'live'），宿主无需任何白名单。 - /prompt-studio/* HTTP 端点注册在 webServer 服务上，仅在 Web 组合下可用；无 Web 时插件仍可正常加载，只是不提供 HTTP 端点与浏览器标签页。