自動化

Feishu

Feishu 対応は、1 台のマシンの hylad に 1 つの Feishu アプリを接続します。ボットにメッセージを送るか、グループで @ メンションすると、Hyla セッションのコーディングエージェントがそれを受け取ります。回答はカードとしてチャットに返ります。セッションは Hyla のサイドバーに残るので、Feishu で会話を続けながら、見ることもターミナルから引き継ぐこともできます。

この考えは MetaBot から来ています。MetaBot は Feishu などのチャットチャネルをコーディングエージェントにつなぎます。Hyla は別のやり方をします。MetaBot は自身のエンジンを動かします。Hyla は すでにあるセッションを使います: そのプロセス、エージェント検出、会話履歴、状態、ほかのホストへのアクセスです。

アーキテクチャ

text
Feishu Open Platform
   |  a long-lived WebSocket (im.message.receive_v1 events)
   v
hylad -- internal/feishu
   |-- IM adapter      messages  <->  commands, reply cards
   |-- Bridge          the binding of a chat to a session, the replies to Feishu
   |-- Prompt host     the prompts in the session's pane
   +-- existing code   detect / resume / pane.report / notify
   ^
   |  the same RPC
Hyla app (the session is visible, and can be taken over)
hyla CLI
other hosts

ボットは Feishu への長寿命の WebSocket を保ちます。Feishu はこれを「長接続」と呼びます。短い接続には webhook 用の公開 HTTPS エンドポイントが必要です。長接続はポートを開けません。

hylad で動かす理由

選択 得られるもの 失うもの
MetaBot のように別プログラム 機能がそろっている 2 つ目のランタイムと 2 つ目のセッション一式。Hyla のペインを操作も引き継ぎもできない
ここで設計したように hylad 内 エージェント検出、会話の再開、状態、ホスト、1 つのバイナリ。チャットの作業がアプリに見える hylad にコードが増える
アプリ内 ボットはアプリが終了すると止まる アプリが App Secret をバックグラウンドで持ち、アプリが閉じていると hylad の助けがない

どの場合もプロンプトは hylad を通ってペインに入ります。後の段階で IM アダプターをアプリに移し、アプリがすでに持つ hylad への接続からペインに入れられます。hylad は変わりません。

Feishu のコマンド

コマンド 何をするか
/new [プロジェクト] [エージェント] プロジェクトでセッションを始め、ペインでエージェントを動かし、チャットをそれに結び付けます
/use <セッション> 名前か ID の先頭で、開いているセッションにチャットを結び付けます
/ls 開いているセッションを一覧し、それぞれに状態の点を付けます
/status 結び付いたセッションの状態、ブランチ、変更、ディレクトリを表示します
/stop 今のターンを中断します(Ctrl-C)
/answer <テキスト> エージェントの質問に答えます
/close 結び付いたセッションを、確認のあと終えます

コマンドでないテキストはプロンプトとして結び付いたセッションへ送られます。グループでは、ボットを @ メンションしたメッセージだけがそうします。別のボットへの @ は含みません。グループの会話はそれぞれ自分のスレッド(「トピック」)を持ちます。

コマンドモード

feishu-run = command では、hylad がプロンプトごとにエージェント自身のコマンドをターミナルなしで動かします:

text
claude -p --output-format text --session-id <id> "<prompt>"    # Claude Code
pi -p --session-id <id> "<prompt>"                              # Pi
gemini -p "<prompt>"                                            # Gemini CLI
opencode run "<prompt>"
codex exec "<prompt>"
dsh headless --json --session-id <id> "<prompt>"                # DSH

各コマンドはチャットのセッションで動きます。そのセッションにはターミナルもシェルもありません。動いているあいだサイドバーは working を、終わると idle を表示します。feishu-dir のディレクトリで、ペインと同じ環境で動きます。出力は hyla のディレクトリの feishu-run 下のファイルに書き込まれ、そのテキストが返信になります。チャットは会話を続けます。最初のターンは hylad が作った ID でセッションを始め、次のターンがそれを続けます:

エージェント 最初のターン 次のターン
Claude Code --session-id <id> --resume <id>、または結果が示す ID
Pi --session-id <id> --session-id <id>
Gemini --session-id <id> --resume <id>
OpenCode run "<prompt>" run --session <id>。出力がセッションを示す
Codex exec "<prompt>" exec resume <id> --skip-git-repo-check。出力がセッションを示す
DSH headless --json "<prompt>"。DSH は --permission-mode を受け付けず、設定 DSH_PERMISSION_MODE を使う。出力がセッションを示す headless --json --session-id <id> "<prompt>"。DSH は知らない ID で失敗する

