Poolchaos/Trysquare

# Trysquare 一个本地的代码审查工具，它会像一位细心的资深工程师那样阅读 git 分支，并且拒绝向你提供任何它无法证明的发现。 直角尺是木工用来抵住接头以检查其是否真正方正，而不仅仅是看起来方正的工具。这正是这里的核心理念。AI 可能会生成一份读起来很好但实际上却悄悄出错的审查报告：可能是偏差的行号、上游防护子句已经处理的 bug，或者是它从未打开过的文件。Trysquare 的构建初衷就是让这些失败被程序捕获，而不是被盲目信任。 ## 状态 处于早期开发阶段，诚实的总结很短：**审查流水线尚未构建完成。** 目前存在的只是基础部分。项目脚手架已经可以运行，质量门禁（`./verify.sh`）已经就位，并且其失败模式是经过验证的而非假设的，设计详情见 [docs/](docs/)。十二个工作包中已完成一个。 目前还没有可用的审查功能。如果你是来寻找一个今天就能运行的工具，那它还没准备好。如果你是来阅读设计或做出贡献的，你需要的一切都在 [docs/](docs/) 和 [docs/plans/BUILD-PLAN.md](docs/plans/BUILD-PLAN.md) 中。 ## 理念 大多数 AI 审查工具要求模型查看 diff 并报告其发现。这会产生两种难以察觉的失败模式：模型在未告知你的情况下跳过了一些内容，以及它报告了不真实的内容。 Trysquare 的设计基于这两种情况都会发生的假设。 **记录工作是代码，而非判断。** 构建已更改文件和代码块的列表、运行机械化的模式扫描、跟踪哪些代码块已被处理，以及检查引用的行号，所有这些都由程序完成。只要求模型提供判断，且仅仅是判断。 **不允许静默跳过任何内容。** 每一个代码块、每一次扫描命中，以及每一次删除，在审查结束时都必须要么附带一个发现，要么附有理由明确清除。只要有任何内容未被处理，审查就无法进入报告阶段。这是通过数据库中的覆盖账本来执行的，而不是通过对模型的温和请求。 **每一个发现都由未编写它的人进行验证。** 候选发现会在一个全新的会话中进行第二轮处理，且无法访问生成它们的推理过程。它的工作是打开文件，引用实际的代码行，并试图扼杀这个发现：代码真的在那里吗，机制真的成立吗，上游是否有已经处理了它的防护。然后，程序会检查验证者自己的工作，将引用的代码与所引用行处的文件进行字节比较。一个行号不匹配的发现无论如何确信都会被抹杀。 **由人类决定什么才算数。** 幸存下来的发现会呈现给你，让你确认或附上理由驳回。只有你确认的内容才会进入报告。 **被审查的代码绝不会被修改。** 项目以裸库形式克隆，审查在固定到某个 commit 的分离工作树中运行，并且模型获得一个只读的工具白名单。没有任何代码路径可以写入正在审查的仓库。 ## 它将如何工作 你通过 git URL 添加一个项目，它会在本地克隆。你选择要审查的分支、要比较的分支，以及要应用的规则集。规则集分为三个可组合的层级：适用于任何代码的规则、适用于特定技术的规则，以及特定于某一个项目的规则。 然后，审查作为一系列阶段运行，类似于严格的手动审查：构建变更清单、评估风险、理解代码（包括它调用的文件）、根据规则库进行对抗性搜寻、将删除视为头等变更进行审查、验证每一个候选发现，并在生成任何内容之前审计覆盖率。 有两个细节值得了解。审查可以一次跨越两个仓库，这在应用和它所调用的 package 同时更改，而 package 中的类型更改仅在调用方处有危险的情况下很常见。此外，请求之间的工作划分方式会根据你选择的模型进行调整，因为具有大上下文窗口的模型可以一次容纳整个规则集，而较小的模型则不能。永远不变的是覆盖率：较弱的模型会获得更多、更小的请求，但绝不会获得缩减的规则集。 ## 要求 - Node 22 或更新版本 - git - 已安装并登录 [Claude Code](https://claude.com/claude-code) Trysquare 驱动你机器上已有的 `claude` CLI，使用它已经持有的任何凭证。它不自带任何模型，没有账户系统，没有自己的服务器，也没有遥测功能。 需要清楚这意味着什么和不意味着什么。使用模型审查代码意味着将代码发送给该模型：当审查运行时，diff、相关文件的内容以及你的规则集会通过 Claude Code CLI 发送给 Anthropic，受你与他们已有的条款和计划约束。这是工具完成其工作的固有属性，而不是额外附加的。Trysquare 增加的是确保没有任何东西会流向其他地方：没有 Trysquare 服务，没有分析，没有第三方。你的项目、审查历史和发现仅存储在本地 SQLite 数据库和你自己主目录下的文件中。 ## 运行它 ``` npm install npm run dev ``` 这会在 上启动应用。目前它只渲染一个占位页面：请参阅上面的状态。 ## 开发 ``` ./verify.sh # the gate: lint, format, types, house style, tests ./verify.sh --build # adds a production build ./verify.sh --e2e # adds end-to-end tests ``` 在这个项目中，“已验证”只意味着一件事：`./verify.sh` 以零状态退出。 该脚本会将其每个步骤的退出状态与输出分开检查，并扫描该输出中的运行时错误标记，因为一个打印了堆栈跟踪但仍然以零状态退出的步骤也是一种失败。一个挂起的步骤也是失败，而不是需要等待完成的事情。 门禁自身的失败路径已被故意触发并观察到其启动。一个从未失败过的门禁在被证明 otherwise 之前会被假定为已损坏，而它的第一个版本确实漏掉了一个本该捕获的违规。 ## 文档 设计是在构建之前写下的，并且这些文档会保持更新，而不是只写一次。 | 文档 | 涵盖内容 | | --- | --- | | [docs/00-BRIEF.md](docs/00-BRIEF.md) | 应用旨在成为什么 | | [docs/01-ARCHITECTURE.md](docs/01-ARCHITECTURE.md) | 拓扑、分层规则、磁盘布局、引擎适配器 | | [docs/02-DATA-MODEL.md](docs/02-DATA-MODEL.md) | Schema、状态机、覆盖率不变量 | | [docs/03-REVIEW-PIPELINE.md](docs/03-REVIEW-PIPELINE.md) | 审查阶段以及什么是代码与判断 | | [docs/04-UI-DESIGN.md](docs/04-UI-DESIGN.md) | 屏幕、状态、可访问性 | | [docs/05-TESTING.md](docs/05-TESTING.md) | 测试策略和注入 bug 的质量门禁 | | [docs/06-MODELS-AND-PROFILES.md](docs/06-MODELS-AND-PROFILES.md) | 模型发现以及流水线如何适应模型能力 | | [docs/plans/BUILD-PLAN.md](docs/plans/BUILD-PLAN.md) | 工作包、里程碑、当前进度 | | [docs/PROJECT-STATE.md](docs/PROJECT-STATE.md) | 目前实际构建了什么 | ## 许可证 [MIT](LICENSE)。 ## 不隶属于 Anthropic 这是一个独立项目。它不由 Anthropic 制作、认可或附属。它在你自己的机器上根据你已有的计划运行 Claude Code CLI，并且“Claude”和“Anthropic”是 Anthropic PBC 的商标，在此使用仅用于说明该工具与之通信的对象。

标签：AI代码审查, Git, MITM代理, SOC Prime, 云安全监控, 开发工具, 网络安全研究, 自动化攻击, 静态分析