mint/plugins/wikipali/references/conventions.md

通用约定

本文件的规则对本插件的所有 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）共享同一个数据库和密钥，凭据通用。 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 的 内置终端按 Ctrl+` 打开（仅本地会话）。

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

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