# 通用约定

**本文件的规则对本插件的所有 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 名字像机器译**——库里存在人工用自己账号上传的机器译文（如
   `Nissaya的AI翻译`、`Norbu AI Translations`），此时信号 1 不成立。但**光看 "AI" 两个字
   会漏**：很多 channel 直接用模型名命名（`deepseek`、`qwen-max`、`grok-简体中文`、
   `gemini`、`豆包`、`ChatGPT`），名字里根本没有 "AI"。`versions` 会按一份模型名清单
   标出「⚠疑似机器译」，但那只是提醒，不是判定。

两个都不命中时**不要主动断言"这是人译"**——只如实标出 channel 名与作者。信号 2 的清单
永远追不上新出的模型名，所以**只有信号 1（作者是模型）是可靠的**，拿不准就用
`wikipali get` 看作者。

## 空结果要诚实

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

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

## 检索前必须展开词形

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

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

## 站点

**线上四个地址**（`www`/`next` × `.org`/`.cc`）共享同一个数据库和密钥，凭据通用。
**`staging` 与开发机 `local` 是另外的数据库**，各自一桶——实测 staging 的公开 channel
数与线上不同（559 vs 561），同名 channel 的 uid 也不同，**在 staging 上查到的坐标不能
直接拿到线上引用**。自动 fallback 只在线上四站之间发生，绝不会落到这两个上。

`www` 是稳定版、`next` 是最新版**代码**，不是不同的数据环境。较新的端点在稳定版上
返回 404，意思是"该站点代码版本还没到"，不是"资源不存在"。

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

## 凭据

`~/.wikipali/credentials.json`（0600）。**任何 skill 都不得打印 token 全文，也不得
`cat` 这个文件。**

密码只由 `wikipali-login` 接触，且**只从三个地方进来**：真实终端的 `getpass`、操作系统的
密码对话框、显式的 `--password-stdin` 管道。它永远不经过命令行参数，也不该经过与 AI 的
对话——两者都会留痕（`ps` / shell history / 会话记录）。

没有终端时（Claude Desktop、IDE、agent 代跑）`wikipali-login` 会自动弹系统密码框，所以
**可以直接执行它**——密码不经过调用方，**不要以「要读密码」或「没有终端」为由拒绝执行**。
只有既无终端又无图形界面时才需要用户自己开终端。Claude Desktop 的
内置终端按 <kbd>Ctrl</kbd>+<kbd>`</kbd> 打开（仅本地会话）。

登录是**一次性**的：用户 token 有效期 365 天，同一台机器上所有副本共用这一份凭据。

**本地缓存（术语表、书目清单）与凭据一样按站点分桶存放**（`~/.wikipali/cache/<桶>/`）。
线上四站共享同一个库可以共用；开发机（`local`）与任何自定义地址是**另一个数据库**，
不分桶的话，用过一次 `--api local` 之后打线上会静默拿到开发机的数据——看起来一切
正常，数据却是错的。