npm - repo-audit-tool - Versions diffs - 1.2.0 → 1.2.3 - Mend

repo-audit-tool 1.2.0 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/PUBLISHING.md +21 -18
package/README.en.md +5 -4
package/README.md +5 -4
package/docs/AGENT-INDEX.json +239 -0
package/docs/AGENT-PROTOCOL.md +295 -0
package/docs/SCHEMA.json +94 -0
package/docs/index.html +213 -0
package/docs/repo-audit/AGENT-GUIDE.md +54 -1
package/docs/repo-audit/HUMAN-GUIDE.md +30 -0
package/package.json +5 -1
package/repo-audit.mjs +40 -2
package/HANDOFF.md +0 -124

package/PUBLISHING.md CHANGED Viewed

@@ -1,17 +1,24 @@
-# 发布记录：@ninjasln-labs/repo-audit
+# 发布记录：repo-audit-tool
 ## 发布状态（2026-09-06 更新）
 | 项 | 状态 |
 |---|---|
-| npm | `@ninjasln-labs/repo-audit` v1.2.0（未发布，待首次发布） |
+| npm | `repo-audit-tool` v1.2.3（latest，CI 自动发布） |
 | GitHub | `NinjaSln-labs/repo-audit` master；发版 tag `v*` |
 | 本地验证 | 自审计 100/A，验证链 4/4，测试 3/3，CI 全绿 |
 ## 版本历史
+- **1.2.3** — package.json 补充 `repository` 字段，修复 npm provenance E422；
+  首次 Trusted Publisher（OIDC）tag 触发自动发布（2026-09-06）
+- **1.2.2** — publish CI 修复：node 20→22 + npm 条件升级，修复 EBADENGINE；
+  tag 发布因 npm 已存在 1.2.1 未出包（OIDC 鉴权链路已验证通过）（2026-09-06）
+- **1.2.1** — README 链接改为绝对 URL（修复 npm 页面 404）；手动发布（2026-09-06）
 - **1.2.0** — 开源就绪：补充 AGENTS.md、CI/publish workflow 适配、json_field monorepo 感知、
   fallback_field 数组格式修复、英文 README、参数类型校验、占位符残留扫描（2026-09-06）
+  - 首次发布：`npm publish --access public`（手动 bootstrap）
+  - 后续发布：Trusted Publisher（OIDC）由 CI 自动发布
 ## 发布通道（npm OIDC Trusted Publishing）
@@ -23,7 +30,7 @@
 ```sh
 npm version patch --no-git-tag-version
 V="$(node -p "require('./package.json').version")"
-git commit -am "chore: release @ninjasln-labs/repo-audit v$V — <一句话主旨>"
+git commit -am "chore: release repo-audit-tool v$V — <一句话主旨>"
 git tag v$V
 git push && git push --tags
 # CI 接手：审计 → 验证链 → 测试 → 版本守卫 → npm publish
@@ -34,29 +41,25 @@ git push && git push --tags
 ```sh
 npm version prerelease --preid=next --no-git-tag-version
 V="$(node -p "require('./package.json').version")"
-git commit -am "chore: canary @ninjasln-labs/repo-audit v$V" && git tag v$V
+git commit -am "chore: canary repo-audit-tool v$V" && git tag v$V
 git push && git push --tags
