pi-context-kit 0.4.2 → 0.4.4

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 (39) hide show
  1. package/CHANGELOG.md +22 -8
  2. package/LICENSE +1 -1
  3. package/README.md +162 -151
  4. package/context-kit.schema.json +62 -78
  5. package/extensions/index.ts +279 -256
  6. package/node_modules/pi-hl-utils/LICENSE +21 -0
  7. package/node_modules/pi-hl-utils/package.json +47 -0
  8. package/node_modules/pi-hl-utils/src/errors.ts +9 -0
  9. package/node_modules/pi-hl-utils/src/evidence.ts +363 -0
  10. package/node_modules/pi-hl-utils/src/expand-on-click.ts +90 -0
  11. package/node_modules/pi-hl-utils/src/layered-settings.ts +513 -0
  12. package/node_modules/pi-hl-utils/src/null-optional-arguments.ts +147 -0
  13. package/node_modules/pi-hl-utils/src/pi-agent-session-discovery.ts +48 -0
  14. package/node_modules/pi-hl-utils/src/record.ts +3 -0
  15. package/node_modules/pi-hl-utils/src/settings-command.ts +213 -0
  16. package/node_modules/pi-hl-utils/src/settings-menu.ts +477 -0
  17. package/node_modules/pi-hl-utils/src/token-calibration.ts +39 -0
  18. package/node_modules/pi-hl-utils/src/ui.ts +355 -0
  19. package/package.json +42 -44
  20. package/src/background.ts +2 -3
  21. package/src/command.ts +17 -0
  22. package/src/config.ts +3 -207
  23. package/src/context-kit-settings.ts +152 -0
  24. package/src/context.ts +43 -16
  25. package/src/files.ts +6 -13
  26. package/src/handoff.ts +3 -7
  27. package/src/maintain.ts +6 -19
  28. package/src/menu.ts +159 -0
  29. package/src/migrate.ts +99 -19
  30. package/src/note.ts +5 -6
  31. package/src/prune.ts +2 -1
  32. package/src/recall.ts +14 -37
  33. package/src/settings-file.ts +13 -101
  34. package/src/shake.ts +6 -12
  35. package/src/stale.ts +22 -26
  36. package/src/status.ts +2 -6
  37. package/src/tool-calls.ts +2 -3
  38. package/README.zh-CN.md +0 -387
  39. package/src/panel.ts +0 -89
package/src/shake.ts CHANGED
@@ -3,6 +3,7 @@ import type {
3
3
  ContextEditableContent,
4
4
  ProjectedSessionEntry,
5
5
  } from "@earendil-works/pi-coding-agent";
