能力分档与产品定位
维护者决策记录见 ADR 0015 — 能力分档模型。
Zhin.js 是 TypeScript 多通道 IM Bot 框架（插件热重载、Sandbox、Remote Console），可选 Agent 栈（@zhin.js/agent）：通过 Endpoint 接入 IM、邮件、GitHub、Sandbox 等通道，同时支持 传统命令交互、ZhinAgent 对话与 二者混合。
zhin.js 4.x 安装分层
**zhin.js 4.x 安装分层**：`pnpm add zhin.js` 仅 IM 核心（<10MB）；AI 另装 `@zhin.js/agent zod ai` 与所选 `@ai-sdk/*`。见 [ADR 0019](/adr/0019-install-size-layering) 与 [快速开始 — Install tiers](/getting-started/#install-tierszhinjs-4x)。产品对标：多通道 生活/工作助手（私聊/群聊、记忆、cron、Home Assistant、通知）——不是 Cursor / Claude Code 类的 写代码 Agent，也不内置 plan mode 或以改仓库为主轴的 Harness。IM 是 Endpoint 的主场景之一，不是产品定义的全部。
产品边界（刻意不做 vs 计划中）
| 方向 | 态度 | 说明 |
|---|---|---|
| 多轮对话、工具、记忆、Compaction、会话树 | ✅ 核心 | 服务对话与生活场景；会话树是「聊天分支」，不是代码变更计划 |
spawn_task / 子 Agent | ✅ Advanced | 任务分工（查资料、总结），非 IDE 式 plan-and-execute 写代码 |
| Assistant Runtime、Home、Profile | ✅ Advanced / opt-in | ADR 0008 路线 |
| RAG / 知识库 | ✅ Advanced | knowledge_search 工具，ai.knowledge.baseDir 配置 |
| plan mode、终端 coding harness、项目级写代码 | ❌ 不在范围 | ADR 0010 仅借鉴 compaction/会话树，不照搬 pi coding-agent 产品形态 |
| MCP Server 对外暴露工具 | 可选集成 | 供 Claude Desktop / Cursor 调用 Zhin；不改变 Zhin 自身「生活助手」定位 |
与 pi 的关系：对齐 LLM 内核与会话 Harness 机制，不对齐 coding-agent 终端产品。详见 pi 映射表 与 ADR 0010「不在本 ADR 范围」。
四档一览
| 档位 | 一句话 | 验证 |
|---|---|---|
| Stable（Core） | 最少配置能跑：Sandbox + 命令 + Console（IM）；AI 见 full-bot | pnpm check:stable（Core 批）· minimal-bot |
| Platform Stable | 主流 IM 适配器，框架侧 integration 有 CI | pnpm check:stable（Platform 批）· 适配器索引 |
| Advanced | 编排增强：toolSearch、MCP Mesh、多 Endpoint 同进程 | test-bot ACCEPTANCE |
| Experimental | 协议试验，自行验证 | 无全量 CI 承诺 |
Platform Stable 说明：我们保证 Adapter 与消息链路的集成测试；QQ 风控、公众号 HTTPS、NapCat 部署等 平台侧问题由你自担。
命令与 AI：同一套栈
很多用户以为必须二选一。实际上：
| 能力 | 档位 | 文档 |
|---|---|---|
MessageCommand / addCommand | Stable | 命令系统 |
/ 前缀命令（不触发 AI） | Stable | ai.trigger.ignorePrefixes |
@ / 关键词触发 Agent | Stable（需 @zhin.js/agent） | AI 模块 |
内置运维命令 /tools、/mcp | Stable（需 agent 栈 + trusted） | 命令 — 内置 IM 运维 |
toolSearch + Worker | Advanced | Agent 概念 — toolSearch |
典型混合 Bot：日常用 hello、签到 等命令；需要时用 @机器人 或 ai: 前缀走 Agent。
Platform Stable 适配器（当前）
| 适配器 | 文档 |
|---|---|
| ICQQ | icqq |
| QQ 官方 | |
| OneBot v11 | onebot11 |
| NapCat | napcat |
| KOOK | kook |
| Telegram | telegram |
| Discord | discord |
| Slack | slack |
| 钉钉 | dingtalk |
| 飞书 | lark |
| 微信公众号 | wechat-mp |
| 微信 iLink（个人微信） | weixin-ilink |
| 企业微信（WeCom） | wecom |
| LINE | line |
本地调试 IM 仍推荐 Sandbox（Stable Core）：Remote Console 沙盒页。
完整矩阵与 Experimental 列表见 平台适配器索引。
Platform Stable 共 12 个 IM 路径（含 QQ 三件套 ICQQ / NapCat / OneBot11 与个人微信 iLink）。
待补充平台
暂无。企业微信（WeCom）和 LINE 已在上方 Platform Stable 列表中。
Stable（Core）还包含什么
除 Sandbox 外，下列不需要开启 Advanced 开关（Agent / MCP 相关能力需已安装 @zhin.js/agent，脚手架启用 AI 时会写入）：
- 插件化（
usePlugin）、热重载、TypeScript - Feature：Tool / Skill / cron / 数据库（
cron-engine在check:stable） - MCP Client：filesystem 等（
mcpServers默认可为空；见 MCP 集成） - Agent：
spawn_task、exec 策略、三层文件记忆、Bootstrap（SOUL/AGENTS/TOOLS） - Remote Console 连接 Host API（见下）
Remote Console = 官方管理界面
Host（:8086）故意不提供内嵌网页 UI；console.zhin.dev 即为官方管理面板（独立仓库 zhin-console）。
这不是「少做了一个 GUI」，而是 UI 与 Endpoint 解耦：
- 一个 Console 可管理多个 Host（换 API Base 即可）；
- 改 Console 不用重启 Bot；
- 适配器可通过 Console Entry 扩展专属页（如 ICQQ 登录辅助）。
登录：API Base（如 http://127.0.0.1:8086）+ Bearer Token（.env 的 HTTP_TOKEN）。详见 Remote Console。
我该用哪条路径
| 目标 | 起点 |
|---|---|
| 5 分钟首跑（仅 IM） | 快速开始 → Console 沙盒 · minimal-bot |
| 5 分钟首跑（含 AI） | full-bot 或 npm create zhin-app 启用 AI |
| 纯命令 Endpoint | 命令系统 + 任选 Platform Stable 适配器 |
| QQ / 微信系 | qq、icqq、wechat-mp、weixin-ilink、napcat |
| Agent + MCP | Agent 概念 → test-bot |
| 硬编排 + 语义记忆 | full-bot · pnpm check:l4 |
维护者：升档检查清单
将适配器升为 Platform Stable 时：
- 确认
integration.test.ts通过； - 更新
scripts/sync-adapter-docs.mjs的ADAPTER_META； - 将测试路径加入
scripts/run-stable-smoke.mjs的platformStableTests； pnpm sync:adapter-docs+pnpm check:stable；- 更新 ACCEPTANCE.md Platform Stable 段。