研究这个精简化方案billion-context-pi-lean

[ranxianglei]

https://github.com/kunkun9527/billion-context-pi-lean

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 研究完成。结论先行：方案成立，数据属实，引擎零改动；代价是放弃 acp_delegate + 一个对上游内部结构敏感的代理层。 以下是完整分析。

一、方案是什么

billion-context-pi-lean 不是 fork，是一个 265 行的门面（facade）：

lean index.ts (265 行, 直接以 TS 分发, 无构建步骤)
  └─ import { createAcpExtension } from "billion-context-pi"   // 精确锁定 0.1.52
       └─ 引擎 100% 原样运行（压缩/分层/nudge/overflow 自愈/throttle retry 全保留）

它用 Proxy 包裹传给上游的 pi API，只做三件事：

1. 拦截 registerTool：丢弃 acp_delegate 系列 3 个工具；把 decompress / search_context / acp_status 捕获进 Map 但不注册；给 compress 换上精简 schema（删字段描述、promptSnippet: ""、promptGuidelines: []）。
2. 拦截 on("before_agent_start")：替换上游唯一的 system prompt handler，把 15.8K 字符的完整 ACP prompt 换成 ~1.1K 的精简版。
3. 注册 acp_context 门面工具：{op: "decompress"|"search_context"|"acp_status"|"help", args}，用 typebox Check 按捕获的上游 schema 本地校验后转发执行；结果文本里的 search_context({...}) / run acp_status 等调用提示被正则改写为 acp_context({op:...})。

二、我实际验证过的（不是只看代码）

验证项	结果
lean 测试套件（npm ci && npm test）	✅ 10/10 通过，其中 2 个用例直接加载真实 billion-context-pi@0.1.52
固定开销测量（真实 0.1.52 dist + lean index.ts 实测）	✅ 22,647 → 2,861 字符（-87.4%），与 README 宣称的 22,645→2,859 吻合。delegate 开启（默认体验）时上游是 30,097 字符 ≈ 7.5K tokens/次调用，lean 省 ~90.5%
跨 typebox 版本校验（lean 1.3.7 vs dist 内联打包的 1.3.8）	✅ 实测 Check 正常工作（TypeBox 1.x schema 是纯 JSON，无 per-instance Kind symbol，版本漂移安全）
Pi 能否加载 TS 扩展	✅ pi-coding-agent 用 jiti 加载扩展（tryNative 关闭，所有 import 走 jiti），pi.extensions: ["./index.ts"] 可行
pi install git: 是否装依赖	✅ 源码确认：clone 后检测到 package.json 即执行 npm install
上游是否只有一个 before_agent_start	✅ 当前是（src/index.ts:372），lean 的替换逻辑干净
精简 prompt 会不会丢分层压缩规则	✅ 不会全丢：acp-kernel 的 nudge 文本（gentle/emergency/T2/T3）内联注入 howToCompressRules / tier2DistillRules / tier3CondenseRules——规则在触发时按需送达
compress 错误信息里的 run acp_status 提示	✅ 会经过 lean 的 wrapCompress 改写为门面调用

三、风险与局限

1. 代理层对上游内部结构敏感（最大风险）。lean 硬编码了工具名、"上游只有一个 before_agent_start handler"、delegate 在 session_start 惰性注册等假设。当前靠精确 pin 0.1.52 控制住了；但将来 bump pin 时，上游若重构（比如新增第二个 before_agent_start handler），lean 会静默丢失该 handler。这是 fork-free 方案的固有代价。
2. 用户 acp.json 可绕过 pin：reloadConfig 是 applyUserConfig(factoryAdapter, user)，autoUpdate 是用户可设 key（src/user-config.ts:56）。若用户全局 acp.json 里写了 autoUpdate: true（为上游装的），lean 的 autoUpdate: false 会被覆盖，自动更新器可能把 0.1.52 升掉。小概率但真实。
3. acp_delegate 完全禁用（上游 1,242 行的功能）。需要委派的用户得另装扩展，与 lean 共存时有重复注册冲突风险（lean 会丢弃 delegate 工具，但上游 delegate 的 system prompt 段也被 lean 整体替换掉了——行为上自洽，只是功能没了）。
4. 常驻 prompt 变薄 = 指导变少：KEEP/REF marker 用法、WHEN TO/NOT TO COMPRESS 清单、PRIORITY 排序这些细节不再常驻。nudge 时内联注入补回了一部分，但摘要质量是否下降没有实测数据（README 也承认这点）。
5. rewriteText 正则只处理单行 {...} 调用形态，多行 JSON 参数不会被改写（模型仍能看到原始工具名，只是门面工具没注册——模型最多困惑，不会坏）。
6. 工程成熟度：2 个 commit、0 star、无 release、单一维护者；无真实 Pi 会话的 e2e 测试（只有 mock pi + 真实上游注册级测试）；decorateWithCollapsedDisplay 依赖作者本地的 pi-collapsed-tools 项目（可选，缺失时 no-op，但 TUI 折叠展示是本地生态功能）。

