nolo-cli 0.1.51 → 0.1.52

package/README.md

@@ -1,70 +1,55 @@
 # @nolo/cli
 
-Agent-first terminal client for Nolo.
+面向 Agent 的 Nolo 终端客户端。
 
-`nolo` should be understood as the terminal workspace for Nolo agents. The
-existing command mode still wraps repo scripts, but the product direction is a
-TUI-first experience similar to Claude Code / Codex CLI:
+`nolo` 是 Nolo 智能体的终端工作空间。现有的命令模式仍然包装仓库脚本，但产品方向是类似于 Claude Code / Codex CLI 的 TUI 优先体验：
 
-- open `nolo` and work inside a persistent Agent session;
-- chat with an Agent;
-- inspect and manage that Agent's dialogs, docs, tables, skills, and spaces;
-- run internal ops/doctor agents with the same mental model;
-- use non-interactive commands and `--json` for automation.
+- 打开 `nolo`，在持久的 Agent 会话中工作；
+- 与 Agent 聊天；
+- 检查和管理该 Agent 的 dialogs、docs、tables、skills 和 spaces；
+- 以同样的心智模型运行内部 ops/doctor agents；
+- 使用非交互式命令和 `--json` 进行自动化。
 
-The current MVP uses a dependency-free readline workspace. It is intentionally
-small: status line, text input, lightweight slash commands, and script-backed
-Agent chat. A richer Ink UI can replace the rendering layer later without
-changing the session model.
+当前的 MVP 使用无依赖的 readline 工作空间。它故意保持小巧：状态行、文本输入、轻量级斜杠命令和脚本驱动的 Agent 聊天。未来可以用更丰富的 Ink UI 替换渲染层，而无需更改会话模型。
 
-Inside `nolo`, normal text continues the current dialog after the first agent
-reply. Use `/new` when you want a clean dialog. Response token details stay
-hidden by default; set `NOLO_SHOW_USAGE=1` when debugging usage.
+在 `nolo` 内部，收到第一条 Agent 回复后，普通文本继续当前 dialog。需要清空 dialog 时使用 `/new`。响应的 token 详情默认隐藏；调试用量时设置 `NOLO_SHOW_USAGE=1`。
 
-Nolo is intentionally not trying to copy coding-only CLIs one-for-one. Claude
-Code, Codex CLI, and Copilot CLI are strongest when a developer is already
-inside a codebase. Nolo's CLI should sit between ordinary users and developers:
-one assistant by default, with specialist agents, docs, tables, dialogs, and
-synced workspace data one slash command away.
+Nolo 并非试图逐字复刻纯编码 CLI。Claude Code、Codex CLI 和 Copilot CLI 在开发者已进入代码库时表现最佳。Nolo 的 CLI 应介于普通用户和开发者之间：默认提供一个助理，而专业 agent、docs、tables、dialogs 和同步工作空间数据只需一个斜杠命令。
 
-## Usage
+## 使用说明
 
 ```bash
 npm install -g nolo-cli
 nolo
 
-# see which install you are running
+# 查看当前运行的安装版本
 nolo doctor
 nolo --version
 
-# no Nolo login required: runs the local Codex CLI in the current directory
+# 无需 Nolo 登录：在当前目录运行本地 Codex CLI
 nolo run "review this repository"
 
-# update later from your shell
+# 稍后从 shell 更新
 nolo update
 ```
 
-Inside the TUI, run:
+在 TUI 内部运行：
 
 ```text
 /update
 ```
 
-The published npm package runs on plain Node.js (no Bun required). The
-shipped entry is a bundled `index.js` with a `#!/usr/bin/env node` shebang.
+发布的 npm 包在纯 Node.js 上运行（不需要 Bun）。打包入口是一个包含 `#!/usr/bin/env node` shebang 的单一 bundle `index.js`。
 
