cs-note/claude-code-best/docs/features/kairos.md

tags, create time

tags	create time
KAIROS 常驻助手 bridge proactive dream feature-flag	2026-06-09 22:30

KAIROS — 常驻助手模式

概述

KAIROS 将 Claude Code CLI 从"问答工具"转变为"常驻助手"。开启后 CLI 持续运行在后台，支持持久化 bridge 会话、后台执行任务、推送通知、每日记忆日志和外部频道消息接入。

[!info] Feature Flag: FEATURE_KAIROS=1（及子 Feature） 实现状态：核心框架完整，部分子模块为 stub；proactive/sleep 节奏控制已可用 引用数：154（全库最大）

正文

子 Feature 依赖关系

flowchart TD
    A["KAIROS 主开关"] --> B["KAIROS_BRIEF BriefTool 结构化输出"]
    A --> C["KAIROS_CHANNELS 外部频道消息"]
    A --> D["KAIROS_PUSH_NOTIFICATION 移动端推送"]
    A --> E["KAIROS_GITHUB_WEBHOOKS GitHub PR webhook"]
    A --> F["KAIROS_DREAM 记忆蒸馏"]

Warning

PROACTIVE 与 KAIROS 强绑定。所有代码检查都是 feature('PROACTIVE') || feature('KAIROS')，即 KAIROS 开启时自动获得 proactive 能力。

系统提示

KAIROS 在系统提示中注入两大段落：

Brief 段落 (getBriefSection)

文件：src/constants/prompts.ts:847-858

当 feature('KAIROS') || feature('KAIROS_BRIEF') 时注入。Brief 工具（SendUserMessage）的结构化消息输出指令。/brief toggle 和 --brief flag 只控制显示过滤，不影响模型行为。

Proactive/Autonomous Work 段落 (getProactiveSection)

文件：src/constants/prompts.ts:864-918

当 feature('PROACTIVE') || feature('KAIROS') 且 isProactiveActive() 时注入。核心行为指令：

• Tick 驱动：通过 <tick_tag> prompt 保持存活，每个 tick 包含用户当前本地时间
• 节奏控制：使用 SleepTool 控制等待间隔（prompt cache 5 分钟过期）
• 空操作时必须 Sleep：禁止输出 "still waiting" 类文本（浪费 turn 和 token）
• 偏向行动：读文件、搜索代码、修改文件、commit — 都不需询问
• 终端焦点感知：terminalFocus 字段指示用户是否在看终端
  • Unfocused -> 高度自主行动
  • Focused -> 更协作，展示选择

实现架构

核心模块

模块	文件	状态	职责
Assistant 入口	src/assistant/index.ts	Stub	isAssistantMode()、initializeAssistantTeam()
Session 发现	src/assistant/sessionDiscovery.ts	Stub	发现可用 bridge session
Session 历史	src/assistant/sessionHistory.ts	Stub	持久化 session 历史
Gate 控制	src/assistant/gate.ts	Stub	GrowthBook 门控检查
Session 选择器	src/assistant/AssistantSessionChooser.ts	Stub	UI 选择 session
BriefTool	src/tools/BriefTool/	Stub	结构化消息输出工具
Channel Notification	src/services/mcp/channelNotification.ts	Stub	外部频道消息接入
Dream Task	src/components/tasks/src/tasks/DreamTask/	Stub	记忆蒸馏任务
Memory Directory	src/memdir/memdir.ts	Stub	记忆目录管理

SleepTool（与 Proactive 共享）

文件：src/tools/SleepTool/prompt.ts

SleepTool 是 KAIROS/Proactive 的节奏控制核心。工具描述让模型理解"休眠"概念：

• 工具名：Sleep
• 功能：等待指定时间后响应 tick prompt；若队列出现新工作或 proactive 被关闭，会提前唤醒
• 与 <tick_tag> 配合实现心跳式自主工作
• 远程控制 surfaces 可通过 automation_state 看到 standby / sleeping 两种状态

Bridge 集成

KAIROS 通过 Bridge Mode（src/bridge/）连接到 claude.ai 服务器：

flowchart TD
    A["claude.ai web/app"] -->|"HTTPS long-poll"| B["Bridge API Client"]
    B -->|"src/bridge/bridgeApi.ts"| C["Session Runner"]
    C -->|"src/bridge/sessionRunner.ts"| D["REPL + Proactive Tick Loop"]

数据流

flowchart TD
    A["用户从 claude.ai 发送消息"] --> B["Bridge pollForWork() 收到 WorkResponse"]
    B --> C["acknowledgeWork() 确认接收"]
    C --> D["sessionRunner 创建/恢复 REPL session"]
    D --> E["用户消息注入到 REPL 对话"]
    E --> F["模型处理 -> 工具调用 -> BriefTool 结构化输出"]
    F --> G["结果通过 Bridge API 回传到 claude.ai"]

关键设计决策

1. Tick 驱动而非事件驱动：模型通过 SleepTool 自行控制唤醒频率，而非外部事件推送。简化架构但增加 API 调用开销
2. KAIROS 包含 PROACTIVE：所有 proactive 检查都包含 KAIROS，无需同时开启两个 flag
3. Brief 显示/行为分离：/brief toggle 只控制 UI 过滤，模型始终可以使用 BriefTool
4. Terminal Focus 感知：模型根据用户是否在看终端自动调节自主程度
5. GrowthBook 门控：部分功能（如推送通知）即使 feature flag 开启还需要服务端 GrowthBook 开关

使用方式

# 最小启用（常驻助手 + Brief）
FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev

# 全功能启用
FEATURE_KAIROS=1 \
FEATURE_KAIROS_BRIEF=1 \
FEATURE_KAIROS_CHANNELS=1 \
FEATURE_KAIROS_PUSH_NOTIFICATION=1 \
FEATURE_KAIROS_GITHUB_WEBHOOKS=1 \
FEATURE_PROACTIVE=1 \
bun run dev

# 配合 Token Budget 使用
FEATURE_KAIROS=1 FEATURE_TOKEN_BUDGET=1 bun run dev

外部依赖

• Anthropic OAuth：必须使用 claude.ai 订阅登录（非 API key）
• GrowthBook：服务端特性门控（tengu_ccr_bridge 等）
• Bridge API：/v1/environments/bridge 系列端点

文件索引

文件	行数	职责
src/assistant/index.ts	9	Assistant 模块入口（stub）
src/assistant/gate.ts	—	GrowthBook 门控（stub）
src/assistant/sessionDiscovery.ts	—	Session 发现（stub）
src/assistant/sessionHistory.ts	—	Session 历史（stub）
src/assistant/AssistantSessionChooser.ts	—	Session 选择 UI（stub）
src/tools/BriefTool/	—	BriefTool 实现（stub）
src/tools/SleepTool/prompt.ts	~30	SleepTool 工具提示
src/tools/SleepTool/SleepTool.ts	~200	休眠/唤醒与 automation metadata
src/services/mcp/channelNotification.ts	5	频道消息接入（stub）
src/memdir/memdir.ts	—	记忆目录管理（stub）
src/constants/prompts.ts:557,847-918	72	系统提示注入
src/components/tasks/src/tasks/DreamTask/	3	Dream 任务（stub）
src/proactive/index.ts	—	Proactive 核心（KAIROS 共享）
src/utils/sessionState.ts	—	向 bridge/CCR 暴露 automation 状态

关联笔记

• claude-code-best/docs/features/proactive
• claude-code-best/docs/features/auto-dream
• claude-code-best/docs/features/token-budget