四、收益怎么算

• 省的是每次 LLM 调用的固定开销（system prompt + 工具 schema 每次都发）：delegate 关闭时 ~5.7K→0.7K 字符（约 5K tokens），delegate 开启时 ~7.5K→0.7K。
• 有 prompt caching 的供应商（如 Anthropic）：稳定前缀走缓存读，边际成本约为列表价 10%，实际省费打折。
• 无缓存 / 小窗口模型：收益全额兑现——窗口预算每轮多出 ~5-7K tokens，注意力也更集中在任务内容上。长会话 + 小窗口 + 无缓存场景收益最大。
• 引擎能力零损失：分层压缩、nudge、overflow 自愈、throttle retry、guardrails、/acp 命令全部保留。

五、建议

1. 值得试，尤其长会话 + 小上下文窗口模型 + 无 prompt caching 的场景。装法就是 README 那两行（pi install git:... + 加 pi.extensions）。
2. 若想让这个思路进主仓库，比 fork 更稳的路径是在上游做可选模式（比如 lean: true 配置项）：上游自己注册精简 prompt + acp_context 门面，不需要 Proxy 拦截，没有"静默丢失 handler"的脆弱性，pin 漂移也不存在。lean 仓库验证了需求（工具合并 + prompt 精简能省 ~90% 固定开销），可以作为上游实现的参照。
3. 若作者继续维护 lean，建议补：真实 Pi 会话 e2e 测试、pin bump 时的上游契约检查（工具名/handler 数量的启动期断言，失败 loudly 而不是静默降级）。

[ranxianglei]

看下如果我们支持自定义提示词 是否可以不改代码的情况下有一个 lean 模式呢
只考虑省 token

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 查完了，先说结论：自定义提示词其实已经支持了（不用新开发），但纯配置只能做到 -43%，到不了 lean facade 的 -87%，而且有个质量坑。 以下是实测数据。

一、现状：prompts 覆盖已经是可用功能

~/.pi/acp.json（或项目级 .pi/acp.json）里：

{
  "prompts": {
    "compressPhilosophy": "...",
    "howToCompressRules": "...",
    "tier2DistillRules": "...",
    "tier3CondenseRules": "..."
  },
  "acknowledgePromptsRisk": true
}

acknowledgePromptsRisk: true 是必填闸门（src/user-config.ts:20, src/index.ts:103 → acp-kernel resolvePrompts）。session_start 时生效。

二、实测：纯配置 lean 能省多少

用真实 0.1.52 dist 跑了两组（delegate 关闭，完整 session 生命周期）：

模式	system prompt	tool metadata	固定总开销	降幅
默认	15,803	6,844	22,647 字符 (≈5.7K tokens/次)	—
4 个 prompt 字段全缩成一行	6,157	6,844	13,001 字符 (≈3.2K tokens/次)	-42.6%
lean facade（对照）	1,473	1,388	2,861 字符 (≈0.7K tokens/次)	-87.4%

省不掉的 57% 分两块，都不在配置的管辖范围内：

1. 静态骨架 6,157 字符：ACP TAGS、TOOLS（5 个工具的用法说明）、WHEN TO/NOT TO COMPRESS、MULTI-TIER、CONTEXT BREAKDOWN、PROVIDER THROTTLE RETRY 这些段落硬编码在 src/system-prompt.ts，不属于 Prompts 接口。acp-kernel 的 prompts.d.ts 里明确写了：surface 层文本"intentionally NOT part of this interface — it is owned by the adapter or a later prompt-set format layer"——即内核设计时就把这层留给了 adapter 侧的 prompt-set 机制，目前这个机制还没实现。
2. 工具元数据 6,844 字符：TypeBox schema 的字段描述 + promptSnippet + promptGuidelines（Pi 会把它注入 system prompt）硬编码在各 tool 源文件里，配置碰不到。

三、关键坑：配置缩 prompt = nudge 也一起缩

4 个 prompt 字段是 system prompt 和 nudge 共用的同一个对象（src/index.ts:267 renderNudgeText(turn.nudge, runtime.prompts)）。你把 howToCompressRules 缩成一行，每次 nudge 注入的规则也变成一行——摘要质量在真正写摘要的时刻降级。这正是 acknowledgePromptsRisk 闸门警告的事（kernel 文档原话：这些规则"tuned over months of production use and are quality-critical"）。

而 lean facade 的做法刚好相反：常驻 prompt 瘦身，nudge 保留完整规则（它不碰 kernel prompts，nudge 照常内联完整 4,618 字符的 howToCompressRules）——规则在需要的时候才送达，平时不占 token。这个"常驻瘦 + nudge 全"的组合用现有配置表达不出来，因为两者共享同一个 prompts 对象。

所以纯配置路线本质是"降质量省 token"，不是 lean 那种"按需送达省 token"。

