Download the PHP package likun-mci/php-ai without Composer

On this page you can find all versions of the php package likun-mci/php-ai. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of likun-mci/php-ai

Informations about the package php-ai

PHP AI 标准库

一个框架无关的 PHP AI 调用标准库，用统一接口屏蔽 40 个国内外主流 AI 平台在鉴权方式、请求协议、返回格式、流式协议上的差异——国内的通义千问、豆包、文心一言、智谱 GLM、Kimi、腾讯混元、讯飞星火、DeepSeek……，海外的 OpenAI、Claude、Gemini、Grok、Mistral……，以及 OpenRouter、硅基流动等聚合中转与 Ollama 等本地部署。切换平台只需换一个配置项。

除对话能力外，还内置了 Agent 工具调用循环、AI 代码编辑协议、带 SSRF 防护的网页抓取工具与 Agent 长期记忆，可直接用于构建后台 AI 助手、代码编辑助手、内容翻译等实际业务。

本文档中的示例均来自真实业务系统（一套 CodeIgniter 3 的建站系统）中的实际用法，非伪代码。

🌏 English documentation: README-en.md

特性

环境要求

项目 要求
PHP >= 7.1
扩展 ext-curl、ext-json、ext-mbstring、ext-dom（仅 HTML 转换用到）
网络 可访问对应平台 API；中国环境通常需配置代理，见 网络代理

安装

Composer

手动引入（不使用 Composer）

库自带 PSR-4 加载器，把整个目录放进项目后引入一次即可：

快速开始

换成国产平台，只需改配置——业务代码一行不用动：

完整的平台清单见 支持的平台与模型，可运行的示例见 examples_platforms.php。

chat() 接受字符串（自动包装为一条 user 消息）或完整 payload 数组：

多轮对话：默认不保存历史（messages 由业务层完整传入）。若想让库自动维护上下文，设 rounds 即可，见 多轮对话上下文。

支持的平台与模型

平台一览

protocol 传下表中的取值，api_key 传该平台控制台的密钥，其余写法所有平台完全一致：

中国大陆主流平台

平台 protocol 取值 默认端点 模型名自动识别
DeepSeek 深度求索 deepseek
别名 deepseek-ai		 api.deepseek.com/v1/chat/completions deepseek-*
阿里云百炼（通义千问） qwen
别名 dashscope / bailian / tongyi / aliyun		 dashscope.aliyuncs.com/compatible-mode/v1/chat/completions qwen*、qwq*
阿里云百炼（通义千问） qwen-anthropic
别名 qwen-claude / dashscope-anthropic		 dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy/v1/messages —
火山方舟（豆包） doubao
别名 ark / volcengine / volces / volc		 ark.cn-beijing.volces.com/api/v3/chat/completions doubao-*
百度千帆（文心一言） ernie
别名 qianfan / baidu / wenxin / yiyan		 qianfan.baidubce.com/v2/chat/completions ernie-*
智谱 AI（GLM） zhipu
别名 glm / bigmodel / chatglm / zhipuai		 open.bigmodel.cn/api/paas/v4/chat/completions glm-*、cogview-*
智谱 AI（GLM） zhipu-anthropic
别名 glm-anthropic / zhipu-claude		 open.bigmodel.cn/api/anthropic/v1/messages —
月之暗面（Kimi） moonshot
别名 kimi / yuezhianmian		 api.moonshot.cn/v1/chat/completions kimi-*、moonshot-*
月之暗面（Kimi） moonshot-anthropic
别名 kimi-anthropic / moonshot-claude		 api.moonshot.cn/anthropic/v1/messages —
腾讯混元 hunyuan
别名 tencent / tencent-hunyuan		 api.hunyuan.cloud.tencent.com/v1/chat/completions hunyuan-*
讯飞星火 spark
别名 xunfei / iflytek / xfyun / xinghuo		 spark-api-open.xf-yun.com/v1/chat/completions spark*、4.0Ultra
MiniMax（稀宇科技） minimax
别名 xiyu / minimaxi		 api.minimaxi.com/v1/text/chatcompletion_v2 MiniMax-*、abab*
阶跃星辰（Step） stepfun
别名 step / jieyue		 api.stepfun.com/v1/chat/completions step-*
零一万物（Yi） yi
别名 lingyiwanwu / 01ai / 01-ai / zeroone		 api.lingyiwanwu.com/v1/chat/completions yi-*
百川智能 baichuan
别名 baichuan-inc		 api.baichuan-ai.com/v1/chat/completions Baichuan*
商汤日日新（SenseNova） sensenova
别名 sensetime / sensechat / shangtang		 api.sensenova.cn/compatible-mode/v1/chat/completions SenseChat-*
360 智脑 zhinao
别名 360 / qihoo / 360ai		 api.360.cn/v1/chat/completions 360gpt*
华为云 ModelArts（盘古 / MaaS） modelarts
别名 huawei / maas / pangu		 api.modelarts-maas.com/v1/chat/completions —

海外主流平台

平台 protocol 取值 默认端点 模型名自动识别
OpenAI openai
别名 oai / openai-compatible / compatible / chat_completions		 api.openai.com/v1/chat/completions gpt-*、o3
Anthropic Claude claude
别名 anthropic / claude-messages / messages		 api.anthropic.com/v1/messages claude-*
Google Gemini gemini
别名 google		 generativelanguage.googleapis.com/v1beta/openai/chat/completions gemini-*
Z.ai（智谱国际站） zai
别名 z-ai / zhipu-global		 api.z.ai/api/paas/v4/chat/completions —
xAI（Grok） grok
别名 xai / x-ai / x.ai		 api.x.ai/v1/chat/completions grok-*
Mistral AI mistral
别名 mistralai		 api.mistral.ai/v1/chat/completions mistral-*、codestral-*
Meta（Llama API） llama
别名 meta / meta-llama		 api.llama.com/compat/v1/chat/completions —
Cohere cohere
别名 command		 api.cohere.ai/compatibility/v1/chat/completions command-*
Perplexity perplexity
别名 pplx / sonar		 api.perplexity.ai/chat/completions sonar*
Azure OpenAI azure
别名 azure-openai / azureopenai		 需自填base_url`` —

聚合中转平台

平台 protocol 取值 默认端点 模型名自动识别
OpenRouter openrouter
别名 or / open-router / open_router		 openrouter.ai/api/v1/chat/completions —
硅基流动（SiliconCloud） siliconflow
别名 silicon / siliconcloud / guiji		 api.siliconflow.cn/v1/chat/completions —
魔搭社区（ModelScope） modelscope
别名 moda / damo		 api-inference.modelscope.cn/v1/chat/completions —
Groq groq
别名 groqcloud		 api.groq.com/openai/v1/chat/completions —
Together AI together
别名 togetherai / together-ai		 api.together.xyz/v1/chat/completions —
Fireworks AI fireworks
别名 fireworksai		 api.fireworks.ai/inference/v1/chat/completions —
DeepInfra deepinfra api.deepinfra.com/v1/openai/chat/completions —
Cerebras cerebras api.cerebras.ai/v1/chat/completions —
NVIDIA NIM nvidia
别名 nim / nvidia-nim / build-nvidia		 integrate.api.nvidia.com/v1/chat/completions —

本地 / 自建部署

平台 protocol 取值 默认端点 模型名自动识别
Ollama（本地） ollama localhost:11434/v1/chat/completions —
LM Studio（本地） lmstudio
别名 lm-studio		 localhost:1234/v1/chat/completions —
vLLM（自建） vllm
别名 sglang / xinference		 localhost:8000/v1/chat/completions —

表格由 $ai->listProtocols() / listProtocolGroups() 提供程序化版本，可直接渲染后台下拉框； $ai->listKnownModels('qwen') 返回该平台的常用模型清单（不发请求）。 别名只是同一协议的另一种写法，效果完全相同（protocol => 'kimi' 等价于 protocol => 'moonshot'）。

内置模型标识（快捷方式）

下列模型标识可直接传给 model，无需 protocol，库会解析出平台、协议与端点：

平台 模型标识 实际协议 端点
OpenAI gpt-4.1 OpenAI api.openai.com
OpenAI gpt-4o OpenAI api.openai.com
Claude claude-3-opus Claude api.anthropic.com
Gemini gemini-2.5-pro Gemini（OpenAI 兼容端点） generativelanguage.googleapis.com
DeepSeek deepseek-chat OpenAI api.deepseek.com
DeepSeek deepseek-reasoner OpenAI api.deepseek.com
DeepSeek deepseek-v4-pro OpenAI api.deepseek.com
DeepSeek deepseek-v4-flash OpenAI api.deepseek.com
DeepSeek deepseek-anthropic Claude api.deepseek.com/anthropic
OpenRouter openai/gpt-4o 等完整标识 OpenRouter（OpenAI 兼容） openrouter.ai/api

deepseek-anthropic 是 DeepSeek 的 Anthropic 兼容端点，用 Claude 协议通信——需要工具调用（Agent）时用它，可以用 DeepSeek 的价格跑 Anthropic 的 tools 协议。

表外的模型也能直接用

上表只是「开箱即用的快捷标识」，model 并不限于表内的值：

模型名无法归属官方平台、又没给 base_url / endpoint 时，请求前会抛 ConfigException，而不是把 Key 发到不相干的官方域名。

protocol 除了上面平台表里的取值，还可以传实现了 Ai\Contracts\ProtocolInterface 的自定义协议类名（见「扩展开发」）。

不传 protocol 时按模型名推断（见平台表「模型名自动识别」列），也识别 厂商/模型 写法（如 qwen/qwen-max）。推断不出时按 openai 协议处理，此时必须给 base_url 或 endpoint。

只对厂商自有模型名做推断。llama3、mixtral 这类被多家平台托管的开源模型名不参与推断（无法判断你想连哪一家），需要显式给 protocol 或 base_url。

协议差异（重要）

各平台协议对 payload 键的支持并不一致，写业务代码前需要知道：

payload 键 OpenAI 协议 Claude 协议 Gemini 协议
messages ✅ ✅（role: system 会被丢弃） ✅
system（顶层） ❌ 忽略 ✅ ❌ 忽略
tools / tool_choice ❌ 忽略 ✅ ❌ 忽略
temperature / max_tokens ✅ ✅ ✅
stream ✅（自动附带 usage 统计） ✅ ✅

结论：

protocol 平台 鉴权用的密钥
deepseek-anthropic（模型标识） DeepSeek deepseek__api_key
zhipu-anthropic 智谱 GLM zhipu__api_key
moonshot-anthropic 月之暗面 Kimi moonshot__api_key
qwen-anthropic 阿里云百炼 qwen__api_key

运行时查询平台与模型

真实用例——按平台分组拉取模型列表并本地缓存一周，供后台下拉框渲染：

配置项

setConfig() 是增量合并，可以分多次调用；每次传入 model 都会重建模型与协议实例。base_url、protocol 等既可以和 model 一起传，也可以在设置模型之后再补。

生成参数（max_tokens、max_completion_tokens、temperature、top_p、top_k、stop、presence_penalty、frequency_penalty、seed、response_format、system、tools、tool_choice、reasoning_effort、thinking）写在 setConfig() 里对所有请求生效，单次 chat() 的 payload 优先级更高；连接信息（api_key、base_url 等）不会进入请求体。

接口有私有参数时用 extra_body（直接并入请求体），需要特殊鉴权头时用 headers：

链式接口：

调试时可用 $ai->getLastInfo() 获取最近一次请求的 cURL 信息（http_code、总耗时等）。

网络代理

支持 http://、https://、socks5://、socks5h://（DNS 也走代理）、socks4://、socks4a://：

自定义接口地址（第三方转发 / 中转 / 自建网关）

默认端点是各平台的官方地址。要接入第三方转发、中转或自建网关，有两种配置方式，优先级从高到低：

1. base_url —— 接口根地址，与协议官方路径智能拼接（最常用）

只要给出根地址即可，库会补上协议对应的路径；根地址自带的路径前缀会保留，与官方路径重叠的片段自动去重：

base_url 协议路径 实际端点
https://proxy.com /v1/chat/completions https://proxy.com/v1/chat/completions
https://proxy.com/v1 /v1/chat/completions https://proxy.com/v1/chat/completions（重叠段去重）
https://proxy.com/openai /v1/chat/completions https://proxy.com/openai/v1/chat/completions
https://proxy.com/v1/chat/completions /v1/chat/completions 原样（已是完整端点）
127.0.0.1:8080 /v1/chat/completions https://127.0.0.1:8080/v1/chat/completions（缺 scheme 按 https）

2. endpoint —— 完整端点覆盖，原样使用（最灵活）

当接口路径结构与官方完全不同时使用，直接给出完整 URL：

endpoint 优先级高于 base_url；两者都不设置时使用官方默认端点，完全向后兼容。

OpenRouter 聚合中转

OpenRouter 是一个 AI 模型聚合平台，通过统一的 OpenAI 兼容接口访问 OpenAI、Claude、Gemini、DeepSeek、Llama 等多种模型。库已内置 openrouter 协议，开箱即用：

OpenRouter 上的模型名使用 厂商/模型 格式，协议推断规则会自动提取厂商前缀：

OpenRouter 返回的 usage 字段是 OpenRouter 统计而非原始模型统计（可能包含缓存命中标记等扩展字段），$response->getUsage() 原样透传。

通过 OpenRouter 查看实时模型状态：

其他常见 AI 中转/聚合服务

OpenRouter、硅基流动、魔搭、Groq、Together、Fireworks、DeepInfra、NVIDIA NIM 已内置为协议（见「平台一览」），直接 protocol 指定即可。其余中转站与自建网关走 OpenAI 兼容协议（protocol=openai），配置 base_url 或 endpoint：

以上所有接入方式均支持流式输出、附件、回调等完整功能。

模型列表端点：listModels() 会跟随 base_url 走同一个网关；只配了 endpoint 时，库按对话端点同源推导（如 .../v1/chat/completions → .../v1/models）。若网关的模型列表路径特殊，用 endpoint_models 单独完整覆盖（仅对 listModels() 生效）。OpenRouter 的模型列表接口返回完整定价数据，listModels(true) 可获取。

当前实际请求端点可随时查询：

Claude Code CLI 程序调用

Ai\Cli\ClaudeCode 直接调用本机安装的 claude 可执行程序（Claude Code CLI），与 Ai\Protocol\Claude（Anthropic HTTP API）互补。适合让 AI 直接操作工作区文件：读写文件、执行工具，配合 acceptEdits 权限模式实现"AI 改代码"。

快速开始

默认参数（均经实测验证）：

--allowedTools 与 --tools 语义不同：前者决定"哪些工具不用问"，后者（setTools()）决定"模型有哪些工具可用"。要真正限制能力范围用 setTools() 或 setDisallowedTools()。

claude 路径：自动检测 + 缓存 + 手动指定

