# 用户手册 (user-guide.md)

## 打开工作室

侧边栏底部（设置按钮旁）出现 🧩 **插件工作室**。点击后全屏面板打开，含 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`，读取时自动归一化并合并精选库。
6. **测试**：填 JSON payload（按参数名），单次执行监听函数体看返回值/错误。
7. **被动监控**：触发器包或任意监听场景——设定秒数开始监控，窗口内事件（bus + DSH 真实事件）
   实时列出，用于验证"触发器是否被正确触发"。
8. **推送为插件**：整个包进入"插件管理·动态插件"（监听包→监听插件，触发器包→触发器插件），
   可在那里启动/停止/组合/移除。

所有编辑即时持久化（`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/`