# actory-contracts

**Repository Path**: actory-suite/actory-contracts

## Basic Information

- **Project Name**: actory-contracts
- **Description**: Actory Suite — actory-contracts
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# actory-contracts

> Actory 的跨仓库接口契约层。定义全部 HTTP API 的 OpenAPI spec + codegen 生成各仓库的 TypeScript / Python 类型——保证跨仓库接口类型一致。

![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-85EA2D) ![YAML](https://img.shields.io/badge/spec-5份-CB171E)

---

## 目录

- [项目定位](#项目定位)
- [系统架构](#系统架构)
- [契约文件清单](#契约文件清单)
- [消费方](#消费方)
- [DTO Schema](#dto-schema)
- [跨仓协作](#跨仓协作)
- [项目结构](#项目结构)
- [开发指南](#开发指南)

---

## 项目定位

contracts 是 Actory 的**编译时类型安全基础设施**。所有跨仓库的 HTTP 接口规格集中在此仓库定义，通过 codegen 生成各仓库的本地类型包，确保前端、网关、后端的接口类型始终一致。

| ✅ 负责 | ❌ 不负责 |
|---------|---------|
| OpenAPI spec 定义（5 份 YAML） | 运行时代码 |
| TS codegen（→ @actory/contracts npm 包） | 业务逻辑 |
| PY codegen（→ Pydantic models） | 数据模型实现 |
| DTO Schema 定义 | |

---

## 系统架构

```
                    ┌──────────────┐
                    │  contracts   │
                    │  5 份 spec   │
                    │  + codegen   │
                    └──┬───┬───┬──┘
           TS codegen   │   │   PY codegen
        ┌───────────────┘   └──────────────┐
        ▼                                   ▼
  ┌───────────┐                      ┌───────────┐
  │ TS 仓库    │                      │ PY 仓库    │
  │           │                      │           │
  │ frontend  │                      │ engine    │
  │ gateway   │                      │ mcp-gw    │
  │ platform  │                      │ domain    │
  └───────────┘                      └───────────┘

  spec 定义接口形状 → codegen 生成类型 → 各仓库 import 使用
  接口变更先改 contracts → CI 跑 codegen → 各仓库升级依赖
```

---

## 契约文件清单

| 文件 | 路径数 | 职责 |
|------|--------|------|
| `v1-frontend.yaml` | 245 | 前端消费的聚合 API（=engine+platform+ontology），TS codegen 主来源 |
| `v1-engine.yaml` | 122 | 运行态：对话/执行/Playground/HITL/SSE/场景运行 + ExecutionDto/NodeResultDto |
| `v1-platform.yaml` | 114 | 设计态+运营+本体域：认证/租户/Agent/Scene/Skill/MCP/计费/ontology/IM管理 |
| `v1-ontology.yaml` | 40 | 本体：对象/关系/逻辑/动作 CRUD（R12 由 platform 托管，spec 保留供 codegen） |
| `v1-im-gateway.yaml` | 3 | IM webhook + health |

### 架构铁律约束

```
                    路径前缀统一 /api/v1/
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    v1-engine       v1-platform     v1-ontology
    (运行态)         (设计态+运营)    (本体域)
          │               │               │
          └───────┬───────┘               │
                  │  零交叉                │
                  │  engine ∩ platform = ∅ │
                  ▼                       │
            v1-frontend                    │
            (聚合 = 并集) ←────────────────┘
```

- 三后端 yaml 之间**零交叉**（engine ∩ platform = ∅）
- frontend yaml = 三后端 yaml 路径并集
- engine yaml 只含运行态；设计态一律归 platform
- mcp-gateway 和 domain-plugin 不走 OpenAPI（MCP 用 JSON-RPC，DomainPlugin 用 Python ABC）

---

## 消费方

| 仓库 | 语言 | 消费方式 |
|------|------|---------|
| frontend | TS | `import { ExecutionDto } from '@actory/contracts'` |
| gateway | TS | 路由规则对齐 spec 路径定义 |
| platform | TS | 响应类型校验 |
| engine | Python | codegen → Pydantic models（ExecutionDto/AgentConfig/SceneDSL 等） |
| mcp-gateway | Python | codegen → Pydantic models |
| domain-breeding | Python | codegen → Pydantic models |

---

## DTO Schema

核心 DTO 定义（跨仓库共享的类型契约）：

### ExecutionDto

```
ExecutionDto
├─ id: string
├─ status: PENDING | RUNNING | WAITING_HITL | DONE | FAILED
├─ triggerType: TRIGGER | MANUAL
├─ startedAt / finishedAt: datetime
├─ totalDuration / totalTokens / totalCost: number | null
├─ error: string | null
├─ pendingNodeId: string | null       （HITL 等待确认的节点）
└─ nodeResults: NodeResultDto[]
    └─ NodeResultDto
       ├─ id: string
       ├─ nodeId: string               （= 画布节点 ID = TaskStep.step_code）
       ├─ nodeType: START | LLM | AGENT | TOOL | CONDITION | HITL | KNOWLEDGE | END
       ├─ nodeLabel: string
       ├─ input / output: object | null
       ├─ status: PENDING | RUNNING | WAITING | DONE | FAILED | SKIPPED
       ├─ duration: number | null     （秒）
       ├─ error: string | null
       ├─ tokenCount: number | null
       └─ retries: number
```

### 其他核心 DTO

| DTO | 定义位置 | 消费方 |
|-----|---------|--------|
| `AgentConfig` | engine schemas.py | engine ← platform（Internal API） |
| `SceneDSL` | engine schemas.py | engine ← platform（Internal API） |
| `ModelRoute` | engine schemas.py | engine ← platform（Internal API） |
| `ToolDef` | engine schemas.py | engine ← platform（Internal API） |

---

## 跨仓协作

```
┌──────────┐    codegen     ┌──────────┐
│contracts │ ──────────────→│ frontend │
│          │                 ├──────────┤
│ 5 份 YAML│ ──────────────→│ gateway  │
│ + codegen│                 ├──────────┤
│          │ ──────────────→│ platform │
└──────────┘                 ├──────────┤
                             │ engine   │
                             ├──────────┤
                             │ mcp-gw   │
                             ├──────────┤
                             │ domain   │
                             └──────────┘

接口变更流程:
  1. 改 contracts 的 YAML spec
  2. CI 自动 codegen → 发布内部包
  3. 各仓库升级依赖
  4. 按 contracts 新类型修改实现
```

---

## 项目结构

```
actory-contracts/
├── openapi/                         OpenAPI spec
│   ├── _base.yaml                   基础（servers/info）
│   ├── v1-engine.yaml               122 路径 · 运行态
│   ├── v1-platform.yaml             114 路径 · 设计态+运营
│   ├── v1-frontend.yaml             245 路径 · 聚合
│   ├── v1-ontology.yaml             40 路径 · 本体
│   ├── v1-ontology.generated.yaml   40 路径 · 自动提取版
│   └── v1-im-gateway.yaml           3 路径 · IM 渠道
│
├── codegen/                         codegen 配置
│   ├── ts.config.yaml               TS（openapi-typescript-codegen）
│   └── py.config.yaml               Python（datamodel-code-generator）
│
├── scripts/                        提取脚本
│   ├── extract_v5_routes.py         从 V5 代码提取路由
│   └── extract_agentforge_routes.py
│
├── docs/
│   └── Contracts-仓库架构设计.md
├── package.json                     TS codegen 脚本
├── pyproject.toml                   Python codegen 依赖
└── README.md
```

---

## 开发指南

```bash
pnpm install
pnpm codegen:ts    # 生成 TS 类型
pnpm codegen:py    # 生成 Python 类型

# spec 校验
openapi-cli validate openapi/v1-*.yaml
```

### 接口变更流程

1. 改 contracts 的 OpenAPI YAML spec
2. CI 跑 codegen → 发布内部 npm/pip 包
3. 各仓库升级依赖
4. 按 contracts 新类型修改实现
## 文档

契约设计见 [docs/README.md](./docs/README.md)（架构蓝图 / 仓库架构设计）。