From 2d9a20046feb6c5d25874d2b6694865b3905cf3e Mon Sep 17 00:00:00 2001 From: Zhengshou Lai Date: Tue, 7 Apr 2026 09:35:16 +0800 Subject: [PATCH] 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 --- README.md | 348 ++++++++++++++++++------------------------------------ 1 file changed, 117 insertions(+), 231 deletions(-) diff --git a/README.md b/README.md index 8f0012c..27f232f 100644 --- a/README.md +++ b/README.md @@ -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 等文件 +--- ## 项目结构