myagents/README.md

MyClaude

一个基于 Claude Code 的个人助理工具，支持通过飞书机器人进行远程交互。

功能特性

• 🤖 多模型支持：Claude、DeepSeek、Kimi、Kimi Code
• 💬 飞书机器人集成：随时随地与 AI 助手对话
• 📝 智能记忆：自动保存对话历史和项目上下文
• 🔧 技能扩展：支持自定义 Skill 增强功能

视频教程

📺 部署流程详解：Bilibili - MyClaude 完整部署指南

项目结构

myclaude/
├── .claude/               # Claude Code 配置
│   └── skills/            # 自定义技能
├── .venv/                 # Python 虚拟环境
├── desktop/               # 桌面宠物（Electron + React）
│   ├── electron/          # 主进程
│   ├── src/               # React 前端
│   └── package.json
├── templates/             # 模板目录
│   └── workspace/         # 工作区模板（CLAUDE.md, .gitignore）
├── bin/                   # Python 源码
│   ├── cli.py             # CLI 入口
│   ├── commands/          # 子命令
│   └── ...
├── CLAUDE.md              # 项目配置（自动生成）
├── pyproject.toml         # Python 项目配置
└── README.md              # 本文件

快速开始

1. 安装 Claude Code

macOS/Linux:

curl -fsSL https://claude.ai/install.sh | sh
# 或使用 npm: npm install -g @anthropic-ai/claude-code

Windows:

irm https://claude.ai/install.ps1 | iex
# 或: winget install Anthropic.ClaudeCode

注意：Windows 用户需先安装 Git for Windows

💡 认证提示：运行 claude login 后，建议选择 方案 2 (API Key)，但将 API Token 留空。这样 Claude 会使用 cc-switch 的配置，方便后续通过 cc-switch 切换不同模型。

来源：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):

brew update
brew tap farion1231/tap
brew install cc-switch

Linux (Debian/Ubuntu):

# 下载 .deb 包后
sudo dpkg -i cc-switch_*.deb
# 如有依赖问题，运行：
sudo apt-get install -f

Linux (RHEL/CentOS/Fedora):

sudo rpm -i cc-switch_*.rpm

配置模型:

💡 推荐 GUI 配置：

1. 启动 cc-switch 桌面应用
2. 点击「Add」添加模型
3. 选择模型类型（DeepSeek/Kimi/Claude 等），粘贴 API Key
4. 点击「Set Default」设置默认模型

命令行配置（可选）：

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

检查依赖：

python3 --version   # 需 >= 3.10
make --version      # 确认已安装
git --version       # 确认已安装

克隆并安装：

# 克隆到本地
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。如需自定义，设置环境变量：

export MYCLAUDE_WORKSPACE_ROOT="/your/custom/workspace"

首次运行 myclaude 时，会自动创建工作区目录并复制 templates/workspace/ 中的模板文件。

Shell 补全（可选）： 在 ~/.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. 安装桌面宠物（可选）

基于 Electron + React 的桌面宠物，常驻屏幕角落，点击展开终端聊天框。

前置依赖：

工具	版本要求	说明
Node.js	20+	JavaScript 运行时
Claude CLI	-	已安装并登录

安装运行：

cd ~/Documents/myBin/myclaude/desktop
npm install
npm run rebuild    # 编译原生模块（node-pty）
npm run dev        # 开发模式

快捷键：

• Cmd+Shift+M（macOS）/ Ctrl+Shift+M（Win/Linux）：显示/隐藏宠物

特性：

• 会话保持 — Claude CLI 进程常驻，收起/展开不影响对话
• 宠物外壳 — 80x80 悬浮 orb，可拖拽，呼吸动画
• CRT 终端 — 复古终端风格，扫描线 + 文字发光效果
• 窗口位置记忆 — 自动保存位置

6. 安装 Metabot

快速安装:

# 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：

# 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
# 或：重开一个终端窗口

启用命令自动补全（可选）：

# 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

基本命令：

metabot start      # 启动飞书机器人
metabot stop       # 停止机器人
metabot restart    # 重启机器人
metabot status     # 查看运行状态
metabot logs -f    # 查看实时日志
metabot update     # 更新到最新版本

6. 配置飞书机器人

6.1 创建飞书应用

1. 访问 飞书开发者平台
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 项目同级目录）:

{
  "feishuBots": [
    {
      "name": "myclaude",
      "feishuAppId": "cli_xxxxx",
      "feishuAppSecret": "xxxxxxxxxxxxx",
      "defaultWorkingDirectory": "~/workspace"
    }
  ]
}

⚠️ 注意：默认工作目录为 ~/workspace，可根据需要修改。

💡 提示：飞书应用需要先发布，再开启「长连接」事件订阅

---

使用指南

首次使用

告诉 Claude：

"我是第一次使用，请引导式地问我一些问题，帮我建立个性化配置并更新到 CLAUDE.md 中。"

这会帮你设置：身份背景、技术栈、沟通偏好、工作模式等。

日常交互

方式 1：飞书对话

• 在飞书中找到机器人
• 直接发送消息即可对话

方式 2：本地终端

myclaude          # 默认启动 Claude Code，cwd = ~/workspace
myclaude --cwd .  # 开发 CLI 时，cwd = 项目根目录

---

进阶配置

Skill 管理

方式 1：让 Claude 帮你找

# 安装 find-skills
npx skills add -g shubhamsaboo/awesome-llm-apps@find-skills
/skill skills-sync

然后直接对话：

"帮我找一个能处理 PDF 的 skill" 或 "我想找个前端设计的 skill"

方式 2：手动安装

# 项目级（仅当前项目）
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: 切换模型

cc-switch list
cc-switch use deepseek

Q3: 飞书机器人不响应

1. 检查 metabot start 是否启动
2. 检查 bots.json 凭证是否正确
3. 飞书应用是否已发布、长连接是否开启

Q4: Windows 找不到 Git Bash
在 ~/.claude/settings.json 添加：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

---

维护与故障排查

更新升级

Claude Code:

claude update

cc-switch:

# macOS (Homebrew)
brew upgrade cc-switch

# 其他平台：下载最新安装包重新安装

Metabot:

metabot update

卸载

Claude Code:

claude uninstall

cc-switch:

# macOS
brew uninstall cc-switch

# 其他平台：使用系统包管理器或删除安装文件

Metabot:

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 别名：

# 在 ~/.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 使配置生效。

使用时手动切换：

git_proxy_set_fastgithub    # 设置代理
git clone https://github.com/xxx/xxx.git
git_proxy_unset             # 取消代理

---

License

MIT