把服务器上的 Codex 工作，变成可检索、可整理、可追溯、可操控的个人知识工作台

证据策略

• 外部资料优先使用英文一手来源：官方手册、官方文档、项目仓库和许可证。
• 本机调查以 metadata、文件时间线和必要的 Stop 审计片段为限；没有把完整对话、凭证、私有域名或环境变量写入报告。
• GitHub 星标、push 时间和软件版本是 2026-07-11 的生态活跃度快照；质量判断同时依据源码、文档与实测。
• Codex app-server、remote-control 等接口仍可能变化，报告把它们视为高级集成接口，不作为第一阶段的数据事实源。[S1]

事件格式已经足够支撑高质量浏览

本机 rollout 已观察到 session_meta、response_item、event_msg、工具调用、补丁、token 统计与子线程关系等事件。现有工具已经能把 Codex 的 exec_command、apply_patch 等映射为可读视图。[S10]

官方能力的边界

以上官方边界来自 Codex 官方手册，核验日期 2026-07-11。[S1]

4.1 会话浏览与导出

4.2 知识门户与全文搜索

4.3 运行观测与 trace

5.1 核心网页：AgentsView + Tailscale

• AgentsView 原生发现 Codex sessions，首次运行建立本地 SQLite 索引，并在 127.0.0.1:8080 提供网页；支持会话搜索、文件变更、token / cost 统计与实时刷新。[S9]
• 单用户场景优先直接安装一个 binary，以用户级 systemd service 常驻；Docker 只在希望额外限制文件读取范围时采用。
• Tailscale Serve 把 loopback 页面映射为 tailnet 内 HTTPS。MacBook 浏览器只需加入同一 tailnet；无需 Cloudflare、FRP 或公网端口。[S4]
• AgentsView 读取 live sessions 与归档目录；已经缺失的 155 条只显示 metadata-only，不能凭 SQLite 还原正文。

5.2 操控入口：Cursor Remote SSH

• 当前服务器已经运行 Cursor Remote SSH server，说明 MacBook 到服务器的直接工作链路已经可用。
• Cursor 打开的是服务器真实目录，不产生第二份项目副本；编辑 research/、projects/、wiki/ 后立即作用于事实源。
• Remote SSH 同时提供远程 terminal、端口转发和服务器侧 extension；适合 tmux、Git、Codex CLI、脚本和服务管理。[S33]
• 因此“网页直接写文件、运行 shell”的复杂控制台暂不需要。未来若明确需要纯浏览器写入，再比较 SilverBullet 或 code-server。

5.3 Quartz v5 与 MacBook Obsidian 的关系

5.4 可选组件何时才加入

• Quartz：希望不用打开 Obsidian，也能在浏览器查看 Wiki、反向链接和图谱时加入。
• claude-replay：需要把某一次会话做成可分享或教学的单文件 HTML 时临时运行。[S10]
• SilverBullet / code-server：明确需要浏览器直接编辑 Markdown 或运行开发环境时再评估。
• OTel / Phoenix / Langfuse：出现成本、延迟、失败分布或评测问题时再加入；当前不解决核心需求。

MADR-lite 最小字段

---
title: 服务器作为唯一事实源
date: 2026-07-11
status: active
project: codex-knowledge-hub
evidence:
  - session_id: "<codex-session-id>"
  - report: "research/.../2026-07-11-codex-web-knowledge-hub.html"
---

## Context
Codex 会话、Wiki、研究和项目都已经位于服务器；MacBook 需要稳定访问和编辑。

## Decision
服务器保存权威文件；浏览器、Obsidian 和 Cursor 都只是访问或同步视图。

## Rationale
避免多个副本争夺事实源，也能继续使用服务器算力、路径和现有自动化。

## Consequences
Obsidian 需要独立同步；Cursor Remote SSH 可直接编辑；Quartz 只能做只读构建。

即使完全不部署 Quartz，MADR-lite 仍然有价值，因为 Obsidian、Cursor、普通文本工具和 Git 都能直接读取。Quartz 只负责把这些 Markdown 变成更适合浏览器阅读的页面。[S24][S26]

知识 Vault 同步方案怎么选

$HOME/.codex/                      # Codex live source
$HOME/.local/share/codex-archive/ # 版本化会话归档，不传播删除
$HOME/.local/share/agentsview/    # AgentsView SQLite / cache
$WORKSPACE/wiki/                  # Obsidian / MADR-lite 知识源
$WORKSPACE/research/              # Cursor 直接访问；Quartz 按需纳入
$WORKSPACE/projects/              # Cursor 直接访问；不做 Obsidian 全量同步
$WORKSPACE/projects/codex-knowledge-hub/ # 成熟后再放 service / Quartz config

每阶段的硬性验收门

• 归档：删除源端测试文件后，历史归档仍存在并能恢复；禁止 --delete 类镜像语义。
• 会话：至少核验一条普通会话、一条含工具/补丁的会话、一条缺失 rollout 的 metadata。
• 远程：MacBook 在同一 tailnet 能打开 AgentsView；Cursor 能编辑服务器真实文件并使用远程 terminal。
• 同步：只运行一种主同步机制；测试双端编辑冲突、离线修改和删除恢复。
• 决策：每篇只记录一个决定，证据链接可达；没有价值的临时选择不进入 Wiki。
• Quartz（若部署）：375 / 768 / 1280 / 1440 px 无横向溢出；搜索、wikilink 与反向链接可用；构建不会修改源 Markdown。

