内容
="center">
# Tether MD
您评论。智能代理提出修改建议。您决定。
[](https://github.com/tether-md/tether-md/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/tether-md)
[](LICENSE)
<img src="docs/assets/hero.gif" alt="Tether MD 工作流程：评论某段文字，智能代理提出修改建议，接受应用修改，导出结果与原文字节级一致" width="820">
<i>在草稿中评论，提出事实或解读。智能代理一次性处理所有评论；您可以接受或拒绝每个修改建议。导出结果保持字节级一致。</i>
</div>
---
大多数 AI 写作界面要么在您不知情的情况下重写您的文档（聊天画布、“应用”按钮），要么将审阅功能锁定在特定平台上（Google Docs、Word、Notion）。Markdown 在 git 中没有标准的建议模式：一种方式是对某段文字留下评论，让 AI 根据评论进行修改，并让您自己批准或拒绝每个修改。
Tether MD 就是这一层：为 Markdown 添加锚定评论，AI 代理可以根据评论提出修改建议，但永远不会直接应用修改。它是一种文件格式，而不是一个平台。
- **评论存储在文件中。** 每个评论都有一个不可见的 HTML 评论标记和一个机器可读的代码块存储在文件末尾。无需数据库，无需辅助文件，无需服务；原始文件可以在 GitHub、VS Code 预览和通过 pandoc 渲染干净。
- **锚定评论在编辑过程中保持一致。** 使用模糊重新锚定技术，评论会跟随文本变化，并在需要审阅时标记不确定的匹配项或孤立的评论。
- **智能代理提出修改建议；人类应用修改。** 您的评论是锚定指令。智能代理附加修改建议；接受应用修改并清除评论，拒绝则丢弃建议。
- **导出结果经过 CI 测试，确保字节级一致。** 一个投影函数剥离评论层；结果与原文字节级一致。
## 快速入门
```sh
npm i -g tether-md
```
```sh
printf '一份包含特定短语的草稿。\n' >tether comment add draft.md --quote "特定短语" --body "精简此段" --write
tether status draft.md # 查看评论、建议和锚定健康状况
tether comment suggest draft.md <id> --to "更紧凑的版本" --write # 智能代理的修改建议（或您自己的）
tether comment diff draft.md <id> # 预览：当前版本 / 建议版本
tether comment accept draft.md <id> --write # 应用修改并清除评论
tether export draft.md # 导出作者的原始文本，字节级一致
```
每个修改命令默认打印其结果，只有在 `--write` 标志下才会就地编辑文件，并且支持` 格式。退出代码稳定：
| 代码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 用法错误 |
| 2 | 存储块格式错误 |
| 3 | IO 错误 |
| 4 | 检查失败（`status --check`） |
在 30 秒内尝试在一个真实文档上使用：[`examples/`](examples/) 提供了一个完整的演练，包括导出保证的单行证明（`tether export reviewed.md | diff - draft.md` 输出为空，表明字节级一致）。
## 连接您的智能代理
在您的项目中运行一个命令：
```sh
tether init # 生成 .mcp.json（项目范围的 MCP 服务器）+ AGENTS.md 合同注释
tether init --skill # 还会将 Claude Code 技能安装到 .claude/skills
```
Claude Code 会在下次打开项目时自动发现 `.mcp.json`，而 `AGENTS.md` 则为使用自己的文件工具的智能代理提供了合同。两个操作都是幂等的，可以合并到现有的文件中。要手动配置 MCP 服务器，可以使用任何支持 MCP 的智能代理（Claude Code、Cursor、Codex CLI 等）：
```sh
claude mcp add tether -- tether mcp
```
MCP 服务器暴露了 `tether_list`、`tether_status`、`tether_diff`、`tether_suggest`、`tether_comment`（）tether_export`故意省略了 和 edit 操作，其服务器指令告诉所有连接代理保持在该其中，信任结构性的，而不是基于提示的礼仪。
有一个重要的大多数编码智能代理（ Code、Cursor 等）也文件工具，并且格式可以限制这些工具。 如果智能代理从未被，它会像处理其他一样处理 Tether 文件并直接编辑它。 因此，请：运行 `tether init`，安装下面的技能，或将项目的 `AG` 或 `CLAUDE.md` 中：
```
文件可能包含 tether-md 评论：不可见的 <!--tether:...--> 标记和文件末尾的存储永远不要直接编辑；永远不要触摸存储块。 使用 `tether comment list` 读取线程，使用 `tether comment suggest <file> <id> --" --write` 写，使用 `t add <file> -- --body "..." --author agent --write` 点。 接受、拒绝和导出属于人类。
Claude Code，还有一个，[`skills/tetherKILL.md`](skills-edit/SKILL它从头到尾：读取文档，读取指示建议修改，标记无法定位的内容，交回。智能代理永远不会解决或导出。
变为：评论短语智能代理“解决”，然后在编辑器每个建议并接受或。
## 在 VS
安装扩展：从leases](https://github.com/tether-md/tether) 下载 `tether-md`，然后在 VS Code 中打开扩展面板，从其 `⋯` 菜单中选择从 VSIX 安装。或者，从克隆仓库中构建它（`npm install && npm run build && npm run package -w tether-md-vscode`）。然后：
- 选择文本，按 <kbd>⌘⌥C</kbd>（Windows/Linux 上的 <kbd>Ctrl+Alt+C</kbd>），输入；它呈现为内联线程
- 智能代理的建议在线程中以 diff出现（当前版本与建议版本），带有接受和拒绝按钮 模糊重新锚定会得到虚线警告下划线和诊断信息立的评论问题”面板中出现一键修复按钮
Tether: 文档”会在文件旁边写入 `<name>.clean.md VS Code 在每个逻辑显示一个 `+`对于同一段软文本上的第二个评论文本并使用快捷键器和智能代理永远不会相互通信。它们只会操作文件，因此您可以在打开器中查看建议## 文件的实际内容
```markdown
模式始终相同。应用程序从文本编辑，变成数据库。 <!--:c=01KWQFDFTHXWAF7RJS1ZNSSX-->数据库在下一轮存在。
<!--tether:store
{"idKWQ2QFDFTHXWAF7RJS1ZNSSX","1,"trust":"fact":"human","body":"sharpen this",...}
:store-->
```
每个评论都有一个插入符标记（一个 ULID，不能形成 `--` 序列，这是 HTML 评论），所有数据都 JSONL 存储块中文件末尾，经过以保持语法合法。渲染隐藏 HTML 评论，因此原始文件在 GitHub、VS Code 预览和通过渲染时看起来很干净。语法、投影算法器模型和重新锚定置信度区间docs/spec/wire-projection.md`](docs/spec-format-and-pro) 中指定。规范；这里的 Type参考实现。
## 文本编辑时发生了什么
一个短语，您不断编辑文档。每次读取文件时，每个评论都会重新匹配到当前文本，并获得一个 0 和 1置信度分数了三种结果之一| 结果 | 条件看到的内容 |
|---|---|锚定语仍然匹配（ 0.75）跟随其文本 |
| 需要审阅 |变化足够使匹配变得.50–0.75） | 虚线线和诊断接受在您重新拒绝 |
| 孤语实际上已经 0. | 明显的错误；` status --check退出代码 4，以便捕获它 |
弱匹配会降级为“需要审阅”或孤立的评论；它不会无声地附加到错误的位置。
<div align="center">
<img src="docs/assets/anchors.gif" alt="评论跟随其文本，通过编辑，标记为需要审阅，当短语被删除时孤立" width="800">
</div>
匹配首先尝试精确，然后通过周围上下文消除重复，最后在使用模糊匹配，这是分数的来源（详见 [docs/spec/wire-projection.md)）。 额外的保护措施是需要仍然与建议一致，因此过不会拼接成的措辞。
##不变性
上述都归结为，在每次提交时都会：
1.锚定或。** 在任何都会重新在置信度以上或明显孤立匹配永远不会无声无息。
2零扰动。或删除评论永远不会出的文本或任何其他评论的锚点. **导出身份。** `tether export`级别与作者的完全一致。
##| | 文件中评论随编辑保留 建议，人类接受 | 与任何代理一起工作干净的导出保证 |
|---|---|---|---|---|---|
MD | 是 | 模糊，响亮的孤 原生线程 / + MCP + | 字节相同，在 |
| Google Docs / Notion | 否（平台数据库） | 是仅他们的 AI | 导出与源| GitHub PR | 否（PR） | 否（在 上过时） | 在 PR UI 中 |绑定机器人 | 不 diff，而不是文档） |
| CriticMarkup | 是（可见语法） | 内联，无漂移检测 | 无原生流程 | 仅格式 | 取决于处理器 |
| 游标 / 聊天画布 | 否（会话diff） | —到会话结束 | — |
| Rough 是（CriticMarkup） | 内联，无漂移检测 | 在其本地 Web UI 中 | 是（CLI 未指定或 |
我们的赌注是模式应该成为文档应用程序的属性。这也是 格式独立于此实现；欢迎移植。
使用 CriticMarkup语法在任何 CriticMarkup感知渲染器可见的噪音Hub），并且其评论仅通过邻接没有任何机制检测当针对的文本被时。Tether 的渲染视图中隐藏引用文本重新。 为什么不使用审查？ 那里的到 diff 行在数据库中，需要远程和请求，并在 rebase 后这里，文档本身承载审查，在任何仓库状态下离线。
## 多模块仓库
| 包 | 描述 |
|---|---|
| [`tether-md`](packages/cli) | `tether` CLI 和 MCP 服务器（`tether mcp`）：稳定的、仅限文件的契约接口。 |
| [`@tether-md/kernel`](packages/kernel) | 纯投影内核：`P(raw) → clean`，锚存储编解 IO。 [`tether-md-vscode`](packagescode-ext) | 扩展（原生评论 API）。 |
| [``](skills) |契约（Cl 技能）。 |
docs/`](docs 线格式规格，架构决策里程碑 |
```sh
https://github.com/tether-md tether-md
&& npm run build test
```
## 限制（v0.1）
- 编辑器 UI 目前仅限于 VS Code。内核与编辑器无关；Obsidian 和 nvim 移植是最需要的贡献。
- 建议-不应用契约在 MCP 接口上是结构性的，但具有自己文件工具的代理只有技能或上述 `AGENTS.md` 注释遵循它。 未知代理会像其他 Markdown编辑文件。
- 存储块仅限 LF CRLF 报错而不是错误解析；存储库的 `.gitattributes` 保护签出，容错读取正在跟踪。
- 每个文件一个存储块；并发写入者在文件级别竞争。像源代码一样对待（git 合并不佳）。
- 在代码区域内锚定的评论会将其标记重新区域之前。 两个病理形状被拒绝。
## 路
- 验证门（起源）：事实验证和声明强度检查，其发现作为锚定评论到达 CriticMarkup导出，端口ance 测试向量， 插件，浏览器构建。
## 贡献
规格第一，三个不变性不可妥协错误优先于。参见 [CON](CONTRIBUT## 许可证
MIT
