# Taifost-Hermes

中文使用手册：[`docs/USER_GUIDE.zh-CN.md`](docs/USER_GUIDE.zh-CN.md)

实施架构与技术说明：
[`docs/IMPLEMENTATION_ARCHITECTURE.zh-CN.md`](docs/IMPLEMENTATION_ARCHITECTURE.zh-CN.md)

Hermes 角色配置与修改：
[`docs/ROLE_CONFIGURATION.zh-CN.md`](docs/ROLE_CONFIGURATION.zh-CN.md)

The deliberately small integration boundary between Hermes Agent and Taifost
Core. It exposes exactly two MCP tools:

- `taifost_save_draft`
- `taifost_publish`

The adapter computes the Markdown SHA-256 itself, sends a stable
`Idempotency-Key`, retries only transport/5xx failures, and never exposes the
Core bearer key to an LLM tool argument or tool result.

## Configuration

Required environment variables:

- `TAIFOST_CORE_URL` — Core origin, for example `http://127.0.0.1:2333`
- `TAIFOST_HERMES_API_KEY` — the same secret as Core's `HERMES_API_KEY`

Optional: `TAIFOST_HTTP_TIMEOUT_SECONDS` (default `20`) and
`TAIFOST_HTTP_RETRIES` (default `3`).

`taifost-hermes-watchdog` provides model-independent timeout notifications.
It scans the durable Kanban board, retries each configured delivery target,
falls back to later targets, and records successful notifications so one task
run is reported only once. The included user-level systemd timer checks every
five minutes. QQ is enabled now; add `email` to
`TAIFOST_NOTIFICATION_TARGETS` after Hermes email credentials are configured.

For the installed Hermes environment, add the block in
[`config/hermes-mcp.example.yaml`](config/hermes-mcp.example.yaml) to the
publisher profile only. The other profiles must not receive this MCP server.
The safe, secret-free role settings are recorded as `config.overlay.yaml`
beside each profile template. Merge those keys into the matching Hermes
profile; do not copy the orchestrator's QQ credentials into worker profiles.

## Verification

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
```