术语表

每项标注 L1 / L2 / L3：你大概在哪个学习阶段会遇到。

消息与调度

术语	级别	简述
MessageDispatcher	L2	入站消息调度器：Guardrail → Route → Handle（命令 / AI）。zhin.js 默认会注册。
Guardrail	L2～L3	Dispatcher 第一阶段：必须 next() 才放行；适合鉴权、限流、全局过滤（如消息过滤 Feature）。
exclusive	L2	路由默认模式：命中命令则不走 AI；否则再判 AI。
dual	L3	双轨：命令与 AI 独立判定；可配置顺序与是否允许两次回复。
message.receive（插件生命周期）	L2	根插件上的事件：在 MessageDispatcher.dispatch 完成之后 触发。适合收件箱、统计。
adapter.on('message.receive')	L3	适配器级监听：在 插件生命周期之后 调用；仅建议用于 观测/UI，不作业务路由。
before.sendMessage	L2	出站统一钩子：所有 sendMessage / $reply 路径都会经过，可改写发出内容。
replyWithPolish / getOutboundReplyStore	L3	Dispatcher 与 before.sendMessage 协作的润色机制；依赖异步上下文，见 AI 文档。

插件与运行时

术语	级别	简述
Plugin / usePlugin()	L1～L2	IM 侧插件单元；usePlugin() 按文件归属插件树。
Feature	L2	能力模块（如 CommandFeature、ToolFeature），通过 provide 挂到根上下文。
PluginBase（kernel）	L3	@zhin.js/kernel 中的通用插件基类；不等同于 @zhin.js/core 的 Plugin，IM 主路径以 core 为准。
addMiddleware	L2～L3	在 Dispatcher 主处理之后 执行的扩展链；前置拦截优先 Guardrail。

包与生态

术语	级别	简述
@zhin.js/ai	L3	与 IM 无关的 LLM / Agent 循环等。
@zhin.js/agent	L3	IM 场景下 ZhinAgent、AIService 等编排。
@zhin.js/satori	L3	Vercel satori 的 SVG 渲染工具包；不是 Satori 协议适配器。

AI 与 Agent

术语	级别	简述
ZhinAgent	L3	IM 场景主 Agent：收集工具、构建上下文、调用 @zhin.js/ai 引擎完成回合。
AgentOrchestrator	L3	ctx.agent 背后的编排中枢：Tool / Skill / SubAgent / MCP / Hook 注册表。
ctx.ai（AIService）	L3	业务侧 AI 服务：会话、createAgent、runAgent。
ctx.agent	L3	扩展编排： addTool、addSkill、addMcp 等注册 API。
Subagent（spawn_task）	L3	主 Agent 派发的后台子任务，默认即可用，与 harness「角色」不同。
toolSearch	L3+	Advanced：ai.agent.toolSearch: true 启用 deferred Worker 编排，控制 prompt 体积。
MCP Client	L3+	Zhin 消费外部 MCP Server 工具（ai.mcpServers、ai.memoryMcp）。
MCP Server	L3+	Zhin 对外暴露工具（@zhin.js/mcp），供 Claude / Cursor 等调用。
Bootstrap	L2～L3	SOUL.md / AGENTS.md / TOOLS.md 注入 system prompt 的引导文件。

AI 能力文件约定

术语	级别	简述
*.tool.md	L2	文件化 Tool 定义。YAML frontmatter 声明参数/元数据，可选 handler 指向执行文件或用 body 作为 模板。框架自动扫描 tools/ 目录。
*.agent.md	L2	文件化 Agent 预设。frontmatter 声明名称/关键词/关联工具/模型，body 作为 systemPrompt。框架自动扫描 agents/ 目录。
plugin.yml / PluginManifest	L2	插件元数据清单（name、description、version）。通过 plugin.manifest getter 访问，fallback 到 package.json。

返回 学习路径。