自动检测顺序：command -v claude（PATH）→ 常见安装路径（~/.local/bin、Homebrew、/usr/bin）→ nvm 最新版本 ~/.nvm/versions/node/*/bin/claude → 登录 shell command -v。结果缓存到进程内 + 文件（默认 sys_get_temp_dir()/ai_claude_binary_cache.json），避免 PHP-FPM 下每次请求重复探测。

自定义 CLI 参数

所有 claude 参数均可覆盖/新增/删除：

参数名不区分下划线：setFlag('permission_mode', 'plan') 等价于 --permission-mode plan。

多值参数会按 CLI 各自的解析规则渲染，无需自己拼串：setting-sources/tools/fallback-model 逗号连接，add-dir/mcp-config 一个 flag 跟多个值，plugin-dir/plugin-url 重复 flag。

注意：claude CLI 没有 --working-dir、--max-budget、--proxy、--theme 这些参数（实测会被拒绝）。工作目录用 setWorkdir()（内部转成 cd ... &&），代理走环境变量 HTTP_PROXY/HTTPS_PROXY。

常用参数的专用方法

除了通用的 setFlag()，常用选项都有带取值校验的专用方法：

结构化输出

setJsonSchema() 约束模型最终必须输出符合 schema 的 JSON，getStructured() 直接拿数组：

流式调用（事件回调）

runStream() 逐事件回调，事件语义与官方 IDE 插件一致，可直接转发给 SSE：

result 事件是最终汇总：文本取自 result.result，费用取自 result.total_cost_usd（CLI 实测值，无需价格表），is_error:true 时 isSuccess() 返回 false。

响应对象除 getContent() / getSessionId() / getCostUsd() 外还提供：getStructured()、getThinking()、getToolUses()、getTools()、getPermissionDenials()、getSubtype()、getStopReason()、getInit()、getNumTurns()、getDurationMs()、getExitCode()、getCommand()。

多轮会话续接

每次执行后若输出带新 session_id，会自动回写到内部，getSessionId() 始终是最新的。

自定义执行器（远程 / 容器化场景）

默认用 proc_open 本地执行。需要经 SSH/SFTP 在宿主机跑 claude 时（如 Docker 容器内 PHP），注入自定义执行器：

配套设置：

进程行为：环境变量 / 信号 / 协程

以下三项对 ClaudeCode 与 ClaudeCodeSession 同时生效。

子进程默认继承当前进程的环境变量（setInheritEnv(false) 关闭）

proc_open 收到非 null 的 env 数组时会整体替换子进程环境，不是叠加。因此不继承时子进程连 HOME 都没有，claude 只能靠 /etc/passwd 兜底才找得到 ~/.claude 下的登录凭据 —— 容器里 /etc/passwd 常常没有对应条目，表现就是"登录态莫名丢失"；PATH 也只剩 shell 的内置默认值，nvm 装的 node 不在其中。

继承是全量的：父进程若设了 ANTHROPIC_API_KEY、CLAUDE_CODE_* 之类变量，子进程一样读得到（可能改变 claude 的计费与行为）。需要干净环境时关掉继承，再用 setEnv() 精确给定。

claude 直接取代 shell 进程（setExecReplace(false) 关闭）

命令里给 claude 加了 exec 前缀。proc_open 传字符串走的是 sh -c "<cmd>"，实测 dash 不做 exec 优化，进程树是 sh → claude 两层，proc_terminate() 的信号只打到中间那层 sh —— 超时抛完异常、kill() 返回之后，claude 其实还在后台跑到把整轮写完，额度照烧。加上 exec 后信号直达 claude 本人。

只有一种情况需要关掉：自定义执行器拿到命令串后还要往后面接东西（如 $cmd . '; echo done'，exec 之后 shell 已被替换，后面的命令不会执行），或者调用方自己已经插过 exec（exec exec cmd 在 dash 下直接报 127）。

配套的 setKillGrace(2)：结束进程时先发 SIGTERM 并留出这段宽限期，让 claude 自己收尾、把 session 落盘（之后还能 --resume），期限内没退出才 SIGKILL。设 0 表示直接强杀。

协程环境把内部等待换掉（setSleeper()）

Swoole / Workerman 这类常驻协程环境里，库内部的 usleep 与 stream_select 会把整个 worker 钉死，同 worker 上的其它请求全部排队：

设置后，本地执行的轮询间隔、双工会话的事件泵与关闭流程都改走它，会话类的 stream_select 一并改成"轮询 + 让出"，不再阻塞整个线程。

信息查询（版本 / 登录态 / 模型列表 / 额度用量）

不需要发起对话就能读取 CLI 侧的各类信息，不消耗模型额度：

listModels() 与 Ai\AI::listModels() 保持同样的约定：默认返回可直接使用的模型标识数组，传 true 返回完整数据，适合后台下拉框渲染。

额度查询

每项还含 severity（normal / 告警级别）、resets_at（ISO8601）、is_active。按订阅计费时 limit_dollars 类字段为 null，只提供百分比；额度不可用时返回空数组。

getUsage() 的完整结构：

键 说明
session 当前进程的 total_cost_usd、耗时、代码增删行数、分模型用量
subscription_type 订阅类型，如 max / pro
rate_limits 各限流窗口原始数据 + 归一化后的 limits 数组 + extra_usage 额度包信息
behaviors 近一天 / 一周的 request_count、session_count 等统计

在会话中查询：ClaudeCodeSession 上同名方法会复用已运行的进程，因此 getUsage() 拿到的 session.total_cost_usd 就是本会话的真实累计花费；另有 getSessionCost() 返回同交互式 /cost 的文本报告。

CLI 的 get_context_usage（上下文窗口占用）只在交互式 UI 下响应，headless 模式不回包，故本库未提供对应方法。

常驻双工会话（ClaudeCodeSession）

Ai\Cli\ClaudeCodeSession 复刻官方 IDE 插件（VSCode / JetBrains）的进程工作方式：claude 以长驻进程运行，stdin 持续接收 JSON 消息，stdout 持续吐事件，工具权限通过 stdio 上的 control_request 协议实时回调给 PHP 决策。

插件实测启动参数：

本类默认采用其中与服务端场景相符的部分（双工 + stdio 权限回调 + 全设置源 + 消息回显 + 禁用 Chrome）；权限模式保持更保守的 acceptEdits，思考预算和调试日志默认不开，需要时用 setThinkingTokens(31999) / setDebug() 打开。

与一次性模式的区别

ClaudeCode ClaudeCodeSession
进程 每轮起停一次 长驻，多轮共用
多轮 --resume 重放历史 上下文常驻内存
工具权限 靠 flag 静态配置 逐次回调 PHP 决策
中断 只能 kill 进程 interrupt() 优雅中断
运行时改配置 不支持 热切权限模式 / 模型 / 思考预算
处理中继续提需求 不支持 post() 轮内插入
事件循环 库内阻塞 tick() 可由宿主驱动
受限 PHP 环境 支持自定义执行器（SSH） 仅本地 proc_open

处理过程中继续提需求（非阻塞事件泵）

send() 一直阻塞到本轮结束，所以"claude 正在跑的时候用户又提了个新需求"在它身上做不到 —— 调用方唯一的执行流正卡在等待里。post() 把"投递"与"等待"拆开，事件循环交给宿主自己驱动，对齐官方 IDE 插件里的交互：

方法 作用
post($text) / postMessage($blocks) 非阻塞投递一条用户消息，返回本地消息 ID
tick($onEvent) 处理当前已可读的输出并派发事件，随即返回；返回值 = 本轮是否仍在进行
isTurnActive() 当前是否处在一轮之中（UI 据此决定输入框与停止按钮的状态）
takeResult() 取走最近一轮的结果，取走即清空；结构与 send() 的返回完全一致

轮内插入的语义（claude CLI 2.1.207 实测）：

比 send() 多出两个事件：posted（本地已投递，['id','content','injected']，injected 标记是否为轮内插入）与 delivered（CLI 已收下并回显，['id','event']）。UI 上建议 post() 返回后先标"已排队"，收到 delivered 再改"已送达"。其余事件与 send() 完全一致。

send() 内部就是 post() + 循环 tick()，两套 API 可以混用，落库代码也可以共用。

中断与运行时控制

interrupt() 就是 UI 上的"停止"按钮 —— 非阻塞化之后它才真正好用（此前唯一的调用时机是 send() 的事件回调里）。它让 claude 自己收尾、落 session 记录，进程保活可继续下一轮；kill() 则是直接收掉进程（默认先 SIGTERM、宽限 2 秒再 SIGKILL，见 setKillGrace()），claude 没有收尾机会。

权限回调的边界（重要）

onPermission() 只会收到 CLI 认为"需要询问"的调用，它不是一道完整的拦截层。以下情况 CLI 自行放行、不问 PHP：

要硬性禁止某个工具，用 setDisallowedTools(['Bash'])（工具从工具集移除，模型根本看不到）或 setTools([...]) 限定可用集合，不要只依赖回调。

未注册 onPermission() 时，默认只自动放行 Read / Edit / Write / Grep / Glob，其余一律拒绝；setAutoApproveTools([...]) 改名单，allowAllTools() 全部交回 CLI 自己判断。

其余会话方法：start() / isRunning() / close() / kill() / sendMessage($contentBlocks) / getInit() / getAvailableTools() / getCommand()。ClaudeCode 的全部参数方法在会话类上同样可用（需在首次 send() 前设置），包括 setSleeper() / setInheritEnv() / setExecReplace() / setKillGrace()（见「进程行为」一节）。

环境要求

流式输出（SSE）

调用 setStream(true) 后，chat() 会在接收模型数据的同时直接向输出缓冲区写 SSE 数据（自动设置响应头、关闭 Nginx 缓冲），无需注册回调：

服务端实际输出的报文格式（固定协议，前端按此解析）：

对应的前端消费代码：

真实用例——后台聊天接口（含代理、附件、流式）：

PHP 环境注意：流式输出会清空并关闭所有输出缓冲。如果使用会话锁（session_start()），建议在流式开始前 session_write_close()，否则同一用户的其它请求会被阻塞。

常驻内存框架（Swoole / Workerman）：setStreamCallback()

上面的默认行为是 echo 到输出缓冲区，只适用于 PHP-FPM / CLI。在 Swoole、Workerman、RoadRunner 这类常驻内存框架里，echo 会落到进程标准输出（日志文件），永远送不到客户端。这种场景注册回调，由调用方自己下发：

注册回调后库不再产生任何输出，SSE 帧格式完全由调用方决定。事件结构：

字段 说明
type stream_chunk 增量分片 / stream_end 结束
content stream_chunk 的增量文本，已由协议层归一化，跨平台通用；无正文的分片为 null
raw stream_chunk 的平台原始分片数组，需要平台专有字段时才用
data stream_end 的汇总：content 完整正文、model、usage

传 null（setStreamCallback(null)）恢复默认的直接输出。

平台兼容性：40 个协议均已覆盖

「普通对话 + 流式输出 + token 统计」是每个协议的基础能力，tests/stream_test.php 用各平台真实的 SSE 报文逐个回放校验。三套测试都不联网、不需要 Key、不依赖 PHPUnit：

CI 会在 PHP 7.1 / 7.2 / 7.4 / 8.0 / 8.2 / 8.4 上跑同样的检查，并在 8.2 上额外跑一次静态分析 与 PHP 7.1 兼容性扫描。最低版本 7.1 是真的把整套测试跑一遍，不是只做语法检查。

库内所有公开方法都带完整的 phpdoc 类型（PHP 7.1 不支持类型化属性，类型只能写在注释里）， IDE 能正确补全 getToolCalls() 这类方法的返回结构。

覆盖的报文差异（都踩过坑，已在传输层统一处理）：

差异 说明
data: 后不带空格 SSE 规范里冒号后的空格是可选的，讯飞星火等平台就不带；只认带空格的写法会导致整个流为空
CRLF 行尾 部分网关/代理会改写换行符
末尾无换行符 最后一帧（往往正是带 usage 的收尾帧）没有换行时不能被丢弃
夹杂 event: / id: 等字段 Anthropic 协议每帧都带 event:，需正确跳过
用量分帧下发 Anthropic 把 input_tokens 放在 message_start、output_tokens 放在 message_delta，需跨帧合并
HTTP 200 但流里报错 MiniMax（base_resp）、OpenAI 系（error）等出错时状态码仍是 200，需抛异常而不是返回空内容

usage 中的 prompt_tokens / completion_tokens / total_tokens 三个标准字段在所有平台一致可用 （Anthropic 系的 input_tokens / output_tokens 已自动映射），平台特有字段原样保留。

流式下 getStopReason() 与 getToolCalls() 同样可用：

自定义协议可选实现四个流式钩子（都不实现也能正常流式，只是拿不到对应信息）：

钩子 作用
parseStreamUsage(array $chunk): ?array 该帧的 token 用量，AI 层逐帧合并
parseStreamError(array $chunk): ?string 该帧的错误信息，非空即抛异常
parseStreamStopReason(array $chunk): ?string 该帧的结束原因（已归一）
parseStreamToolCalls(array $chunk): ?array 该帧的工具调用分片，返回 [索引 => ['id'=>, 'name'=>, 'arguments'=>片段]]，AI 层按索引拼接

附件（多模态）

附件格式由模型层适配：视觉模型（如 gpt-4o）转成各平台的图片块；不支持多模态的模型（如 DeepSeek 系列）会把附件信息以文本形式追加到最后一条用户消息，避免请求直接报错。

附件在每次 chat() 后自动清空，不会影响下一轮对话。

多轮对话上下文

两种方式，按需选一：

方式一：设 rounds，库自动维护（推荐）

rounds 默认为 0（不启用），此时库完全不碰历史，行为与旧版本一致。

多用户 / 常驻进程下用 setSessionId() 隔离上下文，一个 AI 实例可服务多个会话：

历史存在内存里，进程退出即失。跨请求要持久化就自己落库：

方法 说明
setSessionId(string) / getSessionId() 切换/读取当前会话，不同会话各自独立一份历史
getHistory() / setHistory(array) 读写当前会话的历史消息
clearHistory(bool $all = false) 清空当前会话；传 true 清空全部会话
exportHistory() / importHistory(array) 导出/导入全部会话，用于持久化

裁剪按「轮」而非按条数：一轮从一次真正的用户提问开始，只含 tool_result 的消息 算作上一轮工具调用的一部分。这样不会把 tool_use 和对应的 tool_result 切散—— 切散会让下一次请求直接被平台拒绝。

chatBatch() 不读写历史：批量里每条都是独立请求，混进同一份上下文没有意义。

方式二：自己维护 messages

不设 rounds 时库完全不介入，业务层自行拼接：

需要完全掌控裁剪策略（按 token 数、按重要性摘要等）时用这种方式。

请求前后回调

回调内抛出的异常会被捕获并记录到 error_log，不会中断主流程。

响应对象

chat() 返回 Ai\Contracts\AIResponseInterface：

方法 说明
getContent(): string 回复文本（流式模式下为累积后的完整文本）
getRaw(): array 平台原始响应体（Agent 解析 tool_use 块靠它）
getUsage(): array 完整用量对象，含 prompt_tokens / completion_tokens / total_tokens 及平台返回的扩展字段（prompt_tokens_details.cached_tokens、cache_creation_input_tokens 等，因平台而异）
tokens(): int 总 tokens
getModel(): string 实际返回的模型名
isSuccess(): bool 是否成功
cost(array $pricing): float 按价格表估算费用，默认每千 tokens（与旧版本一致，不改动已有代码的账）
costPerMillion(array $pricing): float 同上但按每百万 tokens，可直接抄官网数字，如 ['prompt'=>5.0,'completion'=>25.0,'cached'=>0.5]；cached 为命中缓存的输入价，两大家族的字段名都认
getToolCalls(): array 模型发起的工具调用，已归一：[['id'=>..,'name'=>..,'input'=>[..]]]
hasToolCalls(): bool 本轮是否要求调用工具
getStopReason(): string 结束原因（已归一）：end_turn / tool_use / max_tokens / content_filter / refusal
getSources(): array 联网搜索检索到的来源，已归一，见「来源与引用」
getCitations(): array 回答正文里的引用（含在正文里的字符区间），已归一，见「来源与引用」
toAssistantMessage(): array 转成可回填进 messages 的 assistant 回合
getError(): string 失败原因（仅 chatBatch() 这类不抛异常的场景会填充）
toArray() / __toString() 转数组 / 直接当字符串用

异常处理

RequestException 由传输层抛出，chat() 内部会将其转成携带平台信息的 AIException，业务层通常只需捕获 AIException。

健壮性：超时与自动重试

AI 接口最高频的失败不是「打不通」，而是 429 限流和 5xx 临时故障。库默认已处理：

情形 行为
408 / 409 / 429 / 500 / 502 / 503 / 504 / 529 自动重试
响应带 Retry-After（秒数或 HTTP 日期） 优先按服务端给的时间等待，并有上限保护
无 Retry-After 指数退避 + 抖动（避免多进程被同时限流后又齐刷刷重试）
4xx（除上表）如 400 / 401 / 403 不重试，立即抛异常
流式请求 不重试——分片已经吐给调用方，重试会造成重复输出
请求体含非 UTF-8 字节 立即抛 RequestException 并说明原因（此前会静默发出空请求体）

需要接入连接池、换 HTTP 客户端或在单元测试里注入假传输层时，替换整个传输层：

并发批量：chatBatch()

批量翻译、摘要、打标签这类场景串行跑，总耗时是「单条 × 条数」，且每条都要重做一次 TLS 握手。chatBatch() 用 curl_multi 并发，总耗时约等于「最慢的一条 × 批次数」：

日志：接到你自己的日志系统

库内不再硬编码 error_log()。注入后拉取模型列表失败、流式回调异常等都会走你的日志：

Agent：工具调用循环

Ai\Agent\Agent 实现完整的 agentic 循环：模型决定调用哪个工具 → 库执行工具 → 结果回填给模型 → 继续，直到模型给出最终答复或达到迭代上限。v2.0 起内部采用 AgentRuntime 架构，新增面向对象的工具接口与防死循环守卫。

40 个协议全部可用。各家把同一件事写成了两套结构，库在协议层吃掉了差异：

OpenAI 系（36 个协议） Anthropic 系（4 个协议）
工具定义 {type:'function', function:{name, parameters}} {name, description, input_schema}
模型发起 message.tool_calls[]，arguments 是 JSON 字符串 content 里的 tool_use 块，input 是数组
结果回填 独立的 {role:'tool', tool_call_id} 消息 user 消息里的 tool_result 块
结束原因 finish_reason: 'tool_calls' stop_reason: 'tool_use'
系统提示 messages 首条 role:'system' 顶层 system 字段

业务层只写一套（库的统一格式，采用 Anthropic 风格），换平台只改 protocol：

完整可运行示例见 examples_agent.php；跨平台一致性由 tests/tools_test.php 保证。

流式跑 Agent：setStream(true) 后每轮正文实时吐给回调，工具调用照常工作—— 库会把各平台分片下发的 tool_calls 重组回来（OpenAI 系按 delta.tool_calls[].index 拼 arguments 字符串，Anthropic 系按 content_block_start + input_json_delta 拼）。 适合聊天界面：用户能一边看模型说话，一边看它去调工具。

Agent 只是临时借用你的 AI 实例：跑完会把 setStream() 恢复原状（异常路径也会）， 不会影响后续无关的 chat()。

也可以直接写 OpenAI 原生格式（{type:'function'} 的工具定义、role:'tool' 的消息）， 库会识别并转成目标平台的结构，不强制迁移已有代码。

chat()：多轮对话

run() 是无状态的单次运行——调用方自备完整 messages，跑完不记账。要接着上一轮继续说，用 chat()：上下文由库维护，每次只说新的那句，返回 AgentResult。

run(array $messages) chat($input)
上下文 调用方自备完整消息 库维护，只传新的那句
返回 void（文本取 lastText()） AgentResult
适合 单次任务、自己管历史 聊天界面、连续追问

上下文存哪儿：默认在实例内存里，进程退出即失；挂上 SessionManager 就落到会话，跨请求、跨进程都能接着聊（见会话持久化）。

⚠️ 用 chat() 时不要给 $ai 设 rounds：上下文由 Agent 维护，AI 层再拼一份会翻倍。

等授权时可以直接说新的。 上一轮停在 permission_denied（等用户决策）时，除了 approve() / deny()，还可以直接 chat() 说别的——等于告诉模型「那个别做了，改做这个」：

库会先给那个没被批准的工具调用补一条「未执行」的结果，再把这句话作为同一条消息里的文本块接在后面。补结果这一步不是可选的：模型发出的每个 tool_use 都必须有一个 id 对得上的 tool_result，缺了下一次请求直接被平台判 400——不是降级，是整轮发不出去。

方法 说明
chat($input) 说一句话（也接受一条/一批消息），返回 AgentResult
getConversation() 读当前上下文；挂了 SessionManager 时读的是会话里那份
setConversation(array) 灌入上下文，用于自建持久化
clearConversation() 清空，下一次 chat() 从头开始
isAwaitingPermission() 上一轮是否停在等授权

不用 Agent，自己控制循环

AIResponse 提供了平台无关的取用接口：

工具定义

handler 返回的字符串会作为 tool_result 回填给模型；抛出的异常会被自动转成 ERROR: 异常信息 交给模型，不会中断循环。

运行

事件类型

onEvent() 回调会依次收到：

事件 字段 含义
thinking iter 第几轮迭代开始
agent_text text 模型输出的自然语言
tool_call name、input 模型决定调用某工具
tool_error name、message 工具执行出错（已回填给模型）
tool_permission name、input、request_id 需要用户授权
context_compact tokens、messages 上下文压缩开始
context_compact_done messages 压缩完成
done — 正常结束
error message 出错或达到最大迭代步数

每个事件统一携带以下字段，便于 SSE / WebSocket 断线重连：

字段 类型 说明
id string 自增事件 ID（evt_1_xxx）
session_id string 会话 ID
agent_id string Agent 标识
turn_id string 当前迭代轮次
timestamp float Unix 时间戳（微秒精度）

工具内部的细粒度事件（如 diff、进度）由各 handler 自行通过闭包发出，库不做假设。

执行结果（AgentResult）

Agent::run() 仍保持向后兼容返回 void，但通过 $agent->getRuntime()->run() 可获得完整的 AgentResult 对象：

方法 返回 说明
getText() string 模型最终自然语言回复
getStopReason() string 停止原因（见 StopReason）
getToolCalls() array 本轮工具调用序列
getUsage() array 累计 token 用量
getIterations() int 实际迭代次数
isDone() bool 是否正常结束
isError() bool 是否异常停止

AgentToolInterface：面向对象的工具定义

v2.0 起工具可以写成对象，实现 Ai\Agent\Tool\AgentToolInterface：

对象工具与旧格式闭包工具可混用：

并行安全标记

实现 ParallelSafeToolInterface 可标记工具为并行安全，只读工具（read_file / grep / glob）可并行执行：

不实现此接口的工具默认按「不可并行」处理，安全优先。

ClaudeCodeTools：内置工具工厂

Ai\Agent\Tools\ClaudeCodeTools 提供一键创建 Agent 完整内置工具集的能力，与 Claude Code CLI 默认工具集对齐：

六个内置工具详情：

工具 说明 并行安全
read_file 读取文件，支持 offset/limit 分页 ✅
write_file 创建或覆盖文件，自动创建目录 ❌
edit_file 精确局部替换（str_replace 语义）；edits 数组可批量原子编辑（全成功才落盘） ❌
glob 按 glob 模式匹配文件路径（可靠递归 **，尊重 .gitignore） ✅
grep 按模式搜索内容；探测到 ripgrep 自动加速，支持 ignore_case / 上下文行 / output_mode ✅
bash 执行 shell 命令，超时自动终止；run_in_background=true 可后台跑长任务 ❌
bash_output 读取后台命令的增量输出（action=read/kill/list） ❌

所有文件工具都受 PathSafety 沙箱保护，无法逃逸 workdir 范围。

二进制防护：read_file 读到图片/PDF/压缩包时不会把原始字节回传（那会产生非法 UTF-8， 让下一次请求的 json_encode() 失败、整个 Agent 运行中断），而是给出类型、大小、图片宽高等 结构化说明；grep 同样跳过二进制文件。

后台长任务（bash + bash_output）

构建、测试、装依赖这类长任务不该把 Agent 阻塞在一次工具调用里：

bash_output 每次只返回上次之后的新输出，适合轮询进度；进程结束后带上退出码。

精确代码导航（lsp，按需启用）

code_index 是词法级的，自述「callers 可能不准，当作重构唯一依据不行」；语言服务器有完整类型系统， 改接口找全部实现、跳定义、看真实签名只有它做得准。Ai\Agent\Tools\LspTool 把它接给模型：

语言服务器是可选外部程序，不进 composer 依赖；探测不到时工具会明确提示改用 grep / code_index， 而不是静默给错答案。传输复用 McpStdioTransport——LSP 与 MCP 同为「Content-Length 分帧 + JSON-RPC over stdio」。

分工：精确导航走 lsp，快速缩小范围走 code_index/grep。

code_index 的可选 AST 增强

装了 nikic/php-parser（composer require --dev nikic/php-parser）后，code_index 自动改走 AST 解析： 类名解析成全限定名（分组 use、别名、implements、参数类型、静态调用都拿到 FQN），闭包内部的调用也不会漏。 没装则维持 token 级解析，功能不受影响——零运行时依赖的承诺不变。

AST 只给语法结构、给不了类型：$obj->save() 的接收者类型推断仍需 lsp。

模型驱动的反思（LlmReflectionStrategy）

默认反思靠固定关键词表判「任务完成没有」，换个措辞、说中文就判不出来。可换成让模型自己判：

模型按 {"done":…,"reason":…,"next":…} 的 JSON 契约作答；请求异常或返回不可解析时走 fallback， 没给 fallback 则保守判「完成」并写明原因——判官坏了就停下让人看到，好过在循环里空转烧钱。

Notebook 编辑（notebook_edit，按需启用）

.ipynb 是 JSON，用 read_file 整份读会把 outputs 里的 base64 图片全灌进上下文。 Ai\Agent\Tools\NotebookEditTool 按 cell 读写，输出只给摘要：

它不在 all() 里——工具 schema 每次请求都占 token，notebook 在 PHP 项目里属小众，按需注册即可。

联网工具（web_fetch / web_search / translate）

自 v2.1 起，ClaudeCodeTools::web() 提供三个默认不装配的联网工具，需显式 ->tools(...) 启用（避免给所有 Agent 平白开外网）。它们属外呼，默认经 PermissionManager 把关（manual 询问，dont_ask / bypass / auto 放行）：

工具 说明
web_fetch 抓取网页正文（HTML 自动转纯文本），复用 Ai\Tools\HttpFetch 做 SSRF 安全防护（拒内网/回环/云元数据，逐跳重校验重定向）
web_search 关键词网页搜索，返回标题/链接/摘要（DuckDuckGo Lite，免费无密钥）
translate 文本翻译（Edge 免费接口，无需密钥）

渐进增强：grep 探测到 rg（ripgrep）、glob 探测到 git 就自动用它们换取性能/精度，探测不到则回退纯 PHP 实现——外部二进制只是可选增强，不是依赖。

文本翻译（Translate helper）

Ai\Helpers\Translate 可直接翻译文本，Edge 免费接口为主、库自带 LLM 兜底：

配套脚本 php bin/translate-readme.php README.md > README-en.draft.md 可把中文 Markdown 按段落翻成英文初稿（代码围栏原样保留），平台名/模型名/端点 URL 需人工校对后再落地。

上下文：文件读取去重与自定义 tokenizer

长任务里模型常为"再确认一下"重复读同一个文件，每次全文都再进一次上下文——token 白烧， 旧内容还可能与改动后的现状矛盾。ContextManager 会在压缩前先折叠重复读取，同一文件只留最新一份 （只改 tool_result 的内容字符串，不动 tool_use_id，不破坏配对）：

输出截断：Text 助手

工具输出、命令回显、diff 正文都要限长。substr() 会把汉字劈成两半（非法 UTF-8 会让 json_encode() 失败），mb_substr() 又是按字符算、限不住字节，所以内置工具统一走 Ai\Helpers\Text：

自己写工具时，凡是会回填给模型的内容都用 cutBytes()。

权限系统

Agent 内置 6 种权限模式，控制工具调用的放行策略：

模式 说明
manual 只读工具自动放行，危险工具（bash）询问用户
auto 全部自动放行
plan 仅允许只读工具，其余拒绝
accept_edits 允许文件修改，bash 等高风险操作询问
dont_ask 自动放行（不询问）
bypass 全部放行（⚠️ 不安全，不要用于不可信输入）

规则匹配

在模式基础上，可以用 allowTool / denyTool 添加细化规则，优先级：deny > allow > 模式默认：

也可通过快捷方式设置：

用户授权流程

当权限管理器返回 ask 时，Agent 暂停并发出 PERMISSION_DENIED 停止信号，等待业务层通过 approve() / deny() 响应：

上下文压缩

Agent 自动检测上下文长度，超过阈值时用 AI 自身将历史消息压缩为摘要，避免 token 超限。压缩以 Agent Turn（一轮完整交互）为单位，保证 tool_use 与对应的 tool_result 永远不会被拆散：

压缩过程自动触发 context_compact / context_compact_done 事件，前端可展示进度。

会话持久化

Agent 会话可保存到文件系统，支持跨请求恢复（适用于 PHP-FPM 场景）：

用 run() 的场合（自备完整消息的单次运行），续跑要自己把消息取回来：

run() 在会话存在时以会话消息为准，传进去的那份被视为它的旧副本。所以别拿 run() 追加新一轮提问——那句话会被覆盖掉且不报错。追加走 chat()。

会话状态流转：running → paused（等待授权）→ running（恢复）→ completed / interrupted。

默认持久化与双根存储

自 v1.63 起，Agent 具备惰性自动持久化：不必显式挂 SessionManager / MemoryManager，只要表达了持久化意图（设置 setSessionId()、setUserId()、setAgentHome() 或 setProjectRoot() 之一），库就会自动把会话与记忆落到磁盘。

行为变化（升级须知）：从本版本起，仅调用 setSessionId() 也可能产生磁盘数据。若只想要纯内存行为，显式关闭：

双根存储：数据分两处落盘，语义不同——

根 位置 内容 权限
项目根 <project>/.agent/AGENT.md 对团队/其他 Agent 也有价值的项目长期知识（可进 Git） 0755
HOME 根 ~/.agent/（users/、projects/、sessions/ …） 含用户输入/输出、绝对路径、session ID 等 0700

项目根从 workdir 向上寻找 .agent/（到 HOME 必停，最多 10 层，不依赖 .git，不用 realpath()）；找不到则用 workdir。跨目录部署（蓝绿发布、CI 与开发机路径不同）若需复用会话，显式 setProjectRoot() 固定项目身份。

多租户隔离：setUserId() 后，用户记忆与会话按用户分片存放，原始 userId 不进磁盘路径（只存其 SHA-256 分片）。会话加载时做 ownership 校验：当前 userId / 项目身份与会话记录不符则拒绝加载。sessionId 由 Agent::newSessionId() 生成（128 bit 随机），但它不是授权凭证，应用层仍须校验用户是否拥有目标会话。

JSONL 会话存储：自动挂载使用 JsonlSessionStore——每个会话一个 <sid>.jsonl（每行一个事件）+ <sid>.state.json（非消息状态）。消息通常只增不减，追加一行的成本是 O(新增)；只有 compact / rollback 时才整份重写（临时文件 + rename 原子替换）。整个读改写事务在 <sid>.lock 独占锁下完成，避免并发 lost update。显式 new FileSessionStore(...) 的旧用户不受影响，旧 <sid>.json 仍可读、不自动迁移；需要转换存量会话时运行 php bin/agent-migrate-sessions.php <目录>。

记忆与指令的区别——两者物理与语义分离，不要混淆：

文件 性质
AGENTS.md / CLAUDE.md 人写的规则/规程，Agent 只读的 Instruction
.agent/AGENT.md Agent 自动维护、跨会话复用的 Memory

Git：库不会自动改动 .gitignore / git config / git status。是否提交项目记忆 .agent/AGENT.md 由项目自行决定；若要提交，可自行配置 .agent/.gitignore。

子 Agent

通过 SubAgentManager 注册子 Agent，主 Agent 可通过 spawn_agent 工具派生子 Agent 执行独立任务，子 Agent 拥有隔离的上下文，不会导致主 Agent 上下文膨胀：

子 Agent 权限继承自父 Agent，且不能超越父 Agent 的权限范围。

后台模式（Background SubAgent）

spawn_agent 工具支持 background 参数。设为 true 时，主 Agent 不阻塞等待子 Agent 完成，立即返回 task_id 继续执行自己的任务：

子 Agent Transcript（P0-5）

每次子 Agent 运行的完整消息历史、迭代次数、停止原因、最终结果都被记录，与主 Agent 的 transcript 分离保存：

主 Agent 看到的只是 spawn_agent 工具返回的结构化摘要（含 transcript_id），完整 transcript 通过 getTranscript() 单独查询，不会导致主 Agent 上下文膨胀。

Worktree 隔离模式

spawn_agent 的 isolation 参数设为 worktree 时，子 Agent 在一个独立的 git worktree 中执行，改动不会碰到主工作区；执行完毕捕获 diff 并清理 worktree：

适合让子 Agent 试探性地改代码：拿到 diff 后由主 Agent 或人工决定是否应用。工作目录不是 git 仓库时该次运行返回 status = failed、reason = no_git_repo，不会退化成直接改主工作区。

预算控制

BudgetManager 跟踪 token 用量与估算成本，超过预算自动停止：

BudgetManager 还管两个与花钱无关、但同样能让任务跑飞的维度：

这两条是执行预算，与 token / 成本各管各的：一个卡在慢工具上的任务可能一个 token 都没多花，却已经占着 HTTP 连接跑了十分钟；一个反复 grep 的 Agent 可能 token 不多，工具调用已经上百次。超限时同样以 budget_exceeded 停止，summary()['reason'] 会说清是哪一项：

墙钟从循环开始处起算（start() 由循环自动调用），不是从 BudgetManager 构造时——它常常在装配阶段就建好，离真正开跑可能隔着很久。同一个实例跑第二个任务前调 reset() 清空计量。

子 Agent 与父 Agent 共用同一本账：委派出去的活儿花的 token、成本、工具调用都记在父账本上，父 Agent 的墙钟上限对它一样有效。跟权限同一条道理——子 Agent 的额度 ⊆ 父 Agent 的额度。不继承的话，父 Agent 设了 5 分钟上限却挡不住它派出去的活儿跑二十分钟。取消令牌一并往下传：叫停父 Agent 会把它派出去的子 Agent 一起停掉。

运行结束后，成本、耗时、改动的文件会自动填进 AgentResult，不必自己去各个管理器里拼：

模型调用的瞬时失败重试

传输层会重试 408 / 429 / 5xx，但不重试 4xx——一般来说这是对的，400 通常意味着请求本身有问题，重发多少次都一样。

实测发现这条规则有例外：把别家模型包装成 Anthropic 兼容接口的第三方网关会偶发吐 400。同一份字节完全相同的请求连发四次，三次成功、一次 400 Format Error。这个概率放到 25 轮的任务上就是必然事件——单次 1/4 的失败率，跑完一整轮几乎注定中途暴毙，而且前面所有工作一起丢。

所以循环层对模型调用另做一层重试（默认 2 次，指数退避）：

它重试的是同一个模型（治网关瞬时故障），与 setFallbackModels() 分工不同——后者是重试完还不行才换模型（治模型本身不可用）。鉴权失败、模型不存在（401 / 403 / 404 / 413）立即放弃，重试只是白等。每次重试都发 model_retry 事件。

万一重试用尽仍然失败，结果里会带上最后一段模型文本而不是空字符串——模型调用挂在第 N 轮，前 N-1 轮真做过的事不该跟着一起丢：

取消：让 Agent 停得下来

生产环境里任务需要能中途停下：用户按了停止、浏览器断开、任务超时。CancellationToken 让循环在安全点收手：

检查点选在三个安全边界上：开新一轮之前、模型回话后工具开跑前、一批工具结果回填之后。不在这些点之外硬中断——PHP 没有安全的线程中断，半途掐掉一个正在写文件的工具，留下的是半截文件，比多跑一轮糟得多。

取消不是放弃。 命中后会先存检查点再以 user_cancel 收尾，之后可以接着跑：

长跑的工具（下载、全库扫描）可以在执行途中反复问「还要不要继续」：

并行工具执行

当模型一次返回多个工具调用时，并行安全的工具（read_file / grep / glob）可同时执行，其余工具按顺序执行。默认关闭，需显式开启：

并行执行器默认按顺序执行（语义正确），在 Swoole / Workerman 协程环境可注入并行运行器实现真正并发：

工具执行超时

一次工具调用（含重试等待）超过指定秒数后自动标记为超时，不再继续重试：

超时判断时间点在每次执行完成和每次重试等待前，因此不会在工具执行中途强行中断（同步 PHP 无法打断用户态代码），但能阻止后续重试。框架内置的 BashTool 自带超时终止能力，可与全局超时配合使用。

超时工具的 StopReason 为 timeout，结果中的 error 包含超时详情。

模型降级

主模型服务级错误时，Agent 自动按序切换降级模型，保持上下文和工具状态不变：

降级发生后会发出 model_fallback 事件，包含当前使用的模型名与原始错误信息。所有降级模型均失败后，Agent 才以 MODEL_ERROR 停止。

验证管理（VerificationManager）

工具执行后自动运行验证命令（如 php -l），确保代码改动真实可用，而不是让模型"记得自己测试"。验证失败的错误信息会回填给模型，让它自行修复。

验证策略按工具名配置，支持多条命令；命令中的 {file} 占位符会替换为工具输入里的 file_path。验证通过 exec() 同步执行，退出码 0 视为通过，非 0 的错误输出回填给模型。

单独使用 VerificationManager：

验证器框架（VerifierInterface）

命令式的 addRule() 适合「跑一条命令看退出码」。需要解析工具输出、定位到具体文件行号时，实现 VerifierInterface 写一个验证器：

PhpSyntaxVerifier 对写入的 .php 文件跑 php -l，并把 Parse error / Fatal error 输出解析成带行号的结构化错误。非 PHP 文件、文件不存在、验证器被禁用时直接返回通过，不阻断流程。

VerificationResult 同时保留原有的 isPassed() / getCommand() / getOutput() / getError()，新增 getVerifierName()、getErrors()、addError()、toArray()，旧代码不受影响。

内置验证器

除 PhpSyntaxVerifier 外还有三个开箱即用的验证器，都实现 VerifierInterface：

验证器 名称 作用
PhpSyntaxVerifier php_syntax 对写入的 .php 跑 php -l，解析出带行号的语法错误
SecurityVerifier security 扫描危险函数（eval / exec / system …）与硬编码凭据
UnitTestVerifier unit_test 改动后跑测试命令，解析失败用例名
GitDiffVerifier git_diff 统计改动规模，超出上限或碰了受保护路径即拦下

或者一次挂全部：

SecurityVerifier 基于 token_get_all() 扫描，注释和字符串里的 eval 不会误报， $db->exec() 这类方法调用也不算内置危险函数。确实需要某个函数时用 allow() 放行：

GitDiffVerifier 的用途是给「放手让 Agent 改代码」加护栏——一次动了 40 个文件、 几千行，通常不是任务要求的，而是模型跑偏了。目录不是 git 仓库时直接放行，不阻断流程。

工作区管理（WorkspaceManager）

跟踪 Agent 当前工作区的 Git 状态，让模型了解 cwd、分支、已修改文件等。状态按需刷新（默认 5 秒缓存），不会每轮都跑 git 命令。

工作区状态被格式化为 <workspace> 块，在每次迭代时自动注入系统提示词，让模型知道当前工作目录、分支、已修改文件等上下文。

注意：setWorkdir() 也会自动创建 WorkspaceManager（如果未显式设置），因此已有的 setWorkdir() 调用会自动获得工作区状态跟踪能力。

技能系统（Skills）

技能（Skill）是某项能力或工作流程的详细指令，按目录组织。默认只把「名称 + 描述」注入系统提示词（节省 Context），模型需要时通过 use_skill 工具加载完整正文。

SKILL.md 目录格式

Skills 目录约定为 {dir}/{skill-name}/SKILL.md，支持 frontmatter：

use_skill 工具被自动注册到 Agent 工具注册表，模型调用后加载完整技能正文，同时收集 allowed-tools 中的工具限制（不能突破全局权限）。

技能附件（references/ 等附带文件）

一个技能目录里除 SKILL.md 之外的文件都是它的附带文件：

这不是可有可无的补充：官方 Agent Skills 的渐进披露是两层的，正文往往只写「遇到 X 就去 references/y.md 挑匹配的那一份」，真正的方法论在被引用的文件里。只给正文等于让模型猜文件名。

所以 use_skill 返回的不只是正文，后面还会附一段附件说明：

模型随后用 read_resource 工具读具体附件（与 use_skill 一起由 Agent 运行时自动注册）：

按需发现与场景匹配（Skill 2.0）

技能多起来之后，loadFromDir() 会把每份正文都读进内存。discover() 只解析 frontmatter 登记技能，正文等模型真正 use_skill 时再读盘：

frontmatter 多认两个字段：

没配 files 的技能永远匹配不到——按技能名去猜文件路径太容易误伤，宁可要求显式声明。

技能名很多时：去掉 schema 里的 enum

use_skill 的 schema 默认带技能名 enum（IDE 与模型都能少猜）。技能上百时， 一百多个名字每次工具调用都要重发一遍，可以关掉，把「先检索再加载」的约定留给 description：

子 Agent 的技能子集

宿主用子类扩展过 SkillManager（自建索引、按需发现等）时，取子集要用 subset()—— 它会 clone 出同类型的新实例并保留定义的全部字段（含附件目录），按名 new SkillManager() 重建会把子类行为降级回基类：

项目指令（InstructionManager）

加载项目级指令文件（CLAUDE.md / AGENTS.md），这些是项目必须遵守的长期规则，与 Skill 不同：

加载优先级（后加载的优先级更高）：Global → Project → Subdirectory → Task。指令内容被格式化为 <instructions> 块注入系统提示词。

MCP Runtime（McpManager）

MCP（Model Context Protocol）服务器管理，通过 stdio 子进程运行 MCP 服务器，将 MCP 工具自动注册到 Agent 工具注册表。

每个 MCP 服务器通过独立的子进程运行，通过 JSON-RPC 2.0 over stdio 通信。工具名格式为 {serverName}__{toolName}，避免不同服务器间的工具名冲突。

传输协议：stdio / HTTP / SSE / WebSocket

MCP 是 JSON-RPC 2.0 协议，传输方式可以换。本地工具走 stdio 子进程，远程服务走 HTTP，需要长连接走 WebSocket：

协议 传输方式 适用场景
stdio 子进程 stdin/stdout 本地工具（文件系统、Git、数据库客户端）
HTTP / SSE HTTP POST，响应可为 text/event-stream 远程服务、团队共享的 MCP 服务器
WebSocket 长连接双向通信 需要服务端推送、或一次会话里连续调很多次工具

连接管理——不再是「一次性全起、全关」：

连接失败返回 false 而不是抛异常——一个 MCP 服务器不可用不该让整个 Agent 停下来，具体原因从 getLastError() 取。

HTTP 传输会记住服务端返回的 Mcp-Session-Id 并自动带在后续请求上；SSE 响应里穿插的通知会被跳过，只取 id 对得上的那条。wss:// 需要 openssl 扩展，CDP 与本地 ws:// 不需要。

作用域记忆（MemoryManager）

分作用域的长期记忆管理，支持 user / project / session / task / agent 五个作用域，各有独立的记忆文件。注入系统提示词时按作用域顺序合并，让模型感知不同层级的记忆上下文。

记忆文件持久化在 {baseDir}/{scope}.md，支持追加、覆盖、清空、读取：

记忆检索（MemoryRetriever）

forPrompt() 会把所有作用域的记忆整段注入。记忆攒多了之后这就成了负担：几千字的历史里 可能只有两行和当前任务有关，其余全在挤占上下文。检索器把记忆按行拆成条目， 只注入与当前任务最相关的几条：

设置了 setGoal() 的 Agent 会自动走检索注入；没设目标时退回注入全部记忆，行为与升级前一致。

相关性是纯本地计算，不调模型：英文按词、中文按二元组切分，命中越多、覆盖查询的比例越高分越高。 这套打分认字面不认语义——问「鉴权」匹配不到只写了「登录」的记忆。需要语义检索时换掉打分器：

压缩与过期——长跑任务里记忆会无限增长，定期清理比等到超出 maxInject 被截断更可控：

expire() 只处理带日期前缀的条目（[2026-09-02] ...），没有日期的一律保留—— 分不清写入时间就不该替用户决定它过期了。

模型自主记忆（remember / forget 工具）

自 v1.65 起，remember() 默认给每条记忆加上日期 + 内容散列 id 前缀：

id 取内容散列（非随机/自增），因此同一条内容重复 remember() 天然幂等，不会把 记忆文件撑满。remember($scope, $content, ['date' => false]) 可关掉日期前缀（id 仍写）。 配套的删除按 id 精确进行：

挂了记忆、且是用工具的 Agent（如 codeAgent()）时，库会自动注册 remember / forget 两个工具，让模型主动记录/删除结论。记忆写入属持久副作用，默认经 PermissionManager 把关（dont_ask / bypass 放行）。注入系统提示词时，长期 scope （agent / user / project）常驻、短期 scope（session / task）按目标相关性—— 即便某次检索零命中，长期记忆也不会消失。

自动沉淀默认关闭——自动从每次结果里提炼长期记忆比自动保存会话风险高得多， 必须显式开启：

检查点（CheckpointManager）

每轮迭代结束时自动保存检查点（Checkpoint），Runtime 崩溃后可从最新检查点恢复。每个检查点以 JSON 文件持久化，按任务 ID 分组。

默认保留最近 5 个检查点，超出的旧检查点自动清理。支持过期清理：

崩溃恢复（Crash Recovery）

从崩溃中恢复——加载最新检查点，恢复消息上下文，继续执行。

recoverFromCrash() 内部调用 AgentRuntime::recover()，自动加载最新检查点、恢复迭代计数、设置任务 ID。异常时也会自动保存崩溃时的检查点，防止数据丢失。

长任务恢复：不只是消息历史

小时级甚至天级的任务恢复回来，光有消息历史不够——得知道计划走到第几步、目标是什么，否则模型只能从消息里重新推断。检查点因此会一并保存运行时状态：

检查点里存的内容：消息历史、迭代计数、任务目标、执行计划快照（含每一步的状态）、崩溃时的工作区状态（目录 / 分支 / 已修改文件）、记忆目录。

工作区不会被自动"恢复"：检查点存的是崩溃那一刻工作区长什么样，而磁盘上的文件此刻可能已经不同了，照着旧快照改回去是危险操作。它作为信息交给你比对，要不要动由你决定。

任务队列（AgentQueue）

将任务（Task）+ 运行时（AgentRuntime）按入队顺序排队执行，适用于 PHP-FPM 下需要后台执行的场景。

AgentQueue 内部使用 TaskManager 管理任务生命周期，自动创建或复用外部传入的 TaskManager。

执行计划（PlanManager）

面对复杂任务时，Agent 先把目标拆成有序步骤再动手，而不是「想一步做一步」。计划带状态、依赖与修订历史，可持久化到磁盘，崩溃后继续执行。

步骤状态为 pending → running → completed / failed / skipped；计划状态为 pending → running → completed / failed。

按依赖图执行——步骤可声明依赖，PlanExecutor 只执行依赖已满足的步骤：

计划审查——执行过程中偏离预期时，PlanReview 给出问题与建议，并可直接改计划：

接入 Agent 运行时

PlanManager 挂到 Agent 上之后，计划摘要会在每轮迭代注入系统提示词（<plan> 块）， 模型据此知道整体走到第几步：

plan() 同时把目标写进 setGoal()——反思和记忆检索都用这个目标。

计划可以随任务状态一起落盘，崩溃恢复后接着执行：

自我反思（ReflectionManager）

工具执行完不等于目标达成。ReflectionManager 在每轮工具结果回填后判断「目标是否真的完成」，未完成则给出下一步行动建议，形成「执行 → 检查 → 未完成 → 继续」的闭环。

默认判据按顺序看四条：

  1. 最后一条 assistant 消息带完成标记（「任务完成」「已解决」「all done」…）→ 完成
  2. 最后一批工具结果里还有报错 → 继续修；同一个报错连撞两批则停手，继续重试没有进展
  3. 一个工具都没调过、且还在首轮 → 继续（模型还停在对话阶段）
  4. 其余 → 完成

第 2 条只看最后一批：早先的报错可能已经在后续轮次里修掉了，拿旧报错反复逼模型会一直空转到轮数上限。报错的判定以工具结果的 is_error 标志为准（库回填时一定带），只有调用方手工拼的、没有这个标志的消息才退回关键词扫描——对库产出的结果做关键词扫描会误伤，读一个正文里出现 error 的文件就算报错了。

第 4 条是「模型不再调用工具」这个信号本身：它比任何关键词都可靠。不要按轮次硬逼——回填的那句话不带任何任务信息，模型只会困惑地反问，而那句反问就成了调用方拿到的最终答案，真正的结论被顶掉。

需要模型驱动的反思时注入自定义策略：

maxRounds 是兜底：反思次数达到上限后强制结束，避免模型在「还差一点」的判断里空转。它数的是反思做过几轮（reflection_round），不是 Agent 循环的迭代号（iteration）——两者语义不同，混用会变成「跑到第 N 轮迭代之后反思一律放行」，哪怕工具还在报错。

这道闸排在判据之后：自定义策略永远会被调用，只是它说「还要继续」而轮次已到顶时，由上限收口。（排在前面会让注入的策略在轮次超限后根本不执行，排查时只会怀疑自己的策略写错了。）

接入 Agent 循环

挂到 Agent 上之后，反思发生在「模型不再调用工具、准备收工」的那一刻：目标没达成就把 下一步建议作为 user 消息回填，驱动模型继续干，而不是就此结束。

没调用 enableReflection() 时循环行为与升级前完全一致——不会平白多跑几轮。 setGoal() 未设置时，目标退回取首条用户消息。

开发者 API：三样东西就能开工

用户不需要理解 LoopController / ContextManager / PermissionManager / SubAgentManager——提供 AI、workdir、Prompt 三样东西即可：

链式配置：

AgentResult 的结构化契约：getStatus() / getSummary() / getFilesChanged() / getTests() / getVerification() / getArtifacts() / getSubtasks() / getCost() / getDuration()，toContract() 一次拿全，可直接 JSON 返回给调用方。字段由调用方或 WorkspaceSnapshot 填入——AgentResult 自己不去扫工作区，那是 Workspace 的职责。

工具分组与按需发现

工具多了不该一股脑全发给模型：几十个工具定义塞进每一轮请求，既占 token 又让模型更难选对。

内置分组：filesystem / git / database / network / browser / cloud / testing / deployment。没归过组的工具默认可用——分组用来收窄，不该因为忘了归类就让工具消失。工具属于多个分组时，任一分组启用即可用。

按需发现则反过来：初始只给一小撮常用工具 + 一个 search_tools，模型需要别的能力时自己搜：

搜索是纯本地的关键词匹配（工具名 + 描述），不调模型——为了省 token 而多花一次模型调用不划算。

收窄的是「给模型看什么」，不是「能执行什么」：工具注册表始终保有全量工具（否则搜出来激活了也执行不了），每轮真正发给模型的工具定义由激活集过滤。所以模型这一轮 search_tools 激活的工具，下一轮就能看见并直接调用。

分层权限策略

权限来自四个层面，关系是取交集而不是取并集，并且 DENY 优先：

顺序不能反过来：如果允许下层放宽上层，那么一个被 Skill 声明允许的 Bash(rm -rf *) 就能绕过全局禁令。任务结束时 clearLayer('task')，层与层之间不该互相污染。

事件回放（EventLog）

前端断线重连时要的是「从我收到的最后一条之后继续发」，只重发事件，不重新执行 Agent——重跑会产生新的副作用（再改一遍文件、再跑一遍命令），而客户端要的只是补上漏掉的那几条。

事件 ID 找不到时返回全部——宁可重发也不要漏发，客户端自己去重比丢消息强。不传目录则只在内存里；断线重连场景必须配目录，重连时进程可能已经换了。

调度与并发上限

优先级：critical / high / normal / low，同优先级按提交顺序。一个 PHP 请求不该产生几十个 Agent——每个子 Agent 都是独立的模型调用与上下文，失控的并发既烧钱又会把内存吃满，所以默认上限都很保守。

挂上 TaskGraph 之后只调度依赖已满足的任务。失败自动重试是因为瞬时故障（网络抖动、模型超时）重试一次多半就好了，让人手动重投没有意义。

模型路由与产物管理

让 explorer 用最强的模型去 grep 代码是浪费，让 coder 用最便宜的模型去改架构是省小钱花大钱：

不配置模型名就不路由：返回空串，调用方沿用当前模型。硬塞一个猜的模型名，换来的是运行时报「模型不存在」。

路由器创建后会自动接到子 Agent 管理器上：定义里没写 model 的角色由它选，写死了 model 的以定义为准——显式配置不该被启发式覆盖。选出来的模型跨平台时，凭据从 platforms() 登记的表里按模型名自动匹配：

budget_left / priority 这些只有调用方知道的值，用 setRouteContext() 补进去（传数组是固定值，传闭包则每次路由前取实时值）：

产物（测试报告、补丁、日志、分析结果）不该全文塞进上下文——一份 5000 行的报告扔进去，剩下的对话就没地方了：

产物名会做路径穿越防护，../../../etc/passwd 这类写法进不来。

模型驱动：让模型自己拆计划、自己派子 Agent

编排层用规则在模型看到任务之前决定策略——描述里出现「重构」就先拆计划，撞上某个子 Agent 的 description 就派给它。规则跑得快、可复现，但它看不懂任务：真正该委派的探索识别不出来，碰巧撞词的简单改动反而被派走。

modelDrivenTools() 把这两件事做成工具，交给模型在循环里自己决定：

codeAgent() 会自动挂上这两个工具（它本来就装了 PlanManager 和六个子 Agent），传 ['noModelDrivenTools' => true] 可以关掉。

工具 模型用它做什么
update_plan 写下打算怎么做、每完成一步标成 completed、发现原计划不对就整表改掉
delegate 把需要翻很多文件才能得出一个结论的探索，交给子 Agent 在独立上下文里做，只收回摘要

计划是状态，不是脚本。 关键差别在于模型能在拿到真实结果之后改主意——读了三个文件发现项目里已经有现成的 AuthProvider 基础类，就直接把计划改掉，而不是照着开工前定死的那张表继续走：

每次覆写前的版本都会被快照保留（PlanManager::versions()）——「原计划是什么、为什么改成现在这样」是排查 Agent 走偏的关键线索，直接覆盖就查不到了。想在自己的代码里做同样的整表覆写，用 PlanManager::rewrite($planId, $steps, $reason)。

几条边界：

默认系统提示词

codeAgent() 会装上一份默认系统提示词（CodeAgentPrompt），告诉模型这些工具什么时候该用——工具描述只说明「这个工具做什么」，回答不了「什么时候该用它」。

自己调过 setSystem() 就不会被覆盖：

它讲四件事：动手前先读懂现状；改已有文件一律用 edit_file 增量改（write_file 只用于新建）；三件以上的任务先用 update_plan 写步骤；改完必须实际验证。

这份提示词是实测调出来的。同一个任务（给多文件项目加三个功能并补测试）在真网关上的对比：

无提示词 有提示词 加「批量编辑」一句后
轮数 6 13 9
成本 $0.032 $0.067 $0.053
update_plan 调用 0 次 3 次 2 次
改已有文件的方式 write_file 整体重写 ×3 edit_file ×6 edit_file ×5（并列发出）
测试结果 ALL PASS ALL PASS ALL PASS

三次产出都正确，差别在过程安全性与成本。无提示词那次用 write_file 整体重写了三个已有文件——这次文件小、重写对了，但在几百行的文件上，整体重写正是静默丢代码的经典路径。默认提示词用大约 60% 的成本增量换掉这个风险；补上「想清楚的改动一次全部发出」之后，增量降到约 40%。

嫌贵可以自己换一份更短的提示词，或者干脆 setSystem('')——但那等于回到「模型全靠猜」的状态。

编排层（AgentOrchestrator）

AgentRuntime 回答的是「怎么跑一轮循环」，编排层回答的是「这活该怎么干」——直接调工具、先拆计划、派给子 Agent、并行铺开，还是丢后台。

codeAgent() 一次装齐：内置工具、六个专职子 Agent、默认验证器、执行计划、反思、项目指令。之后一句 task() 就能开工。

七种策略：

策略 何时选中 典型任务
direct 范围明确 「读一下 README」
plan 范围大、含重构/迁移类动词、或带编号步骤 「重构整个用户认证系统」
delegate 与某个子 Agent 的职责匹配 「审查 Auth.php 的安全问题」→ reviewer
parallel 识别到并列的多个子任务 「分析认证、支付、SEO」
background 描述里明确要求后台 「后台扫描整个项目」
ask_user 任务描述为空或无法判断 ——
verify 只是要确认既有改动 「跑一下测试确认没问题」

默认的策略选择是基于关键词的，读不懂任务：「顺便重构一下措辞」会被判成大型重构。useModelStrategy() 把这一步也交给模型：

这是一次小而便宜的模型调用：只要一段 JSON，不给工具、不进 Agent 循环，同一个任务描述会缓存。模型拿不准、返回的不是 JSON、或者调用失败时自动退回规则版——决策失败不该是任务失败。模型点名一个不存在的子 Agent 时降级成 direct 自己干，而不是硬派出去。

决策一定会进事件流（strategy_decision 事件，带 reason）。Agent 自主选策略之后，使用者必须能回答「它为什么这么干」，否则出了问题只能靠猜：

决策与执行是分开的，可以先看再决定要不要照做：

默认选择器是基于规则的，不额外调模型——多花一次模型调用去决定「要不要多花模型调用」不划算，而且规则版的决策可复现、出问题能查。拿不准时一律退回 direct：保守执行的代价是多跑几轮工具，错误委派的代价是一个子 Agent 带着错误上下文跑十几轮。

需要模型驱动时换掉它：

不挂子 Agent 与计划管理器时，所有策略都退回 direct，跑出来跟直接调 run() 一样——编排层是加法，不改变既有行为。

内置子 Agent（BuiltinAgents）

六个开箱即用的专职角色。它们的价值主要不在提示词，而在工具集是收窄的：explorer 拿不到写文件的工具，所以它不可能在「调查代码」的过程中顺手改掉什么。这比在提示词里写「请不要修改代码」可靠得多。

角色 用途 工具
explorer 代码搜索、阅读、调查、依赖分析 read_file / grep / glob
planner 执行计划生成与任务拆解 read_file / grep / glob
coder 代码修改 read_file / write_file / edit_file / grep / glob / bash
tester 运行测试、分析失败 read_file / grep / glob / bash
reviewer 代码审查、安全审查 read_file / grep / glob / bash
debugger 错误分析、问题定位 read_file / grep / glob / bash

子 Agent 完整配置

子 Agent 的能力永远是父 Agent 的子集。 这条是硬约束，不是建议：

三步收窄，每一步都只会让工具变少：起点是子 Agent 声明的 tools（没声明则用父全集）→ 与父工具集求交 → 去掉 disallowedTools。permissionMode 同理，只能往严格方向调：bypass 的父 Agent 下面可以挂 manual 的子 Agent，反过来不行。

model 与连接信息由一个独立的 AI 实例承载（从父实例 clone 而来），父 Agent 的模型与凭据不会被改动，详见下一节。

定义里声明的 background / isolation 是下限：工具入参可以额外开启，但不能关闭。一个被配置成必须 worktree 隔离的子 Agent，不该因为模型没传参就直接改到父工作区。

跨平台编排：不同角色跑在不同平台

用 DeepSeek 写代码、Kimi 审代码、GPT 做规划——三家平台、三把 Key、三个地址，写在一个 Agent 里：

角色多了不必逐个贴 Key——用 platforms() 按平台登记一次，库按模型名推断平台后自动配对：

表的键可以是平台名（同 AI::platformOfModel() 的取值），也可以是具体模型名——模型名精确匹配优先，用于同平台不同模型要走不同网关的情况。已经有配好的 AI 实例时直接给 'ai' => $kimiAi，优先级最高。

可写的连接键：api_key、base_url、endpoint、endpoint_models、protocol、platform、headers、organization、project_id、extra_body，也可以整块塞进 connection。

三条规则，都是为了避免「静默打错平台」：

  1. 写了任何一个连接键，父 Agent 的连接信息就整份不再继承。 半继承最危险——留下父 Agent 的 base_url，Kimi 的模型名会被发到 DeepSeek 的地址上，报回来的是「模型不存在」，没人会往连接信息上想。
  2. 一个连接键都不写时行为与旧版一致：完全沿用父 Agent 的连接，只换模型名。OpenRouter / 自建网关那种「一把 Key 打所有模型」的用法不受影响。
  3. temperature、max_tokens 这类生成参数照常从父 Agent 继承，它们与「打到哪个平台」无关。

子 Agent 拿到的是独立 AI 实例（父实例 clone 而来，注入的 transport 与流式回调跟着走），所以：跑完父 Agent 的模型与 Key 原样不动，并行铺开时几个角色也不会互相踩。凭据不会进 transcript——SubAgentDefinition::toArray() 只列连接的键名，不含值。

完整可运行示例见 examples_multi_platform.php。

任务依赖图（TaskGraph）

父子关系（parentTaskId）表达的是从属，依赖表达的是顺序——两个兄弟任务可以同属一个父任务，却一个必须等另一个跑完。这两件事必须分开表达，否则「B 与 C 并行、D 等 C」这种结构根本写不出来。

失败会向下游传播成 blocked：让一个注定跑不起来的任务留在队列里等，只会浪费一次调度。

软依赖只约束顺序，上游失败也照跑：

会成环的依赖直接被拒绝（dependsOn() 返回 false）——环意味着谁都跑不起来，建图时报错比运行时死锁好查得多。自依赖同理。

与 TaskManager 打通：

后台与并行执行

PHP 没有内置事件循环，「后台执行」在不同部署环境里能做到的程度差别很大。本库把三档路径收在一处，并且如实告知走的是哪一档——悄悄退化成同步执行、却让调用方以为是异步的，比直接说做不到危险得多。

档位 条件 行为
runner 注入了 runner（Swoole / Workerman 协程、队列 Worker） 真异步，立即返回
fork pcntl_fork 可用且未被 disable_functions 禁用 fork 子进程，父进程立即返回
sync 都不可用 同步跑完再返回，但仍返回 task_id，状态机一致

fork 档的结果只能靠落盘传回来，所以 resultDir 不配就取不到结果。runner 如果同步返回了结果，句柄会如实标成 completed 而不是假装还在跑。

并行子 Agent 同样是三档降级（runner / fork / sequential）：

顺序降级档的结果与并行档完全一致，只是不省时间。注入的 runner 返回条数对不上时会退回顺序执行——宁可慢，也不能把结果与任务错位对应。

maxConcurrency 默认 4：一个 PHP 请求不该产生几十个 Agent。

结果聚合（ResultAggregator）

并行派出去三个 explorer，回来三份几千字的报告。主 Agent 默认只该收到摘要，完整内容留在各自的 transcript 里按需查——否则并行省下的时间，全赔在被污染的上下文里了。

默认是规则聚合（截断 + 归类 + 去重），不调模型。需要更好的摘要时注入模型摘要器——但那要多花一次调用，默认不替使用者做这个决定：

摘要器抛异常时会退回规则拼接，不会因为摘要挂了把结果整个丢掉。

子 Agent transcript 落盘与续跑

不配 transcriptDir 时 transcript 只在内存里，进程结束即丢——后台任务与崩溃恢复都需要它能被另一个进程读到，所以长任务场景必须配。

验证闸门与完成判据

不能因为模型说「完成了」就算完成。 模型判断自己是否达成目标是出了名的乐观：测试还红着、计划还剩三步、上一次工具调用还在报错，它照样会说「已完成」。

闸门按任务类型选不同的验证链——一套验证跑遍所有任务，要么太松（漏掉该验的）要么太紧（改个错别字也跑全量集成测试）：

任务类型 验证链 识别关键词
bug_fix 语法 → 单元测试 修复 / 报错 / bug / fix
feature 语法 → 安全 → 单元测试 新增 / 实现 / 支持 / implement
refactor 语法 → 测试 → 改动规模检查 重构 / 重写 / refactor
security 语法 → 安全（必过） → 测试 安全 / 漏洞 / 注入 / injection
default 语法 + 安全 认不出来时用它

策略里写了但没挂对应验证器的步骤会被跳过并记录，不会让整条链卡住。failFast 默认开启：必过项一失败就停，不再白跑后面的。

四条内置判据：verification_passed（没跑过验证 = 未满足，说「没验证所以算通过」就等于没有这道闸门）、no_pending_steps、no_pending_errors、model_claims_done。也可以注册自定义判据：

预设：CompletionCriteria::lenient()（只看有没有报错，适合没测试没计划的轻量任务）、::strict()（四条全要）。

任务交接（AgentHandoff）

Coder 改到一半发现是数据库结构的问题，把任务转给 DBA；后者处理完再转回来。交接必须留痕——否则一个任务在几个角色之间转了几圈之后，没人说得清它经历过什么。

交接会自动向接手方投递一条 handoff 消息，对方下次被分派任务时，收件箱里就带着「谁交给我的、为什么、进展到哪」。

消息类型也补齐到九种：原有的 task / bug / review / status / result，新增 request / response / error / handoff。回应会自动带上 reply_to——一个角色同时问了三件事时，没有这个字段就分不清答复对应哪个问题：

跨 Session 消息（SessionBus）

AgentCommunication 管的是一个团队内部、同一个进程里的消息。跨 Session 是另一回事：后台 Agent 在另一个进程（甚至另一次 PHP 请求）里跑完，得让主 Session 知道。那条消息必须落盘才传得过去——内存里的队列，另一个进程根本看不见。

订阅回调只在本进程内 send() 时触发——跨进程投递的消息，另一端得靠 receive() 主动取。PHP 没有常驻的进程间推送通道，这一点无法回避。

不传目录时退化成纯内存模式，只在同进程内可用；后台任务通知必须配目录，否则消息发出去没人收得到。

计划版本链

modifyPlan() 不再原地覆盖，而是产生新版本。「原计划是什么、为什么改成现在这样」是排查 Agent 走偏的关键线索，直接覆盖就查不到了。

工作区快照（WorkspaceSnapshot）

任务开始拍一张，结束再拍一张，两张一比就知道这个任务到底改了什么——而不是听模型自己报「我改了 Auth.php」。模型漏报和多报都很常见，尤其在它中途改了主意又改回去的时候。

快照内容：cwd、分支、commit、已修改文件、未跟踪文件、工作区 diff 哈希。不是 git 仓库时快照仍然可用，只是 branch / commit / diff_hash 为空——能记的记下来，记不了的留空，不猜。

Worktree 收尾：合入或丢弃

子 Agent 在隔离的 worktree 里改完、diff 拿回来了，接下来要么合入要么丢弃：

用 git apply 打补丁而不是 merge 分支——worktree 里的改动通常没提交，没有 commit 可合。

Skill 生命周期与依赖

SKILL.md 多认两个字段：

required_tools 里的工具当前拿不到时，这个技能加载了也用不了——与其让模型按技能指示去调一个不存在的工具，不如提前说清楚。

指令就近发现

从文件所在目录向上找到项目根，沿途的指令文件按「远的在前、近的在后」加载——离当前文件最近的规则优先级最高，因为它最具体。识别 CLAUDE.md / AGENTS.md / AI.md / .ai/AGENTS.md。

projectRoot 是向上查找的边界：没有边界的话会一路找到文件系统根，把别的项目甚至用户主目录的规则也拉进来。已加载过的路径会跳过——同一份规则注入两遍不会让模型更遵守它，只会白占上下文。

记忆整理（MemoryConsolidator）

不要让所有工具结果自动进记忆。 那样记忆很快会变成一堆噪音：读过的每个文件、跑过的每条命令都在里面，真正重要的两三条反而被淹没。

候选不会立刻写盘——consolidate() 之前它们只在内存里排队。这一步存在的意义就是「攒一批再筛」：单条判断谁重要很难，一批放一起比较就容易多了。

去重用检索器的相关性打分做近似判断，说的是同一件事就不重复写。敏感内容用筛选器挡掉：

多角色团队（AgentTeam）

从「父 Agent 派生子 Agent」升级为「一组各司其职的角色协作」。区别在于成员是长期存在的：Developer 改完代码，Tester 拿到的是同一轮任务的上下文，Reviewer 能看到前两者的结论。

内置五个角色：manager / developer / tester / security / reviewer，各自的系统提示词写明了职责边界——比如 Tester 的提示词明确「发现问题时给出复现步骤，不要自己去改实现代码」，否则多角色协作很容易退化成每个角色都在改代码。

自定义角色，并按角色收窄工具：

成员共享团队统一的工具集与权限配置，但各自持有独立的 AgentRuntime 与上下文——这正是多角色的意义：Tester 的上下文里不该塞满 Developer 的思考过程。

某个成员抛异常时记为 status = failed 继续往下走，不会中断整条流水线——Reviewer 知道 Tester 挂了，比什么都不知道有用。

Agent 间通信（AgentCommunication）

成员之间的消息在总线上投递与留存。纯文本传递会丢类型与来源，收到的一方分不清这是任务分派还是结果汇报，type 字段就是为此存在的。

消息类型：task（任务分派）/ bug（缺陷反馈）/ review（审查意见）/ status（状态同步，默认广播）/ result（执行结果）。

分派任务时收件箱里的未读消息会自动拼在任务描述前面——上一环留给他的话，不该等他自己去问。全量历史留在 history() 里供事后复盘：多角色协作出问题时，光看最终结果判断不出是哪一环传歪了。

人工审批（ApprovalWorkflow）

AI 改完代码不直接算数：先提交审核（附 diff），等人批准才继续，驳回则带着理由退回去改。企业环境里这是硬要求——没有人签字的自动改动进不了生产。

$workflow = $agent->enableApproval('/var/data/approvals');

// AI 侧：改完提交
$request = $agent->submitForApproval($diff, [
    'summary' => '修复登录 401',
    'files'   => ['src/Auth.php'],
]);

// 人工侧：另一个进程 / 后台页面
foreach ($workflow->getPendingRequests() as $req) {
    echo $req->toSummary();      // 摘要 + 涉及文件 + diff
}
$workflow->approve($request->getId(), '张三');
// 或：$workflow->reject($request->getId(), '缺少输入校验', '李四');

// AI 侧：拿结果
$status = $workflow->getStatus($request->getId());   // approved / rejected / pending_review / expired
if ($status === \Ai\Agent\Approval\ApprovalRequest::STATUS_REJECTED) {
    $agent->ask($workflow->getRequest($request->getId())->toRejectionPrompt());
}

审批天然跨进程：提交的是 Agent，批准的是人，中间可能隔几小时。所以传了目录时请求会落盘，getStatus() 每次都从磁盘重读——只看内存副本会一直看到 pending，Agent 崩了重启也能接着等。不传目录则只放内存，适合同进程内的交互式确认。

其它能力：

$workflow->waitFor($id, 300);              // 阻塞等待，超时返回当前状态而不是无限期挂着
$workflow->onSubmit(function ($req) { … }); // 提交时发邮件 / 飞书 / 建工单
$workflow->purgeDecided();                  // 清掉已处理与已过期的
new ApprovalWorkflow('', ['ttl' => 3600]);  // 请求 1 小时后过期
new ApprovalWorkflow('', ['autoApprove' => true]);  // 本地调试用，自动过审

已处理或已过期的请求不能再批——审批结果只能出一次。一个三天前提的审批不该还能被批准，所以设了 ttl 的请求过期后状态直接变成 expired，不必等谁来清理。

浏览器工具（BrowserTool）

让 Agent 操作真实浏览器：打开页面、点击、填表、截图、提取内容。跟 HTTP 抓取的区别是这里跑的是 Chrome——JS 渲染出来的内容、登录后的状态、前端路由，抓 HTML 拿不到的这里都拿得到。

use Ai\Agent\Tools\BrowserTool;

$agent->addTool(new BrowserTool(['headless' => true]));

// 模型调用：
//   browser(action: "open", url: "https://example.com")
//   browser(action: "wait", selector: "#results")
//   browser(action: "type", selector: "#q", text: "php")
//   browser(action: "click", selector: "button[type=submit]")
//   browser(action: "extract", selector: ".result")
//   browser(action: "screenshot", path: "shot.png", full_page: true)
//   browser(action: "close")

会话是复用的：一次 open 之后，后续 click / type 都在同一个页面上，登录态和页面状态都还在。

直接用 BrowserSession：

use Ai\Agent\Tools\BrowserSession;

if (!BrowserSession::isAvailable()) {
    echo '本机没装 Chrome / Chromium';
}

$session = new BrowserSession(['headless' => true, 'timeout' => 30]);
$session->launch();
$session->navigate('https://example.com');
echo $session->title();
echo $session->text('h1');
print_r($session->extractAll('.item', 20));
$session->waitFor('#ready', 5000);
$session->evaluate('document.querySelectorAll("a").length');
$session->screenshot('/tmp/shot.png', true);
$session->close();

实现走 Chrome DevTools Protocol：--remote-debugging-port 起一个常驻 headless 实例，用 CDP 的 HTTP 端点拿页面目标，用 WebSocket 发命令。点击与输入通过页面内 JS 完成（输入后会派发 input / change 事件，否则 Vue / React 收不到值变化），不是模拟鼠标坐标——坐标点击遇到滚动和浮层就不准了。

前置条件：本机装了 Chrome / Chromium，且允许 proc_open。没装时工具返回明确的错误信息而不是抛异常——模型看到「没有浏览器」可以换个办法，看到崩溃则只能重试。CDP 走本地 ws://，不需要 openssl 扩展。

传入 PathSafety 后截图路径受工作区限制：

$agent->addTool(new BrowserTool([], new \Ai\Agent\Tools\PathSafety('/var/www/project')));

浏览器授权工具（BrowserGrantTool）

BrowserTool 拉起的是服务端自己的浏览器；这个取的是用户那台浏览器的驱动权——扩展装在里面、登录态是他的、窗口就在他眼前。凭据不能凭空要，得让用户亲自点一次确认，所以走「匿名票据」流程：

use Ai\Agent\Tools\BrowserGrantTool;

$agent->addTool(new BrowserGrantTool('https://example.com', ['app' => 'MCI AI Agent']));

// 模型调用：
//   browser_authorize(action: "start")                      → 申请票据，把授权链接经事件交出去
//   browser_authorize(action: "status")                     → 用户确认后取回 device + 密钥
//   browser_authorize(action: "status", wait_seconds: 60)   → 在服务端等一会儿再问，别空转多次
//   browser_authorize(action: "credential")                 → 看本地已存的凭据（不回密钥明文）
//   browser_authorize(action: "forget")                     → 清掉本地凭据与待确认票据

新标签页由宿主打开：后端开不了用户的浏览器。start 会 emit 一个 browser_authorize 事件（带 authorize_url / app / expires_in），宿主的 SSE / WebSocket 前端据此 window.open(authorize_url)；用户确认后 status 再 emit browser_credential（只带 device / 密钥前缀，不带明文）。

授权天然跨轮次——用户可能在下一轮才去点确认。所以票据与凭据落在按身份隔离的目录里（有 userId 走 users/<hash>/，否则退到 projects/<slug>/），目录 0700、文件 0600；密钥明文只在取回那一次交给模型，本地留档是给后续步骤用的。身份不明（storageDir 为空，既没 userId 也没 sessionId）时工具拒绝写盘并说明原因——两个身份共用一份能驱动浏览器的密钥，比没有凭据更糟：

$agent->setUserId('admin:7')->setSessionId('sess-1');   // 至少给一个，才有地方安全地放凭据

wait_seconds 有上限（默认 120，最多 300），且会响应取消——用户点停止时不会继续在服务端干等。

浏览器操作工具（MciBrowserTool）

上面那个只把凭据取回来，之后怎么驱动浏览器还得自己接；MciBrowserTool 把「授权」与「操作」收进同一个工具名，模型只记一件事：

use Ai\Agent\Tools\MciBrowserTool;

$agent->addTool(new MciBrowserTool('https://example.com', ['app' => 'MCI AI Agent']));

// 调用方若知道「用户此刻正在用的那台」，经 client_device 传进来更准（可选）：
// 页面从扩展写在 <html data-mci-device> 上的设备号读来，随消息一起交过来。
// $agent->addTool(new MciBrowserTool('https://example.com', [
//     'app'           => 'MCI AI Agent',
//     'client_device' => 'd5708b07f',
// ]));

// 授权那一半（没凭据时先做；与 browser_authorize 同名同义，原样委托过去）：
//   mci_browser(action: "authorize")                       → 弹确认页，取票据
//   mci_browser(action: "grant", wait_seconds: 60)          → 用户确认后取回 device + 密钥
//
// 操作那一半（有凭据即可，直通站点 /Browser/Api/*）：
//   mci_browser(action: "devices")                          → 哪几台浏览器在线
//   mci_browser(action: "open", url: "https://example.com") → 后台开一个标签页
//   mci_browser(action: "text", selector: "h1")             → 读正文
//   mci_browser(action: "eval", expression: "document.title") → 执行 JS 取回结果
//   mci_browser(action: "screenshot")                       → 截图直接进上下文

动作共 25 个：查看类 devices / tabs / url / text / html / form / metrics / console / network / cookies / quota，操作类 open / click / type / press / scroll / select / wait / reload / back / forward / close / activate，脚本类 eval / screenshot。

几处刻意的取舍：

代码理解（CodeAnalyzer）

Agent 改代码前得先看懂代码。Ai\Code 扫描项目建立类索引与两张关系图——谁调用了谁、谁依赖了谁——之后回答「改这个方法会影响谁」不用再 grep 整个项目。

use Ai\Code\CodeAnalyzer;

$analyzer = new CodeAnalyzer();
$analyzer->scan('/var/www/project/src');

print_r($analyzer->stats());
// ['files' => 189, 'classes' => 189, 'methods' => 2107, 'callEdges' => 3604, 'dependencyEdges' => 422]

$analyzer->findCallers('login');                       // 谁调用了 login
$analyzer->findDependencies('App\Auth');               // Auth 依赖谁
$analyzer->findDependents('App\Auth', true);           // 谁（间接）依赖 Auth —— 改动影响面
$analyzer->findRelatedFiles('src/Auth.php');           // 该一起看的文件
$analyzer->findSymbol('login');                        // 符号定义在哪个文件第几行

explain() 生成一段可直接注入提示词的类说明，比把整个类的源码塞进上下文省得多，而且带上了单看源码看不到的「谁依赖我」：

echo $analyzer->explain('App\Service\Auth');
// class App\Service\Auth extends App\Service\BaseAuth implements App\Contract\AuthInterface
//   file: src/Service/Auth.php:23
//   public function login($name, $password = ...): bool   # line 41
//   protected function verify($user, $password): bool     # line 47
//   依赖: App\Model\User, App\Support\Token
//   被依赖: App\Http\LoginController
//   继承链: App\Service\BaseAuth
//   子类: App\Service\AdminAuth

单文件分析——不建索引也能用：

use Ai\Code\FileAnalyzer;

$analysis = (new FileAnalyzer())->analyze('src/Auth.php');
echo $analysis->getNamespace();                    // 'App\Service'
print_r($analysis->getImports());                  // ['User' => 'App\Model\User', ...]
$class = $analysis->getMainClass();
echo $class->getParent();                          // 父类完整名（已按 import 解析）
print_r($class->getMethods());                     // 方法名 => FunctionAnalysis
echo $class->getMethod('login')->getSignature();   // 'public function login($name, $password = ...): bool'

两张图——CallGraph 与 DependencyGraph 也能单独用：

$analyzer->callGraph()->impactOf('App\Auth::login');      // 直接间接会调到 login 的函数
$analyzer->callGraph()->unreferenced();                   // 没有调用方的函数（候选死代码）
$analyzer->dependencyGraph()->detectCycles();             // 循环依赖
$analyzer->dependencyGraph()->mostDepended(10);           // 被依赖最多的类 —— 改它风险最高
$analyzer->dependencyGraph()->layers();                   // 按依赖深度分层
$analyzer->classAnalyzer()->allMethods('App\Auth', $analyzer->index());  // 含继承与 trait 的方法表

精度说明：解析基于 token_get_all()，不依赖任何第三方 parser。能认命名空间、import（含成组导入与别名）、继承实现、方法签名（参数类型、可空、可变参数、返回类型）、属性可见性、类常量、函数体内的调用。

认不了的：变量的实际类型。$obj->save() 拿不到 $obj 是什么类，图里记的是 ->save，查 save 的调用方时所有类的同名方法会一起命中。结果是「可能的调用方」，用来缩小排查范围可以，当作重构的唯一依据不行。 动态调用（$class::$method()）与 eval 里的代码同理，静态扫描看不见。

代码索引工具（CodeIndexTool）

把 Ai\Code\CodeAnalyzer 的能力交给 Agent：一次扫描，反复查询。explorer 调查一个类时不必每次都 grep 全项目，也不必把整个类的源码读进上下文。

$agent->addTool(new \Ai\Agent\Tools\CodeIndexTool('/var/www/project/src'));

// 模型调用：
//   code_index(action: "explain", target: "App\Auth")        类结构 + 继承链 + 谁依赖它
//   code_index(action: "callers", target: "login")           谁调用了它
//   code_index(action: "dependents", target: "App\Auth")     改动影响面
//   code_index(action: "related", target: "src/Auth.php")    该一起看的文件
//   code_index(action: "symbol", target: "login")            定义在哪一行
//   code_index(action: "stats")                              索引规模
//   code_index(action: "refresh")                            改过文件后重建索引

codeAgent() 会自动装上它，explorer / planner / reviewer / debugger 四个内置角色也都带着它——它们的活就是「先看懂再说」。

索引是惰性建立的（首次调用时扫描），之后常驻内存。改过文件要 refresh，否则查到的还是旧结构。

工具返回里会带上精度提醒：$obj->save() 拿不到接收者的真实类型，查 callers 时同名方法会一起命中。这是静态扫描的固有限制，结果是「可能的调用方」。

项目索引（RepositoryIndexer）

首次进入一个项目时扫一遍结构，认出框架、入口、控制器 / 模型 / 服务 / 配置在哪，存成 project.index.json。之后 Agent 直接读索引，不用每次都把项目结构重新摸一遍。

use Ai\Agent\Code\RepositoryIndexer;

$indexer = new RepositoryIndexer();
$index = $indexer->ensureIndex('/var/www/project');   // 有且没过期就复用，否则重建

echo $index->getFramework();        // 'Laravel'
echo $index->getEntry();            // 'public/index.php'
print_r($index->getFiles('controllers'));
print_r($index->getNamespaces());   // ['App\' => 'app/']
echo $index->toSummary();           // 注入提示词的 <project> 块

框架识别先看 composer 依赖，再看目录特征，覆盖 Laravel / Symfony / CodeIgniter / ThinkPHP / Yii / CakePHP / Laminas / Slim / WordPress。认不出来时返回空串而不是猜——猜错会让模型按错误的约定去找文件，比不知道更糟。

索引过期的判据是 ttl（默认 1 天）或 composer.json 变新，不逐个文件比 mtime——大项目上那样太慢。文件分类是按路径与文件名的启发式判断（app/Http/Controllers/Auth.php → controllers），不读文件内容。

用户交互（AskUser）

当任务描述不明确、存在多个合理执行方案或涉及关键选择时，Agent 可以向用户提问，而不是自行猜测。这与 Permission 有本质区别：

use Ai\Agent\Interaction\UserInteractionManager;

$uim = new UserInteractionManager();

$agent
    ->setUserInteractionManager($uim)
    ->setTools([...]);

$result = $agent->getRuntime()->run($messages);

// 暂停后等待用户回答
if ($result->getStopReason() === 'waiting_user') {
    $questionId = $result->getExtra()['question_id'] ?? '';
    $answer = 'main';  // 用户的选择

    // 回答后恢复执行
    $result = $agent->answerUser($questionId, $answer, $messages);
    echo $result->getText();
}

Agent 会在需要时调用 ask_user 工具，暂停并等待用户回答。answerUser() 将答案回填给模型继续执行。

钩子系统（Hooks）

在 Agent 执行链的关键节点注入自定义逻辑，无需修改核心工具。钩子覆盖完整的生命周期：工具执行前后、模型调用前后、权限请求、任务、子 Agent、上下文压缩、会话启停。

$agent
    // 工具执行前调用：返回 ToolResult 可短路执行（跳过实际工具）
    ->onBeforeTool(function ($name, $input, $ctx) {
        if ($name === 'bash') {
            // 记录所有 bash 命令到审计日志
            return null; // 返回 null 继续执行
        }
    })
    // 工具执行后调用：可修改/包装结果
    ->onAfterTool(function ($name, $result) {
        return $result;
    })
    // 模型调用前调用：可修改请求参数
    ->onBeforeModel(function ($messages, $tools) {
        // 注入额外的系统消息或过滤敏感数据
        return ['messages' => $messages, 'tools' => $tools];
    })
    // 模型调用后调用：可记录响应或注入额外数据
    ->onAfterModel(function ($resp) {
        return $resp;
    });

完整钩子及签名：

钩子 注册方法 签名 触发时机
before_tool onBeforeTool (string $name, array $input, ToolContext $ctx): ?ToolResult 工具执行前；返回 ToolResult 则短路，不执行实际工具
after_tool onAfterTool (string $name, ToolResult $result): ToolResult 工具执行后；可修改/包装结果
tool_error onToolError (string $name, ToolResult $result): void 工具执行出错后（或权限拒绝时）
after_tool_batch onAfterToolBatch (array $results): array 一批工具全部执行完成后、下一次模型调用前；可统一审计/刷新状态
before_model onBeforeModel (array $messages, array $tools): array 模型调用前；返回 ['messages'=>..., 'tools'=>...] 修改请求参数
after_model onAfterModel ($response): $response 模型调用后；可修改/记录响应
permission_request onPermissionRequest (string $toolName, array $input, string $requestId): HookResult 权限请求创建时；返回 HookResult 可表达处理意见
task_start onTaskStart (string $taskId, string $goal): void 任务开始执行
task_complete onTaskComplete (string $taskId, string $result): void 任务正常完成
task_failed onTaskFailed (string $taskId, string $error): void 任务执行失败
subagent_start onSubagentStart (string $agentName, string $task): void 子 Agent 启动
subagent_stop onSubagentStop (string $agentName, string $result): void 子 Agent 结束
before_compact onBeforeCompact (int $tokenCount, int $messageCount): void 上下文压缩前
after_compact onAfterCompact (int $messageCount): void 上下文压缩后
agent_start onAgentStart (): void Agent 循环开始
agent_stop onAgentStop (string $stopReason): void Agent 循环结束（携带停止原因）

onTaskFailed / onAgentStart / onAgentStop 三个钩子不在 Agent 的快捷方法里，需要直接注入钩子容器：

use Ai\Agent\Hooks\AgentHooks;

$hooks = new AgentHooks();
$hooks->onTaskFailed(function ($taskId, $error) {
    log_message('error', "任务 {$taskId} 失败：{$error}");
});
$hooks->onAgentStart(function () {
    echo 'Agent 开始执行';
});
$hooks->onAgentStop(function ($stopReason) {
    echo "Agent 停止：{$stopReason}";
});

$agent->getRuntime()->setHooks($hooks);

HookResult：钩子统一返回值

Ai\Agent\Hooks\HookResult 是钩子的统一返回类型，支持五种动作：

动作 工厂方法 说明
CONTINUE HookResult::go() 继续执行（默认）
ALLOW HookResult::allow() 放行
DENY HookResult::deny($reason) 拒绝，附理由
MODIFY HookResult::modify($data) 修改输入后继续
STOP HookResult::stop($reason) 停止 Agent 
use Ai\Agent\Hooks\HookResult;

$hooks->onPermissionRequest(function ($toolName, $input, $requestId) {
    if ($toolName === 'bash' && strpos($input['command'], 'DROP TABLE') !== false) {
        return HookResult::deny('禁止执行 DROP TABLE');  // 拒绝并说明理由
    }
    return HookResult::go();                              // 继续默认流程
});

HookResult 提供 getAction() / getReason() / getData() 与 isContinue() / isAllow() / isDeny() / isModify() / isStop() 判断方法。

执行顺序

钩子按固定顺序接入执行链：

Model
 ↓
Tool Call
 ↓
before_tool（可短路）
 ↓
Permission
 ↓
Tool 执行
 ↓
tool_error（出错时）/ after_tool
 ↓
after_tool_batch（整批完成后）
 ↓
Tool Result 回填
 ↓
Model

注意：钩子的放行不能绕过硬性权限拒绝。权限优先级保持 Deny 规则 → Permission Deny → Allow → Ask，before_tool 只能短路「将要执行的工具」，不能解除权限系统已做出的拒绝。

任务系统（Task）

Agent 任务系统将「整个用户目标」与「每一轮模型交互」分离。一个 Task 包含多个 Turn，支持完整的生命周期管理。

核心组件：

use Ai\Agent\Task\TaskManager;

$tm = new TaskManager();

// 创建任务
$task = $tm->create('修复登录问题', 'sess_abc');

// 通过 AgentRuntime 执行任务
$result = $tm->start($task->getId(), $runtime, $messages);

// 生命周期控制
$tm->pause($task->getId());
$tm->resume($task->getId());
$tm->cancel($task->getId());

TaskState 进度记录

TaskState 记录详细执行进度，适合注入 Context Compaction 后的系统提示词，让 Agent 在上下文压缩后仍知道任务状态：

use Ai\Agent\Task\TaskState;

$state = new TaskState(['goal' => '修复登录问题']);
$state->addCompleted('找到 Auth.php');
$state->addPending('运行 PHPUnit');
$state->addModifiedFile('Auth.php');
$state->addImportantFact('session 过期时间设置错误');

// 生成进度摘要
echo $state->toSummary();
// # 任务状态
// 目标：修复登录问题
//
// ## 已完成
// - 找到 Auth.php
//
// ## 待处理
// - 运行 PHPUnit
//
// ## 修改的文件
// - Auth.php
// ...

通过 Agent 注入 TaskManager

$agent = (new Agent($ai))
    ->setSystem('助手')
    ->setTaskManager($tm)        // 注入任务管理器
    ->setTaskId($task->getId());  // 关联当前任务

$agent->run($messages);
// 任务完成后自动标记为 completed 或 failed
// 同时发出 task_start / task_complete / task_failed 事件

任务生命周期事件可通过 onEvent() 接收：

事件 说明
task_start 任务开始执行
task_complete 任务正常完成
task_failed 任务执行失败（含异常/错误）

运行时架构

v2.0 内部结构：

Agent（对外 API）
  ├── setTools() / setSystem() / onEvent() / setMaxIter() / run()
  ├── setPermissionMode() / setSessionId() / setMaxBudget()
  ├── setFallbackModels() / setToolTimeout()
  ├── setTaskManager() / setTaskId()                   ← 任务系统
  ├── setUserInteractionManager()                      ← 用户交互
  ├── setVerification()                                ← 验证管理
  ├── setWorkspaceDir()                                ← 工作区管理
  ├── loadSkills() / setSkillManager()                 ← 技能系统
  ├── loadInstructions() / setInstructionManager()     ← 项目指令
  ├── setMcpServers() / setMcpManager()                ← MCP Runtime
  ├── setMemoryDir() / setMemoryManager()              ← 作用域记忆
  ├── setCheckpointDir() / recoverFromCrash()          ← 检查点 / 崩溃恢复
  ├── approve() / deny()                              ← 用户授权
  ├── answerUser()                                    ← 回答用户提问
  ├── onBeforeTool() / onAfterTool()                  ← 工具钩子
  ├── onToolError() / onAfterToolBatch()              ← 工具错误 & 批量后置钩子
  ├── onBeforeModel() / onAfterModel()                ← 模型钩子
  ├── onPermissionRequest()                           ← 权限钩子
  ├── onTaskStart() / onTaskComplete()                ← 任务钩子
  ├── onSubagentStart() / onSubagentStop()            ← 子 Agent 钩子
  ├── onBeforeCompact() / onAfterCompact()            ← 上下文压缩钩子
  └── getRuntime() ─────────────────────────────────→  AgentRuntime（执行引擎）
        ├── ToolRegistry（工具注册表）                  ← AgentToolInterface 注册
        ├── ToolExecutor（工具执行器）                  ← 重试 / 超时 / 输出截断
        ├── LoopController（自循环控制器）              ← 驱动主循环（含降级模型）
        ├── LoopGuard（防死循环守卫）                   ← 重复调用检测 + 结果级进展检测
        ├── ParallelToolExecutor（并行执行器）           ← 并行安全工具
        ├── PermissionManager（权限管理器）              ← 6 种模式 + 规则匹配
        ├── ContextManager（上下文管理器）               ← Turn-aware 自动压缩
        ├── SessionManager（会话管理器）                 ← 持久化 / 暂停 / 恢复
        ├── BudgetManager（预算管理器）                  ← token / 成本控制
        ├── VerificationManager（验证管理器）            ← 工具执行后自动验证
        ├── WorkspaceManager（工作区管理器）             ← Git 状态跟踪
        ├── SkillManager（技能管理器）                   ← 技能目录 + use_skill / read_resource 工具
        ├── InstructionManager（项目指令管理器）          ← CLAUDE.md / AGENTS.md
        ├── McpManager（MCP 管理器）                    ← stdio JSON-RPC 工具
        ├── MemoryManager（记忆管理器）                  ← 分作用域长期记忆
        ├── CheckpointManager（检查点管理器）            ← 每轮 checkpoint 自动保存
        ├── SubAgentManager（子 Agent 管理器）           ← spawn_agent 工具
        ├── TaskManager（任务管理器）                   ← 任务生命周期（AgentTask / TaskState）
        ├── UserInteractionManager（用户交互管理器）      ← ask_user 工具
        └── AgentHooks（钩子系统）                      ← 完整生命周期钩子：before/after_tool、tool_error、
                                                         after_tool_batch、before/after_model、
                                                         permission_request、task_start/complete/failed、
                                                         subagent_start/stop、before/after_compact、
                                                         agent_start/stop

通过 $agent->getRuntime() 可访问全部内部组件，实现高级定制。

停止原因（StopReason）

Agent 停止时可通过 $result->getStopReason() 获取原因：

常量 值 说明
END_TURN end_turn 模型给出最终回答，正常结束
MAX_ITER max_iter 已达最大迭代次数上限
NO_PROGRESS no_progress 连续重复调用同一工具，无进展
TOOL_ERROR tool_error 工具执行出错
USER_CANCEL user_cancel 用户取消
BUDGET_EXCEEDED budget_exceeded 预算超限
TIMEOUT timeout 超时
PERMISSION_DENIED permission_denied 权限被拒绝或等待用户授权
WAITING_USER waiting_user 等待用户回答问题（ask_user）
MODEL_ERROR model_error 模型返回错误

Agent Tool 标准与 Tool Registry

把传统 PHP 应用已有的、已经受权限控制的业务能力标准化成 Agent 可以发现和调用的 Tool——不重写业务逻辑，不新建一套权限系统。

Controller / Service + @agent-tool 标注
        ↓  php-ai index
SQLite Tool Registry（FTS5 全文索引）
        ↓  search_app_tools / get_app_tool
Agent 按需加载 Tool Schema
        ↓  call_app_tool
应用现有 Controller 入口权限校验   ← 唯一的安全边界
        ↓
Controller / Service → 业务数据库

一句话原则：让 AI 能够发现应用有什么能力，但永远不能自行决定这些能力是否有权执行。

为什么需要它

Agent 接业务系统时通常有两条路，都不好走：

这套方案走第三条：能力目录进数据库，模型按需搜索、按需加载，执行时回到应用原有的 Controller 入口。

三行接入

use Ai\Agent\Indexer\ToolIndexer;
use Ai\Agent\Registry\SqliteToolRegistry;
use Ai\Agent\Registry\CallableControllerGateway;
use Ai\Agent\Discovery\RegistryToolBridge;
use Ai\Agent\Registry\ToolSearchContext;

// 1. 发布阶段：扫描应用，写入 Registry（也可以用 CLI: php-ai index）
$registry = new SqliteToolRegistry(APP_PATH . '/.ai/registry.sqlite');
(new ToolIndexer($registry))->scan([APP_PATH . '/Controller', APP_PATH . '/Service']);

// 2. 运行时：告诉 php-ai 怎么走你现有的 Controller 入口
$gateway = new CallableControllerGateway(function ($path, array $args, array $ctx) {
    // ⚠️ 这里必须跑你现有的权限校验，它是最终安全边界
    if (!$auth->check($ctx['user_id'], $path)) {
        throw new \RuntimeException('无权访问 ' . $path);
    }
    return $router->dispatch($path, $args);
});

// 3. 接进 Agent
$bridge = new RegistryToolBridge($registry, $gateway);
$bridge->setContext(new ToolSearchContext([
    'user_id'     => $user->id,
    'permissions' => $auth->permissionsOf($user),   // 可选：Discovery 阶段的候选过滤
]));

$agent->tools($bridge->tools());

完整可运行的演示见 examples_tool_registry.php（自带样本应用与临时数据库，跑完自清理，不需要 API Key）。

PHPDoc 标注标准

在已有的 Controller / Service 方法上加几行注释即可，业务代码一行不用改：

/**
 * 修改文章
 *
 * @agent-tool article.update
 * @agent-description 修改指定文章的标题、摘要和正文
 * @agent-controller article/update
 * @agent-risk medium
 * @agent-confirm false
 * @agent-keywords 文章,编辑,标题
 *
 * @param int $id 文章 ID
 * @param string|null $title 文章标题
 * @param string|null $content 文章正文
 * @return array 修改后的文章
 */
