KAIROS — Claude Code "Assistant Mode" 完整解析

基于 Claude Code 源码逆向分析（2026-04-03）数据来源：restored-src (sourcemap 还原) + claude-code-source (反编译)

一、KAIROS 是什么

KAIROS 是 Claude Code 内部正在开发的 Assistant Mode（助手模式） 的工程代号。

一句话定义：把 Claude Code 从"你问我答的 CLI 工具"变成"始终在线、自主行动的 AI 助手守护进程"。

1.1 普通模式 vs KAIROS 模式

普通 Claude Code（被动工具）：

  用户输入 → Agent 执行 → 返回结果 → 等待 → 用户输入 → ...

  ● 用户不说话，Agent 什么都不做
  ● 关掉终端，Agent 就消失了
  ● 每次对话是独立的，不记得上次做了什么


KAIROS（主动助手守护进程）：

  Agent 24 小时运行 ──┬── 自己巡逻思考（tick 心跳）
                      ├── 按计划执行任务（cron 定时）
                      ├── 监听外部事件（GitHub / MCP / Webhook）
                      ├── 主动推送简报给用户
                      ├── 记住做过的事（日志 + Dream 巩固记忆）
                      └── 用户随时从任意终端连入查看

  ● 用户不在，Agent 照样工作
  ● 关掉终端，Agent 继续运行（daemon 模式）
  ● 跨 session 有记忆，越用越了解你的项目

1.2 能力全景图

KAIROS 的完整能力可以分为五层：

┌─────────────────────────────────────────────────────────┐
│                    KAIROS 能力架构                        │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─ 感知层 ─────────────────────────────────────────┐   │
│  │  定时任务（cron）         — 预设好的计划           │   │
│  │  外部事件（GitHub/MCP）   — 被动触发              │   │
│  │  自主巡逻（tick 心跳）    — 没人叫也会自己醒来     │   │
│  └──────────────────────────────────────────────────┘   │
│          ↓                                               │
│  ┌─ 决策层 ─────────────────────────────────────────┐   │
│  │  自主判断下一步行动（做事 or Sleep）               │   │
│  │  可以 spawn 子 agent 并行协作                     │   │
│  │  调用所有 Claude Code 原有工具                    │   │
│  └──────────────────────────────────────────────────┘   │
│          ↓                                               │
│  ┌─ 输出层 ─────────────────────────────────────────┐   │
│  │  SendUserMessage — 推送文字简报                   │   │
│  │  SendUserFile    — 推送文件                       │   │
│  │  PushNotification — 推送到手机/设备               │   │
│  └──────────────────────────────────────────────────┘   │
│          ↓                                               │
│  ┌─ 记忆层 ─────────────────────────────────────────┐   │
│  │  Daily Log — 每天的工作日志                       │   │
│  │  Dream     — 空闲时巩固成长期记忆                 │   │
│  │  MEMORY.md — 跨 session 的知识库                  │   │
│  └──────────────────────────────────────────────────┘   │
│          ↓                                               │
│  ┌─ 查看层 ─────────────────────────────────────────┐   │
│  │  Remote Viewer — 任意终端实时连入查看和交互        │   │
│  │  Brief 模式   — chat 视图只看简报 / transcript    │   │
│  │                  视图看完整过程                    │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
└─────────────────────────────────────────────────────────┘

1.3 一个具体场景

假设你是一个团队 lead，KAIROS 模式下的 Claude Code 可以这样工作：

早上 9:00 — cron 定时任务触发，Agent 自动检查过夜的 GitHub PR，生成 review 摘要，通过 SendUserMessage 推送给你： "昨晚有 3 个 PR 需要关注：#142 改了数据库 schema（风险高），#143 是文档更新（可直接合），#145 有 CI 失败。"

上午 10:30 — 你在写代码，Agent 在后台收到 GitHub webhook：#142 的作者 push 了新 commit。Agent 自动 re-review，发现之前标记的问题已修复，推送通知："#142 已修复之前的 schema 问题，建议合入。"

