HelixWiki CLI (hw)

HelixWiki 的命令行工具：在终端登录后浏览知识库、检索文档、查看节点内容，并使用 AI 生成深度研究报告。

功能概览

| 能力 | 命令 | 说明 | | --- | --- | --- | | 授权登录 | hw login | 打开浏览器完成授权登录，并等待授权完成 | | 登录状态 | hw status | 查看当前登录状态 | | 退出登录 | hw logout | 删除本地保存的登录凭证 | | 知识库列表 | hw list | 列出可访问的知识库 | | 文档树 | hw tree | 查看知识库中的文档目录 | | 语义检索 | hw search | 根据问题查找相关文档节点 | | AI 深度搜索 | hw research | 根据问题生成综合研究报告 | | 节点详情 | hw detail | 查看文档节点的详细内容 | | 思维导图 | hw mindmap | 查看文档节点的思维导图 |

安装

需要 Node.js 22 或更高版本。

npm install -g @helixlife-ai/helixwiki-cli
hw --help

配置

环境变量

CLI 默认连接正式服务，安装后可以直接使用。需要连接其他服务时，可以通过环境变量覆盖默认地址，或在当前目录创建 .env 文件。已经在终端中设置的环境变量优先级更高。

| 变量 | 说明 | | --- | --- | | HELIXWIKI_BASE_URL | Wiki 服务地址 | | HELIXWIKI_AUTH_URL | 登录认证服务地址 |

连接其他环境时，可以在当前目录创建 .env：

HELIXWIKI_BASE_URL=https://your-wiki-host
HELIXWIKI_AUTH_URL=https://your-auth-host

常用参数

| 参数 | 说明 | | --- | --- | | --json | 输出 JSON，便于脚本处理 |

快速开始

# 1. 登录（默认打开浏览器并等待授权完成）
hw login

# 2. 确认状态
hw status

# 3. 列出知识库
hw list

# 4. 查看某知识库的文档树（knowledge_token 来自 hw list）
hw tree <knowledge_token>

# 5. 查找相关文档
hw search "如何配置知识库权限"

# 6. 使用检索结果中的 node_token 查看节点
hw detail <node_token>
hw mindmap <node_token>

# 7. 生成 AI 深度研究报告
hw research "基础研究"

命令说明与示例

hw login

打开授权链接完成登录，并等待授权完成。

hw login
hw login --no-open          # 不自动打开浏览器，仅输出授权链接
hw login --no-wait          # 不等待授权结果，完成网页授权后再执行 hw status
hw login --json             # 输出 JSON

默认行为：

• --open（默认开启）：自动打开授权链接
• --wait（默认开启；--json 时默认关闭）：等待授权成功或超时（约 2 分钟）

文本输出示例（授权完成）：

authorized: true

hw status / hw logout

hw status
hw logout

status 会检查当前登录是否有效。文本输出示例：

authorized: true

未授权时可能附带：

reason: missing_token    # 本地无登录凭证
reason: expired_token    # 登录凭证已失效
run: hw login

hw list

分页列出知识库；默认每页 20 条。

hw list
hw list --page 2
hw list -p 2 --json

文本模式首行为分页摘要，例如：

共 133 个知识库 (第 1 页，每页 20 个)，还有更多...
<knowledge_token>    <知识库名称>

hw tree <knowledge_token>

hw tree 7b0ec7b6-a5fc-4f03-997b-44c1a2c00ef9
hw tree <knowledge_token> --json

输出为缩进树形文本，节点行包含标题、类型（若有）和 node_token。

hw search <query>

hw search "报销流程是什么"
hw search "API 鉴权" --json

文本模式每行：knowledge_name、url、node_token（制表符分隔）。

hw research <query>

hw research "基础研究"
hw research "基础研究" --link
hw research "CRISPR 基因编辑机制" --json

文本模式输出报告元信息及由 HELIXWIKI_BASE_URL/report/?id=<id> 生成的 Web 报告链接，并按“结果摘要、机制层级图、知识脉络图谱、参考来源”分段展示完整报告。--link 只输出 Web 报告 URL，适合在脚本或管道中使用；--json 返回完整结构化结果（含 pathway、graph、reference 等字段，若服务端返回）。--link 与 --json 不能同时使用。

hw detail <node_token> / hw mindmap <node_token>

hw detail <node_token>
hw mindmap <node_token> > mindmap.md

mindmap 将节点思维导图以 Markdown 打印到标准输出，可重定向保存。

hw commands

列出所有已注册子命令及简短说明。

hw commands
hw commands --json

典型工作流

flowchart LR
  login[hw login] --> status[hw status]
  status --> list[hw list]
  status --> search[hw search query]
  status --> research[hw research query]
  list --> tree[hw tree knowledge_token]
  search --> node[node_token]
  tree --> node
  node --> detail[hw detail node_token]
  node --> mindmap[hw mindmap node_token]
  research --> report[研究报告或报告链接]

1. 浏览知识库：执行 hw list，再使用返回的 knowledge_token 执行 hw tree <knowledge_token>。
2. 查找文档节点：执行 hw search "问题描述"，使用返回的 node_token 执行 hw detail <node_token> 或 hw mindmap <node_token>。
3. 生成研究报告：直接执行 hw research "问题描述"；如果只需要报告链接，使用 hw research "问题描述" --link。

常见问题

hw list 报「Token 非法」或授权相关错误

1. 执行 hw status 检查登录状态。
2. 如果未授权，重新执行 hw login。
3. 如果配置过 HELIXWIKI_BASE_URL，确认它指向 Wiki 服务地址。

hw list 报「无法解析的响应」且正文像 HTML
多半是 HELIXWIKI_BASE_URL 指到了前端页面而非 Wiki 服务地址。检查当前目录下的 .env 或终端中的环境变量。

hw login --no-wait 后 hw status 显示未授权
属正常现象：浏览器授权尚未完成。在浏览器打开登录时输出的 link_url 完成绑定后，再执行 hw status 或重新 hw login。

项目目录里找不到登录凭证文件

登录凭证会保存在用户目录 ~/.config/helixwiki-cli/，不会出现在项目目录中。