插件 README 模板
August 23, 2026 · View on GitHub
本文件是
plugins/dsh-desktop-*/README.md的固定格式模板（规范依据见 plugins/PLUGIN_STANDARDS.md §10.2）。 编写或更新插件 README 时，复制下方骨架并填写<...>占位符；不要改变章节顺序与标题层级，不存在的章节按编号保留并写「无」（保持目录稳定）。 所有文档一律使用简体中文；只写本插件的事实——不写其他插件的现状，不写规范本身（规范见 PLUGIN_STANDARDS.md）。
一、必备章节与内容要求
| 章节 | 必须包含 | 关联规范 |
|---|---|---|
| 标题 + 引言块 | 一句话定位；「框架/数据流/安全模型」等关键事实的 > 引用块 | — |
| 目录 | 全部章节锚点 | — |
| 1. 架构总览 | ASCII 图：host/client 半区、路由、服务、与官方接缝；依赖注入声明 | §1 |
| 2. 与官方 DSH 的集成方式 | 插槽/服务注册表（位置、条目 id、order、用途）；DOM 或服务依赖清单 | §4、§2.3（原 4.3） |
| 3. 宿主 API 契约 | 路由表（方法/参数/成功响应/错误码）+ 语义要点；所有功能路由（不止 config） | §6 |
| 4. 安全模型 | 会话 cwd 白名单、realpath 防逃逸、类型/大小白名单、spawn 约束、信任边界 | §6.1 |
| 5. 客户端行为契约 | 状态机、关键行为（边缘检测、防误操作、持久化语义）、交互约定 | §7 |
| 6. 解析/渲染契约（如有） | 解析算法、渲染安全（转义）、性能设计 | — |
| 7. 已知缺陷与风险 | 每条带状态标注（🟡 功能级 / 🔵 卫生级）+ 修复方向；无功能级缺陷也要写明 | — |
| 8. 已修复缺陷 | 表格：缺陷 → 修复（仅列本 README 维护周期内修过的） | — |
| 9. 加固建议 | 编号列表，与第 7 节缺陷一一对应 | — |
| 10. 维护与升级检查清单 | 复选框清单：插槽/服务签名、DOM 结构、端点路径、实测回归项（含第 2 节登记的依赖） | §4.3 |
二、写作约定
- 事实优先：每个断言都能在代码里找到出处；拿不准的语义（如官方节点流）标注"待验证"，不写死。
- 缺陷如实标注：功能级缺陷（影响用户可见行为）标 🟡，卫生级（不影响功能）标 🔵；已确认未修的要写清"修复方向"，方便后续处理。
- 不写规范：集成优先级、禁止事项等规范内容一律指向
PLUGIN_STANDARDS.md对应章节，不在插件 README 里重复。 - 登记 DOM/服务依赖：任何对官方 DOM 结构、hash 类名、官方服务方法的依赖，必须出现在第 2 节的清单中，并在第 10 节有对应检查项（规范 §4.3 硬性要求）。
- 代码引用：提具体代码时给「文件 + 大致行号或函数名」，方便对照。
- 双语：插件若含用户可见文案，README 中出现的词典键（zh/en）应成对提及。
三、模板骨架
# dsh-desktop-<name>
<一句话定位：这个插件做什么、以什么形态存在、开关在哪>
- **框架/宿主**：<消费的服务 / 提供的服务 / 有无 host 能力>
- **数据流**：<一句话：数据从哪来、经谁校验、到哪去>
- **安全模型**（如有）：<一句话：cwd 白名单等>
- **开关**：<在「功能增强」卡片（desktop.features.item）/ 无开关（公用/框架插件）>
> 质量结论：<一句话总体评价；引用规范 §4 集成级别（①官方插槽 / ②自定义插槽 / ③服务组件复用 / ④DOM 注入）>
---
## 目录
1. [架构总览](#1-架构总览)
2. [与官方 DSH 的集成方式](#2-与官方-dsh-的集成方式)
3. [宿主 API 契约](#3-宿主-api-契约)
4. [安全模型](#4-安全模型)
5. [客户端行为契约](#5-客户端行为契约)
6. [解析 / 渲染契约](#6-解析--渲染契约)
7. [已知缺陷与风险](#7-已知缺陷与风险)
8. [已修复缺陷](#8-已修复缺陷)
9. [加固建议](#9-加固建议)
10. [维护与升级检查清单](#10-维护与升级检查清单)
---
## 1. 架构总览
```
┌────────────────────────────── 桌面壳 ──────────────────────────────┐
│ host 半区（lib/index.js，<行数> 行） │
│ ├─ /api/desktop-<name>/config 开关（exact，GET/HEAD/POST） │
│ └─ <其他功能路由> │
│ client 半区（lib/client.js，<行数> 行） │
│ ├─ <插槽条目 / 服务注册> │
│ └─ <核心行为> │
└────────────────────────────────────────────────────────────────────┘
```
依赖注入声明：client `<exports.inject 列表>`；host `<inject 列表>`。
## 2. 与官方 DSH 的集成方式
| 位置 | 条目 | 说明 |
| ------------- | ----------- | ------ |
| <插槽/服务名> | <id, order> | <用途> |
### 2.1 <集成机制说明>
<插槽用法 / 服务消费 / 事件桥接等，说明为什么这样接>
### 2.2 DOM / 服务依赖清单（若有，规范 §4.3 硬性要求）
| 依赖 | 用途 | 失效后果 |
| ----------------- | ------ | ---------- |
| <选择器/服务方法> | <用途> | <失效表现> |
> 只依赖稳定属性（`data-slot` 等）；hash 类名仅作兜底并注释。升级 DSH 运行时按第 10 节清单逐条核对。
## 3. 宿主 API 契约
| 路由 | 方法 | 请求 | 成功响应 | 说明 |
| ---------------------------- | ------------- | ---------------- | ------------------------- | ------------ |
| `/api/desktop-<name>/config` | GET/HEAD/POST | POST `{enabled}` | `{enabled}` / `{ok:true}` | 通用开关约定 |
语义要点：<原子写、merge、白名单收窄、上限、错误码等>
## 4. 安全模型
<会话 cwd 白名单 / realpath 防逃逸 / 类型与大小白名单 / spawn 无 shell / 信任边界>
## 5. 客户端行为契约
<状态机表 / 关键行为 / 持久化语义 / 交互约定>
## 6. 解析 / 渲染契约
<无 —— 本插件不含解析/渲染逻辑>
## 7. 已知缺陷与风险
> 状态：🟡 功能级（已确认未修）/ 🔵 卫生级。
### 7.1 🔵 <缺陷名>
<描述 + 影响 + 修复方向>
## 8. 已修复缺陷
| 缺陷 | 修复 |
| ---------- | ---------- |
| <缺陷描述> | <修复内容> |
## 9. 加固建议
1. <与第 7 节缺陷一一对应的建议>
## 10. 维护与升级检查清单
- [ ] <插槽/服务签名未变>
- [ ] <DOM 结构依赖未变（第 2 节清单逐条）>
- [ ] <端点路径与响应格式未变>
- [ ] <实测回归项>
四、与规范文档的关系
| 文档 | 角色 |
|---|---|
plugins/PLUGIN_STANDARDS.md | 规范本身（应/不应/禁止、流程、契约）——唯一权威 |
本模板（docs/PLUGIN-README-TEMPLATE.md） | 插件 README 的固定格式 |
plugins/dsh-desktop-*/README.md | 各插件的现状、契约、缺陷、升级清单 |