Skip to content

架构决策记录(ADR)索引 ​

本目录收录 Zhin.js 的架构决策记录(Architecture Decision Records, ADR)。每份 ADR 记录一项关键架构边界、背景动机、演进取舍与代码落盘位置。

现存 ADR 列表(0034–0066) ​

服务插件与平台适配器契约 ​

ADR标题状态核心落盘模块
ADR 0034Activity Feedback 服务插件Accepted / Implementedplugins/services/activity-feedback/、@zhin.js/core
ADR 0035评论型平台适配器契约(Bilibili 先行)Accepted(Experimental 实现)plugins/adapters/bilibili/、plugins/adapters/github/
ADR 0044适配器能力画像——规范在 zhin,能力由适配器注入,功能按能力组合Implemented@zhin.js/im-contract、@zhin.js/adapter、@zhin.js/core
ADR 0064Sandbox 全能力渲染与「按平台预览」——Sandbox 是能力上界,降级只在 core 投影里发生并产出逐段报告,预览读真实适配器画像(按会话类型解析);新增 select 语义段,interactive 声明扩展为对象,流式进入画像(D1–D11 按推荐);2026-11-17 增补入站能力对齐(D12–D17:本地文件由 Sandbox 托管并签发限时地址、托管地址按签发者视为本机可信来源、引用经 reply 段提升 replyTo、平台事件经 control 帧上报)Accepted(P0、I0 已实施)@zhin.js/core(plugin-runtime/im/outbound-segments.ts、outbound-renderer.ts、built/segment-contract/、built/user-interaction.ts)、@zhin.js/adapter(capability-profile.ts)、plugins/adapters/sandbox、plugins/adapters/github、plugins/adapters/qq

受控落地、群运营与自我演进 ​

ADR标题状态核心落盘模块
ADR 0036受控落地第 0 期——决策审计、控制面与危险工具硬闸Implemented@zhin.js/agent(decision-events、scene-control、security/)、@zhin.js/console
ADR 0037受控落地第 1 期——群运营闭环Implemented@zhin.js/agent(group-ops/、欢迎/公告/日程唤醒/群管冷却)
ADR 0038连续输入合流——高热群与弹幕Implemented@zhin.js/agent(入站合流窗口)、@zhin.js/harness(Mailbox 合流策略)
ADR 0039动态群管规则——批准一次的违规阶梯Implemented@zhin.js/agent(group-ops/ 违规阶梯与硬闸审批)
ADR 0040受控自我进化——变更草稿、审批生效与重启回报Implemented@zhin.js/agent/src/self-change/、basic/cli
ADR 0061每条入站消息都有结局与原因——消灭静默失败:有限结局集合与人话模板、im_message_outcomes 一行摘要(链接决策审计与 turn trace)、why / Console 结局时间线 / zhin why、finally 提交与 check:silent-catch;IM 回合审批与 Console 共用 ToolApprovalQueueAccepted@zhin.js/core(plugin-runtime/im/)、@zhin.js/agent(plugin-runtime/ingress/、media/、assistant/timer-scheduler.ts)、@zhin.js/im-contract、@zhin.js/console-protocol、basic/cli、scripts/check-silent-catch.mjs
ADR 0065MCP 工具按聊天角色授权——接入时保留上游 annotations,ai.mcpServers[].permit(readOnly / default / tools,复用 PermissionHost 与插件工具 permissions 的 DSL,另有保留字 everyone / deny);默认上游标注只读的对所有人开放、其余只给 owner@global,标注不放宽审批;ai.agents.<name>.mcpServers 的覆盖与服务器级取 AND、只能收窄;每轮按发送者过滤并在执行前复核;zhin status / Console / trace 显示;定时任务沿用降档后的创建者主体(D1–D7 所有者 2026-11-17 批准)Accepted(未实施)@zhin.js/mcp-feature(definition.ts)、@zhin.js/agent(plugin-runtime/agent-runtime.ts expandMcpTools、capability-ingress.ts、mcp-client/、host/config.ts、assistant/job-creator.ts)、@zhin.js/runtime(host-config-schema.json)、@zhin.js/console-protocol、basic/cli(zhin status)、Console 前端(zhinjs/console)

提示词缓存与上下文 Token 预算 ​

ADR标题状态核心落盘模块
ADR 0041提示词分段组装与消息头Implemented@zhin.js/agent(Prompt Section Assembler、消息头格式)
ADR 0042压低首轮 token——固定前缀瘦身与少走回合Implemented@zhin.js/agent(固定前缀裁剪与延迟工具披露)
ADR 0043历史只存对话——按 token 预算的历史窗口与引用消息Implemented@zhin.js/ai、@zhin.js/agent(Token 预算滑窗与历史净化)
ADR 0045当前消息的运行时上下文放在正文之后——让历史前缀可缓存Implemented@zhin.js/agent(后缀注入 [Turn context],跨轮 Prefix Cache 稳定)