public function update($id, $title = null, $content = null)
{
    // 原有业务逻辑，不用改
}
标签 必需 说明
@agent-tool ✅ Tool 名，推荐 资源.动作（article.update）而不是类名方法名——类改名不会影响 Agent
@agent-controller ✅ 映射到的现有 Controller 入口路径，权限与执行都走它
@agent-description 否 给模型看的能力描述；不写则取 docblock 首行摘要
@agent-risk 否 low / medium / high / critical，默认 low
@agent-confirm 否 true / false，覆盖风险等级推导出的确认要求
@agent-permission 否 可多次出现；仅用于 Discovery 候选过滤，不是授权依据
@agent-keywords 否 逗号分隔的补充搜索词（中文同义词很有用）
@agent-enabled 否 false 可临时下线某个能力
@agent-version 否 Tool 版本
@param / @return 否 补充 Reflection 拿不到的描述与更精确的类型

没有 @agent-tool 的 public 方法不会进 Registry。 内部 API、辅助方法、管理方法不会被误暴露——这一点是硬规则，不是配置项。

PHP 8 Attribute（可选）

PHP 8+ 项目可以改用 Attribute，拼错标签名会被 IDE 和静态分析当场发现：

use Ai\Agent\Attribute\AgentTool;

#[AgentTool(name: 'article.update', description: '修改文章', controller: 'article/update', risk: 'medium')]
public function update(int $id, ?string $title = null): array
{
}

