docs: update README with improved installation and configuration guide

2026-04-09 23:17:07 +08:00
parent e693198727
commit 7d37914cbf
1 changed files with 243 additions and 57 deletions
@@ -13,6 +13,28 @@

 📺 **部署流程详解**：[Bilibili - MyClaude 完整部署指南](https://www.bilibili.com/video/BV15TPrzeELm/)

+## 项目结构
+
+```
+myclaude/
+├── .claude/               # Claude Code 配置
+│   └── skills/            # 自定义技能
+├── .venv/                 # Python 虚拟环境
+├── knowledge/             # 持久化记忆与知识库
+│   ├── memories/          # 记忆文件（自动加载）
+│   └── files/             # 长摘录、参考资料
+├── workspace/             # 工作目录
+│   ├── .obsidian/         # Obsidian 配置
+│   ├── myAcademia/        # → Obsidian 知识库（软链接）
+│   ├── myWebpage/         # → 课题组网站（软链接）
+│   ├── myagent/           # → myagent 项目（软链接）
+│   └── tmp/               # 临时文件
+├── myclaude/              # 源码目录
+├── CLAUDE.md              # 项目配置（自动生成）
+├── pyproject.toml         # Python 项目配置
+└── README.md              # 本文件
+```
+
 ## 快速开始

 ### 1. 安装 Claude Code
@@ -37,6 +59,14 @@ irm https://claude.ai/install.ps1 | iex
 > 
 > **来源**：[Claude Code 官方文档](https://code.claude.com/docs/en/quickstart)

+安装完成后，首次使用需登录：
+
+```bash
+claude login
+```
+
+> 💡 建议选择 **方案 2 (API Key)**，但将 API Token 留空，这样 Claude 会使用 cc-switch 的配置。
+
 ### 2. 开通大模型会员（推荐）

 | 服务 | 说明 | 开通地址 |
@@ -47,27 +77,114 @@ irm https://claude.ai/install.ps1 | iex

 ### 3. 安装 cc-switch（多模型切换）

-**macOS:**
+**方式 1：下载安装包（推荐，全平台通用）**
+
+访问 https://github.com/farion1231/cc-switch/releases 下载对应安装包：
+
+- **macOS**: `.dmg` 或 `.pkg`
+- **Linux**: `.deb` (Debian/Ubuntu) 或 `.rpm` (RHEL/CentOS)
+- **Windows**: `.msi`
+
+**方式 2：包管理器安装**
+
+macOS (Homebrew):

 ```bash
+brew update
 brew tap farion1231/tap
 brew install cc-switch
 ```

-**Windows:**
+Linux (Debian/Ubuntu):

-1. 访问 https://github.com/farion1231/cc-switch/releases
-2. 下载 `.msi` 安装包运行
+```bash
+# 下载 .deb 包后
+sudo dpkg -i cc-switch_*.deb
+# 如有依赖问题，运行：
+sudo apt-get install -f
+```
+
+Linux (RHEL/CentOS/Fedora):
+
+```bash
+sudo rpm -i cc-switch_*.rpm
+```

 **配置模型:**

+> 💡 **推荐 GUI 配置**：
+> 1. 启动 cc-switch 桌面应用
+> 2. 点击「Add」添加模型
+> 3. 选择模型类型（DeepSeek/Kimi/Claude 等），粘贴 API Key
+> 4. 点击「Set Default」设置默认模型
+>
+> **命令行配置**（可选）：
+> ```bash
+> cc-switch add deepseek --api-key YOUR_KEY
+> cc-switch add kimi --api-key YOUR_KEY
+> cc-switch default claude
+> ```
+
+### 4. 安装 myclaude
+
+**前置依赖：**
+
+| 工具 | 版本要求 | 说明 |
+|------|---------|------|
+| Python | 3.10+ | 项目运行环境 |
+| make | - | 构建工具（macOS/Linux 通常自带） |
+| git | - | 代码仓库管理 |
+| uv 或 pip | - | Python 包管理器，推荐 [uv](https://github.com/astral-sh/uv) |
+
+**检查依赖：**
+
 ```bash
-cc-switch add deepseek --api-key YOUR_KEY
-cc-switch add kimi --api-key YOUR_KEY
-cc-switch default claude
+python3 --version   # 需 >= 3.10
+make --version      # 确认已安装
+git --version       # 确认已安装
 ```

-### 4. 安装 Metabot
+**克隆并安装：**
+
+```bash
+# 克隆到本地
+git clone <repository-url> ~/your-path/myclaude
+cd ~/your-path/myclaude
+
+# 安装（会自动检测并使用 uv 或 pip）
+make install
+```
+
+> 💡 **提示**：如未安装 uv，会使用系统 pip 安装，速度稍慢
+
+**配置快捷命令：**
+
+将 `myclaude` 添加到 shell 配置，方便全局调用：
+
+```bash
+# 编辑 ~/.zshrc 或 ~/.bashrc
+MYCLAUDE_PATH="$HOME/your-path/myclaude"  # 修改为你的实际路径
+if [ -d "$MYCLAUDE_PATH/.venv/bin" ]; then
+  alias myclaude=$MYCLAUDE_PATH/.venv/bin/myclaude
+  eval "$(_MYCLAUDE_COMPLETE=zsh_source myclaude)"  # zsh 补全
+  # eval "$(_MYCLAUDE_COMPLETE=bash_source myclaude)"  # bash 补全
+fi
+
+# 使配置生效
+source ~/.zshrc  # 或 source ~/.bashrc
+```
+
+验证并启动：
+
+```bash
+# 验证安装
+myclaude --version
+
+# 启动本地交互模式
+myclaude chat
+```
+
+### 5. 安装 Metabot

 **快速安装:**

@@ -81,9 +198,51 @@ irm https://raw.githubusercontent.com/xvirobotics/metabot/main/install.ps1 | iex

 安装器会引导完成：工作目录设置 → Claude 认证 → IM 平台选择 → 机器人配置 → PM2 自启动

-### 5. 配置飞书机器人
+**配置环境变量：**

-#### 5.1 创建飞书应用
+Metabot 命令安装后需要添加到 PATH：
+
+```bash
+# 1. 确定 shell 类型
+echo $SHELL
+# /bin/zsh  → 编辑 ~/.zshrc
+# /bin/bash → 编辑 ~/.bashrc (Linux) 或 ~/.bash_profile (macOS)
+
+# 2. 添加 PATH
+export PATH="$PATH:$HOME/.local/bin"
+
+# 3. 使配置生效（二选一）
+source ~/.zshrc      # 或 source ~/.bashrc
+# 或：重开一个终端窗口
+```
+
+**启用命令自动补全（可选）：**
+
+```bash
+# zsh: 编辑 ~/.zshrc
+fpath=($HOME/.local/bin/completions $fpath)
+autoload -Uz compinit && compinit
+
+# bash: 编辑 ~/.bashrc
+for f in $HOME/.local/bin/completions/*; do
+  [ -f "$f" ] && source "$f"
+done
+```
+
+**基本命令：**
+
+```bash
+metabot start      # 启动飞书机器人
+metabot stop       # 停止机器人
+metabot restart    # 重启机器人
+metabot status     # 查看运行状态
+metabot logs -f    # 查看实时日志
+metabot update     # 更新到最新版本
+```
+
+### 6. 配置飞书机器人
+
+#### 6.1 创建飞书应用

 1. 访问 [飞书开发者平台](https://open.feishu.cn/)
 2. 创建企业自建应用，添加「机器人」能力
@@ -96,7 +255,7 @@ irm https://raw.githubusercontent.com/xvirobotics/metabot/main/install.ps1 | iex
   - 订阅方式选择「长连接」（无需公网 IP）
   - 或在「请求地址配置」中填写回调 URL（需要 HTTPS）

-#### 5.2 配置 bots.json
+#### 6.2 配置 bots.json

 在 `metabot/bots.json` 创建配置（与 myclaude 项目同级目录）:

@@ -107,46 +266,20 @@ irm https://raw.githubusercontent.com/xvirobotics/metabot/main/install.ps1 | iex
      "name": "myclaude",
      "feishuAppId": "cli_xxxxx",
      "feishuAppSecret": "xxxxxxxxxxxxx",
-      "defaultWorkingDirectory": "~/Documents/myResearch/myProjects/apaam/repo/myclaude"
+      "defaultWorkingDirectory": "~/your-path/myclaude"
    }
  ]
 }
 ```

+> ⚠️ **注意**：请修改 `defaultWorkingDirectory` 为你本地的 myclaude 项目实际路径。
+
 > 💡 提示：飞书应用需要先发布，再开启「长连接」事件订阅

 ---

 ## 使用指南

-### 配置环境变量（首次）
-
-将 `metabot` 和 `myclaude` 命令添加到 PATH，方便全局调用：
-
-```bash
-# 编辑 zshrc
-vim ~/.zshrc
-
-# 添加以下行（根据实际安装路径调整）
-export PATH="$PATH:$HOME/.metabot/bin"
-export PATH="$PATH:$HOME/.local/bin"
-
-# 使配置生效
-source ~/.zshrc
-```
-
-> 💡 **提示**：Metabot 安装器通常会将命令安装到 `~/.metabot/bin/` 或 `~/.local/bin/`，请根据实际路径调整。
-
-### 启动服务
-
-```bash
-# 启动飞书机器人
-metabot start
-
-# 本地交互模式
-myclaude chat
-```
-
 ### 首次使用

 告诉 Claude：
@@ -164,7 +297,6 @@ myclaude chat
 **方式 2：本地终端**

 ```bash
-cd ~/Documents/myResearch/myProjects/apaam/repo/myclaude
 myclaude chat
 ```

@@ -205,6 +337,28 @@ cp SKILL.md ~/.claude/skills/my-skill/
 | `git-proxy-clone` | 加速 Git 下载 | `npx skills add -g xvirobotics/metabot@git-proxy-clone` |
 | `metabot` | 飞书 API 调用 | `npx skills add -g xvirobotics/metabot@metabot` |
 | `metamemory` | 共享知识库 | `npx skills add -g xvirobotics/metabot@metamemory` |
+| `lark-doc` | 飞书文档操作 | `npx skills add -g xvirobotics/metabot@lark-doc` |
+| `lark-im` | 飞书消息收发 | `npx skills add -g xvirobotics/metabot@lark-im` |
+| `lark-calendar` | 飞书日历管理 | `npx skills add -g xvirobotics/metabot@lark-calendar` |
+| `lark-task` | 飞书任务管理 | `npx skills add -g xvirobotics/metabot@lark-task` |
+| `lark-vc` | 飞书会议记录 | `npx skills add -g xvirobotics/metabot@lark-vc` |
+| `lark-drive` | 飞书云空间 | `npx skills add -g xvirobotics/metabot@lark-drive` |
+| `lark-base` | 飞书多维表格 | `npx skills add -g xvirobotics/metabot@lark-base` |
+| `lark-contact` | 飞书通讯录 | `npx skills add -g xvirobotics/metabot@lark-contact` |
+| `lark-sheets` | 飞书电子表格 | `npx skills add -g xvirobotics/metabot@lark-sheets` |
+| `lark-wiki` | 飞书知识库 | `npx skills add -g xvirobotics/metabot@lark-wiki` |
+| `lark-approval` | 飞书审批 | `npx skills add -g xvirobotics/metabot@lark-approval` |
+| `lark-whiteboard` | 飞书画板 | `npx skills add -g xvirobotics/metabot@lark-whiteboard` |
+| `lark-event` | 飞书事件订阅 | `npx skills add -g xvirobotics/metabot@lark-event` |
+| `lark-minutes` | 飞书妙记 | `npx skills add -g xvirobotics/metabot@lark-minutes` |
+| `lark-mail` | 飞书邮箱 | `npx skills add -g xvirobotics/metabot@lark-mail` |
+
+> 💡 **安装方式**：在 `myclaude chat` 或飞书对话中，直接告诉 Claude：
+> - "帮我安装处理 PDF 的 skill"
+> - "安装飞书日历相关的 skills"
+> - "我想用飞书文档功能，帮我安装"
+>
+> Claude 会自动帮你完成安装。

 ### Workspace 与资料管理

@@ -231,11 +385,13 @@ Claude 会自动执行：

 ## 常用指令

+> 💡 **以下指令在飞书机器人对话中直接输入使用**
+
 | 指令 | 说明 |
 |------|------|
 | `/help` | 显示帮助 |
-| `/reset` | 重置对话（飞书卡住时用） |
-| `/stop` | 停止当前任务 |
+| `/reset` | 开启新对话（重置上下文） |
+| `/stop` | 停止当前任务（卡住时用） |
 | `/skills` | 列出可用 skills |
 | `/memory` | 查看记忆内容 |

@@ -243,8 +399,9 @@ Claude 会自动执行：

 ## 常见问题

-**Q1: 飞书回复 error 或卡住**  
-发送 `/reset` 重置对话
+**Q1: 飞书回复 error 或卡住**
+- 卡住时发送 `/stop` 停止当前任务
+- 想开启新对话发送 `/reset`

 **Q2: 切换模型**  
 ```bash
@@ -269,22 +426,51 @@ cc-switch use deepseek

 ---

-## 项目结构
+## 维护与故障排查

+### 更新升级
+
+**Claude Code:**
+```bash
+claude update
 ```
-myclaude/
-├── .claude/
-│   ├── skills/          # 自定义技能
-│   ├── memory/          # 持久化记忆
-│   └── conversations/   # 对话记录
-├── workspace/           # 工作目录
-│   ├── archives/        # 归档资料
-│   ├── references/      # 参考资料
-│   └── templates/       # 常用模板
-├── CLAUDE.md            # 项目配置（自动生成）
-└── README.md            # 本文件
+
+**cc-switch:**
+```bash
+# macOS (Homebrew)
+brew upgrade cc-switch
+
+# 其他平台：下载最新安装包重新安装
 ```

+**Metabot:**
+```bash
+metabot update
+```
+
+### 卸载
+
+**Claude Code:**
+```bash
+claude uninstall
+```
+
+**cc-switch:**
+```bash
+# macOS
+brew uninstall cc-switch
+
+# 其他平台：使用系统包管理器或删除安装文件
+```
+
+**Metabot:**
+```bash
+rm -rf ~/.metabot
+rm ~/.local/bin/metabot
+```
+
+---
+
 ## License

 MIT