📝 docs: 补上提交信息规范的自查脚本

scripts/check-commit-log.mjs 按 CONTRIBUTING.md 的类型表检查提交首行，只报告不拦提交。它从规范文件里读 emoji 对照，所以改表不用改脚本。同时收紧规范：emoji 由「可选」改为「必需且必须与类型一致」。原先的写法下 ✨ docs: 这类不匹配不会被发现。
✨ docs: 把提交信息规范固化成 CONTRIBUTING.md
2026-09-30 16:50:29 +08:00 · 2026-09-30 16:49:22 +08:00
4 changed files with 199 additions and 0 deletions
@@ -0,0 +1,10 @@
+# <emoji> <type>[(scope)][!]: <中文描述，不超过 72 宽度，不加句号>
+# 类型与 emoji：feat ✨ / fix 🐛 / docs 📝 / refactor ♻️ / perf ⚡️ /
+#              test ✅ / build 📦️ / ci 💚 / chore 🔧 / revert ⏪️
+# 例：✨ feat(client): 会话行悬停区加删除按钮
+# 例：🐛 fix(host): 延迟删除台账只记录根会话
+#
+# ↓ 正文（可省略）：为什么这么改、影响面、迁移注意事项，每行不超过 72 宽度
+#
+#
+# ↓ 脚注（可省略）：Refs: #12 / Closes: #34 / BREAKING CHANGE: <中文说明>
@@ -0,0 +1,105 @@
+# 提交信息规范
+
+本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域、脚注关键字保持英文。
+
+## 格式
+
+```text
+<emoji> <type>[(scope)][!]: <描述>
+<空行>
+[正文：为什么这么改、影响面、迁移注意事项]
+<空行>
+[脚注：Refs: #12 / Closes: #34 / BREAKING CHANGE: ...]
+```
+
+- `<emoji>`：下面表格里该类型对应的 emoji，后面跟**一个空格**。emoji 是必需的，且必须与本行类型一致——`📝 docs:` 对，`✨ docs:` 不对。
+- `<type>`：小写英文关键字，见下表。
+- `(scope)`：可选，改动范围。用 `()` 包住一个简短英文标识，例如 `docs(ci)`、`fix(client)`、`feat(host)`。
+- `!`：可选，紧跟在 type 或 scope 之后、冒号之前，表示破坏性变更。
+- `<描述>`：中文，一句话，讲清这次改动做了什么。**首行不超过 72 个字符**（中文字符按 2 个宽度算），结尾不加句号。
+- 正文：中文，每行不超过 72 个宽度。说清"为什么"，不要复述 diff。单行描述足以讲明白时就省略。
+- 脚注：破坏性变更必须写 `BREAKING CHANGE: <中文说明>`，不能只靠 `!`。
+
+## 类型与 emoji
+
+| 类型 | emoji | 码位 | 用途 |
+| --- | --- | --- | --- |
+| `feat` | ✨ | `U+2728` | 新增功能 |
+| `fix` | 🐛 | `U+1F41B` | 修复缺陷 |
+| `docs` | 📝 | `U+1F4DD` | 只改文档 |
+| `refactor` | ♻️ | `U+267B U+FE0F` | 重构，行为不变 |
+| `perf` | ⚡️ | `U+26A1 U+FE0F` | 性能优化 |
+| `test` | ✅ | `U+2705` | 变更测试 |
+| `build` | 📦️ | `U+1F4E6 U+FE0F` | 构建系统或依赖 |
+| `ci` | 💚 | `U+1F49A` | CI 配置 |
+| `chore` | 🔧 | `U+1F527` | 杂项，以上都不属于时用 |
+| `revert` | ⏪️ | `U+23EA U+FE0F` | 回滚某次提交，正文写 `Refs: <被回滚的提交>` |
+
+**复制上表里的 emoji，不要手敲。** 带 `U+FE0F` 的那五个是「基础字符 + 变体选择符」两个码位，手敲时很容易只打出前一个字符；对工具来说 `♻`（`U+267B`）和 `♻️`（`U+267B U+FE0F`）是两个不同的字符串，比对会失败。写规范或写脚本时，比较 emoji 前先做一次 NFC 归一化，或把两边都按 `\uFE0F?` 处理。
+
+## 示例
+
+新增功能：
+
+```text
+✨ feat(client): 会话行悬停区加删除按钮
+
+官方 archive 与 pin 两个悬停按钮保持原位，本插件的删除按钮插在两者
+之间，不再借用 archive 的 id 压级替换。
+```
+
+修复缺陷：
+
+```text
+🐛 fix(host): 延迟删除台账只记录根会话
+
+台账原先记录整棵树，但启动清扫以根为单位整棵删除，导致子会话被重复
+删除并重复广播 api-session/removed。
+```
+
+破坏性变更：
+
+```text
+♻️ refactor!: 行内按钮改用自己的槽位 id
+
+BREAKING CHANGE: 悬停区布局变化，官方归档按钮回到原来的位置。按住旧
+结构写样式的用户需要调整。
+```
+
+纯文档：
+
+```text
+📝 docs: 安装说明改为只走 Git 标签与本地 tgz
+```
+
+## 工具链提示
+
+emoji 在行首是本仓库的有意选择，视觉上整齐。代价是：以类型前缀开头的解析工具（`commitlint`、`semantic-release`、`release-please` 等）会读不到类型。如果以后要接这类工具，有两条路：
+
+1. 把 emoji 挪到冒号之后（`feat: ✨ 描述`），类型回到行首，规范其余部分不变；
+2. 保留行首 emoji，给工具写一个剥掉开头 emoji 与空格的预处理。可用的正则（`\p{Extended_Pictographic}` 已覆盖带与不带变体选择符两种写法）：
+
+   ```text
+   ^(?:\p{Extended_Pictographic}\uFE0F?\s+)?(?<type>[a-z]+)(?:\((?<scope>[^)]*)\))?(?<breaking>!)?:\s(?<desc>.+)$
+   ```
+
+## 自查
+
+`scripts/check-commit-log.mjs` 会按本规范检查现有提交的首行，只报告、不拦提交：
+
+```bash
+node scripts/check-commit-log.mjs        # 最近 10 条
+node scripts/check-commit-log.mjs all    # 全部
+```
+
+它从本文件的类型表里读 emoji 对照表，所以改了表不用改脚本。规范之前的提交不符合是正常的。
+
+## 启用提交模板（可选）
+
+`.gitmessage` 是提交信息模板。启用后每次 `git commit` 会带上前缀提示，删掉不需要的部分即可：
+
+```bash
+git config commit.template .gitmessage
+```
+
+模板里以 `#` 开头的行会被 git 自动丢弃，不会进入提交信息。只对当前仓库生效；换机器要重新执行一次。
@@ -76,6 +76,8 @@ https://gitea.iwake.top/dsh-plugin/session-delete.git#v2.0.0

 DSH 暂不支持插件自动更新，升级就是用新标签重装一次（建议先移除旧版本）。安装或升级后：**宿主半变更需要重启 DSH**（完全退出再打开，仅关闭窗口不一定退出进程）；只改浏览器半时刷新页面即可。

