核心模块设计
接入层
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
任务系统的数据中枢（平台运行时仅 PostgreSQL）。
主要表：jobs · token_usage · job_steps · job_events · settings · wiki_state · wiki_runtime · api_tokens
特点：进程级共享 SQLAlchemy Engine（QueuePool）· PostgreSQL schema/migration · 测试期 SQLite 兼容层
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、报告 |
Harness 执法层
Harness 是 memex-server 的质量执法层，职责是在 Agent 产出内容之后、进入下一阶段之前，进行确定性质检、阻断违规、生成修复任务。Harness 不改引擎规范，只执行和补充引擎规范。
harness.rules
可配置的 HCK 规则引擎（YAML 定义，热改无需发版）。
每条 HCK 规则定义：检测器 ID、阻断级别（block / warn-only / report）、repair spec（策略 + gene）。
当前主要规则：
| 规则 | 职责 |
|---|---|
| HCK14 | PN 语义对齐（断言是否对应 PN 原文） |
| HCK15 | Corpus QC 门禁 |
| HCK17 | 模板占位符残留检测 |
| HCK19 | 语言纯度（非中文 wiki 混入中文） |
| HCK20 | 多 PN 合并引注检测 |
harness.detectors
零 LLM 确定性检测器，秒级扫全库，输出标准 evidence dict 供 review 层使用。
检测维度：无引文信号、PN 格式错误、页面 lint、质量分布、wikilink 完整性、gitignore 合规等。
harness.phase_gates
阶段门禁：boot/grow/butler 各阶段收尾时的质量硬门，决定任务是否能推进到下一阶段。
harness.repair_planner
从 evidence dict + HCK repair spec 生成修复任务，写入 queue.md P1/P2，由 butler 下一轮接力执行。
harness.corpus_qc
语料质量门禁：检查 doc_final.md 预处理质量（epub/pandoc 残留、PN 坐标合法性等），阻断 PN 分配前的脏语料。
supervisor.*
独立于建站 agent 的 LLM 监工判定层：
supervisor.decision— LLM 读失败上下文，出SupervisionDecision（exempt / 续跑 / 规约 / escalate）supervisor.executor— Harness 带护栏执行监工决策（防抖 + 审计，同 job+phase 干预 ≤ N 次）
幻觉检测层（hallucin）
memex.hallucin 是 2026-07 新增的独立质量治理模块，负责 Wiki 页面的幻觉检测与修复任务调度。
详见：幻觉检测模块设计
核心设计
异步解耦：主建站流程（grow/butler）不等待幻觉检测结果，通过队列文件异步触发，不影响建站速度。
信号来源：读取引擎已写的 logs/butler/actions.jsonl，识别 NEW1/RCH 建页事件，无需引擎改动。
两层检测：
| 层次 | 工具 | Token | 触发 |
|---|---|---|---|
| 确定性层（Phase 1） | check_citations.py + pn-source.json 覆盖率 | 0 | scheduler_tick |
| 语义深核（Phase 2） | /hallucin-sweep skill（LLM QUO23） | 按需 | 仅 UNCERTAIN 项 |
模块组成
| 文件 | 职责 |
|---|---|
hallucin/models.py | PendingItem / ScanFinding / DeepPendingItem / SweepResult |
hallucin/queue.py | HallucinQueue（harvest + pending）+ HallucinDeepQueue（UNCERTAIN 暂存） |
hallucin/scanners.py | CitationScanner + PnScanner + Quo23Scanner + ScannerRegistry |
hallucin/sweep.py | HallucinSweep：编排检测 + UNCERTAIN 路由 + run_deep() + verify_repaired() |
hallucin/repair.py | RepairWriter：发现 → queue.md P2，直接用引擎 gene 代码 |
agent/hallucin.py | run_hallucin_sweep()（零 LLM）+ run_hallucin_deep_check()（LLM 深核） |
API 执行与调度层
api.sse
当前系统中最复杂的执行协调模块，负责任务实时输出流、后台流水线执行、阶段切换、超时/恢复/重试。
api.scheduler
任务计算资源调度器拆成两个独立循环：
scheduler_loop默认每 5 秒工作守恒地派发任务，执行全局并发、单用户公平性、 lifecycle step 模型路由与 profile quota 准入reconciler_loop默认每 30 秒处理孤儿恢复、wedged/overlong 清扫、完成判定和 模型配置漂移，避免慢对账阻塞派发- 幻觉检测队列 harvest（sweep_hallucin_queue，2026-07 新增）：为活跃 grow/butler wiki harvest 新建页事件并触发后台扫描
Service 的构建入口统一为 life。每次执行只运行一个明确的 EGG/BRH/GRW step；
step checkpoint 后释放模型租约并开启新 Agent session。完整说明见
生命周期执行、模型路由与并发。
api.job_process / api.job_runner
将长任务放到独立子进程（python -m memex.api.job_runner）中运行，避免阻塞 Web worker。
api.auth
Bearer Token 认证 · token 生成/列举/吊销 · admin/user 角色区分 · auth middleware。认证数据与业务数据共用同一数据库。