商机管理（Opportunity Pipeline）
概述
在 WorkBuddy 中管理商机管线。核心数据模型是三张关联表：商机管线（主表）、客户档案（客户维度）、跟进记录（时间线维度）。配套工作日每日 09:00 待跟进商机自动提醒。
存储后端（二选一，由用户决定）：
- 腾讯文档智能表格（在线协作、手机端可看、支持企业微信提醒）—— 既有方案
- 本地 Excel 文件（离线、三 sheet 存于工作空间）—— 备选方案
两种后端的字段模型一致，仅在 I/O 方式与日期/下拉的存储格式上有差异（见下文「存储后端差异与操作路由」）。
何时使用
- 用户说「记录一个商机」「新增商机」「录入跟进」「商机进展」「查看商机统计」「查询商机」「更新商机阶段」「复盘报告」等。
- 用户要求设置商机每日待跟进提醒。
- 用户在某工作空间首次管理商机（走初始化流程，并选择存储后端）。
配置优先原则
执行任何操作前，先读取当前工作空间的 .workbuddy/pipeline_config.md：
- 若文件存在且含
storage与对应后端的连接信息，直接使用这些配置值操作，不要再询问用户。 - 若文件不存在（工作空间首次使用），执行初始化流程：先问用户选哪种存储后端，再据此建表并写入配置。
存储后端差异与操作路由
| 操作 | 腾讯文档（tencent） | 本地 Excel（local） |
|---|---|---|
| 环境检查 | cd <skill_dir> && python3 tencentdocs.py tdoc_init |
python excel_ops.py --help |
| 新增记录 | python3 tencentdocs.py tdoc_call tencent-docs smartsheet.add_records '[json]' |
python excel_ops.py add --path <xlsx> --sheet <sheet名> --json '{...}' |
| 更新记录 | python3 tencentdocs.py tdoc_call tencent-docs smartsheet.update_records '[json]' |
python excel_ops.py update --path <xlsx> --sheet <sheet名> --id <记录ID> --json '{...}' |
| 读取记录 | python3 tencentdocs.py tdoc_call tencent-docs smartsheet.list_records '[json]' |
python excel_ops.py list --path <xlsx> --sheet <sheet名> |
| 查字段定义 | python3 tencentdocs.py tdoc_schema tencent-docs smartsheet.<tool> |
列名为字段定义 |
| 日期字段 | 毫秒时间戳（string_value），UTC+8 |
Excel 日期单元格（yyyy-mm-dd），传 YYYY-MM-DD 或毫秒时间戳均可 |
| 单选字段 | option_value:{items:[{id:"xxx",text:"选项名"}]} |
纯文本单元格（已加下拉数据验证） |
| 参考字段 | reference_value:{items:["<record_id>"]} |
纯文本（填关联商机的记录ID） |
| 记录标识 | 腾讯自动 record_id |
内置 记录ID 列（R0001...） |
> 腾讯文档智能表格调用入口（tencentdocs.py）位置见配置文件的 tdoc_skill_dir。该脚本需要先 tdoc_init 确认 READY 才能调用工具。
> 本地 Excel 后端操作一律走本 skill 的 scripts/excel_ops.py（openpyxl，自动安装依赖）。
三表结构与字段
完整字段定义见 references/field_spec.md。
商机管线（Pipeline）— 主表
记录每条商机的核心信息：商机名称、客户名称、客户决策链、产品方案、所属区县、商机阶段、赢率、优先级、商机来源、负责人、下次跟进时间、下次跟进责任人、商机复盘、备注、客户类型。
商机阶段字段为文本类型（非单选），可选值：线索发现 → 初步接触 → 需求确认 → 方案设计 → 方案报价 → 商务谈判 → 成交 → 交付中 → 已回款；终止态：已丢单。
客户档案（Customer Profile）
客户维度信息：客户名称、联系人、职务、关键决策人、所属区县、客户类型、主要业务、合作状态、备注。
跟进记录（Follow-up Records）
时间线维度记录、通过「关联商机」字段关联到商机管线：关联商机、跟进日期、跟进主题、跟进方式、跟进人、接触对象、跟进内容、客户信号、阶段变更、下次跟进时间、下次跟进责任人、风险提示、备注。
字段格式踩坑（仅腾讯文档后端，关键——格式错会静默丢数据）
腾讯文档智能表格各字段类型要求特定的值包裹格式：
- dateTime 字段（跟进日期 / 下次跟进时间）：必须用
string_value传毫秒时间戳（UTC+8）。不要传文本，否则会被静默丢弃。
计算：
bash python3 -c "from datetime import datetime,timezone,timedelta; tz=timezone(timedelta(hours=8)); print(int(datetime.strptime('YYYY-MM-DD','%Y-%m-%d').replace(tzinfo=tz).timestamp()*1000))" - singleSelect 字段（跟进方式 / 客户信号 / 阶段变更）：用
option_value:{items:[{id:"xxx",text:"选项名"}]}。若不确定 id，先用list_fields查实际选项。 - reference 字段（关联商机）：用
reference_value:{items:["<record_id>"]}。 - text 字段（大部分字段）：用
text_value:{items:[{text:"...",type:"text"}]}。 - url 字段（商机复盘）：用
url_value:{items:[{text:"复盘报告",type:"url",link:"https://..."}]}。
> 本地 Excel 后端无需上述格式：日期直接传 YYYY-MM-DD 或毫秒时间戳、单选直接传文本字符串即可（由 excel_ops.py 处理）。
腾讯文档调用方式（重要——避免 DeferExecuteTool 不可用问题）
本技能使用腾讯文档插件自带的 tencentdocs.py 脚本调用 MCP 工具，而非 DeferExecuteTool（新会话中这些工具可能不在 deferred index 中）。
skill 目录（tdoc_skill_dir）示例：
C:\Users\geodo\AppData\Local\Programs\WorkBuddy\resources\app.asar.unpacked\resources\builtin-plugins\tencent-docs-plugin\skills\tencent-docs
调用前检查环境：
cd "<tdoc_skill_dir>" && python3 tencentdocs.py tdoc_init
# READY → 可调用工具
# ERROR:no_token → 提示用户在 WorkBuddy 中完成腾讯文档授权
调用工具：
cd "<tdoc_skill_dir>" && python3 tencentdocs.py tdoc_call tencent-docs smartsheet.<tool> '[json_args]'
查参数定义：
python3 tencentdocs.py tdoc_schema tencent-docs smartsheet.<tool>
为避免命令行 JSON 嵌套引号问题，参数应先写入临时文件再通过 cat 传入：
cd "<tdoc_skill_dir>" && python3 tencentdocs.py tdoc_call tencent-docs smartsheet.add_records "$(cat '/path/to/temp_args.json')"
日常操作（后端无关，按上表路由）
新增商机
- 收集信息：商机名称、客户名称、决策链、产品方案、商机来源、当前阶段、优先级等。
- 组装「商机管线」记录 → 按后端路由写入。
- 同步录入对应「客户档案」记录（新建客户时）。
- （可选）录入第一条「跟进记录」。
录入跟进记录
- 确认关联商机的
record_id（腾讯文档）或记录ID（本地 Excel）。 - 组装跟进记录字段：关联商机、跟进日期（时间戳）、跟进主题、跟进方式、跟进人、接触对象、跟进内容、客户信号、阶段变更（如有）、下次跟进时间（如有）、风险提示。
- 写入跟进记录。
- 若有阶段变更或下次跟进时间变更，同步更新商机管线主表的对应字段。
更新商机阶段 / 下次跟进时间
更新商机管线主表的「商机阶段」「赢率」「下次跟进时间」等字段。日期字段必须用时间戳（腾讯文档）。
查询商机统计
读取所有商机管线记录 → 按阶段/优先级汇总，标注待跟进项。
生成复盘报告
- 读取该商机的所有跟进记录（按「关联商机」筛选）。
- 整理时间线、分析丢单原因、提炼教训。
- 创建腾讯文档在线文档（
create_file）或本地 Markdown，填入复盘内容。 - 将复盘报告链接更新到商机管线的「商机复盘」字段（url 类型）。
初始化流程（工作空间首次使用）
仅当 .workbuddy/pipeline_config.md 不存在时执行：
- 询问用户选择存储后端：腾讯文档 还是 本地 Excel。
- 若选腾讯文档：
- 确认
tencent-docs连接器已连接（若断开，提示用户重连）。 tdoc_init确保环境 READY。manage.create_file(file_type="smartsheet", title="商机管理")→ 得file_id。list_tables(file_id)→ 得三个 sheet_id。- 按
references/init_prompt.md第 1 节的 JSON 为三个 sheet 分别添加字段。 - 清理默认空行与默认列。
- 若选本地 Excel：
- 运行
python <skill目录>/scripts/excel_ops.py init --path "<工作空间>/商机管理表.xlsx" - 三 sheet（商机管线 / 客户档案 / 跟进记录）自动创建，含表头与下拉验证。
- 写入
.workbuddy/pipeline_config.md（模板见references/init_prompt.md第 2 节）。 - 询问用户是否创建自动化：工作日每日 09:00 待跟进商机提醒 → 企业微信（需提供 userid）。
自动化
工作日每日 09:00 待跟进商机提醒（RRULE: FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=1;BYMINUTE=0）
你是商机管理助手。请执行以下步骤：
0. 读取 .workbuddy/pipeline_config.md，确认 storage 及连接信息。
1. 读取商机管线的所有记录。
2. 筛选待跟进商机：「下次跟进时间」不为空且日期 ≤ 今天，且「商机阶段」不是「已丢单」或「已回款」。
3. 如果有待跟进商机，生成简洁提醒消息并发送给负责人。
4. 如果没有，静默结束。
自动化 prompt 需根据实际 storage 后端调整读取方式（tencent 走 tdoc_call list_records，local 走 excel_ops.py list）。
资源文件
references/field_spec.md— 三表完整字段定义、类型与写入格式、时间戳计算、本地 Excel 列布局。references/init_prompt.md— add_fields 完整 JSON（三个 sheet）、pipeline_config.md 模板、本地 Excel 初始化命令、已知实例配置。scripts/excel_ops.py— 本地 Excel 后端 CLI 工具（init/list/add/update/delete），三 sheet 结构，依赖 openpyxl（自动安装）。
