repo-audit-tool 1.2.0

package/rules/domains/security.yaml

@@ -0,0 +1,79 @@
+rules:
+  - id: SEC-001
+    title: "无硬编码密钥"
+    severity: critical
+    domain: security
+    applies_to: ["*"]
+    check: grep
+    params:
+      patterns:
+        - "(?i)(api[_-]?key|secret|password|token)\\s*[:=]\\s*['\"][^'\"]{8,}"
+      exclude:
+        - ".git/"
+        - "node_modules/"
+        - ".scaffold/"
+        - "audit-report/"
+        - "templates/"
+      max_match: 0
+    description: "源代码中不应包含硬编码密钥或凭证（AGENTS-core 机密红线第 3 条）"
+    fix_hint: "使用环境变量或密钥管理服务"
+
+  - id: SEC-002
+    title: "Workflow 使用 SHA 固定"
+    severity: major
+    domain: security
+    applies_to: ["dsh-plugin", "python-app", "go-service", "javascript", "npm-package"]
+    check: grep
+    params:
+      patterns:
+        - "@[a-f0-9]{40}"
+      exclude:
+        - ".git/"
+        - "node_modules/"
+        - ".scaffold/"
+        - "audit-report/"
+        - "templates/"
+      max_match: 1
+    description: "GitHub Actions workflow 应使用 SHA 固定而非 tag（BEST-PRACTICES §6.1）"
+    fix_hint: "将 actions/checkout@v4 改为 actions/checkout@<SHA>"
+    note: "无 workflow 文件的仓库豁免"
+
+  - id: SEC-003
+    title: "无本机绝对路径"
+    severity: minor
+    domain: security
+    applies_to: ["*"]
+    check: grep
+    params:
+      patterns:
+        - "/home/[a-z]"
+        - "/Users/[a-z]"
+        - "/mnt/[a-z]"
+      exclude:
+        - ".git/"
+        - "node_modules/"
+        - ".scaffold/"
+        - "audit-report/"
+        - "templates/"
+        - "CHANGELOG.md"
+        - "HANDOFF.md"
+        - "HANDOFF-ARCHIVE/"
+        - ".agents/"
+      max_match: 0
+    description: "源代码不应包含本机绝对路径（AGENTS-core 机密红线第 3 条）；CHANGELOG/HANDOFF 等交接文档豁免"
+    note: "severity=minor：描述性路径文本（如 CHANGELOG 中的扫描描述）容忍；硬编码密钥仍由 SEC-001 覆盖"
+
+  - id: SEC-004
+    title: "publish workflow 含 id-token write"
+    severity: critical
+    domain: security
+    applies_to: ["dsh-plugin", "python-app"]
+    check: yaml_field
+    params:
+      path: ".github/workflows/publish.yml"
+      field: "permissions.id-token"
+      expected: "write"
+      skip_if_no_file: ".github/workflows/publish.yml"
+    description: "publish workflow 必须请求 id-token: write 权限（OIDC Trusted Publishing）"
+    template_ref: "templates/repo-root/.github/workflows/publish.yml"
+    fix_hint: "在 workflow 顶部添加 permissions: id-token: write"

package/shim/repo-audit.cmd

@@ -0,0 +1,7 @@
+@echo off
+:: repo-audit Windows CMD shim
+:: 找到脚本所在目录的父目录，执行 repo-audit.mjs
+setlocal enabledelayedexpansion
+set "SCRIPT_DIR=%~dp0"
+set "NODE_SCRIPT=%SCRIPT_DIR%..\repo-audit.mjs"
+node "%NODE_SCRIPT%" %*

package/shim/repo-audit.ps1

@@ -0,0 +1,4 @@
+# repo-audit PowerShell shim
+# 找到脚本所在目录的父目录，执行 repo-audit.mjs
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+& node "$scriptDir\..\repo-audit.mjs" @args

package/shim/repo-audit.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# repo-audit Linux/macOS/Unix POSIX shell shim
+# 找到脚本所在目录的父目录，执行 repo-audit.mjs
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "$SCRIPT_DIR/../repo-audit.mjs" "$@"

package/templates/AGENT-GUIDE.md

