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

人工智能AI 应用桌面应用【免费下载链接】open-codesignOpen-source Claude Design alternative. One-click import your Claude Code / Codex API key. Prompt → prototype / slides / PDF. Multi-model (Claude, GPT, Gemini, Kimi, GLM, Ollama). BYOK, local-first, MIT.项目地址https://gitcode.com/gh_mirrors/op/open-codesign点击查看免费下载导读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识别过时的 CLAUDE/AGENTS 内容。围绕 v0.2 agentic workspace 决策重写AGENTS.md。校验过时引用与空白问题。这看似简单的三步背后对应着一次架构范式的切换。计划文档的 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.jsxindex.html保留给独立导出或旧版 workspace 文件。2. 硬约束项目承诺而非偏好AGENTS.md用九条硬约束划定了不可逾越的边界这些与 docs/v0.2-plan.md §1 的非目标清单一一对应不捆绑模型运行时不得在安装包里附带 Ollama、llama.cpp、Python、浏览器二进制或模型权重只能使用系统安装或用户可见同意的按需下载只做 BYOK无托管账户、无代理 API、默认无遥测用户凭据保存在人类可读的本地配置中本地优先存储v0.2 使用 pi JSONL session 真实 workspace 文件v0.1 SQLite 数据可以迁移但不得为 session、聊天历史、评论、快照或设计文件新增 SQLite 表每个 design 必有 workspacev0.2 没有 sealed/open 之分workspace 文件系统是 artifact 与资产的真相源MIT 兼容许可捆绑的应用/运行时依赖、内置资产、scaffolds、skills、品牌引用和复制的代码必须宽松许可拒绝 GPL/AGPL/SSPL/专有依赖仅用于 CI/发布的工具可例外但需记录理由重特性懒加载PPTX 导出、网页抓取、scaffolds、skills、品牌引用、图片生成都必须按需加载不能随应用启动一起加载优先复用 pi 原语pi-coding-agent拥有 session、内置工具、bash 执行、事件流、模型注册表、provider 注册和能力数据除非有 design-specific 需求能证明需要自建品牌值是数据而非模型记忆使用DESIGN.md、用户文件、官方 CSS/SVG/截图或品牌 URL禁止凭记忆发明品牌 hex 值PR 保持兼容、可升级、精简、优雅。其中第 8 条直接来自 v0.2-plan 的Brand Acquisition Protocol§5LLM 对品牌颜色的记忆错误率高即使 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 的ModelT字段input、reasoning、cost、contextWindow、maxTokens读取自定义 provider 通过pi.registerProvider()注册不建平行 provider SDK 层所有 LLM 调用走pi-ai应用代码不得直接导入 provider SDK。Storagedesign 等于 pi sessionsession 历史以 pi JSONL 形式存放在 app user data设计源文件、生成的 JSX/HTML/CSS、资产、导出物、AGENTS.md、DESIGN.md都放在用户 workspaceworkspace 设置放在.codesign/settings.json并带schemaVersionsettings.local.json属于个人偏好默认 gitignorev0.1 SQLite 是待迁移的遗留数据不是 v0.2 存储模型。Toolsv0.2 的工具面是 pi 的 7 个内置工具加上 Open CoDesign 设计工具。AGENTS.md列出的设计工具与 v0.2-plan §3 的清单一致ask(questions)渲染结构化问题并等待用户scaffold(kind, path)把精选 starter 复制进 workspaceskill(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 SystemDESIGN.md遵循 Google spec既是输入也是输出代理生成多屏作品时应随 token 涌现持续更新DESIGN.md保持视觉一致内置品牌引用必须带 attribution、来源、license 元数据和非附属声明内置 skills 使用 agentskills 风格SKILL.mdskill 与 scaffold manifest 应携带 license 和来源元数据。Resource BoundariesAGENTS.md对四类模板资源做了严格区分这是最容易让代理混淆的地方apps/desktop/resources/templates/skills/*.md 是方法规则告诉代理怎么工作不往 workspace 复制文件apps/desktop/resources/templates/brand-refs/*/DESIGN.md 是仅参考的设计系统通过skill(brand:slug)加载不得为某个项目直接编辑采用的选择应翻译进 workspaceDESIGN.mdapps/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 文档必须用.htmlJSX/React starter 用.jsxCSS 片段用.cssscaffold()复制时应保留源扩展名内置 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构建编排 Turborepolint/format 用 Biome单测 Vitest、E2E PlaywrightTypeScript 严格模式 verbatimModuleSyntax bundler resolution禁用any提交用 Conventional Commits版本管理用 Changesets不要手改CHANGELOG.mdNode 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/desktopElectron 壳、主进程、渲染进程、packages/core代理编排、prompts、设计工具、packages/providerspi 集成与 provider 兼容 shim、packages/runtime沙盒渲染与预览运行时、packages/ui共享 UI token 与组件、packages/artifactsartifact schema 与 bundle 格式、packages/exportersPDF/PPTX/ZIP 导出器懒加载、packages/templates内置示例与 starter 模板、packages/shared共享类型/工具/schema、docs/gitignored 的内部愿景/计划/原则/研究、examples/公开演示复现。四、权限模型单一模式 四层 TierAGENTS.md的 Permission Model 与 docs/v0.2-plan.md §6 完全一致采用单一权限模式 四层分级抄 Claude Code 的成熟做法Tier 0workspace 内读写、简单文件命令、只读 git无感放行、不弹窗Tier 1安装、构建命令、非本地网络抓取、cwd 外命令首次弹窗后可 allowlistTier 2发布、push、sudo 和高爆炸半径命令每次必弹窗、不可 suppressTier 3破坏性系统命令、curl | sh、系统目录写入硬拦截、无 override。弹窗 UX 是三按钮设计拒绝 / 允许 / 总是允许默认 scope 是 per-design 命令前缀如pnpm install *。Allowlist 存储分两级workspace 级.codesign/settings.jsonper-design、可 commit{ schemaVersion: 1, allowedTools: [ Bash(pnpm install *), Bash(pnpm run *), Bash(git status) ] }全局级~/.codesign/settings.json同格式。加载顺序global → project → localsettings.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.tsask工具只负责 wire 格式执行在渲染进程的AskModal /主进程 IPC 桥把代理的挂起 tool call 用用户答案或cancelled标记resolve。五种题型在 TypeBox schema 中逐一定义text-options≥2 个字符串选项可选multi、svg-options选项带id/label/svg、slidermin max且step 0default必须在区间内、file可选accept/multiple、freeform可选placeholder/multiline。单次最多 25 题question id 不可重复validateAskInput纯函数校验可被运行时与测试共用答案值超过 500 字符会被截断。返回{status: answered, answers}或{status: cancelled, answers: []}。packages/core/src/tools/preview.tspreview从done拆出让代理可以在不结束回合的情况下自检中间状态。它是能力驱动的输出——vision 模型返回截图data URL 或路径纯文本模型返回 DOM outline metrics console 错误。模块拥有线格式与预算上限console 错误 ≤50 条MAX_CONSOLE_ENTRIES 50、资产错误 ≤20 条MAX_ASSET_ERRORS 20trimPreviewResult负责裁剪。工具还支持最多 16 步的声明式交互步骤click/fill/select/press/assertMAX_PREVIEW_STEPS 16assert 必须提供visible/text/value之一每步 2 秒、全部 20 秒调用之间无状态保持可安全重复调用。packages/core/src/tools/done.tsdone是最终 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_ENTRYApp.jsx旧版回退到LEGACY_SOURCE_ENTRY。apps/desktop/src/main/migration/v01-to-v02.tsv0.1 → v0.2 迁移脚本按 v0.2-plan §11 的策略实现检测userData/designs.db对designs表每行在defaultWorkspaceRoot/slug/物化 workspace 并写入design_files把chat_messages翻译成 SessionManager 管理的 JSONLappendUserMessage/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 应用桌面应用【免费下载链接】open-codesignOpen-source Claude Design alternative. One-click import your Claude Code / Codex API key. Prompt → prototype / slides / PDF. Multi-model (Claude, GPT, Gemini, Kimi, GLM, Ollama). BYOK, local-first, MIT.项目地址https://gitcode.com/gh_mirrors/op/open-codesign点击查看免费下载相关推荐RealSense SDKlibrealsense实战让深度相机从装好到跑通项目的完整指南RealSense SDKlibrealsense实战让深度相机从装好到跑通项目的完整指南 librealsense 是 Intel RealSense智能硬件音视频计算机视觉Open CoDesign 开发指南AGENTS.md 驱动的桌面设计 Agent 架构、工具面与工程约束解读Open CoDesign 开发指南AGENTS.md 驱动的桌面设计 Agent 架构、工具面与工程约束解读 导读 本文以 Open CoDesign 仓库人工智能AI 应用桌面应用特斯拉数据记录工具 TeslaMate:三步切换界面语言、贡献翻译的完整指南特斯拉数据记录工具 TeslaMate:三步切换界面语言、贡献翻译的完整指南 TeslaMate 是一款自托管的特斯拉数据记录工具,帮你把车辆的充电、行驶、里程后端数据分析数据可视化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考