归档规范 v1.3

立库日期：2026-10-11 ｜维护：墨童
v1.1（2026-10-12）：新增 §5.2 上手门槛 维度，用于筛出"普通人可直接用"的项目。
v1.2（2026-10-12）：确立构建式架构（CARD.md 为唯一手写源，dist/ 全部是构建产物）；新增 §8 品牌约定。
v1.3（2026-10-13）：内容产品化——新增 口径冲突清单（CONFLICTS.md） 与 跨项目设计范式（PARADIGMS.md） 两个独立页面；新增 §9 页面、无障碍与响应式基线；新增运维配置 deploy/。

1. 目录结构

github上的高分项目集合/
├── config.json                # 站点配置（站名、副标题、分类字典、门槛文案）
├── build.mjs                  # ✅ 零依赖构建器：CARD.md + *.md → 静态站
├── CONVENTIONS.md             # 本规范（渲染为 about.html）
├── DISCLAIMER.md              # 免责声明（渲染为 disclaimer.html）
├── CONFLICTS.md               # 口径冲突清单（渲染为 conflicts.html）
├── PARADIGMS.md               # 跨项目设计范式（渲染为 paradigms.html）
├── README.md                  # 人类可读索引（表格）
├── static/                    # 需原样复制的二进制资产（og.png / apple-touch-icon.png）
├── deploy/                    # 运维配置（nginx.conf 模板 + DEPLOY.md 部署步骤）
├── templates/
│   └── PROJECT_CARD.md        # 项目卡片模板
├── dist/                      # ⚙️ 构建产物：完整静态站（**勿手工编辑**）
│   ├── index.html             # 列表页（搜索 / 筛选 / 排序 / 门槛筛选 / 对比勾选）
│   ├── beginner.html          # 普通人精选页
│   ├── compare.html           # 对比页（最多并排 3 个项目）
│   ├── p/NNN.html             # 详情页（正文 + 目录 TOC + 相关项目 + 新鲜度）
│   ├── tags/<slug>.html       # 分类页
│   ├── about.html · disclaimer.html · conflicts.html · paradigms.html · 404.html
│   ├── feed.xml               # RSS 2.0 订阅
│   ├── favicon.svg · assets/ · sitemap.xml · robots.txt
│   └── index.json             # 机读索引（由构建器生成）
├── index.json · index.html    # 根目录向后兼容产物（离线单文件版）
└── projects/
    └── NNN-owner-repo/        # 一个项目一个目录
        ├── CARD.md            # ✅ **唯一手写数据源**
        └── assets/            # 截图、附件（按需创建）

架构原则：只写 CARD.md，其余全由 build.mjs 生成。 新增/修改项目后跑一次 node build.mjs 即全站同步，不要再手工编辑 index.json、index.html 或 dist/ 下任何文件。

2. 命名规则（一律 ASCII）

项目目录：NNN-owner-repo，序号三位零填、全局自增、作废不复用。
目录名全小写、连字符分词，不出现空格与中文。
采集到的截图 / 附件放各自项目目录下的 assets/。

3. 卡片必填字段（YAML front matter）

字段	说明
`id`	三位序号，必须与目录序号一致
`name` / `repo` / `url`	项目名、`owner/repo`、仓库地址
`category`	见 §4 分类字典，可多值
`language` / `license`	主语言、许可证
`stars` / `forks`	快照数值（整数，不加千分位）
`snapshot_date`	必填，数据快照日期，格式 `YYYY-MM-DD`
`gate`	上手门槛等级（0–4），见 §5.2
`scores`	四项评分，见 §5
`verdict`	一句话结论，≤40 字

4. 分类字典

AI Agent ｜ 开发工具 ｜ 逆向与安全 ｜ 创意与媒体 ｜ 基础设施 ｜ 数据与金融 ｜ 其他

5. 评分口径（各项 ⭐ / 10）

维度	含义
`heat`	传播热度：星标增速、榜单位次、社区讨论量
`engineering`	工程完成度：文档、测试、发布节奏、代码质量
`relevance`	与老爷四条线（网文 / 漫剧 / TextFlow / 变现）的直接相关性
`archive_value`	收藏观察价值：是否值得长期跟踪、是否有可借鉴范式

5.2 上手门槛（`gate`，0–4）

目的：区分"开发者工具"与"普通人能直接用"的项目。数值越低越友好。

