MemBridge（通忆）— AI 协同编程的记忆中继站

一个知识库，三种工作模式：

开发循环工作流

这个 skill 设计为支撑"大循环套小循环"的开发模式：

版本迭代（大循环）
├── AI 开发 → build_db.py --incremental → 知识库更新
├── 人类审查 → export_md.py --review → 审查清单
├── AI 继续开发 → build_db.py --incremental → 知识库更新
├── 人类审查 → export_md.py --review → 审查清单
├── ... 重复 ...
└── 版本完成 → export_md.py → 完整 PROJECT_SPEC.md

核心架构

项目目录/
├── .ai/
│   ├── project.ai.db        # SQLite 知识库（开发模式核心）
│   ├── CONTEXT.md           # L1 导航文件（AI 首次读取）
│   ├── build_db.py          # 构建脚本
│   ├── query_db.py          # AI 查询脚本（支持 SQL 直传）
│   ├── export_md.py         # 导出脚本（SQLite → 完整 Markdown）
│   └── init_project.sh      # 快速初始化（可选）
└── docs/
    └── PROJECT_SPEC.md      # 交接模式输出（由 export_md.py 生成）

工作流程

首次接入项目

1. 扫描项目 — 运行 init_project.sh 或 build_db.py 解析源码，填充 SQLite
2. 生成 CONTEXT.md — 自动产出 ~500 token 的 L1 导航文件
3. 注入约束模板 — 初始红线规则（金额、安全、权限等）
4. AI 首次读取 — 新 AI session 先读 CONTEXT.md 建立心智模型

日常开发循环

# AI 开发完一段代码后 — 增量更新知识库（几秒完成）
cd .ai && python3 build_db.py /path/to/project --incremental --author 'AI-session-xxx'

# AI 按需查询
cd .ai && python3 query_db.py "这次循环改了什么"       # 查看最近变更
cd .ai && python3 query_db.py billing                  # 查 billing 约束
cd .ai && python3 query_db.py --sql "SELECT rule FROM constraints WHERE severity='forbidden'"

AI 有两种查询方式：

• 自然语言模式 — query_db.py "用户创建 token 的流程" → 自动匹配 SQL
• SQL 直传模式 — query_db.py --sql "SELECT ..." → AI 直接写 SQL 精确查询

交接给人类审查

# 生成变更摘要（diff 模式）
cd .ai && python3 export_md.py project.ai.db --diff -o CHANGELOG.md

# 生成人类审查清单
cd .ai && python3 export_md.py project.ai.db --review -o REVIEW.md

CHANGELOG.md 包含：最近变更列表、变更统计、可能违反约束的警告。

REVIEW.md 包含：变更概览、约束审查清单（标记 forbidden/critical）、变更影响面、审查确认 checkbox。

人类审查后交还给 AI

人类看完 REVIEW.md，确认 checkbox，然后 AI 继续下一轮开发。每次循环：

1. AI 改代码 → build_db.py --incremental 更新知识库
2. export_md.py --review 生成审查清单给人类
3. 人类确认 → 回到第 1 步

版本迭代完成时

# 导出完整 Markdown 文档
cd .ai && python3 export_md.py project.ai.db --output docs/PROJECT_SPEC.md

生成的 Markdown 包含：

• 项目概述与一句话定位
• 系统架构分层图（Mermaid）
• 完整 API 路由清单
• 数据库 ER 图 + 字段说明
• 关键业务链路（Sequence Diagram）
• 核心模块清单与依赖关系
• 所有 ADR 决策记录
• 全部约束（按严重度分级）
• 配置项清单
• 变更日志

脚本说明

scripts/build_db.py — 构建/更新知识库

python build_db.py <项目路径> [--output <db路径>] [--incremental] [--force]

功能：

1. 自动检测项目语言（Go/Python/JS/TS）
2. 扫描源码文件，提取模块、符号、API 路由
3. 解析数据库表定义
4. 收集代码中的决策注释和约束
5. 构建/更新 SQLite 数据库
6. 自动生成/更新 CONTEXT.md

增量模式（--incremental）：

• 只扫描变更过的文件（对比文件 mtime）
• 保留手工维护的 ADR 和约束
• 更新 change_log 表记录变更

scripts/query_db.py — AI 查询接口

# 自然语言查询
python query_db.py <db路径> "用户创建 token 的流程"

# SQL 直传（AI 专用）
python query_db.py <db路径> --sql "SELECT name, responsibility FROM modules WHERE layer='billing'"

# 指定输出格式
python query_db.py <db路径> "列出所有 API" --format json|table|md

AI 查询优先级：

1. 如果提供 --sql，直接执行 SQL
2. 尝试匹配预定义的自然语言模式
3. 退化为多表 LIKE 搜索

scripts/export_md.py — 导出完整 Markdown

python export_md.py <db路径> [--output <输出路径>] [--include-diagrams]

输出内容：

• 项目概述（meta 表）
• 架构分层图（modules 表 → Mermaid flowchart）
• API 完整清单（api_routes 表 → 表格）
• 数据库 ER 图（tables 表 → Mermaid erDiagram）
• 字段说明（tables.fields → 表格）
• 关键业务链路（data_flow 表 → Mermaid sequenceDiagram）
• 核心模块索引（modules 表 → 表格）
• ADR 决策记录（decisions 表 → 分级标题）
• 约束清单（constraints 表 → 按 severity 分组）
• 配置项（config 表 → 表格）
• 变更日志（change_log 表 → 表格）

scripts/init_project.sh — 快速初始化

bash init_project.sh <项目路径>

在项目下创建 .ai/ 目录，复制所有脚本，自动运行首次构建。

表结构

详见 references/schema.md。

核心 8 张表：

• meta — 项目元信息
• modules — 模块骨架
• symbols — 符号表
• api_routes — API 路由
• tables — 数据库表
• decisions — ADR 决策记录
• constraints — 业务约束
• config — 配置项

可选 2 张表：

• data_flow — 数据流文档
• change_log — 代码变更日志

最佳实践

给 AI 的建议

1. 首次接触项目 — 先读 CONTEXT.md，不要直接读源码
2. 查询精确信息 — 用 query_db.py --sql 而不是读整个 spec
3. 修改代码前 — 查 constraints 表中 related module 的 forbidden/critical 规则
4. 修改代码后 — 运行 build_db.py --incremental 更新知识库
5. 需要交接时 — 运行 export_md.py 生成完整文档

给人类的建议

1. 查看项目全貌 — 直接读 docs/PROJECT_SPEC.md
2. 查看决策历史 — 读 PROJECT_SPEC.md 的 ADR 章节
3. 查看红线 — 读约束清单中标记为 forbidden 的条目
4. 手工补充 ADR — 可以在数据库中直接 INSERT 到 decisions 表

适用场景

• 复杂项目的 AI 辅助开发
• 跨 session / agent 的工作交接
• 团队共建项目（不同人负责不同模块）
• 新人（人类或 AI）快速上手
• 代码审查前的结构了解
• 项目文档自动化维护