# openHermit 安装与团队运维指南

这是一份给人和 Agent Loop 共同阅读的操作手册。目标不是展示源码，也不是营销介绍，而是说明如何安装 openHermit、如何创建团队、如何让 Agent Loop 按规则运维团队，以及出现问题时如何排障。

## 1. openHermit 是什么

openHermit 是一个本地运行的 AI 团队指挥台。它通过 cc-connect 管理 Claude Code、Codex、Gemini、Qoder 等 Agent 运行时，并把团队、任务、消息、定时循环、外部渠道统一到一个 Web 控制台中。

核心定位：

- 你负责定义目标、审批结果和处理例外。
- openHermit 负责团队看板、消息路由、任务状态和运行时管理。
- Agent Loop 负责持续检查任务、执行工作、回写证据和报告异常。

默认地址与目录：

- Web 控制台：`http://127.0.0.1:5680`
- 默认页面：`/teams`
- 本地状态目录：`~/.hermit/`
- cc-connect Management API：`9820`
- cc-connect Bridge：`9810`

## 2. 安装指南

### 2.1 普通用户安装

```bash
npm install -g @yancyyu/openhermit
openhermit
```

启动后打开：

```text
http://127.0.0.1:5680
```

常用命令：

```bash
openhermit              # 启动 openHermit
open-hermit             # 等同于 openhermit
hermit                  # 等同于 openhermit
openhermit --port 8080  # 指定端口
openhermit --version    # 查看版本
openhermit update       # 检查并更新
```

首次启动会自动准备本地配置。Agent 排障时只需要知道配置位置，不要打印里面的 token 或 secret：

```text
~/.hermit/
  cc-connect/
    config.toml
  teams/
  logs/
```

### 2.2 本地开发安装

```bash
git clone https://github.com/yancyuu/Hermit.git
cd Hermit
pnpm install
pnpm dev
```

开发模式默认打开：

```text
http://localhost:5174
```

开发和 CI 约定：

- 使用 `pnpm`，不要用 npm/yarn 做项目开发命令。
- 运行长日志命令时只保留尾部输出，例如 `pnpm typecheck 2>&1 | tail -20`。
- 不要把 `~/.hermit/cc-connect/config.toml`、token、secret、cookie 写入日志、文档或 memory。

## 3. 创建第一个团队

1. 打开 `/teams`。
2. 点击「新建团队」。
3. 填写团队名，例如 `backend`、`frontend`、`qa`。
4. 选择 harness，例如 `claudecode`、`codex`、`gemini`、`qoder`。
5. 绑定 cc-connect project。
6. 保存团队。
7. 在团队看板里创建任务，或通过外部渠道发送任务。
8. Agent Loop 认领任务、执行、回写结果。

推荐团队划分：

| 团队 | 推荐 harness | 负责内容 |
| --- | --- | --- |
| frontend | Claude Code / Qoder | UI、交互、前端缺陷 |
| backend | Claude Code / Codex | API、数据、服务逻辑 |
| qa | Gemini / Codex | 测试、回归、验收 |
| research | Gemini / Kimi | 调研、文档、竞品分析 |
| ops | Claude Code | CI、部署、运行状态、排障 |

## 4. 团队数据和运维目录

openHermit 自己的团队状态默认在：

```text
~/.hermit/teams/<team-slug>/
  team.json          # 团队配置
  messages/group.jsonl
  tasks/board.json
```

给数字员工长期运行的工作区建议这样组织：

```text
/Users/distill/teams/
  .memory/
    rules/
    decisions/
    needs-review/
  .claude/
    skills/
    workflows/
  <team-folder>/
    .env
    CLAUDE.md
    00_index/
      conflict-review.md
    01_business-docs/
    03_data/
    07_memory/
    99_temp/
    .claude/
      skills/
```

放置规则：

| 位置 | 放什么 | 禁止放什么 |
| --- | --- | --- |
| `<team>/CLAUDE.md` | 团队身份、边界、执行规则 | token、secret |
| `<team>/07_memory/` | 经过确认的团队长期事实 | 原始导出、临时日志 |
| `.memory/needs-review/` | 冲突事实、待审批提案 | 已确认事实 |
| `.claude/skills/` | 可复用操作能力 | 业务密钥 |
| `.claude/workflows/` | 稳定多步骤流程 | 临时笔记 |
| `99_temp/` | 临时材料 | 长期规则 |

## 5. Agent Loop 推荐工作流

Agent Loop 每轮执行时按这个顺序走：

