vault backup: 2026-06-09 23:15:17

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

@@ -1,44 +1,46 @@
+---
+tags: [KAIROS, 常驻助手, bridge, proactive, dream, feature-flag]
+create time: 2026-06-09 22:30
+---
+
 # KAIROS — 常驻助手模式
 
+## 概述
+
+KAIROS 将 Claude Code CLI 从"问答工具"转变为"常驻助手"。开启后 CLI 持续运行在后台，支持持久化 bridge 会话、后台执行任务、推送通知、每日记忆日志和外部频道消息接入。
+
+> [!info]
 > Feature Flag: `FEATURE_KAIROS=1`（及子 Feature）
 > 实现状态：核心框架完整，部分子模块为 stub；proactive/sleep 节奏控制已可用
 > 引用数：154（全库最大）
 
-## 一、功能概述
-
-KAIROS 将 Claude Code CLI 从"问答工具"转变为"常驻助手"。开启后，CLI 持续运行在后台，支持：
-
-- **持久化 bridge 会话**：跨终端重启复用 session，通过 Anthropic OAuth 连接 claude.ai
-- **后台执行任务**：用户离开终端时继续工作（配合 PROACTIVE feature）
-- **推送通知到移动端**：任务完成或需要输入时推送（配合 `KAIROS_PUSH_NOTIFICATION`）
-- **每日记忆日志**：自动记录和回顾工作内容（配合 `KAIROS_DREAM`）
-- **外部频道消息接入**：Slack/Discord/Telegram 消息转发到 CLI（配合 `KAIROS_CHANNELS`）
-- **结构化 Brief 输出**：通过 BriefTool 输出结构化消息（配合 `KAIROS_BRIEF`）
+## 正文
 
 ### 子 Feature 依赖关系
 
-```
-KAIROS (主开关)
-├── KAIROS_BRIEF (BriefTool, 结构化输出)
-├── KAIROS_CHANNELS (外部频道消息)
-├── KAIROS_PUSH_NOTIFICATION (移动端推送)
-├── KAIROS_GITHUB_WEBHOOKS (GitHub PR webhook)
-└── KAIROS_DREAM (记忆蒸馏)
+```mermaid
+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 记忆蒸馏"]
 ```
 
-**注意**：PROACTIVE 与 KAIROS 强绑定。所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即 KAIROS 开启时自动获得 proactive 能力。
+> [!warning]
+> PROACTIVE 与 KAIROS 强绑定。所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即 KAIROS 开启时自动获得 proactive 能力。
 
-## 二、系统提示
+### 系统提示
 
 KAIROS 在系统提示中注入两大段落：
 
-### 2.1 Brief 段落 (`getBriefSection`)
+#### Brief 段落 (`getBriefSection`)
 
 文件：`src/constants/prompts.ts:847-858`
 
 当 `feature('KAIROS') || feature('KAIROS_BRIEF')` 时注入。Brief 工具（`SendUserMessage`）的结构化消息输出指令。`/brief` toggle 和 `--brief` flag 只控制显示过滤，不影响模型行为。
 
-### 2.2 Proactive/Autonomous Work 段落 (`getProactiveSection`)
+#### Proactive/Autonomous Work 段落 (`getProactiveSection`)
 
 文件：`src/constants/prompts.ts:864-918`
 
@@ -49,12 +51,12 @@ KAIROS 在系统提示中注入两大段落：
 - **空操作时必须 Sleep**：禁止输出 "still waiting" 类文本（浪费 turn 和 token）
 - **偏向行动**：读文件、搜索代码、修改文件、commit — 都不需询问
 - **终端焦点感知**：`terminalFocus` 字段指示用户是否在看终端
-  - Unfocused → 高度自主行动
-  - Focused → 更协作，展示选择
+  - Unfocused -> 高度自主行动
+  - Focused -> 更协作，展示选择
 
-## 三、实现架构
+### 实现架构
 
-### 3.1 核心模块
+#### 核心模块
 
 | 模块 | 文件 | 状态 | 职责 |
 |------|------|------|------|
@@ -68,7 +70,7 @@ KAIROS 在系统提示中注入两大段落：
 | Dream Task | `src/components/tasks/src/tasks/DreamTask/` | Stub | 记忆蒸馏任务 |
 | Memory Directory | `src/memdir/memdir.ts` | Stub | 记忆目录管理 |
 
-### 3.2 SleepTool（与 Proactive 共享）
+#### SleepTool（与 Proactive 共享）
 
 文件：`src/tools/SleepTool/prompt.ts`
 
@@ -78,66 +80,38 @@ SleepTool 是 KAIROS/Proactive 的节奏控制核心。工具描述让模型理
 - 与 `<tick_tag>` 配合实现心跳式自主工作
 - 远程控制 surfaces 可通过 `automation_state` 看到 `standby` / `sleeping` 两种状态
 
-### 3.3 Bridge 集成
+#### Bridge 集成
 
 KAIROS 通过 Bridge Mode（`src/bridge/`）连接到 claude.ai 服务器：
 
-```
-claude.ai web/app
-      │
-      ▼ (HTTPS long-poll)
-┌──────────────────────┐
-│  Bridge API Client   │  src/bridge/bridgeApi.ts
-│  (register/poll/     │
-│   acknowledge)       │
-└──────────┬───────────┘
-           │
-           ▼
-┌──────────────────────┐
-│  Session Runner      │  src/bridge/sessionRunner.ts
-│  (创建/恢复 REPL)     │
-└──────────┬───────────┘
-           │
-           ▼
-┌──────────────────────┐
-│  REPL + Proactive    │  Tick 驱动自主工作
-│  Tick Loop           │
-└──────────────────────┘
+```mermaid
+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"]
 ```
 
-### 3.4 数据流
+#### 数据流
 
-```
-用户从 claude.ai 发送消息
-         │
-         ▼
-Bridge pollForWork() 收到 WorkResponse
-         │
-         ▼
-acknowledgeWork() 确认接收
-         │
-         ▼
-sessionRunner 创建/恢复 REPL session
-         │
-         ▼
-用户消息注入到 REPL 对话
-         │
-         ▼
-模型处理 → 工具调用 → BriefTool 结构化输出
-         │
-         ▼
-结果通过 Bridge API 回传到 claude.ai
+```mermaid
+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
+2. **KAIROS 包含 PROACTIVE**：所有 proactive 检查都包含 KAIROS，无需同时开启两个 flag
 3. **Brief 显示/行为分离**：`/brief` toggle 只控制 UI 过滤，模型始终可以使用 BriefTool
 4. **Terminal Focus 感知**：模型根据用户是否在看终端自动调节自主程度
 5. **GrowthBook 门控**：部分功能（如推送通知）即使 feature flag 开启还需要服务端 GrowthBook 开关
 
-## 五、使用方式
+### 使用方式
 
 ```bash
 # 最小启用（常驻助手 + Brief）
@@ -156,13 +130,13 @@ bun run dev
 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` 系列端点
 
-## 七、文件索引
+### 文件索引
 
 | 文件 | 行数 | 职责 |
 |------|------|------|
@@ -180,3 +154,9 @@ FEATURE_KAIROS=1 FEATURE_TOKEN_BUDGET=1 bun run dev
 | `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]]