# Cangjie Skill 官方网站产品与设计方案（第一版）

日期：2026-07-13
状态：待确认的产品设计草案，不包含前端实现
项目：Cangjie Skill / 仓颉 Skill

> 当前实施以 [MVP 功能与页面布局规格](./2026-07-13-cangjie-skill-website-mvp-functional-spec.md) 为准；本文保留为后续视觉与完整产品愿景参考。

## 1. 一句话结论

官网不应该只是一个更漂亮的 README，而应该成为一个由 GitHub 驱动的“可验证 Skill 知识库”：用户能在 3 分钟内学会使用，能按真实问题找到合适的 Skill，贡献者能通过一个目录 PR 提交作品，维护者则直接在 GitHub 完成自动检查、人工审核和合并发布。

推荐第一阶段不做独立后台、不做站内账号、不做数据库。GitHub 仓库就是数据库，Pull Request 就是审核后台，Git 历史就是审计日志，GitHub Actions 就是自动质检员，官网只负责学习、发现、生成投稿内容和展示审核结果。

## 2. 当前项目诊断

### 2.1 已经拥有的资产

当前仓库已经具备官网最难得的四类内容资产：

1. 明确的产品主张：把书、长视频、播客、课程等长内容中的方法论蒸馏为可调用的 AI Skills。
2. 一套可解释的方法论：Adler 整体理解、并行提取、三重验证、RIA++ 构造、Zettelkasten 链接、压力测试和最终交付。
3. 一批可以直接展示的结果：当前 README 列出了 22 个 Skill Packs，合计约 300 个原子 Skills。
4. 一套较完整的产物模板：`BOOK_OVERVIEW.md`、`INDEX.md`、`DIGEST.md`、子 Skill 的 `SKILL.md`、`test-prompts.json` 和审计轨迹。

这意味着官网不用从“解释一个概念”开始，而可以直接从“给我一个问题，我帮你找到可用的方法”开始。

### 2.2 当前信息呈现的问题

当前 README 对熟悉 GitHub 和 Agent Skills 的用户很完整，但对新用户存在四个断点：

- 不知道 Skill 和 Prompt、知识库、聊天机器人有什么区别。
- 看见几十个仓库后，不知道自己该选哪一个。
- 找到仓库后，不知道安装到 Claude Code、Codex、Cursor 或 Copilot 的哪个位置。
- 想贡献时，没有统一入口、提交契约、质量等级和审核状态说明。

因此，官网的核心任务不是“讲更多”，而是降低四次决策成本：理解、选择、安装、贡献。

### 2.3 一个需要先解决的规范问题

当前 Cangjie 生成模板把 `source_book`、`source_chapter`、`tags`、`related_skills` 作为 `SKILL.md` 顶层 frontmatter 字段，其中数组使用 YAML flow list。现有 Agent 客户端可能会忽略这些额外字段并正常加载，但按 2026 年当前 Agent Skills 官方规范和 `skills-ref` 校验器，这种写法不是稳定的跨客户端契约。

建议官网上线前把标准拆成两层：

- Agent 执行契约：`SKILL.md` 只使用规范字段，包括 `name`、`description`，以及可选的 `license`、`compatibility`、`metadata`、`allowed-tools`。
- Cangjie 收录契约：展示、分类、作者、来源、质量等级、仓库地址等信息放在独立的 `entry.yaml` 中，不依赖 Agent 是否理解这些字段。

来源、章节、标签和关联 Skill 若需要留在 `SKILL.md` 内，应放入 `metadata`，并使用字符串值，以获得更好的官方校验兼容性。

## 3. 产品定位

### 3.1 推荐定位

> Cangjie Skill 是一个把高价值内容转化为可调用 Agent Skills 的开源方法与公共知识库。

网站同时承担三个角色：

- 学习站：让新手理解、安装并调用 Skills。
- Skill Library：展示官方和社区贡献的 Skill Packs 与原子 Skills。
- 开源贡献门户：让贡献者用 PR 提交，自动校验，公开审核。

### 3.2 不建议的定位

第一阶段不建议把它做成：

- “AI 应用商店”：会让人期待在线运行、付费、评分、账号体系和复杂权限。
- “内容摘要站”：会弱化可调用、可执行、可测试的核心差异。
- “上传网盘”：会带来存储、版权、恶意文件和运营责任。
- “后台 CMS”：在贡献规模尚未验证前，维护成本大于收益。

