heliograph

---

有人能访问这台机器。你不能，而你才是知道该问它什么的人。heliograph 将这段距离变成一个循环，而不是单纯的转交：你发布一个步骤，它在远端运行，随后整个运行过程都会作为日志返回，每一行都带有 UTC 时间戳，无论成功还是失败。

you        heliograph send net-probe ────────────────▶ transport
station    picks it up within seconds, runs it
           pushes status, then the log ──────────────▶ transport
you        heliograph logs --last --gaps ◀────────────

跨越这段距离的三种方式

heliograph 将请求送到一台你无法登录的机器，并把日志带回来。跨越这段距离有三种方式，区别只在于：什么会一直保留，以及保留多久。

Beacon。 你无法访问这台机器，它也无法访问你，但你们都能访问同一个约定地点。你把请求留在那里，然后离开。之后机器路过时会取走请求、执行它，并留下日志供你收取。双方从未建立连接；中间等待的是一条消息。这是三种方式中最安全的一种，因为要执行的代码已经在远端，可以在任何操作发生前先行查看；但也最慢，因为你要等机器下次到访。

Flare。 你可以直接访问这台机器的入口。你敲门、交出请求，在门口等待它运行，然后在同一次访问中带走日志。中间没有等待，也不会保持连接。它更快，因为不必等待取件。代价是：你要把代码带过去，因此机器信任的是入口，而不是事先审核代码。

Beam。 你和机器建立连接并保持连接畅通。任意一方都可以随时发话，另一方会立即听到，直到你挂断。这是真正的会话，而非一条消息或一次敲门；也是暴露面最大的一种，因为连接畅通时，任何内容都可能沿着连接传输。你可以主动启用它，并在完成后关闭。它仍在设计中，尚未成为可选的传输方式。

一句话概括：Beacon 保留一条消息，Flare 是一次往返，Beam 保留连接本身。

听起来熟悉吗？

• 你没有生产环境的 SSH 访问权限，而且也不会有人给你。
• 环境是气隙隔离的，或位于你无法访问的堡垒机、跳板机或 VPN 之后。
• 这是一个客户所有或由客户管理的资产环境。只有他们的员工可以登录。
• 访问受阻的原因是策略，而非能力：受限、变更受控，或需要他人批准。
• 你已经第四次遇到**“你能运行这个并粘贴输出吗”**，而对方发回来的却是半个终端的截图。
• 你是正在推动调查的 AI 编码 Agent，需要的是证据，而不是别人对证据的总结。

如果你能直接通过 SSH 登录，就不需要这个工具。

三个角色，一个边界

边界就是间隙，而布局只需说明一次：

控制	你的机器：heliograph CLI、heliograph mcp，以及驱动它们的技能。Go，以及近端所能承受的一切
传输	通道：git、中继、文件共享、捆绑包、对象存储——都位于同一个接口之后，因此只读门控集中在一处，不会因传输方式而出现偏差
站点	远端：植入私有传输仓库的 station/bash/。Bash 4+、git 和 GNU coreutils。无需软件包、凭据或隧道

远端绝不会安装任何东西。 站点是纯文本，你可以先阅读再运行——使用 Bash 4+；对于没有 Bash 且不会安装 Bash 的 Windows 环境，则使用 PowerShell 5.1。station/ 下绝不会出现 Go，唯一例外是让 CLI 携带负载的那个文件。CI 会强制执行这一点。对于安装任何东西都要单独提交变更请求的锁定设备，这项约束就是整个方案的价值所在。

安装

# Linux and macOS, from a release
curl -sSL https://github.com/heliograph-io/heliograph/releases/latest/download/heliograph-linux-amd64 \
  -o /usr/local/bin/heliograph && chmod +x /usr/local/bin/heliograph

# or from source
go install github.com/heliograph-io/heliograph/cmd/heliograph@latest

单个静态二进制文件，无需运行时。每次发布都会附带校验和，二进制文件中包含构建时使用的站点负载。

构建可复现：packaging/reproduce.sh v0.4.3 会从标签重建每个已发布的制品，并得到已发布的哈希值，因此“路径中的二进制文件就是你所读的源码”是可以验证的事实，而不只是我们的一句承诺。完整说明（包括尚未涵盖的内容）见docs.heliograph.io/provenance。

Agent 技能——同一工作循环，可通过 Claude Code、Codex、Cursor 等驱动：

/plugin marketplace add dbhq-uk/marketplace
/plugin install heliograph@dbhq         # Claude Code
./install-codex.sh                      # Codex, from a clone
./install.sh                            # Claude Code, from a clone
npx skills add heliograph-io/heliograph       # any agent, via skills.sh

