duoduo-admin

Duoduo Admin

Duoduo の全体像をまだ把握できていないユーザー向けに、ホストモードのエントリーポイントとしてこのスキルを使用します。

まず状況を確認する

1. duoduo daemon status でデーモンが起動していることを確認します。
2. 永続的な変更を行う前に duoduo daemon config を読みます。この出力をパスと有効な設定の正として扱います。
3. デーモンが停止している場合は、まずデーモンから対応します。マシンがまだオンボーディングされていない場合は、まずユーザーに duoduo のオンボーディングを完了する必要があることを説明します。
4. ユーザーから何かが壊れていると言われた場合は、まずローカルの設定ミス、オペレーターの操作ミス、チャネル／プラグインのセットアップエラー、Duoduo 製品のバグの可能性のいずれかを判断します。

ホストモードの用語で Duoduo を説明する

具体的に、ファイルシステムを中心に説明します。

• オンボーディング後、stdio はデフォルトの直接的なオペレーター向けインターフェースです。
• duoduo daemon ... は、長時間稼働するランタイムプロセスを管理します。
• duoduo channel ... は、インストール可能な外部チャネルプラグインを管理します。
• ~/.config/duoduo/.env は、ホストモードの永続的な設定ファイルです。
• kernel/config/<kind>.md には、チャネル種別ごとのデフォルト設定と種別プロンプトが保存されます。
• var/channels/<channel_id>/descriptor.md には、チャネルインスタンスごとの上書き設定とインスタンスプロンプトが保存されます。
• ホストデーモンは、切り離されたバックグラウンドプロセスです。パッケージファイルを更新しただけでは、実行中のプロセスは置き換わりません。
• 同じ実際のワークスペースパスから duoduo を再度開くと、新しい会話インターフェースを作成する代わりに、同じ stdio セッションキーに再接続します。

これらのインターフェースがどのように連携するかについて、詳しい説明が必要な場合は references/host-mode-map.md をお読みください。

アップグレードと再起動

「アップデートはありますか？」と聞かれたら、両方を確認します。

duoduo --version
npm view @openduo/duoduo version

duoduo --version がバージョンを表示せず、デーモンの WebSocket エラーで終了する場合、答えは「はい」です。この失敗は v0.8.1 までのすべてのビルドに存在するバグであり、アップグレードで解消します。その間は duoduo daemon status からインストール済みバージョンを確認してください。同じバージョン番号が表示され、失敗する経路を通りません。

標準的なアップグレード手順（同じメジャーバージョン内のマイナーアップデートで使用できます）：

npm install -g @openduo/duoduo@latest
duoduo daemon restart -r "upgraded @openduo/duoduo to <version>"

新しいビルドでは、両方の手順を1つのコマンドにまとめています。このコマンドは、実行中のバイナリを所有するプレフィックスにもインストールします（npm install -g を実行しただけでは、そこにインストールされない場合があります）。また、再起動の理由を自動的に指定し、新しいデーモンのヘルスチェックも行います。

duoduo upgrade [version] [--wake <session-or-alias>]

バージョン番号ではなく、CLI 自体から利用可能かどうかを確認してください。この動作が利用可能な場合に限り、duoduo --help のアップグレードの説明に --wake が表示されます。古いビルドの duoduo upgrade はバージョンしか受け取らず、上記の処理も行いません。その場合は、2つのコマンドを使う形式を使用してください。

デーモンは切り離されたバックグラウンドプロセスであるため、再起動が必要です。新しい CLI パッケージをインストールしても、デーモンはホットスワップされません。

これらのスキルはアップグレードに含まれません。 npm パッケージではなく GitHub リポジトリから提供されるため、どちらのアップグレード手順でもスキルは更新されません。そのため、新しい CLI を古い手順のまま操作することになります。バージョンが変わるたびに、スキルの更新を提案してください。

npx -y skills add https://github.com/openduo/duoduo --global --all

提案は行いますが、黙って実行しないでください。非対話型環境や SSH に関する注意点については、 references/upgrade-playbook.md を参照してください。

