Portal Workflow

开源社区官网的自动化运维协调仓。接 atomgit 上游 issue,自动跑 需求 → 设计 → 实现 → 自检 → 提 PR 链路,合并后自动关 issue。

集成一条链路:

• self-service(6 stage):普通前端需求/缺陷,跑 requirement → design → implement → built → tested → push-pr

技术全景 + 流程图 + agent 编排见 docs/design.md。

纳管的 portal

权威注册表:packages/shared/portal-registry/portals.yml

alias	display_name	atomgit 仓	官网
openEuler	openEuler 社区官网	openeuler/openEuler-portal	https://www.openeuler.org/
MindSpore	MindSpore 社区官网	mindspore/mindspore-portal	https://www.mindspore.cn/
openGauss	openGauss 社区官网	opengauss/website	https://opengauss.org/
openUBMC	openUBMC 社区官网	openubmc/website	https://www.openubmc.cn/
UnifiedBus	灵衢社区官网	unifiedbus/UnifiedBus-portal	https://www.unifiedbus.com/
HiFloat	HiFloat 社区官网	hifloat/hifloat-portal	https://hifloat.gccorg.com/

用法

1. 在 atomgit 提 issue

社区贡献者直接到对应 portal 的 atomgit 仓提 issue,标题 + 正文写清楚要改什么 + 验收标准。

如果原始 issue 描述比较松散(口语化、需求/缺陷混在一起、缺验收标准),维护者或提交者 可以先评一条 /draft 让流水线自动整理出结构化草案,见下一步。

2. (可选)/draft 草案预演

任何人(只要 atomgit 账号在 accept_users 白名单内)在原 issue 顶格评论 /draft, mirror-issues.yml 15 分钟 cron 扫到 → 派发 draft.yml:

1. 拉 atomgit issue 标题 / 正文 / 评论(自动过滤掉历史草案评论,避免滚雪球)
2. 喂 draft-writer agent → 输出 4 段固定模板(背景 / 期望行为 / 验收标准 / 范围)
3. 把草案回评到原 atomgit issue,带版本 marker <!-- portal-draft v{N} -->

要点:

• 可重复触发:再评一次 /draft 出 v2、v3 …… 版本号自增,旧版评论保留
• 不进主链路:不创建本仓 mirror issue、不打 stage:* label
• 接纳时自动接力:后面评 /accept 走主链路,stage 1 requirement-analyst 会优先读最新版本的 draft 评论作为输入
• 评论署名 w-robot(ATOMGIT_ROBOT_TOKEN),与 commit author 对齐

适合"需求模糊 → 先让 agent 整理一版 → 维护者与提交者基于草案对话校准 → 校准满意后 /accept"的工作流。

3. 维护者接纳

维护者在 atomgit 那条 issue 顶格评论以下命令之一:

• /accept → 走 self-service(6 stage)

命令必须精确单词匹配(strip 空白后等值比较),评论人 atomgit 账号必须在 portals.yml 的 accept_users 白名单。

mirror-issues.yml 15 分钟扫一次(8,23,38,53 * * * *),把接纳的 issue 镜像到本仓 + 触发 对应主链路(/draft 在同一次扫描里被分流到 draft.yml,见上一节)。

3.1 (可选)运营自己提的 PR 拿预览环境

运营自己改 portal 仓代码、提了 PR、想要一个临时预览站。在自己提的 atomgit PR 上(不是 issue) 顶格评论 /preview,流程:

1. mirror cron 扫到 → 派发 community-preview.yml
2. 本仓建一份轻量 GH 协调 issue(打 kind:community-preview label)
3. preview-deploy 通过 refs/pull/N/head 从 base 仓 fetch 代码(fork 仓 / 私有 fork 都支持, bot 不需要访问 fork 仓的权限),k8s 起 vite-dev pod
4. 预览 URL 只评论到本仓 GH 协调 issue,不回评 atomgit PR(预览资源不对外暴露)
5. atomgit PR 合并 / 关闭后 4h cron 自动 cleanup

权限同 /accept:评论人 atomgit 账号需要在对应 portal 的 accept_users 白名单。

4. 看进度

本仓 mirror issue 上有:

• stage:* label:实时反映当前在哪一步(stage:requirement / stage:built / ...)
• progress board 评论:6 / 5 槽位进度板,每个 stage 完成就刷新
• 失败评论:任意 stage 失败 → 评论失败摘要 + 叠加 failed label(保留原 stage:* 便于定位)

5. 重试

按失败评论提示在 mirror issue 评论对应 /retry-<stage>:

