内容
<p align="center">
<img src="./assets/readme/hero.svg" width="100%" alt="CommitLore: commit 4842356, record r-2b58d4, is graded [claim] and guard returns MATCH">
</p>
<p align="center">
<a href="https://github.com/MongLong0214/commitlore/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/MongLong0214/commitlore/actions/workflows/ci.yml/badge.svg"></a>
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-3f6b52"></a>
<a href="package.json"><img alt="Node.js 22 or newer" src="https://img.shields.io/badge/Node.js-%3E%3D22-3f6b52"></a>
</p>
<p align="center">
<strong>中文</strong> · <a href="README.ko.md">韩语</a> · <a href="README.ja.md">日语</a> · <a href="README.zh-CN.md">简体中文</a>
</p>
# CommitLore
CommitLore 是一个用于在 Git 提交记录中保留决策上下文的协议，主要通过在提交记录的尾部添加 trailers 以及在 `refs/notes/commitlore` 中存储相关信息来实现。该协议优先于客户端的实现，客户端负责验证、路由和向 shell、钩子（hooks）和 MCP 客户端暴露这些记录。目前尚未证明 CommitLore 能改善代码代理的行为。
## 测量记录
<!-- BENCH:WITHDRAWN -->
已注册的行为测量并未显示 CommitLore 能改变代理的行为。后续的一次运行被作废，因为在运行过程中测试二进制文件被更改。更根本的是，现有的数据集并未记录足够多的出处信息，以证明哪个构建过程产生了每一条记录，因此 [`bench/report.ts`](bench/report.ts) 拒绝汇总这些记录。
所有此前发布的基准测试结果均被撤回。已过期的裁决仍然作为记录可查阅，而不是作为效果声明：[`VERDICT-M1.md`](bench/VERDICT-M1.md)、[`VERDICT-M1b.md`](bench/VERDICT-M1b.md)、[`VERDICT-M2.md`](bench/VERDICT-M2.md)，以及[被作废的运行记录](bench/PREREGISTRATION.md#15-m3-is-void-the-binary-under-test-changed-while-it-ran)。只有当数据集能识别测试基准和捆绑的二进制文件时，数字才会恢复。参见 [`bench/README.md`](bench/README.md)。
## 仓库证明的内容
- **记录在正常的 Git 工作流中存活。** 提交记录的尾部和 notes 镜像在 [变基和压缩](test/squash.test.ts)、[历史重写和远程传输](test/notes.test.ts) 以及 [单步和多步重命名](test/follow.test.ts) 中得到验证。
- **信任在各个路由中具有相同的含义。** 查询输出、CLI 注入、编辑钩子、MCP 工具和防护（guard）都使用相同的 `directive | claim | blocked` 等级。路由检查位于 [`query.test.ts`](test/query.test.ts)、[`inject.test.ts`](test/inject.test.ts)、[`mcp.test.ts`](test/mcp.test.ts) 和 [`guard.test.ts`](test/guard.test.ts)。
- **类似注入的记录不会以纯文本形式到达模型。** 当任何自由文本尾部与注入模式匹配时，记录被评为 `blocked`；可读路由报告内容被保留，但不引用它。CLI/钩子案例在 [`inject.test.ts`](test/inject.test.ts) 中，MCP 在 [`mcp.test.ts`](test/mcp.test.ts) 中针对相同答案进行了检查。
- **未知不为空。** 防护（guard）以 `0` 退出，对于具有记录的可读仓库，没有记录则退出 `3`。合约在 [`notes-availability.test.ts`](test/notes-availability.test.ts)、[`guard.test.ts`](test/guard.test.ts) 和 [`RELEASE-GATE`](docs/RELEASE-GATE.md) 中固定。
## 一条记录
此示例也是一个一致性测试。Git 自己的尾部解析器必须在每个翻译的 README 中以相同的方式读取它。
```text
防止在长时间运行的操作期间出现静默会话丢包
身份验证服务在令牌过期时返回不一致的状态代码，
因此拦截器捕获所有 4xx 响应并触发内联刷新。
限制：身份验证服务不支持令牌自省
记录 ID：r-4b7e21
排除：延长令牌 TTL 至 24 小时 | 安全策略违规
排除：基于定时器的后台刷新 | 竞争条件
确定性：坚定
影响范围：模块
撤销：容易
警告：4xx 处理故意为之广泛
-- 在验证上游行为之前不要缩小范围
已验证：单个过期令牌刷新（单元）
未验证：身份验证服务启动 > 500ms 行为
CommitLore 版本：2.0.0
```
### 协议词汇
| 尾部字段 | 含义 |
|---|---|
| `限制:` | 限制决策的外部条件 |
| `记录 ID:` | 跨重写提交哈希的稳定身份标识 |
| `排除:` | `替代方案 \| 原因` |
| `确定性:` | `坚定` \| `尝试` \| `猜测` |
| `影响范围:` | `本地` \| `模块` \| `系统` |
| `撤销:` | `容易` \| `昂贵` \| `永久` |
| `警告:` | 未来修改者的警告；交付前信任评级 |
| `已验证:` / `未验证:` | 已检查和未检查的内容 |
| `遵循:` / `取代:` | 决策链和生命周期链接 |
| `过期:` | 结束约束的日期或条件 |
| `证据:` | 支持声明的路径、锚点或 URL |
| `出处:` | `作者` \| `继承 <sha>` \| `重建` |
| `CommitLore 版本:` / `X-*:` | 协议身份和扩展 |
完整的合约在 [`spec/SPEC.md`](spec/SPEC.md) 中。
## 信任是路由，而不是徽章
提交 `4842356` 包含此活动记录：
```gitcommit
排除：豁免在字段存在之前编写的数据集 | 它只有一行并且删除了保证
警告：这使得 README 在 M3-b 运行之前没有任何测量的数字。 这是诚实的态度，但这也是更糟糕的第一印象。 另一种选择是发布二进制文件 nobody 记录的数字
记录 ID：r-2b58d4
出处：作者
```
相同的 `警告:` 文本按评级路由：
| 等级 | 条件 | 模型可读路由接收的内容 |
|---|---|---|
| `[指令]` | `出处：作者`，活动记录和作者在此仓库中明确受信任 | 警告作为指令 |
| `[声明]` | 没有受信任的作者，外部作者或重建/未知出处 | 警告作为信息，附有明确的“非指令”标签 |
| `blocked` | 任何自由文本尾部与注入模式匹配 | 保留通知；匹配内容不呈现 |
默认情况下，没有作者是受信任的。加密作者验证未实现；它在问题 #28 中被跟踪。
## 从克隆安装
没有 CommitLore 注册表包。分发是 Git 仓库（[ADR-0011](docs/adr/ADR-0011-plugin-first-distribution.md)），CLI 需要 Node.js 22 或更新版本：
```bash
git clone https://github.com/MongLong0214/commitlore ~/.commitlore
node ~/.commitlore/dist/commitlore.mjs --version
node ~/.commitlore/dist/commitlore.mjs doctor --fix
node ~/.commitlore/dist/commitlore.mjs context src/auth --no-index
```
提交的捆绑包无需构建即可运行。仍然存在一个警告：它不携带本地 `better-sqlite3` 模块，因此克隆本身无法打开 SQLite 索引。使用 `--no-index` 直接扫描 Git，或在克隆中运行 `npm install` 以启用当前索引。接受的迁移远离本地模块在 [ADR-0012](docs/adr/ADR-0012-drop-the-native-dependency.md) 中记录。
对于 MCP 客户端，注册相同的克隆入口点：
```json
{
"mcpServers": {
"commitlore": {
"command": "node",
"args": ["/absolute/path/to/commitlore/dist/commitlore.mjs", "mcp"]
}
}
}
```
无需 CLI 即可读取协议：
```bash
git log --format='%(trailers:key=Ruled-out,valueonly,separator=%x3B)'
git log --follow --format='%h %(trailers:key=Limit,valueonly)' -- src/auth/
```
使用 Git 的尾部解析器，而不是文本搜索；包含 `Key:` 的纯文本不一定是尾部块。
## 它尚未完成的功能
- 加密验证作者：[#28](https://github.com/MongLong0214/commitlore/issues/28)
- 报告仓库范围的记录覆盖率：[#32](https://github.com/MongLong0214/commitlore/issues/32)
- 将记录锚定到符号而不是路径：[#33](https://github.com/MongLong0214/commitlore/issues/33)
- 提供交互式提交构建器或自动过期提醒：[#34](https://github.com/MongLong0214/commitlore/issues/34)
- 通过有效基准测试证明防护（guard）对代理行为的影响：[#37](https://github.com/MongLong0214/commitlore/issues/37)
- 在没有 Node.js 的情况下作为静态二进制文件运行：[#39](https://github.com/MongLong0214/commitlore/issues/39)
## 贡献
阅读 [spec](spec/SPEC.md)、[ADRs](docs/adr/) 和 [`CONTRIBUTING.md`](CONTRIBUTING.md)。此仓库记录了其自身的决策；在更改文件之前运行 `commitlore context <path>`。
## 许可证
[MIT](LICENSE)
