fmode-app/.agents/skills/dev-expert

编程专家 - dev-expert

一个覆盖编程全生命周期的 AI 编程助手：说需求，它自动选对工具并组合执行，你不必记任何名字。

                    _ooOoo_
                   o8888888o
                   88" . "88
                   (| -_- |)
                   O\  =  /O
                ____/`---'\____
              .'  \\|     |//  `.
             /  \\|||  :  |||//  \
            /  _||||| -:- |||||-  \
            |   | \\\  -  /// |   |
            | \_|  ''\---/''  |   |
            \  .-\__  `-`  ___/-. /
          ___`. .'  /--.--\  `. . __
       ."" '<  `.___\_<|>_/___.'  >'"".
      | | :  `- \`.;`\ _ /`;.`/ - ` : | |
      \  \ `-.   \_ __\ /__ _/   .-` /  /
 =====`-.____`-.___\_____/___.-`____.-'=====
                    `=---='
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          佛祖保佑       永无BUG

🚀 第一次用？只看这段：直接说你的目标（如"帮我给后台加个导出按钮"），路由、组合、验证它全包了；只有"报错 / 不确定能不能做"时才需要查 FAQ。

📌 TL;DR（30 秒速览）

• 是什么：19 个子技能的全链路编程助手；说需求即自动匹配 + 自动组合，无需记名字。
• 怎么用：自然对话说目标（带"目标+约束+验收"最省事）；边界/报错查 FAQ。
• 护栏：hooks 是可选增强（备份/lint/安全）；红线（直拼 SQL、盲写库、跳过验证）踩了被拦。
• 深入：专项细节在 references/*.md，本文件只给入口与导航。
• 知识图谱：@project-knowledge-graph 纯正则建依赖图，查询近零 LLM token（见附录 A）。

⚠️注意

本技能的目的是跨工具实现快速迁移，工具不好用就换！别想用工具黏上你的工作流和习惯！你可以随意的切换使用工具并保证你的进度保持同步不被任何工具绑定 你的进度 规范 踩坑错误册 图谱 编排进度 都可以快速的随你的工具任意迁移而不被任何工具束缚！ hooks 和 scripts（知识图谱)属于高级进阶功能，须Agents根据自身规则适配才能使用，非开箱即用功能！

为什么保留渐进式路由（而非一步直达）

你可能会问：既然"说需求即自动匹配"，为什么 SKILL.md 还要保留 @显式调用 → 关键词 → 领域路由表 → 优先级矩阵 → 意图三分法 这套多层、逐级收窄的渐进式路由，而不是直接让模型凭一句话判断进哪个子技能就执行？

因为渐进式路由不是单纯的"分类器"，而是六步闭环工作流（Step 0–6）的入口分发轨道——它的每一层输出都挂着后续的一道门。抛离路由等于拆掉轨道：模型仍会"做事"，但流程会从中间断裂，丢失可验证、可恢复、可审计的保证。

路由层	它挂接的后续步骤（不抛离的原因）
@显式 / 关键词 / 领域路由表	命中结果决定加载哪个 reference 主模板，模板里的澄清门控、验证证据、SELF-AUDIT 清单才有挂载点
领域路由表的「路由边界」列	提前识别"不在本技能范围"的请求（用户调研 / 排期 / 容器编排 / 安全深度扫描），只做边界说明不硬覆盖
优先级矩阵（40+ 行「X+Y」场景）	决定组合协同顺序（先审查后重构、先基线后对比、CMS 规范优先于代码生成），无此则组合失据
意图三分法（信息查询 / 简单任务 / 复杂任务）	决定走快速通道还是先方案确认——安全闸门的触发点就在这里，抛离会跳过生产配置 / DB 写入的事先确认

如果完全抛离、改为一步直达，会同时丢掉四道关：Step 1.5 澄清门控（模糊形容词直接动手，做完才发现理解不一致）、Step 2 安全闸门（DB / 生产配置未确认即执行）、Step 4 验证证据 + Step 5 SELF-AUDIT（无证据交付）、长任务 handoff / Wave 的主模板锚点（上下文压缩后无法无损续做）。

一句话：渐进式路由保的是"工作流不断裂"——可验证、可恢复、可审计的闭环都挂在它上面。你描述目标时感觉不到它，是因为它已经在后台把每道门按顺序挂好了。

那为什么 SKILL.md 显得很大？ 不是路由本身臃肿，而是同一份文件把"分发轨道 + 闭环步骤 + 护栏边界"三件必须共存的东西压在了一起：

• 闭环步骤是硬骨架：Step 0 记忆加载 → Step 1 意图路由 → Step 1.5 澄清门控 → Step 2 规划门禁 → Step 3 执行（7 防线）→ Step 4 验证证据 → Step 5 交付 + SELF-AUDIT → Step 6 复盘沉淀。每一步都不能省，否则闭环断一节。
• 路由是轨道、护栏是闸：路由表 / 领域路由表 / 优先级矩阵 / 意图三分法负责"分发"，安全闸门、失败重试基线、对话流异常边界、子 Agent 边界、长任务可靠性负责"兜底"——它们必须和步骤写在同一份运行时指令里，模型加载 SKILL.md 时才一次拿到全部门控。
• 为什么没拆进 references：references/ 下 28 个文件是"各子技能的详细模板"，而 SKILL.md 是"总控流程 + 跨步骤门控"。门控若拆出去，模型要先跳读多个文件才知道哪步该停，反而增加断裂风险。所以 SKILL.md 故意"大而全"，references 才"专而深"。

简言之：大是为了不断裂——闭环骨架 + 分发轨道 + 兜底护栏都必须在同一次加载里齐备，拆散反而会让模型在某步"忘了该不该停下"。真正会被按需懒加载的细节，都在 references/ 里，不用一次读完。

子技能列表

本节要点：19 个子技能一表速览，说需求即自动匹配，不必背名字。

子技能	功能	触发关键词
软件项目总控	通用软件项目从需求到交付的总控：边界、行为契约、架构、数据/API/集成、测试、安全、发布、回滚、监控、告警、巡检和沉淀	软件项目, API服务, 后端服务, 后台模块, CLI工具, 数据脚本, 自动化任务, 插件项目, 完整功能, 项目交付, 部署, 发布, 回滚, 运维, 监控, 告警, 巡检
网站项目总控	从需求到上线的建站项目总控：站点规划、内容SEO、前端设计、CMS/API/数据、测试安全、性能部署、验收运维	做网站, 建站, 企业官网, 营销页, CMS网站, 网站上线, 网站交付
API设计	根据业务需求设计RESTful或GraphQL API接口，长任务采用 Init-Step-Poll 契约	API设计, RESTful, GraphQL, 接口规范, AJAX防卡死, Init-Step-Poll, 长任务接口, 轮询接口
Bug诊断	分析错误日志和异常堆栈，定位Bug根因并给出修复方案	Bug诊断, debug, 报错, 异常堆栈
Karpathy编码规范	提供Karpathy核心编码哲学：思考优先、简洁至上	Karpathy编码规范, Karpathy, 编码哲学
Spec驱动开发	编码前对齐需求规格，使用OpenSpec artifact flow	Spec驱动开发, spec, 需求对齐
代码审查	审查代码质量，发现Bug、安全漏洞和代码缺陷	代码审查, code review, 代码缺陷
代码生成	根据功能需求生成高质量代码，含错误处理和边界条件	代码生成, 生成代码, 实现功能
任务拆解与执行	将复杂需求拆分为原子任务，按Wave分组执行	任务拆解与执行, 任务分解, Wave执行
技术选型	根据项目需求推荐合适技术栈、框架和工具	技术选型, 技术栈, 框架选型
文档生成	根据代码生成技术文档、README、API文档、部署说明和运维文档	文档生成, API文档, README, 部署说明, 回滚说明, 运维文档
测试用例生成	生成单元测试、集成测试、安全测试、性能测试和长任务测试	测试用例生成, 单元测试, 测试用例, 安全测试, 性能测试, 长任务测试
重构建议	分析代码结构，识别坏味道并提供重构方案	重构建议, 重构, 坏味道, 代码异味
项目记忆管理	捕获上下文和决策，实现跨会话项目记忆沉淀	项目记忆管理, 项目记忆, 跨会话
CMS二次开发	PHP+MySQL CMS 二次开发全链路：CMS探测/PHP版本/数据库规范/安全红线/插件开发/长任务防卡死	CMS, 帝国CMS, WordPress, ThinkPHP, PHP8兼容, 二次开发, 插件开发, 批量任务, 导入导出, 生成静态页
前端设计	UI/UX 与前端实现设计：设计思维、信息架构、视觉规范、品牌、Banner、图标、社媒图、响应式、可访问性、安全性、命名规范、目录规范、代码质量、ESLint基线、性能实现、浏览器验证、进度轮询	前端设计, UI设计, UX, 交互设计, 响应式, 设计系统, 前端安全, 命名规范, 目录规范, ESLint, 代码质量, 性能实现, 品牌设计, Banner, 图标, 社媒图, 进度条, 轮询状态
MySQL数据库	MySQL 数据建模、SQL安全、索引设计、事务边界、慢查询诊断、迁移回滚和数据安全	MySQL, 数据库设计, SQL, 索引, 事务, 慢查询, EXPLAIN, DDL, 迁移, 表结构, SQL优化
性能基准测试	量化性能验证：识别触发面、测量耗时/内存/吞吐量、生成瓶颈报告、优化前后A/B对比	性能测试, benchmark, 基准测试, 耗时分析, 内存分析, 吞吐量, QPS, 瓶颈分析, 性能对比
项目知识图谱	为项目自动构建代码结构依赖图谱（节点+依赖边），跨模块改动/重构/审查时查依赖闭包与影响面，agent 开发时借全局视角理解项目、定位更准改动更稳；纯 agent 受众，不生成 mermaid 可视化	依赖图, 模块关系, 谁依赖, 影响面, 代码结构图谱, 画依赖图, 依赖分析, 改这个会影响哪些文件

你不必背这 19 个技能——说需求即自动匹配（见「使用方法」）。上表的作用是帮你快速了解「每个技能大概干什么、什么场景会自动触发」，方便你判断交付结果是否符合预期；想用得更好，扫一遍这张表即可，无需记忆触发词。

使用方法

本节要点：对话自然触发、自动组合；「3 分钟上手」表 + 需求公式"目标+约束+验收"。

通过 对话自然触发，说出需求即可自动匹配对应子技能。

你不用记这 19 个子技能，也不用手动编排组合。 只要把目标说清楚（最好带约束和验收，见「需求表达完整示例」），系统会按领域路由表 + 优先级矩阵自动串联所需的子技能与专项参考——例如你说"实现导出功能并出接口文档"，它会自动走 代码生成 + 文档生成；你说"定位这个报错顺带看看安全隐患"，它会自动走 Bug诊断 + 代码审查。组合是自动发生的，你只需描述完整目标。

Laravel、Eloquent、Blade、artisan、Migration、Form Request、Queue、PHPUnit、PHPStan 等关键词会触发 Laravel 专项参考；Java、Spring Boot、MyBatis、JPA、Maven、Gradle、JUnit、Mockito、JVM、GC、线程池、并发等关键词会触发 Java 专项参考；代码优化、性能优化、架构优化、N+1、缓存、异步、性能瓶颈等关键词会触发性能反模式审查与性能基准测试协同。专项参考与代码生成、测试用例生成、API设计、MySQL数据库、性能基准测试等现有子技能协同执行。

3 分钟上手

如果是第一次使用，不需要记住全部触发词，按下面入口说需求即可：

你想做什么	推荐说法	会进入
写一个功能	"帮我实现登录接口，要求有参数校验和测试"	代码生成 + 测试用例生成
修一个报错	"这个报错帮我定位原因并给修复方案"	Bug诊断
检查代码有没有问题	"审查这个文件，重点看安全和性能"	代码审查
做 CMS/PHP 二开	"这是 WordPress/帝国CMS 项目，帮我加一个后台功能"	CMS二次开发
设计接口	"设计一个订单导出接口，数据量大，需要进度条"	API设计 + Init-Step-Poll
换电脑继续上次任务	"继续上次任务，先恢复 handoff"	项目记忆管理
顺带做两件事	"实现导出接口，顺带生成接口文档"	代码生成 + 文档生成
不知道功能叫啥	"帮我看看这段代码安不安全"	代码审查（描述目标即可，不必记名字）

需求表达完整示例（初次使用照着抄，不用背技能名）

光看表格还不够，下面给真实可直接发送的句子。记住一个万能公式：目标 + 约束 + 验收，越齐越省事（详见 FAQ 十六、Q"我不想被问太多"）。

① 把"模糊需求"改成"可验收需求"（最推荐练手）

• ❌ 太模糊：帮我把系统优化一下 → 会触发 Wayfinder 探索，先和你对齐再动手（不是错，但慢）
• ✅ 直接命中：用户列表接口响应超过 2s，帮我定位慢查询并加索引，目标降到 200ms 内 → 命中 mysql-database + performance-benchmark，且澄清少

② 带约束的功能开发（目标 + 范围 + 格式 + 权限）

• 给后台加一个导出用户的功能：范围=按筛选条件、格式=CSV、要鉴权+限频、能正确导出 1 万行且带表头 → 命中 代码生成 + doc-generation，几乎不用追问

③ 一次要两个能力（顺带式）

• 实现登录接口，并生成单元测试 → 代码生成 + 测试用例生成
• 定位这个报错，顺带看看附近代码有没有安全隐患 → Bug诊断 + 代码审查

④ 不知道功能叫什么，只描述目标

• 帮我看看这段代码有没有安全隐患 → 自动命中 代码审查（你无需知道 @code-review 这个名字）
• 这段逻辑太绕了，理一理结构 → 自动命中 重构建议

⑤ 纠正 / 反馈（让下次更准）

• 刚才那个修复不对，第 12 行的判空应该用if x is None而不是if not x`` → 触发修正并重跑验证；若排查耗时久，会被记入踩坑错误册供下次复用（见 FAQ 十七）

关键：说目标比背名字更稳。不确定叫啥就直接描述，系统按关键词 + 意图三分法路由；命中不了会问你一句，不会偷偷用错技能。

⚠️ 上手前先扫一眼红线（边界速览，完整版见 FAQ「能力边界速览 / 二、执行禁区 / 六、边界外」）

新手最容易"无意踩坑"的边界，先记一眼，免得做到一半才发现不能做：

• 本技能不覆盖的领域：用户调研、工时排期、容器深度编排、IDE 配置、缺陷跟踪流程、安全深度扫描（只做边界说明，不替代专门流程）。
• 明确禁止的做法（执行禁区）：直拼 SQL、Shell 写中文/UTF-8 文件、跨模块扩散修改、硬编码密钥、跳过验证直接交付、安全/数据类失败重试、凭猜测补业务规则、快速通道执行数据库写入、跨模块(≥2)/批量替换(>10处) 走快速通道。
• 关键限制：单次最多加载 3 个 reference；子 Agent 禁止写/改代码（只做检索收集）；代码审查（@code-review）是只读的、不自动改写实现；Laravel / Java / JS 三个专项 reference 不支持 @ 显式调用（用关键词触发即可）；涉及库写入 / 权限 / 生产配置须先给方案与回滚路径，不进快速通道。

记不住全表也没关系："写代码 / 查 Bug / 做文档 / 审质量"都能做；问调研排期、动生产配置前先确认、别让 Agent 替你盲写库"就是边界。

⚠️ 重点：红线不是建议——直拼 SQL / 盲写库 / 跳过验证直接交付，踩了会被安全闸门拦截、交付判无效，不是"提醒一下"。

文档阅读顺序

| 场景 | 先看 | 再看 | | -------------------------- | --------------------------------------------------- | ------------------------------------- | --- | | 只想知道怎么用 | README.md 的"3 分钟上手"和"子技能列表" | FAQ.md | | 不知道该用哪个技能 | README.md 子技能列表 | SKILL.md 路由表 | | 遇到报错、卡住、看不懂提示 | FAQ.md | 对应 references/*.md 的失败回退机制 | | 长任务执行/续做/可靠交付 | FAQ.md 第九节 | SKILL.md 长任务执行可靠性专节 | | 要改技能执行规则 | SKILL.md | 对应 references/*.md | | 要看某个技能细节 | references/ 下对应文件 | FAQ.md 的反模式清单 | | 想先知道哪些不能做 / 红线 | FAQ.md「能力边界速览」/ 二、执行禁区 / 六、边界外 | SKILL.md 安全闸门 / 澄清策略 | |

组合子技能与进阶触发

• 不知道某个功能叫什么名字？ 不必背子技能名。路由表同时匹配「子技能名」和「功能说明里的场景词」，直接描述目标/动作即可：说"帮我看看这段代码有没有问题"会命中代码审查，说"这段逻辑太绕了理一理结构"会命中重构建议，说"写个带参数校验的接口"会命中代码生成。实在不确定就描述需求，系统按关键词 + 意图三分法路由，命中不了会向你确认，不会乱猜。
• 想一次用两个功能？ 多数情况不用你操心组合——只要把完整目标说清（如"实现导出功能并出接口文档"），系统按领域路由表 + 优先级矩阵自动串联所需子技能（代码生成 + 文档生成），你不必手动指定谁先谁后。两种可选表达仅当你想精确控制时再用：①「顺带式」显式点名（"...顺带生成接口文档"）；②「显式点名式」用多个 @（"@code-review 先审，@refactoring 再按问题重构"）。自动组合与显式调用都只跳过路由匹配、不影响协同加载。
• 组合的典型顺序：审查类（代码审查 / Bug诊断）是只读的，先出报告、你确认后，再走重构 / 代码生成落地修改；性能类先跑基准拿基线、再重构，禁止无基线声称"显著提升"。多子技能同时命中按优先级矩阵组合路由（首选 + 必要协同），单次最多加载 3 个 reference，过多会提示你分阶段做。

Hooks 自动守卫（可选，增强护栏）

本节要点：15 个可选护栏钩子；两种启用方式（占位符/安装器）；多 IDE 工具名并集匹配。

本技能在 hooks.json 中提供一组通用示例守卫钩子（共 15 个：PreToolUse 3 + PostToolUse 11 + PreCompact 1），对全部子技能与 JS 专项共用，作为强制护栏兜底机械项（备份、lint、PHP8 兼容、安全/脱敏、UTF-8、调试残留、SELECT *、压缩快照、规划拦截、受保护目录写前拦截）。

三个 hooks 文件的关系（模板 / 增量草案 / 安装产物）

目录里会出现三个带 hooks 前缀的 JSON，分工如下，别混为一谈：

文件	类别	由谁产生	作用
hooks.json	主模板（源，手写维护）	你自己维护	15 个跨平台守卫钩子的完整定义；占位符 {{PYTHON_BIN}}/{{HOOKS_DIR}} 由运行时或安装器替换。已含 capture_learning.py 的 PostToolUse 项，但不含 UserPromptSubmit 段
hooks.capture-draft.json	捕获 hook 增量草案（源，手写维护，可选）	你自己维护	同一个 capture_learning.py 的 PostToolUse 项 + 额外一条 UserPromptSubmit（带 --mode correction 直接捕获你的纠错句式，信号最准）。因 UserPromptSubmit 并非所有 IDE 都支持（不支持的 IDE 会因未知事件名导致整份配置加载失败），故单列 opt-in，要用就单独并入，不用不影响主配置
hooks.installed.json	安装产物（自动生成，勿手改）	install_hooks.py 生成	把 hooks.json（或指定源）里的占位符替换成真实机器路径后的可加载配置，直接接入运行时即可

一句话：.json 是手写源、capture-draft.json 是可选附加源（多一路最准的纠错捕获）、.installed.json 是编译输出。日常只动前两个源文件，第三个由安装器重跑覆盖。

启用步骤（两种方式任选其一）：

方式 A：运行时占位符替换（适用于支持变量替换的 IDE）

1. 将 hooks.json 接入你的 Agent 运行时（按各 IDE 的 hooks 配置入口加载）。
2. 设置两个环境变量：
   • PYTHON_BIN：Python 解释器路径（如 /usr/bin/python3 或 F:\BtSoft\python\python_python\python3.exe）
   • HOOKS_DIR：hook 脚本目录，可指向技能自带 dev-expert/hooks/，或你复制到项目的 .codebuddy/hooks/
3. hooks.json 命令串用 {{PYTHON_BIN}} "{{HOOKS_DIR}}/xxx.py" 占位符，加载时由运行时替换为真实路径——不写死任何机器路径，换机换项目直接改环境变量即可。

方式 B：安装器预处理（适用于运行时不支持占位符替换的 IDE，推荐跨平台使用）

1. 运行安装器，自动探测 Python 路径和 hooks 目录，生成已替换占位符的 hooks.installed.json：

   # 自动探测（推荐）
   python hooks/install_hooks.py
   
   # 或通过参数指定
   python hooks/install_hooks.py --python-bin /usr/bin/python3 --hooks-dir /path/to/hooks
   
   # 或通过环境变量指定
   PYTHON_BIN=/usr/bin/python3 HOOKS_DIR=/path/to/hooks python hooks/install_hooks.py
   

2. 将生成的 hooks.installed.json 接入你的 Agent 运行时（路径已硬编码，无需运行时替换）。

3. 换机换项目时重跑安装器即可；--in-place 可原地覆盖（自动备份为 .bak），但建议保留 hooks.json 模板不变，仅使用 hooks.installed.json。

hooks.installed.json 文件顶部的 _comment 内含各智能体平台适配说明：CodeBuddy CN（工具名 write_to_file/replace_in_file）、Trae/Cursor 类（工具名 Write/Edit）等，matcher 已同时覆盖；若平台工具名不同（如 MultiEdit），在 matcher 里用 | 追加即可，无需改脚本。换机/换平台后 command 中的 Python 与 hooks 目录路径需同步更新（用安装器重生成或直接改 command）。

hooks 是护栏不是验证替代：动态/业务正确性（真实运行、端到端）仍须 Agent 显式产出证据。hooks 拦截即视为该防线未过，禁止绕过；运行时无 hooks 集成时须回退正文手动执行。钩子明细与故障排查见 FAQ.md 十五、Hooks 自动守卫。

适配平台（多 IDE 兼容）

本技能对 hooks 的适配基于工具名并集匹配（matcher），不是为每个 IDE 写专属配置。只要你的 Agent 运行时的工具名落在下表某个家族里，hooks 即开箱可用；工具名不同则在 matcher 用 | 追加一行即可，无需改脚本。

平台适配矩阵

| 平台 | 工具名家族 | hooks 开箱覆盖 | 说明 | | ----------------------- | ---------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------- | --------------- | | CodeBuddy CN | write_to_file / replace_in_file | ✅ 已覆盖 | 国内 IDE，代码/历史已确认 | | Trae / Trae CN | Write / Edit | ✅ 已覆盖 | 代码/历史已确认 | | Cursor | Write / Edit | ✅ 已覆盖 | 代码/历史已确认 | | Cline | write_to_file / replace_in_file | ✅ 已覆盖 | 寄生 VS Code，搜索核实其工具名与 CodeBuddy 同族 | | Roo Code | write_to_file / replace_in_file | ✅ 已覆盖 | Cline 分支，同族 | | Qoder CN | write_to_file / replace_in_file | ✅ 已覆盖 | 国内 IDE，v1.8.2「同类产品适配」已登记 | | WorkBuddy | write_to_file / replace_in_file | ✅ 已覆盖 | 国内 IDE，v1.8.2「同类产品适配」已登记 | | Claude Code | Write / Edit / Bash / UserPromptSubmit | ✅ PostToolUse；UserPromptSubmit 可选 | 支持事件最全，搜索核实其 hooks 含 PreToolUse/PostToolUse/UserPromptSubmit/Stop/Notification | | Codex（OpenAI） | Bash / 命令类 | ✅ 已覆盖 | 命令类家族 | | OpenClaw（龙虾类） | 命令类 | ✅ 已覆盖 | capture-draft.json 明确点名可在 UserPromptSubmit 挂捕获 | | Gemini CLI | Bash / 命令类 | ✅ 已覆盖 | 命令类家族，同 Claude/Codex 模式 | | Windsurf（Codeium） | write_file / edit_file | ⚠️ 需 | 追加 | 工具名与主流不同，在 matcher 补 write_file | edit_file 即可 | | Zed | 视配置 | ⚠️ 需确认 | 工具名随扩展形态变化，确认后追加 | | Continue | VS Code 扩展 | ⚠️ 需确认工具名 | 确认其工具名后追加到 matcher | | Aider | CLI 自有机制 | ❌ 非工具名匹配 | 走自带 hook / 包装层，不在本 matcher 范围 |

✅ = hooks.json matcher 已含该工具名家族，接入即生效；⚠️ = 在 matcher 用 | 追加对应工具名即可；❌ = 走另一套机制，本 hooks 不适用。

怎么追加未列出的平台

若你的平台不在上表（或工具名不同，如 MultiEdit、save_file），只需编辑 hooks.json 每个 matcher 字符串，用 | 并入新工具名，例如把 write_to_file|replace_in_file|Write|Edit 改为 write_to_file|replace_in_file|Write|Edit|MultiEdit|save_file。额外名称不会匹配时无害，可放心并集。改完重跑安装器生成 hooks.installed.json 即可。

各平台适配细节也写在 hooks.installed.json 顶部的 _comment 里。本技能除 hooks 外对运行时不挑平台——核心路由/19 子技能是纯自然语言触发的，不接 hooks 也能用，hooks 只是可选增强护栏。

⚠️ 长任务 / 捕获 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 第九节）。

协同技能

本节要点：14 条协同路径由路由自动串联，你只需说清目标，无需手动拼装。

子技能内部协同

下面 14 条协同路径是系统自动执行的编排结果——你描述完整目标后由领域路由表 + 优先级矩阵自动串联，无需你手动拼接。列出仅方便你了解内部如何协作、以及核对交付是否完整。你不必背这 19 个技能，说需求即自动匹配与组合。

19个子技能通过"关联Skill"章节相互引用，形成全生命周期闭环。常见协同路径：

• 通用软件项目：软件项目总控 → Spec驱动开发 → 技术选型/API设计/MySQL数据库/CMS二次开发 → 任务拆解与执行 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成/部署运维说明 → 项目记忆管理
• 网站项目：网站项目总控 → Spec驱动开发 → 任务拆解与执行 → 前端设计/CMS二次开发/API设计/MySQL数据库 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成 → 项目记忆管理
• 需求阶段：Spec驱动开发 → 任务拆解与执行 → 前端设计/代码生成
• 页面阶段：前端设计 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成
• 交付阶段：代码生成 → 代码审查 → 测试用例生成 → 文档生成/部署运维说明
• 治理阶段：Bug诊断/重构建议 → 代码审查 → Karpathy编码规范 → 项目记忆管理
• CMS二开：CMS二次开发 → (前端设计/代码生成/Bug诊断/代码审查/技术选型) → 项目记忆管理
• MySQL专项：MySQL数据库 → 代码生成/代码审查/Bug诊断 → 测试用例生成 → 项目记忆管理
• 性能验证：性能基准测试 → 代码审查/重构建议/MySQL数据库 → 项目记忆管理
• 代码优化：代码审查(性能反模式) → 性能基准测试(L0/L1/L2) → MySQL数据库/重构建议 → 测试用例生成 → 项目记忆管理
• Laravel功能：Laravel专项参考 → 代码生成/API设计/MySQL数据库 → 代码审查 → 测试用例生成 + Laravel测试参考 → 项目记忆管理
• Java功能：Java专项参考 → 代码生成/API设计/MySQL数据库 → 代码审查 → 测试用例生成 → 性能基准测试/文档生成
• AJAX防卡死：Init → Step → Poll，API设计 → 前端设计 → CMS二次开发 → 测试用例生成
• 沉淀阶段：任何子技能 → 项目记忆管理（记录决策/规范/summary）

跨技能包协同

本技能包为独立套件，暂无可直接联动的其他职业技能包。如需在编程任务中集成外部数据或服务，可使用主 Agent 当前可用的外部检索工具获取。

文件结构

本节要点：技能目录清单与每个文件职责；知识图谱脚本在 scripts/build_graph.py。

• SKILL.md - 技能运行时指令
• README.md - 本文件，用户入口文档
• FAQ.md - 常见问题、执行禁区、验证失败和边界外请求答疑
• hooks/ - 钩子脚本目录（高级功能，需按自身 IDE/工具适配）：15 个守卫钩子（备份/lint/PHP8/安全/脱敏/UTF-8/调试残留/SELECT */依赖扫描/SQL注入/CMS风险/学习捕获/压缩快照/规划拦截/受保护目录拦截）+ install_hooks.py 安装器 + step_ref_check.py 步骤号检查器 + recurrence_promote.py 提升评估
• scripts/build_graph.py - 项目知识图谱构建/查询工具（高级功能，需按自身环境适配 Python 路径等；纯正则，无 AST/tree-sitter；LSP 仅探测可用性记录、不参与抽取；构建与查询均零 LLM token）：--root 全量构建 / --query <file|symbol，多入口逗号分隔合并子图> [--direction up|down|both] [--depth N] 子图裁剪 / --rebuild / --incremental / --selftest；输出写盘 {PROJECT_ROOT}/.ai-memory/knowledge-graph/{graph.json,meta.json,symbols.json,graph.md}。token 消耗对比见文末「附录 A」
• references/ - 子技能详细模板（共19个子技能）+ 8 个专项 reference（不计入子技能）+ 3 个工作流保障 reference
• references/laravel-development.md - Laravel 开发专项参考（不计入子技能）
• references/laravel-testing.md - Laravel 测试专项参考（不计入子技能）
• references/java-development.md - Java/Spring 开发专项参考（不计入子技能）
• references/javascript-development.md - JavaScript/Node.js 开发专项参考（不计入子技能）；含「CMS / PHP 内联 JS」：PHP 内联 JS 强制校验（引号配对 / window.open features 收尾 / 全仓 Node 校验）
• references/domain-driven-design.md - 领域驱动设计专项参考（不计入子技能）；复杂业务系统领域建模：统一语言/限界上下文/聚合根/领域事件/防腐层
• references/distributed-systems.md - 分布式系统设计专项参考（不计入子技能）；跨服务事务/CAP/Saga/TCC/最终一致/幂等/分布式锁
• references/delivery-assurance.md - 交付保障：执行率自检 / 收尾报告 / 确认超时 / Graceful Abort
• references/error-ledger.md - 踩坑错误册：ERR-XXX 索引 + 单条模板 + 触发-定位-读取 + 新坑即录 + 归档
• references/execution-safety.md - 执行安全：规划门禁 / 审计修复分离 / 批量修改防线 / 写码前确认 / 不卡死计数器 / 清单化质量+安全
• references/style-alignment.md - 风格对齐（风格嗅探协议）：二开/插件生成前强制取样原项目已有文件、提取风格标记、产出「风格基线」逐行对齐，禁止凭想象套用样式
• references/architecture-decision.md - 架构决策（通用最小决策模板）：候选方案 + trade-off + 反选论证 + 接受的代价 + 撤销条件；命中复杂度门槛时强制走决策流程

维护建议

本节要点：reference 体量监控（建议 ≤400 行）与步骤号一致性检查命令。

Reference 体量监控

单个 reference 文件建议控制在 400 行以内；超过时考虑拆分（如「设计规范」与「实现规范」分离）或提取共性内容到独立 reference。当前体量分布（按行数降序）：

文件	行数	评估
project-memory-management.md	~479	偏大，职责内聚可暂保留
frontend-design.md	~435	偏大，后续可拆分「设计规范」与「实现规范」
cms-development.md	~406	偏大，CMS 场景复杂度本身高
code-review.md	~309	合理
其余 21 个	84-281	健康

跨文件步骤号一致性检查

新增/修改 reference 章节号后，运行检查器验证 SKILL.md / README.md / FAQ.md 中的步骤号引用与目标文件实际章节一致：

python hooks/step_ref_check.py

退出码 0 = 全部匹配；1 = 发现不匹配（会列出具体位置和期望/实际步骤号）。建议在合并 PR 前或重大版本发布前运行。

---

附录 A：知识图谱 token 消耗对比（常规 LLM 理解 vs 图谱方式）

本节要点：知识图谱 vs 常规 LLM 理解的 token 消耗对比——构建/查询均近零 LLM token（省的是"源码正文进上下文"）。

估算量级，非精确计费；基准：332 文件 / ~5 万行帝国 CMS 项目，图含 2890 有效依赖边，MAX_NODES=80（节点硬上限）。

维度	常规 LLM 理解（无图谱）	知识图谱方式
构建 / 索引成本	无（每次现读源码）	0 token（纯正则本地抽取，不进 LLM 上下文）
单次依赖查询	6k–60k token（把 5–50 个源文件喂进上下文理解依赖）	1k–3k token（返回子图 JSON，≤80 节点）
10 次任务累积	60k–600k token	10k–30k token
跨会话复用	每次重读，不留存	图谱缓存复用，query 恒定 ~2k
上下文污染	大（源码占满上下文窗口）	小（仅依赖拓扑，不含实现细节）

单次跨模块依赖查询的 token 消耗（ASCII 示意，取中值）：

常规 LLM 理解（无图谱）
  读 10–50 个源文件理解依赖    ████████████████████████   6k – 60k tok
知识图谱方式
  返回子图 JSON（≤80 节点）     ██                         ~1k – 3k tok

→ 单次节省约 70%–95%；跨会话 / 多任务累积节省更显著（图谱一次构建、永久复用）

为何能省：图谱把"代码 → 依赖关系"的抽取放在 LLM 之外（纯正则静态抽取，LSP 仅探测可用性、不参与抽取），LLM 只需消费精简后的依赖拓扑 JSON，而非原始源码。构建阶段 token≈0、查询阶段不重读源码，故整体近零 LLM 成本。详见 references/project-knowledge-graph.md。