@agentunion/kite 1.5.0 → 1.6.0

package/docs/Kite/346/241/206/346/236/266/350/256/276/350/256/241/06-/347/233/256/345/275/225/347/273/223/346/236/204.md

@@ -0,0 +1,231 @@
+# 6. 目录结构
+
+本文档描述 Kite 框架在生产环境和开发环境下的完整目录结构。
+
+---
+
+## 6.1 生产环境（通过 `kite` 命令启动）
+
+### 全局目录（~/.kite/）
+
+```
+~/.kite/
+├── versions/                           ← 版本化的框架代码
+│   ├── 1.0.6/                          ← KITE_PROJECT（当前版本）
+│   │   ├── main.py                     ← Python 入口
+│   │   ├── cli.js                      ← npm 入口（设置 KITE_* 环境变量）
+│   │   ├── package.json
+│   │   ├── .env.example                ← .env 模板
+│   │   ├── .gitignore
+│   │   ├── launcher/                   ← 启动器（不作为子进程）
+│   │   │   ├── entry.py
+│   │   │   ├── process_manager.py
+│   │   │   ├── module_scanner.py
+│   │   │   └── module.md
+│   │   ├── kernel/                     ← 内核（Registry + Event Hub 合并）
+│   │   │   ├── entry.py
+│   │   │   ├── server.py
+│   │   │   ├── rpc_router.py
+│   │   │   ├── registry_store.py
+│   │   │   ├── event_hub.py
+│   │   │   ├── router.py
+│   │   │   ├── dedup.py
+│   │   │   └── module.md
+│   │   ├── extensions/
+│   │   │   └── services/
+│   │   │       └── watchdog/           ← 健康监控服务
+│   │   │           ├── entry.py
+│   │   │           ├── monitor.py
+│   │   │           └── module.md
+│   │   ├── scripts/                    ← 工具脚本
+│   │   │   └── count_lines.py          ← 代码统计工具
+│   │   ├── tests/                      ← 测试模块
+│   │   │   ├── modules/
+│   │   │   │   └── hello_node/         ← Node.js 测试模块
+│   │   │   └── README.md
+│   │   └── docs/
+│   └── 1.0.7/                          ← 其他版本
+│
+├── workspace/                          ← KITE_WORKSPACE（实例工作区根）
+│   ├── project-a/                      ← KITE_INSTANCE_DIR（实例 A）
+│   │   ├── .cwd                        ←   记录 KITE_CWD 完整路径
+│   │   ├── launcher/
+│   │   │   ├── state/                  ←   运行时状态文件
+│   │   │   │   ├── processes.json      ←     当前实例子进程记录
+│   │   │   │   └── lifecycle.jsonl     ←     启动/停止生命周期日志（每次启动清空）
+│   │   │   └── log/                    ←   日志文件（见日志规范）
+│   │   ├── kernel/                     ←   Kernel 实例级数据
+│   │   │   └── log/
+│   │   └── {module_name}/             ←   各模块实例级内部数据
+│   ├── project-b/                      ← KITE_INSTANCE_DIR（实例 B）
+│   └── project-a~1/                    ←   末级目录重名时加后缀
+│
+├── data/                               ← KITE_DATA（跨实例共享）
+│   ├── users/                          ←   用户身份层数据
+│   ├── contacts/                       ←   联系人数据
+│   ├── config/                         ←   全局配置（runtime.yaml 等）
+│   ├── switches.json                   ←   全局工具/技能开关
+│   └── {module_name}/                 ←   模块用户级持久数据
+│
+├── modules/                            ← KITE_MODULES（用户扩展模块）
+│   └── {module_name}/
+│       ├── entry.py
+│       └── module.md
+│
+└── repo/                               ← KITE_REPO（版本管理备份）
+```
+
+### 用户项目目录（KITE_CWD）
+
+```
+/home/user/project-a/                   ← KITE_CWD（用户执行 kite 的目录）
+├── （用户自己的项目文件）
+└── .kite/                              ← 用户可见的 Kite 文件
+    ├── ignore                          ←   忽略规则（类似 .gitignore）
+    ├── config.json                     ←   本目录的 Kite 配置
+    └── logs/                           ←   用户可查看的日志
+```
+
+---
+
+## 6.2 开发环境（直接 `python main.py` 启动）
+
+### 源码目录（KITE_PROJECT）
+
+```
+{source_root}/                          ← KITE_PROJECT（源码目录，即 KITE_CWD）
+├── main.py                             ← 入口：加载 .env → 设置 KITE_* 默认值 → --debug
+├── cli.js                              ← npm 入口（开发时不使用）
+├── package.json
+├── README.md                           ← 项目说明
+├── CLAUDE.md                           ← Claude Code 项目指南
+├── .env                                ← 本地开发配置（不提交 git）
+├── .env.example                        ← .env 模板
+├── .gitignore
+│
+├── launcher/                           ← 启动器（核心模块）
+│   ├── entry.py                        ← Launcher 主类 + _resolve_instance_dir()
+│   ├── process_manager.py              ← 子进程管理
+│   ├── module_scanner.py               ← 模块发现
+│   └── module.md                       ← Launcher 配置 + discovery 源
+│
+├── kernel/                             ← 内核（核心模块，Registry + Event Hub 合并）
+│   ├── entry.py                        ← Kernel 入口
+│   ├── server.py                       ← FastAPI + WebSocket 统一服务器
+│   ├── rpc_router.py                   ← JSON-RPC 2.0 路由器
+│   ├── registry_store.py               ← 注册表存储 + token 验证
+│   ├── event_hub.py                    ← 事件路由 + 去重
+│   ├── router.py                       ← 事件路由匹配
+│   ├── dedup.py                        ← 事件去重
+│   └── module.md                       ← Kernel 配置
+│
+├── extensions/                         ← 扩展模块
+│   ├── agents/                         ← AI 代理
+│   ├── channels/                       ← 通信通道
+│   └── services/                       ← 服务模块
+│       └── watchdog/
+│           ├── entry.py
+│           ├── monitor.py
+│           └── module.md
+│
+├── scripts/                            ← 工具脚本
+│   └── count_lines.py                  ← 代码统计工具
+│
+├── tests/                              ← 测试相关
+│   ├── modules/                        ← 测试模块
+│   │   └── hello_node/                 ← Node.js 测试模块
+│   │       ├── entry.js
+│   │       └── module.md
+│   └── README.md
+│
+├── docs/                               ← 设计文档
+│   ├── Kite框架设计/
+│   ├── 环境变量与运行时目录设计.md
+│   └── ...
+│
+├── data/                               ← 开发时数据（不提交）
+│   └── stats/                          ← 代码统计历史
+│
+└── .dev/                               ← 开发相关（不提交）
+    ├── changelogs/                     ← 变更日志
+    ├── releases/                       ← 发布备份
+    └── docs-archive/                   ← 已归档文档
+```
+
+### 运行时数据（~/.kite/）
+
+开发环境的运行时数据结构与生产环境完全相同：
+
+```
+~/.kite/
+├── workspace/                          ← KITE_WORKSPACE
+│   └── {source_root_basename}/         ← KITE_INSTANCE_DIR
+│       ├── .cwd
+│       ├── launcher/
+│       │   ├── state/
+│       │   │   ├── processes.json
+│       │   │   └── lifecycle.jsonl
+│       │   └── log/
+│       ├── kernel/                     ← Kernel 实例级数据
+│       │   └── log/
+│       └── {module_name}/              ← 各模块实例级内部数据
+│           └── log/
+├── data/                               ← KITE_DATA
+├── modules/                            ← KITE_MODULES
+└── repo/                               ← KITE_REPO
+```
+
+---
+
+## 6.3 环境变量与目录的对应关系
+
+| 环境变量 | 生产环境 | 开发环境 |
+|---------|---------|---------|
+| `KITE_PROJECT` | `~/.kite/versions/1.0.6/` | 源码目录 |
+| `KITE_CWD` | 用户执行 `kite` 的目录 | `os.getcwd()` |
+| `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_INSTANCE` | Launcher PID | Launcher PID |
+| `KITE_ENV` | `production` | `development` |
+| `KITE_DEBUG` | `--debug` 时为 `1` | `--debug` 时为 `1` |
+| `KITE_KERNEL_PORT` | Launcher 运行时设置 | Launcher 运行时设置 |
+| `KITE_MODULE_DATA` | Launcher 注入（`KITE_INSTANCE_DIR/{module_name}/`） | Launcher 注入 |
+
+---
+
+## 6.4 数据归属判断
+
+```
+数据是给用户看的吗？
+├── 是 ──→ KITE_CWD/.kite/（用户可见的 Kite 文件）
+│
+└── 否（Kite 内部数据）
+    │
+    ├── 多实例间需要共享吗？
+    │   └── 是 ──→ KITE_DATA（用户级共享）
+    │
+    └── 否（实例独占）
+        └── ──→ KITE_MODULE_DATA（= KITE_INSTANCE_DIR/{module_name}/）
+```
+
+---
+
+## 6.5 模块目录规范
+
+每个模块（core 或 extension）遵循统一结构：
+
+```
+{module_name}/
+├── entry.py / entry.js         ← 入口文件（runtime 决定）
+├── module.md                   ← 模块配置（YAML frontmatter）
+├── server.py                   ← HTTP/WS 服务（可选）
+└── ...                         ← 模块自身代码
+```
+
+模块不在自身源码目录下存放运行时数据。运行时数据写入：
+- 实例级：`KITE_MODULE_DATA`（由 Launcher 注入，等于 `KITE_INSTANCE_DIR/{module_name}/`）
+- 用户级：`KITE_DATA/{module_name}/`

