AI 能力总览
默认安装的 Zhin 只会执行命令,不会"聊天"。启用 AI 后,没有匹配到任何命令的消息会交给大模型回答,模型还可以调用你写的工具。
AI 是可选的:不启用时,Bot 不依赖任何模型 SDK,也不需要 API Key。
三步启用
1. 运行向导
npx zhin setup --ai
pnpm install向导会让你选择模型服务(OpenAI、Anthropic、DeepSeek、Google、OpenAI 兼容接口,或本地的 Ollama),然后安装对应 SDK 和 Agent 运行时,并在 package.json 里声明工具与 Prompt Section 能力。
2. 填写密钥
云端模型的 Key 写在 .env 里(向导会提示变量名,例如 AI_API_KEY)。使用本地 Ollama 时不需要 Key。
3. 试一试
pnpm dev在 Sandbox 私聊里直接发一句话,或者在群聊里发 ai: 你好,Bot 会用模型回复。
向导写入 zhin.config.yml 的配置大致如下:
ai:
enabled: true
providers:
openai-main: # 自己起的名字
sdk: openai
apiKey: ${AI_API_KEY}
agents:
zhin: # 主 Agent,必须叫 zhin
provider: openai-main
model: gpt-4o-miniproviders 定义"连哪个模型服务",agents 定义"哪个 Agent 用哪个模型"。
不用向导,手动安装
pnpm add @zhin.js/agent zod ai
pnpm add @ai-sdk/openai # 按所用厂商安装对应的 SDK只装 @zhin.js/agent 不足以让 tools/、prompt-sections/ 目录生效,还需要在 package.json#zhin.features 中声明 @zhin.js/tool 与 @zhin.js/prompt-section。代码里从 zhin.js/agent(或 @zhin.js/agent)导入 ZhinAgent、AIService 等。模型 SDK 是可选依赖,缺失时启动会报 Missing peer dependency 并给出安装命令。
AI 什么时候会回复
没有匹配到命令的消息,按下面的顺序判断是否交给 AI:
| 顺序 | 情况 | 默认行为 |
|---|---|---|
| 1 | 消息以 /、!、! 开头 | 跳过 AI,避免和命令冲突 |
| 2 | 消息以 #、AI:、ai: 开头 | 交给 AI(私聊和群聊都生效),去掉前缀后作为问题 |
| 3 | 群聊或频道中 @ 了 Bot | 交给 AI |
| 4 | 私聊 | 整条消息直接交给 AI |
| 5 | 私聊中包含设置的关键词 | 交给 AI |
所以在群里,Bot 默认不会插话,只有被 @ 或使用前缀时才回复。这些规则都可以修改,见 ai.trigger。
让 AI 做事
AI 默认只能聊天。要让它查天气、搜歌、操作数据库,写一个工具放进 tools/:
// tools/weather/index.ts
import { defineAgentTool } from '@zhin.js/tool';
import { z } from 'zod';
export default defineAgentTool<{ city: string }>({
description: '查询城市的实时天气',
inputSchema: z.object({ city: z.string().min(1) }),
async execute({ city }) {
const response = await fetch(`https://wttr.in/${encodeURIComponent(city)}?format=3`);
return response.text();
},
});工具参数的 schema 会原样发给模型,enum、anyOf、可空类型、integer、format 和取值范围都会保留,MCP 工具也一样。模型传回的参数按同样的约束校验,不符合时会把错误告诉模型,让它重新调用。Gemini 不接受没有类型的字段,这类字段发给 Gemini 时会按字符串处理。
限制工具的使用范围、要求用户确认、用 Skill 封装流程、补充业务背景,见 Agent 工具与技能。
常见调整
| 我想…… | 改这里 |
|---|---|
| 换模型或厂商、接入本地模型 | ai.providers |
| 让群里不 @ 也能触发,或修改前缀 | ai.trigger |
| 只对部分用户或群开放 AI | ai.access |
| 不同的群用不同的 Agent 或模型 | ai.agents |
| 让 AI 使用外部 MCP 服务器的工具 | ai.mcpServers |
| 控制 AI 能执行哪些 Shell 命令、是否需要审批 | ai.agent |
| 让 AI 理解语音、回复语音 | 语音 |
配置参考
全部配置位于 zhin.config.yml 的 ai: 段,${VAR} 会从环境变量展开。
ai.providers
每个 provider 以你起的名字为键,sdk 决定使用哪个模型 SDK:
ai:
providers:
openrouter:
sdk: openai-compatible
baseUrl: ${OPENROUTER_BASE_URL}
apiKey: ${OPENROUTER_API_KEY}| sdk | 需要安装 | 关键配置 |
|---|---|---|
openai | @ai-sdk/openai | apiKey,可选 baseUrl(代理根路径自动补 /v1,规则同 openai-compatible) |
openai-compatible | @ai-sdk/openai-compatible | baseUrl + apiKey(路径里没有版本号时自动补 /v1,见下方 compat);Cloudflare Workers AI 可用 accountId 代替 baseUrl |
anthropic | @ai-sdk/anthropic | apiKey,可选 baseUrl(自动补 /v1) |
deepseek | @ai-sdk/deepseek | apiKey,可选 baseUrl |
minimax | @ai-sdk/minimax | apiKey,可选 baseUrl(默认 https://api.minimax.io/anthropic/v1;国内站写 https://api.minimaxi.com/anthropic,自动补 /v1) |
google | @ai-sdk/google | apiKey,可选 baseUrl(自动补 /v1beta) |
ollama | @ai-sdk/openai-compatible(通过 OpenAI 兼容接口) | host(默认 http://127.0.0.1:11434,自动补 /v1),不需要 apiKey;建议写 contextWindow(见下方) |
可选字段:
models:允许使用的模型列表。不写时,启动后会自动从/v1/models获取(先用上次的缓存,再在后台刷新)。input:模型能接收的内容类型,text | image | audio | video | file。不写时按 SDK 和模型名取默认值:sdk: google的 Gemini 对话模型原生多模态,默认text, image, audio, video, file;TTS、embedding、图像生成和 Live 模型只按文本处理。sdk: openai的 GPT-4o、GPT-4.1、GPT-4.5、GPT-5.x 以及 o1、o3、o4-mini,和sdk: anthropic的 Claude 3 及以后的模型,默认text, image。audio、realtime、TTS、search、embedding、图像生成这些变体,以及 o1-mini、o3-mini,只按文本处理。PDF 等文件不默认开启,需要时写input: [text, image, file]。- 其他 SDK(DeepSeek、MiniMax、Ollama、各类网关)只按文本处理,因为同一家的模型能力不一样。Groq 例外:Llama 4 Scout / Maverick 默认
text, image,GPT-OSS 等其他模型只按文本处理。
写了
input就以它为准。contextWindow:上下文窗口大小。不写时一般按 128k 估算;sdk: ollama例外:先读OLLAMA_CONTEXT_LENGTH环境变量(zhin 和 Ollama 在同一台机器时有效),否则按 4096 计算。Ollama 按显存分配上下文(24 GiB 以下 4k,24–48 GiB 32k,48 GiB 以上 256k),OpenAI 兼容接口无法逐请求调大,超出部分会被静默截掉开头(包括 system prompt),所以框架宁可少估。请把contextWindow写成ollama ps里 CONTEXT 列的值;没写时启动会给出提示。thinkingLevel:思考深度,off | low | medium | high。不写时用 provider 默认。框架把它作为 AI SDK 的reasoning参数传给各 SDK,再由 SDK 换成自己的设置:Gemini 3 的thinkingLevel(off对应minimal)、Gemini 2.5 的思考预算、Claude 的 thinking 预算、OpenAI 和 DeepSeek 的 reasoning effort。如果providerOptions里已经写了思考设置(thinkingConfig、thinking、reasoningEffort或effort),以providerOptions为准。MiniMax 固定用自适应思考,不受影响。maxOutputTokens:每次请求的输出 token 上限,默认8192。Gemini 和 Claude 的思考 token 也算在里面,所以thinkingLevel: high时建议调大,免得回复被截断。compat(openai-compatible/ollama):includeUsage:是否请求流式 usage(stream_options.include_usage),默认true。不写的话大多数兼容服务流式时不返回 token 用量;少数拒绝该字段的服务设为false。appendV1:baseUrl是否补/v1。不写时:路径里已有版本段(如/api/v3、/api/paas/v4、/v1beta/openai)或以/openai结尾就原样使用,否则补/v1(旧配置https://host、https://host/api行为不变)。true总是补(旧行为),false总是原样。promptCacheKey:是否发送 OpenAI 的prompt_cache_key,默认false(严格的网关会拒绝未知字段)。supportsDeveloperRole(sdk: openai):设为false时推理模型(o 系列、gpt-5)的系统提示用system角色发送,给不认developer的 OpenAI 协议端点用。supportsReasoningContent、toolCallsInAssistant已废弃,不起作用。
authScheme:Authorization头方案。不写时用 SDK 默认(OpenAI 系Bearer,Anthropicx-api-key,Googlex-goog-api-key);''发送Authorization: <key>;Bearer、Token等发送Authorization: <scheme> <key>。对话请求和模型列表请求用同一规则。timeout、maxRetries:该 provider 的单次请求超时(毫秒,0 关闭)和每个模型的重试次数,覆盖ai.providerResilience的requestTimeoutMs/maxRetries;按模型配置的modelHarness.requestTimeoutMs仍然优先。firstChunkTimeoutMs、chunkTimeoutMs:流式卡顿超时(毫秒),默认关闭。前者限制等响应头和第一个 chunk 的时间,后者限制两个 chunk 之间的静默时间。超时按 timeout 处理:重试,用尽后切换备用模型。比timeout更早发现“连上了但不出字”的请求,建议设成几十秒。imageGeneration:文生图的默认参数。providerOptions:按 SDK 名分组的 AI SDKproviderOptions,每次请求都会合并进去。Gemini 常用的是安全设置和思考深度:yamlai: providers: gemini: sdk: google apiKey: ${GEMINI_API_KEY} defaultModel: gemini-3.8-flash providerOptions: google: safetySettings: - { category: HARM_CATEGORY_HARASSMENT, threshold: BLOCK_ONLY_HIGH } thinkingConfig: { thinkingLevel: low }Gemini 因安全策略(SAFETY、PROHIBITED_CONTENT、RECITATION、提示词被拦截等)拒答时,用户会看到一句礼貌的说明(“抱歉,这条内容触发了模型的内容安全策略,没能生成回复(SAFETY),换个说法再试试吧”),而不是一条空回复。这种拒答不会重试,也不会切换到备用模型:同样的内容再问一次结果相同,换模型绕过拒答等于绕过你配置的
safetySettings。Gemini 走隐式缓存:system prompt 和工具定义保持不变,命中的 token 记在 usage 的cacheRead和 turn trace 的cache_read_tokens里。如果想要更稳定的折扣,可以开显式缓存:contextCache: { mode: explicit, ttlSeconds: 600 }。开启后,框架会给 system prompt 和工具定义建一个cachedContents,在 TTL 内复用;前缀变了就新建一个并删掉旧的,服务端缓存失效时自动退回完整请求,建不了(比如前缀太短)时退回隐式缓存。缓存按存储时长计费。显式缓存只支持 Gemini 3 / 2.5,Gemini 4 Argon 及以后不支持。Gemini 走自己的代理:如果代理只是原样转发(请求、
x-goog-api-key鉴权和响应都和官方一致,只是域名不同),把baseUrl指到代理即可。写到根路径或带/v1beta都行,结尾的/会被去掉,不会出现重复的/v1beta。不写时默认https://generativelanguage.googleapis.com。generateContent、流式的streamGenerateContent、显式缓存的cachedContents(创建和删除)以及模型列表都会走这个地址。代理需要额外请求头时可以加headers,所有请求都会带上,可不填:yamlai: providers: gemini: sdk: google apiKey: ${GEMINI_API_KEY} baseUrl: https://gemini-proxy.example.com # 等价于 https://gemini-proxy.example.com/v1beta headers: # 可选 x-proxy-tag: zhinGroq(GroqCloud):走
openai-compatible,框架内置了 Groq 预设。别名写groq(或groqcloud)时可以省略sdk和baseUrl;baseUrl指向api.groq.com时,无论别名是什么都按 Groq 处理,sdk: openai也会被改成openai-compatible:yamlai: providers: groq: sdk: openai-compatible baseUrl: https://api.groq.com/openai/v1 apiKey: ${GROQ_API_KEY} models: - openai/gpt-oss-120b - openai/gpt-oss-20b # thinkingLevel: medium # GPT-OSS 默认 low,可改 medium / high注意事项:
- 之前的思考内容按 Groq 接受的
reasoning字段回传(Groq 拒绝 SDK 默认的reasoning_content,否则工具循环的第二步会 400)。 - Groq 不支持
logprobs、top_logprobs、logit_bias和大于 1 的n,这些字段不会发出去。 reasoning_effort只发给 GPT-OSS 和 Qwen 3;GPT-OSS 默认low,回复快,也更不容易碰到免费档每分钟 8K token 的上限。其他模型(如 Llama)即使配置了thinkingLevel也不会带这个字段。- GPT-OSS 只收文本,图片会按"模型不支持图片"处理,不会发给 Groq;Llama 4 Scout / Maverick 默认
text, image。写了input以它为准。 - 上下文窗口按模型名推断:GPT-OSS 是 131072,其他模型按 128k 估算,可用
contextWindow覆盖。 - 免费档限额很低(GPT-OSS 约每分钟 8K token、每天 1000 次请求,见 Groq 限额)。每分钟的限额(RPM / TPM)触发 429 时按
retry-after等待后重试;每天的限额(RPD / TPD)当天重试没用,直接切换到下一个候选模型(限额按模型计算),没有候选时提示今天的额度已用完。
- 之前的思考内容按 Groq 接受的
ai.agents
把 Agent 名字绑定到 provider + model。zhin 是主 Agent,必须存在:
ai:
agents:
zhin:
provider: openrouter
model: openrouter/free
mcpServers: [icqq] # 这个 Agent 使用的 MCP 服务器
nickname: 小智 # AI 的自称和界面展示名
planner:
provider: openrouter
model: openrouter/free
permission: # 它能派出哪些子 Agent
task: { "researcher": allow, "*": deny }| 字段 | 说明 |
|---|---|
provider / model | 引用 ai.providers 的名字与模型 id(必填) |
mcpServers | 引用 ai.mcpServers 中的 name |
nickname | AI 的自称与展示名 |
permission.task | glob → allow / deny,限制 spawn_task 能派出的子 Agent |
IM 消息总是交给 zhin;其他 Agent 只按名字调用(spawn_task、协作角色)。
已弃用:priority / match
ai.agents.<name>.priority 和 match(包括 hasMedia、scene、adapter 等全部条件)从来没有生效过。现在仍然接受,但启动时会告警,zhin config check --fix 会删除它们,下一个 minor 版本移除。想让文本模型看懂图片,请用 ai.multimodal.perception。
ai.mcpServers
让 AI 连接外部的 MCP 服务器,使用对方提供的工具。需要安装 @modelcontextprotocol/sdk。
ai:
mcpServers:
- name: icqq
transport: streamable-http # stdio | streamable-http | sse
url: ${ICQQ_MCP_URL}
headers:
Authorization: Bearer ${ICQQ_MCP_TOKEN}
- name: filesystem
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/zhin-mcp-test"]- 连接成功后,对方的工具以带服务器名前缀的名字加入工具池。
- 任何一个服务器连接失败,新配置都不会生效,旧版本继续服务。
ai.agents.<name>.mcpServers只能引用这里声明过的名字,否则配置校验失败。
反过来:把你的 Bot 变成 MCP 服务器
如果想让外部 AI 客户端连接你的 Bot,使用顶层的 mcp: 配置,并运行 pnpm add @zhin.js/mcp @zhin.js/agent zod ai。这与 ai.mcpServers 是两回事,设置其中一个不会开启另一个。见 MCP Server 配置。
ai.trigger
ai:
trigger:
prefixes: ["ai:"] # 默认 ['#', 'AI:', 'ai:']
ignorePrefixes: ["/"] # 默认 ['/', '!', '!']
respondToAt: true # 默认 true:群里 @ Bot 时触发
respondToPrivate: true # 默认 true:私聊直接触发
keywords: [] # 私聊中包含这些词时触发
timeout: 60000 # 单轮超时(毫秒)
thinkingMessage: 思考中… # 可选:开始处理前的占位回复
errorTemplate: "❌ AI 处理失败: {error}"
masters: ["10001"] # 有审批权的用户
trusted: [] # 受信任用户(权限低于 master)@ 触发依赖适配器标记消息为"提到了 Bot"(例如 CQ 码、Slack 的 app_mention)。
ai.access
控制哪些会话可以使用 AI(例如为满足平台对 AIGC 的合规要求):
ai:
access:
mode: whitelist # open(默认)| closed | whitelist
users: ["10001"] # 允许的用户 id
groups: ["123456"] # 允许的群 / 频道 id
denyMessage: 当前会话未开放 AI 功能。私聊被拒绝时回复 denyMessage;群聊和频道被拒绝时不回复。
ai.multimodal.perception
主模型不能看图(例如 Groq 的 gpt-oss 只收文本)时,图片默认只会变成 [Media unsupported:provider_input: image] 占位,AI 不知道图里是什么。配置 perception 后,框架先用一个能看图的模型(例如 Gemini Flash-Lite)把图片描述成文字,再交给主模型:
ai:
providers:
groq:
sdk: openai-compatible
baseUrl: https://api.groq.com/openai/v1
apiKey: ${GROQ_API_KEY}
gemini:
sdk: google
apiKey: ${GEMINI_API_KEY}
agents:
zhin:
provider: groq
model: openai/gpt-oss-120b
multimodal:
perception:
provider: gemini # 必填,ai.providers 里的名字
model: gemini-2.5-flash-lite # 必填,这个模型必须声明能接收对应类型
kinds: [image] # 可选:image | video | file,默认 [image];file 只处理 PDF
maxChars: 800 # 可选:描述最长字符数,默认 800
timeoutMs: 30000 # 可选:单次请求超时,默认 30000
maxItemsPerTurn: 4 # 可选:每个回合最多描述几项,默认 4| 字段 | 说明 |
|---|---|
provider / model | 用来描述媒体的模型,provider 必须是 ai.providers 里的名字;配置错误时启动失败,zhin config check 也会报错 |
kinds | 要描述的类型。音频不在这里,仍走 ai.multimodal.audio 的语音转写 |
maxChars | 描述超出时截断 |
timeoutMs | 单次请求超时;失败最多重试 1 次,走和主对话相同的重试、超时和错误分类 |
maxItemsPerTurn | 一个回合里超出数量的媒体保持占位 |
行为说明:
- 只处理主模型收不了的媒体。主模型本身能看图时,图片照常直接发给主模型,不会调用
perception。 - 描述以
[图片描述]/[视频描述]/[文件描述]开头,并标注为不可信的外部内容:图片里的文字可能夹带指令,模型只把它当作数据。读过描述的回合属于“已接触外部内容”,之后执行命令、给其他会话发消息、改配置、建定时任务都需要审批,审批卡片的来源链会写“图片/媒体的自动描述”。 - 描述会随用户消息写入会话历史,之后的回合可以继续问“刚才那张图”;图片本身不写入历史。
- 相同内容的图片(按字节的 sha256)只描述一次,常见的表情包和贴纸不会重复调用。
- 描述失败、超时或超出
maxItemsPerTurn时,回到原来的占位,回合照常进行。每项媒体的结果记录在zhin trace时间线的media_resolution事件里,描述成功时code为media_perception并带上所用模型。 - 不配置
perception时行为与之前完全一样。
ai.agent
ai.agent 控制 AI 的运行方式,其中最重要的是 bash 等执行类工具的安全策略:
ai:
agent:
execSecurity: allowlist # deny | allowlist(默认)| full
execPreset: readonly # readonly | network | development | custom
execAllowlist: [make] # execPreset=custom 时的白名单
execApprovalMode: ask # ask(默认)| bypass | auto
gitStatus: true # 默认 true:在提示词中注入一行 git 状态(非 git 仓库自动跳过)
contextPaths: [] # 额外注入系统提示词的上下文文件(支持 ~ 与相对路径)
systemPromptMaxChars: 100000 # 系统提示词总字符上限
inboundQueue:
groupMode: supersede # 默认:同一发起人的新消息替换他尚未回复的回合;fifo:全部按到达顺序排队
maxQueuedTurns: 5 # 每个会话最多排队的回合数
ttlMs: 180000 # 排队超时命令白名单:execPreset 逐级放宽——readonly(ls、cat、grep、find 等)→ network(再加 curl、wget、ping 等)→ development(再加 npm、node、git、python 等)。无论哪种模式,sudo、eval、dd、export 等危险命令一律拒绝,rm -rf node_modules 这类操作直接阻断。
审批方式:
execApprovalMode | 行为 |
|---|---|
ask(默认) | 向 master 请求审批 |
auto | 交给一个没有工具的审核 Agent 判断;它无法判断时再询问 master;模型出错、超时或输出无效时直接拒绝 |
bypass | 跳过审批,但仍然不能绕过危险命令黑名单、工具权限、文件 / 网络边界和沙箱 |
审批时,群聊和频道里可以选择"拒绝 / 仅本次 / 当前会话 / 始终允许",私聊里是"拒绝 / 仅本次 / 始终允许"。"当前会话"对会话中所有人生效;"始终允许"只对当前发送者生效;所有持续决定都只绑定当前会话。/approve always bash 与 /approve rule <正则> 管理本账号的持久放行规则。
更多细节
- 全局上下文文件:除
contextPaths外,还会自动加载~/.config/zhin/AGENTS.md与~/.config/zhin/ZHIN.md(不存在则跳过),作为# User Context段放在项目上下文之前;单个文件最多 8KB,总计最多 16KB。 - 提示词预算:超过
systemPromptMaxChars时,先移除opportunistic的内容;required的内容放不下时,本轮明确失败。 - 命令检查链:危险黑名单 → 去掉环境变量前缀(
FOO=bar cmd按cmd匹配)→ 去掉 wrapper(timeout 10 cmd)→ 拆分复合命令(&&、|逐段检查)→ 非full模式下拒绝换行、$(...)和反引号 → 只读命令自动放行。审批通过当前回合的ApprovalPort发起。 - 旧版审批文件:V1 审批文件不会在线迁移,升级前需要显式重建规则。
- 消息排队:
inboundQueue.groupMode也是默认的回合意图策略。supersede表示同一发起人的新消息会替换他自己尚未回复的回合(其他成员的消息总是排队,不会打断别人);fifo表示按到达顺序等待。详见 Agent:回合运行中又来了消息。steer、follow_up、observe由适配器、命令或其他策略显式指定;跨参与者的steer/follow_up授权只能由 Host 的可信resolveTurnIntent策略产生,消息 metadata 不能自行声明。工具始终受当前回合的权限约束,执行日志会记录发起控制的用户与回合 ID。
它是怎么工作的
启动时,Zhin 会自动清理 ai: 配置:凭据展开后为空的 provider 会被剔除(只记录 debug 日志),绑定到它的 Agent 一并跳过;如果最终没有可用的 zhin Agent,AI 不会启用,但不影响 Bot 的其他功能正常启动。
下一步
- Agent 工具与技能:让 AI 调用你的函数。
- Agent 深入:回合、按需加载工具、子任务、会话与上下文压缩。
- 结构化决策:Agent / Skill / Tool 推荐、检索排序与自动审核。
- 语音:语音识别与语音回复。
- Console:在浏览器里观察 AI 会话与运行情况。