playbook/cangjie-skill/docs/requirements/2026-07-21-cangjie-skill-website-prd.md

仓颉 Skill 官方网站产品需求文档（PRD）

• 文档版本：V1.0
• 日期：2026-07-21
• 产品阶段：MVP 已实现，待推送、合并并正式部署
• 适用对象：产品、设计、前端、维护者、社区贡献者
• 需求基线：codex/website-mvp 分支

1. 文档目的

本文件用于统一仓颉 Skill 官方网站的产品范围、页面功能、数据规则、投稿审核流程、安装体验和验收标准。

它同时承担三项作用：

1. 作为当前 MVP 的功能说明，描述网站已经具备的能力。
2. 作为开发验收依据，明确每项功能的输入、行为、状态和结果。
3. 作为后续迭代边界，区分必须完成、可继续优化和暂不建设的功能。

本文优先描述产品行为。具体代码结构、组件名称和技术实现可以调整，但不得改变已经确认的用户流程。

2. 产品概述

2.1 产品名称

• 中文名：仓颉 Skill
• 英文名：Cangjie Skill
• 产品形态：知识蒸馏方法论官网 + 开放 Skill Registry

2.2 一句话定位

把书籍、课程、长视频、播客和其他高价值内容中的方法论，蒸馏成 Agent 可以直接安装、调用和复用的 Skills。

2.3 产品要解决的问题

网站需要解决四个核心问题：

1. 用户不知道仓颉 Skill 是什么，也不知道它与普通摘要、笔记和提示词的区别。
2. 用户知道某个 Skill 存在，但很难根据真实任务找到合适的 Skill Pack。
3. Skill 的安装方式过于技术化，普通用户不应该自己判断不同 Agent 的目录和复制命令。
4. 社区成员希望贡献 Skill，但项目不需要为首版建设账号、数据库和独立审核后台。

2.4 核心解决方案

• 用首页解释价值并完成用户分流。
• 用教程页教用户完成“选择—安装—调用—验证”。
• 用 Registry 展示并检索已经蒸馏好的 Skill Packs。
• 用统一安装提示词把安装工作交给 Agent。
• 用 GitHub Pull Request 作为公开、透明、可审计的投稿审核机制。

3. 产品目标与非目标

3.1 MVP 产品目标

编号	目标	成功结果
G-01	帮助新用户理解仓颉 Skill	用户能说清 Skill Pack、原子 Skill 和普通摘要的区别
G-02	帮助用户找到合适的 Skill	用户能通过搜索和筛选进入一个 Pack 详情页
G-03	降低安装门槛	用户只需复制一条提示词给 Agent，不必手动判断目录
G-04	完成一次真实调用	用户安装后能用自然语言让 Agent 调用对应方法
G-05	建立公开投稿闭环	贡献者能生成标准 Registry 文件并进入 GitHub PR 审核
G-06	保持低运维成本	网站不依赖账号系统、数据库和独立后端

3.2 MVP 明确不做

• 不做站内账号、登录和用户资料。
• 不做独立管理后台。
• 不做收藏、点赞、评分、评论和关注。
• 不做站内支付、交易和商业分成。
• 不做在线运行或沙箱执行陌生 Skill。
• 不做自动安装本地文件的桌面客户端。
• 不做每个原子 Skill 的独立详情页。
• 不做复杂推荐算法、个性化推荐和外部搜索服务。
• 不做多语言站点和深色模式。
• 不做复杂动效和高成本视觉系统。
• 不把原始受版权保护的书籍、课程、视频或音频作为 Registry 内容托管。

4. 用户角色

4.1 Skill 使用者

典型需求：

• 了解仓颉 Skill 的作用。
• 根据当前问题找到合适的 Pack。
• 把 Skill 安装到 Codex、Claude Code、Cursor、WorkBuddy 等 Agent。
• 确认安装是否成功并开始调用。

4.2 Skill 贡献者

典型需求：

• 提交一个已经公开到 GitHub 的 Skill 仓库。
• 提交一个尚未独立开源的本地 Skill 文件夹。
• 在提交前看到格式错误、敏感文件和目录问题。
• 保留自己的 GitHub 身份、仓库归属和维护权。

