runx

runx

Agent 技能的受治理运行时

快速开始 · 工作流 · 编写技能 · 执行凭证 · 基于 Runx 构建

---

A skill is a URL.
A graph is what unfolds.
Authority narrows. It does not pass through.
Every act produces a receipt.

技能是以便携式 SKILL.md 发布的专业知识：一份人类可以理解、Agent 可以据此行动的操作手册。它包含方法、需要查找的证据、需要做出的决策，以及工作所需的工具。技能可以调用其他技能，并将其结果传递下去，完成更大型的任务。

Runx 让这些工作可以执行。研究简报可以转化为外联草稿。产品发布可以串联发布工作、文档和客户更新。搜索和产品分析可以为网站的下一次改动提供参考。在这些交接过程中，Runx 会根据明确的权限准入调用，在工具边界提供凭据，监督执行，并封存可验证的记录。

Agent 提供判断。Runx 掌管执行边界。 使用 CLI、MCP 或语言客户端，配合你已经在使用的 Agent 或编排框架。执行、状态和凭证签名均在本地运行；托管注册表、凭据托管和公证服务均为可选。运行时采用 Rust 编写，并以 Apache-2.0 许可。

快速开始

使用你的 Agent

将 Runx 操作手册交给你的 Agent：

Set up Runx: https://runx.ai/SKILL.md

然后给它一项范围明确的工作。例如：

Use Runx to investigate where our organic visitors stop becoming active users.
Use Search Console, GA4, and our saved PostHog activation funnel. Compare the
last two complete 28-day periods. Bring back the evidence, three priorities,
and a proposed content or product change. Stop before publishing or sending.

Agent 可以发现技能、检查其输入、绑定你选择的工具，并处理运行中尚未完成的轮次。缺少的账户、证据或决策都会作为明确请求保留。Claude Code 和 Codex 也可以使用原生技能导出。

在终端中使用

通过 npm 安装原生 CLI：

npm install --global @runxhq/cli

或在 macOS 或 Linux 上使用独立安装程序：

curl -fsSL https://runx.ai/install | sh

运行最精简的完整示例。此示例需要 Git 和 Node.js 20 或更高版本； 不需要 Runx 账户、模型或提供商密钥。

git clone --depth 1 https://github.com/runxhq/runx.git
cd runx

runx skill ./examples/hello-world --run-id first-run \
  -i message="Hello, Runx." --json

结果中的选定字段：

{
  "status": "sealed",
  "outcome": "completed",
  "run_id": "first-run",
  "result": { "message": "Hello, Runx." },
  "receipt_id": "sha256:…"
}

读取运行记录，然后验证命令返回的完整回执 ID：

runx history first-run --json
runx verify <receipt-id> --json

此示例执行一个已纳入版本控制的 Node.js 命令。它使用了更大型技能所用的同一套准入、执行和签名流程。npm 包分发原生运行时；此处的示例脚本需要 Node.js。 完整演练请参阅入门指南，平台安装包请参阅安装选项。

技能可以来自本地目录、URL 或注册表。已发布的技能会保留其 publisher/name 身份；已验证发布者的技能也可以使用简短的根名称。解析不带限定符的名称时，本地包优先。 若要复现他人的运行，请使用确切的版本和摘要。

技能协同工作

技能会将有用的成果传递下去：匹配的事实、有来源支持的简报、经过验证的草稿、待批准的确切操作，或上次运行的回执。 下一个技能可以直接使用这些结果。

这些组合可以交给 Agent：Runx 技能与您的代码库、提供商技能和关联账户协同工作。您的 Agent 或项目自有的图谱负责交接，将实际输出传入下一个技能的输入中。

业务运营：让下一次发布触达客户

We're launching team workspaces in Northstar. Use Runx to prepare the release,
choose the customer audience, update the setup guide, draft the announcement,
and coordinate the rollout with the team. Establish the activation baseline
from workspace creation to the first teammate invited so we can measure adoption.
Bring back the launch kit, blockers, and receipts. Ask before sending,
publishing, or deploying.

