@comchatx/cx-topics 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.zh-CN.md +61 -0
  2. package/package.json +3 -2
@@ -0,0 +1,61 @@
1
+ 为你的对话生成标题,并读取你引用的消息。cx-topics 是一个 pi 扩展。它自己为卖家的工作写标题,所用的模型就是卖家对话时选的模型,并依据 Jev 对每条卖家消息的判断;它还给 cx 一个工具 `quoted`,用来读取卖家引用的消息。
2
+
3
+ ## 标题
4
+
5
+ 这个包负责起标题,也负责改标题。它为对话中卖家的第一条消息、以及 Jev 判断为新工作的每条消息写标题;当 Jev 判断某项工作的标题已不能概括这项工作时,改写这个标题。平时随消息逐条进行;安装之后,则从第一条消息起把整段对话过一遍。标题属于卖家,用卖家自己的措辞和语言:写标题的模型会被告知,标题是给卖家看的,卖家靠它找回这项工作。标题只有一行,中文与拉丁字母、数字之间留空格,最多 8 个词、80 个字符(`title()`);裁剪后什么都不剩的回答,不写入任何标题。cx 没有起标题或改标题的工具,也不会被告知任何与标题有关的事。
6
+
7
+ 标题是卖家消息上的一个 pi 标签(label):新工作的标题打在它的第一条消息上,改写后的标题作为同一条消息上更晚的一个标签。没有文字的消息(只有图片或引用)不单独起标题,归入它前面的那项工作。每条消息要么接着当前这项工作,要么开始一项新工作;不会回到更早的工作。
8
+
9
+ **何时调用。** 每条归入某个标题的卖家消息,调用一次 Jev 分类。同一时间只有一轮处理:它按顺序走过当前分支(`getBranch`)上的卖家消息,从进度记录的最后一条开始,逐条判断尚未判断的消息(`src/extensions/pass.ts`)。进度是 `cx-topics` 名下的自定义记录,每判断完一条消息写一条 `{through: <entry id>}`,安装后的清除完成后写一条 `{install: <token>}`;pi 把它们存在会话文件里,一条也不放进模型的上下文。
10
+
11
+ **从哪里继续。** 如果进度记录指向的消息已不在当前分支上,就从分支上最新的一条卖家消息继续,不发起任何调用。首次加载时,如果没有进度记录,也没有未处理过的安装令牌,就在分支上最新的一条卖家消息处写一条起始记录,不发起任何调用。
12
+
13
+ **何时从头开始。** 只有安装会从第一条消息开始:清除这个包写过的所有标题,再为整段对话重新写标题。pi 不会告诉一个包它是怎样被加载的,所以每次安装时,宿主都会在项目下的 `.pi/cx-installs.json`(`INSTALLS_FILE`)里记下一个新令牌,键是这个包的来源、去掉其中的 npm 版本号(`installKey`);如果自己这个键对应的令牌不在任何一条进度记录里,这个包就把这次加载当作一次安装。它的键取自 pi 为 `quoted` 工具列出的来源,并且这个工具的文件必须是这个包自己的,所以别的包里的 `quoted` 不会提供键。没有键、没有文件、没有令牌,或者文件读不出来,都照常继续。
14
+
15
+ **何时写标题。**
16
+ - 对话中第一条有文字的卖家消息,以及 Jev 判断为新工作的消息:写标题的模型只根据这条卖家消息写标题。
17
+ - 接着当前工作的消息:同一次 Jev 调用还会回答当前标题是否仍能概括这项工作。结果在 0.2 或以下(`ROUTING_LIMITS.staleTitle`)时,写标题的模型根据原标题和这项工作中的卖家消息改写标题。
18
+ - 只有发起请求时所依据的标签仍然存在,并且新标题与它不同,才会写入标题。
19
+
20
+ **Jev 看到什么。** 从 pi 的分支中取出的当前工作:它的标题、其中卖家自己的话(去掉 `<quote>` 标记),以及被判断的这条消息;cx 说的话、步骤、思考过程和图片一概不给。卖家消息超过 31 条时,只给最新的 31 条(`ROUTING_LIMITS.sellerMessages`)。超过 512 个码位的消息、以及超过 2,048 个码位的最新一条消息,只保留开头和结尾,中间换成 `\n[… N characters omitted …]\n`。这项工作有多长,决定了 Jev 要有多大把握,才算一条消息是接着它的:卖家消息不超过两条时,五五开就算接着;从八条起,需要 0.8 的把握;两者之间,门槛均匀升高(`ROUTING_LIMITS`)。发给 Jev 的请求最大为 109,260 字节。
21
+
22
+ **模型。** Jev 取自 pi 的模型列表,即 `typesafe` `jev-latest`(`JEV`)。写标题的模型就是卖家对话时所用的模型,每次写标题时从 pi 读取(`ctx.model`),所以卖家换了模型,下一个标题就由新模型来写。标题属于卖家,由卖家自己选的模型来写(Jack,2026-10-28),这个包不指定自己的模型,也不提供这方面的设置。对于实体模型,写标题的调用(`modelRegistry.complete`)最多要 128 个输出 token,不思考、不用工具、不保留缓存,限时 20,000 毫秒。如果卖家选的是虚拟模型,由 pi 负责路由(`modelRegistry.streamSimple`,选项相同),并采用卖家的路由器返回的思考强度,pi 会在 128 之外再加上相应的思考预算。这是卖家自己的配置,和对话一样计费,因为 pi 1.4.0 没有给扩展提供公开的方法,先路由请求、再加以限制。这个包不保存任何地址或密钥。pi 没有配置 Jev 时,不发起任何调用;对话没有模型,或者 pi 没有这个模型的密钥或登录时,不写标题,这一轮处理停在这条消息上,和调用被拒绝时一样。
23
+
24
+ **失败时什么都不写。** 只有 pi 以 `stop` 结束、并且回答了每个问题的结果,才算判断结论;只有 pi 以 `stop` 结束的回答,才算标题。已得到回答的调用,或者请求本身被拒绝(`400`、`413`、`422`,或者不带网关错误码的 `403`),会继续处理下一条消息;以其他方式失败的调用,会让这一轮处理停在这条消息上,等下一条卖家消息或下一次加载时再调用,绝不循环。任何调用都不重试。
25
+
26
+ **停止。** 「停止」只结束 cx 的回答,卖家的消息仍会照常归档:正在进行的 Jev 调用和写标题调用会各按自己的时限完成,标题照常写入。
27
+
28
+ ## `quoted`
29
+
30
+ `quoted` 接收 `entry`,即 pi 的一个记录 id。它读取 pi 的整个会话(`getEntries`,无论是否已整理成摘要),返回被引用的消息,以及它前后各最多 2 条卖家或 cx 的消息:谁说的、什么时候说的、说了什么,回答中的每个步骤各占一行。时间精确到分钟,按最新一个注明时区的引用标记的时区显示,没有就用 UTC。被引用的消息超过 8,000 个字符、前后的消息超过 1,000 个字符时截断,每处截断都会注明省略了什么。如果会话里没有这个 id,就回答这条消息来自更早的对话。
31
+
32
+ 加载了这个包的会话,每次请求都会在系统提示词的工具部分告诉模型,`quoted` 按 `<quote>` 标签的 `entry` 属性读取被引用的消息;并在规则部分告诉模型,带引用的消息要在 `quoted` 读取之后再回答。共 255 个字符,约 64 个 token。
33
+
34
+ ## 引用标记
35
+
36
+ 卖家消息中的引用按以下格式发送:
37
+
38
+ ```
39
+ <quote entry="<pi entry id>" at="<epoch>:<seq>" zone="<IANA zone>">the quoted or selected words</quote>
40
+ ```
41
+
42
+ 每条被引用的消息或每段选中的文字对应一个标记,放在卖家自己的话前面。被引用的文字里不会出现字面的 `</quote>`。`entry` 是 `quoted` 读取的内容;`zone` 是引用卡片显示时间所用的时区。没有这个包时,模型直接读取标记里的引用文字。
43
+
44
+ ## 实现方式
45
+
46
+ - `src/core/` 存放纯逻辑部分,包括 Jev 问题的协议、路由门槛和标题的裁剪,只引用自身。
47
+ - `src/extensions/topics.ts` 是唯一的扩展;`judge.ts` 负责调用和写入,`pass.ts` 负责遍历分支。`npm run build` 把 `topics.ts` 打包成 `dist/extensions/topics.js`,pi 自己的包留给 pi 提供;这个包只发布这一个文件。构建出的模块还导出 `INSTALLS_FILE`、`installKey` 和 `JEV`,供宿主据此约束这个包。
48
+ - `package.json` 不声明 `type`。这样,pi 的加载器会按 pi 列出 `quoted` 工具来源时所用的路径读取打包文件;如果声明为模块,它会被原生加载,并以真实路径识别自己,而在符号链接后面,真实路径与 pi 列出的路径不同,这个包就会找不到自己的键,从而漏掉一次安装。
49
+
50
+ ## 测试
51
+
52
+ - `test/core/`:协议;对照固定的比较表(`test/support/routing-comparison.json`)检查路由门槛;标题的裁剪;以及核心部分不引用任何其他代码、打包文件只包含实际使用的文件。
53
+ - `test/extensions/`:在 pi 自己的会话结构上检查标题和引用读取;Jev 的判断与标题;以及处理过程,包括安装后的清除和从第一条开始的判断、继续处理、离开分支、同一时间只有一轮处理、重新加载后再次发起被中断的调用,以及从 pi 的工具列表中读取键。
54
+ - `test/support/replay.test.ts` 和 `replay-main.test.ts`:不用密钥,通过 pi 自己的注册表在替身上重放校准集,检查写标题的请求指定的是对话所用的模型;在两条消息之间换模型时,第二条由新模型写标题;虚拟模型被路由到对应的实体模型;实体模型请求和经路由的请求各自带的输出 token 与思考设置;以及 pi 没有密钥的模型不会被调用。
55
+ - `test/package.test.ts`:锁定版本的 pi 能加载构建出的扩展及其工具和处理函数;构建出的模块导出宿主用来约束它的内容;这个包只发布构建出的扩展。
56
+
57
+ **校准集。** `test/support/calibration-cases.ts`,由 `test/support/replay-main.ts` 手动重放,并像 `replay-main.test.ts` 那样用 esbuild 打包(`--live --keys <env file>`):每条卖家消息都由这个包自己的判断程序在 pi 的注册表上判断,调用 TypeSafe 和 OpenRouter,所用的开发密钥按名称从 env 文件读取,并与期望的结果对照,即新工作、标题不变的延续,或要求改写标题。没有密钥时,在替身上运行。这套用例是在对话使用 `balance` `minimax/minimax-m3`(ComChatX 默认的模型,`CALIBRATED`)时测得的;Jev 的判断与对话所用的模型无关,而标题的措辞现在会随卖家对话所用的模型而变。
58
+
59
+ ## 发布
60
+
61
+ 每个版本在打上 `v<version>` 标签时,由 `.github/workflows/release.yml` 发布;本仓库是这个包在 npm 上的可信发布者。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@comchatx/cx-topics",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "Names your conversations and retrieves the messages you quote.",
5
5
  "license": "MIT",
6
6
  "author": "ComChatX",
@@ -19,7 +19,8 @@
19
19
  ]
20
20
  },
21
21
  "files": [
22
- "dist"
22
+ "dist",
23
+ "README.zh-CN.md"
23
24
  ],
24
25
  "scripts": {
25
26
  "build": "node scripts/build.mjs",