四、建议

1. 只考虑省 token、坚持不改代码：现在就能用上面的 acp.json 配置，省 ~2.4K tokens/次调用（-43%），代价是摘要质量下降（nudge 规则同步缩水）。可以当临时手段，不建议当"lean 模式"推广。

2. 想要 facade 的效果又不想要 proxy 脆弱性：在 adapter 侧加一个小改动就够了——

   • promptSet: "lean"（或完整模板覆盖）：换掉静态骨架，对应 kernel 文档预留的 "prompt-set format" 层；
   • compactToolDocs: true：压缩工具描述、清空 promptSnippet/promptGuidelines；
   • kernel prompts 保持默认（nudge 保留完整规则）；
   • 工具合并（acp_context）可选——不做的话预计 ~-80%，做了 ~-87%，都接近 facade 水平，且没有"静默丢失 handler"的代理风险。

   改动量估计 300-500 行，全在 billion-context-pi 侧，acp-kernel 不用动。

3. 如果目标是"零代码 + 最大省 token"，答案就是方案 1 的 -43%；如果接受一点 adapter 代码，方案 2 能到 -80~87% 且不牺牲 nudge 质量。

[ranxianglei]

我理解这个是配置缺失？是不是应该允许所有提示词自定义 包括工具的？
https://github.com/ranxianglei/billion-context 可能也有类似问题 需要你分析

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 两个仓库都分析完了。是的，这是配置缺失，而且 billion-context（proxy）有完全相同的缺口——因为两边的提示词都来自同一个 acp-kernel 0.0.46。另外挖到一个意外发现：pi adapter 的常驻 prompt 里有一段是 nudge 已经会送达的重复内容，可以零成本砍掉。

一、billion-context（proxy）的分析

它注入的模型可见面（每个请求都发）：

组成	大小	来源	可配置？
system prompt（buildCompressSystemPrompt）	7,681 字符（hybrid 7,172 / text 7,589）	acp-kernel	部分（仅 4 个规则字段）
工具 schema（4 个 ACP 工具）	Anthropic 1,999 / OpenAI 2,164 / Responses 2,112 字符	acp-kernel（compress-tool.ts 纯 re-export）	❌
合计	≈9.7K 字符 ≈ 2.4K tokens/请求

配置面（src/compress-settings.ts:43-94）：

• prompts 覆盖：和 pi 版完全相同的 4 个 kernel 字段 + acknowledgePromptsRisk 闸门，且做成三级级联（global → provider → model，子字段级 merge）
• 工具侧唯一的开关：compress.injectTool: false（全有或全无，关掉连 prompt 一起没了）
• plugin 模式（pi/omp/opencode 原生插件）：工具 schema 由 proxy 的 GET /__bili/plugin/manifest 下发——同样不可定制

实测纯配置 lean（4 字段缩成一行）：9,680 → 4,650 字符 = -52%（比 pi 版的 -42.6% 更有效，因为 kernel 自己的骨架本来就瘦，见下）。

二、关键结构差异：kernel 的 prompt 设计本来就是"lean 的"

实测对比两个 standing prompt（都是默认 prompts）：

	pi adapter buildAcpSystemPrompt	kernel buildCompressSystemPrompt（proxy 用）
总大小	15,803	7,681
含 compressPhilosophy + howToCompressRules	✅	✅
含 tier2/tier3 规则（4,734 字符）	✅ 在常驻 prompt 里	❌ 不在（T2/T3 nudge 触发时内联送达）
静态骨架	~5,921（WHEN TO COMPRESS / MULTI-TIER / PHILOSOPHY OF DECOMPRESS / CONTEXT BREAKDOWN / THROTTLE RETRY 等 9 段）	~2,411（只有 ACP TAGS / TOOLS / COMPRESSION SUMMARIES / HOW TO COMPRESS 4 段）

也就是说：proxy 路线的 prompt 天然比 pi 路线瘦 2 倍，因为 kernel 的设计哲学就是"规则按需送达（nudge 时注入），常驻只留最小骨架"——这正是 lean facade 想达到的效果，kernel 自己在 prompt 层面已经做了一半。

三、回答"是否应该允许所有提示词自定义（包括工具的）"

应该，但形态不应该是"每个字符串一个文本框"，而是 kernel 文档里已经预留的 prompt-set 层。acp-kernel prompts.d.ts 原文把提示词分成两类：

load-bearing（4 条规则）：已可覆盖，需 acknowledgeRisk 闸门 —— 保持现状
surface（骨架段落 + 工具描述）："intentionally NOT part of this interface — it is owned by the adapter or a later 'prompt-set format' layer and is safe to customize freely"

这个 "prompt-set format layer" 从未实现——这就是缺口的准确定义。建议的设计：

