Skip to content

feat(cli): add doctor integrations for first-class host status #1314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
knqiufan wants to merge 3 commits into
base: master
Choose a base branch
from
Open

feat(cli): add doctor integrations for first-class host status #1314

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f72c105
feat(cli): add setup select for explicit multi-host plugin install
knqiufan Aug 21, 2026
19bf317
style: format setup select tests for ruff
knqiufan Aug 21, 2026
b87faa8
feat(cli): add doctor integrations for first-class host status
knqiufan Aug 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/en/docs/how-to/install-and-run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,14 @@ powercontext setup dsh --source oceanbase/powercontext --ref <ref>
powercontext setup pi --source oceanbase/powercontext --ref <ref>
```

Per-host commands remain the explicit path. To install more than one first-class host in one run, pass `--host`
repeatedly, or omit `--host` on a TTY to choose from the catalog. `powercontext setup` with no subcommand still
prints help:

```bash
powercontext setup select --host codex --host dsh --source oceanbase/powercontext --ref <ref>
```

For host-specific options, see [Configure Codex](configure-codex.md) and
[Configure DeepSeek Harness](configure-dsh.md).

Expand Down Expand Up @@ -53,6 +61,7 @@ disable the Dashboard explicitly.

```bash
powercontext doctor
powercontext doctor integrations
powercontext doctor codex
powercontext doctor dsh
powercontext doctor pi
Expand All @@ -63,6 +72,7 @@ powercontext capabilities
`doctor` checks the installed package, Server liveness, and Server readiness without requiring an integration. Server
readiness covers the database and each configured inference provider. Runtime or database failures return
`not_ready`; an inference failure returns `degraded` without removing database-backed operations from traffic.
`doctor integrations` is an optional read-only overview of every first-class host; a missing CLI does not fail that command.
`doctor codex`, `doctor dsh`, and `doctor pi` separately check their optional host CLI and PowerContext integration. The content commands exercise the
public HTTP SDK path. `ready` and `capabilities` show the readiness and enabled capabilities of the running service. For complete status definitions and
recovery steps, see [Troubleshoot](troubleshoot.md).
Expand Down
9 changes: 8 additions & 1 deletion docs/en/docs/how-to/troubleshoot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,17 @@ The command checks the package, Server liveness, and Server readiness. It exits
the top-level result and every check include `ok` and `status`. Check optional host integrations separately:

```bash
powercontext doctor integrations
powercontext doctor codex
powercontext doctor claude-code
powercontext doctor dsh
powercontext doctor pi
```

`doctor integrations` prints every first-class host. A host whose CLI is not on PATH is `missing` and does not fail
the command. A present host that is broken still exits 1. Single-host commands such as `doctor codex` stay fail-closed
when that CLI is missing.

## Installation cannot read the Git URL

Confirm that Git can read the repository:
Expand All @@ -48,7 +53,9 @@ command -v pi

Add the uv tool bin directory to `PATH` if needed. `powercontext setup codex`, `powercontext setup claude-code`,
`powercontext setup dsh`, and `powercontext setup pi` report an error rather than attempting installation when the host
CLI is unavailable.
CLI is unavailable. `powercontext setup select` installs only the hosts you choose. A selected host that is missing
still fails that row and does not block the other selected hosts. An unselected host is skipped even if its CLI is on
`PATH`.

## The plugin is missing or stale

Expand Down
11 changes: 7 additions & 4 deletions docs/en/docs/reference/interfaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,9 @@ boundary flushing fail open; explicit durable writes require interactive confirm
powercontext setup codex
powercontext setup dsh
powercontext setup pi
powercontext setup select
powercontext doctor
powercontext doctor integrations
powercontext doctor codex
powercontext doctor dsh
powercontext doctor pi
Expand Down Expand Up @@ -115,10 +117,11 @@ powercontext external-skill import --scope-id project:example --fingerprint SHA2
All content commands call the configured Server. The optional `server` role adds `powercontext server run`; it does
not create a second content profile inside the CLI.

`powercontext doctor` checks the package and Server without requiring an integration. `powercontext doctor codex`
checks the Codex CLI and PowerContext plugin explicitly. `powercontext doctor dsh` checks the DeepSeek Harness CLI
and that dump-config lists the plugin id `powercontext-dsh`. `powercontext doctor pi` checks the Pi executable and
that Pi lists the PowerContext package.
`powercontext doctor` checks the package and Server without requiring an integration. `powercontext doctor integrations`
prints a read-only matrix for every first-class host; a missing CLI is `missing` and does not fail the command.
`powercontext doctor codex` checks the Codex CLI and PowerContext plugin explicitly and still fails when that CLI is
missing. `powercontext doctor dsh` checks the DeepSeek Harness CLI and that dump-config lists the plugin id
`powercontext-dsh`. `powercontext doctor pi` checks the Pi executable and that Pi lists the PowerContext package.