4.3 Registry 维护者

典型需求：

• 通过 Pull Request 查看所有变更。
• 自动验证 Registry Schema、目录和构建结果。
• 检查来源、版权、安全性、可执行性和重复度。
• 合并通过的投稿，并让网站自动更新。

4.4 Agent

Agent 是安装流程中的执行角色，需要：

• 读取统一安装规范。
• 识别自身运行环境和 Skills 目录。
• 检查来源仓库和文件结构。
• 安装全部必要文件。
• 处理冲突和风险。
• 汇报安装位置、安装结果和验证状态。

5. 核心用户旅程

5.1 使用 Skill 的主流程

flowchart LR
  A[进入官网] --> B[理解仓颉 Skill]
  B --> C[搜索或筛选 Skill Pack]
  C --> D[查看详情与使用场景]
  D --> E[复制 Agent 安装提示词]
  E --> F[Agent 读取安装规范]
  F --> G[Agent 检查并完成安装]
  G --> H[用户描述真实任务]
  H --> I[确认 Skill 已正确触发]

5.2 投稿审核主流程

flowchart LR
  A[选择投稿方式] --> B[填写 Registry 信息]
  B --> C[浏览器本地校验]
  C --> D[生成 entry.yaml 或 ZIP]
  D --> E[创建 GitHub Pull Request]
  E --> F[自动 Schema 与构建检查]
  F --> G[维护者人工审核]
  G --> H[合并到 main]
  H --> I[网站自动重新构建并上线]

6. 信息架构

6.1 核心路由

路由	页面	主要目标
/	首页	解释产品、展示规模、分流到使用、浏览和投稿
/learn	使用教程	教会用户选择、安装、调用和验证 Skill
/skills	Skills 目录	搜索、筛选并浏览 Skill Packs
/skills/[slug]	Skill Pack 详情	理解用途、复制安装提示词、查看来源
/submit	提交 Skill	生成投稿文件并进入 GitHub PR 流程
/install/cangjie-skill.md	Agent 安装规范	供 Agent 读取，不作为普通营销页面

6.2 全站导航

页头必须包含：

• 仓颉 Skill 品牌入口，点击返回首页。
• 使用教程。
• Skills。
• 提交 Skill。
• GitHub 外部链接。

当前路由需要通过 aria-current 标识。外部 GitHub 链接在新窗口打开。

页脚必须包含：

• 品牌与一句话说明。
• 使用教程。
• Skill 目录。
• 参与共建。
• GitHub。

7. 功能优先级定义

优先级	含义
P0	MVP 必须具备；缺失会导致核心流程无法完成
P1	上线后应优先完善；不会阻断主流程
P2	后续增长或体验增强

本文中标记“已实现”表示当前分支已有对应功能；“待发布”表示代码已存在，但尚未进入正式 GitHub Pages；“后续”表示尚未实现。

8. 首页需求

8.1 页面目标

首页只承担三项任务：

1. 让第一次访问的人迅速理解产品价值。
2. 让使用者进入 Skill 目录或教程。
3. 让贡献者进入投稿流程。

8.2 Hero 模块

需求编号	优先级	状态	需求
FR-HOME-001	P0	已实现	展示主标题“把知识，变成 AI 可以执行的方法”
FR-HOME-002	P0	已实现	展示仓颉 Skill 是知识蒸馏方法和开放 Skill 目录
FR-HOME-003	P0	已实现	提供“浏览 Skills”主按钮，进入 /skills
FR-HOME-004	P0	已实现	提供“从零开始使用”按钮，进入 /learn

8.3 Registry 数据概览

首页必须从 Registry 构建时动态计算并展示：

• Skill Pack 数。
• 原子 Skill 总数。
• Knowledge Domains 数。
• Contributor 数。

当前数据基线：

• 22 个 Skill Packs。
• 300 个原子 Skills。
• 23 个知识领域。
• 2 个来源贡献者。

禁止在页面组件中手工维护这些数字。新增或删除 Registry 条目后，统计必须自动变化。

8.4 三步使用说明

步骤固定为：

