@zmice/zc 0.2.6 → 0.2.8

package/vendor/packages/toolkit/src/content/skills/branch-finish-and-cleanup/body.md

@@ -1,172 +1,172 @@
-# 分支收尾与清理
-
-## 概述
-
-任务“做完”不等于 branch 可以安全结束。只有当变更已经验证、去向已确定、残留工作区已清理，branch / worktree 才算真正收尾。
-
-这个技能只处理收尾判定与清理：
-
-- 这个 branch 现在应该 merge、开 PR、继续保留，还是直接丢弃
-- 关联 worktree 是否还需要保留
-- 失败实验、半成品和临时分支如何安全退出
-
-它不替代实现、审查或发布流程；它只负责把这些流程的结果变成一个干净、可追踪、可回滚的结束状态。
-
-## 何时使用
-
-在以下时点进入本技能：
-
-- 一个功能或修复已经完成实现，准备结束开发分支
-- 一个 worktree 中的实验已经得出结论，需要保留或放弃
-- 多 agent 并行执行结束，准备 fan-in 之后清理各自分支
-- PR 已合并、被拒绝，或决定不继续推进，需要处置残留 branch / worktree
-
-## 收尾决策树
-
-```
-任务结果明确了吗？ ─── 否 ──→ 不收尾，先补齐验证或结论
-    │
-   是
-    ▼
-变更应该进入主线吗？ ─── 否 ──→ 丢弃或归档实验分支
-    │
-   是
-    ▼
-当前团队通过 PR 合入吗？ ─── 是 ──→ 推送 + 开/更新 PR + 等待合入
-    │
-   否
-    ▼
-直接 merge 到目标分支 → 验证目标分支状态 → 删除已完成分支
-```
-
-关键点：
-
-- 先判定“是否保留”，再判定“如何合入”
-- 未经验证的 branch 不能因为“差不多完成了”就进入收尾
-- 未合入主线的实验分支，只有明确保留价值时才继续存在
-
-## 收尾前门禁
-
-收尾前必须确认：
-
-- 任务范围已经冻结，没有继续顺手改的内容
-- 当前 branch 的测试、lint、构建或本任务要求的验证已完成
-- 审查结论已明确：可合入、待修复或放弃
-- branch 的目标去向已明确：merge、PR、保留、归档或删除
-- 没有未解释的脏文件、临时脚本或生成物
-
-如果上述任一项不明确，就不要进入 cleanup 动作。
-
-## 四种结束状态
-
-### 1. 合入主线
-
-适用于：功能完成、验证通过、审查通过，且应该进入目标分支。
-
-动作：
-
-1. 确认 branch 相对目标分支的差异是预期范围
-2. 使用团队约定的方式 merge 或 rebase 后合入
-3. 在目标分支重新运行必要验证
-4. 删除已完成 branch
-5. 若 branch 绑定 worktree，清理对应 worktree
-
-### 2. 提交 PR 等待合入
-
-适用于：变更已准备好，但团队要求经由 PR 流程进入主线。
-
-动作：
-
-1. 推送 branch 并创建或更新 PR
-2. 在 PR 描述中写明范围、验证证据和风险点
-3. branch 保持最小存活时间，只为等待审查和合入而存在
-4. PR 合并后删除 branch，并清理关联 worktree
-
-### 3. 暂时保留
-
-适用于：实验有价值，但当前不合入；或后续还会基于该分支继续工作。
-
-动作：
-
-1. 记录为什么保留、保留多久、谁负责
-2. 标明当前状态是 `paused`、`blocked` 或 `needs-follow-up`
-3. 清理无关临时文件，避免下次恢复时状态不明
-4. 定期复核，过期未恢复的分支要么合入，要么删除
-
-保留不是默认值。没有明确后续计划的 branch，不应长期悬挂。
-
-### 4. 丢弃或清理失败实验
-
-适用于：方案被否定、实现失败、或成本明显高于价值。
-
-动作：
-
-1. 先保留需要沉淀的结论、数据或复盘记录
-2. 确认 branch 上没有还要转移的变更
-3. 删除分支或直接移除 worktree
-4. 清除临时文件、缓存和不再需要的脚本
-
-不要把“也许以后有用”的实验分支长期留着替代文档。
-
-## Worktree 收尾协议
-
-如果 branch 通过 worktree 运行，收尾时把 branch 和 worktree 视为一个整体：
-
-- branch 已合入或放弃后，worktree 也应同步清理
-- 仅当该 worktree 仍承担后续明确任务时才保留
-- 清理前先确认没有未提交变更或未转移的调试资料
-- 移除 worktree 后，确保主仓库或其他工作区不再引用该路径
-
-worktree 是隔离手段，不是长期存档机制。
-
-## 多分支 / 多 Agent 场景
-
-并行执行结束后，不要只做“合并成功”检查，还要逐个确认各分支的收尾状态：
-
-- 哪些分支已经合入，可以删除
-- 哪些分支因失败或冲突需要重做，应清理现场后重新开始
-- 哪些分支暂时保留，原因和负责人是什么
-- 哪些 worktree 已经没有活跃任务，应立即移除
-
-如果一个并行批次完成后还残留大量无主分支，说明收尾协议没有真正执行。
-
-使用 `zc team` 时，先运行 dry-run：
-
-```bash
-zc team shutdown <team-name> --plan
-```
-
-它只读取 fan-in 状态，不关闭 tmux、不删除 worktree。重点看每个 worker worktree：
-
-- `clean`：没有未提交变更，可以继续判断是否合入或删除
-- `dirty`：仍有未提交变更，必须先转移、提交或明确丢弃
-- `ahead`：分支领先目标引用，需要判断是否合入或开 PR
-- `merged`：已合入的分支可以进入删除流程
-- `unknown`：状态无法判断，必须人工检查后再清理
-
-只有每个 worktree 的去向明确后，才运行不带 `--plan` 的 `zc team shutdown <team-name>`。
-
-## 最小收尾清单
-
-- [ ] branch 的最终去向已明确
-- [ ] 必要验证已完成，证据可追溯
-- [ ] 需要保留的信息已转移到 PR、任务系统或文档
-- [ ] `zc team shutdown <team-name> --plan` 没有暴露未解释的 `dirty` / `unknown`
-- [ ] 不再需要的 branch 已删除
-- [ ] 不再需要的 worktree 已移除
-- [ ] 没有遗留未解释的脏文件或临时产物
-
-## 与其他技能的衔接
-
-- **git-workflow-and-versioning** — 定义提交、分支和 worktree 的日常纪律；本技能负责这些对象的结束状态
-- **parallel-agent-dispatch** — 并行批次 fan-in 后，逐个分支进入收尾判定
-- **team-orchestration** — 团队停机前，先明确每个 worker 的 branch / worktree 去向
-- **verification-before-completion** — 收尾前的验证证据必须真实存在，不能凭感觉删除或合入分支
-
-## Red Flags
-
-- 任务未验证完成就急着删分支
-- PR 已合并但 branch / worktree 长期残留
-- 失败实验既不记录结论，也不清理现场
-- 用“先留着吧”替代明确的保留期限和责任人
-- 多 agent fan-in 后只关心代码合并，不处理分支残留
+# 分支收尾与清理
+
+## 概述
+
+任务“做完”不等于 branch 可以安全结束。只有当变更已经验证、去向已确定、残留工作区已清理，branch / worktree 才算真正收尾。
+
+这个技能只处理收尾判定与清理：
+
+- 这个 branch 现在应该 merge、开 PR、继续保留，还是直接丢弃
+- 关联 worktree 是否还需要保留
+- 失败实验、半成品和临时分支如何安全退出
+
+它不替代实现、审查或发布流程；它只负责把这些流程的结果变成一个干净、可追踪、可回滚的结束状态。
+
+## 何时使用
+
+在以下时点进入本技能：
+
+- 一个功能或修复已经完成实现，准备结束开发分支
+- 一个 worktree 中的实验已经得出结论，需要保留或放弃
+- 多 agent 并行执行结束，准备 fan-in 之后清理各自分支
+- PR 已合并、被拒绝，或决定不继续推进，需要处置残留 branch / worktree
+
+## 收尾决策树
+
+```
+任务结果明确了吗？ ─── 否 ──→ 不收尾，先补齐验证或结论
+    │
+   是
+    ▼
+变更应该进入主线吗？ ─── 否 ──→ 丢弃或归档实验分支
+    │
+   是
+    ▼
+当前团队通过 PR 合入吗？ ─── 是 ──→ 推送 + 开/更新 PR + 等待合入
+    │
+   否
+    ▼
+直接 merge 到目标分支 → 验证目标分支状态 → 删除已完成分支
+```
+
+关键点：
+
+- 先判定“是否保留”，再判定“如何合入”
+- 未经验证的 branch 不能因为“差不多完成了”就进入收尾
+- 未合入主线的实验分支，只有明确保留价值时才继续存在
+
+## 收尾前门禁
+
+收尾前必须确认：
+
+- 任务范围已经冻结，没有继续顺手改的内容
+- 当前 branch 的测试、lint、构建或本任务要求的验证已完成
+- 审查结论已明确：可合入、待修复或放弃
+- branch 的目标去向已明确：merge、PR、保留、归档或删除
+- 没有未解释的脏文件、临时脚本或生成物
+
+如果上述任一项不明确，就不要进入 cleanup 动作。
+
+## 四种结束状态
+
+### 1. 合入主线
+
+适用于：功能完成、验证通过、审查通过，且应该进入目标分支。
+
+动作：
+
+1. 确认 branch 相对目标分支的差异是预期范围
+2. 使用团队约定的方式 merge 或 rebase 后合入
+3. 在目标分支重新运行必要验证
+4. 删除已完成 branch
+5. 若 branch 绑定 worktree，清理对应 worktree
+
+### 2. 提交 PR 等待合入
+
+适用于：变更已准备好，但团队要求经由 PR 流程进入主线。
+
+动作：
+
+1. 推送 branch 并创建或更新 PR
+2. 在 PR 描述中写明范围、验证证据和风险点
+3. branch 保持最小存活时间，只为等待审查和合入而存在
+4. PR 合并后删除 branch，并清理关联 worktree
+
+### 3. 暂时保留
+
+适用于：实验有价值，但当前不合入；或后续还会基于该分支继续工作。
+
+动作：
+
+1. 记录为什么保留、保留多久、谁负责
+2. 标明当前状态是 `paused`、`blocked` 或 `needs-follow-up`
+3. 清理无关临时文件，避免下次恢复时状态不明
+4. 定期复核，过期未恢复的分支要么合入，要么删除
+
+保留不是默认值。没有明确后续计划的 branch，不应长期悬挂。
+
+### 4. 丢弃或清理失败实验
+
+适用于：方案被否定、实现失败、或成本明显高于价值。
+
+动作：
+
+1. 先保留需要沉淀的结论、数据或复盘记录
+2. 确认 branch 上没有还要转移的变更
+3. 删除分支或直接移除 worktree
+4. 清除临时文件、缓存和不再需要的脚本
+
+不要把“也许以后有用”的实验分支长期留着替代文档。
+
+## Worktree 收尾协议
+
+如果 branch 通过 worktree 运行，收尾时把 branch 和 worktree 视为一个整体：
+
+- branch 已合入或放弃后，worktree 也应同步清理
+- 仅当该 worktree 仍承担后续明确任务时才保留
+- 清理前先确认没有未提交变更或未转移的调试资料
+- 移除 worktree 后，确保主仓库或其他工作区不再引用该路径
+
+worktree 是隔离手段，不是长期存档机制。
+
+## 多分支 / 多 Agent 场景
+
+并行执行结束后，不要只做“合并成功”检查，还要逐个确认各分支的收尾状态：
+
+- 哪些分支已经合入，可以删除
+- 哪些分支因失败或冲突需要重做，应清理现场后重新开始
+- 哪些分支暂时保留，原因和负责人是什么
+- 哪些 worktree 已经没有活跃任务，应立即移除
+
+如果一个并行批次完成后还残留大量无主分支，说明收尾协议没有真正执行。
+
+使用 `zc team` 时，先运行 dry-run：
+
+```bash
+zc team shutdown <team-name> --plan
+```
+
+它只读取 fan-in 状态，不关闭 tmux、不删除 worktree。重点看每个 worker worktree：
+
+- `clean`：没有未提交变更，可以继续判断是否合入或删除
+- `dirty`：仍有未提交变更，必须先转移、提交或明确丢弃
+- `ahead`：分支领先目标引用，需要判断是否合入或开 PR
+- `merged`：已合入的分支可以进入删除流程
+- `unknown`：状态无法判断，必须人工检查后再清理
+
+只有每个 worktree 的去向明确后，才运行不带 `--plan` 的 `zc team shutdown <team-name>`。
+
+## 最小收尾清单
+
+- [ ] branch 的最终去向已明确
+- [ ] 必要验证已完成，证据可追溯
+- [ ] 需要保留的信息已转移到 PR、任务系统或文档
+- [ ] `zc team shutdown <team-name> --plan` 没有暴露未解释的 `dirty` / `unknown`
+- [ ] 不再需要的 branch 已删除
+- [ ] 不再需要的 worktree 已移除
+- [ ] 没有遗留未解释的脏文件或临时产物
+
+## 与其他技能的衔接
+
+- **git-workflow-and-versioning** — 定义提交、分支和 worktree 的日常纪律；本技能负责这些对象的结束状态
+- **parallel-agent-dispatch** — 并行批次 fan-in 后，逐个分支进入收尾判定
+- **team-orchestration** — 团队停机前，先明确每个 worker 的 branch / worktree 去向
+- **verification-before-completion** — 收尾前的验证证据必须真实存在，不能凭感觉删除或合入分支
+
+## Red Flags
+
+- 任务未验证完成就急着删分支
+- PR 已合并但 branch / worktree 长期残留
+- 失败实验既不记录结论，也不清理现场
+- 用“先留着吧”替代明确的保留期限和责任人
+- 多 agent fan-in 后只关心代码合并，不处理分支残留

