mcpField
T
tinyship-feature

tinyship-feature

github.com/tinyshipcn开发585 次安装2 周前更新
代码仓库

关于 tinyship-feature

为 TinyShip 单体仓库项目提供功能开发步骤，面向需要按既有架构添加功能的开发者。指南覆盖共享业务逻辑、API 与界面、国际化、权限、积分及验证流程。

主要功能

  1. 01梳理功能范围与需求
  2. 02按层组织共享逻辑和配置
  3. 03为多个应用框架添加 API 与界面
  4. 04维护英文和中文翻译
  5. 05接入认证、权限与积分
  6. 06通过类型检查、构建和手动测试验证

适用场景

  1. 01为 TinyShip 添加全栈功能
  2. 02在 Next.js、Nuxt.js 或 TanStack Start 中实现路由
  3. 03开发需要认证或积分扣费的功能
  4. 04按项目约定检查新功能并验证

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tinyshipcn/tinyship-skills --skill tinyship-feature

安装后在 Claude Code 中输入/tinyship-feature确认已加载。

详细介绍

TinyShip 功能开发

逐步介绍如何为 TinyShip 项目添加新功能，并遵循单体仓库架构模式。

步骤 0：明确功能范围

请用户说明：

  1. 功能类型？ 仅 UI / 仅 API / 全栈
  2. 功能作用？ 简要描述功能
  3. 是否需要身份验证？ 是否应受到保护？
  4. 是否消耗额度？ 如果与 AI 相关，是否应扣除额度？

步骤 1：共享逻辑（libs/）

将领域/业务逻辑放在 libs/ 中，切勿在多个应用中重复实现。

阅读根目录的 AGENTS.md，了解完整的功能检查清单；阅读 libs/*/AGENTS.md，了解现有的库模式。

何时新建 lib，何时扩展现有 lib：

  • 与支付相关 → 扩展 libs/payment/
  • 与身份验证相关 → 扩展 libs/auth/
  • 与 AI 相关 → 扩展 libs/ai/
  • 新领域 → 创建包含 AGENTS.md 的 libs/your-domain/

步骤 2：配置（config/）

如果功能需要可配置选项：

  1. 添加新的配置文件 config/yourFeature.ts，或扩展现有文件
  2. 在 config.ts 中导出该配置
  3. 在 env.example 中添加新的环境变量，并附上说明

步骤 3：API 路由

在当前启用的应用中创建 API 端点：

Next.js：apps/next-app/app/api/your-feature/route.ts

import { yourLogic } from '@libs/your-domain';

export async function POST(req: Request) {
  // Auth check, input validation, call shared logic, return response
}

Nuxt.js：apps/nuxt-app/server/api/your-feature.post.ts

import { yourLogic } from '@libs/your-domain';

export default defineEventHandler(async (event) => {
  // Auth check, input validation, call shared logic, return response
});

TanStack Start：使用 createServerFn 或传统 API 路由。

步骤 4：页面/UI

创建前端页面：

Next.js：apps/next-app/app/[lang]/your-feature/page.tsx Nuxt.js：apps/nuxt-app/pages/your-feature.vue TanStack Start：apps/tanstack-app/src/routes/[lang]/your-feature.tsx

使用 libs/react-shared/ 中的共享 React 组件（适用于 Next + TanStack）。

步骤 5：i18n

在两种语言文件中添加翻译键：

  1. libs/i18n/locales/en.ts — 英语（唯一可信来源）
  2. libs/i18n/locales/zh-CN.ts — 中文（保持结构一致）
// In en.ts
yourFeature: {
  title: 'Your Feature',
  description: 'Feature description',
  // ... all user-facing strings
}

切勿在组件中硬编码面向用户的字符串。

步骤 6：身份验证与权限

如果功能需要身份验证：

Next.js：在 apps/next-app/middleware.ts 中将路由加入中间件保护 Nuxt.js：在 apps/nuxt-app/server/middleware/permissions.ts 中配置 TanStack Start：在路由定义中添加 beforeLoad 守卫

基于角色的访问控制请使用 libs/permissions/ 中的 CASL 权限系统。

步骤 7：额度（如适用）

如果功能会消耗额度：

  1. 在 config/credits.ts 中定义费用
  2. 使用 libs/credits 中的 creditService.consumeCredits()
  3. 在 libs/credits/utils.ts 中添加交易类型代码
  4. 在 libs/i18n/locales/ 中添加额度说明的翻译

步骤 8：验证

# Typecheck
pnpm --filter @tinyship/next-app typecheck  # adjust for your app

# Build
pnpm --filter @tinyship/next-app build

手动测试功能：

  1. 打开新页面
  2. 测试 API 端点
  3. 验证身份验证保护是否正常
  4. 切换语言以测试 i18n

TinyShip 仓库中的参考文件

  • AGENTS.md — 根目录功能检查清单（权威参考）
  • libs/*/AGENTS.md — 各库的模式和架构
  • .cursor/rules/project-structure.mdc — 单体仓库布局指南
  • libs/i18n/AGENTS.md — i18n 约定
  • libs/permissions/AGENTS.md — 权限系统指南

评论

支持 Markdown