770 Readme Cn D821373f

<p align="center">
  <img src="docs/assets/logo.png" alt="OpenAkita Logo" width="200" />
</p>

<h1 align="center">OpenAkita</h1>

<p align="center">
  <strong>忠诚可靠的 AI 伙伴</strong>
</p>

<p align="center">
  <a href="https://github.com/openakita/openakita/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" />
  </a>
  <a href="https://www.python.org/downloads/">
    <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python Version" />
  </a>
  <a href="https://github.com/openakita/openakita/releases">
    <img src="https://img.shields.io/github/v/release/openakita/openakita" alt="Release" />
  </a>
  <a href="https://github.com/openakita/openakita/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/openakita/openakita/ci.yml?branch=main" alt="Build Status" />
  </a>
</p>

<p align="center">
  <a href="#特性">特性</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#文档">文档</a> •
  <a href="#架构">架构</a> •
  <a href="#贡献">贡献</a>
</p>

<p align="center">
  <a href="./README.md">📖 English Documentation</a>
</p>

---

## 什么是 OpenAkita？

OpenAkita 是一个**自进化 AI 助手** — 你在数字世界中忠诚可靠的伙伴。

就像它名字来源的秋田犬一样，OpenAkita 具备这些品质：
- 🤝 **忠诚伙伴** — 始终陪伴在你身边，随时准备帮助你
- 🧠 **与你共同成长** — 记住你的偏好，变得越来越懂你
- 💪 **可靠搭档** — 承诺完成任务，不轻言放弃
- 🛡️ **值得信赖** — 保护你的数据安全，尊重你的隐私

OpenAkita 不只是一个工具 — 它是一个记住你、理解你、与你并肩面对每个挑战的伙伴。

### 为什么选择 OpenAkita？

- **🔄 自我进化**：自动从 GitHub 搜索技能或生成代码获取新能力
- **💪 永不放弃**：持续执行直到任务完成
- **🛠️ 工具执行**：原生支持 Shell 命令、文件操作和 Web 请求
- **🔌 MCP 集成**：通过 Model Context Protocol 连接浏览器、数据库等外部服务
- **💬 多平台部署**：CLI、Telegram、飞书 完整支持（文字、语音、图片、文件）；企业微信、钉钉已实现

## 特性

| 特性 | 描述 |
|------|------|
| **Ralph Wiggum 模式** | 持续执行循环 - 任务未验证完成不会终止 |
| **Plan 模式** | 智能多步骤任务规划与执行，实时进度追踪 |
| **自我进化** | 搜索 GitHub 获取技能，安装依赖，或即时生成代码 |
| **工具调用** | 执行 Shell 命令、文件操作、HTTP 请求，内置安全机制 |
| **MCP 支持** | 集成 Model Context Protocol 服务器，支持浏览器自动化、数据库 |
| **多轮对话** | 上下文感知对话，支持持久化记忆 |
| **多平台** | CLI、Telegram、飞书（完整支持：文字/语音/图片/文件）；企业微信、钉钉、QQ（已实现，未测试） |

### Plan 模式（多步骤任务管理）

对于需要多个步骤完成的复杂任务，OpenAkita 会自动激活 **Plan 模式**，确保可靠执行：

#### 工作原理

```
┌─────────────────────────────────────────────────────────────┐
│                       Plan 模式                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   用户请求                                                    │
│        ↓                                                     │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  多步骤检测                                          │   │
│   │  • 5+ 个动作词（复杂任务）                           │   │
│   │  • 3+ 个动作词 + 连接词（"然后"、"接着"）            │   │
│   │  • compound 复合任务类型                             │   │
│   └─────────────────────────────────────────────────────┘   │
│        ↓                                                     │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  create_plan → 执行步骤 → update_plan_step          │   │
│   │       ↓            ↓              ↓                 │   │
│   │   创建计划      工具调用      进度追踪               │   │
│   │       ↓            ↓              ↓                 │   │
│   │   通知用户      实时执行      状态更新               │   │
│   └─────────────────────────────────────────────────────┘   │
│        ↓                                                     │
│   complete_plan → 生成总结报告                               │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

#### 功能特点

| 功能 | 描述 |
|------|------|
| **自动检测** | 智能识别多步骤任务 |
| **计划优先** | 强制先创建计划再执行 |
| **进度追踪** | 实时更新每个步骤状态 |
| **用户通知** | 向 IM 通道推送执行进度 |
| **持久化保存** | 计划保存为 Markdown 文件 |
| **步骤依赖** | 支持步骤间依赖关系 |

#### 使用示例

```
用户: "打开百度搜索天气并截图发我"

📋 任务计划：在百度搜索天气并截图
├─ 1. 启动浏览器并访问百度
├─ 2. 输入搜索关键词
├─ 3. 点击搜索按钮
└─ 4. 截图并发送

