# @cosmicdrift/kumiko-framework 中文文档

规范地址：https://npmcn.com/package/%40cosmicdrift/kumiko-framework/

版本：0\.419\.0
npm 元数据更新时间：2026-11-10T16:32:38.351Z
中文译文更新时间：2026-11-10T20:09:23.578Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cosmicdrift/kumiko-framework
原文对照：https://npmcn.com/package/%40cosmicdrift/kumiko-framework/?lang=original
项目主页：https://kumiko.rocks/
源码仓库：https://github.com/CosmicDriftGameStudio/kumiko-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.5 MB，1811 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：11 个
- peer 依赖：bun-types ^1\.4\.4，meilisearch ^0\.62\.0
- 首次发布：2026-05-06T18:20:54.770Z
- 最新版本发布：2026-11-10T16:32:37.924Z
- 近 30 天下载量：26827（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：551（近 12 个月 551 个）

## 中文简介

框架核心——发动机,管线,API,DB,以及使克米子去的所有其他位子.

## 安装

```sh
npm install @cosmicdrift/kumiko-framework
```

也可以使用：`pnpm add @cosmicdrift/kumiko-framework`、`yarn add @cosmicdrift/kumiko-framework`、`bun add @cosmicdrift/kumiko-framework`

## README

# @cosmicdrift/kumiko-框架

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://npmcn.com/package/LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)

Kumiko-发动机、管道、API、DB、事件存储和 每一分钱都能让久美子走.

> Bun + Hono + 的多租户、基于命令、事件源应用程序框架 后发相. 定义特性、注册实体、写入命令——框架 电线发送、持久性、预测、同步用户和实时 交货.

