Files

T

phptits b1f17cf637 v2 platform foundation (docs 01/02/03): Action Runtime + Registry + unified API

- v2 foundation: ActionResult/DevError/ActorContext/ResourceRef/Execution types
- ActionRegistry + ResourceRegistry (namespaced types, FAIL FAST on duplicates)
- ActionRuntime pipeline: validate -> authorize -> middleware -> handler ->
  output validation -> audit -> event -> execution persisted (devos_action_executions)
- Legacy bridge: v1 services registered as devops.*/core.* resources & actions (47 actions, 9 resources)
- Unified Action API: POST /api/v2/actions/:actionId, GET discovery (actions/resources)
- 10 v2 unit tests (registry fail-fast, validation, authz, failure audit, events)

2026-09-10 21:09:44 +00:00

52 KiB

Raw Blame History

DevOS Data / Query / Search / Index Runtime

Document: 14 Status: Required Audience: Zcode / DevOS Core Team Depends On:

03_RESOURCE_ACTION_MODEL.md

06_MCP_SKILL_AGENT_RUNTIME.md

09_TASK_JOB_QUEUE_RUNTIME.md

12_MIGRATION_VERSIONING_COMPATIBILITY.md

13_DEPLOYMENT_ENVIRONMENT_CONFIG_RUNTIME.md

1. Goals

DevOS 已经拥有：

Resource
Action
Event
Agent
Skill
MCP
Task
Job
Queue
Worker
Configuration
Environment
Deployment

下一步必须解决：

DevOS 中的数据应该如何被统一访问、查询、过滤、排序、搜索、聚合和索引？

否则最终会出现：

UI → Prisma
Plugin → Prisma
Agent → Prisma
MCP → Prisma
Action → Prisma
Search → Elasticsearch
Plugin Search → 自己实现

最终形成多个数据访问体系。

本 Document 要建立：

Data Runtime
Query Runtime
Repository Runtime
Search Runtime
Index Runtime
Filter Runtime
Pagination Runtime
Relation Runtime

最终原则：

Resource
    ↓
Data Definition
    ↓
Repository / Query
    ↓
Data Runtime
    ↓
Database / Search Index

2. Core Principle

DevOS 必须区分：

Resource
Data
Query
Search
Index
Action

它们不是同一个东西。

3. Resource

Resource 表示：

系统中的业务对象。

例如：

core.user
core.organization
core.project
core.task

seo.website
seo.article

devops.server
devops.deployment

4. Data

Data 表示：

Resource 当前保存的数据。

例如：

{
  "id": "website_123",
  "domain": "example.com",
  "status": "active"
}

5. Query

Query 表示：

从结构化数据中获取数据。

例如：

所有 active website
最近创建的 20 个 Task
某个 Organization 的 Users

6. Search

Search 表示：

根据文本、语义、字段权重等进行相关性检索。

例如：

搜索：
"关于 AI SEO 的文章"

返回：
Article 1
Article 2
Website 3
Task 4

7. Index

Index 表示：

为 Query / Search 提供高效读取结构。

数据库 Index：

B-Tree
GIN
GiST

搜索 Index：

Full Text
Vector
Hybrid

8. Architecture

                       Resource
                          │
                    Resource Schema
                          │
             ┌────────────┴────────────┐
             │                         │
        Data Runtime              Search Runtime
             │                         │
       Repository Runtime         Index Runtime
             │                         │
       ┌─────┴──────┐          ┌───────┴───────┐
       │            │          │               │
   PostgreSQL     Cache     Full Text       Vector
                              Index           Index

9. Data Runtime

统一入口：

export interface DataRuntime {
  repository<T>(
    resource: string,
    context: DataContext
  ): Repository<T>

  query<T>(
    resource: string,
    query: QueryInput,
    context: DataContext
  ): Promise<QueryResult<T>>

  count(
    resource: string,
    query: QueryInput,
    context: DataContext
  ): Promise<number>

  exists(
    resource: string,
    query: QueryInput,
    context: DataContext
  ): Promise<boolean>
}

10. DataContext

所有数据访问必须携带 Context。

export interface DataContext {
  requestId: string

  actor: Actor

  organizationId?: string

  projectId?: string

  environmentId?: string

  permissions: string[]

  metadata?: Record<string, unknown>
}

禁止：

repository.findMany()

在没有：

actor
organization
scope

的情况下访问业务数据。

11. Repository

Repository 是 Resource 的结构化数据访问接口。

export interface Repository<T> {
  findById(
    id: string
  ): Promise<T | null>

  findMany(
    query: QueryInput
  ): Promise<QueryResult<T>>

  count(
    query: QueryInput
  ): Promise<number>

  exists(
    query: QueryInput
  ): Promise<boolean>
}

注意：

Repository 默认只负责：

读取

写入仍然应该通过：

Action Runtime

12. Important Rule

禁止：

UI
 ↓
Repository
 ↓
UPDATE database

应该：

UI
 ↓
Action
 ↓
Action Runtime
 ↓
Repository / Domain Service
 ↓
Database

13. Read vs Write

DevOS 可以采用：

CQRS-lite

即：

Read
 ↓
Query / Repository

Write
 ↓
Action Runtime

不需要一开始实现完整 CQRS/Event Sourcing。

14. Query Input

export interface QueryInput {
  select?: string[]

  filter?: FilterNode

  sort?: SortRule[]

  pagination?: PaginationInput

  include?: IncludeRule[]

  search?: SearchInput

  groupBy?: string[]

  aggregates?: AggregateRule[]

  distinct?: boolean
}

15. Filter

Filter 是 DevOS 非常重要的统一抽象。

例如：

status = active

{
  field: 'status',
  operator: 'eq',
  value: 'active'
}

16. Filter Operators

至少支持：

