| name | harness-gate-scan |
| version | 1.7.1 |
| description | 在提交前对任意项目跑静态代码分析（HarnessToolKit Gate Engine 17 个规则文件）+ PII 敏感信息扫描（72 条规则 / 9 大类）+ Skill 规范合规扫描（11 必选 + 23 可选）。覆盖任意语言项目的代码质量/安全/命名/容器/API 规则，以及身份证、银行卡、手机号、API Key、私钥、连接串、内网 IP、客户金融机构名称等敏感信息，含 JR/T 0171-2020 金融分级对照与 PCI-DSS 脱敏要求。适用于金融行业代码提交前自检、CI 静态扫描卡点、敏感信息脱敏审查、skill 入库规范审查等场景。跨平台（Windows/Mac/Linux）、跨工具（Claude Code / Trae / Codex）。触发词：静态扫描、static scan、code quality check、扫安全规则、gate check、HarnessToolKit、PII扫描、敏感信息扫描、脱敏、身份证/银行卡/手机号扫描、JR/T 0171。 |
HarnessToolKit Gate 静态扫描
概述
用 HarnessToolKit 的 Gate Engine 对任意项目做静态扫描：遍历源文件 × 17 个规则文件，调 gate check --stdin 收集未通过项，输出 TSV 报告。同时对 PII 与敏感信息做正则扫描（身份证、银行卡、手机号、API Key、私钥、连接串、内网 IP、客户金融机构名称 等共 72 条规则），含金融行业 JR/T 0171-2020 分级对照与 PCI-DSS 脱敏要求。
默认行为：Gate + PII + Skill-spec 三合一扫描，一次调用三份结果合并到同一份 TSV。用 --gate-only / --pii-only / --skill-spec 切换只跑其一。自带跨平台 Node.js 脚本 scan.mjs + 规则文件 pii-rules.mjs / skill-spec-rules.mjs，零外部 npm 依赖，Windows/Mac/Linux 均可运行。
关键事实：HarnessToolKit 仓库（https://gitcode.com/SETools/HarnessToolKit）不包含 scan-project.mjs 这类汇总脚本，只有 gate check --stdin 单文件检查能力。本 skill 的 scan.mjs + 规则文件随 skill 分发。
角色定义
静态扫描助手：负责在代码提交前对项目做结构化规则扫描与敏感信息扫描，输出 TSV 报告供提交者修复。不修改代码、不运行测试、不做架构判断。
所属领域
研发工具链 / 代码质量与安全合规（金融行业 JR/T 0171-2020 数据分级对照）。
触发条件
- 用户要求对项目跑静态扫描、代码质量检查、安全规则扫描
- 用户要检查硬编码密钥、命名规范、容器安全、API 安全、PII / 敏感信息（身份证、银行卡、手机号、API Key、人名、内网 IP、客户金融机构名称）
- 提交前自检（PR 模板里的"静态扫描结果"一节）
- 用户提到 HarnessToolKit、Gate Engine、gate check
- 用户要检查 skill 目录是否合规于
Skill编写规范.docx
不适用：运行时动态检查、单元测试、E2E 测试。
目标
一次调用产出三份结果合并到同一份 TSV：Gate Engine 规则扫描（17 个规则文件）+ PII 敏感信息扫描（72 条规则 / 9 大类）+ Skill 规范合规扫描（11 必选 + 23 可选检查项）。让提交者在 PR 阶段一次性看清 error/warning/suggestion 分布与命中样例，阻断 C3 级敏感信息入仓。
在不同 AI 工具中加载本 skill
本 skill 由五个文件组成：SKILL.md（本文档）、VERSION（版本与适配 commit）、scripts/scan.mjs（扫描主程序）、scripts/pii-rules.mjs（PII 规则定义）、scripts/skill-spec-rules.mjs（Skill 规范规则定义）。三个 .mjs 都在 scripts/ 子目录下，scan.mjs 通过相对路径 import 引用两个规则文件。
不同工具 skill 目录不同（Claude Code 在 ~/.claude/skills/、Codex 在 ~/.agents/skills/、Trae 在其 agent 配置目录），按下方"定位 scan.mjs"三步法找到 $SKILL_DIR。若工具不识别 skill 目录结构，把 scripts/ 下三个 .mjs 一起复制到任意位置直接调用即可——脚本是自包含的 Node.js。
三个 .mjs 必须放在同一目录——scan.mjs 顶部用相对路径 import 引用 pii-rules.mjs 与 skill-spec-rules.mjs，缺一个就会报 Cannot find module './xxx-rules.mjs'。
定位 scan.mjs（执行扫描前必读）
不同 AI 工具的 skill 目录不同，$SKILL_DIR 不是固定值。执行扫描前必须先确定 scan.mjs 的绝对路径，按以下顺序尝试：
- 检查环境变量：
echo "$HARNESS_GATE_SKILL_DIR"，若已设值且该路径下同时存在 scripts/scan.mjs、scripts/pii-rules.mjs、scripts/skill-spec-rules.mjs，直接用
- 搜索本机常见 skill 目录：
find ~/.claude/skills ~/.agents/skills ~/.trae/skills ~/Library/Application\ Support/Trae/skills \
~/.config/trae/skills /opt/trae/skills \
-type f -name scan.mjs -path '*harness-gate-scan*' 2>/dev/null
找到的路径就是 $SKILL_DIR。若没覆盖到你的工具，扩大搜索：find ~ -type f -name scan.mjs -path '*harness-gate-scan*' 2>/dev/null | head -5
- 询问用户：若前两步都无结果，不要凭空猜测路径，直接问用户要绝对路径。若用户也确认本机文件不全，让用户重新从 skill 包解压安装（含
SKILL.md + VERSION + scripts/ 下三个 .mjs，缺一不可）
同时确认 $SKILL_DIR/scripts/ 下还有 pii-rules.mjs 和 skill-spec-rules.mjs——缺任一个会报 Cannot find module './xxx-rules.mjs'，需重新解压完整 skill 包。
验证定位成功：node <你找到的路径>/scripts/scan.mjs --help 2>&1 | head -3，应输出用法说明，不报 Cannot find module。
前置要求
本机必须已安装 Node.js ≥ 18（scan.mjs 用了 ESM .mjs 语法与 execFileSync，低版本会报错）。验证：node --version 应输出 v18.x.x 或更高。未安装或版本过低，到 https://nodejs.org 下载 LTS 版安装。
依赖说明：scan.mjs 本身零外部 npm 依赖（仅用 Node.js 内置模块），不需要在 skill 目录跑 npm install。但 scan.mjs 驱动的 HarnessToolKit CLI（dist/cli.cjs）有自己的依赖，需在 HarnessToolKit 仓库跑 npm install && npm run build（见第一步）。
第一步：加载 HarnessToolKit
HarnessToolKit 必须先在本地准备好（含 dist/cli.cjs 和 .harness/gates/rules/）。
方式 A：源码克隆（全量扫描必走，推荐）
git clone https://gitcode.com/SETools/HarnessToolKit.git
cd HarnessToolKit
npm install
npm run build
node dist/cli.cjs version
若未设 git config --global user.email，version 命令会打印遥测提示，正常现象，不影响功能。设邮箱或加环境变量 HARNESS_TELEMETRY_DISABLED=1 可静默。
方式 B：发布包全局安装（仅单文件检查/修复，不能全量扫描）——从 release/ 目录手动下载 tgz，npm install -g ./harness-rd-toolkit-0.1.0-<日期>.tgz。发布包不含 .harness/gates/rules/，所以全量扫描必须走方式 A。
版本对齐强制阻断（v1.7.0 起）
本 skill 在 VERSION 文件里标注了适配的 HarnessToolKit commit（如 适配 HarnessToolKit: 594412a）。HarnessToolKit 规则频繁刷新（c7d3586 → 594412a 期间，java-coding-style.yaml 从 ~20 条扩到 213 条，python-coding-style.yaml 扩到 192 条），版本不一致会导致规则覆盖差异，silently 扫出过时结果比报错更危险。
scan.mjs 启动时检测本机 HarnessToolKit 的实际 commit 与 VERSION 标注对比，不匹配时直接 exit 10 阻断扫描（仅 Gate 模式校验；--pii-only / --skill-spec 不依赖 HarnessToolKit 规则，跳过校验）。任一 commit 无法确定（非 git 仓库 / VERSION 缺失）时静默跳过。
对齐方式 1（推荐，跟随上游）：
cd <HarnessToolKit 目录>
git fetch origin && git checkout main && git pull origin main
npm install && npm run build
git rev-parse --short HEAD
对齐方式 2（锁定到 skill 适配版本）：
cd <HarnessToolKit 目录>
git fetch origin && git checkout <VERSION 标注的 commit>
npm install && npm run build
第二步：跑全量扫描
默认同时跑 Gate + PII + Skill-spec 三合一：
node $SKILL_DIR/scripts/scan.mjs <项目根目录> \
--toolkit <HarnessToolKit 路径> \
--report <TSV 输出路径>
参数：
<项目根目录>：必填，要扫描的项目--toolkit：HarnessToolKit 根目录（Gate 扫描必需；--pii-only 时不需要）。未指定时依次查 $HARNESS_TOOLKIT_DIR、~/HarnessToolKit、~/code/HarnessToolKit、/opt/HarnessToolKit、./HarnessToolKit--report：TSV 报告输出路径。指定后报告写文件；不指定则 TSV 走 stdout，可 > report.tsv 重定向。汇总信息始终走 stderr，不会污染 TSV--rules：逗号分隔 Gate 规则名（不含 .yaml），默认全部 17 个--gate-only：仅扫 Gate，跳过 PII / Skill-spec--pii-only：仅扫 PII，跳过 Gate（不需要 HarnessToolKit）--skill-spec：仅扫 skill 目录规范合规性，跳过 Gate / PII（不需要 HarnessToolKit）--fix：Gate 扫描后调 gate fix 自动修复 3 类规则（var→const / tabs→2空格 / 删 console.debug）。与 --pii-only/--skill-spec/--pre-edit 互斥--html <path>：同时输出 HTML 报告（自生成，零依赖，含汇总卡片 + 三段折叠表 + 严重度色码）--pre-edit <file>：增量模式，从 stdin 读 content（或 stdin 空时自动从磁盘读 <file>），binding=pre-edit 传 edit.content，跳过 full-only 规则；只跑 Gate--git-diff <base>：CI 模式，git diff --name-only <base>...HEAD 拿改动文件列表，全量扫这些文件--help：查看用法
示例：
node $SKILL_DIR/scripts/scan.mjs /path/to/any-project \
--toolkit ~/code/HarnessToolKit --report /tmp/scan.tsv
node $SKILL_DIR/scripts/scan.mjs /path/to/any-project \
--toolkit ~/code/HarnessToolKit --gate-only --report /tmp/gate.tsv
node $SKILL_DIR/scripts/scan.mjs /path/to/any-project --pii-only --report /tmp/pii.tsv
v1.7.0 新增 flag 用例
node $SKILL_DIR/scripts/scan.mjs /path/to/project --toolkit ~/code/HarnessToolKit \
--gate-only --fix --report /tmp/scan.tsv
node $SKILL_DIR/scripts/scan.mjs /path/to/project --toolkit ~/code/HarnessToolKit \
--report /tmp/scan.tsv --html /tmp/report.html
cat src/main.js | node $SKILL_DIR/scripts/scan.mjs /path/to/project \
--toolkit ~/code/HarnessToolKit \
--pre-edit src/main.js --gate-only --report /tmp/edit.tsv
node $SKILL_DIR/scripts/scan.mjs /path/to/project --toolkit ~/code/HarnessToolKit \
--git-diff origin/main --report /tmp/scan.tsv
flag 交互矩阵：
| 模式 | Gate | PII | Skill-spec | Fix | HTML |
|---|
| 默认 | ✓ | ✓ | ✓ 自动 | ✗ | ✓ |
--gate-only | ✓ | ✗ | ✗ | ✓ | ✓ |
--pii-only | ✗ | ✓ | ✗ | ✗ | ✓ |
--skill-spec | ✗ | ✗ | ✓ | ✗ | ✓ |
--pre-edit <f> | ✓ | ✗ | ✗ | ✗ | ✓ |
--git-diff <b> | 受 --gate-only/--pii-only/--skill-spec 控制 | | | ✓（gate 模式下） | ✓ |
互斥：--pre-edit 与 --pii-only/--skill-spec/--git-diff exit 8；--fix 与 --pii-only/--skill-spec/--pre-edit warn + skip。
何时使用 --fix / --pre-edit（AI 助手决策指南）
--fix 唤起场景：提交前自检发现 practice-no-var / format-no-tabs / review-no-console-debug-leftovers 命中 > 5 条 → 主动建议用户「要我自动修这几条吗」，同意后跑 --fix。AI 助手刚改完文件怀疑引入可机械修复违规 → --fix 自动修，再跑一次扫描确认。不该唤起：PR review 审计 / 生产分支保护 / 合规统计 / --pii-only/--skill-spec 模式。
--pre-edit 唤起场景：编辑器 hook 实时检查未保存 buffer（<1s 返回，跳过 full-only 规则）；AI 助手编辑代码时实时反馈；CI pre-commit hook 检查 staged 文件。不该唤起：提交前全量自检 / PR 审计 / 首次扫描新项目 / CI 跑 PR 改动文件（用 --git-diff）/ 扫 PII/Skill 规范。
核心区别：--fix 改代码（全量作用域、post-edit binding、有副作用、数秒~数十秒）；--pre-edit 只检查不改代码（单文件、pre-edit binding 跳过 full-only、无副作用、<1s）。
扫描覆盖的文件类型
扫描分两层：Gate 层（结构化代码规则）只扫源码 + YAML + HTML + Markdown，避免对 JSON/CSV 产生格式类误报；PII 层（敏感信息扫描）覆盖所有文本类文件（含 Office 文档 zip+XML 解压提取），是脱敏检查的重点。
| 类别 | 扩展名 / 文件名 | Gate | PII |
|---|
| 源码 | .py .js .jsx .ts .tsx .mjs .cjs .vue .svelte .astro .java .kt .scala .groovy .go .rs .c .cpp .cs .php .rb .swift .lua .sh .ps1 .proto .graphql 等 60+ 种 | ✓ | ✓ |
| 容器 / 特殊文件名 | Dockerfile、Makefile、Gemfile、Jenkinsfile、BUILD、WORKSPACE 等 | ✓ | ✓ |
| 配置 - YAML | .yml .yaml | ✓ | ✓ |
| 配置 - JSON/TOML/INI/XML/IaC | .json .toml .ini .xml .tf .hcl 等 | ✗ | ✓ |
| 环境变量 | .env、.env.* | ✗ | ✓ |
| Web - HTML | .html .htm .xhtml | ✓ | ✓ |
| Web - 样式/模板 | .css .scss .ejs .hbs .pug .njk 等 | ✗ | ✓ |
| 文档 - Markdown | .md .markdown .mdx | ✓ | ✓ |
| 文档 - 纯文本/Office | .txt .rst .adoc .docx .xlsx .pptx（Office zip+XML 解压） | ✗ | ✓ |
| 数据 | .csv .tsv .sql .psql | ✗ | ✓ |
自动排除目录：node_modules venv .venv dist build __pycache__ .git .cache logs proxy-logs .pytest_cache target bin obj .next .nuxt .turbo .parcel-cache coverage .nyc_output .gradle .idea .vscode。跳过文件：echarts-offline.js、scan.mjs、cli.cjs，以及各类 lock 文件。PII 扫描额外跳过二进制/大型生成文件（.png .jpg .svg .pdf .zip .gz .exe .dll .class .pyc .min.js .min.css 等）。Office 文件 >50MB 跳过（zip bomb 防护）。
语言专用规则说明：17 个规则中 python-coding-style 仅对 Python 文件触发、java-coding-style 仅对 Java 文件触发、advanced-analysis 对 Java/Python 文件触发；doc-structure/language-style/content-elements 三个文档规范规则仅对 Markdown 文件触发；其余 12 个通用规则（安全、命名、格式、API、容器等）对所有代码文件都生效。Gate Engine 的 includes 字段自动按文件扩展名筛选规则，文档规则不会扫代码、代码规则也不会扫 Markdown。
JSON/CSV 不进 Gate 层：Gate 规则含 format-prefer-single-quote、format-line-width-limit 等，对 JSON（双引号）会大量误报。这些文件只走 PII 层扫敏感信息。
规则文件 17 个
位于 HarnessToolKit 的 .harness/gates/rules/：
| 规则文件 | 覆盖范围 |
|---|
security-design / security-design-extended / security-redline / security-checklist | 安全设计基线、扩展、红线、检查清单（硬编码密钥、SQL/命令注入、输入校验等） |
container-security | 容器安全（针对 Dockerfile） |
api-security | API 安全（CSRF、XSS、审计日志、参数校验） |
naming-convention / code-format / code-practice | 命名规范、代码格式、代码实践 |
contributing-compliance | 贡献规范（IP 地址、MAC 地址） |
code-review | 代码评审项 |
java-coding-style / python-coding-style | Java / Python 编码风格（仅对应语言文件触发） |
advanced-analysis | 高级代码规则（华为 Java/Python 编程规范，空指针、资源泄漏、并发安全等深度模式） |
doc-structure / language-style / content-elements | 文档结构 / 语言风格 / 内容元素规范（仅 Markdown 文件触发） |
仓库 .harness/gates/rules/ 下还有 arch-driven-overview（文档架构类）和 req-*/telemetry-*/scaffold-paths-drift（HarnessToolKit 自身契约漂移类），与源码/文档扫描无关，不启用。
第三步：读报告
TSV 6 列：file、ruleId、severity、message、rulesFile、line。例：
src/main.py py-no-catch-except-base warning 不应直接捕获 Exception 基类 code-practice 42
web/app.js contrib-no-ip-address error 代码中不应包含公网 IP 地址 contributing-compliance 15
严重度分级：
error 红线，必须修复才能提交（硬编码密钥、SQL 注入、公网 IP 等）warning 警告，应修复，确属误报在 PR 说明suggestion 建议，酌情处理
常用筛选（bash / awk）
REPORT=/tmp/scan.tsv
awk -F'\t' 'NR>1 && $3=="error"' "$REPORT"
awk -F'\t' 'NR>1{print $2}' "$REPORT" | sort | uniq -c | sort -rn
awk -F'\t' 'NR>1{print $1}' "$REPORT" | sort | uniq -c | sort -rn | head
awk -F'\t' -v f="src/main.py" 'NR>1 && $1==f' "$REPORT"
Windows PowerShell 用 Import-Csv -Path C:\tmp\scan.tsv -Delimiter "t"，然后 Where-Object { $_.severity -eq 'error' }。用 awk避免 macOS BSD grep 不支持grep -P` 的问题。
第四步：单文件检查与自动修复
调试单文件、或 CI 里只查改动文件，直接调 HarnessToolKit CLI（在 HarnessToolKit 根目录）：
echo '{"binding":"post-edit","rulesFile":"/path/to/HarnessToolKit/.harness/gates/rules/security-design.yaml","projectRoot":"/path/to/project","edit":{"filePath":"src/main.py"}}' \
| node dist/cli.cjs gate check --stdin
node dist/cli.cjs gate fix /path/to/project/src/main.py
gate fix 只修可机械修复的项，其余手动改。本 skill 的 --fix flag 封装了多文件批量修复逻辑。
第五步：PII 与敏感信息扫描
Gate Engine 的 17 条规则是结构化代码规则（命名、安全设计模式等），不识别项目特定的 PII（身份证、银行卡、手机号、API Key、私钥、连接串、人名、业务标识符、内网地址）。本 skill 的 PII 扫描覆盖 72 条规则，分 9 大类，规则定义在 pii-rules.mjs：
类别（pii-<cat>） | 覆盖范围 | 严重度 |
|---|
cloud | AWS / 阿里云 / 华为云 / 腾讯云 / Azure / GCP 的 AK/SK、API Key | error |
ai | OpenAI / Anthropic / 智谱 GLM / 百度千帆 / Cohere / HuggingFace / Replicate | error/warning |
token | Bearer / JWT / GitHub / GitLab / Slack / Discord / npm / PyPI / Stripe / Twilio / SendGrid | error/warning |
im | 飞书 / 钉钉 / 企业微信 的 App Secret 与 Webhook | error |
key | RSA / EC / DSA / PGP / OpenSSH / PEM / Encrypted PEM 私钥头 | error |
db | MySQL / PostgreSQL / MongoDB / Redis / SQL Server / Oracle 连接串，通用密码字段 | error/warning |
pii | 中国大陆 手机号 / 身份证 / 护照 / 港澳通行证 / 军官证 / 统一社会信用代码 / 组织机构代码 / 银行卡（Luhn 校验） | warning/suggestion |
net | 内网 IP / IPv6 link-local / 邮箱 / MAC 地址 / 32 位 hex / UUID | warning/suggestion |
customer | 客户金融机构名称（银行/保险/证券）：全称（工商银行/中国银行/太平洋保险/中国人寿/国泰君安…）+ 缩写（工行/建行/太保/人保/国寿…，民生/华夏/太平 需带业务后缀） | warning |
规则正则与 severity 全部在 pii-rules.mjs，可读可改。例如想新增"客户名称"扫描，可在该文件追加规则。人名这类无法用通用正则覆盖，建议在 PR 流程里人工 review dataset/、测试数据；金融机构名已由 customer 类覆盖。
运行 PII 扫描
默认全量扫描已包含 PII 扫描，无需单独跑。若只想跑 PII（跳过 Gate，无需 HarnessToolKit）：
node $SKILL_DIR/scripts/scan.mjs /path/to/any-project --pii-only --report /tmp/pii.tsv
PII 命中在 TSV 报告里以 pii-<cat> 形式出现在 rulesFile 列。汇总信息（stderr）会显示 [PII 分类] cloud=X token=Y pii=Z ...，便于一眼看清敏感信息分布。
金融行业 PII 分级对照（JR/T 0171-2020）
中国人民银行《个人金融信息保护技术规范》将个人金融信息按敏感度分 C1/C2/C3 三级，各级脱敏要求不同。本 skill 的 PII 规则按严重度对应：
| 级别 | 对应数据 | PII 规则 | 严重度 | 处置 |
|---|
| C3 | API Key、私钥、连接串密码、银行卡磁道/CVN、密码、动态验证码、生物特征 | *-access-key / *-secret-key / *-private-key / *-conn / password-field | error | 完全清除，禁止入仓 |
| C2 | 客户身份证号、手机号、支付账号、银行卡有效期、家庭住址、账户余额、交易记录 | cn-id-card / cn-phone / bank-card | warning | 掩码（身份证前3+末尾顺序号中间 *；手机号前3+末2如 138******01；银行卡首6末4，PCI-DSS 要求） |
| C1 | 账户开户时间、开户机构、账户状态 | 业务字段，无通用正则 | suggestion | 可保留，标注非敏感 |
C3 级原则：不应入仓、不应委托外部处理、销毁需不可恢复。扫描发现 C3 痕迹（任何 error 级 PII 命中）立即清除，不只是脱敏。详表与脱敏处理原则见 pii-rules.mjs 注释。
银行卡号 Luhn 校验
13-19 位连续数字会大量误报（时间戳、订单号、版本号）。bank-card 规则命中 13-19 位数字后会再过一遍 Luhn 校验，不通过就丢弃。PCI-DSS 要求展示时掩码为"首6末4"（如 00000000****0000000），存储时加密或 tokenization。
脱敏处理原则
- 保留文件结构与跨文件引用，只替换值——不要因脱敏破坏 JSON/YAML 结构或配置项的键名
- 分级脱敏：C1 可保留或轻度掩码，C2 掩码（保留可识别前缀+后缀），C3 完全清除
- 配置文件：真实 URL/Key 替换为模板占位（
https://<your-host>/v1/<app_id>/...、{{ASSISTANT_API_KEY}}），运行时从环境变量注入
- 测试数据：占位号（如
138****0000、110000000000000000）可保留；真实数据必须替换
- 业务标识符（workspace_id/project_id/app_id）：清空值，但跨文件引用 ID 保留——无脑正则替换所有 32-hex 会破坏
level2_resources 引用 ID
第六步：Skill 规范合规扫描
针对提交入库的 skill 目录做规范合规检查，依据 Skill编写规范.docx。规则定义在 skill-spec-rules.mjs。有两种触发方式：
自动发现（默认模式自带）：默认模式（Gate + PII）下，walk 遍历目录时若发现 SKILL.md，会自动记录其所在目录为 skill 目录，扫描完成后对每个 skill 跑规范检查，结果合到同一份 TSV（rulesFile 列为 skill-spec）。无需任何额外参数。汇总信息会多出一行 [Skill规范] 自动发现 N 个 skill 目录，规范检查 M 项（error=X / suggestion=Y）。
显式单 skill 扫描（--skill-spec）：只扫一个 skill 目录（项目根就是 skill 本身），跳过 Gate/PII，不需要 HarnessToolKit：
node $SKILL_DIR/scripts/scan.mjs <skill-dir> --skill-spec --report /tmp/spec.tsv
适用场景：单个 skill 入库前自检、Review 别人的 skill PR、不关心代码/PII 只看 skill 结构合规性。
检查项
必选（error 级，缺失即不合规）：
| 规则 ID | 检查内容 |
|---|
skill-spec-file-exists | SKILL.md 文件存在 |
skill-spec-frontmatter-exists | frontmatter 合法（开头 --- ... ---） |
skill-spec-frontmatter-name | frontmatter 含 name 字段 |
skill-spec-frontmatter-description | frontmatter 含 description 字段 |
skill-spec-frontmatter-version | frontmatter 含 version 字段 |
skill-spec-name-format | name 格式 {业务域}-{能力关键词}（至少 2 段，用 - 分隔，如 harness-gate-scan / fund-risk-credit） |
skill-spec-description-trigger | description 含「触发词：xxx」标记。规范模板：技能描述。适用于相关业务场景 触发词：xxx、xxx——技能描述在前、适用场景居中、触发词列表收尾，三段缺一不可。检查规则目前只硬性校验「触发词：」标记是否存在，技能描述与适用场景的完整性由人工 review |
skill-spec-section-role-definition | 正文含 ## 角色定义 章节 |
skill-spec-section-domain | 正文含 ### 所属领域 子节 |
skill-spec-section-trigger-condition | 正文含 ## 触发条件 章节 |
skill-spec-section-goal | 正文含 ## 目标 章节 |
可选（suggestion 级，缺失仅提示）：23 个可选字段——前置条件 / 金融属性 / 合规要求 / 输入参数 / 输出参数 / 能力清单 / 工作流程 / 工作流节点 / 输出格式 / 系统依赖 / MCP 工具调用 / 关联技能 / 合规约束 / 降级策略 / 记忆管理 / 评估指标 / 审计日志 / 免责声明 / 注意事项 / 结束条件 / 输入输出示例 / 边缘场景 / 文件引用。
error=0 即合规，可以入库；error>0 必须修复必选项后重新提交。报告筛选：
awk -F'\t' 'NR>1 && $3=="error"' spec.tsv
awk -F'\t' 'NR>1 && $3=="suggestion"{print $4}' spec.tsv
常见错误
| 症状 | 原因 | 修复 |
|---|
Cannot find module 'scan-project.mjs' | 引用了 HarnessToolKit 仓库未提交的脚本 | 用本 skill 的 scan.mjs，不要找 scan-project.mjs |
错误: 找不到 HarnessToolKit | scan.mjs 没定位到工具目录 | 用 --toolkit <path> 显式指定，或设 HARNESS_TOOLKIT_DIR 环境变量 |
dist/cli.cjs 不存在 | 源码克隆后没跑 npm run build | 在 HarnessToolKit 根目录执行 npm install && npm run build |
错误: HarnessToolKit 版本不匹配，扫描终止 (exit 10) | 本机 commit 与 VERSION 标注不一致 | 按第一步「版本对齐强制阻断」两种方式之一对齐，然后更新 VERSION 文件 |
| 遥测警告刷屏 | 未设 git config --global user.email | 设一个邮箱，或加环境变量 HARNESS_TELEMETRY_DISABLED=1（scan.mjs 已自动加） |
| Windows 跑不了 shell 命令 | 旧文档用 bash find/while read | 本 skill 的 scan.mjs 是纯 Node.js，跨平台直接跑 |
macOS grep -P 报 option not supported | BSD grep 不支持 PCRE | 用 awk -F'\t' 'NR>1 && $3=="error"' 替代，见第三步 |
| Dockerfile 违规没被扫到 | 旧脚本只扫 .py/.js/.ts | 本 skill 的 scan.mjs 已覆盖 Dockerfile*/.html/.yml 及更多语言 |
| Trae / 其他工具找不到 scan.mjs | skill 目录路径与 Claude Code 不同，$SKILL_DIR 未替换成实际路径 | 按"定位 scan.mjs"三步法定位；定位失败说明 skill 安装不完整（缺 scan.mjs），重新解压完整 skill 包。不要凭空猜测路径 |
Cannot find module './pii-rules.mjs' 或 './skill-spec-rules.mjs' | skill 安装不完整，scripts/ 下缺规则文件 | 重新解压完整 skill 包（含 SKILL.md + VERSION + scripts/ 下三个 .mjs）。三个 .mjs 必须在同一目录 |
| 只想扫 PII 但报"找不到 HarnessToolKit" | 默认模式 Gate 扫描需要 HarnessToolKit | 用 --pii-only 跳过 Gate，PII 扫描本身不需要 HarnessToolKit |
| (exit 11) |
自检说明（扫描 skill 自身目录）
用本 skill 扫描 harness-gate-scan 自身目录时，PII 层会产生一批自匹配误报——pii-rules.mjs 命中的是规则正则字面量（私钥头部标记、连接串模式、客户机构名），SKILL.md 命中的是文档示例文本（138****0000 是工信部规定的测试号段、举例提到的金融机构名）。这些是规则定义性内容和文档示例，并非真实敏感数据泄露，无需处理。scan.mjs 本身在 SKIP_FILES 黑名单里不会被扫到。
输出处理建议
扫描跑完后向用户汇报时分两块：
- Gate Engine（结构化规则）：总量（N 文件 / M 检查 / K 失败）→ 严重度分布（error=X / warning=Y / suggestion=Z，强调 error 必须修）→ Top 5 违规规则
- PII 扫描（
rulesFile 列以 pii- 开头）：按分类计数（[PII 分类] 行直接给出 cloud=X / token=Y / pii=Z 等）→ error 级（C3，API Key/私钥/连接串）X 处必须清除、warning 级（C2，手机号/身份证/银行卡）Y 处需脱敏 → 每类给 1-2 条样例标明文件:行号
不要把整个 TSV 全量输出贴给用户——动辄几百行。给汇总 + error/C3 清单 + 各类 Top 样例即可。