/new <プロジェクト> <エージェント> は別のエージェントで新しい会話を始めます。

返信はコマンドの出力です。Claude Code では、feishu-agent-command で --output-format stream-json を使うコマンドは、ストリーム全体ではなくメッセージのテキストを返します。DSH では、最初のイベントがセッションを示し、final イベントが答えです。

バックグラウンドのコマンドはペインへの入力を持ちません。そのようなセッションでの /answer はそう答えます。

ターンの権限

コマンドモードでは Claude Code のターンはメッセージのストリームで動きます。ターンがツールの権限を必要とすると、Claude Code はそのストリームで要求し、hylad はその要求をターンの出力の隣のファイルに書きます。ボットはチャットにカードを送り、ツールと、使うコマンド、ファイル、またはアドレスを書きます。カードには三つのボタンがあります。

ボタン 動作
1 回だけ許可 このターンだけツールを実行します。
常に許可 このターンでツールを実行し、このチャットの次のターンはそのツールを要求しません。
拒否 このターンはツールを実行しません。カードの見出しの下に書いた理由はエージェントに渡ります。

ターンは回答があるまで待ちます。タイムアウト(feishu-timeout)したターン、または回答なしで終わったターンは、残りの権限を拒否します。

コマンドモードのほかのエージェントは、権限の要求なしでツールを実行します。

セッションモード

ボットはプロンプトをペインに入力して Enter を押し、ターンが終わるまでペインを追います: エージェントがユーザーを待つ、または働いたあと画面と状態が静かになるまでです。状態がずっと「working」と言わないターンも、画面が止まれば終えます:

  • 画面がプロンプトの前と同じで、回答も出ない場合、ボットは「Hyla はターンのテキストを以前のものと区別できません」と返信します。
  • ペインが 5 秒を超えて「working」のままで、作業の兆しがない場合、ボットはターンが終わったものとします。

feishu-timeout のあともエージェントが働いている場合、返信はそう伝えます。

ターンの回答

ターミナルの画面はきれいな回答ではありません。TUI の枠やステータスバーを含みます。Claude Code では、hyla skill setup が入れる Stop フック(hyla answer claude)が、ターンが終わるたびにエージェントの最後のメッセージを、ボットがペインに渡したファイル(hylad のディレクトリの feishu-answers)に書き込みます。ボットは画面のテキストではなく、そのメッセージで返信します。ほかのエージェントに使える Stop フックはなく、ボットはターミナルのテキストを使います。

ボットがペインにファイルを渡していなければ、hyla answer は何もしません。Hyla の外でも、どんなエラーでも何もしません: エージェントを失敗させることはありません。

チャットビュー

チャットは、セッションのペインにターミナルの代わりに表示されます。セッションメニューの 会話、またはペインヘッダーのチャットボタンをクリックして開きます。ペインは単独で表示され、チャットに十分な場所ができます。ヘッダーのボタンでターミナルに戻ります。チャットには、そのセッションのチャットが表示されます:

  • ユーザーのプロンプトは右側、アクセント色の吹き出し;
  • エージェントの思考は淡い文字;
  • エージェントが実行したツールとその出力はそれぞれ淡い一行:ツールをクリックすると引数と出力全体が開きます;
  • エージェントのメッセージは左側で、ターンの回答は濃い背景にします。

メッセージは Markdown として表示されます。見出し、リスト、引用、表、コードブロックは整形され、リンクはブラウザで開きます。

会話は固定幅の列でペインの中央に表示されます。ペインが狭くなると列も狭くなります。

この表示は会話を見せるだけです。入力欄はありません。プロンプトは Feishu で送ってください。チャットを開いたときと、ホストの状態が変わるたびに、セッションのホストが feishu.feed でチャットを読みます。

