@agentunion/kite 1.5.0 → 1.6.1

package/docs/logs-api-guide.md

@@ -0,0 +1,42 @@
+# Logs 模块 API 使用说明
+
+端口：18771
+
+所有接口支持 `purpose` 参数（可选），记录到 `api_calls.jsonl`。URL 中文需编码。
+
+## API 端点
+
+**列出文件** `GET /api/logs/files`
+
+**变更记录** `GET /api/logs/changes` — 只输出变更的文件
+
+**搜索日志** `GET /api/logs/search?keyword=ERROR&module=launcher&limit=50`
+- `module` — 模块名
+- `mentioned` — 提到的模块（在 [] 内）
+- `keyword` — 关键词或正则
+- `from` / `to` — 时间（`HH:MM` 或 `MM-DD HH:MM` 或 `YYYY-MM-DD HH:MM`）
+- `lines` — 行范围（`1000-2000`）
+- `limit` — 返回数量（默认 100）
+- `include_archive` — 搜索归档（默认 false）
+
+默认搜当前日志，启用 `include_archive` 搜归档。自动去重。
+
+**清理日志** `DELETE /api/logs/cleanup?modules=launcher&before=03-01&dry_run=true`
+- `modules` — 模块列表（必填）
+- `types` — 文件类型（archive/crashes）
+- `before` — 删除此日期之前（`MM-DD`）
+- `dry_run` — 预览模式（默认 true）
+
+**使用说明** `GET /api/logs/help`
+
+## 日志文件
+
+- `latest.log` — 当前运行（启动清空）
+- `crashes.jsonl` — 崩溃记录（启动清空）
+- `api_calls.jsonl` — API 调用记录（追加）
+- `{YYYY-MM}/{YYYY-MM-DD}.log` — 按日归档
+- `registry_test.log` — 注册测试（覆盖）
+
+多实例用 `~N` 后缀（如 `latest~2.log`）。
+
+路径：`{KITE_INSTANCE_DIR}/{module_name}/log/`

package/docs/npm/345/214/205Python/347/216/257/345/242/203/347/256/241/347/220/206/346/226/271/346/241/210.md

