常见问题答疑（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：要求输出普通人可读版。标准格式是：

发生了什么：[一句话解释]
可能原因：[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 文件内联（混 <?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：两种稳妥表达：

顺带式："做 A，并 / 顺带 / 再帮我做 B"——如"帮我实现导出功能，顺带生成接口文档"。系统按优先级矩阵组合路由（A 为主、B 为协同）。
显式点名式：用多个 @ 标识，如"@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：三点打消顾虑，基本"选错无后果"：

路由表同时认"名字"和"场景词"：描述目标比背名字更稳；真命中不了，系统会向你确认意图，不会乱猜（见一、Q1）。
显式指定错了也会被拦：即使你 @xxx 指定错，系统检测到强冲突会提示"任务-技能不匹配"，你回复后切换，绝不擅自二选一；回复"按原指定执行"则立刻按你指定的走（见一、Q2）。
组合类用"做 A，顺带 B"句式：A 为主、B 为协同，不必精确排序（见上「触发方式」两种稳妥表达）。结论：怕选错就描述目标，系统要么命中、要么问你一句、要么提示冲突——不会偷偷用错技能干完。

实战演练：一个"需要澄清 + 组合技能"的真实任务

下面用一条完整链路演示系统如何走（你只需看"输入 → 系统行为"，不必背流程）：

你的输入："我想给后台加个导出用户的功能，要快；顺带把接口文档也出了。"

路由：关键词"导出 + 功能 + 后台" → 命中 代码生成（主）+ cms-development / api-design（协同）。「顺带出文档」触发 doc-generation 协同加载。
澄清门控触发（因为是"写功能 + 涉及数据库/权限"的复杂任务，见十六、Q1）：最多问你 3 个关键缺口，例如：
- 导出范围：全部用户，还是按条件筛选？
- 输出格式：CSV / Excel / JSON？
- 是否要鉴权 + 限频（防批量拖库）？
- 能合理推断的（如"UTF-8 编码"）用默认值并标注，不重复问。
你回答后进入实现：先给方案（表/字段、接口签名、回滚路径）→ 你确认 → 代码生成 落地 → lint 验证证据。
组合收尾：doc-generation 产出的文档签名与你真实代码对齐，禁凭假设补接口（见十三、Q1）。
交付：收尾报告含完成度 + 验证证据（lint/运行输出），未验证项不隐藏（见十七、Q2）。

要点：你不需要背这套流程，只要把「目标 + 关键约束（范围/格式/权限）」说清，剩下的路由、门控、组合由系统按规则补齐。

一句话触发对照表（深入用法速查）

你想做的事	一句话怎么说（命中即组合）	触发链路
写功能 + 顺带测试	"实现登录接口，并生成单元测试"	代码生成 + 测试用例生成
修报错 + 顺带审查	"定位这个报错，顺带看看附近有没有安全隐患"	Bug诊断 + 代码审查
先定位瓶颈再重构	"这个列表很慢，先帮我定位瓶颈再重构"	性能基准测试 + 重构建议（先基线）
审查完再重构	"`@code-review` 先审，`@refactoring` 再按问题改"	代码审查(只读) → 重构建议
写功能 + 顺带文档	"加个导出功能，顺带生成接口文档"	代码生成 + doc-generation

十九、常见技能实际代码示例（可直接抄用）

本节要点：5 段可直接抄的真实代码（PDO 预处理 / PHP8 修复 / 审查报告 / 内联 JS 居中 / handoff 检查点）。

上面各节偏步骤与模板；这里补几段真实可运行的代码片段，对应高频技能，照抄即可落地。每条都锚定前文规则出处。

A. 数据库写入：PDO 预处理（替代直拼 SQL）

// ❌ 直拼（注入风险，违反 二、执行禁区）
$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 兼容：两个高频修复

// ❌ 数组键无引号 + 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 项：短标签 <?→<?php、each()/create_function() 替换、?? 优先级加括号、class_exists() 第二参数（见十一、Q"CMS 二次开发"）。

C. 代码审查（@code-review）只读报告长什么样

[代码审查报告] src/Order.php
- [Bug]     L42  未校验 $qty 上限，可传负数导致库存为负
- [安全]    L88  直拼 SQL，存在注入（见 mysql-database）
- [性能]    L120 循环内逐条 SELECT，建议批量 IN 查询
- [坏味道]  L15  函数 80 行，建议拆 init / calc / final
建议：先修 [安全][Bug]，再据报告走 @refactoring。
（本技能只出清单，不自动改写；确认后再改）

这正是十八、所述「审计修复分离」：审查是只读的，要改写须走重构/生成分支并先确认。

D. PHP 内联 JS：window.open 弹窗居中（Node 校验 + 正确写法）

<!-- ❌ features 以空串结尾 → 浏览器报 SyntaxError -->
<button
  onclick="window.open(u,'','width=600,height=400,left='+(screen.width-600)/2)"
>
  打开
</button>

<!-- ✅ 坐标用 Math.floor 包裹，末尾真实非空串 -->
<button
  onclick="window.open(u,'','width=600,height=400,left='+Math.floor((screen.width-600)/2)+',top='+Math.floor((screen.height-400)/2)+',scrollbars=auto,resizable=yes')"
>
  打开
</button>

校验：node --check 对纯 JS 有效；PHP 文件内联 JS，php -l 完全无感，须把这段 JS 抽出来用 Node 单独跑（见十四、Q2「CMS / PHP 内联 JS」）。

E. 长任务检查点（handoff.md 实际内容）

# 交接快照 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"收尾报告长什么样"）。

FAQ.md 68 KB Permalink Cronologia Originale