+如果你是在本地开发这个插件（profile 里装的是 `link:` 到工作目录），**光刷新页面看不到改动**：profile 的 `node_modules` 里可能是一份与源码同 inode 的硬链接副本，需要移除再重装一次插件，让 profile 重新取一份。
+
 ## 兼容性

 基于 **DeepSeek Harness 0.2.0-rc.2** 编写。DSH 仍在演进，其它版本与平台组合未逐一验证。
@@ -84,6 +86,14 @@ DSH 暂不支持插件自动更新，升级就是用新标签重装一次（建
 - **宿主半**只依赖稳定的服务契约：`sessionQuery`（`traceSession` 取血缘、`listSessions` 取语料）、`sessionPersistence`（含其 JSONL 后端的 `locate()` 诊断钩子，用于定位会话目录）、`workspaceRegistry`、`connection.fetch`（注册受认证的 exact 路由），以及 spill 后端的目录规则。
 - **跨半边通信**走 `connection.fetch` 注册的 `POST /api/plugin/session-delete/delete` 与 `.../orphans` 两条路由，浏览器半用文档相对路径请求（支持挂载前缀）。这是静态客户端包与宿主半通信的正规通道；`host.call` 属于动态客户端运行器，不适用于包形式的插件。

+## 贡献
+
+提交信息用「emoji + Conventional Commits + 中文描述」，规则、类型表和示例见 [CONTRIBUTING.md](CONTRIBUTING.md)。想省事可以让 git 带上模板：
+
+```bash
+git config commit.template .gitmessage
+```
+
 ## License

 [MIT](LICENSE)
