repo-audit-tool 1.2.0

package/templates/categories/sandbox/CATEGORY.md

@@ -0,0 +1,31 @@
+<!-- 模板说明（用后删除）：E 类"本地实验/dogfood 沙盒"分类 delta 模板（最小集）。
+     实证：11 个 fuyao-* 仓（同构 agents/docs/package.json/src/tests、master、无 origin、生命周期短）。 -->
+
+# E 类 · 本地实验/dogfood 沙盒（最小集）
+
+> 设计原则：**生命周期短、无发布面**——只保留"跑得起来 + 记得下来"的最小结构。
+
+## 文件集（就这些，不再多）
+
+```
+<repo>/
+├── README.md          # 一句话目标 + 跑法 + 结论/收尾链接
+├── README.en.md       # 英文镜像（双语标配）
+├── AGENTS.md          # core 通用纪律 + 沙盒纪律 3 条（单源拼装）
+├── .gitignore         # 通用段（机密/编辑器）+ Node 段
+├── package.json       # 若 Node：name/description/scripts（按需，可省）
+├── agents/ docs/ src/ tests/   # 按需；无则不建
+└── HANDOFF.md         # 建议本地留（.gitignore 已忽略）
+```
+
+## 明确去掉的（相对基类，scaffold 已删）
+
+- LICENSE/CONTRIBUTING/SECURITY/CHANGELOG/PUBLISHING/DEVELOPMENT/CI workflow/hooks——**无协作、无发布**
+- 版本管理：不打 tag、不发 npm；"收尾"= README 写结论 + 会话归档
+- 分支：master 直提；无 PR、无 CI
+- 双语：README.en.md 骨架已提供（Goal/How to run/Outcome 极简镜像）
+
+## 升级出口
+
+实验转正（要发布/多人）→ 按目标分类（A/B/C/D）走 `scaffold.mjs` 全量脚手架，把本仓内容迁入——
+**不要**在本分类上打补丁凑规范。

package/templates/categories/sandbox/README.en.md

