dsh-agent-studio

Readme

# dsh-agent-studio

**DSH 智能体与插件开发** —— 专精于构建 DeepSeek Harness **智能体（agent preset）** 与 **预设本地插件** 的开发智能体预设。

一个 DSH 智能体就是一个 agent preset：一个目录，包含 Cordis 组合文件 `agent.cordis.yml`（能力 = 插件行）、显示元数据 `preset.yml`、随行技能 `skills/` 与预设本地插件 `plugins/`。本仓库就是这个预设的完整目录——把它放入 DSH 的用户预设根即可使用。

## 目录结构

```
agent-studio/
├── agent.cordis.yml                    # 组合文件：persona + 全部工具行
├── preset.yml                          # 显示元数据（picker 里的名字与描述）
├── plugins/                            # 随预设旅行的本地插件（CJS、无 harness import）
│   ├── agent-builder-tools/index.js    #   preset_list / preset_read / preset_copy /
│   │                                   #   preset_validate / preset_validate_all /
│   │                                   #   preset_remove / preset_default / preset_files
│   │                                   #   runtime_services / runtime_tools
│   ├── plugin-scaffold/index.js        #   plugin_scaffold 插件骨架生成
│   ├── plugin-lint/index.js            #   plugin_lint   插件文件静态检查
│   ├── preset-lint/index.js            #   preset_lint   组合审查 + preset_diff 差异对比
│   ├── preset-default/index.js         #   preset_set_default / preset_clear_default
│   └── skill-scaffold/index.js         #   skill_scaffold 技能骨架生成（含必需 frontmatter）
└── skills/                             # 随行技能（SKILL.md 必须带 YAML frontmatter）
    ├── dsh-agent-development/SKILL.md
    ├── editing-cordis-compositions/SKILL.md
    └── cordis-plugin-development/SKILL.md
```

## 能力清单

在 standard 模式全部能力（文件编辑、Shell、文件/网页检索、Skills、计划、目标、子代理、工作流、Ralph）之外，本预设贡献：

| 工具 | 用途 |
| --- | --- |
| `preset_list` / `preset_read` / `preset_files` | 定位、阅读预设与它的文件树 |
| `preset_copy` | 从 standard / cordis / 任意预设复制出新的用户预设 |
| `preset_validate` / `preset_validate_all` | 真实挂载校验（standingKeyFor）：包解析、配置、行激活、realm 归属 |
| `preset_remove` / `preset_default` | 删除用户预设 / 读取默认预设与可写性 |
| `runtime_services` / `runtime_tools` | live 运行时内省：服务归属（root/isolated）与工具目录 |
| `plugin_scaffold` | 生成合规预设本地插件骨架（可选参数/output schema、inject 服务、execute 函数体） |
| `plugin_lint` | 插件文件静态检查：ESM 语法、外部 require、CJS 形状、工具注册、组合行接线 |
| `preset_lint` | 整预设审查：roster 健康、元数据、persona 行、tool-cordis 单例、重复行 id、插件双向接线、技能 frontmatter |
| `preset_diff` | 两个预设组合文件的逐行 diff（副本与源预设的漂移） |
| `preset_set_default` / `preset_clear_default` | 设置/清除默认预设（写入 settings 命名空间 `agent-presets`） |
| `skill_scaffold` | 生成带 YAML frontmatter（name/description 必填）的技能骨架 |

## 安装

把本目录（`agent-studio/`）整体复制到 DSH 的用户预设根：

```text
${DSH_HOME:-$HOME/.dsh}/.agent-presets/agent-studio/
```

- Linux/macOS：`~/.dsh/.agent-presets/agent-studio/`
- Windows：`C:\Users\<you>\.dsh\.agent-presets\agent-studio\`

然后在 DSH 中**新开会话**并选择「DSH 智能体与插件开发」预设。以 roster（`preset_list`）报告的真实路径为准；`roster.broken` 只检查文件形状，`preset_validate` 才是可用性判据。

## 典型工作流

1. `preset_list` 看现状 → `preset_copy` 复制出新的用户预设目录（绝不编辑随部署发布的预设）；
2. 编辑副本：`preset.yml` 元数据、persona、增删工具行；自定义能力用 `plugin_scaffold` 生成插件骨架，实现后用 `plugin_lint` 检查并在 `agent.cordis.yml` 接线；
3. 技能用 `skill_scaffold` 生成（必须带 frontmatter，否则被技能 provider 静默忽略）；
4. `preset_lint` 静态审查 → `preset_validate` 真实挂载校验（修复四类失败：包不解析 / 配置无效 / 行未激活 / 服务泄漏到根 realm）；
5. 校验通过后新开会话验证；`preset_set_default` 可把成品设为默认预设。

## 注意事项

- **不含 `tool-cordis`**：其检查 Provider 注册进进程级 `cordisInspect` 注册表（进程级单例），与 `cordis`/`plugin-dev` 预设共存的进程里挂载必失败。动态 Cordis 插件（Host/Client 两半）的开发请用 `plugin-dev` 预设会话。
- **平面规则**：HOST 组合持有注册表与跨会话共享设施；AGENT PRESET 只持有单会话贡献（工具、persona、提示词）。发布服务的行必须放进 `isolate` realm，只消费 host 注册表的行留在 realm 外。
- **信任边界**：本工具集可运行模型编写的 JavaScript，产出的组合会成为其他会话挂载的预设——把该预设的会话视作 shell 访问（与 `cordis` 预设相同的信任声明）。
- 本仓库派生自 DSH 部署自带的 `cordis`/`plugin-dev`/`agent-builder` 预设组合，随 DSH 版本演进可能需要同步更新；以官方文档与随部署发布的最新预设为准。