Skip to content

Ubuntu Lifecycle

Jump to bottom
AceGuru-mjh edited this page Oct 1, 2026 · 4 revisions

Ubuntu 产品生命周期（T82）

🖥️ 终端 & Linux · 🏠 首页 › Ubuntu-Lifecycle

Home Version Kotlin Modules Tools License

Ubuntu-Lifecycle
📑 本页目录

T72–T81 已交付完整的 Ubuntu 安装基础设施，但产品层有 4 个断点。 T82 交付 UbuntuLifecycleCoordinator 把 Install → Bootstrap → Capability → Repair → READY → Terminal → Agent → UI 串起来。 来源：docs/ubuntu-lifecycle.md、docs/T82_FINAL_REPORT.md。

1. Phase 0 审计发现的四个断点

# 断点 证据
B-1 App 启动不感知 Ubuntu 状态（无 reconcile、无状态派生） ApexApp.onCreate() 只做 Shizuku / CS-Mem / attachment
B-2 终端 UI 的"依赖安装中心" 100% 失效 DepCatalog 全是 apt 命令，但 ensureSession() 用默认 local backend 创建 Android shell 会话 → apt-get: command not found
B-3 Agent 拉起 Ubuntu 需 3 次工具调用、自行解读 3 套状态机 terminal.ubuntu.install / terminal.linux.bootstrap / terminal.linux.capabilities 三个独立入口
B-4 crash 后"上次中断在哪"要 Agent 自己探测 bootstrap 有 isInProgress 标记但产品层无人消费

2. 状态机

stateDiagram-v2
    direction LR
    [*] --> NOT_INSTALLED
    NOT_INSTALLED --> INSTALLING : install
    INSTALLING --> ROOTFS_READY
    ROOTFS_READY --> BOOTSTRAPPING : bootstrap
    BOOTSTRAPPING --> READY
    INSTALLING --> FAILED : 失败(stage, retryable)
    BOOTSTRAPPING --> FAILED : 失败(stage, retryable)
    FAILED --> NOT_INSTALLED : 重来
    NOTE --> RECOVERING : warmUp / repair（过程态，不残留）
Loading
状态 含义
NOT_INSTALLED 无 rootfs
INSTALLING 下载/解压中（可续传）
ROOTFS_READY rootfs 就位，未 bootstrap
BOOTSTRAPPING 基础包与配置安装中
READY 可用
FAILED(stage, retryable) 任一阶段失败，保留阶段与可重试标志
RECOVERING 过程态：warmUp reconcile / repair，不残留

3. 六大 API

API 语义
ensureReady(force, timeoutMs) 幂等单飞编排 install → bootstrap → capability 快照；超时 = IN_PROGRESS（断点续传，进度不丢）
warmUp() App 启动恢复：provisioner.reconcile + 状态派生，绝不下载（用户没同意消耗流量前 App 不替用户做决定）
refreshState() 从底层派生 phase（单一事实源仍是 RootfsProvisioner / BootstrapManager，不复制判定逻辑）
stateFlow / progressFlow() UI/Agent 订阅：phase 转移 + install/bootstrap 双进度聚合
cancelInstall() install 阶段真取消（字节保留续传）；其他阶段诚实 NotSupported
repair() 透传 EnvironmentRepairService，单轮 detect→repair→verify，不触发大下载

DEFAULT_ENSURE_TIMEOUT_MS = 15 分钟。

4. 五处产品层接线

# 位置 改动
① TerminalModule（DI） provideUbuntuLifecycleCoordinator @Singleton，适配 UbuntuBootstrapManager（Result 六分支归一化）/ LinuxCapabilityProbe / EnvironmentRepairService / bootstrap progress Flow
② ToolModule 注册 terminal.ubuntu.ensure（一键拉起）+ terminal.ubuntu.status（只读快照，零动作）
③ EnvironmentProvisioner 新增 ensureUbuntuSession()：apt 命令先 ensureReady 再落 linux-ubuntu 会话；不可用则诚实降级 local
④ TerminalViewModel 依赖安装改走 ensureDepInstallSession()，暴露 ubuntuLifecycleState 供 UI 订阅
⑤ ApexApp initUbuntuLifecycleRecovery()：启动 warmUp（reconcile + 派生状态，零下载零 bootstrap）

Note

terminal.ubuntu.install / terminal.linux.bootstrap / terminal.linux.capabilities / terminal.linux.repair 全部保留 —— ensure 是聚合入口，不是替代。

5. 五条设计决策

  1. 状态派生而非复制：derivePhase(hasRootfs, rootfsState, bootstrapState) 是纯函数（11 组合矩阵测试），底层单一事实源不动；
  2. 函数端口而非接口：bootstrap / probe / repair 以 suspend (…) -> … 注入（生产 DI 适配单例、测试注 fake），不建第二套类抽象（T81 禁令）；
  3. 超时 = IN_PROGRESS：与 install 工具同语义，断点续传（Range 下载）+ bootstrap stageEvidence 续跑，进度永不丢失；
  4. probe 失败不否定 READY：环境可用性与诊断快照分离；
  5. RECOVERING 是过程态：refreshState 一律派生事实终态。

6. Agent 决策字段（terminal.ubuntu.ensure / .status）

status | phase | failedStage | retryable | capabilities

status 工具是只读零动作快照，适合先问再动。

7. 测试与验证

项 结果
UbuntuLifecycleCoordinatorTest 30 用例：编排顺序 / 幂等 / force / 失败矩阵（install Failed/Busy/Cancelled/异常；bootstrap Failed/InProgress/Busy）/ probe 降级 / 超时续跑 / 并发单飞（10 并发仅 1 次 install） / warmUp 不下载 / crash 中断续跑 / derivePhase 11 组合 / cancelInstall 三态 / repair 三态
TerminalUbuntuLifecycleToolTest 11 用例：READY / ALREADY_READY / FAILED / IN_PROGRESS / probeDegraded / status 只读零动作
全量回归 149 测试类 / 1045 用例 → 1037 绿 + 7 个 forkpty/定时器类环境敏感 flaky（单独运行 19/19 全过，基线与 T82 树一致 → 并发资源竞争，非代码回归）
质量门禁 行数 max 633（预算 1200/1600）、括号平衡、无 printStackTrace/反射/TODO、工具 ID 唯一

Warning

NOT VERIFIED（如实声明，绝不写 PASS）： ① 真机全链（真实下载 → 真 apt → Ubuntu 会话 → apt 装包 → 终端可见）； ② ensureReady 15 分钟超时预算是估计，未做真机采样校准； ③ ApexApp.warmUp 在真进程的启动时序。

8. 相关页面

footer

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room

Android Guru Agent · 仓库 · 官网 · 下载 APK · Issue · PR · CI

🏠 首页 · 📚 文档索引 · 🛰️ MCP 生态 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图

Wiki 随主干 main 演进 · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room · License TBD

发现与代码不一致？欢迎提 Issue 纠正。

🚀 入门

🏗️ 架构

🧠 Agent 内核

🔧 能力

🛰️ MCP 生态

  • MCP 生态总览 新
  • （沙箱 MCP · 官方 Hub · 逆向 Host · 门控语义）

🖥️ 终端 & Linux

💡 记忆

🎨 UI & 扩展

🛠️ 工程化

🔒 参考

共 58 页 · 4,600+ 行 · 随主干 main 演进

🐛 提 Issue · ⭐ Star 仓库

Clone this wiki locally