Files
STM32F4-Base/docs/CI
wandering1 e4981aa2f6 refactor(docs): point entry-file references at their new homes
AGENTS.md stopped being the store of record for build steps, Python env,
hardware pins, doc conventions, log cost and task ownership. Those facts
already live in docs, skills and role files; the entry file now only
points at them. This commit moves every reference that used to name the
entry file to the authoritative landing point, so a reader who follows a
link arrives at the fact instead of at a sentence that no longer exists.

What changed is links and prose, not behaviour. Code, scripts and tests
only have comment and docstring lines touched; the only non-comment edit
in the whole changeset is one note string inside the generated pin table
JSON, and its generator was changed in the same step so the two stay
byte-identical.

New landing points created before the references were retargeted:
- The console single-writer log design doc, section 7.1, is now the single
  authority for log cost: about 90 B flash and 216 B stack per DBG_ line,
  and the rule that deep call chains must predefine DBG_LINE_BUF_MAX.
  It also carries the full list of the twelve translation units that have
  tightened it, plus the grep command that decides the truth if the list
  and the code ever disagree.
- The document writing standard, section 2, now holds the BOM list.
- keil-build skill gains an exit code table: 0 success, 1 build failure,
  2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief
  that was never actually written down anywhere: exit 2 does not simply
  mean environment error, argparse also exits 2 and the wrapper script
  was remapped so the two no longer collide.

Regenerated and checked byte for byte:
- The end-to-end architecture SVG in docs/images from its generator.
- tools/netlist_semantics/pinout_kb.json from gen_kb.py.
Both are idempotent; running the generators again produces no diff.

Deliberately not touched, because machines read them:
- scripts/check_bom_drift.py joins every line containing BOM and asserts
  four paths are present, so the entry file BOM line must stay one line.
- scripts/gen_task_table.py reads the TASK_TABLE anchors directly.
- scripts/rename_maps and scripts/archive keep their historical wording;
  they describe what happened, not what is true now.

Verified: doc links report the same six pre-existing findings as the base
commit and no new ones, generated-fresh passes, bom drift is clean across
101 files, and AGENTS.md itself is unchanged in this commit.
2026-11-16 19:38:27 +08:00
..

远程 CI(Gitea Actions)—— 本目录是唯一入口

适用范围(先读这句,可以省下很多时间) 本仓库的远程 CI 只跑在本机这一台 runner 上:runner 名 win-stm32-ci,装在 D:\Docker\act_runner,连的是本机原生 Gitea http://127.0.0.1:3001。 其他机器、其他项目都不涉及,也不需要配这套东西。

日常改代码不需要读本目录:提交前的等价自查是本地门禁,runner 在不在线都照样跑——

& '.venv\Scripts\python.exe' scripts/ci_local.py     # 静态门禁 + 提交信息门禁 + 主机侧纯逻辑单测

只有在这三种情况下才需要进来:① 换机/重装后要重新部署 runner;② CI 不出任务或莫名 取消;③ 改 .gitea/workflows/ci.yml 本身。

索引

全部内容是一篇文档:远程CI完整指南.md(2026-10-12 由原「环境与部署」 目录下的两篇指南 CI配置指南.md 与 Gitea_Runner部署指南.md 合并而来,两篇均已删除, 去重后为单一来源)。

想干什么 去看
先搞清 CI 需要哪三样东西就位、本机拓扑、部署前置清单 §0 / §0.1 / §0.2
CI 体积门禁现在怎么守(同码凭证强制,「只声明不执行」那处盲区已关闭;gitlint 空转仍在) §0.0 + §7 排障表"钩子条数对不上"行
服务端开启 Actions、DEFAULT_ACTIONS_URL 到底管什么 §1(含 §1.2.1,这条最容易搞反)
下载 / 注册 runner(--instance 用回环、labels 必须精确匹配 runs-on) §2.2
config.yaml 各字段语义(capacity / timeout / labels / 日志目录…) §2.3
常驻:为什么必须看门狗、不能只起 daemon、也不能做成 Windows 服务 §2.4 + §3.0
runner 装什么软件、为什么变量必须对 SYSTEM 可见、机器级 DTU_* §4(§4.1.1~§4.1.3 是三个真坑)
workflow 位置 / 触发 / 内网拉不到 actions/checkout 的三种处置 §5(§5.3 零依赖写法)
两个 job 各自跑哪些步骤、两条 Python 探测链要同序同步 §5.5
端到端验证清单、无网页登录时直查 MySQL 核验 §6 / §6.1
出问题了按症状查表(含 0x41301、1053、72h 被杀、.ps1 无 BOM 乱码…) §7
日常维护(改钩子集 / 改 workflow 后要不要动 runner) §8
一键自检脚本、最小操作清单 TL;DR §9 / §10

常用命令速查

# 本地等价门禁(不依赖 runner,日常用这个)
& '.venv\Scripts\python.exe' scripts/ci_local.py

# runner 体检(四项:计划任务 / 进程 / Gitea 可达 / 机器级变量)—— 须管理员
& '.\scripts\ci_runner_bootstrap.ps1' -Status

# 干跑:只打印将要写入的启动器与任务对象,不落盘不注册(免管理员)
& '.\scripts\ci_runner_bootstrap.ps1' -DryRun

# 部署 / 修复:写机器级 DTU_* + 生成看门狗启动器 + 注册开机计划任务 + 立即启动(须管理员)
& '.\scripts\ci_runner_bootstrap.ps1' -SetEnv -StartNow

⚠️ 上面三条 ci_runner_bootstrap.ps1 是本机运维动作,会改系统计划任务与机器级环境 变量;返回码 0x41301 是"任务正在运行"、next run 为空是开机触发器的正常表现, 都不是故障(详见指南 §3.4)。

✅ 机器侧遗留已清理(2026-10-12):旧方案的 deploy_runner_task.ps1 与 run_runner.cmd 已从 D:\Docker\act_runner\ 删除(它们跑单次 daemon,首次 Declare 失败就永久停摆, 机理见指南 §3.2;check_env.ps1 里指向它们的提示也已改指 bootstrap)。 现行部署只有 ci_runner_bootstrap.ps1 这一条路。

🔴 重跑部署前先知道这条(2026-10-12 实测):Unregister-ScheduledTask 不会带走旧实例 启动的进程。旧看门狗会作为孤儿继续养着它的 daemon,而那个 daemon 占着 .runner.lock, 于是新看门狗每 10 秒失败一次(runner file is already locked by another process)—— 而 runner 在网页上照样显示 online,CI 看着正常,任务其实谁也没管。 现在 -StartNow 会先清掉这些残留进程再启动(约离线几秒),-Status 也会报出重复实例。 2026-10-12 已实测收敛:清掉 3 个残留后 daemon up: pid … (single instance), 监管链 svchost(任务) → 看门狗 → daemon 恢复,runner 回 online。

相关文档