Plugin 配置

首次安装运行 qiongli install，按快速开始操作。本页说明可选参数与自定义导出。

选择 Host

qiongli install all
qiongli install plugin --target codex
qiongli install plugin --target claude
qiongli install plugin --target deepseek
qiongli install plugin --target antigravity
qiongli install plugin --target pi
qiongli install plugin --target codex,deepseek

Qiongli 2.5.0： 使用 qiongli install all，或在主安装菜单选 5（全部安装）、Plugin 的 Host 菜单选 6 / all，即可依次为所有检测到的 受支持客户端 CLI（codex、claude、dsh、agy、pi）安装 Plugin。每个 Plugin 已包含 Skills 和 Full MCP，无需分别安装。向导会列出选中的客户端和因缺少 CLI 而跳过的客户端；一个也没找到时停止，不执行安装。此命令不安装客户端程序本身。 upgrade all、update all 更新同一组检测到的客户端；可用 --language auto|zh|en 统一选择本轮描述语言。

Qiongli 2.5.1： 不填 --target 的 Plugin 命令默认自动检测， 主安装菜单直接回车也选择全部检测到的客户端。显式指定目录或 Hook 而未指定 Host 时仍显示 Host 菜单；--target all 使用同样的自动选择。 检测覆盖 PATH 和已有的常见 CLI 安装目录；只有桌面应用或配置目录不算可用 CLI。 显式指定 --target codex,claude 等列表时，仍要求这些客户端均可用。 每个 Host 保留各自的文件变更与注册批准流程；单个客户端失败或明确拒绝后继续处理 其余客户端，输入关闭／不完整或输出失败才停止整批。已完成的安装保留。源目录自动选择，无需逐个输入：

• Codex / Claude 优先复用已登记目录，或该 Host 已验证的旧 ~/qiongli 导出。 首次安装分别使用 ~/qiongli-codex、~/qiongli-claude；预发布使用 qiongli-next-*。
• AGY 从已验证的插件缓存恢复原源目录；首次安装用 ~/qiongli-antigravity。
• Pi 复用已登记的本地包路径；首次安装用 ~/qiongli-pi。
• DeepSeek 保留原有 profile 选择与官方包管理流程。

全部检测模式保留已有 Hook 设置，新安装默认关闭；语言和文件／注册批准仍需确认。 默认目录含未知文件、内容被修改或路径不安全时拒绝该项，不覆盖或另建编号目录。

单个 Host 可用 --destination 指定父目录已存在的路径。Codex / Claude 支持原来的 qiongli、qiongli-next 末级目录，也支持对应 Host 的新默认目录名。全部安装不接受 --destination、--hooks 或 --dry-run；这些选项需显式选择兼容的 Host。

文件导出与官方 Host 注册分别确认。取消注册会保留导出文件，不改变 Host 设置；处理失败原因后对同一 Host 重试。保留旧源目录与缓存便于恢复。已知 Codex 冲突可确认迁移，Claude 冲突需手动停用。

安装进度与失败处理

2.5.3 默认只保留客户端标题、审批摘要和最终结果。DeepSeek 的十二项检查 仍会执行，成功时不逐行打印；--verbose 展开阶段、耗时和完整计划。失败始终 显示确切步骤和重试命令。

qiongli install plugin --target deepseek
qiongli install plugin --target deepseek --verbose
qiongli install all --plain

支持的终端在同一短行内更新 Qiongli 状态，不清除历史内容。--plain、 --verbose、NO_COLOR、CI、不支持的终端，以及宽度未知或过窄时停用原地 刷新。重定向安装仍在写入前拒绝；显示选项不会批准修改。

