MakerChecker

# MakerChecker [](https://github.com/sammysltd/makerchecker/actions/workflows/ci.yml) [](https://github.com/sammysltd/makerchecker/releases/latest) [](LICENSING.md) **官网： [makerchecker.ai](https://makerchecker.ai)** **您的AI代理已转移资金。没有人批准。** MakerChecker是一款自我托管的软件，通过**结构强制**和**人工审批**来管理AI代理。结构强制以机器速度运行，没有人类介入：代理仅通过**角色**运行，仅运行其角色**授予**的技能（默认拒绝，精确到版本号），不能超过其限制，并且不能证明其自身工作的批准。人工审批保留用于少数高风险操作，需要指定人员签名。每个操作都提交到一个哈希链、Ed25519签名的**审计日志**，任何人都可以离线验证。更改一行，验证就会在该行中断。 您的代理在现有的框架中继续运行。MakerChecker是它们的前置检查点和后面的记录：一个Fastify服务器使用Postgres。代理连接为一个**流程**（MakerChecker运行步骤和关口）或一个**代理会话**（MakerChecker授权并记录工具调用您的框架执行）。两者都写入相同的审计链。 **新来者？** 操作员 → [快速入门](#快速入门). 集成商 → [集成](#集成). 安全审查员 → [docs/security-model.md](docs/security-model.md). 检查员 → [docs/audit-spec.md](docs/audit-spec.md). GRC分析师 → [docs/compliance/control-mapping.md](docs/compliance/control-mapping.md). [在线演示](https://makerchecker.ai/demo/)：一个代理被阻止超过其授予的额度，并且不能批准自己的工作，运行的审计链离线验证，一个指定的人在规则要求时签名。无需注册。  ## 工作原理 - **授予。** 将角色绑定到确切的技能版本。其他版本不允许运行。 - **检查。** 每个工具调用首先命中关口。没有授予、超过限制或违反SoD约束，工具主体运行前将被拒绝。 - **关口。** 高风险步骤等待指定人工批准。请求者不能批准自己的请求。 - **记录。** 状态更改和工具调用在同一事务中提交到审计链，每个事件通过哈希链接到上一个事件。 每个拒绝都是命名的和审计的： | 控制 | 拒绝 | |---|---| | 技能未授予角色 | `skill_not_granted` | | 超过每次调用的金额或次数限制（失败关闭） | `limit_amount`, `limit_invocations` | | 冲突的角色已在运行中操作（职责分离） | `enforcement.sod_violation` | | 高风险技能无先验关口 | `high_risk_requires_gate` | | 任何更改的审计行 | `audit verify` → `{ ok: false, failedSeq }` | ## 快速入门 ```bash docker compose up ``` Postgres和服务器启动在端口3000。首次启动时，会初始化演示环境并打印管理员密钥和官员密钥 — 从日志中复制它们。 在生产环境（非演示）部署中，不会初始化任何内容；使用`node dist/cli.js bootstrap-admin --email <e> --name <n>`显式创建第一个管理员及其API密钥（打印一次）。参见 [首次管理员在全新部署](docs/quickstart.md#first-admin-on-a-fresh-deployment). 现金核对流程已初始化并准备就绪，带有制造商检查约束： ```bash export H='authorization: Bearer mk_...' # 日志中的管理员密钥 # 触发流程 curl -X POST localhost:3000/api/flows/daily-cash-reconciliation/runs -H "$H" -H 'content-type: application/json' -d '{}' # 检查待批复的关口 curl localhost:3000/api/approvals -H "$H" # 批准关口 curl -X POST localhost:3000/api/approvals/<id>/decision -H "$H" -H 'content-type: application/json' \ -d '{"decision":"approved","reason":"Exceptions resolved"}' # 验证审计链 curl localhost:3000/api/audit/verify -H "$H" ``` 完整的本地设置和运行真实模型，请参见 [docs/quickstart.md](docs/quickstart.md). 对于Kubernetes，Helm图表 — 非根pod，持久卷上的签名密钥，以及两个角色强化作为预安装钩子 — 位于 [deploy/helm](deploy/helm/README.md). 快速入门连接到Postgres所有者，这会禁用追加审计触发器。为了防止篡改受损的应用凭证，以非所有者角色运行服务器，并使用 [`docker-compose.hardened.yml`](docker-compose.hardened.yml) ([演练](docs/security-model.md#database-hardening-walkthrough)). ## 软件包 pnpm工作区与Turborepo。服务器是AGPL-3.0；SDK和连接器是Apache-2.0，因此您可以将它们嵌入到闭源代码中。 | 软件包 | 许可证 | 它是什么 | |---|---|---| | [`packages/server`](packages/server) | AGPL-3.0 | Fastify API、流程引擎、工作人员、审计写入器、演示种子、`cli.js`管理员工具。 | | [`packages/web`](packages/web) | AGPL-3.0 | Vite/React SPA：运行查看器、审批收件箱、注册表。 | | [`packages/shared`](packages/shared) | AGPL-3.0 | 域类型、TypeBox模式、RFC 8785规范JSON、哈希实用程序。 | | [`packages/sdk`](packages/sdk) | Apache-2.0 | 类型化的TypeScript HTTP客户端加上`governedTool`包装器。 | | [`packages/sdk-python`](packages/sdk-python) | Apache-2.0 | 类型化的Python HTTP客户端加上`governed_tool`。 | | [`packages/connector-langchain`](packages/connector-langchain) | Apache-2.0 | `governLangChainTool` / `governToolkit`适用于LangChain `StructuredTool`s。 | | [`packages/connector-claude-agent`](packages/connector-claude-agent) | Apache-2.0 | `governClaudeTool`适用于Claude Agent SDK自定义工具。 | 受管原始对象 — 代理、角色、技能、触发器、流程、运行/审计 — 是Postgres支持的，并有版本号。参见 [docs/concepts.md](docs/concepts.md). ## 集成 打开一个代理会话，然后包装每个工具。每个调用运行`proxy.check`（拒绝抛出`GovernanceDeniedError`在工具运行前），执行工具，然后记录输出。高风险技能在代理路径上被拒绝；它们需要一个流程关口。 ```ts import { createClient, governedTool, GovernanceDeniedError } from "@makerchecker/sdk"; const client = createClient({ baseUrl: "http://localhost:3000", apiKey: "mk_..." }); const { session } = await client.proxy.openSession({ label: "recon-run" }); const match = governedTool( client, session.id, "recon-preparer", // 注册代理，评估其角色授予 "txn-match@1", // skillRef: name@version (input: { statement: unknown[]; ledger: unknown[] }) => matchTxns(input), ); await match({ statement, ledger }); // 如果拒绝，抛出GovernanceDeniedError await client.proxy.closeSession(session.id); ``` 连接器保留您的工具名称、描述和模式： - **LangChain** — `governLangChainTool`返回一个`DynamicStructuredTool`。参见 [examples/connectors/langchain](examples/connectors/langchain/README.md). - **Claude Agent SDK** — `governClaudeTool`返回一个`SdkMcpToolDefinition`用于`createSdkMcpServer`。参见 [packages/connector-claude-agent](packages/connector-claude-agent/README.md). - **Python** （CrewAI、LangChain、LlamaIndex、AutoGen）— `create_client`然后`governed_tool`；`pip install makerchecker`。参见 [packages/sdk-python](packages/sdk-python/README.md). ## 审计和验证 每个状态转换都会在状态写入的同一事务中发出一个审计事件。每个事件的哈希是SHA-256超过RFC 8785规范JSON的事件（排除`seq`），通过`prev_hash`从实例的创世事件链接。更改任何行，重新计算就会在该行中断。 `GET /api/audit/verify`遍历链并返回 `{ ok, count, headHash }`，或在中断时返回 `{ ok: false, failedSeq, reason }`。CLI验证实时链和签名包离线： ```bash # 验证运行数据库 docker compose exec server node dist/cli.js audit verify # 导出签名包，然后在没有数据库的情况下验证它 docker compose exec server node dist/cli.js audit export --out bundle.json node dist/cli.js audit verify-bundle --in bundle.json node dist/cli.js audit verify-bundle --in bundle.json --key instance.pub # 固定密钥 ``` 包是Ed25519签名的，并带有重新计算链所需的清单。格式在 [docs/audit-spec.md](docs/audit-spec.md)中指定，以便在任何语言中重新实现。`audit report --run <id>`构建一个自包含的HTML运行报告；`audit access-review`渲染角色/授予/SoD审查（也在`/api/reports/access-review`）。 链是记录系统，因此像对待记录系统一样备份： [docs/backup-restore.md](docs/backup-restore.md)涵盖数据库备份、PITR、单独保存写一次签名密钥，以及在`audit verify`后恢复演练。 ## 状态 MakerChecker 1.0。服务器、网页、共享、集成和验证路径均由CI中的Postgres单元测试和集成测试覆盖。 1.0没有拖放式流程构建器、SSO/SAML或多租户。流程定义是类型化的JSON/YAML。 ## 许可证 服务器、网页和共享是AGPL-3.0 ([LICENSE](LICENSE))。SDK、连接器和示例是Apache-2.0 — 导入并在闭源产品中发货，无需 copyleft。可向无法使用AGPL-3.0的组织提供商业许可证：hello@makerchecker.ai。详情： [LICENSING.md](LICENSING.md). 贡献： [CONTRIBUTING.md](CONTRIBUTING.md) · 安全： [SECURITY.md](SECURITY.md) · 代码行为： [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · 更新日志： [CHANGELOG.md](CHANGELOG.md)