Cubic Wiki 资料存档

这里保存 Cubic 为 zhinjs/zhin 生成的 Wiki：29 篇中文译文及英文原文。它们是供追溯的资料，不是当前用法指南。要解决实际问题，请先看知识索引。

英文原文抓取于 2026-09-23，对应源码提交 368db14。每篇保留源码引用和中英文切换链接；归档清单记录原文来源与校验哈希。

使用前请核对

这是一份第三方 AI 生成内容的参考快照，中文页经机器辅助翻译，尚未逐页与当前代码核验。代码示例、源码行号和运维建议可能有误或过时。实际开发请以维护中的中文文档和当前源码为准。已确认的错误会在对应文章顶部标注；导入脚本也对少量明确错误做了修正。

已确认勘误

快照主题	当前行为	维护中的文档
快速开始	新项目要求 Node.js >=22.12.0，目前配置的 HTTP 端口为 8068；8086 是未配置时的 Runtime 回退端口。	入门指南
插件 Runtime、命令	命令入口为 commands/**/index.ts；Handler 使用 handlers/<name>/index.ts。	约定目录
MCP	可选 Runtime Host 只有在顶层配置 mcp: 时才注册 Tool；ai.mcpServers 配置的是 Agent 客户端。	Runtime 源码、文档修正
安全与沙箱	execApprovalMode 为 `ask	auto
配置管理	zhin migrate 不会自动把 bots: 改成 endpoints:。	配置文档
Agent 编排、安全策略	Tool 与 Hook 使用具名目录；execSecurity 与 execApprovalMode 是独立配置。内置默认值分别是 deny 与 auto，项目配置可以覆盖。	约定目录、Agent 配置
适配器核心	快照将脚手架中的 Endpoint 示例与 createEndpointLifecycle 混为一谈；入站适配器示例不完整，且不能编译。	端点生命周期
消息段、Satori	Runtime 的 raw 与 segment.raw 不同；wrapCardHtml 需要背景色参数。	中间件与组件
安全策略、生产部署	复制 8086 示例前应核对实际 http.port；新项目使用 8068。pnpm daemon 和 pnpm stop 是旧项目迁移脚本。	生产部署

浏览中文译文

入门与架构

• Zhin.js 简介
• 快速开始与安装
• 系统架构与分层
• 插件 Runtime 与约定
• 入站与出站消息链路
• Generation 与热重载

IM、扩展与基础服务

• 命令、Handler 与中间件
• 通用消息段与组件
• 数据库抽象与持久化
• 调度引擎与 Cron
• 日志与遥测

Agent 与 AI

• Agent 编排与 ZhinAgent
• LLM Provider 与 SDK 桥接
• Agent 工具与能力
• Skill 与渐进披露
• 记忆、上下文与压缩
• 安全策略与沙箱
• 模型上下文协议（MCP）

平台与媒体

• 适配器核心与端点生命周期
• 平台接入
• Satori 富媒体
• 语音链路（STT 与 TTS）

Console、配置与运维

• 远程 Console 架构
• 开发 Console 页面
• 配置管理
• 生产部署
• 安全策略与最佳实践
• CLI 命令与工具
• 测试与 CI 门禁

更新快照

在仓库根目录运行 python3 scripts/import-cubic-wiki.py 可重新抓取英文原文，再运行 python3 scripts/import-cubic-wiki.py --verify 核对文章与清单。

更新后须审阅英文差异、勘误及对应中文译文，并将本页和英文存档页的抓取日期、源码提交改为清单中的新值。运行 pnpm check:cubic-wiki-translations；导入脚本不会覆盖中文译文。

当页面结构、预期文章 ID 或外部 HTML 变化时，脚本会停止，避免发布不完整的内容。