下午 2:00 — 没有外部事件。Agent 在 tick 巡逻中发现项目的 TODO 列表里有一个标记为"low priority"的 lint 配置优化。它自主决定执行，完成后推送简报。

晚上 11:00 — 你已经下班。Agent 触发 dream，把今天的工作日志总结成几条关键记忆，写入 MEMORY.md。明天的 session 会自动加载这些记忆。

第二天早上 — 你从家里的笔记本用 claude assistant 连入，看到 Agent 昨晚和今早的所有工作记录。

1.4 工程规模

这不是一个 prototype。KAIROS 是一个渗透到 Claude Code 75 个文件、175 处代码引用的系统级特性，配备了：

6 个编译时 feature flag + 7 个运行时远程开关
运维级别的远程热配置（5 分钟全量生效的 kill-switch）
三重安全门控（编译 + 远程 + 本地信任）
完整的 Datadog analytics 标记体系

二、当前状态

2.1 代码存在形式

KAIROS 的代码通过 feature('KAIROS') 编译时开关控制。在公开发布的 Claude Code 构建中，这个开关是 false，导致：

所有 feature('KAIROS') ? require('./assistant/index.js') : null 被求值为 null
对应的模块文件从 bundle 中被 tree-shake 删除
sourcemap 无法还原这些模块

结果：我们能看到所有的"调用点"（知道 KAIROS 会做什么），但看不到"实现"（不知道它怎么做）。

2.2 可见 vs 不可见

类别	状态	说明
调用点（175 处）	可见	散布在 75 个文件中的 `feature('KAIROS')` 分支
类型签名	可见	`kairosActive: boolean`、`kairosEnabled: boolean` 等
GrowthBook 配置名	可见	`tengu_kairos`、`tengu_kairos_cron` 等
CLI flag	可见	`--assistant`、`--brief`、`--channels`
`src/assistant/index.js`	不可见	主入口，被 tree-shake
`src/assistant/gate.js`	不可见	门控逻辑，被 tree-shake
`src/proactive/`	不可见	整个 proactive 模块，被 tree-shake
专属工具实现	不可见	SendUserFile、PushNotification、SubscribePR、Monitor

2.3 发布状态

KAIROS 处于 内部灰度阶段，证据：

--assistant flag 被 .hideHelp() 隐藏，不出现在帮助文档中
激活需要三重门控：编译开关 + GrowthBook 远程 gate + 目录 trust dialog
代码注释中有 TODO(public-ship) 标记，说明有明确的公开发布待办清单
运维级别的远程 kill-switch（5 分钟内全量生效），说明已在小范围内部使用

三、Feature Flag 体系

KAIROS 不是单一开关，而是一个 flag 家族，可以独立控制各子功能的发布：

3.1 编译时 Flag（dead code elimination）

Flag	控制范围
`KAIROS`	主开关：assistant mode 全部功能
`KAIROS_BRIEF`	Brief 通信（SendUserMessage 工具）
`KAIROS_CHANNELS`	MCP Channel 消息推送
`KAIROS_DREAM`	Disk-skill dream（记忆巩固）
`KAIROS_GITHUB_WEBHOOKS`	GitHub PR 订阅 webhook
`KAIROS_PUSH_NOTIFICATION`	推送通知工具
`PROACTIVE`	Proactive 自主行动模式（可独立于 KAIROS）
`AGENT_TRIGGERS`	Cron 定时任务（可独立于 KAIROS）

3.2 运行时 Gate（GrowthBook 远程控制）

Gate 名称	用途	刷新间隔
`tengu_kairos`	主 entitlement 门控	启动时检查
`tengu_kairos_cron`	Cron 调度器开关	5 分钟
`tengu_kairos_cron_durable`	持久化 cron 开关	5 分钟
`tengu_kairos_cron_config`	Cron jitter 调参 (JSON)	1 分钟
`tengu_kairos_brief`	Brief 工具开关	5 分钟
`tengu_kairos_brief_config`	Brief UI 配置 (JSON)	缓存
`tengu_harbor`	Channel 通知网关	运行时

3.3 设计意图

这种分层控制的好处：

