跳转至

维护者快速使用说明

  • 项目名称：携游数据管家
  • 当前阶段：ACCEPTANCE
  • 当前目标：以 crawler4j module 形态完成账号数据域、三类对外 workflow 收口、模块首页统计 Dashboard 与账号管理 UI 正式接入，并完成技术验收。

新协作者先读什么

  1. AGENTS.md / GEMINI.md
  2. .factory/project.json
  3. .factory/memory/agent-session.md
  4. .factory/memory/current-state.md
  5. 本目录下的运维手册和追踪矩阵

后续怎么和 AI 协作

  • 修缺陷时说：新增一个 BUG，先分析影响，再同步代码、测试、文档和 AI 记忆。
  • 加需求时说：新增一个 CR，先补需求和设计，再进入实现。
  • 不确定下一步时说：先生成 agent session 和 state doctor，再告诉我最合适的下一步。

维护边界

  • 以当前真实实现状态为准，不把项目当成新项目重做。
  • 缺陷走 BUG-*，需求走 CR-*，治理补齐走 TASK-*。

当前配置入口

  • workflow 现在只暴露 3 个对外入口：login_workflow、auto_ctrip_login_workflow、web_quiz_workflow。
  • 模块运行参数统一由宿主模块详情页的“模块配置 / Workflow 配置”维护；静态默认值只保留在 module.yaml.config_defaults，task/workflow 在使用点直接读取 ctx.get_config() / ctx.config，helpers/runtime_settings.py 仅保留无状态转换 util。
  • 手动携程登录主要使用 login.url、login.ctrip.phone、account.manual_phone 和 login.manual_confirmation_timeout_seconds 作为页面打开、手机号回退与用户确认超时控制来源。
  • 自动携程登录主要使用 login.ctrip.phone、login.ctrip.country_code、login.ctrip.sms_verify_type、login.ctrip.sms_code、login.sms_platform.* 和 Core ctx.tools 暴露的 captcha.* 工具。
  • web_quiz_workflow 现在会先准备两类账号：优先复用当前 env_id 已绑定且可运行的携程账号，复用不到再从 accounts 表选择并绑定；同时从 labor_accounts 表选择一个未占用劳保账号并置为占用。任一账号不可用时，workflow 会在进入做题主链前明确失败。
  • 网页做题还会读取 pipeline.max_rounds、pipeline.retry_limit、pipeline.claim_wait_seconds、pipeline.similarity_threshold 和 pipeline.question_confirmation.*；其中 retry_limit 表示当前劳保账号连续无任务多少次后尝试切号，claim_wait_seconds 表示两次无任务轮询之间的等待秒数；人工确认默认关闭，关闭时会自动继续。