字段优先级：Attribute > PHPDoc > Reflection 推断。Attribute 没给的字段仍从 PHPDoc 取，两者可以混用。PHP 7 环境下 Attribute 被当成注释忽略，自动只走 PHPDoc，不会报错。

参数 Schema 自动生成

Reflection 负责类型、必填、默认值，PHPDoc 负责描述，两边合并成 JSON Schema：

{
  "type": "object",
  "properties": {
    "id":      { "type": "integer", "description": "文章 ID" },
    "title":   { "type": ["string", "null"], "description": "文章标题" },
    "status":  { "type": "string", "description": "状态", "enum": ["draft", "published"] },
    "page":    { "type": "integer", "description": "页码", "default": 1 }
  },
  "required": ["id"]
}

支持 int / float / string / bool / array / object / 可空 ?T / PHP 8 联合类型 / PHP 8.1 backed enum，以及 docblock 里的 int[]、array<int, string>、字面量联合 'draft'|'published'（自动变成 enum）。

索引与 CLI

php-ai index                            # 按配置扫描并写库
php-ai index --path=app/Controller      # 指定目录（可重复）
php-ai index --clear                    # 先清空再全量扫描
php-ai index --check                    # 只检查是否需要重建，过期时退出码 1
php-ai index --force                    # 忽略文件 hash，全部重扫
php-ai tools                            # 列出全部 Tool
php-ai tools:search "文章 修改"          # 搜索 Tool
php-ai tools:show article.update        # 打印完整定义与 Schema
php-ai tools:remove article.update       # 从 Registry 删除

