update-project

用途

将此技能用于现有仓库。它会先判断仓库是否已准备好进行 Copier 更新、需要迁移旧版工作流，或是符合条件、可显式采用自身的 dstack 模板源。常规更新会从 .copier-answers.yml 中的 Git 源解析已记录的稳定或不稳定通道，然后应用 Copier 的三方更新，使项目自有的更改保留在本地。

将 <skill-dir> 解析为包含此 SKILL.md 的目录；将 <core-dir> 解析为其同级的 dstack-core 技能目录。通过共享工作流运行器运行更新辅助工具，以便 uv 为整个工作流复用同一环境，而不是为每个脚本路径创建一个环境。

共享信任约定

执行此工作流前，请阅读并遵循 ../dstack-core/references/TRUST-AND-AUTHORITY.md。此约定对本工作流具有规范效力。如果它与此技能冲突，请遵循限制更严格的规则并报告冲突。

启动版本证据

应用更新或迁移前，请遵循 ../dstack-core/references/SKILL-VERSION.md 中针对 update-project 的说明。在只读预检后，捕获准确的单行输出，并在修改前将其纳入更新/迁移 JSON 或响应中。stale 结果会提示使用 npx skills update；unavailable 表示未作出新鲜度声明，不会阻止离线工作。

更新专属授权：

• 调用授权进行预检检查。只有仓库通过迁移路由后，才授权执行本地 Copier 更新和专用协调提交。不授权推送、合并、强制推送、删除分支或进行无关的项目更改。
• 默认通道为 stable，它会选择最新的、兼容 PEP 440 的 vX.Y.Z 稳定版本。unstable 会选择已记录源的默认分支 HEAD。现有项目会保留其已记录的通道。
• 每个选定的标签、分支或显式修订版本都会解析为可到达的提交，并将其准确 SHA 持久化到 _commit；已安装的技能元数据绝不是模板来源。
• 显式开发修订版本必须在修改前报告。采用模板源自身的行为绝不隐式执行。

1. 更新前迁移旧版仓库

先运行不会修改任何内容的预检：

uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --preflight --json

该辅助工具会检查：

• .copier-answers.yml 是否存在；
• 项目中所有处于活动状态的 tasks.md 文件，但不包括工具、模板、归档、迁移和供应商目录；
• Beads 状态是否已初始化，不会将复制过来的公式视为已初始化的数据库。

当 recommended_workflow 为 migrate-workflow 时，不要运行 Copier 更新。说明检测到的任务文件以及缺失的 Beads 状态，然后使用 AskUserQuestion 只询问一个问题：Run /migrate-workflow now?

• 如果用户同意，执行 /migrate-workflow，让该工作流采用当前标记的模板，手动协调渲染后的新项目结构，初始化 Beads，并导入旧版任务状态。
• 如果用户拒绝，则停止，不运行 Copier，也不更改文件。
• 迁移完成并提交检查点后，在考虑更新之前重新运行此预检。

无论是否已存在 Copier 状态，都适用此路由。包含旧版 tasks.md 文件且没有 Beads 状态的仓库，必须先迁移，再更新模板。

对于尚未在 answers 中包含 language_profiles 的 Copier 管理项目，请使用预检中仅针对根目录的 suggested_language_profiles。它会将 pyproject.toml 映射为 Python，将 tsconfig.json 或 package.json 映射为 TypeScript，将 Cargo.toml 映射为 Rust，将 go.mod 映射为 Go，将 mix.exs 映射为 Elixir，并将 flake.nix 映射为 Nix。请用户确认这些建议；切勿自动应用。如果未找到或未接受任何建议，则提供唯一的 other 配置选项。递归发现软件包不属于此工作流的范围。

较早的 answers 文件默认使用 single-package，且不包含任何软件包。除非用户明确要求转换，否则保留此状态。仅当每个完整软件包都使用 --monorepo-package '<JSON object>' 指定时，才使用 --repository-layout monorepo 进行转换；切勿推断软件包。预检会列出确切目标位置和已占用路径，并在查找修订版本或渲染前拒绝无效、保留、重叠、大小写冲突或符号链接路径。软件包对象必须且只能包含 display_name、slug、path 和 language_profiles；显示名称和缩写须原样保留。

2. 更新前提条件

仅当预检建议 update-project，并且满足以下条件时，才继续执行常规更新：

• .copier-answers.yml 中记录了基于 Git 的 _src_path 和 _commit；
• 初始脚手架或已完成的迁移检查点已提交；
• 工作树干净，除非用户明确接受在工作树不干净时更新；
• 记录的 Git 源可以解析所选频道或明确指定的修订版本。

3. 应用模板更新

通过记录的频道更新，或明确覆盖频道：

uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py
uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --stable
uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --unstable

预览、包含预发布版本，或明确选择其他修订版本：

uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --pretend
uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --prereleases --pretend
uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --vcs-ref <release-tag>
uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --vcs-ref <reviewed-tag-branch-or-commit>
uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --add-profile typescript
uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --remove-profile python --add-profile other

省略配置文件标志会保留记录的选择。添加/移除标志可重复使用，是幂等的集合操作；同一配置文件不能同时出现在两个集合中。other 具有排他性；移除最后一个已识别配置文件时，必须在同一次调用中添加 other。

