任务工作区

把过程文件和正式交付分开。.oil-ui 是项目里的本地工作区，不是交付目录，也不是另一套设计规范。

优先级与边界

• 用户指定的输出路径和项目已有约定优先。项目已经规定 _work/、shots/ 或其他过程目录时沿用，不另建 .oil-ui，也不迁移旧文件。
• 没有约定时，从项目根目录使用 .oil-ui/<任务名>。任务名用简短、可辨认的名称；同名目录属于别的任务时加后缀，不覆盖。
• 真实代码、正式测试、最终文档和线上引用的资产仍写用户项目。页面、构建配置、样式和脚本不得引用 .oil-ui。
• 不把凭据、未脱敏的用户数据或令牌写进工作区。不自动清理历史任务；删除、迁移和对外上传仍需授权。

开始任务

先读项目的 AGENTS.md、DESIGN.md 或同类规范，再决定工作目录。没有这些文件不影响开始。只有确定使用 .oil-ui 时，才检查并准备下面的目录；项目已有其他过程目录约定时不创建它。

.oil-ui 已存在但不是目录，或者它是指向别处的符号链接时，不往里写，说明冲突并由用户决定。已是普通目录时复用，不清空。每个任务使用独立子目录，继续同一任务时才复用该子目录。

使用 .oil-ui 且 .gitignore 不存在时写入：

*!.gitignore

它只忽略过程文件，不修改项目根目录的 .gitignore。已有这个文件但内容不同时保留原文，并告诉用户过程文件可能出现在 Git 状态里。需要提交的证据或文档应明确放到项目正式位置，不改变忽略规则。

过程文件放哪

按实际需要创建子目录，不为形式完整创建空目录：

• explore/：候选方案、调研、未确认的设计草稿和临时小样。
• assets/：原始素材、中间变体和素材缓存。
• shots/：截图、录屏和评审证据。
• logs/：命令日志和临时输出。

需要长期保存的正式测试、设计规范和交付文档不藏在这里。进行中的迁移状态留在任务目录；规范条目的确认与推断按存量项目的规则标记，不把推断写成用户确认。

工具的命令目录与输出

不是所有工具都一律从任务目录运行。根据页面资源和 HTML 引用基准选择命令目录，过程输出统一放进任务目录。显式 --out、--dir、--cache 和其他输出参数始终优先，不重新解释。

• 截图与录屏：用 --root <项目根> 明确静态服务根，并用 --out .oil-ui/<任务名>/shots 指定输出。这样嵌套页面仍能加载项目共享资源，截图则留在工作区；--root 只决定服务范围，不决定截图输出位置。
• 素材检索：从任务目录运行 curate-media.mjs，默认 assets/ 和 .curate-cache.json 就会留在任务目录。显式 --dir 指向其他位置时，工具可能回退读取该目录或父目录的已有缓存；需要任务隔离时，同时显式指定本任务的 --cache .curate-cache.json，需要共享时再复用旧缓存。
• 对比页：候选放在任务目录的 explore/，build_explorer.py 会默认把 style-explorer.html 生成在旁边。
• 生图：最终结果要成为页面资产时，用 --out 直接写到项目正式资产目录。
• 图片处理：需要复制正式 srcset 时，从项目根目录运行 prep-image.mjs 并输出到正式资产目录。它的片段按命令目录计算，不要从任务目录复制相对路径到正式页面。

工具选项见 工具 [blocked]。中间原图可以留在工作区，但最终 HTML 及其依赖只能引用项目正式位置里的文件。

存量项目续作

未确认的方向草稿和进行中的迁移状态留在工作区。项目已有设计规范文件的读取、确认、推断标记、更新和入口按该文件及项目约定执行，不把过程草稿当成项目规范，也不另写一套重复规则。

交付检查与停止

交付前核对最终改动，不只看命令是否成功：

• git diff 中只有正式交付、必要的规范更新和用户要求的文件。git status 里的过程文件只能作为未跟踪项保留，不能加入提交；.oil-ui/.gitignore 是允许保留的工作区配置。
• 已有不同忽略规则导致过程文件出现在未跟踪项时，列出来并说明，不为了消除提示而删除、迁移或改写规则。
• 正式代码和页面没有 .oil-ui 引用，所引用的资产都存在于项目正式位置。
• 项目根目录没有意外新增的候选、截图或缓存；旧文件没有被移动或删除。
• 交付说明给出正式文件和工作区证据的位置，并运行项目相应检查。

现有约定和工具已经能完成时，不新增目录管理程序。只有真实任务反复出现建错目录、覆盖任务或误交付时，才把初始化或检查做成脚本。