上下文工程方案
系统级文档：定义清海如何感知用户身份、组装对话上下文、管理数据权威性。所有产品功能共用此架构。
📌 概述
清海是多通道 AI 企业助理，需要在每次对话中「知道自己在和谁说话」。本文档定义从消息进入到回复输出的完整上下文链路，是所有业务功能的底层基础。
🔀 消息处理主链路
🪪 身份识别
识别方式
| 通道 | 识别方式 | 说明 |
|---|---|---|
| 飞书 | 用户 ID 直接匹配 | 飞书消息自带 open_id，直接查用户档案 |
| Telegram | 管理员预配置 + /bind 自助绑定 | 管理员后台配置，或员工通过 /bind 输入手机号自助关联飞书身份 |
识别结果分支
📩 收到消息
├── ✅ 已识别员工 → 加载完整组织上下文，正常对话
├── 🚫 离职员工 → 完全静默不回复，自动通知人事确认
├── ⚪ 未关联 TG 用户 → 正常对话，无组织上下文
└── ⚪ 外部人员 → 正常对话，无组织上下文「认识」的表现方式
清海不区分首次/后续对话，统一采用自然带入方式——需要时自然使用身份信息，不刻意问好或强调身份。
| 表现 | 示例 |
|---|---|
| 需要时自然带入身份 | 「我帮你同步给你们部门负责人张三」 |
| 不需要时不刻意提及 | 正常对话，不强调对方身份 |
📂 数据权威性
数据源层级
📂 飞书通讯录（唯一权威数据源）
│
├── 组织字段 → 部门、职位、直属上级
│ └── ⚠️ 始终以飞书为准，覆盖其他来源
│
└── 同步到 ──┬── 用户档案（unified_users）
└── 用户画像（PersonCard）
└── 其他字段（偏好、习惯等）由对话积累，保留不覆盖核心原则
飞书通讯录是唯一权威数据源。组织相关字段（部门、职位、上级）始终以飞书为准。用户画像（PersonCard）作为补充——由对话积累的用户偏好、习惯等信息保留不覆盖，但组织字段发生冲突时以飞书为准。
数据同步机制
| 项目 | 说明 |
|---|---|
| 🔄 同步频率 | 每 30 分钟自动同步一次 |
| 📊 同步范围 | 全部部门（多层级递归）+ 全部人员 |
| 🔎 数据自检 | 每次同步后自动检查数据完整性 |
| 📬 缺失通知 | 缺失信息通知管理员，每日最多一次 |
🧩 上下文组装
清海的 AI 对话上下文分层组装，从固定到动态：
┌─────────────────────────────────────────┐
│ 1️⃣ 固定层（每次对话都有） │
│ 角色设定 + 技能列表 + 人格特征 │
├─────────────────────────────────────────┤
│ 2️⃣ 身份层 │
│ 用户姓名 / 部门 / 职位 / 上级 / 角色 │
├─────────────────────────────────────────┤
│ 3️⃣ 动态层 │
│ 会话简报 + 相关记忆检索结果 │
├─────────────────────────────────────────┤
│ 4️⃣ 历史层 │
│ 近期完整对话 + 旧对话压缩摘要 │
├─────────────────────────────────────────┤
│ 5️⃣ 当前消息 │
│ 用户本次发送的内容 │
└─────────────────────────────────────────┘身份层注入内容
对于已识别的员工，身份层包含：
| 字段 | 来源 | 示例 |
|---|---|---|
| 姓名 | 飞书通讯录 | 王五 |
| 部门 | 飞书通讯录 | 产品部 |
| 职位 | 飞书通讯录 | 产品经理 |
| 直属上级 | 飞书通讯录 | 张三 |
| 角色 | 系统判定 | 老板 / 管理者 / 普通员工 |
| 是否管理者 | 飞书通讯录 | 是 / 否 |
🔒 角色与权限
三级角色
| 角色 | 判定规则 | 信息可见范围 |
|---|---|---|
| 👑 老板 | 配置文件指定（1-2 人） | 系统内全部信息 |
| 📋 管理者 | 飞书通讯录中标记为部门主管 | 本部门相关信息 |
| 👤 普通员工 | 其他所有人 | 仅自己相关 + 公司公开信息 |
权限影响范围
角色影响清海的以下行为：
- 对话回复：根据角色动态调整可回答范围
- 查询结果：返回前检查角色权限
- 通知接收：不同角色收到不同级别的通知
🔔 通知上下文
通知升级链
MVP 阶段采用两层固定链路，不做 AI 自主判断。后续迭代引入智能升级。
防骚扰机制
| 规则 | 说明 |
|---|---|
| ⏱️ 冷却机制 | 同一任务的升级链共用 4 小时冷却 |
| 🌙 时段限制 | 非工作时间不发送通知 |
| 📊 每日上限 | 复用现有的每日通知上限控制 |
🔄 人员变动处理
| 事件 | 系统行为 |
|---|---|
| 👋 新员工入职 | 飞书录入 → 30 分钟内同步 → 对话时自然带入身份 |
| 🔀 人员调岗 | 飞书修改 → 下次同步更新 → 清海无缝切换上下文 |
| 🚪 员工离职 | 飞书标记 → 同步后标记 → 静默不回复 + 通知人事（后续迭代可增加交接期） |
| 📝 信息不全 | 正常对话 + 静默通知管理员补充 |
📏 上下文预算分配
定义各层上下文的 token 预算，确保总量可控、优先级清晰。
预算分配
| 层 | 内容 | 预算上限 | 优先级 | 超限策略 |
|---|---|---|---|---|
| 1️⃣ 固定层 | 角色设定 + 技能列表 + 人格 | ~2,000 tokens | 最高，不裁剪 | — |
| 2️⃣ 身份层 | 姓名/部门/职位/上级/角色 | ~200 tokens | 最高，不裁剪 | — |
| 3️⃣ 动态层 | 会话简报 + 记忆检索 | ~3,000 tokens | 高 | 按相关性排序，截断尾部 |
| 4️⃣ 历史层 | 近期对话 + 旧对话摘要 | ~4,000 tokens | 中 | 近期保留完整，旧对话压缩摘要 |
| 5️⃣ 当前消息 | 用户本次输入 | 不限 | 最高 | — |
总量控制
- 总上下文预算：约 10,000 tokens（不含当前消息和模型回复）
- 工具结果 Pruning：历史中的 tool_use 结果超过阈值后自动裁剪，只保留摘要
- 旧对话 Compaction：超过保留窗口的历史对话自动压缩为摘要，释放 token 空间
- 优先级裁剪顺序：历史层（最先压缩）→ 动态层（截断低相关性）→ 固定层/身份层（不裁剪）
设计原则
AI 的回复质量取决于上下文质量。预算分配的核心原则：宁可少放不相关的记忆，也不要挤掉近期对话。近期对话是连续性的基础，记忆检索是千人千面的基础，两者平衡，固定层和身份层永远保留。