boss-agent-cli 2.0.0__tar.gz → 2.0.1__tar.gz

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-09-29
+
+### Fixed
+- `boss chat` 现在公开跨请求稳定的联系人 `uid`，`chatmsg` / `chat-summary` / `mark` / `exchange` 优先按 `uid` 重新解析联系人并使用本次沟通列表返回的动态 `securityId`；沟通快照、diff 与导出映射同步改用 `uid` 主键，避免轮换令牌导致联系人查找必然失败和快照重复。既有 `security_id` 参数名与无 `uid` 的旧快照仍兼容，但旧令牌仅作兜底且可能已经失效。
+
 ## [2.0.0] - 2026-09-15
 
 ### Changed（含 Breaking Change）

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: boss-agent-cli
-Version: 2.0.0
+Version: 2.0.1
 Summary: AI Agent 专用的 BOSS 直聘求职 CLI 工具
 Project-URL: Homepage, https://github.com/can4hou6joeng4/boss-agent-cli
 Project-URL: Repository, https://github.com/can4hou6joeng4/boss-agent-cli

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/docs/capability-matrix.en.md

@@ -43,8 +43,8 @@ Compatibility modes `assisted` and `research` can both call every implemented ca
 | Capability | CLI command | Login required | Transport |
 |---|---|---|---|
 | Conversation list | `boss chat` | Yes | Existing-browser read session when Bridge is connected; otherwise httpx with stored credentials |
-| Message history | `boss chatmsg [--raw]` | Yes | Existing-browser read session when Bridge is connected; otherwise httpx with stored credentials; `--raw` preserves structured body/link/job-card fields |
-| Conversation summary | `boss chat-summary` | Yes | Platform adapter + local processing |
+| Message history | `boss chatmsg [--raw]` | Yes | Prefer the stable `uid` returned by `boss chat`; use the existing-browser read session when Bridge is connected, otherwise httpx with stored credentials; `--raw` preserves structured body/link/job-card fields |
+| Conversation summary | `boss chat-summary` | Yes | Prefer the stable `uid`; platform adapter + local processing |
 | Contact labels | `boss mark` | Yes | Platform adapter |
 | Contact exchange | `boss exchange` | Yes | Platform adapter |
 | Interview invites | `boss interviews` | Yes | httpx |

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/docs/capability-matrix.md

@@ -43,8 +43,8 @@
 | 能力 | CLI 命令 | 需要登录 | 通道 |
 |---|---|---|---|
 | 沟通列表 | `boss chat` | 是 | Bridge 已连接时复用现有浏览器只读会话；否则使用本地凭据的 httpx |
-| 聊天消息 | `boss chatmsg [--raw]` | 是 | Bridge 已连接时复用现有浏览器只读会话；否则使用本地凭据的 httpx；`--raw` 保留结构化 body/链接/职位卡片字段 |
-| 聊天摘要 | `boss chat-summary` | 是 | 平台适配器 + 本地处理 |
+| 聊天消息 | `boss chatmsg [--raw]` | 是 | 优先接受 `boss chat` 输出的稳定 `uid`；Bridge 已连接时复用现有浏览器只读会话，否则使用本地凭据的 httpx；`--raw` 保留结构化 body/链接/职位卡片字段 |
+| 聊天摘要 | `boss chat-summary` | 是 | 优先接受稳定 `uid`；平台适配器 + 本地处理 |
 | 联系人标签 | `boss mark` | 是 | 平台适配器 |
 | 交换联系方式 | `boss exchange` | 是 | 平台适配器 |
 | 面试邀请 | `boss interviews` | 是 | httpx |

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/docs/commands.en.md

@@ -105,16 +105,16 @@ After every page, `<data-dir>/crawl/runs/<run_id>/jobs.json`, `jobs.csv`, and a
 | `boss greet <sid> <jid>` | Greet a recruiter; duplicates return `ALREADY_GREETED` |
 | `boss batch-greet <query>` | Search and greet up to an explicit `--limit`; supports `--dry-run`; on `ACCOUNT_RISK` / `ENVIRONMENT_RISK` the batch stops immediately with `ok:false`, and already-greeted items are returned in `error.details.greeted` |
 | `boss apply <sid> <jid>` | Apply or start a conversation; duplicates return `ALREADY_APPLIED` |
