pictera · ハーネス理解

dsh と OpenCode から言えるハーネスのこと

DeepSeek Harness（dsh）の SDK クライアント解説と、OpenCode の公開ドキュメント・リポジトリ README だけを根拠に、ハーネスという概念と外部実装の境界を整理します。推測は書きません。ソースに無い接続は「欠落」とします。pictera の製品決定は正本（project-context.md）に明示されたものだけ載せます。

更新 2026-09-23 dsh 根拠: deepseek-harness-sdk-client-ja.html OpenCode 根拠: README / docs / packages

範囲と正本

この HTML はハーネスを理解するための読み物です。実装の完了やコードの置き場所は前提にしません。

  • dsh — sandbox_baya の pichtml/deepseek-harness-sdk-client-ja.html（DeepSeek Harness TypeScript SDK クライアント README 等の日本語整理）。配置の読み方は Project ストアの deepseek-harness-architecture.md を参照（本 HTML では再掲しない）。
  • OpenCode — リポジトリ anomalyco/opencode（確認時 dev / 18ef3cc）、Agents ドキュメント、Server ドキュメント、packages/client/README.md、packages/sdk-next/README.md。
  • pictera 製品決定 — Project 正本 project-context.md の「決定」節のみ。正本に無い採用・接続は書きません。
dsh 解説 HTML は呼び出し元の例として Pictera と書いています。これは SDK 文書上の例示であり、正本が DeepSeek を実行先に採用した決定ではありません。

用語（正本）

正本の決定 9 より:

  • pictera が持つハーネス — 製品側の層。Claude Code はハーネスそのものではなく、状況によって選ぶ実行先の一つ。
  • 実行 — ターミナルではなく画面のクリック（決定 10）。状態は右上（決定 11）。

dsh の DeepSeekHarness や OpenCode サーバーは、それぞれ別製品のランタイム／エージェント基盤です。正本の「ハーネスは自分で持つ」と同一視しない（配置図の二層の整理）。

dsh（DeepSeek Harness）から言えること

根拠: deepseek-harness-sdk-client-ja.html（パッケージ @deepseek-ai/dsh-sdk-client）。

位置づけ

TypeScript プログラムから dsh ランタイムを別プロセスとして起動し、標準入出力上の JSON-RPCでセッションとエージェント実行を操作するクライアントです。エージェント本体・ツール・セッション保存方式・モデルに見えるプロンプトは、起動するランタイムのプロファイルとプラグインが決めます。

呼び出し元アプリHTML 上の例: Pictera
DeepSeekHarnessセッションと run
HarnessClientstdio JSON-RPC
dsh ランタイム別プロセス
Agent / Pluginsモデル・ツール・履歴

SDK が決めること / 決めないこと

SDK が決めるSDK が決めない
子プロセスの起動と所有、initialize / session/prompt / shutdown、通知購読、run() がアイドルまで待って結果を返すこと、close() の終了順（shutdown → stdin 終了 → SIGTERM → SIGKILL） エージェント本体、ツール、セッション保存方式、モデル向けプロンプト（ランタイム側）。クライアントプロセスは KV キャッシュを使わない

実行とセッション

  • 同じ DeepSeekHarness インスタンスは複数回の run() で子プロセスを再利用する。
  • sessionId を省略した run() は新しいセッション。会話を続けるには同じ sessionId を渡す。
  • 会話履歴は dsh ランタイムが管理。dsh が知らないアプリ状態（例: 画面状態）は入力または設定済みツール経由で渡す必要がある。
  • run() の finalResponse は、収集区間におけるルートセッションの最後に確定したアシスタント本文であり、必ずしも今回の入力だけへの回答ではない。

2 段階の API

API用途
DeepSeekHarness入力を実行し、次のアイドルまで待ってイベントと最終応答を返す（一般的な統合）
HarnessClientinitialize、prompt()、通知購読などプロトコル直接制御。低水準 prompt() は完了を待たない

