Qiongli 2 CLI：安装与直接下载

本文对应从 main 构建的原生 CLI 首个正式版 2.0.0。与 Python 版本的区别及迁移步骤，见 1.x / 2.0 对比指南。

Qiongli 2 以原生 CLI 为入口，不需要打开或安装 Qiongli App。同一版本、同一平台的 GitHub 二进制包、npm 和 PyPI 包使用相同的原生可执行文件。

安装与命令指南

在终端中运行 qiongli install 或 qiongli upgrade 即可打开向导。 qiongli install plugin 同时负责安装和更新，upgrade plugin、update plugin 使用相同流程。向导选择 Host，并复用它已经登记的源目录。也可以加 --target codex、--target claude 或 --target all。all 对两个 Host 分别确认，取消或失败就停止后续步骤；新源目录必须各自独立，且父目录已经存在。单个 Host 仍可指定 --destination。脚本保留参数明确的 --dry-run 预览，重定向输出时的裸 install 仍返回只读清单。

Plugin 源文件不需要放进 ~/.agents/skills。完成官方注册后，Host 会从自己的 Plugin 缓存中加载 Skills 和 MCP。如果已启用另一个 Qiongli Plugin，新流程会在导出前列出它的名称。Qiongli 2.0 支持在确认后，将 qiongli-next@personal 等穷理旧插件迁移到 CLI 随包 Plugin。Host 确认页会列出需要停用的具体插件；Codex 官方配置接口会校验配置版本，只修改这些插件的启用状态，保留旧来源、缓存及其他设置。取消 Host 确认时，旧插件保持启用。如果停用后新版注册失败，可以重试安装，或在 Codex 中重新启用旧插件。配置接口不受支持或插件不属于用户配置时，需要手动核对；Claude 保留手动停用步骤。仅导出成功，不能算安装完成。

用 qiongli doctor 和 qiongli install list 检查注册，再开新会话验证实际工具。独立 Skills 仍导出到 .qiongli-skills，不会接入 Host；需要自动注册时选 Plugin。

在终端中直接运行 config backend、project graph、project capture、 project portfolio 或 app plan，会显示该命令组的用法。脚本保留原有错误码；项目写入仍需明确的预览和批准参数。

从安装到首次使用

在终端运行 qiongli install（仍支持 --interactive）。先选择 Plugin，再选择 Codex 或 Claude。默认导出目录是用户主目录下的 qiongli-next，可填写其他绝对路径；父目录必须已存在。升级时自动复用已登记且通过核验的源目录，第二个 Host 使用单独的目录。选择菜单不会写文件，后续仍需分别确认文件计划和 Host 注册。只需要指导文件时选 Skills；已有接入时可查看 MCP 配置。

入口	内容与接入
CLI 包	原生程序，包含研究资源与 MCP 实现；不会自动配置 Host
CLI 安装的 Plugin	Skills + 原生程序 + Full MCP 配置，32 个工具
原生 Marketplace 平台 Plugin	Skills + 原生程序 + Lite MCP 配置，14 个工具
独立 Skills	导出指导和参考资料，不提供运行中的 MCP，也不自动注册 Host

MCP 已编译进 qiongli，无需另装服务包。Host 根据 Plugin 的配置启动 stdio 子进程，通常不需要另开终端运行 mcp serve。install skills --profile full 中的 full 是内容范围，不代表安装或启动了 Full MCP。用 qiongli install list 查看只读清单；重定向输出时，裸命令 install 也保留原来的清单输出。

安装完成后分三步检查：

查看文件与注册结果。完成摘要会集中列出版本、源目录与缓存位置、已验证的注册状态，以及尚待检查的会话工具和 Hook。取消注册会保留导出文件，可以用原目录重试。
运行 qiongli mcp check（或 --profile lite）：检查当前 CLI 的初始化、工具列表和一次只读调用。它不验证 Plugin 缓存、Host 会话或在线服务。
新开 Host 会话，要求列出实际 Qiongli 工具并调用 qiongli_config_status；文献服务的配置再用 qiongli_literature_status 检查。工具缺失时不能声称已就绪。

