setup-project

目的

仅将此技能用于新仓库。它会从官方 Git 源解析所选频道，验证已安装的捆绑模板与该提交完全一致，渲染模板包，为后续三方更新记录提交，初始化新项目工作流，并验证生成的文档。它不会迁移旧项目状态。

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

共享信任约定

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

启动版本证据

渲染或初始化项目之前，请按照 ../dstack-core/references/SKILL-VERSION.md 中针对 setup-project 的要求操作。在只读目标预检之后，捕获确切的单行输出，并在修改项目之前将其纳入设置 JSON/响应中。若结果为 stale，请提示运行 npx skills update；若结果为 unavailable，请记录未对新鲜度作出保证，且不要阻止离线工作。

设置专属授权：

• 默认源为 gh:RobertDeRose/dstack；stable 选择其最新的稳定 PEP 440 标签，unstable 选择其默认分支的 HEAD。默认使用 stable。
• 辅助程序会解析所选标签、分支或显式修订，验证捆绑的 copier.yml 和 template/ 与该提交一致，并在 .copier-answers.yml 中记录准确且可访问的 40 位 SHA；技能元数据绝不会用作模板来源依据。
• --template-source 和 --vcs-ref 是显式的开发/测试覆盖项。请求的修订必须可从记录的源获取。
• 此工作流绝不会将现有项目内容解释为迁移输入。辅助程序没有覆盖项目文件的模式；现有仓库应转至 /migrate-workflow。

路由预检

调用辅助程序前检查目标位置。

1. 如果存在 .copier-answers.yml，不要运行设置。说明该项目已由 Copier 管理，并使用 AskUserQuestion 提出且只提出一个问题：Run /update-project instead?
2. 仅在用户同意时运行 /update-project。如果用户拒绝，则停止，不要修改仓库。
3. 如果存在项目文件但没有 .copier-answers.yml，则停止并引导用户使用 /migrate-workflow；不要将迁移工具复制到项目中，也不要通过此工作流合并现有仓库。
4. 仅当目标是新项目目录时才继续设置；已安装的本地 skills 树或 skills-lock.json 除外。

辅助程序会独立拒绝已存在 .copier-answers.yml 的情况；这是非交互式安全保障，并不表示可以自动调用 /update-project。

项目概要

在调用辅助程序之前，使用 AskUserQuestion 收集缺失的信息，每次只问一个问题，顺序如下：

1. --purpose：用一句话描述问题和预期结果；
2. --users：用一句话描述目标用户；
3. --scope：用一句话描述当前支持的范围；
4. --boundaries：用一句话描述主要排除事项和所有权边界；
5. --project-kind：选择 library、cli、service、application、infrastructure、documentation 或 other；
6. --language-profile：从 python、typescript、rust、go、elixir、nix 或 other 中选择一个或多个。

选择项目类型和语言配置即表示确认；不要再问第二个确认问题。other 不能与其他选项同时选择，且表示没有受认可的语言工具链。值必须是非空的单行内容。不要根据项目名称推断缺失信息，也不要编造默认值。

然后询问仓库是 single-package（默认值）还是 monorepo。对于 monorepo 模式，收集 1–32 个明确的 package 对象，每个对象包含准确的 display_name、小写连字符格式的 slug、规范化的相对 POSIX path，以及非空的规范 language_profiles 列表。保留显示名称和技术缩写的原样。将每个对象作为 JSON 传入 --monorepo-package，并传入 --repository-layout monorepo。完整报告辅助程序的 layout_preflight；如果它报告路径无效、已保留、重叠、大小写冲突或为符号链接，则不要渲染。

默认值

• 项目名称：使用提供的值，否则使用 basename "$PWD"。
• 目标位置：当前工作目录。
• 模板通道：stable；传入 --unstable 以选择源默认分支的 HEAD。
• 渲染源：完成精确修订版本验证后的已安装程序包；显式指定的 --template-source 会覆盖此设置。
• 记录的更新源：gh:RobertDeRose/dstack，除非显式指定了 --template-source。
• 记录的基线修订版本：精确解析出的提交 SHA；stable 结果还会报告所选发布标签。
• 默认分支：main。
• Beads：在项目仓库中执行原生的非 stealth 初始化。原生 Beads 会提交协作控制文件、发现 Git origin、管理 Dolt 的存放位置并配置同步。执行 bd init 时保留 --skip-hooks，验证其精确提交路径，应用由机器生成的 README 排除规则，再通过项目钩子修正该提交，然后运行 bd hooks install 并验证 bd hooks list --json。如果 bd 不可用，则报告初始化和钩子验证仍待完成；绝不能用 --stealth 替代，也不能提交运行时或数据库路径。
• 工具链：渲染后以及可选的 Git 初始化完成后，为 Linux/macOS x64/ARM64 解析 mise.lock，使用 mise install --locked 安装，然后单独安装仓库本地 hk 钩子。这些步骤需要 mise 和网络访问权限。

