@zmice/zc 0.2.8 → 0.3.0

package/vendor/packages/toolkit/src/content/skills/context-engineering/body.md

@@ -1,67 +1,67 @@
-# 上下文工程
-
-这是 `command:start` 判型后进入的专项 skill：当任务核心不是“做什么”，而是“如何把正确上下文装载给接下来的阶段”，进入这里。
-
-## 何时使用
-
-- 开始新的编码会话或新子任务时
-- 输出质量下降，开始出现幻觉、忽略约定或跑偏
-- 任务切换导致上下文混杂时
-- 需要为代理准备最小但足够的输入材料时
-
-## 方法原则
-
-- 复杂任务先校准目标、边界和验证方式，再装载上下文
-- 最小充分上下文优先于“大而全”材料堆叠
-- 上下文装载要服务当前任务，不为可能发生的旁支需求提前铺料
-- 一旦任务阶段变化，就主动压缩和重建上下文，避免 drift
-- skill 按需加载优先于常驻加载；常驻文件只放稳定项目约定和路由规则
-- 用户级配置、跨项目路由、跨会话记忆或跨机器同步都属于持久化行为，必须先说明影响并取得明确授权
-
-## 输入前提
-
-- 已知道当前任务真正需要哪些信息
-- 愿意主动裁剪无关上下文
-- 接受规则文件、规格、源码、错误输出有不同优先级
-
-## 执行步骤
-
-1. 先校准：明确目标、非目标、风险点和需要的验证证据
-2. 先装载稳定规则：规则文件、长期约定、关键边界
-3. 再装载任务级上下文：规格片段、相关源码、测试、错误输出
-4. 控制上下文体积，只保留当前任务需要的信息
-5. 任务切换或阶段推进时主动压缩总结，清理旧上下文
-6. 发现上下文冲突、缺口或陈旧信息时，显式暴露而不是猜测
-7. 区分上下文载体：
-   - `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`：长期规则、项目边界、稳定路由
-   - skill 文件：阶段性工作流，按需加载
-   - references / checklists：需要深入验证时再加载
-   - 用户级配置或记忆：只在明确授权后写入
-
-## 成功标准
-
-- 开始执行前，代理已经知道目标、边界和验证方式
-- 代理看到的是当前任务需要的最小充分上下文
-- 规则、规格、源码和错误信息的层级清晰
-- 上下文切换不会把旧问题带入新任务
-- 遇到冲突时能清楚指出需要人类决策的点
-- 不会因为上下文膨胀而偏离当前任务
-- 没有为了“方便”把所有 skill、所有上游文档或所有历史记忆一次性塞入当前会话
-- 任何持久化写入都有明确授权、可解释影响和回滚路径
-
-## 相关原则
-
-- 复杂任务谨慎优先于求快
-- 少而准，比多而杂更有效
-- 目标导向决定装载顺序
-- 外科式修改也适用于上下文，只带入要改的那一小块
-- 规格和规则优先于猜测
-- 压缩上下文是持续动作，不是最后补救
-- 上游能力先变成治理记录，再决定是否成为常驻规则或平台能力
-
-## 回到主流程
-
-- 上下文已校准完成：回到后续真正要执行的阶段或专项入口
-- 需求仍模糊：回到 `spec-driven-development`
-- 任务已经明确、准备实现：回到 `incremental-implementation`
-- 会话健康恶化明显：结合 `context-budget-audit`
+# 上下文工程
+
+这是 `command:start` 判型后进入的专项 skill：当任务核心不是“做什么”，而是“如何把正确上下文装载给接下来的阶段”，进入这里。
+
+## 何时使用
+
+- 开始新的编码会话或新子任务时
+- 输出质量下降，开始出现幻觉、忽略约定或跑偏
+- 任务切换导致上下文混杂时
+- 需要为代理准备最小但足够的输入材料时
+
+## 方法原则
+
+- 复杂任务先校准目标、边界和验证方式，再装载上下文
+- 最小充分上下文优先于“大而全”材料堆叠
+- 上下文装载要服务当前任务，不为可能发生的旁支需求提前铺料
+- 一旦任务阶段变化，就主动压缩和重建上下文，避免 drift
+- skill 按需加载优先于常驻加载；常驻文件只放稳定项目约定和路由规则
+- 用户级配置、跨项目路由、跨会话记忆或跨机器同步都属于持久化行为，必须先说明影响并取得明确授权
+
+## 输入前提
+
+- 已知道当前任务真正需要哪些信息
+- 愿意主动裁剪无关上下文
+- 接受规则文件、规格、源码、错误输出有不同优先级
+
+## 执行步骤
+
+1. 先校准：明确目标、非目标、风险点和需要的验证证据
+2. 先装载稳定规则：规则文件、长期约定、关键边界
+3. 再装载任务级上下文：规格片段、相关源码、测试、错误输出
+4. 控制上下文体积，只保留当前任务需要的信息
+5. 任务切换或阶段推进时主动压缩总结，清理旧上下文
+6. 发现上下文冲突、缺口或陈旧信息时，显式暴露而不是猜测
+7. 区分上下文载体：
+   - `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`：长期规则、项目边界、稳定路由
+   - skill 文件：阶段性工作流，按需加载
+   - references / checklists：需要深入验证时再加载
+   - 用户级配置或记忆：只在明确授权后写入
+
+## 成功标准
+
+- 开始执行前，代理已经知道目标、边界和验证方式
+- 代理看到的是当前任务需要的最小充分上下文
+- 规则、规格、源码和错误信息的层级清晰
+- 上下文切换不会把旧问题带入新任务
+- 遇到冲突时能清楚指出需要人类决策的点
+- 不会因为上下文膨胀而偏离当前任务
+- 没有为了“方便”把所有 skill、所有上游文档或所有历史记忆一次性塞入当前会话
+- 任何持久化写入都有明确授权、可解释影响和回滚路径
+
+## 相关原则
+
+- 复杂任务谨慎优先于求快
+- 少而准，比多而杂更有效
+- 目标导向决定装载顺序
+- 外科式修改也适用于上下文，只带入要改的那一小块
+- 规格和规则优先于猜测
+- 压缩上下文是持续动作，不是最后补救
+- 上游能力先变成治理记录，再决定是否成为常驻规则或平台能力
+
+## 回到主流程
+
+- 上下文已校准完成：回到后续真正要执行的阶段或专项入口
+- 需求仍模糊：回到 `spec-driven-development`
+- 任务已经明确、准备实现：回到 `incremental-implementation`
+- 会话健康恶化明显：结合 `context-budget-audit`

