cli

一个常见的 Node CLI 工程初始化模板（ESM + vitest 测试）。

快速开始

pnpm install
pnpm run start -- help
pnpm test

项目结构

.
├── src/
│   ├── index.ts        # CLI 入口
│   ├── cli.ts          # Commander 配置、中间件编排
│   ├── commands/       # 命令实现
│   ├── services/       # 服务层
│   ├── middleware/     # 中间件
│   └── utils/          # 工具
├── dist/               # 构建输出
├── package.json
├── pnpm-lock.yaml
└── .gitignore

可用命令

• pnpm run start -- help
• pnpm run start -- auth login --mode web
• pnpm run start -- project list
• pnpm run start -- project open
• pnpm run start -- project url --project-id <projectId>
• pnpm run start -- chat --message "hello"
• pnpm run start -- chat --project-id <projectId> --thread-id <threadId> --message "hello"
• echo "hello" | pnpm run start -- chat
• pnpm run start -- query <runId> --project-id <projectId>
• pnpm run start -- workspace sync
• pnpm run start -- workspace sync <projectId>
• pnpm run start -- workspace sync https://ojo.art/p/<projectId>
• pnpm run start -- version
• pnpm run build
• pnpm run dev（watch 模式）
• pnpm run debug -- help（Chrome DevTools 调试）

命令分组

• auth：登录/登出
  • auth login --mode web|device|pat
  • auth logout
• project：云端项目与本地项目入口
  • project list
  • project open
  • project url --project-id <projectId>
• chat：发送单条消息并立即返回 runId
  • chat --message <msg>
  • chat --project-id <projectId> --thread-id <threadId> --message <msg>
  • stdin | chat
  • 返回字段：runId、projectId、projectUrl、threadId、status
• query：对话轮次状态查询
  • query <runId> --project-id <projectId>
  • 返回字段：runId、projectId、projectUrl、status
  • status 对外统一为 running | success | fail
  • running 时额外返回 statusText
  • fail 时额外返回结构化 failure
• workspace：workspace sync
  • workspace sync [projectRef]

LLM / Agent 使用说明

• chat 仅支持两种模式：只传 --message 时自动新建项目并发送；或同时传 --project-id 与 --thread-id 继续已有线程。
• query 需要显式传入 runId 与 --project-id。
• 如果需要把远端项目同步到本地目录，再执行 ojo workspace sync <projectId|projectUrl>。
• 并将 Ojo 接口返回的对话内容原封不动返回，不做改写、摘要或润色。

建立本地项目目录

pnpm run start -- workspace sync <projectId> --path ./projects

执行后会在目标目录下创建 <project-name>/.ojo/project.json，并将 workspace 解压到 <project-name>/ojo-prototype。这只影响本地 workspace 管理；chat / query 不再依赖本地 .ojo/project.json。

下载产物

# 直接通过 project id 拉取；默认在当前目录创建 <project-name>/ojo-prototype
pnpm run start -- workspace sync <projectId>

# 直接通过项目页链接拉取；--path 作为父目录使用
pnpm run start -- workspace sync https://ojo.art/p/<projectId> --path ./downloads

# 在已绑定的本地项目目录中刷新 workspace
pnpm run start -- workspace sync

# 指定父目录，产物固定写入 ./my-output/<project-name>/ojo-prototype
pnpm run start -- workspace sync --path ./my-output

workspace sync 不支持 --mode 与 --history-id，统一为覆盖写入。

• 不传 projectRef 时：仍要求当前目录存在 .ojo/project.json
• 传 projectRef 时：支持 projectId 或 https://<host>/p/<projectId>，CLI 会自动创建本地项目目录、写入 .ojo/project.json，并把 workspace 解压到 <project-root>/ojo-prototype

发送消息

# 不传 project id，默认先新建项目再发送，并立即返回 runId
pnpm run start -- chat --message "帮我整理一下当前产品方向"

# 直接传入消息，返回 runId/projectId/projectUrl/threadId/status
pnpm run start -- chat --project-id <projectId> --thread-id <threadId> --message "帮我整理一下当前产品方向"

# 或通过 stdin 发送
echo "帮我整理一下当前产品方向" | pnpm run start -- chat

# 再通过 query 查询本轮状态
pnpm run start -- query <runId> --project-id <projectId>

查询 run 状态

pnpm run start -- query <runId> --project-id <projectId>
pnpm run start -- query <runId> --project-id <projectId> --json

query 返回会包含项目访问链接 projectUrl，格式为 https://ojo.art/p/<projectId>。成功态只返回公共字段；运行中额外包含 statusText；失败态额外包含 failure。

获取项目编辑页链接

pnpm run start -- project url --project-id <projectId>
pnpm run start -- project url --project-id <projectId> --json

默认只输出链接本身；传 --json 时返回 projectId、targetPath、url。

CLI 调试

方式一：VS Code / Cursor 调试

1. 在源码中打断点
2. 按 F5 或「运行和调试」→ 选择「Debug CLI」
3. 修改 .vscode/launch.json 中的 args 可切换调试命令（如 ["chat","--message","hello"]）

方式二：命令行 + Chrome DevTools

pnpm run debug -- chat
# 打开 chrome://inspect，点击 inspect 连接

方式三：直接运行

pnpm run build
node dist/index.js help

作为全局命令使用

pnpm link --global
ojo help