@@ -0,0 +1,74 @@
+// Checks real commit subjects (newest first) against the CONTRIBUTING.md spec:
+// the documented regex must parse them, the leading emoji must be present and
+// match the type table exactly, and the subject must stay within 72 width.
+//
+// This is a reporting tool, not a hook: it never blocks a commit.
+//
+// Usage:
+//   node scripts/check-commit-log.mjs          # newest 10 commits
+//   node scripts/check-commit-log.mjs 50       # newest 50 commits
+//   node scripts/check-commit-log.mjs all      # every commit
+//   DSD_SPEC=path/to/CONTRIBUTING.md node scripts/check-commit-log.mjs
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const specPath = process.env.DSD_SPEC ?? resolve(repoRoot, 'CONTRIBUTING.md')
+const doc = readFileSync(specPath, 'utf8')
+const count = process.argv[2] ?? '10'
+
+/** The regex the spec documents for stripping a leading emoji. */
+const SUBJECT = new RegExp(
+  '^(?:\\p{Extended_Pictographic}\\uFE0F?\\s+)?' +
+  '(?<type>[a-z]+)' +
+  '(?:\\((?<scope>[^)]*)\\))?' +
+  '(?<breaking>!)?' +
+  ':\\s(?<desc>.+)$',
+  'u',
+)
+
+// The spec's table is the single source of truth for the type → emoji mapping,
+// so a table edit cannot drift from what this script checks.
+const emojiOfType = new Map()
+for (const row of doc.split('\n').filter((line) => /^\| `[a-z]+` \| /.test(line))) {
+  const cells = row.split('|').map((cell) => cell.trim())
+  emojiOfType.set(cells[1].replaceAll('`', ''), cells[2])
+}
+if (emojiOfType.size === 0) throw new Error(`${specPath} has no type table to read`)
+
+/** Strip the variation selector, so '♻' and '♻️' compare equal. */
+const base = (text) => text.replace(/\uFE0F/g, '')
+/** Display width, counting anything above U+2000 as double. */
+const widthOf = (text) => [...text].reduce((n, c) => n + (c.codePointAt(0) > 0x2000 ? 2 : 1), 0)
+
+const args = count === 'all' ? ['log', '--format=%h%x09%s'] : ['log', `-${Number(count)}`, '--format=%h%x09%s']
+const rows = execFileSync('git', args, { encoding: 'utf8', cwd: repoRoot })
+  .trim().split('\n').filter((line) => line !== '')
+
+let problems = 0
+for (const row of rows) {
+  const [hash, subject] = row.split('\t')
+  const notes = []
+  const match = SUBJECT.exec(subject)
+  if (match === null) {
+    notes.push('缺少类型前缀，或整体格式不是 <emoji> <type>[(scope)][!]: <描述>')
+  } else {
+    const expected = emojiOfType.get(match.groups.type)
+    const lead = [...subject][0]
+    if (expected === undefined) notes.push(`类型不在规范表里：${match.groups.type}`)
+    else if (base(lead) !== base(expected)) notes.push(`类型 ${match.groups.type} 的 emoji 应为 ${expected}，实际是 ${lead}`)
+    const width = widthOf(subject)
+    if (width > 72) notes.push(`首行宽度 ${width}，超过 72`)
+    if (/[。.]$/.test(subject)) notes.push('首行结尾不应有句号')
+  }
+  if (notes.length > 0) problems += 1
+  const mark = notes.length === 0 ? 'ok  ' : 'FAIL'
+  console.log(`  ${mark} ${hash} ${notes.length === 0 ? '' : notes.join('；') + ' — '}${subject}`)
+}
+
+console.log(problems === 0
+  ? `\n检查了 ${rows.length} 条提交，全部符合规范`
+  : `\n检查了 ${rows.length} 条提交，其中 ${problems} 条不符合规范（规范文件：${specPath}）`)
+process.exit(problems === 0 ? 0 : 1)