### 3.3 成功标准

首版上线后，至少能回答以下问题：

- 新用户能否在 3 分钟内完成一次安装和触发测试？
- 用户能否从“我想解决什么问题”出发找到一个 Skill，而不是只按书名浏览？
- 外部贡献者能否在 10 分钟内创建一个格式正确的 PR？
- 维护者能否在 5 分钟内判断一个投稿是格式问题、质量问题还是版权问题？
- 合并 PR 后，官网和 README 是否能自动更新而不重复维护？

## 4. 三种产品路线

### 路线 A：README 展示站

把当前 README 做成首页、教程页和卡片列表，投稿仍然完全跳转 GitHub。

优点：开发最快、风险最低。
缺点：只能“看”，没有真正改善发现和投稿体验，未来很快需要重构。

### 路线 B：GitHub 原生 Skill Registry（推荐）

官网从仓库中的结构化目录构建。每个收录项对应一个独立目录；官网提供投稿向导，在浏览器中生成 `entry.yaml` 和 `README.md`，用户最终通过 GitHub fork + PR 提交。GitHub Actions 自动检查，人工审核后合并，网站自动重建。

优点：无独立后台、透明、可审计、贡献者身份保留、可以逐步扩展。
缺点：投稿者仍需要 GitHub 账号；本地文件夹投稿比纯链接投稿多几步。

### 路线 C：完整 Skill 平台

使用 GitHub OAuth、GitHub App、数据库和对象存储，站内完成登录、上传、状态管理、评论和 PR 创建。

优点：体验最完整，可以做收藏、评分、在线试用和贡献者中心。
缺点：开发、运维、安全与合规成本显著增加，现阶段缺少足够数据证明这些能力必要。

### 推荐决策

采用路线 B。架构上保留未来接入 GitHub App 的位置，但首版不建设账号、数据库和上传后台。

## 5. 用户与核心任务

### 5.1 第一次听说 Skill 的普通用户

目标：弄懂“它能帮我做什么”，选择一个 Skill，完成安装和首次调用。

官网需要提供：

- 30 秒概念解释。
- 一个真实的输入、触发和输出演示。
- 按工具切换的安装命令。
- 可复制的测试 Prompt。
- 安装失败的最短排查路径。

### 5.2 已经使用 Agent 的进阶用户

目标：按任务、领域、来源和平台发现高质量 Skills。

官网需要提供：

- 快速搜索与多维筛选。
- Skill Pack 和原子 Skill 两层结构。
- 触发场景、反场景、执行步骤和测试状态。
- GitHub、复制安装命令、查看源材料等快捷动作。

### 5.3 Skill 创作者与内容蒸馏者

目标：提交自己的 Skill 或仓库，获得收录和署名。

官网需要提供：

- 两种提交模式：已有 GitHub 仓库、仅有本地文件夹。
- 投稿模板和实时预检。
- 清楚的质量等级、版权要求和审核过程。
- PR 状态、修改建议和贡献者署名。

### 5.4 维护者

目标：低成本判断投稿是否能收录，并保持品牌质量。

官网和仓库需要提供：

- 自动 schema 校验。
- Agent Skills 官方格式校验。
- 文件、链接、许可证、秘密信息和高风险脚本检查。
- 可重复使用的人工审核清单。
- 合并后自动生成目录、README 和官网数据。

## 6. 网站信息架构

主导航建议保持六项：

1. 首页
2. 学会使用
3. Skill 库
4. 蒸馏方法
5. 提交 Skill
6. GitHub

辅助入口：语言切换、搜索、深色模式、交流群。

建议路由：

```text
/
/learn
/library
/library/packs/[slug]
/library/skills/[slug]
/method
/contribute
/contribute/guide
/quality
/contributors
/about
```

首页不是所有信息的堆叠，而是负责把三类人分流：

- “我想学会使用” → `/learn`
- “我想找一个 Skill” → `/library`
- “我想提交作品” → `/contribute`

## 7. 首页详细设计

### 7.1 顶部导航

左侧是 Cangjie 标志与文字，右侧是主导航、全站搜索、GitHub Star 按钮和“提交 Skill”主按钮。

