# 插件开发规范（docs/plugin-development）

本项目（dsh-tokstat）的目标形态：**TUI（Python）+ dsh 设置面板（npm 插件）**
双通道。本目录整理了把"设置面板插件"做对所需的全部官方规范与本地源码调研，
全部附来源，可追溯。

## 文档索引

| 文档 | 内容 | 何时读 |
|---|---|---|
| [01-official-extension-cookbook.md](01-official-extension-cookbook.md) | 官方 docs/extension-cookbook：工具/钩子/UI/协议驱动四类插件形态 | 决定插件形态 |
| [02-settings-panel-seam.md](02-settings-panel-seam.md) | **设置面板扩展机制调研**（本地源码实证）：`settings.section` slot 注册 API、client 插件声明、数据通道 | 实现设置面板前必读 |
| [03-make-dsh-plugin-notes.md](03-make-dsh-plugin-notes.md) | 官方 make-dsh-plugin skill 要点：形态选型、仓库布局、package.json 关键字段、client half 构建、安装验证、topics | 搭插件脚手架 |
| [04-awesome-dsh-plugins-inclusion.md](04-awesome-dsh-plugins-inclusion.md) | awesome-dsh-plugins 收录条件（README 九章节 + 最低门槛）+ 本项目符合性对照 | 发布前对照 |
| [05-repository-structure.md](05-repository-structure.md) | 目标仓库结构方案（根即插件包 + tui/ 子目录）与迁移步骤 | 结构调整 |
| [06-data-access.md](06-data-access.md) | **读取 token 消耗与性能数据的通道**（本地源码实证）：`ctx.sessionPersistence` 官方读取 API、投影缓存、折叠口径、inject/依赖清单、数据流 | 实现 Node half 数据层 |
| [07-awesome-dsh-plugins-registration.md](07-awesome-dsh-plugins-registration.md) | awesome-dsh-plugins 登记草稿：建议 PR 信息、PLUGINS.md 追加行、提交前检查 | 发布前提交登记 PR |
| [08-web-profile-setup.md](08-web-profile-setup.md) | 将 dsh-tokstat 加入 web profile 的手动/脚本步骤 | 用户要试用、加入真实 web profile |

## 一句话结论

- **设置面板插件 = "Node + 浏览器 UI" 形态**：npm 包 + Cordis entry（Node half，
  提供统计数据服务）+ `dsh.client`（client half，注册 `settings.section` slot 渲染面板）。
- 仓库布局按 make-dsh-plugin 的 **bundle 形态**（包根 = 仓库根），根目录
  `package.json` 即插件声明——这同时满足 awesome-dsh-plugins 收录的
  `package.json` + 集成入口门槛。
- Python TUI 作为 `tui/` 子目录保留，与插件包共存于同一仓库（monorepo 语义，
  但插件包是仓库根）。
- 收录与兼容性检测是两回事：收录只要求结构门槛；雷达的静态兼容性检测会在
  收录后针对 npm 插件跑（patch/seam/peerDeps/编译），需要适配 mainline。

## 来源

- deepseek-ai/deepseek-harness 官方 docs（docs/extension-cookbook.zh.md、
  docs/capability-seams.zh.md、docs/cookbook/adding-a-package.zh.md）
- vlln/plugin-registry 的 make-dsh-plugin skill（官方插件开发引导，v3.0.0）
- 本地安装的 dsh 0.1.0-rc.6 源码（`@deepseek-ai/dsh-client-ui-settings-general`、
  `@deepseek-ai/dsh-client-ui-slots` 的编译产物——设置面板 slot 机制的实证）
- AdamPlatin123/awesome-dsh-plugins（收录条件与 PR 模板）