| name | plankton-code-quality |
| description | 使用 Plankton 的写入时代码质量强制执行 —— 通过钩子在每次文件编辑时自动格式化、lint 和 Claude 驱动的修复。 |
| origin | community |
Plankton 代码质量技能
Plankton（致谢：@alxfazio）的集成参考，一个用于 Claude Code 的写入时代码质量强制执行系统。Plankton 通过 PostToolUse 钩子在每次文件编辑时运行格式化器和 linter，然后生成 Claude 子进程来修复智能体未捕获的违规。
何时使用
- 你希望在每次文件编辑时自动格式化和 lint（不仅是在提交时）
- 你需要防御智能体修改 linter 配置以通过检查而非修复代码
- 你想要分层模型路由来修复（Haiku 用于简单样式、Sonnet 用于逻辑、Opus 用于类型）
- 你使用多种语言（Python、TypeScript、Shell、YAML、JSON、TOML、Markdown、Dockerfile）
工作原理
三阶段架构
每次 Claude Code 编辑或写入文件时，Plankton 的 multi_linter.sh PostToolUse 钩子运行：
阶段 1：自动格式化（静默）
├─ 运行格式化器（ruff format、biome、shfmt、taplo、markdownlint）
├─ 静默修复 40-50% 的问题
└─ 不向主智能体输出
阶段 2：收集违规（JSON）
├─ 运行 linter 并收集无法修复的违规
├─ 返回结构化 JSON：{line, column, code, message, linter}
└─ 仍然不向主智能体输出
阶段 3：委派 + 验证
├─ 使用违规 JSON 生成 claude -p 子进程
├─ 根据违规复杂度路由到模型层级：
│ ├─ Haiku：格式化、导入、样式（E/W/F 代码）— 120 秒超时
│ ├─ Sonnet：复杂度、重构（C901、PLR 代码）— 300 秒超时
│ └─ Opus：类型系统、深度推理（unresolved-attribute）— 600 秒超时
├─ 重新运行阶段 1+2 验证修复
└─ 干净时退出码为 0，违规仍存在时退出码为 2（报告给主智能体）
主智能体看到的内容
| 场景 | 智能体看到的内容 | 钩子退出码 |
|---|
| 无违规 | 无 | 0 |
| 子进程修复了所有违规 | 无 | 0 |
| 子进程后仍有违规 | [hook] N violation(s) remain | 2 |
| 建议性（重复、旧工具） | [hook:advisory] ... | 0 |
主智能体只看到子进程无法修复的问题。大多数质量问题被透明地解决。
配置保护（防御规则博弈）
LLM 会修改 .ruff.toml 或 biome.json 来禁用规则，而不是修复代码。Plankton 通过三层保护来阻止这一点：
- PreToolUse 钩子 ——
protect_linter_configs.sh 在编辑发生之前阻止对所有 linter 配置的修改
- Stop 钩子 ——
stop_config_guardian.sh 在会话结束时通过 git diff 检测配置变更
- 受保护文件列表 ——
.ruff.toml、biome.json、.shellcheckrc、.yamllint、.hadolint.yaml 等
包管理器强制执行
Bash 上的 PreToolUse 钩子阻止遗留包管理器：
pip、pip3、poetry、pipenv -> 已阻止（使用 uv）npm、yarn、pnpm -> 已阻止（使用 bun）- 允许的例外：
npm audit、npm view、npm publish
设置
快速开始
注意： Plankton 需要从其仓库手动安装。安装前请先审查代码。
brew install jaq ruff uv
uv sync --all-extras
claude
无需安装命令，无需插件配置。.claude/settings.json 中的钩子在你于 Plankton 目录中运行 Claude Code 时自动生效。
每项目集成
要在你自己的项目中使用 Plankton 钩子：
- 复制
.claude/hooks/ 目录到你的项目
- 复制
.claude/settings.json 钩子配置
- 复制 linter 配置文件（
.ruff.toml、biome.json 等）
- 为你的语言安装 linter
语言特定依赖
| 语言 | 必需 | 可选 |
|---|
| Python | ruff、uv | ty（类型）、vulture（死代码）、bandit（安全） |
| TypeScript/JS | biome | oxlint、semgrep、knip（死导出） |
| Shell | shellcheck、shfmt | — |
| YAML | yamllint | — |
| Markdown | markdownlint-cli2 | — |
| Dockerfile | hadolint（>= 2.12.0） | — |
| TOML | taplo | — |
| JSON | jaq | — |
与 ECC 配合使用
互补而非重叠
| 关注点 | ECC | Plankton |
|---|
| 代码质量强制执行 | PostToolUse 钩子（Prettier、tsc） | PostToolUse 钩子（20+ linter + 子进程修复） |
| 安全扫描 | AgentShield、security-reviewer 智能体 | Bandit（Python）、Semgrep（TypeScript） |
| 配置保护 | — | PreToolUse 阻止 + Stop 钩子检测 |
| 包管理器 | 检测 + 设置 | 强制执行（阻止遗留 PM） |
| CI 集成 | — | git 的预提交钩子 |
| 模型路由 | 手动（/model opus） | 自动（违规复杂度 -> 层级） |
推荐组合
- 安装 ECC 作为你的插件（智能体、技能、命令、规则）
- 添加 Plankton 钩子用于写入时代码质量强制执行
- 使用 AgentShield 进行安全审计
- 使用 ECC 的验证循环作为 PR 前的最终门控
避免钩子冲突
如果同时运行 ECC 和 Plankton 钩子：
- ECC 的 Prettier 钩子和 Plankton 的 biome 格式化器可能在 JS/TS 文件上冲突
- 解决方案：使用 Plankton 时禁用 ECC 的 Prettier PostToolUse 钩子（Plankton 的 biome 更全面）
- 两者可以在不同文件类型上共存（ECC 处理 Plankton 未覆盖的内容）
配置参考
Plankton 的 .claude/hooks/config.json 控制所有行为：
{
"languages": {
"python": true,
"shell": true,
"yaml": true,
"json": true,
"toml": true,
"dockerfile": true,
"markdown": true,
"typescript": {
"enabled": true,
"js_runtime": "auto",
"biome_nursery": "warn",
"semgrep": true
}
}
关键设置：
- 禁用你不使用的语言以加速钩子
volume_threshold —— 违规数超过此计数自动升级到更高的模型层级subprocess_delegation: false —— 完全跳过阶段 3（仅报告违规）
环境覆盖
| 变量 | 用途 |
|---|
HOOK_SKIP_SUBPROCESS=1 | 跳过阶段 3，直接报告违规 |
HOOK_SUBPROCESS_TIMEOUT=N | 覆盖层级超时 |
HOOK_DEBUG_MODEL=1 | 记录模型选择决策 |
HOOK_SKIP_PM=1 | 绕过包管理器强制执行 |
参考
- Plankton（致谢：@alxfazio）
- Plankton REFERENCE.md —— 完整架构文档（致谢：@alxfazio）
- Plankton SETUP.md —— 详细安装指南（致谢：@alxfazio）
ECC v1.8 新增内容
可复制的钩子配置
设置严格的质量行为：
export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true
语言门控表
- TypeScript/JavaScript：首选 Biome，Prettier 回退
- Python：Ruff format/check
- Go：gofmt
配置篡改守护
在质量强制执行期间，标记同一迭代中对配置文件的更改：
biome.json、.eslintrc*、prettier.config*、tsconfig.json、pyproject.toml
如果配置被更改以抑制违规，则要求合并前进行显式审查。
CI 集成模式
在 CI 中使用与本地钩子相同的命令：
- 运行格式化器检查
- 运行 lint/类型检查
- 严格模式下快速失败
- 发布修复摘要
健康指标
跟踪：
- 被门控标记的编辑数
- 平均修复时间
- 按类别重复违规数
- 因门控失败导致的合并阻塞数