当前 workflow 行为

  • login_workflow：打开携程登录页后会先切到“验证码登录”面板，并在确认手机号输入、验证码输入或发送验证码控件可见后进入手动登录等待；当用户输入手机号后，workflow 会先进入短暂观察窗口：如果检测到用户已经手动点击了“发送验证码”并出现验证码弹框或后续验证码输入，则不会再补点发送按钮；如果用户没有继续操作，workflow 会在观察窗口后自动点击一次“发送验证码”，因此在“重复手机号提示后重新输入新手机号”的场景下也能自动继续。短信验证码现在只接受 6 位数字，少于或多于 6 位都不会触发登录提交。若用户提交的短信验证码被页面判定为“验证码错误”，task 会自动重新点击一次“发送验证码”并继续等待用户输入新的验证码，不再因为连续输错而直接中止任务；日志里也只会保留精简后的错误行，不再把整页正文一起打出来。滑块模式会调用 Core 滑块缺口识别并循环重试，点选模式则等待用户手动完成验证；登录、会员中心提问、滑块拖动、酒店详情入口点击等页面动作现统一走拟人化浏览器操作层，带随机鼠标轨迹、点击落点、输入节奏与短暂停顿，且每次执行形态不同。其中验证码滑块会保留 Core 计算出的精确目标点，仅把拖动路径拟人化，不再使用通用大过冲拖拽；每次滑块尝试只允许读取页面 src/data: 原图参与 Core/本地求解，并只保留背景图、拼图块和 Core/本地求解出的目标位移到 /tmp/ctrip_crawler_captcha_debug/，不再额外截图或保存拖动后的结果图。其 Core 路径会额外把 target_center_x/y 和 puzzle_piece_offset_x/y 落到 metadata.json，便于排查“闪动”或缺口偏移问题。会员中心固定问句现按“候选联想 -> 提交确认 -> 跟进响应”三段式状态机执行：先走精确拟人化输入并等待联想候选，命中时优先点击候选；候选阶段除原 query 外，还会按白名单尝试 查询注册时间/注册时间、会员等级/会员级别 等别名候选，但仍保持原 query 优先。若候选阶段未命中，发送链会先观察 3 秒，再额外等待 1.6 到 2.8 秒并复查一次，只有仍未确认进入会话时才脚本重发，避免网络稍慢时把同一句补发两次；发送后若页面只剩同名跟进按钮，则继续等待回答而不是重复点同名按钮。账号信息查询完成后会在页面额外停留 1 秒再离开。确认面板中的账号状态显示为中文“正常 / 黑号”，只有用户点击确认后 workflow 才结束。
  • 会员中心问句的页面级回归已经补齐，覆盖了注册时间和会员等级两类别名按钮，不再只停留在文档层面的“已覆盖”描述。
  • auto_ctrip_login_workflow：用配置手机号和验证码链路自动登录携程，提取账号摘要后同步到 accounts。
  • web_quiz_workflow：当前执行完整闭环：准备携程账号和劳保账号，完成劳保登录与题目快照读取，再按 pipeline.max_rounds 循环执行 claim_labor_task -> execute_labor_task -> deliver_labor_task。做题阶段会先走携程酒店搜索接口匹配 hotel_id/city_id，再打开酒店详情页并只以 getHotelRoomListInland 命中作为成功条件；成功结果会编码为 labor 平台要求的字符串后进入交付。若 claim_labor_task 返回 no_task，workflow 会先用 warn 日志打印当前环境和劳保账号信息，再按 pipeline.claim_wait_seconds 等待并继续领题；连续 pipeline.retry_limit 次无任务后，会优先尝试切换到新的未占用劳保账号，切号成功后继续轮询，切号失败或无可用新账号时保持当前账号继续轮询。若出现 account_blacklisted、执行失败或交付失败，workflow 会写出 stop_reason 并停止后续轮次。
  • UI 现状：模块首页现已接入统计 Dashboard，展示 今日总数、今日成功、今日失败、今日黑号 4 张 KPI 卡片，以及劳保账号分布和今日黑号明细；账号管理入口继续通过 detail_menu -> core:data_table:accounts、core:data_table:labor_accounts、core:data_table:xc_accounts 打开。
  • 当前能力：统计首页会按 Asia/Shanghai 自然日直接聚合 pending_judgments 与 account_events，用于展示今日已交付、今日终判成功、今日终判失败与今日黑号数量；携程账号管理页支持账号列表查看、账号新增、账号编辑、主键只读保护和运行态字段只读保护；劳保账号管理页除账号/密码外，还支持维护账号级偏好任务类型/渠道/城市，并展示最近登录状态、最近登录检查时间、平台用户名、平台角色、平台状态、最后登录时间、任务数、当日任务数、失败任务数、当日失败任务数和占用中；XC 账号管理页支持 query token / submit token 维护与运行态展示。
  • 表契约：两个账号表都会在页面打开时由模块 declare_ui 主动注册，不依赖 before_run() 或 workflow 执行。
  • 当前边界：网页做题相关单元/集成回归、当前 SDK CLI smoke 与宿主离屏 smoke 已完成；真实携程/劳保网站回放仍需在具备联网、验证码和人工确认条件的环境补验，当前文档不会把这一步写成已通过。

当前验收结论

  • 测试 Gate 已通过，当前状态见 .factory/process/quality-check-report.md。
  • web_quiz_workflow 的技术验收已经覆盖“账号准备、多轮循环、黑号停止、统计回写、cleanup 释放和人工确认开关化”；证据见 test-report.md、smoke-report.md 和 acceptance-checklist.md。
  • 宿主账号管理 UI 与模块入口离屏 smoke 已通过；真实携程/劳保网站 smoke 仍待外部环境补验。