GitHub 工作流
本页说明 .github/workflows/ 当前有效的 GitHub Actions，以及它们与仓库文件、包和外部工具的依赖关系。
工作流总览
当前自动化分成三条路径：
v*Tag 触发发布链路，构建 FPK 并发布 GitHub Release。- Pull Request 或手动触发质量链路，检查 SDD、文档、共享包和 harness 插件。
v*Tag 或手动触发文档部署链路，构建并部署 VitePress。
mermaid
flowchart TD
tag["推送 v* Tag"]
releaseWorkflow[".github/workflows/build-release.yml"]
prepare["prepare-release：创建或重置草稿 Release"]
dsh["build-dsh：可复用工作流"]
publish["publish-release：上传完成并生成 Release 说明"]
releaseStatus{"发布链路成功？"}
releaseDone["是：发布 Release"]
releaseFailure["否：report-failure 保留失败草稿"]
tag --> releaseWorkflow --> prepare
prepare --> dsh
dsh --> publish
publish --> releaseStatus
releaseStatus -->|是| releaseDone
releaseStatus -->|否| releaseFailure
prepare -->|失败| releaseFailure
dsh -->|失败| releaseFailure
qualityTrigger["Pull Request / workflow_dispatch"]
sddWorkflow[".github/workflows/sdd-check.yml"]
sddRun["pnpm run check -- --all"]
sddDone["SDD、文档、包和 harness 插件检查完成"]
qualityTrigger --> sddWorkflow --> sddRun --> sddDone
docsTrigger["v* Tag / workflow_dispatch"]
docsWorkflow[".github/workflows/deploy-docs.yml"]
docsRun["pnpm exec fnos-dsh-cli build --docs"]
pages["上传 Pages artifact → 部署 GitHub Pages"]
docsTrigger --> docsWorkflow --> docsRun --> pages两个发布任务的时序
prepare-release 完成后，build-dsh 作为可复用工作流执行；它完成后 publish-release 才会继续。
mermaid
sequenceDiagram
participant github as GitHub Actions
participant prepare as prepare-release<br/>创建或重置草稿 Release
participant dsh as build-dsh<br/>可复用工作流
participant gateway as build:gateway<br/>构建 fnOS Gateway
participant dshBuild as build<br/>构建 Harness FPK + 上传
participant publish as publish-release<br/>等待构建任务
participant notes as pnpm run release:notes<br/>调用 changelogithub
participant release as GitHub Release
github->>prepare: push v* Tag
prepare->>github: release_id
prepare->>dsh: workflow_call(release_tag, release_id)
dsh->>gateway: fnos-dsh-cli build:gateway
gateway->>dsh: Gateway bundle
dsh->>dshBuild: fnos-dsh-cli build --fpk
dshBuild->>dsh: FPK asset uploaded
dsh->>publish: completed
publish->>notes: assets 全部上传后
notes->>release: changelogithub 执行完成
release->>github: 发布 Releasechangelogithub 的执行时机
Release 日志不是在 build-app.yml 中生成的，而是在 build-release.yml 的 publish-release 任务中执行。具体顺序是：
prepare-release创建或重置草稿 Release，并输出release_id。build-dsh构建并上传 Harness FPK。- 构建任务成功后，
publish-release开始发布任务；成功路径不再写入自定义 Releasename/body。 publish-release设置 Node.js / pnpm，安装 CLI 依赖。- 执行
pnpm run release:notes，由fnos-dsh-cli release:notes调用changelogithub，生成并写入完整 Releasename/body。 - Release 日志生成完成后，GitHub Release 才会被发布；失败路径只把诊断信息写入 Actions Summary，并保留草稿。
成功路径不再通过 gh api 写入自定义 Release name 或 body，避免与 changelogithub 的完整更新结果产生覆盖或拼接耦合。失败信息属于运行诊断，写入 $GITHUB_STEP_SUMMARY，不作为 Release 日志内容。
build-app.yml 内部步骤
mermaid
flowchart TD
workflow["build-app.yml"]
checkout["checkout"]
tooling["Node 24 + pnpm 11"]
install["安装 fnos-gateway... 与 CLI 依赖"]
gateway["fnos-dsh-cli build:gateway"]
fnpack["安装 fnpack 1.2.1"]
build["fnos-dsh-cli build --fpk --app fn-deepseek-harness"]
rename["重命名：Tag(项目版本) + catalog 派生 DSH 基线"]
upload["上传 Harness FPK 到 Release"]
status{"上传成功？"}
done["是：构建完成"]
uploadFail["否：重试 5 次后失败"]
workflow --> checkout --> tooling --> install --> gateway --> fnpack
fnpack --> build --> rename --> upload --> status
status -->|是| done
status -->|否| uploadFailbuild-app.yml 只接受 workflow_call，不会自行响应 push；它必须由 build-release.yml 传入 release_tag 和 release_id。
工作流与文件、包的依赖关系
下图只展示运行时真正读取或调用的边界：工作流调用 CLI，CLI 再调用 Turbo、VitePress、fnpack 或包内脚本；应用的 manifest 决定是否进入 FPK 矩阵。
mermaid
flowchart LR
subgraph workflows["GitHub 工作流"]
release[".github/workflows/build-release.yml"]
dsh[".github/workflows/build-app.yml"]
docs[".github/workflows/deploy-docs.yml"]
sdd[".github/workflows/sdd-check.yml"]
end
subgraph repo["仓库入口与配置"]
rootPackage["package.json"]
lockfile["pnpm-lock.yaml"]
turbo["turbo.json"]
docsConfig["docs/.vitepress/config.mts"]
end
subgraph cli["fnos-dsh-cli CLI"]
program["tooling/fnos-dsh-cli/src/program.ts"]
commands["tooling/fnos-dsh-cli/src/commands/*.ts"]
build["build / build:gateway"]
check["check"]
releaseNotes["release:notes"]
end
subgraph packages["Workspace packages"]
gateway["packages/fnos-gateway"]
sharedUi["packages/dsh-semi-ui"]
harnessPlugins["plugins/* harness 插件"]
end
subgraph apps["FPK 应用"]
manifests["apps/*/manifest"]
harnessApp["apps/fn-deepseek-harness"]
end
subgraph tools["外部工具与发布服务"]
fnpack["fnpack 1.2.1（CI）"]
github["GitHub Release / Pages API"]
end
release -->|workflow_call| dsh
release --> releaseNotes
dsh -->|build:gateway + FPK| build
dsh --> gateway
dsh --> harnessApp
dsh --> fnpack
dsh -->|上传 FPK| github
docs -->|--docs| build
docs --> docsConfig
docs -->|Pages| github
sdd -->|--all| check
sdd --> docsConfig
sdd --> rootPackage
sdd --> lockfile
sdd --> harnessPlugins
sdd --> manifests
build --> turbo
build -->|^build| sharedUi
build -->|build:app| gateway
check --> turbo
check --> sharedUi
check --> harnessPlugins
turbo --> sharedUi
turbo --> harnessPlugins各工作流的职责
| 工作流 | 触发方式 | 主要职责 | 关键输入 |
|---|---|---|---|
build-release.yml | 推送 v* Tag | 创建草稿 Release、调用 FPK 构建、发布 Release | github.ref_name、Release ID |
build-app.yml | 仅 workflow_call | 构建 Gateway、构建 Harness FPK | release_tag、release_id |
deploy-docs.yml | v* Tag / 手动 | 构建 VitePress 并部署 GitHub Pages | DOCS_BASE=/ |
sdd-check.yml | Pull Request / 手动 | 执行完整 SDD、文档、包和 harness 插件检查 | 变更路径 |
发布链路
1. 创建版本 Tag
版本命令由根 CLI 执行，项目/FPK 使用 v<版本号> Tag：
bash
pnpm run version -- patch
git push origin main
git push origin v<版本号>2. 构建 DeepSeek Harness FPK
build-app.yml 的顺序不能省略：
- 安装 Gateway 和 FPK 构建依赖。
- 执行
pnpm exec fnos-dsh-cli build --fpk --app fn-deepseek-harness --skip-bundle-dsh-plugins，由构建流程先编译 Gateway，再构建 FPK；node-pty 使用上游 npm 包自带的平台预编译产物，构建阶段不再准备原生产物。 - 按 Release Tag 和 DSH 版本重命名并上传 FPK。
3. 发布 Release
Harness FPK 上传成功后，publish-release 执行根 release:notes：
bash
pnpm run release:notes任一阶段失败时，report-failure 会将阶段状态写回草稿 Release；草稿不会被误发布。
文档与 SDD 链路
文档和 SDD 工作流都会构建 VitePress，因此页面里的 Mermaid 图会一并渲染：
bash
pnpm run build -- --docs
pnpm run check -- --alldeploy-docs.yml构建docs/.vitepress/dist，上传后由deploy-pages发布。sdd-check.yml对 Pull Request 的指定路径执行完整check --all。- 只修改
apps/**时，仍会触发 SDD 工作流，因为它在路径过滤器中；FPK 的真实安装行为还必须在 fnOS 设备上验收。
修改工作流的检查清单
- [ ] 新增或修改触发器后，更新本页的触发条件和总览图。
- [ ] 可复用工作流的输入、输出和
needs关系保持一致。 - [ ] FPK 构建继续通过
fnos-dsh-cli和fnpack，不在工作流中复制 CLI 逻辑。 - [ ] 版本与 fnpack 版本来源保持一致；node-pty 的预编译产物由上游 npm 包提供，不在仓库内固定。
- [ ] 文档或 Mermaid 图改动通过
pnpm run build -- --docs。 - [ ] 提交前运行
pnpm run check -- --all。 - [ ] 不把
.fpk或 GitHub Token 写入仓库。