@@ -0,0 +1,302 @@
+# npm 包 Python 环境管理方案
+
+## 概述
+
+通过 npm 包自动管理 Python 环境，用户只需 `npm install @agentunion/kite` 即可完成所有准备工作。
+
+## 设计原则
+
+### 1. 环境隔离在 KITE_DATA
+
+所有 Python 相关文件安装在用户目录，避免权限问题：
+
+```
+~/.kite/                          ← KITE_DATA
+├── python/                       ← Python 安装目录（如果系统没有）
+│   ├── python.exe
+│   └── ...
+├── venv/                         ← 虚拟环境
+│   ├── Scripts/ (Windows)
+│   ├── Lib/site-packages/
+│   └── pyvenv.cfg
+├── versions/                     ← 框架代码（按版本）
+│   └── 1.4.0/
+│       ├── main.py
+│       ├── launcher/
+│       └── ...
+├── modules/                      ← 用户模块
+└── workspace/                    ← 运行时数据
+
+node_modules/@agentunion/kite/    ← npm 包（只读代码）
+├── package.json
+├── cli.js
+├── scripts/
+│   ├── setup-python-env.js       ← postinstall 脚本
+│   └── python-env.js             ← 环境工具
+└── ...
+```
+
+### 2. 自动化流程
+
+```
+npm install @agentunion/kite
+    ↓
+postinstall 钩子执行
+    ↓
+scripts/setup-python-env.js
+    ↓
+1. 检测系统 Python 3.8+
+2. 如果没有 → 下载 Python embeddable (仅 Windows)
+3. 创建虚拟环境 ~/.kite/venv/
+4. 安装 requirements.txt 依赖
+    ↓
+完成！用户可以运行 kite start
+```
+
+## 实现文件
+
+### 1. package.json
+
+```json
+{
+  "name": "@agentunion/kite",
+  "version": "1.4.0",
+  "scripts": {
+    "postinstall": "node scripts/setup-python-env.js"
+  },
+  "files": [
+    "cli.js",
+    "main.py",
+    "requirements.txt",
+    "scripts/**",
+    "core/**",
+    "launcher/**",
+    "kernel/**",
+    "extensions/**"
+  ]
+}
+```
+
+### 2. scripts/setup-python-env.js
+
+**功能：**
+- 检测系统 Python（python3 / python）
+- 版本检查（需要 3.8+）
+- 如果没有 Python：
+  - Windows：下载 Python embeddable 到 `~/.kite/python/`
+  - Linux/macOS：提示用户手动安装
+- 创建虚拟环境到 `~/.kite/venv/`
+- 安装 requirements.txt 依赖
+
+**关键逻辑：**
+```javascript
+// 检测系统 Python
+function detectSystemPython() {
+  for (const cmd of ['python3', 'python']) {
+    try {
+      const version = execSync(`${cmd} --version`);
+      if (version >= 3.8) return cmd;
+    } catch {}
+  }
+  return null;
+}
+
+// 下载 Python (仅 Windows)
+async function downloadPython() {
+  const url = 'https://www.python.org/ftp/python/3.11.9/python-3.11.9-embed-amd64.zip';
+  const installPath = path.join(os.homedir(), '.kite', 'python');
+  // 下载 + 解压
+}
+
+// 创建虚拟环境
+function createVenv(pythonCmd) {
+  const venvPath = path.join(os.homedir(), '.kite', 'venv');
+  execSync(`${pythonCmd} -m venv "${venvPath}"`);
+}
+
+// 安装依赖
+function installPythonDeps() {
+  const pip = path.join(os.homedir(), '.kite', 'venv', 'Scripts', 'pip.exe');
+  execSync(`"${pip}" install -r requirements.txt`);
+}
+```
+
+### 3. scripts/python-env.js
+
+**功能：**
+提供工具函数，供 cli.js 使用
+
+```javascript
+module.exports = {
+  getKiteDataPath,      // ~/.kite/
+  getVenvPath,          // ~/.kite/venv/
+  getVenvPython,        // ~/.kite/venv/Scripts/python.exe
+  getVenvPip,           // ~/.kite/venv/Scripts/pip.exe
+  venvExists,           // 检查虚拟环境是否存在
+  isPythonReady         // 检查 Python 环境是否就绪
+};
+```
+
+### 4. cli.js（已修改）
+
+**变更：**
+```javascript
+// 旧代码
+const python = process.platform === 'win32' ? 'python' : 'python3';
+
+// 新代码
+const { getVenvPython, isPythonReady } = require('./scripts/python-env');
+
+if (!isPythonReady()) {
+  console.error('Python 环境未就绪，请运行: npm install');
+  process.exit(1);
+}
+
+const python = getVenvPython();
+```
+
+## 用户体验
+
+### 安装
+
+```bash
+npm install -g @agentunion/kite
+```
+
+**输出：**
+```
+[Kite Setup] 开始准备 Python 环境...
+[Kite Setup] 检测到系统 Python: Python 3.11.5
+[Kite Setup] 正在创建虚拟环境...
+[Kite Setup] 虚拟环境已创建: C:\Users\xxx\.kite\venv
+[Kite Setup] 正在安装 Python 依赖...
+[Kite Setup] Python 依赖安装完成
+[Kite Setup] Python 环境准备完成！
+[Kite Setup] 虚拟环境路径: C:\Users\xxx\.kite\venv
+```
+
+### 启动
+
+```bash
+kite start
+```
+
+**自动使用虚拟环境的 Python**，无需用户手动激活。
+
+## 跨平台兼容性
+
+### Windows
+
+- ✅ 自动检测系统 Python
+- ✅ 如果没有，下载 Python embeddable
+- ✅ 创建虚拟环境
+- ✅ 安装依赖
+
+### Linux / macOS
+
+- ✅ 自动检测系统 Python
+- ⚠️ 如果没有，提示用户安装（不支持自动下载）
+- ✅ 创建虚拟环境
+- ✅ 安装依赖
+
+**Linux/macOS 安装 Python：**
+```bash
+# Ubuntu/Debian
+sudo apt install python3 python3-venv python3-pip
+
+# macOS
+brew install python3
+```
+
+## 优势
+
+1. **用户无感知**：只需 `npm install`，自动准备环境
+2. **环境隔离**：所有文件在 `~/.kite/`，不污染系统
+3. **无需权限**：不需要管理员权限
+4. **跨版本共享**：多个 Kite 版本共享同一个虚拟环境
+5. **自动更新**：重新 `npm install` 会自动更新依赖
+
+## 故障排查
+
+### 问题：postinstall 失败
+
+**原因**：网络问题或 Python 下载失败
+
+**解决**：
+```bash
+# 手动运行 setup 脚本
+node node_modules/@agentunion/kite/scripts/setup-python-env.js
+```
+
+### 问题：虚拟环境创建失败
+
+**原因**：系统 Python 没有 venv 模块
+
+**解决**：
+```bash
+# Ubuntu/Debian
+sudo apt install python3-venv
+
+# 或使用 virtualenv
+pip install virtualenv
+```
+
+### 问题：依赖安装失败
+
+**原因**：pip 版本过旧或网络问题
+
+**解决**：
+```bash
+# 升级 pip
+~/.kite/venv/Scripts/pip.exe install --upgrade pip
+
+# 使用国内镜像
+~/.kite/venv/Scripts/pip.exe install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+### 问题：kite 命令找不到 Python
+
+**原因**：虚拟环境未正确创建
+
+**解决**：
+```bash
+# 删除虚拟环境重新创建
+rm -rf ~/.kite/venv
+npm install -g @agentunion/kite --force
+```
+
+## 开发测试
+
+### 本地测试 postinstall
+
+```bash
+cd Kite
+node scripts/setup-python-env.js
+```
+
+### 测试 CLI
+
+```bash
+node cli.js start
+```
+
+### 清理环境
+
+```bash
+rm -rf ~/.kite/venv
+rm -rf ~/.kite/python
+```
+
+## 未来改进
+
+1. **支持 Python 版本选择**：允许用户指定 Python 版本
+2. **依赖缓存**：加速重复安装
+3. **离线安装包**：提供包含 Python 的离线安装包
+4. **自动更新检测**：检测依赖变更，自动重新安装
+5. **多环境支持**：支持开发/生产环境切换
+
+## 参考
+
+- Python embeddable: https://www.python.org/downloads/windows/
+- npm postinstall: https://docs.npmjs.com/cli/v9/using-npm/scripts
+- Python venv: https://docs.python.org/3/library/venv.html

package/docs/npm/345/217/221/345/270/203/344/270/216CLI/344/275/277/347/224/250/346/214/207/345/215/227.md

@@ -0,0 +1,245 @@
+# Kite npm 发布与 CLI 使用指南
+
+## 概述
+
+Kite 通过 npm 发布为全局命令行工具，安装后可在任意目录执行 `kite` 命令启动框架。
+
+npm 包名：`@agentunion/kite`
+
+---
+
+## 一、工程中的支持文件
+
+### 1. package.json
+
+npm 包的核心配置文件，关键字段：
+
+```json
+{
+  "name": "@agentunion/kite",     // scoped 包名，@agentunion 是 npm 用户名
+  "version": "1.0.6",
+  "bin": {
+    "kite": "./cli.js"            // 声明全局命令 kite 对应 cli.js
+  },
+  "files": [                      // 发布时包含的文件
+    "cli.js",
+    "main.py",
+    "__main__.py",
+    "__init__.py",
+    "core/**",
+    "extensions/**"
+  ]
+}
+```
+
+- `name`：`@agentunion/kite` 是 scoped 包名，`@agentunion` 是 npm 用户名作为 scope，保证全局唯一
+- `bin`：告诉 npm "安装后创建一个叫 `kite` 的全局命令，指向 `cli.js`"
+- `files`：控制哪些文件会被打包发布到 npm registry，避免发布无关文件
+
+### 2. cli.js
+
+Node.js CLI 入口脚本，是 `kite` 命令的实际执行体。职责：
+
+1. 解析命令行参数（支持 `--cwd` 指定工作目录、`--use` 指定版本）
+2. 首次运行时将框架代码复制到 `~/.kite/versions/{ver}/`
+3. 设置环境变量（`KITE_PROJECT`、`KITE_CWD`、`KITE_WORKSPACE`、`KITE_DATA` 等，详见 [环境变量与运行时目录设计](环境变量与运行时目录设计.md)）
+4. 用 `spawn` 启动 Python 子进程执行 `main.py`
+5. 转发信号（Ctrl+C）实现优雅退出
+
+```
+cli.js 本身不做任何 Launcher 逻辑，它只是一个"启动 Python 的薄壳"。
+```
+
+### 3. __main__.py / __init__.py
+
+支持 Python 包模式启动：
+
+```bash
+python -m Kite    # 从 Kite 的父目录执行
+```
+
+`__main__.py` 的作用等同于 `main.py`，只是让 Python 的 `-m` 机制能找到入口。
+
+
+---
+
+## 二、发布流程
+
+### 前置条件
+
+- 安装 Node.js（>= 16）
+- 注册 npm 账号：https://www.npmjs.com/signup
+
+### 步骤
+
+#### 1. 登录 npm
+
+```bash
+npm login
+```
+
+会跳转浏览器完成认证。登录成功后 token 自动保存在 `~/.npmrc`。
+
+验证登录状态：
+
+```bash
+npm whoami
+# 输出: agentunion
+```
+
+#### 2. 检查发布内容
+
+```bash
+cd Kite
+npm pack --dry-run
+```
+
+列出将被打包的文件，确认没有敏感文件（密钥、.env 等）。
+
+#### 3. 发布
+
+```bash
+npm publish --access public
+```
+
+`--access public` 是必须的，因为 scoped 包（`@agentunion/xxx`）默认是私有的（需付费），加此参数免费公开发布。
+
+如果账号启用了 2FA，有两种方式处理：
+
+- 方式 A：使用 authenticator app 生成 OTP
+  ```bash
+  npm publish --access public --otp=123456
+  ```
+- 方式 B：在 npm 网站创建 Granular Access Token（勾选 Bypass 2FA），token 会自动写入 `~/.npmrc`
+
+#### 4. 更新版本
+
+每次修改代码后需要升版本才能重新发布：
+
+```bash
+npm version patch    # 1.0.6 → 1.0.7（小修复）
+npm version minor    # 1.0.6 → 1.1.0（新功能）
+npm version major    # 1.0.6 → 2.0.0（大改动）
+
+npm publish --access public
+```
+
+---
+
+## 三、安装流程
+
+### 全局安装
+
+```bash
+npm install -g @agentunion/kite
+```
+
+npm 执行以下操作：
+
+1. 从 registry 下载 `@agentunion/kite` 包
+2. 解压到全局 node_modules 目录：
+   - Linux/macOS: `/usr/local/lib/node_modules/@agentunion/kite/`
+   - Windows: `%APPDATA%\npm\node_modules\@agentunion\kite\`
+3. 读取 `package.json` 的 `bin` 字段
+4. 在全局 bin 目录创建可执行入口：
+   - Linux/macOS: `/usr/local/bin/kite` → symlink 到 `cli.js`
+   - Windows: `%APPDATA%\npm\kite.cmd`（内容为 `node "...\cli.js" %*`）
+
+### 本地开发安装
+
+```bash
+cd Kite
+npm link
+```
+
+效果与全局安装相同，但通过 symlink 指向本地源码，修改代码后立即生效。
+
+---
+
+## 四、kite 命令执行原理
+
+### 为什么任意目录都能执行
+
+全局 bin 目录（如 `%APPDATA%\npm\`）已在系统 PATH 中，shell 在任何目录都能找到 `kite` 命令。
+
+### 完整执行链
+
+```
+用户在 D:\any-dir> 输入 kite
+  │
+  ▼ shell 在 PATH 中查找
+全局 bin 目录下的 kite.cmd (Windows) 或 kite symlink (Linux/macOS)
+  │
+  ▼ 等价于执行
+node "/path/to/node_modules/@agentunion/kite/cli.js"
+  │
+  ▼ cli.js 执行
+fs.realpathSync(__dirname)
+  → 解析 symlink，得到 Kite 框架真实安装路径
+  │
+  ▼ 设置环境变量
+KITE_PROJECT   = ~/.kite/versions/{ver}/（框架代码目录）
+KITE_CWD       = 用户执行 kite 命令时所在的目录
+KITE_WORKSPACE = ~/.kite/workspace/
+KITE_DATA      = ~/.kite/data/
+KITE_MODULES   = ~/.kite/modules/
+KITE_REPO      = ~/.kite/repo/
+KITE_VERSION   = 版本号
+KITE_ENV       = production
+  │
+  ▼ spawn 子进程
+python main.py
+  cwd: KITE_PROJECT（Python 工作目录 = 框架目录）
+  stdio: 'inherit'（输出直接打到用户终端）
+  │
+  ▼ Python Launcher 启动
+与直接执行 python main.py 完全一样的流程
+```
+
+### 进程模型
+
+```
+kite 命令
+  └─ Node.js 进程 (cli.js)        ← 守护壳，几乎零开销
+       └─ Python 进程 (Launcher)   ← 实际工作进程
+            ├─ Registry 子进程
+            ├─ Event Hub 子进程
+            ├─ Watchdog 子进程
+            └─ ... 其他模块
+```
+
+Node.js 进程在 Python 退出后自动退出，返回相同的 exit code。
+Ctrl+C 信号由 Node.js 捕获并转发给 Python，实现优雅退出。
+
+### 路径说明
+
+| 变量 | 含义 | 生产环境示例 |
+|------|------|------|
+| `KITE_PROJECT` | 框架代码目录 | `~/.kite/versions/1.0.6/` |
+| `KITE_CWD` | 用户执行命令时的目录 | `/home/user/my-project` |
+| `KITE_WORKSPACE` | 工作区根路径 | `~/.kite/workspace/` |
+| `KITE_DATA` | 用户数据路径 | `~/.kite/data/` |
+| `KITE_MODULES` | 扩展模块路径 | `~/.kite/modules/` |
+| `KITE_REPO` | 仓库路径 | `~/.kite/repo/` |
+| `KITE_VERSION` | 当前版本 | `1.0.6` |
+| `KITE_ENV` | 运行环境 | `production` |
+
+完整环境变量定义见 [环境变量与运行时目录设计](环境变量与运行时目录设计.md)。
+
+支持 `--cwd` 参数覆盖用户目录：
+
+```bash
+kite --cwd /data/my-project
+```
+
+---
+
+## 五、所有启动方式汇总
+
+| 方式 | 命令 | 适用场景 |
+|------|------|---------|
+| Python 脚本 | `python main.py` | 本地开发，在 Kite 目录下 |
+| Python 包 | `python -m Kite` | 本地开发，在 Kite 父目录下 |
+| Node.js 直接 | `node cli.js` | 本地开发，在 Kite 目录下 |
+| npm 全局安装 | `npm install -g @agentunion/kite` → `kite` | 生产部署，任意目录 |
+| npm link | `cd Kite && npm link` → `kite` | 本地开发，任意目录 |