Docs / 開発

Developer Guide

ローカル開発、変更箇所の見つけ方、検証、ドキュメント更新。

Setup

git clone --recurse-submodules https://github.com/tqmane/vyline.git
cd vyline
bun install --frozen-lockfile
bun run typecheck
bun run lint
bun test
bun run build

Bun 1.4+。workspaceは Vyline/packages/*、desktop app、backend等を含み、Protocol/Plugin/Themesはsubmoduleです。

開発サーバー

bun run dev
# backendのみ:  bun run dev:backend
# frontendのみ: bun run dev:frontend

dev:backendはBun watchでVyline/backend/src/index.tsを再起動し、dev:frontendはVite dev serverを起動します。本番buildではFrontendをstatic assetへbuildし、Bun/Hono backendが同じprocessから配信します。

変更箇所の見つけ方

変更したいもの	まず見る場所
Web UI	`Vyline/apps/desktop`
HTTP API / DB / restore	`Vyline/backend`
LINE RPC / E2EE / login	`Vyline/packages/protocol`
Plugin contract	`Vyline/packages/plugin` + Backend plugin runtime
Theme preset	`Vyline/packages/themes`
Desktop LINE reverse research	`tools`

処理を追うときの順番

処理	Frontend	Backend	Protocol
初期表示	`useLineData.ts` → `api.line.bootstrap`	`GET /line/:accountId/bootstrap` → SQLite	通常RPCなし
新着	`useVylineSync.ts` / `pollIncoming`	event buffer / `processFetchedOperations`	`base.talk.sync`
active chat差分	`pollMessagesDelta`	`/messages/:chatMid/delta`	必要に応じてremote fetch
送信	`api/client.ts`	`api/line.ts` → `lineService.sendMessage`	Talk / E2EE
login	auth UI/client	`clientManager`	QR / Email / Token + E2EE ensure
media	upload/download API	`lineService` / media storage	Talk metadata + object storage/E2EE

不具合を追うときは、UIからProtocolへ直接飛ばず、Frontend request → BFF route → service → session manager → Protocolの順に境界を確認します。

Backend APIを変更するとき

Vyline/apps/desktop/src/api/client.tsのclient contractを確認する。
Vyline/backend/src/api/line.tsでは入力検証、status code、HTTP serializationを扱う。
LINE/DBを伴う処理はservice/lineService.tsまたは対象serviceへ置く。
account/sessionが必要ならline/clientManager.tsの既存queue/urgent/send経路を使う。
保存状態を変えるならstorage層とrestore/backupの整合も確認する。
route/serviceのtestを追加し、Frontend型と実responseを合わせる。

api/line.tsへ大きな業務ロジックを積まないのが現在の境界です。同じ操作を別endpointや将来のconsumerから使えるよう、HTTPに依存しない処理をserviceへ残します。

Protocolを変更するとき

RPCを追加・変更する場合は Vyline/packages/protocol/src/dictionary/rpcMap.ts で既存対応を確認し、Desktopの根拠、Protocol stack、domain facade、Backend service/BFFの順に追います。

rpcMap.ts
  canonicalName / desktopEvidence / path
        ↓
stack API / Thrift types
        ↓
domain API
        ↓
backend lineService
        ↓
api/line.ts
        ↓
frontend api/client.ts

Desktop更新起因の不具合は bun run vyline:delta や bun run vyline:find-native -- <name> で現在の実体を確認します。modules.map.tsのfeatureから関連binary、search string、analysis docsを絞れます。

Storageを変更するとき

chat runtime persistenceはSQLiteで、chatStoreSqlite.tsがWAL mode、schema version、chats/messages/message_sync/local_read等を管理します。履歴全体を起動時にメモリへhydrateする設計ではありません。

既存schemaとPRAGMA user_versionの扱いを確認する。
既存DBを壊さず前方migrationできる変更にする。
restore/importはstagingまたはcopy上で検証し、失敗時に元DBを部分更新しない。
Dockerでは/app/dataと/app/storageのどちらへ置くデータかを決める。
backup quota、media sidecar、cache削除時の意味も確認する。

cacheと永続データを混同しません。再生成可能なCDN/icon cacheと、session/chat DB/saved media/backupでは削除時の影響が違います。

Plugin / Themeを変更するとき

Plugin contractはsubmoduleの@vyline/plugin-sdk、実行とaccountごとのenable状態はBackendのpluginRuntime.ts/pluginManager.tsが担当します。pluginのactivate/deactivateやevent handlerは本体を落とさないよう隔離されます。

permission文字列をmanifestへ追加するだけではcapabilityは増えません。SDK型、Backend contextで実際に公開しているmethod、manager側のpermission handlingを揃えて確認します。ThemeはVyline/packages/themesのVyThemeとpreset tokenを正にします。

検証の段階

bun run typecheck
bun run lint
bun test
bun run build

この4つが通っても実LINE sessionやDocker deploymentまで証明したことにはなりません。変更内容に応じてlocal backend API、browser UI、Docker image、実sessionの順に追加検証します。

Docsサイト更新

web/ は手書きの静的HTML/CSS/JavaScriptです。ページを変更するときは対象の web/docs/<page>/index.html を直接編集し、共通スタイルは web/assets/vyline.css、Docsの検索・テーマ・目次・コピー処理は web/assets/docs.js で管理します。

Web Docsの自動生成スクリプトは使いません。実装変更を説明するページだけを、その実装と既存docsを読み直して更新します。変更後はローカルHTTP serverで表示とリンクを確認してください。

README

README.src.md がREADMEの編集元です。日本語・英語の生成はWebサイトとは別系統で、変更後に bun run docs:readme を実行します。Web Docs自体は生成せず、対象HTMLを直接更新します。