导航采用半透明浅色背景或墨色背景上的细描边，不做常见的厚重 SaaS 胶囊按钮堆叠。

### 7.2 Hero

主标题建议：

> 把读过、看过、听过的知识，变成 Agent 真正会用的能力。

副标题：

> Cangjie Skill 使用 RIA-TV++，把书、课程、访谈和长内容中的方法论蒸馏为可触发、可执行、可测试的 Agent Skills。

两个主要动作：

- 开始使用
- 浏览 Skill 库

一个次级动作：

- 在 GitHub 查看源码

Hero 右侧不放泛化 AI 插画，建议使用“从长内容到知识节点再到 Agent 行动”的真实动态关系图。节点可使用当前仓库中的真实 Skill 名称，例如 `margin-of-safety`、`economic-moat`、`viral-copywriting`，避免装饰性假数据。

### 7.3 实时成果条

从 registry 自动计算并显示：

- Skill Packs 数量
- 原子 Skills 数量
- 贡献者数量
- 通过测试的比例

当前可作为初始值展示“22 个 Packs / 约 300 个 Skills”，但上线后禁止手工写死。

### 7.4 三步使用演示

用一个真实例子完成闭环：

1. 选择一个 Skill，例如“安全边际”。
2. 一键复制对应平台安装命令。
3. 输入一个真实问题，看 Agent 如何触发并执行。

这部分应带工具切换：Claude Code / Codex / GitHub Copilot / 其他兼容客户端。切换后命令、目录和验证方式同步变化。

### 7.5 精选 Skill Packs

首页只展示 6 个，不展示全部：

- 巴菲特致股东信
- 穷查理宝典
- 认知红利
- 爆款文案
- AI for Everyone
- 毛泽东选集

卡片信息控制在：封面或主题视觉、名称、来源类型、原子 Skill 数、三条代表性能力、质量徽章、查看详情。

### 7.6 方法论横截面

不在首页完整解释七个阶段，只展示一句话流水线：

> 理解全貌 → 提取候选 → 三重验证 → 构造 Skill → 建立关联 → 压力测试 → 安装交付

点击进入 `/method` 查看详细过程、产物示例和质量门槛。

### 7.7 社区贡献区

展示最近收录、贡献者头像和审核规则，主文案：

> 你贡献的不是一条链接，而是一项能被验证、被署名、被长期维护的 Agent 能力。

动作：

- 提交已有 GitHub 仓库
- 提交本地 Skill 文件夹

## 8. “学会使用”页面

这个页面应采用交互式教程，而不是长文档。

### 8.1 第一步：先选你的工具

工具卡片：

- Claude Code
- OpenAI Codex
- GitHub Copilot
- Cursor
- OpenClaw
- 其他 Agent Skills 兼容客户端

只展示经过验证的目录和命令。对于尚未确认完全兼容的平台，明确标注“实验性”，不要为了平台数量而过度承诺。

### 8.2 第二步：选安装范围

- 个人级：所有项目可用。
- 项目级：只在当前项目使用。

页面根据选择生成可复制命令，并解释复制的是完整目录而不是单个 Markdown 文件。

### 8.3 第三步：验证是否生效

每个平台提供：

- 查看已发现 Skills 的方式。
- 一个 `should_trigger` 测试 Prompt。
- 一个 `should_not_trigger` 反例 Prompt。
- 常见错误：目录名不匹配、文件名不是大写 `SKILL.md`、frontmatter 无效、描述过宽、会话未刷新。

### 8.4 第四步：理解触发机制

用一个简短的三层图解释渐进加载：

1. Agent 先只看 `name + description`。
2. 匹配任务后加载 `SKILL.md` 正文。
3. 真正执行时才读取 `scripts/`、`references/`、`assets/`。

这个解释能让用户理解为什么 `description` 不是普通简介，而是 Skill 能否被调用的核心索引。

## 9. Skill 库

### 9.1 不要把 Pack 和 Skill 混在同一个平面

当前项目中的“巴菲特致股东信”是一个 Pack，内部含 20 个原子 Skills；“安全边际”才是一个具体 Skill。官网应明确两层：

- Packs：由一本书、一套课程或一组材料蒸馏出的完整知识包。
- Skills：可单独触发和执行的能力单元。

