newidea-cli

Newidea AI 平台的命令行工具，面向人类用户和 Agent 使用。

安装

要求 Node.js 20 或更高版本。

npm install -g @helixlife-ai/newidea

安装后，全局命令 newidea 即可使用。

登录授权

newidea login

执行后 CLI 会通过仙桃授权接口获取 token_key 和授权链接，把 token 保存到与 xiantao-cli 共用的 ~/.config/helixlife/user-access-token.txt，并打开浏览器授权页面。授权完成后，CLI 轮询仙桃 check-token 接口确认授权状态；确认通过即完成登录，没有单独的 CLI session 需要激活。此后所有业务请求都直接携带 Authorization: Bearer <token_key>。普通文本模式会等待授权确认完成；JSON 模式默认立即返回授权链接，可显式使用 --wait 等待确认。

无浏览器环境可使用 newidea login --no-open --json 获取 link_url 后手动打开。

Agent 与凭证隔离：授权链接会追加 source=<agent>。可通过 --profile <name> 显式指定；否则依次读取 AGENT_NAME、识别 Cursor/OpenCode/OpenClaw 环境，最后默认使用 opencode。仙桃 token 与 xiantao-cli 共享、不按 profile 隔离；只有本地缓存和异步执行历史按 profile 隔离。

newidea login --profile cursor
newidea invocation start ... --profile cursor

授权失效时（newidea status 检测到，或业务接口返回未授权），需重新运行 newidea login 完成授权：

您的授权已过期或无效，请重新完成授权。

支持的命令

登录与状态

| 命令 | 说明 | |------|------| | newidea login | 获取并授权共享 token，等待仙桃授权确认 | | newidea logout | 退出登录，删除本地共享 token | | newidea status | 校验共享 token 是否有效 |

Skill

| 命令 | 说明 | |------|------| | newidea skill list --page 1 --limit 20 | 按角色、分类与关键词分页查询 Skill | | newidea skill list --role_id <uuid> --category_id <uuid> --keyword "搜索词" | 筛选 Skill | | newidea skill list --new | 只列出最新 Skill（也可使用 --latest） | | newidea skill role | 查询角色、分类及去重 Skill 数 | | newidea skill count | 查询未软删除 Skill 总数及热门 Skill UUID | | newidea skill download <skill-id> | 使用 skill list 或 skill count 返回的 Skill UUID 获取签名下载链接 | | newidea skill downloads --skill-id <uuid> --skill-id <uuid> | 批量去重计数后下载 Skill zip 包 | | newidea skill downloads --skill-id <uuid> -o ./skills.zip | 指定批量下载 zip 输出路径 |

机制图

| 命令 | 说明 | |------|------| | newidea diagram generate --prompt "..." | 调用机制图生成接口 | | newidea diagram generate --prompt "..." --mode technology-roadmap | 生成技术路线图 | | newidea diagram refine --prompt "..." --input-url "..." | 基于原图再优化 | | newidea diagram quota | 查询月度额度 | | newidea diagram generate --prompt "..." -o ./diagram.png | 下载生成结果到本地 |

机制图命令默认使用共用的仙桃 token（Authorization: Bearer <token_key>）请求机制图服务。NEWIDEA_DIAGRAM_TOKEN 仅用于调试或临时覆盖。

机制图一次只能生成一张。每次 diagram generate 只产出单张图；若需要多张，请按顺序逐张生成。

异步执行

| 命令 | 说明 | |------|------| | newidea invocation tools --page 1 --size 100 | 分页列出可用于 invocation 的 tools | | newidea invocation start <tool-id> --input "你好" | 开始异步执行任务，返回 session_id 和 run_record_id | | newidea invocation start <tool-id> --input "继续" --session-id <session-id> --parent-record-id <run-record-id> | 复用已有会话并基于父级执行记录继续对话 | | newidea invocation start --input "继续" --continue-last | 使用最近一次本地异步执行记录继续对话，失败记录会回退到上一个成功父节点 | | newidea invocation start --input "继续" --continue-from <run-record-id> | 使用指定本地异步执行记录继续对话，失败记录会回退到上一个成功父节点 | | newidea invocation process <run-record-id> | 查询执行进度、最终状态和产物链接 | | newidea invocation progress <run-record-id> | invocation process 的别名 | | newidea invocation list | 查看本地保存的异步执行记录 | | newidea invocation last | 查看最近一次异步执行记录 |

多轮对话通过 invocation start 的 --session-id / --parent-record-id 或 --continue-last / --continue-from 实现：CLI 会把上一轮成功执行的 run_record_id 作为下一轮的 parent_record_id。每轮执行失败时不会推进父记录，因此下一条消息仍会从上一个成功节点继续。

配置管理

| 命令 | 说明 | |------|------| | newidea config set <key> <value> | 设置配置项，持久化到 ~/.config/newidea/config.json | | newidea config get <key> | 获取配置项的解析值（优先级：环境变量 > 配置文件 > 默认值） |

支持的配置项：base-url、api-url、completion-url、diagram-api-url、auth-api-url、agent-url。

历史记录

| 命令 | 说明 | |------|------| | newidea history list | 获取历史执行记录（后端 API 暂不支持） | | newidea history list --starred | 只显示收藏的记录（后端 API 暂不支持） |

JSON 输出模式

所有命令都支持 --json 标志，输出结构化 JSON，便于 Agent 解析：

newidea invocation tools --json
newidea skill list --json
newidea invocation start <tool-id> --input "你好" --json

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | NEWIDEA_BASE_URL | 用户中心基础地址 | https://uc.newidea.pro | | NEWIDEA_API_URL | API 前缀 | https://uc.newidea.pro/api/v1 | | NEWIDEA_AGENT_URL | 异步调用 API 前缀 | https://agent-service.newidea.pro/api/v1 | | NEWIDEA_DIAGRAM_API_URL | 机制图 API 前缀 | https://image-vip.jova.ai/api/v1 | | NEWIDEA_COMPLETION_URL | 文本生成 API 前缀 | https://completion.newidea.pro/api | | NEWIDEA_DIAGRAM_TOKEN | 机制图 API 调试覆盖令牌（可选） | - | | HELIXLIFE_AUTH_API_URL | 仙桃授权 API 前缀 | https://agent.helixlife.cn/api/v1 | | AGENT_NAME | 授权链接的默认 source 标识 | 自动识别，最终回退 opencode | | NEWIDEA_PROFILE | Profile 名称（内部使用，由 --profile flag 自动设置） | - |

开发

npm install
npm run dev -- <command>
# 例如
npm run dev -- invocation tools --json
npm test