diff --git a/CHANGELOG.md b/CHANGELOG.md index 96553bf..e7869f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ Pi shows the entries newer than your installed version after `pi update`. +## [0.4.2] - 2026-11-13 + +- Documentation in Simplified Chinese: README, contribution guide and security policy. No change to the extension. + ## [0.4.1] - 2026-11-13 - The README has a quick start and a troubleshooting section. No change to the extension. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7579606..d442b9f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing +English | [简体中文](CONTRIBUTING.zh-CN.md) + Small, focused contributions are welcome. Discuss large behavior changes in an issue before implementing them. ## Local checks @@ -31,6 +33,7 @@ Do not load another copy of this extension in the same session. - Prefer existing Pi APIs and small changes over new dependencies or abstractions. - Add a regression test for a bug and check that it fails before the fix. - Do not weaken tests or input validation to pass checks. +- Update the English and the Simplified Chinese version of a document in the same pull request. - Give the pull request a title that describes the user-visible change. Release notes are generated from these titles. - Never include credentials, account data, or private conversation content in commits, screenshots, or logs. @@ -51,7 +54,7 @@ Do not bump the package version in pull requests. The release tag sets the publi ### Release procedure -1. In a pull request, add a `## [X.Y.Z] - YYYY-MM-DD` entry at the top of `CHANGELOG.md`, in words a user understands. Choose `patch` for fixes, `minor` for compatible features, or `major` for breaking changes. Pi shows this entry to users after `pi update`. +1. In a pull request, add a `## [X.Y.Z] - YYYY-MM-DD` entry at the top of `CHANGELOG.md`, in words a user understands. Choose `patch` for fixes, `minor` for compatible features, or `major` for breaking changes. Pi shows this entry to users after `pi update`. Write `CHANGELOG.md` in English only, because Pi reads only this file. 2. Wait for CI to succeed on the `main` commit you want to publish. 3. On GitHub, open **Releases > Draft a new release**. 4. Create the tag `vX.Y.Z` on `main`. diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md new file mode 100644 index 0000000..1dfa9ed --- /dev/null +++ b/CONTRIBUTING.zh-CN.md @@ -0,0 +1,72 @@ +# 参与贡献 + +[English](CONTRIBUTING.md) | 简体中文 + +欢迎小而专注的贡献。较大的行为变更,请先在 issue 中讨论,再动手实现。 + +## 本地检查 + +使用 Node.js 22.19 或更高版本。CI 会检查 Node 22 和 24。 + +```bash +npm ci +npm run check +``` + +`npm run check` 会检查 TypeScript、圈复杂度(每个函数最多 10,`npm run lint`)以及离线测试。函数过于复杂时,请拆分它;行内 `eslint-disable` 注释不起作用。测试使用 Pi 的模拟(faux)提供商,而不是真实模型。 + +CI 还会在 Node 24 上安装最早支持的 Pi `1.0.3` 和最新发布的 Pi 包,并重新运行这些检查。即使仓库没有变更,CI 也会每周运行一次。 +保持锁文件基线可复现;不要用不受约束的依赖树替换它。由宿主提供的 peer 依赖保持为 `*`。 + +可选:在 Pi 中手动测试: + +```bash +pi -e . +``` + +不要在同一个会话中加载本扩展的另一个副本。 + +## 变更要求 + +- 让扩展不依赖个人路径、提示词和其他扩展。 +- 保留无关的用户指令和会话内容。 +- 优先使用现有的 Pi API 和小改动,而不是新的依赖或抽象。 +- 修复 bug 时添加回归测试,并确认它在修复前会失败。 +- 不要为了通过检查而削弱测试或输入校验。 +- 在同一个 pull request 中同时更新文档的英文版和简体中文版。 +- pull request 的标题要描述用户可见的变化。发布说明由这些标题生成。 +- 不要在提交、截图或日志中包含凭据、账号数据或私人对话内容。 + +## Pull request + +创建分支或 fork,然后向 `main` 提交 pull request。 + +说明问题、最小修复方案以及你运行过的检查。无关的变更请放在单独的 pull request 中。 + +`main` 要求通过 pull request 合并,并且 `Check (Node 22)` 和 `Check (Node 24)` 检查要基于当前目标分支通过。 +不需要他人审批,因此独立维护者可以在 CI 通过后合并。禁止强制推送和删除分支。 + +## 发布 + +只有仓库所有者可以发布。GitHub release 会触发 **Publish release**,并且所有者必须批准 `npm` 环境的部署。 + +不要在 pull request 中修改包版本。发布标签决定发布的版本。 + +### 发布流程 + +1. 在一个 pull request 中,在 `CHANGELOG.md` 顶部添加一条 `## [X.Y.Z] - YYYY-MM-DD` 记录,用用户能理解的话来写。修复选择 `patch`,兼容的新功能选择 `minor`,不兼容的变更选择 `major`。用户运行 `pi update` 后,Pi 会向他们显示这条记录。`CHANGELOG.md` 只用英文书写,因为 Pi 只读取这个文件。 +2. 等待要发布的 `main` 提交的 CI 通过。 +3. 在 GitHub 上打开 **Releases > Draft a new release**。 +4. 在 `main` 上创建标签 `vX.Y.Z`。 +5. 选择 **Generate release notes**,然后选择 **Publish release**。 +6. 在 Actions 运行中批准 `npm` 环境的部署。 + +以下发布会被工作流拒绝:不是由所有者创建的发布、预发布、不符合 `vX.Y.Z` 的标签、不在 `main` 上的提交、CI 未通过的提交,或者 `CHANGELOG.md` 中没有对应记录的版本。工作流会运行 `npm run check`,根据标签设置包版本,并带 npm provenance 发布。新的 npm 发布会更新 `latest` dist-tag。 + +Release 和 `v*` 标签不可更改。如果发布因外部原因失败,请在原来的运行中使用 **Re-run failed jobs**。如果代码需要修复,请发布一个新版本。 + +工作流使用 npm 可信发布(trusted publishing),因此仓库中不保存 npm token。为本仓库、`release.yml` 和 GitHub 环境 `npm` 配置 npm 可信发布者。将该环境限制为 `v*` 标签,并将所有者设为必需审批人,允许自我审批。 + +## 安全 + +请通过[私密报告流程](SECURITY.zh-CN.md)报告安全漏洞。不要在公开 issue 中写入漏洞利用细节或凭据。 diff --git a/README.md b/README.md index 25729d3..7fdfe59 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # pi-context-kit: long Pi sessions that stay sharp +English | [简体中文](https://github.com/HugoLopes45/pi-context-kit/blob/main/README.zh-CN.md) + [![CI](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit) [![Pi package](https://img.shields.io/badge/pi.dev-package-blue)](https://pi.dev/packages/pi-context-kit) diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..dfd4d45 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,387 @@ +# pi-context-kit:让 Pi 长会话始终保持清晰 + +[English](README.md) | 简体中文 + +[![CI](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit) +[![Pi package](https://img.shields.io/badge/pi.dev-package-blue)](https://pi.dev/packages/pi-context-kit) +[![Node.js](https://img.shields.io/node/v/pi-context-kit)](https://nodejs.org) +[![License: MIT](https://img.shields.io/npm/l/pi-context-kit)](LICENSE) + +为 [Pi 编程智能体](https://github.com/earendil-works/pi)提供压缩(compaction)和上下文管理。pi-context-kit 会把过时的文件读取和旧的工具输出从上下文窗口中清理出去,在 Pi 需要之前于后台写好交接摘要,并让当前分支的原始文本只需一次 `recall` 搜索即可找回。 + +```sh +pi install npm:pi-context-kit +``` + +重启 Pi。默认设置无需任何配置即可使用。 + +## 为什么选择 pi-context-kit + +- **更干净的上下文窗口。** 超过阈值后,文件的旧副本和旧的工具输出会变成一行提示。最新的工具输出保持不变。 +- **提前写好的摘要。** 会话模型在后台写交接笔记,同时继续工作。到达阈值时,如果已准备好的笔记仍能放进上下文,压缩就不必等待新的摘要。 +- **不删除任何内容。** 会话保留原始文本。模型可以用 `recall` 工具搜索并重新读取它。 +- **尽量免费。** 替换旧的读取、修剪(prune)和精简(shake)都不调用模型。 +- **对缓存友好。** 上下文只在超过阈值后才被修改,并且一次完成。提供商的提示词缓存在每个维护步骤中只失效一次,而不是每个轮次都失效。 +- **零配置。** 安装、重启、开始工作。默认情况下,维护从上下文窗口的 75% 开始,对大多数模型来说,这早于 Pi 自身的限制。 +- **状态可见。** 底部状态栏显示上下文的占用程度以及清理何时开始。一条提示会告诉你释放了多少空间。输入 `/context-kit` 即可在面板中修改主要设置,无需编辑文件。 + +## 模型看到的内容 + +超过阈值后,大段的旧内容会变成一行提示。完整文本仍保留在会话中。示例(大小和 ID 仅为示意;最后一条提示只在精简运行时出现,参见 [`strategy`](#主要设置)): + +```diff +- ++ [Superseded by a newer read of this file] + +- ++ [Output pruned: about 12000 tokens. Call recall with entryId "a1b2c3d4" to read it.] + +- ++ [Elided block: about 2000 tokens. Call recall with entryId "e5f6a7b8" to read it.] +``` + +这些提示永远不会改变你的消息或模型的工具调用。模型的推理内容也会保留,Anthropic 有一个例外。压缩仍然会用摘要替换较早的消息。参见[维护会保留什么](#维护会保留什么)。 + +## 单独使用 Pi,与搭配 pi-context-kit 使用 Pi + +| 在长会话中 | 单独使用 Pi | 搭配 pi-context-kit | +| --- | --- | --- | +| 模型再次读取同一个文件 | 两个副本都留在上下文中。 | 超过阈值后,旧副本被替换。 | +| 旧的工具输出占满上下文 | 它们一直保留,直到 Pi 生成摘要。 | 它们被替换为一条简短提示。不需要模型请求。 | +| 上下文达到限制 | Pi 写一份摘要。 | 交接笔记可能已经准备好,因为它是在后台写的。 | +| 模型需要一个已移除的细节 | 上下文中只剩下摘要。 | 模型调用 `recall` 读取原始文本。 | + +原始的会话条目永远不会改变。只有 Pi 发送给模型的上下文会变小。 + +pi-context-kit 适用于 Pi 长会话:大量文件读取、很长的命令输出,或多次压缩。在短会话中,上下文很少达到阈值,因此在轮次结束时上下文不会改变。接近阈值时,后台交接笔记仍可能开始编写;`/compact` 会先尝试交接笔记,失败时回退到 Pi 的摘要。 + +## 为什么 Pi 长会话需要上下文管理 + +AI 模型一次只能读取有限的文本。这个限制就是**上下文窗口**。文本以 **token** 计量。Pi 大约把 4 个字符算作一个 token。 + +在长会话中,对话会逐渐占满上下文窗口。文件读取和命令输出通常是最大的部分。当窗口快满时,Pi 会进行**压缩**:用一份摘要替换旧的对话。摘要可能丢失细节,而且需要时间和费用。 + +
+本文档中使用的术语 + +| 术语 | 含义 | +| --- | --- | +| Token | 一小段文本。模型以 token 计算它的记忆容量。 | +| 上下文窗口 | 模型一次能读取的最大 token 数。 | +| 上下文 | Pi 当前发送给模型的全部文本:指令、消息和工具输出。 | +| 轮次 | 一个循环:模型回复、使用工具,然后停止。 | +| 工具输出 | 工具的结果,例如文件内容或命令输出。 | +| 阈值 | 维护开始时的 token 数。 | +| 压缩 | Pi 用一份摘要替换旧的对话。最新的消息保留。 | +| 交接笔记 | pi-context-kit 使用与你的会话相同的模型写的摘要。 | +| Pi 的摘要 | 没有可用的交接笔记时,Pi 写的摘要。 | + +
+ +## 快速开始 + +你需要 Pi 1.0.3 或更高版本,以及 Node.js 22.19 或更高版本。 + +1. 用上面的命令安装本包。 +2. 重启 Pi。 +3. 查看底部状态栏。扩展生效时,它显示 `Context 0% · cleanup at 75%`。 +4. 照常工作。输入 `/context-kit` 修改设置。 + +## 更新、试用或移除 + +```sh +pi update npm:pi-context-kit # 更新,然后重启 Pi +pi -e npm:pi-context-kit # 不安装,只试用一个会话 +pi remove npm:pi-context-kit # 移除,然后重启 Pi +``` + +更新后,Pi 会根据 [CHANGELOG.md](CHANGELOG.md)(英文)显示变更内容。 + +## 使用方法 + +你不需要做任何配置。pi-context-kit 在 Pi 的底部状态栏中显示它的状态: + +| 底部状态栏 | 含义 | +| --- | --- | +| `Context 62% · cleanup at 75%` | 上下文已占用 62%。清理从 75% 开始。 | +| `Context 70% · cleanup at 75% · writing summary` | 正在后台编写交接笔记。`summary ready` 表示笔记已准备好。 | +| `Context 25% · no automatic cleanup` | Pi 的自动压缩已关闭,因此只有在你输入 `/compact` 时才会清理。 | +| `Context cleanup off` | 你关闭了自动清理。 | + +pi-context-kit 缩短旧输出后,Pi 会显示一条提示,例如:`pi-context-kit freed 17% of the context (34k tokens). The agent can still look up what was removed.` + +要修改设置,输入 `/context-kit` 并按 Enter。用方向键选择一行,按 Enter 修改它的值。修改会立即保存,并从下一个轮次开始生效。按 Escape 关闭面板。 + +面板使用英文界面: + +| 面板行 | 选项 | 文件中的设置 | +| --- | --- | --- | +| Automatic cleanup(自动清理) | On、Off | `enabled` | +| Clean up when the context is(何时清理) | 50% full 到 90% full、At Pi's limit | `threshold` | +| Cleanup method(清理方式) | Summary notes (recommended)、Trim first、Pi's summary | `strategy`:`"balanced"`、`"frugal"`、`"pi-summary"` | + +当文件中有 `advanced.methodOrder` 时,面板不显示 Cleanup method 这一行,因为该设置会取代清理方式。 + +在非交互模式下,`/context-kit` 用一行文字显示当前设置。 + +## 会话中的工作方式 + +```text + 每个轮次结束 + | + v + 上下文接近阈值? --是--> 在后台开始编写交接笔记 + | + v + 上下文超过阈值? --否--> 继续工作 + | + 是 + v + 替换旧的文件读取,并修剪旧的工具输出 + | + v + 现在足够小了? --是--> 继续工作 + | + 否 + v + 依次尝试策略中的每个方法,例如:handoff、shake、soft +``` + +### 1. 旧的文件读取会被替换 + +有时模型会把同一个文件读取两次,这时第一个副本就过时了。 +pi-context-kit 会把旧副本替换为这段文本:`[Superseded by a newer read of this file]`。 + +只有当新的读取完全覆盖旧的读取时,才会这样做。如果新的读取被截断,旧副本会保留。 +只有当上下文超过阈值时才会这样做,并且与修剪、精简或压缩在同一次修改中完成。每次修改旧文本,都会让提供商在没有缓存的情况下重新读取之后的全部文本。对于 Anthropic,它还会从请求中移除模型之前的推理内容。在接近阈值时修改一次,比每个轮次都修改的成本更低。 + +### 2. 提前准备交接笔记 + +在上下文达到阈值之前,会话模型会在后台写交接笔记。你的工作不会中断。 +笔记提前阈值的八分之一开始编写,最多提前 32,000 个 token。阈值为 150,000 个 token 时,它大约在 131,250 个 token 时开始。 + +笔记使用与 Pi 的摘要相同的章节。它还会列出读取过和修改过的文件。 + +### 3. 修剪旧的工具输出 + +超过阈值后,旧的工具输出会被替换为一条简短提示,例如: +`[Output pruned: about 5000 tokens. Call recall with entryId "abc123" to read it.]` + +最新的 40,000 个 token 的工具输出始终保留。只有当上下文变得足够小时,pi-context-kit 才会保留这次修改。“足够小”指阈值的 80% 或更少。 + +### 4. 依次使用其他方法 + +如果修剪不够,pi-context-kit 会依次尝试[策略](#主要设置)中的方法: + +| 方法 | 作用 | 是否使用模型 | +| --- | --- | --- | +| `handoff` | 用交接笔记替换旧的对话。最新的消息保留。 | 是 | +| `shake` | 把较大的旧代码块、XML 块和图片替换为一条简短提示。你的消息永远不会被精简。 | 否 | +| `soft` | 用 Pi 的摘要替换旧的对话。最新的消息保留。到此为止。 | 是 | + +在这些步骤中,你的工作会继续进行。pi-context-kit 永远不会为了压缩而中断正在运行的任务。 + +### `recall` 工具 + +`recall` 工具读取原始会话文本,而不是发送给模型的缩短后的上下文。它可以: + +- 搜索当前分支上较早的对话文本,包括已移除和已被摘要的消息; +- 按 ID 读取一个条目的文本,较大的条目支持分页。 + +其他分支和会话不包括在内。系统提示词条目不会被搜索。 +图片保留在原始会话条目中,但 `recall` 只返回它们的 MIME 类型,不返回图片内容。 +模型必须调用 `recall` 才能找回缺失的细节。找回不会自动进行。 + +## 维护会保留什么 + +文件读取替换、修剪和精简不会改写原始会话条目。 +在模型的上下文中,这些步骤会保留: + +- 你的消息,包括你的指令和图片。 +- 模型的工具调用和推理内容。在被修改的消息之后,Anthropic 仍可能丢弃推理内容(参见[旧的文件读取会被替换](#1-旧的文件读取会被替换))。 +- 工具调用与工具结果的配对。每个工具调用都保留它的结果,但结果内容可能被缩短。 + +压缩则不同:它会用摘要替换较早的上下文,包括较早的用户消息。原始条目仍保留在会话历史中。 + +## 设置 + +本节面向需要编辑设置文件的用户。面板可以修改三个主要设置;文件中还包含高级设置。 + +### 设置文件 + +| 文件 | 适用范围 | +| --- | --- | +| `~/.pi/agent/context-kit.json` | 你的所有项目。`~` 是你的主目录。 | +| 项目文件夹中的 `.pi/context-kit.json` | 仅限该项目,并且只有在你于 Pi 中信任该项目时才生效。它的值会取代全局文件中的值。 | + +你不需要设置所有选项。未设置的选项使用默认值。pi-context-kit 在每个轮次都会重新读取这些文件,所以你不需要重启 Pi。如果项目文件设置了某个选项,面板会写入项目文件,否则写入全局文件。 + +添加 `$schema` 这一行,即可在 VS Code 等编辑器中获得补全和检查: + +```json +{ + "$schema": "https://unpkg.com/pi-context-kit/context-kit.schema.json", + "threshold": "70%", + "strategy": "frugal" +} +``` + +### 主要设置 + +| 设置 | 允许的值 | 默认值 | 作用 | +| --- | --- | --- | --- | +| `enabled` | `true`、`false` | `true` | `false` 停止所有维护和交接笔记。`recall` 工具仍然可用。 | +| `threshold` | token 数(整数)、百分比(例如 `"75%"`)或 `"pi"` | `"75%"` | 维护开始的位置。 | +| `strategy` | `"balanced"`、`"frugal"`、`"pi-summary"` | `"balanced"` | 修剪不够时,pi-context-kit 采取的做法。 | + +**`threshold`。** 百分比按每个模型的上下文窗口计算,因此对于 200,000 token 的窗口,`"75%"` 是 150,000 个 token;对于 1,000,000 token 的窗口,则是 750,000 个 token。允许使用小数,例如 `"72.5%"`。`150000` 这样的数字对所有模型都相同。token 数中不要使用空格、点或逗号。`"pi"` 表示等到 Pi 自身的限制。pi-context-kit 只能在 Pi 的限制之前开始,不能在之后:如果你设置的值更大,则使用 Pi 的限制。参见[同样生效的 Pi 设置](#同样生效的-pi-设置)。 + +**`strategy`。** + +| 策略(面板名称) | 超过阈值并修剪之后 | 后台请求 | +| --- | --- | --- | +| `"balanced"`(Summary notes) | 交接笔记。如果笔记失败,则精简。然后是 Pi 的摘要。 | 是:笔记在达到阈值之前写好。 | +| `"frugal"`(Trim first) | 先精简,因为它不调用模型。如果不够,再写交接笔记。然后是 Pi 的摘要。 | 否 | +| `"pi-summary"`(Pi's summary) | Pi 的摘要。不写交接笔记,也不精简。 | 否 | + +### 高级设置 + +把这些设置放在 `advanced` 块中。大多数用户永远不需要它们。 + +```json +{ + "advanced": { + "methodOrder": ["handoff", "shake", "soft"], + "background": true, + "supersedeReads": true, + "progressRatio": 0.8, + "prune": { "enabled": true, "protectTokens": 40000, "minSavings": 20000, "minTokens": 50 }, + "shake": { "protectTokens": 16000, "minSavings": 4000, "blockMinTokens": 400 } + } +} +``` + +| 设置 | 默认值 | 作用 | +| --- | --- | --- | +| `methodOrder` | 由 `strategy` 决定 | 取代策略的方法顺序。允许的值:`"handoff"`、`"shake"`、`"soft"`。`"soft"` 之后的方法永远不会运行。如果 `"soft"` 之前没有 `"handoff"`,就不会写交接笔记,`/compact` 时也一样。空列表 `[]` 只替换旧的读取并进行修剪。 | +| `background` | 由 `strategy` 决定 | `true` 在后台写交接笔记,提前阈值的八分之一开始(最多 32,000 个 token)。`false` 在达到阈值时才写,你的工作需要等待它完成。 | +| `supersedeReads` | `true` | 替换模型再次读取的文件的旧副本。 | +| `progressRatio` | `0.8` | 每个方法都必须把上下文降到阈值的这个比例,否则不使用它的结果,并运行下一个方法。大于 0,最大为 1。 | +| `prune.enabled` | `true` | `false` 表示从不修剪工具输出。 | +| `prune.protectTokens` | `40000` | 最新的工具输出,在这个 token 数以内,永远不会被修剪。 | +| `prune.minSavings` | `20000` | 只有当修剪至少移除这么多 token 时才会进行。 | +| `prune.minTokens` | `50` | 小于这个大小的工具输出永远不会被修剪。 | +| `shake.protectTokens` | `16000` | 最新的上下文,在这个 token 数以内,永远不会被精简。你自己的消息永远不会被精简。 | +| `shake.minSavings` | `4000` | 只有当精简至少移除这么多 token 时才会进行。 | +| `shake.blockMinTokens` | `400` | 小于这个大小的代码块和 XML 块永远不会被精简。 | + +### 设置有误时 + +pi-context-kit 会检查每个值。如果某个值有误,Pi 会显示警告,并且该设置使用默认值。其他设置仍然生效。例如,使用 `"threshold": "150000"`(带引号的文本,而不是数字)时,Pi 显示: + +```text +pi-context-kit settings need attention: threshold must be a positive integer (tokens), a percentage such as "75%", or "pi" (default used). Type /context-kit to see them. +``` + +对于拼写错误的设置名称、不是有效 JSON 的文件,以及不起作用的设置,Pi 也会发出警告,例如方法顺序中没有交接笔记时设置了 `advanced.background`。 + +### 从 0.3 升级 + +你不需要做任何事。0.4 版本读取它自己的文件。首次启动时,它会把 Pi 的 `settings.json` 中的 `contextKit` 块复制到 `~/.pi/agent/context-kit.json`(受信任项目中的块则复制到 `.pi/context-kit.json`),行为保持不变,并显示一次提示。项目文件只获得项目块修改过的设置,因为 0.3 的其他设置使用的是全局块。它不会修改 Pi 的 `settings.json`;你可以删除不再使用的 `contextKit` 块。如果 `context-kit.json` 已经存在,则不会复制任何内容。如果你之前没有 `contextKit` 块,0.4 会从新的默认值 `"75%"` 开始维护;如果想像以前一样等到 Pi 的限制,请设置 `"threshold": "pi"`。下表说明了这些值如何转换。 + +| 0.3(`settings.json` 中的 `contextKit`) | 0.4(`context-kit.json`) | +| --- | --- | +| `thresholdTokens: 150000` | `threshold: 150000` | +| `thresholdPercent: 75` | `threshold: "75%"` | +| 同时设置了 `thresholdTokens` 和 `thresholdPercent` | 使用 token 数的 `threshold` | +| 没有阈值(Pi 的限制) | `threshold: "pi"`。新用户的默认值是 `"75%"`。 | +| `methodOrder: ["shake", "handoff", "soft"]` | `strategy: "frugal"`,并且除非 `asyncEnabled` 为 `false`,否则带有 `advanced.background: true` | +| `methodOrder: ["soft"]` | `strategy: "pi-summary"` | +| 其他 `methodOrder` 值 | `advanced.methodOrder`,去掉 0.3 已经跳过的 `"remote"` 和 `"snapcompact"`。包含未知方法的列表会变为默认顺序,与 0.3 相同。 | +| `asyncEnabled` | `advanced.background`(仅当它与该策略的默认值不同时) | +| `supersedeReads`、`progressRatio`、`prune`、`shake` | `advanced` 中的同名设置 | + +### 同样生效的 Pi 设置 + +这些设置属于 Pi,而不属于 pi-context-kit。请把它们放在 Pi 的 `settings.json` 的 `compaction` 块中。 + +| Pi 设置 | 默认值 | 对 pi-context-kit 的影响 | +| --- | --- | --- | +| `compaction.enabled` | `true` | `false` 停止 Pi 的自动压缩。此时 pi-context-kit 只在 `/compact` 时修改上下文,因为没有阈值。 | +| `compaction.reserveTokens` | `16384` | Pi 的限制等于上下文窗口减去这个数。pi-context-kit 总是在这个限制处或之前开始。 | +| `compaction.keepRecentTokens` | `20000` | 交接笔记之后,大约这么多的最新 token 保持不变。 | +| `compaction.modelOverrides` | 无 | 为某一个模型修改 `reserveTokens` 和 `keepRecentTokens`。 | + +pi-context-kit 没有针对单个模型的设置。如果只想让某个模型更早开始,请用 `compaction.modelOverrides` 为这个模型缩小 Pi 的限制,例如 `{ "compaction": { "modelOverrides": { "provider/model-id": { "reserveTokens": 80000 } } } }`。对于 200,000 token 的窗口,这个模型最晚在 120,000 个 token 时开始。模型键必须是准确的 `provider/modelId`。要查看这些 ID,请输入 `pi --list-models`。 + +## 常用配置 + +| 我想要…… | `context-kit.json` | +| --- | --- | +| 更晚开始,等到 Pi 自身的限制 | `{ "threshold": "pi" }` | +| 在所有模型上以相同的 token 数开始 | `{ "threshold": 150000 }` | +| 尽可能避免模型请求 | `{ "strategy": "frugal" }` | +| 从不写交接笔记 | `{ "advanced": { "methodOrder": ["shake", "soft"] } }` | +| 保留更多最近的工具输出 | `{ "advanced": { "prune": { "protectTokens": 80000 } } }` | +| 保留所有旧的文件副本 | `{ "advanced": { "supersedeReads": false } }` | +| 关闭 pi-context-kit,但保留 `recall` | `{ "enabled": false }`,或使用 `/context-kit` | + +## 限制 + +- **Pi 仍有自己的限制。** 当上下文达到上下文窗口减去 `compaction.reserveTokens`(默认 16,384)时,Pi 会进行压缩。pi-context-kit 只能更早开始,不能更晚。你可以用 `compaction.reserveTokens` 和 `compaction.modelOverrides` 设置 Pi 的限制。 +- **阈值不是保证。** 到达阈值时,pi-context-kit 会尝试缩小上下文。如果某个工具输出非常大,或者摘要请求失败,这些方法可能会失败。此时 Pi 会在自身的限制处进行压缩。 +- **token 数是估算值。** pi-context-kit 使用 Pi 的估算。提供商的实际计数可能不同。 +- **如果 Pi 的压缩已关闭**(`compaction.enabled: false`),pi-context-kit 只在你运行 `/compact` 时修改上下文。这时它会写交接笔记,与压缩开启时相同。`threshold` 会被忽略,因为 pi-context-kit 只在阈值处自动修改上下文。 +- **手动压缩和错误。** 当你输入 `/compact`、上下文对模型来说过大,或 Pi 在轮次开始前进行压缩时,`shake` 无法运行。pi-context-kit 会使用已准备好的交接笔记,或 Pi 的摘要。 +- **方法顺序在 `soft` 处停止。** `soft` 之后的方法不会运行。 +- **子智能体**读取相同的设置文件。它们不显示警告和状态,因为它们没有界面。 + +## 故障排除 + +**底部状态栏没有 `Context`**:输入 `pi list`,确认列表中有 `npm:pi-context-kit`。然后重启 Pi。Pi 只在交互模式下显示底部状态栏。 + +**`pi-context-kit settings need attention`**:某个设置文件中的值无效。pi-context-kit 对该值使用默认值。输入 `/context-kit` 查看问题,然后修正文件,或在面板中选择新的值。 + +**`pi-context-kit moved its settings to ...`**:较早的版本把设置保存在 Pi 的 `settings.json` 中。pi-context-kit 已把它们复制到自己的文件中,只复制一次。你可以从 `settings.json` 中删除 `contextKit` 条目。 + +**`pi-context-kit: handoff note failed`**:摘要请求失败。pi-context-kit 会使用下一个方法或 Pi 的摘要,所以你的会话会继续。请检查模型和提供商的限额。 + +**面板无法保存某个值**:Pi 显示 `pi-context-kit:` 和文件错误。确认你可以写入该设置文件,然后再次选择这个值。 + +## 常见问题 + +**它会拖慢我的工作吗?** +通常不会。交接笔记在后台编写,修剪和精简不使用模型。 +如果到达阈值时没有准备好的笔记,pi-context-kit 可以推迟交接,直到正在编写的笔记准备好。它也可以写一份新的笔记,这会增加一次模型请求。 + +**它会增加费用吗?** +一份交接笔记就是一次额外的模型请求。它使用与你的会话相同的模型、思考级别和工具选择。对于 Anthropic,这样可以让提供商复用已缓存的对话。缓存不能保证。 + +**交接笔记失败会怎样?** +Pi 会显示一条以 `pi-context-kit: handoff note failed` 开头的警告。然后 pi-context-kit 使用下一个方法,或 Pi 的摘要。在阈值处的笔记失败后,pi-context-kit 在下一次压缩之前不会再在阈值处尝试新的笔记。 + +**我可以为摘要指定重点吗?** +可以。输入 `/compact` 加上重点,例如 `/compact keep the database migration details`。如果空间足够,pi-context-kit 会按照这个重点写一份新的笔记。否则,由 Pi 写它的摘要。 + +**模型忘记了一个细节,我该怎么办?** +让模型使用 `recall` 工具,例如:“Use recall to find the error message from the first test run.” + +## 开发 + +```sh +npm ci +npm run check +``` + +测试使用 Pi 的模拟(faux)提供商离线运行。它们不会调用真实模型。 +开发使用 Pi `1.5.2`。最早支持的版本是 Pi `1.0.3`。CI 在 Node 22 和 24 上检查锁定的依赖,并在 Node 24 上检查 Pi `1.0.3` 和最新版 Pi。 +由宿主提供的 peer 依赖使用 `"*"`,这是 Pi 包指南的要求。这并不保证每个 Pi 版本都能正常工作。 + +## 参与贡献与发布 + +关于本地检查、pull request 和发布流程,请参阅 [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。请通过 [SECURITY.zh-CN.md](SECURITY.zh-CN.md) 报告安全漏洞,不要使用公开 issue。 + +## 许可证 + +MIT diff --git a/SECURITY.md b/SECURITY.md index 76168ee..9ce2fd9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,7 @@ # Security policy +English | [简体中文](SECURITY.zh-CN.md) + ## Supported versions Security fixes target the latest published release. Older releases do not have a separate maintenance branch. diff --git a/SECURITY.zh-CN.md b/SECURITY.zh-CN.md new file mode 100644 index 0000000..acfc17c --- /dev/null +++ b/SECURITY.zh-CN.md @@ -0,0 +1,30 @@ +# 安全策略 + +[English](SECURITY.md) | 简体中文 + +## 支持的版本 + +安全修复针对最新发布的版本。旧版本没有单独的维护分支。 + +## 报告漏洞 + +请使用 [GitHub 私密漏洞报告](https://github.com/HugoLopes45/pi-context-kit/security/advisories/new)。 + +请包含: + +- 受影响的包版本和 Pi 版本。 +- 影响,以及使用合成数据的最小复现步骤。 +- 修复建议(如果有)。 + +不要附上访问令牌、凭据、私人对话内容或会话文件。 +在与维护者协调披露之前,不要在 issue 或 pull request 中公开漏洞利用细节。 + +本项目由志愿者维护。不保证响应或解决的期限。 + +## 范围与限制 + +请通过私密渠道报告意外的数据泄露(例如通过 `recall` 或交接笔记)以及本扩展中的其他漏洞。 + +普通的压缩错误或兼容性错误,请使用公开的 bug 报告,并对细节进行脱敏。 + +本扩展在 Pi 中运行,拥有 Pi 进程的权限。只从你信任的来源安装扩展。