actradeck/actradeck

# ActraDeck **面向编码 agent 的厂商中立控制平面 —— 在一个控制台中实现机密脱敏、跨厂商审计和审批治理。** ActraDeck 运行在您的编码 agent —— Claude Code、Codex 以及未来将出现的 工具 —— 旁边，为您提供一个**统一的平台来监控它们的行为、在机密被存储前将其拦截，并保留跨厂商的审计追踪**。开箱即用的审批功能可将 Claude Code 的操作转发至控制台，对于在托管模式下的 Codex 同样支持（参见 [支持矩阵](#vendor--mode-support)）。它是本地优先的：您机器上的一个 sidecar 负责收集结构化事件，在*任何内容被持久化之前*对机密进行脱敏，并提供一个 由您掌控的 Web 控制台。 ## 实际效果展示 以下是在**带有真实会话的在线环境**中录制的控制台演示 （机密在显示之前，已经在 sidecar 处被屏蔽）：  ▶ **完整演示（约 90 秒）：** [`docs/media/usage.mp4`](./docs/media/usage.mp4) — 实时面板、基于证据的存活检测、带有分类计数的机密脱敏、跨厂商 审计（Claude Code **和** Codex 在同一条追踪记录中）、审批收件箱以及会话 回放。90 秒产品故事操作手册位于 [`docs/demo-90s.md`](./docs/demo-90s.md)；可通过 [`scripts/record-cockpit-cast.mjs`](./scripts/record-cockpit-cast.mjs) 从您自己的 环境中重新生成此录像。 ## 为什么会有这个项目 厂商们已经在构建优秀的单一厂商仪表盘（例如 Claude Code 的 Agent View）。ActraDeck 刻意 **不**追求在单一厂商的“并行会话概览”竞赛中获胜。相反，它专注于模型厂商在架构上不会去构建的部分：**跨竞争 agent 的中立治理。** - **审批治理，而不仅仅是 prompt。** 结构化风险分类器会拦截 高风险命令；一个可选的持久化白名单允许您跳过对_安全_操作的重复审批，同时绝对不会自动放行危险操作。 - **机密在持久化或传输前被脱敏。** 双层脱敏器 （INV-REDACTION）会屏蔽检测到的密钥、token 和 `.env` 内容：sidecar 在它收集的事件_到达磁盘或网络之前_进行脱敏，而后端入口 对每个事件——包括来自外部 adapter 的直接 POST 请求——在存储前应用相同的无条件底线。UI 中会显示各分类的计数。检测 是尽力而为的模式匹配（gitleaks 风格规则 + 自定义 regex）——这是一个强大的安全 网，而非绝对的保证（参见[诚实的局限性](./docs/approval-policy.md#honest-limits)）。 - **审计与回放。** 每个会话都可以在事后回放，用于审查、 事件分析或合规。会话报告可导出为 HTML/Markdown，并带有 嵌入的完整性清单（SHA-256 哈希链）。启用 `ACTRADECK_AUDIT_SIGNING_KEY` （Ed25519）可获得带有签名的、**防篡改**的报告，接收方可以验证报告在导出后未被 更改；如果没有提供密钥，清单仅包含哈希链（内部完整性）。 检测底层存储在导出_之前_的篡改不在当前范围内（已列入 roadmap）。 - **跨厂商。** 统一的事件模型和一条审计追踪记录，涵盖 Claude Code _和_ Codex，并在一个审批收件箱中展示（关于每种模式转发的内容，请参见支持矩阵 — 未来会支持更多 agent）。 - **公开的摄入契约。** 任何工具都可以规范化其自身的事件，并通过 `POST /ingest` 将其发送到同一个控制台和审计追踪中。provider 维度是一个开放的 slug，而 `event_type` 保持为封闭的 enum，以确保状态机保持有意义。请从 [`docs/ingestion-contract.md`](./docs/ingestion-contract.md) 和位于 [`docs/examples/ingest-adapter/`](./docs/examples/ingest-adapter/) 的零依赖 示例 adapter 开始。 ## 当前可用的功能 - 通过通用、规范化的事件模型，监控 **Claude Code**（通过 hooks）和 **Codex**（通过 Attach 模式下的 rollout tailing，或托管模式下的 App Server）。 - **实时会话状态** —— 运行中 / 等待审批 / 等待用户 / 停滞 / 失败 / 已完成 —— 源自分解后的心跳（进程 / 事件 / stdout / 模型流），因此“停滞”状态是基于证据展示的，而非盲目断言。 - 跨会话和 agent 的**审批收件箱**；允许 / 拒绝 / 在本次会话中允许，并为安全操作提供可选的重启持久化白名单。 - **持久化前进行机密脱敏**，UI 中显示各分类的脱敏计数。 - **会话回放**和只追加的本地事件日志。 - 通过公开摄入契约（`provider=`， `source=external`）接入的**外部 adapter**，在持久化前由后端入口进行脱敏。 ## 厂商 / 模式支持 每个 agent 获得的功能取决于您运行它的模式。Attach 模式（快速入门的 默认模式）无需改变您启动 agent 的方式；托管模式（由 ActraDeck 启动 agent）为 Codex 增加了审批转发。 | 功能 | Claude Code (Attach) | Codex (Attach) | Codex (Managed) | | ---------------------------------------------- | :------------------: | :-------------: | :-------------: | | 监控 — 状态、当前操作、diff | ✅ | ✅ | ✅ | | 持久化前脱敏 | ✅ | ✅ | ✅ | | 审计日志 + 回放 | ✅ | ✅ | ✅ | | 审批转发 — 从控制台允许 / 拒绝 | ✅ | ⛔ 仅限监控 | ✅ | 因此，在默认的 Attach 模式下，**监控、脱敏和审计现已支持跨厂商**。**审批转发** 在 Attach 模式下适用于 Claude Code；对于 Codex，则 需要托管模式 —— 使用 `./scripts/actradeck codex ""` 启动它（这是一个对 `agentmon codex -- ""` 的单命令封装），其 App Server 审批会转发到控制台（允许 / 拒绝 / 在本次会话中允许）。在 Attach 模式下，Codex 会被 监控，但其原生的审批仍在其自身的 TUI 中进行。（为简洁起见，省略了在托管模式下全部为 ✅ 的 Claude Code）。 **通过外部 adapter 接入其他 agent。** 任何第三方 CLI 都可以通过将其 事件映射到公开的摄入契约（`provider=`，`source=external`）来进行监控。 首个内置示例是 **opencode**（`docs/examples/opencode-adapter/`）：一个零依赖的 opencode 插件，它将其 hooks 映射到规范化的事件模型中 —— **仅限监控**（状态、 当前操作、命令退出代码、diff、流式传输），脱敏在后端入口的底线处进行，并且它 **不** 转发审批。 | 功能 | opencode (external adapter) | | ---------------------------------------------- | :-------------------------: | | 监控 — 状态、当前操作、diff | ✅ | | 持久化前脱敏（后端底线） | ✅ | | 审计日志 + 回放 | ✅ | | 审批转发 — 从控制台允许 / 拒绝 | ⛔ 仅限监控 | ## 快速入门 只需一行命令 —— 获取源代码并启动控制台（需要 `git`、Node 22.16+ 和 pnpm；**无需 Docker**，数据库是内嵌的）： ``` curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/actradeck/actradeck/main/scripts/install.sh | sh ``` 对于带有来源和校验和验证的发布压缩包，请使用验证失败即关闭的验证路径（需要 GitHub CLI）： ``` curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/actradeck/actradeck/main/scripts/install.sh -o install.sh ACTRADECK_VERIFY=1 ACTRADECK_REF=v0.3.0 sh install.sh ``` 已经克隆了代码，或者更喜欢手动进行（需要 Node 22.16+ 和 pnpm —— **无需 Docker**）： ``` ./scripts/quickstart # .env + embedded DB + all tiers, one command ``` 数据库是一个内嵌的 PostgreSQL (PGlite)，位于 `~/.actradeck/pgdata` —— 无需 Docker，也 无需单独的服务。如果要改用外部的 Postgres（用于生产环境或现有的 DB），请在 `.env` 中设置 `DATABASE_URL`，或者运行 `ACTRADECK_DB_MODE=postgres ./scripts/quickstart` 通过 `docker compose` 启动一个实例。  然后通过 **http://localhost:55400** 打开控制台。在空白面板上，您可以点击 **运行 30 秒安全演示**，在配置任何内容之前，在一个一次性的会话中体验拦截 / 脱敏 / 审计 —— 然后正常运行您的 agent，无需改变它们的启动方式： ``` cd ~/any/project && claude # or: codex → shows up in the cockpit ``` `quickstart` 是幂等的，并在首次 运行时生成一个带有随机本地机密的 `.env` 文件。在 Linux 上，它会最后通过 `systemd --user` 将这四个层级守护进程化。在 macOS 上 （没有 systemd），它会停在最后一步之前，并打印出需要运行的一条命令 — `./scripts/actradeck up` —— 然后它会自动选择 supervisor：当存在 `launchctl` 时选择 **launchd LaunchAgents**，否则选择前台 supervisor。 macOS 的 LaunchAgents 在您的登录会话中运行（登录期间始终运行，并会在下次登录时自动启动）；而一个完全无头、能在注销后存活的 daemon 需要 root 权限的 `LaunchDaemon`，这不在当前范围内。在既没有 systemd 也没有 launchd 的主机上， `up` 会运行一个前台 supervisor（保持终端打开；Ctrl-C 可停止它）。 更倾向于手动操作，或者遇到了问题？请参见 [`docs/getting-started.md`](./docs/getting-started.md)（手动步骤 + 故障排除）。Attach 模式的精度/限制详见 [`docs/attach-mode.md`](./docs/attach-mode.md)。 ### 或者使用 Docker 的一条命令 如果您不想安装 Node/pnpm，**控制台**（后端 + webui + 内嵌 数据库）可以从单个镜像中运行 —— 无需外部数据库，也无需构建步骤： ``` docker run --rm -p 127.0.0.1:55400:55400 ghcr.io/actradeck/actradeck:latest # 然后打开 http://localhost:55400 ``` 该容器**仅包含控制台技术栈**。用于监控您 agent 的 sidecar 会监视*宿主机*的 Claude Code / Codex 进程，因此它无法在容器内运行 — 您需要在宿主机上运行它，并通过 loopback 将其指向容器的摄入端口。 详尽的支持矩阵、确切的 `docker run` 参数、验证镜像的 cosign 签名，以及如何配置宿主机 agent，全部都在 [`docs/docker.md`](./docs/docker.md) 中。 ## 架构 ``` [Claude Code / Codex CLI / Codex App Server] │ hooks / JSON-RPC events ▼ [Local Sidecar] process monitor · stdout/stderr · git diff · secret redactor · approval bridge │ redact-before-emit → append-only local log ▼ [Ingestion API] → [Event Store + State Engine] → [Realtime WS/SSE] → [Web Cockpit] ``` 设计原则：Web UI 永远不会直接连接到本地 CLI。在 agent 的路径上，sidecar 会在任何内容被存储或发送之前对事件进行脱敏；每一个事件 — 包括通过公开摄入契约从外部 adapter 直接发送的 POST 请求 — 在后端入口存储之前，也都会通过一个无条件的脱敏底线。 - 公开摄入契约：[`docs/ingestion-contract.md`](./docs/ingestion-contract.md) - 架构决策记录：[`docs/adr/`](./docs/adr/) - 90 秒演示操作手册：[`docs/demo-90s.md`](./docs/demo-90s.md) ## 安全 持久化前进行机密脱敏是一项核心不变量，而不是一个 feature flag。如果 您认为自己发现了漏洞（脱敏绕过、审批门限 绕过、connector 中的 SSRF 等），请**不要提交公开的 issue** — 有关负责任的披露，请参见 [`SECURITY.md`](./SECURITY.md)。 ## 贡献 ActraDeck 是一个 monorepo（pnpm workspaces）：包含 `apps/sidecar`、`apps/backend`、 `apps/webui` 以及共享的 `packages/`。采用 TypeScript strict 模式、conventional commits 规范， 每个 PR 都有 CI 检查。有关环境设置、本地 验证门限、PR 指南以及需要额外关注的对安全敏感区域的说明，请参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)；我们期望所有参与者都能遵守我们的 [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)。为了获得更深入的背景信息，`docs/adr/` 下的 ADR 描述了系统预期的行为方式。欢迎提交 issue 和 pull request。 ## 许可证 [Apache License 2.0](./LICENSE)。

标签：AI治理, AI编程助手, MITM代理, Web控制台, 审批网关, 密钥脱敏, 本地优先, 测试用例, 自动化攻击, 请求拦截