开发技能

ZShip 提供了一套开发技能（Skills），帮助您更高效地完成常见的开发任务。这些技能是 AI 驱动的工作流，在确保符合 ZShip 规范的同时，指导您完成复杂的操作。

什么是 Skills？

Skills 是存储在 .cursor/skills/ 中的专业 AI 工作流，为以下任务提供分步指导：

创建新应用和服务
向仪表板添加功能
自定义品牌
审查代码合规性
同步上游更新
等等…

当您要求 AI 助手执行任务时，它会自动使用相关技能，确保最佳实践和规范合规性。

可用技能

核心开发技能

`onboard`

ZShip 二次开发首次设置指南

解释架构和只读边界
安全检查清单（密钥、API 密钥）
命名规则和约定
多租户隔离要求

使用场景： 启动新的 ZShip 项目或为新开发者提供入门指导。

`create-app`

通过复制官方 web 模板创建新的品牌站点

将 apps/web/ 复制到您的新应用目录
设置 app_key、品牌和配置
配置唯一端口和包名

使用场景： 为新品牌启动新的前端项目。

`create-admin`

通过复制官方管理模板创建自定义管理控制台

将 apps/admin/ 复制到您的自定义管理目录
设置管理特定配置
配置管理路由和权限

使用场景： 需要具有自定义修改的管理功能时。

`create-service`

创建新的后端服务（Cloudflare Worker + Hono + D1）

生成完整的服务结构
设置 Hono 框架、D1 数据库、迁移
强制执行命名约定（绝不使用 nodeXX-* 格式）
包含多租户隔离模式

使用场景： 需要超出官方 nodeX 服务提供的自定义服务器端逻辑时。

功能开发技能

`add-page`

向您的 ZShip 应用添加新页面（Astro 或 Nuxt）

创建具有正确结构的页面组件
根据需要设置 API 代理路由
集成 i18n 支持
适用于 Astro 和 Nuxt 应用

使用场景： 向前端应用添加新页面时。

`add-dashboard`

向用户仪表板添加新功能标签页

创建 Vue 岛屿组件
设置 Astro 页面外壳
添加导航条目
创建 API 代理路由

使用场景： 向面向用户的仪表板添加新功能/标签页时。

`add-provider-model`

向 zship-provider1-service 添加新的 AI 提供商模型

解析提供商 API 文档
生成完整的数据库种子 SQL
更新文档
支持 KIE、WaveSpeed AI 和自定义平台

使用场景： 将新的 AI 提供商模型集成到提供商服务时。

自定义技能

`customize-brand`

自定义您的 ZShip 应用的品牌

站点名称、徽标、颜色、SEO
主题自定义
CSS 变量覆盖
绝不修改官方模板

使用场景： 自定义应用的品牌和视觉标识时。

维护技能

`sync-upstream`

将您的应用与官方 ZShip 模板更新同步

在模板和您的副本之间执行差异分析
建议要合并的更改
保留您的自定义
识别要跳过的无关更改

使用场景： 拉取 ZShip 更新后需要合并模板更改时。

`review`

审查代码更改是否符合 ZShip 规范

检查是否意外修改了官方文件
验证命名约定
安全检查清单（密钥、API 密钥）
多租户隔离验证
API 响应格式验证
架构边界检查

使用场景： 提交代码或创建拉取请求之前。

Skills 如何工作

自动激活：当您描述任务时，AI 助手会自动识别并使用相关技能。
分步指导：每个技能提供详细的步骤、代码模板和示例。
规范执行：技能确保您的代码遵循 ZShip 规范：
- 绝不修改官方文件（apps/web/、apps/admin/、backend/nodeX-*/）
- 正确的命名约定
- 多租户隔离
- 安全最佳实践
验证清单：大多数技能包括验证步骤，以确保一切正常工作。

技能结构

Skills 存储为 .cursor/skills/{skill-name}/SKILL.md 中的 Markdown 文件，包含：

Frontmatter：名称和描述
关键规则：必须遵循的约定
分步说明：详细指导
代码模板：即用型代码片段
验证：确认完成的清单

最佳实践

始终使用技能完成常见任务，而不是手动完成
在开始前阅读关键规则，了解每个技能的要求
完成任务后遵循验证清单
在提交重大更改前运行 review 技能
定期使用 sync-upstream 以保持与模板改进的同步

技能列表

技能名称	用途	使用场景
`onboard`	首次设置指南	新项目启动、新开发者入门
`create-app`	创建新应用	创建新的品牌站点
`create-admin`	创建管理控制台	需要自定义管理功能
`create-service`	创建后端服务	需要自定义 Worker 服务
`add-page`	添加页面	前端添加新页面
`add-dashboard`	添加仪表板功能	用户仪表板添加新标签页
`add-provider-model`	添加 AI 模型	集成新的 AI 提供商模型
`customize-brand`	自定义品牌	修改品牌和主题
`sync-upstream`	同步上游更新	合并模板更新
`review`	代码审查	提交前检查规范合规性

下一步

项目结构 — 了解项目结构
部署指南 — 部署您的应用
自定义指南 — 自定义您的应用