# @idlekit/core 中文文档

规范地址：https://npmcn.com/package/%40idlekit/core/

版本：0\.7\.0
npm 元数据更新时间：2026-11-01T07:25:11.915Z
中文译文更新时间：2026-11-01T10:34:38.784Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40idlekit/core
原文对照：https://npmcn.com/package/%40idlekit/core/?lang=original
项目主页：https://github.com/imjlk/idlekit/tree/main/packages/core#readme
源码仓库：https://github.com/imjlk/idlekit

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

- 包体积（解压后）：2.5 MB，285 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-10-11T10:42:24.774Z
- 最新版本发布：2026-11-01T07:25:11.620Z
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

为空闲的游戏经济编写、模拟、分析和报告。

## 安装

```sh
npm install @idlekit/core
```

也可以使用：`pnpm add @idlekit/core`、`yarn add @idlekit/core`、`bun add @idlekit/core`

## README

# @idlekit /核心

空闲游戏经济设计的仿真与分析基元。 它编译场景，执行运行，并评估长期kpi和面向设计的度量。 官方支持v1: Bun `>=1.4.2` 只有。Node.js和浏览器运行时不是v1兼容性契约的一部分。

```bash
bun add @idlekit/core
```

需要面包 `>=1.4.2`.

使用此包时，您需要：

-   场景验证/编译
-   仿真回路和 `stepOnce`
-   内置策略和调优原语
-   增长、里程碑、会话模式和蒙特卡罗分析
-   假设的LTV估计通过 `deriveMonetizationConfig`， `estimateLtvPerUser` 和 `estimateLtvDistribution`

## LTV估计

导入三个LTV函数 `retentionAtDay` / `progressionFactor` 帮助者和 `MonetizationConfig`， `LtvEstimateArgs`， `LtvDistributionArgs`， `LtvPointEstimate` 和 `LtvDistribution` 类型的 `@idlekit/core`。通过一项 `ScenarioV1` 来 `deriveMonetizationConfig`； 传递返回的配置， `horizonDays` 和 `progression` 来 `estimateLtvPerUser`. `estimateLtvDistribution` 还读 `draws`， `quantiles` 和 `seed`;一个被忽略的人会后退 来 `config.uncertainty`，明确的一方获胜。它总是采样： `config.uncertainty.enabled` 是调用者是否调用它的开关，如在CLI中。CLI使用相同的实现。

LTV是未贴现的累积价值。的地平线 `H` 日数涵盖安装日数 `[0, H)`第0天 根据定义，安装日是否处于活动状态，如遥测和 `idk calibrate`。分数末位 每一天的留存率是成比例的，所以0.5天是安装日的一半。早些时候发布 覆盖的天 `[1, H]`，降低了安装日收入，并在D1上收取了0.5天的期限 保留。同样的地平线现在增加了安装日和掉落日 `H`，因此LTV值会发生变化 通常会上升。

输入是假设性的假设，每个已安装的用户使用一种呼叫者选择的货币。 默认情况下，用户留存率和收益都不会受到影响。净收入为平台费用 毛利率；然后LTV减去CPI，包括在零日范围内。有限的发展 被夹在0…1。分位数波段描述的是对假设的敏感性，而不是拟合置信度 享受/保留的时间间隔或证据。

同步限制：0..36500天，1…10万次抽奖，最多1000万次抽奖日(至少 每个图纸一个工作单位)。分位数必须是1…0..1中的101个不同的值。每个输出键为 确切的百分比(`q50`， `q90`， `q2.5` 为0.025, `q12.4` 对于0.124)，所以键永远不会碰撞或 圆的。种子必须是0..4294967295之间的整数；还有一些种子是扔出来的，而不是折叠起来的。 `retentionAtDay` 需要一个有限的日期>= 0和一个有效的曲线(第0天是1，在（0,1）中的任何一天读 D1，从D1开始的锚点为线性)； `progressionFactor` 拒绝南 log和一个非有限且正的空间，并处理一个无限值的log（零值） 没有进展。无效输入和数字溢出引发 `RangeError`。抽样收缩 不一致的相关矩阵走向独立。 完全队列保留观察和安全贴片应用可在核心； 公众 `idk calibrate` CLI共享观察和规划实现。 公共估计配置也接受分位数端点。点估计验证整体 配置，包括分布读取的不确定性默认值；关键的区别和 当分发使用它们时检查种子范围。 `ScenarioV1` 授权分位数保留 他们现有的 `(0, 1)` 模式时传递给 `deriveMonetizationConfig`.

