Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions doc/current/M10/设计-T10.17-健康环境准备复用.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# T10.17 健康环境准备复用

完整 bootstrap 新增 `--reuse-ready-environment`,仅改变环境复用权限,不改变工作区目标选择。原参数默认行为保持;`--if-needed` 的日常启动语义保持。

持原 mutation 锁完成事务恢复、工作区同步和源码真实性检查后,仅当工作区未变化、初始和仓库状态均 ready、版本及 Commit 匹配、venv 结构完整,才允许复用。新选项还用现有 CheckPython 复验受管 Python,随后执行既有离线解释器与锁定依赖检查。明确未就绪回原准备流程;取消、输出、进程或状态基础设施错误直接失败。源码恢复和环境重建不短路。

`version` 的 result.details 追加 `bootstrapEnvironmentReuse: true`。桌面端从已有 exe 版本查询提取该能力,在成功对齐的本次结果中传递;旧 exe 或未知能力不传新参数,不猜测首发版本,不增加进程。独立 repair、重建和普通失败重试不启用此选项。进度沿用现有完成收口,遥测复用原命令结果观察者。

新选项若执行完整准备,必须在写入 ready 前严格离线复验实际解释器和锁定依赖。同步退出 0 不能替代此实证;仍未就绪或复验故障经既有持久化入口写 broken,保留原错误码与 cause,不再递归准备、不自动删除 venv。健康快速返回不增加检查。旧默认、if-needed 与独立 sync 的既有行为保持,本次不修复它们的配置恢复缺口。

不合并准备与监督,不改锁、进程、源测速算法或 uv 安装/同步的全局语义,不改安装版。

## 实施与验收

1. 先扩展 bootstrap 的 alpha 更新、健康/损坏及错误分类矩阵,确认新选项在基线因不支持而失败;补 version 能力断言。
2. 实现独立复用策略及受管 Python 检查,保留原依赖检查和修复;定向回归、vet、build、全仓检查。
3. 主程序接入能力透传及正常初始化选项,覆盖旧/未知 exe、升级后能力、离线、进度和重建语义;运行相关测试、Electron 编译与格式检查。
4. 在隔离 app root 用真实 uv 和相同仓库/环境,交替测量旧/新二进制。保留网络探测与实际动作证据,验证健康/缺包/解释器失效的原行为。
5. pstack 审查规范和规格,修复可复现问题后复验。记录验证限制,不以模拟计时替代真实性能。

实现、真实计时与损坏试验、规范及规格双轴复审已完成,结果见[本地验收](验收-T10.17-健康环境准备复用.md)。复验开始事件的输出故障也会写 broken;测量身份漂移会中止。进入正式 PR 交付,全仓检查保留有记录的环境失败说明,未替换安装版或发布。
53 changes: 53 additions & 0 deletions doc/current/M10/验收-T10.17-健康环境准备复用.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# T10.17 本地验收

2026-11-10。Runtime 基线 `116a045e89abcccc4cce7f4c1995bb6f9a3fb119`,主程序实现基线 `d6ba789a5dd38e29c5dce6e5865fd25c013a3573`,交付前已快进到 `31f2db9b3f642618fe8745ff597b03132ed4cff9`。两个隔离 worktree 的实现与验证记录;未替换安装版、未启动安装版后端或发布。

## 实现

- 完整 bootstrap 可显式开启健康环境复用。目标查询、pending、源码恢复、原 mutation 锁、状态/revision/venv 条件保持;实际受管 Python、venv 解释器与锁定依赖检查均保留。
- 通过既有 version 查询的 `bootstrapEnvironmentReuse` 能力确认兼容性,只有布尔 true 才启用。不猜首发版本,不增加查询进程。能力只来自当前路径的 exe,不取旧备份。
- 正常初始化可启用,普通失败重试和锁文件恢复明确禁用,旧 exe、未知能力与离线回退保持原命令。进度与遥测复用既有完成和结果观察者。
- 真实坏解释器试验发现 uv sync 返回 0 仍可能未修复配置。因此新选项在完整准备后、写 ready 前再严格离线复验,失败保留原错误并写 broken;不自动删 venv、不重复准备。此保护不改变旧默认和 if-needed 的既有修复行为。

