AGENTS.md

本仓库的 AI 代理工作规范。任何 AI/NPC 在本仓库执行任务前，必须先阅读并遵守本文件。

仓库约定（先看这里）

项目结构

index.md / about.md        # 站点首页、关于页（中文，路由 /）
en/                        # 英文镜像（en/index.md、en/about.md，路由 /en/）
docs/                      # 调研笔记正文（公开页面，如 fzd-matches-youku.md、yifan-fengshen-s2-fzd.md）
docs/index.md              # 调研笔记总览页
.vitepress/config.mts      # 站点配置（nav / sidebar / locales / srcExclude）
public/                    # 静态资源
raw-data/                  # 原始数据（matches/、rankings/、interviews/，不发布）
images/                    # 图片素材（matches/、events/、portraits/，不发布）
videos/                    # 视频素材（>10MB 走 Git LFS，不发布）

网站结构

• 导航主入口：「调研笔记」下拉，其下分类目前有：一饭、比赛。
• 网站分类是活的：网站改版、新增分类（如报告、文章等）时，同步更新本节分类说明与下方「站点维护约束」中的三处同步清单。
• 侧栏：调研笔记 → 一饭 / 比赛 分组；「站点」分组收「关于」。
• 中英文站点结构对称，改一侧必须改另一侧。

技术栈

• VitePress（配置 .vitepress/config.mts，TypeScript）
• Node 22（.node-version / .nvmrc），npm
• 部署：Cloudflare Pages（Git 集成，push main 自动构建，构建命令 npm run build，产物 .vitepress/dist）
• 站点仅公开 docs/ 与基础页面；raw-data/、images/、videos/、README.md 已通过 srcExclude 排除

站点维护约束

1. 新增/改名/移动 docs/ 文档、或网站改版新增分类（如报告、文章等），必须同步三处：.vitepress/config.mts 的中英文 nav + sidebar、中英文首页（index.md / en/index.md）、docs/index.md 总览页；改完确认导航无 404。
2. 图片引用前复制并压缩到 public/images/，不直接引用 images/ 仓库路径；大文件必须走 Git LFS。

内容红线（数据与事实）

1. 事实性数据（链接、比分、日期、人名、国籍）必须来自可访问的一手来源（官方页面、权威媒体报道），逐条验证后填入。
2. 查不到就标「无法确认」或直接移除该条目，禁止「见视频 / 见合集 / 详见官网」式甩锅占位。
3. 给链接必须给最终落地页（含 vid/cid 的原始链接），不给搜索页、合集页凑数。
4. 用户点名要的字段一个不能少，比赛索引字段尽量齐全（官方链接、时间、赛事、场次、简介、比分、对阵运动员和国家等）。
5. 交付前自查：ts 验证通过 + 链接能打开即可，不需要每次都跑 npm run build。本环境没有 Node 时要如实说明无法本地验证，不谎称已验证。

内容风格（面向球迷，不是程序员）

1. 站点文档（docs/、首页、关于页）禁止出现：仓库/Issue/PR 链接、HTTP 状态码、接口名、SSR、showid/cid 等技术术语。
2. 数据来源用大白话表述，如「优酷体育频道公开视频，链接均经人工验证可正常打开」。
3. 技术实现细节只出现在 Issue/PR 评论区，不进站点正文。

流程纪律

1. 用户说「调研 / 考察 / 整理方案 / 等我拍板」时只发评论输出方案，不动代码；明确说「开始实施 / 落盘 / 提 PR」才动手。
2. 被 @ 时先读 Issue/PR 已有评论：已有方案在讨论中就不要另起炉灶输出冲突方案；用户否定反馈时停止辩解，回溯原始记录定位根因。
3. 改代码必须走 PR、在 PR 源分支上提交，不直接推 main、不新建无关分支。