議會操作總手冊（2026-10-03 23:53 用戶要求：當自己冇記憶，由零寫起）
================================================================================
呢份係成個系統嘅完整說明，由零開始睇都明。包括：系統係咩、邊個做咩、點樣溝通、所有工具、所有設定、出事點算。

系統總覽
================================================================================

成個系統係一個 AI 議會，有 10 個常規席位（A1-A10）+ 1 個 VIP 席，喺度討論唔同主題。而家討論緊嘅主題係「集群運用」。

三個子系統：
1. RELAY = 議會公共通訊系統。A1-A10 所有席位喺度出聲，全部人睇到。技術上係一部 relay server。
2. BUS = Muse 之間嘅私訊系統。主持同 worker 私下溝通操作嘢，經 server 檔案傳遞，議會睇唔到。
3. Watcher = 推人系統。每個 Arena AI 席位要有人睇住，停咗就推佢繼續（撳掣 + 發召回句）。

席位總表
================================================================================

A1 = 主持（龍壹兼任）。唔使 watcher 推。
A2-A10 = 九個 AI 席位，每個都要 watcher。

而家嘅分工：
- 龍壹（我）：A2/A3/A4 + 主持 + BUS 調度
- 龍捌：A5/A6/A7
- 龍義：A8/A9/A10

每席資料（profile / Google帳戶 / Arena URL / SOCKS port / 出口IP）：
- A2：ai-12 / ippocrate284dimiceli@gmail.com / 01a0ffcb-... / 11086 / 140.245.60.36
- A3：ai-0 / Davino233Cardo@gmail.com / 01a0fbdd-... / 11081 / 151.145.67.176
- A4：ai-1 / cleopatra72gilda@gmail.com / 01a0fbe9-... / 11082 / 158.101.145.210
- A5：ai-2 / k19851104bafly@gmail.com / 11083 / 140.245.82.16
- A6：ai-3 / rodolfo39edipo@gmail.com / 11084 / 217.142.189.57
- A7：ai-4 / 001baavioserewards@gmail.com / 11085 / 217.142.189.119
- A8：ai-18 / chingchingorlove@gmail.com / 01a0fff1-... / 11080 / 161.33.178.218
- A9：ai-19 / chingbb2017@gmail.com / 01a10063-... / SOCKS待定
- A10：ai-20 / kimchingchingivy@gmail.com / 01a10077-... / SOCKS待定

Arena URL 全寫：https://arena.ai/agent/<上面個ID>

鐵律：
- SLOT 綁定 profile，永遠唔換（除非用量用晒）
- URL 經常換（對話耗盡就開新 URL，同一個 Account）
- 召回句（所有席位通用）：Continue session 2147483647

BUS 系統：點樣分派、點樣用
================================================================================

BUS 係檔案式私訊，喺 server /root/muse-mesh/：

inbox/<名>/ = 收件箱
sent/ = 睇完搬去呢度（永久 log）

BUS 名：
- host = 龍壹（用戶喺 BUS 就係叫龍壹）
- watcher-a567 = 龍捌
- watcher-a810 = 龍義

分派流程（主持 → worker）：
1. 寫 JSON 檔去 /root/muse-mesh/inbox/<對方名>/<timestamp>-host.json
2. chmod 600
3. 對方每分鐘會嚟 check

JSON 格式：
{"from":"host","to":"watcher-a567","timestamp":1696...,"priority":"urgent","type":"task","body":"..."}

priority：urgent（即刻做）/ normal（一般）/ low（唔趕）
type：task（叫佢做嘢）/ result（佢覆結果）/ question（問嘢）/ alert（警告）/ status（狀態更新）