@@ -0,0 +1,24 @@
+# <宿主能力面 / 实验目标一句话>（English mirror）
+
+[中文](README.md) ｜ English is a mirror; the Chinese README is authoritative and may lag behind.
+
+<!-- 模板说明（用后删除）：沙盒仓英文镜像极简即可——三件事：Goal / How to run / Outcome。
+     与中文 README 同步更新；结论（Outcome）随实验收尾补写。 -->
+
+## Goal
+
+<What hypothesis this experiment/dogfood validates, one short paragraph.>
+
+## How to run
+
+```sh
+<minimal copy-paste command>
+```
+
+## Structure
+
+- `agents/` <说明> · `docs/` <说明> · `src/` <说明> · `tests/` <说明> (remove what's absent)
+
+## Outcome
+
+<Written at wrap-up: what was validated / conclusion / promote to a full repo via scaffold.mjs>

package/templates/categories/sandbox/README.md

@@ -0,0 +1,23 @@
+# <宿主能力面 / 实验目标一句话>
+
+[English](README.en.md) ｜ 中文为权威版本，翻译可能滞后。
+
+<!-- 模板说明（用后删除）：沙盒仓 README 就三件事——目标、跑法、收尾结论。生命周期短，不养规范面。 -->
+
+## 目标
+
+<这个实验/dogfood 要验证什么假设，一段话>
+
+## 跑法
+
+```sh
+<最小可复制命令>
+```
+
+## 结构
+
+- `agents/` <说明> · `docs/` <说明> · `src/` <说明> · `tests/` <说明>（没有的删掉）
+
+## 结论
+
+<实验收尾时写：验证了什么 / 结论 / 是否升级为正式库（升级走 scaffold.mjs 目标分类全量脚手架，不在本仓打补丁）>

package/templates/check-single-source.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * 单源漂移检查（多源收敛的常态化守卫）。
+ *
+ * 原则：AGENTS / CONTRIBUTING / .gitignore 的共性内容只允许存在于 common/*-core 一份源；
+ * 分类目录只允许 *-append.md（差异段）与 sandbox/content 的整文件例外（见下）。
+ *
+ * 检查项：
+ *   A. core 源存在且唯一
+ *   B. 任何分类目录/基类不得包含"整份重复"——以 core 特征句为指纹扫描
+ *   C. 分类 append 文件命名规范（*-append.md 或 sandbox/content 的整文件白名单）
+ *   D. 基类 repo-root 不再保留三份成文（已迁 common）
+ *
+ * 用法：node templates/check-single-source.mjs   （CI/审计均可挂）
+ * 退出码：发现多源 = 1。
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = dirname(fileURLToPath(import.meta.url));
+const COMMON = join(ROOT, 'common');
+const BASE = join(ROOT, 'repo-root');
+const CATS = join(ROOT, 'categories');
+const ENGINEERING = ['dsh-plugin', 'python-app', 'go-service']; // core+append 模式
+const MINIMAL = ['sandbox', 'content'];                          // core+append（AGENTS）/整文件白名单
+const WHITELIST_FULL = new Set(['categories/sandbox/AGENTS.md', 'categories/content/AGENTS.md']); // 历史例外（现为空集则通过）
+
+// core 指纹：这些句子只允许在 common 源出现一次；在分类/基类文件中出现 = 多源漂移
+const CORE_FINGERPRINTS = {
+  'AGENTS-core.md': ['AI 协作守则（agent 贡献者必读）', 'Conventional Commits 前缀 + 中文描述', '完成的定义 = 验证链全绿'],
+  'CONTRIBUTING-core.md': ['main 保持线性历史', '尊重、建设性、对事不对人'],
+  'gitignore-core.md': ['本机私有信息不入库（与 AGENTS.md 机密纪律同源）', 'HANDOFF-ARCHIVE/'],
+  'README-core.md': ['README = 卖点 + 5 分钟上手', 'AI 协作者先读'],
+  'DEVELOPMENT-core.md': ['小步提交、每步可验证、事实落盘', '复盘三问'],
+  'PUBLISHING-core.md': ['每版一行：**做了什么 + 为什么 + 怎么验证的**', '实机重装/升级路径实测一遍'],
+  'SECURITY-core.md': ['确认收到后 72 小时内回复', '严重漏洞优先修复并发布补丁版本'],
+};
+// 串味守卫：非 dsh-plugin 分类禁止出现 A 类专属命名串 `dsh-<name>`
+const DSH_NAME_RE = /dsh-<name>/;
+const DSH_NAME_ALLOWED_PREFIX = 'categories/dsh-plugin/';
+
+let failed = 0;
+const fail = (msg) => { console.error(`✗ ${msg}`); failed++; };
+const ok = (msg) => console.log(`✓ ${msg}`);
+
+// A. core 存在且唯一
+for (const f of Object.keys(CORE_FINGERPRINTS)) {
+  existsSync(join(COMMON, f)) ? ok(`common/${f} 存在`) : fail(`common/${f} 缺失（单源源丢失）`);
+}
+
+// B. 指纹扫描：core 特征句只准在 common 出现（覆盖 .md/.toml/.yml/.json——串味不全在 md）
+const SCAN_EXT = /\.(md|toml|ya?ml|json)$/;
+const scanTargets = [];
+function collectMd(dir) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) collectMd(full);
+    else if (SCAN_EXT.test(e.name)) scanTargets.push(full);
+  }
+}
+collectMd(BASE);
+collectMd(CATS);
+for (const [core, prints] of Object.entries(CORE_FINGERPRINTS)) {
+  for (const print of prints) {
+    for (const f of scanTargets) {
+      const rel = f.slice(ROOT.length + 1);
+      if (rel.startsWith(`common${'/'}${core}`)) continue;
+      const text = readFileSync(f, 'utf8');
+      if (text.includes(print)) fail(`多源漂移：指纹「${print.slice(0, 24)}…」同时出现在 common/${core} 与 ${rel}`);
+    }
+  }
+}
+ok('B. core 指纹扫描完成（无重复源即通过）');
+
+// B2. 串味守卫：非 dsh-plugin 分类禁止 `dsh-<name>`（A 类专属命名）
+for (const f of scanTargets) {
+  const rel = f.slice(ROOT.length + 1);
+  if (!rel.startsWith('categories/') || rel.startsWith(DSH_NAME_ALLOWED_PREFIX)) continue;
+  const text = readFileSync(f, 'utf8');
+  if (DSH_NAME_RE.test(text)) fail(`跨分类串味：${rel} 含 A 类专属命名串 dsh-<name>（应用 <repo>）`);
+}
+ok('B2. dsh-<name> 串味扫描完成');
+
+// C. 分类 append 命名规范
+for (const cat of readdirSync(CATS)) {
+  const d = join(CATS, cat);
+  for (const f of readdirSync(d)) {
+    if (/^(AGENTS|CONTRIBUTING)\.md$/.test(f) && !WHITELIST_FULL.has(`categories/${cat}/${f}`)) {
+      fail(`整份成文应改为 ${f.replace('.md', '')}-append.md（差异段）或入白名单：categories/${cat}/${f}`);
+    }
+    if (/^(AGENTS|CONTRIBUTING|gitignore)-append\.md$/.test(f) && !ENGINEERING.concat(MINIMAL).includes(cat)) {
+      fail(`append 段出现在未知分类：categories/${cat}/${f}`);
+    }
+  }
+}
+ok('C. append 命名规范检查完成');
+
+// D. 基类不留三份成文
+for (const f of ['AGENTS.md', 'CONTRIBUTING.md', '.gitignore']) {
+  if (existsSync(join(BASE, f))) fail(`基类残留成文 ${f}（应迁 common + append，scaffold 拼装生成）`);
+}
+ok('D. 基类单源化检查完成');
+
+console.log(failed ? `\n共 ${failed} 处多源/违规。` : '\n单源检查全部通过。');
+process.exit(failed ? 1 : 0);

package/templates/common/AGENTS-core.md

@@ -0,0 +1,28 @@
+# AGENTS（AI 协作与工程纪律）
+
+> 本文件由模板**单源拼装**（`common/AGENTS-core.md` + 分类 append）——重复段不要在仓库里手改；
+> 改规则先改模板源，再重新生成。人工协作者同样适用本文件全部条款。
+
+## 项目概览
+
+<一句话描述>。仓库根即工程根；分支、提交、验证、发版规范见下与 CONTRIBUTING.md。
+
+## 提交规范
+
+- **Conventional Commits 前缀 + 中文描述**：`feat(scope):` / `fix(scope):` / `refactor:` / `docs:` / `test:` / `chore:`；scope 用模块名；发布提交固定 `chore: release v<版本> — <一句话主旨>`。
+- **提交前必须跑本仓验证链单源**（命令见下方分类纪律节）并全绿；CI 与本地同源。FAIL 修根因，不绕过；确需 `--no-verify` 必须在提交说明注明原因。
+
+## AI 协作守则（agent 贡献者必读）
+
+1. **不猜 API/契约**：写代码前用宿主/依赖的检查工具查精确签名；测试 stub 必须按真实契约形状写（实践库教训：失真的 stub 会掩盖契约 bug）。
+2. **完成的定义 = 验证链全绿 + 实机/测试验收**，不是"代码写完"；声称完成前附验证输出。
+3. **机密红线**：本机绝对路径、个人邮箱、token/密钥、会过时的部署实况描述一律不入库；提交前 `git grep` 自查（模式见本仓 .gitignore 注释区）。
+4. **不静默绕过门禁**：pre-commit/CI FAIL 先修根因；中间态确需跳过必须留痕注明。
+5. **改动最小化**：不顺手重构、不改无关文件；构建产物与锁文件按仓库既定规则处理（产物不入库、锁文件必须入库）。
+6. **文档同步**：行为/接口变化同步 README、DEVELOPMENT 速查表（或等价文档）、CHANGELOG（如有）。
+7. **冲突处理**：本文件与生成它的模板源冲突时以模板源为准并回写；用户显式指示优先于本文件，但需在 PR/提交说明中标注冲突点。
+
+## 安全考虑
+
+- 漏洞**不要**公开披露：走 SECURITY.md 指定的私密漏洞报告渠道。
+- 依赖与 CI action 升级走仓库既定自动化（如有）；引入新依赖需在 PR 说明中给出理由。

package/templates/common/CONTRIBUTING-core.md

@@ -0,0 +1,21 @@
+# 贡献指南
+
+感谢贡献！本文件由模板**单源拼装**（`common/CONTRIBUTING-core.md` + 分类 append）——重复段勿在仓库手改。
+
+## 分支与合并
+
+- **单维护者（默认）**：直接提交 main；push 即触发 CI 验证链；main 保持线性历史。
+- **多人协作时**：feature 分支（`feat/<短名>` 或 `fix/<issue号>`）→ PR → CI 绿 + 评审通过后 squash 合并。
+
+## 提交规范
+
+- **Conventional Commits 前缀 + 中文描述**（改了什么 + 为什么）；发布提交格式见下方分类节。
+- **机密红线**：本机绝对路径、个人邮箱、token、部署实况快照一律不入库（与 AGENTS.md 同源纪律）。
+
+## 行为准则
+
+简单说：尊重、建设性、对事不对人。维护者会驳回不友善或与主题无关的 issue / PR。
+
+---
+
+<!-- 以下由分类 append 拼装：开发环境命令、部署/验证纪律、发版流程指路 -->

package/templates/common/DEVELOPMENT-core.md

@@ -0,0 +1,45 @@
+# <repo> 开发流程
+
+> 通用的**开发 → 验证 → 构建 → 发布**规范（humen 与 agent 均按此执行）；流程模型的团队变体
+> （如敏捷迭代）由分类 append 或团队自行补充。原则：**小步提交、每步可验证、事实落盘**。
+> 本文件由模板单源拼装（common/DEVELOPMENT-core.md + 分类 append）——重复段勿手改。
+
+## 1. 开发（Develop）
+
+- **动手前**：明确要做的一件事（功能/缺陷/技术债），用户故事格式更佳——`作为 <用户>，我想要 <能力>，以便 <收益>`
+- **契约预检**：用依赖方/宿主的检查工具查清要用的 API/接口**精确签名**——不猜（格式错误运行时才发现 = 一个迭代白做）
+- **实现规范**：见下方「分类纪律」节（语言/宿主专属硬规则）
+- **边界条件**：空输入 / 并发 / 超时 / 取消 / 重启恢复，设计时想过、测试里覆盖
+
+## 2. 验证（Verify）
+
+**验证链单源**（命令见 AGENTS.md / CONTRIBUTING.md 的分类纪律节；本地与 CI 同一入口）：
+
+- 提交前本地全绿；FAIL 修根因，不绕过（`--no-verify` 必须留痕注明）
+- **实机/实测验收**：部署到本机或测试环境真实跑一遍用户路径；无运行中验证 = 未做完
+- 机密自查：`git grep` 本仓既定模式（本机路径/邮箱/token），见 AGENTS.md 机密红线
+
+## 3. 构建与文档（Build & Document）
+
+- 构建产物不入库（CI 从源码重建）；锁文件必须入库（CI 复现依赖）
+- 文档同步：行为/接口变化同步 README 与等价设计文档；新坑进速查表（见附录机制）
+- CHANGELOG / 版本历史（如有）：每版一行「做了什么 + 为什么 + 怎么验证的」
+
+## 4. 发布（Release）
+
+- 发布是显式人工决策（tag / Release PR 合并）；流程见 [PUBLISHING.md](PUBLISHING.md)
+- 发布后验证：确认 latest 更新、provenance/attestations（按通道）、实机重装路径走一遍
+
+## 5. 反馈与沉淀（Feedback）
+
+- 用户的每个反馈都登记：满意点 / 不满意点 / 建议——不满意点优先转成待办缺陷条目
+- **复盘三问**（答案落盘）：① 这次什么顺利？② 这次踩了什么坑（新坑 → 立即进速查表）？
+  ③ 同类坑重复出现 ≥2 次？是 = 流程缺陷，先补流程再继续
+
+## 附录：高频坑速查表（回顾沉淀）
+
+<!-- 模板说明（用后删除）：三列 = 坑 | 症状 | 拦截环节；新坑先补表再修码；
+     回顾中发现"清单没拦住"的坑 → 改清单（流程本身也要迭代）。
+     预置行由分类 append 提供，其余按本库回顾追加。 -->
+
+## 6. 新增节（C2 升级实测）：升级流程验证。

package/templates/common/PUBLISHING-core.md

@@ -0,0 +1,31 @@
+# 发布记录：<repo>
+
+> 本文件由模板单源拼装（core + 分类 append）：发布通道/发布流程/应急发布由分类 append 决定；
+> 共性纪律在 core。
+
+## 发布状态（<日期> 更新）
+
+| 项 | 状态 |
+|---|---|
+| <发布面> | <版本 / dist-tag 状态> |
+| GitHub | `<org>/<repo>` main；发版 tag <tag 格式> |
+| 本地验证 | <验证链全绿 + 实测结论> |
+
+## 版本历史
+
+> 每版一行：**做了什么 + 为什么 + 怎么验证的**；重大教训展开写进当版条目。
+
+- **x.y.z** — <一句话主旨>（<日期>）：<要点；breaking 标注；验证方式>
+
+<!-- 模板说明（用后删除）：
+- 命名沿革/更名/deprecate 也记录在此（参照实践库"旧包 deprecate 指向新包"条目）
+- "只改产物不进 src = 修复丢失"类教训要写明，让历史可追溯
+-->
+
+## 发布后验证（共性纪律）
+
+- 确认 latest 已更新（包管理器或 GitHub Release 页）
+- provenance/attestations 徽章（按通道）或等价完整性校验
+- 实机重装/升级路径实测一遍（面向用户的安装命令照 README 走一遍）
+
+> 通道专属验证命令由分类 append 覆盖（按实际通道选择对应命令）。

package/templates/common/README-core.md

@@ -0,0 +1,60 @@
+# <repo>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+<!-- 分类徽章（npm/PyPI 等）由 append 提供并插到本行之后 -->
+
+<一句话描述>（与 GitHub about / 包管理器 description 一致；<120 字符，无节标题——Standard Readme #4）。
+
+[English](README.en.md) ｜ 中文为权威版本，翻译可能滞后。
+
+<!-- 模板说明（用后删除）：
+- 本文件由模板单源拼装（common/README-core.md + 分类 README-append）——重复段勿手改
+- 章节骨架依据 Standard Readme（github.com/RichardLitt/standard-readme，2026-09 核实）+ GitHub
+  官方 5 问 + makeareadme，分三档：
+  必选 = 标题+一句话简介 / 安装·上手 / 用法 / 贡献 / License（最后一节）
+  推荐 = 徽章 / **状态** / 详细简介(Why·Features) / 安全 / **非目标(边界)** / 求助渠道 / 多语言切换行
+  可选 = Banner·截图 / ToC(README<100 行可免) / API·配置参考 / Extra 自定义节 / Roadmap / 维护者 / 致谢 / See Also
+  （状态与非目标来自本生态 15 仓实况，为对 Standard Readme 的两处增强）
+- 分工：README = 卖点 + 5 分钟上手；CONTRIBUTING.md = 参与手册；docs/ = 全量参考（>500 KiB 渲染
+  截断，长内容一律外迁且从 README 可达）
+- 分类差异（徽章/安装/使用/配置）由分类 append 拼装（见下）
+- 状态/非目标两节来自本生态 15 仓实况（状态节 3 仓、非目标节 4 仓）——比 Standard Readme 更贴合
+  实际维护节奏，且对 agent 是范围护栏
+-->
+
+## 状态
+
+<当前状态：活跃开发 / 维护模式 / 验证期（先 N 周真实使用再决定）/ 已归档（欢迎 fork 接手）>
+
+<!-- 模板说明（用后删除）：状态声明放 README 顶部区（makeareadme 惯例）——停滞/验证期必须写明，让读者第一屏就知道预期。 -->
+
+## 功能
+
+<分类 append 拼装：功能/安装/使用/配置段（Standard Readme 的 Install/Usage/Extra）>
+
+<!-- 模板说明（用后删除）：双语策略（标配）：中文权威；README.en.md 由各分类提供——若暂无英文镜像，删除上方切换行并补 TODO。 -->
+
+## 非目标（边界）
+
+<明确不做什么：本版本刻意不覆盖的场景与原因——非目标能防止范围蔓延（humen/agent 都受益）；
+示例措辞：「v0.1 不做 <X>，因为 <原因>」
+
+## 安全
+
+漏洞**不要**公开 issue——走 [SECURITY.md](SECURITY.md) 指定的私密漏洞报告渠道。
+
+## 文档
+
+<!-- 无 docs/ 目录时删除本行；可选：ROADMAP / AUDIT 等 -->
+- [设计](docs/DESIGN.md)
+- [开发与验证纪律](DEVELOPMENT.md) · [发布流程](PUBLISHING.md)
+
+## 贡献
+
+- 问题与讨论：GitHub Issues / Discussions；是否收 PR 见 [CONTRIBUTING.md](CONTRIBUTING.md)
+- AI 协作者先读 [AGENTS.md](AGENTS.md)（含 AI 协作守则）
+- 行为准则：尊重、建设性、对事不对人（详见 CONTRIBUTING.md）
+
+## License
+
+[MIT](LICENSE)

package/templates/common/SECURITY-core.md

@@ -0,0 +1,19 @@
+# 安全策略
+
+## 支持面
+
+本仓库是<宿主能力面 / 服务用途>。安全边界值得关注的面：
+
+- <列出暴露面：网络入口（RPC/HTTP 端点及访问限制）、读写的敏感数据、对外请求>
+- <配置值来源与敏感度说明>
+- <发布产物携带的最小依赖>
+
+## 报告漏洞
+
+若你发现漏洞或安全缺陷，**不要**公开 issue——到 GitHub 仓库 Security 标签页用私密漏洞报告
+（Private vulnerability reporting，首选）。
+
+## 响应
+
+- 确认收到后 72 小时内回复。
+- 严重漏洞优先修复并发布补丁版本。

package/templates/common/copilot-instructions.md

@@ -0,0 +1,5 @@
+<!-- AI 协作入口（GitHub Copilot）：规则单源在仓库根 AGENTS.md -->
+Read AGENTS.md at the repository root before making any changes, and follow its
+AI-collaboration rules (verify before claiming done, never guess contracts, keep
+secrets out of the repo). Run the repo's single-source verification command
+before declaring a change complete.

package/templates/common/gitignore-core.md

@@ -0,0 +1,11 @@
+# ===== 通用段（scaffold 拼装时本行被剥除；改规则改本文件，勿手改产物）=====
+# 本机私有信息不入库（与 AGENTS.md 机密纪律同源）
+.env
+.env.*
+HANDOFF.md
+HANDOFF-ARCHIVE/
+
+# 编辑器与系统
+.DS_Store
+Thumbs.db
+*.log

package/templates/repo-root/.githooks/pre-commit

@@ -0,0 +1,20 @@
+#!/bin/sh
+# 部署纪律硬拦截：提交涉及插件源码（src/，lib/ 为构建产物已 ignore）时，
+# 强制跑装后自检（DEVELOPMENT.md「部署纪律：profile 安装」）。
+# 启用方式：git config core.hooksPath .githooks
+
+changed=$(git diff --cached --name-only --diff-filter=ACMR \
+        | grep -E '^(src|scripts)/' \
+        | head -1)
+[ -z "$changed" ] && exit 0
+
+echo "pre-commit：检测到源码改动（src/scripts），执行部署纪律自检 npm run check:deploy ..."
+node scripts/check-deploy.mjs
+code=$?
+if [ $code -ne 0 ]; then
+  echo ""
+  echo "✗ 部署纪律自检 FAIL：该插件源码与 profile 部署产物不一致（同版本号不同内容事故拦截点）。"
+  echo "  修复：npm run build 后执行 dsh plugin --profile web install，再重跑 npm run check:deploy。"
+  echo "  若本次提交确属尚未部署的中间态，请 commit --no-verify 并在提交说明注明\"未部署，部署前需自检\"。"
+  exit 1
+fi

package/templates/repo-root/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+# dsh-<name> CI 工作流（push/PR 验证）
+#
+# 首推前置：package-lock.json 必须已生成并入库（下方 npm ci 与 setup-node cache 都依赖
+# 它——参照实践库踩过的"setup-node cache 找不到 lockfile"坑；首次 commit 前先本地
+# npm install --legacy-peer-deps 生成 lockfile，模板 TODO 第 5 步有此指引）。
+#
+# 与 publish.yml 的分工：
+# - 本 workflow：push 到 main / PR 时跑验证链——把坏提交拦在进 main 当下，
+#   而不是等打 tag 发布时（publish.yml）才暴露
+# - 验证链与发布完全同源：scripts/verify.mjs 单源入口（npm test / publish.yml / 此处三者同调），
+#   链内增删步骤只改 verify.mjs
+# - 无发布语义：不需要 id-token（那是 OIDC 用的），权限只要 contents: read
+# - 新 push 取消同分支旧 run（与 publish.yml 的 cancel-in-progress: false 相反——
+#   发布不取消，验证随时可弃）
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@<commit-SHA> # actions/checkout@v7.0.1
+      - name: Setup Node
+        uses: actions/setup-node@<commit-SHA> # actions/setup-node@v7.0.0
+        # 不加 registry-url：CI 只读验证，不发布（见 publish.yml 内的 OIDC 说明）
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Install
+        run: npm ci --legacy-peer-deps
+      - name: Verify
+        run: node scripts/verify.mjs

package/templates/repo-root/.github/workflows/publish.yml

@@ -0,0 +1,77 @@
+# dsh-<name> 发布工作流（OIDC Trusted Publishing）
+#
+# 安全模型：
+# - 触发 = 本机人工创建的 tag（<name>-vX.Y.Z），发布决策永远是人的决定
+# - 认证：npm Trusted Publishing（OIDC）——npmjs.com 包设置里配置的 trusted
+#   publisher 只接受本仓库 publish.yml 的发布，免长期 token、自动 provenance
+#   （来源仓库须 public 才能生成 provenance）
+# - 权限最小化：contents: read + id-token: write（OIDC 签发所需）
+# - 版本一致性守卫：tag 版本必须与 package.json version 完全一致
+#   （打 tag 用显式两步：npm version --no-git-tag-version → 手动 git tag <name>-v$V，
+#    见 PUBLISHING.md——npm version 默认打 v%s tag，与本触发器不符）
+# - actions 按 SHA 固定（防供应链；升级 action 时换 SHA 并注明版本）
+name: publish
+
+on:
+  push:
+    tags:
+      - '<name>-v*'
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: npm-publish
+  cancel-in-progress: false
+
+# 可选人工审批门：GitHub repo Settings → Environments 建 <env 名> 并设
+# required reviewers，然后取消下行注释（npm 端 trusted publisher 的
+# environment 字段须与这里同名，逐字段一致）。
+# environment: npm-publish
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@<commit-SHA> # actions/checkout@v7.0.1
+      - name: Setup Node
+        uses: actions/setup-node@<commit-SHA> # actions/setup-node@v7.0.0
+        # 注意：不加 registry-url。setup-node 的 registry-url 会写一个带占位
+        # _authToken 的 .npmrc（NODE_AUTH_TOKEN=XXXXX…），shadow 掉 OIDC 认证，
+        # 使 npm publish 走 token 路径而 E404。trusted publishing 纯靠
+        # id-token: write，无需 registry-url / NODE_AUTH_TOKEN。
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: 'Guard: tag version matches package.json'
+        run: |
+          EXPECTED="refs/tags/<name>-v$(node -p "require('./package.json').version")"
+          if [ "$GITHUB_REF" != "$EXPECTED" ]; then
+            echo "::error::tag/version mismatch: $GITHUB_REF vs $EXPECTED"
+            exit 1
+          fi
+      - name: Install
+        run: npm ci --legacy-peer-deps
+        # 有 Playwright 视觉测试的库再加：env: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1'
+      - name: Verify (build → typecheck → smoke/vitest → mount …)
+        # 验证链单源：scripts/verify.mjs——链内增删步骤只改它；此处与 package.json "test" 都只调它。
+        # smoke/mount/vitest 为探测式：文件存在才跑，接入即自动进链。
+        run: node scripts/verify.mjs
+      - name: Publish to npm (OIDC trusted publishing)
+        # 升级 npm：trusted publishing 需 npm CLI >= 11.5.1（含 OIDC 支持）。
+        # prerelease → dist-tag next（忘加 --tag next 是最常见事故：
+        # 用户 npm install 会装到 prerelease）；稳定版 → latest。
+        run: |
+          npm install -g npm@latest
+          echo "npm version: $(npm --version)"
+          VERSION="$(node -p "require('./package.json').version")"
+          if [[ "$VERSION" == *-* ]]; then
+            echo "canary prerelease $VERSION → dist-tag next"
+            npm publish --access public --tag next --provenance --loglevel verbose
+          else
+            echo "stable $VERSION → dist-tag latest"
+            npm publish --access public --provenance --loglevel verbose
+          fi

package/templates/repo-root/CLAUDE.md

@@ -0,0 +1,3 @@
+<!-- 模板说明：Claude Code 不直接读 AGENTS.md，官方桥接做法是 CLAUDE.md 用 @ 导入。
+     本文件原样复制即可；如需 Claude 专属指令，追加在 @AGENTS.md 之后。 -->
+@AGENTS.md

package/templates/repo-root/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) <year> <org 法律名>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.