Open CoDesign AGENTS.md v2 更新计划：如何让 Codex 代理跟随 v0.2 本地设计代理架构

• 人工智能
• AI 应用
• 桌面应用

导读

AGENTS.md是 Codex 等 AI 编程代理在本仓库工作的入口文件。随着项目从 v0.1 的"prompt 生成 artifact"应用演进到 v0.2 的"长期运行的本地设计代理"架构，仓库维护者需要把这份代理指令从过时的CLAUDE.md拷贝中解放出来，让它对齐最新的docs/v0.2-plan.md。本文基于 .Codex/workspace/agents_md_v2_update_plan.md 这份更新计划，完整还原其目标、步骤、发现与验证方法，并结合 AGENTS.md、docs/v0.2-plan.md 及仓库源码，展开讲解 v0.2 的存储模型、工具面、权限模型、设计系统与资源边界等核心决策，帮助你理解"代理指令文档如何与架构演进同步"这一工程实践。

一、这份更新计划在解决什么问题

.Codex/workspace/agents_md_v2_update_plan.md是一份内部工作计划的执行记录，核心目标只有一句话：让 Codex 代理遵循最新的 v0.2 计划，而不是过时的CLAUDE.md拷贝。

计划列出了三个步骤，均标记为 complete：

1. 识别过时的 CLAUDE/AGENTS 内容。
2. 围绕 v0.2 agentic workspace 决策重写AGENTS.md。
3. 校验过时引用与空白问题。

这看似简单的三步，背后对应着一次架构范式的切换。计划文档的 Findings 部分指出，更新前CLAUDE.md和当时的AGENTS.md存在五类过时信息：

• 仍把 Open CoDesign 描述成"prompt-to-artifact 应用"，而不是本地设计代理（local design agent）；
• 仍把设计历史指向 SQLite，而 v0.2 把 session 迁移到 pi JSONL、把文件迁移到真实 workspace；
• 仍说 pi-ai 的缺口应扩展为packages/providers扩展，但 pi spike 的结论是 provider/session/capability/bash 应交给 pi-coding-agent 处理；
• 硬编码了部分技术栈版本号，更新后的AGENTS.md应指示代理直接阅读 manifest 获取精确版本；
• 缺少最新计划的核心表述：design 即 pi session、每个 design 必有 workspace、v0.2 无 sealed/open 模式、无 project 抽象。

这些差异的根源在于：CLAUDE.md反映的是旧版产品形态，而docs/v0.2-plan.md（见 docs/v0.2-plan.md）才是 v0.2 的真实实施参考。更新计划还记录了验证手段：用rg -e精确搜索确认没有better-sqlite3、旧 provider-extension 指引、硬编码 React/Vite 版本、旧存储措辞等残留；用git diff --no-index --check /dev/null AGENTS.md确认没有空白告警；并记录了第一次搜索因 shell 反引号未转义触发命令替换的教训（改用rg -e模式、去掉反引号）。

二、更新后的 AGENTS.md 核心内容：v0.2 的架构共识

重写后的 AGENTS.md 是这份更新计划的直接产物，也是 Codex 代理工作的"公共真相源"（public source of truth）。它明确声明：CLAUDE.md可能落后于当前计划；docs/目录被 gitignore，维护者本地可能有内部计划，公共贡献者可能没有，因此不要在没有该文件时阻塞公共贡献工作。

1. 产品定位：从生成器到代理

更新后的定位是：Open CoDesign 是一个开源的桌面设计代理——把 prompt、本地文件、skills、scaffolds、品牌系统和模型输出转化为用户笔记本上的设计 artifact。v0.2 方向不再是单次 prompt 生成器：每个 design 都是一个长期运行的 pi session，拥有真实 workspace，代理可以读写文件、执行带权限的命令、提出结构化问题、预览 artifact、暴露 tweak 控件、在模型支持时生成图片，并产出DESIGN.md设计系统 artifact。

产品模型上，Design 拥有 workspace：代理在 workspace 中编辑设计源文件，preview 运行时把源文件渲染成网页文档，exporters 把渲染结果导出为 HTML、PDF、PPTX、ZIP 或 Markdown。v0.2 的默认源入口是App.jsx，index.html保留给独立导出或旧版 workspace 文件。

2. 硬约束：项目承诺而非偏好

