ThinkPHP Skill是专为固化结构化业务逻辑设计的AI知识模块，支持将客户投诉处理等SOP自动执行；需ThinkPHP 8.0+与PHP 8.0+环境，通过继承Skill类、标注@skill标签、实现handle()方法并校验输入，结合硬编码/YAML/数据库三种规则绑定方式，经注册、扫描后由SkillFactory调用执行。
你想把公司内部的「客户投诉处理SOP」或「订单退款审核流程」直接变成AI能自动执行的插件，而不是每次都要人工翻文档、填表单、查规则——ThinkPHP Skill正是为此设计的可复用AI知识模块，它能把结构化业务逻辑固化进框架，让AI调用时自动遵循步骤、校验条件、触发动作。
确认环境与基础依赖
确保你正在使用 ThinkPHP 8.0 或更高版本，且已启用 PHP 8.0+ 的严格类型和属性声明特性。低版本不支持 Skill 所需的反射元数据注入机制。
运行 php -v 验证版本，输出中必须包含 8.0 或更高数字；若为 7.x，请先升级 PHP 环境再继续。
执行 composer require thinkphp/skill-support --dev 安装官方技能支持包。该包提供 SkillInterface、SkillRegistry 和基础生命周期钩子，是所有自定义 Skill 的运行基石。
立即学习“PHP免费学习笔记（深入）”；
定义一个标准 Skill 类
在 app/Skill/ 目录下新建文件 ComplaintHandlerSkill.php：
继承 think\skill\Skill，实现 handle() 方法，并在类顶部用 PHPDoc 注释标注 @skill 标签——这是 SkillRegistry 自动扫描识别的关键标识，漏写将导致注册失败。
在 handle() 中接收输入参数（如 $data = ['order_id' => 'ORD-2026-XXXX', 'reason' => '物流破损']），调用内置 $this->validate() 进行字段必填与格式校验，失败时直接抛出 SkillValidationException。
这一步不能跳过校验：SOP 流程一旦进入执行阶段，就默认输入合法；若未提前拦截非法数据，后续步骤可能触发数据库异常或空指针，导致整个 Skill 中断且无回滚。
绑定 SOP 规则到 Skill 执行流
方法一：硬编码规则链
在 handle() 内按顺序写死判断逻辑，例如：if ($data['reason'] === '物流破损') { $this->triggerLogisticsReview(); } → else if ($data['amount'] > 500) { $this->escalateToManager(); } → else { $this->autoApprove(); }。适合规则稳定、分支少、无需频繁变更的 SOP。
方法二：加载外部 YAML 规则文件
创建 config/sop/complaint_rules.yaml，用缩进定义条件树；在 Skill 中用 Yaml::parseFile() 加载，再通过递归匹配引擎执行对应动作。修改规则只需改 YAML，无需重发代码。
【注意：YAML 文件必须放在 config/ 下且不可被 Web 目录直接访问，否则敏感规则可能泄露】
方法三：对接数据库规则表
建表 sop_rules，字段含 skill_code、condition_json、action_class、priority；在 Skill 初始化时调用 $this->loadRulesFromDb('complaint_handler')。适用于多租户、灰度发布、A/B 测试等复杂治理场景。
注册 Skill 并启用自动发现
第一步：打开 app/provider.php，在返回数组末尾追加一行：think\skill\SkillServiceProvider::class,
第二步：在 config/app.php 的 'skills' 配置项中添加：'complaint_handler' => app\Skill\ComplaintHandlerSkill::class
第三步：执行 php think skill:scan 命令，触发自动扫描所有带 @skill 标签的类并生成缓存映射表。此命令必须在每次新增 Skill 类后手动运行，否则新类不会被识别。
第四步：在控制器中调用：$result = \think\skill\SkillFactory::make('complaint_handler')->handle($input); 即可启动完整 SOP 流程。