用户可以从 Pack 进入，也可以直接搜索原子 Skill。

### 9.2 筛选维度

首版建议保留真正有区分度的筛选：

- 内容来源：书籍、视频、课程、播客、访谈、资料集、实战经验。
- 领域：投资、商业、写作、营销、学习、组织、决策、技术等。
- 类型：Pack / 原子 Skill。
- 维护方式：官方维护 / 社区维护。
- 质量等级：官方蒸馏 / 社区认证 / 社区收录。
- 可用平台：由兼容性与实测结果生成。

不要在首版引入星级评分。样本少时评分没有信息量，也容易把开源贡献变成竞赛。

### 9.3 搜索排序

搜索同时匹配：

- 名称和别名。
- 用户会说的话，也就是触发语言。
- 领域和来源。
- 解决的问题。

默认排序不只看 GitHub Stars，推荐综合：

- 触发场景匹配度。
- 质量等级。
- 测试通过情况。
- 最近维护时间。
- GitHub 社交信号。

### 9.4 Pack 详情页

信息顺序：

1. 一句话说明这个 Pack 帮用户解决什么。
2. 来源、作者、年份、维护者、许可证和质量等级。
3. 代表性使用场景。
4. Pack 内 Skill 地图。
5. 推荐学习或调用顺序。
6. 安装整个 Pack / 选择安装单个 Skill。
7. DIGEST、BOOK_OVERVIEW、GLOSSARY 和审计轨迹。
8. GitHub、问题反馈和贡献者。

### 9.5 原子 Skill 详情页

信息顺序：

1. 什么时候用。
2. 什么时候不要用。
3. 用户可能会说什么。
4. Agent 会按什么步骤执行。
5. 一个过去案例和一个未来案例。
6. 触发测试、反例测试与最近结果。
7. 关联 Skills：依赖、对比、组合。
8. 安装与查看源码。

这会比直接渲染整份 `SKILL.md` 更适合人类阅读，同时保留“查看原始文件”入口。

## 10. GitHub 原生投稿与审核系统

### 10.1 核心原则

用户提交的不是全局 README 的一行，而是一个独立、可校验、可回滚的收录目录。全局 README、网站卡片、搜索索引和贡献者页面全部由这些目录自动生成。

这样可以避免：

- 多个人同时修改同一张 README 表格导致冲突。
- README、官网和数据文件出现三套不一致信息。
- 维护者手工复制投稿信息。
- 删除或撤销一个收录项时难以追踪。

### 10.2 推荐仓库结构

```text
cangjie-skill/
├── registry/
│   ├── buffett-letters-skill/
│   │   ├── entry.yaml
│   │   └── README.md
│   ├── community-scene-skill/
│   │   ├── entry.yaml
│   │   ├── README.md
│   │   └── skill/
│   │       ├── SKILL.md
│   │       ├── scripts/
│   │       ├── references/
│   │       └── assets/
│   └── another-pack/
│       ├── entry.yaml
│       ├── README.md
│       └── skills/
│           ├── skill-a/SKILL.md
│           └── skill-b/SKILL.md
├── website/
├── schemas/
│   └── registry-entry.schema.json
├── scripts/
│   ├── validate-registry.*
│   ├── build-catalog.*
│   └── sync-readme.*
└── .github/
    ├── workflows/
    │   ├── validate-submission.yml
    │   └── deploy-website.yml
    ├── PULL_REQUEST_TEMPLATE.md
    └── CODEOWNERS
```

### 10.3 两种收录模式，共用一个目录模型

#### 模式 A：外部 GitHub 仓库

贡献者已开源。`entry.yaml` 的 `artifact.type` 为 `external`，保存仓库 URL、默认分支和可选的 Skill 路径。Cangjie 仓库不复制对方代码，只保存结构化索引与介绍页。

适合：独立维护、有自己的 release 和 issue 的成熟项目。

#### 模式 B：托管在 Cangjie 仓库中

贡献者没有独立仓库。`entry.yaml` 的 `artifact.type` 为 `bundled`，实际文件放在同一目录的 `skill/` 或 `skills/` 下。

适合：单个场景 Skill、小型 Pack、首次开源的创作者。

两种模式在官网上的详情页结构一致，区别只体现在“源码位置”和“维护方式”。

