wecom-smartsheet-webhook

name	wecom-smartsheet-webhook
description	企业微信智能表格「接收外部数据」Webhook 的 AI 执行 skill。用于复用或建立网页登录态，抓取当前表真实 schema/记录，自动解析当前工作表已绑定 webhook，并在 schema drift guard 保护下安全推送。

企业微信智能表格 Webhook

什么时候用

• 需要从企业微信文档网页当前运行态获取真实字段、列类型、记录或已绑定 webhook。
• 需要通过“接收外部数据” webhook 做 dry-run、正式写入或写后回读验证。
• 需要在 cookie 复用、企微快速登录、二维码登录之间按顺序回退。

读取顺序

• 默认只读 references/playbook.md。
• 需要默认执行路径、官方事实、已验证事实时，再读 references/workflow-and-facts.md。
• 需要处理 schema drift、guard、字段支持边界时，再读 references/schema-guard.md。
• 需要在多个脚本入口之间选型时，再读 references/script-entrypoints.md。
• 只有老板在问能力边界、能做什么/不能做什么时，再读 references/limits-and-boundaries.md。
• 只有复杂字段值格式拿不准时，再读 references/field-value-cheatsheet.md。

最少向老板索取什么

• 必要时只索取：智能表格链接、目标动作（只读 / dry-run / 正式推送）、待发送 payload 来源。
• 不要向老板索取列名、字段类型、字段 ID、已绑定 webhook 地址；这些默认都应从当前页面运行态自动获取。
• 若本地没有 guard，正式写入前默认先生成 guard 并中止本次写入；只在老板明确要求时才无 guard 硬推。
• 若信息已在当前目录文件或对话里给出，默认直接复用，不重复追问。

不变约束

• 一律走 Webhook，不把服务端 API 当备用方案。
• 真实字段与类型只从当前页面运行态获取，不靠右侧示例数据猜。
• values 的 key 默认使用字段 ID，不依赖字段标题。
• 已有脚本和默认协议能覆盖时，不要临时发明新流程。
• 项目目录里若已有 smartsheet-schema-guard.json，默认必须启用 guard 校验。
• 发现类型变化、必需字段缺失、标题歧义、unsupported 字段时，先中止推送并汇报差异。
• 不要把真实 webhook 地址写进仓库、截图或公开输出。

默认三段流程

1. 建立登录态：先复用本地会话缓存；失效时再尝试企业微信快速登录；再不行才二维码登录。
2. 抓真实状态：读取当前激活工作表的真实 schema、记录和已绑定 webhook，不依赖页面示例数据。
3. 守卫后写入：若当前目录没有 smartsheet-schema-guard.json：
   • dry-run 可继续，但应优先生成 guard
   • 正式写入默认先自动生成 guard，再中止本次写入
   • 只有老板明确要求时，才允许无 guard 正式写入
4. 若已有 guard，则自动加载并校验 drift。
5. 正式同步默认走 scripts/sync_smartsheet_webhook.py；若未显式提供 webhook，默认只解析当前激活工作表已绑定的“接收外部数据” webhook。
6. 若 payload 里的旧字段 ID 在当前表失效，但 guard 中能按标题唯一映射，默认允许按标题自动重绑。
7. 正式写入成功后，默认执行回读验证；无回读验证不判成功。

立刻中止并汇报

• 无法建立可用登录态。
• 页面存在多个工作表，但无法唯一判定当前激活工作表。
• 当前表未绑定 webhook，或绑定了多个且无法自动判定目标。
• guard 报告出现 tableIdentityDrifts、typeDrifts、missingRequiredFields、ambiguousTitleMatches、unsupportedPayloadFields、payloadFieldIdCollisions。
• 没有 guard 且老板未明确允许无 guard 正式写入。
• webhook 接口返回成功，但回读验证失败。
• 需要更新的记录不是由 webhook 写入。
• 当前表包含当前脚本未稳定覆盖的字段类型，而 payload 仍试图写入这些字段。
• 当前问题已经超出脚本支持的字段类型或页面结构。

脚本选择

• 遇到环境、依赖、Chrome、session cache 可用性问题时，先跑 scripts/doctor.py。
• doctor.py 与主写入结果会显式给出 loginPath、tableResolutionState、webhookResolutionState、blockingCodes，优先读这些机器可读状态，不要靠异常文案猜。
• 默认入口：scripts/sync_smartsheet_webhook.py
• 其他入口与短命令见 references/script-entrypoints.md。