package/docs/Kite/346/241/206/346/236/266/350/256/276/350/256/241/07-/346/225/260/346/215/256/346/250/241/345/236/213.md

@@ -0,0 +1,68 @@
+# 7. 数据模型
+
+## 7.1 会话（Session）
+
+```python
+{
+    "session_id": str,
+    "session_key": str,            # 会话隔离键（由 resolve_session_key 生成）
+    "agent_id": str,               # agent 身份名
+    "peer_id": str,                # 对方身份名（contact 或 group）
+    "peer_kind": "peer" | "group",   # 对方类型（私聊 / 群）
+    "channel": str,                # 渠道类型
+    "direction": "outgoing" | "incoming",
+    "source": "api" | "auto" | "manual",
+    "mode": "managed" | "authorized",
+    "status": "active" | "ended" | "failed",
+    "started_at": str,
+    "ended_at": str | None,
+    "duration_seconds": int,
+    "summary": str,
+    "session_dir": str,            # 数据存储路径
+}
+```
+
+## 7.2 任务（Task）
+
+```python
+{
+    "task_id": str,
+    "type": str,                  # 任务类型（自定义）
+    "goal": str,                  # 任务目标
+    "status": "pending" | "in_progress" | "completed" | "failed",
+    "priority": int,              # 优先级 1-5
+    "parent_task_id": str | None,
+    "created_by": str,            # 创建者（Agent / API / 用户）
+    "assigned_to": str | None,    # 执行者（Agent 实例）
+    "created_at": str,
+    "started_at": str | None,
+    "completed_at": str | None,
+    "result": str | None,
+    "metadata": dict,             # 任务相关元数据
+}
+```
+
+## 7.3 身份（Identity）
+
+```python
+{
+    "identity_id": str,           # 文件夹名（人类可读名 或 channel_id）
+    "roles": ["agent" | "owner" | "contact" | "group"],  # 角色标记列表（可多个）
+    "name": str,                  # 显示名称
+    "channel_ids": {              # 渠道 ID 映射
+        "phone": ["138xxxx"],
+        "email": ["xxx@xxx.com"],
+        "wechat": ["group_abc123"],
+        "aid": ["abc123"],
+    },
+    "metadata": dict,
+}
+```
+
+## 7.4 索引文件（_index/{channel}_{id}.json）
+
+```json
+{
+    "identity": "张三"
+}
+```