### 10.4 `entry.yaml` 建议契约

```yaml
schema_version: 1
slug: margin-of-safety
title: 安全边际
summary: 在估值不确定时，用价值与价格之间的缓冲降低判断错误的代价。
kind: skill
language: zh-CN

source:
  type: book
  title: 巴菲特致股东的信
  creator: Warren Buffett

artifact:
  type: external
  repository: https://github.com/kangarooking/buffett-letters-skill
  path: margin-of-safety

authors:
  - github: kangarooking

taxonomy:
  domains: [investment, decision-making]
  use_cases: [valuation, risk-control]

quality:
  tier: official-distilled
  methodology: RIA-TV++
  tests: available

license: MIT
```

这里的字段是官网 Registry 的数据，不等于 `SKILL.md` frontmatter。两者必须分离，避免为了做官网而破坏 Agent Skills 的可移植性。

### 10.5 投稿向导

页面分为五步：

1. 选择“已有 GitHub 仓库”或“上传本地文件夹”。
2. 填写名称、解决的问题、典型触发语、反场景、作者、许可证和来源。
3. 对于外部仓库，输入 URL 并检查公开可访问性；对于本地文件夹，只在浏览器本地读取和预览，不上传到 Cangjie 服务器。
4. 生成 `entry.yaml`、`README.md`、目标目录名和 PR 检查清单。
5. 跳转 GitHub 创建新文件或进入个人 fork 上传目录，然后创建 PR。

GitHub 官方支持在无写权限仓库中创建或编辑文件时自动 fork，并引导用户发起 Pull Request；多文件目录投稿则先进入或创建个人 fork，再上传并向上游发 PR。因此首版无需保存 GitHub Token，也不需要自己实现账号体系。

### 10.6 对“本地文件夹提交”的现实处理

纯静态网站无法安全地替用户把文件写入 GitHub，也不应该在前端内嵌长期有效的仓库 Token。

首版建议：

- 浏览器本地读取目录，显示缺失文件和预检结果。
- 自动生成 `entry.yaml` 与 `README.md`，让用户下载投稿包。
- 若用户尚无 fork，先创建个人 fork；随后进入个人 fork 的 `registry/` 目录，通过 Add file → Upload files 拖入整个目录。
- 用户选择新分支并创建 PR。

GitHub Web 当前支持拖入文件夹，但单文件上限 25 MiB、单次最多 100 个文件。超出限制时，页面切换为 Git / GitHub Desktop 指南。

### 10.7 PR 状态机

```mermaid
flowchart LR
  A[官网填写投稿] --> B[生成目录与文件]
  B --> C["GitHub Fork + PR"]
  C --> D[自动格式校验]
  D -->|失败| E[贡献者修改]
  E --> D
  D -->|通过| F[人工质量审核]
  F -->|请求修改| E
  F -->|通过| G[合并到 main]
  G --> H[重建目录与官网]
  H --> I[正式收录并署名]
```

推荐标签：

- `submission:new`
- `submission:external`
- `submission:bundled`
- `checks:failed`
- `review:needed`
- `review:changes-requested`
- `ready-to-merge`

## 11. 自动审核与人工审核

### 11.1 自动审核负责客观事实

自动检查建议分为六组：

1. Registry 结构：目录名、slug、必填字段、唯一性、URL 格式。
2. Agent Skills 规范：`SKILL.md` 存在、frontmatter 合法、name 与父目录一致、description 长度和字段类型。
3. Cangjie 质量结构：触发场景、反场景、执行步骤、测试文件和来源信息是否存在。
4. 安全：秘密信息扫描、符号链接、超大文件、危险二进制文件和异常路径。
5. 外部链接：仓库可访问、默认分支存在、声明路径中能找到至少一个 `SKILL.md`、许可证可识别。
6. 构建：目录页、详情页、搜索索引和自动 README 能否生成。

自动检查不得执行投稿中的脚本。对 fork PR 使用权限受限的 `pull_request` 工作流；需要打标签或评论时单独使用受控工作流，不能在高权限上下文中 checkout 后执行投稿代码。

### 11.2 人工审核负责判断价值

人工审核不重复检查 YAML，而判断以下问题：

