@agentunion/kite 1.5.0 → 1.6.0

package/docs//347/216/257/345/242/203/345/217/230/351/207/217/344/270/216/350/277/220/350/241/214/346/227/266/347/233/256/345/275/225/350/256/276/350/256/241.md

@@ -0,0 +1,499 @@
+# 环境变量与运行时目录设计
+
+## 概述
+
+Kite 通过环境变量统一管理运行时路径。所有环境变量在启动入口（`cli.js` 或 `main.py`）设置后，由 Launcher 传递给所有子进程，模块直接通过 `os.environ` 读取。
+
+---
+
+## 一、环境变量定义
+
+| 环境变量 | 含义 | 说明 |
+|---------|------|------|
+| `KITE_PROJECT` | 工程路径 | 框架核心代码所在目录，升级时会被覆盖 |
+| `KITE_CWD` | 用户工作目录 | 用户执行 `kite` 时所在的目录，用户产生和使用数据的地方 |
+| `KITE_WORKSPACE` | 工作区根路径 | 所有实例工作区的根目录（如 `~/.kite/workspace/`） |
+| `KITE_INSTANCE_DIR` | 实例工作区路径 | 当前实例的工作区目录，由 Launcher 从 KITE_WORKSPACE 中解析确定 |
+| `KITE_DATA` | 用户数据路径 | 跨实例共享的用户数据（身份、全局配置等） |
+| `KITE_MODULES` | 扩展模块路径 | 用户安装的扩展模块，升级不受影响 |
+| `KITE_REPO` | 仓库路径 | 版本管理备份 |
+| `KITE_VERSION` | 当前版本 | 生产环境为版本号（如 `1.0.6`），开发环境不指定 |
+| `KITE_INSTANCE` | 实例标识 | Launcher 启动时生成，用于标识当前实例 |
+| `KITE_ENV` | 运行环境 | `production` 或 `development` |
+| `KITE_DEBUG` | 调试模式 | `1` = 开启，跳过 token 验证，任何 token 放行 |
+| `KITE_REGISTRY_PORT` | Registry 端口 | Launcher 启动 Registry 后写入，子进程自动继承（见 [stdio与端口发现重构](stdio与端口发现重构.md)） |
+| `KITE_MODULE_DATA` | 模块数据目录 | 每个模块的实例级数据目录，由 Launcher 注入（`KITE_INSTANCE_DIR/{module_name}/`） |
+
+> **`KITE_WORKSPACE` 与 `KITE_INSTANCE_DIR` 的关系：** `KITE_WORKSPACE` 是工作区根路径，下面包含多个实例工作区子目录。`KITE_INSTANCE_DIR` 是 Launcher 根据 `KITE_CWD` 查找确定的当前实例工作区路径。模块写实例级数据时使用 `KITE_INSTANCE_DIR`。
+
+---
+
+## 二、数据归属划分
+
+### KITE_CWD — 用户工作目录
+
+用户执行 `kite` 时所在的目录。这是用户自己的项目目录，用户产生数据、查看数据、交付数据的地方。
+
+`KITE_CWD/.kite/` 下放置与 Kite 相关的、用户可能需要查看的文件：
+
+| 数据 | 路径 | 说明 |
+|------|------|------|
+| 忽略文件 | `KITE_CWD/.kite/ignore` | 类似 .gitignore，控制 Kite 忽略的文件 |
+| 用户日志 | `KITE_CWD/.kite/logs/` | 用户需要查看的日志 |
+| 实例配置 | `KITE_CWD/.kite/config.json` | 当前工作目录的 Kite 配置 |
+
+### KITE_INSTANCE_DIR — 实例工作区（Kite 内部数据）
+
+Kite 内部使用的工作数据，用户不需要直接查看。每个模块在实例工作区下拥有以自身名称命名的子目录，用于存放日志、运行时状态等。
+
+| 数据 | 路径 | 说明 |
+|------|------|------|
+| CWD 记录 | `KITE_INSTANCE_DIR/.cwd` | 完整的 KITE_CWD 路径 |
+| 进程记录 | `KITE_INSTANCE_DIR/launcher/state/processes.json` | 当前实例的子进程信息 |
+| 启动日志 | `KITE_INSTANCE_DIR/launcher/state/lifecycle.jsonl` | 启动/停止记录（每次启动清空） |
+| 事件 outbox | `KITE_INSTANCE_DIR/event_hub/event_outbox.jsonl` | 未确认事件 |
+| Registry 日志 | `KITE_INSTANCE_DIR/registry/` | Registry 运行时数据 |
+| 模块工作数据 | `KITE_INSTANCE_DIR/{module_name}/` | 各模块的实例级内部数据（日志、缓存等），即 `KITE_MODULE_DATA` |
+
+> **注意：** Registry 端口不再写入文件，改为通过 stdout 回传 + 环境变量 `KITE_REGISTRY_PORT` 传递。详见 [stdio与端口发现重构](stdio与端口发现重构.md)。
+
+### KITE_DATA — 用户级共享数据
+
+跨实例共享的持久数据，所有实例看到同一份。
+
+| 数据 | 路径 | 说明 |
+|------|------|------|
+| 用户身份 | `KITE_DATA/users/` | 身份层数据（profile、history） |
+| 全局配置 | `KITE_DATA/config/` | 运行时配置（runtime.yaml 等） |
+| 全局开关 | `KITE_DATA/switches.json` | 全局工具/技能开关 |
+| 联系人 | `KITE_DATA/contacts/` | 联系人数据 |
+| 模块用户数据 | `KITE_DATA/{module_name}/` | 模块的用户级持久数据 |
+
+### 判断依据
+
+```
+数据是给用户看的吗？
+├── 是 ──→ KITE_CWD/.kite/（用户可见的 Kite 文件）
+│
+└── 否（Kite 内部数据）
+    │
+    ├── 多实例间需要共享吗？
+    │   └── 是 ──→ KITE_DATA（用户级共享）
+    │
+    └── 否（实例独占）
+        └── ──→ KITE_MODULE_DATA（= KITE_INSTANCE_DIR/{module_name}/）
+```
+
+---
+
+## 三、两种启动模式
+
+### 生产环境（通过 `kite` 命令启动）
+
+`cli.js` 设置环境变量后 spawn Python 进程：
+
+```
+KITE_ENV=production
+KITE_PROJECT=~/.kite/versions/1.0.6/
+KITE_CWD=用户执行 kite 命令时所在的目录
+KITE_WORKSPACE=~/.kite/workspace/
+KITE_DATA=~/.kite/data/
+KITE_MODULES=~/.kite/modules/
+KITE_REPO=~/.kite/repo/
+KITE_VERSION=1.0.6
+```
+
+Launcher 启动后解析工作区，追加设置：
+
+```
+KITE_INSTANCE_DIR=~/.kite/workspace/project-a/（由 Launcher 解析确定）
+KITE_INSTANCE=（由 Launcher 生成）
+```
+
+### 开发环境（直接 `python main.py` 启动）
+
+`main.py` 加载 `.env` 文件后设置默认值：
+
+```
+KITE_ENV=development
+KITE_PROJECT=./（项目源码目录）
+KITE_CWD=当前执行目录
+KITE_WORKSPACE=~/.kite/workspace/
+KITE_DATA=~/.kite/data/
+KITE_MODULES=~/.kite/modules/
+KITE_REPO=~/.kite/repo/
+KITE_VERSION=（不指定）
+```
+
+Launcher 启动后同样解析工作区，追加设置 `KITE_INSTANCE_DIR` 和 `KITE_INSTANCE`。
+
+### 对比
+
+| 环境变量 | 生产环境 | 开发环境 |
+|---------|---------|---------|
+| `KITE_PROJECT` | `~/.kite/versions/1.0.6/` | `./`（源码目录） |
+| `KITE_CWD` | 用户执行目录 | 当前执行目录 |
+| `KITE_WORKSPACE` | `~/.kite/workspace/` | `~/.kite/workspace/` |
+| `KITE_INSTANCE_DIR` | （Launcher 解析） | （Launcher 解析） |
+| `KITE_DATA` | `~/.kite/data/` | `~/.kite/data/` |
+| `KITE_MODULES` | `~/.kite/modules/` | `~/.kite/modules/` |
+| `KITE_REPO` | `~/.kite/repo/` | `~/.kite/repo/` |
+| `KITE_VERSION` | `1.0.6` | （空） |
+| `KITE_ENV` | `production` | `development` |
+
+### 多实例运行
+
+在不同目录下执行 `kite`，每个实例的 `KITE_CWD` 不同，Launcher 解析到不同的实例工作区，内部数据自然隔离：
+
+```bash
+# 终端 A
+cd /home/user/project-a && kite
+# KITE_CWD=/home/user/project-a
+# KITE_INSTANCE_DIR=~/.kite/workspace/project-a/
+
+# 终端 B
+cd /home/user/project-b && kite
+# KITE_CWD=/home/user/project-b
+# KITE_INSTANCE_DIR=~/.kite/workspace/project-b/
+```
+
+两个实例共享 `KITE_DATA`（用户身份、配置），但各自的进程记录、outbox、模块日志在各自的 `KITE_INSTANCE_DIR` 下互不干扰。
+
+---
+
+## 四、目录结构
+
+```
+~/.kite/
+  ├── versions/                    ← 版本化的框架代码
+  │   ├── 1.0.6/                   ← KITE_PROJECT（生产 1.0.6）
+  │   │   ├── core/
+  │   │   ├── extensions/
+  │   │   └── main.py
+  │   └── 1.0.7/                   ← KITE_PROJECT（生产 1.0.7）
+  │
+  ├── workspace/                   ← KITE_WORKSPACE（工作区根路径）
+  │   ├── project-a/               ← KITE_INSTANCE_DIR（实例 A）
+  │   │   ├── .cwd                 ←   内容: /home/user/project-a
+  │   │   ├── launcher/
+  │   │   │   ├── state/
+  │   │   │   │   ├── processes.json
+  │   │   │   │   └── lifecycle.jsonl
+  │   │   │   └── log/
+  │   │   ├── registry/            ←   Registry 实例级数据
+  │   │   ├── event_hub/
+  │   │   │   └── event_outbox.jsonl
+  │   │   └── {module_name}/       ←   各模块实例级数据
+  │   │
+  │   ├── project-b/               ← KITE_INSTANCE_DIR（实例 B）
+  │   │   ├── .cwd                 ←   内容: /home/user/project-b
+  │   │   └── ...
+  │   │
+  │   └── project-a~1/             ← 末级目录重名时加后缀
+  │       ├── .cwd                 ←   内容: /data/work/project-a
+  │       └── ...
+  │
+  ├── data/                        ← KITE_DATA（跨实例共享）
+  │   ├── users/                   ←   用户身份层数据
+  │   ├── contacts/                ←   联系人数据
+  │   ├── config/                  ←   全局配置
+  │   ├── switches.json            ←   全局工具开关
+  │   └── {module_name}/           ←   模块用户级持久数据
+  │
+  ├── modules/                     ← KITE_MODULES（用户扩展模块）
+  │
+  └── repo/                        ← KITE_REPO（版本管理备份）
+
+/home/user/project-a/              ← KITE_CWD（用户项目目录）
+  ├── （用户自己的项目文件）
+  └── .kite/                       ← 用户可见的 Kite 文件
+      ├── ignore                   ←   忽略规则
+      ├── config.json              ←   本目录的 Kite 配置
+      └── logs/                    ←   用户可查看的日志
+```
+
+---
+
+## 五、实例工作区解析机制
+
+`KITE_WORKSPACE` 是工作区根路径，`KITE_INSTANCE_DIR` 是当前实例的工作区目录。Launcher 启动时通过以下步骤从 `KITE_CWD` 解析确定 `KITE_INSTANCE_DIR`：
+
+### 查找算法
+
+1. 取 `KITE_CWD` 的末级目录名，如 `/home/user/project-a` → `project-a`
+2. 在 `KITE_WORKSPACE` 下查找所有匹配 `project-a` 和 `project-a~{数字}` 的目录
+3. 逐个检查 `.cwd` 文件，比对完整路径：
+   - 找到 `.cwd` 内容与 `KITE_CWD` 一致的目录 → 使用该目录
+   - 未找到匹配 → 创建新目录（无后缀优先，否则递增后缀），写入 `.cwd` 文件
+4. 将解析后的目录路径设置为 `KITE_INSTANCE_DIR` 环境变量，传递给所有子进程
+
+### 参考实现
+
+```python
+def resolve_instance_dir(cwd: str, workspace_root: str) -> str:
+    """从 KITE_CWD 解析实例工作区路径。"""
+    basename = os.path.basename(cwd.rstrip(os.sep))
+    suffix = 0
+
+    while True:
+        name = basename if suffix == 0 else f"{basename}~{suffix}"
+        candidate = os.path.join(workspace_root, name)
+        cwd_file = os.path.join(candidate, ".cwd")
+
+        if not os.path.exists(candidate):
+            # 空位，创建新工作区
+            os.makedirs(candidate, exist_ok=True)
+            with open(cwd_file, "w") as f:
+                f.write(cwd)
+            return candidate
+
+        if os.path.isfile(cwd_file):
+            with open(cwd_file, "r") as f:
+                if f.read().strip() == cwd:
+                    return candidate  # 匹配，使用已有工作区
+
+        suffix += 1
+```
+
+### 示例
+
+```
+KITE_CWD=/home/user/project-a
+KITE_WORKSPACE=~/.kite/workspace/
+
+查找过程：
+  ~/.kite/workspace/project-a/.cwd → 内容 "/home/user/project-a" → 匹配！
+
+结果：
+  KITE_INSTANCE_DIR=~/.kite/workspace/project-a/
+```
+
+```
+KITE_CWD=/data/work/project-a
+KITE_WORKSPACE=~/.kite/workspace/
+
+查找过程：
+  ~/.kite/workspace/project-a/.cwd → 内容 "/home/user/project-a" → 不匹配
+  ~/.kite/workspace/project-a~1/   → 不存在 → 创建，写入 .cwd
+
+结果：
+  KITE_INSTANCE_DIR=~/.kite/workspace/project-a~1/
+```
+
+---
+
+## 六、调试模式
+
+### 启用方式
+
+通过命令行参数 `--debug` 传入：
+
+```bash
+# 生产环境
+kite --debug
+
+# 开发环境
+python main.py --debug
+```
+
+### 传递链
+
+```
+命令行参数 --debug
+    ↓
+main.py 解析参数，设置 os.environ["KITE_DEBUG"] = "1"
+    ↓
+Launcher 启动子进程（子进程继承环境变量）
+    ↓
+Registry / Event Hub / 所有模块均可读取 KITE_DEBUG
+```
+
+### 行为
+
+- `KITE_DEBUG=1` 时，token 验证逻辑对任何 token 放行
+- 模块中判断方式：
+
+```python
+import os
+
+is_debug = os.environ.get("KITE_DEBUG") == "1"
+
+def verify_token(token: str) -> bool:
+    if is_debug:
+        return True
+    return token == expected_token
+```
+
+---
+
+## 七、环境变量传递链
+
+### 生产环境
+
+```
+用户执行 kite [--debug]
+    ↓
+cli.js 设置初始环境变量：
+  KITE_PROJECT / KITE_CWD / KITE_WORKSPACE / KITE_DATA
+  KITE_MODULES / KITE_REPO / KITE_VERSION / KITE_ENV
+    ↓
+spawn python main.py（继承环境变量）
+    ↓
+main.py 解析 --debug → 设置 KITE_DEBUG
+    ↓
+Launcher 启动：
+  1. 解析 KITE_CWD → KITE_INSTANCE_DIR（查找/创建实例工作区）
+  2. 生成 KITE_INSTANCE
+  3. 设置 KITE_MODULE_DATA（Launcher 自身 = KITE_INSTANCE_DIR/launcher/）
+  4. 启动 Registry → 获取端口 → 设置 KITE_REGISTRY_PORT
+  5. 启动 Event Hub → Event Hub 注册到 Registry
+     → Registry 感知 Event Hub 上线 → Registry 发送 module.ready
+  6. 按拓扑序启动其他模块（每个子进程的 KITE_MODULE_DATA 指向各自的数据目录）
+    ↓
+所有子进程继承全部 KITE_* 环境变量（os.environ.copy()）
+```
+
+### 开发环境
+
+```
+开发者创建 .env 文件（配置 KITE_* 变量）
+    ↓
+python main.py [--debug]
+    ↓
+main.py 加载 .env（python-dotenv）
+main.py 为未设置的变量填充默认值
+main.py 解析 --debug → 设置 KITE_DEBUG
+    ↓
+Launcher 启动（同上步骤 1-5）
+    ↓
+所有子进程继承全部 KITE_* 环境变量
+```
+
+### 优先级（从高到低）
+
+1. Launcher 运行时设置的变量（`KITE_INSTANCE_DIR`、`KITE_REGISTRY_PORT`、`KITE_MODULE_DATA`）
+2. cli.js 显式设置的环境变量
+3. `.env` 文件中的配置
+4. `main.py` 中的默认值
+
+---
+
+## 八、.env 配置
+
+### .env 文件（本地开发，不提交到 git）
+
+```bash
+# .env
+
+# 运行环境
+KITE_ENV=development
+
+# 路径配置（通常使用默认值即可，无需配置）
+# KITE_CWD=当前目录
+# KITE_DATA=~/.kite/data
+# KITE_WORKSPACE=~/.kite/workspace
+# KITE_MODULES=~/.kite/modules
+# KITE_REPO=~/.kite/repo
+
+# API Keys
+OPENAI_API_KEY=sk-xxx
+ANTHROPIC_API_KEY=sk-ant-xxx
+```
+
+### .env.example 模板（提交到 git，供参考）
+
+```bash
+# .env.example
+
+# 运行环境
+KITE_ENV=development
+
+# 路径配置（可选，默认值见文档）
+# KITE_CWD=当前目录
+# KITE_DATA=~/.kite/data
+# KITE_WORKSPACE=~/.kite/workspace
+# KITE_MODULES=~/.kite/modules
+# KITE_REPO=~/.kite/repo
+
+# API Keys
+OPENAI_API_KEY=your_key_here
+ANTHROPIC_API_KEY=your_key_here
+```
+
+### 加载方式
+
+```python
+# main.py（最开头）
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+```
+
+---
+
+## 九、废弃项
+
+| 废弃项 | 替代方案 |
+|--------|---------|
+| `core/data_dir.py` | 直接读取环境变量 `os.environ.get("KITE_*")` |
+| `port.txt` / `port_{id}.txt` | stdout 结构化消息 + `KITE_REGISTRY_PORT` 环境变量 |
+| 模块源码树内 `data/` 目录 | `KITE_MODULE_DATA`（实例级）或 `KITE_DATA/{module}/`（用户级） |
+
+---
+
+## 十、模块中使用
+
+### Python
+
+```python
+import os
+
+# 读取路径
+project_dir   = os.environ.get("KITE_PROJECT")
+cwd           = os.environ.get("KITE_CWD")
+workspace     = os.environ.get("KITE_WORKSPACE")      # 工作区根路径
+instance_dir  = os.environ.get("KITE_INSTANCE_DIR")    # 当前实例工作区（已解析）
+data_dir      = os.environ.get("KITE_DATA")
+modules_dir   = os.environ.get("KITE_MODULES")
+repo_dir      = os.environ.get("KITE_REPO")
+module_data   = os.environ.get("KITE_MODULE_DATA")     # 本模块的实例级数据目录
+version       = os.environ.get("KITE_VERSION", "")
+instance      = os.environ.get("KITE_INSTANCE", "")
+env           = os.environ.get("KITE_ENV", "production")
+is_debug      = os.environ.get("KITE_DEBUG") == "1"
+registry_port = int(os.environ.get("KITE_REGISTRY_PORT", "0"))
+
+# 实例级数据（写到 KITE_MODULE_DATA，由 Launcher 注入）
+my_state      = os.path.join(module_data, "state.json")
+my_log        = os.path.join(module_data, "events.jsonl")
+
+# 用户级共享数据（写到 KITE_DATA）
+user_profile  = os.path.join(data_dir, "users", phone, "profile.yaml")
+global_config = os.path.join(data_dir, "config", "runtime.yaml")
+my_persist    = os.path.join(data_dir, module_name, "history.jsonl")
+
+# 用户可见文件（写到 KITE_CWD/.kite/）
+user_log = os.path.join(cwd, ".kite", "logs", "latest.log")
+```
+
+### Node.js
+
+```javascript
+const cwd         = process.env.KITE_CWD;
+const instanceDir = process.env.KITE_INSTANCE_DIR;
+const dataDir     = process.env.KITE_DATA;
+const moduleData  = process.env.KITE_MODULE_DATA;    // 本模块的实例级数据目录
+const isDebug     = process.env.KITE_DEBUG === '1';
+const regPort     = process.env.KITE_REGISTRY_PORT;
+
+// 实例级数据（写到 KITE_MODULE_DATA）
+const myState = path.join(moduleData, 'state.json');
+
+// 用户级共享数据
+const userDir = path.join(dataDir, 'users');
+
+// 用户可见文件
+const logFile = path.join(cwd, '.kite', 'logs', 'latest.log');
+```