本地开发指南

先弄清边界，再动代码。

给准备改 OpenRelix 的人看：从哪下手、什么不能进仓库、改完怎么验证、出问题先查哪条链路。

先看懂名词 看全景图 看技术原理 按改动找文件

这是本地开发的主入口；稳定规则看 AGENTS.md，详细检查命令看验证矩阵。

名词解释

看架构图前，先把这几个词对齐。

state root 最容易混：它是 OpenRelix 的应用根目录，不是源码仓库。

state root：OpenRelix 应用根目录

重点

这里保存 OpenRelix 的本地应用数据：工作窗口记录、复盘、登记册、生成的面板文件、缓存和日志。它属于私有运行态，不进 git，也不进 npm。测试时用 AI_ASSET_STATE_DIR 指到临时目录。

repo：源码仓库

可提交

源码仓库只放可复用的工程逻辑：安装代码、脚本、模板、公开技能、测试和开发文档。

host home：AI 工具目录

工具拥有

这些目录归 Codex / Claude 自己管，里面有配置、历史记录、会话文件和原生上下文。OpenRelix 会谨慎读取，只在启用时写受控摘要块。

工作窗口：一段连续工作

整理单位

OpenRelix 会把 AI 工具里的活动整理成工作窗口。后续摘要要靠它判断哪段时间做了什么、在哪个项目、来自哪个工具。

overview-data.json：面板数据文件

可重建

本地面板只读这份生成 JSON。不要让面板直接翻 AI 工具原始文件，也别让它到处读私有运行态文件。

工程架构图

先看工程层级，再看本地数据怎么变成页面。

技术词只在能对应到真实文件、字段或命令时保留；第一次出现时，会顺手解释清楚。

全工程架构图：输出在上，host 在下

这张图把 host（运行 AI 的工具）放在最下面，因为它是来源层；repo（源码仓库）保存可复用逻辑，state root（OpenRelix 应用根目录）保存私有运行数据，面板和 host summary（写给 AI 看的摘要）都是生成结果。

记住这条边界：只读 Codex / Claude 自己的历史和会话文件；只写私有本地数据目录；面板和摘要都能重建；源码仓库只放可复用工程逻辑。
技术原理

这里讲具体实现：窗口怎么采、记忆怎么选、面板为什么只读一份数据。

下面每个概念都能落到真实文件、命令或输出路径。绕不开的术语，会在旁边解释清楚。

新同学先弄清三件事：文件放哪、面板怎么生成、哪些内容会写回 AI 工具

刚上手通常先卡在三件事：哪些文件可以提交、面板数据从哪来、为什么只有少量摘要会写回 Codex / Claude。

新增文件放哪里

加文件前先判断归属：工程文件可以提交，个人运行文件不能提交。

可以提交的工程文件 安装代码、脚本、模板、技能、测试和脱敏文档放源码仓库。 repo: install/ scripts/ templates/ .agents/skills/
不能提交的个人运行文件 原始工作记录、登记册、日志、缓存和生成报告，都留在本地数据目录。 state root: raw/ registry/ reports/ runtime/
可以写回 AI 工具的摘要文件 只写回受控的简短摘要，不写回原始工作记录。 scripts/sync_host_memory_summary.py

本地面板从哪里来

面板展示不对时，就按这条链路从 AI 工具记录一路查到最终 HTML。