- 这个 Skill 是否对应一个清晰、重复出现的真实场景？
- 没有这个 Skill 时，通用 Agent 是否已经能同样好地完成？
- `description` 是否足够精确，能触发又不会泛滥触发？
- 执行步骤是否可操作、可判断完成，而不是口号？
- 是否写清不要使用的情况和失败模式？
- 来源、作者、许可证和引用是否可信？
- 测试是否包含正例、诱饵和边界，而不是只证明“它能工作”？

### 11.3 建议质量等级

#### 官方蒸馏

由 Cangjie 项目维护，完成 RIA-TV++ 全流程，有来源、验证、压力测试和审计轨迹。

#### 社区认证

由社区维护，符合 Agent Skills 标准，通过自动检查和人工审核，有明确测试与许可证，但不一定由 Cangjie 全流程生成。

#### 社区收录

格式合格、来源清楚、基本可用，但尚未完成完整压力测试。页面必须明确展示这一状态，避免用户误认为已获官方质量背书。

不建议把所有合并项都标成“Cangjie 认证”。“收录”与“认证”必须是两个概念。

## 12. 视觉设计方向

### 方向一：现代知识档案馆（推荐）

关键词：墨色、暖白、矿物金、朱砂、编辑设计、知识索引、精密网格。

整体像一家当代研究机构或高级出版品牌，而不是古风网站。中文标题有适度书卷感，界面正文保持现代无衬线高可读性。卡片像档案卡，但通过细线、编号、分类章和数据排版体现秩序，不使用卷轴、毛笔、竹简等直白古风素材。

优势：能同时承载“仓颉”的文化感和“Agent Skills”的技术感，适合内容型长页面，也容易形成独特品牌。
风险：如果金色、印章和纹理使用过多，会变成文创商城。

### 方向二：Agent Knowledge OS

关键词：深海军蓝、冷白、青蓝节点、图谱、终端、实时状态。

首页强调从知识节点到 Agent 行动的动态关系图，Skill 卡片更像开发者工具和 API Registry。

优势：技术感强，开发者一眼能理解这是可执行能力系统。
风险：容易与大量 AI SaaS 官网同质化，也会弱化内容蒸馏和中文品牌个性。

### 方向三：未来出版物

关键词：高对比黑白、大字号、非对称编辑布局、亮橙或荧光绿、实验性排版。

把官网做成一本不断生长的数字杂志，每个 Pack 像一期专题。

优势：传播截图很有记忆点，适合公众号和社交媒体。
风险：复杂筛选、安装教程和长文档可能牺牲可用性。

### 推荐融合方式

以方向一作为品牌与内容底座，吸收方向二的知识图谱和状态可视化。不要把三套风格平均混合。

### 12.1 推荐色彩

- 背景暖白：`#F3F0E8`
- 主墨色：`#151713`
- 次级墨灰：`#565A50`
- 矿物金：`#B69042`
- 朱砂强调：`#C9472D`
- 成功绿：`#2F7656`
- 边框米灰：`#D9D3C5`

深色模式使用墨黑而不是纯黑，卡片采用略暖的深灰，金色只用于关键状态和高质量徽章。

### 12.2 字体策略

- 中文标题：优先使用有现代感的宋体或衬线体作为展示字体。
- 中文正文与 UI：高可读无衬线。
- 英文、数字、代码：中性 Grotesk + 等宽字体。

网页字体需要控制体积并设置系统字体回退，避免中文首屏因字体文件过大而变慢。

### 12.3 图形语言

- 使用真实 Skill 关系生成的节点图，而不是装饰性星空。
- 用“编号、索引条、引用线、验证章”建立档案感。
- 图标使用统一图标库，不用 emoji 作为正式功能图标。
- 图片优先使用真实书籍、课程或仓库资产，并处理版权和封面使用边界。

### 12.4 动效

动效用于解释状态变化：

- Hero 中长内容逐步压缩为多个 Skill 节点。
- 鼠标经过 Skill 卡片时显示触发语言和相邻节点。
- 安装命令复制后有明确反馈。
- 投稿步骤和 CI 检查显示实时状态。

避免持续漂浮、粒子背景和大面积视差。它们会增加噪音并降低文档阅读效率。

## 13. 技术架构建议

### 13.1 推荐技术栈