公共选项：--db=PATH（默认 .ai/registry.sqlite）、--config=PATH、--bootstrap=PATH（先加载应用自己的 autoloader）、--json、--quiet。

路径也可以写进配置文件，之后直接 php-ai index：

// .ai/config.php
return ['agent' => ['index' => [
    'paths'    => [APP_PATH . '/Controller', APP_PATH . '/Service'],
    'excludes' => ['vendor', 'tests'],
    'db'       => APP_PATH . '/.ai/registry.sqlite',
]]];

推荐把 php-ai index 放进发布流程，避免第一次 Agent 请求时才做全量扫描：

Git Push → CI/CD → composer install → php-ai index → 应用启动

CI 里可以用 php-ai index --check 校验索引是否跟代码同步（过期返回退出码 1）。

增量扫描

每个源文件的内容 hash 存在 Registry 里，hash 没变就跳过，一万个文件里改了 12 个就只重新解析这 12 个。文件被删除、或标注被拿掉时，其名下的 Tool 会被自动清除。

扫描器还做了两层保护：

  1. 文件内容里既没有 @agent-tool 也没有 AgentTool 时，连 include 都不做——业务代码里的顶层副作用（连数据库、注册路由）不会因为一次索引被跑起来；
  2. 类名靠 token_get_all 词法提取，先给应用自己的 autoloader 机会，实在加载不到才 require_once。

