支付通道商户认证状态批量查询与回填
本技能将"登录聚合支付后台 → 逐户查询商户各支付通道微信/支付宝认证状态 → 生成认证状态表回填总表"的全流程封装为可复用脚本与标准 SOP。适用于收银软件/聚合支付运营中，需要对一大批商户（数百~数千户）批量核验认证状态并回填到腾讯文档总表的场景。
适用场景（触发条件）
- 用户给出腾讯文档总表链接 + 指定查询/输出列 + 筛选条件 + 当日验证码
- 典型指令："查询某总表的认证状态，D列=商户号，M列=通道，R列=授权情况，除已授权以外的都查一遍"
- 涉及通道：随行付、易宝、乐刷、扫呗国通（由
config/channels.json配置，新增通道只需加一条，无需改代码）
输入（Inputs）
| 输入 | 说明 | 示例 |
|---|---|---|
| 腾讯文档 file_id | 文档 URL 中 /sheet/Dxxxx 部分 |
TMgPRoAkYdaf |
| 工作表 sheet_id | URL 中 ?tab=xxxx 部分 |
s9vpbm / BB08J2 |
| 列映射 | 商户号列、支付通道列、输出列（0-based 列号或 A1 列字母） | 商户号=D(3)、通道=M(12)、输出=R(17)；或微信X(23)/支付宝Y(24)分列 |
| 筛选条件 | 从总表筛出待查候选的规则 | "除微信和支付宝均已授权以外的户" |
| 候选范围 | 归属人/行数等口径确认 | 蔡念耕名下 543 行 → 非已授权 406 户 |
| 短信验证码 | 用户在管理员后台触发后提供，当日有效、限频 | 950666 |
| 后台登录凭据 | 通过环境变量 AUTH_USERNAME/AUTH_PASSWORD 注入（或 --username/--password），代码中无明文 |
详见「运行边界、权限与凭据声明」 |
输出（Outputs）
- 本地独立 CSV：
认证状态_查询.csv（字段：乐檬商户号、归属代理商、查询通道、微信认证状态、支付宝认证状态、备注）——核心交付物，供用户用 VLOOKUP 按商户号回填总表对应列。 - 结果 JSON：
auth_query_results.json（每户户_v版本号 +note终态标记 +elapsed单户耗时），用于断点续跑与成本测算（量化自动化节省工时），无需人工干预。 - 可选在线子表：当总表被"保护选定范围"锁定无法直接写回时，新建在线子表存放结果（绕过锁定），用户再 VLOOKUP。
执行步骤（Execution Steps）
- 接收参数：确认 file_id / sheet_id / 列映射 / 筛选条件 / 候选范围。
- 导出候选：用腾讯文档 MCP（
tdocs-app）读取指定 sheet 的候选行，按列映射提取（商户号、通道、归属），按筛选条件过滤，导出candidates.csv（字段：doc_row, merchant_id, agent, channel）。参考references/workflow-details.md的列映射表。 - 链路验证（强烈建议）：取每通道各 1 户（随行付/易宝/乐刷/扫呗国通）共 4 户，先跑
--limit验证后台能正常读取各通道状态（确认卡片名匹配、状态字段可读）。 - 触发验证码：运行
python3.11 scripts/send_captcha.py（在管理员登录页真实点击"获取验证码"触发短信）；用户收码后提供。 - 批量查询：
python3.11 scripts/auth_query_driver.py --captcha <码> --candidates candidates.csv，逐户登录后台查询（每 10 户落盘，幂等 resume）。 - 自动续跑 + 抗中断：
bash scripts/autorun.sh <码> /workspace/candidates.csv循环 resume；沙箱清理进程后重拉；检测到验证码过期写/workspace/_NEEDCAPTCHA_auth并停。 - 过期处理：若写
_NEEDCAPTCHA_auth，暂停并向用户请求新验证码，收到后重新运行 autorun。 - 完成检测：
python3.11 scripts/check_complete.py --candidates candidates.csv确认终态数 == 候选数。 - 交付：生成最终
认证状态_查询.csv（核心交付物）。 - 受控回填（破坏性操作）：若需写回总表，先用 MCP 导出目标列当前值 →
backfill_tool.py plan生成写入计划+备份快照 → 灰度写前 5 户核对 → 全量；异常用rollback恢复。严禁无备份/无灰度直接全量写回。 - 沉淀记忆（持久记忆）：任务结束把本次新增口径、通道特性、坑写入
memory/MEMORY.md（memory_store.py add），供后续任务recall主动调用。 - 标记完成 / 定时（可选）：完成时
bash mark_done.sh <task>记录日期；如需周期性刷新，bash setup_cron.sh注册定时自检（工作日到点自检+自动触发发码+提醒）。
运行边界、权限与凭据声明
本技能的能力范围（含补齐的三项：破坏性操作 / 持久记忆 / 定时任务），便于安全评审与权限控制：
能力清单
| 能力 | 包含 | 安全约束 |
|---|---|---|
| 读文件 | ✅ 有 | 读取候选 CSV、断点续跑 JSON |
| 写文件 | ✅ 有 | 本地落盘结果 JSON / 认证状态 CSV / 本地标记（不直连改写远端） |
| 联网 | ✅ 有 | Playwright 访问聚合支付后台；腾讯文档 MCP 读写 |
| 浏览器自动化 | ✅ 有 | 登录、点击获取验证码、逐户检索查询 |
| 破坏性操作 | ✅ 受控 | 写回总表经 backfill_tool.py 三道防线：①备份快照 ②灰度预览(前5户) ③回滚指令；实际写入由 agent 用 MCP 逐行执行 |
| 写入持久记忆 | ✅ 有 | memory_store.py + memory/MEMORY.md 跨任务沉淀，后续 recall 主动调用 |
| 定时任务 | ✅ 有 | setup_cron.sh 注册 crontab；cron_check.sh 到点自检+自动触发发码+提醒；mark_done.sh 记录日期 |
权限（已在 frontmatter allowed-tools 声明）：bash（执行脚本）、browser（Playwright 登录/查询）、mcp__tdocs-app（读写字档）、read/write/edit（本地文件）。
凭据安全（不硬编码）：后台账号密码 经环境变量 AUTH_USERNAME/AUTH_PASSWORD 注入（或 --username/--password 传入，优先于环境变量），代码中无明文。工作目录默认 /workspace，可 export WORK_DIR=/your/path 覆盖，便于跨环境移植。
使用条件（Preconditions）
- 运行环境：Python 3.11 + Playwright(chromium)，能访问聚合支付后台域名
allpay-earth-client.lemengcloud.com。 - 已连接腾讯文档 MCP（
tdocs-app）用于读取/写回总表。 - 拥有有效管理员账号与短信验证码获取权限（验证码当日有效、限频，需现场触发，不可臆测旧码仍有效）。
- 候选商户号与通道可从总表明确提取；支持通道由
config/channels.json配置（随行付/易宝/乐刷/扫呗国通为内置默认），新增通道只需在配置加一条，无需改代码。 - 单户查询约 6–8 秒，数百户需预留数十分钟并启用自动续跑。
已知坑（必读）
- 多通道终态识别：原 base 的
TERMINAL_NOTES仅含随行付/扫呗；易宝/乐刷/扫呗国通的"无X通道/审核驳回"必须靠通用正则is_terminal识别（已固化在auth_backfill_base.py，勿删）。 - 发送验证码必须用真实鼠标坐标点击（JS click / dispatchEvent 无效），并通过监听
sms.send接口 + 按钮倒计时确认下发（见send_captcha.py）。 - 总表单元格保护锁：部分单元格被"保护选定范围"锁定，写入静默丢弃；方案是新建在线子表（商户号统一存数字、严格校验），绕过锁定。
- 沙箱进程清理：约每 7–10 分钟清理后台进程，必须靠幂等落盘 +
autorun.sh重拉，不能一次性前台跑完大批量。 - 验证码时效：跨天必失效；过期后脚本自动停，需用户重发，不能臆测旧码有效。
- 字段读取失败：偶发（
字段读取失败(wx=空, ali=...)），属可重试非终态，结束后可--force对非 OK 户单独重查。
脚本清单（scripts/）
查询主链路
- auth_backfill_base.py：通用底座（登录/查询/落盘/通用终态/写回文档）。勿改核心查询逻辑。
- auth_query_driver.py：通用驱动（读候选→查询→落盘→写 CSV），参数化所有路径与列。
- send_captcha.py：触发管理员登录页"获取验证码"（真实坐标点击，已验证可靠）。
- autorun.sh：自动续跑包装器（resume + 完成/过期检测）。
- check_complete.py：完成度检测（终态数 == 候选数）。
破坏性操作（受控回填）
- backfill_tool.py：生成写入计划 + 备份快照（plan）、回滚指令（rollback）；实际写入由 agent 用 MCP 逐行执行。
持久记忆
- memory_store.py：跨任务记忆库（init/add/recall/list），沉淀到 memory/MEMORY.md。
定时任务
- setup_cron.sh：注册 crontab 定时自检。
- cron_check.sh：到点自检（超阈值自动触发发码 + 写待补码提醒）。
- mark_done.sh：标记任务完成日期（供定时判定有效期）。
评测（运行期自检）
- self_eval.py：用真实落盘数据真实调用核心函数（is_terminal / 通道配置化 / resume 幂等），产出 eval_report.md + eval_report.json，填补静态评估中"需真实 agent 运行评估"的运行期项。
测试 / 示例 / 授权
- tests/test_core.py：核心函数离线单测（is_terminal 终态识别、normalize_channel/channel_aliases 配置化、build_record 的 elapsed 透传、resume 跳过逻辑），python3.11 -m unittest tests.test_core -v 运行，无需联网。
- examples/：即开即用示例数据（candidate_example.csv 输入模板 + output_example.csv 输出模板 + README.md 最小验证命令），便于新环境快速验证链路。
- LICENSE：MIT 许可证，来源可信、可商用/二次分发。
详细 SOP、列映射示例、字段口径、历史坑案例，以及"受控回填/持久记忆/定时任务"三节专题见 references/workflow-details.md。