- 框架：Astro。
- 内容：Markdown/MDX + YAML Registry。
- 交互岛：React、Preact 或 Svelte，仅用于搜索、筛选、安装命令和投稿向导。
- 样式：CSS Design Tokens + Tailwind 或轻量组件层。
- 搜索：构建时生成索引，使用 Pagefind 或 Fuse.js；首版不需要搜索服务。
- Schema：JSON Schema + YAML 解析。
- Skill 规范校验：官方 `skills-ref` 加项目自定义规则。
- CI：GitHub Actions。
- 部署：首版 GitHub Pages；若中国大陆访问质量成为核心指标，再把同一静态产物部署到国内对象存储/CDN。

选择 Astro 的原因：

- 内容页和 SEO 友好。
- 默认输出静态页面，无服务器成本。
- 允许局部交互，不必把整个网站做成 SPA。
- 适合从 Git 仓库内容构建详情页。

### 13.2 数据流

```mermaid
flowchart TD
  R[registry 目录] --> V[Schema 与 Skill 校验]
  V --> J[生成 catalog.json]
  J --> W[Astro 静态页面]
  J --> S[搜索索引]
  J --> M[自动生成 README 列表]
  W --> P["GitHub Pages / 静态托管"]
```

Registry 是唯一事实来源。网站不直接解析 README 表格，README 也不再手工维护收录列表。

### 13.3 不需要的首版组件

- 数据库。
- 后台管理页面。
- GitHub OAuth。
- 用户画像和推荐算法。
- 在线执行陌生 Skill。
- 评分、评论、收藏和排行榜。
- 上传原始书籍、视频或受版权保护的全文。

## 14. 安全、版权与治理

### 14.1 安全边界

- 自动校验只能把提交内容当作数据，不能执行投稿中的脚本。
- PR 工作流使用最小权限和只读 Token。
- 禁止 secrets、私钥、cookie、访问令牌和个人敏感信息。
- 禁止符号链接逃逸、超大二进制、构建产物和依赖目录。
- 外部仓库只做结构与元数据检查，不自动安装或运行。

### 14.2 版权边界

投稿者必须确认：

- 有权提交 Skill 本身及附带素材。
- 原文引用控制在合理范围，并标注来源。
- 不上传原书、完整课程、受版权保护字幕全集等材料。
- 仓库或目录拥有明确许可证。
- 外部仓库链接不等于 Cangjie 对内容版权做保证。

### 14.3 治理文件

首版建议补齐：

- `CONTRIBUTING.md`
- `CODE_OF_CONDUCT.md`
- `SECURITY.md`
- `PULL_REQUEST_TEMPLATE.md`
- Registry schema 与示例目录
- 收录、认证、下架和争议处理规则

## 15. SEO 与传播

每个 Pack 和 Skill 都应该拥有独立、可索引的 URL，并生成：

- 独立 title 与 description。
- Open Graph 分享图。
- JSON-LD 中的软件或创意作品信息。
- canonical URL。
- sitemap。

适合内容传播的页面模板：

- “这本书被蒸馏成了哪些 Skills？”
- “当你遇到什么问题时应该调用这个 Skill？”
- “一个 Skill 如何通过正例、诱饵和边界测试？”

分享图不只展示封面，应突出“解决的问题 + Skill 数量 + 质量等级”，让社交媒体用户在不读正文时也理解价值。

## 16. 国际化与可访问性

仓库已有中文、英文、日文 README，官网架构应从第一天支持多语言字段，但首版可以只完整发布中文。

建议：

- Registry 的 slug 保持语言无关。
- 标题、摘要、详情正文使用 locale 文件或多语言 Markdown。
- 缺少翻译时回退到中文并明确标识，而不是隐藏页面。
- 所有交互支持键盘操作、焦点样式和减少动态效果。
- 颜色不是唯一状态信号；质量徽章同时提供文字。
- 正文对比度、字号和行宽优先于视觉实验。

## 17. 分阶段实施

### Phase 0：规范整理（2—3 天）

- 定义 Registry schema。
- 明确 Pack、Skill、外部链接、仓库托管四个概念。
- 确定质量等级与人工审核清单。
- 统一 `SKILL.md` 标准字段策略。
- 把当前 22 个 Pack 迁移为 Registry 条目。