package/vendor/packages/toolkit/src/content/skills/continuous-learning/body.md

@@ -1,102 +1,102 @@
-# Continuous Learning
-
-## 角色定位
-
-把一次会话中的可复用经验提炼成可审查、可回滚的学习项。它服务于长期协作质量，不是默认打开的遥测系统，也不是跨会话记忆的自动授权入口。
-
-核心模式：观察 → 提炼 → 验证 → 持久化 → 演化。
-
-## 何时使用
-
-- 用户明确要求 `/learn` 或复盘当前会话。
-- 多次出现同一纠正、错误修复路径或项目约定。
-- Sprint retrospective 需要沉淀可复用经验。
-- 需要把高频经验升级成 skill、command 或项目规则。
-
-不适用：
-
-- 单次偶然偏好。
-- 未经验证的猜测。
-- 敏感信息、凭据、生产数据或私人内容。
-- 用户没有同意的自动跨会话记忆。
-
-## 快速路径
-
-1. 收集本轮会话中可复用的观察，不存大段原始输入输出。
-2. 区分事实、用户偏好、项目约定和一次性上下文。
-3. 只提炼“触发条件 → 行动”的原子 instinct。
-4. 给每条 instinct 标置信心、证据、作用域和失效条件。
-5. 低置信度只留本地候选；高置信度也要说明为什么可复用。
-6. 需要写入长期文件或跨会话记忆时，先说明范围并等待用户同意。
-7. 多次重复后，再考虑演化为正式 skill / command / AGENTS 规则。
-
-## Instinct 格式
-
-```yaml
-id: prefer-targeted-verification
-trigger: "when finishing a scoped toolkit content change"
-action: "run toolkit lint and package tests before claiming completion"
-confidence: 0.8
-scope: project
-evidence:
-  - "User repeatedly asked for evidence before completion"
-expires_when: "project verification policy changes"
-```
-
-写得下这一段，才说明它足够明确；写不下就不要持久化。
-
-## 作用域判断
-
-| 类型 | 默认作用域 |
-|---|---|
-| 当前仓库验证命令、目录边界、提交习惯 | project |
-| 用户长期偏好，但不含敏感信息 | personal，需确认 |
-| 通用安全实践、证据先于断言 | global candidate，需多次证明 |
-| 一次性任务背景、临时路径、失败日志 | 不持久化 |
-
-## 证据质量
-
-可用证据：
-
-- 用户明确纠正。
-- 同一模式在多个任务中重复出现。
-- 修复失败后验证证明某个流程更可靠。
-- 仓库文档、测试或代码约束支持该规则。
-
-不可用证据：
-
-- 模型自己的感觉。
-- 单次偶然成功。
-- 未读完整输出的命令结果。
-- 涉及秘密、个人数据或生产数据的原文。
-
-## 演化门槛
-
-从 instinct 升级为正式内容前，检查：
-
-- 是否至少出现多次，或由用户明确要求沉淀。
-- 是否能写成清晰触发条件，而不是宽泛建议。
-- 是否与现有 skill / command 重叠。
-- 是否有验证方式或反例边界。
-- 是否会增加常驻上下文负担。
-
-优先把稳定规则写进已有 skill 或项目文档；只有边界清楚、复用频繁时才新增 skill。
-
-## Hook 边界
-
-Hook / automation 只能作为显式 opt-in 能力：
-
-- 安装前说明会记录什么、不记录什么、写到哪里。
-- 默认只记录摘要，不记录完整工具输入输出。
-- 支持关闭和清理。
-- 平台事件名和配置方式必须以当前官方能力为准。
-
-不要在内容层假设所有平台都支持同样的 hook 事件，也不要把 hook 当成默认运行前提。
-
-## 推荐输出
-
-```text
-Recommendation: <不记录 / 记录为候选 / 写入项目规则 / 演化为 skill> because <证据、作用域和长期上下文代价>。
-```
-
-推荐必须说明被放弃的替代方案，例如“只留聊天结论”“写入 AGENTS”“新增 skill”，以及为什么当前选择更合适。
+# Continuous Learning
+
+## 角色定位
+
+把一次会话中的可复用经验提炼成可审查、可回滚的学习项。它服务于长期协作质量，不是默认打开的遥测系统，也不是跨会话记忆的自动授权入口。
+
+核心模式：观察 → 提炼 → 验证 → 持久化 → 演化。
+
+## 何时使用
+
+- 用户明确要求 `/learn` 或复盘当前会话。
+- 多次出现同一纠正、错误修复路径或项目约定。
+- Sprint retrospective 需要沉淀可复用经验。
+- 需要把高频经验升级成 skill、command 或项目规则。
+
+不适用：
+
+- 单次偶然偏好。
+- 未经验证的猜测。
+- 敏感信息、凭据、生产数据或私人内容。
+- 用户没有同意的自动跨会话记忆。
+
+## 快速路径
+
+1. 收集本轮会话中可复用的观察，不存大段原始输入输出。
+2. 区分事实、用户偏好、项目约定和一次性上下文。
+3. 只提炼“触发条件 → 行动”的原子 instinct。
+4. 给每条 instinct 标置信心、证据、作用域和失效条件。
+5. 低置信度只留本地候选；高置信度也要说明为什么可复用。
+6. 需要写入长期文件或跨会话记忆时，先说明范围并等待用户同意。
+7. 多次重复后，再考虑演化为正式 skill / command / AGENTS 规则。
+
+## Instinct 格式
+
+```yaml
+id: prefer-targeted-verification
+trigger: "when finishing a scoped toolkit content change"
+action: "run toolkit lint and package tests before claiming completion"
+confidence: 0.8
+scope: project
+evidence:
+  - "User repeatedly asked for evidence before completion"
+expires_when: "project verification policy changes"
+```
+
+写得下这一段，才说明它足够明确；写不下就不要持久化。
+
+## 作用域判断
+
+| 类型 | 默认作用域 |
+|---|---|
+| 当前仓库验证命令、目录边界、提交习惯 | project |
+| 用户长期偏好，但不含敏感信息 | personal，需确认 |
+| 通用安全实践、证据先于断言 | global candidate，需多次证明 |
+| 一次性任务背景、临时路径、失败日志 | 不持久化 |
+
+## 证据质量
+
+可用证据：
+
+- 用户明确纠正。
+- 同一模式在多个任务中重复出现。
+- 修复失败后验证证明某个流程更可靠。
+- 仓库文档、测试或代码约束支持该规则。
+
+不可用证据：
+
+- 模型自己的感觉。
+- 单次偶然成功。
+- 未读完整输出的命令结果。
+- 涉及秘密、个人数据或生产数据的原文。
+
+## 演化门槛
+
+从 instinct 升级为正式内容前，检查：
+
+- 是否至少出现多次，或由用户明确要求沉淀。
+- 是否能写成清晰触发条件，而不是宽泛建议。
+- 是否与现有 skill / command 重叠。
+- 是否有验证方式或反例边界。
+- 是否会增加常驻上下文负担。
+
+优先把稳定规则写进已有 skill 或项目文档；只有边界清楚、复用频繁时才新增 skill。
+
+## Hook 边界
+
+Hook / automation 只能作为显式 opt-in 能力：
+
+- 安装前说明会记录什么、不记录什么、写到哪里。
+- 默认只记录摘要，不记录完整工具输入输出。
+- 支持关闭和清理。
+- 平台事件名和配置方式必须以当前官方能力为准。
+
+不要在内容层假设所有平台都支持同样的 hook 事件，也不要把 hook 当成默认运行前提。
+
+## 推荐输出
+
+```text
+Recommendation: <不记录 / 记录为候选 / 写入项目规则 / 演化为 skill> because <证据、作用域和长期上下文代价>。
+```
+
+推荐必须说明被放弃的替代方案，例如“只留聊天结论”“写入 AGENTS”“新增 skill”，以及为什么当前选择更合适。

