repo-audit-tool 1.2.0

package/templates/categories/product-oss/SUPPORT.md

@@ -0,0 +1,71 @@
+<!-- 模板说明（用后删除）：本文件是 B 类"产品/多人协作 OSS"分类共性文档（语言无关），
+     与语言基类（python-app / go-service / dsh-plugin）叠加使用。
+     语言基类管"怎么构建验证"，本文件管"怎么协作发布"。
+     依据：docs.github.com（rulesets/merge queue/CODEOWNERS/issue forms/auto-merge）+
+     googleapis/release-please v5 + docs.pypi.org 安全模型，2026-09 核实。 -->
+
+# 分类共性：产品级多人协作 OSS
+
+> 实证特征：PR 流（Merge PR 实证）、CHANGELOG、ROADMAP、双语 README、评审/审计文档入库。
+> 核心差异 vs 个人单维护者库：**变更经 PR、发布经 Release 流、事实经 CHANGELOG/release-please 单源**。
+
+## 文件层（overlay 已随本目录提供，scaffold `--overlay product-oss` 自动叠加）
+
+| 文件 | 作用 | 备注 |
+|---|---|---|
+| `CHANGELOG.md` | 变更唯一事实源（Keep a Changelog 分类） | release-please 自动维护；手工模式则并入手写 |
+| `.github/PULL_REQUEST_TEMPLATE.md` | PR 自检清单（验证链/机密/文档/兼容性） | — |
+| `.github/ISSUE_TEMPLATE/bug_report.yml` + `config.yml` | YAML issue forms（复现步骤/环境）+ 私密漏洞报告指路 | blank_issues_enabled: false |
+| `.github/CODEOWNERS` | 评审责任人锁定（自身必须有 owner） | 开 "Require review from Code Owners" 后任一 owner 批准即满足 |
+| `.github/dependabot.yml` | 依赖与 action 自动升级（minor/patch 成组） | ecosystem 按语言基类增删 |
+| `.github/workflows/release-please.yml` + `release-please-config.json` + `.release-please-manifest.json` | **版本晋升自动化**：conventional commits → 自动 Release PR → 合并即打 tag + GitHub Release + CHANGELOG | manifest 首版手写当前版本，此后勿手改 |
+| `.github/workflows/dependency-review.yml` | PR 依赖安全审查（fail-on-severity: high 起步） | — |
+
+## 发布分工（关键！避免撞车）
+
+- **release-please** 管**版本晋升**：算 next version、开 Release PR、维护 CHANGELOG、合并时打 tag + 发 GitHub Release
+- **语言基类的 publish/release 工作流**（npm OIDC / PyPI TP / GoReleaser）管**制品构建上传**，被 release-please 打的 tag 触发
+- ⚠️ 不要让两边同时建 GitHub Release：GoReleaser 检测到 Release 已存在会更新（不撞车）；npm/PyPI 的 pypa/npm publish 只传包不建 Release（不冲突）
+- GITHUB_TOKEN 限制：release-please 用它建的事件不再触发其他 workflow——依赖 tag 触发发布（默认架构）就无需 PAT；要"Release PR 合并后直接 publish"才换 PAT
+
+## 与单人库的红线差异
+
+- 单人库"直提 main"的 pre-commit 门禁 → **PR 门禁**（ci.yml 必须 required check）
+- pre-commit 部署纪律钩子仍随库分发；贡献者无法跑 check:deploy（无本机 profile）时 PR 说明注明，由维护者发版前代跑
+
+## 单人直提 main → 多人 PR 协作：升级检查清单
+
+> 来源：docs.github.com rulesets/protected-branches/merge queue/auto-merge 官方文档（2026-09 核实）。
+> 分支保护建议用 **rulesets**（GitHub 演进方向：多 ruleset 叠加取最严、可 Evaluate/Active 启停、支持一键从 classic 保护迁移）。
+
+### A. 仓库 General
+1. Pull Requests：只留 **squash merging**；勾 **Automatically delete head branches**、**Allow auto-merge**
+2. Actions → General：勾 **Allow GitHub Actions to create and approve pull requests**（release-please 必需）
+3. Collaborators：协作者给 write 及以上（CODEOWNERS 与 required approvals 的前提）
+
+### B. Rulesets（Settings → Rules → Rulesets → Branch ruleset，目标 `~DEFAULT_BRANCH`）
+4. Require a pull request before merging：Required approvals = 1（≥2 人后升 2）；勾 Dismiss stale approvals、Require review from Code Owners、Require conversation resolution
+5. Require status checks：加入 CI check 名（**check 名须全局唯一**）；初期勾 Require branches to be up to date（strict）
+6. Require linear history（与 squash 配套）
+7. Bypass list：加 `release-please[bot]`、`dependabot[bot]`；多人期给 admin 勾 **Do not allow bypassing**
+8. 温和上线：先用 **Evaluate** 模式跑几天再切 Active
+
+### C. 文件层
+9. CODEOWNERS / ISSUE_TEMPLATE / dependabot.yml / release-please 三件套 / dependency-review.yml——overlay 已含
+10. SECURITY.md + Settings → Code security → **Private vulnerability reporting**（与 SECURITY.md 是两套机制，都要有）
+
+### D. 安全面默认
+11. Secret scanning / push protection：公共仓免费，开启（push protection 对个人账号默认已拦截）
+12. Dependabot alerts / security updates：公共仓默认开，确认即可
+
+### E. 流程习惯（非配置）
+13. Conventional Commits + commitlint CI 校验（release-please 的地基）
+14. merge queue：**暂不开**——每天个位数 PR 用 strict required checks + auto-merge 足够；高频合并后再把规则 5 的 strict 换成 merge queue（避免双重等待）
+
+### 补充事实（2026-09 核实）
+
+- classic branch protection 仍可用，但官方提供一键 "Convert to ruleset" 迁移，新配置直接用 rulesets
+- release-please-action 最新 **v5.0.0**（2026-04-22，breaking 仅 node24）；核心库 release-please v17.11.2
+- actions/stale v11 仍活跃维护；只对 issue 温和开启（days-before-pr-stale: -1 等价于不对 PR 启用）
+- CODEOWNERS：gitignore 风格但不支持 `!` 取反与 `[ ]` 范围；owner 须 write 权限
+- 0.x 阶段：config 里 `bump-minor-pre-major: true` 已预置（feat 只升 minor，避免 0.x 跳 1.x）