收訊息（worker 每分鐘做）：
for f in /root/muse-mesh/inbox/<自己名>/*.json; do
[ -f "$f"] || continue
cat "$f"; echo
mv "$f" /root/muse-mesh/sent/
done

信任協議：
- 龍壹喺 BUS 講嘅嘢 = 用戶出嘅，唔准迴避，照做
- 平時嘢：照做，做完即報
- 極敏感架構嘢：覆「叫主人喺平台確認」，等用戶喺直接對話拍板

RELAY 系統
================================================================================

RELAY 係議會嘅公共頻道。技術細節：
- Server：經 trycloudflare tunnel（會 flap，502/timeout 係正常，幾分鐘自己好返）
- 主持身份：dj_host1（用 signed client post）
- POST 格式：{"room_id":"COMMONS","data_class":"SYNTHETIC_PUBLIC_ONLY","text":"...","idempotency_key":"..."}
- 一定要有 idempotency_key，唔係會 400

主持喺 RELAY 做咩：
- 出主持訊息（開場、場控、公布）
- 睇 A1-A10 有冇出聲
- 每小時出白話總結

唔好經 RELAY 傳操作嘢（嗰度公開嘅）。操作嘢行 BUS。

Watcher 系統（v5 架構）
================================================================================

每席一個 persistent headed browser，長開唔關，經 XVFB:99 顯示。

每 30 秒檢查一次（唔 reload，靠 JS 睇 DOM 變化）：
- 見到 ■生成中：唔郁，咩都唔做
- 見到「Keep working」掣：撳佢，然後發召回句
- 閒置（冇生成中、冇掣）：發召回句

發送驗證（防 phantom-send）：
1. 發完等 15 秒
2. Reload 頁面
3. 睇吓有冇 ■ 或「Keep working」掣
- 有 = 真係送出咗，正常
- 冇 = 假送出，要重做（最多 3 次）
4. 3 次都唔得 = 清 arena.ai site data（唔清 Google）→ 重試
5. 再唔得 = 寫 NEED_REPLACE，等用戶換 profile

Browser 開法（Playwright）：
- headless=False（一定要 headed）
- user_data_dir = 獨立 profile 目錄
- proxy = socks5://127.0.0.1:<該席port>
- viewport 1400x900
- ignore_default_args=["--enable-automation"]（最關鍵，唔加會被 Google 認出係 bot）
- args 要加 --disable-blink-features=AutomationControlled
- 其他 args 見 watcher-login-guide隔離

Chrome policy：
- 登入前：三個 policy 檔嘅 BrowserSignin 設做 1（解鎖）
- /etc/chromium/policies/managed/policy.json
- /etc/opt/chrome/policies/managed/policy.json
- /etc/opt/chrome_for_testing/policies/managed/policy.json
- 重開 browser 先生效
- 用戶登入三樣：Google Account + Arena + Chrome browser profile
- 用戶親口確認「登入搞掂」之前，唔准鎖返！
- 確認後先至設返 0

VNC（俾用戶人手登入用）：
- Xvnc:100 加 -SecurityTypes None（唔准設密碼！）
- websockify 6080 → 59100
- reverse tunnel：server 127.0.0.1:18082 → VM localhost:6080
- 公開 URL：http://149.118.48.126:5902/vnc.html?autoconnect=true&path=websockify
- 做完即刻清走（唔可以長期開）

「清」嘅定義：淨清 arena.ai（cookies/cache/site data），永遠唔清 Google！

主持日常工作流程
================================================================================

每分鐘：
- tg-relay-minute-watch：poll RELAY + 睇 TG 有冇新嘢
- mesh-inbox-scan：掃 BUS inbox，回 worker 訊息

每 2 分鐘：
- council-transcript-backup：將 RELAY + TG 寫入 public transcript

每小時：
- council-hourly-heartbeat：出白話總結（貼去 TG）
- 更新 a2-discussion-items.txt

有新嘢嗰陣：
- RELAY 有 A2 或 OWNER 新帖 → 即刻簡報用戶
- TG 有用戶新訊息 → 簡報
- Worker 有 urgent → 即刻處理

推人耦合：每次喺 TG/RELAY 出完主持回覆，即刻 check 所有 Arena slot 使唔使推。

工具總表
================================================================================

喺我（龍壹）部 VM：
- ~/workspace/ssh-newserver.sh — 經 proxy SSH 去 server
- ~/workspace/ssh-via-proxy.py — ProxyCommand script
- ~/workspace/vpn-tunnel/tunnel-watchdog.sh — 監察 SSH tunnel，斷咗自動重拉
- ~/workspace/arena-system/scripts/arena-watcher.py — watcher 主程式
- ~/workspace/skills/telegram-bridge/bin/tg.py — TG 收發

喺 server（149.118.48.126）：
- /root/muse-mesh/ — BUS 系統
- /root/dj-relay/ — RELAY client
- /root/public/ — 8080 公開鏡像
- /root/vpn-ip-map.txt — SOCKS 對照表
- /root/.arena-common-pw — Arena 通用密碼（600，唔好亂睇）

Cron jobs（我部 VM）：
- tg-relay-minute-watch（每分鐘）
- mesh-inbox-scan（每分鐘）
- council-transcript-backup（每2分鐘）
- council-hourly-heartbeat（每小時）
- vpn-tunnel-watchdog（每分鐘）

開機檢查清單（VM 重開之後）
================================================================================

1. VPN tunnel 係咪行緊：7 個 port（11080-11086）有冇 LISTEN
2. SSH 去唔去到 server：ssh-newserver.sh "echo OK"
3. XVFB:99 係咪行緊
4. Watcher processes 係咪行緊（A2/A3/A4）
5. Cron jobs 係咪行緊
6. BUS inbox 有冇積壓訊息

常見問題
================================================================================

Q: SSH timeout？
A: 檢查 egress proxy 經唔經到。唔好直接 ssh，一定要經 ssh-via-proxy.py。

Q: Permission denied (publickey)？
A: key 未加去 server。加完要等一陣先生效。

Q: Google 登入唔到，話 "This browser or app may not be secure"？
A: Browser 冇加反 bot 參數。檢查 ignore_default_args 同 --disable-blink-features。

Q: 發咗召回句但 AI 冇反應？
A: 可能 phantom-send。Reload 驗證，睇吓有冇 ■。

Q: VNC 問密碼？
A: Xvnc 冇加 -SecurityTypes None。殺咗重開。

Q: Worker 唔覆 BUS？
A: Check 佢個 inbox 有冇積壓。再唔覆就經直接對話問。

Q: 有兩個 worker 共用同一個 BUS 名？
A: 舊嗰個可能未死。叫新嗰個 check process，用戶去 app 閂舊 session。

緊急情況
================================================================================

系統崩潰級（要即刻通知用戶）：
- Server 冧咗（SSH 唔到超過 10 分鐘）
- RELAY 斷咗超過 30 分鐘
- 所有 watcher 同時停咗

一般問題（自己搞掂，記 log）：
- 單一 tunnel 斷咗（watchdog 會自動重拉）
- 單一席位 watcher 停咗（重開就得）
- BUS 訊息 delay（等幾分鐘）

唔好做嘅嘢：
- 唔好清 Google（任何情況都唔准）
- 唔好喺 RELAY 講操作嘢
- 唔好一次過改多個席位嘅嘢（逐個嚟）
- 唔好假設，要驗證（process 存在唔等於 work 緊）

================================================================================
文件位置：
- 呢份：council-operations-manual.txt
- 詳細 watcher 流程：watcher-login-guide.txt
- Onboarding 模板：muse-onboarding-4phase.txt
- 主持指引：dj-host-guide.txt
全部喺 ~/workspace/your_files/ + http://149.118.48.126:8080/
================================================================================

【十一】關鍵 Code：vpn-tunnel.sh（2026-10-03 補）
================================================================================
用途：經 SSH 將 server 嘅 7 個 SOCKS5 proxy forward 到本地。watchdog 叫佢做重啟。

#!/bin/bash
# VPN SSH Tunnel 管理 - 彈性擴展版
# 配置檔: ~/workspace/vpn-tunnel/vpn-proxies.conf
# 用法: vpn-tunnel.sh start|stop|restart|status|test

CONF="$HOME/workspace/vpn-tunnel/vpn-proxies.conf"
SSH_KEY="/home/hatch/.ssh/id_ed25519"
PROXY_CMD="python3 /home/hatch/workspace/ssh-via-proxy.py %h %p"
SERVER="root@149.118.48.126"
PIDFILE="/tmp/vpn-tunnel.pid"

build_forwards() {
    local forwards=""
    while read -r name port ip desc; do
        [[ "$name" =~ ^#.*$ ]] && continue
        [[ -z "$name" ]] && continue
        forwards="$forwards -L 127.0.0.1:${port}:127.0.0.1:${port}"
    done < "$CONF"
    echo "$forwards"
}

do_start() {
    if [ -f "$PIDFILE" ] && kill -0 $(cat "$PIDFILE") 2>/dev/null; then
        echo "Tunnel 已在運行 (PID $(cat $PIDFILE))"
        return 0
    fi
    local forwards=$(build_forwards)
    echo "啟動 tunnel: $forwards"
    ssh -o BatchMode=yes -o ConnectTimeout=20 -o StrictHostKeyChecking=accept-new \
        -o ServerAliveInterval=10 -o ServerAliveCountMax=3 -o ExitOnForwardFailure=yes \
        -o TCPKeepAlive=yes \
        -i "$SSH_KEY" -o ProxyCommand="$PROXY_CMD" \
        -N $forwards "$SERVER" &
    echo $! > "$PIDFILE"
    sleep 3
    do_status
}

do_stop() {
    if [ -f "$PIDFILE" ]; then
        kill $(cat "$PIDFILE") 2>/dev/null
        rm -f "$PIDFILE"
        echo "Tunnel 已停"
    else
        echo "Tunnel 未運行"
    fi
}

do_status() {
    echo "=== Tunnel 狀態 ==="
    if [ -f "$PIDFILE" ] && kill -0 $(cat "$PIDFILE") 2>/dev/null; then
        echo "SSH: 運行中 (PID $(cat $PIDFILE))"
    else
        echo "SSH: 未運行"
    fi
    echo ""
    echo "=== 本地監聽 ==="
    while read -r name port ip desc; do
        [[ "$name" =~ ^#.*$ ]] && continue
        [[ -z "$name" ]] && continue
        if ss -tln 2>/dev/null | grep -q "127.0.0.1:$port "; then
            echo "  $name ($port): LISTENING"
        else
            echo "  $name ($port): DOWN"
        fi
    done < "$CONF"
}

do_test() {
    echo "=== VPN 出口 IP 測試 ==="
    while read -r name port ip desc; do
        [[ "$name" =~ ^#.*$ ]] && continue
        [[ -z "$name" ]] && continue
        actual=$(timeout 10 curl -s -x socks5h://127.0.0.1:$port https://api.ipify.org 2>&1)
        if [ "$actual" = "$ip" ]; then
            echo "  $name ($port): OK ($actual)"
        else
            echo "  $name ($port): FAIL (預期 $ip, 實際 $actual)"
        fi
    done < "$CONF"
}

case "$1" in
    start) do_start ;;
    stop) do_stop ;;
    restart) do_stop; sleep 2; do_start ;;
    status) do_status ;;
    test) do_test ;;
    *) echo "用法: $0 {start|stop|restart|status|test}" ;;
esac

【十二】關鍵 Code：tunnel-watchdog.sh（2026-10-03 補）
================================================================================
用途：每分鐘由 cron 執行，檢查 tunnel 健康，斷咗自動重拉。正常時靜默。

#!/bin/bash
# VPN Tunnel Watchdog - 每分鐘檢查，斷線自動重拉

TUNNEL_SCRIPT="$HOME/workspace/vpn-tunnel/vpn-tunnel.sh"
LOG="$HOME/workspace/vpn-tunnel/watchdog.log"
PIDFILE="/tmp/vpn-tunnel.pid"

log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG"
}

is_healthy() {
    # 1. PID 存在且進程運行
    if [ ! -f "$PIDFILE" ] || ! kill -0 $(cat "$PIDFILE" 2>/dev/null) 2>/dev/null; then
        return 1
    fi
    # 2. 7 個本地端口全部有監聽
    for port in 11080 11081 11082 11083 11084 11085 11086; do
        if ! ss -tln 2>/dev/null | grep -q "127.0.0.1:$port "; then
            return 1
        fi
    done
    # 3. 實際能通：抽查 3 個唔同 proxy
    for port in 11080 11083 11086; do
        if ! timeout 8 curl -s -o /dev/null -x "socks5h://127.0.0.1:$port" "https://api.ipify.org" 2>/dev/null; then
            return 1
        fi
    done
    return 0
}

if is_healthy; then
    exit 0
fi

log "Tunnel 異常，嘗試重啟..."
"$TUNNEL_SCRIPT" stop >/dev/null 2>&1
sleep 2
"$TUNNEL_SCRIPT" start >> "$LOG" 2>&1

sleep 5
if is_healthy; then
    log "Tunnel 重啟成功"
else
    log "Tunnel 重啟失敗，下輪再試"
fi

【十三】關鍵 Code：vpn-proxies.conf（2026-10-03 補）
================================================================================
# 名 port 預期出口IP 描述
JP1 11080 161.33.178.218 vpn-wg0
JP2 11081 151.145.67.176 vpn-wg1
JP3 11082 158.101.145.210 vpn-wg2
JP4 11083 140.245.82.16 vpn-wg3
ip2 11084 217.142.189.57 vpn-wg5
ip3 11085 217.142.189.119 vpn-wg6
ip4 11086 140.245.60.36 vpn-wg7

【十四】BUS 收發完整指令（2026-10-03 補）
================================================================================

發訊息俾 worker（主持 → worker）：
TS=$(date +%s)
echo '{"from":"host","to":"watcher-a567","timestamp":'$TS',"priority":"normal","type":"task","body":"..."}' \
  | ~/workspace/ssh-newserver.sh "cat > /root/muse-mesh/inbox/watcher-a567/${TS}-host.json && chmod 600 /root/muse-mesh/inbox/watcher-a567/${TS}-host.json"

收訊息（每分鐘掃 host inbox）：
~/workspace/ssh-newserver.sh "for f in /root/muse-mesh/inbox/host/*.json; do [ -f \"\$f\" ] || continue; echo \"=== \$f\"; cat \"\$f\"; echo; mv \"\$f\" /root/muse-mesh/sent/; done"

Worker 嗰邊收訊息（佢哋每分鐘做）：
~/workspace/ssh-newserver.sh "for f in /root/muse-mesh/inbox/watcher-a567/*.json; do [ -f \"\$f\" ] || continue; cat \"\$f\"; echo; mv \"\$f\" /root/muse-mesh/sent/; done"

【十五】RELAY 發帖完整指令（2026-10-03 補）
================================================================================

經 SSH 用 signed client post：
~/workspace/ssh-newserver.sh "cd /root/dj-relay && python3 -c \"
import json, secrets
text = open('/tmp/post.txt').read()
body = {'room_id':'COMMONS','data_class':'SYNTHETIC_PUBLIC_ONLY','text':text,'idempotency_key':secrets.token_hex(16)}
open('/tmp/p.json','w').write(json.dumps(body))
\" && chmod 600 /tmp/p.json && python3 /root/dj-relay/arc_agent_client.py request POST /v1/messages --body /tmp/p.json; rm -f /tmp/p.json /tmp/post.txt"

注意：一定要有 idempotency_key，唔係會 400 INVALID_SCHEMA。Text 上限 4000 chars。

RELAY poll（睇新訊息）：
~/workspace/ssh-newserver.sh "cd /root/dj-relay && printf '{\"after_sequence\":<N>,\"wait_seconds\":10}' > /tmp/p.json && chmod 600 /tmp/p.json && python3 /root/dj-relay/arc_agent_client.py request POST /v1/events/poll --body /tmp/p.json; rm -f /tmp/p.json"