operations-review 会检查发布状态并提出下一步发布操作建议。lead-enrichment 会整理提供的客户事实，以协助选择受众；实际受众和联系政策由操作人员提供。

release#prepare 会检查项目的发布配置，并生成与版本绑定的简报。完整的 release 运行器通过项目命令负责审批、发布和验证。 content-package 会结合发布事实和产品文档，利用 research 和 ghostwrite 准备设置指南和公告，然后将其打包以供发布。

message-send#plan 会绑定主体、受众、已接受的内容和审批要求。调用该技能的 Agent 可以将此计划交给 Nitrosend 或其他电子邮件提供商的技能，以完成审核、审批和发送工作流。如需发布团队更新，message-send#send 会自行负责 Slack 帖子及独立回读。 product-analytics 会根据提供的报告建立从工作区到邀请的基准，并按照相同的衡量定义比较后续结果。

返回内容： 一套发布工具包，包含发布说明、设置指南、客户公告、团队更新和激活基准，以及上线和后续跟踪采用情况所需的阻碍事项、决策和回执。

外联：事实 → 匹配度 → 有价值的首次联系

lead-enrichment 会整理你提供的、与已明确匹配对象相关的事实。 lead-qualify 会根据你的 ICP 核查这些事实，并将商业匹配度与联系资格分开处理。 cold-outreach 会利用这些背景信息、可靠的研究，以及确切收件人的抑制状态，准备一封邮件。

草稿可以采用 brand-voice 和 taste-profile，但不会让二者编造产品声明。在 cold-outreach 中，ghostwrite#admit 会在起草前验证证据和写作背景；ghostwrite#verify 会在起草后核查结果与来源的对应关系。缺少联系资格、存在抑制状态或包含无依据的声明，都会导致暂停。

**返回内容：**确切的发件人、收件人、主题、正文，以及供审核的来源对应关系。message-send#plan 可以将获准的草稿交接给提供商。选定的邮件技能——Nitrosend 或其他提供商——会检查自身的受众和发件人要求，针对确切的发送内容获取审批，并报告提供商的结果。请选择允许进行预期联系的提供商和发送模式；仅有商业匹配度并不代表获准联系。

信息补全使用你提供的证据；提供商查询属于单独的连接器操作。调用应用会保留结果以便后续跟进。收到回复、选择退订或联系资格发生变化，都会影响下一次运行可执行的操作。

试着让你的 Agent 执行：“利用提供的潜在客户研究、我们的 ICP、品牌调性和联系政策决定，准备一封有价值的首次联系邮件。展示邮件所依据的事实，并暂停处理联系资格尚未明确的收件人。”

自然增长：将发现与激活连接起来

每种来源回答的问题都不相同。Search Console 展示人们如何找到你。GA4 根据该媒体资源的衡量模型展示获客和行为。产品分析展示注册后，特定旅程中哪些环节会流失用户或账户。

google-search-console 和 google-analytics 返回经过规范化的证据，并附带来源摘要和衡量注意事项。 PostHog connector 从你选择的 Cloud 项目和区域读取已保存的洞察；它会保留查询定义和缓存结果的新鲜度。 product-analytics 使用提供的汇总报告，计算漏斗和留存率，并检查比较是否有意义。

organic-growth 将搜索、分析、站点和市场证据汇总为优先事项和衡量计划。产品发现可以连同其来源引用和摘要一并纳入这些证据。例如，某个页面的点击量增加，但访客未能激活，这可能意味着需要更明确的承诺、更好的引导流程，或修复埋点。

**返回内容：**观察结果、假设、排序后的行动、来源绑定和衡量计划。内容工作可以通过 content-package 继续；代码和埋点工作可以在所属仓库中通过 code-plan 和 github-issue-to-pr 继续。下一次分析会继续使用可比的时间窗口和定义。缺失或过时的报告仍属于衡量缺口。

