@team-agent/installer 0.5.66 → 0.5.68

package/crates/team-agent/src/lifecycle/display.rs

@@ -1,3 +1,27 @@
+//! ---
+//! purpose: team 显示面的能力探测、后端解析、开关与 rebind 后重建
+//! contract:
+//!   provides:
+//!     - name: resolve_display_backend
+//!       what: 按 requested 优先于 recorded 优先于 adaptive 选后端，并标出是否偏离默认
+//!     - name: probe_display_capabilities
+//!       what: 探测当前进程能否开 adaptive 显示，给出被挡原因
+//!     - name: open_worker_displays
+//!       what: 按后端为各 worker 打开显示，返回 agent 到 WorkerDisplay 的映射
+//!     - name: close_team_display_backends
+//!       what: 关闭本 team 的显示后端
+//!     - name: rebuild_adaptive_display_after_rebind
+//!       what: leader rebind 之后重建 adaptive 窗口
+//!   depends:
+//!     - crate::transport
+//!     - crate::state::persist
+//! boundary:
+//!   - 不 spawn 也不 kill worker 进程，只管显示面
+//!   - 显示失败不阻塞 team readiness
+//!   - tmux 操作一律走 workspace 作用域的 TmuxBackend，不用继承 $TMUX 的 ambient 调用
+//!   - ambient leader-pane 探测不属于本文件
+//! maturity: wired
+//! ---
 //!
 //! lifecycle::display —— 能力门 / 后端解析 / 开关 / rebind 后重建。
 //!
@@ -20,6 +44,13 @@ use super::*;
 
 // ── lifecycle::display —— 能力门 / 后端解析 / 开关 / rebind 后重建 ────────────
 
+/// ---
+/// purpose: 定出本次使用的显示后端
+/// params:
+///   requested: 本次命令显式请求的后端，None 表示未指定
+///   recorded: state 里记录的上次后端
+/// returns: 选中的后端，附带它是否偏离默认 adaptive
+/// ---
 ///
 /// `resolve_display_backend(requested, recorded, source)`(`display/backend.py`)。默认
 /// adaptive;显式 none 是逃生口。
@@ -34,6 +65,13 @@ pub fn resolve_display_backend(
     }
 }
 
+/// ---
+/// purpose: 探测当前环境是否具备 adaptive 显示能力
+/// params:
+///   _workspace: 未参与判定，仅保留签名
+/// returns: 平台名、leader 所在 tmux session 与 pane、能力位、状态与被挡原因
+/// errors: 当前实现不产生 Err
+/// ---
 ///
 /// `probe_display_capabilities(...)`(`display/adaptive.py:31`,C13)。能力探测,分支只看
 /// 结果不看 `cfg!(target_os)`;Windows/WSL → `NotImplementedThisPlatform`。
@@ -71,6 +109,14 @@ pub fn probe_display_capabilities(_workspace: &Path) -> Result<DisplayProbe, Lif
     })
 }
 
+/// ---
+/// purpose: 按已解析的后端为各 worker 打开显示
+/// params:
+///   backend: 已解析的显示后端；不带 worker 视图的后端得到空映射
+///   probe: 能力探测结果，adaptive 分支据此决定开还是记 blocked
+/// returns: 后端与 agent_id 到 WorkerDisplay 的映射
+/// errors: adaptive 开窗或读取显示目标失败时返回 LifecycleError
+/// ---
 ///
 /// `open_worker_displays(workspace, session_name, jobs, backend, capability_probe)`
 /// (`display/worker_window.py`)。按后端分派 adaptive / ghostty_workspace / ghostty_window;
@@ -95,6 +141,11 @@ pub(crate) fn open_worker_displays(
     Ok(OpenDisplaysReport { backend, displays })
 }
 
+/// ---
+/// purpose: 关闭本 team 的显示，当前实现只处理 adaptive
+/// returns: 关闭报告
+/// errors: 底层 tmux 操作失败时返回 LifecycleError
+/// ---
 ///
 /// `close_team_display_backends(state, event_log)`(`display/close.py`,C9)。按 state
 /// 记录的后端关显示;adaptive 只删带 team tag 的窗口(C2 leader pane 安全)+ orphan 清理。
@@ -105,6 +156,11 @@ pub fn close_team_display_backends(
     close_adaptive_displays(workspace, session_name)
 }
 
+/// ---
+/// purpose: leader rebind 完成之后重建 adaptive worker 窗口
+/// returns: 重新打开的显示映射
+/// errors: 同 open_worker_displays
+/// ---
 ///
 /// `rebuild_adaptive_display_after_rebind(...)`(`display/rebuild.py`,C12)。restart 在
 /// leader rebind **之后**重建 adaptive 窗口(读 `leader_receiver.rebind_applied` 事件)。

package/crates/team-agent/src/lifecycle/helpers.rs