package/docs/Kite/346/241/206/346/236/266/350/256/276/350/256/241/08-/346/211/251/345/261/225/346/200/247.md

@@ -0,0 +1,34 @@
+# 8. 扩展性
+
+## 8.1 添加新渠道
+
+1. 创建模块目录 `extensions/channels/{channel_name}/`
+2. 编写 `module.md` 定义工具和事件
+3. 实现 `entry.py` 和渠道逻辑
+4. 在模块的 `module.md` 中设置 `state: enabled`
+5. 启动系统
+
+## 8.2 添加新 Agent 类型
+
+Agent 本质也是模块，遵循统一的模块结构：
+
+1. 在 `extensions/agents/` 下创建类型目录
+2. 编写 `entry.py`、`module.md`
+3. 在 `tools/` 下放置该 Agent 提供的工具
+4. 在 `permissions/` 下配置该 Agent 可使用的工具权限
+5. 在 `prompts/` 下编写提示词模板
+6. Kernel 中添加调度逻辑
+
+## 8.3 添加新工具
+
+1. 在模块中定义工具（`module.md`）
+2. 实现工具逻辑
+3. 注册到注册中心
+4. Agent 即可调用
+
+## 8.4 添加新事件类型
+
+1. 在模块中声明事件类型（`module.md`）
+2. 在适当时机发送事件
+3. 其他模块订阅该事件
+4. 事件中心自动路由