执行 DSH 安装命令时，把终端交给官方管理器，由它显示 pnpm 的进度、缓存计数、 交互和错误。Qiongli 先清除自己的状态行，不叠加计时提示，也不捕获或重放这段 输出。Qiongli 的 --plain／--verbose 不改变 DSH 自己的显示方式。安装命令 使用正常环境与当前工作目录，并传入已核对的 HOME／DSH_HOME 根目录；等待用户 输入时没有 Qiongli 设置的安装超时。Ctrl-C 中断前台命令。其他客户端和 DSH 只读版本检查、profile 初始化仍使用有界捕获与安全诊断摘要，不把初始化生成的 整份配置打印出来。

最终汇总分别列出成功、失败、跳过和未执行的客户端，并提供定向重试命令。 普通失败或拒绝确认会继续后续客户端；关闭输入或中断则停止整批。已完成的修改 保留；只要有失败，整批返回非零状态。只重试未完成的客户端，并选择相同 profile：

qiongli install plugin --target deepseek

host-command-nonzero-exit 本身不能说明网络、版本或权限根因。DSH 的实际错误 现在直接显示在退出状态与重试命令之前，先查看它和保留文件再重试。Qiongli 不保存 DSH 的原始输出。

DeepSeek 分步诊断

十二项依次为：定位命令、检查版本、选择 profile、计划与最新版本查询、确认授权、 复查批准状态、按需初始化 profile、安装包、检查 bundle 注册、包版本与入口声明、 来源内容收据、语言偏好。--verbose 显示 START、结果和耗时，默认仅显示失败。 例如 [DSH 8/12] FAILED 表示管理器执行失败；[DSH 11/12] FAILED 表示安装后 内容检查失败。管理器返回 0 不直接证明安装验证通过，更不能证明新会话工具可用。

已发布的 2.5.1 每步都打印；2.5.2 默认隐藏 START，但仍打印成功结果。这两版还会 捕获安装输出并设置超时。上面的 2.5.3 行为替代了这一 DSH 专属流程。

描述语言

qiongli install plugin --target codex --language zh
qiongli install plugin --target claude --language en

Auto 跟随环境和系统语言，其他语言回退到英文。更新默认保留已保存的选择。只改变描述和支持的显示信息，入口名与工作流正文不变；切换后刷新 Host 或新开会话。

可选上下文 Hook

首次安装默认关闭，更新保留已有选择。

qiongli install plugin --target codex --hooks context
qiongli install plugin --target codex --hooks off

预览会列出命令，Host 信任与实际事件送达仍需单独检查，见 Hook 配置与验证。

DeepSeek Harness

qiongli install plugin --target deepseek 先查询 npm 最新稳定版，再把确切版本锁定 到等待批准的命令中：

dsh plugin --profile desktop add qiongli@<查询到的版本>

不再附加 registry／scripts 参数，包管理策略和相关提示由 DSH 负责。批准后即使 npm 的 latest 变化，也不会改变命令；查询失败则停止当前客户端，不静默使用 缓存版本。下载继续复用 DSH／pnpm 缓存。Plugin 可以比启动安装的 CLI 更新，这 不会升级该 CLI 本身。安装后核验注册、选定包版本和重构的来源内容，不再要求与 旧 CLI 内嵌资源相同；下载完整性仍由官方管理器负责。

单独安装 DSH 时，直接复用所选 profile 保存的语言；首次使用系统语言，省去 单独询问。--language zh、en 或 auto 可以覆盖。损坏的偏好文件会在修改前 拒绝。模型设置保留。

不安装全局 CLI 也可以接入：在 DeepSeek Desktop 的 Add plugin → Official npm registry 中填 [email protected]，或运行：

dsh plugin --profile desktop add [email protected]

把 desktop 换成自己的 profile。包内含 22 个 Skill 入口、Full MCP 和对应平台程序。每个 profile 保留一份穷理，重新加载后检查实际工具。