运行本地工作流验证

在此检出目录中运行：

# Research → draft → channel package → publication handoff
runx harness skills/content-package/fixtures/composes-in-graph.yaml

# A specific outreach draft with supplied evidence and writing context
runx harness skills/cold-outreach/fixtures/prepares-approved-context-email.yaml

# Search + analytics + site evidence → growth priorities
runx harness skills/organic-growth/fixtures/composes-in-graph.yaml

# Defined product funnel → rates and source-bound recommendations
runx harness skills/product-analytics/fixtures/composes-in-graph.yaml

# Exact Slack post → approval → provider response → independent readback
runx harness skills/message-send/fixtures/post-default-notifies-and-verifies.yaml

这些是由 fixture 提供支持的执行，不会读取或发送任何实时账户数据。实时工作会使用你的提供方绑定和实际证据。浏览 技能目录以查看更多工作流，或查看 演示库，了解本地执行、状态和循环示例。

技能包含判断能力

SKILL.md 是该能力的操作手册。它会说明何时使用该技能、哪些证据至关重要、如何作出决策、何时停止，以及如何定义完成。它本身易于阅读且实用。

---
name: hello-world
description: Echo a message through a checked-in command.
---

# Hello World

Print the supplied message so the caller can inspect the local execution
and its signed receipt.

当工作需要可执行步骤、类型化输入和输出、权限、产物或测试框架用例时，该包还会包含 run.yaml：

skill: hello-world
version: "0.1.1"

runners:
  default:
    default: true
    inputs:
      message:
        type: string
        required: true
    steps:
      - id: default
        tool: { command: node, args: [run.mjs] }
        inputs:
          message: $input.message
        outputs:
          message: string

这是 examples/hello-world 的执行结构。该示例包还包含已签入的命令和测试框架用例。

部分	职责
SKILL.md 和参考资料	专业知识、流程、判断、恢复和完成标准。
run.yaml	可执行运行器、类型化契约、声明的能力、权限和测试框架用例。
领域模块	技能专属的确定性计算。
Runx	提供方传输、文件系统和进程访问、凭据交付、执行状态和回执。

Runx 通过摘要将手册与执行闭包绑定起来。执行任务的 Agent 会收到所调用技能的完整手册；相邻技能只会提供有界摘要，直到被调用。图还可以在 Agent 步骤中通过显式的 context_skills 提供技能，例如写作评分标准。上下文可辅助判断；权限则由准入机制决定。

图让行动可以组合

运行器可以组合五种步骤：

步骤	用途
agent	根据技能手册和明确的调用限额进行判断。
tool	原生能力、确定性计算或已声明的进程命令。
operation	调用外部提供方的类型化连接器。
ask	运行继续前需要回答的问题或作出的决定。
skill	另一个技能的运行器，具有明确的输入和输出。

一个小型图可以清楚展示数据流：

name: hello-graph
steps:
  - id: first
    skill: ../hello-world
    inputs:
      message: Hello from the first skill.
  - id: second
    skill: ../hello-world
    inputs:
      message: $steps.first.message

第二个技能会使用第一个技能的类型化输出。图回执会关联它们的回执。相同的机制可让 content-package 将研究资料包传递给 ghostwrite，再将经过验证的草稿传递给其打包和交接运行器。请将其实际图与最小示例放在一起查看。

对于需要判断的工作，请使用 Agent 回合。当阶段、分支、守卫条件或审批边界必须成为执行契约的一部分时，请使用图。必需的副作用应放在明确的执行步骤中，以便 Runx 记录尝试和结果。Agent 的完成文本不能替代提供方操作。

图和 Agent 回合都可以调用技能。主机可以将现有资料包工件传入后续调用；Runx 会检查其内容摘要和输入架构。这样，有用的结果就能成为后续工作的输入，同时不必将其来源信息压平成一段文字。

组合技能 · 执行配置文件参考

工作可以超出 Agent 回合的时限