等级	名称	判定标准	普通人友好
`0`	打开即用	网页版 / 免安装双击，无需注册或配置	✅ 最友好
`1`	装个软件	下载安装包 → 图形界面 → 装完能用	✅ 友好
`2`	动一次设置	需选模型 / 填 API Key / 具备显卡等一次性准备	⚠️ 一般
`3`	敲一条命令	命令行 / Docker / 把脚本粘给 Agent 执行	⚠️ 偏难
`4`	自建或写码	需部署服务、配环境、改代码才能跑起来	❌ 劝退

口径：以"首次跑通"的最小代价判定，不以后续高级用法为准。

排序：列表页支持「按上手门槛」升序（越友好越靠前），并提供「只看普通人友好（L0–L2）」筛选。

6. 内容纪律（沿用老爷硬性偏好）

必须区分 真问题·硬伤 与建议，不得混装。
必须给 锚点清单，并显式标出 待核实 项。
数据必须带 来源与时点；无来源的数字标"待核实"，绝不编造。
星标是廉价指标，下载量 / 依赖数 / issue 活跃度 优先采信。

7. 新增项目流程（五步闭环）

采数 → 2. 交叉验证（多源比对，优先 GitHub 官方 API）

→ 3. 写卡片 projects/NNN-owner-repo/CARD.md

→ 4. 构建：node build.mjs（自动生成列表页、详情页、分类页、index.json、sitemap.xml）

→ 5. 复核：截图肉眼验收，且卡片字段与产出条目数一致

⚠️ 不要再手工编辑 dist/ 下任何文件，也不要手写 index.json——它们全是构建产物，下次构建即被覆盖。

8. 品牌约定（2026-10-12 立）

站名「星鉴」：星 = GitHub 星标，鉴 = 鉴别验真。站名内不出现 "GitHub" 字样（商标风险），商标只在正文与副标题中作正常指称。
副标题承担搜索词：「GitHub 高星项目录 · 每个项目都重新打过分」——"高星"放副标题吃搜索流量。
核心词是「高分」而非「高星」：库内实测，星标与综合评分的相关系数 r ≈ 0.44（弱相关），星标前十与评分前十仅 7 项重合。"高星"是可复述的公开数字，"高分"才是本库的增量——故站名与标语一律用"高分 / 验真"，不用"高星"当门面。
术语跟社区叫法：Star → 星标（官方界面译作"收藏"，但社区主流为"星标"，本库统一用"星标"）；Fork → Fork / 复刻；Pull Request → PR。
Slogan：高星不等于好用，这里替你验真。

9. 页面、无障碍与响应式基线（2026-10-13 立）

页面清单（全部由 build.mjs 生成）

页面	路径	说明
列表页	`index.html`	搜索（含正文）/ 筛选 / 六种排序 / 门槛筛选 / 对比勾选
普通人精选	`beginner.html`	门槛 ≤ L2，按易到难排列
对比页	`compare.html`	最多并排 3 个项目，支持 `?ids=001,020,021` 直达
详情页	`p/NNN.html`	正文 + 自动目录（TOC） + 相关项目 + 新鲜度 + 复制链接
分类页	`tags/<slug>.html`	按分类归档
口径冲突清单	`conflicts.html`	渲染 `CONFLICTS.md`
跨项目设计范式	`paradigms.html`	渲染 `PARADIGMS.md`
归档规范 / 免责	`about.html` / `disclaimer.html`	渲染 `CONVENTIONS.md` / `DISCLAIMER.md`
订阅	`feed.xml`	RSS 2.0，最新 20 条

硬性基线（每次改动不得回退）

无障碍：每页含 skip-link、<main id="main">、:focus-visible 焦点环；表格必须有 <caption> 与 <th scope="col">；表单控件必须有可读标签（视觉或 .sr-only）；筛选结果用 aria-live="polite" 播报；列表行可键盘聚焦并回车进入。
响应式：断点 1080 / 720 / 560；窄屏逐级收起次要列（hide-sm 收语言与门槛、hide-xs 收分类），表格外层 .tbl-wrap 兜底横向滚动，任何宽度下不得出现横向溢出（以 scrollWidth == innerWidth 为准）。
主题：必须同时支持浅色与 prefers-color-scheme: dark，并遵守 prefers-reduced-motion。
SEO：canonical / OG / Twitter Card / JSON-LD（WebSite + ItemList + SoftwareApplication + BreadcrumbList + WebPage）齐备，首页 canonical 用根路径 /；不输出 aggregateRating（自评分数会被判违规）；404 页必须 noindex。
构建自检：build.mjs 会校验 id 唯一性、必填字段、gate 范围、评分合法性与分类字典归属，发现问题在构建日志中列出。