hermes-pilot 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.ja.md +390 -0
- package/README.md +398 -2
- package/__init__.py +15 -0
- package/apps/bridge/src/api-errors.js +165 -0
- package/apps/bridge/src/architect.js +1298 -0
- package/apps/bridge/src/auth.js +202 -0
- package/apps/bridge/src/capabilities.js +256 -0
- package/apps/bridge/src/capture.js +145 -0
- package/apps/bridge/src/chat-profile.js +95 -0
- package/apps/bridge/src/config.js +73 -0
- package/apps/bridge/src/discord.js +89 -0
- package/apps/bridge/src/gitinfo.js +211 -0
- package/apps/bridge/src/hermes.js +97 -0
- package/apps/bridge/src/inbox.js +347 -0
- package/apps/bridge/src/kanban.js +361 -0
- package/apps/bridge/src/lang.js +60 -0
- package/apps/bridge/src/live.js +285 -0
- package/apps/bridge/src/memos.js +150 -0
- package/apps/bridge/src/ops.js +201 -0
- package/apps/bridge/src/pair-codes.js +125 -0
- package/apps/bridge/src/pipeline-optimizer.js +358 -0
- package/apps/bridge/src/pipeline-watcher.js +1018 -0
- package/apps/bridge/src/qr.js +808 -0
- package/apps/bridge/src/repos.js +544 -0
- package/apps/bridge/src/review-watcher.js +271 -0
- package/apps/bridge/src/review.js +1749 -0
- package/apps/bridge/src/search.js +162 -0
- package/apps/bridge/src/server.js +1738 -0
- package/apps/bridge/src/snippets.js +373 -0
- package/apps/bridge/src/specs.js +734 -0
- package/apps/bridge/src/tail.js +28 -0
- package/apps/bridge/src/telemetry.js +667 -0
- package/apps/bridge/src/term-snippets.js +228 -0
- package/apps/bridge/src/transcript.js +231 -0
- package/apps/bridge/src/usage.js +294 -0
- package/apps/bridge/src/workerFeed.js +72 -0
- package/apps/dashboard/index.js +2014 -0
- package/apps/dashboard/manifest.json +14 -0
- package/apps/dashboard/pilot_dashboard.py +1466 -0
- package/apps/dashboard/plugin_api.py +237 -0
- package/apps/dashboard/plugin_init.py +15 -0
- package/apps/dashboard/style.css +928 -0
- package/apps/web/dist/assets/TermPane-DYP7pi_n.css +32 -0
- package/apps/web/dist/assets/TermPane-U500JD2P.js +12 -0
- package/apps/web/dist/assets/index-6iFDsB0G.css +1 -0
- package/apps/web/dist/assets/index-X4Bi2FWB.js +94 -0
- package/apps/web/dist/favicon.ico +0 -0
- package/apps/web/dist/icon-180-v6.png +0 -0
- package/apps/web/dist/icon-192-v6.png +0 -0
- package/apps/web/dist/icon-512-v6.png +0 -0
- package/apps/web/dist/icon-maskable-192-v6.png +0 -0
- package/apps/web/dist/icon-maskable-512-v6.png +0 -0
- package/apps/web/dist/icon-v6.svg +15 -0
- package/apps/web/dist/index.html +21 -0
- package/apps/web/dist/manifest.webmanifest +49 -0
- package/apps/web/dist/sw.js +69 -0
- package/bin/hermes-pilot.mjs +964 -0
- package/dashboard/dist/index.js +2014 -0
- package/dashboard/dist/style.css +928 -0
- package/dashboard/manifest.json +14 -0
- package/dashboard/pilot_dashboard.py +1466 -0
- package/dashboard/plugin_api.py +237 -0
- package/package.json +75 -4
- package/plugin.json +70 -0
- package/plugin.yaml +4 -0
- package/scripts/deploy.mjs +58 -0
- package/scripts/migrate-to-hermes-pilot.mjs +472 -0
- package/scripts/postinstall.mjs +32 -0
- package/scripts/sync-dashboard.mjs +98 -0
- package/skills/annotation/SKILL.md +103 -0
- package/skills/quick-review/SKILL.md +170 -0
- package/skills/quick-review/assets/sheet-template.html +175 -0
- package/skills/spec-architect/SKILL.md +175 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Hermes Pilot contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.ja.md
ADDED
|
@@ -0,0 +1,390 @@
|
|
|
1
|
+
# Hermes Pilot(日本語)
|
|
2
|
+
|
|
3
|
+
自律走行する [Hermes Agent](https://hermes-agent.nousresearch.com/docs) を、スマホやタブレットから**操縦**するための
|
|
4
|
+
PWA プラグインです。エージェントが判断を仰ぐ場面を「1 タップのレビューシート」と「スクショへの赤入れ」に変え、
|
|
5
|
+
**1 行の思いつきを、起票済みで自走するカンバンバッチまで運ぶ(A2B パイプライン)**うえで、
|
|
6
|
+
カンバン・チャット・ターミナル・使用量を 1 つのインストール可能な PWA にまとめます。
|
|
7
|
+
|
|
8
|
+
English README: [`README.md`](README.md)
|
|
9
|
+
|
|
10
|
+
**[▶ インタラクティブデモを試す](https://hajimemanila.github.io/hermes-pilot/)** — インストール不要・Hermes 不要。A2B フロー(Spec Seed → Quick Review → Spec Launchpad → Architect 進行 → Mission Receipt)をモックで一通り触れます。単一ファイルは [`demo/index.html`](demo/index.html) にも同梱(Google Sites に埋め込み可)。
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
[スマホ / タブレット PWA] → https://<tailscale-host>/(または http://<lan-ip>:4097)
|
|
14
|
+
│
|
|
15
|
+
[ブリッジ :4097] ──► http://127.0.0.1:9119(既存の Hermes ダッシュボードは変更しない)
|
|
16
|
+
├── カンバン SQLite(読み取り専用)
|
|
17
|
+
├── Hermes WebSocket(チャット JSON-RPC 中継)
|
|
18
|
+
└── ~/.hermes/plugin-data/hermes-pilot/(トークン・シート・画像・フィード)
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## できること
|
|
22
|
+
|
|
23
|
+
- **Quick Review(レビュー)**: エージェントが「3±1 問+推奨案」のシートを作り、カンバンタスクを blocked で
|
|
24
|
+
起票します。スマホから 1 タップで回答すると、コメントとして返り、ワーカーが再開します。スキル: `skills/quick-review/`
|
|
25
|
+
- **Annotation(赤入れ)**: エージェントが添付したスクショに指で赤を入れ(矩形・矢印・メモ)、座標付きの修正リストとして返します。
|
|
26
|
+
スキル: `skills/annotation/`
|
|
27
|
+
- **Spec Architect(仕様化)**: 1 行の種から設計ヒアリングを行い、ワーカーが追加質問なしに完走できる
|
|
28
|
+
`docs/SPEC-*.md` を作ります。スキル: `skills/spec-architect/`
|
|
29
|
+
- **タスク / 承認待ち**: ボード切替、詳細、イベント履歴、タスクごとの git 差分、承認・コメント・中断。**Spec Seed** と同列に **🧠 ブレスト**・**🛠 リファクタリング** を装備
|
|
30
|
+
- **チャット**: ストリーミング、思考ログ、ツールログ、添付、定型スニペット、セッション横断検索、バブルメニュー(コピー・メモ保存・要約・継続指示)、履歴ドロワーの「継続可 / 閲覧専用」識別&稼働中表示
|
|
31
|
+
- **メモ(ひらめき&レポート受信箱)**: Keep 風のカードグリッドで 1 行メモ・チェックリスト・タグ・検索・定期/完了レポートの受信箱を管理し、ブレストや Spec Seed へそのまま接続
|
|
32
|
+
- **ターミナル**: 実 PTY。OS に応じたコマンドスニペット付き
|
|
33
|
+
- **全タブ状態保持**: タスク・レビュー・チャット・メモ・ターミナル・設定のすべてのタブを裏で保持し、タブ往復時の再読み込みタイムラグや入力ロスを防止
|
|
34
|
+
- **英語・日本語**(既定フォールバックは `en`、`ja` 同梱)、**Dark / Light / System** テーマ、そして 2 段階の
|
|
35
|
+
2 ペイン: **680px から狭幅マスター・ディテール**(左 280px。iPad mini 縦などの 744/768px 用)と
|
|
36
|
+
**820px から広幅 2 ペイン**(レビュー左 380px / タスク左 360px)。680px 未満は詳細が全画面シートで開きます
|
|
37
|
+
- **外部プラグイン不要** — リポジトリはプロジェクトフォルダの 1 階層スキャンで見つけ、システム状態は
|
|
38
|
+
Hermes 標準 API だけで組み立てます
|
|
39
|
+
|
|
40
|
+
## A2B パイプライン(種 → 自走するバッチ)
|
|
41
|
+
|
|
42
|
+
1 行の意図が、ワーカーが最後まで走れる仕様書になります。質問をチャットに積みません。
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
📝 Spec Seed ──► Quick Review ──► 📄 SPEC-<SLUG>.md ──► 🚀 Spec Launchpad ──► ⚡ ライブ監視 ──► 🏆 Mission Receipt
|
|
46
|
+
1 行(音声可) 3(±1) 問 バッチごとの実行モード 冪等な一括起票 ArchitectJobBar 1200×630 PNG
|
|
47
|
+
1 タップ回答 受入条件を明記 (カンバン) LiveSheet/WorkerFeed X 換算 280 文字以内
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**2 つの正規ルート(どちらも外部 AI CLI を起動しません):**
|
|
51
|
+
|
|
52
|
+
- **A. SPEC 配置 → 1 タップ自律実装(基本ルート)** — `docs/SPEC-*.md`(必要なら先に
|
|
53
|
+
`review/sheets/*.json`)を自分でリポジトリへ置きます。自分のターミナル、公式 Antigravity Remote PWA、
|
|
54
|
+
任意のエディタのどれでも構いません。Hermes Pilot はファイル監視(`Spec Launchpad` / `reviewWatcher`)
|
|
55
|
+
だけで受け取り、1 タップの起票から自律実装が始まります。
|
|
56
|
+
- **B. `Hermes Native` による仕様策定(スマホ完結)** — `Spec Seed` → Quick Review → `docs/SPEC-*.md` →
|
|
57
|
+
Launchpad。Hermes 自身の `hermes kanban create` で回すため、外部プロセスはゼロです(下の 1〜4)。
|
|
58
|
+
|
|
59
|
+
1. **📝 Spec Seed** — タスクタブで 1 行を入力(音声ディクテーション可)し、**実行モード**を選びます。
|
|
60
|
+
- **`Zero-Stop`**(既定)— 全バッチが承認待ちで止まらず最後まで自走します。
|
|
61
|
+
- **`Visual-Gate`** — チェックポイントで止まり、次のバッチへ進む前に描画結果(スクショ/赤入れ)を
|
|
62
|
+
目で確認できます。
|
|
63
|
+
- **ランナー** — `Hermes Native` 固定です。Architect は Hermes 自身の中で回り、外部 AI CLI を
|
|
64
|
+
サブプロセスとして起動することはありません(上の「2 つの正規ルート」を参照)。
|
|
65
|
+
2. **Quick Review ヒアリング** — Architect が推奨案つきの 3(±1) 問をシートに載せます。
|
|
66
|
+
「⚡ 推奨を一括承認」で 1 タップですべて回答できます。
|
|
67
|
+
3. **📄 仕様書** — 2 ラウンド目で `docs/SPEC-<SLUG>.md` を書きます。決定表・バッチごとの `Execution Mode`・
|
|
68
|
+
変更ファイル・受入コマンドまで含むので、ワーカーが「どう実装するか」を聞き返しません。
|
|
69
|
+
4. **🚀 Spec Launchpad** — タスクタブが仕様書の `### Batch <ID>` をアコーディオン+Markdown プレビューで
|
|
70
|
+
一覧し、1 タップでカンバンに起票します。同じ `[ID]` の未完了タスクがあるバッチは飛ばすので、
|
|
71
|
+
二度押し・再読み込みでも重複しません。
|
|
72
|
+
5. **⚡ ライブ監視** — `ArchitectJobBar` がジョブのフェーズ(`spawning → round1_sheet → round2_spec →
|
|
73
|
+
spec_ready → launched`)を出し、進まなくなると停滞警告を出し、失敗・停滞したジョブは 1 タップで
|
|
74
|
+
再試行できます。
|
|
75
|
+
`LiveSheet` と `WorkerFeed` が実行中ワーカーのログを流します。
|
|
76
|
+
6. **🏆 Mission Receipt** — バッチ完走後、完走サマリが **1200×630 の PNG レシート**と、
|
|
77
|
+
**JA/EN とも X 換算 280 文字以内**のシェア文(KPI の数値は 1 つも落とさず、見出しとフッターから削る)
|
|
78
|
+
を出力します。
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
# 1) 種を起票(202 と jobId を即返し、Architect は背後で走る)
|
|
82
|
+
curl -s -X POST -H "x-client: mobile" -H "content-type: application/json" \
|
|
83
|
+
-d '{"board":"<board>","seedText":"レシートのダークモード書き出しを足す","autoStart":false}' \
|
|
84
|
+
"http://127.0.0.1:4097/api/architect/seed?t=$(cat ~/.hermes/plugin-data/hermes-pilot/token)"
|
|
85
|
+
|
|
86
|
+
# 2) ジョブの状態・完成 SPEC・未起票 SPEC
|
|
87
|
+
curl -s -H "x-client: mobile" \
|
|
88
|
+
"http://127.0.0.1:4097/api/architect/jobs?board=<board>&t=$(cat ~/.hermes/plugin-data/hermes-pilot/token)"
|
|
89
|
+
|
|
90
|
+
# 3) バッチを一括起票(冪等。同じ板の未完了はスキップ)
|
|
91
|
+
curl -s -X POST -H "x-client: mobile" -H "content-type: application/json" \
|
|
92
|
+
-d '{"board":"<board>","specRelPath":"docs/SPEC-DARK-RECEIPT.md","batchIds":["B1","B2"]}' \
|
|
93
|
+
"http://127.0.0.1:4097/api/specs/launch?t=$(cat ~/.hermes/plugin-data/hermes-pilot/token)"
|
|
94
|
+
|
|
95
|
+
# 4) 完走後 — 完走サマリとレシートの材料(読み取り専用の集計)
|
|
96
|
+
curl -s -H "x-client: mobile" \
|
|
97
|
+
"http://127.0.0.1:4097/api/telemetry/receipt?board=<board>&hours=24&t=$(cat ~/.hermes/plugin-data/hermes-pilot/token)"
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## 意思決定コックピット(v2)
|
|
101
|
+
|
|
102
|
+
「エージェントが判断を待っている」から「また走り出した」までを最短にする 5 つ。スマホからも標準
|
|
103
|
+
ダッシュボードからも触れます。
|
|
104
|
+
|
|
105
|
+
- **Spec Launchpad** — タスクタブがボードのリポジトリの `docs/SPEC-*.md` を読み、`### Batch P1: …` の
|
|
106
|
+
バッチを一覧して 1 タップでカンバンに起票します。同じ `[ID]` の未完了タスクがあるバッチは飛ばすので、
|
|
107
|
+
二度押しや再読み込みで重複しません。
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
curl -s -H "x-client: mobile" "http://127.0.0.1:4097/api/specs?board=<board>&t=$(cat ~/.hermes/plugin-data/hermes-pilot/token)"
|
|
111
|
+
curl -s -X POST -H "x-client: mobile" -H "content-type: application/json" \
|
|
112
|
+
-d '{"board":"<board>","specRelPath":"docs/SPEC-PILOT-V2.md","batchIds":["P5"]}' \
|
|
113
|
+
"http://127.0.0.1:4097/api/specs/launch?t=$(cat ~/.hermes/plugin-data/hermes-pilot/token)"
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
- **1 タップ一括承認(Fast-Track)** — 設問に推奨案があるシートでは
|
|
117
|
+
「⚡ 推奨案(Q1:A · Q2:B)で一括承認して再開」が出ます。1 タップで推奨をまとめて送信し、ワーカーを
|
|
118
|
+
unblock して次の判断待ちへ移ります(`POST /api/review/:id/answer`)。
|
|
119
|
+
- **Before ↔ After 比較** — 前ラウンド(`*.before.png` または 1 つ前の連番スクショ)がある注釈レビューでは
|
|
120
|
+
比較トグルが出て、自分が入れた赤と最新スクショを切り替えて見られます。「✅ 検収 OK」で 1 タップ完了
|
|
121
|
+
(`POST /api/review/:id/approve`)。
|
|
122
|
+
- **標準ダッシュボード連携** — Hermes ダッシュボード(`:9119`)の「Hermes Pilot」タブで、リポジトリ
|
|
123
|
+
(追加・ピン・非表示・ボード作成)、チャット&端末スニペット、ブリッジ/GW/監査ログを、PWA と同じ
|
|
124
|
+
ファイルに対して操作できます(`scanDirs` の設定箇所は 1 か所だけ)。
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
node bin/hermes-pilot.mjs init --force # 更新後にダッシュボードのプラグインファイルを入れ替える
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
- **スニペット編集** — 組み込みも Hot(バー表示)/ 非表示を切替でき、自分用の追加・編集・並べ替え・削除が
|
|
131
|
+
チャットと端末の両方で、英語・日本語のまま行えます(「既定に戻す」つき)。
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
curl -s -H "x-client: mobile" "http://127.0.0.1:4097/api/snippets?lang=ja" # チャット
|
|
135
|
+
curl -s -H "x-client: mobile" "http://127.0.0.1:4097/api/snippets/term?lang=ja" # 端末
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## 快適さと 1 タップ設定
|
|
139
|
+
|
|
140
|
+
- **Vibe モード** — 設定の `⚡ ドーパミン ⇄ 🧘 セロトニン` は「見た目と手触りの強さ」だけを変え、機能は変えません
|
|
141
|
+
(Dopamine 時は 3D ベベルの HUD ルック、チャットバブルグロー、上部バナー&ドット明滅、EN/JA 擬音付き
|
|
142
|
+
`sakuga-vfx` 風バネ&Canvas 作画エフェクト、`Working…` オーロラグローが有効になり、Serotonin 時は静謐な
|
|
143
|
+
フラット表示へ戻ります)。ハプティクスと効果音は独立トグルで、**Vibe を切り替えても維持**されます(音量を
|
|
144
|
+
下げたつもりが振動まで止まる事故を起こさないため)。
|
|
145
|
+
- **スニペット帯トグル** — チャット入力欄の上、注釈ツールバー、端末キーのチップ帯はそれぞれ折りたためます。
|
|
146
|
+
選択は帯ごとに記憶され、390px の画面で入力欄とキーボードが場所を取り合いません。
|
|
147
|
+
- **1 タップ環境最適化** — *設定 → この Hermes を最適化*(`POST /api/pipeline/optimize`)が
|
|
148
|
+
`~/.hermes/SOUL.md` へ A2B の規律節を**冪等に**追記し、同梱 3 スキルを `~/.hermes/skills/` へ配置します。
|
|
149
|
+
`GET /api/pipeline/status` は適用済みかだけを返し、`SOUL.md` の中身は返しません。
|
|
150
|
+
- **旧 cron の自動片付け** — `migrate`(と `init`)は旧 `mobile-akapen-watch` / `mobile-review-watch` の
|
|
151
|
+
cron を削除します。完了フィードはブリッジ内蔵の監視が書くようになり、2 者が書くと報告が二重になるためです。
|
|
152
|
+
他の cron とストアのトップレベル構造は変更しません。
|
|
153
|
+
|
|
154
|
+
## 触って試せるデモ(バックエンド不要)
|
|
155
|
+
|
|
156
|
+
`npm run build:demo` で `apps/web/dist-demo` に**ブリッジもゲートウェイも DB も要らない**静的サイトを
|
|
157
|
+
生成します。GitHub Pages などの静的ホスティングに置けば、誰でもパイプラインを体験できます。
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
npm run build:demo # VITE_DEMO_MODE=1 / base ./ / outDir apps/web/dist-demo
|
|
161
|
+
npx serve apps/web/dist-demo # もしくは python3 -m http.server -d apps/web/dist-demo 4321
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
- **スマホ**では普通の PWA として全画面で開きます(筐体なし)。
|
|
165
|
+
- **PC ブラウザ(900px 以上)**ではデバイス筐体つきで表示し、`Phone 390×844` / `Tablet 820×1180`
|
|
166
|
+
(2 ペイン)/ `Full window` を即時切替。`Dopamine ⇄ Serotonin`・音・`Dark ⇄ Light`・`EN ⇄ JA`・
|
|
167
|
+
「ツアーを最初から」も同じバーから切り替わります。筐体の中身は本物の `<iframe>` なので、
|
|
168
|
+
メディアクエリ・`position: fixed` のシート・トースト・下部ナビが実機と同じように振る舞います。
|
|
169
|
+
- **4 ステップのガイド**(上部バー。各ステップにジャンプボタン): ① 仕様の判断シートを
|
|
170
|
+
「⚡ 推奨を一括承認」→ ② 生成された仕様書のバッチを一括起票して自走を眺める →
|
|
171
|
+
③ 赤入れスタンプ or Before ↔ After の視覚検収 → ④ 実行サマリと**完了レシート**
|
|
172
|
+
(1200×630 PNG / シェア文)を開く。
|
|
173
|
+
|
|
174
|
+
データはすべてメモリ上(`apps/web/src/demo/mockApi.js`)で、視覚検収に使う画像も inline SVG の
|
|
175
|
+
data URL として組み立てるため、デモは外部ネットワークに一切依存しません。
|
|
176
|
+
|
|
177
|
+
**本番は汚しません**: `main.jsx` が `import.meta.env.VITE_DEMO_MODE` を見るので、通常の
|
|
178
|
+
`npm run build` ではデモ分岐ごと(動的 import を含めて)消えます。`apps/web/dist` にモックのコード・
|
|
179
|
+
ツアー用 CSS・スクショは入りません(共有辞書の `demo.*` 文言だけは辞書に残ります)。
|
|
180
|
+
`apps/web/dist-demo` は git 管理外で、`npm pack` にも含まれません。
|
|
181
|
+
|
|
182
|
+
### Google Sites(単一ファイル埋め込み)
|
|
183
|
+
|
|
184
|
+
`npm run build:demo` は **`apps/web/dist-demo/google-sites-embed.html`** も生成します。JS・CSS・SVG 画像を
|
|
185
|
+
すべてインライン化し、`localStorage` をメモリ実装に差し替え、PWA 用の `<link>` を外した 1 ファイルです。
|
|
186
|
+
生成直後の `verifyEmbedHtml()` 自己チェックで外部参照が 1 つでも残っていれば**ビルドが exit 1 で失敗**する
|
|
187
|
+
ため、壊れたファイルがサイトに出ることはありません。
|
|
188
|
+
|
|
189
|
+
1. `npm run build:demo`
|
|
190
|
+
2. Google Sites → *挿入* → **埋め込み** → **コードを埋め込む** → `google-sites-embed.html` の中身を丸ごと貼り付け
|
|
191
|
+
3. PC ブラウザで開くと、埋め込み文書が自分をフレームだと認識する(`window.__HM_DEMO_FRAME__`)ため、
|
|
192
|
+
**`Phone 390×844` / `Tablet 820×1180` / `Full window`** のデバイスシミュレータと上部バーがそのまま出ます。
|
|
193
|
+
「ツアーを最初から」は `srcdoc` の reload ではなく内側 iframe の再生成なので、Google Sites 上でも動きます
|
|
194
|
+
4. GitHub Pages なら `apps/web/dist-demo` をそのまま公開(相対 `base`)。埋め込みファイルは任意です。
|
|
195
|
+
|
|
196
|
+
## 必要なもの
|
|
197
|
+
|
|
198
|
+
- Node.js **22.19 以上**
|
|
199
|
+
- Hermes Agent(ブリッジは `http://127.0.0.1:9119` を中継します)
|
|
200
|
+
- 任意: [Tailscale](https://tailscale.com/)(外出先から HTTPS で使う場合)。同じ LAN なら
|
|
201
|
+
`http://<lan-ip>:4097` で Tailscale 無しでも動きます
|
|
202
|
+
|
|
203
|
+
## インストール
|
|
204
|
+
|
|
205
|
+
ルートは 2 つ。最初の 1 手が違うだけで、そのあとは同じ **コードを取る → `npm ci` → `init`** の 3 手です。
|
|
206
|
+
まだ npm へ公開していないため、以下のコマンドはすべて `npx` ではなくリポジトリ(またはプラグイン
|
|
207
|
+
ディレクトリ)の CLI を直接叩く `node bin/hermes-pilot.mjs …` で書いています。
|
|
208
|
+
|
|
209
|
+
**A. Hermes のプラグインカタログから(推奨)**
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
hermes plugins install hajimemanila/hermes-pilot --ref <sha> # sha で固定。--ref を省くと既定ブランチ
|
|
213
|
+
cd ~/.hermes/plugins/hermes-pilot
|
|
214
|
+
npm ci
|
|
215
|
+
node bin/hermes-pilot.mjs init
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
**B. このリポジトリを clone して**
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
git clone https://github.com/hajimemanila/hermes-pilot.git
|
|
222
|
+
cd hermes-pilot
|
|
223
|
+
npm ci
|
|
224
|
+
node bin/hermes-pilot.mjs init
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
`npm ci` は省略できません。ブリッジは `ws` と**ネイティブアドオン**の `node-pty` を使い、
|
|
228
|
+
`postinstall` が npm の tarball 展開で落ちる `spawn-helper` の実行ビットを戻しています
|
|
229
|
+
(これが無いと端末タブが `posix_spawnp failed` で落ちます)。
|
|
230
|
+
|
|
231
|
+
以下の `node bin/hermes-pilot.mjs …` はすべて、カレントディレクトリがそのリポジトリ/プラグイン
|
|
232
|
+
ディレクトリである前提です。短く打ちたければ一度 `npm link` してから `hermes-pilot …` を使ってください。
|
|
233
|
+
|
|
234
|
+
`init` は何度実行しても安全で、次の 5 つを行います。
|
|
235
|
+
|
|
236
|
+
1. `~/.hermes/plugin-data/hermes-pilot/`(と `review/{sheets,shots,library}`)を作成
|
|
237
|
+
2. **256-bit hex のアプリトークン**を `token` に `0600` で生成(既にあれば作り直さない)
|
|
238
|
+
3. 旧 `~/Projects/akapen` / `~/.hermes/plugin-data/akapen` / `~/.hermes/mobile-pwa` があれば移行
|
|
239
|
+
(**コピー**のみ・`mtime` 保持・カンバンの `[akapen]` タグを `[review]` に書換)
|
|
240
|
+
4. 同梱スキル `quick-review` / `annotation` / `spec-architect` を `~/.hermes/skills/` へ配置
|
|
241
|
+
5. 到達可能なアドレス(Tailscale の MagicDNS 名、無ければ LAN IP)を検出して、
|
|
242
|
+
**ペアリング URL とターミナル QR** を表示
|
|
243
|
+
|
|
244
|
+
そのあとブリッジを起動します。
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
node bin/hermes-pilot.mjs start # http://127.0.0.1:4097
|
|
248
|
+
node bin/hermes-pilot.mjs start --port 4097 --host 127.0.0.1
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
## 端末のペアリング(長いトークンを打たない)
|
|
252
|
+
|
|
253
|
+
- **ターミナルから**: `node bin/hermes-pilot.mjs qr` が候補と QR を表示。Tailscale `serve` が 443 以外で HTTPS を
|
|
254
|
+
出している場合は `--tls-port 8444` を付けます
|
|
255
|
+
- **アプリから**: 設定 →「端末を追加」→「ペアリング QR を表示」(`GET /api/auth/pairing`)。
|
|
256
|
+
2 台目のスマホ/タブレットで読み取ります
|
|
257
|
+
|
|
258
|
+
QR を読むと `https://<host>/?token=<token>`(または `#token=`)が開きます。アプリはそのトークンを
|
|
259
|
+
`POST /api/auth/login` で **HttpOnly のセッション Cookie** に交換し、直後に `history.replaceState` で
|
|
260
|
+
アドレスバーからトークンを消します(履歴・ブックマーク・スクショに残さない)。
|
|
261
|
+
|
|
262
|
+
> QR にはアプリトークンが入っています。読み取った人はこの Hermes を操作できます。スクショの共有は
|
|
263
|
+
> パスワードと同じ扱いにしてください。ローテーションは
|
|
264
|
+
> `rm ~/.hermes/plugin-data/hermes-pilot/token` してブリッジを再起動(全端末がログアウトされます)。
|
|
265
|
+
|
|
266
|
+
## 常駐化
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
node bin/hermes-pilot.mjs service install # macOS は launchd、Linux は systemd --user
|
|
270
|
+
node bin/hermes-pilot.mjs service status
|
|
271
|
+
node bin/hermes-pilot.mjs service restart
|
|
272
|
+
node bin/hermes-pilot.mjs service uninstall
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
- macOS: `~/Library/LaunchAgents/ai.hermes.pilot.plist`(ラベル `ai.hermes.pilot`)、
|
|
276
|
+
ログは `~/.hermes/logs/pilot.out.log` / `pilot.err.log`
|
|
277
|
+
- Linux: `~/.config/systemd/user/hermes-pilot.service`
|
|
278
|
+
(`systemctl --user enable --now hermes-pilot.service`)
|
|
279
|
+
|
|
280
|
+
### `hermes-mobile-pwa` からの移行(HEADS-UP)
|
|
281
|
+
|
|
282
|
+
サービスラベルは `ai.hermes.hermes-mobile` → `ai.hermes.pilot`、パッケージ名は
|
|
283
|
+
`hermes-mobile-pwa` → `hermes-pilot` に変わりました。**旧ラベルは止めずに併設**して、無停止で切り替えます。
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
node bin/hermes-pilot.mjs init # データをコピー(旧ファイルはそのまま残る)
|
|
287
|
+
node bin/hermes-pilot.mjs service install # 新しいラベルを登録して起動
|
|
288
|
+
node bin/hermes-pilot.mjs service status # 起動確認
|
|
289
|
+
|
|
290
|
+
# 新しい方で問題ないと確認できてから、旧ラベルを引退させる:
|
|
291
|
+
launchctl bootout gui/$(id -u)/ai.hermes.hermes-mobile
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
どちらもポート 4097 を使います。旧がまだ 4097 を掴んでいる場合は、新を別ポートで先に起動して確認し
|
|
295
|
+
(`node bin/hermes-pilot.mjs start --port 4098`)、あとで入れ替えてください。旧 `~/.hermes/mobile-pwa/` は
|
|
296
|
+
コピーされるだけで削除されません。不要になったら手動で消してください。
|
|
297
|
+
|
|
298
|
+
## セキュリティ
|
|
299
|
+
|
|
300
|
+
待ち受けているのはブリッジだけであり、Hermes に手が届くのもブリッジだけです。
|
|
301
|
+
|
|
302
|
+
| 面 | ルール |
|
|
303
|
+
|---|---|
|
|
304
|
+
| 待受 | 既定は `127.0.0.1:4097`。Tailscale `serve` などの TLS プロキシを前段に置かない限り外には出ません |
|
|
305
|
+
| 端末の資格情報 | `~/.hermes/plugin-data/hermes-pilot/token`(`0600`)の 256-bit hex アプリトークン。1 回だけ **`HttpOnly` / `SameSite=Strict` のセッション Cookie** に交換し、トークンは `history.replaceState` でアドレスバーから消します |
|
|
306
|
+
| QR ペアリング | QR に載るのは**ワンタイムのペアリングコード**(10 分・1 回限り)で、アプリトークンそのものではありません。それでもスクショの共有はパスワード扱いで。ローテーションは `rm …/token` + 再起動で全端末がログアウトします |
|
|
307
|
+
| Hermes のセッショントークン | ブリッジの外に出ません。PWA が持つのはアプリトークン/Cookie だけです |
|
|
308
|
+
| 書き込み | 変更系は **`X-Client: mobile`** ヘッダ(無いと 401)とセッション Cookie の両方が必要で、クロスサイトのフォーム送信では動きません |
|
|
309
|
+
| キルスイッチ | 1.5 秒長押し+確認語。API 側でも `confirm` を検査します。UI から生の `launchctl` は叩きません |
|
|
310
|
+
| レート制限 | 読み取り 120 回/分(エンドポイント別バケット)、書き込み 60 回/分 |
|
|
311
|
+
| 監査 | すべての書き込みを `~/.hermes/plugin-data/hermes-pilot/audit.jsonl` へ追記(設定タブから閲覧可) |
|
|
312
|
+
| 読み取り専用 | カンバン SQLite・使用量・レシートは読み取り専用で開き、ブリッジが勝手に板を移行することはありません |
|
|
313
|
+
| 公開パス | 認証不要なのはアプリの殻(`/`, `/assets/*`, `/manifest.webmanifest`, `/sw.js`, `/icon-*`, `/auth`, `/healthz`)だけ。Android の WebAPK 生成が資格情報なしで取りに来るためです。`/api/*` と `/ws/*` はすべて認証の内側です |
|
|
314
|
+
| デモ | `apps/web/dist-demo`(と Google Sites 埋め込み)は**モックデータのみ**。トークンもブリッジもネットワークも使いません |
|
|
315
|
+
|
|
316
|
+
## データと環境変数
|
|
317
|
+
|
|
318
|
+
永続データはすべて `~/.hermes/plugin-data/hermes-pilot/` の下にあります。
|
|
319
|
+
|
|
320
|
+
```text
|
|
321
|
+
config.json { lang, scanDirs, servicePort, tlsPort? }
|
|
322
|
+
token アプリトークン(0600)
|
|
323
|
+
audit.jsonl 監査ログ(書き込みごと)
|
|
324
|
+
repos.json scanDirs / pinned / hidden / custom
|
|
325
|
+
snippets.json ユーザー定義のチャットスニペット
|
|
326
|
+
review/ sheets/, shots/, library/, feed.jsonl, chat-reports.jsonl, task-chats.json
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
| 変数 | 意味 |
|
|
330
|
+
|---|---|
|
|
331
|
+
| `HP_DATA_DIR` | プラグインのデータ先(既定 `~/.hermes/plugin-data/hermes-pilot`) |
|
|
332
|
+
| `HM_DATA` | データ先の完全上書き(開発・検証用) |
|
|
333
|
+
| `HM_PORT` / `HM_HOST` | ブリッジの待受(既定 `4097` / `127.0.0.1`) |
|
|
334
|
+
| `HERMES_HOME` | Hermes ホーム(既定 `~/.hermes`。`profiles/<name>` を指した場合はルートに補正) |
|
|
335
|
+
|
|
336
|
+
## 構成の決定
|
|
337
|
+
|
|
338
|
+
| 項目 | 決定 |
|
|
339
|
+
|---|---|
|
|
340
|
+
| 公開 | `https://<host>:8444`(Tailscale `serve`)。ブリッジ自体は `127.0.0.1:4097` のみ |
|
|
341
|
+
| 認証 | アプリトークン Cookie(`HttpOnly` / `SameSite=Strict`)+書き込み時 `X-Client: mobile` |
|
|
342
|
+
| カンバン | ボードごとの SQLite を読み取り専用で直接読む(HTTP API が無いため) |
|
|
343
|
+
| キルスイッチ | Hermes の `/api/gateway/*`。UI から生の `launchctl` は叩かない |
|
|
344
|
+
| レビュー | `~/.hermes/plugin-data/hermes-pilot/review/`(シート・画像・ライブラリ・フィード) |
|
|
345
|
+
| 完了通知 | ブリッジ内蔵 `review-watcher.js` が `feed.jsonl` / `chat-reports.jsonl` を追記(cron 不要) |
|
|
346
|
+
|
|
347
|
+
## 開発
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
npm install # postinstall が node-pty の権限を直す
|
|
351
|
+
npm run dev # Vite :4098(/api・/ws は 4097 へプロキシ)
|
|
352
|
+
npm test # 単体テスト(808 件)
|
|
353
|
+
npm run verify # test + check:pwa(34 項目)+ check:oauth + 本番ビルド + audit:responsive
|
|
354
|
+
npm run build:demo # バックエンド不要の静的デモ → apps/web/dist-demo(+ google-sites-embed.html)
|
|
355
|
+
npm run deploy # 検証付きで dist を原子的に切替(無停止)
|
|
356
|
+
npm run migrate:pilot # init と同じ移行を単体で実行
|
|
357
|
+
node bin/hermes-pilot.mjs --help
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
`npm run verify` はすべての変更が通す関門です(このツリーでの実測):
|
|
361
|
+
|
|
362
|
+
| 手順 | 何を保証するか |
|
|
363
|
+
|---|---|
|
|
364
|
+
| `npm test` | **808 件**の単体・結合テストが 0 fail(node:test、フレームワーク無し) |
|
|
365
|
+
| `check:pwa` | `apps/web/public` に対する **34/34** 項目(マニフェスト・アイコン・マスカブル・Service Worker・viewport) |
|
|
366
|
+
| `check:oauth` | **0 違反**: 端末の資格情報や OAuth トークンがブラウザ側バンドルから読めないこと |
|
|
367
|
+
| `build` | Vite 本番ビルドが通り、`demo/` のコードが混入していないこと |
|
|
368
|
+
| `audit:responsive` | `390×844` / `844×390` / `820×1180` などのレイアウト監査(タップ 44px 以上・新規の見切れなし) |
|
|
369
|
+
|
|
370
|
+
構成:
|
|
371
|
+
|
|
372
|
+
```text
|
|
373
|
+
bin/hermes-pilot.mjs CLI: init / start / qr / service / migrate
|
|
374
|
+
apps/bridge/src/ ブリッジ(server.js, auth.js, review.js, qr.js, capabilities.js, ...)
|
|
375
|
+
apps/bridge/test/ ブリッジの単体テスト(qr.test.js は qrencode の参照行列と比較)
|
|
376
|
+
apps/web/src/ React PWA(i18n/, features/, lib/pairing.js, lib/theme.js)
|
|
377
|
+
apps/web/src/demo/ デモ専用(mockApi.js, DemoStage.jsx, demo.css)— dist には入りません
|
|
378
|
+
apps/web/dist/ ブリッジが配信する本番ビルド
|
|
379
|
+
apps/web/dist-demo/ 静的デモビルド(`npm run build:demo`・git 管理外)
|
|
380
|
+
skills/ 同梱スキル quick-review / annotation / spec-architect
|
|
381
|
+
docs/ SPEC-PUBLIC-PLUGIN.md(仕様), OPERATIONS.md, PLAN.md, EVIDENCE.md
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
QR 生成は依存ゼロ(`apps/bridge/src/qr.js`)です。byte モード・誤り訂正レベル M・型番 1〜10 に対応し、
|
|
385
|
+
UI 向けに SVG、ターミナル向けに ANSI 半角ブロックを出します。生成したモジュール行列は
|
|
386
|
+
`apps/bridge/test/qr.test.js` で `qrencode` の参照行列と一致することを検証しています。
|
|
387
|
+
|
|
388
|
+
## ライセンス
|
|
389
|
+
|
|
390
|
+
MIT
|