# Kestra 受控 Bridge 接口规范 v1

更新时间：2026-06-02
状态：设计草案

## 1. 目标

Bridge 的目标是让 Kestra 能调用 Bot1、Bot2、OpenClaw 等执行层，同时避免 Kestra 容器直接接触 Hermes/OpenClaw 的敏感 profile 环境、auth 文件和本机权限。

POC 已验证：

```text
Kestra -> host.docker.internal:19091 -> local bridge -> Hermes/OpenClaw/SSH -> JSON result
```

正式版本应升级为：

```text
Kestra -> HTTPS/token -> bridge -> allowlisted wrapper -> structured JSON
```

## 2. 核心原则

1. 不接受自由 shell 命令。
2. 不接受任意 prompt 直通。
3. 不暴露 `.env`、`auth.json`、token、cookie、Feishu secret。
4. 不允许 bridge 直接写 NAS 共享知识库、项目归档、`03_用户资料`。
5. 每个 endpoint 绑定一个固定 wrapper 和固定能力边界。
6. 每次调用必须有 `request_id` 和 `flow_id/execution_id`。
7. 输出必须是结构化 JSON。
8. stderr/stdout 必须脱敏和截断。
9. 每个 wrapper 必须有 timeout、并发限制、最大输出大小。
10. 重要副作用由 Hermes IT 再验收，不信任 worker 自述。

## 3. 推荐 Endpoint

### `GET /health`

返回 bridge 自身健康。

```json
{
  "ok": true,
  "service": "kestra-agent-bridge-bot1",
  "version": "0.1.0",
  "host": "bot1",
  "time": "2026-06-02T23:00:00+08:00"
}
```

### `POST /v1/hermes/profile-run`

调用指定 Hermes profile 执行受控任务 brief。

请求：

```json
{
  "request_id": "kestra-exec-xxx-step-yyy",
  "profile": "it",
  "brief_path": "/path/to/brief.md",
  "output_dir": "/path/to/output",
  "mode": "bounded",
  "timeout_sec": 600,
  "expected_markers": ["BOT1_OK"]
}
```

限制：

- `profile` 必须在 allowlist；
- `brief_path` 必须在允许根目录；
- `output_dir` 必须在允许根目录；
- 不接受任意命令；
- profile 不得被要求改 gateway/config/LaunchAgent，除非另有高风险确认。

响应：

```json
{
  "ok": true,
  "request_id": "...",
  "profile": "it",
  "exit_code": 0,
  "elapsed_sec": 12.3,
  "stdout_tail": "...",
  "artifacts": [
    {"path": "/path/to/output/result.json", "sha256": "...", "bytes": 1234}
  ],
  "markers_found": ["BOT1_OK"]
}
```

### `POST /v1/openclaw/worker-run`

调用 OpenClaw 受控 worker。

请求：

```json
{
  "request_id": "...",
  "worker": "video-executor",
  "brief_path": "/path/to/brief.md",
  "output_dir": "/path/to/output",
  "timeout_sec": 900
}
```

限制：

- worker 必须在 allowlist；
- 不允许 OpenClaw 写 NAS；
- 不允许改 Hermes Skills/SOUL/config；
- 不允许安装 daemon/LaunchAgent；
- 输出由 Hermes 再验收。

### `POST /v1/remote/bot2-profile-run`

Bot1 bridge 通过 SSH/API 调 Bot2，或 Kestra 直接调 Bot2 bridge。长期推荐后者：

```text
Kestra -> Bot2 bridge -> Bot2 Hermes profile
```

而不是：

```text
Kestra -> Bot1 bridge -> SSH Bot2 -> Hermes
```

POC 使用 SSH 是为了快速验证跨机器可行。

## 4. 鉴权设计

最低要求：

- Bridge 只监听内网 IP 或 Tailscale/局域网 IP；
- `Authorization: Bearer <bridge-token>`；
- token 放在 Kestra secret/env，不进入 flow 日志；
- token 定期轮换；
- 拒绝无 token 请求。

增强版：

- mTLS；
- IP allowlist；
- per-flow scoped token；
- request 签名；
- replay protection：timestamp + nonce。

## 5. Allowlist 示例

```yaml
profiles:
  bot1:
    - it
    - designer1
    - visual-operator
    - video
  bot2:
    - it2
    - novelist
    - screenwriter

workers:
  openclaw:
    - main
    - video-executor

allowed_roots:
  bot1:
    - /Users/bot1/Volumes/root_for_ai/AI工作区
    - /tmp/kestra-agent-work
  bot2:
    - /Users/bot2/.hermes/profiles/it2/handoffs
    - /tmp/kestra-agent-work
```

## 6. 日志脱敏

必须替换：

```text
api_key=...
token=...
secret=...
password=...
Authorization: ...
app_secret=...
verification_token=...
encrypt_key=...
```

输出限制：

- `stdout_tail` 最多 4–8 KB；
- 完整日志只存在本机 bridge 日志中，且仍需脱敏；
- Kestra task output 只保存摘要。

## 7. 并发与超时

建议起步：

| 类型 | 并发 | timeout |
|---|---:|---:|
| profile ping/health | 2 | 60–180s |
| Hermes profile bounded task | 1/profile | 600–1200s |
| OpenClaw worker | 1/worker | 900–1800s |
| Bot2 SSH/API | 1/profile | 600–1200s |

同一个 profile 不建议并发多任务，避免 profile session/context/credentials 竞争。

## 8. 错误码

Bridge 响应不直接用 shell exit code 作为唯一判断。推荐：

```json
{
  "ok": false,
  "error_code": "PROFILE_TIMEOUT",
  "exit_code": 124,
  "message": "profile run timed out",
  "retryable": true
}
```

常见错误：

- `UNAUTHORIZED`
- `PROFILE_NOT_ALLOWED`
- `PATH_NOT_ALLOWED`
- `PROFILE_TIMEOUT`
- `REMOTE_UNREACHABLE`
- `WORKER_BUSY`
- `OUTPUT_VALIDATION_FAILED`
- `SECRET_REDACTION_TRIGGERED`
- `HIGH_RISK_ACTION_BLOCKED`

## 9. 高风险动作阻断

Bridge/wrapper 遇到这些动作必须拒绝或返回 `HIGH_RISK_ACTION_BLOCKED`：

- restart Hermes gateway/profile/LaunchAgent；
- 修改 Hermes config/auth/skills；
- NAS 写共享知识库/项目归档/`03_用户资料`；
- 外发正式消息；
- 输入密码/付款/账号安全操作；
- 删除/覆盖大范围文件；
- 未确认的服务常驻安装。

## 10. POC 到正式版差异

| 项目 | POC | 正式版 |
|---|---|---|
| 协议 | HTTP loopback | HTTPS/token 或内网 token |
| endpoint | `/ping/*` | `/v1/...` |
| 命令 | 少量固定 ping | allowlisted wrapper |
| 鉴权 | 无，仅 loopback | 必须有 |
| 日志 | 简单脱敏 | 系统化脱敏 + 限长 |
| 并发 | 未限制 | per profile/worker 限制 |
| NAS 写入 | 无 | 仍必须 Hermes 二次确认 |