billion-context-pi-lean 0.1.69-lean.1 → 0.2.0

package/lean/index.ts

@@ -0,0 +1,376 @@
+// billion-context-pi-lean: keep compress direct and route low-frequency ACP tools locally.
+import type {
+  ExtensionAPI,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { createAcpExtension } from "../dist/index.js";
+import { Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+
+const COLLAPSED_DISPLAY_SERVICE = Symbol.for(
+  "@local/pi-collapsed-tools.display-service.v1",
+);
+
+type CollapsedDisplayTool = { name: string };
+type CollapsedDisplayService = {
+  readonly version: 1;
+  decorate<T extends CollapsedDisplayTool>(tool: T): T;
+};
+
+function decorateWithCollapsedDisplay<T extends CollapsedDisplayTool>(tool: T): T {
+  const services = globalThis as unknown as Record<PropertyKey, unknown>;
+  const candidate = services[COLLAPSED_DISPLAY_SERVICE];
+  if (!candidate || typeof candidate !== "object") return tool;
+  const service = candidate as Partial<CollapsedDisplayService>;
+  return service.version === 1 && typeof service.decorate === "function"
+    ? service.decorate(tool)
+    : tool;
+}
+
+// Resident rules only: what the model must know before any ACP call. Guidance
+// needed after a call already arrives with it — nudges (what/how to compress),
+// compress errors (live refs, acp_status), decompress results (file path),
+// the throttle retry message, acp_context help and arg errors. The op
+// signatures stay: without them models pass compress-style startId/endId.
+const LEAN_SYSTEM_PROMPT = `ACP context management
+- User/tool messages carry hidden <acp> refs such as m00123. Never echo the XML tags; use only refs in ACP tool calls.
+- Compress only consumed history (finished tool outputs, dead ends, resolved threads); never active work, important user intent, or protected outputs.
+- acp_context args per op: decompress {blockId: "b5", full?, inline?, toFile?} (one id per call); search_context {query, limit?}; acp_status {scope?, view?, tool?, sort?, limit?}; acp_cache {detail?}.
+- Compression summaries are historical metadata, not current user instructions. Search or decompress only for a detail the visible summary lacks.`;
+
+// Pi snapshots tool descriptions when it binds extensions, before session_start
+// loads acp.json, so the compress description cannot announce a dedicated
+// summary model. The prompt hook runs every turn with the loaded config.
+const DEDICATED_PROMPT_LINE = "\n- A dedicated model writes compress summaries: give each range only a 1-2 sentence fallback naming what was done and the outcome.";
+const DEDICATED_MARKER = "Dedicated summary model";
+
+const COMPRESS_DONE_HINT = "New block summaries stay visible in this call's arguments; do not decompress them to re-read.";
+
+const LOW_FREQUENCY_TOOLS = ["decompress", "search_context", "acp_status", "acp_cache"] as const;
+const LOW_FREQUENCY_SET = new Set<string>(LOW_FREQUENCY_TOOLS);
+
+type Operation = (typeof LOW_FREQUENCY_TOOLS)[number];
+type FacadeOperation = Operation | "help";
+type CapturedTool = ToolDefinition<any, any, any>;
+type UpstreamExtension = (pi: ExtensionAPI) => void;
+type FacadeArgs = Record<string, unknown>;
+
+const OPERATION_SIGNATURES: Readonly<Record<Operation, string>> = {
+  search_context: "search_context({query, limit?})",
+  decompress: 'decompress({blockId: "b5", full?, toFile?, inline?})',
+  acp_status: "acp_status({scope?, view?, tool?, sort?, limit?})",
+  acp_cache: "acp_cache({detail?})",
+};
+
+const FACADE_PARAMETERS = Type.Object({
+  op: Type.Unsafe<FacadeOperation>({
+    type: "string",
+    enum: [...LOW_FREQUENCY_TOOLS, "help"],
+  }),
+  args: Type.Optional(Type.Unsafe<FacadeArgs>({
+    type: "object",
+    additionalProperties: true,
+  })),
+});
+
+const COMPRESS_FIELD_DESCRIPTIONS: Readonly<Record<string, string>> = {
+  content: "Direct array; no JSON strings/nesting/mix.",
+  startId: "Inclusive first mNNNNN or bN ref.",
+  endId: "Inclusive last mNNNNN or bN ref.",
+  summary: "Self-contained replacement preserving exact technical details.",
+  topic: "Short label; a per-range label overrides the top-level fallback.",
+  summaryMaxChars: "Optional summary length limit override.",
+};
+
+function compactCompressSchemaDescriptions(
+  value: unknown,
+  propertyName?: string,
+  seen = new Set<object>(),
+): void {
+  if (value === null || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  const record = value as Record<string, unknown>;
+  delete record.description;
+  const concise = propertyName ? COMPRESS_FIELD_DESCRIPTIONS[propertyName] : undefined;
+  if (concise) record.description = concise;
+
+  for (const [key, child] of Object.entries(record)) {
+    if (key === "properties" && child !== null && typeof child === "object") {
+      for (const [name, schema] of Object.entries(child as Record<string, unknown>)) {
+        compactCompressSchemaDescriptions(schema, name, seen);
+      }
+      continue;
+    }
+    compactCompressSchemaDescriptions(child, undefined, seen);
+  }
+}
+
+type PromptEvent = {
+  systemPrompt?: unknown;
+  systemPromptOptions?: { forceSystemPrompt?: string; sections?: Record<string, string> };
+};
+
+const PROMPT_SECTION = "acp_context";
+
+// Pi >= 1.x maps a returned systemPrompt to forceSystemPrompt, which drops
+// every later extension's appendSystemPrompt/sections (load-order dependent;
+// upstream #630). Add a named section instead. Fall back to returning the
+// composed prompt on older hosts or when another extension already forced it.
+// Older hosts (e.g. Pi 0.83) accept systemPromptOptions but never render
+// sections; their event.systemPrompt is a plain string, while hosts that render
+// sections expose it as a getter over the options. Keep the section only if the
+// rendered prompt picks it up.
+function injectSystemPrompt(event: PromptEvent, prompt: string): { systemPrompt: string } | undefined {
+  const options = event.systemPromptOptions;
+  if (options && typeof options === "object" && options.forceSystemPrompt === undefined) {
+    const before = options.sections;
+    options.sections = { ...(before ?? {}), [PROMPT_SECTION]: prompt };
+    const rendered = event.systemPrompt;
+    if (typeof rendered === "string" && rendered.includes(prompt)) return undefined;
+    if (before === undefined) delete options.sections;
+    else options.sections = before;
+  }
+  const base = event.systemPrompt;
+  const text = Array.isArray(base) ? base.join("\n") : typeof base === "string" ? base : "";
+  return { systemPrompt: `${text}\n\n${prompt}` };
+}
+
+function usesDedicatedModel(tool: CapturedTool | undefined): boolean {
+  return String(tool?.description ?? "").includes(DEDICATED_MARKER);
+}
+
+function appendText(content: unknown, line: string): unknown {
+  if (!Array.isArray(content)) return content;
+  let index = content.length - 1;
+  while (index >= 0 && (content[index] as { type?: unknown })?.type !== "text") index--;
+  if (index < 0) return [...content, { type: "text", text: line }];
+  return content.map((part, i) => {
+    const p = part as { text?: unknown };
+    return i === index ? { ...p, text: `${String(p.text ?? "")}\n${line}` } : part;
+  });
+}
+
+function rewriteText(text: string): string {
+  return text
+    .replace(
+      /\b(search_context|decompress|acp_status|acp_cache)\((\{[^\r\n]*?\})\)/g,
+      (_, op: string, args: string) => `acp_context({ op: "${op}", args: ${args} })`,
+    )
+    .replace(
+      /\brun acp_status\b/gi,
+      'call acp_context({ op: "acp_status", args: {} })',
+    )
+    .replace(
+      /\buse search_context or decompress\b/gi,
+      'use acp_context with op "search_context" or "decompress"',
+    )
+    .replace(
+      /\buse search_context\b/gi,
+      'use acp_context with op "search_context"',
+    )
+    .replace(
+      /\b(call|run) (search_context|acp_status|acp_cache)\b/gi,
+      (_, verb: string, op: string) => `${verb} acp_context op "${op}"`,
+    );
+}
+
+function rewriteModelFacingText(value: unknown, seen = new WeakMap<object, unknown>()): unknown {
+  if (typeof value === "string") return rewriteText(value);
+  if (value === null || typeof value !== "object") return value;
+  const cached = seen.get(value);
+  if (cached) return cached;
+
+  if (Array.isArray(value)) {
+    const copy: unknown[] = [];
+    seen.set(value, copy);
+    for (const item of value) copy.push(rewriteModelFacingText(item, seen));
+    return copy;
+  }
+
+  const copy: Record<string, unknown> = {};
+  seen.set(value, copy);
+  for (const [key, item] of Object.entries(value)) {
+    copy[key] = rewriteModelFacingText(item, seen);
+  }
+  return copy;
+}
+
+// Recall results carry original conversation text, which must come back
+// verbatim. decompress output has no ACP hint the rewrites target; in
+// search_context output only the hint line closing each result does (exact
+// upstream format, followed by the blank separator or the end); preview lines
+// are recalled text, may span lines and may themselves start with an arrow.
+// The message ref is a raw entry id (e.g. `088aaedb`, `4d9e965e#toolu_…|fc_…`), not an mNNNNN ref.
+const SEARCH_HINT_LINE = /^  → decompress\(\{ blockId: "b\d+" \}\)(  \(block containing message [^\s()]+\))?$/;
+
+function rewriteRecallResult(op: string, value: unknown): unknown {
+  if (op === "decompress") return value;
+  if (op !== "search_context") return rewriteModelFacingText(value);
+  if (value === null || typeof value !== "object") return value;
+  const result = value as { content?: unknown };
+  if (!Array.isArray(result.content)) return value;
+  return {
+    ...result,
+    content: result.content.map((part) => {
+      const p = part as { type?: unknown; text?: unknown };
+      if (p?.type !== "text" || typeof p.text !== "string") return part;
+      const lines = p.text.split("\n");
+      const text = lines
+        .map((line, i) => (SEARCH_HINT_LINE.test(line) && (i === lines.length - 1 || lines[i + 1] === "") ? rewriteText(line) : line))
+        .join("\n");
+      return { ...p, text };
+    }),
+  };
+}
+
+function validationError(tool: CapturedTool, args: FacadeArgs): string | undefined {
+  if (!tool.parameters || Check(tool.parameters, args)) return undefined;
+  const first = Errors(tool.parameters, args)[0];
+  const location = first?.instancePath || "/";
+  const reason = first?.message || "arguments do not match the upstream schema";
+  return `${location}: ${reason}`;
+}
+
+function helpResult(args: FacadeArgs, tools: Map<string, CapturedTool>) {
+  const requested = typeof args.tool === "string" ? args.tool : "";
+  if (!requested) {
+    return {
+      content: [{
+        type: "text" as const,
+        text: `Operations: ${LOW_FREQUENCY_TOOLS.map((op) => OPERATION_SIGNATURES[op]).join(", ")}. For a full schema, use op help with args {tool: operationName}.`,
+      }],
+      details: { operation: "help" },
+    };
+  }
+  if (!LOW_FREQUENCY_SET.has(requested)) {
+    throw new Error(`acp_context help operation is unknown: ${requested}`);
+  }
+  const tool = tools.get(requested);
+  if (!tool) throw new Error(`acp_context could not find upstream tool: ${requested}`);
+  return {
+    content: [{
+      type: "text" as const,
+      text: [
+        requested,
+        tool.description,
+        "Pass args matching this schema:",
+        JSON.stringify(tool.parameters, null, 2),
+      ].filter(Boolean).join("\n\n"),
+    }],
+    details: { operation: requested },
+  };
+}
+
+// `exposure` is a pi 1.x field; the ToolDefinition types here come from billion-context-pi's older pi dependency.
+function wrapCompress(tool: CapturedTool): CapturedTool & { exposure: "model-only" } {
+  return {
+    ...tool,
+    // ACP finds compress results by toolName in the session log; a call nested in a codemode
+    // script is recorded under codemode, so keep compress declared and out of scripts.
+    exposure: "model-only",
+    get description() {
+      const upstreamDescription = String(tool.description ?? "");
+      return upstreamDescription.includes(DEDICATED_MARKER)
+        ? "Replace consumed ranges using refs. A dedicated model writes the detailed summary; provide a meaningful fallback of 1-2 sentences preserving goals, exact paths/versions/errors, decisions, current state, and TODOs."
+        : "Replace consumed conversation ranges with self-contained summaries using mNNNNN or bN refs.";
+    },
+    promptSnippet: "",
+    promptGuidelines: [],
+    async execute(callId, params, signal, onUpdate, ctx) {
+      const forwardUpdate = onUpdate
+        ? (update: unknown) => onUpdate(rewriteModelFacingText(update) as any)
+        : undefined;
+      const result = await tool.execute(callId, params, signal, forwardUpdate, ctx);
+      // Rewrite only what the model reads; details (the recorded fold used to
+      // rebuild state) must stay verbatim.
+      const { details, ...modelFacing } = (result ?? {}) as unknown as { details?: unknown } & Record<string, unknown>;
+      const rewritten = rewriteModelFacingText(modelFacing) as Record<string, unknown>;
+      if ((details as { acpFolded?: unknown } | undefined)?.acpFolded) {
+        rewritten.content = appendText(rewritten.content, COMPRESS_DONE_HINT);
+      }
+      return { ...rewritten, details } as any;
+    },
+  };
+}
+
+function facadeTool(tools: Map<string, CapturedTool>): ToolDefinition<typeof FACADE_PARAMETERS, unknown, unknown> {
+  return {
+    name: "acp_context",
+    label: "ACP Context",
+    description: 'Search, restore, or inspect ACP context with original operation args; if unsure call { op: "help", args: { tool: "search_context" } }.',
+    promptSnippet: "",
+    promptGuidelines: [],
+    parameters: FACADE_PARAMETERS,
+    async execute(callId, params, signal, onUpdate, ctx) {
+      if (params.op === "help") return helpResult(params.args ?? {}, tools);
+      const tool = tools.get(params.op);
+      if (!tool) throw new Error(`acp_context could not find upstream tool: ${params.op}`);
+      const args = params.args ?? {};
+      const invalid = validationError(tool, args);
+      if (invalid) {
+        throw new Error(
+          `acp_context ${params.op} args invalid at ${invalid}. Expected ${OPERATION_SIGNATURES[params.op as Operation]}; retry with exactly these fields. Use op help with args {"tool":"${params.op}"} for the full schema.`,
+        );
+      }
+      const forwardUpdate = onUpdate
+        ? (update: unknown) => onUpdate(rewriteRecallResult(params.op, update) as any)
+        : undefined;
+      const result = await tool.execute(callId, args, signal, forwardUpdate, ctx);
+      return rewriteRecallResult(params.op, result) as any;
+    },
+  };
+}
+
+export function createLeanAcpExtension(
+  upstream: UpstreamExtension = createAcpExtension({ externalSystemPrompt: true }),
+): (pi: ExtensionAPI) => void {
+  return (pi: ExtensionAPI): void => {
+    const tools = new Map<string, CapturedTool>();
+    let compressTool: CapturedTool | undefined;
+    let promptHookRegistered = false;
+    const leanPi = new Proxy(pi, {
+      get(target, property, receiver) {
+        if (property === "registerTool") {
+          return (tool: CapturedTool) => {
+            if (LOW_FREQUENCY_SET.has(tool.name)) {
+              tools.set(tool.name, tool);
+              return;
+            }
+            if (tool.name === "compress") {
+              compressTool = tool;
+              compactCompressSchemaDescriptions(tool.parameters);
+              target.registerTool(decorateWithCollapsedDisplay(wrapCompress(tool)));
+              return;
+            }
+            target.registerTool(decorateWithCollapsedDisplay(tool));
+          };
+        }
+        if (property === "on") {
+          return (eventName: string, handler: (...args: unknown[]) => unknown) => {
+            if (eventName !== "before_agent_start") {
+              return Reflect.apply(target.on, target, [eventName, handler]);
+            }
+            if (promptHookRegistered) return;
+            promptHookRegistered = true;
+            // Run upstream for its side effects (active-pack stamp, summary rules,
+            // ignored-config warning); replace only the prompt it returns.
+            // undefined means a refused host: inject nothing either.
+            return Reflect.apply(target.on, target, [eventName, async (event: PromptEvent, ...rest: unknown[]) => {
+              const upstreamResult = await handler(event, ...rest);
+              if (upstreamResult === undefined) return undefined;
+              const prompt = usesDedicatedModel(compressTool) ? LEAN_SYSTEM_PROMPT + DEDICATED_PROMPT_LINE : LEAN_SYSTEM_PROMPT;
+              return injectSystemPrompt(event, prompt);
+            }]);
+          };
+        }
+        const value = Reflect.get(target, property, receiver);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+
+    upstream(leanPi);
+    pi.registerTool(decorateWithCollapsedDisplay(facadeTool(tools)));
+  };
+}
+
+export default createLeanAcpExtension();

package/package.json

@@ -1,38 +1,87 @@
 {
-  "name": "billion-context-pi-lean",
-  "version": "0.1.69-lean.1",
-  "type": "module",
-  "description": "Token-lean Pi facade for billion-context-pi with the full upstream context engine.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kunkun9527/billion-context-pi-lean.git"
-  },
-  "homepage": "https://github.com/kunkun9527/billion-context-pi-lean#readme",
-  "bugs": {
-    "url": "https://github.com/kunkun9527/billion-context-pi-lean/issues"
-  },
-  "files": [
-    "index.ts",
-    "README.md",
-    "README.zh-CN.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test tests/*.test.mjs",
-    "typecheck": "tsc -p tsconfig.json",
-    "check": "npm run typecheck && npm test"
-  },
-  "dependencies": {
-    "billion-context-pi": "0.1.69",
-    "typebox": "1.3.7"
-  },
-  "devDependencies": {
-    "typescript": "5.9.3"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  }
+	"name": "billion-context-pi-lean",
+	"version": "0.2.0",
+	"description": "Lean fork of billion-context-pi for Pi: long-session context compression with an optional cheap summary model — 486 initialization tokens, 94% fewer than the original.",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./contract": {
+			"types": "./dist/contract.d.ts",
+			"import": "./dist/contract.js"
+		},
+		"./contract/schema": "./schema/bcp-block-v1.json"
+	},
+	"pi": {
+		"extensions": [
+			"./lean/index.ts"
+		]
+	},
+	"files": [
+		"dist",
+		"schema",
+		"lean/index.ts",
+		"README.md",
+		"LICENSE"
+	],
+	"sideEffects": false,
+	"homepage": "https://github.com/kunkun9527/billion-context-pi-lean",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kunkun9527/billion-context-pi-lean.git"
+	},
+	"bugs": {
+		"url": "https://github.com/kunkun9527/billion-context-pi-lean/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"test": "node --import tsx --import ./tests/support/isolate-env.ts --test tests/*.test.ts",
+		"typecheck": "tsc --noEmit",
+		"typecheck:lean": "tsc -p lean/tsconfig.json",
+		"test:lean": "node --import tsx --import ./tests/support/isolate-env.ts --test lean/tests/*.test.mjs",
+		"check": "npm run typecheck && npm test && npm run build && npm run typecheck:lean && npm run test:lean",
+		"build": "tsup && tsc --emitDeclarationOnly",
+		"e2e": "node scripts/e2e/run-e2e.mjs",
+		"measure": "node scripts/measure.mjs"
+	},
+	"keywords": [
+		"pi",
+		"acp",
+		"context",
+		"compression",
+		"context-management",
+		"llm",
+		"pi-package",
+		"pi-extension",
+		"token-efficient"
+	],
+	"author": "kunkun9527",
+	"contributors": [
+		"ranxianglei"
+	],
+	"license": "MIT",
+	"type": "module",
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "0.83.0",
+		"@earendil-works/pi-coding-agent": "0.83.0",
+		"@earendil-works/pi-tui": "0.83.0",
+		"@types/node": "^26.1.2",
+		"acp-kernel": "0.0.101",
+		"billion-context-pi": "0.1.83",
+		"tsup": "^8.5.1",
+		"tsx": "^4.23.1",
+		"typescript": "^7.0.2"
+	}
 }

package/schema/bcp-block-v1.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ranxianglei/billion-context-pi/schema/bcp-block-v1.json",
+  "title": "BcpBlockV1",
+  "description": "One compressed block as persisted in billion-context-pi's <sessionFile>.acp.json sidecar (schemaVersion 1). Fields mirror acp-kernel's CompressionBlock verbatim; unknown extra fields are additive and must be ignored by readers.",
+  "type": "object",
+  "required": [
+    "blockId",
+    "runId",
+    "tier",
+    "summary",
+    "directMessageIds",
+    "effectiveMessageIds",
+    "directBlockIds",
+    "compressedTokens",
+    "createdAt",
+    "survivedCount",
+    "generation",
+    "active"
+  ],
+  "properties": {
+    "blockId": { "type": "string", "pattern": "^b[0-9]+$" },
+    "runId": { "type": "string" },
+    "tier": { "type": "integer", "minimum": 1, "maximum": 3 },
+    "topic": { "type": "string" },
+    "summary": { "type": "string" },
+    "directMessageIds": { "type": "array", "items": { "type": "string" } },
+    "effectiveMessageIds": { "type": "array", "items": { "type": "string" } },
+    "directBlockIds": { "type": "array", "items": { "type": "string" } },
+    "compressedTokens": { "type": "integer", "minimum": 0 },
+    "createdAt": { "type": "number" },
+    "survivedCount": { "type": "integer", "minimum": 0 },
+    "generation": { "type": "string", "enum": ["young", "old"] },
+    "active": { "type": "boolean" },
+    "expanded": { "type": "boolean" },
+    "durationMs": { "type": "number" },
+    "compressCallId": { "type": "string" },
+    "startRef": { "type": "string" },
+    "endRef": { "type": "string" }
+  },
+  "additionalProperties": true
+}

package/README.zh-CN.md

@@ -1,79 +0,0 @@
-# billion-context-pi-lean
-
-[English](README.md)
-
-基于 [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) 的精简封装。在完整保留上下文压缩引擎的同时，大幅剔除系统提示词与工具 Schema 中的冗余文本，显著降低上下文初始开销。
-
-## 核心特性
-
-* 完整上下文引擎：保留上游的对话历史压缩、分层摘要、主动提示（Nudge）、溢出恢复、重试机制与工具保护能力。
-* 优化工具布局：高频使用的 `compress` 工具直接对外暴露，其余 `decompress`、`search_context` 与 `acp_status` 操作整合为按需调用的 `acp_context` 入口。
-* 纯粹专注：主动移除了内置的 Delegation 代理分发与自动更新逻辑；如需多 Agent 协作，建议搭配独立的 Subagent 扩展使用。上游依赖版本锁定为 `billion-context-pi@0.1.69`，确保运行稳定可靠。
-
-## 精简优化成效
-
-在双方均关闭 Delegation 的配置下，与上游 `billion-context-pi@0.1.69` 本地对比：Lean 精简版常驻上下文开销为 690 tokens，上游为 5,802 tokens，减少 **5,112 tokens（88.1%）**。
-
-## 安装
-
-```bash
-pi install git:github.com/kunkun9527/billion-context-pi-lean
-```
-
-也可以通过本地克隆进行安装：
-
-```bash
-git clone https://github.com/kunkun9527/billion-context-pi-lean.git
-cd billion-context-pi-lean
-npm install
-pi install ./
-```
-
-请勿与其它 `billion-context-pi` 扩展同时加载，以防重复注册 ACP 工具与生命周期 Hooks。
-
-## 使用方法
-
-模型可见工具包括：
-
-```text
-compress
-acp_context
-```
-
-`acp_context` 支持 `decompress`、`search_context`、`acp_status` 和 `help`。
-
-```json
-{
-  "op": "search_context",
-  "args": {
-    "query": "authentication"
-  }
-}
-```
-
-仅在确需查看完整上游 Schema 时调用 `help`。
-
-## 初始化上下文占用对比
-
-单独启用本扩展时，注入到模型初始上下文中的 Token 占用实测如下：
-
-| 项目 | Lean 精简版 | 原版 `billion-context-pi@0.1.69` |
-| --- | ---: | ---: |
-| `compress` | 231 | 549 |
-| 上下文检索与操作 | `acp_context`: 90 | `decompress` + `search_context` + `acp_status`: 1,095 |
-| 系统提示词增量 | 369 | 4,158 |
-| **合计** | **690** | **5,802** |
-
-相比当前上游扩展，初始开销减少了 **5,112 tokens（88.1%）**。
-测试时双方均关闭 Delegation，环境为 Pi 0.85.1 与 `measure-plugin-tokens-v3.mjs` 独立会话，排除了 Pi 内置工具、Skills、上下文文件与无关扩展。Token 按 `ceil(字符数 / 4)` 估算。未计入不会发送给模型的纯运行时 UI 与 Slash 命令。
-
-## 本地开发
-
-```bash
-npm ci
-npm run check
-```
-
-## 开源协议与致谢
-
-MIT 协议。本包装层基于采用 MIT 协议的 [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi)。