GitHub Workflow
本页说明 .github/workflows/ 当前有效的 GitHub Actions，以及它们与仓库文件、包和外部工具的依赖关系。
Workflow 总览
当前自动化分成三条路径：
v*Tag 触发发布链路，构建 FPK 并发布 GitHub Release。- Pull Request 或手动触发质量链路，检查 SDD、文档和包。
v*Tag 或手动触发文档部署链路，构建并部署 VitePress。
发布 Job 的时序
prepare-release 完成后，build-common 作为可复用 Workflow 执行；它完成后 publish-release 才继续。
changelogithub 的执行时机
Release 日志不是在 build-common-fn.yml 中生成的，而是在 build-release.yml 的 publish-release Job 中执行。具体顺序是：
prepare-release创建或重置草稿 Release，并输出release_id。build-common构建并上传全部 FPK。- 构建 Job 成功后，
publish-release开始发布任务；成功路径不再写入自定义 Releasename/body。 publish-release设置 Node.js / pnpm，安装 CLI 依赖。- 执行
pnpm run release:notes，由fn-apps-cli release:notes调用changelogithub，生成并写入完整 Releasename/body。 - Release 日志生成完成后，GitHub Release 才会被发布；失败路径只把诊断信息写入 Actions Summary，并保留草稿。
成功路径不再通过 gh api 写入自定义 Release name 或 body，避免与 changelogithub 的完整更新结果产生覆盖或拼接耦合。失败信息属于运行诊断，写入 $GITHUB_STEP_SUMMARY，不作为 Release 日志内容。
build-common-fn.yml 内部步骤
build-common-fn.yml 只接受 workflow_call，不会自行响应 push；它必须由 build-release.yml 传入 release_tag 和 release_id。
Workflow 与文件、包的依赖关系
下图只展示运行时真正读取或调用的边界：Workflow 调用 CLI，CLI 再调用 Turbo、VitePress 或 fnpack；应用的 manifest 决定是否进入 FPK 矩阵。
各 Workflow 的职责
| Workflow | 触发方式 | 主要职责 | 关键输入 |
|---|---|---|---|
build-release.yml | 推送 v* Tag | 创建草稿 Release、调用 FPK 构建、发布 Release | github.ref_name、Release ID |
build-common-fn.yml | 仅 workflow_call | 扫描应用并按矩阵构建、重命名、上传 FPK | release_tag、release_id |
deploy-docs.yml | v* Tag / 手动 | 构建 VitePress 并部署 GitHub Pages | DOCS_BASE=/ |
sdd-check.yml | Pull Request / 手动 | 执行完整 SDD、文档和包检查 | 变更路径 |
发布链路
1. 创建版本 Tag
版本命令由根 CLI 执行，项目/FPK 使用 v<版本号> Tag：
pnpm run version -- patch
git push origin main
git push origin v<版本号>2. 构建 FPK
build-common-fn.yml 扫描 apps/*，只保留包含 manifest 的目录，然后为每个应用创建独立矩阵任务：
pnpm exec fn-apps-cli build --fpk --app <app-name>3. 发布 Release
FPK 都上传成功后，publish-release 执行根 release:notes：
pnpm run release:notes任一阶段失败时，report-failure 会将阶段状态写回草稿 Release；草稿不会被误发布。
文档与 SDD 链路
文档和 SDD Workflow 都不需要额外安装图形工具：Mermaid 图由插件在浏览器端渲染。
pnpm run build -- --docs
pnpm run check -- --alldeploy-docs.yml构建docs/.vitepress/dist，上传后由deploy-pages发布。sdd-check.yml对 Pull Request 的指定路径执行完整check --all。- 只修改应用时，仍会触发 SDD Workflow，因为
apps/**在路径过滤器中；FPK 的真实安装行为还必须在 fnOS 设备上验收。
修改 Workflow 的检查清单
- [ ] 新增或修改触发器后，更新本页的触发条件和总览图。
- [ ] 可复用 Workflow 的输入、输出和
needs关系保持一致。 - [ ] FPK 构建继续通过
fn-apps-cli和fnpack，不在 Workflow 中复制 CLI 逻辑。 - [ ] 版本和 fnpack 版本来源与配置文件保持一致。
- [ ] 文档或流程图改动通过
pnpm run build -- --docs。 - [ ] 提交前运行
pnpm run check -- --all。 - [ ] 不把
.fpk、native 临时目录或 GitHub Token 写入仓库。