marketplace-health-check

市场健康检查

使用并行扇出动态工作流，对此 Claude Code 技能市场仓库进行全面、基于证据的健康检查。让独立检查人员并行覆盖以下维度：

1. 代码与脚本安全 — 危险删除、NO-FALLBACK 机密泄漏、硬编码真实路径、裸露的 except、注入、缺少 shebang
2. 文档 / SSOT 一致性 — 权威文档检查、发布策略一致性、失效引用、派生值偏差
3. 安全 / PII — gitleaks 无法发现的无关键词泄漏（真实姓名、私人域名）、通用机密扫描、案例文件审计
4. 未关闭 PR 分类 — 对每个 PR 进行分类（值得合并 / 需要修改 / 作为推广内容拒绝）
5. 未关闭 issue 分类 — 真实 Bug 与技能请求及推广内容的区分，以及错误安装命令这一类 Bug
6. 市场清单完整性 — check_marketplace.sh + check_doc_skill_lists.py、孤立项、套件注册

然后由你核实重要发现，并按优先级报告。使用捆绑脚本（scripts/repo-health-check.workflow.js）进行编排；该文件说明了运行和解读方式。

为什么使用工作流——以及为什么必须在行内运行

各个维度彼此独立，因此将任务扇出给并行 Agent，比单个 Agent 按顺序逐项检查快得多；每位检查人员只需专注于一个关注点，并按结构化格式输出结果。

扇出前，请使用脚本明确指定的最大任务预算及其运行时拒绝机制。添加检查人员或更改预算前，先审查使用成本；不要根据当前维度列表推导限制。

此技能必须在行内运行（不能使用 context: fork）。 它通过 Workflow 工具编排并行 Agent，而分叉出的子 Agent 无法再启动子 Agent 或启动工作流——若以分叉方式运行，扇出将会无声失效。Workflow 工具还要求用户明确选择启用；用户要求“运行健康检查”即表示已选择启用，因此请继续。

如何运行

第 1 步 — 探查当前规模，并将结果分享给所有检查人员

工作流脚本接收一个 args 对象，以便所有 Agent 共享同一份准确快照，而非各自重新探查。请收集以下信息：

将此 Skill 的安装目录 / 源目录解析为 <health-skill-dir>，确认所选仓库根目录，并运行：

python3 "<health-skill-dir>/scripts/scout_repository.py" --repo "<owner/name>" --root "<repo-root>"

读取辅助工具的 JSON 和退出状态；其 --help 说明了输出 / 退出约定。它会将清单元数据解析为 JSON，并遵循 github-ops GraphQL 分页方案 获取 PR 和 issue，同时根据服务器总数核对去重后的条目。将完整输出保存在源代码树之外，以便检查人员读取；在 scale 中包含其准确路径和简要范围摘要。如果检查人员无法解析已安装的套件，也要在其中传入辅助工具的绝对路径。若清点失败，请将部分条目标记为 not_checked；绝不可将其报告为 ALL，也不可将请求失败报告为零。后续检查人员可以使用同一辅助工具补全这份确切的缺失清单，并使用新验证的结果。

在进行公开发布 PII 判断前，请确认 identity.isPrivate: false。如果无法获取可见性信息，则将该判断保持为未知；如果目标仓库为私有，则按照其实际隐私边界判断。不要更改账户、权限或全局设置来让探查看起来已准备就绪。

步骤 2 — 启动工作流

读取捆绑脚本，并通过 script 参数以内联方式启动它（传入脚本内容，这样就不依赖 Skill 的安装位置）：

Workflow({
  script: <full contents of scripts/repo-health-check.workflow.js>,
  args: { repo: "<owner/name>", scale: "<one-line summary from Step 1>" }
})

告诉用户，这会启动并行模型工作，并消耗当前计划的用量；不要把固定的时间或令牌估算说成保证。保留宿主实际的权限门控。编辑已保存的脚本前，如果 Claude Code 的 /workflow-authoring 捆绑 Skill 可用，请先加载它；关于宿主前提条件和脚本限制，请查阅官方 Workflow 合约。

区分启动与完成：初始 error 表示本次运行未生成审计结果；async_launched 仅确认已启动。等待该次运行的最终完成事件，并检查其返回的报告。若失败、取消或 Workflow 工具不可用，请将审计报告为尚未完成，并指出缺少的前提条件；不要把启动回执或侦察结果当作已完成的审计。

最终载荷为 { complete, checks: [...] }。每个预期维度保留一行，包含 dimension、status（checked / not_checked）、现有的 health、summary、findings[] 和 stats 字段。complete 表示所有维度报告均已完成，包括报告关键缺陷的情况；它不表示代码库健康。检查器缺失、失败或无效时，将其替换为空的 not_checked 占位项，并设 health: needs-attention。对于符合架构但不完整的报告，保留其发现和统计数据，并采用相同的保守健康状态；说明代码库整体健康状况仍未确定。覆盖不完整不会撤销已观察到的发现：仍须按常规严重程度进行反审查并报告。

