opensource/proxycast
3
0
Fork 0
mirror of https://github.com/aiclientproxy/proxycast.git synced 2026-09-24 23:10:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: release v0.96.0

Browse Source
This commit is contained in:
coso
2026-03-25 22:04:38 +08:00
parent 307b2d3670
commit 0ee56c1098
328 changed files with 40949 additions and 6948 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/roadmap/artifacts/architecture-blueprint.md
+744
View File
@@ -0,0 +1,744 @@
# Lime Artifact Workbench 架构蓝图
> 状态：提案
> 更新时间：2026-03-24
> 运行时边界：凡涉及发送边界、runtime metadata、Team 委派、Op/Event 收口，均以 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 为准；本文只细化 Artifact Workbench 架构
> 依赖文档：
> - `docs/roadmap/artifacts/roadmap.md`
> - `docs/roadmap/artifacts/artifact-document-v1.md`
> - `docs/roadmap/artifacts/framework-boundary.md`
> - `docs/roadmap/artifacts/system-prompt-and-schema-contract.md`
> 目标：把 Lime 高配版 Artifact Workbench 的产品形态、运行链路、时序关系、system prompt 组装策略与实现边界收敛成一份可直接指导开发实施的总装图
## 1. 固定决策
本蓝图固定以下 v1 决策，不再留给后续实现阶段临时判断：
1. **右侧主工作台**
Artifact Workbench 的主交互面是聊天右侧工作台，不以全屏页为默认入口。
2. **双阶段生成**
高价值结构化交付物默认采用：
- Stage 1：Reasoning / Outline / Intent Resolution
- Stage 2：ArtifactDocument 结构化产出
3. **分层组装 prompt**
system prompt 由后端统一分层拼装，不让前端直接拼完整 prompt。
4. **产品层 canonical model**
- `ArtifactDocument JSON` 是长期事实源
- `Tiptap / ProseMirror JSON` 仅是 `rich_text` block 的编辑器载荷
- `Markdown / HTML / PDF` 是导出快照
5. **研究类 source 强约束**
- `report / analysis / comparison / research`：必须有 source
- `roadmap / prd / plan / brief`：source 可选，但建议保留
6. **消息区与交付区职责分离**
- 消息区负责解释、进度、追问、下一步
- 交付区负责正式产物
- 不允许整篇 Artifact 再重复贴回消息区
7. **框架层与产品层分离**
- Lime 持有 `ArtifactDocument` 与 Workbench 产品能力
- Aster Runtime 持有 `thread / turn / item / event / output schema`
- `blueprint` 只是可选 planning module，不是主运行时
## 2. 文档依据
本文基于以下现役事实源：
- `src/components/agent/chat/hooks/agentRuntimeAdapter.ts`
- `src-tauri/src/commands/aster_agent_cmd/runtime_turn.rs`
- `src-tauri/src/commands/aster_agent_cmd/prompt_context.rs`
- `src-tauri/src/services/memory_profile_prompt_service.rs`
- `src-tauri/src/services/web_search_prompt_service.rs`
- `src/components/agent/chat/workspace/workbenchPreview.tsx`
- `src/components/agent/chat/workspace/WorkspaceCanvasContent.tsx`
- `src/components/artifact/ArtifactRenderer.tsx`
- `src/components/content-creator/canvas/document/editor/NotionEditor.tsx`
- `src-tauri/src/services/agent_timeline_service.rs`
从这些事实源可以确认：
1. 前端已支持 turn 级 `systemPrompt` 透传。
2. 后端现有主链已按阶段合并 `runtime agents / memory / web search / request policy / elicitation / team preference / auto continue`。
3. Lime 已具备右侧工作台、Artifact 渲染、Timeline 投影与富文本编辑器底座。
4. 需要新增的是 Artifact 相关的产品层协议、编排层与 prompt 层，而不是另造第二套聊天系统。
## 3. 总体架构
## 3.0 跨层总装图
```mermaid
flowchart TB
User["用户"]
subgraph FE["Lime 前端"]
Conversation["Conversation"]
Workbench["Artifact Workbench"]
Inspector["Timeline / Sources / Diff"]
end
subgraph App["Lime 应用层"]
ArtifactDomain["ArtifactDocument Domain"]
WorkbenchService["Artifact Workbench Service"]
ProductPolicy["Artifact Product Policy"]
end
subgraph Runtime["Aster Runtime 层"]
ThreadTurn["Thread / Turn / Item"]
PromptComposer["Prompt Composer"]
SchemaRuntime["Output Schema Runtime"]
EventBus["Runtime Event Bus"]
Approval["Approval / Elicitation / Interrupt"]
end
subgraph Planning["Blueprint 模块"]
Blueprint["Blueprint / TaskTree / Worker"]
end
subgraph Model["模型与工具"]
LLM["LLM"]
Tooling["Web / File / Exec / MCP"]
end
User --> Conversation
Conversation --> WorkbenchService
Workbench --> ArtifactDomain
Inspector --> EventBus
WorkbenchService --> ProductPolicy
WorkbenchService --> ThreadTurn
ProductPolicy --> PromptComposer
ThreadTurn --> PromptComposer
PromptComposer --> SchemaRuntime
SchemaRuntime --> LLM
LLM --> Tooling
Tooling --> EventBus
EventBus --> ArtifactDomain
ThreadTurn -. optional planning handoff .-> Blueprint
```
## 3.1 总体架构图
```mermaid
flowchart TB
User["用户请求"]
subgraph Frontend["前端交互层"]
Conversation["Conversation / Message List"]
Inputbar["Inputbar / Intent Metadata"]
Workbench["Artifact Workbench Shell"]
Inspector["Timeline / Inspector / Sources Drawer"]
end
subgraph Runtime["Aster Runtime / Lime Runtime Adapter"]
TurnGateway["agent_runtime_submit_turn"]
IntentResolver["Artifact Intent Resolver"]
PromptComposer["Artifact Prompt Composer"]
Planner["Stage 1 Planner / Reasoner"]
Generator["Stage 2 Artifact Generator"]
Validator["Validator / Repair"]
Timeline["Agent Timeline Recorder"]
end
subgraph Domain["Artifact Domain 层"]
ArtifactStore["ArtifactDocument Store"]
Versioning["Artifact Versioning"]
SourceRegistry["Artifact Source Registry"]
Exporter["Export Adapters"]
end
subgraph Render["渲染与编辑层"]
BlockRenderer["Artifact Block Renderer Registry"]
RichTextAdapter["RichText Adapter / Tiptap"]
end
User --> Inputbar --> TurnGateway
TurnGateway --> IntentResolver
IntentResolver --> PromptComposer
PromptComposer --> Planner
Planner --> Generator
Generator --> Validator
Validator --> ArtifactStore
Validator --> Timeline
ArtifactStore --> Versioning
ArtifactStore --> SourceRegistry
Conversation --> Inspector
Timeline --> Inspector
ArtifactStore --> Workbench
SourceRegistry --> Inspector
Workbench --> BlockRenderer
BlockRenderer --> RichTextAdapter
Workbench --> Exporter
Exporter --> Versioning
```
## 3.2 分层职责
### 前端交互层
- 收集用户输入与 UI 场景元数据
- 展示消息区、右侧 Artifact Workbench、Timeline / Source Inspector
- 不负责拼装完整 system prompt
- 不负责决定最终 block schema
### Runtime 层
- 判断本次 turn 是否进入 Artifact 主链
- 组装 prompt
- 绑定 turn 级 output schema
- 执行 Stage 1 / Stage 2
- 做 validator / repair
- 产出 timeline 事件
- 持有 item / delta / approval / interrupt 语义
### Artifact Domain 层
- 作为 `ArtifactDocument` 的持久化与版本事实源
- 管理 sources、version、export records
- 连接 turn / item 与 artifact
### 渲染与编辑层
- 把 block 渲染成统一视觉组件
- 让 `rich_text` block 接入 Tiptap
- 承载局部编辑、局部 AI 改写、diff、导出
## 4. 生命周期流程
## 4.1 生命周期流程图
```mermaid
flowchart TD
A["用户发起请求"] --> B{"是否需要正式交付物?"}
B -- 否 --> C["普通消息链路"]
B -- 是 --> D["解析 artifact intent / kind / source policy"]
D --> E["组装 Stage 1 system prompt"]
E --> F["Stage 1 输出意图、骨架、source 需求、block 计划"]
F --> G["组装 Stage 2 system prompt"]
G --> H["Stage 2 输出 artifact_document_draft 或 artifact ops"]
H --> I["Validator / Repair"]
I --> J{"是否合法?"}
J -- 否 --> K["降级为 rich_text fallback + 记录 telemetry"]
J -- 是 --> L["写入 ArtifactDocument Store"]
K --> L
L --> M["生成版本记录 / source 绑定 / timeline 事件"]
M --> N["右侧 Artifact Workbench 渲染"]
N --> O{"用户继续编辑/改写?"}
O -- 否 --> P["导出 / 归档 / 保留为最终版本"]
O -- 是 --> Q["局部 rewrite / 局部编辑 / 新版本生成"]
Q --> I
```
## 4.2 状态机
| 状态 | 说明 | 可迁移到 |
|------|------|------|
| `draft` | 已建立 ArtifactDocument，尚未开始正式流式写入 | `streaming` / `failed` |
| `streaming` | 正在由 Stage 2 或局部 rewrite 写入 | `ready` / `failed` |
| `ready` | 当前版本可用 | `streaming` / `archived` |
| `failed` | 当前回合生成失败，但文档对象仍保留 | `streaming` / `archived` |
| `archived` | 已归档，只读 | - |
触发原则：
- `artifact.begin` 或创建 draft 时进入 `draft`
- 第一个有效 block 写入时进入 `streaming`
- validator / repair 完成并落盘进入 `ready`
- Stage 2 或 rewrite 失败进入 `failed`
- 归档操作进入 `archived`
## 5. 核心时序图
以下时序图只表达产品层与运行时层的职责分工，不单独定义 Lime 当前仓库的 on-wire 字段名、命令名或 metadata 归一化细节。
这些当前实施细节统一以 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 为准。
## 5.1 生成时序图
```mermaid
sequenceDiagram
participant User as 用户
participant FE as 前端工作台
participant RT as Runtime Turn
participant PC as Artifact Prompt Composer
participant S1 as Stage 1 Planner
participant S2 as Stage 2 Generator
participant VR as Validator/Repair
participant Store as ArtifactDocument Store
participant TL as Timeline
participant WB as Workbench
User->>FE: 输入请求
FE->>RT: submit_turn(message + artifact metadata)
RT->>PC: build prompts by layers
PC-->>RT: stage1_prompt + stage2_prompt context
RT->>S1: 执行 Stage 1
S1-->>RT: artifact_intent + outline + source policy
RT->>TL: emit artifact_intent_resolved
RT->>S2: 执行 Stage 2
S2-->>RT: artifact_document_draft / artifact ops
RT->>VR: validate and repair
VR-->>RT: repaired document
RT->>Store: persist document + version + sources
RT->>TL: emit artifact_version_persisted
Store-->>WB: latest ArtifactDocument
WB-->>User: 右侧显示正式交付物
```
## 5.2 Prompt 组装时序图
```mermaid
sequenceDiagram
participant FE as 前端
participant RT as runtime_turn
participant AP as artifact_prompt_service
participant Base as Base Prompt Layer
participant Mem as Memory Prompt Layer
participant Search as Web Search Layer
participant Artifact as Artifact Policy Layer
participant Source as Source Policy Layer
participant Stage as Stage Contract Layer
participant Schema as Output Schema Binder
FE->>RT: submit_turn(system metadata only)
RT->>AP: compose(stage, kind, sourcePolicy, metadata)
AP->>Base: merge base runtime rules
AP->>Mem: merge memory prompt
AP->>Search: merge web search prompt
AP->>Artifact: merge artifact policy prompt
AP->>Source: merge source requirement prompt
AP->>Stage: merge stage-specific contract
AP->>Schema: attach turn-level output schema
Schema-->>AP: final system prompt + output schema
AP-->>RT: composed prompt + stage markers + schema
```
## 5.3 局部改写时序图
```mermaid
sequenceDiagram
participant User as 用户
participant WB as Workbench
participant RT as Artifact Rewrite Runtime
participant PC as Prompt Composer
participant Gen as Rewrite Generator
participant VR as Validator/Repair
participant Store as Version Store
participant Diff as Diff Engine
User->>WB: 选中 block 并点击 AI 改写
WB->>RT: rewrite(blockId, instruction, current document)
RT->>PC: compose rewrite prompt
PC-->>RT: rewrite system prompt
RT->>Gen: 仅生成目标 block 新内容
Gen-->>RT: updated block
RT->>VR: validate block + document
VR-->>RT: repaired document snapshot
RT->>Store: create new version
Store->>Diff: compare previous/current
Diff-->>WB: block diff
WB-->>User: 展示差异并切换到新版本
```
## 5.4 导出时序图
```mermaid
sequenceDiagram
participant User as 用户
participant WB as Workbench
participant Export as Export Service
participant Render as Render Adapter
participant Store as Artifact Store
User->>WB: 点击导出
WB->>Export: export(artifactId, format)
Export->>Store: load latest version
Store-->>Export: ArtifactDocument + editor payloads
Export->>Render: convert to md/html/pdf/json
Render-->>Export: exported content/file
Export-->>WB: download path / result
WB-->>User: 导出完成
```
## 6. Prompt 架构
## 6.1 为什么必须由后端组装
当前现役事实源已经说明，system prompt 的主要规则是在后端主链按阶段合并：
- `runtime agents`
- `memory`
- `web search`
- `request tool policy`
- `elicitation`
- `team preference`
- `auto continue`
Artifact Workbench 不应绕开这条链，也不应让前端页面继续自行决定 prompt 顺序。
因此：
- 前端只传意图元数据
- 后端统一决定 prompt 层级、去重 marker、冲突处理与日志记录
## 6.2 Prompt 分层
v1 固定采用 7 层 prompt：
### 1) Base Runtime Layer
职责：
- 基础身份
- 输出语言
- 工具边界
- 安全约束
- “消息区 vs 交付区”职责分工
### 2) Runtime Agents Layer
复用现有运行时能力提示与工作目录上下文。
### 3) Memory Layer
复用现有记忆画像和记忆来源提示。
### 4) Search / Source Layer
包含：
- 现有 web search 偏好
- 新增 Artifact source policy
规则：
- 研究类任务要求引用来源
- 普通计划类任务仅鼓励来源
### 5) Artifact Policy Layer
新增 Artifact 专属系统规则，至少包含：
1. 何时必须生成 Artifact
2. 不要把完整文档重复发回聊天区
3. 模型只输出语义结构，不输出视觉样式
4. block 类型必须来自白名单
### 6) Stage Contract Layer
根据 stage 动态切换：
- `stage1`: 输出 artifact intent / outline / source policy / block plan
- `stage2`: 输出 `artifact_document_draft` 或 `artifact ops`
- `rewrite`: 只重写指定 block
### 7) Turn Context Layer
来自 turn metadata 的本次上下文：
- theme
- artifact kind
- source policy
- selected block
- rewrite instruction
- workspace mode
### 8) Output Schema Hint Layer
职责：
- 提醒模型当前 turn 存在严格 schema
- 明确优先满足结构合同，而不是自由排版
- 让 stage1 / stage2 / rewrite 三条链分别受约束
## 6.3 Prompt marker 约定
为避免重复拼装，建议引入新 marker：
- `【Artifact 交付策略】`
- `【Artifact 来源策略】`
- `【Artifact Stage 1 合同】`
- `【Artifact Stage 2 合同】`
- `【Artifact Rewrite 合同】`
规则与现有服务一致：
- 已包含 marker 时不重复追加
- 空 prompt 不插入空段落
- 每层都是可独立观测的 prompt section
## 6.4 前端到后端的 Artifact 意图字段
前端不直接传完整 prompt，而是透传结构化 Artifact 意图。
这里的接口只描述 Artifact 领域希望表达的最小语义，不等于 Lime 当前请求载荷的最终 wire contract。
当前仓库实际发送边界、`harness` 结构和 metadata 归一化，统一以执行效率路线图为准。
建议长期需要表达的 Artifact turn intent 包含：
```ts
interface ArtifactTurnMetadata {
artifact_mode?: "none" | "draft" | "rewrite";
artifact_kind?:
| "report"
| "roadmap"
| "prd"
| "brief"
| "analysis"
| "comparison"
| "plan";
artifact_stage?: "stage1" | "stage2" | "rewrite";
source_policy?: "required" | "preferred" | "none";
workbench_surface?: "right_panel" | "fullscreen";
artifact_request_id?: string;
artifact_target_block_id?: string;
artifact_rewrite_instruction?: string;
}
```
用途：
- 驱动 prompt 组装
- 写入 timeline
- 连接 ArtifactDocument 与本次 turn
## 6.5 Stage 1 system prompt 目标
Stage 1 的职责不是写正文，而是锁定结构。
必须输出：
- 是否需要 Artifact
- `kind`
- 建议标题
- source policy
- block 计划
- section 骨架
- 风险或缺失信息
不得输出：
- 完整长文
- 任意 HTML
- 样式参数
## 6.6 Stage 2 system prompt 目标
Stage 2 的职责是生成正式结构化交付物。
必须输出：
- `artifact_document_draft`
- 或增量 `artifact ops`
必须遵守：
- block 类型白名单
- source 绑定要求
- 不重复把全文写回消息区
## 6.7 Prompt 不是唯一控制点
本蓝图在此明确：
- prompt 负责行为引导
- turn 级 output schema 负责结构约束
- validator / repair 负责最后兜底
如果只做 prompt，不做 schema 和 validator，Workbench 最终只会退化成“更漂亮的 Markdown 容器”。
## 7. 运行时服务设计
## 7.1 新增服务
建议新增：
- `src-tauri/src/services/artifact_prompt_service.rs`
- `src-tauri/src/services/artifact_document_service.rs`
- `src-tauri/src/services/artifact_document_validator.rs`
- 可选 `src-tauri/src/services/artifact_generation_orchestrator.rs`
如果同步建设 `aster-rust`，则建议把运行时通用能力下沉为独立 runtime 模块：
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/runtime/thread.rs`
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/runtime/turn.rs`
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/runtime/item.rs`
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/runtime/event.rs`
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/runtime/prompt.rs`
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/runtime/schema.rs`
这部分是框架层远期形态参考，不构成 Lime 当前仓库的直接实施清单。
职责：
### `artifact_prompt_service`
- 组装 Artifact 相关 prompt 层
- 输出 stage1/stage2/rewrite 的最终 system prompt
- 记录 prompt stage 结果
### `artifact_document_service`
- 持久化 `ArtifactDocument`
- 管理版本、sources、导出记录
- 提供读模型给右侧 Workbench
### `artifact_document_validator`
- 做 schema 校验
- 做 repair
- 输出 telemetry 与错误信息
### `artifact_generation_orchestrator`
- 负责编排 Stage 1 / Stage 2
- 连接 timeline 与 store
- 负责失败回退
## 7.2 建议新增事件
建议新增以下运行时事件，既供前端消费，也供 timeline 投影：
- `artifact_intent_resolved`
- `artifact_stage_started`
- `artifact_stage_completed`
- `artifact_validation_repaired`
- `artifact_validation_failed`
- `artifact_version_persisted`
- `artifact_ready_for_render`
## 8. 前端工作台设计
## 8.1 右侧主工作台壳层
建议新增 `ArtifactWorkbenchShell`，统一承载：
- 阅读态
- 编辑态
- 版本条
- source drawer
- diff 入口
- 导出入口
### 阅读态
- 主渲染面
- 使用 block renderer
- `rich_text` block 才接 Tiptap static renderer
### 编辑态
- 仅对 `rich_text` block 进入 Tiptap 编辑
- 结构型 block 走专用编辑表单或轻量编辑器
### 来源抽屉
- 展示 `sourceId -> locator`
- 可跳转到 timeline item / web result / file path
## 8.2 与现有模块的关系
| 现有模块 | 蓝图定位 |
|------|------|
| `workbenchPreview.tsx` | 过渡期入口壳 |
| `WorkspaceCanvasContent.tsx` | 右侧容器事实源 |
| `ArtifactRenderer.tsx` | 兼容层入口，后续可下沉为 block renderer 包装器 |
| `NotionEditor.tsx` | `rich_text` block 编辑器 |
| `AgentThreadTimeline.tsx` | 过程和证据面 |
## 9. 数据与导出
## 9.1 产品层事实源
唯一长期事实源：
- `ArtifactDocument JSON`
附属快照：
- `editor_payload_snapshot`
- `markdown_snapshot`
- `render_manifest`
规则：
- 产品逻辑只依赖 `ArtifactDocument`
- 编辑器恢复依赖 `editor_payload_snapshot`
- 导出依赖 `markdown_snapshot` 或渲染适配
## 9.2 导出策略
v1 支持：
- Markdown
- HTML
- PDF
- JSON
其中：
- Markdown 面向可复用文本
- HTML/PDF 面向阅读和交付
- JSON 面向版本、调试、二次处理
## 10. 失败与回退
## 10.1 Stage 1 失败
- 回退为普通消息链路
- timeline 标记本次未进入 Artifact 主链
## 10.2 Stage 2 失败
- 仍创建 ArtifactDocument
- 状态记为 `failed`
- 保留最小 fallback 内容：
- 一个 `rich_text(markdown)` block
- 错误诊断进入 timeline / telemetry
## 10.3 validator 失败
- 优先 repair
- repair 后仍失败则降级为 `rich_text(markdown)`
- 不允许把不合法结构直接渲染成 ready
## 11. 验收标准
满足以下条件，才算架构蓝图落地正确：
1. 右侧 Workbench 成为高价值交付物默认展示面。
2. system prompt 的 Artifact 规则由后端统一组装，不由前端页面拼接。
3. Stage 1 与 Stage 2 的输出边界清晰，timeline 能区分。
4. `ArtifactDocument JSON` 与 `Tiptap/ProseMirror JSON` 的层级关系明确，不混淆。
5. 研究类交付物缺 source 时不会直接进入 ready。
6. 消息区不再重复整篇 Artifact。
7. `blueprint` 不承担 Artifact 主链的根抽象。
8. turn 级 output schema 已纳入主链，而不是只靠 prompt。
## 12. 本蓝图刻意不做
1. 不做无限开放的 block DSL。
2. 不做任意页面搭建器。
3. 不做完整协同编辑协议。
4. 不做全屏页优先的主导航改造。
5. 不做所有内容类型一次性统一迁移。
## 13. 实施顺序建议
建议严格按以下顺序推进：
1. 实现 `artifact_prompt_service` 与 prompt marker
2. 实现 Stage 1 / Stage 2 编排
3. 实现 validator / repair
4. 实现 `ArtifactWorkbenchShell`
5. 接入 3 个核心结构块：
- `hero_summary`
- `callout`
- `table`
6. 最后再接入 source drawer、diff、导出
原因：
**没有 prompt 合同和 validator，WorkBench 只会成为更漂亮的 Markdown 容器。**
docs/roadmap/artifacts/artifact-document-v1.md
+777
View File
@@ -0,0 +1,777 @@
# ArtifactDocument v1 协议草案
> 状态：提案
> 更新时间：2026-03-24
> 运行时边界：turn metadata、prompt 组装入口、runtime output schema 注入链以 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 为准；本文只定义 `ArtifactDocument v1` 的产品层协议与校验映射
> 依赖文档：`docs/roadmap/artifacts/roadmap.md`
> 架构蓝图：`docs/roadmap/artifacts/architecture-blueprint.md`
> 分层边界：`docs/roadmap/artifacts/framework-boundary.md`
> Prompt 合同：`docs/roadmap/artifacts/system-prompt-and-schema-contract.md`
> 目标：定义 Lime 高配版 Artifact Workbench 的第一版正式协议，包括产品层对象模型、模型输出契约、校验修复规则与渲染映射
## 1. 结论先行
本协议锁定以下架构决策：
1. `ArtifactDocument JSON` 是产品层长期事实源。
2. `Tiptap / ProseMirror JSON` 只作为编辑器层载荷，主要存在于 `rich_text` block 内。
3. 模型不负责视觉样式，只负责语义结构。
4. 前端不直接渲染“任意 Markdown 长文”为最终交付面，而是渲染语义 block。
5. validator / repair 是主链路必备组件，不允许把模型原始输出直接当成可靠协议。
一句话概括：
**模型输出结构，系统校验结构，渲染器呈现结构。**
这里还要补一句边界声明：
**`ArtifactDocument v1` 是产品层 persisted snapshot，不是 Aster runtime 的 thread/turn/item 协议。**
## 2. 适用范围
`ArtifactDocument v1` 适用于以下高价值输出：
- 报告
- 研究总结
- roadmap
- PRD
- 方案对比
- 执行摘要
- 调研表格
- 多来源整合文档
不适用于：
- 纯聊天短答
- 普通代码片段
- 单张图片生成结果
- 浏览器实时会话帧流本身
这些内容仍可通过现有 `Artifact` 兼容层或其他工作台承载。
## 3. 设计原则
## 3.1 语义优先
协议描述“这是什么内容”，而不是“它长什么样”。
允许：
- `hero_summary`
- `table`
- `callout`
- `citation_list`
不允许：
- 自定义颜色值
- 自定义边距
- 自定义字体大小
- 自定义 CSS class
## 3.2 产品对象优先于编辑器对象
产品层要能表达：
- 版本
- 来源
- 执行绑定
- block 语义
- 导出
这些不应被编辑器内部树结构主导。
## 3.3 Flat But Typed
`v1` 采用**扁平有序 block 列表**，不做复杂嵌套布局系统。
原因：
1. 降低模型输出难度。
2. 降低 validator / repair 复杂度。
3. 降低 renderer 实现成本。
4. 足够支持 80% 的报告类场景。
## 3.4 可降级
任何 block 在渲染失败、校验失败或组件不存在时，都必须可降级到：
- `rich_text`
- 或纯文本 fallback
## 4. 顶层对象模型
## 4.1 ArtifactDocumentV1
```ts
export type ArtifactKind =
| "report"
| "roadmap"
| "prd"
| "brief"
| "analysis"
| "comparison"
| "plan"
| "table_report";
export type ArtifactStatus =
| "draft"
| "streaming"
| "ready"
| "failed"
| "archived";
export interface ArtifactDocumentV1 {
schemaVersion: "artifact_document.v1";
artifactId: string;
workspaceId?: string;
threadId?: string;
turnId?: string;
kind: ArtifactKind;
title: string;
status: ArtifactStatus;
language: "zh-CN";
summary?: string;
blocks: ArtifactBlockV1[];
sources: ArtifactSourceV1[];
metadata: ArtifactDocumentMetaV1;
}
export interface ArtifactDocumentMetaV1 {
theme?:
| "general"
| "document"
| "knowledge"
| "planning"
| "social-media";
audience?: string;
intent?: string;
generatedBy?: "agent" | "user" | "automation";
rendererHints?: {
density?: "comfortable" | "compact";
defaultExpandedSections?: string[];
};
sourceRunBinding?: {
threadId?: string;
turnId?: string;
itemIds?: string[];
};
exportHints?: {
preferredFormats?: Array<"md" | "html" | "pdf" | "json">;
};
}
```
## 4.2 顶层约束
1. `schemaVersion` 必须固定为 `artifact_document.v1`。
2. `title` 必须为非空字符串。
3. `blocks` 至少 1 个，建议不超过 40 个。
4. `sources` 可以为空，但如果文档声称“基于搜索/网页/文件”，则不应为空。
5. `language` 在 `v1` 固定为 `zh-CN`，避免多语言排版漂移。
## 5. Block 模型
## 5.1 通用字段
```ts
export interface ArtifactBlockBase {
id: string;
type: ArtifactBlockType;
sectionId?: string;
hidden?: boolean;
sourceIds?: string[];
}
export type ArtifactBlockType =
| "section_header"
| "hero_summary"
| "key_points"
| "rich_text"
| "callout"
| "table"
| "checklist"
| "metric_grid"
| "quote"
| "citation_list"
| "image"
| "code_block"
| "divider";
```
规则：
1. `id` 在同一文档内必须唯一。
2. `sourceIds` 只能引用 `sources[]` 中已存在的 id。
3. `sectionId` 只作归组标记，不引入嵌套 DOM 协议。
## 5.2 Block 定义
### A. `section_header`
用于开始一个新章节。
```ts
export interface SectionHeaderBlock extends ArtifactBlockBase {
type: "section_header";
title: string;
description?: string;
}
```
约束：
1. `title` 必填。
2. 文档首块不强制必须是 `section_header`。
### B. `hero_summary`
用于顶部摘要卡。
```ts
export interface HeroSummaryBlock extends ArtifactBlockBase {
type: "hero_summary";
eyebrow?: string;
title?: string;
summary: string;
highlights?: string[];
}
```
约束：
1. `summary` 必填，建议 60 到 220 字。
2. `highlights` 建议 2 到 5 项。
### C. `key_points`
用于快速结论列表。
```ts
export interface KeyPointsBlock extends ArtifactBlockBase {
type: "key_points";
title?: string;
items: string[];
}
```
约束：
1. `items` 至少 2 项，建议不超过 7 项。
### D. `rich_text`
通用正文块。
```ts
export interface RichTextBlock extends ArtifactBlockBase {
type: "rich_text";
contentFormat: "prosemirror_json" | "markdown";
content: unknown;
}
```
规则：
1. 长期建议以 `prosemirror_json` 为主。
2. `markdown` 只作为兼容输入与 repair fallback。
3. `rich_text` 是唯一允许承载大段连续正文的 block。
### E. `callout`
用于提醒、结论、风险、建议。
```ts
export interface CalloutBlock extends ArtifactBlockBase {
type: "callout";
tone: "info" | "success" | "warning" | "danger" | "neutral";
title?: string;
body: string;
}
```
### F. `table`
```ts
export interface TableBlock extends ArtifactBlockBase {
type: "table";
title?: string;
columns: string[];
rows: string[][];
}
```
约束：
1. `columns` 至少 2 列。
2. 每行单元格数量应与列数一致。
3. 单元格内容必须是字符串，`v1` 不支持复杂嵌套对象。
### G. `checklist`
```ts
export interface ChecklistBlock extends ArtifactBlockBase {
type: "checklist";
title?: string;
items: Array<{
id: string;
text: string;
state: "todo" | "doing" | "done";
}>;
}
```
### H. `metric_grid`
```ts
export interface MetricGridBlock extends ArtifactBlockBase {
type: "metric_grid";
title?: string;
metrics: Array<{
id: string;
label: string;
value: string;
note?: string;
tone?: "neutral" | "success" | "warning" | "danger";
}>;
}
```
约束：
1. 建议 2 到 8 个 metric。
2. `value` 一律字符串化，避免渲染层处理 number/date 混乱。
### I. `quote`
```ts
export interface QuoteBlock extends ArtifactBlockBase {
type: "quote";
text: string;
attribution?: string;
}
```
### J. `citation_list`
```ts
export interface CitationListBlock extends ArtifactBlockBase {
type: "citation_list";
title?: string;
items: Array<{
sourceId: string;
note?: string;
}>;
}
```
### K. `image`
```ts
export interface ImageBlock extends ArtifactBlockBase {
type: "image";
url: string;
alt?: string;
caption?: string;
}
```
### L. `code_block`
```ts
export interface CodeBlock extends ArtifactBlockBase {
type: "code_block";
language?: string;
title?: string;
code: string;
}
```
### M. `divider`
```ts
export interface DividerBlock extends ArtifactBlockBase {
type: "divider";
}
```
## 5.3 Block 联合类型
```ts
export type ArtifactBlockV1 =
| SectionHeaderBlock
| HeroSummaryBlock
| KeyPointsBlock
| RichTextBlock
| CalloutBlock
| TableBlock
| ChecklistBlock
| MetricGridBlock
| QuoteBlock
| CitationListBlock
| ImageBlock
| CodeBlock
| DividerBlock;
```
## 6. Source 模型
```ts
export type ArtifactSourceType =
| "web"
| "file"
| "tool"
| "message"
| "search_result";
export interface ArtifactSourceV1 {
id: string;
type: ArtifactSourceType;
label: string;
locator?: {
url?: string;
path?: string;
lineStart?: number;
lineEnd?: number;
toolCallId?: string;
messageId?: string;
};
snippet?: string;
reliability?: "primary" | "secondary" | "derived";
}
```
规则：
1. `label` 必填。
2. `snippet` 为可选摘录，不是完整内容镜像。
3. `locator` 用于跳转，不要求所有字段齐全。
## 7. Version 模型
`v1` 不要求把版本协议塞进文档正文，但必须预留独立版本对象：
```ts
export interface ArtifactVersionRecordV1 {
id: string;
artifactId: string;
versionNo: number;
documentSnapshot: ArtifactDocumentV1;
editorPayloads?: Record<string, unknown>;
markdownSnapshot?: string;
summary?: string;
createdBy: "agent" | "user" | "automation";
createdAt: string;
}
```
## 8. 模型输出契约
## 8.1 模型不应该直接输出什么
禁止作为正式协议输出：
- 任意 CSS
- 任意 HTML 模板
- 组件名 + 样式参数混合
- 整篇只靠纯自然语言长文承载结构
## 8.2 模型应该输出什么
模型应输出以下两类之一：
### 模式 A：一次性草稿
适用于：
- 首次生成
- 非流式离线生成
- 简单交付物
输出对象：
```ts
export interface ArtifactDraftEnvelope {
type: "artifact_document_draft";
document: ArtifactDocumentV1;
}
```
### 模式 B：增量操作
适用于：
- 流式生成
- 多轮修订
- 局部改写
输出对象：
```ts
export type ArtifactOpEnvelope =
| {
type: "artifact.begin";
artifactId: string;
kind: ArtifactKind;
title: string;
}
| {
type: "artifact.meta.patch";
artifactId: string;
patch: Partial<ArtifactDocumentMetaV1>;
}
| {
type: "artifact.source.upsert";
artifactId: string;
source: ArtifactSourceV1;
}
| {
type: "artifact.block.upsert";
artifactId: string;
block: ArtifactBlockV1;
}
| {
type: "artifact.block.remove";
artifactId: string;
blockId: string;
}
| {
type: "artifact.complete";
artifactId: string;
summary?: string;
}
| {
type: "artifact.fail";
artifactId: string;
reason: string;
};
```
## 8.3 推荐生成流程
推荐两段式：
1. `artifact_intent`
- 判断是否需要 Artifact
- 判断文档 kind
- 判断是否需要 sources
2. `artifact_document_draft` 或 `artifact ops`
- 正式生成结构化内容
这样比“一次自然语言长回复”更稳定。
## 8.4 模型约束规则
提示词应明确要求模型：
1. 优先输出有限 block 集，不要发明新 block 类型。
2. 每个 block 只承载单一职责。
3. 所有来源型结论必须绑定 `sourceIds` 或 `citation_list`。
4. 不要重复把整篇文档再输出到聊天消息区。
5. block id 必须稳定且语义化，如 `hero`, `market-table`, `next-steps`。
6. 需要大段正文时，使用 `rich_text` block，而不是拆成很多碎 paragraph block。
## 9. Validator 规则
## 9.1 文档级校验
必须校验：
1. `schemaVersion` 是否匹配。
2. `title` 是否存在。
3. `kind` 是否在白名单中。
4. `blocks` 是否非空。
5. `block.id` 是否唯一。
6. `sourceIds` 是否都可解析。
## 9.2 Block 级校验
### `hero_summary`
- `summary` 必填
- `highlights` 非字符串项直接丢弃
### `table`
- `columns.length >= 2`
- 每行长度与列数对齐
### `checklist`
- item `state` 只能是 `todo / doing / done`
- `text` 为空则删除该项
### `metric_grid`
- `label` 与 `value` 必填
- 超过 8 项时保留前 8 项
### `citation_list`
- `sourceId` 必须存在于 `sources`
### `rich_text`
- `contentFormat` 只能是 `prosemirror_json` 或 `markdown`
- `content` 不能为空
## 9.3 Source 级校验
1. `id` 必须唯一。
2. `label` 必填。
3. `type` 必须在白名单中。
4. `snippet` 超长时截断，不作为正文存档。
## 10. Repair 策略
validator 失败时，不应直接放弃整份文档。
`v1` 采用保守修复策略：
## 10.1 文档级 repair
1. 缺 `title`
- 用首个 `section_header.title`
- 再不行用任务标题
- 再不行用 `未命名交付物`
2. 缺 `blocks`
- 将原始文本包成一个 `rich_text(markdown)` block
3. 重复 block id
- 自动追加稳定后缀，如 `-2`、`-3`
## 10.2 Block 级 repair
1. 不支持的 block type
- 降级为 `rich_text(markdown)`
2. `table` 行列不齐
- 自动补空字符串到齐平
3. `citation_list` 引用了不存在的 source
- 删除非法项
- 若最终为空，整个 block 删除
4. `metric_grid` 非法 value
- 强制转字符串
5. `callout.body` 为空
- 降级为 `rich_text(markdown)`
6. `rich_text.prosemirror_json` 无法解析
- 降级为 `rich_text(markdown)`
## 10.3 最终 fallback
如果整份文档经过 repair 仍不合法：
1. 保留 `artifactId / kind / title`
2. 将模型原始输出包成单个 `rich_text(markdown)` block
3. 标记 `metadata.rendererHints.density = "comfortable"`
4. 在 telemetry 中记录 repair failure
## 11. Renderer 映射
| Block 类型 | 建议组件 | 失败回退 |
|------|------|------|
| `section_header` | `ArtifactSectionHeader` | `rich_text` |
| `hero_summary` | `ArtifactHeroSummaryCard` | `rich_text` |
| `key_points` | `ArtifactKeyPointsList` | `rich_text` |
| `rich_text` | `ArtifactRichTextRenderer` | 纯文本 |
| `callout` | `ArtifactCallout` | `rich_text` |
| `table` | `ArtifactStructuredTable` | `rich_text` |
| `checklist` | `ArtifactChecklist` | `rich_text` |
| `metric_grid` | `ArtifactMetricGrid` | `rich_text` |
| `quote` | `ArtifactQuote` | `rich_text` |
| `citation_list` | `ArtifactCitationList` | 删除 |
| `image` | `ArtifactImageBlock` | 占位图 |
| `code_block` | 复用现有 `CodeRenderer` | `rich_text` |
| `divider` | `ArtifactDivider` | 删除 |
## 11.1 RichText Renderer 约束
`ArtifactRichTextRenderer` 只负责：
- 解析 `rich_text` 内容
- 渲染内联 mark
- 渲染段落、标题、列表、引用、代码
不负责：
- 指标卡
- 提示框
- 表格型业务块
- 来源列表
这些必须由业务 block 组件承载。
## 12. Prompt 模板约束
本节只定义 `ArtifactDocument v1` 需要的结构约束，不重新定义 runtime prompt 入口。
也就是说：
- “哪些 turn 进入 Artifact 主链”
- “turn metadata 如何归一化”
- “output schema 在哪里注入”
这些执行层问题仍以 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 为准。
系统提示词应增加以下硬约束：
1. 当用户请求的是报告、roadmap、PRD、比较、研究、整合总结时，优先输出 `ArtifactDocument v1`。
2. 先给 `hero_summary` 或 `key_points`，再给主体 block。
3. 对来源敏感内容必须附带 source。
4. 不要输出 CSS、HTML class、视觉说明。
5. 不要在消息正文里重复完整文档，只输出简短说明和下一步。
## 13. 仓库落地建议
建议新增：
```text
src/lib/artifact-document/schema.ts
src/lib/artifact-document/validator.ts
src/lib/artifact-document/repair.ts
src/lib/artifact-document/adapters/tiptap.ts
src/lib/artifact-document/examples.ts
```
职责建议：
- `schema.ts`：类型与 zod/schema 定义
- `validator.ts`：协议合法性检查
- `repair.ts`：保守修复逻辑
- `adapters/tiptap.ts`：`rich_text` 与 Tiptap 互转
- `examples.ts`：供 prompt / tests / storybook 复用的样例
后端建议新增：
```text
src-tauri/src/services/artifact_document_service.rs
src-tauri/src/services/artifact_document_validator.rs
```
## 14. 本版刻意不做
1. 不做复杂栅格布局协议。
2. 不做任意嵌套 section tree。
3. 不做通用组件 DSL。
4. 不做样式 token 下发。
5. 不做完全开放的自定义 block 注册。
`v1` 的目标是稳定，不是无限灵活。
## 15. 最终建议
如果你们要把“漂亮回复”真正做成产品能力，实施顺序应该是：
1. 先锁定 `ArtifactDocument v1`
2. 再做 validator / repair
3. 再做 renderer registry
4. 再做模型输出约束
5. 最后才是视觉细化
原因很简单：
**没有协议，渲染只是化妆。**
docs/roadmap/artifacts/framework-boundary.md
+356
View File
@@ -0,0 +1,356 @@
# Lime Artifact Workbench 与 Aster Runtime 分层边界
> 状态：提案
> 更新时间：2026-03-24
> 运行时边界：凡涉及发送边界、runtime metadata、Team 委派、Op/Event 收口、状态同步，均以 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 为准；本文只定义长期框架分层原则与远期边界
> 关联文档：
> - `docs/roadmap/artifacts/roadmap.md`
> - `docs/roadmap/artifacts/architecture-blueprint.md`
> - `docs/roadmap/artifacts/system-prompt-and-schema-contract.md`
> 目标：明确 Lime 产品层、Aster 框架层、Blueprint 规划模块三者的长期职责边界，避免后续把产品协议、任务规划、运行时编排混成一团
## 1. 结论先行
本文件锁定以下分层判断：
1. **Lime 持有产品层交付物模型**
- `ArtifactDocument`
- Workbench UI
- block renderer / editor / source drawer / export
- `report / roadmap / prd / analysis / comparison` 这些产品语义
2. **Aster 应补齐通用 runtime substrate**
- `thread / turn / item / event`
- prompt 组装管线
- turn 级 `output schema`
- approval / elicitation / interrupt / retry
- 运行时状态持久化与事件流
3. **Blueprint 不是 Artifact Workbench 的根抽象**
- Blueprint 应定位为长期规划与执行模块
- 适合承接需求蓝图、任务树、TDD loop、worker coordination
- 不适合作为 Lime 文档交付协议或聊天主运行时
4. **Codex 值得参考的是运行时协议，不是它的 artifact 名字**
- `codex` 的强项在 `turn/start + outputSchema + item events + thread state`
- `codex-artifacts` 则是本地 JS runtime 的 presentation/spreadsheet 工具，不是报告文档协议
一句话总结：
**Lime 负责“交付物产品”，Aster 负责“代理运行时”，Blueprint 负责“长周期规划”。**
## 2. 事实依据
## 2.1 Lime 现役事实
来自以下文件：
- `src-tauri/src/commands/aster_agent_cmd/runtime_turn.rs`
- `src-tauri/src/commands/aster_agent_cmd/prompt_context.rs`
- `src-tauri/src/services/memory_profile_prompt_service.rs`
- `src-tauri/src/services/web_search_prompt_service.rs`
- `src/components/agent/chat/hooks/agentRuntimeAdapter.ts`
可确认：
1. Lime 已经有以 turn 为单位的运行链路。
2. system prompt 已经是后端分层组装，而不是纯前端拼接。
3. 前端只需要透传结构化 metadata，就可以驱动不同运行策略。
4. Lime 当前缺的是正式 Artifact 产品协议与工作台闭环，而不是重新发明 thread/turn 的概念。
## 2.2 Aster Blueprint 现役事实
来自以下文件：
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/blueprint/README.md`
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/blueprint/types.rs`
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/blueprint/task_tree_manager.rs`
- `/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/blueprint/worker_executor.rs`
可确认：
1. Blueprint 的中心对象是 `Blueprint / TaskTree / TaskNode / Checkpoint / WorkerAgent`。
2. 它的 `ArtifactType` 是 `file / patch / command`，明显偏代码执行产物。
3. prompt 模板围绕 TDD 测试、写代码、重构，不围绕正式交付文档。
4. Timeline 也是任务执行事件，不是聊天交付事件。
因此：
**Blueprint 与 Artifact Workbench 存在概念相邻，但语义核心不同。**
## 2.3 Codex 现役事实
来自以下文件：
- `/Users/coso/Documents/dev/rust/codex/codex-rs/app-server/README.md`
- `/Users/coso/Documents/dev/rust/codex/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts`
- `/Users/coso/Documents/dev/rust/codex/codex-rs/app-server/src/thread_state.rs`
- `/Users/coso/Documents/dev/rust/codex/codex-rs/codex-api/src/common.rs`
- `/Users/coso/Documents/dev/rust/codex/codex-rs/core/src/memories/phase1.rs`
- `/Users/coso/Documents/dev/rust/codex/codex-rs/artifacts/README.md`
可确认：
1. `turn/start` 支持 turn 级 `outputSchema`。
2. app-server 明确定义了 `thread / turn / item / item delta / approval / interruption` 协议。
3. 内部已经把结构化输出作为 runtime 能力，而不是业务页面私货。
4. `codex-artifacts` 只是受控 JS artifact runtime，不是文档产品协议。
因此：
**Codex 给我们的参考点，是 runtime substrate 的形状。**
## 3. 分层总图
```mermaid
flowchart TB
User["用户"]
subgraph Lime["Lime 产品层"]
UI["Conversation + Artifact Workbench + Inspector"]
Product["ArtifactDocument / Source UX / Export UX"]
Policy["Artifact Kind / Source Policy / UX Rules"]
end
subgraph Aster["Aster Runtime 层"]
Thread["Thread / Turn / Item"]
Events["Runtime Event Bus"]
Prompt["Prompt Composer"]
Schema["Output Schema / Validator Contract"]
Control["Approval / Elicitation / Interrupt / Retry"]
Persist["Runtime State Store"]
end
subgraph Planning["Blueprint 模块"]
BP["Blueprint"]
Tree["TaskTree / Checkpoint"]
Worker["Worker / TDD / Sandbox"]
end
subgraph Model["模型与工具层"]
LLM["LLM"]
Tools["Tools / Web / File / Exec"]
end
User --> UI
UI --> Product
UI --> Policy
Product --> Thread
Policy --> Prompt
Thread --> Events
Prompt --> Schema
Schema --> LLM
LLM --> Tools
Tools --> Events
Events --> Persist
Events --> Product
Thread -. optional planning handoff .-> BP
BP --> Tree
Tree --> Worker
Worker --> Events
```
## 4. 职责边界表
| 能力 | Lime 产品层 | Aster Runtime 层 | Blueprint 模块 |
|------|------|------|------|
| 线程 / 回合 / item 生命周期 | 不持有根定义 | 持有 | 可消费 |
| turn 级 `output schema` | 提供业务 schema | 持有执行通道 | 不负责 |
| prompt 分层组装 | 提供 Artifact 业务片段 | 持有总组装器 | 仅自有规划 prompt |
| 正式交付物对象 | 持有 `ArtifactDocument` | 不持有业务语义 | 不持有 |
| block renderer / editor | 持有 | 不持有 | 不持有 |
| source policy | 持有业务规则 | 负责执行与校验挂钩 | 不持有 |
| approvals / elicitation / interrupt | UI 展示与交互 | 持有协议与状态 | 可复用 |
| task tree / TDD loop | 仅作为某类 Artifact 来源 | 可桥接 | 持有 |
| file / patch / command 代码产物 | 只做引用展示 | 可流转 | 持有 |
## 5. 为什么 Blueprint 不应直接接管 Artifact Workbench
## 5.1 对象模型不匹配
Blueprint 的产物中心是：
- 模块
- 任务
- 测试
- patch
- command
Lime Artifact Workbench 的产物中心是：
- 文档
- block
- source
- version
- reading/edit/export
这不是同一类对象。
## 5.2 生命周期不匹配
Blueprint 关注：
- 立项
- 拆任务
- 执行
- 回滚
- 验收
Artifact Workbench 关注：
- 生成草稿
- 结构校验
- 工作台阅读
- 局部改写
- 版本 diff
- 导出分享
前者是执行治理，后者是交付体验。
## 5.3 prompt 不匹配
Blueprint 的 prompt 语言天然偏：
- 写测试
- 写实现
- 修复错误
- 重构代码
Artifact Workbench 要控制的是：
- 交付物 kind
- source policy
- block plan
- report / roadmap / comparison 结构
直接混用会让 runtime 概念污染产品协议。
## 6. 应从 Codex 借鉴什么
## 6.1 必须借鉴
1. **turn 级输出 schema**
- 每次调用都能带一个明确的结构目标
- 不把“结构化输出”写死成某个固定产品
2. **thread / turn / item / delta 协议**
- UI 能增量渲染
- 持久化层能重建历史
- 工具、计划、消息、文件改动可归一化
3. **独立的事件流**
- `turn_started`
- `item_started`
- `item_delta`
- `item_completed`
- `turn_completed`
4. **approval / elicitation / interrupt 是 runtime 一等公民**
- 不能散落在某个单独产品页面中硬编码
## 6.2 不应照搬
1. 不照搬 `codex-artifacts` 的 JS runtime 工具模型。
2. 不照搬终端/TUI 的 UI 心智。
3. 不把 Lime 的文档协议退化成单一 `outputSchema` 结果对象。
因为 Lime 的核心仍然是：
**多轮对话中的正式交付物工作台。**
## 7. 建议中的 Aster Runtime 新边界
这里要明确：
- 本节描述的是 **Aster 框架层的目标形状参考**
- 不是 Lime 当前仓库的直接实施主计划
- 如果与 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 的当前迁移顺序、协议收口方式冲突，以后者为准
建议在 `aster-rust` 中，把通用 agent runtime 从 `blueprint` 旁边独立出来，而不是继续把所有能力堆进 `blueprint/`。
建议中的模块形态：
```text
crates/aster/src/runtime/
mod.rs
thread.rs
turn.rs
item.rs
event.rs
prompt.rs
schema.rs
approval.rs
persistence.rs
orchestration.rs
```
建议职责：
- `thread.rs`：线程与上下文边界
- `turn.rs`：turn 生命周期、输入、状态机
- `item.rs`：消息、plan、tool、artifact stage 等 item 定义
- `event.rs`：统一事件类型与 delta
- `prompt.rs`：分层 prompt composer
- `schema.rs`：turn 级输出 schema 注册与校验入口
- `approval.rs`：approval / elicitation / interrupt / retry
- `persistence.rs`：runtime state 存储
- `orchestration.rs`：Stage Runner、模型调用与失败恢复
## 8. Lime 与 Aster 的连接方式
本节时序图只表达长期职责连接，不单独定义 Lime 当前发送协议字段名。
建议 Lime 不直接自己实现第二套完整 runtime，而是成为 Aster runtime 的产品适配层：
```mermaid
sequenceDiagram
participant FE as Lime Frontend
participant App as Lime App Service
participant RT as Aster Runtime
participant LLM as Model
participant WB as Artifact Workbench
FE->>App: submit_turn(message + artifact metadata)
App->>RT: turn.start(input + prompt layers + output schema refs)
RT->>LLM: response request
LLM-->>RT: item deltas / final output
RT-->>App: turn events + item events + validated result
App-->>WB: ArtifactDocument / timeline / diff
WB-->>FE: render delivery view
```
这里的关键是：
- Lime 提供业务语义和工作台
- Aster 提供运行时协议和编排
- 两者通过 turn metadata、schema id、event taxonomy 对接
- 但 Lime 当前仓库里的实际发送边界和 runtime 收口步骤，仍按执行效率路线图推进
## 9. 实施顺序建议
本节属于框架层远期演进建议，不覆盖 Lime 当前仓库已确定的 P1 / P2 / P3 / P4 执行顺序。
## Phase A：先立 runtime 边界
- 在文档和接口层确认 Aster runtime 与 Blueprint 分家
- 定义 `thread / turn / item / event / schema`
## Phase B：再接 Artifact 主链
- Lime 将 Stage 1 / Stage 2 接到 Aster runtime turn
- 引入 Artifact 专用 output schema
## Phase C：最后接 Blueprint
- 仅在需要“长周期规划 / 多 worker 执行”时，把 Blueprint 作为特殊 item 或 planning capability 接入
- 不让 Blueprint 接管普通 report / prd / roadmap 生成
## 10. 最终决策
长期最稳的架构不是：
**Blueprint 不断膨胀，最后既当聊天 runtime，又当 Artifact 协议，又当任务执行器。**
长期最稳的架构应该是：
**Codex 式 runtime substrate + Blueprint 式 planning module + Lime 式 artifact product layer。**
docs/roadmap/artifacts/roadmap.md
+903
View File
@@ -0,0 +1,903 @@
# Lime 高配版 Artifacts 路线图
> 状态：进行中，P1 / P2 已落地，P3 已闭环，rewrite typed patch 合同已落地
> 更新时间：2026-03-25
> 运行时边界：发送边界、runtime metadata、Team 委派、协议瘦身以 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 为准；本文只定义 Artifact 产品层与 Workbench 主线
> 目标：把 Lime 从“能显示文件/画布的聊天工作台”升级为“交付物优先的 Artifact Workbench”，让回复不再只是普通 Markdown，而是可扫描、可编辑、可版本化、可复用的正式产物
>
> 配套文档：
> - `docs/roadmap/artifacts/architecture-blueprint.md`
> - `docs/roadmap/artifacts/artifact-document-v1.md`
> - `docs/roadmap/artifacts/framework-boundary.md`
> - `docs/roadmap/artifacts/system-prompt-and-schema-contract.md`
## 1. 文档依据
本文不是从抽象概念反推，而是基于当前仓库现役实现与设计约束编写。
关键事实源：
- `docs/aiprompts/overview.md`
- `docs/aiprompts/design-language.md`
- `src/lib/artifact/types.ts`
- `src/lib/artifact/parser.ts`
- `src/components/artifact/ArtifactRenderer.tsx`
- `src/components/artifact/ArtifactToolbar.tsx`
- `src/components/agent/chat/components/MarkdownRenderer.tsx`
- `src/components/agent/chat/hooks/useArtifactDisplayState.ts`
- `src/components/agent/chat/components/AgentThreadTimeline.tsx`
- `src/components/agent/chat/workspace/workbenchPreview.tsx`
- `src/components/agent/chat/workspace/WorkspaceCanvasContent.tsx`
- `src/components/content-creator/core/CanvasContainer/CanvasContainer.tsx`
- `src/components/content-creator/canvas/document/DocumentRenderer.tsx`
- `src/components/content-creator/canvas/document/editor/NotionEditor.tsx`
- `src-tauri/src/services/agent_timeline_service.rs`
从这些事实源可以确认：
1. Lime 已经是 `Artifact First` 方向，而不是纯聊天产品。
2. 当前前端已经具备 `ArtifactRenderer + CanvasWorkbench + Timeline + Tiptap 编辑器` 这四块关键底座。
3. 当前 Artifact 系统仍以“文件快照/Markdown 内容”作为主要载体，还不是“结构化交付物协议”。
4. 当前回复的美观度问题，本质不是“模型不会写”，而是“产物协议、渲染层、交互层还没有真正收敛成一个系统”。
## 1.1 当前已落地能力
以下链路已经在当前仓库进入实现态：
1. `runtime_turn` 已接入 Artifact 专属 prompt 组装服务。
2. Artifact 回合已支持 turn-level `output_schema` 注入，不再只依赖 prompt hint。
3. 后端已具备 `ArtifactDocument v1` 的 validator / repair / fallback / workspace 落盘能力。
4. Timeline snapshot metadata 已可回灌 `artifactDocument`，前端在 `content` 为空时也能直接渲染结构化文档。
5. 前端已落地最小 `artifact-protocol` 壳层，用于统一 runtime metadata 中的 `artifactDocument` 与 `artifact_path(s)` 读取合同。
6. 后端已支持最小 `artifact_ops` 增量协议，可把 `artifact.upsert_block / attach_source / finalize_version` 等操作应用到已有 `ArtifactDocument` 并生成新版本。
7. 右侧已接入最小 `ArtifactWorkbenchShell`，包含阅读面与 `概览 / 来源 / 版本 / 差异` inspector。
8. 当前版本已支持最小 block diff 摘要，以及来源项 / 差异项到文档 block 的 Workbench 内跳转。
9. `rewrite` 已把 `artifact_target_block_id` 贯通到 prompt / output schema / ops apply / persist 链路，非目标 block 的 op 会在运行时被忽略并记录 issue。
10. `rewrite` 现已支持专用 `artifact_rewrite_patch` envelope，并保留 `artifact_ops` 兼容回退，用于逐步收紧模型输出合同。
这意味着当前主线已经从“只有路线图”推进到“结构合同 + 版本快照 + Workbench inspector 闭环”。当前仍然属于后续阶段的，主要是更细粒度的 typed rewrite patch 合同，以及编辑态 / 展示态 / 导出态的进一步同源。
## 2. 现状判断
## 2.1 Lime 已经具备的能力
- 有聊天主入口与工作台分栏能力，支持右侧预览区。
- 有 Artifact 类型系统、解析器、统一渲染入口、工具栏与列表。
- 有 Document Canvas 与 Tiptap 编辑器，可承载更高级的文档编辑体验。
- 有 Agent Timeline，可记录 turn、item、artifact snapshot、warning、error。
- 有 Workspace 概念，可作为 Artifact 的上下文边界与持久化边界。
这说明 Lime 不需要再造第二套“文档产品”，而是要把现有能力从“散件”收敛成“Artifact Workbench”。
## 2.2 当前短板
当前体验之所以还不够像 Ribbi / Manus / Claude Artifacts 的高配版本，主要有五个结构性问题：
### 1) 回复仍以消息文本为主，Artifact 只是附属物
`MarkdownRenderer.tsx` 负责把 assistant 文本渲染成较好的 Markdown，但主心智仍然是“消息正文”。
这会导致：
- 模型把重要内容写在消息里，而不是交付区
- 视觉上仍然像聊天气泡，而不是正式报告
- 后续编辑、复用、导出、版本比较都不自然
### 2) Artifact 模型还是“文件/片段导向”，不是“结构化文档导向”
当前 `Artifact` 的核心字段是：
- `type`
- `title`
- `content`
- `meta`
这对代码块、HTML、Mermaid 足够，但对高质量报告类交付物不够。
缺的是：
- section / block 层级
- citations / references
- summary / scorecard / callout / table / checklist 等语义块
- 版本差异与局部 patch
### 3) Timeline、Canvas、Document Editor 还没有同源
当前：
- Timeline 记录的是过程事件
- Canvas 展示的是当前 artifact 预览
- DocumentCanvas 编辑的是内容画布
三者都与 Artifact 相关，但还没有统一到同一个交付物主模型。
### 4) 当前 parser 仍以 fence/markdown 提取为主
`src/lib/artifact/parser.ts` 现在主要做：
- ` ```artifact ... ` 提取
- 普通代码块推断
- plainText 与 artifact 分离
这适合兼容模式，不适合作为高配版的长期事实源。
高配版必须从“解析文本里有什么 artifact”升级为“运行时明确产出什么 artifact block”。
### 5) 编辑态与展示态还不是一个产品闭环
当前有 Tiptap 编辑器，但它主要存在于 `document canvas` 内。
高配版需要的是：
- 先生成
- 再预览
- 再局部重写
- 再比对版本
- 再导出/复用
这些动作要围绕同一个 Artifact Document 完成，而不是在聊天、画布、文件之间来回切换。
## 3. 核心决策
## 3.1 产品主张
Lime 的高配版 Artifacts 应该明确采用：
**Chat for reasoning, Artifact for delivery。**
含义：
- 聊天区负责目标澄清、任务推进、过程解释、追问与协作
- Artifact Workbench 负责正式产物的创建、阅读、编辑、对比、导出与沉淀
- Timeline 负责过程透明，而不是承担最终阅读面
换句话说：
**消息区不是最终作品区。**
## 3.2 长期事实源
长期统一到：
**结构化 Artifact Document + 版本化 Block Tree + 可编辑 Workbench**
而不是：
- 普通 Markdown 长文
- 单个大字符串 HTML
- 临时 artifact fence 解析结果
## 3.3 技术主栈决策
高配版建议采用：
**Tiptap / ProseMirror 作为主编辑引擎，但不作为顶层长期 canonical model。**
更准确地说：
- `ArtifactDocument JSON` 才是产品层长期事实源
- `Tiptap / ProseMirror JSON` 是编辑器层载荷与 rich_text block 的工作表示
- `Markdown / HTML / PDF` 是导出与分发表达
理由：
1. Tiptap / ProseMirror 非常适合富文本编辑、schema 约束、节点扩展、局部事务与协同增强。
2. 但它的 JSON 结构本质上贴近编辑器内部 schema，不适合作为整个平台的顶层产品对象。
3. Lime 的 Artifact 不只是富文本，还包括来源、评分块、表格块、执行绑定、浏览器会话引用、导出记录等领域对象。
4. 如果把这些全部硬塞进 ProseMirror 节点树，未来的迁移、查询、导出、跨端实现和协议演进成本会被放大。
因此建议采用四层模型：
- 兼容输入层：Markdown / artifact fence / 文件快照
- 运行时协议层：Artifact Parts / Block Ops
- 产品持久化层：ArtifactDocument JSON
- 编辑器载荷层：RichText Block 内可使用 Tiptap / ProseMirror JSON
## 3.4 框架层决策
在重新评估 `aster-rust blueprint` 与 `codex-rs` 之后，路线图增加一条硬决策：
**不要把 Artifact Workbench 直接建立在 Blueprint 抽象之上。**
更合适的长期分层是：
- Lime：产品层交付物与工作台
- Aster Runtime：通用 `thread / turn / item / event / output schema`
- Blueprint：可选的长周期 planning module
判断依据见：
- `docs/roadmap/artifacts/framework-boundary.md`
这条决策很关键，因为一旦把文档交付协议和任务树执行框架混在一起，后面每扩一种 Artifact 类型，都会反向污染 runtime。
## 4. 目标与非目标
## 4.1 总目标
为 Lime 建立一套统一的 Artifact Workbench，让高价值回复默认沉淀为：
`结构化交付物 -> 专用阅读面 -> 局部可编辑 -> 可版本比较 -> 可导出复用`
## 4.2 子目标
1. 让“报告、方案、规划、研究、执行摘要、表格型结论”默认进入 Artifact Workbench，而不是只停留在消息正文。
2. 让回复具备更强的视觉层级：摘要卡、提示框、表格、评分块、引用块、来源区、版本条。
3. 让 Artifact 在会话中持续增量更新，而不是每轮都生成一个新的孤岛文件。
4. 让编辑态、展示态、导出态围绕同一份 Artifact Document 运转。
5. 让 Service Skill、Automation、Browser Assist、Theme Workbench 的产物最终都能落到同一套 Artifact Workbench。
## 4.3 非目标
1. 不做通用网页搭建器。
2. 不在第一阶段做任意 React 组件执行沙箱。
3. 不让模型直接输出大量不受控 HTML 作为主协议。
4. 不重写现有全部 Canvas，只做收敛与增量替换。
5. 不把所有回复都强制转成 Artifact，短问答仍可保持轻量聊天。
## 5. 目标产品形态
## 5.1 三栏心智
高配版建议把主界面稳定为三种职责：
| 区域 | 主职责 | 说明 |
|------|------|------|
| Conversation | 对话、追问、任务推进 | 保留聊天心智，但弱化“大段正式正文” |
| Artifact Workbench | 阅读、编辑、比对、导出 | 正式交付面 |
| Timeline / Inspector | 过程、工具、来源、状态 | 可折叠的执行与证据面 |
这与当前 Lime 的工作台分栏方向一致，不需要推翻现有 UI 模式。
## 5.2 Artifact Workbench 的核心视图
每个 Artifact Document 至少支持五种视图：
1. `阅读视图`
- 报告式排版
- 强层级和可扫描性
2. `源码视图`
- Markdown / JSON / 原始块数据
3. `编辑视图`
- Tiptap 可编辑文档
4. `版本对比视图`
- 上一版本与当前版本差异
5. `来源视图`
- citations、搜索结果、文件引用、工具产物引用
## 5.3 回复升级规则
不是所有回复都进入高配 Artifact。
建议由运行时按任务意图决定：
| 场景 | 默认形态 |
|------|------|
| 简短问答 | 普通消息 |
| 研究、汇总、总结、方案、PRD、roadmap | Artifact Document |
| 表格、评分、对比、清单 | Artifact 内语义块 |
| 浏览器实时会话 | Browser Assist Artifact |
| 图片/海报/文档主题工作台 | Theme Canvas / Artifact Workbench |
判断原则：
- 有明确交付物时，Artifact 优先
- 需要多轮持续改写时，Artifact 优先
- 只是即时回答问题时，消息优先
## 6. 信息架构
## 6.1 核心对象模型
建议新增或收敛为以下产品对象：
### ArtifactDocument
正式交付物实体。
建议字段：
| 字段 | 说明 |
|------|------|
| `id` | Artifact 文档 ID |
| `threadId` | 所属 thread |
| `workspaceId` | 所属 workspace |
| `theme` | 主题域，如 general / document / social-media |
| `kind` | `report / plan / brief / table / dashboard / canvas` |
| `title` | 标题 |
| `status` | `draft / streaming / ready / failed / archived` |
| `currentVersionId` | 当前版本 |
| `sourceRunId` | 来源 turn/run |
| `deliveryMode` | `inline / docked / fullscreen / exported` |
### ArtifactVersion
文档版本实体。
建议字段：
| 字段 | 说明 |
|------|------|
| `id` | 版本 ID |
| `artifactId` | 所属文档 |
| `versionNo` | 递增版本号 |
| `documentSnapshot` | ArtifactDocument JSON 快照 |
| `editorPayloads` | 可选的编辑器层载荷快照，如 rich_text block 的 Tiptap JSON |
| `markdownSnapshot` | 兼容导出快照 |
| `summary` | 版本摘要 |
| `createdBy` | `agent / user / automation` |
| `createdAt` | 创建时间 |
### ArtifactBlock
文档内部结构块。
建议首批支持：
- `heading`
- `paragraph`
- `summary_card`
- `key_points`
- `callout`
- `table`
- `checklist`
- `score_grid`
- `quote`
- `citation_list`
- `image`
- `code_block`
- `divider`
### ArtifactSourceLink
来源绑定。
建议字段：
| 字段 | 说明 |
|------|------|
| `artifactId` | 文档 ID |
| `blockId` | 对应 block |
| `sourceType` | `web / file / tool / message / search_result` |
| `sourceRef` | 来源引用 |
| `label` | 显示名称 |
| `locator` | 行号、URL、toolCallId 等定位信息 |
### ArtifactRunBinding
交付物与执行过程的绑定关系。
建议字段：
| 字段 | 说明 |
|------|------|
| `artifactId` | 文档 ID |
| `threadId` | thread |
| `turnId` | turn |
| `itemId` | timeline item |
| `bindingType` | `primary_output / intermediate / exported` |
## 6.2 与现有 `Artifact` 的关系
当前 `src/lib/artifact/types.ts` 不应直接废弃，而应定位为：
- 兼容层 Artifact
- 流式展示与轻量渲染容器
高配版建议新增一层更长期的 `ArtifactDocument` 模型。
关系如下：
- `Artifact`：运行时 UI 容器
- `ArtifactDocument`：产品层正式交付物
- `ArtifactVersion`：持久化版本
- `ArtifactBlock`：结构化文档语义块
## 7. 协议设计
## 7.1 为什么要引入协议层
如果继续让模型只输出普通 Markdown，前端只能“尽量渲染好看”。
高配版需要的是：
- 模型明确声明自己在生成什么类型的交付物
- 前端知道哪些内容属于摘要卡、表格、结论、提醒、引用
- 后端能在流式过程中做版本记录与落盘
因此需要从“文本解析”升级为“结构化产物协议”。
但这里要注意：
**结构化产物协议属于 Lime 产品层，不等于 runtime 协议。**
runtime 协议更接近 `codex` 的做法：
- turn 级 `outputSchema`
- item lifecycle
- approval / elicitation / interrupt
- event stream
Artifact Workbench 应建立在这层稳定 runtime substrate 之上，而不是反过来把产品协议塞进框架层。
## 7.2 三层协议
### A. Message Parts 协议
用于聊天流中的即时显示。
建议 part 类型：
- `text`
- `reasoning_summary`
- `tool_call`
- `tool_result`
- `artifact_intent`
- `artifact_progress`
- `artifact_block`
- `citation`
这层用于：
- 消息区轻量回显
- Timeline 过程展示
- Workbench 流式创建状态
### B. Artifact Ops 协议
用于构建正式交付物。
建议操作：
- `artifact.create`
- `artifact.set_meta`
- `artifact.upsert_block`
- `artifact.reorder_blocks`
- `artifact.remove_block`
- `artifact.attach_source`
- `artifact.finalize_version`
- `artifact.fail`
每个 block 必须有稳定 `blockId`，这样才支持：
- 流式增量更新
- 局部重写
- 版本 diff
- 引用与块绑定
### C. Persisted Snapshot 协议
最终持久化为：
- `artifact_document_json`
- `editor_payload_snapshot`
- `markdown_snapshot`
- `render_manifest`
其中：
- `artifact_document_json` 是长期事实源
- `editor_payload_snapshot` 是编辑器层快照，不是产品层 canonical
- `markdown_snapshot` 负责兼容导出
- `render_manifest` 负责阅读态性能与缓存
## 7.3 与当前 parser 的关系
`src/lib/artifact/parser.ts` 应保留，但角色需要降级为：
### current
- 兼容旧模型输出
- 解析 fence/code block
- 在没有结构化协议时尽量抽出 artifact
### future
- 仅作为 fallback ingest
- 不再承担高配版主生成链路
## 8. 前端架构
## 8.1 Workbench Shell
建议新增统一的 `ArtifactWorkbenchShell`，作为右侧或全屏交付物容器。
应复用：
- `workbenchPreview.tsx`
- `WorkspaceCanvasContent.tsx`
- `ArtifactToolbar`
- `ArtifactRenderer`
但职责要更清晰：
- Shell 负责布局、视图切换、侧栏、版本条、来源抽屉
- Renderer 负责块渲染
- Editor 负责编辑
- Timeline/Inspector 负责过程与证据
## 8.2 阅读态渲染器
阅读态不建议继续只靠通用 Markdown CSS。
应改为：
**Artifact Block Renderer Registry -> 自定义 React 组件**
其中：
- 语义块直接走业务组件渲染
- rich_text block 可选使用 Tiptap Static Renderer
每个语义块对应稳定组件：
- 摘要卡
- 指标卡
- 对比表
- 提示框
- 评分矩阵
- 来源列表
这样才能做到：
- 风格稳定
- 留白稳定
- 层级稳定
- 多次生成看起来像同一产品，而不是不同模型的随机输出
## 8.3 编辑态
编辑态建议直接复用并扩展现有 `NotionEditor.tsx`：
- 支持块级选中
- 支持局部 AI 改写
- 支持引用插入
- 支持固定模板块
- 支持 slash command 插入语义块
不建议新起第二套富文本编辑器。
## 8.4 版本比较
高配版必须把“上一版/最新版”作为一等能力。
当前 `useArtifactDisplayState.ts` 已经有“上一版本占位”思路。
下一步应该升级为真正的版本系统：
- block diff
- 章节级变化高亮
- 用户确认采纳/回退
## 8.5 来源与证据层
漂亮的回复如果没有证据层，会变成只是“看起来专业”。
因此 Workbench 需要固定的来源面：
- 本地文件引用
- 搜索结果引用
- 网页来源
- tool 输出来源
- timeline item 引用
阅读态中可用上标或尾注形式呈现，点击后跳到右侧来源抽屉。
## 8.6 UI / UX 原则
遵守 `docs/aiprompts/design-language.md`，并针对 Artifact Workbench 补充以下原则：
1. 主表面使用实体白底，不用半透明磨砂主容器。
2. 正文排版优先中文阅读节奏，避免文档像英文博客模板。
3. 强调色只用于：
- 状态
- 关键结论
- 引导操作
4. 表格、提示框、指标卡必须来自统一组件，不允许模型自由拼样式。
5. 右侧阅读面优先长时间可读，不做营销风大横幅。
## 9. 后端与持久化
## 9.1 数据库建议
建议新增以下表：
### `artifact_documents`
- 文档主表
- 归属 workspace / thread / theme
### `artifact_versions`
- 版本表
- 保存 `artifact_document_json`、可选 `editor_payload_snapshot`、`markdown_snapshot` 与版本摘要
### `artifact_sources`
- block 到 source 的映射
### `artifact_exports`
- 导出记录
- 记录导出格式、路径、时间
### `artifact_run_bindings`
- 连接 timeline turn/item 与 artifact
## 9.2 文件系统策略
Lime 是本地优先产品，Artifact 应支持落盘，但不能写死平台路径。
要求：
1. 落盘路径通过 Workspace 或应用目录 API 解析。
2. 导出格式首期支持：
- Markdown
- HTML
- PDF
- JSON
3. 自动保存使用原子写入策略，避免写入中断造成损坏。
4. Windows/macOS 都走统一目录解析，不写死 `~/Library/...`。
## 9.3 与 Timeline 的关系
`src-tauri/src/services/agent_timeline_service.rs` 当前已能投影 `ArtifactSnapshot`。
高配版建议扩展为：
- timeline 记录过程
- artifact document 记录产物
- 两者通过 `artifact_run_bindings` 连接
原则：
- Timeline 不直接承担正式阅读面
- Artifact 不丢失来源过程
## 10. Agent 与编排策略
## 10.1 产物生成策略
高配版不建议一开始就拆成很多 formatter 子 agent。
首期先统一协议，再逐步增强编排。
建议顺序：
1. 先让主 agent 明确输出 `artifact_intent`
2. 再通过 `artifact ops` 生成结构化块
3. 最后可选地引入 `formatter/refiner` 子阶段
## 10.2 Prompt 约束
系统提示词需要明确：
1. 当任务目标是报告、方案、roadmap、总结、研究时，优先生成 Artifact Document。
2. 消息区只保留：
- 简短说明
- 进度
- 下一步
3. 不把完整长文再次重复贴回聊天区。
4. 优先使用 block 语义，而不是自由拼 HTML。
## 10.3 与 Service Skills 的关系
当前正在推进 `ServiceSkill`。
高配版 Artifact Workbench 可以成为 ServiceSkill 的统一交付面：
- `instant`：生成一份 Artifact Document
- `scheduled`：定期生成新版本
- `managed`：持续维护同一文档或同一档案集
这会让 ServiceSkill 从“启动器”真正闭环到“交付物系统”。
## 11. 分阶段路线图
## Phase 0：协议与壳层对齐
目标：
- 明确长期对象模型与协议边界
- 不大改 UI，只先收口事实源
交付：
1. 定义 `ArtifactDocument / ArtifactVersion / ArtifactSourceLink` 类型
2. 明确 `Artifact` 兼容层与 `ArtifactDocument` 长期层的关系
3. 定义 `artifact ops` 事件协议
4. 新增 Workbench Shell 设计稿与组件边界
不做：
- 大规模 UI 改版
- 完整编辑器改造
## Phase 1：高质量阅读态 Workbench
目标：
- 先把“看起来高级”做出来
- 回复从普通 Markdown 升级为报告式交付物
交付：
1. 新增 `ArtifactWorkbenchShell`
2. 新增首批语义块：
- `summary_card`
- `callout`
- `table`
- `checklist`
- `score_grid`
- `citation_list`
3. 消息区与 Artifact Workbench 分工明确
4. 高价值回复默认进入右侧交付面
验收：
- 用户不打开源码，也能一眼扫读主要结论
- 报告类回复在视觉上明显区别于普通消息
## Phase 2：可编辑 Artifact Document
目标：
- 让 Artifact 不只是预览面，而是正式编辑面
交付：
1. 以 `ArtifactDocument JSON` 作为正式持久化模型
2. 在 `rich_text` block 内引入 Tiptap / ProseMirror 编辑载荷
3. 将现有 `NotionEditor` 融入 Artifact Workbench
4. 支持局部块编辑、局部 AI 改写、块插入
5. 支持自动保存与版本生成
验收：
- 用户能直接在 Workbench 上编辑，而不是跳回消息区重来
- 编辑后的结果不会丢失结构与样式
## Phase 3：版本、差异与来源闭环
目标：
- 让 Artifact 成为长期资产，而不是一次性结果
交付：
1. 版本列表与版本摘要（已落地）
2. block diff（最小闭环已落地）
3. source drawer / citations（已落地，支持来源项 -> block 跳转）
4. timeline item 与 artifact block 双向跳转（已落地）
验收：
- 用户能知道“新版本改了什么”
- 用户能知道“这段内容从哪里来”
## Phase 4：Artifact First 产品化
目标：
- 让 Artifact Workbench 成为 Lime 的统一交付层
交付：
1. ServiceSkill 默认输出 Artifact
2. Automation 定时生成 Artifact 版本
3. Browser Assist / Search / File 结果可沉淀到同一文档
4. 支持导出、分享、归档、项目复用
验收：
- 用户可以把 Lime 当作持续生成与维护交付物的工作台
- 交付物在会话结束后仍具备长期价值
## 12. 仓库落地建议
## 12.1 建议优先复用的现有模块
| 现有模块 | 建议角色 |
|------|------|
| `src/components/artifact/*` | 保留为渲染与工具栏底座 |
| `src/lib/artifact/*` | 保留为兼容层与基础状态层 |
| `workbenchPreview.tsx` | 升级为 Artifact Workbench 入口壳 |
| `WorkspaceCanvasContent.tsx` | 继续承载右侧主预览容器 |
| `NotionEditor.tsx` | 作为编辑态主内核 |
| `AgentThreadTimeline.tsx` | 作为过程层和来源层入口 |
| `CanvasContainer.tsx` | 继续承接主题类 Canvas |
## 12.2 建议新增的目录
建议新增：
```text
src/components/artifact-workbench/
src/lib/artifact-document/
src/lib/artifact-protocol/
src-tauri/src/services/artifact_document_service.rs
```
职责建议：
- `artifact-workbench/`：壳层、视图切换、侧栏、版本条、来源抽屉
- `artifact-document/`：对象模型、版本管理、diff、序列化
- `artifact-protocol/`：artifact ops、part 映射、兼容层；当前已先落地 metadata/path 读取壳层，后续继续向完整协议边界收敛
- `artifact_document_service.rs`：持久化与查询
如果后续同步推进 `aster-rust`，则建议新增独立 runtime 模块，而不是继续堆进 `blueprint/`：
```text
/Users/coso/Documents/dev/ai/astercloud/aster-rust/crates/aster/src/runtime/
```
这部分是框架层远期方向，不覆盖 Lime 当前仓库已确定的运行时收口主计划。
建议职责：
- `thread / turn / item`
- `event bus`
- `prompt composer`
- `output schema`
- `approval / elicitation / interrupt`
- `state persistence`
## 12.3 迁移原则
1. 不直接删除旧 Artifact 系统，先把它降级成兼容层。
2. 不直接替换所有 Canvas，只先把通用报告类产物接到新 Workbench。
3. 优先打通 `general/document/planning/knowledge` 四类高价值文本产物。
4. 在协议稳定前，不急着让所有模型都严格产出结构化块。
5. 不让 `blueprint` 直接接管 Artifact 主链，Blueprint 只作为可选 planning capability 接入。
## 12.4 运行时迁移原则
本节只表达 Artifact 产品侧对 runtime 的依赖顺序，不替代 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 已锁定的 P1 / P2 / P3 / P4 执行顺序。
1. 先把 `system prompt + output schema + validator` 的控制链建立起来。
2. 再把 Stage 1 / Stage 2 生成链升级为标准 turn。
3. 再定义 item / delta / version / diff 事件。
4. 最后才考虑把 Blueprint 接入某些“复杂规划型 Artifact”场景。
## 13. 成功指标
上线后建议重点观察：
1. 报告类任务中，Artifact 打开率与停留时长。
2. 用户对同一 Artifact 的二次编辑率。
3. 版本比较的使用率。
4. 导出率与复制率。
5. 消息区长文占比是否下降。
6. 用户是否更少要求“帮我重新整理得更清晰一点”。
## 14. 风险与约束
## 14.1 主要风险
1. 同时维护产品层 JSON、编辑器载荷和导出快照，容易漂移。
2. 过早做成任意页面搭建器，会把范围做爆。
3. 语义块过多、过复杂，会压垮 prompt 与 renderer。
4. 如果没有来源层，最终只会变成“更好看的幻觉输出”。
## 14.2 控制原则
1. `ArtifactDocument JSON` 是正式事实源；Tiptap / ProseMirror JSON 只存在于编辑器层或 rich_text block 内。
2. 首批只做有限 block 集，不追求无限扩展。
3. 先把阅读态与编辑态打通，再做复杂自动排版。
4. 任何导出与落盘都必须通过 workspace / 应用目录 API 解析路径。
5. system prompt 不是唯一控制点，必须叠加 turn 级 schema 与 validator。
## 15. 最终结论
Lime 不缺“漂亮回复”的单点技巧，缺的是：
**统一的 Artifact Product Model。**
你们现有代码已经具备高配版所需的 70% 基础设施：
- 有工作台
- 有 artifact
- 有 timeline
- 有 canvas
- 有 Tiptap
真正要补的是剩下这 30%：
- 正式交付物对象
- 结构化协议
- 报告式阅读面
- 版本与来源闭环
因此最优路径不是“继续调 Markdown 样式”，而是：
**把 Artifact 从“聊天的附件”升级为“Lime 的正式交付层”。**
docs/roadmap/artifacts/system-prompt-and-schema-contract.md
+402
View File
@@ -0,0 +1,402 @@
# Artifact Workbench 的 System Prompt 与 Schema 合同
> 状态：进行中，核心合同已落地，P3 产品闭环已落地，rewrite typed patch 合同已落地
> 更新时间：2026-03-25
> 运行时边界：prompt 组装入口、turn metadata 主合同、runtime output schema 注入链以 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 为准；本文只细化 Artifact 相关合同
> 关联文档：
> - `docs/roadmap/artifacts/architecture-blueprint.md`
> - `docs/roadmap/artifacts/artifact-document-v1.md`
> - `docs/roadmap/artifacts/framework-boundary.md`
> 目标：定义 Artifact Workbench 在运行时如何通过 prompt、turn metadata、output schema、validator 四层协同控制结构化输出质量
## 当前落地状态
以下能力已经进入实现态：
1. 后端已按 turn metadata 组装 Artifact 专属 prompt 段落。
2. Artifact 回合已在 `runtime_turn` 中绑定 turn-level output schema。
3. 结构化输出已经接入 validator / repair / fallback，并可落盘为 `ArtifactDocument v1`。
4. `stage2` 已允许输出 `artifact_document_draft | artifact_ops`，`rewrite` 已收紧到增量 `artifact_ops`。
5. 后端已支持最小 `artifact_ops` 应用链，可在已有 Artifact 上执行 block / source / version 级增量更新。
6. 当前版本已回灌 `currentVersionDiff / artifactVersionDiff`，Workbench 也已接入来源抽屉、差异面以及来源项 / 差异项到 block 的定位。
7. 当前版本已支持 `timeline item <-> artifact block` 双向跳转：timeline 可精确打开目标 block，Workbench 也可回跳对应过程项。
8. `rewrite` 已把 `artifact_target_block_id` 下沉到 prompt hint、turn-level output schema、`artifact_ops` runtime apply 与 persist validator context；非目标 block 的改写 / 绑定 / 删除会被忽略并记录 issue。
9. `rewrite` 已支持专用 `artifact_rewrite_patch` 输出 envelope，并在后端兼容转换为 `artifact_ops` 应用链，便于逐步把改写合同从“通用 ops”收紧到“目标 block patch”。
仍未完全落地的部分：
1. rewrite 已具备 typed patch 主合同，但当前仍保留 `artifact_ops` 兼容分支；待模型稳定后可进一步收紧到单一 rewrite envelope
## 1. 核心观点
用户之前的判断是对的：
**渲染只是结果层。**
如果模型上游没有被清晰约束，后面的漂亮渲染只是在给随机长文做包装。
Artifact Workbench 的真正控制链应是：
1. prompt policy 决定任务规则
2. stage contract 决定本轮该输出什么
3. output schema 决定结果必须长什么结构
4. validator / repair 决定是否可以进入 ready
5. renderer 决定最终视觉呈现
一句话：
**结构质量先于视觉质量。**
## 2. 总控制栈
```mermaid
flowchart TD
A["用户请求"] --> B["Turn Metadata"]
B --> C["System Prompt Composer"]
C --> D["Stage Contract"]
D --> E["Turn-level Output Schema"]
E --> F["LLM 输出"]
F --> G["Validator / Repair"]
G --> H["ArtifactDocument Store"]
H --> I["Renderer / Editor / Export"]
```
## 3. 为什么不能只靠 Prompt
只靠 prompt，会稳定出现以下问题：
1. **阶段串线**
- Stage 1 应该给结构计划，结果却开始写正文
2. **来源丢失**
- 明明要求 source，模型仍然忘记挂引用
3. **block 漂移**
- 一会儿输出表格，一会儿输出纯长文
4. **协议脆弱**
- 一旦模型换版本，结果 shape 就可能漂
所以 prompt 只能解决“倾向”，不能单独保证“合同”。
## 4. 参考基准
本合同借鉴 `codex` 的一个关键思路：
- turn 可以携带自己的 `outputSchema`
- schema 只约束当前 turn 的结构，不污染整个产品层协议
依据：
- `/Users/coso/Documents/dev/rust/codex/codex-rs/app-server/README.md`
- `/Users/coso/Documents/dev/rust/codex/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts`
- `/Users/coso/Documents/dev/rust/codex/codex-rs/codex-api/src/common.rs`
这说明：
**把结构化输出做成 runtime 能力，比把所有结构约束硬写死在前端页面或单个 prompt 模板里更稳。**
## 5. 后端 Prompt 组装原则
## 5.1 前端不拼完整 prompt
前端只提供：
- 用户输入
- artifact metadata
- 工作台上下文
- 局部改写目标
后端负责：
- 合并基础 system prompt
- 合并记忆/搜索/source 规则
- 合并 Artifact 专属规则
- 合并 stage 合同
- 绑定 output schema
## 5.2 Prompt 分层
建议长期固定为以下 8 层：
1. `Base Runtime Layer`
- 身份、语言、安全边界、消息区与交付区职责分离
2. `Workspace / Team Layer`
- 团队偏好、项目约束、cwd、工作模式
3. `Memory Layer`
- 记忆画像、长期偏好、已知上下文
4. `Search / Source Layer`
- 搜索行为、来源要求、引文约束
5. `Artifact Policy Layer`
- 什么时候必须进入 Artifact
- 不要在消息区重复整篇文档
- 只能输出白名单 block
6. `Stage Contract Layer`
- 当前是 `stage1 / stage2 / rewrite`
7. `Turn Context Layer`
- kind、source_policy、selected_block、rewrite_instruction
8. `Schema Hint Layer`
- 明确提醒本轮有严格 output schema
- 模型应优先满足 schema 而不是自由发挥
## 5.3 Marker 约定
建议统一 marker：
- `【Artifact 交付策略】`
- `【Artifact 来源策略】`
- `【Artifact Stage 1 合同】`
- `【Artifact Stage 2 合同】`
- `【Artifact Rewrite 合同】`
- `【Artifact 输出 Schema 提示】`
作用：
- 可观测
- 可去重
- 可调试
## 6. Turn Metadata 合同
这里的 `ArtifactTurnMetadata` 只表达 Artifact 领域的意图模型，不直接等于 Lime 当前仓库的请求 wire format。
当前实际发送边界、`harness` 结构、metadata 归一化与兼容收口，统一以 `docs/roadmap/lime-conversation-execution-efficiency-roadmap.md` 为准。
建议长期保留以下 Artifact turn intent：
```ts
interface ArtifactTurnMetadata {
artifactMode?: "none" | "draft" | "rewrite";
artifactKind?:
| "report"
| "roadmap"
| "prd"
| "brief"
| "analysis"
| "comparison"
| "plan";
artifactStage?: "stage1" | "stage2" | "rewrite";
sourcePolicy?: "required" | "preferred" | "none";
workbenchSurface?: "right_panel" | "fullscreen";
artifactRequestId?: string;
artifactTargetBlockId?: string;
artifactRewriteInstruction?: string;
}
```
这里的设计原则是：
- metadata 表达意图
- prompt 表达规则
- schema 表达结构
三者不要混写。
## 7. Stage 合同
## 7.1 Stage 1
职责：
- 判断是否需要正式交付物
- 锁定 `kind`
- 生成标题建议
- 生成 source policy
- 生成 block plan / section outline
- 标记缺口与风险
禁止：
- 直接写完整长文
- 输出 HTML / CSS
- 输出最终排版说明
建议 schema 形态：
```ts
interface ArtifactStage1Result {
needsArtifact: boolean;
kind:
| "report"
| "roadmap"
| "prd"
| "brief"
| "analysis"
| "comparison"
| "plan";
title: string;
sourcePolicy: "required" | "preferred" | "none";
outline: Array<{
id: string;
title: string;
goal: string;
}>;
blockPlan: Array<{
id: string;
type:
| "section_header"
| "hero_summary"
| "key_points"
| "rich_text"
| "callout"
| "table"
| "checklist"
| "metric_grid"
| "citation_list";
sectionId?: string;
purpose: string;
}>;
gaps?: string[];
}
```
## 7.2 Stage 2
职责：
- 输出正式 `artifact_document_draft`
- 或输出增量 `artifact ops`
必须：
- 满足 `ArtifactDocument v1`
- 满足 source 约束
- block 类型只能来自白名单
建议 schema 形态：
```ts
type ArtifactStage2Result =
| {
type: "artifact_document_draft";
document: ArtifactDocumentV1;
}
| {
type: "artifact_ops";
artifactId: string;
ops: ArtifactOpEnvelope[];
};
```
## 7.3 Rewrite
职责：
- 只改目标 block
- 不允许顺手重写整篇文档
建议 schema 形态：
```ts
interface ArtifactRewriteResult {
artifactId: string;
targetBlockId: string;
block: ArtifactBlockV1;
}
```
## 8. Output Schema 策略
## 8.1 Schema 绑定位置
建议 schema 不是前端硬编码，而是由后端在 turn 发起时绑定。
以下时序图只表达“绑定责任在后端”，不单独定义当前仓库的命令名、函数名或中间结构：
```mermaid
sequenceDiagram
participant FE as 前端
participant App as Lime App
participant RT as Aster Runtime
participant Model as LLM
FE->>App: submit_turn(input + artifact metadata)
App->>RT: build_turn(stage, metadata)
RT->>RT: compose system prompt
RT->>RT: attach output schema
RT->>Model: request(instructions + schema)
Model-->>RT: structured output
```
## 8.2 Schema 颗粒度
建议采用三类 schema：
1. **运行时 schema**
- 限制某一轮输出结构
2. **产品层 schema**
- `ArtifactDocument v1`
3. **编辑器 payload schema**
- `rich_text` 内的 ProseMirror/Tiptap JSON
不要把这三层混成一个巨大 schema。
## 8.3 Schema 与 Validator 的关系
schema 不是 validator 的替代品。
原因：
1. 模型可能输出“表面符合 schema，但业务仍非法”的内容
2. sourceId 引用、block 数量、fallback 等逻辑需要业务修复
3. 编辑器 payload 可能需要额外兼容修正
因此主链仍然必须有：
- schema check
- business validation
- repair
- fallback
## 9. Validator / Repair 策略
validator 至少负责：
1. 顶层字段校验
2. block 类型白名单校验
3. source 引用合法性校验
4. `rich_text` payload 兼容性校验
5. source policy 业务校验
repair 至少负责：
1. 缺省 title 补全
2. table 行列补齐
3. citation 无效项删除
4. block fallback 到 `rich_text(markdown)`
5. 整体失败时回退为单个 `rich_text` 文档
## 10. 推荐实现边界
## 10.1 Lime 产品层
建议新增或持有：
- `artifact_document_schema.ts`
- `artifact_stage1_schema.ts`
- `artifact_stage2_schema.ts`
- `artifact_rewrite_schema.ts`
- `artifact_document_validator.ts`
- `artifact_document_repair.ts`
## 10.2 Aster Runtime 层
建议持有：
- prompt composer
- turn 级 schema registry
- model invocation wrapper
- item/turn events
- output parsing / validation hook
## 11. 最终决策
Artifact Workbench 的输出质量，不应依赖“模型今天状态好不好”。
长期正确方案是：
**Prompt 负责引导，Schema 负责约束，Validator 负责兜底，Renderer 负责呈现。**