-r の理由は、再起動後に起動されるすべてのセッションに通知されます。これを指定しないと、再起動によって応答の途中でターンが中断されたセッションは、会話がなぜ途中で止まったのかを知る手段がありません。通常は、誰かに会話を中断されたと判断します。セッションが回答を待っていた場合は、--wake <session-or-alias> を追加してください（繰り返し指定できます）。セッションは自動では再開されません。呼び出し元が、再起動されるデーモン内のセッションである場合も同様です。ウェイク指示は再起動そのものによって引き継がれるため、古いデーモンとともに呼び出し元のプロセスが終了しても維持されます。

大きな境界をまたぐアップグレード（v0.5 を含む）

アップグレードによって動作上の境界をまたぐ場合（v0.5 では Feishu のメインセッションのセマンティクスと、DM に対する新しい信頼モデルが追加されています）は、上記の一行コマンドではなく、完全な手順に従ってください。

references/upgrade-playbook.md をお読みください。

手順の分岐に必要な情報を収集するには、事前チェックを実行してください。

bash scripts/v05-upgrade-preflight.sh

スクリプトは、インストール済みバージョン、デーモンの状態、チャネルの一覧、Feishu の環境変数キー、ディスクリプターの形式を記載した Markdown を出力し、Branch B／C／D のいずれかを推奨します。これは作業を効率化するためのものであり、必須の手順ではありません。スクリプトを実行できない場合や、環境が一般的でない場合は、手順の Step 1 にある代替手順で、スクリプトが実行するすべての確認を個別のコマンドとして実行し、エージェントが手動で再現できます。

自動化で把握しておくべきインターフェース

エージェントや自動化が duoduo と連携する際に、これらのインターフェースが重要になります。 通常の duoduo の対話利用では、いずれも必要ありません。

• duoduo onboard：ウィザードを実行して終了する専用サブコマンドです（チャット REPL には移行しません）。自動化やエージェントから呼び出す場合は、これをエントリーポイントとして使用してください。非 TTY 環境では、プロンプトを表示する代わりに、環境変数（少なくとも ALADUO_RUNTIME_MODE、ALADUO_CLAUDE_AUTH_SOURCE）から回答を読み取ります。これらが設定されていない場合は、終了コード 2 で終了し、環境変数の設定手順全体を stderr に出力します。推測で補わず、その手順を呼び出し元に転送してください。
• DUODUO_NODE_BIN 環境変数：設定すると、duoduo bash ラッパーは PATH から node を解決せず、指定された絶対パスを使用します。エージェントの起動時の bash -lc や、独自の Node ランタイムを同梱する GUI マネージャーなど、呼び出し元の環境で PATH がリセットされる場合に使用してください。詳しい理由は openduo/duoduo#50 を参照してください。
• ユーザーに表示されるドレインエラー：デーモンの内部 SDK ターンが失敗した場合（最も一般的なのは、Claude Code の現在のワイヤースキーマに対応していないサードパーティの互換エンドポイントです）、ユーザーには無応答ではなく、[duoduo:drain-error] で始まるテキストの返信が表示されます。このメッセージには元のエラーが記載され、一般的な回避策として ~/.config/duoduo/.env に DISABLE_ADAPTIVE=1 DISABLE_THINKING=1 DISABLE_INTERLEAVED_THINKING=1 MAX_THINKING_TOKENS=0 を設定するよう案内されます。
• duoduo session archive <session_key>：1 回の呼び出しで、1 つのセッションの永続アーティファクトすべて（セッションディレクトリ、受信スナップショット、送信ボックスのレコード、チャネル記述子）をアーカイブします。「アーカイブ」は文字どおりの意味です。何も削除されず、すべて var/<kind>-archive/ に移動され、オペレーターは mv で元に戻せます。対象に実行中のアクターがある場合は拒否されるため、先に /cancel でキャンセルしてください。ダッシュボードにもう存在すべきではないセッションが表示されている場合（チャネルのリセット後など）や、ランタイムの残りには触れず、特定のセッションだけを初期状態に戻したい場合に適したツールです。duoduo-channel-admin の reset-feishu-session.sh スクリプトはこの CLI を使用します。チャネルごとにまとめてアーカイブする必要がある場合は、実例としてこのスクリプトを参照してください。
• ランタイムの選択：Claude、Codex、Grok、Pi は対等なランタイムです。ランタイムが宣言されていない場合、Claude がデフォルトになります。duoduo が認識しないランタイムが宣言されている場合は、フォールバックで置き換えずに拒否されます。Codex と Grok（runtime: codex|grok または ALADUO_DEFAULT_RUNTIME）には暗黙の Claude フォールバックはありません。CLI をインストールしてログインしてください。ランタイムが利用できない場合はターンが拒否されますが、修正後にメッセージを再送するだけで十分です。Pi は duoduo に同梱されており（インストール不要で、常に利用可能）、同様に暗黙のフォールバックはありません。すべての Pi セッションにはモデルポインター（ジョブのフロントマター、/model、またはパーティションのフロントマターで指定する provider/modelId）が必要で、指定されていない場合は具体的な対処方法とともに失敗します。意図的にグローバルのデフォルトを変更する場合に限り、ALADUO_DEFAULT_RUNTIME=codex、=grok、または =pi を使用してください。セッションは、その会話を所有するランタイムに紐付けられています。ランタイムだけを変更すると、次のターンは拒否されます。先に /clear を実行してからランタイムを変更してください。詳しくは duoduo-runtime-admin の「セッションのランタイムを切り替える」を参照してください。
• 標準入出力のバッファリング：ターミナル UI ではアシスタントのテキストがより適切にバッファリングされるため、ステータスやツールの表示がアシスタントの文章と混在する様子が目立ちにくくなります。これは UX の改善であり、プロトコルの変更ではありません。