package/vendor/packages/toolkit/src/content/skills/documentation-and-adrs/body.md

@@ -19,26 +19,28 @@
 ## 执行步骤
 
 1. 判断是否需要 ADR、README 更新、接口文档或注释
-2. 记录背景、约束、候选方案、决策和后果
-3. 对公共 API 或关键流程补充可消费文档
-4. 对源码中的非显而易见陷阱补充“为什么”类注释
-5. 检查发布或实现是否让以下长期文档产生 drift：
+2. 先选文档类型：教程、操作指南、参考手册、解释说明或 ADR；不要把这些目的混进同一份文档
+3. 记录背景、约束、候选方案、决策和后果
+4. 对公共 API 或关键流程补充可消费文档
+5. 对源码中的非显而易见陷阱补充“为什么”类注释
+6. 检查发布或实现是否让以下长期文档产生 drift：
    - README 和 quick start
    - 架构说明、ADR、迁移或兼容性说明
    - 公共 API、CLI、配置项、安装说明
    - 关键行为变更、默认值变化、已知限制
-6. 满足以下任一触发条件时，把文档同步视为显式收尾项，而不是可选备注：
+7. 满足以下任一触发条件时，把文档同步视为显式收尾项，而不是可选备注：
    - 用户首条成功路径变了
    - 安装、升级、回滚步骤变了
    - 默认行为、配置语义或兼容性边界变了
    - 运维、支持或后续开发会因为旧文档而误判
