@kevinhao/pi-distill1.10.0

@kevinhao/pi-distill

保留原文，把上下文留给决策。

一个工具结果处理入口，两种互斥策略：按 outputRequest 生成普通摘要，或通过显式启用的诊断证据提取保留原文引文。证据机制改编自 NVIDIA SoL-Pi。任何被接受的有损替换都先归档来源；需要核实时使用 Pi 原生 read，不新增摘要或回读工具。

English: README.md

安装与启用

pi install npm:@kevinhao/pi-distill

运行 /reload，再通过 /config:distill 选择模型和配置处理。/pi-distill 是兼容别名；/distill:stats 显示本会话结果、尝试次数、用量、预计上下文节省和成本。交互式命令需要带 UI 的会话，工具结果处理也支持无界面运行。

配置位于 <Pi agent 目录>/extensions/pi-distill/config.json，通常在 ~/.pi/agent 下，支持 PI_CODING_AGENT_DIR。加载时不写配置，不迁移或修改用户全局设置。默认配置见 config.example.json。

**证据模式与 Fusion 日志处理默认关闭。**明确开启诊断证据时配置：

{
  "evidence": {
    "enabled": true,
    "fusion": true,
    "minBytes": 8192,
    "commands": []
  }
}

fusion: true 额外允许处理 Action Fusion edit/write 追加的命令日志，不负责启用 Action Fusion。明确的 tools.edit.enabled: false 或 tools.write.enabled: false 优先。交互式设置提供这两个证据开关；字节配额和附加命令前缀在 JSON 中配置。

处理链路

工具返回真实结果
  ├─ 关闭 / RAW / 非文本 / 排除范围 → 保留原结果
  └─ 确定一个处理范围和一种策略
       ├─ 识别出的诊断命令 → 证据提取（已开启时）
       └─ 其他已启用文本＋outputRequest → 普通摘要
            ↓ 检查大小、完整性、疑似敏感内容
            ↓ 模型调用前先归档原文
            ↓ 模型处理和本地校验
            ├─ 合法、未超预算且有收益 → 处理结果＋来源引用
            └─ 失败 / 取消 / 收益不足 → 保留原结果

证据失败不会降级为普通摘要，已处理的收据不再处理。Distill 不改变命令执行、文件修改或工具错误状态；通过原生 tool_call/tool_result 接入，不注册替代工具。事件按扩展顺序执行，因此来源是 Distill 实际收到的结果，不能恢复其他扩展已经丢掉的内容。

工具 schema 与 RAW

普通已启用 object-schema 工具保留必填、非空的 outputRequest。未配置的非修改工具仍按旧版默认开启，通过 tools.<name>.enabled: false 排除；启用证据不会暗中重置这份工具范围。

{
  "command": "npm run test",
  "outputRequest": "保留失败用例、断言差异和最终统计"
}

去除首尾空白后严格为 RAW（不区分大小写）时跳过两种策略，保留收到的工具 content，不是无限制的进程全文；底层工具自己的限制仍然存在。RAW、禁用和失败回退不再被 Distill 截断或改成文件指针，即使 maxOutputChars 配得很小也不会截断它们。自定义工具仍需自行限制输出；保留超大回退结果仍可能超过主模型上下文。

明确启用证据和 Fusion 时，暴露 then_run 的兼容 edit/write 获得可选 outputRequest：省略则用默认证据规则，RAW 跳过，其他文本指定关注重点。它只作用于命令日志；普通修改结果永不摘要，即使存在旧版 tools.edit/write.enabled: true 设置。Distill 仅捕获并移除已成功注入且仍由自己拥有的处理字段；原工具已有同名 outputRequest 时警告并保持原状，不删除禁用工具的同名业务字段。

非文本或混合媒体结果不处理。扩展禁用时不向系统提示词添加处理契约。

两种策略的区别

诊断证据