-For local maintainer workflows, `nolo run "..."` does not require a Nolo
-account. It resolves to the built-in `local-codex` agent, runs in the current
-working directory, and uses the local Codex CLI installation. This is intended
-for repository-local review, triage, and release-check tasks.
+对于本地维护者工作流，`nolo run "..."` 不需要 Nolo 账户。它会解析为内置的 `local-codex` agent，在当前工作目录运行，并使用本地 Codex CLI 安装。这适用于仓库本地的审查、分类和发布检查任务。
 
-Remote Nolo records and synced workflows still require a token:
+远程 Nolo 记录和同步工作流仍需要 token：
 
 ```bash
 NOLO_SERVER=https://nolo.chat AUTH_TOKEN=<token> nolo
 ```
 
-Or save a local profile once:
+或者一次性保存本地配置文件：
 
 ```bash
 nolo login --server https://nolo.chat
@@ -72,25 +57,21 @@ nolo whoami
 nolo
 ```
 
-By default, `nolo login` opens the Nolo website and waits for browser
-authorization. In SSH or browserless environments, use:
+默认情况下，`nolo login` 打开 Nolo 网站并等待浏览器授权。在 SSH 或无浏览器环境中，使用：
 
 ```bash
 nolo login --no-browser
 ```
 
-Then open the printed URL on a logged-in browser. Automation can still save a
-token directly:
+然后在已登录的浏览器中打开打印的 URL。自动化也可以直接保存 token：
 
 ```bash
 nolo login --server https://nolo.chat --token <token>
 ```
 
-Local repo development should use `nolo login` or an explicit `AUTH_TOKEN` for
-agent runs.
+本地仓库开发应使用 `nolo login` 或显式 `AUTH_TOKEN` 来运行 agent。
 
-Inside the TUI, `/update` is the shortcut for the same global `nolo update`
-command.
+在 TUI 内部，`/update` 是全局 `nolo update` 命令的快捷方式。
 
 ```bash
 nolo --help
@@ -117,65 +98,55 @@ nolo agent smoke-current agent-user-1-agent-1 --msg "ping"
 nolo chat --agent agent-pub-01APPBUILDER00000001YAII3I --msg "你好"
 ```
 
-For document creation, prefer the CLI over direct scripts. Use `nolo doc create`
-for ordinary pages and `nolo skill-doc create` for skill-backed pages. Both
-support `--sync`, `--dry-run`, `--json`, and `--allow-secrets`, and both write
-for the current auth token user rather than a demo bootstrap user.
+创建文档时，优先使用 CLI 而非直接脚本。普通页面使用 `nolo doc create`，技能驱动的页面使用 `nolo skill-doc create`。两者都支持 `--sync`、`--dry-run`、`--json` 和 `--allow-secrets`，并且都使用当前认证 token 的用户身份写入，而非 demo 引导用户。
 
-Experimental machine connector commands:
+实验性机器连接器命令：
 
 ```bash
-nolo connect          # send one machine heartbeat
-nolo connect --watch  # keep this terminal process online with periodic heartbeats
-nolo connect --ws     # keep a live connector websocket for bound agent runs
-nolo connect --daemon # start connect --ws silently in the background
+nolo connect          # 发送一次机器心跳
+nolo connect --watch  # 通过周期性心跳保持此终端进程在线
+nolo connect --ws     # 为绑定的 agent 运行保持实时连接器 websocket
+nolo connect --daemon # 在后台静默启动 connect --ws
 nolo daemon --server-url https://api.nolo.chat --machine-key sk_machine_xxx
-nolo machine status   # list machines registered to the current profile
+nolo machine status   # 列出注册到当前配置文件的机器
 ```
 
-These commands only register machine presence and runtime capabilities today.
-They do not expose shell, file-write, or raw local LLM endpoints.
+目前这些命令仅注册机器存在性和运行时能力。它们不会暴露 shell、文件写入或原始本地 LLM 端点。
 
