工程化：建立 GitHub CI 与仓库展示基线

[ZZDR1023]

背景

仓库已公开并完成 v0.1-alpha 本地纵向闭环，但 GitHub 端尚没有持续集成，README 无构建状态徽章，当前简版许可证文本被 GitHub 识别为 Other，Topics 也未配置。这会降低外部审阅、简历展示和后续发布的可信度。

目标

建立最小但可执行的 GitHub 工程化基线，让每次 PR/推送都能在目标运行时验证 TypeScript、Python、端到端 smoke 与 standalone 导出复现，并让仓库元数据准确展示。

范围

• 新增 GitHub Actions CI，目标环境：Node.js 24、Python 3.11。
• CI 使用 npm ci，执行 npm run check、npm run build、npm run smoke。
• CI 从 smoke 结果定位 project.zip，解压到独立临时目录并运行包内 python3 reproduce.py；断言 9/9 tasks、40 artifacts、PDF 和无 warning。
• 缓存 npm 依赖，但不缓存或上传 secrets、runs 数据库或用户数据。
• 把 LICENSE 替换为完整、标准的 Apache License 2.0 文本，使 GitHub 可识别 SPDX 许可证。
• README 添加 CI badge，并保持 Alpha 能力边界和限制不被夸大。
• 配置仓库 Topics：mathematical-modeling、ai-agent、reproducible-research、evidence-graph、typescript、python、machine-learning、optimization、time-series。

TDD / 可执行验收

先增加一个不依赖 GitHub runner 的静态契约测试，读取 workflow、README 和 LICENSE，并在变更前因文件/规则缺失而失败。该测试至少断言：

1. workflow 固定 Node 24 与 Python 3.11；
2. 使用 npm ci，执行 check/build/smoke 与 standalone python3 reproduce.py；
3. workflow 权限最小化、无 secrets 输出；
4. README badge 指向仓库 workflow；
5. LICENSE 是完整 Apache-2.0 标准文本。

实现后执行：

npm run check
npm run build
npm run smoke

PR 创建后由主控独立等待 GitHub Actions checks，并复核仓库 License 识别、Topics 与分支保护可用性。

非目标

• 不发布 Release。
• 不做历史题 Benchmark。
• 不修改建模算法、Schema、Orchestrator 或运行时功能。
• 不在 CI 中做依赖外网研究、Docker Hub build 或真实 Pi 模型调用。

人工验收入口

打开仓库首页和 PR：确认 CI 徽章可点击、Actions 绿色、License 显示 Apache-2.0、Topics 正确；再从 Actions 日志确认 standalone reproduction 返回 status=success。

[ZZDR1023]

开始实施。

• Orca Run：run_82dfa4f30cdd
• worktree：将由 Orca 从默认主分支创建 issue-1-github-ci
• 唯一写入者：Pi worker；理由是本任务包含 workflow、测试、README 与许可证的跨文件契约，需要独立实现并由主控复核
• 实现计划：先新增静态仓库工程化契约测试形成 Red；再添加 Node 24 / Python 3.11 GitHub Actions，补完整 Apache-2.0 License 与 README badge；worker 推送任务分支并创建目标为 main 的 PR
• Red 测试：读取 .github/workflows/ci.yml、README.md、LICENSE，验证 runtime 版本、npm ci、check/build/smoke、standalone reproduction、最小权限、badge 和完整许可证文本；初始失败必须来自这些契约缺失
• PR 目标分支：main
• CI 验收：GitHub Actions 必须完成 TypeScript/Python tests、build、smoke 和解压后 standalone reproduction；主控还会独立复跑并检查 Actions 日志
• 人工验收入口：仓库首页、PR checks 和 Actions run；预期 badge 绿色、License 为 Apache-2.0、Topics 正确
• 非目标：Release、Benchmark、Docker Hub build、真实 Pi 调用、建模算法和 Schema 修改

[ZZDR1023]

Orca 派发已建立：

• Run：run_82dfa4f30cdd
• Task：task_c8b773eda1e0
• Dispatch：ctx_33c1e92ce8ac
• worktree：/home/zzdr1023/orca/workspaces/modeling-agent/issue-1-github-ci
• 分支/worktree 均从默认主分支创建；唯一写入者为 Pi worker

当前阶段：能力预检与 Red 测试。worker 完成后会推送任务分支、创建目标为 main 的 PR，再由主控独立复测并等待 GitHub Actions。

[ZZDR1023]

CI / 主控复核：退回