-| `boss exchange <sid>` | Request a phone-number or WeChat exchange |
+| `boss exchange <uid-or-sid>` | Request a phone-number or WeChat exchange; prefer the stable `uid` returned by `boss chat` |
 
 ## Conversation track
 
 | Command | Description |
 |---------|-------------|
 | `boss chat` | List conversations with pagination and source filters |
-| `boss chatmsg <sid> [--raw]` | Read message history; `--raw` preserves structured body/link/card fields |
-| `boss chat-summary <sid>` | Build a structured conversation summary |
-| `boss mark <sid> --label X` | Add or remove a contact label |
+| `boss chatmsg <uid-or-sid> [--raw]` | Read message history; prefer the stable `uid` returned by `boss chat`; `--raw` preserves structured body/link/card fields |
+| `boss chat-summary <uid-or-sid>` | Build a structured conversation summary; prefer the stable `uid` |
+| `boss mark <uid-or-sid> --label X` | Add or remove a contact label; prefer the stable `uid` |
 | `boss interviews` | Interview invitations |
 | `boss history` | Browsing history |
 

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/docs/commands.md

@@ -101,16 +101,16 @@ boss crawl stop <run_id>
 | `boss greet <sid> <jid>` | 向指定招聘者打招呼；重复记录返回 `ALREADY_GREETED` |
 | `boss batch-greet <query>` | 搜索后按显式 `--limit` 批量打招呼，支持 `--dry-run`；命中 `ACCOUNT_RISK` / `ENVIRONMENT_RISK` 立即停批并返回 `ok:false`，已成功项随 `error.details.greeted` 带回 |
 | `boss apply <sid> <jid>` | 发起投递或立即沟通；重复记录返回 `ALREADY_APPLIED` |
-| `boss exchange <sid>` | 请求交换手机号或微信 |
+| `boss exchange <uid-or-sid>` | 请求交换手机号或微信；优先使用 `boss chat` 输出的稳定 `uid` |
 
 ## 沟通跟进
 
 | 命令 | 说明 |
 |------|------|
 | `boss chat` | 查看沟通列表，支持分页和来源筛选 |
-| `boss chatmsg <sid> [--raw]` | 查看聊天历史；`--raw` 保留结构化 body、链接和职位卡片字段 |
-| `boss chat-summary <sid>` | 基于聊天历史生成结构化摘要 |
-| `boss mark <sid> --label X` | 添加或移除联系人标签 |
+| `boss chatmsg <uid-or-sid> [--raw]` | 查看聊天历史；优先使用 `boss chat` 输出的稳定 `uid`，`--raw` 保留结构化 body、链接和职位卡片字段 |
+| `boss chat-summary <uid-or-sid>` | 基于聊天历史生成结构化摘要；优先使用稳定 `uid` |
+| `boss mark <uid-or-sid> --label X` | 添加或移除联系人标签；优先使用稳定 `uid` |
 | `boss interviews` | 面试邀请 |
 | `boss history` | 浏览历史 |
 

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "boss-agent-cli"
-version = "2.0.0"
+version = "2.0.1"
 description = "AI Agent 专用的 BOSS 直聘求职 CLI 工具"
 readme = "README.md"
 requires-python = ">=3.10"

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/__init__.py

@@ -28,7 +28,7 @@ if TYPE_CHECKING:
 	)
 	from boss_agent_cli.resume.models import ResumeData, ResumeFile
 
