koment

koment

让代码背后的 原因 紧随代码，并经过检查，避免悄然失效。

问题所在

有人把 retry 5 times 写成了 3 次，当时是有充分理由的。六个月后，没人记得原因，于是它被“简化”回 3 次，bug 又出现了。

原本注释是用来防止这种情况的。注释会失效：它们紧挨着代码，却没有与代码绑定；代码一旦变更，没有任何提示告诉你注释已经成了谎言。接着，你的 AI Agent 读到这句谎言，并据此采取行动。

koment 的作用

你可以在源代码之外记录原因，并将它锚定到所解释的确切代码行。然后 koment 会监视这些代码行。修改它们，koment 就会给出提示：

$ koment check
internal/auth/token.go
  drifted   gotcha        internal/auth/token.go  01KZN63VC5SZASDYJBMPDC03WB
    Without it, clients whose clock runs fast get logged out mid-request. Bit
    us in #412.
1 annotation across 1 file: 1 drifted
koment: 1 annotation no longer resolves; revisit it or update the anchor

退出码为 1。构建会停止。没有人会悄然沿用一个已无法描述代码现状的原因。

这些记录以 YAML 格式保存在 Git 仓库的 .koment/ 目录中。无需数据库、服务或账号。它们会与促使其编写的变更在同一个拉取请求中接受审核。

查看运行效果 → — koment 自己的注解，由可复制的工作流发布。

面向 AI Agent

koment 的价值在这里体现得淋漓尽致。Agent 经常编写解释性注释，也会在不理解代码编写缘由的情况下修改代码。koment 会让这两种行为立即失败，此时 Agent 仍在工作：

• 它编写注释 → 编辑会被拒绝，并提示将相关理由记录为注解。
• 它未经检查就修改带有注解的代码 → 必须重新检查注解，才能完成本轮操作。

一个 MCP 服务即可为 Claude Code、Cursor、Codex、opencode、Hermes、Zed 等工具提供服务，让每个 Agent 都能通过相同的接口读取相同的理由。 配置你的环境 →

人类也能在编辑器中体验同样的流程：注释下方会出现波浪线，并提供快速修复选项：转换为注解或保留并记录在案。

安装

brew install koment-dev/tap/koment

mise use -g github:koment-dev/koment          # mise
go install github.com/koment-dev/koment/cmd/koment@latest
docker run --rm -v "$PWD:/repo" -w /repo ghcr.io/koment-dev/koment:3 check

一分钟快速上手

在任意 Git 仓库中运行：

koment bootstrap

此操作会创建 .koment/，并为你使用的 Agent 配置相应连接。现在，记录一个原因并观察它如何接受检查：

koment add src/auth.go \
  --excerpt 'if token.Expiry.Before(now.Add(-clockSkew)) {' \
  --kind gotcha \
  --title 'Skew subtraction keeps fast clocks logged in' \
  --body 'Without it, clients whose clock runs fast get logged out
          mid-request. Bit us in #412.'

koment check     # ok

现在修改那一行，然后再次运行 koment check。 检查会失败，并告诉你哪些理由与对应代码不再匹配。这就是整个产品；其余部分只是将它交付给需要它的人和 Agent。

koment ui        # read them in a browser
koment show src/auth.go

工作原理

1. 你为一段代码添加注释。koment 会记录说明文字、精确摘录、周边源代码上下文、当时所在的提交，以及你的身份。

2. 记录会写入 .koment/annotations/<id>.yaml，每条注释对应一个文件。并发运行的 Agent 会创建彼此独立的文件，而不是替换同一个共享列表。

3. 解析器会在当前文件中搜索该摘录，并生成且只生成一种状态：

   	含义	构建
   ok	在上次找到的位置找到	通过
   ambiguous	仍有多个符合上下文的候选项	失败
   drifted	文件存在，但已找不到注释所指的代码	失败
   orphaned	文件已不存在	失败

4. 遇到 ambiguous、drifted 或 orphaned 时，koment check 会以非零状态退出。这就是全部机制：不确定的理由比没有注释更糟，因此必须确保无法忽略。

5. 检查失败时，运行 koment reanchor <id> --excerpt '<new text>' 重新指向代码——保留其 ID 和创建日期，并为你重新采集上下文和行号。系统不会自动重新关联；必须由人确认原有理由仍然成立。