个人会话、AI Provider 图与多 Agent 协作 Harness ​

ADR标题状态核心落盘模块
ADR 0046Personal Session model policyPartially Superseded(Personal Session 有效;Model Catalog/Policy 被 ADR 0047 取代)@zhin.js/agent/personal-session(有效);模型目录与策略已迁至 @zhin.js/ai/provider
ADR 0047AI Provider 订阅接入与多决策模型Implemented(Accepted,S0–S4 已合入 main)@zhin.js/ai/src/provider/、@zhin.js/ai/src/providers/、@zhin.js/agent/src/decision/
ADR 0048Agent Harness——从流程到协作Implemented(Accepted,H0–H5 已全部完成)@zhin.js/harness、@zhin.js/core(venue/)、@zhin.js/agent、@zhin.js/a2a
ADR 0066插话判断合并——「旁听」用途与「旁听参与判断」决策合成一项 purposes.ambient(语言 / 决策模型可选,两类混排一条备用链,切换条件同 ADR 0047 增补;「仅评估」改为对照模型并显示一致率;门槛 minConfidence 与「只观察」mode: shadow 各只留一个,ai.trigger.ambient 只管群与节流;旧配置自动迁移、zhin doctor 提示一次、可回退)Accepted(所有者授权按推荐处理,2026-11-17;所有者已在 2026-11-17 的维护会话中批准 P0–P3 全部实施);本仓库 P0–P3 已实施,zhinjs/console 前端部分待做@zhin.js/ai(provider/)、@zhin.js/agent(plugin-runtime/ingress/ambient-engagement.ts、plugin-runtime/inference/)、zhin.js/instance(console/assistant-status.ts)、basic/cli(zhin doctor、zhin ai purposes revert)、Console 前端(zhinjs/console)

Console:访问控制、三级功能配置与运维 ​