eq
neq
gt
gte
lt
lte

in
notIn

contains
startsWith
endsWith

isNull
isNotNull

between

exists

17. Filter Tree

复杂查询：

status = active
AND
(
  score > 80
  OR
  backlinks > 100
)

表示：

{
  and: [
    {
      field: 'status',
      operator: 'eq',
      value: 'active'
    },
    {
      or: [
        {
          field: 'score',
          operator: 'gt',
          value: 80
        },
        {
          field: 'backlinks',
          operator: 'gt',
          value: 100
        }
      ]
    }
  ]
}

18. Filter Schema

export type FilterNode =
  | FilterCondition
  | FilterGroup

export interface FilterCondition {
  field: string

  operator:
    | 'eq'
    | 'neq'
    | 'gt'
    | 'gte'
    | 'lt'
    | 'lte'
    | 'in'
    | 'notIn'
    | 'contains'
    | 'startsWith'
    | 'endsWith'
    | 'isNull'
    | 'isNotNull'
    | 'between'

  value?: unknown
}

export interface FilterGroup {
  and?: FilterNode[]

  or?: FilterNode[]

  not?: FilterNode
}

19. Security: Filter Fields

用户不能任意查询数据库字段。

Resource 必须声明：

export interface FieldDefinition {
  name: string

  type: FieldType

  readable?: boolean

  writable?: boolean

  searchable?: boolean

  sortable?: boolean

  filterable?: boolean

  sensitive?: boolean
}

例如：

passwordHash

必须：

readable = false
searchable = false
filterable = false

20. Field Types

至少：

string
text
integer
float
decimal
boolean
date
datetime
json
uuid
enum
relation
array

未来：

vector
geometry
binary

21. Resource Schema

Resource 应定义 Schema：

export interface ResourceSchema<T = unknown> {
  resource: string

  version: string

  fields: FieldDefinition[]

  relations?: RelationDefinition[]

  indexes?: IndexDefinition[]

  search?: SearchDefinition

  validation?: unknown
}

22. Resource Schema Example

const websiteSchema: ResourceSchema = {
  resource: 'seo.website',

  version: '1.0',

  fields: [
    {
      name: 'id',
      type: 'uuid',
      readable: true
    },
    {
      name: 'domain',
      type: 'string',
      readable: true,
      searchable: true,
      sortable: true,
      filterable: true
    },
    {
      name: 'status',
      type: 'enum',
      readable: true,
      filterable: true,
      sortable: true
    }
  ]
}

23. Pagination

统一支持：

offset pagination
cursor pagination

24. Offset Pagination

export interface OffsetPagination {
  type: 'offset'

  page: number

  pageSize: number
}

{
  items: [],
  page: 1,
  pageSize: 20,
  total: 1234
}

适合：

Admin UI
Reports
Tables

25. Cursor Pagination

export interface CursorPagination {
  type: 'cursor'

  cursor?: string

  limit: number

  direction?: 'forward' | 'backward'
}

{
  items: [],
  nextCursor: '...',
  hasMore: true
}

适合：

Agent
Activity Feed
Events
Logs
Large datasets

26. Pagination Limits

系统必须限制：

maxPageSize
maxOffset
maxQueryCost

默认：

pageSize <= 100

Agent / MCP：

更严格

禁止：

pageSize = 1000000

27. Sort

export interface SortRule {
  field: string

  direction: 'asc' | 'desc'
}

例如：

createdAt desc
score desc
domain asc

28. Sort Security

只有：

sortable = true

的字段才能排序。

禁止用户：

ORDER BY arbitrary SQL

29. Include

支持 Resource Relation：

Task
 └── Jobs

查询：

{
  include: [
    {
      relation: 'jobs'
    }
  ]
}

但是必须防止：

N+1 query

30. Relations

统一：

export interface RelationDefinition {
  name: string

  target: string

  type:
    | 'one'
    | 'many'

  foreignKey?: string

  targetKey?: string

  readable?: boolean
}

31. Relation Examples

core.organization
 └── users

core.task
 └── jobs

core.job
 └── executions

seo.website
 └── articles

32. Relation Permission

Relation 也需要权限。

例如：

User

可以看到：

Organization

但不能自动：

Organization
 ↓
all users

除非：

relation.read

允许。

33. Query Authorization

Query Runtime 必须执行：

Actor Permission
+
Resource Permission
+
Field Permission
+
Scope Policy
+
Filter Policy

最终才生成：

Database Query

34. Row-Level Security

某些 Resource 需要 Row Scope。

例如：

organizationId = currentOrganization

必须由 Runtime 自动注入。

不能依赖前端：

?organizationId=xxx

35. Scope Provider

export interface ScopeProvider {
  resolve(
    resource: string,
    context: DataContext
  ): Promise<FilterNode | undefined>
}

例如：

core.task

自动添加：

organizationId = currentOrganization

36. Scope Composition

最终：

User Filter
AND
Organization Scope
AND
Project Scope
AND
Environment Scope
AND
Policy Scope

例如：

User:
status = failed

System:
organizationId = org_1

Project:
projectId = project_2

最终：

status = failed
AND organizationId = org_1
AND projectId = project_2

37. Query Compilation

Query Runtime：

QueryInput
 ↓
Validate
 ↓
Authorize
 ↓
Inject Scope
 ↓
Resolve Relations
 ↓
Optimize
 ↓
Compile
 ↓
Database Query

38. SQL Boundary

禁止：

Agent
Plugin
MCP
UI

直接发送：

raw SQL

只有：

Data Runtime

可以执行 SQL。

39. Raw SQL

Core 可以在极少数 Infrastructure 场景使用：

data.rawQuery(...)

但必须：

internal only

不能暴露：

MCP
REST
Agent
Plugin public API