1. 选择 Skill Pack。
2. 交给 Agent 安装。
3. 描述真实任务。

安装说明不得再把 git clone、cp -R 或某一个 Agent 的目录作为普通用户默认流程。

8.5 精选 Skill Packs

需求编号	优先级	状态	需求
FR-HOME-010	P0	已实现	从 featured: true 的 Registry 条目中读取精选 Pack
FR-HOME-011	P0	已实现	首页最多展示 6 个精选 Pack
FR-HOME-012	P0	已实现	卡片展示质量、原子 Skill 数、名称、简介、领域和详情入口
FR-HOME-013	P0	已实现	提供查看全部入口

8.6 共建入口

首页底部必须明确说明：

• 无需注册独立账号。
• 投稿生成标准 Registry 文件。
• GitHub Pull Request 是审核入口。

主按钮进入 /submit。

9. 使用教程需求

9.1 页面目标

教程页帮助用户完成以下认知：

• Skill Pack 是什么。
• 如何选择 Pack。
• 如何把安装交给 Agent。
• 如何开始调用。
• 如何确认 Skill 已生效。

9.2 页面结构

教程由五个连续步骤和常见问题组成：

1. 理解 Skill Pack 目录。
2. 选择适合当前任务的 Pack。
3. 把安装提示词交给 Agent。
4. 用自然语言描述真实任务。
5. 验证 Skill 是否生效。
6. 常见问题。

桌面端展示页内目录；移动端可以隐藏目录，但正文锚点必须保留。

9.3 安装提示词示例

教程必须展示可理解的完整示例：

请根据 https://kangarooking.github.io/cangjie-skill/install/cangjie-skill.md，
从 https://github.com/kangarooking/buffett-letters-skill
安装 buffett-letters-skill。

固定安装规范地址为：

https://kangarooking.github.io/cangjie-skill/install/cangjie-skill.md

该地址只有在官网部署完成后才可访问。发布前必须把安装规范文件与网站同时部署，避免生产页面引用 404。

9.4 Agent 安装结果说明

教程需要告诉用户 Agent 将自动完成：

• 识别当前 Agent。
• 判断全局或项目级 Skills 目录。
• 读取来源仓库。
• 检查 SKILL.md、风险和同名冲突。
• 安装脚本、模板与资源。
• 验证并报告安装结果。

以下情况 Agent 必须暂停并请求确认：

• 覆盖存在本地修改的同名 Skill。
• 执行未审查脚本。
• 需要密钥、凭证或个人信息。
• 需要提升系统权限。
• 来源不可验证或存在明显风险。

9.5 调用和验证

用户安装后可以直接描述业务任务，不要求记忆命令。

验证 Prompt 至少需要让 Agent 说明：

• 使用了哪个 Skill。
• 为什么选择它。
• 它要求遵循哪些步骤。

9.6 常见问题

P0 必须覆盖：

• Agent 没有识别 Skill。
• 一次安装多个 Skill 的冲突。
• Skill 是否会上传用户资料。
• 安装后是否需要新会话或重新扫描。

10. Skills 目录需求

10.1 页面目标

用户应当根据“我要解决什么问题”发现 Skill，而不只是按书名或仓库名浏览。

10.2 列表内容

每张 Skill Card 必须展示：

• 质量等级。
• 原子 Skill 数。
• Pack 名称。
• 一句话简介。
• 领域标签。
• 详情页入口。

10.3 搜索

当前本地搜索范围：

• 名称。
• slug。
• summary。
• domains。
• use_cases。

搜索行为：

• 不区分大小写。
• 去除首尾空格。
• 输入后即时过滤，不需要提交。
• 没有关键词时展示全部。

P1 扩展项：

• 把原子 Skill 名称和触发描述纳入索引。
• 支持拼音或中英文别名。
• 支持结果相关性排序。

10.4 筛选

P0 筛选维度：

• 领域。
• 质量：已验证、社区收录、实验性。
• 来源：GitHub 仓库、仓库内置。

筛选条件可以组合，结果取交集。

10.5 URL 状态

当前已实现：

• q：搜索关键词。
• domain：领域。
• quality：质量。

