repo-audit-tool 1.2.0

package/README.en.md

@@ -0,0 +1,71 @@
+# repo-audit
+
+> **Repository Standardization Audit Tool + Engineering Scaffold Generator**
+
+Audits repositories against industrial best practices (zero npm dependencies, single-file pure Node.js ESM) and generates compliant engineering scaffolds from templates.
+
+## ✨ Features
+
+- **Zero dependencies**: Single `repo-audit.mjs` file, pure Node.js ESM, no `npm install` required
+- **Cross-platform**: Built-in launchers for Windows (`.cmd` / `.ps1`) and Linux/macOS (`.sh`)
+- **Auto-classification**: Scores file structure to detect 18 repository types (dsh-plugin / python-app / go-service / content / sandbox / archive, etc.)
+- **Extensible rules**: YAML rules in `rules/`, covering 5 dimensions (docs / git / quality / security) + category-specific rules
+- **Monorepo awareness**: Auto-detects workspace layouts (`apps/*` / `packages/*`, etc.)
+- **Repo-level waivers**: `.auditrc.yaml` declares known-accepted findings to prevent alert fatigue
+- **Optional LLM enhancement**: Supports 15+ providers (OpenAI / Anthropic / DeepSeek / Qwen / GLM / OpenRouter, etc.)
+- **Read-only safety**: Does not modify any files in the audited repository
+
+## 📦 Quick Start
+
+### Audit a repository
+
+```bash
+# Direct run (Linux/macOS)
+./shim/repo-audit.sh --repo /path/to/repo
+
+# Or with node
+node repo-audit.mjs --repo /path/to/repo --format json
+
+# Windows
+shim\repo-audit.cmd --repo C:\path\to\repo
+```
+
+### Generate a scaffold
+
+```bash
+node templates/scaffold.mjs --type dsh-plugin --name my-plugin --org my-org --desc "Plugin description"
+```
+
+## 🏗️ Directory Structure
+
+```
+repo-audit/
+├── repo-audit.mjs          # Core audit engine (single file, zero deps)
+├── rules/                  # Audit rules (YAML)
+│   ├── domains/            # Cross-dimension rules (docs/git/quality/security)
+│   └── categories/         # Category-specific rules (dsh-plugin/python-app/...)
+├── shim/                   # Cross-platform launchers
+├── templates/              # Engineering scaffold templates + generator
+├── docs/repo-audit/        # User manuals (AGENT-GUIDE + HUMAN-GUIDE)
+├── AUDIT.md                # Audit methodology
+├── BEST-PRACTICES.md       # Best practices reference
+├── REPO-CLASSIFICATION.md  # Classification detection guide
+└── REPO-AUDIT.md           # Tool overview
+```
+
+## 📚 Documentation
+
+- [Human Guide](docs/repo-audit/HUMAN-GUIDE.md) — Full usage documentation
+- [Agent Guide](docs/repo-audit/AGENT-GUIDE.md) — Machine-readable operation protocol
+- [Audit Methodology](AUDIT.md)
+- [Best Practices](BEST-PRACTICES.md)
+
+## 🛠️ Development
+
+- Audit rules: Edit `rules/domains/*.yaml` (cross-dimension) or `rules/categories/*.yaml` (category-specific)
+- New categories: Add `<type>.yaml` to `rules/categories/`, or extend via `REPO_AUDIT_TYPES` env var
+- Custom rules: `--rules my-rules.yaml` parameter
+
+## 📄 License
+
+MIT © 2026 NinjaSln-labs

package/README.md

