企业官网建设流程全解析

wanman 是一款受日本单人驾驶列车启发的开源智能体矩阵运行时，其 SQLite 存储层设计堪称极简主义的典范：整个多智能体系统——消息队列、任务池、共享上下文、变更胶囊——全部落在一个 SQLite 文件里。对于想理解 AI Agent 框架状态持久化的新手来说，wanman 提供了一个干净利落的学习样本：没有数据库集群，没有中间件，只有一个文件。

为什么"一个文件"就足够了？

多智能体系统常被想象成需要复杂基础设施的重型工程，但 wanman 的 Supervisor（监督者） 选择了一条务实路线：所有运行时状态都是结构化的"小表"，单机、单文件完全够用。

打开数据库的代码只有几十行（见 supervisor.ts#L616-L641），核心逻辑是：

1. 打开单个数据库文件：默认路径/tmp/wanman.db，可通过环境变量WANMAN_DB或配置文件dbPath指定（见 config.ts#L29-L30）
2. 初始化各存储模块：同一个db连接被传给MessageStore、ContextStore、TaskPool、InitiativeBoard、ChangeCapsulePool五个模块，它们各自只负责自己的一张表

const db = new Database(dbPath); db.pragma('journal_mode = WAL'); db.pragma('busy_timeout = 5000');

💡WAL（Write-Ahead Logging）模式是关键一笔：它让"读"和"写"互不阻塞——监督者一边持续写入消息，一边响应 CLI 的查询请求，不会出现锁等待。busy_timeout则确保并发写入时最多等待 5 秒而不是立刻报错。

存储层全景：一个文件里的六张核心表

这套设计的精髓是每个模块"自治"：模块构造函数里先执行CREATE TABLE IF NOT EXISTS建表，再用prepare()预编译好常用 SQL。模块之间零耦合，谁也不关心别人的表长什么样。

消息队列：智能体间通信的"信箱"

messages表是整个矩阵的神经中枢。智能体 A 给 B 发消息，本质就是往表里插一行；B 收消息时查未读行并标记为已送达（见 message-store.ts#L74-L91 的表定义）。

三个巧妙的设计细节：

• 优先级排序：查询按ORDER BY CASE priority WHEN 'steer' THEN 0 ELSE 1 END, timestamp ASC执行——"steer"（转向）级消息永远插队，让人类能随时打断智能体正在干的事
• 原子领取：recv()在单个事务里"读取 + 标记已送达"，保证消息不会被投递两次
• 复合索引：idx_messages_to_delivered索引正好覆盖"查某智能体未读消息"这个最高频查询

任务池：状态机 + 作用域冲突检测

tasks表（见 task-pool.ts#L220-L245）是矩阵的"车间看板"，每个任务经历pending → assigned → in_progress → review → done/failed的生命周期。

两个亮点值得新手注意：

🔒原子认领：UPDATE tasks SET status='assigned' ... WHERE id=? AND status='pending'——用条件更新保证两个智能体不会抢到同一个任务，天然免锁。

🛡️作用域冲突检测：任务创建时声明自己会改哪些文件（scope字段），系统在认领前检查两个"活跃"任务的文件范围是否重叠，避免智能体互相踩文件。

另外，更新语句大量使用COALESCE和乐观并发检查（task-pool.ts#L198-L211），即"只更新我传了的字段、且状态未变才生效"——这是无锁并发下的经典写法。

免迁移的 Schema 演进：自修复策略

wanman 的表结构不是靠迁移脚本管理的，而是每次启动时自愈：

• 建表用CREATE TABLE IF NOT EXISTS，幂等无副作用
• 新增列用try { ALTER TABLE ... } catch {}包裹——列已存在就静默跳过（见 task-pool.ts#L247-L277）
• 旧版本数据格式（如messages表的content列）在启动时探测并自动改名迁移（见 message-store.ts#L59-L93）

对开源项目来说，这套策略极大降低了用户的升级成本：删库重来从来不是唯一选择。

安全边界：SQL 注入的最后防线

所有智能体产出的内容最终都要写进 SQL，wanman 在 sql-escape.ts 提供了分层防御：

• esc()/escJson()：字符串与 JSON 的引号转义
• SAFE_IDENT/SAFE_PATH白名单正则：智能体名、产物路径等"标识符"直接正则校验，不匹配就拒绝，从源头堵死注入

进阶：可选的"云脑"双层架构

本地 SQLite 是"永远在线"的第一层；如果配置了db9凭据，BrainManager 会在云端创建第二层存储，把产物、假设、运行记录镜像过去，实现跨运行、跨机器的记忆共享。没装该依赖时直接降级禁用，本地单文件模式不受影响——这就是架构文档中描述的双层持久化（见 docs/architecture.md）。

小结：向 wanman 学的存储设计清单

✅ 状态规模可控时，单文件 SQLite 比分布式方案更简单可靠 ✅ WAL 模式 + busy_timeout，低成本获得并发读写能力 ✅ 一个模块一张表，预编译语句，模块间零耦合 ✅ 条件更新实现原子操作，避免显式加锁 ✅ 启动时自愈式建表，用户升级零负担 ✅ 白名单校验 + 转义函数，守住 SQL 注入防线

这套"小文件承载大矩阵"的写法，对任何构建 AI Agent 系统的团队都是可以直接抄作业的范式。