P1 要求：

• source 同样写入 URL。
• 页面加载时恢复全部筛选条件。
• 分享 URL 后接收者看到相同结果。

10.6 结果状态

必须包含：

• 全部结果计数。
• 筛选后的结果计数。
• 重置筛选。
• 无匹配结果空状态。
• 空状态中的“清空筛选”操作。

11. Skill Pack 详情页需求

11.1 页面目标

详情页需要回答四个问题：

1. 这是什么？
2. 它适合解决什么问题？
3. 怎样交给 Agent 安装？
4. 来源是否公开、当前质量状态是什么？

11.2 页面信息结构

顶部：

• 返回 Skills 目录。
• 质量等级。
• 原子 Skill 数。
• 领域。
• Pack 名称。
• 简介。

页内导航：

• 概览。
• 使用场景。
• 如何使用。
• 来源信息。

主体采用双栏结构：

• 左侧：概览、使用场景、使用步骤和来源。
• 右侧：Agent 安装卡和 Registry 元数据。

移动端右侧安装卡移动到正文前方，确保核心动作优先出现。

11.3 Agent 安装卡

需求编号	优先级	状态	需求
FR-DETAIL-010	P0	已实现	根据 Registry 条目自动生成安装提示词
FR-DETAIL-011	P0	已实现	提供“复制安装提示词”按钮
FR-DETAIL-012	P0	已实现	复制成功后显示短暂成功反馈
FR-DETAIL-013	P0	已实现	提供“查看安装规范”链接
FR-DETAIL-014	P0	已实现	提供“查看源代码”链接
FR-DETAIL-015	P0	已实现	不把手动 Git 命令作为默认安装流程

GitHub 来源的提示词格式：

请根据 {安装规范 URL}，从 {source_url} 安装 {slug}。

仓库内置来源的提示词格式：

请根据 {安装规范 URL}，
从 {source_url} 中的 {skill_path} 安装 {slug}。

11.4 概览

概览需要展示：

• Pack 简介。
• 原子 Skill 数。
• 领域数量。
• 支持语言数量。

11.5 使用场景

每个 Pack 展示 1—6 个 use_cases。使用场景必须描述用户任务，不应只是抽象主题词。

正确示例：

• 分析企业长期价值。
• 检查投资决策的关键假设。

不推荐示例：

• 投资。
• 思考。

11.6 如何使用

固定为三步：

1. 把安装提示词发给 Agent。
2. 说清楚真实任务。
3. 确认调用了正确方法。

页面需要提供一条通用调用示例。

11.7 来源信息

必须展示：

• GitHub 仓库路径。
• 可点击的源仓库入口。
• Registry 的 slug、质量、领域、语言、来源类型和状态。
• Registry 文件的修改路径。

12. Agent 安装规范需求

12.1 文件与地址

• 源文件：website/public/install/cangjie-skill.md
• 正式地址：https://kangarooking.github.io/cangjie-skill/install/cangjie-skill.md
• 内容类型：Markdown 文本。
• 目标读者：Agent。

12.2 安装位置判断

规范必须包含常见 Agent 的 Skills 目录：

• Codex。
• Claude Code。
• Cursor。
• Windsurf。
• Gemini CLI。
• QoderWork。
• WorkBuddy。
• 其他 Agent 的兜底判断方式。

如果用户明确要求安装到当前项目，优先使用项目级目录；否则使用全局目录。

12.3 来源检查

Agent 必须：

• 确认 URL 可访问。
• 记录仓库版本或 commit。
• 在临时目录检查，不直接覆盖。
• 阅读 README 和 SKILL.md。
• 检查脚本、外部下载、凭证要求和目录冲突。

12.4 安装范围

Agent需要查找全部 SKILL.md，并把包含 SKILL.md 的目录及其必要脚本、模板和资源完整安装。

不得复制：

• .git。
• 构建缓存。
• .env。
• 密钥。
• 无关大型素材。
• 明显不属于 Skill 运行所需的文件。

12.5 冲突策略

• 内容与版本相同：跳过并说明。
• 可以安全升级：保留必要配置后更新。
• 存在本地修改：停止覆盖并询问。
• 无法判断安全性：停止并说明。