-# 实测通过 → 晋级 latest：npm dist-tag add @ninjasln-labs/repo-audit@x.y.z latest
+# 实测通过 → 晋级 latest：npm dist-tag add repo-audit-tool@x.y.z latest
 ```
-## 首次发布前置（一次性）
+## 首次发布（已完成）
-1. **npm 包创建**：npmjs.com → Create Package → `@ninjasln-labs/repo-audit`（需先创建 `ninjasln-labs` org）
-2. **Trusted Publisher 配置**：包设置 → Trusted Publisher → 填 GitHub repo `NinjaSln-labs/repo-audit`
-   + workflow `publish.yml` + branch `master`（逐字段一致）
-3. **首次 bootstrap**：首版可手动发布：
-   ```sh
-   npm login  # 交互登录 + 2FA
-   npm publish --access public
-   ```
-   随后立即切 Trusted Publishing 由 CI 发布
-4. **验证发布成功**：`npm view @ninjasln-labs/repo-audit dist-tags` + npm 页 provenance 徽章
+1. **npm 包创建**：`npm publish --access public`（v1.2.0，2026-09-06）
+2. **Trusted Publisher 配置**：npmjs.com → 包设置 → Trusted Publisher →
+   - Repository: `NinjaSln-labs/repo-audit`
+   - Workflow: `publish.yml`
+   - Branch: `master`（注：tag 触发场景 npm 亦放行，v1.2.2 实测通过）
+3. **验证**：`npm view repo-audit-tool dist-tags` → latest 已更新 ✓
 ## 发布后验证
-- 确认 latest 已更新（`npm view @ninjasln-labs/repo-audit dist-tags`）
+- 确认 latest 已更新（`npm view repo-audit-tool dist-tags`）
 - provenance 徽章（npm 包页面）
-- 实机安装路径实测：`npm install -g @ninjasln-labs/repo-audit` → `repo-audit --repo .`
+- 实机安装路径实测：`npm install -g repo-audit-tool` → `repo-audit --repo .`
 ## 维护要点

package/README.en.md CHANGED Viewed

@@ -55,10 +55,11 @@ repo-audit/
 ## 📚 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)
+- [Human Guide](https://github.com/NinjaSln-labs/repo-audit/blob/master/docs/repo-audit/HUMAN-GUIDE.md) — Full usage documentation
+- [Agent Guide](https://github.com/NinjaSln-labs/repo-audit/blob/master/docs/repo-audit/AGENT-GUIDE.md) — Machine-readable operation protocol
+- [Audit Methodology](https://github.com/NinjaSln-labs/repo-audit/blob/master/AUDIT.md)
+- [Best Practices](https://github.com/NinjaSln-labs/repo-audit/blob/master/BEST-PRACTICES.md)
+- [GitHub Pages](https://ninjasln-labs.github.io/repo-audit/) — Online documentation
 ## 🛠️ Development

package/README.md CHANGED Viewed

@@ -55,10 +55,11 @@ repo-audit/
 ## 📚 文档
-- [人类手册](docs/repo-audit/HUMAN-GUIDE.md) — 完整使用说明
-- [Agent 手册](docs/repo-audit/AGENT-GUIDE.md) — 机器可读的操作协议
-- [审计方法论](AUDIT.md)
-- [最佳实践标准](BEST-PRACTICES.md)
+- [人类手册](https://github.com/NinjaSln-labs/repo-audit/blob/master/docs/repo-audit/HUMAN-GUIDE.md) — 完整使用说明
+- [Agent 手册](https://github.com/NinjaSln-labs/repo-audit/blob/master/docs/repo-audit/AGENT-GUIDE.md) — 机器可读的操作协议
+- [审计方法论](https://github.com/NinjaSln-labs/repo-audit/blob/master/AUDIT.md)
+- [最佳实践标准](https://github.com/NinjaSln-labs/repo-audit/blob/master/BEST-PRACTICES.md)
+- [GitHub Pages](https://ninjasln-labs.github.io/repo-audit/) — 在线文档
 ## 🛠️ 开发

package/docs/AGENT-INDEX.json ADDED Viewed

@@ -0,0 +1,239 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "repo-audit 文档索引",
+  "description": "AI Agent 可读的文档索引 — 包含所有文档的元数据、结构、和调用协议",
+  "version": "1.2.3",
+  "updated": "2026-09-06",
+  "repo": "NinjaSln-labs/repo-audit",
+  "npm": "repo-audit-tool",
+  "pages": "https://ninjasln-labs.github.io/repo-audit/",
+  "entry_points": {
+    "json_index": "/AGENT-INDEX.json",
+    "schema": "/SCHEMA.json",
+    "protocol": "/AGENT-PROTOCOL.md",
+    "human_guide": "/repo-audit/HUMAN-GUIDE.md",
+    "agent_guide": "/repo-audit/AGENT-GUIDE.md"
+  },
+  "tool": {
+    "name": "repo-audit",
+    "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
+    "bin": "repo-audit",
+    "version": "1.2.3",
+    "language": "JavaScript (ESM)",
+    "runtime": "Node.js >= 18",
+    "dependencies": [],
+    "license": "MIT",
+    "invocation": {
+      "command": "repo-audit [options]",
+      "options": {
+        "--repo": { "type": "string", "default": ".", "description": "目标仓库路径" },
+        "--type": { "type": "string", "description": "强制指定分类（跳过自动检测）" },
+        "--format": { "type": "string", "enum": ["md", "json", "both"], "default": "both", "description": "输出格式" },
+        "--output": { "type": "string", "default": "<repo>/audit-report/", "description": "输出目录" },
+        "--llm-provider": { "type": "string", "description": "LLM 协议：openai/anthropic 或厂商别名" },
+        "--llm-model": { "type": "string", "description": "模型名称" },
+        "--strict": { "type": "boolean", "default": false, "description": "严格模式：Critical/Major 即 exit 1" },
+        "--rules": { "type": "string", "description": "自定义规则 YAML（可多次）" },
+        "--dim": { "type": "string", "description": "只审计指定维度（可多次）" },
+        "--feedback": { "type": "string", "description": "提交反馈（创建 GitHub Issue）" },
+        "--help": { "type": "boolean", "description": "显示帮助" }
+      },
+      "exit_codes": {
+        "0": "审计通过（无 Critical/Major 或 --strict 未启用）",
+        "1": "有 Critical/Major 发现且 --strict 启用",
+        "2": "参数错误",
+        "3": "目标不是 git 仓库"
+      }
+    },
+    "environment_variables": {
+      "LLM_PROVIDER": "LLM 协议（openai/anthropic/none），也可用厂商别名如 deepseek/qwen/glm",
+      "LLM_API_KEY": "API Key（必须手动指定）",
+      "LLM_MODEL": "模型名称",
+      "LLM_BASE_URL": "自定义 API 端点（OpenAI 兼容厂商必填）",
+      "REPO_AUDIT_TYPES": "自定义分类列表（JSON 数组）"
+    }
+  },
+  "audit": {
+    "dimensions": [
+      {
+        "id": "docs",
+        "label": "文档",
+        "rules": ["DOC-001", "DOC-002", "DOC-003", "DOC-003b", "DOC-004", "DOC-005", "DOC-006", "DOC-007"],
+        "description": "README/LICENSE/CONTRIBUTING/SECURITY 等文档完整性"
+      },
+      {
+        "id": "git",
+        "label": "Git",
+        "rules": ["GIT-001", "GIT-002", "GIT-003", "GIT-004"],
+        "description": "commit 规范、分支策略、scaffold 管理"
+      },
+      {
+        "id": "quality",
+        "label": "质量",
+        "rules": ["QUA-001", "QUA-002", "QUA-003", "QUA-004", "QUA-005"],
+        "description": "构建配置、测试、lint、typecheck"
+      },
+      {
+        "id": "security",
+        "label": "安全",
+        "rules": ["SEC-001", "SEC-002", "SEC-003", "SEC-004"],
+        "description": "密钥泄露、依赖漏洞、权限配置"
+      }
+    ],
+    "scoring": {
+      "formula": "score = 100 - (critical × 25) - (major × 10) - (minor × 3)",
+      "grades": {
+        "A": ">= 90",
+        "B": ">= 80",
+        "C": ">= 70",
+        "D": ">= 60",
+        "F": "< 60"
+      },
+      "note": "score 和 grade 不在 JSON 输出中，Agent 需根据 summary 字段自行计算"
+    },
+    "categories": [
+      "dsh-plugin", "python-app", "go-service", "content", "sandbox",
+      "archive", "product-oss", "javascript", "typescript", "java",
+      "python", "rust", "cpp", "dotnet", "php", "ruby", "unknown"
+    ]
+  },
+  "documents": [
+    {
+      "id": "human-guide",
+      "title": "人类使用手册",
+      "path": "/repo-audit/HUMAN-GUIDE.md",
+      "url": "https://ninjasln-labs.github.io/repo-audit/repo-audit/HUMAN-GUIDE.md",
+      "audience": "human",
+      "sections": [
+        "一、安装",
+        "二、快速开始",
+        "三、命令行参数",
+        "四、环境变量",
+        "五、输出说明",
+        "六、退出码",
+        "七、审计维度说明",
+        "八、扩展指南",
+        "九、故障排查",
+        "十、与 scaffold 的配合",
+        "十一、操作授权与完成路径",
+        "十二、新特性说明"
+      ]
+    },
+    {
+      "id": "agent-guide",
+      "title": "Agent 操作手册",
+      "path": "/repo-audit/AGENT-GUIDE.md",
+      "url": "https://ninjasln-labs.github.io/repo-audit/repo-audit/AGENT-GUIDE.md",
+      "audience": "agent",
+      "sections": [
+        "一、工具定位",
+        "二、调用协议",
+        "三、输出解析",
+        "四、标准操作流程",
+        "五、错误处理协议",
+        "六、性能参考",
+        "七、Agent 决策树",
+        "八、操作授权与完成路径",
+        "九、快速参考卡",
+        "十、反馈通道"
+      ]
+    },
+    {
+      "id": "audit-methodology",
+      "title": "审计方法论",
+      "path": "/AUDIT.md",
+      "url": "https://github.com/NinjaSln-labs/repo-audit/blob/master/AUDIT.md",
+      "audience": "both",
+      "description": "评分体系、规则设计、维度划分"
+    },
+    {
+      "id": "best-practices",
+      "title": "最佳实践标准",
+      "path": "/BEST-PRACTICES.md",
+      "url": "https://github.com/NinjaSln-labs/repo-audit/blob/master/BEST-PRACTICES.md",
+      "audience": "both",
+      "description": "工程仓库应满足的标准化检查项"
+    },
+    {
+      "id": "classification",
+      "title": "分类检测说明",
+      "path": "/REPO-CLASSIFICATION.md",
+      "url": "https://github.com/NinjaSln-labs/repo-audit/blob/master/REPO-CLASSIFICATION.md",
+      "audience": "both",
+      "description": "18 种仓库类型识别逻辑，置信度评分"
+    },
+    {
+      "id": "templates",
+      "title": "脚手架模板",
+      "path": "/templates/README.md",
+      "url": "https://github.com/NinjaSln-labs/repo-audit/blob/master/templates/README.md",
+      "audience": "both",
+      "description": "从零生成符合规范的工程脚手架"
+    },
+    {
+      "id": "schema",
+      "title": "审计报告 JSON Schema",
+      "path": "/SCHEMA.json",
+      "url": "https://ninjasln-labs.github.io/repo-audit/SCHEMA.json",
+      "audience": "agent",
+      "format": "json-schema",
+      "description": "JSON Schema 定义，用于验证审计报告输出"
+    }
+  ],
+  "feedback": {
+    "description": "反馈通道 — Agent 可通过 GitHub Issues API 检测和处理用户反馈",
+    "label": "audit-feedback",
+    "repo": "NinjaSln-labs/repo-audit",
+    "detect": {
+      "command": "gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open --json number,title,createdAt,body",
+      "description": "列出未处理的反馈"
+    },
+    "view": {
+      "command": "gh issue view <NUMBER> --repo NinjaSln-labs/repo-audit --json title,body,labels,createdAt",
+      "description": "获取单条反馈详情"
+    },
+    "close": {
+      "command": "gh issue close <NUMBER> --repo NinjaSln-labs/repo-audit --comment '已处理：[处理说明]'",
+      "description": "反馈已处理，关闭 Issue"
+    },
+    "create": {
+      "command": "node repo-audit.mjs --feedback '<反馈内容>'",
+      "description": "通过 CLI 创建反馈 Issue（自动预填环境信息）"
+    },
+    "priorities": [
+      { "level": "critical", "sla": "24h", "description": "工具崩溃/数据损坏" },
+      { "level": "major", "sla": "72h", "description": "功能严重受损" },
+      { "level": "minor", "sla": "1周", "description": "功能部分受损" },
+      { "level": "info", "sla": "排期", "description": "建议改进" }
+    ]
+  },
+  "quick_start": {
+    "install": "npm install -g repo-audit-tool",
+    "audit": "repo-audit --repo /path/to/repo",
+    "json_output": "repo-audit --repo /path/to/repo --format json",
+    "scaffold": "node templates/scaffold.mjs --type dsh-plugin --name my-plugin",
+    "strict_mode": "repo-audit --repo /path/to/repo --strict",
+    "custom_rules": "repo-audit --repo /path/to/repo --rules my-rules.yaml",
+    "llm_enhanced": "LLM_API_KEY=sk-xxx repo-audit --repo . --llm-provider deepseek"
+  },
+  "changelog": {
+    "1.2.3": "package.json 补充 repository 字段，修复 npm provenance E422；完成 Trusted Publisher tag 自动发布",
+    "1.2.2": "publish CI 改用 node 22 + 条件升级 npm，修复 EBADENGINE（tag 发布因 1.2.1 已存在未出包）",
+    "1.2.1": "README 链接改为绝对 URL（修复 npm 页面 404）",
+    "1.2.0": "开源就绪：AGENTS.md、CI/publish workflow、json_field monorepo、fallback_field 数组、英文 README、参数类型校验、占位符扫描"
+  }
+}

package/docs/AGENT-PROTOCOL.md ADDED Viewed

@@ -0,0 +1,295 @@
+---
+title: repo-audit Agent Protocol
+version: "1.2.1"
+audience: agent
+format: markdown+metadata
+schema: /SCHEMA.json
+index: /AGENT-INDEX.json
+---
+# repo-audit Agent Protocol
+> 机器可读的操作协议。Agent 直接执行，无需人类解释。
+## 1. 工具身份
+```json
+{
+  "name": "repo-audit",
+  "npm": "repo-audit-tool",
+  "version": "1.2.1",
+  "bin": "repo-audit",
+  "language": "JavaScript ESM",
+  "runtime": "Node.js >= 18",
+  "dependencies": [],
+  "license": "MIT",
+  "readonly": true
+}
+```
+## 2. 调用协议
+### 2.1 基本调用
+```
+repo-audit [--repo <path>] [--type <type>] [--format <fmt>] [--output <path>]
+           [--llm-provider <p>] [--llm-model <m>] [--strict]
+           [--rules <file>] [--dim <domain>] [--feedback <msg>]
+```
+### 2.2 参数
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `--repo` | string | 否 | `.` | 目标仓库路径 |
+| `--type` | string | 否 | 自动检测 | 强制指定分类 |
+| `--format` | enum | 否 | `both` | `md` / `json` / `both` |
+| `--output` | string | 否 | `<repo>/audit-report/` | 输出目录 |
+| `--llm-provider` | string | 否 | 环境变量 | LLM 协议 |
+| `--llm-model` | string | 否 | 自动 | 模型名称 |
+| `--strict` | bool | 否 | `false` | Critical/Major 即 exit 1 |
+| `--rules` | string[] | 否 | — | 自定义规则 YAML |
+| `--dim` | string[] | 否 | 全部 | 只审计指定维度 |
+| `--feedback` | string | 否 | — | 提交反馈 |
+### 2.3 退出码
+| 码 | 含义 | Agent 应执行 |
+|---|---|---|
+| 0 | 审计通过 | 正常继续 |
+| 1 | Critical/Major 发现 + --strict | 读取 findings 并报告 |
+| 2 | 参数错误 | 修正参数后重试 |
+| 3 | 目标不是 git 仓库 | 提示用户切换到 git 仓库 |
+## 3. 输出格式
+### 3.1 JSON 报告结构
+```json
+{
+  "generated_at": "2026-09-06T12:00:00.000Z",
+  "audit_type": "dsh-plugin",
+  "llm_used": false,
+  "metadata": {
+    "remote": "https://github.com/org/repo.git",
+    "branch": "master",
+    "commitCount": 42,
+    "fileCount": 117,
+    "lastCommit": "2026-09-06 12:00:00 +0800",
+    "path": "/path/to/repo"
+  },
+  "summary": {
+    "critical": 0,
+    "major": 0,
+    "minor": 0,
+    "info": 0,
+    "pass": 19,
+    "total": 19,
+    "waived": 0,
+    "llmUsed": false
+  },
+  "findings": [
+    {
+      "id": "DOC-001",
+      "title": "README.md 存在",
+      "severity": "critical",
+      "domain": "docs",
+      "applies_to": ["*"],
+      "status": "pass",
+      "message": "符合",
+      "evidence": "✓ README.md (3.1kB)",
+      "hint": null,
+      "template_ref": null
+    }
+  ]
+}
+```
+### 3.2 评分公式
+```
+score = 100 - (critical × 25) - (major × 10) - (minor × 3)
+```
+| 等级 | 分数 |
+|---|---|
+| A | ≥ 90 |
+| B | ≥ 80 |
+| C | ≥ 70 |
+| D | ≥ 60 |
+| F | < 60 |
+### 3.3 发现状态
+| 状态 | 含义 | Agent 处理 |
+|---|---|---|
+| `pass` | 检查通过 | 忽略 |
+| `fail` | 检查失败 | 读取 `message` + `evidence` + `hint` |
+| `waived` | 已豁免 | 读取 `waived_reason` + `waived_since` |
+### 3.4 严重级别
+| 级别 | 扣分 | Agent 优先级 |
+|---|---|---|
+| `critical` | -25 | P0 — 立即处理 |
+| `major` | -10 | P1 — 优先处理 |
+| `minor` | -3 | P2 — 正常处理 |
+| `info` | 0 | P3 — 参考信息 |
+## 4. 标准操作流程
+### 4.1 新建仓库后验证
+```bash
+repo-audit --repo /path/to/new-repo --format json
+```
+Agent 读取 JSON，检查 `summary.grade`：
+- `A` → 通过，报告成功
+- `B/C` → 报告需改进项（列出 fail findings）
+- `D/F` → 警告，建议修复 critical/major 问题
+### 4.2 CI 门禁集成
+```yaml
+# GitHub Actions 示例
+- name: Audit
+  run: repo-audit --repo . --format json --strict
+```
+`--strict` 使 Critical/Major 发现返回 exit 1，自动阻断 CI。
+### 4.3 自定义规则
+```yaml
+# my-rules.yaml
+rules:
+  - id: COM-001
+    title: "提交信息规范"
+    severity: major
+    domain: git
+    applies_to: ["*"]
+    check: commit_message
+    params:
+      pattern: "^(feat|fix|docs|chore|refactor|test):"
+```
+```bash
+repo-audit --repo . --rules my-rules.yaml
+```
+### 4.4 反馈处理
+```bash
+# 检测新反馈
+gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open --json number,title,createdAt,body
+# 获取详情
+gh issue view 42 --repo NinjaSln-labs/repo-audit --json title,body,labels
+# 处理完成
+gh issue close 42 --repo NinjaSln-labs/repo-audit --comment "已处理：修复了 X 问题"
+```
+## 5. 错误处理协议
+| 错误 | 原因 | Agent 处理 |
+|---|---|---|
+| `目标不是 git 仓库` | 目录无 `.git/` | 提示 `git init` 或切换到正确路径 |
+| `未知参数` | 参数拼写错误 | 检查 `--help` |
+| `LLM 增强失败` | API Key 无效/网络问题 | 降级为非 LLM 模式 |
+| `规则加载失败` | YAML 语法错误 | 报告错误行，不阻断审计 |
+| `分类检测不准` | 文件结构特殊 | 使用 `--type` 强制指定 |
+## 6. Agent 决策树
+```
+收到审计请求
+  ├─ 有 --repo 参数？
+  │   ├─ 否 → 默认当前目录
+  │   └─ 是 → 使用指定路径
+  ├─ 有 --format 参数？
+  │   ├─ json → 只输出 JSON
+  │   ├─ md → 只输出 Markdown
+  │   └─ both/默认 → 同时输出
+  ├─ 有 LLM 配置？
+  │   ├─ 是 → 启用 LLM 增强
+  │   └─ 否 → 纯规则审计
+  ├─ 执行审计
+  ├─ 解析 summary
+  │   ├─ grade A → 报告通过
+  │   ├─ grade B/C → 报告改进项
+  │   └─ grade D/F → 警告严重问题
+  └─ 输出结果
+```
+## 7. 反馈通道
+### 7.1 检测协议
+```bash
+# 列出未处理反馈
+gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open --json number,title,createdAt,body
+# 获取详情
+gh issue view <NUMBER> --repo NinjaSln-labs/repo-audit --json title,body,labels,createdAt
+# 关闭已处理
+gh issue close <NUMBER> --repo NinjaSln-labs/repo-audit --comment "已处理：[说明]"
+```
+### 7.2 创建反馈
+```bash
+# CLI 方式
+node repo-audit.mjs --feedback "在 xxx 场景下出现 yyy 问题"
+# API 方式
+gh issue create --repo NinjaSln-labs/repo-audit \
+  --title "Feedback: <标题>" \
+  --body "<正文>" \
+  --label "feedback,audit-feedback"
+```
+### 7.3 处理优先级
+| 级别 | SLA | 描述 |
+|---|---|---|
+| critical | 24h | 工具崩溃/数据损坏 |
+| major | 72h | 功能严重受损 |
+| minor | 1周 | 功能部分受损 |
+| info | 排期 | 建议改进 |
+## 8. 快速参考卡
+```bash
+# 安装
+npm install -g repo-audit-tool
+# 基本审计
+repo-audit --repo /path/to/repo
+# JSON 输出
+repo-audit --repo /path/to/repo --format json
+# 严格模式（CI 用）
+repo-audit --repo . --format json --strict
+# LLM 增强
+LLM_API_KEY=sk-xxx repo-audit --repo . --llm-provider deepseek
+# 自定义规则
+repo-audit --repo . --rules my-rules.yaml
+# 指定维度
+repo-audit --repo . --dim security --dim docs
+# 生成脚手架
+node templates/scaffold.mjs --type dsh-plugin --name my-plugin
+# 提交反馈
+repo-audit --feedback "问题描述"
+# 检测反馈
+gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open
+```

package/docs/SCHEMA.json ADDED Viewed

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ninjasln-labs.github.io/repo-audit/SCHEMA.json",
+  "title": "repo-audit 审计报告 Schema",
+  "description": "repo-audit 工具输出的 JSON 报告格式定义",
+  "type": "object",
+  "required": ["generated_at", "audit_type", "llm_used", "metadata", "summary", "findings"],
+  "properties": {
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "报告生成时间 (ISO 8601)"
+    },
+    "audit_type": {
+      "type": "string",
+      "description": "检测到的仓库分类",
+      "enum": [
+        "dsh-plugin", "python-app", "go-service", "content", "sandbox",
+        "archive", "product-oss", "javascript", "typescript", "java",
+        "python", "rust", "cpp", "dotnet", "php", "ruby", "unknown"
+      ]
+    },
+    "llm_used": {
+      "type": "boolean",
+      "description": "是否使用了 LLM 增强"
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["remote", "branch", "commitCount", "fileCount", "lastCommit", "path"],
+      "properties": {
+        "remote": { "type": ["string", "null"], "description": "git remote URL" },
+        "branch": { "type": "string", "description": "当前分支" },
+        "commitCount": { "type": "number", "description": "commit 总数" },
+        "fileCount": { "type": "number", "description": "文件总数" },
+        "lastCommit": { "type": "string", "description": "最近 commit 时间" },
+        "path": { "type": "string", "description": "仓库路径" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["critical", "major", "minor", "info", "pass", "total", "waived", "llmUsed"],
+      "properties": {
+        "critical": { "type": "number", "minimum": 0, "description": "Critical 级发现数" },
+        "major": { "type": "number", "minimum": 0, "description": "Major 级发现数" },
+        "minor": { "type": "number", "minimum": 0, "description": "Minor 级发现数" },
+        "info": { "type": "number", "minimum": 0, "description": "Info 级发现数" },
+        "pass": { "type": "number", "minimum": 0, "description": "通过的检查数" },
+        "total": { "type": "number", "minimum": 1, "description": "总检查数" },
+        "waived": { "type": "number", "minimum": 0, "description": "已豁免的检查数" },
+        "llmUsed": { "type": "boolean" }
+      },
+      "description": "汇总统计。评分公式：score = 100 - (critical×25) - (major×10) - (minor×3)。等级：A≥90, B≥80, C≥70, D≥60, F<60"
+    },
+    "findings": {
+      "type": "array",
+      "description": "审计发现列表",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "severity", "domain", "status", "message", "evidence"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "规则 ID",
+            "pattern": "^(DOC|GIT|QUA|SEC|COM|DEP)-\\d{3}[a-z]?$"
+          },
+          "title": { "type": "string", "description": "规则标题" },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "major", "minor", "info"]
+          },
+          "domain": {
+            "type": "string",
+            "enum": ["docs", "git", "quality", "security", "compliance", "dependencies"]
+          },
+          "applies_to": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "适用的仓库分类列表，* 表示全部"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail", "waived"]
+          },
+          "message": { "type": "string", "description": "通过: '符合'; 失败: 规则描述" },
+          "evidence": { "type": "string", "description": "证据文本" },
+          "hint": { "type": ["string", "null"], "description": "修复建议" },
+          "template_ref": { "type": ["string", "null"], "description": "模板引用" },
+          "waived_reason": { "type": ["string", "null"], "description": "豁免原因" },
+          "waived_since": { "type": ["string", "null"], "description": "豁免起始日期" }
+        }
+      }
+    }
+  }
+}

package/docs/index.html ADDED Viewed

@@ -0,0 +1,213 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>repo-audit 文档</title>
+  <!-- JSON-LD 结构化数据 — AI Agent 可读 -->
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "①type": "SoftwareApplication",
+    "name": "repo-audit",
+    "url": "https://github.com/NinjaSln-labs/repo-audit",
+    "downloadUrl": "https://www.npmjs.com/package/repo-audit-tool",
+    "softwareVersion": "1.2.1",
+    "applicationCategory": "DeveloperApplication",
+    "operatingSystem": "Node.js >= 18",
+    "license": "MIT",
+    "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
+    "programmingLanguage": "JavaScript ESM",
+    "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
+    "documentation": [
+      { "name": "AGENT-INDEX.json", "url": "https://ninjasln-labs.github.io/repo-audit/AGENT-INDEX.json", "format": "json" },
+      { "name": "SCHEMA.json", "url": "https://ninjasln-labs.github.io/repo-audit/SCHEMA.json", "format": "json-schema" },
+      { "name": "AGENT-PROTOCOL.md", "url": "https://ninjasln-labs.github.io/repo-audit/AGENT-PROTOCOL.md", "format": "markdown" },
+      { "name": "HUMAN-GUIDE.md", "url": "https://ninjasln-labs.github.io/repo-audit/repo-audit/HUMAN-GUIDE.md", "format": "markdown" },
+      { "name": "AGENT-GUIDE.md", "url": "https://ninjasln-labs.github.io/repo-audit/repo-audit/AGENT-GUIDE.md", "format": "markdown" }
+    ]
+  }
+  </script>
+  <style>
+    :root { --bg: #0d1117; --card: #161b22; --border: #30363d; --text: #e6edf3; --muted: #8b949e; --accent: #58a6ff; --accent-hover: #79c0ff; --green: #3fb950; }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; background: var(--bg); color: var(--text); line-height: 1.6; }
+    .container { max-width: 960px; margin: 0 auto; padding: 2rem 1rem; }
+    header { text-align: center; padding: 3rem 0 2rem; }
+    h1 { font-size: 2.5rem; margin-bottom: 0.5rem; }
+    h1 a { color: var(--text); text-decoration: none; }
+    .subtitle { color: var(--muted); font-size: 1.1rem; margin-bottom: 1.5rem; }
+    .badges { display: flex; gap: 0.5rem; justify-content: center; flex-wrap: wrap; }
+    .badge { display: inline-flex; align-items: center; gap: 0.3rem; padding: 0.25rem 0.6rem; border-radius: 999px; font-size: 0.8rem; font-weight: 600; }
+    .badge-npm { background: #f70a45; color: white; }
+    .badge-ci { background: var(--accent); color: white; }
+    .badge-node { background: #339933; color: white; }
+    .badge-license { background: #555; color: white; }
+    .badge-zero { background: var(--green); color: white; }
+    .badge-count { background: var(--muted); color: white; }
+    .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin: 2rem 0; }
+    .card { background: var(--card); border: 1px solid var(--border); border-radius: 8px; padding: 1.5rem; transition: border-color 0.2s; }
+    .card:hover { border-color: var(--accent); }
+    .card h2 { font-size: 1.2rem; margin-bottom: 0.5rem; color: var(--accent); }
+    .card p { color: var(--muted); font-size: 0.9rem; margin-bottom: 1rem; }
+    .card a { display: inline-block; color: var(--accent); text-decoration: none; font-weight: 600; font-size: 0.9rem; }
+    .card a:hover { color: var(--accent-hover); text-decoration: underline; }
+    .quickstart { background: var(--card); border: 1px solid var(--border); border-radius: 8px; padding: 1.5rem; margin: 2rem 0; }
+    .quickstart h2 { font-size: 1.3rem; margin-bottom: 1rem; color: var(--accent); }
+    pre { background: #0d1117; border: 1px solid var(--border); border-radius: 6px; padding: 1rem; overflow-x: auto; font-size: 0.9rem; }
+    code { font-family: 'SF Mono', Monaco, Inconsolata, monospace; }
+    code:not(pre code) { background: #21262d; padding: 0.2rem 0.4rem; border-radius: 4px; font-size: 0.85em; }
+    .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 1rem; margin: 2rem 0; }
+    .stat { background: var(--card); border: 1px solid var(--border); border-radius: 8px; padding: 1.5rem; text-align: center; }
+    .stat-value { font-size: 2rem; font-weight: 700; color: var(--accent); }
+    .stat-label { font-size: 0.85rem; color: var(--muted); margin-top: 0.3rem; }
+    .feedback { background: #1a1a2e; border: 1px solid #4c4c8a; border-radius: 8px; padding: 1.5rem; margin: 2rem 0; }
+    .feedback h2 { color: #a78bfa; }
+    .feedback p { color: var(--muted); }
+    footer { text-align: center; padding: 2rem 0; color: var(--muted); font-size: 0.85rem; border-top: 1px solid var(--border); margin-top: 2rem; }
+    footer a { color: var(--accent); text-decoration: none; }
+    footer a:hover { text-decoration: underline; }
+    .nav-bar { display: flex; justify-content: space-between; align-items: center; padding: 0.75rem 0; margin-bottom: 1rem; border-bottom: 1px solid var(--border); }
+    .nav-links { display: flex; gap: 1rem; }
+    .nav-links a { color: var(--muted); text-decoration: none; font-size: 0.9rem; }
+    .nav-links a:hover { color: var(--accent); }
+  </style>
+</head>
+<body>
+<div class="container">
+  <div class="nav-bar">
+    <a href="https://github.com/NinjaSln-labs/repo-audit" style="font-weight:700;color:var(--text);text-decoration:none;">repo-audit</a>
+    <div class="nav-links">
+      <a href="AGENT-INDEX.json">🤖 Agent 索引</a>
+      <a href="SCHEMA.json">📐 Schema</a>
+      <a href="AGENT-PROTOCOL.md">📖 协议</a>
+      <a href="repo-audit/HUMAN-GUIDE.md">使用手册</a>
+      <a href="repo-audit/AGENT-GUIDE.md">Agent 手册</a>
+      <a href="../AUDIT.md">审计方法论</a>
+      <a href="../BEST-PRACTICES.md">最佳实践</a>
+    </div>
+  </div>
+  <header>
+    <h1><a href="https://github.com/NinjaSln-labs/repo-audit">repo-audit</a></h1>
+    <p class="subtitle">仓库标准化审计工具 + 工程脚手架生成器（零依赖）</p>
+    <div class="badges">
+      <span class="badge badge-npm">npm repo-audit-tool</span>
+      <span class="badge badge-ci">CI 全绿</span>
+      <span class="badge badge-node">Node ≥18</span>
+      <span class="badge badge-zero">零依赖</span>
+      <span class="badge badge-license">MIT</span>
+      <span class="badge badge-count">19 条规则 · 18 种分类</span>
+    </div>
+  </header>
+  <div class="stats">
+    <div class="stat"><div class="stat-value">100/A</div><div class="stat-label">自审计评分</div></div>
+    <div class="stat"><div class="stat-value">18</div><div class="stat-label">仓库分类</div></div>
+    <div class="stat"><div class="stat-value">15+</div><div class="stat-label">LLM 提供商</div></div>
+    <div class="stat"><div class="stat-value">0</div><div class="stat-label">npm 依赖</div></div>
+  </div>
+  <!-- Agent 入口 -->
+  <div class="agent-entry" style="background:#0d2137;border:1px solid #1f6feb;border-radius:8px;padding:1.5rem;margin:2rem 0;">
+    <h2 style="color:#58a6ff;font-size:1.3rem;margin-bottom:1rem;">🤖 AI Agent 入口</h2>
+    <p style="color:#8b949e;margin-bottom:1rem;">Agent 可读取以下结构化文档，自动理解工具协议、输出格式和调用方式：</p>
+    <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:1rem;">
+      <div style="background:#161b22;border:1px solid #30363d;border-radius:6px;padding:1rem;">
+        <a href="AGENT-INDEX.json" style="color:#58a6ff;text-decoration:none;font-weight:600;">📋 AGENT-INDEX.json</a>
+        <p style="color:#8b949e;font-size:0.85rem;margin-top:0.3rem;">机器可读文档索引<br>包含工具参数、退出码、环境变量、文档结构</p>
+      </div>
+      <div style="background:#161b22;border:1px solid #30363d;border-radius:6px;padding:1rem;">
+        <a href="SCHEMA.json" style="color:#58a6ff;text-decoration:none;font-weight:600;">📐 SCHEMA.json</a>
+        <p style="color:#8b949e;font-size:0.85rem;margin-top:0.3rem;">JSON Schema 定义<br>用于验证审计报告输出格式</p>
+      </div>
+      <div style="background:#161b22;border:1px solid #30363d;border-radius:6px;padding:1rem;">
+        <a href="AGENT-PROTOCOL.md" style="color:#58a6ff;text-decoration:none;font-weight:600;">📖 AGENT-PROTOCOL.md</a>
+        <p style="color:#8b949e;font-size:0.85rem;margin-top:0.3rem;">Agent 操作协议<br>调用方式、输出解析、决策树、错误处理</p>
+      </div>
+    </div>
+    <pre style="margin-top:1rem;background:#0d1117;border:1px solid #30363d;border-radius:6px;padding:1rem;font-size:0.85rem;"><code># Agent 一键获取文档索引
+curl -s https://ninjasln-labs.github.io/repo-audit/AGENT-INDEX.json | jq '.tool.invocation'
+# 验证审计报告
+jq --argfile schema https://ninjasln-labs.github.io/repo-audit/SCHEMA.json \
+  'empty as $_ | ., (input)' audit-report.json &gt; /dev/null</code></pre>
+  </div>
+  <div class="cards">
+    <div class="card">
+      <h2>📖 人类使用手册</h2>
+      <p>安装、快速开始、参数说明、环境变量、审计维度、故障排查、与 scaffold 配合</p>
+      <a href="repo-audit/HUMAN-GUIDE.md">→ HUMAN-GUIDE.md</a>
+    </div>
+    <div class="card">
+      <h2>🤖 Agent 操作手册</h2>
+      <p>调用协议、输出解析、标准操作流程、错误处理、决策树、授权路径</p>
+      <a href="repo-audit/AGENT-GUIDE.md">→ AGENT-GUIDE.md</a>
+    </div>
+    <div class="card">
+      <h2>🔍 审计方法论</h2>
+      <p>评分体系、规则设计、维度划分、分类检测逻辑</p>
+      <a href="../AUDIT.md">→ AUDIT.md</a>
+    </div>
+    <div class="card">
+      <h2>📏 最佳实践</h2>
+      <p>工程仓库应满足的标准化检查项，按维度分类</p>
+      <a href="../BEST-PRACTICES.md">→ BEST-PRACTICES.md</a>
+    </div>
+    <div class="card">
+      <h2>🏷️ 分类检测</h2>
+      <p>18 种仓库类型识别逻辑，置信度评分，自动检测规则</p>
+      <a href="../REPO-CLASSIFICATION.md">→ REPO-CLASSIFICATION.md</a>
+    </div>
+    <div class="card">
+      <h2>🚀 脚手架生成</h2>
+      <p>从零生成符合规范的工程脚手架，支持 6 种分类</p>
+      <a href="../templates/README.md">→ templates/README.md</a>
+    </div>
+  </div>
+  <div class="quickstart">
+    <h2>⚡ 快速开始</h2>
+    <pre><code># 全局安装
+npm install -g repo-audit-tool
+# 审计仓库
+repo-audit --repo /path/to/repo
+# JSON 输出
+repo-audit --repo /path/to/repo --format json
+# 生成脚手架
+node templates/scaffold.mjs --type dsh-plugin --name my-plugin</code></pre>
+  </div>
+  <div class="feedback">
+    <h2>💬 反馈通道</h2>
+    <p>工具内置 <code>--feedback</code> 命令，一键创建 GitHub Issue（自动预填上下文）。也可通过以下方式反馈：</p>
+    <pre><code># 工具内反馈（自动预填审计结果）
+repo-audit --feedback "问题描述"
+# GitHub Issues
+https://github.com/NinjaSln-labs/repo-audit/issues
+# Bug 报告（预填模板）
+https://github.com/NinjaSln-labs/repo-audit/issues/new?template=bug_report.yml</code></pre>
+  </div>
+  <footer>
+    <p>Made with ❤️ by <a href="https://github.com/NinjaSln-labs">NinjaSln-labs</a> · MIT License · 2026</p>
+    <p><a href="https://github.com/NinjaSln-labs/repo-audit">GitHub</a> · <a href="https://www.npmjs.com/package/repo-audit-tool">npm</a></p>
+  </footer>
+</div>
+</body>
+</html>

package/docs/repo-audit/AGENT-GUIDE.md CHANGED Viewed

@@ -471,4 +471,57 @@ node repo-audit.mjs --repo <path> --format json \
 ---
-*Agent 操作手册 v1.2 · 2026-09-06（新增 monorepo 感知 P6 + .auditrc.yaml 豁免）
+## 十、反馈通道
+### 10.1 Agent 检测协议
+Agent 可通过 GitHub Issues API 检测用户反馈：
+```bash
+# 列出未处理的反馈（label: audit-feedback + state: open）
+gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open --json number,title,createdAt,body
+# 获取单条反馈详情
+gh issue view <NUMBER> --repo NinjaSln-labs/repo-audit --json title,body,labels,createdAt
+# 反馈已处理，关闭 Issue
+gh issue close <NUMBER> --repo NinjaSln-labs/repo-audit --comment "已处理：[处理说明]"
+```
+**标签语义**：
+- `audit-feedback` — 所有工具反馈（Agent 过滤条件）
+- `feedback` — 通用反馈（与 audit-feedback 同时存在）
+- `bug` — Bug 报告
+- `enhancement` — 功能建议
+- `documentation` — 文档问题
+### 10.2 Agent 创建反馈
+Agent 可通过 CLI 或 API 创建反馈 Issue：
+```bash
+# CLI 方式（自动预填环境信息）
+node repo-audit.mjs --feedback "在 xxx 场景下出现 yyy 问题"
+# API 方式（更灵活）
+gh issue create --repo NinjaSln-labs/repo-audit \
+  --title "Feedback: <简要标题>" \
+  --body "<Markdown 正文>" \
+  --label "feedback,audit-feedback"
+```
+### 10.3 反馈处理流程
+```
+用户反馈 → audit-feedback label → Agent 检测 → 分类处理 → 关闭 Issue
+    ↓                                    ↓
+GitHub Issues                    修复 / 文档 / 不采纳
+```
+**处理优先级**：
+1. `critical` — 工具崩溃/数据损坏（24h 内响应）
+2. `major` — 功能严重受损（72h 内响应）
+3. `minor` — 功能部分受损（1 周内响应）
+4. `info` — 建议改进（排期处理）
+*Agent 操作手册 v1.3 · 2026-09-06（新增反馈通道 §10）

package/docs/repo-audit/HUMAN-GUIDE.md CHANGED Viewed

@@ -746,4 +746,34 @@ grep -rE '<commit-SHA>|dsh-demo|demo-v' .github/workflows/ && echo "✗ 有残
 `npm ci`（无 lockfile）、`scripts/verify.mjs`（路径错误）、`main` 分支（实际 master）、
 `<commit-SHA>`（占位符未替换）四项同时失败，workflow 不触发。
+### 12.8 反馈通道
+**工具内反馈**（推荐，自动预填环境信息）：
+```bash
+repo-audit --feedback "在 monorepo 项目中 DOC-003b 规则误报"
+```
+效果：自动创建 GitHub Issue，包含反馈内容 + 工具版本 + Node.js 版本 + 平台信息。
+Agent 可通过 `gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback` 检测反馈。
+**GitHub Issues**：
+- [Bug 报告](https://github.com/NinjaSln-labs/repo-audit/issues/new?template=bug_report.yml) — 预填复现步骤/实际输出/期望输出
+- [功能反馈](https://github.com/NinjaSln-labs/repo-audit/issues/new?template=feedback.yml) — 建议/文档问题/性能问题
+- [全部 Issues](https://github.com/NinjaSln-labs/repo-audit/issues)
+**其他渠道**：
+- Discord/Slack：见 GitHub Discussions
+- 邮件：info@ninjasln-labs.com（仅安全问题）
+**Agent 反馈检测协议**：
+```bash
+# 检测新反馈
+gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open --json number,title,createdAt
+# 获取反馈详情
+gh issue view <NUMBER> --repo NinjaSln-labs/repo-audit
+# 反馈已处理
+gh issue close <NUMBER> --repo NinjaSln-labs/repo-audit --comment "已处理，感谢反馈"
+```

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "repo-audit-tool",
-  "version": "1.2.0",
+  "version": "1.2.3",
   "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
   "type": "module",
   "main": "repo-audit.mjs",
@@ -20,6 +20,10 @@
     "best-practices",
     "repository"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NinjaSln-labs/repo-audit"
+  },
   "engines": {
     "node": ">=18"
   },

package/repo-audit.mjs CHANGED Viewed

@@ -37,11 +37,11 @@ const DEFAULT_OUTPUT_DIR = 'audit-report'
 const KNOWN_FLAGS = new Set([
   '--repo', '--type', '--format', '--output',
   '--llm-provider', '--llm-model', '--llm-base-url', '--strict',
-  '--rules', '--dim', '--help', '-h'
+  '--rules', '--dim', '--help', '-h', '--feedback'
 ])
 const VALUE_FLAGS = new Set([
   '--repo', '--type', '--format', '--output',
-  '--llm-provider', '--llm-model', '--llm-base-url', '--rules', '--dim'
+  '--llm-provider', '--llm-model', '--llm-base-url', '--rules', '--dim', '--feedback'
 ])
 function parseArgs(argv) {
@@ -106,6 +106,7 @@ function usage() {
   --strict            严格模式：Critical/Major 发现即 exit 1
   --rules <file>      自定义规则文件（可多次）
   --dim <domain>      只审计指定维度（可多次，如 --dim security --dim docs）
+  --feedback <msg>    提交反馈（创建 GitHub Issue，自动预填环境信息）
   --help, -h          显示此帮助
 环境变量：
@@ -1406,6 +1407,43 @@ async function main() {
     process.exit(0)
   }
+  // Feedback 通道：创建 GitHub Issue（Agent 可检测）
+  if (args.flags['--feedback']) {
+    const message = args.flags['--feedback'] || '（未提供反馈内容）'
+    const label = 'feedback'
+    const body = `## 反馈内容
+${message}
+---
+## 环境信息
+- **工具版本**: ${readFileSync('package.json', 'utf-8').match(/"version":\s*"([^"]+)"/)?.[1] || 'unknown'}
+- **Node.js**: ${process.version}
+- **平台**: ${process.platform} ${process.arch}
+- **时间**: ${new Date().toISOString()}
+## 标签
+- ${label}
+- audit-feedback
+`
+    // 尝试通过 gh CLI 创建 Issue
+    const { execSync } = await import('node:child_process')
+    try {
+      const result = execSync(
+        `gh issue create --repo NinjaSln-labs/repo-audit --title "Feedback: ${message.slice(0, 60)}" --body "${body.replace(/"/g, '\\"').replace(/\n/g, '\\n')}" --label "${label},audit-feedback"`,
+        { encoding: 'utf-8', timeout: 30000 }
+      )
+      console.error(`✓ 反馈已提交: ${result.trim()}`)
+    } catch (e) {
+      console.error(`✗ gh CLI 不可用，请手动提交反馈：`)
+      console.error(`  https://github.com/NinjaSln-labs/repo-audit/issues/new?labels=${label},audit-feedback&body=${encodeURIComponent(body)}`)
+    }
+    process.exit(0)
+  }
   const repoPath = resolve(args.flags['--repo'] || '.')
   const forceType = args.flags['--type']
   const format = args.flags['--format'] || 'both'

