# 工件预览与控制台恢复体验

日期：2026-08-14

# 目标

让 Agent 通过 write / edit 产生的文件成为可恢复、可预览的会话结果，并补齐主控制台在桌面与移动端的会话/详情访问能力。

# 变更

• SessionStore 将 ToolResult.details 持久化到 JSONL；旧记录仍可只恢复 timedOut。成功的 write、edit 从 details.path 提取 ArtifactReference。
• 新增 GET /api/artifacts?sessionId=... 和 GET /api/artifacts/{toolCallId}/content?sessionId=...。内容接口限制 1 MB，强制 workspaceRoot 边界，不继承 PIAGENTNO_SANDBOX 的放宽效果，并返回 CSP sandbox / nosniff。
• React 新增工件详情抽屉：按选择懒加载文本，支持 Markdown、文本/代码、JSON/CSV 和图片，提供下载与复制相对路径。
• 当前会话、侧栏折叠、详情尺寸、已选工件与减少动效偏好使用 localStorage 恢复；会话刷新仍以服务端历史和 AgentState 为准。
• 移动端提供会话抽屉；详情面板在小屏改为固定覆盖层。新增 ⌘/Ctrl + K 快捷命令以及可访问的会话键盘操作。

# 契约

artifacts[] 的稳定字段：id（来源 toolCallId）、path、name、sourceTool、createdAt、modifiedAt、size、mimeType、previewable。

列表仅反映当前会话分支上仍存在、仍位于工作区的文件；它不是整个工作区的文件浏览器，也不会把 bash 的任意输出猜成工件。

# 验证

• mvn -pl pi-agent-v1 clean test：通过（项目当前没有测试源码）。
• mvn -pl pi-agent-v1 package -DskipTests：通过。
• web/ 下 npm run build：TypeScript 检查和 Vite 生产构建通过。
• 使用 Mock 模型写入 output.txt 后，GET /api/artifacts?sessionId=artifact-smoke 返回工件元数据，内容接口返回写入原文。

# 已知边界与下一步

• 预览上限为 1 MB；更大文件可由后续下载/分块预览迭代处理。
• P3 尚未实现按真实高度计算的消息虚拟列表、长任务迷你地图，以及运行卡/工具卡展开状态恢复；这些不应被本次状态恢复能力混同。