@@ -0,0 +1,71 @@
+# repo-audit
+
+> **仓库标准化审计工具 + 工程脚手架生成器**
+
+对仓库进行工业级最佳实践审计（无需 npm 依赖的纯 Node.js ESM 单文件），并支持从模板生成符合规范的工程脚手架。
+
+## ✨ 特性
+
+- **零依赖**：单个 `repo-audit.mjs` 文件，纯 Node.js ESM，无需 `npm install`
+- **跨平台**：内置 Windows（`.cmd` / `.ps1`）、Linux/macOS（`.sh`）启动器
+- **自动分类**：基于文件结构评分检测 18 种仓库类型（dsh-plugin / python-app / go-service / content / sandbox / archive 等）
+- **可扩展规则**：`rules/` 目录下 YAML 规则，支持 5 大维度（docs / git / quality / security）+ 分类专属规则
+- **Monorepo 感知**：自动探测 workspace 布局（`apps/*` / `packages/*` 等）
+- **仓库级豁免**：`.auditrc.yaml` 声明已知接受的发现，避免「狼来了」效应
+- **可选 LLM 增强**：支持 15+ 提供商（OpenAI / Anthropic / DeepSeek / Qwen / GLM / OpenRouter 等）
+- **只读安全**：不修改被审计仓库任何文件
+
+## 📦 快速开始
+
+### 审计仓库
+
+```bash
+# 直接运行（Linux/macOS）
+./shim/repo-audit.sh --repo /path/to/repo
+
+# 或用 node
+node repo-audit.mjs --repo /path/to/repo --format json
+
+# Windows
+shim\repo-audit.cmd --repo C:\path\to\repo
+```
+
+### 生成脚手架
+
+```bash
+node templates/scaffold.mjs --type dsh-plugin --name my-plugin --org my-org --desc "插件描述"
+```
+
+## 🏗️ 目录结构
+
+```
+repo-audit/
+├── repo-audit.mjs          # 核心审计引擎（单文件，零依赖）
+├── rules/                  # 审计规则（YAML）
+│   ├── domains/            # 跨维度规则（docs/git/quality/security）
+│   └── categories/         # 分类专属规则（dsh-plugin/python-app/...）
+├── shim/                   # 跨平台启动器
+├── templates/              # 工程脚手架模板 + 生成器
+├── docs/repo-audit/        # 使用手册（AGENT-GUIDE + HUMAN-GUIDE）
+├── AUDIT.md                # 审计方法论
+├── BEST-PRACTICES.md       # 最佳实践标准
+├── REPO-CLASSIFICATION.md  # 分类检测说明
+└── REPO-AUDIT.md           # 工具概述
+```
+
+## 📚 文档
+
+- [人类手册](docs/repo-audit/HUMAN-GUIDE.md) — 完整使用说明
+- [Agent 手册](docs/repo-audit/AGENT-GUIDE.md) — 机器可读的操作协议
+- [审计方法论](AUDIT.md)
+- [最佳实践标准](BEST-PRACTICES.md)
+
+## 🛠️ 开发
+
+- 审计规则：编辑 `rules/domains/*.yaml`（跨维度）或 `rules/categories/*.yaml`（分类专属）
+- 新增分类：在 `rules/categories/` 添加 `<type>.yaml`，或用 `REPO_AUDIT_TYPES` 环境变量扩展
+- 自定义规则：`--rules my-rules.yaml` 参数加载
+
+## 📄 许可证
+
+MIT © 2026 NinjaSln-labs

package/REPO-AUDIT.md