## 性能

运行 `scripts/benchmark-bootstrap-reuse.ps1 -SourceRoot <已准备安装目录> -BaseRef 116a045e89abcccc4cce7f4c1995bb6f9a3fb119 -Pairs 5`。脚本从同一代码基线构建控制版与候选版,只复制受管程序资产到新目录,排除 Junction,改写并验证 venv Python home,使用独立状态。每轮严格校验实际版本与 Commit,漂移即中止,并保存实际身份。预热不计入中位数,五组按交替顺序执行真实 uv。

目标 `v5.8.0`,Commit `a640598bf521c59cb255202e95ae2595dd690b45`。最终构建的结果:

| 组 | 控制版 ms | 候选版 ms |
| --- | ---: | ---: |
| 1 | 8995.25 | 3835.32 |
| 2 | 6750.02 | 3410.65 |
| 3 | 5879.00 | 3814.17 |
| 4 | 8500.60 | 3294.91 |
| 5 | 7461.03 | 4481.01 |
| 中位数 | 7461.03 | 3814.17 |

减少 3646.86 ms,约 49%。候选每次均有 readiness 事件,未进入 Python 安装或依赖同步;network.probe 事件由 12 减至 3,保留 Git 源探测。前两轮同条件五组分别为 9658.33 → 5509.54 ms、10193.79 → 4994.35 ms,减少 4148.79 ms、5199.44 ms;网络与文件读取有波动,不能承诺固定节省 5 秒。

这只是该机器健康环境的完整 bootstrap,不是首次安装、整机启动或业务主页时间。两轮准备尚未合并,原约 24 秒的未细分异常未由此解释。

## 真实安全试验

所有故障均在副本制造,安装目录只读:

1. 向跟踪的 main.py 追加内容。候选恢复到原 SHA-256 `0FE65A0AC9554F6EFAB5C4FFB98709F94B5DC84E554223D4A5EECE87B5D0B32A`,完整同步后复验成功,未走 unchanged 快返回。
2. 将副本 pyvenv.cfg 的 home 指向副本内不存在目录。离线检查拒绝坏解释器,原准备仍未能修复时,新后置复验返回 `DEPENDENCY_SYNC_FAILED`、退出 50、状态 `environment_broken`,不写 ready。

原始 comparison.json、逐次 NDJSON、构建 SHA-256、safety.json 及安全试验脚本保存在作者本机临时目录 `auto-mas-bootstrap-reuse-20261110-pr`。同条件、Commit 漂移、版本漂移三类测量身份故障注入也已验证:缺少守卫时漂移被接受,当前脚本拒绝两种漂移。

## 检查

- 新参数与 version 能力的基线红灯、实现后绿灯已执行。
- alpha 目标选择、同 revision 复用、源码变化、venv 损坏、解释器/包缺失、取消、输出/执行故障、准备后仍损坏及后置复验错误均有回归覆盖。
- 主程序交付前 85 项相关测试、Electron 与 renderer 类型检查、锁定版本 Ruff 格式检查、frontend format、lint 通过。lint 有一条未修改页面的已有 prop 默认值警告。
- Go gofmt、vet、build、diff-check 与定向回归通过。全量测试未全绿:`SUBST W:` 未就绪已在基线复现;文件系统夹具另有目录非空的清理失败,最新涉及未改的 ExFAT 生命周期用例,该用例基线定向重跑通过。不把这些失败表述为绿色全仓。未新增生产并发,不宣称 race 通过。

## 规范

双轴独立复审后,无未解决硬违规或可操作的可维护性发现。少量请求构造重复保留了快路径“允许回准备”与准备后“必须失败”的不同语义。

## 规格

