# KAi

> 开启思考。不是帮你做事，是帮你想得更深、更远。

KAi 是一款**多 AI Agent 协作桌面应用**。你创建的每个 Agent 都有独立的记忆、工作空间和能力边界——它们像一支真正的团队一样协作。

**一个人，一支团队。**

## 为什么

通用聊天助手的问题不是不聪明，而是没有结构：它什么都能答，却没有稳定身份、长期记忆、职责边界和团队协作。

KAi 的答案是 Agent 团队。你可以让一个「乔布斯」负责产品判断，一个「Anders Hejlsberg」把控类型和架构，一个「TJ Holowaychuk」快速落地，一个「Robert C. Martin」做代码审查。它们各有各的工作空间、记忆、工具和性格；它们会 @mention 彼此，会 handoff，会广播讨论，也会把子任务分派给后台 Agent。

## 特性

### 🧠 Agent 系统

- **独立身份** — 每个 Agent 有自己的名字、头像、描述和 SOUL（行为准则）。
- **持久记忆** — Agent 自主维护 `MEMORY.md` 和每日笔记，跨会话保留上下文。
- **独立工作空间** — 每个 Agent 拥有自己的文件工作区：`~/.kai/agents/{agentId}/workspace/`。
- **能力边界** — 可为 Agent 分配 Skills、MCP 服务、禁用工具和监督参数。

### 👥 多 Agent 协作

- **Session 化对话** — 单聊和群聊都以 Session 为主概念；一个群组可拥有多个隔离 Session。
- **单聊多 Session** — 同一个 Agent 可并行开启多个讨论，适合把不同任务、分支思路和长期陪跑拆开。
- **Handoff 交接** — Agent 可以主动交接任务，并附带原因和上下文摘要。
- **@mention** — 在消息中 @ 指定 Agent，触发协作或路由。
- **Broadcast 广播** — 一次问题并行询问多个 Agent，聚合不同专业判断。
- **子任务分派** — Agent 可以创建前台或后台任务，委托其他 Agent 执行。
- **Supervisor 监督** — 指定监督者评估执行结果，决定继续、重试、跳过、修订或终止。

### 🛠 内置工具

Agent 开箱即用的能力：

| 工具 | 功能 |
|------|------|
| **Shell** | 执行终端命令 |
| **File Tools** | 安全读写和精确编辑本地文件 |
| **Web Search** | 网络搜索 |
| **Web Fetch** | 抓取和解析网页内容 |
| **Database** | 只读查询应用数据库 |
| **Scheduler** | 创建和管理定时任务 |
| **Skill** | 按需加载技能包 |
| **MCP** | 通过 Model Context Protocol 连接外部工具服务 |
| **Image** | 图片识别与图片生成 |

### 💬 聊天体验

- 流式输出，实时渲染 Markdown / 代码高亮 / 推理过程。
- 支持图片、文件附件和多模态消息。
- 工具调用、任务结果、广播结果以结构化卡片展示，并展示状态与耗时。
- 群聊与单聊都支持顶部 Session Tabs：新建、切换、重命名、归档。
- 快捷回复支持独立 `⚡` 入口与键盘直发；`/` 命令保留给真正的命令。
- 产品级快捷键绑定见 `docs/design-decisions/keyboard-shortcuts.md`。
- 明暗主题自适应。
- 中英文国际化（i18n）。

### 🔌 连接与自动化

- **模型通道** — 支持主模型、备用模型、自动 fallback 和健康状态记录。
- **模型能力学习** — 根据真实报错学习上下文窗口 / 最大输出限制，自动修正后重试。
- **MCP 服务** — 在设置中添加 MCP 服务，并一键应用到指定 Agent。
- **Bot 接入** — 支持外部频道接入，让 Agent 不只活在桌面窗口里。
- **远程访问** — 可通过远程入口访问本地 KAi。
- **定时任务** — 定期触发消息、记忆整理或自动化工作流。
- **自动更新** — 桌面应用支持检查更新、下载进度和安装更新。

## 技术栈

```text
Electron 42 + React 19 + TypeScript 5
Vercel AI SDK + SQLite3 + Zustand + CSS Modules
electron-vite + Vitest + Playwright
```

- **运行形态**：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 1.x

### 安装

```bash
git clone https://github.com/pansinm/kai.git
cd kai
yarn install
```

### 开发

```bash
yarn dev
```

### CLI

```bash
yarn build:cli
npx @sinm/kai@latest start --port 9529
```

### 构建与打包

```bash
yarn build        # 构建 Electron 应用
yarn package      # 打包当前平台安装包，输出到 release/
yarn build:cli    # 构建 CLI
```

### 测试

```bash
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
```

### 消息与 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` 保存。

### 消息压缩管线

长对话自动压缩，按成本从低到高处理：

```text
ToolResultSpill
  → ReasoningRemoval
    → Summarization
      → Pruning
```

### 数据存储

```text
~/.kai/
├── kai.db                         # SQLite：消息等结构化数据
├── config/                        # 应用配置，加密存储 API Key
├── direct-sessions/
│   └── {sessionId}/
│       └── context.json           # 单聊 Session 上下文
├── agents/
│   └── {agentId}/
│       ├── 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

KAi 通过 Vercel AI SDK 连接大语言模型，支持：

- OpenAI Compatible（OpenAI、DeepSeek、Moonshot、MiniMax 等）
- Anthropic Claude
- Google Gemini
- 任何兼容 OpenAI API 的模型服务

在设置的「模型通道」中配置 API Key 即可使用。

## MCP（Model Context Protocol）

KAi 内置 MCP 客户端。在设置中添加 MCP 服务，然后应用到指定 Agent；只有被授权的 Agent 才会看到对应 MCP 工具。

示例配置形态：

```json
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
```

## 安全模型

KAi 采用 Electron 三进程安全架构：

- **渲染进程**：沙箱化，无 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

MIT
