# Secure Local AI Agent

## Generated Project Image

![Generated project setup image](docs/assets/generated-readme-hero.png)

This image is generated by the automation harness during repository creation so the README contains a real visual asset, not only image-generation instructions.

![Architecture](docs/assets/architecture.svg)

Custom GPT、ChatGPT Developer Mode、Codex などから、**自分の Windows PC 上の Chrome・許可フォルダ・許可アプリだけ**を操作するための安全重視の実行基盤です。

- 公開ダッシュボード: https://secure-local-ai-agent.pages.dev
- GitHub Actions: https://github.com/univcorp2-ctrl/secure-local-ai-agent/actions

> 重要: クラウド側だけではローカルPCを操作できません。本リポジトリのローカルエージェントを対象PCへ導入し、Cloudflare Gateway と共有鍵で接続します。任意の PowerShell / CMD 実行は公開しません。

## できること

- Playwright で専用 Chrome プロファイルを操作
- 指定ルート配下だけファイルを読取・作成・一覧化
- pywinauto で許可済み Windows アプリと既知 UI 要素を操作
- Custom GPT Actions（OpenAPI）と Remote MCP の両方からタスク投入
- Cloudflare D1 にタスク・結果・監査状態を保存
- 危険操作を `awaiting_approval` に停止
- ローカル側は外向き HTTPS ポーリングのみ。受信用ポート開放不要
- 公開ダッシュボードから接続確認とタスク状態確認

## 構成

```mermaid
flowchart LR
  GPT[Custom GPT / ChatGPT / Codex] -->|HTTPS + Bearer| CF[Cloudflare Worker]
  CF --> D1[(D1 task queue)]
  PC[Windows Local Agent] -->|outbound poll| CF
  PC --> B[Playwright / Chrome]
  PC --> F[Allowed folders]
  PC --> W[Allowlisted Windows apps]
  PC --> L[(JSONL audit log)]
```

## 最短セットアップ

### 1. Cloudflare Gateway

Windows PowerShell で次を実行します。

```powershell
.\scripts\Bootstrap-Cloudflare.ps1
```

このスクリプトは D1 作成、schema 適用、2つのSecret登録、Worker配備まで進めます。

### 2. Windows ローカルエージェント

管理者 PowerShell で実行します。

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\Install-Agent.ps1 -GatewayUrl "https://YOUR-WORKER.workers.dev" -AgentSecret "YOUR_AGENT_SECRET"
```

インストーラーは `C:\AI-Agent`、専用 Chrome プロファイル、許可ワークスペース、Python 仮想環境、Playwright、タスクスケジューラ自動起動を準備します。

### 3. Custom GPT

`openapi/custom-gpt-actions.yaml` の `servers.url` を Worker URL に置換し、GPT Builder の Actions へ貼り付けます。認証は Bearer API Key、値は `CONTROL_PLANE_SECRET` と同じものです。

Remote MCP を使う場合は ChatGPT Developer Mode から `https://YOUR-WORKER.workers.dev/mcp` を追加します。

## 安全設計

- 任意シェル、任意実行ファイル、資格情報読取、銀行・証券・購入・契約操作は実装していません。
- `allowed_roots` 外のパス、許可外アプリ、危険 URL スキーム、ローカルネットワーク宛 URL を拒否します。
- 送信・投稿・削除・上書き・アプリ内確定クリックは既定で承認待ちです。
- 監査ログには秘密値を保存しません。
- 普段用 Chrome ではなく専用プロファイルを利用します。

## 主要ディレクトリ

- `src/local_agent/`: Windows 常駐エージェント
- `cloud/`: Cloudflare Worker、D1、Remote MCP
- `dashboard/`: Cloudflare Pages ダッシュボード
- `openapi/`: Custom GPT Actions スキーマ
- `scripts/`: Windows ワンクリック導入
- `docs/`: 設計・初期設定・セキュリティ・トラブル対応

## 開発

```bash
python -m pip install -e ".[dev]"
pytest
ruff check .
mypy src/local_agent/models.py src/local_agent/settings.py src/local_agent/security.py src/local_agent/filesystem.py
npm --prefix cloud install
npm --prefix cloud test
npm --prefix dashboard install
npm --prefix dashboard run build
```

## 必要な Secrets

実値はリポジトリへ保存しません。

- Cloudflare Worker: `CONTROL_PLANE_SECRET`, `AGENT_SHARED_SECRET`
- GitHub Actions で Worker を自動配備する場合: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `CONTROL_PLANE_SECRET`, `AGENT_SHARED_SECRET`, `CLOUDFLARE_D1_DATABASE_ID`

詳細は [docs/setup.md](docs/setup.md)、設計は [docs/architecture.md](docs/architecture.md)、安全方針は [docs/security.md](docs/security.md) を参照してください。

## License

MIT