⚠️ 一个 PHP 进程里同一个类只会被读到一次。同一次执行里改了源码再 scan()，Reflection 拿到的仍是先前载入的定义。正常用法（php-ai index 每次都是新进程）不受影响。

按需发现：三个工具，而不是几千个

RegistryToolBridge 产出三个运行时工具，模型初始只看到它们：

工具 作用
search_app_tools 用自然语言搜业务能力，返回候选摘要（名称 / 简介 / 风险）
get_app_tool 拉某个能力的完整 JSON Schema
call_app_tool 调用它（经 Controller 入口 + 应用现有权限校验）

一次典型交互：

用户：把昨天销量最高的商品价格降低 5%

search_app_tools("商品 销量 价格")
  → product.sales.stats / product.update_price
get_app_tool("product.sales.stats") → 执行
get_app_tool("product.update_price") → 执行

工具名刻意避开了 ToolDiscovery 的 search_tools：那个搜的是 Agent 自己的运行时工具（read_file / bash…），这里搜的是应用的业务能力，两者不是一回事。

中文全文搜索

SQLite 的 unicode61 分词器把连续汉字当成一个 token，「修改文章的标题」整段是一个词，搜「文章」一无所获。因此写进 FTS5 索引的是归一化后的 token 串——汉字切成单字 + 相邻二元组，英文按分隔符切开并小写：

article.update 修改文章
  → article update 修 改 文 章 修改 改文 文章

查询串走同一套切法，两边才对得上。单字保召回，二元组保精度。FTS5 不可用（编译期没开）时自动降级到 LIKE 扫描 + 纯 PHP 打分，功能不中断。

Registry 实现选择

ToolRegistryInterface 不绑定 SQLite，SQLite 只是默认实现：

场景 建议
Demo / 单元测试 MemoryToolRegistry（零依赖，不需要任何扩展）
普通 PHP 网站 / 中型单服务器 SqliteToolRegistry（默认）
多 PHP 实例 / SaaS 自行实现 MySQL / PostgreSQL 版，Agent 上层逻辑不用改

Registry 与业务数据库默认独立：它属于应用元数据，可以随时删掉重建，删了不影响任何业务数据，不同部署环境也可以有不同的 Registry。

表结构：agent_tools / agent_tool_parameters / agent_tool_permissions / agent_index_files / agent_tools_fts。

风险等级与人工确认

风险不是权限，两者独立。article.delete 即使权限校验通过，也可以因为 risk = high 而要求用户先确认一下。

等级 默认行为
low 直接执行
medium 直接执行（权限由 Controller 把关）
high 需要确认
critical 需要确认，且不能被阈值绕过 
use Ai\Agent\Registry\RiskPolicy;
use Ai\Agent\Tool\ToolDefinition;

$policy = new RiskPolicy();
$policy->setThreshold(ToolDefinition::RISK_MEDIUM);   // 中风险起就要确认
$policy->setOverride('article.delete', false);        // 单个 Tool 免确认

$bridge = new RegistryToolBridge($registry, $gateway, ['risk_policy' => $policy]);

未确认时 call_app_tool 返回失败结果，metadata 里带 requires_confirmation、forced、risk 与已校验的参数；把提示转达用户，得到同意后带 confirmed => true 重试即可。

critical 的强制确认是最后一道闸：setThreshold 和 setOverride 都绕不过它，只有显式调用 allowCriticalWithoutConfirm(true) 才能关掉。

参数校验：模型给的参数不可信

执行前 ArgumentValidator 会做三件事：

  1. 未声明的参数一律丢弃，不透传给 Controller。让模型能往 Controller 塞任意字段，等于把入参白名单交给模型决定；
  2. 必填缺失直接失败，不用默认值蒙混过去；
  3. 只做无歧义的类型收敛——"123" → 123、"true" → true 这类 JSON 传输损耗要修，但 "abc" → 0 这种会把「模型填错了」变成「Controller 收到 0」的转换一律拒绝。

枚举取值不在允许范围时同样拒绝执行。

三条安全红线

  1. Discovery 的权限过滤只是优化，不是安全边界。 ToolSearchContext 的 permissions 与网关的 can() 都跑在「模型还没决定用哪个 Tool」的时候，结果可能被缓存、可能过期，也可能因为对象级规则（「只能改自己写的文章」）而不完整。真正的授权只有一个地方：ControllerGatewayInterface::dispatch() 里应用自己的那套校验。 dispatch() 里不做权限校验，是这套方案唯一的致命误用。

  2. 没有 @agent-controller 的 Tool 拒绝执行。 没有 Controller 入口就没有权限边界。这种 Tool 仍会被索引（能被搜到，索引时会给出警告），但执行阶段直接拒绝——绝不退回「拿 class/method 反射直调」那条路。

  3. Agent 不碰业务数据库。 registry.sqlite 只存 Tool 元数据。业务数据永远走 Controller / Service，因为改一篇文章通常不只是一条 UPDATE：还有权限检查、缓存清理、搜索索引更新、修改日志、Webhook、审核状态、CDN 清理。这些都该由原有 Service 负责。

审计

每次执行（成功 / 失败 / 被拒 / 待确认）都会回调一次：

$bridge->executor()->onExecuted(function (array $record) use ($logger) {
    $logger->info('agent_tool', $record);
    // tool / controller / risk / success / error / metadata / user_id / time
});

API 速查

类 作用
Ai\Agent\Tool\ToolDefinition Tool 元数据值对象，schema() 产出 JSON Schema
Ai\Agent\Tool\ToolParameter 单个参数
Ai\Agent\Attribute\AgentTool PHP 8 Attribute
Ai\Agent\Indexer\ToolIndexer 扫描编排：scan() / check() / scanClass() / clear()
Ai\Agent\Indexer\PhpDocParser @agent-* 与 @param 解析
Ai\Agent\Indexer\ReflectionSchemaBuilder Reflection → 参数 Schema
Ai\Agent\Registry\ToolRegistryInterface search() / get() / register() / remove()
Ai\Agent\Registry\SqliteToolRegistry 默认实现，SQLite + FTS5
Ai\Agent\Registry\MemoryToolRegistry 内存实现，零依赖
Ai\Agent\Registry\ToolSearchContext 搜索上下文与候选过滤
Ai\Agent\Registry\ControllerGatewayInterface 应用唯一需要实现的接口
Ai\Agent\Registry\CallableControllerGateway 闭包实现，小应用与测试直接可用
Ai\Agent\Registry\ControllerToolExecutor 执行链：校验 → 风险 → 网关
Ai\Agent\Registry\RiskPolicy 风险 → 是否需要确认
Ai\Agent\Discovery\ToolSearcher 搜索 + 权限过滤 + 摘要
Ai\Agent\Discovery\RegistryToolBridge 产出三个 Agent 运行时工具

SqliteToolRegistry 需要 pdo_sqlite 扩展（绝大多数 PHP 发行版默认自带）；没有它时可以用 MemoryToolRegistry 或自行实现 ToolRegistryInterface。

Editor：AI 代码编辑

Ai\Editor\* 提供一套「让 AI 改代码」的完整协议：把编辑器现场（当前文件、光标、选区、已打开文件、工作区规范）结构化后交给模型，模型返回可校验、可执行的编辑动作。

use Ai\Editor\EditContext;
use Ai\Editor\EditProtocol;
use Ai\Editor\EditExecutor;
use Ai\Editor\EditAction;

// 1. 组装编辑上下文
$ctx = (new EditContext(FCPATH))
    ->setFile('templates/default/index.php')
    ->setLanguage('php')
    ->setContent($fileContent)
    ->setCursor(['line' => 42, 'column' => 8])
    ->setSelection(['start' => [...], 'end' => [...]], $selectedText)
    ->setOpenedFiles($openedFiles)
    ->setWorkspace($workspace);      // Ai\Editor\Workspace，限定可写根目录与编码规范

