DSH外掛腳手架

如果用户只是问某个局部问题（例如“为什么挂载失败”），不要重跑全流程；直接读
`references/` 中对应的合同、坑或验证章节。

## 阶段 0：明确目标与能力面

先确定插件到底做什么，避免进入实现后再改形态。

必须确定：

- 插件名（规范化为小写连字符形式）
- 一句话目标
- 能力面：工具、服务、HTTP 路由、浏览器 UI、根布局、skill、MCP、静态资源等
- 目标 profile，默认 `web`

决策门：如果用户需求同时包含多种能力，先列全，再在阶段 1 决定哪些由插件承担。
未列全能力面之前，不要开始选形态。

## 阶段 1：选择插件形态

依据阶段 0 的能力面选形态：

| 能力面 | 形态 | scaffold 参数 |
|---|---|---|
| 仅 Node 工具/服务/事件处理 | pure Cordis | `--kind pure` |
| 需要组合层或随包分发多个挂载 | bundle | `--kind bundle` |
| Node half + 浏览器 client bundle | bundle-client | `--kind bundle-client` |

如果需要完全替换默认 web shell 根布局，由 AI agent 在业务实现阶段自行判断并
实现：在 client 侧注册 `ctx.slots.register({ name: 'root' })`，必要时在
`cordis.patch.yml` 中禁用默认 `ui-layout`。脚手架不提供独立参数。

同时确定：

- 分发方式：git 源、本地目录、npm
- 包管理器：pnpm（默认）或 npm

决策门：`--kind`、分发方式必须明确后，才能进入阶段 2。

## 阶段 2：生成脚手架

运行：

```bash
python3 scripts/scaffold.py <plugin-name> \
  --out <output-directory> \
  --kind <pure|bundle|bundle-client> \
  --description "Short description"
```

随后进入生成目录并验证骨架可用：

```bash
cd <output-directory>/<plugin-name>
pnpm install
pnpm run bundle
pnpm run gates
```

决策门：以上三条命令全部通过后，才允许开始写业务。

生成目录包含 `docs/plugin-plan.md`。把阶段 0、1 已确定的字段核对一遍，再把
阶段 2 的验证结果勾掉。

## 阶段 3：实现业务

严格按阶段 1 的形态实现：

- 只生成对应形态的 `src/index.ts` 和/或 `src/client/index.ts`。
- 使用 `ctx.*` 服务前，先把服务名加入 entry 的 `inject`。
- 注册工具、路由、服务或事件时用 `ctx.effect()`，并返回 cleanup disposer。
- client 侧按需注入 `slots`、`sessions`、`workspaces` 等服务；如果业务要接管
  整个 web shell 根布局，由 AI agent 判断并注册
  `ctx.slots.register({ name: 'root' })`。
- 不要手改 `lib/`；每次改 `src/` 后运行 `pnpm run bundle`。

决策门：Node half 与 client half 的业务行为必须符合阶段 0 的能力面清单；
不要在实现时临时扩大形态。

## 阶段 4：本地验证

验证顺序：

```bash
pnpm run bundle
pnpm run gates
npm pack --dry-run
```

然后做安装冒烟和浏览器验证，具体见
[references/verification.md](references/verification.md)。

如果验证失败：

- 业务错误回到阶段 3；
- 形态或 contract 错误才允许回到阶段 1。

决策门：本地构建、门禁、包内容、安装与浏览器冒烟全部通过后，才进入发布准备。

## 阶段 5：发布准备

发布前完成：

- 初始化 git 仓库并关联真实 remote。
- 把 README 中的 `<owner>` 占位 ref 替换为真实 git 源。
- UI 插件补至少一张截图。
- 确认 `lib/` 构建产物已提交。
- 设置仓库 description 和 topics。
- 再次运行 `pnpm run gates` 和 `npm pack --dry-run`。

决策门：没有通过阶段 4 之前，不得初始化发布动作或写最终 ref。

## 阶段 6：发布并最终验证

按阶段 1 决定的分发方式执行：

- git 源：`git push`，然后用目标 ref 重装。
- npm：`npm publish`，然后用包名安装。

最终验收必须从最终分发源重新安装，并重启 web，确认：

- 无 `plugin tree failed to load`
- 浏览器无 `slot entry crashed`
- 插件功能符合阶段 0 的目标

决策门：只有在最终安装验证通过后，才算全流程完成。

## References

- [contracts.md](references/contracts.md)：package、entry、client 合同。
- [gotchas.md](references/gotchas.md)：构建和打包的高频坑。
- [verification.md](references/verification.md)：安装、包内容和浏览器冒烟。