读取 Codex / Claude 的工作记录 优先读 Codex 本地接口；不可用时，再读历史文件和会话文件。 Codex app-server / history.jsonl / sessions/*.jsonl
整理成工作窗口 工作窗口就是一段连续工作；会保留来源、项目路径、输入和会话标识。 scripts/collect_codex_activity.py 生成面板要读的数据文件 把工作窗口、复盘、登记册和摘要合成一份稳定 JSON。 reports/overview-data.json
打开 HTML 面板 静态页面只读 overview-data.json，不直接翻原始私有文件。 reports/panel.html

哪些内容会写回 AI 工具

本地可以保留很多记录，但只把短而有用的摘要写回 Codex / Claude。

待筛选的本地记录 候选内容包括稳定规则、排障步骤、模块映射和反复出现的偏好。 registry/memory_entries.jsonl
只选真正有用的摘要 优先选择可复用、还新鲜、优先级高的内容；一次性噪声留在本地。 scripts/openrelix_overview/memory_context.py 生成给 AI 看的短摘要 入选内容会被压缩成一小段摘要，方便下次 AI 工具读取。 scripts/build_codex_memory_summary.py
其他记录继续留在本地 复盘和原始工作窗口仍可检索，但不会塞进下次对话的提示里。 state root/reviews/ raw/windows/
窗口采集

一个工作窗口是怎么采出来的

采集脚本只读 AI 工具的本地文件或接口，统一整理后只写入 state root（OpenRelix 应用根目录）。

  • 默认模式：activity-source=auto，先试 codex app-server --listen stdio://（Codex 本地线程接口），失败再回退到本地文件。
  • Codex 文件回退：读 CODEX_HOME/history.jsonl（历史索引）和 CODEX_HOME/sessions/**/*.jsonl（会话事件），再按 session id（会话标识）拼成窗口。
  • Claude 来源：读 CLAUDE_HOME/projects/**/*.jsonl（项目会话记录）和 CLAUDE_HOME/history.jsonl（历史记录）。
  • 统一输出：写 raw/daily/<date>.json（当天汇总）和 raw/windows/<date>/*.json（单窗口文件），保留 ai_host（来源工具）、cwd（项目路径）和 session/thread id（会话或线程标识）。
scripts/collect_codex_activity.py OPENRELIX_ACTIVITY_SOURCE OPENRELIX_ACTIVITY_HOST
记忆选择

为什么不是所有记忆都会进 AI 工具

OpenRelix 本地能存更多，但写给 AI 的上下文要少而准，因为上下文空间有限，噪声会影响后续工作。

  • 权威来源：registry/memory_entries.jsonl 是当前记忆登记册；旧的 memory_items.jsonl 只做兼容 fallback（旧数据兜底）。
  • 筛选规则：优先保留可复用规则、排障路径、模块映射、稳定偏好；问候、一次性测试和无结论窗口会降级或丢弃。
  • 注入策略：injection_policy（是否写给 AI 的策略）只有 global_context（通用上下文）和 project_context（项目上下文）会进入候选。
  • 预算控制：global（通用）最多约占摘要预算 10%，project（项目）最多约占 30%，再按 priority（优先级）、heat（复用热度）和 freshness（新鲜度）排序。
scripts/openrelix_overview/memory_context.py scripts/build_codex_memory_summary.py runtime/host-context/memory_summary.md
面板契约

为什么面板不直接读历史文件

面板是本地静态页面，应该读稳定的生成数据，不应该自己到处翻原始私有文件。

  • 构建入口：scripts/build_overview.py 读取 registry（登记册）、reviews（复盘）、raw（原始窗口）、consolidated（整理结果）等来源。
  • 稳定契约：reports/overview-data.json 是面板数据契约；展示层只消费它，避免 UI 和底层文件格式强耦合。
  • 可见产物：reports/panel.html 是最终本地面板；如果页面看起来旧，先确认打开的是哪个 state root（OpenRelix 应用根目录）下的产物。
  • 检索增强：runtime/openrelix-index.sqlite3 是可重建 SQLite index（本地搜索索引），删除它不能影响 raw、registry 或 consolidated 源数据。
scripts/build_overview.py reports/overview-data.json reports/panel.html
代码入口

按改动类型找文件，别靠眼熟乱搜。

OpenRelix 的模块边界比较清楚。多数改动应该收在下面一两行里，别一口气横扫安装器、面板、记忆策略和发布配置。

安装器

安装参数、档位、后台任务

安装、卸载、定时、shell 命令、LaunchAgent（macOS 后台任务配置）行为变化时看这里。

  • install/install.sh
  • install/npm-bin.js
  • ops/launchd/
  • install/templates/
运行路径

state root（OpenRelix 应用根目录）、host home（AI 工具目录）、配置

新脚本只要需要路径，就优先走 runtime module（运行路径模块），不要自己重新拼。

  • scripts/asset_runtime.py
  • runtime/config.json
  • AI_ASSET_STATE_DIR
  • CODEX_HOME
Host 采集

Codex / Claude 活动输入

读取 app-server（Codex 本地线程接口）、history（历史记录）、session（会话文件）或 Claude transcript（会话记录）的逻辑在这里。

  • scripts/collect_codex_activity.py
  • raw/daily/
  • raw/windows/
  • ai_host
记忆上下文

哪些注入，哪些留本地

看 scope（作用范围）、injection policy（是否写给 AI 的策略）、priority（优先级）、heat（复用热度）和预算，不要退回旧的 durable/session 说法。

  • scripts/openrelix_overview/memory_context.py
  • scripts/build_codex_memory_summary.py
  • scripts/sync_host_memory_summary.py
  • registry/memory_entries.jsonl
概览和面板

报告数据、静态 HTML、展示文案

`overview-data.json` 是 renderer（渲染器）的 contract（数据契约）；不要让面板直接读 raw（原始数据）/ runtime（运行态）文件。

  • scripts/build_overview.py
  • scripts/openrelix_overview/
  • reports/overview-data.json
  • reports/panel.html
文档和站点

公开说明和可视化指南

文档和截图必须通用、脱敏，并和当前版本及 changelog 口径对齐。

  • README*.md
  • docs/*.md
  • docs/*.html
  • docs/changelog/v0.x.html
验证方式

按改动类型选检查，别上来就跑一堆命令。

小文案或 HTML 改动，重点看隐私、空白、本地预览和包内容。只有碰到脚本、安装器或共享数据契约时，再扩大验证范围。

改前

先看当前有哪些改动

先知道工作区里已经有什么，避免顺手清掉别人的无关改动。

git status --short --branch
每次都跑

隐私和空白检查

这两条先挡住最容易出事的点：私有数据进仓库、patch 空白污染。

python3 scripts/check_personal_info.py git diff --check
Python / 安装器

编译、单测、shell 语法

改脚本、安装器辅助逻辑、runtime config（运行配置）或 shell 入口时跑这一组。

python3 -m py_compile scripts/*.py install/*.py python3 -m unittest discover -s tests zsh -n install/install.sh scripts/*.sh
概览链路

改面板数据时用临时应用根目录

只有改报告数据、面板渲染、记忆展示或标签时才跑。它不会碰真实 OpenRelix 应用根目录。

STATE_DIR="$(mktemp -d /tmp/openrelix-validation.XXXXXX)" AI_ASSET_STATE_DIR="$STATE_DIR" python3 scripts/build_overview.py python3 -m json.tool "$STATE_DIR/reports/overview-data.json" >/dev/null
公开表面

包内容和本地预览

改 docs/site、包白名单、发布或可见 HTML 时用这一组。本地预览优先走 HTTP。

npm pack --dry-run --json python3 -m http.server 8766
隐私红线

凡是能指向某台机器或真实私有任务的内容，都别进仓库。

OpenRelix 的价值来自公开 repo（源码仓库）和 private state（私有状态）分开。这个边界不是事后清理，而是产品能力的一部分。

  • 不要提交原始 Codex / Claude history（历史记录）、session（会话文件）、transcript（会话记录）、运行日志、生成报告或真实 registry（登记册）行。
  • 不要加入密钥、token、Cookie、账号标识、私有组织名、内部 URL 或未脱敏报错。
  • 不要写死个人 home 路径；用 runtime config（运行配置）、参数或环境变量。
  • 公开文档、包内容、fixture（测试样例）、release asset（发布附件）里不要放真实私有面板截图。
好的公开样例，本来就应该普通。

用合成路径、小 fixture（测试样例）、通用项目名和短脱敏片段。样例只需要说明契约，不需要证明真实工作流。

python3 scripts/check_personal_info.py
本地排障

页面看着不对，先查真实产物。

代码改动看着正确，不代表生成面板、包内容或公开页面已经对。先验用户真正会看到的页面和文件。

现象 常见原因 先查什么
面板还是旧文案 source（源码）改了，但 `reports/panel.html` 没重建，或打开了另一个 state root（OpenRelix 应用根目录） AI_ASSET_STATE_DIR="$STATE_DIR" python3 scripts/build_overview.py
记忆摘要没有更新 host context（AI 可读上下文）关闭、`CODEX_HOME` 不对，或 sync（同步）只保留了 host-owned（AI 工具拥有）内容 python3 scripts/sync_host_memory_summary.py --print-json
npm 包里出现奇怪文件 `package.json` files 白名单过宽，或生成文件放进了 repo npm pack --dry-run --json
采集结果为空 app-server（Codex 本地线程接口）不可用、host home（AI 工具目录）串了，或所选日期确实没有活动 openrelix doctor --app-server-check
浏览器打不开 file URL 本地 file 安全策略挡住页面或资源 python3 -m http.server 8766
文档入口

先看这份图解，需要细节时再打开详细文档。

这份 HTML 是本地开发的图解入口；下面是更完整的参考资料，不必一开始全读完。

全部 HTML 文档 开发者详细指南 系统概览 技术方案 数据契约 验证矩阵 隐私与分发边界 发布检查清单