@sinm/kai 1.9.2 → 1.10.0-alpha

package/README.md

@@ -2,32 +2,34 @@
 
 > 开启思考。不是帮你做事，是帮你想得更深、更远。
 
-KAi 是一款**多 AI Agent 协作桌面应用**。你可以创建多个拥有独立人格、记忆和技能的 Agent，让它们在你的桌面上像一个真正的团队一样协作——讨论、交接、互审、分工。
+KAi 是一款**多 AI Agent 协作桌面应用**。你创建的每个 Agent 都有独立的记忆、工作空间和能力边界——它们像一支真正的团队一样协作。
+
+**一个人，一支团队。**
 
 ## 为什么
 
-用 ChatGPT 聊天，你得到的是一个无所不能但什么都记不住的通用助手。
+通用聊天助手的问题不是不聪明，而是没有结构：它什么都能答，却没有稳定身份、长期记忆、职责边界和团队协作。
 
-KAi 不一样。你可以让一个"乔布斯"负责产品思考，一个"Anders Hejlsberg"把控架构，一个"TJ Holowaychuk"写代码，一个"Robert C. Martin"写审查。它们各有各的记忆、工具权限和个性。它们会 @mention 彼此，会交接任务，会监督结果。
-
-**一个人，一支团队。**
+KAi 的答案是 Agent 团队。你可以让一个「乔布斯」负责产品判断，一个「Anders Hejlsberg」把控类型和架构，一个「TJ Holowaychuk」快速落地，一个「Robert C. Martin」做代码审查。它们各有各的工作空间、记忆、工具和性格；它们会 @mention 彼此，会 handoff，会广播讨论，也会把子任务分派给后台 Agent。
 
 ## 特性
 
 ### 🧠 Agent 系统
 
-- **独立身份** — 每个 Agent 有自己的名字、头像、个性描述，甚至可以自定义 SOUL（行为准则）
-- **持久记忆** — Agent 自主维护 MEMORY.md（长期记忆）和每日笔记，跨会话记住上下文
-- **工作空间** — 每个 Agent 拥有独立的文件工作空间（`~/.kai/agents/{id}/workspace/`）
-- **Skill 技能系统** — 可扩展的技能包，Agent 按需加载，提升专业领域表现
+- **独立身份** — 每个 Agent 有自己的名字、头像、描述和 SOUL（行为准则）。
+- **持久记忆** — Agent 自主维护 `MEMORY.md` 和每日笔记，跨会话保留上下文。
+- **独立工作空间** — 每个 Agent 拥有自己的文件工作区：`~/.kai/agents/{agentId}/workspace/`。
+- **能力边界** — 可为 Agent 分配 Skills、MCP 服务、禁用工具和监督参数。
 
 ### 👥 多 Agent 协作
 
-- **群聊模式** — 多个 Agent 在同一个对话中协作，支持 sequential / parallel / broadcast 策略
-- **Handoff 交接** — Agent 之间可以主动交接任务，附带原因和上下文摘要
-- **@mention** — 在回复中 `@AgentName` 触发自动交接
-- **Supervisor 监督** — 指定一个 Agent 作为监督者，评估执行结果是否达成目标
-- **子任务分派** — Agent 可以创建前台/后台子任务，委托给其他 Agent 执行
+- **Session 化对话** — 单聊和群聊都以 Session 为主概念；一个群组可拥有多个隔离 Session。
+- **单聊多 Session** — 同一个 Agent 可并行开启多个讨论，适合把不同任务、分支思路和长期陪跑拆开。
+- **Handoff 交接** — Agent 可以主动交接任务，并附带原因和上下文摘要。
+- **@mention** — 在消息中 @ 指定 Agent，触发协作或路由。
+- **Broadcast 广播** — 一次问题并行询问多个 Agent，聚合不同专业判断。
+- **子任务分派** — Agent 可以创建前台或后台任务，委托其他 Agent 执行。
+- **Supervisor 监督** — 指定监督者评估执行结果，决定继续、重试、跳过、修订或终止。
 
 ### 🛠 内置工具
 
@@ -36,44 +38,62 @@ Agent 开箱即用的能力：
 | 工具 | 功能 |
 |------|------|
 | **Shell** | 执行终端命令 |
-| **Read/Write/Edit File** | 读写和精确编辑本地文件 |
+| **File Tools** | 安全读写和精确编辑本地文件 |
 | **Web Search** | 网络搜索 |
 | **Web Fetch** | 抓取和解析网页内容 |
-| **Database** | 查询应用数据库（只读） |
+| **Database** | 只读查询应用数据库 |
 | **Scheduler** | 创建和管理定时任务 |