然后用一份你提供的材料试运行：阅读并保留来源位置、提出规范研究记录、审阅后保存，再检查 Graph 和阶段总结。保存走原有批准流程，总结不删除原文件。

升级 CLI 后，运行 qiongli doctor 检查 Plugin 是否需要刷新，再执行 qiongli install plugin 选择 Host，或用 --target 指定。Plugin 保存自己的程序副本；版本号相同也需要核对收据和摘要。 CLI 的多版本清理仍由 qiongli setup 提供建议，由用户自行操作。

常用命令

常用操作有简短入口，帮助按操作显示，终端查询提供易读输出。 ql 是 qiongli 的短名称，两者用法相同。

要做什么	简短入口
查看常用命令	`qiongli`
检查本地状态和问题	`qiongli doctor`
审查已安装的 CLI 版本	`qiongli setup`
查看 CLI 安装和 Host	`qiongli install list`
列出研究项目	`qiongli project`
查看一个项目	`qiongli project show <id>`
查看配置	`qiongli config`
查看内置内容配置档	`qiongli content`
以 stdio 接入 Full MCP	`qiongli mcp serve --profile full`

不必在一页中查找所有参数。例如，qiongli help project create 和 qiongli project create --help 都只显示创建项目的用法。 qiongli help all 提供完整命令参考，包括高级安装操作。 qiongli update 查询受管理安装的更新状态；通过 npm、pip 或 Cargo 安装的包，仍使用原包管理器升级。

终端中的查询默认显示易读摘要；重定向时保留原有输出格式。脚本可以明确使用 --json，需要保存易读报告时则使用 --text。格式参数放在命令开头或末尾，只选一个：

qiongli status --json
qiongli doctor --text > qiongli-doctor.txt

setup 借用了 1.x 熟悉的入口名称，在 2.x 中专门用于审查 CLI 安装，不会配置 Host、更换模型或卸载程序。无参数运行改为显示帮助，需要审查版本时再运行 qiongli setup。项目写入仍需预览、批准和修订检查；易读预览完整保留审批所需的参数，程序处理时使用 --json。

独立二进制下载

推荐直接下载：解压后就能运行，不用先安装 Python、Node.js、Rust 或包管理器。 你可以直接在解压目录使用，PATH 配置是可选项。

从 GitHub Release v2.0.0 选择与你的操作系统和 CPU 对应的压缩包：

平台	完整 CLI 二进制包
macOS Apple Silicon / ARM64	qiongli-2.0.0-aarch64-apple-darwin.tar.gz
Windows x64	qiongli-2.0.0-x86_64-pc-windows-msvc.zip
Linux x64 / glibc 2.35+	qiongli-2.0.0-x86_64-unknown-linux-gnu.tar.gz

Windows 2.0 版本已将 C 运行库编入程序，不需要另装 Visual C++ 运行库。 Linux 使用系统自带库，要求 glibc 2.35+。

压缩包内有 qiongli（Windows 为 qiongli.exe）、README.md 和 LICENSE。研究 Skills、模板及 Lite/Full MCP 资源已经嵌入可执行文件，无需额外下载资源目录或克隆仓库。模型 Host 和在线文献服务仍需单独配置。

请在 Release 的 Assets 中选择上述平台包。页面自动生成的 Source code 是需要编译的源码， .tgz 是 npm 包，.whl 是 Python 包，qiongli-next-…-plugin-… 是 Host 插件包。当前版本不提供 Intel Mac、Linux ARM 或 Windows ARM 原生构建。

1. 校验下载文件

下载同一 Release 的 SHA256SUMS。在下载目录中，运行与你的平台对应的命令，将结果与 SHA256SUMS 中该文件名对应的摘要比较；一致后再继续。

# macOS
shasum -a 256 qiongli-2.0.0-aarch64-apple-darwin.tar.gz
# Linux
sha256sum qiongli-2.0.0-x86_64-unknown-linux-gnu.tar.gz

powershell

# Windows
Get-FileHash .\qiongli-2.0.0-x86_64-pc-windows-msvc.zip -Algorithm SHA256

