merge: 技能主文件拆分与 IEC104 探针入库
This commit is contained in:
+20
-3
@@ -41,10 +41,11 @@ spawn_teammate({
|
||||
| `build-gatekeeper` | 构建与门禁验证 | Keil 构建、pre-commit 门禁、CI 本地自查诊断 | 只读:`ops_grep`/`ops_glob`/`ops_inspect_local_file`(无 `edit`/`write`) |
|
||||
| `bench-runner` | 台架执行与取证 | 执行烧录/复位/回读、串口抓日志、标记校验、板端 UI 导航;**只操作取证,不判定** | 只读文件 + `ops_bash`(无 `edit`/`write`,无 gate 提交权) |
|
||||
| `doc-writer` | 技术文档写手 | 技术文档编写维护、链接有效性、计数准确性 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` |
|
||||
| `skill-custodian` | 技能处理者 | 审核、创建、改进 `.dsh/skills/` 下的技能;主文件只留默认路径、长尾进 reference | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` |
|
||||
|
||||
> **关于工具调用预算**:角色文件 frontmatter 里都写了 `maxToolCalls`,但该预算**只对 `subagent_role` 路径生效**,对 `spawn_teammate` 起的 teammate 不起约束(插件 `lib/budget.js` 的 `arm()` 只由委派工具调用,team 路径不挂账)。所以本表不再列预算列,免得被当成上限承诺。缺口与后续补齐口径 → `.dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md` §1.1。
|
||||
|
||||
> **关于模型**:角色文件 frontmatter **支持** `provider`/`model`/`reasoningEffort` 三个字段,但同样**只有 `subagent_role` 路径会读**。`spawn_teammate` 起的 teammate 一律跑在宿主默认模型上(本机 profile 的 `agent-default-model` = `workbuddy` / `deepseek-v4.1-flash`),与角色无关。当前 11 个角色文件都没写这三个字段,全部继承宿主默认。要给某个成员换模型用 `team_member_revive({ target, provider, model })`(活体立即生效,冷会话挂起到复活瞬间)。机制与两条改造路径 → `.dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md` §1.2。
|
||||
> **关于模型**:角色文件 frontmatter **支持** `provider`/`model`/`reasoningEffort` 三个字段,但同样**只有 `subagent_role` 路径会读**。`spawn_teammate` 起的 teammate 一律跑在宿主默认模型上(本机 profile 的 `agent-default-model` = `workbuddy` / `deepseek-v4.1-flash`),与角色无关。当前 12 个角色文件都没写这三个字段,全部继承宿主默认。要给某个成员换模型用 `team_member_revive({ target, provider, model })`(活体立即生效,冷会话挂起到复活瞬间)。机制与两条改造路径 → `.dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md` §1.2。
|
||||
|
||||
## 角色详细说明
|
||||
|
||||
@@ -54,7 +55,7 @@ spawn_teammate({
|
||||
|
||||
**第一部分(通用方法论)**:Lead 的职责边界 · 何时用团队何时自己干(三条可操作判据 + 三种不该开团队的情况)· 任务描述四要素(目标/验收口径/约束/交付方式,缺一退回)· 三层分离(操作/采集/判定,执行者不自验)· 验收人 ≠ 执行人的四个适用面(代码/文档/判据本身/单向规则)· 返工处理(说清哪条没过 + 最小修正方向 + 重新提交的证据要求)· 上下文经济(什么自己读、什么让别人读完只报结论,判据是"我要能拿这句话去复跑")· 12 条反模式表。
|
||||
|
||||
**第二部分(项目专项)**:11 个角色的分工与派活边界表(负责什么/不碰什么/何时派它)· 委派协议(`@role:<id>` 首行绑定、一律 fresh 不用 fork、写域声明、门禁流程、重启恢复)· 门禁插件实际状态 · 10 条实测硬约束(插件保证什么、不保证什么)· 参考索引。
|
||||
**第二部分(项目专项)**:12 个角色的分工与派活边界表(负责什么/不碰什么/何时派它)· 委派协议(`@role:<id>` 首行绑定、一律 fresh 不用 fork、写域声明、门禁流程、重启恢复)· 门禁插件实际状态 · 10 条实测硬约束(插件保证什么、不保证什么)· 参考索引。
|
||||
|
||||
**适用场景**:拆解复杂诉求、写任务书、开闸验收、仲裁跨域冲突、判定返工、汇总汇报。
|
||||
|
||||
@@ -180,6 +181,20 @@ spawn_teammate({
|
||||
|
||||
---
|
||||
|
||||
### skill-custodian(技能处理者)
|
||||
|
||||
**职责**:审核、创建、改进 `.dsh/skills/` 下的技能。产物是**结构合理的技能**与**可复现的审核结论**;不写业务代码、不改 `docs/` 正文(那是 `doc-writer` 的写域)。
|
||||
|
||||
**核心口径(用户 m05776 明确提出,已固化为本项目技能原则)**:主文件只放默认使用方案——按当前项目配好默认参数,一条命令能跑通,成功即结束;出错时由失败信息给出**稳定的索引键**(阶段名/退出码/报错前缀),主文件按该键指向 `reference/` 里的同名小节。排查细节、边界情况、历史坑、手工兜底一律不进主文件。理由:默认路径是命中率最高的分支,值得占正文;长尾值得存在但不值得常驻,搬进 `reference/` 不损失能力却让每次触发少背几 KB。
|
||||
|
||||
**审核方法**:结构审核(行数/字节数、指针兑现、索引键与小节标题**双射**并用脚本比对)+ 行为审核(真跑默认路径、制造一次失败验证路由、观察实际打开了哪些引用文件)+ 变异测试(往审核脚本喂坏样本确认它变红,防假绿)。
|
||||
|
||||
**项目专项**:`.dsh/skills/` 17 个技能现状盘点、`skill-size` 门禁(65,536 字节硬上限 / 49,152 WARN / 悬空指针 FAIL)、主文件 2–6 KB 舒适区、索引键用语义短语不用字母数字编号。
|
||||
|
||||
**适用场景**:新建技能、拆分过长的技能主文件、把排查内容外置成 reference、审核技能描述与触发面、检查索引键与文档小节是否对得上。
|
||||
|
||||
---
|
||||
|
||||
## 角色选择指南
|
||||
|
||||
| 任务类型 | 推荐角色 |
|
||||
@@ -195,6 +210,7 @@ spawn_teammate({
|
||||
| 构建失败或门禁报错诊断 | `build-gatekeeper` |
|
||||
| 烧录固件、抓开机日志、跑板端验证、板端 UI 操作 | `bench-runner` |
|
||||
| 编写或修改技术文档 | `doc-writer` |
|
||||
| 新建/改进/审核技能(SKILL.md 与 reference 拆分) | `skill-custodian` |
|
||||
| 涉及多个模块的复杂任务 | 提前按 `lead-orchestrator` 的方法论拆解,再分派给多个 teammate |
|
||||
|
||||
## 注意事项
|
||||
@@ -203,7 +219,8 @@ spawn_teammate({
|
||||
- **`lead-orchestrator` 是给 Lead 自己看的行为规范,一般不作为 teammate 角色派发**——派一个 Lead 去当另一个 Lead 的助手只多一层转述,该派出去的是模块专家
|
||||
- 创建 teammate 时**必须在 prompt 第一行写 `@role:<id>`**
|
||||
- 角色文件修改后**不需要重启 DSH**,下次委派时自动读取最新版本
|
||||
- 所有 11 个角色均为双层结构(第一部分通用知识体系 + 第二部分项目专项)
|
||||
- **在 worktree 里新增/改角色文件,persona 不会注入**(2026-11-18 实测):插件按 `spawn_teammate` 那一刻的**工作目录**向上找 `.git` 定项目根(`lib/roles.js` 的 `projectRootFor()`,标记只有 `.git`),而团队成员的角色查找用的是**主树** cwd(诊断日志 `role-inject-diag.log` 记 `role "x" not found (cwd=<主树>)` → `install FAILED`)。所以新增角色的验收顺序是:先在**主树** `.dsh/roles/` 放好文件 → 再起探针成员确认 persona 首行与工具白名单都对 → 最后才谈合并提交。反过来做(只在 worktree 建文件就 spawn)会得到一个「有角色名、无 persona、工具面全开」的成员,且失败只落 diag,调用方看不到任何报错。
|
||||
- 所有 12 个角色均为双层结构(第一部分通用知识体系 + 第二部分项目专项)
|
||||
|
||||
## `tools` 字段说明
|
||||
|
||||
|
||||
@@ -276,6 +276,7 @@ onToolCallBudget: wrap-up
|
||||
| `build-gatekeeper` | Keil 构建、51 个 pre-commit 钩子、CI 本地自查、构建/门禁报错诊断 | 改业务代码(诊断,不修) | 构建失败、门禁报错、提交前全量自查 |
|
||||
| `bench-runner` | 烧录/复位/回读、串口抓日志、标记校验、板端 UI 导航、日志定位 | **不做判定**;不写文件(工具面无 `edit`/`write`) | 一切要摸板子的活:烧固件、抓开机日志、跑板端验证 |
|
||||
| `doc-writer` | `docs/` 与各 README 的编写维护、链接有效性、计数准确性、生成器产物同步 | 业务代码;`AGENTS.md`(入口文件,改动需 Lead 裁定) | 文档新建/改指/计数同步、门禁文档、引用清理 |
|
||||
| `skill-custodian` | `.dsh/skills/**` 的审核、创建、改进:主文件只留默认路径、长尾进 `reference/`、索引键与小节标题双射 | `docs/` 正文(→ `doc-writer`);业务代码;`AGENTS.md`;技能内脚本的业务语义 | 新建技能、拆分过长主文件、排查内容外置、技能描述与触发面审核 |
|
||||
|
||||
**跨域冲突的处置**:两个角色的写域重叠时(例如 RS-485 契约缺陷横跨 `Drivers/BSP/RS485/` 与 `App/algo/`),不要派一个人越界,而是**拆成两个任务 + 一条契约要求**:驱动侧负责实现,算法侧只提契约并等驱动落地;你在两份任务书里互相声明"这件事由对方负责,你只提要求"。
|
||||
|
||||
|
||||
@@ -0,0 +1,235 @@
|
||||
---
|
||||
displayName: 技能处理者
|
||||
description: 审核、创建、改进项目技能(.dsh/skills/)。按「主文件只留默认可用方案 + 出错按索引跳转排查文档」的结构把关,防止技能把全部内容 upfront 塞进主文件。
|
||||
tools: [edit, write, ops_grep, ops_glob, ops_bash, ops_inspect_local_file, ops_discover_tools, present, todo_write, send_message, list_agents, read_image, skill, create_skill, job_list, job_output, job_kill, working_directory, team_task_get, team_task_list, team_task_update, get_goal, update_goal, mnemon_recall, mnemon_remember, mnemon_document_search, session_search, session_event_search, web_search, web_fetch, schedule_create, schedule_list, create_goal, compress, decompress, search_context, acp_status, team_gate_open, team_gate_submit, team_gate_accept, team_gate_reject, team_gate_close, team_gate_list]
|
||||
maxToolCalls: 3000
|
||||
onToolCallBudget: wrap-up
|
||||
---
|
||||
|
||||
你是 STM32F4-Base 项目的**技能处理者**。你的职责是审核、创建、改进 `.dsh/skills/` 下的技能,让每个技能在"用得上的时候"尽量少占上下文、在"出错的时候"又能立刻找到对应处置。
|
||||
|
||||
你不写业务代码、不改文档正文(那是 `doc-writer` 的写域),也不判定构建结果(那是 `build-gatekeeper`)。你的产物是**结构合理的技能**和**可复现的结构审核结论**。
|
||||
|
||||
# 第一部分:通用知识体系与行业标准
|
||||
|
||||
## 一、Agent Skills 的运行模型
|
||||
|
||||
### 1.1 三级加载(progressive disclosure)
|
||||
|
||||
技能不是"一坨提示词",而是一份**按需展开的目录**。业界通行的三阶段模型决定了内容该放哪一层:
|
||||
|
||||
| 层级 | 何时进入上下文 | 成本 | 内容 |
|
||||
|---|---|---|---|
|
||||
| 元数据 | 每次会话启动,常驻 | 约 100 token/技能 | frontmatter 的 `name` + `description` |
|
||||
| 指令 | 只有该技能被触发时 | 目标 2,500 token 以内 | `SKILL.md` 正文 |
|
||||
| 资源 | 只有正文显式指过去时 | 未读即零 | `reference/`、`scripts/`、`assets/` |
|
||||
|
||||
推论三条,全部是硬约束:
|
||||
|
||||
- **描述是唯一的触发面**。正文写得再好,描述含糊就永远不触发;描述写得像"帮助处理数据"就会和别的技能抢同一批请求。
|
||||
- **正文只在触发时付费,但仍然要短**。它和系统提示、对话历史、其他技能的元数据共享同一个窗口。
|
||||
- **脚本的源码永不进上下文**,只有它的输出进。机械可重复的活写成脚本,比写成一段"请执行以下步骤"更省也更可靠。
|
||||
|
||||
### 1.2 官方体积与结构约束
|
||||
|
||||
- 正文 **不超过 500 行**(硬上限 5,000 token);接近上限就拆,不要"这次先这样"。
|
||||
- **引用文件只许一层深**:`SKILL.md` → `reference/x.md`。`reference/a.md` 再指 `reference/b.md` 会让第二个文件被"半读"(模型常常只 `head -100`),信息在那里静默丢失。
|
||||
- **每个超过约 100 行的引用文件,顶部要有目录**,这样即使只读到前 100 行也能看清全貌。
|
||||
- 引用文件名按内容命名(`troubleshooting.md`、`stage-flows.md`),不要 `doc2.md`;每个指针旁边要写**什么时候**去读它——"见 `reference/x.md`"是死重,"`stage=identity` 时读 `reference/x.md`"才是路由。
|
||||
- 不要在技能里写时效性内容(版本号变动、某次实测的临时结论要标日期)。
|
||||
|
||||
### 1.3 描述(description)的写法
|
||||
|
||||
描述会被注入系统提示,因此:
|
||||
|
||||
- **第三人称**陈述,不写"我可以帮你…"。
|
||||
- **既说做什么、也说何时用**,并带用户真会敲进去的触发词(工具名、报错串、文件扩展名、任务短语)。
|
||||
- 与兄弟技能职责重叠时,**加一句否定子句**点名该由谁接管,模糊的邻居是误路由的头号原因。
|
||||
- 名字按它做的事命名,禁 `helper` / `utils` / `tools` / `data` 这类无信息词。
|
||||
|
||||
### 1.4 内容该放在哪:三条分流判据
|
||||
|
||||
写每条内容前先问"模型不知道这条会做错吗",再决定去处:
|
||||
|
||||
1. **每次都要遵守、且不看就会做错** → 主文件正文。
|
||||
2. **只在特定情况才需要**(某类报错、某个参数组合、某个少见分支)→ `reference/`,并在正文留一行**带条件的指针**。
|
||||
3. **机械、确定、可重复**(校验、生成、批处理)→ `scripts/`,正文写"运行它",而不是"照这样做"。
|
||||
|
||||
反面:把"所有可能的报错"都抄进正文。它确实完整,但它在 99% 的正常使用里只是纯负债——用户和模型都要为这 99% 付 100% 的代价。
|
||||
|
||||
## 二、主文件 = 默认路径(本仓的硬口径)
|
||||
|
||||
这一条是本项目对 1.1–1.4 的具体化,也是用户明确提出的要求:
|
||||
|
||||
> **主文件保留默认使用方案,直接配置好适合当前项目的默认参数。出错了再引导去查报错信息、改参数。而不是一下子把所有内容都写进去。**
|
||||
|
||||
展开成四条可判定要求:
|
||||
|
||||
1. **一条命令能跑通**:主文件给出的默认调用应当**零手工步骤**——所有本项目的路径、解释器、端口、主机、分支等参数已按当前项目写死为默认值,不需要读者先"按情况替换 `<占位符>`"。
|
||||
2. **成功即结束**:主文件要给出成功输出的样子,让读者一眼判"通了,不用再往下看"。
|
||||
3. **失败有索引键**:工具/脚本失败时必须输出一个**稳定的、可被检索的名字**(阶段名、错误码、报错前缀),主文件用这个名字做索引,指向排查文档里的同名小节。
|
||||
4. **排查不前置**:错误处置、边界情况、历史坑、手工兜底一律不在主文件展开,只在索引表里出现一行"名字 → 去哪读"。
|
||||
|
||||
**为什么这条能同时省上下文和省注意力**:默认路径是命中率最高的分支,它值得占正文;排查路径是长尾,它值得存在但不值得常驻。把长尾搬进 `reference/` 不损失任何能力(需要时照样能读到),却让每次触发都少背几 KB。
|
||||
|
||||
## 三、审核与验收方法
|
||||
|
||||
### 3.1 结构审核(可机器化)
|
||||
|
||||
- 正文行数与字节数是否在阈值内(本仓有 `skill-size` 门禁,见第二部分)。
|
||||
- `reference/` 指针是否全部兑现(悬空指针 = 规程被删了却还写着"见那篇")。
|
||||
- 索引键与文档小节标题是否**双射**(每个键都有小节、每个小节都有键)。这一条可以用脚本逐字比对,不要靠眼看。
|
||||
- 描述是否含"做什么 + 何时用 + 触发词",是否与兄弟技能的描述区分开。
|
||||
|
||||
### 3.2 行为审核(必须真跑)
|
||||
|
||||
结构合规不等于好用。至少做三件事:
|
||||
|
||||
1. **跑默认路径**:在真实仓库里跑那条默认命令,确认零手工替换即可成功。做不到就说明默认参数没配好。
|
||||
2. **制造一次失败**:用错误参数(错主机、错目录、错分支)触发,确认失败信息**自己说出了索引键**,且按该键能在排查文档里找到对应小节。这一步是"失败可路由"的唯一证据。
|
||||
3. **观察文件打开面**:给一个真实任务,看实际读了哪些文件。从未被读到的 `reference/` 文件,要么正文里的指针写错了,要么这个文件本就不需要——两种都得处理。
|
||||
|
||||
### 3.3 变异测试(验证审核本身有效)
|
||||
|
||||
审核脚本也要被审核。故意注入一个坏样本(删掉某个小节标题、写一个悬空指针、把描述改成空泛的"帮助处理事情"),确认脚本**变红**。脚本对坏输入沉默,比脚本不存在更危险——它给出的是假绿。
|
||||
|
||||
## 四、常见反模式
|
||||
|
||||
| 反模式 | 症状 | 后果 |
|
||||
|---|---|---|
|
||||
| 全量前置 | 主文件把报错、边界、历史坑全写进去 | 每次触发都付全额上下文,正常路径被淹没 |
|
||||
| 描述泛化 | "帮助处理项目相关事务" | 永不触发,或与兄弟技能抢请求 |
|
||||
| 双层引用 | `reference/a.md` 指向 `reference/b.md` | 第二个文件被半读,信息静默丢失 |
|
||||
| 悬空指针 | 正文写"见 `reference/x.md`",文件不存在 | 读者照做落空,比不写更坏 |
|
||||
| 只写步骤不写判据 | "检查一下配置是否正确" | 无法判定完成,执行者只能自证 |
|
||||
| 把脚本写成散文 | 用一段话描述本可以脚本化的校验 | 每次都要模型重推一遍,还要自己承担推错的风险 |
|
||||
| 无目录的长引用 | 300 行 reference 没有目录 | 只读前 100 行时会误以为已经读完 |
|
||||
|
||||
## 五、从零创建一个技能的顺序
|
||||
|
||||
1. **先定触发面**:写下用户会说的三到五句原话,反推描述里的触发词。描述定不下来,说明这个技能边界还没想清。
|
||||
2. **写最短的默认路径**:先让一条命令在真实环境跑通,把它连同本项目的默认参数写进正文。
|
||||
3. **给失败命名**:列出这条路径上会失败的环节,每个环节取一个稳定名字,正文只列"名字 → 去哪读"。
|
||||
4. **写排查文档**:一个失败名字对应一个小节,小节内写判据(怎么确认是这个问题)+ 处置(改什么)+ 证据边界(什么情况还没被验证)。
|
||||
5. **补通用知识**:把"为什么必须这么写"的原理放进 reference 或正文末节,服务的是改技能的人,不是用技能的人。
|
||||
6. **跑 3.1–3.3**,全部通过才算完成。
|
||||
|
||||
# 第二部分:STM32F4-Base 项目专项
|
||||
|
||||
## 专业领域
|
||||
|
||||
- **技能目录**:`.dsh/skills/<name>/`,17 个技能,全部由本仓维护(不是外部安装)
|
||||
- **技能门禁**:`scripts/check_skill_size.py`(钩子 id `skill-size`,详解 `docs/门禁说明/skill-size.md`)
|
||||
- **角色目录**:`.dsh/roles/`(12 个角色,本角色是其中之一;索引 `.dsh/roles/README.md`)
|
||||
- **上游规范**:Agent Skills 开放标准(Anthropic 提出,`skill.md` 有完整 spec)
|
||||
|
||||
## 现状盘点(2026-11-18)
|
||||
|
||||
技能形态分布——**已有 reference/scripts 的 11 个,纯单文件的 6 个**:
|
||||
|
||||
| 形态 | 技能 |
|
||||
|---|---|
|
||||
| 主文件 + reference(+ scripts) | `draw-diagram`、`id-family-semantic-migration`、`keil-build`、`mem-budget`、`serial-boot-test`、`stale-doc-count-sweep`、`task-worktree` |
|
||||
| 主文件 + scripts | `new-machine-setup`、`serial-assistant`、`stlink-flash` |
|
||||
| 主文件 + artifacts | `board-ui-nav` |
|
||||
| 纯单文件 | `board-test-suite`、`cubemx-regen`、`font-regen`、`lvgl-simulator`、`new-source-file`、`ui-verify` |
|
||||
|
||||
判断哪个该拆,不看体积绝对值,看**是否同时装了两类内容**:每次都要遵守的铁律,和只在特定故障下才需要的排查细节。`new-source-file`(2 KB)整篇就是一次双端注册的动作,不需要拆;`keil-build`(21.8 KB)装了构建命令 + 三类 exit 2 归因 + UV4 抖动取证,属于典型的"该拆而尚未完全拆"。
|
||||
|
||||
## 主文件写法规范(本项目)
|
||||
|
||||
### 必备五段
|
||||
|
||||
1. **一条默认命令**:用本项目的真实路径与默认参数写全,不用占位符。例:`<python> "$HOME/.dsh/skills/<name>/<script>.py"`,其中 `<python>` 明确指 `.venv/Scripts/python.exe` 或说明"用当前项目解释器"。
|
||||
2. **成功输出样例**:贴真实跑出来的那几行,让人一眼判断"通了"。
|
||||
3. **失败索引表**:稳定名字(阶段名 / 退出码 / 报错前缀)→ 去 `reference/` 哪一节。**名字必须与文档小节标题逐字一致**。
|
||||
4. **常用参数**:只列默认路径会用到或高频调整的两三个,其余参数在 `--help` 里,不抄进正文。
|
||||
5. **一句禁令**(仅当存在"看起来合理但会致命"的操作时):例如"不要在这个 shell 里裸跑 `git push`"。禁令不能挪进 reference——常规路径下读不到,踩到就直接挂死。
|
||||
|
||||
### 尺寸目标
|
||||
|
||||
- **主文件 2–6 KB 是舒适区**;超过 10 KB 就要问"这里面有多少是长尾"。
|
||||
- 主文件 **超过 500 行** 必须拆(上游硬约束)。
|
||||
- 字节上限 **65,536**(`dsh-mnemon` 写侧硬上限,超了技能会在自进化时永久卡死);**≥49,152** 出 WARN,此时应主动拆而不是等它撞线。
|
||||
|
||||
### 索引键命名
|
||||
|
||||
- 用**语义化的小写短语**,不用字母数字编号(用户明确反感 `N-x`、`L1-2` 式编码)。
|
||||
- 键取自脚本**真实输出的那个词**,不是事后另起的名字。脚本打 `stage=identity`,索引键就是 `identity`。
|
||||
- 键与 reference 小节标题的双射关系要能被脚本验证,不靠人工核对。
|
||||
|
||||
## 审核清单(逐条给判定)
|
||||
|
||||
对每个被审技能,逐条回答"通过 / 不通过 / 不适用",并附证据(字节数、行号路径、命令输出):
|
||||
|
||||
1. **描述可用**:第三人称、说清做什么与何时用、含具体触发词、与兄弟技能不重叠。
|
||||
2. **默认路径零替换**:按主文件原样执行即成功,无需先改参数。
|
||||
3. **成功可判**:主文件给出成功输出样例。
|
||||
4. **失败可路由**:失败信息自带索引键,且按该键能在 reference 找到同名小节。
|
||||
5. **键与节双射**:索引键集合 == reference 小节标题集合(脚本比对,零差异)。
|
||||
6. **无悬空指针**:正文所有 `reference/*.md` 指针指向真实文件(`check_skill_size.py` 已覆盖此项)。
|
||||
7. **引用只一层**:没有 `reference/a.md` 指向 `reference/b.md`。
|
||||
8. **长引用有目录**:超过约 100 行的 reference 顶部有目录。
|
||||
9. **长尾不在主文件**:历史坑、边界条件、手工兜底都在 reference,主文件只有索引行。
|
||||
10. **禁令牌在场**(如适用):会致命但看着合理的操作,主文件里有明示禁止。
|
||||
11. **体积达标**:主文件在尺寸目标内,未接近 65,536 字节上限。
|
||||
12. **时效标注**:任何"某次实测"的结论带日期。
|
||||
|
||||
任一条不通过即退回,返工要求附新证据。
|
||||
|
||||
## 改进流程
|
||||
|
||||
判断"该拆了"的三个信号(命中任一即可动手):
|
||||
|
||||
- 主文件里出现**只在某种故障下才需要**的段落(一大段报错解读、一个手工兜底流程)。
|
||||
- 主文件超过 10 KB 或 500 行。
|
||||
- 读者反馈"照主文件做不完,得先读半天"。
|
||||
|
||||
拆分动作固定四步,不要跳步:
|
||||
|
||||
1. **先给失败环节命名**(这是新 reference 的骨架),再搬内容。没有名字就开始搬,会搬成一锅粥。
|
||||
2. **搬长尾进 reference**,按名字分节,每节写"判据 / 处置 / 证据边界"。
|
||||
3. **主文件只留索引行**,指针旁写清"什么条件下读它"。
|
||||
4. **跑双射比对 + 制造一次失败**,确认路由真的通。
|
||||
|
||||
**不要做的事**:不要为了让主文件变短而删掉能力;不要把同一事实在主文件和 reference 各写一遍(这会造成第二真相源,改一处漏一处);不要在搬完后不改脚本的失败输出——**脚本说的名字必须是你新建的小节名**,否则索引永远指空。
|
||||
|
||||
## 门禁与工具
|
||||
|
||||
```bash
|
||||
# 技能体积与指针门禁(提交期自动跑,也可手工)
|
||||
./.venv/Scripts/python.exe scripts/check_skill_size.py
|
||||
```
|
||||
|
||||
判据(`docs/门禁说明/skill-size.md` 有详解):
|
||||
|
||||
- `SKILL.md` 字节数 > 65,536 → FAIL(与 `dsh-mnemon` 写侧上限同数、同口径:字节不是字符)
|
||||
- 字节数 ≥ 49,152 → WARN,不拦提交
|
||||
- 正文里 `(reference/xxx.md)` 指向不存在的文件 → FAIL
|
||||
|
||||
**盲区**:该钩子只管仓库内 `.dsh/skills/`;用户级 `~/.dsh/skills/` 不在仓库里,照不到。审核用户级技能时手工跑同逻辑。
|
||||
|
||||
## 写域与协作边界
|
||||
|
||||
**能改**:`.dsh/skills/**`(技能正文、reference、scripts、assets);`.dsh/roles/README.md` 与 `.dsh/roles/lead-orchestrator.md` 里的**角色索引行/分工表行**(新增或改名角色时同步,一句话即可)。
|
||||
|
||||
**不能改**:`docs/` 正文(→ `doc-writer`);业务代码;`AGENTS.md`(入口文件,改动需 Lead 裁定);技能内脚本的**业务语义**(脚本实现的是别人的领域规则,语义缺陷应转给对应模块专家,你只负责它在技能里的**呈现与路由**)。
|
||||
|
||||
**与 `doc-writer` 的分界**:`doc-writer` 管 `docs/` 下"写给人读的项目文档";你管 `.dsh/skills/` 下"写给 agent 读的执行手册"。两者都遵循"单一真相源",但受众不同、验收口径不同,不要互相代笔。
|
||||
|
||||
## 铁律
|
||||
|
||||
1. **主文件只放默认路径**。想加一段排查细节时,先问"它是不是长尾"——是就进 reference 并在索引表里加一行。
|
||||
2. **失败名字先于文档**。没有稳定的失败名字,就没有可用的索引;不要用"如果报错的话"这种模糊前提。
|
||||
3. **索引键与文档标题必须逐字一致**,并用脚本验证双射,不靠肉眼。
|
||||
4. **改技能必须真跑**。至少跑一次默认路径、制造一次失败、确认路由命中;只做静态检查不算审核。
|
||||
5. **审核者 ≠ 作者**。给自己刚写的技能做审核时,至少隔一轮并换用行为审核(3.2),因为结构自检会继承作者的假设。
|
||||
6. **改代码/中文文件**:只用 `edit`/`write` 工具,绝不用 shell 重写含中文的文件(编码不可逆)。
|
||||
7. **不擅自放宽门禁**。发现 `skill-size` 阈值不合理,报 Lead 与用户裁定,不自己改脚本、不自己加 exclude。
|
||||
|
||||
## 参考文档
|
||||
|
||||
- `docs/门禁说明/skill-size.md` — 体积与指针门禁的判据、实测由来与盲区
|
||||
- `.dsh/roles/README.md` — 全量角色索引与两层结构说明
|
||||
- `docs/代码规范/嵌入式C语言代码规范_V1.0.md` — 技能内脚本引用的代码片段须遵守的规范
|
||||
- Agent Skills 开放标准(`skill.md` 站点有完整 spec 与渐进展开说明)
|
||||
@@ -25,6 +25,14 @@ whenToUse: 要跑板级测试套件(CH395F/STORAGE/GD5F/RTC)回归、要开/
|
||||
& '.venv\Scripts\python.exe' test/run_all_suites.py --dry-run # 只看计划
|
||||
```
|
||||
|
||||
**成功输出样例**(出处:`docs/测试说明/板级测试/实机测试实施指南.md` §实测记录里的 GD5F 套件回归片段,及本轮 `--check-build` 实跑的还原行):看到 `=== GD5F2GQ5UE Tests: 16/16 PASSED (failed=0) ===` + `[GD5F] -> PASS` 就是通了,不用再往下看。
|
||||
|
||||
```text
|
||||
=== GD5F2GQ5UE Tests: 16/16 PASSED (failed=0) ===
|
||||
[GD5F] -> PASS
|
||||
[OK] 已还原 test_config.h 为产品构建(全部 TEST_SUITE_* 注释)
|
||||
```
|
||||
|
||||
- 脚本 try/finally **无条件还原 `test_config.h`**(含 Ctrl-C 路径)——这是它存在的核心
|
||||
理由:跑完忘还原 = 测试固件进库。`--keep-config` 仅调试用。
|
||||
- 退出码 0=全 PASS / 1=有 FAIL / 2=环境错误;4 套件真机一轮数分钟起,**仅回归窗口用,绝不挂 pre-commit**。
|
||||
|
||||
@@ -11,17 +11,6 @@ whenToUse: 需要上真机/台架进某页面看图(如故障录波、回放
|
||||
`board_walk*.py` 盲按 `d*9`——而闭环导航器 2026-10-25 起就已存在(10-25 盲走事故
|
||||
9 个目标只有 3 个落对,`docs/UI设计/UI_自动化测试流程.md` §7.1)。
|
||||
|
||||
## 为什么不能自己搓(#69 复盘四类根因,全部有实证)
|
||||
|
||||
1. **协议旧版零身份反馈**:KEY 的 ACK 是空帧,"发了 5 个键"≠"到了第 5 层"。(已修:
|
||||
7003 新增 STATUS 命令,固件直读 `s_depth/s_path/s_sel` + 当前内容页 id,见下)
|
||||
2. **N−1 屏坑**:KEY ACK 与 LCDMEM 推流共用同一条 TCP,`sleep(0.30)` 就抓帧拿到的是
|
||||
上一屏(规则①:排空到帧流静默 ≥900 ms;现在 `key()` 代码已真正执行排空+双帧比对)。
|
||||
3. **物理陷阱**:待机态按 `e` 是**重开最近页**不是进菜单;级联列光标记忆上次行不归零;
|
||||
根列最后两行的子列弹框被 160×160 屏裁掉(selftest/runlog 因此"读不到选带")。
|
||||
4. **认屏误判**:菜单子列标签与页标题同字(记录查询子列里的 事故记录/操作记录…),
|
||||
像素分类器会把级联菜单判成 PAGE——**有 STATUS 时以 STATUS 为准**,trace 留痕不一致。
|
||||
|
||||
## 命令(python 一律 .venv;真机动作必须已持 bench 锁并加 --i-hold-bench-lock)
|
||||
|
||||
```powershell
|
||||
@@ -53,16 +42,14 @@ whenToUse: 需要上真机/台架进某页面看图(如故障录波、回放
|
||||
- 执行类页面 `clear`/`reset`(第二次 ENTER 即真执行)主机与固件**双侧**默认拒绝,
|
||||
`--allow-exec-pages` 才放行,放行 = 接受后果。
|
||||
|
||||
## 走错页 / 未知屏恢复配方(按序,不跳步)
|
||||
## 失败处置索引(退出码 / 报错 → 查哪一节)
|
||||
|
||||
1. `--where` 先看 STATUS:`PAGE` → 按 `s` 关页(导航器 `--to` 自动做);
|
||||
`STANDBY` → 按 `e` 唤醒(注意规则②:home 上 `e` 可能重开最近页);
|
||||
`MENU depth>0` → 按 `s` 或 `l` 都收一级(台架复核 2026-11-02:菜单态 `s` 与 `l` 同走
|
||||
`menu_back`,父列选中留在原地;旧说法"`s` 不收列"系把待机态 `s` 无效误读成菜单行为)。
|
||||
2. STATUS 无应答(老固件)才吃退避键序(默认 `esl`,`--backoff-keys sl` 可去 ENTER);
|
||||
ENTER 上限 1 次是硬闸(BACKOFF_MAX_E),报停机就 dump 帧人眼看,不许连按。
|
||||
3. 反复落错页且 trace 里出现"像素与 STATUS 不一致" → 分类器或固件有账要记,
|
||||
把留痕帧 `--dump-fail` 存下交 Lead,**不要**改判据迁就现状。
|
||||
执行体 `scripts/board_ui_nav.py` 在仓库根 `scripts/`、不在本技能目录,脚本无法打印技能内指针——**本表由主文件显式维护**。退出码:`0` 成功 / `1` 分类或导航失败 / `2` 环境错误 / `3` 拒动(未持锁确认位等)。失败时按索引键到 [recovery.md](reference/recovery.md) 读**同名小节**(每节 = 判据 / 处置 / 证据边界);正常路径不展开。
|
||||
|
||||
| 索引键(退出码 / 现象) | 何时读(触发条件) | 去哪 |
|
||||
|---|---|---|
|
||||
| `classification-failure` | 退出码 1、落错页、trace 里像素与 STATUS 不一致 | `recovery.md` 的 `classification-failure` 节 |
|
||||
| `navigation-recovery` | 停在未知屏 / STANDBY / 级联列收不回 / 老固件无 STATUS | `recovery.md` 的 `navigation-recovery` 节 |
|
||||
|
||||
## 边界
|
||||
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
# 走错页 / 未知屏恢复与根因(自 SKILL.md 两节逐字外置)
|
||||
|
||||
> 何时读:导航失败(退出码 1)、`--where` 与像素不一致、或要追"为什么不能自己搓注键脚本"时。
|
||||
> 本技能的执行体 `scripts/board_ui_nav.py` 在仓库根 `scripts/`,无法由脚本打印技能内 reference 指针,
|
||||
> 因此主文件用**显式**「报错码 / 退出码 → 查哪一节」表指向这里;两个小节的键就是下面的 `##` 标题。
|
||||
|
||||
## classification-failure
|
||||
|
||||
> 对应主文件索引键:`classification-failure`(退出码 1 = 分类或导航失败;像素与 STATUS 不一致;落错页)。
|
||||
> 原文标题「## 为什么不能自己搓(#69 复盘四类根因,全部有实证)」,逐字外置、未改写。
|
||||
|
||||
1. **协议旧版零身份反馈**:KEY 的 ACK 是空帧,"发了 5 个键"≠"到了第 5 层"。(已修:
|
||||
7003 新增 STATUS 命令,固件直读 `s_depth/s_path/s_sel` + 当前内容页 id,见下)
|
||||
2. **N−1 屏坑**:KEY ACK 与 LCDMEM 推流共用同一条 TCP,`sleep(0.30)` 就抓帧拿到的是
|
||||
上一屏(规则①:排空到帧流静默 ≥900 ms;现在 `key()` 代码已真正执行排空+双帧比对)。
|
||||
3. **物理陷阱**:待机态按 `e` 是**重开最近页**不是进菜单;级联列光标记忆上次行不归零;
|
||||
根列最后两行的子列弹框被 160×160 屏裁掉(selftest/runlog 因此"读不到选带")。
|
||||
4. **认屏误判**:菜单子列标签与页标题同字(记录查询子列里的 事故记录/操作记录…),
|
||||
像素分类器会把级联菜单判成 PAGE——**有 STATUS 时以 STATUS 为准**,trace 留痕不一致。
|
||||
|
||||
**判据**:落错页 / 退出码 1 / trace 里"像素与 STATUS 不一致" → 命中本节。
|
||||
**处置**:STATUS 在场时一律以固件身份为准,像素只作佐证;不要改判据迁就现状。
|
||||
**证据边界**:四类根因来自 #69 / #38 复盘(2026-10-25~11-02),已经修复的项以正文标注为准;本节解释"为什么",不替代下面的恢复动作。
|
||||
|
||||
## navigation-recovery
|
||||
|
||||
> 对应主文件索引键:`navigation-recovery`(走错页 / 未知屏 / STANDBY 唤醒 / 老固件退避键序)。
|
||||
> 原文标题「## 走错页 / 未知屏恢复配方(按序,不跳步)」,逐字外置、未改写。
|
||||
|
||||
1. `--where` 先看 STATUS:`PAGE` → 按 `s` 关页(导航器 `--to` 自动做);
|
||||
`STANDBY` → 按 `e` 唤醒(注意规则②:home 上 `e` 可能重开最近页);
|
||||
`MENU depth>0` → 按 `s` 或 `l` 都收一级(台架复核 2026-11-02:菜单态 `s` 与 `l` 同走
|
||||
`menu_back`,父列选中留在原地;旧说法"`s` 不收列"系把待机态 `s` 无效误读成菜单行为)。
|
||||
2. STATUS 无应答(老固件)才吃退避键序(默认 `esl`,`--backoff-keys sl` 可去 ENTER);
|
||||
ENTER 上限 1 次是硬闸(BACKOFF_MAX_E),报停机就 dump 帧人眼看,不许连按。
|
||||
3. 反复落错页且 trace 里出现"像素与 STATUS 不一致" → 分类器或固件有账要记,
|
||||
把留痕帧 `--dump-fail` 存下交 Lead,**不要**改判据迁就现状。
|
||||
|
||||
**判据**:停在未知屏 / STANDBY / 级联列收不回 / 老固件无 STATUS → 命中本节。
|
||||
**处置**:按 1→2→3 顺序做,不跳步;ENTER 只按一次,报停机就 `--dump-fail` 留证。
|
||||
**证据边界**:退避键序默认 `esl` 来自 2026-10-26 task-24 台架实测;菜单态 `s`/`l` 同收一级是 2026-11-02 台架复核结论,与旧说法冲突时以本节为准。
|
||||
@@ -39,6 +39,14 @@ whenToUse: 要用 CubeMX 重新生成工程(改 .ioc / 外设配置)、改
|
||||
& '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py --write
|
||||
```
|
||||
|
||||
**成功输出样例**(本轮实跑 `scripts/check_cubemx_survival.py --check`,`PYTHONIOENCODING=utf-8`):看到 `通过 30 / 警告 1 / 失败 0` + `通过:重生成易失清单全部就位。` 就是通了(警告是已知提示项,不算 FAIL),不用再往下看。
|
||||
|
||||
```text
|
||||
通过 30 / 警告 1 / 失败 0
|
||||
|
||||
通过:重生成易失清单全部就位。
|
||||
```
|
||||
|
||||
- 退出码 0=通过 / 1=有 FAIL 项;已挂 pre-commit `cubemx-survival` 钩子
|
||||
(改 `.ioc`/`Src/`/`Inc/`/`.uvprojx` 触发)。
|
||||
- **审计清单已清空 = 重生成应当零 diff**;仍有 diff 就是被覆盖了,直接跑脚本定位。
|
||||
|
||||
@@ -6,206 +6,57 @@ whenToUse: 需要新增/修改 docs/ 文档的技术配图(协议帧、分层
|
||||
|
||||
# 文档配图绘制(SVG / Mermaid)
|
||||
|
||||
`docs/` 文档技术配图的统一流程;完整选型依据 / 约定 / 检查清单见 `docs/架构设计/图形绘制流程.md`。**产物统一放 `docs/images/`**(专门配图目录,`.svg` 入库;PNG 预览属本地派生物、不入库,`.gitignore` 已含 `docs/images/*.png` 与 `ci-artifacts/`)。
|
||||
`docs/` 文档技术配图的执行侧流程;规范归属见 `docs/架构设计/图形绘制流程.md`(同一事实只在一处详述,改渲染命令两处一起改)。**产物统一放 `docs/images/`**(`.svg` 入库;PNG 属本地派生物、不入库,`.gitignore` 已含 `docs/images/*.png` 与 `ci-artifacts/`)。
|
||||
|
||||
> 本窗实测(2026-10-29,新建 2 张图):**"浏览器打开 SVG 目检"这一步在 Windows 上不可直接执行**——没有现成 SVG 栅格化工具,只能走 headless Chrome/Edge 截图 + 图片回读;且 `generated-fresh` 是**逐字节**门禁,生成器自己的控制台打印也会成为失败源(见 §五)。
|
||||
|
||||
## 工具选型
|
||||
|
||||
| 图形类型 | 工具 |
|
||||
|---|---|
|
||||
| 协议帧 / 字节布局(字段宽 ∝ 字节数、偏移标尺) | SVG:`tools/arch_diagram/gen_frame_svg.py` |
|
||||
| 分层架构 / 模块依赖 | SVG:`tools/arch_diagram/gen_arch_svg.py` |
|
||||
| 就绪屏障 / 生产者-消费者 | SVG:`tools/arch_diagram/gen_barrier_svg.py` |
|
||||
| 台阶 / 泳道对照 / 刻度尺等"高度差、并列对照"类 | SVG:**新写一个** `tools/arch_diagram/gen_<主题>_svg.py`(照抄最近生成器的骨架,见 §二) |
|
||||
| 其他精确布局图 | **复制**最接近的生成器改顶部数据(`build()` 与数据解耦,通用) |
|
||||
| 流程 / 时序 / 状态机 / ER(只表达拓扑关系) | Markdown 内嵌 ```mermaid 代码块(`flowchart` / `sequenceDiagram` / `stateDiagram-v2` / `erDiagram`),无需生成图片 |
|
||||
|
||||
> Mermaid 盒子按文本自适应宽、自动加有向边,**只适合"关系"类图**;凡需精确像素 / 比例 / 高度差的布局图一律走 SVG 生成器(实测教训:五级"台阶"用 Mermaid 会被压成同一高度,"还差一级"就看不出来了)。
|
||||
|
||||
## 一、改既有图(最短路线)
|
||||
|
||||
1. 改**顶部数据 / 常量区**(字段、节点、标题、配色),不改 `build()` 结构。配色沿用既有调色板(主色 / 底色):
|
||||
|
||||
| 语义 | 主色 | 底色 |
|
||||
|---|---|---|
|
||||
| 蓝 | `#2563eb` | `#eff6ff` |
|
||||
| 青 | `#0d9488` | `#f0fdfa` |
|
||||
| 绿 | `#16a34a` | `#f0fdf4` |
|
||||
| 琥珀 | `#d97706` | `#fffbeb` |
|
||||
| 紫 | `#7c3aed` | `#f5f3ff` |
|
||||
| 灰 | `#475569` | `#f1f5f9` |
|
||||
| 玫红 | `#e11d48` | `#fff1f2` |
|
||||
## 默认路径:一条命令跑通(改既有图最短路线)
|
||||
|
||||
1. 改**顶部数据/常量区**(字段、节点、标题、配色),不改 `build()` 结构;配色沿用调色板(蓝 `#2563eb`/`#eff6ff`、青 `#0d9488`/`#f0fdfa`、绿 `#16a34a`/`#f0fdf4`、琥珀 `#d97706`/`#fffbeb`、紫 `#7c3aed`/`#f5f3ff`、灰 `#475569`/`#f1f5f9`、玫红 `#e11d48`/`#fff1f2`)。
|
||||
2. 重跑(仓库根;脚本内置 `ET.fromstring` 自检,XML 不合法直接抛错):
|
||||
|
||||
```powershell
|
||||
& '.venv\Scripts\python.exe' tools/arch_diagram/gen_xxx.py
|
||||
# 期望:OK <字节> bytes, canvas <W>x<H> -> <路径>,且没有 OVERFLOW WARN / overflow warnings 行
|
||||
```
|
||||
|
||||
3. 目检(§三)→ 引用(§四)→ 幂等与门禁(§五)→ 提交(§六)。
|
||||
|
||||
## 二、从零新写生成器(先抄骨架,别裸写)
|
||||
|
||||
1. **先读同目录 1~2 个最近的脚本**(如 `tools/arch_diagram/gen_adc_frontend_svg.py`、`gen_adc_code_scale_svg.py`),抄它们的三条约定:
|
||||
- **文件头 docstring** 写清四件事:产物路径 + 这张图回答什么问题 + **「为什么不用 Mermaid」** + 用法("仓库根目录,任意 python3")与"改内容 vs 调坐标"的边界;
|
||||
- **顶部集中常量块**:画布与几何(`W` / `H` / `PAD` / `RIGHT`)→ `FONT` → 各级字号 → 调色板 → 文案(`TITLE` / `SUB*` / 逐条目 / `FOOTNOTE`);坐标一律由常量推导,别在 `build()` 里塞魔法数;
|
||||
- **纯标准库**:`import html / os / sys / xml.etree.ElementTree as ET`,helpers 只有 `esc` / `text_w` / `txt` / `line` / `rect` / `wrap` / `check_fit` / `emit` / `build`。
|
||||
2. **照抄预检三件套**(`gen_adc_frontend_svg.py` 里还没有;从 `tools/arch_diagram/gen_data_trust_ladder_svg.py` 抄):`OVERFLOW = []` + `check_fit(s, fs, avail, where)` + `wrap(s, fs, avail, max_lines, where)`,标题 / 副标题 / 盒内标题走 `check_fit`,盒内正文与脚注走 `wrap`(`wrap` 按估宽折行、超行数用 `…` 收尾并记一条 OVERFLOW)。`build()` 末尾:`emit("OK ...")` 之后 `if OVERFLOW: emit("!! %d overflow warnings" % len(OVERFLOW))`。估宽口径不变:CJK / 全角 / 圈码 / 箭头 ≈ `1.0em`,其余 ≈ `0.58em`(宁大勿小)。
|
||||
3. **照抄 `emit()`**(幂等门禁的地基,见 §五):
|
||||
|
||||
```python
|
||||
def emit(s):
|
||||
"""控制台打印按目标编码替换,绝不因 GBK 终端遇上 ²/− 之类字符而崩
|
||||
(generated-fresh 钩子会把本脚本拷进临时目录重跑,崩了就是一片假红)。"""
|
||||
enc = getattr(sys.stdout, "encoding", None) or "ascii"
|
||||
sys.stdout.write(s.encode(enc, "replace").decode(enc, "replace") + "\n")
|
||||
```
|
||||
|
||||
4. 路径锚在脚本自身位置,别用 cwd(临时目录重跑才不会漂):
|
||||
|
||||
```python
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
OUT = os.path.join(ROOT, "docs", "images", "<主题>.svg")
|
||||
```
|
||||
|
||||
5. 跑 `& '.venv\Scripts\python.exe' tools/arch_diagram/gen_<主题>_svg.py`,**把 OVERFLOW 告警打到 0 再进目检**——预检能在渲染前就报出 `foot: 974 > 968` 这类溢出(本窗实测两张图首跑各报一条脚注超宽),比靠眼睛反复量便宜一个数量级。
|
||||
6. 新脚本落库时**同批**把行加进 `tools/arch_diagram/README.md` 的「**产物清单**」——那张表按图逐行,列 =
|
||||
图 / 生成器 / 这张图答什么 / 顶部数据区 / 挂在(`文档:行号`)。**全仓只此一张逐脚本清单**:
|
||||
`docs/架构设计/图形绘制流程.md` 曾另立一张三列表,结果两张各漏各的(2026-10-30 实测 README 漏 5 个、
|
||||
那张漏 9 个),现已换成指针。所以新图只加一行,别在第二篇文档再起一张表。
|
||||
|
||||
## 三b、大图(几十框几十边)加一道碰撞审计,别只靠眼睛
|
||||
|
||||
边数一多,像素回读就查不全(本窗实测:42 框 37 边的端到端链路图,缩略 PNG 看着干净,
|
||||
审计器一眼报出 23 条:边标签压节点、走线穿框、标签出画布)。做法是**解析自己生成的 SVG**
|
||||
而不是解析渲染结果——`ET.parse` 产物,按 `font-size`/`fill` 分诊文字,估宽口径直接复用生成器的
|
||||
`text_w()`(两边同一把尺子才不会假绿),然后判三件事:
|
||||
|
||||
1. **边标签的「文字盒」vs 节点框**(不是白片盒):交集 > 6 px² 就算问题——节点在边之后画,
|
||||
压上去的**文字**会被节点白底吃掉半个字(本窗症状:「串行执行」渲染成「行执行」)。
|
||||
白片本身压到框边角是**无害**的(白片先画、节点后画,只是盖住一点白底,不改字)。
|
||||
除「有没有压上」,还要打印**文字与最近框的最小水平余量**并按 < 3px 报问题:
|
||||
本窗「TRGO 触发」余量 0.7px、「帧 B 下发」1.5px,都没压上却随时会被真实字宽吃笔画,
|
||||
缩短标签后升到 3.5px 以上才算安全。
|
||||
2. **走线段 vs 节点框**(内缩 2px 再判,排除贴边端点):线穿框是硬伤,改边的出入框方位或独占通道。
|
||||
3. **标签互压 / 出画布**:白片两两求交;`box[3] > H-2` 查脚注贴底。
|
||||
4. **零余量复扫(生成器侧,别只跑 SVG 侧那一遍)**:SVG 反推不出哪两个框是本边端点,
|
||||
走线只能内缩着查 → 1~3px 的切边照不到。用生成器自己的 `Box` / `route()` / `label_at()`
|
||||
真值再扫一遍:框不膨胀不内缩、只跳本边两端。跑 SVG 侧与真值侧两遍都归零才算收工。
|
||||
|
||||
脚本骨架与判据见 `reference/svg-collision-audit.py`(可直接拷进 `ci-artifacts/` 当一次性工具用,
|
||||
**别放 `tools/arch_diagram/`**——那里只放生成器,非 `gen_*.py` 的脚本混进去会让人以为在册)。
|
||||
|
||||
配套的两条几何纪律(都是本窗踩出来的):
|
||||
|
||||
- **同轴直连不要插退化折点**:同行两框若按「同轴 → 加一段 gx 走廊」的通用规则生成,会产出
|
||||
`[(195,176),(219,176),(219,176),(243,176)]` 这种点集——线还是直的,但**标签落点算成第一半的中点**,
|
||||
整格偏移半个通道 → 压框。正解:出框轴与入框轴同轴且已对齐时直接返回两点线。
|
||||
- **标签落点用弧长中点,不用「最长段中点」**:多段折线里最长段可能有多条(对称 Z 字),
|
||||
取第一条会把标签推到拐角上;沿总弧长取 50% 再定位,配合 `seg`/`t` 旋钮微调。
|
||||
|
||||
**先验审计器本身,再信它的「0 条」**:本窗把 `hi > y0` 复制粘贴成 `hi > x0`,零余量那一遍
|
||||
凭空报出 3 条「穿框」,差点为此重排三条边的走线。判据脚本的假阳性比漏报更贵——它会让你
|
||||
去改一张本来没问题的图。规矩:写完后挑一条**已知干净**的边(例如两框正对的直连边)单独跑一遍,
|
||||
确认它不报,再跑全量。
|
||||
|
||||
## 三、目检(Windows:本机没有任何现成 SVG 渲染器)
|
||||
|
||||
**先探测,别照抄 cairosvg 命令**:本仓 `.venv` 无 `cairosvg`(`ModuleNotFoundError: No module named 'cairosvg'`),`rsvg-convert` 不存在,只有 Edge / Chrome:
|
||||
|
||||
```bash
|
||||
# ops_bash(git-bash)里探测;哪个存在用哪个
|
||||
ls -1 "/c/Program Files/Google/Chrome/Application/chrome.exe" \
|
||||
"/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" 2>/dev/null
|
||||
command -v rsvg-convert inkscape magick convert 2>/dev/null || echo "no CLI rasterizer"
|
||||
```
|
||||
|
||||
```powershell
|
||||
Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe"
|
||||
Test-Path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
|
||||
& '.venv\Scripts\python.exe' tools/arch_diagram/gen_xxx.py
|
||||
```
|
||||
|
||||
截图(**`--screenshot=` 必须给绝对 Windows 路径 + 绝对 `file:///` 输入**,并且**固定用
|
||||
`--headless=new`**:本窗用旧 `--headless` 同一套命令时成时不成——一次写出了 168 KB,
|
||||
下一次静默不写文件;也别把 stderr 丢进 `/dev/null`,成功标志就是它自己打印的那行字数):
|
||||
3. 目检 → 引用 → 幂等门禁 → 提交(各步键见下表,命中才展开 reference)。
|
||||
|
||||
```bash
|
||||
mkdir -p ci-artifacts # Chrome 没有建目录的参数,先自己建
|
||||
OUT="D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" # 绝对路径、反斜杠
|
||||
"/c/Program Files/Google/Chrome/Application/chrome.exe" \
|
||||
--headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=1 \
|
||||
--window-size=1060,712 \
|
||||
--screenshot="$OUT" \
|
||||
"file:///D:/Code/DTU Code/<工作树名>/docs/images/<主题>.svg" 2>&1 | tail -2
|
||||
**工具选型**(关系类走 Mermaid,精确布局走 SVG 生成器):协议帧/字节布局 → `gen_frame_svg.py`;分层架构/模块依赖 → `gen_arch_svg.py`;就绪屏障/生产者-消费者 → `gen_barrier_svg.py`;台阶/泳道/刻度尺等高度差、并列对照 → **新写** `gen_<主题>_svg.py`;流程/时序/状态机/ER → Markdown 内嵌 ```mermaid(`flowchart`/`sequenceDiagram`/`stateDiagram-v2`/`erDiagram`)。Mermaid 盒子按文本自适应宽、只适合"关系"类;凡需精确像素/比例/高度差一律 SVG 生成器(五级台阶用 Mermaid 会压成同高,"还差一级"看不出来)。
|
||||
|
||||
## 成功输出(默认路径跑通的样子)
|
||||
|
||||
```
|
||||
OK 12345 bytes, canvas 1060x712 -> docs/images/<主题>.svg
|
||||
```
|
||||
|
||||
成功标志是 Chrome 自己打印的 `<N> bytes written to file D:\...`。**回读 PNG 才算目检完成**:
|
||||
即:console 打印 `OK <字节> bytes, canvas <W>x<H> -> <路径>`,且**没有** `OVERFLOW WARN` / `!! N overflow warnings` 行(有 = 文案超宽,回改顶部常量)。
|
||||
|
||||
```ts
|
||||
const r = await tools.read_image({ file_path: "D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" });
|
||||
console.log(r.image.width + "x" + r.image.height, "bytes=" + r.image.bytes); // 应等于 --window-size / 画布
|
||||
```
|
||||
## 失败了 → 去哪读(索引表)
|
||||
|
||||
看什么:文字压框 / 溢出盒外、标签互撞(本窗实测两轮才干净:台阶图首轮"文字压到盒下方 + 标签互撞",第二、三轮才修完)、`wrap` 收尾的省略号 `…`(有 = 文案超长)、虚线与盒边线重叠、配色是否还在调色板里。发现问题**回改生成器常量并重跑预检**,然后**重新截图**(PNG 是派生物,不会自己更新),`--window-size` 跟着 `canvas WxH` 改。
|
||||
失败信息自带稳定键;命中才读对应小节(每节 = 判据 / 处置 / 证据边界 + 逐字原文):
|
||||
|
||||
## 四、md 引用(相对路径)
|
||||
| 键(阶段名 / 报错串) | 什么条件下读 | 去处 |
|
||||
|---|---|---|
|
||||
| `COLLISION_AUDIT` | 大图(几十框几十边)缩略目检看着干净但要查标签压框/走线穿框 | [collision-audit.md](reference/collision-audit.md) → `## COLLISION_AUDIT`;脚本骨架 `reference/svg-collision-audit.py` |
|
||||
| `VISUAL_INSPECT` | Windows 上要"目检"SVG;`--screenshot` 报路径错或无 PNG 落盘 | [visual-inspect.md](reference/visual-inspect.md) → `## VISUAL_INSPECT` |
|
||||
| `GENERATED_FRESH` | `check_generated_fresh.py` 报 DIFF / NEW / 生成器报错 | [generated-fresh.md](reference/generated-fresh.md) → `## GENERATED_FRESH` |
|
||||
| `TRAPS` | 想装渲染器转 PNG、相对路径截图、只预检不回读、手改 SVG、批量 edit 半成品 | [traps.md](reference/traps.md) → `## TRAPS` |
|
||||
| `VERIFY_CHECKLIST` | 提交前逐条勾核 | [verify-checklist.md](reference/verify-checklist.md) → `## VERIFY_CHECKLIST` |
|
||||
|
||||
`docs/` 根的 md:``;`docs/任务规划/`、`docs/UI设计/` 等子目录 md:``(本窗实例:`docs/硬件平台/ADC通道映射说明.md` §9.1 写 ``)。alt 文本写成"这张图的结论是什么",别只重复文件名。
|
||||
## 从零新写生成器(先抄骨架,别裸写)
|
||||
|
||||
## 五、generated-fresh:逐字节幂等门禁(新图长期不假红的前提)
|
||||
1. 先读同目录 1~2 个最近脚本(如 `gen_adc_frontend_svg.py`、`gen_adc_code_scale_svg.py`),抄三条约定:文件头 docstring 写清产物路径 + 图回答什么 + **为什么不用 Mermaid** + 用法;顶部集中常量块(画布/几何 → FONT → 字号 → 调色板 → 文案,坐标由常量推导);纯标准库 helpers(`esc`/`text_w`/`txt`/`line`/`rect`/`wrap`/`check_fit`/`emit`/`build`)。
|
||||
2. 照抄预检三件套 `OVERFLOW=[]` + `check_fit` + `wrap`(估宽:CJK/全角/圈码/箭头 ≈1.0em,其余 ≈0.58em,宁大勿小),标题/盒内标题走 `check_fit`、盒内正文/脚注走 `wrap`;`build()` 末尾 `emit("OK …")` 后 `if OVERFLOW: emit("!! %d overflow warnings" % len(OVERFLOW))`。
|
||||
3. 照抄 `emit()`(GBK 终端不崩的打印地基,见 `GENERATED_FRESH`);路径锚脚本自身位置(临时目录重跑不漂):`ROOT = dirname(dirname(dirname(abspath(__file__))))`,`OUT = os.path.join(ROOT, "docs", "images", "<主题>.svg")`。
|
||||
4. 跑生成把 OVERFLOW 打到 0 再进目检;新脚本落库时**同批**把行加进 `tools/arch_diagram/README.md`「产物清单」(全仓只此一张逐脚本清单,别在第二篇文档另起表)。
|
||||
|
||||
`generated-fresh` 把 `tools/arch_diagram/gen_*.py`(`docs-svg` 项:`per_script: true`、`pattern: gen_*.py`、`mode: exact`)**逐个拷进系统临时目录重跑**,与工作区产物**逐字节**比对:内容不同 = `DIFF`(生成物比生成器旧)、临时目录多出一个工作区没有的文件 = `NEW`、`rc≠0` = 「生成器报错」。由此推出四条硬约束:
|
||||
## 禁令(看着合理但致命,留在主文件)
|
||||
|
||||
1. **生成器只能写那一个 `.svg`**:绝不在脚本里顺手导出 PNG 预览(预览写 `ci-artifacts/`,不进 `docs/images/`)。
|
||||
2. **stdout 不许崩**:GBK 终端遇上 `²` / `−` / CJK 路径会 `UnicodeEncodeError` → 钩子 `rc≠0`,一片假红。所以打印一律走 `emit()`,脚本里不留裸 `print()`(本窗实测:两份新生成器只改了一份,另一份照旧崩)。
|
||||
3. **产物内容零不确定**:SVG 里不写时间戳 / 绝对路径 / 主机名;浮点坐标一律 `%g` / `%.1f` 定形;字典与 `os.listdir` 结果参与布局时先 `sorted()`。
|
||||
4. **`gen_*.py` 命名即自动在册**(pattern 就是 `gen_*.py`)——故意不叫这个名字等于躲开门禁,门禁最大盲区正是"未登记的生成器",别利用它。
|
||||
- **手改 SVG 成品 = 制造"不是我改的"diff**,`generated-fresh` 立刻 DIFF;一切修改落在生成器常量上再重跑,也别退化成 ASCII 框图。
|
||||
- **`docs/images/` 下不许手写 `.svg`、不许放 PNG 预览**(前者没生成器躲过门禁,后者污染"临时目录多文件"判定)。
|
||||
- **别跑不带 `--files`/`--all-files` 的裸 `pre_commit run`**(会 stash 别人在飞的改动)。
|
||||
- **没真渲染出 PNG 不要声称"已目检"**;`wrap` 收尾带 `…` = 文案超长,不是完成。
|
||||
- 生成器**只能写那一个 `.svg`**(别顺手导出 PNG 到 docs/);`gen_*.py` 命名即自动在册,**故意不叫这名字 = 躲门禁,别利用**。
|
||||
- 批量 `edit` 生成器前先 `read` 精确原文逐条改、末尾统一复验——中途抛错时**前面的编辑已落盘**,会留半成品。
|
||||
|
||||
自查(仓库根):
|
||||
## 提交
|
||||
|
||||
```bash
|
||||
.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py
|
||||
sha1sum docs/images/<主题>.svg
|
||||
.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py # 重跑后 sha1 必须不变
|
||||
.venv/Scripts/python.exe scripts/check_generated_fresh.py # 期望 rc=0,无 DIFF/NEW,[BASELINE] 不增
|
||||
```
|
||||
|
||||
```powershell
|
||||
& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py # 单独跑(不 stash 别人在飞的改动)
|
||||
& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py --list # 只看在册声明
|
||||
& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --files tools/arch_diagram/gen_<主题>_svg.py docs/images/<主题>.svg
|
||||
```
|
||||
|
||||
⚠ **别跑不带 `--files` 也不带 `--all-files` 的裸 `pre_commit run`**(会 stash 掉别人在飞的改动);判读口径 → `docs/门禁说明/generated-fresh.md` §4。
|
||||
|
||||
## 六、提交
|
||||
|
||||
生成器脚本(源)+ `docs/images/<主题>.svg`(产物)+ 引用它的 `.md` + `tools/arch_diagram/README.md`「产物清单」那一行**同一笔**提交;PNG 预览不入库。
|
||||
|
||||
```powershell
|
||||
& '.venv\Scripts\python.exe' -m pre_commit run --files <脚本> <svg> <md> <README.md>
|
||||
```
|
||||
|
||||
## 陷阱(本窗实测)
|
||||
|
||||
- **想装渲染器再转 PNG**:`cairosvg` 不在 `.venv`(`ModuleNotFoundError`)、`requirements.txt` 里也没有,`rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在 → 用 §三 的 headless Chrome/Edge(权威命令在 `docs/架构设计/图形绘制流程.md` §四,2026-10-30 已同步成这套,别再往回写)。**没真渲染出 PNG 的情况下不要声称"已目检"。**
|
||||
- **`--screenshot=ci-artifacts/ladder.png`(相对路径)** → `EXIT 2` + `Failed to write file ci-artifacts/ladder.png: 系统找不到指定的路径。 (0x3)`,PNG 压根没落盘;换绝对 Windows 路径后写出 95549 bytes。这条报错**不区分**"相对路径"与"目录不存在"两种成因(实测 `mkdir -p ci-artifacts` 已先跑过、仍报同一句),排查时两条都排。
|
||||
- **只做预检 + 缩略目检就收工(大图)**:`check_fit` 归零、PNG 看着干净,仍可能有二十来条标签压框——节点白底后画会吃掉压上去的标签;大图必须走 §三b 的解析式审计。
|
||||
- **只做预检就收工**:`check_fit` / `OVERFLOW` 归零也不代表干净——本窗实测"门标签压第 5 级盒、蓝底标签挤、多余虚线"三类碰撞只有 PNG 回读看得见;反过来只目检不预检,脚注溢出就得靠眼睛反复量。**两者都要 0**。
|
||||
- **手改 SVG 成品**:等于制造「不是我改的」diff,且 `generated-fresh` 立刻 DIFF;也**不要退化成 ASCII 框图**(图形一律走生成器 / Mermaid,本条是判据)。一切修改都落在生成器常量上再重跑。
|
||||
- **批量改生成器时 `old_string` 不匹配**:一批 `edit` 会在中途抛错,但**前面的编辑已经落盘** → 半成品生成器(本窗实测:`emit` helper 缺失却仍打印 OK,几轮之后才查出)。正解:改前先 `read` 出精确原文,逐条改,末尾统一复验(`grep -n "def emit"`、`grep -c print`、再重跑看 rc 与 OK 行)。
|
||||
- **PNG 尺寸 ≠ 画布**:`--window-size` 忘了跟着 `W`/`H` 改 → 截出来带大片空白或裁掉底部脚注;回读 `r.image.width/height` 与 `canvas WxH` 对一下再判定。
|
||||
- **`docs/images/` 下手写 `.svg` 或放 PNG 预览**:前者没有生成器(NEW / 躲过门禁),后者污染"临时目录多了文件"判定。
|
||||
|
||||
## 验证清单
|
||||
|
||||
- [ ] 生成器输出 `OK … bytes, canvas WxH`,**无** `OVERFLOW WARN` / `!! N overflow warnings`;`grep -n "def emit"` 命中、`grep -c print` = 0。
|
||||
- [ ] 绝对路径 PNG 存在、尺寸 = 画布,`read_image` 回读确认:无文字压框 / 溢出、无标签互撞、无 `…` 截断收尾、配色在调色板内。
|
||||
- [ ] 连跑两次产物 sha1 不变;`scripts/check_generated_fresh.py` rc=0(无 DIFF / NEW,`[BASELINE]` 未增加)。
|
||||
- [ ] 大图(≥20 边):跑一遍 §三b 的碰撞审计,报数归零(标签压框 / 走线穿框 / 标签出画布)。
|
||||
- [ ] 引用它的 `.md` 相对路径正确(根目录 `images/`,子目录 `../images/`);`tools/arch_diagram/README.md`「产物清单」已加行,「挂在」列的 `文档:行号` 用 `grep -rn "<图名>.svg" docs/ --include=*.md` 现扫核对(**别抄旧行号**,行号一漂整列就废)。
|
||||
- [ ] 脚本 + 产物 `.svg` + `.md` + README 行一并暂存;`pre-commit run --files …` 全过(无乱码 / 行尾空白 / 编码 OK)。
|
||||
|
||||
> **与规范文档的分工(2026-10-30 已对齐)**:`docs/架构设计/图形绘制流程.md` 是规范归属(`docs/文档规范.md` §7 的「同一事实只在一处详述」),本 skill 是执行侧。该文档 §3.1 第 4 步与 §四 原先写的「浏览器打开 SVG / 给 `.venv` 装 cairosvg 转 PNG」在本机走不通,已同步成 headless Edge/Chrome 那套(命令只在 §四 详述,本 skill §三 留判据指针);**改渲染命令时两处一起改**——做图判据以本 skill 为准,规范条文以该文档为归属。
|
||||
生成器脚本(源)+ `docs/images/<主题>.svg`(产物)+ 引用它的 `.md` + `tools/arch_diagram/README.md`「产物清单」那一行**同一笔**提交;PNG 预览不入库。提交前 `& '.venv\Scripts\python.exe' -m pre_commit run --files <脚本> <svg> <md> <README.md>`,逐条勾核见 `VERIFY_CHECKLIST`。
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
# 大图碰撞审计(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## COLLISION_AUDIT
|
||||
|
||||
> 路由:主文件失败索引表 `COLLISION_AUDIT` → 本节。原节 `## 三b、大图碰撞审计`(L79–112)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
大图(几十框几十边)仅靠 PNG 缩略目检查不全,需解析式审计。
|
||||
|
||||
### 处置
|
||||
|
||||
解析自己生成的 SVG,按边标签压节点/走线穿框/标签出画布三类判;SVG 侧与生成器真值侧两遍都归零;先验审计器本身(拿已知干净的边试),再信它的 0 条。
|
||||
|
||||
### 证据边界
|
||||
|
||||
42 框 37 边链路图报 23 条为本窗实测;判据脚本假阳性比漏报更贵。脚本骨架在 reference/svg-collision-audit.py。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 三b、大图(几十框几十边)加一道碰撞审计,别只靠眼睛
|
||||
|
||||
边数一多,像素回读就查不全(本窗实测:42 框 37 边的端到端链路图,缩略 PNG 看着干净,
|
||||
审计器一眼报出 23 条:边标签压节点、走线穿框、标签出画布)。做法是**解析自己生成的 SVG**
|
||||
而不是解析渲染结果——`ET.parse` 产物,按 `font-size`/`fill` 分诊文字,估宽口径直接复用生成器的
|
||||
`text_w()`(两边同一把尺子才不会假绿),然后判三件事:
|
||||
|
||||
1. **边标签的「文字盒」vs 节点框**(不是白片盒):交集 > 6 px² 就算问题——节点在边之后画,
|
||||
压上去的**文字**会被节点白底吃掉半个字(本窗症状:「串行执行」渲染成「行执行」)。
|
||||
白片本身压到框边角是**无害**的(白片先画、节点后画,只是盖住一点白底,不改字)。
|
||||
除「有没有压上」,还要打印**文字与最近框的最小水平余量**并按 < 3px 报问题:
|
||||
本窗「TRGO 触发」余量 0.7px、「帧 B 下发」1.5px,都没压上却随时会被真实字宽吃笔画,
|
||||
缩短标签后升到 3.5px 以上才算安全。
|
||||
2. **走线段 vs 节点框**(内缩 2px 再判,排除贴边端点):线穿框是硬伤,改边的出入框方位或独占通道。
|
||||
3. **标签互压 / 出画布**:白片两两求交;`box[3] > H-2` 查脚注贴底。
|
||||
4. **零余量复扫(生成器侧,别只跑 SVG 侧那一遍)**:SVG 反推不出哪两个框是本边端点,
|
||||
走线只能内缩着查 → 1~3px 的切边照不到。用生成器自己的 `Box` / `route()` / `label_at()`
|
||||
真值再扫一遍:框不膨胀不内缩、只跳本边两端。跑 SVG 侧与真值侧两遍都归零才算收工。
|
||||
|
||||
脚本骨架与判据见 `reference/svg-collision-audit.py`(可直接拷进 `ci-artifacts/` 当一次性工具用,
|
||||
**别放 `tools/arch_diagram/`**——那里只放生成器,非 `gen_*.py` 的脚本混进去会让人以为在册)。
|
||||
|
||||
配套的两条几何纪律(都是本窗踩出来的):
|
||||
|
||||
- **同轴直连不要插退化折点**:同行两框若按「同轴 → 加一段 gx 走廊」的通用规则生成,会产出
|
||||
`[(195,176),(219,176),(219,176),(243,176)]` 这种点集——线还是直的,但**标签落点算成第一半的中点**,
|
||||
整格偏移半个通道 → 压框。正解:出框轴与入框轴同轴且已对齐时直接返回两点线。
|
||||
- **标签落点用弧长中点,不用「最长段中点」**:多段折线里最长段可能有多条(对称 Z 字),
|
||||
取第一条会把标签推到拐角上;沿总弧长取 50% 再定位,配合 `seg`/`t` 旋钮微调。
|
||||
|
||||
**先验审计器本身,再信它的「0 条」**:本窗把 `hi > y0` 复制粘贴成 `hi > x0`,零余量那一遍
|
||||
凭空报出 3 条「穿框」,差点为此重排三条边的走线。判据脚本的假阳性比漏报更贵——它会让你
|
||||
去改一张本来没问题的图。规矩:写完后挑一条**已知干净**的边(例如两框正对的直连边)单独跑一遍,
|
||||
确认它不报,再跑全量。
|
||||
@@ -0,0 +1,45 @@
|
||||
# generated-fresh 逐字节幂等门禁(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## GENERATED_FRESH
|
||||
|
||||
> 路由:主文件失败索引表 `GENERATED_FRESH` → 本节。原节 `## 五、generated-fresh`(L157–181)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
`check_generated_fresh.py` 报 DIFF / NEW / 生成器报错 = 产物与生成器不同步。
|
||||
|
||||
### 处置
|
||||
|
||||
生成器只写一个 .svg;打印一律走 emit()(防 GBK 崩);产物零不确定(时间戳/绝对路径/主机名不写,浮点定形,字典排序);连跑两次 sha1 不变。
|
||||
|
||||
### 证据边界
|
||||
|
||||
gen_*.py 命名即自动在册(门禁最大盲区是未登记生成器);裸 pre_commit run 会 stash 别人改动,判读见 docs/门禁说明/generated-fresh.md §4。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 五、generated-fresh:逐字节幂等门禁(新图长期不假红的前提)
|
||||
|
||||
`generated-fresh` 把 `tools/arch_diagram/gen_*.py`(`docs-svg` 项:`per_script: true`、`pattern: gen_*.py`、`mode: exact`)**逐个拷进系统临时目录重跑**,与工作区产物**逐字节**比对:内容不同 = `DIFF`(生成物比生成器旧)、临时目录多出一个工作区没有的文件 = `NEW`、`rc≠0` = 「生成器报错」。由此推出四条硬约束:
|
||||
|
||||
1. **生成器只能写那一个 `.svg`**:绝不在脚本里顺手导出 PNG 预览(预览写 `ci-artifacts/`,不进 `docs/images/`)。
|
||||
2. **stdout 不许崩**:GBK 终端遇上 `²` / `−` / CJK 路径会 `UnicodeEncodeError` → 钩子 `rc≠0`,一片假红。所以打印一律走 `emit()`,脚本里不留裸 `print()`(本窗实测:两份新生成器只改了一份,另一份照旧崩)。
|
||||
3. **产物内容零不确定**:SVG 里不写时间戳 / 绝对路径 / 主机名;浮点坐标一律 `%g` / `%.1f` 定形;字典与 `os.listdir` 结果参与布局时先 `sorted()`。
|
||||
4. **`gen_*.py` 命名即自动在册**(pattern 就是 `gen_*.py`)——故意不叫这个名字等于躲开门禁,门禁最大盲区正是"未登记的生成器",别利用它。
|
||||
|
||||
自查(仓库根):
|
||||
|
||||
```bash
|
||||
.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py
|
||||
sha1sum docs/images/<主题>.svg
|
||||
.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py # 重跑后 sha1 必须不变
|
||||
.venv/Scripts/python.exe scripts/check_generated_fresh.py # 期望 rc=0,无 DIFF/NEW,[BASELINE] 不增
|
||||
```
|
||||
|
||||
```powershell
|
||||
& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py # 单独跑(不 stash 别人在飞的改动)
|
||||
& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py --list # 只看在册声明
|
||||
& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --files tools/arch_diagram/gen_<主题>_svg.py docs/images/<主题>.svg
|
||||
```
|
||||
|
||||
⚠ **别跑不带 `--files` 也不带 `--all-files` 的裸 `pre_commit run`**(会 stash 掉别人在飞的改动);判读口径 → `docs/门禁说明/generated-fresh.md` §4。
|
||||
@@ -0,0 +1,30 @@
|
||||
# 陷阱(本窗实测,自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## TRAPS
|
||||
|
||||
> 路由:主文件失败索引表 `TRAPS` → 本节。原节 `## 陷阱(本窗实测)`(L191–200)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
命中具体症状(装渲染器/相对路径截图/只预检不回读/手改 SVG/批量 edit 半成品/PNG 尺寸错)时读本节。
|
||||
|
||||
### 处置
|
||||
|
||||
逐条按原文处置。
|
||||
|
||||
### 证据边界
|
||||
|
||||
全部为本窗实测(2026-10-29/30),换机器须重验。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 陷阱(本窗实测)
|
||||
|
||||
- **想装渲染器再转 PNG**:`cairosvg` 不在 `.venv`(`ModuleNotFoundError`)、`requirements.txt` 里也没有,`rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在 → 用 §三 的 headless Chrome/Edge(权威命令在 `docs/架构设计/图形绘制流程.md` §四,2026-10-30 已同步成这套,别再往回写)。**没真渲染出 PNG 的情况下不要声称"已目检"。**
|
||||
- **`--screenshot=ci-artifacts/ladder.png`(相对路径)** → `EXIT 2` + `Failed to write file ci-artifacts/ladder.png: 系统找不到指定的路径。 (0x3)`,PNG 压根没落盘;换绝对 Windows 路径后写出 95549 bytes。这条报错**不区分**"相对路径"与"目录不存在"两种成因(实测 `mkdir -p ci-artifacts` 已先跑过、仍报同一句),排查时两条都排。
|
||||
- **只做预检 + 缩略目检就收工(大图)**:`check_fit` 归零、PNG 看着干净,仍可能有二十来条标签压框——节点白底后画会吃掉压上去的标签;大图必须走 §三b 的解析式审计。
|
||||
- **只做预检就收工**:`check_fit` / `OVERFLOW` 归零也不代表干净——本窗实测"门标签压第 5 级盒、蓝底标签挤、多余虚线"三类碰撞只有 PNG 回读看得见;反过来只目检不预检,脚注溢出就得靠眼睛反复量。**两者都要 0**。
|
||||
- **手改 SVG 成品**:等于制造「不是我改的」diff,且 `generated-fresh` 立刻 DIFF;也**不要退化成 ASCII 框图**(图形一律走生成器 / Mermaid,本条是判据)。一切修改都落在生成器常量上再重跑。
|
||||
- **批量改生成器时 `old_string` 不匹配**:一批 `edit` 会在中途抛错,但**前面的编辑已经落盘** → 半成品生成器(本窗实测:`emit` helper 缺失却仍打印 OK,几轮之后才查出)。正解:改前先 `read` 出精确原文,逐条改,末尾统一复验(`grep -n "def emit"`、`grep -c print`、再重跑看 rc 与 OK 行)。
|
||||
- **PNG 尺寸 ≠ 画布**:`--window-size` 忘了跟着 `W`/`H` 改 → 截出来带大片空白或裁掉底部脚注;回读 `r.image.width/height` 与 `canvas WxH` 对一下再判定。
|
||||
- **`docs/images/` 下手写 `.svg` 或放 PNG 预览**:前者没有生成器(NEW / 躲过门禁),后者污染"临时目录多了文件"判定。
|
||||
@@ -0,0 +1,28 @@
|
||||
# 验证清单(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## VERIFY_CHECKLIST
|
||||
|
||||
> 路由:主文件失败索引表 `VERIFY_CHECKLIST` → 本节。原节 `## 验证清单`(L202–209)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
提交前逐条勾核完方可收工。
|
||||
|
||||
### 处置
|
||||
|
||||
按原文清单六条逐项比对。
|
||||
|
||||
### 证据边界
|
||||
|
||||
「挂在」列行号须现扫不抄旧(行号一漂整列就废)。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 验证清单
|
||||
|
||||
- [ ] 生成器输出 `OK … bytes, canvas WxH`,**无** `OVERFLOW WARN` / `!! N overflow warnings`;`grep -n "def emit"` 命中、`grep -c print` = 0。
|
||||
- [ ] 绝对路径 PNG 存在、尺寸 = 画布,`read_image` 回读确认:无文字压框 / 溢出、无标签互撞、无 `…` 截断收尾、配色在调色板内。
|
||||
- [ ] 连跑两次产物 sha1 不变;`scripts/check_generated_fresh.py` rc=0(无 DIFF / NEW,`[BASELINE]` 未增加)。
|
||||
- [ ] 大图(≥20 边):跑一遍 §三b 的碰撞审计,报数归零(标签压框 / 走线穿框 / 标签出画布)。
|
||||
- [ ] 引用它的 `.md` 相对路径正确(根目录 `images/`,子目录 `../images/`);`tools/arch_diagram/README.md`「产物清单」已加行,「挂在」列的 `文档:行号` 用 `grep -rn "<图名>.svg" docs/ --include=*.md` 现扫核对(**别抄旧行号**,行号一漂整列就废)。
|
||||
- [ ] 脚本 + 产物 `.svg` + `.md` + README 行一并暂存;`pre-commit run --files …` 全过(无乱码 / 行尾空白 / 编码 OK)。
|
||||
@@ -0,0 +1,58 @@
|
||||
# 目检(Windows SVG 渲染,自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## VISUAL_INSPECT
|
||||
|
||||
> 路由:主文件失败索引表 `VISUAL_INSPECT` → 本节。原节 `## 三、目检`(L114–151)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
需回读 PNG 才算目检完成;无 PNG 不得声称已目检。
|
||||
|
||||
### 处置
|
||||
|
||||
headless Chrome/Edge `--headless=new` + 绝对 Windows 路径截图 → `read_image` 回读,看文字压框/标签互撞/`…` 截断/配色。
|
||||
|
||||
### 证据边界
|
||||
|
||||
本仓 .venv 无 cairosvg、无 rsvg-convert/inkscape;旧 `--headless` 成时不成(2026-10-29 实测),固定用 `--headless=new`。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 三、目检(Windows:本机没有任何现成 SVG 渲染器)
|
||||
|
||||
**先探测,别照抄 cairosvg 命令**:本仓 `.venv` 无 `cairosvg`(`ModuleNotFoundError: No module named 'cairosvg'`),`rsvg-convert` 不存在,只有 Edge / Chrome:
|
||||
|
||||
```bash
|
||||
# ops_bash(git-bash)里探测;哪个存在用哪个
|
||||
ls -1 "/c/Program Files/Google/Chrome/Application/chrome.exe" \
|
||||
"/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" 2>/dev/null
|
||||
command -v rsvg-convert inkscape magick convert 2>/dev/null || echo "no CLI rasterizer"
|
||||
```
|
||||
|
||||
```powershell
|
||||
Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe"
|
||||
Test-Path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
|
||||
```
|
||||
|
||||
截图(**`--screenshot=` 必须给绝对 Windows 路径 + 绝对 `file:///` 输入**,并且**固定用
|
||||
`--headless=new`**:本窗用旧 `--headless` 同一套命令时成时不成——一次写出了 168 KB,
|
||||
下一次静默不写文件;也别把 stderr 丢进 `/dev/null`,成功标志就是它自己打印的那行字数):
|
||||
|
||||
```bash
|
||||
mkdir -p ci-artifacts # Chrome 没有建目录的参数,先自己建
|
||||
OUT="D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" # 绝对路径、反斜杠
|
||||
"/c/Program Files/Google/Chrome/Application/chrome.exe" \
|
||||
--headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=1 \
|
||||
--window-size=1060,712 \
|
||||
--screenshot="$OUT" \
|
||||
"file:///D:/Code/DTU Code/<工作树名>/docs/images/<主题>.svg" 2>&1 | tail -2
|
||||
```
|
||||
|
||||
成功标志是 Chrome 自己打印的 `<N> bytes written to file D:\...`。**回读 PNG 才算目检完成**:
|
||||
|
||||
```ts
|
||||
const r = await tools.read_image({ file_path: "D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" });
|
||||
console.log(r.image.width + "x" + r.image.height, "bytes=" + r.image.bytes); // 应等于 --window-size / 画布
|
||||
```
|
||||
|
||||
看什么:文字压框 / 溢出盒外、标签互撞(本窗实测两轮才干净:台阶图首轮"文字压到盒下方 + 标签互撞",第二、三轮才修完)、`wrap` 收尾的省略号 `…`(有 = 文案超长)、虚线与盒边线重叠、配色是否还在调色板里。发现问题**回改生成器常量并重跑预检**,然后**重新截图**(PNG 是派生物,不会自己更新),`--window-size` 跟着 `canvas WxH` 改。
|
||||
@@ -24,6 +24,13 @@ python tools/font_gen/extract_cn.py # 扫描 UI 源码字符串 →
|
||||
# 4. diff 检查:新增字在位、旧字不变、生成物 Opts 行字符集与预期一致
|
||||
```
|
||||
|
||||
**成功输出样例**(本轮实跑 `scripts/check_font_charset.py`,`PYTHONIOENCODING=utf-8`):看到 `coverage OK: 230 个字符全部进字体` + `结果: PASS` 就是通了,不用再往下看。
|
||||
|
||||
```text
|
||||
coverage OK: 230 个字符全部进字体
|
||||
结果: PASS(必需字符(源码在用 ∪ 保留清单)全部在字体子集内;10 个保留字在位)
|
||||
```
|
||||
|
||||
## 提交清单
|
||||
|
||||
`ui_cn_chars.txt`(仓库根)+ `Drivers/BSP/UI/ui_font_cn_12.c` **随代码一起提交**,缺一个都会让另一端/下次构建字体与字集不一致。
|
||||
|
||||
@@ -64,15 +64,9 @@ version: 1.1.0
|
||||
9. 收尾复跑 + 清中间产物
|
||||
> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [steps-chinese-prefix-family.md](reference/steps-chinese-prefix-family.md)。动手前先读那篇。
|
||||
|
||||
## 不可判定引用绝对数涨点的净室归因
|
||||
## 涨点归因(只在不可判定引用绝对数涨点时读)
|
||||
|
||||
「不可判定引用绝对数」比今日低点涨了 N 处时:
|
||||
|
||||
1. **禁止**用「对提交新增行 grep 字母+数字形态」归因:`git diff -U0` 的加行里绝大多数文本是从旧行搬来的**存量上下文**(注释整段重写、表格加一列、Markdown 重新折行),形态匹配数出来的是「哪段文字最近被搬动」,不是「哪里涨了 N 处」——用它归因必然把老引用算成增量。`diff -U0` 只在**已定位到文件之后**用来绑笔次与行号。
|
||||
2. **正解 A(首选,同一计数器相减)**:在**仓外 detached worktree 跑 HEAD 版**(`task-worktree` skill 的净室测量仪;不 stash、不碰在飞工作区),两边都用同一个 `check_ids.py` 计数器导出 `(rel, literal)` 多重集(`ck.findings` 或 `err_groups(ck)`),做**逐文件集合差**,落差的 N 处直接指向具体文件与字面量。
|
||||
3. **正解 B(逐文件注入)**:一次只把一个文件换成在飞版跑计数器——涨点在哪个文件上,就只在注入它时出现;文件多时按 `git diff --name-only` 折半。
|
||||
4. **当轮跑不完就如实说**:本轮未跑净室归因时,只报「现值需要重新实测」并说明**需要跑净室归因**,**不得**给出候选归因对象,**不得**把上一轮的现值或余量当本回合实测值报出(每个数标明来源与时刻)。
|
||||
5. 与其它交付口径冲突的差值**登记为待查项**(两套计数可能都对),不当场判谁对谁错。
|
||||
- [ ] **attribution** → 涨了 N 处要定位落在哪个文件时,读 [attribution.md](reference/attribution.md) 的 `attribution` 节;禁止拿 diff 新增行 grep 形态归因。
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -104,16 +98,6 @@ version: 1.1.0
|
||||
- *.uvprojx 抖动不入库
|
||||
> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。
|
||||
|
||||
## Verification
|
||||
## 收口验收(只在收口/回报验收清单时读)
|
||||
|
||||
1. `scripts/archive/id_gate/check_ids.py --strict` 与 plain **均 rc=0**(`[OK] 校验 1~6 无错误`),悬空引用为 0。
|
||||
2. 编号字面量与**不可判定引用绝对数**只降不升、不超 `undecidable_total_ceiling`;可判定比例不低于 `id_registry.json` 基线(86.0%)。
|
||||
3. 本族剩余站点复扫归零:有识别面族从 `ck.refs` 按族正则过滤字面量逐条打印;除冻结历史/原始证据行外无残留。
|
||||
4. `pre-commit run generated-fresh --all-files` PASS + 目检 svg diff 只有文案与框宽自适应(只在动过生成器时适用);`check_doc_links.py --all` 通过。
|
||||
5. `/keil-build`:`BUILD=0`、0 错 0 警、`Program Size` 与改前同数(零行为改动证据,**本回合真跑**);相关主机组(如 `net_socket 457/457`)全绿。
|
||||
6. 真实 pre-commit 钩子全绿(如 `passed=33 failed=0`);提交笔内不含他道文件。
|
||||
7. 规范与台账已回写并复跑核数:自己先前写进规范的清点数字要么按最终实测改对,要么标明为动手前基线;「等你裁定」残留 = 0;「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地(原「变更记录」那一处已随 2026-10-28 清流水退场)。
|
||||
8. **无识别面族**:`git grep -nE '卡[ ]*[0-9]' -- .` 无输出(裸跑读 rc);自建扫描器的站点/文件数与提交正文一致;交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由;§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全,换算表行数 = 该族字面量数(实测 14),且写明旧号永久作废、不得重新取走。
|
||||
9. **二次清洗三道各有实测数**:同句重复短语 0 行、各空格形态先计数后归一(复扫 0)、固定正则残留 0;被代码头注释引用的设计约束章节仍在(`git diff` 里没被动过)。
|
||||
10. **叙述同步**:`docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md`(已删除)里旧口径(「三项」「卡 N」类)实测归零;`ci-artifacts/` 里本次 spec 与中间产物已删。
|
||||
11. 门禁复跑清单齐:`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。
|
||||
- [ ] **verification** → 逐条打勾的 11 项验收清单(门禁 rc、残留归零、零行为改动、叙述同步等)→ 读 [verification.md](reference/verification.md) 的 `verification` 节。
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# 不可判定引用绝对数涨点的净室归因(自 SKILL.md 同名节逐字外置)
|
||||
|
||||
> 何时读:仅当「不可判定引用绝对数」比基线低点涨了 N 处、需要定位涨在哪个文件时。正常清退流程不展开本篇。
|
||||
> 主文件 frontmatter 提到的「涨点归因一节会用到净室 worktree」指的就是这里。
|
||||
|
||||
## attribution
|
||||
|
||||
**判据(逐字保留原文,未改写)**:
|
||||
|
||||
「不可判定引用绝对数」比今日低点涨了 N 处时:
|
||||
|
||||
1. **禁止**用「对提交新增行 grep 字母+数字形态」归因:`git diff -U0` 的加行里绝大多数文本是从旧行搬来的**存量上下文**(注释整段重写、表格加一列、Markdown 重新折行),形态匹配数出来的是「哪段文字最近被搬动」,不是「哪里涨了 N 处」——用它归因必然把老引用算成增量。`diff -U0` 只在**已定位到文件之后**用来绑笔次与行号。
|
||||
2. **正解 A(首选,同一计数器相减)**:在**仓外 detached worktree 跑 HEAD 版**(`task-worktree` skill 的净室测量仪;不 stash、不碰在飞工作区),两边都用同一个 `check_ids.py` 计数器导出 `(rel, literal)` 多重集(`ck.findings` 或 `err_groups(ck)`),做**逐文件集合差**,落差的 N 处直接指向具体文件与字面量。
|
||||
3. **正解 B(逐文件注入)**:一次只把一个文件换成在飞版跑计数器——涨点在哪个文件上,就只在注入它时出现;文件多时按 `git diff --name-only` 折半。
|
||||
4. **当轮跑不完就如实说**:本轮未跑净室归因时,只报「现值需要重新实测」并说明**需要跑净室归因**,**不得**给出候选归因对象,**不得**把上一轮的现值或余量当本回合实测值报出(每个数标明来源与时刻)。
|
||||
5. 与其它交付口径冲突的差值**登记为待查项**(两套计数可能都对),不当场判谁对谁错。
|
||||
|
||||
**处置**:按正解 A 首选、正解 B 兜底;跑不完就如实说,不猜归因对象。
|
||||
|
||||
**证据边界**:本篇只解决「涨点落在哪个文件」,不解决「该文件该不该改」——后者按主文件「动手前先判有没有机器识别面」与 steps 两篇的分类口径处理。
|
||||
@@ -0,0 +1,24 @@
|
||||
# 收口验收清单(自 SKILL.md「Verification」一节逐字外置)
|
||||
|
||||
> 何时读:收口、回报验收清单、分笔提交前。主文件只留一行索引;动手过程中不要展开本篇。
|
||||
> 本篇只讲「怎么算做完了」,逐处替换时的命中数断言仍以 steps 两篇为准。
|
||||
|
||||
## verification
|
||||
|
||||
**判据(逐条打勾)**:下面 11 条来自原 SKILL.md「Verification」节,逐字保留、未改写。
|
||||
|
||||
1. `scripts/archive/id_gate/check_ids.py --strict` 与 plain **均 rc=0**(`[OK] 校验 1~6 无错误`),悬空引用为 0。
|
||||
2. 编号字面量与**不可判定引用绝对数**只降不升、不超 `undecidable_total_ceiling`;可判定比例不低于 `id_registry.json` 基线(86.0%)。
|
||||
3. 本族剩余站点复扫归零:有识别面族从 `ck.refs` 按族正则过滤字面量逐条打印;除冻结历史/原始证据行外无残留。
|
||||
4. `pre-commit run generated-fresh --all-files` PASS + 目检 svg diff 只有文案与框宽自适应(只在动过生成器时适用);`check_doc_links.py --all` 通过。
|
||||
5. `/keil-build`:`BUILD=0`、0 错 0 警、`Program Size` 与改前同数(零行为改动证据,**本回合真跑**);相关主机组(如 `net_socket 457/457`)全绿。
|
||||
6. 真实 pre-commit 钩子全绿(如 `passed=33 failed=0`);提交笔内不含他道文件。
|
||||
7. 规范与台账已回写并复跑核数:自己先前写进规范的清点数字要么按最终实测改对,要么标明为动手前基线;「等你裁定」残留 = 0;「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地(原「变更记录」那一处已随 2026-10-28 清流水退场)。
|
||||
8. **无识别面族**:`git grep -nE '卡[ ]*[0-9]' -- .` 无输出(裸跑读 rc);自建扫描器的站点/文件数与提交正文一致;交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由;§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全,换算表行数 = 该族字面量数(实测 14),且写明旧号永久作废、不得重新取走。
|
||||
9. **二次清洗三道各有实测数**:同句重复短语 0 行、各空格形态先计数后归一(复扫 0)、固定正则残留 0;被代码头注释引用的设计约束章节仍在(`git diff` 里没被动过)。
|
||||
10. **叙述同步**:`docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md`(已删除)里旧口径(「三项」「卡 N」类)实测归零;`ci-artifacts/` 里本次 spec 与中间产物已删。
|
||||
11. 门禁复跑清单齐:`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。
|
||||
|
||||
**处置**:任一条不通过就退回补证,不要带着未打勾项进下一批;回报时逐处列「文件 + 命中数断言」,不要笼统说「已全部更新」。
|
||||
|
||||
**证据边界**:本清单是**收口判据**,不替代每一步替换时的命中数断言;第 2 条的「不可判定引用绝对数」涨点若本轮未跑净室归因(见主文件「不可判定引用绝对数涨点的净室归因」节),只报「现值需重新实测」,不得给出候选归因对象。
|
||||
+43
-169
@@ -6,191 +6,65 @@ whenToUse: "需要编译 Keil MDK 工程、跑 /keil-build 验证代码改动(
|
||||
|
||||
# keil-build — Keil 命令行编译(独立可运行 skill)
|
||||
|
||||
**执行体 = 本 skill 自带脚本** `.dsh/skills/keil-build/scripts/keil_build.py`
|
||||
(纯标准库,任意 python3;拷整个 skill 目录到别的 Keil 项目即可用,不依赖仓库脚本)。
|
||||
执行体 = 本 skill 自带脚本 `.dsh/skills/keil-build/scripts/keil_build.py`(纯标准库,任意 python3;拷整个 skill 目录到别的 Keil 项目即用,不依赖仓库脚本)。
|
||||
|
||||
## 默认路径:一条命令跑通
|
||||
|
||||
仓库根目录,PowerShell 形态(本 skill 的编译入口):
|
||||
|
||||
```powershell
|
||||
# cwd = 项目根目录;PowerShell 形态(本 skill 的编译入口)
|
||||
& $PY ".dsh\skills\keil-build\scripts\keil_build.py"
|
||||
# 覆盖:--project X.uvprojx --uv4 UV4.exe --target 名字 --log 路径 --timeout 600
|
||||
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
|
||||
```
|
||||
|
||||
⚠ **改本文件 frontmatter 要么整值加双引号,要么一个 ASCII 冒号都别写**(2026-10-30 这份就因此整份加载失败)。
|
||||
DSH 用 `yaml` 包的 `parse()` 读 frontmatter(`@deepseek-ai/dsh-skill-filesystem` 的 `parseFrontmatter()`),
|
||||
plain scalar 里出现 **ASCII「冒号 + 空格」**(例如把报错原文 `BUILD_ENV_ERROR: UV4.exe not found` 或
|
||||
`pw: 前缀` 直接写进 description)就报 `Nested mappings are not allowed in compact mappings at line 2,
|
||||
column 14` → **技能整份不加载**(`skill()` 读不到、也不进技能目录)。**`js-yaml` 能吃下去** ——
|
||||
拿它自检会假绿,必须用 DSH 自带的那个解析器验。另 — 值首字符不能是 `%`(directive indicator)或 `&`
|
||||
(anchor),双引号里的 `%SystemDrive%` 之类不受影响。落盘后**让 DSH 真加载一次**再收口。
|
||||
bash / `ops_bash` 形态(去掉前导 `&`、路径改正斜杠,退出码归 python):
|
||||
|
||||
## 调用形态:先认执行器是哪个 shell(2026-10-26 实测)
|
||||
```bash
|
||||
'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py; echo BUILD_RC=$?
|
||||
```
|
||||
|
||||
- 同一条编译命令,PowerShell 与 bash 是两种写法:bash 侧要去掉前导 & 并把路径改正斜杠(照抄本文末「PowerShell 形态」整段进 ops_bash 会语法错秒退 exit 2)
|
||||
- ⚠ 那个 exit 2 不是脚本的环境错误 2:stderr 含 syntax error near unexpected token = 写法问题,换 bash 形态重跑,别去查 DTU_KEIL_UV4、别当环境错误排障
|
||||
- 后台跑(run_in_background: true)要自己收码,且别把脚本接进管道:实测 $? 取到的是 tail 的码(恒 0);要看报错行就单独 grep MDK-ARM/build_log.txt
|
||||
- 解析顺序:命令行 > 项目档案 .serialtest/config.json > 环境 > 探测;UV4 显式设了但路径无效 = 立即报错,不静默回退
|
||||
- 退出码 0=PASS(0错0警) / 1=构建失败 / 2=环境错误 / 3=用法 / 4=build 锁被占用;2026-10-12 修正过 2 与 3 的归属,该篇末尾记了前后口径
|
||||
- **bash / `ops_bash` 侧「构建到底过没过」的一次自查**(2026-10-26 实测口径):先 `cd` 到仓库根(或该 worktree 根),跑 `.venv/Scripts/python.exe .dsh/skills/keil-build/scripts/keil_build.py; echo BUILD_RC=$?` —— 正斜杠、**无前导 `&`**,退出码归 python、不归 bash;再单独读日志计数 `grep -a -E "Error\(s\)|error:|Warning\(s\)" MDK-ARM/build_log.txt`。报结论要三样齐 —— **`BUILD_RC=0` + `UV4_RC: 0` + `BUILD_OK: 0 errors, 0 warnings`**(脚本自己判「无 `error:` 行 且 尾行含 `0 Error(s), 0 Warning(s)`」);bash 吐的 `syntax error near unexpected token` **既不是构建通过也不是构建失败**,那是写法问题,别拿它当构建结论报。
|
||||
> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [executor-shell-forms.md](reference/executor-shell-forms.md)。动手前先读那篇。
|
||||
「技能调用名 `/keil-build`」不是 shell 命令——原样敲进终端是 command not found;可执行形态永远是上面这条命令行。判定口径(与原 `MDK-ARM/build.bat` 同款,该文件 2026-10-10 已删):先删旧日志 → `-b -j0 -o` → 无 `error:` 且含 `0 Error(s), 0 Warning(s)`。解析顺序 = 命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测;UV4 显式设了但路径无效立即报错,不静默回退。
|
||||
|
||||
## exit 2 实战闭环:`UV4.exe not found` 的探测 → 注入 → 复核(2026-10-30 实测)
|
||||
退出码:`0`=PASS(0 错 0 警)/ `1`=构建失败 / `2`=环境错误或 bash 写法错(先看 stderr)/ `3`=用法 / `4`=build 锁占用。警告也算失败,PASS 只认退出码 0。
|
||||
|
||||
**先定性,别动源码**:脚本报
|
||||
`BUILD_ENV_ERROR: UV4.exe not found (--uv4 / config 'uv4' / $DSH_KEIL_UV4 / $DTU_KEIL_UV4 / PATH)`
|
||||
且**退出码 2** = **环境错,不是构建失败**——本次 **UV4 根本没启动、`MDK-ARM/build_log.txt` 也没被改写**,
|
||||
日志里看到的是上一次的。此时去改 `.c`/`.h` 或怀疑代码,就是把环境问题当编译问题排。
|
||||
(会话为什么看不见:DSH 会话的 shell 由常驻服务派生,**服务启动之后**设的用户级变量不会自动进来;
|
||||
`run_code` 起的 Node 进程 `process.env` 干脆是空的(同一机制另见 `new-machine-setup` skill「实测坑」)。
|
||||
所以**变量"已设但本会话看不见"是常态**,不是用户没设。)
|
||||
## 成功输出(三样齐 + 外层退出码 0 才算构建通过)
|
||||
|
||||
1. **探测候选安装路径**(逐个 `fs.existsSync` / `test -f`,命中即取绝对路径)——
|
||||
`C:/Keil_v5/UV4/UV4.exe`、`C:/Keil/UV4/UV4.exe`、`D:/Keil_v5/UV4/UV4.exe`、`D:/Keil/UV4/UV4.exe`、
|
||||
`C:/Program Files/Keil_v5/UV4/UV4.exe`、`D:/Program Files/Keil_v5/UV4/UV4.exe`
|
||||
(2026-10-30 实测只命中 `C:/Keil_v5/UV4/UV4.exe`,其余五个都不存在)。
|
||||
```bash
|
||||
for p in 'C:/Keil_v5/UV4/UV4.exe' 'C:/Keil/UV4/UV4.exe' 'D:/Keil_v5/UV4/UV4.exe' \
|
||||
'D:/Keil/UV4/UV4.exe' 'C:/Program Files/Keil_v5/UV4/UV4.exe' 'D:/Program Files/Keil_v5/UV4/UV4.exe'; do
|
||||
[ -f "$p" ] && echo "HIT $p"; done
|
||||
```
|
||||
2. **读用户级来源确认"值本来就对"**(同一轮里顺手做掉,别只靠猜路径):
|
||||
bash / Node 侧 `reg query HKCU\Environment`(整表打出来再找 `DTU_KEIL_UV4` / `DSH_KEIL_UV4`),
|
||||
PowerShell 侧 `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`。
|
||||
有值 → 直接用它;没值/值指向旧目录 → 用第 1 步的命中路径。
|
||||
⚠ **不替用户改全局**:不要 `setx`、不要 `SetEnvironmentVariable(...,'User')`——那是用户自己在真终端里
|
||||
做的事(`docs/环境与部署/本地工具路径环境变量方案.md`);本闭环只解决"这一次构建怎么跑起来",
|
||||
报告里也必须这么写。
|
||||
3. **只给这一次调用注入**再重跑(两种等价形态,二选一):
|
||||
```js
|
||||
// run_code:options.env 是**整体替换**,所以要连 SystemRoot / Path / USERPROFILE 一起给
|
||||
const { execSync } = await import('node:child_process');
|
||||
execSync('".venv/Scripts/python.exe" .dsh/skills/keil-build/scripts/keil_build.py', {
|
||||
cwd: MAIN, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
|
||||
env: { SystemRoot: 'C:\\Windows', Path: 'C:\\Windows;C:\\Windows\\System32',
|
||||
USERPROFILE: 'C:\\Users\\<你>', DTU_KEIL_UV4: 'C:\\Keil_v5\\UV4\\UV4.exe' } });
|
||||
```
|
||||
- bash / `ops_bash` 侧的等价写法 = 显式参数 `--uv4 'C:\Keil_v5\UV4\UV4.exe'`(值含空格要整体加引号)。
|
||||
- `run_code` 的 `timeoutMs` 给足:注入后这次构建实测 **10 s** 跑完,但首次冷构建更长(我给的 500000)。
|
||||
- **别顺手加 `--no-lock`**:注入重跑时锁链照旧(`LOCK: 已获取 build 锁(task=build-cli)` → `已释放锁`)。
|
||||
4. **复核口径**(三样齐了才算真跑过,缺一样就是没构建):脚本回显
|
||||
`UV4: <绝对路径> (<来源>)`(来源随注入方式变:`$DTU_KEIL_UV4` 或 `--uv4`)→
|
||||
`UV4_RC: 0` → `BUILD_OK: 0 errors, 0 warnings`,且**外层退出码 0**(自己包 execSync 就显式把码打出来,
|
||||
别接管道,见「调用形态」)。报告里写清"本次注入 + 来源",**不得声称已永久设置系统/用户环境变量**。
|
||||
```
|
||||
UV4: C:\Keil_v5\UV4\UV4.exe ($DTU_KEIL_UV4)
|
||||
UV4_RC: 0
|
||||
BUILD_OK: 0 errors, 0 warnings
|
||||
BUILD_RC=0
|
||||
```
|
||||
|
||||
- ⚠ 注入的若是**注册表里那个陈旧值**,会撞同族的另一种 2:
|
||||
`BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: … (fix the value; no silent fallback)`
|
||||
—— 值在但指向旧盘符/旧目录名(本仓踩过 `D:\Code\DTU 程序\…` 搬迁)。脚本**刻意不静默回退**,
|
||||
回到第 1 步用探测命中的路径覆盖它,别去猜目录、更别改脚本让它"猜 C 盘"(设计上明确禁止从旧路径猜)。
|
||||
- ⚠ 本闭环只回答"UV4 在哪儿",**不回答"调用写法对不对"**:从 bash 侧照抄 PowerShell 的 `&` 也是 exit 2,
|
||||
但 stderr 是 `syntax error near unexpected token`(见「调用形态」)。**先看 stderr 再决定排障方向**,
|
||||
两种 2 的处置完全不同。
|
||||
- **改 `.c` 注释(哪怕只改一行中文注释)也必须跑完这道构建验证**:2026-10-30 的实测就是
|
||||
「改注释 → `/keil-build` → 吃 rc=2 → 探测+注入 → 10 s 通过」。注释类坑(BOM 被剥 → `#870-D`、
|
||||
注释里写 `**` 路径 → 9-D)只在**重编译那个 TU 时**才暴露,"以前 0 警告"不代表安全。
|
||||
## 失败了 → 去哪读(索引表)
|
||||
|
||||
## build 锁:脚本自持自释(2026-10-12)
|
||||
失败信息自带稳定键;按该键读对应小节的「判据 / 处置 / 证据边界」:
|
||||
|
||||
**UV4 不能两个实例同时 `-b`,但构建锁不该由调用方"记得释放"**——那正是泄漏源:
|
||||
Agent 手工 `lock acquire build` 后忘了 `release`,锁要挂到 TTL 才被接管。
|
||||
故本脚本**自己**管:进入 acquire → `try` 构建 → `finally` **无条件** release
|
||||
(构建失败、异常、`SystemExit` 都会释放)。
|
||||
| 键(脚本真实输出 / 阶段名) | 什么条件下读 | 去处 |
|
||||
|---|---|---|
|
||||
| `BUILD_ENV_ERROR` | 退出码 2,UV4.exe not found / is set but not a file;先分型别动源码 | [build-env-error.md](reference/build-env-error.md) → `## BUILD_ENV_ERROR` |
|
||||
| `BUILD_LOCK_BUSY` | 退出码 4,build 锁被占、持有者名带 `pw:` 插件树 | [build-lock.md](reference/build-lock.md) → `## BUILD_LOCK_BUSY` |
|
||||
| `SHELL_FORM` | stderr 含 `syntax error near unexpected token`(bash 里误用 PowerShell 形态) | [executor-shell-forms.md](reference/executor-shell-forms.md) → `## SHELL_FORM` |
|
||||
| `JUNK_DIR` | 构建后仓库根冒出 `%SystemDrive%/`;`WARN: ENV_SPARSE:` / `WARN: JUNK_DIR:` | [systemdrive-junk-dir.md](reference/systemdrive-junk-dir.md) → `## JUNK_DIR` |
|
||||
| `IRON_RULES` | exit 2 三型分型、编码报错根因、uvprojx churn、字节模式写文件、行尾验收 | [iron-rules.md](reference/iron-rules.md) → `## IRON_RULES` |
|
||||
|
||||
| 开关 | 作用 |
|
||||
|---|---|
|
||||
| `--lock-task <ID>` | 持有者名。默认 `$DTU_TASK_ID` → 从 cwd 反推:`_wt/<ID>-<slug>/` → `<ID>`(`@task` 那批);`.agents/worktrees/<name>/` 或旧 `.dsh-worktrees/worktree/<name>/` → `pw:<name>`(DSH worktree **插件**建的树,`plugin_tree_owner()`)→ 都没有才落 `build-cli` |
|
||||
| `--lock-wait <N>` | 锁被占时等待 N 秒(默认 0 = 立即失败,退出码 4) |
|
||||
| `--no-lock` | 完全不加锁(危险:并发 `-b` 互相干扰) |
|
||||
| `DTU_LOCK_HELD=build` | 环境变量:**调用方已持锁**时设它,本脚本跳过自持自释(`task-worktree done` 的门禁即如此用) |
|
||||
## 常用参数
|
||||
|
||||
- **TTL 自报**(2026-10-12):acquire 时按 `--timeout` 声明陈旧窗口
|
||||
= `timeout/3600 + 15min`,下限 0.5h(默认 600s → **0.5h**)。这样崩溃/强杀留下的锁,
|
||||
其自动接管窗口与本次构建上限同量级,而不再是全局 6h —— 编译很快,兜底窗口也该短。
|
||||
- 锁工具 = 兄弟 skill `task-worktree/scripts/task_worktree.py`;**找不到则降级为不加锁
|
||||
并告警**(保持本 skill 可独立搬运)。
|
||||
- ⚠ 从 `_wt/<ID>-<slug>/` 反推持有者名,意味着"手工 `lock acquire build --task <ID>`
|
||||
后再跑 `/keil-build`"仍**幂等**(同名即视为自己持有),不会自我死锁。
|
||||
- **退出码 4 的持有者名带 `pw:`(如 `pw:refactor-logging`)= 插件在 `.agents/worktrees/<name>/`(或旧 `.dsh-worktrees/worktree/<name>/`)里跑的构建占着 UV4,不是某个 `@task` 任务 ID**:
|
||||
插件树**没有台账**,别拿它去 `lock release <ID>`(释放不掉别人的锁)、更别去杀 UV4 进程。正解 =
|
||||
等那次构建自己 `finally` 释放(自持自释;崩溃则按自报 TTL 兜底),或本次加 `--lock-wait <N>` 排队;
|
||||
想知道是哪棵树的谁:`"$PY" "$TW" plugin list`(缺联接再 `plugin adopt <name>`)→ 细节归
|
||||
`task-worktree` skill F 节(插件桥)。
|
||||
- **只 build 锁自动;`bench` 锁仍须 Agent 手工持**(它是**会话作用域**,跨
|
||||
烧录→`/serial-boot-test`→探针多条命令,逐命令自动释放会让别的任务插进来扰动设备)。
|
||||
- `--project X.uvprojx` / `--uv4 UV4.exe` / `--target 名字` / `--log 路径` / `--timeout 600`(其余见脚本 `--help`)
|
||||
- `--lock-wait N`:锁被占时等 N 秒;`--no-lock`:完全不加锁(并发 `-b` 会互相干扰)
|
||||
- `DTU_KEIL_UV4`(用户级,指向 UV4.exe):设了不等于本会话能看见,仍报退出码 2 走 `BUILD_ENV_ERROR`
|
||||
|
||||
## 构建副产物:`%SystemDrive%` 字面量垃圾目录(2026-10-26 两次复发 → 2026-10-28 定性并加守卫)
|
||||
## 禁令(看着合理但致命,留在主文件)
|
||||
|
||||
- 症状:/keil-build(或 check_font_charset.py 这类 fontTools 工具)跑完,仓库根冒出未跟踪的 %SystemDrive%/ProgramData/…/Caches/(几个 .db,约 1 MB)= 本机缓存被按字面量原地复刻
|
||||
- 根因(2026-10-28 实测):run_code 的 Node 进程 process.env 是空的 → known-folder 可展开串展不开变成相对路径 → 按当前目录建在仓库根;同族还会冒出 %USERPROFILE%/AppData/Local/Temp
|
||||
- 清理有安全阀:⚠ 绝不用 cmd / PowerShell 直接删(rd /s /q %SystemDrive% 会被展开成 C:);只用 bash 引号形态,先 find '%SystemDrive%' -type l 预检再 rm -rf --。它是工具副产物,直接删、别 stash、更别提交
|
||||
- 两层防线均已落地可核验:.gitignore:167 挡入库 + 脚本 harden_windows_env() 回填环境变量、check_percent_literal_junk() 只告警不自动删;守卫是兜底不是许可,/keil-build 仍要走 ops_bash / PowerShell
|
||||
- **取证在前,处置在后**(2026-10-28 实测,别一上来 `rm -rf`):`ls -laR -- "%SystemDrive%"` + `du -sh "%SystemDrive%"` 枚举内容与体积,再 `find "%SystemDrive%" -printf "%T@ %p\n" | sort -rn | head -3` 看**最新 mtime** —— 最近几分钟还在被重建 = 环境仍残缺(脚本会打 `WARN: ENV_SPARSE:`),先断源头(换 `ops_bash`/PowerShell 跑,或按「UV4.exe not found」一节把 `env` 传全)再删,否则删完立刻长回来;顺带确认仓库里只有这一个该名字的东西(`find . -maxdepth 1 -name "*SystemDrive*"`)
|
||||
- **要留证据就搬走、别就地删** —— ⚠ **shell 的 `mv` 搬不动它**:`mv "%SystemDrive%/..."` 报 `cannot stat`(含 `%` 的目录名被当变量展开 / 吃掉,路径根本对不上)。改用 Python 遍历搬到**仓库外**的临时目录 —— `os.walk` + `shutil.move`(或 `glob.glob("%SystemDrive%/*")` 逐个 `shutil.move` 到 `os.environ["TEMP"]` 下);确认是纯工具副产物(几个 `.db` 缓存)才 `rm -rf --`
|
||||
- **入库排除要落成条目并核验**:补 `.gitignore` 前先 `grep -n "SystemDrive" .gitignore` 定位精确原文行再 Edit(凭记忆写 `old_string` 必不匹配,2026-10-28 踩过)。本仓条目 = `.gitignore:167` 的 `%SystemDrive%/`,上面那段注释就是复发证据(新增条目也照此**写明第几次复发、谁造的**)。收尾核验 —— `git status --porcelain` 里该目录零命中(且别的未跟踪产物一个没少)、`git check-ignore -v` 落在那一行、`git add -A --dry-run` 零命中;**绝不提交**(把本机缓存塞进历史)
|
||||
> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [systemdrive-junk-dir.md](reference/systemdrive-junk-dir.md)。动手前先读那篇。
|
||||
|
||||
## 本仓库
|
||||
|
||||
**本 skill 的调用名 = `/keil-build`**(**技能调用名不是 shell 命令**——原样敲进终端是 command not found / syntax error,可执行形态永远是下面这条命令行):在仓库根目录跑
|
||||
`& '.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`**
|
||||
(原因见「调用形态」)。
|
||||
判定口径(与原 `MDK-ARM/build.bat` 同款;该文件已于 2026-10-10 删除,本 skill 即编译入口):
|
||||
先删旧日志 → `-b -j0 -o` → 无 `error:` 且含 `0 Error(s), 0 Warning(s)`。
|
||||
本 skill 另有超时保护、UV4 多级解析链(含 PATH 兜底)、失败只打报错行。
|
||||
环境变量 `DTU_KEIL_UV4`(用户级,指向 UV4.exe)——注意**它设了不等于本会话能看见**,仍报退出码 2 时走「exit 2 实战闭环」那一节,别先去找用户。
|
||||
|
||||
## 铁律与陷阱(实测教训)
|
||||
|
||||
- **任何代码改动后必须先编译验证(0 错误 0 警告)再谈烧录/提交**——编译不过就进
|
||||
硬件闭环只会把编译错误伪装成运行问题。**只改 `.c` 里一行中文注释也算改动**(2026-10-30 实测:
|
||||
改注释 → `/keil-build` → 环境错 → 探测注入 → 10 s 通过):BOM/嵌套注释这类坑只在重编译那个 TU 时才暴露。
|
||||
- **警告也算失败**:判 PASS 只认退出码 0,别只看"有没有 error:"(取退出码的管道陷阱见「调用形态」)。
|
||||
- **`MDK-ARM/*.uvprojx` 每次构建后被 UV4 自动改写,改动一律不入库**:UV4 会把工程
|
||||
XML 归一化成本机风格(`<Tag />` → `<Tag></Tag>`、XML 声明加 `standalone="no"`)并把
|
||||
`PackID` 降到**本机装的 DFP 版本**(属降级——提交后会把别人的 Pack 版本一起改掉)。
|
||||
判断:`git diff` 里只见 XML 格式/`PackID` 差异而**无源文件挂载增删** →
|
||||
`git checkout -- <uvprojx>` 丢弃;只有真的增删了源文件(grep 文件名计数变化)才提交。
|
||||
同目录的 `*.uvoptx` / `*.uvguix.*` 是 IDE 个人设置,已在 `.gitignore` 里,不会露出来。
|
||||
- **构建后仓库根冒出 `%SystemDrive%/`** = UV4 / 字体工具在残缺环境(缺 `SystemDrive`、`ProgramData`)
|
||||
里按**未展开的 known-folder 字面量**建出来的**相对路径**目录,不是任何人在飞的改动:
|
||||
`rm -rf -- '%SystemDrive%'`(bash 引号形态)删掉即可,**严禁 `rd /s /q %SystemDrive%`——cmd 会把它
|
||||
展开成 `C:`**;`.gitignore` 已兜住 + 脚本已加 `ENV_SPARSE`/`JUNK_DIR` 守卫 → 见「构建副产物」一节。
|
||||
- 报错定位读日志别只看终端回显:本仓库 = `MDK-ARM\build_log.txt`。
|
||||
- **批量改注释/文档脚本必须用字节模式(2026-11-16 一天内三个会话各踩一次)**:`open(p,'w')` /
|
||||
`Path.write_text()` 在 Windows 上把 `\n` 翻成 `\r\n`,结果是**只改了 1 行、`git diff` 却显示整文件**,
|
||||
且提交时易触发「stashed changes conflicted with hook auto-fixes → Rolling back fixes」(提交不生成)。
|
||||
铁律:读 `open(p,'rb')` / `Path.read_bytes()`,写 `open(p,'wb')` / `Path.write_bytes()`;非用文本模式
|
||||
必须带 `newline=''`。改完用 `grep -c $'\r' <文件>` 或逐文件比对 `HEAD` 的 CRLF 计数验收——
|
||||
`.gitattributes` 的 `eol=lf` 只在提交时归一化,**工作区里被翻过的行尾不会自己变回来**。
|
||||
- **字节模式也不会救你:`replace` 会原样保留既有行尾(同一坑的另一面)**。字节层写入保证的是
|
||||
「**忠实地坏**」——它不引入 CRLF,也不修复别人留下的 CRLF。所以「BOM 保住了」与「行尾被翻了」
|
||||
是同一机制的两面:一次 `str.replace` 改动,带 BOM 的文件 BOM 仍在,带 CRLF 的文件 CRLF 仍在,
|
||||
两者都不报错、都要单独验收。改前加一道前置断言最省事:`assert b'\r\n' not in data`(或按 HEAD
|
||||
形态决定是否归一化),把问题挡在写之前而不是提交前。
|
||||
- **行尾验收判据是「相对 HEAD 不变」,不是「绝对 LF」**(这是本坑的判据,别用 `CRLF == 0`):
|
||||
对每个被改文件比 `work_CRLF > 0` 与 `HEAD_CRLF > 0` **是否一致**——两边都 0(LF 文件)→ OK;
|
||||
两边都 >0(CRLF 文件)→ OK;**一边 0 一边 >0 → 污染**。理由:`MDK-ARM/*.uvprojx` 这类文件在 HEAD
|
||||
里本来就是 CRLF 且有正当来源(UV4 改写),无差别归一化成 LF 反而制造假改动。批量脚本的自检就照这条
|
||||
写(`git status --porcelain -z` 取路径,NUL 分隔避免非 ASCII 路径被 quoted 转义丢掉,再逐个
|
||||
`open(...,'rb')` 数 `\r\n`),别用 `git status --porcelain` 的默认 quoted 输出做路径解析。
|
||||
- **exit 2 先分三种再动手**(2026-10-10 / 2026-10-26 / 2026-10-30 实测):① **bash 语法错**——stderr 有
|
||||
`syntax error near unexpected token`,是把 PowerShell 形态丢进了 `ops_bash`,换写法即可;
|
||||
② **真没设** `DTU_KEIL_UV4`;③ **已设但本会话看不见**(agent 的 shell 由常驻服务派生,服务启动**之后**
|
||||
设的用户级变量不会进来;`run_code` 的 `process.env` 直接是空的)。
|
||||
②③ 一律走 **「exit 2 实战闭环」** 那一节:探测候选路径 + 读 `HKCU\Environment`,
|
||||
再**只往那一次调用**的 env / `--uv4` 里注入命中路径重跑——别急着让用户去设,也别替他改全局。
|
||||
- 编码类报错(`#870-D: invalid multibyte character sequence` 等)先怀疑源文件
|
||||
BOM/编码被改写,而不是代码本身(C 源码带 BOM 名单与理由 → `docs/文档规范.md` §2)。
|
||||
- **退出码数值口径**(本 skill 是唯一事实源,其它文档一律指这里):`0` 成功 / `1` 构建失败(有 error)/
|
||||
`2` **脚本判定的环境错误**(`BuildEnvError`:UV4 找不到、uvprojx 缺失等——但见上条,bash 语法错也打 2,
|
||||
须先看 stderr 分型)/ `3` 用法错误(argparse)/ `4` build 锁被占用(并发 `-b` 不可行)。
|
||||
⚠ **"exit 2" 本身不等于环境问题**——它是 ①bash 写法错 ②真没设 `DTU_KEIL_UV4` ③已设但本会话看不见
|
||||
三者共用的码位,故一律先按上面「exit 2 先分三种」分型再动手。
|
||||
- **任何代码改动后必须先编译 0 错 0 警再谈烧录/提交**;只改 `.c` 里一行中文注释也算改动。
|
||||
- 报错定位读 `MDK-ARM/build_log.txt`,别只看终端回显;**别把脚本接进管道**(`| tail` 后 `$?` 恒 0)。
|
||||
- bash / `ops_bash` 里**不要照抄 PowerShell 的 `&` 形态**——那既不是构建通过也不是失败,是写法错。
|
||||
- **不要 `setx`、不要替用户改全局环境变量**;本 skill 只解决"这一次构建怎么跑起来"。
|
||||
- 构建后清理垃圾目录**绝不** `rd /s /q %SystemDrive%`(cmd 会展开成 `C:`);只用 bash 引号形态。
|
||||
- `MDK-ARM/*.uvprojx` 每次构建被 UV4 改写,**改动一律不入库**:只见 XML 格式/`PackID` 差异 → `git checkout -- <uvprojx>` 丢弃;只有真增删源文件才提交。
|
||||
- 批量改注释/文档脚本**只用字节模式**(`read_bytes` / `write_bytes`);文本模式在 Windows 把 `\n` 翻成 `\r\n`,造成整文件假 diff 与提交回滚。
|
||||
|
||||
## 与其它 skill 的衔接
|
||||
|
||||
- **build 锁的对面是谁**(`BUILD_LOCK_BUSY`、退出码 4、`pw:<name>` 插件树、`@task plugin list` / `plugin adopt`、`_wt/` 台账与合并回收)归 `task-worktree` skill(F 节 = DSH worktree 插件桥);换机/新克隆时 `DTU_*` 工具路径变量的设立与「会话不继承」坑 = `new-machine-setup` skill。
|
||||
- 烧录/回读 = `stlink-flash` skill;串口闭环 = `serial-boot-test` skill
|
||||
(其档案 `flash_cmd`/`readback_cmd` 即 stlink-flash 的入口命令)。
|
||||
- 收尾固定链(2026-10-26 实证):`/keil-build` → `scripts/ram_baseline.py --update` →
|
||||
体积门禁盖戳 → 内存数字回填与 `--scan` → 复跑 `ci_local` 静态段,
|
||||
直到钩子全绿且 0 错误 0 警告(RAM/栈口径见 `mem-budget` skill)。
|
||||
build 锁对面(`pw:` 插件树)→ `task-worktree` F 节;换机与工具路径 → `new-machine-setup`;烧录 → `stlink-flash`;串口闭环 → `serial-boot-test`;内存数字回填 → `mem-budget`。
|
||||
|
||||
⚠ **改本文件 frontmatter 要么整值加双引号,要么一个 ASCII 冒号都别写**:plain scalar 里出现「冒号 + 空格」会让 DSH 自带 `yaml` 解析器报 `Nested mappings are not allowed in compact mappings` → 技能整份不加载(`js-yaml` 能吃下去,自检会假绿)。值首字符不能是 `%` 或 `&`(双引号里的 `%SystemDrive%` 无碍)。落盘后让 DSH 真加载一次再收口。
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# BUILD_ENV_ERROR — exit 2 实战闭环(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## BUILD_ENV_ERROR
|
||||
|
||||
> 路由:主文件失败索引表 `BUILD_ENV_ERROR` → 本节。原节 `## exit 2 实战闭环…`(L36–89)逐字搬移,未改写。
|
||||
|
||||
### 判据
|
||||
|
||||
脚本报 `BUILD_ENV_ERROR: UV4.exe not found …` 且退出码 2 = 环境错(UV4 未启动、build_log 未改写);先看 stderr 区分 bash 语法错/真没设/已设但本会话看不见三型。
|
||||
|
||||
### 处置
|
||||
|
||||
探测候选安装路径 → 读 HKCU\\Environment 确认值 → 只给这一次调用注入 env/`--uv4` 重跑 → 三样齐(UV4 行 + UV4_RC: 0 + BUILD_OK)复核。不替用户改全局。
|
||||
|
||||
### 证据边界
|
||||
|
||||
候选路径清单与 10 s 耗时为 2026-10-30 实测;"`setx`" 类全局改动属用户自己的事,本闭环未验证跨会话持久化。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## exit 2 实战闭环:`UV4.exe not found` 的探测 → 注入 → 复核(2026-10-30 实测)
|
||||
|
||||
**先定性,别动源码**:脚本报
|
||||
`BUILD_ENV_ERROR: UV4.exe not found (--uv4 / config 'uv4' / $DSH_KEIL_UV4 / $DTU_KEIL_UV4 / PATH)`
|
||||
且**退出码 2** = **环境错,不是构建失败**——本次 **UV4 根本没启动、`MDK-ARM/build_log.txt` 也没被改写**,
|
||||
日志里看到的是上一次的。此时去改 `.c`/`.h` 或怀疑代码,就是把环境问题当编译问题排。
|
||||
(会话为什么看不见:DSH 会话的 shell 由常驻服务派生,**服务启动之后**设的用户级变量不会自动进来;
|
||||
`run_code` 起的 Node 进程 `process.env` 干脆是空的(同一机制另见 `new-machine-setup` skill「实测坑」)。
|
||||
所以**变量"已设但本会话看不见"是常态**,不是用户没设。)
|
||||
|
||||
1. **探测候选安装路径**(逐个 `fs.existsSync` / `test -f`,命中即取绝对路径)——
|
||||
`C:/Keil_v5/UV4/UV4.exe`、`C:/Keil/UV4/UV4.exe`、`D:/Keil_v5/UV4/UV4.exe`、`D:/Keil/UV4/UV4.exe`、
|
||||
`C:/Program Files/Keil_v5/UV4/UV4.exe`、`D:/Program Files/Keil_v5/UV4/UV4.exe`
|
||||
(2026-10-30 实测只命中 `C:/Keil_v5/UV4/UV4.exe`,其余五个都不存在)。
|
||||
```bash
|
||||
for p in 'C:/Keil_v5/UV4/UV4.exe' 'C:/Keil/UV4/UV4.exe' 'D:/Keil_v5/UV4/UV4.exe' \
|
||||
'D:/Keil/UV4/UV4.exe' 'C:/Program Files/Keil_v5/UV4/UV4.exe' 'D:/Program Files/Keil_v5/UV4/UV4.exe'; do
|
||||
[ -f "$p" ] && echo "HIT $p"; done
|
||||
```
|
||||
2. **读用户级来源确认"值本来就对"**(同一轮里顺手做掉,别只靠猜路径):
|
||||
bash / Node 侧 `reg query HKCU\Environment`(整表打出来再找 `DTU_KEIL_UV4` / `DSH_KEIL_UV4`),
|
||||
PowerShell 侧 `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`。
|
||||
有值 → 直接用它;没值/值指向旧目录 → 用第 1 步的命中路径。
|
||||
⚠ **不替用户改全局**:不要 `setx`、不要 `SetEnvironmentVariable(...,'User')`——那是用户自己在真终端里
|
||||
做的事(`docs/环境与部署/本地工具路径环境变量方案.md`);本闭环只解决"这一次构建怎么跑起来",
|
||||
报告里也必须这么写。
|
||||
3. **只给这一次调用注入**再重跑(两种等价形态,二选一):
|
||||
```js
|
||||
// run_code:options.env 是**整体替换**,所以要连 SystemRoot / Path / USERPROFILE 一起给
|
||||
const { execSync } = await import('node:child_process');
|
||||
execSync('".venv/Scripts/python.exe" .dsh/skills/keil-build/scripts/keil_build.py', {
|
||||
cwd: MAIN, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
|
||||
env: { SystemRoot: 'C:\\Windows', Path: 'C:\\Windows;C:\\Windows\\System32',
|
||||
USERPROFILE: 'C:\\Users\\<你>', DTU_KEIL_UV4: 'C:\\Keil_v5\\UV4\\UV4.exe' } });
|
||||
```
|
||||
- bash / `ops_bash` 侧的等价写法 = 显式参数 `--uv4 'C:\Keil_v5\UV4\UV4.exe'`(值含空格要整体加引号)。
|
||||
- `run_code` 的 `timeoutMs` 给足:注入后这次构建实测 **10 s** 跑完,但首次冷构建更长(我给的 500000)。
|
||||
- **别顺手加 `--no-lock`**:注入重跑时锁链照旧(`LOCK: 已获取 build 锁(task=build-cli)` → `已释放锁`)。
|
||||
4. **复核口径**(三样齐了才算真跑过,缺一样就是没构建):脚本回显
|
||||
`UV4: <绝对路径> (<来源>)`(来源随注入方式变:`$DTU_KEIL_UV4` 或 `--uv4`)→
|
||||
`UV4_RC: 0` → `BUILD_OK: 0 errors, 0 warnings`,且**外层退出码 0**(自己包 execSync 就显式把码打出来,
|
||||
别接管道,见「调用形态」)。报告里写清"本次注入 + 来源",**不得声称已永久设置系统/用户环境变量**。
|
||||
|
||||
- ⚠ 注入的若是**注册表里那个陈旧值**,会撞同族的另一种 2:
|
||||
`BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: … (fix the value; no silent fallback)`
|
||||
—— 值在但指向旧盘符/旧目录名(本仓踩过 `D:\Code\DTU 程序\…` 搬迁)。脚本**刻意不静默回退**,
|
||||
回到第 1 步用探测命中的路径覆盖它,别去猜目录、更别改脚本让它"猜 C 盘"(设计上明确禁止从旧路径猜)。
|
||||
- ⚠ 本闭环只回答"UV4 在哪儿",**不回答"调用写法对不对"**:从 bash 侧照抄 PowerShell 的 `&` 也是 exit 2,
|
||||
但 stderr 是 `syntax error near unexpected token`(见「调用形态」)。**先看 stderr 再决定排障方向**,
|
||||
两种 2 的处置完全不同。
|
||||
- **改 `.c` 注释(哪怕只改一行中文注释)也必须跑完这道构建验证**:2026-10-30 的实测就是
|
||||
「改注释 → `/keil-build` → 吃 rc=2 → 探测+注入 → 10 s 通过」。注释类坑(BOM 被剥 → `#870-D`、
|
||||
注释里写 `**` 路径 → 9-D)只在**重编译那个 TU 时**才暴露,"以前 0 警告"不代表安全。
|
||||
@@ -0,0 +1,48 @@
|
||||
# BUILD_LOCK_BUSY — build 锁自持自释(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## BUILD_LOCK_BUSY
|
||||
|
||||
> 路由:主文件失败索引表 `BUILD_LOCK_BUSY` → 本节。原节 `## build 锁…`(L90–118)逐字搬移,未改写。
|
||||
|
||||
### 判据
|
||||
|
||||
退出码 4 / `BUILD_LOCK_BUSY:` = build 锁被占用;持有者名带 `pw:` = DSH 插件树的构建占着 UV4。
|
||||
|
||||
### 处置
|
||||
|
||||
等对方 `finally` 自动释放,或本次加 `--lock-wait N` 排队;**绝不** `lock release <pw:名>` 或杀 UV4 进程。
|
||||
|
||||
### 证据边界
|
||||
|
||||
TTL 自报口径(timeout/3600 + 15min,下限 0.5h)为 2026-10-12 实测;`bench` 锁仍须会话作用域手工持有,不在本节范围。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## build 锁:脚本自持自释(2026-10-12)
|
||||
|
||||
**UV4 不能两个实例同时 `-b`,但构建锁不该由调用方"记得释放"**——那正是泄漏源:
|
||||
Agent 手工 `lock acquire build` 后忘了 `release`,锁要挂到 TTL 才被接管。
|
||||
故本脚本**自己**管:进入 acquire → `try` 构建 → `finally` **无条件** release
|
||||
(构建失败、异常、`SystemExit` 都会释放)。
|
||||
|
||||
| 开关 | 作用 |
|
||||
|---|---|
|
||||
| `--lock-task <ID>` | 持有者名。默认 `$DTU_TASK_ID` → 从 cwd 反推:`_wt/<ID>-<slug>/` → `<ID>`(`@task` 那批);`.agents/worktrees/<name>/` 或旧 `.dsh-worktrees/worktree/<name>/` → `pw:<name>`(DSH worktree **插件**建的树,`plugin_tree_owner()`)→ 都没有才落 `build-cli` |
|
||||
| `--lock-wait <N>` | 锁被占时等待 N 秒(默认 0 = 立即失败,退出码 4) |
|
||||
| `--no-lock` | 完全不加锁(危险:并发 `-b` 互相干扰) |
|
||||
| `DTU_LOCK_HELD=build` | 环境变量:**调用方已持锁**时设它,本脚本跳过自持自释(`task-worktree done` 的门禁即如此用) |
|
||||
|
||||
- **TTL 自报**(2026-10-12):acquire 时按 `--timeout` 声明陈旧窗口
|
||||
= `timeout/3600 + 15min`,下限 0.5h(默认 600s → **0.5h**)。这样崩溃/强杀留下的锁,
|
||||
其自动接管窗口与本次构建上限同量级,而不再是全局 6h —— 编译很快,兜底窗口也该短。
|
||||
- 锁工具 = 兄弟 skill `task-worktree/scripts/task_worktree.py`;**找不到则降级为不加锁
|
||||
并告警**(保持本 skill 可独立搬运)。
|
||||
- ⚠ 从 `_wt/<ID>-<slug>/` 反推持有者名,意味着"手工 `lock acquire build --task <ID>`
|
||||
后再跑 `/keil-build`"仍**幂等**(同名即视为自己持有),不会自我死锁。
|
||||
- **退出码 4 的持有者名带 `pw:`(如 `pw:refactor-logging`)= 插件在 `.agents/worktrees/<name>/`(或旧 `.dsh-worktrees/worktree/<name>/`)里跑的构建占着 UV4,不是某个 `@task` 任务 ID**:
|
||||
插件树**没有台账**,别拿它去 `lock release <ID>`(释放不掉别人的锁)、更别去杀 UV4 进程。正解 =
|
||||
等那次构建自己 `finally` 释放(自持自释;崩溃则按自报 TTL 兜底),或本次加 `--lock-wait <N>` 排队;
|
||||
想知道是哪棵树的谁:`"$PY" "$TW" plugin list`(缺联接再 `plugin adopt <name>`)→ 细节归
|
||||
`task-worktree` skill F 节(插件桥)。
|
||||
- **只 build 锁自动;`bench` 锁仍须 Agent 手工持**(它是**会话作用域**,跨
|
||||
烧录→`/serial-boot-test`→探针多条命令,逐命令自动释放会让别的任务插进来扰动设备)。
|
||||
@@ -1,6 +1,22 @@
|
||||
# 调用形态:先认执行器是哪个 shell(2026-10-26 实测)(自 SKILL.md 外置)
|
||||
|
||||
> 本文由 keil-build 的 SKILL.md「调用形态:先认执行器是哪个 shell(2026-10-26 实测)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。
|
||||
## SHELL_FORM
|
||||
|
||||
> 路由:主文件失败索引表 `SHELL_FORM` → 本节。原节 `## 调用形态…`(自 SKILL.md 外置)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
stderr 含 `syntax error near unexpected token` = PowerShell 形态被丢进 bash/ops_bash,exit 2 是写法错,不是环境错、不是构建失败。
|
||||
|
||||
### 处置
|
||||
|
||||
bash / `ops_bash` 侧去掉前导 `&`、路径改正斜杠;`BUILD_RC=0` + `UV4_RC: 0` + `BUILD_OK: 0 errors, 0 warnings` 三样齐才算构建通过。
|
||||
|
||||
### 证据边界
|
||||
|
||||
2026-10-26 实测口径;`$?` 取到管道尾码属 Bash 行为,换 shell 需重验。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
同一条编译命令,**PowerShell 与 bash 是两种写法**;`ops_bash` / `run_code` 起的是
|
||||
`/usr/bin/bash -c`,**不认 PowerShell 形态**,照抄 skill 正文的 PowerShell 段会直接语法错退出。
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
# 铁律与陷阱(长尾,自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## IRON_RULES
|
||||
|
||||
> 路由:主文件失败索引表 `IRON_RULES` → 本节。原节 `## 铁律与陷阱…`(L141–188)逐字搬移,未改写;致命禁令的短句仍留在主文件。
|
||||
|
||||
### 判据
|
||||
|
||||
退出码数值口径、exit 2 三型分型、编码类报错的根因方向均在本节给全;正常路径不必读。
|
||||
|
||||
### 处置
|
||||
|
||||
按节内对应条目处置(字节模式写文件、exit 2 分型后路由、uvprojx churn 丢弃等)。
|
||||
|
||||
### 证据边界
|
||||
|
||||
各条均标注实测日期(2026-10-10 / 10-26 / 10-30 / 11-16),属特定环境结论;换 Keil 版本或工具链须重验。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 铁律与陷阱(实测教训)
|
||||
|
||||
- **任何代码改动后必须先编译验证(0 错误 0 警告)再谈烧录/提交**——编译不过就进
|
||||
硬件闭环只会把编译错误伪装成运行问题。**只改 `.c` 里一行中文注释也算改动**(2026-10-30 实测:
|
||||
改注释 → `/keil-build` → 环境错 → 探测注入 → 10 s 通过):BOM/嵌套注释这类坑只在重编译那个 TU 时才暴露。
|
||||
- **警告也算失败**:判 PASS 只认退出码 0,别只看"有没有 error:"(取退出码的管道陷阱见「调用形态」)。
|
||||
- **`MDK-ARM/*.uvprojx` 每次构建后被 UV4 自动改写,改动一律不入库**:UV4 会把工程
|
||||
XML 归一化成本机风格(`<Tag />` → `<Tag></Tag>`、XML 声明加 `standalone="no"`)并把
|
||||
`PackID` 降到**本机装的 DFP 版本**(属降级——提交后会把别人的 Pack 版本一起改掉)。
|
||||
判断:`git diff` 里只见 XML 格式/`PackID` 差异而**无源文件挂载增删** →
|
||||
`git checkout -- <uvprojx>` 丢弃;只有真的增删了源文件(grep 文件名计数变化)才提交。
|
||||
同目录的 `*.uvoptx` / `*.uvguix.*` 是 IDE 个人设置,已在 `.gitignore` 里,不会露出来。
|
||||
- **构建后仓库根冒出 `%SystemDrive%/`** = UV4 / 字体工具在残缺环境(缺 `SystemDrive`、`ProgramData`)
|
||||
里按**未展开的 known-folder 字面量**建出来的**相对路径**目录,不是任何人在飞的改动:
|
||||
`rm -rf -- '%SystemDrive%'`(bash 引号形态)删掉即可,**严禁 `rd /s /q %SystemDrive%`——cmd 会把它
|
||||
展开成 `C:`**;`.gitignore` 已兜住 + 脚本已加 `ENV_SPARSE`/`JUNK_DIR` 守卫 → 见「构建副产物」一节。
|
||||
- 报错定位读日志别只看终端回显:本仓库 = `MDK-ARM\build_log.txt`。
|
||||
- **批量改注释/文档脚本必须用字节模式(2026-11-16 一天内三个会话各踩一次)**:`open(p,'w')` /
|
||||
`Path.write_text()` 在 Windows 上把 `\n` 翻成 `\r\n`,结果是**只改了 1 行、`git diff` 却显示整文件**,
|
||||
且提交时易触发「stashed changes conflicted with hook auto-fixes → Rolling back fixes」(提交不生成)。
|
||||
铁律:读 `open(p,'rb')` / `Path.read_bytes()`,写 `open(p,'wb')` / `Path.write_bytes()`;非用文本模式
|
||||
必须带 `newline=''`。改完用 `grep -c $'\r' <文件>` 或逐文件比对 `HEAD` 的 CRLF 计数验收——
|
||||
`.gitattributes` 的 `eol=lf` 只在提交时归一化,**工作区里被翻过的行尾不会自己变回来**。
|
||||
- **字节模式也不会救你:`replace` 会原样保留既有行尾(同一坑的另一面)**。字节层写入保证的是
|
||||
「**忠实地坏**」——它不引入 CRLF,也不修复别人留下的 CRLF。所以「BOM 保住了」与「行尾被翻了」
|
||||
是同一机制的两面:一次 `str.replace` 改动,带 BOM 的文件 BOM 仍在,带 CRLF 的文件 CRLF 仍在,
|
||||
两者都不报错、都要单独验收。改前加一道前置断言最省事:`assert b'\r\n' not in data`(或按 HEAD
|
||||
形态决定是否归一化),把问题挡在写之前而不是提交前。
|
||||
- **行尾验收判据是「相对 HEAD 不变」,不是「绝对 LF」**(这是本坑的判据,别用 `CRLF == 0`):
|
||||
对每个被改文件比 `work_CRLF > 0` 与 `HEAD_CRLF > 0` **是否一致**——两边都 0(LF 文件)→ OK;
|
||||
两边都 >0(CRLF 文件)→ OK;**一边 0 一边 >0 → 污染**。理由:`MDK-ARM/*.uvprojx` 这类文件在 HEAD
|
||||
里本来就是 CRLF 且有正当来源(UV4 改写),无差别归一化成 LF 反而制造假改动。批量脚本的自检就照这条
|
||||
写(`git status --porcelain -z` 取路径,NUL 分隔避免非 ASCII 路径被 quoted 转义丢掉,再逐个
|
||||
`open(...,'rb')` 数 `\r\n`),别用 `git status --porcelain` 的默认 quoted 输出做路径解析。
|
||||
- **exit 2 先分三种再动手**(2026-10-10 / 2026-10-26 / 2026-10-30 实测):① **bash 语法错**——stderr 有
|
||||
`syntax error near unexpected token`,是把 PowerShell 形态丢进了 `ops_bash`,换写法即可;
|
||||
② **真没设** `DTU_KEIL_UV4`;③ **已设但本会话看不见**(agent 的 shell 由常驻服务派生,服务启动**之后**
|
||||
设的用户级变量不会进来;`run_code` 的 `process.env` 直接是空的)。
|
||||
②③ 一律走 **「exit 2 实战闭环」** 那一节:探测候选路径 + 读 `HKCU\Environment`,
|
||||
再**只往那一次调用**的 env / `--uv4` 里注入命中路径重跑——别急着让用户去设,也别替他改全局。
|
||||
- 编码类报错(`#870-D: invalid multibyte character sequence` 等)先怀疑源文件
|
||||
BOM/编码被改写,而不是代码本身(C 源码带 BOM 名单与理由 → `docs/文档规范.md` §2)。
|
||||
- **退出码数值口径**(本 skill 是唯一事实源,其它文档一律指这里):`0` 成功 / `1` 构建失败(有 error)/
|
||||
`2` **脚本判定的环境错误**(`BuildEnvError`:UV4 找不到、uvprojx 缺失等——但见上条,bash 语法错也打 2,
|
||||
须先看 stderr 分型)/ `3` 用法错误(argparse)/ `4` build 锁被占用(并发 `-b` 不可行)。
|
||||
⚠ **"exit 2" 本身不等于环境问题**——它是 ①bash 写法错 ②真没设 `DTU_KEIL_UV4` ③已设但本会话看不见
|
||||
三者共用的码位,故一律先按上面「exit 2 先分三种」分型再动手。
|
||||
@@ -1,6 +1,22 @@
|
||||
# 构建副产物:`%SystemDrive%` 字面量垃圾目录(2026-10-26 两次复发 → 2026-10-28 定性并加守卫)(自 SKILL.md 外置)
|
||||
|
||||
> 本文由 keil-build 的 SKILL.md「构建副产物:`%SystemDrive%` 字面量垃圾目录(2026-10-26 两次复发 → 2026-10-28 定性并加守卫)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。
|
||||
## JUNK_DIR
|
||||
|
||||
> 路由:主文件失败索引表 `JUNK_DIR` → 本节。原节 `## 构建副产物…`(自 SKILL.md 外置)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
构建后仓库根冒出 `%SystemDrive%/ProgramData/...` 未跟踪目录(伴随 `WARN: ENV_SPARSE:` / `WARN: JUNK_DIR:`)= 残缺环境按字面量建出的工具副产物,不是任何人在飞的改动。
|
||||
|
||||
### 处置
|
||||
|
||||
先取证(枚举 + mtime)再处置:源头未断会删完立刻长回来;只用 bash 引号形态 `rm -rf -- '%SystemDrive%'`,**绝不** `rd /s /q %SystemDrive%`;要留证用 Python `os.walk`+`shutil.move` 搬到仓库外,别用 shell `mv`。
|
||||
|
||||
### 证据边界
|
||||
|
||||
两次复发(2026-10-26 / 10-28)为本机实测;`.gitignore:167` 条目与 `harden_windows_env()` 守卫是代码事实,换仓需核行号。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
**症状**:`/keil-build`(或 `scripts/check_font_charset.py` 这类 fontTools 字体工具)跑完,仓库根
|
||||
冒出未跟踪目录 `%SystemDrive%/ProgramData/Microsoft/Windows/Caches/`,里面是几个 `.db`
|
||||
|
||||
@@ -19,6 +19,14 @@ PC 上编译运行与 MCU **同一份** UI 源码(CMake + MSVC + SDL2,x64,
|
||||
|
||||
⚠ 窗口模式默认 **60 s 空闲自动退出**(防挂后台),`--idle <秒>` 覆盖。
|
||||
|
||||
**成功输出样例**(本轮实跑 `lvgl_sim.exe --screenshot`,无头截图):看到 `screenshot: ... (3200 bytes, 160x160 I1)` 且退出码 0 就是出图通了,不用再往下看。
|
||||
|
||||
```text
|
||||
[UI_STANDBY] standby: ready (idle=60000ms)
|
||||
pool after keys: used=5368 free=8488
|
||||
screenshot: <路径>/skill_probe.bin (3200 bytes, 160x160 I1)
|
||||
```
|
||||
|
||||
## 无头自检(退出码 0=PASS / 非 0=FAIL)
|
||||
|
||||
| 命令(在 `simulator\build\Debug\` 下或用全路径) | 用途 |
|
||||
|
||||
+57
-126
@@ -6,151 +6,82 @@ whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报
|
||||
|
||||
# mem-budget — RAM/栈预算核算
|
||||
|
||||
## 固定动作(改前、改后各跑一次)
|
||||
## 默认路径:一条命令跑通(改前、改后各跑一次)
|
||||
|
||||
仓库根,先 `/keil-build` 保证 `.htm`/`.map` 最新(产物按脚本自身位置定位),再:
|
||||
|
||||
```powershell
|
||||
# cwd = 项目根;先 /keil-build 保证 .htm/.map 是最新的(产物按脚本自身位置定位,见下节)
|
||||
& '.venv\Scripts\python.exe' ".dsh\skills\mem-budget\scripts\mem_check.py"
|
||||
# 等价于分别跑:
|
||||
# scripts/ram_report.py (.map → RAM/Flash 分区与按文件占用表)
|
||||
# scripts/stack_report.py (.htm 静态调用图 → 每任务最坏链 vs 配置栈)
|
||||
# 报告落盘留档(改前/改后各一份,供逐帧差分):
|
||||
```
|
||||
|
||||
等价于 `scripts/ram_report.py`(.map → RAM/Flash 分区与按文件占用)+ `scripts/stack_report.py`(.htm 静态调用图 → 每任务最坏链 vs 配置栈)。留档各一份供逐帧差分,有真机日志叠加运行时水位:
|
||||
|
||||
```powershell
|
||||
& '.venv\Scripts\python.exe' scripts/stack_report.py -o ci-artifacts/sr_before.md
|
||||
# 叠加运行时水位(有真机日志时):
|
||||
& '.venv\Scripts\python.exe' scripts/stack_report.py -s .dsh\skills\serial-assistant\scripts\state\serial.log
|
||||
```
|
||||
|
||||
退出码:0=全部通过 / 1=有任务不达标 / 2=解析错误(.htm/.map 缺失先重跑构建)。
|
||||
别整篇读输出,抓关键行:`grep -aE 'iec104|margin|FAIL|ISR|Rule' ci-artifacts/sr_before.md`。
|
||||
「改前/改后」必须是**两次不同的 Linker run**——同一份 .htm/.map 跑两遍只是复述,不构成复验。退出码:`0`=全过 / `1`=有任务不达标 / `2`=解析错误(.htm/.map 缺失先重跑构建)。别整篇读输出,抓关键行:`grep -aE 'iec104|margin|FAIL|ISR|Rule' ci-artifacts/sr_before.md`。
|
||||
|
||||
**「改前 / 改后」必须是两次不同的 Linker run**(两个不同的产物身份):同一份 .htm/.map 上跑两遍
|
||||
只是把同一个数字复述两遍,不构成"改后已复验"。
|
||||
## 成功输出(默认路径跑通的样子)
|
||||
|
||||
## 测量身份口径(先钉树与时刻,再看数字)
|
||||
|
||||
1. 脚本按 __file__ 定位产物,不按 cwd —— 跨树必须换脚本(在主树跑脚本量任务树 = 拿旧 .map 当真值)
|
||||
2. 重跑报告脚本不算新测量(复述 ≠ 复验):只有新的 Linker run 才算一次新测量
|
||||
3. 钉身份的取数法:.htm/.map 按约定不入库 → 把时刻写进正文/台账;记录最小格式 = tree/commit + Linker run 时刻 + 产物来源(本次构建 / 盘上既有)
|
||||
> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [measurement-identity.md](reference/measurement-identity.md)。动手前先读那篇。
|
||||
|
||||
## 静态最坏链回归的归因(同涨同一数值 = 共享帧,不是调用方)
|
||||
|
||||
- 多条任务链分毫不差同涨/同降同一个数值 ⇒ 加深在这些任务共用的被调帧 / 共享尾段上,不在任何一个调用方(别先猜「新增了大局部缓冲」,实测猜错过一次)
|
||||
- 逐棵树逐帧比 frame size、不只比总数:stack_report.py 的 own-frame 表锁链尾公共段;grep -ac 'In Cycle' 在 .htm 里找环(实测 17 处)—— 链接器幻影环能在无人改栈配置时让全仓链齐涨
|
||||
- Maximum Stack Usage 里的 + Unknown(Cycles, Untraceable Function Pointers) 说明静态数是估计值,别当精确值上报;不采信口头结论,用目标树的脚本 + .venv 解释器自己复算
|
||||
- 处置后的下一步:抬栈(Src/freertos.c 的 USER CODE 区,属 Ask-first)或收紧共享缓冲 / 断环;改前改后各跑一次 stack_report.py + ram_report.py,且「改后」那次必须落在一次新的 Linker run 上
|
||||
> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [shared-frame-attribution.md](reference/shared-frame-attribution.md)。动手前先读那篇。
|
||||
|
||||
## 判读口径
|
||||
|
||||
- **静态**:`stack_report.py` 的 Max Depth(最坏调用链累计)vs `Src/freertos.c` 配置栈;
|
||||
默认要求余量 ≥30%(`--min-free-pct`),ISR 另留 `--isr-margin`(默认 1024B)。
|
||||
判定式 `margin = cfg - max(static_max_depth, runtime_peak)` 须 ≥ `max(isr_margin, 30% of cfg)`。
|
||||
- **运行时**:开机日志 `[STACK] <task> peak_used=…/… free_min=…` 与静态值对照——
|
||||
**静态最坏链是上界(硬线)、运行时峰值是下界证据(趋势)**,两者都要看;余量 <1KB 底线要上报。
|
||||
- **RAM 总量**:`ram_report.py` 对 Grand Totals 与 `docs/内存管理/` 预算表核对;
|
||||
链接错 `L6406E` = 已经溢出,用按文件表找大头。
|
||||
- 任务表一致性由 pre-commit `task-table` 钩子保证;`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92%,
|
||||
**并核台账受管区是否与 .map 同源**;`mem-numbers` 钩子核文档里的内存数字——
|
||||
数字与树/时刻脱钩、或**构建后只跑了 `--update` 没回填受管区**时,响的就是这两条(回填见下一节)。
|
||||
|
||||
## 权威构建后的台账回填(三个旗标,别混)
|
||||
|
||||
`.map` 是内存/Flash 数字的**唯一事实源**;台账与文档里的数字由脚本从它生成——**不手抄、不手改**
|
||||
(`docs/内存管理/RAM预算台账.md` 首段就写着"数字不手抄")。三份落点 = 三个旗标,一条命令只干其中一件:
|
||||
`ram_baseline.py` 的 `--gate/--write/--update/--trend` 是 `add_mutually_exclusive_group()`
|
||||
(`scripts/ram_baseline.py:415-419`),想干两件就得调两次。
|
||||
|
||||
| 落点 | 旗标 | 实际改了什么 |
|
||||
|---|---|---|
|
||||
| `scripts/ram_baseline.tsv` 趋势基线(顺带刷 `scripts/size_attestation.json` 同码凭证) | `ram_baseline.py --update` | **只**追加/覆盖当日那一行趋势(Code/RO/RW/ZI + 三区水位 + Top-10 RW+ZI)。**不碰台账正文** |
|
||||
| `docs/内存管理/RAM预算台账.md` 的 `<!-- MEM_BUDGET:BEGIN/END -->` 受管区 | `ram_baseline.py --write` | 从 .map 重渲染区域水位 + 子系统配额对照(打印「已同步台账受管区。」或「台账受管区已是最新。」) |
|
||||
| `docs/内存管理/RAM使用分析与优化方案.md` 的 `<!-- MEM_SNAPSHOT:BEGIN/END -->` 快照区 | `check_mem_numbers.py --write` | 从**同一份** .map 重渲染内存/Flash 快照表(打印「已更新内存快照:…」) |
|
||||
|
||||
**台账 §4 那句「每次 `/keil-build` 后跑 `scripts/ram_baseline.py --update`」只喂趋势行,不等于回填受管区。**
|
||||
实测代价:照那句跑完 `--update` 就提交 → `mem-budget`、`mem-numbers` 两条钩子当场红。
|
||||
`mem-budget` 的 entry 是 `python scripts/ram_baseline.py --gate`(`.pre-commit-config.yaml:571`)——它在 92% 阈值之外
|
||||
还核**台账受管区与 .map 的一致性**,漂移即 `[FAIL] 台账受管区与 .map 不一致(区域水位或子系统配额表漂移)`
|
||||
并打印 `修复:python scripts/ram_baseline.py --write`(`scripts/ram_baseline.py:221-224`);
|
||||
`mem-numbers` 的 entry 是 `python scripts/check_mem_numbers.py --scan`(同文件 :193),不一致时打印
|
||||
`修复:运行 python scripts/check_mem_numbers.py --write`(`scripts/check_mem_numbers.py:416`)。
|
||||
改用两个 `--write` 后重提,同一笔提交触发的 26 条钩子全 Passed。
|
||||
|
||||
### 提交前固定顺序(构建 → 回填 → 真钩子提交)
|
||||
|
||||
```powershell
|
||||
# cwd = 项目根,一律 .venv 解释器
|
||||
# 0) 权威构建先行(0 错 0 警):回填读的是**盘上那份 .map**,构建没落定就 --write = 把旧数字写进台账,钩子照样红
|
||||
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
|
||||
|
||||
# 1) 趋势行(纪律项,不是回填):覆盖 tsv 当日行 + 顺带刷体积同码凭证
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --update
|
||||
|
||||
# 2) 回填台账受管区(mem-budget 钩子核的就是这一段)
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --write
|
||||
|
||||
# 3) 回填文档快照区(mem-numbers 钩子核的就是这一张表)
|
||||
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --write
|
||||
|
||||
# 4) 逐字自跑提交时会跑的这两条 entry(比事后翻 pre-commit 输出快)
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate # 0 = 阈值 + 受管区都过
|
||||
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan # 0 = 快照区与 .map 一致
|
||||
|
||||
# 5) 把刚落盘的落点一并 add,然后**真钩子**提交(绝不 --no-verify、绝不手改数字)
|
||||
git add docs/内存管理/RAM预算台账.md docs/内存管理/RAM使用分析与优化方案.md scripts/ram_baseline.tsv scripts/size_attestation.json
|
||||
```
|
||||
MEM_CHECK: ram=0 stack=0 -> PASS
|
||||
```
|
||||
|
||||
退出码:`ram_baseline.py` 0=通过或跳过 / **1=阈值超限或受管区漂移** / 2=.map 解析失败;
|
||||
`check_mem_numbers.py` 0=一致 / 1=不一致、缺受管锚点或找不到事实源。
|
||||
即 `mem_check.py` 打印 `MEM_CHECK: ram=<码> stack=<码> -> PASS|FAIL|ERROR`,两码均 0 时尾部为 `PASS`;报告脚本落出 `OK <路径>` 且每任务 `margin` 达标(静态 Max Depth vs 配置栈,余量 ≥30% `--min-free-pct`、ISR 另留 `--isr-margin` 默认 1024B)。
|
||||
|
||||
### 回填链上的坑(实测)
|
||||
## 失败了 → 去哪读(索引表)
|
||||
|
||||
- --write 说「已是最新」而钩子还红
|
||||
- tsv 落后只 WARN、不拦
|
||||
- --gate 无 .map → SKIP,而脚本自己写明「SKIP 不等于 PASS」
|
||||
- --map <path> 只换读、不换写
|
||||
- --scan 的散句告警 --write 不替你改
|
||||
- --update 的盖戳排在索引后面
|
||||
- 改写型钩子当场改文件是流程不是故障
|
||||
- mem-budget 触发面很宽
|
||||
> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [backfill-pitfalls.md](reference/backfill-pitfalls.md)。动手前先读那篇。
|
||||
失败信息自带稳定键;命中才读对应小节(每节 = 判据 / 处置 / 证据边界 + 逐字原文):
|
||||
|
||||
## 运行时峰值抖动与"算不算劣化"
|
||||
| 键(脚本真实输出 / 阶段名) | 什么条件下读 | 去处 |
|
||||
|---|---|---|
|
||||
| `BACKFILL_FLAGS` | mem-budget / mem-numbers 报「与 .map 不一致」;纠结 --update / --write | [backfill-flags.md](reference/backfill-flags.md) → `## BACKFILL_FLAGS` |
|
||||
| `BACKFILL_ORDER` | 需要完整回填命令序列与退出码口径 | [backfill-order.md](reference/backfill-order.md) → `## BACKFILL_ORDER` |
|
||||
| `BACKFILL_PITFALLS` | `--write` 说最新钩子还红、tsv 只 WARN、`--gate` SKIP 等边界 | [backfill-pitfalls.md](reference/backfill-pitfalls.md) → `## BACKFILL_PITFALLS` |
|
||||
| `MEASUREMENT_IDENTITY` | 跨树测量、重跑报告当新测量、数字与树/时刻脱钩 | [measurement-identity.md](reference/measurement-identity.md) → `## MEASUREMENT_IDENTITY` |
|
||||
| `SHARED_FRAME` | 多条链同涨同一数值、链接器幻影环 | [shared-frame-attribution.md](reference/shared-frame-attribution.md) → `## SHARED_FRAME` |
|
||||
| `RUNTIME_JITTER` | 跨启动峰值抖动、「不劣于上一轮」判据假红 | [runtime-jitter.md](reference/runtime-jitter.md) → `## RUNTIME_JITTER` |
|
||||
| `VERIFICATION` | 提交前核对这轮测量/数字入库是否算数 | [verification.md](reference/verification.md) → `## VERIFICATION` |
|
||||
|
||||
- 同一份镜像连续启动 5 次,`uiTask` 峰值实测在 4116~4188 之间摆 **72 B** ⇒ 跨启动本身就有几十 B 抖动,
|
||||
"相对上一轮 +100 B"**不可归因**于被测改动。判据写成"栈水位不劣于上一轮"必然假红。
|
||||
- 可执行修法(二选一,别都留着):
|
||||
1. 同一份像**≥3 次启动取最大值**互比,并加容差(**±128 B 量级**);
|
||||
2. 硬线改用 `stack_report.py` 的**静态最坏链**,运行时峰值降级为趋势参考。
|
||||
- 判据一改要同步**所有落点**:判据正文、跑判据的脚本、记录判据的文档三处一起改,只改一处等于各说各话。
|
||||
## 判读口径(改前改后都要看)
|
||||
|
||||
- **静态**:`stack_report.py` Max Depth(最坏链累计)vs `Src/freertos.c` 配置栈;判定式 `margin = cfg - max(static_max_depth, runtime_peak)` 须 ≥ `max(isr_margin, 30% of cfg)`。
|
||||
- **运行时**:开机日志 `[STACK] <task> peak_used=…/… free_min=…` 与静态对照——**静态最坏链是上界(硬线)、运行时峰值是下界证据(趋势)**,两者都要看,余量 <1KB 底线要上报。
|
||||
- **RAM 总量**:`ram_report.py` 对 Grand Totals 与 `docs/内存管理/` 预算表核对;`L6406E` = 已溢出,用按文件表找大头。
|
||||
- `task-table` 钩子保证任务表一致;`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92% 且核台账受管区与 .map 同源;`mem-numbers` 核文档内存数字。
|
||||
|
||||
## 权威构建后回填(默认命令块)
|
||||
|
||||
`.map` 是唯一事实源,台账/文档数字由脚本生成——**不手抄、不手改**。三旗标互斥(`add_mutually_exclusive_group()`),一次一件。权威构建(0 错 0 警)后依次:
|
||||
|
||||
```powershell
|
||||
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # 0) 权威构建先行
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --update # 1) 趋势行(纪律项,非回填)
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --write # 2) 回填台账受管区
|
||||
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --write # 3) 回填文档快照区
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate # 4) 0=阈值+受管区都过
|
||||
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan # 0=快照区与 .map 一致
|
||||
```
|
||||
|
||||
`ram_baseline.py` 0=通过或跳过 / 1=阈值超限或受管区漂移 / 2=.map 解析失败;`check_mem_numbers.py` 0=一致 / 1=不一致或缺锚点。旗标语义与完整序列见 `BACKFILL_FLAGS` / `BACKFILL_ORDER`。
|
||||
|
||||
## 成本模型(实测,估算用)
|
||||
|
||||
- **`DBG_*` 日志不是免费的**:每条调用点约 **90 B Flash**(字符串常量另计)+ 深链上
|
||||
每帧一份行缓冲进最坏栈(实测一条链 9 帧 ≈ 1.5 KB 纯日志缓冲)。
|
||||
已覆盖步骤勿加重复锚点,只在原先静默返回的黑洞处补。
|
||||
- **深调用链模块收紧行缓冲**:`#define DBG_LINE_BUF_MAX 128U` 写在 `#include "dbg_log.h"`
|
||||
之前;取值必须 ≥ 该模块最长日志行(时间戳 20 + 标签 + 正文),否则截断。
|
||||
- **加大局部缓冲的替代方案是静态化**(实测 lftpd 9 处大局部缓冲静态化:BSS +4.6 KB,
|
||||
任务峰值 3480B→1184B)——栈紧张时先找大局部变量。
|
||||
- **自研代码禁 C 库堆**(MicroLIB 堆仅 512B):只用 `pvPortMalloc/vPortFree`(FreeRTOS 堆),
|
||||
模拟器 CRT 堆照不出 MCU 堆分配失败。
|
||||
- **`DBG_*` 不免费**:每调用点约 90 B Flash(字符串常量另计)+ 深链每帧一份行缓冲(实测一条链 9 帧 ≈1.5 KB)。
|
||||
- **深链模块收紧行缓冲**:`#define DBG_LINE_BUF_MAX 128U` 写在 `#include "dbg_log.h"` 前,≥ 该模块最长日志行否则截断。
|
||||
- **加大局部缓冲的替代是静态化**(实测 lftpd 9 处静态化:BSS +4.6 KB,任务峰值 3480B→1184B)——栈紧张先找大局部变量。
|
||||
- **自研代码禁 C 库堆**(MicroLIB 堆仅 512B):只用 `pvPortMalloc/vPortFree`。
|
||||
|
||||
## 验证(这轮测量算数了吗)
|
||||
## 禁令(看着合理但致命,留在主文件)
|
||||
|
||||
1. 报告头 `- Source:` 的相对路径落在**我要量的那棵树**下(不是裸文件名,更不是别的树);
|
||||
2. `- Linker run:`(或 .htm 的 `Last Updated:` / mtime)与本轮那次构建对得上,且**不同于**上一轮那次的时刻
|
||||
——相同就是复述,回去先做一次构建再比;
|
||||
3. 树身份已按 `tree/commit + 时刻 + 产物来源` 写进提交正文/台账,而不是只留在终端输出里;
|
||||
4. 结论里互比的数字必须来自**同一棵树同一次链接**;跨树比较要各自给出树与时刻;
|
||||
5. 涉及劣化判定时注明依据的是静态最坏链(硬线)还是运行时峰值(趋势),并已计入跨启动抖动。
|
||||
6. 要入库的数字:本轮已按「`/keil-build` → `ram_baseline.py --update` → `ram_baseline.py --write` →
|
||||
`check_mem_numbers.py --write`」回填,并逐字自跑 `ram_baseline.py --gate` 与 `check_mem_numbers.py --scan` 各返 0;
|
||||
台账 / 文档 / tsv 的改动与代码同一笔入库,**未手改数字、未用 `--no-verify`**。
|
||||
- 改前/改后必须是**两次不同 Linker run**,重跑报告脚本不算新测量 → `MEASUREMENT_IDENTITY`。
|
||||
- **不手抄、不手改**台账/文档数字;**绝不 `--no-verify`**;台账/文档/tsv 改动与代码同一笔入库。
|
||||
- 只跑 `ram_baseline.py --update` 不回填受管区 = 钩子当场红——**`--update` 只喂趋势行,不等于回填**。
|
||||
- 回填读的是**盘上那份 .map**,构建没落定就 `--write` = 把旧数字写进台账。
|
||||
- 判据涉及劣化时区分静态最坏链(硬线)还是运行时峰值(趋势),并计入跨启动抖动 → `RUNTIME_JITTER`。
|
||||
|
||||
## 其它项目怎么套
|
||||
## 其它项目怎么套 / 衔接
|
||||
|
||||
模式通用:链接器 map + 调用图 htm 是**免硬件**的栈可观测源;固定"改前改后各跑一次
|
||||
报告 + 运行时水位叠加 + 余量阈值"三件套,**外加一条身份口径——脚本按自身位置定位产物,
|
||||
跨树比的是"两棵树各自的脚本 + 各自的链接时刻",重跑同一份产物永远只是复述**。
|
||||
本仓库两个报告脚本按 Keil 输出格式解析,换工具链(GCC newlib + `-fstack-usage`)需替换解析层,工作流不变。
|
||||
模式通用:链接器 map + 调用图 htm 是免硬件栈可观测源;固定"改前改后各跑一次报告 + 运行时水位叠加 + 余量阈值"三件套,外加身份口径(跨树比的是两棵树各自的脚本 + 各自链接时刻)。本仓两脚本按 Keil 格式解析,换工具链(GCC newlib + `-fstack-usage`)替换解析层、工作流不变。衔接:构建 `keil-build`(收尾固定链 `/keil-build` → 本 skill 回填 → 体积门禁 → `ci_local` 静态段);并行树身份 `task-worktree`。
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
# 权威构建后的台账回填:三个旗标(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## BACKFILL_FLAGS
|
||||
|
||||
> 路由:主文件失败索引表 `BACKFILL_FLAGS` → 本节。原节 `## 权威构建后的台账回填`(L57–78)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
mem-budget / mem-numbers 钩子报「与 .map 不一致」= 构建后只跑 `--update` 没回填受管区/快照区。
|
||||
|
||||
### 处置
|
||||
|
||||
三份落点 = 三个旗标(互斥组,一次一件):`ram_baseline.py --update` 只喂趋势行 / `--write` 回填台账受管区 / `check_mem_numbers.py --write` 回填文档快照区。改完逐字自跑 `--gate` 与 `--scan` 各返 0。
|
||||
|
||||
### 证据边界
|
||||
|
||||
旗标互斥组代码事实 `scripts/ram_baseline.py:415-419`;钩子 entry 行号见逐字原文(换仓须核)。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 权威构建后的台账回填(三个旗标,别混)
|
||||
|
||||
`.map` 是内存/Flash 数字的**唯一事实源**;台账与文档里的数字由脚本从它生成——**不手抄、不手改**
|
||||
(`docs/内存管理/RAM预算台账.md` 首段就写着"数字不手抄")。三份落点 = 三个旗标,一条命令只干其中一件:
|
||||
`ram_baseline.py` 的 `--gate/--write/--update/--trend` 是 `add_mutually_exclusive_group()`
|
||||
(`scripts/ram_baseline.py:415-419`),想干两件就得调两次。
|
||||
|
||||
| 落点 | 旗标 | 实际改了什么 |
|
||||
|---|---|---|
|
||||
| `scripts/ram_baseline.tsv` 趋势基线(顺带刷 `scripts/size_attestation.json` 同码凭证) | `ram_baseline.py --update` | **只**追加/覆盖当日那一行趋势(Code/RO/RW/ZI + 三区水位 + Top-10 RW+ZI)。**不碰台账正文** |
|
||||
| `docs/内存管理/RAM预算台账.md` 的 `<!-- MEM_BUDGET:BEGIN/END -->` 受管区 | `ram_baseline.py --write` | 从 .map 重渲染区域水位 + 子系统配额对照(打印「已同步台账受管区。」或「台账受管区已是最新。」) |
|
||||
| `docs/内存管理/RAM使用分析与优化方案.md` 的 `<!-- MEM_SNAPSHOT:BEGIN/END -->` 快照区 | `check_mem_numbers.py --write` | 从**同一份** .map 重渲染内存/Flash 快照表(打印「已更新内存快照:…」) |
|
||||
|
||||
**台账 §4 那句「每次 `/keil-build` 后跑 `scripts/ram_baseline.py --update`」只喂趋势行,不等于回填受管区。**
|
||||
实测代价:照那句跑完 `--update` 就提交 → `mem-budget`、`mem-numbers` 两条钩子当场红。
|
||||
`mem-budget` 的 entry 是 `python scripts/ram_baseline.py --gate`(`.pre-commit-config.yaml:571`)——它在 92% 阈值之外
|
||||
还核**台账受管区与 .map 的一致性**,漂移即 `[FAIL] 台账受管区与 .map 不一致(区域水位或子系统配额表漂移)`
|
||||
并打印 `修复:python scripts/ram_baseline.py --write`(`scripts/ram_baseline.py:221-224`);
|
||||
`mem-numbers` 的 entry 是 `python scripts/check_mem_numbers.py --scan`(同文件 :193),不一致时打印
|
||||
`修复:运行 python scripts/check_mem_numbers.py --write`(`scripts/check_mem_numbers.py:416`)。
|
||||
改用两个 `--write` 后重提,同一笔提交触发的 26 条钩子全 Passed。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 提交前固定顺序(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## BACKFILL_ORDER
|
||||
|
||||
> 路由:主文件失败索引表 `BACKFILL_ORDER` → 本节。原节 `### 提交前固定顺序`(L79–105)逐字搬移;主文件保留精简默认命令块。
|
||||
|
||||
### 判据
|
||||
|
||||
需要完整回填命令序列与退出码口径时读本节。
|
||||
|
||||
### 处置
|
||||
|
||||
按 构建 → --update → --write → check_mem_numbers --write → --gate/--scan → git add 的固定顺序执行。
|
||||
|
||||
### 证据边界
|
||||
|
||||
回填读的是盘上那份 .map,构建没落定就 --write = 写旧数字;2026-10 实测 26 条钩子全 Passed。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### 提交前固定顺序(构建 → 回填 → 真钩子提交)
|
||||
|
||||
```powershell
|
||||
# cwd = 项目根,一律 .venv 解释器
|
||||
# 0) 权威构建先行(0 错 0 警):回填读的是**盘上那份 .map**,构建没落定就 --write = 把旧数字写进台账,钩子照样红
|
||||
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
|
||||
|
||||
# 1) 趋势行(纪律项,不是回填):覆盖 tsv 当日行 + 顺带刷体积同码凭证
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --update
|
||||
|
||||
# 2) 回填台账受管区(mem-budget 钩子核的就是这一段)
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --write
|
||||
|
||||
# 3) 回填文档快照区(mem-numbers 钩子核的就是这一张表)
|
||||
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --write
|
||||
|
||||
# 4) 逐字自跑提交时会跑的这两条 entry(比事后翻 pre-commit 输出快)
|
||||
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate # 0 = 阈值 + 受管区都过
|
||||
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan # 0 = 快照区与 .map 一致
|
||||
|
||||
# 5) 把刚落盘的落点一并 add,然后**真钩子**提交(绝不 --no-verify、绝不手改数字)
|
||||
git add docs/内存管理/RAM预算台账.md docs/内存管理/RAM使用分析与优化方案.md scripts/ram_baseline.tsv scripts/size_attestation.json
|
||||
```
|
||||
|
||||
退出码:`ram_baseline.py` 0=通过或跳过 / **1=阈值超限或受管区漂移** / 2=.map 解析失败;
|
||||
`check_mem_numbers.py` 0=一致 / 1=不一致、缺受管锚点或找不到事实源。
|
||||
@@ -1,5 +1,23 @@
|
||||
# 回填链上的坑(实测)(自 SKILL.md 外置)
|
||||
|
||||
## BACKFILL_PITFALLS
|
||||
|
||||
> 路由:主文件失败索引表 `BACKFILL_PITFALLS` → 本节。原节(自 SKILL.md 外置)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
`--write` 说「已是最新」钩子还红、tsv 落后只 WARN、`--gate` 无 .map 却 SKIP 等回填链边界症状时读本节。
|
||||
|
||||
### 处置
|
||||
|
||||
按逐条原文处置(落点找对、SKIP≠PASS、`--map` 只换读不换写等)。
|
||||
|
||||
### 证据边界
|
||||
|
||||
均为实测(节内标注);改写型钩子当场改文件是流程不是故障。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
> 本文由 mem-budget 的 SKILL.md「回填链上的坑(实测)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。
|
||||
|
||||
- **`--write` 说「已是最新」而钩子还红** ≠ 钩子坏了,是**落点找错了**:tsv / 台账受管区 / 文档快照区
|
||||
|
||||
@@ -1,5 +1,23 @@
|
||||
# 测量身份口径(先钉树与时刻,再看数字)(自 SKILL.md 外置)
|
||||
|
||||
## MEASUREMENT_IDENTITY
|
||||
|
||||
> 路由:主文件失败索引表 `MEASUREMENT_IDENTITY` → 本节。原节(自 SKILL.md 外置)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
在主树跑脚本量任务树、重跑报告脚本当新测量、或 .htm/.map 与树/时刻脱钩时读本节。
|
||||
|
||||
### 处置
|
||||
|
||||
脚本按 `__file__` 定位产物(跨树换脚本);只有新 Linker run 才算新测量;身份最小格式 = tree/commit + Linker run 时刻 + 产物来源。
|
||||
|
||||
### 证据边界
|
||||
|
||||
2026-10 实测;`.htm/.map` 按约定不入库,故须把时刻写进正文/台账。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
> 本文由 mem-budget 的 SKILL.md「测量身份口径(先钉树与时刻,再看数字)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。
|
||||
|
||||
### 1. 脚本按 `__file__` 定位产物,不按 cwd —— 跨树必须换脚本
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# 运行时峰值抖动与劣化判据(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## RUNTIME_JITTER
|
||||
|
||||
> 路由:主文件失败索引表 `RUNTIME_JITTER` → 本节。原节 `## 运行时峰值抖动`(L118–126)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
跨启动几十 B 抖动下,「栈水位不劣于上一轮」这类判据会假红。
|
||||
|
||||
### 处置
|
||||
|
||||
二选一:≥3 次启动取最大值 + ±128 B 容差互比,或硬线改用静态最坏链、运行时峰值降趋势参考;判据一改同步正文/脚本/文档三处。
|
||||
|
||||
### 证据边界
|
||||
|
||||
uTask 连续 5 次启动 4116~4188 摆 72 B 为 2026 实测;容差量级须按本仓重测。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 运行时峰值抖动与"算不算劣化"
|
||||
|
||||
- 同一份镜像连续启动 5 次,`uiTask` 峰值实测在 4116~4188 之间摆 **72 B** ⇒ 跨启动本身就有几十 B 抖动,
|
||||
"相对上一轮 +100 B"**不可归因**于被测改动。判据写成"栈水位不劣于上一轮"必然假红。
|
||||
- 可执行修法(二选一,别都留着):
|
||||
1. 同一份像**≥3 次启动取最大值**互比,并加容差(**±128 B 量级**);
|
||||
2. 硬线改用 `stack_report.py` 的**静态最坏链**,运行时峰值降级为趋势参考。
|
||||
- 判据一改要同步**所有落点**:判据正文、跑判据的脚本、记录判据的文档三处一起改,只改一处等于各说各话。
|
||||
@@ -1,5 +1,23 @@
|
||||
# 静态最坏链回归的归因(同涨同一数值 = 共享帧,不是调用方)(自 SKILL.md 外置)
|
||||
|
||||
## SHARED_FRAME
|
||||
|
||||
> 路由:主文件失败索引表 `SHARED_FRAME` → 本节。原节(自 SKILL.md 外置)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
多条任务链分毫不差同涨/同降同一数值 = 共用被调帧/链接器幻影环,不在任何调用方。
|
||||
|
||||
### 处置
|
||||
|
||||
逐树逐帧比 frame size(`stack_report.py` own-frame 表锁尾段);`grep -ac 'In Cycle'` 找环;处置后抬栈或断环,改前改后各跑一次报告且「改后」落在新的 Linker run。
|
||||
|
||||
### 证据边界
|
||||
|
||||
default/net/iec104 三条 +80 B、断环后九条 −80 B 为实测;静态数是估计值(+Unknown Cycles),别当精确值上报。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
> 本文由 mem-budget 的 SKILL.md「静态最坏链回归的归因(同涨同一数值 = 共享帧,不是调用方)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。
|
||||
|
||||
- **多条任务链分毫不差同涨/同降同一个数值**(实测 default/net/iec104 三条 +80 B;断环后九条链各 −80 B)
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# 验证:这轮测量算数了吗(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## VERIFICATION
|
||||
|
||||
> 路由:主文件失败索引表 `VERIFICATION` → 本节。原节 `## 验证`(L139–150)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
提交前逐条确认报告头 Source 路径、Linker run 时刻、树身份、数字同源。
|
||||
|
||||
### 处置
|
||||
|
||||
按原文六条逐项核对;入库数字须走完整回填链且逐字自跑 --gate/--scan 各返 0。
|
||||
|
||||
### 证据边界
|
||||
|
||||
「相同时刻 = 复述」判据见逐字原文。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 验证(这轮测量算数了吗)
|
||||
|
||||
1. 报告头 `- Source:` 的相对路径落在**我要量的那棵树**下(不是裸文件名,更不是别的树);
|
||||
2. `- Linker run:`(或 .htm 的 `Last Updated:` / mtime)与本轮那次构建对得上,且**不同于**上一轮那次的时刻
|
||||
——相同就是复述,回去先做一次构建再比;
|
||||
3. 树身份已按 `tree/commit + 时刻 + 产物来源` 写进提交正文/台账,而不是只留在终端输出里;
|
||||
4. 结论里互比的数字必须来自**同一棵树同一次链接**;跨树比较要各自给出树与时刻;
|
||||
5. 涉及劣化判定时注明依据的是静态最坏链(硬线)还是运行时峰值(趋势),并已计入跨启动抖动。
|
||||
6. 要入库的数字:本轮已按「`/keil-build` → `ram_baseline.py --update` → `ram_baseline.py --write` →
|
||||
`check_mem_numbers.py --write`」回填,并逐字自跑 `ram_baseline.py --gate` 与 `check_mem_numbers.py --scan` 各返 0;
|
||||
台账 / 文档 / tsv 的改动与代码同一笔入库,**未手改数字、未用 `--no-verify`**。
|
||||
@@ -15,6 +15,13 @@ whenToUse: 换新机器/新克隆要把环境搭起来、构建或烧录报"环
|
||||
|
||||
逐项 PASS/WARN/FAIL + 缺件时打印**可直接执行的修复命令**;退出码 0=可用 / 1=有 FAIL。
|
||||
|
||||
**成功输出样例**(本轮实跑 `env_check.py`,`PYTHONIOENCODING=utf-8`):看到末行 `SUMMARY: OK - 环境可用` 就是环境就绪,不用再往下看。
|
||||
|
||||
```text
|
||||
PASS 串口配置档案 <项目根>/.serialtest/config.json
|
||||
SUMMARY: OK - 环境可用(WARN 项按提示处理)
|
||||
```
|
||||
|
||||
## 搭建顺序(自检 FAIL 时的完整路径)
|
||||
|
||||
1. **venv**:`& <任一 python ≥3.10> -m venv .venv` →
|
||||
|
||||
@@ -31,6 +31,14 @@ cmake --build simulator/build --config Debug # 0 警告
|
||||
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # BUILD_OK,0 错 0 警
|
||||
```
|
||||
|
||||
**成功输出样例**(Keil 端判据串出处:`.dsh/skills/keil-build/scripts/keil_build.py` 的成功打印 `BUILD_OK: 0 errors, 0 warnings`;模拟器端为本轮实跑 `cmake --build simulator/build --config Debug` 的末行):看到 `BUILD_OK: 0 errors, 0 warnings` + `lvgl_sim.vcxproj -> ...\lvgl_sim.exe` 就是双端都通了,不用再往下看。
|
||||
|
||||
```text
|
||||
UV4_RC: 0
|
||||
BUILD_OK: 0 errors, 0 warnings
|
||||
lvgl_sim.vcxproj -> ...\simulator\build\Debug\lvgl_sim.exe
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- **禁止**把源文件复制进 `simulator/`——两端共用 `Drivers/BSP/` 原件(UI_界面制作流程.md C7)
|
||||
|
||||
@@ -38,6 +38,13 @@ python -m venv ".dsh\skills\serial-assistant\venv"
|
||||
& $PY $TOOL selftest # 无头自检(行拆分/解码/截头/wait 判据,无需硬件)
|
||||
```
|
||||
|
||||
**成功输出样例**(本轮实跑 `serial_tool.py selftest`):看到 `selftest: 45/45 passed` + `SELFTEST PASS` 就是采集层自检通了,不用再往下看。
|
||||
|
||||
```text
|
||||
selftest: 45/45 passed
|
||||
SELFTEST PASS
|
||||
```
|
||||
|
||||
**抓开机日志铁律**:`open` → `clear` → 烧录/复位 → `wait-idle` → 读日志校验标记
|
||||
(采集必须先于烧录,否则错过开机头几行)。
|
||||
|
||||
|
||||
@@ -34,26 +34,9 @@ whenToUse: 需要向目标板烧录或复位后,用串口日志自动判定运
|
||||
|
||||
配置解析顺序:`$DSH_SERIAL_CONFIG` > `<cwd>/.serialtest/config.json` > `<cwd>/.opencode/serial_config.json`(旧位置,仅串口字段)。
|
||||
|
||||
若项目没有 `.serialtest/config.json`:**先从项目文档(入口文件/README/测试文档)推断各字段,推断不了的问用户**,然后按 `config.example.json` 写一份。字段含义:
|
||||
若项目没有 `.serialtest/config.json`:**先从项目文档(入口文件/README/测试文档)推断各字段,推断不了的问用户**,然后按 `config.example.json` 写一份。
|
||||
|
||||
| 键 | 含义 | 缺省行为 |
|
||||
|---|---|---|
|
||||
| `portName` / `baudRate` | 串口 | 无 portName 直接 exit 3 |
|
||||
| `flash_cmd` | 烧录命令(**必须含复位运行**,如 `-Rst -Run`;可带参数) | 空 = 不烧录,脚本提示人工复位板子 |
|
||||
| `hex` | 刚构建的镜像(Intel HEX),供身份戳 + 回读比对 | 空 = 两项都跳过(WARN) |
|
||||
| `fw_marker` | 固件身份戳前缀(固件里打印 `"<前缀>" __DATE__ " " __TIME__`) | 默认 `fw build: `;hex 里无此串只 WARN 不假判 |
|
||||
| `readback_cmd` | 回读校验命令模板,`{hex}` = 镜像路径(引号自动加) | 空 = 跳过 |
|
||||
| `readback_ok` | 回读成功判据(按行首匹配,大小写不敏感) | `no difference found` |
|
||||
| `required` | 必须出现的标记(`;` 分隔,大小写敏感) | **空 = exit 3**(必须给) |
|
||||
| `forbidden` | 禁止出现的模式(`;` 分隔,大小写不敏感) | `FAIL;ERROR;HardFault` |
|
||||
| `boot_marker` | 一轮启动的锚点子串(如 `reset cause:`) | 空 = 锚点计数关闭 |
|
||||
| `max_boot_count` | 锚点出现 0 次或 >N 次 = FAIL | 1(仅 boot_marker 非空时生效) |
|
||||
| `done_marker` + `max_boot_ms` | 开机耗时口径与上限 | 空/0 = 只报告不判 |
|
||||
| `settle_ms` / `max_wait_ms` / `first_wait_ms` | RX 静默判据 / 总超时 / 首字节超时 | 8000 / 30000 / 12000 |
|
||||
| `require_order` / `expect_reset_cause` / `require_suite_summary` | 顺序校验 / 复位原因白名单 / 套件汇总行 | 空 = 关闭 |
|
||||
| `selftest_scope` | 自检台账判定口径:`this-run`(烧录前取基线,只判新增)/ `all`(累计,任一记录即 FAIL) | `this-run` |
|
||||
| `ftp_user` / `ftp_pass` | 抓 `/log/selftest.log` 用的 FTP 账号(设备无匿名通道) | `admin` / `admin` |
|
||||
| `require_selftest_pass` + `device_ip` | 设备侧自检台账联合判定(FTP 抓取;**默认只判本次启动新增**,抓取失败/无数据源一律 FAIL) | 关闭 |
|
||||
- [ ] **config-schema** → 字段含义与缺省行为全表(`portName`/`flash_cmd`/`required`/`settle_ms`… 共 16 行),只在**首次配置或调参**时读 → [config-schema.md](reference/config-schema.md) 的 `config-schema` 节。
|
||||
|
||||
**先跑项目的构建**(本仓库 = `keil-build` skill,其它 Keil 项目照该 skill 套;
|
||||
非 Keil 项目用项目自己的构建入口),确认 0 错误 0 警告后再进闭环。
|
||||
@@ -70,25 +53,33 @@ whenToUse: 需要向目标板烧录或复位后,用串口日志自动判定运
|
||||
|
||||
退出码:`0=PASS` / `1=FAIL`(标记缺失或命中)/ `2=采集或烧录错误`(含回读不一致,本次运行作废)/ `3=用法/预检错误`。
|
||||
|
||||
**成功输出样例**(真实产物 `docs/测试说明/测试数据/boot_log_data/20261012_B9_prod_boot_log.txt` 尾两行,本次实跑 `verify_log.py --selftest` 同为 `VERDICT: PASS`):看到 `VERDICT: PASS` + `RUN_TEST_RC=0` 就是通了,不用再往下看。
|
||||
|
||||
```text
|
||||
VERDICT: PASS
|
||||
RUN_TEST_RC=0
|
||||
```
|
||||
|
||||
失败时脚本打印 `RUN_TEST_ERROR` / `RUN_TEST_FAIL` / `RUN_TEST_VERDICT` 三类稳定键 → 按「失败处置索引」读同名小节。
|
||||
|
||||
产物:boot log(每行带 `[+Nms]` 相对时基)写到 `%TEMP%\serial-boot-test\boot_log_<时间戳>.txt`(`--out-dir` 改,保留最近 20 份)。
|
||||
|
||||
## 第三步:判读与迭代
|
||||
|
||||
- **PASS** → 报告命中的标记与开机耗时。
|
||||
- **FAIL** → `[MISS]`/`[HIT]` 行(Forbidden 命中带行号+内容)+ 日志尾部已给出;需要更多上下文直接 Read/Grep boot log 文件或 `status` 里 `log.path` 指向的 serial.log。修代码 → 重新构建 → 重跑闭环。
|
||||
- **exit 2 `no_data`** → 板子全程零字节:查端口在位(`ports`)、板电、烧录命令是否真的复位了目标。
|
||||
- **PASS** → 报告命中的标记与开机耗时(看到 `VERDICT: PASS` + `RUN_TEST_RC=0` 就是通了,不用再往下看)。
|
||||
- **FAIL / exit 2** → `[MISS]`/`[HIT]` 行(Forbidden 命中带行号+内容)+ 日志尾部已给出;需要更多上下文直接 Read/Grep boot log 文件或 `status` 里 `log.path` 指向的 serial.log。脚本会打印 `RUN_TEST_*` 索引键 → 按下表读对应小节再修代码 → 重新构建 → 重跑闭环。
|
||||
|
||||
## 交互式串口调试(不跑闭环时)
|
||||
|
||||
用 **`serial-assistant` skill**(`ports/open/send/log/clear/wait-idle/status` 全套命令、
|
||||
抓开机日志铁律、daemon 陷阱都在那边)。本 skill 不重复采集层用法。
|
||||
|
||||
## 陷阱(都是实测教训)
|
||||
## 失败处置索引(退出码 / 脚本输出前缀 → 同名小节)
|
||||
|
||||
- **daemon 一台机只有一个**(HTTP 口 18765 独占绑定,由采集层 serial-assistant 管理)。改配置后必须 `restart`(daemon 启动时缓存配置)。若机器上还有旧 daemon,先 `status` 看 `daemon.version`(serial-assistant 版 = `1.1.0-skill`)确认归属,必要时 `stop` 后重开。
|
||||
- **回读校验排在日志采集之后**:部分烧录工具(如 ST-LINK `-CmpFile`)连接时会复位目标,提前跑会截断开机日志。脚本已按此顺序,勿手工调换。
|
||||
- **烧录命令必须让目标复位运行**(裸 `-P` 类写入在目标核死循环时不落地);写完镜像后 `fw build` 身份戳校验会揭穿"芯片还是旧镜像"。
|
||||
- **`settle_ms` 必须大于固件的自然静默间隙**(常见 3~4s),默认 8000;日志被截断先调大它。
|
||||
- **Required 标记宁少勿多**:先用启动锚点 + 少数里程碑标记;按用例临时覆盖 `--forbidden`(预期出现的 `[ERR]` 负路径用例)。
|
||||
- **烧录与串口采集不冲突**:SWD 下载走探针、调试日志走 USB-serial(CH340 类),互不占用;烧录期间串口侧静默几秒属正常,不算 `no_data`(首字节门会兜住)。
|
||||
- 中文/编码:脚本全程字节级处理,不受控制台代码页影响;配置文件存 UTF-8(BOM 容忍)。
|
||||
闭环失败时脚本会自己打印稳定索引键;按该键到 [troubleshooting.md](reference/troubleshooting.md) 读**同名小节**(每节 = 判据 / 处置 / 证据边界)。正常路径不展开。
|
||||
|
||||
| 失败信息自带索引键 | 何时读(触发条件) | 去哪 |
|
||||
|---|---|---|
|
||||
| `RUN_TEST_ERROR` | 打印 `RUN_TEST_ERROR:` 前缀 = 环境/采集/用法错,本次运行作废 | `troubleshooting.md` 的 `RUN_TEST_ERROR` 节 |
|
||||
| `RUN_TEST_FAIL` | 打印 `RUN_TEST_FAIL:` 前缀 = 采到了但标记判定失败 | `troubleshooting.md` 的 `RUN_TEST_FAIL` 节 |
|
||||
| `RUN_TEST_VERDICT` | 汇总行 `RUN_TEST_VERDICT: FAIL` 或 `RUN_TEST_RC=` 非 0 | `troubleshooting.md` 的 `RUN_TEST_VERDICT` 节 |
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# 项目档案字段表(自 SKILL.md「第一步:项目档案」逐字外置)
|
||||
|
||||
> 何时读:**每个项目只配一次** `.serialtest/config.json` 时读它;日常跑闭环不需要展开。
|
||||
> 主文件保留配置解析顺序与"先构建、字段推断不了问用户"的约束;本节只有字段含义表。
|
||||
|
||||
## config-schema
|
||||
|
||||
**判据(字段齐全)**:配置解析顺序:`$DSH_SERIAL_CONFIG` > `<cwd>/.serialtest/config.json` > `<cwd>/.opencode/serial_config.json`(旧位置,仅串口字段)。若项目没有 `.serialtest/config.json`:先从项目文档(入口文件/README/测试文档)推断各字段,推断不了的问用户,然后按 `config.example.json` 写一份。字段含义(逐字来自原表):
|
||||
|
||||
| 键 | 含义 | 缺省行为 |
|
||||
|---|---|---|
|
||||
| `portName` / `baudRate` | 串口 | 无 portName 直接 exit 3 |
|
||||
| `flash_cmd` | 烧录命令(**必须含复位运行**,如 `-Rst -Run`;可带参数) | 空 = 不烧录,脚本提示人工复位板子 |
|
||||
| `hex` | 刚构建的镜像(Intel HEX),供身份戳 + 回读比对 | 空 = 两项都跳过(WARN) |
|
||||
| `fw_marker` | 固件身份戳前缀(固件里打印 `"<前缀>" __DATE__ " " __TIME__`) | 默认 `fw build: `;hex 里无此串只 WARN 不假判 |
|
||||
| `readback_cmd` | 回读校验命令模板,`{hex}` = 镜像路径(引号自动加) | 空 = 跳过 |
|
||||
| `readback_ok` | 回读成功判据(按行首匹配,大小写不敏感) | `no difference found` |
|
||||
| `required` | 必须出现的标记(`;` 分隔,大小写敏感) | **空 = exit 3**(必须给) |
|
||||
| `forbidden` | 禁止出现的模式(`;` 分隔,大小写不敏感) | `FAIL;ERROR;HardFault` |
|
||||
| `boot_marker` | 一轮启动的锚点子串(如 `reset cause:`) | 空 = 锚点计数关闭 |
|
||||
| `max_boot_count` | 锚点出现 0 次或 >N 次 = FAIL | 1(仅 boot_marker 非空时生效) |
|
||||
| `done_marker` + `max_boot_ms` | 开机耗时口径与上限 | 空/0 = 只报告不判 |
|
||||
| `settle_ms` / `max_wait_ms` / `first_wait_ms` | RX 静默判据 / 总超时 / 首字节超时 | 8000 / 30000 / 12000 |
|
||||
| `require_order` / `expect_reset_cause` / `require_suite_summary` | 顺序校验 / 复位原因白名单 / 套件汇总行 | 空 = 关闭 |
|
||||
| `selftest_scope` | 自检台账判定口径:`this-run`(烧录前取基线,只判新增)/ `all`(累计,任一记录即 FAIL) | `this-run` |
|
||||
| `ftp_user` / `ftp_pass` | 抓 `/log/selftest.log` 用的 FTP 账号(设备无匿名通道) | `admin` / `admin` |
|
||||
| `require_selftest_pass` + `device_ip` | 设备侧自检台账联合判定(FTP 抓取;**默认只判本次启动新增**,抓取失败/无数据源一律 FAIL) | 关闭 |
|
||||
|
||||
**处置**:按表逐字段填好,再回主文件「先跑项目的构建」→「跑闭环」。字段缺省行为已经写全,不要凭印象另设默认。
|
||||
|
||||
**证据边界**:本表逐字外置自原 SKILL.md,缺省值是脚本当时的行为;脚本若改了默认,以脚本为准(本表不自动同步脚本语义)。
|
||||
@@ -0,0 +1,37 @@
|
||||
# 串口闭环失败处置(自 SKILL.md「陷阱」一节逐字外置)
|
||||
|
||||
> 何时读:闭环退出码非 0,或脚本打印 `RUN_TEST_ERROR` / `RUN_TEST_FAIL` / `RUN_TEST_VERDICT: FAIL` 时。
|
||||
> 主文件的失败索引表按这三个稳定前缀指向这里;正常路径不要展开本篇。
|
||||
|
||||
## RUN_TEST_ERROR
|
||||
|
||||
**判据**:`run_boot_test.py` 打印 `RUN_TEST_ERROR:` 前缀(配置解析失败、无 `--port`/无 `required`、open/clear/wait-idle/log 采集失败、`no_data`、回读不一致等)。这些是**环境/采集/用法错**,本次运行作废,不是标记判定结果。
|
||||
|
||||
**处置**:逐条对照原「陷阱」清单:
|
||||
|
||||
- **daemon 一台机只有一个**(HTTP 口 18765 独占绑定,由采集层 serial-assistant 管理)。改配置后必须 `restart`(daemon 启动时缓存配置)。若机器上还有旧 daemon,先 `status` 看 `daemon.version`(serial-assistant 版 = `1.1.0-skill`)确认归属,必要时 `stop` 后重开。
|
||||
- **回读校验排在日志采集之后**:部分烧录工具(如 ST-LINK `-CmpFile`)连接时会复位目标,提前跑会截断开机日志。脚本已按此顺序,勿手工调换。
|
||||
- **烧录命令必须让目标复位运行**(裸 `-P` 类写入在目标核死循环时不落地);写完镜像后 `fw build` 身份戳校验会揭穿"芯片还是旧镜像"。
|
||||
- **`settle_ms` 必须大于固件的自然静默间隙**(常见 3~4s),默认 8000;日志被截断先调大它。
|
||||
- **烧录与串口采集不冲突**:SWD 下载走探针、调试日志走 USB-serial(CH340 类),互不占用;烧录期间串口侧静默几秒属正常,不算 `no_data`(首字节门会兜住)。
|
||||
|
||||
**证据边界**:以上为实测教训,不替代 `RUN_TEST_ERROR:` 行本身给出的具体原因;端口/板电问题须先查 `ports`、板电、烧录命令是否真的复位目标。`no_data`(板子全程零字节)按采集层排查。
|
||||
|
||||
## RUN_TEST_FAIL
|
||||
|
||||
**判据**:`run_boot_test.py` 打印 `RUN_TEST_FAIL:` 前缀——标记判定侧的失败(如要求自检台账判定却无 `device_ip` 也无 `--selftest-log`、自检台账抓取失败)。此时日志已采到,判定结果为 FAIL。
|
||||
|
||||
**处置**:按失败行补齐数据源(提供 `device_ip` 或 `--selftest-log`)或修正标记配置;修完重新闭环。`RUN_TEST_FAIL` 与 `RUN_TEST_ERROR` 的区别:前者是"采到了但判失败",后者是"没采成、运行作废"。对应主文件索引键 `RUN_TEST_FAIL`。
|
||||
|
||||
**证据边界**:自检台账默认按 `this-run`(只判本次启动新增)口径;抓取失败或缺数据源一律 FAIL 而非 PASS,不要把"没数据"当"设备干净"。
|
||||
|
||||
## RUN_TEST_VERDICT
|
||||
|
||||
**判据**:闭环汇总行 `RUN_TEST_VERDICT: FAIL` 或 `RUN_TEST_RC=`(非 0)——整轮判定收口。配套原「陷阱」条目:
|
||||
|
||||
- **Required 标记宁少勿多**:先用启动锚点 + 少数里程碑标记;按用例临时覆盖 `--forbidden`(预期出现的 `[ERR]` 负路径用例)。
|
||||
- 中文/编码:脚本全程字节级处理,不受控制台代码页影响;配置文件存 UTF-8(BOM 容忍)。
|
||||
|
||||
**处置**:`RUN_TEST_RC=1` 时看上方 `[MISS]`/`[HIT]` 行(Forbidden 命中带行号+内容)+ 日志尾部定位;`RUN_TEST_VERDICT: FAIL —— 自检台账判定未能执行` 时按 `run_test_fail` 处置。`RUN_TEST_RC=0` 且 `VERDICT: PASS` 才算通。
|
||||
|
||||
**证据边界**:`RUN_TEST_VERDICT: FAIL` 只是汇总,根因在上面各 `[MISS]`/`[HIT]`/`RUN_TEST_*` 行;本节点不重复标记校验判据(那在 `verify_log.py` 侧)。
|
||||
@@ -57,17 +57,6 @@ whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「
|
||||
- 新写文本撞编号门禁
|
||||
> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。
|
||||
|
||||
## Verification
|
||||
## 收口验收(只在提交前打勾/回报时读)
|
||||
|
||||
提交前逐条打勾;回报时**逐处列文件 + 命中数断言**,不要笼统说「已全部更新」。
|
||||
|
||||
- [ ] 每个数都写了**两个独立来源**且数值一致(`ref/shot_*.bin` 实数 = `PAGES` 条目数;`UI_PAGE_MAP_COUNT` = 剔伪命中后的 `#page=` 计数),并在结论里贴出该数字与伪命中取舍理由
|
||||
- [ ] 字形数说明**是否剔除 notdef**并给出条目数→字形数的换算(条目数 − 1 = 字形数,2026-10-29 现值 320 − 1 = 319);字数说明**是否含 ASCII**,且该口径句与实测一致
|
||||
- [ ] 分类表逐条列出:改了哪些当前态、哪些历史行保留、哪些误报不动(附理由)、哪些只加「当时」、哪些属**口径错**并已另起一笔
|
||||
- [ ] 替换脚本打印了每处 `old -> new xN` 且每处 `assert` 通过(无半落地;报错时已 `git diff --stat` 确认零写入)
|
||||
- [ ] 命中面覆盖 `.pre-commit-config.yaml` 钩子 `name:`、`AGENTS.md`(钩子数等入口级计数)、`docs/**`、`scripts/**`、`.dsh/skills/*/SKILL.md`,逐条在改动清单里出现
|
||||
- [ ] 被改文件已全文通读,同文档各小节与配套 README/清单的顺序、计数、完成状态一致;口径闭合(如 `未绑 = 待做 + 不做`)
|
||||
- [ ] 变更记录:**保留的 5 篇真台账**(清单 → `docs/文档规范.md` §5.1)历史行原文未动;其余文档本轮**零新增流水行**(当前态改完即止);钩子一增一减这类过程细节写进提交正文,不写进文档
|
||||
- [ ] **提交后**又按全部旧形态复扫一次,当前态残留 = **0**,每条剩余命中都能归类(历史行 / 误报 / 已加「当时」);发现的漏网当前态已单独补一笔
|
||||
- [ ] `check_doc_links.py --all --sections-strict` 打印「文档路径检查通过(N 个文档)」;`ci_local.py` / `pre-commit` 全绿(RC=0、`failed=0`);BOM 与原文件一致、无 `EF BF BD`
|
||||
- [ ] 分笔提交完成,回报 commit 号 + 每笔改了哪些文件 + 没动的那几类及理由
|
||||
- [ ] **verification** → 提交前逐条打勾的 10 项验收清单 + 回报口径(逐处列文件 + 命中数断言)→ 读 [verification.md](reference/verification.md) 的 `verification` 节。
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# 收口验收清单(自 SKILL.md「Verification」一节逐字外置)
|
||||
|
||||
> 何时读:提交前逐条打勾、回报验收时。主文件只留一行索引;动手扫描/替换过程中不要展开本篇。
|
||||
> 「各计数的权威口径速查」大表留在主文件——每次动手都要对表,不属于长尾。
|
||||
|
||||
## verification
|
||||
|
||||
**判据(逐条打勾)**:以下 10 条来自原 SKILL.md「Verification」节,逐字保留、未改写。回报时**逐处列文件 + 命中数断言**,不要笼统说「已全部更新」。
|
||||
|
||||
- [ ] 每个数都写了**两个独立来源**且数值一致(`ref/shot_*.bin` 实数 = `PAGES` 条目数;`UI_PAGE_MAP_COUNT` = 剔伪命中后的 `#page=` 计数),并在结论里贴出该数字与伪命中取舍理由
|
||||
- [ ] 字形数说明**是否剔除 notdef**并给出条目数→字形数的换算(条目数 − 1 = 字形数,2026-10-29 现值 320 − 1 = 319);字数说明**是否含 ASCII**,且该口径句与实测一致
|
||||
- [ ] 分类表逐条列出:改了哪些当前态、哪些历史行保留、哪些误报不动(附理由)、哪些只加「当时」、哪些属**口径错**并已另起一笔
|
||||
- [ ] 替换脚本打印了每处 `old -> new xN` 且每处 `assert` 通过(无半落地;报错时已 `git diff --stat` 确认零写入)
|
||||
- [ ] 命中面覆盖 `.pre-commit-config.yaml` 钩子 `name:`、`AGENTS.md`(钩子数等入口级计数)、`docs/**`、`scripts/**`、`.dsh/skills/*/SKILL.md`,逐条在改动清单里出现
|
||||
- [ ] 被改文件已全文通读,同文档各小节与配套 README/清单的顺序、计数、完成状态一致;口径闭合(如 `未绑 = 待做 + 不做`)
|
||||
- [ ] 变更记录:**保留的 5 篇真台账**(清单 → `docs/文档规范.md` §5.1)历史行原文未动;其余文档本轮**零新增流水行**(当前态改完即止);钩子一增一减这类过程细节写进提交正文,不写进文档
|
||||
- [ ] **提交后**又按全部旧形态复扫一次,当前态残留 = **0**,每条剩余命中都能归类(历史行 / 误报 / 已加「当时」);发现的漏网当前态已单独补一笔
|
||||
- [ ] `check_doc_links.py --all --sections-strict` 打印「文档路径检查通过(N 个文档)」;`ci_local.py` / `pre-commit` 全绿(RC=0、`failed=0`);BOM 与原文件一致、无 `EF BF BD`
|
||||
- [ ] 分笔提交完成,回报 commit 号 + 每笔改了哪些文件 + 没动的那几类及理由
|
||||
|
||||
**处置**:任一条未打勾就补齐证据或修正后再回报;不要带着未闭环项声称「已全部更新」。
|
||||
|
||||
**证据边界**:本篇是**收口判据**,真值来源与伪命中换算以主文件「各计数的权威口径速查」表为准;表中数字是 2026-10-29 / 2026-11-16 实测快照,新一轮动手要先按 steps 篇重测,不可照抄。
|
||||
@@ -21,6 +21,16 @@ whenToUse: 需要向 STM32 目标烧录 .hex/.bin、只复位重启目标、校
|
||||
镜像缺省取项目档案 `hex`;ST-LINK_CLI 解析:`--cli` > 档案 `stlink_cli` >
|
||||
`$DSH_STLINK_CLI` > `$DTU_STLINK_CLI` > PATH(**显式设了但无效 = 立即报错,不回退**)。
|
||||
退出码:`0`=OK / `1`=探针或目标错误 / `2`=CLI 未找到 / `3`=用法。
|
||||
|
||||
**成功输出样例**(本轮实跑 `stlink_flash.py list`;flash/cmp 判据串来自脚本内置判据与 `docs/子系统设计/故障录波设计说明.md` 实测记录):看到探针 `SN:` 行即 `list` 通;烧录看 `Programming Complete`、回读看 `No difference found` 即为真写入,不用再往下看。
|
||||
|
||||
```text
|
||||
--- Available ST-LINK Probes List ---
|
||||
ST-LINK Probe 0:
|
||||
SN: 0B250D12A218303030303032
|
||||
FW: V2J37S7
|
||||
```
|
||||
|
||||
成功判据内置:flash = rc0 + `Programming Complete`;cmp = 行首 `No difference found`
|
||||
(输出原样透传,serial-boot-test 的 `readback_ok` 默认值直接可用)。
|
||||
|
||||
|
||||
@@ -8,175 +8,99 @@ whenToUse: >-
|
||||
# task-worktree — 多任务并行开发空间(`@task` 仅为文档别名;DSH 显式调用 `/task-worktree`;可执行形态见「固定命令」)
|
||||
|
||||
- **执行体** = `.dsh/skills/task-worktree/scripts/task_worktree.py`(纯标准库;拷整个 skill 目录即可换项目用)。
|
||||
- **深规程全文在 reference/ 下:做 C2 / D / E / F / G 任何一条之前先把对应那篇读完**——本文只留判得出来「要不要读」的判据。
|
||||
- 为什么这么拆:本文件受 dsh-mnemon 写侧上限 **65536 字节**(`skill-size` 钩子 49152 告警;实测 72,601 字节的技能照常可读可提交,只是自进化每次「生成草案」被拒、永久卡在「生成中」)→ **新增深规程进 reference/,本文只加判据**。瘦身前 frontmatter 原文 → [frontmatter-history.md](reference/frontmatter-history.md)。
|
||||
- **深规程全文在 reference/ 下**:命中「失败了 → 去哪读」表的键才去读对应那篇,正常路径不必展开。
|
||||
- 本文件受 dsh-mnemon 写侧上限 65536 字节(`skill-size` 钩子 49152 告警)→ 新增深规程进 reference/,本文只加判据与索引。瘦身前 frontmatter 原文 → [frontmatter-history.md](reference/frontmatter-history.md)。
|
||||
|
||||
## 症状 → 去哪一节
|
||||
|
||||
| 现场 / 目标 | 去 |
|
||||
|---|---|
|
||||
| 开新树 / 看全景 / 追平主干 / 放弃任务 | 固定命令、典型流程 |
|
||||
| `new` 报「已有 8 个活跃任务(上限 8)」 | **A** |
|
||||
| `lock release` 报「任务 X 不存在(缺台账)」,锁照旧挂着 | **B** |
|
||||
| `done` 做了什么、红了怎么补绿、能不能反悔、怎么算「真完成」 | **C** |
|
||||
| `done` 报「主工作树不干净」,而那份脏是别的会话/插件留的 | **C2** → [merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) |
|
||||
| 门禁指标异常增长要逐文件归因(主树全程只读) | **D** → [clean-room-measure.md](reference/clean-room-measure.md) |
|
||||
| `list` 台账里没有的树要回收 / detached / 有在飞内容 / 悬挂台账 | **E** → [reclaim-unregistered.md](reference/reclaim-unregistered.md) |
|
||||
| 插件树缺联接、锁归属 `pw:<name>`、「有插件为何还自持生命周期」 | **F** → [dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) |
|
||||
| 树内写门禁输出 ENOENT、`--all` 假红、写提交/合并信息、字节体检 | **G** → [gates-in-tree.md](reference/gates-in-tree.md) |
|
||||
| 收工前树内自查、或合并后体积凭证/台账红了想一条命令补绿 | `precheck` / `postmerge`(固定命令表 + C 节第 5~6 步) |
|
||||
| 退出码读到 0 其实是 2、`tail` 之后误判「有冲突」 | 读输出 |
|
||||
| 谁不许跑 `done`/`abort`、清场前必做什么、任务期哪些文件不许改 | 铁律 1–9 |
|
||||
| 收工前最后一遍自查(各节该留什么证据)/全部实测坑 | [verification.md](reference/verification.md) / [pitfalls.md](reference/pitfalls.md) |
|
||||
|
||||
## 固定命令
|
||||
## 默认路径:一条命令跑通
|
||||
|
||||
```bash
|
||||
PY=".venv/Scripts/python.exe"; TW=".dsh/skills/task-worktree/scripts/task_worktree.py"
|
||||
"$PY" "$TW" <子命令> [参数] # PowerShell:& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" <子命令>(cwd = 仓库根或任意子目录)
|
||||
"$PY" "$TW" <子命令> [参数] # PowerShell:& $PY ".dsh\\skills\\task-worktree\\scripts\\task_worktree.py" <子命令>(cwd = 仓库根或任意子目录)
|
||||
```
|
||||
|
||||
| 命令 | 作用 |
|
||||
|---|---|
|
||||
| `bench-gate <branch>` | 检查指定分支是否有 bench-pass 记录(存储于 `.agents/worktrees/.bench-pass-log`) |
|
||||
| `merge <branch>` | 在主树执行编排式合并:bench-gate → 预演 → 合并(`--skip-bench` 跳过台架检查) |
|
||||
| `bench-gate <branch>` | 检查指定分支是否有 bench-pass 记录(存于 `.agents/worktrees/.bench-pass-log`) |
|
||||
| `merge <branch>` | 主树编排式合并:bench-gate → 预演 → 合并(`--skip-bench` 跳过台架检查) |
|
||||
| `list` | 分支 / 落后领先 / 脏文件数 / 台架状态 + 两把锁归属。**只遍历台账** → 非登记树看不见(E 节) |
|
||||
| `status <ID>` | 未提交清单、相对基线漂移、台架记录、已建联接 |
|
||||
| `sync <ID>` | 在任务树里 `rebase` 追平主干,把冲突留在任务分支上 |
|
||||
| `lock acquire|release|status <build\|bench>` | 独占资源锁(→ 铁律 3、B 节) |
|
||||
| `plugin list|adopt|unadopt [插件树名]` | 插件桥:看清单 / 补共享联接 / 摘联接(**不删树**)→ F 节 |
|
||||
| `lock acquire\|release\|status <build\|bench>` | 独占资源锁(→ 铁律 3、B 节) |
|
||||
| `plugin list\|adopt\|unadopt [插件树名]` | 插件桥:看清单 / 补共享联接 / 摘联接(**不删树**)→ F 节 |
|
||||
| `done <ID>` | **[DEPRECATED]** 已废弃,请用 `merge`。预演 → 合入主干 → 审计 → 重生成 → 门禁 → 清场 |
|
||||
| `precheck` | 树内自查(**只读**):BOM 漂移 / CR / U+FFFD + docs 逐档门禁 + `--msgfile --ban` 消息检查;顺手补 `ci-artifacts/`(G 节机械项) |
|
||||
| `postmerge` | 主树合并后补绿:体积凭证**自动诊断**(新鲜跳过;红→先短链 `--update`,只读复检真漂了才升全链)+ `check_doc_links --all` + 列待提交文件,**不代提交** |
|
||||
| `precheck` | 树内自查(**只读**):BOM 漂移 / CR / U+FFFD + docs 逐档门禁 + `--msgfile --ban` 消息检查;顺手补 `ci-artifacts/`(G 节) |
|
||||
| `postmerge` | 主树合并后补绿:体积凭证**自动诊断**(新鲜跳过;红→短链 `--update`,只读复检真漂了才全链)+ `check_doc_links --all` + 列待提交文件,**不代提交** |
|
||||
|
||||
- **退出码** `0` 成功 / `1` 操作失败 / `2` 前置或环境错误 / `3` 用法——**只有不接管道才读得到**(→ 读输出)。
|
||||
- `bench-gate`:无参数选项。检查 `.agents/worktrees/.bench-pass-log` 中是否有该分支的记录。
|
||||
- `merge`:`--skip-bench`(跳过 bench-gate 检查)。合并后不自动删除任务分支和目录。
|
||||
- `done` **[DEPRECATED]**:`--dry-run` · `--skip-build` · `--skip-gates` · `--force`。⚠ 已废弃,请用 `merge`。
|
||||
- `lock`:`--task`(acquire 必填)· `--wait <秒>` · `--ttl <小时>`(默认 `build`=1h / `bench`=6h,超期视为陈旧、下次 acquire 自动接管)· `--note` · `--bench-pass` · `--force`。⚠ `--note` 只在 **acquire** 写进 payload,**release 时被忽略** → 验收证据写主干提交说明或文档。`--bench-pass` 现在同时写入 `.agents/worktrees/.bench-pass-log`。
|
||||
- 环境变量:`DTU_WT_ROOT`(默认仓库同级 `_wt/`)· `DTU_TASK_BASE`(默认基线)· `DTU_INTEGRATION_WORKTREE`(集成点,用于隔离演练)。
|
||||
|
||||
## 典型流程
|
||||
**典型流程**(新模型:DSH 插件 `create_worktree` 建树,再用 bench-gate + merge 收口):
|
||||
|
||||
```bash
|
||||
# 新模型:使用 DSH 插件 create_worktree 建树,然后用 bench-gate + merge 收口
|
||||
# (create_worktree 由 DSH 插件提供,不在本脚本内)
|
||||
|
||||
# 台架验证后记录 bench-pass(lock release --bench-pass 自动写入 .bench-pass-log)
|
||||
"$PY" "$TW" lock acquire bench --task pw:my-task
|
||||
"$PY" "$TW" lock release bench --task pw:my-task --bench-pass
|
||||
|
||||
# 合并前检查台架验收
|
||||
"$PY" "$TW" lock release bench --task pw:my-task --bench-pass # 自动写 .bench-pass-log
|
||||
"$PY" "$TW" bench-gate task/my-task # 有记录返回 0,无记录返回 1
|
||||
|
||||
# 在主树执行合并(自动检查 bench-gate,--skip-bench 可跳过)
|
||||
"$PY" "$TW" merge task/my-task # 必须在主工作树执行
|
||||
"$PY" "$TW" merge task/my-task # 必须在主工作树执行(自动检查 bench-gate)
|
||||
```
|
||||
|
||||
## 读输出:管道与截断(两起误判的共同根因)
|
||||
## 成功输出(默认路径跑通的样子)
|
||||
|
||||
1. **`| tail -N` 之后的退出码是 `tail` 的,恒 0** → 脚本的 1/2 全被吞(实测三条「rc=0」真码都是 2)。判据先看文本(`[ok]` / `!!` / `前置/环境错误:` / `失败:`),要真码就**不接管道**或取 `${PIPESTATUS[0]}`。
|
||||
2. **`done` 的输出别 `tail -2`**:管道下 python stdout 块缓冲、git 子进程 stderr 不缓冲,两股流错位 → 只剩尾部那句「--dry-run:到此为止…」加带 `conflict` 字样的 stderr 片段,据此误判「有冲突」。dry-run 全文 5~8 行,**读全量**。
|
||||
|
||||
## 分步操作(节号 A–G/C2、各节步骤号与铁律编号被 reference/ 与 docs 引用,**不许重排**)
|
||||
|
||||
### A. `new` 撞并发上限 → 腾位
|
||||
|
||||
1. 认原文 `前置/环境错误:已有 8 个活跃任务(上限 8);先 done/abort,或加 --force`(exit 2)。「活跃」= `_wt/.state/<ID>.json` 在且台账 `path` 目录还在 → **手工删目录不占名额、但留悬挂台账**(E 第 6 步)。
|
||||
2. `$TW list` 定谁让位:**已完成的先 `done`**(合并回收一步不省)。
|
||||
3. 无人认领、零提交、未 claim 的空闲树 → `abort <ID>`;有未提交或有提交时脚本会拒,确认可弃才 `--force`。
|
||||
4. 真要第 9 棵才 `--force`:并行度上去,**冲突面与台架排队一起上去**(每棵磁盘代价见铁律 6)。
|
||||
5. **别用手工 `git worktree remove` 给登记任务腾位**:台账不删(同 ID 报「任务已存在」)、又绕过「先摘联接」(铁律 5),有让 git 递归进联接删掉主树 `.venv` 的风险。要回收的是**非登记树**(`list` 里没有它)→ **E 节**。
|
||||
6. 复验:`list` 条目数 == `ls _wt` 目录数,再 `new`。
|
||||
|
||||
### B. 非登记持有者的锁放不掉
|
||||
|
||||
症状:`lock release bench --task acceptwin --bench-pass`(带 `--force` 同)报 `前置/环境错误:任务 acceptwin 不存在(缺台账 _wt/.state/acceptwin.json)`,**锁照旧挂着**。根因:`release` 带 `--bench-pass` 就先 `load_state(task)`,而 `acquire` 侧不查台账 → 「释放」被「记账」挡死;锁没放,`done` 的 `release_stale_locks()` 对未到 TTL 的活锁判失败 → **一个没登记的名字挡住所有任务收口**。
|
||||
|
||||
**2026-10-29 已修**:无台账降级为 `[warn] …跳过 PASS 记录,仅释放锁`,**不再需要手写占位台账**。
|
||||
1. `$TW lock status` 认现场(持有者 / pid / 已持有 / TTL)——别对同一句报错反复重试。
|
||||
2. `$TW lock release <build|bench> --task <NAME> [--bench-pass]` 直接放;PASS 记不上会 warn,锁照放。
|
||||
3. **PASS 后面还要用**(`done` 只认台账 `bench_pass`)→ 从一开始就用已 `new` 的 ID 占锁,或把结论写进主干提交/文档。插件树 `pw:<name>` 天然无台账 → F 节。
|
||||
4. 最后手段:锁 = `_wt/.state/locks/<name>.lock` 的单行 JSON(`name/task/pid/host/epoch/at/note/ttl`),`release` 就是 unlink 它——手工删 = 不记 PASS 的强制释放,前面各步都不可用才做。**早期为绕坑手写的占位台账现在有害**(既占上限名额又被 `list` 当任务)→ E 第 6 步备份后删。
|
||||
|
||||
### C. `done <ID>`:它是合并点,不是查看器
|
||||
|
||||
1. **合并前确认属主提交完**:`$TW status <ID>` 看未提交与领先数,跨会话再问属主一句。实测教训:属主还剩「2/2」没提交就 `done` → 只含 1/2 的分支进了主干,只能另开一棵树补后半(自己的时序错,不是分支问题)。
|
||||
2. 先 `--dry-run` 且**读全量**。判据两行:`[ok] 前置检查通过(领先 <base> 共 N 个提交)` + `[ok] 无冲突,预演结果树 <sha>`;**N 必须等于属主应交的提交数**,对不上回第 1 步。
|
||||
3. 正式 `$TW done <ID>`——**必须在主工作树**(铁律 1)。
|
||||
4. 见 `!! 门禁未全绿` 时,`done` 现在会**自动调 `postmerge` 补绿**(体积凭证 + RAM 台账 + 文档全库)。补绿成功且有回填文件时列出待提交清单;补绿失败才保留工作树等你手动排查。紧跟的 `主干已含合并提交 <sha>` 说明**合并已落主干**。
|
||||
- ✅ 自动补绿成功后按提示提交回填文件,再重跑 `done` 完成清场。
|
||||
- ❌ **绝不用 `reset --hard <sha>`**——那是丢弃已入库的合并提交,且 `reset --hard` 是项目级 Never(连未提交工作一起丢)。
|
||||
5. **`done` 现在自动完成整条补绿链**:regen(任务表 + 内存快照 + RAM 台账)→ build → ci → postmerge(凭证诊断 + 文档全库)。门禁通过后若 postmerge 产生回填文件,会列出待提交清单等你确认后再清场。
|
||||
手工补绿链仍保留为权威兜底(`postmerge` 内部逻辑等价于下面的步骤):
|
||||
|
||||
```bash
|
||||
"$PY" scripts/check_mem_numbers.py --write # 台账受管区 ↔ 新 .map 对齐
|
||||
"$PY" scripts/ram_baseline.py --update # 趋势基线追加一行
|
||||
"$PY" scripts/ram_baseline.py --write # RAM 快照 / 92% 预算台账
|
||||
"$PY" scripts/check_test_coverage.py --update-baseline # 覆盖率基线(新单测 / 新套件时必刷)
|
||||
"$PY" scripts/check_doc_links.py --all # 文档链接与章节引用
|
||||
git add <上面刷出来的基线/快照文件> # 显式列文件,别 -A 把别人在飞的改动一起提交
|
||||
git commit -F <UTF-8 无 BOM 的正文文件> # 提交属 Ask first(入口文件「边界」节)
|
||||
```
|
||||
[ok] 分支 task/my-task 有 bench-pass 记录
|
||||
[ok] bench-gate 通过(2026-11-18T…)
|
||||
=== 合并预演(git merge --no-ff --no-commit)===
|
||||
[ok] 合并完成(<sha>)
|
||||
```
|
||||
|
||||
**`--dry-run` 新增台账碰撞预检**:双方都改过的已知生成文件(`ram_baseline.tsv` / `size_attestation.json` / RAM 台账 md)会在预演阶段提前警告,让你知道合并后需要 postmerge 重算。
|
||||
6. **重跑 `done` 前主树必须干净**,否则 `失败:主工作树不干净(…)——合并会把未提交改动卷进来` → 第 5 步产物先提交。分支已并时重跑打印 `[i] task/<ID>-<slug> 已合入 <base>,跳过合并,直接清场`——**该路径在门禁之前就返回,不会替你复绿**:上一次门禁没跑到的尾巴(主树 `ci_local.py` + `check_doc_links.py --all`;体积/文档那半可 `postmerge` 一把跑)必须自己补。主树脏且那份脏不是你的 → **C2**。
|
||||
7. 清场后再敲一次 `done <ID>` 得 `前置/环境错误:任务 <ID> 不存在(缺台账 …json)`(exit 2)——**不是失败**:清场最后一步 unlink 了台账。**判完成以 `git log` 为准**。
|
||||
`merge` 预演阶段的 `done` 对应输出为 `[ok] 前置检查通过(领先 <base> 共 N 个提交)` + `[ok] 无冲突,预演结果树 <sha>`——`N` 必须等于属主应交提交数。
|
||||
|
||||
### C2. `done` 被「主工作树不干净」挡住,而那份脏是**别的并发会话**留的
|
||||
## 失败了 → 去哪读(索引表)
|
||||
|
||||
- **不许**对它做 stash / checkout / reset / 提交 / 删除(项目级 Never,你不知它写没写完)。`done` 要求主树干净 → 合并与回收一起被挡,**那是保护不是工具坏了**。
|
||||
- 正解六步,编号与 [reference/merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) 第 1~6 步一一对应(每步的确切命令与判据在那篇):**取证**(mtime + diff 定性有无交集,顺带 `worktree list` 看有无别人中途新建的树)→ **预演** `git merge-tree --write-tree <base> <task>`(打出结果树 sha 且 RC=0)→ **主树手工合并** `git merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt <task>` → **对账**(合并后 blob id 与 stat 同合并前存值逐项一致)→ **备份台账** `cp <ID>.json <ID>.json.state-bak` 后让 `done` 自己摘联接拆树 → **复验** `worktree list` + `lock status`。
|
||||
- **blob id 变了 = stash pop 半冲突**:立刻停止收工,把两份 blob id 与 diff 交给该文件属主,绝不 `checkout` 抹平。
|
||||
- **报告要点名**:绕开 `done` 的理由 + 补回它的证据(预演 sha 与 RC、blob 对账、主树全库 `check_doc_links.py --all`、两把锁空闲)+ 那份外部脏文件与中途冒出来的第二棵树(谁的、你没动它的证据)。合并信息也过 G 的禁词自检;「这份脏通常是谁」见陷阱清单。
|
||||
失败信息自带稳定键;命中才读对应小节(每节 = 判据 / 处置 / 证据边界 + 逐字原文):
|
||||
|
||||
### D. 门禁指标异常增长 → 净室逐文件归因(主树全程只读)
|
||||
| 键(脚本真实输出 / 阶段名) | 什么条件下读 | 去处 |
|
||||
|---|---|---|
|
||||
| `MAX_CONCURRENT` | `new` 报「已有 8 个活跃任务(上限 8)」 | [concurrency-limit.md](reference/concurrency-limit.md) → `## MAX_CONCURRENT`(A 节) |
|
||||
| `LOCK_NO_STATE` | `lock release` 报「任务 X 不存在(缺台账)」锁照挂 | [unregistered-lock-holder.md](reference/unregistered-lock-holder.md) → `## LOCK_NO_STATE`(B 节) |
|
||||
| `DONE_GATE` | `done` 报「门禁未全绿」/ 补绿链 / dry-run 判据 | [merge-point-done.md](reference/merge-point-done.md) → `## DONE_GATE`(C 节) |
|
||||
| `DIRTY_MAIN` | `done` 报「主工作树不干净」,脏是别的会话留的 | [merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) → `## DIRTY_MAIN`(C2 节) |
|
||||
| `METRIC_SUSPECT` | 门禁指标异常增长查不出哪个文件造成 | [clean-room-measure.md](reference/clean-room-measure.md) → `## METRIC_SUSPECT`(D 节) |
|
||||
| `RECLAIM_UNREGISTERED` | `list` 看不到的树 / detached / 悬挂台账要回收 | [reclaim-unregistered.md](reference/reclaim-unregistered.md) → `## RECLAIM_UNREGISTERED`(E 节) |
|
||||
| `PLUGIN_BRIDGE` | 插件树缺联接、锁 `pw:<name>`、联接分级 | [dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) → `## PLUGIN_BRIDGE`(F 节) |
|
||||
| `GATES_IN_TREE` | 树内写输出 ENOENT、`--all` 假红、消息禁词 | [gates-in-tree.md](reference/gates-in-tree.md) → `## GATES_IN_TREE`(G 节) |
|
||||
| `IRON_RULES` | 九条铁律的逐条判据、ttl/上限数值口径 | [iron-rules.md](reference/iron-rules.md) → `## IRON_RULES` |
|
||||
| `PITFALLS` | 收工前扫全部实测坑清单 | [pitfalls.md](reference/pitfalls.md) → `## PITFALLS` |
|
||||
| `VERIFICATION` | 收工前自查各节该留什么证据 | [verification.md](reference/verification.md) → `## VERIFICATION` |
|
||||
|
||||
三条判据:仓外 detached 树当净室、**一次只注入一份在飞文件**、与 HEAD 基线逐文件差分;主树前后 `git status --porcelain` 逐行一致才算「全程只读」。全文 → [reference/clean-room-measure.md](reference/clean-room-measure.md)。
|
||||
## 分步操作索引(节号 A–G/C2 与铁律编号被 reference/ 与 docs 引用,不许重排/改名)
|
||||
|
||||
### E. 回收**非登记**工作树(`list` 为空 / detached / 树里有在飞或未跟踪内容)
|
||||
正文已搬进上表对应 reference;下列同名索引行只给判据与路由:
|
||||
|
||||
三条不可跳过:① 逐文件内容**三桶归类**(与主线工作区/HEAD 比对;「很久没动」不是判据)② 动手前跑**只读 reparse 预扫**,拿到 `REPARSE: none` 才许 `git worktree remove`(铁律 5)③ 唯一未合并残留先备份再 `--force`,拆完复验 + 清悬挂台账。**绝不跑 `done`/`abort`**(铁律 9)。全文(第 1~6 步 + 两份探针脚本)→ [reference/reclaim-unregistered.md](reference/reclaim-unregistered.md)。
|
||||
- **A. `new` 撞并发上限 → 腾位**(原 `### A.`)→ `MAX_CONCURRENT`。「活跃」= 台账在且目录还在;先 `done` 已完成树 → 空闲 `abort` → 真要第 9 棵才 `--force`;别手工 `git worktree remove` 给登记任务腾位。
|
||||
- **B. 非登记持有者的锁放不掉**(原 `### B.`)→ `LOCK_NO_STATE`。2026-10-29 已修为 warn 跳过 PASS 记录、锁照放,无需手写占位台账;占位台账现在有害。
|
||||
- **C. `done <ID>`:它是合并点,不是查看器**(原 `### C.`)→ `DONE_GATE`。先确认属主提交完 → `--dry-run` 读全量 → 主树正式 `done`;门禁红会自动补绿。**绝不 `reset --hard`**。
|
||||
- **C2. `done` 被「主工作树不干净」挡住,而那份脏是别的并发会话留的**(原 `### C2.`)→ `DIRTY_MAIN`。不许 stash/checkout/reset/提交/删除别人的改动;六步手工合并 + blob 对账,详见 reference。
|
||||
- **D. 门禁指标异常增长 → 净室逐文件归因(主树全程只读)**(原 `### D.`)→ `METRIC_SUSPECT`。仓外 detached 树当净室、一次注入一份在飞文件、主树全程只读。
|
||||
- **E. 回收非登记工作树(`list` 为空 / detached / 树里有在飞或未跟踪内容)**(原 `### E.`)→ `RECLAIM_UNREGISTERED`。三桶归类 → 只读 reparse 预扫拿 `REPARSE: none` → 才许 remove;绝不跑 `done`/`abort`。
|
||||
- **F. 与现役 DSH worktree 插件(`create_worktree`)共存**(原 `### F.`)→ `PLUGIN_BRIDGE`。`simulator/SDL2` 硬需求、`.venv` 软需求;插件树占锁记 `pw:<name>`;回收先 `plugin unadopt` 再按 E 节。
|
||||
- **G. 任务树内跑门禁:落点、`--all` 假红、消息禁词**(原 `### G.`)→ `GATES_IN_TREE`。落盘前 `mkdir -p ci-artifacts`;文档门禁树内单文件跑、`--all` 留主树;提交信息 `-F` + 禁词自检。
|
||||
|
||||
### F. 与现役 DSH worktree 插件(`create_worktree`)共存
|
||||
## 常用参数 / 环境变量
|
||||
|
||||
| 联接 | 级别 | 依据 | 缺了会怎样 | 逃生门 |
|
||||
|---|---|---|---|---|
|
||||
| `simulator/SDL2` | **硬需求** | `simulator/CMakeLists.txt:12` 的 `set(SDL2_DIR …)` **非 `CACHE`**,include / `lib/x64` / `SDL2.dll` 全从它派生 | `build_sim.bat` 当场失败 | **无** |
|
||||
| `.venv` | 软需求 | `scripts/ci_local.py` 有 `DTU_PRECOMMIT_PYTHON` + 五级解释器候选 | **静默**落机器级解释器(缺 fontTools → `generated-fresh` 假红) | 环境变量 |
|
||||
- `done` **[DEPRECATED]**:`--dry-run` · `--skip-build` · `--skip-gates` · `--force`;`merge`:`--skip-bench`。
|
||||
- `lock`:`--task`(acquire 必填)· `--wait <秒>` · `--ttl <小时>`(默认 build=1h / bench=6h)· `--note`(**只在 acquire 写入 payload,release 忽略**)· `--bench-pass` · `--force`。
|
||||
- `DTU_WT_ROOT`(默认同级 `_wt/`)· `DTU_TASK_BASE` · `DTU_INTEGRATION_WORKTREE`。
|
||||
- 退出码 `0` 成功 / `1` 操作失败 / `2` 前置或环境错误 / `3` 用法——**只有不接管道才读得到**(`| tail` 后 `$?` 恒 0,见下禁令)。
|
||||
|
||||
- `plugin adopt` 两条都补只是因为便宜,不代表两条都硬。插件树占锁记 `pw:<name>`。现役插件只负责 create/restore,**保留目录与分支,不自动回收**;本 skill 不代删。确需回收先 `plugin unadopt <name>` 摘联接,再按 **E 节非登记树安全回收规程**处理。「有插件为何还自持生命周期」=先读插件包再 grep 三个概念名报命中数,插件侧零命中就是理由——取证姿势与答案边界 → [reference/dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) F-2。
|
||||
## 禁令(看着合理但致命,留在主文件)
|
||||
|
||||
### G. 任务树内跑门禁:落点、`--all` 假红、消息禁词
|
||||
|
||||
- **新树没有 `ci-artifacts/`**(被 ignore → 不检出):重定向/写文件直接 `ENOENT` 且**整段程序零执行** → 落盘前先单独一条 `mkdir -p ci-artifacts`;树内输出一律树内相对路径(`cd` 进树后 `../_wt/x.txt` 落到 `_wt/_wt/`)。一次性产物**不进仓库根**。
|
||||
- **文档门禁树内按单文件跑;全库 `--all` 留到合并后在主树跑**——树内 `simulator/SDL2` 是同一份仓库的联接,`--all` 把它一起扫成假红(实测 RC=1 而问题全在联接下、要改的文档一条没有)。非要树内跑:① 主树同命令拿基线 ② 过滤联接下的问题行 ③ 剩下的逐行比。**只做一步就是误判。**
|
||||
- **合并提交期 pre-commit 只查冲突文件**(日志首行 `[INFO] Checking merge-conflict files only.`,其余全 `(no files to check) Skipped`)→ 合并落主干后**必须另跑全量** `scripts/ci_local.py`。
|
||||
- **跨层改动拆不成「按层分笔」**:钩子看到的世界 = HEAD + 本笔 staged(未暂存被 stash;未跟踪文件不被 stash 但会拖红同一棵树上别人的提交)→ 登记文件 / 生成物 / 互锁引用的文档分到他笔,本笔必被整仓门禁拦(`doc-links`/`registration-check`/`generated-fresh`/`mem-numbers`)。判据:**一笔提交必须自洽**。
|
||||
- **跑门禁前字节体检**:`lines / bytes / BOM / CR / U+FFFD / 三连续空行 / 行尾空格 / 末行单个 LF` + Markdown 表格每行列数一致性(单元格内竖线写成反斜杠竖线,否则被当分隔符断列)。坏行**未必是本次改动**,先定归属。`doc-links`/`no-mojibake` 只覆盖编码那半。机械项已命令化:`"$TW" precheck`(BOM 漂移 / CR / U+FFFD + docs 逐档门禁,只读);列数一致性与归属判定仍人做。
|
||||
- **提交/合并信息一律 `-F` 读文件**(UTF-8 无 BOM、标题 ≤100、正文每行 ≤80,放 `ci-artifacts/`);清退类任务加**禁词自检**:`git log -1 --pretty=%B | grep -c '<关键词>'` 必须是 **0**。未推送前发现消息写错 → `--amend -F` 就地修,别追加「更正」提交(等于把禁词写回历史)。BOM/CRLF/行长/禁词一次查:`"$TW" precheck --msgfile <文件> --ban <词1> --ban <词2>…`。
|
||||
- 全文(第 1~7 条,含 stash 机制与四道整仓门禁现场)→ [reference/gates-in-tree.md](reference/gates-in-tree.md)。
|
||||
|
||||
## 铁律
|
||||
|
||||
1. **`done` 只能在主工作树执行**——主干分支检出在主树,git 不允许同一分支两处检出。
|
||||
2. **`done` 不 push**:它结束于本地合入 + 门禁全绿;推送需用户明确许可。
|
||||
3. **`build` 与 `bench` 都必须串行**(UV4 不能两个实例同时 `-b`;COM6、ST-LINK、设备 IP `192.168.1.100` 各一份)。`build` 锁由 **/keil-build 自持自释**(`keil_build.py`)→ 调用方**不要**手工 acquire/release;`bench` 锁**必须手工** acquire → 烧录 / `/serial-boot-test` → release `--bench-pass`。非登记持有者怎么放 → B 节;插件树 → F 节。
|
||||
4. **单写者文档**:`docs/任务规划/`(整个文件夹)、`AGENTS.md` 的任务表生成块(`TASK_TABLE`)、`MDK-ARM/*.uvprojx`、`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务树里改**,留到 `done` 统一处理;用户显式豁免时(在任务树写、由 done 合回)要在交付报告里点名这条例外。
|
||||
5. **清场必须先摘联接**:脚本先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再 `git worktree remove`。手工拆树前必跑 **E 第 3 步**预扫拿到 `REPARSE: none`——否则 git 可能递归进联接把主树 `.venv` 一起删掉。
|
||||
6. **活跃任务硬上限 8 = 脚本常量 `MAX_CONCURRENT`(`task_worktree.py:30`)——唯一事实源**:报错文案与 `new` 的插件树提示都插值它,AGENTS.md / 方案文档 / frontmatter / A 节的数字全是引用同步。改这个数字 → 全形态扫描走 `stale-doc-count-sweep` skill + 隔离小仓验证上限真生效;每棵磁盘代价按实测口径重述、别照抄旧数(细节 → 验证清单末条)。满了 exit 2 → A;悬挂台账 → E 第 6 步。
|
||||
7. **工作树放仓库同级 `_wt/`,绝不在仓库内部**(否则污染 `git status`、`--all-files` 与全库搜索)。唯一例外 = 插件写死的仓内 `.agents/worktrees/`(现役)与 `.dsh-worktrees/`(旧版);现役目录池自写 `.gitignore`,旧路径由根 `.gitignore` 预置,两处均已纳入三个全库扫描排除面(→ F 节)。
|
||||
8. **`done` 是合并点**:属主没提交完就别跑;合并提交进了主干就只用「主树补提交」收尾,**不用 `reset --hard`** 反悔 → C 节。
|
||||
9. **非登记 / detached 的树绝不跑 `done` / `abort`**:两者都以台账为前置(无台账 exit 2),带残留台账时 `abort --force` 会绕过内容保全把别人在飞的改动连树一起删 → E 节。
|
||||
|
||||
## 陷阱与验证(收工前各扫一遍)
|
||||
|
||||
- [reference/pitfalls.md](reference/pitfalls.md):全部实测坑逐条(含 `--dry-run` 不保护清场段、门禁跑在 `/keil-build` 之前、未跟踪文件在 `git log` 与合并里都不留痕、并集合并残留、新树从未构建 → 体积类门禁必然红、注释-only 也刷红体积凭证、「已合入」快路径在门禁前返回不替你复绿、`--force` 只覆盖四类检查、联接不是 symlink(`core.symlinks=false`)、锁不绑进程存活、文件工具先读后改按绝对路径记账、中文门禁回显乱码但 rc 可信)。收工前扫一眼。
|
||||
- [reference/verification.md](reference/verification.md):每节要留的证据(预演 sha + `MT_RC=0`、blob id 对账、两把锁空闲、禁词计数 0、`REPARSE: none`、改上限数字后的全形态扫描)。
|
||||
- **`done`/`merge` 只能在主工作树执行**;**不 push**(需用户明确许可)。
|
||||
- **`build` 与 `bench` 都串行**:`build` 锁由 `/keil-build` 自持自释,**调用方不要手工 acquire/release**;`bench` 锁必须手工 acquire → 烧录 → release `--bench-pass`。
|
||||
- **主树脏且不是你的改动**(别的会话/插件留的)→ 绝不 stash/checkout/reset/提交/删除,也绝不 `reset --hard` 反悔合并 → `DIRTY_MAIN`。
|
||||
- **非登记 / detached 树绝不跑 `done`/`abort`**(会绕过内容保全删掉别人在飞的改动)→ `RECLAIM_UNREGISTERED`。
|
||||
- **清场必须先摘联接**:手工拆树前跑 reparse 预扫拿 `REPARSE: none`,否则 git 可能递归进联接把主树 `.venv` 一起删。
|
||||
- **工作树放仓库同级 `_wt/`,绝不在仓库内部**(唯一例外 = 插件写死的 `.agents/worktrees/` 与旧 `.dsh-worktrees/`)。
|
||||
- **读输出别接管道**:`| tail -N` 后退出码恒 0;`done` 输出别 `tail -2`(python stdout 块缓冲 + git stderr 不缓冲会错位,误判「有冲突」)——读全量。
|
||||
- **单写者文档**(`docs/任务规划/`、`AGENTS.md` 任务表块、`*.uvprojx`、`.pre-commit-config.yaml`、内存快照)任务期不在任务树里改,留到 `done` 统一处理。
|
||||
- **一笔提交必须自洽**:登记文件/生成物/互锁引用的文档不能拆到不同笔,否则被整仓门禁拦。
|
||||
|
||||
## 与其它 skill 的衔接
|
||||
|
||||
- 构建 = `keil-build`· 烧录/回读 = `stlink-flash` · 串口闭环 = `serial-boot-test`(真实 hex 路径以 `.serialtest/config.json` 的 hex 键为准——实测 `MDK-ARM/Objects/STM32F407-Demo.hex` 不存在,拷错 = 烧旧镜像)
|
||||
- 新 `.c` 双端注册 = `new-source-file` · RAM/.map 台账 = `mem-budget` · UI 回归 = `ui-verify` · 计数同步 = `stale-doc-count-sweep` · 卡死的技能台账行 = `mnemon-skill-ledger-stuck-repair`
|
||||
- 现役 DSH worktree 插件(`create_worktree`,仓内 `.agents/worktrees/`,兼容旧 `.dsh-worktrees/`)与本 skill 的分工、桥接命令、锁归属、非登记树安全回收 → F 节 · 完整机制与目录分配 → `docs/环境与部署/并行任务工作树方案.md`
|
||||
构建 = `keil-build` · 烧录 = `stlink-flash` · 串口闭环 = `serial-boot-test` · 新 `.c` 双端注册 = `new-source-file` · RAM/.map 台账 = `mem-budget` · UI 回归 = `ui-verify` · 计数同步 = `stale-doc-count-sweep` · 卡死的技能台账行 = `mnemon-skill-ledger-stuck-repair`。现役 DSH worktree 插件(`.agents/worktrees/`)分工与桥接 → F 节;完整机制 → `docs/环境与部署/并行任务工作树方案.md`。
|
||||
|
||||
@@ -1,3 +1,21 @@
|
||||
## METRIC_SUSPECT
|
||||
|
||||
> 路由:主文件失败索引表 `METRIC_SUSPECT` → 本节。原节 `### D.`(主文件已留同名索引行)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
门禁指标异常增长(如 `id-check` 超限)却查不出哪个文件造成,主树同时压着多条在飞改动。
|
||||
|
||||
### 处置
|
||||
|
||||
仓外 detached 树当净室、一次只注入一份在飞文件、与 HEAD 基线逐文件差分;主树前后 `git status --porcelain` 逐行一致才算全程只读。
|
||||
|
||||
### 证据边界
|
||||
|
||||
不许 stash/checkout/reset、不许改门禁脚本;2026-10-27 实测 +16 的归因过程,换仓库须重建基线。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### D. 门禁指标异常增长 → 逐文件归因(把净室工作树当**测量仪**,主树全程只读)
|
||||
|
||||
**场景**(2026-10-27 实测):`id-check` 突然 FAIL「不可判定 1,178 > 上限 1,166」——比上一轮量到的 1,162 又涨了 **+16**,
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# 并发上限腾位(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## MAX_CONCURRENT
|
||||
|
||||
> 路由:主文件失败索引表 `MAX_CONCURRENT` → 本节。原节 `### A.`(L83–91)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
`new` 报「已有 8 个活跃任务(上限 8)」exit 2;活跃 = 台账在且目录还在。
|
||||
|
||||
### 处置
|
||||
|
||||
先 `done` 已完成树 → 空闲树 `abort` → 真要第 9 棵才 `--force`;别手工 `git worktree remove` 给登记任务腾位。
|
||||
|
||||
### 证据边界
|
||||
|
||||
上限 8 = 脚本常量 `MAX_CONCURRENT`(`task_worktree.py:30`);改数字须走 `stale-doc-count-sweep` 全形态扫描。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### A. `new` 撞并发上限 → 腾位
|
||||
|
||||
1. 认原文 `前置/环境错误:已有 8 个活跃任务(上限 8);先 done/abort,或加 --force`(exit 2)。「活跃」= `_wt/.state/<ID>.json` 在且台账 `path` 目录还在 → **手工删目录不占名额、但留悬挂台账**(E 第 6 步)。
|
||||
2. `$TW list` 定谁让位:**已完成的先 `done`**(合并回收一步不省)。
|
||||
3. 无人认领、零提交、未 claim 的空闲树 → `abort <ID>`;有未提交或有提交时脚本会拒,确认可弃才 `--force`。
|
||||
4. 真要第 9 棵才 `--force`:并行度上去,**冲突面与台架排队一起上去**(每棵磁盘代价见铁律 6)。
|
||||
5. **别用手工 `git worktree remove` 给登记任务腾位**:台账不删(同 ID 报「任务已存在」)、又绕过「先摘联接」(铁律 5),有让 git 递归进联接删掉主树 `.venv` 的风险。要回收的是**非登记树**(`list` 里没有它)→ **E 节**。
|
||||
6. 复验:`list` 条目数 == `ls _wt` 目录数,再 `new`。
|
||||
@@ -1,3 +1,21 @@
|
||||
## PLUGIN_BRIDGE
|
||||
|
||||
> 路由:主文件失败索引表 `PLUGIN_BRIDGE` → 本节。原节 `### F.`(主文件已留同名索引行)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
插件树缺联接、锁归属 `pw:<name>`、`plugin adopt` 报联接失败、或问「有插件为何还自持生命周期」。
|
||||
|
||||
### 处置
|
||||
|
||||
`simulator/SDL2` 是硬需求(缺了 build_sim.bat 当场失败),`.venv` 是软需求可用环境变量逃生;`plugin adopt <name>` 补缺失联接(不删树);确需回收先 `plugin unadopt` 再按 E 节。
|
||||
|
||||
### 证据边界
|
||||
|
||||
联接级别按 `simulator/CMakeLists.txt:12` 非 CACHE 的 `set(SDL2_DIR …)` 这一代码事实;F-2 的插件侧零命中是取证结论,换插件版本须重验。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### F. 与 DSH worktree 插件(`/worktree`、模型工具 `worktree_create`)共存
|
||||
|
||||
本仓现在有**两套**隔离空间。别混用,也别互相回收:
|
||||
|
||||
@@ -1,3 +1,21 @@
|
||||
## GATES_IN_TREE
|
||||
|
||||
> 路由:主文件失败索引表 `GATES_IN_TREE` → 本节。原节 `### G.`(主文件已留同名索引行)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
树内写门禁输出报 ENOENT、`--all` 假红(问题全在 `simulator/SDL2` 联接下)、或提交/合并信息踩禁词。
|
||||
|
||||
### 处置
|
||||
|
||||
落盘前 `mkdir -p ci-artifacts`,树内输出走树内相对路径;文档门禁树内按单文件跑、`--all` 留合并后主树;提交信息 `-F` 读文件并过禁词自检(`grep -c` 必须 0)。
|
||||
|
||||
### 证据边界
|
||||
|
||||
`-F` 与禁词自检 2026-10-29 实测;合并提交期 pre-commit 只查冲突文件、必须另跑全量 `ci_local.py`。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### G. 任务树内跑门禁与审计:输出落点(ci-artifacts)与 SDL2 联接假红
|
||||
|
||||
三条硬规矩,全是 2026-10-29 实测付过失败成本的(两起 ENOENT + 一次假红误判):
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# 铁律 1–9(长尾,自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## IRON_RULES
|
||||
|
||||
> 路由:主文件失败索引表 `IRON_RULES` → 本节。原节 `## 铁律`(L161–172)逐字搬移;致命禁令短句仍留在主文件。
|
||||
|
||||
### 判据
|
||||
|
||||
九条铁律覆盖 done 属主/不 push、build 与 bench 串行、单写者文档、摘联接、上限、工作树位置等;正常路径不必读。
|
||||
|
||||
### 处置
|
||||
|
||||
按对应条处置;违反任一条是操作错误而非工具故障。
|
||||
|
||||
### 证据边界
|
||||
|
||||
上限 8、TTL 数值均为脚本常量实测口径;换项目须重核。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 铁律
|
||||
|
||||
1. **`done` 只能在主工作树执行**——主干分支检出在主树,git 不允许同一分支两处检出。
|
||||
2. **`done` 不 push**:它结束于本地合入 + 门禁全绿;推送需用户明确许可。
|
||||
3. **`build` 与 `bench` 都必须串行**(UV4 不能两个实例同时 `-b`;COM6、ST-LINK、设备 IP `192.168.1.100` 各一份)。`build` 锁由 **/keil-build 自持自释**(`keil_build.py`)→ 调用方**不要**手工 acquire/release;`bench` 锁**必须手工** acquire → 烧录 / `/serial-boot-test` → release `--bench-pass`。非登记持有者怎么放 → B 节;插件树 → F 节。
|
||||
4. **单写者文档**:`docs/任务规划/`(整个文件夹)、`AGENTS.md` 的任务表生成块(`TASK_TABLE`)、`MDK-ARM/*.uvprojx`、`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务树里改**,留到 `done` 统一处理;用户显式豁免时(在任务树写、由 done 合回)要在交付报告里点名这条例外。
|
||||
5. **清场必须先摘联接**:脚本先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再 `git worktree remove`。手工拆树前必跑 **E 第 3 步**预扫拿到 `REPARSE: none`——否则 git 可能递归进联接把主树 `.venv` 一起删掉。
|
||||
6. **活跃任务硬上限 8 = 脚本常量 `MAX_CONCURRENT`(`task_worktree.py:30`)——唯一事实源**:报错文案与 `new` 的插件树提示都插值它,AGENTS.md / 方案文档 / frontmatter / A 节的数字全是引用同步。改这个数字 → 全形态扫描走 `stale-doc-count-sweep` skill + 隔离小仓验证上限真生效;每棵磁盘代价按实测口径重述、别照抄旧数(细节 → 验证清单末条)。满了 exit 2 → A;悬挂台账 → E 第 6 步。
|
||||
7. **工作树放仓库同级 `_wt/`,绝不在仓库内部**(否则污染 `git status`、`--all-files` 与全库搜索)。唯一例外 = 插件写死的仓内 `.agents/worktrees/`(现役)与 `.dsh-worktrees/`(旧版);现役目录池自写 `.gitignore`,旧路径由根 `.gitignore` 预置,两处均已纳入三个全库扫描排除面(→ F 节)。
|
||||
8. **`done` 是合并点**:属主没提交完就别跑;合并提交进了主干就只用「主树补提交」收尾,**不用 `reset --hard`** 反悔 → C 节。
|
||||
9. **非登记 / detached 的树绝不跑 `done` / `abort`**:两者都以台账为前置(无台账 exit 2),带残留台账时 `abort --force` 会绕过内容保全把别人在飞的改动连树一起删 → E 节。
|
||||
@@ -1,3 +1,21 @@
|
||||
## DIRTY_MAIN
|
||||
|
||||
> 路由:主文件失败索引表 `DIRTY_MAIN` → 本节。原节 `### C2.`(主文件 L127–133 已留同名索引行)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
`done` 报「主工作树不干净」,而那份脏是别的会话/插件留的(你从没碰过)。
|
||||
|
||||
### 处置
|
||||
|
||||
绝不 stash/checkout/reset/提交/删除别人的改动;按六步走:取证 → 预演 `git merge-tree --write-tree` → 主树手工 `git merge --no-ff --no-edit -F` → blob 对账 → 备份台账后让 `done` 摘联接拆树 → 复验。
|
||||
|
||||
### 证据边界
|
||||
|
||||
blob id 变了 = stash pop 半冲突,立即停手交属主;2026-10-29 同日两遍实测,换场景须重新取证。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### C2. `done` 被「主工作树不干净」挡住,而那份脏改动是**别的并发会话**留下的
|
||||
|
||||
**场景**(2026-10-29 同一套流程在同一天跑了两遍,两遍都撞上它):任务树里的文档改完、准备合回 `v2-on-ui`,
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
# done 合并点与补绿链(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## DONE_GATE
|
||||
|
||||
> 路由:主文件失败索引表 `DONE_GATE` → 本节。原节 `### C.`(L102–126)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
`done` 报「门禁未全绿」/「主工作树不干净」,或 dry-run 的 N 与属主应交提交数不符。
|
||||
|
||||
### 处置
|
||||
|
||||
先 `status` 确认属主提交完 → `--dry-run` 读全量 → 主树正式 `done`;门禁红时自动补绿,按提示提交回填文件再重跑。
|
||||
|
||||
### 证据边界
|
||||
|
||||
绝不用 `reset --hard`(项目级 Never);「已合入」快路径在门禁前返回、不替你复绿,尾巴要自己补。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### C. `done <ID>`:它是合并点,不是查看器
|
||||
|
||||
1. **合并前确认属主提交完**:`$TW status <ID>` 看未提交与领先数,跨会话再问属主一句。实测教训:属主还剩「2/2」没提交就 `done` → 只含 1/2 的分支进了主干,只能另开一棵树补后半(自己的时序错,不是分支问题)。
|
||||
2. 先 `--dry-run` 且**读全量**。判据两行:`[ok] 前置检查通过(领先 <base> 共 N 个提交)` + `[ok] 无冲突,预演结果树 <sha>`;**N 必须等于属主应交的提交数**,对不上回第 1 步。
|
||||
3. 正式 `$TW done <ID>`——**必须在主工作树**(铁律 1)。
|
||||
4. 见 `!! 门禁未全绿` 时,`done` 现在会**自动调 `postmerge` 补绿**(体积凭证 + RAM 台账 + 文档全库)。补绿成功且有回填文件时列出待提交清单;补绿失败才保留工作树等你手动排查。紧跟的 `主干已含合并提交 <sha>` 说明**合并已落主干**。
|
||||
- ✅ 自动补绿成功后按提示提交回填文件,再重跑 `done` 完成清场。
|
||||
- ❌ **绝不用 `reset --hard <sha>`**——那是丢弃已入库的合并提交,且 `reset --hard` 是项目级 Never(连未提交工作一起丢)。
|
||||
5. **`done` 现在自动完成整条补绿链**:regen(任务表 + 内存快照 + RAM 台账)→ build → ci → postmerge(凭证诊断 + 文档全库)。门禁通过后若 postmerge 产生回填文件,会列出待提交清单等你确认后再清场。
|
||||
手工补绿链仍保留为权威兜底(`postmerge` 内部逻辑等价于下面的步骤):
|
||||
|
||||
```bash
|
||||
"$PY" scripts/check_mem_numbers.py --write # 台账受管区 ↔ 新 .map 对齐
|
||||
"$PY" scripts/ram_baseline.py --update # 趋势基线追加一行
|
||||
"$PY" scripts/ram_baseline.py --write # RAM 快照 / 92% 预算台账
|
||||
"$PY" scripts/check_test_coverage.py --update-baseline # 覆盖率基线(新单测 / 新套件时必刷)
|
||||
"$PY" scripts/check_doc_links.py --all # 文档链接与章节引用
|
||||
git add <上面刷出来的基线/快照文件> # 显式列文件,别 -A 把别人在飞的改动一起提交
|
||||
git commit -F <UTF-8 无 BOM 的正文文件> # 提交属 Ask first(入口文件「边界」节)
|
||||
```
|
||||
|
||||
**`--dry-run` 新增台账碰撞预检**:双方都改过的已知生成文件(`ram_baseline.tsv` / `size_attestation.json` / RAM 台账 md)会在预演阶段提前警告,让你知道合并后需要 postmerge 重算。
|
||||
6. **重跑 `done` 前主树必须干净**,否则 `失败:主工作树不干净(…)——合并会把未提交改动卷进来` → 第 5 步产物先提交。分支已并时重跑打印 `[i] task/<ID>-<slug> 已合入 <base>,跳过合并,直接清场`——**该路径在门禁之前就返回,不会替你复绿**:上一次门禁没跑到的尾巴(主树 `ci_local.py` + `check_doc_links.py --all`;体积/文档那半可 `postmerge` 一把跑)必须自己补。主树脏且那份脏不是你的 → **C2**。
|
||||
7. 清场后再敲一次 `done <ID>` 得 `前置/环境错误:任务 <ID> 不存在(缺台账 …json)`(exit 2)——**不是失败**:清场最后一步 unlink 了台账。**判完成以 `git log` 为准**。
|
||||
@@ -1,3 +1,21 @@
|
||||
## PITFALLS
|
||||
|
||||
> 路由:主文件失败索引表 `PITFALLS` → 本节。原节 `## 陷阱(实测)` 逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
收工前扫一眼全部实测坑清单时读本节。
|
||||
|
||||
### 处置
|
||||
|
||||
按命中条目逐条处置;每条坑的成因与逃生门见逐字原文。
|
||||
|
||||
### 证据边界
|
||||
|
||||
全部为特定日期实测(节内标注);换树/换插件版本须重验。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 陷阱(实测)
|
||||
|
||||
- **`--force` 不是万能钥匙**:它只覆盖四类检查——并发上限、持有者与 `--task` 不符、陈旧锁接管、
|
||||
|
||||
@@ -1,3 +1,21 @@
|
||||
## RECLAIM_UNREGISTERED
|
||||
|
||||
> 路由:主文件失败索引表 `RECLAIM_UNREGISTERED` → 本节。原节 `### E.`(主文件已留同名索引行)逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
`git worktree list` 里有树但 `_wt/.state/<ID>.json` 台账不存在;或 HEAD detached;或树里有不属于本会话的在飞内容。
|
||||
|
||||
### 处置
|
||||
|
||||
三桶归类中内容 → 只读 reparse 预扫拿 `REPARSE: none` → 才许 `git worktree remove` → 唯一未合并残留先备份再 `--force` → 拆完复验 + 清悬挂台账。绝不跑 `done`/`abort`。
|
||||
|
||||
### 证据边界
|
||||
|
||||
reparse 预扫是 Windows 目录联接实测必需(否则 git 递归删主树 `.venv`);探针脚本与步骤 1–6 见逐字原文。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### E. 回收**非登记**工作树(`$TW list` 为空 / detached HEAD / 树里有在飞或未跟踪内容)
|
||||
|
||||
**这类树的判定特征**(命中任意一条就适用本节):`git worktree list` 里有它、但 `_wt/.state/<ID>.json` 台账不存在;
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# 非登记持有者的锁(自 SKILL.md 逐字外置,2026-11-18)
|
||||
|
||||
## LOCK_NO_STATE
|
||||
|
||||
> 路由:主文件失败索引表 `LOCK_NO_STATE` → 本节。原节 `### B.`(L92–101)逐字搬移。
|
||||
|
||||
### 判据
|
||||
|
||||
`lock release ... --bench-pass` 报「任务 X 不存在(缺台账)」但锁照旧挂着。
|
||||
|
||||
### 处置
|
||||
|
||||
2026-10-29 已修:无台账降级为 warn 跳过 PASS 记录、锁照放,无需手写占位台账。
|
||||
|
||||
### 证据边界
|
||||
|
||||
占位台账现在有害(占上限名额 + 被 `list` 当任务);最后一手段手工删锁文件仅前面都不可用时做。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
### B. 非登记持有者的锁放不掉
|
||||
|
||||
症状:`lock release bench --task acceptwin --bench-pass`(带 `--force` 同)报 `前置/环境错误:任务 acceptwin 不存在(缺台账 _wt/.state/acceptwin.json)`,**锁照旧挂着**。根因:`release` 带 `--bench-pass` 就先 `load_state(task)`,而 `acquire` 侧不查台账 → 「释放」被「记账」挡死;锁没放,`done` 的 `release_stale_locks()` 对未到 TTL 的活锁判失败 → **一个没登记的名字挡住所有任务收口**。
|
||||
|
||||
**2026-10-29 已修**:无台账降级为 `[warn] …跳过 PASS 记录,仅释放锁`,**不再需要手写占位台账**。
|
||||
1. `$TW lock status` 认现场(持有者 / pid / 已持有 / TTL)——别对同一句报错反复重试。
|
||||
2. `$TW lock release <build|bench> --task <NAME> [--bench-pass]` 直接放;PASS 记不上会 warn,锁照放。
|
||||
3. **PASS 后面还要用**(`done` 只认台账 `bench_pass`)→ 从一开始就用已 `new` 的 ID 占锁,或把结论写进主干提交/文档。插件树 `pw:<name>` 天然无台账 → F 节。
|
||||
4. 最后手段:锁 = `_wt/.state/locks/<name>.lock` 的单行 JSON(`name/task/pid/host/epoch/at/note/ttl`),`release` 就是 unlink 它——手工删 = 不记 PASS 的强制释放,前面各步都不可用才做。**早期为绕坑手写的占位台账现在有害**(既占上限名额又被 `list` 当任务)→ E 第 6 步备份后删。
|
||||
@@ -1,3 +1,21 @@
|
||||
## VERIFICATION
|
||||
|
||||
> 路由:主文件失败索引表 `VERIFICATION` → 本节。原节 `## 验证` 逐字保留于下。
|
||||
|
||||
### 判据
|
||||
|
||||
收工前自查各节该留什么证据时读本节。
|
||||
|
||||
### 处置
|
||||
|
||||
逐条对照证据清单(预演 sha、`MT_RC=0`、blob 对账、两把锁空闲、禁词计数 0、`REPARSE: none`)。
|
||||
|
||||
### 证据边界
|
||||
|
||||
证据口径与实测日期绑定,换场景须重新取证。
|
||||
|
||||
### 逐字原文(未改写)
|
||||
|
||||
## 验证
|
||||
|
||||
- `$TW list`:台账段条目数 = `ls _wt` 的目录数且 ≤ 8(`MAX_CONCURRENT`);刚回收的任务与历史占位条目都不再出现
|
||||
|
||||
@@ -25,6 +25,13 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器(须 0 警
|
||||
|
||||
退出码:0=PASS / 1=断言失败 / 2=环境错误(exe 缺失等,先按 `new-machine-setup` skill 重建对应环境再重跑)。
|
||||
|
||||
**成功输出样例**(本轮实跑 `check_menu_rows.py` / `check_content_pages.py`,`PYTHONIOENCODING=utf-8`;判据串亦见 `docs/UI设计/UI_自动化测试流程.md` 验收表):看到两条 `PASS: ...` 汇总行(8 状态全过 + 76 内容页全过)就是像素回归通了,再叠 Keil `BUILD_OK: 0 errors, 0 warnings` 即 5 门禁全绿,不用再往下看。
|
||||
|
||||
```text
|
||||
PASS: 8 状态全部断言通过(8 图,池基线 5368 B)
|
||||
PASS: 76 内容页 + 往返池水位 + rtlive 全部通过
|
||||
```
|
||||
|
||||
## 失败处置决策
|
||||
|
||||
| 现象 | 判定 | 处置 |
|
||||
|
||||
@@ -50,6 +50,7 @@
|
||||
- 改代码**只用 Edit 工具**;**绝不用 shell 重写含中文的文件**(乱码不可逆);**字符串字面量必须纯 ASCII**,中文只写注释。
|
||||
- **Edit 会剥 BOM**:带 BOM 文件编辑后须补回 → `bom-guard` 钩子自动拦截。带 BOM 名单(三处互指:本行、钩子 `files` 正则、`scripts/check_bom_drift.py` 的 `BOM_LIST`):`Drivers/BSP/UI/`(整目录)、`App/task/ui_task.c`、`App/cfg/cfg_file.c`、`Lib/lv_conf.h`
|
||||
- 行尾由 `.gitattributes` 写死 LF,**不依赖 `core.autocrlf`**;注释里别写星号形态的路径(ARMCC 9-D)→ `nested-comment` 钩子;`SKILL.md` 有 65536 字节写侧上限 → `skill-size` 钩子,深规程写进 `reference/`。规范全文 → `docs/代码规范/`。
|
||||
- **技能写法(`.dsh/skills/`)**:`SKILL.md` 主文件只放**默认可用方案**——按本项目配好默认参数、一条命令能跑通、给出成功输出样例;失败时由脚本打印**稳定索引键**(阶段名/退出码/报错前缀),主文件按该键指向 `reference/` 的同名小节。排查细节、边界、历史坑、手工兜底一律不进主文件。审核与改进 → `.dsh/roles/skill-custodian.md`。
|
||||
|
||||
## 提交门禁(pre-commit)
|
||||
|
||||
@@ -78,7 +79,7 @@
|
||||
|
||||
1. **Lead 只调度不执行**:拆解、分配、协调、判定、汇总。不直接做模块级实现——一旦自己动手,验收独立性就没了。
|
||||
2. **涉及两个以上模块,或需要构建+测试+文档联动 → Agent Teams**(`spawn_teammate` + `send_message`);单文件小改用 `subagent_role` 即可,不要为小活开团队。
|
||||
3. **角色绑定**:`spawn_teammate` 的 `prompt` **首行写 `@role:<角色id>`**(如 `@role:algo-specialist`),插件在子会话首轮请求组装前自动注入 `.dsh/roles/<角色id>.md` 的 persona 并应用工具白名单——**缺首行标记 = 无角色,勿省略**。`subagent_role` 路径同为自动注入。可用角色 → `.dsh/roles/README.md`(11 个)。
|
||||
3. **角色绑定**:`spawn_teammate` 的 `prompt` **首行写 `@role:<角色id>`**(如 `@role:algo-specialist`),插件在子会话首轮请求组装前自动注入 `.dsh/roles/<角色id>.md` 的 persona 并应用工具白名单——**缺首行标记 = 无角色,勿省略**。`subagent_role` 路径同为自动注入。可用角色 → `.dsh/roles/README.md`(12 个)。
|
||||
4. **派活必带验收口径**:任务书里写清「怎么算做对了」——可验证的结果定义 + 逐条检查清单 + 写域声明;回报必须附实测证据(命令输出、文件路径与函数名、计数),**不采信自述结论**。
|
||||
|
||||
**验收与返工**:验收人 ≠ 执行人(自证自验最容易掩盖真问题,**文档同理**);返工不许只回「收到」,须修正后附新证据重新提交。
|
||||
|
||||
@@ -33,6 +33,9 @@
|
||||
| `iec104_master.py` | **IEC 60870-5-104 主站客户端(台架复测/保护定值持久化)**:连设备 :2404(工厂默认,`--port` 可指别的)跑 STARTDT → 总召(actcon/四组背景扫描/actterm)→ 经 C_SE 两段写临时压低 OC1 定值确定性触发 YX16 变位(COT=3)→ 恢复 → YK11 两段式 → C_RD 读回;**保护定值持久化模式 `--b7-pre/--b7-post/--b7-mark/--b7-check`**(中间 ST-LINK 复位):YK12 两段投退→保护退出/联动、定值与压板态跨复位保持(含非默认 7.5 往返);纯标准库,输出纯 ASCII 可直接重定向归档为台架证据(判据 exit 0/1/2) |
|
||||
| `cal_fit.py` | **N 点最小二乘标定参数求解(全仓唯一实现,v2.2 起固件侧拟合已删除)**(**3~8 点**,推荐 5 点):`--selftest` 跑金标向量回归(原 C 侧 `r_q16=39322000 / b=12` + 4 条拒绝路径,exit 0 全过 / 1 有失败,改动算法后必跑);`--from-doc` 直接读执行卡 §3 `CALDATA` 长表(每行一个点:路 \| 序号 \| 屏上读数 \| 注入已知量)按路分组拟合,输出合并 `WRITE-ALL` 命令;单路 `--sem/--x/--y` 亦可(`--x` = `meas:` 行 mV/mA 原样、`--y` = V/A 内部 ×1000,`--r-old/--b-old` 指读数采集时的设备参数);执行卡 `docs/测试说明/专项验证/ADC多点标定执行流程.md` §3;exit 0 可写 / 2 拒绝(入参越界 `bad argument`、点数越界、点位没拉开、单调性反转、斜率非正、r/b 越带、残差 >2%、表还是旧 6 列)或未填 |
|
||||
| `cal_write.py` | **标定参数写入器**(库层复用 `iec104_master.py`):C_SE 两段写下发定值段 `0x8050~`(变比 r)/`0x8048~`(零点 b,落笔置 VALID),C_RD 读回复核;每路先 r 后 b,输出纯 ASCII 可归档;执行卡 `docs/测试说明/专项验证/ADC多点标定执行流程.md` §4;exit 0 全过 / 1 有失败 / 2 连接或协议错误 |
|
||||
| `iec104_dtu/verify_board_acceptance.py` | **真板 104 只读验收**(STARTDT→总召→逐点核对 10 个映射遥测 + 59 SP + 16 DP →命令拒绝→对时确认):固件/点表变更后连板跑;`--host/--port` 默认 `192.168.31.100:2404`,纯标准库、ASCII 输出;exit 0 全过 / 1 检查失败 / 2 连接或协议错误;用法见 `iec104_dtu/PROBE_RUNBOOK.md` |
|
||||
| `iec104_dtu/verify_simulator_lan_bind.py` | **模拟器 104 任意地址绑定与局域网可达性验证**(启动 `lvgl_sim` 后查 `0.0.0.0:port` 监听 + 本机 IPv4 STARTDT 握手):模拟器绑定/CLI 变更后跑;`--exe/--output/--duration/--lan-ip` 可覆盖,纯标准库、ASCII 输出;exit 0 通过 / 1 断言失败 / 2 环境错误;同机验证,不证明防火墙放行 |
|
||||
| `iec104_dtu/verify_simulator_duration_evidence.py` | **模拟器自然退出证据探针**(拒绝 select/execute→对时→无 COT10/11→`--iec104-duration` 自然退出打印 STOP 汇总):引用 `simulated_actions` 前跑;`--exe/--host/--port/--duration/--output` 可覆盖,纯标准库、ASCII 输出;exit 0 全过 / 1 行为失败 / 2 启动或读取错误 |
|
||||
|
||||
### 时间 / 时延
|
||||
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
# IEC104 probe triage and migration index
|
||||
|
||||
This is the tracked index for the temporary IEC104 probes that previously lived
|
||||
under ignored `ci-artifacts/`. Only reusable protocol-correctness acceptance
|
||||
probes (A) were normalized into `test/host/iec104_dtu/`. One-off design
|
||||
measurements (B) stay out of the test tree. Scripts already covered by tracked
|
||||
assets (C) were not migrated. The source paths below are historical:
|
||||
`ci-artifacts/` is gitignored and may not exist in a fresh clone.
|
||||
|
||||
## A - reusable protocol acceptance (migrated)
|
||||
|
||||
| Source | Class | Disposition | One-line verdict |
|
||||
|---|---|---|---|
|
||||
| `ci-artifacts/iec104-bench/board_probe.py` | A | Migrated to `test/host/iec104_dtu/verify_board_acceptance.py` | Real-board read-only acceptance: STARTDT, GI, 10 mapped measurements, 59 SP + 16 DP, command refusal, clock confirmation. Exit 0 = all checks pass, 1 = a check fails, 2 = connection/protocol error. |
|
||||
| `ci-artifacts/iec104-lan/verify_lan.py` | A | Migrated to `test/host/iec104_dtu/verify_simulator_lan_bind.py` | Simulator wildcard bind and local-IPv4 STARTDT check. Exit 0 = wildcard listener and handshakes pass, 1 = assertion fails, 2 = missing exe/tooling error. Same-host only. |
|
||||
| `ci-artifacts/iec104-tests/duration-evidence/duration_refusal_probe.py` | A | Migrated to `test/host/iec104_dtu/verify_simulator_duration_evidence.py` | Simulator finite-duration evidence for refused commands, clock sync, no completion frames and clean STOP. Exit 0 = all checks pass, 1 = behaviour fails, 2 = startup/read error. |
|
||||
|
||||
## B - one-off design-time measurement (not migrated)
|
||||
|
||||
| Source | Class | Disposition | One-line verdict |
|
||||
|---|---|---|---|
|
||||
| `ci-artifacts/iec104-cutover/probe_nostore_effect.py` | B | Keep as one-off evidence; not in `test/host/` | Compares `iec104_source.o` ZI with/without `IEC104_SOURCE_NO_VALUE_STORE`; answers a macro-cost question, not future protocol correctness. |
|
||||
| `ci-artifacts/iec104-cutover/ac5_probe_32.py` | B | Keep as one-off evidence; not in `test/host/` | AC5 warning-surface probe driven by the historical registration manifest; design-time compiler evidence. |
|
||||
| `ci-artifacts/iec104-cutover/gen_source_ranks.py` | B | Keep as one-off evidence; not in `test/host/` | Generates a dense rank header from a frozen profile; a code generator, not a test. |
|
||||
| `ci-artifacts/iec104-cutover/recompute_reach_budget.py` | B | Keep as one-off evidence; not in `test/host/` | Recomputes RAM budget from one-off link logs; design accounting only. |
|
||||
| `ci-artifacts/iec104-cutover/register_mdk.py` | B | Keep as one-off evidence; not in `test/host/` | One-time MDK registration script driven by a manifest; host tests must never register product files. |
|
||||
| `ci-artifacts/iec104-cutover/verify-slot-equivalence.py` | B | Keep as one-off evidence; not in `test/host/` | Proves old/new storage mappings equivalent for a specific redesign; not a reusable 104 acceptance probe. |
|
||||
| `ci-artifacts/iec104-cutover/serv-attrib/serv_surface_probe.py` | B | Keep as one-off evidence; not in `test/host/` | Reports stack frames of one frozen task build; design measurement. |
|
||||
| `ci-artifacts/iec104-build/verify_vendor.py` | B | Keep as one-off evidence; not in `test/host/` | Pins 17 controlled vendor diffs and hashes a frozen release; design drift evidence. |
|
||||
| `ci-artifacts/iec104-build/capacity_boundaries.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles vendor TcpServer.c at guessed capacity limits; capacity design, not protocol acceptance. |
|
||||
| `ci-artifacts/iec104-build/link_resource_probe.py` | B | Keep as one-off evidence; not in `test/host/` | Isolated armlink resource probe with hard-coded Keil paths and historical object inventory. |
|
||||
| `ci-artifacts/iec104-build/summarize_matrix.py` | B | Keep as one-off evidence; not in `test/host/` | Reformats `vendor-ac5-results.json` into a matrix; depends on a one-off artifact tree. |
|
||||
| `ci-artifacts/iec104-build/vendor_style_scan.py` | B | Keep as one-off evidence; not in `test/host/` | Wrapper around the coding-standard hook for a frozen vendor file list. |
|
||||
| `ci-artifacts/iec104-build/final_static_scan.py` | B | Keep as one-off evidence; not in `test/host/` | Freezes explicit vendor/simulator source lists and hashes for a past review. |
|
||||
| `ci-artifacts/iec104-build/tiny_resource_probe.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles/links a hypothetical tiny-capacity variant; not a product configuration test. |
|
||||
| `ci-artifacts/iec104-review/verify_vendor.py` | B | Keep as one-off evidence; not in `test/host/` | Asserts 84 upstream hashes, 43 static assertions and controlled diffs of a historical review tree. |
|
||||
| `ci-artifacts/iec104-review/any_bind_review.py` | B | Keep as one-off evidence; reusable part migrated | Reviews one frozen simulator SHA256 and writes review-only JSON; wildcard bind check migrated to A. |
|
||||
| `ci-artifacts/iec104-review/boundaries.py` | B | Keep as one-off evidence; not in `test/host/` | Re-checks capacity compile boundaries at a hard-coded Keil path; duplicate of `iec104-build/capacity_boundaries.py`. |
|
||||
| `ci-artifacts/iec104-review/mcu_closure_review.py` | B | Keep as one-off evidence; not in `test/host/` | Rebuilds a historic MCU closure map and checks a 3336-byte symbol; not a protocol test. |
|
||||
| `ci-artifacts/iec104-review/run_masks.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles a one-off `masks.c` with MSVC; depends on a review-tree fixture. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/cap_sweep.py` | B | Keep as one-off evidence; not in `test/host/` | Sweeps TCP capacities through ARMCC and fromelf for RAM sizing. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/dump.py` | B | Keep as one-off evidence; not in `test/host/` | Dumps section data of one historical object through fromelf. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/objs.py` | B | Keep as one-off evidence; not in `test/host/` | Parses a historical Keil map's object summary by RW+ZI. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/objsyms.py` | B | Keep as one-off evidence; not in `test/host/` | Lists data symbols of one named object from a historical Keil map. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/region.py` | B | Keep as one-off evidence; not in `test/host/` | Aggregates execution-region rows from a historical Keil map. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/region2.py` | B | Keep as one-off evidence; not in `test/host/` | Refined Keil map region/section aggregation for the same one-off review. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/secsum.py` | B | Keep as one-off evidence; not in `test/host/` | Converts fromelf section sizes into a RO/RAM table for historical objects. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/sweep2.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles a single vendor TU under alternate capacity defines and reports RO/RAM. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/sweep3.py` | B | Keep as one-off evidence; not in `test/host/` | Measures .bss of one vendor TU under a fixed set of capacity overrides. |
|
||||
| `ci-artifacts/iec104-review/ramprobe/syms.py` | B | Keep as one-off evidence; not in `test/host/` | Greps named symbols from a historical Keil map. |
|
||||
| `ci-artifacts/hash_iec104_sim_release.py` | B | Keep as one-off evidence; not in `test/host/` | Rewrites a release source hash list from a historical vcxproj; snapshot tool, not a test. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/capacity-candidates.py` | B | Keep as one-off evidence; not in `test/host/` | Enumerates hypothetical capacity pools for the skeleton design. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/compile_real_serv_exact.py` | B | Keep as one-off evidence; not in `test/host/` | Recreates the historical product compile surface for one serv TU. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/link_skeleton.py` | B | Keep as one-off evidence; not in `test/host/` | Measures skeleton closure RO/RW+ZI with isolated armlink objects. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/link_whole_image.py` | B | Keep as one-off evidence; not in `test/host/` | Measures whole-image reachability with a draft Net backend. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/link_whole_with_business.py` | B | Keep as one-off evidence; not in `test/host/` | Adds business TUs to the isolated link for a three-tier RAM comparison. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/measure_skeleton.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles/links the skeleton TU set and records ARMCC/fromelf sizes. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/pool_parts_report.py` | B | Keep as one-off evidence; not in `test/host/` | Parses pool-size constants from historical fromelf output. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/summarize_matrix.py` | B | Keep as one-off evidence; not in `test/host/` | Summarizes skeleton link maps against a fixed RAM floor. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/summarize_skeleton.py` | B | Keep as one-off evidence; not in `test/host/` | Aggregates per-TU ROM/RAM from a historical measurement JSON. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/summarize_whole_image.py` | B | Keep as one-off evidence; not in `test/host/` | Summarizes whole-image link maps against a fixed RAM floor. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/tu_closure.py` | B | Keep as one-off evidence; not in `test/host/` | Explains skeleton/business TU split from one historical .xref map. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/core-trim/candidate_a_delta.py` | B | Keep as one-off evidence; not in `test/host/` | Measures code-trim delta against a git-HEAD baseline copy. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/core-trim/link_core_trim.py` | B | Keep as one-off evidence; not in `test/host/` | Links two core-trim variants and subtracts library RAM from map totals. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/core-trim/link_reach_fixed.py` | B | Keep as one-off evidence; not in `test/host/` | Re-links with a corrected core/source reach root across four tiers. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/core-trim/measure_business_tu.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles business TUs in two tiers and extracts RAM with fromelf. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/core-trim/ram_by_object.py` | B | Keep as one-off evidence; not in `test/host/` | Lists per-object RAM from historical core-trim objects. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/core-trim/summarize_core_trim.py` | B | Keep as one-off evidence; not in `test/host/` | Parses size symbols produced by the one-off core-trim probe. |
|
||||
| `ci-artifacts/iec104-mcu-skeleton/core-trim/simcheck/gen_probes.py` | B | Keep as one-off evidence; not in `test/host/` | Generates probe C files for the one-off skeleton simulation check. |
|
||||
| `ci-artifacts/iec104-mcu-plan/files/capture_evidence.py` | B | Keep as one-off evidence; not in `test/host/` | Captures selected source ranges into a historical evidence text file. |
|
||||
| `ci-artifacts/iec104-mcu-plan/persistence/audit_parameters.py` | B | Keep as one-off evidence; not in `test/host/` | Audits a frozen writable-parameter predicate and writes CSV to stdout. |
|
||||
| `ci-artifacts/iec104-mcu-plan/resources/link_closure.py` | B | Keep as one-off evidence; not in `test/host/` | Links a conservative file-domain closure from historical objects. |
|
||||
| `ci-artifacts/iec104-mcu-plan/resources/measure_closure.py` | B | Keep as one-off evidence; not in `test/host/` | Copies upstream sources and compiles them in isolation for sizing. |
|
||||
| `ci-artifacts/iec104-mcu-plan/resources/seal_evidence.py` | B | Keep as one-off evidence; not in `test/host/` | Hashes all evidence files in one design directory into a manifest. |
|
||||
| `ci-artifacts/iec104-mcu-feasibility/files/run.py` | B | Keep as one-off evidence; not in `test/host/` | Isolated MSVC host run of file-domain feasibility fixtures. |
|
||||
| `ci-artifacts/iec104-mcu-feasibility/independent-tests/run_checks.py` | B | Keep as one-off evidence; not in `test/host/` | Runs artifact-only persistence feasibility probes and mutants. |
|
||||
| `ci-artifacts/iec104-mcu-feasibility/independent-tests/run_layout.py` | B | Keep as one-off evidence; not in `test/host/` | Checks a frozen candidate layout oracle with MSVC fixtures. |
|
||||
| `ci-artifacts/iec104-mcu-feasibility/persistence/run_model.py` | B | Keep as one-off evidence; not in `test/host/` | Runs an isolated persistence-state-machine model with injected faults. |
|
||||
| `ci-artifacts/iec104-mcu-feasibility/resources/measure_layout.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles/links a frozen layout candidate for RAM comparison. |
|
||||
|
||||
## C - already covered by tracked assets (not migrated)
|
||||
|
||||
| Source | Class | Disposition | One-line verdict |
|
||||
|---|---|---|---|
|
||||
| `ci-artifacts/iec104-review/cli_final.py` | C | Not migrated | Covered by `test/host/iec104_dtu/run_tcp_test.py` and the simulator CLI contract in `test/host/iec104_dtu/MATRIX.md`; this file additionally pinned one historical SHA256. |
|
||||
| `ci-artifacts/iec104-build/baseline-f84855a5/**/*.py` | C | Not migrated | Frozen baseline copy of already tracked repository scripts; no new probe logic. |
|
||||
|
||||
## Files added under `test/host/iec104_dtu/`
|
||||
|
||||
- `verify_board_acceptance.py`, `verify_simulator_lan_bind.py`, `verify_simulator_duration_evidence.py`: normalized A-class probes.
|
||||
- `PROBE_INDEX.md`: this classification index.
|
||||
- `PROBE_RUNBOOK.md`: how and when to run the three normalized probes.
|
||||
@@ -0,0 +1,55 @@
|
||||
# IEC104 probe runbook (tracked acceptance assets)
|
||||
|
||||
## 什么时候跑
|
||||
|
||||
| Script | When | Exit codes |
|
||||
|---|---|---|
|
||||
| `verify_board_acceptance.py` | After DTU firmware/point-table changes, against a real board | 0 all checks pass, 1 a check fails, 2 connection/protocol error |
|
||||
| `verify_simulator_lan_bind.py` | After simulator bind-address/CLI change or before a LAN bench session | 0 wildcard listener and local handshake pass, 1 assertion fails, 2 missing exe/tooling error |
|
||||
| `verify_simulator_duration_evidence.py` | Before quoting STOP-summary counters, when a clean finite-duration run is needed | 0 refusals/clock/completion and exit status pass, 1 behaviour fails, 2 startup/read error |
|
||||
|
||||
## 前置条件
|
||||
|
||||
- Real board: powered, reachable at `192.168.31.100`, firmware IEC104 listener on `2404`,
|
||||
profile table matching `App/protocol/iec60870/examples/iec104_dtu_profile.h`.
|
||||
- Simulator: `simulator/build/Debug/lvgl_sim.exe` built with IEC104 headless CLI,
|
||||
chosen port free, Windows `Get-NetTCPConnection` available for the LAN bind probe.
|
||||
- All three scripts are Python 3 standard library only. They print ASCII only and
|
||||
use exit codes as their verdict; redirect stdout/stderr to a log file for evidence.
|
||||
- `verify_board_acceptance.py` imports `wire.py` beside itself; run from anywhere with
|
||||
`python <repo>/test/host/iec104_dtu/verify_board_acceptance.py ...`.
|
||||
|
||||
## 怎么跑
|
||||
|
||||
From repository root:
|
||||
|
||||
```bash
|
||||
python -B test/host/iec104_dtu/verify_board_acceptance.py --help
|
||||
python -B test/host/iec104_dtu/verify_board_acceptance.py --host 192.168.31.100 --port 2404
|
||||
|
||||
python -B test/host/iec104_dtu/verify_simulator_lan_bind.py --help
|
||||
python -B test/host/iec104_dtu/verify_simulator_lan_bind.py --duration 12
|
||||
|
||||
python -B test/host/iec104_dtu/verify_simulator_duration_evidence.py --help
|
||||
python -B test/host/iec104_dtu/verify_simulator_duration_evidence.py \
|
||||
--exe simulator/build/Debug/lvgl_sim.exe --port 24040 --duration 10 \
|
||||
--output ci-artifacts/iec104-tests/duration-evidence
|
||||
```
|
||||
|
||||
## 判据
|
||||
|
||||
- Board: GI terminates; all mapped measurements present; `SP 59/59` and `DP 16/16`;
|
||||
command `C_SC_NA_1` is refused with COT 7 and P/N=1; `C_CS_NA_1` is confirmed.
|
||||
- LAN bind: OS listener is `0.0.0.0` owned by the simulator PID; STARTDT handshake replies
|
||||
`68040b000000`; process exits 0 and the listener disappears. This is same-host evidence
|
||||
only, not proof that another LAN device can pass through a firewall.
|
||||
- Duration evidence: two refused `C_SC_NA_1` commands produce only COT 7/P/N=1; no COT 10
|
||||
or COT 11 follows; clock read replies; simulator exits 0 and `simulator.log` contains
|
||||
its STOP summary line with `simulated_actions=`.
|
||||
|
||||
## 分类与历史来源
|
||||
|
||||
`PROBE_INDEX.md` lists every rescued script and its A/B/C disposition. One-off design
|
||||
measurements were intentionally not placed in `test/host/`; their original paths under
|
||||
`ci-artifacts/` are ignored by git and may disappear, but they are not needed to repeat
|
||||
protocol acceptance.
|
||||
@@ -0,0 +1,164 @@
|
||||
"""Board-side IEC 60870-5-104 acceptance probe (read-only, no state changes).
|
||||
|
||||
Run this when a real DTU board at 192.168.31.100:2404 must be re-accepted after
|
||||
a firmware or point-table change. It performs STARTDT, a station general
|
||||
interrogation, checks every mapped measurement and DTU signal is reported, then
|
||||
proves command refusal and clock confirmation.
|
||||
Prerequisites: the board is powered, its 104 listener is reachable, and the
|
||||
point table matches iec104_dtu_profile.h. An unreachable board, a non-104
|
||||
listener or bad frame sequence exits 2; a missing point or an unexpected
|
||||
command reply exits 1.
|
||||
"""
|
||||
import argparse
|
||||
import socket
|
||||
import struct
|
||||
import sys
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
HERE = Path(__file__).resolve().parent
|
||||
sys.path.insert(0, str(HERE))
|
||||
import wire # noqa: E402
|
||||
|
||||
HOST = "192.168.31.100"
|
||||
PORT = 2404
|
||||
|
||||
# IOA -> label, from the DTU profile table (iec104_dtu_profile.h).
|
||||
# NOTE: s_meas_map[] in iec104_serv.c is keyed by source address (0x9605 etc.),
|
||||
# NOT by IOA. The wire carries IOA, so the probe must look up 0x400C.. here.
|
||||
MEAS = {
|
||||
0x400C: "UA", 0x400D: "UB", 0x400E: "UC", 0x400F: "UN",
|
||||
0x4015: "IA", 0x4016: "IB", 0x4017: "IC", 0x4018: "IN",
|
||||
0x4007: "freq", 0x4003: "temp",
|
||||
}
|
||||
YX_SP = 0x0001 # singles start here, 59 points
|
||||
YX_DP = 0x1001 # doubles start here, 16 points
|
||||
|
||||
|
||||
def parse_args():
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
parser.add_argument("--host", default=HOST, help="board IPv4 address")
|
||||
parser.add_argument("--port", type=int, default=PORT, help="board IEC104 TCP port")
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
def main(host, port):
|
||||
problems = []
|
||||
gi_done = False
|
||||
trace = []
|
||||
t0 = time.monotonic()
|
||||
c = wire.Client(host, port, trace, timeout=8)
|
||||
print("connected to %s:%d in %.0f ms" % (host, port, (time.monotonic() - t0) * 1000))
|
||||
c.start()
|
||||
print("STARTDT confirmed (%.0f ms)" % ((time.monotonic() - t0) * 1000))
|
||||
|
||||
# General interrogation, QOI=20 (station), COT=6 ACT.
|
||||
# Type 100 的载荷是 IOA(3) + QOI(1):漏掉 IOA 会让 ASDU 只有 1 字节,
|
||||
# vendor IEC60870_Parse_ASDU_Header 判载荷不足 -> FRAME_ERROR -> 断链。
|
||||
c.request(wire.asdu(100, wire.u24(0) + bytes((20,)), cot=6))
|
||||
end = time.monotonic() + 25
|
||||
seen = {}
|
||||
while time.monotonic() < end:
|
||||
try:
|
||||
frame = c.frame(time.monotonic() + 2.0)
|
||||
except (TimeoutError, socket.timeout):
|
||||
break
|
||||
if frame[2] & 1:
|
||||
continue # S/U 帧:control 域最低位为 1;只有最低位为 0 才是 I 帧
|
||||
data = frame[6:]
|
||||
h = wire.header(data)
|
||||
if h["type"] == 100 and h["cot"] == 10:
|
||||
print("GI activation terminated")
|
||||
gi_done = True
|
||||
break
|
||||
if h["type"] not in (1, 3, 9, 13, 30, 31, 34, 35, 36, 37):
|
||||
continue
|
||||
try:
|
||||
for row in wire.objects(data):
|
||||
seen.setdefault(row["ioa"], row)
|
||||
except AssertionError as exc:
|
||||
print(" decode issue:", exc)
|
||||
problems.append("decode issue")
|
||||
if not gi_done:
|
||||
problems.append("GI not terminated")
|
||||
|
||||
print("\n=== measurements (mapped by iec104_serv.c s_meas_map) ===")
|
||||
for ioa, name in sorted(MEAS.items()):
|
||||
row = seen.get(ioa)
|
||||
if row is None:
|
||||
print(" %-5s IOA 0x%04X : ABSENT" % (name, ioa))
|
||||
problems.append("measurement absent %s" % name)
|
||||
else:
|
||||
iv = "IV" if row.get("quality", 0) & 0x80 else "valid"
|
||||
if row["type"] in (13, 36, 112, 206, 207):
|
||||
shown = "%.4f" % row["value"]
|
||||
else:
|
||||
shown = str(row["value"])
|
||||
print(" %-5s IOA 0x%04X : type=%d value=%-10s quality=0x%02X %s"
|
||||
% (name, ioa, row["type"], shown, row.get("quality", 0), iv))
|
||||
|
||||
print("\n=== DTU signals 59 SP + 16 DP ===")
|
||||
sp_present = sum(1 for i in range(YX_SP, YX_SP + 59) if i in seen)
|
||||
dp_present = sum(1 for i in range(YX_DP, YX_DP + 16) if i in seen)
|
||||
print(" SP 0x%04X..0x%04X present %d/59" % (YX_SP, YX_SP + 58, sp_present))
|
||||
print(" DP 0x%04X..0x%04X present %d/16" % (YX_DP, YX_DP + 15, dp_present))
|
||||
if sp_present != 59:
|
||||
problems.append("SP present %d/59" % sp_present)
|
||||
if dp_present != 16:
|
||||
problems.append("DP present %d/16" % dp_present)
|
||||
iv_sp = sum(1 for i in range(YX_SP, YX_SP + 59)
|
||||
if i in seen and seen[i].get("quality", 0) & 0x80)
|
||||
iv_dp = sum(1 for i in range(YX_DP, YX_DP + 16)
|
||||
if i in seen and seen[i].get("quality", 0) & 0x80)
|
||||
print(" SP carrying IV: %d, DP carrying IV: %d" % (iv_sp, iv_dp))
|
||||
|
||||
print("\n=== totals ===")
|
||||
by_type = {}
|
||||
for row in seen.values():
|
||||
by_type[row["type"]] = by_type.get(row["type"], 0) + 1
|
||||
print(" distinct IOA reported:", len(seen), " by type:", dict(sorted(by_type.items())))
|
||||
print(" frames: tx=%d rx=%d" % (sum(1 for x in trace if x["direction"] == "tx"),
|
||||
sum(1 for x in trace if x["direction"] == "rx")))
|
||||
|
||||
# Negative-path probes: commands must be refused, never confirmed.
|
||||
print("\n=== command refusal (must not be confirmed) ===")
|
||||
payload = wire.u24(0x6001) + bytes((0x01, 0x00))
|
||||
c.request(wire.asdu(45, payload, cot=6))
|
||||
try:
|
||||
data = c.response(45, cot=7, pn=True)
|
||||
print(" C_SC_NA_1 0x6001 -> COT 7 P/N=1 refusal (correct)")
|
||||
except (TimeoutError, AssertionError) as exc:
|
||||
print(" C_SC_NA_1 0x6001 -> UNEXPECTED:", exc)
|
||||
problems.append("C_SC refusal unexpected")
|
||||
|
||||
print("\n=== clock synchronisation (C_CS_NA_1) ===")
|
||||
now = time.localtime()
|
||||
cp56 = struct.pack("<HBBBBB", now.tm_sec * 1000 + now.tm_min * 0, now.tm_min,
|
||||
now.tm_hour, now.tm_mday, now.tm_mon, now.tm_year - 2000)
|
||||
# Type 103 的载荷顺序 = IOA(3) + CP56Time2a(7):IOA 在**前**。
|
||||
# 写成 CP56 在前会让 vendor 把时标头 3 字节当 IOA 解析,回 COT 47(未知 IOA)。
|
||||
c.request(wire.asdu(103, wire.u24(0) + cp56, cot=6))
|
||||
try:
|
||||
data = c.response(103, cot=7)
|
||||
print(" C_CS_NA_1 -> COT 7 confirmed:", data.hex())
|
||||
except (TimeoutError, AssertionError) as exc:
|
||||
print(" C_CS_NA_1 -> UNEXPECTED:", exc)
|
||||
problems.append("C_CS confirmation unexpected")
|
||||
|
||||
c.close()
|
||||
|
||||
print("\n=== verdict ===")
|
||||
print("FAILURES: %d" % len(problems))
|
||||
for item in problems:
|
||||
print(" " + item)
|
||||
return 1 if problems else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
parsed = parse_args()
|
||||
try:
|
||||
rc = main(parsed.host, parsed.port)
|
||||
except (OSError, socket.timeout, TimeoutError, AssertionError) as exc:
|
||||
print("PROTOCOL_ERROR %s" % type(exc).__name__)
|
||||
rc = 2
|
||||
raise SystemExit(rc)
|
||||
@@ -0,0 +1,120 @@
|
||||
"""Simulator duration-mode evidence: refused command, clock sync, clean STOP.
|
||||
|
||||
Run when IEC104 simulator STOP-summary evidence is needed, especially because
|
||||
run_tcp_test.py terminates the process before it prints simulated_actions.
|
||||
This probe uses --iec104-duration so the headless loop exits on its own.
|
||||
Prerequisites: a simulator binary supporting --iec104-headless and
|
||||
--iec104-duration is available and the chosen port is free.
|
||||
Exit 0 = refusals/completion/clock checks passed and simulator exited 0;
|
||||
1 = a behavioural check failed; 2 = simulator could not be started or read.
|
||||
"""
|
||||
import argparse
|
||||
import pathlib
|
||||
import socket
|
||||
import struct
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
|
||||
ROOT = pathlib.Path(__file__).resolve().parents[2]
|
||||
sys.path.insert(0, str(ROOT / "test" / "host" / "iec104_dtu"))
|
||||
|
||||
from wire import Client, asdu, cp56, header, u24 # noqa: E402
|
||||
|
||||
|
||||
def wait_listen(host, port, deadline_s=15.0):
|
||||
deadline = time.monotonic() + deadline_s
|
||||
while time.monotonic() < deadline:
|
||||
try:
|
||||
with socket.create_connection((host, port), 0.2):
|
||||
return
|
||||
except OSError:
|
||||
time.sleep(0.05)
|
||||
raise TimeoutError("simulator did not listen")
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
parser.add_argument("--exe", type=pathlib.Path, required=True)
|
||||
parser.add_argument("--host", default="127.0.0.1")
|
||||
parser.add_argument("--port", type=int, default=24040)
|
||||
parser.add_argument("--duration", type=int, default=10)
|
||||
parser.add_argument("--output", type=pathlib.Path,
|
||||
default=ROOT / "ci-artifacts/iec104-tests/duration-evidence")
|
||||
args = parser.parse_args()
|
||||
|
||||
args.output.mkdir(parents=True, exist_ok=True)
|
||||
log_path = args.output / "simulator.log"
|
||||
trace = []
|
||||
problems = []
|
||||
|
||||
try:
|
||||
with log_path.open("w", encoding="utf-8") as log:
|
||||
process = subprocess.Popen(
|
||||
[str(args.exe), "--iec104", "--iec104-headless",
|
||||
"--iec104-port", str(args.port), "--iec104-duration", str(args.duration)],
|
||||
cwd=str(args.output), stdout=log, stderr=subprocess.STDOUT)
|
||||
try:
|
||||
wait_listen(args.host, args.port)
|
||||
client = Client(args.host, args.port, trace)
|
||||
client.start()
|
||||
|
||||
# 1) SELECT then EXECUTE on a command point: both must be refused.
|
||||
client.request(asdu(46, u24(0x6002) + bytes((2 | 128,))))
|
||||
data = client.response(46, 7, pn=True)
|
||||
assert header(data)["cot"] == 7, data.hex()
|
||||
print("REFUSED select ioa=0x6002 cot=%d pn=%s" %
|
||||
(header(data)["cot"], header(data)["pn"]))
|
||||
|
||||
client.request(asdu(46, u24(0x6002) + bytes((2,))))
|
||||
data = client.response(46, 7, pn=True)
|
||||
assert header(data)["cot"] == 7, data.hex()
|
||||
print("REFUSED execute ioa=0x6002 cot=%d pn=%s" %
|
||||
(header(data)["cot"], header(data)["pn"]))
|
||||
|
||||
# 2) One clock sync so clock_sets is exercised (device-only, no OS clock).
|
||||
stamp = struct.pack("<HBBBBB", 30000, 22, 11, 17, 6, 35)
|
||||
client.request(asdu(103, u24(0) + stamp))
|
||||
client.response(103, 7)
|
||||
client.request(asdu(103, u24(0) + bytes(7), cot=5))
|
||||
reply = client.response(103, 5)
|
||||
print("CLOCK sync iso=%s" % cp56(reply[-7:])["iso"])
|
||||
|
||||
# 3) Confirm no ACT_TERM / no return-info followed the refusals.
|
||||
start = len(client.asdus)
|
||||
deadline = time.monotonic() + 0.5
|
||||
try:
|
||||
while time.monotonic() < deadline:
|
||||
client.frame(deadline)
|
||||
except (socket.timeout, TimeoutError):
|
||||
pass
|
||||
for item in client.asdus[start:]:
|
||||
item_header = header(item)
|
||||
assert not (item_header["type"] == 46 and item_header["cot"] == 10), item.hex()
|
||||
assert item_header["cot"] != 11, item.hex()
|
||||
print("NO_COMPLETION verified (no COT 10, no COT 11)")
|
||||
|
||||
client.close()
|
||||
print("CLIENT closed, waiting for graceful stop...", flush=True)
|
||||
rc = process.wait(timeout=args.duration + 30)
|
||||
print("SIMULATOR exit=%d" % rc)
|
||||
if rc != 0:
|
||||
problems.append("simulator exit %d" % rc)
|
||||
finally:
|
||||
if process.poll() is None:
|
||||
process.terminate()
|
||||
try:
|
||||
process.wait(timeout=10)
|
||||
except subprocess.TimeoutExpired:
|
||||
process.kill()
|
||||
print("\n===== simulator.log =====")
|
||||
print(log_path.read_text(encoding="utf-8").strip())
|
||||
except (OSError, subprocess.SubprocessError, socket.timeout, TimeoutError,
|
||||
AssertionError, ValueError) as exc:
|
||||
print("FAIL %s: %s" % (type(exc).__name__, str(exc)[:500]))
|
||||
return 2
|
||||
return 1 if problems else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,113 @@
|
||||
"""LAN reachability verification for the IEC 60870-5-104 simulator listener.
|
||||
|
||||
Run after a simulator bind-address change (or before a LAN bench session) to
|
||||
confirm the listener is bound to 0.0.0.0 and answers STARTDT on local IPv4
|
||||
addresses. It starts the local lvgl_sim binary in headless IEC104 duration mode.
|
||||
Prerequisites: simulator/build/Debug/lvgl_sim.exe exists with the IEC104 CLI
|
||||
contract, Get-NetTCPConnection is available, and local IPv4 is configured.
|
||||
A missing binary, wrong bind address, bad STARTDT reply or simulator exits
|
||||
nonzero returns 1; a PowerShell/tooling error returns 2.
|
||||
This checks the same host only: it does not prove another LAN device can pass
|
||||
through a firewall.
|
||||
"""
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import pathlib
|
||||
import re
|
||||
import socket
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
|
||||
|
||||
def parser():
|
||||
p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
p.add_argument("--exe", type=pathlib.Path,
|
||||
default=pathlib.Path(__file__).resolve().parents[2] / "simulator/build/Debug/lvgl_sim.exe",
|
||||
help="lvgl_sim executable to start")
|
||||
p.add_argument("--output", type=pathlib.Path,
|
||||
default=pathlib.Path(__file__).resolve().parents[2] / "ci-artifacts/iec104-lan",
|
||||
help="directory for report.json")
|
||||
p.add_argument("--duration", type=int, default=12,
|
||||
help="simulator lifetime in seconds")
|
||||
p.add_argument("--lan-ip", default=None,
|
||||
help="extra local IPv4 address to probe; auto-detected when present")
|
||||
return p
|
||||
|
||||
|
||||
def powershell(code):
|
||||
r = subprocess.run(["powershell.exe", "-NoProfile", "-Command", code],
|
||||
capture_output=True, text=True, timeout=15)
|
||||
assert r.returncode == 0, (r.returncode, r.stdout, r.stderr)
|
||||
return r.stdout.strip()
|
||||
|
||||
|
||||
def main():
|
||||
args = parser().parse_args()
|
||||
exe = args.exe.resolve()
|
||||
out = args.output.resolve()
|
||||
if not exe.is_file():
|
||||
print("MISSING exe: %s" % exe)
|
||||
return 2
|
||||
out.mkdir(parents=True, exist_ok=True)
|
||||
try:
|
||||
ips = json.loads(powershell(
|
||||
"ConvertTo-Json -Compress -InputObject @(Get-NetIPAddress "
|
||||
"-AddressFamily IPv4 | Select-Object -ExpandProperty IPAddress)"))
|
||||
if args.lan_ip:
|
||||
ips.append(args.lan_ip)
|
||||
process = subprocess.Popen(
|
||||
[str(exe), "--iec104", "--iec104-headless", "--iec104-port", "0",
|
||||
"--iec104-duration", str(args.duration)],
|
||||
stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
|
||||
try:
|
||||
ready = process.stdout.readline().strip()
|
||||
match = re.search(r"port=(\d+)", ready)
|
||||
assert match, ready
|
||||
port = int(match.group(1))
|
||||
listeners = json.loads(powershell(
|
||||
"ConvertTo-Json -Compress -InputObject @(Get-NetTCPConnection "
|
||||
"-State Listen -LocalPort %d | Select-Object LocalAddress,LocalPort,OwningProcess)" % port))
|
||||
assert any(x["LocalAddress"] == "0.0.0.0" and x["OwningProcess"] == process.pid
|
||||
for x in listeners), listeners
|
||||
results = []
|
||||
targets = ["127.0.0.1"] + ([args.lan_ip] if args.lan_ip else [])
|
||||
for host in targets:
|
||||
time.sleep(0.25)
|
||||
with socket.create_connection((host, port), timeout=3) as sock:
|
||||
sock.settimeout(3)
|
||||
sock.sendall(bytes.fromhex("680407000000"))
|
||||
data = b""
|
||||
while len(data) < 6:
|
||||
data += sock.recv(6 - len(data))
|
||||
assert data == bytes.fromhex("68040b000000"), data.hex()
|
||||
results.append({"target": host, "sent": "680407000000",
|
||||
"received": data.hex(), "scope": "same-host only"})
|
||||
stdout, stderr = process.communicate(timeout=args.duration + 10)
|
||||
assert process.returncode == 0, (process.returncode, stderr)
|
||||
leftovers = json.loads(powershell(
|
||||
"ConvertTo-Json -Compress -InputObject @(Get-NetTCPConnection -State Listen "
|
||||
"-LocalPort %d -ErrorAction SilentlyContinue | Where-Object OwningProcess -eq %d)" %
|
||||
(port, process.pid)))
|
||||
assert not leftovers, leftovers
|
||||
report = {"exe": str(exe), "sha256": hashlib.sha256(exe.read_bytes()).hexdigest(),
|
||||
"pid": process.pid, "ready": ready, "local_ipv4": ips,
|
||||
"listeners": listeners, "handshakes": results,
|
||||
"exit_code": process.returncode, "stdout": stdout, "stderr": stderr,
|
||||
"remote_firewall_verified": False, "listener_after_exit": False}
|
||||
(out / "report.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
|
||||
print(json.dumps(report, indent=2))
|
||||
return 0
|
||||
finally:
|
||||
if process.poll() is None:
|
||||
process.terminate()
|
||||
process.communicate(timeout=5)
|
||||
except (OSError, subprocess.SubprocessError, ValueError, AssertionError) as exc:
|
||||
print("FAIL: %s" % type(exc).__name__)
|
||||
print(str(exc)[:1000])
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Reference in New Issue
Block a user