1. kernel 层加 promptSet：buildSystemPrompt(prompts, set)，presets 含 "full"（现状）/ "lean"（kernel 骨架 + 按需规则）/ 自定义模板（命名 slot：{{tags}} {{tools}} {{howToCompress}}…）。放在 kernel 是因为 pi 和 proxy 两个 adapter 消费同一组 builder，kernel 实现一次两边受益，也符合文档预留。
2. 工具提示词可覆盖：tools: { compress: { description, snippet, guidelines } }（pi 侧）/ 工具 schema description（proxy 侧）。工具描述属于 surface 类，不需要风险闸门。
3. 风险闸门只保留在 load-bearing 4 字段上。

四、意外发现：pi adapter 可以零配置、零质量损失先省 1.2K tokens/次

既然 T2/T3 nudge 本来就内联注入完整的 tier2/tier3 规则（之前已验证），pi 常驻 prompt 里那 4,734 字符的 tier 规则段是纯重复。把这两段从 buildAcpSystemPrompt 挪出去（nudge 通道保留）：

• 22,647 → 17,913 字符（-21%），不需要用户配置任何东西，摘要质量零损失（规则在真正触发 T2/T3 的时刻照样送达）
• 这是"不改配置面就能拿到的 lean"，比让用户自己缩 prompt（还要承担 nudge 同步缩水的风险）好得多

proxy 侧同理已天然如此，不用动。

五、建议的落地顺序

1. pi adapter 小 PR：standing prompt 移除 tier2/tier3 重复段（~20 行改动 + 测试），立刻 -21%
2. acp-kernel issue/PR：prompt-set 层（promptSet + 工具描述覆盖），两个 adapter 各自接线
3. 之后 lean facade 仓库的历史使命就完成了——它的 -87% 效果可以用"promptSet: lean + 工具合并"在主仓库原生实现，没有 proxy 代理层的脆弱性

需要的话我可以直接把 1 做了（开 PR），2 我可以先在 acp-kernel 提 issue 把设计写清楚。

[ranxianglei]

pi adapter 小 PR：standing prompt 移除 tier2/tier3 重复段（~20 行改动 + 测试），立刻 -21%
你是说里面有重复内容还是移除 2 和 3 的常驻系统提示词？

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 是后者：把 TIER 2 / TIER 3 规则段从常驻 system prompt 里移除（nudge 通道原样保留）。prompt 内部本身没有重复段落——"重复"是指同一段规则文本走了两条投递通道：

通道 1（常驻，每次 LLM 调用都发）：pi 的 standing prompt 里 MULTI-TIER COMPRESSION 段共 5,220 字符，内嵌完整的 tier2DistillRules（2,713 字符）+ tier3CondenseRules（2,021 字符）原文。

通道 2（按需，仅 T2/T3 触发时发）：acp-kernel 的 renderNudgeText（dist/chunk-MWXUJVMN.js:308）在 T2/T3 nudge 消息里逐字注入同一份 prompts.tier2DistillRules / prompts.tier3CondenseRules，还带 howToCompressRules、目标 block 列表和调用示例——nudge 文本是自包含的。

所以现状是：

• 绝大多数普通调用：tier 规则躺在 system prompt 里完全用不上（模型不会自发做 tier 压缩，T2/T3 永远是 nudge 触发的）
• T2/T3 触发那一刻：模型同时在 system prompt 和 nudge 里各看到一份完整规则

PR 做的事：只删通道 1 里的规则原文，MULTI-TIER 段保留开头 2-3 行机制说明 + 一句指针（"tier 2/3 规则在触发时由 nudge 送达"）。通道 2 一行不动。

为什么只砍 tier 规则、不砍 howToCompressRules：T1 压缩是模型自发做的（standing prompt 的 WHEN TO COMPRESS 引导它主动压，不等 nudge），所以 howToCompress 规则必须常驻；而 T2/T3 压缩必然伴随 nudge 出现，规则在需要的那一刻一定有。这条分界线恰好就是 kernel 自己的设计——buildCompressSystemPrompt（proxy 用的那个）只含 philosophy + howToCompress，本来就不含 tier 规则，实测 7,681 字符 vs pi 的 15,803。pi adapter 只是偏离了 kernel 的投递哲学，这个 PR 就是拉齐。

数字：22,647 → ~17,780 字符（-21.5%，≈1.2K tokens/次调用），摘要质量零损失（T2/T3 时刻规则照样完整送达）。改动集中在 src/system-prompt.ts 一处 + 测试断言"standing prompt 不含 tier 规则原文、含指针"。

要我现在开这个 PR 吗？

[ranxianglei]

否决 这些会导致模型无法自主进行 t2t3 压缩
你还是专心考虑如何让所有提示词可配置 麻烦梳理一下

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 收到，tier 规则常驻不动（默认行为保持现状，模型自主 T2/T3 的能力不受影响）。下面是"所有提示词可配置"的完整梳理。

一、模型可见提示词面完整清单（实测大小）

A. 常驻 system prompt（15,803 字符/次调用）

