# obsidian-kilo

**Repository Path**: LXP-Never/obsidian-kilo

## Basic Information

- **Project Name**: obsidian-kilo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Obsidian Kilo

> 把 Kilo Code（VS Code AI 编码助手）移植为 Obsidian 笔记 AI 助手

## 这是什么

一个 Obsidian 插件，将 [Kilo Code](https://github.com/Kilo-Org/kilocode)（VS Code AI 编码助手）的核心能力移植到 Obsidian 笔记场景：
- ✍️ 写作润色、翻译、续写、总结
- 💬 对话（AI 理解你的整个知识库）
- ⚡ 行内写作补全（Ghost Text）
- 📦 批量笔记处理
- 📝 Git commit 消息自动生成
- 🤖 500+ AI 模型可选

**与 KiloCode 的关系**：复用其 React 前端组件和 opencode CLI 后端架构，但粘合层全部重写（VS Code API → Obsidian API），并新增 Vault 索引、笔记解析、Dataview 集成等 Obsidian 特有功能。

## 快速开始

### 安装

#### 方式一：手动安装

1. 下载插件发行版（`main.js`、`manifest.json`、`styles.css`）到：
   ```
   <你的 Vault>/.obsidian/plugins/obsidian-kilo/
   ```
2. 在 Obsidian 设置 → 第三方插件中启用 `Kilo AI`

#### 方式二：从源码构建

```bash
# 克隆仓库
git clone https://gitee.com/LXP-Never/obsidian-kilo.git
cd obsidian-kilo

# 安装依赖
npm install

# 下载后端二进制
node scripts/download-binary.mjs

# 构建
npm run build

# 复制到 vault
VAULT="/path/to/your-vault/.obsidian/plugins/obsidian-kilo"
mkdir -p "$VAULT"
cp main.js manifest.json styles.css "$VAULT/"
```

#### 验证安装

启动 Obsidian，查看开发者工具（`Ctrl+Shift+I`）控制台是否输出：
```
[Kilo AI] 插件已加载
```

### 配置

1. 打开 Obsidian 设置 → Kilo AI
2. 添加 AI Provider（OpenAI / Anthropic / OpenRouter 等）
3. 填入 API Key
4. 选择默认模型
5. 点击侧边栏 ⚡ 图标打开对话面板

### 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Mod+Shift+K` | 打开对话面板 |
| `Mod+Shift+L` | 润色选中文本 |
| `Mod+Shift+C` | 续写 |
| `Mod+Shift+S` | 总结选中文本 |
| `Mod+Shift+U` | 添加到对话上下文 |
| `Mod+Shift+G` | 生成 Commit 消息 |

> 💡 翻译功能可通过右键菜单使用，暂未分配快捷键。

### 右键菜单

选中文本后右键，可用操作：
- 🌐 **润色**：学术风格 / 简洁风格 / 口语化
- 🌍 **翻译**：English / 中文 / 日本語 / Français / Deutsch
- ✏️ 续写、📋 总结、❓ 解释、🔧 Fix Markdown
- 📑 生成大纲、🏷️ 生成标题
- ➕ 添加到对话上下文

## 功能清单

### ✅ 已完成

| 功能 | 状态 | 说明 |
|------|------|------|
| 插件骨架 + 生命周期 | ✅ | 完整的 Obsidian 插件生命周期管理 |
| 后端连接管理 | ✅ | ServerManager + ConnectionService + SdkSseAdapter |
| 对话面板 | ✅ | KiloChatView + React UI + 多会话管理 |
| 编辑器集成 | ✅ | 润色/翻译/续写/总结/解释/Fix Markdown |
| 自动补全 | ✅ | CM6 Ghost Text，行内 AI 补全 |
| Git Commit 生成 | ✅ | 分析 git diff 自动生成 commit 消息 |
| Diff 引擎 | ✅ | DiffView 可视化对比修改前后 |
| 设置面板 | ✅ | Provider/模型/通用设置/功能开关 |
| 权限管理 | ✅ | PermissionModal + AutoApprove 自动审批 |
| Vault 索引 + 搜索 | ✅ | 全文索引 + 标签/链接/反向链接 |
| Agent 管理 + 批量操作 | ✅ | 批量润色/翻译/格式化笔记 |
| Marketplace | ✅ | 技能/模式/MCP 搜索安装 |
| 键盘快捷键 | ✅ | 6 个常用命令快捷键 |
| 状态栏 | ✅ | 连接状态/模型/补全开关 |
| 右键菜单增强 | ✅ | 润色 3 种风格 + 翻译 5 种语言 |
| API Key 加密 | ✅ | AES-256-GCM + 机器指纹 |
| 错误卡片增强 | ✅ | 重试 + 打开设置按钮 |
| 文件日志 | ✅ | 自动轮转（1MB 上限，保留 5 个） |
| 生成大纲/标题 | ✅ | 2 个新的编辑器操作 |
| @文件引用框架 | ✅ | MentionAutocomplete 组件 |
| 断开连接降级 | ✅ | 菜单警告 + Notice 通知 |
| 对话历史持久化 | ✅ | 后端不可用时的本地回退 |
| 模板系统 | ✅ | 5 个内置模板（文章/邮件/会议纪要等）+ 自定义模板 |
| 每日笔记增强 | ✅ | AI 自动生成每日总结 |
| Dataview 集成 | ✅ | 自然语言生成 DQL 查询 |
| 性能优化 | ✅ | VaultIndexer/NoteParser/React/main.js 全面优化 |
| 性能监控 | ✅ | Logger startTimer/endTimer API |

### 📋 待办（v0.4.0 规划中）

> v0.3.0 已完成全部性能优化，欢迎提出新功能建议！

| 功能建议 | 优先级 | 说明 |
|----------|--------|------|
| 图片/附件 OCR 支持 | P1 | AI 理解知识库中的图片内容 |
| 语音输入/输出 | P2 | 语音转文字 + TTS 朗读 |
| 本地模型支持 (Ollama) | P2 | 完全离线的 AI 推理 |
| 知识库问答增强 | P2 | RAG 检索增强生成 |
| 插件国际化 (i18n) | P3 | 多语言界面支持 |

## 技术栈

| 层级 | 技术 |
|------|------|
| 语言 | TypeScript (ES2020) |
| 构建 | esbuild + tsc |
| 前端 | React 18 + Context API |
| 后端通信 | 原生 HTTP + fetch SSE |
| 编辑器 | CodeMirror 6 (Ghost Text) |
| 测试 | Vitest |
| Git 集成 | simple-git |
| 加密 | Node.js crypto (AES-256-GCM) |

## 架构概览

```
┌─────────────────────────────────────────────────────┐
│                   Obsidian 桌面端                     │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌──────────────┐    ┌──────────────────────────┐   │
│  │  main.ts     │    │  FakeWebview 桥接层       │   │
│  │  (插件入口)   │◄──►│  (模拟 VS Code Webview)   │   │
│  └──────┬───────┘    └────────────┬─────────────┘   │
│         │                         │                 │
│    ┌────┴────┐            ┌───────┴────────┐       │
│    │ Views   │            │  React App     │       │
│    │ - Chat  │            │  (webview/)    │       │
│    │ - Diff  │            │  - ChatPanel   │       │
│    │ - Agent │            │  - MessageBubble│      │
│    │ - Market│            │  - SessionSidebar│     │
│    └────┬────┘            └────────────────┘       │
│         │                                          │
│    ┌────┴────────────────────────────┐             │
│    │  核心服务 (src/)                 │             │
│    │  - connection/  后端连接管理     │             │
│    │  - editor/      编辑器操作       │             │
│    │  - settings/    配置 + 加密存储  │             │
│    │  - vault/       Vault 索引搜索   │             │
│    │  - permissions/ 权限审批         │             │
│    │  - agent/       Agent 管理       │             │
│    │  - marketplace/ 技能市场         │             │
│    └────────────────┬────────────────┘             │
│                     │                              │
│              ┌──────┴──────┐                       │
│              │  opencode   │                       │
│              │  CLI 进程    │                       │
│              │  (HTTP+SSE) │                       │
│              └─────────────┘                       │
│                                                     │
└─────────────────────────────────────────────────────┘
```

## 项目文档

### 开发文档

| 文档 | 位置 | 内容 |
|------|------|------|
| 项目规范 | [PROJECT.md](./PROJECT.md) | 每个目录/文件的职责说明 |
| Agent 指南 | [AGENTS.md](./AGENTS.md) | 新 agent 快速上手指南 |
| 开发状态 | [TODO.md](./TODO.md) | 已完成和待办任务清单 |
| 测试方法 | [docs/TESTING.md](./docs/TESTING.md) | 测试编写和运行指南 |

### 设计文档

| 文档 | 位置 | 内容 |
|------|------|------|
| 功能总览 | [docs/01-功能总览.md](./docs/01-功能总览.md) | Kilo Code 14 大功能分析 |
| 技术拆解 | [docs/02-技术拆解.md](./docs/02-技术拆解.md) | 每个模块的实现细节 |
| 功能取舍 | [docs/03-功能取舍.md](./docs/03-功能取舍.md) | Obsidian 场景下做哪些不做哪些 |
| PRD | [docs/04-PRD.md](./docs/04-PRD.md) | 产品需求文档 |
| 技术架构 | [docs/05-技术架构.md](./docs/05-技术架构.md) | 技术架构设计 |
| 项目结构 | [docs/06-项目结构.md](./docs/06-项目结构.md) | 目录结构设计 |
| 开发路线 | [docs/07-开发路线.md](./docs/07-开发路线.md) | 12 个 Phase 的开发计划 |
| UI 设计 | [docs/08-UI设计.md](./docs/08-UI设计.md) | 界面布局和交互设计 |
| 数据模型 | [docs/09-数据模型.md](./docs/09-数据模型.md) | 类型定义和数据结构 |
| 错误处理 | [docs/10-错误处理.md](./docs/10-错误处理.md) | 错误策略和重试逻辑 |
| 实施手册 | [docs/11-实施手册.md](./docs/11-实施手册.md) | 从零搭建的详细步骤 |
| 测试策略 | [docs/12-测试策略.md](./docs/12-测试策略.md) | 测试分层和清单 |
| 开发准备 | [docs/13-开发准备.md](./docs/13-开发准备.md) | 环境搭建和开发准备 |

## 开发者指南

### 环境要求

- Node.js >= 18
- npm >= 9
- Obsidian >= 1.5.0（桌面端 + 移动端）
- opencode 二进制（通过 `node scripts/download-binary.mjs` 自动下载）

### 开发命令

```bash
npm install          # 安装依赖
npm run dev          # esbuild watch 模式（开发时运行）
npm run build        # tsc 类型检查 + esbuild 生产构建
npm test             # vitest 运行所有单元测试
npm run test:watch   # vitest watch 模式
npm run test:e2e     # Playwright E2E 测试
```

### 项目结构

```
obsidian-kilo/
├── src/                    # 插件主代码
│   ├── main.ts             # 插件入口
│   ├── constants.ts        # 常量定义
│   ├── types.ts            # 全局类型
│   ├── connection/         # opencode 进程管理 + SSE 连接
│   ├── bridge/             # FakeWebview + ReactMount 桥接层
│   ├── core/               # KiloClient + EventBus
│   ├── editor/             # 右键菜单 + 编辑器操作
│   ├── views/              # Obsidian ItemView
│   ├── settings/           # DataStore + CryptoStore + SettingTab
│   ├── vault/              # Vault 索引 + 笔记解析 + 搜索
│   ├── permissions/        # 权限审批 + 自动审批规则
│   ├── agent/              # Agent 管理 + 批量操作
│   └── marketplace/        # Marketplace 搜索/安装/卸载
├── webview/                # React 前端组件
│   ├── app.tsx             # 根组件
│   ├── components/         # UI 组件
│   ├── context/            # React Context
│   └── hooks/              # 自定义 Hooks
├── tests/                  # Vitest 单元测试 + Playwright E2E
│   ├── __mocks__/          # Mock 文件
│   ├── unit/               # 单元测试 (26 文件)
│   ├── integration/        # 集成测试 (3 文件)
│   └── e2e/                # E2E 测试 (7 文件)
├── docs/                   # 项目文档
├── manifest.json           # Obsidian 插件清单
├── package.json            # npm 包配置
├── tsconfig.json           # TypeScript 配置
├── esbuild.config.mjs      # 构建脚本（webview 内联打包）
├── styles.css              # 插件全局样式
├── AGENTS.md               # Agent 接手指南
├── PROJECT.md              # 项目规范文档
└── TODO.md                 # 开发状态
```

## 参考项目

- **上游**：[Kilo-Org/kilocode](https://github.com/Kilo-Org/kilocode)
- 核心包：`packages/opencode`（后端）、`packages/app`（前端）、`packages/kilo-vscode`（VS Code 壳）

## 许可证

MIT