-Run a Slock-style connector command:
+运行 Slock 风格的连接器命令：
 
 ```bash
 nolo daemon --server-url https://api.nolo.chat --machine-key sk_machine_xxx
 ```
 
-Future published package shape:
+未来发布的包形态：
 
 ```bash
 npx @nolo/daemon@latest --server-url https://api.nolo.chat --machine-key sk_machine_xxx
 ```
 
-The daemon registers this computer, reports local CLI capabilities, keeps a live
-websocket open, and executes bound CLI agents on this computer. Agents bind to a
-machine, not to a workspace or project folder.
+daemon 注册本台计算机、报告本地 CLI 能力、保持实时 websocket 连接，并在此计算机上执行绑定的 CLI agents。Agent 绑定到机器，而非工作空间或项目文件夹。
 
-Bind an agent to the current machine:
+将 agent 绑定到当前机器：
 
 ```bash
 nolo agent bind-current <agentKey>
 ```
 
-The agent keeps its own CLI settings. The binding only records which connected
-machine must be online when that agent runs.
+Agent 保持自己的 CLI 设置。绑定仅记录哪个已连接的机器在该 agent 运行时必须在线。
 
-Run a one-command connector smoke test:
+运行单命令连接器冒烟测试：
 
 ```bash
 nolo agent runtime-doctor <agentKey>
 nolo agent smoke-current <agentKey> --msg "ping"
 ```
 
-`runtime-doctor` checks whether the agent is a CLI agent and whether the current
-machine has the required CLI capability. `smoke-current` heartbeats the current
-machine, binds the agent to it, opens a temporary connector websocket, calls
-`/api/agent/run`, and prints the returned dialog id/content.
+`runtime-doctor` 检查该 agent 是否为 CLI agent 以及当前机器是否具有所需的 CLI 能力。`smoke-current` 向当前机器发送心跳，将 agent 绑定到该机器，打开临时的连接器 websocket，调用 `/api/agent/run`，并打印返回的 dialog id/content。
 
-## Product Shape
+## 产品形态
 
-The preferred command model is Agent-first:
+推荐的命令模型是 Agent 优先：
 
 ```bash
 nolo agent list
@@ -190,60 +161,38 @@ nolo dialog list --space <space>
 nolo dialog read <dialog>
 nolo dialog delete <dialog...> --yes
 nolo doc list --agent <agent>
-nolo table query --table meta-0e95801d90-NOLOTASKBOARD --limit 20
-nolo table query --table meta-0e95801d90-NOLOTASKBOARD --columns '["title","status","owner","priority","codeStatus"]' --no-base-fields --output items
-nolo table update-row --table meta-0e95801d90-NOLOTASKBOARD --row 01ROWID --changes '{"status":"已完成"}'
-nolo table add-column --table meta-0e95801d90-NOLOTASKBOARD --schema-write-ok --name "blockedBy" --label "Blocked By"
+nolo table query --table meta-0e95801d90-01KWSK4Q4TESXQ06SW39JN2TTJ --limit 20
+nolo table query --table meta-0e95801d90-01KWSK4Q4TESXQ06SW39JN2TTJ --columns '["title","status","owner","priority","codeStatus"]' --no-base-fields --output items
+nolo table update-row --table meta-0e95801d90-01KWSK4Q4TESXQ06SW39JN2TTJ --row 01ROWID --changes '{"status":"已完成"}'
+nolo table add-column --table meta-0e95801d90-01KWSK4Q4TESXQ06SW39JN2TTJ --schema-write-ok --name "blockedBy" --label "Blocked By"
 ```
 
