172 lines
6.2 KiB
Markdown
172 lines
6.2 KiB
Markdown
# Claude Code 工作状态监控
|
||
|
||
> 状态：方案设计中 | 2026-06-05
|
||
|
||
## 需求
|
||
|
||
在 u-desktop 中即时反馈当前 Claude Code 工作状态（多项目、多会话并行），基于会话指令解析出任务便于跟踪。
|
||
|
||
两个入口：
|
||
1. **桌面 Overlay 卡片** — 状态概览 + 会话名 + busy/idle
|
||
2. **托盘看板窗口** — 完整详情 + 任务列表 + 团队信息 + 进度（置顶 + 可调大小）
|
||
|
||
---
|
||
|
||
## 数据源
|
||
|
||
| 源文件 | 内容 | 路径 |
|
||
|--------|------|------|
|
||
| sessions/*.json | 活跃进程：PID、sessionId、cwd、status、name | `~/.claude/sessions/` |
|
||
| history.jsonl | 用户输入历史：sessionId + display | `~/.claude/history.jsonl` |
|
||
| tasks/<sid>/*.json | 任务列表：subject、status、依赖 | `~/.claude/tasks/` |
|
||
| teams/<name>/config.json | 团队：成员、模型、工作目录 | `~/.claude/teams/` |
|
||
|
||
### 数据关联
|
||
|
||
```
|
||
sessions/*.json → 活跃会话列表
|
||
├─ cwd → 项目名（extractProjectName）
|
||
├─ name → 会话名（自动生成的任务摘要，优先展示）
|
||
└─ sessionId → 关联 history/tasks
|
||
|
||
history.jsonl → 尾读 64KB（覆盖 ~3 天）
|
||
└─ sessionId → lastPrompt（每个会话最后一条指令）
|
||
|
||
tasks/<sid>/ → 临时文件，完成即清除
|
||
└─ N.json → subject + status + 依赖关系
|
||
```
|
||
|
||
### 字段实测（2026-06-05）
|
||
|
||
```
|
||
PID 20804 → name: "knowledge-card-markdown-rendering" status: busy 项目: u-desktop
|
||
PID 22244 → name: "claude-code-status-monitor" status: busy 项目: u-desktop
|
||
PID 30064 → name: "add-audio-viz-modes" status: idle 项目: u-desktop
|
||
PID 7516 → name: "" status: idle 项目: u-desk
|
||
```
|
||
|
||
- `name` 字段是 Claude Code 自动生成的会话名，比 lastPrompt 更结构化
|
||
- `status` 在 busy 时 updatedAt 实时刷新（~15s），idle 时长时间不更新
|
||
- history.jsonl 64KB 覆盖 352 行 / 4828 分钟 / 28 个会话，lastPrompt 命中率 4/4
|
||
|
||
---
|
||
|
||
## 技术方案
|
||
|
||
### 采集策略
|
||
|
||
**定时轮询 5 秒**（非文件监视）。
|
||
|
||
理由：
|
||
- sessions/ 通常 1-5 个文件 × 300B，全读 <1ms
|
||
- history.jsonl 尾读 64KB <1ms
|
||
- 与现有 weatherLoop/knowledgeLoop 模式一致
|
||
- ReadDirectoryChangesW 在此场景无优势
|
||
|
||
### 数据结构
|
||
|
||
```go
|
||
type ClaudeSession struct {
|
||
PID int `json:"pid"`
|
||
SessionID string `json:"sessionId"`
|
||
Project string `json:"project"` // cwd → 项目名
|
||
CWD string `json:"cwd"`
|
||
Status string `json:"status"` // idle | busy
|
||
Name string `json:"name"` // 会话名（任务摘要）
|
||
LastPrompt string `json:"lastPrompt"` // 最后用户指令
|
||
StartedAt int64 `json:"startedAt"`
|
||
UpdatedAt int64 `json:"updatedAt"`
|
||
Version string `json:"version"`
|
||
Duration string `json:"duration"` // 运行时长
|
||
}
|
||
|
||
type ClaudeTask struct {
|
||
ID string `json:"id"`
|
||
Subject string `json:"subject"`
|
||
Status string `json:"status"` // pending | in_progress | completed
|
||
}
|
||
|
||
type ClaudeStatusData struct {
|
||
Sessions []ClaudeSession `json:"sessions"`
|
||
TotalActive int `json:"totalActive"`
|
||
TotalBusy int `json:"totalBusy"`
|
||
UpdatedAt int64 `json:"updatedAt"`
|
||
}
|
||
```
|
||
|
||
### 关键修正（来自研判）
|
||
|
||
1. **isProcessAlive(pid)** — 用 OpenProcess 验证进程存活，过滤幽灵会话
|
||
2. **history 尾读跳过首行** — Seek 后首行必然被截断，跳过避免 JSON 解析失败
|
||
3. **缓存 lastPrompts** — 按 PID 集合变化决定是否重新读 history，避免重复解析
|
||
|
||
### 推送到前端
|
||
|
||
复用现有 `evalJS()` + `window.updateClaudeStatusFromGo()` 模式。
|
||
看板窗口通过 `WebView2.Dispatch()` 独立推送。
|
||
|
||
---
|
||
|
||
## 卡片设计
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Claude Code ●2 忙碌 / 4 活跃 │
|
||
│ ─────────────────────────────────── │
|
||
│ ● u-desktop knowledge-card... │
|
||
│ 最后: 知识卡片刷新按钮修复 │
|
||
│ ○ u-desktop add-audio-viz-modes │
|
||
│ ○ u-desk ~ │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
- 优先展示 `name`（会话名），补充 `lastPrompt`
|
||
- busy = 绿色脉冲，idle = 灰色
|
||
- 最多 5 个会话，超出折叠
|
||
|
||
---
|
||
|
||
## 看板窗口
|
||
|
||
- 托盘菜单"Claude 看板"入口
|
||
- 独立 WebView2，纯 HTML embed（不走 Vite 构建）
|
||
- 深色主题匹配 overlay 风格
|
||
- **置顶**：`wsExTopmost` (0x00000008) 切换
|
||
- **可调大小**：保留 `wsSizebox`
|
||
- 会话详情卡片 + 任务列表 + 团队信息
|
||
|
||
---
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| `claude_status.go` | 新建 | 监控引擎：轮询采集、数据结构、推送 |
|
||
| `claude_board.go` | 新建 | 看板窗口：WebView2 + 置顶 + 可调大小 |
|
||
| `web/claude-board.html` | 新建 | 看板页面（纯 HTML embed） |
|
||
| `ClaudeStatusCard.vue` | 新建 | Overlay 卡片组件 |
|
||
| `config.go` | 修改 | +`HideClaudeStatus` |
|
||
| `win32.go` | 修改 | +`wsExTopmost` + `procOpenProcess` + `procCloseHandle` |
|
||
| `systray.go` | 修改 | +看板菜单 + 启动 loop |
|
||
| `wallpaper.go` | 修改 | +cardVisibility + reloadAllCards |
|
||
| `settings.go` | 修改 | +toggle + refreshVisibleCards |
|
||
| `types.ts` | 修改 | +ClaudeStatusData 类型 |
|
||
| `useOverlayState.ts` | 修改 | +claudeStatus 状态 |
|
||
| `bridge.ts` | 修改 | +updateClaudeStatusFromGo |
|
||
| `SingleLayout.vue` | 修改 | +ClaudeStatusCard |
|
||
| `MultiLayout.vue` | 修改 | +ClaudeStatusCard + grid area |
|
||
| `ToggleSection.vue` | 修改 | +Claude 状态 toggle |
|
||
|
||
---
|
||
|
||
## 研判结论
|
||
|
||
| 维度 | 评估 |
|
||
|------|------|
|
||
| 数据可靠性 | 中→高（加进程存活校验后）。sessions 是第一方数据源，字段稳定 |
|
||
| 性能影响 | 极低。每轮 <5ms / 65KB I/O。0.1% CPU |
|
||
| 对工具负担 | 零。纯只读、共享读、不锁文件、不连 socket |
|
||
| 价值 | 高。多会话并行监控的刚需，无其他工具提供 |
|
||
| 成本 | 低。~450 行代码。运行开销可忽略 |
|
||
| 性价比 | **极高** |
|