独立发布：KAIROS_BRIEF 可以单独开放给非 KAIROS 用户（事实上已经在做）
灰度控制：通过 GrowthBook 按用户/组织/比例灰度
Incident 响应：运维可以在 5 分钟内远程关闭任何子功能
成本控制：Cron config 可以远程调整 jitter 参数，应对推理请求高峰

四、六大核心子系统

4.1 Proactive Mode — 自主行动循环

本质： 一个 tick 驱动的自主决策循环。

┌──────────────────────────────────────────────┐
│              Proactive Loop                   │
│                                               │
│  系统发送 <tick> ──→ Agent 收到心跳            │
│       ↑                    ↓                  │
│       │              有事做？──→ 执行工具调用   │
│       │                    ↓                  │
│       │              没事做？──→ 调用 SleepTool │
│       │                    ↓                  │
│       └──── 等待下一个 tick ←──┘              │
│                                               │
│  用户按 ESC → pauseProactive()               │
│  用户发消息 → 恢复 proactive                  │
│  Context 耗尽 → setContextBlocked(true)       │
└──────────────────────────────────────────────┘

关键设计：

<tick> 标签携带用户本地时间，Agent 用它判断时间（外部工具时间戳可能是不同时区）
Context 耗尽时自动阻止 tick 循环，避免 "tick → 报错 → tick → 报错" 的死循环
Coordinator mode（多 agent 编排）下禁用 proactive，避免和 delegation 指令冲突

System Prompt 注入：

# Proactive Mode

You are in proactive mode. Take initiative — explore, act, and make
progress without waiting for instructions.

You will receive periodic <tick> prompts. These are check-ins. Do
whatever seems most useful, or call Sleep if there's nothing to do.

激活方式：

--proactive CLI flag
CLAUDE_CODE_PROACTIVE=true 环境变量
KAIROS assistant mode 自动包含

4.2 Brief / SendUserMessage — Agent 向用户通信

本质： Agent 主动给用户发简报消息，而不是让用户翻看完整的工具调用日志。

双视图模式：

┌─ transcript 视图（默认）──────────────────────┐
│  [tool_use] Read file /src/main.ts            │
│  [tool_result] ... 200 lines ...              │
│  [tool_use] Edit file /src/main.ts            │
│  [tool_result] OK                             │
│  [assistant] 我已经修复了这个 bug...           │
│  [tool_use] SendUserMessage "修复完成..."      │
└───────────────────────────────────────────────┘

┌─ chat 视图（Brief 模式）─────────────────────┐
│                                               │
│  🤖 修复完成，main.ts 第 42 行的空指针已处理。 │
│                                               │
│  （所有工具调用细节被隐藏）                     │
└───────────────────────────────────────────────┘

关键设计：

defaultView setting 持久化用户偏好（'chat' 或 'transcript'）
dropTextInBriefTurns() — 当 turn 中有 SendUserMessage 时，自动隐藏冗余的 assistant text
Ctrl+Shift+B 快捷键切换视图
非交互模式（--print）下自动禁用 Brief，避免污染 stdout

工具家族：

工具	功能
`SendUserMessage`	发送文字简报
`SendUserFile`	发送文件附件（带验证 + 上传）
`PushNotificationTool`	推送到用户设备

4.3 Cron 定时任务 — 计划执行

本质： Agent 可以创建、管理、执行定时任务。

架构特点（独立于 KAIROS）：

AGENT_TRIGGERS flag 独立发布，不依赖 KAIROS 主开关
三个工具：CronCreate / CronDelete / CronList
存储：.claude/scheduled_tasks.json

Jitter 防雷设计（精细到可远程调参）：

人类设定时任务喜欢取整（每小时的 :00 或 :30），如果全球用户的 cron 都在 :00 触发，会造成推理请求洪峰。KAIROS 的解决方案：

原始触发时间: 14:00:00
   ↓
oneShotMinuteMod: 30 → 只对 :00 和 :30 做 jitter
oneShotMaxMs: 90000  → 最多提前 90 秒
oneShotFloorMs: 0    → 最少提前 0 秒
   ↓
实际触发时间: 13:58:47（随机提前 73 秒）

运维可以在 incident 时热推送配置，1 分钟内全量生效。

