shmindmaster/crewscore

``` pip install crewscore crewscore scan . # Gate 那个最重要的 control： crewscore scan . --require human_gate.approval_required ``` 对 prompt 文本**以及** `.py` / `.ts` / `.js` 源码中的 `SYSTEM_PROMPT` / `system_prompt` 字符串字面量进行确定性正则表达式匹配。**完全离线，无需 API key，不依赖 LLM。** ## 请先阅读此部分 **CrewScore 是一份清单，而不是基准测试。** 这个数字代表你的 prompt 包含了**23 项已发布控制**的比例 — 与它们是否被充分说明、是否相互一致或在运行时是否被遵守无关。 | Prompt 的操作 | 得分 | | --- | --- | | 没有写下任何内容 | **0** | | 8 个维度各有一项控制 | **36** | | 全部 23 项控制 | **100** | | 一项控制以五种不同方式重述 | 与只表述一次相同 | 因此，**低分意味着你可以采取行动** — 你可能还没有写下注入防御策略、人工审批环节或安全停止规则，而这些都非常值得 写下来。**高分仅意味着文本存在**，并不代表 agent 会遵守 它。不要用这个数字来对 prompt、团队或供应商进行排名，也不要把某个 阈值当作安全标准。请关注具体的检查结果，而不是总分。 其中三个维度 — **Cost**、**Compliance**、**Audit** — 在构建有效性上存在已知的局限性，并在结果中进行了说明。规则集 `0.6.0` 针对测量出的语料库假阳性收紧了它们的模式；Compliance 依然不代表合法合规处理。 📄 **[验证研究 →](docs/validation.md)** — 包括展示我们自己的评分标准在 `0.1.0` 版本前存在缺陷的算术推导，我们在修复之前就发布了这些内容。 📊 **[基于 356 个真实 prompt 的测量 →](docs/validation-corpus.md)** — Cliff's δ = 0.614，通过专门的生成工具而非人工输入，成功将生产环境 agent prompt 与通用 prompt 区分开来。 ## 使用方法 ``` crewscore scan . # prompts + AGENTS.md + inline SYSTEM_PROMPT=... crewscore scan . --no-inline # file discovery only crewscore init . # prompt-free regression baseline + PR workflow crewscore scan . --fail-on-regression --baseline .crewscore-baseline.json crewscore scan . --require human_gate.approval_required # one-control CI habit crewscore test --prompt-file ./prompt.md # coverage N/23 + first gap to review crewscore fix --prompt-file ./prompt.md --plan # what's missing, no writes crewscore rules --concepts # the 23 controls, and the rules behind them ``` **[完整 CLI 参考 →](docs/cli.md)** · **[评分机制 →](docs/scoring-and-controls.md)** ## CI ``` - uses: shmindmaster/crewscore@v2 with: scan-path: "." # Report-only by default. Protect controls explicitly instead of treating # the coverage average as a safety bar: required-controls: "human_gate.approval_required,safe_stop.stop_condition" sarif: "crewscore.sarif" ``` 发布一条带有公开规则检查结果的固定 PR 评论。请根据 `scored` 输出来判断后续步骤， 而不是根据 `score` — 空分数会被转换为 `0`。 **[Action 输入、输出及 CLI 变体 →](docs/github-action.md)** ## 两种产物，两种规则集 CrewScore 判定两类文件，并会告诉你它判定的是哪一类。检测基于文件名和路径 — 绝不通过嗅探内容来判断。 | 产物 | 示例 | 判定依据 | |----------|----------|-----------| | **Coding-agent config** | `AGENTS.md`, `CLAUDE.md`, `.cursorrules` | 配置坏味道 | | **Agent system prompt** | `system-prompt.md`, `任何位于 `prompts/` 或 `agents/` 下的文件` | 8 个治理维度 | 一个写着“*始终使用 pnpm*”的文件是在告诉 coding agent 如何在你的 repo 中工作。它没有理由包含 HIPAA 相关术语，用这种标准来对它评分 属于范畴错误。 我们之所以了解这个错误的大小，是因为我们进行了测量：在拥有 `AGENTS.md` 且最多 star 的前 100 个 repo 中 （[arXiv:2606.15828](https://arxiv.org/abs/2606.15828)），治理规则集将 **所有 100 个 repo 都列入了最差等级**。一个让整个群体都无法通过的标准不携带任何信息。因此，配置文件会得到一个坏味道判定 — 并且在 `--json` 中， 根本不会给出治理评分。 ``` crewscore test --prompt-file AGENTS.md # -> CONFIG: NO SMELLS DETECTED （不是 "0/100 CRITICAL GAPS"） ``` ## 配置坏味道 指指令文件在*结构*上而非内容上的问题，源自一份已发布的目录 — [*Configuration Smells in AGENTS.md Files*](https://arxiv.org/abs/2606.15828) (dos Santos et al., 2026)，该研究发现 **100** 个热门项目中有 **91** 个至少存在一个坏味道。 | 坏味道 | 启发式方法 | 发现于 | |-------|-----------|----------| | **Context Bloat** | ≥ 200 行 | 42% 的研究项目 | | **Lint Leakage** | 已配置的 linter 已经强制执行的样式规则 | 62% | | **Init Fossilization** | 被 git 追踪且仅包含一次 commit | 24% | 论文中的其他三个坏味道需要 LLM 才能检测。我们宁愿发布 三个准确的检测器，也不愿发布六个近似的检测器。Lint Leakage 是对 论文检测器的近似，并在其输出中进行了说明；Init Fossilization 无法区分“从不需要修改”和“从未被修改过”。 **坏味道永远不会改变分数。** 将它们纳入评分会默默改变现有 每个 `--threshold` 的含义。 ## 开发 ``` git clone https://github.com/shmindmaster/crewscore.git cd crewscore pip install -e ".[dev]" pytest ``` **[开发指南 →](docs/development.md)** · [AGENTS.md](AGENTS.md) · [CONTRIBUTING.md](CONTRIBUTING.md) ## 文档 | | | |---|---| | [验证](docs/validation.md) | 该数字能测量和不能测量的内容 | | [语料库验证](docs/validation-corpus.md) | 在 356 个真实 prompt 上的生成结果 | | [评分与控制](docs/scoring-and-controls.md) | 公式、23 项控制、章程、治理 | | [CLI](docs/cli.md) | 每个命令和标志 | | [GitHub Action](docs/github-action.md) | Action 输入/输出和 CI 中的 CLI | | [策略与 SARIF](docs/policies.md) | 回归测试和必需控制 CI（无分数门槛限制） | | [架构](docs/architecture.md) | 模块、数据流、精简目标 | | [开发](docs/development.md) | 本地设置、规则、打包、媒体 | | [实时评估交接](docs/next-steps-eval.md) | 结构化检查后的 Promptfoo / garak 测试 | | [路线图](docs/roadmap.md) | 可用的工作和刻意推迟的功能 | | [安全](SECURITY.md) | 私密漏洞报告 | | [社区讨论](https://github.com/shmindmaster/crewscore/discussions) | 问题、采用反馈和开放性想法 | | [对比](docs/comparison.md) | 其他工具，以及在此工具之后该用什么 | | [CHANGELOG](CHANGELOG.md) | 包括每一次评分变更及其测量到的差值 | | [清理清单](docs/cleanup-and-completion.md) | 本次精简产品过程保留、完成和推迟的内容 | ## 本项目不包含的内容 实时的对抗性红队测试 · 运行时工具网关执行 · 安全或 合规认证 · 模型会遵守文本的证明。 **路线图：** 从 LangGraph / CrewAI / AutoGen 图中提取 prompt 的框架适配器；可选的实时对抗性测试（在获得关注后实现，不是 默认路径）。 MIT 许可证。

标签：AI代理, GitHub Action, LNA, 云安全监控, 代码质量审查, 文档结构分析, 逆向工具, 静态分析