卓安Claw Agent 线索上下文与录音检索 V1 实现说明

日期：2026-11-13
状态：原型演示版已实现
关联：卓安Claw-Agent与业务全流程融合方案-v1.0.md、卓安Claw-录音与案件档案证据链-业务方案-v1.0.md 代码：zhuoan-claw（HEAD 待提交）

1. 解决的问题

此前 Agent 只在绑定 case_id 时注入案件上下文，客户/线索页没有对象上下文，也不能检索谈案录音。后果是：

• 客服、客户经理、谈案律师在线索页问“下一步怎么跟”，Agent 只能泛泛回答。
• 用户必须先切到案件页，Agent 才能看到业务对象，线索与案件之间断层。
• 录音虽然已能上传，但 Agent 无法按关键词找到“报价/风险/异议”对应的沟通时间点。
• 角色提示固定，客服也可能被引导去答案件问题。

本版把 Agent 从“案件聊天框”推进到“线索/客户/案件三种业务对象之一”，先解决上下文、权限和录音检索，不碰自动写入。

2. 已实现

2.1 线索/客户上下文

新增 channel/web/api/zhuoan_lead_context.py：

• 入参只有 lead_id（前端只传 id，名称/状态/权限由服务端解析）。
• 同时支持线索 intake 与客户 client，已转客户会回溯原线索。
• 注入内容：
• 姓名、脱敏电话、来源、分所、负责人、状态、咨询事项。
• 下一步跟进、备注、最近跟进记录、线索事件。
• 近期预约（按 intake 或关联案件归集）。
• 沟通录音元数据、转写状态、质检摘要。
• 关联案件仅给案号/名称/类型/阶段/状态，不含案卷正文。
• 不注入：案卷、证据、文书正文、文件路径、真实金额。
• 角色收敛：
• 客服：只给线索/客户、跟进、预约、录音元数据；关联案件详情剔除，仅保留“存在关联案件但无权限查看”的提示，防止 Agent 推断“尚未转案”。
• 客户经理：不给证据、最终报价、真实金额。
• 谈案律师：只读，不推进节点，不读案卷。
• 承办律师：可看关联案件状态，但本页不展开案卷。
• 管理者：可用经营/质量摘要，但 AI 评分不能直接作为处罚依据。

2.2 会话绑定

• channel/web/core/channel.py：
• /message 增加 lead_id 解析；有 case_id 时案件优先，没有案件才绑定线索。
• 线索不存在或无权访问时直接拒绝，不进入模型。
• 线索调用写 agent_chat 审计，target_type=lead。
• 线索上下文显式设置 zhuoan_can_file=False，不继承案件文件权限。
• bridge/agent_bridge.py：
• 系统提示后缀按 身份 → 案件 → 线索 合并。
• 线索上下文下移除 case_manager 工具。即使角色有案件文件权限，也必须先切到案件页；防止 Agent 从客户 id 自行跳到关联案件读卷。
• channel/web/static/js/chat/send.js：
• 发送体带 lead_id；有 case_id 时不带 lead_id。
• 刷新恢复：
• 线索上下文写 localStorage，刷新后保留。
• 案件上下文优先；进入案件模块时显式切回案件，并清除线索绑定。

2.3 线索/客户页 Agent 入口

• 客户/线索行新增「问 Agent」按钮。
• 点击后：
• 清除当前案件绑定，避免案件/线索串上下文。
• 右侧上下文条显示“正在处理 · 客户/线索 · 姓名”。
• 空状态提示改为“当前客户/线索已绑定”，不再误写“当前案件”。
• 按角色预填一条跟进类问题，不自动发送。
• 窄屏回退到会话页，宽屏留在客户页同屏。
• 角色化快捷提示：
• 客服：首联/回访话术、下一步建议、建档缺项。
• 客户经理：跟进建议、意向/异议、回访消息。
• 谈案律师：咨询意向/风险/接诊提纲、谈案信息缺口、转案前确认。
• 承办律师：关联案件状态、接诊交接、跟进断点。
• 管理者：跟进/预约/转化卡点、主管介入风险、谈案留痕。

2.4 录音检索工具

新增 zhuoan_case(method=search_communications)：

• 支持按当前案件或当前线索/客户范围检索。
• 检索字段：转写全文、分段时间点、录音备注、参与人、客户名、案号/案件名、质检摘要。
• 返回：
• 沟通类型、发生时间、时间点（如 00:02:00）。
• 命中片段、命中字段（转写全文/录音片段/录音元数据/质检摘要）。
• 转写状态、是否已有转写。
• 引用规则随结果返回：必须写“沟通类型 + 时间 + 时间点”，只引用返回片段，不得扩写。
• 未接 ASR 时明确返回“已检查 N 条，均未完成转写”，不伪造对话。
• 非管理者仍沿用 V1 录音可见范围：只看自己上传的录音；管理者看全部。

2.5 预约与录音归集

• appointment_context_for_lead：按 intake_id 或关联案件 id 归集预约。
• recording_summary_for_lead：按 intake_id、client_id、关联案件 id 归集录音，只返回元数据和质检摘要，不返回转写全文。
• search_recordings：在可见范围内做关键词检索，返回时间点片段。

3. 验证

已做：

1. Python 编译检查：zhuoan_lead_context.py、zhuoan_communications.py、zhuoan_appointments.py、zhuoan.py、channel.py、agent_bridge.py、zhuoan_case.py。
2. JS 语法检查：zhuoan.js、send.js。
3. 服务端构造器测试： - 线索对象：客户经理可见负责人、关联案件状态、录音统计。 - 客户对象：客户经理/承办/管理者可见 1 件关联案件；客服详情数为 0，但 cases_restricted=true，提示存在关联案件但无权查看。
4. 录音检索测试： - 合成“客户问律师费报价能不能分期”转写，检索“报价”命中，时间点 00:02:00；测试后删除合成记录。
5. 浏览器测试（1920×1080）： - 客户行「问 Agent」12 个入口可见。 - 点击后上下文条、空状态、角色快捷提示正确，无 JS 错误。 - 发送体包含 lead_id，不包含 case_id。 - 刷新后线索上下文保留，不再被默认案件覆盖。 - 点击案件模块后切回案件，线索绑定清除。
6. Agent 实机调用： - 日志确认 卓安线索上下文：已移除 case_manager 工具 (26/27)。 - Agent 仅调用 zhuoan_case(method=lead_context)，回答基于线索/客户上下文，未读取案卷。

4. 当前边界

• 线索负责人数据范围仍不完整：V1 没有独立的线索负责人/公海规则，非管理者录音可见范围按“本人上传”兜底。
• 六类材料、录音保留/销毁、财务/运营岗位细则仍按原型演示版暂不展开。
• ASR 未接入：search_communications 已具备转写与时间点检索能力，但演示库录音仍以“待转写”为主。
• 语音质检五维分析结果仍是后续 worker；本版只读已有质检摘要，不生成评分。
• 角色快捷提示是前端按角色生成，后续可改为服务端下发，避免前端与权限表漂移。

5. 下一步

1. 录音用途/阶段/参与人角色 UI 补齐，案件节点录音索引与归档门禁。
2. ASR 测试环境装 FunASR CPU，先跑电话/面谈/会议样本，再接异步转写 worker。
3. 归档缺项草稿：Agent 读六类材料与录音索引，输出缺项，不写库。
4. Agent 调用审计看板：谁、什么对象、问什么、用了什么工具、是否确认。
5. 财务/运营角色与线索负责人数据范围补齐。