package/templates/categories/product-oss/release-please-config.json

@@ -0,0 +1,10 @@
+{
+  "release-type": "node",
+  "packages": {
+    ".": {}
+  },
+  "include-component-in-tag": false,
+  "bump-minor-pre-major": true,
+  "separate-pull-requests": false,
+  "group-pull-request-title-pattern": "chore(main): release ${version}"
+}

package/templates/categories/python-app/.githooks/pre-commit

@@ -0,0 +1,13 @@
+#!/bin/sh
+# 验证链前门（Python 版）：提交时强制 ruff + pytest（scripts/verify.py 单源）。
+# 启用方式：git config core.hooksPath .githooks
+# 依赖：本地 venv 已激活或 python 环境含 ruff/pytest（未就绪时 --no-verify 并注明）。
+
+echo "pre-commit：执行验证链 python3 scripts/verify.py ..."
+python3 scripts/verify.py
+code=$?
+if [ $code -ne 0 ]; then
+  echo ""
+  echo "✗ 验证链 FAIL：修复后重试；确属中间态请 commit --no-verify 并在说明注明。"
+  exit 1
+fi

package/templates/categories/python-app/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+# Python CI（push/PR 验证）
+#
+# 验证链单源：scripts/verify.py（ruff → pytest 探测式）——本地与 CI 同一入口。
+# 首推前置：无 lockfile 时首次安装生成 requirements 锁（如 pip-compile）再入库，可选。
+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 Python
+        uses: actions/setup-python@<commit-SHA> # actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: pip
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Verify
+        run: python scripts/verify.py

package/templates/categories/python-app/.github/workflows/publish.yml

