{"id":20206624,"url":"https://github.com/zhinjs/zhin","last_synced_at":"2026-06-14T14:02:03.478Z","repository":{"id":57750486,"uuid":"525594612","full_name":"zhinjs/zhin","owner":"zhinjs","description":"a chat bot framework for Node.js developers, compatible with qq、icqq、wechat、discord、onebot(11/12)、dingtalk and more","archived":false,"fork":false,"pushed_at":"2026-06-09T11:28:35.000Z","size":93340,"stargazers_count":129,"open_issues_count":5,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-09T12:24:17.193Z","etag":null,"topics":["bot","bot-framework","cli","oicq","qq","qq-bot"],"latest_commit_sha":null,"homepage":"http://zhin.js.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhinjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://afdian.net/a/lc-cn"]}},"created_at":"2022-08-17T01:12:28.000Z","updated_at":"2026-06-09T11:29:01.000Z","dependencies_parsed_at":"2026-04-10T09:02:23.530Z","dependency_job_id":null,"html_url":"https://github.com/zhinjs/zhin","commit_stats":{"total_commits":624,"total_committers":10,"mean_commits":62.4,"dds":"0.20512820512820518","last_synced_commit":"1d8b4483561b163e1881be51159c07183beca46a"},"previous_names":[],"tags_count":2280,"template":false,"template_full_name":"l-collect/ts-dev-template","purl":"pkg:github/zhinjs/zhin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhinjs%2Fzhin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhinjs%2Fzhin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhinjs%2Fzhin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhinjs%2Fzhin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhinjs","download_url":"https://codeload.github.com/zhinjs/zhin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhinjs%2Fzhin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34323994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","bot-framework","cli","oicq","qq","qq-bot"],"created_at":"2024-11-14T05:25:18.604Z","updated_at":"2026-06-14T14:02:03.470Z","avatar_url":"https://github.com/zhinjs.png","language":"TypeScript","funding_links":["https://afdian.net/a/lc-cn"],"categories":[],"sub_categories":[],"readme":"# Zhin.js\n\n现代 TypeScript **AI Agent 运行时** —— 多通道 **Endpoint** 接入、Harness 安全编排、插件热重载\n\n[文档](https://zhin.js.org)\n[CI](https://github.com/zhinjs/zhin/actions/workflows/ci.yml)\n[codecov](https://codecov.io/github/zhinjs/zhin)\n[License](./LICENSE)\n\n## 核心特性\n\n能力按成熟度分档：**Stable**（推荐首跑与对外默认承诺）、**Advanced**（多 Endpoint / toolSearch / MCP 等）。完整分档见下表。\n\n**核心词汇**：**Adapter** 承载平台协议；**Endpoint** 是 Adapter 下的账号/连接实例（QQ 号、Discord Bot、邮箱、Sandbox 会话等）；**ZhinAgent** 在 Endpoint 入站消息上编排大模型、工具与安全策略。IM 是 Endpoint 最常见的一类通道，不是产品边界。\n\n| Tier | 特性 | 说明 |\n|------|------|------|\n| **Stable** | AI 驱动 | ZhinAgent + 单 Provider；Sandbox 本地调试；基础多轮与工具调用 |\n| **Stable** | 插件化架构 | `usePlugin()` Hooks API，AsyncLocalStorage 上下文 |\n| **Stable** | 热重载 | 代码与配置变更自动生效 |\n| **Stable** | Remote Console | Host 仅 API（`:8086`）；UI 在 [console.zhin.dev](https://console.zhin.dev)（Sandbox 聊天） |\n| **Stable** | TypeScript | 完整类型推导 |\n| **Stable** | 安全（基础） | Bash allowlist、文件策略、交互式审批（见 [Agent 安全文档](./docs/advanced/agent-harness-engineering.md)） |\n| **Advanced** | 多通道 Endpoint | IM / 邮件 / GitHub / Webhook 等适配器见 [plugins/adapters](./plugins/adapters) 与 [适配器文档](./docs/essentials/adapters.md) |\n| **Advanced** | Feature 体系 | 命令、工具、技能、cron、数据库等组合 |\n| **Advanced** | toolSearch / MCP | 编排工具、deferred worker、MCP Client/Server |\n\n\u003e **推荐首跑**：克隆仓库后进入 [`examples/minimal-bot`](./examples/minimal-bot/)（Sandbox + 最少插件）。**零安装先试**：[**demo.zhin.dev**](https://demo.zhin.dev)（官方在线 Sandbox）。**L4 参考**：[`examples/full-bot`](./examples/full-bot/)。[`examples/test-bot`](./examples/test-bot/) 为维护者**厨房水槽**配置，勿当作默认模板。\n\n## 快速开始\n\n### 环境要求\n\n- **Node.js** 20.19.0+ 或 22.12.0+\n- **pnpm** 9.0+（`npm install -g pnpm`）\n\n### 在 monorepo 内首跑（Stable，推荐）\n\n```bash\ngit clone https://github.com/zhinjs/zhin.git\ncd zhin\npnpm install\ncd examples/minimal-bot\ncp .env.example .env   # 可选：配置 Ollama 或 OpenAI\npnpm dev\n```\n\n1. 保持 `pnpm dev` 运行（Host 监听 `http://127.0.0.1:8086`，**无**内置网页 UI）。\n2. 打开 **[Remote Console](https://console.zhin.dev)**，API Base 填终端日志中的 Host 地址（如 `http://127.0.0.1:8086`），Token 与 `.env` 中 `HTTP_TOKEN` 一致。\n3. 在 Sandbox 窗口发 `hello`；AI 回合需 Ollama 或 API Key。详见 [minimal-bot README](./examples/minimal-bot/README.md) 与 [Remote Console 说明](./docs/console-remote.md)。\n\n### 创建独立项目（脚手架）\n\n```bash\nnpm create zhin-app my-bot\ncd my-bot\npnpm dev          # 开发模式（热重载）\n```\n\n脚手架会引导你选择运行时、数据库、聊天平台和 AI 提供商。\n\n启动后在本机提供 Console **API**（默认 `http://127.0.0.1:8086`）。在 **[console.zhin.dev](https://console.zhin.dev)** 登录并填写 API Base 与 Token（见 [docs/console-remote.md](./docs/console-remote.md)）。\n\n\u003e **Windows 用户** 📌：遇到问题请参考 [Windows 初始化指南](./docs/essentials/windows-setup.md)。\n\n### 基础用法\n\n```typescript\n// src/plugins/hello.ts\nimport { usePlugin, MessageCommand } from 'zhin.js'\n\nconst { addCommand } = usePlugin()\n\naddCommand(\n  new MessageCommand('hello \u003cname:string\u003e')\n    .desc('打个招呼')\n    .action((_, result) =\u003e `Hello, ${result.params.name}!`)\n)\n```\n\n在 `zhin.config.yml` 中启用插件：\n\n```yaml\nplugins:\n  - hello\n```\n\n## 插件开发、测试与发布\n\nZhin.js 提供完整的插件开发工具链：\n\n```bash\n# 创建插件\nnpx zhin new my-plugin        # 交互式创建插件模板\n\n# 开发调试\npnpm dev                      # 热重载开发，终端直接输入消息测试\n\n# 测试\npnpm test                     # 运行 Vitest 单元测试\npnpm test:watch               # 监听模式\npnpm test:coverage            # 生成覆盖率报告\n\n# 构建与发布\nnpx zhin build                # 构建插件\nnpx zhin pub                  # 发布到 npm\n```\n\n其他用户安装你发布的插件：\n\n```bash\nnpx zhin search \u003ckeyword\u003e     # 搜索插件\nnpx zhin install \u003cname\u003e       # 安装插件\nnpx zhin info \u003cname\u003e          # 查看插件信息\n```\n\n📖 完整指南：[插件开发、测试与发布](./docs/guide/plugin-development.md)\n\n## AI 智能体\n\nZhin.js 内置 **ZhinAgent** 编排层，让各 Endpoint 上的会话具备大模型对话、工具调用与 Harness 安全能力：\n\n```yaml\n# zhin.config.yml\nai:\n  providers:\n    ollama:\n      api: ollama-chat\n      host: \"http://localhost:11434\"\n      # models 可省略 — 启动时 listModels（Ollama / OpenAI 兼容 GET /v1/models）\n  agents:\n    zhin:\n      provider: ollama\n      model: qwen3:14b         # 须出现在发现列表；中转 API 无需手写 models 白名单\n  agent:\n    execSecurity: allowlist      # bash：deny / allowlist / full\n    execPreset: network        # 预设：readonly / network / development\n    execApprovalMode: ask      # 白名单外：ask / allow / deny\n```\n\n插件通过 `addTool` 注册 AI 可调用的工具：\n\n```typescript\nconst { addTool } = usePlugin()\n\naddTool({\n  name: 'get_weather',\n  description: '查询指定城市的天气',\n  parameters: {\n    city: { type: 'string', description: '城市名称', required: true }\n  },\n  execute: async ({ city }) =\u003e `${city}：晴，25°C`\n})\n```\n\n### 文件化 AI 能力（零代码 / 轻代码）\n\n除了上述程序化注册，还可以在约定目录放置 Markdown 文件，框架**自动发现并注册**，无需编写 TypeScript。\n\n#### Tool（`*.tool.md`）\n\n```text\ntools/\n├── greeting.tool.md          # 纯模板 Tool\n└── weather/\n    ├── weather.tool.md        # 带 handler 的 Tool\n    └── handler.ts             # execute 逻辑\n```\n\n**纯模板示例**（`greeting.tool.md`）：\n\n```markdown\n---\nname: greeting\ndescription: 向用户问好\nparameters:\n  name:\n    type: string\n    description: 用户名称\n    required: true\n---\n你好，{{name}}！欢迎使用 Zhin.js 🎉\n```\n\n\u003e body 中的 `{{param}}` 会被参数值替换后直接作为返回。若需复杂逻辑，在 frontmatter 加 `handler: ./handler.ts`，指向一个默认导出函数。\n\n#### Skill（`SKILL.md`）\n\n```text\nskills/\n└── code-review/\n    └── SKILL.md\n```\n\n```markdown\n---\nname: code-review\ndescription: 代码审查助手\nkeywords: [review, lint, best-practice]\ntags: [dev]\ntools: [read_file, grep_search]\nalways: false          # true = 常驻注入；false = 按需激活\n---\n你是一个代码审查专家，请对用户提供的代码进行审查……\n```\n\n#### Agent 预设（`*.agent.md`）\n\n```text\nagents/\n└── translator.agent.md\n```\n\n```markdown\n---\nname: translator\ndescription: 多语翻译助手\nmodel: gpt-4o\nmaxIterations: 5\ntools: [web_search]\n---\n你是一名专业翻译，精通中英日三语互译……\n```\n\n#### 发现顺序\n\n框架按 **`./tools`（或 `./skills` / `./agents`）→ `~/.zhin/\u003ckind\u003e/` → `.agents/skills/`（向上至 git 根）→ 已加载插件包内对应目录 → `~/.zhin/packages/` / `.zhin/packages/`** 的顺序扫描（实现见 `packages/im/agent/src/discovery/`），同名先发现者优先；插件模块变更可通过 `Plugin.watch` **热重载**。\n\n### IM 会话与 Harness（[ADR 0010](./docs/adr/0010-pi-coding-agent-harness-alignment.md)）\n\n长对话自动 **Compaction**（L1 micro + L2 LLM）、**消息级会话树**（`/tree`）、epoch 归档（`/reset`）。`zhin.config.yml` 示例：\n\n```yaml\nai:\n  agent:\n    compaction:\n      enabled: true\n      auto: true\n      keepRecentTokens: 20000\n```\n\n| 类别 | IM 命令 |\n|------|---------|\n| 会话 | `/compact` · `/tree` · `/tree N` · `/reset` |\n| 运维 | `/models` · `/health` |\n| 内省 | `/cmd` · `/endpoints` · `/bindings` · `/tools` · `/mcp` |\n\nzhin-package 安装：\n\n```bash\nzhin packages install npm:@scope/pkg\n```\n\nConsole 可查询会话树：`GET /api/agent/sessions/:sessionKey/tree`、`POST .../leaf`。\n\n📖 详见：[AI 模块](./docs/advanced/ai.md) · [工具与技能](./docs/advanced/tools-skills.md) · [pi 映射表](./docs/advanced/pi-coding-agent-mapping.md)\n\n### 安全模型\n\nAI 执行 bash 命令时受 **6 层纵深防御** 保护：\n\n\n| 层   | 防御                                          |\n| --- | ------------------------------------------- |\n| 1   | 危险命令黑名单（`sudo`/`eval`/`dd` 等即使 full 模式也拦截）  |\n| 2   | 环境变量前缀剥离（`FOO=bar rm` → 识别为 `rm`）           |\n| 3   | Safe wrapper 剥离（`timeout 10 rm` → 识别为 `rm`） |\n| 4   | 复合命令拆分（`ls \u0026\u0026 rm -rf /` → 逐段检查）             |\n| 5   | 只读命令自动放行（`cat`/`grep`/`ls` 无需白名单）           |\n| 6   | Owner 审批信号（`execApprovalMode: ask` 时经 `ask_user` / `ZHIN_NEEDS_OWNER` 确认）  |\n\n\n## 架构设计\n\nZhin.js 采用分层架构，将 AI 编排、IM 消息生命周期与可选队列运行时分离。入口：[docs/architecture/README.md](docs/architecture/README.md)、[docs/architecture-overview.md](docs/architecture-overview.md)、[docs/contributing/repo-structure.md](docs/contributing/repo-structure.md)。**默认开发示例**：`examples/minimal-bot`；全功能回归：`examples/test-bot`。\n\n### 1. Monorepo 分层依赖拓扑\n\n本系统是基于 pnpm workspace 的单体多包结构，严格遵循从**无状态元通用层**向**智能体/应用层**单向依赖流转：\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px' }}}%%\ngraph TB\n  subgraph L5[\"🚀 zhin (主入口与聚合导出)\"]\n    L5A(\"Zhin 实例化 \u0026 引导启动\")\n  end\n\n  subgraph L4[\"🤖 @zhin.js/agent (Agent 编排与 IM 深度集成)\"]\n    L4A(\"ZhinAgent 中央编排\")\n    L4B(\"McpClientManager 跨应用客户端\")\n    L4C(\"能力动态扫描 (Discovery)\")\n    L4D(\"安全策略 (ExecPolicy \u0026 FilePolicy)\")\n  end\n\n  subgraph L3[\"核心能力双子星 (IM 层 + AI 引擎层)\"]\n    subgraph L3A[\"💬 @zhin.js/core (IM 核心模块)\"]\n      C1(\"Plugin \u0026 Adapter \u0026 Endpoint 契约\")\n      C2(\"Command \u0026 Middleware 中间件\")\n      C3(\"MessageDispatcher 分发器\")\n    end\n    subgraph L3B[\"🧠 @zhin.js/ai (通用 AI 核心引擎)\"]\n      A1(\"ModelRegistry 模型发现/降级\")\n      A2(\"AIProvider 厂商适配层\")\n      A3(\"Memory \u0026 Session 状态持久化\")\n      A4(\"Compaction 压缩器 \u0026 CostTracker\")\n    end\n  end\n\n  subgraph L2[\"⚙️ @zhin.js/kernel (运行时内核 - 无 IM 概念)\"]\n    L2A(\"PluginBase 关系树 \u0026 依赖注入 (DI)\")\n    L2B(\"Feature 运行时服务抽象\")\n    L2C(\"Cron \u0026 Scheduler 任务调度\")\n  end\n\n  subgraph L1[\"📦 基础层 basic/ (通用底层原子基建)\"]\n    L1A(\"@zhin.js/logger 结构化日志\")\n    L1B(\"@zhin.js/database 统一数据库\")\n    L1C(\"@zhin.js/schema 强类型配置\")\n    L1D(\"@zhin.js/cli 编译与手写架\")\n  end\n\n  %% 依赖流向\n  L5 --\u003e L4\n  L4 --\u003e L3A\n  L4 --\u003e L3B\n  L3A --\u003e L2\n  L3B --\u003e L2\n  L2 --\u003e L1\n\n  classDef main fill:#2e7d32,stroke:#1b5e20,color:#fff,rx:8\n  classDef agent fill:#1565c0,stroke:#0d47a1,color:#fff,rx:8\n  classDef core fill:#e65100,stroke:#bf360c,color:#fff,rx:8\n  classDef ai fill:#6a1b9a,stroke:#4a148c,color:#fff,rx:8\n  classDef kernel fill:#37474f,stroke:#263238,color:#fff,rx:8\n  classDef basic fill:#4e342e,stroke:#3e2723,color:#fff,rx:8\n\n  class L5,L5A main\n  class L4,L4A,L4B,L4C,L4D agent\n  class L3A,C1,C2,C3 core\n  class L3B,A1,A2,A3,A4 ai\n  class L2,L2A,L2B,L2C kernel\n  class L1,L1A,L1B,L1C,L1D basic\n```\n\n\n\n- **[packages/im/kernel](packages/im/kernel)** 剥离了一切 IM 交互要素，只负责插件和 Feature 开发契约，能作为独立任务框架。\n- **[packages/im/ai](packages/im/ai)** 不含 IM/Endpoint 概念，仅专注多轮 AI 交互及上下文管理，可在任意 Web 服务内单用。\n\n---\n\n### 2. IM 消息分发与中间件洋葱生命周期\n\n当外部事件到达时，[packages/im/core/src/built/dispatcher.ts](packages/im/core/src/built/dispatcher.ts) 分解为 Guardrail（护栏安全检查）、Route（规则路由）与 Handle（中间件洋葱路由与指令处理）三个阶段：\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor User as 用户 (QQ/Discord)\n    participant Adapter as 平台 Adapter\n    participant Disp as MessageDispatcher\n    participant Handle as Handle 阶段\n    participant Cmd as 命令解析器\n    participant Agent as ZhinAgent (AI)\n\n    User-\u003e\u003eAdapter: 发送原始消息 (Raw Event)\n    Adapter-\u003e\u003eAdapter: 解析格式 \u0026 构建标准 Message 实例\n    Adapter-\u003e\u003eDisp: dispatch(message)\n    Note over Disp: Stage 1 Guardrail（鉴权/过滤/日志）\n    Note over Disp: Stage 2 Route（exclusive 或 dualRoute）\n    Disp-\u003e\u003eHandle: Stage 3 Handle\n    alt 命中 Command\n        Handle-\u003e\u003eCmd: commandService.handle()\n        Cmd-\u003e\u003eCmd: 解析参数 (SegmentMatcher)\n    else 未命中 Command 且应触发 AI\n        Handle-\u003e\u003eAgent: aiHandler → ZhinAgent.process()\n        Agent-\u003e\u003eAgent: 工具收集 / 提示词 / Agent.run 循环\n    end\n    Handle-\u003e\u003eDisp: 经 replyWithPolish → $reply → sendMessage\n    Disp-\u003e\u003eUser: 统一出站（before.sendMessage → Endpoint）\n```\n\n\n\n---\n\n### 3. AI 智能体编排与文件化能力注册图\n\n[packages/im/agent/src/orchestrator](packages/im/agent/src/orchestrator) 是 AI 的交互中轴，它扫描目录，以零代/代码化的格式汇聚资产，并受运行、文件沙盒的多重审查机制保护：\n\n```mermaid\ngraph TD\n    %% 发现与注册\n    subgraph Discovery[\"系统动态文件发现（支持热重载）\"]\n        ToolMD[\"*.tool.md (Markdown工具)\"] --\u003e|Frontmatter \u0026 handler.ts| ToolReg[\"ToolRegistry (工具注册)\"]\n        SkillMD[\"SKILL.md (技能/提示词模板)\"] --\u003e|依赖检查 \u0026 摘要XML| SkillReg[\"SkillRegistry (技能注册)\"]\n        AgentMD[\"*.agent.md (Agent预设)\"] --\u003e|元数据 \u0026 系统提示| SubAgentReg[\"SubAgentRegistry (子代理)\"]\n    end\n\n    %% MCP 接入\n    subgraph MCPClient[\"跨系统标准互联\"]\n        McpServer[\"MCP Servers (Claude-compatible)\"] -.-\u003e|stdio / http-sse| McpMgr[\"McpClientManager (多客户端管理)\"]\n        McpMgr --\u003e|桥接转化为 AgentTool| ToolReg\n    end\n\n    %% AI 中枢大脑\n    subgraph Orchestrator[\"ZhinAgent 决策中枢\"]\n        ZhinAgent[\"ZhinAgent Core\"]\n        RichPrompt[\"buildRichSystemPrompt（主路径常驻段）\"] ---\u003e|system prompt| ZhinAgent\n        PromptBuilder[\"PromptBuilder（可选分层 API）\"] -.-\u003e|buildRichSystemPromptWithBuilder| ZhinAgent\n        ModelRegistry[\"ModelRegistry (模型自动发现 \u0026 自动降级)\"] ---\u003e|智能分配最合适 LLM| ZhinAgent\n        AIProvider[\"AIProvider (接入 Ollama / OpenAI / DeepSeek 等)\"] -.-\u003e|单/多轮 API 轮询| ZhinAgent\n    end\n\n    %% 安全策略层\n    subgraph Security[\"双重安全屏障\"]\n        ExecPolicy[\"ExecPolicy (6层Bash安全纵深防御)\"]\n        FilePolicy[\"FilePolicy (路径校验 \u0026 敏感设备/文件拦截)\"]\n    end\n\n    %% 关联关系\n    ToolReg --\u003e|获取执行清单| ZhinAgent\n    SkillReg --\u003e|匹配历史上下文激活| ZhinAgent\n    SubAgentReg --\u003e|嵌套派生 Subagent| ZhinAgent\n    ZhinAgent --\u003e|1. 检查 Sandbox 命令| ExecPolicy\n    ZhinAgent --\u003e|2. 检查读写操作| FilePolicy\n    ExecPolicy --\u003e|拦截/合规执行| ToolReg\n    FilePolicy --\u003e|合规访问| ToolReg\n\n    classDef disc fill:#fff3e0,stroke:#ffb74d,color:#5d4037\n    classDef mcp fill:#f3e5f5,stroke:#ba68c8,color:#4a148c\n    classDef orch fill:#e3f2fd,stroke:#64b5f6,color:#0d47a1\n    classDef sec fill:#ffebee,stroke:#e57373,color:#b71c1c\n\n    class ToolMD,SkillMD,AgentMD,ToolReg,SkillReg,SubAgentReg disc\n    class McpServer,McpMgr mcp\n    class ZhinAgent,RichPrompt,PromptBuilder,ModelRegistry,AIProvider orch\n    class ExecPolicy,FilePolicy sec\n```\n\n\n\n---\n\n### 4. AI 思考状态连携与统一出站链路\n\n[packages/im/agent/src/init/register-typing-indicator.ts](packages/im/agent/src/init/register-typing-indicator.ts) 自动转换 AI 复杂的思考流、子任务分发状态并渲染给指示器。最终的渲染通过统一保护链路：\n\n```mermaid\ngraph TD\n    %% AI 生命周期事件广播\n    subgraph EventStream[\"1. AI 生命周期事件流\"]\n        direction LR\n        Evt_Start[\"ai.processing.start\"] ~~~ Evt_Think[\"ai.thinking.update\"] ~~~ Evt_SubStart[\"ai.subagent.start\"] ~~~ Evt_SubFinish[\"ai.subagent.finish\"] ~~~ Evt_Finish[\"ai.processing.finish\"]\n    end\n\n    %% 状态自动连携\n    subgraph StateBinding[\"2. AI 思考状态连携机制\"]\n        RegIndicator[\"register-typing-indicator (启动绑定)\"]\n        TIM[\"TypingIndicatorManager (适配器管理)\"]\n        ActiveInd[\"Active Typing Indicator (思考指示器)\"]\n\n        RegIndicator --\u003e|监听全部 ai.* 事件| TIM\n        TIM --\u003e|启动 / 流式 editMessage / 终止| ActiveInd\n    end\n\n    %% 统一安全出站链路 (IM Send Path)\n    subgraph OutboundPipeline[\"3. 统一安全出站保护链路\"]\n        ActiveInd --\u003e|流式思考内容 / 状态占位符| SendAPI[\"Adapter.sendMessage / Message.$reply\"]\n        ZhinAgentAns[\"ZhinAgent 最终回复内容\"] --\u003e|输出内容| SendAPI\n\n        SendAPI --\u003e|1. 经过模板渲染与组件自解析| Render[\"renderSendMessage (JSX 动态解析)\"]\n        Render --\u003e|2. before.sendMessage 终层防线拦截| BeforeHook[\"Root Plugin 挂载的拦截钩子\"]\n        BeforeHook --\u003e|3. 送达底层平台容器发送| EndpointSend[\"Endpoint.$sendMessage\"]\n        EndpointSend --\u003e|4. 分发到客户端| Client[\"QQ / Discord / Slack 等通道\"]\n    end\n\n    %% 事件流到绑定的连动\n    Evt_Start --\u003e|1. 触发| RegIndicator\n    Evt_Think --\u003e|2. 触发| RegIndicator\n    Evt_SubStart --\u003e|3. 触发| RegIndicator\n    Evt_SubFinish --\u003e|4. 触发| RegIndicator\n    Evt_Finish --\u003e|5. 触发| RegIndicator\n\n    classDef stream fill:#eceff1,stroke:#90a4ae,color:#263238\n    classDef binding fill:#e8f5e9,stroke:#81c784,color:#1b5e20\n    classDef pipeline fill:#fff8e1,stroke:#ffb74d,color:#5d4037\n\n    class Evt_Start,Evt_Think,Evt_SubStart,Evt_SubFinish,Evt_Finish stream\n    class RegIndicator,TIM,ActiveInd binding\n    class SendAPI,ZhinAgentAns,Render,BeforeHook,EndpointSend,Client pipeline\n```\n\n\n\n- **不允许直发绕过**：指示器和最终答案均触发统一的 [packages/im/core/src/adapter.ts](packages/im/core/src/adapter.ts) 中的发送生命周期，拒绝 `Endpoint.$sendMessage` 被业务层直接旁路调用。\n\n## 多平台适配器\n\n仓库内 [`plugins/adapters/`](./plugins/adapters/) 共 **19** 个适配器包（成熟度因平台而异，对外默认承诺以 Sandbox 为主）：\n\n| 平台 | 包名 | 平台 | 包名 |\n|------|------|------|------|\n| Sandbox（Stable 首跑） | `@zhin.js/adapter-sandbox` | QQ (ICQQ) | `@zhin.js/adapter-icqq` |\n| QQ 官方 | `@zhin.js/adapter-qq` | NapCat | `@zhin.js/adapter-napcat` |\n| OneBot v11 | `@zhin.js/adapter-onebot11` | OneBot v12 | `@zhin.js/adapter-onebot12` |\n| Milky | `@zhin.js/adapter-milky` | KOOK | `@zhin.js/adapter-kook` |\n| Discord | `@zhin.js/adapter-discord` | Telegram | `@zhin.js/adapter-telegram` |\n| Slack | `@zhin.js/adapter-slack` | 钉钉 | `@zhin.js/adapter-dingtalk` |\n| 飞书 | `@zhin.js/adapter-lark` | 微信公众号 | `@zhin.js/adapter-wechat-mp` |\n| Email | `@zhin.js/adapter-email` | GitHub | `@zhin.js/adapter-github` |\n| 企业微信（WeCom） | `@zhin.js/adapter-wecom` | LINE | `@zhin.js/adapter-line` |\n| Satori | `@zhin.js/adapter-satori` | | |\n\n\n## 常用命令\n\n```bash\n# 运行\npnpm dev                      # 开发模式（热重载）\npnpm start                    # 生产模式\npnpm start -- -d              # 后台守护进程\nnpx zhin stop                 # 停止后台进程\n\n# 插件管理\nnpx zhin new \u003cname\u003e           # 创建插件模板\nnpx zhin build                # 构建插件\nnpx zhin pub                  # 发布插件到 npm\nnpx zhin search \u003ckeyword\u003e     # 搜索 npm 上的 Zhin 插件\nnpx zhin install \u003cname\u003e       # 安装插件\n\n# zhin-package（ADR 0010）\nnpx zhin packages list        # 已安装的 zhin-package\nnpx zhin packages install npm:@scope/pkg\n\n# 诊断\nnpx zhin doctor               # 检查环境和配置\nnpx zhin setup                # 交互式配置向导\n```\n\n## 文档导航\n\n\n| 分类     | 链接                                                                                                                                                                |\n| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **入门** | [快速开始](./docs/getting-started/index.md) · [Docker 部署](./docs/getting-started/docker.md) · [Windows 环境](./docs/essentials/windows-setup.md)                        |\n| **基础** | [核心概念](./docs/essentials/index.md) · [配置文件](./docs/essentials/configuration.md) · [命令系统](./docs/essentials/commands.md) · [插件系统](./docs/essentials/plugins.md)    |\n| **进阶** | [AI 模块](./docs/advanced/ai.md) · [ADR 0010 Harness](./docs/adr/0010-pi-coding-agent-harness-alignment.md) · [Feature 系统](./docs/advanced/features.md) · [工具与技能](./docs/advanced/tools-skills.md) · [消息流转](./docs/essentials/message-flow.md) |\n| **开发** | [插件开发指南](./docs/guide/plugin-development.md) · [贡献指南](./docs/contributing.md) · [架构概览](./docs/architecture-overview.md) · API 参考（`pnpm docs:api` 本地生成）|\n\n\n## 项目结构\n\n本仓库采用 **pnpm workspace** 单仓多包管理（**无 git submodule**）：\n\n```\nzhin/                          # 主仓库 (github.com/zhinjs/zhin)\n├── basic/                     # 基础层（独立 npm 包目录）\n│   ├── cli/                   #   CLI 工具       (@zhin.js/cli)\n│   ├── database/              #   数据库抽象\n│   ├── logger/                #   日志系统\n│   └── schema/                #   Schema 校验\n├── packages/                  # 核心层\n│   ├── kernel/                #   运行时内核\n│   ├── ai/                    #   AI 引擎\n│   ├── core/                  #   IM 框架\n│   ├── agent/                 #   Agent 编排\n│   ├── client/                #   Web 控制台\n│   ├── satori/                #   渲染引擎\n│   ├── create-zhin/           #   项目脚手架（create zhin-app）\n│   ├── scaffold-wizard/       #   共享配置向导（create + zhin setup）\n│   └── zhin/                  #   主入口包\n├── plugins/                   # 插件生态（适配器 / 服务 / 特性 / 工具）\n├── docs/                      # VitePress 文档站\n└── examples/                  # 示例项目\n```\n\n📖 详见：[仓库结构与模块化约定](./docs/contributing/repo-structure.md) · [单仓库迁移说明](./docs/contributing/monorepo-no-submodules.md)\n\n## 贡献者\n\n[![贡献者](https://contributors-img.web.app/image?repo=zhinjs/zhin)](https://github.com/zhinjs/zhin/graphs/contributors)\n![Alt](https://repobeats.axiom.co/api/embed/26e79889b3756142f3145cd72ae19830e6b4c06a.svg \"Repobeats analytics image\")\n\n\n\n## 参与贡献\n```bash\ngit clone https://github.com/zhinjs/zhin.git\ncd zhin\npnpm install \u0026\u0026 pnpm build\ncd examples/minimal-bot \u0026\u0026 pnpm dev   # Stable 黄金路径（根目录 pnpm dev 启动的是 test-bot）\n```\n\n📖 详见：[贡献指南](./docs/contributing.md)\n\n## 许可证\n\nMIT License","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhinjs%2Fzhin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhinjs%2Fzhin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhinjs%2Fzhin/lists"}