制約（HTML が列挙するもの）

  • TypeScript 版は dsh 実行ファイルを同梱しない。dshBin または同バージョンの @deepseek-ai/dsh が必要。パッケージ済みランタイムの自動検出は Python 側。
  • 実行途中だけをキャンセルするプロトコル操作はない。放棄するならランタイムプロセスを閉じる。
  • HarnessClientOptions.env を渡すと子プロセス環境は置き換え（親の環境変数は自動継承されない）。
  • 初期化要求には作業ディレクトリとモデル経路などが含まれる（事実）。llm-router 出力を provider / model に渡す手続きは dsh ソースに無い → 欠落（後述）。

OpenCode から言えること

根拠: OpenCode README（日本語 README.ja.md 含む）、公式 docs、上記 packages README。

製品の説明（README）

OpenCode は オープンソースの AI コーディングエージェント（The open source AI coding agent）。ターミナル UI・デスクトップアプリ・IDE 連携など複数の利用形態を README が案内する。モデル提供元に固定されない設計を README が述べる範囲は、英語 README の比較節などに依存するため、本 HTML では docs の設定・API 記述を優先する。

クライアント / サーバー

Server ドキュメントより:

  • 通常 opencode 起動時、TUI がクライアント、サーバーが OpenAPI 3.1 エンドポイントを公開する。
  • opencode serve でヘッドレス HTTP サーバー単体を起動できる（既定 127.0.0.1:4096）。複数クライアントから同じサーバーへ接続する構成が可能、と docs が説明する。
  • 仕様は http://<host>:<port>/doc の OpenAPI。プログラム連携用に @opencode-ai/client が HttpApi から生成される（packages/client/README.md）。
  • @opencode-ai/sdk-next は Server の HTTP ルータをプロセス内で実行し、ネットワーク I/O なしで同じルーティング・ミドルウェア・ハンドラを使う（packages/sdk-next/README.md）。
クライアントTUI / デスクトップ / HTTP クライアント / 組み込み SDK
OpenCode サーバーOpenAPI · セッション · エージェント · ツール
モデルプロバイダ設定と認証（/provider 等）

エージェント（Agents ドキュメント）

エージェントは primary（Tab で切替・メイン会話）と subagent（@ メンションまたは primary からの委任）に分類される。

組み込みの例（docs が列挙するもの）:

  • build — 既定の primary。ツールは permission で制御；開発向けフルアクセスの説明。
  • plan — primary。ファイル編集・bash などを既定 ask / 拒否寄りにし、分析・計画向け。
  • general — subagent。複雑な調査・マルチステップ（README.ja も @general を記載）。
  • explore — subagent。読み取り専用のコードベース探索。
  • scout — subagent。外部ドキュメント・依存関係調査（読み取り専用）。
  • compaction / title / summary — 非表示の primary 系システムエージェント（自動実行）。

subagent は子セッションを作る。親子セッション間のナビゲーション用キーバインドが docs にある（session_child_first 等）。

各エージェントは opencode.json または Markdown（~/.config/opencode/agents/、.opencode/agents/）で mode、model、permission などを設定できる。

セッションと HTTP API（Server ドキュメントの一部）

サーバーはセッション CRUD、メッセージ送信、非同期プロンプト、中断、権限応答、子セッション一覧などを HTTP で公開する。例:

  • POST /session — セッション作成（任意 parentID）
  • POST /session/:id/message — メッセージ送信して応答待ち
  • POST /session/:id/prompt_async — 非同期送信（204）
  • GET /session/status — 全セッションのステータス
  • POST /session/:id/abort — 実行中断
  • GET /session/:id/children — 子セッション

LSP・MCP・ツール一覧などもサーバー API 経由で扱う（docs の API 表）。

pictera 正本から言えること（製品決定のみ）

根拠: project-context.md 決定節。ハーネス実装の技術選定はここから増やさない。