40. Query Cost

每一个 Query 应估算成本：

export interface QueryCost {
  estimatedRows: number

  joins: number

  sortCost: number

  searchCost: number

  totalScore: number
}

高成本 Query：

reject

或：

require async Task

41. Large Query

例如：

导出 100 万条数据

不能：

HTTP Request
 ↓
Query
 ↓
return 1M rows

应该：

Export Action
 ↓
Task
 ↓
Job
 ↓
Worker
 ↓
Cursor Query
 ↓
Artifact

42. Data Export

统一 Resource：

core.export

Action：

core.export.create
core.export.cancel
core.export.download

支持：

CSV
JSON
JSONL
Excel

43. Export Security

Export 必须使用：

same permission
same scope
same field security

不能：

UI Query

没有权限：

passwordHash

但：

Export

却把它导出来。

44. Search Runtime

统一：

export interface SearchRuntime {
  search<T>(
    resource: string,
    input: SearchInput,
    context: DataContext
  ): Promise<SearchResult<T>>

  suggest(
    resource: string,
    input: SuggestInput,
    context: DataContext
  ): Promise<SuggestResult>
}

45. Search Input

export interface SearchInput {
  query: string

  fields?: string[]

  filter?: FilterNode

  sort?: SortRule[]

  pagination?: PaginationInput

  mode?:
    | 'fulltext'
    | 'semantic'
    | 'hybrid'

  minScore?: number
}

46. Search Modes

Full Text

keyword
token
phrase
field weight

Semantic

embedding
vector similarity

Hybrid

Full Text
+
Vector
+
Ranking

DevOS 推荐最终：

hybrid

47. Search Provider

抽象：

export interface SearchProvider {
  index(
    document: SearchDocument
  ): Promise<void>

  delete(
    id: string
  ): Promise<void>

  search(
    input: SearchProviderInput
  ): Promise<SearchProviderResult>

  health(): Promise<HealthResult>
}

48. Search Provider Implementations

第一阶段：

PostgreSQL Full Text

可选：

OpenSearch
Elasticsearch
Meilisearch
Typesense

Vector：

pgvector

优先使用：

PostgreSQL + pgvector

减少基础设施复杂度。

49. Search Index

Resource 可以声明：

export interface SearchDefinition {
  enabled: boolean

  fields: SearchField[]

  provider?: string

  vector?: {
    enabled: boolean

    dimensions: number

    model?: string
  }
}

50. Search Field

export interface SearchField {
  field: string

  weight?: number

  searchable?: boolean

  vectorizable?: boolean

  stored?: boolean
}

例如：

title weight=10
description weight=5
content weight=2

51. Search Document

export interface SearchDocument {
  id: string

  resource: string

  resourceId: string

  fields: Record<string, unknown>

  text?: string

  vector?: number[]

  metadata?: Record<string, unknown>

  version: string

  indexedAt: Date
}

52. Index Isolation

Index 必须包含：

organizationId
projectId
environmentId
resource

防止：

Org A

搜索到：

Org B

的数据。

53. Search Permission

搜索结果必须再次执行：

Permission
+
Scope

不能认为：

Index = authorized data

因为权限可能发生变化。

54. Search Flow

User
 ↓
Search Action
 ↓
Search Runtime
 ↓
Permission
 ↓
Scope
 ↓
Search Provider
 ↓
Result
 ↓
Permission Recheck
 ↓
Return

55. Search Ranking

基础：

text relevance
field weight
freshness
exact match

未来：

business score
authority
quality
user preference

56. Hybrid Ranking

例如：

finalScore =
  textScore * 0.4
  +
  vectorScore * 0.4
  +
  businessScore * 0.2

权重必须由：

Search Definition

定义。

57. Semantic Search

Agent 可以：

搜索：
“寻找高质量 AI SEO 文章”

转换：

embedding
 ↓
vector search
 ↓
metadata filter
 ↓
ranking

58. Agent Search

Agent 不应该获取：

10000 records

而应该：

Search Runtime
 ↓
topK

例如：

topK = 10

59. Capability Discovery Search

结合：

06_MCP_SKILL_AGENT_RUNTIME.md

Capability Registry 也可以使用：

Search Runtime

搜索：

Capability
Skill
Plugin
MCP
Action

60. Search as Capability

Search 本身也是：

Capability

例如：

core.search

但 Agent 获取搜索能力时：

Search

必须根据：

Permission
Scope
Budget

限制。

61. Index Lifecycle

Index 状态：

pending
building
ready
degraded
rebuilding
failed

62. Index Resource

core.searchIndex

export interface SearchIndex {
  id: string

  resource: string

  provider: string

  status:
    | 'pending'
    | 'building'
    | 'ready'
    | 'degraded'
    | 'rebuilding'
    | 'failed'

  documentCount: number

  version: string

  lastIndexedAt?: Date

  error?: string
}

63. Index Actions

core.searchIndex.create
core.searchIndex.rebuild
core.searchIndex.pause
core.searchIndex.resume
core.searchIndex.delete
core.searchIndex.health

64. Rebuild

Index 重建必须：

Task
 ↓
Job
 ↓
Worker
 ↓
Cursor Query
 ↓
Batch Index

不能：

HTTP Request
 ↓
全部读取
 ↓
全部 Index

65. Incremental Index

Resource 数据变化时：

Resource Changed
 ↓
Event
 ↓
Index Job
 ↓
Update Index

例如：

seo.website.updated

触发：

search.index.update

66. Outbox

数据库写入：

Transaction
 ├── Update Resource
 └── Insert Outbox Event

然后：

Outbox
 ↓
Worker
 ↓
Search Index

防止：

DB updated
but index not updated

67. Index Consistency

DevOS 默认：

Database = Source of Truth
Search Index = Derived State