初审两处 P2 已修复并补红绿测试:备份查询污染当前 exe 能力;实际 Python 重试与锁文件恢复误启用新选项。追加故障注入审查发现的后置复验开始事件输出失败 P2 也已修复:输出故障同样经既有入口写 broken,再返回原 cause;原始隔离 overlay 与永久回归均已闭环。P3 测量身份建议已落实。最终规范与规格独立复审无剩余可操作发现,目标更新、源码恢复、锁与错误 cause 保留。
7 changes: 7 additions & 0 deletions doc/任务拆分.md
Original file line number Diff line number Diff line change
Expand Up @@ -1670,8 +1670,15 @@ T6.1~T6.7 固定测试名、Windows/race 门和双审清零规则完成;已
- 依赖:T4.12;内容:源码恢复扫描复用持续固定的公共目录链,保留身份、Reparse、大小写与文件共享检查,恢复写入前释放扫描句柄。
- 设计、验证计划与本地测量:[T10.16](current/M10/设计-T10.16-源码路径链复用.md)。不改安装版和协议,不发布。

- [ ] **T10.17 健康环境准备复用** 🚧 2026-11-10
- 依赖:T13.21、T4.12;内容:完整 bootstrap 显式允许复用经实证的健康同 revision 环境,保持目标更新、源码校验、锁与恢复语义。
- 设计与验证:[T10.17](current/M10/设计-T10.17-健康环境准备复用.md)。已获贡献分支提交、推送与正式 PR 授权,不替换安装版或发布。
- 实现、真实计时、损坏验收与双轴复审完成,详见[验收](current/M10/验收-T10.17-健康环境准备复用.md)。最新中位数 7461.03 → 3814.17 ms;P2 输出失败与 P3 测量身份问题已修复,全仓有环境失败,待 PR 合入。

## 7. 变更记录

2026-11-10:登记 T10.17,新增显式健康复用选项与 version 能力声明;桌面端复用既有版本查询识别支持,不增加查询进程。保留日常启动和显式重建,完成同条件计时与 pstack 审查。

2026-11-10:按 AUTO-MAS CNB #263 登记 T5.17,保留 uv 准备失败的结构化详情,
补齐命令日志器关闭后的最终失败落盘;范围限定 Runtime,不修改 Electron。

Expand Down
2 changes: 2 additions & 0 deletions doc/架构设计.md
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,8 @@ stage 独占 mutation Mutex 但不要求 backend Mutex 空闲;其他变更仍

正式安装版通过 `workspace sync` 使用内置 Go Git 能力更新受管后端仓库,不要求目标机器额外安装 Git。开发模式只启动用户指定的源码目录,默认不自动更新或清理该目录。降级不设专用回滚命令,调用 `workspace sync --version <旧版本>` 即可按同一确定性流程重新获取旧发布分支。

`bootstrap --reuse-ready-environment` 允许完整初始化复用健康同 revision 环境,不改变目标仓库查询。工作区校验恢复、状态和 venv 结构检查仍在原 mutation 锁内完成;新选项还复验受管 Python,再复用上述离线解释器与依赖就绪实证。不满足条件则执行原准备流程,并在写入 ready 前再次严格离线复验;仍未就绪保留原错误并写 broken,不自动删除环境或重复准备。显式修复与默认 bootstrap 不短路。`version` 的 `result.details.bootstrapEnvironmentReuse: true` 公告此能力;旧版本缺省表示不支持,桌面端复用已有查询,不额外启动进程。

除 `backend supervise` 外,所有命令执行完成后退出。每次调用只创建一个执行单一顶层操作的 Runtime 进程,不实现通用常驻 RPC 服务。

### Electron 调用
Expand Down
94 changes: 77 additions & 17 deletions internal/cli/bootstrap.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ func bootstrapCommand(deps *deps) *cobra.Command {
}
command.Flags().String("version", "", "目标版本(例如 v5.4.0-beta.1)")
command.Flags().Bool("if-needed", false, "仅在仓库更新或环境未就绪时同步依赖")
command.Flags().Bool("reuse-ready-environment", false, "复验并复用健康环境,不改变目标仓库查询")
return command
}