#	段落	大小	现状
A1	compressPhilosophy	530	✅ 已可配（prompts + 风险闸门）
A2	ACP TAGS	455	❌ 硬编码 src/system-prompt.ts:9
A3	COMPRESSION SUMMARIES IN CONTEXT	1,115	❌ 硬编码 :13-18
A4	TOOLS（4 工具说明）	~1,480	❌ 硬编码 :22-27
A5	WHEN TO COMPRESS	677	❌ 硬编码 :33-39
A6	WHEN NOT TO COMPRESS	399	❌ 硬编码 :43-45
A7	howToCompressRules	4,620	✅ 已可配
A8	MULTI-TIER 引导段	482	❌ 硬编码 :51-53
A9	tier2DistillRules	2,715	✅ 已可配
A10	tier3CondenseRules	2,023	✅ 已可配
A11	THE PHILOSOPHY OF DECOMPRESS	440	❌ 硬编码 :61
A12	CONTEXT BREAKDOWN	200	❌ 硬编码 :65
A13	PROVIDER THROTTLE RETRY	640	❌ 硬编码 :69-70

小计：已可配 9,888（4 个 kernel 规则字段）/ 硬编码 5,915（9 个段落）

B. 工具提示词面（6,844 字符/次调用，随 tools 参数发送）

工具	description	参数 schema 描述	promptSnippet	promptGuidelines
compress	243	1,495	77	348
decompress	655	928	157	407
search_context	212	246	39	299
acp_status	232	831	73	185

全部 ❌ 硬编码在各 tool 源文件（TypeBox schema + Pi 的 snippet/guidelines 字段）。

C. Delegate prompt（ACP_DELEGATE_PROMPT，~1,850 字符，仅 delegate 开启时）❌ 硬编码 src/system-prompt.ts:74-86

D. Nudge 文本（每次 nudge 注入，kernel 生成）：脚手架（触发行/breakdown/示例行）❌ 在 acp-kernel 内部；注入的规则部分 ✅ 走 A1/A7/A9/A10（已可配）。D 的脚手架要可配需要动 kernel（见第五节）。

二、设计：三层配置（acp.json，全部走现有 ~/.pi/acp.json / 项目级覆盖机制）

{
  // 第 1 层：已有，不动（load-bearing，保留风险闸门）
  "prompts": { "compressPhilosophy": "...", "howToCompressRules": "...", "tier2DistillRules": "...", "tier3CondenseRules": "..." },
  "acknowledgePromptsRisk": true,

  // 第 2 层：新增 —— system prompt 段落级覆盖（surface，免闸门）
  "promptSections": {
    "acpTags": "..." | null,            // string=整段替换, null=删除该段, 缺省=内置默认
    "summariesInContext": "..." | null,
    "tools": "..." | null,
    "whenToCompress": "..." | null,
    "whenNotToCompress": "..." | null,
    "multiTierIntro": "..." | null,
    "decompressPhilosophy": "..." | null,
    "contextBreakdown": "..." | null,
    "throttleRetry": "..." | null
  },

  // 第 3 层：新增 —— 工具提示词覆盖（surface，免闸门）
  "toolPrompts": {
    "compress": {
      "description": "...",
      "paramDescriptions": { "content": "...", "topic": "..." },
      "promptSnippet": "" ,              // 空串=清空
      "promptGuidelines": []             // 空数组=清空
    },
    "decompress": { "...": "..." },
    "searchContext": { "...": "..." },
    "acpStatus": { "...": "..." }
  },

  // 第 4 层：新增 —— delegate prompt 覆盖
  "delegatePrompt": "..." | null
}

语义：段落/字段级 merge，string 整段替换、null 删除、缺省用内置默认。不引入"整段模板字符串"（那是 v2 的事，见下）。

三、一致性不变量（文档里必须写死，否则用户一改就坏）

1. 工具名不可配：kernel 的 nudge 文本硬编码了 compress({...}) 示例和错误信息里的 run acp_status（chunk-MWXUJVMN.js:308 等）。只允许改描述，不允许改名——改名会让 nudge 指向不存在的工具。
2. ACP TAGS 段是"表面但半承重"：它描述的是 adapter 实际注入的标签格式。改文案可以，但必须继续正确描述 <acp>/<dcp-message-id> 标签和 mNNNNN 引用规则，否则模型提取不到 ref，压缩直接失效。文档标注清楚即可，不加闸门（用户显式配置=显式担责，与 kernel 对 surface 的分类一致）。
3. 改描述不改行为：CONTEXT BREAKDOWN / THROTTLE RETRY 等段描述的是系统实际行为，覆盖文案不会改变行为本身——文案与行为脱节的风险由用户承担。
4. promptSections.tools 与 toolPrompts 可能互相矛盾（两处都在跟模型描述工具）：允许，但文档提示两者应保持一致。

四、实施计划（全部在 billion-context-pi 内，acp-kernel 零改动）

