@kagurazakayashi/dsh-startup-command

dsh plugin --profile web add @kagurazakayashi/dsh-startup-command

dsh-startup-command

[简体中文](README.zh-CN.md) | 繁體中文 | [English](README.md) | [日本語](README.ja.md)

在 dsh web 啟動成功後執行使用者自訂命令的 DeepSeek Harness Web 外掛。

當 dsh web 完成啟動（Loader 樹全部穩定、webServer 開始監聽）後，本外掛會執行你在 profile 中配置的自訂命令——例如用特定瀏覽器、帶特定參數開啟 Web GUI。

命令完全由配置（profile 的 cordis.patch.yml 中 dsh-startup-command 的 config 條目，可從網頁設定卡片編輯）決定，不硬編碼在外掛原始碼中。{url} 佔位符會被替換為實際 GUI 地址（http://127.0.0.1:<port>/?token=…），因此即使使用 --port 0 由作業系統分配埠也能正確工作。

截圖

本外掛自己的「插件」頁（側邊欄「外掛」→ 開啟本外掛，設定區位於外掛說明與各項之間）顯示的設定卡片：

功能特性

• 啟動成功後觸發：與內建 web-app 的 openBrowser 走完全相同的生命週期——等整棵 Loader 樹 settle、webServer 服務就緒之後才執行，保證拿到的一定是「監聽啟動後」的實際地址。
• 命令完全可配置：外掛自己宣告設定 schema，名稱空間即 profile 入口 id（dsh-startup-command），command 支援單條字串或多條陣列；多條命令按順序依次執行（前一條退出後才執行下一條）。改配置無需動外掛原始碼。
• {url} / {home} / {browser} 佔位符：{url} 執行前替換為 http://127.0.0.1:<實際埠>/?token=…（新版 dsh web 需要 token 換取瀏覽器登入 cookie；舊版或無 connection 服務時自動退回不帶 token 的乾淨 URL），埠自動分配（--port 0）時同樣生效；{home} 替換為使用者資料夾；{browser} 自動查詢 Chromium 家族瀏覽器（優先 Chromium > Chrome > Edge，若預設瀏覽器是其中之一則採用預設瀏覽器）。
• 不阻塞 dsh 行程：以 detached 方式生成子行程並忽略其標準輸入輸出，命令獨立執行，dsh 退出時不會被拖住。
• 開關與模式：enabled: false 可臨時關閉；shell: true 可走系統 shell 執行（預設關閉，直接以參數陣列 spawn，路徑含空格也安全）。
• 配置缺失即跳過：未設定 command 時列印警告並跳過，不會靜默失敗或誤執行。
• 網頁設定卡片：在本外掛自己的「插件」頁（側邊欄「外掛」→ 開啟本外掛）提供一張可展開卡片，就地編輯 enabled / shell / command，並提供「新增示例命令」按鈕——彈出說明框介紹示例命令後，一鍵插入自動查詢瀏覽器的現成命令，無需手改 cordis.patch.yml。

掛載方式

本外掛是「雙面」外掛：host 半側（index.js，啟動時執行命令）+ 瀏覽器半側（client.js，在側邊欄「外掛」頁中本外掛自己的頁面註冊設定卡片）。

1. 獲取包

從 npm 安裝（推薦）：

npm install @kagurazakayashi/dsh-startup-command
# pnpm 型 profile 可用：
# pnpm add @kagurazakayashi/dsh-startup-command

或從原始碼安裝（本地開發）——將外掛目錄放到 profile 下並軟鏈：

C:\Users\<你>\.dsh\profiles\web\plugins\dsh-startup-command\

{
  "dependencies": {
    "@kagurazakayashi/dsh-startup-command": "link:plugins/dsh-startup-command"
  }
}

然後執行 pnpm install 生成軟鏈；或手動建立

node_modules/@kagurazakayashi/dsh-startup-command 指向

../../plugins/dsh-startup-command 的 junction/symlink。

2. 掛載外掛

在 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml 中新增 insert 條目（該行只負責掛載；命令本身作為 config 條目在下一節新增）：

- insert:
    - id: dsh-startup-command
      name: '@kagurazakayashi/dsh-startup-command'
      inject: [webServer]

3. 配置並重啟

在 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml 中為 dsh-startup-command 新增 config 條目（見下節），然後重啟 dsh web 生效。重啟後，本外掛自己的「插件」頁（側邊欄「外掛」→ 開啟本外掛）會出現設定卡片，可就地編輯 enabled / shell / command。

在哪裡找到這張卡片（dsh 0.2.x 起外掛配置已不在「設定」對話方塊裡，而在外掛自己的頁面上）：

1. 在側欄頂部開啟「外掛」頁（四宮格圖示，位於「工作區」之上），不是底部的「設定」。

2. 等「已安裝」清單填充出來。該頁需要向 host 查詢外掛清單，冷啟動的瀏覽器會話裡可能要十幾秒；清單未出現時頁面幾乎是空的，並非沒有內容。

3. 在「已安裝」裡點本外掛的條目開啟詳情頁——1.1.1 起清單顯示本地化名稱「啟動命令」，舊版本顯示包名 @kagurazakayashi/dsh-startup-command；點右側開關或空白處不會進入詳情頁。

