Zhengshou Lai
ffac0ba37d
Cursor Agent CLI wrapper (mycursor) with resume/session listing. Product xiaohe CLI stays in xiaohe-api only — no dual entry.
143 lines
5.1 KiB
Markdown
143 lines
5.1 KiB
Markdown
# MyAgents
|
||
|
||
一个统一的 AI coding agent 启动器，封装 Claude Code、Kimi Code CLI、OpenAI Codex、Hermes Agent 等工具。
|
||
|
||
## 功能
|
||
|
||
- 🤖 **多 Agent 统一入口**：`myagents claude` / `myagents kimi` / `myagents codex` / `myagents hermes`
|
||
- 🚀 **独立快捷命令**：`myclaude`、`mykimi`、`mycodex`、`myhermes`
|
||
- 📂 **自动 Workspace 解析**：默认 `~/workspace`，可通过环境变量覆盖
|
||
- 📝 **Session 管理**：`--list` 列出可恢复会话
|
||
- ➡️ **原生参数透传**：任意底层 agent 支持的参数直接透传
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
myagents/
|
||
├── myagents/
|
||
│ ├── cli.py # myagents 统一入口
|
||
│ ├── entrypoints.py # myclaude / mykimi / mycodex / myhermes 独立入口
|
||
│ ├── launcher.py # Agent 启动逻辑
|
||
│ ├── project_root.py # 项目/工作区根目录解析
|
||
│ └── commands/ # update / upgrade 子命令
|
||
├── tests/
|
||
├── pyproject.toml
|
||
├── Makefile
|
||
└── README.md
|
||
```
|
||
|
||
## 安装
|
||
|
||
**前置依赖**
|
||
|
||
| 工具 | 版本要求 | 说明 |
|
||
|---|---|---|
|
||
| Python | 3.10+ | 项目运行环境 |
|
||
| make | - | 构建工具（macOS/Linux 通常自带） |
|
||
| git | - | 代码仓库管理 |
|
||
| uv 或 pip | - | Python 包管理器，推荐 [uv](https://github.com/astral-sh/uv) |
|
||
|
||
**克隆并安装**
|
||
|
||
```bash
|
||
git clone <repository-url> /path/to/myagents
|
||
cd /path/to/myagents
|
||
make install
|
||
```
|
||
|
||
`make install` 会：
|
||
1. 同步/创建虚拟环境并做可编辑安装
|
||
2. 在 `~/.local/bin/` 创建 `myagents`、`myclaude`、`mykimi`、`mycodex`、`myhermes` 符号链接
|
||
3. 自动安装 shell 补全到 `~/.local/share/zsh/site-functions` 和 `~/.local/share/bash-completion/completions`
|
||
|
||
请确保 `~/.local/bin` 在 `PATH` 中，并在 `~/.zshrc` 里加上：
|
||
|
||
```bash
|
||
fpath=(~/.local/share/zsh/site-functions $fpath)
|
||
autoload -Uz compinit && compinit
|
||
```
|
||
|
||
移除链接与补全：`make uninstall`。
|
||
|
||
首次运行任意 `myagents` / `myclaude` / `mykimi` 命令时，若补全缺失会自动补齐。也可以手动管理：
|
||
|
||
```bash
|
||
myagents completion doctor # 查看补全状态
|
||
myagents completion install # 手动重装补全
|
||
myagents completion zsh # 打印 zsh 补全脚本
|
||
```
|
||
|
||
> 💡 **提示**：没有 uv 时会创建项目 `.venv` 并用其中的 pip 做可编辑安装。
|
||
|
||
## 命令用法
|
||
|
||
```bash
|
||
# 统一入口
|
||
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 codex # 启动 OpenAI Codex CLI
|
||
myagents codex -r <session-id> # 恢复 Codex session（映射为 resume）
|
||
myagents codex resume <id> # 原生 resume 子命令
|
||
myagents hermes # 启动 Hermes Agent（默认 --yolo）
|
||
myagents hermes -l # 列出最近的 Hermes sessions（全局 SQLite 存储）
|
||
myagents hermes --resume <id> # 恢复 Hermes session
|
||
myagents update # 重装 myagents 并同步 workspace 链接
|
||
myagents upgrade # update 别名
|
||
myagents completion # 安装/查看/卸载 shell 补全
|
||
|
||
# 独立入口（与上面完全等价）
|
||
myclaude
|
||
myclaude --cwd . -r <session-id>
|
||
mykimi
|
||
mykimi -S <session-id>
|
||
mycodex
|
||
mycodex -r <session-id>
|
||
mycodex resume <session-id>
|
||
myhermes
|
||
myhermes --resume <session-id>
|
||
|
||
# tmux 防断线（SSH 远程场景）
|
||
myclaude -t # 在 tmux 会话中启动，掉线/合盖不丢会话
|
||
myclaude -t -r <session-id> # 与透传参数任意组合
|
||
```
|
||
|
||
`--tmux` / `-t` 会把 agent 包进一个**按后端 + 目录命名**的 tmux 会话（如 `myclaude-myagents-a1b2c3`）：重复执行同一命令即重新接入（`tmux new-session -A` 语义），`C-b d` 脱离。已在 tmux 内时自动退化为直接运行；未安装 tmux 会给出明确提示。
|
||
|
||
各后端原生参数会原样透传。例如 Kimi npm 版支持 `--session`、`-c`（continue）、`-y`（yolo）等，Codex 支持 `resume`、`continue`、`exec` 等子命令；`mycodex` 还会将 `-r` / `--resume` 映射为 `codex resume`，与 `myclaude` 体验保持一致。Hermes 默认带 `--yolo` 启动，支持 `--resume <id>` / `--continue` 透传；其 sessions 存在全局 SQLite（`~/.hermes/state.db`），不区分工作目录，`-l` 列出最近 20 条。
|
||
|
||
## 配置
|
||
|
||
| 环境变量 | 说明 |
|
||
|---|---|
|
||
| `MYAGENTS_PROJECT_ROOT` | 覆盖项目根目录自动检测 |
|
||
| `MYAGENTS_WORKSPACE_ROOT` | 覆盖 workspace 根目录，默认 `~/workspace` |
|
||
|
||
设置示例：
|
||
|
||
```bash
|
||
export MYAGENTS_WORKSPACE_ROOT="/your/custom/workspace"
|
||
```
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
# 运行测试
|
||
python3 -m pytest tests/ -q
|
||
|
||
# 代码检查
|
||
python3 -m ruff check myagents tests scripts
|
||
```
|
||
|
||
## 完整部署指南
|
||
|
||
如果你要部署的是**小荷助理**完整环境（Session API、Desktop、Skills Hub 等），请参见 [xiaohe-agent 仓库 README](../../README.md)（产品包名 **xiaohe-api**）。
|
||
|
||
## License
|
||
|
||
MIT
|