WorkBuddy 体验官反馈收集器

目的

让每位安装了 WorkBuddy 的员工（个人版 / 企业版均可），在日常任意任务对话中随手把「使用痛点、希望自动化的诉求、优化建议」结构化地收集到企业统一的腾讯文档在线表格里，无需跳出当前工作流、无需重复填身份信息。

何时触发

当员工在对话中表达“提交/记录一条反馈或需求”的意图时触发，例如：

• “反馈一个需求”“提个诉求”“记录一下这个痛点”“收集反馈”“提交体验反馈”“feedback”
• “刚才这个场景我希望能自动化……”“这里 WorkBuddy 做得不够好，我想反馈”
• 员工在完成某个任务后感慨“这个要是能一键就好了”，可主动询问是否记录为一条反馈

也支持员工主动要求“配置/重新设置反馈收集”（重新录入姓名、部门、文档链接）。

整体流程（决策树）

触发技能
  │
  ├─ 1. 读取本地配置（scripts/config.py get）
  │      ├─ 未初始化(exit 2 / 缺必填) → 走【首次安装引导】录入并保存
  │      └─ 已初始化 → 直接使用姓名/部门/文档链接
  │
  ├─ 2. 收集本条反馈字段（见 references/fields.md）
  │      └─ 必填字段缺失 → 逐项【追问补全】，直到 4/5/6 齐全
  │
  ├─ 3. 写入腾讯文档（见 references/tencent-docs-write.md）
  │      ├─ 动态发现腾讯文档写入工具 → 读表头对齐 → 追加一行
  │      └─ 无可用连接器 → 【降级】输出可粘贴文本 + 文档链接
  │
  └─ 4. 回执：确认已收集 + 摘要本条反馈关键字段

1. 首次安装引导（仅首次 / 或用户要求重设时）

先运行本地配置读取：

python3 scripts/config.py get

• exit code 2 或缺少 name/dept/doc_url → 说明尚未初始化。
• 此时向员工说明这是一次性设置，并逐项收集（一次问全，员工没答全就追问缺的那项）：
  1. 员工姓名
  2. 部门或中心名称
  3. 企业统一收集反馈的腾讯文档在线链接（形如 https://docs.qq.com/sheet/xxxx）

收集齐后写入本地配置（值含空格务必用引号）：

python3 scripts/config.py set --name "张三" --dept "海外电商中心" --doc-url "https://docs.qq.com/sheet/xxxx"

保存成功后告知员工：身份信息已记住，以后反馈无需再填姓名和部门，直接说要反馈的内容即可。然后继续进入第 2 步收集本条反馈。

配置为纯本地 JSON（~/.workbuddy/feedback-collector/config.json），只存姓名、部门、文档链接，不含任何密钥。员工换文档或调岗时可随时用 config.py set 局部更新对应项。

2. 收集本条反馈字段

字段定义见 references/fields.md。需向员工收集的字段（姓名、部门自动来自配置，无需再问）：

追问原则：

• 一次对话中员工往往只说了痛点，未说场景分类/预计效果 —— 必须逐项追问补全必填字段，一次问 1–2 项，语气自然不轰炸。
• 员工已经在描述里隐含了某字段（如场景很明显）时，可先复述你的归类让员工确认，不必机械重问。
• 员工对“衡量方法”表示没有/想不到 → 直接填「暂无」，进入写入。
• 备注、截图为选填：不强行索取；但收集必填项时可自然带一句“如果有相关截图，直接发给我即可，我会一并存进去”。员工发了图就走嵌图流程，没发就留空。

3. 写入腾讯文档

详见 references/tencent-docs-write.md。要点：

1. 动态发现工具：用工具搜索查找当前会话可用的腾讯文档写入能力（个人版 tencent-docs / 企业版 tencent-docs-oa 工具名不固定），拿到真实 schema 后按 schema 传参执行，绝不臆造参数。两个账号都连接时，按 doc_url 归属选账号；判断不了就让员工选。
2. 字段按表头名称对齐（不按固定列序）；表头为空则先写标准表头再写数据行。标准表头含末尾两列「备注」「截图」。
3. 提交时间用 shell 生成，禁止手算：date "+%Y-%m-%d %H:%M"。
4. 先写文本行：[提交时间, 姓名, 部门, 场景分类, 痛点描述, 预计优化效果, 衡量方法/「暂无」, 备注]，追加到表格末尾，并记住该行 row_index。
5. 再嵌截图（若员工发了图）：读取员工在对话中粘贴的本地图片路径 → 小图走 base64、较大图先 upload_image 拿 image_id → 用 sheet.insert_image 把图嵌入该行「截图」列单元格。详见 references/tencent-docs-write.md 第 4 步。

4. 降级方案（未装/未授权腾讯文档连接器）

不报错终止。改为输出制表符分隔的一行 + 可读清单，附上文档链接，让员工手动粘贴到表格末尾；并顺带提示可安装并 Trust 腾讯文档连接器以后自动写入。细节见 references/tencent-docs-write.md。

5. 回执

写入（或生成可粘贴文本）后，向员工简要回执：确认已收集第 N 条反馈 + 摘要 { 场景分类 / 痛点一句话 / 是否含截图 }，并询问是否还要再提一条。

资源

• scripts/config.py —— 本地配置读写（get / set / path）。首次引导与每次触发前读取身份信息。
• references/fields.md —— 字段 schema、必填/选填、场景分类建议值、字段灵活变化的处理原则。
• references/tencent-docs-write.md —— 腾讯文档写入的动态发现流程、表头对齐、标准表头、截图上传与单元格嵌图、降级方案。