URDF-Studio: Instructions file for Claude Code

URDF Studio Agent Guide

URDF Studio 是机器人设计、装配、可视化与多格式导出工作台，使用 React、TypeScript、Three.js/R3F、Vite、Tailwind CSS 和 Zustand。依赖版本以 package.json 为准。

本文件只保留项目约定与易踩坑的约束；专题细节按任务查阅末尾文档，不要求每次通读。重构进度、债务清单和文件行数不放在这里。

协作方式

• 默认中文沟通；代码标识符、命令、路径和错误原文保持原文。
• 根据目标和上下文自治完成任务；常规实现选择自行决定，只有真正影响目标或涉及破坏性操作的不确定事项才澄清。
• 独立子任务能提高效率时使用原生 subagent 并行处理。
• 按变更风险选择验证；必要检查通过后结束，不为小改动反复扩大测试范围。

设计原则

• 第一性原理：从实际目标、约束和数据模型推导方案；发现更简单的可行路径时主动指出，不机械照表面措辞实现。
• Linux 设计哲学：一个模块做好一件事，接口小而清晰，优先组合现有稳定能力；让数据流和控制流简单直接。
• 简单与实用：新抽象必须降低整体复杂度；不为假设的未来需求预埋框架，不为行数把内聚逻辑拆成碎片。
• 可调试性优先：所有权、生命周期和失败路径显式可追踪；暴露真实错误，不用隐式同步、静默降级或魔法默认值掩盖坏状态。
• Google-style 工程质量：正确性与数据所有权优先，保持类型安全，用必要的行为测试保护变更，逐步收紧存量债务。

设计取舍的详细约束见 docs/architecture.md §9–10。

架构红线与执行准则

依赖方向：app -> features -> store -> shared -> core -> types，允许跨级向下依赖。app 编排跨域 workflow，features 承载单一业务能力，store 保存状态，shared 放稳定共享原语，core 保持无 React/UI 的领域逻辑。@/ 指向 src/。

• feature 间不直接互引；跨 feature/store 协调放 app/hooks，store action 不得写另一个 store。Editor facade 是精确登记的例外。
• 分层、公开入口、发布包依赖闭包和循环依赖统一由 scripts/tools/dependency_boundaries.mjs 检查；不复制 checker，不扩大 allowlist，不用 require() 绕过检查。
• src/lib/ 与 packages/react-robot-canvas/ 的可发布运行时不得传递依赖 app/store/features；应用状态通过 props/ports 和 feature adapter 注入。
• workspaceStore.workspace: AssemblyState 是唯一可写机器人模型，使用单一 history；RobotData 仅存在于 component 或只读 projection，不恢复顶层 robot 镜像或 source 双写同步。
• viewer/export 从 createAssemblySceneProjection / createAssemblyScenePlacement 或 canonical export projection 派生；renderer strategy 不参与 selection、mutation、history 或 source 路由。
• source-local mutation 归 app/hooks/workspace-mutations/；component source command、draft/reconcile/history 策略归 app/hooks/workspace-source-sync/。viewer 只上报 typed renderer facts，mutation queue 和 transaction 由 app coordinator 消费和决定。
• .usp 仅接受与生成严格 3.0 canonical workspace schema，不恢复旧版迁移、旧 payload 或双 history。
• 格式检测唯一实现：src/core/parsers/format_detection.ts；app/file-io 只做 workflow wrapper。
• 通用 robot kernel/backend 生命周期归 shared/components/3d/robot/，无 store/feature 依赖；features/urdf-viewer 注入应用状态并拥有 workspace adapter；shared/components/3d/renderers/ 只放纯 mesh renderer 与 Collada helpers。
• worker/runtime 明确 app/document 生命周期 owner；组件卸载使自身在途 async 结果失效，不销毁其他 viewer 共用的 runtime。observer、listener、timer 和 THREE 等资源必须对称 cleanup；worker entry 保持 protocol dispatch，独立 cache/session 按生命周期归属模块。
• 多 viewer 的 interaction/hover/selection lock 使用 owner token 或引用计数，成对 acquire/release；只读、offscreen、snapshot viewer 不改 canonical selection 或全局 hover lock。
• 导入、导出、解析、hydration、worker 链路保留真实错误，不用空值、旧缓存或静默降级伪装成功。