企微社群运营实施记录

对应方案：qiwei-group-operations-product-development-spec.md
开始日期：2026-07-18
当前阶段：Phase 3 受控自动化底座已完成，真实自动发送保持关闭

状态说明

完成：代码已落地并通过对应本地验证。
进行中：已有实现，但仍缺集成或真实环境验证。
待开始：尚未开发。
受阻：需要真实账号、业务规则或外部权限。

已完成

2026-07-18

工作项	状态	产物/说明
产品与技术方案	完成	`docs/specs/qiwei-group-operations-product-development-spec.md`
`qiwei-group-operations` Skill 骨架	完成	主 `SKILL.md` + 数据模型、质检规则、输出契约三份渐进引用
Skill UI 元数据	完成	`skills/qiwei-group-operations/agents/openai.yaml`
社群运营 SQLite 数据层	完成	群主档、SOP/版本、计划/计划项、消息、质检、审计；所有业务表带 `account_key`
SOP 版本管理	完成	创建草稿、创建版本、发布、指定版本回滚、审计
每日运营计划	完成	从已发布 SOP 生成待审核计划，同群同日幂等，支持模板变量
计划项人工闭环	完成	批准、拒绝、跳过、标记人工已执行；真实自动发送保持关闭
确定性质检 MVP	完成	投诉/退款等风险词、客户问题超时未回应、稳定指纹去重、原消息证据
每日运营简报	完成	群数、已发布 SOP、今日任务、完成率、待审核、高风险和未闭环事项
MCP 工具	完成	新增 8 个工具：上下文、计划、话术、质检、简报、SOP、计划执行、质检处理
Dashboard API	完成	新增 `/api/group-ops/*` 读取、发布、计划、审核和质检处理接口
Dashboard MVP	完成	新增“社群运营”导航、运营指标、SOP、计划生成、今日工作台、质检预警
可访问性与响应式基础	完成	表单 label、按钮禁用态、键盘 focus、375px/平板布局、减少动态效果
本地 smoke 脚本	完成	覆盖账号隔离、SOP 发布、计划幂等、审核执行、风险质检和闭环
发布检查接入	完成	`release-check.js` 已加入 `group-ops:check` 与 `group-ops:smoke`
群消息兼容入库	完成	webhook 与历史同步成功落盘后，按设备 `guid` 兼容写入账号隔离的社群运营群/消息表；缺少 guid 时安全跳过新表

2026-07-18 · Phase 2

工作项	状态	产物/说明
按门店批量生成计划	完成	支持显式群列表或门店范围；逐群幂等，部分失败不回滚成功项
跨门店运营对比	完成	展示群数、今日任务、完成数、执行率、未闭环与高风险；无任务时显示数据不足
群活跃趋势与生命周期建议	完成	对比近 7 天与前 7 天消息、活跃成员、最近消息、风险，并给出可解释建议和覆盖率
整改任务主账	完成	质检项可创建整改任务，支持负责人、期限、优先级、状态和审计
企微官方待办衔接	完成	精确匹配内部成员且人工确认后创建真实待办；本地完成可同步官方完成状态
质检阈值配置	完成	账号级 SLA、风险词、禁止承诺配置并留审计；消息质检自动采用当前配置
误报反馈评测集	完成	`false_positive` 不删除历史结论，独立保存反馈记录并统计误报率
质量评测脚本	完成	`scripts/group-operations-quality-eval.js` 输出 precision/recall 并纳入发布检查
优秀话术沉淀	完成	从已执行且有最终内容的计划项汇总高频话术，不把未发送草稿计入
SOP 版本治理	完成	版本列表、结构差异、影响群/门店预览、指定版本发布和回滚
Dashboard 五视图	完成	运营总览、今日工作台、群洞察、SOP 版本、质检督导；移动端响应式与键盘焦点保持一致
Phase 2 MCP/API	完成	新增批量计划、运营洞察、整改任务 3 个 MCP 工具，总计 86 个；Dashboard API 完成对应闭环

2026-07-18 · Phase 3