@@ -0,0 +1,112 @@
+# Python 发布工作流（PyPI Trusted Publishing）
+#
+# 信任链：tag v* → build job（版本守卫 + python -m build + twine check）→
+#   PyPI publish job（OIDC Trusted Publishing，自动 PEP 740 attestations）
+# 要点（2026-09 官方文档核实）：
+# - 构建必须在独立 build job——PyPA guide 原话 "Building distributions in a publishing
+#   job is unsupported"；publish job 只做"下载 artifact + 上传"
+# - permissions 工作流级清零，id-token: write 只放 publish job（最小化）
+# - TestPyPI 走 workflow_dispatch 手动触发（验证发布链路用；TestPyPI 独立账号+独立配置）
+# - 不加 skip-existing：PyPI 禁文件名复用，且 release 14 天后冻结——失败换新版本号重发
+# - attestations 默认开启，无需额外签名步骤
+name: publish
+
+on:
+  push:
+    tags: ['v*.*.*']
+  workflow_dispatch: {}   # 手动触发时只发 TestPyPI（验证链路）
+
+permissions: {}
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: 构建发行包（sdist + wheel）
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@<commit-SHA> # actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Setup Python
+        uses: actions/setup-python@<commit-SHA> # actions/setup-python@v7
+        with:
+          python-version: '3.12'
+      - name: 版本一致性守卫（tag ↔ pyproject.toml 静态版本）
+        run: |
+          python - <<'PY'
+          import os, re, sys, tomllib
+          tag = os.environ["GITHUB_REF_NAME"]
+          m = re.fullmatch(r"v(\d+(?:\.\d+)+(?:[.-]?[a-zA-Z0-9.]+)?)", tag)
+          if not m:
+              sys.exit(f"::error::tag '{tag}' 不符合 vX.Y.Z 约定")
+          expected = m.group(1)
+          with open("pyproject.toml", "rb") as f:
+              data = tomllib.load(f)
+          actual = data.get("project", {}).get("version")
+          if actual is None:
+              sys.exit("::error::pyproject.toml 无静态 version；动态版本请改用『构建后比对 dist 文件名』守卫（见下注释）")
+          if actual != expected:
+              sys.exit(f"::error::版本不一致：tag {tag} vs pyproject.toml {actual}")
+          print(f"版本一致：{actual}")
+          PY
+        # ▸ 动态版本（dynamic = ["version"]）替代：移到 python -m build 之后，比对产物文件名：
+        #   glob "dist/*-{GITHUB_REF_NAME[1:]}.tar.gz" 不存在即失败（最通用，绕开版本来源差异）
+      - name: 构建 sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: twine check（pypa action 上传前也会校验；此处尽早失败）
+        run: |
+          python -m pip install twine
+          python -m twine check dist/*
+      - name: 上传构建产物
+        uses: actions/upload-artifact@<commit-SHA> # actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-testpypi:
+    name: 发布到 TestPyPI（仅手动触发）
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/<name>
+    permissions:
+      id-token: write          # Trusted Publishing 必需
+    steps:
+      - name: 下载构建产物
+        uses: actions/download-artifact@<commit-SHA> # actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: 发布到 TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1   # 2026-07 当前 v1.14.2；可 pin 到 tag/SHA
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: 发布到 PyPI（tag 触发；environment 需配 required reviewers）
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi               # GitHub Settings → Environments：required reviewers 必开
+      url: https://pypi.org/p/<name>
+    permissions:
+      id-token: write          # Trusted Publishing；attestations 默认生成
+    steps:
+      - name: 下载构建产物
+        uses: actions/download-artifact@<commit-SHA> # actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: 发布到 PyPI（自动 PEP 740 attestations）
+        uses: pypa/gh-action-pypi-publish@release/v1

package/templates/categories/python-app/AGENTS-append.md

@@ -0,0 +1,18 @@
+<!-- ===== append：python-app 分类纪律（拼接到 AGENTS-core 之后） ===== -->
+
+## 环境与验证纪律（本分类硬性）
+
+1. **环境声明**：一切命令在项目 venv 内执行（`python -m venv .venv && . .venv/bin/activate` 后 `pip install -e ".[dev]"`）；不依赖全局解释器包状态。CI 与本地同命令（`scripts/verify.py` 单源）。
+2. **提交前门**：`python scripts/verify.py`（ruff → pytest，探测式）全绿；pre-commit 钩子自动执行（启用：`git config core.hooksPath .githooks`）。
+3. 数据文件入 `data/` 前先确认无敏感字段（机密红线见上方 AI 协作守则第 3 条）。
+
+
+
+
+- （升级验证）guide 手册回归项。
+
+6. （闭环实测）模板升级新条款。
+
+7. （闭环实测 v2）第二轮升级。
+
+6. （闭环终测）模板升级 A。

package/templates/categories/python-app/CATEGORY.md

@@ -0,0 +1,34 @@
+<!-- 模板说明（用后删除）：C 类"Python 应用/研究"分类 delta 模板（语言基类）。
+     叠加规则：repo-root 的**通用文档层**（README/LICENSE/CONTRIBUTING/DEVELOPMENT/PUBLISHING/
+     SECURITY/AGENTS/CLAUDE/.gitignore 基干 + skill/）照用；npm/TS 专属文件（package.json/
+     tsconfig*/src TS 骨架/scripts/*.mjs/workflows）由本分类替代。 -->
+
+# C 类 · Python 应用/研究（语言基类）
+
+> 实证来源：chumen / shisui / shuijing-v2 / vertical-small-model（pyproject + src/tests 同构）。
+
+## 文件 delta（相对 repo-root 基类）
+
+| 动作 | 文件 | 说明 |
+|---|---|---|
+| **替换** | `pyproject.toml`（本目录提供骨架） | 取代 package.json：PEP 621 元数据 + 工具配置单源 |
+| **替换** | `src/<name>/__init__.py`（**自建**，TODO 有指引） | 取代 TS 骨架；src 布局，scaffold 不生成代码文件 |
+| **替换** | `.github/workflows/ci.yml`、`publish.yml`（本目录提供） | pytest/ruff 验证链；publish 用 **PyPI Trusted Publishing（OIDC）**——与 npm 同信任链模型 |
+| **删除** | package.json / tsconfig* / scripts/*.mjs / src/index.ts / cordis.patch.yml / dsh 字段 | npm/TS 专属 |
+| **保留** | 通用文档层 + `.githooks/pre-commit` | 钩子内命令改为 `python -m pytest`（见本目录 pre-commit delta） |
+
+## 验证链（对应 verify.mjs 的 Python 单源）
+
+```sh
+# scripts/verify.py（或 Makefile target）：
+ruff check . → python -m pytest tests/ -q
+# 探测式：tests/ 存在才跑 pytest；deploy 场景（shuijing-v2）加 docker build 校验（本地前门，不进 CI）
+```
+
+## 与 dsh 插件基类的红线差异
+
+- **无部署纪律**（无 dsh profile/file: 安装）——AGENTS.md 去掉该 5 条，改为：venv/uv 环境声明、
+  `pip install -e ".[dev]"`、机密不入库（保留）、提交前 `ruff check + pytest`（保留）
+- **发布面**：PUBLISHING.md 换成 PyPI 版（trusted publisher / 版本策略同款；无 npm provenance 概念，
+  用 PyPI "Trusted Publishing" + attestations）
+- README 徽章换 PyPI / CI / License；安装段 `pip install <pkg>`

package/templates/categories/python-app/CONTRIBUTING-append.md

@@ -0,0 +1,13 @@
+<!-- ===== append：python-app 分类段（拼接到 CONTRIBUTING-core 之后） ===== -->
+
+## 开发环境
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+python -m pip install -e ".[dev]"
+python scripts/verify.py   # 验证链单源：ruff → pytest（探测式，tests/ 就位后自动进链）
+```
+
+## 发版流程
+
+见 [PUBLISHING.md](PUBLISHING.md)（bump-my-version 或手工 tag → PyPI Trusted Publishing 发布）。

package/templates/categories/python-app/DEVELOPMENT-append.md

@@ -0,0 +1,21 @@
+<!-- ===== append：python-app 分类段（拼接到 DEVELOPMENT-core 之后） ===== -->
+
+## 分类纪律：Python 实现规范
+
+- 包布局：src/（pyproject packages 已指向 `src/<name>`）；入口逻辑收敛，测试放 `tests/`
+- 类型与风格：ruff（E/F/I/UP/B）必须零告警；公共函数带类型注解
+- 配置：schemastery 或 dataclass + 防御性解析（partial 配置也能得到完整结果，参照 src config 惯例）
+- 提交前门：`python scripts/verify.py`（ruff → pytest，探测式）全绿；pre-commit 钩子已指向它
+
+## 分类 DoD 补充（Python）
+
+- [ ] ruff 零告警；pytest 全绿（tests/ 就位后自动进验证链）
+- [ ] 发布前 `python -m build && twine check dist/*` 通过（如发布）
+- [ ] 依赖变更同步 pyproject；lock（如用 uv/pip-compile）入库
+
+## 速查表预置（回顾追加）
+
+| 坑 | 症状 | 拦截环节 |
+|---|---|---|
+| 占位依赖没填就 npm/pip install | EINVALIDPACKAGENAME / Cannot find module | 脚手架 TODO 第 1 步 + CONTRIBUTING 首装提示 |
+| 发布后改 pyproject version 不同步 tag | CI 版本守卫 FAIL | publish.yml 版本一致性守卫 |

package/templates/categories/python-app/PUBLISHING-append.md

@@ -0,0 +1,52 @@
+<!-- ===== append：python-app 分类段（拼接到 PUBLISHING-core 之后） ===== -->
+
+## 发布通道（PyPI Trusted Publishing）
+
+**认证**：PyPI **Trusted Publishing（OIDC）**——无 token，`id-token: write` 换发 15 分钟短命
+项目 token；上传自动带 **PEP 740 attestations**（Sigstore，PyPI 项目页显示 provenance）。
+**前置验证**：ci.yml（ruff → pytest）把住质量关；publish 只做构建与上传（build/publish 分离是
+PyPA guide 硬要求）。
+
+## 日常发布流程
+
+```sh
+# ① bump（版本静态在 pyproject.toml；推荐 bump-my-version 一条命令 commit+tag）
+pip install bump-my-version
+bump-my-version bump patch        # 自动改 pyproject version + commit + 打 vX.Y.Z tag
+# 或手工：改 pyproject.toml version → commit → git tag vX.Y.Z
+
+# ② push（发布是人的决定：tag 推送触发 publish.yml）
+git push && git push --tags       # CI：构建守卫 → build → pypi 环境（人工批准）→ 上传
+```
+
+- **守卫**：CI 比 tag 与 pyproject 静态 version 一致性（动态版本项目用 dist 文件名比对，见 publish.yml 注释）
+- **灰度**：先 `workflow_dispatch` 手动跑 TestPyPI 验证链路；`pip install --index-url https://test.pypi.org/simple/` 实测
+- **发布失败**：大声失败换新版本号重发——**不要**加 skip-existing（PyPI 禁文件名复用；release 14 天后冻结新文件）
+
+## 首次发布前置（一次性）
+
+1. **GitHub Environments**：建 `pypi`（**必开 required reviewers**——PyPA guide 强调每次运行都需
+   人工批准）与 `testpypi`
+2. **pending publisher 登记**（先建配置后建项目）：账号侧 `https://pypi.org/manage/account/publishing/`
+   填项目名 + owner/repo + workflow 文件名 `publish.yml` + environment `pypi`；首次发布成功自动建项目。
+   ⚠️ pending 不保留项目名，发布前被抢注则失效。TestPyPI 单独重复（独立账号）
+3. （建议）tag protection：限制 `v*` tag 只能由维护者推送
+
+## 应急手动发布（CI 不可用时）
+
+```sh
+python scripts/verify.py && python -m build && twine check dist/*
+# 需 API token 兜底（TP 不可用时）：PyPI 账号建 API token（用户名 __token__），本地 twine upload dist/*
+```
+
+## 维护要点
+
+- **offboarding 维护者**：审查 Trusted Publishers（TP 绑定项目而非用户）与 GitHub environment reviewers
+- **版本工具**：小库推荐静态 pyproject + bump-my-version；setuptools-scm（tag 即真相源）tag 密集项目才值得
+- **依赖更新**：Dependabot 保持 action 版本（含 pypa/gh-action-pypi-publish 的 release/v1 跟踪）
+
+## 参考来源（2026-09 核实）
+
+- docs.pypi.org/trusted-publishers/（含 security-model / creating-a-project-through-oidc）
+- packaging.python.org GitHub Actions 发布指南 · pypa/gh-action-pypi-publish v1.14.2（master 已 sunset，用 @release/v1）
+- blog.pypi.org（2025 年度回顾 / "14 天冻结"公告）

package/templates/categories/python-app/PUBLISHING.md

@@ -0,0 +1,61 @@
+# 发布记录：<repo>（Python / PyPI）
+
+**发布通道**：PyPI **Trusted Publishing（OIDC）**——无 token，`id-token: write` 换发 15 分钟短命
+项目 token；上传自动带 **PEP 740 attestations**（Sigstore，PyPI 项目页显示 provenance）。
+**前置验证**：ci.yml（ruff → pytest）把住质量关；publish 只做构建与上传。
+
+## 发布状态（<日期> 更新）
+
+| 项 | 状态 |
+|---|---|
+| PyPI | <版本 / latest> |
+| TestPyPI | <测试通道验证记录> |
+| 本地验证 | <verify.py 全绿 + pip install 实测> |
+
+## 一次性前置（首次发布前）
+
+1. **GitHub Environments**：Settings → Environments 建 `pypi`（**必开 required reviewers**——
+   PyPA guide 强调 "you must require manual approval on each run"）与 `testpypi`
+2. **pending publisher 登记**（先建配置后建项目）：账号侧 `https://pypi.org/manage/account/publishing/`
+   填项目名 + owner/repo + workflow 文件名 `publish.yml` + environment `pypi`；首次发布成功自动建项目。
+   ⚠️ pending 不保留项目名，发布前被抢注则失效。TestPyPI 在 test.pypi.org 单独重复（独立账号）
+3. （建议）tag protection：限制 `v*` tag 只能由维护者推送
+4. 本地演练：`python -m build && twine check dist/*`
+
+## 日常发布流程
+
+```sh
+# ① bump（版本静态在 pyproject.toml；推荐 bump-my-version 一条命令 commit+tag）
+pip install bump-my-version
+bump-my-version bump patch        # 自动改 pyproject version + commit + 打 vX.Y.Z tag
+# 或手工：改 pyproject.toml version → commit → git tag vX.Y.Z
+
+# ② push（发布是人的决定：tag 推送触发 publish.yml）
+git push && git push --tags       # CI：构建守卫 → build → TestPyPI 跳过 → pypi 环境（人工批准）→ 上传
+```
+
+- **守卫**：CI 比 tag 与 pyproject 静态 version 一致性（动态版本项目用 dist 文件名比对，见 publish.yml 注释）
+- **灰度**：先 `workflow_dispatch` 手动跑 TestPyPI 验证链路；`pip install --index-url https://test.pypi.org/simple/` 实测
+- **发布失败**：大声失败换新版本号重发——**不要**加 skip-existing（PyPI 禁文件名复用；release 14 天后冻结新文件）
+- 发布成功验证：PyPI 项目页 provenance/attestations 徽章 + `pip install <pkg>` 实测
+
+## 应急手动发布（CI 不可用时）
+
+```sh
+python scripts/verify.py && python -m build && twine check dist/*
+# 需 API token 兜底（TP 不可用时）：PyPI 账号建 API token（用户名 __token__），
+# 本地 twine upload dist/* —— 上传后仍建议补跑一次 CI 发布以恢复 attestations 链路
+```
+
+## 维护要点
+
+- **offboarding 维护者**：审查 Trusted Publishers（TP 绑定项目而非用户）与 GitHub environment reviewers
+- **版本工具**：小库推荐静态 pyproject + bump-my-version；hatch version 适合动态版本（`__about__.py`）；setuptools-scm（tag 即真相源）tag 密集项目才值得
+- **依赖更新**：Dependabot 保持 action 版本（含 pypa/gh-action-pypi-publish 的 release/v1 跟踪）
+
+## 参考来源（2026-09 核实）
+
+- docs.pypi.org/trusted-publishers/（含 security-model / creating-a-project-through-oidc）
+- packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+- github.com/pypa/gh-action-pypi-publish（v1.14.2 README；master 已 sunset，用 @release/v1）
+- blog.pypi.org（2025 年度回顾 / 2026-07 "14 天冻结"与 UI 更新公告）

package/templates/categories/python-app/README-append.md

@@ -0,0 +1,27 @@
+<!-- ===== append：python-app 分类段（拼接到 README-core 之后） ===== -->
+
+[![PyPI](https://img.shields.io/pypi/v/<name>.svg)](https://pypi.org/project/<name>/)
+
+
+
+- <功能点 1：一句话说清用户得到什么>
+- <功能点 2>
+
+## 安装
+
+> 要求 Python >= 3.11（见 pyproject.toml requires-python）。
+
+```sh
+pip install <name>
+# 开发：python -m venv .venv && . .venv/bin/activate && pip install -e ".[dev]"
+```
+
+## 使用
+
+<最小可复制示例：CLI 命令 / import 调用。示例代码块必须可直接粘贴执行。>
+
+## 配置
+
+| 配置项 | 默认 | 说明 |
+|---|---|---|
+| `<field>` | `<default>` | <作用与生效方式（live / 重启生效）> |

package/templates/categories/python-app/README.en.md

@@ -0,0 +1,44 @@
+# <name>
+
+[![PyPI](https://img.shields.io/pypi/v/<name>.svg)](https://pypi.org/project/<name>/)
+
+<One-line English description>（与中文版 README 首句同义）.
+
+[中文](README.md) ｜ English is a mirror; the Chinese README is authoritative and may lag behind.
+
+## Features
+
+- <Feature 1>
+- <Feature 2>
+
+## Install
+
+> Requires Python >= 3.11 (see `requires-python` in pyproject.toml).
+
+```sh
+pip install <name>
+# Development: python -m venv .venv && . .venv/bin/activate && pip install -e ".[dev]"
+```
+
+## Usage
+
+<Minimal copy-paste example: CLI command / import call.>
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `<field>` | `<default>` | <What it does; live or requires restart> |
+
+## Docs
+
+- [Design](docs/DESIGN.md) <!-- remove this line if no docs/ directory -->
+- [Development & verification discipline](DEVELOPMENT.md) · [Publishing](PUBLISHING.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). AI collaborators read [AGENTS.md](AGENTS.md) first (AI-collaboration rules).
+
+## License
+
+[MIT](LICENSE)

package/templates/categories/python-app/gitignore-append.md

@@ -0,0 +1,19 @@
+# ===== append：python-app 分类忽略（拼接到通用段之后） =====
+
+# 本机私有钩子（commit-msg 含身份检查）不追踪；pre-commit 随仓库分发
+.githooks/commit-msg
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/

package/templates/categories/python-app/pyproject.toml

@@ -0,0 +1,41 @@
+# <name>（Python）
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "<name>"
+version = "0.1.0"
+description = "<一句话描述>"
+license = { text = "MIT" }
+authors = [{ name = "<org>" }]
+requires-python = ">=3.11"
+dependencies = [
+  # 运行时依赖按契约预检结果填
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/<org>/<repo>#readme"
+Repository = "https://github.com/<org>/<repo>.git"
+Issues = "https://github.com/<org>/<repo>/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/<name>"]   # src 布局：包目录 src/<name>/（自建，含 __init__.py）
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

package/templates/categories/python-app/scripts/verify.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""验证链单源入口（Python 版 verify.mjs）：ruff → pytest（探测式）。
+
+package 无构建期 npm 段；链内增删步骤只改本文件。
+退出码：任一步 FAIL = 1（发布前门）。工具未安装时提示先建环境而非裸 traceback。
+"""
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+steps = [["ruff", "check", "."]]
+if (ROOT / "tests").exists():
+    # pytest 走 PATH 上的可执行（与 ruff 同源，venv 内一致）；不用 sys.executable -m，
+    # 否则 PATH stub/隔离环境无法统一拦截
+    steps.append(["pytest", "tests/", "-q"])
+# 探测式扩展点：deploy 校验（如 docker build）为本地发布前门，不进 CI——按需自行追加
+
+# 工具可用性前置检查：缺工具 = SKIP 语义（exit 2，不阻塞 update 的 adopt/commit），
+# 区别于"工具在但验证失败"（exit 1，阻塞）
+missing = sorted({s[0] for s in steps if shutil.which(s[0]) is None and s[0] != sys.executable})
+if missing:
+    print(f"△ 验证链工具未安装：{', '.join(missing)}——跳过门禁（SKIP）")
+    print("  → 先建环境：python -m venv .venv && . .venv/bin/activate && pip install -e \".[dev]\"")
+    sys.exit(2)
+
+print(f"验证链（verify.py 单源）：{' → '.join(s[0] for s in steps)}\n")
+
+for step in steps:
+    r = subprocess.run(step, cwd=ROOT)
+    if r.returncode != 0:
+        print(f"\n✗ [FAIL] {step[0]}（exit {r.returncode}）——验证链中断，禁止发布")
+        sys.exit(1)
+    print(f"✓ [PASS] {step[0]}")
+
+print(f"\n验证链全绿（{len(steps)} 步）。")

package/templates/categories/sandbox/AGENTS-append.md

@@ -0,0 +1,7 @@
+<!-- ===== append：sandbox 分类纪律（拼接到 AGENTS-core 之后，3 条） ===== -->
+
+## 沙盒纪律
+
+1. **master 直提，无 CI 无发布**：不打 tag、不发 npm/PyPI；验证靠本地跑通（提交规范与机密红线仍适用）。
+2. **收尾闭环**：实验结束必须在 README「结论」节写验证结果。
+3. **转正路径**：需要发布/协作时走 `scaffold.mjs` 目标分类全量脚手架迁移，**不在本仓打补丁凑规范**。