Open Design 仓库级 Agent 协作规范以 AGENTS.md 为单一事实来源的工程治理指南【免费下载链接】open-design Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. ️ Local-first desktop app. ️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images video — real files, HTML/PDF/PPTX/MP4 export. Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode 20 CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-designOpen Design 是一个 local-first 的设计产品仓库Web 运行时 本地守护进程 Electron 壳层 打包运行时 独立分发内容的五层应用架构。仓库根目录的AGENTS.md是该仓库的单一事实来源single source of truth任何 Agent 进入仓库都应先读它再按层级进入apps/、packages/、tools/、e2e/读取各层的AGENTS.md。本文以该文档为骨架结合仓库源码与配置文件系统讲解仓库拓扑、开发工作流、数据目录契约、发布渠道模型、UI/CLI 双轨能力暴露、Agent 运行时约定与验证策略帮助你快速、正确地在这类大型多包仓库中开展工作而不破坏边界约束。单一事实来源原则根 AGENTS.md 的角色与层级根AGENTS.md开篇即声明自己是agents entering this repository的单一事实来源并规定了两条核心纪律先读根文档再读层级文档进入apps/、packages/、tools/或e2e/后必须读取对应目录的AGENTS.md如 apps/AGENTS.md、packages/AGENTS.md、tools/AGENTS.md、e2e/AGENTS.md获取模块级细节。不反向拷贝不要把模块级细节抄回根文档根文档只聚焦跨仓库边界、工作流与命令。这样做避免了多份文档各自维护同一规则导致的漂移。文档还给出了核心文档索引相当于 Agent 的知识地图产品与上手README.md、QUICKSTART.md架构与协议docs/architecture.md、docs/skills-protocol.md、docs/agent-adapters.md、docs/modes.md已归档历史基线docs/spec.md、docs/roadmap.md明确标注 archived其过期决策不得当作当前行为当前计划与参考docs/references.md、docs/code-review-guidelines.md、specs/current/maintainability-roadmap.md打包更新架构与本地 harnesstools/pack/AGENTS.md提示词组合双实现docs/prompt-composition.md。仓库拓扑工作区目录、内容目录与失效目录工作区包结构包来源由 pnpm-workspace.yaml 定义apps/*、packages/*、shells/*、tools/*与e2e全部是 workspace 包。各层职责划分清晰apps/web是 Next.js 16 App Router React 18 的 Web 运行时文档明确不要恢复apps/nextjsapps/daemon是本地特权守护进程与od二进制所在层拥有/api/*、Agent 派生、skills、设计系统、artifacts 与静态服务apps/desktop是 Electron 壳层通过 sidecar client 边界消费 web/daemon 状态apps/packaged是薄打包运行时入口只启动打包 sidecar 并持有od://入口胶水apps/closure拥有独立分发的 OpenDesign Closure 内容packages/contracts是纯 TypeScript 的 web/daemon 应用契约层packages/sidecar-proto拥有业务 DTO 与 action 名packages/sidecar拥有完整的与业务无关的 sidecar client 边界与协议实现packages/platform提供通用 OS 进程原语packages/standalone拥有壳层无关的元数据、校验、物化、生成与启动器契约shells/terminal是官方 Node 载体与面向终端的生命周期命令tools/dev是本地开发生命周期控制平面tools/pack是打包构建控制平面tools/serve是 fixture 服务控制平面tools/release拥有发布元数据与通知数据契约。顶层内容目录skills/Agent 任务中调用的功能性技能见 skills/AGENTS.mddesign-templates/渲染目录deck、原型、图像/视频/音频模板design-systems/品牌DESIGN.md文件craft/与品牌无关的通用工艺规则技能可通过od.craft.requires选择加入mocks/基于匿名 Langfuse 轨迹构建的回放式 mock CLIopencode/claude/codex/gemini/cursor-agent/deepseek/qwen/grok、ACP 家族与 AMRvela通过 PATH-overlay 作为测试与自校验的即插即用替身见 mocks/README.md。失效目录apps/nextjs、packages/shared、apps/landing-page已被移除不得重建或引用本地运行时数据、.tmp/、Playwright 报告与 Agent 草稿目录必须留在 git 之外。开发环境基线与环境准备根文档对运行环境给出了硬性约束Node~24package.json#engines指定node: ~24pnpm10.33.2使用 Corepack 选择 package.json 中钉定的 pnpm 版本。Node 22 不被支持见根文档 FAQ。项目自有的入口点、模块、脚本、测试、reporter 与配置默认使用 TypeScript残余 JavaScript 仅限生成产物、vendored 依赖、明确记录的兼容构建产物以及 scripts/guard.ts 中的白名单。Windows native 注意事项macOS、Linux 与 WSL2 是主支持路径Windows native 是 best-effort。文档特别提醒了几个已知摩擦点历史记录见 closed issues #10/#96/#100/#203/#315安装 Node 24winget install OpenJS.NodeJS.LTSWinGet LTS 指针会在 2026 年 10 月滚动到下一 major重跑安装命令前需重新验证node --versioncorepack enable在 Windows 上会因无法向Program Files写 shim 而 EPERM 失败改用npm install -g pnpm10.33.2better-sqlite311.10.0没有 win32/Node 24 预编译二进制pnpm install会经 node-gyp 从源码编译约 2 分钟需要 Visual Studio Build Tools 2022 或更新——这是预期行为而非版本不兼容。本地生命周期pnpm tools-dev 是唯一入口根文档规定pnpm tools-dev是唯一的本地开发生命周期入口并且明确禁止添加或恢复根级生命周期别名pnpm dev、pnpm dev:all、pnpm daemon、pnpm preview、pnpm start。FAQ 解释了原因避免 daemon/web/desktop 通过不一致的 env、端口、namespace 或日志路径启动。关键细节端口由tools-dev的--daemon-port与--web-port标志管理见 tools/dev/src/cli-args.ts 中OPTIONS_WITH_VALUE集合两者都在其中tools-dev导出OD_PORTweb 代理目标与OD_WEB_PORTweb 监听器不要使用NEXT_PORTtools-dev消费 sidecar 的启动/发现/生命周期原子操作只拥有开发者编排策略。常用命令直接来自根文档的 Common commands 区块均为可复制执行pnpm install pnpm tools-dev pnpm tools-serve start updater pnpm tools-dev start web pnpm tools-dev run web --daemon-port 17456 --web-port 17573 pnpm tools-dev status --json pnpm tools-dev logs --json pnpm tools-dev inspect desktop status --json pnpm tools-dev inspect desktop screenshot --path /tmp/open-design.png pnpm tools-dev stop pnpm tools-dev checkpnpm guard pnpm typecheck包级命令必须 package-scopedpnpm --filter package ...或 tool-scopedpnpm tools-pack ...根级不允许添加聚合的pnpm build/pnpm test别名pnpm --filter open-design/web typecheck pnpm --filter open-design/web test pnpm --filter open-design/web build pnpm --filter open-design/daemon test pnpm --filter open-design/daemon build pnpm --filter open-design/desktop build pnpm --filter open-design/tools-dev build pnpm --filter open-design/tools-pack build pnpm --filter open-design/tools-serve build打包构建与安装mac / Windows / Linuxpnpm tools-pack mac build --to all pnpm tools-pack mac install pnpm tools-pack mac cleanup pnpm tools-pack win build --to nsis pnpm tools-pack win install pnpm tools-pack win cleanup pnpm tools-pack linux build --to appimage pnpm tools-pack linux install pnpm tools-pack linux build --containerizedDaemon 数据目录契约唯一权威的数据路径规则这是根文档中最重要的基础设施章节之一也是唯一事实来源原则最严格的落点所有 daemon 管理的数据路径规则只能以本仓库根AGENTS.md为准各 README、部署笔记与交接文档不得自行重述或发明新的路径约定。解析链与唯一真源daemon 启动时apps/daemon/src/server.ts 把OD_DATA_DIR解析为RUNTIME_DATA_DIR源码第 1342 行const RUNTIME_DATA_DIR resolveDataDir(process.env.OD_DATA_DIR, PROJECT_ROOT, {...})所有 daemon 数据路径必须从RUNTIME_DATA_DIR或由其派生的常量如PROJECTS_DIR、ARTIFACTS_DIR推导。从源码可见ARTIFACTS_DIR、PROJECTS_DIR、USER_SKILLS_DIR、USER_DESIGN_SYSTEMS_DIR、BRANDS_DIR、LIBRARY_DIR等都通过path.join(RUNTIME_DATA_DIR, ...)派生同文件 1375-1419 行resolveDataDir的实现位于 apps/daemon/src/daemon-paths.ts未设置OD_DATA_DIR时回退到projectRoot/.od设置时先做项目相对路径解析然后mkdirSync递归创建并fs.accessSync校验可写性不可写时抛出包含当前用户、父目录与ls -ld排查建议的明确错误。当OD_SANDBOX_MODE启用时requireExplicit会强制要求显式提供OD_DATA_DIR否则直接抛错Agent 子进程接收解析后的数据根作为OD_DATA_DIRserver.ts 在派生进程时注入OD_DATA_DIR: RUNTIME_DATA_DIR它们必须继承 daemon 的真源而不是自行猜测数据路径。被划为 daemon 数据、必须留在解析后的数据根下的内容涵盖ARTIFACTS_DIR、SQLite、应用配置、memory、MCP 配置/token、自动化状态、插件状态、连接器凭据、生成文件、sandbox 模式日志与 Agent 运行时 home。开发态与打包态的传播开发态tools-dev --namespace name本身不定义daemon 数据隔离需要隔离数据根时必须把OD_DATA_DIR传入 daemon 进程环境之后 daemon 一次性解析所有数据路径从RUNTIME_DATA_DIR流出。打包态tools-pack/apps/packaged拥有打包渠道与 namespace 布局打包代码在 spawn daemon之前解析最终 namespace 作用域的数据根daemon 接收该最终根作为OD_DATA_DIR且不得从应用名、ElectronuserData、端口、渠道名或 namespace 名推断打包数据路径。受制裁的例外与禁止复用的逃逸模式例外每个都是狭窄的、非数据根的用途OD_MEDIA_CONFIG_DIR仅覆盖media-config.json不是第二个 daemon 数据根OD_LEGACY_DATA_DIR仅作为旧数据导入的迁移来源外部工具 home如CODEX_HOME是集成输入不是 daemon 数据根Agent/项目 cwd 的技能暂存别名、manifest 元数据键与 CSS 标识符都是语义命名空间不是文件系统路径约定。明确禁止复用的逃逸候选指向 cwd 相对旧数据目录的模块级默认值、重新从process.env.OD_DATA_DIR或 cwd 回退计算数据根的 helper 默认值如defaultRegistryRoots()、依赖 fallback 的openDatabase(projectRoot)调用、以及建议具体旧数据目录的脚本帮助文本。修复应一律路由到RUNTIME_DATA_DIR或显式数据根参数不明确时阻塞 PR 并请求核心维护者裁决。发布渠道模型beta / prerelease / preview / stable根文档把发布渠道建模为四层并给出严格的晋升规则beta每日研发/开发验证渠道优化快速反馈不参与稳定晋升门prerelease稳定交付的内部验证渠道稳定发布以经过验证的 prerelease 工件为前提preview独立的早期访问渠道采用类稳定的严谨度版本形如X.Y.Z-preview.N发布到previewR2 渠道updater feed 在preview/latest下遵循 stable 的平台策略包括可选的 Linux 启用stable正式交付渠道不得依赖 preview只依赖 prerelease。几个关键的强制执行点均有源码佐证macOS Intel 是 critical pathrelease-prerelease.yml的enable_mac_x64默认true因为 Intel 构建跑在更慢的macos-15-intel队列上约 33 分钟其他平台约 21 分钟。没有enable_mac_x64的 prerelease 不能晋升 stable——validateStablePrereleaseMetadatatools/release/src/metadata/prepare-stable.ts要求被晋升 prerelease 的元数据包含platforms.macIntelenabled: true、arch: x64、signed: true以及带版本的 dmg/zip URL否则 stable 的metadata任务直接失败而非静默发布未验证的 Intel 构建。platforms.linux在该处被刻意不要求。签名不可省略validateStablePrereleaseMetadata同时要求platforms.mac.signed true与platforms.macIntel.signed true因此mac_sign_mode: no产出的 prerelease 永远无法成为 stable。公证notarize没有元数据字段因此不被校验——这正是快速默认值只砍公证不砍签名的原因。自动化测试不 gate prerelease 交付prerelease 的存在意义是让人安装并手工测试机器 CI 只是同一提交的并行意见不应阻塞发布。release-prerelease.yml只包含metadata → build_* → publish加上两个 fire-and-forget 调度任务验证分散在三个 concurrency-group 作用域到来源运行的派发工作流中release-prerelease-tests.yml功能 e2e、e2e_vitest、daemon 单元测试、verify、release-prerelease-smoke.yml打包 mac/Windows smoke不测试本地构建目录而是读取已发布版本元数据、下载用户实际会拿到的 DMG/setup.exe、校验 sha256 sidecar再写入tools-pack platform install读取的唯一路径、release-prerelease-card.yml渐进式 Feishu 卡片。发布卡片只有一个写入者FeishuPATCH会整卡替换因此release-prerelease-card.yml独占消息通过轮询三个运行的 jobs API 学习状态tools/release/src/notifications/prerelease-card.ts把卡片渲染成该状态的纯函数单元测试见 tools/release/tests/prerelease-card.test.tsfeishu-app.ts是应用机器人传输层。version_metadata_url是包是否已发布的权威信号而非 workflow conclusion后者会因为发布后的任何工作而变红。tools/release/src/notifications/feishu.ts也遵守同一规则VERSION_METADATA_URL优先于BUILD_STATE。公开应用身份按渠道区分stable 用Open Designbeta 用Open Design Betaprerelease 用Open Design Prereleasepreview 用Open Design Preview不得发布拖拽安装应用包为Open Design.app的 beta/prerelease/preview DMG。默认开启布尔值的派发转发写法notify-release-feishu.yml对默认开启的布尔值必须写${{ github.event_name ! workflow_dispatch || inputs.flag }}绝不写${{ inputs.flag || true }}——push 时inputs未设置第二种写法在 dispatch 上会把取消勾选读成 true使开关永远关不掉默认关闭的布尔值镜像使用${{ inputs.flag || false }}。能力暴露UI/CLI 双轨是回归红线根文档把每个用户可见能力必须同时通过 Web UI 与odCLI 可达定为硬性约束只交付其中一种表面即为回归CLI 是嵌入性契约外部 Agenthermes-agent、openclaw、自定义 Slack/Discord 机器人、从其他 shell 调用的打包运行时通过od子命令驱动 OpenDesign它们不渲染 Web UI两条表面必须调用同一组/api/*端点daemon HTTP 层是唯一真源共享 DTO 由packages/contracts承载CLI 形态必须支持--json输出并通过--prompt-file path|-接受长格式提示词保证经xargs、jq、heredoc管道作业干净新能力是一个三步闭合apps/daemon/src/*-routes.ts的 HTTP 端点配套 packages/contracts/src/api/ 契约类型apps/web/src/的 UI 表面 apps/daemon/src/cli.ts 中注册到SUBCOMMAND_MAP的od capability子命令源码第 388 行定义映射表836-839 行完成顶层分发。三步必须同一 PR 落地现有参照模式od automation …对应 Automations 标签页并映射/api/routinesod plugin …、od ui …、od project …、od media …、od mcp …、od research …遵循同一形态。Agent 运行时约定与物理 Run 生命周期根文档对运行时的几个关键机制给出了精确约定均有源码与测试佐证Prompt 输入格式RuntimeAgentDef.promptInputFormat决定 daemon 如何把 prompt 写入子进程 stdin。默认text写完即关闭 stdinstream-json把 prompt 包装为一条 JSONLuser消息并保持 stdin 打开使 daemon 可以在回合中途继续回写用户消息。Claudeapps/daemon/src/runtimes/defs/claude.ts搭载stream-json与--input-format stream-json作为通用中途输入基础设施其他 Agent 均停留在text。turn 边界与 stdin 关闭apps/daemon/src/server.ts 在 run 对象上跟踪run.stdinOpenapplyClaudeStreamJsonRunBookkeeping在收到turn_end或usage且stop_reason非tool_use时关闭 stdin 并记录turnCompletedCleanly。tool_use意味着模型在工具中途暂停等待 claude-code 内部 runner此时关 stdin 会截断后续响应。三帧读取 stop_reasonclaude-stream.ts从三个帧读取stop_reason因为 Claude Code 迁移了字段位置而 daemon 无法控制用户安装的构建版本(1)stream_event → message_delta → delta.stop_reason仅 2.1.259 携带需协商--include-partial-messages(2)assistant → message.stop_reason旧形态2.1.259 每帧为 null但旧 CLI 与 argv 兼容 fork 仍填充(3) 终帧result以usage形式暴露所有构建与 flag 组合都有。emitTurnEndOnce按 assistant message id 去重且刻意没有版本门。无论哪个来源触发turn_end都在该消息所有tool_use之后发出保证 daemon 不会在看见工具调用前关闭 stdin只有主回合帧可以触发带非空顶层parent_tool_use_id的 Task 子 Agent 帧会被拒绝#5487。所有上述行为的逐字 CLI 录音在 apps/daemon/tests/fixtures/claude-cli-recordings/见其 README。物理 Run 启动咽喉每个物理 Run 必须经internalRunCreation.start(run, analytics, starter)apps/daemon/src/services/internal-run-service.ts启动直接调用 run registry 的start会绕过 Run 分析生命周期不产生run_created/run_finished。pnpm guard的 run start choke point 检查强制这一点见 scripts/guard.ts 第 1528 行唯一允许调用.runs.start(的是该服务本身。analytics参数是刻意必填的无身份可归属的调用者定时 Automation、后台刷新必须显式传requestAnalyticsContext: null声明无身份是代码必须记录的决定。向用户提问唯一的question-form机制仓库只有一种澄清用户意图的机制模型内联输出的question-formmarkdown artifact。AssistantMessage.tsx直接在源 assistant 消息内渲染QuestionFormView答案作为下一条用户消息回流formatFormAnswers在 apps/web/src/artifacts/question-form.ts经POST /api/chat没有独立的 Questions 标签页、没有AskUserQuestion工具接线、没有/api/runs/:id/tool-result端点、也没有宿主答案返回路径question-form在任意回合都有效不只 turn-1 发现既用于 turn-1 发现 brief也用于对话中途澄清run-artifacts.ts中的runAskedUserQuestion通过扫描 run 的流式文本中的question-form标记跨text_delta块重组来产生run_finished.asked_user_question分析信号而不是检测任何工具调用stream-json 输入骨架的唯一产品消费者是POST /api/runs/:id/steer引导对话B11由用户向仍在运行的回合推入后续消息与question-form方向相反。其可接受性判定在apps/daemon/src/runtimes/run-steering.ts的classifyRunSteering不得在调用点重新推导也不得扩展成宿主提问路径。Chat UI 约定执行记录、Plan pill 与渲染接缝根文档对 Chat 面板的约定非常具体决策记录见 specs/current/chat-panel-next.mdTodoWrite 没有固定在 composer 上方的卡片任务列表只在回合执行记录内完整出现一次形态为执行计划 · N 步加每步一个抽屉components/chat/ExecutionShell.tsx旧的PinnedTodoSlot已随新执行记录移除不得复活固定在 composer 上方的是 Plan pillcomponents/chat/PlanPill.tsx一行第 N / M 步胶囊完整列表在悬停 popover 中且向上打开。N表示当前正在运行的步骤不是{done}/{total}run 结束或列表全部完成时 pill 消失。可见性、N/M与每步标记全部在纯函数runtime/chat/plan-pill.ts中组件只负责绘制自动滚动接线pill 位于.chat-log滚动容器之外与QueuedSendStrip共用同一套自动滚动管道containerRefResizeObserverMutationObserver重挂载且在 DOM 顺序上位于QueuedSendStrip之前避免队列增长时重叠快照工具去重dedupeSnapshotToolRetries折叠TodoWrite快照每次调用都是状态替换只保留最近一次SNAPSHOT_TOOL_NAMES列出快照型工具HTML 预览渲染模式apps/web/src/components/file-viewer-render-mode.ts 决定 URL 加载还是 srcDoc 预览bridgedeck、comment/inspect 选择、palette、edit、tweaks只能经 srcDoc 路径注入。宿主同时挂载两个 iframe 并通过 CSS 可见性切换避免切换渲染模式时 iframe 重载闪烁接收过滤器用isOurIframe(ev.source)接受两个 iframe 的消息但只应来自活动 iframe 的信号如od:tweaks-available会再检查ev.source iframeRef.current?.contentWindow。Web 工程规范CSS 所有权、组件复用、i18n 与动画哲学CSS 所有权apps/web/src/index.css 是仅导入的级联入口不得在其中添加选择器或声明共享全局样式放 apps/web/src/styles/设计 token、base/reset、primitive、app-shell 布局与无法安全 scoped 的遗留跨组件选择器新组件样式默认使用组件旁的 CSS ModulesComponent.module.css。全局类名只保留给刻意共享的契约可复用 primitive、主题钩子、第三方/内容样式、跨组件布局。组件复用新apps/webUI 应复用 packages/components 的共享 primitive如Button、VisuallyHidden不得为新增 UI 引入primary、ghost、icon-btn、sr-only等原始类——这些是存量标记的遗留兼容面。缺少 primitive 时优先向packages/components添加带 colocated CSS Module 的小型聚焦 primitive。i18napps/web/src/i18n/types.ts 是类型化Dict每个 key 必须在全部 19 个 locale 文件apps/web/src/i18n/locales/*.ts含ar、de、en、es-ES、fa、fr、hu、id、it、ja、ko、pl、pt-BR、ru、th、tr、uk、zh-CN、zh-TW中定义先在types.ts加 key缺失翻译会直接产生 typecheck 错误。UI 动画哲学默认 ease-out 为cubic-bezier(0.23, 1, 0.32, 1)内置ease太弱ease-in被禁止非对称时长——进入约 200ms、退出约 140ms手风琴展开/收起使用grid-template-rows: 0fr - 1fr搭配不透明度渐变规范实现是 apps/web/src/index.css 的.accordion-collapsible.accordion-collapsible-inner类对绝不要从transform: scale(0)动画从scale(0.9)或更高配opacity: 0起步条件性显示的元素保持挂载并切换 CSS 类如.chat-jump-btn-active因为 React 卸载会完全跳过退出过渡。验证策略与 Bug 跟进工作流根文档把验证纪律总结为一条可执行路径先写红 spec默认把 bug 编码为可证伪测试在源码改动前先变红让修复锚定在可观测行为上。工作示例见 e2e/tests/dialog/stop-reconciles-message.test.tsissue #135的完整闭环。从最便宜层开始e2e Vitestdaemon HTTP 边界→ 应用本地 Vitest → Playwright UI → 平台原生 harness只有更便宜层看不到症状时才下探。守住 spec 边界超出 bug 描述范围的缺陷属于后续任务自己的红 spec、自己的 PR在 PR 体的 Adjacent issues 中列出。让修复读起来像不变量优先写 docblock 描述必须成立什么的命名 helper而不是带道歉式历史注释的补丁式if。对基线做 diff邻接套件有既有失败时先 stash 或 checkout upstream 再声称无新增失败。PR 体链接 issue使用Fixes #N/Closes #N/Resolves #N使 issue 在合并时自动关闭并让发布时反向查找gh issue view N --json closedByPullRequestsReferences→git tag --contains merge sha有链可循。可见 bug 需要人工验证UI、平台原生行为、动画、单元测试看不到的竞态绿色 spec 不等于验收。典型形态是两个 namespace 运行时一个main、一个修复分支的 buggy-vs-fix 对比数据只能经生产 HTTP API 播种——源码级测试后门会让验证失效。本地验证兜底涉及 agent-stream/parser 改动时用mocks/的 mock CLI 回放录制会话验证事件形状往返不烧 provider 预算。PATH-overlay 激活方式export PATH$PWD/mocks/bin:$PATH OD_MOCKS_TRACE8-char-id OD_MOCKS_NO_DELAY1。标记工作就绪前至少运行pnpm guard与pnpm typecheck加上与改动文件匹配的 package-scoped 测试/构建。Prompt 双实现与切换开关根文档揭示了一个容易踩坑的结构一次生成运行由两个独立 prompt 实现之一组合而成。composeSystemPrompt在 apps/daemon/src/prompts/system.ts 第 905 行附近当 run 携带 OD Next recipe 时提前返回跳过该行以下的整个遗留栈API/BYOK 镜像在 packages/contracts/src/prompts/system.ts 第 318 行以同样方式分叉。两侧没有共享组合底加到一侧的规则只对走该侧的 run 生效。遗留侧apps/daemon/src/prompts/API/BYOK 镜像在packages/contracts/src/prompts/OD Next 侧plugins/_official/scenarios/od-next-strategy/assets/**逐字发送给模型的 markdown加packages/contracts/src/prompts/od-next-strategy.ts宿主运行时契约如question-form与 deck framework 在这里不在 task profile 中开关Settings → Labs → Design Harness、app-configodNextStrategyMode或OD_NEXT_STRATEGY_ROLLOUT。资格由 apps/daemon/src/strategies/od-next/rollout.ts 第 138 行的evaluateOdNextRollout每 run 重估且可被运行时信号中途锁下——因此同一台机器开关不变时 run 走哪一侧也会变化两侧分歧会表现为间歇性 bug。任何 prompt 文本改动上述任一位置前必须读 docs/prompt-composition.md它承载变体轴、命名当前各契约由哪条路径承载的宿主运行时契约表、插件侧 asset 清单与包哈希规则。宿主契约应只有一个被所有路径消费的来源packages/contracts/src/prompts/deck-framework.ts 是已落地的范例从单一脚手架喂给 classic、BYOK 与 OD Next。该插件assets/下的文件会被逐字发送给模型绝不写入仓库维护笔记。边界约束与提交纪律速查根文档把仓库边界约束集中为一组可直接检查的规则测试放apps/、packages/、tools/内与src/同级的tests/目录src/保持纯源码不新增*.test.ts/*.test.tsx应用包不得把另一个应用的私有src/或tests/实现当作共享 helper 导入尤其apps/web/**不得导入apps/daemon/src/**web/daemon 集成只能走 HTTP API、packages/contracts与应用本地 provider 边界共享 API DTO、SSE event union、错误形态、任务形态与示例 payload 集中在packages/contracts且该包保持纯 TypeScript不得依赖 Next.js、Express、Node 文件系统/进程 API、浏览器 API、SQLite、daemon 内部与 sidecar 控制平面Sidecar 进程戳恰好五个字段channel、namespace、source、mode、appIPC 是私有实现细节永远不是戳字段sidecar 身份只来自 argv不得创建由戳派生的身份/状态文件编排层tools-dev、tools-pack、打包启动器必须调用open-design/sidecar的 client/atomic primitive不得暴露 argv 组装、IPC 路径或进程扫描打包运行时路径必须 namespace-scoped且与 daemon/web 端口无关默认运行时文件位于project-root/.tmp/source/namespace/...私有 IPC 端点由 sidecar 从五字段戳与当前 OS principal 派生POSIX 端点在 OS 临时目录下 principal-scoped 的哈希目录调用方把具体路径当不透明值Git 提交不得包含Co-authored-by或任何共同作者元数据PR 打开使用.github/pull_request_template.md且每个区块都要填Why 必须同时回答作者用例与被解决的痛点What users will see 从用户视角描述而非代码视角Surface area 清单必须反映实际触及的表面含skills/、design-systems/、design-templates/、craft/、CLI flag、env var、i18n key 与新依赖代码评审以 docs/code-review-guidelines.md 为仓库级标准本根AGENTS.md与其冲突时以根文档为准阻塞性反馈聚焦正确性、安全/密钥、数据完整性、仓库边界违规、契约/迁移破坏、缺失必需校验与高风险可维护性问题涉及.github/的改动先读 .github/AGENTS.mdCI 自动化采用两层架构——业务层工作流ci.yml是主低权限 PR/merge-queue/手动验证工作流产出类型化交接工件与原子能力工作流comment.atom.yml、autofix.atom.yml、report.atom.yml。新增业务命名后续工作流前先尝试表达为ci.yml生产者加现有能力交接工件的命名、存储布局与解析行为集中在.github/scripts/handoff.py。FAQ 精华常见疑问的权威答案为什么没有根级pnpm dev/pnpm start避免 daemon、web、desktop 通过不一致的 env、端口、namespace 或日志路径启动所有本地生命周期一律走pnpm tools-dev。为什么apps/nextjs不能恢复当前 web 运行时是apps/web历史apps/nextjs布局已从活动仓库形态移除恢复会重新引入重复的应用边界与过期脚本。desktop 如何发现 web URL通过 sidecar client 查询运行时状态URL 来自 client status而不是 desktop 猜测端口、IPC 路径或读取 web 内部。sidecar-proto / sidecar / platform 如何拆分open-design/sidecar-proto拥有业务 action 名与 DTO/状态形态open-design/sidecar是五字段 argv 戳、私有 IPC、OS 资源、进程发现、启动、调用与终端生命周期的唯一真源open-design/platform提供 sidecar 之下的通用 OS 进程原语不得把这些实现细节泄漏给应用或编排层。何时需要pnpm install修改包 manifest、workspace 布局、命令入口点、bin/link 相关内容或增删 workspace 包之后。能用 Node 22 吗不能。package.json#engines指定node: ~24是唯一受支持运行时lockfile 钉定better-sqlite311.10.0Windows 上无 Node 24 预编译二进制需 node-gyp 源码编译旧版本未测试可能遭遇 lockfile 或依赖不兼容。结语Open Design 根级AGENTS.md的价值不在于罗列命令而在于把单一事实来源落到实处数据路径只有一个真源RUNTIME_DATA_DIR、能力暴露必须双轨、Run 启动只有一个咽喉、提问只有一种机制、发布卡片只有一个写入者。对进入该仓库的 Agent 与开发者而言遵循这份规范意味着每一次改动都能被pnpm guard、pnpm typecheck、package-scoped 测试与分层AGENTS.md的边界检查所验证从而在大规模多包仓库中保持可维护性、可验证性与跨层一致性。【免费下载链接】open-design Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. ️ Local-first desktop app. ️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images video — real files, HTML/PDF/PPTX/MP4 export. Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode 20 CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考