造一个把别人的 Agent 当引擎的设计宿主

先看终点：一个「设计引擎宿主」长什么样

在写第一行代码前，先把要拼的东西看清楚。编程 Agent 和设计 Agent 宿主的分界，不在模型，而在这五件事：

1. 它自己不推理——推理是你机器上那个 claude / codex / cursor-agent 在干；
2. 它的产物是给人看的，不是给编译器看的，所以「对不对」之外还有「好不好看」；
3. 好看这件事有相当大一部分可以程序化执法（Tailwind indigo、两段式渐变、emoji 当图标、ALL CAPS 不加字距）；
4. 品牌是一份可以版本化的契约，不是一堆散落的 CSS 变量；
5. 交付物是真实文件，能预览、能导出、能扔进 Cursor 继续写代码。

flowchart TB
    subgraph UI["① 你能看到的"]
        CHAT["聊天 + 问卷卡片"]
        FW["文件工作区"]
        PREV["沙箱 iframe 预览"]
    end
    subgraph HOST["② 宿主（你要写的全部代码）"]
        REG["运行时注册表
26 条适配器数据定义"]
        COMP["提示词组装器
20+ 层，按变化频率分带"]
        LINT["反 AI 味 linter"]
        JURY["五陪审评审剧场"]
        SSE["统一事件流（SSE）"]
    end
    subgraph CONTENT["③ 内容四平面（文件系统，可版本化）"]
        SK["skills/ 功能技能"]
        TP["design-templates/ 渲染模板"]
        DS["design-systems/ 品牌契约"]
        CR["craft/ 通用工艺规则"]
    end
    subgraph ENGINE["④ 引擎（不是你的代码）"]
        CLI["claude / codex / cursor-agent /
copilot / opencode / …"]
    end
    CHAT --> SSE
    SSE --> COMP
    COMP --> CONTENT
    COMP -->|组装好的系统提示词| REG
    REG -->|spawn，cwd = 项目工作区| CLI
    CLI -->|原生 Write/Edit 工具| FILES["项目文件（真实磁盘）"]
    CLI -->|stdout| SSE
    FILES --> FW --> PREV
    FILES --> LINT -->|artifact-lint 系统提醒| CLI
    FILES --> JURY -->|轮次摘要| CLI
    

我们的设计 Agent 只需要会干一件事（先把一件事干透）：

「帮我们做一个 SaaS 产品落地页，用我们公司的品牌。」

这一句话里，藏着我们要撞的每一堵墙：

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

这个决定的连锁后果（必须提前想清楚）

选 B 不是省事，是换了一组问题：

先看错误的做法

// ❌ 别这么写
abstract class AgentAdapter {
  abstract detect(): Promise<boolean>;
  abstract run(prompt: string): AsyncIterable<Event>;
  abstract cancel(): void;
}
class ClaudeAdapter extends AgentAdapter { /* 200 行 */ }
class CodexAdapter  extends AgentAdapter { /* 200 行 */ }
// × 25 = 5000 行，且每个都要自己实现取消、超时、错误分类

问题不在代码量，在行为漂移：25 个 run() 会有 25 种取消语义、25 种超时处理、25 种错误分类。半年后你会发现 Cursor 的取消不干净、Copilot 的超时没生效——因为没人能同时维护 25 份生命周期代码。

正确的做法：把「怎么跟它说话」和「怎么调度它」彻底分开

// ✅ 一个纯数据对象 + 一个纯函数
type RuntimeAgentDef = {
  id: string;                            // 唯一键
  name: string;                          // 显示名
  bin: string;                           // PATH 上探测的可执行文件
  versionArgs: string[];                // 版本探测参数
  fallbackModels: RuntimeModelOption[];  // 探测不到模型时的静态兜底
  buildArgs: (prompt, imagePaths, extraDirs?, options?, ctx?) => string[];  // 唯一的函数，且是纯的
  streamFormat: string;                 // 引擎据此分派解析器
  // …~38 个可选字段，全部是数据
};

flowchart LR
    DEF["RuntimeAgentDef
（纯数据）"] --> E1["detection.ts
探测"]
    DEF --> E2["launch.ts
路径解析 + 环境"]
    DEF --> E3["invocation.ts
argv 组装 + spawn"]
    DEF --> E4["run 生命周期
取消 / 超时 / 错误分类"]
    DEF -->|streamFormat 分派| E5["4 个解析器之一"]
    

逐条讲为什么：以 Claude Code 的定义为样本

buildArgs: (_prompt, _imagePaths, extraAllowedDirs = [], options = {}, ctx = {}) => {
  const caps = agentCapabilities.get('claude') || {};
  const args = ['-p', '--input-format', 'stream-json',
                '--output-format', 'stream-json', '--verbose'];
  if (caps.partialMessages) args.push('--include-partial-messages');   // 能力门
  if (options.model && options.model !== 'default') args.push('--model', options.model);
  const dirs = extraAllowedDirs.filter(d => typeof d === 'string' && d.length > 0);
  if (dirs.length > 0 && caps.addDir !== false) args.push('--add-dir', ...dirs);
  if (ctx.resumeSessionId)   args.push('--resume', ctx.resumeSessionId);
  else if (ctx.newSessionId) args.push('--session-id', ctx.newSessionId);
  args.push('--permission-mode', 'bypassPermissions');
  return args;
},

注意 _prompt 前面那个下划线——提示词根本不进 argv。理由见第 4 步。

三种「会话续跑」风格要分清

注册表：81 行 + 一条加载期不变式

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);
}

那个 throw 在模块加载期执行。用户自定义的 profile 撞了内置 id → daemon 起不来，而不是安静地覆盖掉内置适配器。让错误尽早、尽响。

契约要克制：明确它不包含什么

这一点比「它包含什么」更重要。刻意没有：nativeSkillLoading / skillInjectionStrategy（技能投递是共享行为）、capabilities() 方法（那个文件全文只有 131 字节）、surgicalEdit 特性门表（那会变成一张永远对不齐的能力矩阵）。

flowchart TB
    S["probe(def, configuredEnv)"] --> R["① resolveAgentLaunch(def, env)
解析出「将来真正会被 spawn 的那个路径」"]
    R -->|解析不出| U1["不可用 + 可执行文件诊断"]
    R --> V["② 版本探测（在那个路径上）"]
    V -->|OS 级缺失/不可执行| U2["不可用 + 不可调用诊断"]
    V -->|能启动但拒绝 --version| OK1["✅ 可用，version = null"]
    V -->|成功| P
    OK1 --> P
    P["③ 三个后置探测并发 Promise.all"] --> C1["--help 能力表"]
    P --> C2["模型发现"]
    P --> C3["鉴权探针（仅当声明了）"]
    C1 & C2 & C3 --> OUT["DetectedAgent"]
    

翻译：GUI 启动的 App 拿到的 PATH 是被系统精简过的（macOS 的 launchd 不读你的 .zshrc）；nvm/fnm/mise 装的 CLI 常常是 shim，在那个精简 PATH 下跑不起来；但你的启动解析器可能有能力升级到打包的原生二进制。于是探测用 A 路径说「没装」，真跑用 B 路径其实能跑——用户看到红叉但功能是好的。

规则：探测入口的第一件事必须是调用和 spawn 完全相同的那个路径解析函数。

三个次要但会救命的细节

• 并发但有序：「a single agent's detection wall is max(help, models, auth) ≈ 5s rather than the sum ≈ 15s」
• 每条适配器故障隔离：裸 Promise.all 会因一条拒绝而整体拒绝——一个坏掉的可执行文件不能清空整个选择器

鉴权：不猜

老做法是看 ~/.foo/ 目录在不在猜有没有登录，猜错的代价是把能用的 agent 标红。新规则：只有声明了 authProbe 的适配器才主动探测鉴权；没声明的 → authStatus 就是 unknown；真正的鉴权问题只从真实运行失败的错误文本里推断。探针必须是便宜、无副作用的 status/whoami 类命令。

探测的 UX

GET /api/agents?stream=1：每探完一条发一个 SSE 事件，设置面板不用等最慢的 CLI 就能开始画卡片。不做 24 小时缓存——用户刚 npm i -g 装完，刷新就该看见。

先算一笔账

stream-json 输入格式：为什么要保持 stdin 打开

When set to 'stream-json' the daemon writes a single JSONL line wrapping the prompt as an Anthropic user message (so tool_result blocks can later be injected into the same stdin without re-spawning the child). types.ts:125-130

Stdin remains open so the daemon can forward additional user messages mid-turn, then is closed after a clean terminal turn_end/usage rather than at a mid-tool tool_use pause.

cwd 就是项目工作区 + 一个看门狗

spawn(resolvedBin, args, { cwd: projectWorkspaceDir, env: spawnEnv })

cwd 是执行根，不是沙箱（第 16 步会再强调一次）。子进程的 Write/Edit 直接落在这里，你的文件工作区监听这个目录的变化。

子进程可能长时间不吐字节（比如 Copilot 生成 deck 时的思考阶段）。所以要有基于 stdout/stderr/SSE 活动的不活跃超时，全局默认 10 分钟，适配器可以用 inactivityTimeoutMs 声明更长上限，操作者可以用环境变量覆盖（env 优先）。注释点破了本质：「The watchdog observes child stdout/stderr/SSE activity, not real CPU progress」——你观测的是「有没有说话」，不是「有没有在干活」。

25 个 CLI 有 25 种 stdout？不。按 wire format 分类之后只有 7 种 streamFormat、4 类解析器。所有解析器输出同一套事件：thinking / tool-call / tool-result / text-delta / file-write / error / done。UI 只认这套，不认底层格式。

plain 流：最弱的适配器要写最多的代码

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

return /\s/.test(
  text.charAt(idx + '<artifact'.length));

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

不要只写文件。每个产物按扩展名生成一份旁挂清单，声明 kind / renderer / exports / entry。这份清单让下游知道用哪个渲染器、能导出成什么、哪个是入口文件。没有它，你的文件工作区只能靠扩展名猜。

不同 CLI 的能力差得很远：Claude Code 有完整的 Read/Write/Edit/Bash；DeepSeek TUI 在你选的调用模式下只会吐文本。你不能为每条适配器写一套交付逻辑。抽象成两档——一个 249 字节的文件：

export type ExecutionProfile = 'filesystem' | 'text_artifact';
export function executionProfileFromStreamFormat(streamFormat) {
  return streamFormat === 'plain' ? 'text_artifact' : 'filesystem';
}

flowchart TB
    RUN["一次生成"] --> P{"执行画像"}
    P -->|filesystem| F1["CLI 用原生工具直接写项目文件"]
    F1 --> F2["文件事件 → 文件工作区 → 预览"]
    F2 --> F3["助手以普通摘要收尾
❌ 禁止再输出 artifact 源码块"]
    P -->|text_artifact| T1["模型循环里没有任何文件工具"]
    T1 --> T2["唯一交付形态：一个完整 artifact 块"]
    T2 --> T3["run 结束后宿主扫 stdout 提取并落盘"]
    T3 --> F2
    

一个值得学的架构回归

早期版本在 daemon 里实现过一个「直连 Anthropic + 自己实现 Read/Write/Edit」的兜底循环。现在被彻底删掉了，换成把 BYOK 凭证翻译成 OpenCode 配置，让装好的 opencode 进程继续拥有模型/工具循环。

There is no daemon-owned fallback loop and no daemon implementation of Read/Write/Edit tools.

为什么值得学：那个兜底循环违背了「我们不实现 Agent 循环」这条根本主张。一旦你开了这个口子，它会慢慢长成第二个（更差的）Agent。删掉它是对的。

品牌不是一堆 CSS 变量，是一份可版本化的契约

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

关键约束：manifest.id 必须等于文件夹 slug 且用规范化 ASCII；文件名固定；每条声明的路径必须安全、相对、存在——这是 guard 检查的。

富文件是缓存，不是竞争的真理源

派生文件一致性由 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["⑧ 活跃技能/模板正文"]
    

默认使用契约值得原样抄：

Read DESIGN.md for visual principles, paste tokens.css verbatim into the first <style> when it is provided… Treat any pull-layer index as optional context for deeper inspection; do not assume those files have already been loaded.

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

三件刻意不做的事

质量门槛：约束密度，不约束形态

The package-quality guard requires at least seven substantive H2 headings, without prescribing their names, order, or numbering. Use headings that fit the actual system and keep their decisions synchronized with tokens.css.

上游用九段固定模板，OD 演进成「保留充实度门槛，去掉标题名的僵化」。这是内容契约设计的一个好范式。

用户没有品牌怎么办：品牌提取五步

1. 定位源：有附件就列出来；给了 URL 就 WebFetch <brand>.com/brand、/press、/about
2. 下载样式产物：CSS、品牌指南 PDF、截图
3. 提取真值：grep -E '#[0-9a-fA-F]{3,8}' 抓 CSS 里的 hex；截图靠视觉读排版。绝不凭记忆猜颜色
4. 编码成契约：写 brand-spec.md——六个 OKLch 色 token（--bg --surface --fg --muted --border --accent）+ display/body/mono 字体栈 + 3–5 条观察到的版式姿态（圆角、边框粗细、accent 预算）
5. 口头复述：一句话说清将用的系统（「深海军蓝产品画布，单一电光青 accent 在 oklch(68% 0.16 220)，几何 display + 系统 body」），让用户能廉价纠偏

你现在有三根轴：技能（干什么）、模板（做成什么形状）、设计系统（用什么品牌）。做出来的东西还是一眼假。为什么？

因为有一类知识不属于任何一个品牌，也不属于任何一个技能：ALL CAPS 永远需要 ≥0.06em 字距；var(--accent) 每屏最多出现 2 次；#6366f1 永远是 AI 默认色的破绽；display 字体和 body 字体不该是同一个家族。

这些是称职设计师的肌肉记忆。把它们写进 151 份 DESIGN.md？那是 151 份重复，而且改一次要改 151 处。所以拆出第四根轴。

按需订阅，不是全量注入

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

只有列出的段落进提示词。一个只排版的技能不用为色彩、动效内容付 token 成本。11 个已发布 slug：typography · typography-hierarchy · typography-hierarchy-editorial · color · anti-ai-slop · state-coverage · animation-discipline · accessibility-baseline · rtl-and-bidi · form-validation · laws-of-ux。

两级执法：诚实地标注哪些是真检查

而且在文档里逐条标注：凡是没接进 linter 的规则后面都跟着「(guidance, not auto-checked)」。

运行时宽容 vs 仓库严格

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

现在你有了引擎、有了品牌、有了工艺。用户输入「帮我们做个落地页」，模型开始想……然后 25 秒后吐出一整页 HTML，用米色背景、紫色渐变、三个 emoji 图标。用户关掉页面走了。

问题不在模型，在你没给它剧本。

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant H as 你的宿主
    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: 品牌提取五步
        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（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.

用户容忍不了 15 秒的沉默，但完全能接受 2 秒内弹出一张能一路点完的表单。而且必须堵死模型的借口：

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.

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

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

RULE 2：四步优先级的分支解析

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

分支 B 明确禁止二次问方向：「Do not emit any second direction-picking form… pick the best-matching direction yourself and bind it without asking.」这是一次产品决策的沉淀：早期版本会弹「五选一方向卡」，后来发现多一次点击就多一次流失。

RULE 3：九步计划 + 两道非协商闸门

1.  读活跃 DESIGN.md + 技能资源（template.html, layouts.md, checklist.md）
2.  绑定 token 到 :root
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.

实现上有三个分支（每个都是一次事故的化石）：deck 项目注入通用骨架；自由形态项目注入带条件前缀的骨架；有技能种子时不注入（种子自己有更有主张的框架，重复会冲突）。

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

到这一步，你的系统提示词已经有 20 层了。它们会互相打架。举三个真实的冲突：

三种压制手段

Ask mode is light, not amnesiac.

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

一个正在进行的重构：slim vs classic

两套装配路径并存：classic 分层堆叠（现役），slim 把三块塌缩成一份宪章文档（A/B 验证中）。注释写得很坦白：「the classic stack keeps the legacy layered composition until the A/B comparison signs off」。

你的系统提示词 30–80 KB。用户在一个项目里聊 20 轮。如果每轮都是全新的前缀，你烧掉的钱可以按数量级优化。LLM 的前缀缓存是前缀匹配的：只要前 N 个 token 一样就能命中。所以排序决定成本。

flowchart LR
    Z1["① 全局静态
设计师宪章 · 注入抵抗
【所有会话共享】"] --> Z2["② 会话稳定
模式覆盖 · locale
【一个会话内不变】"]
    Z2 --> Z3["③ 项目稳定
设计系统 · 技能 · 元数据
【一个项目内不变】"]
    Z3 --> Z4["④ 回合可变
deck/media/platform 信号触发块
【每回合可能翻转】"]
    

最精妙的一条：触发信号的稳定性决定块的位置

同一个内容块，根据它是被什么信号触发的，放在不同的带：

// 元数据信号（项目创建时固定）→ 放在项目稳定带
if (isSlimCore && metadataPlatformSignal) {
  parts.push(PLATFORM_CONTRACTS_BLOCK, '\n\n---\n\n');
}
// 对话文本信号（中途可能翻转）→ 推到回合可变后缀
else if (isSlimCore && (platformHintSignal ?? false)) {
  slimTurnVariableParts.push(`\n\n---\n\n${PLATFORM_CONTRACTS_BLOCK}`);
}

The conversation-text signal is turn-variable (a mid-session "make it an iOS app" flips it on), so signal-only triggers defer the block to the turn-variable suffix… an early insert would break the cached prefix for every section after this line.

同一个块，放错位置就毁掉后面所有段的缓存。

缓存命中归因：出问题时你要知道是哪一段

if (!isResuming)                 → missReason: 'new-session'
if (storedHash === currentHash)  → hit: true
if (storedHash === null)        → missReason: 'missing-stored-hash'
else                             → missReason: 'stable-prompt-changed'
                                   + changedSections: 逐段 diff

「这个页面一眼是 AI 做的」——听起来完全主观。但拆开看，其中相当大一部分是可枚举的具体模式：

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

// ❌ 天真实现，会漏一半
const m = /letter-spacing:\s*([\d.]+)em/.exec(body);
if (!m || parseFloat(m[1]) < 0.06) report();

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

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

假阳性比漏检更致命——报错报烦了没人看。三道防护：剥 HTML 注释（注释里常有教学示例）、剥 CSS 注释（/* ... */ 浏览器不渲染但正则会匹配）、区分 token 定义 vs 直接使用（把 indigo 定义成 token 是合法的）。

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.

每个阈值都应该能说出它是从哪个真实场景倒推的，否则半年后没人敢动它。

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

<artifact-lint>
2 P0（必须修）, 1 P1（应该修）, 0 P2（可以修）。
下一回合重发修正版 <artifact> —— 不要另写解释，用户手上已经有上一版了。

**[P0] ai-default-indigo** — Found #6366f1 used as a solid accent.
  Fix: Use var(--accent) from the active design system.
  Snippet: `background: #6366f1`
</artifact-lint>

三个要点：按严重度排序（P0 在前）、明确要求重发修正版（不要写解释）、每条都带 fix——只给 message 模型会去猜，猜错就多一轮。

正则能抓「用了 indigo」，抓不到「这个层次结构很混乱」。第二道闸门用模型评模型。

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

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.

收敛循环与五种结算状态

composite = designer×0.0 + critic×0.4 + brand×0.2 + a11y×0.2 + copy×0.2
threshold = 8.0 / 10       maxRounds = 3
perRoundTimeoutMs = 90_000   totalTimeoutMs = 240_000
fallbackPolicy = 'ship_best'   // 或 'ship_last' / 'fail'

五种结算状态：Shipped / Below threshold / Timed out / Interrupted / Degraded。

跨 25 条 CLI 的一致性纪律

你的评审协议要求 agent 吐 <CRITIQUE> 块。25 条 CLI 的模型不一样，遵守程度也不一样。所以要有降级机制（5 种原因，含 adapter_unsupported 的 24h TTL）和一致性门槛：

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 degraded for 24h.

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

还要可回放：每次 run 写一份结构化 .ndjson。评审是个多轮过程，用户看完了想再看一遍「它到底为什么给我 6.2 分」——没有回放，这个信息就丢了。

记忆的三条铁律

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

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

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

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

Plugins never own the atom implementations; they only reference them by id. 宿主负责把每个原子解析成：系统提示词片段 + 工具门控 + GenUI 面声明。

flowchart TB
    M["插件 manifest
od.pipeline.stages[*].atoms[]"] -->|①解析| PS["PipelineStage[]"]
    PS -->|②run 前| B["解析内置原子指令体
渲染成 ## Active stage 提示词块"]
    B --> R["③运行时逐阶段走"]
    R --> E1["发 pipeline_stage_started"]
    E1 --> W["④向 worker 注册表要
宿主可观测的信号"]
    W --> A["⑤往 run_devloop_iterations 写一行审计"]
    A --> E2["发 pipeline_stage_completed + 信号"]
    E2 --> R
    

until 词汇表必须是封闭的

原子的晋升路径

不要一上来就把新能力做成内置原子：① 先作为树外插件实现 → ② 形状稳定后加内置原子、往目录追加一行、有真实可观测信号时才注册 worker → ③ 同一个 PR 更新文档和 spec 表格 → ④ 通过 pipeline 引用 / API / CLI / doctor 触达。

放弃了执行层的闸门，就必须把预算全花在边界上。六条：

边界一：默认 loopback

daemon 默认绑 127.0.0.1；LAN 暴露需要同时设两个环境变量（缺一不可）；连接器凭证和预览路由无论如何都保持 loopback-only——即使公开部署也不放开。

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

你有一个 BYOK 代理，用户可以填任意 baseUrl。这是教科书级的 SSRF 面。默认封锁解析到私有/内部地址的 URL——RFC1918、link-local、CGNAT、云元数据 IP（169.254.169.254 那类，能偷 IAM 凭证）。

但真实用户确实有内网网关（VPN 里的 LiteLLM、Ollama），所以要有 opt-out，且必须严格：严格 opt-in（默认空）· 精确主机匹配（不做子域名/子串匹配）· 范围受限（只作用于你自己配的 provider 端点）· 不放宽下游（上游响应里返回的下载 URL 仍然被封）· 错误项丢弃（畸形条目和 CIDR 记法被丢弃并告警，不静默信任）。

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

用户要导入本机任意文件夹。这个能力很危险——渲染进程里的一段恶意脚本能不能构造一个请求，让 daemon 去读 /etc/？

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: 打上服务端控制的「可信选择器」标记
    Note over D: 之后每次文件访问都对该外部根做安全路径解析
    

边界四：预览必须是沙箱 iframe

沙箱 iframe，无宿主同源访问；每个面只 opt-in 它需要的特性；切换渲染模式时两个 frame 都保持挂载避免闪烁；消息处理器校验发送方 iframe；需要来自活跃 frame 的信号会再次核对活跃窗口——最后两条防的是：页面里有多个 iframe 时，一个后台 frame 冒充活跃 frame 发消息。

边界五：技能暂存必须是拷贝，不是软链

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

如果你必须支持一条只吃 argv 的 CLI，你需要三道守卫：

两个 Windows 守卫互斥。三者一起抓的是：原始字节数没超，但引号密集的提示词（代码块、JSON 形状的技能种子）展开后超过 CreateProcess 的 32 767 字符上限。三者发同一个可行动的错误：告诉用户「减少技能/设计系统上下文、缩短对话、或换一个支持 stdin 的适配器」。并且三者都有单测，「so the guards can't silently regress」。

三种运行形态，一套代码

Ports are transport details; they do not define process identity, namespaces, or daemon data roots.

打包桌面模式下 Electron 不假设端口——它通过 sidecar IPC 去问 web 的真实 URL。

数据根契约：一处值得抄的文档纪律

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

dual-track 规则：能力必须同时在 UI 和 CLI 出现

When adding a user-facing capability, close the loop in one change: contract type, daemon route, web surface if applicable, and CLI command with --json plus --prompt-file <path|-> for long prompts where relevant.

为什么强制？因为 CLI 是外部 agent 消费你的产品的方式。如果一个能力只有 UI 有，那么通过 MCP 接进来的 Claude Code 就用不了它——你的「可被任意 agent 消费」这个卖点就漏了一个洞。而且注意 --json：每个命令都要支持，这样才能 | jq | xargs 进自动化。

把自己做成 MCP 服务端

这是「agent 原生」这个定位的闭环：你不仅调用别人的 agent，还要被别人的 agent 调用。

od mcp install <agent>     # 一行装进 16+ 个 CLI 的配置
# 然后在那个 agent 里：
od project list --json
od files read <project-id> <relative-path>

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.

不做跨 agent 自动兜底

A crash, auth failure, timeout, or invalid invocation remains a failure for that run… the daemon does not silently move the request to another detected CLI.

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

导出矩阵与 mock agent

这一句话到底跑了什么

用户在 Home 打字：「帮我们做一个 SaaS 产品落地页，用我们公司的品牌。」然后选了设计系统 linear-app，点 Run。

sequenceDiagram
    autonumber
    participant U as 用户
    participant W as Web
    participant D as 宿主 Daemon
    participant C as claude 子进程
    participant F as 项目文件
    U->>W: 输入简报 + 选 linear-app + Run
    W->>D: POST /api/projects
    D->>D: 分配托管项目工作区（RUNTIME_DATA_DIR 派生）
    W->>D: POST /api/chat（SSE）
    Note over D: 【组装阶段】
    D->>D: 探测 agent（已 warm）→ claude 可用
    D->>D: 暂存活跃技能到 .od-skills/saas-landing-3f2a91b0c4/
    D->>D: 组装系统提示词（20+ 层，按变化频率分带）
    D->>D: 算 stablePromptHash → 新会话，miss
    Note over D: 【启动阶段】
    D->>D: resolveAgentLaunch → 拿到真实可执行路径
    D->>D: buildArgs → -p --input-format stream-json …
    D->>C: spawn(cwd=项目工作区)，提示词经 stdin，stdin 保持打开
    Note over C: 【第 1 回合 · RULE 1】
    C-->>D: "明白了 — SaaS 落地页，用 Linear 的设计语言。补几个信息："
    C-->>D: question-form（4 题，全部预填）
    D-->>W: SSE 事件流
    W->>U: 渲染问卷卡（没有方向/主题色题）
    U->>W: 直接提交（不改）
    W->>D: POST /api/chat（"[form answers — discovery] …"）
    D->>C: 同一 stdin 写入新的 user 消息（不重启进程）
    Note over C: 【第 2 回合 · RULE 2 分支 B】
    C-->>D: 有活跃设计系统 → 不再问方向，直接进 RULE 3
    Note over C: 【第 3 回合 · RULE 3】
    C-->>D: tool-call TodoWrite（9 步计划）
    C->>F: Read .od-skills/… 的 template.html / layouts.md / checklist.md
    C->>F: Write saas-landing.html（绑 linear-app 的 :root token）
    D-->>W: file-write 事件 → 文件工作区 → 沙箱 iframe 预览
    Note over D: 【闸门一】
    D->>D: lintArtifact() → 1 条 P1: accent-overuse（9 次）
    D->>C: artifact-lint 系统提醒（含 fix + snippet）
    C->>F: Edit（把 7 处降级成 var(--fg)）
    Note over C: 【自检】
    C-->>D: step7 checklist P0 全过
    C-->>D: step8 五维自评：具体性 2/5（填充文案）→ 返工
    C->>F: Edit（替换 [REPLACE] 为真实文案）→ 重评全部 ≥3/5
    Note over D: 【闸门二 · 若开启】
    D->>C: Design Jury round 1（同一会话的 5 个回合）
    D->>D: composite = 8.3 ≥ 8.0 → Shipped at round 1
    Note over C: 【交付 · filesystem 档】
    C-->>D: 普通摘要（❌ 不发 artifact 源码块）
    D-->>W: done
    W->>U: 预览 + 导出按钮
    U->>W: 导出 PDF
    

这条链路上，你写的代码在哪？

验收断言（做完每步怎么验）

点一下打勾，进度存在浏览器本地。全部通过 = 你有一个能跑的设计 Agent 宿主。

十二个最容易翻的车

点开看症状、根因、修法。每一条都是真实事故的化石。

源码对照索引

结语：这条路线适合谁

继续读