@@ -0,0 +1,107 @@
+# repo-audit — 仓库标准化审计工具
+
+专门审计 scaffold 生成的仓库是否符合工业最佳实践标准。审计基准 = `templates/` 目录下的模板文件。
+
+## 快速开始
+
+```bash
+# 审计当前仓库（自动检测分类）
+node repo-audit.mjs
+
+# 审计指定仓库
+node repo-audit.mjs --repo /path/to/repo
+
+# 指定分类（跳过自动检测，加速）
+node repo-audit.mjs --repo /path/to/repo --type python-app
+
+# 启用 LLM 增强（对 fail 的发现做根因分析和修复建议）
+export LLM_PROVIDER=deepseek
+export LLM_API_KEY=sk-xxx
+node repo-audit.mjs --repo /path/to/repo --llm-model deepseek-chat
+
+# 严格模式（Critical/Major 发现即 exit 1，适合 CI）
+node repo-audit.mjs --strict
+
+# 只输出 JSON（CI 解析用）
+node repo-audit.mjs --format json
+
+# 只审计特定维度
+node repo-audit.mjs --dim security --dim docs
+
+# 叠加自定义规则
+node repo-audit.mjs --rules my-custom-rules.yaml
+```
+
+## 跨平台安装
+
+```bash
+# 方式一：直接运行
+node repo-audit.mjs --repo /path/to/repo
+
+# 方式二：加入 PATH（shim 目录）
+export PATH="$PATH:/path/to/shim"
+repo-audit --repo /path/to/repo   # Windows 用 repo-audit.cmd，Linux/macOS 用 repo-audit.sh
+```
+
+## 命令行参数
+
+| 参数 | 说明 | 默认值 |
+|---|---|---|
+| `--repo <path>` | 目标仓库路径 | 当前目录 |
+| `--type <type>` | 强制指定分类（跳过自动检测） | 自动推断 |
+| `--format <fmt>` | 输出格式：md / json / both | both |
+| `--output <path>` | 输出目录 | `<repo>/audit-report/` |
+| `--llm-provider <p>` | LLM 供应商：openai / anthropic / deepseek / none | none |
+| `--llm-model <m>` | 模型名称 | auto |
+| `--strict` | 严格模式：Critical/Major 发现即 exit 1 | 关 |
+| `--rules <file>` | 自定义规则文件（可多次） | 无 |
+| `--dim <domain>` | 只审计指定维度（可多次） | 全部 |
+| `--help, -h` | 显示帮助 | — |
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|---|---|---|
+| `LLM_PROVIDER` | LLM 供应商 | `none` |
+| `LLM_API_KEY` | API Key | 无（必须手动指定）|
+| `LLM_MODEL` | 模型名称 | `auto` |
+| `LLM_BASE_URL` | 自定义 API 端点 | 供应商默认 |
+| `REPO_AUDIT_TYPES` | 自定义分类列表（JSON 数组） | 内置默认 |
+
+支持的 LLM 供应商：`openai`、`anthropic`、`deepseek`、`none`
+
+## 输出说明
+
+审计报告写入 `<repo>/audit-report/` 目录：
+- `report.md` — 人类可读的详细报告（评分 + 分级发现 + LLM 分析）
+- `report.json` — 机器可读的结构化数据（CI 消费用）
+- stdout — 简洁摘要（评分 + 发现统计）
+
+## 审计维度（可扩展）
+
+| 维度 | 初始规则数 | 说明 |
+|---|---|---|
+| `git` | 4 | Conventional Commits、.gitignore、提交数、lock 状态 |
+| `docs` | 8 | README/LICENSE/AGENTS/CONTRIBUTING 等（引用 templates/common/ 单源） |
+| `security` | 4 | 硬编码密钥、CI SHA 固定、本机路径、id-token 权限 |
+| `quality` | 5 | 验证链、CI workflow、pre-commit、锁文件、CLAUDE.md |
+| `dsh` / `python` / `go` / `sandbox` / `content` / `oss` | 各 3-7 | 分类专属规则（从 CATEGORY.md 推导） |
+
+**新增维度**：在 `rules/domains/` 下加新 YAML 文件，无需改引擎代码。
+**新增分类**：在 `rules/categories/` 下加新 YAML + `detectType` 加分支。
+
+## 与 scaffold 的关系
+
+- `scaffold.mjs --generate` 后 → 立即跑 `repo-audit` 验证出库质量
+- `scaffold.mjs --update` 后 → 再跑 `repo-audit` 确认模板升级未破坏既有内容
+- audit 报告可作为 PR 描述附件，说明仓库当前健康度
+- 规则随模板升级自动更新（`template_ref` 指向 templates/，不改代码）
+
+## 退出码
+
+| 码 | 含义 |
+|---|---|
+| 0 | 审计通过（无 Critical/Major 或 --strict 未启用） |
+| 1 | 有 Critical/Major 发现且 --strict 启用 |
+| 2 | 参数错误 / 运行时错误 |
+| 3 | 目标不是 git 仓库 |

package/REPO-CLASSIFICATION.md

