code-quality

代码质量：一致性、简化与审查

先读取项目 AGENTS.md，只进入当前任务涉及的部分：比较已有实现时用「代码一致性」，用户要求精简时用「代码简化」，要求审查时用「代码审查」。需要过程式主流程、变量内联、函数边界或异常收尾等标准时，按需读取 编码标准；普通明确小改无需全量加载。

代码一致性

修改已有项目时，先查看当前文件、相邻代码和最接近的同类业务实现，沿用其已经验证的 API、控制流、异常处理及日志模式；不要为同一个问题另造等价写法。

• 当前文件 / 模块有成熟先例时直接参考，新增或改变 xbot API 调用契约时仍以知识库正式事实页核对。
• 同类实现不一致时，优先选择与本次业务最接近、当前仍在使用且可确认正确的写法，不顺便统一整个项目。
• 没有适用先例时按项目 AGENTS.md 和对应知识页处理，不照搬错误、过时或业务条件不同的示例。
• 修改后仅检查本次代码与附近实现是否无理由产生新的差异；用户明确要求重构、替换旧模式或统一风格时不机械沿用旧代码。

代码简化

只优化本次最近修改的代码，使实现更直接、清晰、符合当前项目习惯；不改变业务行为，不顺手重构无关代码。

先确定范围

优先以当前 git diff、本次会话实际修改文件和用户指定范围为准。

除非用户明确要求扩大范围，否则不要因为发现旧代码也能优化，就继续整理整个文件、模块或项目。

简化前先读取当前项目 AGENTS.md。涉及项目已有实现方式时，同时按 本 Skill 的「代码一致性」部分 检查附近和同类代码，不用通用“最佳实践”覆盖项目已经形成的合理约定。

简化目标

重点检查本次改动是否出现：

• 没有额外语义、只服务下一行调用的一次性临时变量。
• 为当前单次业务步骤新增的薄函数、包装层或中转参数。
• 同一 Page 的连续操作被拆成无真实复用、无独立职责或稳定后置条件的薄函数；按 编码标准 判断，必要时还原清晰的主流程。
• 可以直接表达却被拆成初始化再覆盖、重复判断或多余状态的逻辑。
• 不必要的嵌套、重复分支、重复转换或重复读取。
• 已有成功时间和跳过机制仍新增跨轮文件缓存、额外状态源，或没有明确业务需求却新增关闭 / 重开工作簿、补跑和回滚分支。
• 只为形式分层新增的 Service、Manager、Context、Helper 等业务抽象。
• 与当前模块已有代码相比明显更绕、更啰嗦或采用了第二套等价写法的实现。
• 逐行复述代码、没有解释业务意图的注释。

简化时优先让真实业务顺序直接可见，并遵守项目已有的函数边界、日志、异常处理和 xbot API 使用方式。

表格更新 RPA 的独立 Sheet 失败继续、最后统一保存等固定规则，直接按 表格操作 Skill 执行，不额外添加重开和回滚流程。

保持行为不变

简化不是重新设计。不得无理由改变：

• 业务条件、执行顺序、循环边界和停止条件。
• 将多个函数合并回主流程时，检查原函数的局部变量是否覆盖外层循环变量或业务状态；同时保持原有执行顺序、异常处理、返回值和页面状态不变。
• 返回值、数据结构、异常传播和失败语义。
• 日志中承担排查价值的业务上下文。
• 用户已确认的字段名、XPath、CSS、URL、按钮文案、Sheet 名、状态值和配置值。
• xbot / 市场指令的 API、参数、调用时机和页面交互顺序。
• 已有必要封装提供的后置条件，例如“返回一个已经登录且可直接使用的 page”。

如果无法确认某个改写是否保持行为一致，就不要为了更短或更“优雅”而修改。

不要过度简化

目标不是减少行数。

以下情况应保留显式结构：

• 分支包含多个业务动作、副作用或异常处理。
• 中间变量会复用、参与后续判断，或名称能明显解释业务含义。
• 函数 / 类确实隐藏一组实现细节，并向调用方提供稳定完整的结果或后置条件。
• 展开写法更方便排查、调试或理解真实业务顺序。

不要生成密集 one-liner、复杂条件表达式、难读的链式调用或仅为了“更少代码”合并多个业务步骤。

完成后验证

修改后重新检查 diff，确认：

1. 只修改了本次简化范围。
2. 没有引入与当前项目不同的新实现模式。
3. 业务行为、失败语义和关键常量没有变化。

按项目 AGENTS.md 的验证规则做与本次简化直接相关的最小必要验证。没有实际运行或可验证证据时，只能说明静态检查结果，不能声称业务运行行为已经验证一致。