ADR标题状态核心落盘模块
ADR 0049Console 访问控制——数据库里的用户、角色与权限Accepted@zhin.js/console-protocol、@zhin.js/host-http、@zhin.js/gateway(packages/host/gateway/src/iam/)、basic/cli(zhin console)
ADR 0050功能配置三级覆盖——全局 < 适配器 < 账号Accepted@zhin.js/runtime、@zhin.js/plugin-runtime、@zhin.js/core、packages/im/zhin/src/instance/console/(feature.* RPC)
ADR 0051Console 终端——宿主 Shell 与 SSHAccepted@zhin.js/gateway(packages/host/gateway/src/terminal/)、@zhin.js/host-http
ADR 0052Console 信息架构——状态、功能、运维、访问控制分区AcceptedConsole 前端(zhinjs/console)
ADR 0053Console 引导——create-zhin 只建项目,其余在 Console 完成Acceptedcreate-zhin、@zhin.js/gateway(packages/host/gateway/src/onboarding/)、Console 前端
ADR 0054管理网关——CLI 启动网关,网关管理 Zhin 实例Accepted@zhin.js/gateway(packages/host/gateway/src/)、zhin.js/instance(packages/im/zhin/src/instance/)、basic/cli(commands/)
ADR 0055会话级功能配置——在账号之下按群 / 私聊覆盖,存数据库,可群内自助Acceptedpackages/im/plugin-runtime、packages/im/zhin/src/instance/console/
ADR 0056聊天角色——zhin 角色分四级;发言者平台身份与机器人自身身份是独立维度,三维度过滤能力(2026-11-12 修订)Acceptedpackages/im/zhin/src/instance/(chat-roles.ts、feature-self-service.ts)、packages/im/core
ADR 0057配置与状态存放——声明放 zhin.config.yml,运行时状态放数据库,密钥放 .env(分五步实施,第 1 步:规则、x-zhin-secret、明文密钥警告与 zhin doctor --fix、.env 原子写)Accepted@zhin.js/runtime(config-secrets.ts、config-file/env-file.ts)、@zhin.js/gateway(config/literal-secrets.ts)、basic/cli(zhin doctor)、packages/im/zhin/src/instance/start-command.ts
ADR 0058登录辅助 v2——每个账号一条登录流程,挑战带引导材料,提交后能看到真实结果(P1:模型、描述符、引导块、协议与 RPC、审计、终端)Accepted@zhin.js/core(built/login-assist.ts、built/login-captcha.ts)、@zhin.js/adapter(login-capability.ts)、@zhin.js/console-protocol(login.ts)、@zhin.js/host-http(console-rpc-extended/login-rpc.ts)、packages/im/zhin/src/instance/console/login-assist-*.ts
ADR 0059网关存储隔离——Console 账号放 .zhin/gateway.db,SQLite 实例连接拒绝 ATTACH,PostgreSQL / MySQL 原始 SQL 只用受限账号Accepted@zhin.js/database(dialects/sqlite.ts、console-credential.ts)、@zhin.js/gateway(database/gateway-store.ts、iam/legacy-import.ts、database/console-role.ts、http/gateway-console.ts)、@zhin.js/core(database-host-installer.ts、database-config.ts)、basic/cli(zhin console migrate、zhin db console-role、zhin doctor)
ADR 0060聊天身份与角色的唯一事实来源——人、平台身份与角色绑定;配置名单只作种子,Console 账号与聊天身份一对一链接,第一位 owner 的引导Accepted(P0–P3 已实施)packages/im/core(built/roles.ts、built/chat-role-reader.ts)、packages/im/zhin/src/instance/(chat-roles.ts、chat-role-migration.ts、feature-self-service.ts)、@zhin.js/console-protocol、plugins/adapters/sandbox
ADR 0062每件事只留一条路——重复入口清单(25 项)与收敛建议:数据库为事实来源、文件只做种子,新用户操作只在 Console 与聊天,每页只教一条路(Q0–Q25 全部按推荐定稿)Accepted@zhin.js/cli、create-zhin-app、zhin.js/instance、@zhin.js/agent、@zhin.js/gateway、@zhin.js/console-protocol、官方插件、Console 前端(zhinjs/console)、docs/
ADR 0063Console 与插件页面 UI 统一——Console 组件抽成 @zhin.js/console-ui(放在 zhinjs/zhin),插件页必须用统一页面外壳,插件页挂成插件详情页签并进入命令面板,zk- 弃用后在 minor 中删除(P4 已删除 @zhin.js/client/ui、zk-、旧令牌别名与蓝图 mark)(D1–D10、D12–D14 按推荐,D11 所有者已定);增补 D15–D22(zhinjs/console#111 设计规则:三层令牌由 @zhin.js/console-ui 统一生成,对 Console 强制并由 stylelint、ESLint、生成的 Tailwind 主题和 Playwright 审计约束,对第三方插件页面推荐使用组件库、只设一组很小的硬性底线,zhin plugin check 只提示;本仓库的官方插件完整遵守全部规则,自 P2 起 D8 第 1–3 条、第 4–6 条和 Playwright 全项审计在 CI 中为错误)Accepted(P1–P4 已实施)@zhin.js/console-ui(新)、@zhin.js/client(声明式页面 / 适配器页 / 评论审批页渲染器)、@zhin.js/pagemanager、@zhin.js/page、@zhin.js/cli(plugin check)、Console 前端(zhinjs/console)

早期奠基 ADR 摘要(代码中引用的历史架构契约) ​

早期架构演进中确立的基石契约直接固化在核心包与系统架构 SSOT 中,关键编号如下:

  • ADR 0001 — Plugin Runtime 唯一入口与能力目录约定:确立 plugin.ts + definePlugin() 与命名能力目录(commands/、adapters/、components/、handlers/、middlewares/、tools/、skills/、agents/ 等)为唯一插件模型,移除 usePlugin() / getPlugin() / zhin.js/node(落地于 @zhin.js/plugin-runtime、@zhin.js/runtime)。
  • ADR 0008 — Canonical ConversationEventStore:确立 conversation_events 为跨会话事件的权威落盘表,支撑统一会话审计、历史重建与游标消费(落地于 packages/im/zhin/src/setup/register-chat-message-store.ts 与 basic/cli)。
  • ADR 0009 — AgentLoop 与 ContextRepository 解耦:将无 IM 概念的 agentLoop 与上下文仓储沉淀至 @zhin.js/ai,与上层 @zhin.js/agent 的 IM 编排和权限门禁解耦。
  • ADR 0010 — 会话上下文 Compaction(摘要压缩):在 @zhin.js/ai 中引入基于 Token 水位线的历史会话自动摘要与压缩机制,防止长对话撑爆上下文窗口。
  • ADR 0019 — 安装体积分层(IM 核心 ≤10MB):默认安装 zhin.js 仅包含 IM 核心(生产 node_modules ≤10MB,由 pnpm check:install-size 门禁守护);AI 能力按需加装 @zhin.js/agent + zod + ai + @ai-sdk/*。
  • ADR 0024 — 多 Agent 编排演进(已被 ADR 0048 取代):早期五角色矩阵与 Workroom Kernel 探索;其冗余状态机与 packages/im/workroom 已在 ADR 0048 中正式退役,由 @zhin.js/harness(Actor / Mail / Mailbox / Engagement / Authority / GuardKernel)与 @zhin.js/core venue/ 统一取代。