iwishwp/AgentOS

AgentOS デスクトップ操作マニュアル（任意のエージェント共通）

本マニュアルは自己完結型です。あなたのフレームワークが stdio MCP サーバーをマウントできる場合（Goose / Claude Code / Z Code / Cursor 等）、 §1 に従ってマウントすれば、以下の全機能が利用可能になります。すべての項目は実機で検証済みです（Fedora + niri Wayland、 2026-10 のエンドツーエンドの証拠はリポジトリ docs/capabilities.md にあります）。

0. メンタルモデル：4 層の機能、優先順位の降順

1. L0 システム層——ウィンドウ/ワークスペース/起動/ファイル/通知/クリップボード（niri/desktop/system/files 拡張）：最も安定しており、優先的に使用します。
2. L1 アクセシビリティツリー——GUI アプリケーション内での名前ベースのクリック/テキストの読み書き（a11y 拡張、AT-SPI2）：フォーカス不要、ユーザーに干渉しません。 GTK3/GTK4/Qt で実証済み（Qt のグローバルスイッチと Chromium の toolkit-accessibility はシステムデフォルトで有効、 2026-10-18 現在）；Chromium のツリー読み取り/テキスト入力は可能（ページ内クリックは L2）；Java は未インストール（パスは capabilities.md 付録 B 参照）；純粋な X11 アプリケーション（xterm 類）にはツリーがなく、L3 のみ。
3. L2 ブラウザ CDP——Web ページの全操作（browser 拡張、エージェント専用のヘッドレス Chromium）。
4. L3 ビジュアル/入力フォールバック——grim スクリーンショット（信頼性あり）、キーボード注入（scripts/kb-inject.sh：wtype ユーザーレベルが主力、テキスト/キーの組み合わせは信頼性あり；制御キー（Enter/Tab）は ydotool にフォールバックし sudo が必要）、ポインター注入（信頼性が低い：加速度によりドリフトするため、最後の手段としてのみ使用）。

「開けない/うまく操作できない」アプリケーションに遭遇した場合：まず L1 の前提条件が満たされているか（a11y スイッチ）を考え、次に L3 のスクリーンショットで実際の状態を確認し、盲目的にリトライしないでください。

1. マウント（1 回限り）

goose（~/.config/goose/config.yaml、1.54 で検証済みの形式；name: フィールドは必須、これがないと拡張全体が静かに破棄されます）：

extensions:
  niri:
    type: stdio
    name: niri
    enabled: true
    cmd: /path/to/AgentOS/scripts/env/with-niri-env.sh
    args: []
    env_keys: []
    envs: {}
    timeout: 300          # 単位：秒
  # desktop/system/files/session/a11y/browser/cred も同様に、
  # cmd はそれぞれ with-desktop-env.sh / with-system-env.sh / ... を使用（scripts/env/ 下の 8 つのランチャー）

その他のフレームワーク（Claude Code / Z Code 等の mcpServers JSON 形式）：

{
  "mcpServers": {
    "niri":    { "command": "/path/to/AgentOS/scripts/env/with-niri-env.sh" },
    "desktop": { "command": "/path/to/AgentOS/scripts/env/with-desktop-env.sh" },
    "system":  { "command": "/path/to/AgentOS/scripts/env/with-system-env.sh" },
    "files":   { "command": "/path/to/AgentOS/scripts/env/with-files-env.sh" },
    "session": { "command": "/path/to/AgentOS/scripts/env/with-session-env.sh" },
    "a11y":    { "command": "/path/to/AgentOS/scripts/env/with-atspi-env.sh" },
    "browser": { "command": "/path/to/AgentOS/scripts/env/with-browser-env.sh" },
    "cred":    { "command": "/path/to/AgentOS/scripts/env/with-cred-env.sh" }
  }
}

要点：

• ランチャースクリプトを使用してください。node dist/index.js を直接指定しないでください——ランチャーは niri IPC ソケット （パスに compositor PID が含まれ、セッションごとに異なります。例：/run/user/1000/niri.wayland-1.2762.sock）を自動検出し、 Wayland/dbus 環境（XDG_RUNTIME_DIR/WAYLAND_DISPLAY/DBUS_SESSION_BUS_ADDRESS）を補完します。 SSH/サービス環境から起動した場合でもツールが使用可能になります。
• ランチャーの手動テスト：timeout 2 scripts/env/with-niri-env.sh </dev/null、exit 0 で正常。
• 前提条件：Node ≥ 20、リポジトリで npm install && npm run build が実行済み、niri グラフィカルセッションのユーザーとして実行されていること。

