# Agent Guide — dsh-graphics

给在 `dsh-graphics` 这个包上工作的 agent 的硬规则。这不是建议。

---

## 0. 这个包是什么

一个 **DSH profile bundle**：`package.json` 的 `dsh.bundle.patch` 指向 `cordis.patch.yml`，
profile 把它当补丁层加载。它同时提供：

- **宿主侧插件**（`lib/index.mjs`）——注册 Agent 工具、伺服前端静态资源；
- **浏览器侧插件**（`lib/client.js`）——在 DSH Web 里渲染 Excalidraw 编辑面板。

安装动作由 DSH 的 `plugin_manager` 完成（写 profile 的 `package.json` + `bundles` 列表）。

---

## 1. 环境事实（live 0.2.1-rc.1，已核对）

- DSH：`/Applications/DeepSeek Harness.app`，版本 **0.2.1-rc.1**；`dsh` CLI 同为 0.2.1-rc.1。
  （`devDependencies` 里 pin 的 `@deepseek-ai/dsh-tools` 仍是 0.2.0-rc.2，只影响本地开发；
  运行时的 `defineTool` 走 peer 依赖，由宿主提供。）
- 目标 profile：`~/.dsh/profiles/desktop`，`patchReload: live` —— 补丁保存即热加载。
- 本包以 `link:` 依赖挂进该 profile；**源码改动不需要重新安装**（只有改了 `dsh.bundle.patch` 指向或包名才需要）。
- DSH 的官方包（`@deepseek-ai/*`）在 `app.asar` 归档里，**不是**普通目录，`ls`/`cat`/ripgrep 都打不开。
  需要读实现时用 `.scratch` 之外的独立解析脚本，或直接读 npm 上同版本的发布包（含 `.d.ts`）。
- 官方插件开发指南在 `app.asar` 内：
  `dsh/node_modules/@deepseek-ai/dsh-agent-preset/skills/cordis-plugin-development/`。

---

## 2. 硬规则

1. **绝不修改 App 包内的文件**（`/Applications/DeepSeek Harness.app/...`，含 `app.asar` 里的 `@deepseek-ai/*`）。
   会破坏签名、更新即丢。所有能力都从本包的补丁行与插件代码实现。
2. **绝不手写 profile 的 `package.json` / `cordis.patch.yml`，不在 `$DSH_HOME` 下建包，不在 profile 目录跑 pnpm。**
   用 `plugin_manager` 的 `install_bundle` / `remove_bundle`。
3. **文件访问一律走 `ctx.fs`，不用 node 的 `fs`。**
   `ctx.fs` 由 `fs-sandbox` 后端提供时会强制工作区边界；绕过它等于绕过 DSH 的沙箱，是安全事故。
   注意该 seam **没有删除 / 重命名 / 复制原语**——需要这类能力时重新设计，不要退回 node `fs`。
4. **模型可见的一切要有证据。** 任何"注入了什么 / 渲染成什么样 / 模型能不能看见"的判断，
   都要有真实产物（会话日志里的 `tool/result` 事件、真实 PNG/SVG 文件、`cordis_inspect_query` 输出），
   不许只读代码就下结论。
5. **客户端 bundle 必须满足格式约束**（见 `docs/design.md`）：
   `window.__ModuleLoader__.load({ id: '<包名>', factory })`、产物路径 `lib/client.js`、
   `exports["./client"]` 必须显式声明、React 从浏览器模块表 `require('react')` 取、**不要 require 任何 `@deepseek-ai/dsh-client-*` 包**。
6. **不新增架构层。** 宿主侧放 `lib/`，浏览器侧放 `lib/client.js`，前端静态资源放 `editor/`，
   补丁放 `cordis.patch.yml`。不要引入额外的服务层或自造 manifest。
7. **渲染必须确定性。** 同样的 scene 渲染两次要得到字节级相同的输出（渲染图是给模型当证据的）。
   不要用 `loadSystemFonts: true`。

---

## 3. 命令

```sh
# 安装 / 重装 / 卸载（profile 级，需要审批）
plugin_manager install_bundle  target=/Users/juergenie/Projects/Workspaces/dsh-graphics
plugin_manager remove_bundle   target=dsh-graphics

# 查看已装载的插件行（不需要审批）
cordis_inspect_query  platform=host  provider=Service  method=...

# 查看客户端 slot 树（需要页面连着）
cordis_inspect_query  platform=client  provider=Slots  method=listSubTree
```

---

## 4. 验收口径

| 能力 | 怎么证明它真的成立 |
|---|---|
| 工具注册成功 | `cordis_inspect_query` 能查到该工具行；或会话日志 `request/header` 的 `data.header.tools[]` 里出现工具名 |
| 模型能"看见"图 | 会话日志里该次 `tool/result` 事件的 `message.content` 含 `{type:'image', attachment:{attachmentId:'sha256:...'}}`，且 `attachmentId` 在 `~/.dsh/attachments/` 下能找到对应文件 |
| 导出正确 | 真实生成 SVG/PNG 文件，校验尺寸与像素（不能只看文件存在） |
| 渲染确定性 | 同一 scene 连续渲染两次，SHA-256 相同 |
| 面板可用 | 页面里 Excalidraw 真的加载、能改、能保存回原文件；控制台无 slot entry crash |

细节见 `docs/plan.md` 的验收表。