用户手册 (user-guide.md)

August 27, 2026 · View on GitHub

打开工作室

侧边栏底部（设置按钮旁）出现 🧩 插件工作室。点击后全屏面板打开，含 4 个页签： 事件流 · 插件一览 · 插件管理 · 插件开发，右上 × 关闭。

事件流（waterfall）

  • 默认实时滚动（400ms 刷新）；每一行 = 一次事件分发：seq、时间、模式徽标（emit/waterfall/ serial/parallel/bail/bus）、事件名（按命名空间着色）、参数摘要。
  • 点击行展开完整参数摘要（浅层安全序列化），并在摘要下方按参数给出 可展开明细： 每个 [Object] / [Function] / [Array(n)] 芯片可点击展开，看到对象的键值（含构造器名， 如 Plugin、Agent）、函数的源码（截断 1200 字符）、Map/Set/Error/Date/RegExp 等内容的 深层 dump（深度 6 层、每层 40 键/项、整体约 600 节点的安全上限）；旧事件（无 detail 字段）自动回退为纯摘要文本。
  • 工具栏：搜索（事件名/参数）、模式过滤、分类芯片（agent/tools/llm/session/workflow/…）、 实时/暂停、缓存上限（默认 500，50–10000 可调并持久化）、清空。
  • 仅内存：重启进程即清空。

插件一览

  • 事件目录：所有反射事件（含签名/说明），可搜索；带"注释"徽标的是持久化注释层补充。
  • 关系图：事件（左）↔ 插件（右）连线；studio 插件是精确监听边，系统插件显示装载状态。
  • 插件矩阵：每个 studio 插件的输入事件、类型、启停状态；系统插件的装载/状态行。

插件管理

页面为五张卡片：

  1. 快照管理：制作 / 恢复 / 改名 / 删除快照，并可把快照设为快捷启动。快照 = 捕获当前 系统+外来+动态 三类插件启停状态；恢复 = 全盘恢复（含系统插件，写回部署装载表）。快照列表与快捷启动标记持久化到 state.json。
  2. 系统插件（loader）：绿=运行中，红=未运行。可手动启停，但 boot 按部署默认配置、不手动就不碰。 启停会写回部署装载表（慎重）。
  3. 外来插件（GitHub / 本地 package）：默认关闭；注册后出现于此，可启停/移除（卸载其 loader entry）。
  4. 动态插件（工作室目录）：默认关闭；启动/停止/编辑（导入插件开发）/移除（连带清理组合引用）。
  5. 插件组合（sets · 支持嵌套）：全启=绿，全停=红，部分=黄；支持一键启停组合。

顶栏「+ 安装/注册外部插件」用于安装 GitHub 或注册本地插件包（成为外来插件）。

无状态插件开发

  1. 新建插件包（无状态子插件包，不再区分监听包 / 触发器包）。
  2. 在编辑器里写 function apply(ctx) { … } 的花括号内函数体（编辑器默认就是 apply 的内容）。 编辑器前后有只读的 apply 代码块提示（function apply(ctx) { … } + return { name, inject, apply }）， 方便看清你的代码落在哪。
  3. 编辑器内可用 ctx.on(事件, 处理器) 注册行为、ctx.get(服务) 读取服务；「推送为插件」会把无状态包 推入动态插件目录（插件管理），成为一个可启停的插件（启动时执行 apply、停止时回收其注册）。
  4. 插入分区示例：编辑器上方两级下拉——第一级选功能分区（通用 / llm / tools / agent / session / fs / settings / timer / terminal / workflow / subagent / approval / commands / credentials / goal / 事件 / 调试）， 第二级选具体示例（如「创建会话 sessions.create」「tools/pre-execute 允许/拦截/提问」「启动持久化 PTY」）。 每个示例包含两部分：① 官方手册地址（deepseek-ai/DeepSeek-Harness 的官方文档，插入时代码顶部自动带 // 官方手册: … 注释，下方也有可点击链接，常用链接指向 docs/user/develop/framework/service.md / events.md、 basic/index.md / basic/tool.md、cordis-primer.md 及参考站 reference/index.html）与 ② 典型用途 （// 用途: … + 示例代码，例如 session 演示创建 / append / fork / 投影消息）。选中即插入光标处。 模板库持久化于 ctx-templates.json，读取时自动归一化并合并精选库。
  5. 测试：填 JSON payload（按参数名），单次执行监听函数体看返回值/错误。
  6. 被动监控：触发器包或任意监听场景——设定秒数开始监控，窗口内事件（bus + DSH 真实事件） 实时列出，用于验证"触发器是否被正确触发"。
  7. 推送为插件：整个包进入"插件管理·动态插件"（监听包→监听插件，触发器包→触发器插件）， 可在那里启动/停止/组合/移除。