@@ -0,0 +1,137 @@
+# 个人仓库分类总表（2026-09 扫描）
+
+> 扫描范围：`~/ninjasin-labs/`（maxdepth 3 找 `.git`）。每仓标注：分类 / 证据 / 模板映射。
+> 分类按"模板差异"划分而非纯技术栈——差异维度：语言运行时、制品形态（npm 发布/服务部署/无制品）、协作模式（单人直提 main / 多人 PR 流）。
+
+## 分类定义与模板映射
+
+| 分类 | 定义 | 模板 |
+|---|---|---|
+| **A · dsh 插件单库** | TypeScript + npm 发布 + 宿主 dsh peer；部署纪律（profile file: 安装） | `templates/repo-root/`（基类，`--type dsh-plugin` 默认） |
+| **B · 产品/多人协作 OSS** | 有 PR 流（merge commit 实证）/ CHANGELOG / ROADMAP / 双语 README；语言不限 | 对应语言基类（A/C/D）+ `templates/categories/product-oss/` overlay |
+| **C · Python 应用/研究** | pyproject.toml + src/ + tests/；pytest/ruff；无 npm | `templates/categories/python-app/`（delta） |
+| **D · Go 服务** | go.mod + cmd/ + Makefile | `templates/categories/go-service/`（delta） |
+| **E · 本地实验/dogfood 沙盒** | 同构 agents/docs/src/tests 结构、master 分支、无 origin、生命周期短 | `templates/categories/sandbox/`（delta，最小集） |
+| **F · 内容/写作** | 文档/文章本体即制品，无构建链 | `templates/categories/content/`（delta，最小集） |
+| **G · 存档只读** | 封版仓，禁改禁发布 | **无模板**（遵守仓内封版纪律） |
+
+## 逐仓清单（23 个 git 仓库）
+
+### A · dsh 插件单库 ×6 → repo-root 基类
+
+| 仓库 | 证据 |
+|---|---|
+| `dsh-ecosystem/dsh-context-compass` | npm 0.11.6、cordis.patch.yml、PUBLISHING/DEVELOPMENT 全套 |
+| `dsh-ecosystem/dsh-subagent-router` | npm 0.4.0、OIDC trusted publishing 首跑 |
+| `dsh-ecosystem/dsh-imgdraw` | 规范化对齐 compass（AGENTS/CONTRIBUTING/SECURITY 全套） |
+| `dsh-ecosystem/dsh-knowledge-sqlite` | npm keywords/files 白名单、双语 README |
+| `dsh-ecosystem/dsh-session-slm-router` | S3 阶段文档、规范全套 |
+| `dsh-ecosystem/dsh-subagent-cursor` | 规范全套、CHANGELOG |
+
+### B · 产品/多人协作 OSS ×4 → 语言基类 + product-oss overlay
+
+| 仓库 | 语言基类 | 证据（PR 流/规范面） |
+|---|---|---|
+| `qingfu-envoy` | python-app | Merge PR #23、CONTRIBUTING/SECURITY/ROADMAP、package-lock（前端） |
+| `neonforge` | python-app（apps/ 多包，待定） | 双轴评审报告入库、lefthook、双语 |
+| `fuyao-nomad` | python-app（harness/） | CHANGELOG/CONTRIBUTING/ROADMAP、release guards |
+| `Voyage` | python-app（impl/sim） | CHANGELOG/双语/PRODUCT-DOC-AUDIT、红蓝对抗报告 |
+
+### C · Python 应用/研究 ×4 → python-app delta
+
+| 仓库 | 证据 |
+|---|---|
+| `chumen` | pyproject.toml + src/tests/tools、内测统计脚本 |
+| `shisui` | pyproject.toml + examples/runs/profiles |
+| `shuijing-v2` | pyproject + setup.cfg + Dockerfile（可部署） |
+| `vertical-small-model` | adapters/lib/tests/reports（研究型，master、无 origin） |
+
+### D · Go 服务 ×1 → go-service delta
+
+| 仓库 | 证据 |
+|---|---|
+| `jinteng` | go.mod/go.sum、cmd/、Makefile、deploy/docs/examples |
+
+### E · 本地实验/dogfood 沙盒 ×11 → sandbox delta
+
+| 仓库 | 证据 |
+|---|---|
+| `fuyao-adopt-qingfu-envoy` / `-shisui` / `-voyage` | 同构 agents/docs/package.json/src/tests、master、无 origin |
+| `fuyao-dogfood-action-list` / `-audit-trail` / `-boundary-s7` / `-changelog-slice` / `-dual-harness` / `-grant-gate` / `-reading-card` / `-todo-strip` | 同上 8 个 dogfood 粒度仓库 |
+| `weather-outfit-assistant` | 单页 JS 小工具（app.js/server.mjs）、dogfood 收尾 |
+
+### F · 内容/写作 ×2 → content delta
+
+| 仓库 | 证据 |
+|---|---|
+| `rsi-unit-of-evolution` | essay.md/en + review 三轮 + revision-notes |
+| `part-time-job` | 简历/素材/行动计划（含 PDF 生成脚本） |
+
+### G · 存档只读 ×1
+
+| 仓库 | 说明 |
+|---|---|
+| `dsh-ecosystem/dsh-plugins` | 2026-09 封版（AGENTS.md 硬性规则：禁改插件源码、发布流程已删）——**不套模板** |
+
+### 非 git 目录（不计入，仅登记）
+
+`agent-tools`、`scripts`、`questions`、`plans`、`cloud-services`、`dsh-ecosystem/research/`（本地研究区）、`generated-images`、`visual`
+
+## 使用方式
+
+```sh
+# A 类（默认）
+node templates/scaffold.mjs --name <name> --org NinjaSln-labs --desc "..."
+# C/D/E/F 类
+node templates/scaffold.mjs --type python-app --name chumen2 --org NinjaSln-labs --desc "..."
+node templates/scaffold.mjs --type sandbox --name dogfood-xxx --desc "..."
+# B 类：先用语言基类脚手架，再叠加 product-oss overlay（见 categories/product-oss/CATEGORY.md）
+```
+
+## 分类模板体系（templates/categories/）
+
+```
+templates/
+├── repo-root/              # 基类工程件（A 类 dsh 插件）；AGENTS/CONTRIBUTING/.gitignore 已迁 common
+├── common/                 # **单源**：AGENTS-core（含 AI 协作守则 7 条）/ CONTRIBUTING-core / gitignore-core / copilot-instructions
+├── categories/             # 各分类 delta（工程件 + *-append.md 差异段 + CATEGORY.md）
+│   ├── dsh-plugin/ python-app/ go-service/ sandbox/ content/ product-oss/
+├── scaffold.mjs            # --type 路由 + --overlay；三件套单源拼装（core+append）
+├── check-single-source.mjs # 多源漂移检查：core 指纹扫描/append 命名/基类残留（发现多源 exit 1）
+└── skill/ README.md
+```
+
+设计原则：**通用文档层一份**（LICENSE/README/DEVELOPMENT/PUBLISHING/SECURITY 骨架）；
+**AGENTS/CONTRIBUTING/.gitignore 单源拼装**（common core + 分类 append，产物内勿手改拼装段）；
+语言差异只在工程件 delta（构建/CI/钩子/忽略表）；`--type` 路由由 `scaffold.mjs` 执行，
+delta 规则的文档源在各分类 `CATEGORY.md`（改规则先改文档）。
+
+**Agent 参与优化（所有工程分类）**：AGENTS.md 内置「AI 协作守则」7 条（不猜契约 / 完成的定义 =
+验证链全绿 / 机密红线 / 不静默绕过门禁 / 改动最小化 / 文档同步 / 冲突处理）；AI 入口三桥接——
+CLAUDE.md（`@AGENTS.md` 导入）+ `.github/copilot-instructions.md`（工程分类自动配）+ AGENTS.md 本体；
+pre-commit 验证链前门即 agent 防呆。
+
+**单源收敛与漂移把守（2026-09 二轮审计）**：AGENTS/CONTRIBUTING/.gitignore 原为 5/4/4 份重复源，
+已收敛为 common 单源 + 分类 append；`check-single-source.mjs` 常态把守（core 指纹扫描——若有人把
+共性段拷回分类文件即 exit 1；实测原样通过）。
+
+**实测记录（2026-09）**：五分类 + B 类混合 scaffold 全跑通；累计抓修 9 个实施 bug（ask fallback
+语义、legal/target 重复声明、delta 落空、最小集漏删、go 空目录清理、SUPPORT/CATEGORY 入产物、
+PR 模板位置、overlay 源路径 ENOENT、content 残留 .gitignore 引用）。
+
+## 边界说明（2026-09 更新：原"未出模板"项已按工业实践调研补全）
+
+- ~~C 类 publish（PyPI）~~ ✅ 已补：`categories/python-app/.github/workflows/publish.yml`（PyPI Trusted
+  Publishing：tag 守卫 + build/publish 分离 + 两环境 pypi/testpypi + PEP 740 attestations 默认开）
+  与 PyPI 版 PUBLISHING.md（pending publisher / bump-my-version / 14 天冻结新规）——依据 docs.pypi.org +
+  pypa/gh-action-pypi-publish v1.14.2（2026-09 核实）
+- ~~D 类 publish（GitHub Release）~~ ✅ 已补：`categories/go-service/.goreleaser.yaml`（v2 最小配置，
+  默认 ldflags 版本注入 + conventional changelog 分组）+ `release.yml`（goreleaser-action@v7）+
+  Go 版 PUBLISHING/CONTRIBUTING——依据 goreleaser.com v2.18（2026-09 核实）；SBOM/cosign/GHCR 按小库
+  务实取舍默认注释、成对启用
+- ~~B 类 overlay 未验证~~ ⬆️ 已升级为完整 overlay：release-please v5 三件套（版本晋升自动化）+
+  YAML issue forms + CODEOWNERS + dependabot + dependency-review + SUPPORT.md 含 21 条"单人→多人
+  升级检查清单"（rulesets 为推荐路径）——依据 docs.github.com 与 googleapis/release-please（2026-09 核实）
+- **仍然成立的不确定项**：三条链均为"按官方文档当前版整理"，未经过一次真实发布回归——各分类首个
+  新库落地时按 PUBLISHING.md 实测并把偏差回写模板；E/F 最小集从现有 13 库实况反推，转正走全量迁移
+

package/SECURITY.md

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