架构概览

memex-server 是一个 Wiki 生成编排服务，核心职责是把书籍或文本语料组织成可恢复、可审计、可监督的 Agent 执行流水线，驱动引擎依次完成 egg → boot → grow → butler 四个阶段。

分层结构

用户 / 外部系统
  ├─ CLI: memex
  ├─ Web UI: FastAPI + Jinja2
  ├─ HTTP API: /api/v1/*
  └─ MCP: FastMCP
            │
            ▼
      接入层（Adapter）
  ├─ memex.cli
  ├─ memex.web
  ├─ memex.api.routes / sse / auth / scheduler
  └─ memex.mcp_server
            │
            ▼
      Core 编排层
  ├─ core.service          ← 多入口共享服务层
  ├─ core.task_manager     ← 任务状态数据中枢
  ├─ core.wiki_execution   ← 阶段完成语义（磁盘证据）
  ├─ core.phase_review     ← 阶段质量复核
  ├─ core.wiki_runtime     ← 预览/Butler 运行态管理
  └─ core.job_diagnostics  ← 任务诊断
            │
            ▼
      Harness 执法层（地方立法）
  ├─ harness.rules          ← HCK 规则引擎（可配置 YAML 规则）
  ├─ harness.detectors      ← 确定性质检（零 LLM，秒级扫全库）
  ├─ harness.phase_gates    ← 阶段门禁（阻断/放行/warn-only）
  ├─ harness.repair_planner ← 问题 → queue.md P1/P2 修复任务
  ├─ harness.corpus_qc      ← 语料质量门禁
  ├─ supervisor.*           ← 监工 agent（LLM 判定层，独立于建站 agent）
  └─ hallucin.*             ← 幻觉检测异步队列（2026-07 新增）
            │
            ▼
      Agent / 执行层
  ├─ agent.egg              ← run_skill：拉起 Claude Agent SDK 会话
  ├─ agent.qc_review        ← /qc-review skill 封装
  ├─ agent.hallucin         ← /hallucin-sweep skill 封装
  ├─ cli.phase              ← grow/boot pipeline 阶段编排
  └─ api.sse / job_runner   ← 子进程执行 + SSE 事件流
            │
            ▼
      外部引擎层（只读挂载，MEMEX_ROOT，不 vendoring）
  ├─ GROW.spec.md / BIRTH.spec.md ← 阶段规格（6600+ 行）
  ├─ .claude/skills/             ← slash command skill 定义
  ├─ wiki/scripts/butler/        ← 可执行工具脚本（corpus_search.py 等）
  └─ skills/gene/                ← 可组合 gene（QUO/FIX/COR/CHK 系列）
            │
            ▼
      数据面
  ├─ PostgreSQL（jobs / token / event / runtime）
  ├─ wiki 工作目录（磁盘证据）
  └─ 日志目录（logs/butler/、logs/harness/）

引擎与 Harness 的职责边界

memex 的内容质量治理遵循宪法/地方立法原则：

层	比喻	职责	能改吗
引擎（MEMEX_ROOT）	宪法	定义 wiki 内容的规范、阶段流程、gene 词汇表	需发版，只读挂载
Harness（memex-server/harness/）	地方立法	执行质量门禁、检测违规、生成修复任务、监督 agent	热改，无需发版

新增执法能力（HCK 规则、检测器、幻觉扫描）优先在 Harness 侧实现，验证后通过 RFC 流程推入引擎层。

多 Agent 架构

系统存在三个独立的 agent 层次，互不阻塞：

层次 1（job 级并行）
  调度器同时拉起多个 job runner → 每本书一个独立 Claude SDK 会话

层次 2（会话内 Task fan-out）
  每个 grow/butler 会话拥有 Task 工具（allowed_tools 含 "Task"）
  主 agent（贵模型）维护索引/决策，子 agent（flash 模型）独立执行小任务
  MEMEX_MAX_SUBAGENTS=4 控制并发上限

层次 3（监工 agent，supervisor）
  独立于建站 agent 的 LLM 判定层
  建站 agent 卡住/反复失败时出 SupervisionDecision
  harness 带护栏地执行（防抖 + 审计）

核心架构原则

• 单一编排核心：memex.core.service 为多入口共享服务层，四种接入方式都调它
• 接入层薄封装：HTTP / MCP / CLI 只适配协议，不重复实现业务编排
• 以磁盘证据为准：阶段完成不依赖 Agent 自述，依赖 wiki_execution 验收落盘产物
• 异步任务后台化：长任务由独立子进程执行，前端通过 SSE 获取实时事件
• 发布生命周期解耦：Web 与 Worker 使用独立 Compose project 和 generation；Web 切流不重启长任务
• 引擎外置（只读）：引擎不 vendoring；每个 Worker generation 挂载按 commit 固定的 worktree
• 确定性优先：质量检测先跑零 token 的确定性工具，只把模糊案例交 LLM（省 token、速度快）
• 异步解耦：幻觉检测、QC review 等后置治理工作通过队列异步执行，不阻塞主建站流程

技术栈

层次	技术
语言	Python 3.12
HTTP 框架	FastAPI + Uvicorn
CLI	Typer
模板	Jinja2
MCP	FastMCP
异步	asyncio + subprocess
数据库	PostgreSQL（所有平台部署）
ORM/查询	SQLAlchemy Core
部署	固定基础设施 Compose + 独立 Web/Worker rolling projects + Traefik