2. ツールクイックリファレンス（拡張グループ別、ツール名 = <拡張>__<ツール>）

niri —— ウィンドウ/ワークスペース/起動（L0）

ツール	用途	主要パラメータ
list_windows	全ウィンドウを一覧表示（id/app_id/タイトル/ワークスペース/フォーカス）	—
list_workspaces	ワークスペースを一覧表示（idx は id とは別物です、move には番号または名前を使用）	—
list_outputs	ディスプレイを一覧表示	—
focus_window	前面フォーカスを切り替え（ユーザーのビューを切り替えるため、注意して使用）	id
focus_workspace	ワークスペースを切り替え（ユーザーのビューを切り替える）	reference: "3" または名前
move_window_to_workspace	ウィンドウを移動（フォーカスを奪わない、整理用）	id?（デフォルト=フォーカス中のウィンドウ）、reference
close_window	ウィンドウを閉じる	id?
open_app	ユーザーデスクトップでアプリケーションを起動	command: 配列、例：["ghostty"]

a11y —— GUI アプリケーション内操作（L1、AT-SPI2）

ツール	用途	主要パラメータ
a11y_list_apps	アクセシビリティバスに登録されているアプリケーションを一覧表示	—
a11y_dump_tree	特定のアプリケーションのアクセシビリティツリーをダンプ（ボタン名/構造を見つけるため）	app
a11y_click	アクセシブルな名前でクリック（フォーカス不要、ユーザーに干渉しない）	app、buttonName
a11y_read_texts	アプリケーションのすべての空でないテキストを読み取り（ディスプレイ/結果/ラベル）	app
a11y_set_text	ノード名でテキストボックスに書き込み	app、match（名前の部分文字列、デフォルト * で最初のもの）、text

実証済みの規律：名前でアドレス指定し、ツリーインデックスは使用しないでください（ツリー構造は AT 接続をまたぐと再構築されます）；GTK4 のツリーは AT クライアントが登録されるまで完全になりません；同名の複数インスタンスがある場合、ブリッジは最初に登録された方を解決します——テキストを読み取ってインスタンスを識別し、必要に応じて余分なインスタンスを閉じてください。 Chromium の注意点：ツリーは遅延構築されます（ブリッジが自動的にトリガー、初回ダンプでは 1-2 秒の待機が正常です）；テキストボックスへの書き込みは「grabFocus + kb-inject type」の組み合わせを使用します（Chromium の entry は setTextContents を受け付けません）；ページ内のボタンクリックは機能しません（doAction はディスパッチされますが、onclick は実行されません）。ページ操作はすべて browser 拡張を使用してください。

browser —— Web ページ操作（L2、エージェント専用ヘッドレス Chromium）

ツール	用途	主要パラメータ
browser_open	ナビゲーション（初回呼び出しで自動的にブラウザが起動）	url
browser_eval	ページ内で JS を実行、フォーム入力/クリック/コンテンツ読み取りはこれで行う	JS コード
browser_screenshot	スクリーンショット（ブラウザはヘッドレス、視覚情報はこれに依存）	—

フォーム入力の標準的な手順：el.value = "..." の後に必ず el.dispatchEvent(new Event("input", {bubbles: true})) を実行してください。 そうしないと、モダンなフレームワークは入力を受け取りません。CAPTCHA に遭遇した場合：処理を停止しユーザーに通知、自動的にバイパスしないでください。

files —— ファイルサンドボックス（L0、ルート = ~/Agent/、パスは相対パスで記述）

ツール	用途	主要パラメータ
read_file / write_file	テキストファイルの読み書き（親ディレクトリを自動作成）	path、content
list_dir / create_dir	ディレクトリの一覧表示/作成	path
move / delete	移動 / 削除（.trash に移動され復元可能、シェルの rm は使用しないでください）	source/dest、path
find_by_name	名前でファイルを検索	pattern
download	http(s) ダウンロードをサンドボックスに保存（≤50MB / 60s、シェルの curl は使用しないでください）	url、path

