Hapsland：为编码智能体提供编码规范的实时语义建议

在你的编码代理仍在工作时，捕捉可疑的数据和代码决策。

Hapsland 让你对编码代理的更改应用自动审查，并立即给出反馈。

它以智能的方式做到这一点，从代理的 diff 中收集语义上下文。

它兼顾你的隐私：不会将提示词或无关更改发送给分类器，审查请求会根据你的访问设置来构建。

它会实时将发现的问题发送回代理，使其能在围绕错误构建更多代码之前加以修正。

它关注你的代理的上下文和注意力，将审查批量合并，并丢弃任何过时的审查。

它完全可观测：你可以看到发送给分类器（例如 Jev）的内容，以及到达代理的内容。

不再需要 AGENTS.md 苦苦哀求“请使用领域类型”。将你的 AGENTS.md 指令提升到实时，并在你的代码风格规则被违反时立即拍打那只机器手。

审查代码编辑背后的决策

一个类型可能允许毫无意义的取值组合。一个函数可能假定其输入满足某种其类型并未强制执行的约束。发现这些问题可能需要阅读编辑行之外的更多定义。

Hapsland 找到被更改的类型或函数，并沿其引用收集相关定义，包括其他文件中的定义。每条规则会用所需的相关代码审查被更改的声明。如果必要的代码不可用，Hapsland 会跳过该规则。

子代理

Hapsland 还会审查 Codex CLI 和 Claude Code 子代理所做的受支持的原生编辑。当运行时能可靠识别出进行编辑的子代理时，Hapsland 会将审查反馈定向到它。

我的仓库会有什么内容外泄？

将源代码发送到审查服务是一项数据共享决策。

像 Jev 这样的一些分类器会存储你的数据，并可以随意处置。

你的任务提示词以及与代理的对话不会发送到审查后端。

复制到所选源代码或配置的规则问题中的文本，可能会作为这些输入的一部分被发送。请参阅内容隔离契约与证明限制。

你可以选择哪些已更改文件可以被审查，以及哪些文件可以提供相关代码。

选定的源代码和规则问题会发送给选定的外部分类器：默认是 Jev，或 Cloudflare Clef/Clef-flash。它看到的是那些代码和那些问题，而不是代理的任务或对话。Hapsland 将其结果映射到配置的反馈消息。检查器会收到一个类型声明，或一个 TypeScript 函数的签名和函数体，以及通过本地引用到达的相关代码。不会发送的内容：完整文件、编辑 diff、代理对话以及无关源代码。在有审查凭据且没有文件设置时，所有其他符合条件的文件都会被选中。当你想要更窄的边界时，请设置明确的范围。请参阅配置。

动画从一个小编辑开始，扩展到声明和相关代码，然后展示一个反馈与修复循环。反馈跟随编辑之后；它不会撤销编辑，也不保证修复。交付和可选的阻塞反馈取决于代理运行时和配置。有关流程及其边界，请参阅架构指南。运行 hapsland --feedback-preview 以查看带有合成发现的共享代理指令；不会发出审查请求。

选择审查后端

Jev 是默认选项。要使用 Cloudflare，请在你的用户配置中设置 reviewBackend（项目配置无法选择后端）：

使用你的 Cloudflare 账户 ID，并让已安装的运行时可以使用 CLOUDFLARE_API_TOKEN。模型也可以是 clef-flash；hapsland --login 管理 Jev 凭据。共享的限制目录会在有文档记录的地方检查请求字节数和问题数量，包括 Clef 的 64 个问题限制。Token 限制会被记录，但在能够强制执行之前需要一个分词器。详情请参阅提供商配置与限制。

Hapsland 还管理审查资源：每个后台服务都有独立的池，用于八个准备作业和八个并发分类器请求许可，此外还有对保留状态和建议输出的限制。关于饱和行为、配置控制以及收集限制与模型限制之间的区别，请参阅审查资源与限制。

经过形式化检查的核心

审查请求必须适配模型的上下文，包括规则问题。Hapsland 限制它收集的相关代码量。形式化证明检查核心是否将选定的代码保持在该配置的大小限制内。一个经过检查的访问拒绝案例不会发出任何读取被排除文件的命令。* 确定性模拟使用该核心来演练失败和恢复；原生集成测试检查独立的文件系统、传输和主机边界。

* 在已检查的排除案例中，核心不会为被拒绝的依赖发出源代码读取命令。这是对该案例的证明，而不是对每次执行中都不存在泄漏的普遍证明。源代码解析、文件系统观察和网络调用仍然是原生代码。请参阅证明范围与证据。

规则

默认情况下，授权设置会启用 7 个可编辑的 JSON 规则文件，其中包含关于代码设计的问题。

你可以编辑这些规则，或将你自己的关注点写为本地 JSONC 文件。

使用 hapsland rules list 或 hapsland rules show --id meaningless_combinations 检查它们。

使用规则参考来检查、管理和测试规则，或按照编写你的第一条规则获取完整示例。规则检查会将选定的源代码发送到你配置的分类器；一个结果并不能确立规则的准确性。请参阅语言与限制。

安装

让你的编码代理安装它：

