# 05 数据模型

SQLite（WAL 模式），Drizzle 管理迁移。文件内容不入库，只存元数据。

## 1. 实体关系

```
api_keys ──< sessions >── profiles ──< profile_knowledge >── knowledge_roots
                ├─< runs ──< interactions
                ├─< events
                └─< files
settings   audit_logs   usage_daily   admin_sessions
```

不区分使用者：上层平台通过 API Key 调用，会话归属到 API Key。

## 2. 表定义（要点）

| 表 | 关键字段 | 说明 |
|---|---|---|
| `api_keys` | id, name, key_hash, key_prefix, enabled, allowed_profile_ids(json), default_profile_id, created_at, last_used_at | 每个上层平台一个 Key；只存哈希；只能使用勾选的 Profile（ADR-0015） |
| `profiles` | id, name, provider, model, system_prompt, permission_mode, allowed_tools(json), disallowed_tools(json), skills(json), file_access(json), knowledge_root_ids(json), is_default, builtin, version, updated_at | Agent 预设；`file_access` 见 06 §4；`builtin` 的通用助手不可删除 |
| `knowledge_roots` | id, name, path, description, access('read'\|'write'), enabled, visible(检测结果), checked_at | 资料库，**在后台设定** |
| `profile_knowledge` | profile_id, knowledge_root_id | Profile 启用的资料库 |
| `sessions` | id, source, profile_id, provider, model, permission_mode, provider_session_id, workspace_dir, title, last_seq, created_at, updated_at, archived | `permission_mode` 为空表示跟随 Profile（只有后台可以覆盖） |
| `runs` | id, session_id, status, started_at, ended_at, input_tokens, output_tokens, cost_usd, error | |
| `events` | session_id, seq, run_id, type, payload(json), ts — PK(session_id, seq) | 事件全量落库 |
| `interactions` | id, run_id, session_id, kind, request(json), response(json), status, created_at, resolved_at, expires_at | |
| `files` | id, session_id, rel_path, origin('upload'\|'agent'), mime, size, sha256, created_at | |
| `settings` | key, value(json), updated_at | 全局配置，见 §3 |
| `audit_logs` | id, ts, actor, session_id, kind('command'\|'file_access_denied'\|'approval'\|'admin'), summary, detail(json) | |
| `usage_daily` | date, api_key_id, provider, model, runs, input_tokens, output_tokens, cost_usd | |
| `admin_sessions` | id, created_at, expires_at | 后台登录会话 |

预留（暂不建表）：`connectors`、`profile_connectors`（内部平台接入，见 08）；`credentials`（API Key 类凭证，见 ADR-0008）。

## 3. 后台可设定的全局配置（`settings`）

| key | 默认值 | 说明 |
|---|---|---|
| `paths.workspaceRoot` | `/srv/agent-server/workspaces` | 会话工作区根目录 |
| `paths.skillsDir` | `/srv/agent-server/skills` | 共享技能目录 |
| `paths.pythonRuntime` | `/srv/agent-server/runtime/py` | Python 环境 |
| `paths.matplotlibrc` | `/srv/agent-server/runtime/matplotlibrc` | 中文字体配置 |
| `security.globalDeny` | 内置清单（见 06 §4.1）+ 自定义 | 内置项不可删除 |
| `security.defaultFileAccess` | `restricted` | 新建 Profile 的默认模式 |
| `network.allowedDomains` | `pypi.org`, `files.pythonhosted.org` | Claude Bash 沙箱的白名单 |
| `network.blockPrivateFetch` | `true` | WebFetch 私网拦截 |
| `limits.concurrency` | `{ global: 4, claude: 2, codex: 2 }` | |
| `limits.interactionTimeoutSec` | `600` | 交互超时（按拒绝处理） |
| `limits.uploadMaxMB` / `workspaceMaxMB` | `50` / `2048` | |
| `retention.workspaceDays` | `30` | 归档后的工作区保留天数 |
| `providers.claude` | `{ enabled, cliPath, defaultModel }` | |
| `providers.codex` | `{ enabled, cliPath, defaultModel, configOverrides }` | `configOverrides` 用于禁用个人 config 中的插件和 MCP |

修改后对**新的 Run** 立即生效；`providers.codex` 的修改会触发 app-server 进程平滑重启（等活动 turn 结束后再重启）。

## 4. 文件系统布局

```
/srv/agent-server/                  （属主 jerry-remote）
├─ app/                             部署的构建产物
├─ data/agent.db                    SQLite
├─ workspaces/<sessionId>/
│   ├─ uploads/                     用户上传（数据文件、截图）
│   ├─ outputs/                     最终产出
│   └─ .agent/                      工具大输出等内部文件
├─ knowledge/                       默认资料库位置（也可以在后台添加其他路径）
├─ skills/                          共享技能
├─ runtime/py/                      Python venv（已创建）
├─ runtime/matplotlibrc             中文字体配置（已创建）
├─ runtime/requirements.lock        锁定的 Python 依赖版本
└─ logs/
```

## 5. 保留策略
- 工作区：会话归档后保留 `retention.workspaceDays` 天，之后清理目录，会话与事件保留
- 事件：永久保留；`tool.completed.output` 超过 64KB 时截断，全文写入 `.agent/tool-outputs/`
- 审计日志：保留 1 年