内容
# 运行见证 RunWitness
<p>
<a href="https://github.com/karurikwao/runwitness/actions/workflows/verify.yml"><img alt="CI" src="https://github.com/karurikwao/runwitness/actions/workflows/verify.yml/badge.svg"></a>
<a href="package.json"><img alt="版本 v0.1.0" src="https://img.shields.io/badge/version-v0.1.0-blue"></a>
<a href="LICENSE"><img alt="许可证 Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
<a href="package.json"><img alt="Node 22.19+" src="https://img.shields.io/badge/node-22.19%2B-35c2a1?logo=node.js"></a>
</p>
<p>
<a href="https://runwitness.pages.dev">在线演示</a> |
<a href="https://runwitness.pages.dev/launch">启动页面</a> |
<a href="https://github.com/karurikwao/runwitness">GitHub 仓库</a> |
<a href="https://github.com/karurikwao/runwitness/wiki">维基</a>
</p>
<p align="center">
<a href="https://runwitness.pages.dev/launch/">
<img src="https://raw.githubusercontent.com/karurikwao/runwitness/master/site/assets/runwitness-receipt-flow.gif" alt="Animated RunWitness receipt flow showing task intake, policy review, approval, command capture, and receipt export." width="760">
</a>
</p>
自主代理与凭证。
RunWitness 是一个本地优先的控制平面，用于代理工作。它允许代理运行任务，记录 RunWitness 可以观察到的重要操作，跟踪文件更改和命令结果，并导出人类可以稍后检查的凭证包。
第一个里程碑故意很小：
1. 运行一个任务。
2. 观察命令、账本事件、文件更改、推断的测试结果和凭证导出。
3. 阻止或预先批准高风险步骤。
4. 生成凭证。
RunWitness 并不试图取代 OpenClaw、Hermes、Codex、Claude Code、本地代理或 MCP 工具。它是围绕它们的见证层：策略、事件历史、凭证和验证。
## Alpha 状态
RunWitness 已准备好进行 GitHub alpha 启动。今天，它对本地见证命令、策略决策、凭证、沙盒预检、选择加入 Docker/Podman 沙盒执行、回滚证据、适配器事件捕获、哈希操作员身份验证和实时本地驾驶舱等功能非常有用。它不是一个托管的 SaaS 控制平面、通用秘密边界或完整的嵌套代理跟踪器。
启动和信任文档：
- [安全策略](SECURITY.md)
- [贡献指南](CONTRIBUTING.md)
- [行为准则](CODE_OF_CONDUCT.md)
- [启动检查清单](docs/LAUNCH_CHECKLIST.md)
- [Alpha 版本说明](docs/ALPHA_RELEASE_NOTES.md)
- [集成](docs/INTEGRATIONS.md)
- [启动项目板](docs/GITHUB_PROJECT.md)
- [讨论启动器](docs/discussions/README.md)
- [维基发布指南](docs/WIKI_PUBLISHING.md)
- [GitHub 远程设置](docs/GITHUB_REMOTE_SETUP.md)
- [启动准备差距](docs/LAUNCH_READINESS_GAPS.md)
- [示例](examples/README.md)
## 集成状态
RunWitness 集成是 RunWitness 仓库方面的官方集成。这意味着该仓库维护仓库官方的 OpenClaw 插件包、Hermes 技能包示例和 Codex、Claude 兼容主机及其他 MCP 能力主机的 MCP 服务器。
在上游项目接受、列出或从其官方渠道发布集成之前，请勿将其称为上游官方集成。
稍后，要使集成成为上游官方集成，请通过每个生态系统提交或列出：
- OpenClaw 插件市场/ClawHub（如果适用）
- Hermes 技能/目录路由（如果可用）
- Codex 或 Claude MCP 文档/示例，仅当 OpenAI 或 Anthropic 接受它们。
## 为什么它存在
自主代理非常有用，因为它们可以触及真实的系统：文件、shell、浏览器、API、聊天工具和部署。这也是它们具有风险的原因。当任务触及源代码、秘密、CI 或生产时，置信的最终消息是不够的。
RunWitness 使被见证的工作可检查：
- 代理运行了什么？
- 哪些文件发生了变化？
- 哪些高风险操作需要批准？
- 测试是否通过？
- 凭证在哪里？
- 是否有足够的证据来审计或恢复运行？
## 核心概念
- **运行**：具有唯一 ID、工作区、代理名称、状态、时间线和最终凭证的用户请求任务。
- **步骤**：运行内的离散观察操作，例如命令、文件快照、批准或测试结果。
- **凭证**：运行的最终 JSON 和 Markdown 证明包。
- **策略**：将操作分类为允许、拒绝或需要批准的本地规则。
- **技能**：具有声明的权限、规范摘要和可选签名验证的可重用能力。
- **批准**：高风险操作的记录的人类或非交互式决策。
- **适配器**：RunWitness 和正在执行工作的实体之间的桥梁，从本地 shell 命令、命令包装器和本地 HTTP/SSE 基础架构开始，为 OpenClaw 和 Hermes 以及浏览器自动化、MCP、CI 和部署系统提供通用包装器。
## 快速入门
从锁定文件安装依赖项：
```bash
npm ci
```
运行一个被见证的命令：
```bash
npm run rw -- run --task "列出文件" -- node -e "console.log('hello from RunWitness')"
```
检查运行前 YAML 策略：
```bash
npm run rw -- policy check --policy examples/quickstart-policy.yml -- node -e "console.log('ok')"
```
使用该策略运行：
```bash
npm run rw -- run --policy examples/quickstart-policy.yml --task "策略检查任务" -- node -e "console.log('ok')"
```
检查其他基础：
```bash
npm run rw -- adapters list
npm run rw -- skill inspect --file examples/quickstart-skill.yml
npm run rw -- serve --data-dir .runwitness --host 127.0.0.1 --port 8787
node packages/mcp-server/dist/src/bin.js --help
```
使用 bearer 身份验证启动操作员 API，而不打印令牌：
```bash
RUNWITNESS_OPERATOR_TOKEN=change-me npm run rw -- serve --auth-token-env RUNWITNESS_OPERATOR_TOKEN --operator-role approver
```
从托管样式的哈希凭证配置启动操作员 API：
```bash
npm run rw -- serve --hosted-auth-config ./hosted-auth.json --data-dir .runwitness
```
启用本地沙盒基元：
```bash
npm run rw -- run --sandbox --write-allow src --protect .env --task "沙盒烟雾测试" -- node -e "console.log('sandboxed cwd')"
```
在执行容器沙盒调用之前进行干运行：
```bash
npm run rw -- sandbox container --image node:22-alpine --dry-run -- node --version
```
连接代理运行时：
```bash
# OpenClaw 插件包
npm --workspace @runwitness/openclaw-plugin run plugin:validate
# Hermes 技能包验证，从仓库根目录
npm run rw -- skill inspect --file examples/hermes-runwitness-skill-pack/runwitness-skill.yml
# 共享 MCP 服务器，仓库构建后
node packages/mcp-server/dist/src/bin.js --workspace . --data-dir .runwitness
```
运行网络预检和回滚证据：
```bash
npm run rw -- run --network-allow example.com --rollback --rollback-mode dry-run --task "防护命令" -- node -e "console.log('https://example.com'); process.exit(1)"
```
通过传递环境变量名称来编辑命令输出中的机密值，而不是机密文字：
```bash
API_TOKEN=secret npm run rw -- run --redact-secret-env API_TOKEN --task "编辑输出" -- node -e "console.log(process.env.API_TOKEN)"
```
在 Windows 上，包含 shell 元字符的命令（例如 `|`, `>`, `<`, 或 `&`）可以在 RunWitness 看到它们之前被 `npm run` 重新解释。对于这些命令，请先构建然后直接调用生成的二进制文件：
```bash
npm run build
node dist/apps/cli/src/bin.js run --task "管道安全命令" -- node -e "console.log('a|b')"
```
导出的工件默认写入 `.runwitness/` 下：
```txt
.runwitness/
runwitness.sqlite
receipts/
rw_...json
rw_...md
```
运行验证：
```bash
npm run verify
```
## 当前阶段
已实现的基石：
- 第 0 阶段：产品合同、威胁模型、概念词汇、MVP 承诺。
- 第 1 阶段：TypeScript 多仓库基础。
- 第 2 阶段：运行账本 MVP，带有 SQLite、仅追加事件、命令跟踪、文件更改跟踪、测试结果跟踪和凭证导出。
- 第 3 阶段基础：受保护的策略/身份验证批准基础，包括分层策略加载、源和有效策略摘要、受保护的策略源路径、凭证策略谱系、持久的待处理批准和可选的带有角色和用户/工作区范围的操作员身份验证令牌。
- 第 4 阶段基础：YAML 技能清单解析、规范摘要、权限风险摘要、Ed25519 签名验证、本地信任注册表检查、安装/隔离评估、运行时权限检查助手，用于 shell、文件系统、网络和命名秘密，以及一个经纪的技能运行助手，在请求的操作被允许之前阻止执行。
- 第 5 阶段基础：硬化的本地沙盒基元，包括写入预检、网络预检、路径安全检查、受保护的路径拒绝列表、过滤的环境和 PATH 构造、隔离的临时工作空间、可审计的过程隔离计划、可选的 Docker/Podman 沙盒执行、回滚基线/包创建和可选的回滚干运行/应用编排，用于失败的命令。
- 第 6 阶段基础：流适配器合同、注册表、本地命令适配器流、OpenClaw/Hermes 命令包装适配器、可选的原生 HTTP/SSE 适配器，用于 OpenClaw 和 Hermes，以及用于浏览器自动化、MCP、CI 和部署的通用包装适配器，它们在可用时规范化结构化事件，同时将未公开的嵌套活动标记为不透明。
- 第 7 阶段基础：静态和实时的操作员驾驶舱渲染器，以及用于运行、时间线、批准、凭证、身份验证的本地操作员 API，用于 Server-Sent Events 快照、批准操作、操作员身份/会话显示和策略谱系视图。
- 第 8 阶段基础：身份和秘密隔离基元，包括工作区角色、显式秘密授予、本地秘密经纪人描述符、加密的本地保险箱存储、命令输出编辑钩子、`--redact-secret-env`、编辑后的访问审计/凭证记录、哈希托管操作员身份验证配置、用户/工作区范围的操作员视图、作用域操作员主体、秘密环境过滤和技能秘密权限声明/检查。
- 集成基础：仓库官方的 OpenClaw 工具插件包、Hermes 技能包示例和用于 MCP 能力主机的共享标准输入/输出 MCP 服务器。
计划中的强化：
- 将强制执行的沙盒执行纳入更多编排路径，并为本地执行添加网络出口强制执行，超出容器运行时模式。
- 扩展用于代理运行时的原生适配器，超出初始的 OpenClaw/Hermes HTTP/SSE 基础架构。
- 将实时驾驶舱打包为更完整的浏览器/桌面应用程序，并保持策略写入禁用，直到完成身份验证验证/审计。
- 在更多运行时路径中集成保险箱/经纪人凭证交接，并添加更强的托管多用户授权视图。
参见 [docs/ROADMAP.md](docs/ROADMAP.md) 和 [docs/NEXT_PHASES.md](docs/NEXT_PHASES.md)，了解当前的强化计划。
## 仓库布局
```txt
apps/
cli/ 命令行界面，用于见证运行。
web/ 静态和实时的操作员驾驶舱渲染器。
desktop/ 计划中的桌面 shell。
packages/
adapters/ 适配器合同、注册表、本地桥、OpenClaw/Hermes 包装器和原生 HTTP/SSE 适配器。
core/ 运行类型、ID、事件账本、编排和操作员 API。
policy/ Shell 风险分类、YAML 策略和批准记录助手。
receipts/ 凭证和证明包导出器。
sandbox/ 快照、预检、过滤环境、临时工作空间、路径安全、回滚、隔离计划/运行器。
skills/ 技能清单、摘要、信任检查、经纪的运行时权限检查。
mcp-server/ RunWitness 工具的共享标准输入/输出 MCP 服务器。
ui/ 共享的操作员驾驶舱渲染助手。
docs/
examples/
integrations/
openclaw-runwitness-plugin/ 原生 OpenClaw 工具插件包。
tests/
```
## 安全姿态
RunWitness 从观察、策略决策、本地批准、沙盒预检基元、作用域本地操作员访问和凭证生成开始。它现在具有策略层次结构、技能信任和经纪人检查、沙盒临时工作空间、可选的容器支持的沙盒执行、回滚工作流、流适配器、实时驾驶舱渲染和用户/秘密隔离基元的基础。
这些基础并不等同于 OS 级别的完美隔离。正常的被见证命令仍然通过主机进程执行，除非操作员选择容器沙盒路径，否则网络出口会预检或委托给容器运行时模式，但 RunWitness 不会普遍阻止它们，嵌套工具活动仅在适配器公开时可见，回滚是可选的，并非在所有故障模式下都保证，并且保险箱/经纪人基元尚未成为通用的运行时凭证边界。
参见 [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)，了解安全模型和当前限制。
