wandering1
d3107f374f
- rename_ref.py 搬迁：git mv + 全库引用改写 33 文件 82 处 - README.md 保留 §0 编号空间 / §1 未闭环一览 / §2 推进顺序权威 / §3 维护约定 - 拆出 6 文件：W1-采集保护收尾（任务卡五字段）、排期详述、暂缓-RS485、 登记簿、测试与架构专项、基线与待确认 - 外部引用重定位 ~50 处：裸「登记簿 §X」、§5.1→基线与待确认 §2.1、 §2.4→暂缓-RS485、§6→基线与待确认 §3、脚本注释 T-x/N-x→登记簿 - 新增并行写纪律：任务分支不改本文件夹，状态列由 Lead 主工作树更新 - 验证：doc-links 141 文档全绿；mem-numbers 一致；refgraph 重生成； @build 0 错误 0 警告；新文件无 BOM / LF / 零乱码
97 lines
6.4 KiB
Markdown
97 lines
6.4 KiB
Markdown
---
|
||
name: task-worktree
|
||
description: 多任务并行开发的空间管理（git worktree 生命周期）：new 开一棵工作树 + 任务分支、目录联接共享 .venv 与模拟器 SDK、build/bench 两类独占锁、done 预演合并回主干并审计并集残留。规格见 docs/环境与部署/并行任务工作树方案.md。
|
||
whenToUse: 要同时推进多个任务、担心同分支同文档互相冲突；要为新任务开一个隔离空间；要把任务合并回主干；或遇到两个任务抢 COM6 / UV4、"改了文档被覆盖"、并集合并残留时。
|
||
---
|
||
|
||
# task-worktree — 多任务并行开发空间（短命令 `@task`）
|
||
|
||
**执行体 = 本 skill 自带脚本** `.dsh/skills/task-worktree/scripts/task_worktree.py`
|
||
（纯标准库，任意 python3；拷整个 skill 目录到别的项目即可用）。
|
||
|
||
```powershell
|
||
# cwd = 仓库根（或任意子目录）
|
||
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" <子命令> [参数]
|
||
```
|
||
|
||
退出码：`0`=成功 / `1`=操作失败 / `2`=前置或环境错误 / `3`=用法。
|
||
|
||
## 固定命令
|
||
|
||
| 命令 | 作用 |
|
||
|---|---|
|
||
| `new <ID> <slug>` | 建分支 `task/<ID>-<slug>` + 工作树 + 共享联接 + 台账；打印新空间路径 |
|
||
| `list` | 所有任务一览：分支 / 落后领先 / 脏文件数 / 台架状态 + 两个锁的归属 |
|
||
| `status <ID>` | 单任务详情（未提交清单、相对基线漂移、台架记录、已建联接） |
|
||
| `sync <ID>` | 在任务工作树里 `rebase` 追平主干，把冲突控制在任务分支上 |
|
||
| `lock acquire\|release\|status <build\|bench>` | 独占资源锁 |
|
||
| `done <ID>` | 预演 → 合入主干 → 并集残留审计 → 重生成产物 → 门禁 → 清场 |
|
||
| `abort <ID>` | 放弃任务（工作树 + 分支一起删，**永久丢弃**） |
|
||
|
||
`new` 常用开关：`--base <分支>`（默认 `v2-on-ui`）· `--needs-bench`（无台架 PASS 则 `done` 拒合）·
|
||
`--lean`（跳过 Git LFS smudge）· `--no-bootstrap`（不建联接）。
|
||
|
||
`done` 常用开关：`--dry-run`（只预演，零改动）· `--skip-build` · `--skip-gates` · `--force`。
|
||
|
||
**环境变量**（高级）：`DTU_WT_ROOT`（任务容器位置，默认仓库同级 `_wt/`）·
|
||
`DTU_TASK_BASE`（默认基线分支，默认 `v2-on-ui`）·
|
||
`DTU_INTEGRATION_WORKTREE`（集成点，默认主工作树——用于隔离演练/测试）。
|
||
|
||
## 典型流程
|
||
|
||
```powershell
|
||
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" new N21 dhara-isfree --needs-bench
|
||
# → 把新会话的工作目录切到打印出来的 _wt/N21-dhara-isfree/，在那里干活
|
||
|
||
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" lock acquire bench --task N21
|
||
# 烧录 / @test / 板级套件……
|
||
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" lock release bench --task N21 --bench-pass
|
||
|
||
# 回到主工作树执行回收
|
||
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" done N21
|
||
```
|
||
|
||
## 铁律
|
||
|
||
1. **`done` 只能在主工作树执行**——主干分支检出在主工作树，git 不允许同一分支在两处检出。
|
||
2. **`done` 不 push**。它结束于本地合入 + 门禁全绿；推送需用户明确许可（项目既有纪律）。
|
||
3. **`build` 与 `bench` 都必须持锁**：UV4 不能两个实例同时 `-b`；串口 COM6、ST-LINK、
|
||
设备 IP `192.168.1.100` 各只有一份。**构建与烧录都不可并发。**
|
||
4. **单写者文档**：`docs/任务规划/`（整个文件夹）、`AGENTS.md` 的任务表块、`MDK-ARM/*.uvprojx`、
|
||
`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务工作树里改**，留到 `done` 统一处理。
|
||
5. **清场必须先摘联接**：脚本会先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再
|
||
`git worktree remove`。**手工清场时千万别直接 `git worktree remove`**——git 可能递归进联接，
|
||
把主工作树的 `.venv` 一起删掉。
|
||
6. **并发上限 3 棵工作树**（每棵约 83 MB 检出）。
|
||
7. **工作树放仓库同级 `_wt/`，绝不在仓库内部**——否则污染 `git status`、`pre-commit --all-files` 与全库搜索。
|
||
|
||
## 陷阱（实测）
|
||
|
||
- **联接不是符号链接**：本仓库 `core.symlinks=false`，git 里的 symlink 会被检出成
|
||
「内容是目标路径的文本文件」。共享 `.venv` 只能用 Windows **目录联接**（`mklink /J`，
|
||
不需要管理员权限），且联接必须建在版本控制之外。
|
||
实测（2026-10-12）：用 ctypes 直调 `DeviceIoControl(FSCTL_SET_REPARSE_POINT)`
|
||
会被系统拒绝（Win32 4392），`mklink /J` 正常——所以脚本走后者，参数以列表交给
|
||
subprocess，含空格的路径（本项目 `DTU Code`）由 subprocess 自动加引号。
|
||
- **联接建失败不中止 `new`**：只告警并打印手工补建命令，避免留下半成品任务空间；
|
||
但该任务里跑不了 `.venv\Scripts\python.exe`，`@build` / `ci_local.py` 会找不到解释器。
|
||
- **`done` 前主工作树必须干净**：否则未提交改动会被卷进合并。
|
||
- **并集合并残留**：双方都改过的文件（尤其 `.gitignore`）会被 git 自动并成**并集**，
|
||
可能留下指向已删目录的死规则或重复条目。脚本会自动报「双方都改过」的文件清单 +
|
||
连续重复行；**权威判据是 base / 两个 tip 三方对比**（`git show <ref>:<file>` 逐项 `grep -F`），
|
||
别用 `tail -N` 目测。
|
||
- **`.workbuddy-ai/` 刻意不共享**：记忆不随任务分叉，也不给联接递归删除的机会。
|
||
任务工作树自己的记忆由 `done` / `abort` 在清场前归并回主工作树。
|
||
- **`--lean` 只省磁盘不省时间**：实测全量 smudge 7.25 s / 83 MB，跳过 smudge 7.05 s / 45 MB，
|
||
两者工作区都干净。默认走全量（参考图可用），磁盘紧张时才用 `--lean`。
|
||
- **锁不绑定进程存活**：`lock acquire` 本身是短命进程，而真正用资源的烧录/构建在别的进程里跑。
|
||
所以判「陈旧」只看**时效**（默认 6 小时，`LOCK_TTL_HOURS`）加显式 `--force`；pid 仅作排障记录。
|
||
同任务重复 acquire 是幂等的（不会把自己锁死）。
|
||
- **陈旧锁可自动接管**：超过 6 小时未释放即视为陈旧，下次 acquire 会接管并提示；活锁需 `--force`。
|
||
|
||
## 与其它 skill 的衔接
|
||
|
||
- 构建 = `keil-build` skill（`@build`）；烧录/回读 = `stlink-flash` skill；串口闭环 = `serial-boot-test` skill
|
||
- 新 `.c` 文件 = `new-source-file` skill（`uvprojx` 与 `CMakeLists.txt` 双端注册）
|
||
- 完整机制与目录分配 → `docs/环境与部署/并行任务工作树方案.md`
|