交付标准：所有现有条目可被脚本读取，统计数字能自动生成。

### Phase 1：官网 MVP（5—8 天）

- 首页。
- 学会使用。
- Skill 库与搜索筛选。
- Pack / Skill 详情页。
- 方法论页。
- 投稿说明页。
- GitHub Pages 部署、SEO、基础统计。

交付标准：用户可以完成“发现 → 安装 → 验证”的闭环。

### Phase 2：GitHub 投稿闭环（4—6 天）

- 投稿向导。
- 两种模式的文件生成。
- 浏览器本地目录预检。
- PR 模板、CODEOWNERS、自动标签。
- Registry、Skill 规范、安全和构建检查。
- 合并后自动更新官网与 README。

交付标准：一个外部贡献者不需要维护者代写文件即可完成合格 PR。

### Phase 3：质量与社区（按真实需求）

- 自动生成 PR 预览。
- 贡献者页面。
- 质量报告和测试历史。
- 更完整的平台兼容性矩阵。
- GitHub App 一键创建 PR，仅在投稿量证明有必要时开发。

## 18. MVP 验收清单

### 使用体验

- 新用户可在 3 分钟内看懂 Skill、选择平台、复制命令并完成验证。
- 移动端、桌面端均可完成搜索、安装和投稿阅读。
- 每个可复制动作都有反馈。
- 安装说明不使用未经验证的平台命令。

### 内容与发现

- 当前所有 Pack 均有独立详情页。
- Pack 与原子 Skill 不混淆。
- 搜索能匹配中文标题、英文 slug、触发语言和领域。
- 所有计数来自 Registry 自动生成。

### 投稿与审核

- 外部链接和托管目录共用一套 entry schema。
- PR 自动检查失败时给出可操作的错误信息。
- 合并后无需人工修改 README 和网站数据。
- 投稿代码不会在高权限 CI 中被执行。
- 每个收录项都有作者、来源、许可证和质量等级。

### 品牌与视觉

- 视觉不是通用 AI 渐变 SaaS 风格。
- 真实 Skill 名称和数据出现在视觉表达中。
- 中文长文阅读体验稳定。
- 动效可关闭，不影响核心操作。

## 19. 主要风险与应对

### 风险一：把“收录”误解为“官方认证”

应对：建立三层质量徽章，详情页明确维护者、测试和审核范围。

### 风险二：提交规则太重，社区不愿贡献

应对：外部链接投稿只要求一个目录和结构化元数据；完整 RIA-TV++ 仅用于“官方蒸馏”认证，不把所有社区 Skill 强行变成拆书产物。

### 风险三：提交规则太松，品牌质量下降

应对：格式自动化、价值人工化；把反场景、许可证和最小测试作为合并底线。

### 风险四：GitHub 对普通用户门槛较高

应对：官网生成全部内容，用户只完成 GitHub 的 fork、粘贴或上传、创建 PR；用截图和动图把步骤压缩到一条路径。

### 风险五：外部仓库后来失效或变质

应对：定时只读检查链接、许可证和 Skill 路径；失效条目标记为“维护异常”，人工确认后下架，不自动删除。

## 20. 最终推荐

我建议把官网定义为：

> 一个以 GitHub 为治理基础、以可验证 Agent Skills 为内容单位、以“学会使用—发现能力—参与贡献”为核心闭环的开放知识基础设施。

最重要的不是先做一个漂亮首页，而是先确定 Registry 目录和质量规则。只要 Registry 是稳定的，首页、搜索、README、贡献者榜单、API、CLI 甚至未来的 GitHub App 都可以从同一份数据自然生长出来。

## 21. 参考依据

- Agent Skills 官方规范：https://agentskills.io/specification
- Agent Skills 创建最佳实践：https://agentskills.io/skill-creation/best-practices
- Agent Skills 评测方法：https://agentskills.io/skill-creation/evaluating-skills
- Anthropic Skills 示例仓库：https://github.com/anthropics/skills
- GitHub 创建新文件与自动 fork/PR：https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files
- GitHub 编辑其他仓库并自动 fork/PR：https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
- GitHub PR 模板：https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates
- GitHub Pages 发布：https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- GitHub Actions `pull_request_target` 安全说明：https://docs.github.com/en/actions/reference/security/securely-using-pull_request_target