KarlCat: Instructions file for Claude Code

CLAUDE.md

本文件用于指导 Claude Code（claude.ai/code）在本仓库内进行开发与维护。

项目定位

KarlCat（卡尔猫）是基于 TypeScript + Node.js 的分布式多人游戏服务端框架。

• 技术栈：Node.js、TypeScript、MongoDB（Mongoose）、protobufjs
• 传输层：TCP / WebSocket / KCP
• 架构来源：pomelo → pinus → mydog → karlcat
• 当前原则：仓库保持“纯框架”，不内置具体业务表/业务模块

纯框架约束（重要）

1. 允许保留框架级扩展点，但默认不注入业务表。
2. server/src/database/ 中若出现业务表代码，可作为示例；不要默认视为“必须启用”。
3. 评审时不要把“未启用业务表”当作缺陷，除非用户明确要求跑业务功能。

最小业务接入模板

在保持“纯框架”主干不变的前提下，推荐按以下最小步骤接入业务：

1. 定义 Table（数据库服）

• 新建 XxxTable，继承 BaseOneKeyTable 或 Base2Table（或直接 BaseTable）。
• 写操作统一走 WAL 包装：insert/update/deleteRecoverOne -> MarkedXxxFinish。
• 在 init(db) 中完成 schema/model 初始化，并调用 BaseTable.initDataLog(this)。

1. 定义 Model（逻辑服）

• 新建 XxxModel 继承 BaseModel。
• 通过 app.rpcDB() 调用 DB 事件，不直接访问 Mongo。
• 按需开启缓存（覆盖 enableCache() 和 TTL 配置）。

1. 定义 ModelLogic（业务入口）

• 新建 XxxModelLogic 继承 BaseModelLogic。
• 在此组织业务读写、缓存刷新、登出清理等流程。

1. 注册协议处理入口

• 在 servers/<type>/ 下新增处理类，继承 BaseServerLogic。
• 使用 bindCmd/bindAwait 绑定协议处理函数。
• 协议主键需落入 route.ts 对应服务器区间。

1. 业务模块启用方式（建议）

• 不改框架主干默认行为。
• 在业务分支或部署层显式启用：实例化 XxxTable/XxxModel/XxxModelLogic，并在启动流程中注册。
• 未启用时，框架可运行但业务事件不可用，这属于预期行为。

最小代码骨架（可复制）

1. server/src/database/XxxTable.ts

import mongoose from "mongoose";
import { allTables } from "../app";
import { BaseTable } from "./BaseTable";

export class XxxTable extends BaseTable {
  public static get Instance(): XxxTable {
    return this.getInstance();
  }

  public async init(db: mongoose.Mongoose) {
    const schema = new mongoose.Schema({
      roleUid: { type: Number, required: true, index: true },
      value: { type: Number, default: 0 },
    });
    this.table = db.model(this.tableName, schema);
    allTables.push(this);
    BaseTable.initDataLog(this);
  }

  public async insertOne(data: any): Promise<any> {
    this.insertRecoverOne(data, { roleUid: data.roleUid });
    const ret = await super.insertOne(data);
    if (ret) {
      this.MarkedInsertFinish(data);
      this.dataLog?.updateLastWriteTime();
    }
    return ret;
  }
}