BiliStalkerMCP: Instructions file for Codex

BiliStalkerMCP 项目规范

1. 核心理念：以用户为中心的数据采集

BiliStalkerMCP 为 AI 模型提供专注、深入的 B 站数据采集能力。开发工作应遵循以下原则。

1.1. 用户焦点原则

• 定位：围绕特定 B 站用户及其相关内容获取数据，帮助建立有依据的用户画像和内容理解。优先提高信息的深度与完整性。
• 功能边界：新增功能应服务于定位目标用户、了解该用户及分析相关内容。用户查找可以作为确定目标的入口；平台级的内容搜索、发现和推荐不属于本项目范围。

1.2. 只读操作原则

• 业务工具：只读取 B 站数据，不提供点赞、发表评论、发布内容、关注等改变账号或内容状态的功能。
• 凭据维护：凭据初始化与刷新可以执行必要的鉴权请求和本地凭据写入。维护凭据时应保护秘密值，并保证写入失败后能够安全恢复。

1.3. 数据时效性与准确性原则

• 数据质量：以准确、完整且具有明确时间含义的数据支持分析。缓存应具有合理的有效期，避免把过期结果当作实时状态。
• 结果表达：返回利于机器解析、结构稳定且有文档说明的数据。获取失败、部分成功、分页未取完或内容截断时，应明确表达结果的范围，不将缺失误报为不存在。

2. 开发准则

• 理解现状：修改相关功能前，检查当前代码、工具输入输出约定，以及所用 MCP、FastMCP 和 Bilibili API 的实际行为。
• 信息获取：需要补充依据时，使用可用的文档、源码、社区反馈和实际验证；区分已经验证的事实与推测。
• 验证范围：根据改动选择相关检查。涉及数据采集和解析时，使用有代表性的输入验证完整性与错误处理；不以本机通过代替其他环境的验证。

3. 运行环境与命令示例

• 跨平台：支持 Windows 和 Linux。共享代码、配置模板与文档不应依赖开发者的盘符、用户名、目录布局或本机代理端口；需要的路径和网络配置由运行环境提供。
• 终端语法：普通命令尽量通用。环境变量、管道和文件读取等存在终端差异时，分别提供 Bash 与 PowerShell 写法，并标明适用环境。
• 环境配置：明确路径相对于哪个工作目录解析、环境变量由哪个进程读取。凭据、本机配置和缓存不纳入版本控制或发布产物。

4. 文档标准

• README：README.md 与 README_zh.md 保持简洁，重点说明核心功能、配置和运行方法；版本历史放在发布记录中。
• 一致性：行为变更时同步相关文档。示例应能按说明替换配置后使用，避免把个人开发环境写成项目要求。

5. 核心功能开发注意事项

5.1. 图文动态解析

• 问题背景：项目早期曾出现上游库返回的图文动态无法直接取得完整正文、导致信息丢失的问题。不同动态结构需要对应的解析处理。
• 当前实现：动态获取与分页主要位于 bili_stalker_mcp/services/dynamic_service.py，内容解析主要位于 bili_stalker_mcp/parsers/dynamic_parser.py。
• 回归要求：修改动态获取、过滤或解析时，验证受影响类型的正文、图片、转发原文及分页行为，确保已有内容不会因上游结构变化或字段精简而丢失。