使用 https://github.com/dearlordylord/hapsland/blob/master/docs/installation-workflows.md 为我的编码代理安装 Hapsland。让我以交互方式审查并批准设置更改。请让我在掩码设置提示中输入任何 Jev 密钥，而不是在聊天中。

现成的软件包可用于 macOS arm64 和 Linux arm64：

brew install dearlordylord/tap/hapsland
hapsland setup

在你想要审查的 Git 仓库中运行 hapsland setup。按照终端提示选择你的编码代理并确认安装其钩子，然后重启该代理。

公共 npm 包在 2026-10-06 返回了 404；下面的 npm 命令需要单独的 npm 发布。贡献者仍然可以使用本地检出安装，这需要开发工具链。

在设置之前，选择你的代理和审查文件范围。钩子会应用于所选用户配置文件，并跨仓库生效。

在稳定版本发布并验证后，手动安装：

安装 Hapsland：

npm install -g --ignore-scripts @hapsland/hapsland

在你想要审查的 Git 仓库中，运行：
```
hapsland setup
```
使用复选框选择 Claude Code、Codex CLI 和/或 Pi（方向键移动，空格键切换，回车键继续）。已安装的客户端会被勾选并标记。取消勾选某个客户端会保留其安装不变。要跳过选择器，请使用 hapsland setup claude、hapsland setup codex 或 hapsland setup pi。Pi 需要 Linux arm64 以及设置所接受的版本；OpenCode 设置不可用。

安装程序会预览已拥有的钩子，在应用前询问，通过掩码输入接受缺失的 Jev 密钥，显示所选的密钥来源和替换说明，并报告离线就绪状态。然后你可以使用内置问候语批准一次可选的 Jev 密钥检查；它不会发送任何项目代码，但可能会使用付费额度。
完成当前客户端工作，正常重启客户端，完成其原生信任提示。按照检查指南启用录制，进行新的受支持编辑，并检查其审查；仅安装并不能证明审查已运行。

这些钩子会应用于所选的用户配置文件，而不仅仅是你运行安装程序的仓库。在审查私有代码之前设置文件选择。安装和设置不会将代码发送给 Jev。

npm 命令使用你配置的全局前缀，并假定其 bin 目录在 PATH 上。如果安装因权限问题失败或命令缺失，请使用用户自有前缀替代方案。该包为每个平台包含一个 Bun 运行时；命令包共享它。

本指南并未确立公共注册表的可用性。有关当前分发和主机证据，请参阅安装通道。

使用 hapsland update 更新已安装的集成；添加 claude、codex 或 pi 以选择一个客户端。该命令会预览钩子更改并在应用前询问。使用 --channel=next 获取已发布的候选版本。

如果审查无法正常工作，请从 hapsland doctor 开始：它会诊断已注册的客户端而不更改文件。有关本地构建、更新、恢复和移除，请参阅安装工作流，或参阅 Claude 和 Codex 指南以了解确切的主机限制和自动化。

配置

通过个人和项目 JSONC 设置配置文件选择、相关代码访问、隐私排除和逐规则应用。如果没有文件设置，所有其他符合条件的文件都会被选中；用户排除项可以关闭审查。

一个小的项目配置：

有关字段、优先级、规则选择以及保存的更改何时生效，请参阅完整配置指南。

语言和限制

语言	已审查的代码	主要限制
TypeScript（`.ts`、`.tsx`、`.mts`、`.cts`）	接口、类型别名和命名函数，以及相关的本地类型和导入，在配置的限制范围内	不支持的语法或无法解析的证据可能会阻止审查。
Rust（`.rs`）	顶层结构体、枚举和类型别名，以及跨已验证 Cargo 模块的本地类型上下文	Hapsland 解析显式的本地 `mod`/`use` 绑定和别名。不支持外部 crate、重导出、内联模块、函数、宏和条件编译。Cargo 元数据和支持文件必须通过文件选择。诸如 `derive` 之类的属性会使默认规则的证据不完整。
Bend（`.bend`）	顶层 `type` 数据类型和构造函数载荷、普通或擦除的数据类型参数，以及字面量数量参数。相关定义来自同一文件、显式相对 `.bend` 别名导入或固定的 Base `List`，在配置的限制范围内。	不支持函数、定律/证明、依赖类型或计算类型，以及 hub、bare 或绝对导入。构造函数必须占据一行，使用两个空格缩进。数据类型语法中的字面量仍不受支持；无关主体中的字面量不会阻止提取。

Rust 跨文件上下文要求选择一个明确的 Cargo.toml，并指定 2018、2021 或 2024 edition 以及已接受的 library/binary 目标。工作区继承的 edition、自定义构建目标以及 test/example/bench 目标表不在本配置范围内。模块路径必须无歧义；被排除的辅助文件保持不读取。

语言支持适用于源代码审查；它不会选择 agent 运行时。如果某次编辑缺少某条规则所需的证据，Hapsland 会跳过该规则。沉默并不代表代码通过了审查。有关语法限制，请参阅审查契约；要查看审查活动，请参阅会话状态。

文档

使用文档指南查找安装、配置、规则编写、诊断、架构以及与现有解决方案的对比。

开发

有关源代码设置、代码风格、检查以及本地开发工作流，请参阅贡献指南。仓库地图可定位契约、实现负责人、测试、网站资源和研究内容。