# 常见问题答疑（FAQ）
本文件集中索引 dev-expert 技能使用中常见疑问、执行禁区、验证失败处置和边界外请求处理。详细规则出处以章节名标注，便于追溯到 SKILL.md 或对应 reference。
> 📌 **TL;DR（30 秒速览）**
>
> - 不会选技能？**直接描述目标**，系统自动路由+组合，选错会提示确认，不会乱干。
> - 怕踩坑？先扫「能力边界速览」看哪些不能做；红线（直拼 SQL/盲写库/跳验证）必被拦。
> - 长任务/换电脑？靠 `.ai-memory/handoff.md` 检查点续做，进度不丢。
> - 改错了？`.bak` 自动备份，复制回原文件即回滚（**别手动删 `.bak`**）。
> - 看不懂报错？要求"普通人可读版"，必须给"发生了什么/原因/方向"。
### FAQ 主题速查
> 🚀 **第一次用？只看这段**：直接说你的需求，系统自动路由+组合；只有"报错 / 不确定能不能做 / 想纠正"才需要往下翻。
需要按主题查找？点开速查表
| 你想了解 | 看哪节 |
| ---------------------------------------------------------- | -------------------------------------------------------- |
| 怎么选 / 触发哪个技能、关键词没命中怎么办 | 一、路由与子技能选择 |
| 哪些事不能做（执行禁区 / 边界外） | 二、执行禁区清单 / 六、边界外请求 / 顶部「能力边界速览」 |
| 报错看不懂、验证失败怎么处置 | 三、验证失败处置 / 四、异常处理与稳定性 |
| 常见反模式与踩坑 | 五、常见反模式与踩坑 |
| 显式 `@` 调用与自动路由 | 七、显式调用与自动路由 |
| 子 Agent 能不能改代码 | 八、子Agent 边界 |
| 长任务续做 / 检查点 / 可靠交付 / 权限开放 | 九、长任务执行与可靠产出物 |
| 数据库 / 迁移 / 慢查询安全 | 十、数据库与迁移安全 |
| CMS / Laravel / Java 专项边界 | 十一、专项领域与框架边界 |
| 项目记忆 / 换电脑续做 | 十二、新会话恢复与项目记忆 |
| 文档 / Spec / 技术选型 | 十三、文档与规范类任务 |
| JS / Node.js 专项 | 十四、JavaScript 专项 |
| Hooks 自动守卫（启用 / 检查 / 排查 / 禁用） | 十五、Hooks 自动守卫 |
| 需求澄清 / Wayfinder / 模块边界 | 十六、需求澄清与模块边界 |
| 交付保障 / 收尾报告 / 踩坑错误册 | 十七、交付保障与踩坑管理 |
| 多技能组合与触发进阶 | 十八、子技能组合与触发进阶 |
| 新手常问但前面没答的问题（纠正/回滚/中文/省 token/第一步） | 二十、新手高频疑问补遗 |
| 可直接抄用的代码示例 | 十九、常见技能实际代码示例 |
## 先看这里：普通人可读版
> **本节要点**：新人先读这节——"你遇到的情况"对照表 + 能力边界速览，一眼分清能做/不能做。
| 你遇到的情况 | 先做什么 | 不要做什么 |
| -------------------------- | -------------------------------------------- | ------------------------------------ |
| 不知道该用哪个技能 | 直接描述目标，例如"帮我修这个报错" | 不必先背全部触发词 |
| 看不懂错误提示 | 要求输出"发生了什么 / 可能原因 / 修复方向" | 不要只根据专业术语改配置 |
| 网络卡住或下载失败 | 允许最多 2 次安全重试，并记录最后错误 | 不要对写入、扣费、发布类操作自动重试 |
| 涉及数据库、权限、生产配置 | 先看方案、影响范围、回滚和验证路径 | 不要直接进入快速通道 |
| 文档太多不知道看哪个 | README 看入口，FAQ 看踩坑，references 看细节 | 不要同时读全量 reference |
### 能力边界速览：哪些事本技能明确不做（一眼看清，免得踩坑）
很多人翻到 FAQ 深处才发现"原来这不能做"。这里先集中摆一眼，**完整清单仍在 二、执行禁区清单 与 六、边界外请求**。
**① 明确不覆盖的领域（边界外，只做说明不替代专门流程）**
用户调研 · 工时排期 · 容器深度编排 · IDE 配置 · 缺陷跟踪流程 · 安全深度扫描。
**② 明确禁止的做法（执行禁区，踩了会被安全闸门拦 / 交付无效）**
直拼 SQL · Shell 写中文/UTF-8 文件 · 跨模块扩散修改 · 硬编码密钥 · 跳过验证直接交付 · 安全/数据类失败重试 · 凭猜测补业务规则 · 快速通道执行数据库写入 · 跨模块(≥2)/批量替换(>10处) 走快速通道。
**③ 用户最容易忽略的技术限制（放在显眼处提醒）**
- **单次最多加载 3 个 reference**：一句话挂太多子技能会触发"过度路由"回退，只保留首选 + 必要协同（见 一、Q4）。
- **子 Agent 禁止写/改代码（L0 硬约束）**：只做检索收集，改码须主 Agent 自写或复核后执行（见 八、）。
- **代码审查是只读的**：`@code-review` 只出分级问题清单，**不默认改写实现**；要改须走重构/生成分支并先确认（见 十八、）。
- **十一个"专项 reference"不支持 `@` 显式调用**：`@laravel-development` / `@laravel-testing` / `@java-development` / `@javascript-development` / `@execution-safety` / `@delivery-assurance` / `@error-ledger` / `@style-alignment` / `@architecture-decision` / `@domain-driven-design` / `@distributed-systems` 只作领域协同资料，用关键词触发即可（见 七、Q5 / 十四、Q1）。
- **快速通道有门槛**：仅低风险、可局部回退、目标明确时启用；涉及库写入 / 权限 / 生产配置须退出，先给方案与回滚路径（见 四、Q"哪些操作前必须确认"）。
- **hooks 是护栏，不替代 Agent 验证**：只兜底机械项（备份/lint/PHP8/脱敏…），真实运行与 E2E 仍须 Agent 显式产出证据（见 十五、Q"hooks 能替代吗"）。
> 记不住全表没关系，记住一句：**"写代码/查 Bug/做文档/审质量"都能做；问调研排期、动生产配置前先确认、别让 Agent 替你盲写库"就是边界。**
## 一、路由与子技能选择
> **本节要点**：没命中关键词/显式@/多领域/跨模块怎么路由，单次最多加载 3 个 reference。
**Q1：我说的话没命中任何关键词怎么办？**
A：优先用 `@<英文标识>` 显式指定（见 SKILL.md Step 1.2），或在输入中描述任务目标而非关键词（如"加个登录接口"会被路由到 `api-design`）。仍无法命中时，系统会按"无法唯一确定时向用户确认意图"规则向你索取意图。
**Q2：显式指定后，发现任务实际不该用这个子技能，会自动切换吗？**
A：不会自动切换。系统检测到强冲突时输出提示让你确认（见 SKILL.md Step 1.2 「任务-技能不匹配提示」表），你回复后才会切换；回复"按原指定执行"时立即按显式指定走，不再追问。
**Q3：多个子技能同时命中怎么决定？**
A：按 SKILL.md「子技能优先级矩阵」组合路由；无法组合时选匹配度最高的；无法唯一确定时向你确认。
**Q4：任务跨多个领域（如 CMS + 数据库 + 前端）怎么处理？**
A：按 SKILL.md「领域路由表」的协同 reference 顺序加载，先执行首选 reference，再按需加载协同 reference。一次任务最多加载 3 个 reference，超过则触发"过度路由"回退（见 SKILL.md「对话流异常处理边界」）。
## 二、执行禁区清单
> **本节要点**：9 条明确禁止做法 + 每禁区真实场景对照；踩了交付无效或被安全闸门拦。
以下做法在本技能中明确禁止，踩坑会导致交付无效或被安全闸门拦截：
| 禁区 | 原因 | 正确做法 | 规则出处 |
| ----------------------------------------- | ---------------------- | ------------------------------------------- | ------------------------------------- |
| 直拼 SQL 字符串 | SQL 注入风险 | 用 PDO 预处理 / 参数绑定 | `mysql-database` |
| Shell 写中文/UTF-8 文件 | 编码损坏、中文乱码 | 用 Edit / Write 工具，或二进制读写 | SKILL.md 非 Git 文件操作安全协议 |
| 跨模块扩散修改 | 破坏上下文延迟加载协议 | 一次只改当前目标文件 + 直接引用文件 | SKILL.md 上下文延迟加载协议 |
| 硬编码密钥/Token/密码 | 安全闸门拦截 | 从环境变量读取，密钥不入代码 | SKILL.md 安全闸门 / `cms-development` |
| 跳过验证直接交付 | 违反 Step 4 硬性前提 | 必须采集命令输出/测试报告/截图/API 响应之一 | SKILL.md Step 4 验证结果 |
| 安全/数据类失败重试 | 失败重试基线 = 0 | 立即升级，不重试 | SKILL.md 失败重试基线 |
| 凭猜测补齐业务规则 | 业务规则不明时禁止 | 高澄清级别，向用户索取输入 | SKILL.md 澄清策略分级 |
| 快速通道执行数据库写入 | 退出快速通道条件 | 切换到"先方案后执行"模式 | SKILL.md 快速通道机制 |
| 跨模块(≥2)/批量替换(>10处) 在快速通道执行 | 误判快速通道 | 立即退出快速通道 | SKILL.md 对话流异常处理边界 |
### 二（续）· 每个禁区的具体场景举例
上面表格的「原因 / 正确做法」偏原则，下面给每个禁区配一个**真实可对照**的场景，方便新人"对号入座"：
- **直拼 SQL 字符串**
❌ `mysql_query("SELECT * FROM user WHERE id=".$_GET['id'])` —— 传入 `1; DROP TABLE user` 即注入脱裤。
✅ PDO `WHERE id = ?` 并 `bindParam`，或走框架访问层传参（`mysql-database`）。
- **Shell 写中文/UTF-8 文件**
❌ PowerShell `Set-Content -Value "中文配置" x.txt` 默认 GBK/带 BOM，跨平台读成乱码。
✅ 用 Edit/Write 工具写盘，或 Python `open(f, encoding='utf-8')` 二进制写。
- **跨模块扩散修改**
❌ 改一个工具函数，顺手把 8 个"看着像"的无关模块调用一起改 —— 破坏延迟加载，引发未知编译错误。
✅ 只改当前目标文件 + 它直接 import 的文件；其余列入 `*_plan.md` 由你确认。
- **硬编码密钥/Token/密码**
❌ `api_key = "sk-live-xxxx"` 写进源码并提交。
✅ 从环境变量 / 密钥管理读取，代码只留 `os.getenv("API_KEY")`。
- **跳过验证直接交付**
❌ "改完了，应该没问题" —— 无 lint / 测试 / 运行输出。
✅ 至少贴一种证据：命令输出、测试报告、截图或 API 响应（Step 4 硬性前提）。
- **安全/数据类失败重试**
❌ 扣费接口 500 后自动再发一次 —— 可能重复扣费。
✅ 立即升级报你，绝不自动重试（失败重试基线 = 0）。
- **凭猜测补齐业务规则**
❌ 看到字段空，自己猜"默认走 A 渠道"就写死。
✅ 高澄清级别，先问你"默认渠道是 A 吗？"再动手。
- **快速通道执行数据库写入**
❌ "顺手把这条脏数据 UPDATE 掉" —— 没给影响行数和回滚。
✅ 切"先方案后执行"模式：SELECT 验证 → 给影响行数 → 备回滚 SQL → 你确认。
- **跨模块/批量替换走快速通道**
❌ 在快速通道里一次性替换 15 处字符串。
✅ 立即退出快速通道，输出方案 + 验证路径，按「批量修改 7 防线」做。
## 三、验证失败处置
> **本节要点**：按失败类型查重试上限（安全类 0 次、Lint 3 次、验证 2 次、环境 1 次）。
按失败类型索引到现有规则，避免重复定义：
| 失败类型 | 最大重试 | 处置 | 规则出处 |
| ---------------------- | -------- | ------------------------------------ | ------------------------------------------ |
| 安全/数据类 | 0 | 立即升级，不重试 | SKILL.md 失败重试基线 |
| Lint/语法类 | 3 | 多次尝试修复 | SKILL.md 失败重试基线 |
| 验证类失败 | 2 | 默认 2 次后升级 | SKILL.md 失败重试基线 |
| 环境类失败 | 1 | 重试 1 次后升级 | SKILL.md 失败重试基线 |
| 业务规则不明 | 0 | 立即向用户索取输入 | SKILL.md 失败重试基线 |
| 同一 Bug 2 轮未修复 | — | 标记已知限制，不再循环 | SKILL.md 轮次控制 → 失败熔断 |
| 连续 2 轮仅做 P2 微调 | — | 建议提前结束 | SKILL.md 轮次控制 → 低收益检测 |
| 加载 reference 数 > 3 | — | 回到意图三分法，只保留首选 reference | SKILL.md 对话流异常处理边界 → 过度路由 |
| 快速通道发现跨模块(≥2) | — | 立即退出快速通道，输出方案和验证路径 | SKILL.md 对话流异常处理边界 → 快速通道误判 |
| 输出含 Token/密码/密钥 | — | 回到安全闸门，隔离不可信输入 | SKILL.md 对话流异常处理边界 → 安全闸门失效 |
## 四、异常处理与稳定性
> **本节要点**：报错须给"普通人可读版"；生产/库/权限操作前必确认；网络仅安全场景重试 2 次。
**Q：出了 Bug 时，会怎么告诉我？**
A：必须给出"发生了什么、可能原因、修复方向、验证方法"。如果根因证据不足，只能说"最可能原因"和"待验证动作"，不能把猜测写成结论。
**Q：专业报错看不懂怎么办？**
A：要求输出普通人可读版。标准格式是：
```text
发生了什么：[一句话解释]
可能原因：[1-3 个候选原因，标注已确认/待验证]
修复方向：[下一步最小动作]
需要你提供：[缺什么就写什么，没有则写"无"]
```
**Q：哪些操作前必须确认？**
A：生产配置、数据库写入、权限、凭证、隐私、不可回滚操作、发布上线、批量替换、删除文件、扣费或发消息类操作，都必须先说明影响范围和验证/回滚路径，等用户确认后再执行。
**Q：网络卡顿会自动重试吗？**
A：只在安全场景自动重试。下载依赖、只读请求、临时超时、远程 5xx 可以最多重试 2 次；写操作、扣费、发邮件、发布、删除、权限失败、参数错误、4xx 业务错误不自动重试。
**Q：连续失败会不会偷偷继续？**
A：不会。失败会按 SKILL.md "失败重试基线"熔断：安全/数据类不重试，验证类默认 2 次，Lint/语法类最多 3 次，环境类 1 次。超过后必须说明阻塞和下一步。
**Q：什么情况下会停下来问我，而不是直接继续？**
A：三类必问：① 涉及生产配置、数据库写入、权限、凭证、隐私或不可回滚操作 → 触发安全闸门，退出快速通道先给方案与验证路径；② 业务规则/验收口径不明 → 按澄清策略分级，高澄清级别先问关键问题再执行；③ 自主度随验证失败、范围扩大或新风险动态下调一级，关键步骤前确认。低风险、可局部回退、目标明确的任务则进快速通道直接做，并在交付里说明假设与证据（见 SKILL.md「自主度分级」「澄清策略分级」）。
## 五、常见反模式与踩坑
> **本节要点**：16 条常见反模式对照表，提前避坑（含"未验证就说完成""审查却直接改实现"等）。
| 反模式 / 坑 | 典型表现 | 正确做法 |
| ---------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| 只看 README 不看 FAQ | 初次能启动，但遇到失败不知道怎么办 | README 看入口，FAQ 查踩坑和边界 |
| 一次加载太多 reference | 文档越看越乱，任务边界变大 | 单任务最多首选 + 必要协同 reference |
| 未验证就说完成 | 没有命令、测试、截图或 API 响应证据 | 按 Step 4 输出至少一种验证证据 |
| 把优化当主线 | 主功能没验收，却开始整理命名/注释 | 主线完成度只按用户核心交付物计算 |
| 网络失败反复重试 | 下载/接口失败后无限循环 | 最多 2 次安全重试，之后输出阻塞 |
| 数据库写入走快速通道 | 未确认影响行数和回滚路径 | 先方案后执行，必要时 SELECT/EXPLAIN 验证 |
| 报错只给专业术语 | 用户只看到堆栈和错误码 | 同时给普通人可读解释和下一步动作 |
| 换电脑只依赖 IDE 会话 | 新电脑不知道上次做到哪 | 写 `.ai-memory/handoff.md` 并随代码同步 |
| 修改缓存文件修报错 | 下次缓存重建后问题复发 | 排查上游生成逻辑，不直接改缓存 |
| Shell 改中文文件 | UTF-8/GBK 被破坏导致乱码 | 使用安全编辑方式，避免 `Set-Content` / `Out-File` |
| 长任务不落检查点 | 对话压缩/关 IDE 后进度全丢，重跑已验证部分 | 每 Wave/每 5 原子任务写 `handoff.md` 检查点（已完成+证据/未完成/阻塞） |
| 把"已返回"当"已完成" | 长任务部分失败却报全绿，未验证项被隐藏 | 可靠交付物四要素全披露，未验证项/部分失败明细不得省略 |
| 性能优化无基线声称提升 | 只说"快了"却无 profiler/benchmark 对比 | 先跑基线再跑对比，量化前后耗时/内存差异（`performance-benchmark`） |
| 审查请求却直接改实现 | 用户要 review，却直接重写代码 | 代码审查以发现问题为主，不默认重写；确认后再改（`code-review` 互斥规则） |
| 数据库写入直拼 SQL | SQL 注入风险，且绕过框架访问层 | 全部参数绑定，`IN(?,?,?)`/白名单映射 ORDER BY（`mysql-database`） |
## 六、边界外请求
> **本节要点**：不覆盖领域（调研/排期/容器深度编排/IDE 配置等）只做边界说明，不替代专门流程。
本技能不覆盖以下领域（详见 SKILL.md「本技能边界声明」章节）：用户调研、工时排期、容器深度编排、IDE 配置、缺陷跟踪流程、安全深度扫描。出现这些请求时只做边界说明，不声称已覆盖，不尝试用泛化方案替代专门流程。
## 七、显式调用与自动路由
> **本节要点**：`@` 显式调用只跳路由、不破安全闸门；专项 reference 不支持 `@`；含知识图谱用法 Q&A。
**Q：显式调用会破坏自动识别吗？**
A：不会。显式调用是前置短路逻辑：仅当输入以 `@<合法英文标识>` 开头时跳过关键词路由，否则完全走原有路由表 + 优先级矩阵 + 意图三分法。拼写错误、邮箱、@提及等不触发显式调用，自动回退到关键词匹配。
**Q：显式调用后还能加载协同 reference 吗？**
A：可以。显式调用只跳过"路由匹配"环节，领域路由表的协同 reference 仍按需加载。例如 `@api-design` 仍会按需加载 `frontend-design`、`cms-development`。
**Q：显式调用后，意图三分法和安全闸门还生效吗？**
A：全部生效。显式调用只决定"用哪个子技能"，不决定"怎么执行"。意图三分法、安全闸门、澄清策略、验证闭环、复盘沉淀全部照常执行。
**Q：显式调用后任务-技能不匹配，提示几次？**
A：最多 1 次。用户确认后立即执行，不再追问；用户回复"按原指定执行"时按显式指定走。避免过度澄清（详见 SKILL.md「对话流异常处理边界 → 澄清过度」）。
**Q：为什么 `@laravel-development` / `@java-development` 不生效？**
A：Laravel、Java（及 laravel-testing）属于「专项 reference 映射」，只作领域协同资料按需加载，**不加入 `@英文标识` 显式调用索引、也不计入 19 个子技能数量**（见 SKILL.md「专项 reference 映射」）。要用它们，在输入里用关键词触发领域路由即可自动追加其框架约定（如"Laravel/Eloquent/Blade 写代码"→ 代码生成 + laravel-development 协同；"Java/Spring Boot 写代码"→ 代码生成 + java-development 协同）。只有 19 个核心子技能支持 `@` 显式调用（含新增的 `@project-knowledge-graph`）。
**Q：项目知识图谱（`@project-knowledge-graph`）怎么用？构建和查询耗 token 吗？**
A：**零 LLM token**。构建走 `scripts/build_graph.py` 纯正则静态抽取（无 AST/tree-sitter；LSP 仅探测 `intelephense`/`phpactor` 可用性并写 `meta.json.lsp_available`，**不参与抽取**），不进 LLM 上下文（构建 token≈0）；查询只返回子图 JSON（节点硬上限 `MAX_NODES=80`），也不重读源码。用法：
- 构建：`python scripts/build_graph.py --root {PROJECT_ROOT} --rebuild`
- 查依赖闭包（跨模块改动/重构前）：`--query a.php,b.php,c.php --direction both --depth 3`（**多个入口逗号分隔，自动合并子图**——覆盖 SKILL.md Step2 P1 的依赖闭包用法）
- 查上游依赖方：`--query 某模块 --direction up --depth 2`
- 图不存在/被误删：自动触发 `[GRAPH-STALE]` 当场重建，不会崩（不会报 `GRAPH-MISSING`，也不会"回退全图扫描"——未命中符号时返回空子图）
- 真实边类型：`include`(含 require/include_once/require_once) / `use`(命名空间) / `autoload`(new \Ns\Class) / `extends` / `template`({include file=}) / `tpimport`(ThinkPHP import/vendor/Loader::import) / `import`(非 PHP 语言) / `cssimport` / `asset`(HTML link/script) / `calls`。注意 `require` 已并入 `include`，`implements` 是类属性、**非独立边**。token 节省量级见 README「附录 A」。
## 八、子Agent 边界
> **本节要点**：子 Agent 一律禁改码，只检索收集；生成式方案须主 Agent 复核后才落地。
**Q：子 Agent（如 code-explorer）能帮我直接改代码吗？**
A：不能。无论何种子 Agent，一律禁止写或改项目代码文件（L0 级硬约束），写码/改码须主 Agent 自写或经显式授权并复核边界后执行。详见 `SKILL.md → 二、子Agent 边界与委派协议`：检索收集型子 Agent 只返回 `文件:行号 + 原文`，禁推理归纳；审查型只输出问题清单；子 Agent 不继承版本/环境/用户有意优化等铁律，其生成式结论须主 Agent 复核。委派前主 Agent 必须先给出目标/边界/验收口径，否则触发"理解委派"失败模式收回任务。
**Q：子 Agent 返回的"修复建议"能直接用吗？**
A：不能。检索收集型子 Agent 只能给原文，审查型可给问题清单但仍需主 Agent 复核；任何生成式修改方案都必须经主 Agent 审查边界、跑验证后才能落地（呼应安全闸门与红线6）。
**Q：什么情况下才能委派子 Agent？**
A：主 Agent 先完成需求分析与意图澄清，输出目标/边界/验收口径后，再把执行型子任务委派出去（见 `task-decomposition-and-execution.md` 第四步「委派简报」）。任务未明确即委派会触发"理解委派"失败模式，收回任务回到需求分析。
## 九、长任务执行与可靠产出物
> **本节要点**：Wave 轮次不跨累计；handoff 检查点续做；部分失败不谎报全绿；自动执行须开放权限。
**Q：长任务会不会因为"轮次上限"被中途强制结束、之前做的工作全废？**
A：不会。"安全最大轮次 = 6"只约束**单个 Wave 内的收敛循环**，不跨 Wave 累计。大任务应通过 Wave 拆分 + 跨会话 `handoff.md` 续做；已完成 Wave 的产出物（变更文件 + 验证证据）保留，不回退清零。达到上限时输出该 Wave 未完成清单并转交续做。
**Q：长任务跑到一半、对话被压缩或我关掉 IDE，进度会丢吗？**
A：不会丢。每完成一个 Wave 或累计 5 个原子任务，必须向 `.ai-memory/handoff.md`（跨会话可迁移）或本任务状态文件落检查点，含「已完成项(带验证证据) → 相关文件 + 未完成项(下一步) + 阻塞项」。新会话/新电脑读取 `handoff.md` 即可无损续做，不重跑已验证部分（见 `SKILL.md → 长任务执行可靠性` 与 `project-memory-management.md` 交接协议）。
**Q：长任务部分批次失败了，会不会被说成"全部完成"？**
A：不会。可靠交付物强制四要素：① 已完成清单(每项带验证证据) ② 未验证项/已知限制(显式列出，禁止隐藏) ③ 部分失败明细(哪些批次成功/失败、是否可 resume、失败原因与已落地错误列表) ④ 下一步(未完成项续做动作)。任何"已返回结果"不等同"已验证完成"；未声明的验证视为未完成。
**Q：被设计的长任务接口（Init-Step-Poll）和我让 Agent 跑的长任务，是一回事吗？**
A：不是两层。前者是你**产品的**后台长任务（批量导入/导出/生成静态页等）须采用 `Init → Step → Poll` 防卡死架构，权威定义与「长任务验证」证据表见 `software-project.md` 第六步；后者是 **Agent 自身**的长链路执行须落检查点、披露未验证项。两层都要求可验证进度与恢复点，但约束对象不同（产品侧另见 `cms-development.md` 第六步、`api-design.md`、`task-decomposition-and-execution.md` 第四步 Wave 拆解与上下文隔离）。
**Q：长任务怎么才算"验收通过"？**
A：除通用验收标准（见 `SKILL.md` 第五步）外，长任务还须满足「长任务可靠」维度：有 handoff/状态文件检查点；交付含未验证项与部分失败明细且未隐藏；被设计的系统层 Init/Step/Poll/Cancel/失败重试/僵尸检测各有验证证据（见 `software-project.md` 第六步「长任务验证」证据表）。
**Q：长任务要"自动执行 + 自动测试"，为什么还得在运行时开放权限？**
A：捕获 hook（capture_learning.py 等）和长任务闭环要自主跑通「执行命令 → 跑测试（php -l / phpunit / node --check）→ 落记录」，依赖运行时授予 `Bash`/`execute_command` 等工具的**免确认执行权限**。系统默认对危险操作（如**删除文件**、写入受保护目录、生产配置）会要求用户确认——若未开放，长任务每步弹确认就会被卡死，自我改进闭环也无法自主推进。开放方式两层：① 技能侧 `SKILL.md` 的 `allowed-tools` 已声明需要 `Bash` 等工具；② 运行侧（IDE/平台权限策略）须允许这些工具 auto-approve（或任务前显式授权删除/写入等）。未开放时，长任务须退化为「每步请求确认」模式，不得假设可无人值守自动执行（见 `SKILL.md` frontmatter 的 `allowed-tools` 声明 与 `FAQ.md` 第九节）。
## 十、数据库与迁移安全
> **本节要点**：SQL 全参数绑定、UPDATE/DELETE 带 WHERE+先 SELECT、DDL 给回滚；慢查询先 EXPLAIN 再优化。
**Q：写 SQL / 做数据库迁移前要注意什么？**
A：遵循 `mysql-database` 规范：① 所有外部输入必须参数绑定（禁直拼 `$id`/`$kw`，用 `?` / `IN(?,?,?)` / 白名单映射 ORDER BY / LIMIT 转 int）；② 任何 UPDATE/DELETE 必须带 WHERE 并先 SELECT 验证影响行数，禁无 WHERE 写操作；③ 建表统一 `utf8mb4`、InnoDB、`BIGINT UNSIGNED` 主键，金额用 `DECIMAL` 禁 float；④ 索引必须对应具体查询路径并用 `EXPLAIN` 验证 `key/type/rows/Extra`，禁无理由加索引、禁低区分度字段单独建索引；⑤ DDL/数据修复必须给出备份方案 + 执行 SQL + 影响行数预估 + 回滚 SQL + 执行窗口，大表 ALTER 须在线 DDL（见 `mysql-database` 第八步）。
**Q：慢查询怎么诊断，能直接上缓存吗？**
A：先拿证据再优化：原始 SQL + 参数样例 + 表行数 + `EXPLAIN` + 相关索引。看 `type`(警惕 ALL/index)、`rows`(远大于返回行数)、`key`(未命中预期)、`Extra`(Using filesort/temporary)。优化顺序：改查询条件 → 调索引 → 改分页/统计 → 拆表/缓存；**不得先上缓存掩盖 SQL 问题**。
**Q：大批量导入/导出/修数据为什么要用 Init-Step-Poll？**
A：单事务影响行数超 10000 必须分批；大批量任务须采用 `Init → Step → Poll` 渐进式防卡死架构（Init 创建、Step 分批、Poll 查进度、支持 Cancel/失败重试/僵尸检测），避免长事务锁表、内存溢出或前端超时卡死（见 `api-design` 长任务模式与 `mysql-database` 第六步）。
## 十一、专项领域与框架边界
> **本节要点**：CMS 先确认类型再生成；Laravel/Java 只协同、不 `@` 显式调用（未确认前不套用到非框架项目）。
**Q：CMS 二次开发（帝国CMS/WordPress/PHP8）要注意什么？**
A：遵循 `cms-development`：先确认 CMS 类型再生成框架特定代码（未确认前禁止生成）；PHP8 兼容（数组键引号、短标签、`each/create_function`、`??` 优先级、`fetch1` 返 false 守卫等）；严守安全红线（SQL 注入/XSS/CSRF/文件上传/反序列化/路径遍历/eval/Include）；插件走官方扩展点，后台路径不写死；CMS 数据库任务联动 `mysql-database` 的表前缀与官方数据访问层。
**Q：我的项目是 Laravel/Java，能用 `@laravel-development` 显式调用吗？**
A：不能。Laravel/Java（及 laravel-testing）属于「专项 reference 映射」，只作领域协同资料，不进 `@` 显式调用索引、不计入 19 子技能（见 七、Q5）。用关键词触发领域路由即可自动追加其框架约定；但**未确认 Laravel/Java 项目前，不得把规则套用到 CMS 等非框架项目**（领域路由边界）。
## 十二、新会话恢复与项目记忆
> **本节要点**：记忆只写 `.ai-memory/` 不污染仓库；新会话自动恢复；daily 即时追加、超 30 天蒸馏。
**Q：新会话/换电脑怎么接着上次做？**
A：新会话首次响应前执行 Step 1.1「恢复历史记忆」：探测 `{PROJECT_ROOT}/.ai-memory/`，按三层策略加载（Metadata→Body→References，token 预算≈1000）；你说"继续/下一步"时先加载上次主线目标、执行位置、阻塞状态再动手，不重跑已验证部分。长任务续做读 `.ai-memory/handoff.md` 检查点（见 九、长任务）。无历史记忆时正常进意图识别，不阻塞（详见 SKILL.md Step 1.1 与 `project-memory-management`）。
**Q：项目记忆存在哪、会污染代码仓库吗？**
A：只写 `.ai-memory/`（会话摘要、决策记录、规范捕获、已知问题清单），业务历史写 `project_memory.md`；**不写入代码仓库、不污染版本控制**。跨会话恢复、决策可撤销性、规范复用都靠它（见 `project-memory-management`）。
**Q：daily.md 是什么？和 session_memory 有什么区别？**
A：`daily.md` 是当日逐条操作日志（append-only），每次完成实质性工作后**立即追加**，记录单条操作的摘要、修改文件、决策和验证结果。`session_memory` 是会话结束后生成的完整总结，包含全局目标、已完成清单、关键决策和下一步计划。两者互补：`daily.md` 记录操作点滴（操作级），`session_memory` 记录会话全貌（会话级）。
**Q：写后即记协议什么时候触发？**
A：7 类实质性操作完成后自动触发，不经确认：Bug 修复、功能实现/代码生成、代码审查/重构、技术选型定案、配置变更/数据库迁移、文档生成/规范沉淀、项目约定/用户偏好新发现。纯信息查询、只读检查、临时测试不触发（详见 SKILL.md Step 0）。
**Q：旧日志怎么清理？**
A：超过 30 天的 `{YYYYMMDD}/` 日志目录在 Step 6 复盘时触发蒸馏：关键决策/Bug 模式/项目约定 → 提炼入 `project_memory.md`，纯操作流水丢弃，蒸馏后删除整个日期目录。`daily.md` 当日超 8000 字符出示精简提醒，超 12000 字符强制蒸馏（详见 `project-memory-management` 记忆维护协议）。
## 十三、文档与规范类任务（doc-generation）
> **本节要点**：文档不得替代验证、签名须对齐真码；Spec/选型须先验证再拍板。
**Q：让我写 API 文档 / README / 部署手册，是不是写完就行？**
A：不是。文档、注释、规范属于"代码可读性的延伸"，**不得替代代码验证**。写文档前须先确认对应代码已实现并跑通（至少 `lint` + 关键路径自测）；文档里的接口签名、参数、返回值必须与真实代码一致，禁止凭假设补文档。文档发布须带回滚方案与发布/运维步骤（详见 `doc-generation`：文档不得替代验证、发布须含回滚与运维步骤）。
**Q：先写 Spec（需求/设计文档）再写代码，Spec 本身需要验证吗？**
A：需要。Spec 驱动开发走 `spec-driven-development` 五步（意图→边界案例→Requirements→Design→Tasks），编码前须过「第六步：编码前 Spec 验证」：逐条 Requirements/Scenario 与真实代码/接口 trace 核对，确认可实现、无歧义才进编码。Spec 与实现脱节（写完 Spec 不校验就编码）会在后期返工，且违反 Step 4 验证前提。
**Q：技术选型（该用哪个框架/库）能直接拍板吗？**
A：不能。涉及技术选型须走 `tech-selection`：先列候选与决策维度（团队/生态/长期维护/迁移成本），给出可撤销建议并说明假设，而非凭偏好下结论；选型结论须记录到项目记忆的 Decision Record 以便回滚（见 十二、与 `tech-selection`）。
## 十四、JavaScript / Node.js 专项（javascript-development）
> **本节要点**：JS 走 node --check 四步；PHP 内联 JS 须额外三道校验（`php -l` 对 JS 无感）。
**Q：JS/Node.js 项目能用 `@javascript-development` 显式调用吗？**
A：不能。`javascript-development` 与 Laravel、Java 同属「专项 reference 映射」，只作领域协同资料按需加载，不进 `@` 显式调用索引、不计入 19 子技能（见 七、Q5）。命中 JavaScript/Node.js/ES6/JS 代码检查/JS 风格规范/PHP 内联 JS 等关键词时自动加载。
**Q：JS 项目代码质量怎么验？**
A：走 `javascript-development`「代码质量检查流程」4 步：① 确认 Node.js 运行时版本（需 >= 15，推荐 18+）→ ② `node --check` 语法检查（利用 Node.js 内置语法解析器，不执行代码）→ ③ 全角符号自动修复（ESLint `--fix` 或按映射手动替换）→ ④ `node -e` 可执行性验证（验证修复后脚本可被 Node.js 正常加载并运行）。验证后再用 `code-review` 加载 JS 代码风格规范 47 条规则做静态审查。Node.js 版本未达 15 必须升级或在 README/CLAUDE.md 标注兼容范围。⚠️ 若 JS 写在 **PHP 文件内联**（混 `` 与 HTML、`onclick="..."` 事件属性、`window.open` 弹窗居中），`php -l` 对 JS 完全无感，必须额外走 `javascript-development`「CMS / PHP 内联 JS」三道强制校验：HTML 事件属性引号配对、window.open features 串非空收尾、批量改造后全仓逐条 Node 校验。
**Q：JS 风格走哪个规范？**
A：默认走 `javascript-development`「JS 代码风格规范」节，47 条规则 8 分类，按优先级 CRITICAL > HIGH > MEDIUM > LOW：Module/Language/Type Safety/Naming/Control Flow/Functions/Objects/Formatting。核心约束：const 优先（永远不 var）、ES module 优先（不用 require）、class 优先于原型操作、严格相等（==/!= 仅用于 null 检查）、显式分号、不修改内置原型、不用 eval。项目特殊规范存在时以项目为准，但禁止与 CRITICAL 级冲突。
**Q：JS 代码有全角符号/中文标点怎么修复？**
A：走 `javascript-development`「代码质量检查流程」第 3 步：全角符号修复用 ESLint `--fix` 自动修复，或手动将全角符号替换为半角（`，`→`,`、`。`→`;`、`！`→`!`、`？`→`?`、`：`→`:`、`「`/`」`→`"`、`（`/`）`→`(`/`）`）。常因来源内容含中文标点、复制粘贴编码异常触发。修复后必须重新跑 `node --check` 验证语法，再执行确认逻辑未改坏。
## 十五、Hooks 自动守卫（hooks.json）
> **本节要点**：15 个可选护栏；两种启用；hooks 不能替代 Agent 验证（动态/业务正确性仍须显式证据）。
**Q：技能自带的 hooks 是什么，怎么启用？**
A：本技能在 `hooks.json` 中声明了一组**通用示例**守卫钩子（共 15 个：PreToolUse 3 + PostToolUse 11 + PreCompact 1），覆盖写前/写后/压缩三类时机，对全部子技能与 JS 专项共用。启用方式：把 `hooks.json` 接入你的 Agent 运行时（具体见各 IDE 的 hooks 配置入口），并设置两个环境变量——`PYTHON_BIN`（Python 解释器路径）与 `HOOKS_DIR`（hook 脚本目录，可指向技能自带 `hooks/` 或你项目的 `.codebuddy/hooks/`）。`hooks.json` 内命令串用 `{{PYTHON_BIN}} "{{HOOKS_DIR}}/xxx.py"` 占位符，加载时由运行时替换为真实路径，不写死任何机器路径。
**Q：hooks 守卫具体做哪些检查？**
A：共 15 个钩子，分三组：
- **PreToolUse（写前，3 个）**：`backup_on_write`（写/改已存在源码前自动备份为 `.bak`，保留最近 3 个历史版本 `.bak` / `.bak.1` / `.bak.2`）、`guard_dirs`（拦截对数据/依赖目录的写操作）、`plan_guard`（改核心目录前强制要求存在进行中的 `*_plan.md`）。
- **PostToolUse（写后，11 个）**：`lint_on_write`（写 PHP 后语法自检）、`php8_compat`（PHP 8.x 兼容扫描）、`security_scan`（安全红线静态扫描，对齐 Rules §5）、`secret_scan`（敏感信息扫描，对齐 §5/§19）、`utf8_check`（UTF-8 合法性校验）、`debug_residue`（调试残留扫描）、`select_star`（裸 `SELECT *` 扫描）、`dep_scan`（依赖漏洞扫描提示）、`sql_injection_check`（SQL 注入检测，覆盖 PHP/Python/JS/Java 拼接模式）、`cms_risk_check`（CMS/框架风险检测，覆盖 18 种 CMS/框架 SQL 注入 + 13 种框架特有风险）、`capture_learning`（学习捕获：监听工具输出错误信号与用户输入纠错句式，命中即回显「建议记录到 error-ledger」提醒，非阻塞、不自动写文件，与前面 10 个防护型 hook 互补——详见 `error-ledger.md`）。
- **PreCompact（压缩前，1 个）**：`handoff_snapshot`（压缩/交接前生成检查点快照，保障长任务可恢复）。
**Q：hooks 能替代 Agent 自己的验证吗？**
A：不能。hooks 是**强制护栏**，只兜底机械项（备份、lint、PHP8 兼容、安全/脱敏、UTF-8、调试残留、SELECT \*、压缩快照、规划拦截、受保护目录写前拦截）；动态/业务正确性（如真实运行、端到端验证）仍须 Agent 显式产出证据链。hooks 拦截即视为该防线未过，禁止绕过。若运行时无 hooks 集成，须回退到对应正文手动执行，不得留空白洞。
**Q：脚本路径报"找不到文件"怎么办？**
A：先确认 `HOOKS_DIR` 指向的目录里确有对应 `.py`（技能自带在 `dev-expert/hooks/`，或你复制到项目的 `.codebuddy/hooks/`）。示例 `hooks.json` 默认指向占位符，未设 `HOOKS_DIR` 或指向错误目录都会找不到脚本——这不是技能 bug，是部署变量未配置。
**Q：运行时不支持 `{{PYTHON_BIN}}` / `{{HOOKS_DIR}}` 占位符替换怎么办？**
A：用安装器预处理：运行 `python hooks/install_hooks.py`（自动探测 Python 路径和 hooks 目录），生成已替换占位符的 `hooks.installed.json`，直接接入运行时即可。支持 `--python-bin` / `--hooks-dir` 参数或 `PYTHON_BIN` / `HOOKS_DIR` 环境变量指定路径；`--in-place` 可原地覆盖（自动备份 `.bak`）。详见 README「方式 B：安装器预处理」。
**Q：不想用 hooks 了，怎么禁用 / 卸载？**
A：两种方式，按你想禁的范围选：① 运行时侧：在 IDE 的 hooks 配置里移除对 `hooks.json` / `hooks.installed.json` 的引用即可，脚本本身不动、下次想用再接回；② 脚本侧：删除 / 移走 `HOOKS_DIR` 指向目录里的对应 `.py`（只想禁某一项就删单个文件，如 `backup_on_write.py`）。hooks 是**可选增强**，不接也不影响子技能本身运行，只是少了机械护栏（备份 / lint / 安全扫描等）兜底——禁用后须自行用 `php -l`、人工审查等手段补上验证（见本节约上文「hooks 能替代吗」）。重装：重跑安装器 `python hooks/install_hooks.py` 或把 `hooks.json` 重新接入运行时。
**Q：`hooks.capture-draft.json` 和 `hooks.installed.json` 为什么是两个分开的文件，分别干嘛？**
A：两者类别和用途都不同，必须分开：
- **`hooks.capture-draft.json`（增量草案，源文件）**：单独放着"捕获 hook"的额外一段——它比 `hooks.json` 多了**一条 `UserPromptSubmit` 事件**（命令带 `--mode correction`，直接抓取你输入里的纠错句式，是信号最准的来源）。但 `UserPromptSubmit` **不是所有 IDE 都支持**，若写进主 `hooks.json`、在不支持的 IDE 上会因为"未知事件名"导致整份配置加载失败，所以这条只能**单列 opt-in**：你想用就单独把这段并入，不用就不影响主配置。它的 PostToolUse 项与 `hooks.json` 里的是重复的，真正多出来的是 `UserPromptSubmit` 那一段。
- **`hooks.installed.json`（安装产物，自动生成）**：是 `install_hooks.py` 把 `hooks.json`（或 `capture-draft.json`）里的 `{{PYTHON_BIN}}`/`{{HOOKS_DIR}}` 占位符替换成真实机器路径后的输出文件，可直接接入运行时。它和"源文件"是天然两类——合并了就又变回需要替换占位符的源状态了，所以不可能和源文件合二为一。
- 三者关系：`.json` = 手写主源、`capture-draft.json` = 可选附加源（多一路最准的纠错捕获）、`.installed.json` = 编译产物。日常只维护前两个源，第三个由安装器重跑覆盖（详见 README「三个 hooks 文件的关系」小节）。
## 十六、需求澄清与模块边界
> **本节要点**：复杂任务强制澄清（≤3 问）；模糊词走 Wayfinder；"目标+约束+验收"最省追问。
**Q：需求澄清门控什么时候触发？**
A：当意图三分法判定为「复杂任务」且满足任一触发信号（见 SKILL.md Step 1.5）时强制进入。信息查询和简单任务跳过门控。目的是把模糊形容词转为可验收标准，避免做完后发现理解不一致。
**Q：门控会问很多问题吗？**
A：最多 3 问——只问影响验收口径的关键缺口。假设能合理推断的用默认值并标注，让用户纠正而非从头问起。
**Q：大型模糊任务（如"帮我优化系统"）怎么处理？**
A：启动 Wayfinder 模式：先做现状快照→问题树展开→候选路径排序→最小探索动作→收敛为明确任务。不直接用"优化"这种模糊词进入实现。
**Q：模块边界审查什么时候做？**
A：在 software-project 第三步（架构方案）和第四步（Wave 拆解）之间。检查依赖方向/接口契约/数据持有/变更半径/术语一致性。循环依赖或数据归属冲突为阻塞级，必须在拆解前解决。
**Q：代码生成怎么会联动测试和审查？**
A：复杂任务（多模块/数据持久化/安全敏感）在代码生成第〇步自动决策是否联动 test-generation 和 code-review。单文件简单任务不联动，避免过度流程。
**Q：术语表（Glossary）是什么？**
A：当同一概念被多个名称指代时，project-memory-management 会自动记录规范名称到 `.ai-memory/project_memory.md` 的 Glossary 章节。后续会话恢复时会加载，确保 Agent 使用统一术语。新会话首次识别到术语漂移时会提醒用户。
**Q：快速原型需要画图吗？**
A：不需要高保真设计图。frontend-design 的二步点五用 ASCII 线框图快速对齐页面骨架和交互流。用户确认结构后再进入完整视觉设计，避免方向性返工。
**Q：哪些"模糊地带"系统会停下来问我，而不是自己定？**
A：典型模糊地带（命中即触发澄清，不会擅自动手）：
- **验收口径不确定**：如"做得好一点 / 快点 / 安全点"这类形容词，无量化标准 → 转成可验收标准再动手；
- **多解分支**：实现路径有 ≥2 种且影响不同（如分页用游标 vs offset）→ 问你偏好；
- **默认值有业务后果**：如"默认渠道 / 默认状态"选错会写错数据 → 高澄清级别先问；
- **范围边界**：任务是否包含某模块/某依赖（如"重构这段"要不要连带改调用方）→ 确认变更半径。
反之，纯信息查询、单行修复、可局部回退且目标明确的任务不会问，直接进快速通道（见 SKILL.md「自主度分级」）。
**Q：我不想被问太多，怎么一次性把信息给够？**
A：用「目标 + 约束 + 验收」三段式描述，能大幅减少追问：
- **目标**：要做什么（如"导出后台用户"）；
- **约束**：范围 / 格式 / 权限 / 性能等硬限制（如"按筛选条件、CSV、需鉴权限频"）；
- **验收**：怎么算做对了（如"能正确导出 1 万行且带表头"）。
三要素越齐，门控问得越少；缺哪块系统就只补问哪块（最多 3 问），其余用合理默认并标注让你纠正。这正对应十六、Q2「假设能合理推断的用默认值并标注」。
**Q：Wayfinder 探索和我直接给目标，区别在哪？**
A：当你只给"优化系统 / 帮我看看"这类过泛词时，系统不会莽撞动手，而是先走 Wayfinder：现状快照 → 问题树 → 候选路径排序 → 最小探索 → 收敛成明确任务，过程中可能回问你方向。若你已能给出较具体目标，则跳过探索直接路由，省去来回。即：**越具体越省事，越模糊越要先对齐**（见 十六、Q3）。
## 十七、交付保障与踩坑管理
> **本节要点**：SELF-AUDIT 16 条、收尾报告 5 字段、Graceful Abort、错误册 ERR-XXX、学习捕获三层闭环。
**Q：SELF-AUDIT 执行率自检是什么？什么时候触发？**
A：交付前强制执行（收口于 Step 5），16 条硬约束（E2E 条目/验收标准/安全/质量/性能/GATE-CHECK/轮次/构建/修改 checkpoints/回退/规划/图谱 G1/G2'/G3/架构自检/证伪）。任一 ❌ 回退对应阶段修复→重走 Step 4→复检，最多 3 轮；超出后列未修复项+原因+选项，不阻塞交付。详见 `delivery-assurance.md`「执行率自检」。
**Q：收尾报告长什么样？**
A：固定 5 字段格式：`完成度: X% | 主线: {状态} | 产出: {摘要} | 待办: {内容/无} | 下一步: {建议/无}`。禁止自由格式，必须有验证可追溯。详见 `delivery-assurance.md`「收尾报告模板」。
**Q：任务中途我想中止怎么办？**
A：走 Graceful Abort 流程：输出中止声明→保留 `.bak` / `.bak.1` / `.bak.2` 备份→_plan.md 标注中断点→清理临时脚本（不删 .bak）→简化收尾。恢复时从 handoff.md 或 \_plan.md 中断点继续，回滚则倒序 `.bak` 恢复（`.bak` 为最新备份，`.bak.1` 次之，`.bak.2` 最旧）。详见 `delivery-assurance.md`「Graceful Abort」。
**Q：确认超时了会怎么处理？**
A：通用确认 5 分钟无回复→最保守/安全选项自动推进；破坏性操作（DDL/删除/覆盖/批量写）→默认取消；规划确认→默认推进；安全相关→一律等明确回复。详见 `delivery-assurance.md`「确认超时默认规则」。
**Q：踩坑错误册（ERR-XXX）怎么用？**
A：索引表 `error_index.md` + 单条 `errors/ERR-XXX.md`。Bug 诊断/审查/重构 session 启动时先用正则/关键词匹配索引的触发关键词，命中则读对应 ERR-ID 全文复用修复方式。新坑排查耗时 ≥ 40 分钟→强制分配 ERR-ID+写单条+更新索引+同步 project_memory Known Issues。详见 `error-ledger.md`。
**Q：新加的「学习捕获」钩子是怎么让技能自我改进的？**
A：分三层闭环，但本技能**不自动改写自身规则**（避免越权）：① **捕获**（`capture_learning.py`，挂 PostToolUse）：监听工具输出的错误信号（Parse error / PHP Fatal / 断言失败 / GATE-CHECK 不足等）+ 你输入里的纠错句式，命中即回显「建议记录到 error-ledger」提醒——非阻塞、`exit 0` 仅提醒、不自动写文件；② **沉淀**（`error-ledger.md`）：你按提醒把坑记成 `errors/ERR-XXX.md`（含 `Recurrence-Count`/`Tasks` 等字段），形成可复用知识库；③ **提升**（`recurrence_promote.py`）：解析单条错误册，当某坑 `Recurrence-Count≥3 且 Tasks≥2 且 30 天窗口`内反复出现，输出「建议升规则」提示——由你确认后才写入项目规则文件（用 `--target` 指定落点），不擅自改。简言之：**捕获提醒 → 你记录 → 高频坑经你确认升级为规则**，闭环靠人把关，Agent 不自我改规则（详见 `error-ledger.md` 与 `hooks/capture_learning.py` / `hooks/recurrence_promote.py`）。
**Q：批量修改很多文件时有什么安全保障？**
A：触发"批量修改 7 防线"（≥ 3 文件或 ≥ 10 处修改点）：预检 lint→试点 3-5 文件→备份 `.bak`（保留最近 3 个历史版本）→逐文件执行+日志→后检 lint→MD5 对比→回读确认。ROLLBACK > 20% 整批回退。详见 `execution-safety.md`「批量修改 7 防线」。
## 十八、子技能组合与触发进阶
> **本节要点**：组合自动发生、不用手拼；正确姿势"先审查后重构"（审查只读）；附一句话触发对照表。
### 能力边界：多个子技能能不能同时用、怎么配合？
> 先说清一件事：**组合是自动的，不用你手动编排。** 你只需把完整目标说清（如"实现导出功能并出接口文档"），系统按领域路由表 + 优先级矩阵自动串联所需子技能，你不必显式点名谁先谁后。下面内容仅供你想了解内部协作方式、或在自动结果不符预期时手动微调。
**Q：我想"代码审查 + 重构"一起做，可以吗？**
A：可以组合，但正确姿势是「先审查、后重构」，不是在同一份代码上同时改。这通常是**系统自动按"治理阶段"路径串联**的，你也可以显式用 `@code-review` + `@refactoring` 精确控制：
- 代码审查（`@code-review`）按「审计修复分离」规则是**只读**的：只输出分级问题清单（Bug / 安全 / 性能 / 坏味道）和修复建议，**不默认改写实现**（见 SKILL.md 代码审查 协同 `refactoring` 的边界注记"以发现问题为主，不默认重写实现"）。
- 重构建议（`@refactoring`）负责把审查发现的问题落地为具体重构步骤；它同样要求"未建立验证路径前不得扩大重构范围"。
- 推荐配合链路：先 `@code-review` 出报告 → 你确认要修哪些 → 再 `@refactoring`（或代码生成）按报告逐条改 → 改完可再跑一次 `@code-review` 验收。这正是 README「协同技能」里的"治理阶段：Bug诊断/重构建议 → 代码审查 → …"路径。
- 注意互斥提示：如果你 `@code-review` 却说"帮我重写/实现这段"，系统会提示"任务更像代码生成，是否切换？"——因为审查 ≠ 改写。要改写必须走重构/生成分支并先确认（见 一、Q2 的任务-技能不匹配提示表）。
**Q：还有哪些常见的"组合套餐"？**
A：这些都是**系统自动触发**的例子（你一句话说清目标即可，无需手动拼）。完整「一句话触发对照表」（写功能+测试 / 修报错+审查 / 先定位瓶颈再重构 / 审查完再重构 / 写功能+顺带文档 等高频组合）见 README「一句话触发对照表」，系统按优先级矩阵自动串联，无需你手动拼。
**Q：组合时会不会超出 reference 加载上限？**
A：会受"单次最多加载 3 个 reference"约束（SKILL.md 对话流异常处理边界 → 过度路由）。当一句话挂了过多子技能时，系统回到意图三分法，只保留首选 + 必要协同，其余提示你分阶段做，不会一股脑全加载。
### 触发方式：不知道功能名字 / 想组合两个，怎么说才命中？
**Q：我想要某个能力，但不知道它叫"代码审查"还是别的名字，怎么说？**
A：直接**描述目标/动作**，不必背名字。路由表同时匹配「子技能名」和「功能说明里的场景词」：
- "帮我看看这段代码有没有问题 / 安不安全" → 命中 代码审查（无需知道 `@code-review` 这个名字）
- "这段逻辑太绕了，理一理结构" → 命中 重构建议
- "写个能跑的接口，最好带参数校验" → 命中 代码生成
- 实在不确定，用最上层的 `@<英文标识>` 显式指定（见 七、）；拿不准标识就直接描述，系统按关键词 + 意图三分法路由，命中不了会向你确认意图（不会乱猜）。
**Q：我想同时用两个功能，怎么一句话表达才不跑偏？**
A：两种稳妥表达：
1. **顺带式**："做 A，并 / 顺带 / 再帮我做 B"——如"帮我实现导出功能，顺带生成接口文档"。系统按优先级矩阵组合路由（A 为主、B 为协同）。
2. **显式点名式**：用多个 `@` 标识，如"`@code-review` 先审一遍，`@refactoring` 再按问题重构"。显式调用只跳过路由匹配、不影响协同加载（见 七、Q2）。
- 反例（易跑偏）：只说"帮我优化一下"这类模糊词 → 触发 Wayfinder 探索而不是直接动手；想精准组合就用上面两种明确表达。
- 若两个功能明显冲突（如"审查但不许改" vs "直接重写"），系统会按「任务-技能不匹配提示」表问你确认（见 一、Q2 / SKILL.md Step 1.2），不会擅自二选一。
### 常见模糊需求 → 会命中哪个子技能（速查，专治"怕说错"）
不知道功能叫啥、怕描述模糊触发错？下表把**口语化模糊需求**直接映射到子技能，照着说基本不会偏：
| 你说的（模糊表达） | 实际命中子技能 | 备注 |
| --------------------------------------- | ------------------------- | -------------------------------- |
| "帮我看看这段代码有没有问题 / 安不安全" | 代码审查 | 无需知道 `@code-review` 这个名字 |
| "这段逻辑太绕了，理一理结构" | 重构建议 | |
| "写个能跑的接口，最好带参数校验" | 代码生成 | |
| "这个报错帮我修一下" | Bug诊断 | |
| "帮我写份 API 文档 / README" | doc-generation | 文档签名须与真实代码对齐 |
| "给我做个网站 / 落地页" | frontend-design | |
| "数据库慢查询怎么优化" | mysql-database | 常与性能基准测试协同 |
| "CMS 二次开发（帝国/WordPress/PHP8）" | cms-development | 先确认 CMS 类型再生成 |
| "技术选型用哪个框架/库" | tech-selection | 不凭偏好拍板，给可撤销建议 |
| "长任务 / 导入导出接口怎么设计" | api-design | Init→Step→Poll 防卡死 |
| "让我做个 PPT / Word 报告" | 依 docx/pptx 等 reference | 关键词触发 |
| "帮我管一下项目记忆 / 交接" | project-memory | |
**Q：我怕说错导致选错技能，怎么办？**
A：三点打消顾虑，基本"选错无后果"：
1. **路由表同时认"名字"和"场景词"**：描述目标比背名字更稳；真命中不了，系统会向你确认意图，不会乱猜（见 一、Q1）。
2. **显式指定错了也会被拦**：即使你 `@xxx` 指定错，系统检测到强冲突会提示"任务-技能不匹配"，你回复后切换，绝不擅自二选一；回复"按原指定执行"则立刻按你指定的走（见 一、Q2）。
3. **组合类用"做 A，顺带 B"句式**：A 为主、B 为协同，不必精确排序（见上「触发方式」两种稳妥表达）。
结论：**怕选错就描述目标，系统要么命中、要么问你一句、要么提示冲突——不会偷偷用错技能干完。**
### 实战演练：一个"需要澄清 + 组合技能"的真实任务
下面用一条完整链路演示系统如何走（你只需看"输入 → 系统行为"，不必背流程）：
> **你的输入**："我想给后台加个导出用户的功能，要快；顺带把接口文档也出了。"
1. **路由**：关键词"导出 + 功能 + 后台" → 命中 `代码生成`（主）+ `cms-development` / `api-design`（协同）。「顺带出文档」触发 `doc-generation` 协同加载。
2. **澄清门控触发**（因为是"写功能 + 涉及数据库/权限"的复杂任务，见 十六、Q1）：最多问你 3 个关键缺口，例如：
- 导出范围：全部用户，还是按条件筛选？
- 输出格式：CSV / Excel / JSON？
- 是否要鉴权 + 限频（防批量拖库）？
- 能合理推断的（如"UTF-8 编码"）用默认值并标注，不重复问。
3. **你回答后进入实现**：先给方案（表/字段、接口签名、回滚路径）→ 你确认 → `代码生成` 落地 → `lint` 验证证据。
4. **组合收尾**：`doc-generation` 产出的文档签名与你真实代码对齐，禁凭假设补接口（见 十三、Q1）。
5. **交付**：收尾报告含完成度 + 验证证据（lint/运行输出），未验证项不隐藏（见 十七、Q2）。
**要点**：你不需要背这套流程，只要把「目标 + 关键约束（范围/格式/权限）」说清，剩下的路由、门控、组合由系统按规则补齐。
### 一句话触发对照表（深入用法速查）
| 你想做的事 | 一句话怎么说（命中即组合） | 触发链路 |
| ----------------- | ------------------------------------------------ | --------------------------------- |
| 写功能 + 顺带测试 | "实现登录接口，并生成单元测试" | 代码生成 + 测试用例生成 |
| 修报错 + 顺带审查 | "定位这个报错，顺带看看附近有没有安全隐患" | Bug诊断 + 代码审查 |
| 先定位瓶颈再重构 | "这个列表很慢，先帮我定位瓶颈再重构" | 性能基准测试 + 重构建议（先基线） |
| 审查完再重构 | "`@code-review` 先审，`@refactoring` 再按问题改" | 代码审查(只读) → 重构建议 |
| 写功能 + 顺带文档 | "加个导出功能，顺带生成接口文档" | 代码生成 + doc-generation |
## 十九、常见技能实际代码示例（可直接抄用）
> **本节要点**：5 段可直接抄的真实代码（PDO 预处理 / PHP8 修复 / 审查报告 / 内联 JS 居中 / handoff 检查点）。
上面各节偏步骤与模板；这里补几段**真实可运行**的代码片段，对应高频技能，照抄即可落地。每条都锚定前文规则出处。
### A. 数据库写入：PDO 预处理（替代直拼 SQL）
```php
// ❌ 直拼（注入风险，违反 二、执行禁区）
$id = $_GET['id'];
$sql = "SELECT * FROM user WHERE id = $id";
// ✅ 预处理（mysql-database 规范）
$stmt = $pdo->prepare("SELECT * FROM user WHERE id = ?");
$stmt->execute([$id]);
$row = $stmt->fetch(PDO::FETCH_ASSOC);
```
> 补充：`IN` 用 `IN (?,?,?)` 占位；`ORDER BY` 走白名单映射；`LIMIT` 转 int；任何 UPDATE/DELETE 必须带 `WHERE` 并先 `SELECT` 验证影响行数（见 十、Q1）。
### B. PHP8 兼容：两个高频修复
```php
// ❌ 数组键无引号 + fetch1 返 false 未守卫（PHP8 告警/致命）
$row = $db->fetch1("SELECT * FROM news WHERE id=1");
echo $row[id]; // Undefined array key（PHP8 报 warning）
echo $row['title']; // 若 $row 为 false → 致命错误
// ✅ 加引号 + false 守卫（php8-compat）
$row = $db->fetch1("SELECT * FROM news WHERE id=1") ?: [];
echo $row['id'];
echo $row['title'] ?? '';
```
> 其余 PHP8 项：短标签 ` 这正是 十八、所述「审计修复分离」：审查是只读的，要改写须走重构/生成分支并先确认。
### D. PHP 内联 JS：window.open 弹窗居中（Node 校验 + 正确写法）
```html
```
> 校验：`node --check` 对纯 JS 有效；**PHP 文件内联 JS，`php -l` 完全无感**，须把这段 JS 抽出来用 Node 单独跑（见 十四、Q2「CMS / PHP 内联 JS」）。
### E. 长任务检查点（handoff.md 实际内容）
```markdown
# 交接快照 handoff.md
## 已完成（带验证证据）
- 导出接口 POST /api/export ✅ php -l 通过 + curl 返回 200 + 1 万行 CSV
## 未完成
- 导出限频未加（待你确认阈值）
## 阻塞
- 无
## 下一步
- 补限频 → 重跑 lint → 交付
```
> 每完成一个 Wave 或累计 5 个原子任务落一次，跨会话/换电脑读它即可无损续做（见 九、Q"进度会丢吗"）。
## 二十、新手高频疑问补遗（问答覆盖查漏）
> **本节要点**：新手常问（纠正/回滚/中文/省 token/第一步/产出在哪），前面没落点的都收在这里。
本节能级收口"前面章节没专门答、但新手常问"的问题，避免"有些疑问找不到答案"。
**Q：它是不是理解错了我的需求？怎么纠正？**
A：两种方式。① 即时纠正：直接说"不对，第 X 行应该 Y 而不是 Z"——系统按你的纠正重做并复跑验证，不辩解。② 若纠正涉及一个反复踩的坑，会触发"学习捕获"提醒你记入错误册（见 十七、Q"学习捕获钩子"），下次同类问题自动复用正确做法。纠正不会被当成"拒绝合作"，放心提。
**Q：它改错了 / 我想撤销某次改动，怎么回滚？**
A：改动前 hooks 已自动备份为 `.bak`（`backup_on_write`，保留最近 3 个版本 `.bak`/`.bak.1`/`.bak.2`）。回滚：把 `.bak` 复制回原文件名即可恢复上一版，`.bak.1`/`.bak.2` 是更早版本。若任务进行中中止，走 Graceful Abort：`.bak` 保留、plan 标中断点，恢复时从 `handoff.md` 或 `.bak` 倒序恢复（见 十七、Q"任务中途想中止"）。注意：`.bak` 是唯一的回滚点，**不要手动删 `.bak`**。
**Q：支持中文吗？我的代码/注释是中文的。**
A：支持。本技能面向中文开发者，输入用中文即可；代码注释、标识符、报错信息均按中文语境处理。唯一的编码红线是：**不要用 Shell 直接写中文/UTF-8 文件**（易乱码），交给 Edit/Write 工具或 Python `open(encoding='utf-8')` 处理（见 二、禁区 / 五、反模式）。
**Q：我口头纠正它，算不算"反馈让它变好"？**
A：算，但分两层。即时纠正只影响本次；若想"下次自动更准"，需把坑记入错误册（ERR-XXX，见 十七、Q"踩坑错误册"），或经你确认后由 `recurrence_promote.py` 升为规则。单纯口头说一句不会自动改写技能自身规则——闭环靠人把关（详见 十七、Q"学习捕获钩子"）。
**Q：会不会很耗 token / 上下文？怎么省？**
A：三道机制控成本：① 上下文延迟加载——只加载当前任务所需文件，不预读全库（见 SKILL.md「上下文延迟加载协议」）；② 单次最多加载 3 个 reference，过度路由自动回退（见 三、/ 一、Q4）；③ 单日日志超 8000 字符提醒精简、超 12000 强制蒸馏（见 十二、Q"旧日志怎么清理"）。省 token 的实操：**需求一次说清（目标+约束+验收）**，少来回追问最划算。
**Q：新手第一步该做什么？**
A：不用学规则。① 打开 README「3 分钟上手」+「需求表达完整示例」，照着抄一句需求即可；② 不确定能不能做、会不会踩坑，先扫一眼 README「上手前先扫一眼红线」或 FAQ「能力边界速览」；③ 真遇到报错/卡住，去 FAQ「普通人可读版」按"你遇到的情况"对号入座。规则是给 Agent 看的，你只需把目标说清。
**Q：它生成的东西在哪看？输出会跑哪里去？**
A：两类产出。① 代码/文件类：直接写到你项目对应路径（改动前有 `.bak` 备份）；② 报告/清单类：在对话里输出（如代码审查清单、审计结论、收尾报告）。每次交付含「变更摘要 + 验证证据 + 收尾报告」，你据收尾报告即可定位改了哪些文件（见 十七、Q"收尾报告长什么样"）。