@@ -0,0 +1,331 @@
+# scaffold init/update 操作手册（agent 用）
+
+## §A 开始之前
+
+### 1. 适用对象与前提
+
+- 使用对象：AI coding agent（DSH agent、Claude Code、Copilot 等以编程方式调用 scaffold 的场景）。人也可以参考，但本手册假设调用方是 agent——所有输出都可 grep/parse，所有异常都有明确退出码。
+- 前置条件：git 可用；node 可用（≥18）；模板集路径可达。
+- 反馈路径（绝对路径，写反馈前先确认可达）：
+  `./feedback/`
+- 参考文档：[UPDATE-MODEL.md](UPDATE-MODEL.md)（机制设计）· [UPDATE-PLAN.md](UPDATE-PLAN.md)（分阶段实施）
+
+### 2. 速查
+
+```sh
+S="/path/to/templates/scaffold.mjs"
+
+# 新建仓库（五分类 + overlay）
+node $S --type <分类> --name <短名> --org <org> --desc "<一句话>" --target <目录>
+
+# 更新已有仓库（自动探测元数据；可显式覆盖）
+node $S --update <仓库路径> [--type <分类>] [--name/--org/--desc/--legal/--surface ...]
+
+# 预览（不写任何文件）
+node $S --update <仓库路径> --dry-run
+
+# 回滚最近一次 update
+node $S --rollback <仓库路径>
+```
+
+### 3. 分类选择
+
+| --type | 适用 | 产物 |
+|---|---|---|
+| `dsh-plugin`（默认） | dsh 宿主插件 | TS 骨架 + npm 发布链 + 部署纪律 |
+| `python-app` | Python 应用/研究 | pyproject + PyPI TP 发布链 |
+| `go-service` | Go 服务 | Makefile + GoReleaser 发布链 |
+| `sandbox` | 本地实验/dogfood | 最小集（无 CI/发布） |
+| `content` | 内容/写作 | 最小集（正文 + review 分离） |
+| + `--overlay product-oss` | 上述任一 + 多人协作 | 额外叠加 release-please/PR/issue/CODEOWNERS/dependabot |
+
+判断规则：写代码挂到 dsh 宿主 → dsh-plugin；pyproject 项目 → python-app；go.mod → go-service；一次性实验 → sandbox；文档即制品 → content；会多人协作 → 加 `--overlay product-oss`。
+
+## §B 操作
+
+### 4. init（新建仓库）操作流程
+
+#### 步骤 1：契约预检（写代码之前）
+
+1. `cordis_inspect_list` / `cordis_inspect_query` 查清用到的 Service/Event/Builtin/Slot 精确签名——**不猜 API**
+2. 记录宿主包清单 → 决定 package.json peer/devDeps
+3. 确认分类：host half only 还是 host+client 双 half（影响 dsh.client.inject 与 build-client.mjs）
+
+#### 步骤 2：出库
+
+```sh
+node $S --type dsh-plugin --name myplugin --org NinjaSln-labs \
+  --desc "一句话描述" --surface "宿主能力面" --target /path/to/dsh-myplugin
+```
+
+- `--name` 不带 dsh- 前缀（自动剥除并告警）；包名/仓库名派生为 `dsh-<name>`
+- 产物：全套治理文件（AGENTS/README×2/CONTRIBUTING/DEVELOPMENT/PUBLISHING/SECURITY/LICENSE/CLAUDE.md/.gitignore）+ 工程骨架（package.json/tsconfig/src/scripts/.github/.githooks）
+- git init + hooksPath 自动完成
+
+#### 步骤 3：按产物 AGENTS.md 与 TODO 清单执行
+
+出库末尾打印分类专属 TODO（含精确命令）。关键必做项：
+
+1. package.json 填 peer/devDeps（占位符不是合法包名，直接 install 会报 EINVALIDPACKAGENAME）——**dsh-plugin 专属**
+2. `npm install --legacy-peer-deps` → `package-lock.json` **必须入库**——**dsh-plugin 专属**
+3. `npm run build` → `dsh plugin --profile web install`（file: 接线）→ `npm run check:deploy`——**dsh-plugin 专属**
+4. workflow 的 `<commit-SHA>`：从参照库（dsh-context-compass）同名文件抄当前锁定值
+5. GitHub 建库：`gh repo create <org>/<repo> --public --source . --description "..." --push`
+6. **所有分类通用：出库后必须 `git add -A && git commit`**（工作区脏会阻塞后续 update；pre-commit 钩子因工具链缺失 FAIL 时可用 `--no-verify` 应急）
+
+#### init 后的验证清单（agent 自检，全绿才算完成）
+
+```sh
+cd <产物目录>
+grep -rn '模板说明' . --include='*.md' | wc -l        # 期望 0
+# 依赖占位检查：dsh-plugin 查 package.json；python-app 查 pyproject.toml；go-service 查 go.mod
+# 期望 0（依赖占位已填）
+# 验证链按分类：dsh-plugin=node scripts/verify.mjs / python-app=python3 scripts/verify.py / go-service=make verify
+# （期望"验证链全绿"或 SKIP——工具未装时 exit 2 不阻塞）
+git add -A && git commit                              # init 产物必须 commit（否则 update 的 clean 检查拒绝）
+```
+
+### 5. update（已有仓库）操作流程
+
+#### 何时用 update
+
+> **硬性要求：update 时始终显式传 `--type <分类>`**——不传时 lock.template 优先（二次 update 安全），
+> 但首次 adopt（无 lock）会 fallback 为 dsh-plugin，可能对非 dsh 仓库产生错误分类的文件。
+
+
+
+- 存量仓库要接入模板治理（首次 adopt）
+- 已接入的仓库要吸收模板升级（lock 存在时全自动）
+- 仓库缺失模板管辖文件（CI/hooks/AGENTS 等）需要补齐
+
+#### 首次 update（adopt 模式）——仓库无 .scaffold/lock/ 时
+
+```sh
+# 先 dry-run 看会改什么（不写任何文件）
+node $S --update /path/to/repo --type <分类> --dry-run
+
+# 确认后正式执行
+node $S --update /path/to/repo --type <分类>
+```
+
+**adopt 行为**：
+
+- 建立状态层：`.scaffold/lock/`（base 快照 + manifest）+ `last-update.json`
+- 仓库**缺失**的模板文件 → ADDED 直拷（写仓库）
+- 仓库**已有**的文件 → 不覆盖！模板版写入 `.scaffold-merge/<相对路径>` 供比对采纳
+- git 自动 commit（回滚点）+ `.gitignore` 增补过程目录
+
+**agent 必做的 adopt 收尾**：
+
+1. 逐个查看 `.scaffold-merge/` 的 diff（`diff <仓库文件> <merge文件>`），决定采纳策略
+2. 采纳 = 用模板版覆盖仓库文件（或人工合并两边内容）
+3. `git add -A && git commit`（收口 adopt，否则下次 update 会被 clean 检查拒绝）
+4. 确认 `.scaffold/lock/` 已入库（回滚连带状态）
+
+#### 后续 update（lock 存在时）——全自动
+
+```sh
+node $S --update /path/to/repo
+```
+
+**状态机**（对每个模板管辖文件）：
+
+| 判定 | 处置 | agent 需要做 |
+|---|---|---|
+| 仓库缺失 | ADDED 直拷 | 无（自动 commit） |
+| ours == lock.base | FAST-FORWARD 采纳模板新版 | 无（自动 commit）——用户未改过，安全 |
+| 模板未变 | UNCHANGED 保持 | 无 |
+| ours ≠ base ≠ new | 三方合并（git merge-file --zdiff3）| 见下方冲突处理 |
+
+**冲突处理（QUARANTINED）**：三方合并无法自动解决时，冲突文件（含 zdiff3 markers）落盘到 `.scaffold/conflicts/<路径>.rej`，不阻塞其他文件。
+
+agent 裁决步骤：
+
+1. 读 `.rej` 文件（zdiff3 格式：current/base/template 三段）
+2. 结合上下文决定保留/合并——**保留用户已填的占位值与自定义段，吸收模板新条款**
+3. 把裁决结果写回仓库文件（替换含 markers 的原文件）
+4. `git add -A && git commit`
+5. 删除 `.scaffold/conflicts/` 对应文件
+6. 下次 update 该文件将走 UNCHANGED 或正常合并（lock 已吸收裁决）
+
+#### update 后收口（agent 必做）
+
+- 全部 UNCHANGED/FAST-FORWARD/MERGED-CLEAN → 工具已自动 commit，无需操作
+- 有 MERGE-REVIEW → 查看 .scaffold-merge/ 并采纳（或忽略），然后 `git add -A && git commit`
+- 有 QUARANTINED → 按"冲突裁决 6 步"处理，然后 commit + 删 .scaffold/conflicts/
+- **update 后不收口会阻塞下一次 update**（clean 检查拒绝）
+
+#### update 输出解读
+
+每个文件的状态标记：
+
+| 标记 | 含义 | agent 动作 |
+|---|---|---|
+| `ADDED` | 新文件已写入 | 无 |
+| `FAST-FORWARD` | 仓库未改→采纳模板新版 | 无 |
+| `UNCHANGED` | 与模板一致或模板未变 | 无 |
+| `MERGED-CLEAN` | 三方合并干净 | 无 |
+| `MERGE-REVIEW` | adopt 首见差异→.scaffold-merge/ | **人工/agent 比对采纳** |
+| `QUARANTINED` | 三方合并冲突→.scaffold/conflicts/ | **agent 裁决（见上）** |
+| `SKIP` | 用户在 --skip 清单中 | 无 |
+
+#### update 后的验证清单（agent 自检）
+
+```sh
+cd <仓库>
+# 按分类选验证链：dsh-plugin=node scripts/verify.mjs / python-app=python3 scripts/verify.py / go-service=make verify
+git status --porcelain | wc -l                 # 期望 0（全部已 commit）
+grep -rn '<<<<<<<\|>>>>>>>' <管辖文件> 2>/dev/null | wc -l  # 期望 0（无残留 marker）
+test -f .scaffold/lock/manifest.json && echo "lock ✓"
+test -f .scaffold/last-update.json && echo "更新记录 ✓"
+```
+
+#### 各分类自动探测源差异（update 模式元数据探测）
+
+| 分类 | name 来源 | desc 来源 | org 来源 | 限制 |
+|---|---|---|---|---|
+| dsh-plugin | package.json（剥 dsh-）→ 目录名 | package.json description | git remote origin | 探测最完整 |
+| python-app | pyproject.toml name → 目录名 | pyproject description | git remote origin | 需显式传 desc（探测可能为空） |
+| go-service | 目录名 | **无自动探测**（必须显式传 --desc） | git remote origin | 需显式传 --desc/--surface |
+| sandbox/content | 目录名 | **无自动探测** | 默认 NinjaSln-labs | 最小集，建议全显式传参 |
+
+#### update 后收口（agent 必做）
+
+- 全部 UNCHANGED/FAST-FORWARD/MERGED-CLEAN → 工具已自动 commit，无需操作
+- 有 MERGE-REVIEW → 查看 .scaffold-merge/ 并采纳（或忽略），然后 `git add -A && git commit`
+- 有 QUARANTINED → 按"冲突裁决 6 步"处理，然后 commit + 删 .scaffold/conflicts/
+- **update 后不收口会阻塞下一次 update**（clean 检查拒绝）
+
+## §C 安全网
+
+### 6. 使用前备份（agent 必做）
+
+> 实测覆盖不可能穷尽所有仓库状态；使用反馈尚不足以确认所有边界安全。**update 前的备份是 agent 的责任，不是工具的责任。**
+
+#### update 前必须做的备份（按仓库状态选择）
+
+| 仓库状态 | 备份命令 | 恢复方式 |
+|---|---|---|
+| **git 仓且工作区 clean**（标准场景） | 无需额外备份——前置 clean + 自动 commit 已构成回滚点 | `git revert <sha>` 或 `git reset --hard <preUpdateHEAD>` |
+| **git 仓但有未提交改动** | `git stash push -m "scaffold update 前备份"`（update 拒绝 dirty，先 stash 后再跑） | `git stash pop` |
+| **非 git 目录** | `cp -r <目录> <目录>.bak.<日期>` | `rm -rf <目录> && mv <目录>.bak.<日期> <目录>` |
+| **不确定 / 首次接触该仓** | `git tag scaffold-pre-update-$(date +%s)` + `cp -r <目录> <目录>.bak.<日期>` | tag: `git reset --hard <tag>`；目录：同上 |
+
+#### agent 备份自检（update 前逐条过）
+
+1. `git status --porcelain` 是否为空？→ 空则安全（git 可回滚）
+2. 仓库是否有 `.scaffold/lock/`？→ 有则走自动模式（比 adopt 安全）
+3. 仓库是否有大量非模板管辖的自定义文件？→ 有则**额外** `cp -r` 目录备份
+4. 是否为首次接触该仓库？→ 是则**额外** `cp -r` 目录备份（不信任探测结果）
+
+#### 备份完成后才允许调用 update
+
+```sh
+# 标准场景（git clean）：跳过额外备份
+node $S --update <仓库路径>
+
+# 非标准场景（有自定义内容 / 首次接触）：先备份
+cp -r <仓库目录> <仓库目录>.bak.$(date +%Y%m%d%H%M%S)
+# 确认备份存在后才执行 update
+ls <仓库目录>.bak.* >/dev/null && node $S --update <仓库路径>
+```
+
+### 7. 回滚
+
+```sh
+node $S --rollback /path/to/repo
+# 等价于：git reset --hard <preUpdateHEAD>（回到 update 前状态）
+```
+
+前置：工作区必须 clean。回滚后审计历史保留（revert 生成新 commit；update 的 last-update.json 记录 preUpdateHEAD）。
+紧急情况（revert 失败）：`git reset --hard <preUpdateHEAD>`（last-update.json 有记录）。
+
+#### 回滚能力边界（agent 必知）
+
+| 能力 | 机制 | 限制 |
+|---|---|---|
+| 撤销最近一次 update 的全部改动 | `--rollback`（git reset --hard preUpdateHEAD） | **只保留最近一次**（last-update.json 每次覆盖） |
+| 回到 update 前的精确状态 | `git reset --hard <preUpdateHEAD>` | 同上；且会连 lock 一起回退 |
+| 撤销最近一次 update 的全部改动 | `--rollback`（git reset --hard preUpdateHEAD） | **只保留最近一次**（last-update.json 每次覆盖） |
+| 回到 update 前的精确状态 | `git reset --hard <preUpdateHEAD>` | 同上；且会连 lock 一起回退 |
+| 恢复单个文件 | `git log --oneline -- <file>` 找到 commit → `git checkout <sha> -- <file>` | 手动操作（**不要用 last-update.json 的 commitSha**——amend 后 SHA 可能变化） |
+| 两次前的 update | 不支持（lock 只有一层） | 如需多次回滚：update 前手动打 tag |
+| 恢复"update 前工作区未提交改动" | 不存在此场景 | update 前置 clean 检查已保证 |
+
+**不是备份系统**：`--rollback` = git reset --hard preUpdateHEAD（回到 update 前状态），不是文件快照恢复。update 的安全模型 = 前置 clean + 自动 commit（回滚点）+ revert（撤销）。多次 update 需多次回滚时，建议 update 前手动打 tag（`git tag pre-update-<N>`）。
+
+## §D 排障
+
+### 8. 异常与退出码
+
+| 退出码 | 场景 | agent 处置 |
+|---|---|---|
+| 0 | 成功 | 按 TODO/report 继续 |
+| 1 | 拒绝执行（非 git 仓/脏工作区/lock 损坏/未知旗标/参数缺失） | 读 stderr 修复调用条件后重试 |
+| 2 | verify.py 工具未安装（SKIP 语义） | 不阻塞 update；建议 `pip install -e ".[dev]"` 后重跑 |
+| 129 | git merge-file usage 错误 | 更新模式下自动降级 MERGE-REVIEW；如复现报 issue |
+
+### 9. 注意事项（硬性）
+
+1. **不要手改 `.scaffold/lock/`**：manifest/base 是三方合并的 base，手改会欺骗算法
+2. **不要手改 `last-update.json`**：rollback 依赖它
+3. **不要把 `.scaffold/lock/` 加入 .gitignore**：lock 必须入库（Copier/buf 惯例）
+4. **update 前必须 commit/stash**：工作区不干净时拒绝执行（回滚点唯一性）
+5. **每次 update 后立即 commit**：未 commit 状态会阻塞下一次 update
+6. **非模板管辖文件 update 永远不碰**：src 实现、data、用户手写文件不在管辖集内
+7. **`--skip <path>` 让文件退出自动更新域**：对"这个文件我手管"的文件使用（可多次）
+8. **update 前做备份（见 §C"使用前备份"）**：实测覆盖不可能穷尽，agent 自己兜底
+9. **lock 损坏（非法 JSON）→ 自动降级为 adopt 模式**：仍安全，但失去三方合并能力；修复=删除 .scaffold/lock/ 后重跑 update 重建快照
+10. **类型不可中途切换**：update 时 --type 与 lock.template 不一致会被拒绝；切换分类需删 .scaffold/lock/ 重新 adopt
+
+## §E 参考
+
+### 10. 完整参数参考
+
+```
+--type <分类>          分类（默认 dsh-plugin）
+--name <短名>          名称（不带 dsh- 前缀，自动剥除+告警）
+--org <org>            GitHub 组织（默认 NinjaSln-labs）
+--desc "<一句话>"      一句话描述（与 GitHub about 一致）
+--surface "<能力面>"   宿主能力面（默认=desc）
+--legal "<版权主体>"   LICENSE 版权行（默认=org）
+--target <目录>        目标目录（generate 模式；默认 ../dsh-<name>）
+--force                空目录复用（含 .git 时仍拒绝）
+--update <仓库路径>    更新模式（自动探测元数据）
+--overlay <名>         叠加 overlay（product-oss）
+--dry-run              只对比不写文件（update 模式）
+--skip <path>          退出自动更新域（update 模式，可多次）
+--rollback <仓库路径>  回滚最近一次 update
+--help                 帮助
+```
+
+### 11. 反馈通道
+
+模板集仍在实测阶段，以下情况请记录并反馈给模板维护者：
+
+| 类型 | 示例 | 反馈内容 |
+|---|---|---|
+| **误覆盖** | update 后仓库文件内容丢失/被改 | 仓库路径 + .scaffold/lock/manifest.json + 丢失前后的 diff |
+| **误判分类** | 某仓库用 A 分类出库但行为不符 | 仓库名 + 使用的 --type + 期望 vs 实际 |
+| **merge-file 失败** | exit 129/负数/空输出 | .scaffold/conflicts/ 的 .rej 文件 + stderr |
+| **探测错误** | name/desc/org 自动探测结果不对 | 仓库元数据文件（package.json 等）+ 探测输出 |
+| **模板内容错误** | 产物中的规范/命令与实际不符 | 具体文件 + 正确做法 |
+
+#### 反馈存放路径（agent 必读）
+
+```
+./feedback/
+```
+
+#### agent 写反馈的执行步骤
+
+1. **确认路径可达**：`test -d "./feedback/"` → 不存在则 `mkdir -p`
+2. **确认可写**：`test -w` 同路径 → 不可写则**用 ask_user 向用户确认正确的反馈存放路径**，不要猜
+3. 路径确认后写入：`<feedback路径>/<YYYY-MM-DD>-<主题>.md`
+
+#### 反馈文件内容要求
+
+- 仓库绝对路径
+- 使用的完整命令（含全部旗标）
+- 期望 vs 实际（附相关文件 diff 或报错原文）
+- 如涉及 update：附 .scaffold/lock/manifest.json 快照副本

