@fastcar/cli 0.1.2 → 0.1.4

package/skills/fastcar-rpc-microservices/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: fastcar-rpc-microservices
-description: FastCar RPC 与微服务开发指南。Use when working with FastCar framework for: (1) Building RPC servers and clients with @fastcar/rpc, (2) Using WebSocket/SocketIO/MQTT/gRPC for service communication, (3) Setting up microservices architecture (center/connector/chat/web/base), (4) Configuring RPC endpoints, authentication, retry policies, (5) Using protobuf with RPC.
+description: FastCar RPC 与微服务开发指南。Use when working with FastCar framework for: (1) Building RPC servers and clients with @fastcar/rpc, (2) Using WebSocket/SocketIO/MQTT/gRPC for service communication, (3) Setting up microservices architecture, (4) Configuring RPC endpoints, authentication, retry policies, (5) Using protobuf with RPC.
 ---
 
 # FastCar RPC & Microservices
 
-FastCar RPC 模块提供基于多种协议（WS、SocketIO、MQTT、gRPC）的远程调用能力，并支持构建 center / connector / chat / web / base 多服务微服务架构。
+FastCar RPC 模块提供基于多种协议（WS、SocketIO、MQTT、gRPC）的远程调用能力，并支持构建多服务微服务架构。
 
 ## RPC 核心概念
 
@@ -23,50 +23,24 @@ export default new APP();
 
 ### 服务端配置
 
-通过 `ApplicationSetting` 注入 RPC 服务器列表配置类：
-
 ```typescript
 import { Application, ApplicationSetting } from "@fastcar/core/annotation";
 import { EnableRPC } from "@fastcar/rpc/annotation";
-import RpcServerList from "./RpcServerList";
+import { SocketEnum } from "@fastcar/rpc/constant/SocketEnum";
 
 @Application
 @EnableRPC
-@ApplicationSetting(RpcServerList)
-class APP {}
-```
-
-`RpcServerList.ts` 示例：
-
-```typescript
-import { SocketEnum } from "@fastcar/rpc/constant/SocketEnum";
-import { Protocol } from "@fastcar/server";
-import { CodeProtocolEnum } from "@fastcar/rpc/types/CodeProtocolEnum";
-import * as path from "path";
-
-export default {
+@ApplicationSetting({
   rpc: {
     list: [
       { id: "rpc-1", type: SocketEnum.WS, server: { port: 1238 }, serviceType: "rpc" },
       { id: "rpc-2", type: SocketEnum.SocketIO, server: { port: 1235 }, serviceType: "rpc" },
-      { id: "rpc-3", type: SocketEnum.MQTT, server: { port: 1236, protocol: Protocol.net }, serviceType: "rpc" },
-      {
-        id: "rpc-4",
-        type: SocketEnum.MQTT,
-        server: { port: 1239, protocol: Protocol.https, ssl: { key: "./ssl/server.key", cert: "./ssl/server.crt" } },
-        serviceType: "rpc",
-      },
-      {
-        id: "rpc-5",
-        type: SocketEnum.Grpc,
-        server: { port: 1240, ssl: { ca: path.join(__dirname, "cert/ca.crt"), key: "cert/server.key", cert: "cert/server.crt" } },
-        serviceType: "rpc",
-        codeProtocol: CodeProtocolEnum.PROTOBUF,
-        extra: { checkClientCertificate: true },
-      },
+      { id: "rpc-3", type: SocketEnum.MQTT, server: { port: 1236 }, serviceType: "rpc" },
+      { id: "rpc-4", type: SocketEnum.Grpc, server: { port: 1240 }, serviceType: "rpc" },
     ],
   },
-};
+})
+class APP {}
 ```
 
 支持的协议类型：