因此：

Index corrupted

可以：

Rebuild

而不会丢失业务数据。

68. Cache Runtime

Data Runtime 可以使用：

Cache Runtime

export interface CacheRuntime {
  get<T>(key: string): Promise<T | undefined>

  set<T>(
    key: string,
    value: T,
    options?: CacheOptions
  ): Promise<void>

  delete(key: string): Promise<void>

  invalidate(prefix: string): Promise<void>
}

69. Cache Rules

缓存只能是：

derived data

不能作为：

source of truth

70. Cache Key

必须包含：

resource
query
scope
configuration version

例如：

devos:
query:
seo.website:
org_1:
hash(...)

避免：

Org A cache

被：

Org B

使用。

71. Query Cache Invalidation

Resource 更新：

Action
 ↓
Event
 ↓
Cache Invalidation

例如：

seo.website.updated

触发：

invalidate seo.website

72. Data Loader

防止 N+1：

export interface DataLoader<K, V> {
  load(key: K): Promise<V>

  loadMany(keys: K[]): Promise<V[]>
}

Relation Runtime 应使用：

batch loading

73. Query Observability

每个 Query 记录：

requestId
resource
operation
duration
rows
queryCost
cacheHit
provider

不能记录：

Secret
Sensitive values

74. Slow Query Detection

配置：

query.slowThresholdMs

例如：

> 500ms

产生：

core.query.slow

Event / Metric。

75. Query Timeout

每个 Query 必须有：

timeout

例如：

{
  timeoutMs: 5000
}

超时：

cancel

而不是无限等待。

76. Query Cancellation

Data Runtime 必须支持：

interface QueryOptions {
  signal?: AbortSignal
}

Agent / Task 取消时：

Agent
 ↓
Task Cancel
 ↓
Job Cancel
 ↓
Query Abort

77. Query Transactions

复杂 Action：

Action
 ↓
Transaction
 ├── read
 ├── validate
 ├── write
 └── event

Transaction 生命周期不能跨：

HTTP request
Task
Worker
Agent iteration

过长时间。

78. Optimistic Lock

需要支持：

version
updatedAt

例如：

Update Website
where id=123
and version=4

成功：

version=5

失败：

Conflict

79. Data Conflict

export interface DataConflictError {
  type: 'conflict'

  resource: string

  resourceId: string

  expectedVersion: number

  actualVersion: number
}

UI：

数据已被其他用户修改。

Agent：

re-read
→
re-plan

80. Soft Delete

Resource 可以定义：

deletion: {
  strategy:
    | 'hard'
    | 'soft'
}

Soft delete：

deletedAt

默认 Query：

deletedAt IS NULL

81. Restore

Soft Delete Resource：

restore

Action：

resource.restore

必须重新经过：

Authorization
Scope
Validation

82. Archive

Archive 和 Delete 必须区分：

active
archived
deleted

Archive：

仍然存在
但默认不出现在普通 Query

83. Data Lifecycle

Resource 可以定义：

export interface DataLifecycle {
  retentionDays?: number

  archiveAfterDays?: number

  deleteAfterDays?: number
}

例如：

Execution
 ├── 30 days → archive
 └── 180 days → delete

84. Lifecycle Worker

数据生命周期由：

Scheduler
 ↓
Task
 ↓
Job
 ↓
Worker

执行。

禁止：

API startup
 ↓
delete old records

85. Data Retention Policy

Production 必须支持：

Audit retention
Execution retention
Log retention
Artifact retention
Event retention

不同类型可以独立配置。

86. Privacy

未来如果系统保存用户个人数据：

Resource 必须声明：

privacy?: {
  pii: boolean

  fields?: string[]

  retentionDays?: number
}

PII 字段：

redaction
access policy
export policy

必须更严格。

87. Data Masking

支持：

email
phone
address
token
credential

显示：

u***@example.com

而不是：

full value

88. Generic CRUD

对于简单 Resource：

list
get
create
update
delete

可以自动生成。

但是：

Generic CRUD

只能作为：

Resource Action Generator

不能绕过：

Action Runtime

89. Resource Query API

90. Generic Query Example

{
  "filter": {
    "and": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      }
    ]
  },
  "sort": [
    {
      "field": "createdAt",
      "direction": "desc"
    }
  ],
  "pagination": {
    "type": "cursor",
    "limit": 20
  }
}

91. Generic Search API

POST /api/search

请求：

{
  "resource": "seo.website",
  "query": "AI SEO",
  "mode": "hybrid",
  "limit": 10
}

{
  "items": [],
  "nextCursor": "...",
  "totalApproximate": 100
}

92. Search Across Resources

支持：

POST /api/search/global

例如：

query:
"Cloudflare production"

搜索：

Website
Server
Deployment
Task
Plugin
Document

但是必须：

permission filtered

93. Global Search Registry

export interface GlobalSearchSource {
  resource: string

  priority: number

  searchableFields: string[]

  transform(
    item: unknown
  ): SearchDocument
}

Plugin 可以注册：

global search source

94. Plugin Search

Plugin 可以声明：

search?: {
  enabled: boolean

  fields: SearchField[]
}

安装后：

Plugin
 ↓
Search Registry
 ↓
Global Search

自动可搜索。

95. MCP Search

MCP 可以调用：

core.search

而不是：

MCP → Database

MCP 搜索：

permission
+
scope
+
budget

必须全部有效。

96. Agent Query vs Search

Agent 应优先：

Search

而不是：

Query all

例如：

找 10 个最相关网站

使用：

Search topK=10

而不是：

Query all websites

97. Agent Structured Query

如果目标明确：

查找 status=failed 的任务

使用：

Query

而不是：

LLM semantic search

规则：

Structured requirement
 → Query

Natural language requirement
 → Search

