@team-agent/installer 0.5.66 → 0.5.68

package/crates/team-agent/src/lifecycle/launch/fork_entry.rs

@@ -1,6 +1,30 @@
+//! ---
+//! purpose: fork 一席的入口，解析活跃 team 并绑定它实际使用的 tmux socket
+//! contract:
+//!   provides:
+//!     - name: fork_agent
+//!       what: 解析 team 与 transport 后转 fork_agent_with_transport
+//!   depends:
+//!     - crate::state::selector
+//!     - crate::lifecycle::restart
+//!     - crate::tmux_backend
+//! boundary:
+//!   - 不自己做窗口注入，注入在 fork_agent.rs
+//!   - 不用 workspace 哈希兜底 socket 覆盖已持久化的 endpoint
+//! maturity: wired
+//! ---
 //!
 use super::*;
 
+/// ---
+/// purpose: fork 一席的对外入口
+/// params:
+///   source_agent_id: 源席位
+///   as_agent_id: 新席位名
+///   label: 新席位的角色标签
+/// returns: fork 报告
+/// errors: 选不到活跃 team 返回 TeamSelect，其余透传 fork_agent_with_transport
+/// ---
 /// `fork_agent(workspace, source_agent_id, as_agent_id, ...)`(`lifecycle/operations.py:284`)。
 /// native session fork(provider 须 supports_session_fork ∧ auth_mode!=compatible_api);
 /// 失败回滚,每条失败臂 `adapter.cleanup_mcp`。

package/crates/team-agent/src/lifecycle/launch/grok_per_seat.rs

