富文本与预览

先决定要交付什么形态#

产物形态决定后面所有步骤：写成文件、用哪种预览呈现、要不要固化成页面。先把形态说清楚，比产出后再返工省事。

1. 说清用途：给人看的说明文档、要发出去的邮件正文、还是需要反复查看的指标看板。
2. 说清格式偏好：需要保留原样排版就用 HTML，纯文字与结构化内容用 Markdown。
3. 说清留存要求：一次性的结果留在文件里，长期要看的做成页面。

产出文件，就地预览#

预览读的是磁盘上的文件。Agent 先把内容写成文件，再用预览块引用它，你在对话里就能直接看到成品。

修改也走同一条路：改文件，再重新预览一次。不要指望在预览里直接编辑内容。

1. 让 Agent 把结果写成文件，而不是只贴在回复正文里。
2. 确认预览引用的路径是文件真实所在的绝对路径，路径不对就预览不出东西。
3. 需要比较多个版本时，把它们放进同一个预览的多个条目，用标签页切换。

预览里能看到什么#

每种预览的渲染方式不同，知道差异才能判断该用哪一种。

1. 先在内联高度里看整体效果，需要细节再展开全屏。
2. 多个条目之间用标签页切换，切换时才加载内容。
3. 图表用 Mermaid 描述即可，不必先生成图片再插入。

让结果长期存在#

预览是即时的，文件是持久的，页面是可持续的。三者对应三种不同的留存需求。

页面住在工作区里，渲染在应用内，可以长期打开、反复查看，还能按计划自动更新数据。

1. 一次性结果：留在工作目录里，需要时直接取用文件。
2. 长期要看的仪表盘、报表与追踪表：做成页面，放在侧栏的页面区域。
3. 需要自动更新的：给页面配上刷新计划，按 cron 触发取数并写回数据。

• 页面可以在你批准后调用工作区的来源：读一份数据、发一条消息这类操作都要逐项批准。
• 批准的是一份具体且有界的权限，不是把整个账号交给页面。
• 需要在本机运行工作区脚本的页面，权限更高，也因此不能被发布出去。
• 分享出去的副本是自包含的：对外请求全部被拦下，页面只能靠自己内联的资源工作。