企服助手 (Enterprise Service Assistant)

📋 概述

企服助手是面向园区运营管理的智能助手，基于《C+基础保障服务手册》设计，按照企服人员的日常工作组织：

每日常工作只有四个步骤：今日工作（看什么）→ 企业情况（为什么）→ 办理业务（怎么做）→ 处理完成（自动归档）

三板块

管家不做报修、巡检、保养、库存这些事，但负责推进——AI帮盯时限、防遗漏。政策日历、认股权台账均属于C+增值服务，不独立成模块。

🛡️ 自由度—可控性声明（出厂标配）

依据 writing-for-agents v1.2.0 第 8 项自检：每个 skill 必须显式声明其「自由度—可控性」位置。高自由度 ≠ 拥有控制权。

⚠️ AI执行原则（重要）

本skill通过腾讯文档MCP工具读取数据，支持本地缓存加速，所有逻辑由AI直接执行。

缓存机制（必须遵循）

每次查询前，AI 必须按以下顺序执行：

Step 0 → 检查本地缓存（最快，<0.001秒）
         cache_file = ~/.workbuddy/workspace/enterprise-service-assistant/cache/{table_name}.json
         检查 cache_file 是否存在 且 修改时间 <30分钟前
         → 若存在且未过期 → 直接使用，跳过 Step 1

Step 1 → 缓存未命中，调用腾讯文档MCP工具读取数据
         方式A（推荐，无需sheet_id）：mcp__tencent-docs__get_content(file_id)
         方式B（需sheet_id）：mcp__tencent-docs__smartsheet.list_records(file_id, sheet_id)
         方式C：mcp__tencent-docs__smartsheet.get_cell_data(doc_id, table_id, record_id, field_id)
         💡 get_content 不需要sheet_id，一次调用返回所有子表markdown数据，优先使用

Step 2 → 将数据写入本地缓存
         cache_file = ~/.workbuddy/workspace/enterprise-service-assistant/cache/{table_name}.json
         写入格式：{"updated_at": "ISO时间戳", "data": [...]}

Step 3 → 按本文档中的逻辑处理数据
         - 计算、判断、分级

Step 4 → 格式化输出（使用本文档中的模板）

Step 5 → 推送企微（如需要，使用本文档中的webhook配置）

缓存TTL配置

快速模式（用户主动触发）

触发词（任选一）：

• 「快速查询 XX」
• 「用缓存，别调MCP」
• 「本地数据有吗？先看本地的」

AI 行为：

• 只读取 ~/.workbuddy/workspace/enterprise-service-assistant/cache/ 中的 JSON 文件
• 完全不调用 MCP
• 响应时间：<0.1秒

缓存刷新（用户主动触发）

触发词（任选一）：

• 「刷新」
• 「重新读取」
• 「调MCP」
• 「更新缓存」

AI 行为：

• 删除对应的缓存文件
• 重新调用 MCP 读取最新数据
• 写入新缓存

🗄️ 本地数据库模式 (SQLite) — 推荐

核心优势：

• 查询速度：<0.1秒（直接读本地DB，无需API调用）
• Token消耗：0（查询时不调用任何MCP工具）
• 支持复杂查询：SQL联表、聚合、筛选

数据库路径

~/.workbuddy/workspace/enterprise-service-assistant/local_db.sqlite

AI执行优先级（必须遵循）

Step -1 → 读取配置 force_local / mcp_available（来自 knowledge_base_config.json）
          if config.get("force_local") is True or config.get("mcp_available") is False:
              → 跳过所有 MCP 调用，直接查本地 SQLite（Step 3）
              → 适用场景：腾讯文档 MCP 未连接 / 单机演示 / 弱网环境
              → 这是最快路径，响应 <5ms，零网络等待

Step 0 → 检查本地数据库是否存在且新鲜（<24小时）

Step 0 → 检查本地数据库是否存在且新鲜（<24小时） DB_PATH = ~/.workbuddy/workspace/enterprise-service-assistant/local_db.sqlite → 若存在且新鲜 → 直接查SQLite（Step 3） → 若否则过期 → 先同步（Step 1），再查询（Step 3）

Step 1 → 同步腾讯文档数据到SQLite（仅在DB不存在/过期时） 调用 mcp__tencent-docs__smartsheet.list_records 读取数据 写入SQLite（见"同步逻辑"章节）

Step 2 → 标记同步完成 更新 sync_log 表

Step 3 → 查询SQLite（超快，零token） 使用 Python + sqlite3 模块查询 格式化输出

### 同步逻辑

**触发词：**
- 「同步数据库」
- 「刷新数据库」
- 「更新本地数据」

**AI行为：**
1. 调用 `mcp__tencent-docs__get_content(file_id)` 读取所有工作表数据（不需要sheet_id）
2. 用Python解析返回的markdown表格数据
3. **同步校验（data-security-verifier 能力③，铁律）**：覆盖前对比 源表行数 vs 目标表行数、主键去重、必填字段非空率（单元号/企业名/金额）
   - 校验通过 → 才执行覆盖写入
   - **校验失败 → 不覆盖**：保留旧库，`sync_log.status='failed'`，输出差异明细，等人工确认
4. 更新 `sync_log` 表记录同步时间（含 `data_as_of` 时间戳，供时效分级使用）

**💡 为什么用 get_content 不用 list_records：**
- `get_content` 只需要 `file_id`，不需要 `sheet_id`
- 一次调用返回所有子表数据（客户管理、费用收缴、报修情况汇总、库存管理、C+服务记录、能耗汇总、投诉记录、退租汇总等）
- 没有分页问题，没有权限门槛
- 解析markdown表格比调多个MCP更简单可靠

**AI同步流程（AI执行）：**