-| **Skill** | 加载和执行技能包 |
-| **MCP** | 通过 Model Context Protocol 连接外部工具服务器 |
+| **Skill** | 按需加载技能包 |
+| **MCP** | 通过 Model Context Protocol 连接外部工具服务 |
+| **Image** | 图片识别与图片生成 |
 
 ### 💬 聊天体验
 
-- 流式输出，实时渲染 Markdown / 代码高亮 / 推理过程
-- 支持图片附件
-- 明暗主题自适应
-- 中英文国际化（i18n）
+- 流式输出，实时渲染 Markdown / 代码高亮 / 推理过程。
+- 支持图片、文件附件和多模态消息。
+- 工具调用、任务结果、广播结果以结构化卡片展示，并展示状态与耗时。
+- 群聊与单聊都支持顶部 Session Tabs：新建、切换、重命名、归档。
+- 快捷回复支持独立 `⚡` 入口；`/` 命令保留给真正的命令。
+- 明暗主题自适应。
+- 中英文国际化（i18n）。
+
+### 🔌 连接与自动化
+
+- **模型通道** — 支持主模型、备用模型、自动 fallback 和健康状态记录。
+- **模型能力学习** — 根据真实报错学习上下文窗口 / 最大输出限制，自动修正后重试。
+- **MCP 服务** — 在设置中添加 MCP 服务，并一键应用到指定 Agent。
+- **Bot 接入** — 支持外部频道接入，让 Agent 不只活在桌面窗口里。
+- **远程访问** — 可通过远程入口访问本地 KAi。
+- **定时任务** — 定期触发消息、记忆整理或自动化工作流。
+- **自动更新** — 桌面应用支持检查更新、下载进度和安装更新。
 
 ## 技术栈
 
-```
-Electron 40 + React 19 + TypeScript 5
+```text
+Electron 42 + React 19 + TypeScript 5
 Vercel AI SDK + SQLite3 + Zustand + CSS Modules
-electron-vite + Vitest
+electron-vite + Vitest + Playwright
 ```
 
-- **主进程**：Agent 执行引擎、IPC、数据库、文件系统、MCP 客户端
-- **渲染进程**：React UI，沙箱化运行（`contextIsolation: true`）
-- **预加载层**：`contextBridge` 安全桥接
+- **运行形态**：Electron 桌面应用 + CLI + 本地 telemetry dashboard
+- **Core**：Agent / Message / Tool / Skill 等领域逻辑与端口接口。
+- **Adapters**：LLM、MCP、DB、文件存储、工具、调度器、外部频道等具体实现。
+- **Electron Main**：应用启动、IPC、自动更新、崩溃日志、远程访问。
+- **Renderer**：React UI，沙箱化运行（`contextIsolation: true`）。
+- **Preload**：通过 `contextBridge` 暴露受控 API。
+- **CLI**：复用核心链路的命令行入口。
 
 ## 快速开始
 
 ### 环境要求
 
 - Node.js >= 22
-- Yarn
+- Yarn 1.x
 
 ### 安装
 
 ```bash
-git clone https://github.com/your-org/kai.git
+git clone https://github.com/pansinm/kai.git
 cd kai
 yarn install
 ```
@@ -81,66 +101,139 @@ yarn install
 ### 开发
 
 ```bash
-yarn dev          # 启动开发服务器（支持 HMR）
+yarn dev
+```
+
+### CLI
+
+```bash
+yarn build:cli
+npx @sinm/kai@latest start --port 9529
 ```
 
-### 构建
+### 构建与打包
 
 ```bash
-yarn build        # 构建生产版本
-yarn package      # 打包为平台安装包（输出到 release/）
+yarn build        # 构建 Electron 应用
+yarn package      # 打包当前平台安装包，输出到 release/
+yarn build:cli    # 构建 CLI
 ```
 
 ### 测试
 
 ```bash
