556 lines
16 KiB
Markdown
556 lines
16 KiB
Markdown
# Cangjie Skill 官网 MVP 功能与页面布局规格
|
||
|
||
日期：2026-07-13
|
||
状态：待确认的功能设计稿
|
||
原则：功能优先、静态优先、GitHub 原生、暂缓视觉精修
|
||
|
||
## 1. 产品范围
|
||
|
||
首版官网只完成两个闭环：
|
||
|
||
1. 用户找到一个适合自己的 Skill Pack，学会安装并完成一次调用。
|
||
2. 贡献者提交一个外部 GitHub 仓库或本地 Skill 文件夹，并进入 GitHub PR 审核流程。
|
||
|
||
首版不做：
|
||
|
||
- 登录、站内账号和独立后台。
|
||
- 收藏、评分、评论和排行榜。
|
||
- 在线运行陌生 Skill。
|
||
- 多语言、深色模式和复杂动效。
|
||
- 独立的贡献者中心。
|
||
- 每个原子 Skill 的独立详情页。
|
||
- 数据库、搜索服务和推荐算法。
|
||
|
||
当前约 22 个 Pack 直接进入 Registry。Pack 内约 300 个原子 Skills 在 Pack 详情页中列出，并参与搜索，但首版不为每个原子 Skill 生成单独页面。
|
||
|
||
## 2. MVP 页面地图
|
||
|
||
首版只有五个核心页面：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
H[首页] --> L[使用教程]
|
||
H --> S[Skill 库]
|
||
H --> U[提交 Skill]
|
||
S --> D[Skill Pack 详情]
|
||
D --> L
|
||
U --> G[GitHub PR]
|
||
```
|
||
|
||
路由：
|
||
|
||
```text
|
||
/
|
||
/learn
|
||
/skills
|
||
/skills/[slug]
|
||
/submit
|
||
```
|
||
|
||
GitHub、README、完整 RIA-TV++ 方法论和项目介绍先作为外部链接，不单独建设官网页面。
|
||
|
||
## 3. 全站公共布局
|
||
|
||
### 3.1 页头
|
||
|
||
| 区域 | 内容 | 行为 |
|
||
|---|---|---|
|
||
| 左侧 | Cangjie Skill / 仓颉 Skill | 点击回首页 |
|
||
| 中间 | 使用教程、Skill 库、提交 Skill | 当前页面高亮 |
|
||
| 右侧 | GitHub | 新窗口打开仓库 |
|
||
|
||
移动端把三个导航项收进简单菜单。首版不做悬浮玻璃效果、搜索弹窗或多层下拉菜单。
|
||
|
||
### 3.2 页脚
|
||
|
||
只保留：
|
||
|
||
- GitHub 仓库。
|
||
- README / 方法论。
|
||
- License。
|
||
- 问题反馈。
|
||
- 公众号和交流群入口。
|
||
|
||
## 4. 首页 `/`
|
||
|
||
首页的任务是分流，不承担完整文档功能。
|
||
|
||
### 4.1 页面顺序
|
||
|
||
| 顺序 | 模块 | 必须展示的内容 | 主要动作 |
|
||
|---|---|---|---|
|
||
| 1 | Hero | 产品一句话、简短解释 | 开始使用、浏览 Skill 库 |
|
||
| 2 | 数据概览 | Pack 数、原子 Skill 数、RIA-TV++ | 无 |
|
||
| 3 | 三步说明 | 选择、安装、调用 | 查看使用教程 |
|
||
| 4 | 精选 Packs | 6 个代表性 Pack | 查看详情、查看全部 |
|
||
| 5 | 提交入口 | 两种投稿方式说明 | 提交 Skill |
|
||
| 6 | 页脚 | 项目与社区链接 | 外部链接 |
|
||
|
||
### 4.2 Hero 文案
|
||
|
||
标题：
|
||
|
||
> 把读过、看过、听过的知识，变成 Agent 真正会用的能力。
|
||
|
||
说明：
|
||
|
||
> Cangjie Skill 把书、课程和长内容中的方法论，蒸馏成可触发、可执行、可测试的 Agent Skills。
|
||
|
||
按钮：
|
||
|
||
- 主按钮：开始使用 → `/learn`
|
||
- 次按钮：浏览 Skill 库 → `/skills`
|
||
|
||
### 4.3 数据概览
|
||
|
||
数据必须从 Registry 构建时计算，禁止写死：
|
||
|
||
- `pack_count`
|
||
- `skill_count`
|
||
- `contributor_count`
|
||
|
||
RIA-TV++ 是方法标签，不作为动态计数。
|
||
|
||
### 4.4 三步说明
|
||
|
||
1. 找到适合当前问题的 Pack。
|
||
2. 复制到 Agent 的 Skills 目录。
|
||
3. 用测试 Prompt 确认它能正确触发。
|
||
|
||
### 4.5 精选 Packs
|
||
|
||
首版固定展示 6 个，由 `featured: true` 决定。每项只显示：
|
||
|
||
- 名称。
|
||
- 一句话用途。
|
||
- 来源类型。
|
||
- 原子 Skill 数量。
|
||
- 2—3 个标签。
|
||
- 质量等级。
|
||
- 查看详情。
|
||
|
||
不在首页显示完整简介、测试报告或全部子 Skills。
|
||
|
||
## 5. 使用教程 `/learn`
|
||
|
||
这个页面只解决“怎么安装、怎么验证”。
|
||
|
||
### 5.1 页面布局
|
||
|
||
| 区域 | 内容 |
|
||
|---|---|
|
||
| 页面标题 | 3 分钟开始使用 Cangjie Skills |
|
||
| 工具选择 | 经过验证的平台标签页 |
|
||
| 安装范围 | 个人级 / 项目级 |
|
||
| 安装命令 | 可复制命令和目标目录 |
|
||
| 验证步骤 | 查看 Skill、测试正例、测试反例 |
|
||
| 常见问题 | 目录、文件名、frontmatter、会话刷新 |
|
||
| 下一步 | 前往 Skill 库 |
|
||
|
||
### 5.2 平台配置
|
||
|
||
平台信息不硬编码在页面组件里，使用一个配置文件：
|
||
|
||
```yaml
|
||
platforms:
|
||
- id: claude-code
|
||
name: Claude Code
|
||
status: verified
|
||
user_skill_dir: ~/.claude/skills/
|
||
project_skill_dir: .claude/skills/
|
||
- id: codex
|
||
name: OpenAI Codex
|
||
status: experimental
|
||
user_skill_dir: TBD
|
||
project_skill_dir: TBD
|
||
```
|
||
|
||
实现前必须逐个平台验证目录和发现方式。未验证的平台显示“实验性”，不能给出看似确定的命令。
|
||
|
||
### 5.3 安装步骤
|
||
|
||
1. 用户选择平台。
|
||
2. 用户选择个人级或项目级。
|
||
3. 页面展示目标目录和复制命令。
|
||
4. 页面展示一个来自该 Pack 的 `should_trigger` Prompt。
|
||
5. 页面展示一个 `should_not_trigger` Prompt，帮助确认触发边界。
|
||
|
||
### 5.4 错误处理
|
||
|
||
常见错误按优先级展示：
|
||
|
||
- 目录名与 `name` 不一致。
|
||
- 文件名不是大写 `SKILL.md`。
|
||
- YAML frontmatter 无效。
|
||
- 只复制了 `SKILL.md`，遗漏所需的 `scripts/` 或 `references/`。
|
||
- 安装后没有重新打开会话。
|
||
- 当前客户端尚不支持 Agent Skills 标准。
|
||
|
||
## 6. Skill 库 `/skills`
|
||
|
||
### 6.1 页面目标
|
||
|
||
让用户通过“我要解决什么问题”找到 Pack，而不是只按书名浏览。
|
||
|
||
### 6.2 页面布局
|
||
|
||
| 区域 | 内容 | 交互 |
|
||
|---|---|---|
|
||
| 标题区 | 已收录的 Cangjie Skill Packs | 无 |
|
||
| 搜索区 | 单个搜索框 | 输入即时过滤 |
|
||
| 筛选区 | 来源、领域、质量等级 | 可组合、多选 |
|
||
| 结果信息 | 共 N 个结果、清除筛选 | 重置 |
|
||
| 结果列表 | Pack 行或简单卡片 | 进入详情 |
|
||
| 空状态 | 无匹配结果 | 清除筛选、提交新 Skill |
|
||
|
||
### 6.3 搜索范围
|
||
|
||
前端搜索索引包含：
|
||
|
||
- Pack 中文名、英文名和 slug。
|
||
- 一句话用途。
|
||
- 来源名称和作者。
|
||
- 标签和领域。
|
||
- Pack 内原子 Skill 的名称。
|
||
- 典型触发语言。
|
||
|
||
首版使用构建时 JSON + 浏览器本地搜索，不接外部搜索服务。
|
||
|
||
### 6.4 首版筛选项
|
||
|
||
- 来源：书籍、视频、课程、播客、访谈、资料集、实战经验。
|
||
- 领域：投资、商业、写作、营销、学习、组织、决策、技术、其他。
|
||
- 质量：官方蒸馏、社区认证、社区收录。
|
||
|
||
首版不做平台筛选、更新时间筛选、Star 排序和复杂综合排序。
|
||
|
||
### 6.5 每个结果项
|
||
|
||
必须显示：
|
||
|
||
- Pack 名称。
|
||
- 一句话用途。
|
||
- 来源。
|
||
- 原子 Skill 数量。
|
||
- 质量徽章。
|
||
- 最多 3 个标签。
|
||
- 查看详情。
|
||
|
||
可选显示 GitHub Stars，但不参与默认排序。
|
||
|
||
默认排序：`featured` 优先，其余按名称稳定排序。后续有真实使用数据后再设计推荐排序。
|
||
|
||
## 7. Skill Pack 详情 `/skills/[slug]`
|
||
|
||
### 7.1 页面布局
|
||
|
||
| 顺序 | 模块 | 内容 |
|
||
|---|---|---|
|
||
| 1 | 标题区 | 名称、用途、来源、作者、维护者、许可证、质量等级 |
|
||
| 2 | 操作区 | 查看安装方法、打开 GitHub |
|
||
| 3 | 适用场景 | 3—5 个真实使用场景 |
|
||
| 4 | 原子 Skills | 可搜索的子 Skill 列表 |
|
||
| 5 | 推荐使用 | 推荐先安装哪些、测试 Prompt |
|
||
| 6 | 项目资料 | DIGEST、INDEX、GLOSSARY、测试报告等可用链接 |
|
||
| 7 | 贡献信息 | 维护者、贡献者、更新时间、问题反馈 |
|
||
|
||
### 7.2 原子 Skill 列表
|
||
|
||
每个子 Skill 只展示：
|
||
|
||
- `name`
|
||
- 中文标题。
|
||
- `description` 的精简版本。
|
||
- 触发语言。
|
||
- 是否有测试文件。
|
||
- 在 GitHub 查看原始 `SKILL.md`。
|
||
|
||
首版点击子 Skill 不进入独立详情页，可以展开查看摘要或直接跳 GitHub。
|
||
|
||
### 7.3 两种来源的差异
|
||
|
||
外部仓库：
|
||
|
||
- “打开 GitHub”跳到贡献者仓库。
|
||
- 网站在构建时读取 Registry 中保存的数据。
|
||
- 外部仓库不可访问时显示“来源暂时不可用”，但保留已构建页面。
|
||
|
||
仓库托管：
|
||
|
||
- “打开 GitHub”跳到 Cangjie 仓库对应目录。
|
||
- 安装命令直接复制本仓库中的 Skill 路径。
|
||
|
||
## 8. 提交 Skill `/submit`
|
||
|
||
### 8.1 页面目标
|
||
|
||
让贡献者生成一个合格的 Registry 目录并完成 GitHub PR，而不是在网站后台保存投稿。
|
||
|
||
### 8.2 页面步骤
|
||
|
||
| 步骤 | 页面内容 | 输出 |
|
||
|---|---|---|
|
||
| 1 | 选择提交方式 | 外部 GitHub / 本地文件夹 |
|
||
| 2 | 填写基本信息 | Registry entry 草稿 |
|
||
| 3 | 自动预检 | 错误、警告、通过项 |
|
||
| 4 | 预览提交内容 | `entry.yaml` 与目录结构 |
|
||
| 5 | 前往 GitHub | 创建文件或上传目录并发 PR |
|
||
|
||
页面顶部始终显示当前进度。错误未解决前不允许进入最后一步；警告可以继续，但会带入 PR 检查清单。
|
||
|
||
### 8.3 公共字段
|
||
|
||
- 名称。
|
||
- slug。
|
||
- 一句话用途。
|
||
- 类型：Pack / 单个 Skill。
|
||
- 来源类型、来源名称、原作者。
|
||
- 投稿者 GitHub 用户名。
|
||
- 许可证。
|
||
- 领域标签，最多 5 个。
|
||
- 典型使用场景，至少 2 个。
|
||
- 版权确认复选框。
|
||
|
||
贡献者不能自己选择“官方蒸馏”或“社区认证”。投稿时统一为 `pending`，质量等级由维护者审核后设置。
|
||
|
||
### 8.4 外部 GitHub 模式
|
||
|
||
额外字段：
|
||
|
||
- 仓库 URL。
|
||
- 默认分支，可自动发现。
|
||
- Skill 路径。
|
||
|
||
自动预检：
|
||
|
||
- URL 是否为公开 GitHub 仓库。
|
||
- 声明路径是否存在。
|
||
- 是否找到至少一个 `SKILL.md`。
|
||
- 是否能识别许可证。
|
||
- `SKILL.md` 基本 frontmatter 是否有效。
|
||
|
||
输出只有一个必须提交的文件：
|
||
|
||
```text
|
||
registry/<slug>/entry.yaml
|
||
```
|
||
|
||
网站生成内容并引导用户在 GitHub 创建新文件。无写权限时，GitHub 完成 fork 和 PR 流程。
|
||
|
||
### 8.5 本地文件夹模式
|
||
|
||
浏览器通过目录选择读取文件，仅在本地完成预检，不上传到官网服务器。
|
||
|
||
自动预检：
|
||
|
||
- 是否存在 `SKILL.md`。
|
||
- 目录名和 `name` 是否一致。
|
||
- frontmatter 是否可解析。
|
||
- 是否包含秘密信息和异常大文件。
|
||
- 是否存在不安全符号链接或不允许的二进制文件。
|
||
- 文件数是否适合 GitHub Web 上传。
|
||
|
||
输出：
|
||
|
||
```text
|
||
registry/<slug>/
|
||
├── entry.yaml
|
||
└── skill/
|
||
├── SKILL.md
|
||
└── optional-resources/
|
||
```
|
||
|
||
网站提供“下载投稿包”，然后引导用户：fork 仓库 → 上传目录 → 创建 PR。
|
||
|
||
### 8.6 提交失败与恢复
|
||
|
||
- 表单内容保存在浏览器本地，刷新后可恢复。
|
||
- GitHub 跳转失败时仍可下载 `entry.yaml` 或投稿包。
|
||
- 文件夹不支持时显示 Git / GitHub Desktop 的替代流程。
|
||
- 验证错误必须指出文件、字段和修复建议，不能只显示“提交失败”。
|
||
|
||
## 9. Registry 数据结构
|
||
|
||
### 9.1 最小目录
|
||
|
||
```text
|
||
registry/<slug>/
|
||
├── entry.yaml
|
||
└── skill/ # 仅仓库托管模式存在
|
||
```
|
||
|
||
不再强制每个条目额外提交 `README.md`。详情页由 `entry.yaml` 和 Skill 内容生成，减少 PR 文件数量。
|
||
|
||
### 9.2 最小 `entry.yaml`
|
||
|
||
```yaml
|
||
schema_version: 1
|
||
slug: buffett-letters-skill
|
||
title: 巴菲特致股东的信
|
||
summary: 用于投资判断、企业分析和资本配置的 20 个方法论 Skills。
|
||
kind: pack
|
||
language: zh-CN
|
||
|
||
source:
|
||
type: book
|
||
title: 巴菲特致股东的信
|
||
creator: Warren Buffett
|
||
|
||
artifact:
|
||
type: external
|
||
repository: https://github.com/kangarooking/buffett-letters-skill
|
||
path: .
|
||
|
||
submitter:
|
||
github: kangarooking
|
||
|
||
tags:
|
||
- investment
|
||
- decision-making
|
||
|
||
use_cases:
|
||
- 评估企业长期竞争优势
|
||
- 在不确定估值中设置安全边际
|
||
|
||
license: MIT
|
||
quality: pending
|
||
featured: false
|
||
```
|
||
|
||
`quality` 与 `featured` 在合并前由维护者确认。
|
||
|
||
### 9.3 构建产物
|
||
|
||
构建脚本读取 Registry，生成但不要求手工编辑：
|
||
|
||
```text
|
||
generated/catalog.json
|
||
generated/search-index.json
|
||
generated/stats.json
|
||
```
|
||
|
||
这些文件可以作为构建缓存，也可以只存在于 CI 产物中。Registry 始终是唯一事实来源。
|
||
|
||
## 10. 审核流程
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[提交目录 PR] --> B[Schema 校验]
|
||
B --> C[Skill 格式校验]
|
||
C --> D[安全与链接检查]
|
||
D --> E[网站构建检查]
|
||
E --> F[人工质量审核]
|
||
F --> G[维护者设置质量等级]
|
||
G --> H[合并]
|
||
H --> I[自动部署官网]
|
||
```
|
||
|
||
### 10.1 自动检查
|
||
|
||
- 目录与 slug 一致。
|
||
- `entry.yaml` 符合 JSON Schema。
|
||
- 外部链接和声明路径存在。
|
||
- 托管 Skill 通过 Agent Skills 格式校验。
|
||
- 无秘密信息、超大文件和危险路径。
|
||
- 新条目不与现有 slug 重复。
|
||
- 全站能够成功构建。
|
||
|
||
PR 自动检查只读取投稿内容，不能执行投稿中的脚本。
|
||
|
||
### 10.2 人工检查
|
||
|
||
- 是否解决明确且重复出现的问题。
|
||
- `description` 是否能准确触发。
|
||
- 执行步骤是否可操作。
|
||
- 是否有明确反场景和边界。
|
||
- 来源和许可证是否可信。
|
||
- 测试是否包含正例、反例和边界。
|
||
|
||
### 10.3 质量等级
|
||
|
||
- `official-distilled`：Cangjie 官方按 RIA-TV++ 完整蒸馏。
|
||
- `community-certified`：社区维护，完成格式、质量和测试审核。
|
||
- `community-listed`：满足基本收录标准，尚未完成完整压力测试。
|
||
|
||
## 11. 技术方案
|
||
|
||
### 11.1 推荐实现
|
||
|
||
- Astro：静态页面和内容路由。
|
||
- YAML + JSON Schema：Registry。
|
||
- 构建时脚本：生成目录、统计和搜索索引。
|
||
- 少量浏览器 JavaScript：搜索、筛选、复制、投稿表单和本地目录预检。
|
||
- GitHub Actions：PR 校验和站点部署。
|
||
- GitHub Pages：首版托管。
|
||
|
||
### 11.2 数据流
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
R[Registry] --> V[校验脚本]
|
||
V --> C[Catalog 与搜索索引]
|
||
C --> A[Astro 页面]
|
||
A --> P[静态站点]
|
||
M[PR 合并] --> R
|
||
```
|
||
|
||
没有运行时数据库。用户访问的是构建完成的静态页面，投稿表单只在浏览器本地生成文件。
|
||
|
||
## 12. 基础视觉约束
|
||
|
||
在功能阶段只使用：
|
||
|
||
- 白色或暖白背景。
|
||
- 黑色正文。
|
||
- 一个主色用于按钮和链接。
|
||
- 系统字体。
|
||
- 统一的 8px 间距体系。
|
||
- 统一的按钮、输入框、标签和状态提示。
|
||
- 桌面最大内容宽度 1200px。
|
||
- 移动端单列布局。
|
||
|
||
首版不制作品牌插画、复杂图谱、封面系统和动效。页面信息层级正确后再统一升级视觉。
|
||
|
||
## 13. 验收标准
|
||
|
||
### 13.1 用户使用闭环
|
||
|
||
- 首页两个主按钮路径正确。
|
||
- 用户能搜索并筛选当前全部 Packs。
|
||
- 搜索子 Skill 名称能返回所属 Pack。
|
||
- 每个 Pack 都有可访问详情页。
|
||
- 用户能从详情页进入正确的安装说明和 GitHub 仓库。
|
||
|
||
### 13.2 投稿闭环
|
||
|
||
- 外部 GitHub 模式能生成合法 `entry.yaml`。
|
||
- 本地文件夹模式不会把文件上传到官网服务器。
|
||
- 无效 Skill 能得到具体错误信息。
|
||
- 用户能下载投稿包并进入 GitHub PR 流程。
|
||
- 合并新 Registry 条目后，下一次部署自动出现新页面。
|
||
|
||
### 13.3 安全与稳定性
|
||
|
||
- PR 校验不执行投稿脚本。
|
||
- 外部仓库失效不会导致整个网站构建失败。
|
||
- Registry 单个条目错误时能定位到具体文件。
|
||
- 无 JavaScript 时仍能浏览首页、列表和详情页。
|
||
- 移动端能完成浏览和阅读；本地文件夹投稿可提示改用桌面端。
|
||
|
||
## 14. 推荐开发顺序
|
||
|
||
1. 定义 `entry.yaml` Schema。
|
||
2. 把当前 22 个 Pack 迁入 Registry。
|
||
3. 编写校验与 Catalog 生成脚本。
|
||
4. 完成首页、列表、详情和教程页。
|
||
5. 完成外部 GitHub 投稿。
|
||
6. 完成本地文件夹预检和投稿包下载。
|
||
7. 接入 PR 校验和 GitHub Pages 部署。
|
||
8. 功能验收后再进入统一视觉设计。
|
||
|
||
## 15. 最终 MVP 决策
|
||
|
||
首版最重要的产品单位是 Skill Pack，不是每一个原子 Skill。原子 Skills 仍然会被索引、搜索和展示，但不单独建页。这能显著降低内容迁移、路由、SEO 和维护复杂度，又不影响用户发现具体能力。
|
||
|
||
首版最重要的后台是 GitHub PR，不是自建管理系统。只有当投稿量、非 GitHub 用户比例或维护者协作成本证明现有流程不足时，再考虑 GitHub App 或独立后台。
|