Generation and revision commands accept repeatable `--source-ref TYPE/ID` and
`--artifact-ref FAMILY/ID@REVISION` options instead of serialized request files. `--target FAMILY/ID@REVISION`
Expand Down
11 changes: 10 additions & 1 deletion docs/zh/docs/how-to/install-and-run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,13 @@ powercontext setup dsh --source oceanbase/powercontext --ref <ref>
powercontext setup pi --source oceanbase/powercontext --ref <ref>
```

单宿主命令仍是显式路径。若要一次安装多个一级宿主，可重复传入 `--host`；在 TTY 上省略 `--host` 则从目录中选择。
不带子命令的 `powercontext setup` 仍然只打印帮助：

```bash
powercontext setup select --host codex --host dsh --source oceanbase/powercontext --ref <ref>
```

宿主专有选项见[配置 Codex](configure-codex.md)和[配置 DeepSeek Harness](configure-dsh.md)。

## 运行本地 Server
Expand All @@ -50,6 +57,7 @@ powercontext server run

```bash
powercontext doctor
powercontext doctor integrations
powercontext doctor codex
powercontext doctor dsh
powercontext doctor pi
Expand All @@ -59,7 +67,8 @@ powercontext capabilities

`doctor` 检查已安装的包、Server 存活状态和 Server 就绪状态，不要求安装集成。Server 就绪检查涵盖数据库和
每个已配置的推理服务。Runtime 或数据库故障返回 `not_ready`；推理服务故障返回 `degraded`，不会使数据库
操作退出流量。`doctor codex`、`doctor dsh` 和 `doctor pi` 分别检查对应的可选宿主 CLI 与 PowerContext 集成。内容命令会经过公开 HTTP SDK
操作退出流量。`doctor integrations` 是可选的一级宿主只读总览，缺失 CLI 不会让该命令失败。
`doctor codex`、`doctor dsh` 和 `doctor pi` 分别检查对应的可选宿主 CLI 与 PowerContext 集成。内容命令会经过公开 HTTP SDK
路径。`ready` 和 `capabilities` 用于查看运行中服务的就绪状态和已启用能力。完整的状态解释和恢复步骤见[排查问题](troubleshoot.md)。

## 更新或替换安装
Expand Down
6 changes: 6 additions & 0 deletions docs/zh/docs/how-to/troubleshoot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,16 @@ powercontext doctor
`ok` 与 `status`。可单独检查可选的宿主集成：

```bash
powercontext doctor integrations
powercontext doctor codex
powercontext doctor claude-code
powercontext doctor dsh
powercontext doctor pi
```

`doctor integrations` 会打印全部一级宿主。CLI 不在 PATH 上时该行是 `missing`，不会让整条命令失败；已安装但异常的
宿主仍会以状态码 1 退出。单宿主命令（如 `doctor codex`）在该 CLI 缺失时仍然失败。

## 安装时无法读取 Git 地址

确认 Git 能够读取仓库：
Expand All @@ -48,6 +52,8 @@ command -v pi

必要时把 uv tool bin 目录加入 `PATH`。宿主 CLI 不可用时，`powercontext setup codex`、
`powercontext setup claude-code`、`powercontext setup dsh` 和 `powercontext setup pi` 都会报告错误，而不会尝试安装。
`powercontext setup select` 只安装你选中的宿主。某个选中宿主未安装时，该行失败，但不会阻塞其余选中项；未选中的
宿主即使已在 `PATH` 上也不会安装。

## 插件缺失或版本不一致

Expand Down
7 changes: 5 additions & 2 deletions docs/zh/docs/reference/interfaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,9 @@ Pi transcript。召回、采集和边界 flush 都会正常降级；显式持久
powercontext setup codex
powercontext setup dsh
powercontext setup pi
powercontext setup select
powercontext doctor
powercontext doctor integrations
powercontext doctor codex
powercontext doctor dsh
powercontext doctor pi
Expand Down Expand Up @@ -106,8 +108,9 @@ powercontext external-skill import --scope-id project:example --fingerprint SHA2
所有内容命令都调用已配置的 Server。可选的 `server` role 会增加 `powercontext server run`，但不会在 CLI
中创建第二套内容 profile。

`powercontext doctor` 检查安装包和 Server，不要求任何集成；`powercontext doctor codex` 显式检查 Codex CLI
和 PowerContext 插件；`powercontext doctor dsh` 检查 DeepSeek Harness CLI，以及 dump-config 是否列出插件 id
`powercontext doctor` 检查安装包和 Server，不要求任何集成。`powercontext doctor integrations` 打印全部一级宿主的只读矩阵；
CLI 不在 PATH 上时该行是 `missing`，不会让整条命令失败。`powercontext doctor codex` 显式检查 Codex CLI
和 PowerContext 插件，该 CLI 缺失时仍失败。`powercontext doctor dsh` 检查 DeepSeek Harness CLI，以及 dump-config 是否列出插件 id
`powercontext-dsh`；`powercontext doctor pi` 检查 Pi 可执行文件，以及 Pi 是否列出了 PowerContext package。

Generation 和 revision 命令通过可重复的 `--source-ref TYPE/ID` 与
Expand Down
Loading
Loading