从零理解 zhin
一句话：zhin 是让 AI 能在 IM 群里长期生活的运行时——说话像人，做事守规矩，花钱有数，到哪个平台都能用。
这一页把分散在各个 ADR 里的设计串成一张图。想动手写插件，先看插件模型；想知道消息怎么流动，看消息流。这里讲的是「为什么是这样」。
一张图
┌────────────────────── 平台（QQ / OneBot / Discord / …）──────────────────────┐
│ │
适配器 ── 声明能力画像（能做什么，随会话场景变化）── 实现端口（怎么去做）── 映射标准事件
│ │
▼ │
zhin 运行时 ─ 规范：能力目录 · 段组装器 · 消息 / 事件契约 · 审计 · 硬闸 · 控制面 │
│ │
▼ │
插件 / Agent ─ 按「这一回合组合出来的能力」决定：说什么、调哪些工具、能做哪些动作 ─────┘分工的原则：zhin 提供规范；适配器按规范注入能力；插件根据组合出来的能力完成实际功能。 核心代码里不写「如果是某平台就……」，差异全部来自适配器的声明（ADR 0044）。
四个目标，各由哪些设计支撑
1. 像人——它在群里怎么待
| 设计 | 作用 | 出处 |
|---|---|---|
| 旁听与自主插话 | 没人 @ 也会读群，自己判断该不该开口；@ 它也可以选择不回 | ambient engagement |
| 消息头只在需要时带全 | 每个人第一次出现、资料变化时才带名字 / 角色 / 头衔，之后只有短头 | 0041 |
| 状态变更进历史 | 进群、退群、改名片、升管理员作为对话的一部分，可回看 | 0041 |
| 引用消息直接看懂 | 被引用的消息在上下文里就 reply_to，不在就内联摘要，不必再调工具 | 0043 |
| 连续输入合流 | 多人同时 @ 合成一次回复、分别 @；弹幕挑一条回 | 0038 |
| 克制的表情与反应 | 表情包、表情回应带冷却与随机，不是每句都配 | 表情回应限频 |
| 人设与规则分离 | SOUL.md 只写性格和语气；通用规则在系统提示词里，不重复 | bootstrap 作用域（0042） |
2. 受控——出了事能捏住
| 设计 | 作用 | 出处 |
|---|---|---|
| 决策审计 | 每次醒来、拦下、放行、调工具、出站都留痕，可按回合回放 | 0036 |
| 控制面 | 急停、静音、只读、仅 @，实例与会话两级，改动带 revision | 0036 |
| 危险动作硬闸 | 踢人、禁言、发公告、改宿主配置等，必须有人新鲜批准；bypass 与「记住授权」都不算 | 0036、#1030 |
| 群运营闭环 | 欢迎、公告审批、冷场降噪、日程提醒、群管冷却 | 0037 |
| 批准一次的规则 | 群主批准一条违规阶梯后，禁言自动执行；踢人仍每次审批 | 0039 |
| 受控自我修改 | Agent 起草变更 → 试跑 → 人批 → 生效 / 重启 → 原会话回报，失败回滚一次后急停 | 0040 |
原则：模型可以提议，放宽限制和危险动作必须有人拍板，事后能查是谁批的。
3. 省钱——长期待着也养得起
| 设计 | 作用 | 出处 |
|---|---|---|
| 段组装器 | 系统提示词按「系统 → 环境 → 角色规则 → 平台 → 场景」组装，前四段跨会话逐字节稳定 | 0041 |
| 稳定前缀与缓存断点 | 场景放末尾，新会话第一句也能命中缓存 | 0042 |
| 工具分档与按名调用 | 群聊只常驻聊天必需工具；按名字调用即自动加载；工具列表会话内只追加 | 0042 |
| 历史只存对话 | 每轮的上下文（时间、规则、工具索引……）不进历史；窗口按 token 预算 | 0043 |
| 旧工具结果裁剪 | 结束回合的工具结果只留前 200 字 | 0043 |
| 少走回合 | 场景迭代上限、原地打转检测、并行调用 | 0042 |
| 真实账本 | zhin usage report 与 Console「Token 用量」页，按模型 / 会话 / 时间看花费与缓存命中 | 0043、Console |
目标：成本随群数和消息量线性增长，而不是随历史膨胀。
4. 平台无关——能力组合，而不是写死
| 设计 | 作用 | 出处 |
|---|---|---|
| 能力画像 | 适配器声明七组能力（消息、会话场景、动作、事件、交互反馈、投递约束、prompt 贡献），按会话类型区分 | 0044 |
| 动态收窄 | 按 Bot 角色、禁言、被动回复窗口等当前事实只收窄、不放宽 | 0044 |
| 平台说明自动生成 | prompt 里的平台说明由能力生成，适配器可补充自定义文本 | 0044 |
| 共享事件映射 | OneBot / NapCat / icqq 共用一套原始事件 → 标准事件映射 | 0044 |
| 工具按能力出现 | 工具声明 requiresCapabilities；Bot 不是管理员，禁言工具就不出现 | 0044 |
一条消息经历了什么
- 入站：适配器把平台消息变成标准消息；可信入口补上发送者角色、会话场景事实（群名、群主、管理员、Bot 角色，走两级缓存）。
- 能力：按会话类型合并能力画像，再按当前事实收窄，得到本回合能力。
- 准入：合流窗口、控制面（急停 / 静音 / 仅 @）、会话门禁决定这条消息是否、何时进模型。
- 组装：系统提示词按段拼好（稳定前缀 + 场景）；历史按 token 预算截取，只含对话；当前消息附上本轮上下文。
- 推理与工具：模型只看得到本回合能力允许、权限允许的工具；危险工具过硬闸审批。
- 出站：结构化回复按平台能力渲染、降级、投递；表情回应限频；全程写审计。
目录：ADR 一览
| ADR | 主题 |
|---|---|
| 0034 | 执行状态反馈服务 |
| 0035 | 评论回复适配器契约 |
| 0036 | 受控落地第 0 期：审计、控制面、硬闸 |
| 0037 | 第 1 期：群运营闭环 |
| 0038 | 连续输入合流（高热群、弹幕） |
| 0039 | 动态群管规则 |
| 0040 | 受控自我进化 |
| 0041 | 提示词分段组装与消息头 |
| 0042 | 压低首轮 token |
| 0043 | 历史只存对话、token 预算窗口、引用消息 |
| 0044 | 适配器能力画像 |
| 0045 | 当前消息运行时上下文放在正文之后（提示词缓存） |
| 0046 | 个人 Session、模型目录与作用域策略 |
0036–0040 的整体规划见受控落地路线图。