不写 Agent 的 Agent 产品

一个不写 Agent 循环的 Agent 产品

2026 年 4 月，Anthropic 发布 Claude Design——第一次让大模型不再吐散文，而是直接交付设计成品。它火了，但它闭源、付费、纯云、锁死在 Anthropic 的模型和技能上：不能自托管，不能换 Agent，不能 Vercel 部署。

Open Design（下称 OD）是它的开源替身。README 的定位句拆成三条可验证的工程主张：

与本系列前九个项目的根本差别

前面九份分析（opencode / hermes-agent / Raven / CodeWhale / goose / nanobot / grok-build / OpenManus / Suna / openworker）里，每一个都在实现自己的主循环：调模型、解析工具调用、执行、拼上下文、再调模型。它们争的是「谁的循环更好」。

OD 一行主循环都没有。docs/agent-adapters.md:5 说得非常直白：

We delegate the entire agent loop — model calls, tool use, context management, permission handling, resume, cancel — to the user's existing code agent CLI. OD's job is to detect it, feed it a skill + prompt + working directory, and stream its output back to the web UI.

以及那句立论 docs/agent-adapters.md:9：

Thesis: The code agent space has already converged on strong implementations… Reimplementing another one is worse than talking to all of them.

数字化的项目形状

全景架构：四进程 · 四类内容 · 一条 SSE

