由壹点客户端 Pi Agent
原生客户端的正常“编辑画布”发送入口已接入 @earendil-works/pi-coding-agent@1.3.0。画布与界面仍为 Rust PhotoCraft；Pi 是本机独立 Node 进程，不引入 Electron、Web UI 或生产端 Agent 服务。生图继续复用原生个人 Key 适配，不经 Pi 自动重发。
运行边界
- Pi 管理完整 JSONL 会话、历史检索、摘要及工具循环。同一账号／本机项目／规则版本串行加锁，重启读取原会话。事实更正引用用户原话；原始历史保留，不只发送 UI 最近几条消息。
- Rust 逐次核对素材库授权、账号、模型用途及个人 Key。Windows 凭据库内的 Key 不传给 Node、模型、自建工具或项目文件；Node 只连接原生受限模型桥。
- 98k 仅通过公开客户接口调用。调用选项来自公开模型契约，不借用其他项目的后台、源码或服务器。
native-tools已实测当前选择的grok-4.7；不据此认定所有模型兼容。structured-json仍是显式验证模式，失败后不自动切换协议或补发。 - 每次请求按当前任务注入精确店铺／品类快照：普通对话保留身份、调性和事实约束，画布任务才带影像细则，方案／生图任务才带模板。
context_read可按需读取品牌、模板或来源。不把品牌文本同时塞入多个字段，旧工具大响应只投影可追溯摘要，原文不删除。 - 素材库
GET /api/desktop/agent-rules返回已配置组合；?binding=<ID>返回精确版本包。已接入真实顾家／电脑桌模板；其他缺少完整模板的组合不会借用或伪装就绪。旧项目保留原快照，不被公共规范更新改写。 - 输入超过80000字符先压缩，投影后超过120000字符不派发；每个用户轮最多12次模型调用，压缩同样计入预算。这是本地资源策略，不是98k模型窗口承诺。
工具与画布
只开放规则读取、事实记忆、历史检索、沙箱工具开发／运行、画布读取及现有图层编辑。禁用 SDK 默认终端、文件操作、外部扩展、目录扫描和任意网络工具。
自建工具使用 quickjs-emscripten@0.32.0：8MB内存、256KB栈、约200ms中断限时、仅JSON输入输出。至少3项测试通过才保存不可变版本；运行时复核版本哈希。无宿主文件、网络、Key或Node API。计算结果不直接写画布，仍须通过原生编辑命令。
画布操作串行进入同一原生队列、实时显示、共用手动撤销历史。每步核对账号、文档、revision及接手状态。用户接手、人工修改、切换文档后停止剩余写入，不能在前置检查结束后重新开启已撤销的编辑许可。
结果未知与恢复
每个POST前持久写入请求身份；SDK与HTTP均关闭自动重试。dispatched / received / unknown 阻止同项目新调用、删除和切换规则绕过。
- 恢复只读取本机留存原响应，或对原客户请求号执行GET，不创建新生成。
- 原回复完整时，经原协议解析器验证后补回会话和界面；中断时的残缺参数不执行。
- 取回尚未执行的工具建议时，保持待核对，绝不自动重跑写操作；客户端可明确放弃这些建议后继续。
- 410继续保留未知、请求号及幂等键，不当成失败。不清空旧记录以绕过门禁。
- 用户接手画布不代表已经取消上游推理。本机子进程异常退出也保留原请求与草稿。
缓存口径
本地历史／规则快照是持久化，不等于模型缓存。只按98k响应中的 cached_tokens 或 cache_read_input_tokens 统计；字段缺失显示未知，不记成0。总命中率按缓存输入Token之和除以总输入Token，不能平均单笔百分比。命中仍占上下文窗口，价格优惠未独立核实，不保证固定缓存率。
验证与本地打包
Pi 的项目运行时固定为 Node 24.22.1 或同一 24.x 线的后续安全版本。
开发时先安装已校验官方 SHA-256 的 Node 到 runtime/；不借用全局 Node。
主进程、独立 SDK 入口及打包工具都校验版本，旧版本不会启动模型桥。
cd apps/detail-agent-pi
npm ci --ignore-scripts
npm test
原生客户端构建与使用见 ../detail-photocraft/JIANSUN.md。完整本地包包含原生程序、agent/node.exe、agent/src与锁定依赖，不包含账号配置、Key、用户工程或请求日志：
node apps/detail-agent-pi/scripts/package-client.mjs <photocraft.exe> <新的输出目录> <node.exe> <对应版本Node的LICENSE>
实际模型脚本会消耗本人Key额度，仅在明确验收时运行。尝试记录以独占文件防止误重跑；遇到未知只读恢复，不能删除尝试记录再提交。summarize-client-validation.mjs 仅汇总留存证据，不调用模型。
本轮接通与真实验收见根目录 docs/pi-client-integration-acceptance-2026-10-22.md。此前选型与兼容性记录仍保留在2026-10-21两份报告中，不用后续成功覆盖失败现场。