98. Search Progressive Disclosure

Agent Search Tool Schema：

Level 1:
search(resource, query)

Level 2:
filters
fields
ranking

Level 3:
advanced search

不要一次把：

所有 Search Schema

发送给模型。

99. Data Capability

Data Runtime 暴露：

Query
Search
Count
Exists
Aggregate
Export

作为：

Capabilities

例如：

core.resource.query
core.resource.search
core.resource.aggregate
core.resource.export

100. Aggregate

支持：

count
sum
avg
min
max

例如：

统计：
过去 7 天失败 Task 数量

不要读取所有 Task：

Query all
 ↓
Agent count

而应该：

Aggregate

101. Aggregate Definition

export interface AggregateRule {
  field?: string

  function:
    | 'count'
    | 'sum'
    | 'avg'
    | 'min'
    | 'max'

  alias: string
}

102. Group By

例如：

按 status 统计 Task

{
  groupBy: ['status'],
  aggregates: [
    {
      function: 'count',
      alias: 'count'
    }
  ]
}

103. Aggregate Security

Aggregate 也必须：

permission
scope
field policy

例如：

salary

不能因为：

AVG(salary)

就绕过：

salary field permission

104. Query Builder

UI 可以提供：

Filter Builder
Sort Builder
Group Builder
Search

例如：

Status [is] Failed
AND
Created At [after] 2026-09-01

最终生成：

QueryInput

105. Saved Query

用户可以保存：

Saved Query

Resource：

core.savedQuery

interface SavedQuery {
  id: string

  resource: string

  name: string

  query: QueryInput

  ownerId: string

  scope: 'private' | 'organization' | 'project'

  createdAt: Date
}

106. Saved Search

类似：

core.savedSearch

可以保存：

query
filters
sort
columns

UI：

My Searches
Team Searches

107. Query Preset

Plugin 可以提供：

preset

例如 SEO：

High Value Websites
Broken Backlinks
Low DR Websites
Recently Scanned

这些都是：

Saved Query / Query Preset

而不是每个页面重新写 SQL。

108. Data Table

DevOS UI 应提供：

Generic Resource Table

支持：

columns
filter
sort
pagination
search
selection
bulk actions
saved views
export

109. Generic Resource Detail

Resource Detail 页面可以自动生成：

Overview
Fields
Relations
Activity
Events
Tasks
Executions
Artifacts

Plugin 可以扩展：

Custom Tabs
Widgets
Actions

110. Bulk Operations

大量操作：

Select 100 websites
 ↓
Bulk Action

不能：

HTTP request
 ↓
for each
 ↓
execute synchronously

必须：

Bulk Action
 ↓
Task
 ↓
Jobs

111. Bulk Job Expansion

例如：

100 websites

创建：

1 Task
+
100 Jobs

而不是：

100 Tasks

符合：

09_TASK_JOB_QUEUE_RUNTIME.md

112. Data Change Events

Resource 数据发生变化：

created
updated
deleted
restored
archived

事件：

core.resource.created
core.resource.updated
core.resource.deleted

Plugin 可以订阅。

113. Event Payload

Event 不应该发送完整 Resource：

巨大 Payload

默认：

interface ResourceChangedEvent {
  resource: string

  resourceId: string

  operation: 'created' | 'updated' | 'deleted'

  version: number

  changedFields?: string[]

  actorId: string

  timestamp: Date
}

Consumer 如果需要：

Query Resource

重新读取。

114. Search Index Event

Resource Updated
 ↓
Outbox
 ↓
Event
 ↓
Index Worker
 ↓
Search Index

这样：

Database

始终是：

Source of Truth

115. Reindex Safety

Reindex 必须支持：

checkpoint
resume
retry
pause
cancel

因此：

Task

必须保存：

cursor
processedCount
failedCount

116. Search Provider Failure

如果：

OpenSearch

挂了：

业务数据：

仍然正常

Search：

degraded

可以：

fallback PostgreSQL search

如果配置允许。

117. Search Fallback

interface SearchPolicy {
  primary: string

  fallback?: string[]

  failMode:
    | 'fail'
    | 'fallback'
}

118. Data Provider

Data Runtime 也应该抽象：

interface DataProvider {
  query(...)
  transaction(...)
  health(...)
}

默认：

PostgreSQL

未来：

MySQL
SQLite
External API

但 DevOS Core 推荐：

PostgreSQL first

119. External Resource

不是所有 Resource 都必须存在数据库。

例如：

GitHub Repository
Cloudflare Zone
AWS Server

可以：

External Resource Provider

interface ExternalResourceProvider<T> {
  get(id: string): Promise<T>

  list(query: QueryInput): Promise<QueryResult<T>>
}

120. External Resource Cache

外部 Resource：

GitHub Repository

可以缓存：

Database
+
Cache

但：

External API

仍然是真实来源。

121. Sync Runtime

外部 Resource 同步：

External API
 ↓
Sync Task
 ↓
Job
 ↓
Worker
 ↓
Resource
 ↓
Database
 ↓
Index

122. Sync Cursor

支持：

cursor
etag
updatedAt
lastSyncAt

减少：

API calls

123. Rate Limit

Data Provider 必须支持：

rate limit
retry
backoff
concurrency

特别是：

GitHub
Cloudflare
AWS
External APIs

124. Provider Resource Boundary

Provider 不应该：

直接修改核心数据库

应该：

Provider
 ↓
External Data
 ↓
Action
 ↓
Resource Repository

125. Search Embedding Provider

Embedding 也作为：

Provider

例如：

embedding.openai
embedding.local

接口：

interface EmbeddingProvider {
  embed(
    input: string
  ): Promise<number[]>

  embedBatch(
    inputs: string[]
  ): Promise<number[][]>