更新会复用 Copier 已记录的结构化项目简介值。对于缺少用途、用户、范围、边界或项目类型中任一项的旧版项目，请一次询问一个问题，并传入相应的 --purpose、--users、--scope、--boundaries 和 --project-kind 标志。切勿从旧版描述中推导缺失值。

明确指定的分支、提交或 HEAD 是一次性覆盖。辅助工具会保存确切解析出的提交，同时保留所选稳定/不稳定频道，作为下次更新的默认值。

dstack 自我采用

当预检报告 update-project-adopt 时，仅在获得用户明确批准且工作树干净后运行：

uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/update-project.py --adopt --unstable \
  --project-name dstack --project-slug dstack \
  --purpose "<purpose>" --users "<users>" --scope "<scope>" --boundaries "<boundaries>" \
  --project-kind other --language-profile python --json

自我采用会在隔离环境中渲染可从远程默认分支访问的提交，复制缺失的生成路径，保留现有的 dstack 所有路径，将有差异的生成版本写入 migration/copier-adoption-candidates/，并记录精确的不稳定 Copier 状态。逐一处理所有候选项，并在验证或提交前删除该目录。它绝不会采用仅存在于本地的提交，也不会在处理完成前运行生成代码。

助手契约

助手：

1. 解析 Git 根目录，并在任何修订版本查找或变更操作之前处理迁移／自我采用路由；
2. 从 .copier-answers.yml 读取 Copier 源和先前的修订版本；
3. 解析保留的或显式指定的频道：stable 使用按 PEP 440 顺序排列的最大符合条件标签；unstable 使用源默认分支的 HEAD；
4. 默认排除预发行版本，仅在使用 --prereleases 时包含；
5. 验证所选的每个修订版本均可访问，并在报告成功前保存其精确提交 SHA；
6. 默认要求工作树干净；
7. 应用 Copier 更新；
8. 仅检查 Git 可见的已修改和未跟踪文件，确认是否存在完整的冲突标记、Git 未合并路径和新生成的 .rej 文件；
9. 忽略依赖环境和其他 Git 忽略的内容，例如 .venv；
10. 无冲突时，运行 python3 scripts/setup-tooling.py --json 以刷新 mise.lock、使用 --locked 安装，并协调 hk 钩子；
11. 工具设置成功后，运行 bd hooks install，并验证 bd hooks list --json 报告的每个钩子均已安装且为最新；单独的 beads_hooks 结果会报告状态和恢复命令；
12. 存在冲突时，跳过所有生成的项目代码，将工具设置和 Beads 钩子报告为已跳过，并注明恢复命令；
13. 若存在 scripts/check-docs.py，则运行该脚本；
14. 使用与存储模式无关的 Beads 冒烟测试：运行 bd info --json 和 bd ready --json --limit 1；
15. 若存在项目功能公式，则对其进行验证；
16. 保留或显式添加／移除规范语言配置；预检报告的旧版根清单建议绝不静默应用；
17. 将较旧布局的答案默认为单包，并在渲染前验证显式的包转换；
18. 报告所选发行版、解析得到的 Copier 提交、变更文件、单独的工具设置和 Beads 钩子阶段、验证结果、警告、冲突及就绪状态。

不使用 bd doctor，因为并非所有 Beads 存储模式都支持它。

4. 处理每个变更路径

根据助手的变更文件输出以及 git status --short 和 git diff --name-status 建立路径核算台账。每个变更路径都必须恰好出现一次，并归为以下一种类别：

• template change accepted；
• project change preserved；
• conflict resolved。

对于每个路径，记录上游变更、必须保留的本地行为、解决方案和验证证据：

路径	分类	上游／本地意图	解决方案	验证
…	template change accepted	…	…	…

保留项目自有的架构、运维、开发、参考资料、路线图和功能历史。路径含义不明确时停止；没有文本冲突不代表已接受。只要有任何变更路径未列入台账，或仅归类为 unknown，处理就尚未完成。

核算完所有路径后，针对最终文件重新运行项目专属验证，并将模板更新作为独立边界提交，然后再继续功能开发。工具设置结果若处于降级状态，则仍未解决：运行报告中的每条恢复命令，并验证 mise.lock 为最新且非空，然后才能将更新归类为就绪。

返回

报告：

1. 预检路径、旧版任务文件、Beads 状态结果，以及提供迁移选项时用户的同意决定；
2. 目标位置和 Copier 源；
3. 之前的 Copier 修订版本和渠道；
4. 所选渠道、易读标签／分支／引用，以及解析后的确切修订版本；
5. 之前、建议和最终的语言配置；
6. 仓库布局、确切的软件包预检结果、渲染后软件包路径，以及每个尚未解决的候选项；
7. 已更改文件和完整的路径核算清单；
8. 实际更新冲突及解决方法；
9. 工具可用性、锁定、安装和钩子状态的分别说明，以及确切的恢复命令；
10. 文档和 Beads 验证；
11. 警告和任何未分类路径；
12. 是否已准备好恢复功能开发；如果仍需要迁移、仍存在冲突或工具降级、仍有未解决的候选项、锁定已过期或缺失，或者有已更改路径未分类，则必须为否。