package/vendor/packages/toolkit/src/content/skills/browser-qa-testing/body.md

@@ -1,111 +1,111 @@
-# Browser QA Testing
-
-## 角色定位
-
-用真实浏览器验证用户是否真的能完成关键路径。单元测试和 API 测试不能证明页面可用、交互可达、网络错误可见或视觉没有严重错位；浏览器 QA 用运行中的应用和可复查证据补上这层门禁。
-
-本文只给执行骨架。项目已有 Playwright/Cypress/Puppeteer 时优先沿用；没有既有选择时默认 Playwright。
-
-## 何时使用
-
-- 前端页面、组件、导航、表单或状态流改动后。
-- 后端 API 改动会影响前端体验时。
-- 发布前需要最终用户路径证据时。
-- bug 报告来自浏览器行为、视觉错位或交互失败时。
-- 单元/API 测试通过，但仍需要确认真实页面没有空白、控制台错误或不可操作状态时。
-
-不适用：纯后端逻辑、纯文档、无需浏览器渲染的配置改动。
-
-## 快速路径
-
-1. 明确 1-3 条失败就不能放行的关键路径。
-2. 启动应用或确认目标 URL 可访问。
-3. 准备稳定测试数据，避免依赖生产数据。
-4. 驱动真实浏览器执行关键路径。
-5. 同时检查 DOM 可见结果、控制台错误、网络失败和基本响应式。
-6. 失败时保留截图、trace、控制台或网络证据。
-7. 修复后重跑原始失败路径，证明不再复发。
-
-## 工具选择
-
-| 工具 | 默认判断 |
-|---|---|
-| Playwright | 默认推荐，适合跨浏览器、trace、截图、自动等待和 CI |
-| Cypress | 项目已经使用 Cypress 时沿用 |
-| Puppeteer | 只在需要 Chrome DevTools Protocol 细节时使用 |
-| Browser plugin / in-app browser | 适合快速人工式走查和本地交互验证 |
-
-不要为了浏览器 QA 引入第二套 E2E 框架，除非现有工具无法覆盖目标。
-
-## 关键路径选择
-
-优先级：
-
-- P0：应用能打开，核心页面不是空白。
-- P1：主要业务动作能完成，并看到可验证结果。
-- P2：错误路径有明确反馈，不是静默失败。
-- P3：关键移动端/桌面布局没有阻塞性重叠。
-
-bug 修复场景必须先覆盖：
-
-- 原始失败如何复现。
-- 修复后如何证明失败不再发生。
-
-## 验收记录格式
-
-浏览器 QA 的结果必须能被复查：
-
-```text
-Browser QA transcript:
-- Target:
-- Build/server:
-- Paths tested:
-- Data setup:
-- Evidence:
-- Console/network:
-- Screenshots/traces:
-- Result:
-- Follow-up:
-```
-
-没有证据的“我点过了”不算完成。
-
-## 最小检查清单
-
-- 页面加载成功，没有白屏或阻塞性错误。
-- 关键按钮、输入框、菜单、弹窗可访问。
-- 主流程成功结果可见。
-- 失败路径有用户可理解的错误反馈。
-- 控制台没有与本次改动相关的新错误。
-- 网络请求状态和错误处理符合预期。
-- 关键视口下文本和控件不重叠。
-
-## 与自动化测试的关系
-
-- 已有稳定 E2E：优先运行并补充必要断言。
-- 没有 E2E：先做最小浏览器走查，再决定是否把路径沉淀为 Playwright 测试。
-- 一次性验证：可以只保留 transcript 和截图。
-- 高风险回归：应补自动化测试，避免下次靠人工记忆。
-
-## 常见失败处理
-
-- 白屏：先看控制台、构建输出和入口资源 404。
-- 点击无效：检查元素是否被遮挡、disabled、事件未绑定或异步状态未完成。
-- 表单失败：检查校验、提交 payload、接口响应和错误反馈。
-- 布局错位：截 desktop/mobile 两个视口，定位固定宽度、溢出和层级遮挡。
-- 间歇失败：避免 `sleep`，使用明确的可见性、URL、网络或状态等待条件。
-
-## 边界
-
-- 不把浏览器 QA 当成完整可访问性审计；需要深挖时转专项工具。
-- 不把视觉主观偏好当成阻塞问题，除非它影响可用性或验收标准。
-- 不连接生产数据做破坏性动作。
-- 不在没有目标路径的情况下机械铺满长尾场景。
-
-## 推荐输出
-
-```text
-Recommendation: <放行 / 修复后重测 / 补自动化测试> because <浏览器证据、失败影响和替代方案 trade-off>。
-```
-
-推荐必须说明证据来自哪条路径，以及未覆盖风险是什么。
+# Browser QA Testing
+
+## 角色定位
+
+用真实浏览器验证用户是否真的能完成关键路径。单元测试和 API 测试不能证明页面可用、交互可达、网络错误可见或视觉没有严重错位；浏览器 QA 用运行中的应用和可复查证据补上这层门禁。
+
+本文只给执行骨架。项目已有 Playwright/Cypress/Puppeteer 时优先沿用；没有既有选择时默认 Playwright。
+
+## 何时使用
+
+- 前端页面、组件、导航、表单或状态流改动后。
+- 后端 API 改动会影响前端体验时。
+- 发布前需要最终用户路径证据时。
+- bug 报告来自浏览器行为、视觉错位或交互失败时。
+- 单元/API 测试通过，但仍需要确认真实页面没有空白、控制台错误或不可操作状态时。
+
+不适用：纯后端逻辑、纯文档、无需浏览器渲染的配置改动。
+
+## 快速路径
+
+1. 明确 1-3 条失败就不能放行的关键路径。
+2. 启动应用或确认目标 URL 可访问。
+3. 准备稳定测试数据，避免依赖生产数据。
+4. 驱动真实浏览器执行关键路径。
+5. 同时检查 DOM 可见结果、控制台错误、网络失败和基本响应式。
+6. 失败时保留截图、trace、控制台或网络证据。
+7. 修复后重跑原始失败路径，证明不再复发。
+
+## 工具选择
+
+| 工具 | 默认判断 |
+|---|---|
+| Playwright | 默认推荐，适合跨浏览器、trace、截图、自动等待和 CI |
+| Cypress | 项目已经使用 Cypress 时沿用 |
+| Puppeteer | 只在需要 Chrome DevTools Protocol 细节时使用 |
+| Browser plugin / in-app browser | 适合快速人工式走查和本地交互验证 |
+
+不要为了浏览器 QA 引入第二套 E2E 框架，除非现有工具无法覆盖目标。
+
+## 关键路径选择
+
+优先级：
+
+- P0：应用能打开，核心页面不是空白。
+- P1：主要业务动作能完成，并看到可验证结果。
+- P2：错误路径有明确反馈，不是静默失败。
+- P3：关键移动端/桌面布局没有阻塞性重叠。
+
+bug 修复场景必须先覆盖：
+
+- 原始失败如何复现。
+- 修复后如何证明失败不再发生。
+
+## 验收记录格式
+
+浏览器 QA 的结果必须能被复查：
+
+```text
+Browser QA transcript:
+- Target:
+- Build/server:
+- Paths tested:
+- Data setup:
+- Evidence:
+- Console/network:
+- Screenshots/traces:
+- Result:
+- Follow-up:
+```
+
+没有证据的“我点过了”不算完成。
+
+## 最小检查清单
+
+- 页面加载成功，没有白屏或阻塞性错误。
+- 关键按钮、输入框、菜单、弹窗可访问。
+- 主流程成功结果可见。
+- 失败路径有用户可理解的错误反馈。
+- 控制台没有与本次改动相关的新错误。
+- 网络请求状态和错误处理符合预期。
+- 关键视口下文本和控件不重叠。
+
+## 与自动化测试的关系
+
+- 已有稳定 E2E：优先运行并补充必要断言。
+- 没有 E2E：先做最小浏览器走查，再决定是否把路径沉淀为 Playwright 测试。
+- 一次性验证：可以只保留 transcript 和截图。
+- 高风险回归：应补自动化测试，避免下次靠人工记忆。
+
+## 常见失败处理
+
+- 白屏：先看控制台、构建输出和入口资源 404。
+- 点击无效：检查元素是否被遮挡、disabled、事件未绑定或异步状态未完成。
+- 表单失败：检查校验、提交 payload、接口响应和错误反馈。
+- 布局错位：截 desktop/mobile 两个视口，定位固定宽度、溢出和层级遮挡。
+- 间歇失败：避免 `sleep`，使用明确的可见性、URL、网络或状态等待条件。
+
+## 边界
+
+- 不把浏览器 QA 当成完整可访问性审计；需要深挖时转专项工具。
+- 不把视觉主观偏好当成阻塞问题，除非它影响可用性或验收标准。
+- 不连接生产数据做破坏性动作。
+- 不在没有目标路径的情况下机械铺满长尾场景。
+
+## 推荐输出
+
+```text
+Recommendation: <放行 / 修复后重测 / 补自动化测试> because <浏览器证据、失败影响和替代方案 trade-off>。
+```
+
+推荐必须说明证据来自哪条路径，以及未覆盖风险是什么。