  dimensions(): number
}

126. Embedding Task

大量数据 embedding：

Resource
 ↓
Index Task
 ↓
Batch Jobs
 ↓
Embedding Provider
 ↓
Vector Index

不能：

API request
 ↓
10000 embeddings

127. Token Budget

Embedding / Search / LLM 查询也要计入：

Agent Budget

尤其：

embedding calls
external search calls

128. Search Budget

Agent Search：

interface SearchBudget {
  maxQueries: number

  maxResults: number

  maxExternalCalls: number

  maxEstimatedCost?: number
}

129. Data Access Audit

敏感 Resource Query：

User
 ↓
Query
 ↓
Audit

尤其：

User
Credential
Secret Metadata
Billing
Audit
Organization

130. Query Audit Policy

Resource Schema 可以定义：

audit?: {
  read: boolean

  sensitiveRead: boolean

  export: boolean
}

131. Data Access Observability

Metrics：

devos_query_total
devos_query_duration
devos_query_errors
devos_query_rows
devos_query_cache_hit
devos_search_total
devos_search_duration
devos_search_errors
devos_index_documents
devos_index_failures

132. Database Index Definition

Resource Schema：

interface IndexDefinition {
  name: string

  fields: string[]

  unique?: boolean

  type?:
    | 'btree'
    | 'gin'
    | 'gist'
    | 'hash'

  where?: string
}

禁止 Plugin 在 Runtime：

CREATE INDEX

Schema Migration 才能修改数据库结构。

133. Migration Integration

结合：

12_MIGRATION_VERSIONING_COMPATIBILITY.md

新增 Index：

Migration

删除 Index：

Migration

修改 Schema：

Migration

134. Schema Registry

统一：

interface SchemaRegistry {
  register(
    schema: ResourceSchema
  ): void

  get(
    resource: string,
    version?: string
  ): ResourceSchema

  list(): ResourceSchema[]

  validate(
    resource: string,
    data: unknown
  ): ValidationResult
}

135. Schema Versioning

Resource：

seo.website

Schema：

1.0
1.1
2.0

结合：

12_MIGRATION_VERSIONING_COMPATIBILITY.md

数据迁移必须可追踪。

136. API Schema

Resource Schema 应自动生成：

REST schema
OpenAPI schema
MCP schema
Agent tool schema
UI schema
TypeScript types

减少重复定义。

137. Single Source of Truth

最终：

Resource Schema
       │
 ┌─────┼─────┬─────┬─────┐
 │     │     │     │     │
API   UI    MCP   Agent  DB

不要：

API schema
UI schema
MCP schema
Agent schema
DB schema

分别维护。

138. Query Schema Generation

Resource Schema 自动生成：

Filter Fields
Sort Fields
Search Fields
Selectable Fields
Relation Fields

这样 Generic UI 可以直接使用。

139. Plugin Example

Plugin：

seo

seo.website
seo.article
seo.backlink

每个 Resource：

Schema
Actions
Relations
Search
Indexes
UI metadata

安装后自动进入：

Resource Registry
Query Runtime
Search Runtime
Action Runtime
UI
Agent Capability Registry

140. SEO Example

用户：

找出 DR > 50
且最近 30 天没有发布文章的网站

Agent：

Goal
 ↓
Capability Discovery
 ↓
seo.website.search
 ↓
Query
 ↓
Filter

最终：

DR > 50
AND
lastArticleAt < now - 30d

而不是：

Agent
 ↓
读取所有网站
 ↓
自己计算

141. Natural Language Query

未来支持：

“找出过去一周失败最多的 Worker”

转换：

Natural Language
 ↓
Query Planner
 ↓
Resource
 ↓
Fields
 ↓
Filters
 ↓
Aggregates
 ↓
Query Runtime

但是：

LLM generated query

必须经过：

Schema Validation
Permission
Scope
Cost Check

142. Query Planner

可以定义：

interface QueryPlan {
  resource: string

  query: QueryInput

  explanation?: string

  estimatedCost?: QueryCost
}

Agent 生成：

QueryPlan

Runtime 验证后执行。

143. Query Planner Safety

LLM 不能生成：

DROP TABLE

也不能：

raw SQL

只能生成：

QueryInput

144. Search Planner

同样：

interface SearchPlan {
  resource: string

  input: SearchInput

  estimatedCost?: number
}

145. Query Result

统一：

interface QueryResult<T> {
  items: T[]

  pagination?: PaginationResult

  total?: number

  aggregates?: Record<string, number>

  metadata?: Record<string, unknown>
}

146. Search Result

interface SearchResult<T> {
  items: SearchItem<T>[]

  nextCursor?: string

  total?: number

  tookMs: number
}

interface SearchItem<T> {
  item: T

  score?: number

  highlights?: Record<string, string[]>
}

147. Query Errors

统一错误：

invalid_filter
invalid_field
invalid_sort
forbidden_field
forbidden_resource
scope_violation
query_timeout
query_too_expensive
provider_unavailable

148. Search Errors

invalid_query
unsupported_mode
index_unavailable
provider_unavailable
search_timeout
search_budget_exceeded

149. CLI

增加：

devos data resources

devos data schema seo.website

devos data query seo.website

devos data count seo.website

devos data export seo.website

devos search "AI SEO"

devos search "AI SEO" --resource seo.website

devos index list

devos index rebuild seo.website

devos index health

150. UI

DevOS 应提供：

Resource Explorer

例如：

Resources
├── Core
│   ├── Users
│   ├── Organizations
│   ├── Tasks
│   ├── Jobs
│   └── Executions
│
└── Plugins
    └── SEO
        ├── Websites
        ├── Articles
        └── Backlinks

151. Resource Explorer

统一页面：