12.6 安装结果

Agent 最终必须报告：

• 来源。
• 版本或 commit。
• 安装目录。
• 已安装或已更新的 Skill。
• 被跳过的内容。
• 风险提示。
• 验证结果。

安装成功后不得自动执行 Skill 的业务任务，除非用户同时提出该任务。

13. 提交 Skill 页面需求

13.1 页面目标

让贡献者在没有账号系统和后台的情况下，生成符合规范的投稿文件，并进入 GitHub Pull Request 审核。

13.2 审核流程说明

页面顶部展示四步：

1. 填写信息。
2. 发起 PR。
3. 自动检查。
4. 人工审核。

页面必须说明：

• 所有审核公开发生在 GitHub。
• 网站不会在后台保存所填信息。
• 自动检查通过不代表一定合并。

13.3 投稿模式 A：公开 GitHub 仓库

适用于已经公开开源的 Skill。

输入：

• Pack 名称。
• slug。
• 简介。
• GitHub 仓库 URL。
• 原子 Skill 数量。
• 语言。
• 领域标签。
• 使用场景。
• 投稿确认。

输出：

• registry/{slug}/entry.yaml。
• YAML 预览。
• 复制 YAML。
• 下载 entry.yaml。
• 打开 GitHub 新建文件页面。

GitHub URL 必须：

• 使用 HTTPS。
• 域名为 github.com。
• 至少包含 owner 和 repository 两级路径。
• 自动移除结尾的 .git 和斜杠。

13.4 投稿模式 B：本地 Skill 文件夹

适用于尚未建立独立公开仓库的 Skill。

用户在浏览器中选择本地文件夹。网站只在浏览器本地读取和打包，不把文件上传到网站服务器。

输出 ZIP 结构：

registry/{slug}/
├── entry.yaml
└── skill/
    ├── README.md
    ├── atomic-skill-a/
    │   └── SKILL.md
    └── atomic-skill-b/
        └── SKILL.md

Registry 字段：

• source_type 为 bundled。
• source_url 指向仓颉 Skill 主仓库。
• skill_path 为 registry/{slug}/skill。

13.5 本地文件夹校验

必须拦截：

• 找不到 SKILL.md。
• 总大小超过 20 MB。
• 包含 .env。
• 包含 id_rsa 或 id_ed25519。
• 包含 credentials.json。
• 包含 pem、key 或 p12 文件。

必须忽略：

• .DS_Store。
• Thumbs.db。
• node_modules。

警告但不阻断：

• 缺少 README.md。

检测通过后，页面自动把 SKILL.md 数量写入原子 Skill 数量。

13.6 表单规则

字段	规则
name	必填，2—80 字符
slug	必填，小写英文、数字、连字符，最长 64
summary	必填，10—240 字符
repositoryUrl	GitHub 模式必填
skillCount	正整数，最小 1
domains	至少 1 个，支持中文或英文逗号
languages	zh-CN、en、ja，可多选
useCases	每行 1 个，至少 1 个，最多取前 6 个
agreement	必须勾选

13.7 Slug 生成

名称输入时可以自动生成 slug：

• 转为小写。
• 非字母数字替换为连字符。
• 去除首尾连字符。
• 最长 64 字符。

用户手动修改 slug 后，不再被名称变化自动覆盖。

中文名称无法自动生成有效英文 slug 时，用户必须手动填写。

13.8 草稿与隐私

当前实现：

• 普通字符串字段保存到浏览器 localStorage。
• 所选文件夹不会保存。
• 所选文件夹不会自动上传。
• 页面不会把表单内容发送到独立服务器。

P1：

• 正确保存和恢复多语言选择。
• 提供“清除草稿”。
• 在不同投稿模式间切换时保留有效字段。

13.9 生成结果

提交表单后必须：

• 显示生成的 YAML。
• 启用复制按钮。
• 展示下一步说明。
• 根据模式展示 entry.yaml 下载或完整 ZIP 下载。
• GitHub 模式展示创建文件入口。
• 失败时在表单附近展示明确错误。

14. Registry 数据需求

