agilab-source-connectors の俯瞰

AGIラボには既に backend / Discord / note / X / vault / Cloudflare / Supabase など、データを持っている場所が散らばっている。 それぞれに API・CLI・vault skill・OSS が既にある。 このワークスペースは、その 「読む側のインターフェース」 を 1 ヶ所に揃える役割を持つ。 新しいデータ源を作るのではなく、既存ソースを compact / 一定の形 / 安全な経路 でアクセスできるようにすることが目的。

connectors/ がソース別アダプタの本体、sources/ は参照用の外部 repo checkout、state/ は生成 snapshot、logs/ と tmp/ はランタイム作業領域。 書き込み可能なのは connectors/ と state/ のみで、それ以外は read-only の慣習。

Connector は 1 source = 1 connector の原則で作る。 1 つの connector に全てを知らせず、上位レイヤで複数 connector の出力を組み合わせる方針。 CLI 風のインターフェース（実装が API ラッパでも script でも）を共通化することで、呼び出し側のコードを安定させる。

全ソースを同時に着手するのではなく、 1 つずつ 「最初に役に立つ snapshot」 まで持っていく。 これを破ると、 connector が中途半端な状態で並んで、 どれも使えない状況になりがち。

全 8 ソースの推奨 build order と、各ソースで最初に達成する「役に立つ snapshot」の定義。 Discord は vault 側に既に強い資産があるので 「rebuild せず wrap する」 のが規律。 Instagram は最後に着手して、 X / note の出力 schema が固まってから合流する。

Current Priority — 4 ステップ

最初に組み立てた connector。 connectors/agi-backend/ 配下に README / manifest / check スクリプトが揃っている。 まだ aggregate snapshot 出力は実装されておらず、 ローカルテストの状況を見ながら次に進む段階。

Health check スクリプト — scripts/check.sh

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORKSPACE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
REPO="${AGI_BACKEND_REPO:-$WORKSPACE_ROOT/sources/agi-backend}"

if [[ ! -d "$REPO/.git" ]]; then
  echo "missing_repo path=$REPO"
  exit 1
fi

cd "$REPO"
echo "repo=$REPO"
echo "head=$(git rev-parse --short HEAD)"
echo "status=$(git status --short | wc -l | tr -d ' ') changed_files"

if [[ -x ./node_modules/.bin/wrangler ]]; then
  echo "wrangler=$(./node_modules/.bin/wrangler --version)"
else
  echo "wrangler=missing"
fi

if [[ "${1:-}" == "--test" ]]; then
  npm test -- --run
fi

Next useful step

connector を増やしていく途中で、 ここを甘くすると 1 ヶ月後に「何を信じていいか分からない workspace」になりがち。 4 つの境界線を最低限維持する。

このページから何を読み始めればよいか、 役割別の最短ルート。 ローカルに repo がある場合のコマンド例も載せている。

# 1. ワークスペースに移動
cd /Users/kai/Develop/airi-source-connectors

# 2. agi-backend connector の health check (read-only)
connectors/agi-backend/scripts/check.sh

# 3. オプション: upstream tests を流す
connectors/agi-backend/scripts/check.sh --test

# 4. 設計を眺める
cat connectors/README.md
cat connectors/source-catalog.md
cat HANDOVER.md