-`agent list` and `dialog list` use global server candidates for the current CLI
-profile: the selected `--server` / `NOLO_SERVER` plus known Nolo cluster peers.
-List commands merge tombstones so a newer delete on one server hides older live
-records from another.
-
-Delete commands fan out wider by default: the selected server, cluster peers,
-`READ_DIALOG_BASE`, and the local dev API origin. That means `nolo dialog delete`
-and script helpers such as `deleteRecord()` / `deleteAgentRecords()` delete on
-`nolo.chat`, `us.nolo.chat`, and local dev when present—not just the current
-`BASE_URL`. Dialog, doc, skill-doc, space, and agent public-record deletes all
-use this multi-server path; each server applies the normal tombstone/cascade
-behavior for that record type.
-
-`nolo table add-column` mutates table schema metadata, so it requires
-`--schema-write-ok` and should be run serially per table. Row-level table writes
-do not require this flag.
-
-For agent config inspection and small config mutations, prefer the CLI-native
-commands instead of ad hoc scripts:
-
-- `nolo agent list` is CLI-native and prefers the local cache, then degrades to
-  remote query when the local LevelDB cache is unavailable or locked.
-- `nolo agent read <agent>` reads local cached agent records first, then falls
-  back to remote fetch + local cache refresh across known server candidates.
-- if the local LevelDB cache is unavailable or locked, `nolo agent read`
-  degrades to remote-only lookup instead of hard-failing on the local DB.
-- `nolo agent update <agent> ...` is CLI-native and supports small targeted
-  updates such as `--model`, `--cli-provider`, `--api-source`, and repeated
-  `--field key=value`.
-
-Account ownership matters for private agent maintenance. Default new tests,
-validation dialogs, task-board writes, machine-bound agent runs, and
-user-visible results should write to the current operator account
-`0e95801d90`. The legacy
-`b2e06f801f` / platform-demo account still owns older public/shared records, but
-it is being retired as the default write target. Use `nolo agent read`,
-`nolo agent update`, and repo-native helpers as the normal entrypoints; only
-owner-only operations that explicitly target legacy records should use the
-maintained platform-demo token from `scripts/testUtils.ts` or a regenerated
-token from `scripts/generateToken.ts`. Do not copy token strings into docs,
-logs, or prompts.
-
-Inside the current TUI, examples of supported slash commands include:
-`/agent`, `/agents`, `/switch`, `/context` (alias `/ctx`), `/dialog`, `/doc`,
-`/help`, `/new`, `/customize`, `/login`, `/profile`, `/version`, `/quit`
-(alias `/exit`), and `/update` (which maps to `nolo update`).
-
-Future product-direction examples for the broader TUI command model:
+`agent list` 和 `dialog list` 使用当前 CLI 配置文件的全局服务器候选列表：选定的 `--server` / `NOLO_SERVER` 加上已知的 Nolo 集群对等节点。列表命令会合并墓碑记录，因此一个服务器上较新的删除会隐藏来自另一个服务器的较旧活动记录。
+
+删除命令默认扩散范围更大：选定的服务器、集群对等节点、`READ_DIALOG_BASE` 以及本地开发 API 源。这意味着 `nolo dialog delete` 和脚本助手如 `deleteRecord()` / `deleteAgentRecords()` 会在 `nolo.chat`、`us.nolo.chat` 和本地开发环境（如果存在）上执行删除——而不仅仅是当前的 `BASE_URL`。Dialog、doc、skill-doc、space 和 agent 公共记录的删除都使用此多服务器路径；每个服务器对该记录类型应用通常的墓碑/级联行为。
+
+`nolo table add-column` 会改变表 schema 元数据，因此需要 `--schema-write-ok` 并且应当对每个表串行执行。行级表写入不需要此标志。
+
+对于 agent 配置检查和小的配置变更，优先使用 CLI 原生命令而非临时脚本：
+
+- `nolo agent list` 是 CLI 原生命令，优先使用本地缓存，当本地 LevelDB 缓存不可用或被锁定时降级为远程查询。
+- `nolo agent read <agent>` 首先读取本地缓存的 agent 记录，然后回退到跨已知服务器候选的远程获取 + 本地缓存刷新。
+- 如果本地 LevelDB 缓存不可用或被锁定，`nolo agent read` 会降级为纯远程查找，而不会在本地数据库上硬失败。
+- `nolo agent update <agent> ...` 是 CLI 原生命令，支持小的定向更新，如 `--model`、`--cli-provider`、`--api-source` 和重复的 `--field key=value`。
+- `nolo agent create <slug> --name <display> [--prompt <text>] [--copy-provider-from <agent>]` 创建私有 agent 记录（需已登录）。
+- `nolo agent email provision <agent> [--purpose <label>] [--local-part pay]` 调用 `/rpc/provisionAgentEmailIdentity` 开通受控收件箱（如 `pay@nolo.chat`）。
+- `nolo agent email bind <agent> --email <address>` 将已有地址绑定到 agent。
+- `nolo agent email create-and-provision <slug> --name <display> [--local-part pay] [--copy-provider-from <agent>]` 一步创建 agent 并开通邮箱。
+- `nolo auth cloudflare [--client-id <id>] [--generate-token] [--zone-name <domain>] [--write-to-env [path]]` 通过 Cloudflare 自托管 OAuth 授权并可选生成 `Zone:Email Routing:Edit` 的 API Token，还可直接写入 `.env`。
+
+账户所有权对私有 agent 维护很重要。默认的新测试、验证 dialogs、任务板写入、机器绑定的 agent 运行和用户可见的结果应写入当前操作员账户 `0e95801d90`。原有的 `b2e06f801f` / platform-demo 账户仍然拥有较旧的公共/共享记录，但正在作为默认写入目标退出使用。使用 `nolo agent read`、`nolo agent update` 和仓库原生助手作为正常入口点；只有明确针对旧记录的所有者专属操作才应使用维护的 platform-demo token（来自 `scripts/testUtils.ts`）或重新生成的 token（来自 `scripts/generateToken.ts`）。不要将 token 字符串复制到文档、日志或提示词中。
+
+在当前 TUI 中，支持的斜杠命令示例包括：
+`/agent`、`/agents`、`/switch`、`/context`（别名 `/ctx`）、`/dialog`、`/doc`、
+`/help`、`/new`、`/customize`、`/login`、`/profile`、`/version`、`/quit`
+（别名 `/exit`）和 `/update`（映射到 `nolo update`）。
+
+更广泛的 TUI 命令模型的未来产品方向示例：
 
 ```text
 /agent list
@@ -253,28 +202,22 @@ Future product-direction examples for the broader TUI command model:
 /table query builtin-dialog-probe-runs
 ```
 