建议的周期任务

资源与运维重量

AgentsView 的单 binary + SQLite、Tailscale、一个文件同步进程以及 Quartz 静态构建都属于轻量组件；对这台 60 GiB 内存服务器几乎没有资源压力。保持架构轻量的关键是不要提前加入数据库型 Wiki、OTel 后端、public staging 和多套反向代理。

建议按这个顺序执行

1. 今天第一步：为 $HOME/.codex/sessions、history、state 与 memory-hook 审计建立不传播删除的版本化归档，并恢复一条 fixture。
2. 今天第二步：在 loopback 启动 AgentsView，用 77 条现存 rollout 验证解析、搜索、文件变更和 155 条 metadata-only 会话表现。
3. 今天第三步：用 Tailscale Serve 给 MacBook 浏览器开放 AgentsView；Cursor Remote SSH 保持现有链路。
4. 本周：在 wiki/decisions/ 写 3–5 条 MADR-lite；如果确实希望在 MacBook Obsidian 中整理，再选择 Sync + Headless 或 Syncthing。
5. 使用一段时间后：只有当“浏览器里看 Wiki”成为高频需求，才部署 Quartz；只有分享某次会话时才运行 claude-replay。

最小可交付范围是：归档 timer、AgentsView、Tailscale Serve、现有 Cursor Remote SSH、wiki/decisions/ 与一套恢复/浏览器验收脚本。这个范围已经覆盖会话浏览与检索、知识整理与溯源、服务器事实源和 MacBook 操控；Quartz 与同步客户端都可以在核心闭环稳定后独立加入。

1. OpenAI Codex ManualCODEX_HOME、本地状态、OpenTelemetry、app-server、remote-control 与 Remote 能力边界。
2. OpenTelemetry Semantic Conventions for Generative AIOTel GenAI 语义约定与可迁移观测数据模型。
3. OpenTelemetry Collector独立 Collector 的接收、处理与导出架构。
4. Tailscale Serve在 tailnet 内提供 HTTPS / 反向代理服务。
5. Tailscale Funnel公网入口能力及其与 tailnet-only Serve 的差异。
6. Cloudflare Tunnel无需开放源站入站端口的隧道架构。
7. Cloudflare Access Controls身份、策略与 deny-by-default 外部访问控制；仅在未来需要外部协作时评估。
8. Docker bind mounts: read-only原始会话目录使用 ro bind mount 的官方语义。
9. kenn-io/agentsviewCodex 支持、SQLite FTS5、SSE、Docker、HTML export、loopback 默认值与外部 origin/auth 配置。
10. es617/claude-replayCodex rollout 解析、自包含 HTML、书签、裁剪、secret redaction，以及嵌入 payload 的隐私警告。
11. nogataka/codex-viewer专用 Codex Web viewer 与实时刷新原型。
12. HizTam/codex-history-viewerVS Code 内的 Codex 历史搜索、时间线和笔记能力。
13. coding_agent_session_search跨 coding-agent SQLite/BM25/语义检索设计。
14. liaohch3/claude-tap代理层上下文与 API trace 查看，适合高敏感诊断。
15. OpenLITcoding-agent hooks、OpenTelemetry-native traces、工具/文件/subagent 事件与观测后端。
16. Arize Phoenix DocumentationOTel-native LLM tracing、evaluation 与调试。
17. Langfuse Self-hosting自托管 LLM observability、trace、prompt、evaluation 组件。
18. Quartz v5 / DocumentationObsidian Markdown、wikilinks、backlinks、graph、search、private pages 与静态构建。
19. Pagefind静态站构建后全文索引，无需运行搜索服务器。
20. SilverBullet浏览器 Markdown Wiki、双向链接、查询与脚本。
21. Material for MkDocs成熟技术文档站生成与导航能力。
22. Docmost / Docs多人协作 Wiki、权限与自托管组件。
23. Outline / Hosting docs团队知识库、协作、权限与自托管。
24. MADR: Markdown Architectural Decision Records上下文、选项、决策、后果等版本控制友好的 ADR 模板。
25. Log4brains从 Markdown ADR 生成静态决策站点。
26. Architecture Decision Record organizationADR 方法、工具和实践索引。
27. OWASP Logging Cheat Sheet日志数据最小化、敏感字段和安全日志实践。
28. Obsidian Headless服务器命令行运行 Obsidian Sync / Publish，以及 Vault 配置边界。
29. Obsidian Publish官方托管发布、站点范围与精选内容工作流。
30. Cloudflare Pages静态站构建与托管，可承载 public-reviewed Quartz 输出。
31. Obsidian Headless Sync / Obsidian SyncHeadless open beta、持续同步、remote vault、选择性同步、E2EE、版本历史，以及同一设备不要同时运行 desktop Sync 与 Headless Sync 的官方约束。
32. Syncthing Getting Started / Folder Types两设备点对点同步、设备 ID、共享文件夹与 send / receive 模式。
33. Visual Studio Code Remote SSH远程打开真实目录、服务器侧 extension、terminal、端口转发和 SSH 配置；本机同时实测到 Cursor Remote SSH server 正在运行。
34. 本机 rollout 删除取证责任 session 的 memory-hook Stop 审计快照、state_5.sqlite 只读查询、155 条缺失 path 与 36 个父目录 mtime 交叉核验；冻结于 2026-07-11。
35. Codex rollout compression source / migration 40压缩写入、校验、持久化、删除顺序，以及 migration 仅新增 history_mode 列的源码证据。