保守命令识别覆盖常见测试、构建、检查命令，包括 npm run test/build、test:unit 脚本、pnpm/yarn/bun、pytest/unittest、Go/Cargo 和原生构建工具。支持简单的非引号命令边界及常见包装，不解释任意 shell 程序。复合命令必须每段均为诊断或有限的无输出准备（cd、环境变量赋值、true、:）；npm test; cat confidential.txt 不进入自动证据策略。echo 'npm test' 等引号示例、命令替换和 heredoc 不自动认定为诊断。evidence.commands 添加字面 token 前缀，不是可执行正则；使用规范化后的可执行文件名，例如 ./verify --ci 对应 "verify --ci"。

固定双语提示词要求连续原文引文。outputRequest 只能选择关注重点，不能取消固定约束；处理模型不生成诊断或修复建议。证据策略只请求一次，不做 JSON 修复，不使用普通摘要的重试预算。校验 schema、数量/长度、引文原文匹配和必要的可识别失败证据；零失败统计不能冒充失败证据。工具状态成功但日志包含强失败信号时也要求保留失败证据。行号在本地计算，哈希、路径和观察到的工具错误状态由代码生成，不让模型编造。

结果带 [distill:evidence]。引文真实不证明覆盖完整、分类正确、因果关系正确或测试全部通过。|| true 等命令可以掩盖测试失败；模型的不确定性只是建议，不是完整性证明。

普通摘要

其他启用文本仍按 outputRequest 处理，保留现有 RAW/SUMMARY 协议、重试预算和一次 JSON-only 格式修复。结果带 [distill:summary]，明确声明未在本地逐项核验事实。归档增强的是追溯能力，不是摘要正确性。

两种策略按完整投影结果（含来源及受保护修改确认）计算收益，要求至少 1.4 倍字符压缩，并满足正文及完整结果预算。字符节省不是精确 tokenizer 节省。下面旧版真实会话截图中的 213.40 倍压缩发生在来源收据引入之前，仅说明合适冗长输出的潜力，不是此版本的保证。

原文与原生 read 回读

每次被接受的摘要或证据都提供模型可见来源：

source_artifact="/…/extensions/pi-distill/artifacts/<会话哈希>/objects/<原文哈希>.txt"
source_sha256=…
source_bytes=…
source_lines=4200
source_kind=tool-output

调用时使用不含 JSON 引号的真实路径：

{
  "path": "/…/objects/<原文哈希>.txt",
  "offset": 200,
  "limit": 60,
  "outputRequest": "RAW"
}

仅在当前 read schema 暴露该字段时提供 outputRequest。行号从 1 开始；最后 N 行可一次定位：offset = max(1, source_lines - N + 1)，limit = N。行数沿用原生 read 的换行切分语义，包括末尾空行；read 自身行数/字节限制仍有效。

工具提供的有界、普通、单链接且非符号链接临时文件可以作为更完整来源。Bash/Fusion 仅接受操作系统临时目录直属的原生 pi-bash-*.log，或错误标准化后原生格式的最终截断提示。不合法、不存在、过大或变化中的文件会回退原结果。已知截断且无法取得完整日志时不做证据替换；其他文本可作为 source_kind=preview 摘要，但不能冒称全文。来源是 Pi 提供的 UTF-8 文本；完整文件含非法 UTF-8 时拒绝，不默默改写。

Fusion 仅处理 [then_run:succeeded] 或 [then_run:failed] 后的命令日志。修改确认、成功结果的 diff/patch metadata、机器标记和外层错误状态不变；跳过、执行中、缺失或边界歧义则不处理。Pi 对失败调用抛出的错误进行标准化后，可能本就没有 diff details，Distill 无法恢复。支持 details.actionFusion.bashDetails，不导入 Fusion 私有源码。

存储、隐私与回退

原文存于 agent 目录，不写项目。会话 ID 和内容经哈希成为路径；原子发布、内容去重并核验完整性，支持的平台使用私有权限。限制单条来源字节数和恢复后会话对象累计大小。归档失败或配额用尽时不发送模型请求，保留原结果。重新加载、恢复会话和正常退出不会删除归档；确认引用不再需要后，由用户明确执行文件清理。