见 [单列波根 README](https://npmcn.com/package/README.md) 为了更大的投出 [文件/计划](https://npmcn.com/package/docs/plans) 建筑目录,以及 [样本/](https://npmcn.com/package/samples) 用于每个特性的可运行示例.

## 安装

```bash
bun add @cosmicdrift/kumiko-framework
# peers you probably already have:
bun add hono ioredis zod
```

Bun是预定的运行时间和测试跑者.

## 闪亮

```typescript
import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";

export const taskEntity = createEntity({
  table: "read_tasks",
  fields: {
    title: createTextField({ required: true, searchable: true }),
    done: createTextField(),
  },
  softDelete: true,
});

export const taskFeature = defineFeature("tasks", (r) => {
  // r.crud wires create/update/delete/restore + list/detail queries in one
  // call — events + projection in the same TX, optimistic locking, access
  // control, all explicit via the options below.
  r.crud("task", taskEntity, {
    write: { access: { roles: ["User"] } },
    read: {
      access: {
        openToAll: {
          reason: "any signed-in user may list and view tasks; only writes are role-gated",
        },
      },
    },
  });

  // Read-model fed from task events, rebuildable via the CLI
  r.projection({
    name: "tasks-per-day",
    source: "task",
    table: tasksPerDayTable,
    apply: {
      "task.created": async (event, tx) => {
        /* count++ */
      },
    },
  });

  // Async consumer — runs after commit via the event-dispatcher,
  // cursor-based, at-least-once, per-consumer dead-letter semantics.
  // Omit `table` for pure side-effect handlers (mail, webhooks, ...).
  r.multiStreamProjection({
    name: "notify-new-task",
    apply: {
      "task.created": async (event) => {
        // e.g. push to an external notification service
      },
    },
  });
});
```

## 软件包出口

| 条目 | 里面有什么东西 |
| --- | --- |
| `@cosmicdrift/kumiko-framework/engine` | `defineFeature`, (中文(简体) ), `createEntity`、实地帮助者、访问规则、登记 |
| `@cosmicdrift/kumiko-framework/db` | `deriveEntityTableMeta`, (中文(简体) ), `createEventStoreExecutor`移徙、租户-db |
| `@cosmicdrift/kumiko-framework/event-store` | `events` 表格中, `append`, (中文(简体) ), `loadAggregate`, (中文(简体) ), `loadAggregateAsOf` |
| `@cosmicdrift/kumiko-framework/pipeline` | 调度员,事件发送员(AsyncDaemon),投影重建,SSE+搜索消费者 |
| `@cosmicdrift/kumiko-framework/api` | `buildServer`、 认证中间软件、 SSE 路由、 错误合同 |
| `@cosmicdrift/kumiko-framework/auth` | JWT 助手, 密码散列, 会话用户 |
| `@cosmicdrift/kumiko-framework/search` | `SearchAdapter` 接口、 内记忆适配器、 Meili 包 |
| `@cosmicdrift/kumiko-framework/jobs` | 由 BullMQ 支持的工作选手, cron 排程 |
| `@cosmicdrift/kumiko-framework/files` | 已签名的 URL 上传/下载、租户范围存储 |
| `@cosmicdrift/kumiko-framework/i18n` | i18next设置,每个地段的翻译注册 |
| `@cosmicdrift/kumiko-framework/ui` | 反应钩子(Zustand商店,SSE订阅,乐观变种) |
| `@cosmicdrift/kumiko-testing/stack` | `setupTestStack`, (中文(简体) ), `createTestDb`,请求帮助 |
| `@cosmicdrift/kumiko-framework/utils` | 安全 JSON, 合格名助手 |
| `@cosmicdrift/kumiko-framework/errors` | 错误分类, `writeFailure`,理由合同 |

## 核心概念

-   **作为部署单位的特点.** `defineFeature` 登记实体, 写作/处理器、预测、活动后用户、生命周期钩、, 和翻译.
-   **指挥入,出州.** 写作是通过HTTP发送的命令; 发送器验证,强制访问,运行生命周期钩,持续 并触发一个TX的预测.
-   **事件来源默认.** 每一个字都经过 `createEventStoreExecutor` ,并将一个域事件附加到聚合流中。 自动生成 CRUD 活动(`<entity>.created/updated/deleted/restored`记录下来, 明确 `ctx.events.append` 用于有意的域事件。 预测反馈 关闭流中用于同-TX读后写入一致性.
-   **Async 通过光标的副作用.** SSE广播、搜索索引和 特性注册 `r.multiStreamProjection` 消费者单打独斗 基于光标的调度器( AsyncDeamon 模式) 。 消费者检查站, n重试之后的死信.
-   **多租户范围界定.** 每个事件、实体、投影和搜索 索引带 `tenantId`。 。 。 . `TenantDb` 是拒绝的 TX 扫描包 在租户外写作.
-   **乐观的货币.** `UNIQUE(aggregate_id, version)` 活动说明 给原子附件+冲突检测; `VersionConflictError` 表面 种族作为一等值.
-   **同上,p.c.c.c.c.c.c.c.c.c.c.c.c.c.c.d.c.c.c.c.c.c.d.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c.c. . . . . . . . . .........................................................................................** 关于事件的请求- id 备份独有索引 表格将重试变为重放. `IdempotencyGuard` 缓存写入 每一房客的结果.

## 状态

这个框架是1.0前的,进取快. 每个特性都有可运行的 样本 `samples/`;路线图生活在 [文件/计划/基准](https://npmcn.com/package/docs/plans/uebersicht.md)。 。 。 .

## 许可证

麻省理工学院,看 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 常见问题

### @cosmicdrift/kumiko-framework 是什么？

框架核心——发动机,管线,API,DB,以及使克米子去的所有其他位子\.

### 如何安装 @cosmicdrift/kumiko-framework？

在项目目录运行 npm install @cosmicdrift/kumiko-framework，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：bun-types（^1\.4\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cosmicdrift/kumiko-framework 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cosmicdrift/kumiko-framework 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cosmicdrift/kumiko-framework 可以商用吗？

@cosmicdrift/kumiko-framework 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cosmicdrift/kumiko-framework 的下载量有多少？

根据 npm 官方下载统计，@cosmicdrift/kumiko-framework 在 2026/10/11 – 2026/11/09 这 30 天内被下载 26,827 次，日均约 894 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cosmicdrift/kumiko-framework 还在维护吗？

最新版本 0\.419\.0 发布于 2026/11/11（今天）；至今共发布 551 个版本，其中过去 12 个月发布了 551 个；首次发布于 2026/05/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。