默认情况下，Agent 步骤会将工作交还给调用它的 Agent。Runx 会返回手册、类型化请求和允许的调用。你的主机可以通过 MCP 处理该回合，提供结果，然后继续同一次运行。可选的 --managed-agent 模式会将这些回合委托给已配置的模型提供方。

# Inspect a running, paused, or completed run
runx history <run-id> --json

# Serve the paused run's agent turns over MCP
runx mcp --run <run-id>

# Continue with answers to the run's exact pending requests
runx resume <run-id> answers.json --json

运行会记录待处理请求和已完成的调用。相互独立的读取调用可以并发运行；副作用则会在运行期间串行执行。重试会沿用该调用的标识；不确定的外部结果会明确保留，以便协调处理。恢复运行时会检查软件包和执行闭包，确保技能发生变化后不会静默地继续旧运行。

Agent 答案和人工审批使用不同的字段。每项决定都会绑定到其所回应请求的摘要。主机负责获取人工决定；在审批字段中填入 JSON 值只是主机的声明，并不能证明某人的身份。

对于周期性操作，外层主机负责调度和停止策略。每次迭代都可以读取之前的回执和持久状态、提交有界运行，并保留结果供下一次迭代使用。请参阅循环示例和续接契约。

连接工具，而不向技能提供秘密

技能声明所需的连接器操作。连接器声明类型化请求、作用域、凭据要求和读取回传行为。由你选择账户和绑定方式：本地凭据、受支持的现有会话，或可选的托管连接。

例如，安装网页搜索并将其绑定到你的 Exa 账户：

runx registry install runx/web-search
runx connector use exa
runx skill runx/web-search -i query="Agent skill interoperability" --json

如果已设置连接器声明的凭据变量，connector use 会绑定到该变量；否则会提示你输入密钥。对于受支持的会话，例如现有的 gh 登录：

runx connector use github --session --scope repo.read

内核仅在获准操作的传输边界处提供凭据。技能指定操作并提供类型化输入。秘密材料不会进入技能指令、模型上下文或执行回执。

一个技能可以使用不同的兼容提供方。一个连接器绑定可以服务于多个技能。使用托管凭据保管时，调用方操作员及其状态仍保留在本地，除非你明确选择托管服务。

连接器名称用于标识能力提供方：github、posthog、google/analytics 或 google/search-console。如果技能绑定自身插件之外的连接器，就会固定其清单摘要；执行闭包则绑定实际会用到的操作。

凭据设置 · 连接器目录 · 连接器清单

权限随工作而定

每次受治理的执行都遵循相同的边界：

Admit → Resolve grant → Deliver credentials → Execute → Seal

权限会在调用执行的位置进行检查。子调用始终受限于父调用授予的权限；仅仅指定另一个技能，或在提示词中描述某个操作，都不会产生权限。需要审批的操作会暂停，并提供要由宿主呈交给用户的准确请求。

各执行通道有明确的边界：

• 确定性模块执行 JSON 到 JSON 的领域计算，不具备对文件系统、网络、进程、环境、时钟或随机数的隐式访问权限。
• 原生能力负责可复用的运行时机制及其准入检查，包括文件访问、进程、制品和数据操作。
• 连接器操作在类型化权限和效果契约下执行已声明的 HTTP、MCP 或 Connect 调用。
• 进程工具是受信任的本地可执行文件。Runx 控制其 argv、工作目录、提供的环境、凭据和监督方式。它们使用宿主的 OS 权限执行；这并非可移植的 OS 隔离。

这些保障适用于通过 Runx 执行的工作。周边的 Agent 或应用负责其其他工具、对人工决策的认证以及宿主隔离。

权限与安全证明 · 安全策略

回执证明了什么

Agent 离开后，回执能回答那些重要的问题：

问题	证据
运行了什么？	技能标识、来源和执行摘要，以及运行器元数据。
谁或什么准许了它？	操作者引用、授权引用和执行条款。
允许了什么？	作用域、已解析的授权和审批决定。
发生了什么？	行为、输出引用、执行结果和收尾信息。
工作是如何关联的？	链接的子回执和工件来源信息。
之后还能检查吗？	内容寻址 ID、规范摘要和签名。

