apple-swift-package-bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple Swift Package Bootstrap

Apple Swift Package 引导初始化工具

Purpose

用途

Create a new Swift package repository with one top-level entry point and a simplicity-first Swift baseline.

scripts/run_workflow.py

is the runtime wrapper, and

scripts/bootstrap_swift_package.sh

remains the implementation core for scaffold creation and validation.

创建带有单一顶层入口、遵循简约优先Swift基线的新Swift包代码仓库。

scripts/run_workflow.py

是运行时封装脚本，

scripts/bootstrap_swift_package.sh

是脚手架创建和校验的核心实现。

When To Use

适用场景

Use this skill for new Swift package scaffolding.
Use this skill when the user wants consistent package defaults,
```
AGENTS.md
```
generation, and immediate validation.
Use this skill when the user wants to customize the documented bootstrap defaults for future runs.
Do not use this skill as the default path for normal Xcode app collaboration work.
Recommend
```
apple-xcode-workflow
```
when the user is working in an existing Xcode project or needs Apple-platform execution after bootstrap.
Recommend
```
apple-dash-docsets
```
when the user needs Dash docset search, install, or generation work.

为新Swift包搭建脚手架时使用本工具
当用户需要一致的包默认配置、
```
AGENTS.md
```
生成和即时校验能力时使用本工具
当用户需要自定义引导默认配置用于后续运行时使用本工具
请勿将本工具作为常规Xcode应用协作工作的默认流程
当用户在现有Xcode项目中工作，或引导初始化后需要Apple平台执行能力时，推荐使用
```
apple-xcode-workflow
```
当用户需要Dash文档集的搜索、安装或生成工作时，推荐使用
```
apple-dash-docsets
```

Single-Path Workflow

单路径工作流

Collect the required inputs:

```
name
```
```
type
```
```
destination
```
```
platform
```
```
version_profile
```
optional
```
testing_mode
```
optional
```
skip_validation
```

Normalize aliases exactly as

scripts/bootstrap_swift_package.sh

does:

```
macos -> mac
```
```
ios -> mobile
```
```
both -> multiplatform
```
```
latest -> latest-major
```
```
minus-one -> current-minus-one
```
```
minus-two -> current-minus-two
```

Run
```
scripts/run_workflow.py
```
so documented defaults are loaded from customization state and normalized into one JSON contract.
Select testing mode before scaffold creation:
- require a supported and validated
```
Swift 5.10+
```
  toolchain floor before bootstrap planning continues
- prefer
```
swift-testing
```
  on supported current toolchains
- use
```
xctest
```
  when explicitly requested or when the supported toolchain requires it
- stop with
```
blocked
```
  when the local toolchain is older than
```
5.10
```
  or when the local
```
swift package init
```
  command cannot select the requested testing mode

Let the wrapper invoke the bundled script:

bash

scripts/bootstrap_swift_package.sh --name <Name> --type <library|executable|tool> --destination <dir> --platform <mac|macos|mobile|ios|multiplatform|both> --version-profile <latest-major|current-minus-one|current-minus-two|latest|minus-one|minus-two> --testing-mode <swift-testing|xctest>

Verify the generated repository:

```
Package.swift
```
```
.git
```
```
AGENTS.md
```
```
Tests/
```
```
swift build
```
and
```
swift test
```
unless
```
--skip-validation
```
was requested

Ensure the generated guidance encodes the shared Swift policy:
- apply the detailed local policy in
```
references/snippets/apple-swift-core.md
```
- keep the generated repo aligned with the simplicity-first, shape-preserving, and anti-ceremony Swift guidance in that snippet
- preserve the project-appropriate logging, telemetry, and SwiftUI architecture guidance from that snippet
Hand off package execution guidance cleanly:
- use
```
swift build
```
  and
```
swift test
```
  by default
- recommend
```
apple-xcode-workflow
```
  for package builds that need Xcode-managed toolchain behavior, such as package builds that depend on Xcode-provided Metal or other Apple-managed build assets
Return one JSON execution summary with the created path, normalized options, and validation result.

收集必填输入项：

```
name
```
```
type
```
```
destination
```
```
platform
```
```
version_profile
```
可选
```
testing_mode
```
可选
```
skip_validation
```

完全按照

scripts/bootstrap_swift_package.sh

的规则对别名进行标准化：

```
macos -> mac
```
```
ios -> mobile
```
```
both -> multiplatform
```
```
latest -> latest-major
```
```
minus-one -> current-minus-one
```
```
minus-two -> current-minus-two
```

运行
```
scripts/run_workflow.py
```
，从自定义配置中加载已记录的默认值并标准化为统一JSON契约
在创建脚手架前选择测试模式：
- 继续引导流程前要求本地安装了支持且校验通过的
```
Swift 5.10+
```
  工具链最低版本
- 在支持的当前工具链上优先使用
```
swift-testing
```
- 当用户明确要求或当前工具链要求时使用
```
xctest
```
- 当本地工具链版本低于
```
5.10
```
  或本地
```
swift package init
```
  命令无法选择请求的测试模式时，返回
```
blocked
```
  状态终止流程

