85 lines
9.0 KiB
Markdown
85 lines
9.0 KiB
Markdown
# 沙盒 Git 接入（2026-10-18）
|
||
|
||
当前组件版本为 **0.4.0 / protocol 1**。Git 现在默认随 YCode 提供，普通用户无需安装或注册；内置来源、构建和打包验证见[内置分发记录](沙盒内置Git分发-2026-10-18.md)。已接入真实 Git for Windows 运行时和跨命令保存的**沙盒专用仓库**。本记录不表示完整 P2、宿主仓库集成或 WorkBuddy 等价验收完成。
|
||
|
||
## 当前可用范围
|
||
|
||
- `execute_command` 显式选择 `runtimes: ['git']` 后，可执行本地 `status`、`diff`、`add`、`commit -m`、`log`、分支、`switch` 等操作；也可与 Node/Python 运行时组合。
|
||
- 首次选择 Git 时，从本次过滤后的工作区文件生成一个合成提交，分支名为 `ycode-sandbox`。基线包含所有通过快照过滤的文件，不复用宿主 Git 的跟踪、暂存或忽略状态。后续 `git add` 使用沙盒内的 Git 忽略规则。
|
||
- 合成基线保留快照原始字节，初始化的私有 `info/attributes` 默认禁用 text/filter/ident/eol/working-tree-encoding 自动转换，避免项目 `.gitattributes` 让首次 CRLF/编码文件出现虚假差异；这不复刻宿主 clean/smudge 语义。用户在沙盒内主动改动这些规则仍受原生隔离约束。
|
||
- `status` / `diff` 比较当前快照与沙盒索引/提交。后续宿主编辑会作为工作树差异出现；恢复文件事务后，Git 也会看到相应工作树差异。
|
||
- 暂存、提交、分支等仓库元数据发生变化时，需要审批保存。仅查询状态/差异/日志不触发审批；关闭可选锁及 diff 自动刷新索引，避免缓存刷新产生审批。
|
||
- 宿主文件仍使用现有文件/目录事务；沙盒仓库修订在 `stateRoot/git` 下独立保存。命令结果、审计和 `sandboxOperation` 查询分别显示 `writeback` 与 `git.persistence`。
|
||
|
||
**宿主 `.git`、历史、索引、远程配置、凭证及 hook 均不导入，宿主 `.git` 不写回。** 因此，首次沙盒状态为干净并不代表宿主仓库干净，沙盒 `log` 也不表示宿主历史。工具描述、能力状态、结构化结果和文本结果都明确标注这一差别。宿主 worktree 的 `.git` 文件同样排除。
|
||
|
||
## 运行时与边界
|
||
|
||
`toolchains.ts` 默认使用应用资源中的固定版本 Git；维护者仍可显式导入 `cmd/git.exe`、`bin/git.exe` 或实际的 MinGW/UCRT x64 `git.exe` 覆盖它。导入器只读取 PE 导入表，递归复制该主程序实际依赖的本地 DLL；不在宿主执行选中的程序。PE 依赖分析使用已经复制的同一份字节。导入失败不会替换已有注册项。
|
||
|
||
每次执行重新校验清单及全部文件摘要，复制到原生只读 ACL 约束的工具目录。不复制 Git Bash、网络辅助程序、SSH、签名程序或凭证管理器，也不继承宿主 PATH 和环境。Git 不是依赖缓存类型；`dependencies` 继续只允许 Node/Python。
|
||
|
||
原生环境指定私有 HOME、空系统/全局配置、禁止交互凭证提示、空模板/默认 hook 目录，以及默认关闭 hook、fsmonitor、凭证助手、提交/标签签名和自动维护。默认禁止全部 Git 传输协议，包括本地 file 传输。上述 Git 配置属于默认兼容策略，沙盒内命令主动修改参数或环境仍受同一 AppContainer/Job 约束；真正的宿主访问和联网边界来自原生隔离。没有新增网络 capability。
|
||
|
||
`GIT_DIR` 指向当前 stage 的 `repository`，`GIT_WORK_TREE` 指向 `workspace`。需要实际工作区 `.git` 目录或宿主绝对仓库路径的第三方工具尚未兼容。未执行的 Git 子命令、Git Bash 脚本、submodule、LFS、原生插件、交互编辑器及版本矩阵不因本轮测试通过而声称可用。
|
||
|
||
## 保存、策略与恢复
|
||
|
||
仓库修订位于 `stateRoot/git/<workspace-sha256>/objects/<uuid>`，清单绑定规范工作区、策略内容指纹及每个文件的摘要。活动引用原子替换；同工作区执行队列之外，再使用跨维护进程的 `repository.lock` 防止重复操作。工作区之间不共享仓库对象。
|
||
|
||
首次合成基线只写沙盒内部状态。用户命令产生的候选修订先保存独立文件及清单，并在运行目录写入 `git-candidate.json`，然后将候选身份和文件变更摘要共同绑定审批。保存前核对活动引用、策略和完整初始工作区快照。审批期间外部编辑、策略变化、索引/运行时损坏均拒绝旧操作。命令失败、超时、取消或审批拒绝，不发布该命令的仓库变更。
|
||
|
||
新策略可能禁止旧历史中的某些文件，因此任何策略指纹变化都会拒绝加载旧仓库，要求维护者先查看 `git-state`，再显式 `git-reset`。不会自动丢弃原有历史。`git-reset` 归档活动引用；此前修订仍留在状态目录，新的基线重新按当前策略过滤。
|
||
|
||
单次仓库修订上限：30,000 项、256 MiB，总清单 8 MiB，单文件 32 MiB；链接、硬链接、特殊文件、ADS/设备路径、外部 alternates、commondir/gitdir 及遗留 `.lock` 文件拒绝保存。这里不是 OS 磁盘硬配额；旧修订、未发布候选及运行记录尚无自动保留清理，长期磁盘管理仍待补齐。
|
||
|
||
**宿主文件事务与私有 Git 引用发布是两个持久化步骤，不保证跨步骤原子性或断电级耐久性。** 文件事务成功而 Git 发布失败时，结果保留真实 `writeback: committed`、事务 ID，并单独报告 `git.persistence: failed`。此时可查询运行/候选记录，并按现有事务恢复文件；不能根据原生命令退出码推断两者都已保存。进程异常退出可能留下 `repository.lock`；先核实记录中的 PID 已退出，再由维护者处理该锁，当前不做自动抢锁。
|
||
|
||
## 维护入口
|
||
|
||
以下命令供维护者查询或覆盖版本使用，普通用户无需执行 Git 导入。`C:\YCodeData\sandbox` 是示例，应替换为该应用实际 userData 下的 `sandbox`。验证只使用隔离夹具，没有修改用户生产配置或重启窗口。
|
||
|
||
```powershell
|
||
npm run sandbox:maintain -- toolchain-add git --source "C:\Program Files\Git\cmd\git.exe" --state-root "C:\YCodeData\sandbox"
|
||
npm run sandbox:maintain -- toolchains --state-root "C:\YCodeData\sandbox"
|
||
npm run sandbox:maintain -- git-state --workspace "C:\Project" --state-root "C:\YCodeData\sandbox"
|
||
npm run sandbox:maintain -- git-reset --workspace "C:\Project" --state-root "C:\YCodeData\sandbox"
|
||
```
|
||
|
||
模型工具参数示例：
|
||
|
||
```json
|
||
{"command":"git status --short && git diff","runtimes":["git"]}
|
||
```
|
||
|
||
Node 捕获 Git 子进程输出时，继续按已有显式适配器规则执行：
|
||
|
||
```json
|
||
{"command":"node --require \"%YCODE_SANDBOX_PROCESS%\" script.cjs","runtimes":["node","git"]}
|
||
```
|
||
|
||
## 验证与遗留工作
|
||
|
||
专项入口为 `npm run test:sandbox:git`，使用独立 userData/state/workspace、真实 AppContainer 和本机 Git for Windows 2.55.0.windows.5。夹具宿主仓库包含曾提交后删除的假 `.env`，验证其内容及宿主历史未进入沙盒；所有宿主 Git 初始化/提交均只作用于生成的夹具，未操作 YCode 自身历史。
|
||
|
||
真实生产 Electron/preload/main → OMP RPC → 本地确定性模型 → `execute_command` → 原生 Git → 聊天审批 → 文件事务/仓库保存 → 后续读取及持久结果查询，也有独立验收。构建/报告及摘要汇总见 `.tmp/sandbox-git-integration-validation.json`。
|
||
|
||
0.3.0 首批接入时完整构建/类型检查通过，6 组共 207 项通过；0.4.0 内置版本的新增与复核结果见内置分发记录：
|
||
|
||
| 专项 | 通过项 | 报告 |
|
||
| --- | --- | --- |
|
||
| Git | 43 | `.tmp/sandbox-git-YDNhf3/report.json` |
|
||
| 原生隔离 | 52 | `.tmp/sandbox-regression-wZty7E/report.json` |
|
||
| 策略/授权 | 38 | `.tmp/sandbox-policy-6AgDYV/report.json` |
|
||
| Node/Python 工具链及依赖 | 24 | `.tmp/sandbox-toolchain-mH9fP5/report.json` |
|
||
| Node/Python 进程兼容 | 20 | `.tmp/sandbox-process-IPJvWP/report.json` |
|
||
| 真实生产 Electron/OMP | 30 | `.tmp/sandbox-app-pBc7pP/report.json` |
|
||
|
||
另实测维护 CLI 的 Git 导入、列举、仓库查询与重置。将 `sandbox:maintain` 改为单一 Node 启动器，避免 npm 因前置 cmd shim 给参数双重转义；安装路径、状态目录和工作区含空格、中文及字面量 `^` 的场景通过。测试期间未接触生产沙盒配置，也未重启用户窗口。
|
||
|
||
尚未接入：宿主原有仓库的安全只读历史/索引导入、宿主 `.git` 的审批事务、远程协议及授权凭证、持久可写工作区、完整 Git 子命令/多版本兼容、自动清理、标准用户/安装包矩阵、原版同场景 REA 比较。后续导入原仓库时必须解决对象库/packfile 中的受保护历史，不能直接复制整个 `.git`。
|
||
|
||
## 0.7.0 后续增量（2026-10-18）
|
||
|
||
以上是 0.3.0/0.4.0 历史记录，保留当时的范围和报告，不再代表当前缺口。宿主 Git 导入、`.git` 元数据组事务、长期 Git 草稿、远程 HTTP(S)/SSH 和凭证现在已在[完整接入记录](沙盒Git完整接入-2026-10-18.md)中完成工程实现；当前 0.7.0 验收矩阵、限制和 29/25/40/52 新专项结果见[专用矩阵](沙盒Git接入验收矩阵-2026-10-18.md)。
|