2. 解压后直接运行

使用一个新目录，保留已有安装和研究文件。在 macOS 终端中：

mkdir qiongli-2.0.0-macos-arm64
tar -xzf qiongli-2.0.0-aarch64-apple-darwin.tar.gz -C qiongli-2.0.0-macos-arm64
cd qiongli-2.0.0-macos-arm64
./qiongli --version
./qiongli --help
./qiongli content list

在 Linux 终端中：

mkdir qiongli-2.0.0-linux-x64
tar -xzf qiongli-2.0.0-x86_64-unknown-linux-gnu.tar.gz -C qiongli-2.0.0-linux-x64
cd qiongli-2.0.0-linux-x64
./qiongli --version
./qiongli --help
./qiongli content list

Windows 用户在下载目录打开 PowerShell：

powershell

Expand-Archive -Path .\qiongli-2.0.0-x86_64-pc-windows-msvc.zip -DestinationPath .\qiongli-2.0.0-windows-x64
Set-Location .\qiongli-2.0.0-windows-x64
.\qiongli.exe --version
.\qiongli.exe --help
.\qiongli.exe content list

版本应显示 qiongli 2.0.0。独立包只提供 qiongli 可执行文件；ql 别名由 npm / PyPI / Cargo 安装提供。

3. 可选：加入 PATH

你可以一直使用可执行文件的绝对路径。若希望在任意目录输入 qiongli，将解压目录加入用户 PATH： macOS / Linux 使用自己的 Shell 配置，Windows 使用用户环境变量设置；完成后打开新终端。

macOS / Linux 用 type -a qiongli，PowerShell 用 Get-Command qiongli -All 检查实际运行的路径，再运行 qiongli --version，避免旧版本或包管理器的入口优先于新版本。

升级时将新版本解压到另一个目录，验证后再更新 PATH 或 Host 配置中的路径。保留旧二进制及研究数据以便回退；切换二进制不会撤销数据迁移。

检查和迁移已有 CLI

Qiongli 可以列出本机可见的安装，并提供交互式迁移建议。如果旧版在 PATH 中排在前面，请用新安装程序的完整路径运行下面的命令：

qiongli install inventory --paths exact
qiongli setup

清单会合并同一安装的别名，并区分包元数据版本与当前运行版本。检测范围包括 PATH、常见用户安装目录及已配置的 Cargo、Python、npm 位置；其他环境和 Shell 函数需要单独检查。检测不会执行来源不明的程序。doctor 默认隐藏实际路径，需要时再明确查看完整路径。

向导让你选择准备使用的安装，并逐项查看其他版本的归档或卸载说明。直接按回车会保留现有设置。选择默认版本只生成建议，不会修改 PATH 或 Host 配置，也不会删除、移动或归档任何文件。卸载前要确认文件归属：旧包可能与新版共用启动入口。研究文件、配置和 Plugin 缓存不属于 CLI 清理范围。

无参数运行显示帮助，通过 qiongli setup 打开版本审查向导。如需在 npm 安装过程中显示向导，可以为本次安装授权穷理的脚本，并让脚本连接终端：

npm install -g qiongli@latest --allow-scripts=qiongli --foreground-scripts

新版 npm 会对尚未明确授权的 postinstall 脚本发出警告。警告本身不代表安装失败，也不代表脚本已被阻止；启用严格脚本策略后则可能报错。 --allow-scripts=qiongli 只为本次命令明确授权穷理的脚本，不修改已保存的 npm 配置。 --foreground-scripts 让脚本使用当前终端；输入和输出都连接终端时，向导才会出现。详见 npm 脚本设置。

使用 --ignore-scripts 禁用安装脚本，仍可正常使用 CLI。已经安装成功时，无需重装，直接用新版可执行文件的完整路径运行 setup 即可。 pip 和 Cargo 用户也在安装完成后运行向导。脚本、帮助与版本查询、MCP 启动不会弹出交互提示。

包管理器安装应保留在原位置，并记录版本及原环境以便重装；确认是独立发布包后，才适合另行复制完整备份并校验。归档副本本身不会停用旧命令。

