内容
Runmark
<a href="https://githubit-zero-labs/runmark/actions/workflows/checkimg alt="Check" src="https.shields.io/github/actions/workflow/status/exabs/runmark/check.yml?branch==check&-square"></aa href="https://github.com-labs/runmark/actions/workflows/ci alt="Node compatibility" src=".shields.io/github/actions/workflow/status-labs/runmark/ci.yml?branchlabel=node%20compatibility&stylea>
<a href="https.npmjs.com/package/@exit-zero-labs"><img alt="npm version" src="img.shields.io/npm/v/%40exitabs%2Frunmark?labelstyle=flat-square"></a>
<="LICENSE"><="License"://img.shields.io/github/license/ex-labs/runmark?style=flat-square"></a>
` 是一个基于文件的流运行器，适用于仓库。它在mark/` 目录中记录请求意图，在 `/artifacts/` 目录中记录运行时状态，并通过 CLI 和 MCP 服务器提供相同的执行模型，两者都包含在单个二进制文件中。
当 API 验证应与所测试的代码位于同一位置时，使用 `runmark`，并具有显式的运行、持久化的和暂停/恢复语义，这些语义都可以被人类和 AI 代理检查。
## 安装
根据您所处的仓库方式：
### 全局安装bash
npm install -g @exit/runmark --### / CI 安装
```bash
npm install @exit-zero-labs/runmark
mark --version
```
要更新现安装：
```bash
npm install -exit-zero-labs/runmark@latest
--version
```
- `runmark`适用于人类和脚本的 CLI。
- `cp` — 适用于代理的标准输入 服务器（相同的引擎，相同的隐藏，相同的。
如果您选择了上述的，请在下面的命令中添加 `npx` 前缀（例如，`npx run）。全局安装可以直接使用 `runmark```bash
mkdir demo-api && cd demomark init
解决问题
需求 | `runmark` |
| --- |
| 记录请求定义 | `runmark下的普通文件 |
| 多步骤 API 工作具有顺序、并行和暂停的命名运行 |
| 可检查的执行证据runmark/artifacts/` 目录下持久化会话和工件 |
| 人类的统一模型 | 通过 CLI 和 MCP 相同引擎 |
## 快速入门
即可创建一个新项目，启动捆绑的演示服务器，运行烟雾测试流，然后拆除演示：
```bash
mkdir demo-api && cd demo-api
runmark quickstart
```
当没有现有项目时，`quickstart` 会创建一个新项目。当存在项目时，它会重新运行烟雾测试流。传递 `--no-demo` 如果目标服务已经运行，或者传递 `--port <n>` 将演示从 `4318` 移动到其他端口。
典型的输出是 JSON 格式的完整执行结果作为标准输出，以及标准错误流中的一行人类提示，例如：
```
[runmark] ✓ 在 /-api 目录下创建了项目
[runmark] ✓ 演示服务器在 http://127.0.0.1:4318 运行
[runmark] ✓ 烟雾测试流完成。检查：runmark session show run-<timestamp>-<id>
```
### 分步等价
如果您更喜欢显式地查看每个步骤：
```bash
runmark init
runmark demo start # 在另一个终端
runmark validate
runmark describe --run smoke
runmark run # 选择唯一的运行，当只有一个运行时
```
`runmark init` 为您提供了一个小但真实的起点：一个环境、一个请求、一个运行和带有模式感知 YAML 文件的脚手架。脚手架的 `dev` 环境已经指向://127.0.0.1:4318` 上的捆绑演示服务器，因此您可以在连接达到第一个成功 `init` 输出如下json
{
rootDir": "//demo-api",
"": [
"//demo-api/runmark/.gitkeep",
/demo-api/runmark/artifacts/history/.git "/path/to/runmark/artifacts/skeep",
/to/demo-api/run.yaml",
"/path/runmark/env/dev.env.yaml",
"/path/to/demo-api/runmark/requests/ping.request.yaml",
path/to/demo/runs/sm.yaml",
/to/demo-api/."
],
"nextSteps": [
以下命令运行所有mark quickstart "或者手动：在 `runmark，然后运行 run --run ]
}
/to/demo 代表您的实际绝对。实际的 `还包括运行时` 占位根目录 `.。
```json "rootDir-api",
"": []
```json
{
"session": {
": "run-<timestamp>-<id>",
state": "completed "runId":oke",
"Path": "/artifacts/history/<>/manifest.json"
"diagnostics":```
您应该看到：
- `init`创建的路径和下一步骤。
- ` 返回一个空的 `diagnostics` 数组。
- `run --run smoke`session.state: " 结束，并将工件写入 `runmark/history/<sessionId。
如果流程需要本地机密，请在 `ifacts/secrets.yaml` 下添加它们：
```yaml
devPassword:
apiToken: sk_test_123
```
跟踪引用 `{{secrets.alias}}` 或 `$ENV:NAME`，但机密文字应避免出现在 `runmark/` 中。
会话文件会故意分离携带机密值的部分：
- `runmark/artifacts/sessions/<sessionId>.json` 保留可检查的会话账本，并使用隐藏的占位符。
- `runmark/artifacts/sessions/<sessionId>.secret.json` 保留本地机密伴侣状态，并具有仅限所有者的权限。
- `runmark audit export` 永远不会机密伴侣负载。
- `run` 一起删除文件及其机密。
相同的 JSON也使得暂停、失败状态易于识别```json
{
session": {
Id": "timestamp>-<id "state": "paused",
"nextStepId": "touch-user "pausedReason":变异前检查获取的工件",
Outputs": {
login": { "": "[REDA },
-user": { " "Ada"list-orders "firstOrderId": "ord_1 }
},
"diagnostics": []
```json
{
"session": {
"sessionId": "run-<timestamp>-<id "state": "failed",
"next "fetch-report",
"failureReason断言失败：状态等于预期 200 但得到 503。"
},
diagnostics": [
"code": "_FAILED",
": "runmark/requests/recovery/fetch-report.request.yaml",
"line": 7,
"message": "状态等于：200，得到 503 }
]
```json
{
": {
"sessionId": "run>-<id>",
": "completed",
runId":oke"
},
"diagnostics": []
}
```
使用 [`docs/ins-resume/inspect-and-resume.md) 获取完整的暂停/失败/恢复循环检查和退出代码 3 的安全当运行暂停或失败时，下一步骤显式的：
runmark sessionsessionId>
runmark artifacts list <sessionrunmark resume <session```
## 项目布局
`runmark` 有意将作者计划证据分开：
```text
demo└── runmark ├── config.yaml env/
└── dev.env ├── requests/
│ └── ping.request.yaml
├── runs/
│ └── smoke.run.yaml
└── artifacts/
├── secrets.yaml
├── sessions/
└── history/
```
| 路径 | 用途 |
| --- | --- |
| `runmark/` | Git 跟踪的请求、运行、块、主体模板和 Git 子树 |
| `runmark/artifacts/` | 本地机会话状态、锁的请求工件正常的项目中mark/artifacts/` 应该保持 Git 跟踪的 `.gitkeep` 占位存储库中检查的示例包括一个小的 `/artifacts/` 骨架，以便于检查运行时布局 机密存储
`runmark` 将密排除在可共享的会话账本- 主会话文件存储隐藏的占位符，以便 CLI 输出、MCP 响应和审计导出保持检查。
- 机密伴侣文件位于 `ifacts/sessions/*.secret.json` 下视为备份和敏感本地运行时状态。
- `runmark audit export` 永远不会包含伴侣文件的内容。
- `runmark clean` 一起删除会话账本和伴侣文件。
## 操作属性验证后再执行 在发出 HTTP捕获模式、安全问题检查后再修改。** 使用 ` 和 `explain variables在执行前会发生什么。
- **有目的的暂停 在有意义的检查点停止，检查，然后显式恢复。
- **默认** 机密值在 CLI 输出、M响应、会话和工件读取中- **。** 当定义或 `$ENV偏移时，mark` 阻止不安全的恢复。
所有检查的都位于/`](examples/README 下，并由套件执行。
| 示例 | 最内容 |
| --- | --- [`examples/getting-started`](examples/getting-started 首次项目 一个环境、一个请求、一个运行 |
examples/multi-env-smoke`](examples/multioke) | 环境雾检查 | 一个运行在多个 `dev`staging` 环境 |
| [`pause-resume`](pause-resume) | 了解完整的工作流 | 登录、机密提取、并行读取、暂停、工件检查和恢复 |
| [`examples/api-key-body-file`](examples/api-key-body-file) | 更丰富的现实世界请求连线 | `$ENV` 认证、主体模板、运行输入和步骤输出链接 |
| [`examples/basic-auth-crud`](examples/basic-auth-crud) | 本地机密认证和可 基本认证、JSON 主体和顺序 CRUD |
| [`-checkout`](examples/ecommerce-checkout 产品样式业务 | 购物车账、提取后续验证 |
examples/incident-runexamples/incident-runbook) | 操作手册 | 并行诊断、暂停和前安全恢复 |
| [`examples/fcovery`](examples/failure-recovery)故障处理 |、历史记录和恢复后重试是具有自动化覆盖率的维护参考项目。
## CI 和团队采用
`runmark` 作为仓库本地验证良好：其作为开发依赖项安装，并通过 `npx runmark` / `pnpm exec runmark` 调用
- 在 `runmark/` 下保留跟踪，并保持/artifacts 忽略
- 上传 `runmark、`runmark/artifacts/history/`、输出或选定的隐藏会话账本 或审查者需要证据时
-不要上传 `runmark/artifacts/secrets.yaml `runmark/sessions/*.secret.json 在运行时 机密或外部管理器中提取本地机密，而不是提交它们这些指南，当项目单个笔记本电脑以外： [`docs-and-team-adoptiondocs/ci-andadoption.md)
docs/external-secret-sdocs/external-secret.md)
-/error-codes.md`](docs/error-codes.md)
## 核心工作流
| 目标 | 命令 |
| --- | --- |
| 脚手架 + 演示 + 一键运行 | `quickstart` |
| 脚手架项目 | `init` |
| 脚手架单个定义 | `new <request\|env\|eval>` |
| 在 $EDITOR 中打开定义 | `edit <id>` |
| 验证（CI 友好别名） | `lint` |
| 发现请求、运行、环境或会话 | `list` |
| 验证后再执行 | `validate` |
| 检查请求或运行形状 | `describe` |
| 检查解析的值和出处 | ` |
| 执行请求或运行 | ` |
| 检查暂停或失败的会话 |` |
的请求/响应证据 | `artifacts list` / `artifacts read` |
| 继续暂停或失败的工作 `resume` |
| 列出或运行数据集驱动的评估 | list` / `eval run` |
## MCP 服务器
`runmark mcp` 启动一个标准输入输出 MCP 服务器，公开与 CLI引擎 — 相同的隐藏、相同的工件、相同的运行时模型。将任何 MCP 客户端（ Desktop、Claude Code、Cursor 等 `runmark` 二进制文件，并将cp` 作为第一个
```json "mcpServers": {
" {
"command": "runmark",
"args": ["mcp"]
}
}
}
```
如果您不想要全局安装，请npx`:
```json
{
"Servers": {
"runmark": {
"command": "npx",
"args":y", "@exit-zero-labs/runmarkmcp"]
}
}
}
MCP 服务器通常在全局范围内配置，因此启动 `runmark m **不会** 选择项目。每个 MCP 工具必须包含 `projectRoot` 指向mark/config.yaml存储库目录注册的工具：
- `list `validate_project`
- `describe_request `describe_run`
- `run_definition` — 接受 `requestId` 或 `runId` 中的一个
- `resume_session`
_session_state `list_artifactsread_ `get`
- `cancel_session`
- `explain- `export_audit_summary`
- `` —、状态过滤器和保留标志
故障排除
状 | 可能原因 | 修复方法 |
| --- | --- | --- |
| `mark/config.yaml found...` | 您在项目根目录之外。 | 运行 `runmark init`，移动到项目目录，或传递 `--project-root`。 |
| `validate` 报告模式或 YAML 错误 | 跟踪文件形状或语法错误。 | 修复报告的文件并重新运行。 |
| 请求无法连接 |Url` 错误或运行。 |mark demo start` 以获取捆本地 API，或更新 `runmark/env/*. 以指向您的服务并重试。 |
| 机密查找失败 | `runmark/artifacts` 丢失或不完整。 |更新本地机密别名。 |
resume` 以代码 `3` 退出踪定义已更改或另一个进程仍持有。 | 在锁清除后重试；如果定义偏移，请启动新的运行而不是强制恢复。 |
信任和数据- `runmark` 将跟踪意图保存在 `runmark/` 中，将本地运行时证据保存在mark/artifacts。
- 新手架默认为Body: metadata以便初始运行保持更小安全。
- 主会话文件保持可隐藏；机密伴侣文件保secret.json，并具有仅者的权限。
- `runmark 将保留策略应用于终端会话，`runmark audit export`隐藏的交。
- `runmark` 不产品遥测数据；网络流量来自请求和身份验证流。
有关模型，请参阅：
- [`-and-privacy.md`](docs/securityprivacy.md)
- [`docs/filesystem-safety.md`](docs/filesystem-safety.md [`docs/unsafe-resume.md/unsafe-res)
## 支持runmark` 打算通过捐。Gitors 是主要循环 Collective 是次，用于一次性支持可见性：
- <https://github.com/exit-zero-labs>
- <https://opencollective.com/exit-zero-labs>
参阅 [`docs/supportdocs/support.md) 了解捐款资金的用途以及两种支持路径的区别 了解更多
- [`docs/product.md`](docs/product.md) 获取产品- [`docs/inspect-and-resumedocs/inspect-and-resume.md) 获取规范的暂停/失败/恢复工作流
- [`docs/examples.md`](docs/examples.md) 获取示例目录和推荐起始顺序
- [`docs/ci-and-team-adoption.md`](docs/ci-and-team-adoption.md) 获取 GitHub Actions、PR 审查和多模块模式
- [`docs/security-and-privacy.md`](docs/security-and-privacy.md) 获取存储、隐藏、保留和遥测说明
- [`docs/yaml-reference.md`](docs/yaml-reference.md) 获取跟踪 YAML 字段指南
- [`docs/cli-reference.md`](docs/cli-reference.md) 获取子和输出约定docs/outputs-and-runtime-files.md`](s-and-runtime 获取 CLI/M 形状和运行时文件布局
- [`-codes.md`](docs/error-codes.md退出代码和常见诊断系列
- [`-guide.md`](docs/agent-guide.md) MCP
