# @north-light/cli 中文文档

规范地址：https://npmcn.com/package/%40north-light/cli/

版本：0\.3\.573
npm 元数据更新时间：2026-11-01T23:59:45.598Z
中文译文更新时间：2026-11-02T01:11:49.187Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40north-light/cli
原文对照：https://npmcn.com/package/%40north-light/cli/?lang=original
项目主页：https://github.com/Northlight-Systems/crouter#readme
源码仓库：https://github.com/Northlight-Systems/crouter

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

- 包体积（解压后）：21.7 MB，2947 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：31 个
- 首次发布：2026-10-09T21:01:29.075Z
- 最新版本发布：2026-11-01T23:59:45.417Z
- 已发布版本数：161（近 12 个月 161 个）

## 中文简介

带有内存、插件和市场的代理运行时

## 安装

```sh
npm install @north-light/cli
```

也可以使用：`pnpm add @north-light/cli`、`yarn add @north-light/cli`、`bun add @north-light/cli`

## README

# crouter—代理运行时：画布上的持久代理，由CLI或SDK驱动

![crouter](https://npmcn.com/package/%40north-light/cli/assets/banner.svg)

[![npm](https://img.shields.io/npm/v/@north-light/cli?label=npm)](https://www.npmjs.com/package/@north-light/cli) [![node](https://img.shields.io/badge/node-%3E%3D22.19-339933)](https://nodejs.org/) [![discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/txKS3swtWY)

crouter是Node.js的代理运行时。每个代理都是一个 **节点**：带有目标、上下文目录和分离进程（它的进程）的记录 _代理_)，它承载模型会话。一个守护进程, `crtrd`，拥有每个节点的状态和生命周期。你用 `crtr` 命令行、终端查看器或类型化TypeScript SDK——这三者都是同一个本地API的客户端。每个模型会话运行 [π](https://github.com/earendil-works/pi)开源编码代理工具；crouter在它周围添加守护进程、节点图、上下文系统和CLI。

关闭终端不会停止代理，正在等待的代理根本没有进程。节点可以产生子节点，向订阅它们的任何人报告，并共享当其他代理变得相关时显示的降价文档。路由器不是模型，也不绑定模型：您在安装期间登录到模型提供程序。它也不是托管服务；它在您的机器上运行，或者在您启动的容器中运行。

[文档](https://crouter.docs.northlight.ai/) · [开始](https://crouter.docs.northlight.ai/docs/cli/first-session) · [概念](https://crouter.docs.northlight.ai/docs/concepts) · [SDK](https://crouter.docs.northlight.ai/docs/sdk) · [插件](https://crouter.docs.northlight.ai/docs/plugin) · [市场](https://github.com/crouton-labs/crouter-official-marketplace) · [不和](https://discord.gg/txKS3swtWY)

## 安装

```bash
npm install -g @north-light/cli
crtr
```

第一个 `crtr` 在机器上打开安装程序安装程序。它将您登录到模型提供者，然后提供配套软件包（包括官方插件市场）和系统依赖项，如tmux。设置后, `crtr` 打开与代理的对话，代理将提供有关路由器工作原理的简短介绍。 `crtr sys setup` 稍后重新打开安装程序。

要求:

-   Node.js 22.19及以上版本。这是pi包所依赖的下限；CI和Docker镜像运行Node 24。
-   Tmux，用于终端内查看器。第一次运行的安装程序提供安装它，并且 `crtr` 开始在外面tmux打开一个 `crouter` Tmux会话，在那里运行。
-   macOS是CI练习的对象。在Linux上，支持的路由是Docker镜像(参见 [在容器中运行它](https://npmcn.com/package/%40north-light/cli/#readme-run-it-in-a-container)）。

## 快速启动

从您希望代理在tmux外部工作的目录中， `crtr` 为你启动它)：

```bash
crtr                                           # a conversation here
crtr . "Inspect this repository and report the failing tests."   # with a first message
crtr -c                                        # return to the latest conversation here
crtr -r <node-id>                              # reopen one conversation by id (`crtr -r` alone picks)
```

输入发送消息；Alt+Enter （Mac上的选项+Enter）或Shift+Enter开始新行。

要在不接管终端的情况下从脚本或其他代理启动代理，请创建一个根节点：

```bash
crtr node new --root "Inspect this repository and report the failing tests."
```

`--root` 创建独立节点并启动其代理。在tmux内部，该命令为它打开一个查看器窗格；在tmux外部，它打印节点id，你自己打开查看器：

```bash
crtr surface attach to <node-id>
```

观众不是代理人。关闭它，节点继续工作；稍后为保存的对话再次打开它。查看画布上的每个节点：

```bash
crtr canvas dashboard     # the subscription tree as ASCII: status, kind, context size
crtr canvas browse        # interactive navigator with tabs and search
crtr canvas attention list  # nodes waiting on you
```

这个 [第一次会议指南](https://crouter.docs.northlight.ai/docs/cli/first-session) 按顺序进行讲解。

## 它是做什么的

每个项命名执行该操作的命令。 `crtr <command> -h` 打印出他们所有人的确切合同。

**节点和委托。** `crtr node new` 创建一个子进程并订阅其父进程；这个孩子报告说 `crtr push update` 以 `crtr push final`，这个报告唤醒了父母。 `--worktree <branch>` 给子进程自己的git工作树 `crtr/<node-id>` 分支, `--fork-from` 从另一个节点的会话启动它，并且 `--output-schema` 使其最终结果成为根据模式验证的JSON文档。决定其工作划分为独立部分的节点运行 `crtr node promote` 成为了一名管弦乐演奏家。

**等待不需要付出任何代价。** 无事可做的节点结束了它的回合并处于休眠状态：没有代理，没有模型调用。一个孩子的报告，一条信息(`crtr node message send`)，一个人类的回答，或者一个cron唤醒它的对话完好无损。如果代理崩溃，守护进程保留节点的行、会话、等待和收件箱； `crtr canvas revive --all` 重新启动后重新连接每个断开连接的节点。

**画布上。** 每个节点、文档、后台作业和所有者都是一个具有名称的对象。 `crtr canvas read`， `list`， `search` 和 `edges` 努力解决所有问题。阅读或编写对象使您成为观察者，因此稍后的编辑和报告将到达您的收件箱。 `crtr canvas history` 搜索目录中过去的运行被告知和说了什么。

**文档。** 知识（咨询）和偏好（遵循）是节点、repo、配置文件、用户或插件拥有的标记文档。传递规则决定是否向代理显示文档的名称，它的一行“读取时”预览，或者它的整个主体——在启动时，当它读取文件时，或者在命令之前。 `crtr doc write` 和 `crtr doc edit` 把它们写; `crtr sys context` 解释为什么载入或不载入； `crtr sys sync` 导入 `CLAUDE.md`， `AGENTS.md`， `.claude/rules` 还有技能包。

**人类的收件箱。** `crtr human send` 将键入的页面（选择器、表格、自由文本）放入收件箱；您的答案被传递回请求的节点。 `crtr human review` 打开带有固定注释的文档以供查看 `crtr human show` 将文件保存在tmux窗格中。

**调度。** `crtr cron add` 存储守护进程每次或每次运行的bash命令(`--at`， `--every`)，并可以将其输出路由到节点的收件箱或新节点(`--sink node:<id>` / `spawn:<kind>`）. 退出75的命令被视为尚未合格，下一个节奏将重新检查它。

**范围。** 节点或远程令牌携带允许列表(`crtr:llm`， `crtr:act`， `crtr:schedule`， `crtr:memory:read:user`，…)，守护进程在执行操作的路由上检查。 `crtr sys connect --app <id> --scopes …` 生成一个令牌，其列表包含应用程序可以创建的所有内容。

**插件和市场。** 市场是一个git插件仓库； `crtr pkg market add <git-url>` 注册一个及 `crtr pkg plugin install <marketplace>/<plugin>` 从它安装。插件可以添加命令（本地可执行文件或HTTP）、文档、代理类型和二进制文件。 `crtr custom-object register` 使外部服务成为画布上的可观察对象。

## 它们是如何组合在一起的

```mermaid
flowchart LR
  CLI[crtr CLI] --> API["/v1 API"]
  SDK[SDK application] --> API
  Viewer[Terminal viewer] --> API
  API --> Daemon[crtrd]
  Daemon --> Canvas[Canvas state]
  Daemon --> Broker[Detached broker per node]
  Viewer -. live session .-> Broker
```

`crtrd` 是唯一的画布状态的作者和唯一的经纪人的启动器。命令行、查看器和SDK应用程序调用其 `/v1` API;它们都不会打开画布数据库或启动自己的引擎。在一台机器上，他们使用一个专用的Unix套接字。浏览器或远程进程使用TCP侦听器和承载令牌(`crtr sys connect`）。

代价是：必须运行一个守护进程（CLI和SDK在第一次使用时启动它），并且远程客户机上的网络故障导致请求失败，而不是重放请求。它所购买的是状态的一个所有者，因此节点比终端、查看器或创建它的应用程序更长寿。 [为什么是守护进程？](https://crouter.docs.northlight.ai/docs/concepts/why-a-daemon) 涵盖了推理。

## 从应用程序中使用路由器

```bash
npm install @north-light/sdk zod
```

```ts
import Crouter from '@north-light/sdk';
import { z } from 'zod';

const client = new Crouter(); // local daemon; started on first request if it is not running

const run = await client.nodes.parse({
  prompt: 'Read package.json and return its name and version.',
  cwd: '/absolute/path/to/project',
  output_schema: z.object({ name: z.string(), version: z.string() }),
});

if (run.kind === 'result') console.log(run.output_parsed.name, run.output_parsed.version);
else console.error(run.reason, run.detail);
```

`nodes.parse` 返回类型化结果或显式失败；它永远不会返回需要解析的文本。 `nodes.stream` 将运行的文本和工具调用管道到UI。看到 [SDK文档](https://crouter.docs.northlight.ai/docs/sdk) 和 [食谱](https://crouter.docs.northlight.ai/docs/sdk/guides).

## 在容器中运行它

```bash
docker run --cap-add SYS_ADMIN --cap-add NET_ADMIN --security-opt seccomp=unconfined --security-opt apparmor=unconfined \
  -e CRTRD_TOKEN=<a-secret-you-choose> -p 7777:7777 ghcr.io/northlight-systems/crtrd
curl -H "Authorization: Bearer <a-secret-you-choose>" http://localhost:7777/healthz
```

图像运行 `crtrd` TCP背后的无头；每个请求都需要承载令牌。它的沙盒启动程序需要两个功能和不受限制的seccomp/AppArmor配置文件。它不包含模型凭据，所以在创建运行之前给代理一个。挂载指定卷 `/volume` 以便在重新启动时保持画布和已安装的凭据。从节点, [`@north-light/env-docker`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-env-docker) 为您启动和停止此容器。详情见 [`docker/README.md`](https://github.com/Northlight-Systems/crouter/blob/main/docker/README.md).

## 延长克劳特

应用程序将类型化操作公开为本机操作 `crtr` 命令与 [`@north-light/plugin`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-plugin)定义一次命令树，它就会生成HTTP处理程序和它的归档文件 `crtr pkg plugin install --endpoint <url> --name <name>` 读取。这个 [插件文档](https://crouter.docs.northlight.ai/docs/plugin) 涵盖命令、参数、输出、错误和部署。

现成的插件就在 [官方市场](https://github.com/crouton-labs/crouter-official-marketplace)： `exa-search`， `capture`， `tsym`， `bird`， `github-asset`， `dev`， `vercel`， `fly`， `railway`， `cloudflare`等等。第一次运行的安装程序提供注册它。

## 包

| 包 | 它是什么？ | 来源 |
| --- | --- | --- |
| [`@north-light/cli`](https://www.npmjs.com/package/@north-light/cli) | 这个 `crtr` CLI, `crtrd` Daemon和终端查看器 | [`src/`](https://github.com/Northlight-Systems/crouter/tree/main/src) |
| [`@north-light/sdk`](https://www.npmjs.com/package/@north-light/sdk) | 类型节点和浏览器客户端：运行、流、结果、文件、bash、内存 | [`packages/crouter-sdk`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-sdk) |
| [`@north-light/plugin`](https://www.npmjs.com/package/@north-light/plugin) | 从一个类型的命令树编写HTTP插件 | [`packages/crouter-plugin`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-plugin) |
| [`@north-light/api`](https://www.npmjs.com/package/@north-light/api) | 这个 `/v1` API合同: `CrtrClient`， dto，路由，错误 | [`packages/crouter-api`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-api) |
| [`@north-light/env-docker`](https://www.npmjs.com/package/@north-light/env-docker) | 开始或连接到 `crtrd` 容器 | [`packages/crouter-env-docker`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-env-docker) |
| [`@north-light/identity`](https://www.npmjs.com/package/@north-light/identity) | 验证访问令牌并评估作用域 | [`packages/crouter-identity`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-identity) |

大多数应用程序只需要 `@north-light/sdk`． 其他存储库内容： [`docs/`](https://github.com/Northlight-Systems/crouter/tree/main/docs) 是文件的来源， [`apps/docs`](https://github.com/Northlight-Systems/crouter/tree/main/apps/docs) 是TanStack Start网站，在crouter.docs.northlight.ai上发布。 [`docker/`](https://github.com/Northlight-Systems/crouter/tree/main/docker) 构建 `crtrd` 形象, [`examples/`](https://github.com/Northlight-Systems/crouter/tree/main/examples) 包含SDK配方和本地主机演示。

## 开发

源存储库是北极光系统私有的；本节是针对其开发人员的。

```bash
git clone git@github.com:Northlight-Systems/crouter.git
cd crouter
npm ci
npm run build
```

考试分三车道进行——单位(`npm test`)，集成，以及针对编译的接缝 `dist/`． 用 `npm run test:isolated`，它将签出复制到临时的 `HOME` 首先：该套件拒绝针对您的真实帐户运行，因为运行时安装程序和项目范围查找可能会写入它。 `test:isolated` 使用 `/usr/bin/lockf` 和 `/Users/Shared`，所以它运行在macOS上。

```bash
npm run test:isolated                    # unit lane
npm run test:isolated -- integration seam
npm run test:isolated -- path/to/file.test.ts
```

文档站点运行于 `apps/docs` 与 `npm run dev`. [CONTRIBUTING.md](https://npmcn.com/package/%40north-light/cli/CONTRIBUTING.md) 有北极光系统开发人员的下拉请求约定。

## 安全

要报告漏洞，请执行以下操作 [SECURITY.md](https://github.com/Northlight-Systems/crouter/blob/main/SECURITY.md) 而不是公开问题。

## 许可证

路由器是专有软件。版权所有2026 Northlight Systems版权所有。源存储库是私有的；这些包以编译后的、缩小的构建版本的形式发布到NPM。看到 [许可证](https://npmcn.com/package/%40north-light/cli/LICENSE).

## 常见问题

### @north-light/cli 是什么？

带有内存、插件和市场的代理运行时

### 如何安装 @north-light/cli？

在项目目录运行 npm install @north-light/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 crtr、crtrd、crouter、crtr-launcher，可以用 npx crtr 直接运行。

### @north-light/cli 支持 TypeScript 吗？

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

### @north-light/cli 支持 ESM 还是 CommonJS？

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

### @north-light/cli 可以商用吗？

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

### @north-light/cli 还在维护吗？

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