AGENTS.md@src/host/assets · diff
git:20261008.100852a to git:20261011.d1c3e3a
8 added, 2 removed. Audit A to A.
# Assets Module Rules
## 范围与职责
适用于 `src/host/assets/`。
以**单文件 SQLite（`<root>/assets.db`）**保存两类持久化事实，并对外提供其读写入口：
- **资产**：模版的晋升形态。带版本控制、Active 指针、回滚与退役；分角色资产与工作流资产两类；
- **经验**：主体在运行中沉淀的可长期复用知识（九项语义核心 + 检索投影 + 向量），
- 以及其生成策略表 `experience_prompts`（三类主体各至多一个活跃 Prompt）。
+ 以及其生成策略表 `experience_prompts`（两类主体各至多一个活跃 Prompt）。
+ 主体类型 `team` 已永久退役：两张表的 CHECK 收窄为 `('agent','orchestrator')`，
+ 存量 team 行与其子行在初始化时物理删除，不留备份表。
判断归属：该修改是否改变「资产/经验被持久化成什么形状、版本如何推进、Active 如何指向」？
只改变业务语义判断（该不该晋升、该不该复用、两条经验是否算重复）应放到调用方模块。
## 时间戳与版本
- 时间戳一律 epoch 毫秒，由本模块记账（`AssetStoreDeps.now` 可注入，测试确定化）。
- `created_at` 是**资产诞生时间**，升版时沿用既有版本行的值；`updated_at` 每次写入刷新。
- `version_id` 从 1 开始、按资产独立递增（`max(version_id) + 1`）；版本行 id 固定
`<asset_id>@<version_id>`，它是工作流版本行反向引用角色版本行的键，属对外契约。
- 回滚只移动 Active 指针，不新增版本、不改历史行。
## 经验（Experience）
- 磁盘形状：`experiences`（写入即固定，状态只有 `is_active` 两态，没有版本与 Active 表）与
`experience_prompts`（生成策略；每个主体类型至多一行活跃，由部分唯一索引保证，不靠 TS 约定）。
- 向量以 BLOB 存 Float64 数值、维度另列；读侧严格校验字节长度与维度，不可用即按「无向量」降级——
不得截断、补零，也不得让整次列表读失败。
- 判重算法由经验域以闭包注入；本模块只保证「读活跃行 → 判定 → 写入」在同一笔事务内完成，
相似度与阈值不得下沉到本模块。
- 向量与检索文本一律在事务外算好随行传入：远程嵌入调用与首次模型加载都不得占用写事务。
- 必填语义字段被清空即拒绝（可行动错误）：经验没有版本，改坏无从回滚。
- 旧形状 `experiences`（无 `experience_type`）在初始化时删表重建，不留旧数据、不留备份表。
- - 三类生成 Prompt 的 V1 正文作为常量随代码发布；播种条件是「该主体类型没有任何行」，
+ - `team` 主体类型退役迁移的判据是「`experiences` / `experience_prompts` 任一表的建表原文仍含 `'team'`」，
+ 混合态（只收窄了其中一张表）同样收口；重建只针对仍含 `'team'` 的那张表，已收窄的表不重建。
+ 重建期间外键先关后开，子行（usage / evaluation / stats）必须先于父行删除——三张子表的外键都没有级联删除。
+ 重建前校验旧表列集合与当前形状一致，不符即报可行动错误并整笔回滚，不静默丢列。
+ - 两类生成 Prompt 的 V1 正文作为常量随代码发布；播种条件是「该主体类型没有任何行」，
已存在的行（含用户改写的正文）一律不被覆盖。
## 核心原则
1. 资产事实由本模块单独拥有，磁盘形状与错误码属对外契约。
2. 读改写不出事务，失败不留半成品。
3. 历史不可变，Active 即指针；统计是缓存，可重建且有唯一维护点。
4. 时间戳与版本号由本模块记账，注入式时钟保证测试确定。
5. 列表读可用、单资源读可诊断；重建宁可报错也不产半成品。
6. 经验只承担形状与原子边界：判重规则属经验域，本模块不实现相似度。