From 4005510ff746ead0e2088fafe6fa539bcde22e1b Mon Sep 17 00:00:00 2001 From: Teingi Date: Fri, 4 Sep 2026 09:37:46 +0800 Subject: [PATCH 1/3] docs: fix install and DSH startup guidance --- README.md | 34 +++++++++++++---------- README_CN.md | 33 +++++++++++++---------- README_JP.md | 34 ++++++++++++----------- docs/en/docs/how-to/configure-dsh.md | 40 ++++++++++++++++++++-------- docs/zh/docs/how-to/configure-dsh.md | 37 +++++++++++++++++-------- 5 files changed, 113 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 9ba33c7db..40f09b75f 100644 --- a/README.md +++ b/README.md @@ -24,39 +24,45 @@ You decide what will matter later and what needs to move with the task. PowerCon ## Works with your agents -Install [PowerContext](https://pypi.org/project/powercontext/): +Install the latest released [PowerContext](https://pypi.org/project/powercontext/): ```bash uv tool install "powercontext[cli,server]==0.1.0" - -# To use the latest unreleased code instead: -# uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master" ``` -For a persistent personal Server that survives terminal closure and can start again after login, install the native current-user service: +Start a local Server in its own terminal: ```bash -powercontext service install # Uninstall with `powercontext service uninstall` -powercontext service status +powercontext server run ``` -On Windows, the installer asks whether to enable startup at the next login when no login option is supplied; pressing -Enter keeps it disabled. Use `--start-on-login` or `--no-start-on-login` to choose explicitly. +The Server stores context in a local SQLite database by default. -If you want to use it foreground in a terminal, you can run: +Then set up an agent integration from the matching release. For example: ```bash -powercontext server run +powercontext setup codex --ref powercontext-v0.1.0 ``` -The Server stores context in a local SQLite database by default. +Keep the PowerContext tool and agent integration on the same Git ref. To try the latest unreleased `master`, install +and configure both from `master`: -Then set up an agent integration. For example: +```bash +uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master" +powercontext setup codex --source oceanbase/powercontext --ref master +``` + +The current `master` also provides an optional persistent personal Server that survives terminal closure and can +start again after login: ```bash -powercontext setup codex --ref v0.1.0 # --ref also accepts a Git commit, such as 55616dca. +powercontext service install # Uninstall with `powercontext service uninstall` +powercontext service status ``` +On Windows, the installer asks whether to enable startup at the next login when no login option is supplied; pressing +Enter keeps it disabled. Use `--start-on-login` or `--no-start-on-login` to choose explicitly. + For other agents and deployment options, continue with the [agent setup guide](https://powercontext.oceanbase.io/en/docs/tutorials/agent-quickstart/). Supported agent clients and IDEs connect through MCP or a dedicated integration. diff --git a/README_CN.md b/README_CN.md index 8e47b4c7c..12c5a7d7e 100644 --- a/README_CN.md +++ b/README_CN.md @@ -24,39 +24,44 @@ PowerContext 让上下文跟随工作，跨越不同的对话。你回来时， ## 与你使用的 Agent 一起工作 -安装 [PowerContext](https://pypi.org/project/powercontext/)： +安装最新发布的 [PowerContext](https://pypi.org/project/powercontext/)： ```bash uv tool install "powercontext[cli,server]==0.1.0" - -# To use the latest unreleased code instead: -# uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master" ``` -如需让个人 Server 在终端关闭后继续运行，并可以在下次登录后再次启动，请安装原生当前用户服务： +在单独的终端中启动本地 Server： ```bash -powercontext service install # 卸载请运行 `powercontext service uninstall` -powercontext service status +powercontext server run ``` -在 Windows 上，未提供登录启动选项时，安装器会询问是否在下次登录时自动启动；直接按 Enter 的默认选择是不启用。 -需要显式选择时，请使用 `--start-on-login` 或 `--no-start-on-login`。 +Server 默认将上下文保存到本地 SQLite 数据库。 -如果想在终端以前台方式使用，可以运行： +然后从同一个发布版本配置 Agent 集成。例如： ```bash -powercontext server run +powercontext setup codex --ref powercontext-v0.1.0 ``` -Server 默认将上下文保存到本地 SQLite 数据库。 +PowerContext 工具与 Agent 集成应始终使用同一个 Git ref。如需试用最新但尚未发布的 `master`，请同时从 +`master` 安装工具和配置集成： -然后为 Agent 配置集成。例如： +```bash +uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master" +powercontext setup codex --source oceanbase/powercontext --ref master +``` + +当前 `master` 还提供可选的持久个人 Server，它可以在终端关闭后继续运行，并在下次登录后再次启动： ```bash -powercontext setup codex --ref v0.1.0 # --ref also accepts a Git commit, such as 55616dca. +powercontext service install # 卸载请运行 `powercontext service uninstall` +powercontext service status ``` +在 Windows 上，未提供登录启动选项时，安装器会询问是否在下次登录时自动启动；直接按 Enter 的默认选择是不启用。 +需要显式选择时，请使用 `--start-on-login` 或 `--no-start-on-login`。 + 其他 Agent 的配置方式和部署选项请继续阅读 [Agent 配置指南](https://powercontext.oceanbase.io/zh/docs/tutorials/agent-quickstart/)。支持的 Agent Client 和 IDE 可通过 MCP 或专用集成连接。
diff --git a/README_JP.md b/README_JP.md index 3da0cafd8..56236baf7 100644 --- a/README_JP.md +++ b/README_JP.md @@ -24,40 +24,44 @@ PowerContext は、会話をまたいでもコンテキストを作業ととも ## 利用中の Agent と接続する -[PowerContext](https://pypi.org/project/powercontext/) をインストールします： +最新リリースの [PowerContext](https://pypi.org/project/powercontext/) をインストールします： ```bash uv tool install "powercontext[cli,server]==0.1.0" - -# To use the latest unreleased code instead: -# uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master" ``` -ターミナルを閉じても動作を続け、次回ログイン時に再び起動できる個人用 Server を実行するには、現在のユーザー用 -ネイティブサービスをインストールします： +別のターミナルでローカル Server を起動します： ```bash -powercontext service install # Uninstall with `powercontext service uninstall` -powercontext service status +powercontext server run ``` -Windows では、ログイン起動のオプションを指定しない場合、次回ログイン時の自動起動を有効にするか確認します。 -Enter を押すと既定では無効のままです。明示的に選ぶ場合は `--start-on-login` または `--no-start-on-login` を指定します。 +Server はデフォルトで、コンテキストをローカルの SQLite データベースに保存します。 -ターミナルでフォアグラウンド実行する場合は、次のコマンドを使用できます： +次に同じリリースから Agent との連携を設定します。例： ```bash -powercontext server run +powercontext setup codex --ref powercontext-v0.1.0 ``` -Server はデフォルトで、コンテキストをローカルの SQLite データベースに保存します。 +PowerContext ツールと Agent 連携には、常に同じ Git ref を使用してください。最新の未リリース版 `master` を試す場合は、 +ツールのインストールと連携の設定の両方で `master` を指定します： -次に Agent との連携を設定します。例： +```bash +uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master" +powercontext setup codex --source oceanbase/powercontext --ref master +``` + +現在の `master` では、ターミナルを閉じても動作を続け、次回ログイン時に再び起動できる個人用 Server も利用できます： ```bash -powercontext setup codex --ref v0.1.0 # --ref also accepts a Git commit, such as 55616dca. +powercontext service install # アンインストールは `powercontext service uninstall` +powercontext service status ``` +Windows では、ログイン起動のオプションを指定しない場合、次回ログイン時の自動起動を有効にするか確認します。 +Enter を押すと既定では無効のままです。明示的に選ぶ場合は `--start-on-login` または `--no-start-on-login` を指定します。 + その他の Agent の設定方法と導入方法は、[Agent セットアップガイド](https://powercontext.oceanbase.io/en/docs/tutorials/agent-quickstart/)を参照してください。対応する Agent クライアントと IDE は MCP または専用の連携機能で接続できます。
diff --git a/docs/en/docs/how-to/configure-dsh.md b/docs/en/docs/how-to/configure-dsh.md index 2de6affb7..ee757619e 100644 --- a/docs/en/docs/how-to/configure-dsh.md +++ b/docs/en/docs/how-to/configure-dsh.md @@ -7,9 +7,14 @@ description: Install the PowerContext DeepSeek Harness plugin and control its lo ## Install or refresh the plugin -Install DeepSeek Harness first and make sure the web profile exists. Then run: +Install DeepSeek Harness first and make sure the web profile exists. Choose the command that matches the +PowerContext tool you installed: ```bash +# PowerContext 0.1.0 installed from PyPI +powercontext setup dsh --source oceanbase/powercontext --ref powercontext-v0.1.0 + +# Latest unreleased PowerContext installed from Git powercontext setup dsh --source oceanbase/powercontext --ref master ``` @@ -21,7 +26,29 @@ A local checkout works the same way: powercontext setup dsh --source . ``` -`setup dsh` calls `dsh plugin --profile web add`. Open a new `dsh web` session after setup. +`setup dsh` calls `dsh plugin --profile web add`. Complete the startup and checks below before opening a new +`dsh web` session. + +## Start and verify the integration + +Start the Server in a separate terminal and keep it running: + +```bash +powercontext server run +``` + +A successful startup prints the local Dashboard URL. In another terminal, verify both the Server and the installed +DSH plugin, then start a new DSH session: + +```bash +powercontext doctor +powercontext doctor dsh +dsh web +``` + +Run `/pc doctor` inside DSH. It should report successful Server liveness and readiness. The plugin does not print a +success message for every ordinary prompt; when the Server is unavailable, recall and capture fail open so DSH can +continue without PowerContext. Use `/pc doctor` to distinguish that fallback from a working connection. ## Understand what the plugin does @@ -67,12 +94,3 @@ dsh web ``` Do not put the token in the patch file or the Server URL. If the Server is unavailable, recall and capture fail open. Plugin load still requires the DeepSeek Harness peer modules. - -## Verify the installation - -```bash -powercontext doctor -powercontext doctor dsh -``` - -`doctor` checks the package and Server. `doctor dsh` checks the DeepSeek Harness CLI and that dump-config contains the plugin id `powercontext-dsh`. diff --git a/docs/zh/docs/how-to/configure-dsh.md b/docs/zh/docs/how-to/configure-dsh.md index f01d24e39..7d5ff8dfb 100644 --- a/docs/zh/docs/how-to/configure-dsh.md +++ b/docs/zh/docs/how-to/configure-dsh.md @@ -7,9 +7,13 @@ description: 安装 PowerContext DeepSeek Harness 插件并控制其本地行为 ## 安装或刷新插件 -先安装 DeepSeek Harness，并确保 web profile 可用。然后执行： +先安装 DeepSeek Harness，并确保 web profile 可用。然后根据已安装的 PowerContext 工具选择对应命令： ```bash +# 从 PyPI 安装的 PowerContext 0.1.0 +powercontext setup dsh --source oceanbase/powercontext --ref powercontext-v0.1.0 + +# 从 Git 安装的最新未发布 PowerContext powercontext setup dsh --source oceanbase/powercontext --ref master ``` @@ -21,7 +25,27 @@ powercontext setup dsh --source oceanbase/powercontext --ref master powercontext setup dsh --source . ``` -`setup dsh` 内部会执行 `dsh plugin --profile web add`。配置完成后重新打开 `dsh web`。 +`setup dsh` 内部会执行 `dsh plugin --profile web add`。完成下面的启动和检查步骤后，再打开新的 `dsh web` 会话。 + +## 启动并验证集成 + +在单独的终端中启动 Server，并保持该进程运行： + +```bash +powercontext server run +``` + +启动成功后会输出本地 Dashboard 地址。在另一个终端中检查 Server 和已安装的 DSH 插件，然后打开新的 DSH 会话： + +```bash +powercontext doctor +powercontext doctor dsh +dsh web +``` + +在 DSH 中运行 `/pc doctor`，结果应显示 Server 的 liveness 和 readiness 检查成功。插件不会在每次普通对话中都显示 +成功提示；Server 不可用时，召回和采集会正常降级，让 DSH 可以在没有 PowerContext 的情况下继续工作。请使用 +`/pc doctor` 区分正常降级和已经建立的连接。 ## 理解插件行为 @@ -67,12 +91,3 @@ dsh web ``` 不要把 token 写进 patch 文件或 Server URL。Server 不可用时，召回和采集会正常降级。插件加载仍然需要 DeepSeek Harness 的 peer 模块。 - -## 验证安装 - -```bash -powercontext doctor -powercontext doctor dsh -``` - -`doctor` 检查已安装的包和 Server。`doctor dsh` 检查 DeepSeek Harness CLI，以及 dump-config 是否包含插件 id `powercontext-dsh`。 From fe3b528a4abd7604c5aaaa59321b40aa510b6d3a Mon Sep 17 00:00:00 2001 From: Teingi Date: Fri, 4 Sep 2026 10:39:48 +0800 Subject: [PATCH 2/3] docs: drop DSH guide changes --- docs/en/docs/how-to/configure-dsh.md | 40 ++++++++-------------------- docs/zh/docs/how-to/configure-dsh.md | 37 ++++++++----------------- 2 files changed, 22 insertions(+), 55 deletions(-) diff --git a/docs/en/docs/how-to/configure-dsh.md b/docs/en/docs/how-to/configure-dsh.md index 31c0d9ec9..da5486c95 100644 --- a/docs/en/docs/how-to/configure-dsh.md +++ b/docs/en/docs/how-to/configure-dsh.md @@ -7,14 +7,9 @@ description: Install the PowerContext DeepSeek Harness plugin and control its lo ## Install or refresh the plugin -Install DeepSeek Harness first and make sure the web profile exists. Choose the command that matches the -PowerContext tool you installed: +Install DeepSeek Harness first and make sure the web profile exists. Then run: ```bash -# PowerContext 0.1.0 installed from PyPI -powercontext setup dsh --source oceanbase/powercontext --ref powercontext-v0.1.0 - -# Latest unreleased PowerContext installed from Git powercontext setup dsh --source oceanbase/powercontext --ref master ``` @@ -26,29 +21,7 @@ A local checkout works the same way: powercontext setup dsh --source . ``` -`setup dsh` calls `dsh plugin --profile web add`. Complete the startup and checks below before opening a new -`dsh web` session. - -## Start and verify the integration - -Start the Server in a separate terminal and keep it running: - -```bash -powercontext server run -``` - -A successful startup prints the local Dashboard URL. In another terminal, verify both the Server and the installed -DSH plugin, then start a new DSH session: - -```bash -powercontext doctor -powercontext doctor dsh -dsh web -``` - -Run `/pc doctor` inside DSH. It should report successful Server liveness and readiness. The plugin does not print a -success message for every ordinary prompt; when the Server is unavailable, recall and capture fail open so DSH can -continue without PowerContext. Use `/pc doctor` to distinguish that fallback from a working connection. +`setup dsh` calls `dsh plugin --profile web add`. Open a new `dsh web` session after setup. ## Understand what the plugin does @@ -96,3 +69,12 @@ dsh web ``` Do not put the token in the patch file or the Server URL. If the Server is unavailable, recall and capture fail open. Plugin load still requires the DeepSeek Harness peer modules. + +## Verify the installation + +```bash +powercontext doctor +powercontext doctor dsh +``` + +`doctor` checks the package and Server. `doctor dsh` checks the DeepSeek Harness CLI and that dump-config contains the plugin id `powercontext-dsh`. diff --git a/docs/zh/docs/how-to/configure-dsh.md b/docs/zh/docs/how-to/configure-dsh.md index 73a5d5a75..3bdc498dc 100644 --- a/docs/zh/docs/how-to/configure-dsh.md +++ b/docs/zh/docs/how-to/configure-dsh.md @@ -7,13 +7,9 @@ description: 安装 PowerContext DeepSeek Harness 插件并控制其本地行为 ## 安装或刷新插件 -先安装 DeepSeek Harness，并确保 web profile 可用。然后根据已安装的 PowerContext 工具选择对应命令： +先安装 DeepSeek Harness，并确保 web profile 可用。然后执行： ```bash -# 从 PyPI 安装的 PowerContext 0.1.0 -powercontext setup dsh --source oceanbase/powercontext --ref powercontext-v0.1.0 - -# 从 Git 安装的最新未发布 PowerContext powercontext setup dsh --source oceanbase/powercontext --ref master ``` @@ -25,27 +21,7 @@ powercontext setup dsh --source oceanbase/powercontext --ref master powercontext setup dsh --source . ``` -`setup dsh` 内部会执行 `dsh plugin --profile web add`。完成下面的启动和检查步骤后，再打开新的 `dsh web` 会话。 - -## 启动并验证集成 - -在单独的终端中启动 Server，并保持该进程运行： - -```bash -powercontext server run -``` - -启动成功后会输出本地 Dashboard 地址。在另一个终端中检查 Server 和已安装的 DSH 插件，然后打开新的 DSH 会话： - -```bash -powercontext doctor -powercontext doctor dsh -dsh web -``` - -在 DSH 中运行 `/pc doctor`，结果应显示 Server 的 liveness 和 readiness 检查成功。插件不会在每次普通对话中都显示 -成功提示；Server 不可用时，召回和采集会正常降级，让 DSH 可以在没有 PowerContext 的情况下继续工作。请使用 -`/pc doctor` 区分正常降级和已经建立的连接。 +`setup dsh` 内部会执行 `dsh plugin --profile web add`。配置完成后重新打开 `dsh web`。 ## 理解插件行为 @@ -93,3 +69,12 @@ dsh web ``` 不要把 token 写进 patch 文件或 Server URL。Server 不可用时，召回和采集会正常降级。插件加载仍然需要 DeepSeek Harness 的 peer 模块。 + +## 验证安装 + +```bash +powercontext doctor +powercontext doctor dsh +``` + +`doctor` 检查已安装的包和 Server。`doctor dsh` 检查 DeepSeek Harness CLI，以及 dump-config 是否包含插件 id `powercontext-dsh`。 From 036fc8f59614e10539be79a02a9de17ef2f447d8 Mon Sep 17 00:00:00 2001 From: Teingi Date: Fri, 4 Sep 2026 11:45:29 +0800 Subject: [PATCH 3/3] docs: clarify service availability in v0.1.0 --- README.md | 3 +++ README_CN.md | 3 +++ README_JP.md | 4 ++++ 3 files changed, 10 insertions(+) diff --git a/README.md b/README.md index 40f09b75f..8af99f7bd 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,9 @@ Start a local Server in its own terminal: powercontext server run ``` +The `powercontext service` command is not available in the `0.1.0` release. Keep `powercontext server run` running +while you use PowerContext, or install the unreleased `master` version below to use the native personal service. + The Server stores context in a local SQLite database by default. Then set up an agent integration from the matching release. For example: diff --git a/README_CN.md b/README_CN.md index 12c5a7d7e..5e3da7c3e 100644 --- a/README_CN.md +++ b/README_CN.md @@ -36,6 +36,9 @@ uv tool install "powercontext[cli,server]==0.1.0" powercontext server run ``` +`0.1.0` 发布版不包含 `powercontext service` 命令。使用 PowerContext 时，请保持 `powercontext server run` +进程运行；如需使用原生个人服务，请改用下文尚未发布的 `master` 版本。 + Server 默认将上下文保存到本地 SQLite 数据库。 然后从同一个发布版本配置 Agent 集成。例如： diff --git a/README_JP.md b/README_JP.md index 56236baf7..62fb4c771 100644 --- a/README_JP.md +++ b/README_JP.md @@ -36,6 +36,10 @@ uv tool install "powercontext[cli,server]==0.1.0" powercontext server run ``` +`0.1.0` リリースには `powercontext service` コマンドは含まれていません。PowerContext の使用中は +`powercontext server run` を実行したままにするか、ネイティブの個人用サービスを使用するために、以下の未リリース版 +`master` をインストールしてください。 + Server はデフォルトで、コンテキストをローカルの SQLite データベースに保存します。 次に同じリリースから Agent との連携を設定します。例：