# @cargo-ai/app-sdk 中文文档

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

版本：1\.0\.12
npm 元数据更新时间：2026-11-06T00:01:18.844Z
中文译文更新时间：2026-11-09T03:08:37.123Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：826 kB，311 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：41 个
- peer 依赖：react 18\.3\.1，react-dom 18\.3\.1，@cargo-ai/api ^1\.0\.107，react-router-dom ^6\.30\.6，@auth0/auth0-react ^2\.11\.0
- 首次发布：2026-05-12T01:38:16.866Z
- 最新版本发布：2026-11-06T00:01:18.613Z
- 近 30 天下载量：80542（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

货物托管 App SDK : 货物 OAuth 认证提供者, 精细化数据提供者于 @cargo-ai/ api 上, shadcn/ui 主题, 版式, 以及用于 Vite + React apps 部署到货物托管的钩子

## 安装

```sh
npm install @cargo-ai/app-sdk
```

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

## README

# @ cargo-ai/ app- sdk

用于构建 Cargo 主机应用程序的 SDK — a Vite + React + [细化](https://refine.dev/) 捆绑,可以让你工作 货物OAuth 登录,一个打字 [`@cargo-ai/api`](https://www.npmjs.com/package/@cargo-ai/api) 客户端(通过) `useCargoApi()`),一个有"阴影"(Shadcn/ui)风格的主题,而标准精细的取景脚手架——因此克洛德代码(或您)可以在实际上很重要的屏幕上花出符号.

## 安装

```sh
npm install @cargo-ai/app-sdk @cargo-ai/api @auth0/auth0-react react react-dom react-router-dom
```

## 用这个

```tsx
// src/App.tsx
import { CargoRefineApp, CargoSiderLayout } from "@cargo-ai/app-sdk";
import { Routes, Route } from "react-router-dom";
import { Inbox } from "lucide-react";

import { LeadInbox } from "./pages/LeadInbox";

const resources = [
  {
    name: "leads",
    list: "/",
    meta: { label: "Leads", icon: <Inbox className="h-4 w-4" /> },
  },
];

export const App = () => (
  <CargoRefineApp resources={resources}>
    <CargoSiderLayout title="Lead Console">
      <Routes>
        <Route path="/" element={<LeadInbox />} />
      </Routes>
    </CargoSiderLayout>
  </CargoRefineApp>
);
```

## 什么样的船

-   `<CargoRefineApp>` ——货物OAuth + 精炼+路由器+货物API上下文,全部有线.
-   `CargoAuthProvider` ——细化 `AuthProvider` 打开应用程序 `app_metadata.workspaceUuids` 匹配构建时间 `VITE_CARGO_WORKSPACE_UUID`。 。 。 .
-   钩子: `useCargoApi()` 对于输入的 API 客户端, `useCargoAnalytics()` 用于页面视图+自定义事件.
-   布局 : `<CargoSiderLayout>`, (中文(简体) ), `<CargoEmpty>`, (中文(简体) ), `<CargoErrorBoundary>`, (中文(简体) ), `<CargoUserMenu>`, (中文(简体) ), `<CargoWorkspaceBadge>`。 。 。 .
-   查看包装符 : `<List>`, (中文(简体) ), `<Show>`, (中文(简体) ), `<Edit>`, (中文(简体) ), `<Create>`, (中文(简体) ), `<DataTable>`。 。 。 .
-   货物域复合材料 `src/components/domain/<domain>/`: 只读图标 / 徽章 / 牌在打入的上方 `@cargo-ai/api` 域名类型——代理,工作流程+运行状态,数据集/模型,片段,集成/连接器,成员(外加自取自取) `<MemberSelect>`) (中文(简体) ).
-   从登记册上复制到 `src/components/ui/`: 表单(`<Button>`, (中文(简体) ), `<Input>`, (中文(简体) ), `<Textarea>`, (中文(简体) ), `<Label>`, (中文(简体) ), `<Checkbox>`, (中文(简体) ), `<RadioGroup>`, (中文(简体) ), `<Switch>`, (中文(简体) ), `<Slider>`, (中文(简体) ), `<Select>`, (中文(简体) ), `<Toggle>`, (中文(简体) ), `<ToggleGroup>`, (中文(简体) ), `<Calendar>`),表面(`<Card>`, (中文(简体) ), `<Sheet>`, (中文(简体) ), `<Dialog>`, (中文(简体) ), `<AlertDialog>`, (中文(简体) ), `<Popover>`, (中文(简体) ), `<HoverCard>`, (中文(简体) ), `<Tooltip>`, (中文(简体) ), `<Separator>`, (中文(简体) ), `<ScrollArea>`, (中文(简体) ), `<Collapsible>`, (中文(简体) ), `<Accordion>`),导航(`<Tabs>`, (中文(简体) ), `<Breadcrumb>`, (中文(简体) ), `<Pagination>`, (中文(简体) ), `<NavigationMenu>`, (中文(简体) ), `<DropdownMenu>`, (中文(简体) ), `<ContextMenu>`, (中文(简体) ), `<Menubar>`, (中文(简体) ), `<Command>`),显示(`<Table>`, (中文(简体) ), `<Badge>`, (中文(简体) ), `<Avatar>`, (中文(简体) ), `<Skeleton>`, (中文(简体) ), `<Progress>`, (中文(简体) ), `<Spinner>`, (中文(简体) ), `<Alert>`, (中文(简体) ), `<Toaster>`)和图表`<ChartContainer>` + 帮助者, 包装 `recharts`) (中文(简体) ).
-   尾风预设( T)`@cargo-ai/app-sdk/tailwind-preset`\+ 基础CSS(`@cargo-ai/app-sdk/styles.css`) (中文(简体) ).

