多入口與 Typert：一個內核，五張面孔

先玩再講。下面左邊是入口，右邊是內核。五個標籤是五張面孔，選一個，點播放：看這個入口披着什麼皮、發出什麼樣的報文，再看內核的會話日誌裏落下什麼事件。然後換一個入口重播一遍，盯住右邊那排事件，這就是本課要講的全部。

上一批課講過，DSH 的一切功能都是 Cordis 插件，進程啓動時按一份 cordis.yml 把插件掛成一棵樹。這個設計在本課收穫回報：所謂「入口」，就是一份不同的 cordis.yml。倉庫的 examples/ 目錄下躺着現成的三份：headless、JSON-RPC、ACP，翻開對比會發現它們大同小異，DeepSeek 適配器、bash 執行器、JSONL 會話持久化、壓縮、文件系統工具這些內核插件三份全有，差異集中在最上面幾行：JSON-RPC 入口多掛一個 sdk-jsonrpc-server，ACP 入口多掛一個 acp-demo 協議橋和沙箱策略，headless 乾脆什麼伺服器都不掛，進程本身就是入口。

Web 面孔的皮厚一點，但仍然是插件：host-webserver 是個純粹的 node:http 載體，文檔明説它不屬於 agent loop、不瞭解任何 harness 概念（docs/subsystems/web-server.zh.md）；frontend-static 認領回退席位當 SPA 伺服器；client-modules 用 tapIndex 往 index.html 裏注入啓動清單 window.__DSH_BOOT__，瀏覽器端照單加載各插件的前端模組。HTTP API 面孔則是一條鏈：api-remotes 做身份解析，api-gateway 做參數解碼和方法調用，connection 獨佔 /api 路由的 RPC 信封，最後落回同一個 webserver（docs/api-gateway.zh.md）。

Python SDK 最能説明「皮」有多薄。pip install deepseek-harness-sdk 會連帶裝一個平台 wheel，裏面是單文件可執行的 dsh-jsonrpc-agent；SDK 啓動它當子進程，通過 DSH_CORDIS_CONFIG 注入預設組合，然後在 stdio 上説 JSON-RPC（python/sdk/README.zh.md）。所以 Python SDK 和 JSON-RPC 入口是同一張面孔的兩種穿法，Python 這層只是把協議包成了 harness.run("…")。

大綱裏那道邊界條件題的答案就藏在配置註釋裏。JSON-RPC 示例的第 2 行寫着 stdout 保留給 JSON-RPC，禁止加 console logger 或終端 UI；ACP 示例同樣聲明整棵樹不掛 stdout 日誌和 HMR，因為 stdout 載着 ACP 的 JSON-RPC（兩份 cordis.yml 的開頭註釋）。道理一句話：這兩種協議把 stdout 當傳輸綫，往上面混打一行日誌，對端的解析器就斷綫了。日誌走 ctx.logger 另尋出路，這是協議入口的鐵律。

翻開 examples/jsonrpc-agent/cordis.yml，第 1 行註釋説明這是給捆綁運行時用的無人值守部署，第 2 行就是那條鐵律的原文：stdout 保留給 JSON-RPC，不要加 console logger 或終端 UI。往下看，協議橋 sdk-jsonrpc-server 只是插件列表裏普通的第一項，連它的配置都走環境變數注入。一個入口的全部家當就這麼多：一份配置，頂部幾行是它的臉，其餘全是和別的入口共用的內核。

出處：examples/jsonrpc-agent/cordis.yml 第 1 至 7 行，核對日期 2026-08-13。

五張面孔裏，Web 和 HTTP API 這兩張要跨進程調用 Host 裏的業務方法，這就需要一層 RPC。DSH 沒用現成框架，自研了 Typert。業務開發者要做的事少到只剩一個裝飾器：在服務方法上標 @Remote('create')，構建時 Typert 分析 TypeScript 類型圖，生成三樣東西：校驗參數的 Zod schema、描述調用的 descriptor、給瀏覽器端用的類型聲明。不需要手寫路由表、參數轉換、客戶端 stub，改一處方法簽名，重新構建後所有端的調用約定同步更新（docs/subsystems/typert.zh.md、packages/typert/generator/README.zh.md）。

點解現成方案唔得？因為要跨 wire 的東西裏有 Cordis 特有的概念，通用 schema 生成器沒有詞彙描述它們。三個例子。第一，Host 和瀏覽器是兩個獨立的 TypeScript Program，同名的 Cordis Context 在兩邊的類型合併結果不一樣，一份 schema 餵兩邊行不通。第二，業務方法的參數可能是 Agent 這樣的活對象，它不能被序列化過 wire，Typert 用 lookup 機制把 agent 參數改寫成 wire 字段 agentId，Gateway 收到請求後先把 id 解析回活對象再調方法。第三，客戶端的 ctx.remote.goals 是隨插件掛載卸載的活服務，最後一個方法撤回，整個 namespace 跟着卸載，這是 OpenAPI 那種靜態描述表達不了的生命週期（Typert Gateway Agent Note 2026-08-02）。

還有一條值得記住的紀律：descriptor 是本地反射信息，不上 wire。Host 和客戶端各自在構建時生成彼此對應的 descriptor，請求裏只發 endpoint 和具名參數；取消信號作為帶外的 carrier signal 注入，絕不混進業務參數（docs/subsystems/typert.zh.md 的調用 descriptor 一節）。生成器還很固執：遇到表達不了的類型投影直接報錯，絕不把源類型展平弱化了矇混過去。這和前兩課的「拒絕解讀」一脈相承，説不清楚的事寧可不做。

Goal 服務的真實程式碼。一個裝飾器加一個薄適配，JSDoc 裏那句「從 wire identity 解析出的活 Agent」就是 lookup 機制在業務側的樣子：

  /**
   * Create one Goal through the remote boundary.
   * @param agent - exact live Agent resolved from the wire identity.
   * @param request - objective and optional round cap.
   * @returns the created Goal identity.
   */
  @Remote('create')
  remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
    const view = this.create(agent, request)
    return { ref: { id: view.id, revision: view.revision } }
  }