playbook/cangjie-skill/docs/plans/2026-07-13-cangjie-skill-website-mvp-functional-spec.md

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 页面地图

首版只有五个核心页面：

flowchart TD
  H[首页] --> L[使用教程]
  H --> S[Skill 库]
  H --> U[提交 Skill]
  S --> D[Skill Pack 详情]
  D --> L
  U --> G[GitHub PR]

路由：

/
/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 平台配置

平台信息不硬编码在页面组件里，使用一个配置文件：

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 是否有效。

输出只有一个必须提交的文件：

registry/<slug>/entry.yaml

网站生成内容并引导用户在 GitHub 创建新文件。无写权限时，GitHub 完成 fork 和 PR 流程。

8.5 本地文件夹模式

浏览器通过目录选择读取文件，仅在本地完成预检，不上传到官网服务器。

自动预检：

• 是否存在 SKILL.md。
• 目录名和 name 是否一致。
• frontmatter 是否可解析。
• 是否包含秘密信息和异常大文件。
• 是否存在不安全符号链接或不允许的二进制文件。
• 文件数是否适合 GitHub Web 上传。

输出：

registry/<slug>/
├── entry.yaml
└── skill/
    ├── SKILL.md
    └── optional-resources/

网站提供“下载投稿包”，然后引导用户：fork 仓库 → 上传目录 → 创建 PR。

8.6 提交失败与恢复

• 表单内容保存在浏览器本地，刷新后可恢复。
• GitHub 跳转失败时仍可下载 entry.yaml 或投稿包。
• 文件夹不支持时显示 Git / GitHub Desktop 的替代流程。
• 验证错误必须指出文件、字段和修复建议，不能只显示“提交失败”。

9. Registry 数据结构

9.1 最小目录

registry/<slug>/
├── entry.yaml
└── skill/          # 仅仓库托管模式存在

不再强制每个条目额外提交 README.md。详情页由 entry.yaml 和 Skill 内容生成，减少 PR 文件数量。

9.2 最小 entry.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，生成但不要求手工编辑：

generated/catalog.json
generated/search-index.json
generated/stats.json

这些文件可以作为构建缓存，也可以只存在于 CI 产物中。Registry 始终是唯一事实来源。

10. 审核流程

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 数据流

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 或独立后台。