仓库结构实现

本 仓库结构设计 定义归属与依赖边界。本页把这些边界映射到源码位置、兼容要求和验证。迁移顺序与既往审查输出可查 Git 历史，不代表当前验收结果。

实现映射#

来源： 应用 workspace, 核心以及 维护脚本.

兼容性与剩余归属#

openprogram/cli/__init__.py 在 checkout 或安装包中解析规范 CLI 应用，并拒绝已加载的外来同名规范包。 openprogram.cli, python -m openprogram及 CLI 模块入口保持兼容；内部文件移动必须保留行为。

openprogram/webui/ 仍是 Server 兼容入口。包括 Agent profiles 在内的路由实现位于 apps/server/openprogram_server/_webui/routes/ 并按产品域分组。兼容包解析应用模块，不重复实现。

scripts/install-release.sh 仍为公开安装入口，其实现位于 scripts/release/。根 npm workspace 与 lockfile 协调 Web、Desktop 和 CLI 依赖。使用方不能假定每个应用下都有独立 lockfile 或单独依赖安装。依赖补丁保持应用清单、根 workspace 锁文件和实际安装版本一致。同一依赖的重复更新分支都保留提交 ancestry，版本变更只应用一次。锁文件保留安装后消费者仍需的传递依赖条目，包括可选包依赖图；安装器成功退出本身不能证明消费者可以加载。干净安装后同时检查公开消费者的实际导入。合并后的源代码在发布前执行统一的验证清单。

默认本地运行时使用端口 18100 和 ~/.openprogram。已安装 App 验收使用 /Applications/OpenProgram.app；仓库布局变更必须同时保留打包、已安装 import 和源码 checkout 执行。

验证#

本 仓库合同 检查目录归属、应用位置与兼容要求。在仓库根目录运行既有合同：

uv run --locked --extra dev python -m pytest -q tests/contracts/repository/test_repository_layout.py

布局合同本身不验证运行行为。实现变更还需操作受影响的公开 CLI 或 HTTP/WebSocket 入口，构建 wheel 并在 checkout 外检查 import，以及验证受影响应用的打包。使用 贡献者检查 和 测试系统设计 选择必要门禁。

文档修改后先构建再检查链接；检查器读取 docs/_site/，而不是 Markdown 源码：

python -m scripts.docs_site.build
python -m scripts.docs_site.checklinks

模块组织与文件操作安全

功能模块同时拥有自己的类型、状态和私有辅助函数。目录大小是审查信号，不是任意增加层次的理由。Web 浏览器、标签页、桌面、执行和文件职责有明确模块。服务端文件操作和轮次文件历史使用不同包。认证集中账号与登录编排；自更新集中验证、修复与交付。测试保留执行层级并增加功能目录，发现机制包含嵌套测试。

大型源码文件按可独立测试的职责拆分，公开入口保持稳定。不为满足行数限制而引入通配转发、重复实现或动态源码执行。原生终端渲染和职责一致的路由集合与混合用途工具目录分别审查。

文件操作合同

• 剪贴板条目标识来源项目。在显式跨项目传输操作存在之前，不支持跨项目粘贴。
• 变更作用于选中的目录项，绝不隐式重命名或删除符号链接目标；不安全路径失败时两个条目都不变。
• 在支持时提供可恢复删除。导出未保存草稿不代表授权删除唯一确认保留的副本；浏览器下载未确认时保留本地草稿。
• 刷新文件使用不变的查询重复当前搜索，并保留请求代次隔离。

验收

公开 WebSocket 回归测试覆盖符号链接。挂载式 Web 测试覆盖项目剪贴板归属、当前搜索刷新和草稿保留。模块移动保留收集到的测试身份及已安装 import。源码与测试清单记录目录计数和大型文件职责。发布前运行全部贡献者 Python 层级、Web 测试/typecheck/check/build、受影响 CLI/Desktop 检查、文档链接与 wheel import 验收。规格和质量审查独立进行。

模块职责

执行控制在同一服务实例上区分激活、取消、等待、分支操作、恢复和安全点。执行存储区分记录、命令、事件、状态 blob、投影和结束修复，同时保留一个 store 及其事务边界。任务执行、资源管理、Agent 生产执行、Workflow runtime 和 session 存储采用相同方式：操作模块共享归属实例和规范模块状态。

Desktop main 组合窗口与 IPC 注册，并使用传输、原生视图、布局、菜单、下载和浮层模块。package manifest 显式包含嵌套模块，刷新脚本保留相对路径。Web Desktop bridge 按状态、恢复、传输、菜单、事件和界面分组；文件树操作和查询辅助函数保留既有请求生命周期。服务端运行操作共享规范 Server 状态。自更新验证绑定执行命令限制的已打包 WebSocket 分发模块，并接受旧包布局以支持回滚。

功能目录替代扁平的 Web 库、脚本和测试、Python 认证/更新模块、Server 路由及混合测试目录。大型测试与检查文件保留全部场景、共享 fixture 归属和确定性发现。子进程验收属于 integration 测试层。

文件长度仍是审查信号。生成的 Yoga binding 和 vendored Ink renderer 保留上游组织方式。独立 provider adapter 保持同级文件。Desktop main 保留应用组合职责；一致的 checkpoint 事务、安全 HTTP 策略及其他单领域模块不因任意行数限制而拆分。清单记录剩余大型文件，不宣称全部解决。

模块组织和文件操作变更通过独立规格及质量审查。验收包含固定四个 worker 的连续三次完整 Python 测试，Web/CLI 测试与类型检查、Desktop 检查、应用构建、文档链接、浏览器交互测试和 checkout 外已安装 wheel import。测试清理访问规范 SessionStore cache；原生恢复验收在明确期限内等待实际启动/关闭完成。可选外部 Office-pack 验收仍取决于是否提供该包。

这些计数涵盖直接 Python、JavaScript 和 TypeScript 源码文件。功能子目录保留实现与测试；移动文件不减少行为覆盖。原收集测试身份全部保留，并增加四个回归场景。

实现状态#

长文件并不自动成为待重构项。进一步拆分需要独立职责及相关行为覆盖。