4. 配置區位於該外掛的說明與包含的元件之間；卡片預設收起，點卡片標題展開。

若啟用了帶背景圖案的皮膚，插件頁的文字會壓在畫面上、對比度偏低（該頁沒有不透明底色，卡片保留自己的底色），臨時切換或停用皮膚會更容易看清。

配置詳解

配置位於 profile 的 cordis.patch.yml（例如 $DSH_HOME/profiles/<profile>/cordis.patch.yml）中 dsh-startup-command 的 config 條目。schema 由外掛自己宣告，名稱空間即本 bundle 的 cordis.patch.yml 宣告的 profile 入口 id dsh-startup-command；未配置時以下 schema 預設值生效：

- id: dsh-startup-command
  config:
    enabled: true
    shell: false
    command: '"C:\Program Files\Chromium\Application\chrome.exe" --user-data-dir="..." --app={url}'

支援以下欄位：

• command (string | string[]) — 單條命令直接寫字串；多條命令寫成陣列，按順序依次執行，前一條退出後才執行下一條；每條按引號分組成 argv，路徑含空格必須用雙引號包住
• enabled (boolean, 預設 true) — 設為 false 臨時關閉
• shell (boolean, 預設 false) — 設為 true 時經系統 shell 執行

command 支援以下佔位符，均在執行前替換：

• {url} — 實際 GUI 地址（新版 dsh web 為帶 ?token= 的認證 URL）
• {home} — 當前使用者資料夾（os.homedir()）
• {browser} — 自動查詢的 Chromium 家族瀏覽器可執行檔案路徑。查詢規則：系統預設瀏覽器若是 Chromium / Chrome / Edge 之一，則採用預設瀏覽器；否則按 Chromium > Chrome > Edge 的優先順序返回第一個已安裝者

網頁設定卡片上的「新增示例命令」按鈕會先彈出說明框介紹示例命令，確認後再追加一條使用 {browser}、{home}、{url} 的現成命令；查詢結果來自 host 上只讀路由 GET /dsh-startup-command/browser，卡片掛載時讀取一次；若未找到 Chromium / Chrome / Edge，則會提示「無法生成示例命令」並說明原因。

使用示例

用 Chrome 以獨立配置目錄、快取目錄、仿 APP 視窗開啟 GUI，不顯示歡迎畫面、不載入任何擴充套件：

- id: dsh-startup-command
  config:
    command: '"C:\Program Files\Google\Chrome\Application\chrome.exe" --user-data-dir="D:\dsh-chrome-profile" --disk-cache-dir="D:\dsh-chrome-cache" --app={url} --no-first-run --disable-extensions'

各參數含義：

• --app={url} — 仿 APP 視窗（應用模式，無位址列/工具欄）
• --no-first-run — 不顯示首次執行歡迎畫面
• --disable-extensions — 不載入任何擴充套件
• --user-data-dir=<路徑> — 指定配置（profile）目錄
• --disk-cache-dir=<路徑> — 指定快取目錄

注：使用獨立 --user-data-dir 可避免與已執行的 Chrome 例項衝突（否則 --app 會被已有例項接管、開關不生效）。

自動查詢 Chromium / Chrome / Edge 並帶上上述參數（等效於網頁卡片上的「新增示例命令」按鈕）：

- id: dsh-startup-command
  config:
    command: '"{browser}" --user-data-dir="{home}/.dsh/dsh-browser-data" --disk-cache-dir="{home}/.dsh/dsh-browser-cache" --app={url} --no-first-run --disable-extensions'

多條命令按順序依次執行（前一條退出後才執行下一條）：

- id: dsh-startup-command
  config:
    command:
      - 'cmd /c ping -n 3 127.0.0.1' # 先做點準備工作（此例約 2 秒後退出）
      - '"C:\Program Files\Google\Chrome\Application\chrome.exe" --app={url}'

開啟任意程式（例如記事本）：

- id: dsh-startup-command
  config:
    command: 'C:\Windows\System32\notepad.exe'

與內建「開啟預設瀏覽器」的關係

dsh web 內建會在啟動成功後用 open 包開啟系統預設瀏覽器（web-runtime 行的 openBrowser）。如果你用本外掛指定瀏覽器開啟，通常會希望關掉內建行為，避免雙重開啟。在 cordis.patch.yml 中覆蓋該行（patch 會整行替換 config，必須重述所有鍵）：

- id: web-runtime
  config:
    openBrowser: false
    printUrl: true
    surfaceContext: true
    trustedHosts: !!js ctx.webStartup.trustedHosts

如果不需要禁用內建行為（例如想讓預設瀏覽器與自訂命令共存），去掉這段即可。

觸發時序

dsh web 啟動
    │
    ▼
Loader 樹全部 settle（webServer 開始監聽）
    │
    ▼
dsh-startup-command 執行：{url} 替換 → spawn(命令)
    │
    ▼
子行程 detached 執行，dsh 持續服務

解除安裝

從 profile 的 cordis.patch.yml 中刪除 dsh-startup-command 的 insert 條目（以及不再需要的 web-runtime 覆蓋）與該檔案中 id: dsh-startup-command 的 `config:

…(truncated)