diff --git a/README.md b/README.md index 267f57e..098fdbc 100644 --- a/README.md +++ b/README.md @@ -1,530 +1,109 @@ -# MyClaude +# MyClaude CLI -一个基于 Claude Code 的个人助理工具，支持通过飞书机器人进行远程交互。 +个人助理命令行工具，作为 Claude Code 的启动器和工作区管理器。 -## 功能特性 +## 功能 -- 🤖 多模型支持：Claude、DeepSeek、Kimi、Kimi Code -- 💬 飞书机器人集成：随时随地与 AI 助手对话 -- 📝 智能记忆：自动保存对话历史和项目上下文 -- 🔧 技能扩展：支持自定义 Skill 增强功能 +- **启动 Claude Code**：默认在 `~/workspace` 目录运行 +- **工作区切换**：通过 `--cwd` 指定任意目录 +- **参数透传**：未识别的参数自动转发给 `claude` +- **自更新**：`myclaude update` / `myclaude upgrade` 从本地仓库重新安装 +- **自动补全**：安装时自动生成 zsh/bash 补全脚本 -## 视频教程 +## 安装 -📺 **部署流程详解**：[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/ # 子命令 -│ └── ... -├── CLAUDE.md # 项目配置（自动生成） -├── pyproject.toml # Python 项目配置 -└── README.md # 本文件 -``` - -## 快速开始 - -### 1. 安装 Claude Code - -**macOS/Linux:** +**前置依赖**：Python 3.10+、make、git，推荐 [uv](https://github.com/astral-sh/uv) ```bash -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 -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 ~/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` 时才会删除）。 +会在 `~/.local/bin/myclaude` 创建符号链接。移除：`make uninstall`。 -> 💡 **提示**：无 uv 时会创建项目 `.venv` 并用其中的 pip 做可编辑安装。 +> 无 uv 时会自动创建 `.venv` 并用 pip 做可编辑安装。 -**配置工作区（可选）：** - -默认工作区为 `~/workspace`。如需自定义，设置环境变量： +## 使用 ```bash -export MYCLAUDE_WORKSPACE_ROOT="/your/custom/workspace" +myclaude # 启动 Claude Code，cwd = ~/workspace +myclaude --cwd . # cwd = 当前目录 +myclaude --cwd /path/to/project # cwd = 指定目录 +myclaude --dangerously-skip-permissions # 透传给 claude +myclaude update # 从本仓库重新安装 +myclaude upgrade # update 的别名 ``` -首次运行 `myclaude` 时，会自动创建工作区目录并复制 `templates/workspace/` 中的模板文件。 - -**Shell 补全（可选）：** 在 `~/.zshrc` 或 `~/.bashrc` 中加入（有命令再注册，避免未安装时报错）： +**Shell 补全**（可选）： ```bash +# ~/.zshrc 或 ~/.bashrc 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 +export MYCLAUDE_WORKSPACE_ROOT="/your/custom/workspace" ``` -安装器会引导完成：工作目录设置 → 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 -# 或：重开一个终端窗口 +export MYCLAUDE_PROJECT_ROOT="/path/to/myclaude/repo" ``` -**启用命令自动补全（可选）：** +## 项目结构 + +``` +myclaude/ +├── bin/ # Python 源码 +│ ├── cli.py # CLI 入口 +│ ├── commands/ # 子命令 +│ └── project_root.py +├── templates/ # 模板目录 +│ └── workspace/ # 工作区模板 (CLAUDE.md) +├── tests/ # 测试 +├── scripts/ # 安装/卸载脚本 +├── Makefile +├── pyproject.toml +└── README.md +``` + +## 生态系统扩展（可选） + +以下组件可增强 myclaude 的功能，但**不属本 CLI 的必要依赖**： + +| 组件 | 用途 | 安装 | +|------|------|------| +| 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 ` | + +详细配置说明见原 [完整部署文档](https://www.bilibili.com/video/BV15TPrzeELm/)。 + +## 维护 + +**更新升级**： ```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 +claude update # 更新 Claude Code +cc-switch upgrade # 更新 cc-switch（如已安装） +metabot update # 更新 Metabot（如已安装） ``` -**基本命令：** +**卸载**： ```bash -metabot start # 启动飞书机器人 -metabot stop # 停止机器人 -metabot restart # 重启机器人 -metabot status # 查看运行状态 -metabot logs -f # 查看实时日志 -metabot update # 更新到最新版本 +make uninstall # 卸载 myclaude CLI +claude uninstall # 卸载 Claude Code ``` -### 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 、/skill git-proxy-clone skill 、/skill git-proxy-clone exec "" -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 diff --git a/scripts/install_completion.sh b/scripts/install_completion.sh index 88df412..90a9f28 100755 --- a/scripts/install_completion.sh +++ b/scripts/install_completion.sh @@ -38,4 +38,9 @@ if [[ "$USER_SHELL" == "zsh" ]]; then install_zsh_completion elif [[ "$USER_SHELL" == "bash" ]]; then install_bash_completion +else + echo "Shell '$USER_SHELL' is not supported for automatic completion installation." + echo "To install completions manually, run one of the following commands:" + echo " zsh: _MYCLAUDE_COMPLETE=zsh_source $VENV_MYCLAUDE > /path/to/completions/_myclaude" + echo " bash: _MYCLAUDE_COMPLETE=bash_source $VENV_MYCLAUDE > /path/to/completions/myclaude.bash" fi