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.
3.2 KiB
调用形态:先认执行器是哪个 shell(2026-10-26 实测)(自 SKILL.md 外置)
本文由 keil-build 的 SKILL.md「调用形态:先认执行器是哪个 shell(2026-10-26 实测)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。
同一条编译命令,PowerShell 与 bash 是两种写法;ops_bash / run_code 起的是
/usr/bin/bash -c,不认 PowerShell 形态,照抄 skill 正文的 PowerShell 段会直接语法错退出。
| 执行器 | 正确写法(cwd = 仓库根) |
|---|---|
| PowerShell | & '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py |
bash(ops_bash) |
'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py |
- bash 侧去掉前导
&(bash 里&是"丢后台",不是调用操作符)、路径改正斜杠 (\Scripts\python.exe的反斜杠在 bash 是转义,路径根本解析不出来)。 - 实测(step 41→42):把 PowerShell 形态丢进
ops_bash后台任务 → 任务秒退、exit 2,stderr 只有这一行:
/usr/bin/bash: -c: line 1: syntax error near unexpected token `&'
- ⚠ 这个 2 不是脚本的环境错误 2:脚本自己报环境错误会打出
BuildEnvError/ 中文诊断(UV4 找不到、工程找不到、档案解析失败),而语法错连解释器都没启动,MDK-ARM/build_log.txt不会被改写。判据:stderr 含syntax error near unexpected token= 写法问题 → 换 bash 形态重跑,别去查DTU_KEIL_UV4、别当环境错误排障。 - 后台跑(
run_in_background: true)时要自己收码,且别把脚本接进管道:'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py; rc=$?; echo RC=$rc。 实测脚本 | tail -6; echo RC=$?里的$?是tail的退出码(恒 0), 拿它当 PASS/FAIL 会永远"绿";set -o pipefail能透出非零码,但尾巴上挂的grep无匹配时同样报 1,也不可信。要看报错行就单独 grep 日志:grep -a -E 'Error|error:|Warning' MDK-ARM/build_log.txt。
解析顺序(命令行 > 项目档案 .serialtest/config.json > 环境 > 探测):
工程 uvprojx(档案缺省时自动搜 cwd 下唯一 *.uvprojx);UV4 uv4 >
$DSH_KEIL_UV4 > $DTU_KEIL_UV4 > PATH(显式设了但路径无效 = 立即报错,不静默回退)。
退出码:0=PASS(0错0警) / 1=构建失败(打印报错行)/ 2=环境错误(UV4 找不到或
路径无效、工程找不到、档案解析失败)/ 3=用法错误 / 4=build 锁被占用(并发 -b 不可行)。
收到 2 先确认它是脚本打的还是 shell 语法错打的(见上节),再走"环境错误"排障。
2026-10-12 修正:旧实现把环境错误写成
raise SystemExit("...")→ 实际退出码是 1, 而用法错误由 argparse 抛SystemExit(2)→ 恰好占了"环境错误"的位置,于是当时"报 exit 2 = 环境问题"这条经验不成立。现按脚本实际行为改正(现行口径见 skill 正文「退出码数值口径」): 环境错误 → 2(BuildEnvError),用法错误 → 3(覆盖 argparse 的error())。