-__version__ = "2.0.0"
+__version__ = "2.0.1"
 
 _LAZY_EXPORT_MODULES = {
 	"AuthManager": "boss_agent_cli.auth.manager",

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/ai_cmd.py

@@ -501,7 +501,7 @@ def ai_reply_cmd(ctx: click.Context, recruiter_message: str, context: str, resum
 		render=lambda d: render_ai_result(d, title="ai-reply"),
 		hints={"next_actions": [
 			"复制草稿到 BOSS 聊天框发送",
-			"boss chatmsg <security_id> 查看完整聊天历史",
+			"boss chatmsg <uid> 查看完整聊天历史（uid 见 boss chat 输出）",
 		]},
 	)
 

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/chat.py

@@ -99,6 +99,9 @@ def chat_cmd(ctx: click.Context, page: int, from_who: str | None, days: int | No
 				"last_time": last_time_str,
 				"last_ts": last_ts,
 				"msg_status": msg_status_label,
+				# uid 是跨请求稳定的联系人标识，chatmsg/chat-summary/mark/exchange
+				# 都应优先使用它；security_id 是每请求轮换的令牌，仅作参考。
+				"uid": item.get("uid") or "",
 				"security_id": item.get("securityId") or "",
 				"encrypt_job_id": item.get("encryptJobId") or "",
 				"unread": item.get("unreadMsgCount") or 0,
@@ -156,7 +159,7 @@ def chat_cmd(ctx: click.Context, page: int, from_who: str | None, days: int | No
 				),
 					hints={"next_actions": [
 						"boss detail <security_id> — 查看职位详情",
-						"boss chatmsg <security_id> — 查看消息后继续沟通",
+						"boss chatmsg <uid> — 查看消息后继续沟通（uid 见上方输出）",
 				]},
 			)
 			return
@@ -179,6 +182,7 @@ def chat_cmd(ctx: click.Context, page: int, from_who: str | None, days: int | No
 					("Boss", "name", "bold cyan"),
 					("职称", "title", "dim"),
 					("公司", "brand_name", "green"),
+					("uid", "uid", "dim"),
 					("发起方", "initiated_by", "magenta"),
 					("未读", "unread", "red"),
 					("已读", "msg_status", "dim"),
@@ -192,7 +196,7 @@ def chat_cmd(ctx: click.Context, page: int, from_who: str | None, days: int | No
 			render=_render,
 				hints={"next_actions": [
 					"boss detail <security_id> — 查看职位详情",
-					"boss chatmsg <security_id> — 查看消息后继续沟通",
+					"boss chatmsg <uid> — 查看消息后继续沟通（uid 见上方输出）",
 			]},
 		)
 

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/chat_export.py

@@ -7,7 +7,7 @@ import io
 import json
 from typing import Any
 
-from boss_agent_cli.commands.chat_utils import sanitize_csv_cell, escape_md_cell, GROUP_ORDER
+from boss_agent_cli.commands.chat_utils import sanitize_csv_cell, escape_md_cell, contact_identity, GROUP_ORDER
 
 
 def prepare_render_data(
@@ -32,7 +32,7 @@ def prepare_render_data(
 	me_read = sum(1 for x in me_items if x.get("msg_status") == "已读")
 	me_unread = len(me_items) - me_read
 
-	added_ids = {item.get("security_id") for item in diff_result.get("added", [])}
+	added_ids = {contact_identity(item) for item in diff_result.get("added", [])}
 
 	# diff 摘要
 	diff_summary = None
@@ -82,12 +82,13 @@ def prepare_render_data(
 		for item in group_items:
 			global_idx += 1
 			sid = item.get("security_id", "")
-			is_new = sid in added_ids
+			key = contact_identity(item)
+			is_new = key in added_ids
 			ref = f"S{global_idx}"
 			msg = str(item.get("last_msg") or "-")
 			unread = item.get("unread") or 0
 			rows.append({
-				"ref": ref, "is_new": is_new, "sid": sid,
+				"ref": ref, "is_new": is_new, "sid": sid, "key": key,
 				"brand_name": item.get("brand_name") or "-",
 				"name": item.get("name") or "-",
 				"title": item.get("title") or "-",
@@ -96,7 +97,7 @@ def prepare_render_data(
 				"msg_status": item.get("msg_status") or "-",
 				"last_msg": msg,
 			})
-			id_map.append((ref, sid, f"{item.get('brand_name') or '-'} {item.get('name') or '-'}"))
+			id_map.append((ref, key, f"{item.get('brand_name') or '-'} {item.get('name') or '-'}"))
 
 		sections.append({"subtitle": subtitle, "rows": rows})
 
@@ -135,7 +136,7 @@ def _render_csv(friends: list[dict[str, Any]]) -> str:
 	fields = [
 		"name", "title", "brand_name", "initiated_by",
 		"msg_status", "unread", "last_msg", "last_time",
-		"security_id", "encrypt_job_id",
+		"uid", "security_id", "encrypt_job_id",
 	]
 	buf = io.StringIO(newline="")
 	writer = csv.DictWriter(buf, fieldnames=fields, extrasaction="ignore")
@@ -205,15 +206,16 @@ def _render_markdown(
 
 	if rd["id_map"]:
 		lines.append("<details>")
-		lines.append("<summary>security_id 映射表（点击展开）</summary>")
+		lines.append("<summary>联系人标识映射表（点击展开）</summary>")
 		lines.append("")
-		lines.append("| 编号 | 公司/联系人 | security_id |")
-		lines.append("|------|------------|-------------|")
-		for ref, sid, label in rd["id_map"]:
-			lines.append(f"| {ref} | {label} | {sid} |")
+		lines.append("| 编号 | 公司/联系人 | 联系人标识（uid 优先） |")
+		lines.append("|------|------------|--------------------------|")
+		for ref, key, label in rd["id_map"]:
+			lines.append(f"| {ref} | {label} | {key} |")
 		lines.append("")
 		lines.append("</details>")
 		lines.append("")
+		lines.append("> 优先使用 uid 调用 `boss chatmsg <uid>`；缺少 uid 的旧记录会回退展示可能已失效的 security_id。")
 
 	return "\n".join(lines) + "\n"
 
@@ -224,7 +226,7 @@ def _render_html(
 	days: int | None,
 	diff_result: dict[str, Any],
 ) -> str:
-	"""渲染为 HTML 格式，含分组、diff 标记和 security_id 映射。"""
+	"""渲染为 HTML 格式，含分组、diff 标记和联系人标识映射。"""
 	esc = _html.escape
 	rd = prepare_render_data(friends, from_who, diff_result)
 
@@ -284,17 +286,18 @@ def _render_html(
 			<tbody>{''.join(rrows)}</tbody>
 		</table>"""
 
-	# security_id 映射表
+	# 联系人标识映射表
 	map_rows = []
-	for ref, sid, label in rd["id_map"]:
-		map_rows.append(f"<tr><td>{ref}</td><td>{esc(label)}</td><td class='sid'>{esc(sid)}</td></tr>")
+	for ref, key, label in rd["id_map"]:
+		map_rows.append(f"<tr><td>{ref}</td><td>{esc(label)}</td><td class='sid'>{esc(key)}</td></tr>")
 	map_html = f"""
 	<details>
-		<summary>security_id 映射表（点击展开）</summary>
+		<summary>联系人标识映射表（点击展开）</summary>
 		<table>
-			<thead><tr><th>编号</th><th>公司/联系人</th><th>security_id</th></tr></thead>
+			<thead><tr><th>编号</th><th>公司/联系人</th><th>联系人标识（uid 优先）</th></tr></thead>
 			<tbody>{''.join(map_rows)}</tbody>
 		</table>
+		<p>优先使用 uid；缺少 uid 的旧记录会回退展示可能已失效的 security_id。</p>
 	</details>""" if map_rows else ""
 
 	return f"""<!DOCTYPE html>

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/chat_snapshot.py

@@ -5,13 +5,14 @@ import json
 import os
 from typing import Any
 
+from boss_agent_cli.commands.chat_utils import contact_identity
 from boss_agent_cli.output import Logger
 
 
 def save_snapshot_and_diff(
 	snapshot_dir: str, friends: list[dict[str, Any]], logger: Logger
 ) -> dict[str, Any]:
-	"""保存当日 JSON 快照（按 security_id 合并）并与上次对比。"""
+	"""保存当日 JSON 快照（uid 优先，旧数据回退 security_id）并与上次对比。"""
 	os.makedirs(snapshot_dir, exist_ok=True)
 	today = datetime.date.today().isoformat()
 	snapshot_path = os.path.join(snapshot_dir, f"{today}.json")
@@ -24,16 +25,16 @@ def save_snapshot_and_diff(
 				prev_today = json.load(f)
 			if isinstance(prev_today, list):
 				for item in prev_today:
-					if isinstance(item, dict) and item.get("security_id"):
-						existing[item["security_id"]] = item
+					if isinstance(item, dict) and contact_identity(item):
+						existing[contact_identity(item)] = item
 		except (json.JSONDecodeError, OSError):
 			pass
 
 	# 用当前数据更新（新数据优先）
 	for item in friends:
-		sid = item.get("security_id")
-		if sid:
-			existing[sid] = item
+		key = contact_identity(item)
+		if key:
+			existing[key] = item
 
 	merged = list(existing.values())
 
@@ -50,22 +51,22 @@ def save_snapshot_and_diff(
 	if prev_friends is None:
 		return {"is_first": True, "added": [], "removed": [], "new_unread": []}
 
-	# 用 security_id 做 key 对比
-	curr_map = {item["security_id"]: item for item in merged if item.get("security_id")}
-	prev_map = {item["security_id"]: item for item in prev_friends if item.get("security_id")}
+	# 用稳定标识（uid 优先）做 key 对比
+	curr_map = {contact_identity(item): item for item in merged if contact_identity(item)}
+	prev_map = {contact_identity(item): item for item in prev_friends if contact_identity(item)}
 	curr_ids = set(curr_map)
 	prev_ids = set(prev_map)
 
-	added = [curr_map[sid] for sid in (curr_ids - prev_ids)]
-	removed = [prev_map[sid] for sid in (prev_ids - curr_ids)]
+	added = [curr_map[key] for key in (curr_ids - prev_ids)]
+	removed = [prev_map[key] for key in (prev_ids - curr_ids)]
 
 	# 新增未读：检测任何未读增量
 	new_unread = []
-	for sid in (curr_ids & prev_ids):
-		prev_unread = prev_map[sid].get("unread", 0) or 0
-		curr_unread = curr_map[sid].get("unread", 0) or 0
+	for key in (curr_ids & prev_ids):
+		prev_unread = prev_map[key].get("unread", 0) or 0
+		curr_unread = curr_map[key].get("unread", 0) or 0
 		if curr_unread > prev_unread:
-			new_unread.append(curr_map[sid])
+			new_unread.append(curr_map[key])
 
 	return {
 		"is_first": False,

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/chat_summary.py

@@ -4,12 +4,12 @@ from boss_agent_cli.auth.manager import AuthManager
 from boss_agent_cli.chat_summary import summarize_messages
 from boss_agent_cli.compliance import require_compliance_allowed
 from boss_agent_cli.commands._platform import get_platform_instance
-from boss_agent_cli.commands.contact_lookup import resolve_friend_or_emit
+from boss_agent_cli.commands.contact_lookup import current_friend_security_id_or_emit, resolve_friend_or_emit
 from boss_agent_cli.display import boss_command_for_ctx, handle_auth_errors, handle_not_supported, handle_output, handle_platform_error_output, render_message_panel
 
 
 @click.command("chat-summary")
-@click.argument("security_id")
+@click.argument("security_id", metavar="UID_OR_SECURITY_ID")
 @click.option("--page", default=1, help="页码")
 @click.option("--count", default=20, help="每页消息数量")
 @click.pass_context
@@ -28,9 +28,13 @@ def chat_summary_cmd(ctx: click.Context, security_id: str, page: int, count: int
 			return
 		gid = str(friend_item.get("uid", ""))
 		friend_name = friend_item.get("name") or "-"
+		# securityId 是每请求轮换的令牌，必须用本次 friend_list 返回的新值。
+		fresh_security_id = current_friend_security_id_or_emit(ctx, "chat-summary", friend_item)
+		if fresh_security_id is None:
+			return
 
 		try:
-			resp = platform.chat_history(gid, security_id, page=page, count=count)
+			resp = platform.chat_history(gid, fresh_security_id, page=page, count=count)
 		except NotImplementedError as exc:
 			handle_not_supported(ctx, "chat-summary", exc, fallback_message="当前平台不支持聊天记录能力")
 			return
@@ -45,7 +49,8 @@ def chat_summary_cmd(ctx: click.Context, security_id: str, page: int, count: int
 		ctx,
 		"chat-summary",
 		{
-			"security_id": security_id,
+			"uid": gid,
+			"security_id": fresh_security_id,
 			"name": friend_name,
 			**summary,
 		},
@@ -53,7 +58,7 @@ def chat_summary_cmd(ctx: click.Context, security_id: str, page: int, count: int
 		hints={
 			"next_actions": [
 				boss_command_for_ctx(ctx, "chat"),
-				boss_command_for_ctx(ctx, f"chatmsg {security_id}"),
+				boss_command_for_ctx(ctx, f"chatmsg {gid}"),
 			]
 		},
 	)

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/chat_utils.py

@@ -1,5 +1,7 @@
 """Chat 共享常量和安全工具函数。"""
 
+from typing import Any
+
 # relationType 映射：API 返回值 → 可读标签（key 类型放宽为 object，兼容 API 返回 None/未知值走 default）
 RELATION_LABELS: dict[object, str] = {1: "对方主动", 2: "我主动", 3: "投递"}
 FROM_FILTER = {"boss": 1, "me": 2}
@@ -9,6 +11,20 @@ MSG_STATUS_LABELS = {1: "未读", 2: "已读"}
 GROUP_ORDER = ["对方主动", "我主动", "投递"]
 
 
+def contact_identity(item: dict[str, Any]) -> str:
+	"""返回联系人的稳定标识：优先 ``uid``，缺失时回退 ``security_id``。
+
+	``security_id`` 是 BOSS 每次请求轮换的加密令牌，同一个联系人在两次请求中
+	会拿到不同的值。因此凡是需要「跨请求比较同一个联系人」的场景
+	（快照合并、diff、映射表）都必须以 ``uid`` 为主键，
+	仅对缺少 uid 的历史快照数据回退到 ``security_id``。
+	"""
+	uid = item.get("uid")
+	if uid not in (None, ""):
+		return str(uid)
+	return str(item.get("security_id") or "")
+
+
 def sanitize_csv_cell(value: str) -> str:
 	"""防止 CSV 公式注入：以 =+@- 开头的值前置单引号；过滤 Tab 和回车。"""
 	if not isinstance(value, str):

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/chatmsg.py

@@ -6,7 +6,7 @@ import click
 
 from boss_agent_cli.auth.manager import AuthManager
 from boss_agent_cli.compliance import require_compliance_allowed
-from boss_agent_cli.commands.contact_lookup import resolve_friend_or_emit
+from boss_agent_cli.commands.contact_lookup import current_friend_security_id_or_emit, resolve_friend_or_emit
 from boss_agent_cli.commands._platform import get_platform_instance
 from boss_agent_cli.display import boss_command_for_ctx, handle_auth_errors, handle_not_supported, handle_output, handle_platform_error_output, render_simple_list
 
@@ -17,14 +17,17 @@ _MSG_TYPE_MAP = {
 
 
 @click.command("chatmsg")
-@click.argument("security_id")
+@click.argument("security_id", metavar="UID_OR_SECURITY_ID")
 @click.option("--page", default=1, help="页码")
 @click.option("--count", default=20, help="每页消息数量")
 @click.option("--raw", "show_raw", is_flag=True, default=False, help="输出保真结构化消息字段")
 @click.pass_context
 @handle_auth_errors("chatmsg")
 def chatmsg_cmd(ctx: click.Context, security_id: str, page: int, count: int, show_raw: bool) -> None:
-	"""查看与指定好友的聊天消息历史"""
+	"""查看与指定好友的聊天消息历史
+
+	SECURITY_ID 可传 boss chat 输出的 uid（推荐，跨请求稳定）或 security_id。
+	"""
 	if not require_compliance_allowed(ctx, "chatmsg"):
 		ctx.exit(1)
 
@@ -38,15 +41,23 @@ def chatmsg_cmd(ctx: click.Context, security_id: str, page: int, count: int, sho
 			"chatmsg",
 			platform,
 			security_id,
-			not_found_message=f"未在沟通列表中找到 security_id={security_id}，请确认该联系人存在",
+			not_found_message=(
+				f"未在沟通列表中找到联系人 {security_id}，请确认该联系人存在"
+				"（可用 boss chat 输出的 uid 或 security_id）"
+			),
 		)
 		if friend_item is None:
 			return
 		gid = str(friend_item.get("uid", ""))
 		friend_name = friend_item.get("name") or "-"
+		# securityId 是每请求轮换的令牌，必须用本次 friend_list 返回的新值，
+		# 否则会拿一个已失效的令牌去请求消息历史。
+		fresh_security_id = current_friend_security_id_or_emit(ctx, "chatmsg", friend_item)
+		if fresh_security_id is None:
+			return
 
 		try:
-			resp = platform.chat_history(gid, security_id, page=page, count=count)
+			resp = platform.chat_history(gid, fresh_security_id, page=page, count=count)
 		except NotImplementedError as exc:
 			handle_not_supported(ctx, "chatmsg", exc, fallback_message="当前平台不支持聊天记录能力")
 			return
@@ -77,7 +88,7 @@ def chatmsg_cmd(ctx: click.Context, security_id: str, page: int, count: int, sho
 			render=_render,
 			hints={"next_actions": [
 				f"{boss_command_for_ctx(ctx, 'chat')} — 返回沟通列表",
-				f"{boss_command_for_ctx(ctx, f'detail {security_id}')} — 查看职位详情",
+				f"{boss_command_for_ctx(ctx, f'detail {fresh_security_id}')} — 查看职位详情",
 			]},
 		)
 

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/contact_lookup.py

@@ -5,20 +5,24 @@ class FriendLookupLimitExceeded(RuntimeError):
 	"""Raised when paginated friend lookup cannot prove completion safely."""
 
 
-def find_friend_by_security_id(
+def find_friend(
 	platform: Any,
-	security_id: str,
+	identifier: str | int,
 	*,
 	start_page: int = 1,
 	max_pages: int = 50,
 ) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
-	"""分页遍历沟通列表，按 security_id 查找联系人。
+	"""分页遍历沟通列表，按 ``uid`` 或 ``security_id`` 查找联系人。
 
 	返回 (friend_item, error_response)：
 	- 找到联系人：返回 (item, None)
 	- 平台返回失败响应：返回 (None, raw_response)
 	- 遍历完成仍未找到：返回 (None, None)
 	"""
+	needle = str(identifier).strip()
+	if not needle:
+		return None, None
+
 	page = start_page
 	terminated = False
 	seen_signatures: set[tuple[str, ...]] = set()
@@ -29,11 +33,18 @@ def find_friend_by_security_id(
 
 		platform_data = platform.unwrap_data(resp) or {}
 		items = platform_data.get("result") or platform_data.get("friendList") or []
-		for item in items:
-			if item.get("securityId") == security_id:
+		dict_items = [item for item in items if isinstance(item, dict)]
+		# 同一页先完整检查稳定 uid，再回退到轮换的 securityId。这样即使某个
+		# securityId 恰好与另一条记录的 uid 文本相同，也不会命中错误联系人。
+		for item in dict_items:
+			if str(item.get("uid") or "").strip() == needle:
+				return item, None
+		for item in dict_items:
+			if str(item.get("securityId") or "") == needle:
 				return item, None
 
-		signature = tuple(str(item.get("securityId", "")) for item in items if isinstance(item, dict))
+		# securityId 会在请求间轮换，不能用于重复页判定；有 uid 时必须优先用 uid。
+		signature = tuple(str(item.get("uid") or item.get("securityId") or "") for item in dict_items)
 		if signature in seen_signatures:
 			terminated = True
 			break
@@ -50,25 +61,57 @@ def find_friend_by_security_id(
 	return None, None
 
 
+# 向后兼容：旧名称保留为别名（匹配逻辑已放宽为 uid 或 security_id）
+find_friend_by_security_id = find_friend
+
+
+def current_friend_security_id_or_emit(
+	ctx: Any,
+	command: str,
+	friend_item: dict[str, Any],
+) -> str | None:
+	"""读取本次 friend_list 返回的 securityId；缺失时安全停止。
+
+	调用方传入的标识可能是 uid，绝不能在 securityId 缺失时把 uid 猜作
+	securityId，尤其不能用于联系方式交换等写请求。
+	"""
+	from boss_agent_cli.display import handle_error_output
+
+	security_id = str(friend_item.get("securityId") or friend_item.get("security_id") or "").strip()
+	if security_id:
+		return security_id
+	handle_error_output(
+		ctx,
+		command,
+		code="NETWORK_ERROR",
+		message="沟通列表返回的联系人缺少当前 securityId，已停止执行；请刷新沟通列表后重试",
+	)
+	return None
+
+
 def resolve_friend_or_emit(
 	ctx: Any,
 	command: str,
 	platform: Any,
-	security_id: str,
+	identifier: str,
 	*,
 	not_found_message: str | None = None,
 ) -> dict[str, Any] | None:
-	"""按 security_id 定位联系人；失败时输出统一错误信封并返回 None。
+	"""按 uid（或 security_id）定位联系人；失败时输出统一错误信封并返回 None。
 
 	封装 mark/exchange/chatmsg/chat-summary 共用的「解析 + 错误处理」样板：
 	NotImplementedError→NOT_SUPPORTED、FriendLookupLimitExceeded→NETWORK_ERROR、
 	平台失败→按错误码、未找到→JOB_NOT_FOUND。成功返回 friend_item；否则输出错误信封
 	并返回 None（调用方应立即 return）。
+
+	注意：调用方**不要**把 identifier 直接当作 securityId 传给平台 API——
+	securityId 是每请求轮换的令牌，必须使用本次 friend_list 返回的
+	``friend_item["securityId"]``。
 	"""
 	from boss_agent_cli.display import handle_error_output, handle_not_supported, handle_platform_error_output
 
 	try:
-		friend_item, friends_error = find_friend_by_security_id(platform, security_id)
+		friend_item, friends_error = find_friend(platform, identifier)
 	except NotImplementedError as exc:
 		handle_not_supported(ctx, command, exc, fallback_message="当前平台不支持沟通列表能力")
 		return None
@@ -90,7 +133,7 @@ def resolve_friend_or_emit(
 			ctx,
 			command,
 			code="JOB_NOT_FOUND",
-			message=not_found_message or f"未在沟通列表中找到 security_id={security_id}",
+			message=not_found_message or f"未在沟通列表中找到联系人 {identifier}",
 		)
 		return None
 	return friend_item

{boss_agent_cli-2.0.0 → boss_agent_cli-2.0.1}/src/boss_agent_cli/commands/exchange.py

@@ -3,12 +3,12 @@ import click
 from boss_agent_cli.auth.manager import AuthManager
 from boss_agent_cli.compliance import require_compliance_allowed
 from boss_agent_cli.commands._platform import get_platform_instance
-from boss_agent_cli.commands.contact_lookup import resolve_friend_or_emit
+from boss_agent_cli.commands.contact_lookup import current_friend_security_id_or_emit, resolve_friend_or_emit
 from boss_agent_cli.display import boss_command_for_ctx, handle_auth_errors, handle_not_supported, handle_output, handle_platform_error_output, render_message_panel
 
 
 @click.command("exchange")
-@click.argument("security_id")
+@click.argument("security_id", metavar="UID_OR_SECURITY_ID")
 @click.option("--type", "exchange_type", default="phone", type=click.Choice(["phone", "wechat"]), help="交换类型：phone=手机号 / wechat=微信")
 @click.pass_context
 @handle_auth_errors("exchange")
@@ -30,9 +30,13 @@ def exchange_cmd(ctx: click.Context, security_id: str, exchange_type: str) -> No
 			return
 		uid = str(friend_item.get("uid", ""))
 		friend_name: str = friend_item.get("name") or "-"
+		# securityId 是每请求轮换的令牌，必须用本次 friend_list 返回的新值。
+		fresh_security_id = current_friend_security_id_or_emit(ctx, "exchange", friend_item)
+		if fresh_security_id is None:
+			return
 
 		try:
-			resp = platform.exchange_contact(security_id, uid, friend_name, exchange_type=type_id)
+			resp = platform.exchange_contact(fresh_security_id, uid, friend_name, exchange_type=type_id)
 		except NotImplementedError as exc:
 			handle_not_supported(ctx, "exchange", exc, fallback_message=f"当前平台不支持{type_label}交换能力")
 			return
@@ -41,7 +45,8 @@ def exchange_cmd(ctx: click.Context, security_id: str, exchange_type: str) -> No
 			return
 
 		data = {
-			"security_id": security_id,
+			"uid": uid,
+			"security_id": fresh_security_id,
 			"name": friend_name,
 			"type": type_label,
 			"message": f"已向 {friend_name} 发送{type_label}交换请求",
@@ -51,6 +56,6 @@ def exchange_cmd(ctx: click.Context, security_id: str, exchange_type: str) -> No
 			render=lambda d: render_message_panel(d, title="exchange"),
 			hints={"next_actions": [
 				f"{boss_command_for_ctx(ctx, 'chat')} — 返回沟通列表",
-				f"{boss_command_for_ctx(ctx, f'chatmsg {security_id}')} — 查看聊天记录",
+				f"{boss_command_for_ctx(ctx, f'chatmsg {uid}')} — 查看聊天记录",
 			]},
 		)