desktop —— 表示/通知/クリップボード/確認（L0）

ツール	用途	主要パラメータ
open	成果物を開く：URL またはファイル；Office 文書は必ず app: "libreoffice" を指定してください（ホワイトリスト、システムの MIME 関連付けは信頼できません）	target、app?
notify	デスクトップ通知（3 段階については §3 参照）	summary（必須）、body、urgency、action?
confirm	ユーザーへの確認/意思決定依頼（T1 は 4 つのバナー：許可/セッション許可/拒否/永久拒否、30 秒無応答＝拒否）	summary（機密情報は入れない）、tier?（t1/t2、文言に影響）
clipboard_read / clipboard_write	クリップボードの読み書き	—

session —— 水族館（エージェント専用のネストされた niri セッション、GUI 作業はすべてここで行う）

ツール	用途
agent_session_start / agent_session_stop / agent_session_status	ネストされたセッションのライフサイクル（デスクトップ上に監視可能なウィンドウが表示されます）
agent_open_app	水族館内でアプリケーションを起動（例：gnome-calculator、chromium）
agent_list_windows	水族館内のウィンドウを一覧表示
agent_screenshot	水族館内部のスクリーンショットを撮影（grim）

system —— システムクエリ（L0 読み取り専用はすべて許可）

system_status / list_services / service_status / journal / network_info / list_packages / package_info / package_install（T2 強確認：polkit パスワードダイアログが表示され、ユーザーの操作が必要； ヘッドレス実行時は 300 秒でタイムアウトし拒否——無人実行時には呼び出さないでください）。

cred —— 資格情報（エージェントは参照を取得し、プレーンテキストは取得しない）

cred_list（利用可能な資格情報とその参照/env 変数名）· cred_autofill（チャネル A：ページ自動入力、プレーンテキストは即座に破棄）· cred_exec（チャネル B：ホワイトリストによる代理実行＋出力のマスキング）· cred_inject（チャネル C：短い TTL の環境変数注入、 期限が来たら一括クリア）。パスワード/トークンが必要な操作はすべて cred 経由でのみ行い、ユーザーにプレーンテキストを要求しないでください。

3. 動作規定（実証済みの効果的な規律）

1. 成果物はすべて ~/Agent/ に配置し、downloads/ inbox/ reports/ notes/ canvas/ screenshots/ で分類します。 配置されると自動的にアーティファクトインデックス（http://127.0.0.1:7788/artifacts）に追加されます。ユーザーが「前回のレポートはどこ？」と尋ねたら → そのページを開くか、相対パスを報告します。
2. 表示の優先順位：ダッシュボード/レポート/インタラクティブコンテンツ → 自己完結型の単一ファイル HTML を canvas/<名>/index.html に書き込み、 次に open で http://127.0.0.1:7788/<名>/ を開きます；Office 文書 → open に app: "libreoffice" を指定； Web ページ → browser 拡張。
3. 通知の 3 段階：完了 → notify urgency=low + action（{kind:"open_path", path:"reports/x.fodt"} または {kind:"open_url", url:...}、通知をクリックすると成果物に直接移動）；失敗/早急な確認が必要 → urgency=critical + 結論 + 原因の提案；ユーザーの意思決定が必要 → notify は使用せず、confirm を使用します（notify には選択の意味がありません）。 非同期の結果はすべて通知し、黙って完了しないでください。
4. 確認と節度：明示的に要求されない限り、ユーザーが使用中のウィンドウを操作しないでください（最初に list_windows で対象を確認します）； ポリシー拒否（isError で「ポリシー拒否」と表示）の場合は、その旨を正直に伝え、回避しようとしないでください；GUI 操作は水族館内で行い、 ユーザーのフォーカスを奪いません。
5. 資格情報は cred-mcp 参照のみを使用します（§2 cred テーブルの後の規律）。

4. 環境の落とし穴クイックリファレンス（すべて経験済み）

