ngrok-preview

为本地工件生成短暂的、适合移动设备的 ngrok 预览链接，并在 Telegram 中共享它们。当 OpenClaw 生成用户需要在手机上远程查看的图像/图表/生成文件时使用，并且每个任务的临时链接优于手动文件传输。

# ngrok-preview

Provide a temporary preview window for task outputs. Keep it fast, scoped, and easy: generate link -> send link -> close link.

## One-time setup

1. Install ngrok if missing.
2. Configure auth token once:

```bash
ngrok config add-authtoken "$NGROK_AUTHTOKEN"
ngrok config check
```

If token is not preconfigured, pass `--auth-token` when running the script.

## Per-task workflow

1. Collect only task artifacts (images/charts/files) for this request.
2. Create a session-scoped temporary preview link.
3. Send the link with explicit expiry in Telegram.
4. Stop and delete the preview session after user confirms or task ends.

Use this command from the skill directory:

```bash
python3 scripts/ngrok_preview.py up \
  --title "<task title>" \
  --session-id "<task-id>" \
  --ttl-minutes 120 \
  --source "<artifact-path-1>" \
  --source "<artifact-path-2>"
```

The command returns JSON including:
- `public_url`
- `expires_at`
- `session_id`
- `stop_command`

### Session ID convention (context binding)

Use IDs that map to the current conversation/task:
- `tg-<date>-<topic>`
- `task-<short-request-id>`

This keeps each link tied to one task context.

## Telegram send pattern

After `up` succeeds, send a concise message:

```text
🔗 Temporary preview link (valid for <X> minutes)
<public_url>

Scope: artifacts from this task only
This link will be cleaned up after expiry
```

If not currently in Telegram, still return the same link format in the active channel.

## Safety boundaries

- Publish only task-specific outputs, never broad directories (do not expose workspace root).
- Keep TTL short (default 120 minutes; use shorter when possible).
- Treat link as temporary access, not persistent hosting.
- Stop session when no longer needed:

```bash
python3 scripts/ngrok_preview.py down --session-id "<task-id>" --delete-session-dir
```

- Periodically clear expired sessions:

```bash
python3 scripts/ngrok_preview.py cleanup
```

## Command quick reference

```bash
# List sessions
python3 scripts/ngrok_preview.py status

# Create preview (auto-generate session id)
python3 scripts/ngrok_preview.py up \
  --title "image results" \
  --source ./outputs/result-1.png \
  --source ./outputs/result-2.png

# Stop latest session
python3 scripts/ngrok_preview.py down
```

## Troubleshooting

If link creation fails, check `references/troubleshooting.md` and follow the minimum recovery sequence.

---

## 中文说明

# ngrok-preview

为任务输出提供一个临时预览窗口。保持快速、范围受限且易用：生成链接 -> 发送链接 -> 关闭链接。

## 一次性设置

1. 如未安装则安装 ngrok。
2. 配置一次 auth token：

```bash
ngrok config add-authtoken "$NGROK_AUTHTOKEN"
ngrok config check
```

如果 token 未预先配置，运行脚本时传入 `--auth-token`。

## 每个任务的工作流

1. 仅收集本次请求的任务工件（图像/图表/文件）。
2. 创建一个会话级的临时预览链接。
3. 在 Telegram 中发送链接，并明确说明过期时间。
4. 在用户确认或任务结束后，停止并删除该预览会话。

在技能目录下使用以下命令：

```bash
python3 scripts/ngrok_preview.py up \
  --title "<task title>" \
  --session-id "<task-id>" \
  --ttl-minutes 120 \
  --source "<artifact-path-1>" \
  --source "<artifact-path-2>"
```

该命令返回的 JSON 包含：
- `public_url`
- `expires_at`
- `session_id`
- `stop_command`

### 会话 ID 约定（上下文绑定）

使用能映射到当前对话/任务的 ID：
- `tg-<date>-<topic>`
- `task-<short-request-id>`

这样每个链接都绑定到一个任务上下文。

## Telegram 发送模式

`up` 成功后，发送一条简洁的消息：

```text
🔗 Temporary preview link (valid for <X> minutes)
<public_url>

Scope: artifacts from this task only
This link will be cleaned up after expiry
```

如果当前不在 Telegram 中，仍在当前活跃频道返回相同格式的链接。

## 安全边界

- 仅发布任务专属的输出，绝不发布宽泛的目录（不要暴露 workspace 根目录）。
- 保持 TTL 较短（默认 120 分钟；尽可能更短）。
- 将链接视为临时访问，而非持久化托管。
- 不再需要时停止会话：

```bash
python3 scripts/ngrok_preview.py down --session-id "<task-id>" --delete-session-dir
```

- 定期清理过期会话：

```bash
python3 scripts/ngrok_preview.py cleanup
```

## 命令速查

```bash
# List sessions
python3 scripts/ngrok_preview.py status

# Create preview (auto-generate session id)
python3 scripts/ngrok_preview.py up \
  --title "image results" \
  --source ./outputs/result-1.png \
  --source ./outputs/result-2.png

# Stop latest session
python3 scripts/ngrok_preview.py down
```

## 故障排查

如果链接创建失败，查看 `references/troubleshooting.md` 并按最小恢复步骤操作。