```python
import sqlite3
from pathlib import Path

DB_PATH = Path.home() / ".workbuddy" / "workspace" / "enterprise-service-assistant" / "local_db.sqlite"

# 连接数据库
conn = sqlite3.connect(str(DB_PATH))
cursor = conn.cursor()

# 通过get_content读取所有数据（不需要sheet_id）
content_result = mcp__tencent-docs__get_content(file_id="YOUR_DOC_ID")
# content_result 包含所有子表的markdown表格

# 解析markdown表格（按子表标题分割）
tables = parse_markdown_tables(content_result.get('content', ''))

# 写入各表
for table_name, data in tables.items():
    # 清空并写入
    cursor.execute(f"DELETE FROM {table_name}")
    for row in data:
        # 根据表名映射字段，insert into
        pass

# 记录同步日志
cursor.execute("""
    INSERT INTO sync_log (table_name, sync_time, record_count, status)
    VALUES (?, ?, ?, ?)
""", (table_name, datetime.now().isoformat(), len(data), 'success'))

conn.commit()
conn.close()

print("✅ 同步完成")

查询逻辑

触发词（任选一）：

• 普通查询（如「查询客户 T1-601」）
• 「快速查询」（明确指定读DB）

AI行为：

1. 检查DB是否存在且新鲜（<24小时）
2. 若新鲜 → 直接查SQLite
3. 若否则过期 → 先同步，再查询

示例代码（AI执行）：

import sqlite3
from pathlib import Path
from datetime import datetime, timedelta

DB_PATH = Path.home() / ".workbuddy" / "workspace" / "enterprise-service-assistant" / "local_db.sqlite"

# 检查DB是否新鲜
def is_db_fresh():
    if not DB_PATH.exists():
        return False
    
    try:
        conn = sqlite3.connect(str(DB_PATH))
        cursor = conn.cursor()
        cursor.execute("SELECT MAX(sync_time) FROM sync_log WHERE status = 'success'")
        result = cursor.fetchone()
        conn.close()
    except sqlite3.OperationalError:
        # sync_log 表缺失或损坏：降级为「本地可用」，不抛异常、不触发 MCP
        return False
    
    if not result or not result[0]:
        return False
    
    last_sync = datetime.fromisoformat(result[0])
    return datetime.now() - last_sync < timedelta(hours=24)

# 查询客户
def query_customer(unit_no):
    conn = sqlite3.connect(str(DB_PATH))
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM customers WHERE unit_no = ?", (unit_no,))
    result = cursor.fetchone()
    conn.close()
    return result

# 主逻辑
if not is_db_fresh():
    print("⚠️  数据库已过期，正在同步...")
    # 调用同步逻辑（见上）
    
result = query_customer("T1-601")
print(result)

数据库表结构

🛡️ 脱敏字段说明：customers.phone / contact 落库即脱敏（见「注意事项 3 落库脱敏策略」）；完整号码需用时从腾讯文档源实时读取。

定时同步设置

创建每日同步任务：

@WorkBuddy 创建一个定时任务，名称"企服数据同步"，每天08:00执行，提示词："同步企服助手所有表数据（客户管理、费用收缴、报修情况、库存管理、C+服务记录、认股权台账）到本地SQLite数据库"

automation_update 参数：

• scheduleType: "recurring"
• rrule: "FREQ=DAILY;BYHOUR=8;BYMINUTE=0"
• prompt: "同步企服助手所有表数据到本地SQLite数据库，使用mcp__tencent-docs__smartsheet.list_records读取数据，写入~/.workbuddy/workspace/enterprise-service-assistant/local_db.sqlite"
• status: "ACTIVE"

原有执行规则（仍然有效）

• ✅ 使用 mcp__tencent-docs__smartsheet.list_records 等MCP工具读取数据（仅在同步时）
• ✅ 所有计算逻辑由AI阅读本文档后执行
• ✅ 所有推送模板在本文档中定义
• ❌ 禁止：直接读取Excel文件（应使用MCP工具或SQLite）

⚙️ 知识库配置

数据通过知识库模块读取，支持三种数据源：

⚠️ 重要：配置文件在技能目录外

配置文件路径：~/.workbuddy/config/enterprise-service-assistant/knowledge_base_config.json

这样做的好处：

• ✅ 打包分享时不会泄露您的知识库配置
• ✅ 每个用户需要自己配置数据源
• ✅ 配置文件与技能分离，更安全

1. 创建配置文件

第一步：创建配置目录

mkdir -p ~/.workbuddy/config/enterprise-service-assistant

第二步：复制示例配置

cp knowledge_base_config.example.json ~/.workbuddy/config/enterprise-service-assistant/knowledge_base_config.json

第三步：编辑配置文件

# macOS
open ~/.workbuddy/config/enterprise-service-assistant/knowledge_base_config.json

# 或手动编辑，填入实际配置

2. 数据源类型

3. 配置示例

本地Excel文件：

{
  "source_type": "local",
  "source_config": {
    "file_path": "path/to/园区数据.xlsx"
  }
}

腾讯文档：

{
  "source_type": "tencent_docs",
  "source_config": {
    "doc_id": "YOUR_DOC_ID"
  },
  "force_local": false,
  "mcp_available": true
}

⚡ 离线/弱网加速开关（新增）：当腾讯文档 MCP 未连接、或希望完全本地化运行时，设 "force_local": true 且 "mcp_available": false。此时 AI 跳过所有 MCP 调用，直接读本地 SQLite，响应 <5ms，零网络等待。恢复联网同步后改回 false 即可。

IMA知识库：

{
  "source_type": "ima",
  "source_config": {
    "kb_id": "your-ima-kb-id"
  }
}

4. AI自动加载配置

配置完成后，AI会自动从外部路径加载配置：

# 不需要传入config，自动从 ~/.workbuddy/config/enterprise-service-assistant/knowledge_base_config.json 加载
# 或使用自定义配置（可选）
custom_config = {...}

🗂️ 缓存目录设置

AI 首次执行查询时，自动创建缓存目录：

mkdir -p ~/.workbuddy/workspace/enterprise-service-assistant/cache/

缓存文件命名规则：

~/.workbuddy/workspace/enterprise-service-assistant/cache/
├── 客户管理.json
├── 费用收缴.json
├── 报修情况汇总.json
├── 📋客户工单台账.json
├── ⚙️处理人员配置.json
├── 库存管理.json
├── C+服务记录.json
└── 认股权台账.json

缓存文件格式：

{
  "updated_at": "2026-06-13T13:00:00",
  "ttl_minutes": 30,
  "data": [...]
}

AI 查询时检查缓存的逻辑：

1. 检查 {table_name}.json 是否存在
2. 检查 updated_at 距离现在是否超过 ttl_minutes
3. 若未过期 → 直接读取 JSON，不调 MCP（<0.1秒）
4. 若已过期或不存在 → 调 MCP，更新缓存

⚙️ 腾讯文档配置

本Skill通过腾讯文档MCP工具直接读取数据。

⚡ 性能说明：

• 首次查询（缓存未命中）：2-3秒（调MCP API）
• 缓存命中后查询：<0.1秒（读本地JSON缓存）
• 推荐：首次查询后，使用「快速查询」触发词，体验秒回

💡 更快的方式（推荐）： 使用本地文件模式（见「知识库配置」章节），直接读取本地Excel/CSV文件，无需API调用，查询速度 <0.05秒。

配置步骤

第1步：在腾讯文档创建智能表格，包含以下工作表：

• 👨客户管理👨
• 👨💼费用收缴👨💼
• 💡能耗汇总💡
• C+服务记录（含政策日历、认股权台账）
• 投诉记录
• 退租汇总
• 🛠️报修情况汇总🛠️
• 安全巡检计划
• 设备保养台账
• 📦库存管理📦秩序环境
• 秩序环境入库
• 秩序环境出库
• 库存-工程
• 库存-固定资产
• 📋客户工单台账
• ⚙️处理人员配置

第2步：复制文档ID（URL中 /s/ 后面的部分）

第3步：在以下代码示例中，将 YOUR_DOC_ID 替换为实际的文档ID：

# 示例：读取客户管理表
mcp__tencent-docs__smartsheet.list_records(
    file_id="YOUR_DOC_ID",
    sheet_id="m3LDSO"  # 👨客户管理👨 的 sheet_id
)

💡 提示：首次使用时，AI会自动帮你获取各个工作表的 sheet_id，你只需要提供 file_id。

📦 模块一：服务企业 (Enterprise Service)

功能

1. 查询客户档案 — 按单元号/租户名/合同号查询
2. 构建客户画像 — 聚合费用、服务、报修、能耗记录
3. 计算风险标记 — 欠费风险、流失风险、高频报修、低满意度
4. 生成客户时间线 — 按时间倒序排列所有事件

客户管理表字段映射（👨客户管理👨）

核心逻辑

1. 查询客户档案

import json



def parse_excel_date(val):
    if isinstance(val, datetime): return val.date()
    if isinstance(val, str): return datetime.strptime(val, "%Y年%m月%d日").date()
    return None

# 从知识库读取费用数据
fee_data = mcp__tencent-docs__smartsheet.list_records(doc_id, table_id='👨💼费用收缴👨💼')

today = datetime.now().date()
for row in fee_data:
    overdue_days = (today - parse_excel_date(row.get('应收到期日'))).days
    # 后续处理...

欠费合并计算

同一单元号的所有欠费记录合并：

1. 按费用类型分组统计
2. 本金 + 滞纳金（如有）
3. 生成合并通知一次性发送

触发场景

• 每天10:00定时任务自动检查
• @企服助手 催缴检查
• 企微群 @催缴

输出模板

【催缴通知】{租户名}：

您有以下费用待缴纳：
1. {月份}{费项项目}：¥{欠收金额}（逾期{overdue_days}天）
2. ...

总金额：¥{total_amount}

请尽快安排缴纳，避免产生更多滞纳金。
缴费账户：XXX银行 XXX账户

📦 模块二：沟通续租 (Contract Renewal)

功能

1. 三级续租预警 — 90天/60天/30天提前标记
2. 企业画像分析 — 缴费准时率、满意度、成交率
3. 续租方案生成 — 根据企业价值评估生成差异化方案
4. 稳租策略 — A/B/C级客户差异化稳租方案

续租预警三级体系

客户价值评估算法

总分 ≥80 = A级，≥60 = B级，<60 = C级

续租方案决策矩阵

稳租策略（按价值等级）

A级客户（全方位稳租）：

• 提高服务标准：走访频率月度→双周，专属管家
• 关怀活动：生日礼物、节日慰问、企业周年庆贺
• 服务赠送：免费会议室8小时/月、免费停车券2张/月

B级客户（中度稳租）：

• 提高服务标准：走访频率季度→月度
• 关怀活动：节日慰问
• 服务赠送：免费会议室4小时/月

C级客户（基础稳租）：

• 基础服务标准
• 市场化租金定价

触发场景

• 每天09:00定时任务自动检查
• @企服助手 续租检查
• @企服助手 生成续租方案 T1-601

输出模板

━━━━━━━━━━━━━━━
【续租{red}预警】

🏢 企业：{tenant_name}
📍 单元：{unit_no}
📅 合同到期：{lease_end}
⏰ 剩余天数：{days_remaining}天

━━━ 企业画像 ━━━
等级：{level} | 企业类型：{enterprise_type}
缴费准时率：{payment_rate*100:.1f}%
服务满意度：{satisfaction*100:.1f}%

━━━ 续租方案 ━━━
方案类型：{plan_type}
建议租金：¥{proposed_rent}/㎡/月
优惠折扣：{discount_rate*100:.0f}折
优惠政策：{incentive_policy}

🚨 请 @招商人员 @管家 立即跟进！
━━━━━━━━━━━━━━━

📦 模块三：跟进报修 (Workorder Follow-up)

功能

1. 自动分派 — 根据报修描述判断专业领域，分配维修人员
2. SLA超时监控 — 紧急工单>1小时/普通工单>24小时触发升级
3. 工单状态更新 — 待处理→处理中→已完成
4. 维修评价系统 — 客户对维修服务评分

报修情况汇总表字段映射（🛠️报修情况汇总🛠️）

维修人员分派规则

分派逻辑优先顺序：

1. 优先查 ⚙️处理人员配置 表，按「工单类型 + 子类关键词」匹配
2. 若配置表无匹配，回退到以下硬编码规则

硬编码回退规则：

SLA超时标准

触发场景

• 每小时定时任务检查SLA状态
• @企服助手 创建工单 T1-9F女厕 女厕门打不开
• @企服助手 检查工单状态

输出模板

━━━━━━━━━━━━━━━
【紧急工单分派】

📍 位置：{unit_no}
🚨 紧急程度：{urgency}
📝 报修描述：{description}
👤 报修人：{reporter}
⏰ 报修时间：{report_time}

👷 维修人员：{assignee}
⚡ 请立即处理！
━━━━━━━━━━━━━━━

📦 模块四：事项跟进 · 协调库存 / 资产 / 工程 (Inventory & Asset Coordination)

功能

1. 库存水位计算 — 可用月数 = 现库存 / 月使用量
2. 四级库存分级 — 缺货/预警/关注/正常
3. 补货提醒生成 — 按级别生成采购建议
4. 出入库记录更新 — 支持入库/出库操作

库存管理表字段映射（📦库存管理📦秩序环境）

四级库存分级体系

核心逻辑

available_months = 现库存 / 月使用量 if 月使用量 > 0 else 999

触发场景

• 每天09:00定时任务自动检查
• @企服助手 库存检查
• @企服助手 入库 洗手液 5
• @企服助手 出库 洗手液 2

输出模板

━━━━━━━━━━━━━━━
【库存监控日报】{today}

━━━ 🚨 缺货物资 ━━━
{缺货清单 或 "无"}

━━━ ⚠️ 预警物资 ━━━
1. {名称} | 规格：{规格} | 现库存：{现库存}
   月使用量：{月使用量} | 可用月数：{available_months:.1f}
   建议采购量：{purchase_qty}

━━━ 📢 关注物资 ━━━
{关注清单 或 "无"}

━━━ 统计 ━━━
物资总数：{total}个
缺货：{out}个 | 预警：{warn}个 | 关注：{关注}个 | 正常：{normal}个
━━━━━━━━━━━━━━━

📦 模块五：C+增值服务 (C+ Value-Added Service)

功能

1. 需求挖掘 — 从走访记录详情中提取企业需求（NLP关键词匹配）
2. 企业画像获取 — 读取客户管理表获取企业类型、等级
3. 服务推荐算法 — 根据企业类型和需求匹配服务规则库
4. 跟进闭环 — 跟踪推荐服务的跟进状态，提醒逾期未完成

C+服务记录表字段映射

需求挖掘关键词库

服务匹配规则库

触发场景

• 每天10:00定时任务分析昨日走访记录
• @企服助手 服务匹配 上海铭尤力
• @企服助手 分析服务需求

输出模板

━━━━━━━━━━━━━━━
【C+服务推荐】{tenant_name}

━━━ 企业画像 ━━━
类型：{enterprise_type} | 等级：{level}
经营范围：{business_scope}

━━━ 走访需求 ━━━
{needs}

━━━ 推荐服务 ━━━
1. {服务名称}（{优先级}优先级）
   理由：{reason}
   优惠：{discount}

⚡ 操作链接：[腾讯文档-C+服务]
━━━━━━━━━━━━━━━

📦 模块六：客户微信工单处理 (Customer WeChat Workorder)

功能

1. 客户消息接收 — 通过企微MCP（或管家转发）接收客户微信消息
2. 意图识别与分类 — AI自动判断工单类型（报修/投诉/咨询/催缴/续租/其他）+ 子类（如"水管漏水"）
3. 自动分派 — 查 ⚙️处理人员配置 表匹配处理人
4. 工单创建 — 写入 📋客户工单台账，生成完整记录
5. 进度跟踪与闭环 — 状态更新、SLA监控、完成推送

工作流程

客户通过企微客服号私聊发消息
    ↓
[1] 企服助手接收消息（企微MCP回调或管家粘贴转发）
    ↓
[2] AI意图识别
    - 类型：报修/投诉/咨询/催缴/续租/其他
    - 子类：AI从消息中提取关键词判断
    - 紧急程度：含"爆""漏""着火"等→紧急
    - 位置提取：T1-601 等
    ↓
[3] 查询分派规则
    调用：mcp__tencent-docs__smartsheet.list_records(
        file_id="DOC_ID",
        sheet_id="⚙️处理人员配置的sheet_id"
    )
    匹配规则：工单类型 + 子类关键词包含
    ↓
[4] 创建工单
    写入：mcp__tencent-docs__smartsheet.add_records(
        file_id="DOC_ID",
        sheet_id="📋客户工单台账的sheet_id",
        records=[{...}]
    )
    同时写入本地 tracking/completion_log.json
    ↓
[5] 推送通知
    - @处理人：新工单信息
    - 回执客户：已登记+预计处理时间
    ↓
[6] 状态更新（后续）
    客户或管家说「WO-001 处理完了」
    → 更新台账状态为"已完成"
    → 推送客户告知完成

📋客户工单台账字段映射

⚙️处理人员配置表字段映射

自动分派逻辑（AI执行）

# Step 1: 从配置表读取分派规则
def get_assignment_rules():
    response = mcp__tencent-docs__smartsheet.list_records(
        file_id="DOC_ID",
        sheet_id="⚙️处理人员配置的sheet_id"
    )
    return response  # 返回所有行

# Step 2: 匹配规则（按行号顺序优先匹配）
def match_rule(rules, work_type, description):
    """
    匹配规则：先匹配工单类型，再匹配子类关键词
    例：type="报修-水电", keywords="水,漏水,水管"
    若 description 包含任一关键词 → 匹配成功
    """
    for rule in rules:
        if rule.get('工单类型') != work_type:
            continue
        keywords = rule.get('子类关键词', '').split(',')
        for kw in keywords:
            kw = kw.strip()
            if kw and kw in description:
                return rule
    return None

# Step 3: 根据配置表中的SLA计算截止时间
def calc_sla_deadline(rule, urgency):
    if urgency == '紧急':
        hours = rule.get('SLA紧急_小时', 1)
    else:
        hours = rule.get('SLA普通_小时', 24)
    from datetime import datetime, timedelta
    return (datetime.now() + timedelta(hours=hours)).isoformat()

文本分类逻辑

企服助手在接到客户消息后，按以下流程进行意图识别：

Step 1 → 类型判断（关键词优先，AI兜底）

Step 2 → 子类提取：从消息中提取具体内容，填入「子类」字段

Step 3 → 位置提取：正则匹配 T\d+-\d+、X栋X单元 等模式

触发场景

输出模板

━━━━━━━━━━━━━━━
【新工单已创建】

📋 工单编号：{work_order_id}
📍 单元：{unit_no}
📝 类型：{work_type} - {sub_type}
🚨 紧急程度：{urgency}
📄 问题描述：{description}

👤 客户：{customer_name}
👷 已分派：{handler}
⏰ SLA截止：{sla_deadline}

🔄 当前状态：{status}
━━━━━━━━━━━━━━━

客户回执模板：

✅ 收到！已为您登记工单，编号：{work_order_id}
👷 已安排{handler}师傅处理
⏰ 预计{estimated_time}内到场处理
📌 后续可发送「查工单 {work_order_id}」查询进度

分派通知模板（推送给处理人）：

【新工单】{work_order_id} · {work_type}
📍 {unit_no} | 🚨 {urgency}
📝 {description}
⏰ SLA截止：{sla_deadline}
⚠️ 请及时处理！

SLA超时升级模板：

🚨【SLA超时】工单 {work_order_id}
📍 {unit_no} | 类型：{work_type}
👷 处理人：{handler}
⏰ 已超时 {overdue_minutes} 分钟
📝 问题描述：{description}

⚠️ @all 请主管介入！
━━━━━━━━━━━━━━━

功能

1. 走访质量评分 — 基于客户情绪、成交情况、服务类别、详情记录完整性计算（满分100）
2. 走访闭环追踪 — 检查走访中提出的问题是否有后续跟进记录
3. 智能排程 — 根据企业等级、续租预警、欠费风险自动生成走访计划
4. 管家分配 — 根据单元号楼层自动分配管家

走访质量评分算法（满分100）

智能排程规则

管家分配规则

触发场景

• 每周一09:00定时任务生成本周走访计划
• @企服助手 走访管理
• @企服助手 生成本周走访计划

输出模板

━━━━━━━━━━━━━━━
【本周走访计划】{week_start} ~ {week_end}

━━━ 🔴 高优先级（必访）━━━
共{N}个企业待走访

1. {unit_no} {tenant_name}
   等级：{level} | 上次走访：{last_visit}
   原因：{reason}
   管家：{visitor}
   历史质量评分：{avg_quality:.1f} | 闭环状态：{followup_status}

━━━ 🟡 中优先级（应访）━━━
共{M}个企业待走访

━━━ 🟢 低优先级（可访）━━━
共{K}个企业待走访

━━━ 统计 ━━━
本周走访总数：{total}个
高优先级：{N}个 | 中优先级：{M}个 | 低优先级：{K}个

⚡ 操作链接：[腾讯文档-走访计划]
━━━━━━━━━━━━━━━

📊 认股权管理 (Equity Warrant Management)

功能

1. 认股权台账 — 记录每笔认股权的企业、金额、比例、估值上限、到期日
2. 到期提醒 — 认股权到期前90天提醒企服人员跟进
3. 行权条件监控 — 监控企业是否完成合格融资（工商变更/增资协议）
4. 转让退出管理 — 记录认股权转让给第三方投资机构的价格、税费
5. 回购义务追踪 — 企业未融资时，追踪创始股东回购履约情况

腾讯文档数据结构（建议新增工作表：认股权台账）

核心逻辑

1. 认股权台账管理

新增认股权（调用 mcp__tencent-docs__smartsheet.add_records）：

调用 mcp__tencent-docs__smartsheet.add_records
  file_id: "YOUR_DOC_ID"
  sheet_id: "认股权台账的sheet_id"
  records: [{
    "fields": {
      "企业名称": "上海景峰制药有限公司",
      "单元号": "T1-603.05",
      "认股权比例": 5,
      "估值上限": 100000000,
      "行权折扣": 70,
      "授予日期": "2026-06-11",
      "到期日期": "2029-06-11",
      "状态": "待触发",
      "让利金额": 3000000,
      "融资进展": "未启动",
      "备注": ""
    }
  }]

2. 到期提醒（定时任务）

检查逻辑（每日执行）：

from datetime import datetime, timedelta

# 读取认股权台账
warrant_data = mcp__tencent-docs__smartsheet.list_records(
    file_id="YOUR_DOC_ID",
    sheet_id="认股权台账的sheet_id"
)

today = datetime.now().date()
for record in warrant_data:
    expiry_date = datetime.strptime(record['到期日期'], '%Y-%m-%d').date()
    days_left = (expiry_date - today).days
    
    if 0 <= days_left <= 90:
        # 到期前90天内，提醒跟进
        print(f"⚠️ 认股权即将到期：{record['企业名称']}（{days_left}天）")
        
        # 检查融资进展
        if record['融资进展'] == '未启动':
            print(f"  ⚠️ 融资进展：未启动，建议立即对接投资机构")
        elif record['融资进展'] in ['对接中', 'TS阶段', 'DD阶段']:
            print(f"  ✅ 融资进展：{record['融资进展']}，继续跟进")
        elif record['融资进展'] == '已交割':
            print(f"  ✅ 融资已完成，可行权")

3. 行权条件监控

触发条件：

• 企业完成合格融资（工商变更/增资协议）
• 融资估值 ≥ 估值上限 × 行权折扣

行权方式（三选一）：

1. 行权获股权 — 按约定比例获得企业股权
2. 转让获利 — 将认股权转让给第三方投资机构
3. 放弃行权 — 认股权失效

操作流程：

Step 1 → 监控企业融资进展（从C+服务记录中获取）
         mcp__tencent-docs__smartsheet.list_records(
             file_id="YOUR_DOC_ID",
             sheet_id="C+服务记录"
         )
         筛选：服务类别 = "融资对接" AND 企业名称 = "XX公司"

Step 2 → 确认合格融资（工商变更完成 + 融资额 ≥ 最低要求）
         若合格 → 更新认股权台账，状态改为"可行权"

Step 3 → 与企业协商行权方式
         - 若行权获股权 → 签署股权转让协议，完成工商变更
         - 若转让获利 → 寻找第三方投资机构，签署转让协议
         - 若放弃行权 → 认股权失效，更新台账

Step 4 → 更新认股权台账
         mcp__tencent-docs__smartsheet.update_records(
             file_id="YOUR_DOC_ID",
             sheet_id="认股权台账的sheet_id",
             records=[{
               "record_id": "xxx",
               "fields": {
                 "状态": "已行权",  # 或"已转让"/"已失效"
                 "备注": "2026-12-01 行权获股权5%"
               }
             }]
         )

4. 回购义务追踪

触发条件：

• 认股权到期（到期日期 < 今天）
• 且企业未完成合格融资

操作流程：

Step 1 → 检查到期未行权的认股权
         筛选：状态 = "待触发" AND 到期日期 < 今天

Step 2 → 联系企业创始股东，触发回购义务
         回购金额 = 让利金额 + 利息（如年化5%）

Step 3 → 追踪回购履约情况
         - 若已支付 → 更新台账，状态改为"已回购"
         - 若未支付 → 发送律师函，准备诉讼

适用企业筛选标准

筛选数据来源

从C+服务记录中读取以下字段，用于筛选A/B/C类企业：

读取方式（AI自动执行）：

Step 1 → 读取C+服务记录
         mcp__tencent-docs__smartsheet.list_records(
             file_id="YOUR_DOC_ID",
             sheet_id="iSs70V"  # C+服务记录 的 sheet_id
         )

Step 2 → 提取最新一条记录的"营收增长%"和"融资意向"字段
         # 按"服务日期"排序，取最新一条
         latest_record = max(records, key=lambda x: x['服务日期'])

Step 3 → 根据筛选标准分类
         if latest_record['营收增长%'] >= 30 and latest_record['融资意向'] in ['有', '强烈']:
             category = "A类"
         elif 10 <= latest_record['营收增长%'] < 30:
             category = "B类"
         else:
             category = "C类"

💡 提示：若C+服务记录中无"营收增长%"或"融资意向"数据，AI应主动询问用户，或建议企服人员在下次走访时补充。

风险控制

触发场景

⏰ 定时任务配置

在 WorkBuddy 中使用 automation_update 工具配置以下定时任务：

1. 每日风险客户提醒（09:00）

创建方式：在 WorkBuddy 中执行：

@WorkBuddy 创建一个定时任务，名称"风险客户提醒日报"，每天09:00执行，提示词："扫描所有客户风险（欠费、续租预警、高频报修、低满意度），生成风险提醒日报并推送企微群"

automation_update 参数参考：

• scheduleType: "recurring"
• rrule: "FREQ=DAILY;BYHOUR=9;BYMINUTE=0"
• prompt: "扫描所有客户风险（欠费、续租预警、高频报修、低满意度），生成风险提醒日报并推送企微群"
• status: "ACTIVE"

2. 合同续租预警（09:00）

创建方式：

@WorkBuddy 创建一个定时任务，名称"合同续租预警"，每天09:00执行，提示词："检查合同到期日期，提前3个月标记续租预警，提前2个月生成续租方案"

3. 费用催缴检查（10:00）

创建方式：

@WorkBuddy 创建一个定时任务，名称"费用催缴检查"，每天10:00执行，提示词："检查费用收缴状态，按三级分级体系（1-7天静默/8-30天提醒/31天+升级）生成催缴报告"

4. C+服务需求分析（10:00）

创建方式：

@WorkBuddy 创建一个定时任务，名称"C+服务需求分析"，每天10:00执行，提示词："分析昨日C+服务走访记录，从详情记录中提取企业需求，根据企业类型匹配服务资源，生成推荐方案"

5. 库存监控检查（09:00）

创建方式：

@WorkBuddy 创建一个定时任务，名称"库存监控检查"，每天09:00执行，提示词："检查所有物资的库存水位（可用月数=现库存/月使用量），生成补货提醒（缺货/预警/关注三级）并推送"

6. 工单SLA监控（每小时）

创建方式：

@WorkBuddy 创建一个定时任务，名称"工单SLA监控"，每小时执行，提示词："同时检查「🛠️报修情况汇总」和「📋客户工单台账」两张表中待处理工单的SLA状态，紧急工单超过1小时或普通工单超过24小时立即升级推送"

automation_update 参数参考：

• scheduleType: "recurring"
• rrule: "FREQ=HOURLY"
• prompt: "检查「报修情况汇总」和「客户工单台账」中待处理工单的SLA状态，紧急工单超过1小时或普通工单超过24小时立即升级推送"
• status: "ACTIVE"

7. 每周走访计划生成（周一09:00）

创建方式：

@WorkBuddy 创建一个定时任务，名称"走访计划生成"，每周一09:00执行，提示词："生成本周走访计划，根据企业等级（A级每月/B级每季度）、续租预警（剩余≤60天）、欠费风险智能规划走访任务，分配高/中/低优先级"

💬 企微推送配置

Webhook 地址（外部配置，不写入包）

🔒 安全修复（2026-08-17）：webhook key 不再硬编码在 SKILL.md 内（防止 skill 分享时密钥泄露）。改为从外部配置读取，配置路径与 knowledge_base_config.json 同级，不进包、不随分享泄露。

配置步骤：

1. 创建配置目录与文件：

mkdir -p ~/.workbuddy/config/enterprise-service-assistant
cp wecom_webhook.example.json ~/.workbuddy/config/enterprise-service-assistant/wecom_webhook.json

2. 编辑 ~/.workbuddy/config/enterprise-service-assistant/wecom_webhook.json，填入真实 webhook：

{
  "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_WEBHOOK_KEY"
}

推送前读取规则：

• 推送前读取该文件获取 webhook_url；
• 文件不存在或 key 为占位符 → 提示用户先配置，不静默失败、不内置兜底 key；
• 推送内容必须已过脱敏闸门（企业名 / 金额 / 单元号 XX 化，见下方「数据隐私（铁律）」）。

推送格式规范

• 使用Markdown格式
• 标题使用 ━━━━━━━━━━━━━━━ 分隔线
• 紧急通知使用 @all 或 @具体人员
• 操作链接指向腾讯文档对应表格

📝 使用示例

示例1：查询客户档案

用户输入：@企服助手 查询客户 T1-601

执行逻辑：

1. AI自动从 ~/.workbuddy/config/enterprise-service-assistant/knowledge_base_config.json 加载配置
2. 调用 mcp__tencent-docs__smartsheet.list_records(doc_id, table_id='👨客户管理👨') 读取客户数据
3. 筛选 单元号 = "T1-601" 的行
4. 格式化输出客户档案

示例2：检查费用催缴

用户输入：@企服助手 催缴检查

执行逻辑：

1. AI自动加载配置并初始化知识库
2. 调用 mcp__tencent-docs__smartsheet.list_records(doc_id, table_id='👨💼费用收缴👨💼') 读取费用数据
3. 计算每条记录的逾期天数
4. 按三级分级体系分类
5. 生成催缴报告并推送企微

示例3：生成续租方案

用户输入：@企服助手 生成续租方案 T1-601

执行逻辑：

1. 通过知识库查询客户档案获取企业类型和等级
2. 通过知识库读取历史费用记录计算缴费准时率
3. 通过知识库读取C+服务记录计算满意度和成交率
4. 客户价值评估（5个维度，满分100）
5. 根据决策矩阵生成续租方案
6. 根据价值等级生成稳租策略

🔧 快速开始

1. 创建配置目录

mkdir -p ~/.workbuddy/config/enterprise-service-assistant

2. 复制示例配置

cp knowledge_base_config.example.json ~/.workbuddy/config/enterprise-service-assistant/knowledge_base_config.json

3. 编辑配置文件

# macOS
open ~/.workbuddy/config/enterprise-service-assistant/knowledge_base_config.json

# 填入实际配置，例如：
# 本地文件：
# {
#   "source_type": "local",
#   "source_config": {
#     "file_path": "/path/to/your/园区数据.xlsx"
#   }
# }
#
# 腾讯文档：
# {
#   "source_type": "tencent_docs",
#   "source_config": {
#     "doc_id": "your-doc-id"
#   }
# }

4. 测试配置

# 不需要传config，自动从外部路径加载
# 测试读取
data = kb.get_all()
print(f"✅ 成功读取 {len(data)} 条数据")

5. 使用企服助手

配置完成后，AI会自动使用知识库模块读取数据。

🔧 脚本目录

所有Python脚本已内置在 scripts/ 目录：

重要变更：

• ✅ 去掉 knowledge_base.py 中间层
• ✅ 所有数据读取现在直接调用 MCP 工具（仅在缓存未命中时）
• ✅ 支持腾讯文档/IMA知识库/本地文件（通过MCP工具）
• ✅ 新增本地缓存机制（v2.3.0）——首次查询后缓存30分钟内复用，响应<0.1秒
• ✅ 新增快速模式——用户说「快速查询」即只读缓存，完全不调MCP

AI可以直接调用这些脚本，也可以根据本文档描述的逻辑直接用Python代码执行。

⚠️ 注意事项

1. Excel日期格式 — 需兼容多种格式：2025年3月1日、2025-03-01、datetime对象

2. 🔴 数据隐私（铁律） — 任何时候不得在用户可看到的输出或文件中暴露以下数据：

   • 具体项目名称（如"美兰中心""美慧城"）
   • 具体企业名称或租户名
   • 具体数据量（如"149家""1,244条"）
   • doc_id、文件路径等配置信息
   • 具体的缴费金额或逾期天数

   输出指南文件、使用指引、演示文案时一律使用泛化示例：

   • ✅ 「XX科技公司」「X栋X单元」「¥XX」
   • ✅ 「XX制造业」「XX实业」「XXX㎡」
   • ❌ 「上海洁韵信息科技」「T1-1103.05」「¥166,928」

3. 🛡️ 落库脱敏策略（v3.6.0 新增） — 本地 SQLite / 缓存 JSON 存储强 PII 时执行：

   • 存储级脱敏字段：电话 / 手机 → 落库即存 138****1234 形式；联系人姓名 → 存姓 + 首字（如 张*）；证件号 → 不落库
   • 原文保留字段：企业名 / 租户名、单元号、金额、日期（本地库不外发，输出过脱敏闸门即可）
   • 需要完整号码时：从腾讯文档源实时读取（只读同步，不写回），不依赖本地脱敏值
   • 同步时执行：腾讯文档 → SQLite 写入前，对电话 / 联系人字段做脱敏转换再落库
   • 现有存量库：下次同步时自动按此规则重建（全量覆盖前先过校验，失败不覆盖）

4. 关联字段一致性 — 单元号、租户名在各工作表中的格式必须一致

5. SLA超时升级 — 紧急工单超时必须立即@all通知

6. 库存月使用量为0 — 可用月数视为999（无限）

📌 版本历史

⚡ 性能优化建议（v2.3.0新增）

为什么之前慢？

现在快了多少？

推荐使用方式

最佳体验（推荐）：

1. 首次查询某张表 → 自动建立缓存（2-3秒）
2. 之后说「快速查询 XXX」 → 读缓存（<0.1秒）
3. 数据更新后说「刷新」 → 重新调MCP更新缓存

最快方式（适合高频查询）：

1. 配置本地文件模式（source_type: "local"）
2. 直接读取本地Excel/CSV文件（无需API调用）
3. 查询速度：<0.05秒

当前状态：v3.4 三大板块架构，覆盖16张腾讯文档工作表，支持本地缓存加速。可直接发布到ClawHub供其他用户使用。

📋 v3.1 输出规范

今日工作输出（按新格式）

今日工作（{n}）

━━━━━━━━━━━━━━━
● {企业名} — {事项类型}
  原因：{原因简述}
  建议：{建议动作}
━━━━━━━━━━━━━━━

排序规则：按工作紧急度排序。每次输出不超过10条。

企业情况输出（查询某家企业时统一使用）

━━━━━━━━━━━━━━━
企业情况 | {租户名}

━━━ 当前状态 ━━━
{状态简述}

━━━ 当前风险 ━━━
{风险清单 或 "无风险"}

━━━ 待办事项 ━━━
{待办清单 或 "无"}

━━━ 服务建议 ━━━
{建议清单 或 "无"}

━━━ 最近动态 ━━━
{按时间倒序的事件列表}

⚡ 操作链接：[腾讯文档]
━━━━━━━━━━━━━━━

企业情况不是企业所有资料，而是AI判断「办这件事需要知道什么」。五个元素顺序固定不可调换。

🔄 处理完成闭环（Completion Closure）

这是一个行为模块，不是一个独立页面。 你说「办完了」，我自动记录+刷新+更新。

触发词

六种事件类型

AI执行流程

用户说「办完了」或「处理完成」

Step 1 ── 解析上下文，判断事件类型
          ↓
Step 2 ── 调用 completion_tracker.py 处理
          ↓
Step 3 ── 写入本地 tracking/completion_log.json
          ↓
Step 4 ── 刷新三块状态：
          · 今日工作（移除已完成项，重新排序）
          · 企业情况（追加最近动态）
          · 事项跟进（更新对应状态）
          ↓
Step 5 ── 输出闭环反馈：
          ✅ {事件类型} · {企业名} 已处理完成
          📝 {详情}
          🔄 已自动执行：{动作列表}

本地记录文件

~/.workbuddy/workspace/enterprise-service-assistant/tracking/
├── completion_log.json   ← 所有完成记录 + 活跃任务缓冲区

completion_log.json 结构：

{
  "version": "1.0",
  "updated_at": "ISO时间戳",
  "completions": [
    {
      "id": "comp-2026062823-001",
      "type": "催缴完成",
      "unit_no": "T1-1103.05",
      "tenant_name": "上海洁韵信息科技有限公司",
      "details": "分期首款¥50,000已到账",
      "amount": 50000.0,
      "completed_at": "2026-06-28T23:10:00",
      "status": "completed",
      "actions_taken": ["update_fee_status", "remove_from_today", "refresh_enterprise"]
    }
  ],
  "active_tasks_buffer": {
    "催缴完成|T1-1103.05": {
      "status": "completed",
      "completed_at": "...",
      "completion_id": "comp-..."
    }
  }
}

刷新逻辑（AI执行）

当 completion_log.json 中有新完成记录时，AI在生成今日工作和企业情况时自动过滤已闭环项：

今日工作刷新规则：

今日工作输出前：
  读取 completion_log.json → 获取 active_tasks_buffer
  用 completed 项过滤今日工作列表
  输出剩余未完成项（最多10条）

企业情况刷新规则：

企业情况输出时：
  读取 completion_log.json → 获取该企业完成记录
  追加到「最近动态」列表（按时间倒序，带 ✅ 标记）
  刷新「当前风险」和「待办事项」

与MCP的配合（未来完善）

目前写入腾讯文档需要 sheet_id，当前实现：

• ✅ 本地记录 + 状态刷新（已就绪）
• 🔄 写入腾讯文档（需配置sheet_id后可启用）
• 🔄 企微推送通知（需配置webhook后可启用）

使用示例

用户：洁韵催缴搞定了，今天付了¥50,000首期款
  ↓
AI：✅ 催缴完成 · 上海洁韵信息科技有限公司 已处理完成
    📝 分期首款¥50,000已到账，剩余¥113,916分3期
    🔄 已自动执行：
      ✅ 更新费用状态
      ✅ 从今日工作移除
      ✅ 刷新企业情况
    
    现在今日工作剩余：8项（已移除洁韵的催缴任务）
    需要查看刷新后的今日工作吗？