Adopt a repo 把一个代码库带进 1DesignTool:应用把项目注册在一个应用自有的 worktree 上——应用数据目录下签出的 1design/<slug> 分支——让 agent 在你的真实 UI 里设计,却从不写进你的 checkout。它是从"设计一个东西"到"在我的东西里设计"的桥。

怎么采纳

在主屏幕上,Open folder… 选择仓库并打开采纳面板:它读取文件夹,问是否要在其中设计,点击 Design inside this codebase 就会把项目注册为 codebase 项目。应用创建 worktree——签出在应用数据目录下的 1design/<slug> 分支——项目开在它上面,而不是你的 checkout。

你的仓库保持原样:写操作落在应用的 worktree 里,读操作透过它看到你的真实文件。采纳面板也会显示隔离说明——worktree 是什么,以及为什么你的 checkout 不是工作副本。

worktree 模型

codebase 项目活在 1design/<slug> 上——一个应用自有的分支,在应用数据目录下作为 worktree 签出:

读 ——agent 透过 worktree 看到你的真实 UI
写 ——轮次的 diff 落在分支上,永不落在你的 checkout
预览 ——应用对 worktree 的预览,或你自己的 dev server
你的 checkout ——从不被写;托管路径(.1design/、skill 目录) 通过 .git/info/exclude 隐藏,不动你的 .gitignore

项目上的分支条显示这条通道——从 main 开出的 1design/<slug>、领先的提交数、各轮改动的文件。

在代码库里设计

采纳之后,steering 和任何项目一样——只是 brief 是关于你的 UI: "让 header 吸顶"、"在 profile 旁边加个设置界面"。agent 透过 worktree 编辑真实文件;预览显示跑在你自己 dev server 上或应用预览里的 app。

diff 范围的门禁

codebase 项目不跑完整的 design-kit 门禁——你的仓库不是生成产物, 那样检查会标记本轮从没碰过的代码。检查改为 diff 范围:本轮改动的文件被验证(对 diff 跑 tells.mjs),分支条的评审操作准确显示这一轮做了什么。

评审与合并

当一轮的工作看起来对了,分支条的 Review changes 显示这轮产生的 diff;Copy merge command 或 Merge into main 把分支的工作带回你的仓库。Discard 扔掉 worktree 状态。合并进的是你 checkout 的 main——worktree 是沙箱。

Build 与 Sketch 模式

codebase 项目在实时预览之上还带两个额外模式:

Build mode ——可视化编辑运行中 app 的 UI,改动写回代码(见 Build mode)
Sketch mode ——映射到组件的 .1d 草图(见 Sketch mode)

Direct 模式

worktree 模型是默认,因为它最安全——应用写自己的分支、在应用数据目录下,永不碰你的 checkout。Direct mode ——采纳面板上的另一个选项——把项目直接指向你的 checkout;agent 就地编辑真实文件。它更快,但工作落在你的工作副本上,所以 worktree 默认是有理由的。

它擅长什么

在你的真实 app 里设计 ——已经存在的界面,重做样式
功能工作 ——就地做新界面或新流程
UI 走查 ——整个 app 的视觉打磨,带 diff
代码库上手 ——agent 读它要住进去的仓库

隔离说明

worktree 的存在是为了让 agent 的工作在你合并之前碰不到你的 checkout——注册的项目根是应用的分支,读写都透过它,项目需要的托管文件通过 .git/info/exclude 隐藏,让你的 git status 保持干净。代价是一步:工作对了之后,你来合并分支。

Tip: 合并确认干净之前保留 worktree——在工作确认前删分支会丢掉 diff。合并按钮把它变成一步操作;点之前先评审。

采纳一个代码仓库