チャット連携

trackica のエージェントを Feishu、Lark、Slack、DingTalk、WeCom、Telegram に接続し、チームが普段使っているチャットツールから利用する方法を説明します。

チャット連携を使うと、trackica を開かなくても、エージェントへの質問、グループチャットでの @メンション、チャット画面からのイシュー作成ができます。

現在は Feishu/Lark、Slack、DingTalk、WeCom、Telegram に対応しています。セッション、ユーザー識別、実行の仕組みは共通ですが、インストール方法が異なります。

プラットフォームを選ぶ

	Feishu / Lark	Slack	DingTalk	WeCom	Telegram
インストール	trackica で QR コードを生成し、Feishu でスキャンして認証	Slack でアプリを作成し、2 つのトークンを trackica に入力	社内アプリと Stream モードのロボットを作成し、AppKey と AppSecret を trackica に入力	WeCom 管理コンソールで常時接続を有効にしたスマートボットを作成し、Bot ID と Secret を trackica に入力	@BotFather で Bot を作成し、token を trackica に入力
エージェントとの DM	対応	対応	対応	対応	対応
グループまたはチャンネル	Bot を @メンションするとトリガー	Bot を @メンションするとトリガー	Bot を @メンションするとトリガー	Bot を @メンションするとトリガー	Bot を @メンション、または Bot に返信するとトリガー
イシューの作成	`/issue` メッセージコマンド。入力内容からそのまま作成	`/issue` スラッシュコマンド。エージェントが説明を整理してから作成	`/issue` メッセージコマンド。入力内容からそのまま作成	`/issue` メッセージコマンド。入力内容からそのまま作成	`/issue` メッセージコマンド。入力内容からそのまま作成
接続方式	プラットフォームの常時接続	Socket Mode	Stream モード	プラットフォームの常時接続	`getUpdates` long polling

新規接続は現在、中国本土版の Feishu でのみ利用できます。既存の国際版 Lark 接続は、引き続き利用および管理できます。

各 Bot は 1 つの trackica エージェントに紐づきます。同じチャットプラットフォームで複数のエージェントを使う場合は、エージェントごとに Bot を接続してください。

DingTalk、WeCom、Telegram はコミュニティメンテナンスです。各リリースに含まれますが、公式サポート SLA はありません。問題は GitHub issues で報告してください。

WeCom が現在扱えるのはテキストメッセージのみです。音声、画像、ファイルのメッセージにはその旨の短い返信が返り、エージェントには渡されません。

Telegram が現在扱えるのはテキストメッセージのみです。未対応のメディアにはその旨の短い返信が返り、エージェントには渡されません。

詳しい手順:

メッセージが処理される流れ

trackica が Bot に対応するワークスペースとエージェントを特定します。
グループやチャンネルでは、Bot を明示的に @メンションしたメッセージだけを処理します。DM では @メンションは不要です。
trackica が送信者のアカウント連携とワークスペースのメンバー資格を確認します。
メッセージがエージェントとのチャットセッションに追加され、タスクが作成されます。
エージェントの返信が元の DM またはスレッドに返されます。

Bot を @メンションしていないチャンネルメッセージは、エージェントをトリガーせず、会話コンテキストにも追加されません。

通常のメッセージはこの流れで処理されます。/issue はコマンドであり、チャットのターンではありません。trackica は元のプラットフォームに結果を返しますが、コマンド自体は trackica Chat に追加しません。Slack のネイティブスラッシュコマンドは、独立した非同期のタスク作成フローで処理されます。

セッションの分離

Feishu/Lark はチャットごとにセッションを分けます。同じチャットの後続メッセージは同じセッションを継続します。
Slack は DM をチャンネルごとに分けます。チャンネル内では、スレッドごとに独立したセッションが保持されます。
DingTalk は conversation ごとにセッションを分けます。DM とグループはそれぞれのセッションを継続します。
WeCom はチャットごとにセッションを分けます。DM とグループチャットはそれぞれのセッションを継続します。
Telegram はチャットごとにセッションを分け、forum topic は topic ごとに分離します。

チャンネルで追加の依頼を送る場合も、Bot を再度 @メンションする必要があります。エージェントが受け取るのは自分宛てのメッセージだけで、チャンネルの履歴全体を自動的に読み取ることはありません。

アカウント連携

メンバーが初めて Bot にメッセージを送ると、アカウント連携用のリンクが届きます。trackica にログインすると、チャットプラットフォームのアカウントが現在のワークスペースのメンバー資格に紐づきます。

trackica がエージェントを実行するのは、アカウント連携が完了した後だけです。メッセージを受け取るたびにアカウント連携とワークスペースのメンバー資格を再確認するため、ワークスペースから退出した後は Bot 経由でアクセスできません。

アカウント連携は送信者の本人確認にのみ使われます。チャットプラットフォームのほかのメンバーが trackica ワークスペースへ自動的に追加されることはありません。

接続を管理する

ワークスペースの owner と admin は Bot を接続または切断できます。Feishu/Lark Bot の場合は、エージェントの所有者も接続と切断ができます。通常のメンバーは接続済みの連携を確認し、自分に実行権限があるエージェントを利用できます。

切断すると、Bot は新しいメッセージを受信しなくなります。既存の trackica の会話と実行記録は保持されます。

セルフホスト

セルフホスト環境では、trackica が接続エンドポイントを有効にする前に、プラットフォームごとに 32 バイトの暗号化キーを設定する必要があります。

TRACKICA_LARK_SECRET_KEY=<base64-encoded 32-byte key>
TRACKICA_SLACK_SECRET_KEY=<base64-encoded 32-byte key>
TRACKICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>
TRACKICA_WECOM_SECRET_KEY=<base64-encoded 32-byte key>
TRACKICA_TELEGRAM_SECRET_KEY=<base64-encoded 32-byte key>

これらのキーは、保存された Bot の認証情報を暗号化します。プライベート環境での生成、保管、ローテーション方法は環境変数を参照してください。

WeCom はさらにバックエンドを単一レプリカで運用する必要があります。送信経路が 1 つのプロセスが保持する WebSocket だけのため、他のレプリカで生成された返信は破棄されます。レプリカ間の送信ルーティングが実装されるまで、WeCom を有効にしたバックエンドは多重化しないでください。