@agentunion/kite 1.4.0 → 1.6.0

package/docs/audit-module-design.md

@@ -0,0 +1,315 @@
+# Audit 模块设计文档
+
+## 概述
+
+Audit 模块是 Kite 框架的审计与日志查询服务，提供：
+1. **审计功能** — 不可篡改的操作记录，用于合规、安全、责任追溯
+2. **日志查询** — 统一的技术日志查询接口，节省 token 消耗
+
+## 核心概念
+
+### 日志 vs 审计
+
+| 维度 | 日志（Logging） | 审计（Auditing） |
+|------|----------------|-----------------|
+| 目的 | 调试、故障排查 | 合规、安全、追溯 |
+| 受众 | 开发者、运维 | 审计员、管理层 |
+| 内容 | 技术细节、错误 | 用户行为、敏感操作 |
+| 格式 | 灵活 | 结构化、标准化 |
+| 保留 | 短期（天/周） | 长期（月/年） |
+| 可变性 | 可清理 | 不可篡改 |
+
+### 审计事件模型
+
+```json
+{
+  "timestamp": "2026-03-09T10:30:45.123Z",
+  "event_id": "uuid-v4",
+  "actor": {
+    "type": "user|module|system",
+    "id": "launcher",
+    "ip": "127.0.0.1"
+  },
+  "action": "module.start",
+  "resource": {
+    "type": "module",
+    "id": "web",
+    "attributes": {"version": "1.5.0"}
+  },
+  "result": "success|failure",
+  "reason": "user_request",
+  "context": {
+    "session_id": "...",
+    "request_id": "..."
+  }
+}
+```
+
+## 架构设计
+
+### 模块结构
+
+```
+extensions/services/audit/
+├── module.md              # 模块配置
+├── entry.py               # 入口（stdin 协议 + WS 连接）
+├── server.py              # FastAPI HTTP 服务
+├── collector.py           # 审计事件收集器
+├── storage.py             # 审计日志存储（append-only）
+├── query_audit.py         # 审计查询引擎
+├── query_logs.py          # 技术日志查询引擎
+├── routes/
+│   ├── __init__.py
+│   ├── routes_audit.py    # 审计查询 API
+│   └── routes_logs.py     # 日志查询 API
+└── schemas/
+    ├── __init__.py
+    └── audit_event.py     # 审计事件 Schema
+```
+
+### 数据流
+
+```
+Kernel 事件 → Collector → Storage (append-only) → Query API
+                ↓
+            审计索引（可选）
+```
+
+### 存储结构
+
+```
+{KITE_INSTANCE_DIR}/audit/
+├── events/                     # 审计事件
+│   ├── 2026-03/
+│   │   ├── 2026-03-09.jsonl    # 每日一个文件
+│   │   └── 2026-03-09.sha256   # 完整性校验
+│   └── index.db                # SQLite 索引（Phase 2）
+├── snapshots/                  # 状态快照（Phase 3）
+└── metadata.json               # 审计配置
+```
+
+## API 设计
+
+### 审计 API
+
+#### 1. GET /api/audit/events
+查询审计事件
+
+**Query 参数：**
+- `start_time` — 开始时间（ISO 8601）
+- `end_time` — 结束时间
+- `actor_type` — 操作者类型
+- `actor_id` — 操作者 ID
+- `action` — 操作类型
+- `resource_type` — 资源类型
+- `resource_id` — 资源 ID
+- `result` — 结果（success/failure）
+- `limit` — 返回数量（默认 100）
+- `offset` — 偏移量
+
+**响应：**
+```json
+{
+  "total": 1234,
+  "events": [
+    {
+      "timestamp": "2026-03-09T10:30:45.123Z",
+      "event_id": "...",
+      "actor": {...},
+      "action": "module.start",
+      "resource": {...},
+      "result": "success"
+    }
+  ]
+}
+```
+
+#### 2. GET /api/audit/timeline
+时间线视图（按小时/天聚合）
+
+#### 3. GET /api/audit/actors
+按操作者分组统计
+
+#### 4. GET /api/audit/export
+导出审计报告（CSV/JSON）
+
+#### 5. POST /api/audit/verify
+验证审计日志完整性
+
+### 日志 API
+
+#### 1. GET /api/logs/modules
+列出所有模块及其日志统计
+
+**响应：**
+```json
+{
+  "modules": [
+    {
+      "name": "launcher",
+      "log_dir": "...",
+      "latest_logs": ["latest.log", "latest~2.log"],
+      "crash_logs": ["crashes.jsonl"],
+      "daily_logs_count": 7,
+      "total_size_mb": 12.5
+    }
+  ]
+}
+```
+
+#### 2. GET /api/logs/{module}/list
+列出指定模块的所有日志文件
+
+#### 3. GET /api/logs/{module}/read
+读取日志内容
+
+**Query 参数：**
+- `file` — 文件名（必填）
+- `offset` — 行偏移（默认 0）
+- `limit` — 行数限制（默认 1000）
+- `search` — 搜索关键词（可选）
+
+#### 4. GET /api/logs/{module}/crashes
+读取崩溃日志（解析 crashes.jsonl）
+
+#### 5. GET /api/logs/search
+全局搜索
+
+**Query 参数：**
+- `keyword` — 搜索关键词（必填）
+- `modules` — 模块列表（逗号分隔，可选）
+- `date_from` — 开始日期
+- `date_to` — 结束日期
+- `limit` — 返回数量
+
+## 实现计划
+
+### Phase 1 — 基础框架（当前）
+
+**目标：** 建立模块骨架，实现基础的事件收集和日志查询
+
+**任务：**
+1. 创建模块目录结构
+2. 实现 `module.md` 配置
+3. 实现 `entry.py`（stdin 协议 + Kernel WS 连接）
+4. 实现 `server.py`（FastAPI 应用）
+5. 实现 `collector.py`（订阅 Kernel 事件）
+6. 实现 `storage.py`（append-only JSONL 存储）
+7. 实现 `query_logs.py`（技术日志查询）
+8. 实现 `routes/routes_logs.py`（日志查询 API）
+9. 实现 `routes/routes_audit.py`（审计查询 API，基础版）
+
+**交付物：**
+- 可启动的 audit 模块
+- 能订阅 Kernel 事件并写入审计日志
+- 提供日志查询 API（/api/logs/*）
+- 提供基础审计查询 API（/api/audit/events）
+
+### Phase 2 — 完整性保护
+
+**目标：** 实现审计日志的不可篡改性
+
+**任务：**
+1. 每日日志封存 + SHA256 校验
+2. 完整性验证 API
+3. 自动清理过期日志
+4. 与 backup 模块集成
+
+### Phase 3 — 高级功能
+
+**目标：** 提升查询性能和用户体验
+
+**任务：**
+1. SQLite 索引加速查询
+2. 审计报告导出（CSV/JSON/PDF）
+3. 可视化时间线
+4. 告警规则（异常行为检测）
+
+## 配置示例
+
+### module.md
+
+```yaml
+---
+name: audit
+preferred_port: 18770
+advertise_ip: 127.0.0.1
+state: enabled
+graceful_shutdown: true
+tools:
+  rpc:
+    module:
+      health: {}
+      status: {}
+---
+
+# Audit Service
+
+审计与日志查询服务。
+
+## 功能
+
+- 审计事件收集与存储
+- 技术日志统一查询
+- 审计报告导出
+```
+
+### 审计配置（metadata.json）
+
+```json
+{
+  "retention": {
+    "audit_events_days": 365,
+    "technical_logs_days": 30,
+    "crash_logs_days": 90,
+    "auto_cleanup": true
+  },
+  "collection": {
+    "subscribed_events": [
+      "module.*",
+      "registry.*",
+      "config.*"
+    ],
+    "buffer_size": 1000,
+    "flush_interval_seconds": 5
+  },
+  "storage": {
+    "compression": false,
+    "checksum_algorithm": "sha256"
+  }
+}
+```
+
+## 安全考虑
+
+1. **只读访问** — 审计日志文件权限设为只读（除了 audit 模块）
+2. **独立存储** — 审计日志与技术日志分离存储
+3. **加密传输** — 审计查询 API 强制 HTTPS（生产环境）
+4. **访问审计** — 查询审计日志的操作本身也要被审计
+5. **备份策略** — 定期备份审计日志到外部存储
+
+## 与其他模块的交互
+
+### Kernel
+- 订阅事件：`module.*`, `registry.*`, `config.*`
+- 发布事件：`audit.daily_sealed`（每日日志封存完成）
+
+### Backup
+- 订阅 `audit.daily_sealed` 事件，自动备份审计日志
+
+### Web
+- 可选：Web 模块发布业务审计事件（`call.*`, `sms.*`）
+
+## 参考标准
+
+- **ISO 27001** — 信息安全管理
+- **SOC 2** — 服务组织控制
+- **GDPR** — 数据保护（欧盟）
+- **NIST SP 800-92** — 日志管理指南
+
+## 未来扩展
+
+1. **分布式审计** — 多实例审计日志聚合
+2. **实时告警** — 异常行为检测与通知
+3. **机器学习** — 基于审计日志的异常检测
+4. **区块链** — 审计日志哈希链上链

package/docs/audit-module-implementation-summary.md

@@ -0,0 +1,149 @@
+# Audit 模块实现总结
+
+## 已完成的工作
+
+### 1. 设计文档
+- `docs/audit-module-design.md` — 完整的设计文档，包含架构、API、实现计划
+
+### 2. 模块结构
+```
+extensions/services/audit/
+├── module.md              # 模块配置
+├── entry.py               # 入口（stdin 协议 + Kernel 连接）
+├── server.py              # FastAPI HTTP 服务器
+├── collector.py           # 审计事件收集器
+├── storage.py             # Append-only 存储
+├── query_audit.py         # 审计查询引擎
+├── query_logs.py          # 技术日志查询引擎
+├── routes/
+│   ├── __init__.py
+│   ├── routes_audit.py    # 审计查询 API
+│   └── routes_logs.py     # 日志查询 API
+├── schemas/
+│   ├── __init__.py
+│   └── audit_event.py     # 审计事件 Schema
+└── README.md              # 使用说明
+```
+
+### 3. 核心功能
+
+#### 审计功能
+- ✅ 订阅 Kernel 事件（module.*, registry.*）
+- ✅ 转换为结构化审计事件
+- ✅ Append-only JSONL 存储（按日期分文件）
+- ✅ 基础查询 API（时间范围、操作者、资源、结果过滤）
+
+#### 日志查询功能
+- ✅ 列出所有模块及日志统计
+- ✅ 列出模块的日志文件
+- ✅ 读取日志内容（支持分页、搜索）
+- ✅ 读取崩溃日志（解析 crashes.jsonl）
+- ✅ 全局搜索（跨模块）
+
+### 4. API 端点
+
+**审计 API：**
+- `GET /api/audit/events` — 查询审计事件
+- `GET /api/audit/timeline` — 时间线视图（占位）
+- `GET /api/audit/actors` — 按操作者分组（占位）
+- `GET /api/audit/stats` — 审计统计信息
+
+**日志 API：**
+- `GET /api/logs/modules` — 列出所有模块
+- `GET /api/logs/{module}/list` — 列出日志文件
+- `GET /api/logs/{module}/read` — 读取日志内容
+- `GET /api/logs/{module}/crashes` — 读取崩溃日志
+- `GET /api/logs/search` — 全局搜索
+
+### 5. 集成点
+
+- ✅ 标准 stdin 协议（boot_info）
+- ✅ Kernel WebSocket 连接
+- ✅ 注册到 Registry
+- ✅ 订阅事件
+- ✅ 发布 module.ready
+- ✅ 优雅关闭流程（shutdown.ack → exiting → ready）
+
+## 下一步工作
+
+### 测试与调试
+1. 启动 Kite 系统，验证 audit 模块能否正常启动
+2. 测试审计事件收集（触发模块启动/停止，查看审计日志）
+3. 测试日志查询 API（通过 Swagger UI 或 curl）
+4. 修复发现的 bug
+
+### Phase 2 功能
+1. 每日日志封存 + SHA256 校验
+2. 完整性验证 API
+3. 自动清理过期日志
+4. 与 backup 模块集成
+
+### Phase 3 功能
+1. SQLite 索引加速查询
+2. 审计报告导出（CSV/JSON/PDF）
+3. 可视化时间线
+4. 告警规则（异常行为检测）
+
+## 技术亮点
+
+1. **零共享代码依赖** — 完全独立的模块，符合 Kite 架构原则
+2. **Append-only 存储** — 审计日志不可篡改
+3. **结构化事件** — 标准化的审计事件格式
+4. **统一日志查询** — 一个 API 查询所有模块的日志
+5. **安全设计** — 路径遍历防护、分页限制
+
+## 文件清单
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| `docs/audit-module-design.md` | 300+ | 设计文档 |
+| `module.md` | 60 | 模块配置 |
+| `entry.py` | 350 | 入口文件 |
+| `server.py` | 250 | HTTP 服务器 |
+| `collector.py` | 60 | 事件收集器 |
+| `storage.py` | 100 | 存储层 |
+| `query_audit.py` | 80 | 审计查询 |
+| `query_logs.py` | 200 | 日志查询 |
+| `routes/routes_audit.py` | 120 | 审计 API |
+| `routes/routes_logs.py` | 130 | 日志 API |
+| `schemas/audit_event.py` | 80 | 事件 Schema |
+| `README.md` | 150 | 使用说明 |
+
+**总计：约 1880 行代码**
+
+## 启动方式
+
+模块会被 Launcher 自动发现和启动（如果 `state: enabled`）。
+
+手动测试：
+```bash
+# 1. 确保 Kite 系统正在运行
+python main.py
+
+# 2. 访问 API 文档
+http://127.0.0.1:18770/docs
+
+# 3. 测试日志查询
+curl "http://127.0.0.1:18770/api/logs/modules"
+
+# 4. 测试审计查询
+curl "http://127.0.0.1:18770/api/audit/events?limit=10"
+```
+
+## 注意事项
+
+1. **依赖检查** — 确保已安装 FastAPI、websockets、PyYAML
+2. **端口冲突** — 默认端口 18770，如有冲突会自动分配
+3. **环境变量** — 需要 `KITE_INSTANCE_DIR` 环境变量（Launcher 自动设置）
+4. **日志目录** — 审计日志存储在 `{KITE_INSTANCE_DIR}/audit/events/`
+
+## 总结
+
+Audit 模块的基础框架已完成，实现了：
+- ✅ 完整的模块骨架
+- ✅ 审计事件收集与存储
+- ✅ 技术日志统一查询
+- ✅ RESTful API 接口
+- ✅ 完整的文档
+
+可以开始测试和调试，然后逐步实现 Phase 2 和 Phase 3 的高级功能。

package/docs/llm-context-design.md

@@ -0,0 +1,52 @@
+# LLM 对话上下文方案
+
+> Kite 控制台（evol 模块）的大模型对话页面上下文设计
+
+## 设计原则
+
+- **全量上下文**：system prompt 全量载入 CLAUDE.md + module.md + 注册中心信息
+- **工具动态发现**：可用工具从注册中心动态获取，不硬编码
+- **工具直接 RPC**：LLM 的工具调用直接走 Kernel RPC 路由，不经中间层代理
+- **最少工具原则**：只提供「调用任意 RPC」和「读取文件」两个通用工具，不为每个场景造专用工具
+
+## System Prompt 内容（全量）
+
+通过 `evol.get_system_context` RPC 获取，包含三部分：
+
+| 内容 | 来源 | 说明 |
+|---|---|---|
+| CLAUDE.md | 项目根目录文件 | 全文载入 |
+| Module Documentation | 各模块 `module.md` | 所有在线模块的完整文档 |
+| Registry Information | `registry.lookup()` + `registry.get()` | 模块列表、RPC 方法、事件定义 |
+
+## 工具调用
+
+### 可用工具
+
+工具定义从注册中心动态获取（`convertRegistryToolsToOpenAI()`），加上 evol 自身注册的 `file_read`：
+
+- **各模块注册的 RPC 方法** — 从注册中心 tools 字段动态解析
+- **evol.file_read** — 读取项目文件（路径限制在项目目录内）
+
+### 调用方式
+
+LLM 返回 tool_calls → 前端直接通过 `kernelClient.call(tool_name, args)` 走 Kernel RPC 路由。
+
+符合 Kite 核心设计：模块间通过 RPC 通信，Kernel 统一路由。
+
+## 已完成的修改
+
+### 后端 server.py
+
+1. **修复 `_rpc_get_system_context`** — `registry.list`（不存在）改为 `registry.lookup()` + `registry.get()`
+2. **新增 `_rpc_file_read`** — 读取项目文件，路径安全检查，注册到注册中心
+
+### 前端 evol-app.js
+
+- `_buildSystemContext()` — 全量：CLAUDE.md + module.md + 注册中心
+- `convertRegistryToolsToOpenAI()` — 从注册中心动态解析工具定义
+- 工具调用 — 直接 `kernelClient.call(tool_name, args)`
+
+## 已知问题
+
+1. **竞态条件** — 上下文异步加载（500ms 后），用户可能在加载前发消息导致无 system context