Feishu では、1 ターンは 1 枚のカードで表示されます(feishu-cards)。グループのトピックのリクエストは、カードもそのトピックに投稿されます。ターンが始まるとボットがカードを送り、見出しは実行中であることを示します(🔵 Running…)。ユーザーのメッセージはそのまま残り、OnIt のリアクションだけが付きます。エージェントが作業している間は feishu-stream の間隔で、実行中のツールと書いている途中のテキストをカードに表示します。バックグラウンドのコマンドで動く OpenCode のターンは OpenCode のサーバーが逐次報告し、ペインのターンは端末の末尾の行を取ります。ターンが終わると同じカードが回答になり、見出しのアイコンと色が状態(🟢 回答、🟡 質問、🔴 エラー)に変わり、リアクションは外れます。本文は Markdown で、下部は小さな 1 行で、まず色付きタグで状態、次に使用したモデル、続いて使用量(↑入力 · ↓出力 · cache · ctx 使用量/上限 パーセント)と所要時間(1m24s など)を表示します。値がわからない項目は表示しません。使用量と所要時間を報告するのは Claude Code のコマンドモードだけです。Feishu がカードの更新を拒否した場合(更新が頻繁すぎるなど)は、回答を新しいカードとして送るので、回答が失われることはありません。

選択肢のある質問

エージェントが選択を求めると、ターンのカードに質問と、選択肢ごとのボタンがあります。ボタンの下の入力欄には、自分で書いた回答を入れられます。エージェントのテキストの末尾にある、二つ以上の選択肢のリストが対象です。前の行の質問は : か ? で終わります。各行が番号(1.、2))、文字(A.、B))、または括弧((Red)、(Red))で始まるリストを選択肢とします。「1. インストール、2. 実行」のような手順のリストは質問ではありません。

ボタンを押すと、bot は質問と選んだ選択肢のテキストをエージェントに送り、カードに回答を表示します。入力欄の回答も同じように送ります。質問の回答は一つだけです。エージェントは回答からターンを続け、次の回答は新しいカードです。

ボタンはカードだけに表示されます。feishu-cards = false のときは、/answer かメッセージで回答してください。

設定

ini
# ~/.config/hyla/config

# The same Feishu app may connect from more than one machine. By
# default, only the machine the chat is bound to receives its events.

feishu-app = bot:cli_a1b2c3d4   # the app's App ID; every machine writes the same name
feishu-allow = *                # who may use it: open_id, user_id or email; repeat it

# All machines
feishu-timeout = 30m            # the longest a turn waits
feishu-stream = 2s              # how often a card updates

# While the bot is connected, hylad stays even with no session open:
# sessions started from Feishu restore after a hylad restart.

# This machine
feishu-run = command            # how a prompt runs its agent: command, in the background; or session, in a pane
feishu-agent = claude           # the agent for new sessions and commands; default uses the new session's program
feishu-dir = ~/code/repo        # where new sessions start when you name no project

# One line for each agent, by the name the detector uses
feishu-agent-command = claude=claude --permission-mode acceptEdits
feishu-agent-command = codex=codex --full-auto
feishu-agent-command = pi=pi
キー 既定値 説明
feishu-app 空 Feishu アプリの App ID。空なら Feishu は無効です。
feishu-allow 空 プロンプトを送れる人: open_id、user_id、email。空なら hyla feishu setup を実行したユーザーだけです。
feishu-timeout 30m ターンが待つ最長時間。超えるとカードがタイムアウトを示します。
feishu-stream 2s 作業中のカードが新しいテキストを取り込む間隔です。
feishu-cards true 1 ターンを 1 枚のカードで表示します。開始時は見出しが実行中を示し、実行中はユーザーのメッセージにリアクションが付き、終了時に同じカードが回答になります。本文は Markdown です。false にすると返答は通常のメッセージになり、カードもリアクションも表示しません。
feishu-run session プロンプトがエージェントを動かす方法: command はバックグラウンドでエージェント自身のコマンド、session はセッションのペインでユーザーのターンとして。
feishu-agent default /new セッションが動かすエージェント: default、または検出器が知る名前(claude、codex、opencode、pi、dsh)。
feishu-dir 空 メッセージがプロジェクトを名指さないときに、新しいセッションが始まるディレクトリ。空なら new-session-directory です。
feishu-agent-command 空 名前=コマンド、エージェント名ごと: そのエージェントを動かすコマンド。載っていないエージェントは、引数なしでプログラムを実行します。コマンドは ~/ で始められます。

エージェントの環境

hylad は自分自身の環境でタスクを起動します。その環境は launchd のジョブのものです。PATH はユーザーのログインシェルの PATH に、エージェントの導入先(~/.local/bin、~/.bun/bin、~/.cargo/bin、nvm と fnm の Node、/opt/homebrew/bin、/usr/local/bin)を続けたものです。ログインシェルの PATH は 1 分に 1 回まで読み直します。エージェントが見つからないときは、feishu-agent-command でそのコマンドを指定します。