安装和升级随包 Plugin、Skills

可以直接安装并注册随包 Plugin；目标和目录也可交给向导选择。以 Codex 为例：

mkdir -p "$HOME/qiongli-plugins/codex"
qiongli install plugin --target codex \
  --destination "$HOME/qiongli-plugins/codex/qiongli-next"

命令先显示文件变更，确认后导出当前 CLI 的原生二进制、研究 Skills 和 Full MCP。随后单独显示 Host 操作，再次确认后，调用 Codex 官方插件命令完成注册和启用。 Plugin 本身无需 Python、Node 或 Cargo 运行时；Codex 仍需事先安装。 Claude Code 使用 --target claude，并另建一个导出父目录，例如 $HOME/qiongli-plugins/claude。

安装 Plugin 时可以选择可选的上下文提醒。首次默认关闭，更新时保留已有选择。运行 qiongli install plugin --hooks context 可加入提醒， --hooks off 可移除 Plugin 内的提醒配置。确认页会显示具体命令，Host 信任和实际触发仍需分别核对，详见 Hook 安装与验证。独立 Skills 导出不安装 Hook。

通过原安装渠道更新 CLI 后，刷新已登记的 Plugin：

qiongli install plugin --target codex

命令会从 Host 中发现源目录，无需重新填写。--target all 分别处理两个 Host，每个新 Host 使用独立目录；此时不要指定 --destination。

update plugin 与 upgrade plugin 等效。重复运行 install plugin 也会核对并更新已有的完整导出。更新 Host 缓存前会校验收据，只有完全匹配的旧插件才会通过官方命令移除并重装，具体命令会列在确认页。已知 Codex 插件可以按前述流程确认迁移。被修改的文件、来源路径冲突或意外的安装范围仍会阻止注册，需要手动核对。

每次确认直接按回车都表示取消。取消 Host 注册或 Host 命令失败时，已导出的文件会保留；解决问题后，对同一 Host 重新运行 install plugin 即可。成功提示表示官方安装状态和缓存文件已核对，请开启新的 Host 会话加载 Skills 和 Full MCP。实际工具调用仍需在新会话中检查，安装过程不会更换模型。

只需要独立内容文件时：

qiongli install skills
qiongli upgrade skills --preset current-project --profile full

默认安装完整内容到 $HOME/.qiongli-skills；current-project 使用当前目录中的 .qiongli-skills。这一步不会把文件自动注册为 Host Plugin。更新已有内容时需指定原来的 profile，避免无意切换配置档。

脚本可加 --dry-run --json 生成文件计划，审查后用 qiongli app apply 和对应摘要、批准参数执行。该方式只导出文件；Host 注册使用交互入口或手动执行官方命令。管道输入不能代替交互确认。

qiongli upgrade cli 会列出 npm、pip、Cargo 和 GitHub 二进制包的升级方式，不会自行调用包管理器。Plugin 和 Skills 更新的是当前 CLI 内置内容，不会下载新版 CLI。

接入 MCP 与 Plugin

在 Host 的 MCP 配置中，将 command 设为 qiongli 可执行文件的绝对路径，参数设为：

text

mcp serve --profile full --transport stdio

需要 Lite MCP 时使用 --profile lite。Full 提供项目、Graph 和交接等工具，Lite 提供较小的文献工具集。模型与凭据由 Host 管理；下载 CLI 不会自动注册或激活 Plugin。接入后应能看到真实工具，并成功执行一次只读调用。

Alpha.8 也支持将当前可执行文件、Full MCP 与研究资源导出为用户批准的本地 Plugin 来源，再通过 Host 的插件机制注册；详见本地 Plugin 导出步骤。现有项目写入仍需要对应的预览、批准和修订检查，安装不改变这些要求。

Codex Plugin 同时提供 $qiongli 总入口和 $qiongli-paper-read、$qiongli-lit-review、$qiongli-academic-write 等 workflow 入口。这些入口共享同一套研究流程，底层技能卡与模板按需加载，无需手动创建 wrapper。本地 CLI 导出和 Marketplace 打包都会自动生成它们；已经安装的旧 Plugin 需要更新来源或插件包，并通过 Codex 刷新后才能显示新增入口。