1. 确认自己服务哪个 team。
2. 读取 team 的 `CLAUDE.md` 和必要的 `07_memory/`。
3. 查询 openHermit 团队状态、任务看板和最近消息。
4. 判断输入来源：看板任务、跨团队消息、外部渠道、定时任务、人工 DM。
5. 如果任务还没被明确启动，不要直接执行破坏性动作。
6. 认领或更新任务状态。
7. 执行最小安全步骤。
8. 保存证据：命令、结果、链接、截图或失败原因。
9. 回写任务评论或状态。
10. 如果动作会重复发生，把它升级为 skill、workflow 或 cron。
11. 如果发现事实冲突，写入 `needs-review` 并停止自动推进。

任务状态建议：

```text
received -> in_progress -> completed -> approved
                    └── failed / blocked / needs-review
```

## 6. 常用运维 Loop

### 6.1 团队健康检查

- 列出全部团队。
- 检查是否有离线、卡住、失败的 Agent。
- 检查最近消息和任务状态。
- 检查外部渠道绑定是否仍然有效。
- 输出报告：团队、症状、证据、建议动作。

### 6.2 任务派发检查

- 确认 source team 和 target team。
- 判断是普通消息还是正式任务派发。
- 正式派发前确认 Redis task bus 已配置。
- 目标团队未启动任务前，不要把消息当成已接受。
- 记录从 `received` 到 `approved` 的全过程。

### 6.3 记忆治理

- 稳定业务事实写到 `<team>/07_memory/`。
- 跨团队规则先写到 `.memory/needs-review/`，审批后再提升。
- 原始导出只放 data/report 路径，memory 只写指针。
- secret 永远不写进 memory、docs、messages 或日志。

### 6.4 CI / Pages 检查

- 每次提交后检查 GitHub Actions。
- 如果 `Deploy Agent Runbook to GitHub Pages` 失败，优先修 Pages workflow 或页面构建脚本。
- 如果普通 app CI 失败，但 Pages 成功且线上页面正确，不要把它误判为 page 问题。
- 验证线上页面必须包含：`openHermit 安装与团队运维指南` 和 `Feishu/Lark CLI 团队隔离`。

## 7. Feishu/Lark CLI 团队隔离

每个团队都应该有自己的 CLI profile。推荐使用 PATH 级 wrapper，而不是让 Agent 直接调用真实 `lark-cli`。

调用链：

```text
Agent 在团队目录中调用 lark-cli
  -> PATH 命中 ~/.local/bin/lark-cli wrapper
  -> wrapper 从当前目录向上寻找最近的 .env
  -> wrapper 读取 LARK_CLI_PROFILE
  -> wrapper 调用真实 lark-cli 并自动附加 --profile <team-profile>
```

团队 `.env` 模板：

```bash
LARK_CLI_PROFILE=<team-folder-name>
LARK_CLI_BRAND=feishu
LARK_APP_ID=<app_id>
LARK_APP_SECRET=<app_secret>

# 如果团队使用 FEISHU 命名，也可以：
# FEISHU_APP_ID=<app_id>
# FEISHU_APP_SECRET=<app_secret>
```

安全规则：

- `LARK_CLI_PROFILE` 可以打印。
- app id 按内部策略处理。
- app secret 绝不能打印、提交、写日志、写文档、写 memory。

执行任何飞书操作前先检查：

```bash
pwd
command -v lark-cli
lark-cli config show
lark-cli profile list
```

期望：

- `command -v lark-cli` 指向 `~/.local/bin/lark-cli`。
- `lark-cli config show` 显示当前团队 profile。
- 用户授权页显示当前团队 app 名称。

## 8. Feishu/Lark 排障表

| 症状 | 检查 | 修复 |
| --- | --- | --- |
| profile 错了 | `pwd`、最近 `.env`、`lark-cli config show` | cd 到正确团队目录，或显式传 `--profile` |
| Agent 子进程用了错误 app | `command -v lark-cli` | 确保 PATH 先命中 `~/.local/bin/lark-cli` |
| 授权页显示错应用 | cwd、`.env`、`LARK_APP_ID` | 修正目录和 profile 后重新生成授权 URL |
| permission denied | scope、身份、bot 权限 | 先补 bot scope；必须用户语义时再用 user auth |
| 多团队串号 | profile 和 token 共享 | 分 profile，强隔离时分 OS user 或 runtime |
| secret 泄露 | docs/logs/history | 立刻轮换 secret，并清理泄露材料 |

## 9. 安全边界

Agent 必须遵守：

- 不打印 token、secret、cookie、private key、password。
- 不把工具原始输出直接写入长期 memory。
- 不把目标态 Task Bus 当成已交付能力。
- 不把一条渠道消息当成正式任务已接受。
- 不静默绕过 Lark profile wrapper。
- 不把团队业务事实写进全局 memory，除非 owner 批准。
- 不确定时写入 `needs-review`，不要自作主张升级为事实。