package/templates/README.md

@@ -0,0 +1,192 @@
+# 个人仓库模板集（templates/）
+
+> 依据上级目录 `../BEST-PRACTICES.md` 的调研结论整理，dsh 插件基类（repo-root/）
+> 以已跑通发布的 `dsh-context-compass` / `dsh-subagent-router` 单库实底文件为蓝本，不是凭空设计。
+> 适用两条路线：**A. 从零新建库**（主路线）与 **B. 从 dsh-plugins monorepo 迁移**（增量路线，另见
+> `../../DSH-PLUGIN-STANDALONE-MIGRATION.md`）。
+> **分类体系**：全仓 23 个 git 仓库按模板差异分 7 类（见 `../REPO-CLASSIFICATION.md`），
+> `scaffold.mjs --type <分类>` 路由；`categories/` 为各分类 delta 与说明。
+
+## 分类与脚手架路由
+
+| --type | 分类 | 覆盖仓库（实证数） | 产物 |
+|---|---|---|---|
+| `dsh-plugin`（默认） | A · dsh 插件单库 | dsh-* 6 库 | repo-root 基类全量 |
+| （overlay） | B · 产品/多人 OSS | qingfu-envoy / neonforge / fuyao-nomad / Voyage | 语言基类 + `categories/product-oss/` 叠加（`--overlay product-oss`）：release-please v5 版本晋升自动化 / YAML issue forms / CODEOWNERS / dependabot / dependency-review / SUPPORT.md 升级检查清单 |
+| `python-app` | C · Python 应用/研究 | chumen / shisui / shuijing-v2 / vertical-small-model | 基类换 pyproject/verify.py/ruff+pytest CI |
+| `go-service` | D · Go 服务 | jinteng | 基类换 Makefile 四件套/go CI |
+| `sandbox` | E · 本地实验/dogfood | fuyao-* 11 库 + weather-outfit-assistant | 最小集（README+AGENTS，无 CI/发布） |
+| `content` | F · 内容/写作 | rsi-unit-of-evolution / part-time-job | 最小集（正文+review 分离） |
+| （不套模板） | G · 存档只读 | dsh-plugins（封版） | 遵守仓内封版纪律 |
+
+```sh
+node scaffold.mjs --type python-app --name chumen2 --desc "..."   # 例
+```
+
+## 单源原则（AGENTS / CONTRIBUTING / .gitignore / README / DEVELOPMENT / PUBLISHING / SECURITY）
+
+- 共性内容**只存在于 `common/*-core.md` 一份**：
+  - `AGENTS-core.md`——概览/提交规范/**「AI 协作守则」7 条**（不猜契约 / 完成的定义 = 验证链全绿 /
+    机密红线 / 不静默绕过门禁 / 改动最小化 / 文档同步 / 冲突处理）/ 安全考虑
+  - `CONTRIBUTING-core.md` · `gitignore-core.md` · `README-core.md`（标题/简介/文档/贡献/License）
+  - `DEVELOPMENT-core.md`（核心循环/Backlog/Sprint 契约预检/DoD 三段/回顾/速查表机制）
+  - `PUBLISHING-core.md`（发布状态/版本历史/发布后验证）· `SECURITY-core.md`（通用，无分类差异）
+- 分类差异只写 `categories/<type>/*-append.md`（npm/PyPI/GoReleaser 的安装段与发布通道、
+  dsh 部署纪律全文等）；scaffold 拼装生成，产物内**不要手改**拼装段
+- **双语 README 标配**：各分类均提供 `README.en.md` 模板；语言切换行在 README-core（单源），
+  英文镜像回链 `README.md` 并声明中文权威；英文镜像与中文同步更新（DoD 文档项）
+- 改规则 → 改 common/append 源 → 重新 scaffold；**漂移由 `check-single-source.mjs` 把守**
+  （core 指纹扫描 / append 命名 / 基类残留，CI/审计可挂，发现多源 exit 1）
+
+## 更新模式（--update，v2.1 设计定稿）
+
+已初始化仓库可通过 `scaffold --update <仓库路径>` 吸收模板更新：生成-对比（Copier 同款语义）→
+状态机（快进/三方合并 git merge-file --diff3）→ 冲突分级裁决（机械自动 / agent 裁决 + 确定性验证
+门禁 / QUARANTINED `.rej` 兜底）→ 自动 commit（回滚点）→ 报告与回滚（`--rollback`）。
+状态层 `.scaffold/lock/`（base 快照 + manifest）入库。**完整设计：[UPDATE-MODEL.md](UPDATE-MODEL.md)（机制 v2.1）· [UPDATE-PLAN.md](UPDATE-PLAN.md)（分阶段实施方案）——已实施，agent 操作手册：[AGENT-GUIDE.md](AGENT-GUIDE.md)。**
+
+## Agent 参与优化
+
+所有工程分类的 AGENTS.md 内置「AI 协作守则」；AI 入口三桥接——`CLAUDE.md`（`@AGENTS.md` 导入）、
+`.github/copilot-instructions.md`（工程分类自动配，sandbox/content 最小集不带）、AGENTS.md 本体
+（DSH 实证有效）。pre-commit 验证链前门即 agent 防呆：FAIL 修根因，`--no-verify` 必须留痕。
+
+## 占位符约定
+
+| 占位符 | 含义 | 示例 |
+|---|---|---|
+| `<name>` | 插件短名（不带 dsh- 前缀） | `context-compass` |
+| `<repo>` | 仓库名，scaffold 按分类派生：dsh-plugin = `dsh-<name>`，其余 = `<name>` | `dsh-context-compass` / `chumen` |
+| `dsh-<name>` | npm 包名（A 类专属派生） | `dsh-context-compass` |
+| `<org>` | GitHub 组织 | `NinjaSln-labs` |
+| `<一句话描述>` | repo description / README 首句 / package.json description | `DSH 上下文占用罗盘` |
+| `<year>` / `<org 法律名>` | LICENSE 版权行 | `2026 ninjasln` |
+| `<宿主能力面>` | 插件挂在 dsh 的哪一层（工具/命令/设置页/Slot UI…） | `多会话上下文健康面板` |
+| `<用到的宿主包>` 等 | package.json peer/devDeps 占位 | 按 `cordis_inspect_query` 契约预检结果填 |
+
+模板内的 **HTML 注释 `<!-- 模板说明：… -->` 与引用块说明在使用时删除**；正文是可保留的成文。
+
+## 文件 → 单库目标路径映射
+
+> **七份文档（README/README.en/CONTRIBUTING/DEVELOPMENT/PUBLISHING/SECURITY/AGENTS）+ .gitignore
+> 已迁单源拼装**：源在 `common/*-core.md` + `categories/<type>/*-append.md`，由 scaffold 拼装生成
+> （见上方「单源原则」）——**repo-root 已无这些文件**，勿在此表找复制路径。
+
+### 文档与仓库治理（拼装生成 / 分类提供）
+
+| 模板 | 产物 | 作用 | 拼装后必改 |
+|---|---|---|---|
+| `common/README-core.md` + `<type>/README-append.md` | 根 `README.md` | 通用骨架（Standard Readme 三档 + 状态/非目标节）+ 分类徽章/安装/使用/配置 | 标题/描述/安装命令/配置项 |
+| `categories/<type>/README.en.md` | 根 `README.en.md` | 英文镜像（双语标配，各分类提供，回链中文）；结构为 Standard Readme 核心节（Features/Install/Usage/Configuration/Docs/Contributing/License）——状态/非目标两节仅中文版提供（中文权威的扩展节） | 同步中文版对应节 |
+| `common/CONTRIBUTING-core.md` + append | 根 `CONTRIBUTING.md` | 分支/提交规范/机密红线 + 分类开发环境命令 | 验证链命令按本库改 |
+| `common/DEVELOPMENT-core.md` + append | 根 `DEVELOPMENT.md` | 通用开发→验证→构建→发布流程 + 分类纪律/DoD/速查表 | 验证链/插件名 |
+| `common/PUBLISHING-core.md` + append | 根 `PUBLISHING.md` | 发布状态 + 版本历史 + 分类发布通道（npm OIDC/PyPI TP/GoReleaser） | 发布状态表填实际值 |
+| `common/SECURITY-core.md` | 根 `SECURITY.md` | 通用安全策略（无分类差异） | 支持面描述 |
+| `common/AGENTS-core.md` + append | 根 `AGENTS.md` | AI 协作守则 7 条 + 分类纪律（agent/humen 双入口） | 包名 |
+| `common/gitignore-core.md` + append | 根 `.gitignore` | 机密/编辑器通用段 + 语言忽略段 | 视库增删 |
+| `common/copilot-instructions.md` | `.github/copilot-instructions.md` | Copilot 桥接（指向 AGENTS.md） | 无 |
+| `categories/dsh-plugin/CLAUDE.md`（基类 `repo-root/CLAUDE.md`） | 根 `CLAUDE.md` | Claude Code 桥接（`@AGENTS.md` 导入） | 无（原样复制） |
+| `skill/SKILL.md` | `~/.agents/skills/<skill-name>/SKILL.md`（已验证）；项目级分发 Claude Code 用 `.claude/skills/`，DSH 项目级未验证 | 跨仓库可复用流程的 skill 骨架 | name/description（description 写法见模板内注释） |
+
+### 工程与发布
+
+| 模板 | 复制到单库 | 作用 | 复制后必改 |
+|---|---|---|---|
+| `repo-root/package.json` | 根 | 字段骨架（type: module / exports / **dsh 字段**（client half 必需：bundle.patch + client.inject + platform）/ peer/devDeps 规范，对齐两实践库） | 全部占位符 + 真实 peer/devDeps（见实践报告 §5.2）；纯 host 插件删除 `dsh` 字段；`test` 已指向 verify.mjs 单源 |
+| `repo-root/tsconfig.json` | 根 | IDE/typecheck 配置（noEmit） | 无（可选调 target/lib） |
+| `repo-root/tsconfig.build.json` | 根 | 构建配置（outDir lib + declaration） | 无 |
+| `repo-root/src/index.ts` | `src/index.ts` | host half 入口骨架（OBJECT form 默认导出 + 生命周期注释） | 替换为本插件能力；**OBJECT form 注释保留** |
+| `repo-root/src/config.ts` | `src/config.ts` | schemastery Config + resolveConfig 骨架 | 配置项（编译依赖 schemastery/@types/node 已预置在 devDeps） |
+| `repo-root/scripts/verify.mjs` | `scripts/verify.mjs` | **验证链单源入口**：build→typecheck→探测式 smoke/vitest/mount/client-mount | 无（探测式，接入即自动进链；visual 留作本地发布前门） |
+| `repo-root/scripts/build.mjs` | `scripts/build.mjs` | build 链探测包装：tsc 后按存在性跑 build-client.mjs（无 client 的库不再死在缺失脚本） | 无 |
+| `repo-root/scripts/check-deploy.mjs` | `scripts/check-deploy.mjs` | 部署纪律装后自检（单库/多包自适应） | 只核对默认 profile 名（脚本头部注释） |
+| `repo-root/.github/workflows/ci.yml` | `.github/workflows/ci.yml` | push(main)/PR 验证链（坏提交拦在进 main 当下，不等打 tag） | 无（与 publish.yml 同调 verify.mjs；action SHA 同步更新） |
+| `repo-root/.github/workflows/publish.yml` | `.github/workflows/publish.yml` | OIDC Trusted Publishing 发布流水线 | tag pattern、node 版本、可选 environment 审批门 |
+| `repo-root/.githooks/pre-commit` | `.githooks/pre-commit` | 部署纪律硬拦截 | 无（原样复制后 `git config core.hooksPath .githooks`） |
+| `scaffold.mjs` | **不随库分发**（模板集工具） | 一条命令完成阶段 2：复制 + 占位符替换 + 删模板注释 + git init/hooks + TODO 清单 | — |
+
+> 从零新建且有 client half 时需 `scripts/build-client.mjs`（client bundle）——与 client 格式
+> 强耦合，**从 `dsh-context-compass/scripts/build-client.mjs` 复制适配**，模板不固化；
+> `package.json` 的 build 经 `scripts/build.mjs` 探测包装，接入即生效，无 client 的库不受影响。
+> 纯 host 插件删除 package.json 的 `dsh` 字段；cordis.patch.yml 仅 client half 插件需要。
+
+## 明确不模板化的项
+
+| 项 | 处理方式 |
+|---|---|
+| `scripts/build-client.mjs` / smoke/mount 测试脚本 | **从参照库复制适配**（与 client bundle 格式、验证策略强耦合）；路由 A 第 8 步 |
+| `.githooks/commit-msg` | **本机私有，禁止入库**——只留本地 + `.gitignore` 已忽略 |
+| `cordis.patch.yml` | profile 自有但**随发布物分发**（package.json files 已引用）——按本 profile 实况填写，不模板化 |
+| `lib/`、`visual/baselines/` | 构建产物/实机基线，非模板 |
+
+## 已知限制（诚实标注）
+
+- `typecheck` 模板用严格版（`tsc -p tsconfig.json --noEmit`）；实践库实际带 `|| true` 宽松后缀（消化 SlotMap augmentation 双副本类报错的实战 hack）——从零起步建议先严格，遇到 augmentation 报错再按实践库放宽并注释原因
+- `tsconfig.build.json` 的 `allowImportingTsExtensions` + `declaration` 组合要求 TypeScript ≥ 5.7（模板 devDeps 已钉 `^5.7.0`）
+- DSH harness 的项目级 skills 目录机制未经验证（见 skill 模板注释）；agent 读取的 AGENTS.md 已由本会话实证有效
+- 首版 bootstrap 描述基于 2025-12 npm 新规的公开报道，发布当日以 npm 官方文档为准
+- 模板骨架未含 lockfile——脚手架产物首次 `npm install` 后**必须把 package-lock.json 入库**（CI npm ci 依赖；scaffold TODO 第 5 步与 ci.yml 头注释均有提示）
+- 客户端 bundle 格式（`__ModuleLoader__` 工厂）与宿主强耦合，build-client.mjs 不模板化；client half 插件的 `dsh` 字段值需按本库宿主包实际填写
+
+---
+
+## 路线 A：从零新建插件库（通用步骤）
+
+> 前提：宿主 dsh 可运行（本机 profile）、GitHub org 有建库权限、npm org 可发包。
+> 阶段划分的原则来自实践报告：**先跑通最小闭环，再补发布面；每版一个关注点**。
+
+### 阶段 1：契约预检（写代码之前）
+
+1. 明确插件要挂在 dsh 的哪一层（工具/命令/投影/设置页/Slot UI），列 host/client 各自做什么（两个 half 都想清楚）
+2. `cordis_inspect_list` → `cordis_inspect_query` 查清用到的 Service/Event/Builtin/Slot **精确签名**——不猜 API
+3. 记录要依赖的宿主包清单（决定 package.json 的 peer/devDeps）
+
+### 阶段 2：仓库脚手架（一条命令）
+
+4. **首选脚手架**：`node templates/scaffold.mjs --name <name> --org <org> --desc "<一句话>"`（缺省参数且 TTY 时交互问答；非 TTY 必须全旗标）——自动完成第 5-7 步的**本地部分**并打印手工 TODO 清单（**GitHub 建库、npm install 等远端/网络操作不在其中**，见 TODO 第 5/7 步）
+5. （手动替代）`gh repo create <org>/dsh-<name> --public`（public：provenance 需要；`--description "<一句话>"`）→ 本地 init → 复制 `repo-root/` 全部文件 → 逐文件替换占位符 → 删模板说明注释
+6. `package.json`：按阶段 1 的契约清单填 peerDependencies（宽 caret + 预发布下界）、peerDependenciesMeta、devDependencies（peer 同范围复制 + 运行时可达宿主包全量）
+7. `git config core.hooksPath .githooks` 启用 pre-commit；首次 `git grep` 机密自查后 commit
+
+### 阶段 3：最小实现闭环（先跑通再补齐）
+
+8. 复制适配 `scripts/build-client.mjs`（不做 client 的插件跳过）→ 写 `src/`（入口骨架 + config 骨架起步）→ `npm install --legacy-peer-deps` → build/typecheck 全绿
+9. 按 DEVELOPMENT.md 核心循环开发：Backlog → Sprint（契约预检）→ 实现 → **DoD 三段**；部署纪律遵守：`file:` 安装 + `check:deploy` PASS 才算改过源码
+10. 每个"类发布"节点跑完整验证链（build → typecheck → 测试 → mount；有 client 加 client-mount/visual）
+
+### 阶段 4：发布面补齐（首个公开版之前）
+
+11. 文档定稿：README 双语同步、DEVELOPMENT 速查表已积累、SECURITY 支持面写实
+12. `gh repo edit` 设 description + topics；GitHub community profile 检查（LICENSE/README/CONTRIBUTING/SECURITY）
+13. npmjs.com 配 Trusted Publisher（org/repo/`publish.yml` 文件名逐字段一致）；granular token 选不到未发布包 → **首版手动 `npm publish` bootstrap**，随后立即切 OIDC
+14. 首发验证：`npm view dsh-<name> dist-tags` + npm 页 provenance 徽章 + `npm audit signatures`
+
+### 阶段 5：例行发版（此后每版）
+
+15. `npm version <semver>` → push tag → CI 验证链 → （environment 审批门）→ 自动发布；灰度走 `--preid=next` 的 canary 通道（PUBLISHING.md 模板）
+16. 每版在 PUBLISHING.md 记一行（做了什么 + 为什么 + 怎么验证）；新坑进速查表
+
+## 路线 B：从 dsh-plugins monorepo 迁移（增量，在路线 A 基础上）
+
+前置与切库步骤（subtree split、拉历史、推仓库）**见 `DSH-PLUGIN-STANDALONE-MIGRATION.md` §3**，
+本模板集只覆盖迁移后的"规范化"增量：
+
+1. 迁移后仓库已有 src/lib/package.json —— 复制本模板集**文档与治理文件**（README/LICENSE/CONTRIBUTING/DEVELOPMENT/PUBLISHING/SECURITY/AGENTS/CLAUDE/.gitignore）
+2. 对照模板补工程文件：`.github/workflows/publish.yml`（monorepo 时代的已在封版仓删除）、`tsconfig*.json`、`.githooks/pre-commit`、`scripts/check-deploy.mjs`（参照库复制或用本模板，核对 `localSrcFor()` 单库分支）
+3. 全局 `grep -rn "dsh-plugins"` 清旧引用（src 默认数据 URL **发版前必改**；package.json repository/homepage/bugs 指向新库——OIDC/provenance 依赖）
+4. rebuild lib → 验证链全绿 → `git grep` 机密自查 → npm 配 Trusted Publisher → tag 发布
+5. 迁移后按迁移文档 §9 分版本推进（v+1 宿主适配/URL 修正，v+2 规范化，v+3+ 功能）
+
+## 两路线共同的红线（模板已内建，勿删）
+
+- **OBJECT form 默认导出**（`src/index.ts` 模板注释）——工厂写法被静默忽略
+- **部署纪律**（AGENTS.md 5 条 + DEVELOPMENT.md 全文 + pre-commit + check-deploy）——同版本号不同内容事故的唯一拦截链
+- **机密不入库**——`.gitignore` 模板已忽略 HANDOFF/commit-msg；提交前 `git grep -nE '/home/[a-z]|/mnt/[a-z]|/Users/[a-z]'`
+- **验证链单源**——package.json `test`、ci.yml 与 publish.yml 都只调 `scripts/verify.mjs`（结构保证，非纪律约束）；链内增删步骤只改 verify.mjs
+
+## 将来可选：GitHub template repo
+
+模板集成熟（≥2 个插件用 scaffold.mjs 建库跑通）后，可把 `templates/repo-root/` 推成独立
+GitHub 仓库并勾选 Settings → "Template repository"，即可用 "Use this template" 一键建库；
+scaffold.mjs 的占位符替换则由 GitHub 变量或首次 commit 后的 sed 替代。本步为可选项，
+当前双文件模板（templates/ + scaffold.mjs）已够用。