部分场景保留覆盖保留CLI的独立默认值。例如, `d1: 0.1` 单独保留默认 `d7: 0.2`;估计保留了现有的插值。 显式完整的场景曲线仍然遵循场景排序验证。直接估计 配置验证每个速率的范围，而不向已完成的默认值添加排序约束。 点投影和分布以同样的方式插值这样一条上升曲线：1 共享保留冲击缩放每个锚，采样不再剪辑后一个锚 前一个，所以零不确定性分布等于点投影。

## 观察队列保留

进口 `observeCohort`， `compareRetention`， `planRetentionPatch` 和 `applyRetentionPatch` 从 `@idlekit/core`. `CohortActivityRow` 需要 `userId` 和整数 `day`； `active` 默认为true。Money字段是可选的，永远不会被这些保留api所匹配。 每个已安装的用户都需要一个零日行，包括不返回者，调用者必须这样做 提供具有通用的、完全成熟的完整活动导出 `observedThroughDay`. API检查一致性；它不能证明出口的完整性。

`observeCohort(rows, cutoff)` 将未来的汇率/间隔保留为空。 `planRetentionPatch` 返回 `ready`， `unavailable` 或者 `requires-review`;每一个未被观察到的目标日都需要 明确保留的假设。与保留值上升或冲突的观测值 保持不变，不能成为自动补丁。 `applyRetentionPatch({ scenario, observation })` 重新计算计划，验证并返回独立的场景副本。 如果补丁还没有准备好，它就会抛出问题，因为它永远不会取代收益、费用、CPI、不确定性， 队列大小或未观察到的保留。 `assertCohortObservation` 验证序列化的输入。

