OpenProgram · Engineering design

Repository structure

本页定义代码与文档的归属边界、超长文件的拆分条件，以及当前可实施的整理顺序。目标是降低修改时需要同时理解的范围，不以文件数量或单一行数作为拆分目标。

Status: Current design
Audience: Maintainers and reviewers
Scope: Source layout and docs navigation
Excluded: Product behavior and public API changes

1. 设计原则

按产品职责归属

Python 产品行为放在 openprogram/ 的产品域；Web、CLI 和 Desktop 分别保留在自己的 workspace。跨界调用通过稳定入口完成，不复制实现。

按可验证边界拆分

只有当一段代码具有独立输入、输出和测试入口时才移动。单纯因为文件长而引入 mixin、manager 或 facade 不属于有效拆分。

公共接口保持稳定

移动实现时保留现有 import、CLI 参数和运行行为。调用方无需在同一批次迁移，结构改动可以单独回滚。

当前设计与实施记录分离

本 HTML 只描述长期结构；具体提交、测试结果和未完成工作记录在独立的 implementation ledger 中。

2. 顶层职责

OpenProgram/
  openprogram/   Python 产品运行时与服务端
  web/           Next.js Web 客户端
  cli/           Ink 终端客户端
  desktop/       Electron 宿主与桌面检查
  tests/         Python 测试：层级 / 产品域
  docs/          用户文档与设计记录
  scripts/       可直接执行的开发、验证和发布脚本
  tools/         可导入的仓库维护工具
  examples/      面向用户的最小可运行示例
  skills/        随产品分发的技能
  config/        产品运行时构建清单
  experiments/   可复现实验，不参与产品运行时
  references/    参考实现快照与本地比较语料
  promo/         发布与宣传源文件
  site/          静态站点入口

.github/、.codegraph/ 和 .superpowers/ 是仓库基础设施，不是产品运行时目录。根目录只保留项目元数据、入口文档、依赖锁和构建配置；可执行的 .py、.ps1 和 .sh 工具进入 scripts/ 或对应 workspace 的 scripts/。

tests/ 中的 Python 用例使用 tests/<layer>/<product-domain>/test_*.py，按最强实际依赖选择层级。具体边界由 Testing system 和仓库 contracts 维护。

3. 超长文件处理

文件	现状	决定	边界
`openprogram/cli.py`	参数声明与命令执行共处，约 2,000 行	本批实施	把现有 parser 定义移到 `openprogram/_cli_parser.py`；`openprogram.cli.build_parser` 继续可用。
`desktop/main.js`	窗口、更新、WebView、标签转移和菜单共处，接近 4,000 行	后续批次	按窗口生命周期、原生 WebView、标签转移、菜单四个既有域移动；先等待当前 Desktop 修改合并。
`web/lib/desktop-bridge.ts`	类型、视图状态和标签转移共处，接近 2,000 行	后续批次	先补执行级测试，再拆为公共类型、view state、tab transfer，并由原文件 re-export。
`runtime.py`、`runner.py`、`resource_governance.py`	文件较长，但核心状态机和不变量集中	不按长度拆	只有出现可独立验证的职责或重复实现时再拆；不引入 mixin 层。
大型检查脚本与 native runtime	测试场景多或包含同步的上游实现	保持现状	优先改善测试数据和局部 helper，不用生产目录规则约束测试及 vendor 文件。

4. 文档信息架构

用户文档

start/、install/、capabilities/、interfaces/、models/、integrations/、server/、reference/。进入公开导航和搜索。

当前设计

reference/design/。按产品域展示当前有效的设计说明；UI 文档按基础、会话编辑、浏览器标签、设置目录、工作区分组。

实施记录

与设计页相邻的 implementation ledger 以及 reference/design/plans/，只记录提交、门禁、剩余任务和实施历史，不把执行过程写进概念设计。

内部计划

docs/superpowers/ 保留在 Git 中供维护者追溯，不进入公开站点。仍被当前设计引用的 reference/design/plans/ 继续发布，并保持独立 Plans 分组。

5. 采用与拒绝

选择	结论	原因
move-only 模块拆分	采用	可以通过兼容 import 和 parser 快照证明行为不变。
通过导航分组整理文档	采用	避免批量移动文件造成旧链接失效。
按固定行数自动拆文件	拒绝	行数不能证明职责独立，容易产生只转发调用的模块。
为拆分引入新的依赖注入框架	拒绝	现有模块函数和显式参数足以保留边界。
一次重排整个仓库	拒绝	会扩大冲突范围，难以区分结构变化与产品行为变化。

6. 验收合同

openprogram.cli.build_parser 保持可导入，完整命令树与拆分前一致。
openprogram/cli.py 不再包含大段 parser 声明，命令执行仍位于该文件。
公开文档构建不包含 docs/superpowers/，所有公开链接有效。
设计导航按产品功能分组；源文件路径保持不变。
Git tracked 顶层目录必须在结构 contract 中声明，根目录不出现开发脚本。
有效 README、技能和安装说明不得引用已删除的源码根路径。
一级 Python 包的目录 README 与 __init__.py docstring 保持同步。
每个结构批次独立提交，先通过直接相关测试，再进入规格与质量复核。

实现状态和可复现命令见 Repository structure implementation ledger。