工作项	状态	产物/说明
自动化策略版本	完成	策略草稿、不可变版本、人工激活、历史策略保留；激活后强制保持暂停
群与内容白名单	完成	只有显式 `allowedGroupIds` 和 `allowedTypes` 才能通过执行闸门
时间窗与灰度	完成	使用 Asia/Shanghai 判断星期和时间窗；按 roomId 稳定哈希命中灰度比例
单群频控	完成	单群每日、近 7 天发送上限，基于成功回执计数
内容与风险闸门	完成	未批准、未到时间、高风险未闭环、变量未替换、禁止承诺和重复发送全部拦截
幂等与回执	完成	保存幂等键、策略版本、决策、模式、状态、外部消息 ID、错误和完成时间
连续失败熔断	完成	达到策略阈值自动熔断；后续项目全部阻止，只能人工确认复位
一键暂停/恢复	完成	暂停立即生效；恢复必须人工确认；状态变化全量审计
dry-run	完成	支持预演和记录 dry-run，不调用 Fmode、不改变计划项发送状态
真实发送三重保护	完成	仅 `auto` 策略 + `execute=true/confirmed=true` + `QIWEI_GROUP_OPS_LIVE_SEND=1` 才可能调用 `/msg/sendText`
自动化 Dashboard	完成	新增策略、状态、白名单、时间窗、灰度、频控、熔断、预演、dry-run 和执行日志视图
Phase 3 MCP/API	完成	新增 `qiwei_group_ops_automation`，总计 87 个 MCP 工具
自动化专项测试	完成	覆盖暂停、白名单、灰度、时间窗、连续失败熔断、人工复位、dry-run 和真实发送阻断

2026-07-18 · 规格对照审查修复

工作项	状态	产物/说明
SOP 草稿与发布版本隔离	完成	创建新草稿不再停用当前已发布 SOP；生成计划只读取当前发布快照，实际话术与 `playbook_version_id` 保持一致
有效回应判定	完成	客户问题后的无关、寒暄或占位消息不再算有效回应；新增意图与关键词相关性规则，并支持后续有效回复自动闭环
质检时间范围	完成	消息质检支持 `startAt` / `endAt`，避免每次扫描全部历史消息
发送回执未知保护	完成	网络超时、连接重置等结果不确定场景记录为 `unknown`，在人工核对回执前锁住同一幂等键，避免自动重发
批次熔断即时生效	完成	每个发送项执行前重新计算安全闸门；批次中途触发熔断后，后续项目立即转为拦截
账号级增量消息同步	完成	每个企微账号只调用一次增量消息流，按 `fromRoomId` 分流到目标群；完整拉取后保存账号级 `travelSyncKey` 游标，分页未完成时不推进游标
SOP 发布/回滚确认	完成	MCP/API 必须显式传 `confirmed=true`；Dashboard 先展示影响范围并由用户确认
可解释群健康分	完成	新增每日评分表，按 SOP、响应、风险、互动分项计算；缺少数据时排除对应权重并展示覆盖率、分项证据量和健康分布
审查回归测试	完成	新增未发布草稿隔离、版本审计一致性、无关/有效回复、回执未知锁定、健康分覆盖率和发布确认测试
RBAC 权限框架与模拟验收	完成	新增总部管理员、区域经理、门店经理、执行员工、只读审计者角色；支持账号级 `userId` 绑定与门店范围；新增角色管理 MCP，当前总计 88 个 MCP 工具；覆盖首次初始化、跨门店拒绝、非总部发布 SOP 拒绝及审计者执行拒绝

进行中

工作项	状态	剩余内容
Phase 0 账号隔离	进行中	新模块数据已隔离；旧 `outputs/groups/*` 和历史消息路径仍需迁移为账号目录
真实样本质量评测	进行中	评测脚本与内置回归集已完成；仍缺 1,000 条脱敏消息和业务人员阈值校准

受阻或需业务确认

