# 实时工件渲染与 Bash 工件声明

日期：2026-08-14

# 问题

原工件能力只在整轮对话结束后重新请求列表，且仅从 write/edit 提取 details.path。模型通过 bash 生成 PNG 时，聊天记录只有“PNG saved”文本，无法知道哪个文件安全可预览，更不会实时显示图片。

# 变更

• toolexecutionend 若工具结果带有合规工件，立即携带 artifact 元数据；React 同步更新工件列表，并在对应工具卡内直接显示图片缩略图。
• bash 新增可选 artifacts: string[] 参数。命令成功后才校验声明的文件存在，并把合规相对路径写入 ToolResult.details.artifacts。
• 未声明 artifacts 时，bash 会比较执行前后的工作区候选文件（有限深度、最多 2,000 个候选/8 个变更），自动把新建或修改的图片、Markdown、文本、JSON、CSV、日志等作为工件；cp 到工作区的 PNG 也因此可即时预览。
• SessionStore 将成功 bash.artifacts 与 write/edit 一样纳入会话工件聚合；一条 bash 可声明多个文件。
• 工件路径验证独立于 PIAGENTNO_SANDBOX：必须在 workspaceRoot 内。禁止从 bash 输出（例如 saved: ~/Desktop/a.png）猜测路径，以免 UI 变成任意本地文件读取器。
• system prompt 明确要求：需要聊天预览的图片/文档写入工作区，并通过 bash.artifacts 声明。

# 调用示例

{
  "command": "python3 render.py --output reports/card.png",
  "artifacts": ["reports/card.png"]
}

命令完成后，reports/card.png 会立即出现在该 bash 工具卡下方，并可从“工件”抽屉打开大图、下载。

# 边界

• 旧会话中没有 details.path/details.artifacts 的工具记录无法事后可靠恢复。
• 写到 ~/Desktop 等工作区外的图片不会预览；将 PIAGENTWORKSPACE 指向希望产物落盘的目录，或让模型改写到当前工作区。
• 内嵌预览仍限制为 1 MB；较大文件可下载，不会被浏览器整块加载。

# 验证

• mvn -pl pi-agent-v1 clean test：通过（当前项目没有测试源码）。
• web/ 下 npm run build：TypeScript 检查与 Vite 生产构建通过。
• Mock SSE 冒烟：成功 write output.txt 的 toolexecutionend 已包含实时 artifact 元数据。
• JShell 工具冒烟：未声明 artifacts 的 bash 创建 copied.png 后，自动返回详情 {exitCode=0, artifacts=[copied.png]}。