执行过程：
✅ [1/4] 启动浏览器 - 已完成
✅ [2/4] 输入关键词 - 已完成
✅ [3/4] 点击搜索 - 已完成
✅ [4/4] 截图发送 - 已完成

🎉 任务完成！4/4 步骤成功执行。
```

#### Plan 工具

| 工具 | 描述 |
|------|------|
| `create_plan` | 创建包含步骤的执行计划 |
| `update_plan_step` | 更新步骤状态（pending/in_progress/completed/failed） |
| `get_plan_status` | 获取当前计划进度 |
| `complete_plan` | 标记计划完成，生成总结 |

### 自维护系统

OpenAkita 的"睡眠周期" — 夜间自动维护：

| 功能 | 执行时间 | 描述 |
|------|----------|------|
| **记忆整理** | 凌晨 3:00 | 整理当日对话，转化为长期记忆 |
| **自检修复** | 凌晨 4:00 | 分析错误日志，自动修复工具问题，生成报告 |
| **任务复盘** | 长任务后 | 回顾执行过程，提取经验教训 |
| **循环检测** | 实时 | 防止无限循环 |

#### 工作原理

```
┌─────────────────────────────────────────────────────────────┐
│                       自维护系统                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────┐    ┌─────────────────┐                 │
│  │    日志系统      │    │    记忆系统      │                 │
│  │  • 文件轮转     │    │  • 记忆整理      │                 │
│  │  • 自动清理     │    │  • 语义去重      │                 │
│  │  • ERROR 过滤   │    │  • 向量检索      │                 │
│  └────────┬────────┘    └────────┬────────┘                 │
│           │                      │                           │
│           └──────────┬───────────┘                           │
│                      ▼                                       │
│           ┌─────────────────────┐                            │
│           │    每日系统自检      │                            │
│           │  • 分析错误日志     │                            │
│           │  • LLM 诊断分析     │                            │
│           │  • 自动修复工具     │                            │
│           │  • 生成检查报告     │                            │
│           └─────────────────────┘                            │
│                                                              │
│  错误分类处理:                                                │
│  • 核心组件 (Brain/Memory/Scheduler) → 仅报告，不自动修复    │
│  • 工具组件 (Shell/File/Web/MCP)     → 自动修复，自我测试    │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

#### 配置说明

```bash
# 日志设置
LOG_LEVEL=INFO
LOG_DIR=logs
LOG_RETENTION_DAYS=30

# 系统任务（不可删除，可禁用）
# 凌晨 3:00 执行记忆整理
# 凌晨 4:00 执行系统自检
```

## 快速开始

