内容
# 领域
[](https://scorecard.dev/viewer/?uri=github.com/sensigo-hq/realm)
**代理调用领域。其他所有工具都调用代理。**
大多数人工智能工作流平台都将大型语言模型（LLM）作为服务来编排：平台决定何时调用模型、发送什么内容以及如何处理结果。领域颠覆了这一做法。代理通过MCP调用`execute_step`。领域的有限状态机响应当前步骤的任务和模式。代理执行后，不能跳过步骤、产生错误输出或在人工门户之前继续进行——这不是因为代理可能会忽略的指令，而是因为在提交有效输出之前状态无法更改。
如果您的技能文件已经列出了许多“不要”规则，那么每一个规则都是代理犯的一个错误的疤痕。领域用结构取代了这些规则：错误行为变得不可能，而不是被禁止。
您可以用YAML定义工作流。引擎强制执行步骤顺序，根据JSON模式验证每个代理输出，在每个步骤中捕获防篡改证据，并在人工门户暂停，直到人员批准。结果不仅是运行的日志——它是一个加密可验证的记录，证明每个步骤都正确运行。对于为客户构建人工智能工作流的开发人员来说，这个记录就是交付成果。
## 软件包
| 软件包 | npm | 描述 |
| --- | --- | --- |
| `@sensigo/realm` | [](https://www.npmjs.com/package/@sensigo/realm) | 核心引擎 — 状态守护、执行循环、证据捕获 |
| `@sensigo/realm-cli` | [](https://www.npmjs.com/package/@sensigo/realm-cli) | `realm` 命令行界面 — 19个命令用于构建、操作和提供工作流服务 |
| `@sensigo/realm-mcp` | [](https://www.npmjs.com/package/@sensigo/realm-mcp) | `realm-mcp` MCP服务器 — 10个用于人工智能代理连接的工具 |
| `@sensigo/realm-testing` | [](https://www.npmjs.com/package/@sensigo/realm-testing) | 测试工具 — 固定装置、断言、内存存储 |
## 安装
**命令行界面（全局）**
```bash
npm install -g @sensigo/realm-cli
```
**MCP服务器（全局，用于人工智能代理连接）**
```bash
npm install -g @sensigo/realm-mcp
```
**程序化使用**
```bash
npm install @sensigo/realm
```
**测试工具**
```bash
npm install --save-dev @sensigo/realm-testing
```
## 快速入门
### 1. 搭建工作流
```bash
realm workflow init my-workflow
```
这会创建`my-workflow/`，包含`workflow.yaml`、`schema.json`、`.env.example`和`README.md`。
### 2. 编辑`my-workflow/workflow.yaml`
```yaml
id: my-workflow
name: '我的工作流'
version: 1
steps:
gather_input:
description: '代理收集所需信息'
execution: agent
depends_on: []
input_schema:
type: object
required: [summary]
properties:
summary:
type: string
finalize:
description: '人工审核和批准提交的摘要'
execution: auto
depends_on: [gather_input]
trust: human_confirmed
```
### 3. 验证、注册和运行
```bash
realm workflow validate ./my-workflow # 检查YAML
realm workflow register ./my-workflow # 在本地存储中注册
realm workflow run ./my-workflow # 交互式运行（开发模式）
```
`realm workflow run`驱动工作流一步一步地进行，提示您模拟代理输出，并在人工门户暂停。
## 通过MCP连接人工智能代理
启动MCP服务器（内置于命令行界面 - 无需额外安装）：
```bash
realm mcp
```
**Claude Desktop - `claude_desktop_config.json`**
```json
{
"mcpServers": {
"realm": {
"command": "realm",
"args": ["mcp"]
}
}
}
```
**Cursor - `~/.cursor/mcp.json`**
```json
{
"mcpServers": {
"realm": {
"command": "realm",
"args": ["mcp"]
}
}
}
```
**托管代理平台**（OpenClaw、Claude.ai、自定义后端）无法启动本地子进程，请改用`realm serve`:
```bash
REALM_SERVE_TOKEN=<secret> realm serve --port 3001
```
这启动了一个受Bearer令牌身份验证保护的HTTP MCP服务器。在本地开发过程中使用`--dev`跳过身份验证。
连接后，代理可以访问10种工具：`list_workflows`、`get_workflow_protocol`、`start_run`、`start_run_batch`、`execute_step`、`submit_human_response`、`get_run_state`、`abandon_run`、`create_workflow`和`list_runs`。
代理调用`list_workflows`以发现已注册的工作流，然后调用`get_workflow_protocol`以获取匹配的工作流的明确逐步指令。它不能执行步骤顺序错误或提交模式验证失败的输出。
当没有注册的工作流与任务匹配时，代理调用`create_workflow`并附上一个`steps`数组，以注册动态工作流并立即启动运行 - 无需YAML文件或`realm workflow register`。运行从那时起与YAML工作流完全相同。
**多个工作流：** 使用`realm workflow register`注册您需要的所有工作流。代理通过`list_workflows`发现它们，并通过ID选择合适的工作流。为每个工作流添加一个`skill.md`，用于工作流特定的代理行为。
## 项目扩展
工作流可以声明自己的自定义适配器、步骤处理程序和处理器 - 无需包装服务器，也无需逐命令连接：
```yaml
# workflow.yaml
extensions: ./registry.js # 相对模块路径；默认导出声明 { adapters, handlers, processors }
```
每个执行步骤的入口点（`run`、`agent`、`listen`、`serve`、`mcp`、`test`、`validate`）都以相同的方式解析声明，具有快速失败加载和强制信任边界。请参阅 [docs/reference/project-extensions.md](docs/reference/project-extensions.md)。
## 命令行界面参考
| 命令 | 描述 |
| --- | --- |
| `realm workflow init <name>` | 搭建新的工作流项目目录 |
| `realm workflow validate <path>` | 验证工作流YAML而不注册它 |
| `realm workflow register <path>` | 在本地存储中注册工作流 |
| `realm workflow watch <path>` | 监视工作流YAML并在每次更改时重新注册 |
| `realm workflow run <path>` | 交互式运行工作流（开发模式） |
| `realm agent` | 使用LLM自主运行工作流 - 无需MCP客户端或IDE |
| `realm workflow test <path>` | 对工作流运行基于固定装置的测试 |
| `realm run list` | 列出所有运行；按 `--workflow <id>` 或 `--status <phase>` 筛选 |
| `realm run resume <run-id>` | 恢复暂停的运行 |
| `realm run respond <run-id>` | 向人工门提交响应 |
| `realm run inspect <run-id>` | 打印运行的完整证据链 |
| `realm run replay <run-id>` | 使用修改后的步骤输出重新评估前提条件 |
| `realm run diff <run-a> <run-b>` | 比较两个运行的证据链 |
| `realm run cleanup` | 将空闲的非终端运行标记为废弃 |
| `realm workflow migrate` | 从早期版本为本地工作流定义填充溯源字段 |
| `realm mcp` | 启动MCP服务器（用于本地人工智能代理） |
| `realm serve` | 启动MCP服务器（用于托管平台） |
| `realm listen` | 启动一个Webhook服务器，将传入的Webhook路由到工作流（按`trigger:`块） |
在任何命令上运行`realm <command> --help`以获取完整的选项。
> GitHub-only的`realm webhook`命令已被删除，改为`realm listen`（带有`auth.mode: github`的工作流`trigger:`块取代它）。运行`realm webhook`现在会打印一条迁移消息并以非零退出。
## 文档
- [入门](docs/getting-started.md) — 包括服务适配器、人工门户和步骤处理器的端到端演练
- [YAML模式参考](docs/reference/yaml-schema.md) — 所有步骤字段、执行模式、转换、信任级别、代理配置文件
- [处理程序编写参考](docs/reference/handlers.md) — `StepHandler`接口、`StepContext`字段、基元目录、内置处理程序、注册
- [MCP协议参考](docs/reference/mcp-protocol.md) — 工具、响应信封、`next_action`、`agent_action`
- [命令行界面参考](docs/reference/cli-commands.md) — 所有命令及其选项
- [内置服务适配器](docs/reference/adapters.md) — `FileSystemAdapter`、`GitHubAdapter`、`GenericHttpAdapter` — 配置、操作、响应形状
- [测试参考](docs/reference/testing.md) — `@sensigo/realm-testing`完整API：固定装置运行器、模拟器、断言、GitHub模拟服务器
- [示例](examples/) — 工作流示例
## 开发
**前提条件：** Node.js 22+，npm 10+
**贡献者要求：** 开发工具链（特别是eslint 10，它声明`engines: ^20.19 || ^22.13 || >=24`）实际上需要**Node ≥22.13**才能在本地运行`npm run lint` - 较旧的Node 22补丁版本将在此处失败。CI运行Node 24，这也是推荐的本地版本；请参见`.nvmrc`（`nvm use` / `fnm use` / `volta run`将自动选取它）。这是**仅限开发**的要求 - 它不会改变发布的运行时底线，即`@sensigo/*`的每个消费者保持`>=22.0.0`。
```bash
npm install # 安装所有工作区依赖项
npm run build # 编译所有软件包
npm run test # 运行所有测试
npm run lint # 检查所有软件包
```
## 安全
请参阅 [`SECURITY.md`](SECURITY.md) 了解如何报告漏洞（GitHub私有漏洞报告 - 请勿公开问题或PR）以及如何处理依赖项建议。
每个`@sensigo/*`软件包都通过npm**受信任的发布**从CI发布，并附有**SLSA构建溯源**，可用于每个版本。 使用以下命令验证已安装软件包的溯源：
```bash
npm audit signatures
```
[](https://scorecard.dev/viewer/?uri=github.com/sensigo-hq/realm)
## 许可证
Apache 2.0