## 环境 vars

货运主机自动将这些烤入捆绑. 用于本地 dev 运行 `cargo-ai hosting app env <appUuid> > .env.local`数字 :

```
VITE_CARGO_OAUTH_DOMAIN=...
VITE_CARGO_OAUTH_CLIENT_ID=...
VITE_CARGO_OAUTH_AUDIENCE=...
VITE_CARGO_API_URL=https://api.getcargo.io
VITE_CARGO_WORKSPACE_UUID=...
VITE_CARGO_APP_UUID=...
VITE_APP_BASE_PATH=/
```

接下来,Js应用读取相同的 vars 与 a `NEXT_PUBLIC_` 前缀( e)`NEXT_PUBLIC_CARGO_API_URL`; 货物托管同时注入.

## 添加阴影原始物

装有Shadcn/ui部件的包船复制成型 `src/components/ui/`通过有线CLI拉出一个新的:

```sh
npm run -w @cargo-ai/app-sdk shadcn:add -- <component>
# e.g.
npm run -w @cargo-ai/app-sdk shadcn:add -- tooltip
```

运行 `shadcn@latest add` 对这个包 `components.json`后处理器(`scripts/shadcn-postprocess.mjs`重写CLI的 `@/` 进口到相对 `./…/foo.js` 路径和条 `"use client"` 因此文件符合SDK的节点Next / Vite 形状。 完成后:

1.  添加新导出到 `src/index.ts` 手(CLI不碰桶).
2.  如果组件拉入 CSS 变量,我们还没有定义(例如:. `--chart-1` 页:1 `chart`),添加到 `styles.css`。 。 。 .

比较当地原始物与上游阴影源:

```sh
npm run -w @cargo-ai/app-sdk shadcn:diff -- <component>
```

> **不运行 `npx shadcn init` 本包中.** `components.json`, (中文(简体) ), `styles.css`,以及 `tailwind.config.ts` 手取之; `init` 会覆盖他们。 仅 `add` 编号 : `diff` 这是安全的.

## 参考文献

-   [SKILLL.MD (英语)](https://npmcn.com/package/%40cargo-ai/app-sdk/skill/SKILL.md) ——即时克洛德代码在脚手架应用时会读取.
-   [@cargo-ai/ api](https://www.npmjs.com/package/@cargo-ai/api) ——打出货物API客户端.
-   [文件.getcargo.ai/参考/介绍](https://docs.getcargo.ai/api-reference/introduction) ——REST参考.

## 常见问题

### @cargo-ai/app-sdk 是什么？

货物托管 App SDK : 货物 OAuth 认证提供者, 精细化数据提供者于 @cargo-ai/ api 上, shadcn/ui 主题, 版式, 以及用于 Vite \+ React apps 部署到货物托管的钩子

### 如何安装 @cargo-ai/app-sdk？

在项目目录运行 npm install @cargo-ai/app-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（18\.3\.1）、react-dom（18\.3\.1）、@cargo-ai/api（^1\.0\.107）、react-router-dom（^6\.30\.6）、@auth0/auth0-react（^2\.11\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cargo-ai/app-sdk 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cargo-ai\_\_app-sdk 是否存在。

### @cargo-ai/app-sdk 支持 ESM 还是 CommonJS？

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

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

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

### @cargo-ai/app-sdk 可以商用吗？

@cargo-ai/app-sdk 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @cargo-ai/app-sdk 的下载量有多少？

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

### @cargo-ai/app-sdk 还在维护吗？

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