1. src/user-config.ts：UserAcpConfig + KNOWN 增加 promptSections / toolPrompts / delegatePrompt 三个 key
2. src/config.ts：AdapterConfig 加对应字段
3. src/system-prompt.ts：把 9 个静态段抽成 DEFAULT_SECTIONS 常量表；buildAcpSystemPrompt(prompts, sections?) 按 sections?.x ?? default（null 跳过）拼装
4. 四个 tool 文件：注册时应用 toolPrompts 覆盖（description / 参数描述克隆 schema / snippet / guidelines）
5. delegate 接线：adapter.delegatePrompt ?? ACP_DELEGATE_PROMPT
6. 测试：每段替换/删除/缺省回落；工具四字段覆盖；空串清空 snippet；默认构建与现状逐字节一致（防回归）
7. 文档：README/CONFIGURATION 段落 + 不变量说明

估计 ~300 行改动 + ~150 行测试，单 PR。

五、v2（跨仓库，可选）

• nudge 脚手架可配（D 面）：触发行、示例行、breakdown 格式在 kernel 内部，需要 acp-kernel 加 prompt-set 层（其 prompts.d.ts 已预留 "prompt-set format layer" 的位置）。pi 和 proxy（billion-context）两边同时受益。
• 整段模板模式：systemPromptTemplate + {{slot}} 占位符，给需要控制段落顺序/增删的极端场景。v1 的段落级覆盖能覆盖 95% 需求，模板留到 v2。

六、这套配置能达到的效果

• 保持默认：与现状逐字节一致（零风险）
• 用户自配 lean：9 段 + 4 规则 + 工具面全部可缩 → 常驻开销可从 15,803+6,844 压到 ~2-3K 字符，不需要改代码、不需要 proxy 门面，且想保留 tier 规则就保留（自主 T2/T3 能力不丢）
• 非英文/小模型调优：kernel 文档本来就提到这是 prompts 覆盖的主要用途之一（issue log: model identity on session start and turn lines #156），这套设计把它从"4 个规则字段"扩展到全部提示词面

确认方案的话我就按第四节的计划开 PR。

[ranxianglei]

两个项目 pi 和 billion-context 版本是否可以统一 包括配置方式

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 可以统一，而且架构上"统一"的正确位置是 acp-kernel，不是两个 adapter 之间互相看齐。现状和方案如下：

现状（已核实）

	billion-context-pi	billion-context (proxy)
版本	0.1.52	0.1.63（独立发布节奏，已漂移 11 个版本）
acp-kernel	0.0.46（精确 pin）	0.0.46（精确 pin）
配置文件	~/.pi/acp.json + 项目 .pi/acp.json（2 级）	bili 自己的 config（providers 按 URL 路由，1 个文件）
compress 级联	全局→provider→model，per-field 最深优先（src/config.ts mergeCompress/resolveCompress）	同样的 3 级级联、同样的语义（src/compress-settings.ts）——两份独立拷贝
prompts 覆盖	4 字段 + acknowledgePromptsRisk 闸门（kernel resolvePrompts）	同样的 4 字段 + 同样的闸门，但多了 provider/model 两级级联

关键事实：两个项目真正的共享契约已经是 acp-kernel——同一个精确版本 pin、同一个 Config/Prompts 类型、同一套压缩引擎。adapter 版本号追踪的是各自壳层的功能（Pi extension API vs HTTP proxy），不是引擎。

版本统一：可以，但建议"功能对齐发布"而非全量 lockstep

• 全量 lockstep（两个包永远同版本号、同时发）：好处是一个版本号=一套功能集，用户好记；代价是 pi 的单个 hotfix 也要拖着 proxy 发一次（反之亦然），每次 release PR ×2 仓库 ×2 版本号，耦合成本高。
• 建议：功能对齐发布——跨切面功能（比如 prompt 可配置化、未来的 prompt-set 层）落地时两个仓库同一天、同版本号发布，并在 README 维护一张"版本 ↔ kernel 版本 ↔ 功能集"对照表；各自的 patch 修复保持独立节奏。兼容性轴对外声明为 kernel 版本（"0.0.46 内核的行为在两个 adapter 上完全一致"），这已经是事实，只是没写出来。

配置统一：把共享 schema + 解析逻辑下沉到 acp-kernel（单一事实源）

现在的问题是同一套语义有两份拷贝（compress 级联、prompts 闸门），未来每加一个共享配置项就要在两个仓库各写一遍、各测一遍。正确做法：

Phase 1 — kernel 收编共享配置层（acp-kernel 新 PR）：

