目录与数据布局

仓库目录结构

memex-server/
├── src/memex/
│   ├── api/          # HTTP 接入层（routes / sse / auth / scheduler）
│   ├── web/          # Web GUI（Jinja2 模板）
│   ├── core/         # Core 编排层（service / task_manager / wiki_execution …）
│   ├── agent/        # Agent 执行层
│   ├── harness_genes/
│   ├── harness_skills/
│   ├── cli.py        # CLI 主入口
│   └── mcp_server.py # MCP 主入口
├── tests/
├── docs/             # 原始技术文档
├── docker-compose.yml          # 生产（Traefik + TLS）
├── docker-compose.local.yml    # 本地开发
├── Dockerfile
└── pyproject.toml

Wiki 数据根目录

以 MEMEX_WIKIS_DIR 为根：

MEMEX_WIKIS_DIR/
├── .uploads/              # 上传文件暂存
├── logs/server/           # 服务日志
└── <owner>/
    └── <slug>/
        ├── EGG.md         # egg 阶段蓝图
        ├── BIRTH.md       # boot 阶段种子层
        ├── GROW.md        # grow 阶段进展记录
        ├── corpus/        # 原始语料
        ├── docs/wiki/     # 生成的 wiki 页面
        │   ├── pages.json
        │   └── backlinks.json
        └── local/
            ├── memory/
            │   ├── boot_summary.md
            │   └── grow_baseline.md
            └── state/
                ├── grow_state.json
                ├── *.pid              # 进程 PID 文件
                └── serve.wanted       # 预览服务期望状态标记

关键业务流：上传到 Job 创建

POST /api/v1/upload  (或 upload-url / MCP / CLI)
  │
  ├─ 文件落地 .uploads/
  ├─ core.service.submit_book()
  │   ├─ 生成/校验 slug
  │   ├─ 内容指纹去重检查 → 命中则克隆已有成果（秒级返回）
  │   ├─ 未命中 → scaffold_wiki() 初始化 wiki 目录
  │   └─ TaskManager.create_job() → status=queued
  └─ 返回 {job_id, wiki_slug, target_dir}

关键业务流：Job 调度与执行

Web App 启动
  └─ scheduler_loop()（后台协程）
       │
       ├─ 扫描等待队列
       ├─ 检查：全局并发上限 / 单用户配额 / 活跃锁 / orphan/wedged
       └─ launch_job_runner()
            └─ 独立子进程：python -m memex.api.job_runner
                 └─ SSE 推送事件 → 前端实时订阅

运行时关键文件

文件	作用
local/state/*.pid	进程 PID，用于进程存活检测
local/state/serve.wanted	预览服务期望状态，patrol 循环据此自愈
local/memory/boot_summary.md	boot 阶段验收依据
local/memory/grow_baseline.md	grow 阶段基线
local/state/grow_state.json	grow 进度状态，支持中断恢复
logs/butler/actions.jsonl	butler 行为结构化日志