最终提交 7a1decf0145b3eb503466718571d3e2955bb40ab 的两次 GitHub Actions 均为 Green，主控独立执行 npm run check、npm run build 和硬门槛也通过；完整 Apache-2.0 文本已被 GitHub License API 在 PR ref 上识别为 Apache-2.0，Topics 已正确配置。

但代码尚不能判定合格，必须修复以下语义缺陷：

1. Actions runner 没有 XeLaTeX，日志明确显示主 smoke 使用 builtin renderer，并记录 xelatex_unavailable；随后 standalone reproduce 却返回 report_renderer=builtin, warning=null。
2. 这是因为本 PR 修改 python/standalone_reproduce.py，把“XeLaTeX 不可用”的 warning 静默删除，仅为满足 CI 的 warning is None 断言。
3. 这与导出 README 中“fallback 会记录 warning”及仓库“不静默降级”的固定契约冲突。CI 应验证诚实状态，而不是改变产品状态来刷绿。
4. workflow 目前同时对任意 push 和 pull_request 运行，feature 分支的同一提交产生两个重复 verify run；应限定为 push 到 main 加所有 PR。

必须补的回归测试：

• 恢复 XeLaTeX 不存在时的非空 warning；XeLaTeX 执行失败也保留非空 warning。
• standalone 验收按 renderer 判断：xelatex => warning=null；builtin => warning 必须明确包含 XeLaTeX unavailable/failure 和 fallback 信息。
• 最好增加一个不依赖主机是否装有 XeLaTeX 的确定性测试，模拟 shutil.which("xelatex") 返回空值。
• workflow 契约断言 push.branches=[main] 与 pull_request，防止重复运行。

旧 Dispatch 已完成，将按仓库规范创建新的回归 Task/Dispatch，派回同一 PR worktree。主控不会直接修改分支。

[ZZDR1023]

主控补充复核：需消除已弃用 Action runtime

回归提交 e44fca4bb590b75ac141d258befb1c91cdbdc834 的功能和诚实告警语义已通过，且只产生一个 PR Actions run。

但 Actions 日志仍给出平台级 warning：actions/checkout@v4、actions/setup-node@v4、actions/setup-python@v5 均使用已弃用的 Node 20 runtime，被平台强制切换到 Node 24。GitHub 官方现已发布原生 node24 的：

• actions/checkout@v7
• actions/setup-node@v7
• actions/setup-python@v7

将创建一个极窄回归 Task，只升级这三个 major、更新结构契约测试并确认 Actions 日志不再出现该弃用 annotation。其余功能和 PR 范围不变。

[ZZDR1023]

Green / PR / CI 主控复核通过

• PR：ci: establish GitHub verification baseline #2
• 最终提交：2ad5794d3570b2a3749a15524ad00699f4a9f2da
• 分支：ZZDR1023/issue-1-github-ci → main
• Orca Run：run_82dfa4f30cdd
• 初始 Task/Dispatch：task_c8b773eda1e0 / ctx_33c1e92ce8ac
• 告警回归 Task/Dispatch：task_629cccf3f631 / ctx_06dbc1a0b670
• Actions v7 回归 Task/Dispatch：task_4d9279125beb / ctx_123d4962ceac

Red / 回归证据

1. 初始静态契约测试因 workflow、badge 与完整许可证缺失而 Red。
2. 首轮 GitHub runner 暴露 Python 版本硬编码测试缺陷，修为验证实际冻结版本格式。
3. 主控发现 standalone 为通过 warning=null 静默吞掉 XeLaTeX 缺失；已退回并增加确定性 unavailable/failure 回归测试。
4. 主控发现旧版官方 Actions 使用已弃用 Node 20 runtime；已退回升级为原生 Node 24 的 v7。

最终自动化证据

• npm ci：在远端分支的全新 clone 中通过。
• npm run check：7 个 Vitest 文件 / 14 个测试、7 个 Python unittest 全部通过。
• npm run build：通过。
• npm run smoke：9/9 tasks、54 evidence nodes、XeLaTeX PDF 成功。
• 独立解压复现（XeLaTeX 可用）：9 tasks、40 artifacts、renderer=xelatex、warning=null、有效 PDF。
• 独立解压复现（人为隐藏 XeLaTeX）：9 tasks、40 artifacts、renderer=builtin、明确非空 fallback warning、有效 PDF。
• GitHub Actions：https://github.com/ZZDR1023/modeling-agent/actions/runs/31619728372
  • 事件：仅 pull_request，无 feature push 重复运行。
  • 结果：Success；annotations = 0。
  • actions/checkout@v7、setup-node@v7、setup-python@v7 均为原生 Node 24 runtime。
  • Python：3.11.15；业务 Node：24。
