@agentunion/kite 1.5.0 → 1.6.0

package/docs/ClaudeCode/350/277/234/347/250/213/345/215/217/344/275/234/347/263/273/347/273/237/350/256/276/350/256/241.md

@@ -0,0 +1,631 @@
+# Claude Code 远程协作系统设计文档
+
+## 项目概述
+
+本项目旨在为 Claude Code 提供**记忆管理**和**消息收发**能力，使其成为可远程调用的智能编码助手。通过 Skill + Hook + 后台服务的架构，实现：
+
+1. **记忆外挂** — 远程 API 提供上下文记忆，动态注入到 Claude Code 会话
+2. **消息通知** — 外部消息自动推送到 Claude Code 会话中
+3. **远程任务执行** — 通过 API 触发 Claude Code 执行编码任务
+
+---
+
+## 核心目标
+
+- **Claude Code 作为远程可调用的编码引擎**
+- **远程 API 作为 Claude Code 的记忆和消息中心**
+- **双向通信**：Claude ↔ 远程 API
+
+---
+
+## 系统架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Claude Code 会话                        │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  系统提示词 (增强)                                     │  │
+│  │  ├─ 记忆提取 (Memory API)                             │  │
+│  │  ├─ 索引缓存 (Index Cache)                            │  │
+│  │  └─ 外部消息 (Message Notifications)                  │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                          ↑                                   │
+│                          │ Hook 注入                         │
+│  ┌──────────────────────┴──────────────────────────────┐  │
+│  │  Hook 系统 (UserPromptSubmit / SessionStart)         │  │
+│  │  └─ 调用本地 API 获取上下文                           │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                          ↕
+┌─────────────────────────────────────────────────────────────┐
+│              本地后台服务 (Background Daemon)                │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  消息轮询器 (Message Poller)                          │  │
+│  │  ├─ 定期调用远程 API 获取新消息                        │  │
+│  │  ├─ 检测会话空闲状态 (通过 Hook 状态文件)              │  │
+│  │  └─ 触发: claude -p "新消息" --resume <session-id>    │  │
+│  └──────────────────────────────────────────────────────┘  │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  本地 API 服务 (Hook Endpoint)                        │  │
+│  │  ├─ GET /memory — 返回记忆摘要                         │  │
+│  │  ├─ GET /index — 返回索引缓存                          │  │
+│  │  └─ GET /messages — 返回待通知消息                     │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                          ↕
+┌─────────────────────────────────────────────────────────────┐
+│                    远程 API (Memory Hub)                     │
+│  ├─ POST /tasks — 接收远程任务请求                          │
+│  ├─ GET /memory/{session} — 提供记忆上下文                  │
+│  ├─ POST /memory/{session} — 保存会话记忆                   │
+│  └─ GET /messages/pending — 返回待处理消息                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 功能模块
+
+### 1. Skill 控制器
+
+**Skill 名称**: `remote-collab` (或 `memory-hub`)
+
+#### 1.1 启用功能
+
+```bash
+/remote-collab enable
+```
+
+**执行流程**：
+1. 调用本地 API: `POST /control/enable`
+2. 本地 API 执行：
+   - 写入 `.claude/settings.json`，配置 Hook
+   - 启动后台守护进程 (Message Poller)
+   - 返回状态确认
+
+**Hook 配置内容**：
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "type": "command",
+      "command": "curl -s http://localhost:9988/hook/session-start"
+    }],
+    "UserPromptSubmit": [{
+      "type": "command",
+      "command": "bash $CLAUDE_PROJECT_DIR/.claude/hooks/inject-context.sh"
+    }]
+  }
+}
+```
+
+#### 1.2 禁用功能
+
+```bash
+/remote-collab disable
+```
+
+**执行流程**：
+1. 调用本地 API: `POST /control/disable`
+2. 本地 API 执行：
+   - 清理 `.claude/settings.json` 中的 Hook 配置
+   - 停止后台守护进程
+   - 清理状态文件
+
+---
+
+### 2. Hook 系统
+
+#### 2.1 SessionStart Hook
+
+**触发时机**: 会话开始时（仅一次）
+
+**功能**:
+- 从远程 API 获取记忆摘要和索引缓存
+- 注入到系统提示词（**仅在会话开始时注入一次**）
+
+**实现**:
+```bash
+#!/bin/bash
+# .claude/hooks/session-start.sh
+
+# 从 stdin 读取 hook 上下文
+CONTEXT=$(cat)
+SESSION_ID=$(echo "$CONTEXT" | jq -r '.sessionId')
+
+# 调用本地 API 获取记忆和索引
+MEMORY=$(curl -s "http://localhost:9988/memory?session=$SESSION_ID")
+INDEX=$(curl -s "http://localhost:9988/index?session=$SESSION_ID")
+
+# 构造 additionalContext
+cat <<EOF
+{
+  "decision": "allow",
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "# 记忆上下文\n$MEMORY\n\n# 索引缓存\n$INDEX"
+  }
+}
+EOF
+exit 0
+```
+
+**关键问题解答**：
+
+> **Q: 记忆和索引是否每轮对话都插入？**
+>
+> **A: 不会。** 使用 `SessionStart` hook 可以确保**仅在会话开始时注入一次**。后续对话轮次不会重复注入，避免浪费 token。
+>
+> Claude Code 的会话机制会保留完整的对话历史，包括 SessionStart 时注入的 `additionalContext`，所以后续轮次 Claude 仍然能看到这些上下文。
+
+#### 2.2 UserPromptSubmit Hook
+
+**触发时机**: 用户每次提交提示词时
+
+**功能**:
+- 检查是否有新的外部消息
+- 如果有，注入到当前提示词上下文
+
+**实现**:
+```bash
+#!/bin/bash
+# .claude/hooks/inject-messages.sh
+
+CONTEXT=$(cat)
+SESSION_ID=$(echo "$CONTEXT" | jq -r '.sessionId')
+
+# 获取待通知消息
+MESSAGES=$(curl -s "http://localhost:9988/messages?session=$SESSION_ID")
+
+if [ -n "$MESSAGES" ] && [ "$MESSAGES" != "[]" ]; then
+  # 有新消息，注入
+  cat <<EOF
+{
+  "decision": "allow",
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "# 新消息通知\n$MESSAGES"
+  }
+}
+EOF
+else
+  # 无新消息，直接放行
+  echo "$CONTEXT"
+fi
+exit 0
+```
+
+**消息通知机制**：
+- 本地 API 维护消息队列
+- 每次 `UserPromptSubmit` 时检查队列
+- 消息被注入后，从队列中移除（避免重复通知）
+
+#### 2.3 会话状态追踪 Hook
+
+**目的**: 追踪会话活跃状态，避免后台触发器与用户交互冲突
+
+**实现**: 见下文"后台服务"部分
+
+---
+
+### 3. 本地 API 服务
+
+**技术栈**: FastAPI (Python) 或 Express (Node.js)
+
+**端口**: `http://localhost:9988`
+
+#### 3.1 API 端点
+
+##### GET /memory
+
+**功能**: 返回记忆摘要
+
+**参数**:
+- `session`: 会话 ID
+
+**返回**:
+```json
+{
+  "summary": "用户正在开发 Kite 框架，最近在实现模块间通信...",
+  "context": [
+    "项目路径: C:/Users/agentcp/.../Kite",
+    "最近修改: kernel.py, launcher.py",
+    "待办事项: 实现 WebSocket RPC"
+  ]
+}
+```
+
+##### GET /index
+
+**功能**: 返回索引缓存
+
+**返回**:
+```json
+{
+  "files": ["kernel.py", "launcher.py", "..."],
+  "symbols": ["KernelModule", "Launcher", "..."],
+  "recent_changes": [...]
+}
+```
+
+##### GET /messages
+
+**功能**: 返回待通知消息
+
+**参数**:
+- `session`: 会话 ID
+
+**返回**:
+```json
+{
+  "messages": [
+    {
+      "id": "msg-001",
+      "content": "用户 Alice 请求帮助：如何配置 Kite 模块？",
+      "timestamp": "2026-03-04T10:30:00Z"
+    }
+  ]
+}
+```
+
+**副作用**: 返回后，这些消息从队列中移除
+
+##### POST /control/enable
+
+**功能**: 启用远程协作功能
+
+**执行**:
+1. 写入 `.claude/settings.json`
+2. 启动后台守护进程
+3. 初始化状态文件
+
+##### POST /control/disable
+
+**功能**: 禁用远程协作功能
+
+**执行**:
+1. 清理 `.claude/settings.json`
+2. 停止后台守护进程
+3. 清理状态文件
+
+---
+
+### 4. 后台守护进程
+
+**进程名**: `claude-message-poller`
+
+**功能**:
+1. 定期轮询远程 API 获取新消息
+2. 检测会话空闲状态
+3. 触发 `claude -p --resume` 处理新消息
+
+#### 4.1 会话状态追踪
+
+**机制**: 通过 Hook 写入状态文件
+
+**Hook 配置**:
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "type": "command",
+      "command": "bash .claude/hooks/track-session.sh"
+    }],
+    "SessionEnd": [{
+      "type": "command",
+      "command": "bash .claude/hooks/track-session.sh"
+    }],
+    "UserPromptSubmit": [{
+      "type": "command",
+      "command": "bash .claude/hooks/track-session.sh"
+    }],
+    "PreToolUse": [{
+      "type": "command",
+      "command": "bash .claude/hooks/track-session.sh"
+    }],
+    "PostToolUse": [{
+      "type": "command",
+      "command": "bash .claude/hooks/track-session.sh"
+    }]
+  }
+}
+```
+
+**状态文件**: `~/.claude/session-state/{session-id}.active`
+
+**内容**: Unix 时间戳（最后活动时间）
+
+#### 4.2 消息轮询器实现
+
+```python
+#!/usr/bin/env python3
+"""claude-message-poller.py"""
+import subprocess, time, requests, json
+from pathlib import Path
+
+# 配置
+REMOTE_API = "https://api.example.com/messages/pending"
+LOCAL_API = "http://localhost:9988"
+SESSION_ID = "your-session-id"
+STATE_DIR = Path.home() / ".claude/session-state"
+POLL_INTERVAL = 10  # 秒
+IDLE_THRESHOLD = 60  # 秒
+
+def is_session_idle():
+    """检查会话是否空闲"""
+    active_file = STATE_DIR / f"{SESSION_ID}.active"
+    if not active_file.exists():
+        return True
+
+    try:
+        last_activity = int(active_file.read_text().strip())
+        return (time.time() - last_activity) > IDLE_THRESHOLD
+    except:
+        return True
+
+def fetch_messages():
+    """从远程 API 获取新消息"""
+    try:
+        resp = requests.get(REMOTE_API, timeout=5)
+        return resp.json().get("messages", [])
+    except Exception as e:
+        print(f"[错误] 获取消息失败: {e}")
+        return []
+
+def push_to_local_queue(messages):
+    """推送消息到本地队列"""
+    try:
+        requests.post(f"{LOCAL_API}/messages/push", json={"messages": messages})
+    except Exception as e:
+        print(f"[错误] 推送到本地队列失败: {e}")
+
+def trigger_claude(message):
+    """触发 Claude Code 处理消息"""
+    prompt = f"收到新消息：\n{json.dumps(message, ensure_ascii=False, indent=2)}"
+    subprocess.run([
+        "claude", "-p", prompt,
+        "--resume", SESSION_ID
+    ])
+
+def main():
+    print(f"[消息轮询器] 启动，会话 ID: {SESSION_ID}")
+
+    while True:
+        # 获取新消息
+        messages = fetch_messages()
+
+        if messages:
+            print(f"[消息轮询器] 收到 {len(messages)} 条新消息")
+
+            # 推送到本地队列（供 Hook 使用）
+            push_to_local_queue(messages)
+
+            # 如果会话空闲，立即触发处理
+            if is_session_idle():
+                print(f"[消息轮询器] 会话空闲，触发处理")
+                for msg in messages:
+                    trigger_claude(msg)
+            else:
+                print(f"[消息轮询器] 会话活跃，消息已入队，等待用户下次提问时通知")
+
+        time.sleep(POLL_INTERVAL)
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## 工作流程
+
+### 场景 1: 用户主动会话（带记忆增强）
+
+```
+1. 用户启动 Claude Code
+   └─> SessionStart Hook 触发
+       └─> 调用本地 API /memory + /index
+           └─> 本地 API 调用远程 API 获取记忆
+               └─> 记忆和索引注入到系统提示词（仅此一次）
+
+2. 用户提问："帮我实现 WebSocket RPC"
+   └─> UserPromptSubmit Hook 触发
+       └─> 检查本地消息队列（无新消息）
+           └─> 直接放行
+
+3. Claude 基于增强的上下文回答
+   └─> 能看到之前的项目记忆和索引
+
+4. 用户继续提问："上次我们讨论到哪了？"
+   └─> Claude 直接从会话历史中看到 SessionStart 注入的记忆
+       └─> 无需重复注入
+```
+
+### 场景 2: 外部消息到达（用户正在会话）
+
+```
+1. 远程 API 收到新消息："Alice 请求帮助"
+   └─> 后台轮询器检测到新消息
+       └─> 推送到本地消息队列
+           └─> 检测会话状态：活跃中
+               └─> 不触发 -p，等待用户下次提问
+
+2. 用户提问："还有什么事吗？"
+   └─> UserPromptSubmit Hook 触发
+       └─> 检查本地消息队列：有新消息
+           └─> 注入消息到当前提示词上下文
+               └─> 消息从队列移除
+
+3. Claude 回答："有一条新消息：Alice 请求帮助..."
+```
+
+### 场景 3: 外部消息到达（用户空闲）
+
+```
+1. 远程 API 收到新消息："紧急任务：修复 bug"
+   └─> 后台轮询器检测到新消息
+       └─> 推送到本地消息队列
+           └─> 检测会话状态：空闲（60 秒无活动）
+               └─> 触发: claude -p "收到新消息..." --resume <session-id>
+
+2. Claude Code 自动启动处理
+   └─> 读取会话历史（包含之前的记忆上下文）
+       └─> 处理新消息
+           └─> 执行任务或等待用户确认
+
+3. 用户回到终端
+   └─> 看到 Claude 已经处理了新消息
+       └─> 可以继续对话或查看结果
+```
+
+### 场景 4: 远程任务执行
+
+```
+1. 远程系统调用: POST /tasks
+   {
+     "task": "在 Kite 项目中添加日志功能",
+     "session_id": "xxx"
+   }
+
+2. 本地 API 接收任务
+   └─> 推送到消息队列
+       └─> 后台轮询器检测到
+           └─> 触发: claude -p "远程任务：添加日志功能" --resume xxx
+
+3. Claude Code 执行任务
+   └─> 读取项目代码
+       └─> 实现日志功能
+           └─> 提交代码
+               └─> 回调远程 API 报告结果
+```
+
+---
+
+## 技术细节
+
+### Token 优化策略
+
+**问题**: 记忆和索引可能很大，每轮对话都注入会浪费 token
+
+**解决方案**:
+
+1. **SessionStart 注入** — 仅在会话开始时注入一次
+2. **增量更新** — 如果记忆有更新，通过消息通知机制推送增量
+3. **摘要压缩** — 远程 API 返回摘要而非完整记忆
+4. **按需加载** — Claude 需要详细信息时，通过工具调用远程 API
+
+### 并发控制
+
+**问题**: 用户交互 + 后台 -p 可能同时写入会话
+
+**解决方案**:
+
+1. **状态检测** — 后台轮询器检测会话空闲才触发
+2. **消息队列** — 活跃时消息入队，等待下次 UserPromptSubmit 通知
+3. **文件锁** — 可选，操作系统级别的互斥保证
+
+### 会话 ID 管理
+
+**问题**: 如何获取和管理会话 ID
+
+**方案 1: 固定会话**
+```bash
+# 启动时指定会话 ID
+claude --session-id <uuid>
+```
+
+**方案 2: 动态获取**
+```bash
+# SessionStart Hook 中提取
+SESSION_ID=$(echo "$CONTEXT" | jq -r '.sessionId')
+# 写入配置文件供后台进程使用
+echo "$SESSION_ID" > ~/.claude/current-session
+```
+
+---
+
+## 部署和使用
+
+### 安装
+
+```bash
+# 1. 安装依赖
+pip install fastapi uvicorn requests
+
+# 2. 启动本地 API 服务
+python local-api-server.py &
+
+# 3. 在 Claude Code 中启用功能
+/remote-collab enable
+```
+
+### 配置
+
+**配置文件**: `.claude/remote-collab.json`
+
+```json
+{
+  "remote_api": "https://api.example.com",
+  "local_api": "http://localhost:9988",
+  "session_id": "auto",
+  "poll_interval": 10,
+  "idle_threshold": 60,
+  "features": {
+    "memory_injection": true,
+    "message_notification": true,
+    "remote_task_execution": true
+  }
+}
+```
+
+### 使用
+
+```bash
+# 启用
+/remote-collab enable
+
+# 禁用
+/remote-collab disable
+
+# 查看状态
+/remote-collab status
+
+# 手动同步记忆
+/remote-collab sync-memory
+
+# 查看消息队列
+/remote-collab list-messages
+```
+
+---
+
+## 安全考虑
+
+1. **本地 API 认证** — 使用 token 或 API key
+2. **远程 API HTTPS** — 加密传输
+3. **会话隔离** — 不同项目使用不同会话 ID
+4. **权限控制** — 远程任务需要用户确认（可配置）
+
+---
+
+## 扩展性
+
+### 未来功能
+
+1. **多会话管理** — 同时管理多个 Claude Code 会话
+2. **记忆持久化** — 本地缓存记忆，减少 API 调用
+3. **智能路由** — 根据任务类型选择合适的会话
+4. **协作模式** — 多个 Claude Code 实例协同工作
+
+---
+
+## 总结
+
+本系统通过 **Skill + Hook + 后台服务** 的架构，实现了：
+
+✅ **记忆外挂** — 远程 API 提供上下文，SessionStart 时注入一次
+✅ **消息通知** — 外部消息通过 Hook 或 -p 推送到会话
+✅ **远程任务** — API 触发 Claude Code 执行编码任务
+✅ **状态感知** — Hook 追踪会话状态，避免并发冲突
+✅ **Token 优化** — 记忆仅注入一次，消息按需通知
+
+**核心价值**: Claude Code 成为可远程调用、具备记忆能力的智能编码引擎。