Data Models

数据模型速查

🏗️ 架构 · 🏠 首页 › Data-Models

---

📑 本页目录

• 1. cs-mem：Room MemoryGraphDatabase（schema v3）
• 2. 任务：FileTaskStore（schema v1）
• 3. 终端会话：SessionRecord（schema v3）
• 4. Skill manifest（apex-skill-v1）
• 5. Shortcut 定义（shortcut.*）
• 6. Plugin 契约（PluginMetadata / PluginToolDescriptor）
• 7. 相关页面

一页看全项目里持久化的结构：Room 记忆库、任务存储、会话记录、技能 manifest、迁移表。

1. cs-mem：Room MemoryGraphDatabase（schema v3）

表	实体	要点
nodes	NodeEntity	语义节点；指纹为主键；含 app_version（缺口 #9 新增）、能量与时间戳
edges	EdgeEntity	关系边（SPATIAL / CAUSAL / SEMANTIC）；**边 ID = `SHA-256(源指纹
episodes	EpisodeEntity	情景记忆：startedAt / finishedAt / goal / status
fsm_macros	FSMMacroEntity	程序性宏技能；含 is_crystallized、能量、成功次数与成功率
migration_map	MigrationMapEntity	旧指纹 → 新指纹别名：oldFingerprint（唯一索引）/ newFingerprint / matchScore / fromVersion / toVersion / createdAt

约束与规则：

• v2 → v3 迁移：清理历史重复边 + 建 (episode_id, edge_label) 唯一索引 + 删除操作增加 episode 作用域；
• 升级必须显式 Migration，仅降级允许 destructive；
• nodes 是跨 Episode 共享字典：删除 Episode 不硬删节点，只降能交由熵遗忘回收；
• 查询注意：IN (:fingerprints) 必须 chunked(500)（Android 8–10 的 SQLITE_MAX_VARIABLE_NUMBER = 999）。

2. 任务：FileTaskStore（schema v1）

filesDir/taskstore/<taskId>.json

元素	内容
Task	AgentTask：状态 / 步骤 / journal / 时间戳 / TaskConfigSnapshot / conversationRef（v1 = "global"）/ contextRef
Step	TaskStepModel：PENDING / RUNNING / DONE / FAILED / SKIPPED
Operation	ToolOperationRecord：NOT_STARTED / RUNNING / SUCCEEDED / FAILED / UNKNOWN；operationId = <taskId>-op<seq>
限制	journal 滚动保留最近 200 条；参数摘要 512 字符、输出摘要 256 字符

写入：tmp → fsync → 原子 rename；损坏文件移入 corrupt/（隔离而非删除）；ignoreUnknownKeys 宽容解析。

3. 终端会话：SessionRecord（schema v3）

字段	用途
backendId	local / linux-ubuntu
rootfsId	使用的 rootfs 指纹
workspaceId	绑定的 workspace
guestCwd	guest 当前目录
workspace binds	/workspace、/root 等挂载信息

崩溃恢复据此区分 local 与 Ubuntu 会话；恢复状态如实标为 EXITED / BROKEN。

4. Skill manifest（apex-skill-v1）

{
  "schema": "apex-skill-v1",
  "id": "web_scrape",
  "name": "网页抓取",
  "type": "Composite | Prompt | Script | Connector",
  "description": "...",
  "params": { "url": "string" },
  "steps": [
    { "tool": "web_fetch", "args": { "url": "{{url}}" } },
    { "tool": "regex_extract", "args": { "pattern": "...", "input": "{{prev_output}}" } }
  ]
}

存放：filesDir/skills/<id>.json；安装后经 SkillToolAdapter 注册为运行时工具。

5. Shortcut 定义（shortcut.*）

id（shortcut.* 命名空间）/ 前置条件 / 声明参数 / 步骤模板（{param} 占位 + {0} 步间引用）
解析期全量校验：未知工具 / 未声明占位符 / 死参数 / 超步数 → 字段级拒绝
风险继承：编译工具的风险 = 所含步骤最坏风险

6. Plugin 契约（PluginMetadata / PluginToolDescriptor）

PluginMetadata(id, name, version, versionName, minHostVersion, description)
PluginToolDescriptor(id, name, description, parametersSchema)

7. 相关页面

• cs-mem 认知记忆 · 任务运行时
• 技能与斜杠命令 · 插件 SDK · 终端 API 契约

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}