Entropyorder 项目索引站

给 Entropyorder 成员的项目地图：一个可公开分享的落地页 + 一个用口令解锁的成员索引区。 当前收录 131 个仓库（2 个公开 / 129 个私有），按方向分类、可搜索、可筛选，并提供上手学习路径。

• 🌐 线上地址：https://entropyorder.github.io/dev-projects/
• 🔐 成员入口：网页内输入内部渠道分发的口令解锁（数据在浏览器本地解密）

为什么是「密文发布」模型

Entropyorder 使用 GitHub Free 计划，私有仓库无法开启 Pages。因此成员专属内容（私有仓库清单、 README 摘要、策展内容）不会以明文形式出现在任何公开文件里，而是：

1. 构建时用 INDEX_PASSPHRASE 通过 PBKDF2-SHA256（600,000 次） 派生密钥，再用 AES-256-GCM 加密成 public/data/index.enc.json；
2. 密文随公开站点一起发布，可被任何人下载，但只有持有口令的人能在浏览器中解开；
3. 明文载荷（payload.json）与明文策展源（curated.private.json）被 .gitignore 排除， CI 中 scripts/verify-data.mjs 做隐私审计兜底。

安全边界：密文可离线爆破，安全性完全取决于口令强度。请使用 ≥12 字符（建议 6 词随机短语）的口令， 口令泄露等同内容泄露；泄露后立即按 docs/DEPLOY.md 轮换。

技术栈

• 前端：React 19 + TypeScript 7 + Vite 8；深色/浅色主题；桌面/平板/手机响应式
• 加解密：WebCrypto（浏览器与 Node ≥ 22.18 共用 shared/crypto.ts，零依赖）
• 数据管线：Node 脚本调用 GitHub REST API 拉取组织全部仓库 + README 摘要 + 分类
• 质量：Vitest 单测、tsc --noEmit 类型检查、scripts/verify-data.mjs 隐私审计
• 部署：GitHub Actions + GitHub Pages（deploy.yml 部署站点，sync.yml 每日同步数据并自行部署）

目录结构

entropyorder-projects/
├── index.html / vite.config.ts / tsconfig.json
├── shared/                     # 前端 & Node 共用（零依赖）
│   ├── types.ts                # 数据契约 v1（唯一类型来源）
│   ├── crypto.ts               # sealJson / openJson / isEnvelope / UnlockError
│   └── crypto.test.ts          # 加解密单测
├── src/                        # React 前端：落地页、口令解锁、成员索引/统计/学习路径
├── public/
│   ├── favicon.svg
│   └── data/                   # 数据产物
│       ├── site.json           # ✅ 提交：公开落地页（只含公开仓库）
│       ├── meta.json           # ✅ 提交：公开元信息（数据版本、KDF 参数）
│       ├── index.enc.json      # ✅ 提交：成员区密文（EncryptedEnvelope）
│       └── payload.json        # ❌ gitignored：明文载荷，禁止提交
├── data-src/
│   ├── site.json               # ✅ 提交：公开文案源
│   ├── curated.enc.json        # ✅ 提交：策展源密文（CI 用口令解密）
│   └── curated.private.json    # ❌ gitignored：策展源明文
├── scripts/
│   ├── build-data.mjs          # 数据同步：拉取 → 规范化 → 分类 → 密封
│   ├── seal.mjs / unseal.mjs   # 手动密封 / 导出明文（支持任意 --in/--out）
│   ├── verify-data.mjs         # 隐私与契约审计（CI 必跑）
│   └── lib/                    # env / github / readme / classifier / privacy 等
├── tests/                      # 测试辅助
├── docs/
│   ├── ARCHITECTURE.md         # 架构与安全模型
│   ├── DATA-CONTRACT.md        # 数据契约与不变量
│   └── DEPLOY.md               # 部署、secrets、轮换、排障
└── .github/workflows/
    ├── deploy.yml              # push main / 手动 → 检查 → 构建 → Pages
    └── sync.yml                # 每日 03:00 UTC / 手动 → 同步数据 → 提交 → 自行部署

本地开发

要求：Node.js >= 22.18（推荐 24），npm，能访问组织私有仓库的 GitHub 账号。

npm ci

# 1) 本地环境变量（.env.local 已被 gitignore，绝不提交）
cp .env.example .env.local
#   编辑 .env.local：ORG=Entropyorder、INDEX_PASSPHRASE=<内部口令>；GH_TOKEN 可留空，自动回退 gh auth token

# 2) 生成/刷新数据（需要 token 读取 129 个私有仓库）
GH_TOKEN=$(gh auth token) npm run data:sync

# 3) 本地预览（公开落地页 + 成员解锁）
npm run dev        # http://localhost:5178/dev-projects/

data:sync 会调用 GitHub API（含 README 摘要拉取），首次运行约 1–2 分钟。

