# 通用约定

**本文件的规则对本插件的所有 skill 一律有效**（研究、写入，以及以后加的任何流程）。
单个 skill 只写自己流程特有的部分，共同的规矩都在这里——改一处，全部生效。

## 坐标

WikiPali 的最小可引用单位是 `book:paragraph`，例如 `216:35`。句子在段内再细分
`word_start`–`word_end`。完整定位一条内容需要三样：

```
book : paragraph  +  word_start-word_end  +  channel_uid
```

`channel` 是**译本/版本**的载体：巴利原文、缅文逐词解析、各家汉译，都是同一坐标下
的不同 channel。所以"取原文"和"取某语言译文"是同一个操作换 channel。

读端与写端共用这一套坐标——检索到的位置，就是能写入的位置。

## 引用格式

> ⚠ **临时格式**，正式规范待定（见 `docs/wikipali-research-agent-design.md` §3.4）。
> 规范给出后只改本节，所有 skill 自动跟上。

```
Cūḷavaggapāḷi, Pārivāsikakkhandhaka (VN 216:35)          ← 本文
Samantapāsādikā, Pārivāsikavattakathā (SP-aṭṭ 141:63)     ← 义注，已标层次
Nissaya（缅文，channel: nissaya）(216:35)                  ← 译文，标明语言与来源
AI-汉译-Nissaya（**AI 生成**，deepseek-v3）(216:35)         ← 机器译文必须标注
```

书名与章节路径直接取检索结果的 `paliTitle` 与 `path` 字段，**不要自己拼**。

## 文献层次必须标明

`mūla`（本文）、`aṭṭhakathā`（义注）、`ṭīkā`（复注）是不同层次的权威。层次信息来自
`dist` 输出里的 tags。

**把义注的解释当成经律本身的说法是学术错误，不是措辞问题。** 引用时必须让读者看出
这句话出自哪一层。

## 译文来源的判定

引用译文前必须判断人译还是机译。两个信号，**任一命中就按机器译文标注**：

1. **作者是 AI 模型**——`get` 返回里的作者若是模型而非人类用户，该译文确定是机器
   生成的，标注时连模型名一起写；
2. **channel 名字含 "AI" 等字样**——库里存在人工用自己账号上传的机器译文（如
   `Nissaya的AI翻译`、`Norbu AI Translations`），此时信号 1 不成立。

两个都不命中时**不要主动断言"这是人译"**——只如实标出 channel 名与作者。

## 空结果要诚实

区分三件事，对用户的下一步完全不同：

| 现象 | 含义 |
|---|---|
| 检索 0 条 | 多半是词形没展开（见下），不是"没有材料" |
| 某坐标取不到某 channel 的内容 | 该译本在此处没有文本。**如实说，不要拿相邻段落或别的译本凑** |
| 请求报错 | 工具或服务的问题，不是语料的问题 |

## 检索前必须展开词形

语料索引的是**变格形**（`parivāsaṃ` / `parivāso` / …），不是词典形（`parivāsa`）。
拿词典形直接检索会**返回 0 条且不报错**——看起来像"搜过了，没有"。

所以任何检索都必须先 `wikipali forms <词>`（或给 `search --lemma`）。

## 站点

线上四个地址（`www`/`next` × `.org`/`.cc`）共享同一个数据库和密钥，凭据通用。
`www` 是稳定版、`next` 是最新版**代码**，不是不同的数据环境。较新的端点在稳定版上
返回 404，意思是"该站点代码版本还没到"，不是"资源不存在"。

`wikipali endpoint` 查看与切换，`--api` 只影响单次调用。

## 凭据

`~/.wikipali/credentials.json`（0600）。**任何 skill 都不得打印 token 全文，也不得
`cat` 这个文件。** 密码只由 `wikipali-login` 接触，且必须由用户本人在真正的终端里跑。