@@ -0,0 +1,260 @@
+//! ---
+//! purpose: 判定 .grok/config.toml env 里哪些键是每席私有
+//! contract:
+//!   provides:
+//!     - name: is_per_seat_env_key
+//!       what: TEAM_AGENT_* 除 WORKSPACE 外都是每席键
+//!     - name: per_seat_keys_in_toml
+//!       what: 扫描 toml env 表里的每席键
+//!     - name: strip_per_seat_keys_from_toml
+//!       what: 从任意 .env 表删掉每席键，留下非框架键
+//!     - name: non_per_seat_env_in_tables
+//!       what: 从指定表的 .env 取出非每席键（值原样），供 overlay 保留
+//! boundary:
+//!   - 不写盘
+//!   - 不数 grok 席位个数
+//!   - 剥离结果只含键名，不含键值
+//! maturity: wired
+//! ---
+
+/// ---
+/// purpose: 判断某环境键是否属于每席私有
+/// returns: 以 TEAM_AGENT_ 起头且不是 TEAM_AGENT_WORKSPACE 时为 true
+/// ---
+/// Shared identity keys belong on pane env. The only TEAM_AGENT_* key
+/// allowed in the directory-scoped grok toml is WORKSPACE (same cwd).
+pub(crate) fn is_per_seat_env_key(key: &str) -> bool {
+    let key = key.trim();
+    key.starts_with("TEAM_AGENT_") && key != "TEAM_AGENT_WORKSPACE"
+}
+
+/// ---
+/// purpose: 扫出 toml 里所有 env 表中的每席键
+/// returns: 首次出现顺序的键值对，值已去掉引号
+/// ---
+pub(crate) fn per_seat_keys_in_toml(text: &str) -> Vec<(String, String)> {
+    let mut in_env_table = false;
+    let mut out = Vec::new();
+    for line in text.lines() {
+        let trimmed = line.trim();
+        if trimmed.starts_with('[') && trimmed.ends_with(']') {
+            let name = &trimmed[1..trimmed.len() - 1];
+            in_env_table = name.ends_with(".env");
+            continue;
+        }
+        if !in_env_table {
+            continue;
+        }
+        let Some((key, rest)) = trimmed.split_once('=') else {
+            continue;
+        };
+        let key = key.trim();
+        if !is_per_seat_env_key(key) {
+            continue;
+        }
+        let rest = rest.trim();
+        let value = rest
+            .strip_prefix('"')
+            .and_then(|s| s.strip_suffix('"'))
+            .or_else(|| rest.strip_prefix('\'').and_then(|s| s.strip_suffix('\'')))
+            .unwrap_or(rest);
+        if out.iter().any(|(existing, _)| existing == key) {
+            continue;
+        }
+        out.push((key.to_string(), value.to_string()));
+    }
+    out
+}
+
+/// ---
+/// purpose: 从所有 env 表里删掉每席键
+/// returns: 删后的全文，以及被删键名的首次出现顺序列表，不含值
+/// ---
+/// Drop per-seat `TEAM_AGENT_*` assignments from any `*.env` table.
+/// Other keys (`TEAM_AGENT_WORKSPACE`, `GROK_FOLDER_TRUST`, user keys) stay.
+/// Returned names are first-seen order, values never included.
+pub(crate) fn strip_per_seat_keys_from_toml(text: &str) -> (String, Vec<String>) {
+    let mut in_env_table = false;
+    let mut out = String::new();
+    let mut removed = Vec::new();
+    for line in text.lines() {
+        let trimmed = line.trim();
+        if trimmed.starts_with('[') && trimmed.ends_with(']') {
+            let name = &trimmed[1..trimmed.len() - 1];
+            in_env_table = name.ends_with(".env");
+            out.push_str(line);
+            out.push('\n');
+            continue;
+        }
+        if in_env_table {
+            if let Some((key, _)) = trimmed.split_once('=') {
+                let key = key.trim();
+                if is_per_seat_env_key(key) {
+                    if !removed.iter().any(|existing| existing == key) {
+                        removed.push(key.to_string());
+                    }
+                    continue;
+                }
+            }
+        }
+        out.push_str(line);
+        out.push('\n');
+    }
+    (out, removed)
+}
+
+fn toml_env_value(rest: &str) -> String {
+    let rest = rest.trim();
+    rest.strip_prefix('"')
+        .and_then(|s| s.strip_suffix('"'))
+        .or_else(|| rest.strip_prefix('\'').and_then(|s| s.strip_suffix('\'')))
+        .unwrap_or(rest)
+        .to_string()
+}
+
+/// ---
+/// purpose: 取出指定表的 env 段里非每席的键值
+/// params:
+///   tables: 目标表名前缀，只看这些表下的 env 段
+/// returns: 键到值的有序映射，供覆盖写入时保留用户键
+/// ---
+/// Keys in `tables*.env` that are **not** per-seat. Unknown keys must be
+/// kept — detection failure does not authorize deletion.
+pub(crate) fn non_per_seat_env_in_tables(
+    text: &str,
+    tables: &[&str],
+) -> std::collections::BTreeMap<String, String> {
+    let mut in_target_env = false;
+    let mut out = std::collections::BTreeMap::new();
+    for line in text.lines() {
+        let trimmed = line.trim();
+        if trimmed.starts_with('[') && trimmed.ends_with(']') {
+            let name = &trimmed[1..trimmed.len() - 1];
+            in_target_env = name.ends_with(".env")
+                && tables
+                    .iter()
+                    .any(|table| name == *table || name.starts_with(&format!("{table}.")));
+            continue;
+        }
+        if !in_target_env {
+            continue;
+        }
+        let Some((key, rest)) = trimmed.split_once('=') else {
+            continue;
+        };
+        let key = key.trim();
+        if key.is_empty() || is_per_seat_env_key(key) {
+            continue;
+        }
+        out.entry(key.to_string())
+            .or_insert_with(|| toml_env_value(rest));
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn workspace_is_shared_other_team_agent_keys_are_per_seat() {
+        assert!(!is_per_seat_env_key("TEAM_AGENT_WORKSPACE"));
+        assert!(is_per_seat_env_key("TEAM_AGENT_ID"));
+        assert!(is_per_seat_env_key("TEAM_AGENT_OWNER_TEAM_ID"));
+        assert!(is_per_seat_env_key("TEAM_AGENT_AUTH_MODE"));
+        assert!(is_per_seat_env_key("TEAM_AGENT_FUTURE_SEAT_KEY"));
+        assert!(!is_per_seat_env_key("GROK_FOLDER_TRUST"));
+    }
+
+    #[test]
+    fn scan_finds_per_seat_keys_in_env_table_only() {
+        let text = r#"
+[mcp_servers.other.env]
+TEAM_AGENT_ID = "ignore-other-server-still-counts"
+
+[mcp_servers.team_orchestrator]
+command = "/bin/x"
+
+[mcp_servers.team_orchestrator.env]
+TEAM_AGENT_WORKSPACE = "/ws"
+TEAM_AGENT_AUTH_MODE = "impostor"
+"#;
+        let keys = per_seat_keys_in_toml(text);
+        assert!(
+            keys.iter()
+                .any(|(k, v)| k == "TEAM_AGENT_AUTH_MODE" && v == "impostor"),
+            "must see AUTH; keys={keys:?}"
+        );
+        assert!(
+            keys.iter().any(|(k, _)| k == "TEAM_AGENT_ID"),
+            "any env table per-seat key counts; keys={keys:?}"
+        );
+        assert!(
+            !keys.iter().any(|(k, _)| k == "TEAM_AGENT_WORKSPACE"),
+            "WORKSPACE is shared; keys={keys:?}"
+        );
+    }
+
+    #[test]
+    fn strip_drops_only_per_seat_keys_and_returns_names() {
+        let text = r#"
+[mcp_servers.keep.env]
+GROK_FOLDER_TRUST = "1"
+TEAM_AGENT_ID = "impostor"
+TEAM_AGENT_WORKSPACE = "/ws"
+
+[mcp_servers.keep]
+command = "/bin/keep"
+
+[other]
+TEAM_AGENT_AUTH_MODE = "not-in-env-table"
+"#;
+        let (cleaned, removed) = strip_per_seat_keys_from_toml(text);
+        assert_eq!(removed, vec!["TEAM_AGENT_ID".to_string()]);
+        assert!(
+            !cleaned.contains("TEAM_AGENT_ID"),
+            "per-seat key must leave the env table; cleaned={cleaned}"
+        );
+        assert!(
+            cleaned.contains("GROK_FOLDER_TRUST = \"1\"")
+                && cleaned.contains("TEAM_AGENT_WORKSPACE = \"/ws\"")
+                && cleaned.contains("TEAM_AGENT_AUTH_MODE = \"not-in-env-table\"")
+                && cleaned.contains("command = \"/bin/keep\""),
+            "non-per-seat keys and non-env tables stay; cleaned={cleaned}"
+        );
+        assert!(
+            !cleaned.contains("impostor"),
+            "stripped values must not be rewritten; cleaned={cleaned}"
+        );
+    }
+
+    #[test]
+    fn non_per_seat_scan_keeps_unknown_keys_from_named_tables_only() {
+        let text = r#"
+[mcp_servers.keep-me.env]
+GROK_FOLDER_TRUST = "other-table"
+
+[mcp_servers.team_orchestrator.env]
+TEAM_AGENT_ID = "stale"
+GROK_FOLDER_TRUST = "1"
+TEAM_AGENT_WORKSPACE = "/ws"
+USER_EXTRA = "keep"
+"#;
+        let kept = non_per_seat_env_in_tables(text, &["mcp_servers.team_orchestrator"]);
+        assert_eq!(kept.get("GROK_FOLDER_TRUST").map(String::as_str), Some("1"));
+        assert_eq!(kept.get("USER_EXTRA").map(String::as_str), Some("keep"));
+        assert_eq!(
+            kept.get("TEAM_AGENT_WORKSPACE").map(String::as_str),
+            Some("/ws")
+        );
+        assert!(
+            !kept.contains_key("TEAM_AGENT_ID"),
+            "per-seat keys are not preserved; kept={kept:?}"
+        );
+        assert_ne!(
+            kept.get("GROK_FOLDER_TRUST").map(String::as_str),
+            Some("other-table"),
+            "only the named table is read; kept={kept:?}"
+        );
+    }
+}

package/crates/team-agent/src/lifecycle/launch/identity.rs

@@ -1,3 +1,31 @@
+//! ---
+//! purpose: team 与席位的身份取值，团队键、display 后端、auth_mode、effort 与 quick-start 层级判定
+//! contract:
+//!   provides:
+//!     - name: spec_team_id
+//!       what: 从 spec 里取 team 标识
+//!     - name: runtime_team_key_for_spec
+//!       what: 由 spec 路径与 session 名算出 runtime 团队键
+//!     - name: transport_has_session
+//!       what: 探测 tmux session 是否存在，探测本身出错一律当不存在
+//!     - name: provider_effort_from_raw
+//!       what: 解析 effort 并要求该 provider 支持，否则 None
+//!     - name: quick_start_depth_guard
+//!       what: 定出本次 quick-start 的父团队与层级，推不出父团队时拒绝
+//!     - name: annotate_persisted_team_depth
+//!       what: 把父团队与层级写回已落盘的 runtime state
+//!   depends:
+//!     - crate::state::projection
+//!     - crate::state::persist
+//!     - crate::state::repository
+//!     - crate::lifecycle::display
+//!     - crate::provider::wire
+//! boundary:
+//!   - 只做身份判定与取值，不 spawn、不开显示
+//!   - effort 不被支持时只丢弃并给出事件载荷，不改写成别的档位
+//!   - 层级判定拿不准时报错，不默认当顶层团队
+//! maturity: wired
+//! ---
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 use std::process::Command;
@@ -14,6 +42,12 @@ use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest}
 
 use super::*;
 
