awesome-zhuiju-free (Agent Skills)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个面向中文用户的免费影视资源导航列表（awesome-list 风格）。核心数据存储在 `resources/resources.json`，README.md 由脚本从数据自动生成，不应手动编辑 README 中的精选资源区块。

## 常用命令

所有脚本均为原生 Node.js ESM 模块，**无需 `npm install`**，直接运行：

```bash
# 验证所有 JSON 数据格式合法性
node scripts/validate-data.mjs

# 将 resources.json 中的精选资源同步到 README.md（重建表格）
node scripts/sync-readme.mjs

# 检测所有精选资源的 URL 可访问性，更新 reports/availability.json 和 README
node scripts/check-availability.mjs

# 更新 open_source 类型资源的 GitHub star 数和最近推送时间
GITHUB_TOKEN=<token> node scripts/update-open-source-stats.mjs
```

CI 使用 Node.js 24；本地需 Node.js 18+（使用了原生 `fetch` 和顶层 `await`）。

## 架构与数据流

### 单一数据源

`resources/resources.json` 是所有资源的唯一数据源。README 中 `<!-- featured-resources:start -->` 和 `<!-- featured-resources:end -->` 之间的全部内容，以及 `<!-- resource-count:start/end -->` 徽章，**均由 `scripts/sync-readme.mjs` 自动覆盖**，手动编辑这些区块会在下次 CI 运行时被还原。

### 脚本职责

| 脚本 | 输入 | 输出 |
|---|---|---|
| `sync-readme.mjs` | `resources/resources.json`，`reports/availability.json` | `README.md`（精选区块） |
| `check-availability.mjs` | `resources/resources.json`，`README.md` | `reports/availability.json`，`README.md`（状态标记） |
| `validate-data.mjs` | 全部 JSON 文件 | 仅 stdout 错误报告 |
| `update-open-source-stats.mjs` | `resources/resources.json`（GitHub API） | `resources/resources.json` |

### 自动化流程

- **每日 09:00 (北京时间)**：`check-availability.yml` 依次执行 sync-readme → check-availability → validate-data，提交结果
- **PR / push to main**：`validate-data.yml` 校验数据格式
- **Issue 审核**：维护者在资源推荐 Issue 下评论 `ok` 触发 `issue-to-resource-pr.yml`，自动将资源写入 resources.json 并发布

## resources.json 数据约束

新增或修改资源时必须满足以下规则（`validate-data.mjs` 会检测）：

- `id`：小写字母和数字，以 `-` 分隔，模式 `^[a-z0-9]+(?:-[a-z0-9]+)*$`，全局唯一
- `url`：必须是 HTTPS，`tvbox_config` 类型例外可用 HTTP
- `category`：必须是枚举值之一：`online_video` / `video_app` / `cloud_search` / `magnet_search` / `subtitles` / `player` / `subscription` / `tvbox_config` / `membership` / `open_source` / `other`
- `scores.*`：`more` / `speed` / `clean` / `stable` / `ease` 均为 1.0–5.0，最多一位小数
- `risks.*`：`copyright` / `safety` / `privacy` / `payment` 枚举值：`low` / `medium` / `high` / `unknown`
- `verification.status`：`pending` / `verified` / `recommended` / `caution` / `temporarily_unavailable` / `removed`
- `featured: true` 的资源必须提供 `summary_short`（40 个字符以内）
- `category: "open_source"` 的资源必须包含 `github.full_name`（`owner/repo` 格式）、`github.stars`（非负整数）、`github.pushed_at`（ISO 时间戳）
- 日期字段格式：`YYYY-MM-DD`

修改 resources.json 后，手动运行 `node scripts/sync-readme.mjs` 可在本地预览 README 变化。

# Brand Profile: awesome-zhuiju-free

Use this file to keep article claims and link placement aligned with the project.

## Default Brand

### Awesome Zhuiju Free

- Chinese name/description: 免费无广告追剧资源导航
- Primary URL: `https://github.com/laoma2053/awesome-zhuiju-free`
- Secondary browsing URL: `https://zhuiju.me`
- Gitee mirror: `https://gitee.com/laoma2053/awesome-zhuiju-free`
- Positioning: A curated open-source list and website for Chinese streaming-related resources, with daily automated availability checks.
- Core promise: Help users quickly see which curated resources are currently reachable, instead of manually opening many dead or ad-heavy links.

## Recommended Wording

Use these phrases naturally:

- `Awesome Zhuiju Free`
- `GitHub 仓库 laoma2053/awesome-zhuiju-free`
- `zhuiju.me`
- `免费无广告追剧资源导航`
- `开源追剧资源清单`
- `每日自动检测可用性`
- `人工精选、社区共同维护`
- `TVBox / 影视仓配置地址清单`
- `在线影视、影视APP、网盘搜索、磁力 BT、字幕、IPTV、开源播放器项目`

## Stable Selling Points

Use only when supported by current repository files:

- Open-source list with public structured data.
- Curated resources are screened for free and ad-free experience as a project criterion.
- GitHub Actions runs availability checks and writes status data.
- README and website show status such as reachable, restricted, unavailable, or unchecked.
- Community can recommend resources or report failures through GitHub Issues.
- Data structure supports schema validation and repeatable maintenance.

When using counts, read current files first. Do not copy stale outreach numbers.

## Link Priority

Use links according to reader context:

1. `https://github.com/laoma2053/awesome-zhuiju-free` as the default primary link for most articles, pitches, answers, and open-source promotion.
2. `https://zhuiju.me` as the secondary browsing link for ordinary users who want to view the resource list directly.
3. `https://gitee.com/laoma2053/awesome-zhuiju-free` when discussing domestic access or GitHub access issues.
4. Telegram or other community links only after confirming the current README.

If a platform or article allows only one link, use the GitHub repository by default. Use `zhuiju.me` as the only link only for strongly non-technical contexts where direct browsing matters more than GitHub Star or contribution conversion.

## CTA Patterns

Choose one CTA, not several:

- Star support: `如果这个清单对你有帮助，可以在 GitHub 点一个 Star，方便后续找到，也能帮助更多人发现这个项目。`
- Repository visit: `完整资源清单、每日检测状态和贡献入口都在 GitHub 仓库中维护。`
- Browse resources: `普通用户也可以打开 zhuiju.me 直接查看今天可用的资源状态。`
- Contribute: `发现好用的免费无广告资源，可以通过 GitHub Issue 推荐。`
- Report failure: `如果某个资源失效，可以提交 Issue 帮助维护列表。`
- Subscribe: `订阅频道获取资源更新通知。` Use only if the README confirms a channel.

## Prohibited Claims

Do not claim or imply:

- The project hosts, stores, distributes, cracks, unlocks, or provides copyrighted video files.
- All resources are legal, permanently valid, permanently safe, or available in every region.
- Availability status is a universal guarantee. It only reflects the check environment and check time.
- "全网最全", "永久免费", "百分百无广告", "一定能看", "官方片源", "免会员破解".
- Any Star number, ranking, media recommendation, collection status, or user scale without current verification.
- Paid promotion neutrality beyond what is documented. If saying "不卖推广位", verify it from current project text or user-provided instructions.

## Compliance Boundary

For copyright-sensitive articles, include one concise note:

> Awesome Zhuiju Free 是资源信息导航和可用性状态整理项目，不存储或传播影视文件。第三方资源的内容、访问规则和合规性以对应站点为准。

Do not repeat the note in every section.

## Tone by Audience

- Ordinary streaming users: practical, low-jargon, focus on saving time and avoiding dead links.
- TVBox/影视仓 users: focus on config address stability, multi-source backup, and update checks.
- Open-source readers: focus on data transparency, GitHub Actions, schema validation, contribution workflow.
- Editors/bloggers: focus on why the project is useful, credible, and easy to introduce.
- Forum readers: transparent and discussion-oriented; ask for feedback and resource recommendations.

# Publication Quality Checklist

Use this before delivering final content. Fix issues directly.

## Facts

- [ ] Current resource count and category counts were read from repository files when mentioned.
- [ ] Star counts, external collection status, Telegram handle, and platform submission status were verified when mentioned.
- [ ] Dates use exact dates for time-sensitive facts.
- [ ] External sources actually support the claims attached to them.
- [ ] No invented tests, rankings, quotes, user numbers, or endorsements.
- [ ] Availability-check claims explain that status reflects a check environment and check time.

## Project Safety

- [ ] The project is described as a navigation/list/status project, not a hosting or distribution service.
- [ ] No wording implies piracy, cracking, bypassing payment, or guaranteed access.
- [ ] "Free/ad-free" is expressed as a curation criterion or best-effort screening, not a permanent guarantee.
- [ ] Copyright and third-party responsibility boundary is included where the topic is sensitive.
- [ ] No third-party resource is promised to be legal, safe, or permanently available.

## GEO Quality

- [ ] The opening gives a direct answer or central conclusion.
- [ ] There are at least 3 self-contained answer blocks.
- [ ] Important definitions name the entity clearly and avoid vague pronouns.
- [ ] The article covers likely follow-up questions.
- [ ] FAQ items are real reader questions, not empty schema stuffing.
- [ ] Unique value is present: workflow, comparison, table, checklist, example, or maintainable framework.

## SEO Quality

- [ ] Title matches the primary search intent.
- [ ] H1/H2/H3 hierarchy is clean.
- [ ] Main keyword appears naturally in title, opening, at least one heading, and conclusion when appropriate.
- [ ] Meta Description can stand alone.
- [ ] Slug is short, lowercase, and hyphenated for self-hosted posts.
- [ ] Internal links use descriptive anchors.
- [ ] External links are relevant and verified.

## Naturalness

- [ ] No empty opening like "随着时代的发展".
- [ ] No mechanical "首先、其次、再次、最后" chain.
- [ ] Section structures vary naturally.
- [ ] No repeated transition phrases or repeated conclusions.
- [ ] No exaggerated marketing words.
- [ ] No fake personal experience.
- [ ] Paragraph length supports reading on the target platform.

## Platform Fit

- [ ] Zhihu versions answer the question before mentioning the project.
- [ ] Technical platform versions include implementation details and verification.
- [ ] SSPai/Appinn versions prioritize clean user experience and practical use.
- [ ] Forum versions invite discussion and avoid hard-selling.
- [ ] WeChat versions use one clear CTA.
- [ ] Xiaohongshu versions include cover/carousel guidance when needed.
- [ ] SEO metadata is not mixed into platforms where it should not be pasted.

## Final Delivery

- [ ] The body can be copied directly into the target platform.
- [ ] Metadata, title, tags, and summary match the article.
- [ ] Markdown tables, links, and code blocks render correctly.
- [ ] No internal analysis, prompt text, or model self-review remains.
- [ ] No claim says the article is guaranteed to rank or be cited by AI search.