-7. 把文档与代码一起进入版本控制；如果代码已发布，再补一次发布后同步核对
+8. 把文档与代码一起进入版本控制；如果代码已发布，再补一次发布后同步核对
 
 ## 成功标准
 
 - 重要决策有书面理由，不依赖口头记忆
 - 文档说明的是“为什么”和“怎么验证”，不是重复代码
 - 后续工程师或代理能直接消费这些记录
+- 文档类型清楚，不把教程、参考和 ADR 写成一锅粥
 - 文档与当前实现保持同步
 - 文档 drift 被显式识别，而不是在发布后被动暴露
 

package/vendor/packages/toolkit/src/content/skills/engineering-principles/body.md

@@ -12,25 +12,29 @@
 1. 先澄清假设
    把输入、约束、风险和未知项说清楚，再进入实现。
 
-2. 简单优先
+2. 疑点优先收敛
+   遇到相互矛盾、会改变架构或会影响数据安全的疑点时，先提出具体问题；低风险疑点可以声明假设后继续推进。
+
+3. 简单优先
    先选最直接、最容易验证、最少抽象的方案。
 
-3. 外科式修改
+4. 外科式修改
    只改完成目标所需的最小范围，不顺手扩散、不借题发挥。
 
-4. 目标导向
+5. 目标导向
    每一步都要能回答“这一步为什么必要，它离目标更近了什么”。
 