// 2. 生成系统提示词（内含编辑协议说明）+ 上下文 JSON
$system  = EditProtocol::systemPrompt($ctx);
$ctxJson = json_encode($ctx->toPromptJson(), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$response = $ai->chat([
    'system'   => $system,
    'messages' => [['role' => 'user', 'content' => $message . "\n\n[CONTEXT]\n```json\n{$ctxJson}\n```"]],
]);

// 3. 解析模型返回的编辑计划
$plan = EditProtocol::parse($response->getContent());

// 4. 校验并执行
$executor = new EditExecutor($workspace->getRoot());   // 越界路径会被拒绝
foreach ($plan->toArray()['actions'] as $a) {
    $action = EditAction::fromArray($a);
    if (!$action->validate()) continue;
    $abs        = $executor->resolveAbsolute($action->file);   // 路径安全解析
    $newContent = $executor->computeContent(file_get_contents($abs), $action);
    file_put_contents($abs, $newContent);                      // 建议先备份
}

配合 Agent 可实现三种工作模式：plan（只读规划）、approval（产出待人工审核的建议）、auto（自动写入并备份）。

联网搜索

不少平台的模型能自己上网查资料再回答。各家的开关五花八门——有的是请求体顶层的一个布尔值， 有的要往 tools 里塞一个内置工具，还有的走插件系统。本库把它们归一成一个 search 配置：

$ai = AI::create([
    'model'   => 'qwen-plus',
    'api_key' => 'sk-xxx',
    'search'  => true,          // 开启联网搜索
]);

echo $ai->chat('今天有哪些重要新闻？')->getContent();

换个平台只改 model，search 这行不动：

$ai->setConfig(['model' => 'claude-sonnet-4-20250514', 'api_key' => 'sk-ant-xxx']);
$ai->setConfig(['model' => 'glm-4-plus',               'api_key' => 'xxx']);

细化配置

search 传数组可以调细节。省略 enable 即视为开启：

$ai->setConfig([
    'search' => [
        'enable'          => true,
        'max_uses'        => 5,               // 单次请求最多搜几次
        'count'           => 10,              // 返回结果条数
        'query'           => 'PHP 8.5 新特性', // 强制指定搜索词，不指定则由模型自己拟
        'recency'         => 'week',          // 时效：hour / day / week / month / year
        'forced'          => true,            // 强制搜索，不让模型自行判断要不要搜
        'citation'        => true,            // 正文里带引用角标
        'sources'         => true,            // 返回搜索来源列表
        'allowed_domains' => ['wikipedia.org'], // 只搜这些域名
        'blocked_domains' => ['spam.com'],      // 不搜这些域名（与上一项互斥）
    ],
]);

平台不支持的细项会被静默忽略，不影响搜索本身开启。这是刻意的：统一层承诺的是 「搜索会开」，不是「每个细节都能在每个平台生效」。下表是各项的实际落点：

统一配置 Claude 通义千问 智谱 GLM Kimi 文心一言 OpenRouter Perplexity
max_uses max_uses — — — — — —
count — — count — search_number max_results —
query — — search_query — — — —
recency — — search_recency_filter — — — search_recency_filter
forced — forced_search require_search — — — —
citation 总是开 enable_citation — — enable_citation — —
sources — enable_source search_result — enable_trace — return_related_questions
allowed_domains ✅ — 仅首个 — — include_domains ✅
blocked_domains ✅ — — — — exclude_domains 加 - 前缀

几处需要留意的差异：

哪些平台支持

print_r(\Ai\Helpers\Protocols::withWebSearch());
// ['claude', 'qwen', 'ernie', 'zhipu', 'moonshot', 'perplexity', 'openrouter']

\Ai\Helpers\Protocols::supportsWebSearch('deepseek');   // false

没列进来的平台，配了 search 会直接抛 ConfigException，而不是静默忽略。 静默忽略在这里是最糟的选择：用户拿到的是一个「答得挺像样、但其实没上网」的回复， 内容陈旧却毫无征兆，往往要等到发现模型说的是去年的事才察觉。

需要特别说明的两个：

平台私有参数：用 extra_body

统一配置只收各家都有的语义，平台独有的参数（通义的 search_strategy、 智谱的 search_engine、OpenRouter 的 engine 等）不进 search，用 extra_body 直接写：

$ai->setConfig([
    'search'     => ['forced' => true],
    'extra_body' => ['search_options' => ['search_strategy' => 'max']],
]);

extra_body 在请求体顶层做合并，同名字段会整体覆盖 search 生成的结果—— 上例中最终发出的 search_options 只有 search_strategy，forced_search 会被顶掉。 要同时用两者，把所有子字段都写进 extra_body。

库对某平台的判断有误或过时时，extra_body 也是逃生口：它绕过全部声明检查， 可以直接发平台原生的搜索参数。

来源与引用

平台界面上那串带角标、点开能看原文的引用，API 其实也发回来了——只是各家放在不同字段、 结构完全不同（Claude 挂在 text 块上，OpenAI 系叫 annotations，Perplexity 是顶层 search_results，Gemini 是 groundingMetadata……）。本库把它们归一成两份列表， 不用关心平台差异，按需取用：

$ai = AI::create(['model' => 'claude-sonnet-5', 'api_key' => 'sk-ant-xxx', 'search' => true]);
$resp = $ai->chat('2026 年世界杯冠军是谁？');

echo $resp->getContent();

// 来源：平台检索到的网页
foreach ($resp->getSources() as $s) {
    echo "[{$s['index']}] {$s['title']} {$s['url']}", $s['cited'] ? '' : '（未被引用）', "\n";
}

// 引用：正文里哪段话出自哪里
foreach ($resp->getCitations() as $c) {
    $said = mb_substr($resp->getContent(), $c['start'], $c['end'] - $c['start']);
    echo "「{$said}」← {$c['url']}\n";
}

两份列表的字段：

来源 getSources() 说明
index 编号，与正文角标 [1] 对应；平台没给就按顺序从 1 编
url / title 网页地址与标题
snippet 摘要或正文片段，平台没给为空串
site_name / published_at 站点名、发布时间（平台原样字符串，不解析）
cited 是否被回答实际引用——区分「用上了」和「只是搜到了」
raw 平台原始条目
引用 getCitations() 说明
url / title 出处
cited_text 来源里被引用的原文，平台没给为空串
start / end 在 getContent() 里的区间，按 UTF-8 字符计，可直接喂 mb_substr()；未知时为 null
source_index 对应 getSources() 的数组下标（从 0 起）
type 平台原始类型（如 web_search_result_location、url_citation）；从正文角标解析出的为 marker
raw 平台原始条目

各平台的实际情况（均以官方文档为准）：

平台 来源 引用 说明
Claude ✅ web_search_tool_result ✅ 带 cited_text 区间是被引用的那段 text 块
OpenRouter 由 annotations 去重得到 ✅ annotations 实测多数模型给的区间是 0-0，库改用正文里 [域名](url) 链接的位置；定位不到的只算来源（cited 为 false）
Perplexity ✅ search_results ✅ 正文 [1] 角标 区间指向角标本身。Sonar 接口官方公告 2026-09-27 停止支持
文心一言 ✅ search_results ✅ 正文 ^[1]^ 角标 需 sources / citation 开启；检索到非公开网页时平台不返回
智谱 GLM ✅ web_search ✅ 正文 [ref_1] 角标 需 'sources' => true。平台默认的 search_prompt 要求模型不标出处，实测正文不带角标；在自定义 search_prompt 里要求按 [ref_1] 标注时可解析
通义千问 ❌ ❌ 官方明确：OpenAI 兼容端点不返回来源与角标，仅 DashScope 原生协议支持
Kimi ❌ ❌ 搜索走工具调用流程，平台不返回来源

另外两处兼容：

以上 Perplexity、智谱 GLM、Gemini 原生结构、OpenRouter（DeepSeek / Grok / Perplexity / Qwen / GLM / Kimi） 已经过真实接口实测，见 tests/live/citations_live_test.php。

流式同样可用，分片里的来源与引用会边收边记，结束后 getSources() / getCitations() 与非流式结果一致。stream_end 事件的 data 里也会带上 sources / citations（去掉了 raw，方便直接下发前端）；没有来源时不出现这两个键，报文与旧版本完全一致。

没开搜索或平台没返回时，两个方法都返回空数组，不需要判空。 需要平台独有字段时，raw 里是原始条目，完整响应仍可用 getRaw() 取。

与 Ai\Tools\HttpFetch 的区别

两者都能让模型用上网页内容，但不是一回事：

search 配置 Ai\Tools\HttpFetch（见下一节）
谁在联网 平台的服务器 你的 PHP 进程
计费 平台按次收搜索费 只有 token 费用，流量走你的服务器
能力 搜索引擎检索 抓取你指定的 URL
可控性 只能给过滤条件 完全可控，含 SSRF 防护
支持范围 仅上表 7 个平台 所有平台

需要「模型自己决定搜什么」用 search；需要「读这几个我指定的页面」用 HttpFetch。 两者可以同时开。

Tools：安全网页抓取

让模型联网读网页时，最大的风险是 SSRF。Ai\Tools\HttpFetch 内置纵深防御：

use Ai\Tools\HttpFetch;
use Ai\Tools\WebContent;

$fetcher = new HttpFetch(['max_bytes' => 1500 * 1024, 'timeout' => 15]);
$res     = $fetcher->fetch($url);
// $res = ['ok'=>bool, 'status'=>int, 'content_type'=>string, 'final_url'=>string, 'bytes'=>int, 'body'=>string, 'error'=>string]

if ($res['ok']) {
    // 按需渲染成模型友好的格式：text 纯文本 / md Markdown / source 原始源码
    $text = WebContent::render($res['body'], $res['content_type'], 'md', 16000);
}

把它包成 Agent 工具即可让模型自主上网：

'fetch_url' => [
    'description'  => '抓取一个公网网页并返回正文，用于查证实时信息。',
    'input_schema' => [
        'type' => 'object',
        'properties' => [
            'url'    => ['type' => 'string'],
            'format' => ['type' => 'string', 'enum' => ['text', 'md', 'source']],
        ],
        'required' => ['url'],
    ],
    'handler' => function ($input) use ($fetcher) {
        $r = $fetcher->fetch($input['url']);
        if (!$r['ok']) return 'ERROR: ' . $r['error'];
        return WebContent::render($r['body'], $r['content_type'], $input['format'] ?? 'md');
    },
],

Agent 多模态与附件对话

让 Agent 收得下图片和 PDF：用户在对话里上传的附件、Agent 自己 read_file 读到的图片，都能被模型真的看到。主模型不支持视觉时，自动交给已配置的视觉模型处理，用户无感。

use Ai\Agent\Media\Attachment;

$agent->chat('这张截图里报的是什么错？', [
    Attachment::fromPath($_FILES['shot']['tmp_name']),
]);

三条设计约定，都是踩过坑之后定下来的：

  1. 对话历史里存引用，不存 base64。 一张 5 MB 的图 base64 后约 6.67 MB，写进会话 JSONL 之后每次 load/save 都要搬运这几 MB。
  2. 模型看不了图时明确告知，绝不伪装。 不用 [图片: x.png] 这种占位符——它看起来像「图已附上」，会诱导模型写出「从图片可以看出……」。
  3. 附件真的进对话历史。 第 3 轮再问「刚才那张图里的数字是多少」，图还在；会话恢复之后也还在。

快速开始

use Ai\AI;
use Ai\Agent\Agent;
use Ai\Agent\Media\Attachment;

$ai    = new AI(['api_key' => $key, 'platform' => 'openai', 'model' => 'gpt-4o']);
$agent = (new Agent($ai))->setWorkdir(APP_PATH);

$result = $agent->chat('这张图里的四位数字是多少？', [
    Attachment::fromPath('/uploads/shot.png'),   // 本地文件
    'https://example.com/b.jpg',                 // 字符串也行，自动识别路径 / URL
    ['path' => '/uploads/doc.pdf'],              // 数组写法
]);

Attachment 三个工厂方法：

方法 用途 安全策略
fromPath($path) 本地文件 realpath 解析（挡 symlink 逃逸）、可选目录白名单、MIME 内容嗅探 + 扩展名交叉校验
fromUrl($url) 远程文件 强制走 HttpFetch，复用其 SSRF / DNS rebinding / 私网与云元数据地址 / 重定向逐跳校验
fromBase64($data, $mime, $name) 已在内存里的字节 接受原始二进制、base64、或完整 data: URI

字节是惰性读取的：fromPath() 只记路径，直到真要落库那一刻才读盘。一次传十个附件不会因为构造对象就把十个文件全读进内存。

支持的类型：图片（png / jpg / gif / webp / bmp）与 PDF。把 .php 改名成 .png 传上来会在 MIME 交叉校验这关被拦下。

附件存哪儿

对话历史里只有引用：

{
  "type": "agent_media",
  "media": "image",
  "mime": "image/png",
  "name": "screenshot.png",
  "bytes": 20480,
  "ref": "media://6a9e37f47d0572c332fb73b2"
}

真实字节归 MediaStore 管，默认落在 AgentHome 的媒体目录（与 sessions 同级，沿用同一套项目隔离与 userId 隔离规则）。发请求的那一刻才由 MediaResolver 解析成 base64。

要接对象存储就自己实现 MediaStoreInterface：

$agent->media(['store' => new MyS3MediaStore($bucket)]);

媒体文件的清理责任在应用。 库不做自动 GC——它不知道同一个 ref 还被哪些会话引用，自动删是不可逆的。提供两个显式接口：

$agent->mediaManager()->prune(30);                       // 清理 30 天前的
$agent->mediaManager()->gcByMessages($liveMessages);     // 按还活着的引用回收

限额与安全

一个总限制是不够的：5 MB 单文件很合理，但十个一起发就是必然失败的请求，而且失败发生在平台侧、错误信息通常很难懂。所以是三级：

$agent->media([
    'max_attachment_bytes'        => 5 * 1024 * 1024,   // 单文件
    'max_message_bytes'           => 10 * 1024 * 1024,  // 单条消息全部附件之和
    'max_attachments_per_message' => 8,                 // 单条消息附件个数
    'max_request_bytes'           => 20 * 1024 * 1024,  // 单次模型请求的媒体总量
    'allowed_paths'               => [APP_PATH . '/uploads'],   // 可选的目录白名单
]);

任一附件不合法则整批失败，不会留下没人引用的孤儿文件。

工作区图片：read_file 直接读图

$agent->setTools(['read_file' => new ReadFileTool(new PathSafety(APP_PATH))]);
$agent->chat('读一下 error.png，告诉我报的什么错');

工具只负责说「我发现了一张图，引用在这里」，不决定它以什么协议格式进入对话——那是运行时与协议层的事。所以 ReadFileTool 完全不需要知道当前跑的是 Claude 还是 OpenAI。

媒体会被拼进同一条 user 消息、排在 tool_result 之后。这一点两个协议家族都成立：Claude 的 user 消息本来就允许 tool_result 块后面跟 image 块；OpenAI 家族则由库自动拆成「若干条 role:tool + 随后一条 role:user」，图片落到那条能接受它的 user 消息里。不能另起一条 user 消息——Anthropic 不接受连续两条同角色消息。

自动模态路由

主模型是纯文本时，配一个能看图的平台，剩下的库自己处理：

$agent->platforms([
    'gemini' => [
        'api_key'    => $geminiKey,
        'platform'   => 'gemini',
        'model'      => 'gemini-2.5-flash',
        'proxy'      => 'http://127.0.0.1:8993',   // 需要代理时
        'modalities' => ['vision'],
    ],
]);

$agent->multimodal(['mode' => 'auto']);   // 默认就是 auto，这行可以省

$agent->chat('图里那个四位数字是多少？', ['/uploads/shot.png']);
// → 主模型看不了图 → 自动交给 Gemini 读成文字 → 主模型据此回答

四种模式：

模式 行为
auto（默认） 当前模型确定支持 → 直发；不支持或不确定 → 找视觉模型 describe；找不到 → 明确告知不可用
native 强制直发当前模型，不路由
describe 总是先让视觉模型把文件读成文字，再交给主模型
switch 本轮这一次模型调用换成视觉模型；tools / permissions / session / memory 一律不变

默认 auto 而不是 describe：主模型本来就支持视觉时，describe 会白花一次调用，还把原图降级成了别人写的文字。

描述是派生上下文，不替代原图。 它被记在媒体块的 description 字段里，原 ref 原样保留。两个好处：以后换成视觉模型还能重新看原图；同一张图在后续轮次里不会被反复描述。

回填时注明来源，主模型收到的是：

[图片「shot.png」的内容描述 —— 由 gemini-2.5-flash 查看后生成，当前模型无法直接查看该文件]
图中是一个红色矩形按钮，上面用白色大写字母写着 SUBMIT，下方有黑色数字 7431。

不写来源的话，主模型会把二手描述当一手观察，在描述有偏差时给出过度自信的结论。

要用自己的方式构造视觉模型的连接（比如走内网网关）：

$agent->modalityRouter()->setAiFactory(function ($model, $config) {
    return new AI(['api_key' => $config['api_key'], 'model' => $model,
                   'base_url' => 'http://gateway.internal/v1']);
});

路由决策会发 modality_route 事件，带 decision / provider / notes。

模型能力表

判断「这个模型能不能吃图片」用的是独立的能力表，不是 BaseModel::$features——那份数据既有假阳性（CustomModel 对 39 个平台一律乐观声明 vision）又有假阴性（Gemini25Pro 只声明了 chat）。

匹配的是模型名，不按协议家族推断：本库 40 个平台里大量是 OpenAI 兼容的中转与自建网关，同一个 /v1/chat/completions 后面可能是 GPT-4o，也可能是纯文本的 7B 模型。

// 查一下
$agent->capabilities()->supports('gpt-4o', 'image');          // true
$agent->capabilities()->supports('deepseek-chat', 'image');    // false
$agent->capabilities()->supports('my-private-vl', 'image');    // null —— 不知道

// 自己补
$agent->multimodal(['capabilities' => [
    'my-private-vl' => ['input' => ['image' => true]],
    'vl-*'          => ['input' => ['image' => true]],   // 支持通配
]]);

null 与 false 是两回事：null 是「不知道」，false 是「确定不支持」。混淆这两者会导致两种错误——把图片发给看不了图的模型（换回一个难懂的错误码），或者放着能用的模型不用。内置表只填有把握的，拿不准的一律留 null。

未知能力时的行为分两种口径：

后一条是实测逼出来的：某些平台的纯文本模型收到图片只返回一个 HTTP 510 Model Request Error，既不说是哪个字段的问题也不说是不支持。

没有视觉模型时会怎样

不会静默忽略，也不会假装看到。模型收到的是一句事实陈述：

[系统提示] 用户上传了图片「shot.png」，但当前模型无法查看图片内容。
请不要臆测其内容；如果需要，请告诉用户换用支持该类型的模型。

实测下模型的回答是「我看不到这张图片。当前模型无法查看图片内容。」——没有编造。

API 速查

类 作用
Ai\Agent\Media\Attachment 附件入口：fromPath / fromUrl / fromBase64
Ai\Agent\Media\MediaReference media://<id> 值对象与 agent_media 块
Ai\Agent\Media\MediaStoreInterface 存储接口，接对象存储时自己实现
Ai\Agent\Media\FileMediaStore 默认实现，原子写 + sidecar 元数据 + prune/gc
Ai\Agent\Media\MediaResolver 请求边界解析引用 + 单次请求媒体配额
Ai\Agent\Media\MediaManager 校验 / 存储 / 解析的门面，三级限额
Ai\Agent\Context\MessagePart text / agent_media 块的构造与识别
Ai\Helpers\MediaTranslator 内部块 → Anthropic image / OpenAI image_url
Ai\Agent\Capability\Modalities 输入模态常量 TEXT / IMAGE / PDF
Ai\Agent\Capability\CapabilityRegistry 模型能力表，内置 + 平台声明 + 用户覆盖
Ai\Agent\Capability\CapabilityResolver 三层合并，null / false 严格区分
Ai\Agent\Capability\ModalityRouter 四种模式的路由决策与消息改写
Ai\Agent\Agent::media() 限额、白名单、自定义存储
Ai\Agent\Agent::multimodal() 路由模式、能力覆盖、unknown_policy

可运行示例见 examples_multimodal.php（不联网、不需要 API Key）。

Memory：Agent 长期记忆

把一个 Markdown 文件当作 Agent 的持久记忆（类似 CLAUDE.md）。文件位置由业务层决定，库不认识任何具体路径。

use Ai\Agent\Memory;

$mem = new Memory(FCPATH . 'writable/agent/memory.md', 20000);  // 第二参数：注入对话时的最大字符数

$block = $mem->forPrompt();          // 读取并截断，空记忆返回 ''
if ($block !== '') {
    $system .= "\n\n# 长期记忆\n" . $block;
}

$mem->append('用户偏好深色主题');    // 追加一条
$mem->write($fullContent);           // 覆盖整份

完整业务案例：批量 JSON 翻译

一个真实场景——把多语言词条按批交给 AI 翻译，要求模型严格返回 {"记录ID":"译文"} 的 JSON，并做失败重试、格式校验与结果回写。

use Ai\AI;
use Ai\Exceptions\AIException;

// 1. 组装待翻译数据：{ 记录ID: 原文 }
$translateData = [];
foreach ($batch as $rec) {
    $translateData[(int)$rec['id']] = $rec['text_source'];
}

// JSON_UNESCAPED_SLASHES 很关键：否则 </p> 会被转义成 <\/p>，
// 模型会把 \/ 当字面字符照抄进译文，导致译文出现错误转义
$dataJson = json_encode($translateData, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$prompt = "把下面 JSON 中每个值从 {$from} 翻译成 {$to}，"
        . "保持键不变、保留 HTML 标签，只返回 JSON：\n{$dataJson}";

// 2. 调用，带重试与 JSON 校验
$ai = new AI();
$ai->setConfig(['model' => $model, 'api_key' => $apiKey, 'max_tokens' => 1024 * 256])
   ->setTimeout(300);

$content = '';
for ($loop = 1; $loop <= 3; $loop++) {
    try {
        $content = trim($ai->chat($prompt)->getContent());
    } catch (AIException $e) {
        log_message('error', 'AI翻译异常: ' . $e->getMessage());
        break;
    }
    // 去掉模型可能包裹的 ```json ``` 围栏后校验
    $content = preg_replace('@^\s*```(json)?\s*(.+?)\s*```\s*$@is', '$2', $content);
    if ($content !== '' && json_decode($content, true) !== null) break;
    $content = '';
}

// 3. 回写
$result = json_decode($content, true);
if (is_array($result)) {
    foreach ($result as $id => $text) {
        if (!isset($translateData[(int)$id]) || trim($text) === '') continue;
        update_translation((int)$id, trim($text));
    }
}

实战经验：

扩展开发

新增模型

namespace Ai\Models\OpenAI;

use Ai\Models\BaseModel;

class GPT4Turbo extends BaseModel
{
    protected $name     = 'gpt-4-turbo';                        // 发给平台的真实模型名
    protected $platform = 'openai';
    protected $protocol = 'Ai\\Protocol\\OpenAI';               // 复用协议
    protected $endpoint = 'https://api.openai.com/v1/chat/completions';
    protected $features = ['chat', 'stream', 'vision'];
    protected $config   = ['max_tokens' => 4096, 'temperature' => 0.7];
}

然后在 AI::$modelMap 中注册 'gpt-4-turbo' => 'Ai\Models\OpenAI\GPT4Turbo'。

需要特殊附件处理的模型，重写 processAttachments(array $payload, array $attachments): array 即可。

只是想临时接一个新模型/新接口，不必写模型类——直接用 model + protocol + base_url 配置即可，库会在运行时构造 Ai\Models\CustomModel。也可以自己 new CustomModel([...]) 传给 setModel()。

绝大多数新平台都是 OpenAI 兼容的，继承 Ai\Protocol\OpenAI 改一个地址即可——库内 30 多个平台协议都是这么实现的：

namespace Ai\Protocol;

/**
 * 某某云（OpenAI 兼容）
 */
class MyCloud extends OpenAI
{
    public function defaultBaseUrl(): string
    {
        return 'https://api.mycloud.com';
    }

    // 路径与 OpenAI 官方不同时才需要覆盖
    public function chatPath(): string   { return '/v2/chat/completions'; }
    public function modelsPath(): string { return '/v2/models'; }

    // 鉴权方式不是 Authorization: Bearer 时覆盖 buildHeaders()

    /** 常用模型：供后台离线渲染下拉框，也是拉取失败时的兜底 */
    public function knownModels(): array
    {
        return ['my-model-pro' => 'MyCloud Pro'];
    }
}

然后在 Ai\Helpers\Protocols::$map 注册标识（顺带在 $alias / $detect 里加别名与模型名识别规则），protocol => 'mycloud' 就能用了。

协议格式本身不同（既不是 OpenAI 也不是 Anthropic / Gemini）时：

  1. 实现 Ai\Contracts\ProtocolInterface：buildRequest、parseResponse、buildHeaders、parseStreamChunk、isStreamEnd、listModels； 可选实现 defaultBaseUrl() / chatPath() / modelsPath() 供自动组装端点，use ModelCatalog 获得常用模型清单与兜底能力；
  2. 创建该平台的模型类，$protocol 指向新协议；或直接把协议类名传给 protocol 配置项（无需改动本库）： 
    AI::create(['model'=>'x', 'protocol'=>'App\\Protocol\\MyApi', 'base_url'=>'https://api.my.com']);
  3. 在 AI::$modelMap 注册模型标识（可选，仅为提供快捷标识）。

传输层 Ai\Transport\CurlTransport 与协议无关，通常无需改动。

架构

php-ai/
├── src/                    # 源代码（PSR-4 命名空间 Ai\）
│   ├── AI.php              # 主入口：配置、模型解析、对话、流式、回调
│   ├── Agent/              # Agent 循环 + 长期记忆
│   │   ├── Media/          # 附件：Attachment / MediaStore / Resolver（历史存引用，不存 base64）
│   │   ├── Capability/     # 输入模态能力表与模态路由（auto / native / describe / switch）
│   │   ├── Registry/       # Tool Registry：SQLite(FTS5) / Memory / 执行器 / 风险策略 / Controller 网关
│   │   ├── Indexer/        # 扫描器：PHPDoc / Attribute 解析、Reflection Schema、增量索引
│   │   └── Discovery/      # 按需发现：搜索、权限过滤、接进 Agent 的三个运行时工具
│   ├── Cli/                # ClaudeCode 一次性调用 / ClaudeCodeSession 常驻双工会话 + 响应对象
│   ├── Contracts/          # 接口定义：Model / Protocol / Transport / AIResponse
│   ├── Editor/             # AI 代码编辑：上下文 / 协议 / 动作 / 执行器 / 工作区
│   ├── Exceptions/         # AIException / ConfigException / RequestException / ProcessException
│   ├── Helpers/            # AIFile（附件封装）、Endpoint（端点解析）、Protocols（协议注册表）
│   │                       # Headers（请求头合并）、Tools（工具调用格式归一）、Log（可注入日志）
│   ├── Models/             # 模型层：各平台模型的名称、端点、能力、默认配置
│   │   ├── BaseModel.php
│   │   ├── CustomModel.php # 通用模型：任意模型名 + 手选协议 + 自定义接口地址
│   │   ├── OpenAI/  Claude/  Gemini/  DeepSeek/
│   ├── Protocol/           # 协议层：40 个平台协议
│   │                       #   ModelCatalog.php   常用模型清单 + 拉取失败兜底（trait）
│   │                       #   OpenAI / Claude / Gemini  三种基础协议格式
│   │                       #   国内：Qwen / Doubao / Ernie / Zhipu / Moonshot / Hunyuan / Spark /
│   │                       #        MiniMax / StepFun / Yi / Baichuan / SenseNova / Zhinao / ModelArts …
│   │                       #   海外：Grok / Mistral / Cohere / Perplexity / Llama / Azure …
│   │                       #   聚合：OpenRouter / SiliconFlow / ModelScope / Groq / Together / Fireworks …
│   │                       #   本地：Ollama / LMStudio / VLLM
│   ├── Response/           # 统一响应对象
│   ├── Tools/              # HttpFetch（SSRF 防护）、WebContent（格式化）
│   └── Transport/          # cURL 传输层（含 SSE 解析、代理、超时）
├── autoload.php            # PSR-4 加载器（不用 Composer 时引入）
├── composer.json
├── tests/                  # 回归测试（纯 PHP，无需 PHPUnit、无需网络、无需 API Key）
│   ├── smoke_test.php      # 全部类可加载/可实例化、继承链签名兼容
│   ├── stream_test.php     # 40 个协议 × 普通对话 / 流式 / token 统计
│   ├── tools_test.php      # 工具调用跨平台一致性（同一段代码跑两个协议家族）
│   ├── lib_test.php        # 并发批量 / Memory 并发安全 / 计价 / 日志注入
│   ├── cli_test.php        # CLI 参数渲染与命令注入防护
│   └── ssrf_test.php       # SSRF 防护的全部已知绕过向量
├── bin/php-ai              # CLI：Agent Tool 索引与查询（php-ai index / tools / tools:search）
├── examples*.php           # 使用示例（examples_platforms.php 为多平台接入示例）
├── LICENSE
├── README.md
└── .gitignore

设计上分四层：模型层声明「是什么」（名称、端点、能力），协议层负责「怎么说」（请求/响应/流式格式），传输层负责「怎么发」（cURL、代理、超时、SSE），主入口负责编排。新增平台只动前两层。

扩展能力：图像 / 语音 / 视频 / 向量

当前进度

能力 状态
文本向量化 embeddings() ✅ v1.15.0，35 个平台
图像生成 images() ✅ v1.16.0 同步 / v1.20.0 异步与编辑
语音合成 / 识别 audio() ✅ v1.17.0，二进制与 JSON-hex 两种形态已归一
WebSocket realtime() ✅ v1.18.0，讯飞语音（RFC 6455 纯 PHP 实现）
视频生成 video() ✅ v1.19.0，4 个平台异步任务已归一

未交付的能力调用时会抛 UnsupportedCapabilityException 并说明原因， 不会静默返回空结果。对话（chat()）功能完全不受影响。

入口

对话之外的能力都走子门面，与 chat() 共享同一份配置： setProxy() / setRetry() / setTimeout() / setLogger() 配一次，各能力自动生效。

$ai = new AI(['api_key' => '...', 'model' => '...']);

$ai->embeddings();   // 文本向量化
$ai->images();       // 图像生成
$ai->audio();        // 语音合成 / 识别（HTTP）
$ai->video();        // 视频生成（异步任务）
$ai->realtime();     // WebSocket 通道，默认关闭

先判断再调用

use Ai\Helpers\Capabilities;

if ($ai->supports(Capabilities::IMAGE)) {
    $img = $ai->images()->generate('一只在看书的猫', ['size' => '1024x1024']);
    $paths = $img->saveTo('/var/www/uploads');   // 返回实际写入的绝对路径
}

$ai->capabilities();   // 当前模型支持的能力清单，如 ['embedding', 'image']

不判断直接调也可以，不支持时会抛出带原因的异常，而不是返回空值让你猜：

当前模型使用的协议不支持「图像生成」能力。本协议目前只支持对话（chat）

文本向量化（已可用）

$ai = new AI(['api_key' => '...', 'model' => 'text-embedding-3-small']);

// 单条
$vec = $ai->embeddings()->create('这是一段文本')->getVector(0);

// 批量：返回顺序**始终**与输入顺序一致
$res = $ai->embeddings()->create(['第一段', '第二段', '第三段']);
$res->getVectors();      // [[...], [...], [...]]
$res->getVector(1);      // 第二段的向量
$res->getDimensions();   // 1536
count($res);             // 3
$res->getUsage();        // ['prompt_tokens' => .., 'total_tokens' => ..]

顺序一致是有代价换来的：多数平台不保证响应里 data 数组的顺序与输入一致， 库会按每条返回的 index 归位。这类错位不会报任何错，只会让后续检索莫名其妙地不准。

平台参数直接透传

$ai->embeddings()->create($texts, [
    'dimensions'      => 512,      // OpenAI text-embedding-3-* 支持降维
    'encoding_format' => 'base64', // 返回 base64 时库会自动解回 float 数组
]);

只归一 model / input 两个字段，其余原样透传给平台。 dimensions 这类参数各平台支持度不同，以对方文档为准——库不替你猜， 不支持的平台会直接返回它自己的错误信息。

超长批量自动分批

各平台单次可提交的条数上限不同（OpenAI 上千条，部分平台只有一二十条）， 且官方文档未必写明。默认不分批（一次发完，不无谓拆分请求）， 需要时用 batch_size 指定：

$res = $ai->embeddings()->create($tenThousandTexts, ['batch_size' => 25]);
// 自动分成 400 个请求，结果按原顺序合并，usage 逐批累加

分批时若某一批返回的向量数与提交的文本数对不上，会当场抛异常而不是继续—— 数量对不上意味着后面所有下标都会错位，静默继续比失败危险得多。

支持情况

31 个协议声明支持向量化，路径由各自的对话路径同级推导 （/v1/chat/completions → /v1/embeddings，/v4/chat/completions → /v4/embeddings）， 所以带前缀的网关、Azure、Gemini 兼容端点都自动正确。

Anthropic Messages 协议家族（claude / qwen-anthropic / zhipu-anthropic / moonshot-anthropic / deepseek-anthropic）不支持——Anthropic 没有向量化接口。 用这些协议调用会得到明确报错。

平台审计（v1.21.0 ~ v1.24.0）已逐个核对官方文档与端点实测。 DeepSeek、商汤、Llama、Perplexity、Cerebras 经确认没有向量化接口，不再声明。 若你确知某平台可用，配 embedding_endpoint 即可绕过库的判断。

图像生成（已可用）

$ai = new AI(['api_key' => '...', 'model' => 'gpt-image-1']);

$img = $ai->images()->generate('一只在看书的猫', ['size' => '1024x1024', 'n' => 2]);

$img->getUrls();            // ['https://...', 'https://...']
$img->getBase64();          // 平台返回 base64 时在这里
$img->getRevisedPrompt();   // 部分平台会改写提示词，原样回传
count($img);                // 2

// ⚠️ 及时落地：各平台的图片 URL 都有有效期
$paths = $img->saveTo('/var/www/uploads', 'cat');
// ['/var/www/uploads/cat_1.png', '/var/www/uploads/cat_2.png']

URL 有效期是这里最容易踩的坑：万相约 24 小时、硅基流动只有 1 小时。 把 URL 存进数据库，用户过一阵回来看就全是坏图。要长期保留必须调 saveTo() 落盘。

saveTo() 的目录必须已存在，不会自动创建——多模态接口常在循环里落盘， 路径拼错时自动 mkdir 会在磁盘上散落一堆空目录，等发现时已经很难收拾。 下载走库内的 HttpFetch（带完整 SSRF 防护），不是裸 file_get_contents()。

各平台字段差异已归一

图像接口远没有对话那么统一。下面这些差异（据各平台官方文档 2026-08 核对） 库内已经处理掉，调用方在所有平台上写法一致：

平台 实际字段 你仍然写
硅基流动 image_size / batch_size，响应是 images[] size / n
xAI aspect_ratio + resolution，没有 size size（自动换算成最接近的比例档）
火山方舟（豆包） response_format: "base64" response_format: "b64_json"
OpenAI gpt-image-* 只返回 b64_json，不支持 url 取 getUrls() 或 getBase64() 都行

平台私有参数（seed、guidance_scale、watermark、negative_prompt 等）原样透传， 不做映射——把所有平台的所有参数都归一，归一层会厚到没法维护。

支持的平台与模型

模型清单据各平台官方文档登记（不是靠端点探测猜的）：

平台 模型
OpenAI gpt-image-1.5、gpt-image-1、gpt-image-1-mini、dall-e-3、dall-e-2
Gemini gemini-3.1-flash-image、gemini-3.1-flash-lite-image、gemini-3-pro-image、gemini-2.5-flash-image
讯飞星火 走独立的 TTI 接口（maas-api.cn-huabei-1.xf-yun.com/v2.1/tti），需 app_id
智谱 glm-image、cogview-4-250304、cogview-4、cogview-3-flash
xAI grok-imagine-image-quality、grok-imagine-image-2.0
硅基流动 Kwai-Kolors/Kolors、Qwen/Qwen-Image-Edit、Qwen/Qwen-Image-Edit-2509
阶跃星辰 step-1x-medium
火山方舟（豆包） doubao-seedream-5.0-lite、doubao-seedream-4.5、doubao-seedream-4.0、doubao-seedream-3.0-t2i
通义万相 异步任务式，见下节 
$ai->images();  // 子门面
(new \Ai\Protocol\Zhipu())->knownImageModels();   // 取某协议的图像模型清单

通义（qwen）走异步接口：其 OpenAI 兼容模式没有同步文生图（实测 404）， 万相是「提交任务再轮询」，用 generateAsync()，见下节。

某个平台是否真的开通了这个接口以对方文档为准——未开通时你会收到该平台自己的 404， 而不是库的猜测。库的判断有误或过时时，配 image_endpoint 即可绕过。

异步文生图（通义万相）

通义万相的文生图是提交任务再轮询，一次请求拿不到图。这类平台上 generate() 会明确报错并指向 generateAsync()——返回一个「成功但没有图」的 响应是最坏的做法，调用方拿到空结果完全不知道去哪找原因。

$ai = AI::create(['protocol' => 'qwen', 'model' => 'wan2.2-t2i-flash', 'api_key' => '...']);

$task = $ai->images()->generateAsync('一只在看书的猫', ['size' => '1024x1024', 'n' => 2]);
$db->save(['task' => json_encode($task->toArray())]);

// ……稍后
$task = AsyncTask::fromArray(json_decode($row['task'], true), $ai);
if ($task->refresh()->isSucceeded()) {
    $task->getResult()->saveTo('/var/www/uploads');
}

和视频任务共用同一套 AsyncTask：不阻塞、可跨请求恢复、超时不算失败。

库内会把统一写法的 size: "1024x1024" 转成万相要的 "1024*1024"（星号）。 分隔符传错不会被容错，平台直接判为非法参数。

图像编辑（图生图 / 局部重绘）

// 整图改写
$ai->images()->edit('/path/cat.png', '把背景换成星空')->saveTo('/var/www/uploads');

// 局部重绘：只改蒙版覆盖的区域
$ai->images()->edit('/path/cat.png', '去掉这只手', ['mask' => '/path/mask.png']);

走 multipart 上传，与文生图不是同一个端点。只接受本地文件—— 远端图片请先用 Ai\Helpers\Media::download() 取回落盘，库不会顺手替你下载， 因为那需要 SSRF 防护，不该由上传逻辑代劳。

支持：OpenAI、阶跃星辰、xAI、智谱。 硅基流动不支持（实测无 /images/edits 路由，它把图生图并进了 images/generations，靠传 image 参数区分）；通义也不支持（兼容模式实测 404）。

语音合成与识别（已可用）

// 文本 → 音频
$ai = new AI(['api_key' => '...', 'model' => 'gpt-4o-mini-tts']);
$ai->audio()->speech('你好世界')->saveTo('/tmp/hello.mp3');

// 带参数
$audio = $ai->audio()->speech('你好世界', [
    'voice'  => 'sage',    // 音色
    'format' => 'wav',     // 库内统一写 format，各平台字段名不同
    'speed'  => 1.2,
]);
$audio->getBytes();    // 原始音频字节
$audio->getFormat();   // 'wav'
$audio->getSize();     // 字节数

// 音频 → 文本
$text = $ai->audio()->transcribe('/tmp/record.wav', ['language' => 'zh'])->getText();

两种完全不同的响应形态，库内已归一

平台 实际返回
OpenAI / 硅基流动 / 阶跃星辰 / 智谱 二进制音频字节（Content-Type: audio/*）
MiniMax JSON，音频在 data.audio，hex 编码（不是 base64）

调用方两边都写 speech()->saveTo()，拿到的都是可以直接播放的文件。

这里有两个不会报错的坑，库内都堵上了：

  1. 平台出错时回的是 JSON，不是音频。 不判别就会写出一堆扩展名 .mp3、 内容是错误信息的文件,全程无报错。库内按响应的实际 Content-Type 判别， 拿到 JSON 一律当错误处理，saveTo() 会直接抛异常而不是写出坏文件。
  2. MiniMax 的 hex 不是 base64。 两者都是可打印字符，用 base64_decode 去解 不报错，只表现为「文件存下来了但放不出声」。另外它的错误不体现在 HTTP 状态码上—— base_resp.status_code 非 0 才是失败，此时 HTTP 仍是 200，库内会检查这个字段。

音色缺省

OpenAI 的 voice 是必填参数，不传直接 400。库内会补一个默认音色， 让 speech('你好') 开箱可用；你显式传了就以你的为准。

(new \Ai\Protocol\OpenAI())->knownVoices();
// ['alloy','ash','ballad','coral','echo','sage','shimmer','verse','marin','cedar']

这份音色清单据 OpenAI 官方 OpenAPI 规范（2026-08），与早年文档已经不同： fable / nova / onyx 已不在枚举里，新增了 marin / cedar。 照着旧印象写音色名会直接 400。

语音识别走 multipart 上传

transcribe() 只接受本地文件（路径字符串或 AIFile 实例）。 远端音频请先用 Ai\Helpers\Media::download() 取回落盘——库不会顺手替你下载， 因为那需要 SSRF 防护，不该由上传逻辑代劳。

支持的平台与模型

模型清单据各平台官方文档登记：

平台 TTS 模型 ASR
OpenAI gpt-4o-mini-tts、tts-1-hd、tts-1 gpt-4o-transcribe、whisper-1 等
硅基流动 FunAudioLLM/CosyVoice2-0.5B、fnlp/MOSS-TTSD-v0.5 FunAudioLLM/SenseVoiceSmall、TeleAI/TeleSpeechASR
阶跃星辰 step-tts-mini、step-tts-2、step-tts-vivid ✅
智谱 glm-tts glm-asr-2512
MiniMax speech-2.8-hd、speech-2.8-turbo 等 8 个 ✖（形态不同，未接入）
Cohere ✖ cohere-transcribe-03-2026（须显式传 language）
Mistral / Groq / Together / Fireworks / OpenRouter / DeepInfra ✅ ✅

通义（qwen）暂不支持：其 OpenAI 兼容模式没有语音接口（实测 404）， 原生 DashScope 语音接口形态差异很大，暂未接入。

讯飞只提供 WebSocket，走 $ai->realtime()。

WebSocket 实时通道（已可用）

讯飞的语音能力只提供 WebSocket，没有等价的 HTTP 接口。本库把它纳了进来， 省得你为一个平台单独写一套 WS 对接。

$ai = AI::create([
    'protocol' => 'spark',
    'app_id'   => '<控制台的 APPID>',
    'api_key'  => '<APIKey>:<APISecret>',   // 冒号拼接
]);

// 必须显式启用 WebSocket 通道
$ai->realtime()->useWebSocket()->speech('你好世界')->saveTo('/tmp/hello.mp3');

$text = $ai->realtime()->useWebSocket()->transcribe('/tmp/record.wav')->getText();

为什么必须显式调用 useWebSocket()

通道默认是 null，不显式启用就不会建立任何连接。这不是啰嗦—— WebSocket 是长连接，超时语义、错误形态都和普通 HTTP 请求不同， 握手成功之后仍可能因帧格式问题静默挂死（服务端既不回数据也不发 close）。 这种行为差异不该在你不知情时自动发生。

不启用直接调用会得到明确提示，而不是含糊的失败：

未指定实时通道协议。当前平台的语音能力只能通过 WebSocket 访问，
请显式调用 ->useWebSocket() 启用。……

零新增依赖

RFC 6455 客户端是纯 PHP 实现的，只用到 stream_socket_client / stream_socket_enable_crypto / random_bytes / pack 这些核心函数， 不需要 ext-sockets，也不引入任何 composer 包。

wss:// 需要 ext-openssl（绝大多数环境都有）。缺失时会给出明确提示， 不会变成一个难懂的连接错误。已在 composer.json 的 suggest 里声明。

凭据与 HTTP 接口不同

讯飞语音的鉴权不走请求头：用 APIKey/APISecret 算 HMAC-SHA256 签名后拼进 URL 查询串。 签名带时间戳且有效期很短，每次连接都要重算，不能缓存 URL。另外还需要 app_id， 是 APIKey/APISecret 之外的第三个凭据。这些库内都处理好了，你只要把三个值配上。

语音识别要的是裸 PCM

讯飞听写接受 16k / 16bit / 单声道的裸 PCM。传 .wav 时库会自动剥掉文件头取出 data 块——直接把整个 wav 灌进去，头部那几十字节会被当成音频采样， 表现为开头一小段噪音或识别结果异常，不会报错，很难往文件格式上想。

其它容器格式（mp3 / m4a 等）请自行转码后再传。本库不做转码， 那需要引入 ffmpeg 之类的外部依赖。

讯飞的 HTTP 语音接口不存在

$ai->audio()->speech() 在讯飞协议上会明确报「不支持」，并在错误信息里列出 本协议支持的能力（含「实时通道」），把你导向 $ai->realtime()。 比让请求打到一个不存在的 HTTP 路径、再拿一个含糊的 404 要好。

视频生成 / 异步任务（已可用）

视频接口无一例外都是异步任务式，所以 generate() 返回的是任务而不是视频。

// Web 请求里：提交后存库就结束，不阻塞
$task = $ai->video()->generate('日落的海边', ['duration' => 5, 'ratio' => '16:9']);
$db->save(['task' => json_encode($task->toArray())]);

// 定时任务 / 队列 worker 里：恢复并查询
$task = AsyncTask::fromArray(json_decode($row['task'], true), $ai);
if ($task->refresh()->isSucceeded()) {
    $task->getResult()->saveTo('/var/www/videos/x.mp4');
}

为什么不直接等结果

视频生成动辄几分钟。wait() 存在，但不要在 Web 请求里调用—— 它会占死一个 PHP-FPM worker，并发一上来整站就挂。那个方法是给 CLI 脚本和队列 worker 用的。

// 只在 CLI / worker 里这么用
$task->wait(300, 3);   // 最多等 300 秒，起始间隔 3 秒后指数退避

超时不是失败

wait() 超时不抛异常。任务在平台侧仍然在跑，抛异常会诱导你 catch 之后当失败处理， 白白丢掉一次已经付费的生成。超时后：

$task->isTimeout();   // true
$task->isDone();      // false —— 所以 if ($task->isDone()) 的写法天然安全
$task->isFailed();    // false —— 不会被误当失败
$task->getMessage();  // 「任务仍在平台侧处理中……请保存 task_id「xxx」，稍后恢复后再查询」

四家平台的状态取值差异已归一

平台 状态字段 取值
通义万相 task_status PENDING / RUNNING / SUCCEEDED / FAILED / CANCELED
智谱 CogVideoX task_status PROCESSING / SUCCESS / FAIL
火山方舟 Seedance status queued / running / succeeded / failed
MiniMax 海螺 status Preparing / Queueing / Processing / Success / Fail
Gemini Veo status queued / in_progress / completed / failed

库内统一成 pending / running / succeeded / failed / timeout 五种。 平台新增了库里没见过的状态值时，按「处理中」对待而不是失败—— 让用户的任务因为平台加了个新状态就全变失败，是最糟的降级方式。

MiniMax 是三段流程

其余三家是「提交 → 轮询」两步，MiniMax 多一步:

提交 POST /v1/video_generation           → task_id
查询 GET  /v1/query/video_generation     → status=Success，但只给 file_id
再取 GET  /v1/files/retrieve             → 真正的下载地址（有效期 9 小时）

库内自动走完三步，调用方感知不到差别。另外 MiniMax 的失败不体现在 HTTP 状态码上—— base_resp.status_code 非 0 才是失败，此时 HTTP 仍是 200，库内会检查这个字段。

支持的平台与模型

平台 模型（据官方文档）
通义万相 wan2.7-t2v、wan2.7-t2v-2026-06-12
智谱 cogvideox-3、cogvideox-2、cogvideox-flash、viduq1-*、vidu2-*
火山方舟 Seedance 系列
MiniMax MiniMax-Hailuo-2.3、MiniMax-Hailuo-02、T2V-01-Director、T2V-01
Gemini veo-3.1-generate-preview、veo-3.1-lite-generate-preview、gemini-omni-flash
Z.ai 视频生成（据 z.ai 文档）

⚠️ 结果 URL 都有有效期（万相约 24 小时、MiniMax 仅 9 小时）， 存 URL 进库很快就会失效,必须及时 saveTo() 落地。

媒体结果要及时落地

多数平台返回的图片/视频 URL 有效期只有几小时到 24 小时， 只把 URL 存进库，第二天就会全部失效。用 saveTo() 及时取回：

$img->saveTo('/var/www/uploads');          // 图片，返回路径数组
$audio->saveTo('/tmp/hello.mp3');          // 音频
$video->saveTo('/var/www/v.mp4');          // 视频，默认上限 64MB

下载走库内带 SSRF 防护的抓取器（IP 钉死、逐跳重校验），不是裸 file_get_contents()。 目标目录必须已存在——库不会自动创建，避免路径写错时在磁盘上散落一堆空目录。

WebSocket 通道默认关闭

讯飞等平台的语音能力只提供 WebSocket。本库已集成， 但必须显式启用，因为 WS 是长连接，超时与错误语义都和普通 HTTP 请求不同：

$ai->realtime()->useWebSocket()->speech('你好世界');

不启用直接调用会得到明确提示，而不是含糊的连接失败。

自定义网关

把 base_url 指向自建网关或中转服务时，图像/语音端点会自动跟着走同一个网关， 不会回落到官方地址（那意味着把数据发到你没指定的服务器上）。 需要单独指定某个能力的完整地址时，用 <能力名>_endpoint 配置项：

$ai = new AI([
    'api_key'        => '...',
    'base_url'       => 'https://my-gateway.com/v1',
    'image_endpoint' => 'https://another-host.com/v1/images/generations',  // 可选
]);

这个配置项同时是逃生口：库对某平台能力的判断有误或过时时，配上 <能力名>_endpoint 就能绕过声明检查。若该协议族本身没有对应形态的解析器 （比如 Claude 之于图像），仍会报错，但会点明是哪一层挡住的，并建议改用 protocol + base_url。

给自定义协议类的迁移说明

ProtocolInterface 在 v1.14.0 新增了 4 个能力方法。

class MyProtocol implements ProtocolInterface
{
    use \Ai\Protocol\Concerns\CapabilityDefaults;   // ← 只需加这一行
    // ……原有 6 个方法一字不用改……
}

受限 PHP 环境：禁用了 exec / proc_open

生产环境（宝塔 / cPanel 面板的默认配置、共享主机）常在 php.ini 的 disable_functions 里禁掉 exec、shell_exec、proc_open。被禁的函数是从函数表里消失，调用时报的是：

Fatal error: Uncaught Error: Call to undefined function Ai\Agent\Workspace\exec()

@ 抑制符挡不住，try/catch 也接不到。所以库里每个要跑外部命令的地方都先探测再调用， 探测不到就降级——功能少一块，但 Agent 照常跑完：

能力 被禁后的行为
git 工作区上下文（WorkspaceManager） 退化成「非 git 仓库」，上下文里只剩 cwd
工作区快照（WorkspaceSnapshot） 仍靠 .git 目录认仓库，分支 / 提交 / diff 取不到而留空
bash 工具（含后台模式） 返回带原因的失败 ToolResult，不抛异常
验证器（php -l / 单测 / git diff） 记为跳过（通过 + 注明原因），不判失败——跑不了检查不等于代码有问题，判失败只会让 Agent 白白重试
MCP stdio 传输 open() 抛 RuntimeException 并说明原因
浏览器工具 isAvailable() 与 launch() 均返回 false
后台派发（BackgroundDispatcher） 从 fork 档退回 sync 同步执行
rg / git 二进制探测（Shell::hasBinary） 一律 false，走纯 PHP 回退实现

自己的代码要判断时用 Ai\Helpers\Shell：

use Ai\Helpers\Shell;

Shell::canExec();                  // exec() 能用吗
Shell::canProcOpen();              // proc_open() 能用吗（管道、超时、后台进程都靠它）
Shell::canRunCommand();            // 两条路通任意一条即可
Shell::hasFunction('shell_exec');  // 任意函数：function_exists + disable_functions / suhosin 黑名单

// 统一入口：exec / proc_open 哪个能用用哪个；两条都被禁时 code = -1、out = ''
$res = Shell::run('git status --porcelain', '/path/to/repo');  // ['code' => int, 'out' => string]

唯一没有降级路径的是 Ai\Cli\ClaudeCode——它本身就是「跑本机的 claude 程序」。 这类环境下请注入自定义执行器走 SSH，见上文「自定义执行器」。

已知限制

许可证

MIT License

All versions of php-ai with dependencies

PHP Build Version
Package Version
Requires php Version >=7.1
ext-curl Version *
ext-json Version *
ext-mbstring Version *
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package likun-mci/php-ai contains the following files

Loading the files please wait ...