docs: restructure README for clarity

- Reorganize sections: Quick Start -> Usage Guide -> Advanced Config - Move Skill installation to Advanced Config section - Update Workspace management to emphasize telling Claude to do it - Simplify language and remove redundant content - Keep video tutorial and project structure sections
2026-04-07 09:35:16 +08:00
parent 9226df44b6
commit 2d9a20046f
1 changed files with 117 additions and 231 deletions
@@ -13,153 +13,90 @@

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

-## 准备工作
+## 快速开始

 ### 1. 安装 Claude Code

 **macOS/Linux:**

 ```bash
-# 官方安装脚本
 curl -fsSL https://claude.ai/install.sh | sh
-
-# 或使用 npm
-npm install -g @anthropic-ai/claude-code
+# 或使用 npm: npm install -g @anthropic-ai/claude-code
 ```

 **Windows:**

 ```powershell
-# 方式1：PowerShell 安装（推荐）
 irm https://claude.ai/install.ps1 | iex
-
-# 方式2：WinGet（Windows 包管理器）
-winget install Anthropic.ClaudeCode
-
-# 方式3：npm（需先安装 Node.js 18+）
-npm install -g @anthropic-ai/claude-code
+# 或: winget install Anthropic.ClaudeCode
 ```

-> **注意**：Windows 用户需先安装 [Git for Windows](https://git-scm.com/download/win)。2025 年后 Claude Code 已提供原生 Windows 支持，不再需要 WSL2。
->
+> **注意**：Windows 用户需先安装 [Git for Windows](https://git-scm.com/download/win)
+> 
 > **来源**：[Claude Code 官方文档](https://code.claude.com/docs/en/quickstart)

 ### 2. 开通大模型会员（推荐）

-为获得更好的使用体验，建议开通以下服务：
-
 | 服务 | 说明 | 开通地址 |
 |------|------|---------|
 | DeepSeek | 国产高性能大模型 | https://platform.deepseek.com |
 | Kimi | 长文本处理专家 | https://kimi.moonshot.cn |
 | Kimi Code | 代码专用模型 | Kimi 内开通 Code 会员 |

-### 3. 安装并配置 cc-switch
+### 3. 安装 cc-switch（多模型切换）

-cc-switch 用于在多个模型间快速切换：
-
-**macOS：**
+**macOS:**

 ```bash
-# 方式1：Homebrew（推荐）
 brew tap farion1231/tap
 brew install cc-switch
-
-# 方式2：从 GitHub Releases 下载
-# 访问 https://github.com/farion1231/cc-switch/releases 下载对应系统版本
 ```

-**Windows：**
+**Windows:**

-```powershell
-# 方式1：MSI 安装程序（推荐）
-# 1. 访问 https://github.com/farion1231/cc-switch/releases
-# 2. 下载 .msi 安装包并运行
-# 3. 从开始菜单或桌面快捷方式启动
+1. 访问 https://github.com/farion1231/cc-switch/releases
+2. 下载 `.msi` 安装包运行

-# 方式2：便携版（免安装）
-# 下载 .zip 版本，解压后直接运行
-```
-
-**配置模型**：
+**配置模型:**

 ```bash
-# 配置模型
-cc-switch add deepseek --api-key YOUR_DEEPSEEK_KEY
-cc-switch add kimi --api-key YOUR_KIMI_KEY
-cc-switch add kimi-code --api-key YOUR_KIMI_KEY
-
-# 设置默认模型
+cc-switch add deepseek --api-key YOUR_KEY
+cc-switch add kimi --api-key YOUR_KEY
 cc-switch default claude
 ```

-> **来源**：[CC Switch GitHub](https://github.com/farion1231/cc-switch)
-
 ### 4. 安装 Metabot

-Metabot 是飞书/Telegram/微信机器人的本地服务端，支持手机控制 Claude Code。
-
-**快速安装（全平台）：**
+**快速安装:**

 ```bash
-# macOS / Linux
+# macOS/Linux
 curl -fsSL https://raw.githubusercontent.com/xvirobotics/metabot/main/install.sh | bash
-```

-```powershell
 # Windows (PowerShell)
 irm https://raw.githubusercontent.com/xvirobotics/metabot/main/install.ps1 | iex
 ```

-**安装器会引导你完成：**
-1. 设置工作目录
-2. Claude Code 认证
-3. 选择 IM 平台（飞书/Telegram/微信）
-4. 配置机器人凭证
-5. PM2 自动启动设置
+安装器会引导完成：工作目录设置 → Claude 认证 → IM 平台选择 → 机器人配置 → PM2 自启动

-**手动安装（备选）：**
-
-```bash
-# 克隆仓库
-git clone https://github.com/xvirobotics/metabot.git
-cd metabot
-
-# 安装依赖
-npm install
-
-# 复制配置模板
-cp bots.example.json bots.json
-cp .env.example .env
-
-# 编辑配置
-# - bots.json: 添加飞书/ Telegram 机器人凭证
-# - .env: 设置 API_SECRET 和 Claude API Key
-
-# 启动
-npm run dev
-```
-
-> **来源**：[Metabot GitHub](https://github.com/xvirobotics/metabot)
-
-### 5. 开通飞书并配置机器人
+### 5. 配置飞书机器人

 #### 5.1 创建飞书应用

 1. 访问 [飞书开发者平台](https://open.feishu.cn/)
-2. 创建企业自建应用
-3. 启用机器人能力，获取 **AppID** 和 **AppSecret**
+2. 创建企业自建应用，添加「机器人」能力
+3. 获取 **AppID** 和 **AppSecret**
+4. 开通权限：`im:message`、`im:message:readonly`、`im:resource`

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

-在 `metabot/` 目录下创建 `bots.json` 文件：
+在 `metabot/bots.json` 创建配置（与 myclaude 项目同级目录）:

 ```json
 {
  "feishuBots": [
    {
      "name": "myclaude",
-      "description": "Claude Code assistant bot",
      "feishuAppId": "cli_xxxxx",
      "feishuAppSecret": "xxxxxxxxxxxxx",
      "defaultWorkingDirectory": "~/Documents/myResearch/myProjects/apaam/repo/myclaude"
@@ -168,153 +105,134 @@ npm run dev
 }
 ```

-**文件路径**：`metabot/bots.json`（与 myclaude 项目同级目录）
+> 💡 提示：飞书应用需要先发布，再开启「长连接」事件订阅

-> 💡 **提示**：复制上述模板，替换 `cli_xxxxx` 和 `xxxxxxxxxxxxx` 为你的飞书应用凭证。`defaultWorkingDirectory` 设置为你希望 Claude 操作的默认工作目录。
+---

-### 6. 启动与使用
+## 使用指南

-**启动飞书机器人**：
+### 启动服务

 ```bash
+# 启动飞书机器人
 metabot start
-```

-**本地交互模式**：
-
-```bash
-# 在项目目录下
+# 本地交互模式
 myclaude chat
 ```

-**飞书交互**：
+### 首次使用

- 在飞书中找到你的机器人
+告诉 Claude：
+
+> "我是第一次使用，请引导式地问我一些问题，帮我建立个性化配置并更新到 CLAUDE.md 中。"
+
+这会帮你设置：身份背景、技术栈、沟通偏好、工作模式等。
+
+### 日常交互
+
+**方式 1：飞书对话**
+- 在飞书中找到机器人
 - 直接发送消息即可对话

-### 7. 首次使用引导
-
-第一次使用时，建议发送以下引导语：
-
-> "我是第一次使用这个 Claude 助手，请引导式地问我一些问题，帮我建立个性化的配置，并更新到 CLAUDE.md 中。"
-
-这将帮助助手了解你的：
- 身份和专业背景
- 技术栈和偏好
- 工作习惯和沟通风格
-
-### 8. Workspace 管理建议
-
-为了更好地组织项目，建议在 `workspace/` 下创建子文件夹，并建立软连接：
+**方式 2：本地终端**

 ```bash
-# 进入 workspace
-cd workspace
-
-# 创建项目子目录
-mkdir myproject
-cd myproject
-
-# 建立常用目录的软连接
-ln -s ~/Documents/myWorks/works myWorks
-ln -s ~/Library/Mobile\ Documents/iCloud~md~obsidian/Documents/myAcademia myAcademia
-
-# 告诉 Claude 这个结构
-# "我在 workspace/myproject 下工作，请帮我管理这个目录"
+cd ~/Documents/myResearch/myProjects/apaam/repo/myclaude
+myclaude chat
 ```

-然后告诉 Claude：
-> "我在 workspace/myproject 下工作，已创建了常用目录的软连接，请帮我管理这个项目的开发。"
+---
+
+## 进阶配置
+
+### Skill 管理
+
+**方式 1：让 Claude 帮你找**
+
+```bash
+# 安装 find-skills
+npx skills add -g shubhamsaboo/awesome-llm-apps@find-skills
+/skill skills-sync
+```
+
+然后直接对话：
+> "帮我找一个能处理 PDF 的 skill" 或 "我想找个前端设计的 skill"
+
+**方式 2：手动安装**
+
+```bash
+# 项目级（仅当前项目）
+mkdir -p .claude/skills/my-skill
+cp SKILL.md .claude/skills/my-skill/
+
+# 全局（所有项目）
+mkdir -p ~/.claude/skills/my-skill
+cp SKILL.md ~/.claude/skills/my-skill/
+```
+
+**推荐 Skills:**
+
+| Skill | 用途 | 安装 |
+|-------|------|------|
+| `pdf` | PDF 处理 | `npx skills add -g anthropic/skills@pdf` |
+| `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` |
+
+### Workspace 与资料管理
+
+**创建项目工作区**（告诉 Claude 让它帮你操作）：
+
+> "在 workspace 下创建 myproject 目录，并链接我的 Works 文件夹和 iCloud 知识库"
+
+Claude 会自动执行：
+- 创建 `workspace/myproject/`
+- 建立软连接到常用目录
+- 初始化项目结构
+
+**Obsidian 集成**（可选）:
+
+告诉 Claude：
+> "帮我在 iCloud 创建 ClaudeWorkspace 文件夹，软连接到 workspace，并配置 Obsidian"
+
+优势：
+- 📱 iPhone/iPad 随时查看 Claude 生成的内容
+- 📝 双向编辑（Obsidian ↔ Claude）
+- 🔍 Obsidian 全文检索资料
+
+---

 ## 常用指令

 | 指令 | 说明 |
 |------|------|
-| `/help` | 显示帮助信息 |
-| `/reset` | 重置当前对话（飞书回复错误时使用） |
+| `/help` | 显示帮助 |
+| `/reset` | 重置对话（飞书卡住时用） |
 | `/stop` | 停止当前任务 |
-| `/skills` | 列出可用的技能 |
+| `/skills` | 列出可用 skills |
 | `/memory` | 查看记忆内容 |

+---
+
 ## 常见问题

-### Q1: 飞书机器人回复 error 或卡住
-
-**解决方案**：发送 `/reset` 重置对话，然后重新提问。
-
-### Q2: 如何切换模型？
+**Q1: 飞书回复 error 或卡住**  
+发送 `/reset` 重置对话

+**Q2: 切换模型**  
 ```bash
-# 查看可用模型
 cc-switch list
-
-# 切换到 DeepSeek
 cc-switch use deepseek
-
-# 切换到 Kimi Code（适合编程任务）
-cc-switch use kimi-code
 ```

-### Q3: 如何添加自定义 Skill？
-
-**Skill 安装方式（两种）：**
-
-**1. 手动安装**
-
-Skill 本质上是一个包含 `SKILL.md` 的文件夹：
-
-```bash
-# 项目级安装（仅当前项目可用）
-mkdir -p .claude/skills/my-skill
-cp /path/to/downloaded/SKILL.md .claude/skills/my-skill/
-
-# 全局安装（所有项目可用，需重启 Claude）
-mkdir -p ~/.claude/skills/my-skill
-cp /path/to/downloaded/SKILL.md ~/.claude/skills/my-skill/
-```
-
-**推荐下载来源：**
- [skills.sh](https://skills.sh) - 官方 Skill 市场
- [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) - 社区精选
- [claude-skills](https://github.com/search?q=claude+skill&type=repositories) - GitHub 搜索
-
-**2. 自动安装（推荐）**
-
-```bash
-# 安装 npx skills CLI
-npm install -g npx
-
-# 安装 find-skills（自动发现和管理 skill）
-npx skills add -g shubhamsaboo/awesome-llm-apps@find-skills
-
-# 同步到 Claude Code
-/skill skills-sync
-```
-
-启用后，可以直接对话让 myclaude 帮你找 skill：
-> "帮我找一个能处理 PDF 的 skill" 或 "我想找个做前端设计的 skill"
-
-**推荐的实用 Skills：**
-
-| Skill | 用途 | 安装命令 |
-|-------|------|---------|
-| `pdf` | PDF 处理（提取文本、图片、合并分割） | `npx skills add -g anthropic/skills@pdf` |
-| `git-proxy-clone` | 自动配置代理加速 Git 下载 | `npx skills add -g xvirobotics/metabot@git-proxy-clone` |
-| `find-skills` | 自动发现和安装 skills | `npx skills add -g shubhamsaboo/awesome-llm-apps@find-skills` |
-| `skill-creator` | 创建和优化自定义 skills | `npx skills add -g anthropic/skills@skill-creator` |
-| `metabot` | 飞书机器人 HTTP API 调用 | `npx skills add -g xvirobotics/metabot@metabot` |
-| `metamemory` | 共享知识库读写 | `npx skills add -g xvirobotics/metabot@metamemory` |
-
-### Q4: 飞书机器人不响应
-
-1. 检查 `metabot start` 是否正常启动
-2. 检查 `bots.json` 中的 AppID/AppSecret 是否正确
-3. 在飞书开发者平台检查机器人权限是否开启
-
-### Q5: Windows 上 Claude Code 找不到 Git Bash
-
-在 `~/.claude/settings.json` 中添加：
+**Q3: 飞书机器人不响应**  
+1. 检查 `metabot start` 是否启动
+2. 检查 `bots.json` 凭证是否正确
+3. 飞书应用是否已发布、长连接是否开启

+**Q4: Windows 找不到 Git Bash**  
+在 `~/.claude/settings.json` 添加：
 ```json
 {
  "env": {
@@ -323,39 +241,7 @@ npx skills add -g shubhamsaboo/awesome-llm-apps@find-skills
 }
 ```

-### Q6: Metabot 在 Windows 上安装失败
-
-1. 确保 Node.js 20+ 已安装：`node --version`
-2. 确保 Git for Windows 已安装
-3. 检查 PowerShell 执行策略：`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
-4. 使用手动安装方式替代一键安装脚本
-
-### 9. 云盘同步与 Obsidian 集成（推荐）
-
-为了更好地与 Claude 交互文件和资料，建议：
-
-**创建云盘同步文件夹**：
-
-```bash
-# 在 iCloud 云盘创建文件夹
-mkdir -p ~/Library/Mobile\ Documents/iCloud~com~apple~CloudDocs/ClaudeWorkspace
-
-# 软连接到 workspace
-cd ~/Documents/myResearch/myProjects/apaam/repo/myclaude/workspace
-ln -s ~/Library/Mobile\ Documents/iCloud~com~apple~CloudDocs/ClaudeWorkspace iCloudSync
-```
-
-**使用 Obsidian 管理**：
-
-1. 安装 Obsidian（https://obsidian.md）
-2. 创建新 Vault，选择 `ClaudeWorkspace` 文件夹
-3. 使用 Obsidian 查看、编辑和管理 Claude 生成的文件
-
-**优势**：
- 📱 跨设备同步：iPhone/iPad 上随时查看 Claude 生成的内容
- 📝 双向编辑：在 Obsidian 中编辑后，Claude 可以读取更新
- 🔍 快速检索：Obsidian 的搜索和链接功能方便资料管理
- 📁 文件共享：通过 iCloud 方便地与 Claude 分享图片、PDF 等文件
+---

 ## 项目结构