List
 ├── Search
 ├── Filter
 ├── Sort
 ├── Columns
 ├── Saved Views
 ├── Bulk Actions
 └── Export

152. Resource Detail

统一：

Overview
Relations
Activity
Events
Tasks
Executions
Artifacts

Plugin 可以增加：

SEO Analysis
Backlinks
AI Recommendations

153. Search UI

全局：

⌘K / Ctrl+K

输入：

AI SEO

Websites
Articles
Tasks
Plugins
Skills
Actions

按照：

relevance

排序。

154. Saved View

用户可以：

保存当前：
filter
sort
columns
search

例如：

Failed Tasks
High DR Websites
Production Deployments

155. Data Table Performance

必须支持：

server-side pagination
server-side sorting
server-side filtering
virtualization

禁止：

GET 100000 records
 ↓
browser filter

156. Bulk UI

Bulk Action：

Select
 ↓
Action
 ↓
Confirmation
 ↓
Task created
 ↓
Task Detail

不能长时间阻塞页面。

157. Import

未来提供：

core.import

支持：

CSV
JSON
JSONL
Excel

流程：

Upload Artifact
 ↓
Import Task
 ↓
Validate
 ↓
Preview
 ↓
Confirm
 ↓
Batch Jobs
 ↓
Actions

158. Import Validation

必须先：

dry-run

显示：

1000 rows
980 valid
15 warnings
5 errors

用户确认后：

execute

159. Import Security

Import 必须：

schema validation
field permission
scope validation
file size limit
row limit
rate limit

160. Data Runtime Package

packages/data/
├── data-runtime.ts
├── data-context.ts
├── repository.ts
├── data-provider.ts
├── query/
│   ├── query-runtime.ts
│   ├── query-schema.ts
│   ├── query-validator.ts
│   ├── query-planner.ts
│   ├── query-cost.ts
│   └── query-compiler.ts
├── filter/
├── pagination/
├── relation/
├── aggregate/
├── cache/
└── index.ts

161. Search Package

packages/search/
├── search-runtime.ts
├── search-provider.ts
├── search-schema.ts
├── search-planner.ts
├── ranking.ts
├── index-runtime.ts
├── index-registry.ts
├── embedding/
├── providers/
└── index.ts

162. Schema Package

packages/schema/
├── schema-registry.ts
├── resource-schema.ts
├── field-definition.ts
├── relation-definition.ts
├── index-definition.ts
├── validation.ts
└── index.ts

163. Cache Package

packages/cache/
├── cache-runtime.ts
├── cache-provider.ts
├── cache-key.ts
├── invalidation.ts
└── index.ts

164. Export Package

packages/export/
├── export-service.ts
├── csv.ts
├── json.ts
├── jsonl.ts
├── excel.ts
└── index.ts

165. Import Package

packages/import/
├── import-service.ts
├── parser.ts
├── validator.ts
├── preview.ts
├── importer.ts
└── index.ts

166. Database

第一阶段：

PostgreSQL

167. When To Add Search Engine

只有出现：

数据规模
搜索复杂度
性能要求

明确超过 PostgreSQL 能力时，再接：

OpenSearch
Elasticsearch
Meilisearch

Search Runtime 必须让切换 Provider 不影响上层。

168. Database Is Source of Truth

绝对原则：

PostgreSQL
    =
Source of Truth

Search Index
    =
Derived State

Cache
    =
Derived State

169. Data Runtime Integration

完整链：

Resource
 ↓
Schema
 ↓
Permission
 ↓
Scope
 ↓
Query Runtime
 ↓
Repository
 ↓
Data Provider
 ↓
PostgreSQL

Search：

Resource
 ↓
Schema
 ↓
Permission
 ↓
Scope
 ↓
Search Runtime
 ↓
Search Provider
 ↓
Index

170. Action Integration

写入：

Action
 ↓
Action Runtime
 ↓
Domain Logic
 ↓
Repository
 ↓
Transaction
 ↓
Database
 ↓
Outbox
 ↓
Event

171. Index Integration

Event
 ↓
Index Job
 ↓
Worker
 ↓
Search Runtime
 ↓
Search Provider

172. Agent Integration

Agent：

Goal
 ↓
Search / Query Capability
 ↓
QueryPlan / SearchPlan
 ↓
Runtime Validation
 ↓
Execution

Agent 不允许：

Database Access

173. MCP Integration

MCP：

MCP
 ↓
Capability
 ↓
Search / Query Action
 ↓
Data Runtime

禁止：

MCP → PostgreSQL

174. Plugin Integration

Plugin 只需要声明：

Resource Schema
Actions
Search Definition
Indexes
Relations

DevOS 自动获得：

Query
Search
Generic UI
Global Search
Agent Capability
MCP Exposure

175. Acceptance Criteria

Data

[ ] Data Runtime
[ ] Repository
[ ] Data Provider
[ ] Query Runtime
[ ] Filter
[ ] Sort
[ ] Pagination
[ ] Relations
[ ] Aggregate
[ ] Scope

Search

[ ] Search Runtime
[ ] Full Text
[ ] Semantic
[ ] Hybrid abstraction
[ ] Search Provider
[ ] Index Runtime
[ ] Incremental Index
[ ] Rebuild
[ ] Search Ranking

Security

[ ] Field permission
[ ] Row scope
[ ] Query authorization
[ ] Search authorization
[ ] Export authorization
[ ] Sensitive field masking

Performance

[ ] Query timeout
[ ] Query cost
[ ] Slow query detection
[ ] Cache
[ ] DataLoader
[ ] Batch
[ ] Cursor pagination

Integration

[ ] Resource Registry
[ ] Action Runtime
[ ] Task Runtime
[ ] Event Runtime
[ ] Agent Runtime
[ ] MCP Runtime
[ ] Plugin Runtime