6
+
6
7
  import {
7
8
  type Edit,
8
9
  type EditableMessage,
@@ -29,10 +30,7 @@ const BLOCK =
29
30
  * so every tool call keeps its result. Signatures stay valid, but Anthropic drops every thinking
30
31
  * block after the first changed message.
31
32
  */
32
- export function shake(
33
- entries: readonly ProjectedSessionEntry[],
34
- options: ShakeOptions,
35
- ): Edit[] {
33
+ export function shake(entries: readonly ProjectedSessionEntry[], options: ShakeOptions): Edit[] {
36
34
  const edits: Edit[] = [];
37
35
  let seen = 0;
38
36
  let savings = 0;
@@ -49,9 +47,7 @@ export function shake(
49
47
  savings += edit.saved;
50
48
  edits.push(edit.edit);
51
49
  }
52
- return savings >= options.minSavings && edits.length > 0
53
- ? edits.reverse()
54
- : [];
50
+ return savings >= options.minSavings && edits.length > 0 ? edits.toReversed() : [];
55
51
  }
56
52
 
57
53
  function shakeEdit(
@@ -63,8 +59,7 @@ function shakeEdit(
63
59
  const targetId = entry.sourceEntry.id;
64
60
  const content = shakeContent(message, targetId, options);
65
61
  if (content === undefined) return undefined;
66
- const saved =
67
- messageTokens(message) - messageTokens(withContent(message, content));
62
+ const saved = messageTokens(message) - messageTokens(withContent(message, content));
68
63
  return saved > 0 ? { edit: { targetId, content }, saved } : undefined;
69
64
  }
70
65
 
@@ -73,8 +68,7 @@ function shakeContent(
73
68
  id: string,
74
69
  options: ShakeOptions,
75
70
  ): ContextEditableContent | undefined {
76
- const text = (value: string) =>
77
- elideBlocks(value, id, options.blockMinTokens);
71
+ const text = (value: string) => elideBlocks(value, id, options.blockMinTokens);
78
72
 
79
73
  if (typeof message.content === "string") {
80
74
  const next = text(message.content);
@@ -95,7 +89,7 @@ function shakeContent(
95
89
  return block;
96
90
  });
97
91
  // Blocks keep their kind, and images only occur where text is also allowed.
98
- return changed ? (next as ContextEditableContent) : undefined;
92
+ return changed ? next : undefined;
99
93
  }
100
94
 
101
95
  function elideBlocks(text: string, id: string, minTokens: number): string {
package/src/stale.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { ToolResultMessage } from "@earendil-works/pi-ai";
2
2
  import type { ProjectedSessionEntry } from "@earendil-works/pi-coding-agent";
3
+
3
4
  import { type Edit, messageTokens, withContent } from "./context.ts";
4
5
  import { newestToolResults, type ToolResult } from "./tool-calls.ts";
5
6
 
@@ -44,19 +45,12 @@ export function supersededReads(
44
45
  recordRead(seen, result, key);
45
46
  newer.set(key.path, seen);
46
47
  }
47
- return edits.reverse();
48
+ return edits.toReversed();
48
49
  }
49
50
 
50
- function isSuperseded(
51
- { message }: ToolResult,
52
- key: ReadKey,
53
- seen: NewerReads,
54
- ): boolean {
51
+ function isSuperseded({ message }: ToolResult, key: ReadKey, seen: NewerReads): boolean {
55
52
  if (message.isError) return seen.anyRead;
56
- return (
57
- seen.fullSuccess ||
58
- (key.range !== undefined && seen.successRanges.has(key.range))
59
- );
53
+ return seen.fullSuccess || (key.range !== undefined && seen.successRanges.has(key.range));
60
54
  }
61
55
 
62
56
  function supersededEdit({ id, message }: ToolResult): Edit | undefined {
@@ -66,11 +60,7 @@ function supersededEdit({ id, message }: ToolResult): Edit | undefined {
66
60
  : undefined;
67
61
  }
68
62
 
69
- function recordRead(
70
- seen: NewerReads,
71
- { message }: ToolResult,
72
- key: ReadKey,
73
- ): void {
63
+ function recordRead(seen: NewerReads, { message }: ToolResult, key: ReadKey): void {
74
64
  seen.anyRead = true;
75
65
  if (message.isError || isTruncatedRead(message.content)) return;
76
66
  if (key.range === undefined) seen.fullSuccess = true;
@@ -81,21 +71,27 @@ function isTruncatedRead(content: ToolResultMessage["content"]): boolean {
81
71
  return content.some(
82
72
  (block) =>
83
73
  block.type === "text" &&
84
- /\[(?:Showing lines |\d+ more lines in file|Line \d+ is )/.test(
85
- block.text,
86
- ),
74
+ /\[(?:Showing lines |\d+ more lines in file|Line \d+ is )/.test(block.text),
87
75
  );
88
76
  }
89
77
 
90
- function readKey(
91
- args: Record<string, unknown> | undefined,
92
- ): ReadKey | undefined {
78
+ function isRangePart(value: unknown): value is number | string | undefined {
79
+ return value === undefined || typeof value === "number" || typeof value === "string";
80
+ }
81
+
82
+ function readKey(args: Record<string, unknown> | undefined): ReadKey | undefined {
93
83
  const path = args?.path;
94
84
  if (typeof path !== "string" || path.length === 0) return undefined;
95
85
  const { offset, limit } = args ?? {};
96
- const ranged = offset !== undefined || limit !== undefined;
97
- return {
98
- path,
99
- range: ranged ? `${String(offset ?? 1)}:${String(limit ?? "")}` : undefined,
100
- };
86
+ // A range that is not a number or string has no comparable key, so the read is never superseded.
87
+ if (!isRangePart(offset) || !isRangePart(limit)) return undefined;
88
+ return { path, range: rangeKey(offset, limit) };
89
+ }
90
+
91
+ function rangeKey(
92
+ offset: number | string | undefined,
93
+ limit: number | string | undefined,
94
+ ): string | undefined {
95
+ if (offset === undefined && limit === undefined) return undefined;
96
+ return `${String(offset ?? 1)}:${String(limit ?? "")}`;
101
97
  }
package/src/status.ts CHANGED
@@ -8,7 +8,7 @@ export interface StatusInput {
8
8
  /** Where compaction starts, or +Infinity when nothing compacts. */
9
9
  limit: number;
10
10
  contextWindow: number;
11
- note?: keyof typeof NOTE_LABEL;
11
+ note?: keyof typeof NOTE_LABEL | undefined;
12
12
  }
13
13
 
14
14
  /** The footer text: context use and threshold as shares of the window, then the background note. */
@@ -22,11 +22,7 @@ export function statusText(input: StatusInput): string {
22
22
  }
23
23
 
24
24
  /** The notice after context edits, which Pi does not show by itself. */
25
- export function freedNotice(
26
- before: number,
27
- after: number,
28
- contextWindow: number,
29
- ): string {
25
+ export function freedNotice(before: number, after: number, contextWindow: number): string {
30
26
  const freed = before - after;
31
27
  return `pi-context-kit freed ${percent(freed, contextWindow)} of the context (${tokenCount(freed)} tokens). The agent can still look up what was removed.`;
32
28
  }
package/src/tool-calls.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { ToolCall } from "@earendil-works/pi-ai";
2
2
  import type { ProjectedSessionEntry } from "@earendil-works/pi-coding-agent";
3
+
3
4
  import { type EditableMessage, editableMessage } from "./context.ts";
4
5
 
5
6
  export interface ToolResult {
@@ -9,9 +10,7 @@ export interface ToolResult {
9
10
  }
10
11
 
11
12
  /** Tool calls in the projected context, by tool call ID. */
12
- function toolCallsById(
13
- entries: readonly ProjectedSessionEntry[],
14
- ): Map<string, ToolCall> {
13
+ function toolCallsById(entries: readonly ProjectedSessionEntry[]): Map<string, ToolCall> {
15
14
  const calls = new Map<string, ToolCall>();
16
15
  for (const entry of entries) {
17
16
  for (const message of entry.messages) {
package/README.zh-CN.md DELETED
@@ -1,387 +0,0 @@
1
- # pi-context-kit:让 Pi 长会话始终保持清晰
2
-
3
- [English](README.md) | 简体中文
4
-
5
- [![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)
6
- [![npm](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit)
7
- [![Pi package](https://img.shields.io/badge/pi.dev-package-blue)](https://pi.dev/packages/pi-context-kit)
8
- [![Node.js](https://img.shields.io/node/v/pi-context-kit)](https://nodejs.org)
9
- [![License: MIT](https://img.shields.io/npm/l/pi-context-kit)](LICENSE)
10
-
11
- 为 [Pi 编程智能体](https://github.com/earendil-works/pi)提供压缩(compaction)和上下文管理。pi-context-kit 会把过时的文件读取和旧的工具输出从上下文窗口中清理出去,在 Pi 需要之前于后台写好交接摘要,并让当前分支的原始文本只需一次 `recall` 搜索即可找回。
12
-
13
- ```sh
14
- pi install npm:pi-context-kit
15
- ```
16
-
17
- 重启 Pi。默认设置无需任何配置即可使用。
18
-
19
- ## 为什么选择 pi-context-kit
20
-
21
- - **更干净的上下文窗口。** 超过阈值后,文件的旧副本和旧的工具输出会变成一行提示。最新的工具输出保持不变。
22
- - **提前写好的摘要。** 会话模型在后台写交接笔记,同时继续工作。到达阈值时,如果已准备好的笔记仍能放进上下文,压缩就不必等待新的摘要。
23
- - **不删除任何内容。** 会话保留原始文本。模型可以用 `recall` 工具搜索并重新读取它。
24
- - **尽量免费。** 替换旧的读取、修剪(prune)和精简(shake)都不调用模型。
25
- - **对缓存友好。** 上下文只在超过阈值后才被修改,并且一次完成。提供商的提示词缓存在每个维护步骤中只失效一次,而不是每个轮次都失效。
26
- - **零配置。** 安装、重启、开始工作。默认情况下,维护从上下文窗口的 75% 开始,对大多数模型来说,这早于 Pi 自身的限制。
27
- - **状态可见。** 底部状态栏显示上下文的占用程度以及清理何时开始。一条提示会告诉你释放了多少空间。输入 `/context-kit` 即可在面板中修改主要设置,无需编辑文件。
28
-
29
- ## 模型看到的内容
30
-
31
- 超过阈值后,大段的旧内容会变成一行提示。完整文本仍保留在会话中。示例(大小和 ID 仅为示意;最后一条提示只在精简运行时出现,参见 [`strategy`](#主要设置)):
32
-
33
- ```diff
34
- - <first read of src/app.ts, about 5,000 tokens>
35
- + [Superseded by a newer read of this file]
36
-
37
- - <output of npm test from one hour ago, about 12,000 tokens>
38
- + [Output pruned: about 12000 tokens. Call recall with entryId "a1b2c3d4" to read it.]
39
-
40
- - <a large code block in an old reply, about 2,000 tokens>
41
- + [Elided block: about 2000 tokens. Call recall with entryId "e5f6a7b8" to read it.]
42
- ```
43
-
44
- 这些提示永远不会改变你的消息或模型的工具调用。模型的推理内容也会保留,Anthropic 有一个例外。压缩仍然会用摘要替换较早的消息。参见[维护会保留什么](#维护会保留什么)。
45
-
46
- ## 单独使用 Pi,与搭配 pi-context-kit 使用 Pi
47
-
48
- | 在长会话中 | 单独使用 Pi | 搭配 pi-context-kit |
49
- | --- | --- | --- |
50
- | 模型再次读取同一个文件 | 两个副本都留在上下文中。 | 超过阈值后,旧副本被替换。 |
51
- | 旧的工具输出占满上下文 | 它们一直保留,直到 Pi 生成摘要。 | 它们被替换为一条简短提示。不需要模型请求。 |
52
- | 上下文达到限制 | Pi 写一份摘要。 | 交接笔记可能已经准备好,因为它是在后台写的。 |
53
- | 模型需要一个已移除的细节 | 上下文中只剩下摘要。 | 模型调用 `recall` 读取原始文本。 |
54
-
55
- 原始的会话条目永远不会改变。只有 Pi 发送给模型的上下文会变小。
56
-
57
- pi-context-kit 适用于 Pi 长会话:大量文件读取、很长的命令输出,或多次压缩。在短会话中,上下文很少达到阈值,因此在轮次结束时上下文不会改变。接近阈值时,后台交接笔记仍可能开始编写;`/compact` 会先尝试交接笔记,失败时回退到 Pi 的摘要。
58
-
59
- ## 为什么 Pi 长会话需要上下文管理
60
-
61
- AI 模型一次只能读取有限的文本。这个限制就是**上下文窗口**。文本以 **token** 计量。Pi 大约把 4 个字符算作一个 token。
62
-
63
- 在长会话中,对话会逐渐占满上下文窗口。文件读取和命令输出通常是最大的部分。当窗口快满时,Pi 会进行**压缩**:用一份摘要替换旧的对话。摘要可能丢失细节,而且需要时间和费用。
64
-
65
- <details>
66
- <summary>本文档中使用的术语</summary>
67
-
68
- | 术语 | 含义 |
69
- | --- | --- |
70
- | Token | 一小段文本。模型以 token 计算它的记忆容量。 |
71
- | 上下文窗口 | 模型一次能读取的最大 token 数。 |
72
- | 上下文 | Pi 当前发送给模型的全部文本:指令、消息和工具输出。 |
73
- | 轮次 | 一个循环:模型回复、使用工具,然后停止。 |
74
- | 工具输出 | 工具的结果,例如文件内容或命令输出。 |
75
- | 阈值 | 维护开始时的 token 数。 |
76
- | 压缩 | Pi 用一份摘要替换旧的对话。最新的消息保留。 |
77
- | 交接笔记 | pi-context-kit 使用与你的会话相同的模型写的摘要。 |
78
- | Pi 的摘要 | 没有可用的交接笔记时,Pi 写的摘要。 |
79
-
80
- </details>
81
-
82
- ## 快速开始
83
-
84
- 你需要 Pi 1.0.3 或更高版本,以及 Node.js 22.19 或更高版本。
85
-
86
- 1. 用上面的命令安装本包。
87
- 2. 重启 Pi。
88
- 3. 查看底部状态栏。扩展生效时,它显示 `Context 0% · cleanup at 75%`。
89
- 4. 照常工作。输入 `/context-kit` 修改设置。
90
-
91
- ## 更新、试用或移除
92
-
93
- ```sh
94
- pi update npm:pi-context-kit # 更新,然后重启 Pi
95
- pi -e npm:pi-context-kit # 不安装,只试用一个会话
96
- pi remove npm:pi-context-kit # 移除,然后重启 Pi
97
- ```
98
-
99
- 更新后,Pi 会根据 [CHANGELOG.md](CHANGELOG.md)(英文)显示变更内容。
100
-
101
- ## 使用方法
102
-
103
- 你不需要做任何配置。pi-context-kit 在 Pi 的底部状态栏中显示它的状态:
104
-
105
- | 底部状态栏 | 含义 |
106
- | --- | --- |
107
- | `Context 62% · cleanup at 75%` | 上下文已占用 62%。清理从 75% 开始。 |
108
- | `Context 70% · cleanup at 75% · writing summary` | 正在后台编写交接笔记。`summary ready` 表示笔记已准备好。 |
109
- | `Context 25% · no automatic cleanup` | Pi 的自动压缩已关闭,因此只有在你输入 `/compact` 时才会清理。 |
110
- | `Context cleanup off` | 你关闭了自动清理。 |
111
-
112
- pi-context-kit 缩短旧输出后,Pi 会显示一条提示,例如:`pi-context-kit freed 17% of the context (34k tokens). The agent can still look up what was removed.`
113
-
114
- 要修改设置,输入 `/context-kit` 并按 Enter。用方向键选择一行,按 Enter 修改它的值。修改会立即保存,并从下一个轮次开始生效。按 Escape 关闭面板。
115
-
116
- 面板使用英文界面:
117
-
118
- | 面板行 | 选项 | 文件中的设置 |
119
- | --- | --- | --- |
120
- | Automatic cleanup(自动清理) | On、Off | `enabled` |
121
- | Clean up when the context is(何时清理) | 50% full 到 90% full、At Pi's limit | `threshold` |
122
- | Cleanup method(清理方式) | Summary notes (recommended)、Trim first、Pi's summary | `strategy`:`"balanced"`、`"frugal"`、`"pi-summary"` |
123
-
124
- 当文件中有 `advanced.methodOrder` 时,面板不显示 Cleanup method 这一行,因为该设置会取代清理方式。
125
-
126
- 在非交互模式下,`/context-kit` 用一行文字显示当前设置。
127
-
128
- ## 会话中的工作方式
129
-
130
- ```text
131
- 每个轮次结束
132
- |
133
- v
134
- 上下文接近阈值? --是--> 在后台开始编写交接笔记
135
- |
136
- v
137
- 上下文超过阈值? --否--> 继续工作
138
- |
139
- 是
140
- v
141
- 替换旧的文件读取,并修剪旧的工具输出
142
- |
143
- v
144
- 现在足够小了? --是--> 继续工作
145
- |
146
- 否
147
- v
148
- 依次尝试策略中的每个方法,例如:handoff、shake、soft
149
- ```
150
-
151
- ### 1. 旧的文件读取会被替换
152
-
153
- 有时模型会把同一个文件读取两次,这时第一个副本就过时了。
154
- pi-context-kit 会把旧副本替换为这段文本:`[Superseded by a newer read of this file]`。
155
-
156
- 只有当新的读取完全覆盖旧的读取时,才会这样做。如果新的读取被截断,旧副本会保留。
157
- 只有当上下文超过阈值时才会这样做,并且与修剪、精简或压缩在同一次修改中完成。每次修改旧文本,都会让提供商在没有缓存的情况下重新读取之后的全部文本。对于 Anthropic,它还会从请求中移除模型之前的推理内容。在接近阈值时修改一次,比每个轮次都修改的成本更低。
158
-
159
- ### 2. 提前准备交接笔记
160
-
161
- 在上下文达到阈值之前,会话模型会在后台写交接笔记。你的工作不会中断。
162
- 笔记提前阈值的八分之一开始编写,最多提前 32,000 个 token。阈值为 150,000 个 token 时,它大约在 131,250 个 token 时开始。
163
-
164
- 笔记使用与 Pi 的摘要相同的章节。它还会列出读取过和修改过的文件。
165
-
166
- ### 3. 修剪旧的工具输出
167
-
168
- 超过阈值后,旧的工具输出会被替换为一条简短提示,例如:
169
- `[Output pruned: about 5000 tokens. Call recall with entryId "abc123" to read it.]`
170
-
171
- 最新的 40,000 个 token 的工具输出始终保留。只有当上下文变得足够小时,pi-context-kit 才会保留这次修改。“足够小”指阈值的 80% 或更少。
172
-
173
- ### 4. 依次使用其他方法
174
-
175
- 如果修剪不够,pi-context-kit 会依次尝试[策略](#主要设置)中的方法:
176
-
177
- | 方法 | 作用 | 是否使用模型 |
178
- | --- | --- | --- |
179
- | `handoff` | 用交接笔记替换旧的对话。最新的消息保留。 | 是 |
180
- | `shake` | 把较大的旧代码块、XML 块和图片替换为一条简短提示。你的消息永远不会被精简。 | 否 |
181
- | `soft` | 用 Pi 的摘要替换旧的对话。最新的消息保留。到此为止。 | 是 |
182
-
183
- 在这些步骤中,你的工作会继续进行。pi-context-kit 永远不会为了压缩而中断正在运行的任务。
184
-
185
- ### `recall` 工具
186
-
187
- `recall` 工具读取原始会话文本,而不是发送给模型的缩短后的上下文。它可以:
188
-
189
- - 搜索当前分支上较早的对话文本,包括已移除和已被摘要的消息;
190
- - 按 ID 读取一个条目的文本,较大的条目支持分页。
191
-
192
- 其他分支和会话不包括在内。系统提示词条目不会被搜索。
193
- 图片保留在原始会话条目中,但 `recall` 只返回它们的 MIME 类型,不返回图片内容。
194
- 模型必须调用 `recall` 才能找回缺失的细节。找回不会自动进行。
195
-
196
- ## 维护会保留什么
197
-
198
- 文件读取替换、修剪和精简不会改写原始会话条目。
199
- 在模型的上下文中,这些步骤会保留:
200
-
201
- - 你的消息,包括你的指令和图片。
202
- - 模型的工具调用和推理内容。在被修改的消息之后,Anthropic 仍可能丢弃推理内容(参见[旧的文件读取会被替换](#1-旧的文件读取会被替换))。
203
- - 工具调用与工具结果的配对。每个工具调用都保留它的结果,但结果内容可能被缩短。
204
-
205
- 压缩则不同:它会用摘要替换较早的上下文,包括较早的用户消息。原始条目仍保留在会话历史中。
206
-
207
- ## 设置
208
-
209
- 本节面向需要编辑设置文件的用户。面板可以修改三个主要设置;文件中还包含高级设置。
210
-
211
- ### 设置文件
212
-
213
- | 文件 | 适用范围 |
214
- | --- | --- |
215
- | `~/.pi/agent/context-kit.json` | 你的所有项目。`~` 是你的主目录。 |
216
- | 项目文件夹中的 `.pi/context-kit.json` | 仅限该项目,并且只有在你于 Pi 中信任该项目时才生效。它的值会取代全局文件中的值。 |
217
-
218
- 你不需要设置所有选项。未设置的选项使用默认值。pi-context-kit 在每个轮次都会重新读取这些文件,所以你不需要重启 Pi。如果项目文件设置了某个选项,面板会写入项目文件,否则写入全局文件。
219
-
220
- 添加 `$schema` 这一行,即可在 VS Code 等编辑器中获得补全和检查:
221
-
222
- ```json
223
- {
224
- "$schema": "https://unpkg.com/pi-context-kit/context-kit.schema.json",
225
- "threshold": "70%",
226
- "strategy": "frugal"
227
- }
228
- ```
229
-
230
- ### 主要设置
231
-
232
- | 设置 | 允许的值 | 默认值 | 作用 |
233
- | --- | --- | --- | --- |
234
- | `enabled` | `true`、`false` | `true` | `false` 停止所有维护和交接笔记。`recall` 工具仍然可用。 |
235
- | `threshold` | token 数(整数)、百分比(例如 `"75%"`)或 `"pi"` | `"75%"` | 维护开始的位置。 |
236
- | `strategy` | `"balanced"`、`"frugal"`、`"pi-summary"` | `"balanced"` | 修剪不够时,pi-context-kit 采取的做法。 |
237
-
238
- **`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-设置)。
239
-
240
- **`strategy`。**
241
-
242
- | 策略(面板名称) | 超过阈值并修剪之后 | 后台请求 |
243
- | --- | --- | --- |
244
- | `"balanced"`(Summary notes) | 交接笔记。如果笔记失败,则精简。然后是 Pi 的摘要。 | 是:笔记在达到阈值之前写好。 |
245
- | `"frugal"`(Trim first) | 先精简,因为它不调用模型。如果不够,再写交接笔记。然后是 Pi 的摘要。 | 否 |
246
- | `"pi-summary"`(Pi's summary) | Pi 的摘要。不写交接笔记,也不精简。 | 否 |
247
-
248
- ### 高级设置
249
-
250
- 把这些设置放在 `advanced` 块中。大多数用户永远不需要它们。
251
-
252
- ```json
253
- {
254
- "advanced": {
255
- "methodOrder": ["handoff", "shake", "soft"],
256
- "background": true,
257
- "supersedeReads": true,
258
- "progressRatio": 0.8,
259
- "prune": { "enabled": true, "protectTokens": 40000, "minSavings": 20000, "minTokens": 50 },
260
- "shake": { "protectTokens": 16000, "minSavings": 4000, "blockMinTokens": 400 }
261
- }
262
- }
263
- ```
264
-
265
- | 设置 | 默认值 | 作用 |
266
- | --- | --- | --- |
267
- | `methodOrder` | 由 `strategy` 决定 | 取代策略的方法顺序。允许的值:`"handoff"`、`"shake"`、`"soft"`。`"soft"` 之后的方法永远不会运行。如果 `"soft"` 之前没有 `"handoff"`,就不会写交接笔记,`/compact` 时也一样。空列表 `[]` 只替换旧的读取并进行修剪。 |
268
- | `background` | 由 `strategy` 决定 | `true` 在后台写交接笔记,提前阈值的八分之一开始(最多 32,000 个 token)。`false` 在达到阈值时才写,你的工作需要等待它完成。 |
269
- | `supersedeReads` | `true` | 替换模型再次读取的文件的旧副本。 |
270
- | `progressRatio` | `0.8` | 每个方法都必须把上下文降到阈值的这个比例,否则不使用它的结果,并运行下一个方法。大于 0,最大为 1。 |
271
- | `prune.enabled` | `true` | `false` 表示从不修剪工具输出。 |
272
- | `prune.protectTokens` | `40000` | 最新的工具输出,在这个 token 数以内,永远不会被修剪。 |
273
- | `prune.minSavings` | `20000` | 只有当修剪至少移除这么多 token 时才会进行。 |
274
- | `prune.minTokens` | `50` | 小于这个大小的工具输出永远不会被修剪。 |
275
- | `shake.protectTokens` | `16000` | 最新的上下文,在这个 token 数以内,永远不会被精简。你自己的消息永远不会被精简。 |
276
- | `shake.minSavings` | `4000` | 只有当精简至少移除这么多 token 时才会进行。 |
277
- | `shake.blockMinTokens` | `400` | 小于这个大小的代码块和 XML 块永远不会被精简。 |
278
-
279
- ### 设置有误时
280
-
281
- pi-context-kit 会检查每个值。如果某个值有误,Pi 会显示警告,并且该设置使用默认值。其他设置仍然生效。例如,使用 `"threshold": "150000"`(带引号的文本,而不是数字)时,Pi 显示:
282
-
283
- ```text
284
- 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.
285
- ```
286
-
287
- 对于拼写错误的设置名称、不是有效 JSON 的文件,以及不起作用的设置,Pi 也会发出警告,例如方法顺序中没有交接笔记时设置了 `advanced.background`。
288
-
289
- ### 从 0.3 升级
290
-
291
- 你不需要做任何事。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"`。下表说明了这些值如何转换。
292
-
293
- | 0.3(`settings.json` 中的 `contextKit`) | 0.4(`context-kit.json`) |
294
- | --- | --- |
295
- | `thresholdTokens: 150000` | `threshold: 150000` |
296
- | `thresholdPercent: 75` | `threshold: "75%"` |
297
- | 同时设置了 `thresholdTokens` 和 `thresholdPercent` | 使用 token 数的 `threshold` |
298
- | 没有阈值(Pi 的限制) | `threshold: "pi"`。新用户的默认值是 `"75%"`。 |
299
- | `methodOrder: ["shake", "handoff", "soft"]` | `strategy: "frugal"`,并且除非 `asyncEnabled` 为 `false`,否则带有 `advanced.background: true` |
300
- | `methodOrder: ["soft"]` | `strategy: "pi-summary"` |
301
- | 其他 `methodOrder` 值 | `advanced.methodOrder`,去掉 0.3 已经跳过的 `"remote"` 和 `"snapcompact"`。包含未知方法的列表会变为默认顺序,与 0.3 相同。 |
302
- | `asyncEnabled` | `advanced.background`(仅当它与该策略的默认值不同时) |
303
- | `supersedeReads`、`progressRatio`、`prune`、`shake` | `advanced` 中的同名设置 |
304
-
305
- ### 同样生效的 Pi 设置
306
-
307
- 这些设置属于 Pi,而不属于 pi-context-kit。请把它们放在 Pi 的 `settings.json` 的 `compaction` 块中。
308
-
309
- | Pi 设置 | 默认值 | 对 pi-context-kit 的影响 |
310
- | --- | --- | --- |
311
- | `compaction.enabled` | `true` | `false` 停止 Pi 的自动压缩。此时 pi-context-kit 只在 `/compact` 时修改上下文,因为没有阈值。 |
312
- | `compaction.reserveTokens` | `16384` | Pi 的限制等于上下文窗口减去这个数。pi-context-kit 总是在这个限制处或之前开始。 |
313
- | `compaction.keepRecentTokens` | `20000` | 交接笔记之后,大约这么多的最新 token 保持不变。 |
314
- | `compaction.modelOverrides` | 无 | 为某一个模型修改 `reserveTokens` 和 `keepRecentTokens`。 |
315
-
316
- 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`。
317
-
318
- ## 常用配置
319
-
320
- | 我想要…… | `context-kit.json` |
321
- | --- | --- |
322
- | 更晚开始,等到 Pi 自身的限制 | `{ "threshold": "pi" }` |
323
- | 在所有模型上以相同的 token 数开始 | `{ "threshold": 150000 }` |
324
- | 尽可能避免模型请求 | `{ "strategy": "frugal" }` |
325
- | 从不写交接笔记 | `{ "advanced": { "methodOrder": ["shake", "soft"] } }` |
326
- | 保留更多最近的工具输出 | `{ "advanced": { "prune": { "protectTokens": 80000 } } }` |
327
- | 保留所有旧的文件副本 | `{ "advanced": { "supersedeReads": false } }` |
328
- | 关闭 pi-context-kit,但保留 `recall` | `{ "enabled": false }`,或使用 `/context-kit` |
329
-
330
- ## 限制
331
-
332
- - **Pi 仍有自己的限制。** 当上下文达到上下文窗口减去 `compaction.reserveTokens`(默认 16,384)时,Pi 会进行压缩。pi-context-kit 只能更早开始,不能更晚。你可以用 `compaction.reserveTokens` 和 `compaction.modelOverrides` 设置 Pi 的限制。
333
- - **阈值不是保证。** 到达阈值时,pi-context-kit 会尝试缩小上下文。如果某个工具输出非常大,或者摘要请求失败,这些方法可能会失败。此时 Pi 会在自身的限制处进行压缩。
334
- - **token 数是估算值。** pi-context-kit 使用 Pi 的估算。提供商的实际计数可能不同。
335
- - **如果 Pi 的压缩已关闭**(`compaction.enabled: false`),pi-context-kit 只在你运行 `/compact` 时修改上下文。这时它会写交接笔记,与压缩开启时相同。`threshold` 会被忽略,因为 pi-context-kit 只在阈值处自动修改上下文。
336
- - **手动压缩和错误。** 当你输入 `/compact`、上下文对模型来说过大,或 Pi 在轮次开始前进行压缩时,`shake` 无法运行。pi-context-kit 会使用已准备好的交接笔记,或 Pi 的摘要。
337
- - **方法顺序在 `soft` 处停止。** `soft` 之后的方法不会运行。
338
- - **子智能体**读取相同的设置文件。它们不显示警告和状态,因为它们没有界面。
339
-
340
- ## 故障排除
341
-
342
- **底部状态栏没有 `Context`**:输入 `pi list`,确认列表中有 `npm:pi-context-kit`。然后重启 Pi。Pi 只在交互模式下显示底部状态栏。
343
-
344
- **`pi-context-kit settings need attention`**:某个设置文件中的值无效。pi-context-kit 对该值使用默认值。输入 `/context-kit` 查看问题,然后修正文件,或在面板中选择新的值。
345
-
346
- **`pi-context-kit moved its settings to ...`**:较早的版本把设置保存在 Pi 的 `settings.json` 中。pi-context-kit 已把它们复制到自己的文件中,只复制一次。你可以从 `settings.json` 中删除 `contextKit` 条目。
347
-
348
- **`pi-context-kit: handoff note failed`**:摘要请求失败。pi-context-kit 会使用下一个方法或 Pi 的摘要,所以你的会话会继续。请检查模型和提供商的限额。
349
-
350
- **面板无法保存某个值**:Pi 显示 `pi-context-kit:` 和文件错误。确认你可以写入该设置文件,然后再次选择这个值。
351
-
352
- ## 常见问题
353
-
354
- **它会拖慢我的工作吗?**
355
- 通常不会。交接笔记在后台编写,修剪和精简不使用模型。
356
- 如果到达阈值时没有准备好的笔记,pi-context-kit 可以推迟交接,直到正在编写的笔记准备好。它也可以写一份新的笔记,这会增加一次模型请求。
357
-
358
- **它会增加费用吗?**
359
- 一份交接笔记就是一次额外的模型请求。它使用与你的会话相同的模型、思考级别和工具选择。对于 Anthropic,这样可以让提供商复用已缓存的对话。缓存不能保证。
360
-
361
- **交接笔记失败会怎样?**
362
- Pi 会显示一条以 `pi-context-kit: handoff note failed` 开头的警告。然后 pi-context-kit 使用下一个方法,或 Pi 的摘要。在阈值处的笔记失败后,pi-context-kit 在下一次压缩之前不会再在阈值处尝试新的笔记。
363
-
364
- **我可以为摘要指定重点吗?**
365
- 可以。输入 `/compact` 加上重点,例如 `/compact keep the database migration details`。如果空间足够,pi-context-kit 会按照这个重点写一份新的笔记。否则,由 Pi 写它的摘要。
366
-
367
- **模型忘记了一个细节,我该怎么办?**
368
- 让模型使用 `recall` 工具,例如:“Use recall to find the error message from the first test run.”
369
-
370
- ## 开发
371
-
372
- ```sh
373
- npm ci
374
- npm run check
375
- ```
376
-
377
- 测试使用 Pi 的模拟(faux)提供商离线运行。它们不会调用真实模型。
378
- 开发使用 Pi `1.5.2`。最早支持的版本是 Pi `1.0.3`。CI 在 Node 22 和 24 上检查锁定的依赖,并在 Node 24 上检查 Pi `1.0.3` 和最新版 Pi。
379
- 由宿主提供的 peer 依赖使用 `"*"`,这是 Pi 包指南的要求。这并不保证每个 Pi 版本都能正常工作。
380
-
381
- ## 参与贡献与发布
382
-
383
- 关于本地检查、pull request 和发布流程,请参阅 [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。请通过 [SECURITY.zh-CN.md](SECURITY.zh-CN.md) 报告安全漏洞,不要使用公开 issue。
384
-
385
- ## 许可证
386
-
387
- MIT
package/src/panel.ts DELETED
@@ -1,89 +0,0 @@
1
- import {
2
- type ContextKitConfig,
3
- type Strategy,
4
- type Threshold,
5
- } from "./config.ts";
6
-
7
- /** The `SettingItem` fields of `@earendil-works/pi-tui` that the panel uses. */
8
- export interface PanelItem {
9
- id: "enabled" | "threshold" | "strategy";
10
- label: string;
11
- description: string;
12
- currentValue: string;
13
- values: string[];
14
- }
15
-
16
- const PI_LIMIT = "At Pi's limit";
17
- const THRESHOLDS = [
18
- ...[50, 60, 70, 75, 80, 90].map((percent) => `${percent}% full`),
19
- PI_LIMIT,
20
- ];
21
- const METHODS: Readonly<Record<Strategy, string>> = {
22
- balanced: "Summary notes (recommended)",
23
- frugal: "Trim first",
24
- "pi-summary": "Pi's summary",
25
- };
26
-
27
- /** The settings the `/context-kit` panel edits, in plain words. The rest stay in the file. */
28
- export function panelItems(config: ContextKitConfig): PanelItem[] {
29
- const threshold = thresholdText(config.threshold);
30
- const items: PanelItem[] = [
31
- {
32
- id: "enabled",
33
- label: "Automatic cleanup",
34
- description:
35
- "Makes room in a long conversation so the agent keeps working. Off leaves only Pi's own cleanup.",
36
- currentValue: config.enabled ? "On" : "Off",
37
- values: ["On", "Off"],
38
- },
39
- {
40
- id: "threshold",
41
- label: "Clean up when the context is",
42
- description:
43
- "Lower keeps answers faster and cheaper. Higher keeps more detail. At Pi's limit waits as long as Pi does.",
44
- currentValue: threshold,
45
- values: THRESHOLDS.includes(threshold)
46
- ? THRESHOLDS
47
- : [threshold, ...THRESHOLDS],
48
- },
49
- ];
50
- if (config.customOrder) return items;
51
- items.push({
52
- id: "strategy",
53
- label: "Cleanup method",
54
- description:
55
- "Summary notes: the agent writes notes ahead of time and they replace old messages. Trim first: shorten large old outputs, with no extra model call. Pi's summary: Pi's own summary.",
56
- currentValue: METHODS[config.strategy],
57
- values: Object.values(METHODS),
58
- });
59
- return items;
60
- }
61
-
62
- /** The JSON value to write for a panel choice. */
63
- export function settingValue(id: string, value: string): unknown {
64
- if (id === "enabled") return value === "On";
65
- if (id === "strategy")
66
- return Object.entries(METHODS).find(([, label]) => label === value)?.[0];
67
- if (value === PI_LIMIT) return "pi";
68
- const tokens = /^(\d+) tokens$/.exec(value);
69
- return tokens ? Number(tokens[1]) : value.replace(/ full$/, "");
70
- }
71
-
72
- /** One line for modes without the panel. */
73
- export function summaryText(config: ContextKitConfig, file: string): string {
74
- if (!config.enabled)
75
- return `pi-context-kit: automatic cleanup off. Settings: ${file}`;
76
- const at =
77
- config.threshold === "pi" ? "Pi's limit" : thresholdText(config.threshold);
78
- const method = config.customOrder
79
- ? `custom methods (${config.methodOrder.join(", ") || "none"})`
80
- : METHODS[config.strategy].replace(" (recommended)", "").toLowerCase();
81
- return `pi-context-kit: automatic cleanup at ${at}, with ${method}. Settings: ${file}`;
82
- }
83
-
84
- function thresholdText(threshold: Threshold): string {
85
- if (threshold === "pi") return PI_LIMIT;
86
- return "tokens" in threshold
87
- ? `${threshold.tokens} tokens`
88
- : `${threshold.percent}% full`;
89
- }