# @econ-v1/app-sdk 中文文档

规范地址：https://npmcn.com/package/%40econ-v1/app-sdk/

版本：7\.6\.185
npm 元数据更新时间：2026-11-13T11:56:22.352Z
中文译文更新时间：2026-11-13T05:59:39.960Z
软件包许可：MIT OR Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40econ-v1/app-sdk
原文对照：https://npmcn.com/package/%40econ-v1/app-sdk/?lang=original
项目主页：https://github.com/econ-v1/node
源码仓库：https://github.com/econ-v1/node

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

- 包体积（解压后）：452 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-05-08T16:37:35.919Z
- 最新版本发布：2026-11-13T11:56:21.933Z
- 近 30 天下载量：36071（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：394（近 12 个月 394 个）

## 中文简介

TypeScript SDK，用于在闪电驱动的marketplace守护进程上构建Node迷你应用插件（Bun runtime）

## 安装

```sh
npm install @econ-v1/app-sdk
```

也可以使用：`pnpm add @econ-v1/app-sdk`、`yarn add @econ-v1/app-sdk`、`bun add @econ-v1/app-sdk`

## README

# @ econ-v1/ app- sdk

> **状态 : `1.0.0-experimental`** —— API表面被冻结,等待至少两个一党包的验证. 中断更改 `1.0.0-experimental.*` 释放是可能的。 制作中精确的版本.

用于构建的脚本 / Bun SDK 类型 **节点- App** 用于此图的插件 [节点](https://github.com/econ-v1/node-app-distribution) 闪电驱动的市场守护进程。 Apps作为单独的 Bun 进程运行,并使用 JSON- newline 协议在一个 Unix- domain 套接字上与主机交谈.

## 它给你什么

-   一个抽象 `NodeApp` 类 —— 扩展它, 声明元数据, 并执行您需要的钩子 .
-   声明 `route()` 帮助者——注册HTTP处理器,并进行内置范围检查(在主机的表单执行上进行防御深入).
-   `invokeCapability()` ——呼叫在宿主能力路由器上注册的任何能力.
-   `publishEvent()` ——向主机事件总线发布命名空间域事件.
-   `host.{trace,debug,info,warn,error}` ——文件支撑结构化记录.

## 快开始

```sh
bun add @econ-v1/app-sdk@1.0.0-experimental
```

```typescript
import { NodeApp, runNodeApp, type AppRequest, type AppResponse } from "@econ-v1/app-sdk";

class MyApp extends NodeApp {
  readonly metadata = {
    name: "my-app",
    version: "0.1.0",
    author: "Me",
    description: "Hello-world Node-App",
    capabilities: ["http_handler"],
  };

  async init() {
    this.route("GET", "/hello", { requiredPermissions: [] }, async () =>
      this.json({ hello: "world" }),
    );
  }
}

runNodeApp(new MyApp());
```

主机启动 Bun 进程,通过 `NODE_APP_SOCKET` 环境变量,以及代理 HTTP 请求、事件和能力调用到套接字的路径.

## 汉堡应用程序

同一软件包服务于在Burger上运行的应用程序(`app_type: "burger"`),以及 所以汉堡应用取决于 `@econ-v1/app-sdk` 没有别的了 `@econ-v1`数字 :

| 编 | 应用程序如何使用它 |
| --- | --- |
| `burger-build` | 包裹 `bin`数字 : `burger-build build src/index.ts --outdir dist` 财务报告和审定财务报表 `burger-build test-prepare …` (见 `sdk/burger-build/README.md`) (中文(简体) ). `node-app build` 编号 : `node-app test` 为您运行它。 1.4.2. 设备箱 同一代码可导入为 `@econ-v1/app-sdk/burger-build` (单位:千美元)`buildApp`, (中文(简体) ), `prepareTests`) (中文(简体) ). |
| `burger-types` | `"types": ["@econ-v1/app-sdk/burger-types"]` 内 `tsconfig.json`页:1 `burger:*` 模块,其 `node:`编号 :`bun:` 化名和运行时间全局. `@econ-v1/app-sdk/burger-types/modules` 只声明 `burger:*`。 。 。 . |

两者都是从 `sdk/burger-build` 财务报告和审定财务报表 `sdk/burger-types` 在此 存储器由 `bun run build` (单位:千美元)`scripts/build-burger-toolchain.ts`) (中文(简体) ).

装入 `burger-build` 选择 `burger` 出口条件, 解决 `@econ-v1/app-sdk` 改为 `dist/burger/index.js`同样的API, 但主机频道是 `burger:host` (香料和JSON 由工会处理) 运行时,内存样本来自QuickJS运行时,没有 检测工人行踪 应用程序观察到的差异 :

