内容
# HCO — Hermes 代码操作员
MIT 许可证 · v1.0.0
HCO 是一个 MCP 控制平面，允许 AI 代理安全地运行 Claude Code。它通过单个 stdio 服务器处理作业、会话、验证和报告。没有任意 shell。没有凭证处理。没有破坏性自动化。
## HCO 的功能
HCO 连接到任何 MCP 客户端（Claude Code、Hermes 代理或任何其他 MCP 主机），并提供 11 种工具：
- `hco_status` — 系统健康、作业计数、会话信息
- `hco_list_jobs` — 列出作业、按状态过滤
- `hco_inspect_job` — 完整的作业详细信息，包括验证和审批
- `hco_list_milestones` — 里程碑进度
- `hco_session_list` — 列出 Claude Code 会话
- `hco_session_status` — 会话详细信息，包含事件日志
- `hco_session_wait` — 等待会话完成
- `hco_session_stop` — 终止正在运行的会话
- `hco_session_archive` — 存档终端会话输出
- `hco_session_start` — 启动 Claude Code 会话
- `hco_task_start` — 启动持久的 Claude Code 任务
每个工具都有边界输入验证、输出上限和清理错误。在客户端之前，机密会被删除。
## 架构
```
src/
├── index.ts MCP 服务器入口
├── config/
│ ├── index.ts
│ └── schema.ts Zod 配置模式、加载器、安全默认值
├── state/
│ ├── index.ts
│ └── db.ts SQLite 迁移、WAL 模式、外键指令
├── cli/
│ └── main.ts CLI：状态、作业、检查、暂停、恢复、恢复
├── daemon/
│ └── main.ts 守护进程，带有 systemd 通知 + 作业工作循环
├── core/
│ ├── index.ts
│ └── context.ts 共享 AppContext（配置 + 数据库）
├── claude/
│ ├── launcher.ts 安全的 Claude Code 进程启动器
│ ├── runner.ts 进程运行器抽象
│ └── session.ts 会话 CRUD 和生命周期
├── jobs/
│ ├── service.ts 作业创建、认领、续期、释放
│ ├── worker.ts 具有租约管理的持久工作循环
│ └── executor.ts 安全的作业到 Claude 执行器
├── repos/
│ ├── service.ts 仓库状态（安全 git 只读）
│ └── files.ts 仓库文件读取（路径验证）
├── validation/
│ ├── profile.ts 验证配置文件定义
│ ├── runner.ts 固定命令配置文件运行器
│ └── telegram.ts 带有删除的报告格式化器
├── github/
│ └── policy.ts GitHub 操作允许列表和策略
├── reporting/
│ └── cli.ts CLI 报告集成
├── mcp/
│ ├── server.ts MCP stdio 服务器，11 种工具
│ └── errors.ts 错误类型和输出清理
├── deploy/
│ └── hco-mcp.service systemd 单元模板
tests/
├── claude.test.ts
├── cli.test.ts
├── config.test.ts
├── daemon.test.ts
├── db.test.ts
├── github-policy.test.ts
├── jobs-executor.test.ts
├── jobs-worker.test.ts
├── jobs.test.ts
├── mcp.test.ts
├── reporting-cli.test.ts
├── repos-files.test.ts
├── repos.test.ts
├── telegram-report.test.ts
├── validation-runner.test.ts
└── validation.test.ts
```
## 安装
要求：Node.js 22 或更高版本，npm 10 或更高版本。
```bash
git clone https://github.com/nzkbuild/hco-mcp.git
cd hco-mcp
npm install
npm run build
```
构建在 `dist/` 中生成编译后的 JavaScript。除了 npm 安装的内容外，没有其他本机依赖项。
## 与 Hermes 代理一起使用
将以下内容粘贴到您的 Hermes 代理聊天中，以将 HCO 添加为 MCP 服务器：
```
将 HCO MCP 服务器添加到我的 Hermes 配置中。使用 npx 命令：
npx -y hco-mcp
服务器使用 stdio 传输。注册所有 11 种工具。只读访问不需要其他配置。
```
或在 `~/.hermes/config.yaml` 中手动配置：
```yaml
mcp:
servers:
hco:
command: "npx"
args: ["-y", "hco-mcp"]
transport: "stdio"
```
## 与 Claude Code 一起使用
在您的项目根目录中将以下内容添加到 `.mcp.json` 中：
```json
{
"mcpServers": {
"hco": {
"command": "npx",
"args": ["-y", "hco-mcp"]
}
}
}
```
重启 Claude Code。输入 `/mcp` 以验证 `hco` 是否已连接并具有 11 种工具。
## 卸载
```bash
rm -rf hco-mcp
rm -rf ~/.hco
```
从 MCP 配置文件中删除 `hco` 块。在克隆目录和 `~/.hco` 之外，没有修改系统级文件。
## 配置
HCO 按以下顺序查找配置：
1. `./hco.json`（项目本地）
2. `~/.hco/config.json`（用户全局）
环境变量覆盖：
- `HCO_DATA_DIR` — SQLite 和运行时数据目录（默认 `~/.hco`）
- `HCO_TRANSPORT` — `stdio`（仅支持的传输）
- `HCO_LOG_LEVEL` — `debug`、`info`、`warn`、`error`（默认 `info`）
示例 `~/.hco/config.json`：
```json
{
"dataDir": "/var/lib/hco",
"transport": "stdio",
"allowlist": [
{ "owner": "your-org", "repo": "your-repo", "trustLevel": "trusted" }
],
"authority": {
"mode": "interactive",
"requireApprovals": false
},
"logLevel": "info",
"maxConcurrency": 4
}
```
## CLI
```bash
hco status # 系统健康和作业摘要
hco jobs # 列出已记录的作业
hco inspect <id> # 完整的作业详细信息
hco pause <id> # 暂停正在运行的作业
hco resume <id> # 恢复暂停的作业
hco recover # 重置卡住的正在运行的作业
```
## 守护进程
守护进程启动一个持久的工作循环，该循环轮询队列作业并通过安全执行器启动 Claude Code：
```bash
hco-daemon # 启动带有作业工作循环的守护进程
```
当设置 `NOTIFY_SOCKET` 时，守护进程会向 systemd 发送就绪信号（`READY=1`）。如果没有 systemd，它会正常启动并等待 SIGTERM/SIGINT。
在 `deploy/hco-mcp.service` 中提供了一个 systemd 单元模板。
## 开发
```bash
npm run dev # 监视模式
npm run lint # eslint
npm run format # prettier 检查
npm run format:fix # prettier 写入
npm test # 运行所有 126 个测试
npm run build # 编译 TypeScript
npm run diff:check # 验证没有暂存的空格问题
```
## 安全边界
- **事件中没有机密。** 事件表仅存储结构化有效载荷。令牌、密钥和凭证不得出现在事件有效载荷或作业输入中。
- **MCP 工具边界化。** 所有 11 种工具都具有输入验证，最大长度、输出上限和清理错误。
- **仓库允许列表。** 只有明确列出的仓库才能被操作。未知仓库被拒绝。
- **没有任意执行。** MCP 服务器没有 shell 或 exec 能力。Claude Code 通过固定的、验证的 spawn 启动，禁用 shell。
- **没有破坏性的 GitHub 操作。** 发布、标记、发布、部署、计费和机密轮换被策略永久拒绝。
- **路径安全。** 仓库文件读取验证绝对路径，拒绝遍历（`..`）、拒绝符号链接并强制字节上限。
## 版本历史
| 版本 | 更改内容 |
|---------|-------------|
| 1.0.0 | 完整的 MCP 控制平面：11 种工具、守护进程工作循环、安全 Claude 执行器、会话生命周期、验证配置文件、GitHub 策略、清理报告 |
| 0.1.0 | 初始基础：具有 4 种只读工具的 MCP 服务器、SQLite 存储、CLI、配置模式 |
## 许可证
MIT — 请参阅 [LICENSE](./LICENSE)。
版权所有 (c) 2024 nzkbuild
