Holley-Studio/thesmos-governance
GitHub: Holley-Studio/thesmos-governance
Thesmos Governance 是一个面向 AI 辅助工程时代的代码治理工具包，通过 CLI、GitHub Action、VS Code 扩展和 MCP server 在代码进入生产前检测 AI 生成代码中的安全漏洞与架构问题。
Stars: 1 | Forks: 0
# Thesmos Governance
[](https://github.com/Holley-Studio/thesmos-governance/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/thesmos-governance)
[](https://www.npmjs.com/package/thesmos-governance)
[](https://marketplace.visualstudio.com/items?itemName=holleystudio.thesmos-governance-vscode)
[](LICENSE)
[](https://nodejs.org)
**1,137 条规则。零配置。为 AI 辅助工程时代而生。**
Thesmos 是一个源码可见的代码治理工具包，专门监控 AI 生成的代码是否存在安全漏洞、破坏性模式以及架构错误——所有这一切都在代码进入生产环境之前完成。
由 [Holley Studio](https://holley.studio) 构建——Thesmos 治理着它自己的代码仓库；此处合并的每一个 PR 都通过了其自身的拦截门禁。查看 [Actions 选项卡](https://github.com/Holley-Studio/thesmos-governance/actions) 以获取证明。
## 为什么选择 Thesmos
AI 工具编写代码的速度远超人类审查的速度。Copilot、Cursor 和 Claude 可以在几分钟内交付可用的功能——但它们也会凭空“幻觉”出模块作用域之外的 Prisma 客户端，将用户输入直接拼接到 LLM prompt 中，并毫无顾忌地制造 N+1 查询瀑布流。
Thesmos 弥补了这一差距。1,137 条涵盖 AI 安全、安全性、性能和正确性的治理规则——安装即刻生效。
## 四种使用方式
### 1. CLI
扫描整个代码库并获取健康度评分：
```
npm install thesmos-governance
npx thesmos scan
```
在提交前仅审查已暂存的更改：
```
npx thesmos review
```
运行 `thesmos audit` 获取详细的 JSON + HTML 报告，或运行 `thesmos init` 以交互方式进行配置。
### 2. GitHub Action
为每个 pull request 添加治理审查。BLOCKER 级别的发现会阻止合并。行内注释会精确出现在对应的代码行上。
将以下内容复制到 `.github/workflows/thesmos-pr.yml`：
```
name: Thesmos Governance
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
pull-requests: write
contents: read
jobs:
governance:
name: Governance Review
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Thesmos PR Review
uses: Holley-Studio/thesmos-governance/actions/pr-review@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
fail-on-severity: BLOCKER
post-inline-comments: 'true'
update-summary: 'true'
```
无需配置任何密钥。没有构建步骤。该 action 完全独立运行。
### 3. VS Code Extension
从 `extensions/vscode/` 目录安装，即可获得：
- 编写代码时的实时发现
- 状态栏中的健康度评分
- AI 适配器面板——让 Claude、Cursor、Copilot 和 Gemini 随时了解你的治理规则，从而使它们从第一行代码起就生成受治理的代码
### 4. Claude Code Plugin
直接在 Claude Code 中安装——无需单独执行 `npm install` 步骤：
```
/plugin marketplace add Holley-Studio/thesmos-governance
/plugin install thesmos-governance
```
内置 MCP server、`scan` / `review` / `advise` 技能，以及 CLI 的 `claude:govern install` 所写入的相同 PreToolUse/PostToolUse/Stop 治理钩子——按项目启用，默认关闭。
## 超越扫描器的功能
规则引擎只是前门——在它背后内置了一个完整的治理平台：
| 界面 | 功能描述 |
|---|---|
| **Diff 感知 PR 门禁** | GitHub Action 仅针对你的 PR 变更行所产生的发现进行拦截——既有的技术债务仅作报告，绝不拦截。基线、行内抑制和置信度分级在所有门禁中的执行方式完全一致（[门禁契约](docs/gating.md)） |
| **Pantheon** | 由 Zeus 编排的 67 个专家级 AI 代理——`thesmos pantheon:*` |
| **Autopilot** | 在隔离分支上由计划文件驱动的自主执行，带有日志记录和一键回滚功能——`thesmos autopilot:*` |
| **Brain** | 能够观察发现结果、学习模式并提出新规则供人工审批的机构记忆——`thesmos brain:*` |
| **MCP server** | 在 AI 代理编写代码*之前*对其进行治理——`thesmos mcp:serve` |
| **Builder 向导** | 搭建受治理的代理、技能、RAG pipeline 和 MCP 工具——`thesmos build:*` |
| **执行顾问** | 为计划推荐合适的模型+代理，生成可直接粘贴的启动方案——`thesmos advise ` |
| **合规包** | 包含 GDPR、欧盟 AI 法案、HIPAA、DORA 规则集及审计跟踪工具——`thesmos compliance:report`、`agent:audit:*` |
| **成本与范围守卫** | 带有硬性停止的 token 预算、代理范围边界、1M 上下文防护——`thesmos tokens:*`、`scope:*` |
## 检测工作原理
我们直言不讳，因为这关系到你应该对发现结果给予多大的信任：Thesmos 的 1,137 条规则**主要基于代码行和模式**——即应用于文件内容和 diff 的正则表达式和轻量级结构启发式方法。这并不是完整的 AST 解析或跨文件数据流分析，我们也没有将其宣传成那样。基于模式的检测速度快，零运行时依赖，且可在任何地方运行——但它可能会被别名、间接引用或与预期模式形状不同的代码所迷惑，这也是同类扫描器共同面临的权衡。
正是基于这种坦白，没有任何发现会被盲目拦截：
- **置信度分级**——每条规则都被标记为 `high`（近乎确定的证据，例如已提交的密钥或被禁用的 TLS 检查）、`medium`（可能误报的形状启发式，例如带有模板字面量且其插值可能是常量的 `exec()`），或 `low`（暗示而非证明的关键字/存在信号）。默认情况下，只有 `medium` 及以上置信度的发现会导致构建失败；`low` 置信度的发现会带有可见标签进行报告，但绝不会改变退出代码。
- **Diff 感知门禁**——只有位于你的 PR 实际更改的行上（或其添加的文件中）的发现才会阻止合并。被修改文件中的其他所有发现仅作报告，绝不拦截。
- **抑制系统**——单个行内注释（`// thesmos-disable-next-line -- reason: -- owner: @who`）可永久移除特定的误报。抑制操作需要提供理由和负责人，并且 `thesmos suppressions:audit` 会报告未使用、已过期或一刀切的抑制记录。
- **基线**——`.thesmos/baseline.json` 是一个已接受债务的账本，因此门禁只会在*新*问题上触发，绝不会对你继承而来的既有问题触发。
完整的策略——包括确切说明哪些发现可以阻止合并、哪些不能——已记录在 [docs/gating.md](docs/gating.md) 中，这是每个门禁（`thesmos validate`、`thesmos ci` 和 GitHub Action）完全遵循的唯一事实来源。
### 谁来审查审查者
合并到*本*仓库的每个 pull request 都必须通过客户 PR 将面临的相同 `thesmos validate` 门禁——包括这一次。这不是一句承诺，而是一份公开记录：[github.com/Holley-Studio/thesmos-governance/actions](https://github.com/Holley-Studio/thesmos-governance/actions)。
本代码库同样也是 AI 加速、人类主导的开发产物——Holley Studio 全程使用 Claude Code 和其他 AI 助手构建 Thesmos。我们认为这是一种优势，而不是需要隐瞒的披露：这里落地的每一项 AI 辅助更改，都会经过我们向你提供的完全相同的门禁。
## 1,137 条规则
规则被划分为 17 个类别：
| 类别 | 规则数 | 示例 |
|----------|-------|---------|
| AI / LLM | 27 | Prompt 注入、token 滥用、系统 prompt 泄露 |
| Security | 22 | CORS 通配符、原型污染、eval 使用 |
| Prisma | 30 | 缺失的外键索引、连接池耗尽、N+1 查询 |
| Zod | 30 | 被绕过的 schema、`.any()` 使用、缺失的 API 校验 |
| tRPC | 25 | 缺失的 auth 中间件、未受保护的 mutation |
| React | 30 | 缺失的错误边界、prop 透传、过期的闭包 |
| Next.js | 22 | 泄露密钥的 Client component、缺失的 Suspense 边界 |
| Performance | 23 | 瀑布式 fetch、庞大的 bundle 引入、未节流的 effect |
| TypeScript | 18 | `any` 逃逸出口、缺失的返回类型 |
| Node.js | 30 | 未处理的 Promise 拒绝、主线程上的同步 I/O |
| Error Handling | 25 | 静默的 catch 块、被吞掉的错误 |
| State | 20 | 派生状态存储在 useState 中、被修改的 ref |
| Forms | 20 | 缺失校验、不受控的输入 |
| Logging | 20 | 日志中的密钥、缺失的请求 ID |
| CSS | 20 | 魔法数字、特异性冲突 |
| Imports | 20 | Barrel 文件循环引用、深度的内部引入 |
| Database | 23 | 缺失事务、未建立索引的外键 |
每条规则都配备了一对回归测试——一个必须**不**触发的误报 fixture，以及一个必须触发的真阳性 fixture（策略详见 [CONTRIBUTING.md](CONTRIBUTING.md)）。截至撰写本文时，这相当于跨越 79 个测试文件的 **2,827 个通过测试**，并在每个 PR 上进行验证。
## 严重性级别
| 级别 | 含义 |
|-------|---------|
| `BLOCKER` | 合并前必须修复。阻止 CI。 |
| `HIGH` | 安全性或正确性风险。尽快修复。 |
| `MEDIUM` | 质量问题。在本迭代内修复。 |
| `LOW` | 最佳实践缺失。在处理附近代码时修复。 |
| `TECH_DEBT` | 仅作记录，不阻止合并。 |
## 配置
无需配置文件。如需自定义，请创建 `.thesmos/config.json`：
```
{
"exclude": ["**/*.test.ts", "scripts/"],
"rules": {
"AI_013": "off",
"PERF_018": "MEDIUM"
},
"failOn": "BLOCKER"
}
```
## 社区规则包
将任何 `.json` 规则包放入 `.thesmos/packs/` 目录——它们会在运行时加载，无需重新构建。schema 请参阅 `CONTRIBUTING.md`。
## 仓库结构
```
thesmos-governance/
├── website/ Marketing site (deployed to Vercel)
│ └── index.html
├── thesmos/ npm package — CLI + core engine
│ ├── bin/ CLI entry points (scan, review, audit, init, watch)
│ ├── catalog/ 1,137 rules organized by category
│ ├── index.ts Public API
│ ├── metrics.ts Health grade calculation
│ └── report.ts Report generation
├── actions/
│ └── pr-review/ GitHub Action (self-contained, no install step)
├── extensions/
│ └── vscode/ VS Code extension
├── .claude-plugin/ Claude Code plugin manifest + marketplace listing
├── skills/ Plugin skills (scan, review, advise)
├── hooks/ Plugin governance hooks (mirrors claude:govern install)
└── .github/workflows/ CI + release pipeline
```
## 许可证
[Functional Source License 1.1, MIT Future License](LICENSE) (FSL-1.1-MIT)——今日源码可见；在每个版本发布四年后转换为 MIT 许可证。可免费使用（包括商业用途），但竞争性用途（将 Thesmos 本身或实质上相似的产品作为托管或本地部署服务提供给第三方）除外。完整条款请参阅 [LICENSE](LICENSE)。
*由 [Holley Studio](https://github.com/Holley-Studio) 构建*
标签：AI治理, MITM代理, SOC Prime, 云安全监控, 开发工具, 暗色界面, 自动化攻击, 静态分析