CraftOS-dev
diff --git a/‎README.cn.md‎
Lines changed: 236 additions & 8 deletions b/‎README.cn.md‎
Lines changed: 236 additions & 8 deletions
@@ -61,7 +61,53 @@
 
 ## 🧰 快速开始
 
-环境要求: Python 3.10+ · 浏览器模式需要 Node.js 18+
+- **自带密钥 (BYOK)** — 灵活的 LLM 提供商系统，支持 OpenAI、Google Gemini、Anthropic Claude、BytePlus 和本地 Ollama 模型。可轻松切换提供商。
+- **记忆系统** — 在午夜整理并汇总一天中发生的事件。
+- **主动式代理** — 学习你的偏好、习惯和人生目标，然后进行规划并启动任务（当然需要你的批准）来帮助你改善生活。
+- **Living UI** — 在 CraftBot 中构建、导入或演进自定义应用。代理始终感知 UI 的状态，并可直接读取、写入和操作其数据。
+- **外部工具集成** — 连接 Google Workspace、Slack、Notion、Zoom、LinkedIn、Discord 和 Telegram（更多即将推出！），支持嵌入式凭据和 OAuth。
+- **MCP** — 模型上下文协议（Model Context Protocol）集成，通过外部工具和服务扩展代理能力。
+- **技能系统** — 可扩展的技能框架，内置任务规划、研究、代码审查、Git 操作等技能。
+- **跨平台** — 完整支持 Windows、macOS 和 Linux，具有平台特定代码变体和 Docker 容器化。
+
+> [!IMPORTANT]
+> **GUI 模式已弃用。** CraftBot 不再支持 GUI（桌面自动化）模式。请改用 Browser 或 CLI 模式。
+
+<div align="center">
+    <img src="assets/craftbot_readme_features.png" alt="CraftBot Banner" width="1280"/>
+	<img src="assets/craftbot_features_custom.png" alt="CraftBot Banner" width="1280"/>
+</div>
+
+---
+
+
+## 🧰 环境设置
+
+### 前置要求
+- Python **3.10+**
+- `git`（克隆仓库所需）
+- 你所选 LLM 提供商的 API Key（OpenAI、Gemini 或 Anthropic）
+- `Node.js` **18+**（可选 - 仅浏览器界面需要）
+- `conda`（可选 - 如未找到，安装器会提供自动安装 Miniconda 的选项）
+
+### 我该选哪种方式？
+
+> **不确定？选方案一。** 它会帮你搞定所有事。
+
+| | 方案一 — 服务安装 | 方案二 — Conda 安装 | 方案三 — 手动安装 |
+|---|---|---|---|
+| **适合谁** | 大多数用户、新手、测试 | 想要独立环境的 Conda 用户 | 进阶用户、自定义 Python、完全控制 |
+| **自动管理 Python 环境？** | ✅ 自动 | ✅ 自动 | ❌ 你自己管理 |
+| **后台运行？** | ✅ 是，作为服务 | ❌ 否 | ❌ 否 |
+| **启动方式** | `python craftbot.py install` | `python install.py --conda` | `python install.py` |
+
+---
+
+### ⭐ 方案一 — 服务安装（推荐）
+
+**适合你，如果：** 你希望 CraftBot 开箱即用——后台服务、开机自启、桌面快捷方式，无需手动操作。
+
+`craftbot.py` 全程自动处理：Python 环境、依赖安装、后台进程管理和自启注册。
 
 ```bash
 # 1. 克隆仓库
@@ -98,7 +144,79 @@ python craftbot.py uninstall  # 停止运行、移除自启动并卸载所有依
 - 一套完全贴合你工作流的定制 CRM?
 - 一个 CraftBot 能替你读取并操作的公司仪表盘?
 
-把它作为一个 Living UI 与 CraftBot 一同运行,并让它随着你的需求持续成长。
+```bash
+# 1. 克隆仓库
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. 安装到 conda 环境
+python install.py --conda
+
+# 3. 运行 CraftBot
+conda run -n craftbot python run.py
+
+# 如果 conda 不在 PATH 中（仅 Windows）：
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+> [!NOTE]
+> 每次运行 CraftBot 时，请使用 `conda run -n craftbot python run.py`。此方式没有后台服务——由你手动启停。
+
+---
+
+### 方案三 — 手动安装（pip）
+
+**适合你，如果：** 你希望完全掌控 Python 环境，不需要任何自动服务或后台进程，自己管理 CraftBot。
+
+`install.py`（不带参数）会对当前激活的 Python 环境执行标准 pip 安装。通过 `run.py` 手动启停 CraftBot。
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. 在当前 Python 环境中安装依赖
+python install.py
+
+# 3. 运行 CraftBot
+python run.py
+```
+
+首次运行会引导你完成 API Key 设置和偏好配置。
+
+> [!NOTE]
+> 如果未安装 Node.js，安装器会提供详细指引。你也可以完全跳过浏览器模式，直接使用 CLI 模式——无需 Node.js：`python run.py --cli`
+
+### 安装完成后你可以做什么？
+- 用自然语言与代理交流
+- 让它执行复杂的多步骤任务
+- 输入 `/help` 查看可用命令
+- 连接 Google、Slack、Notion 等服务
+
+### 🖥️ 界面模式
+
+<div align="center">
+    <img src="assets/WCA_README_banner.png" alt="CraftOS Banner" width="1280"/>
+</div>
+
+CraftBot 支持多种 UI 模式。根据你的偏好选择：
+
+| 模式 | 命令 | 要求 | 最适合 |
+|------|---------|--------------|----------|
+| **浏览器** | `python run.py` | Node.js 18+ | 现代 Web 界面，最易使用 |
+| **CLI** | `python run.py --cli` | 无 | 命令行，轻量级 |
+
+**浏览器模式**是默认的推荐模式。如果你没有 Node.js，安装器会提供安装指引，或者你可以使用 **CLI 模式**。
+
+---
+
+## 🧬 Living UI
+
+**Living UI 是随你需求而进化的系统/应用/仪表盘。**
+
+需要一个内置 AI 副驾的看板？量身定制符合你工作流程的 CRM？
+一个 CraftBot 能读取并驱动的公司仪表盘？
+将它作为 Living UI 启动——它与 CraftBot 并行运行，并随着你的需求变化而成长。
 
 <div align="center">
     <img src="assets/living-ui-example.png" alt="Living UI example" width="1280"/>
@@ -144,7 +262,21 @@ CraftBot 嵌入在每个 Living UI 之中,并且**对其状态保持感知**:它
 - **📊 习惯追踪器** — 培养并追踪自己的习惯,用类 GitHub 风格的活动日历像写代码一样维护你的习惯。
 - **🐦 Luolinglo** — 不是多邻国,但你可以学习新语言、做单词卡片,并和 CraftBot 一起练习。
 
-**[浏览并参与贡献 Living UI 市场 →](https://craftos.net/marketplace)**
+## 🧩 架构概览
+
+| 组件 | 说明 |
+|-----------|-------------|
+| **代理基础层 (Agent Base)** | 核心编排层，管理任务生命周期、协调各组件并处理主要的代理循环。 |
+| **LLM 接口** | 统一接口，支持多个 LLM 提供商（OpenAI、Gemini、Anthropic、BytePlus、Ollama）。 |
+| **上下文引擎** | 生成优化的提示词，支持 KV-cache。 |
+| **动作管理器** | 从动作库中检索和执行动作。自定义动作易于扩展。 |
+| **动作路由器** | 根据任务需求智能选择最佳匹配的动作，需要时通过 LLM 解析输入参数。 |
+| **事件流** | 实时事件发布系统，用于任务进度跟踪、UI 更新和执行监控。 |
+| **记忆管理器** | 基于 RAG 的语义记忆，使用 ChromaDB。处理记忆分块、向量化、检索和增量更新。 |
+| **状态管理器** | 全局状态管理，跟踪代理执行上下文、对话历史和运行时配置。 |
+| **任务管理器** | 管理任务定义，支持简单和复杂任务模式，创建待办事项，多步骤工作流跟踪。 |
+| **技能管理器** | 加载并将可插拔技能注入代理上下文。 |
+| **MCP 适配器** | 模型上下文协议集成，将 MCP 工具转换为原生动作。 |
 
 ---
 
@@ -162,13 +294,109 @@ CraftBot 嵌入在每个 Living UI 之中,并且**对其状态保持感知**:它
 
 ## 🔧 故障排查与常见问题
 
-### 缺少 Node.js (浏览器模式)
-如果运行 `python run.py` 时看到 **"npm not found in PATH"**:
-1. 从 [nodejs.org](https://nodejs.org/) 下载 LTS 版本
-2. 安装后重启终端
+### install.py
+
+| 参数 | 说明 |
+|------|-------------|
+| `--conda` | 使用 conda 环境（可选） |
+
+### run.py
+
+| 参数 | 说明 |
+|------|-------------|
+| （无） | 以**浏览器**模式运行（推荐，需要 Node.js） |
+| `--cli` | 以 **CLI** 模式运行（轻量级） |
+
+**安装示例：**
+```bash
+# 简单 pip 安装（不使用 conda）
+python install.py
+
+# 使用 conda 环境（推荐 conda 用户使用）
+python install.py --conda
+```
+
+**运行 CraftBot：**
+
+```powershell
+# 浏览器模式（默认，需要 Node.js）
+python run.py
+
+# CLI 模式（轻量级）
+python run.py --cli
+
+# 使用 conda 环境
+conda run -n craftbot python run.py
+
+# 如果 conda 不在 PATH 中，使用完整路径
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+**Linux/macOS (Bash):**
+```bash
+# 浏览器模式（默认，需要 Node.js）
+python run.py
+
+# CLI 模式（轻量级）
+python run.py --cli
+
+# 使用 conda 环境
+conda run -n craftbot python run.py
+```
+
+### 🔧 后台服务（推荐）
+
+将 CraftBot 作为后台服务运行，关闭终端后仍可继续运行。系统会自动创建桌面快捷方式，随时可重新打开浏览器。
+
+```bash
+# 安装依赖、注册开机自启、启动 CraftBot
+python craftbot.py install
+```
+
+就这样。终端会自动关闭，CraftBot 在后台运行，浏览器自动打开。
+
+```bash
+# 其他服务命令：
+python craftbot.py start    # 在后台启动 CraftBot
+python craftbot.py status   # 检查是否正在运行
+python craftbot.py stop     # 停止 CraftBot
+python craftbot.py restart  # 重启 CraftBot
+python craftbot.py logs     # 查看最近日志输出
+```
+
+| 命令 | 说明 |
+|---------|-------------|
+| `python craftbot.py install` | 安装依赖、注册开机自启、启动 CraftBot、打开浏览器，并自动关闭终端 |
+| `python craftbot.py start` | 在后台启动 CraftBot（若已运行则自动重启，终端自动关闭） |
+| `python craftbot.py stop` | 停止 CraftBot |
+| `python craftbot.py restart` | 停止并重启 CraftBot |
+| `python craftbot.py status` | 检查 CraftBot 是否在运行，以及自动启动是否已启用 |
+| `python craftbot.py logs` | 显示最近日志（使用 `-n 100` 查看更多行） |
+| `python craftbot.py uninstall` | 停止 CraftBot、注销自启、卸载 pip 包并清理 pip 缓存 |
+
+> [!TIP]
+> 执行 `craftbot.py start` 或 `craftbot.py install` 后，系统会自动创建 **CraftBot 桌面快捷方式**。如果不小心关闭了浏览器，双击快捷方式即可重新打开。
+
+> [!NOTE]
+> **安装：** 安装器会在缺少依赖时提供清晰的指引。如果未找到 Node.js，会提示你安装或切换到 CLI 模式。安装会自动检测 GPU 可用性，必要时回退到仅 CPU 模式。
+
+> [!TIP]
+> **首次设置：** CraftBot 会引导你完成引导流程，配置 API Key、代理名称、MCP 和技能。
+
+> [!NOTE]
+> **Playwright Chromium：** WhatsApp Web 集成可选。如果安装失败，代理在其他任务上仍能正常工作。可稍后手动安装：`playwright install chromium`
+
+---
+
+## 🔧 故障排除与常见问题
+
+### 缺少 Node.js（浏览器模式）
+运行 `python run.py` 时看到 **"npm not found in PATH"**：
+1. 从 [nodejs.org](https://nodejs.org/) 下载（选择 LTS 版本）
+2. 安装并重启终端
 3. 再次运行 `python run.py`
 
-**备选方案:** 改用无需 Node.js 的 TUI 模式:
+**替代方案：** 使用 CLI 模式（不需要 Node.js）：
 ```bash
 python run.py --cli
 ```