rules

[!abstract] 摘要
项目核心操作规则：定义微信公众号内容抓取、文件处理（优先迭代、谨慎新建）与浏览器功能调用（优先 chrome-devtools 的 MCP 工具）三大流程的操作标准、异常处理与合规要求。

1. 项目核心操作规则（优化版）

1.1. 规则元配置

用于定义规则的应用范围与生效策略，确保无场景遗漏。

description: 规范项目内微信公众号内容抓取、文件处理及浏览器相关功能的操作标准，保障流程一致性与结果完整性
globs:
  - "src/crawler/wechat/**/*.js"       # 微信公众号抓取模块适用
  - "src/file-handler/**/*.js"         # 文件处理模块适用
  - "src/browser-service/**/*.js"      # 浏览器功能调用模块适用
alwaysApply: true                      # 所有匹配globs路径的场景强制应用本规则

1.2. 规则总则

  1. 目的：统一项目操作标准，减少功能冲突、确保内容完整性、提升开发与运维效率。
  2. 适用范围：项目中微信公众号链接解析与内容抓取、本地文件迭代与新建、浏览器环境依赖的功能调用全流程。
  3. 合规前提：所有操作需遵守《微信公众平台服务协议》《网络安全法》及第三方平台规则，禁止违规抓取、恶意占用资源等行为。

1.3. 微信公众号内容抓取规则

1.3.1. 抓取优先级

  • 当输入为微信公众号官方链接（格式示例：https://mp.weixin.qq.com/s/xxxx）时，必须优先调用项目内置的「微信公众号专属抓取工具」，禁止直接使用通用爬虫或第三方工具替代。
  • 若专属工具出现故障（如反爬拦截、接口失效），需先触发「故障告警」并同步至运维组，待工具修复后继续，临时替代方案需经技术负责人审批。

1.3.2. 内容完整性要求

需 1:1 还原公众号文章原貌，无任何内容/样式丢失，具体细则如下：

内容类型 处理要求
文本内容 保留段落结构、标点符号、字体样式（粗体/斜体/颜色）、超链接；失效链接需标注「[链接已失效]」。
图片内容 保留源地址、alt 文本、尺寸属性、排版位置（左对齐/居中/右对齐）；防盗链图片需本地缓存（路径：assets/wechat/[文章ID]/img/）并更新引用。
视频/音频 保留源 URL、格式（MP4/MP3 等）、时长、播放控件样式；本地存储时按「media_[序号].[格式]」命名，统一存至 assets/wechat/[文章ID]/media/。
代码块 保留语法高亮标记（如 ```javascript）、缩进格式、注释；需支持「复制代码」交互逻辑，不可删减代码字符。
附属内容 完整保留编者注、脚注、投票/问卷模块（需确保交互功能可用）、末尾「点赞/在看」提示语。

1.3.3. 异常处理

  • 网络异常：单次抓取超时（默认 30s）后自动重试 2 次，仍失败则记录错误日志（含链接、错误码、时间）并终止，不可无限重试。
  • 内容缺失：若某类内容（如视频）无法抓取，需在文章对应位置标注「[该内容因平台限制暂无法展示]」，不可直接删除对应区域。

1.4. 文件处理优先级与迭代规则

1.4.1. 核心原则

「优先迭代现有文件，谨慎新建文件」，避免文件冗余与功能冲突。

1.4.2. 现有文件识别标准

满足以下任一条件即判定为「目标文件/同名功能文件」：

  • 文件名完全一致（含后缀），且存储路径在同一功能模块下（如 src/utils/date.js 与 src/utils/date.js）；
  • 文件名不同，但核心功能域一致（如 src/crawler/wechat_v1.js 与 src/crawler/wechat_core.js，均用于公众号抓取）。

1.4.3. 迭代优化细则

当需新增功能或修复问题时，需先对现有文件进行迭代，具体优化维度包括：

  1. 功能补全：补充未覆盖的场景（如公众号投票模块抓取）、完善缺失的接口（如返回内容的结构化格式定义）；
  2. 逻辑优化：简化冗余判断（如重复的 URL 校验逻辑）、提升性能（如减少循环嵌套、缓存重复计算结果）；
  3. 代码精简：删除死代码（未调用的函数）、合并重复逻辑（如相同的错误处理流程）；
  4. 注释完善：补充「文件功能说明、函数参数/返回值定义、关键逻辑注释、调用示例」，注释覆盖率需≥80%；
  5. 兼容性适配：适配新环境（如 Node.js 18+ 语法）、修复跨浏览器兼容问题（如 DOM 操作差异）。

1.4.4. 新建文件触发条件

仅当现有文件满足以下任一特殊情况时，可申请新建文件，且需同步标注替代原因：

  • 核心逻辑严重冲突：新需求与现有文件核心逻辑完全矛盾（如现有文件仅支持「抓取已发布文章」，新需求需「抓取草稿箱文章」，逻辑无法调和）；
  • 架构无法兼容：现有文件架构不支持新功能的核心依赖（如现有文件为「单体脚本」，新需求需「微服务化调用」，重构架构成本过高）；
  • 重构成本低于优化成本：经技术评审确认，优化现有文件需修改≥80% 代码，而新建文件代码量≤50% 且更易维护（需附成本对比表）。

1.4.5. 版本控制要求

  • 迭代/新建文件后，需更新版本号（遵循「语义化版本」：如 v1.0.0→v1.1.0）；
  • 同步记录「更新日志」（含更新人、更新时间、更新内容、关联需求 ID），日志存至 docs/file-update-log.md。

1.5. 浏览器相关功能调用规则

1.5.1. 调用优先级

所有需「浏览器环境依赖」的操作，必须优先调用「chrome-devtools 的 mcp 工具」，禁止使用其他浏览器工具（如 Firefox DevTools、Selenium）替代。

1.5.2. 适用场景

明确需调用 mcp 工具的场景，避免滥用：

  • 页面渲染需求：需执行 JS 脚本后获取渲染后的 DOM（如公众号文章的动态图片加载）；
  • 网络请求捕获：需获取页面加载过程中的接口请求（如公众号文章的图片源 URL）；
  • DOM 操作需求：需模拟用户操作（如点击「展开全文」按钮）或提取特定 DOM 元素（如文章标题、作者）；
  • 样式获取需求：需获取元素的计算样式（如公众号文章的字体、颜色）。

1.5.3. 调用规范

  1. 参数传递：需明确传递「目标 URL、操作指令（如 “getDOM”“captureRequest”）、超时时间（默认 60s）、结果格式要求」；
  2. 结果返回：返回数据需结构化（如 JSON 格式），包含「操作状态（成功/失败）、结果数据（如 DOM 树、网络日志）、耗时」；
  3. 资源控制：限制并发调用数（默认≤5 个），避免占用过多浏览器资源导致崩溃；
  4. 异常处理：调用失败后自动重试 1 次，仍失败则记录「错误码、错误信息、调用参数」至 logs/browser-service-error.log，并触发告警。

1.6. 附则

  1. 生效时间：本规则自发布之日起生效，替代原有旧规则；
  2. 更新机制：当项目需求变更、第三方平台规则调整或出现新场景时，由技术组发起规则评审，经项目组全员确认后更新；
  3. 监督与落地：由技术组负责规则落地监督，每周抽查「抓取结果完整性、文件迭代合规性、mcp 工具调用规范」，抽查结果同步至项目周报；
  4. 异议处理：对规则有异议的，可提交至 issues/rule-feedback，技术组需在 3 个工作日内回复处理方案。