@agentunion/kite 1.5.0 → 1.6.0

package/docs//344/272/244/344/272/222/345/274/217/347/273/210/347/253/257/346/216/247/345/210/266/346/226/271/346/241/210.md

@@ -0,0 +1,301 @@
+# 交互式终端控制方案
+
+## 需求
+
+启动交互式命令行程序（如 Claude Code），并通过代码读取输出和发送输入。
+
+## 核心挑战
+
+### TTY 检测问题
+
+许多交互式 CLI 工具会检查是否运行在真实终端中：
+
+```python
+import sys
+if not sys.stdin.isatty():
+    print("Error: Must run in a terminal")
+    exit(1)
+```
+
+**检测方法**：
+- `sys.stdin.isatty()` / `sys.stdout.isatty()` (Python)
+- `process.stdin.isTTY` / `process.stdout.isTTY` (Node.js)
+- `isatty(STDIN_FILENO)` (C/C++)
+
+**绕过方法**：使用伪终端（PTY）模拟真实终端环境。
+
+---
+
+## 技术方案
+
+### 方案 1：ptyprocess（跨平台，推荐）
+
+**优点**：
+- 跨平台（Linux/macOS/Windows）
+- API 简单
+- 自动处理 TTY 模拟
+
+**缺点**：
+- Windows 支持依赖 `winpty`
+- 需要额外安装依赖
+
+**安装**：
+```bash
+pip install ptyprocess
+# Windows 额外需要
+pip install pywinpty
+```
+
+**基础用法**：
+```python
+import ptyprocess
+
+# 启动程序
+process = ptyprocess.PtyProcess.spawn(['claude', 'code'])
+
+# 读取输出
+output = process.read(1024)
+print(output.decode())
+
+# 发送输入
+process.write(b'help\n')
+
+# 关闭
+process.terminate()
+```
+
+---
+
+### 方案 2：pexpect / wexpect（功能强大）
+
+**优点**：
+- 支持模式匹配（等待特定输出）
+- 支持交互模式
+- 丰富的控制 API
+
+**缺点**：
+- Linux/macOS 用 `pexpect`，Windows 用 `wexpect`（需分平台处理）
+
+**安装**：
+```bash
+# Linux/macOS
+pip install pexpect
+
+# Windows
+pip install wexpect
+```
+
+**基础用法**：
+```python
+import pexpect  # Linux/macOS
+# import wexpect as pexpect  # Windows
+
+# 启动并等待提示符
+child = pexpect.spawn('claude code')
+child.expect('>')  # 等待特定输出
+
+# 发送命令
+child.sendline('help')
+child.expect('>')
+
+# 读取输出
+print(child.before.decode())
+```
+
+---
+
+### 方案 3：subprocess + winpty（Windows 专用）
+
+**仅适用于 Windows**，直接使用 `winpty` 包装：
+
+```python
+import winpty
+
+pty = winpty.PtyProcess.spawn('claude.exe code')
+pty.write('help\r\n')
+output = pty.read()
+```
+
+---
+
+## TTY 检测绕过原理
+
+### 为什么 PTY 能绕过检测？
+
+PTY（伪终端）在内核层面模拟真实终端设备：
+
+```
+程序 ←→ PTY Slave (/dev/pts/X) ←→ PTY Master ←→ 控制代码
+```
+
+- **程序视角**：stdin/stdout 连接到 `/dev/pts/X`，`isatty()` 返回 `True`
+- **控制代码视角**：通过 PTY Master 读写数据
+
+### 常见 TTY 检测方法及应对
+
+| 检测方法 | PTY 是否通过 | 备注 |
+|---------|-------------|------|
+| `isatty()` | ✅ 通过 | PTY Slave 是真实 TTY 设备 |
+| `tcgetattr()` | ✅ 通过 | PTY 支持终端属性查询 |
+| `ioctl(TIOCGWINSZ)` | ✅ 通过 | PTY 支持窗口大小查询 |
+| 检查 `$TERM` 环境变量 | ⚠️ 需设置 | 默认继承父进程，可手动设置 |
+| 检查 SSH 连接 | ✅ 通过 | PTY 不涉及网络 |
+
+### 设置终端环境变量
+
+```python
+import os
+os.environ['TERM'] = 'xterm-256color'  # 模拟常见终端类型
+```
+
+---
+
+## 推荐实现架构
+
+### 核心类设计
+
+```python
+class InteractiveTerminal:
+    def __init__(self, command: list[str]):
+        """启动交互式终端"""
+
+    def read(self, timeout: float = 1.0) -> str:
+        """读取输出（非阻塞）"""
+
+    def write(self, text: str):
+        """发送输入"""
+
+    def expect(self, pattern: str, timeout: float = 10.0) -> str:
+        """等待特定输出模式"""
+
+    def close(self):
+        """关闭终端"""
+```
+
+### 异步读取设计
+
+使用后台线程持续读取输出，避免阻塞：
+
+```python
+import threading
+import queue
+
+class InteractiveTerminal:
+    def __init__(self, command):
+        self.process = ptyprocess.PtyProcess.spawn(command)
+        self.output_queue = queue.Queue()
+        self.running = True
+
+        # 启动读取线程
+        self.reader = threading.Thread(target=self._read_loop, daemon=True)
+        self.reader.start()
+
+    def _read_loop(self):
+        while self.running:
+            try:
+                data = self.process.read(1024)
+                self.output_queue.put(data)
+            except EOFError:
+                break
+
+    def read(self, timeout=1.0):
+        try:
+            return self.output_queue.get(timeout=timeout)
+        except queue.Empty:
+            return b''
+```
+
+---
+
+## 集成到 Kite 的建议
+
+### 模块结构
+
+```
+extensions/services/interactive_shell/
+├── entry.py          # 模块入口
+├── terminal.py       # InteractiveTerminal 类
+├── rpc_methods.py    # RPC 方法定义
+└── module.json5      # 模块配置
+```
+
+### RPC 接口设计
+
+```json
+{
+  "shell.spawn": {
+    "params": {
+      "command": ["claude", "code"],
+      "env": {"TERM": "xterm-256color"}
+    },
+    "returns": "session_id"
+  },
+  "shell.write": {
+    "params": {
+      "session_id": "xxx",
+      "text": "help\n"
+    }
+  },
+  "shell.read": {
+    "params": {
+      "session_id": "xxx",
+      "timeout": 1.0
+    },
+    "returns": "output_text"
+  },
+  "shell.close": {
+    "params": {
+      "session_id": "xxx"
+    }
+  }
+}
+```
+
+### 事件推送
+
+当有新输出时，通过 Kernel 推送事件：
+
+```json
+{
+  "type": "shell.output",
+  "data": {
+    "session_id": "xxx",
+    "output": "Welcome to Claude Code\n"
+  }
+}
+```
+
+---
+
+## 测试计划
+
+### 测试目标
+
+1. 验证 PTY 能绕过 Claude Code 的 TTY 检测
+2. 验证能正常读取输出和发送输入
+3. 验证跨平台兼容性（Windows/Linux/macOS）
+
+### 测试步骤
+
+1. 创建独立测试模块 `test_interactive_shell/`
+2. 实现基础 `InteractiveTerminal` 类
+3. 测试启动 `claude code` 并发送 `help` 命令
+4. 测试异步读取输出
+5. 测试多会话并发
+
+---
+
+## 依赖项
+
+```txt
+ptyprocess>=0.7.0
+pywinpty>=2.0.0; sys_platform == 'win32'
+```
+
+---
+
+## 参考资料
+
+- [ptyprocess 文档](https://ptyprocess.readthedocs.io/)
+- [pexpect 文档](https://pexpect.readthedocs.io/)
+- [Linux PTY 原理](https://man7.org/linux/man-pages/man7/pty.7.html)

package/docs//344/273/243/347/220/206/345/220/257/345/212/250/345/231/250/344/270/216/345/256/271/345/231/250/345/214/226.md

@@ -0,0 +1,140 @@
+# 代理启动器与容器化
+
+## 1. 概述
+
+代理启动器（Proxy Launcher）是一个扩展模块，负责：
+- 连接远程主节点的 Registry 和 Event Hub
+- 接收主节点指令，在本地启停模块
+- 支持容器化运行模式（Docker）
+
+代理启动器**不修改现有 Launcher**，而是作为独立模块运行。本文档定义设计方案和当前框架需要的配套改动。
+
+## 2. 分布式部署架构
+
+```
+┌──────────────────────────────┐
+│        主节点 (Master)        │
+│  Launcher                    │
+│  ├─ Registry   (0.0.0.0)    │
+│  ├─ Event Hub  (0.0.0.0)    │
+│  ├─ Kernel                   │
+│  └─ 本地模块...              │
+└──────────────┬───────────────┘
+               │ HTTP / WebSocket
+       ┌───────┼───────┐
+       │               │
+┌──────▼─────┐  ┌──────▼─────┐
+│  从节点 A   │  │  从节点 B   │
+│  Proxy      │  │  Proxy      │
+│  Launcher   │  │  Launcher   │
+│  ├─ 模块1   │  │  ├─ 模块3   │
+│  └─ 模块2   │  │  └─ 模块4   │
+└────────────┘  └────────────┘
+```
+
+## 3. 代理启动器（Proxy Launcher）
+
+### 3.1 职责
+
+- 启动时连接主节点 Registry，注册自身
+- 连接主节点 Event Hub，订阅管理事件
+- 扫描本地 `extensions/` 目录的模块
+- 接收主节点指令（通过事件或 API），启停本地模块
+- 本地模块注册到主节点 Registry 时使用本机外网 IP
+
+### 3.2 配置
+
+代理启动器通过 boot_info 或本地配置获取主节点信息：
+
+```yaml
+proxy:
+  master_registry: "http://192.168.1.1:52340"
+  master_event_hub: "ws://192.168.1.1:52341/ws"
+  advertise_ip: "192.168.1.10"
+```
+
+### 3.3 与主 Launcher 的区别
+
+| 项目 | 主 Launcher | 代理启动器 |
+|------|------------|-----------|
+| 启动 Registry | 是 | 否（连接远程） |
+| 启动 Event Hub | 是 | 否（连接远程） |
+| 进程管理 | 是 | 是 |
+| API 接口 | 完整 | 相同（供主节点远程调用） |
+| 模块注册 endpoint | 127.0.0.1 | advertise_ip |
+
+## 4. 容器化运行模式
+
+代理启动器支持以 Docker 容器方式运行模块。
+
+### 4.1 module.md 扩展
+
+```yaml
+runtime: docker
+docker:
+  image: "mymodule:latest"
+  build: true
+  dockerfile: "Dockerfile"
+  ports:
+    - "0:8080"
+  volumes:
+    - "./data:/app/data"
+  network: "host"
+```
+
+### 4.2 容器生命周期
+
+```
+start: docker run → 传递 BOOT_INFO 环境变量 → 启动 stdout 日志线程
+stop:  docker stop -t {timeout} → docker rm
+check: docker inspect --format='{{.State.Running}}'
+```
+
+### 4.3 boot_info 传递
+
+容器模式下 stdin pipe 不可用，改用环境变量 `BOOT_INFO`（JSON 字符串）。模块公共启动库需同时支持 stdin 和环境变量两种读取方式。
+
+## 5. 当前框架需要的配套改动
+
+以下改动为未来分布式部署和容器化做准备，**现在就需要实现**。
+
+### 5.1 Registry 绑定地址可配置
+
+当前 Registry 硬编码绑定 `127.0.0.1`，需改为从配置读取：
+
+```yaml
+registry:
+  bind: "127.0.0.1"   # 默认本地，分布式部署时改为 "0.0.0.0"
+```
+
+### 5.2 Event Hub 绑定地址可配置
+
+同上：
+
+```yaml
+event_hub:
+  bind: "127.0.0.1"   # 默认本地
+```
+
+### 5.3 模块注册 endpoint 支持 advertise_ip
+
+当前模块注册时 `base_url` 固定使用 `127.0.0.1`。需支持配置：
+
+```yaml
+launcher:
+  advertise_ip: "127.0.0.1"  # 默认本地，分布式时改为外网 IP
+```
+
+Launcher 将 `advertise_ip` 写入 boot_info，模块用此 IP 构造注册地址。
+
+### 5.4 Launcher API 认证
+
+分布式部署时 API 暴露到网络，需增加 token 认证：
+
+- 请求头 `Authorization: Bearer {kite_token}`
+- 单机模式默认关闭，保持向后兼容
+
+```yaml
+launcher:
+  api_auth: false  # 分布式部署时开启
+```

package/docs//344/273/243/347/240/201/347/273/237/350/256/241/345/267/245/345/205/267/344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -0,0 +1,217 @@
+# 代码统计工具使用说明
+
+## 功能
+
+自动统计 Kite 项目的代码行数，并记录历史变化趋势。
+
+**每次启动 Kite 时会自动在后台统计代码行数并记录。**
+
+**新增特性**：
+- ✅ 文件级缓存机制 — 只统计修改过的文件，大幅提升速度
+- ✅ 防御性排除目录 — 自动排除构建产物、缓存、备份等目录
+
+## 使用方法
+
+### 1. 自动统计（推荐）
+
+每次启动 Kite 时会自动统计：
+```bash
+python main.py
+```
+
+统计在后台静默执行，不影响启动速度。
+
+### 2. 手动统计并查看结果
+
+```bash
+python main.py --count-lines
+```
+
+输出示例：
+```
+==================================================
+Kite 项目代码统计
+==================================================
+Python 代码:        63,533 行
+JavaScript 代码:    12,011 行
+Markdown 文档:      38,260 行
+YAML 配置:             298 行
+JSON 配置:           2,383 行
+--------------------------------------------------
+总计:              116,485 行
+缓存命中率:       99.8% (421/422)
+==================================================
+```
+
+### 3. 查看历史记录
+
+```bash
+python launcher/count_lines.py --history
+```
+
+或简写：
+```bash
+python launcher/count_lines.py -h
+```
+
+输出示例：
+```
+================================================================================
+历史记录（最近 10 次）
+================================================================================
+时间                            Python         JS         MD         总计         变化
+--------------------------------------------------------------------------------
+2026-03-09 01:49:15           63,184     19,467     35,767    119,413          -
+2026-03-09 02:13:29           63,241     19,231     37,166    120,633     +1,220
+2026-03-09 08:09:51           63,241     12,018     38,260    114,514     -6,895
+================================================================================
+```
+
+## 统计范围
+
+### 包含的文件类型
+
+- **Python 代码**: `*.py`
+- **JavaScript 代码**: `*.js`
+- **Markdown 文档**: `*.md`
+- **YAML 配置**: `*.yaml`, `*.yml`
+- **JSON 配置**: `*.json` (排除 package-lock.json)
+
+### 排除的目录（防御性措施）
+
+**Python 相关**:
+- `__pycache__/` - Python 字节码缓存
+- `.venv/`, `venv/` - Python 虚拟环境
+- `.pytest_cache/` - pytest 缓存
+- `.mypy_cache/` - mypy 类型检查缓存
+- `.tox/` - tox 测试环境
+- `.eggs/`, `*.egg-info/` - Python 包构建产物
+
+**JavaScript 相关**:
+- `node_modules/` - Node.js 依赖
+
+**构建产物**:
+- `dist/` - 分发目录
+- `build/` - 构建目录
+
+**版本控制**:
+- `.git/` - Git 仓库
+- `.svn/` - SVN 仓库
+- `.hg/` - Mercurial 仓库
+
+**IDE 配置**:
+- `.idea/` - JetBrains IDE
+- `.vscode/` - Visual Studio Code
+
+**项目特定**:
+- `.dev/` - 开发相关（变更日志、发布备份）
+- `.claude/` - Claude 工作目录
+
+## 缓存机制
+
+### 工作原理
+
+统计工具会记录每个文件的最后修改时间（mtime）和行数，下次统计时：
+- 如果文件未修改（mtime 相同）→ 直接使用缓存结果
+- 如果文件已修改（mtime 不同）→ 重新统计并更新缓存
+
+### 缓存文件位置
+
+```
+data/stats/cache.json
+```
+
+缓存格式：
+```json
+{
+  "main.py": {
+    "mtime": 1772939347.424227,
+    "lines": 21
+  },
+  "launcher/entry.py": {
+    "mtime": 1772992618.5103776,
+    "lines": 1234
+  }
+}
+```
+
+### 性能提升
+
+- **首次统计**: 需要读取所有文件（~2-3 秒）
+- **后续统计**: 只读取修改过的文件（~0.5-1 秒）
+- **缓存命中率**: 通常 >99%（只有少数文件被修改）
+
+## 数据存储
+
+统计记录保存在：
+```
+data/stats/lines.jsonl
+```
+
+每次统计会追加一条 JSONL 记录：
+```json
+{
+  "timestamp": "2026-03-09T08:36:13.123456",
+  "stats": {
+    "python": 63533,
+    "javascript": 12011,
+    "markdown": 38260,
+    "yaml": 298,
+    "json": 2383,
+    "total": 116485
+  }
+}
+```
+
+## 建议使用频率
+
+**自动统计**: 每次启动 Kite 时自动记录（已默认启用）
+
+**手动查看**:
+- **查看历史**: 随时运行 `python launcher/count_lines.py --history`
+- **详细统计**: 需要看详细数据时运行 `python main.py --count-lines`
+
+## 示例工作流
+
+```bash
+# 正常启动（自动统计）
+python main.py
+
+# 一段时间后，查看代码变化趋势
+python launcher/count_lines.py --history
+
+# 需要详细数据时
+python main.py --count-lines
+```
+
+## 注意事项
+
+1. **统计速度**: 首次统计需要 2-3 秒，后续统计 <1 秒（缓存加速）
+2. **文件编码**: 使用 UTF-8 编码，忽略无法解码的文件
+3. **空行计数**: 包含空行和注释行
+4. **历史记录**: 无限制保存，可手动清理 `data/stats/lines.jsonl`
+5. **缓存清理**: 如需重新统计所有文件，删除 `data/stats/cache.json`
+
+## 当前项目统计 (2026-03-09)
+
+```
+Python 代码:        63,533 行
+JavaScript 代码:    12,011 行
+Markdown 文档:      38,260 行
+YAML 配置:             298 行
+JSON 配置:           2,383 行
+--------------------------------------------------
+总计:              116,485 行
+```
+
+### 代码分布
+
+**核心模块**:
+- `extensions/services/` — 48,005 行 Python（主要业务逻辑）
+- `launcher/` — 4,663 行 Python
+- `kite_cli/` — 3,618 行 Python
+- `kernel/` — 2,343 行 Python
+- 根目录 — 926 行 Python（main.py 等）
+
+**文档**:
+- 设计文档、API 文档、使用说明等 — 38,260 行 Markdown