执行

uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/setup-project.py [project-name] \
  --purpose "<problem and outcome>" \
  --users "<intended users>" \
  --scope "<current supported scope>" \
  --boundaries "<key exclusions and ownership boundaries>" \
  --project-kind <kind> \
  --language-profile <profile> [...] \
  --repository-layout single-package

项目名称仍为可选项，默认使用 basename "$PWD"。添加 --destination <path> 可指定另一个新目录作为目标位置，添加 --delete-readme 可省略起始 README，或添加 --unstable 以使用默认分支上的最新提交。

仅用于开发的模板覆盖仍需提供相同的必需概要标志：

uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/setup-project.py "Reader Control Plane" \
  --purpose "Coordinate reader devices from one control plane." \
  --users "Operators responsible for reader fleets." \
  --scope "Provisioning and health workflows for supported readers." \
  --boundaries "Reader firmware and identity-provider administration remain external." \
  --project-kind service \
  --language-profile python \
  --language-profile typescript \
  --template-source gh:example/dstack-fork \
  --vcs-ref <reviewed-tag-or-commit>

设置辅助程序会自行执行渲染后的初始化。它不会在新项目中生成 scripts/bootstrap.py、scripts/migrate-legacy-workflow.py 或迁移指南。使用 --skip-post-setup 可跳过工具链、Beads 和文档设置，同时保留精确的恢复命令。--no-git-init 仍会解析工具，但会报告钩子和协作式 Beads 初始化仍待完成；如果目标目录本身已经是 Git 仓库，则不在此限。

验证

至少确认：

.copier-answers.yml
AGENTS.md
.beads/formulas/dstack-feature.formula.toml
docs/book.toml
docs/src/SUMMARY.md
docs/src/planned-features.md
docs/src/features/_template/design.md
docs/src/features/_template/index.md
scripts/check-docs.py
scripts/setup-tooling.py
mise.toml
hk.pkl
.config/rumdl.toml

确认这些不适用于新项目的路径不存在：

MIGRATION.md
scripts/bootstrap.py
scripts/migrate-legacy-workflow.py

验证 .copier-answers.yml 记录了所选来源、解析出的确切提交 SHA，以及 dstack_template_channel。 验证生成的 AGENTS.md 要求通过 git commit -F <file> 使用真正的多行提交消息（绝不能使用多个 -m 标志或转义的 \n），并且只允许通过 git merge --ff-only 合并到 main。该辅助脚本会在设置过程中运行 uv run --no-project python scripts/check-docs.py。工具成功运行后会生成非空的 mise.lock，使用 --locked 安装，并运行 mise x -- hk install --mise。Beads 阶段仅在原生初始化修正提交之后运行 bd hooks install， 随后要求 bd hooks list --json 报告的每个钩子都已安装且为最新状态。如果 mise、解析、安装、hk 钩子设置或 Beads 钩子设置失败， 则脚手架保持完整，JSON 中的 tooling 和 beads_hooks 对象分别报告状态、长度受限的错误文本和确切的恢复命令。 使用以下命令重新运行恢复：

python3 scripts/setup-tooling.py --json

运行 Beads 验证之前，先检查其是否可用：

if command -v bd >/dev/null 2>&1; then
  bd prime
  bd list --type epic --label workflow:feature --all --json --limit 0
else
  printf '%s\n' 'Beads verification outstanding: install bd, initialize it, then run bd prime.'
fi

如果 bd 不可用，请勿运行 bd prime。此时设置可以完成，但返回内容必须将 Beads 初始化和验证列为待处理事项。

Copier 合约

• 提交 .copier-answers.yml 和初始脚手架。
• 稳定版设置和更新会选择最新的稳定标签；不稳定版设置和更新会选择源默认分支的 HEAD。两者都会记录使用的确切提交。
• npx skills update 会更新已安装的技能定义和脚本。
• /update-project 会保留记录的通道，除非明确覆盖。
• 请勿手动编辑 .copier-answers.yml。

返回内容

报告项目名称、slug、用途、用户、范围、边界、类型、语言配置、仓库布局、确切的软件包选项、布局预检和渲染目标、目标位置、模板通道、所选引用、记录的确切提交、技能版本、Git 结果、Beads 结果、文档验证、完整的 tooling 和 beads_hooks 状态、待处理的恢复命令，以及下一步的 /plan-features 操作。如果设置流程转到 /update-project，请报告用户的同意决定，且不要声称已运行设置。