-5. 证据先于断言
+6. 证据先于断言
    结论必须建立在测试、构建、检查或运行结果上，而不是感觉。
 
-6. 发布后不允许失控漂移
+7. 发布后不允许失控漂移
    已发布行为、文档、门禁和回归基线发生变化时，必须有明确校验与同步动作，不能默认“上线后自然会对齐”。
 
 ## 原则落点
 
 | 原则 | 主要落点 |
 | --- | --- |
+| 疑点优先收敛 | `spec-driven-development`、`planning-and-task-breakdown`、`debugging-and-error-recovery` |
 | 证据先于断言 | `verification-before-completion`、`ci-cd-and-automation`、`browser-qa-testing` |
 | 复杂任务谨慎优先于求快 | `verification-before-completion`、`context-engineering` |
 | 简单优先 | `ci-cd-and-automation`、`browser-qa-testing`、`context-engineering` |
@@ -41,6 +45,7 @@
 ## 执行检查清单
 
 - 我是否明确了当前目标和不做什么
+- 我是否把会改变路线的疑点变成了问题或显式假设
 - 这次改动是否是当前问题的最小可行解
 - 是否引入了与目标无关的抽象、重命名或结构变动
 - 是否保留了足够的验证证据来支撑最终结论

package/vendor/packages/toolkit/src/content/skills/git-workflow-and-versioning/body.md

@@ -140,29 +140,29 @@ refactor/<简短描述>  → refactor/auth-module
 
 ## Git Worktree 并行开发
 
-当多个 AI Agent 需要并行工作时，使用 git worktree 同时运行多个分支：
+当多个 AI Agent 需要并行工作时，使用 git worktree 同时运行多个分支。优先使用已被 `.gitignore` 覆盖的项目内 `.worktrees/`；如果无法证明项目内目录会被忽略，就使用仓库外的兄弟目录。
 
 ```bash
 # 为 feature 分支创建 worktree
-git worktree add ../project-feature-a feature/task-creation
-git worktree add ../project-feature-b feature/user-settings
+git worktree add .worktrees/project-feature-a feature/task-creation
+git worktree add .worktrees/project-feature-b feature/user-settings
 
 # 每个 worktree 是独立目录，各自有自己的分支
 # Agent 可以并行工作互不干扰
-ls ../
-  project/              ← main 分支
+ls .worktrees/
   project-feature-a/    ← task-creation 分支
   project-feature-b/    ← user-settings 分支
 
-# 完成后合并并清理
-git worktree remove ../project-feature-a
+# 完成后先确认状态，再合并或清理
+git -C .worktrees/project-feature-a status --short --branch
+git worktree remove .worktrees/project-feature-a
 ```
 
 优势：
 - 多个 Agent 可以同时工作在不同功能上
 - 无需切换分支（每个目录有自己的分支）
-- 实验失败时直接删除 worktree — 不会丢失任何东西
 - 变更相互隔离，直到显式合并
+- 实验失败时也先记录结论并检查 diff，再决定合入、保留或丢弃
 
 ## 存档点模式
 
@@ -180,7 +180,7 @@ Agent 开始工作
     └── 功能完成 → 所有提交形成干净的历史
 ```
 
-这个模式意味着你永远不会丢失超过一个增量的工作。如果 Agent 走偏了，`git reset --hard HEAD` 就能回到上一个成功状态。
+这个模式意味着你不会把多个未验证增量混成一团。如果 Agent 走偏了，先读 `git status` 和 `git diff`，确认哪些文件属于本次增量，再按团队规则回退或丢弃；不要在未确认范围时使用破坏性回退命令。
 
 ## 变更摘要