• self-service: /retry / /retry-design / /retry-develop / /retry-test / /retry-pr / /retry-preview
• community-preview: /retry-preview(在本仓 GH 协调 issue 上评论,需有 kind:community-preview label)

state.json 持久化已有产物,retry 续跑不重头扫。

6. PR Review意见纳入(/incorporate-review)

PR 建好后,维护者在 atomgit PR 上留行内/一般评审 → 在本仓 mirror issue 评论 /incorporate-review,workflow 会:

1. 拉本轮新评审(基于 last_incorporated_review_at cursor,去掉 bot 评论)
2. 喂给 developer 做窄改 → 同分支 force-push(commit 标题沿用首次 PR 标题,不变)
3. 把"怎么改的"分别回评到 GH mirror issue + atomgit PR
4. Build smoke 复跑(若上一轮已失败则跳过,省 10-15 分钟)

不是 retry,是独立 follow-up 命令;跑完 stage label 仍是 pr-created,只更新轮次 cursor。

7. PR 合并 → 自动关 issue

poll-pr-status.yml 4 小时扫一次 stage:pr-created 的 issue,检测到 atomgit PR 合并就关 issue。

8. 失败 / 被拒后的自优化(/retrospect)

如果 agent 改不成功(某 stage 失败),或维护者觉得改得有问题(留了评审 → /incorporate-review), 流水线不只是"重试同一套 prompt",而是能回溯本次到底哪错了,并把可固化的修复自动提 PR(人工合并):

1. 自动诊断(只读不改):每次失败 / /incorporate-review 后,会自动在 mirror issue 追加一条 根因诊断评论 —— 判断这是一次性抖动(建议 /retry)、流水线提示词缺约束、还是某个 portal 的 项目文档缺一条规则,并给出下一步建议。关掉:仓库 Variables 加 RETROSPECT_AUTO_DISABLE=1。
2. /retrospect(回溯 + 提优化 PR):维护者在 mirror issue 顶格评论 /retrospect, retrospect.yml 收集本次 run 的全部产物作为证据, 让 retrospect-analyst 诊断,并按分类自动开一个只改文档的 PR:
   • 根因在流水线 agent 提示词 / skill(跨 portal 普遍)→ PR 到本仓(GitHub), 改 packages/*/.github/agents/*.md
   • 根因在某 portal 自己的项目文档(这个 portal 特有)→ PR 到该 portal 仓(AtomGit), 改它的 AGENTS.md / rules/*.md
   • 一次性抖动 / 超出自动化范围 / 置信度不足 → 只评论诊断,不提 PR

安全边界:只改文档(*.md)、只创建 PR 绝不自动合并、改动越界一律整体回滚。合并后,后续同类 需求的 agent 会自动遵循新规则 —— 这正是把"踩过的坑"沉淀回项目级文档(ADR-0018 的真理源)的闭环。 详见 docs/design.md#自优化回溯闭环 + ADR-0031。

新增 portal

1. 编辑 packages/shared/portal-registry/portals.yml, 加 alias / display_name / atomgit owner+repo+default_branch / website_url / accept_users
2. 提 PR(本仓),review 合并
3. 合并后 mirror cron 自动覆盖新 portal,无需其它配置

不需要预先告诉 portal-workflow 这个 portal 的框架 / 目录结构 / 构建命令 — agent 进到仓里 自己探(读 package.json scripts、pnpm-workspace.yaml、*.config.{ts,js})。

配置(最小集)

本仓 GitHub Secrets / Variables:

名称	类型	必填	用途
ATOMGIT_TOKEN	secret	✅	atomgit clone / push / PR / 评论(所有 portal 共用)
GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL	variable	✅	commit author(必须是 atomgit 平台已注册账号)
PREVIEW_KUBECONFIG_B64	secret	✅(self-service 用)	k8s 预览部署
AI_MODEL	variable	-	AI 模型名(如 alibaba-cn/glm-5.1),opencode --model 参数,有默认值
AI_AGENT	variable	-	AI Agent 平台名(如 OpenCode),用于 commit Co-Authored-By + PR AI 参与段,有默认值
ATOMGIT_USER_TOKENS	secret	✅(ADR-0032)	accepter token 映射(JSON),用于 fork model 下的 clone/push/PR

完整列表(含可选环境变量、self-hosted runner 依赖)见 docs/design.md#配置参考。

想了解更多

• 技术全景 + 流程图 + agent 编排:docs/design.md
• 架构决策(ADR):docs/decisions.md
• 本地调试 / 仓库结构 / 流水线细节:见 docs/design.md

反馈

提 issue 到本仓。