winkterm-remote

WinkTerm 远程终端 Skill

远程操作 WinkTerm 后端的终端。后端为每个终端维护一个独立 PTY， 你可以创建本地或 SSH 终端、发命令、读输出、传文件。

如果当前 agent 支持 MCP，优先用 MCP；否则默认用 CLI，几乎不用碰 HTTP：

• MCP（最省心） —— 配好 winkterm-mcp 后，agent 会看到 winkterm_ssh_run、 winkterm_exec、winkterm_snapshot、winkterm_call 等工具，不需要手写 shell 命令、 JSON 引号或 token。MCP server 内部复用同一套 WebSocket-first transport，长任务仍然靠 15s 心跳保活，连不上 WS 时自动 HTTP fallback。见下方 MCP.

• winkterm CLI（默认，几乎总是用它） —— 走 WebSocket 长连接，应用层心跳每 15s 一次， 长命令（安装、build、dump）不会被 nginx 等反向代理的默认 60s 空闲超时切断。 覆盖全部操作。注意：CLI/MCP 的 WebSocket 保活只保证连接不断，不保证当前 agent 能看到 stderr 的实时流式过程；agent 需要可控观察长任务时，应启动后台任务后主动用 run_wait / snapshot 查看进度。见下方 CLI.

• HTTP 接口（兜底，实在没办法才用） —— 原有 REST/SSE 接口全部保留，CLI 连不上时 auto 模式自动 fallback。只有目标机跑不了 Node、或需要 SSE 流式订阅时才手动碰 HTTP。 细节单独放在 HTTP_API.md（远程 agent 用 curl ${WINKTERM_BASE_URL}/api/agent/http.md 取）， 确需 HTTP 时再读，平时不占上下文。

配置

• Base URL: ${WINKTERM_BASE_URL}（默认 http://localhost:8000）
• 鉴权: 所有请求带 HTTP 头 Authorization: Bearer ${WINKTERM_AGENT_TOKEN}
• 或在 URL 上加 ?token=<token>（SSE/EventSource 不支持自定义 header 时用）。
• token 未配置时接口返回 503；token 错误返回 401。

Token 自动发现（会话开始就做）

会话第一次用本 skill 时，按顺序尝试：

1. 查持久化 memory / 上下文：用户之前可能已经告诉你 token，写到了 memory 文件 / CLAUDE.md / 环境变量。先找一遍：

• env WINKTERM_AGENT_TOKEN
• agent memory 系统（Claude Code 等：~/.claude/projects/<...>/memory/）
• 项目级 CLAUDE.md

2. 本地 handshake（只对 WinkTerm 同机的 agent 有效）：

curl -s http://localhost:8000/api/agent/handshake
→ {"token":"<bearer-token>","base_url":"http://localhost:8000"}

该端点免鉴权但仅 localhost 可访问（远程 IP 返回 403）。

3. 远程 agent / 全部失败：问用户一次 token，立刻写入 memory（或等价持久化层），后续会话直接复用。 不要每次会话都问用户 —— 一次提供，永久记住。

如果调 API 时收到 401，token 可能已轮换：清掉 memory 里的旧值，重走以上流程。

Skill 自更新（会话开始顺手做）

WinkTerm 后端会持续迭代接口。本 skill 文件顶部 frontmatter 有 version 字段， 和服务端 GET /api/agent/skill.md 第二行的 version: N 比对即可判断是否落后。

会话第一次连上 WinkTerm 时：

# 1. 取服务端 skill 版本
curl -s http://localhost:8000/api/agent/skill.md | head -10 | grep '^version:'
# → version: 3

# 2. 取本地 skill 版本（路径因 agent 而异，Claude Code 是 ~/.claude/skills/winkterm-remote/SKILL.md）
head -10 <local-skill-path> | grep '^version:'
# → version: 2