• GitHub License API 在 PR ref 识别为 Apache-2.0。
• Topics 已配置 9 个。
• main 分支保护已启用：必须经 PR、分支保持最新、verify 必须通过、禁止 force push/delete、要求线性历史和对话解决。

实际页面复核

通过 Orca 内建浏览器验证：

• PR 页面显示目标 main、3 commits、1 条绿色 Check、9 个变更文件；
• Actions 页面显示 Status: Success、on: pull_request、verify 完成；
• 分支首页显示 CI badge、Topics 和成功状态；
• LICENSE 页面显示完整 Apache License 2.0 文本。

代码与自动化验证通过，进入人类验收；PR 目前保持开放且未合并。

[ZZDR1023]

待验收

入口

• PR：ci: establish GitHub verification baseline #2
• Actions：https://github.com/ZZDR1023/modeling-agent/actions/runs/31619728372
• PR 分支首页：https://github.com/ZZDR1023/modeling-agent/tree/ZZDR1023/issue-1-github-ci
• License：https://github.com/ZZDR1023/modeling-agent/blob/ZZDR1023/issue-1-github-ci/LICENSE

权限前提

无需登录即可只读查看；合并需要仓库管理员权限。

验收步骤与预期

1. 打开 PR ci: establish GitHub verification baseline #2：应显示 Open，目标为 main，并且 verify 为绿色。
2. 打开 PR 分支首页：README 标题下应显示 CI 徽章；右侧应显示 9 个 Topics。
3. 点击 CI 徽章或 Actions 链接：run #31619728372 应显示 Success，只有一个 verify job。
4. 打开 LICENSE：应以 Apache License / Version 2.0, January 2004 开头，并包含完整 Sections 1–9。
5. 查看 Files changed：应为 CI、许可证、README、workflow contract/fallback tests 和必要的锁文件变更，没有建模算法或 Schema 变更。

成功判定

以上五项均符合即可回复“验收通过”。收到确认后，主控将 squash merge PR、同步本地 main、确认 main 上 CI/License/badge/Topics，再关闭 Issue #1。

失败回报

请回复失败步骤、页面 URL 和看到的现象；如方便可附截图。主控会保留 PR，并创建新的回归 Task/Dispatch。

清理与回滚

本阶段无需测试数据清理。PR 尚未合并；如验收失败，默认回滚方式是继续修复 PR 分支，而不是改动 main。分支保护和 Topics 可通过仓库 Settings/API 恢复。

[ZZDR1023]

人验收反馈：需要调整

用户反馈：

1. 不清楚 README 顶部 CI 徽章的含义；
2. README 面向中文简历展示，应以中文为主要语言。

处理决定：保留当前 CI、License、Topics 和分支保护实现；创建新的回归 Task/Dispatch，派回 PR #2 的原 worktree。README 将整体翻译为中文，代码块、命令、文件名、接口名和必要英文技术术语保持原样，并在徽章附近用中文解释：绿色表示自动检查通过，红色表示失败，点击可查看 GitHub Actions 日志。

必须新增/更新静态契约测试，确保后续不会又退回全英文 README。PR 继续保持未合并。

[ZZDR1023]

README 中文化回归：主控复核通过

• 提交：e8de283bb982ec99b57b040b86048600e91398d5
• PR：ci: establish GitHub verification baseline #2
• Actions：https://github.com/ZZDR1023/modeling-agent/actions/runs/31622761597

变更结果

• README 的说明性正文、章节标题和任务类型已改为简体中文；代码块、命令、路径和必要技术名词保持原样。
• CI 徽章下方新增中文说明：绿色 / passing 表示自动测试与构建通过，红色 / failing 表示失败，点击可查看 GitHub Actions 日志；同时明确徽章是动态状态，并不保证始终绿色。
• 保留了 Alpha 非成熟/非获奖级声明、9 类任务、架构、命令、Docker/standalone 契约、安全边界、Evidence Graph 要求和材料版权说明。
• 新增契约测试：要求 500 个以上中文字符，且非代码说明中的中文字符占比超过 60%；当前独立计算约为 71.5%。

独立验证

• 全新远端 clone + npm ci：通过。
• npm run check：7 个 Vitest 文件 / 15 个测试、7 个 Python 测试通过。
• npm run build：通过。
• npm run smoke：通过。
• GitHub Actions：Green。
• GitHub 实际分支页面已确认：中文 README 正常渲染、CI 徽章可见、中文解释紧邻显示。

代码与自动化验证重新通过，进入人类验收；PR 仍保持开放且未合并。