176. Integration Tests

必须测试：

Resource
 ↓
Query
 ↓
Permission
 ↓
Scope
 ↓
Database

测试：

Org A cannot query Org B

User cannot query forbidden field

Invalid filter rejected

Invalid sort rejected

Large query rejected

Query timeout works

Cursor pagination works

Relations do not produce N+1

Aggregate respects permission

177. Search Tests

测试：

full text search
semantic search
hybrid search
ranking
filter
scope
permission
index rebuild
incremental index
index failure
index recovery
fallback

178. Agent Tests

测试：

Agent uses Query for structured requirement

Agent uses Search for semantic requirement

Agent cannot query unauthorized Resource

Agent cannot request forbidden fields

Agent cannot generate raw SQL

Agent respects search budget

Agent respects query limits

179. MCP Tests

测试：

MCP query
MCP search
MCP permission
MCP scope
MCP budget
MCP timeout
MCP cannot bypass Data Runtime

180. Plugin Tests

安装 Plugin：

Plugin
 ↓
Resource Schema
 ↓
Registry
 ↓
Query
 ↓
Search
 ↓
Generic UI
 ↓
Agent Capability

必须全部自动生效。

181. Zcode Implementation Rules

Rule 1

任何业务数据读取：

必须经过 Data Runtime

Rule 2

任何业务数据写入：

必须经过 Action Runtime

Rule 3

禁止：

UI → Prisma
Plugin → Prisma
Agent → Prisma
MCP → Prisma

Rule 4

禁止暴露：

raw SQL

给：

Agent
MCP
Plugin public API
REST client

Rule 5

所有 Query 必须执行：

Schema Validation
Permission
Scope
Cost Check
Timeout

Rule 6

所有 Search 必须执行：

Permission
Scope
Budget

Rule 7

Database 是：

Source of Truth

Search Index 和 Cache 都是：

Derived State

Rule 8

Index 更新必须通过：

Event
+
Task/Job
+
Worker

支持：

retry
resume
rebuild

Rule 9

大数据量操作必须：

Task
+
Job
+
Cursor

不能同步读取全部数据。

Rule 10

Resource Schema 必须成为：

Single Source of Truth

驱动：

Database
API
UI
MCP
Agent
Search

182. Golden Rule

DevOS 数据体系必须遵循：

Resource
   ↓
Schema
   ↓
Permission
   ↓
Scope
   ↓
Query / Search
   ↓
Data Runtime
   ↓
Provider
   ↓
Database / Index

写入：

Action
   ↓
Action Runtime
   ↓
Data Runtime
   ↓
Database
   ↓
Outbox
   ↓
Event
   ↓
Index / Cache / Plugin / Agent

最终形成：

                         Resource
                            │
                          Schema
                            │
                 ┌──────────┴──────────┐
                 │                     │
              Action                 Query
                 │                     │
          Action Runtime        Query Runtime
                 │                     │
                 │               ┌─────┴─────┐
                 │               │           │
                 │          Repository     Search
                 │               │           │
                 │               │      Search Runtime
                 │               │           │
                 └───────┬───────┘      Search Index
                         │
                      Database
                         │
                       Outbox
                         │
                       Event
                         │
              ┌──────────┼──────────┐
              │          │          │
            Cache      Index      Plugin
              │          │          │
              └──────────┼──────────┘
                         │
                       Agent

183. Final Principle

DevOS 不应该让每一个 Plugin 自己实现：

Pagination
Filter
Search
Permission Filter
Scope
Export
Import
Cache
Index
Relation
Query Builder
Data Table

这些应该全部成为：

DevOS Data Platform

于是一个新的业务 Plugin 只需要定义：

Resource Schema
+
Actions
+
Relations
+
Search Definition

DevOS 自动提供：

Database
Query
Search
Index
Permission
Scope
Pagination
Generic UI
Global Search
Agent Capability
MCP Capability
Export
Import
Cache
Audit
Observability

这才是真正意义上的：

Reusable Development OS

而不是：

一个拥有很多功能的 Backend Template

52 KiB Raw Blame History Unescape Escape

DevOS Data / Query / Search / Index Runtime

1. Goals

2. Core Principle

3. Resource

4. Data

5. Query

6. Search

7. Index

8. Architecture

9. Data Runtime

10. DataContext

11. Repository

12. Important Rule

13. Read vs Write

14. Query Input

15. Filter

16. Filter Operators

17. Filter Tree

18. Filter Schema

19. Security: Filter Fields

20. Field Types

21. Resource Schema

22. Resource Schema Example

23. Pagination

24. Offset Pagination

25. Cursor Pagination

26. Pagination Limits

27. Sort

28. Sort Security

29. Include

30. Relations

31. Relation Examples

32. Relation Permission

33. Query Authorization

34. Row-Level Security

35. Scope Provider

36. Scope Composition

37. Query Compilation

38. SQL Boundary

39. Raw SQL

40. Query Cost

41. Large Query

42. Data Export

43. Export Security

44. Search Runtime

45. Search Input

46. Search Modes

Full Text

Semantic

Hybrid

47. Search Provider

48. Search Provider Implementations

49. Search Index

50. Search Field

51. Search Document

52. Index Isolation

53. Search Permission

54. Search Flow

55. Search Ranking

56. Hybrid Ranking

57. Semantic Search

58. Agent Search

59. Capability Discovery Search

60. Search as Capability

61. Index Lifecycle

62. Index Resource

63. Index Actions

64. Rebuild

65. Incremental Index

66. Outbox

67. Index Consistency

68. Cache Runtime

69. Cache Rules

70. Cache Key

71. Query Cache Invalidation

72. Data Loader

73. Query Observability

74. Slow Query Detection

75. Query Timeout

52 KiB

Raw Blame History