• CompressSettings 取两仓库字段的并集（proxy 多 modelContextLimit: number|string，pi 多 nudgeGrowthTokens 命名差异对齐），mergeCompress/resolveCompress 只留 kernel 一份实现
• Prompts + resolvePrompts 已在 kernel ✓
• 新增：surface 提示词覆盖的共享类型——promptSections（各 adapter 的段落键做并集，adapter 只应用自己认识的键、忽略其余）+ 工具提示词基础覆盖（description/paramDescriptions；promptSnippet/promptGuidelines 是 Pi ExtensionAPI 概念，留 pi 侧）
• 可选：通用 loadAcpConfig(cwd, dirName) 两级文件加载器（pi 用 .pi，proxy 可复用也可保留自己的文件位置）

Phase 2 — 两个 adapter 删除本地拷贝，import kernel 的类型和解析函数。之后共享配置键在两个项目里字节级同名同义：

compress / prompts / acknowledgePromptsRisk / promptSections / toolPrompts

adapter 特有键各自保留：pi（autoUpdate/delegate/displayUsage/toolBashDefaultTimeout/toolOutputMaxBytes/delegatePrompt）、proxy（providers 路由/injectTool/compressProtocol/监听与鉴权）。

不能统一的部分（本质差异，不强求）：

• 配置文件位置：proxy 需要 URL 路由表，pi 不需要——文件不同，但共享键的 schema 相同
• 级联键空间：pi 的 provider 级按 provider 名（anthropic），proxy 按上游 URL 前缀——merge 逻辑统一，键空间各自保留

与手头 PR 的关系

我正在实现 pi 侧"所有提示词可配置"（promptSections/toolPrompts/delegatePrompt）。设计时已按"未来上提 kernel"考虑：类型定义干净、不依赖 pi 私有概念，Phase 1 时直接搬进 kernel 即可，pi 侧只改 import。所以顺序是：pi PR 先行（本周可用）→ kernel 配置层 PR → proxy 跟进，每一步都可独立发布、独立回滚。

确认的话：pi 这个 PR 我继续做完；版本对齐策略（lockstep vs 功能对齐）你拍板后我写进两个仓库的 README/AGENTS.md。

[ranxianglei]

先搞内核 收编配置层 然后在内核实现 最终改两个仓库适配 开始执行

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 收到，按「内核先行」执行。计划：

第 1 步 — acp-kernel（关键路径）

• 收编配置层到内核：通用类型（ToolPromptOverrides、section 三态覆盖 string=替换 | null=移除 | 缺省=默认）+ 实现（applyToolOverrides/schema 描述深克隆、通用 section 组装器）
• 内核自己的 buildCompressSystemPrompt 重构成命名 section 并支持覆盖；内核的 compress 工具支持 toolPrompts
• 新配置键：promptSections、toolPrompts（与现有 prompts 4 字段并存，无风险门槛——surface 文本按内核分类可自由定制）
• feature 分支 + PR（version 不动，等人工合并后走 release 分支发版）

第 2 步 — 两个仓库适配（等内核 npm 发布后）

• billion-context-pi：删掉本地的 tool-prompts 实现，改从内核导入；9 个 section + delegatePrompt 用内核通用机制（delegate 是 pi 特有，键留在 pi）
• billion-context（proxy）：同样接入 promptSections/toolPrompts，配置键与 pi 对齐

说明

• pi 适配器上的原型实现已完成（typecheck 通过），作为参考实现，内核落地后重构为导入
• 本轮范围限提示词/工具 surface 配置层；CompressSettings（compress 行为参数）两仓库合并是后续单独一步
• 顺序约束：内核先合并、npm 可 npm view 到新版本后，两个适配器的 PR 才能过 CI（npm ci 装精确版本）

现在开始 clone acp-kernel 并读它的 AGENTS.md。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 内核已开工，PR 已开：ranxianglei/acp-kernel#169（分支 2026-08-30_surface-config）

收编到内核的内容（新模块 src/surface-config.ts，barrel 导出）：

API	作用
applySectionOverrides(sections, overrides?)	系统提示词分区三级语义：string=整段替换（含标题）、null=删除、缺省=默认；未知 key 忽略
buildCompressSystemPrompt / Text / Hybrid(prompts?, sections?)	三个 standing-prompt builder 增加可选第二参数 CompressPromptSections（6 个 key：acpTags / tools / summariesInContext / textProtocol / textTools / functionTools）
cloneWithDescriptions(schema, paramDescriptions)	深克隆 JSON tool schema，按属性名替换任意深度嵌套的参数描述；不改动原对象
applyAcpToolOverrides(tools, overrides?)	按工具覆盖 description + paramDescriptions，三种 wire 形状全支持（anthropic input_schema / openai function.parameters / responses 平铺 parameters）

设计边界（按 DESIGN-prompts.md 的 load-bearing / surface 分类）：

• 这层只管 surface 文本（分区文案、工具描述、参数描述）→ 无风险门禁
• 4 条 load-bearing 规则仍走 resolvePrompts + acknowledgeRisk，不动
• 工具名字不可改（nudge 和内核错误消息硬编码 compress(...) / run acp_status），只动人类可读文本

验证：