两个 Host 的 Plugin 也都包含独立的 no-qiongli Skill。可以在 Codex 中使用 $no-qiongli，或自然地说“NoQ问理，仅回复”。入口不调用工具，使用范围和安装说明见仅回复入口。

包管理器安装

如果更习惯包管理器，可任选一个入口。npm 正式渠道使用 latest， next 可能仍指向之前的 Beta；固定本次 npm 版本可使用 qiongli@2.0.0：

npm install --global qiongli@latest

或者在 Python 虚拟环境中运行：

python -m pip install --upgrade "qiongli==2.0.0"

npm 需要 Node 18+，PyPI 需要 Python 3.9+；两者都提供 qiongli 和 ql。安装后分别用 --version 核对版本。通过原包管理器升级包管理器安装的版本。

Cargo 从源码构建同一个 CLI，需要 Rust 1.97+ 和本机链接器。

cargo install qiongli --version 2.0.0 --locked

安装后可使用 qiongli 和 ql。Cargo 没有 next 渠道，预发布版需指定完整版本号。如果希望解压后立即使用，请选择上方的独立二进制包。

按操作查找入口

要做什么	入口	需要注意
检查安装	`qiongli doctor`、`qiongli install list`	不代表 Host 会话工具已加载
查看和管理项目	`qiongli project --help`	写入保留批准和修订检查
查看内嵌内容	`qiongli content --json`	不会安装 Plugin
查看配置	`qiongli config`、`qiongli config backend status`	模型设置仍由 Host 管理
安装或刷新 Plugin	`qiongli install plugin`	分别确认文件和 Host 注册
导出独立 Skills	`qiongli install skills`	不自动注册 Host 或接入 MCP
查看 CLI 升级方法	`qiongli upgrade cli`	由原包管理器或二进制下载渠道完成升级

论文阅读、写作和审稿通过 Host 中的 Skill 或自然语言请求启动，不是 shell 子命令。 check、provider setup 和 project init 等旧命令不能直接套用到原生 2.x。当前 qiongli setup 用于审查可见的 CLI 安装。

安装状态与版本一致性

qiongli install list 和 qiongli doctor 读取官方 Host 库存，并复用安装时的本地 Plugin 收据校验。来源、缓存、版本或启用状态不能确认时，诊断会说明需要刷新或无法确认，不再一律要求重新安装。只读库存命令有时间和输出限制，不会自动重试写入。

“已注册且缓存一致”只说明安装状态；新会话是否加载了 Skills 和 MCP 工具仍需实际检查。 CLI 与 Plugin 使用各自随包的程序，升级 CLI 后要刷新原 Plugin 目录。检查版本时同时看 qiongli --version、qiongli content --json 和 Host 的 Plugin 库存。

包构建绑定 CLI、内容版本和平台。npm / PyPI 的入口分别只携带各自的启动包装， Cargo 携带可构建的 Rust 源码；共同的 CLI 描述来自同一份包元数据。原生文件与资源摘要、发布收据用于追踪对应构建。版本号相同并不足以证明缓存字节一致。

Research Graph：如何判断比以前更好

可以先看Research Graph 完整示例，里面有虚构输入、可交互页面和可复现的 CLI 流程。在自己的项目中，先看终端摘要，需要检查关系时再打开离线图：

bash

qiongli project graph snapshot --project-id <prj_id> --text
qiongli project graph view --project-id <prj_id> --open

--open 把快照保存为 Qiongli 配置目录中的一个新文件，再请系统默认的 HTML 应用打开它。默认应用通常是浏览器；CLI 会打印保存位置，若没有出现窗口，可以手动打开。只想保存时改用 --save。旧快照会保留，直到你自行删除，不会覆盖项目或之前的导出。原生 CLI 不需要额外运行时，也不用启动本地服务。页面支持按记录类型筛选，并搜索名称、ID 或来源文件；记录较多时可以翻页。关系可以按类型和审阅状态筛选，再逐页查看。箭头表示方向，虚线表示提议，点线表示已拒绝。点击 Back to record 可返回上一条查看过的记录。小屏幕上可以横向滚动关系图，下方列表保留完整名称和相同的查看操作。