对 desktop，上面的命令必须使用 DeepSeek Desktop 安装的启动入口。 普通 npm 安装的 dsh 会拒绝管理这个保留 profile，即使两者的 dsh --version 显示相同版本。DSH 0.2.0-rc.2 的 profile "desktop" is managed exclusively by the Electron application 表示触发了这一限制。请使用 Desktop 的插件管理器或其安装的命令入口； 可用 type -a dsh（Bash/Zsh）或 Get-Command dsh -All（PowerShell） 检查是否存在多个命令。改装到 web 会进入另一个 profile，不会装入 Desktop。 参见 DSH 官方说明。

profile 提示默认 desktop，要求 Desktop 已初始化，不自动回退到 web。如果你使用网页或其他 profile，可显式输入 web 或对应名称。新 CLI profile 由官方 web 模板初始化；Desktop 的保留 profile 由 Desktop 自行初始化。DSH 使用自己的包管理器和 profile；--destination、上下文 --hooks 需要另选 Codex/Claude。

更新时通过向导或管理器指定版本。Desktop 对话框按其说明移除后重新添加，保留 profile 与模型设置。开发者导出和外部任务见外部 Agent 协作。

Pi coding agent

Qiongli 2.5.0： 新增实验性 Pi 适配，要求官方 pi CLI 0.99.0 或更新版本，并启用内置 MCP。PATH 需能找到官方 Pi 的实际可执行文件； 此适配暂不支持 Pi 的 mise shim。在 Host 菜单选择 7，或执行：

qiongli install plugin --target pi --language zh
qiongli update plugin --target pi

qiongli install all 也会检测 Pi。包中只展示 /skill:qiongli 和 /skill:no-qiongli 两个入口，科研子流程保留在内部资源库。随包扩展使用 Pi 内置接口注册原生 Full MCP，按需发现工具，无需另装第三方 MCP 桥接器。

默认源目录为 ~/qiongli-pi。单独选择 Pi 时，可用 --destination 指定以 qiongli、qiongli-next 或 qiongli-pi 结尾的安全绝对路径。更新会复用 Pi 用户设置中已校验的源目录，也能识别相对路径声明。安装器遵循 PI_CODING_AGENT_DIR（默认 ~/.pi/agent），先确认文件变更；需要注册时，再 确认官方 pi install <source> 命令。已有模型设置与其他包保留。Unix 上新建的 配置文件采用私有权限；已有链接或组/其他用户可写的配置会被拒绝，安装器不会 修改其权限。若包资源被 筛选、内置 MCP 被禁用，或存在重复 Qiongli 包、独立 Qiongli MCP 配置，先报告 冲突，由用户检查，不会自动覆盖这些选择。

Pi 直接加载源目录，请保留该目录。开启新会话或运行 /reload，通过 /mcp 查看连接，再让 Pi 发现并调用 qiongli_config_status。终端的 pi mcp list 不会加载包扩展。 项目设置、资源禁用或替代 MCP 扩展仍可能影响会话中的可用性； 注册成功不等于模型会话已验证。本适配暂不提供 Pi 上下文 Hook、签名 Host 集成 或 App --dry-run。卸载先执行 pi remove <source>，再处理源目录；移除注册 会保留源文件，便于恢复。

接口依据 Pi 官方 Packages 文档与 MCP 文档。

Antigravity CLI

2.4.0 新增实验性 Antigravity CLI 适配；2.3.0 程序尚未包含此入口。Codex 仍是 主要科研 Host。AGY 1.3.0 的限定观察覆盖安装、正常结束的状态调用，以及提供 公开工具描述后的正文回读。自动发现、完整科研会话恢复和原始 MCP 响应捕获仍 未通过验证。实验性标记保留这些失败供后续改进，不代表科研流程或 IDE 支持通过。

qiongli install plugin --target antigravity --language zh
# agy 是同一个目标的别名
qiongli update plugin --target agy

