maglev-rb 0.1.1 → 0.2.1

data/README.zh-CN.md

@@ -1,48 +1,93 @@
 # Maglev
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md)
 
 [![CI](https://github.com/benjis/maglev/actions/workflows/ci.yml/badge.svg)](https://github.com/benjis/maglev/actions/workflows/ci.yml)
-[![Ruby](https://img.shields.io/badge/Ruby-3.2%2B-CC342D.svg)](https://www.ruby-lang.org/)
+[![Ruby](https://img.shields.io/badge/Ruby-3.3%2B-CC342D.svg)](https://www.ruby-lang.org/)
 [![Rails](https://img.shields.io/badge/Rails-7.1%20%7C%208.0-D30001.svg)](https://rubyonrails.org/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
 
-**无需在 Rails 之外另建一套系统，也能让 Rails 模型拥有语义记忆。**
+Maglev 0.2 是面向 ActiveRecord 应用的 Rails 原生只读知识与查询层。应用可以通过三条明确路线回答自然语言问题：
 
-Maglev 是面向 ActiveRecord 对象图的 Rails 原生语义知识层。你只需声明领域模型中哪些信息适合被理解和检索，Maglev 就会把记录、关联关系、附件和富文本转换为可搜索的知识。它通过 Rails 原有的生命周期机制持续更新这些知识，并以熟悉的模型 API 提供语义搜索和有依据的问答能力。
+- **结构化查询：** 问题 → 经过验证的 Query IR → 可组合的
+  `ActiveRecord::Relation` 或有界聚合值。
+- **RAG：** 问题 → 经过授权的语义检索 → 可选的有据回答。
+- **混合查询：** 用两种固定流程之一组合结构化筛选与 RAG 证据。
+
+模型只暴露应用显式声明的 allowlist。结构化编译始终从调用方提供的 base relation 开始，并且只能继续收窄。RAG 检索与答案生成彼此独立。
 
 ```ruby
-Product.search("存在续航或易用性问题的笔记本电脑")
+resource_authorizer = ->(_entry, user) { user.account_id == current_account.id }
+result = current_account.invoices.maglev_request(
+  "金额超过 500 美元的未结发票",
+  mode: :structured,
+  planner_adapter: planner,
+  authorizer: resource_authorizer,
+  user: current_user
+)
 
-response = Product.ask("有哪些反复出现、值得调查的产品问题？", user: current_user)
-response.text
-response.sources # 支撑回答的 ActiveRecord 记录和内容分块
+retrieval = SupportTicket.retrieve("取消流程中受阻的客户", user: current_user)
+answer = SupportTicket.ask("反复出现了哪些取消问题？", user: current_user)
 ```
 
-Maglev 专注于检索增强生成（RAG）。ActiveRecord 仍然负责精确筛选、关联查询、报表和聚合；Maglev 则处理用自然语言提出的问题。
+## 从这里开始：先选择数据路径
+
+第一次使用 Maglev 时，不需要先理解完整架构。先判断问题需要哪种数据：
+
+| 用户问题 | 所需数据 | 声明 | 调用方式 |
+| --- | --- | --- | --- |
+| “有多少发票已经逾期？” | 精确字段、筛选、计数 | `queryable` | `maglev_request(..., mode: :structured)` |
+| “客户取消服务时主要抱怨什么？” | 正文、评论、附件等自由文本 | `knowledge` | `retrieve` 或 `ask` |
+| “哪些未关闭工单提到了重复扣款？” | 精确状态 + 语义文本 | 两者都声明 | `maglev_request(..., mode: :hybrid)` |
+
+只需要记住四件事：
+
+1. `maglev_resource :support_tickets` 给模型一个稳定的 Maglev 资源名。
+2. `queryable` 是结构化查询 allowlist：规划器只能筛选、排序、关联或聚合这里声明的内容。
+3. `knowledge` 选择哪些内容会变成可语义检索的证据。
+4. 授权仍由应用提供；结构化查询还必须从调用方的
+   `ActiveRecord::Relation` 开始。Maglev 不会自行扩大权限。
 
 ## 为什么选择 Maglev？
 
-- **Rails 原生：** 它是一个 gem 和 Railtie，而不是独立服务、Engine 或额外 API。
-- **模型驱动：** 在拥有数据的 ActiveRecord 模型旁直接声明知识边界。
-- **理解对象图：** 支持直接关联、`has_many :through` 和多态关联，并可显式限制深度与记录数。
-- **自动保持新鲜：** 已声明记录、直接关联、附件或 Action Text 内容发生变化后，自动重新索引知识所有者。
-- **回答有依据：** 仅根据检索到的上下文生成答案，并返回来源。
-- **面向生产环境：** 内置授权接口、内容限制、清洗、重试、可观测性和幂等重建索引。
-- **可扩展：** 可使用默认的 PostgreSQL/pgvector，也可实现精简的向量存储协议。
+- 普通 Ruby gem + `Maglev::Railtie`，不是 Rails Engine 或独立 API 服务。
+- ActiveRecord-first 结构化查询；不生成或执行不受限 SQL/Ruby。
+- 显式注册可查询字段、关联、scope、聚合和知识来源。
+- 由应用拥有的 relation 携带租户和授权约束。
+- 基于 pgvector 的来源感知 RAG，具有归一化相似度、确定性预算和可检查证据。
+- 不可变计划/结果和默认脱敏 trace。
+- 默认测试使用确定性 fake adapter，不调用线上模型服务。
 
-## 快速开始
+## 架构
 
-### 1. 安装前置依赖
+```mermaid
+flowchart TD
+  Q["问题 + 已注册范围"] --> R["路由器"]
+  R --> S["结构化规划器"]
+  R --> G["RAG 检索"]
+  R --> H["固定混合协调器"]
+  S --> I["不受信任的 Query IR"]
+  I --> V["确定性验证器"]
+  V --> C["在 base relation 上编译"]
+  C --> E["只读有界执行"]
+  G --> X["已授权语义证据"]
+  H --> E
+  H --> X
+  E --> O["证据 + Result"]
+  X --> O
+  O --> A["可选的有据答案"]
+  Q --> T["脱敏 trace"]
+```
 
-Maglev 需要 Ruby 3.2+、Rails 7.1 或 8.0、PostgreSQL，以及
-[`pgvector`](https://github.com/pgvector/pgvector) 扩展。
+Registry 是权限边界。一次请求的 schema snapshot 只包含已注册且已授权的资源，绝不包含记录值。Provider 输出在通过确定性验证前一律不受信任。
 
-将 Maglev 加入应用：
+## 安装
+
+Maglev 需要 Ruby 3.3+、Rails 7.1 或 8.0、PostgreSQL 和 pgvector。
 
 ```ruby
 # Gemfile
-gem "maglev-rb"
+gem "maglev-rb", "~> 0.2.1"
 ```
 
 ```bash
@@ -51,358 +96,520 @@ bin/rails generate maglev:install --embedding-dimensions=1536
 bin/rails db:migrate
 ```
 
-生成器会把 `--embedding-dimensions` 同时写入 `config/initializers/maglev.rb` 和 `maglev_chunks` 的向量列，并创建基于余弦距离的 HNSW 索引。
+Generator 会创建 initializer、`maglev_chunks`、来源/租户元数据、HNSW 余弦索引和 `maglev_index_states` 诊断表。Owner 使用 UUID 主键时请检查并调整生成的迁移。
+
+## 配置
 
-### 2. 配置模型提供商
+内置 embedding 和 generation 客户端使用 OpenAI-compatible HTTP 协议。Planner 默认使用 OpenAI 的 `json_schema` response format；不支持该能力的服务商可以改用约束较弱的 `json_object` format。Embedding 与 generation 可以使用不同服务商。
 
 ```ruby
-# config/initializers/maglev.rb
 Maglev.configure do |config|
   config.embedding_provider do |provider|
-    provider.url = "http://localhost:11434/v1"
-    provider.api_key = ENV["LOCAL_EMBEDDING_API_KEY"]
-    provider.model = "Qwen3-Embedding-0.6B-8bit"
-    provider.dimensions = 1024
+    provider.url = ENV.fetch("MAGLEV_EMBEDDING_URL", "https://api.openai.com/v1")
+    provider.api_key = ENV["MAGLEV_EMBEDDING_API_KEY"]
+    provider.model = "text-embedding-3-small"
+    provider.dimensions = 1536
   end
 
   config.generation_provider do |provider|
-    provider.url = "https://api.deepseek.com/v1"
-    provider.api_key = Rails.application.credentials.dig(:deepseek_api_key)
-    provider.model = "deepseek-chat"
+    provider.url = ENV.fetch("MAGLEV_GENERATION_URL", "https://api.openai.com/v1")
+    provider.api_key = ENV["MAGLEV_GENERATION_API_KEY"]
+    provider.model = "gpt-4.1-mini"
   end
 
+  config.planner_adapter = Maglev::Adapters::FaradayPlanner.new
+  # 用于不支持 json_schema 的服务商：
+  # config.planner_adapter = Maglev::Adapters::FaradayPlanner.new(response_format: :json_object)
+  config.routing_adapter = MyRoutingAdapter.new # 仅 mode: :auto 需要
+
   config.chunk_size = 1000
+  config.minimum_similarity = nil
+  config.retrieval_max_candidates = 1000
+  config.context_max_characters = 4000
+  config.context_per_owner_characters = 1200
+
+  config.snapshot_attribute_max_characters = 20_000
+  config.snapshot_related_record_max_characters = 50_000
+  config.snapshot_max_characters = 100_000
+  config.snapshot_max_chunks = 100
+
+  config.structured_query_timeout = 5
+  config.structured_evidence_max_rows = 100
+  config.structured_evidence_max_bytes = 32_768
 end
 ```
 
-Embedding 与 generation endpoint 相互独立，可以使用不同的 URL、API key 和 model。默认 provider bridge 使用 OpenAI-compatible HTTP endpoint；其他协议仍可通过 Maglev 自定义 adapter 接入。
+若内置协议不适用，可以注入自定义 `embedding_adapter`、`generation_adapter`、`planner_adapter`、`routing_adapter`、`attachment_extractor` 或 `authorization_adapter`。
+
+## 注册资源
 
-对于已有安装，请同时修改配置维度和数据库向量列。Maglev 会在请求 embedding 前检查两者是否一致。
+`maglev_resource` 是 v0.2 的主要 DSL。结构化查询能力与知识能力彼此独立，可以同时声明，也可以只声明一种。
 
-### 3. 声明模型知识
+### 一个带完整注释的结构化资源
 
 ```ruby
-class Product < ApplicationRecord
-  has_many :reviews, inverse_of: :product
-  has_many :product_categories, inverse_of: :product
-  has_many :categories, through: :product_categories
-  has_many_attached :images
-  has_rich_text :description
-
-  has_knowledge do
-    expose :name, :sku, :price, :status
-    tags :product
-
-    include_related :reviews, depth: 1, limit: 10
-    include_related :categories, depth: 1, limit: 10, inverse: :products
-
-    expose_attached :images
-    expose_rich_text :description
+class Invoice < ApplicationRecord
+  # Rails 关联和 scope 仍然是业务逻辑的事实来源。
+  belongs_to :account
+  scope :due_before, ->(date) { where(due_on: ..date) }
+
+  # :invoices 是 Maglev plan/request 使用的稳定资源标识符。
+  maglev_resource :invoices do
+    # 帮助 planner 理解这个资源代表什么。
+    description "属于已授权账户的发票"
+    synonyms "bills"
+
+    # 这个 block 只控制结构化 ActiveRecord 查询。
+    queryable do
+      # 允许对这些真实数据库字段执行精确筛选和排序。
+      # enum 同时限定 planner 可以使用的状态值。
+      field :status, enum: %w[draft open paid void]
+      field :amount, description: "以账户币种表示的发票总额"
+      field :due_on, synonyms: ["deadline", "截止日期"]
+      field :paid_at
+
+      # 即使 planner 请求，也明确禁止这些敏感字段。
+      prohibit :number, :internal_note
+
+      # 允许通过已注册关联连接到另一个 :accounts 资源。
+      association :account, resource: :accounts
+
+      # 允许调用这个已有 Rails scope，并定义其参数类型。
+      scope :due_before,
+        parameters: {date: {type: :date, required: true}}
+
+      # 只开放这些聚合函数和字段。
+      aggregates count: true, sum: [:amount], average: [:amount]
+
+      # 资源级上限，会与全局/请求级限制取最严格值。
+      limits rows: 50, operations: 8, joins: 1
+
+      # 每次结构化规划都必须由调用方授权该资源。
+      authorization :required
+    end
+
+    # 这个独立 block 控制语义索引和 RAG。
+    # 字段在这里重复出现，不会扩大结构化查询权限。
+    knowledge do
+      expose :status, :amount, :due_on, :paid_at
+    end
   end
 end
+```
 
-class Review < ApplicationRecord
-  belongs_to :product, inverse_of: :reviews
+Maglev 不会隐式暴露任何内容。`authorization :required` 表示：除非调用方明确授权，否则该资源不会进入请求的 schema snapshot。`allow_unscoped_model_queries` 必须显式启用，且只应供真正公开的数据使用。
 
-  has_knowledge do
-    expose :rating, :title, :body
-  end
-end
-```
+`queryable` 只定义受约束的 ActiveRecord 查询契约；`knowledge` 只定义 RAG
+索引和检索来源；`maglev_resource` 是统一资源声明，可以只包含其中一个 block，
+也可以同时包含两者。未声明 `knowledge` 的模型不能使用 `search`、`retrieve`、
+`ask`、snapshot 或索引 callback。
 
-只有显式公开的字段和内容源才会进入 Maglev 的知识快照。关联的 `limit` 限制每个关联包含的记录数；`depth` 限制关联跳数：`depth: 1` 会包含直接关联记录，但不会继续展开该记录的关联。`config.max_relation_depth` 是每个快照从根记录到叶记录的全局硬上限。每个关联模型独立声明自己的公开知识，因此连接模型中的敏感字段不会被意外展开。
+请把声明理解为 allowlist，而不是数据库 schema 的复制。未出现在 `field` 中的列
+不能进入 Query IR；未出现在 `expose` 或其他 knowledge source 中的值不会进入语义
+snapshot。
 
-### 4. 为已有记录建立索引
+### 为什么一个字段可以同时出现在两个 block 中
 
-新建和更新记录时会自动将 `Maglev::ReindexJob` 加入队列。安装后可执行一次已有数据回填：
+同一字段可以承担两种不同职责：
 
-```bash
-bin/rails maglev:reindex[Product]
-# 或重建所有声明了 has_knowledge 的模型
-bin/rails maglev:reindex_all
-```
+- `field :status` 允许结构化查询生成 `status = "open"` 这样的精确条件。
+- `expose :status` 会把 `status: open` 写入索引 snapshot，让检索证据保留上下文。
 
-请确保生产环境中的 Active Job 后端正在运行。
+声明一边不会自动声明另一边。标识符、日期、枚举和金额适合放入 `queryable`；
+描述、正文、评论、解决记录和附件文本适合放入 `knowledge`；状态、优先级、产品区域
+这类上下文字段则经常需要同时声明。
 
-### 5. 搜索与提问
+### 一个真正体现 RAG 价值的资源
 
-```ruby
-results = Product.search(
-  "存在续航或易用性问题的笔记本电脑",
-  limit: 10,
-  user: current_user
-)
+当答案存在于人写的语言中，而不是某个精确列里时，RAG 才真正有价值。下面的结构化
+查询可以找出 open/high-priority 工单，而 RAG 可以从工单正文、评论、解决记录和日志
+附件中理解“重复扣款”这类不同措辞。
 
-results.each do |result|
-  result.owner       # => Product
-  result.content     # 检索到的快照分块
-  result.source      # => "snapshot"
-  result.distance    # 余弦距离，越小越接近
-  result.similarity  # 归一化后的便捷相似度分数
+```ruby
+class SupportTicket < ApplicationRecord
+  belongs_to :account
+  has_many :comments
+  has_many_attached :files
+  has_rich_text :resolution
+
+  maglev_resource :support_tickets do
+    description "客户支持请求及其调查证据"
+
+    queryable do
+      # 适合结构化查询：精确、有类型、便于筛选。
+      field :status, enum: %w[open pending resolved closed]
+      field :priority, enum: %w[low normal high urgent]
+      field :product_area
+      field :created_at
+      prohibit :requester_email, :internal_notes
+      limits rows: 100, operations: 8, joins: 1
+      authorization :required
+    end
+
+    knowledge do
+      # 正文包含精确筛选无法表达的语义。
+      expose :subject, :body
+
+      # 与 queryable 重叠，使证据保留业务上下文。
+      expose :status, :priority, :product_area
+
+      # 只纳入数量和顺序都确定的关联对话。
+      include_related :comments, depth: 1, limit: 20,
+        order: {created_at: :desc}
+
+      # 纳入受支持的附件文本和 Action Text 内容。
+      expose_attached :files
+      expose_rich_text :resolution
+    end
+  end
 end
 ```
 
-根据检索到的记录生成有依据的回答：
+被 `include_related` 使用的关联模型也必须声明自己的
+`maglev_resource ... knowledge`。只需要 RAG 时省略 `queryable`；只需要结构化查询时
+省略 `knowledge`。
+
+记录完成索引后，下面三个调用解决不同问题：
 
 ```ruby
-response = Product.ask(
-  "商品团队应调查哪些反复出现的产品问题？",
+# 只返回语义证据，不调用 generation provider。
+evidence = SupportTicket.retrieve(
+  "客户说取消服务后仍被重复扣款",
+  limit: 10,
+  user: current_user
+)
+
+# 根据选中的工单证据生成有据可查的自然语言回答。
+answer = SupportTicket.ask(
+  "取消服务后反复出现了哪些重复扣款模式？",
   limit: 5,
   user: current_user
 )
 
-response.text
-response.sources # 所有者、分块、距离和实际检索到的内容
-response.metadata
+# 先按数据库字段精确筛选，再只在结果集合中做语义检索。
+result = current_account.support_tickets.maglev_request(
+  "客户描述被重复扣款的未关闭紧急工单",
+  mode: :hybrid,
+  hybrid_plan: :structured_first,
+  planner_adapter: planner,
+  authorizer: resource_authorizer,
+  user: current_user
+)
 ```
 
-例如，回答可能根据检索到的评价内容，总结出风扇噪音、触控板偶尔失灵以及实际续航低于宣传值。应把它理解为对“已检索上下文”的总结，而不是对全部产品做出的数据库聚合；每项结论都应通过 `response.sources` 展示依据。
+默认附件提取器支持纯文本、Markdown、HTML 和 XHTML。PDF、Office、OCR、图片、音视频解析需要应用自定义 extractor。Snapshot、relation、附件和 chunk 都有硬预算。
 
-实例级问题会限定在单个知识所有者内：
+无需调用 provider 即可检查暴露内容：
 
 ```ruby
-product.ask("总结这款产品被反馈的优点和缺点。", user: current_user)
+SupportTicket.maglev_schema
+ticket.maglev_snapshot
+ticket.maglev_context_preview(question: "为什么还未解决？")
+ticket.maglev_index_status
 ```
 
-Rails 数据变化时，Maglev 还会沿已声明的关联更新知识。将评价移动到另一款产品后，事务提交会为原产品和新产品安排重新索引，使两边的可搜索知识保持最新：
+### DSL API 参考
 
-```ruby
-review.update!(product: replacement_product)
-# 两个受影响的产品都会加入 Maglev::ReindexJob 队列。
-```
+资源级 DSL：
 
-如果没有检索到可用上下文，Maglev 会返回确定性的“上下文不足”响应，而不会让模型自行猜测。
+| DSL | 用途 |
+| --- | --- |
+| `maglev_resource :identifier` | 为模型注册一个稳定的资源标识符。 |
+| `description "..."` | 提供给 planner 的资源说明；不会包含记录值。 |
+| `synonyms "...", "..."` | 资源可能使用的其他名称。 |
+| `queryable { ... }` | 声明结构化 ActiveRecord 能力；只能出现一次。 |
+| `knowledge { ... }` | 声明 RAG/索引能力；只能出现一次。 |
 
-## 工作原理
+`queryable` DSL：
 
-```mermaid
-flowchart LR
-  A["ActiveRecord 对象图"] --> B["显式知识结构"]
-  B --> C["有边界且已清洗的快照"]
-  C --> D["分块 + 嵌入"]
-  D --> E["向量存储<br/>默认 pgvector"]
-  Q["search / ask"] --> F["语义检索"]
-  E --> F
-  F --> G["上下文组装"]
-  G --> H["基于上下文生成"]
-  H --> I["回答 + 来源"]
-  J["Rails 提交与内容变化"] --> K["Active Job 重建索引"]
-  K --> C
-```
+| DSL | 用途与选项 |
+| --- | --- |
+| `field :name` | 允许一个真实字段。选项：`description:`、`synonyms:`、`enum:`、`sensitive:`。敏感字段不会进入 planner schema。 |
+| `prohibit :a, :b` | 明确禁止真实字段；同一字段不能既允许又禁止。 |
+| `association :account, resource: :accounts` | 允许一个已注册 ActiveRecord 关联路径。支持 `description:`、`synonyms:`；目标资源也必须注册。 |
+| `scope :due_before, parameters: {...}` | 允许一个已有 model scope。参数 metadata 支持 `type`、`required`、`nullable`、`enum_values`、`minimum`、`maximum`。其他 scope 不能调用。 |
+| `aggregates count: true, sum: [:amount]` | 允许 `count`、`sum`、`average`、`minimum`、`maximum`；字段列表进一步限制聚合目标。 |
+| `limits rows:, operations:, joins:` | 设置正整数资源上限；最终使用所有配置中最严格的限制。 |
+| `authorization :required` | 默认值。只有 `authorizer` 批准后，资源才进入 schema snapshot。 |
+| `authorization :public` | 资源 schema 公开；记录访问仍受传入 relation 约束。 |
+| `allow_unscoped_model_queries true` | 允许没有 base relation 的结构化请求。默认关闭，只应用于真正公开的数据。 |
+
+Scope 参数 `type` 支持 `:string`、`:integer`、`:float`、`:decimal`、
+`:boolean`、`:date`、`:datetime`、`:timestamp` 和 `:time`。注册资源时会拒绝不支持的类型。
 
-1. `has_knowledge` 为模型及其声明的关联编译一份显式知识结构。
-2. Maglev 根据允许的属性、关联记录、附件、富文本和标签生成确定性的文本快照。
-3. 快照被拆成大小受限的分块，并通过配置的适配器生成嵌入向量。
-4. 分块被写入向量存储；默认存储使用 PostgreSQL 和 pgvector。
-5. `search` 为查询生成嵌入，并执行基于余弦距离的近邻检索。
-6. `ask` 在上下文预算内组装分块，构建有依据的提示词，并返回包含来源元数据的答案。
-7. Rails 回调会沿对象图传播已声明记录的变化，并为受影响的所有者安排重新索引。
+`knowledge` DSL：
 
-Maglev 不会复制你的关系数据模型。向量文档会指回对应的 ActiveRecord 所有者；事务、业务规则和结构化查询仍由应用负责。
+| DSL | 用途与选项 |
+| --- | --- |
+| `expose :subject, :body` | 把指定的非 nil 模型字段加入可搜索 snapshot。 |
+| `hide :internal_notes` | 明确记录不得暴露的字段；同一字段不能同时 expose 和 hide。 |
+| `tags :support, :customer` | 给该模型的每个 snapshot 添加固定分类标签。 |
+| `include_related :comments, depth:, limit:` | 加入有界关联记录 snapshot。`inverse:` 可指定不明显的反向关联；`order:` 接受字段或 `{field: :asc/:desc}`。 |
+| `expose_attached :files` | 加入指定 Active Storage 附件中提取出的文本。 |
+| `expose_rich_text :resolution` | 加入指定 Action Text 字段的纯文本。 |
 
-## 知识来源
+Maglev 不会根据数据库可见性自动推断权限。DSL 会在注册时验证；未知字段、关联、
+scope 或附件会立即抛出 `Maglev::ConfigurationError`。
 
-### ActiveRecord 对象图
+## 结构化查询
 
-`include_related` 支持对普通关联、`has_many :through` 和多态关联进行有限遍历。当 Maglev 无法自动推断关联模型的变化应如何找到知识所有者时，可使用 `inverse:` 显式指定反向关联。
+规划与执行刻意分离。
 
 ```ruby
-has_knowledge do
-  include_related :tickets, depth: 2, limit: 25
-  include_related :events, depth: 1, limit: 20, inverse: :eventable
-end
+base = current_account.invoices.where(archived: false)
+
+plan = Maglev.plan(
+  "本月到期、金额超过 500 美元的未结发票",
+  resource: :invoices,
+  base_relation: base,
+  authorizer: ->(entry, user) { user.account_id == current_account.id },
+  user: current_user,
+  constraints: {rows: 25, operations: 8, joins: 1},
+  adapter: planner
+)
+
+plan.status                # :ready / :clarification_required / :unsupported / :invalid
+plan.ir                    # ready 时为不可变 Maglev::QueryIR::Query
+plan.explanation
+plan.policy_limits         # 实际生效的 rows/operations/joins/complexity
+plan.evidence_requirements
+plan.trace_id
+
+result = Maglev.execute(plan)
+result.status              # :succeeded
+result.kind                # :relation 或 :aggregate
+result.value               # 受保护的 relation 或有界 scalar
+result.evidence
+result.render
 ```
 
-当关联记录从一个所有者转移到另一个所有者时，Maglev 会同时重新索引旧所有者和新所有者。
+记录 relation 在读取前保持 lazy 和可组合。读取发生在带 `statement_timeout` 的 PostgreSQL 只读事务中；返回记录只读，批量写操作会被拒绝。
+
+Query IR v1 支持已注册 scope；`eq`、`not_eq`、`gt`、`gte`、`lt`、`lte`、`in`、`not_in`、`is_null`、`is_not_null`、`between`；最多两层 join；sort、distinct、limit；以及 count、sum、average、minimum、maximum。它不能包含 SQL、Arel、Ruby、任意方法、写操作、锁、嵌套布尔组、窗口函数、子查询、`HAVING` 或规划器自定义工具。
 
-创建、删除或重新分配连接记录会改变 `has_many :through` 关系，但不会改变关联记录本身。此类连接模型变更后，请在应用中显式加入或执行所有者重新索引。
+## RAG：search、retrieve 与 ask
 
-### Active Storage 与 Action Text
+知识资源仍然可以直接使用模型 API。
 
 ```ruby
-has_knowledge do
-  expose_attached :contracts, :brief
-  expose_rich_text :notes
-end
+matches = SupportTicket.search(
+  "取消流程故障",
+  limit: 10,
+  minimum_similarity: 0.65,
+  user: current_user
+)
+
+matches.first.owner
+matches.first.source_identity
+matches.first.source_type
+matches.first.similarity
 ```
 
-HTML 和 Action Text 内容会在索引前进行清洗。附件会受到内容类型、字节大小和提取字符数限制。已声明附件和富文本的变化会触发所有者重新索引。
+`search` 每个 owner 最多返回一个 `SearchResult`。需要完整、无生成的检索诊断时使用 `retrieve`：
+
+```ruby
+retrieval = SupportTicket.retrieve(
+  "取消流程故障",
+  limit: 10,
+  chunks_per_owner: 2,
+  user: current_user
+)
 
-### 在索引前检查内容
+retrieval.considered
+retrieval.selected
+retrieval.rejected
+retrieval.context
+retrieval.budgets
+retrieval.reasons
+retrieval.timings
+retrieval.trace_id
+```
 
-以下开发者 API 可用于确认模型实际公开的内容，且不会调用嵌入或生成服务：
+只有需要自然语言答案时才调用生成：
 
 ```ruby
-Customer.maglev_schema
-customer.maglev_snapshot
-
-preview = customer.maglev_context_preview(
-  question: "为什么这位客户存在风险？"
+answer = SupportTicket.ask(
+  "哪些取消故障反复出现？",
+  limit: 5,
+  chunks_per_owner: 2,
+  minimum_similarity: 0.65,
+  user: current_user
 )
-preview.text
-preview.metadata # 包含 provider_calls: 0
+
+answer.text
+answer.sources
+answer.metadata
 ```
 
-## 授权
+若授权、相似度或上下文预算过滤掉全部证据，`ask` 会返回确定性的 insufficient context，且不调用 generation provider。
 
-Maglev 不绑定特定的策略库。你可以配置一个简单适配器，在检索和回答时应用应用自身的授权规则：
+## 统一请求与路由
 
-```ruby
-class MaglevAuthorization
-  def scope(model:, user:)
-    model.accessible_by(user)
-  end
+需要统一 Result envelope 或路线选择时，使用 `Maglev.request`、`Model.maglev_request` 或 `relation.maglev_request`。
 
-  def authorize(record:, user:)
-    record.account_id == user.account_id
-  end
-end
+```ruby
+result = current_account.invoices.maglev_request(
+  "有多少未结发票已经逾期？",
+  mode: :structured,
+  planner_adapter: planner,
+  authorizer: resource_authorizer,
+  user: current_user
+)
 
-Maglev.configure do |config|
-  config.authorization_adapter = MaglevAuthorization.new
-end
+result.status
+result.route
+result.kind
+result.value
+result.evidence
+result.warnings
+result.trace_id
+result.confidence
+result.reasons
+result.metadata
 ```
 
-适配器必须实现：
+Mode 包括 `:structured`、`:rag`、`:hybrid`、`:auto`。显式 mode 永不调用路由 classifier。自动路由需要 `routing_adapter`，并且只会收到有界 capability summary，不会收到记录值或来源正文。应用级请求必须提供 resources/models 或 base relation；Maglev 永远不会扫描所有应用模型。
 
-- `scope(model:, user:)`：返回该用户可见的记录。
-- `authorize(record:, user:)`：返回 `false` 时拒绝访问记录。
+Routing adapter 实现 `classify(question:, capabilities:)`，并返回例如
+`{"route" => "structured", "confidence" => 0.9, "reasons" => ["exact fields"]}`
+的结果。Confidence 仅供参考，绝不授予权限。
 
-如果未配置适配器，默认允许访问所有记录。凡是需要限定检索范围的调用，都应一致地传入 `user:`。
+通过统一 API 获得生成式 RAG 答案时传入 `answer: true`；否则 RAG 路线返回 `kind: :semantic_matches`。
 
-`customer.explain` 是面向无需用户级授权场景的便捷 API；需要用户上下文时，请使用 `customer.ask(Maglev.configuration.explain_question, user: current_user)`。授权作用域适用于默认 pgvector 检索路径。将直接 `search` 调用与自定义存储结合前，请阅读[向量存储](#向量存储)。
+## 混合流程
 
-## 配置
+Hybrid 只支持两种固定 shape，并要求一个同时声明 queryable 与 knowledge 的资源。
 
 ```ruby
-Maglev.configure do |config|
-  config.embedding_provider do |provider|
-    provider.url = ENV.fetch("MAGLEV_EMBEDDING_URL", "https://api.openai.com/v1")
-    provider.api_key = ENV["MAGLEV_EMBEDDING_API_KEY"]
-    provider.model = "text-embedding-3-small"
-    provider.dimensions = 1536
-  end
-
-  config.generation_provider do |provider|
-    provider.url = ENV.fetch("MAGLEV_GENERATION_URL", "https://api.openai.com/v1")
-    provider.api_key = ENV["MAGLEV_GENERATION_API_KEY"]
-    provider.model = "gpt-4.1-mini"
-  end
-
-  config.chunk_size = 1000
+result = current_account.support_tickets.maglev_request(
+  "提到取消问题的未结工单",
+  mode: :hybrid,
+  hybrid_plan: :structured_first, # 或 :rag_first
+  planner_adapter: planner,
+  authorizer: resource_authorizer,
+  candidate_limit: 100,
+  user: current_user
+)
 
-  config.context_max_characters = 4000
-  config.context_per_owner_characters = 1200
-  config.max_relation_depth = 3
-
-  config.attachment_allowed_content_types = [
-    "text/plain",
-    "text/markdown",
-    "text/html"
-  ]
-  config.attachment_max_bytes = 5 * 1024 * 1024
-  config.attachment_max_characters = 20_000
-
-  config.provider_max_attempts = 2
-  config.provider_timeout = 30
-  config.logger = Rails.logger
-end
+result.kind                      # :hybrid_answer
+result.value.records
+result.evidence                  # 带 structured/RAG provenance
+result.metadata[:plan_shape]
+result.metadata[:operations]
 ```
 
-`provider_timeout` 对每次 provider 尝试分别生效。超时会被视为可重试错误，并计入 `provider_max_attempts`。
-
-当应用需要不同的模型提供商或策略行为时，可注入自定义的 `embedding_adapter`、`generation_adapter`、`attachment_extractor`、`authorization_adapter` 或 `source_redactor`。测试环境可以使用确定性适配器，全程不发起网络请求。
+Structured-first 先筛选记录，再在候选中检索；RAG-first 先检索 owner，再通过授权 relation 验证。候选项只传递有界且经过类型转换的主键；每个阶段都会重新应用注册、租户、base relation 和授权约束。系统不会循环或自主调用工具。
 
-## 向量存储
+## 授权与租户
 
-PostgreSQL 与 pgvector 是默认的生产环境方案。对于需要其他存储后端的应用，Maglev 也提供了精简的协议：
+Base relation 是 structured 和 hybrid 的权限边界：
 
 ```ruby
-class MyVectorStore < Maglev::VectorStores::Base
-  def upsert(documents:)
-    # 使用 document.id 持久化或替换文档
-  end
-
-  def search(vector:, filters:, limit:)
-    # 返回最近的 Maglev::VectorStores::Document 对象
-  end
-
-  def delete(ids:)
-    # 删除具有这些稳定 ID 的文档
-  end
+current_account.invoices.maglev_request(
+  question, mode: :structured, authorizer: resource_authorizer, user: current_user
+)
+policy_scope(Invoice).maglev_request(
+  question, mode: :structured, authorizer: resource_authorizer, user: current_user
+) # Pundit
+Invoice.accessible_by(current_ability).maglev_request(
+  question, mode: :structured, authorizer: resource_authorizer, user: current_user
+) # CanCanCan
+```
 
-  def delete_by_owner(owner_type:, owner_id:)
-    # 删除属于该所有者的所有文档
-  end
+RAG 授权使用可选 adapter：
 
-  def healthcheck = :ok
-  def capabilities = {metadata_filtering: true}
+```ruby
+class MaglevAuthorization
+  def scope(model:, user:) = model.where(account_id: user.account_id)
+  def authorize(record:, user:) = record.account_id == user.account_id
 end
 
 Maglev.configure do |config|
-  config.vector_store = MyVectorStore.new
+  config.authorization_adapter = MaglevAuthorization.new
+  config.tenant_id_resolver = lambda do |record: nil, user: nil|
+    (record || user)&.account_id&.to_s
+  end
 end
 ```
 
-`Maglev::VectorStores::Memory` 适合测试和本地实验。自定义存储应保留文档元数据筛选能力和稳定的文档标识语义。
+没有 RAG authorization adapter 时，默认允许所有记录。所有用户范围内的检索都应配置 adapter 并传入 `user:`。
 
-自定义向量存储目前会收到模型和所有者元数据筛选条件，但不会收到已配置的授权作用域。`ask` 仍会逐条授权检索到的所有者；使用自定义存储时，不能将直接 `search(..., user:)` 视为已按授权过滤。需要时请在自定义存储内部应用租户或策略筛选；如果搜索必须遵守授权作用域，请使用默认 pgvector 路径。
+存储支持时会下推授权过滤；hydrate 后仍会重新检查每条记录。授权 scope 超过 1,000 个 owner ID 时会 fail closed。
 
-## 运维与可观测性
+## 索引、升级与运维
 
 ```bash
 bin/rails maglev:status
-bin/rails maglev:reindex[Customer]
+bin/rails maglev:reindex[SupportTicket]
 bin/rails maglev:reindex_all
+bin/rails maglev:evaluate_planner
 ```
 
-重建索引可安全重复执行：未变化的分块会被复用，过期分块会被删除。Maglev 会为索引开始/成功/失败、检索、生成和提供商重试发出 ActiveSupport 通知：
+相关事务提交后 callback 会入队 `Maglev::ReindexJob`。索引操作幂等、复用未变化 chunk、原子替换单个 owner 的完整可搜索代际，并记录安全的状态和失败诊断。
 
-```ruby
-ActiveSupport::Notifications.subscribe(/\Amaglev\./) do |name, start, finish, id, payload|
-  Rails.logger.info(
-    event: name,
-    duration_ms: ((finish - start) * 1000).round(1),
-    **payload
-  )
-end
+从 0.1.x 升级请遵循 [CHANGELOG.md](CHANGELOG.md)：
+
+```bash
+bin/rails generate maglev:upgrade_index_version
+bin/rails generate maglev:upgrade_source_identity
+bin/rails db:migrate
+bin/rails maglev:reindex_all
 ```
 
-## 安全与能力边界
+请检查生成的迁移。Embedding 维度变化时需要单独修改 vector 列、重建 HNSW 索引，再完成全量 reindex。旧记录在具有当前 index identity 前不会参与检索。
 
-- 应将提取内容视为不可信上下文。Maglev 会清洗支持的 HTML 来源，但授权和模型公开范围仍由应用负责。
-- 只公开适合发送给所配置模型提供商的字段和内容源。
-- 默认附件限制为 5 MiB 和 20,000 个提取字符；默认允许纯文本、Markdown、HTML 和 XHTML。
-- v1 生成迁移使用 `bigint` 所有者 ID。使用 UUID 的模型需要自定义迁移。
-- Maglev 只负责 RAG。它不会生成 SQL、通过数据库计算回答聚合问题、公开 REST 端点、提供管理界面、运行 Agent 或管理对话记忆。
+### Index identity 与安全替换
 
-## 兼容性
+每个 chunk 都保存 `index_version`。Fingerprint 格式版本 1 使用
+`maglev-index` namespace，并覆盖 embedding 模型/维度、adapter ID/版本、
+chunking 算法/大小和 `application_index_version`。自定义 embedding adapter
+应实现 `maglev_adapter_id` 与 `maglev_adapter_version`，或配置
+`embedding_adapter_id` 与 `embedding_adapter_version`。
 
-CI 测试矩阵如下：
+`upgrade_index_version` 迁移会有意添加可空的 `index_version`。Legacy row
+在全量 reindex 获得当前 identity 前不可检索。维度变化时必须先迁移 vector
+列，再执行 reindex。Owner 替换失败时必须保留上一代完整内容。
 
-| | 支持版本 |
-|---|---|
-| Ruby | 3.2、3.3 |
-| Rails | 7.1、8.0 |
-| 数据库 | PostgreSQL + pgvector |
+## Vector store 契约
 
-矩阵之外的版本可能可以运行，但目前不作保证。
+PostgreSQL/pgvector 是生产默认方案；`Maglev::VectorStores::Memory` 适合测试和本地实验。自定义 store 实现 `fetch(ids:)`、`upsert(documents:)`、`search(vector:, filters:, limit:)`、`delete(ids:)`、`delete_by_owner(owner_type:, owner_id:)`、原子的 `replace_owner(owner_type:, owner_id:, documents:)`、`healthcheck` 和 `capabilities`。
 
-## 开发
+`delete_by_owner` 后接 `upsert` 不是原子替换。同一 owner 的并发替换/删除必须线性化；替换失败必须保留上一代完整内容。
 
-```bash
-bundle install
+## Trace、证据与安全边界
 
-# PostgreSQL + pgvector 集成测试
-MAGLEV_REQUIRE_POSTGRESQL=true MAGLEV_DATABASE=maglev_test bundle exec rspec
+Maglev Result 包含有界证据和 trace ID。Trace 记录标识符、决策、操作名、限制、安全计时、警告和错误类；默认排除记录值、来源正文、prompt、密钥和原始 provider payload。持久化和保留策略由宿主应用负责。
 
+Maglev 0.2 **不提供**：
+
+- 自然语言写操作或 mutation；
+- 不受限 SQL、Ruby、Arel、scope 或代码执行；
+- 自主/迭代 Agent；
+- Rails Engine、REST API、管理 UI 或强制前端；
+- 内置 PDF/Office/OCR/音频解析；
+- streaming 或对话记忆；
+- Qdrant 或其他强制外部向量服务。
+
+检索文档只是证据，绝不是能够改变路线、权限、Query IR 或执行策略的指令。
+
+## 运行环境支持与开发
+
+| 组件 | 支持版本 |
+| --- | --- |
+| Ruby | 3.3、4.0 |
+| Rails | 7.1、8.0 |
+| 数据库 | PostgreSQL + pgvector |
+
+```bash
+bundle exec rspec
 bundle exec standardrb
 bundle exec rubocop
 bundle exec rake build
+bundle exec rake maglev:release_audit
 ```
 
-默认测试套件使用确定性的虚拟适配器，不会调用真实的 LLM 或嵌入服务。
+默认测试使用确定性 fake，不调用线上 LLM 或 embedding provider。
 
 ## 许可证
 
-Maglev 以 [MIT License](LICENSE.txt) 开源发布。
+Maglev 使用 [MIT License](LICENSE.txt)。