決定内容（要約）
9ハーネスは自分で持つ（pictera）。Claude Code は実行先の一つで、状況によって何を使うか決める。
10–11実行は画面のクリック。ステータスは右上。
12Project ページを持ち、常駐エージェントを親とする。コンテキストは Cursor Project のように自前で維持。
13看板は各プロジェクトごと。
14未ログインなら画面からログイン。サブスク CLI 手続きを始め URL を画面に出す。ターミナル UI は埋め込まない。API key にしない。
15エージェントとやり取りするチャット欄。やり取りするチャットを指定できる。
16pictera の PR マージ後は 3087 の API/Web を再起動する。
正本の「未決」: Claude Code 以外の実行先一覧、DeepSeek / OpenCode / HarnessRouter CE の採用、クリック UI の詳細、llm-router と外部ランタイムの接続 — いずれも決定ではない。

dsh と OpenCode の対照（ソースが言える範囲）

観点dsh（SDK クライアント）OpenCode
主な接続同一マシン上の子プロセス、stdio JSON-RPC同一プロセス内 SDK、または HTTP（opencode serve / 通常起動のサーバー）
セッションsessionId と dsh 側履歴管理HTTP /session、親子セッション、ステータス API
エージェント / ツールランタイムプロファイル・プラグインが決定（SDK は起動のみ）組み込み primary/subagent、permission、MCP、LSP 等（docs）
待ち方run() はアイドルまで；低水準 prompt() は受理のみ/message は応答待ち；prompt_async は非同期
pictera 正本SDK 例に Pictera 名あり（採用決定ではない）正本に OpenCode の記載なし → pictera との接続は欠落

両者を pictera の「自分で持つハーネス」と同一視する記述は、正本・dsh HTML・OpenCode docs のいずれにも無い。

欠落（推測で埋めないもの）

次は assigned ソースに接続の記述が無いため、本 HTML では決めない。
  • pictera ハーネスと DeepSeekHarness / dsh ランタイムの採用・配線（正本に DeepSeek 採用決定なし）
  • pictera と OpenCode サーバー / SDK の採用・配線（正本に OpenCode 記載なし）
  • Claude Code 以外の実行先一覧への DeepSeek・OpenCode・Codex を入れる決定
  • クリック対象 UI、右上ステータスと dsh session.status または OpenCode /session/status の対応
  • 常駐親エージェントと sessionId / OpenCode セッション ID の対応
  • llm-router 出力と dsh 初期化パラメータ、または OpenCode の model / agent 選択の接続。「次期」の単位
  • RunResult や OpenCode メッセージを projects / kanban / todo-list のどこに保存するか
  • HarnessRouter CE 経由で dsh や codex を呼ぶか（HR ソースは pictera 関係を欠落と書く）
  • 認証情報を dsh 子プロセス env へ渡す主体；OpenCode の /provider 認証を pictera 画面ログイン（決定 14）とどう共有するか

配置図 deepseek-harness-architecture.md が列挙する欠落（着地 URL、TypeScript / Python SDK のどちらを pictera が呼ぶか等）も、正本・dsh HTML に接続記述が無い限り残る。

出典

  1. pichtml/deepseek-harness-sdk-client-ja.html（DeepSeek Harness TypeScript SDK クライアント、確認日 2026-09-23）
  2. deepseek-harness packages/sdk/client（HTML が参照する README / ソース）
  3. Project ストア docs/project-context.md（pictera 正本・決定 9–16）
  4. Project ストア docs/deepseek-harness-architecture.md（二層・欠落一覧；本 HTML は再掲せず参照）
  5. anomalyco/opencode README.md / README.ja.md（dev @ 18ef3cc 確認）
  6. opencode.ai/docs/agents
  7. opencode.ai/docs/server
  8. OpenCode packages/client/README.md、packages/sdk-next/README.md

OpenCode の README.ja は組み込み subagent として general のみ明示する。explore / scout 等は Agents ドキュメントが正と本 HTML では docs を優先した。