执行模式：

定时触发的任务作为后台 subagent 运行
有独立的 abortController，ESC 杀不掉
结果以 isMeta 标记的消息注入主循环
被杀掉的任务在下次调度时自动重新触发

4.4 Channel 消息推送 — 外部事件驱动

本质： MCP Server 可以向 Agent 推送消息（inbound push），Agent 收到后自主决定如何响应。

外部事件
  │
  ▼
MCP Server 发送 notifications/claude/channel
  │
  ▼
消息包裹在 <channel> 标签中入队
  │
  ▼
SleepTool 轮询 hasCommandsInQueue()
  → 1 秒内检测到并唤醒 Agent
  │
  ▼
Agent 自主决定：
  → 调用 Channel 的 MCP 工具处理？
  → SendUserMessage 通知用户？
  → 两者都做？

权限控制（企业级）：

组织策略：policy?.channelsEnabled（admin 控制开关）
白名单：allowedChannelPlugins（admin 控制哪些插件能推消息）
用户级：--channels <servers...> 指定当前 session 接收哪些 channel
开发模式：--dangerously-load-development-channels（绕过白名单，显示确认对话框）
认证要求：必须 claude.ai OAuth（API Key 用户暂不支持）

4.5 记忆与 Dream — 长期记忆巩固

本质： 把 Agent 的每日工作记忆持久化，并定期巩固成长期知识。

日常运行                    夜间/空闲
────────                    ────────
每次有意义的操作             /dream skill 触发
  ↓                           ↓
追加到 daily log             读取近期日志
logs/YYYY/MM/DD.md            ↓
                            LLM 总结提炼
                              ↓
                            写入 MEMORY.md
                            （长期记忆）

与 AutoDream 的关系：

AutoDream 是普通模式的记忆巩固（多 session 后自动触发）
KAIROS 模式下 AutoDream 被禁用（isGateOpen() 返回 false）
改用 disk-skill dream — 更结构化的"日志 → 巩固"模式
原因：assistant 是长期运行的，需要更可控的记忆策略

4.6 Remote Viewer — 远程查看

本质： 用户可以从另一个终端连接到正在运行的 assistant session，实时查看进度并发送消息。

┌────────────────┐         ┌────────────────┐
│  Agent Daemon   │◄──WS──►│  Viewer Client  │
│  (远端运行)      │         │  (本地连接)      │
│                 │         │                 │
│  agentic loop   │  推送   │  只读流式显示    │
│  工具调用        │ ──────► │  AgentEvent     │
│  决策            │         │                 │
│                 │  POST   │  用户可以        │
│                 │ ◄────── │  发送消息        │
└────────────────┘         └────────────────┘

CLI 入口：

claude assistant              # 发现可用 session
claude assistant <sessionId>  # 连接到指定 session

关键行为：

Viewer 模式下 Ctrl+C/ESC 不会中断远程 Agent
历史消息通过 API 分页懒加载（每页 100 条，滚动上翻时触发）
WebSocket 断线 60 秒内自动重连
后台任务计数从 WebSocket 事件中推算（本地不维护 tasks 状态）

认证：

OAuth headers + anthropic-beta: ccr-byoc-2025-07-29
API endpoint: {BASE_URL}/v1/sessions/{sessionId}/events

五、激活流程

用户在 .claude/settings.json 设置 { assistant: true }
  │
  ▼
启动 Claude Code
  │
  ├─ 编译时检查：feature('KAIROS') == true?
  │    └─ false → KAIROS 代码已被 tree-shake，流程结束
  │
  ├─ 运行时检查：isAssistantMode()?
  │    ├─ settings.json 中 assistant: true?
  │    └─ GrowthBook tengu_kairos gate 命中?
  │         └─ 未命中 → 不激活
  │
  ├─ 信任检查：checkHasTrustDialogAccepted()?
  │    └─ 未通过 → 打印警告，不激活
  │         "Assistant mode disabled: directory is not trusted."
  │
  └─ 全部通过 →
       setKairosActive(true)
       options.brief = true          // 强制开启 Brief
       initializeAssistantTeam()     // 预建 in-process team
       appendSystemPrompt(addendum)  // 注入 assistant prompt
       workerType = 'claude_code_assistant'  // 标记 session 类型