默认单条 1 MiB、单会话 64 MiB。写入同时使用进程内序列化和会话文件系统独占锁。取消可立即中断进程内队列等待，但不会让后续写入越过尚未完成的写入。锁被占用时不等待、不发送模型请求，保留原结果；进程崩溃遗留的锁不会自动夺取，确认没有活跃写入后再明确清理。遗留 staging 和对象目录内其他普通文件也计入配额，不静默删除。会话配额不是全局保留策略；文件系统不支持所需原子链接时保留原结果，不弱化完整性保证。

处理可能把来源发送给当前或配置模型；两种策略都会跳过疑似凭据，但启发式检测不是完整的隐私保证。关闭处理或选择本地处理模型可避免额外的远程接收方，但不会脱敏原工具结果，也不会阻止主 Agent 将它发送给自己的模型；要求所有日志留在本机，还需使用本地主模型并合理配置工具。归档也可能含敏感文本。不要与独立 SoL-Pi Reducer 或重叠的结果摘要扩展同时运行。

父请求取消会传播到模型请求。超时限制的是 Distill 等待时间，不保证忽略取消信号的 provider 停止远程执行或计费；前一个请求是否终止尚未确认时，不启动超时重试。已报告的用量计入 Pi 工具结果成本，包括被拒绝的证据和失败的 JSON 修复。即使修复请求挂起，首次响应已报告的用量也会保留；挂起请求从未报告的用量无法恢复。请求前通过启发式 token／模型上下文窗口检查跳过明显超预算输入。证据失败永不降级为未核验摘要。每次请求由模型注册表统一解析认证和地址，不额外执行鉴权预检查；Codex 后台请求使用独立会话并在请求完成后清理。

配置项

配置项	含义
enabled	是否启用；关键配置（包括格式错误的工具关闭设置）无效时停止处理，需手动修复。
model	可选 provider/modelId，空值使用当前会话模型。
minChars	普通摘要输入阈值，默认 200 字符。
maxChars	被接受的摘要/证据正文预算，默认 100,000 字符；超出保留原结果。
maxOutputChars	完整替换结果预算（含来源），默认 10,000；不是 RAW/回退限制。
timeoutSeconds	每次模型尝试截止时间，默认 10 秒。
timeoutRetryCount/errorRetryCount	普通摘要的超时/其他异常重试，默认各 1 次；证据始终只尝试一次。
missedCompressionRatio	保留的兼容配置字段。
summarizeErrors	false 时两种策略都不处理错误，包括明确请求的长错误。
evidence.enabled	诊断证据策略，默认 false。
evidence.fusion	融合命令范围，默认 false；依赖证据已开启。
evidence.minBytes	证据输入阈值，默认 8,192 个 UTF-8 字节。
evidence.commands	最多 32 个附加字面命令前缀，每项不超过 256 字符。
archive.maxSourceBytes	默认 1 MiB，最多 16 MiB；过大来源不发送模型。
archive.maxSessionBytes	默认 64 MiB，最多 1 GiB；不静默驱逐归档。
tools.<name>.enabled	现有工具开关；修改工具仍需明确开启证据/Fusion。
render.*	UI-only 审计卡片、请求和结果预览。

文件字段优先于现有 PI_DISTILL_* 和旧版 PI_BASH_SUMMARY_*；证据与归档配置仅支持 JSON。不自动改写或迁移全局配置。Fusion 开关仅控制兼容 Fusion 工具的日志处理及 schema，不是 Bash 权限沙箱。

开发与来源

要求 Node.js 22+ 和 Pi 0.87.1+。Pi peer 最低版本与已测试的模型注册表、会话资源及工具用量 API 对齐，不再声明兼容 0.80–0.86。开发和离线 SDK 回归针对 Pi 0.87.1。确定性测试使用注入 provider、临时存储及原生 read，无需 API Key。

npm run typecheck --workspace pi-distill
npm test --workspace pi-distill

提示词和通知跟随共享语言设置；UI 审计不进入模型上下文。SoL-Pi 改编代码的 MIT 授权及归属见 THIRD_PARTY_NOTICES.md 和 LICENSE。