14.1 单一数据源

Registry 是网站 Skill 数据的唯一来源：

registry/{slug}/entry.yaml

页面不得另外维护一份 Skill 列表或统计 JSON。

14.2 Schema 文件

Schema 路径：

schemas/registry-entry.schema.json

使用 JSON Schema Draft 2020-12。

14.3 必填字段

字段	类型	说明
schema_version	常量 1	Registry 格式版本
slug	string	唯一 URL 标识
name	string	展示名称
summary	string	一句话简介
source_type	enum	github 或 bundled
source_url	URI	GitHub 来源地址
skill_count	integer	原子 Skill 数
domains	string[]	领域
language	enum[]	zh-CN、en、ja
status	enum	active、experimental、archived
quality	enum	verified、community、experimental
use_cases	string[]	1—6 个使用场景

14.4 可选字段

字段	说明
skill_path	bundled 模式下的仓库内路径
featured	是否进入首页精选
install	兼容旧数据的手动 clone/copy 信息，当前 UI 不作为主流程

14.5 质量等级

• verified：维护者已检查内容、结构和主要使用方式。
• community：社区投稿，已通过基本审核，但不代表官方背书。
• experimental：仍在试验，结构、兼容性或效果可能变化。

新投稿默认使用 community，不能由普通投稿者自行标记 verified。

14.6 内容状态

• active：正常展示和使用。
• experimental：展示但明确提示实验性。
• archived：不再维护。

P1 需要明确 archived 是否默认从目录隐藏；当前 Schema 已支持，但页面尚未做单独处理。

14.7 目录校验

自动校验必须保证：

• 每个 Registry 子目录都有 entry.yaml。
• 文件夹名等于 slug。
• slug 不重复。
• 所有字段符合 Schema。
• source_url 是 GitHub HTTPS URL。
• 至少存在一个 Registry 条目。
• 可以计算 Pack 和原子 Skill 总数。

15. GitHub PR 审核需求

15.1 原则

GitHub PR 同时承担：

• 投稿队列。
• 身份归属。
• 讨论记录。
• 修改历史。
• 自动检查结果。
• 人工审核记录。

15.2 自动检查

当 Pull Request 修改以下路径时触发：

