@team-agent/installer 0.5.110 → 0.5.112

package/crates/team-agent/src/cli/adapters.rs

@@ -4,7 +4,6 @@
 //! `cmd_doctor`(gate/comms/fix-schema/cleanup-orphans 分派)。
 
 use super::*;
-use crate::transport::Transport;
 
 /// `cmd_quick_start`(`commands.py:18`)。`--json` 或 `!ok` → 整 dict;否则 `result["summary"]`。
 pub fn cmd_quick_start(args: &QuickStartArgs) -> Result<CmdResult, CliError> {
@@ -16,6 +15,9 @@ pub fn cmd_quick_start(args: &QuickStartArgs) -> Result<CmdResult, CliError> {
         args.yes,
         args.backend.as_deref(),
     )?;
+    if let Some(result) = quick_start_config_guidance(&mut value, args) {
+        return Ok(result);
+    }
     append_send_guidance(&mut value, &args.workspace, args.team_id.as_deref());
     let readiness = value.get("readiness").and_then(Value::as_object);
     let all_resumable_have_session = readiness
@@ -46,6 +48,29 @@ pub fn cmd_quick_start(args: &QuickStartArgs) -> Result<CmdResult, CliError> {
         if args.json && status.as_deref() == Some("pending_tool_load") {
             result.exit = ExitCode::Ok;
         }
+        if !args.json {
+            if let CmdOutput::Json(value) = &result.output {
+                let explanation = if value.get("ok").and_then(Value::as_bool) == Some(false) {
+                    format!(
+                        "启动未完成：{}",
+                        value
+                            .get("error")
+                            .and_then(Value::as_str)
+                            .unwrap_or("队伍尚未准备好接收任务")
+                    )
+                } else {
+                    "队伍尚未准备好接收任务；请等待工具完成启动。".to_string()
+                };
+                let mut doctor = format!(
+                    "team-agent doctor --workspace {}",
+                    shell_quote(&args.workspace.to_string_lossy())
+                );
+                if let Some(team) = args.team_id.as_deref() {
+                    doctor.push_str(&format!(" --team {}", shell_quote(team)));
+                }
+                result.output = CmdOutput::Human(format!("{explanation}\n下一步：运行 {doctor}，按体检提示处理；用 status 查看状态，不反复起队或重发任务。"));
+            }
+        }
         Ok(result)
     } else {
         // E13:happy 人类路径必须带 attach_commands(json 路径 cli/mod.rs:1775 已有)。
@@ -53,13 +78,99 @@ pub fn cmd_quick_start(args: &QuickStartArgs) -> Result<CmdResult, CliError> {
     }
 }
 
+// Project only an actual compiler rejection; never reject a valid lifecycle fallback.
+fn quick_start_config_guidance(value: &mut Value, args: &QuickStartArgs) -> Option<CmdResult> {
+    if value.get("ok").and_then(Value::as_bool) != Some(false) {
+        return None;
+    }
+    let error = value.get("error")?.as_str()?;
+    let compile = error.strip_prefix("spec compile failed: ")?;
+    let detail = compile
+        .strip_prefix("validation error: ")
+        .unwrap_or(compile);
+    let team_path = args.agents_dir.join("TEAM.md");
+    let agents_path = args.agents_dir.join("agents");
+    let missing_team = detail == format!("{}: missing TEAM.md", team_path.display())
+        && team_path.try_exists().ok() == Some(false);
+    let missing_roles = detail == format!("{}: missing agents directory", agents_path.display())
+        || detail == format!("{}: no role docs found", agents_path.display());
+    let missing_field = detail.split_once(": ").is_some_and(|(path, reason)| {
+        Path::new(path).parent() == Some(agents_path.as_path())
+            && (reason.contains("missing required field") || reason.contains("is required"))
+    });
+    if !missing_team && !(team_path.is_file() && (missing_roles || missing_field)) {
+        return None;
+    }
+    let role_path = agents_path.join("worker.md");
+    let mut retry = format!(
+        "team-agent quick-start {} --workspace {}",
+        shell_quote(&args.agents_dir.to_string_lossy()),
+        shell_quote(&args.workspace.to_string_lossy())
+    );
+    if let Some(team) = args.team_id.as_deref() {
+        retry.push_str(&format!(" --team {}", shell_quote(team)));
+    }
+    if let Some(name) = args.name.as_deref() {
+        retry.push_str(&format!(" --name {}", shell_quote(name)));
+    }
+    if let Some(backend) = args.backend.as_deref() {
+        retry.push_str(&format!(" --backend {}", shell_quote(backend)));
+    }
+    if args.yes {
+        retry.push_str(" --yes");
+    }
+    if args.detail {
+        retry.push_str(" --detail");
+    }
+    if args.json {
+        retry.push_str(" --json");
+    }
+    let explanation = if missing_team {
+        format!("这里还没有队伍配置：{}。没有启动任何队友。请自行创建下面两个文件；本命令没有写入这些文件。", team_path.display())
+    } else {
+        format!("队友配置尚不完整：{detail}。请补齐角色目录或必需字段；下面仅给安全示例，不覆盖已有文件。")
+    };
+    let next = format!("确认 Pi 已安装并登录；运行 team-agent models --provider pi 核对模型。\n运行 team-agent pi，在该主控的命令行/工具上下文再次执行：\n{retry}");
+    let mut templates =
+        vec![serde_json::json!({"path": role_path, "content": super::emit::WORKER_TEMPLATE})];
+    let mut human = explanation.clone();
+    if missing_team {
+        templates.insert(
+            0,
+            serde_json::json!({"path": team_path, "content": super::emit::TEAM_TEMPLATE}),
+        );
+        human.push_str(&format!(
+            "\n\n{}：\n{}",
+            team_path.display(),
+            super::emit::TEAM_TEMPLATE
+        ));
+    }
+    human.push_str(&format!(
+        "\n\n{}：\n{}\n下一步：\n{next}",
+        role_path.display(),
+        super::emit::WORKER_TEMPLATE
+    ));
+    value["action"] = serde_json::json!(explanation);
+    value["next_actions"] =
+        serde_json::json!(["team-agent models --provider pi", "team-agent pi", retry]);
+    value["templates"] = serde_json::json!(templates);
+    if args.json {
+        Some(CmdResult::from_json(value.clone(), true))
+    } else {
+        let mut result = CmdResult::human(&human);
+        result.exit = ExitCode::Error;
+        Some(result)
+    }
+}
+
 /// E13:quick-start "team 起了" 人类输出 = summary + attach 块。所有成功出口共用(别每分支手拷)。
 /// attach_commands 缺/空 → 只 summary(向后兼容)。
 fn quickstart_human(value: &Value) -> String {
-    let summary = value
-        .get("summary")
-        .and_then(Value::as_str)
-        .unwrap_or("quick-start complete");
+    let summary = if value.get("summary").and_then(Value::as_str) == Some("existing runtime") {
+        "发现已有队伍；请查看返回的连接方式，不会另建同名队伍。"
+    } else {
+        "队伍已启动；下面是连接方式和派发任务的命令。"
+    };
     let attach: Vec<&str> = value
         .get("attach_commands")
         .and_then(Value::as_array)
@@ -72,14 +183,14 @@ fn quickstart_human(value: &Value) -> String {
         .unwrap_or_default();
     let mut out = String::from(summary);
     if !attach.is_empty() {
-        out.push_str("\n\nattach:");
+        out.push_str("\n\n连接队伍：");
         for cmd in attach {
             out.push_str("\n  ");
             out.push_str(cmd);
         }
     }
     if !sends.is_empty() {
-        out.push_str("\n\nsend:");
+        out.push_str("\n\n派发任务（请替换任务内容）：");
         for cmd in sends {
             out.push_str("\n  ");
             out.push_str(cmd);
@@ -146,7 +257,7 @@ pub(crate) fn send_command(agent: &str, workspace: &Path, team: Option<&str>) ->
     let mut command = format!(
         "team-agent send {} {} --workspace {}",
         shell_quote(agent),
-        shell_quote("MESSAGE"),
+        shell_quote("请完成任务并把答案回复给 leader。"),
         shell_quote(workspace)
     );
     if let Some(team) = team {
@@ -156,7 +267,7 @@ pub(crate) fn send_command(agent: &str, workspace: &Path, team: Option<&str>) ->
     Some(command)
 }
 
-fn shell_quote(value: &str) -> String {
+pub(crate) fn shell_quote(value: &str) -> String {
     if value.bytes().all(|byte| {
         byte.is_ascii_alphanumeric() || matches!(byte, b'/' | b'.' | b'_' | b'-' | b':')
     }) {
@@ -238,701 +349,11 @@ pub fn cmd_status_for_team(args: &StatusArgs, team: Option<&str>) -> Result<CmdR
     )))
 }
 
-/// `cmd_watch`(`commands.py:103`)。委派 `coordinator::run_watch`;KeyboardInterrupt/正常 → `SystemExit(0)`。
-/// 返回 [`CmdResult::none`](不经 emit)。
-pub fn cmd_watch(args: &WatchArgs) -> Result<CmdResult, CliError> {
-    let workspace = crate::coordinator::WorkspacePath::new(args.workspace.clone());
-    #[cfg(not(test))]
-    {
-        let mut output = |line: &str| {
-            println!("{line}");
-            let _ = std::io::Write::flush(&mut std::io::stdout());
-        };
-        crate::coordinator::run_watch(&workspace, args.team.as_deref(), 1.0, &mut output)
-            .map_err(|e| CliError::Runtime(e.to_string()))?;
-        Ok(CmdResult::none())
-    }
-    #[cfg(test)]
-    {
-        let store = crate::message_store::MessageStore::open(&args.workspace)
-            .map_err(|e| CliError::Runtime(e.to_string()))?;
-        let mut cursor = crate::coordinator::WatchCursor::default();
-        let lines = crate::coordinator::collect_watch_lines(
-            &workspace,
-            &mut cursor,
-            &store,
-            args.team.as_deref(),
-        )
-        .map_err(|e| CliError::Runtime(e.to_string()))?;
-        Ok(CmdResult::human(lines.join("\n")))
-    }
-}
-
-/// `cmd_sessions`(`parser.py:230`)。
-pub fn cmd_sessions(args: &SessionsArgs) -> Result<CmdResult, CliError> {
-    let selected = crate::state::selector::resolve_active_team(
-        &args.workspace,
-        args.team.as_deref(),
-        crate::state::selector::SelectorMode::RuntimeOnly,
-    )
-    .map_err(|e| CliError::Runtime(e.to_string()))?;
-    let spec = match selected.spec_path.as_ref() {
-        Some(path) => load_team_spec_at(path)?,
-        None => load_team_spec_optional(&selected.run_workspace, &selected.state)?,
-    };
-    Ok(CmdResult::from_json(
-        json!({
-            "ok": true,
-            "sessions": sessions_overview(&selected.state, spec.as_ref()),
-            "workspace": args.workspace.to_string_lossy().to_string(),
-        }),
-        args.json,
-    ))
-}
-
-pub fn cmd_results(args: &ResultsArgs) -> Result<CmdResult, CliError> {
-    let selected = match crate::state::selector::resolve_active_team(
-        &args.workspace,
-        args.team.as_deref(),
-        crate::state::selector::SelectorMode::RuntimeOnly,
-    ) {
-        Ok(selected) => selected,
-        Err(error) => {
-            return Ok(CmdResult::from_json(
-                json!({
-                    "ok": false,
-                    "error": error.to_string(),
-                    "workspace": args.workspace.to_string_lossy().to_string(),
-                }),
-                args.json,
-            ));
-        }
-    };
-    let results = messaging::results::results_for_case(
-        &selected.run_workspace,
-        &args.case_id,
-        Some(selected.team_key.as_str()),
-        args.team.as_deref(),
-    )?;
-    let value = json!({
-        "ok": true,
-        "case_id": args.case_id,
-        "results": results,
-        "workspace": selected.run_workspace.to_string_lossy().to_string(),
-    });
-    Ok(if args.json {
-        CmdResult::from_ordered_json(value)
-    } else {
-        CmdResult::from_json(value, false)
-    })
-}
-
 pub fn cmd_wait(args: &WaitArgs) -> Result<CmdResult, CliError> {
     let result = messaging::wait_for_result(&args.workspace, &args.task_id)?;
     Ok(CmdResult::from_json(result.to_json(), args.json))
 }
 
-/// `cmd_allow_peer_talk`(`parser.py allow-peer-talk`).
-pub fn cmd_allow_peer_talk(args: &AllowPeerTalkArgs) -> Result<CmdResult, CliError> {
-    if args.team.is_some() {
-        return Err(CliError::Usage(
-            "allow-peer-talk --team is not supported yet because peer allowlist storage is not team-scoped".to_string(),
-        ));
-    }
-    let value = messaging::allow_peer_talk(&args.workspace, &args.a, &args.b)?;
-    Ok(CmdResult::from_json(value, args.json))
-}
-
-/// `cmd_preflight`(`parser.py:160`)。
-pub fn cmd_preflight(args: &PreflightArgs) -> Result<CmdResult, CliError> {
-    let report = build_preflight_report(&args.team)?;
-    Ok(CmdResult::from_json(report, args.json))
-}
-
-/// `cmd_wait_ready`(`parser.py:171`)。
-pub fn cmd_wait_ready(args: &WaitReadyArgs) -> Result<CmdResult, CliError> {
-    let report = build_wait_ready_report(&args.workspace, args.timeout, args.team.as_deref())?;
-    Ok(CmdResult::from_json(report, args.json))
-}
-
-/// `cmd_e2e`(`parser.py:449`)。
-pub fn cmd_e2e(args: &E2eArgs) -> Result<CmdResult, CliError> {
-    let mut providers = serde_json::Map::new();
-    for provider in &args.providers {
-        let result = if provider == "fake" {
-            run_fake_e2e(&args.workspace)?
-        } else {
-            skipped_provider_e2e(provider, args.real)
-        };
-        providers.insert(provider.clone(), result);
-    }
-    let ok = providers
-        .values()
-        .all(|value| value.get("ok").and_then(Value::as_bool) == Some(true));
-    Ok(CmdResult::from_json(
-        json!({
-            "workspace": args.workspace.to_string_lossy().to_string(),
-            "providers": Value::Object(providers),
-            "ok": ok,
-        }),
-        args.json,
-    ))
-}
-
-/// `cmd_peek`(`commands.py:118`)。
-pub fn cmd_peek(args: &PeekArgs) -> Result<CmdResult, CliError> {
-    if !args.allow_raw_screen {
-        return Err(CliError::Usage(
-            "peek requires --allow-raw-screen".to_string(),
-        ));
-    }
-    let state = crate::state::persist::load_runtime_state(&args.workspace)?;
-    let Some(agent_state) = state
-        .get("agents")
-        .and_then(|agents| agents.get(&args.agent))
-    else {
-        return Ok(CmdResult::from_json(
-            json!({
-                "ok": false,
-                "agent_id": args.agent,
-                "error": format!("unknown agent id: {}", args.agent),
-            }),
-            args.json,
-        ));
-    };
-    let Some((session, window, target)) = agent_pane_id(&state, &args.agent, agent_state) else {
-        return Ok(peek_unavailable(&args.agent, args.json));
-    };
-    // 0.5.x Phase 1d Batch 3: factory-routed peek backend so conpty
-    // teams peek from the shim scrollback rather than a workspace
-    // tmux capture that would always be empty. Tmux teams keep
-    // byte-equivalent behavior.
-    let backend: Box<dyn crate::transport::Transport> =
-        match crate::transport_factory::resolve_read_only_transport(
-            &args.workspace,
-            Some(&state),
-            crate::transport_factory::TransportPurpose::Status,
-        ) {
-            Ok(r) => r.backend,
-            Err(_) => Box::new(crate::tmux_backend::TmuxBackend::for_workspace(
-                &args.workspace,
-            )),
-        };
-    let windows = backend
-        .list_windows(&crate::transport::SessionName::new(session.clone()))
-        .map_err(|e| CliError::Runtime(e.to_string()))?;
-    if !windows.iter().any(|w| w.as_str() == window) {
-        return Ok(peek_unavailable(&args.agent, args.json));
-    }
-    let range = args
-        .head
-        .map(|head| crate::transport::CaptureRange::Head(head as u32))
-        .unwrap_or_else(|| crate::transport::CaptureRange::Tail(args.tail as u32));
-    let capture = backend
-        .capture(
-            &crate::transport::Target::Pane(crate::transport::PaneId::new(target.clone())),
-            range,
-        )
-        .map_err(|e| CliError::Runtime(e.to_string()))?;
-    let matches = args.search.as_ref().map(|needle| {
-        capture
-            .text
-            .lines()
-            .filter(|line| line.contains(needle))
-            .map(str::to_string)
-            .collect::<Vec<_>>()
-    });
-    Ok(CmdResult::from_json(
-        json!({
-            "ok": true,
-            "agent_id": args.agent,
-            "workspace": args.workspace.to_string_lossy().to_string(),
-            "tail": args.tail,
-            "head": args.head,
-            "search": args.search,
-            "matches": matches,
-            "pane_id": target,
-            "text": capture.text,
-        }),
-        args.json,
-    ))
-}
-
-fn peek_unavailable(agent: &str, json: bool) -> CmdResult {
-    CmdResult::from_json(
-        json!({
-            "ok": false,
-            "agent_id": agent,
-            "error": format!("agent terminal is not available: {agent}"),
-        }),
-        json,
-    )
-}
-
-fn agent_pane_id(
-    state: &Value,
-    agent: &str,
-    agent_state: &Value,
-) -> Option<(String, String, String)> {
-    let session = state
-        .get("session_name")
-        .and_then(Value::as_str)
-        .filter(|s| !s.is_empty())?;
-    let window = ["window", "window_name"]
-        .iter()
-        .find_map(|key| {
-            agent_state
-                .get(*key)
-                .and_then(Value::as_str)
-                .filter(|s| !s.is_empty())
-        })
-        .unwrap_or(agent);
-    Some((
-        session.to_string(),
-        window.to_string(),
-        format!("{session}:{window}"),
-    ))
-}
-
-fn run_fake_e2e(workspace: &Path) -> Result<Value, CliError> {
-    std::fs::create_dir_all(workspace)?;
-    let spec_path = workspace.join("team.spec.yaml");
-    std::fs::write(&spec_path, fake_spec_yaml(workspace))?;
-    let launch = match crate::lifecycle::launch(&spec_path, true, true, true) {
-        Ok(report) => json!({
-            "ok": true,
-            "dry_run": report.dry_run,
-            "session_name": report.session_name.as_str(),
-        }),
-        Err(error) => json!({
-            "ok": false,
-            "error": error.to_string(),
-        }),
-    };
-    seed_fake_e2e_state(workspace)?;
-    let send = messaging::send_message(
-        workspace,
-        &MessageTarget::Single("fake_impl".to_string()),
-        "implement fake task",
-        &SendOptions {
-            task_id: Some(TaskId::new("task_impl")),
-            route_task_id: false,
-            sender: messaging::TrustedSender::leader(),
-            requires_ack: true,
-            ..SendOptions::default()
-        },
-    )?;
-    let send_value = json!({
-        "ok": send.ok,
-        "status": send.status,
-        "message_status": send.message_status.0,
-        "message_id": send.message_id,
-        "reason": send.reason,
-    });
-    if send.ok {
-        if let Some(message_id) = send.message_id.as_deref() {
-            crate::message_store::MessageStore::open(workspace)
-                .map_err(crate::messaging::MessagingError::from)?
-                .mark(message_id, "delivered", None)
-                .map_err(crate::messaging::MessagingError::from)?;
-        }
-        let report = messaging::report_result(
-            workspace,
-            &json!({
-                "schema_version": "result_envelope_v1",
-                "task_id": "task_impl",
-                "agent_id": "fake_impl",
-                "status": "success",
-                "summary": "fake result finalized",
-                "changes": [],
-                "tests": [],
-                "risks": [],
-                "artifacts": [],
-                "next_actions": [],
-            }),
-        )?;
-        let auto_finalized = report
-            .get("finalization_status")
-            .and_then(Value::as_str)
-            == Some("auto_finalized");
-        let shutdown = fake_shutdown(workspace)?;
-        let ok = launch.get("ok").and_then(Value::as_bool) == Some(true)
-            && send.ok
-            && auto_finalized
-            && shutdown.get("ok").and_then(Value::as_bool) == Some(true);
-        return Ok(json!({
-            "ok": ok,
-            "launch": launch,
-            "send": send_value,
-            "report": report,
-            "shutdown": shutdown,
-        }));
-    }
-    let shutdown = fake_shutdown(workspace)?;
-    Ok(json!({
-        "ok": false,
-        "launch": launch,
-        "send": send_value,
-        "report": null,
-        "shutdown": shutdown,
-    }))
-}
-
-fn skipped_provider_e2e(provider: &str, real: bool) -> Value {
-    let command = provider_command(provider);
-    if !command_on_path(command) {
-        return json!({
-            "ok": false,
-            "skipped": true,
-            "reason": format!("{command} not installed"),
-            "version": null,
-        });
-    }
-    let version = command_version(command);
-    if !real {
-        return json!({
-            "ok": false,
-            "skipped": true,
-            "reason": "real provider launch disabled; rerun with --real on an authenticated machine",
-            "version": version,
-        });
-    }
-    json!({
-        "ok": false,
-        "skipped": true,
-        "reason": "real provider e2e is not available in this build",
-        "version": version,
-    })
-}
-
-fn command_on_path(command: &str) -> bool {
-    std::env::var_os("PATH").is_some_and(|paths| {
-        std::env::split_paths(&paths).any(|dir| {
-            let candidate = dir.join(command);
-            candidate.is_file()
-        })
-    })
-}
-
-fn command_version(command: &str) -> Value {
-    match std::process::Command::new(command)
-        .arg("--version")
-        .output()
-    {
-        Ok(output) if output.status.success() => {
-            let text = String::from_utf8_lossy(&output.stdout).trim().to_string();
-            if text.is_empty() {
-                Value::Null
-            } else {
-                Value::String(text)
-            }
-        }
-        _ => Value::Null,
-    }
-}
-
-fn provider_command(provider: &str) -> &str {
-    // E2E provider command grammar, not persisted provider identity parsing.
-    match provider {
-        "claude" | "claude_code" => "claude",
-        "gemini" | "gemini_cli" => "gemini",
-        other => other,
-    }
-}
-
-fn seed_fake_e2e_state(workspace: &Path) -> Result<(), CliError> {
-    crate::state::repository::StateRepository::new(workspace).save(
-        crate::state::repository::StateWriteIntent::FakeE2eSeed,
-        &json!({
-            "leader": {"id": "leader"},
-            "session_name": "team-agent-fake-e2e",
-            "agents": {
-                "fake_impl": {
-                    "provider": "fake",
-                    "status": "running",
-                    "window": "fake_impl",
-                    "pane_id": "%fake_impl",
-                    "spawn_cwd": workspace.to_string_lossy().to_string(),
-                }
-            },
-            "tasks": [{
-                "id": "task_impl",
-                "title": "Fake implementation",
-                "type": "implementation",
-                "assignee": "fake_impl",
-                "status": "pending",
-            }]
-        }),
-    )?;
-    Ok(())
-}
-
-fn fake_shutdown(workspace: &Path) -> Result<Value, CliError> {
-    let mut state = crate::state::persist::load_runtime_state(workspace)?;
-    if let Some(agents) = state.get_mut("agents").and_then(Value::as_object_mut) {
-        for agent in agents.values_mut() {
-            if let Some(obj) = agent.as_object_mut() {
-                obj.insert("status".to_string(), Value::String("stopped".to_string()));
-            }
-        }
-    }
-    crate::state::repository::StateRepository::new(workspace).save(
-        crate::state::repository::StateWriteIntent::FakeE2eSeed,
-        &state,
-    )?;
-    Ok(json!({
-        "ok": true,
-        "session_name": state.get("session_name").cloned().unwrap_or(Value::Null),
-        "session_killed": false,
-        "coordinator": {"status": "missing", "pid": null},
-    }))
-}
-
-fn fake_spec_yaml(workspace: &Path) -> String {
-    let ws = workspace.to_string_lossy();
-    format!(
-        r#"version: 1
-team:
-  name: "fake-e2e"
-  mode: "supervisor_worker"
-  objective: "Exercise fake provider orchestration."
-  workspace: "{ws}"
-leader:
-  id: "leader"
-  role: "leader"
-  provider: "fake"
-  model: null
-  tools:
-    - "fs_read"
-    - "fs_list"
-    - "mcp_team"
-  context_policy:
-    keep_user_thread: true
-    receive_worker_outputs: "structured_only"
-    max_worker_result_tokens: 2000
-agents:
-  - id: "fake_impl"
-    role: "implementation_engineer"
-    provider: "fake"
-    model: null
-    working_directory: "{ws}"
-    system_prompt:
-      inline: "Handle fake implementation tasks."
-      file: null
-    tools:
-      - "fs_read"
-      - "fs_write"
-      - "fs_list"
-      - "execute_bash"
-      - "git_diff"
-      - "mcp_team"
-      - "provider_builtin"
-    permission_mode: "restricted"
-    preferred_for:
-      - "implementation"
-    avoid_for: []
-    output_contract:
-      format: "result_envelope_v1"
-      required_fields:
-        - "task_id"
-        - "status"
-        - "summary"
-        - "artifacts"
-routing:
-  default_assignee: "leader"
-  rules:
-    - id: "implementation-to-fake"
-      match:
-        type:
-          - "implementation"
-      assign_to: "fake_impl"
-      priority: 10
-communication:
-  protocol: "mcp_inbox"
-  topology: "leader_centered"
-  worker_to_worker: true
-  ack_timeout_sec: 2
-  result_format: "result_envelope_v1"
-  message_store:
-    sqlite: ".team/runtime/team.db"
-    mirror_files: ".team/messages"
-runtime:
-  backend: "tmux"
-  session_name: "team-agent-fake-e2e"
-  auto_launch: true
-  require_user_approval_before_launch: false
-  max_active_agents: 1
-  startup_order:
-    - "fake_impl"
-context:
-  state_file: "team_state.md"
-  artifact_dir: ".team/artifacts"
-  log_dir: ".team/logs"
-  summarization:
-    worker_full_logs: "retain_outside_leader_context"
-    state_update: "after_each_result"
-tasks:
-  - id: "task_impl"
-    title: "Fake implementation"
-    type: "implementation"
-    assignee: "fake_impl"
-    deps: []
-    acceptance:
-      - "fake result collected"
-    status: "pending"
-    requires_tools:
-      - "fs_write"
-      - "execute_bash"
-    files:
-      - "src/example.py"
-    risk: "low"
-"#
-    )
-}
-
-fn sessions_overview(state: &Value, spec: Option<&crate::model::yaml::Value>) -> Value {
-    let mut rows = Vec::new();
-    if let Some(agents) = spec
-        .and_then(|v| v.get("agents"))
-        .and_then(crate::model::yaml::Value::as_list)
-    {
-        for agent in agents {
-            let Some(agent_id) = agent.get("id").and_then(crate::model::yaml::Value::as_str) else {
-                continue;
-            };
-            let agent_state = state
-                .get("agents")
-                .and_then(|agents| agents.get(agent_id))
-                .unwrap_or(&Value::Null);
-            rows.push(session_row(state, agent, agent_id, agent_state));
-        }
-    }
-    Value::Array(rows)
-}
-
-fn session_row(
-    state: &Value,
-    spec_agent: &crate::model::yaml::Value,
-    agent_id: &str,
-    agent_state: &Value,
-) -> Value {
-    json!({
-        "agent_id": agent_id,
-        "provider": yaml_str(spec_agent, "provider").map(Value::String).unwrap_or(Value::Null),
-        "model": yaml_str(spec_agent, "model").map(Value::String).unwrap_or(Value::Null),
-        "profile": yaml_str(spec_agent, "profile").map(Value::String).unwrap_or(Value::Null),
-        "session_id": field_or_null(agent_state, &["session_id"]),
-        "resume_id": field_or_null(agent_state, &["resume_id"]),
-        "rollout_path": field_or_null(agent_state, &["rollout_path"]),
-        "captured_at": field_or_null(agent_state, &["captured_at"]),
-        "captured_via": field_or_null(agent_state, &["captured_via"]),
-        "attribution_confidence": field_or_null(agent_state, &["attribution_confidence"]),
-        "spawn_cwd": field_or_null(agent_state, &["spawn_cwd", "working_directory"]),
-        "context_usage": field_or_null(agent_state, &["context_usage"]),
-        "status": field_or_default(agent_state, "status", "unknown"),
-        "last_task": last_task_for_agent(state, agent_id),
-        "handoff_path": field_or_null(agent_state, &["handoff_path"]),
-        "display_target": field_or_null(agent_state, &["display"]),
-        "terminal_target": terminal_target(state, agent_id, agent_state),
-    })
-}
-
-fn yaml_str(value: &crate::model::yaml::Value, key: &str) -> Option<String> {
-    value
-        .get(key)
-        .and_then(crate::model::yaml::Value::as_str)
-        .map(ToString::to_string)
-}
-
-fn field_or_null(value: &Value, keys: &[&str]) -> Value {
-    keys.iter()
-        .find_map(|key| value.get(*key).cloned())
-        .unwrap_or(Value::Null)
-}
-
-fn field_or_default(value: &Value, key: &str, default: &str) -> Value {
-    value
-        .get(key)
-        .cloned()
-        .unwrap_or_else(|| Value::String(default.to_string()))
-}
-
-fn last_task_for_agent(state: &Value, agent_id: &str) -> Value {
-    state
-        .get("tasks")
-        .and_then(Value::as_array)
-        .and_then(|tasks| {
-            tasks
-                .iter()
-                .rev()
-                .find(|task| task.get("assignee").and_then(Value::as_str) == Some(agent_id))
-        })
-        .and_then(|task| {
-            task.get("id")
-                .and_then(Value::as_str)
-                .map(ToString::to_string)
-        })
-        .map(Value::String)
-        .unwrap_or(Value::Null)
-}
-
-fn terminal_target(state: &Value, agent_id: &str, agent_state: &Value) -> Value {
-    json!({
-        "session": agent_state
-            .get("session_name")
-            .cloned()
-            .or_else(|| state.get("session_name").cloned())
-            .unwrap_or(Value::Null),
-        "window": window_target(agent_state, agent_id),
-        "pane": field_or_null(agent_state, &["pane_id"]),
-    })
-}
-
-fn window_target(agent_state: &Value, agent_id: &str) -> Value {
-    let window = field_or_null(agent_state, &["window", "window_name"]);
-    if window.is_null() {
-        Value::String(agent_id.to_string())
-    } else {
-        window
-    }
-}
-
-fn load_team_spec_optional(
-    workspace: &Path,
-    state: &Value,
-) -> Result<Option<crate::model::yaml::Value>, CliError> {
-    let spec_path = state
-        .get("spec_path")
-        .and_then(Value::as_str)
-        .filter(|path| !path.is_empty())
-        .map(PathBuf::from)
-        .or_else(|| {
-            state
-                .get("team_dir")
-                .and_then(Value::as_str)
-                .filter(|path| !path.is_empty())
-                .map(|path| PathBuf::from(path).join("team.spec.yaml"))
-        })
-        .unwrap_or_else(|| workspace.join("team.spec.yaml"));
-    if !spec_path.exists() {
-        return Ok(None);
-    }
-    let text = std::fs::read_to_string(&spec_path)?;
-    crate::model::yaml::loads(&text)
-        .map(Some)
-        .map_err(|e| CliError::Runtime(e.to_string()))
-}
-
-fn load_team_spec_at(spec_path: &Path) -> Result<Option<crate::model::yaml::Value>, CliError> {
-    if !spec_path.exists() {
-        return Ok(None);
-    }
-    let text = std::fs::read_to_string(spec_path)?;
-    crate::model::yaml::loads(&text)
-        .map(Some)
-        .map_err(|e| CliError::Runtime(e.to_string()))
-}
-
 /// `cmd_approvals`(`commands.py:112`)。
 pub fn cmd_approvals(args: &ApprovalsArgs) -> Result<CmdResult, CliError> {
     let selected = crate::state::selector::resolve_active_team(
@@ -1015,27 +436,24 @@ fn format_inbox_human(agent: &str, value: &Value) -> String {
                     .and_then(Value::as_str)
                     .unwrap_or("-"),
             );
-            let sender = clean_inbox_field(
-                message.get("sender").and_then(Value::as_str).unwrap_or("-"),
-            );
+            let sender =
+                clean_inbox_field(message.get("sender").and_then(Value::as_str).unwrap_or("-"));
             let recipient = clean_inbox_field(
                 message
                     .get("recipient")
                     .and_then(Value::as_str)
                     .unwrap_or("-"),
             );
-            let status = clean_inbox_field(
-                message.get("status").and_then(Value::as_str).unwrap_or("-"),
-            );
+            let status =
+                clean_inbox_field(message.get("status").and_then(Value::as_str).unwrap_or("-"));
             let time = clean_inbox_field(
                 message
                     .get("created_at")
                     .and_then(Value::as_str)
                     .unwrap_or("-"),
             );
-            let summary = clean_inbox_field(
-                message.get("summary").and_then(Value::as_str).unwrap_or(""),
-            );
+            let summary =
+                clean_inbox_field(message.get("summary").and_then(Value::as_str).unwrap_or(""));
             truncate_inbox_line(&format!(
                 "[{id}] [{sender} -> {recipient}] [{status}] [{time}] [{summary}]"
             ))
@@ -1054,22 +472,13 @@ pub fn cmd_takeover(args: &TakeoverArgs) -> Result<CmdResult, CliError> {
 
 /// `cmd_claim_leader`(`commands.py:156`)。
 pub fn cmd_claim_leader(args: &ClaimLeaderArgs) -> Result<CmdResult, CliError> {
-    let mut value =
-        leader_port::claim_leader(&args.workspace, args.team.as_deref(), args.confirm)?;
+    let mut value = leader_port::claim_leader(&args.workspace, args.team.as_deref(), args.confirm)?;
     if !args.detail {
         leader_port::compact_lease_value(&mut value);
     }
     Ok(CmdResult::from_json(value, args.json))
 }
 
-/// `cmd_identity`(`commands.py:160`)。
-pub fn cmd_identity(args: &IdentityArgs) -> Result<CmdResult, CliError> {
-    Ok(CmdResult::from_json(
-        leader_port::leader_identity(&args.workspace, args.team.as_deref())?,
-        args.json,
-    ))
-}
-
 /// `cmd_shutdown`(`commands.py:340`)。
 pub fn cmd_shutdown(args: &ShutdownArgs) -> Result<CmdResult, CliError> {
     Ok(CmdResult::from_json(
@@ -1104,10 +513,7 @@ pub fn cmd_start_agent(args: &StartAgentArgs) -> Result<CmdResult, CliError> {
     )?;
     if value.get("agent_ids").is_none() {
         if let Some(object) = value.as_object_mut() {
-            object.insert(
-                "agent_ids".to_string(),
-                json!([args.agent.as_str()]),
-            );
+            object.insert("agent_ids".to_string(), json!([args.agent.as_str()]));
         }
     }
     append_send_guidance(&mut value, &args.workspace, args.team.as_deref());
@@ -1147,10 +553,7 @@ pub fn cmd_add_agent(args: &AddAgentArgs) -> Result<CmdResult, CliError> {
     )?;
     if value.get("agent_ids").is_none() {
         if let Some(object) = value.as_object_mut() {
-            object.insert(
-                "agent_ids".to_string(),
-                json!([args.agent.as_str()]),
-            );
+            object.insert("agent_ids".to_string(), json!([args.agent.as_str()]));
         }
     }
     append_send_guidance(&mut value, &args.workspace, args.team.as_deref());
@@ -1222,10 +625,8 @@ pub fn cmd_doctor(args: &DoctorArgs) -> Result<CmdResult, CliError> {
     }
 
     let explicit_comms = args.comms || matches!(args.gate, Some(DoctorGate::Comms));
-    let default_report = !explicit_comms
-        && args.gate.is_none()
-        && !args.cleanup_orphans
-        && !args.fix_schema;
+    let default_report =
+        !explicit_comms && args.gate.is_none() && !args.cleanup_orphans && !args.fix_schema;
     let mut value = if explicit_comms {
         crate::diagnose::comms::doctor_comms_json(
             &args.workspace,
@@ -1282,22 +683,28 @@ fn unified_default_doctor_report(args: &DoctorArgs, mut value: Value) -> Value {
         args.team.as_deref(),
         crate::state::selector::SelectorMode::RuntimeOnly,
     );
-    let run_workspace = selected.as_ref().map(|selected| selected.run_workspace.clone())
-        .unwrap_or_else(|_| crate::model::paths::canonical_run_workspace(&args.workspace)
-            .unwrap_or_else(|_| args.workspace.clone()));
+    let run_workspace = selected
+        .as_ref()
+        .map(|selected| selected.run_workspace.clone())
+        .unwrap_or_else(|_| {
+            crate::model::paths::canonical_run_workspace(&args.workspace)
+                .unwrap_or_else(|_| args.workspace.clone())
+        });
     let runtime_present = selected.as_ref().is_ok_and(|selected| {
         crate::cli::diagnose::workspace_has_existing_team_runtime(
             &selected.run_workspace,
             &selected.team_key,
         )
     });
-    let db_present = crate::model::paths::runtime_dir(&run_workspace).join("team.db").exists();
+    let db_present = crate::model::paths::runtime_dir(&run_workspace)
+        .join("team.db")
+        .exists();
     // One read-only observation supplies both issue classification and details.
     // A physical database must be checked even before state.json is created.
     let health = (runtime_present || db_present).then(|| {
-        crate::coordinator::coordinator_health_read_only(
-            &crate::coordinator::WorkspacePath::new(run_workspace.clone()),
-        )
+        crate::coordinator::coordinator_health_read_only(&crate::coordinator::WorkspacePath::new(
+            run_workspace.clone(),
+        ))
     });
     match selected {
         Ok(selected) => {
@@ -1358,10 +765,17 @@ fn unified_default_doctor_report(args: &DoctorArgs, mut value: Value) -> Value {
     }
     if let Some(object) = value.as_object_mut() {
         object.insert("runtime".to_string(), runtime);
-        object.insert("event_log".to_string(), Value::String(
-            run_workspace.join(".team").join("logs").join("events.jsonl")
-                .to_string_lossy().to_string(),
-        ));
+        object.insert(
+            "event_log".to_string(),
+            Value::String(
+                run_workspace
+                    .join(".team")
+                    .join("logs")
+                    .join("events.jsonl")
+                    .to_string_lossy()
+                    .to_string(),
+            ),
+        );
     }
     finalize_doctor_report(&mut value, true);
     value
@@ -1385,7 +799,10 @@ fn merge_report_array(report: &mut Value, key: &str, incoming: &Value) {
         .expect("report array normalized before merge");
     for item in items {
         let identity = report_item_identity(item);
-        if !target.iter().any(|existing| report_item_identity(existing) == identity) {
+        if !target
+            .iter()
+            .any(|existing| report_item_identity(existing) == identity)
+        {
             target.push(item.clone());
         }
     }
@@ -1450,11 +867,17 @@ fn finalize_doctor_report(report: &mut Value, default_report: bool) {
         .and_then(|value| value.as_array().cloned())
         .unwrap_or_default();
     let mut add = |issue: Value, repair: Option<Value>| {
-        if !issues.iter().any(|existing| report_item_identity(existing) == report_item_identity(&issue)) {
+        if !issues
+            .iter()
+            .any(|existing| report_item_identity(existing) == report_item_identity(&issue))
+        {
             issues.push(issue);
         }
         if let Some(repair) = repair {
-            if !repairs.iter().any(|existing| report_item_identity(existing) == report_item_identity(&repair)) {
+            if !repairs
+                .iter()
+                .any(|existing| report_item_identity(existing) == report_item_identity(&repair))
+            {
                 repairs.push(repair);
             }
         }
@@ -1467,10 +890,10 @@ fn finalize_doctor_report(report: &mut Value, default_report: bool) {
             .or_else(|| object.get("reason").and_then(Value::as_str))
             .unwrap_or("doctor_failed");
         let issue = if status == "failed" {
-            object
-                .get("gate")
-                .and_then(Value::as_str)
-                .map_or_else(|| "doctor_failed".to_string(), |gate| format!("{gate}_failed"))
+            object.get("gate").and_then(Value::as_str).map_or_else(
+                || "doctor_failed".to_string(),
+                |gate| format!("{gate}_failed"),
+            )
         } else if status.ends_with("_failed") || status == "refused" {
             status.to_string()
         } else {
@@ -1481,7 +904,10 @@ fn finalize_doctor_report(report: &mut Value, default_report: bool) {
             .or_else(|| object.get("next_action"))
             .or_else(|| object.get("reason"))
             .cloned();
-        add(Value::String(issue), repair.map(|value| json!({"action": value})));
+        add(
+            Value::String(issue),
+            repair.map(|value| json!({"action": value})),
+        );
     }
     if object
         .get("workspace")
@@ -1512,9 +938,9 @@ fn finalize_doctor_report(report: &mut Value, default_report: bool) {
         {
             add(
                 json!("grok_slot_mismatch"),
-                grok.get("reason").cloned().map(|reason| {
-                    json!({"issue": "grok_slot_mismatch", "action": reason})
-                }),
+                grok.get("reason")
+                    .cloned()
+                    .map(|reason| json!({"issue": "grok_slot_mismatch", "action": reason})),
             );
         }
     }
@@ -1559,7 +985,9 @@ fn finalize_doctor_report(report: &mut Value, default_report: bool) {
     if runtime_status == "unresolved" {
         add(
             json!("runtime_selection_failed"),
-            Some(json!({"issue": "runtime_selection_failed", "action": "select an existing Team runtime"})),
+            Some(
+                json!({"issue": "runtime_selection_failed", "action": "select an existing Team runtime"}),
+            ),
         );
     }
     if runtime_status == "present"
@@ -1589,7 +1017,7 @@ mod tests {
     #![allow(clippy::unwrap_used)]
 
     use super::{
-        agent_pane_id, append_send_guidance, format_inbox_human, quickstart_human, send_command,
+        append_send_guidance, format_inbox_human, quickstart_human, send_command,
         split_shell_argv,
     };
     use serde_json::{json, Value};
@@ -1610,7 +1038,10 @@ mod tests {
         let output = format_inbox_human("worker", &value);
         for line in output.lines() {
             assert!(line.len() <= 160, "line is {} bytes: {line:?}", line.len());
-            assert!(!line.chars().any(char::is_control), "controls leaked: {line:?}");
+            assert!(
+                !line.chars().any(char::is_control),
+                "controls leaked: {line:?}"
+            );
         }
     }
 
@@ -1625,9 +1056,12 @@ mod tests {
             ],
         });
         let out = quickstart_human(&value);
-        assert!(out.contains("team started"), "must keep summary; got {out}");
         assert!(
-            out.contains("attach:"),
+            out.contains("队伍已启动"),
+            "must show startup summary; got {out}"
+        );
+        assert!(
+            out.contains("连接队伍："),
             "must render attach block; got {out}"
         );
         assert!(
@@ -1643,14 +1077,20 @@ mod tests {
     #[test]
     fn reminders_only_recommend_supported_result_commands() {
         let reminder = crate::cli::QUICK_START_REMINDER;
-        assert!(reminder.contains("Use team-agent status / inbox instead."));
+        assert!(reminder.contains("team-agent status"));
+        assert!(reminder.contains("team-agent inbox"));
         for text in [
             reminder,
             crate::cli::STATUS_REMINDER,
             crate::cli::SEND_REMINDER,
             &quickstart_human(&json!({"summary": "team started"})),
         ] {
-            assert!(!text.contains("collect"), "removed CLI command leaked: {text}");
+            for hidden in ["collect", "team-agent results", "team-agent wait"] {
+                assert!(
+                    !text.contains(hidden),
+                    "private/removed CLI command leaked: {text}"
+                );
+            }
         }
     }
 
@@ -1659,13 +1099,19 @@ mod tests {
         let value = json!({"summary": "quick-start complete"});
         assert_eq!(
             quickstart_human(&value),
-            format!("quick-start complete\n{}", crate::cli::QUICK_START_REMINDER)
+            format!(
+                "队伍已启动；下面是连接方式和派发任务的命令。\n{}",
+                crate::cli::QUICK_START_REMINDER
+            )
         );
-        // 空数组也只 summary。
+        // 空数组也只显示人类摘要与下一步，不凭空编造连接方式。
         let value2 = json!({"summary": "s", "attach_commands": []});
         assert_eq!(
             quickstart_human(&value2),
-            format!("s\n{}", crate::cli::QUICK_START_REMINDER)
+            format!(
+                "队伍已启动；下面是连接方式和派发任务的命令。\n{}",
+                crate::cli::QUICK_START_REMINDER
+            )
         );
     }
 
@@ -1684,7 +1130,7 @@ mod tests {
                 "team-agent",
                 "send",
                 "worker name; echo unsafe",
-                "MESSAGE",
+                "请完成任务并把答案回复给 leader。",
                 "--workspace",
                 "/tmp/my workspace",
                 "--team",
@@ -1695,11 +1141,15 @@ mod tests {
 
     #[test]
     fn send_guidance_is_copyable_and_preserves_explicit_scope() {
-        let command = send_command("worker name; echo unsafe", Path::new("/tmp/my workspace"), Some("team-a"))
-            .unwrap();
+        let command = send_command(
+            "worker name; echo unsafe",
+            Path::new("/tmp/my workspace"),
+            Some("team-a"),
+        )
+        .unwrap();
         assert_eq!(
             command,
-            "team-agent send 'worker name; echo unsafe' MESSAGE --workspace '/tmp/my workspace' --team team-a"
+            "team-agent send 'worker name; echo unsafe' '请完成任务并把答案回复给 leader。' --workspace '/tmp/my workspace' --team team-a"
         );
     }
 
@@ -1720,7 +1170,10 @@ mod tests {
     fn quick_start_guidance_lists_every_known_agent_without_guessing() {
         let mut value = json!({"ok": true, "agent_ids": ["sol", "luna"]});
         append_send_guidance(&mut value, Path::new("/tmp/ws"), Some("team"));
-        let commands = value.get("send_commands").and_then(|v| v.as_array()).unwrap();
+        let commands = value
+            .get("send_commands")
+            .and_then(|v| v.as_array())
+            .unwrap();
         assert_eq!(commands.len(), 2);
         assert!(commands[0].as_str().unwrap().contains("send sol"));
         assert!(commands[1].as_str().unwrap().contains("send luna"));
@@ -1747,53 +1200,19 @@ mod tests {
             .unwrap();
         assert!(command.contains("send worker"));
         assert!(command.contains("--team team-a"));
-        let parts: Vec<&str> = command.split_whitespace().collect();
-        assert_eq!(parts[3], "MESSAGE");
-    }
-
-    #[test]
-    fn agent_pane_id_resolves_session_window_even_with_recorded_pane_id() {
-        let state = json!({
-            "session_name": "team-x",
-            "agents": {
-                "w1": {"pane_id": "%7", "window": "w1"}
-            }
-        });
-        let agent = state
-            .get("agents")
-            .and_then(|agents| agents.get("w1"))
-            .unwrap();
-
         assert_eq!(
-            agent_pane_id(&state, "w1", agent).unwrap(),
-            (
-                "team-x".to_string(),
-                "w1".to_string(),
-                "team-x:w1".to_string()
-            )
+            split_shell_argv(command),
+            [
+                "team-agent",
+                "send",
+                "worker",
+                "请完成任务并把答案回复给 leader。",
+                "--workspace",
+                "/tmp/ws",
+                "--team",
+                "team-a",
+            ]
         );
     }
 
-    #[test]
-    fn agent_pane_id_falls_back_to_session_window_target() {
-        let state = json!({
-            "session_name": "team-x",
-            "agents": {
-                "w1": {"window": "worker-one"}
-            }
-        });
-        let agent = state
-            .get("agents")
-            .and_then(|agents| agents.get("w1"))
-            .unwrap();
-
-        assert_eq!(
-            agent_pane_id(&state, "w1", agent).unwrap(),
-            (
-                "team-x".to_string(),
-                "worker-one".to_string(),
-                "team-x:worker-one".to_string()
-            )
-        );
-    }
 }