[xiaoyumuxi]

背景

一个 API 编号下面常有多个宿主方法，例如 API-24 有 terminal/create、show、close、reopen、dispose、onExit 六个。这些方法可以分几个 PR 陆续加入；函数协议 3 里向后兼容地新增方法也不升协议版本。原来的文档有两个问题：

• API 总表把同一个 API 的方法挤在一个单元格里，没有用途说明。
• 更新记录只能按协议版本查首次出现，查不到某个方法是哪天、哪个 PR 加的。

这个 PR 改成按方法登记，格式参照 1lck/Lithe-IDEA#1653 描述里“原计划编号 | 新增公共方法 | 用途”那张表。API 编号仍是 API 实施计划的规划编号，和协议版本、能力版本分开记录。

改动

reference/api-catalog.md（中英两半同步改）

• 宿主方法表：每个方法一行，列为 API | 方法 | 用途 | 权限 | 协议，按 API 编号排列；新增“用途”一列，共 35 个方法。
• 通知表：同样每个通知一行，列为 API | 通知 | 用途 | 授予条件，补上用途。例如 commands/didRun 只是事件，不表示命令的业务操作成功；didChangeContexts 带 revision，后端再调 listContexts。
• 表前说明：改成三条，分别说明“API”“协议”“权限”三列。其中写明 API 是规划编号，同一个 API 的方法可以分几个 PR 加入，并链接到更新记录的方法索引（只有中文）。
• 快捷键导入的两个方法：表下补一句，说明 keymapImport/listInputs、readChunk 属于 litheKeymapImport 协议，不在 API-01–44 内，并链接到快捷键导入页。

reference/protocol-changelog.md（只有中文）

• 新增“宿主方法（按 API 编号）”索引：放在“按协议查首次出现”下面，一个方法一行，写明 API、方法、协议、首次加入的日期和 PR。35 个请求、3 个通知和 2 个快捷键导入方法都列进去，共 40 行。出处是对主仓库 preview 的 first-parent 历史逐个方法用 git log -S 查出的首次加入 commit：
  • #1470（2026-10-24）：credentials/*，协议 2；
  • #1595（2026-10-30）：协议 3 的大部分方法和全部 3 个通知；
  • #1617（2026-10-31）：editor/registerActions；
  • #1653（2026-11-02）：6 个终端方法；
  • #1695（2026-11-03）：2 个快捷键导入方法。
• 时间线加“API 编号”列：18 张表、42 行都补了，原来的“协议 / API”列改名为“协议 / 能力”。开头的阅读说明改成两条，分别解释这两列。
  • 编号由 docs(plugins): macOS 公共 API 与 SDK 文档实施计划 1lck/Lithe-IDEA#1548（2026-10-28）引入。更早的 PR 没有编号，按计划“API-01–44 完成度总表”里各编号对应的既有能力补填，例如 debugAdapters 是 API-30，vcsProviders 是 API-31，页面上也写明了这一点。
  • 没改到具体 API 的 PR（清单、市场、包信任、SDK、契约文档整理）写 —。
• 修正 #1653 那一行：原来只写了 create、show、close、reopen，漏了 dispose、onExit。现在六个都列上，并按 PR 描述写明各自的作用。
• #1595 那一行：加了一个指向方法索引的链接。#1617 那一行：在 editor/registerActions 后面标出 API-27。
• 维护步骤：从 6 步扩成 8 步，新增两步：
  • 第 3 步：“API 编号”取自 PR 描述里的“原计划编号”；PR 没写时按实施计划判断，不自编新号，不属于任何编号的写 —。
  • 第 4 步：新增宿主方法或通知时，在方法索引里逐个登记，同时在 API 总表中英两张方法表里各加一行，写明用途、权限和协议；同一个 API 的方法分几个 PR 加入时，各自登记自己的 PR。

说明

• 版本表不加 API 列：能力版本表和进程协议版本表没有加 API 列。能力和 API 的对应关系已经在 API 总表“现在能用的 API”表里，再抄一份容易不一致；按 PR 的对应改由时间线的“API 编号”列给出。
• editor/reveal 的说法出自宿主实现：“只处理已打开的文件，没打开时返回 plugin.host.notFound”这一点来自 macOS 宿主（PluginHostEditorService.swift 抛出 documentNotOpen，映射到 plugin.host.notFound/-32016）。契约 README 只写了它和 editor/open 参数相同，以后应补进契约。
• 范围：这个 PR 不同步新的契约版本，contract/v1/ 和“记录到”都没变，也没有登记新的 PR，所以没有 @ 修改人。
• 配套规则：主仓库 AGENTS.md 的登记规则会另开 PR 补上“新增方法逐个登记 API 编号”。

验证

• node scripts/contract.mjs verify：91 个文件和锁定的 644afdaac 一致。
• node --test scripts/contract.test.mjs：13 个测试全部通过。
• 检查了 reference/ 下 19 个文件的 1089 个相对链接和锚点，0 个断链。API 总表指向新锚点 #宿主方法按-api-编号 的链接也检查过。
• 逐行确认时间线每行都是 5 列；42 个 PR 都有 API 编号，没有多也没有漏。
• 方法用途和契约 README 的宿主方法表核对过；方法清单和 Core 白名单 plugin_function.rs 核对过。