Skip to content

Commit 559e65f

Browse files
author
unraid
committed
feat: integrate 5 feature branches + daemon/job 命令层级化 + 跨平台后台引擎 + TypeScript 错误修复
Squashed merge of: 1. fix/mcp-tsc-errors — 修复上游 MCP 重构后的 tsc 错误和测试失败 2. feat/pipe-mute-disconnect — Pipe IPC 逻辑断开、/lang 命令、mute 状态机 3. feat/stub-recovery-all — 实现全部 stub 恢复 (task 001-012) 4. feat/kairos-activation — KAIROS 激活解除阻塞 + 工具实现 5. codex/openclaw-autonomy-pr — 自治权限系统、运行记录、managed flows Additional: 6. daemon/job 命令层级化重构 (subcommand 架构) 7. 跨平台后台引擎抽象 (detached/tmux engines) 8. 修复 src/ 中 43 个预存在的 TypeScript 类型错误 9. 修复 langfuse isolated test mock 不完整问题
1 parent be80da4 commit 559e65f

File tree

109 files changed

+11617
-1551
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

109 files changed

+11617
-1551
lines changed

.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ src/utils/vendor/
1515
.claude/
1616
.codex/
1717
.omx/
18-
18+
.docs/task/
1919
# Binary / screenshot files (root only)
2020
/*.png
2121
*.bmp

02-kairos (1).md

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# KAIROS — 永不关机的 Claude
2+
3+
> 源码位置:`src/assistant/``src/proactive/``src/services/autoDream/`
4+
> 编译开关:`feature('KAIROS')``feature('KAIROS_BRIEF')``feature('KAIROS_CHANNELS')`
5+
> 远程开关:GrowthBook `tengu_kairos`
6+
7+
关掉终端 Claude 还在运行的持久助手模式。KAIROS 是 Claude Code 中最复杂的隐藏功能之一。
8+
9+
---
10+
11+
## 核心概念
12+
13+
KAIROS 让 Claude 从"一次性对话工具"变成"持久运行的 AI 助手":
14+
15+
- 关闭终端后 Claude 仍在后台运行
16+
- 每天自动写日志
17+
- 晚上自动"做梦"整理记忆
18+
- 没人说话时自己找活干
19+
- 命令超 15 秒自动丢后台
20+
21+
---
22+
23+
## 激活流程
24+
25+
定义在 `src/main.tsx`(约第 1054-1092 行),需要通过五层检查:
26+
27+
```
28+
1. feature('KAIROS') ← 编译时 flag
29+
2. settings.assistant: true ← .claude/settings.json
30+
3. 目录信任状态检查 ← 防恶意仓库劫持
31+
4. tengu_kairos ← GrowthBook 远程开关
32+
5. setKairosActive(true) ← 全局状态激活
33+
```
34+
35+
`--assistant` CLI 参数可跳过远程开关检查(用于 Agent SDK daemon 模式)。
36+
37+
全局状态存储在 `src/bootstrap/state.ts`
38+
- `kairosActive: boolean`(默认 `false`
39+
- `getKairosActive()` / `setKairosActive(true)`
40+
41+
---
42+
43+
## 跨会话持久运行
44+
45+
### 会话恢复
46+
47+
`src/utils/conversationRecovery.ts` 中使用 `feature('KAIROS')` 条件导入 `BriefTool``SendUserFileTool`。在反序列化会话时识别这些工具的结果为"终端工具结果",判断 turn 是正常完成还是被中断。
48+
49+
### 持久 Cron 任务
50+
51+
关键在 `.claude/scheduled_tasks.json`。标记为 `permanent: true` 的任务不受 7 天自动过期限制:
52+
53+
- `catch-up`:恢复中断的工作
54+
- `morning-checkin`:每日早间签到
55+
- `dream`:记忆整合
56+
57+
### 会话历史 API
58+
59+
`src/assistant/sessionHistory.ts` 通过 OAuth API 加载远程会话历史,使用 `v1/sessions/{sessionId}/events` 端点,支持分页拉取。
60+
61+
---
62+
63+
## 做梦机制(Dream)
64+
65+
KAIROS 最精巧的子系统——后台运行的子代理,将分散的会话记忆整合为持久的结构化知识。
66+
67+
### 触发条件(三层门控,由廉到贵)
68+
69+
定义在 `src/services/autoDream/autoDream.ts`
70+
71+
```
72+
1. 时间门控:距上次整合超过 24 小时(minHours)
73+
2. 会话门控:至少 5 个新会话(minSessions)
74+
3. 锁门控:没有其他进程正在整合
75+
```
76+
77+
阈值通过 GrowthBook `tengu_onyx_plover` 远程配置动态控制。
78+
79+
### 四阶段整合流程
80+
81+
定义在 `src/services/autoDream/consolidationPrompt.ts`
82+
83+
| 阶段 | 动作 |
84+
|------|------|
85+
| **Orient** | 列出记忆目录、读取 `MEMORY.md` 索引、浏览已有主题文件 |
86+
| **Gather** | 从每日日志、已有记忆、JSONL transcript 中搜集新信号 |
87+
| **Consolidate** | 合并新信号到主题文件,转换相对日期为绝对日期,删除过时事实 |
88+
| **Prune** | 更新 `MEMORY.md` 索引,保持在行数和大小限制内 |
89+
90+
### 锁机制
91+
92+
`src/services/autoDream/consolidationLock.ts`
93+
94+
- 使用 `.consolidate-lock` 文件
95+
- 文件 mtime = `lastConsolidatedAt`
96+
- 文件内容 = 持有者 PID
97+
- 支持 PID 存活检查(1 小时超时)
98+
- double-write 后 re-read 验证防竞争
99+
100+
### 每日日志
101+
102+
路径由 `src/memdir/paths.ts``getAutoMemDailyLogPath()` 计算:
103+
104+
```
105+
<autoMemPath>/logs/YYYY/MM/YYYY-MM-DD.md
106+
```
107+
108+
### UI 呈现
109+
110+
- Footer pill 标签显示 **"dreaming"**
111+
- `src/components/tasks/DreamDetailDialog.tsx` 提供专门的详情对话框
112+
- 支持查看实时进度和手动中止
113+
- `Shift+Down` 打开后台任务对话框
114+
115+
---
116+
117+
## 主动模式(Proactive Mode)
118+
119+
没人说话时 Claude 自己找活干。
120+
121+
### 核心状态
122+
123+
`src/proactive/index.ts` 维护三个状态:
124+
125+
| 状态 | 说明 |
126+
|------|------|
127+
| `active` | 是否激活 |
128+
| `paused` | 是否暂停(用户按 Esc 取消时暂停,下次输入恢复) |
129+
| `contextBlocked` | API 错误时阻塞 tick,防止 tick-error-tick 死循环 |
130+
131+
### 激活方式
132+
133+
- `--proactive` CLI 参数
134+
- `CLAUDE_CODE_PROACTIVE` 环境变量
135+
-`feature('PROACTIVE') || feature('KAIROS')` 保护
136+
137+
### 系统提示
138+
139+
激活后追加:
140+
141+
```
142+
# Proactive Mode
143+
144+
You are in proactive mode. Take initiative -- explore, act, and make progress
145+
without waiting for instructions.
146+
147+
Start by briefly greeting the user.
148+
149+
You will receive periodic <tick> prompts. These are check-ins. Do whatever
150+
seems most useful, or call Sleep if there's nothing to do.
151+
```
152+
153+
### SleepTool 集成
154+
155+
设置中的 `minSleepDurationMs``maxSleepDurationMs` 控制 Sleep 持续时间范围,节流 proactive tick 频率。没活干就 Sleep 等着。
156+
157+
---
158+
159+
## 后台任务管理
160+
161+
### Cron 调度器
162+
163+
`src/utils/cronScheduler.ts`
164+
165+
- 每 1 秒 tick 一次(`CHECK_INTERVAL_MS = 1000`
166+
- 使用 chokidar 监视 `.claude/scheduled_tasks.json`
167+
- 支持调度器锁(`src/utils/cronTasksLock.ts`),防止多实例重复触发
168+
- 锁探测间隔 5 秒,持有者崩溃时自动接管
169+
170+
### 任务类型
171+
172+
| 类型 | 说明 |
173+
|------|------|
174+
| 一次性(`recurring: false`| 触发后自动删除,支持错过任务检测 |
175+
| 循环(`recurring: true`| 触发后重新调度,默认 7 天过期 |
176+
| 永久(`permanent: true`| 不受过期限制(KAIROS 专用) |
177+
| 会话级(`durable: false`| 仅内存中,进程退出即消失 |
178+
179+
### Jitter 防雷群机制
180+
181+
`src/utils/cronJitterConfig.ts`
182+
183+
- 循环任务:基于 taskId 的确定性延迟(interval 的 10%,上限 15 分钟)
184+
- 一次性任务:在 :00 和 :30 施加最多 90 秒提前量
185+
- 运维可在事故期间推送配置变更,60 秒内全客户端生效
186+
187+
---
188+
189+
## 关键源码文件
190+
191+
| 文件 | 职责 |
192+
|------|------|
193+
| `src/bootstrap/state.ts` | KAIROS 全局状态 |
194+
| `src/assistant/index.ts` | 助手模式入口 |
195+
| `src/assistant/sessionHistory.ts` | 远程会话历史 API |
196+
| `src/proactive/index.ts` | 主动模式状态管理 |
197+
| `src/services/autoDream/autoDream.ts` | Auto-Dream 引擎 |
198+
| `src/services/autoDream/consolidationPrompt.ts` | 整合提示(四阶段) |
199+
| `src/services/autoDream/consolidationLock.ts` | 整合锁 |
200+
| `src/services/autoDream/config.ts` | Dream 配置 |
201+
| `src/tasks/DreamTask/DreamTask.ts` | Dream 任务定义 |
202+
| `src/utils/cronScheduler.ts` | Cron 调度器 |
203+
| `src/utils/cronTasks.ts` | Cron 任务持久化 |
204+
| `src/skills/bundled/dream.ts` | `/dream` Skill(存根) |

build.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ const DEFAULT_BUILD_FEATURES = [
4040
'KAIROS',
4141
'COORDINATOR_MODE',
4242
'LAN_PIPES',
43+
'BG_SESSIONS',
44+
'TEMPLATES',
4345
// 'REVIEW_ARTIFACT', // API 请求无响应,需进一步排查 schema 兼容性
4446
// P3: poor mode (disable extract_memories + prompt_suggestion)
4547
'POOR',

0 commit comments

Comments
 (0)