-yarn test              # 运行测试
-yarn test:ui           # 测试 UI
-yarn test:coverage     # 覆盖率报告
+yarn test                         # Vitest
+npx tsc --noEmit -p tsconfig.web.json
+npx tsc --noEmit -p tsconfig.node.json
+yarn test:e2e                     # 内部会先执行 yarn build
+```
+
+发布前建议按这个顺序跑完整门禁：
+
+```bash
+npx tsc --noEmit -p tsconfig.web.json
+npx tsc --noEmit -p tsconfig.node.json
+yarn test
+yarn test:e2e
 ```
 
 ## 架构
 
+KAi 的代码按职责分层，而不是按运行环境硬塞在一起：
+
+```text
+src/
+├── core/                  # 领域核心：Agent、Message、Tools、Skill、Workspace
+├── adapters/              # 适配器：LLM、DB、MCP、Storage、Tools、Scheduler、Channel
+├── electron/              # Electron 主进程、preload、updater、crash、remote
+├── renderer/              # React 渲染进程
+├── shared/                # 共享类型、配置、工具函数
+├── app/                   # 应用 bootstrap
+├── cli/                   # CLI 入口
+└── telemetry-server/      # 遥测服务端
+```
+
 ### Agent 执行层
 
+```text
+SoloExecutor             # 单 Agent 对话
+SwarmExecutor            # 多 Agent 协作编排：handoff / task / broadcast / supervisor
+  ├── TaskOrchestrator   # 子任务与广播任务编排
+  ├── SwarmContext       # 协作运行态：handoff chain、task map 等
+  └── AgentExecutor      # 当前生产执行器：流式模型调用、工具循环、fallback、压缩
+
+AgentLoop                # 正在演进的新执行循环抽象：retry / stopWhen / tool loop / usage collect
+  └── AgentKernel        # 单次模型调用内核：streamText、工具调用投影、tool-call repair
 ```
-SoloExecutor          ← 单 Agent 对话
-SwarmExecutor         ← 多 Agent 群聊（管理 handoff 循环）
-  ├── AgentExecutor   ← 单次 LLM 调用（流式 + 工具执行循环）
-  ├── SupervisorLoop  ← 监督评估循环
-  ├── TaskOrchestrator ← 子任务创建和管理
-  └── SwarmContext    ← 共享状态（handoff chain、task map）
+
+### 消息与 Session
+
+```text
+User Input
+  → window.api.sendUserMessage()
+  → MessageQueue
+  → MessageProcessor
+  → SoloChat / GroupChat
+  → SoloExecutor / SwarmExecutor
+  → LLM + Tools
+  → ConversationEvent stream
+  → Zustand Store
+  → React UI
 ```
 
+- 单聊与群聊都以 `Session` 作为主要运行单元。
+- 单聊的 Session 归属于某个 Agent；群组的 Session 归属于某个 Group。
+- `speaker` 是群组 Session 级状态，而不是全局群组状态。
+- 消息仍由 SQLite 持久化；长上下文由文件 `context.json` 保存。
+
 ### 消息压缩管线
 
-长对话自动压缩，4 级策略管道：
+长对话自动压缩，按成本从低到高处理：
 
-```
-ToolResultSpill（合并冗长工具结果）
-  → ReasoningRemoval（移除推理过程）
-    → Summarization（摘要旧消息）
-      → Pruning（裁剪最旧消息）
+```text
+ToolResultSpill
+  → ReasoningRemoval
+    → Summarization
+      → Pruning
 ```
 
 ### 数据存储
 
-```
+```text
 ~/.kai/
-├── kai.db                    # SQLite 主数据库
-├── config/                   # 应用配置（加密存储 API Key）
+├── kai.db                         # SQLite：消息等结构化数据
+├── config/                        # 应用配置，加密存储 API Key
+├── direct-sessions/
+│   └── {sessionId}/
+│       └── context.json           # 单聊 Session 上下文
 ├── agents/
 │   └── {agentId}/
