核心模块设计
接入层
CLI (memex.cli)
主入口：src/memex/cli.py，提供 memex 命令族。
相关模块：cli.py · cli_phase.py · cli_skill.py · cli_client.py · cli_runtime.py · cli_config.py
HTTP API (memex.api.routes)
核心入口：memex.web.create_web_app / memex.api.routes / memex.api.sse
职责：文件上传、URL 导入、任务创建/查询、SSE 实时日志流、认证与多用户隔离、后台调度触发。
Web GUI (memex.web)
- Jinja2 模板，前后端不分离，页面偏"控制台"
- 页面：
/·/job/{id}·/settings·/factory·/auth·/docs/api
MCP Server (memex.mcp_server)
- 通过 FastMCP 暴露面向 Agent 的工具，直接调用
core.service，不经过 HTTP - 工具：状态查询、提交书籍、查询 job、列表、统计、页面列表、搜索
Core 编排层
core.service
多入口共享的薄服务层，是当前"框架无关服务接口"的核心。
职责：
- 统一处理 wiki 根目录与 owner 目录解析
- 书籍提交、slug 生成与去重
- 上传目录管理
- 统一抛出
ServiceError
core.task_manager
任务系统的数据中枢（SQLite / PostgreSQL 双后端）。
主要表：jobs · token_usage · job_steps · job_events · settings · wiki_state · wiki_runtime · api_tokens
特点：WAL 模式 · 进程级共享 SQLAlchemy Engine（QueuePool）· 兼容 migration
core.wiki_execution
阶段完成语义的关键模块。确保 CLI/API/GUI 对"什么叫完成"使用相同规则——Agent 自己说完成不算，落盘才算。
职责：
- 定义 phase completion 的磁盘证据规则
- 解析
BIRTH.md、GROW.mdphase section - 判断 pipeline 下一阶段、grow debt
- 检测人工确认暂停信号
core.phase_review
阶段质量复核模块，关注的不是"是否执行结束"，而是"产物是否达到质量下限"。
职责：
- 对 egg/boot/grow/butler 结果做复核
- 检查页面质量、结构完整性、引用、short page 等
- 生成
suggested_actions，结合 harness rules 形成 pass/warn/fail 结论
core.wiki_runtime
运行态与文件系统状态之间的桥梁。
职责：
- 预览服务进程管理（PID 文件、wanted flag）
- Butler 运行时状态管理
- Traefik preview route 动态写入
- 容器路径重定位
其他支撑模块
| 模块 | 职责 |
|---|---|
core.job_queue | 排队与调度选择 |
core.job_diagnostics | 任务诊断 |
core.suggested_actions | 建议动作 |
core.preview_artifacts | 预览索引产物构建/检查 |
core.logging_setup | 服务日志落盘和清理 |
core.security | 路径与输入安全校验 |
core.model_config | 模型 profile 配置 |
core.harness_* | 规则、能力、QC、报告 |
API 执行与调度层
api.sse
当前系统中最复杂的执行协调模块，负责任务实时输出流、后台流水线执行、阶段切换、超时/恢复/重试。
api.scheduler
任务计算资源调度器，周期性扫描等待队列，执行：全局并发配额控制 · 单用户公平性控制 · 孤儿任务恢复 · wedged running 清扫。
api.job_process / api.job_runner
将长任务放到独立子进程（python -m memex.api.job_runner）中运行，避免阻塞 Web worker。
api.auth
Bearer Token 认证 · token 生成/列举/吊销 · admin/user 角色区分 · auth middleware。认证数据与业务数据共用 同一数据库。