AGENTS.md用九条"硬约束"划定了不可逾越的边界，这些与 docs/v0.2-plan.md §1 的"非目标"清单一一对应：

1. 不捆绑模型运行时：不得在安装包里附带 Ollama、llama.cpp、Python、浏览器二进制或模型权重，只能使用系统安装或用户可见同意的按需下载；
2. 只做 BYOK：无托管账户、无代理 API、默认无遥测，用户凭据保存在人类可读的本地配置中；
3. 本地优先存储：v0.2 使用 pi JSONL session + 真实 workspace 文件；v0.1 SQLite 数据可以迁移，但不得为 session、聊天历史、评论、快照或设计文件新增 SQLite 表；
4. 每个 design 必有 workspace：v0.2 没有 sealed/open 之分，workspace 文件系统是 artifact 与资产的真相源；
5. MIT 兼容许可：捆绑的应用/运行时依赖、内置资产、scaffolds、skills、品牌引用和复制的代码必须宽松许可，拒绝 GPL/AGPL/SSPL/专有依赖；仅用于 CI/发布的工具可例外，但需记录理由；
6. 重特性懒加载：PPTX 导出、网页抓取、scaffolds、skills、品牌引用、图片生成都必须按需加载，不能随应用启动一起加载；
7. 优先复用 pi 原语：pi-coding-agent拥有 session、内置工具、bash 执行、事件流、模型注册表、provider 注册和能力数据，除非有 design-specific 需求能证明需要自建；
8. 品牌值是数据而非模型记忆：使用DESIGN.md、用户文件、官方 CSS/SVG/截图或品牌 URL，禁止凭记忆发明品牌 hex 值；
9. PR 保持兼容、可升级、精简、优雅。

其中第 8 条直接来自 v0.2-plan 的Brand Acquisition Protocol（§5）：LLM 对品牌颜色的"记忆"错误率高，即使 Linear、Stripe 这类知名品牌也有偏差，凭记忆生成的产物会"形似而神离"，因此强制走 acquisition protocol——询问用户品牌指南、curl/brand或/press路由、下载 SVG/HTML/截图、程序化从 CSS/SVG 提取 hex、最终以 YAML token 块写入DESIGN.md，素材不可用时必须询问用户而不是猜测。

3. 当前架构方向

AGENTS.md把 v0.2 架构方向浓缩成五个层面，与 v0.2-plan 的详细设计互为表里：

Agent Runtime：使用pi-coding-agent和pi-ai；直接用 pi 内置的read/write/edit/bash/grep/find/ls；工具通过 pi 的tool_callhook 和 Open CoDesign 权限 UI 把关；能力从 pi 的Model<T>字段（input、reasoning、cost、contextWindow、maxTokens）读取；自定义 provider 通过pi.registerProvider()注册，不建平行 provider SDK 层；所有 LLM 调用走pi-ai，应用代码不得直接导入 provider SDK。

Storage：design 等于 pi session；session 历史以 pi JSONL 形式存放在 app user data；设计源文件、生成的 JSX/HTML/CSS、资产、导出物、AGENTS.md、DESIGN.md都放在用户 workspace；workspace 设置放在.codesign/settings.json并带schemaVersion；settings.local.json属于个人偏好，默认 gitignore；v0.1 SQLite 是待迁移的遗留数据，不是 v0.2 存储模型。

Tools：v0.2 的工具面是 pi 的 7 个内置工具加上 Open CoDesign 设计工具。AGENTS.md列出的设计工具与 v0.2-plan §3 的清单一致：

• ask(questions)：渲染结构化问题并等待用户；
• scaffold(kind, path)：把精选 starter 复制进 workspace；
• skill(name)：从 manifest 懒加载技能文本；
• preview(path)：渲染 artifact，返回控制台错误、资产错误、DOM outline、指标和（vision 模型）截图；
• gen_image(prompt, path)：在能力与 provider 配置允许时把生成图片写入磁盘；
• tweaks(blocks)：跨文件声明可编辑控件；
• todos(items)：复杂回合展示任务状态；
• done(path)：preview 自检后结束回合。

同时明确不要在 v0.2 重新引入 verifier subagent、snip 工具、自定义 bash 工具、自定义 list-files 工具或代理编写的 working memory，除非计划改变。

