# @alva-ai/toolkit 中文文档

规范地址：https://npmcn.com/package/%40alva-ai/toolkit/

版本：0\.34\.0
npm 元数据更新时间：2026-10-28T09:26:29.504Z
中文译文更新时间：2026-11-09T20:33:12.668Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40alva-ai/toolkit
原文对照：https://npmcn.com/package/%40alva-ai/toolkit/?lang=original
项目主页：https://github.com/alva-ai/toolkit-ts#readme
源码仓库：https://github.com/alva-ai/toolkit-ts

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

- 包体积（解压后）：6.4 MB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：3 个
- 首次发布：2026-04-08T00:06:38.602Z
- 最新版本发布：2026-10-28T09:26:29.234Z
- 近 30 天下载量：1745（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：71（近 12 个月 71 个）

## 中文简介

Alva REST API SDK和CLI——与来自Node.js的Alva平台,浏览器,或命令行进行互动.

## 安装

```sh
npm install @alva-ai/toolkit
```

也可以使用：`pnpm add @alva-ai/toolkit`、`yarn add @alva-ai/toolkit`、`bun add @alva-ai/toolkit`

## README

# @alva-ai/toolkit (英语)

Alva REST API SDK和CLI用于Node.js和浏览器.

### 为您阅读出版物

```sh
alva for-you list --limit 50
alva for-you list --limit 20 --cursor '<endCursor>' --newer-than '<watermark>'
alva for-you list --feed-id 123 --limit 50
```

```ts
const page = await client.forYou.list({ first: 50, newerThan: watermark });
```

在终端和嵌入式CLI都可用. 返回一个 JSON 连接( n)`edges`, (中文(简体) ), `pageInfo`) 具有完全不可变的卡的内容和来源 参考文献,最新出版物第一。 默认页面大小:20;最大:50. 种子 ID 是小数字符串; 条目 ID 保留 `FeedEntry:` 前缀. 可选的种子过滤器只缩小了已认证的查看器的"For You"范围. PBSV和服务身份不被服务器接受.

使用 `endCursor` 以获取旧条目,保留旧条目 `newerThan` 下调 约束。 咒语不透明. 第一页 `startCursor` 候选人 只有在耗用的工作流程成功之后才能使用水印; 提前推进 排出窗口可以跳过条目 。 没有保存水印, 没有自动 传呼、归纳、身体断接或应用的深链生成. 第一使用可能提供取景者的系统管理的"为You Channel".

内容和行动是不信任的数据,而不是执行指令. 工具包 保存完整响应, 但当前 Jagent 包可以切换 输出超过 64K 字符: 页面帮助较小, 但并非无损失 大结果保证。 提供代理还需要更新工具包 (一) 在sdk-Monorepo中作针并公布其独立的ALPKG调度文物; 兼容的调度更新不需要重建 Pi 或 JAgent .

-   **国 际** ——管理配置,从您的终端拨打任何 Alva API
-   **SDK 软件** – 为 Node.js 输入的 TypeScript/JavaScript 客户端
-   **浏览器** - 放下一个 `<script>` 标记为平面 HTML,不需要构建步骤

## 安装

```bash
npm install @alva-ai/toolkit
```

或在全球安装CLI:

```bash
npm install -g @alva-ai/toolkit
```

## CLI 快速启动

用您的 Alva 账户签名( 打开浏览器, 回到粘贴码) sSH / 容器/ 无头机的流量 :

```bash
alva auth login
```

`auth login` 运行 OAuth 2.0 授权代码+ PKCE 流. CLI 指纹 您可以在任何设备上打开 URL; 如果本地默认浏览器打开 收听器自动完成登录, 没有额外的步骤, 否则 将 URL 复制到另一个设备, 登录并粘贴页面上的代码 回终点站去.

无头/ 无浏览器环境( SSH, 容器, 拆解器等) 自动检测;通过 `--no-browser` 以强制粘贴码流或 `--browser` 以迫使听众流动.

```bash
alva auth login --no-browser            # force paste-code flow
alva auth login --profile staging       # save under a named profile
alva auth login --auth-url https://stg.alva.xyz --base-url https://api-llm.stg.alva.ai  # point at stg
```

