@team-agent/installer 0.5.110 → 0.5.111

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

@@ -298,7 +298,8 @@ mod tests {
     #[cfg(unix)]
     #[test]
     fn search_survives_unrelated_spaced_model_ids() {
-        let catalog = include_str!("../lifecycle/tests/fixtures/pi_list_models_spaced_ids.stdout.txt");
+        let catalog =
+            include_str!("../lifecycle/tests/fixtures/pi_list_models_spaced_ids.stdout.txt");
         let path = fixture(&format!("printf '%s' '{catalog}'"));
         let result = cmd_models_with(
             &ModelsArgs {
@@ -370,7 +371,8 @@ mod tests {
             &["models", "--provider", "cursor_agent", "--json"],
         );
         let text = public_cli_text(&output);
-        let calls = std::fs::read_to_string(agent.program.with_extension("count")).unwrap_or_default();
+        let calls =
+            std::fs::read_to_string(agent.program.with_extension("count")).unwrap_or_default();
         drop(agent);
         assert!(output.status.success(), "{text}");
         assert_eq!(calls, "1:--list-models\n");
@@ -405,12 +407,19 @@ mod tests {
         let no_match = run_public_models_cli(
             &grok.program,
             grok.response.as_deref(),
-            &["models", "--provider", "grok", "--search", "definitely-absent"],
+            &[
+                "models",
+                "--provider",
+                "grok",
+                "--search",
+                "definitely-absent",
+            ],
         );
         let json_text = public_cli_text(&json);
         let human_text = public_cli_text(&human);
         let no_match_text = public_cli_text(&no_match);
-        let calls = std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
+        let calls =
+            std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
         drop(grok);
         assert!(json.status.success(), "{json_text}");
         assert!(human.status.success(), "{human_text}");
@@ -422,10 +431,15 @@ mod tests {
         assert_eq!(value["auth_basis"], "catalog_visibility");
         let models = value["models"].as_array().unwrap();
         assert_eq!(
-            models.iter().map(|model| model["model_id"].as_str().unwrap()).collect::<Vec<_>>(),
+            models
+                .iter()
+                .map(|model| model["model_id"].as_str().unwrap())
+                .collect::<Vec<_>>(),
             vec!["grok-4.7", "grok-4.7-build-fast", "grok-4.5", "grok-4.6"]
         );
-        assert!(models.iter().all(|model| model["provider"] == "grok" && model["vendor"] == "xai" && model["aliases"] == json!([])));
+        assert!(models.iter().all(|model| model["provider"] == "grok"
+            && model["vendor"] == "xai"
+            && model["aliases"] == json!([])));
         assert_eq!(models[0]["default"], false);
         assert_eq!(models[3]["default"], true);
         assert!(human_text.contains("grok-4.7-build-fast"));
@@ -471,7 +485,8 @@ mod tests {
                 &["models", "--provider", "grok", "--json"],
             );
             let text = public_cli_text(&output);
-            let calls = std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
+            let calls =
+                std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
             outcomes.push((name, output.status.success(), text, calls));
         }
         for (name, success, text, calls) in outcomes {
@@ -481,21 +496,32 @@ mod tests {
             assert_eq!(value["schema_version"], "models.v1", "{name}");
             assert_eq!(value["ok"], false, "{name}");
             assert_eq!(value["models"], json!([]), "{name}");
-            assert!(!value["error"].as_str().unwrap().to_ascii_lowercase().contains("unsupported model provider"), "{name}: {text}");
+            assert!(
+                !value["error"]
+                    .as_str()
+                    .unwrap()
+                    .to_ascii_lowercase()
+                    .contains("unsupported model provider"),
+                "{name}: {text}"
+            );
         }
     }
 
     #[cfg(unix)]
     #[test]
     fn grok_nonzero_native_command_is_not_a_successful_empty_catalog() {
-        let grok = CliFixture::new(fixture_program("grok", "printf 'private diagnostic' >&2\nexit 7"));
+        let grok = CliFixture::new(fixture_program(
+            "grok",
+            "printf 'private diagnostic' >&2\nexit 7",
+        ));
         let output = run_public_models_cli(
             &grok.program,
             None,
             &["models", "--provider", "grok", "--json"],
         );
         let text = public_cli_text(&output);
-        let calls = std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
+        let calls =
+            std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
         drop(grok);
         assert!(!output.status.success(), "{text}");
         assert_eq!(calls, "1:models\n");
@@ -503,7 +529,14 @@ mod tests {
         let value: Value = serde_json::from_str(text.trim()).unwrap();
         assert_eq!(value["ok"], false);
         assert_eq!(value["models"], json!([]));
-        assert!(value["error"].as_str().unwrap().to_ascii_lowercase().contains("grok"), "{text}");
+        assert!(
+            value["error"]
+                .as_str()
+                .unwrap()
+                .to_ascii_lowercase()
+                .contains("grok"),
+            "{text}"
+        );
     }
 
     #[cfg(unix)]
@@ -518,10 +551,20 @@ mod tests {
         let text = public_cli_text(&output);
         let value: Value = serde_json::from_str(text.trim()).unwrap();
         assert_eq!(value["ok"], false);
-        assert!(value["error"].as_str().unwrap().to_ascii_lowercase().contains("grok"), "{text}");
+        assert!(
+            value["error"]
+                .as_str()
+                .unwrap()
+                .to_ascii_lowercase()
+                .contains("grok"),
+            "{text}"
+        );
         assert!(value["action"].as_str().unwrap().contains("grok"), "{text}");
         assert!(crate::cli::emit::default_help().contains("grok"));
-        assert!(crate::cli::spec::command_spec("models").unwrap().usage.contains("grok"));
+        assert!(crate::cli::spec::command_spec("models")
+            .unwrap()
+            .usage
+            .contains("grok"));
 
         let unsupported = run_public_models_cli(
             &missing.program,
@@ -533,7 +576,13 @@ mod tests {
         drop(missing);
         assert!(!output.status.success());
         assert!(!unsupported.status.success());
-        assert!(unsupported_value["action"].as_str().unwrap().contains("grok"), "{unsupported_text}");
+        assert!(
+            unsupported_value["action"]
+                .as_str()
+                .unwrap()
+                .contains("grok"),
+            "{unsupported_text}"
+        );
     }
 
     #[cfg(unix)]
@@ -579,7 +628,10 @@ mod tests {
     #[cfg(unix)]
     impl CliFixture {
         fn new(program: std::path::PathBuf) -> Self {
-            Self { program, response: None }
+            Self {
+                program,
+                response: None,
+            }
         }
     }
 
@@ -614,7 +666,10 @@ mod tests {
                 "--nocapture",
             ])
             .env("TEAM_AGENT_MODELS_CHILD", "1")
-            .env("TEAM_AGENT_MODELS_ARGS", serde_json::to_string(args).unwrap())
+            .env(
+                "TEAM_AGENT_MODELS_ARGS",
+                serde_json::to_string(args).unwrap(),
+            )
             .env("PATH", path.parent().unwrap())
             .env_remove("PI_PROVIDER")
             .env_remove("PI_MODEL")
@@ -719,7 +774,10 @@ mod tests {
     fn with_native_mode<T>(
         mode: &str,
         action: impl FnOnce() -> T,
-    ) -> (T, crate::lifecycle::launch::pi_mcp::PiCatalogTestObservation) {
+    ) -> (
+        T,
+        crate::lifecycle::launch::pi_mcp::PiCatalogTestObservation,
+    ) {
         let receipt = native_timeout_receipt();
         assert!(!receipt.exists());
         let result = crate::lifecycle::launch::pi_mcp::with_pi_catalog_test_observation(
@@ -1122,9 +1180,8 @@ mod tests {
     fn runner_fails_closed_for_nonzero_oversize_timeout_and_unavailable() {
         let fail = native_timeout_fixture();
         let started = Instant::now();
-        let (failed_result, fail_observation) = with_native_mode("exit7", || {
-            run_catalog(&fail, Duration::from_secs(1), 1024)
-        });
+        let (failed_result, fail_observation) =
+            with_native_mode("exit7", || run_catalog(&fail, Duration::from_secs(1), 1024));
         let elapsed = started.elapsed();
         assert_eq!(
             failed_result.unwrap_err(),
@@ -1161,9 +1218,8 @@ mod tests {
         assert_eq!(failed.exit, ExitCode::Error);
         assert!(!text.contains("sensitive-token"));
         let big = native_timeout_fixture();
-        let (big_result, big_observation) = with_native_mode("oversize", || {
-            run_catalog(&big, Duration::from_secs(1), 8)
-        });
+        let (big_result, big_observation) =
+            with_native_mode("oversize", || run_catalog(&big, Duration::from_secs(1), 8));
         assert!(big_result.unwrap_err().contains("bounded output"));
         assert_eq!(big_observation.spawn_count, 1);
         assert_eq!(big_observation.argv, vec!["--list-models"]);
@@ -1217,7 +1273,7 @@ mod tests {
         );
         assert_eq!(
             crate::cli::spec::command_spec("models").unwrap().usage,
-            "usage: team-agent models [--provider pi|cursor_agent|codex|claude|claude_code|grok] [QUERY|--search TEXT] [--json]"
+            "team-agent models [--provider pi|cursor_agent|codex|claude|claude_code|grok] [QUERY|--search TEXT] [--json]"
         );
     }
 

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

@@ -71,6 +71,25 @@ pub(crate) struct NamedAddressError {
     /// `requested_name`/`suggested_name` without re-parsing. Absent
     /// for exact refusals like empty-workspace.
     pub requested_name: Option<String>,
+    // Presentation only: never serialized or used as routing authority.
+    human_scope: Option<PathBuf>,
+    human_team: Option<String>,
+}
+
+pub(crate) fn human_address_reason(reason: &str) -> Option<&'static str> {
+    Some(match reason {
+        "name_invalid" => "收信队友名不正确；请使用队友列表中的名称。",
+        "workspace_not_found" => "所选项目目录不存在；请核对项目路径。",
+        "state_not_found" | "workspace_no_state" => {
+            "所选项目还没有可用队伍；首次起队用 quick-start，已有队伍恢复用 restart。"
+        }
+        "team_key_not_found" => "所选项目没有这支队伍；请核对 --workspace 和 --team。",
+        "leader_not_attached" => "主控还没有连接到这支队伍；请先体检，按提示恢复连接。",
+        "name_not_resolvable" => "当前队伍没有这个队友；请先查看队友列表。",
+        "name_not_live" => "该队友当前未运行或连接已失效；请查看状态再恢复。",
+        "name_ambiguous" => "有多个同名对象；请明确选择项目和队伍，不猜对象。",
+        _ => return None,
+    })
 }
 
 impl NamedAddressError {
@@ -86,7 +105,77 @@ impl NamedAddressError {
             available_team_keys: Vec::new(),
             suggested_name: None,
             requested_name: None,
+            human_scope: None,
+            human_team: None,
+        }
+    }
+
+    fn with_human_scope(mut self, workspace: Option<&Path>, team: Option<&str>) -> Self {
+        self.human_scope = workspace.map(Path::to_path_buf);
+        if self.human_team.is_none() {
+            self.human_team = team.map(str::to_string);
         }
+        self
+    }
+
+    pub(crate) fn human_guidance(&self, requested: &str) -> (String, String) {
+        let workspace = self.human_scope.as_deref();
+        let mut message = format!(
+            "{}\n你刚才填写的是 {requested:?}。",
+            human_address_reason(self.kind.as_str()).unwrap_or("未能找到可用的收信队友。")
+        );
+        if let Some(workspace) = workspace {
+            message.push_str(&format!("\n所选项目：{:?}。", workspace.to_string_lossy()));
+        }
+        if let Some(team) = self.human_team.as_deref() {
+            message.push_str(&format!("\n所选队伍：{team:?}。"));
+        }
+        let mut action = "没有可靠的拼写建议；请先核对项目和队伍，不猜对象。".to_string();
+        for candidate in &self.candidates {
+            if let (Some(agent), Some(team)) = (
+                candidate.get("agent_id").and_then(Value::as_str),
+                candidate.get("team_key").and_then(Value::as_str),
+            ) {
+                message.push_str(&format!(
+                    "\n候选队伍 {team:?}，队友 {agent:?}；请确认是否是你要找的对象。"
+                ));
+            }
+        }
+        if let Some(candidate) = self.suggested_name.as_deref().and_then(|suggested| {
+            self.candidates
+                .iter()
+                .find(|candidate| candidate.get("name").and_then(Value::as_str) == Some(suggested))
+        }) {
+            if let (Some(workspace), Some(agent), Some(team)) = (
+                workspace,
+                candidate.get("agent_id").and_then(Value::as_str),
+                candidate.get("team_key").and_then(Value::as_str),
+            ) {
+                if !agent.is_empty()
+                    && !team.is_empty()
+                    && !agent
+                        .chars()
+                        .chain(team.chars())
+                        .chain(workspace.to_string_lossy().chars())
+                        .any(char::is_control)
+                {
+                    if let Some(command) =
+                        super::adapters::send_command(agent, workspace, Some(team))
+                    {
+                        action = format!("你是否想发给 {agent:?}、队伍 {team:?}？确认后将任务内容替换到这个例子；本次没有发送：\n{command}");
+                    }
+                }
+            }
+        }
+        if let Some(workspace) =
+            workspace.filter(|path| !path.to_string_lossy().chars().any(char::is_control))
+        {
+            action.push_str(&format!(
+                "\n也可查看可用队友列表：\nteam-agent status --workspace {}",
+                super::adapters::shell_quote(&workspace.to_string_lossy())
+            ));
+        }
+        (message, action)
     }
 
     pub(crate) fn n38_message(&self) -> String {
@@ -188,9 +277,7 @@ impl NamedAddressError {
                 })
             })
             .collect();
-        let best = ranked
-            .first()
-            .map(|agent_id| format!("{team}/{agent_id}"));
+        let best = ranked.first().map(|agent_id| format!("{team}/{agent_id}"));
         self.with_scoped_suggestions(requested_display, candidate_values, best)
     }
 
@@ -216,9 +303,7 @@ impl NamedAddressError {
         // returned candidate (RED-4). Falls back to a status-JSON
         // hint when no candidate cleared the threshold.
         if let Some(best) = best_copyable {
-            self.action = format!(
-                "Did you mean `{best}`? Rerun with `--to-name {best}`."
-            );
+            self.action = format!("Did you mean `{best}`? Rerun with `--to-name {best}`.");
         } else {
             self.action = format!(
                 "No close matches for `{requested}`. \
@@ -430,8 +515,14 @@ pub(crate) fn resolve_name_for_cli(
     // registry-to-E6 internal helper deliberately pass `None` so
     // caller-supplied `--team` never overrides a full address.
     let parsed = normalize_bare_with_team_scope(parsed, bare_team_scope);
-    let target_workspace = resolve_workspace(sender_workspace, parsed.workspace.as_deref())?;
-    let state = load_state_checked(&target_workspace)?;
+    let requested_team = match &parsed.target {
+        ParsedTarget::TeamEntity { team, .. } => Some(team.as_str()),
+        _ => None,
+    };
+    let target_workspace = resolve_workspace(sender_workspace, parsed.workspace.as_deref())
+        .map_err(|error| error.with_human_scope(None, requested_team))?;
+    let state = load_state_checked(&target_workspace)
+        .map_err(|error| error.with_human_scope(Some(&target_workspace), requested_team))?;
     let transport = transport_for_cli_target(&target_workspace, &state, &parsed);
     let resolved = resolve_in_workspace(
         sender_workspace,
@@ -439,7 +530,8 @@ pub(crate) fn resolve_name_for_cli(
         &state,
         &parsed,
         transport.as_ref(),
-    )?;
+    )
+    .map_err(|error| error.with_human_scope(Some(&target_workspace), requested_team))?;
     Ok((resolved, transport))
 }
 
@@ -487,8 +579,8 @@ pub(crate) fn parse_leader_target_workspace_and_team(
     match parsed.target {
         ParsedTarget::TeamEntity { team, entity } if entity == "leader" => {
             let state = load_state_checked(&target_workspace)?;
-            let canonical = canonical_named_team_key(&target_workspace, &state, &team)
-                .unwrap_or(team);
+            let canonical =
+                canonical_named_team_key(&target_workspace, &state, &team).unwrap_or(team);
             Ok(Some((target_workspace, canonical)))
         }
         _ => Ok(None),
@@ -594,7 +686,7 @@ fn resolve_in_workspace(
         ParsedTarget::TeamEntity { team, entity } => {
             let canonical = canonical_named_team_key(target_workspace, state, team)
                 .unwrap_or_else(|| team.clone());
-            if entity == "leader" {
+            let result = if entity == "leader" {
                 resolve_leader(
                     sender_workspace,
                     target_workspace,
@@ -613,7 +705,11 @@ fn resolve_in_workspace(
                     parsed,
                     transport,
                 )
-            }
+            };
+            result.map_err(|mut error| {
+                error.human_team = Some(canonical);
+                error
+            })
         }
         ParsedTarget::SessionWindow { session, window } => resolve_session_window(
             sender_workspace,
@@ -976,11 +1072,7 @@ fn resolve_leader(
     let socket = string_field(receiver, "tmux_socket")
         .map(str::to_string)
         .or_else(|| transport.tmux_endpoint());
-    match crate::messaging::resolve_live_leader_channel(
-        target_workspace,
-        receiver,
-        transport,
-    ) {
+    match crate::messaging::resolve_live_leader_channel(target_workspace, receiver, transport) {
         crate::messaging::LeaderChannelResolution::Live(
             crate::messaging::LiveLeaderChannel::DirectTmux(channel),
         ) => Ok(ResolvedNamedAddress {
@@ -1194,8 +1286,8 @@ fn transport_for_cli_target(
     parsed: &ParsedNamedAddress,
 ) -> Box<dyn Transport> {
     if let ParsedTarget::TeamEntity { team, entity } = &parsed.target {
-        let canonical = canonical_named_team_key(target_workspace, state, team)
-            .unwrap_or_else(|| team.clone());
+        let canonical =
+            canonical_named_team_key(target_workspace, state, team).unwrap_or_else(|| team.clone());
         if entity == "leader" {
             let team_scoped_socket = team_entry(state, &canonical)
                 .and_then(|entry| entry.get("leader_receiver"))
@@ -1302,11 +1394,8 @@ fn canonical_named_team_key(
     if team_entry(state, requested).is_some() || is_legacy_single_team_active(state, requested) {
         return Some(requested.to_string());
     }
-    let selected = crate::state::projection::select_runtime_state(
-        target_workspace,
-        Some(requested),
-    )
-    .ok()?;
+    let selected =
+        crate::state::projection::select_runtime_state(target_workspace, Some(requested)).ok()?;
     let canonical = selected
         .get("active_team_key")
         .and_then(Value::as_str)

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

@@ -5,7 +5,7 @@ use crate::provider::argv_route::{self, Config, Mutation, Override, RouteError};
 use crate::provider::Provider;
 use serde_json::{json, Value};
 
-pub(crate) const HELP: &str = "usage: team-agent route [status] [--json]\n       team-agent route enable|disable [--json]\n       team-agent route show [PROVIDER] [--json]\n       team-agent route set|add PROVIDER [--json] -- ARG [ARG ...]\n       team-agent route clear PROVIDER [--json]\n\nGlobal config: ~/.team-agent/argv-routing.json (default OFF).\nTEAM_AGENT_CLI_ARGV_ROUTING overrides the persisted switch.\nEverything after -- is literal argv data; routing affects the next native Agent launch only.";
+pub(crate) const HELP: &str = "做什么：\n设置工具启动时额外使用的命令行参数，默认关闭。\n用法：team-agent route [status|enable|disable|show [TOOL]|set TOOL -- ARG...|add TOOL -- ARG...|clear TOOL] [--json]\n\n怎么用：\nstatus 看开关；enable 开启；disable 关闭；show 看全部或指定工具的参数。\nset 替换参数；add 追加参数；clear 清除指定工具的参数；--json 给程序读取。\nTOOL 是已支持的工具名称，如 pi/codex/claude/copilot/grok/cursor_agent。\n第一个 -- 后全是工具的字面参数，包含 --help/--json 也不会被这里解析。\n配置保存在 ~/.team-agent/argv-routing.json；影响全机，不按项目或队伍隔离。\nTEAM_AGENT_CLI_ARGV_ROUTING 环境变量优先于保存的开关。\nExamples（可复制）：\nteam-agent route status\nteam-agent route set pi -- --mode text\nteam-agent route enable\n\n下一步（Next Action）：\n用 route show pi 核对参数；仅影响下一次启动，不改变正在运行的对话。\n没有开启或没有配置时，工具仍按原参数启动；不了解参数用途时保持关闭。";
 
 struct Request {
     operation: String,
@@ -16,10 +16,9 @@ struct Request {
 
 fn usage() -> RouteError {
     RouteError {
-        error: "invalid route arguments".to_string(),
+        error: "参数不完整或不正确；set/add 需要工具名、-- 和至少一个工具参数".to_string(),
         reason: "argv_route_usage",
-        action: "run `team-agent route --help`; set/add require PROVIDER -- ARG [ARG ...]"
-            .to_string(),
+        action: "请按 team-agent route --help 的 Examples 填写；例如 team-agent route set pi -- --mode text".to_string(),
         config_path: None,
     }
 }
@@ -119,7 +118,7 @@ fn execute(request: &Request) -> Result<Value, RouteError> {
     }
     if override_state != Override::Unset {
         value["notice"] = json!(format!(
-            "effective switch is overridden by {} ({})",
+            "当前开关由环境变量 {} 决定（{}）",
             argv_route::ENV_NAME,
             override_state.status()
         ));
@@ -168,6 +167,9 @@ fn emit_error(error: RouteError, args: &[String], delimiter: usize, as_json: boo
             .map(String::as_str)
             .unwrap_or("status"));
     }
+    if is_usage {
+        value["next_actions"] = json!(["team-agent route --help"]);
+    }
     if let Some(text) = super::emit(&CmdOutput::Json(value), as_json) {
         if as_json {
             println!("{text}");
@@ -176,6 +178,9 @@ fn emit_error(error: RouteError, args: &[String], delimiter: usize, as_json: boo
         }
     }
     if is_usage {
+        if !as_json {
+            eprintln!("\n{HELP}");
+        }
         ExitCode::Usage
     } else {
         ExitCode::Error

package/crates/team-agent/src/cli/send/presentation.rs

@@ -20,7 +20,7 @@ pub(super) fn watch_notice_json(target: &MessageTarget, opts: &SendOptions) -> V
         "watcher_id": format!("watch-{agent_id}"),
         "task_id": opts.task_id.as_ref().map(|t| t.as_str().to_string()),
         "agent_id": agent_id,
-        "notice": "Team Agent will collect the result and notify the leader when this task reports completion."
+        "notice": "队友回复后会通知主控；用 team-agent inbox leader -n 3 查看。"
     })
 }
 
@@ -183,39 +183,56 @@ pub(super) fn cmd_send_result(value: Value, as_json: bool) -> CmdResult {
 }
 
 pub(super) fn send_human_output(value: &Value) -> String {
-    let mut parts = vec![
-        send_human_field(value, "ok"),
-        format!("status: {}", send_human_status(value)),
-        send_human_field(value, "message_id"),
-        format!("target: {}", send_human_target(value)),
-    ];
-    for key in ["verification", "stage", "reason", "channel", "turn_verification"] {
-        if !value.get(key).is_none_or(Value::is_null) {
-            parts.push(send_human_field(value, key));
+    let agent = send_human_target(value);
+    if value.get("ok").and_then(Value::as_bool) == Some(false) {
+        let reason = value.get("reason").and_then(Value::as_str).unwrap_or("");
+        let explanation =
+            crate::cli::named_address::human_address_reason(reason).unwrap_or(match reason {
+                "target_not_in_team" | "unknown_recipient" => "当前队伍没有这个队友。",
+                "missing_permissions" | "human_confirmation_required" => {
+                    "发送被拒绝：需要先确认交流权限。"
+                }
+                "recipient_busy" | "recipient_pane_in_non_input_mode" => {
+                    "队友当前不能接收任务；请先查看其状态。"
+                }
+                "routing_ambiguous" | "empty_target_list" | "ambiguous" => {
+                    "没有明确选定收信队友；请填写队友名和任务内容。"
+                }
+                "team_owner_mismatch" | "PaneWorkspaceMismatch" | "session_drift" => {
+                    "队伍或终端归属不匹配；已停止发送。"
+                }
+                "coordinator_unavailable" | "tmux_target_missing" => {
+                    "队伍连接暂不可用；本次没有确认送达。"
+                }
+                "message_already_claimed" | "duplicate" => {
+                    "这条消息已由其他发送处理接收；不要重复发送。"
+                }
+                "no_caller_pane" => "当前终端没有可用的队伍连接；请在主控的命令行/工具上下文发送。",
+                _ => value
+                    .get("error")
+                    .and_then(Value::as_str)
+                    .unwrap_or("发送未成功；没有确认任务已送达。"),
+            });
+        let mut out = format!("{explanation}\n下一步：先运行 team-agent status，使用列表中的队友名；连接问题用 team-agent doctor --workspace .。不要反复重发。");
+        if let Some(suggested) = value
+            .get("suggested_name")
+            .and_then(Value::as_str)
+            .filter(|name| !name.is_empty() && !name.contains(['/', ':', ',', '\n', '\r']))
+        {
+            out.push_str(&format!(
+                "\n你是否想发给 {suggested}？确认后使用这个队友名。"
+            ));
         }
+        return out;
     }
-    // 0.5.45 naming-addressing (design §3.4/§3.5, RED-3 positional):
-    // when the refusal envelope carries a scope-safe suggestion,
-    // surface it verbatim in human output so users can copy the
-    // right short id. `requested_name` echoes the typo, `suggested_
-    // name` is the copyable canonical.
-    if let Some(requested) = value
-        .get("requested_name")
-        .and_then(Value::as_str)
-        .filter(|s| !s.is_empty())
-    {
-        parts.push(format!("requested_name: {requested}"));
+    if value.get("status").and_then(Value::as_str) == Some("stored_only") {
+        return format!("已给{agent}留下消息；本次没有发送到当前对话。\n下一步：用 team-agent inbox leader -n 3 查看回复；留言不保证自动执行。");
     }
-    if let Some(suggested) = value
-        .get("suggested_name")
-        .and_then(Value::as_str)
-        .filter(|s| !s.is_empty())
-    {
-        parts.push(format!(
-            "Did you mean `{suggested}`? suggested_name: {suggested}"
-        ));
+    if value.get("delivered").and_then(Value::as_bool) == Some(true) {
+        format!("已发给{agent}。{}", crate::cli::SEND_REMINDER)
+    } else {
+        "任务已收下，但还未送到队友的对话。\n下一步：查看 team-agent status 或 team-agent doctor --workspace .，等真实回复，不反复重发。".to_string()
     }
-    parts.join(" ")
 }
 
 pub(super) fn send_human_field(value: &Value, key: &str) -> String {
@@ -227,11 +244,14 @@ pub(super) fn send_human_field(value: &Value, key: &str) -> String {
 }
 
 pub(super) fn send_human_target(value: &Value) -> String {
-    ["target", "agent_id", "pane_id", "to_name"]
-        .iter()
-        .find_map(|key| value.get(*key).filter(|v| !v.is_null()))
-        .map(send_human_value)
-        .unwrap_or_else(|| "None".to_string())
+    value
+        .get("agent_id")
+        .and_then(Value::as_str)
+        .filter(|name| {
+            !name.is_empty() && *name != "*" && !name.contains(['/', ':', ',', '\n', '\r'])
+        })
+        .map(str::to_string)
+        .unwrap_or_else(|| "该队友".to_string())
 }
 
 pub(super) fn send_human_status(value: &Value) -> String {
@@ -265,13 +285,12 @@ pub(super) fn send_reminder_for_value(value: &Value) -> &'static str {
     let delivered = value.get("delivered").and_then(Value::as_bool);
     let status = value.get("status").and_then(Value::as_str);
     let delivery_status = value.get("delivery_status").and_then(Value::as_str);
-    if delivered == Some(false)
-        || matches!(status, Some("queued"))
-        || matches!(delivery_status, Some("pending"))
-    {
-        "Message queued; coordinator will notify when the worker receives it. Do not poll the worker terminal with capture-pane."
-    } else {
+    if status == Some("stored_only") {
+        "本次只留言，没有发送到当前对话；留言不保证自动执行。"
+    } else if delivered == Some(true) && delivery_status != Some("pending") {
         crate::cli::SEND_REMINDER
+    } else {
+        "任务已收下，但还未确认送到队友对话。查看 team-agent status/doctor，等真实回复，不反复重发。"
     }
 }