使用

heliograph bootstrap ~/transport/payments             # plant the station payload
heliograph init payments --dir ~/transport/payments   # git, the default
heliograph plant                                      # what to send the operator
heliograph send net-probe HOSTS="sql01 sql02"         # publish a request
heliograph watch                                      # follow it
heliograph logs --last                                # read the whole log
heliograph logs --last --gaps                         # where it stalled
heliograph doctor                                     # will this work from here
heliograph mcp                                        # serve all of the above as tools

操作员要做的全部事情就是执行 plant 打印出的步骤：克隆传输仓库，运行 ./start.sh，然后离开。除非操作员另有说明，否则整个循环都只读：每个步骤都会声明自身模式（# heliograph-mode: read-only 或 action）；未声明模式的步骤不会运行；除非使用 --allow-actions 启动，否则站点会拒绝执行操作。它也不会以 root 身份运行。

对于 Agent，heliograph mcp 就是同一 CLI，只是以 MCP 工具的形式输入：

claude mcp add heliograph -- heliograph mcp

门控机制不会改变。工具调用会发布请求；是否运行，仍由站点决定。

--gaps 是值得了解的选项。“读取内容前，先扫描时间戳列中的间隔”是此方法中最有价值的一条指令，而且这只是算术：

$ heliograph logs --last --gaps
demo-20260906T183628Z.txt
5 captured lines

1 interval(s) of 10s or more, longest first.
Each is attributed to the line BEFORE it, which is what was running.

   3m12s  after  09:14:02 | Refreshing state...

间隔归属于它前面的那一行：一行上的时间戳表示该行的产出时间，因此较长的间隔意味着耗时的是前一行中标明的操作。如果日志中的每一行都带有相同的时间戳，则会报告为错误，而不是“没有间隔”。

状态

通过 git 控制 CLI	可用，已针对标准 station 完成端到端测试
heliograph bootstrap	可用：该二进制会部署其构建时包含的 station
--gaps	可用
MCP 服务（heliograph mcp）	可用
bash station	正通过 git 使用：循环、门控、捕获、Azure 主机、Kubernetes、Windows 启动器
relay	端到端可用。heliograph init --transport relay 会选择它，两个 station 均已实现，relay 服务端已部署，且 TestCLIDrivesARelayStation 会在 CI 中驱动完整循环
文件共享、bundle、对象存储	bash station 中均已实现这三种 station 传输（station/bash/transports/）；init 可选择 share、bundle 和 objstore。PowerShell station 支持 share，但不支持 bundle 或 objstore
Azure Blob	端到端可用，通过 station 载荷中的 drop.sh 而非 CLI 实现。这是 Azure Function 主机所用的方式
PowerShell station	已发布。station/powershell/ 约有 2,600 行代码，支持 git、share 和 relay，CI 会在 Windows 运行器上运行它。设计：A8
文档站点	docs.heliograph.io：CLI、传输方式，以及另一端的 station、运行器、步骤、主机、Azure、Windows、容器、服务、密钥、安全和捕获契约

如果传输方式只在连接缺口的一端可用，它就不算传输方式，因此本表会列出两端的情况。Git 和 relay 均由 CLI 端到端驱动，并在 CI 中得到验证；其他传输方式还需要完成哪些工作，以及先后顺序，请参见路线图。

这张表曾经有一段时间是错的，原因值得记录下来。 截至 2026 年 9 月 21 日，表中仍称 relay 是“半成品传输方式”，称“没有 CLI 命令可以选择它”，称 station 不支持 share、bundle 或对象存储传输，还称 PowerShell station“仍在规划中”。这四条说法都与本仓库中的代码不符。文档站点没有发生偏差，因为 transports_doc_test.go 将其与 initTransports 和 station 传输目录绑定在一起——但没有任何东西绑定这个文件。现在已通过 TestReadmeTransportClaimsMatchTheCode 将其绑定。

影响也不止于此：skills.dbhq.uk/heliograph 有意采用了更保守的说法，因为本 README 与文档站点相矛盾，并记录称，在“heliograph 确定哪个说法属实”之前，内容会继续保持保守。现在这个问题已得到解决。

relay

两端都通过普通 HTTPS 向外拨号，因此企业环境无需 git 主机、存储帐户或 VNet。可托管，也可使用同一二进制自行托管。

目前还无法端到端使用。 station 端已完成，服务端也已部署；但没有 CLI 命令可以选择它，因此缺失的是近端这一半。

