harness-gate-scan

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 的绝对路径，按以下顺序尝试：

1. 检查环境变量：echo "$HARNESS_GATE_SKILL_DIR"，若已设值且该路径下同时存在 scripts/scan.mjs、scripts/pii-rules.mjs、scripts/skill-spec-rules.mjs，直接用
2. 搜索本机常见 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
3. 询问用户：若前两步都无结果，不要凭空猜测路径，直接问用户要绝对路径。若用户也确认本机文件不全，让用户重新从 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       # 产出 dist/cli.cjs
node dist/cli.cjs version    # 验证：输出 harness-toolkit v0.1.0

若未设 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    # 拿到新 commit
# 然后更新 skill 的 VERSION 文件：把「适配 HarnessToolKit: <旧 commit>」改为新 commit，加变更记录

对齐方式 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：查看用法

示例：

# 默认：Gate + PII + Skill-spec 都扫
node $SKILL_DIR/scripts/scan.mjs /path/to/any-project \
  --toolkit ~/code/HarnessToolKit --report /tmp/scan.tsv

# 仅扫 Gate（跳过 PII）
node $SKILL_DIR/scripts/scan.mjs /path/to/any-project \
  --toolkit ~/code/HarnessToolKit --gate-only --report /tmp/gate.tsv

# 仅扫 PII（无需 HarnessToolKit，最轻量）
node $SKILL_DIR/scripts/scan.mjs /path/to/any-project --pii-only --report /tmp/pii.tsv

v1.7.0 新增 flag 用例

# 自动修复可机械修复的违规（var/console.debug/tabs）
node $SKILL_DIR/scripts/scan.mjs /path/to/project --toolkit ~/code/HarnessToolKit \
  --gate-only --fix --report /tmp/scan.tsv

# HTML 报告（所有模式都可用）
node $SKILL_DIR/scripts/scan.mjs /path/to/project --toolkit ~/code/HarnessToolKit \
  --report /tmp/scan.tsv --html /tmp/report.html

# 增量模式：编辑器 hook 实时检查未保存 buffer
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
# Trae/Cursor AI agent 直调（无 stdin 管道时自动从磁盘读 <file>，仍走增量模式）

# CI 改动文件模式：只扫相对 base 分支改动的文件
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

# 只看 error 级（必须修复的）
awk -F'\t' 'NR>1 && $3=="error"' "$REPORT"

# 按规则ID聚合命中数
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。

脱敏处理原则

1. 保留文件结构与跨文件引用，只替换值——不要因脱敏破坏 JSON/YAML 结构或配置项的键名
2. 分级脱敏：C1 可保留或轻度掩码，C2 掩码（保留可识别前缀+后缀），C3 完全清除
3. 配置文件：真实 URL/Key 替换为模板占位（https://<your-host>/v1/<app_id>/...、{{ASSISTANT_API_KEY}}），运行时从环境变量注入
4. 测试数据：占位号（如 138****0000、110000000000000000）可保留；真实数据必须替换
5. 业务标识符（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 样例即可。