App Secret

App Secret は設定ファイルにありません。設定ファイルはよくコピーされ、バックアップされ、dotfiles に同期されますが、App Secret は長寿命の資格情報です。hylad は hylad.lock の隣のファイルに、あなたのアカウントだけが読めるように保存し、hyla feishu setup が書き込みます:

sh
hyla feishu setup     # asks for the App ID and App Secret, connects, and checks the app's settings
hyla feishu status    # whether the bot is connected

hyla feishu setup は Feishu アプリを段階ごとに確認します: ボット機能、im:message と im:resource の権限、im.message.receive イベント、公開済みのバージョン。ある段階が失敗すると、その段階と、Feishu 開放平台のコンソールで何を変えるかを示します。

設定ウィンドウはアプリ名、接続状態、使える人を表示します。App Secret は決して表示しません。情報ビュー(⌥⌘I)も、feishu-app にアプリがあるあいだ Feishu カードを表示します: App ID、ボットが接続しているか、使える人。

Hyla との組み合わせ

  • エージェント検出が、エージェントが作業中か、回答を待つか、アイドルかをブリッジに伝えます。
  • 会話の再開により、hylad が再起動しても何も失いません: セッションとエージェントの会話はほかのセッションと同じように戻ります。
  • ファイルペインは、どのセッションでも同じように、エージェントが変えたファイルを開きます。
  • ホストは -H とともに働きます: Feishu のコマンドは結び付いたセッションのホストで動きます。

複数ホストとグループ

  • 既定では、1 つのチャットのイベントは 1 台のマシンが受け取ります: チャットが結び付いたマシンです。
  • 複数のマシンが同じアプリに接続すると、feishu-host がチャットのメッセージを送るホストを決め、/host がチャットでそれを変えます。
  • グループのメッセージはボットを @ メンションしたときだけ作用します。別のボットへの @ は対象外です。返信は会話のスレッドに送られ、グループ全体には送られません。

セキュリティ

  • Feishu のメッセージはあなたのシェルへの入力です。 エージェントはペインで入力したときと同じく、あなたのアカウントの権限で動きます。feishu-allow が送れる人を制限します。あなたが加えない限り、hyla feishu setup を実行したアカウントだけが許されます。* はボットに届く誰でも許します。
  • ブリッジは、ボット自身が送るメッセージ、ほかのアプリのメッセージ(app_id が一致する必要があります)、event_id で見た重複イベントを無視します。
  • カードのボタンは、チャットの持ち主か feishu-allow に載った人だけに作用します。
  • ログと hyla clients は App Secret を決して表示しません。

依存関係

必要 選択
Feishu API、長接続、イベントの配信 公式 Go SDK github.com/larksuite/oapi-sdk-go/v3
カード アダプターが組み立てる JSON。長いテキストには collapsible_panel
カードのボタンイベント 後の段階。今はテキストコマンド

段階

段階 内容
M1: 接続 feishu-* キー、hyla feishu setup、status、test、send、長接続、feishu-allow、/new、/use、/ls、/status、/stop、/answer、/close、@ メンションのグループ、結び付いたセッションへのテキスト、ターンが表示したもののテキスト返信
M2: プロトコル アイドル、待ち、タイムアウトの待機。更新するカード。working、waiting、error の色
M3: 体験 @ メンションとスレッドのグループ。セッションにコピーされる画像とファイル。ボタンと「Hyla で開く」
M4: すべてのエージェント 各ターンの回答をファイルに書く: Claude Code の Stop フック(hyla answer)。ファイルがなければターミナルのテキスト
M5: 複数のマシン 1 つのアプリのイベントが複数のマシンに届く方法。/host
M6: 仕上げ ストリーミングカード、Markdown、設定 › エージェント › Feishu、このページの日本語と中国語版

リスク

  1. ターミナルの画面はきれいな回答ではありません。 TUI の枠やステータスバーを含みます。ターンの回答ファイルが主な対策です。ターミナルのテキストはフックのないエージェントの代替です。
  2. 貼り付け。 貼り付けた複数行のプロンプトで、各行の後に Enter を押してはいけません。プレフィックスはブラケットペーストを使う必要があり、プロンプトはすでに使っています。
  3. Feishu アプリの設定はあなたが行います。 設定の確認は、何が足りないかを正確に示す必要があります。さもないと最初の接続が理由なく失敗します。