open-codesign v0.2 Agentic Design Loop 架构解析:从 JSONL 会话存储到 15 工具 Harness 的完整实施指南
open-codesign v0.2 Agentic Design Loop 架构解析:从 JSONL 会话存储到 15 工具 Harness 的完整实施指南
本文基于 docs/v0.2-plan.md(v0.2 Agent Loop & Harness Plan)展开。这份文档是 open-codesign 从"单 prompt → 单 artifact"的 v0.1 流水线,升级为"读/写用户 workspace、按需拉取 skill、自检自愈"的真正 agentic 设计系统的实施蓝图。读完本文,你将掌握:v0.2 的存储模型与"Design == Session"设计、15 个工具的组合方式与 capability 暴露规则、四层系统 Prompt 叠放、4-Tier 权限模型、渐进式披露(Progressive Disclosure)机制,以及 v0.1 → v0.2 的迁移路径——并能从当前仓库源码(packages/core/src/tools/、packages/core/src/agent.ts 等)中印证每一项设计决策的实际落地。
0. 文档定位与总原则
v0.2 的架构决策有一条贯穿始终的总原则:默认抄 coding agent 约定,只在 design-specific 场景做针对性扩展。
- pi-coding-agent / Claude Code / Cursor 有共识的做法 → 直接抄;
- 三家不一致 → 挑最简单的实现;
- 三家都没有、而我们确有独特需求 → 才讨论发明。
同时遵循 YAGNI 原则:v0.x 阶段允许随意 breaking change,v1.0 才承诺向前兼容。这份计划还基于 2026-04-24 的 pi-coding-agent spike 结果(docs/spike-pi-results.md)做了大幅修订——spike 结论是 pi-coding-agent 满足全部 v0.2 硬需求,session / bash / capability / provider 全部交给 pi 承担,这直接决定了后续存储层、工具层的大量"砍掉自研"决策。
1. v0.2 明确不做的事(Non-goals)
理解 v0.2 边界,才能理解它为什么敢把大量基础设施"外包"给 pi-coding-agent:
| 类别 | 明确不做 |
|---|---|
| 媒体能力 | Video / 3D / logo system / 矢量编辑(不是 design agent 本质) |
| 运行时 | Bundle model runtime(Ollama / llama.cpp / 浏览器等) |
| 云服务 | Cloud sync / telemetry / 用户账户 |
| 协作 | 多人协作、MCP 支持 |
| 安装生态 | 社区 skill / scaffold 安装(pi install 式) |
| 会话能力 | Session branching UI(引擎层 pi 支持,UI 不暴露)、消息队列 / steering |
| 回滚 | Undo / 版本回退(用户可停止,但不能回退 agent 步骤) |
| 子代理 | Verifier subagent(有 preview 自检就够) |
| 记忆 | Working memory 由用户写 AGENTS.md / DESIGN.md |
| 其他 | Snip 工具(靠 pi auto-compact)、Per-design meta.json(session header 够)、Sealed / Open mode split(统一 workspace model)、权限 mode toggle(单一模式 + 四层 Tier) |
一句话概括:v0.2 不做"通用软件工程 Agent",只做"设计 artifact 的迭代 Agent"。
2. 核心架构:去 SQL,走 JSONL + filesystem
2.1 存储模型
v0.2 砍掉了全部 SQLite 表,改为:
~/Library/Application Support/open-codesign/
config.toml # BYOK 配置(provider / API key)
sessions/
<session-uuid>.jsonl # 每个 session(= design)一个 JSONL
thumbnails/ # 缩略图 cache
settings.json # 全局 allowedTools + 偏好
allowed-commands.json # 全局 bash allowlist(也可以合进 settings.json)
<user-workspace>/ # 用户的真 workspace(由 Settings 默认根配置)
(用户文件)
AGENTS.md # 用户写的项目指令(可选)
DESIGN.md # 用户写的品牌 token(可选,Google spec)
.codesign/
settings.json # per-design allowlist + 偏好
settings.local.json # 个人偏好(默认 gitignore)
被砍掉的 SQLite 内容及替代方案:
designs表 → session JSONL header 的cwd+name字段;design_files表 → workspace 磁盘(真源);snapshots/snapshot_files→ 不做版本引擎(v0.3+);chat_messages→ session JSONL message entries;comments→ session JSONL 里带 anchor 的 user message;diagnostic_events→ 可选 append-only log 文件。
spike 之后存储层进一步简化:直接用 pi 的 SessionManager(spike 验证 sessionDir 完全可指定),不用自写 JSONL writer / parser;session 文件名是 <ISO>_<uuidv7>.jsonl(不是纯 uuid,这是 spike 发现的实际行为)。
2.2 Design == Session:没有"project"概念
v0.2 中 Design 就是 pi session,一个 JSONL 文件:
- session header 格式 100% 用 pi v2 原生,不加字段(包括不加 designId);
cwd字段 = workspace 路径;name字段 = 用户给的 design 名(对应 pi 的/name命令);- 多个 session 可共 cwd(= "对同一 codebase 的多个对话");
- Sidebar 扁平展示 session,按
lastOpenedAt排序; - Fork = 新 session(pi 的
/fork,引擎层支持但 UI 暂不暴露)。
2.3 Workspace 统一模型
- 每个 design 必有 workspace(无 sealed mode);
- Settings 里一个配置:默认 workspace 根目录(默认
~/Documents/CoDesign/); - New Design 时默认路径
<默认根>/<design名>/,用户可自定义; - 去掉 PR #173 的 Skip 按钮。
3. 工具清单:15 个(7 个白送 + 8 个自写)
v0.2 总计暴露 15 个工具给 agent:pi-coding-agent 自带 7 个 built-in(执行层不写,只 hook 拦截)+ 自写 8 个(设计 domain 6 + 生命周期 2)。
Pi 自带 7 个(spike 验证白送)
| 名称 | 我们做啥 |
|---|---|
read |
直接用,pi 自带类似 view_budget 机制 |
write |
直接用 |
edit |
str_replace 风格 |
bash |
直接用,通过 tool_call hook 拦截做权限,不写新 bash 工具 |
grep / find / ls |
白送 |
Bash 权限拦截(spike 验证的实现)是异步、可 await Electron IPC 弹窗的:
pi.on("tool_call", async (event) => {
if (isToolCallEventType("bash", event)) {
const allowed = await askUserPermission(event.input.command);
if (!allowed) return { block: true, reason: "user denied" };
}
});
同一 hook 也覆盖 read/edit/write/grep/find/ls,按需扩展权限粒度。event.input 可 mutate,未来 SSH 远程执行不用换工具。
Design domain 6 个(自写)
| 名称 | 行为 |
|---|---|
scaffold(kind, path) |
把预装 starter JSX / CSS 片段复制到 workspace(enum kind) |
skill(name) |
懒加载 skill prompt 文本(manifest 在 system prompt 里列名字) |
ask(questions) |
渲染结构化问卷;end turn 等用户答(5 种题型) |
preview(path) |
渲染 artifact source(默认 App.jsx)→ {screenshot?, consoleErrors, assetErrors, domOutline, metrics};vision model 才返 screenshot |
gen_image(prompt, path) |
文生图,落盘;capability-based 暴露(仅配了 imageGen provider 才给 agent) |
tweaks(blocks) |
声明 EDITMODE 块 + 生成 UI 控件;跨文件支持;全量覆盖语义 |
Lifecycle 2 个(自写)
| 名称 | 行为 |
|---|---|
todos(items) |
任务列表;system prompt 强制 >3 tool call 任务首调;runtime 5-call 后软提醒;UI 钉顶展示 |
done(path) |
终止本轮;默认检查 App.jsx;有错返给 agent 修,干净则 turn 结束 |
已砍掉的工具
verifysubagent(preview 自检够);snip(pi auto-compact);- 独立
list_files、自写 bash(pi 自带); read_design_system(DESIGN.md 直接注入 system prompt);read_url(reference URL 由 host 预取、限流/限大小后作为 untrusted context 注入,不作为 agent 默认工具暴露)。
Capability-based 暴露规则
Session 启动时探测 capabilities(直接读 Model<T>.input / .reasoning / .cost.cacheRead,spike 验证字段齐全):
gen_image只在 imageGen provider 配了时暴露;preview对 vision model 返回截图(Model.input.includes("image")),对纯文本 model 返回 DOM outline + metrics;read图像模式仅 vision model。
在仓库实现中,模型 capability 的确是通过构造 pi 模型形状的 input 数组来体现的——见 packages/core/src/agent.ts 的 buildPiModel 与 supportsImageInput,它直接决定 input: ['text','image'] 还是 ['text'],从而驱动 preview 截图与附件图像注入的开关(attachmentImagesForModel 同样检查 model.input.includes('image'))。
4. Loop 结构:Agentic,无硬相位
v0.2 主线不是 tag-parser / custom streaming grammar,而是 pi function-tool loop + workspace delta stream。推荐把 harness 理解成四层:
- Run Controller:绑定
designId+generationId,执行 preflight ask、title/todos 约束、timeout/cancel、host phase notes。 - Workspace Delta Bus:把
fs_updated、preview pool、snapshot persist 作为按 design/generation/path 隔离的增量事件处理。 - Context Pack / Session Memory:brief、run preferences、workspace state、memory sections 进入 prompt;tool/artifact/error rows 不进入 LLM history。
- Verification Gate:
preview(path)提供中途检查,done(path)负责最终 gate 和 repair loop。
SESSION_START
↓
system prompt 组装(见 §5)
↓
TURN_START (user message + 可选 content blocks)
↓
AGENT_LOOP (pi-agent-core 原生)
├─ agent 思考 / 说话 / 调 tool(可并行)
├─ 工具 result 回流
└─ 终止任一满足:
· 调 done
· 调 ask(等答)
· 60 次 tool call 上限(软询问继续)
· 10 分钟 wall clock
· 用户 abort
↓
TURN_END
↓
if done 被调:
runtime 跑 preview(path)
errors → 喂回 agent → 回 AGENT_LOOP
clean → turn 结束,UI 显示成果
软约束(写进 system prompt,不是 loop 强制):
- 新 / 模糊任务优先调
ask(10+ 问); - 写代码前在 chat 里 declare aesthetic(palette / type / rhythm);
- 复杂任务(>3 step)首调
todos规划; - 完成用
done,它自动 preview + 看 console / 404 后修; - 暴露 2-5 个 tweaks("big-rock" values,不是细枝末节)。
在 packages/core/src/agent.ts 中可以看到这套约束的落地:set_title 与 set_todos 形成 host-required todo gate(wrapPlanningGate 会阻止在未先调 set_todos 前执行 mutation/preview/finish 工具),done 被 wrapDoneState 包裹,错误超过 MAX_DONE_ERROR_ROUNDS = 3 轮即强制终止并明确告知 agent 不得再 claim 设计完成。
Multi-screen 视觉一致性(baton pattern)
多屏 / 多 page 项目(landing + dashboard + settings 等)保证视觉一致的做法是借鉴 Google Stitch 的 baton pattern:
生成屏 1
↓
从产物抽 token(colors / typography / spacing / radius)
↓
更新 DESIGN.md(agent 调 edit)
↓
注入下次生成 system prompt 的 [3] 层
↓
生成屏 2 自动用同 token system
↓
... 第 N 屏
这不是新工具,而是 prompt loop 设计:每生成一屏,agent 自检"DESIGN.md 是否需要更新",更新了下一屏自然继承。配合 §5 的 Brand Acquisition Protocol 形成完整 token 一致性闭环。仓库中 done 工具对 workspace 存在多个 design source 而未建立 DESIGN.md 的情况会报错("Multiple design sources found ... create a Google-compatible DESIGN.md before finishing multi-screen work"),正是 baton pattern 的强制面。
中断语义(对齐 Claude Code)
用户 Esc / Stop:
├─ LLM streaming → AbortSignal
├─ 当前 tool call → 级联 abort
│ └─ bash:SIGTERM → 3s → SIGKILL
├─ queued user messages → 回 editor 供重编辑
└─ 后台进程(dev server)不杀,走单独 "Processes" 面板管
二次 Esc(2s 内):弹出撤销菜单(恢复到 turn 前 / 删除本 turn / 什么都不做)。
半成品文件:write/edit 用 atomic temp + rename,不回滚,中断只影响未完成的写。在源码层面,done 工具接受 AbortSignal(signal?.throwIfAborted()),generateViaAgent 全程传播 input.signal,中断即抛 PROVIDER_ABORTED。
后台进程(tab 模型)
design tab 打开 → background process 活
design tab 关闭 → SIGTERM 进程(关前弹确认)
切换 design tab → 什么都不做,进程继续
app 退出 → TERM → KILL 所有
- 每 design ≤3 进程,全局 ≤10;
- Port 检测:起进程后 2s 扫 stdout 匹配 vite/next/astro/webpack 端口模式;
- Processes 面板(design sidebar 固定)列活进程 + 一键 stop + 看 logs。
5. System Prompt 七层叠放
[1] 主 system prompt 产品级(抄 Claude Design 骨架)
├─ Identity("expert designer, user as manager, filesystem-based project")
├─ Workflow(软指引 7 步)
├─ Output 规则(filename / revisions / 避坑)
├─ React + Babel pinned(SRI 整段抄 Claude Design)
├─ Content Guidelines(反 AI slop 核心)
├─ Aesthetic direction(无品牌时如何承诺)
├─ Typography 默认(Bunny Fonts / Fontshare)
├─ Tools 一览(12 个每个一行)
├─ Tweaks EDITMODE 协议
├─ Ask 规则(10+ 问 + 5 种题型)
├─ Preview / done 协议
└─ Do not divulge
[2] project_info workspace stack 探测结果(~200 字节)
[3] <project_context> 用户项目级
<instructions source="AGENTS.md">...</instructions>
<design_system source="DESIGN.md">
YAML front matter 保留原样(token 不 truncate)
Prose 部分 truncate 到 2000 字
</design_system>
[4] Available scaffolds (enum) 从 scaffold tool schema 的 kind 自动生成
[5] Available skills (manifest) 技法 + brand refs 两段
## Techniques
- oklch_color_system: ...
- bento_grid: ...
## Brand references (skill("brand:<name>"))
linear, vercel, stripe, figma, arc, ...
[6] [对话历史] pi auto-compact 兜底
[7] 本轮 user message
总字符目标:base 9-10K 字符(~2.7K tokens),比 Claude Design 的 30K 小三分之二。
仓库中 prompt 的模块化落地见 packages/core/src/prompts/(compose-full.ts 组装 + sections/ 下的 identity.md、workflow.md、output-rules.md、pre-flight.md、safety.md、anti-slop-digest.md、brand-acquisition.md、design-methodology.md、editmode-protocol.md、tweaks-protocol.md、multi-screen-baton.md 等分段文件),packages/core/src/lib/context-format.ts 负责把 AGENTS.md(formatProjectInstructionsContext)、DESIGN.md(formatProjectDesignSystemContext)、.codesign/settings.json 等注入第 [3] 层。
DESIGN.md 生命周期
DESIGN.md 是协作式的,agent 和用户都可编辑:
- Session 启动读,session prompt 包含;
- Agent 第一次声明 aesthetic → 主动
write("DESIGN.md", ...)生成初版; - 用户外部编辑 → FSWatcher 捕捉 → 下轮重读;
- 用户持续调整某 EDITMODE 值 → agent 主动 propose "promote to DESIGN.md"。
Google DESIGN.md spec 完全采纳(YAML front matter + markdown body,基于 W3C DTCG),不发明自己的 schema。仓库中 done 工具对 DESIGN.md 会调用 validateDesignMd(来自 packages/shared/src/design-md.ts)做合法性与结构检查,并支持 done("DESIGN.md") 将 DESIGN.md 作为一等交付物产出。
Brand Acquisition Protocol
灵感来自 huashu-design(A/B 测结果显示降低输出方差 5×),写进 system prompt:
## Brand acquisition (never invent brand values from memory)
When user mentions a specific brand and DESIGN.md doesn't yet exist:
1. Ask the user for brand guidelines / DESIGN.md / brand site URL
2. If they give a URL: bash `curl` the /brand or /press route
3. Download SVG / HTML / screenshots as fallback (via bash + workspace storage)
4. Extract hex values programmatically from CSS / SVG, NOT from memory
5. Codify into DESIGN.md with YAML token block
NEVER write brand color hex values from memory. Always extract from
authoritative source. If the source is unavailable, ask the user.
理由:LLM 对 brand color 的"记忆"错误率高(即使 Linear / Stripe 这种知名品牌也有偏差),凭记忆生成的产物会"形似而神离"。强制走 acquisition protocol 把这个错误源头 close 掉。仓库侧与程序化提取 token 相关的实现有 packages/core/src/brand/cssVarExtractor.ts(CSS 变量提取)与 packages/core/src/brand/dtcgImporter.ts(DTCG token 导入)。
6. 权限模型:4-Tier(抄 Claude Code)
分层
Tier 0 无感通过(不弹窗)
Tier 1 首次弹窗 + 用户选 allowlist
Tier 2 每次必弹窗(不能 suppress)
Tier 3 硬拦截(UI 拒绝,无 override)
具体归类
| 操作 | Tier |
|---|---|
| 读 workspace 内文件 | 0 |
| 写 / 改 / 删 workspace 内文件 | 0 |
ls / pwd / cat / grep / find / stat(cwd 内) |
0 |
只读 git (git status/log/diff) |
0 |
pnpm install * / pnpm run * / write-git |
1 |
curl / wget 非本机 URL |
1 |
| cwd 外的任何命令 | 1 |
git push / npm publish / sudo |
2 |
rm -rf / / rm -rf ~ / curl | sh / 系统目录写 |
3 |
弹窗 UX(三按钮)
┌─────────────────────────────┐
│ 🟡 Agent 想运行 │
│ │
│ pnpm install │
│ │
│ [拒绝] [允许] [总是允许] │
└─────────────────────────────┘
- 默认 scope = per-design + 命令前缀(
pnpm install *); - 想更宽 / 更窄去 Settings 编辑 allowlist。
Allowlist 存储
<workspace>/.codesign/settings.json(per-design,可 commit):
{
"schemaVersion": 1,
"allowedTools": [
"Bash(pnpm install *)",
"Bash(pnpm run *)",
"Bash(git status)"
]
}
全局:~/.codesign/settings.json(同格式)。加载顺序:global → project → local(settings.local.json,默认 gitignore)。
7. Progressive Disclosure:三层独立机制
源头 budget(预防膨胀)
read:view_budget(首次全文,重复摘要 + 强制 view_range,mtime 变化重置);bash:stdout tail-cap 10KB + exit code;preview:screenshot 压缩 + console ≤50 条 + 404 ≤20 条;grep:head_limit 250。
仓库中 preview 的 budget 是硬编码的 schema 约束:MAX_PREVIEW_STEPS = 16(packages/core/src/tools/preview.ts 中 MAX_CONSOLE_ENTRIES = 50、MAX_ASSET_ERRORS = 20,trimPreviewResult 负责截断)。
按需披露
- Skill manifest 在 system prompt 列名字(~500 字节);
skill(name)调用时返回全文(~500-2000 字节/次);- Scaffold enum 在 tool schema(~200 字节);
scaffold(kind, path)执行时写磁盘 + 返回短路径确认;- 一个 session 内重复
skill(name)→ 返回短 "already loaded",不重复灌。
skill 工具在仓库中的实现(packages/core/src/tools/skill.ts)明确支持 session 级去重:invokeSkill 带 alreadyLoaded Set,第二次命中返回 {status: 'already-loaded'} 与"skill already loaded this session — refer to earlier tool result"。
Tool result 不做类型特定剪枝
coding agent 都不做,我们也不——pi auto-compact 兜底。
Tweak / Inline-edit / Comment delta
直接操纵的 delta 攒 buffer,下次 user chat 时附带到 content block:<tweak_changes>、<direct_edits>(inline text edit);评论立即发,不攒。
8. UI 集成
已有的(PR #173 / v0.1 带来)
HubView→ Hub 页面;DesignSwitcher/DesignsView→ session list;ModelSwitcher→ 模型切换(mid-session 可用);FilesPanel/FilesTabView/CanvasTabBar→ 右 pane;PreviewPane/PhoneFrame→ 预览;InlineCommentComposer→ 评论带 anchor;Settings/+AddCustomProviderModal→ BYOK 配置;RenameDesignDialog/DeleteDesignDialog→ CRUD;- Runtime
tweaks-bridge.ts→ EDITMODE postMessage 基础。
以上组件均已在 apps/desktop/src/renderer/src/components/ 中存在(如 AskModal.tsx、PermissionDialog.tsx、PreviewPane.tsx 等,与计划的"要新增"清单相对应)。
要新增的
| UI 组件 | 用途 | 工作量 |
|---|---|---|
AskModal |
ask 工具弹的结构化问卷 |
M |
PermissionDialog |
bash 三按钮弹窗 | S |
TweakDeltaChip |
Chat input 里的 tweak 变更附件 chip | S |
TweaksPanel |
artifact 里的 slider / color picker 面板 | M |
ProcessesPanel |
design sidebar 的后台进程列表 | M |
MigrationDialog |
v0.1 → v0.2 迁移弹窗 | S |
ScaffoldPicker(optional) |
scaffold() 调用时的可视化挑选 |
M |
事件流到 React:两条独立通道
pi event stream (tool calls / messages / thinking)
↓ IPC
Chat pane + activity feed
Workspace FSWatcher (chokidar)
↓ IPC
Files tab + preview tab(热刷新)
Files tab 不跟 tool call 事件关联——只看磁盘真实状态。外部编辑(VSCode)自然生效。
9. Gap Analysis:已有 vs 要做
工具层
| 现有 / 来源 | 对应 v0.2 | 状态 |
|---|---|---|
| pi-coding-agent 自带 read/write/edit/bash/grep/find/ls | 7 个 built-in | ✅ 直接用,只写 tool_call hook 加权限 |
| 现有 set-todos | todos | ✅ 保留 |
| 现有 done | done | ✅ 保留(含 runtime verifier hook) |
| 现有 declare-tweak-schema | tweaks | ✅ 改跨文件 |
| 现有 generate-image-asset | gen_image | ✅ + capability gate |
| 现有 read-url | - | ❌ 砍(Reference URL 走 host 预取 + untrusted context) |
| 现有 text-editor | - | ⚠️ 保留为 str_replace_based_edit_tool;pi 自带后可砍 |
| 现有 list-files | - | ❌ 砍(pi 自带 ls 覆盖) |
| 现有 read-design-system | - | ❌ 砍(DESIGN.md 直接注入) |
要新建的工具(spike 后精简为 4 个 + 1 个拆分)
ask+ 结构化问卷 + AskModal UI;scaffold工具 + 预装目录packages/core/src/scaffolds/;skill(invoke_skill) + manifest 生成 + 懒加载 + 去重;preview从done里拆出独立工具(半个新 + 半个改造);→ spike 后改为只写 hook(不算独立工具)。bash
仓库中这些工具的 schema 与实现都位于 packages/core/src/tools/:ask.ts(5 种题型 + 1-25 题上限 + AskResult answered/cancelled)、scaffold.ts(manifest 校验、destPath 扩展名调整、workspace 边界与符号链接防护)、skill.ts(manifest 懒加载 + session 去重)、preview.ts(16 步交互预算 + console/asset 上限 + vision 分支)、tweaks.ts(跨文件 EDITMODE 聚合扫描)、done.ts(静态 lint + runtime verifier + DESIGN.md 校验 + 3 轮修复上限)。它们统一由 packages/core/src/agent.ts 的 generateViaAgent 组装进 pi-agent-core 的 Agent。
存储层(spike 后大幅简化)
| 之前计划 | spike 后 |
|---|---|
✅ 直接用 pi 的 SessionManager |
|
model-caps.ts capability 表 |
✅ 直接读 Model<T>.input/reasoning/cost |
✅ 直接用 pi.registerProvider() |
|
| v0.1 → v0.2 迁移脚本 | ✅ 仍要写:扫旧 SQLite → 转 JSONL via SessionManager.appendXXX |
| config.toml → pi.registerProvider 翻译层 | ✅ 仍要写:BYOK 配置注入 |
集成层
- ✅ Pi-coding-agent 集成 spike — 已完成(
docs/spike-pi-results.md); - System prompt 主体内容写满;
- Progressive disclosure:read view_budget pi 已有,bash tail-cap 在 hook 里加,preview 压缩自写。
仍要写的代码(v0.2 实际工作量)
- ✅ Electron IPC 桥(wrap
createAgentSession(),单 session 一个 BrowserWindow); - ✅ Permission Dialog UI(被
tool_callasync hook 调); - ✅ config.toml →
pi.registerProvider()翻译 shim; - ✅ Sandbox 渲染器(packages/runtime,扩展);
- ✅ Artifact / exporter(packages/exporters);
- ✅ FSWatcher → Files tab(独立通道);
- ✅ 4 个工具:scaffold / skill / ask / preview;
- ✅ tweaks 改跨文件;
- ✅ v0.1 → v0.2 迁移脚本。
10. Pi-coding-agent 集成(已完成 spike)
spike 结论摘要:
| 验证 | 结果 | 关键 API |
|---|---|---|
| A. bash 拦截 hook | ✅ Pass | pi.on("tool_call", async (event) => { return { block, reason } }) |
| B. Session storage | ✅ Pass | SessionManager.create(cwd, sessionDir) 完全扁平,文件名 <ISO>_<uuidv7>.jsonl |
| C. Model capability | ⚠️ Partial(实际 Pass) | Model<T> 有 reasoning / input / cost / contextWindow / maxTokens |
v0.2 架构落地(基于 spike 结论):
- Session:
SessionManager.create(cwd, "<userData>/sessions"),扁平存储; - Bash 权限:
tool_callhook + Permission UI(不写新 bash 工具); - Capability:
Model<T>直读,无 fallback 表; - Provider:
pi.registerProvider()从 config.toml 翻译注入; - AuthStorage:
AuthStorage.create(authPath)指向 userData,配合 config.toml 双轨。
Spike 中发现的坑(写进实施 checklist)
- session 文件名是
<ISO>_<uuidv7>.jsonl,不是纯 uuid; Model.provider运行时是 string,不是 object(类型说谎);ModelRegistry.getAll()不是getAllModels();- pi-ai 要 pin
^0.69.0,不要让 pnpm 默认装 0.67.x; - 自定义 gateway 用
pi.registerProvider("anthropic", { baseUrl }),不靠 env。
Bonus 发现(v0.3+ 可白嫖)
SessionManager.forkFrom()— 程序化 fork session;session.navigateTree(targetId)— 内置版本/分支 UX;- 19+ 事件(before_provider_request / after_provider_response / compaction_start_end / auto_retry_*);
- OAuth provider 支持(未来 Claude Code OAuth 续接零代码);
--mode rpc子进程 escape hatch。
11. v0.1 → v0.2 迁移
策略
v0.2 首次启动:
- 检测
app.getPath('userData')/designs.db存在 → 弹框"检测到 X 个 v0.1 designs,迁移吗?"; - 一键迁移:
- SQLite 读
designs/design_files/chat_messages/comments; - 每 design 在
~/Documents/CoDesign/<slug>/创 workspace; - 转 chat_messages → session JSONL;
- 转 design_files → workspace 磁盘文件;
- 转 comments → JSONL 里 content block;
- SQLite 读
- 跳过:旧 SQLite 备份为
designs.db.v0.1.backup,不读; - 迁移完 + backup 保留,允许用户手动清。
保留不碰
config.toml(API key)继续读,只新增defaultWorkspaceRoot字段;- 用户 workspace 里的 web artifact source(劳动成果)不动。
12. 资源清单:Scaffolds / Skills / Brand References
12.1 Scaffolds(预装 starter templates)
目标约 30 个精品,Bundle 预算 ~150-200KB 总内嵌代码(gzip 后 40-50KB)。
P0 必装(9 个,核心视觉独特):neubrutalism-kit、aurora-mesh-bg、glassmorphism-surface、bento-grid、terminal-mockup、vscode-mockup(DIY ~200 行 JSX)、arc-browser-chrome(DIY ~180 行 JSX)、toast-notification + drawer-sheet(sonner/vaul CDN)、slide-deck-16-9(reveal.js CDN)。
P0 Device frames:iphone-frame(现有保留)、iphone-16-pro-frame(devices.css 升级)、ipad/watch/android/macos-safari-frame(现有保留)、macbook-pro-16-2024、chrome-browser-chrome(magnitce Web Component)、vision-pro-spatial(DIY ~150 行)、foldable-phone-frame(DIY ~100 行)。
P1 产品常见(5-7 个):kanban-board、cmdk-palette、skeleton-loader、empty-states-kit、landing-hero、stepper-wizard、file-tree。
P2 美学/背景(2-3 个):noise-grain-overlay(SVG feTurbulence data URI)、dot-grid-bg(radial-gradient 1px dot)、animated-gradient-bg(animata 抽取)。
P2 bonus:voxcss-scene(HTML voxel 引擎,非常独特,可选)。
待实测/推后:esm.sh CDN 在 Babel Standalone srcdoc iframe 的兼容性(sonner / vaul 要验证);motion-primitives / data-table / settings-panel / chat-ui / pricing-table / blog-editorial 等推后 v0.3+。
Bundle 结构(计划中的目标布局):
packages/core/src/scaffolds/
manifest.json # kind → {description, path, size, license, source}
device-frames/ browser/ dev-mockups/ ui-primitives/
backgrounds/ surfaces/ decks/ landing/
仓库中 scaffold 工具的 manifest 契约(packages/core/src/tools/scaffold.ts)已经落地:manifest.json 顶层 schemaVersion: 1 + scaffolds: Record<kind, {description, path, license, source, category?, aliases?, sizeBytes?}>;模板实际放在用户可见的 <userData>/templates/scaffolds/,从 app bundle 播种、只增不删(用户对现有文件的编辑跨启动保留);kind 枚举涵盖 device-frame / browser / app-shell / dev-mockup / ui-primitive / background / surface / deck / report / design-system / landing 等类别。工具还会做扩展名保持(source 是 .css 时 destPath 自动补后缀)与路径越界防护(拒绝符号链接穿越 workspace 边界)。
12.2 Skills(v0.2 目标 12 现有 + 5 新增 P0)
格式:抄 agentskills.io / Anthropic SKILL.md spec:
---
name: form-layout
description: >
Apply when building any form with 3+ fields, multi-step wizards,
onboarding flows, checkout flows, or settings screens.
version: 0.1.0
authors: [open-codesign]
tags: [design, form, ux]
license: MIT
---
## When to use
## Rules
## Do / Don't
## Code patterns
内部 skill() 调用名使用 snake_case(如 skill("form_layout")),SKILL.md 文件名 / name 字段用 kebab-case(如 form-layout/SKILL.md),由别名映射层处理。仓库中的 loader(packages/core/src/skills/loader.ts)实现了三档加载:project > user > builtin(loadAllSkills,同名时高优先级覆盖),builtin 目录在桌面端解析为 <userData>/templates/skills;packages/core/src/skills/types.ts 中 SkillFrontmatterV1 定义 frontmatter 的合法 schema。
现有 12 个 skill 保留并升级:dashboard(加 Vercel Geist scale、APCA contrast rule、4-tier surface)、landing-page(blueprint grid、View Transitions)、glassmorphism(合并进 surface-elevation,保留 alias)、editorial-typography(Swiss grid、pull-quote、drop-cap)、chart-svg(APCA 调色板、色盲友好)、heroes(View Transitions、CJK text-autospace)、slide-deck(investor deck ratio + Geist dark)、pricing/footers/chat-ui/data-table/calendar(加 APCA 提醒)。
v0.2 新增 P0(5 个):
| skill | 何时用 | 关键规则 |
|---|---|---|
form-layout |
3+ 字段表单 / onboarding / 结账 / 设置 | 单列为主;label 在字段上方(禁用 placeholder 当 label);inline validation 在 blur 后;多步在逻辑接缝切分 + progress;44px 最小触摸目标 |
empty-states |
Dashboard panel / 搜索结果 / 首次使用 | 三类:first-use(教育+CTA)/ no-results(reframe+建议)/ error(原因+重试);必带 action button;不准出现裸 "No data" |
loading-skeleton |
形状可预测的异步内容 | 仅形状可预测时用;匹配元素几何;progressive;不可预测转 spinner;10-30s 超时转 error+retry;不做全屏 spinner |
surface-elevation |
卡片 / 模态 / 下拉 / 层级 UI | 层级靠 lightness 而非单一阴影;4-tier: base/raised/overlay/scrim;dark mode 每层 L +5-8%;layered shadow 至少 2 层;nested radius(child ≤ parent) |
cjk-typography |
任何含中/日/韩的页面 | line-height: 1.7-1.8;word-break: normal 简中;line-break: strict 日文;font stack: PingFang SC → Noto Sans SC → system;禁加 letter-spacing;CJK+拉丁混排用 text-autospace 或 U+2009;body 16-18px |
P1 延后(v0.3 候选):oklch_color_system / micro_motion / bento_grid / neo_brutalist / scroll_narrative / investor_deck / navigation-patterns / whitespace-rhythm / icon-system / page-transitions / color-accessibility。
借鉴 huashu-design 的两个 skill:direction-advisory(用户没明确方向时从 5 个设计学派 × 20 哲学抽 3 个不同风格生成 demo 让用户选)与 expert-review(5 维评分:philosophical consistency / hierarchy / execution / functionality / innovation,仅 vision model 对 preview screenshot 做 critique)。expert-review 是轻量级 verifier 的复活路径——不是硬 loop subagent,而是用户主动 / agent 主动调的 skill,代码量 = 一段 prompt。
12.3 Brand References(DESIGN.md 集合)
deliver 的文件 = Google DESIGN.md spec 合规(YAML front matter + markdown body,基于 W3C DTCG)。主素材源是 VoltAgent/awesome-design-md(69 个品牌、9 段精写 prose,MIT)与官方品牌网站 CSS(程序化抽取 token 填 YAML front matter);npx brandmd 可教用户自助生成新品牌。
产出结构:packages/core/src/brand-refs/<brand>/DESIGN.md,每个文件 = YAML front matter(colors / typography / spacing / components)+ prose 段(Visual Theme & Atmosphere、Color Palette & Roles 等),尾部带 attribution("Inspired by [Brand]. Tokens derived from publicly available CSS. Source: VoltAgent (MIT).")。推荐预装 25 个品牌:Vercel、Linear、Stripe、Figma、Notion、Apple、Airbnb、Spotify、Shadcn/Cursor、Supabase、PostHog、Framer、RunwayML、Mistral AI、ElevenLabs、Coinbase、Revolut、Nike、Ferrari、SpaceX、Starbucks、Shopify、IBM、Raycast、Cal.com。skill("brand:<name>") 懒加载,system prompt manifest 里列 25 个名字(~300 字节)。
用户路径(v0.2 写进文档):预装清单外的品牌 → npx brandmd https://yourbrand.com 生成 prose 草稿 → npx @google/design.md lint 校验 + 手补 YAML → 落到 workspace 根目录的 DESIGN.md。
DESIGN.md 是双向 artifact:
- 输入:workspace 根的 DESIGN.md 自动注入 system prompt(Brand acquisition / brand skill 路径);
- 输出:agent 可以
done("DESIGN.md")产出合规 DESIGN.md(YAML + prose),用户可导出或让其它工具消费; - 跨工具兼容:生成的 DESIGN.md 可被 Stitch / Cursor / Claude Code 直接读;
- Stitch 反向导入:用户从 Stitch 导出的 DESIGN.md 拖进 workspace,agent 立刻"懂"该品牌系统。
13. Phase 规划(基于 spike 结论重估)
| Phase | 内容 | 估时 |
|---|---|---|
| Phase 1 Foundation | Pi 集成 spike(已完成)、dev/v0.2 分支、createAgentSession() 骨架 + IPC、config.toml → pi.registerProvider() 翻译层、AuthStorage 路径替换 |
3-5 天 |
| Phase 2 工具 + 存储 | tool_call hook + Permission Dialog UI、FSWatcher → Files tab、v0.1 → v0.2 迁移脚本、删 SQL 相关 IPC、session JSONL 接通 chat pane |
1-2 周 |
| Phase 3 Design-domain 工具 | ask + AskModal(5 种题型)、scaffold + 预装清单、skill + manifest + 懒加载、preview 拆分(vision → screenshot / 否则 → DOM outline)、tweaks 跨文件 |
1-2 周 |
| Phase 4 System prompt + 资源预装 | 主 system prompt 按 §5 写满(含 Brand Acquisition Protocol)、~30 个 scaffold、5 个新 skill + 现有升级、~25 个 brand refs | 3-5 天 |
| Phase 5 UX 抛光 + 测试 | 中断 / 后台进程精细化(SIGTERM 流程)、capability-based tool exposure、progressive disclosure 兜底、E2E + bug bash、release note + upgrade doc | 3-5 天 |
重估总计:~4-5 周单人,2-3 周双人,比 spike 前估的 6-8 周缩减 1/3。主要节省来自:bash 不用自写(省 1-2 周)、session 存储不用自写(省 1 周)、model capability 不用维护表(省几天)。
14. 开放问题 / 风险
必须 spike 验证的(均已 Pass)
- pi-coding-agent 的 bash hook 接口是否存在 — ✅ Pass;
- pi 的 Model 类型是否暴露 vision capability — ✅ Partial→Pass;
- pi SessionManager 能否指定 storage 目录 — ✅ Pass。
设计未完全定的
- Preview 工具对非 web artifact source(SVG / 图像)的渲染策略;
- app 首次启动 + 无默认 workspace 根路径时的降级;
- Export / Claude Code 手递 bundle 具体 schema(v0.2 可先简化 zip + README);
- 是否在 v0.2.x 加
expert-reviewskill(agent 自调,对 preview screenshot 做 5 维评)。
产品 / 业务风险
- Brand refs license 合规:VoltAgent 合规性 + attribution(待调研);
- Google DESIGN.md spec alpha 期可能 breaking change;
- pi-ai / pi-agent-core 版本追踪:pin 死会错过更新,追 latest 可能炸。
性能 / scalability(暂不处理)
- 大 session(500+ turns)UI 虚拟化;
- 大 workspace(5000+ files)FSWatcher 开销;
- 多 design 并发 dev server 资源。
15. 附录:关键决策快速查表
| 决策 | 选项 | 结果 |
|---|---|---|
| 存储 | SQL / JSONL | JSONL + filesystem |
| Design 模型 | 独立实体 / session | session |
| Workspace | 分 sealed/open / 统一 | 统一,默认根目录 |
| 工具数量 | 55 (Claude Design) / 12 | 12(计划口径 15,含 pi 自带 7) |
| Loop 结构 | 相位 / agentic | agentic,软引导 |
| 权限 | 无 / 多 mode / 单 mode 4-tier | 单 mode 4-tier |
| Verifier subagent | 有 / 没有 | 没有 |
| Working memory | 有 / 没有 | 没有,用 AGENTS.md |
| Snip 工具 | 有 / 没有 | 没有 |
| DESIGN.md | 自发明 / 抄 Google | 抄 Google spec |
| Skill 格式 | 自发明 / 抄 agentskills.io | 抄 agentskills.io |
| Brand refs | 无 / 抄 awesome-design-md | 抄并预装 25-30 个 |
| JSX 默认 | 每任务判断 / 默认 JSX | 默认 JSX + 代码简洁规则 |
| 向前兼容 | 严格 schemaVersion / 早期宽松 | v0.x 宽松 |
| Screenshot 截图 | 每次评论自动截 / 用户主动 | 用户主动粘 |
| Verifier 代替 | preview 自检 | preview 自检 |
| 消息队列 | 抄 pi / 不做 | 不做 |
| Session 分支 UI | 暴露 / 隐藏 | 隐藏(引擎支持,UI 不给) |
| Undo | 做 / 不做 | 不做(只 Stop/Esc) |
结语:如何继续深入本仓库
本文描述的是 v0.2 的设计蓝图,而当前仓库的 packages/core 已将该蓝图的大部分工具与流程落地。建议的阅读路径:
- 先读 docs/v0.2-plan.md 原文与 docs/plans/2026-04-23-v0.2-agentic-design-loop-design.md(早期设计文档,可对比演变);
- 通读 packages/core/src/agent.ts 的
generateViaAgent,看 10 个设计工具如何被组装、set_title/set_todosgate 如何生效、done的 3 轮修复上限如何工作; - 逐个研读 packages/core/src/tools/ 下的
ask.ts/scaffold.ts/skill.ts/preview.ts/tweaks.ts/done.ts及各自的.test.ts,理解每个工具的 wire schema、预算上限与安全边界; - 结合 packages/core/src/skills/loader.ts(三档 skill 加载)与 packages/shared/src/design-md.ts(DESIGN.md 校验),体会"skill 懒加载 + 设计 token 作为 baton"的设计闭环。
注:本文基于仓库内
docs/v0.2-plan.md撰写,计划中提及的外部链接(Google Stitch、VoltAgent、huashu-design 等)属于方案参考来源;仓库为只读,所有安装、配置与运行方式均以仓库内文档与源码为准。