工作项	状态	阻塞条件
真实自动群消息发送	受阻	`/msg/sendText`、`/msg/sendGroupMsg` 需真实账号完成回执、频控、超时幂等 smoke
20 群连续试点	受阻	需要确定 3 家门店、20 个授权客户群及负责人
公司级正式 SOP	受阻	需要业务方提供或审核群类型、服务 SLA、禁用词、升级人工规则和首批话术
正式角色映射	受阻	权限框架与模拟测试已完成；需要提供真实总部、区域、门店、审计者的 `userId` 及门店范围后才能启用生产绑定
数据保留与合规	受阻	需要确认群消息保留期限、脱敏范围和内部授权
官方待办 live smoke	受阻	同步逻辑与人工确认保护已完成；需要已初始化的企微官方 CLI 和测试成员完成真实创建/完成验证

后续开发顺序

把 webhook 和历史同步改为“账号级一次增量拉取，按 roomId 分流入库”。
为旧群列表、确认映射和消息缓存增加账号命名空间及迁移脚本。
完成真实发送接口 smoke 后，仅对白名单和人工批准项开放发送。
用 1,000 条脱敏消息扩充评测集，校准投诉与未回应识别阈值。
用真实企微官方 CLI 完成整改待办创建和完成状态 live smoke。
开展 20 群、14 天真实试点并在本文件记录指标。

验证记录

日期	验证	结果
2026-07-18	`npm run group-ops:check`	通过
2026-07-18	`npm run group-ops:smoke`	首次发现消息表占位符错误，修复后通过
2026-07-18	Skill `quick_validate.py`	通过；`Skill is valid!`
2026-07-18	`npm run check`	通过
2026-07-18	Dashboard 本地 HTTP smoke（4322）	`/api/group-ops/overview` 返回 `ok`，首页包含 `group-ops` 导航
2026-07-18	`npm run package:smoke`	通过；18 skills、83 MCP tools、0 forbidden files
2026-07-18	`npm run release:check`	最终通过 11 组发布检查；同步修复 webhook 旧测试期望、Relay 测试隔离、画像 Excel 复用现有导出组件及输出目录 manifest 基线
2026-07-18	Phase 2 `npm run group-ops:smoke`	通过；覆盖 SOP v2/影响预览/回滚、门店批量计划、配置、反馈、整改任务、群洞察和优秀话术
2026-07-18	`npm run group-ops:eval`	通过；内置 4 个规则样本，precision=1、recall=1，仅作为回归测试，不代替真实评测集
2026-07-18	Phase 2 Dashboard 隔离 API smoke	通过；SOP 创建/预览/发布、计划、质检设置、整改任务、门店和群洞察全部返回 `ok`
2026-07-18	Phase 2 Skill `quick_validate.py`	通过；`Skill is valid!`

2026-07-18 · 当前登录账号 live smoke

验证	结果
Fmode 设备登录	通过；设备在线，状态码 2
包月订阅	通过；1/1 席位已使用，订阅有效，自动续费开启
自建外部群读取	通过；读取 6 个外部群，接口无错误
群分类缓存	通过；4 个 `IMPORTED`、2 个 `SUGGESTED`，未自动确认真实客户群
单群详情分析	通过；候选群详情可读，保持 `SUGGESTED`，未误改为已确认
单页历史消息同步	接口通过；所选群本页新增 0 条，因此本次未验证真实消息质检样本
企微官方待办 live smoke	未执行；当前官方 CLI 尚未安装、未授权

本次 live smoke 只执行读取、分析和本地缓存更新，没有发消息、建群、修改群资料或创建真实企微待办。

2026-07-18 · Phase 3 自动化验证

验证	结果
`npm run group-ops:smoke`	通过；策略、暂停、时间窗、灰度、频控、三次失败熔断和人工复位通过
`npm run group-ops:auto-smoke`	通过；dry-run 不调用真实网关，环境开关关闭时真实执行被强制阻断
Phase 3 Dashboard 隔离 API smoke	通过；激活后 `paused=1`、人工恢复后 `paused=0`、预演通过 1 项、dry-run 1 项、真实执行被环境开关阻断
当前真实发送开关	`QIWEI_GROUP_OPS_LIVE_SEND` 未开启，未向当前登录账号的任何群发送测试消息
`npm run release:check`	通过 12 组发布检查；18 个 Skills、87 个 MCP 工具、148 个打包条目、0 个禁入文件