先安装 agy 1.2.17 或更新版本。向导分别确认源文件导出与官方 agy plugin install、enable 命令。默认源目录为 ~/qiongli-antigravity；单独选择此 Host 时可用 --destination 指定安全绝对路径，末级目录为 qiongli、qiongli-next 或 qiongli-antigravity。2.5.1 更新时可省略目录，从已验证的缓存复用原路径。 包内含原生程序和 Full MCP，采用 根目录 plugin.json、mcp_config.json。

Qiongli 2.5.0： AGY 只公开 qiongli 这一个科研入口，并保留独立的 no-qiongli 仅回复入口。阅读、文献综述、写作等工作流作为内部资源保留，由主入口 根据请求选用；仍可在提示中指明工作流名称。2.4.0 导出仍有 22 个公开 Skill。 新版 CLI 可用后，先升级 CLI，再执行上面的 Plugin 更新命令，并重新开启 AGY 会话。 更新会经收据核验和官方管理器替换旧副入口。不要手动删除缓存中的 Skill；有修改 或未知文件时，收据核验会停止并要求单独处理。

安装后保留源目录。 MCP 通过其中程序的绝对路径启动，不依赖未经验证的路径 变量展开。实测 AGY 1.2.17 由官方管理器复制到 ~/.gemini/config/plugins/<name>； 安装器逐文件核对缓存收据，并单独检查注册和启用状态。缓存有未知或被修改的文件、 另一个穷理 Plugin 已启用，或存在独立配置的穷理 MCP 时会停止并提示处理。 安装器不选择模型，也不迁移登录凭据。

完成 AGY 的工作区信任审阅后，新开会话，用 /mcp 确认穷理服务及工具已加载。 调用 qiongli Skill，再要求调用 qiongli_config_status 并列出 穷理工具。安装成功与会话实际使用分别验证；agy plugin list 可查看 Plugin， 但导入的 MCP 不一定出现在独立的 agy mcp list 中。请在交互会话中审阅并批准 所需的 MCP 调用；实测无交互 --print 会拒绝尚未授权的调用，即使退出码为 0， 仍应检查实际工具结果和 denied_actions。移除时先运行 agy plugin uninstall qiongli（预发布用 qiongli-next），再处理源目录。 当前不提供此 Host 的上下文 Hook、签名集成、app plan 或 --dry-run。

格式依据官方 Plugin 文档和 MCP 文档。IDE 与其他操作系统需另行验证。

独立 Skills

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

默认导出 full 内容到 $HOME/.qiongli-skills，current-project 使用当前目录的 .qiongli-skills。已有 profile 保留。这些是指导文件，不自动注册 Host、连接 MCP 或安装 Hook。

脚本导出 Plugin

Codex/Claude 可先查看只读文件计划：

qiongli install plugin --target codex --destination /absolute/qiongli --dry-run --json

审阅后通过底层命令应用。目标末级目录须为 qiongli 或 qiongli-next，父目录须已存在且安全，选用 Host 缓存与 .qiongli 状态目录以外的位置。在 Unix 上，所有上层目录都不能允许同组用户或其他用户写入。因此，即使直接父目录是私有目录，/tmp 或共享工作区的上层目录仍可能触发 insecure-materialization-parent。请选择上层目录也满足要求的私有导出位置，再重新预览：

qiongli app plan plugin-source-install --target codex \
  --destination /absolute/qiongli > plugin-plan.json
qiongli app apply --plan plugin-plan.json \
  --expected-plan-digest <plan_digest_sha256> --approve-filesystem-write
qiongli app plugin-source-status --target codex --destination /absolute/qiongli

使用新的计划文件名，避免覆盖旧计划。应用前核对路径、程序哈希、收据与摘要。导出后用官方 Host 管理器注册；稳定版选择器为 qiongli@qiongli-cli-local，预发布为 qiongli-next@qiongli-cli-local。

更新用 plugin-source-update。移除前先在 Host 注销，再用 plugin-source-remove。文件被修改、出现未知文件或符号链接、收据过期时会拒绝替换或移除；管道输入不能授权。注册或刷新后，新开 Host 会话检查实际工具。