revert: restore original README content

The previous slimmed version removed too much ecosystem documentation. Restore the full README as the project's single entry point.
2026-05-27 11:23:13 +08:00
parent 593b7a85b3
commit 854a69d3d8
1 changed files with 505 additions and 84 deletions
@@ -1,109 +1,530 @@
-# MyClaude CLI
+# MyClaude

-个人助理命令行工具，作为 Claude Code 的启动器和工作区管理器。
+一个基于 Claude Code 的个人助理工具，支持通过飞书机器人进行远程交互。

-## 功能
+## 功能特性

- **启动 Claude Code**：默认在 `~/workspace` 目录运行
- **工作区切换**：通过 `--cwd` 指定任意目录
- **参数透传**：未识别的参数自动转发给 `claude`
- **自更新**：`myclaude update` / `myclaude upgrade` 从本地仓库重新安装
- **自动补全**：安装时自动生成 zsh/bash 补全脚本
+- 🤖 多模型支持：Claude、DeepSeek、Kimi、Kimi Code
+- 💬 飞书机器人集成：随时随地与 AI 助手对话
+- 📝 智能记忆：自动保存对话历史和项目上下文
+- 🔧 技能扩展：支持自定义 Skill 增强功能

-## 安装
+## 视频教程

-**前置依赖**：Python 3.10+、make、git，推荐 [uv](https://github.com/astral-sh/uv)
-
-```bash
-git clone <repository-url> ~/your-path/myclaude
-cd ~/your-path/myclaude
-make install
-```
-
-会在 `~/.local/bin/myclaude` 创建符号链接。移除：`make uninstall`。
-
-> 无 uv 时会自动创建 `.venv` 并用 pip 做可编辑安装。
-
-## 使用
-
-```bash
-myclaude                           # 启动 Claude Code，cwd = ~/workspace
-myclaude --cwd .                   # cwd = 当前目录
-myclaude --cwd /path/to/project    # cwd = 指定目录
-myclaude --dangerously-skip-permissions   # 透传给 claude
-myclaude update                    # 从本仓库重新安装
-myclaude upgrade                   # update 的别名
-```
-
-**Shell 补全**（可选）：
-
-```bash
-# ~/.zshrc 或 ~/.bashrc
-if command -v myclaude >/dev/null 2>&1; then
-  eval "$(_MYCLAUDE_COMPLETE=zsh_source myclaude)"
-fi
-```
-
-## 配置
-
-**自定义工作区目录**：
-
-```bash
-export MYCLAUDE_WORKSPACE_ROOT="/your/custom/workspace"
-```
-
-**自定义项目根目录**（开发时）：
-
-```bash
-export MYCLAUDE_PROJECT_ROOT="/path/to/myclaude/repo"
-```
+📺 **部署流程详解**：[Bilibili - MyClaude 完整部署指南](https://www.bilibili.com/video/BV15TPrzeELm/)

 ## 项目结构

 ```
 myclaude/
+├── .claude/               # Claude Code 配置
+│   └── skills/            # 自定义技能
+├── .venv/                 # Python 虚拟环境
+├── templates/             # 模板目录
+│   └── workspace/         # 工作区模板（CLAUDE.md, .gitignore）
 ├── bin/                   # Python 源码
 │   ├── cli.py             # CLI 入口
 │   ├── commands/          # 子命令
-│   └── project_root.py
-├── templates/        # 模板目录
-│   └── workspace/    # 工作区模板 (CLAUDE.md)
-├── tests/            # 测试
-├── scripts/          # 安装/卸载脚本
-├── Makefile
-├── pyproject.toml
-└── README.md
+│   └── ...
+├── CLAUDE.md              # 项目配置（自动生成）
+├── pyproject.toml         # Python 项目配置
+└── README.md              # 本文件
 ```

-## 生态系统扩展（可选）
+## 快速开始

-以下组件可增强 myclaude 的功能，但**不属本 CLI 的必要依赖**：
+### 1. 安装 Claude Code

-| 组件 | 用途 | 安装 |
-|------|------|------|
-| cc-switch | 多模型切换（Claude/DeepSeek/Kimi） | [GitHub releases](https://github.com/farion1231/cc-switch/releases) |
-| Metabot | 飞书机器人远程交互 | `curl -fsSL https://raw.githubusercontent.com/xvirobotics/metabot/main/install.sh \| bash` |
-| Skills | 自定义 Skill 增强功能 | `npx skills add -g <owner/repo@skill>` |
-
-详细配置说明见原 [完整部署文档](https://www.bilibili.com/video/BV15TPrzeELm/)。
-
-## 维护
-
-**更新升级**：
+**macOS/Linux:**

 ```bash
-claude update        # 更新 Claude Code
-cc-switch upgrade    # 更新 cc-switch（如已安装）
-metabot update       # 更新 Metabot（如已安装）
+curl -fsSL https://claude.ai/install.sh | sh
+# 或使用 npm: npm install -g @anthropic-ai/claude-code
 ```

-**卸载**：
+**Windows:**
+
+```powershell
+irm https://claude.ai/install.ps1 | iex
+# 或: winget install Anthropic.ClaudeCode
+```
+
+> **注意**：Windows 用户需先安装 [Git for Windows](https://git-scm.com/download/win)
+> 
+> **💡 认证提示**：运行 `claude login` 后，建议选择 **方案 2 (API Key)**，但将 API Token 留空。这样 Claude 会使用 cc-switch 的配置，方便后续通过 cc-switch 切换不同模型。
+> 
+> **来源**：[Claude Code 官方文档](https://code.claude.com/docs/en/quickstart)
+
+安装完成后，首次使用需登录：

 ```bash
-make uninstall       # 卸载 myclaude CLI
-claude uninstall     # 卸载 Claude Code
+claude login
 ```

+> 💡 建议选择 **方案 2 (API Key)**，但将 API Token 留空，这样 Claude 会使用 cc-switch 的配置。
+
+### 2. 开通大模型会员（推荐）
+
+| 服务 | 说明 | 开通地址 |
+|------|------|---------|
+| DeepSeek | 国产高性能大模型 | https://platform.deepseek.com |
+| Kimi | 长文本处理专家，API 按量计费 | https://kimi.moonshot.cn |
+| Kimi Code | 代码专用模型，包月/包年订阅更实惠 | Kimi 内开通 Code 会员 |
+
+### 3. 安装 cc-switch（多模型切换）
+
+**方式 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
+```
+
+Linux (Debian/Ubuntu):
+
+```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
+python3 --version   # 需 >= 3.10
+make --version      # 确认已安装
+git --version       # 确认已安装
+```
+
+**克隆并安装：**
+
+```bash
+# 克隆到本地
+git clone <repository-url> ~/your-path/myclaude
+cd ~/your-path/myclaude
+
+# 安装（uv 则 uv sync，否则创建 .venv 并用 pip install -e）
+make install
+```
+
+会在 `~/.local/bin/myclaude` 创建指向本仓库 `.venv/bin/myclaude` 的符号链接；请保证 `~/.local/bin` 在 `PATH` 中（多数发行版默认已包含）。移除该链接：`make uninstall`（仅当链接目标为本仓库的 `.venv/bin/myclaude` 时才会删除）。
+
+> 💡 **提示**：无 uv 时会创建项目 `.venv` 并用其中的 pip 做可编辑安装。
+
+**配置工作区（可选）：**
+
+默认工作区为 `~/workspace`。如需自定义，设置环境变量：
+
+```bash
+export MYCLAUDE_WORKSPACE_ROOT="/your/custom/workspace"
+```
+
+首次运行 `myclaude` 时，会自动创建工作区目录并复制 `templates/workspace/` 中的模板文件。
+
+**Shell 补全（可选）：** 在 `~/.zshrc` 或 `~/.bashrc` 中加入（有命令再注册，避免未安装时报错）：
+
+```bash
+if command -v myclaude >/dev/null 2>&1; then
+  eval "$(_MYCLAUDE_COMPLETE=zsh_source myclaude)"
+fi
+```
+
+Bash 将 `zsh_source` 换成 `bash_source`。保存后 `source` 该配置文件。
+
+### 5. 安装 Metabot
+
+**快速安装:**
+
+```bash
+# macOS/Linux
+curl -fsSL https://raw.githubusercontent.com/xvirobotics/metabot/main/install.sh | bash
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/xvirobotics/metabot/main/install.ps1 | iex
+```
+
+安装器会引导完成：工作目录设置 → Claude 认证 → IM 平台选择 → 机器人配置 → PM2 自启动
+
+**配置环境变量：**
+
+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. 创建企业自建应用，添加「机器人」能力
+3. 获取 **AppID** 和 **AppSecret**
+4. 开通权限：
+   - `im:message` - 发送消息
+   - `im:message:readonly` - 读取消息
+   - `im:resource` - 上传下载资源
+5. **事件订阅**：在「事件与回调」中，订阅 `im.message.receive_v1` 事件（接收用户消息）
+   - 订阅方式选择「长连接」（无需公网 IP）
+   - 或在「请求地址配置」中填写回调 URL（需要 HTTPS）
+
+#### 6.2 配置 bots.json
+
+在 `metabot/bots.json` 创建配置（与 myclaude 项目同级目录）:
+
+```json
+{
+  "feishuBots": [
+    {
+      "name": "myclaude",
+      "feishuAppId": "cli_xxxxx",
+      "feishuAppSecret": "xxxxxxxxxxxxx",
+      "defaultWorkingDirectory": "~/workspace"
+    }
+  ]
+}
+```
+
+> ⚠️ **注意**：默认工作目录为 `~/workspace`，可根据需要修改。
+
+> 💡 提示：飞书应用需要先发布，再开启「长连接」事件订阅
+
+---
+
+## 使用指南
+
+### 首次使用
+
+告诉 Claude：
+
+> "我是第一次使用，请引导式地问我一些问题，帮我建立个性化配置并更新到 CLAUDE.md 中。"
+
+这会帮你设置：身份背景、技术栈、沟通偏好、工作模式等。
+
+### 日常交互
+
+**方式 1：飞书对话**
+- 在飞书中找到机器人
+- 直接发送消息即可对话
+
+**方式 2：本地终端**
+
+```bash
+myclaude          # 默认启动 Claude Code，cwd = ~/workspace
+myclaude --cwd .  # 开发 CLI 时，cwd = 项目根目录
+```
+
+---
+
+## 进阶配置
+
+### 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` |
+| `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` 或飞书对话中，直接告诉 Claude：
+> - "帮我安装处理 PDF 的 skill"
+> - "安装飞书日历相关的 skills"
+> - "我想用飞书文档功能，帮我安装"
+>
+> Claude 会自动帮你完成安装。
+
+### Workspace 与资料管理
+
+**创建项目工作区**（告诉 Claude 让它帮你操作）：
+
+> "在 workspace 下创建 myproject 目录，并链接我的 Works 文件夹和 iCloud 知识库"
+
+Claude 会自动执行：
+- 创建 `workspace/myproject/`
+- 建立软连接到常用目录
+- 初始化项目结构
+
+**Obsidian 集成**（可选）:
+
+告诉 Claude：
+> "帮我在 iCloud 创建 ClaudeWorkspace 文件夹，软连接到 workspace，并配置 Obsidian"
+
+优势：
+- 📱 iPhone/iPad 随时查看 Claude 生成的内容
+- 📝 双向编辑（Obsidian ↔ Claude）
+- 🔍 Obsidian 全文检索资料
+
+---
+
+## 常用指令
+
+> 💡 **以下指令在飞书机器人对话中直接输入使用**
+
+| 指令 | 说明 |
+|------|------|
+| `/help` | 显示帮助 |
+| `/reset` | 开启新对话（重置上下文） |
+| `/stop` | 停止当前任务（卡住时用） |
+| `/skills` | 列出可用 skills |
+| `/memory` | 查看记忆内容 |
+
+---
+
+## 常见问题
+
+**Q1: 飞书回复 error 或卡住**
+- 卡住时发送 `/stop` 停止当前任务
+- 想开启新对话发送 `/reset`
+
+**Q2: 切换模型**  
+```bash
+cc-switch list
+cc-switch use deepseek
+```
+
+**Q3: 飞书机器人不响应**  
+1. 检查 `metabot start` 是否启动
+2. 检查 `bots.json` 凭证是否正确
+3. 飞书应用是否已发布、长连接是否开启
+
+**Q4: Windows 找不到 Git Bash**  
+在 `~/.claude/settings.json` 添加：
+```json
+{
+  "env": {
+    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
+  }
+}
+```
+
+---
+
+## 维护与故障排查
+
+### 更新升级
+
+**Claude Code:**
+```bash
+claude update
+```
+
+**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
+```
+
+---
+
+## 附录：Git 代理加速（可选）
+
+`git-proxy-clone` 是一个本地自定义 skill，可在执行 git 命令时自动配置 FastGithub 代理，加速 GitHub 访问。
+
+### 前置依赖
+
+**安装 FastGithub**
+- 下载地址：https://github.com/creazyboyone/FastGithub/releases
+- 安装并启动 FastGithub（默认代理端口 `38457`）
+
+### 使用方式
+
+#### 方式1：使用 Skill（推荐，自动代理）
+
+**安装 skill：**
+
+复制以下 prompt 发送给 Claude：
+
+```
+请帮我创建一个名为 git-proxy-clone 的本地 skill，用于自动配置 FastGithub 代理加速 GitHub 操作。
+
+要求：
+1. 路径：~/.claude/skills/git-proxy-clone/SKILL.md
+2. 触发条件：用户执行 git clone、git pull、git fetch 或 npx skills add 时
+3. 代理地址：http://127.0.0.1:38457
+4. 自动行为：
+   - 执行 git 命令前自动设置代理（同时设置 http.proxy 和 https.proxy 为 http://127.0.0.1:38457）
+   - 命令完成后自动取消代理（同时 unset http.proxy 和 https.proxy）
+5. 提供封装命令：/skill git-proxy-clone clone <url>、/skill git-proxy-clone skill <owner/repo@skill>、/skill git-proxy-clone exec "<command>"
+6. 当用户直接输入 git clone 等命令时，skill 应自动拦截并包装执行（先设代理、执行命令、最后取消代理）
+
+请创建完整的 SKILL.md 文件。
+```
+
+创建完成后，Claude Code 会自动识别并加载该 skill。
+
+#### 方式2：手动配置（无需 skill）
+
+如果不想使用 skill，可手动配置 Git 别名：
+
+```bash
+# 在 ~/.zshrc 或 ~/.bashrc 中添加：
+alias git_proxy_set_fastgithub='\
+  git config --global http.proxy http://127.0.0.1:38457 && \
+  git config --global https.proxy http://127.0.0.1:38457'
+
+alias git_proxy_unset='\
+  git config --global --unset http.proxy && \
+  git config --global --unset https.proxy'
+```
+
+然后执行 `source ~/.zshrc` 使配置生效。
+
+**使用时手动切换：**
+
+```bash
+git_proxy_set_fastgithub    # 设置代理
+git clone https://github.com/xxx/xxx.git
+git_proxy_unset             # 取消代理
+```
+
+---
+
 ## License

 MIT