+/// ---
+/// purpose: 从 spec 里取 team 标识
+/// params:
+///   spec: 已解析的 spec
+/// returns: team.id 优先，其次 team.name，再次顶层 name；都没有则 None
+/// ---
 pub(super) fn spec_team_id(spec: &Value) -> Option<String> {
     spec.get("team")
         .and_then(|v| v.get("id").or_else(|| v.get("name")))
@@ -22,6 +56,10 @@ pub(super) fn spec_team_id(spec: &Value) -> Option<String> {
         .or_else(|| spec.get("name").and_then(Value::as_str).map(str::to_string))
 }
 
+/// ---
+/// purpose: 取 runtime state 里显式记录的当前活跃团队键
+/// returns: 非空的 active_team_key，缺失或为空则 None
+/// ---
 pub(super) fn explicit_active_team_key(state: &serde_json::Value) -> Option<String> {
     state
         .get("active_team_key")
@@ -30,6 +68,10 @@ pub(super) fn explicit_active_team_key(state: &serde_json::Value) -> Option<Stri
         .map(str::to_string)
 }
 
+/// ---
+/// purpose: 由 spec 路径、spec 内容与 session 名拼出 runtime 团队键
+/// returns: 交给 state::projection 计算出的团队键
+/// ---
 pub(super) fn runtime_team_key_for_spec(
     spec_path: &Path,
     spec: &Value,
@@ -45,6 +87,10 @@ pub(super) fn runtime_team_key_for_spec(
     crate::state::projection::team_state_key(&state)
 }
 
+/// ---
+/// purpose: 探测某 tmux session 是否存在
+/// returns: 只有确定存在才返回 true；transport 报错或 panic 一律当作不存在
+/// ---
 pub(super) fn transport_has_session(transport: &dyn Transport, session_name: &SessionName) -> bool {
     match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
         transport.has_session(session_name)
@@ -54,6 +100,10 @@ pub(super) fn transport_has_session(transport: &dyn Transport, session_name: &Se
     }
 }
 
+/// ---
+/// purpose: 取 spec 请求的显示后端并交给 display 解析
+/// returns: 解析后的后端，spec 未写或写了未知值时为默认 adaptive
+/// ---
 pub(super) fn spec_display_backend(spec: &Value) -> DisplayBackend {
     let requested = spec
         .get("runtime")
@@ -67,6 +117,12 @@ pub(super) fn spec_display_backend(spec: &Value) -> DisplayBackend {
 
 use crate::provider::wire::parse_provider;
 
+/// ---
+/// purpose: 把 auth_mode 字符串解析成枚举
+/// params:
+///   raw: 只接受 subscription、official_api、compatible_api
+/// returns: 对应枚举，未知取值返回 None
+/// ---
 pub(super) fn parse_auth_mode(raw: &str) -> Option<AuthMode> {
     match raw {
         "subscription" => Some(AuthMode::Subscription),
@@ -76,6 +132,12 @@ pub(super) fn parse_auth_mode(raw: &str) -> Option<AuthMode> {
     }
 }
 
+/// ---
+/// purpose: 从原始字符串解析 effort，并要求当前 provider 支持它
+/// params:
+///   raw: effort 原文，None 或空白返回 None
+/// returns: 解析成功且该 provider 支持时返回该档位，否则 None
+/// ---
 /// 0.4.x provider effort MVP step 4: low-level from a raw string. Returns
 /// `Some(effort)` when the level parses AND the provider supports it.
 pub(crate) fn provider_effort_from_raw(
@@ -94,6 +156,10 @@ pub(crate) fn provider_effort_from_raw(
     }
 }
 
+/// ---
+/// purpose: 当 spec 请求了该 provider 不支持的 effort 时，给出告警事件载荷
+/// returns: 含 agent_id、provider、effort 与 ignored 动作的 JSON；未请求或本就支持时为 None
+/// ---
 /// 0.4.x provider effort MVP step 7: warning event payload when the spec
 /// requested an effort level the provider does not support.
 pub(crate) fn provider_effort_event_payload(
@@ -118,6 +184,12 @@ pub(crate) fn provider_effort_event_payload(
     }))
 }
 
+/// ---
+/// purpose: 对 claude 系 provider 兜底确保 CLAUDE_EFFORT 进入待清除环境变量表
+/// params:
+///   base: 已有的待清除变量名列表
+/// returns: 非 claude 系原样返回；claude 系在缺失时补上 CLAUDE_EFFORT
+/// ---
 /// 0.4.x provider effort MVP step 9: defensive guarantee that `CLAUDE_EFFORT`
 /// is unset in the Claude/ClaudeCode worker spawn env. As of the
 /// `profile_launch::provider_env_unsets` update, the base list already
@@ -141,6 +213,11 @@ pub(crate) fn extend_worker_env_unset_for_effort(
     out
 }
 
+/// ---
+/// purpose: 从 YAML agent 节点解析出可用的 effort
+/// returns: 该 provider 支持的 effort，否则 None
+/// contract_id: lifecycle.identity.effort_for_spawn
+/// ---
 /// Convenience: resolve effort for a yaml::Value agent (spec / compiled).
 pub(crate) fn provider_effort_for_spawn(
     agent: &crate::model::yaml::Value,
@@ -149,6 +226,11 @@ pub(crate) fn provider_effort_for_spawn(
     provider_effort_from_raw(agent.get("effort").and_then(|v| v.as_str()), provider)
 }
 
+/// ---
+/// purpose: 从 YAML agent 节点取 effort，若被丢弃则给出告警事件载荷
+/// returns: 告警载荷或 None
+/// contract_id: lifecycle.identity.effort_event_if_dropped
+/// ---
 pub(crate) fn provider_effort_event_if_dropped(
     agent: &crate::model::yaml::Value,
     provider: Provider,
@@ -161,6 +243,11 @@ pub(crate) fn provider_effort_event_if_dropped(
     )
 }
 
+/// ---
+/// purpose: 从 runtime state 的 JSON agent 节点解析出可用的 effort
+/// returns: 该 provider 支持的 effort，否则 None
+/// contract_id: lifecycle.identity.effort_for_spawn
+/// ---
 /// Same as [`provider_effort_for_spawn`] but for serde_json state values
 /// (used by restart paths reading from `state.agents[id]`).
 pub(crate) fn provider_effort_for_spawn_json(
@@ -173,6 +260,11 @@ pub(crate) fn provider_effort_for_spawn_json(
     )
 }
 
+/// ---
+/// purpose: 从 JSON agent 节点取 effort，若被丢弃则给出告警事件载荷
+/// returns: 告警载荷或 None
+/// contract_id: lifecycle.identity.effort_event_if_dropped
+/// ---
 pub(crate) fn provider_effort_event_if_dropped_json(
     agent: &serde_json::Value,
     provider: Provider,
@@ -185,6 +277,10 @@ pub(crate) fn provider_effort_event_if_dropped_json(
     )
 }
 
+/// ---
+/// purpose: 定出 quick-start 本次请求的团队键
+/// returns: team_id 优先于 name 的第一个非空值
+/// ---
 pub(super) fn quick_start_requested_team_key<'a>(
     team_id: Option<&'a str>,
     name: Option<&'a str>,
@@ -197,6 +293,15 @@ pub(super) struct QuickStartDepth {
     pub(super) team_depth: u64,
 }
 
+/// ---
+/// purpose: 定出本次 quick-start 的父团队键与团队层级
+/// params:
+///   requested_team: 请求的团队键，用于识别 child 或 grandchild 这类嵌套意图
+///   _agents_dir: 未参与判定
+///   _strict_real_runtime: 未参与判定
+/// returns: 父团队键与层级；无父上下文时父键为 None、层级为 1
+/// errors: 已有活跃团队且请求键像嵌套意图但推不出父团队时返回 RequirementUnmet
+/// ---
 pub(super) fn quick_start_depth_guard(
     workspace: &Path,
     _agents_dir: &Path,
@@ -257,6 +362,10 @@ pub(super) fn quick_start_depth_guard(
     })
 }
 
+/// ---
+/// purpose: 从 runtime state 推断父团队键
+/// returns: 活跃团队键，且该团队确有 running 席位时返回它，否则 None
+/// ---
 pub(super) fn infer_parent_team_from_active_state(state: &serde_json::Value) -> Option<String> {
     let active = explicit_active_team_key(state)?;
     let team = state
@@ -266,6 +375,10 @@ pub(super) fn infer_parent_team_from_active_state(state: &serde_json::Value) ->
     team_has_running_agent(team).then_some(active)
 }
 
+/// ---
+/// purpose: 判断 state 里是否存在带 running 席位的团队
+/// returns: 任一团队有 running 席位即 true
+/// ---
 pub(super) fn has_live_runtime_teams(state: &serde_json::Value) -> bool {
     state
         .get("teams")
@@ -273,6 +386,10 @@ pub(super) fn has_live_runtime_teams(state: &serde_json::Value) -> bool {
         .is_some_and(|teams| teams.values().any(team_has_running_agent))
 }
 
+/// ---
+/// purpose: 判断某团队节点里是否有状态为 running 的席位
+/// returns: 有则 true
+/// ---
 pub(super) fn team_has_running_agent(team: &serde_json::Value) -> bool {
     team.get("agents")
         .and_then(serde_json::Value::as_object)
@@ -283,6 +400,12 @@ pub(super) fn team_has_running_agent(team: &serde_json::Value) -> bool {
         })
 }
 
+/// ---
+/// purpose: 判断团队键是否像有歧义的子团队名
+/// params:
+///   team: 团队键，比较前去空白并转小写
+/// returns: 以 child 开头但不等于 child 时为 true
+/// ---
 pub(super) fn looks_ambiguous_child_team_key(team: &str) -> bool {
     let team = team.trim().to_ascii_lowercase();
     team != "child"
@@ -292,6 +415,10 @@ pub(super) fn looks_ambiguous_child_team_key(team: &str) -> bool {
             || team.starts_with("child"))
 }
 
+/// ---
+/// purpose: 判断团队键是否像孙团队名
+/// returns: 等于 grandchild 或以 grandchild 开头时为 true
+/// ---
 pub(super) fn looks_grandchild_team_key(team: &str) -> bool {
     let team = team.trim().to_ascii_lowercase();
     team == "grandchild"
@@ -301,6 +428,12 @@ pub(super) fn looks_grandchild_team_key(team: &str) -> bool {
         || team.starts_with("grandchild")
 }
 
+/// ---
+/// purpose: 就地给团队节点写上 team_depth 与可选的 parent_team_key
+/// params:
+///   state: 待改写的团队节点，非对象时不动
+///   parent_team_key: 非空时才写入
+/// ---
 pub(super) fn annotate_team_depth(
     state: &mut serde_json::Value,
     parent_team_key: Option<&str>,
@@ -315,6 +448,11 @@ pub(super) fn annotate_team_depth(
     }
 }
 
+/// ---
+/// purpose: 读出 runtime state，给指定团队写上层级与父键后存回
+/// returns: 成功返回空值；state 里没有该团队时直接返回成功且不写盘
+/// errors: 读或写 runtime state 失败时返回 StatePersist
+/// ---
 pub(super) fn annotate_persisted_team_depth(
     workspace: &Path,
     team_key: &str,
@@ -340,6 +478,10 @@ pub(super) fn annotate_persisted_team_depth(
     Ok(())
 }
 
+/// ---
+/// purpose: 判断 runtime state 里是否已存在该 quick-start 团队
+/// returns: 活跃键、teams 表、投影出的团队键、身份字段或 session 名任一命中即 true
+/// ---
 pub(super) fn runtime_state_has_quick_start_team(state: &serde_json::Value, team: &str) -> bool {
     explicit_active_team_key(state).as_deref() == Some(team)
         || state
@@ -359,6 +501,10 @@ pub(super) fn runtime_state_has_quick_start_team(state: &serde_json::Value, team
             .is_some_and(|session| session == team || session.strip_prefix("team-") == Some(team))
 }
 
+/// ---
+/// purpose: 判断某 JSON 节点的团队身份字段是否等于给定团队键
+/// returns: team.id、team.name 或顶层 name 命中即 true
+/// ---
 pub(super) fn json_team_identity_matches(state: &serde_json::Value, team: &str) -> bool {
     state
         .get("team")