Runx 使用 Ed25519 对回执签名。首次使用时，未配置的 Runx 主目录会创建自己的本地签名密钥。runx history 用于检查记录；runx verify 用于验证其签名和关联的回执树。

有效签名可证明数据相对于可信签署者的完整性。还要查看回执的结果：已封存的拒绝或失败运行，仍然是已封存的。本地内容草稿可证明准备工作；服务提供商的回读可确认外部结果。来自其他主目录或托管发行方的回执需要该发行方的可信公钥。

回执包含引用、决定、哈希和有界观察结果。原始凭据和未经检查的服务提供商私有数据正文不应出现在证明中。结果载荷与签名回执各有用途：结果供下一个调用方使用；回执记录工作是如何获准的，以及执行确认了什么。

阅读回执架构，查看已封存的样例，或使用独立验证器在执行运行时之外检查证明。

编写、测试和发布

将技能保留在项目中、改造现有软件包，或发布技能供他人组合使用。使用以下命令开始编写：

runx new launch-review \
  --objective "Review a release and prepare its customer announcement"

这会进入 skill-build 工作流。你的 Agent 会处理编写过程中的各轮交互；验证通过后，系统会写入软件包。如果没有托管 Agent，该命令会返回待处理工作和恢复说明。

完成的软件包应包含针对成功路径、拒绝情形以及与其他技能组合使用的测试套件用例。测试套件会重放声明的输入以及 Agent／服务提供商的响应，以便在本地检查这些约定。

runx harness ./skills/launch-review
runx login --for publish
runx registry publish ./skills/launch-review

托管发布流程会重建提交的软件包、重新运行其测试套件，并存储不可变的软件包摘要。本地测试套件结果只能证明其覆盖的用例；实时集成声明还需要实际服务提供商路径的证据。

编写参考 · 技能质量标准 · 发布

基于 Runx 构建

CLI、MCP 服务和语言客户端使用相同的 Rust 执行路径。 应用可以启动技能，将其开放回合提供给模型，路由人工决策， 恢复运行，并检查其回执。

界面	入口点
CLI	runx skill <skill-ref> [runner] -i key=value --json — 参考文档。
MCP	使用 runx mcp <skill-ref> 暴露技能；使用 runx mcp --run <run-id> 处理现有运行。
TypeScript / Node.js	@runxhq/client，支持显式配置工作区和环境。
Python	Python SDK。
Rust	runx-sdk。
契约	架构 和公开规范。

MCP 会将一个回合允许的调用作为类型化工具公开。宿主负责模型 对话；Runx 会接纳并记录这些调用。你可以集成单个技能，也可以围绕 长期运行构建产品，无需引入另一套执行实现。

运行时内部：各层的职责

层	负责方
可移植线路契约	runx-contracts
纯策略、权限和状态转换	runx-core
包解析和经过验证的包表示	runx-parser
规范回执、哈希、签名和验证	runx-receipts
执行、能力、进程、适配器和副作用	runx-runtime
参数解析和呈现	runx-cli
语言客户端和扩展协议	packages/
操作人员知识和领域计算	skills/ 和产品自有包

系统架构 定义了这些 职责边界。SDK、导出的 Agent 技能、架构和目录视图 使用相同的契约。

参与贡献

Runx 正在积极开发中。可以从具体的工作流、可复现的 执行问题、连接器契约，或包含实用测试用例的技能着手。 贡献者指南介绍了设置、针对性检查和 签署要求。

从此代码检出版本构建原生 CLI：

cargo build --manifest-path crates/Cargo.toml -p runx-cli
crates/target/debug/runx harness examples/hello-world

参考文档 · 演示 · 版本发布 · 提交问题

---

_{使用 Rust 构建 · Apache-2.0 · runx.ai}