看到 [完整的SDK示例](https://github.com/imjlk/idlekit/blob/main/examples/telemetry/cohort-sdk.ts) 和 [队列输出指南](https://github.com/imjlk/idlekit/blob/main/docs/player-telemetry.md).

## 游戏专用线下结算

`simulateSessionPattern({ scenario, pattern, prepareOffline })` 可选地调用同步 `SessionOfflinePreparer` 一次非空缺席。它接收 `ctx`， `model`，状态快照； `seconds`， `wallStartT`， `wallEndT` 以及当前的政策快照。数值原型是 保存在快照中；将共享引擎、上下文和模型视为不可变的。 在先前封顶的间隙之后使用显式墙壁时间戳进行到期检查。

返回任意一个 `model`， `stepSec` 和 `policy`。它们只适用于这个缺口；遗漏继承 场景设置。 `policy` 代替帽/腐，所以 `{}` 删除两个。会议的行动 政策不变 `scenario.run.offline.actions`;回调不能覆盖它。替代 模型声明自己的 `clocks.respondsTo` 的需求。SDK仍然执行奖励，目标， 直到检查，行动过滤，观察和墙/奖励会计。

具有一个原子沉降的游戏可以在快照上计算它并返回一个模型 将其结果导入到一个奖励tick中 `stepSec` 等于它的有效积分秒 （当信用为零时使用正步骤）。在刻度边界处检查停止；一个点的 解决方案不会暴露中间游戏状态。准备本身不能给你任何好处 外部奖励：零积分或已经达成的目标可能根本不会执行任何转换。 对于部分解决方案或内部差距目标，提供一个每个较小刻度演变的模型。

这是一个SDK回调，而不是一个JSON场景字段。默认会话路径不变。 看到 [大数脱机的例子](https://github.com/imjlk/idlekit/blob/main/examples/session/offline-preparation.ts).

## 简单的例子

```ts
import {
  analyzeGrowth,
  compileScenario,
  createModelRegistry,
  createNumberEngine,
  defineModelFactory,
  runScenario,
  validateScenarioV1,
} from "@idlekit/core";

type Vars = { owned: number };

const linearFactory = defineModelFactory<number, "COIN", Vars>({
  id: "linear",
  version: 1,
  create() {
    return {
      id: "linear",
      version: 1,
      income(ctx, state) {
        return {
          unit: ctx.unit,
          amount: ctx.E.add(1, Number(state.vars.owned ?? 0)),
        };
      },
      actions() {
        return [];
      },
    };
  },
});

const registry = createModelRegistry([linearFactory]);

const scenario = {
  schemaVersion: 1,
  unit: { code: "COIN" },
  policy: { mode: "drop" },
  model: { id: "linear", version: 1 },
  initial: {
    wallet: { unit: "COIN", amount: "0" },
    vars: { owned: 0 },
  },
  clock: { stepSec: 1, durationSec: 60 },
};

const validated = validateScenarioV1(scenario, registry);
if (!validated.ok || !validated.scenario) {
  throw new Error(`scenario should validate: ${JSON.stringify(validated.issues)}`);
}

const E = createNumberEngine();
const compiled = compileScenario({
  E,
  scenario: validated.scenario,
  registry,
});
const run = runScenario(compiled);
const growth = analyzeGrowth({ run, series: "money", windowSec: 10 });

console.log(
  JSON.stringify({
    endMoney: E.toString(run.end.wallet.money.amount),
    growthSegments: growth.segments,
  }),
);
```

## 运行时

在内存中的持续时间 `runScenario` 或者 `applyOfflineSeconds` 因此,进口 `runElapsedSec` 从 `@idlekit/core` 和阅读 `runElapsedSec(run)`。它使用 `run.stop.elapsedSec`，滴答秒的总和。 `state.t` 是绝对奖励时间戳；在一个大的起始时间戳下， `run.end.t - run.start.t` 可以圆不同。例如，10个0.1秒的滴答声从 `1e15` 模拟时间戳相差1.25秒时的大约一秒。没有停止记录的结果退回到该时间戳差异。步进预算停止可以在要求的持续时间之前缩短单个运行；检查 `run.stop?.reason` 或使用 `assertHorizonReached(run, label)` 当需要全视界时。

为 `simulateSessionPattern`,读 `summary.elapsedSec` 对于墙时间， `summary.activeSec` 对于活动tick秒，和 `summary.offlineCreditedSec` 对于离线奖励滴答秒。总 `session.run` 没有单次停车记录，所以呢 `runElapsedSec(session.run)` 使用时间戳回退。 `summary.rewardSec` 也是奖励时间戳的差异；当您需要模拟滴答秒时，使用活动和离线记入总数。

`@idlekit/core` 是作为一个bunfirst ESM包来维护的。

## 文档

-   存储库: [github.com/imjlk/idlekit](https://github.com/imjlk/idlekit)
-   产品路线图: [文档/ roadmap.md](https://github.com/imjlk/idlekit/blob/main/docs/roadmap.md)
-   场景指南: [文档/ scenario-and-tuning.md](https://github.com/imjlk/idlekit/blob/main/docs/scenario-and-tuning.md)
-   典型的工作例子： [例子/教程/ 14-orbital-foundry-v1.json](https://github.com/imjlk/idlekit/blob/main/examples/tutorials/14-orbital-foundry-v1.json)
-   适配器模式示例： [例子/适配器模式](https://github.com/imjlk/idlekit/tree/main/examples/adapter-pattern)

## 常见问题

### @idlekit/core 是什么？

为空闲的游戏经济编写、模拟、分析和报告。

### 如何安装 @idlekit/core？

在项目目录运行 npm install @idlekit/core，或使用 pnpm add / yarn add / bun add。

### @idlekit/core 支持 TypeScript 吗？

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

### @idlekit/core 支持 ESM 还是 CommonJS？

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

### @idlekit/core 可以商用吗？

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

### @idlekit/core 还在维护吗？

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