由封装脚本调用捆绑的执行脚本：

bash

scripts/bootstrap_swift_package.sh --name <Name> --type <library|executable|tool> --destination <dir> --platform <mac|macos|mobile|ios|multiplatform|both> --version-profile <latest-major|current-minus-one|current-minus-two|latest|minus-one|minus-two> --testing-mode <swift-testing|xctest>

校验生成的代码仓库：
- ```
Package.swift
```
- ```
.git
```
- ```
AGENTS.md
```
- ```
Tests/
```
- 除非指定了
```
--skip-validation
```
  参数，否则执行
```
swift build
```
  和
```
swift test
```
  校验
确保生成的指南符合通用Swift规范：
- 应用
```
references/snippets/apple-swift-core.md
```
  中的详细本地规范
- 保持生成的仓库符合该代码片段中简约优先、结构保留、减少冗余流程的Swift指南
- 保留该代码片段中适配项目的日志、遥测和SwiftUI架构指南
清晰交接包执行指南：
- 默认使用
```
swift build
```
  和
```
swift test
```
- 当包构建需要Xcode管理的工具链能力时，比如依赖Xcode提供的Metal或其他Apple管理的构建资产的包构建，推荐使用
```
apple-xcode-workflow
```
返回包含创建路径、标准化参数和校验结果的JSON执行摘要

Inputs

输入参数

```
name
```
: required; must start with a letter and contain only letters, numbers,
```
_
```
, or
```
-
```
.
```
type
```
:
```
library
```
,
```
executable
```
, or advanced explicit
```
tool
```
.
```
destination
```
: parent directory for the new package.
```
platform
```
:
```
mac
```
,
```
mobile
```
, or
```
multiplatform
```
, with aliases normalized by the script.

version_profile

latest-major

current-minus-one

, or

current-minus-two

, with aliases normalized by the script.

```
testing_mode
```
:
```
swift-testing
```
or
```
xctest
```
.
```
skip_validation
```
: optional flag to skip
```
swift build
```
and
```
swift test
```
.
```
dry_run
```
: optional flag to resolve defaults and emit the normalized command contract without creating files.
Defaults:
- runtime entrypoint: executable
```
scripts/run_workflow.py
```
- ```
type
```
  defaults to
```
library
```
- ```
destination
```
  defaults to
```
.
```
- ```
platform
```
  defaults to
```
multiplatform
```
- ```
version_profile
```
  defaults to
```
current-minus-one
```
- ```
testing_mode
```
  defaults to
```
swift-testing
```
- validation runs unless
```
--skip-validation
```
  is passed
- supported and validated Swift toolchain floor is
```
5.10+
```

```
name
```
: 必填；必须以字母开头，仅包含字母、数字、
```
_
```
或
```
-
```
```
type
```
:
```
library
```
、
```
executable
```
或高级显式类型
```
tool
```
```
destination
```
: 新包的父目录
```
platform
```
:
```
mac
```
、
```
mobile
```
或
```
multiplatform
```
，别名由脚本自动标准化

version_profile

latest-major

、

current-minus-one

或

current-minus-two

，别名由脚本自动标准化

```
testing_mode
```
:
```
swift-testing
```
或
```
xctest
```
```
skip_validation
```
: 可选标记，跳过
```
swift build
```
和
```
swift test
```
校验
```
dry_run
```
: 可选标记，仅解析默认值并输出标准化命令契约，不创建实际文件
默认值：
- 运行时入口：可执行文件
```
scripts/run_workflow.py
```
- ```
type
```
  默认值为
```
library
```
- ```
destination
```
  默认值为
```
.
```
- ```
platform
```
  默认值为
```
multiplatform
```
- ```
version_profile
```
  默认值为
```
current-minus-one
```
- ```
testing_mode
```
  默认值为
```
swift-testing
```
- 除非传入
```
--skip-validation
```
  参数，否则默认执行校验
- 支持且校验通过的Swift工具链最低版本为
```
5.10+
```

Outputs

输出参数

```
status
```
- ```
success
```
  : the package was created and verification succeeded
- ```
blocked
```
  : prerequisites, unsupported toolchains, unsupported testing-mode selections, or target-directory constraints prevented the run
- ```
failed
```
  : the script started but did not complete successfully
```
path_type
```
- ```
primary
```
  : the bundled script completed successfully
- ```
fallback
```
  : manual scaffold guidance is being used instead of the bundled script
```
output
```
- resolved package path
- normalized inputs
- validation result
- one concise next step

```
status
```
- ```
success
```
  : 包创建完成且校验通过
- ```
blocked
```
  : 前置依赖缺失、不支持的工具链、不支持的测试模式选择或目标目录约束导致流程无法运行
- ```
failed
```
  : 脚本已启动但未成功完成
```
path_type
```
- ```
primary
```
  : 捆绑脚本执行成功
- ```
fallback
```
  : 未使用捆绑脚本，使用手动脚手架指南
```
output
```
- 解析后的包路径
- 标准化后的输入参数
- 校验结果
- 简洁的下一步操作建议

Guards and Stop Conditions

拦截与终止条件