锚定依据是摘录，而不是行号——编辑上方的内容后，行号就会失效。系统会记录提交哈希，但它只用于还原历史；它不会决定注释是否仍然适用。这是两个不同的问题，需要用两种不同的机制处理。

本地写入会修改你当前正在审查的工作区。通过服务写入绝不会触碰副本或推送默认分支：它们会在确定性分支上创建精确注释，并且只会在拉取请求创建后返回。静态发布内容始终不可变且只读。

三种运行方式

任选一种。每种方式都是一个可停留的选择，而非必须经历的步骤，在它们之间切换不属于迁移——三者读取的都是 Git 中相同的 .koment/，因此无需导出、导入或备份。

多个代码库

一次部署即可服务多个代码库。身份独立于提供方路径分配，每次刷新都会先将分支解析为一个不可变提交，再替换代码库的活动快照：

# yaml-language-server: $schema=https://raw.githubusercontent.com/koment-dev/koment/main/schema/server.schema.json
repositories:
  - id: payments
    name: Payments API
    provider: github
    remote: you/payments
    default_branch: main
    default: true
  - id: web
    name: Customer Web
    provider: github
    remote: you/web
    default_branch: main

只有在非回环监听器配置了可信代理身份或限定范围的 bearer 凭证后，服务才会启动。私有代码库和经过审查的写入还需要 GitHub 令牌。Helm chart 文档介绍了密钥格式和边界。

本地命令无需这些配置——koment 会从工作目录向上查找所属工作区。

Kubernetes

koment 会将 OCI Helm chart 发布到 oci://ghcr.io/koment-dev/charts/koment：

helm install koment oci://ghcr.io/koment-dev/charts/koment \
  --set repositories[0].remote=you/your-repo \
  --set metrics.enabled=true \
  --set metrics.serviceMonitor.enabled=true \
  --set metrics.dashboard.enabled=true

应用端口会对源代码、说明文字、UI 和 MCP 进行身份验证；只有存活状态和就绪状态检查是公开的。指标使用单独的监听器，避免入口控制器意外地将其与应用身份验证一起暴露。该 chart 包含 Grafana 仪表板、ServiceMonitor、强化的 Pod 默认配置、可选的 NetworkPolicy 和中断控制，以及固定摘要的 helm test 探测。

配置

每个标志都可以通过环境变量设置。--flag-name 会变成 KOMENT_FLAG_NAME，显式指定的标志始终优先。

Git 是唯一的权威记录。本地读取会直接根据工作树解析 YAML；可丢弃的读取模型无法恢复或覆盖 Git。

koment <command> --help 会列出每个标志及其对应的变量。

在代码所在之处工作

参考 VS Code 扩展会启动 koment lsp， 将注释正文呈现为虚拟内联文本，将漂移和违规评论报告为诊断，并添加原生的添加、重新定位、转换和显式 确认操作。说明文字绝不会插入源缓冲区。 每个版本都会附带经过签名的 VSIX，并将同一构件发布到 VS Code Marketplace 和 Open VSX。

其他编辑器可以使用 koment lsp 提供的标准悬停、诊断、代码透镜、代码操作 和执行命令接口，无需重新实现存储或锚定功能。

Claude Code 可以安装仓库自带的项目级 Marketplace 插件：

/plugin marketplace add koment-dev/koment
/plugin install koment@koment-dev

它捆绑了可写的 MCP 配置，在会话开始时注入严格流程，并在 Claude 完成一轮对话前运行策略门禁。请先安装已发布的 koment 二进制文件，并在仓库中运行 koment agents install。

OpenCode 在 integrations/agent-plugins/opencode/ 提供了并行插件。 将 @koment/opencode-koment 添加到 opencode.json 中的 plugin 数组；OpenCode 会在启动时安装它。它要求 PATH 中有已发布的 koment 二进制文件， 会拒绝普通的说明性评论意图，并在会话结束时运行策略门禁。ADR 0144 记录了软件包和生成适配器的边界。

Codex 通过 integrations/agent-plugins/codex/ 中的本地 Marketplace 提供相同的策略接口。 使用 codex plugin marketplace add 安装该检出路径，然后运行 codex plugin add koment@koment-dev。发布工作流也会生成经过签名的归档文件。该插件提供可写的 MCP 工具、常驻技能和受信任的生命周期钩子。ADR 0151 记录了软件包边界。

交给你的 Agent

koment agents install
koment mcp --write