flowchart TB
    subgraph P1["① 渲染进程 · 浏览器 / Electron renderer"]
        UI["Next.js 16 + React 18
聊天 · 文件工作区 · 沙箱 iframe 预览 · 设置"]
    end
    subgraph P2["② Web 侧车"]
        WEB["静态 UI + 预览状态
/api/* · /artifacts/* · /frames/* 重写"]
    end
    subgraph P3["③ Daemon · Node 24 + Express + better-sqlite3"]
        API["/api/* 32 个路由模块"]
        DB[("SQLite: projects · conversations
messages · runs · memory")]
        COMP["提示词组装器 2075 行"]
        REG["运行时注册表 26 条"]
        LINT["lint-artifact"]
        JURY["Critique Theater"]
    end
    subgraph P4["④ 被 spawn 的 CLI（不是 OD 的代码）"]
        CLI["claude / codex / cursor-agent / copilot /
opencode / devin / hermes / kimi / pi / …"]
    end
    subgraph P5["⑤ Electron main（可选）"]
        SHELL["原生窗口 · 自动更新 · 文件夹选择器
sidecar IPC"]
    end
    UI -->|同源 HTTP + SSE| WEB --> API
    SHELL --> WEB
    SHELL -.->|HMAC 单次令牌| API
    API --> DB
    API --> COMP --> REG
    REG -->|spawn, cwd = 项目工作区| CLI
    CLI -->|原生工具| FILES["项目文件（真实磁盘）"]
    CLI -->|stdout| API
    API -->|SSE 规范化事件| UI
    API --> LINT
    API --> JURY
    FILES -->|文件事件| UI
    

四条必须记牢的边界

1. Web UI 和 od CLI 调同一套 daemon HTTP API。docs/architecture.md:75「The CLI is not a second business-logic implementation; it is the machine-readable surface for the same capabilities.」这就是仓库反复强调的 dual-track rule：加一个用户能感知的能力，必须同一次改动里补齐 contract 类型 + daemon 路由 + web 界面 + od 子命令。
2. 协议是 HTTP + SSE，不是 WebSocket。架构文档开头有一段罕见的「历史否定说明」docs/architecture.md:11-16：最早的草案画过 Vercel 隧道模式、浏览器直连模式、WebSocket session.generate、内存 session bus、history.jsonl、三根监听式技能注册表——全部被实现推翻。这段「否定式文档」是判断一份 spec 是否可信的好信号。
3. Daemon 是唯一特权进程。它绑 loopback，拥有 SQLite、凭证、项目文件、spawn 权。web 只是壳。
4. 子进程不是 OD 的代码。最容易搞混的一点，值得说第二遍。

内容四平面

OD 把「让模型做出好设计」拆成四条互相正交的轴。craft/README.md:9-16 的表格是最清楚的官方表述：

第四轴是 OD 相对 Claude Design 最聪明的一处拆分。craft/README.md:18-21：

DESIGN.md tells the agent which colors and fonts a brand uses. craft/ tells the agent the universal rules a competent designer applies on top — e.g. ALL CAPS always needs ≥0.06em tracking, regardless of the brand.

技能通过 frontmatter 按需订阅工艺规则，只有被列出的段落会进提示词——一个只排版的技能不用为色彩、动效内容付 token 成本：

od:
  craft:
    requires: [typography, color, anti-ai-slop]

注册表的「用户根优先」扫描

四类内容都遵循同一条发现规则：每次请求都重扫（没有 watcher、没有 SIGHUP、不用重启），同名用户条目遮蔽内置条目（不删除，删掉用户版内置版自动回来）。聊天期解析跨两个注册表——因为持久化的项目里 skillId 既可能是功能技能也可能是设计模板。这是历史包袱换来的兼容性。

三种运行形态与「数据根」这条唯一真理

When ports are not supplied, tools-dev chooses available daemon and web ports… Ports are transport details; they do not define process identity, namespaces, or daemon data roots. docs/architecture.md:22-31

端口是临时的，身份不是端口决定的。打包桌面模式下 Electron 甚至不假设端口——它通过 sidecar IPC 去问 web 的真实 URL。这跟 openworker 用固定 8765 端口 + token 文件的做法形成对照：OD 把端口彻底降级成传输细节。

「数据根契约」：一处刻意的文档纪律

这是全仓库最有意思的一条元规则。docs/architecture.md:160-162：

This document intentionally gives no concrete daemon data path. The root AGENTS.md section Daemon data directory contract is the only path authority.

README 里也重复了同一句禁令（「This README MUST NOT restate it」）。apps/daemon/AGENTS.md:97 再补一刀：「Route all daemon-owned data through RUNTIME_DATA_DIR or constants derived from it.」

为什么值得单独拎出来讲？因为多处文档各自写死一个路径是所有本地优先应用的经典腐烂源：改了实现，八个 md 里有六个还写着旧路径，用户按文档找不到数据。OD 的做法是把路径降级成单点权威，其他所有文档只允许引用不允许复述。

flowchart TB
    ENV["OD_DATA_DIR 环境变量"] -->|启动时解析一次| ROOT["RUNTIME_DATA_DIR"]
    ROOT --> D1["SQLite 库"]
    ROOT --> D2["托管项目工作区"]
    ROOT --> D3["artifacts"]
    ROOT --> D4["用户 skills / templates / design-systems"]
    ROOT --> D5["凭证 · 自动化状态 · 插件状态"]
    IMP["POST /api/import/folder"] -->|唯一例外| EXT["用户选中的外部 baseDir
（校验 + 边界限制，不拷贝）"]
    

适配器契约：RuntimeAgentDef 是数据规格，不是类

面对「要支持 25 个 CLI」这个需求，99% 的团队会写一个抽象基类。OD 没有。docs/agent-adapters.md:17：

An adapter is not a class that implements the agent loop. It is a plain data object — one RuntimeAgentDef object literal per CLI — that declares how to talk to that CLI… There is no per-agent subclass and no run() / cancel() method to implement.

契约本体在 apps/daemon/src/runtimes/types.ts:101-253，共 ~45 个字段，其中只有 6 个必填：

export type RuntimeAgentDef = {
  id: string;                          // 唯一键，注册表用它去重
  name: string;                        // 显示名
  bin: string;                         // 要在 PATH 上探测的可执行文件
  versionArgs: string[];              // 版本探测参数
  fallbackModels: RuntimeModelOption[];// 探测不到模型时的静态兜底
  buildArgs: (prompt, imagePaths, extraAllowedDirs?, options?, runtimeContext?) => string[];
  streamFormat: string;               // 引擎据此分派到解析器
  // …剩下 ~38 个可选字段，全部是数据或纯 arg-builder
};

关键性质：buildArgs 是唯一的函数字段，而且它是纯的——输入提示词和选项，输出 argv 数组。它不 spawn、不读文件、不管生命周期。所以探测、启动、调用、取消、解析全部由共享引擎做。

Adding a CLI is a one-file change. Drop a new runtimes/defs/<cli>.ts… no engine edits, no new class, no method overrides. docs/agent-adapters.md:27

注册表：81 行 + 一条启动期不变式

// registry.ts:30-57 —— 26 条基础定义
const BASE_AGENT_DEFS: RuntimeAgentDef[] = [
  amrAgentDef, claudeAgentDef, codexAgentDef, devinAgentDef,
  opencodeAgentDef, byokOpenCodeAgentDef, hermesAgentDef, traeCliAgentDef,
  grokBuildAgentDef, kimiAgentDef, cursorAgentDef, qwenAgentDef,
  qoderAgentDef, copilotAgentDef, ampAgentDef, piAgentDef,
  kiroAgentDef, kiloAgentDef, vibeAgentDef, deepseekAgentDef,
  aiderAgentDef, antigravityAgentDef, reasonixAgentDef, codebuddyAgentDef,
  mimoAgentDef, atomcodeAgentDef,
];

// registry.ts:65-68 —— 用户本地 profile 合并进来
export const AGENT_DEFS = [...BASE_AGENT_DEFS, ...readLocalAgentProfileDefs(BASE_AGENT_DEFS)];

// registry.ts:70-76 —— 启动期不变式：id 不许重复，重复直接 throw
const ids = new Set();
for (const def of AGENT_DEFS) {
  if (ids.has(def.id)) throw new Error(`Duplicate agent definition id: ${def.id}`);
  ids.add(def.id);
}

三种「会话续跑」风格

types.ts:189-209 用三个布尔字段区分了三种截然不同的续跑机制，这是我在其他项目里没见过的精细分类：

混淆前两者会导致「以为在续跑，实际每次都新开」——捕获式的 newSessionId 根本不传给 CLI。

契约的边界：它刻意不包含什么

docs/agent-adapters.md:176-181 有一段「反向说明」，价值不亚于正向说明：

探测与能力协商：为什么必须探测「将来真正会被 spawn 的那个路径」

flowchart TB
    START["probe(def, configuredEnv)"] --> RESOLVE["① resolveAgentLaunch(def, env)
解析出「将来真正会 spawn 的路径」"]
    RESOLVE -->|无路径| UNAVAIL1["不可用 + ExecutableDiagnostic"]
    RESOLVE --> ENV["② 组装 spawn 环境"]
    ENV --> VER["③ 版本探测"]
    VER -->|OS 级缺失/不可执行| UNAVAIL2["不可用 + NotInvocableDiagnostic"]
    VER -->|能启动但拒绝 --version| OKNOVER["✅ 可用，version = null"]
    VER -->|成功| PAR
    OKNOVER --> PAR
    PAR["④ 三个后置探测并发 Promise.all"] --> C1["--help 能力表"]
    PAR --> C2["模型发现"]
    PAR --> C3["鉴权探针（仅当声明了）"]
    C1 --> CACHE["agentCapabilities.set(def.id, caps)"]
    C1 & C2 & C3 --> OUT["DetectedAgent"]
    

翻译成人话：GUI 启动的 App 拿到的 PATH 是被系统精简过的（macOS 的 launchd 不读你的 .zshrc），nvm 装的 shim 在里面跑不起来；但启动解析器有能力升级到打包的原生二进制。如果探测用 A 路径、真跑用 B 路径，用户就会看到「没装」但其实能跑。

三个次要但会救命的细节

并发的动机被写进注释detection.ts:273-277：「run them concurrently so a single agent's detection wall is max(help, models, auth) ≈ 5s rather than the sum ≈ 15s.」

每条适配器故障隔离：裸 Promise.all 会因一条拒绝而整体拒绝——一个坏掉的可执行文件不能清空整个选择器。

鉴权：只对声明了探针的适配器断言

这是一处刻意的减法。老做法是看 ~/.foo/ 目录在不在来猜有没有登录——猜错的代价是把能用的 agent 标成红叉。

Definitions without authProbe are not assigned a synthetic auth failure from a config-directory guess. docs/agent-adapters.md:126-128

没声明探针就是 unknown，真正的鉴权失败只从真实运行失败的错误文本里推断（classifyAgentServiceFailure）。Claude 的探针就是 ['auth','status']，5 秒超时。

探测的 UX

GET /api/agents?stream=1 每探完一条就发一个 agent SSE 事件，最后 done。设置面板因此不用等最慢的那条 CLI 就能开始画卡片。

没有 24 小时探测缓存——每次调用都重新并发探测。这是一个「宁可多花几秒也不要给用户看陈旧状态」的取舍（用户刚 npm i -g 装完，刷新就该看见）。

四种流格式：从 claude-stream-json 到 ACP 再到裸文本

九条 ACP 适配器共用同一个传输层——这是「新增一条 ACP agent 只需一个 def 文件」的直接原因。defs/kiro.ts 637 字节、defs/vibe.ts 635 字节、defs/kilo.ts 629 字节。

所有解析器输出同一套事件：thinking / tool-call / tool-result / text-delta / file-write / error / done。这套事件是由解析器定义的，不是由 def 定义的docs/agent-adapters.md:107。

plain 流的 <artifact> 提取：最弱的适配器要写最多的代码

裸文本流的 CLI 没有结构化的文件写入工具调用。约定是 Anthropic 风格的源码块，run 结束时扫 stdout 提取。听起来五分钟能写完，实际 plain-stream.ts 有 473 行，因为要绕开四个坑：

再加两个防炸弹：MAX_ARTIFACTS_PER_RUN = 50，文件名冲突加 -2/-3（上限 10 000）。

落盘时同时写「产物清单」

// plain-stream.ts:421-472 —— 按扩展名生成 artifactManifest
// .html → { kind:'html', renderer:'html', exports:['html','pdf','zip'], primary:true }
// .css  → { kind:'code-snippet', renderer:'code', exports:['txt','zip'] }
// .svg  → { kind:'svg', renderer:'svg', exports:['svg','zip'] }
// .md   → { kind:'markdown-document', renderer:'markdown', exports:['md','html','pdf','zip'] }

这份清单就是 CONTEXT.md:23-25 定义的 Artifact Manifest——「把一个项目文件标记成正式产物，并记录它的种类、渲染器、导出方式、入口文件」的旁挂元数据。没有它，文件工作区只能靠扩展名猜。

嵌套 agent：一个诚实的开放问题

Claude Task frames have a non-null parent_tool_use_id; the parser surfaces their content but prevents the child's turn_end from completing the parent run. The UI still does not expose an independent nested-run tree. docs/agent-adapters.md:518-522

内容能显示，但 UI 里没有嵌套树。文档把它明确列在「Open questions」里，而不是假装已解决。

两档执行画像：filesystem vs text_artifact

这是 OD 处理「适配器能力参差」的核心抽象，只有一个 249 字节的文件：

// packages/contracts/src/execution-profile.ts
export type ExecutionProfile = 'filesystem' | 'text_artifact';
export function executionProfileFromStreamFormat(streamFormat) { … }

flowchart TB
    RUN["一次生成"] --> PROF{"executionProfileFromStreamFormat
(def.streamFormat)"}
    PROF -->|filesystem| F1["CLI 用自己的 Write/Edit 原生工具
直接在项目 cwd 写文件"]
    F1 --> F2["文件事件推给文件工作区"]
    F2 --> F3["可预览文件 = 交付物"]
    F3 --> F4["助手以普通摘要收尾
❌ 禁止再输出 artifact 源码块"]
    PROF -->|text_artifact| T1["模型循环里没有文件系统工具"]
    T1 --> T2["唯一交付形态：一个完整的
artifact 源码块"]
    T2 --> T3["run 结束后 daemon 扫 stdout
persistPlainStreamArtifacts()"]
    T3 --> T4["落成项目文件 + Artifact Manifest"]
    T4 --> F3
    

输入分流：六个创建面 × 七种 skill mode

They are intentionally not one-to-one. UI tabs describe the workflow a user starts; skill modes describe how the daemon indexes and routes an instruction bundle. docs/modes.md:5-11

Daemon 侧七种 od.mode：prototype · deck · template · design-system · image · video · audio。

「模板替换默认技能」而不是「模板叠加默认技能」

A selected Start from template replaces the tab's default skill as the project's primary skillId… it does not automatically compose the default prototype skill with the template. docs/modes.md:36-41

选了 saas-landing 模板，就没有默认 prototype 技能了。列表分离（两个 API）不等于自动组合——两份都注入会产生互相打架的工作流指令。

HyperFrames：一个不新增后端 kind 的新入口

CONTEXT.md:39-41 记录了一个很聪明的产品／工程折中：HyperFrames 在 Home 有独立入口（用户感知上是一等公民），提交时却是 kind: "video" + videoModel: "hyperframes-html"——不动 ProjectKind 联合类型、不动 SQLite schema、不动已有项目。

心脏地带：composeSystemPrompt 的二十层与缓存分区

如果说别的 Agent 项目的心脏是主循环，OD 的心脏就是这个函数：daemon 版 apps/daemon/src/prompts/system.ts:791-1370（约 580 行函数体，文件 2 075 行），BYOK 镜像版 packages/contracts/src/prompts/system.ts:256-496。ComposeInput 有 30+ 个字段。

装配顺序（classic 变体）

注意 ⑬ 和 ㉑ 是同一件事说两遍：设计系统的内容在第 13 层注入，第 21 层再补一个「别再问用户要视觉方向了」的覆盖。为什么要重复？因为第 5 层的发现层里有一条硬规则是「turn 1 必须发问卷」，而问卷里通常有品牌／方向问题。

// daemon/prompts/system.ts:603-616 —— ACTIVE_DESIGN_SYSTEM_VISUAL_DIRECTION_OVERRIDE
- Do not ask the user to pick a separate theme color, visual direction, palette,
  typography mood, or direction card.
- Do not emit a direction question-form, a `direction-cards` picker, or any
  visual-direction card while an active design system is present.
- If an earlier discovery answer asks to "Pick a direction for me", treat that as
  already satisfied by the active design system and continue with the plan.

slim vs classic：一次带 A/B 的提示词重构

Slim core collapses the discovery layer + designer charter + their tail overrides into one charter document; the classic stack keeps the legacy layered composition until the A/B comparison signs off.

提示词重构的风险极高（改一个词可能让通过率掉 20%），所以不一次性替换，两套并存 + A/B。slim 还带两个 classic 没有的优化：

1. 方向库改成索引 + 按需拉取system.ts:996-1005：「Slim carries only the id+label index and the agent pulls the chosen direction's full spec via od tools directions --id <id> — but ONLY on filesystem runs. text_artifact runs have no tools to dereference the index… anything less tells them to bind palettes they cannot fetch.」
2. 平台契约块按信号稳定性分区——见下一节。

缓存友好的分区排序：全仓库最精妙的一处工程

Head ordering differs by variant, following prompt-caching prefix rules (stable content first)… the STATIC charter opens the document… so every conversation shares the same cacheable prefix; conversation-stable overrides follow, project context after that, turn-variable blocks last. daemon/prompts/system.ts:851-867

LLM 的前缀缓存是前缀匹配的：只要前 N 个 token 一样就能命中。把最稳定的放最前，一个回合中途翻转的信号（用户说「改成 iOS 版」）只会作废缓存后缀，而不是整份提示词。

缓存命中归因

// runtimes/chat-prompt-inputs.ts:394-442
if (!isResuming)                            → missReason: 'new-session'
if (storedStablePromptHash === currentHash) → hit: true
if (storedStablePromptHash === null)       → missReason: 'missing-stored-hash'
else                                        → missReason: 'stable-prompt-changed'
                                              + changedSections: 逐段 diff

changedSections 只在真正漂移时计算。注释解释：missing-stored-hash 是没有基线的老行，在那里报告「所有段都变了」会淹没真正关心的信号。做遥测时要小心这类「技术上正确但信息量为零」的输出。

Ask 模式：轻，但不失忆

every artifact-oriented block (the ~3k-token discovery layer, direction library, device frames, the full designer charter, deck framework, media contracts, codex imagegen override, critique panel, DS visual-direction override) is gated off so the turn stays cheap. Memory, custom instructions, the active design system, attached skills, plugins, MCP tools, and the clarifying-questions surface are still composed in — Ask mode is light, not amnesiac. system.ts:939-947

省掉的是工作流，保留的是上下文。用户问「这个配色为什么这么选」时，不需要设计师宪章，但需要知道当前设计系统是什么。

三条硬规则：question-form → 品牌分支 → TodoWrite

DISCOVERY_AND_PHILOSOPHY（packages/contracts/src/prompts/discovery.ts:25-354，330 行纯提示词）是整个产品的行为脚本。它蒸馏自两个上游项目：alchaincyf/huashu-design（初级设计师模式、变体而非答案、反 AI 味、化身专家）和 op7418/guizang-ppt-skill（预飞资源读取、P0 自检、主题节奏）。

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant H as OD 宿主
    Note over A: RULE 1 · 第 1 回合
    U->>A: "帮我做一个 SaaS 落地页"
    A->>H: 一句短散文 + question-form + 停
    Note right of A: ❌ 不读文件 ❌ 不 Bash
❌ 不 TodoWrite ❌ 不扩展思考
    H->>U: 渲染成问卷卡（每题预填）
    Note over A: RULE 2 · 第 2 回合
    U->>A: "[form answers — discovery] brand: brand_spec …"
    alt 分支 A：给了品牌/参考源
        A->>A: 品牌提取五步（Bash / Read / WebFetch）
        A->>H: 写 brand-spec.md
        A->>U: 一句话复述系统（便于廉价纠偏）
    else 分支 B：没有品牌源
        A->>A: 用活跃设计系统 / 自己从方向库挑
        Note right of A: ❌ 绝不再弹第二个方向问卷
    end
    Note over A: RULE 3 · 第 3 回合起
    A->>H: TodoWrite 九步计划
    loop 每完成一步
        A->>H: 立刻标 completed
    end
    A->>A: 第7步 checklist.md（P0 必须全过）
    A->>A: 第8步 五维自评，<3/5 就返工
    A->>H: 第9步 交付
    

RULE 1 的偏执程度

your very first output is one short prose line + a <question-form> block. Nothing else. No file reads. No Bash. No TodoWrite. No native tool calls. No extended thinking. The form is your time-to-first-byte. discovery.ts:40-44

而且它明确堵死了模型最爱找的借口：

The form applies even when the user's brief looks complete… Do not justify skipping it ("the brief is rich enough"); ask anyway. The user is fast at picking radios; they are slow at re-doing a wrong direction. discovery.ts:154

只有三种情况允许跳过：在已有设计里做微调、用户明说「skip questions / just build」、消息以 [form answers — …] 开头。

表单编写规则里的六条工程细节

RULE 2 的四步优先级 + 品牌提取五步

// discovery.ts:167-172 —— 分支解析顺序
1. 当前消息/附件/先前简报/URL 里已有真实品牌源  → 分支 A
2. 否则看提交的 brand 值（有 [value: ...] 用稳定值，不用可见标签）
3. brand 值是 "brand_spec" 或 "reference_match"   → 分支 A
4. 否则                                            → 分支 B

1. 定位源：附件就列出来；URL 就 WebFetch <brand>.com/brand、/press、/about
2. 下载样式产物：CSS、品牌指南 PDF、截图
3. 提取真值：grep -E '#[0-9a-fA-F]{3,8}' 抓 CSS 里的 hex；截图靠肉眼看排版。「Never guess colors from memory.」
4. 编码成契约：写 brand-spec.md——六个 OKLch 色 token + display/body/mono 字体栈 + 3–5 条观察到的版式姿态
5. 口头复述：一句话说清将用的系统，让用户能廉价纠偏

RULE 3 的九步计划与五维自评

1.  读活跃 DESIGN.md + 技能资源（template.html, layouts.md, checklist.md）
2.  绑定 token 到 :root（分支A 用 brand-spec.md；有设计系统用它；否则自选方向）
3.  规划章节/幻灯/屏幕清单，含平台变体与节奏（写之前先口头说一遍）
4.  把种子模板拷到项目根
5.  粘贴并填充规划好的版式
6.  用简报里的真实、具体文案替换 [REPLACE] 占位
7.  自检：跑 references/checklist.md（P0 必须全过）
8.  评审：五维雷达，任一 <3/5 就修
9.  交付

Deck 的「框架优先」铁律

Decks especially — framework first, content second.… copy the deck framework HTML verbatim before authoring any slide content. Do NOT write your own scale-to-fit logic, keyboard handler, slide visibility toggle, counter, or print stylesheet — every freeform attempt at this re-introduces the same iframe positioning / scaling bugs we have already fixed in the framework. discovery.ts:223

// contracts/prompts/system.ts:466-485 —— 三个分支，每个都是一次事故的化石
const isDeckProject     = skillMode === 'deck' || metadata?.kind === 'deck';
const isFreeformProject = !skillMode && (!metadata || metadata.kind === 'other');
const hasSkillSeed      = !!skillBody && /assets\/template\.html/.test(skillBody);

if (isDeckProject && !hasSkillSeed)          注入通用骨架;
else if (isFreeformProject && !hasSkillSeed) 注入带条件前缀的骨架;
// 有技能种子时不注入——种子自己有更有主张的框架（simple-deck 的 scroll-snap、
// guizang-ppt 的杂志版式），重复会冲突

第二个分支的条件前缀值得抄：「If — and only if — the brief reads as slides, keynote, presentation, deck, PPT, or 讲解, follow the framework below. Otherwise ignore everything in this section and continue with the freeform output you would have written anyway.」——给一段「可能不适用」的指令加上显式的适用条件，模型就不会硬套。

记忆与双环：task-brief / verify-scorecard / rule-proposal

记忆不是硬规则

Treat them as preferences and context, NOT hard rules: when they collide with the active design system tokens, the brand wins; when they collide with the active skill's workflow, the skill wins. They are still authoritative for tone, voice, terminology… never re-ask the user about something already captured here. contracts/prompts/system.ts:378

注释说明了这段措辞的用意：「what stops the model from treating remembered preferences as harder than the active design system」——防止「用户上次说喜欢深色」压过「本次品牌是浅色」。

Expanding intent this way changes only WHAT you know going in; it never shortcuts the standard build flow — you still plan with TodoWrite and still run the anti-slop / brand self-check on every artifact-producing turn.

flowchart TB
    IN["用户短请求"] --> MEM{"记忆够不够
扩写成简报？"}
    MEM -->|够 & rewrite=ON| CARD1["① od-card type=task-brief
替代 turn-1 问卷"]
    MEM -->|不够| FORM["走 RULE 1 问卷"]
    CARD1 --> BUILD["TodoWrite + 构建
【不可跳过】"]
    FORM --> BUILD
    BUILD --> SLOP["反 AI 味 / 品牌自检
【不可跳过】"]
    SLOP -->|verify=ON & 有已验证规则| CARD2["② od-card type=verify-scorecard
daemon 程序化检查其存在"]
    SLOP --> HANDOFF["交付收尾"]
    CARD2 --> HANDOFF
    HANDOFF --> FB{"用户纠正里
隐含可复用规则？"}
    FB -->|是| CARD3["③ od-card type=rule-proposal
Keep / Edit / Discard"]
    CARD3 -->|用户点 Keep| STORE[("已验证规则库")]
    STORE -.->|下次注入| MEM
    

内容四平面：skills / design-templates / design-systems / craft

技能格式：原样吃下 Claude Code 的 SKILL.md

基础格式完全不改 Claude Code 的约定，OD 只在 frontmatter 里加一个可选的 od: 命名空间。目标写得很明确：「The goal: zero-config compatibility for existing Claude Code skills.」docs/skills-protocol.md:121

.od-skills 暂存：从符号链接到真实拷贝的一次安全修复

flowchart LR
    SRC1["内置 skills/saas-landing/"] -->|fs.cp dereference:true| STAGE
    SRC2["用户根 skills/saas-landing/"] -->|同名遮蔽| SRC1
    STAGE[".od-skills/saas-landing-3f2a91b0c4/
（项目私有真实拷贝）"]
    STAGE --> AGENT["Agent 读 SKILL.md / assets/ / references/"]
    AGENT -.->|即使 Edit 写坏了| STAGE
    STAGE -.->|❌ 不会影响| SRC1
    FAIL["暂存失败"] -.->|提示词里的绝对路径兜底| SRC1
    

设计系统包：三文件最小契约 + 八层注入顺序

design-systems/<slug>/
├── manifest.json    ← 发现元数据、来源出处、声明的包内路径
├── DESIGN.md        ← 给 agent 看的规范散文（canonical）
└── tokens.css       ← 编译好的语义 token 样式表（canonical）

约束：文件夹 slug 必须等于 manifest.id 且用规范化 ASCII；files.design 固定 DESIGN.md、files.tokens 固定 tokens.css；每条声明的路径必须安全、相对、存在。

富文件是缓存不是真理源：components.manifest.json 由 components.html+tokens.css 派生；design-tokens.json 由 token 契约报告派生且必须与 tokens.css 一致；tailwind-v4.css 由 tokens.css 派生。派生文件一致性由 guard 校验——防的是「有人改了 tokens.css 但忘了重生成，模型读到两套冲突的值」。

flowchart TB
    L1["① 包专属 USAGE.md（或默认使用契约）"] --> L2["② 完整的 DESIGN.md 正文"]
    L2 --> L3["③ import-mode 指引（声明了才有）"]
    L3 --> L4["④ tokens.css"]
    L4 --> L5["⑤ 紧凑组件清单
（无清单时用 components.html）"]
    L5 --> L6["⑥ 富文件按需拉取索引"]
    L6 --> L7["⑦ craft 工艺规则"]
    L7 --> L8["⑧ 活跃技能/模板正文"]
    

默认使用契约值得原样引用daemon/prompts/system.ts:617：

Read DESIGN.md for visual principles, paste tokens.css verbatim into the first <style> when it is provided, and match component shapes from the reference component manifest or fixture when available. Treat any pull-layer index as optional context for deeper inspection; do not assume those files have already been loaded.

最后半句在防一个具体的幻觉：模型看到索引就以为文件已经读过了，然后引用一个它没读过的组件。

craft 的两级执法与两级严格度

而且 craft 文件里逐条标注了哪些是「(guidance, not auto-checked)」。为什么这很重要：如果你写一份「规则手册」但只有 30% 真的被检查，而文档假装 100% 都被检查，那么半年后没人相信这份手册。标注清楚反而让被检查的那 30% 更有权威。

FUTURE_SECTIONS.md 很妙：它让「计划中但还没写的段落」变成可见的、有登记的，而不是靠一个 typo 悄悄漏掉一整段提示词。

质量闸门一：lint-artifact 程序化反 AI 味

apps/daemon/src/lint-artifact.ts，1 000 行 / 46 KB。这是本仓库最有创造性的一个模块：把「一眼假」这种主观判断，落成可执行的正则 + CSS 求值。

十六条规则

真正有工程含量的那一条：ALL CAPS 字距

天真实现是 /letter-spacing:\s*([\d.]+)em/ 抓个数字。OD 做的事复杂得多：

flowchart TB
    S1["① extractCssTokens(html)
收集每个作用域的 --name: value"] --> S2
    S2["② buildResolvedThemes(scopes)
把全局主题作用域（:root、[data-theme=…]）
组合成多套主题"] --> S3
    S3["③ resolveCssVars(body, tokens)
递归解析 var(--x)，最大深度 4"] --> S4
    S4["④ resolveFontSizePx(decls)
同规则里的 font-size 折算成 px（root=16）"] --> J
    J["判定：letter-spacing 在每套主题下、
按该字号是否 ≥0.06em 等效"]
    

三层假阳性防护 + 有理由的阈值

Allow up to ~12 raw hex values outside :root. Device chrome (mobile-app frame: bezel gradient, side rails, status icons) has legitimate hardware-specific values in the 8–10 range; raise the threshold so seed templates pass without ceremony. lint-artifact.ts:415-419

12 这个数不是拍脑袋的，是「手机边框种子模板合法用到 8–10 个」倒推的。每个阈值都应该能说出它是从哪个真实场景倒推的，否则半年后没人敢动它。

反馈回路：给 agent 的报错必须自带修复动作

renderFindingsForAgent()lint-artifact.ts:519-537 有三个要点：按严重度排序（P0 在前）、明确要求重发修正版而不是写解释（「the user has the previous version already」）、每条都带 fix——只给 message 模型会去猜，猜错就多一轮。

质量闸门二：Design Jury 五陪审员评审剧场

产品名 Design Jury，内部代号 Critique Theater。代码路径 apps/daemon/src/critique/、web 侧 components/Theater/、SSE 频道 critique.*、环境变量 OD_CRITIQUE_*——用户可见名来自单个 i18n key critiqueTheater.userFacingName，所以改产品名不用动代码。

Designer is weighted at zero in v1 because their dimensions are aesthetic preferences rather than ship gates. The slot exists so the Designer's qualitative notes still travel into the transcript, and a future config release can bump the weight without changing the schema. docs/critique-theater.md:65-68

保留席位、权重归零——让定性意见进入记录，但不让主观审美卡住发布。这是一个很成熟的产品决策。

// packages/contracts/src/critique.ts:58-73 —— 默认配置
weights: { designer: 0, critic: 0.4, brand: 0.2, a11y: 0.2, copy: 0.2 },
maxRounds: 3, scoreScale: 10, scoreThreshold: 8.0,
perRoundTimeoutMs: 90_000, totalTimeoutMs: 240_000,
parserMaxBlockBytes: 262_144, fallbackPolicy: 'ship_best',
maxConcurrentRuns: 4, enabled: false,

// critique.ts:48-54 —— 浮点比较的教科书处理
.refine((cfg) => cfg.scoreThreshold <= cfg.scoreScale + 1e-9, …)

最关键的实现决定：一个会话，不是五个进程

The orchestrator does not spawn extra processes per panelist. Each panelist is a turn in the same agent session, separated by <PANELIST role="..."> tags… This keeps the operational contract identical to a normal generation: same auth, same env, same logs. docs/critique-theater.md:76-82

All five panelists are turns in the same conversation, which keeps the model context coherent and prevents the "panelist disagrees with itself across processes" failure mode.

flowchart TB
    ART["Agent 发出 artifact"] --> R1["Round 1：五位陪审员各自打分
（同一会话的五个回合）"]
    R1 --> COMP["composite = designer×0 + critic×0.4
+ brand×0.2 + a11y×0.2 + copy×0.2"]
    COMP --> GATE{"composite ≥ 8.0 ?"}
    GATE -->|是| SHIP["Shipped at round N, composite X.X"]
    GATE -->|否| CNT{"round < maxRounds(3) ?"}
    CNT -->|是| REV["发出轮次摘要 → Agent 修改 → 下一轮"]
    REV --> R1
    CNT -->|否| FB["fallbackPolicy"]
    FB --> SB["ship_best（默认）：取 composite 最高的那轮"]
    FB --> SL["ship_last"]
    FB --> FL["fail"]
    

四级开关解析器

技能作者的经验法则：产出确定性产物的技能（如 od-export-pdf）通常 opt-out；生成全新设计输出的（magazine-poster、saas-landing）设 required。

跨 25 条第三方 CLI 的一致性纪律

The conformance harness runs every adapter prerelease against 10 brief templates. If an adapter drops under the 90% shipped or 95% clean-parse thresholds for two consecutive cycles, it gets marked critique:degraded for 24h. The mark auto-clears on the next clean cycle.

…globally during M3 after ≥ 90% of production adapters maintain conformance for 14 consecutive days.

可回放：每次 run 写一份结构化 .ndjson（可选 gz）。Replay 支持 Instant / Live / {intervalMs: N} / Paused（暂停后从光标继续，不重新冲刷已发事件），J/K 逐轮跳，Esc 退出。

插件与原子：atoms + pipeline + 封闭的 until 词汇表

my-plugin/
├── open-design.json    ← 必需：市场元数据 + inputs + pipeline + capabilities
├── SKILL.md            ← agent-skill / scenario 类型必需，其他类型可省
├── README.md           ← 可选
├── preview/            ← 可选：index.html / poster.png（视觉类强烈建议）
└── examples/           ← 可选

核心字段：specVersion（当前 1.0.0）· name（稳定 ID）· version（semver）· od.kind（skill/scenario/atom/bundle）· od.taskKind（new-generation/figma-migration/code-migration/tune-collab）· od.mode · od.capabilities[] · od.inputs[]。

一条重要的默认：od.capabilities[] 要声明最小集——受限安装默认只给 prompt:inject。

原子：daemon 暴露给插件的能力单元

A plugin assembles atoms into ordered stages… The daemon is responsible for resolving each atom into a system-prompt fragment, tool gating, and (when applicable) GenUI surface declarations. Plugins never own the atom implementations; they only reference them by id. docs/atoms.md:1-8

flowchart TB
    M["插件 manifest
od.pipeline.stages[*].atoms[]"] -->|①解析| PS["PipelineStage[]
plugins/pipeline.ts"]
    PS -->|②run 开始前| BODIES["解析内置原子指令体
plugins/atom-bodies.ts"]
    BODIES --> BLOCK["渲染成 ## Active stage 提示词块"]
    BLOCK --> RUN["③ pipeline-runner.ts 逐阶段走"]
    RUN --> E1["发 pipeline_stage_started SSE"]
    E1 --> W["④ 向 atoms/registry.ts 的 worker
要 daemon 可观测的信号"]
    W --> AUDIT["⑤ 往 run_devloop_iterations 写一行审计"]
    AUDIT --> E2["发 pipeline_stage_completed + 信号"]
    E2 --> RUN
    

封闭的 until 词汇表

原子的晋升路径

不要一上来就把新能力做成内置原子。docs/atoms.md:89-100 定义了一条路：① 先作为树外插件实现 → ② 形状稳定后加内置原子 + 往 FIRST_PARTY_ATOMS 追加一行 + 有真实可观测信号时才注册 worker → ③ 同一个 PR 更新文档和 spec 表格 → ④ 通过 pipeline 引用 / GET /api/atoms / od atoms list / od plugin doctor 触达。

安全边界：loopback / SSRF / 桌面 HMAC / .od-skills 拷贝

The effective project cwd is an execution root, not a uniform Open Design sandbox, and external-directory flags can widen a CLI's reach… users must treat these runs as trusted agent execution with the authority shown by the selected definition. docs/agent-adapters.md:442-465

为什么必须这样？「the daemon runs agent CLIs without a TTY, so it must not rely on an interactive tool-approval prompt to make progress.」没有 TTY 就没法交互批准，交互批准会直接把 run 挂死。

放弃了执行层的闸门，安全预算就全花在边界上：

边界一：默认 loopback

daemon 默认绑 127.0.0.1；LAN 暴露需要同时设 OD_BIND_HOST 和 OD_ALLOWED_ORIGINS；连接器凭证和 live-artifact 预览路由无论如何都保持 loopback-only——即使公开部署也不放开。

边界二：SSRF——默认封内网，opt-out 极其严格

默认封锁解析到私有/内部地址的 provider base URL——RFC1918、link-local、CGNAT、云元数据 IP（169.254.169.254 那类，能偷 IAM 凭证）。但真实用户确实有内网网关（VPN 里的 LiteLLM、Ollama），所以有 OD_ALLOWED_INTERNAL_HOSTS：

边界三：桌面文件夹导入的短寿命单次 HMAC 令牌

sequenceDiagram
    participant U as 用户
    participant M as Electron main（可信）
    participant R as Renderer（沙箱）
    participant D as Daemon
    U->>M: 点「导入文件夹」
    M->>U: 原生文件夹选择器
    U->>M: 选中 /Users/me/work/site
    M->>M: 铸造短寿命、单次 HMAC 令牌
    M->>R: 令牌 + 路径
    R->>D: POST /api/import/folder（带令牌）
    D->>D: 校验 HMAC + 规范化路径
拒绝落在自己托管存储内的导入
    D->>D: 打上服务端控制的「可信选择器」标记
    D-->>R: 项目创建成功
    Note over D: 之后每次文件访问都对该外部根做安全路径解析
    

边界四：沙箱 iframe 按需开启最小特性

沙箱 iframe，无宿主同源访问；每个面只 opt-in 它需要的 sandbox 特性（下载、弹窗）。切换 URL/srcDoc 渲染模式时两个 frame 都保持挂载避免重载闪烁；消息处理器校验发送方 iframe；需要来自活跃 frame 的信号会再次核对活跃窗口——最后两条防的是页面里有多个 iframe 时，一个后台 frame 冒充活跃 frame 发消息。渲染模式决策单独放在 apps/web/src/components/file-viewer-render-mode.ts。

边界五：Windows 命令行长度的三重守卫

两个 Windows 守卫在给定解析上互斥。三者一起抓的是：原始字节数没超，但引号密集的提示词（代码块、JSON 形状的技能种子）展开后超过 CreateProcess 的 32 767 字符 lpCommandLine 上限。三者发同一个可行动的 AGENT_PROMPT_TOO_LARGE 错误，而且三者都有单测（超长 + 短提示词分支、两条 Windows 路径的引号密集回归、互斥性检查），「so the guards can't silently regress」。

功能特性拾遗

od CLI 与 MCP 服务端：把 OD 变成别人的工具

OD 出货三种形态：skills、CLI、MCP server。od mcp install <agent> 一行装进 16+ 个 CLI 的配置，然后：

od project list --json
od files list <project-id> --json
od files read <project-id> <relative-path>
od plugin list --json
od skills list --json

Why MCP? Exporting and re-attaching a zip every iteration breaks flow. MCP exposes the design source directly — the agent always sees the live file, not a stale export.

一次值得尊敬的架构回归

The former direct-Anthropic fallback was replaced by the byok-opencode profile… There is no daemon-owned fallback loop and no daemon implementation of Read/Write/Edit tools, and this profile is not an automatic recovery target for failed local agents. docs/agent-adapters.md:206-218

早期版本大概真的在 daemon 里实现过一个「直连 Anthropic + 自己实现 Read/Write/Edit」的兜底循环。现在被彻底删掉了——因为那违背了「我们不实现 Agent 循环」这条根本主张。一旦你开了这个口子，它会慢慢长成第二个（更差的）Agent。

没有跨 agent 兜底链

A chat request explicitly names its agent, and a crash, auth failure, timeout, or invalid invocation remains a failure for that run… the daemon does not silently — or through a dedicated one-click fallback action — move the request to Claude, another detected CLI, or BYOK OpenCode.

只有两个窄规则：运行前默认（agentId 省略时用配置的 agent，不可用就用第一个可用的——「This chooses an agent before a run starts; it is not failure recovery」），和过期会话恢复（清掉同一个 agent 的陈旧会话，用完整 transcript 重新播种——「That recovery never changes agent families」）。

为什么反直觉但正确：自动切换 agent 会让计费、鉴权、输出风格全部悄悄改变，用户根本不知道刚才那份产物是谁做的。

Normal Artifact vs Live Artifact

HyperFrames、导出矩阵与 mock agent

总结：三个最独特的设计与三处取舍

三个最独特的设计

三处必须知道的取舍

它在这十个项目里的位置

继续读