Design System：DESIGN.md遵循 Google spec，既是输入也是输出；代理生成多屏作品时应随 token 涌现持续更新DESIGN.md保持视觉一致；内置品牌引用必须带 attribution、来源、license 元数据和"非附属"声明；内置 skills 使用 agentskills 风格SKILL.md；skill 与 scaffold manifest 应携带 license 和来源元数据。

Resource Boundaries：AGENTS.md对四类模板资源做了严格区分，这是最容易让代理混淆的地方：

• apps/desktop/resources/templates/skills/*.md 是方法规则，告诉代理怎么工作，不往 workspace 复制文件；
• apps/desktop/resources/templates/brand-refs/*/DESIGN.md 是仅参考的设计系统，通过skill("brand:<slug>")加载，不得为某个项目直接编辑，采用的选择应翻译进 workspaceDESIGN.md；
• apps/desktop/resources/templates/scaffolds/** 是scaffold(kind, destPath)复制的具体 starter/源资产，可以是 JSX、HTML、CSS、Markdown 等文本格式；
• apps/desktop/resources/templates/design-skills/*.jsx 是可复制的 JSX 组件模式片段，通过虚拟文件系统暴露为skills/<file>.jsx，是源码片段而非 markdown skill、也非品牌权威；
• workspace 根部的DESIGN.md是项目级设计系统接力棒（baton），一旦存在即对当前设计具有权威性，生成工作应维护或修复它，而不是把它当作又一个预设。

4. 内置 starter 与 scaffold 的维护纪律

AGENTS.md专门用一节强调 starter/scaffold 资产是产品代码而不是 prompt 填充物：改动或新增预设前要审查实际文件内容与 manifest；保持源格式与扩展名对齐——完整 HTML 文档必须用.html，JSX/React starter 用.jsx，CSS 片段用.css，scaffold()复制时应保留源扩展名；内置 HTML starter 应自包含且能在当前运行时预览，不得给 scaffold 资产添加 Reveal.js、React、Babel、Chart.js 等 CDN/运行时脚本；避免 "Deck title"、"Page content"、"Replace this" 这类弱占位文案，使用中性可用的示例内容，并在 JSX starter 中通过TWEAK_DEFAULTS暴露明显的替换点；manifest 描述应说明 starter 是 HTML 还是 CSS，并特别提示扩展名敏感的资产（防止代理把文件错误复制成_starters/*.jsx）；触碰 scaffolds 目录时要审计扩展名/内容不匹配、外部网络 URL、过期占位文案和 manifest 漂移，并补充相应测试。

这一节可以在源码里找到印证：packages/core/src/tools/scaffold.ts 定义了ScaffoldManifestEntry（含description、path、category、aliases、license、source、sizeBytes）和带schemaVersion的ScaffoldManifest，所有文件系统路径都来自getScaffoldsRoot()，不做包相对路径解析，保证 electron-vite 打包后工具仍可用、测试可用临时目录隔离。

三、技术栈约定与仓库布局

更新计划强调"精确版本请读 manifest 而非信任过时文档"，AGENTS.md的 Stack and Conventions 一节落地了这条原则：

• 包管理器只用pnpm，禁止 npm/yarn；
• 构建编排 Turborepo；lint/format 用 Biome；单测 Vitest、E2E Playwright；
• TypeScript 严格模式 +verbatimModuleSyntax+ bundler resolution，禁用any；
• 提交用 Conventional Commits；版本管理用 Changesets，不要手改CHANGELOG.md；
• Node 22 LTS，由.nvmrc和engines钉住；
• 精确包版本以package.json、workspace manifest 和pnpm-lock.yaml为准。

前端约定同样明确：React + Vite + Tailwind v4 + CSS 变量；状态用 Zustand（禁 Redux/Recoil/MobX）；组件用 Radix 原语和packages/ui里的 shadcn 风格封装；图标用lucide-react；表单用原生<form>和FormData；动画用 Tailwind 过渡（禁 framer-motion/motion）；应用 chrome 必须用packages/uitoken，生成的 design 源与导出物可以自建视觉系统；沙盒预览保持 Electron iframesrcdoc+ 运行时工具，App.jsx由运行时包裹用于预览/导出，导出的index.html是独立交付物。

仓库布局在AGENTS.md中以树状呈现：apps/desktop（Electron 壳、主进程、渲染进程）、packages/core（代理编排、prompts、设计工具）、packages/providers（pi 集成与 provider 兼容 shim）、packages/runtime（沙盒渲染与预览运行时）、packages/ui（共享 UI token 与组件）、packages/artifacts（artifact schema 与 bundle 格式）、packages/exporters（PDF/PPTX/ZIP 导出器，懒加载）、packages/templates（内置示例与 starter 模板）、packages/shared（共享类型/工具/schema）、docs/（gitignored 的内部愿景/计划/原则/研究）、examples/（公开演示复现）。

四、权限模型：单一模式 + 四层 Tier

AGENTS.md的 Permission Model 与 docs/v0.2-plan.md §6 完全一致，采用单一权限模式 + 四层分级（抄 Claude Code 的成熟做法）：

• Tier 0：workspace 内读写、简单文件命令、只读 git，无感放行、不弹窗；
• Tier 1：安装、构建命令、非本地网络抓取、cwd 外命令，首次弹窗后可 allowlist；
• Tier 2：发布、push、sudo 和高爆炸半径命令，每次必弹窗、不可 suppress；
• Tier 3：破坏性系统命令、curl | sh、系统目录写入，硬拦截、无 override。

弹窗 UX 是三按钮设计（拒绝 / 允许 / 总是允许），默认 scope 是 per-design + 命令前缀（如pnpm install *）。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）。AGENTS.md特别强调：不要隐藏被拦截的工具调用，要展示命令、路径、tier 和原因。

bash 权限拦截的实现方式在 v0.2-plan §3 有 spike 验证的代码骨架——通过 pi 的tool_callhook 异步 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 远程执行不必换工具。这一"只写 hook 不写新 bash 工具"的决策正是更新计划 Findings 中"provider/session/capability/bash 交给 pi-coding-agent"的落地。

五、工具实现与源码印证

v0.2 的工具清单从最初设想的 55 个（Claude Design 规模）精简到12 个（pi 7 内置 + 我们 5 个新增/改造），spike 后进一步砍掉自写 bash 和 list-files。更新后的AGENTS.md只保留 8 个 Open CoDesign 侧工具。仓库源码已经能印证其中几个工具的真实实现细节：

packages/core/src/tools/ask.ts：ask工具只负责 wire 格式，执行在渲染进程的<AskModal />，主进程 IPC 桥把代理的挂起 tool call 用用户答案（或cancelled标记）resolve。五种题型在 TypeBox schema 中逐一定义：text-options（≥2 个字符串选项，可选multi）、svg-options（选项带id/label/svg）、slider（min < max且step > 0，default必须在区间内）、file（可选accept/multiple）、freeform（可选placeholder/multiline）。单次最多 25 题，question id 不可重复，validateAskInput纯函数校验可被运行时与测试共用；答案值超过 500 字符会被截断。返回{status: 'answered', answers}或{status: 'cancelled', answers: []}。

packages/core/src/tools/preview.ts：preview从done拆出，让代理可以在不结束回合的情况下自检中间状态。它是能力驱动的输出——vision 模型返回截图（data URL 或路径），纯文本模型返回 DOM outline + metrics + console 错误。模块拥有线格式与预算上限：console 错误 ≤50 条（MAX_CONSOLE_ENTRIES = 50）、资产错误 ≤20 条（MAX_ASSET_ERRORS = 20）；trimPreviewResult负责裁剪。工具还支持最多 16 步的声明式交互步骤（click/fill/select/press/assert，MAX_PREVIEW_STEPS = 16），assert 必须提供visible/text/value之一，每步 2 秒、全部 20 秒，调用之间无状态保持，可安全重复调用。

packages/core/src/tools/done.ts：done是最终 gate 与 repair loop 的入口，两层结构：第一层对App.jsx（或旧版index.html）做静态 lint，检查未闭合标签、重复 id、缺失 alt text，廉价且不依赖宿主；第二层是宿主注入的运行时 verifier——桌面应用传入回调，在隐藏 Electron BrowserWindow 中加载 artifact，捕获约 3 秒的console-message与did-fail-load，返回收集的错误；没有该回调时（如 vitest 环境）跳过第二步，只报静态问题。结果形如{ status: 'ok' | 'has_errors', errors: [...] }，代理用str_replace_based_edit_tool自愈后再次调用done。默认检查路径是DEFAULT_SOURCE_ENTRY（App.jsx），旧版回退到LEGACY_SOURCE_ENTRY。

apps/desktop/src/main/migration/v01-to-v02.ts：v0.1 → v0.2 迁移脚本按 v0.2-plan §11 的策略实现：检测<userData>/designs.db；对designs表每行在<defaultWorkspaceRoot>/<slug>/物化 workspace 并写入design_files；把chat_messages翻译成 SessionManager 管理的 JSONL（appendUserMessage/appendAssistantMessage）；把comments翻译成带 anchor 的 user message 条目；最后把源 DB 重命名为designs.db.v0.1.backup防止下次启动重复弹窗。脚本是防御性的——单个 design 失败只记日志、循环继续，用户可稍后手动重试。

值得一提的版本事实：当前 packages/core/package.json 中@mariozechner/pi-ai与@mariozechner/pi-coding-agent均已钉到^0.72.1，高于 v0.2-plan §10 记录的 spike 期建议 pin^0.69.0（当时 pnpm 默认会装 0.67.x），说明依赖已随版本演进更新，而"读 manifest 而不是信任旧文档"的原则仍然成立。

六、版本与验证纪律

更新计划把"版本号不再写死"作为重要发现：AGENTS.md明确要求代理在需要精确版本时去读package.json、workspace manifests 和pnpm-lock.yaml，而不是相信可能过时的文档。这一点对任何代理驱动型仓库都适用——文档是方向，manifest 才是事实。

计划中的验证方法同样值得复用：用rg -e精确搜索过时短语（注意转义，避免反引号触发 shell 命令替换）；用git diff --no-index --check /dev/null AGENTS.md做空白检查。这类"搜索 + diff"的组合是代理指令文档维护的最小闭环。

仓库的日常命令（AGENTS.mdUseful Commands 一节）保持不变：pnpm i、pnpm dev、pnpm test、pnpm test:e2e、pnpm lint、pnpm typecheck、pnpm build、pnpm changeset。

七、Things to Avoid：防止代理误入歧途

AGENTS.md以负面清单收尾，是 v0.2 决策的浓缩：

• 不向 git 提交node_modules、构建产物、.env*、发布 artifact 或私有本地文件；
• 不在应用代码导入@anthropic-ai/sdk、openai、@google/genai等 provider SDK；
• 不在 SDK 层 mock LLM，测试应在 core 或 pi 边界 mock；
• 不添加 tracking、analytics、账户流程、云同步或未经显式 opt-in 的自动更新；
• 不硬编码用户路径，尊重 XDG、Electronapp.getPath()与 workspace 根；
• 不为 v0.2 session/design 数据新增 SQLite 特性状态；
• 不引入project作为 v0.2 产品抽象——多个 session 可共享一个 workspace，但侧栏列的是 session；
• 不暴露 session 分支 UI、undo/版本回滚、MCP 支持或社区 skill 安装（除非计划改变）；
• 不在 apps/desktop/src/main、packages/core、packages/providers、packages/exporters、packages/shared使用console.*，改用项目 logger。

这些"避免事项"与 v0.2-plan §1 的非目标清单（无 video/3D/logo 系统、无 bundle model runtime、无云同步/遥测/账户、无多人协作、无 MCP、无社区 skill 安装、无 session 分支 UI、无消息队列、无 undo、无 verifier subagent、无 working memory、无 snip、无 per-design meta.json、无 sealed/open 模式、无权限 mode toggle）一一呼应，构成代理行为的完整边界。

结语

agents_md_v2_update_plan.md这份计划虽小，却完整演示了代理指令文档与架构演进同步的工程闭环：识别过时内容 → 以最新计划为骨架重写 → 用精确搜索与 diff 校验。重写后的AGENTS.md把 v0.2 的九条硬约束、存储模型（JSONL + workspace）、12 工具面、四层权限、资源边界与负面清单固化成了 Codex 代理可执行的公共真相源。对于任何维护代理驱动型仓库的团队，这份计划与其产物（AGENTS.md）都是一份可复用的范本：文档给方向，manifest 给事实，测试与搜索给验证。

• 人工智能
• AI 应用
• 桌面应用