@@ -1,3 +1,29 @@
+//! ---
+//! purpose: runtime 快照的诊断性落盘，以及 plan 状态文件的路径与读写
+//! contract:
+//!   provides:
+//!     - name: save_team_runtime_snapshot
+//!       what: 把 runtime state 以带 not_authoritative 标记的诊断副本写到 legacy 每 session 路径
+//!     - name: team_snapshot_path
+//!       what: 给出某 session 的诊断快照路径
+//!     - name: plan_state_path
+//!       what: 给出某 plan 的状态文件路径
+//!     - name: plan_lock_path
+//!       what: 给出某 plan 的锁文件路径
+//!     - name: read_plan_state
+//!       what: 读取并反序列化 plan 状态
+//!     - name: save_plan_state
+//!       what: 序列化 plan 状态并经临时文件 rename 落盘
+//!   depends:
+//!     - crate::state::persist
+//!     - crate::model::paths
+//!     - std::fs
+//! boundary:
+//!   - 快照文件不是权威 runtime state，产品写路径不得调用它
+//!   - plan 锁文件只被创建，本模块不对它加锁，也不提供并发互斥
+//!   - 不解释 plan 语义，只做路径、序列化与落盘
+//! maturity: wired
+//! ---
 //!
 //! lifecycle::helpers —— runtime snapshot 原子写(bug-084)+ plan-state 路径/读取。
 
@@ -7,6 +33,13 @@ use std::path::{Path, PathBuf};
 
 use super::*;
 
+/// ---
+/// purpose: 把 runtime state 写成带诊断标记的每 session 快照副本
+/// params:
+///   state: 待快照的 runtime state，必须含 session_name 字段
+/// returns: 写出的快照文件路径
+/// errors: 缺 session_name、建目录、写临时文件或 rename 失败时返回 StatePersist
+/// ---
 ///
 /// `save_team_runtime_snapshot(workspace, state)` — Foundation-0 F0-2:
 /// this is now a **diagnostic-only** legacy per-session snapshot writer.
@@ -68,6 +101,12 @@ pub(crate) fn save_team_runtime_snapshot(
     Ok(path)
 }
 
+/// ---
+/// purpose: 给出某 session 的诊断快照文件路径
+/// params:
+///   session_name: 原始 session 名，非字母数字与下划线点横线的字符会被替换
+/// returns: runtime 目录下 teams 子目录中的 state.json 路径
+/// ---
 pub fn team_snapshot_path(workspace: &Path, session_name: &str) -> PathBuf {
     crate::model::paths::runtime_dir(workspace)
         .join("teams")
@@ -98,10 +137,18 @@ fn safe_snapshot_name(raw: &str) -> String {
     }
 }
 
+/// ---
+/// purpose: 给出某 plan 的状态文件路径
+/// returns: runtime 目录下 orchestrator 子目录中的 plan state 文件路径
+/// ---
 pub(crate) fn plan_state_path(workspace: &Path, plan_id: &PlanId) -> PathBuf {
     plan_state_dir(workspace).join(format!("plan-{}.state.json", plan_id.as_str()))
 }
 
+/// ---
+/// purpose: 给出某 plan 的锁文件路径
+/// returns: runtime 目录下 orchestrator 子目录中的 plan lock 文件路径
+/// ---
 pub(crate) fn plan_lock_path(workspace: &Path, plan_id: &PlanId) -> PathBuf {
     plan_state_dir(workspace).join(format!("plan-{}.lock", plan_id.as_str()))
 }
@@ -110,6 +157,11 @@ fn plan_state_dir(workspace: &Path) -> PathBuf {
     crate::model::paths::runtime_dir(workspace).join("orchestrator")
 }
 
+/// ---
+/// purpose: 从文件读取并反序列化 plan 状态
+/// returns: 解析出的 PlanState
+/// errors: 文件读不到或 JSON 不合法时都返回 InvalidPlan
+/// ---
 pub(crate) fn read_plan_state(path: &Path) -> Result<PlanState, LifecycleError> {
     let data = fs::read_to_string(path)
         .map_err(|e| LifecycleError::InvalidPlan(format!("plan not found: {e}")))?;
@@ -117,6 +169,11 @@ pub(crate) fn read_plan_state(path: &Path) -> Result<PlanState, LifecycleError>
         .map_err(|e| LifecycleError::InvalidPlan(format!("invalid plan state: {e}")))
 }
 
+/// ---
+/// purpose: 序列化 plan 状态，经同目录临时文件 rename 落盘，并确保锁文件存在
+/// returns: 写出的 plan 状态文件路径
+/// errors: 建目录、创建锁文件、写临时文件或 rename 失败时返回 StatePersist
+/// ---
 pub(crate) fn save_plan_state(
     workspace: &Path,
     state: &PlanState,