rename: myclaude -> myagents

2026-07-01 23:27:14 +08:00
parent 1db0187b70
commit 7f1aa9f27e
23 changed files with 859 additions and 937 deletions
@@ -1,535 +1,121 @@
-# MyClaude
+# MyAgents

-一个基于 Claude Code 的个人助理工具，支持通过飞书机器人进行远程交互。
+一个统一的 AI coding agent 启动器，封装 Claude Code、Kimi Code CLI 等工具。

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

- 🤖 多模型支持：Claude、DeepSeek、Kimi、Kimi Code
- 💬 飞书机器人集成：随时随地与 AI 助手对话
- 📝 智能记忆：自动保存对话历史和项目上下文
- 🔧 技能扩展：支持自定义 Skill 增强功能
-
-## 视频教程
-
-📺 **部署流程详解**：[Bilibili - MyClaude 完整部署指南](https://www.bilibili.com/video/BV15TPrzeELm/)
+- 🤖 **多 Agent 统一入口**：`myagents claude` / `myagents kimi`
+- 🚀 **独立快捷命令**：`myclaude`、`mykimi`
+- 📂 **自动 Workspace 解析**：默认 `~/workspace`，可通过环境变量覆盖
+- 📝 **Session 管理**：`--list` 列出可恢复会话
+- ➡️ **原生参数透传**：任意底层 agent 支持的参数直接透传

 ## 项目结构

 ```
-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              # 本文件
+myagents/
+├── myagents/
+│   ├── cli.py            # myagents 统一入口
+│   ├── entrypoints.py    # myclaude / mykimi 独立入口
+│   ├── launcher.py       # Agent 启动逻辑
+│   ├── project_root.py   # 项目/工作区根目录解析
+│   └── commands/         # update / upgrade 子命令
+├── tests/
+├── templates/            # workspace 模板
+├── pyproject.toml
+├── Makefile
+└── README.md
 ```

-## 快速开始
+## 安装

-### 1. 安装 Claude Code
-
-**macOS/Linux:**
-
-```bash
-# 推荐：官方安装脚本
-curl -fsSL https://claude.ai/install.sh | sh
-
-# 备选：npm（Homebrew 不可用时，固定 2.1.118，新版本有 Kimi 兼容问题）
-npm install -g @anthropic-ai/claude-code@2.1.118
-```
-
-> ⚠️ **npm 安装已弃用**：`npm install -g @anthropic-ai/claude-code` 从 2026-01-21（v2.1.15）起已被 Anthropic 官方弃用，未来版本可能失效。请优先使用官方安装脚本。
-
-**Windows:**
-
-```powershell
-# 推荐：官方安装脚本
-irm https://claude.ai/install.ps1 | iex
-
-# 或 winget
-winget install Anthropic.ClaudeCode
-```
-
-> **注意**：Windows 用户需先安装 [Git for Windows](https://git-scm.com/download/win)
-> 
-> **💡 认证提示**：首次运行 Claude Code 时，建议选择 **方案 2 (API Key)**，但将 API Token 留空。这样 Claude 会使用 cc-switch 的配置，方便后续通过 cc-switch 切换不同模型。
-> 
-> **来源**：[Claude Code 官方文档](https://code.claude.com/docs/en/quickstart)
-
-安装完成后验证：
-
-```bash
-claude --version
-```
-
-### 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）
+git clone <repository-url> /path/to/myagents
+cd /path/to/myagents
 make install
 ```

-会在 `~/.local/bin/myclaude` 创建指向本仓库 `.venv/bin/myclaude` 的符号链接；请保证 `~/.local/bin` 在 `PATH` 中（多数发行版默认已包含）。移除该链接：`make uninstall`（仅当链接目标为本仓库的 `.venv/bin/myclaude` 时才会删除）。
+`make install` 会：
+1. 同步/创建虚拟环境并做可编辑安装
+2. 在 `~/.local/bin/` 创建 `myagents`、`myclaude`、`mykimi` 符号链接
+3. 安装 shell 补全（zsh/bash）

-> 💡 **提示**：无 uv 时会创建项目 `.venv` 并用其中的 pip 做可编辑安装。
+请确保 `~/.local/bin` 在 `PATH` 中。移除链接：`make uninstall`。

-**配置工作区（可选）：**
+> 💡 **提示**：没有 uv 时会创建项目 `.venv` 并用其中的 pip 做可编辑安装。

-默认工作区为 `~/workspace`。如需自定义，设置环境变量：
+## 命令用法

 ```bash
-export MYCLAUDE_WORKSPACE_ROOT="/your/custom/workspace"
+# 统一入口
+myagents                          # 显示 help
+myagents claude                   # 启动 Claude Code
+myagents claude --cwd .           # 指定工作目录
+myagents claude -l                # 列出可恢复 sessions
+myagents claude -r <session-id>   # 恢复指定 session
+myagents kimi                     # 启动 Kimi Code CLI
+myagents kimi -S <session-id>     # 恢复 Kimi session
+myagents update                   # 重装 myagents 并同步 workspace 链接
+myagents upgrade                  # update 别名
+
+# 独立入口（与上面完全等价）
+myclaude
+myclaude --cwd . -r <session-id>
+mykimi
+mykimi -S <session-id>
 ```

-首次运行 `myclaude` 时，会自动创建工作区目录并复制 `templates/workspace/` 中的模板文件。
+各后端原生参数会原样透传。例如 Kimi npm 版支持 `--session`、`-c`（continue）、`-y`（yolo）等，直接加在命令后即可。

-**Shell 补全（可选）：** 在 `~/.zshrc` 或 `~/.bashrc` 中加入（有命令再注册，避免未安装时报错）：
+## 配置
+
+| 环境变量 | 说明 |
+|---|---|
+| `MYAGENTS_PROJECT_ROOT` | 覆盖项目根目录自动检测 |
+| `MYAGENTS_WORKSPACE_ROOT` | 覆盖 workspace 根目录，默认 `~/workspace` |
+
+设置示例：

 ```bash
-if command -v myclaude >/dev/null 2>&1; then
-  eval "$(_MYCLAUDE_COMPLETE=zsh_source myclaude)"
+export MYAGENTS_WORKSPACE_ROOT="/your/custom/workspace"
+```
+
+## Shell 补全（可选）
+
+在 `~/.zshrc` 或 `~/.bashrc` 中加入：
+
+```bash
+if command -v myagents >/dev/null 2>&1; then
+  eval "$(_MYAGENTS_COMPLETE=zsh_source myagents)"
 fi
 ```

-Bash 将 `zsh_source` 换成 `bash_source`。保存后 `source` 该配置文件。
+Bash 将 `zsh_source` 换成 `bash_source`。保存后 `source` 配置文件。

-### 5. 安装 Metabot
-
-**快速安装:**
+## 开发

 ```bash
-# macOS/Linux
-curl -fsSL https://raw.githubusercontent.com/xvirobotics/metabot/main/install.sh | bash
+# 运行测试
+python3 -m pytest tests/ -q

-# Windows (PowerShell)
-irm https://raw.githubusercontent.com/xvirobotics/metabot/main/install.ps1 | iex
+# 代码检查
+python3 -m ruff check myagents tests scripts
 ```

-安装器会引导完成：工作目录设置 → 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             # 取消代理
-```
-
---
+如果你要部署的是**小荷助理**完整环境（含 Claude Code、cc-switch、Metabot、飞书机器人等），请参见 [xiaohe-agent 部署文档](../../README.md)。

 ## License