来源检查可以定位到问题文件中已提取的记录；没有可显示记录的缺失来源仍会列出。选择记录或关系后，页面会给出绑定当前项目版本和 projection ID 的 qiongli project graph source 命令，用来读取对应记录的片段。点击 Copy command 即可复制；剪贴板不可用时，页面会选中命令，供你手动复制。再沿记录中的文件、页码等位置检查原始材料。来源改变后，需要刷新项目并重新导出。筛选只改变显示内容，下载的 JSON 仍保留完整快照，包括提议和已拒绝的关系。

这个页面是快照。点击 Save snapshot JSON 可以保存同一份投影，作为阶段记录。保留此前的快照和原始材料；导出不会替你归档或删除它们。HTML 和 JSON 都包含研究内容，只应分享给有权查看这些记录的人。

需要自行指定文件位置时，保留原来的 stdout 用法： qiongli project graph view --project-id <prj_id> > research-graph-new.html。请使用新的文件名，避免 shell 重定向覆盖已有文件。

审稿和选刊决定可以通过决策日志中的可选 Related Claims 列关联已有论点 ID，关系为 informs。只有 locked 决定生成已审阅关系，暂定、受阻或待重新考虑的决定仍为提议状态。这些关系不算支持证据。报告位置、理由、适用的期刊要求和稿件影响继续保留在原来的决策记录中。

子代理和跨 Host 协作可以用自然语言提出，例如“让另一个代理独立检查这些证据”。 Skills 会根据实际可用工具分派任务，记录返回的任务标识，等待结果并核对来源版本。 Full MCP 路由会说明其能力边界：它不替 Host 创建代理，也不提供通用跨 Host 自动通信。没有通信工具时，会准备由你转交的材料；重复、过期或尚未完成的返回不算新的独立审查。需要修改项目时，仍由原协调代理整合结果并经过既有写入审批。

1.x 的 citation graph 用于从文献种子扩展引用与参考文献，并去重候选文献。 2.x 的本地 Research Graph 增加了研究记录之间的联系：论点使用稳定标识，证据关联来源和具体位置，写作记录与文献记录可以沿同一来源继续追踪。这两种图的用途不同；不能用增加的节点数量声称文献检索效果或运行速度已经提高。

检查目标	通过标准
一个论点使用多项证据	保留一个 claim ID 和多条独立支持记录，不丢失来源或位置
追踪来源	每条支持边可回到当前记录；CSV 行顺序改变后仍能定位
重复导入与重建	去重后节点和边一致，不产生重复论点
避免虚假支持	缺少位置、待补证据、身份冲突和越界路径不能生成已确认支持
跨阶段继续	沿用论点 ID、citekey、前序总结和来源记录；总结不替代原始证据
防止读取旧状态	CLI/MCP 共用项目 revision，过期读取和未授权修改被拒绝

这些标准由现有 Graph、项目服务和 Full MCP 测试检查。原始笔记或 PDF 仍需要 Host 在授权范围内读取、提出规范记录、供你审阅并保存，再重建 Graph。可用 qiongli project graph --help 查看当前操作；工具缺失时，不能通过直接改文件绕过审批。

结构测试证明记录和来源关系正确，不能代替研究语义判断。下一步比较同一份材料在新 Host 会话中的提取保真度、未解决证据和操作步骤；没有相同任务的前后测量，就不宣称速度提升。

Qiongli 2 CLI：安装与直接下载 ​

安装与命令指南 ​

从安装到首次使用 ​

常用命令 ​

独立二进制下载 ​

1. 校验下载文件 ​

2. 解压后直接运行 ​

3. 可选：加入 PATH ​

检查和迁移已有 CLI ​

安装和升级随包 Plugin、Skills ​

接入 MCP 与 Plugin ​

包管理器安装 ​

按操作查找入口 ​

安装状态与版本一致性 ​

Research Graph：如何判断比以前更好 ​