← 返回知识库 # Hermes 内部看板 ↔ Web 看板接入与同步指南 **节点**：5号（马龙）为首个打通样板 **日期**：2026-08-01 **状态**：本机联调通过（双向 create / status / report / comment / complete） **用途**：新服务器装 Hermes 后，按本文复用同一套 Web 看板接入，无需重新摸索 --- ## 0. 一句话 | 层 | 角色 | 路径/端口 | |:---|:-----|:----------| | **真源** | Hermes 原生看板 SQLite | `/root/.hermes/kanban.db`（CLI：`hermes kanban …`） | | **HTTP 门面** | Web portal / API | `127.0.0.1:18900` → 进程 `kanban-server`（pm2） | | **人类 UI** | 三列看板 | `GET /kanban`；外网 `https://en.hunanningyuan.cloud/kanban/`（nginx 反代） | | **展示兜底** | GDrive TaskBoard `.md` | `/mnt/gdrive/项目与交付/TaskBoard/{01,02,03}_*` | **原则：只认一个写权威 = Hermes `kanban.db`。** Web API 与 CLI 都必须最终落在同一张表；GDrive `.md` 与 `/data/kanban/tasks.json` 仅缓存/兜底，不能当第二真源。任务卡规则仍走： - skill：`task-card-publish`（发任务六问） - skill：`kanban-mcp-ops`（接单 report） - 协议：`~/.hermes/GOVERNANCE/task_card_protocol_v3.md` --- ## 1. 架构（5号已验证） ``` 发起方 ├─ hermes kanban create/comment/complete ──┐ ├─ POST /kanban/create|report|status|move ──┼──► /root/.hermes/kanban.db (authority) └─ Web UI 拖拽 / 归档 ──┘ │ ├─► GET /kanban 页面（读 db，md 仅补漏） ├─► GDrive TaskBoard/*.md（可选镜像） └─► webhooks.json 门铃通知各节点 ``` 软链约定（避免双库）： ```bash /data/kanban/kanban.db -> /root/.hermes/kanban.db ``` 环境变量（可选）： | 变量 | 默认 | 含义 | |:-----|:-----|:-----| | `KANBAN_DB` | 代码内写死 `/root/.hermes/kanban.db` | 真源路径（改代码或 fork 时统一） | | `KANBAN_GDRIVE_BASE` | 自动探测 | TaskBoard 根目录 | | `KANBAN_DB_TASK_CACHE_TTL` | `2` | 读缓存秒数 | | `KANBAN_GDRIVE_SCAN_ON_REQUEST` | `0` | 是否每次请求扫盘 | --- ## 2. 状态映射（铁律） Hermes 真源状态名与 Web 列必须对齐，否则 `hermes kanban complete` 会失败。 | Web / agent 常用 | Hermes DB | Web 列目录 | |:-----------------|:----------|:-----------| | pending / todo / ready | `ready` | `01_任务投递` | | blocked | `blocked` | `01_任务投递` | | in_progress / running / active | **`running`**（禁止写 `in_progress` 进 DB） | `02_执行中` | | done / completed | `done` | `03_已完成` | | archived | `archived` + `archived=1` | `05_归档` | > 2026-08-01 修复：旧版 `DIR_TO_DB_STATUS["02_执行中"]="in_progress"` 会导致 Hermes CLI 无法 complete。现已改为 `running`。 --- ## 3. HTTP API 一览（本机）基址：`http://127.0.0.1:18900` 外网：`https://en.hunanningyuan.cloud`（或 `kb.hunanningyuan.cloud`）同路径。 ### 3.1 读 ```bash curl -s http://127.0.0.1:18900/kanban/stats curl -s http://127.0.0.1:18900/kanban/tasks | head curl -s "http://127.0.0.1:18900/kanban/api/task?id=t_xxxxxxxx" curl -s http://127.0.0.1:18900/kanban/protocol # 含 status_map / 真源路径 ``` ### 3.2 写（都会碰 kanban.db） **创建** ```bash curl -s -X POST http://127.0.0.1:18900/kanban/create \ -H 'Content-Type: application/json' \ -d '{ "title": "[L1][P2][5号][codex] 示例任务", "assignee": "codex", "priority": "P2", "creator": "web-or-agent", "note": "描述或 v3 body 字符串", "body": {"protocol_version":"v3","task_type":"ops","requester_node":"5hao","target_node":"5hao","input":"...","expected_output":"...","delivery_mode":"task_card","attachments":[]} }' # → { ok, task_id: "t_........", kanban_db_ok: true } ``` - 未传 `id` 时自动生成 **`t_` + 8 hex**（与 Hermes 一致） - `note` / `description` / `body` 任一可作描述；`body` 为对象时 JSON 落库 **进度报告（agents 主路径）** ```bash curl -s -X POST http://127.0.0.1:18900/kanban/report \ -H 'Content-Type: application/json' \ -d '{ "id": "t_xxxxxxxx", "agent": "codex", "task": "标题可选", "status": "in_progress", "result": "⏳ 进度：已完成步骤 1/3" }' # → 写 DB status=running + task_comments + task_events ``` `status` 取值：`in_progress|running|done|blocked|ready|pending`（自动归一到 Hermes 名）。 **改状态 / 拖拽** ```bash curl -s -X POST http://127.0.0.1:18900/kanban/status \ -H 'Content-Type: application/json' \ -d '{"task_id":"t_xxxxxxxx","status":"running"}' curl -s -X POST http://127.0.0.1:18900/kanban/move \ -H 'Content-Type: application/json' \ -d '{"task_id":"t_xxxxxxxx","target_dir":"02_执行中"}' ``` **归档** ```bash curl -s -X POST http://127.0.0.1:18900/kanban/archive \ -H 'Content-Type: application/json' \ -d '{"task_id":"t_xxxxxxxx"}' ``` ### 3.3 Hermes CLI（同库） ```bash hermes kanban create '[L1][P2][5号][codex] 标题' --assignee codex --priority 2 --body '...' hermes kanban show t_xxxxxxxx hermes kanban comment t_xxxxxxxx --author agent '⏳ 进度 ...' hermes kanban complete t_xxxxxxxx --result '✅ 完成：路径/摘要' hermes kanban stats hermes kanban list --status running ``` --- ## 4. 双向同步验收清单（新节点必须全绿）在目标机执行（5号已于 2026-08-01 全绿）： | # | 场景 | 通过标准 | |:--|:-----|:---------| | A | `hermes kanban create` → `GET /kanban/api/task?id=` | Web 立刻看到，status=ready | | B | `POST /kanban/status` in_progress | DB `status=running`（不是 in_progress） | | C | Hermes `complete` 在 running 卡上 | 成功；Web 显示 done | | D | `POST /kanban/create` | 返回 `t_…` 且 `kanban_db_ok=true`；`hermes kanban show` 可见 | | E | `POST /kanban/report` in_progress | DB=running + 有 comment | | F | `POST /kanban/report` done | DB=done + result 有值 | | G | Hermes `comment` → Web detail | comments 数组含该正文 | 一键脚本： ```bash python3 /root/skill-pack/kanban-hermes-web-sync/scripts/sync_smoke_test.py # 或 python3 /root/.agents/skills/kanban-mcp-ops/scripts/kanban_report.py --help ``` --- ## 5. 新服务器接入步骤（装了 Hermes 后复用） ### 5.1 前置 1. 本机可跑 `hermes kanban stats`，且 `~/.hermes/kanban.db` 存在 2. Python3 + pm2（或 systemd） 3. 可选：rclone 挂载 GDrive 到 `/mnt/gdrive` 4. 同步 skill：`task-card-publish`、`kanban-mcp-ops`（见 skill 文末分发方式） ### 5.2 部署 Web 门面 ```bash # 1) 拷贝 5号已打通的 server（真源在 5号） scp root@10.0.0.5:/usr/local/bin/kanban-server.py /usr/local/bin/kanban-server.py # 依赖：/usr/local/lib/antcolony/ant_alias.py（可一并 rsync） # 2) 确认 KANBAN_DB 路径指向本机 Hermes # 默认 /root/.hermes/kanban.db —— 若 Hermes 家目录不同，改常量或加环境覆盖 # 3) 数据目录 mkdir -p /data/kanban ln -sfn /root/.hermes/kanban.db /data/kanban/kanban.db # 4) 启动（示例 pm2） pm2 start /usr/local/bin/kanban-server.py --name kanban-server --interpreter python3 pm2 save # 5) 本机冒烟 curl -s http://127.0.0.1:18900/kanban/protocol | jq .authority # hermes_kanban_db python3 /root/skill-pack/kanban-hermes-web-sync/scripts/sync_smoke_test.py ``` ### 5.3 反代（可选外网） nginx 片段： ```nginx location /kanban/ { proxy_pass http://127.0.0.1:18900/kanban/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location = /kanban { return 302 /kanban/; } ``` ### 5.4 节点身份 - `source_node` / `requester_node` / `target_node`：用 `3hao|4hao|5hao|6hao`（新节点起规范名如 `7hao`） - Web create 写入的 `source_node` 当前代码默认为 `5hao` —— **新节点务必改 `mirror_task_created_to_kanban_db` / report 内硬编码为本地节点名** - assignee 必须是本机真实 profile：`hermes kanban assignees` ### 5.5 跨节点（后期 4/6 等同法） | 模式 | 做法 | |:-----|:-----| | **A. 中心门面** | 只在 5号跑 Web；其它节点用 Hermes CLI 写本机库，再经 Relay `kanban:*` 事件同步（见 `codex_tasks/v2.0_codex_check/docs/kanban-relay-protocol.md`） | | **B. 每节点门面** | 每台按 5.2 起 `kanban-server`，绑定**本机** `kanban.db`；跨节点任务用 `target_node` + webhook/Relay，不跨库直写 | | **C. 只 API 互通** | 远端 `POST http://5号:18900/kanban/create`（需网络/鉴权）；执行仍在目标机 Hermes | 推荐：**B 或 A**，禁止多机同时写同一个 sqlite 文件。 --- ## 6. 进程与排障 ```bash pm2 list | grep kanban pm2 logs kanban-server --lines 50 ss -lntp | grep 18900 ls -la /root/.hermes/kanban.db /data/kanban/kanban.db hermes kanban stats curl -s http://127.0.0.1:18900/kanban/stats ``` 常见问题： | 现象 | 原因 | 处理 | |:-----|:-----|:-----| | Web 有卡、Hermes complete 失败 | DB 被写成 `in_progress` | 升级 kanban-server；`UPDATE tasks SET status='running' WHERE status='in_progress'` | | report 返回 ok 但 DB 无变化 | 旧版 report 只写 json/md | 使用 2026-08-01 后版本（含 `report_task_to_db`） | | 任务 id 无 `t_` 前缀 | 旧 create | 升级；已有卡可保留，新卡自动 `t_` | | stats 数字 Web ≠ Hermes | Hermes `stats` 按生命周期枚举；Web 含 done 未归档全集 | 正常；以 `show id` 对单卡 | | 双库分叉 | `/data/kanban/kanban.db` 不是软链 | 停写 → 备份 → 软链回 Hermes 路径 | 备份路径示例：`/usr/local/bin/kanban-server.py.bak-20260801-syncfix` --- ## 7. 与任务卡规则的衔接发任务前强制 `task-card-publish` 六问：安排给谁 / 效果 / 验收 / 时效 / 通知谁 / 附录。标题：`[L级][P级][来源][负责人] 标题`。接单后走 `kanban-mcp-ops`：claim → report → comment → 产出目录 → done。 Web 与 CLI 只是**入口形态**不同，卡片字段与验收标准同一套 v3。 --- ## 8. 5号样板实测记录（摘要） | 用例 | 结果 | |:-----|:-----| | Hermes create → Web detail | PASS (`t_05891ae9` 等) | | Web status → DB `running` → Hermes complete | PASS | | Web create → `t_` id → Hermes show | PASS | | report → comment + running/done | PASS | | Hermes comment → Web comments | PASS | 代码真源（5号）： ```text /usr/local/bin/kanban-server.py 备份：/usr/local/bin/kanban-server.py.bak-20260801-syncfix 副本：/root/kanban-server-v4.py ``` --- ## 9. 文件索引 | 文档/物 | 路径 | |:--------|:-----| | 本文（治理真源） | `/root/.hermes/GOVERNANCE/kanban_hermes_web_sync_guide.md` | | Wiki 接入 | `/root/wiki/接入/Hermes_Web看板接入指南.md` | | 冒烟脚本 | `/root/skill-pack/kanban-hermes-web-sync/scripts/sync_smoke_test.py` | | 任务卡协议 | `/root/.hermes/GOVERNANCE/task_card_protocol_v3.md` | | 看板悟透 | `/root/.hermes/GOVERNANCE/kanban_insight_20260801.md` | | 发任务 skill | `/root/skill-pack/task-card-publish/` | | 接单 skill | `/root/skill-pack/kanban-mcp-ops/` | --- *5号 Grok · 2026-08-01 · 内部看板与 Web 看板双向联调通过后沉淀*