特殊路径 — Agent SDK Daemon 模式：

claude --assistant  # 由 Agent SDK daemon 调用

跳过 GrowthBook gate（daemon 已在外部完成 entitlement 检查）
通过 markAssistantForced() 直接启用

六、安全设计

6.1 三重门控

层级	机制	谁控制
编译时	`feature('KAIROS')`	Anthropic 构建管线
运行时	GrowthBook `tengu_kairos`	Anthropic 远程配置
本地	Trust dialog	用户手动确认

6.2 Trust Dialog 的必要性

代码注释明确说明：

.claude/settings.json is attacker-controllable in untrusted clones.

场景：用户 clone 了一个恶意仓库，里面的 .claude/settings.json 写了 assistant: true。如果没有 trust dialog，Claude Code 会自动进入 assistant mode 并执行 .claude/agents/assistant.md 中的指令。

6.3 远程 Kill-Switch

每个子功能都有独立的远程开关：

翻转 tengu_kairos → 5 分钟内全量禁用 assistant mode
翻转 tengu_kairos_cron → 5 分钟内停止所有定时任务
翻转 tengu_kairos_brief → 5 分钟内禁用 Brief 工具
推送 tengu_kairos_cron_config → 1 分钟内调整 cron jitter 参数

七、Analytics 标记

KAIROS session 在 Datadog 和内部 analytics 中的标识：

标记	值	用途
`kairosActive`	`true`	区分 assistant vs 普通 session
`is_assistant_mode`	`true`	Datadog 维度
`worker_type`	`'claude_code_assistant'`	Bridge session 类型
`assistantActivationPath`	字符串	记录激活路径（settings/flag/forced）

事件追踪：

事件	含义
`tengu_brief_mode_enabled`	Brief 模式被激活
`tengu_brief_mode_toggled`	用户切换了 Brief 开关
`tengu_brief_send`	Agent 调用了 SendUserMessage

八、与现有功能的关系

                    ┌─────────────────────────────┐
                    │       KAIROS (Assistant)      │
                    │                               │
    独立可发布 ──►  │  PROACTIVE    AGENT_TRIGGERS  │  ◄── 独立可发布
                    │  (tick loop)   (cron system)   │
                    │                               │
                    │  KAIROS_BRIEF  KAIROS_CHANNELS │
                    │  (Brief UI)    (MCP push)      │
                    │                               │
                    │  KAIROS_DREAM  KAIROS_WEBHOOKS │
                    │  (memory)      (GitHub PR)     │
                    │                               │
                    │  Remote Viewer  Team Context   │
                    └─────────────────────────────┘
                              │
                    依赖 Claude Code 基础设施：
                    ├── compact (context 管理)
                    ├── Agent SDK (LLM 调用)
                    ├── MCP (工具协议)
                    ├── GrowthBook (feature flag)
                    ├── OAuth (认证)
                    └── Bridge (session 管理)

PROACTIVE 和 AGENT_TRIGGERS 可以脱离 KAIROS 独立使用，代码注释明确说明：

AGENT_TRIGGERS is independently shippable from KAIROS — the cron module graph has zero imports into src/assistant/ and no feature('KAIROS') calls.

这意味着 Anthropic 可能会先单独开放 cron 定时任务给所有用户，然后再逐步开放完整的 assistant mode。

九、总结

KAIROS 不是一个"实验性 demo"，而是一个工程成熟度极高的系统级特性：

175 处代码引用，横跨 75 个文件
6 个编译时 flag + 7 个运行时 gate 的精细灰度控制
运维级别的远程热配置能力
三重安全门控 + 企业级权限体系
完整的 analytics 标记体系

它代表了 Anthropic 对 Claude Code 未来形态的战略定位： 从开发者命令行工具 → AI Agent 平台。

当前它在内部小范围使用，核心实现代码在公开构建中被完全排除。从代码成熟度和运维基础设施的完备程度来看，公开发布可能已经不远。