package/HANDOFF.md DELETED Viewed

@@ -1,124 +0,0 @@
-# HANDOFF — repo-audit 工具（工程交接）
-## 1. 交接元信息
-- **日期**：2026-09-06
-- **交接方**：repo-audit 维护 agent
-- **接收方**：继续维护 repo-audit 的 agent / 新 session
-- **原因**：里程碑达成（开源发布完成）· 开发仓废弃，转入本开源仓
-- **项目一句话**：零依赖 Node.js ESM 仓库标准化审计工具 + 工程脚手架生成器
-- **主战场变更**：**本仓 `ninjasin-labs/repo-audit/` 现在是唯一开发与发布位置**；原开发仓 `dsh-ecosystem/research/scaffold-templates/` **已废弃**（历史快照，勿再改）
-- **文档入口链**（本仓内）：
-  - 会话记录：`ninjasin-labs/.agents/session.md`（进度权威）
-  - 人类手册：`docs/repo-audit/HUMAN-GUIDE.md`
-  - Agent 手册：`docs/repo-audit/AGENT-GUIDE.md`
-  - 自审报告：`docs/repo-audit/SELF-AUDIT.md`
-  - 影子回归：`docs/repo-audit/SHADOW-AUDIT-20260906-v3.md`
-- **接收方建议动作**：
-  1. 读 `ninjasin-labs/.agents/session.md` 了解反馈闭环全貌
-  2. 读 `docs/repo-audit/AGENT-GUIDE.md` 了解操作协议
-  3. 所有后续开发、迭代、审计验收都在**本仓**完成
-## 2. 当前状态快照
-### 版本控制状态
-| 项 | 值 |
-|---|---|
-| 主仓（本仓） | `ninjasin-labs/repo-audit/`（独立 git 仓） |
-| 分支 | master |
-| commits | 6（`11eaf65` → `bca65ff` → `cbb7e40` → `de44f20` → `abea615` → `43e9245`） |
-| 远端 | **已建** — `https://github.com/NinjaSln-labs/repo-audit`（公开） |
-| 废弃仓 | `dsh-ecosystem/research/scaffold-templates/`（历史快照，勿改） |
-### 最近完成（一行式）
-- `43e9245` fix(ci): 适配 repo-audit — 移除 dsh-demo 模板残留（CI 首次跑通）
-- `abea615` fix(engine): json_field monorepo 感知 + fallback_field 数组格式修复
-- `de44f20` fix(docs): 补充 AGENTS.md — 修复 CLAUDE.md 悬空引用 + 多文档断链
-- `bca65ff` 开源就绪 — 补充工程规范 + 验证链 + 测试（自审计 100/A）
-- `11eaf65` repo-audit 开源初始提交
-- （开发仓历史，已废弃，仅参考）`e99b504` P6 monorepo / `bcf21d3` E5 豁免 / `053c524` E6 序列化 / `ca01f00` fuyao 假阳性修复
-### 构建环境状态
-- **零 npm 依赖**，无需 install
-- 自审计 **100/A**（19/19 pass）
-- 测试：`node --test` 3 用例通过；`node verify.mjs` 4 项通过
-- Node ≥18
-### 占位/未完成边界
-- **json_field 检查器**：仅读仓库根 `package.json`，不递归 workspace（neonforge DOC-003b 残留 minor，非阻塞）
-- **GitHub 远端发布未执行**：本地 git 就绪，`gh repo create` / 首次 push 待用户
-## 3. 下一步与验证点
-### 立即待办（按优先级）
-1. ~~**发布到 GitHub 远端**~~ ✅ `NinjaSln-labs/repo-audit` 已公开（2026-09-06）
-2. ~~**json_field workspace 支持**~~ ✅ `abea615` 修复（含 fallback_field 数组格式预存 bug）
-3. ~~**验证 CI**~~ ✅ `43e9245` 修复 dsh-demo 模板残留，CI 首次跑通
-4. **可选**：npm 发布（需 npm 端配置 OIDC trusted publisher）
-### 外部依赖来源
-- 无 API Key / 凭据依赖（工具可选 LLM 增强，Key 由用户运行时提供，不落仓）
-- GitHub 远端发布需用户账号权限
-### 风险提醒
-- 本仓此前无 .git 时自审计 GIT-001 会 fail；已 commit 后正常
-- json_field workspace 盲区影响 monorepo license 一致性检查（minor）
-## 4. 即时操作
-```bash
-# 本仓自审计
-cd ninjasin-labs/repo-audit
-node repo-audit.mjs --repo . --format json
-# 验证链
-node verify.mjs
-node --test
-# 全仓影子回归（ninjasin-labs 下其他仓，可选）
-for repo in $(find /home/shadow/ninjasin-labs -maxdepth 3 -name .git -type d | sed 's|/.git$||'); do
-  node repo-audit.mjs --repo "$repo" --format json 2>/dev/null | grep -o '评分: [0-9]*'
-done
-```
-### 已知坑
-- 引擎对**非 git 仓**输出到 stderr（`✗ 目标不是 git 仓库`），不产生 JSON——verify.mjs 需用 git 仓
-- `glob_count` 无法遍历隐藏目录（`.github/`）——CI 检查用 `regex`+`command` 方案而非 glob_count
-- `.auditrc.yaml` 解析是简单行解析，`reason` 只取单行且去引号，长 reason 需保持单行
-## 5. 引用索引
-| 主题 | 权威文档 |
-|---|---|
-| 会话/进度权威 | `ninjasin-labs/.agents/session.md` |
-| 人类使用手册 | `docs/repo-audit/HUMAN-GUIDE.md` |
-| Agent 操作协议 | `docs/repo-audit/AGENT-GUIDE.md` |
-| AI 协作纪律 | `AGENTS.md` |
-| 工具自审 | `docs/repo-audit/SELF-AUDIT.md` |
-| 全仓影子回归 | `docs/repo-audit/SHADOW-AUDIT-20260906-v3.md` |
-| 反馈闭环（fuyao） | `docs/repo-audit/FEEDBACK-fuyao-nomad.md` |
-| 反馈闭环（neonforge） | `docs/repo-audit/FEEDBACK-neonforge.md` |
-| 审计方法论 | `AUDIT.md` |
-| 最佳实践标准 | `BEST-PRACTICES.md` |
-| 分类检测 | `REPO-CLASSIFICATION.md` |
-| 核心引擎 | `repo-audit.mjs` |
-| 审计规则 | `rules/`（domains + categories） |
-| 脚手架生成器 | `templates/scaffold.mjs` |
-| 废弃开发仓（仅历史参考） | `dsh-ecosystem/research/scaffold-templates/` |
-## 6. 维护规则
-- **更新时机**：跨 session / 里程碑 / 用户要求交接时
-- **防双源**：本文件只记 delta，文档与 commit 已有内容引用不复制
-- **滚动归档**：已确认修复的坑 → `HANDOFF-ARCHIVE/pits.md`，已完成待办 → `HANDOFF-ARCHIVE/done.md`
-- **回填约定**：改动规则/引擎后，同步更新 `docs/repo-audit/HUMAN-GUIDE.md` 和 `AGENT-GUIDE.md`
-- **脱敏**：不含 API Key/密码/PII（本交接含 `ninjasin-labs` 内部路径，若 push 公开前需注意；或建 .gitignore 排除 HANDOFF.md）
-- **主战场**：所有开发在本仓完成，废弃仓不再同步