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

repo-audit-tool 1.2.1 → 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 (7) hide show

package/PUBLISHING.md CHANGED Viewed

@@ -4,12 +4,17 @@
 | 项 | 状态 |
 |---|---|
-| npm | `repo-audit-tool` v1.2.0（已发布，latest） |
+| 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）
@@ -44,11 +49,11 @@ git push && git push --tags
 ## 首次发布（已完成）
 1. **npm 包创建**：`npm publish --access public`（v1.2.0，2026-09-06）
-2. **Trusted Publisher 配置**（下一步）：npmjs.com → 包设置 → Trusted Publisher →
+2. **Trusted Publisher 配置**：npmjs.com → 包设置 → Trusted Publisher →
    - Repository: `NinjaSln-labs/repo-audit`
    - Workflow: `publish.yml`
-   - Branch: `master`
-3. **验证**：`npm view repo-audit-tool dist-tags` → `{ latest: '1.2.0' }` ✓
+   - Branch: `master`（注：tag 触发场景 npm 亦放行，v1.2.2 实测通过）
+3. **验证**：`npm view repo-audit-tool dist-tags` → latest 已更新 ✓
 ## 发布后验证

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 CHANGED Viewed

@@ -4,6 +4,31 @@
   <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; }
@@ -61,12 +86,13 @@
   <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>
-      <a href="../REPO-CLASSIFICATION.md">分类检测</a>
-      <a href="../PUBLISHING.md">发布流程</a>
     </div>
   </div>
@@ -90,6 +116,32 @@
     <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>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "repo-audit-tool",
-  "version": "1.2.1",
+  "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/HANDOFF.md DELETED Viewed

@@ -1,131 +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 | 10（`11eaf65` → `bca65ff` → `cbb7e40` → `de44f20` → `abea615` → `43e9245` → `eea507a` → `45fbfb9` → `b3a2e8f` → `ef967fd` → `4318ae1`） |
-| 远端 | **已建** — `https://github.com/NinjaSln-labs/repo-audit`（公开） |
-| npm | **已发布** — `repo-audit-tool` v1.2.0（latest） |
-| 废弃仓 | `dsh-ecosystem/research/scaffold-templates/`（历史快照，勿改） |
-### 最近完成（一行式）
-- `4318ae1` docs(release): PUBLISHING.md 更新 — 反映 Trusted Publisher 流程
-- `ef967fd` chore(release): 发布 repo-audit-tool@1.2.0 到 npm
-- `b3a2e8f` chore(release): 发布准备 — 改名 + bin 可执行 + PUBLISHING.md
-- `45fbfb9` fix(engine): C 优化补充 — fallback_field 逗号分隔字符串检测
-- `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 发布**~~ ✅ `repo-audit-tool@1.2.0` 已发布（latest）
-5. **下一步**：npmjs.com 配置 Trusted Publisher → Repository: `NinjaSln-labs/repo-audit`, Workflow: `publish.yml`, Branch: `master`
-### 外部依赖来源
-- 无 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` |
-| 发布流程 | `PUBLISHING.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）
-- **主战场**：所有开发在本仓完成，废弃仓不再同步