{"id":20206624,"url":"https://github.com/zhinjs/zhin","last_synced_at":"2026-08-03T05:01:26.847Z","repository":{"id":57750486,"uuid":"525594612","full_name":"zhinjs/zhin","owner":"zhinjs","description":"现代 TypeScript AI Agent 运行时 —— 多通道 Endpoint 接入、Harness 安全编排、插件热重载","archived":false,"fork":false,"pushed_at":"2026-07-29T10:38:42.000Z","size":117588,"stargazers_count":132,"open_issues_count":1,"forks_count":18,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-07-29T12:14:42.075Z","etag":null,"topics":["agent","ai","chatbot","discord","framework","hot-module-replacement","koa","plugin","qq","robot","telegram","tsx","wechat"],"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/conventions.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,"disclosure":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-07-29T10:20:12.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":2823,"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":36218648,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-03T02:00:06.975Z","response_time":56,"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":["agent","ai","chatbot","discord","framework","hot-module-replacement","koa","plugin","qq","robot","telegram","tsx","wechat"],"created_at":"2024-11-14T05:25:18.604Z","updated_at":"2026-08-03T05:01:26.838Z","avatar_url":"https://github.com/zhinjs.png","language":"TypeScript","funding_links":["https://afdian.net/a/lc-cn"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://zhin.js.org\"\u003e\n    \u003cimg src=\"docs/public/logo.svg\" alt=\"Zhin.js\" width=\"120\" height=\"120\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eZhin.js\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e一套代码，跑遍所有聊天平台的 TypeScript bot 框架\u003c/strong\u003e\u003cbr /\u003e\n  \u003cstrong\u003eOne codebase. Every chat platform. TypeScript.\u003c/strong\u003e\u003cbr /\u003e\n  多通道 · 按需 AI · Remote Console\u003cbr /\u003e\n  \u003csub\u003eMulti-channel · Opt-in AI · Remote Console\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/zhinjs/zhin/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/zhinjs/zhin/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/zhin.js\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/zhin.js.svg?color=cb3837\" alt=\"npm\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/zhin.js\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/zhin.js.svg?color=cb3837\" alt=\"npm downloads\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg src=\"https://img.shields.io/node/v/zhin.js.svg?color=339933\" alt=\"Node\" /\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/zhinjs/zhin\"\u003e\u003cimg src=\"https://codecov.io/gh/zhinjs/zhin/graph/badge.svg\" alt=\"codecov\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://zhin.js.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-zhin.js.org-0ea5e9\" alt=\"Docs\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://zhin.js.org\"\u003eDocumentation\u003c/a\u003e ·\n  \u003ca href=\"https://demo.zhin.dev\"\u003eLive Demo\u003c/a\u003e ·\n  \u003ca href=\"https://console.zhin.dev\"\u003eRemote Console\u003c/a\u003e ·\n  \u003ca href=\"./docs/contributing/development.md\"\u003eContributing\u003c/a\u003e ·\n  \u003ca href=\"./README.en.md\"\u003eEnglish\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nZhin.js 为**在聊天平台做严肃 bot / 助手产品**的开发者和团队而生（私聊、群聊、定时、通知、AI 对话），**不是** Cursor / Claude Code 类 coding agent。三个核心词：\n\n- **多通道** — 一套代码跑 20+ 平台（QQ / 微信 / Discord / Slack / 钉钉 / Telegram…），一个 bot 可同时挂多个账号、多个平台\n- **按需 AI** — 默认只是 \u003c10MB 的 IM 框架；装上 `@zhin.js/agent` 就是完整 Agent（工具 / 记忆 / 编排 / MCP），装多少用多少\n- **Remote Console** — 浏览器里管 bot：发消息、改配置、看日志、管定时任务，全程不用碰代码\n\n\u003e **EN**: Built for developers and teams running serious bot/assistant products on chat platforms. One codebase for 20+ platforms (QQ, WeChat, Discord, Slack, Telegram…) with multi-account support; starts as a \u003c10MB IM framework and grows into a full agent (tools, memory, orchestration, MCP) only when you install `@zhin.js/agent`; manage everything from a browser console. **Not** a Cursor/Claude Code-style coding agent. See [capability tiers](./docs/snippets/platform-tiers.md).\n\n```ts\n// bot.ts — 整个机器人可以就是这一份文件\nimport { defineCommand } from 'zhin.js/command'\nimport { definePlugin } from 'zhin.js/plugin-runtime'\n\nexport default definePlugin({\n  name: 'my-bot',\n  setup({ addCommand }) {\n    addCommand('hello', defineCommand({\n      description: '打招呼',\n      execute: () =\u003e 'Hello from Zhin!',\n    }))\n  },\n})\n```\n\n## Quick Start\n\n三步，不用写适配器样板：\n\n```bash\nnpm create zhin-app my-bot -y\ncd my-bot\npnpm dev\n```\n\n打开 [Remote Console](https://console.zhin.dev) → Host 填 `http://127.0.0.1:8086` → Sandbox 发 `/hello`。完事。\n\n`-y` 走 IM 黄金路径：Sandbox + Host + Console，**不需要任何模型 Key**。\n\n| 路径 | 适合谁 | 要多久 |\n|------|--------|--------|\n| [**demo.zhin.dev**](https://demo.zhin.dev) | 零安装点一点 | 立刻 |\n| `npm create zhin-app -y` | 独立项目（推荐） | ~1 分钟 |\n| [`examples/single-file-bot`](./examples/single-file-bot/) | 看「一个 `bot.ts` 就是 bot」 | 克隆后 `pnpm --filter single-file-bot dev` |\n| [`examples/minimal-bot`](./examples/minimal-bot/) | 贡献者 / 约定目录样板 | 根目录 `pnpm dev` |\n\n更多：[安装与启动](./docs/getting-started/index.md) · [示例速览](./docs/examples/index.md) · `npx zhin setup` · `npx zhin doctor`\n\n**要求**：Node.js `^20.19.0` 或 `\u003e=22.12.0`（跑 Plugin Runtime 示例推荐 **≥22.6**），pnpm 9+\n\n## Features\n\n- **IM 优先** — 命令、组件、热重载；`pnpm add zhin.js` **\u0026lt;10MB**\n- **插件化** — 文件约定 + 声明式 API（`definePlugin` / `defineCommand` / `defineAdapter`）\n- **Remote Console** — Host 只提供 API；UI 在 [console.zhin.dev](https://console.zhin.dev)\n- **可选 AI** — `@zhin.js/agent`：对话、工具、MCP、安全策略\n- **多通道** — QQ / 微信 / Discord / Telegram / Slack / GitHub 等，见 [adapters](./plugins/adapters)\n- **文件化创作面** — `commands/`、`agent/tools`、`agent/skills`（见 [agent-authoring](./docs/authoring/agent-tools.md)）\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eStable / Advanced 能力分档\u003c/strong\u003e\u003c/summary\u003e\n\n| Tier | 特性 | 说明 |\n|------|------|------|\n| **Stable** | IM 核心 | Sandbox + 命令 + Console |\n| **Stable** | AI（可选） | `@zhin.js/agent` + provider |\n| **Stable** | 插件 / 热重载 / TypeScript | Hooks API、完整类型 |\n| **Stable** | 安全（基础） | Bash allowlist、文件策略、审批 |\n| **Advanced** | 多 Endpoint | IM / 邮件 / GitHub / Webhook… |\n| **Advanced** | Feature / MCP / toolSearch | 编排、deferred worker |\n\n\u003c/details\u003e\n\n### Install tiers（zhin.js 4.x）\n\n\u003e **SSOT**：[`docs/snippets/install-tiers.md`](./docs/snippets/install-tiers.md) · 在线：[Install tiers](https://zhin.js.org/getting-started/#install-tierszhinjs-4x)\n\n| 档位 | 安装 | 约 production 体积 | 能力 |\n|------|------|-------------------|------|\n| **IM** | `pnpm add zhin.js` + 适配器（如 `@zhin.js/adapter-sandbox`）；dev：`@zhin.js/cli` | **\u003c10MB**（库包） | Plugin Runtime、命令/组件/适配器约定目录（Stable Features 由 `@zhin.js/core` 的 `zhin.features` 继承；Host 为 optional peer + `zhin.plugins`，见 [ADR 0053](/adr/0053-platform-stable-features)） |\n| **AI** | `+ @zhin.js/agent zod ai` | +~12–15MB | ZhinAgent、会话、工具、压缩 |\n| **Provider** | `+ @ai-sdk/openai` 等 | 按厂商 | 大模型调用 |\n| **MCP** | `+ @modelcontextprotocol/sdk` | +~数 MB | MCP Client / memoryMcp |\n| **Rich media** | `+ @zhin.js/html-renderer` | +~数 MB | 出站 `html` / `markdown` 转 PNG（未装则降级 text） |\n| **Speech** | `+ @zhin.js/speech` | +~数 MB | 入站 STT、出站 TTS、`segment.tts`（未装则 warn 降级） |\n\nBreaking（4.x）：`import from 'zhin.js'` 不再含 `ZhinAgent` / `AIService`；请 `import from 'zhin.js/agent'` 或 `zhin.js/ai`。详见 [ADR 0019](./docs/snippets/install-tiers.md)。\n\n\u003e **Windows**：见 [Windows 初始化指南](./docs/getting-started/index.md)。\n\n## Enable AI（optional）\n\n```bash\npnpm add @zhin.js/agent zod ai\npnpm add @ai-sdk/openai   # 按需替换\n```\n\n```yaml\n# zhin.config.yml\nai:\n  enabled: true\n  providers:\n    openai-main:\n      sdk: openai\n      apiKey: ${AI_API_KEY}\n  agents:\n    zhin:\n      provider: openai-main\n      model: gpt-4o-mini\n  agent:\n    execSecurity: allowlist\n    execApprovalMode: ask\n```\n\n深入：[AI 模块](./docs/ai/index.md) · [Agent 安全](./docs/ai/agent.md) · [工具与技能](./docs/authoring/agent-tools.md)\n\n## Adapters\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 11 / 12 | `@zhin.js/adapter-onebot11` / `onebot12` | Discord | `@zhin.js/adapter-discord` |\n| Telegram | `@zhin.js/adapter-telegram` | Slack | `@zhin.js/adapter-slack` |\n| KOOK / 钉钉 / 飞书 | `kook` / `dingtalk` / `lark` | GitHub | `@zhin.js/adapter-github` |\n| Email / 企微 / LINE | `email` / `wecom` / `line` | Satori / WeChat MP | `satori` / `wechat-mp` |\n\n完整说明：[适配器文档](./docs/adapters/index.md) · [`plugins/adapters`](./plugins/adapters)\n\n## Package Map\n\n| 包 | 角色 |\n|----|------|\n| [`zhin.js`](./packages/im/zhin) | IM 入口（4.x） |\n| [`@zhin.js/core`](./packages/im/core) | Plugin / Adapter / Dispatcher |\n| [`@zhin.js/ai`](./packages/im/ai) | 无 IM 的 AI 引擎 |\n| [`@zhin.js/agent`](./packages/im/agent) | Agent 编排与安全 |\n| [`@zhin.js/cli`](./basic/cli) · [`create-zhin-app`](./packages/toolkit/create-zhin) | CLI / 脚手架 |\n\n分层与依赖方向：[架构概览](./docs/concepts/architecture.md) · [仓库结构](./docs/contributing/repo-structure.md)\n\n## Documentation\n\n| | |\n|--|--|\n| **入门** | [快速开始](./docs/getting-started/index.md) · [路线与边界](./docs/index.md) · [稳定性承诺](./docs/concepts/generation-lifecycle.md) · [Docker](./docs/contributing/development.md) · [Windows](./docs/getting-started/index.md) |\n| **基础** | [核心概念](./docs/concepts/architecture.md) · [配置](./docs/configuration/index.md) · [命令](./docs/authoring/commands.md) · [插件](./docs/concepts/plugin-model.md) |\n| **进阶** | [AI](./docs/ai/index.md) · [Agent 创作面](./docs/authoring/agent-tools.md) · [消息流](./docs/concepts/message-flow.md) |\n| **开发** | [插件开发](./docs/authoring/define-plugin.md) · [贡献](./docs/contributing/development.md) · [架构](./docs/concepts/architecture.md) |\n\n站点：[zhin.js.org](https://zhin.js.org)\n\n## CLI\n\n```bash\npnpm dev                 # 开发（本仓默认 minimal-bot；维护者回归用 pnpm dev:test）\nnpx zhin new my-plugin   # 插件模板\nnpx zhin setup           # 增量配置向导\nnpx zhin doctor          # 环境诊断\nnpx zhin search \u003ckw\u003e     # 搜插件\n```\n\n## Contributing\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\n```\n\n见 [贡献指南](./docs/contributing/development.md)。根目录 `pnpm dev` 指向 Stable 约定目录样板 `minimal-bot`；想看「一个文件就是 bot」用 `pnpm --filter single-file-bot dev`。厨房水槽用 `pnpm dev:test`（`test-bot`），**非**用户模板。\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/zhinjs/zhin/graphs/contributors\"\u003e\n    \u003cimg src=\"https://contributors-img.web.app/image?repo=zhinjs/zhin\" alt=\"Contributors\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://repobeats.axiom.co/api/embed/26e79889b3756142f3145cd72ae19830e6b4c06a.svg\" alt=\"Repobeats\" /\u003e\n\u003c/p\u003e\n\n## License\n\n[MIT](./LICENSE)\n","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"}