• registry/**。
• schemas/**。
• website/**。
• .github/workflows/**。

自动执行：

1. npm ci。
2. Registry Schema 校验。
3. 单元测试。
4. Astro 类型检查。
5. 静态站点构建。

15.3 人工审核

维护者至少检查：

• 来源是否公开、真实和可追溯。
• 投稿者是否有权公开内容。
• 是否包含受版权限制的原始材料。
• 是否包含密钥、凭证、隐私或恶意代码。
• Skill 是否有明确触发条件、输入、步骤和输出。
• 是否真正形成可执行方法，而不是普通摘要。
• 是否与现有内容高度重复。
• Registry 简介和 use_cases 是否准确、不过度宣传。

15.4 审核结果

• 通过：合并到 main，网站自动更新。
• 请求修改：在 PR 中说明问题，贡献者继续提交。
• 拒绝：关闭 PR，并保留公开原因。

16. 状态与异常需求

16.1 搜索无结果

展示：

• “没有找到匹配的 Skill”。
• 建议更换关键词或清空筛选。
• 清空筛选按钮。

16.2 安装规范不可访问

正式上线验收时必须检查固定 URL 返回 200。

如果安装规范 URL 不可访问：

• 不得宣称 Agent 安装流程已经正式可用。
• 发布流程应视为未完成。
• P1 可以在页面增加“规范暂不可用”的构建期检测或状态提示。

16.3 Clipboard 不可用

当前复制功能依赖 navigator.clipboard。

P1 需要：

• 捕获复制失败。
• 提示用户手动选择文本。
• 不把复制失败误显示为成功。

16.4 GitHub 不可用

如果 GitHub 新建文件页面无法打开：

• 用户仍可下载 entry.yaml 或 ZIP。
• 页面应保留手动 Fork 和 PR 的说明。

16.5 本地文件夹不受支持

文件夹选择依赖浏览器的 webkitdirectory 能力。P1 需要检测支持情况；不支持时提供 ZIP 或多文件选择的替代说明。

17. 安全、版权与隐私

17.1 安全原则

• 网站不在服务端运行投稿 Skill。
• 网站不自动执行上传文件中的脚本。
• 本地文件夹只在浏览器内检查和打包。
• Agent 安装前必须检查来源和冲突。
• 需要凭证、权限提升或覆盖修改时必须询问。

17.2 版权原则

允许：

• 投稿者自己创作的 Skill。
• 有明确授权的内容。
• 指向投稿者自行维护的公开 GitHub 仓库。
• 对知识方法的原创结构化表达。

不允许：

• 未授权完整书籍、课程、视频、音频和付费资料。
• 通过 Skill 变相分发原始受版权保护内容。
• 无法说明来源或授权状态的资料包。

17.3 隐私

• 不建立用户数据库。
• 不收集投稿文件。
• 不保存所选文件夹。
• localStorage 草稿只存在用户当前浏览器。
• 不在 MVP 中接入第三方行为分析。

18. 非功能需求

18.1 性能

• 网站必须静态生成。
• 首屏不依赖数据库或运行时 API。
• Registry 在构建期读取。
• 搜索和筛选在浏览器本地完成。
• 22 个 Pack 规模下操作应无明显延迟。

P1 性能目标：

• 桌面端 Lighthouse Performance ≥ 90。
• 移动端首屏主要内容在正常网络下 2.5 秒内可见。

18.2 响应式

必须支持：

• 桌面端。
• 平板。
• 宽度约 390px 的移动端。

移动端要求：

• 卡片单列。
• 筛选控件单列或双列。
• 详情页安装卡优先。
• 投稿表单和预览改为单列。
• 不产生影响主流程的横向滚动。

18.3 可访问性

当前基础要求：

• 提供跳到正文链接。
• 主导航有 aria-label。
• 当前页面使用 aria-current。
• 搜索结果数量使用 aria-live。
• 表单字段有 label。
• 按钮可通过键盘触发。
• 文本与背景具备基本对比度。

P1：

• 完成 WCAG 2.1 AA 基础检查。
• 为复制成功和表单错误提供屏幕阅读器状态。
• 检查所有焦点样式。

18.4 SEO

当前已实现：

• 每页独立 title。
• 每页 description。
• lang=zh-CN。
• 静态可抓取 HTML。

P1：

• Open Graph。
• Twitter Card。
• canonical URL。
• sitemap.xml。
• robots.txt。
• Skill 详情结构化数据。

18.5 浏览器兼容

目标：

• 当前版本 Chrome、Edge、Safari、Firefox。

文件夹选择和 Clipboard API 必须重点验证兼容性。

19. 技术与部署约束

19.1 架构

• 框架：Astro 静态站点。
• 数据：YAML Registry。
• Schema：JSON Schema + Ajv。
• 投稿打包：JSZip。
• 测试：Vitest。
• 部署：GitHub Pages。
• 审核：GitHub Pull Request。
• 后端：无。
• 数据库：无。

19.2 GitHub Pages

部署触发：

• main 分支中的 registry/** 变化。
• schemas/** 变化。
• website/** 变化。
• deploy-pages 工作流变化。
• 手动 workflow_dispatch。

部署需要：

• GitHub Pages Source 设置为 GitHub Actions。
• main 包含网站、Registry 和安装规范。
• 构建时 SITE_URL 为 https://kangarooking.github.io。
• base 为 /cangjie-skill。

19.3 发布前阻断项

正式发布前必须全部完成：

• 网站分支推送到 GitHub。
• PR 检查通过。
• 合并到 main。
• Pages 启用 GitHub Actions。
• 首页返回 200。
• /skills 返回 200。
• 任一详情页返回 200。
• /submit 返回 200。
• /install/cangjie-skill.md 返回 200。
• 详情页复制的固定安装 URL 可被 Agent 访问。

20. 当前实现状态

20.1 已实现

• 五个核心页面。
• 22 个动态 Skill Pack 详情页。
• 22 个 Pack、300 个原子 Skill 的 Registry。
• 搜索和领域、质量、来源筛选。
• SkillHub 风格的详情页信息层级。
• Agent 安装提示词。
• 统一 Agent 安装规范。
• GitHub 仓库投稿。
• 本地文件夹投稿。
• YAML 预览、复制和下载。
• 本地 ZIP 打包。
• Schema 校验。
• 单元测试、类型检查和静态构建。
• PR 模板。
• CI 工作流。
• GitHub Pages 部署工作流。

20.2 已配置但待发布

• 正式官网。
• 固定安装规范 URL。
• main 合并后的自动部署。

20.3 当前测试基线

• Registry：22 Packs、300 Atomic Skills。
• 单元测试：9 个。
• Astro 类型错误：0。
• 静态 HTML 页面：26 个。

测试数量和数据量会随功能变化更新，不应作为永久硬编码指标。

21. MVP 验收标准

21.1 用户使用闭环

• 用户可从首页进入 Skill 目录。
• 用户可搜索“投资”等关键词并看到相关 Pack。
• 用户可组合领域、质量和来源筛选。
• 用户可进入任意详情页。
• 用户可复制完整 Agent 安装提示词。
• 安装提示词中的规范 URL 返回 200。
• Agent 能根据规范找到对应来源并完成安装。
• 用户能按照教程验证 Skill 已生效。

21.2 投稿闭环

• GitHub 模式能生成符合 Schema 的 entry.yaml。
• GitHub 模式能下载文件并打开新建文件入口。
• 本地模式能识别 SKILL.md 数量。
• 本地模式能阻止敏感文件和超大文件夹。
• 本地模式能生成正确目录结构的 ZIP。
• PR 能触发自动检查。
• Registry 变更合并后网站内容自动更新。

21.3 质量闭环

• npm run validate:registry 通过。
• npm test 通过。
• npm run check 通过。
• npm run build 通过。
• 桌面端关键页面无明显布局错误。
• 移动端核心操作可完成。
• 用户已有的无关仓库文件未被修改。

22. 后续迭代建议

22.1 P1：上线可靠性

• 正式发布 Pages。
• 部署后健康检查。
• 固定安装规范 URL 的 CI 检查。
• Clipboard 失败回退。
• 文件夹选择兼容提示。
• 所有筛选条件 URL 化。
• 草稿清除和多语言恢复。
• archived 条目的展示策略。

22.2 P1：发现效率

• 把原子 Skill 名称纳入搜索。
• 增加来源作者展示。
• 增加更新时间和版本。
• 增加相似 Skill 和相关 Pack。
• 提供分类落地页。

22.3 P1：可信度

• 展示审核时间和审核者。
• 展示测试报告或验证摘要。
• 展示来源 commit 或版本。
• 增加安全声明和版权声明页面。

22.4 P2：社区能力

• 贡献者主页。
• 收藏、评分和评论。
• 排行榜和趋势。
• 版本更新提醒。
• Skill 兼容性矩阵。

这些能力不得在 MVP 主流程稳定前引入数据库和账号系统。

23. 产品原则

后续所有需求和设计决策应遵循：

1. 先帮助用户解决真实任务，再展示项目概念。
2. 安装优先交给 Agent，不把目录知识转嫁给普通用户。
3. Registry 是唯一数据源。
4. GitHub PR 是首版审核后台。
5. 来源、授权、审核过程必须公开可追溯。
6. 默认不执行、不上传、不索取凭证。
7. 功能优先于视觉复杂度。
8. 先保持静态、低成本和可维护，再扩展社区能力。

24. 相关文件

• 功能规格：docs/plans/2026-07-13-cangjie-skill-website-mvp-functional-spec.md
• Agent 安装调整：docs/plans/2026-07-13-agent-install-detail-redesign.md
• Registry Schema：schemas/registry-entry.schema.json
• Registry 数据：registry/
• 官网源码：website/
• Agent 安装规范：website/public/install/cangjie-skill.md
• 贡献说明：CONTRIBUTING.md
• PR 模板：.github/pull_request_template.md
• Registry 检查：.github/workflows/registry-check.yml
• Pages 部署：.github/workflows/deploy-pages.yml