Expand All @@ -49,6 +50,10 @@ func runBootstrap(
if err != nil {
return sessionSuccess{}, err
}
reuseReadyEnvironment, err := command.Flags().GetBool("reuse-ready-environment")
if err != nil {
return sessionSuccess{}, err
}
version, err := command.Flags().GetString("version")
if err != nil || version == "" {
return sessionSuccess{}, &commandError{
Expand Down Expand Up @@ -260,9 +265,9 @@ func runBootstrap(
// 结构完整仍可能指向失效的基础 Python,或已被重建成缺包的空环境;
// 交给 --no-sync 启动之前必须让 uv 复验实际解释器与锁定依赖。
venvIntact := filesystem.InspectVenv(deps.global.layout).Intact
if ifNeeded && venvIntact && !workspaceResult.Changed && workspaceResult.Status == protocol.StateReadyToStart &&
if (ifNeeded || reuseReadyEnvironment) && venvIntact && !workspaceResult.Changed && workspaceResult.Status == protocol.StateReadyToStart &&
initial.Status == protocol.StateReadyToStart && initial.LastSuccessful.Version == revision.Version() && initial.LastSuccessful.Commit == revision.Commit() {
ready, err := checkBootstrapReadiness(ctx, deps, service, emitter, revision, operationLogger)
ready, err := checkBootstrapReadiness(ctx, deps, service, emitter, revision, operationLogger, reuseReadyEnvironment)
if err != nil {
return sessionSuccess{}, errors.Join(err, rollbackM5Preparation(emitter, machine, protocol.StageDependenciesCheck, "运行环境检查未完成"))
}
Expand Down Expand Up @@ -362,6 +367,38 @@ func runBootstrap(
if err := emitM5Progress(emitter, protocol.StageDependenciesSync, protocol.ProgressSucceeded, "锁定依赖已同步"); err != nil {
return sessionSuccess{}, err
}
if reuseReadyEnvironment {
// uv sync 退出 0 仍可能留下失效的基础解释器;新路径在写入 ready 前严格复验,
// 不把复验失败再折回准备,也不自动删除用户环境。
if err := emitM5Progress(emitter, protocol.StageDependenciesCheck, protocol.ProgressRunning, "正在复验准备后的运行环境"); err != nil {
return sessionSuccess{}, persistM5FailureWithLifecycle(ctx, emitter, store, deps.global.layout, initial, revision, uvExecutable, pythonResult.Spec, operationLogger, machine, protocol.StageDependenciesCheck, err)
}
offline, err := mirror.NewPolicy(mirror.PolicySpec{Offline: true})
if err != nil {
return sessionSuccess{}, err
}
verified, err := service.CheckDependencies(ctx, uv.DependenciesRequest{
ProjectDir: deps.global.layout.RepoDir(), ProjectEnvDir: deps.global.layout.VenvDir(),
PythonVersion: pythonResult.Spec.Version.String(), OperationID: emitter.OperationID(),
Branch: revision.Branch(), Commit: revision.Commit(), MirrorPolicy: offline, Line: uvLogLine(operationLogger),
})
if ctxErr := ctx.Err(); ctxErr != nil {
err = ctxErr
}
if err == nil && (!verified.LockfileChecked || !verified.Synchronized) {
err = &commandError{
code: protocol.CodeDependencySyncFailed, stage: protocol.StageDependenciesCheck,
message: "准备后未确认运行环境就绪", details: map[string]any{},
cause: errors.New("prepared environment did not pass dependency readiness check"),
}
}
if err != nil {
return sessionSuccess{}, persistM5FailureWithLifecycle(ctx, emitter, store, deps.global.layout, initial, revision, uvExecutable, pythonResult.Spec, operationLogger, machine, protocol.StageDependenciesCheck, err)
}
if err := emitM5Progress(emitter, protocol.StageDependenciesCheck, protocol.ProgressSucceeded, "准备后的运行环境检查通过"); err != nil {
return sessionSuccess{}, err
}
}
ready, err := store.NewReadyEnvironment(revision.Version(), revision.Commit())
if err != nil {
return sessionSuccess{}, stateStoreError(protocol.StageDependenciesSync, err)
Expand Down Expand Up @@ -412,18 +449,38 @@ func checkBootstrapReadiness(
emitter *protocol.Emitter,
revision gitrepo.Revision,
logger workspaceLogger,
checkManagedPython bool,
) (bool, error) {
if err := emitM5Progress(emitter, protocol.StageDependenciesCheck, protocol.ProgressRunning, "正在检查当前运行环境"); err != nil {
return false, err
}
spec, err := service.ReadPythonSpec(ctx, deps.global.layout.RepoDir())
if err != nil {
return false, err
}
policy, err := mirror.NewPolicy(mirror.PolicySpec{Offline: true})
if err != nil {
return false, err
}
var spec uv.PythonSpec
if checkManagedPython {
python, err := service.CheckPython(ctx, uv.PythonRequest{
ProjectDir: deps.global.layout.RepoDir(), PythonInstallDir: deps.global.layout.PythonDir(),
ProjectEnvDir: deps.global.layout.VenvDir(), CacheDir: deps.global.layout.UVCacheDir(),
Branch: revision.Branch(), Commit: revision.Commit(), MirrorPolicy: policy, Line: uvLogLine(logger),
})
if ctxErr := ctx.Err(); ctxErr != nil {
return false, ctxErr
}
if err != nil {
if !bootstrapCheckNeedsPreparation(err, protocol.CodePythonVersionMismatch) {
return false, err
}
return false, emitM5Progress(emitter, protocol.StageDependenciesCheck, protocol.ProgressFailed, "受管 Python 未就绪,正在重新准备")
}
spec = python.Spec
} else {
spec, err = service.ReadPythonSpec(ctx, deps.global.layout.RepoDir())
if err != nil {
return false, err
}
}
result, err := service.CheckDependencies(ctx, uv.DependenciesRequest{
ProjectDir: deps.global.layout.RepoDir(), ProjectEnvDir: deps.global.layout.VenvDir(),
PythonVersion: spec.Version.String(), OperationID: emitter.OperationID(),
Expand All @@ -434,17 +491,7 @@ func checkBootstrapReadiness(
return false, ctxErr
}
if err != nil {
// 只有已完成的 uv 检查报告未同步才进入准备流程;读取管道、
// 启动进程或日志出口失败不能被依赖层的外包装掩盖。
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) ||
findOperationErrorCode(err, protocol.CodeOutputWriteFailed) != nil {
return false, err
}
if executionErr := findOperationErrorCode(err, protocol.CodeUVExecFailed); executionErr != nil && executionErr.Details()["failureKind"] != "nonzero_exit" {
return false, err
}
failure := findOperationErrorCode(err, protocol.CodeDependencySyncFailed)
if failure == nil || detailsExitCode(failure.Details()) <= 0 {
if !bootstrapCheckNeedsPreparation(err, protocol.CodeDependencySyncFailed) {
return false, err
}
return false, emitM5Progress(emitter, protocol.StageDependenciesCheck, protocol.ProgressFailed, "当前运行环境未同步,正在重新准备")
Expand All @@ -455,6 +502,19 @@ func checkBootstrapReadiness(
return true, emitM5Progress(emitter, protocol.StageDependenciesCheck, protocol.ProgressSucceeded, "当前运行环境检查通过")
}

// bootstrapCheckNeedsPreparation 只将已完成的 uv 不健康检查归入准备,保留执行与输出故障。
func bootstrapCheckNeedsPreparation(err error, code protocol.Code) bool {
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) ||
findOperationErrorCode(err, protocol.CodeOutputWriteFailed) != nil {
return false
}
if executionErr := findOperationErrorCode(err, protocol.CodeUVExecFailed); executionErr != nil && executionErr.Details()["failureKind"] != "nonzero_exit" {
return false
}
failure := findOperationErrorCode(err, code)
return failure != nil && detailsExitCode(failure.Details()) > 0
}

type directWorkspaceEmitter struct {
emitter *protocol.Emitter
suppressWorkspaceStates bool
Expand Down
Loading