落とし穴	現象	対処
niri IPC ソケットパスがセッションごとに変わる	niri msg が接続できない	ランチャーを使用する（自動的に NIRI_SOCKET を検出）、ハードコードしない
Chromium のキーチェーンがネットワークサービスをロック	ブラウザ起動時にハング	--password-store=basic を付けて起動する（browser 拡張は既に内蔵；自分で chromium を起動する場合は忘れずに付ける）
soffice のシングルインスタンスロック	既に LibreOffice が開いている状態で同種の文書を開こうとすると、ウィンドウが表示されない/ハングする可能性がある	最初に soffice プロセスの状態を確認；文書を開くには app:"libreoffice" を使用してランチャーセマンティクスで実行；前回の異常終了時に「ドキュメント回復」ダイアログが表示されることがある（2026-10-18 実測）、ウィンドウ一覧を確認する際にそれを目的の文書ウィンドウと誤認しないこと
LibreOffice の MIME 関連付けが信頼できない	Fedora が fodt を text/xml として認識し、エディタで開く	open には必ず app:"libreoffice" を指定する
Qt アプリケーションが a11y バスに表示されない	a11y_list_apps で見つからない	システム全体で有効になっている（/etc/environment の QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1、再起動後も持続）；それでも表示されない場合は、アプリケーションが環境設定より前に起動されたか、非公式の Qt バインディングである可能性があるため、アプリケーションを再起動する
Chromium/Electron の a11y ツリーが空	dump してもコンテンツが出ない	① --force-renderer-accessibility を付けて起動する（browser 拡張はデフォルトで有効）；② toolkit-accessibility はアプリケーション起動前に true である必要がある（システム全体で有効；後から変更しても効果なし、アプリケーションの再起動が必要）；③ ツリーは遅延構築されるため、一度 dump してブリッジをトリガーする（§2 a11y 規律参照）
キーボード注入の選択	タイピング/ショートカットキーが必要	scripts/kb-inject.sh：テキストとキーの組み合わせには wtype（ユーザーレベル）を使用；Enter/Tab などの制御キーは wtype が GTK で機能しないため、ydotool（sudo）を使用；中国語は先頭文字が欠落する可能性があるため、入力後 a11y ツリーから読み戻して確認する
水族館初期に niri ホットキーオーバーレイが表示される	スクリーンショットが「Important Hotkeys」で隠れる	Esc を注入して閉じる；エージェントサンドボックス内では ydotoold ソケット（root 600）に接続できないため、niri__open_app を借りて実際のデスクトップ環境で注入を実行する
ydotool ポインターのドリフト	絶対位置の精度が低い（libinput 加速度 ≈0.5）	ポインターは信頼できない；キーボード注入は信頼性あり；ソケットパスは /tmp/.ydotool_socket と $XDG_RUNTIME_DIR のバージョン違いに注意
GTK4 ツリーが初期に不完全	dump してもノードが十数個しかない	最初に a11y_list_apps/dump を一度実行して AT クライアントを登録し、再度 dump すると完全になる（実測で 16→105 ノード）
ヘッドレス実行時の T1/T2 確認	30 秒/300 秒で無人応答のため自動拒否	想定される動作：書き込み操作にはユーザーの存在が必要。またはテスト時は org.agentos.Confirm1.Respond を介してプログラムで応答する
パッケージインストール時に packagekitd がロックを奪う	dnf が偶発的に失敗する	インストール前に systemctl stop packagekit を実行する（T2 helper が既に処理済み）

5. アップグレードパス（対象アプリケーションが開けない場合の順次試行）

L0（システム層、常に最初に試す）→ L1（a11y：GTK3/4/Qt はデフォルトで到達可能；Chromium はフラグと toolkit-accessibility の順序を確認；サードパーティ Electron は capabilities.md 付録 B に従ってフラグを追加）→ L2（Web ページ系は必ず通る）→ L3 フォールバック（grim で確認 + kb-inject キーボード；ポインターは信頼できない）。 それでも開けないタイプ：純粋な X11 アプリケーション（xterm 類、ツリーなし、L3 が終点）、Java（JAB が必要、パスは capabilities.md 付録 B 参照）、コンポジター自身の UI（入力注入のみ）——詳細な表はリポジトリ docs/capabilities.md を参照。