• ✅ 字节级回归：重构后 3 个 builder 与已发布 0.0.46 dist 输出逐字节一致（fixture 已提交：function 7,681 / text 7,589 / hybrid 7,172 字节）
• ✅ 新增 16 个测试（分区替换/删除、跨 builder key 忽略、嵌套参数描述、不改动常量证明、3 种 wire 形状）
• ✅ typecheck + 全量 npm test 556/556（原 540）+ build
• ✅ 文档：README 新增 "Prompt/tool surface configuration" 节、AGENTS.md 模块图、DESIGN-prompts.md 标记 Layer 1 shipped 并重新编号

下一步（等 #169 合并 + CI 发布 npm 后）：

1. pi 适配：把我已写好的 pi 侧特性代码（本地未提交）改为引用内核的 surface-config——删掉本地 cloneWithDescriptions，分区走内核 applySectionOverrides，PiToolPromptOverrides 继承内核 ToolPromptOverrides 并保留 Pi 特有的 promptSnippet/promptGuidelines，acp-kernel 精确升版 → 开 pi PR
2. proxy 适配（billion-context）：config 增加 promptSections / toolPrompts 键，接进 3 个 builder + applyAcpToolOverrides → 开 proxy PR

提醒：内核 AGENTS.md 要求合并前至少 2 个独立 agent review，PR 里已注明；另外 format:check 在干净 master 上本来就有 91 个文件不过（prettier 版本漂移，CI 不卡这项），本次没动以保持 PR 聚焦。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 三个仓库全部执行完毕，按「内核收编 → 两仓库适配」的顺序：

1️⃣ acp-kernel — PR #169（已开，等 review/merge/publish）

ranxianglei/acp-kernel#169

配置层正式收编进内核，新增 surface-config 模块（barrel 导出）：

• applySectionOverrides(sections, overrides) — 分区覆盖统一语义：string = 替换 / null = 删除 / 省略 = 默认，未知 key 忽略、不改原数组
• cloneWithDescriptions(schema, paramDescriptions) — 按属性名在任意嵌套深度替换 schema 描述（深拷贝、不改原对象）
• applyAcpToolOverrides(tools, overrides) — 同时处理三种 wire 形态（anthropic input_schema / openai function 包装 / responses 扁平）
• 三个 prompt builder 增加可选第二参数 CompressPromptSections，签名向后兼容

byte-identity 保证：三个 builder 的默认输出与已发布 0.0.46 逐字节相等（7681/7589/7172 字符，fixtures 进 tests/）。556/556 测试通过（+16 新测试）。文档同步：README 新章节、AGENTS.md 模块表、DESIGN-prompts.md 把 surface 层标为 Layer 1 shipped。

2️⃣ billion-context-pi — 分支 2026-08-30_prompt-config（本地已提交，待内核发布后开 PR）

三个新 acp.json 键（均无风险门禁，surface 文本属呈现层）：

• promptSections — 9 个命名分区（acpTags / summariesInContext / tools / whenToCompress / whenNotToCompress / multiTierIntro / decompressPhilosophy / contextBreakdown / throttleRetry）
• toolPrompts — 4 个工具 × {description, paramDescriptions, promptSnippet, promptGuidelines}
• delegatePrompt — string 替换 / null 删除 delegate 通知分区

本地实现已改为委托内核（applySectionOverrides + cloneWithDescriptions 从 acp-kernel import，Pi 只保留 promptSnippet/promptGuidelines 两个 Pi 特有字段）。默认输出与 0.1.52 逐字节相等（fixture 回归测试）。439/439 测试通过，CONFIGURATION.md 中英双语已补全。

3️⃣ billion-context（proxy）— 分支 2026-08-30_surface-config（本地已提交，待内核发布后开 PR）

• promptSections + toolPrompts 两个新配置键（无 delegate，proxy 没有该功能）
• 三级合并（global → provider → model）沿用现有 mergeCompress 风格
• 4 个 builder 调用点传入 sections；4 个 ACP_TOOLS_* 消费点（含 plugin manifest 端点）套 applyAcpToolOverrides
• 552/552 测试通过

为什么现在还不能开两个 adapter PR

跨仓库发布规则：adapter CI 跑 npm ci 会装 package.json 里 pin 的 acp-kernel 精确版本，内核没上 npm 之前 bump 会让 CI 在 install 阶段直接挂。所以流程是：

1. PR 报错 "Too many tokens, please wait before trying again." + Provider finish_reason: error_finish — 原因是 provider 侧 token 限流（非上下文超长/压缩失效） #169 review + merge（内核 AGENTS.md 要求至少 2 个 agent review，PR 里已注明）
2. CI publish 后 npm view acp-kernel version 确认 0.0.47 上线
3. 两个 adapter 各自 bump pin（0.0.46 → 0.0.47 精确版本）+ 刷新 lockfile + 重跑 typecheck/test/build
4. 开 PR、回 issue

内核 merge 后告诉我一声，我立刻完成 3-4 步。