-See [`docs/nolo-cli-tui.md`](../../docs/nolo-cli-tui.md) for the product and
-technical direction.
+参见 [`docs/nolo-cli-tui.md`](../../docs/nolo-cli-tui.md) 了解产品和技术方向。
 
-## Building for Publish
+## 构建与发布
 
-The CLI is developed in a monorepo with workspace dependencies (`ai` and
-`connector-experimental`). To generate a publish-safe package that can be
-installed via npm outside the monorepo:
+CLI 在包含工作空间依赖（`ai` 和 `connector-experimental`）的单仓库中开发。要生成可在单仓库外通过 npm 安装的发布安全包：
 
 ```bash
 bun run build:publish
 ```
 
-This creates a `dist/` directory with:
-- A single bundled `index.js` (esbuild, `platform: node`, ESM) with a
-  `#!/usr/bin/env node` shebang, runnable on plain Node.js without Bun
-- Workspace dependencies inlined into the bundle
-- A modified package.json with workspace dependencies stripped, `bin.nolo`
-  pointing at `index.js`, and only `index.js` + `README.md` in `files`
+这将创建一个 `dist/` 目录，包含：
+- 一个单一的 bundle `index.js`（esbuild、`platform: node`、ESM），带有 `#!/usr/bin/env node` shebang，可在纯 Node.js 上运行，无需 Bun
+- 工作空间依赖内联到 bundle 中
+- 修改后的 package.json，去除了工作空间依赖，`bin.nolo` 指向 `index.js`，`files` 中仅包含 `index.js` + `README.md`
 