relay 无法读取你的日志，也无法让 station 运行任何东西。 后一点才是关键：如果 relay 能伪造请求，就能在所有企业环境中同时执行代码。内容使用 relay 永远不会持有的密钥进行端到端加密，并且每条消息都经过签名。没有定制方案——使用的是 age 原语和 Ed25519。完整说明，包括 DBHQ 能够和不能够如实声称的内容，见 docs/specs/2026-09-06-relay-encryption-design.md。 relay 服务端位于独立仓库 heliograph-io/heliograph-relay 中，因为它不持有任何密钥，而且必须公开、明确地证明自己无法读取所传输的任何内容。

光束是什么，以及它的代价

光束目前仍处于设计阶段，尚未构建；以下描述的是它上线后的功能。

三种形态中有两种不会保持连接开启。信标会将消息留在双方都能访问的地方，而且永远不需要自身可被访问——无需入站端口、端点或隧道。闪焰会敲门、等待，然后离开；它不会在收到答复后继续保持线路开启。两者结合，即使整个环境完全不允许线路保持开启，也仍能完成全部工作。

光束确实会保持线路开启，实现实时双向通信，而这就是一条隧道。蓝队会将保持开启的通道视为隧道，因为它确实就是隧道。因此，它在两端都明确启用前始终处于关闭状态，并且会经过密封和签名；除非启动时已允许建立隧道，否则站点会拒绝建立隧道。如果某个环境禁止反向连接，那么信标和闪焰就是解决方案，除了延迟之外不会损失任何功能。

每条命令仍会在远端执行，因为有人选择允许它执行，并且拥有合法访问权限。

布局

cmd/heliograph/         the control CLI, and `heliograph mcp`
cmd/heliograph-seal/    key generation for the relay transport
cmd/heliograph-site/    the static site generator
internal/transport/     git | relay | share | bundle | objstore
internal/bootstrap/     `heliograph bootstrap`: plants the embedded station
internal/wire/          the request and status documents that cross the gap
internal/seal/          sign-then-encrypt, for the relay
internal/logfile/       gap analysis
internal/mcp/           JSON-RPC over stdio, no dependencies
internal/estate/        which transport a name refers to
internal/plant/         what to send the operator
station/bash/           the bash station: everything that runs on the far side
station/bootstrap.sh    the no-CLI bootstrap: clone this repo, run it by hand
skills/heliograph/      the agent skill: drives the CLI, and nothing else
tests/                  the station's own suite, conformance contract included
site/content/           the documentation, one source, three renderings
infra/                  terraform: DNS, Pages, R2 state
docs/specs/             the designs, written before the code

这两部分过去分属两个仓库，划分依据是 Go 与 bash，而不是它们之间的功能界限，导致每位读者都必须弄清楚自己看到的是哪一部分。dbhq-uk/heliograph-skill 于 2026-09-08 合并进来，并保留了完整历史；相关原因详见 docs/specs/2026-09-08-station-and-skill-merge.md。

该仓库已于 2026-09-17 删除，其名称不再使用。合并后，它仍保持公开和归档状态，而归档仓库是只读的，并非无法访问：它仍可克隆，install.sh 仍可运行，其中的站点也完全没有请求环境变量保护（heliograph-cloud#274）。其历史记录已私下保存；本仓库自身的历史记录包含了此次合并。

开发

ROADMAP.md 记录了项目进展：heliograph 的用途、目前已实现的功能，以及近期、接下来和未来的史诗任务。已知缺陷会标记为 type: bug。 CONTRIBUTING.md 介绍如何参与开发，AGENTS.md 则供参与开发的 AI Agent 使用。技能文件位于 skills/heliograph/SKILL.md； docs/dev-setup.md 介绍如何从源代码搭建环境并进行实时修改。

许可证

Apache 2.0（版权所有 © 2026 DBHQ Consulting Ltd），site/content/ 下的文本采用 CC BY 4.0 许可。该项目于 2026-09-17 从 MIT 许可证重新授权；截至 b689f9c（含）的所有提交永久保留在 MIT 许可下。NOTICE 说明了为何选择 Apache 而非 MIT，以及此次变更不会剥夺哪些权利。

中继服务属于单独的仓库，采用单独的许可证： heliograph-relay 采用 FSL-1.1-ALv2，即公平源代码许可证，并会在每次发布两年后转为 Apache 2.0。任何形态都不会受到限制：信标、闪焰和光束都可通过你自行托管的中继服务运行。

完整声明，包括专业服务授权及其明确限制： https://docs.heliograph.io/licence