82 lines
11 KiB
Markdown
82 lines
11 KiB
Markdown
# 沙盒 Git 完整接入（2026-10-18）
|
||
|
||
状态：**工程接入已完成（Windows x64 验收范围内）**。本批集中交付完整支持子集，不再把分散的局部增量当作 Git 对齐完成。沙盒全量目标和 WorkBuddy 1:1 等价仍未完成；见本文件的明确边界和[专用验收矩阵](沙盒Git接入验收矩阵-2026-10-18.md)。基线组件升级为 0.7.0 / protocol 1，保留 0.6.0 私有快照 Git 和会话草稿作为兼容路径。
|
||
|
||
## 本批验收范围
|
||
|
||
1. 应用携带可校验、可离线复现的 Git 及远程传输依赖，无需宿主 Git/PATH。
|
||
2. 支持宿主普通仓库和 linked worktree 的历史、真实 HEAD、索引、分支、标签、stash、忽略规则；导入先获明确审批，不导入 hook、凭证 helper、任意配置程序或 alternates 外部对象路径。
|
||
3. 对话中的本地 Git 在 AppContainer/Job 内运行；验证 status/diff/add/commit、分支/切换、merge/冲突处理、rebase/cherry-pick/revert/reset、stash/tag 和 detached HEAD。保留跨命令状态。
|
||
4. 显式宿主提交同时处理项目文件、索引/引用/对象等仓库变更；绑定原根身份、策略、版本和审批，拒绝宿主外部冲突。复用原生事务，组事务记录提交/补偿/恢复结果。
|
||
5. 远程查询、clone/fetch/pull/push 通过专用宿主控制面代理，限定结构化参数、固定 Git 和净化环境。每次远程操作有目标/引用/内容审批；沙盒普通命令继续禁网。凭证显式提供并限定目标，不自动使用宿主 SSH/全局 Git/凭证管理器。
|
||
6. 工具、OMP/备用内核、维护 CLI、状态/结果查询和错误说明一致；不在当前用户真实仓库或远程仓库上做写入测试。
|
||
7. 用真实临时仓库/远程服务验证成功、拒绝、取消、冲突、传输失败、篡改和恢复；构建、兼容回归、资源身份和文档一起验收。
|
||
|
||
交互式编辑器、任意用户 hook/filter/helper、LFS/外部扩展及子模块各自的执行/凭证权限不得通过普通 Git 参数绕过沙盒。测试报告仅记录工程侧行为；未知原版行为不会自动算已对齐。
|
||
|
||
## 原版依据
|
||
|
||
参考目录仍为材料声明的 WorkBuddy 5.8.6，版本未独立证明，目录摘要 `d87c4cab25fb1feec426332fe01b1680538577405cf82476cb6f5b1b14d94b84`。本批通过 REA 复核程序策略和文件代理两个 CJS，父 Evidence `ev_3f45718a91d5c7f20b8940aff699cf62e42467e1c60df9448b8ef9ff4b4be0ab`，摘要视图 `ev_8e62a51a397ca733c115e7bb42d5925b9fbdda1be19ab33b8ff4cbf8b525638c`。仅有静态职责线索，无完整 Git 宿主/远程运行证据；本批工程验收与原版同场景验收分开记录。
|
||
|
||
## 架构决定
|
||
|
||
- 宿主历史通过审批导入为会话私有镜像，Git 命令继续在隔离 stage 使用副本；不直接给 AppContainer 开放宿主 `.git`。
|
||
- 普通项目文件与 Git 元数据使用分别绑定根身份的原生事务，另有组事务记录跨根提交和补偿；不承诺跨根/断电原子性。
|
||
- 原始配置仅由宿主控制面读取和合并白名单数据；沙盒执行配置和传输配置均重新生成，不运行宿主 alias/hook/filter/fsmonitor/credential helper。
|
||
- 远程代理是有网络能力的受信控制面，不向命令 Job 添加网络 capability，也不接受任意 shell/可执行文件/环境变量。
|
||
|
||
## 实施结果
|
||
|
||
### 接入能力
|
||
|
||
- 应用内置并校验官方 MinGit 2.56.0.windows.2；HTTPS、SSH、HTTP/HTTPS helper、OpenSSH、必要 DLL 和许可证作为同一固定归档/清单交付。SHA-256：归档 `da35e72aa21c005a5a0d298cfbae110bc1609a815730ea0dde84b01a1b3cd3be`，运行时清单 `17cbe59d1fdd9230e528be9ec6402b870637d5e7148215f278bbaff01b92ed01`；82 个文件、30,197,068 bytes。普通构建离线复核，不扫描宿主 PATH。
|
||
- `sandbox_git` 接入对话工具，`sandbox_workspace` 的 commit/discard/recover 统一转到 Git 管理路径；受控 Git argv 仍在 AppContainer/Job 执行。状态、远程持久操作结果、会话/项目 owner 只读 IPC 和维护 CLI 已接线。
|
||
- 本地常用流程包含 status/diff/add/commit、分支/标签/switch、merge 冲突继续/abort、rebase、cherry-pick、revert、reset、stash、detached HEAD；非交互 Git editor 只用于已允许的继续操作。
|
||
- `import` 先逐次审批，把宿主普通仓库或现有 linked worktree 的真实历史、HEAD、索引、引用及安全白名单配置导入当前会话镜像；不执行导入的 hook/helper/filter，也不带入凭证或外部对象路径。源内容在审批期间变化即拒绝。
|
||
- `init` 创建真正 unborn 私有仓库。`clone` 读取远程默认分支/全部引用，包含空远程和 SHA-256；首次发布新仓库时先单独审批创建 `.git`，再审批工作区和 Git 元数据组提交。
|
||
- 只有显式批准的宿主提交会同步项目文件及 `.git` 元数据；使用原生目录身份、写前摘要、Git 锁协调和组事务恢复。Linked worktree 按工作树私有目录、common Git 目录拆分提交阶段。对象先发布、引用后发布，宿主对象只追加。
|
||
- 远程操作包括 `ls-remote`/`clone`/`fetch`/`pull`/`push`。HTTPS 校验证书、禁止重定向，SSH 使用显式私钥和 pinned `known_hosts`；凭证经用户 DPAPI 保护并限定到精确 URL。审批指定 endpoint、远端引用和对象 ID；push 使用原子更新，force-with-lease 需用户提供期望旧 OID。普通命令及 AppContainer 仍不获通用网络权限。
|
||
- pull 默认 ff-only，另有显式 merge/rebase；拒绝/取消/策略变化会终止对应作业。Push 响应丢失作为 `unknown` 保存，不自动重试；用户可单独批准只读 reconcile，核对当前引用状态。
|
||
- 控制 Job 使用原生 Git runner 固定 argv/环境、父进程监控、期限和进程树限制。异常控制目录由维护入口仅在 owner/native lease 都无活进程时清理。
|
||
|
||
### 维护者 CLI
|
||
|
||
所有带状态的命令都要求显式 `--state-root` 及绝对路径；需要向宿主项目或远程写入的操作必须额外写 `--approve`。请求文件只承载 argv 或结构化远程参数，不使用 shell 拼接：
|
||
|
||
```powershell
|
||
npm run sandbox:maintain -- git-host-status --workspace 'C:\Project' --session SESSION_ID --state-root 'C:\YCodeData\sandbox'
|
||
npm run sandbox:maintain -- git-host-import --workspace 'C:\Project' --session SESSION_ID --state-root 'C:\YCodeData\sandbox' --approve
|
||
npm run sandbox:maintain -- git-host-commit --workspace 'C:\Project' --session SESSION_ID --state-root 'C:\YCodeData\sandbox' --approve
|
||
npm run sandbox:maintain -- git-host-recover --workspace 'C:\Project' --session SESSION_ID --state-root 'C:\YCodeData\sandbox'
|
||
npm run sandbox:maintain -- git-run --workspace 'C:\Project' --session SESSION_ID --state-root 'C:\YCodeData\sandbox' --request 'C:\requests\git-argv.json'
|
||
npm run sandbox:maintain -- git-remote --workspace 'C:\Project' --session SESSION_ID --state-root 'C:\YCodeData\sandbox' --request 'C:\requests\fetch.json' --approve
|
||
npm run sandbox:maintain -- git-remote-operation OPERATION_UUID --workspace 'C:\Project' --session SESSION_ID --state-root 'C:\YCodeData\sandbox'
|
||
npm run sandbox:maintain -- git-credential-add --url 'https://example.invalid/team/repo.git' --credential-file 'C:\secure\credential.json' --state-root 'C:\YCodeData\sandbox'
|
||
npm run sandbox:maintain -- git-credentials --state-root 'C:\YCodeData\sandbox'
|
||
npm run sandbox:maintain -- git-cleanup --state-root 'C:\YCodeData\sandbox'
|
||
```
|
||
|
||
`git-argv.json` 为 JSON 字符串数组，例如 `["status", "--short"]`；`fetch.json` 是 `{"action":"fetch","url":"https://example.invalid/team/repo.git","branch":"main","credentialId":"CREDENTIAL_UUID"}`。HTTPS 凭证文件格式为 `{"type":"https","username":"...","secret":"...","caCertificate":"可选 PEM"}`，SSH 凭证则提供 PEM private key 和 exact-host `knownHosts`。凭证导入经过 DPAPI 加密，清单只显示 id/URL/type；不要把真实 token 写入命令行、请求或日志。
|
||
|
||
### 最终验证
|
||
|
||
- `npm run build`：通过；包含 Windows x64 原生重建、两套 TypeScript 检查、生产 main/preload/renderer 构建。实际构建日志：`.tmp/git-complete-final-build.log`。
|
||
- 整批新专项：本地完整流程 29/29、安全/并发/事务/崩溃恢复 25/25、HTTP/HTTPS/SSH 真实 loopback remote 40/40、真实生产 Electron + OMP + localhost 模型 52/52；最终目录包内 Git 20/20。
|
||
- 兼容回归：工作区 51、基础沙盒 52、既有 Git 43、策略 38、目录 13、原生写回 32、内置 Git 20、读取桥 21、进程 20、工具链 24；314 项全通过，总计 480 项。
|
||
- 目录包：Windows x64 `win-unpacked` 已构建；包内 native/adapter/manifest 与 82 个 Git 文件核对 SHA-256，并使用包内资源跑 Git 专项。只验未安装/未签名编辑目录包，不代表 NSIS 安装、升级/卸载、公开签名链或标准用户验收。
|
||
- 当前机器 Windows 11 x64、提升权限。本批未对用户真实仓库或远端执行写操作；所有仓库、HTTP/HTTPS/SSH 服务、凭证、用户数据和模型服务均为隔离测试夹具/loopback。未重启用户窗口、未改生产沙盒状态、未提交代码。
|
||
|
||
### 已知不支持 / 未验证
|
||
|
||
- 只验 Windows x64 与当前本地 NTFS/提升权限；标准用户、支持 Windows 版本/文件系统矩阵和独立安全审查仍未验。macOS/Linux/ARM64 不支持。
|
||
- 元数据仅支持 files ref backend；reftable 显式拒绝。Git alternates、partial clone/promisor 必须先明确物化；不跟随外部对象路径。
|
||
- 任意 hook/alias/filter/fsmonitor/credential helper、交互式编辑器、GPG/SSH agent/GCM、LFS、子模块的独立程序/网络执行、项目任意远程 helper/扩展均未开放。宿主配置只读安全白名单。
|
||
- 上限包括 30,000 项元数据、256 MiB 仓库总量、128 MiB 单文件；不承诺大于这些上限的 monorepo/历史。
|
||
- 新仓库 `.git` 骨架初始化与后续组提交是两个显式审批/事务；多根 linked worktree 组提交可暴露中间态，不承诺跨根/断电原子性。原生覆盖仍采用两次 rename，有短暂缺名窗口。
|
||
- 远端 TLS/SSH 行为在真实 loopback fixtures 验证；未对公网托管、企业代理、真实供应商账号/产品仓库做生产凭证验证。代理是受信宿主控制面，不等同于普通命令受控联网。
|
||
- 工程实现覆盖常用 Git，而不是完整 Git 子命令/平台语义。版本兼容范围、长历史资源/性能与所有并发时序仍需扩大测试。
|
||
|
||
### 原版等价范围
|
||
|
||
参考材料目录 SHA-256 `d87c4cab25fb1feec426332fe01b1680538577405cf82476cb6f5b1b14d94b84`，材料声明 WorkBuddy 5.8.6，版本未独立证明。本批仅通过 REA 静态查看 `shims/broker-program-policy-check.cjs` 与 `shims/node-brokered-fs-shim.cjs`；Evidence parent `ev_3f45718a91d5c7f20b8940aff699cf62e42467e1c60df9448b8ef9ff4b4be0ab`，summary `ev_8e62a51a397ca733c115e7bb42d5925b9fbdda1be19ab33b8ff4cbf8b525638c`。没有原版 Git 导入、命令、审批、远程或 UI 的同场景执行证据，故这里只宣称 YCode 的工程集成/实测，不宣称 WorkBuddy 1:1 等价。
|