-The `dist/` directory is the publish-safe artifact consumed by the CI npm
-publish workflow:
+`dist/` 目录是 CI npm 发布工作流使用的发布安全产物：
 
 ```bash
 bun ./scripts/release/prepareCliPublishPackage.ts --out-dir .tmp/nolo-cli-publish
@@ -282,18 +225,44 @@ cd .tmp/nolo-cli-publish
 npm pack
 ```
 
-For this repository, the default release path for `nolo-cli` is the GitHub
-Actions workflow [`.github/workflows/cli-npm-publish.yml`](../../.github/workflows/cli-npm-publish.yml).
-Use local `npm pack` or tarball-based `npm install -g` as preflight verification.
-Do not treat manual local `npm publish` as the normal release route unless you
-are intentionally debugging the CI publish lane.
-
-Key differences between repo-local and published versions:
-- **Repo-local**: Runs from source (`packages/cli/index.ts`) under Bun
-  (`bun ./packages/cli/index.ts`, `bun test`) with workspace dependencies
-  resolved by the monorepo
-- **Published**: Runs from the bundled `dist/index.js` under plain Node.js with
-  workspace dependencies inlined and npm packages declared as `dependencies`
-
-Repo-local development still uses Bun (`bun test`, `bun ./packages/cli/index.ts`);
-only the shipped/published runtime is Bun-free.
+对于本仓库，`nolo-cli` 的默认发布路径是 GitHub Actions 工作流 [`.github/workflows/cli-npm-publish.yml`](../../.github/workflows/cli-npm-publish.yml)。使用本地 `npm pack` 或基于 tarball 的 `npm install -g` 作为预检验证。除非你正在有意调试 CI 发布通道，否则不要将手动本地 `npm publish` 视为正常发布途径。
+
+仓库本地版本与发布版本的关键区别：
+- **仓库本地**：在 Bun 下从源码运行（`packages/cli/index.ts`）（`bun ./packages/cli/index.ts`、`bun test`），工作空间依赖由 monorepo 解析
+- **发布版本**：在纯 Node.js 下从 bundle `dist/index.js` 运行，工作空间依赖内联，npm 包声明为 `dependencies`
+
+仓库本地开发仍使用 Bun（`bun test`、`bun ./packages/cli/index.ts`）；只有发布的运行时不依赖 Bun。
+
+## 原生二进制包
+
+`nolo-cli` 现在支持按平台分发的原生二进制包，以提供更快的启动速度和独立的可执行文件（无需用户本地安装 Bun）。模式与 oh-my-pi 的 `pi-natives` 类似：
+
+- `nolo-cli` 作为入口包，包含一个 Node.js 兼容的 `index.js` 引导脚本
+- `nolo-cli-darwin-arm64` 等子包包含对应平台的预编译二进制
+- 安装时 npm/bun 只会安装匹配当前平台与架构的可选依赖
+- 引导脚本优先调用原生二进制；缺失时回退到 `bun index.ts`
+
+当前支持的平台：
+
+| 平台 | 包名 |
+|---|---|
+| macOS Apple Silicon | `nolo-cli-darwin-arm64` |
+
+构建当前平台的原生包：
+
+```bash
+bun run packages/cli-darwin-arm64/build.ts
+```
+
+这会在 `packages/cli-darwin-arm64/nolo` 生成一个 Bun `--compile` 独立可执行文件。发布原生包时使用：
+
+```bash
+bun ./scripts/release/prepareCliNativePackage.ts --out-dir .tmp/nolo-cli-native
+npm publish .tmp/nolo-cli-native/nolo-cli-darwin-arm64
+```
+
+本地开发时，若已生成本地原生二进制，`nolo` 会通过引导脚本自动使用它。若希望强制走源码（例如正在修改 TS 源码），设置环境变量：
+
+```bash
+NOLO_CLI_SOURCE=1 nolo doctor
+```