regrevia/Envoy / integrations/skills/envoy
envoy
FlaggedRead material the host cannot get itself: video or audio transcripts and frames, PDFs and Office documents, image posts, pages that need scrolling, cookies, or login, GitHub repo/tree/blob/commit/pull/issue links when no gh or git is available, articles a plain fetch truncates, and reads that must stay retained so a later turn can expand, search, or replay them. Start with a plain host fetch; call Envoy only after it is blocked, truncated, or renders an empty shell, or when the answer must outlive the turn. Do not call Envoy for a short static page a plain fetch already answers, for an article whose body a plain fetch already returned in full, for GitHub, GitLab, or Bitbucket source navigation or a repo README while gh or git is available (use gh api, git show, or plain fetch), for material already in this turn's context (use envoy_expand or envoy_search on its material_id), or for a link the user only wants edited, quoted, or saved.
| File | Kind | Size |
|---|---|---|
| INSTALL.md | markdown | 12.5 KB |
| LICENSE | other | 11.1 KB |
| NOTICE | other | 433 B |
| SKILL.md | skill md | 54.3 KB |
| hosts/README.md | markdown | 2.8 KB |
| hosts/mcp.json | config | 111 B |
| references/protocol.md | markdown | 10.3 KB |
| test-prompts.json | config | 7.9 KB |
INSTALL.md
View on GitHub# Envoy 安装 / Install
Envoy 由三部分组成:Skill 指令、本地 CLI runtime、宿主 MCP 连接。当前开发版
`0.1.63`,发行说明以 `CHANGELOG.md` 为准。
装哪个宿主都只需要一条命令:脚本先确认 `PATH` 上有够新的 `envoy`(已装且够新
就复用),再装该宿主的插件。**不需要先手动装 CLI**,也不需要先跑
`envoy browser setup`:runtime 在首次使用时自己补齐,浏览器在第一次要渲染
页面时自己装。
## 先认宿主 / Pick the host
三个宿主装的是三种不同的东西,先确认当前跑在哪个宿主里,再选对应的那条:
| 宿主 | 怎么认 | 装的产物 | 安装目标 |
| --- | --- | --- | --- |
| Claude Code | `command -v claude` | `claude plugin`(marketplace `envoy@envoy`,含 skill + MCP) | `claude-code` |
| Codex | `command -v codex` | `codex plugin`(MCP)+ 一条用户级 hook | `codex` |
| DeepSeek Harness | `command -v dsh`,桌面版在应用包内(`DSH_CLI` 指过去) | npm 包 `envoy-dsh`(bundle:MCP + skill + 路由) | `dsh` |
一句话判据:**宿主是 DeepSeek Harness 就装 `envoy-dsh`,是 Claude Code 就装
`envoy@envoy` 插件,是 Codex 就装 Codex 插件再补一次 `envoy hook install --host codex`。**
认不出来、或机器上装了好几个,把目标换成 `auto`,脚本按检测到的 CLI 各装一份。
## 一条命令 / One command
```bash
# Claude Code
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- claude-code
# Codex(插件装 MCP,脚本同时写用户级 hook)
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- codex
# DeepSeek Harness
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- dsh
# Claude Desktop / Cursor / Windsurf:只写一条 MCP 配置
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- mcp
# 只认 skill 目录的宿主:解到 ~/.envoy/skill/envoy
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- skill
# 机器上装了几个就都装
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- all
```
脚本只要求机器上有 `curl`:uv 和 Python 3.11 由它自己装(`ENVOY_SKIP_UV_INSTALL=1`
可关掉)。下载 runtime 时用 release 里的 `SHA256SUMS` 校验,装完自己跑一遍
`envoy doctor --json` 并打印版本;哪一步失败会停在那一步并给出原因。装完重启
宿主。想先看脚本会做什么:加 `ENVOY_DRY_RUN=1`,只打印命令不执行。
## Windows / PowerShell
```powershell
# 装它能认出来的所有宿主;也可以把 all 换成 claude-code / codex / dsh / mcp / skill
irm https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.ps1 | iex
# 显式给目标、或先看脚本会做什么
powershell -ExecutionPolicy Bypass -File install.ps1 claude-code
$env:ENVOY_DRY_RUN = "1"; powershell -ExecutionPolicy Bypass -File install.ps1 dsh
```
`install.ps1` 与 `install.sh` 同一套约定:装一个私有 runtime 并把它的绝对路径写进
`%USERPROFILE%\.envoy\runtime-path`,在 `%USERPROFILE%\.envoy\bin` 放一个 `envoy.cmd` 转发到
那份 runtime(不改系统级 PATH),再装宿主插件、准备一次浏览器。只装 MCP 条目的
宿主(Claude Desktop / Cursor / Windsurf)会写用户级配置,改动前自动备份。
Windows 侧已在托管干净机 `windows-2022` 上跑过一次完整档 `install.ps1` 全新安装(GitHub Actions run 40825123260,版本 0.1.33):PowerShell 5.1 与 PowerShell 7 两种都装完,`envoy doctor` 通过。这次只证明安装与自检,没有跑真实读取,读取结果仍以 `COMPATIBILITY.md` 的平台矩阵为准。
装完随时可跑 `envoy doctor` 自查:第一行 `runtime` 显示当前跑的是不是安装时
固定下来的那份 `envoy`;显示 `shadowed` 说明 PATH 里另有旧 `envoy`,按提示重跑
安装脚本即可。
## 手动安装 / Manual
### DeepSeek Harness
应用里 Plugin Manager → 搜 `Envoy` → Install。命令行等价:
```bash
dsh plugin --profile web add envoy-dsh
# 或装发行包,不经过 npm
dsh plugin --profile web add https://github.com/regrevia/Envoy/releases/download/v0.1.63/envoy-dsh-0.1.63.tgz
```
桌面版把 CLI 装在应用包内,用脚本时它会自己找到。
### Claude Code / Codex
```bash
# Claude Code
claude plugin marketplace add regrevia/Envoy
claude plugin install envoy@envoy
# Codex
codex plugin marketplace add https://github.com/regrevia/Envoy.git
codex plugin add envoy@envoy
envoy hook install --host codex
```
Codex 0.156 起不加载插件自带的生命周期 hook,所以 hook 要单独写一次用户级
`~/.codex/hooks.json`;该子命令自 `0.1.7` 起提供,`0.1.14` 已包含。首次运行
Codex 会要求确认 hook 信任。
### 没有插件的宿主:Skill + runtime
任何能读 skill 目录、能连 MCP 的宿主都可以只装这两样,一条命令分别装:
```bash
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- mcp
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- skill
```
`mcp` 会找 Claude Desktop、Cursor、Windsurf 的配置并只加 `mcpServers.envoy`
一条(先备份,不动其他 server);`skill` 把 `envoy-skill.zip` 解到
`~/.envoy/skill/envoy`(`ENVOY_SKILL_DIR` 可改目标)。要手工来一遍:
```bash
gh release download v0.1.63 --repo regrevia/Envoy --dir envoy-v0.1.63
cd envoy-v0.1.63
uv tool install --python 3.11 ./envoy_cli-0.1.63-py3-none-any.whl
```
也可以在 [GitHub Release](https://github.com/regrevia/Envoy/releases/tag/v0.1.60)
页面上直接下载 wheel 与 `SHA256SUMS` 手工核对。下载慢或装依赖超时,给
`install.sh` 设 `ENVOY_PYPI_INDEX_URL` 指向可用镜像即可。
然后在宿主的 MCP 配置里加一条:
```json
{
"mcpServers": {
"envoy": { "command": "envoy", "args": ["mcp"] }
}
}
```
`envoy` 不在 `PATH` 时把 `command` 换成绝对路径。默认只暴露 `core` 工具集;
需要本地视频、发现、合集、回放、视觉历史、doctor 这些时,启动宿主前设
`ENVOY_MCP_TOOLSET=full`。
## 验证首次读取 / Check the first read
```bash
printf '%s' '{"protocol_version":"envoy.read/1","request_id":"install-check","source":{"url":"https://example.org/"}}' | envoy read --request-json -
```
只验证公开网页读取,不代表视频或 ASR 已就绪。安装脚本结束时也会打印
`envoy doctor --json` 的 runtime 版本与协议版本,对不上就是没装成。
## 三档安装 / Three profiles
默认是完整档:runtime、Chromium 与 Whisper `base` 权重一次装齐,≈1.0 GB,装完
全部能力离线可用,第一次读不再等下载。CI 与容器选 `minimal`,装完只有 runtime,
Chromium 与权重由缺失时报错里的命令取回。
| 档位 | 装什么 | 大致体积 | 适合 |
| --- | --- | --- | --- |
| `full` 完整(默认) | runtime + Chromium + Whisper `base`:普通网页与 PDF 之外,需要渲染的页面、视频页、字幕、语音、无字幕视频都能处理 | 178 + 683 + 141 MB ≈ 1.0 GB | 装完不再下载,全部能力离线可用 |
| `standard` 标准 | runtime + Chromium:再加必须渲染的页面、视频页 | 178 + 683 MB ≈ 860 MB | 只用网页能力,不需要转写 |
| `minimal` 简洁 | 只有 runtime:读普通网页、PDF、图片 | 178 MB | CI / 容器,愿意首次需要时再下载 |
Whisper 那 141 MB 是 whisper.cpp 的 GGML `base` 权重(`ggml-base.bin`,实际
147,951,465 字节)。机器上没有 whisper.cpp 时,`envoy asr install` 会落到
openai-whisper + torch:功能相同,但要多一份 torch,体积以那一刻的下载为准。
```bash
# 不写 --profile 就是完整档(≈1.0 GB)
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh
# CI / 容器:只装 runtime
curl -fsSL .../install.sh | sh -s -- --profile minimal dsh
# 不要转写
curl -fsSL .../install.sh | sh -s -- --profile standard dsh
# Windows
powershell -ExecutionPolicy Bypass -File install.ps1 -Profile minimal
```
缺能力时的报错会带 `command`、`download`、`ask_first`:先说明这一档补上什么、
需要下载多少,再问用户要不要装,不要静默下载几百 MB。
`ENVOY_PROFILE=minimal` 与 `--profile` 等价(不设就是 `full`);`ENVOY_SETUP_BROWSER=0`、
`ENVOY_SETUP_MEDIA=0` 覆盖所选档位里的某一步(CI 里既想要完整档的插件接线、又不想
下载时用);`ENVOY_ASR_MODEL` 换 `full` 档预取的模型(默认 `base`)。
装完核对,以及升级后回收旧浏览器:
```bash
envoy doctor --json # browser.ready、asr_model_available 应为 true
envoy browser prune --dry-run # 先看会回收多少,不删
```
Playwright 每升一次就换个浏览器版本、从不删旧的,所以升级几次后缓存会翻倍;
`envoy browser setup` 装完会自动清掉被替换掉的旧版本,`envoy browser prune` 可手动
重跑(`--dry-run` 只报不删)。
体积口径:runtime 178 MB 与 Chromium 683 MB(Windows,mac 上 573 MB)实测;
Whisper `base` 的 GGML 权重 141 MB 按官方发布体积(147,951,465 字节)计。机器上
没有 whisper.cpp 时改走 torch,那一份体积各平台不同,本仓库没有实测数字。
后装的补法:`minimal`/`standard` 想升级能力,重跑安装脚本并带 `--profile full`
即可,两步都是幂等的。
English: the installer takes `--profile minimal|standard|full` (`ENVOY_PROFILE` is
the same knob) and defaults to `full` — runtime, Chromium and the Whisper `base`
weights, about 1.0 GB (178 + 683 + 141 MB), so every capability works offline and
nothing downloads on first use. `minimal` is the runtime alone, about 178 MB, for
CI and containers: the first page that needs rendering names `envoy browser setup`
(a one-time ~683 MB Chromium download) and the first transcript names
`envoy asr install --model base` (~141 MB of GGML weights on a whisper.cpp
machine). Runtime 178 MB was measured on macOS and Chromium 683 MB on the measured
Windows host (see the size note above); a machine without whisper.cpp resolves to
the openai-whisper + torch stack, which is not measured here.
## 更新与卸载 / Update and remove
```bash
# 更新 runtime:重跑安装脚本,或在 DSH 里重装 bundle
curl -fsSL https://raw.githubusercontent.com/regrevia/Envoy/main/integrations/install.sh | sh -s -- dsh
# 单独换 wheel
uv tool install --force --python 3.11 ./envoy_cli-0.1.60-py3-none-any.whl
# 卸载
claude plugin uninstall envoy
codex plugin remove envoy
dsh plugin --profile web remove envoy-dsh
uv tool uninstall envoy-cli
```
## 源码开发 / From a checkout
```bash
scripts/dev_install.sh # .venv + editable envoy-core 与 envoy-cli
```
只用 `pip install -e packages/envoy-cli` 会失败:CLI 导入 `envoy-core`,而它不在
PyPI 上;且 CLI 要 Python >= 3.10,macOS 自带的 `python3` 是 3.9。脚本用 `uv`
取一个够新的解释器并两个包一起装。
## 可选能力 / Optional capabilities
- **浏览器渲染**:首次读到需要 JS 的页面时自动 `playwright install chromium`。
想自己控制就在启动宿主前设 `ENVOY_DISABLE_AUTO_BROWSER_SETUP=1`,之后手动
`envoy browser setup`。
- **ASR(本地视频转写)**:需要时按提示装 FFmpeg 与对应模型;没有它时视频页
会退化成读页面正文并标 `partial`,不是整条失败。手工装可跑
`envoy asr install --model base`。下载可以断点续跑:默认 10 分钟没下完就停下并保留断点,
再跑一次同一命令从断点继续,网络慢时可调大 `ENVOY_ASR_DOWNLOAD_SECONDS`;
不想现在装就在启动安装器前设 `ENVOY_SETUP_MEDIA=0`。
- **OCR**:截图里的文字在缺 OCR 时不可用,装好后再读同一 `material_id`。
## Scope and license
见 [LICENSE](LICENSE) 与 [NOTICE](NOTICE)。Envoy 只读取公开可访问的内容。
登录态默认不碰:Envoy 不读取个人浏览器会话。用户自己授权后(`envoy auth handoff on`),可以在 Envoy 自己的浏览器里登录一次,或按域导入已有会话(`envoy auth import --from chrome --domain <站点>`)。登录态只保存在本机,可以查看(`envoy auth status`)、停用(`envoy auth handoff off`)、清除(`envoy auth clear`)。关掉开关只是停止使用,不删除历史登录态;删除需要走清除入口。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |