LumiForge

LumiForge 是面向研究工作的多用户 Linux 工作区。当前版本提供浏览器工作台、 项目与文件管理、对话式 Agent、Wiki/PDF 文献库、Overleaf 风格写作区、Git 管理、定时任务和本地账户边界。

当前正式标记版本是 LumiForge v1.0.0-beta1，发布形态为可信内网 Beta。 后端只监听回环地址，LAN 代理绑定一条明确的内网地址；它不适合直接暴露到公网， 也不声称可以隔离敌对租户。

该发布原点收口了对话回溯栏遮挡与悬停恢复、Wiki 精确返回原会话、微信完成总结/ 会话路由和 Codex CLI 动态契约验证。Codex 协议未验证时只隔离 Codex 后端，不再击穿 Wiki、Writing、Git、OpenCode 或全局工作台。

dev 上的 2026-07-20 成熟检查点进一步让宽屏轮次轨贴合会话列左缘，把 Wiki 笔记三种模式 统一为 16px 页边距，并让 H1-H6 与正文使用相同的 23.25px 行高和零额外上下间距； 微信桌面完成总结可回退到已绑定 owner chat，帮助中心提供完整使用手册。两套指定 Chromium 矩阵各记录 189 个用例（184 pass、5 个显式环境 skip、0 fail），共生成 208 张当前构建截图且无未决 P0/P1。完整审查见 docs/reviews/2026-07-20-rail-wiki-notes-wechat-final-regression.zh-CN.md。 正式 tag lumiforge-v1.0.0-beta1 仍指向原发布提交；后续检查点不会自动推送远端。

2026-07-22 多账户微信与界面修复候选

当前候选把微信连接从管理员专属服务改为任意已登录账户可见的自助扫码入口。桥实例、 项目/会话 route、主动总结偏好、owner chat 与 iLink 凭据私有副本都按 LumiForge 账户 隔离；QQ 与飞书仍保持管理员专属。代码级验收只使用假传输与合成凭据，不连接真实微信 或读取真实消息。完整操作与安全边界见 《微信连接使用手册》。本版本未上线语音输入， 音频自动转写仍是未来计划。

同一候选还让会话索引轨在不改变对话居中的前提下贴左显示，并在宿主空间不足时隐藏； Wiki 笔记 H1–H6 改用 1.25 倍字号的行高，正文继续使用原有 1.55 倍节奏。

2026-07-21 多用户生产候选检查点

本检查点补齐服务器全局部署所需的不可变 release、数据迁移校验、systemd 249 单元、 回滚入口和测试服/正式服隔离。源码 checkout 固定为当前用户的测试实例，使用 18090/18888 和用户本地数据根；正式实例使用 release 自带 Bun、8090/8888、 /srv/lumiforge/{data,cache,config,state} 与 /opt/lumiforge 下的只读版本目录。两者 可并行运行，启动、PID、端口、数据、构建和停止边界互不复用。

浏览器现在对管理员和普通成员统一执行登录门。默认会话只进入 sessionStorage， “在此设备上保持登录”默认关闭；退出后立即失去受保护服务权限。预置脚本可以幂等创建 11 个 Linux 用户对应的 LumiForge 账户，不重置既有成员密码，并要求新成员首次登录 改密。账户设置支持验证后换绑邮箱、SMTP 自助找回和管理员重置成员密码；普通成员的 工作区、Writing、笔记、会话和 Agent 路径继续按账户隔离。账号预置入口只使用当前 release 自带的固定版本 Bun，不依赖服务器 PATH 中是否另有 Bun。

上线前候选已通过隔离 release 运行、虚拟 SMTP、管理员/普通成员流程、完整源码门禁， 以及两轮指定 Chromium 矩阵：每轮 192 个用例（185 pass、7 个显式环境 skip、 0 fail/error），两轮共 220 张截图。该证据只证明源码和发布机制已经就绪，不代表本机 已完成 /opt、/etc、/srv 安装、真实账号写入或真实邮件投递。管理员必须按 生产 systemd 部署 完成受控激活，并按 账号预置与邮件投递 验收真实账户； 不得把源码 checkout 直接当作正式服。

后端完整测试会在 SyncEvent 用例组开始前清除前序测试留下的临时项目数据库，并在每个 临时实例结束时立即释放连接，避免数据库扫描成本随测试规模持续增长。当前完整后端套件 为 2,806 pass、15 项显式 skip、0 fail；七个 SyncEvent 用例在全套中的单例耗时保持在 0.14–0.27 秒，而不是依赖放宽超时掩盖测试隔离问题。

第一次受控全局激活在 systemd 启动 BFF 时触发了权限回归：一次性迁移锁错误地写到 服务账户不可写的 /srv/lumiforge 父目录。安装事务按设计完整回滚，源数据与候选数据 清单一致，未留下活动正式实例。当前源码把迁移锁与迁移标记一同放入服务账户拥有的 LUMIFORGE_STATE_ROOT；Linux 回归以不可写公共父目录和四个独立持久化根复现正式布局， 并与后端类型检查及 9 项生产安装/迁移/回滚生命周期测试共同通过。失败的旧 release 不得再次激活，正式服必须从包含本修复的新提交构建新的不可变发布物。

真实普通账号首次登录又暴露了第二处生产权限边界：/etc/lumiforge 既保存 root-only EnvironmentFile，也是运行时约定的托管配置命名空间。旧安装器把目录设成 root:root 0700，导致服务 UID 枚举托管配置时收到 EACCES，GET /provider 返回 500。 安装器现在使用 root:<service-group> 0750 目录，仍把 lumiforge.env 固定为 root:root 0600；可选的六个 JSON/JSONC 托管配置只有显式设为 root:<service-group> 0640 才会加载。启动前检查会拒绝不可读文件、符号链接和不可穿过 目录，映射安装回归还验证幂等重装能修复目录模式而不放宽私有环境文件。目录原始 owner/mode 进入事务收据，失败升级和显式回滚会恢复原边界，首次安装失败则移除新建的 空配置目录。

LumiForge v1.0.0-beta1 发布基线

2026-07-17 基线把已经验收的 LumiForge 浏览器产品整理为可独立克隆的 Linux 源码仓库。它包含工作台与多标签文件预览、Markdown 内链预览、图片缩放与拖动、 Wiki/PDF 阅读、Overleaf 风格 Writing、Git 管理、OpenCode/Codex Agent 后端、 本地账户绑定与历史数据导入、模型和 Skills 管理、帮助中心、定时任务、微信入口及 资源观测能力。

同日更新将侧栏中的编程代理历史导入块移出日常工作流，历史导入 API 继续保留； 对话上下文改为完整展示“主题、进展、最近三轮”三项用户概览，并拒绝只指向报告或 文件路径的摘要内容。

会话标题区现在提供 Codex 风格的对话检查点菜单，可以跳到任意用户轮次，并在提交前 选择“代码和对话”“仅对话”或“仅代码”三种回滚范围。回滚后的撤销始终基于第一次 回滚前的快照，用户在再次发送消息前可以安全切换范围；文件写入和多文件补丁同样使用 冲突检查、同文件系统暂存、原子发布与反向恢复，尽量避免中断造成半写状态。

文件、会话、Wiki 与 Writing 现在共用同一套内链分类规则：工作区文件在中央预览 标签中打开，Wiki 页面和 PDF 留在 Wiki 阅读视图，Writing 与其他同源页面使用应用 内导航，只有真实外部网址才交给浏览器新标签页。文件预览标签同步采用 Chrome 风格 的连续标签面、分隔线、20px 圆形关闭区和延迟文件详情提示。

浏览器运行时按完整 Chromium 进程树的 PSS、私有内存、JS 堆和 DOM 稳态共同验收， 不使用会重复计算共享映射的 RSS 总和判断泄漏。当前受控 Chrome 回归中的普通会话 PSS 约为 550 MiB；20 次会话切换、40 次文件预览开关、长对话、长 Wiki 和静置恢复 峰值约 647 MiB，所有采样必须低于 1 GiB。文件预览只由稳定的会话侧栏注册 一次 PDF 完成回调，共享 Markdown HTML 缓存同时受条目数和 16 MiB 字节预算限制。

Wiki 笔记的实时与源码模式统一使用锁定版本的 MIT CodeMirror 6，不再加载 Muya。 实时模式按当前活动行显示或隐藏 Markdown 标记，并直接装饰 H1-H6 的字号、字重、 间距和主题强调色；阅读模式继续使用共享安全 Markdown 渲染器。三种模式围绕同一份 Markdown 往返，画布在浅色和深色主题中分别固定为白色和近黑色，反复切换不会维护 两套编辑历史或遗留全局浮层。

Wiki 阅读器在打开 PDF 前会通过账号隔离的轻量状态接口重新核对本地文件，不会把 缺失、永久不可用或列表状态已过期的文献交给 PDF.js。精修页面或 PDF 请求失败时， 错误只显示在 Wiki 阅读区，并提供刷新或返回文献库操作；有效 PDF 的完整读取、字节 范围请求和账户边界保持不变。文献库“刷新”也会同步重建精修页面索引，已删除页面不 再被旧缓存继续列出。

对话框底部控制栏使用稳定的 28px 高度。模型按钮按实际可见名称紧凑展开，左右各保留 4px；思考强度始终直接显示本地化文字而不是抽象图标，速度仅在非默认值时展开； 知识库入口收紧到 24px 宽，权限、引导和 Skills 保持固定命中区。窄屏会优先收起次要 文字，不让隐藏内容占据空白，同时保留悬浮提示、焦点、键盘操作和零横向溢出。

Wiki 默认进入“我的资料”，管理员部署的 Markdown、PDF、索引和文献数据库统一读取 系统级共享目录；Linux 默认是 /srv/lumiforge/wikibuild。共享语料对所有 LumiForge 账号只读可见，收藏、阅读状态、笔记和上传内容仍按账号隔离。笔记的 H1-H6 在编辑与 阅读模式中保留明确的字号和层级色，但行高与正文一致且没有标题专属上下间距；画布 固定为中性白色或 #121212。

这个仓库只包含安装、运行、验证和维护上述功能所需的源码与文档。本机账户数据、 工作区、Writing 文档、Wiki/PDF 语料、模型、凭据、日志、构建产物和 Agent 控制面 不会随 Git 发布。完整 Wiki 文献数量取决于部署者单独配置的 Wikibuild 数据服务。

本目录本身就是 LumiForge 唯一的可发布源码根目录；不要从它所在机器的外层工作区 复制旧版源码或运行产物来补充安装包。远程默认分支为 dev，每个发布检查点都必须 同时通过仓库清单校验、类型检查、生产构建和一次隔离的干净克隆验证，确保其他用户 只靠本仓库即可完成安装。

2026-07-17 审查后纯净检查点

这个检查点把 Wiki 文章/PDF 可用性处理和统一的 Composer 控件几何纳入远程 dev。 机器清单当前覆盖 3,767 个安装、运行、源码、测试和维护候选文件；外层旧工作区、 .ai-loop、.agents、真实环境配置、账户数据、语料、依赖目录、日志和审查媒体均不 属于发布内容。隔离克隆必须在不借用外层文件的情况下完成冻结依赖安装、类型检查、 生产构建和代表性测试；验证器会把依赖安装、构建和测试的临时文件统一放入一次性 克隆目录，并显式隔离 Bun 安装根、包缓存及全局目录；退出后不得在源码 checkout 的 test/ 中遗留原生编译缓存，也不得读写外层工作区或旧版运行目录的依赖状态。

首页“新建对话”现在会先取得账户专属的私有聊天工作区，再初始化 SDK/Sync。子工作区 首次 bootstrap 的状态变化不会再重入当前目录选择器；新对话直接刷新、首条消息跳转、 移动端重载和缓存淘汰压力均保持在同一私有目录，且不显示项目路径、文件或 Git 界面。

管理员“更新管理”现在只请求当前选中的 LumiForge 服务器，并同时携带该服务器的基础 认证与当前账户会话，不再绑定页面启动时的静态地址或回退到默认 4096 端口。首次状态 请求不可达时，错误会留在设置对话框内显示统一的不可用提示和重试操作，不再击穿全局 错误页；重试成功后继续使用原有的三层手动更新流程。

该历史检查点仍按可信内网 Beta 而非最终稳定版验收。宽范围 Chromium E2E 为每个 Worker 启动独立的临时后端和数据目录，强制开启账户边界并先完成管理员登录；页面、SDK 和清理请求始终使用同一个已选服务器与账户会话。工作区切换期间的 Agent 组合器状态也 提供同步默认值，不会再因全局数据替换的短暂空值进入错误页。当前完整 Chromium 产品 矩阵为 170 passed, 5 skipped；5 项均为显式环境跳过，矩阵退出后不遗留 Vite、 Playwright 或临时后端进程。

2026-07-18 最终运行检查点

本检查点在重启后的真实受管运行态重新验收 BFF、LAN 代理和可选 KB：健康检查通过， LAN 验证为 5/5，带账号边界的 Wiki 返回 5,391 条索引、5,381 份有效 PDF、10 条永久 不可用记录、零缺失和 5,577 个页面，PDF 字节范围请求返回有效内容。共享语料没有再次迁移。

选定 Chromium 的六个关键场景全部通过，并人工对照检查 15 张桌面、移动端、浅色和深色 截图；会话检查点与三种恢复范围、Composer 控件、Wiki 默认“我的资料”、H1/H2 排版及旧 历史入口移除均符合当前契约。完整仓库验证和一次从空依赖开始的隔离克隆同时通过安装、 双端类型检查、生产构建与代表性测试。运行稳定后 BFF、代理和 KB 合计约占 0.5 GiB RSS， 未发现本任务遗留的 Chromium、Vite、临时后端或异常僵尸进程。

编码代理异常恢复的产品对照、当前保护和稳定版剩余边界见 docs/reviews/2026-07-18-coding-agent-resilience-audit.zh-CN.md。 检查点覆盖范围化回退、用户修改冲突、事务式补丁、原子状态写入、损坏隔离、严格 PID 身份与服务收养；它仍不承诺断电级多文件事务、敌对租户隔离或公网部署。

纯净 checkout 首次执行 scripts/lan-stack.sh start 时，会固定进入源码测试配置： BFF 使用 127.0.0.1:18090，LAN 代理使用具体私网地址的 18888，业务数据、cache、 config 和 state 使用当前用户的本地根；它拒绝生产角色、生产端口和指向正式数据根的 持久化路径。启动器同时会按根 packageManager 的 精确版本创建 .bun/bin/bun：优先原子复制同版本宿主 Bun，否则下载对应官方 release 并核对 SHASUMS256.txt。构建和 BFF 都直接执行这个项目私有二进制，Web 资源链接及 显式 LUMIFORGE_WEB_ROOT 只指向当前 checkout 的 packages/app/dist，不会因宿主 PATH 或其他 checkout 的 Bun 漂移到旧前端。隔离回归会从完全不存在 .bun/ 的状态 验证该启动契约，真实 .env.local 仍只属于部署机器且不会进入 Git。

正常启动会对前端源码、工作区依赖、锁文件、Bun/平台和 VITE_* 构建输入计算指纹。 输入未变时直接复用已验证的 dist；需要构建时先写入暂存目录，通过完整性检查后再 原子替换，并保留上一份可用构建用于失败恢复。实测强制重建峰值约 2.54 GiB RSS，紧接 的暖启动约 4.5 MiB RSS；scripts/lan-stack.sh build 和 rebuild 均不会读取 .env.local。

运行脚本把 PID 与 Linux 进程启动标识绑定，过期、复用、僵尸或不匹配记录不会被用于 终止进程；跨命名空间无法看到 PID 时保留待核验记录，adopt 只会收养端口、工作目录、 命令和当前 checkout 全部匹配的进程。BFF、代理和可选 KB 都在独立会话中运行，不依赖 启动脚本的进程组存活；部分启动失败只回滚本次新建的服务。阅读批注、 偏好/迁移状态和 Web 更新状态通过同目录原子写入发布，损坏批注会先保留私有 .corrupt 副本再恢复。上述恢复路径均 有故障注入测试，不依靠广泛 pkill 或清空用户数据。Wiki 工作台状态遇到 JSON 截断时 也会先按 0600 权限逐字节保留 .corrupt 副本，再为当前账号返回可继续保存的空状态； 其他账号不受影响，而超限或普通 I/O 错误仍然失败关闭。

Git 管理在紧凑侧栏中保留明确的变更/历史模式选择。Review 使用稳定文件身份维护实时 更新前后的滚动位置，行级和文件级批注会贴合可用宽度，不再裁掉操作区。Question 停靠栏 首次拖动前同步测量实际高度，撤销/重做会强制同步当前会话消息。终端打开后只在原始交互 仍有效时执行延迟聚焦；用户已经返回组合器后，异步创建或定时重试不会再抢走焦点。

会话区的 Review 标签现在拥有明确的侧栏生命周期：当它是侧栏内最后一个标签时，关闭 Review 会同时收起空侧栏；若仍有文件、上下文或 Git 图标签，侧栏会保留并切换到剩余 内容，不会丢失用户正在查看的预览。

移动端终端沿用同一套可访问状态与布局契约：关闭后按钮、面板隐藏状态、inert 交互 边界和零高度同步生效，不会继续撑高页面；再次打开会恢复原终端和可见高度。

浏览器回归以组合器控件的可访问名称为状态契约，并通过当前模型短列表直接选择常用 模型。独立 Wiki 流程使用已选测试服务器并完整模拟全局健康、事件与知识请求，不再向 默认 4096 端口泄漏无关探测。

移动端设置保留紧凑图标栏，并为每个入口提供可访问名称和原生悬停提示；顶部命名 下拉菜单与当前设置页同步，可通过键盘切换且不会扩大对话框宽度。UI 包统一依赖 包级 Solid JSX 配置，Vite 启动与构建不再输出 Toast 文件的过时 pragma 告警。

2026-07-18 十五项交互成熟检查点

本检查点集中修复对话索引、Composer 几何与顺序、回答耗时、历史 Codex 延续、 MP4 和内部链接预览、Wiki 默认集合与笔记编辑器、AI 阅读连续性、Wiki/Writing 返回、 标题栏工具所有权以及预览/Git 标签边界。预览区域现在只包含真实文件标签；Git 管理 固定在文件树侧栏，不会再被恢复为预览标签。

全量点击审查还修复了 Git 实时差异滚动、无文件夹会话首帧目录/SDK 竞态、Composer 过早允许发送、陈旧健康状态和文件 @mention 异步选中竞态。当前选定 Chromium 证据套件 31/31，通过并生成 52 张截图和 31 段视频；独立内存门禁 1/1，静置 PSS 约 613 MiB。逐项根因、源码边界、测试和资源数据见 docs/reviews/2026-07-18-fifteen-item-browser-bug-audit.zh-CN.md。

2026-07-20 旧构建与缺陷包收尾检查点

源码部署现在强制使用当前 checkout 的项目私有 Bun 和显式 Web 根；即使机器上还存在 其他 LumiForge/Aether checkout，受管重启也不会再返回它们的旧前端。Scheduled Work 老库会通过正式幂等迁移补齐六张表和十个索引，结构性数据库故障按低频 WARN 失败关闭， 设置页在 5xx 时显示可重试错误而不是伪装成空列表。

Codex 运行链路会隔离保留目录和畸形 Skill，只对明确的只读目录 RPC 执行一次 App Server 恢复，mutation 不自动重放；服务端保留脱敏后的真实阶段错误，并为 pre-RPC 失败写入不含 prompt/输出的审计记录。注册关闭状态、过期认证记录清理和首轮会话标题 也进入账户隔离契约。

Wiki 标题现使用受限 KaTeX 并在解析失败时保留原文；最近项目会过滤内部、失效和越权 目录，支持只移除列表记录；非 Git 项目显示结构化状态和安全初始化入口。设置 footer、 移动端路径/时间、Wiki 返回原会话、导入 Claude 会话续用、默认桌面轮次轨及 Composer 首帧输入均有对应的单元或隔离 Chromium 回归。普通账户的 Git 越界拒绝也会收敛为 受控失败结果，不会以未处理 Promise 离开请求生命周期；资源事件读取会等待已排队的 持久化写入，避免短暂漏报。完整根因、文件、测试和剩余边界见 docs/reviews/2026-07-20-stale-serving-and-fixpack.zh-CN.md。

2026-07-20 导入会话与双轮浏览器验收检查点

冷启动直接打开窗口外的导入会话时，前端根会话列表曾在深链消息加载完成后再次裁剪 缓存，导致 API 已返回消息而会话区静默变空。当前同步会等待首次根列表，并在 40 个 会话的硬上限内保留正在使用的会话、祖先和后代；任何加载或渲染失败都会留在会话列内 显示可展开详情和真实重试，不再击穿整个工作台。存量 New session - <ISO> 和子会话 默认标题只在展示层转换为本地短日期，不重写用户数据或手工标题。

Wiki 笔记把正文 12-22px、侧栏 11-16px 和 720/940/1200px 画布统一到一个持久化 “显示”菜单，实时、阅读和源码三种模式共用。最近项目在源头过滤测试工作区与废弃 Aether 路径；Wiki 的“打开项目”会携带账户会话并精确恢复此前会话的 path、query 和 hash。帮助页目录链接保留当前 topic；Web 全局错误页的“重启”现在执行真实 reload， 不再是空操作，也不会触碰 CC Switch/Codex 登录状态。

最终生产构建在两套隔离 Chromium 上各完成 116 个操作、116 张截图、17 个区域和 10 组导航组合，均无失败；最终构建后的补充 E2E 为 26/26。类型检查、2,152 模块生产 构建、App 697+105、后端 2,783（15 项显式跳过）和 3,799 个发布候选边界检查均通过。 详细根因、变体路径、视觉证据、设置实际 12 个面板的说明和可信内网边界见 docs/reviews/2026-07-20-imported-session-and-dual-browser-acceptance.zh-CN.md。

2026-07-20 索引轨、Wiki 笔记与微信连接成熟检查点

宽屏会话的轮次索引轨现在固定在会话列左侧 8px，并只给正文保留 8px 安全间距； 1920、1100 和 600px 视口都没有横向溢出，390px 继续按移动端契约隐藏轨道。会话列表 不再为了跟随居中内容而浪费左侧宽度，多面板和居中状态使用相同几何。

Wiki 笔记实时、阅读和源码模式的左右边距统一为 16px。H1-H6 继续通过字号、字重和 主题色表达层级，但计算行高全部与 15px 正文相同，均为 23.25px；实时模式标题 padding 和阅读模式标题 margin 均为 0。浅色、深色和移动端状态都有指定 Chromium 回归。

微信桥单独保存账户所有者的真实聊天目标，不再要求先从微信成功进入某个项目会话。 桌面端完成事件会优先匹配同会话/同项目，再回退到最近绑定的 owner chat，并继续遵守 /summary on|off、去重、退避和失败降级。帮助中心新增《微信连接使用手册》，覆盖 扫码绑定、项目/会话路由、身份头、主动总结、自然语言入口、全部命令和常见问题。

最终构建通过双端 typecheck、2,152 模块生产构建、App/UI 测试、微信后端 11/11、 3,806 个候选文件的仓库边界检查和两轮完整浏览器矩阵。Round A 三 Worker 正序、Round B 单 Worker 反序均为 184 pass、5 个显式 skip、0 fail；两轮共 208 张截图。浏览器压力测试空闲稳定 PSS 约 630 MiB，峰值约 672 MiB。详细根因、机器可重算几何和发布边界见 docs/reviews/2026-07-20-rail-wiki-notes-wechat-final-regression.zh-CN.md。

组成

组件	位置	说明
Web 前端	packages/app	SolidJS、Vite、Writing 与 Wiki/Reader 界面
BFF/Agent 运行时	packages/opencode	Bun/Hono、账户、文件、Git、Provider、OpenCode/Codex 后端
SDK 与 UI	packages/sdk/js、packages/ui	前后端契约和共享组件
内置 Skills	.opencode/skills	账户初始化时复制的 20 个受控产品 Skills
源码测试入口	scripts/lan-stack.sh	在 18090/18888 构建并运行与正式服隔离的测试实例
生产发布	scripts/production、deploy/systemd	不可变 release、数据迁移、systemd 249 单元、安装与回滚
Wikibuild	外部服务	可选的共享 Wiki/RAG 语料与索引，不进入本仓库

环境要求

• 64 位 Linux
• Bun 1.3.14（启动脚本可从兼容宿主原子复制，或下载并校验官方 release）
• Git、Python 3.10+、curl、ss（通常由 iproute2 提供）
• Bubblewrap（bwrap）：普通账户的 Bash/Codex 进程隔离所必需
• 可选：Tectonic（LaTeX 编译）、Codex CLI（内置审计基线 0.145.0，其他版本先做动态 契约验证）、独立 Wikibuild KB 服务

Codex/ChatGPT 登录继续由 Codex 或 CC Switch 管理。CLI 版本变化不需要重新登录； 只有管理员明确要把已经变化的源登录同步到 LumiForge 私有凭据副本时，才运行 scripts/lan-stack.sh refresh-codex-auth。该命令只复制现有文件，不会调用 Codex 登录或退出。版本检查、手工接受、重启和回滚见 Codex App Server 运维。

Debian/Ubuntu 的系统依赖示例：

sudo apt-get install git python3 curl iproute2 bubblewrap

从干净仓库安装

git clone ssh://git@tmytimidly.com:222/CounterAttack/lumiforge.git
cd lumiforge
scripts/bootstrap-linux.sh --check
scripts/bootstrap-linux.sh
cp .env.local.example .env.local
chmod 600 .env.local

bootstrap-linux.sh 只检查依赖、安装锁定依赖并构建前端；它不会读取或创建 .env.local，也不会调用 sudo。

首次启动前编辑 .env.local：

1. 将 WORKPLACE_LAN_IP 改为服务器的一条具体私网地址，不能使用 0.0.0.0。
2. 保持测试端口 WORKPLACE_BFF_PORT=18090、WORKPLACE_APP_PORT=18888；不得复用 正式服 8090/8888。
3. 替换 LUMIFORGE_ADMIN_PASSWORD；默认管理员账户名是 tjz。
4. 保持 LUMIFORGE_ACCOUNT_BOUNDARY=on。
5. 确认账户存储和工作区位于 Git checkout 之外，且服务用户可以写入。
6. 如需完整 Wiki/RAG，配置独立的 WIKIBUILD_KB_API_URL 和 WIKIBUILD_PROJECT_ROOT；Linux 多用户部署应使用 /srv/lumiforge/wikibuild。

启动并检查：

scripts/lan-stack.sh start
scripts/lan-stack.sh status
scripts/lan-stack.sh test
scripts/lan-stack.sh profile

常用维护命令：

scripts/lan-stack.sh stop       # 仅停止由当前 checkout 记录的进程
scripts/lan-stack.sh restart    # 正常重启
scripts/lan-stack.sh recover    # 崩溃后清理本 checkout 的残留 PID/端口
scripts/lan-stack.sh adopt      # 严格核验并收养丢失 PID 记录的现有服务
scripts/lan-stack.sh build      # 输入未变时复用前端构建，不读取 .env.local
scripts/lan-stack.sh rebuild    # 强制暂存、验证并原子发布前端构建

完整安装说明见 Linux 干净安装与运行。 两套实例的端口、数据、Bun、PID、更新与回滚边界见 测试服与正式服运维对照。 多用户首次开通与邮箱/密码恢复见 账号预置与邮件投递。 版本库中的 bun.lock 由项目固定的 Bun 版本生成；Bun 1.3.14 会把默认 npm registry 规范化为空来源字段。正式发布构建会显式指定 registry.npmjs.org，仓库检查也会拒绝 把开发机的区域镜像 URL 写回可分发依赖图。Bootstrap 对冻结安装使用同一缓存最多重试 3 次，吸收单个 tarball 的瞬时断连或传输损坏，持续失败仍会停止。

面向服务器的正式实例不从源码 checkout 直接运行。它先构建带完整文件清单、项目私有 Bun、冻结依赖和前端指纹的只读 release，再由管理员将其安装到 /opt/lumiforge， 把运行数据迁到 /srv/lumiforge，并用两个 systemd 单元分别托管回环 BFF 与 LAN 代理。安装器默认只输出 dry-run；它不会自行提权，也不会停止无法确认归属的监听器。 准备、管理员交接、校验和回滚命令见 生产 systemd 部署。

数据和权限边界

• 当前 Beta 由一个 Linux 服务 UID 运行，LumiForge 在应用层隔离账户会话、工作区、 Knowledge、Reading、Writing 和 Agent 进程。
• 普通账户默认得到权限为 0700 的私有工作区，不能管理 Provider、共享密钥或其他 账户。管理员 tjz 可以为系统管理目的查看所有账户数据。
• 普通账户的 Bash 和 Codex 进程必须进入 Bubblewrap 文件系统边界；无法创建边界时 请求会失败关闭。
• 当前生产安装仍使用一个 Linux 服务 UID，并通过 LumiForge 账户、路径授权和 Bubblewrap 提供应用层边界；它不是敌对租户之间的 OS 安全边界。不可变 systemd 安装与原子回滚已经有受控入口，逐 UID Worker、签名更新和全局排空仍按 多用户安装与更新计划 分阶段实现。
• 不应把 Provider 凭据写进源码或 Git。管理员在运行时设置 Provider；浏览器只接收 脱敏状态。

Wiki/RAG

仓库包含 Wiki、阅读器和 RAG 的连接代码，但不包含本机的大型 Markdown/PDF 语料、 向量索引或 Wikibuild 虚拟环境。没有外部 KB 时，应用仍可启动，但完整文献检索不可用。 Linux 默认共享根是 /srv/lumiforge/wikibuild；迁移脚本只复制明确允许的 Wiki、文献、 PDF、解析结果、RAG 索引和必要数据库，不会复制 .env、Git、Python 环境或私有日志。 按 Wiki 共享文献库部署 完成复制、校验、 切换、回滚和清理，再通过 .env.local 指向共享根；不要把语料复制进 Git。

开发与验证

bun run dev                 # OpenCode/LumiForge CLI 开发入口
bun run dev:web             # Vite 前端开发服务器
bun run typecheck           # App 与后端类型检查
bun run build               # 前端生产构建
bun run test:app            # App 单元测试
bun run test:backend        # 后端完整测试
bun run test:clean-clone    # 临时 commit/clone 后冻结安装、构建与代表性测试
bun run verify:repo         # 干净仓库内容、脚本和代理测试

本地 Chromium E2E 应通过隔离运行器启动。运行器保留 Playwright 自己管理的浏览器缓存， 但会隔离宿主策略、报告目录和账户数据，并按唯一 owner 标记清理完整进程树：

NO_PROXY=127.0.0.1,localhost \
  bun run --cwd packages/app test:e2e:local -- \
  e2e/app e2e/files e2e/projects e2e/settings/settings.spec.ts \
  e2e/sidebar e2e/status --project=chromium --workers=2

不传测试路径时，Playwright 只发现 e2e/**/*.spec.ts 浏览器流程；同目录下使用 bun:test 的 *.test.ts 工具测试仍由 bun test 独立执行，不会被 Node 浏览器 运行器误加载。

新会话会原子保存当前模型和 reasoning 变体；刷新、切换会话或跨工作区返回时， 都会恢复该会话自己的选择，不会退回默认强度或泄漏到新会话。

浏览器回归遵循当前产品交互边界：文件只在组合器拖放区接收，会话分享位于标题的 更多菜单，共享 Review/文件面板按标签所有权断言。Question、Permission、Task、 Review 和定时 Agent 流程均由隔离的确定性测试模型驱动；技能启用和自进化开关具有 独立的可访问名称，测试不会再误操作相邻开关。

Chrome 内存回归会创建隔离测试项目并输出完整进程、堆和 DOM 证据：

cd packages/app
NO_PROXY=127.0.0.1,localhost no_proxy=127.0.0.1,localhost \
  bunx playwright test e2e/performance/browser-memory.spec.ts \
  --project=chromium --workers=1

Wiki 的 Obsidian 式 CodeMirror 回归使用真实 Chrome/Chromium，覆盖活动标题行、 H1-H6 层级、编辑保存、三种模式往返和编辑器根生命周期：

cd packages/app
NO_PROXY=127.0.0.1,localhost no_proxy=127.0.0.1,localhost \
  bunx playwright test e2e/wiki/wiki-obsidian-editor.spec.ts \
  --project=chromium --workers=1

Wiki 文章/PDF 可用性回归覆盖有效、缺失、永久不可用和陈旧文件状态：

cd packages/app
NO_PROXY=127.0.0.1,localhost no_proxy=127.0.0.1,localhost \
  bunx playwright test e2e/wiki/wiki-reading-availability.spec.ts \
  --project=chromium --workers=1

对话框控制栏回归会量测默认方形、非默认值展开、悬浮提示、键盘焦点和 320px 窄屏无溢出状态：

cd packages/app
NO_PROXY=127.0.0.1,localhost no_proxy=127.0.0.1,localhost \
  bunx playwright test e2e/prompt/composer-control-popovers.spec.ts \
  --project=chromium --workers=1

风险较高的 Agent 后端改动还应运行：

TMPDIR="$PWD/test" scripts/test-agent-harness-baseline.sh
TMPDIR="$PWD/test" scripts/verify-codex-upgrade-contract.sh

测试临时文件只能放在根目录 test/，完成后清理。提交前至少运行 bash scripts/verify-clean-repository.sh 和 git diff --check。

仓库边界

本仓库只保存其他用户安装、运行、验证和维护 LumiForge 所需的源码、锁文件、迁移、 许可证、脚本、测试和文档。以下内容不得入库：

• .env.local、API key、账户/session/auth 数据
• 工作区、Writing 项目、Wikibuild 语料和模型文件
• .ai-loop/、.agents/ 和 .opencode/ 中除受控 skills/ 外的本地 Agent 控制面
• node_modules/、dist/、日志、缓存、测试结果、截图和录屏

机器可读根目录清单位于 .repository-allowlist，完整规则见 仓库内容策略。清单中的私有环境文件、数据库、日志和 根目录审查媒体会被完整扫描；验证器不会因管道提前退出而漏掉位于长清单后部的违规项。

安全与许可证

请先阅读 SECURITY.md 和 账户/工作区边界。LumiForge 基于 OpenCode 的 MIT 许可源码演化；Overleaf 相关前端仅复用兼容边界内的行为和材料，详见 许可证边界。packages/app 保留其 AGPL-3.0-only 许可证；各目录的许可证优先适用于该目录。完整边界见 许可证说明，CodeMirror 等第三方前端依赖的许可证随发布 NOTICE 保留。