smart_brain 0.1.2 → 0.2.0

data/db/migrate/002_turn_events_payload.sql

@@ -0,0 +1,9 @@
+-- SmartBrain v0.1.1: persist the full per-turn events payload (JSONB).
+--
+-- Why: the runtime computes entity-gate frequencies from the *candidate*
+-- entities a caller passes in each turn_events (before any gating decision).
+-- The normalized tables (messages / refs / entity_mentions) don't capture
+-- that raw input, so we store the normalized turn_events blob here to let
+-- EventStore::Postgres faithfully reproduce EventStore::InMemory semantics.
+
+ALTER TABLE turns ADD COLUMN IF NOT EXISTS events_json JSONB NOT NULL DEFAULT '{}'::jsonb;

data/db/migrate/003_tiers_and_lifecycle.sql

@@ -0,0 +1,28 @@
+-- SmartBrain v0.1.3: mind-model tiers + knowledge lifecycle (Stage-1).
+--
+-- Tiers (mempal mind model): dao_tian / dao_ren / shu / qi / evidence.
+-- Lifecycle: raw -> candidate -> promoted / demoted (gated by knowledge_events).
+-- These are orthogonal to the conflict `status` (active/superseded/retracted):
+-- an item has both — status resolves conflicts, lifecycle_status governs knowledge.
+
+ALTER TABLE memory_items ADD COLUMN IF NOT EXISTS tier TEXT NOT NULL DEFAULT 'evidence';
+ALTER TABLE memory_items ADD COLUMN IF NOT EXISTS lifecycle_status TEXT NOT NULL DEFAULT 'raw';
+
+CREATE INDEX IF NOT EXISTS idx_memory_items_tier ON memory_items(tier);
+CREATE INDEX IF NOT EXISTS idx_memory_items_lifecycle ON memory_items(lifecycle_status);
+
+-- Append-only audit trail for the distill/gate/promote/demote lifecycle.
+CREATE TABLE IF NOT EXISTS knowledge_events (
+  id TEXT PRIMARY KEY,
+  memory_item_id TEXT NOT NULL,
+  event_type TEXT NOT NULL,            -- distill | promote | demote | gate
+  from_lifecycle TEXT,
+  to_lifecycle TEXT,
+  reason TEXT,
+  reason_type TEXT,                    -- contradicted | obsolete | superseded (demote)
+  reviewer TEXT,
+  evidence_refs JSONB NOT NULL DEFAULT '[]'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_knowledge_events_item ON knowledge_events(memory_item_id);

data/db/migrate/004_kg_edges.sql

@@ -0,0 +1,30 @@
+-- SmartBrain v0.1.4: knowledge graph (triples with temporal validity).
+--
+-- KG edges are orthogonal to memory_items: they record relations between
+-- entities (subject/predicate/object) with valid_from/valid_to temporal
+-- validity and an active|invalidated status. They do NOT participate in the
+-- Stage-1 lifecycle (candidate/promoted/demoted) or the conflict `status` of
+-- memory_items. Invalidation sets valid_to=now + status='invalidated'.
+
+CREATE TABLE IF NOT EXISTS kg_edges (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  subject TEXT NOT NULL,
+  predicate TEXT NOT NULL,
+  object TEXT NOT NULL,
+  subject_entity_id TEXT,
+  object_entity_id TEXT,
+  valid_from TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  valid_to TIMESTAMPTZ,
+  source_turn_id TEXT,
+  source_memory_item_id TEXT,
+  confidence NUMERIC(3,2) NOT NULL DEFAULT 0.6,
+  status TEXT NOT NULL DEFAULT 'active',
+  meta_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_kg_edges_session ON kg_edges(session_id);
+CREATE INDEX IF NOT EXISTS idx_kg_edges_subject ON kg_edges(subject);
+CREATE INDEX IF NOT EXISTS idx_kg_edges_object ON kg_edges(object);
+CREATE INDEX IF NOT EXISTS idx_kg_edges_status ON kg_edges(status);

data/db/migrate/005_domains_and_memory_scopes.sql

@@ -0,0 +1,163 @@
+-- SmartBrain v0.2: domain isolation and multi-scope long-term memory.
+
+CREATE TABLE IF NOT EXISTS domains (
+  id TEXT PRIMARY KEY,
+  metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+INSERT INTO domains (id) VALUES ('legacy') ON CONFLICT (id) DO NOTHING;
+
+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS domain_id TEXT;
+
+-- Older memory_items/kg_edges did not enforce a sessions FK. Preserve them by
+-- materializing any missing legacy sessions before creating scope links.
+INSERT INTO sessions (id, domain_id, metadata_json)
+SELECT source.session_id, 'legacy', '{}'::jsonb
+FROM (
+  SELECT DISTINCT session_id FROM memory_items
+  UNION
+  SELECT DISTINCT session_id FROM kg_edges
+) source
+WHERE source.session_id IS NOT NULL
+ON CONFLICT (id) DO NOTHING;
+
+UPDATE sessions SET domain_id = 'legacy' WHERE domain_id IS NULL;
+ALTER TABLE sessions ALTER COLUMN domain_id SET NOT NULL;
+
+DO $$ BEGIN
+  ALTER TABLE sessions ADD CONSTRAINT fk_sessions_domain
+    FOREIGN KEY (domain_id) REFERENCES domains(id);
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+CREATE TABLE IF NOT EXISTS memory_scopes (
+  id TEXT PRIMARY KEY,
+  domain_id TEXT NOT NULL REFERENCES domains(id),
+  scope_type TEXT NOT NULL,
+  external_id TEXT NOT NULL,
+  parent_scope_id TEXT REFERENCES memory_scopes(id),
+  metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE(domain_id, scope_type, external_id)
+);
+
+CREATE TABLE IF NOT EXISTS session_scope_links (
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  scope_id TEXT NOT NULL REFERENCES memory_scopes(id),
+  access_mode TEXT NOT NULL,
+  priority INTEGER NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY(session_id, scope_id)
+);
+
+INSERT INTO memory_scopes (id, domain_id, scope_type, external_id)
+SELECT 'legacy:session:' || id, 'legacy', 'session', id
+FROM sessions
+WHERE domain_id = 'legacy'
+ON CONFLICT (domain_id, scope_type, external_id) DO NOTHING;
+
+INSERT INTO session_scope_links (session_id, scope_id, access_mode, priority)
+SELECT s.id, ms.id, 'read_write', 0
+FROM sessions s
+JOIN memory_scopes ms
+  ON ms.domain_id = s.domain_id AND ms.scope_type = 'session' AND ms.external_id = s.id
+ON CONFLICT (session_id, scope_id) DO NOTHING;
+
+ALTER TABLE memory_items ADD COLUMN IF NOT EXISTS scope_id TEXT;
+ALTER TABLE memory_items ADD COLUMN IF NOT EXISTS source_session_id TEXT;
+UPDATE memory_items m
+SET scope_id = ms.id, source_session_id = COALESCE(m.source_session_id, m.session_id)
+FROM memory_scopes ms
+WHERE m.scope_id IS NULL
+  AND ms.domain_id = 'legacy' AND ms.scope_type = 'session' AND ms.external_id = m.session_id;
+ALTER TABLE memory_items ALTER COLUMN scope_id SET NOT NULL;
+ALTER TABLE memory_items ALTER COLUMN source_session_id SET NOT NULL;
+
+ALTER TABLE entities ADD COLUMN IF NOT EXISTS scope_id TEXT;
+ALTER TABLE entities ADD COLUMN IF NOT EXISTS source_session_id TEXT;
+
+INSERT INTO sessions (id, domain_id, metadata_json)
+VALUES ('legacy:entities', 'legacy', '{"synthetic":true}'::jsonb)
+ON CONFLICT (id) DO NOTHING;
+INSERT INTO memory_scopes (id, domain_id, scope_type, external_id, metadata_json)
+VALUES ('legacy:session:legacy:entities', 'legacy', 'session', 'legacy:entities', '{"synthetic":true}'::jsonb)
+ON CONFLICT (domain_id, scope_type, external_id) DO NOTHING;
+INSERT INTO session_scope_links (session_id, scope_id, access_mode, priority)
+VALUES ('legacy:entities', 'legacy:session:legacy:entities', 'read_write', 0)
+ON CONFLICT (session_id, scope_id) DO NOTHING;
+
+WITH entity_sources AS (
+  SELECT em.entity_id, MIN(t.session_id) AS session_id
+  FROM entity_mentions em
+  JOIN turns t ON t.id = em.turn_id
+  GROUP BY em.entity_id
+)
+UPDATE entities e
+SET source_session_id = sources.session_id, scope_id = ms.id
+FROM entity_sources sources
+JOIN memory_scopes ms
+  ON ms.domain_id = 'legacy' AND ms.scope_type = 'session' AND ms.external_id = sources.session_id
+WHERE e.id = sources.entity_id AND (e.scope_id IS NULL OR e.source_session_id IS NULL);
+
+UPDATE entities
+SET source_session_id = COALESCE(source_session_id, 'legacy:entities'),
+    scope_id = COALESCE(scope_id, 'legacy:session:legacy:entities');
+ALTER TABLE entities ALTER COLUMN scope_id SET NOT NULL;
+ALTER TABLE entities ALTER COLUMN source_session_id SET NOT NULL;
+
+ALTER TABLE kg_edges ADD COLUMN IF NOT EXISTS scope_id TEXT;
+ALTER TABLE kg_edges ADD COLUMN IF NOT EXISTS source_session_id TEXT;
+UPDATE kg_edges e
+SET scope_id = ms.id, source_session_id = COALESCE(e.source_session_id, e.session_id)
+FROM memory_scopes ms
+WHERE e.scope_id IS NULL
+  AND ms.domain_id = 'legacy' AND ms.scope_type = 'session' AND ms.external_id = e.session_id;
+ALTER TABLE kg_edges ALTER COLUMN scope_id SET NOT NULL;
+ALTER TABLE kg_edges ALTER COLUMN source_session_id SET NOT NULL;
+
+DO $$ BEGIN
+  ALTER TABLE memory_items ADD CONSTRAINT fk_memory_items_scope
+    FOREIGN KEY (scope_id) REFERENCES memory_scopes(id);
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+DO $$ BEGIN
+  ALTER TABLE kg_edges ADD CONSTRAINT fk_kg_edges_scope
+    FOREIGN KEY (scope_id) REFERENCES memory_scopes(id);
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+DO $$ BEGIN
+  ALTER TABLE entities ADD CONSTRAINT fk_entities_scope
+    FOREIGN KEY (scope_id) REFERENCES memory_scopes(id);
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+CREATE INDEX IF NOT EXISTS idx_sessions_domain ON sessions(domain_id);
+CREATE INDEX IF NOT EXISTS idx_memory_items_scope_status_lifecycle ON memory_items(scope_id, status, lifecycle_status);
+CREATE INDEX IF NOT EXISTS idx_memory_items_scope_type_key ON memory_items(scope_id, type, key);
+CREATE INDEX IF NOT EXISTS idx_kg_edges_scope_status ON kg_edges(scope_id, status);
+CREATE INDEX IF NOT EXISTS idx_entities_scope_canonical_kind ON entities(scope_id, canonical_id, kind);
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM memory_items m
+    JOIN memory_scopes ms ON ms.id = m.scope_id
+    JOIN sessions s ON s.id = m.source_session_id
+    WHERE ms.domain_id <> s.domain_id
+  ) OR EXISTS (
+    SELECT 1 FROM kg_edges e
+    JOIN memory_scopes ms ON ms.id = e.scope_id
+    JOIN sessions s ON s.id = e.source_session_id
+    WHERE ms.domain_id <> s.domain_id
+  ) OR EXISTS (
+    SELECT 1 FROM entities e
+    JOIN memory_scopes ms ON ms.id = e.scope_id
+    JOIN sessions s ON s.id = e.source_session_id
+    WHERE ms.domain_id <> s.domain_id
+  ) THEN
+    RAISE EXCEPTION 'multi-scope migration consistency check failed';
+  END IF;
+END $$;

data/docs/coding_todo.md

@@ -0,0 +1,139 @@
+# SmartBrain Ruby 开发待办（v0.1）
+
+## 0. 目标与范围
+- 目标：实现 `commit_turn` 与 `compose_context` 主链路，满足 `docs/policies.md` 的最低验收标准。
+- 边界：SmartBrain 管理对话记忆与上下文装配；资源检索由 SmartRAG 提供。
+- 默认部署：PostgreSQL（SQLite 仅开发模式）。
+
+## 1. 技术基线（Ruby）
+- [x] 确定 Ruby 版本：`3.2+`
+- [x] 选型并固定 ORM：`sequel + pg`（或 ActiveRecord，二选一）
+- [x] 测试框架：`rspec`
+- [x] 契约与校验：`dry-struct` / `dry-validation`
+- [x] HTTP 客户端：`faraday`（SmartRAG Adapter）
+- [x] JSON：`oj`
+- [x] 新增配置文件：`config/brain.yml`（映射 `docs/policies.md` 默认策略）
+
+## 2. 目录与模块骨架
+- [x] 建立目录：
+  - `lib/smart_brain/event_store/`
+  - `lib/smart_brain/memory_extractor/`
+  - `lib/smart_brain/consolidator/`
+  - `lib/smart_brain/retrieval_planner/`
+  - `lib/smart_brain/retrievers/`
+  - `lib/smart_brain/adapters/smart_rag/`
+  - `lib/smart_brain/fusion/`
+  - `lib/smart_brain/context_composer/`
+  - `lib/smart_brain/model_provider/`
+- [x] 建立测试目录：
+  - `spec/commit_turn_spec.rb`
+  - `spec/compose_context_spec.rb`
+  - `spec/integration_smart_rag_adapter_spec.rb`
+
+## 3. 数据库与迁移（Postgres）
+- [x] 创建表：`sessions`
+- [x] 创建表：`turns`
+- [x] 创建表：`messages`
+- [x] 创建表：`tool_calls`
+- [x] 创建表：`refs`
+- [x] 创建表：`memory_items`
+- [x] 创建表：`memory_chunks`
+- [x] 创建表：`entities`
+- [x] 创建表：`entity_mentions`
+- [x] 创建表：`summaries`（存 working_summary 与元信息）
+- [x] 索引：`session_id/turn_id/updated_at/type+key/status`
+- [x] FTS 索引：`messages`、`memory_chunks`
+
+## 4. 里程碑 M1（第 1 周）：主链路打通
+### 4.1 commit_turn
+- [x] 实现 `SmartBrain.commit_turn(session_id:, turn_events:)`
+- [x] EventStore 全量写入：turn/messages/tool_calls/refs
+- [x] Retention Gate v0：
+  - 必写：`tasks`、`decisions`、refs（事件层）
+  - 条件写：`preferences`、`goals`、`events`
+  - 不写长期记忆：闲聊、未确认推测
+- [x] 冲突处理 v0：
+  - 覆盖：`preferences/tasks` -> 旧值 `superseded`
+  - 撤回：`retracted`
+
+### 4.2 compose_context
+- [x] 实现 `SmartBrain.compose_context(session_id:, user_message:, agent_state: {})`
+- [x] 固定槽位装配 `ContextPackage`
+- [x] 实现 `RetrievalPlanner` v0（exact/hybrid + 是否调用 SmartRAG）
+- [x] 实现 SmartRAG Adapter：`retrieve(plan)` -> `EvidencePack`
+
+### 4.3 M1 验收
+- [x] `spec/commit_turn_spec.rb` 通过
+- [x] `spec/compose_context_spec.rb` 通过
+- [x] `context_id/request_id/plan_id` 全链路可追踪
+
+## 5. 里程碑 M2（第 2 周）：策略落地与检索增强
+### 5.1 policies 参数化
+- [x] `retention.entity_gate.window_turns=20`
+- [x] `retention.entity_gate.freq_threshold=2`
+- [x] `confidence.user_asserted/tool_derived/inferred`
+- [x] `retrieval.top_k=30`、`candidate_k=200`
+- [x] `retrieval.query_expansion.enabled/max_queries`
+- [x] `composition.token_limit/system_blocks_max_tokens/summary_max_tokens`
+- [x] `composition.recent_turns_max/evidence_max_items/max_snippet_chars`
+- [x] `composition.diversity.by_document/by_source_uri/memory_resource_ratio`
+
+### 5.2 检索与融合
+- [x] 对话侧 `ExactRetriever`（FTS）
+- [x] 对话侧 `RelationalRetriever`（entities + mentions）
+- [x] 多源去重：
+  - resource: `document_id + section_id (+chunk_index)`
+  - memory: `memory_item_id` 或 `turn_id + message_id`
+- [x] 跨源统一重排接口（可先规则分，后接 reranker）
+
+### 5.3 M2 验收
+- [x] 资源检索触发条件符合 `docs/policies.md`
+- [x] evidence 条数限制与截断生效
+- [x] 多样性约束生效（同文档/同 source 限制）
+- [x] `ignored_fields` 可记录后端不支持字段
+
+## 6. 里程碑 M3（第 3 周）：摘要巩固与可观测
+### 6.1 Consolidation
+- [x] working_summary 触发条件：
+  - `summarize_after_turns`
+  - token 压力
+  - 阶段事件（task 完成/decision 形成）
+- [x] 摘要模板固定：
+  - Goals
+  - Decisions
+  - Tasks
+  - Key References
+  - Open Questions
+- [x] 保存摘要元信息：`summary_version/source_turn_range/generated_at`
+
+### 6.2 Observability
+- [x] `compose_context` 日志：
+  - plan
+  - evidence 入选与分数
+  - token 预算与 trimmed 原因
+  - ignored_fields
+- [x] `commit_turn` 日志：
+  - 写入 memory_items（type/key/confidence/status）
+  - 冲突处理结果
+  - 摘要触发情况
+
+### 6.3 M3 验收
+- [x] 满足 `docs/policies.md` 第 7 节最低验收标准
+- [x] 单个 session 可回放并解释“为何写入/为何选中证据”
+
+## 7. 测试与回归清单
+- [x] 单元测试：gate/conflict/planner/budget/diversity/dedupe
+- [x] 集成测试：SmartRAG adapter（成功、超时、字段降级）
+- [x] 回归测试：固定会话数据集，比较 ContextPackage 关键字段稳定性
+- [x] 性能指标：
+  - `compose_context` P95
+  - evidence 命中来源比例（memory/resource）
+  - token 超预算率
+
+## 8. 执行顺序（严格）
+1. [x] 先做数据库迁移 + 契约对象（RetrievalPlan / EvidencePack / ContextPackage）
+2. [x] 打通 `commit_turn` 最小闭环
+3. [x] 打通 `compose_context` 最小闭环（含 SmartRAG adapter）
+4. [x] 落地 `policies.md` 参数化
+5. [x] 补齐 observability + 回归测试
+6. [x] 再做检索增强与性能优化

data/docs/context_package.md

@@ -0,0 +1,220 @@
+## 1. 目的
+
+ContextPackage 用于把“本轮给模型的上下文”表达为结构化对象，解决：
+- 直接拼接全部 history 不可扩展（token 预算）
+- 证据与对话混在一起不可控（难 debug）
+- 工具结果与长期记忆无法一致治理（无统一入口）
+
+ContextPackage 是 **SmartBrain 的输出**，SmartBrain 对其内容负责；SmartPrompt 只负责把它转换为模型调用格式并发送。
+
+---
+
+## 2. 顶层结构
+
+```json
+{
+  "version": "0.1",
+  "context_id": "uuid",
+  "session_id": "string",
+  "created_at": "2026-02-20T12:00:00Z",
+
+  "system_blocks": [],
+  "developer_blocks": [],
+  "working_summary": "",
+  "recent_turns": [],
+  "evidence": [],
+  "user_message": { "role": "user", "content": "..." },
+
+  "constraints": {},
+  "debug": {}
+}
+```
+
+字段说明：
+
+* `version`：协议版本（必填）
+* `context_id`：本次装配唯一 id（建议必填）
+* `session_id`：会话 id（必填）
+* `created_at`：生成时间（必填）
+* `system_blocks`：可钉在 system 的核心记忆与规则
+* `developer_blocks`：开发者侧指令（工具使用规则、引用规则等）
+* `working_summary`：滚动摘要（可选）
+* `recent_turns`：最近窗口对话（可选）
+* `evidence`：检索证据（可选但关键）
+* `user_message`：本轮用户输入（必填）
+* `constraints`：token 预算/多样性等约束的“结果”或“输入”（可选）
+* `debug`：解释信息（可选）
+
+---
+
+## 3. system_blocks
+
+用于承载稳定信息，通常来自 SmartBrain 的 MemoryExtractor/Consolidator。
+
+```json
+{
+  "type": "core_profile|preferences|goals|policies|other",
+  "text": "string",
+  "updated_at": "2026-02-20T00:00:00Z",
+  "source": { "turn_id": "...", "memory_item_id": "..." }
+}
+```
+
+建议约定：
+
+* `core_profile`：用户身份/背景（稳定）
+* `preferences`：偏好与约束（稳定但会更新）
+* `goals`：长期目标/项目目标
+* `policies`：系统规则（如引用要求、工具调用规范）
+
+---
+
+## 4. developer_blocks（可选）
+
+用于放置“执行层规则”，例如：
+
+* 必须引用证据回答
+* 工具调用失败时如何降级
+* 输出格式要求
+
+结构同 system_blocks，type 可为：`tooling_rules|format_rules|safety_rules|other`
+
+---
+
+## 5. working_summary（可选）
+
+* 目的：压缩较早对话
+* 内容：一段文字（可带 bullet）
+* 由 SmartBrain 维护，SmartPrompt 不应擅自修改
+
+---
+
+## 6. recent_turns（可选）
+
+```json
+[
+  { "role": "user", "content": "..." },
+  { "role": "assistant", "content": "..." }
+]
+```
+
+约束建议：
+
+* 只保留最近 N 轮（由 brain.yml 的 retention.window_turns 控制）
+* 不应包含过长的 tool result（tool result 应进入 evidence 或另一个结构）
+
+---
+
+## 7. evidence（关键）
+
+Evidence 是 SmartBrain 从多个来源收集并筛选后的“可引用证据”，通常来自：
+
+* SmartBrain 自己的 memory store（对话记忆、任务状态、实体事件）
+* SmartRAG 的资源检索（文档/URL 知识库）
+
+### 7.1 EvidenceItem 结构
+
+```json
+{
+  "id": "string",
+  "source": "memory|resource",
+  "source_uri": "string",
+  "title": "string",
+  "snippet": "string",
+  "mode": "exact|semantic|hybrid|relational|associative",
+  "score": 0.0,
+  "signals": {
+    "rerank_score": 0.0,
+    "rrf_score": 0.0,
+    "vector_score": 0.0,
+    "fts_score": 0.0
+  },
+  "provenance": {
+    "request_id": "uuid",
+    "plan_version": "0.1",
+    "retrieved_at": "2026-02-20T12:00:00Z"
+  },
+  "ref": {
+    "document_id": "...",
+    "section_id": "...",
+    "turn_id": "...",
+    "memory_item_id": "..."
+  }
+}
+```
+
+字段说明：
+
+* `source_uri`：必须能定位回源（URL、file://、viking://、smartbrain://turn/...）
+* `snippet`：默认短文本，可用于直接拼入 prompt
+* `signals`：可选，用于 debug 与可解释
+* `ref`：可选，内部定位
+
+### 7.2 Evidence 分组（可选）
+
+SmartBrain 可以在 evidence 上附加 `group` 字段（例如 `exact_hits` / `semantic_hits` / `relational_bundle`），但 v0.1 不强制。
+
+---
+
+## 8. user_message（必填）
+
+```json
+{ "role": "user", "content": "..." }
+```
+
+> SmartBot/SmartPrompt 使用该字段作为最终 user message，而不是从 recent_turns 推断。
+
+---
+
+## 9. constraints（可选）
+
+用于携带“预算输入/装配结果”，便于观测与回归。
+
+```json
+{
+  "token_budget": { "limit": 8000, "used_estimate": 6120 },
+  "diversity": { "by_document": 3, "by_source": 10 },
+  "truncation": { "snippets_max_chars": 800, "recent_turns_max": 8 }
+}
+```
+
+---
+
+## 10. debug（可选但强烈建议开发期启用）
+
+```json
+{
+  "planner": { "intent": "qa", "reason": "user asked for ...", "queries": ["..."] },
+  "why_selected": [
+    "evidence#5 rerank_score=0.91, covers key entity X",
+    "recent_turns kept because user said 'as we discussed earlier'"
+  ],
+  "ignored": [
+    "filter time_range not supported by backend, skipped",
+    "diversity.by_source not supported, skipped"
+  ]
+}
+```
+
+---
+
+## 11. SmartPrompt 消息转换建议（非规范，但推荐）
+
+SmartBot/SmartPrompt 将 ContextPackage 转成 messages 的顺序建议：
+
+1. system：拼接所有 `system_blocks.text`（可加标题分隔）
+2. developer：拼接 `developer_blocks.text`（如果你的 runtime 支持 developer role，否则并入 system）
+3. system/assistant：插入 `working_summary`（建议以“Summary:”前缀）
+4. history：插入 `recent_turns`
+5. assistant/system：插入 `evidence`（建议以“Evidence:”结构化列出）
+6. user：`user_message`
+
+> 重要：证据与摘要应当以稳定格式注入，便于模型引用与后续评估。
+
+---
+
+## 12. 变更策略
+
+* v0.1：新增字段只能“可选”，不得破坏现有字段含义
+* 执行方必须忽略未知字段（向后兼容）
+* 如需破坏性变更，另起 major 版本并提供迁移说明