> ⚠️ **早期阶段项目**：本项目仍在早期开发阶段，部分功能可能不完善。建议使用 AI 编程助手如 [Cursor](https://cursor.sh/)、[Claude](https://claude.ai/) 或 [GitHub Copilot](https://github.com/features/copilot) 来协助部署和排查问题。

### 前置要求

- Python 3.11 或更高版本
- LLM API 密钥（Anthropic、OpenAI 兼容接口、或其他模型）

### 推荐模型

| 模型 | 厂商 | 说明 |
|------|------|------|
| `claude-sonnet-4-5-*` | Anthropic | 默认，性能均衡 |
| `claude-opus-4-5-*` | Anthropic | 能力最强 |
| `qwen3-max` | 阿里通义 | 中文能力强 |
| `minimax-2.1` | MiniMax | 对话创作出色 |
| `kimi-2.5` | 月之暗面 | 超长上下文 |

> 💡 **建议**：复杂任务建议开启"扩展思考"模式。将模型设为 `*-thinking` 版本（如 `claude-opus-4-5-20251101-thinking`）可获得更好的推理效果。

### 快速安装（推荐）

**一行命令安装，交互式配置向导：**

```bash
# 从 PyPI 安装
pip install openakita

# 运行配置向导（交互式引导配置）
openakita init
```

配置向导将引导你完成：
- LLM API 配置（API 密钥、模型选择）
- IM 通道设置（可选：Telegram、飞书等）
- 记忆系统配置
- 目录结构创建

**或使用一键安装脚本：**

```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/openakita/openakita/main/scripts/quickstart.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/openakita/openakita/main/scripts/quickstart.ps1 | iex
```

### 手动安装

```bash
# 克隆仓库
git clone https://github.com/openakita/openakita.git
cd openakita

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装
pip install -e .

# 运行配置向导
openakita init

# 或手动配置
cp examples/.env.example .env
# 编辑 .env 添加你的 API 密钥
```

### 配置

创建 `.env` 文件，至少包含：

```bash
# 必需
ANTHROPIC_API_KEY=你的API密钥

# 可选：自定义 API 端点
ANTHROPIC_BASE_URL=https://api.anthropic.com

# 可选：模型选择
DEFAULT_MODEL=claude-sonnet-4-20250514
```

### 运行

```bash
# 交互式 CLI 模式
openakita

# 执行单个任务
openakita run "创建一个带测试的 Python 计算器"

# 查看状态
openakita status

# 运行自检
openakita selfcheck
```

## 文档

| 文档 | 描述 |
|------|------|
| [📖 快速开始](docs/getting-started.md) | 安装和入门指南 |
| [🏗️ 架构设计](docs/architecture.md) | 系统设计和组件说明 |
| [🔧 配置说明](docs/configuration.md) | 所有配置选项详解 |
| [🚀 部署指南](docs/deploy.md) | 生产环境部署指南 |
| [🔌 MCP 集成](docs/mcp-integration.md) | 连接外部服务 |
| [📱 IM 通道](docs/im-channels.md) | Telegram、钉钉、飞书配置 |
| [🎯 技能系统](docs/skills.md) | 创建和使用技能 |
| [🧪 测试框架](docs/testing.md) | 测试框架和覆盖率 |

## 架构

```
┌─────────────────────────────────────────────────────────────┐
│                         OpenAkita                              │
├─────────────────────────────────────────────────────────────┤
│   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│   │ SOUL.md │  │AGENT.md │  │ USER.md │  │MEMORY.md│       │
│   │  (灵魂)  │  │  (行为)  │  │  (用户)  │  │  (记忆)  │       │
│   └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘       │
│        └────────────┴────────────┴────────────┘            │
│                           ↓                                 │
│   ┌─────────────────────────────────────────────────────┐  │
│   │                    Agent 核心                        │  │
│   │  ┌─────────┐  ┌──────────┐  ┌─────────────────────┐ │  │
│   │  │  Brain  │  │ Identity │  │   Ralph Loop        │ │  │
│   │  │(Claude) │  │  (身份)   │  │  (永不放弃循环)      │ │  │
│   │  └─────────┘  └──────────┘  └─────────────────────┘ │  │
│   └─────────────────────────────────────────────────────┘  │
│                           ↓                                 │
│   ┌─────────────────────────────────────────────────────┐  │
│   │                     工具层                           │  │
│   │  ┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐        │  │
│   │  │ Shell │  │ 文件   │  │  Web  │  │  MCP  │        │  │
│   │  └───────┘  └───────┘  └───────┘  └───────┘        │  │
│   └─────────────────────────────────────────────────────┘  │
│                           ↓                                 │
│   ┌─────────────────────────────────────────────────────┐  │
│   │                   进化引擎                           │  │
│   │  ┌──────────┐  ┌───────────┐  ┌────────────────┐   │  │
│   │  │ Analyzer │  │ Installer │  │ SkillGenerator │   │  │
│   │  │ (需求分析) │  │ (自动安装) │  │   (技能生成)    │   │  │
│   │  └──────────┘  └───────────┘  └────────────────┘   │  │
│   └─────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### 核心文档

OpenAkita 使用独特的基于文档的身份和记忆系统：

| 文档 | 用途 |
|------|------|
| `identity/SOUL.md` | 核心哲学和价值观 - Agent 的"灵魂" |
| `identity/AGENT.md` | 行为规范和工作流程 |
| `identity/USER.md` | 用户档案、偏好和上下文 |
| `identity/MEMORY.md` | 工作记忆、任务进度、经验教训 |

### Ralph Wiggum 模式

Agent 在持续循环中运行：

```
接收任务 → 分析 → 执行 → 验证 → 重复直到完成
              ↓
         遇到失败时：
         1. 分析错误原因
         2. 搜索 GitHub 寻找解决方案
         3. 安装或生成修复代码
         4. 重试任务
```

## 使用示例

### 多轮对话

```
用户: 我叫张三，今年25岁
Agent: 你好，张三！很高兴认识你。

用户: 我叫什么名字？
Agent: 你叫张三，今年25岁。
```

### 复杂任务执行

```
用户: 在 /tmp/calc 目录创建一个 Python 计算器项目，包含加减乘除函数和测试

Agent: 正在执行任务...
  [工具调用] 创建目录结构...
  [工具调用] 写入 calculator.py...
  [工具调用] 写入 test_calculator.py...
  [工具调用] 运行测试...

✅ 任务完成！16 个测试全部通过。
```

### 自我进化

```
用户: 帮我分析这个 Excel 文件

Agent: 检测到需要 Excel 处理能力...
Agent: 搜索 GitHub 找到 openpyxl...
Agent: 正在安装 openpyxl...
Agent: 安装完成，开始分析文件...
```

## 项目结构

```
openakita/
├── identity/               # Agent 身份配置
│   ├── SOUL.md             # Agent 核心哲学
│   ├── AGENT.md            # 行为规范
│   ├── USER.md             # 用户档案
│   └── MEMORY.md           # 工作记忆
├── src/openakita/
│   ├── core/               # 核心模块
│   │   ├── agent.py        # Agent 主类
│   │   ├── brain.py        # Claude API 集成
│   │   ├── ralph.py        # Ralph 循环引擎
│   │   ├── identity.py     # 身份系统
│   │   └── memory.py       # 记忆管理
│   ├── tools/              # 工具实现
│   │   ├── shell.py        # Shell 执行
│   │   ├── file.py         # 文件操作
│   │   ├── web.py          # HTTP 请求
│   │   └── mcp.py          # MCP 桥接
│   ├── evolution/          # 自我进化
│   │   ├── analyzer.py     # 需求分析
│   │   ├── installer.py    # 自动安装
│   │   └── generator.py    # 技能生成
│   ├── channels/           # IM 集成
│   │   └── adapters/       # 平台适配器
│   ├── skills/             # 技能系统
│   ├── storage/            # 持久化层
│   └── testing/            # 测试框架
├── skills/                 # 本地技能目录
├── plugins/                # 插件目录
├── data/                   # 数据存储
└── docs/                   # 文档
```

## 测试覆盖

| 类别 | 数量 | 描述 |
|------|------|------|
| QA/基础问答 | 30 | 数学、编程知识、常识 |
| QA/推理 | 35 | 逻辑推理、代码理解 |
| QA/多轮对话 | 35 | 上下文记忆、指令跟随 |
| 工具/Shell | 40 | 命令执行、文件操作 |
| 工具/文件 | 30 | 读写、搜索、目录操作 |
| 工具/API | 30 | HTTP 请求、状态码 |
| 搜索/Web | 40 | HTTP、GitHub 搜索 |
| 搜索/代码 | 30 | 本地代码搜索 |
| 搜索/文档 | 30 | 项目文档搜索 |
| **总计** | **300** | |

## 部署方式

### CLI 模式（默认）

```bash
openakita
```

### Telegram 机器人

```bash
# 在 .env 中启用
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=你的token

# 运行
python scripts/run_telegram_bot.py
```

### Docker

```bash
docker build -t openakita .
docker run -d --name openakita -v $(pwd)/.env:/app/.env openakita
```

### Systemd 服务

```bash
sudo cp openakita.service /etc/systemd/system/
sudo systemctl enable openakita
sudo systemctl start openakita
```

详细部署说明请参阅 [docs/deploy.md](docs/deploy.md)。

## 贡献

我们欢迎各种形式的贡献！请查看 [贡献指南](CONTRIBUTING.md) 了解详情。

### 快速贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 开发环境设置

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 类型检查
mypy src/

# 代码检查
ruff check src/
```

## 社区

加入我们的社区，获取帮助、分享经验、参与讨论！

### 即时交流

<table>
  <tr>
    <td align="center">
      <img src="docs/assets/wechat_group.jpg" width="200" alt="微信群二维码" /><br/>
      <b>微信交流群</b><br/>
      <sub>扫码加入中文社区</sub>
    </td>
    <td>
      <b>💬 微信群</b> - 中文用户即时交流<br/><br/>
      <b>🎮 Discord</b> - <a href="https://discord.gg/Mkpd3rsm">加入 Discord</a><br/><br/>
      <b>🐦 X (Twitter)</b> - <a href="https://x.com/openakita">@openakita</a><br/><br/>
      <b>📧 邮箱</b> - <a href="mailto:zacon365@gmail.com">zacon365@gmail.com</a>
    </td>
  </tr>
</table>

### 项目互动

- 📖 [文档](docs/) - 完整使用指南
- 🐛 [问题追踪](https://github.com/openakita/openakita/issues) - 报告 Bug、请求功能
- 💬 [讨论区](https://github.com/openakita/openakita/discussions) - 技术讨论、问答
- ⭐ [Star 项目](https://github.com/openakita/openakita) - 支持我们

## 致谢

OpenAkita 站在巨人的肩膀上：

- [Anthropic Claude](https://www.anthropic.com/claude) - 核心 LLM 引擎
- [browser-use](https://github.com/browser-use/browser-use) - AI 浏览器自动化
- [Claude Soul Document](https://gist.github.com/Richard-Weiss/efe157692991535403bd7e7fb20b6695) - 灵魂文档灵感来源
- [Ralph Playbook](https://claytonfarr.github.io/ralph-playbook/) - Ralph Wiggum 模式哲学
- [AGENTS.md Standard](https://agentsmd.io/) - Agent 行为规范标准

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

---

<p align="center">
  <strong>OpenAkita — 忠诚可靠的 AI 伙伴</strong>
</p>

<p align="center">
  <a href="#openakita">返回顶部 ↑</a>
</p>