問題を特定してエスカレーションする

ユーザーがバグや予期しない動作を報告している場合：

1. 症状を再現するか、少なくとも正確な症状を言い換えて確認します。
2. 必要最小限のコマンドを使って現在の状態を調べます。通常は duoduo daemon status、duoduo daemon config、duoduo daemon logs と、 関連する duoduo channel ... status/logs を使用します。
3. ローカルのセットアップミスと、製品側の不具合と思われるものを区別します。
4. duoduo のバグまたはドキュメントの不備と思われる場合は、公開しても問題のない内容で openduo/duoduo 向けの課題の概要を作成します。

ユーザーが課題を報告したい場合、または報告文の作成を依頼した場合は、 references/issue-reporting.md を読んでください。

リクエストを適切なワークフローに振り分ける

• チャネルのインストール、チャネルのライフサイクル、Feishu のセットアップ、またはチャネルの プロンプト／ワークスペースの変更： ../duoduo-channel-admin/SKILL.md を読み、 そのワークフローに実装を任せます。
• Codex、デバッグログ、テレメトリー、実行間隔、デーモンの診断などのランタイムフラグ： ../duoduo-runtime-admin/SKILL.md を読み、 そのワークフローに実装を任せます。
• 公開エスカレーションが必要な、確認済みのバグ報告またはドキュメントの不備： references/issue-reporting.md を使用します。
• 複数の内容が混在するリクエストや曖昧なリクエスト： まず仕組みを説明してから、最小限の具体的な変更に進みます。

運用ルール

• デフォルト設定よりも実際の状態を優先して調べます。システムの設定について述べる前に、実際のデーモン設定、 実際のファイル、実際のチャネル一覧を確認します。
• ~/.config/duoduo/.env を編集した後は、ユーザーが明示的に編集のみを依頼した場合を除き、 duoduo daemon restart -r "changed <setting>" を実行するよう伝えます。理由は中断されたセッションに何が起きたのかを伝えるため、引数なしの restart を決して提案しないでください。
• ユーザーから「duoduo について理解したい」と頼まれた場合は、抽象的なアーキテクチャ用語ではなく、ファイル、 コマンド、ライフサイクルに沿って回答します。
• 生の Git リポジトリをチャネルプラグインとしてインストールできるかのように説明してはいけません。 Duoduo のチャネルインストーラーが受け付けるのは npm パッケージ指定（フラグなし）またはローカルの .tgz アーカイブ（明示的な --from-path フラグが必要）です。