运行期间，你可以做其他有用的准备工作，但不要开始编辑检查器正在读取的文件。

步骤 3 — 报告前反审查严重发现

Agent 的发现只是假设，不是结论。绝不要原样转述。 对每一项 high / critical 发现，都要用一条快速命令自行核实——用 grep 搜索泄露值、用 sed -n 查看有问题的行、用 gh repo view 检查所述状态——确认它 (a) 确实存在，(b) 位于 Agent 所说的位置，且 (c) 没有夸大其影响。这能揪出误报，也同样重要的是，能发现 Agent 提出的实际有害建议。（在提炼出此 Skill 的那次会话中，安全检查器建议把真实的私人域名加入公开的 .gitleaks.toml——这会适得其反，必须拒绝；请参阅方法论参考。）

用以下问题筛选每一项发现：可能性（它真的会发生吗？）、成本（修复还是忽略？）、真实场景（实际中会造成影响吗？）、可验证性（能否用一条命令确认或反驳？）。

报告格式

先给出表格，再按优先级分层。进行分类，不要一股脑罗列：

• 一句话结论 + 维度表，列出状态、健康状况和范围；保留所有预期行。对于 not_checked，以“未检查”开头，指出缺失的证据和恢复操作，并避免给出整体健康的结论
• 🔴 必须修复 — 列出每项已核实的高危 / 严重问题，注明准确位置和具体修复方法
• 🟠 待处理 — PR / issue 分类结果和未完成的检查（决策通常会影响外部；请指出这些问题会影响外部贡献者）
• 🟢 可选 — 低危 / 信息类小问题，每项用一行说明
• 💡 关键洞察 — 值得指出的深层发现（工具中的结构性盲点、反复出现的 Bug 类型）

对每项报告内容标注 ✅ 确实存在 / ⚠️ 部分属实 / ❌ 误报。原始 Agent 输出大多是噪声；你的职责是揭示所有者尚未知晓的真实风险，而不是把原始发现转交给他们自行筛选。

判断原则

解读发现并提出修复方案时，请遵循以下原则。完整的推理过程以及每项原则背后的实际故障案例，见 references/health-check-methodology.md——处理 PII 或 PR/issue 相关发现前请先阅读。

• 反面示例：绝不要通过将真实值列入公开白名单（例如仓库自身的 .gitleaks.toml）来“修复” PII 泄露——列举真实资产的公开列表本身就是一种泄露。应就地清理该值；针对真实私密值的检测规则应放在所有者的私有全局防护机制中，而非这个公开仓库中。
• 历史说明：清理工作副本能修复当前版本，但先前的泄露仍存在于 git 历史中。应如实指出历史暴露风险；重写历史（force-push）是另一项高风险决策，会影响每个 fork——绝不要擅自执行。
• 公开扫描证据：按照方法论参考文档解读标记并执行隔离扫描。运行通用检查并进行语义样本读取；缺少本地凭据或可选的私有资产规则，并不能证明公开软件包未经扫描或不安全。
• 发布与贡献决策：阅读当前的发布负责人和 CONTRIBUTING.md。采用其中的变更分类、已注册的插件身份和维护者后续处理规则；不要自行编造成员版本号，也不要要求每位贡献者履行维护者的记录工作。合并外部 PR 需要由人类所有者决定。
• 默认不接受推广：第三方目录／工具／市场的推广 PR 和 issue 一律拒绝——该仓库是个人精选市场，而非生态目录。拒绝政策模板是仓库根目录中的参考文档（不属于此技能的资源包）。

随附资源

• scripts/repo-health-check.workflow.js — 并行检查 Dynamic Workflow。通过 Workflow 工具的 script 参数运行（步骤 2）。新增或弃用检查维度时，请编辑此文件。
• scripts/scout_repository.py — 只读 JSON 探查工具；使用其 --help 查看参数和退出语义。
• references/health-check-methodology.md — Counter-Review、隐私、隔离扫描处理以及贡献政策解读。
• tests/test_health_check.py — 用于探查工具和 Workflow 正文契约的确定性测试；使用 python3 -m unittest discover -s "<health-skill-dir>/tests" -v 运行。这些测试不能替代原生 Workflow 执行或模型判断。

下一步

提交只读报告，包括尚未解决的覆盖范围问题。仅在用户现有授权范围内继续修复；对于仓库写入、外部评论、合并第三方变更或重写历史，若缺少授权，请先取得授权。仅提出审计请求并不代表授权执行这些操作。