lakeday-org/perch

perch – 基于 AI 的语义代码 lint

是什么 – perch 是一个命令行工具，扫描源代码并报告 语义 缺陷（例如：调用顺序错误、偏移 1 错误、环境变量误用）。分析由 TypeSafe 的大语言模型服务（通过 API 密钥访问）驱动。它超越了语法检查器，让模型推理每个方法的意图，并根据置信度对发现结果进行排序。

如何工作

• perch scan 遍历项目，构建函数/方法的图结构，并向 LLM 发送简洁的“问题”。模型返回某个模式是缺陷的概率；perch 将其转换为严重性分数（P1、P2、…），并打印出表格。
• 结果缓存在隐藏的 .perch/ 文件夹中，因此重复运行速度很快。
• 你可以查询列表（perch issues），深入查看单个发现（perch issues <id>），并在修复后重新检查（perch check <id>）。

扩展方式 – 自定义规则使用简单的 YAML 格式编写（perch.yaml 或 .perch/rules/ 下的文件）。规则指定：

• where – 文件通配符模式
• each – 粒度（method、function 等）
• min – 显示问题所需的最低置信度
• ensure – 所需行为的自然语言描述

助手集成 – perch 可以为各种 LLM 助手（Claude、Codex、Pi、Cursor）安装“技能”。perch setup <assistant> 命令会生成一个 Markdown 文件，其中包含助手可用于建议修复的提示。

快速上手

npm install -g @lakeday/perch
export PERCH_API_KEY=$(cat ~/.perch_key)   # 从 console.typesafe.ai 获取
perch scan

CLI 会打印出问题列表、置信度以及发现位置的方法名。

典型工作流

1. 在本地或 CI 中运行 perch scan。
2. 使用 perch issues 审查严重性最高的项目。
3. 修复代码后，运行 perch check <id> 验证问题是否已解决。
4. 通过向 .perch/closed.jsonl 添加条目来忽略误报。

文档与生态 – 完整文档托管在 https://docs.perchscan.com，涵盖安装、规则语言、CI 集成和内部“图遍历”。项目发布在 npm（@lakeday/perch），包含 CI 标记、类型检查和单元测试。

成熟度 – 仓库提供稳定 CLI、自动化测试和 CI。它需要外部 API 密钥，因此核心分析依赖 TypeSafe 服务，但周边工具（规则引擎、缓存、CI 集成）是开源的。

许可证 – MIT（参见 LICENSE）。

---

Perch 是一个真正的 AI 增强型 lint 平台，旨在为希望获得更高层次、模型驱动的代码质量检查，而无需编写自定义提示的开发者服务。