# TraceCite 输入约定

0.5.0 的文档维护主入口是 `check`，支持本地链接、来源代码片段和自动快照，见 [文档维护指南](maintenance.md)。本文件保留原来的报告、笔记与 Agent JSONL 接口约定。

TraceCite 提供 Markdown 报告引用块、轻量引用笔记和 Agent JSONL 三种输入。报告格式适合在发布前直接检查文档；JSONL 用于保留工具调用、来源与回答之间的关系。

## Markdown 报告引文

普通行内引用支持中文弯双引号或英文直双引号包住的逐字原文，后接同一句中的 Markdown 来源链接：

```markdown
IANA explains that “example.com and example.org are maintained for documentation purposes.” ([IANA](https://www.iana.org/help/example-domains))
```

同一行可以有多条引用。链接可紧跟引号，也可位于其后的同一句短距离内；中间不得出现句号、分号或另一处开引号。代码围栏内的文字不参与检查。没有逐字引文的普通链接不会被解释成证据，工具也不会判断主张是否由引文支持。

列表项还支持 `[链接标题](URL) - “逐字引文”` 及 `“逐字引文” - [来源](URL)` 两种写法。引号字形差异不导致误报；显式 `(…)`、`(...)` 或省略号可跳过来源中的中间文字，但两侧片段必须足够长且顺序一致。HTTP `charset` 会用于 HTML 解码。图片、登录墙和大量依赖 JavaScript 的页面可能只返回外壳文本，这类不匹配需要人工复核。

也可使用显式引用块：

在普通 Markdown 报告中，将一段原文和其来源写成相邻的引用块：

```markdown
## 示例域名

> 原文：“example.com and example.org are maintained for documentation purposes.”
> 来源：[IANA](https://www.iana.org/help/example-domains)
```

运行 `moon run cmd/main check-report report.md`。支持 `原文：` / `引文：` 与 `来源：`，也支持英文 `Quote:` / `Source:`；来源可写 Markdown 链接或纯 HTTP/HTTPS URL。引文中的行内代码反引号是排版符号，匹配网页可见文本前会去掉。代码围栏里的示例不会被检查。每段原文必须跟随来源；未配对、无效来源和没有引用块的报告会报错。输出包含报告原文所在行号，支持 `--json`，来源不可用或引文不匹配时返回退出码 2。

这是显式引用块的约定，不会从任意 Markdown 链接推断其所支持的主张；前一标题仅作上下文显示，不参与语义判断。

## 轻量引用笔记

每条记录各写一行 `claim:`、`quote:` 和 `url:`，字段可以换序；空行或 `---` 分隔多条记录。字段值为单行文本，冒号后面的内容按原样保留（两侧空白会去掉）。以 `#` 开头的行为注释。

```text
claim: The report lists the example domains.
quote: example.com and example.org are maintained for documentation purposes.
url: https://www.iana.org/help/example-domains
```

运行 `moon run cmd/main verify-notes notes.md`。命令回源读取每个 URL，并检查 `quote` 是否出现在当前页面的可见文本中。HTML 实体与标签由 HTML5 解析器处理，匹配时会折叠空白，但保留大小写与标点。`claim` 用于让人理解记录，不进行语义蕴含判断。

## Agent JSONL

每行是一个事件，按观察顺序排列；一次运行中的 `run_id` 一致，`call_id` 和来源 `id` 唯一。未知字段允许保留。

```jsonl
{"type":"tool_call","run_id":"r1","call_id":"c1","tool":"search"}
{"type":"tool_result","run_id":"r1","call_id":"c1","ok":true,"sources":[{"id":"s1","uri":"https://www.iana.org/help/example-domains","content":"example.com and example.org are maintained for documentation purposes."}]}
{"type":"answer","run_id":"r1","claims":[{"text":"The report lists the example domains.","citations":[{"source_id":"s1","quote":"example.com and example.org are maintained for documentation purposes."}]}]}
```

- `tool_call`：需要 `call_id` 和 `tool`。
- `tool_result`：需要 `call_id`、布尔值 `ok`；成功来源包含 `id`、`uri` 和用于证据校验的 `content`。失败结果不能提供来源。
- `answer`：每次运行恰好一个；证据模式要求至少一个 claim，每个 claim 至少一条 citation。引用需要 `source_id` 和非空 `quote`。

`moon run cmd/main trace.jsonl --evidence` 核对引用片段是否是捕获内容的逐字子串。`moon run cmd/main verify-urls trace.jsonl` 先运行证据校验，再按来源 URL 回源核对引用；它不依赖轨迹里的捕获内容来判定网页当前是否包含该引用。`verify-files` 重新读取 `file:` 来源指定的当前文件。`compare old.jsonl new.jsonl` 按稳定 URI 比较捕获内容，报告 `added`、`removed` 和 `changed`。

诊断使用稳定错误码，报告不回显来源正文或引用片段。校验成功退出码为 0；证据不匹配、来源不可用或来源变化为 2；命令参数或笔记格式错误为 1。可传 `--json` 获取机器可读输出。

## HTTP 回源行为

- 仅接受 `http://`、`https://` 和各自默认端口；不支持带用户凭据、IPv6 字面地址或非 ASCII 主机名的 URL。
- 逐跳检查重定向目标，最多跟随五次；拒绝 HTTPS 降级到 HTTP。
- 拒绝本地、私网和保留 IPv4/IPv6 地址；检查 DNS 返回的第一个 IPv4 和第一个 IPv6 地址。对托管执行环境，HTTPS 域名解析到 `198.18.0.0/15` 时允许该网络路由；该段的 IP 字面地址和 HTTP 请求不允许。TLS 证书仍需匹配原始主机名。
- 每个来源请求最多 20 秒、2 MiB。HTML 会提取可见文本；支持 `text/*`、XHTML、JSON 和未声明类型的 UTF-8 页面。超出范围的内容类型、非 UTF-8 页面或 HTTP 错误会返回诊断码。

异步 HTTP 库在连接时重新解析域名，当前校验器没有固定完整 DNS 答案。不要将其当作面向不可信 URL 的服务端网络隔离层。远端页面可能变化；引用出现不证明 claim 的语义真实性，也不构成网页历史快照。