作業場所と会話状態を同じフォルダーに置いたまま、DeepSeek HarnessのPython処理を常駐させている。
最短の解決策は、まず破棄できる作業場所で単一タスクを確認し、SDKと実行環境を固定してから、独立したsession_rootと復旧手順を追加することです。ローカル開発フォルダーをそのままクラウドMacへコピーして長期運用する方法は避けてください。
この記事を読むべき人
PythonからDeepSeek Harnessのコード作業を繰り返し実行する自動化開発者向けです。 クラウドMacで会話状態を維持しながらAgentを動かしたいプラットフォーム担当者や、納品環境が再起動後に戻れるか確認する責任者にも適しています。
最初に押さえるのは、Python SDKが入ることと、継続運用できることは別問題だという点です。公式リポジトリではPythonライブラリの配布経路、事前構築済みランタイム、macOS arm64対応が案内されていますが、常駐プロセス、権限、ログ保存、バックアップまでSDKが自動で設計してくれるわけではありません。導入時点では開発者プレビューとして破壊的変更の可能性も残るため、実施日ごとに公式READMEの状態と配布名を再確認してください。
開始前：実行形態を一つに決める
同じコードでも、単発スクリプト、定時ジョブ、長時間Agentでは必要な設計が異なります。単発なら作業場所を毎回作り直せますが、連続タスクでは会話状態、Bashの状態、ログの保存方針が必要です。
| 運用形態 | 作業場所 | セッション方針 | プロセス責任 |
|---|---|---|---|
| 単発スクリプト | 毎回破棄できる一時ディレクトリ | 新しいID | 呼び出し元が開始・終了を管理 |
| 定時タスク | ジョブ専用ディレクトリ | ジョブ単位で分離 | スケジューラーがタイムアウトを管理 |
| 長期Agent | プロジェクトごとに固定 | 継続作業だけ同じIDを再利用 | 外部の実行管理が再起動とログを担当 |
pip install deepseek-harnessが示され、CLI版とは配布物が分かれています。[PythonライブラリとCLIの対応表](https://github.com/HenryZ838978/deepseek-harness/blob/main/docs/technical_report.md)を確認し、Pythonから呼び出す処理へCLI用パッケージを混ぜないでください。公式APIのPython例はOpenAI SDK互換の呼び出しを前提にしているため、モデル端点、APIキー、SDKの組み合わせを一枚の記録に残します。[DeepSeekのPython API例](https://api-docs.deepseek.com/api_samples/chat_python)も導入前に確認できます。
| 確認項目 | 合格条件 | 不合格時の戻り先 |
|---|---|---|
| CPUアーキテクチャ | arm64など公式対応範囲に一致 | 互換性を確認できるMacへ変更 |
| Python | 公式ガイドが要求する範囲に一致 | 指定版で仮想環境を作り直す |
| 配布物 | Python SDKと捆包ランタイムを同じ記録で管理 | CLIやソース構築用手順を混在させない |
| モデル端点 | 接続先とモデル名を明示できる | 最小リクエストへ戻る |
| 作業場所 | 実行対象を一つの絶対パスで示せる | リポジトリを再配置して再確認 |
arm64の扱いが互換性確認の要点になります。[Apple siliconの移行資料](https://developer.apple.com/documentation/Apple-Silicon/porting-your-macos-apps-to-apple-silicon)を参照し、uname -mの結果を納品記録へ含めてください。
第1段階：最小の隔離環境だけを作る
最初から実際のリポジトリ、書き込み権限、長期セッションを渡すと、SDKの問題と権限設定の問題を分離できません。Pythonのvenvは実行したPython版を基準に環境を作るため、システムPythonの確認後に実行します。Python公式の仮想環境手順に沿って、次のように構成します。
mkdir -p "$HOME/dsh-run"/{app,work,sessions,logs}
cd "$HOME/dsh-run/app"
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install deepseek-harness
python --version
python -m pip show deepseek-harness
uname -m
sw_versここで記録するのは、Pythonの実行版、SDKの表示版、macOS版、CPUアーキテクチャ、インストール元です。執筆時点で確認できる公開READMEにはPythonライブラリの版として0.2.0が記載されていますが、公開版は変わり得るため、固定値として採用する前に実行環境でpip showを確認してください。公開READMEの配布情報と一致しない場合は、ロックファイルを作成せず先へ進まない方が安全です。
DeepSeek Harness Python SDKをMacで使う場合、Node.jsは必須ですか。 Pythonライブラリの事前構築済みランタイムを使う構成では、システムへNode.jsを別途導入しなくても進められると案内されています。ただし、MCP用パッケージやソース構築経路を併用する場合は別の依存関係が発生するため、「Python SDKだから常にNode.js不要」と一般化してはいけません。導入経路を一つに絞り、最初はPythonパッケージだけで起動確認します。
成功信号は、SDKをimportでき、最小処理が正常終了し、終了後にプロセスが残っていないことです。importで失敗したらAPIキーや実リポジトリを追加せず、Python版と配布物の組み合わせまで戻して環境を作り直します。
第2段階：捨てられる作業場所で三つを確認する
次に、空の検証用リポジトリをworkへ置き、モデル応答、ファイル操作、Bash実行を別々に確認します。1回の大きな指示で全機能を試すと、どこで失敗したのか証拠が残りません。
作業記録には、少なくとも次の四項目を残します。
- 入力したタスク文。
- 使用した作業場所の絶対パス。
- 最終応答または終了状態。
- 実際に作成・変更されたファイルとBashの終了結果。
git diffまたはハッシュで変化を確認します。Bashでは、許可されたコマンドだけを実行する専用作業場所を使い、終了コードと標準出力をログへ保存します。プロセスをPythonから管理する場合、シェル呼び出しの扱いはPythonの[subprocess公式資料](https://docs.python.org/3/library/subprocess.html)に合わせ、入力値をそのままシェルへ連結しないでください。
モデル応答だけ成功してファイル操作が失敗する場合は権限またはcwdの問題です。ファイル操作だけ成功して会話が継続しない場合は、会話状態の保存設計をまだ追加していない可能性があります。最小例へ戻し、三つの確認を一つずつ繰り返します。
第3段階：cwd、session_root、session idを分離する
cwdはそのタスクで相対パスを解決する作業場所です。session_rootは会話や実行状態を保存する場所であり、リポジトリそのものと同じにしない方が、バックアップ範囲とアクセス権を分けやすくなります。セッションIDは保存された状態を識別する名前として扱い、プロジェクト名や秘密情報をそのまま含めないでください。
Python SDKのsession_rootはどこに置くべきですか。
通常は、コード用のapp、実行対象のwork、状態用のsessions、監査用のlogsを同じ親ディレクトリの下で分離します。たとえば$HOME/dsh-run/sessionsのような専用ディレクトリです。作業場所を削除しても状態を残すのか、状態も一緒に破棄するのかを先に決め、バックアップ対象を曖昧にしないでください。
同じsession idで別プロセスから続行できますか。
保存形式とSDKの対応範囲が一致し、同じsession_rootを読み取れるなら、別プロセスで同じセッションを開く設計は可能です。ただし、同じIDを同時に二つのプロセスで開くと、会話履歴だけでなく持続中のBash状態や書き込み順序が競合するおそれがあります。新しい仕事は新しいID、同じ仕事の継続だけ既存IDという運用規則にしてください。
JSON-RPC経由の呼び出しを外側の管理プロセスへ追加する場合も、JSON-RPCのIDと内部セッションIDを同一視しないでください。前者は要求と応答を対応付ける値、後者は作業状態を選ぶ値です。タイムアウト後に同じ要求を再送するなら、重複実行を防ぐジョブIDを別に持たせます。
第4段階：資格情報とプロセス責任を追加する
APIキーは環境変数、または所有者と権限を管理できる資格情報ファイルから読み込みます。リポジトリ、セッションログ、シェル履歴、起動スクリプト本文へ直接書かないでください。ログを共有する場合は、要求本文、環境変数、認証ヘッダーのマスキングを先に確認します。
ここで必要なのは、SDKの機能一覧ではなく運用担当の割り当てです。
- 起動担当：手動起動か、外部スケジューラーか。
- 停止担当：通常終了、強制終了、タイムアウトの扱い。
- ログ担当：保存期間、容量上限、ローテーション。
- 復旧担当：プロセス終了、接続断、Mac再起動後の再開方法。
- 重複防止担当：同じジョブを再実行してよい条件。
第5段階：再起動と切り戻しを合格させる
正式な作業場所を接続する前に、次のチェックを実行します。
- [ ] 実行前にSDK版、Python版、macOS版、
uname -mを保存した。 - [ ]
cwdを絶対パスで記録し、想定外の親ディレクトリへ移動していない。 - [ ]
session_rootをリポジトリ外へ分離した。 - [ ] 新規タスクでは新しいセッションIDを発行した。
- [ ] 同じ要求を再送しても重複変更しない仕組みを確認した。
- [ ] APIキーがログ、履歴、リポジトリに残っていない。
- [ ] プロセスを終了させた後、状態とログを読み取れた。
- [ ] SSHや画面接続が切れても、処理状態を確認できた。
- [ ] Macを再起動した後、同じ作業場所とセッションを指定できた。
- [ ] 失敗時に旧SDK、旧仮想環境、旧状態バックアップへ戻せる。
reasoning_contentの保持やストリーミング処理などが含まれますが、ホスト再起動後のジョブ再開を保証するものではありません。[契約仕様の説明](https://github.com/HenryZ838978/deepseek-harness/blob/main/spec/01_reasoning_content.md)と運用上の復旧責任を分けて記録してください。
なお、公開READMEには10項目の契約ルール、Python版を含む4形式の配布、コンテキスト上限1,048,576トークンが記載されています。これらはSDKや仕様の確認材料にはなりますが、あなたのクラウドMacでの処理時間、同時実行数、月額費用を意味しません。性能や料金を見積もる場合は、実際の契約プランと自分のタスクログを別途使う必要があります。
クラウドMacを選ぶときの判定
自宅Macや社内端末で短時間の検証だけを行うなら、常時稼働の費用や遠隔接続の管理は不要です。一方、接続断後も状態を確認したい、作業場所を固定したい、複数の担当者が同じ環境を引き継ぐ必要があるなら、クラウドMacの方が運用境界を作りやすくなります。
ただし、物理USB機器、社内ネットワーク内だけで利用できる資産、長期間の高負荷を固定費で運用する要件がある場合は、自前のMacや専用設備が適することもあります。まずはMACGPUのクラウドMac案内で利用形態を確認し、必要な期間だけ借りるのか、継続利用を前提にするのかを分けて検討してください。地域や端末候補を比較する場合は、Macの利用地域を選ぶための案内も参照できます。
ローカル開発ディレクトリを丸ごと移す方法は、秘密情報の混入、不要な依存関係、誤ったcwd、古いセッションの持ち込みという欠点があります。クラウドMacへ必要なコード、仮想環境の再生成手順、作業場所、状態ディレクトリ、復旧記録だけを分けて移す方が、DeepSeek Harness Python SDKの導入後に原因を追いやすくなります。単発の検証や短期の評価環境が目的なら、必要な期間だけMACGPUのレンタル環境を使い、上のチェックリストで復旧まで確認してから継続利用へ進むのが現実的です。
最終更新：2026年8月18日。配布名、Python SDKの導入経路、macOS arm64対応、事前構築済みランタイムの扱いは、同日に確認した公開README、仕様資料、Python公式資料、Apple公式資料を基準にしています。 v0.2.0などの公開版表記は更新される可能性があるため、実際の導入日には必ず再確認してください。