Stop with
```
blocked
```
if
```
swift
```
is missing.
Stop with
```
blocked
```
if
```
swift --version
```
cannot be parsed into a supported toolchain version.
Stop with
```
blocked
```
if the local Swift toolchain is older than
```
5.10
```
.
Stop with
```
blocked
```
if
```
git
```
is missing.
Stop with
```
blocked
```
if
```
assets/AGENTS.md
```
is missing.
Stop with
```
blocked
```
if the target exists and contains non-ignorable files.
Stop with
```
blocked
```
if
```
name
```
is missing.
Stop with
```
blocked
```
if the requested testing mode cannot be honored by the active
```
swift package init
```
command.

如果缺失
```
swift
```
命令，返回
```
blocked
```
终止流程
如果
```
swift --version
```
的输出无法解析为支持的工具链版本，返回
```
blocked
```
终止流程
如果本地Swift工具链版本低于
```
5.10
```
，返回
```
blocked
```
终止流程
如果缺失
```
git
```
命令，返回
```
blocked
```
终止流程
如果缺失
```
assets/AGENTS.md
```
文件，返回
```
blocked
```
终止流程
如果目标路径已存在且包含不可忽略的文件，返回
```
blocked
```
终止流程
如果缺失
```
name
```
参数，返回
```
blocked
```
终止流程
如果当前
```
swift package init
```
命令不支持请求的测试模式，返回
```
blocked
```
终止流程

Fallbacks and Handoffs

降级方案与流程交接

Preferred path is always
```
scripts/bootstrap_swift_package.sh
```
.
Use manual
```
swift package init
```
guidance only when the script is unavailable or the user explicitly asks for the manual path.
```
tool
```
is an advanced explicit passthrough, not a default branch of the workflow.
After a successful scaffold, hand off build, test, or Xcode-managed package execution tasks to
```
apple-xcode-workflow
```
.
For ordinary package work, prefer
```
swift build
```
and
```
swift test
```
.
For package builds that need Xcode-managed SDK or toolchain behavior, use
```
apple-xcode-workflow
```
and
```
xcodebuild
```
guidance instead of stretching the bootstrap skill into an execution skill.
Recommend
```
apple-dash-docsets
```
directly when the user’s next step is Dash docset or cheatsheet management.
```
scripts/run_workflow.py
```
is the top-level runtime entrypoint and converts the shell script result into the documented JSON contract.

优先执行路径始终为
```
scripts/bootstrap_swift_package.sh
```
仅当脚本不可用或用户明确要求手动流程时，使用手动
```
swift package init
```
指南
```
tool
```
是高级显式透传类型，不是工作流的默认分支
脚手架创建成功后，将构建、测试或Xcode管理的包执行任务交接给
```
apple-xcode-workflow
```
常规包开发工作优先使用
```
swift build
```
和
```
swift test
```
对于需要Xcode管理的SDK或工具链能力的包构建，使用
```
apple-xcode-workflow
```
和
```
xcodebuild
```
指南，不要将本引导工具扩展为执行工具
当用户的下一步操作是Dash文档集或速查表管理时，直接推荐
```
apple-dash-docsets
```
```
scripts/run_workflow.py
```
是顶层运行时入口，将Shell脚本的执行结果转换为已定义的JSON契约

Customization

自定义配置

Use
```
references/customization-flow.md
```
.
```
scripts/customization_config.py
```
stores and reports customization state.
```
scripts/run_workflow.py
```
loads runtime-safe defaults from customization state before invoking the shell script.

scripts/bootstrap_swift_package.sh

now honors the wrapper's git and

AGENTS.md

copy flags.

参考
```
references/customization-flow.md
```
```
scripts/customization_config.py
```
用于存储和查询自定义配置状态
```
scripts/run_workflow.py
```
在调用Shell脚本前从自定义配置中加载运行时安全的默认值
```
scripts/bootstrap_swift_package.sh
```
现在支持封装脚本传入的git和
```
AGENTS.md
```
复制标记

References

参考资料

Workflow References

工作流参考

```
references/package-types.md
```

```
references/package-types.md
```

Contract References

契约参考

```
references/automation-prompts.md
```
```
references/customization-flow.md
```

```
references/automation-prompts.md
```
```
references/customization-flow.md
```

Support References

支持参考

Recommend
```
references/snippets/apple-swift-core.md
```
when the new package repo should start with reusable Apple and Swift baseline policy content next to the generated
```
AGENTS.md
```
.
```
assets/AGENTS.md
```
```
references/snippets/apple-swift-core.md
```

当新包仓库需要在生成的
```
AGENTS.md
```
旁添加可复用的Apple和Swift基线规范内容时，推荐参考
```
references/snippets/apple-swift-core.md
```
```
assets/AGENTS.md
```
```
references/snippets/apple-swift-core.md
```

Script Inventory

脚本清单

```
scripts/run_workflow.py
```
```
scripts/bootstrap_swift_package.sh
```
```
scripts/customization_config.py
```

```
scripts/run_workflow.py
```
```
scripts/bootstrap_swift_package.sh
```
```
scripts/customization_config.py
```