-│       └── workspace/        # Agent 工作空间
-│           ├── IDENTITY.md   # 身份定义
-│           ├── SOUL.md       # 行为准则
-│           ├── MEMORY.md     # 长期记忆
-│           ├── USER.md       # 用户信息
-│           ├── AGENTS.md     # 工作指南
-│           ├── TOOLS.md      # 环境配置
-│           └── memory/       # 每日笔记
-├── attachments/              # 对话附件
-└── sessions/                 # 会话消息存储
+│       ├── meta.json              # Agent 身份
+│       ├── config.json            # 模型、fallback、skills、MCP、禁用工具等能力配置
+│       ├── context.json           # legacy 单聊上下文兼容文件
+│       └── workspace/
+│           ├── IDENTITY.md
+│           ├── SOUL.md
+│           ├── USER.md
+│           ├── MEMORY.md
+│           ├── AGENTS.md
+│           ├── TOOLS.md
+│           └── memory/
+├── groups/
+│   └── {groupId}/
+│       ├── meta.json
+│       ├── config.json
+│       ├── members.json
+│       ├── GROUP_SETTINGS.md      # 人可写，AI 只读
+│       ├── GROUP_MEMORY.md        # 群长期记忆
+│       ├── memory/                # 群每日记忆
+│       └── sessions/
+│           └── {sessionId}/
+│               ├── meta.json
+│               ├── config.json
+│               └── context.json   # 群组 Session 上下文
+├── conversations/                 # 追加式消息日志（jsonl，兼容运行链路）
+└── attachments/                   # 对话附件
 ```
 
 ## 支持的 LLM
@@ -150,69 +243,48 @@ KAi 通过 Vercel AI SDK 连接大语言模型，支持：
 - OpenAI Compatible（OpenAI、DeepSeek、Moonshot、MiniMax 等）
 - Anthropic Claude
 - Google Gemini
-- 任何兼容 OpenAI API 的模型
+- 任何兼容 OpenAI API 的模型服务
 
-在设置的 LLM 通道中配置 API Key 即可使用。
+在设置的「模型通道」中配置 API Key 即可使用。
 
 ## MCP（Model Context Protocol）
 
-KAi 内置 MCP 客户端支持。在设置中配置 MCP 服务器，即可让 Agent 使用外部工具：
+KAi 内置 MCP 客户端。在设置中添加 MCP 服务，然后应用到指定 Agent；只有被授权的 Agent 才会看到对应 MCP 工具。
+
+示例配置形态：
 
 ```json
 {
-  "mcp": {
-    "servers": {
-      "my-server": {
-        "command": "npx",
-        "args": ["-y", "@my/mcp-server"]
-      }
-    }
-  }
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
 }
 ```
 
-## 项目结构
-
-```
-src/
-├── main/                  # Electron 主进程
-│   ├── agent/             # Agent 执行引擎
-│   │   ├── SoloExecutor   # 单 Agent 执行器
-│   │   ├── SwarmExecutor  # 群聊执行器
-│   │   ├── AgentExecutor  # LLM 调用执行器
-│   │   ├── SupervisorLoop # 监督循环
-│   │   ├── TaskOrchestrator # 任务编排
-│   │   ├── SwarmContext   # 共享上下文
-│   │   ├── HandoffResolver # Handoff 解析
-│   │   └── factory/       # Prompt/Tools 构建
-│   ├── compression/       # 消息压缩管线
-│   ├── config/            # 配置管理（加密）
-│   ├── db/                # SQLite 数据层
-│   ├── handlers/          # IPC 处理器
-│   ├── mcp/               # MCP 客户端
-│   ├── scheduler/         # 定时任务系统
-│   ├── skill/             # Skill 技能系统
-│   ├── storage/           # 会话/附件存储
-│   ├── tools/             # 内置工具
-│   └── workspace/         # Agent 工作空间管理
-├── renderer/              # React 渲染进程
-│   └── src/
-│       ├── components/    # UI 组件
-│       ├── stores/        # Zustand 状态管理
-│       ├── locales/       # i18n 翻译文件
-│       └── styles/        # 设计令牌 + CSS Modules
-├── preload/               # 安全桥接层
-└── shared/                # 主进程/渲染进程共享类型
-```
-
 ## 安全模型
 
 KAi 采用 Electron 三进程安全架构：
 
-- **渲染进程**：完全沙箱化，无 Node.js 访问
-- **预加载层**：`contextIsolation: true` + `nodeIntegration: false`
-- **主进程**：所有文件系统、网络操作通过 IPC 暴露给渲染进程
-- **API Key**：AES-256 加密存储，使用机器唯一标识派生密钥
+- **渲染进程**：沙箱化，无 Node.js 直接访问。
+- **预加载层**：`contextIsolation: true` + `nodeIntegration: false`。
+- **主进程**：文件系统、网络、数据库和工具调用通过 IPC 受控暴露。
+- **文件工具**：要求绝对 `workdir` + 相对 `path`，拒绝路径逃逸。
+- **数据库工具**：只允许只读查询。
+- **API Key**：使用本地 salt + machineId 派生密钥，并通过 AES-256-GCM 加密存储。
+
+## 项目文档
+
+- [功能清单](docs/features.md) — 从用户视角查看当前已实现能力
+- [文档索引](docs/README.md) — architecture / design / workflow 等入口
+- [Release Notes](RELEASE_NOTES.md) — 已发布版本记录
+
+## 进一步阅读
+
+- [架构文档](docs/architecture/architecture.md)
+- [功能清单](docs/features.md)
+- [发版流程](docs/workflow/发版流程.md)
+- [基于 worktree 的开发流程](docs/workflow/ai-worktree-workflow.md)
+- [Swarm Supervisor 设计](docs/design/swarm-supervisor-design.md)
+- [Agent Kernel / Loop 设计](docs/design/agent-kernel-loop-design.md)
 
 ## License