package/docs/Kite/346/241/206/346/236/266/350/256/276/350/256/241/09-/344/270/216/345/205/267/344/275/223/345/272/224/347/224/250/347/232/204/345/205/263/347/263/273.md

@@ -0,0 +1,22 @@
+# 9. 与具体应用的关系
+
+框架本身不包含任何特定应用逻辑。要实现具体应用（如 AI 电话、AI 邮件助手等），需要：
+
+1. **实现渠道模块** — 提供该应用所需的渠道（如电话渠道、邮箱渠道）
+2. **定义事件类型** — 该应用特有的事件（如来电、收到邮件）
+3. **实现工具** — 该应用特有的操作（如拨号、发邮件）
+4. **配置 Agent** — 根据应用场景配置 Agent 的提示词和工具范围
+5. **编写业务逻辑** — 在模块中实现应用特定的处理逻辑
+
+框架提供的是：
+- 事件驱动基础设施
+- 模块规范
+- 服务注册与发现
+- 会话和任务管理
+- 身份和权限体系
+- 大模型调用抽象
+
+应用需要提供的是：
+- 具体的渠道实现
+- 具体的事件和工具
+- 具体的业务逻辑

package/docs/Kite/346/241/206/346/236/266/350/256/276/350/256/241/README.md

@@ -0,0 +1,46 @@
+# Kite — Agent 运行时框架设计
+
+## 目录
+
+- [1. 框架定位](01-框架定位.md)
+- [2. 核心概念](02-核心概念.md)
+  - 2.1 身份（Identity）
+  - 2.2 渠道（Channel）
+  - 2.3 事件（Event）
+  - 2.4 会话（Session）
+  - 2.5 Agent
+  - 2.6 工具与技能
+  - 2.7 任务（Task）
+  - 2.8 工作模式
+- [3. 系统架构](03-系统架构.md)
+  - 3.1 进程模型
+  - 3.2 启动器（Launcher）
+  - 3.3 注册中心（Registry）
+  - 3.4 事件中心（Event Hub）
+  - 3.5 系统内核（Kernel）
+  - 3.6 模型服务（Model Service）
+  - 3.7 任务系统（Task System）
+  - 3.8 保活模块（Watchdog）
+  - 3.9 事件可靠性
+- [4. 模块规范](04-模块规范.md)
+  - 4.1 统一模块结构
+  - 4.2 module.md 格式
+  - 4.3 entry.py 启动协议
+  - 4.4 模块职责
+  - 4.5 Agent 模块 Hook 调用规范
+- [5. 核心流程](05-核心流程.md)
+  - 5.1 系统启动流程
+  - 5.2 事件驱动流程（通用）
+  - 5.3 工具调用流程
+  - 5.4 会话生命周期
+  - 5.5 任务执行流程
+- [6. 目录结构](06-目录结构.md)
+  - 6.1 根目录范式
+  - 6.2 详细结构
+- [7. 数据模型](07-数据模型.md)
+  - 7.1 会话（Session）
+  - 7.2 任务（Task）
+  - 7.3 身份（Identity）
+  - 7.4 索引文件
+- [8. 扩展性](08-扩展性.md)
+- [9. 与具体应用的关系](09-与具体应用的关系.md)