常用命令

命令	说明
npm run dev	本地开发服务器（http://localhost:5178/dev-projects/）
npm run build	构建静态站点到 dist/（CI 中在 payload 不存在的干净 checkout 中执行）
npm run preview	预览构建产物
npm run typecheck	TypeScript 类型检查
npm run test	Vitest 单测（加解密、筛选逻辑等）
npm run data:sync	拉取组织仓库 → 规范化/分类/README 摘要 → 写公开数据并密封成员区
npm run data:seal	手动密封：public/data/payload.json → index.enc.json
npm run data:unseal	导出明文载荷（默认写回 payload.json，仅本地维护用）
npm run data:verify	隐私与契约审计（CI 必跑，失败即 exit 1）

支持任意路径的文件加解密（例如策展源）：

# 明文策展源 → 可提交的密文（提交 curated.enc.json，绝不提交 private.json）
npm run data:seal -- --in data-src/curated.private.json --out data-src/curated.enc.json

# 从密文恢复本地明文（用于维护；输出被 gitignore）
npm run data:unseal -- --in data-src/curated.enc.json --out data-src/curated.private.json

# 只看内容不落盘（--stdout 适合管道，直接跑 node 避免 npm 日志混入 stdout）
node scripts/unseal.mjs --stdout | head

两个脚本都支持 --help；退出码约定：0 成功、1 参数/环境/口令错误、2 数据格式或完整性错误。

数据与安全约定

• 提交的文件：public/data/{site,meta,index.enc}.json、data-src/{site.json,curated.enc.json}、 代码与文档。
• 绝不提交：public/data/payload.json、public/data/payload.plain.json、data-src/curated.private.json、 .env / .env.local（.gitignore 已覆盖，data:verify 也会检查 git 跟踪状态）。
• 隐私不变量（CI 强制）：
  1. site.json 只允许 Entropyorder/homepage、Entropyorder/.github 两个公开仓库；
  2. 公开文件不得出现任何私有仓库的 name / description / html_url （大小写敏感 + 单词边界 + 名称长度 > 3，避免公开 benchmark 名被私有仓库名误伤）；
  3. index.enc.json / curated.enc.json 必须是合法 EncryptedEnvelope， kdf.iterations >= 100000、密文非空；
  4. 仓库内不得出现 token / 私钥特征串，也不得出现硬编码口令。
• CI 密钥：ORG_READ_TOKEN（只读：Metadata + Contents）、INDEX_PASSPHRASE（成员区口令）。 只配置在 GitHub Actions secrets，脚本通过环境变量读取。
• 发布产物：只发布 CI 构建的 dist/。本地 npm run build 时如果 public/data/payload.json 存在， Vite 会把它一起复制进 dist/，因此不要发布本地 dist（data:verify 会对此给出警告）。

完整数据契约见 docs/DATA-CONTRACT.md，安全模型见 docs/ARCHITECTURE.md。

部署（三步）

1. 建仓库：在 Entropyorder 组织下创建 Public 仓库 projects，把 main 推送上去；
2. 开 Pages + 配 secrets：Settings → Pages → Source 选 GitHub Actions； Settings → Secrets and variables → Actions 添加 ORG_READ_TOKEN（fine-grained PAT，只读 Metadata + Contents） 与 INDEX_PASSPHRASE（成员区口令）；
3. 上线：push main 触发 Deploy site；成功后访问 https://entropyorder.github.io/dev-projects/。 再到 Sync project data 手动跑一次，验证「每日同步 → 提交数据 → 自动部署」闭环。

详细步骤、token 权限说明、口令轮换流程与故障排查见 docs/DEPLOY.md。

自动化

• Deploy site（deploy.yml）：push main 或手动触发 → npm ci → typecheck → test → data:verify → build → 上传并部署 GitHub Pages。无需 secrets。
• Sync project data（sync.yml）：每日 03:00 UTC（北京时间 11:00）或手动触发 → 校验 secrets → data:sync → data:verify → 数据有变化则以 github-actions[bot] 提交推送 → 在同一个 run 内自行构建并部署（GitHub 的 GITHUB_TOKEN 推送不会触发 deploy.yml，见 docs/DEPLOY.md）。

常见问题

• 成员入口打不开 / 解锁失败：确认口令正确（大小写敏感，全角/半角会归一化）、刷新页面（Pages CDN 缓存约 10 分钟）、 使用支持 WebCrypto 的现代浏览器并通过 https 访问。
• 本地 data:verify 报 dist 含明文载荷：本地构建把 public/data/payload.json 复制进了 dist/； 删除 dist/ 重新构建即可，CI 构建不会包含它。
• 数据没更新：看 Actions 里 Sync project data 的“检测数据文件变化”步骤；无变化时会跳过部署。
• 更多问题见 docs/DEPLOY.md。