# 仓颉 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 的主流程

~~~mermaid
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 投稿审核主流程

~~~mermaid
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 安装提示词示例

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

~~~text
请根据 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 来源的提示词格式：

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

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

~~~text
请根据 {安装规范 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 结构：

~~~text
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 数据的唯一来源：

~~~text
registry/{slug}/entry.yaml
~~~

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

### 14.2 Schema 文件

Schema 路径：

~~~text
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