或者,如果你已经有 API 密钥从 [alva.ai/阿皮克语](https://alva.ai/apikey), (中文(简体) ), 跳过 OAuth 流并直接存储密钥 :

```bash
alva configure --api-key alva_your_key_here
```

将您的证书写给 `~/.config/alva/config.json`。 。 。 .

现在使用任意命令 :

```bash
# List your files
alva fs readdir --path /

# Run code
alva run --code 'return 1 + 1'

# Manage cronjobs
alva deploy list

# Manage secrets
alva secrets list
```

所有输出都是JSON 方便的管道:

```bash
alva fs readdir --path / | jq '.entries[].name'
```

### 阵列 JWT

`alva configure` 自动提供阵列 JWT 服务器侧面(dimpotent, 网络错误的软故障—— `configure` 仍为0出站. 标志是 存放在您的沙盒中的秘密 `ARRAYS_JWT`; CLI 从来不处理 符号串本身.

手动检查或重运行 :

```bash
alva arrays token ensure   # sign-if-needed; returns expires_at + tier
alva arrays token status   # returns exists + renewal_needed
```

`alva whoami` 也报告目前JWT的情况 `_meta.arrays_jwt`。 。 。 .

### 游戏本技能

从 alva-gateway 浏览游戏本模板( 系统 + 用户创建) 大众API. 技能被命名为空格 `<username>/<name>`。 。 。 .

需要用户认证- 运行 `alva auth login` 先说.

流动是渐进的:

-   `get` 返回元数据 + 文件列表(路径 + 大小 - 没有内容).
-   `file` 一次获取一个文件的内容 .

散装内容是故意的 **没有** 暴露于 CLI/ SDK 层; 代理 应先获取文件列表,然后只取出它们需要的文件.

```bash
alva skillhub list                                          # skill catalog
alva skillhub list --tag research                           # filter by tag
alva skillhub list --username alva                          # filter by author
alva skillhub tags                                          # skill tags
alva skillhub get alva/ai-digest                            # metadata + file listing
alva skillhub file alva/ai-digest README.md                 # one file's content
alva skillhub file alva/ai-digest references/api/example.md > out.md
```

默认的输出是相当印刷的人类。 过 `--json` 获取 原始内容 `{success, data}` 信封(例如用于管道 `jq`) (中文(简体) ).

### 游戏本发现

以紧凑,方便代理的结果外形来发现公共剧本. 这个 趋势端点返回标识符和排序上下文,省略 前端仅预览字段.

```bash
alva playbooks trending --keyword scanner --tags macro,ai --sort recent --limit 5
alva playbooks trending --tag btc --cursor <cursor>
```

### 游戏本函数

注册创建者拥有的功能,用于发行的游戏本 `window.alva.udf`。函数条目脚本必须生活在绝对的 ALFS `.js` 在创建者的家目录下。 查看器信贷津贴得到管理 通过网关 REST 会话-用户表面.

```bash
alva functions register --playbook-id 123 --function-name analyze --entry-script-path /alva/home/alice/playbooks/my-playbook/udf/analyze.js --params-schema-file ./schema.json --no-allow-charges
alva functions list --playbook-id 123
alva functions delete --playbook-id 123 --function-name analyze
alva functions invoke --playbook-id 123 --function-name analyze --params '{"ticker":"AAPL"}'
alva functions allowance create --playbook-id 123 --amount 25
alva functions allowance get --playbook-id 123
alva functions allowance list
alva functions allowance revoke --playbook-id 123
```

### 数据技能

浏览 Arrays 后端的数据技能文档 。 这些终点是: 公开——不需要阿尔瓦证书.

```bash
alva data-skills list                            # catalog of skills
alva data-skills summary <skill>                 # endpoints table for a skill
alva data-skills endpoint <skill> <file>         # full endpoint spec
```

### 配置解析

CLI 解决此顺序的配置 :

1.  `--api-key` 编号 : `--base-url` 旗帜
2.  `ALVA_API_KEY` 编号 : `ALVA_ENDPOINT` 环境变量
3.  `~/.config/alva/config.json` (或 `$XDG_CONFIG_HOME/alva/config.json`(中文(简体) )

### 嵌入式CLI调度

嵌入式运行时间可以直接重用 CLI 调度器而无需加载 结点Js CLI外壳或产卵 `alva` 二进制 :

```typescript
import { AlvaClient } from '@alva-ai/toolkit';
import { dispatch, CliUsageError } from '@alva-ai/toolkit/dispatch';

const client = new AlvaClient({ apiKey: process.env.ALVA_API_KEY });
const result = await dispatch(client, ['account', 'whoami']);
```

嵌入式调度器总是会暴露 阿尔皮阿尔瓦命令 目录. 它独立于包装系统 `alva` CLI(英语:CLI). 认证/设置、阵列靴、SDK文档、重复的别名、, 传统高级分组,以及 `feedback submit` 不属于此目录; 旧的代理路径被拒绝而不是化名 。 运行嵌入式 `--help` 页:1 活树。 独立的系统CLI继续暴露反馈.

嵌入式表面与 ALFS 本地工具对齐: 本地文件旗等 `--local-file`, (中文(简体) ), `--file`, (中文(简体) ), `--params-schema-file`截图 `--out` 为: 缺席。 论文命令同样接受文字 `--body` 仅: 本地文件和 stdin 没有经过核实的嵌入式适配器 。 发送前使用 ALFS 中的内置数据或准备内容 命令; 代理截图直接返回图像内容. `dispatch()` 掷出 `CliUsageError` 用于命令行使用错误和 `AlvaError` aPI 错误. 管理命令在引用 API 之前拒绝未知的旗帜 . `trading broker` 是明确的例外, 因为嵌入后前缀会转发 argv 现场代理合同的逐字记录.

节点.js命令线消费者应继续使用 `@alva-ai/toolkit/cli`,增加了配置文件、认证、本地文件, stdio, 及其独立终端周围的 Undici 超时配置 调度员 两个条目都共享SDK和低级命令执行处理器, 不是他们的目录, 解析器, 或帮助.

### 对 ALPI 进行嵌入式 CLI 修改

合并工具包或发布其npm CLI不会更新ALPI. 更新 `sdks/toolkit-dispatch/toolkit` 在Sdk-Monorepo, 冲击调度包版本, 并放在那里: 合并为 STG 主机, 然后使用包放出标记 在Slim Skill/Pi的发布之前发布消息.

见 [SDK 发布指令](https://github.com/alva-ai/sdk-monorepo#package-scoped-production-releases)。 。 。 .

## SDK 用法(节点.js)

```typescript
import { AlvaClient } from '@alva-ai/toolkit';

const client = new AlvaClient({ apiKey: 'alva_your_key_here' });

// List files
const entries = await client.fs.readdir({ path: '/' });

// Run code
const result = await client.run.execute({ code: 'return 1 + 1' });

// Manage cronjobs
const jobs = await client.deploy.list();

// Manage secrets
const secrets = await client.secrets.list();
```

## 浏览器使用

通过 CDN 添加浏览器捆绑 :

```html
<script src="https://unpkg.com/@alva-ai/toolkit/dist/browser.global.js"></script>
<script>
  const client = new AlvaToolkit.AlvaClient({
    viewer_token,
  });

  client.fs.readdir({ path: '/' }).then((entries) => {
    console.log(entries);
  });
</script>
```

> **说明:** Alva API 必须配置用于浏览器请求的 CORS 头条, 以便从您的源头工作 .

### 游戏本 运行时 UDFs

当浏览器捆绑被装入 Alva 游戏本 Iframe 中时,它也会 安装 `window.alva.udf`。运行时间读取游戏本扫描器 符号( r)`_pbsv`) 从 Iframe URL 中,只删除该敏感查询 参数,接受父程序令牌刷新,并使用 PBSV 页眉用于 UDF电话.

注册创建方函数先与 `alva functions register`; 查看器 HTML 应调用浏览器运行时间, 而不是手写 API 获取 .

```html
<script src="https://unpkg.com/@alva-ai/toolkit/dist/browser.global.js"></script>
<script>
  (async () => {
    const response = await window.alva.udf.call('analyze', { ticker: 'AAPL' });
    console.log(response.result, response.credits_charged_consumer);
    const functions = await window.alva.udf.list();
  })();
</script>
```

对于快速交互控制,请挂载运行时管理的UDF按钮. 按钮 禁用,直到 PBSV 令牌出现并发布 DOM 事件进行加载, 结果和错误.

```html
<div id="analyze"></div>
<script>
  const button = window.alva.udf.renderButton('#analyze', {
    functionName: 'analyze',
    params: { ticker: 'AAPL' },
    label: 'Run analysis',
  });

  button.addEventListener('alva:udf-button:result', (event) => {
    console.log(event.detail.result.result);
  });
</script>
```

对于模块用户,从软件包根中可以找到同样的运行时间:

```typescript
import { installPlaybookRuntime, udf } from '@alva-ai/toolkit';

installPlaybookRuntime();
const response = await udf.call('analyze', { ticker: 'AAPL' });
```

## API 参考

### 资源

| 资源 | 方法 |
| --- | --- |
| `client.user` | `me()` |
| `client.fs` | `read()`, (中文(简体) ), `write()`, (中文(简体) ), `rawWrite()`, (中文(简体) ), `stat()`, (中文(简体) ), `readdir()`, (中文(简体) ), `mkdir()`, (中文(简体) ), `remove()`, (中文(简体) ), `rename()`, (中文(简体) ), `copy()`, (中文(简体) ), `symlink()`, (中文(简体) ), `readlink()`, (中文(简体) ), `chmod()`, (中文(简体) ), `grant()`, (中文(简体) ), `revoke()` |
| `client.run` | `execute()` |
| `client.deploy` | `create()`, (中文(简体) ), `list()`, (中文(简体) ), `get()`, (中文(简体) ), `update()`, (中文(简体) ), `delete()`, (中文(简体) ), `pause()`, (中文(简体) ), `resume()` |
| `client.release` | `feed()`, (中文(简体) ), `playbookDraft()`, (中文(简体) ), `playbook()` |
| `client.playbooks` | `trending()` |
| `client.theses` | `create()`, (中文(简体) ), `get()`, (中文(简体) ), `update()`, (中文(简体) ), `close()`, (中文(简体) ), `delete()`, (中文(简体) ), `rewrite()` |
| `client.functions` | `register()`, (中文(简体) ), `list()`, (中文(简体) ), `delete()`, (中文(简体) ), `invoke()`, (中文(简体) ), `getAllowance()`, (中文(简体) ), `listAllowances()`, (中文(简体) ), `createAllowance()`, (中文(简体) ), `revokeAllowance()` |
| `client.secrets` | `create()`, (中文(简体) ), `list()`, (中文(简体) ), `get()`, (中文(简体) ), `update()`, (中文(简体) ), `delete()` |
| `client.sdk` | `doc()`, (中文(简体) ), `partitions()`, (中文(简体) ), `partitionSummary()` |
| `client.comments` | `create()`, (中文(简体) ), `pin()`, (中文(简体) ), `unpin()` |
| `client.remix` | `save()` |
| `client.screenshot` | `capture()` |

### 处理错误

```typescript
import { AlvaClient, AlvaError } from '@alva-ai/toolkit';

try {
  await client.fs.read({ path: '/nonexistent' });
} catch (err) {
  if (err instanceof AlvaError) {
    console.error(err.code); // 'NOT_FOUND'
    console.error(err.status); // 404
    console.error(err.message); // 'File not found'
  }
}
```

## 管理公司新闻

在不上传脚本的情况下创建私有、后端管理的新闻种子或 给自己安排了工作 1 feed 覆盖了所提供的全部计数器列表 :

```bash
alva company-news create --name my-company-news --tickers NVDA,AMD,AAPL
alva company-news create --name earnings-news --tickers NVDA,AMD --initial-lookback-hours 48 --page-size 30
```

使用配置的 Alva API 密钥和 vNext GraphQL 业务突变 `companyNews { createFeed(input: ...) }` 通过 `POST /query`后端 拥有出厂码,并创建了Feed,它的克容和处理状态. 回复包含小数字符串 `feed_id` 财务报告和审定财务报表 `cronjob_id`; 新创建 生产商 **已暂停**,而创造不引用模型或花费模型 学分。 审查配置,然后从终端CLI中明确开始 当准备就绪( 装入式发送不暴露 Feed 生命周期命令) :

```bash
alva feed resume --id <feed_id>
```

一旦恢复使用,模型使用费由经认证的创作者支付。 公司新闻 ; 恢复不能启用按键通知。 没有 `--path`脚本 支持上传,所有者覆盖或自动启动旗.

名称必须是所有者- 本地, 1–64 个字母数字/ 连字符, 起始为一个 数字字符,而非 `news-lane`供应 1-1000 独有的大写 计数器(每个最多20个字符). `--initial-lookback-hours` 接受 0–168次访问 (违约24); `--page-size` 接受 0–100(默认 20)。 0 选择后端 默认。 大宇宙是逐渐读出而不是全部读出.

以 **同名和配置**; 此返回 不改变现有资源是否运行。 不同 同名下配置冲突。 此命令不更新一个 已存在的滴答宇宙. 不同的名称会创建独立的Feeds,即使它们的计时器重叠. 用于单个计时器 `--tickers NVDA`;对许多人来说,通过完整的逗号分隔 列表一次。 不支持在同一 Feed 上递增附加计数器 .

SDK 等量 :

```typescript
const { feed_id, cronjob_id } = await client.companyNews.create({
  name: 'my-company-news',
  tickers: ['NVDA', 'AMD'],
  initial_lookback_hours: 24,
  page_size: 20,
});
```

需要同行网关适配器和后端公司新闻的部署, 移徙。 无法使用的后端明显失败 ; cLI不会回到脚本部署。 终端和嵌入式调度 两者都支持创建,但仅发布这个npm CLI并不能更新ALPI; 遵循下面嵌入式CLI发布指令.

## CLI 命令

```text
alva configure --api-key <key> [--base-url <url>] [--profile <name>]
alva whoami [--profile <name>]
alva auth login [--browser | --no-browser] [--profile <name>]
alva user me
alva fs <read|write|stat|readdir|mkdir|remove|rename|copy|symlink|readlink|chmod|grant|revoke>
alva run --code <code> [--entry-path <path>] [--working-dir <dir>] [--args <json> | --args-stdin] [--timeout-ms <ms>]
alva deploy <create|list|get|update|delete|pause|resume|runs|run-logs>
alva release <feed|playbook-draft|playbook>
alva playbooks <trending>
alva thesis <list|related|create|get|signals|set-visibility|update|close|delete|rewrite>
alva thesis version get --id <thesis-id> --author-version-id <version-id>
alva thesis list --person <slug>       # or --person-name <name> / --user <username>
alva thesis list --ticker NVDA         # or --entity-id <id>; --cursor <nextCursor>
alva thesis related --id <playbook-id>
alva functions <register|list|delete|invoke|allowance>
alva secrets <create|list|get|update|delete>
alva sdk <doc|partitions|partition-summary>
alva skillhub <list|tags|get|file> [<user>/<name>] [<file>] [--tag <t>] [--username <u>] [--json]
alva data-skills <list|summary|endpoint> [<skill>] [<file>] [--json]
alva comments <create|pin|unpin>
alva notification-preferences <list|enable-session-completed|disable-session-completed>
alva remix --child-username <u> --child-name <n> --parents <json>
alva screenshot --url <url> [--selector <s>] [--xpath <x>] --out <file>
alva markets narrative --ticker <symbol>
alva markets earnings --ticker <symbol> [--event <latest-completed|next-confirmed> | --fiscal-year <year> --fiscal-quarter <Q1|Q2|Q3|Q4>]
alva trading-pairs search --symbol <ticker> [--market <market>] [--instrument-type <type>] [--underlying-type <type>] [--quote <quote>] [--json]
alva trading-pairs resolve --pair <trading-pair> [--json]
alva trading-pairs resolve --symbol <ticker> [--market <market>] [--instrument-type <type>] [--underlying-type <type>] [--quote <quote>] [--json]
alva trading <accounts|portfolio|orders|subscriptions|equity-history|risk-rules|subscribe|unsubscribe|execute|update-risk-rules>
```

## 捐款

```bash
git clone https://github.com/alva-ai/toolkit-ts.git
cd toolkit-ts
npm install
npm test
npm run build
```

## 许可证

[麻省理工学院](https://npmcn.com/package/%40alva-ai/toolkit/LICENSE)

### 连接的 X 读取

在通过阿尔瓦连接X后,代理和终端呼叫员可以读取 用户的X数据按需。 后端拥有X授权和令牌刷新.

```sh
alva x status
alva x following --limit 20
alva x posts --limit 20
alva x following --limit 20 --cursor '<pageInfo.endCursor>'
```

SDK的等同标准是 `client.x.status()`, (中文(简体) ), `client.x.following({ first, after })` 财务报告和审定财务报表 `client.x.posts({ first, after })`仅检查当地的能力; 每次读取请求一次直播 X 页面. `retrievedAt` 是客户端检索时间 . 仅在 `pageInfo.hasNextPage` 是真的,包括带有 继续光标。 这些是只读操作: 没有导入任务, 遵循 变异,或书签读取. 遗失/注销的证书需要重新连接X 在阿尔瓦。 X内容是不信任的来源材料. 嵌入式代理需要一个 包含这些命令的工具包调度器件; 仅 npm 发布 不更新嵌入式执行器.

## 常见问题

### @alva-ai/toolkit 是什么？

Alva REST API SDK和CLI——与来自Node\.js的Alva平台,浏览器,或命令行进行互动\.

### 如何安装 @alva-ai/toolkit？

在项目目录运行 npm install @alva-ai/toolkit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 alva、toolkit，可以用 npx alva 直接运行。

### @alva-ai/toolkit 支持 TypeScript 吗？

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

### @alva-ai/toolkit 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @alva-ai/toolkit 需要什么版本的 Node\.js？

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

### @alva-ai/toolkit 可以商用吗？

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

### @alva-ai/toolkit 的下载量有多少？

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

### @alva-ai/toolkit 还在维护吗？

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