生成的仓库适配器为 Agent 提供严格的操作流程，并配置可写入的 stdio 服务。它提供三个读取工具：

• koment_get(file, repository?) — 获取 Agent 即将编辑的文件的注释
• koment_search(query, repository?) — 按主题查找理由；省略 repository 时会搜索所有仓库
• koment_repositories() — 查看此部署服务的仓库及其数量

写入模式会增加四个工具：

• koment_add — 创建带有 Agent 归属信息的理由
• koment_reanchor — 显式移动现有锚点
• koment_convert_comment — 将评论记录为理由，然后移除该评论
• koment_acknowledge_comment — 仅在显式确认后保留特殊评论

这四个变更工具都在本地检出版本上操作。经过身份验证的 MCP 服务接口会公开 koment_add，并返回确定性的分支、提交和拉取请求 URL；会修改源代码的转换和重新锚定操作则保留在本地，避免服务覆盖 Agent 的独立工作树。

每条注释都会附带其解析状态和所属仓库，因此过时的注释绝不会被当作当前信息展示，查询结果也不会脱离其适用范围。当某个路径存在于多个仓库中时，koment_get 会拒绝操作并列出候选项，而不是猜测。

发布

审阅者不会安装任何东西。给他们一个 URL 即可：一个工作流文件会将所有注释渲染为静态 HTML，以及 annotations.json 和 search.json，然后将原子快照发布到 GitHub Pages，无需设计服务器、数据库或身份验证。

- uses: actions/checkout@v7
- uses: koment-dev/koment@v3
- run: koment check
- run: koment site --out dist

每个页面都会标明其渲染所依据的提交，因此快照绝不会被误认为当前代码树。同一工作流中的 koment check 会确保任何存在偏差的构建在发布前失败。

获取可直接复制的完整工作流 →

网站除了注释也会渲染源代码，因此从私有仓库发布网站就会公开该源代码。分组发布会为每个仓库渲染一个快照，并通过常规仓库切换器将它们连接起来；不会有选择器首页。

文档

• 发布 — 可复制粘贴的工作流，以及之后迁移到服务实例的方法
• 贡献者设置 — 建立经过验证的开发检出版本
• 快速入门 · 撰写优质注释 · CLI 参考 · CI

koment 不是什么

• 不是通用项目文档。 koment 保存的是与代码中的某个位置绑定的知识；宽泛的项目指南应放在团队已经使用的文档系统中。
• 不是记忆系统。 汇总型存储会改述、合并，并最终遗忘。koment 是记录，而非观点。
• 不是精确到行的。 锚点是代码片段。

相关先例

Codetations / Magic Markup 是最接近的现有项目——提供位于文档之外的注释，并使用大模型重新锚定。锚定问题可追溯至 Microsoft Research，2001 年，至今在一般情况下仍未解决。它的界面形态借鉴了 konflate：konflate 为 Flux 显示一个不可见层，而 koment 也试图以此方式呈现理由。

许可证

除 integrations/editors/zed/ 外，本仓库适用 AGPL-3.0-or-later 开源许可。该扩展的代码单独适用 GPL-3.0-or-later，以便 Zed 能够通过其注册表构建并分发该扩展；它启动的 koment 二进制文件仍适用 AGPL。两份许可证文件均为原文，以便自动扫描工具正确识别。ADR 0145 记录了这一有限例外。

完整的对应源代码即为本仓库：https://github.com/koment-dev/koment。对于通过网络与 koment 服务交互的任何人，本仓库满足 AGPL §13 的义务。

对于政策不允许使用 AGPL，或希望获得保修或赔偿的组织，可按需申请商业许可证 — 请发送邮件至 [email protected]。

≤ v0.6.0 的版本以 MIT 许可证分发，并永久保留 MIT 许可。可无限期依据这些条款，从最后一个带 MIT 标签的源代码 v0.6.0 创建分支。相关决定记录在 ADR 0117 中。

使用 koment 会让我的代码也适用 AGPL 吗？ 不会。koment 是一种工具；它写入的注释属于数据，而非该工具的衍生作品。这与使用 GCC 编译程序的法律性质相同：工具的许可证约束的是工具，而非你用它构建的内容。这也是所有经 OSI 批准、用于处理外部输入的 AGPL 部署所秉持的意图；如果你所在组织的法律顾问对此有异议，商业许可证可以解决问题。