所有编辑即时持久化（dev-packages.json 权威副本 + dev-packages/<id>/ 本地文件镜像）。

tool 管理（tools）

  • 列出当前可用的工具：tool 与 skill 都是按 agent 域分层的注册表——内置/预设挂载的工具注册在 agent 的 scope 层，所以 studio 会遍历当前活着的 agent，取其真实 ToolRuntime（agent.ctx.get('tools')， 路由到 presets.serviceFor 兜底）后调用 schemas(agent) 并按工具名取并集；无活跃 agent 时回退到全局层。 因此 系统/内置工具（如 read/write/tool-fs 等）也会出现，每个工具显示来源（builtin 内置 / studio 自建）、 执行方式（POST https://... / 代码）、激活状态。
  • 以持久化方式创建：+ 新建工具 —— 填工具名、描述、参数 JSON Schema（顶层 type:object），选执行方式：
    • HTTP (curl / FastAPI 式)：method / URL / headers(JSON) / 请求体（整体为参数 JSON / 无 / {{key}} 模板替换）。 运行时其 execute 执行 fetch(url, { method, headers, body })。
    • 自定义代码 (async)：写 async 函数体，可访问 args（解析后的参数）与 exec（含 exec.signal）。
  • 创建后默认启用并注册进运行时（用 harness.defineTool(...) 产出定义、参数先做 DSL 归一化，避免多余 JSON-Schema 关键字导致激活失败），模型可真正调用；若仍失败工具会持久化并提示原因。
  • 可启用/停用（注册/注销）与删除。自建工具持久化于 tools.json，启动时自动重新注册。

skill 管理（skills）

  • 列出当前可用技能：同 tool，按 agent 域分层——遍历活跃 agent，用 registry.list({ scope: agent }) 取并集 （registry 先取 agent.ctx.get('skills')，再兜底 presets.serviceFor / 全局 ctx.skills）。因此 系统/内置技能（如 cordis 预设自带的 editing-cordis-compositions 等）也会出现，含来源（studio / system）。
  • 以持久化方式创建：技能名（小写 kebab-case，如 my-skill）、描述（路由用）、whenToUse、Markdown 正文 （加载后作为 <skill_content> 指令注入）。
  • 创建后注册进 studio 的 SkillProvider，从而进入 ctx.skills.list() 且可被 skill 工具加载；持久化于 skills.json，启动时自动重新登记 provider。可启用/停用/删除，点击「查看内容」看正文。

预设管理（presets · 对应“创造模式”的完整管理功能）

  • 列出所有预设：ctx.agentPresets.list()（id / trust(系统/本地) / name / description / order / broken / 是否默认）。 “创造模式”本身就是系统预设 cordis（显示名“创造模式”）。
  • 创建：+ 从现有预设创建 —— 选择来源预设（默认 standard/cordis），填新预设 id 与显示名。 底层用 agentPresets.copy(from, id, name)（唯一 authoring 写入，整体复制一个已有预设在本地用户根目录）。 这与“创造模式”的副本式创作一致：只能用已有的插件/工具/技能 + 你输入的提示词。
  • 编辑（结构化模板 · 不落盘）：点击行进入。自动把 agent.cordis.yml 解析成组合行（顶层 - id: 行 + 原样保留的 body），并能：
    • Persona 提示词：单独文本域编辑 dsh-persona.config.text（{{model}}/{{cwd}} 渲染时替换）。
    • 插件行是“删除/增加”，不是启用与否：每行一个「删除」按钮（确认后从组合移除）；对 !!js 平台条件启用的行， 删除时会带有警告提示（该平台条件失效）。底部的“可用插件”（来自 loader/catalog，即已存在的插件模块）点击即 - id: <id> + name: "@deepseek-ai/..." 追加进组合（增加）。
    • 顶部实时预览生成的 YAML。不保存到磁盘：底部「复制到剪贴板」把“preset.yml 元数据 + agent.cordis.yml 组合” 作为一份完整预设模板复制到剪贴板，供你粘贴到 ~/.dsh/.agent-presets/<id>/。未改的行保持原样（逐行透传）。
  • 因此不再需要工作区外写入/审批：模板生成不写盘，系统预设仍只读展示（但可“从现有预设创建”副本后编辑其模板）。
  • 可设为默认（写 agent-presets.default，对之后新建的会话生效）与删除（仅本地 user 预设；系统预设不可删）。
  • 仅能编辑 user 预设；系统（shipped）预设只读展示。

数据位置

  • 默认：<当前工作区>/dsh-plugin-studio-data/
  • 回退：~/.dsh/dsh-plugin-studio/