内容
# 目录
## 工具列表
## 安装
```bash
cd gloss
npm install && npm run setup
```
`npm run setup` 是幂等的，它一次性完成所有操作：链接 `gls` 命令到你的 `PATH`，注册 MCP 服务器（`claude mcp add`，用户范围），并安装 `Stop + PostToolUse` 钩子，以保持实时编辑循环，信号 UI 当代理编辑，并关联每个审阅到其 Claude 会话。它报告它更改的内容。（再次运行它；它不会重复。）
## 使用
命令是 `gls`（保留 `gloss` 作为别名）。如果你跳过了 `npm run setup`，请使用 `npm link` 将其链接到你的 `PATH`。
**新用户？参加交互式导览：**
```bash
gls review samples/welcome.md
```
`samples/welcome.md` 是一个实时演练 - 它教你注释，键盘导航，笔记面板，弹出笔记和审阅循环，让你直接在 UI 中尝试每个功能。
在文件夹上启动（默认为当前目录）：
```bash
gls ./docs # 或：npm start -- ./docs
```
这将打开一个浏览器，显示 `./docs` 下的每个 `.md` 文件列表。点击一个文件进行阅读和评论。标志：`--port N`，`--no-open`。
### `gls review` - 阻塞单个文件审阅
CLI 的双胞胎（如下）：打开一个文件，**阻塞**，直到你点击 **完成审阅**（或关闭标签页），然后打印收集的评论 + 笔记。
```bash
gls review ./proposal.md # 人类可读的摘要
gls review ./proposal.md --json # 机器可读的，纯 JSON 输出
```
`--json` 形式打印与 MCP 工具返回的相同结果形状，因此任何可以运行 shell 命令的脚本，代理或 CI 步骤都可以获得相同的阻塞审阅循环 - 无需 MCP 客户端。标志：`--json`，`--no-open`，`--timeout MS`。进度（URL）输出到 stderr，因此 stdout 保持纯 JSON。
要直接打开特定文件：
```
http://localhost:5173/?path=/absolute/path/to/file.md
```
或者只需运行 `npm run dev` 并自己传递 `?path=...`。
### `gls list` - 管理打开的会话
查看所有项目的所有打开审阅并关闭它们：
```bash
gls list # 交互式：↑/↓ 移动 · x 关闭 · r 刷新 · q 退出
gls list --json # 机器可读的转储（也用于管道）
```
每行显示文件，所有者进程是否为 **●实时** 或 **○孤立**（被崩溃会话遗弃），及其年龄。关闭实时审阅会正常结束它 - 就像点击 **完成**，因此其代理获得正常的 `mode:"done"`；孤立的会话直接被回收。当审阅卡住或你丢失了正在运行的跟踪信息时，这非常有用。
## 评论文件（LLM 面向的合约）
`notes.md` 的评论写入同一文件夹中的 `notes.comments.json`：
```json
{
"version": 1,
"file": "/abs/path/to/notes.md",
"notes": "## 自由笔记\n\n审阅者输入的 markdown，不绑定到评论",
"comments": [
{
"id": "0b3c…",
"anchor": { "start": 142, "end": 168 },
"quote": "突出显示的确切文本",
"body": "用户的评论",
"resolved": false,
"status": "saved",
"createdAt": "2026-06-15T12:00:00.000Z"
}
]
}
```
`anchor.start`/`end` 是渲染的纯文本的字符偏移量；`quote` 是字面上的突出显示文本。LLM 可以 grep `*.comments.json`，读取每个 `quote` + `body`，并相应地修订源 `.md` 文件。可选的 `notes` 字段保存审阅者在笔记面板中编写的自由 markdown - 这是与特定段落无关的常规反馈。
每个评论还包含一些可选的记帐字段，当仅读取反馈时，可以忽略这些字段：`status` 是实时编辑生命周期 - `"saved"`（默认，一个普通的批量评论），然后 `"queued"` → `"working"` → `"done"`，当“发送现在”评论被发送到代理时（带有 `queuedAt` 时间戳）；如果审阅者在第一次编写后修改了正文，则会设置 `editedAt`。
## MCP 服务器（LLM 驱动的审阅）
MCP 服务器公开了两个工具，允许 LLM 请求对 `.md` 文件的人类审阅，读取评论，然后关闭它们。这是与 `gls review`（共享核心位于 `lib/review.js`）相同的阻塞流程 - 将 MCP 用于循环中的代理，等待结果作为工具调用，以及 CLI 用于人类，脚本或仅限 shell 的代理。
`review_markdown`：
1. 启动 gloss UI，限定在文件的目录中，
2. 在浏览器中打开文件，
3. **阻塞**，直到您点击 **完成审阅**（或直接关闭浏览器标签页 - 那也会结束会话），
4. 以内联方式返回您的评论（每个评论都有 `id`，`quote` + `body`）以及任何自由笔记和评论文件路径，
5. 将 UI 关闭。
`resolve_comments({ path, ids })` 然后让代理将评论标记为 `resolved: true`（gloss 保留 JSON 所有权 - 代理从不手动编辑它）。已解决的评论折叠在 **显示已解决** 下，并从下一个审阅的开放集中删除。CLI 双胞胎是 `gls resolve <file.md> <id…>`。
`npm run setup` 已经为您注册了此功能（具有正确的绝对路径）。要手动执行，请一次性全局注册它（在所有项目中可用）- 从 gloss 仓库根目录：
```bash
claude mcp add --scope user gloss -- node "$(pwd)/mcp/server.js"
```
作用域：`--scope user` = 所有项目（推荐）· `--scope project` = 提交的 `.mcp.json` 用于共享仓库 · `--scope local` = 仅当前项目。
工具输入：`{ "path": "/abs/file.md", "timeoutMs"?: number }`（省略 `timeoutMs` 以无限期等待）。
## 许可证
[MIT](LICENSE) © Percival Moser