@@ -77,15 +51,13 @@ export default {
 
 ### 安全认证
 
-在服务端配置 `secure`：
-
 ```typescript
 {
   id: "rpc-auth",
   type: SocketEnum.WS,
   server: { port: 1238 },
   serviceType: "rpc",
-  secure: { username: "user", password: "123456" },
+  secure: { username: "user", password: "your-password" },
 }
 ```
 
@@ -93,7 +65,7 @@ export default {
 
 ```typescript
 import { Controller } from "@fastcar/core/annotation";
-import { RPC, RPCMethod, RPCMiddleware } from "@fastcar/rpc/annotation";
+import { RPC, RPCMethod } from "@fastcar/rpc/annotation";
 
 @Controller
 @RPC("/hello")
@@ -130,14 +102,13 @@ const client = new RpcClient(
   {
     url: "ws://localhost:1238",
     type: SocketEnum.WS,
-    secure: { username: "user", password: "123456" },
+    secure: { username: "user", password: "your-password" },
   },
   new NotifyHandle()
 );
 
 await client.start();
 const result = await client.request("/hello");
-console.log(result);
 ```
 
 ### 断线重连与重试策略
@@ -157,19 +128,6 @@ const client = new RpcClient(
 );
 ```
 
-### SSL 连接
-
-```typescript
-const client = new RpcClient(
-  {
-    url: "wss://localhost:1239",
-    type: SocketEnum.MQTT,
-    extra: { rejectUnauthorized: false },
-  },
-  new NotifyHandle()
-);
-```
-
 ### Protobuf 调用
 
 ```typescript
@@ -177,11 +135,10 @@ import { RpcClient } from "@fastcar/rpc";
 import { SocketEnum } from "@fastcar/rpc/constant/SocketEnum";
 import { CodeProtocolEnum } from "@fastcar/rpc/types/CodeProtocolEnum";
 import { ClientRequestStatic } from "@fastcar/rpc/service/rpc/RequestStatic";
-import * as path from "path";
 
 const client = new RpcClient(
   {
-    url: "local.dev.com:1240",
+    url: "localhost:1240",
     type: SocketEnum.Grpc,
     codeProtocol: CodeProtocolEnum.PROTOBUF,
     ssl: {
@@ -189,15 +146,8 @@ const client = new RpcClient(
       key: path.join(__dirname, "cert/client.key"),
       cert: path.join(__dirname, "cert/client.crt"),
     },
-    extra: {
-      options: {
-        "grpc.ssl_target_name_override": "example",
-        "grpc.default_authority": "example",
-      },
-    },
   },
-  new NotifyHandle(),
-  { retryCount: 0 }
+  new NotifyHandle()
 );
 
 client.addProtoBuf({
@@ -224,7 +174,7 @@ FastCar 微服务模板将系统拆分为以下服务模块：
 |------|------|
 | center | 服务中心，提供服务注册与发现 |
 | connector | 连接器服务，处理客户端连接（通常标记 `front: true`） |
-| chat | 聊天服务，处理实时消息 |
+| message | 消息服务，处理实时消息 |
 | web | Web 服务，提供 HTTP 接口 |
 | base | 基础服务，提供公共功能 |
 
@@ -234,7 +184,7 @@ FastCar 微服务模板将系统拆分为以下服务模块：
 settings:
   microservices:
     center:
-      token: "nW0tT4bZ6qM7mF7wD2rT2pR9dT7gK3hZ"
+      token: "your-token-here"
       servers:
         - host: "localhost"
           clusters: 1
@@ -246,7 +196,7 @@ settings:
               disconnectInterval: 1000
               retry: { retryCount: 3, retryInterval: 3000, timeout: 30000, maxMsgNum: 10000, increase: true }
     connector:
-      token: "x3TGsWC9uloZu235LA07eAiJ61nQ1A5f"
+      token: "your-token-here"
       servers:
         - host: "localhost"
           clusters: 1
@@ -254,8 +204,8 @@ settings:
             - front: true
               type: "ws"
               server: { port: 60100 }
-    chat:
-      token: "go0kbkNM3wQ4e2Vgo0kbkNM3wQ4e2V"
+    message:
+      token: "your-token-here"
       servers:
         - host: "localhost"
           clusters: 1
@@ -263,7 +213,7 @@ settings:
             - type: "ws"
               server: { port: 60200 }
     web:
-      token: "go0kbkNM3wQ4e2Vgo0kbkNM3wQ4e2V"
+      token: "your-token-here"
       koa:
         koaBodyParser:
           enableTypes: ["json", "form", "text"]

package/skills/fastcar-serverless/SKILL.md

@@ -17,58 +17,58 @@ FastCar Serverless 框架支持将 FastCar 应用部署到阿里云函数计算
 import { ServerlessApp, Service, Handler, HttpTrigger, TimerTrigger, EventTrigger } from "@fastcar/serverless";
 
 @Service
-class OrderService {
-  async createOrder(data: any) {
-    return { orderId: Date.now(), ...data };
+class BizService {
+  async process(data: any) {
+    return { id: Date.now(), ...data };
   }
 }
 
 @ServerlessApp({
-  name: "order-service",
+  name: "example-service",
   version: "1.0.0",
-  components: [OrderService],
+  components: [BizService],
   init: async (app) => {
-    console.log("Order service initializing...");
+    console.log("Service initializing...");
   },
 })
-class OrderApp {
-  @HttpTrigger({ path: "/orders", method: "POST" })
+class ExampleApp {
+  @HttpTrigger({ path: "/items", method: "POST" })
   @Handler()
-  async createOrder(event: any, context: any) {
-    const orderService = (this as any).app.getFastCarApp().getComponentByName("OrderService") as OrderService;
-    const order = await orderService.createOrder(event.body);
+  async createItem(event: any, context: any) {
+    const service = (this as any).app.getFastCarApp().getComponentByName("BizService") as BizService;
+    const result = await service.process(event.body);
     return {
       statusCode: 200,
       headers: { "Content-Type": "application/json" },
-      body: { success: true, data: order },
+      body: { success: true, data: result },
     };
   }
 
-  @HttpTrigger({ path: "/orders/:id", method: "GET" })
+  @HttpTrigger({ path: "/items/:id", method: "GET" })
   @Handler()
-  async getOrder(event: any, context: any) {
+  async getItem(event: any, context: any) {
     return {
       statusCode: 200,
-      body: { orderId: event.params?.id },
+      body: { id: event.params?.id },
     };
   }
 
   @TimerTrigger({ cron: "0 0 * * * *" })
   @Handler()
-  async hourlyReport(event: any, context: any) {
-    console.log(`[${context.requestId}] Generating hourly report`);
+  async hourlyTask(event: any, context: any) {
+    console.log(`[${context.requestId}] Running scheduled task`);
     return { success: true };
   }
 
   @EventTrigger({ eventSource: "oss" })
   @Handler()
-  async handleFileUpload(event: any, context: any) {
-    console.log(`[${context.requestId}] Processing file upload event`);
+  async handleEvent(event: any, context: any) {
+    console.log(`[${context.requestId}] Processing event`);
     return { success: true };
   }
 }
 
-const orderApp = new OrderApp();
+const app = new ExampleApp();
 ```
 
 ### 触发器类型
@@ -100,51 +100,51 @@ import {
 import { startLocalDev } from "@fastcar/serverless/local";
 
 @Service
-class UserService {
-  private users = [
-    { id: "1", name: "张三" },
-    { id: "2", name: "李四" },
+class DataService {
+  private data = [
+    { id: "1", name: "示例1" },
+    { id: "2", name: "示例2" },
   ];
-  findAll() { return this.users; }
-  findById(id: string) { return this.users.find(u => u.id === id); }
-  create(user: any) {
-    const newUser = { id: String(Date.now()), ...user };
-    this.users.push(newUser);
-    return newUser;
+  findAll() { return this.data; }
+  findById(id: string) { return this.data.find(d => d.id === id); }
+  create(item: any) {
+    const newItem = { id: String(Date.now()), ...item };
+    this.data.push(newItem);
+    return newItem;
   }
 }
 
 @Controller
-class UserController {
+class ApiController {
   @Autowired
-  private userService!: UserService;
+  private service!: DataService;
 
-  @HttpTrigger({ path: "/users", method: "GET" })
+  @HttpTrigger({ path: "/items", method: "GET" })
   @Handler()
-  async listUsers(ctx: ServerlessContext) {
-    ctx.json({ code: 0, data: this.userService.findAll(), requestId: ctx.requestId });
+  async list(ctx: ServerlessContext) {
+    ctx.json({ code: 0, data: this.service.findAll(), requestId: ctx.requestId });
   }
 
-  @HttpTrigger({ path: "/users/:id", method: "GET" })
+  @HttpTrigger({ path: "/items/:id", method: "GET" })
   @Handler()
-  async getUser(ctx: ServerlessContext) {
-    const user = this.userService.findById(ctx.params.id);
-    if (!user) ctx.throw(404, "User not found");
-    ctx.json({ code: 0, data: user });
+  async getOne(ctx: ServerlessContext) {
+    const item = this.service.findById(ctx.params.id);
+    if (!item) ctx.throw(404, "Not found");
+    ctx.json({ code: 0, data: item });
   }
 
-  @HttpTrigger({ path: "/users", method: "POST" })
+  @HttpTrigger({ path: "/items", method: "POST" })
   @Handler()
-  async createUser(ctx: ServerlessContext) {
-    const user = this.userService.create(ctx.bodyData);
+  async create(ctx: ServerlessContext) {
+    const item = this.service.create(ctx.bodyData);
     ctx.status = 201;
-    ctx.json({ code: 0, data: user });
+    ctx.json({ code: 0, data: item });
   }
 }
 
 async function main() {
   const app = new ServerlessApplication();
-  app.register(UserController, UserService);
+  app.register(ApiController, DataService);
   app.use(ErrorMiddleware({ includeStack: true }));
   app.use(LoggerMiddleware({ logQuery: true }));
   app.use(CorsMiddleware({ origin: "*" }));
@@ -167,21 +167,21 @@ main().catch(console.error);
 
 ```typescript
 import { createFCAdapter } from "@fastcar/serverless";
-export const handler = createFCAdapter((orderApp as any).app);
+export const handler = createFCAdapter((app as any).app);
 ```
 
 ### 腾讯云 SCF
 
 ```typescript
 import { createSCFAdapter } from "@fastcar/serverless";
-export const main_handler = createSCFAdapter((orderApp as any).app);
+export const main_handler = createSCFAdapter((app as any).app);
 ```
 
 ### AWS Lambda
 
 ```typescript
 import { createLambdaAdapter } from "@fastcar/serverless";
-export const handler = createLambdaAdapter((orderApp as any).app);
+export const handler = createLambdaAdapter((app as any).app);
 ```
 
 ## 常用中间件

package/skills/fastcar-toolkit/SKILL.md

@@ -28,41 +28,35 @@ import { Service, Autowired } from "@fastcar/core/annotation";
 import { CacheApplication } from "@fastcar/cache";
 
 @Service
-class UserCacheService {
+class CacheService {
   @Autowired
   private cache!: CacheApplication;
 
-  setUser(id: string, user: any) {
+  setItem(id: string, data: any) {
     // ttl 单位秒，0 为不过期
-    this.cache.set("userStore", id, user, { ttl: 60 });
+    this.cache.set("dataStore", id, data, { ttl: 60 });
   }
 
-  getUser(id: string) {
-    return this.cache.get("userStore", id);
+  getItem(id: string) {
+    return this.cache.get("dataStore", id);
   }
 
-  hasUser(id: string) {
-    return this.cache.has("userStore", id);
+  hasItem(id: string) {
+    return this.cache.has("dataStore", id);
   }
 
-  deleteUser(id: string) {
-    return this.cache.delete("userStore", id);
+  deleteItem(id: string) {
+    return this.cache.delete("dataStore", id);
   }
 
-  getTTL(id: string) {
-    return this.cache.getTTL("userStore", id);
-  }
-
-  getAllUsers() {
-    return this.cache.getDictionary("userStore");
+  getAll() {
+    return this.cache.getDictionary("dataStore");
   }
 }
 ```
 
 ### 持久化缓存配置
 
-通过 `@CacheMapping` 配置缓存节点，支持文件持久化或数据库持久化：
-
 ```typescript
 import { CacheMapping } from "@fastcar/cache";
 import { FSClient } from "@fastcar/cache";
@@ -80,11 +74,13 @@ class CacheConfig {}
 
 ## 定时任务 (@fastcar/timer)
 
+> **推荐使用 `@fastcar/timer/scheduling2` 模块**
+
 ### 开启定时任务
 
 ```typescript
 import { Application } from "@fastcar/core/annotation";
-import { EnableScheduling } from "@fastcar/timer";
+import { EnableScheduling } from "@fastcar/timer/scheduling2";
 
 @Application
 @EnableScheduling
@@ -94,7 +90,7 @@ class APP {}
 ### 间隔任务
 
 ```typescript
-import { ScheduledInterval } from "@fastcar/timer";
+import { ScheduledInterval } from "@fastcar/timer/scheduling2";
 import { Component } from "@fastcar/core/annotation";
 
 @Component
@@ -109,7 +105,7 @@ class HeartbeatTask {
 ### Cron 任务
 
 ```typescript
-import { ScheduledCron } from "@fastcar/timer";
+import { ScheduledCron } from "@fastcar/timer/scheduling2";
 import { Component } from "@fastcar/core/annotation";
 
 @Component
@@ -123,7 +119,7 @@ class ReportTask {
 
 ## 时间轮 (@fastcar/timewheel)
 
-适用于需要大量延时任务的场景（如订单超时取消、消息延时投递）。
+适用于需要大量延时任务的场景（如超时取消、消息延时投递）。
 
 ```typescript
 import { HashedWheelTimer } from "@fastcar/timewheel";
@@ -135,7 +131,7 @@ const timer = new HashedWheelTimer<string>({
 });
 
 // 添加一个 5 秒后触发的任务
-timer.addId("order-123", 5000);
+timer.addId("job-123", 5000);
 
 // 配合心跳循环处理
 setInterval(() => {
@@ -148,7 +144,7 @@ setInterval(() => {
 }, 100);
 
 // 取消任务
-timer.removeId("order-123", slotId);
+timer.removeId("job-123", slotId);
 ```
 
 ## 工作线程池 (@fastcar/workerpool)
@@ -156,7 +152,7 @@ timer.removeId("order-123", slotId);
 将 CPU 密集型操作卸载到 worker 线程执行，避免阻塞主线程。
 
 ```typescript
-import { WorkerPool, TaskType, TaskSyncType } from "@fastcar/workerpool";
+import { WorkerPool } from "@fastcar/workerpool";
 
 const pool = new WorkerPool({
   minWorkers: 2,
@@ -167,7 +163,7 @@ const pool = new WorkerPool({
 const result = await pool.exec("heavyComputation", [1, 2, 3, 4, 5]);
 ```
 
-在 FastCar 应用中通常通过 `@fastcar/core` 的 `@WorkerPool` / `@WorkerTask` 注解使用（参考 fastcar-framework skill）。
+在 FastCar 应用中通过 `@WorkerPool` / `@WorkerTask` 注解使用（参考 fastcar-framework skill）。
 
 ## 文件监听 (@fastcar/watchfile)
 
@@ -206,7 +202,7 @@ const sign = getSign(
   {
     appid: account.appid,
     expireTime: Math.floor((Date.now() + 5 * 60 * 1000) / 1000),
-    dir_path: "/", // 授权路径
+    dir_path: "/",
     mode: 7, // 1可读 2可写 4可查
   },
   account.serectkey
@@ -232,7 +228,6 @@ await cos.uploadfile("/test/text.txt", file);
 
 // 下载文件
 const res = await cos.getFile("/test/hello/test.txt");
-console.log(res.data);
 
 // 带鉴权下载
 await cos.getFile("/test.txt", true);
@@ -256,10 +251,6 @@ await cos.rename("/test/old.txt", "/test/new.txt");
 
 // 设置重定向
 await cos.setRedirect({ redirectUrl: "/test/hello.txt", flag: false, bucket: "test" });
-
-// 查询重定向
-await cos.getRedirect();
-await cos.queryRedirect({ bucketUrl: "http://xxx" });
 ```
 
 ## 完整模块列表

package/skills/typescript-coding-style/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: typescript-coding-style
+description: TypeScript 编码规范与最佳实践。Use when writing TypeScript code for: (1) Defining reusable type aliases for complex intersection types, (2) Using enums instead of string literals for status fields, (3) Naming conventions for types and interfaces, (4) Code organization and maintainability tips.
+---
+
+# TypeScript 编码规范
+
+## 1. 复用复杂类型别名
+
+### 问题场景
+当同一个交叉类型在多处使用时，直接重复书写会导致代码冗余、维护困难和可读性差。
+
+### 反例
+```typescript
+// ❌ 重复书写复杂的交叉类型
+private async getData(): Promise<(Detail & { related: Related })[]> {
+    const result: (Detail & { related: Related })[] = [];
+}
+
+private groupById(
+    items: (Detail & { related: Related })[]
+): Map<string, (Detail & { related: Related })[]> {
+}
+```
+
+### 正例
+```typescript
+// ✅ 定义类型别名，一处定义多处使用
+type DetailWithRelated = Detail & { related: Related };
+
+// 或者使用 interface
+interface DetailWithRelated extends Detail {
+    related: Related;
+}
+
+// 使用
+private async getData(): Promise<DetailWithRelated[]> {
+    const result: DetailWithRelated[] = [];
+}
+
+private groupById(items: DetailWithRelated[]): Map<string, DetailWithRelated[]> {
+}
+```
+
+### 规范建议
+1. **当交叉类型在 2 处及以上使用时**，应提取为类型别名或接口
+2. **命名规范**：使用 `With` 连接，如 `DetailWithRelated`
+3. **文档注释**：为复杂类型添加 JSDoc 说明其用途
+
+---
+
+## 2. 使用枚举代替字符串字面量
+
+### 问题场景
+状态字段使用字符串字面量会导致拼写错误、IDE 无法自动补全、重构困难和类型安全性差。
+
+### 反例
+```typescript
+// ❌ 使用字符串字面量
+const result = await this.mapper.select({
+    where: { status: "pending" }
+});
+
+await this.mapper.updateOne({
+    where: { id },
+    row: { status: "running" }
+});
+
+switch (detail.status) {
+    case "success":
+        break;
+    case "failed":
+        break;
+}
+```
+
+### 正例
+```typescript
+// ✅ 定义枚举
+export enum JobStatus {
+    pending = "pending",   // 待执行
+    running = "running",   // 执行中
+    success = "success",   // 成功
+    failed = "failed",     // 失败
+}
+
+// 使用枚举
+const result = await this.mapper.select({
+    where: { status: JobStatus.pending }
+});
+
+await this.mapper.updateOne({
+    where: { id },
+    row: { status: JobStatus.running }
+});
+
+switch (detail.status) {
+    case JobStatus.success:
+        break;
+    case JobStatus.failed:
+        break;
+}
+```
+
+### 规范建议
+1. **状态字段优先使用枚举**：任何表示状态的字段都应该使用枚举
+2. **枚举命名**：使用 PascalCase，如 `JobStatus`、`ItemType`
+3. **枚举值**：字符串枚举推荐，便于调试和序列化
+4. **注释说明**：为每个枚举值添加 JSDoc 注释
+
+### 完整示例
+```typescript
+// types/Enums.ts
+export enum JobStatus {
+    pending = "pending",
+    running = "running",
+    success = "success",
+    failed = "failed",
+}
+
+export enum ItemType {
+    typeA = "typeA",
+    typeB = "typeB",
+    typeC = "typeC",
+}
+
+export enum ExecuteMode {
+    now = "now",
+    schedule = "schedule",
+}
+
+// 使用
+import { JobStatus, ItemType } from "@/types/Enums";
+
+class Service {
+    async create(type: ItemType) {
+        const item = new Record({
+            itemType: type,
+            status: JobStatus.pending,
+            executeMode: ExecuteMode.now,
+        });
+    }
+}
+```