-   `openDatabase()` 默认为 256 KiB 页面缓存( Burger's cap) 页:1.
-   遥测保持不活动( E)`telemetryActive()` 实值 `false`:汉堡第1阶段 没有 `fetch` 适用于OTLP出口商.
-   `heap_snapshot_request` 答案为 `success: false`。 。 。 .
-   在节点-app-burger上 0.3.3个巢 `invokeCapability` 携带 `invocation_context_id` 无论多少人 `await`将它与 处理器,如 Bun: SDK 负载 `burger:async_hooks` (ADR 004)加一个 动态导入和使用 `AsyncLocalStorage`在更古老的运行时间 导入会悄悄地失败, 第一阶段的行为会停止: 只有打过电话 在处理者第一个之前 `await` 随身携带身份证明,后期身份被分类 由主办方作为背景工作,从不作为前台(Burger合同C6), `docs/superpowers/plans/2026-09-17-burger-00-overview-and-contracts.md`) (中文(简体) ). 因此,同一SDK在每个运行时版本上都加载. 重建应用程序于 这个SDK在0.3.3上改变了它的巢中呼叫:现在它们携带呼叫者的呼叫 因此,东道主根据电话来电来评判他们(拒绝他们) `capability.invalid_invocation_context` 如果打电话者的背景已经 (已关闭)。 在发布前在0.3.3上运行应用程序的套房.

汉堡应用软件将SDK捆入 `dist/index.js`;运行时不共享.

## 生产大楼

`@econ-v1/app-sdk` 本身是一个 **共同依赖** (已安装) 一次时间 `/usr/lib/node/shared/node_modules/@econ-v1/app-sdk`),所以这是 _没有_ 绑入你的应用软件 `dist/index.js`。建造管道处理这个 自动——你不需要做任何特殊的事情.

您的应用程序的另一道道具在 三桶之一:

| 何处 | 何时 |
| --- | --- |
| **捆绑** 输入 `dist/index.js` _(默认)_ | 纯- JS 分解; 刷树 + 精密 |
| **共享** 时间 `/usr/lib/node/shared/node_modules/` | 戴普在馆里 `SHARED_EXTERNALS` 列表( LLM SDKs, 这个 SDK) |
| **私营** 时间 `<your-app>/node_modules/` | 您选择通过 `manifest.json#nodeApp.privateRuntime` (内部约束,版本覆盖) |

通过编辑选择一个私有的 DCP `manifest.json`数字 :

```json
{
  "name": "my-app",
  "version": "0.1.0",
  "entrypoint": "dist/index.js",
  "nodeApp": {
    "privateRuntime": ["better-sqlite3"]
  }
}
```

使用 `privateRuntime` 仅针对有本地绑定或版本的软件包 与共享树相冲突 – 每个条目将其已安装的全部大小添加到 你的应用程序。 参见Cononic 参考文献: [`docs/app-development/12-typescript-dependencies.md`](https://github.com/econ-v1/node/blob/main/docs/app-development/12-typescript-dependencies.md) 用于全面捆绑和解析模式.

### 构建命令

```sh
# Inside the node monorepo:
bash infra/scripts/build-bun-app.sh modules/my-app dist/build-aarch64/builtin-apps/my-app

# As a downstream app (after publishing):
bunx @econ-v1/app-sdk build .
```

## 深入防卫范围检查

```typescript
this.route(
  "POST",
  "/admin/**",
  { requiredPermissions: ["payments:write"] },
  async (req) => this.json({ ok: true }),
);
```

主机已经执行 `endpoint_policies` 在申请到达应用软件之前 从您的清单中 `route()` 重新检查 `request.caller.granted_permissions` 作为第二道防线.

## 呼叫东道方能力

```typescript
import { invokeCapability } from "@econ-v1/app-sdk";

const response = await invokeCapability({
  id: crypto.randomUUID(),
  capability: "core.storage.get",
  payload: { key: "user_pref" },
});
```

## 出版活动

```typescript
import { publishEvent } from "@econ-v1/app-sdk";

publishEvent("my-app.user_created", { userId: 42 });
```

事件名称 **必须** 与应用程序名称相隔的名称( e)`my-app.*`);主机拒绝未命名的事件.

## ABI 兼容性

类型脚本 SDK 目标 **节点主机 API v1** 过IPC。 线条格式是独立版本的,但跟原生(Rust / Go / C / Zig)应用中使用的 C ABI 一样的语义. 见 `core/host-abi-v1/include/node-host-api-v1.h` 为C表面.

## 许可证

根据其中任何一项颁发的许可证

-   Apache 许可证,2.0版本
-   MIT 许可证

随便你.

## 常见问题

### @econ-v1/app-sdk 是什么？

TypeScript SDK，用于在闪电驱动的marketplace守护进程上构建Node迷你应用插件（Bun runtime）

### 如何安装 @econ-v1/app-sdk？

在项目目录运行 npm install @econ-v1/app-sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 burger-build，可以用 npx burger-build 直接运行。

### @econ-v1/app-sdk 支持 TypeScript 吗？

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

### @econ-v1/app-sdk 支持 ESM 还是 CommonJS？

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

### @econ-v1/app-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @econ-v1/app-sdk 可以商用吗？

@econ-v1/app-sdk 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @econ-v1/app-sdk 的下载量有多少？

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

### @econ-v1/app-sdk 还在维护吗？

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