# 开发文档

面向本插件的贡献者与二次开发者。框架机制以 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 上游实现为准，本文只说明本插件用到的部分。

## 架构

插件分两半，同一 package 内两个入口：

```
dsh-media-forge/
├── src/                      # TypeScript 源码（构建产物在 lib/）
│   ├── index.ts              # Host 半：Node 侧插件入口（lib/index.js）
│   ├── store.ts              # 技能持久化（$DSH_HOME/media-forge/skills.json）
│   ├── recipe.ts             # recipe 执行器（HTTP 请求 + 媒体提取 + 落盘）
│   └── client/               # 浏览器半：侧边栏 UI（lib/client.js）
│       ├── index.ts          # 客户端入口：注册词典 + 占据 sidebar.footer.action
│       ├── MediaForgeFooterAction.tsx  # 侧边栏触发行（图标 + 标签 + 角标）
│       ├── MediaForgePanel.tsx         # 技能选择面板
│       ├── locales.ts        # zh / en 文案
│       ├── styles.ts         # 运行时注入的 <style>（用 --dsw-alias-* 设计变量）
│       ├── icons.tsx         # 内联 SVG 图标
│       └── types.ts          # settings namespace 的客户端镜像类型
├── cordis.patch.yml          # dsh.bundle 层声明（插入 media-forge 插件行）
├── tsdown.config.ts          # lib / client 双产物构建
├── test/smoke.mjs            # 冒烟测试（mock ctx + 本地 HTTP 服务）
└── package.json              # dsh.bundle + dsh.client manifest
```

### 数据流

```
用户发 API Key 给 Agent
  └─ Agent 调研 + 实测（自带工具）
       └─ media_forge_save_skill(name, description, content, recipe?)
            ├─ store.ts → skills.json 落盘
            ├─ ctx.skills.register() → 注册为运行时 agent skill
            └─ settings.update({ knownSkills }) → 镜像到 settings 供 UI 读取

侧边栏面板（client）
  ├─ settingsScope.bind({ namespace: 'media-forge' }) 读 knownSkills / selectedSkills
  └─ 勾选 → scope.set('selectedSkills', [...])

下一条消息发出
  └─ Host 监听 agent/pre-step
       ├─ 读取 selectedSkills，渲染技能正文
       ├─ digest（名称+内容哈希）去重：内容没变不重复注入
       └─ 以 media-forge-selection 来源的 user message 注入会话

Agent 生成
  └─ media_forge_generate_media(skill, prompt, extraBody?, outputPath?)
       └─ recipe.ts：占位符替换 → fetch → url/base64/binary 提取 → 写文件
```

### 关键设计决策

- **技能目录走 settings 镜像而非 RPC**：DSH 的浏览器 RPC 面只暴露既有端点（如 `skill.list`），第三方不能新增 per-session RPC。因此 Host 把 `{ name, description }[]` 镜像进 `media-forge` settings namespace，客户端通过 `ctx.settingsScope.bind()` 订阅——天然跨会话持久、增量同步，且无需自建通信。
- **注入用 `agent/pre-step` + digest 去重**：每个选中状态计算一个 sha256 digest（技能名 + 内容哈希）。会话里最新一条可见的 `media-forge-selection` 消息 digest 相同就跳过注入，因此「改选择」「改技能」会刷新注入，而恢复会话不会重复注入。
- **skill 正文与 recipe 分离**：`content` 是给模型读的 markdown（含提示词模板），`recipe` 是机器可读的请求配方。只有支持「一次 HTTP 请求直接拿媒体」的 API 需要 recipe；轮询 / 多步骤上传类 API 可以只写 content，Agent 按说明自行调用。
- **API Key 明文本地存储**：写入 `skills.json` 与技能正文（模型需要读它来发请求）。这是功能取舍，UI 底部常驻灰色警示，文档同步说明。
- **客户端样式走 `--dsw-alias-*` 设计变量**：DSH 的设计平台变量随 `body[data-ds-dark-theme]` 自动切换明暗，面板配色零成本跟随应用主题；变量缺失时回退到内置默认色。

### 客户端 bundle 约定

DSH 的 Web 端是懒加载 CJS 模块表：浏览器执行 `lib/client.js` 只注册工厂 `window.__ModuleLoader__.load({ id, factory })`；React、Cordis 等基线模块通过注入的 `require` 解析（见 `tsdown.config.ts` 的 `external` 与 banner/footer 包装）。因此：

- 客户端代码对其他插件包只能做 **type-only import**（擦除后不产生 require），跨插件协走 cordis 服务（`ctx.settingsScope` 等）；
- 不用 CSS 文件 / CSS Modules，样式在首次渲染时注入 `<style>`（`styles.ts`），保证单文件 bundle 自包含；
- `package.json` 的 `dsh.client.inject` 声明服务提供方（runtime / locale / ui-settings），供模块图排序。

## 构建与测试

```sh
pnpm install          # 安装依赖
pnpm build            # tsc 产出 lib/types → tsdown 打 lib/index.js + lib/client.js
pnpm test             # 构建 + 冒烟测试
```

冒烟测试（`test/smoke.mjs`）用 mock cordis context 驱动真实构建产物：注册 4 个工具、保存/列出/删除技能、通过本地 HTTP 服务验证 recipe 执行（URL 与 base64 两种响应、占位符替换、鉴权头透传、产物落盘）、store 持久化格式、以及 pre-step 注入与 digest 去重。

类型检查：

```sh
npx tsc -p tsconfig.json --noEmit
```

## 本地调试

开发期用 `--patch` overlay 直接从源码目录加载（无需安装进 profile）：

```sh
pnpm build
dsh web --patch ./dsh-media-forge/cordis.patch.yml
```

注意 patch 中插件行按包名解析（`name: dsh-media-forge`），需在 DSH 能解析到的位置（如 profile 依赖或 pnpm link）。浏览器端可配合上游 `dsh-client-hmr` 的 invalidate 机制重载 bundle。

日志：Host 侧异常会经 cordis fiber 上抛；`loadStore` 对损坏的 skills.json 只警告不崩溃。

## 扩展点

- **新响应类型**：在 `src/store.ts` 的 `readRecipe` / `src/index.ts` 的 `RESPONSE_TYPES` 与 `src/recipe.ts` 的提取分支三处同步扩展（如轮询任务 ID）。
- **面板新增操作**（如删除按钮、技能详情）：`MediaForgePanel.tsx` 加 UI，操作走对话引导（提示用户让 Agent 调用对应工具）或参考上游 settings 卡片模式通过 `settingsScope` 写状态；本插件刻意不做「客户端直连 Host 工具」的私有 RPC。
- **多语言**：`src/client/locales.ts` 增加字典并同步 `MediaForgeDictionary` 接口。

## 已知限制

- 选择状态是全局的（settings 单用户层），对所有会话生效——「本次对话」语义由注入时机实现：改选择只影响下一次发出的消息，已注入的会话保持其内容。
- 远程浏览器（非 loopback）模式下 settings 只读，面板会提示「选择不会被保存」。
- `media_forge_generate_media` 依赖技能带 recipe；纯说明型技能由 Agent 按正文自行调用 API。