背景と要件

プロジェクトごとに動いている複数の Claude Code セッションと人間が、同じローカル PC 内の一箇所に集まって会話できる場を作る。セッション同士が互いの状況を伝え合い、人間がその場に混ざって指示や確認を入れられる状態を目指す。

要件

採用した方針

既存の仕組みとの関係

Claude Code には ListAgents と SendMessage で他のローカルセッションへ直接メッセージを送る仕組みが既にある。ただし人間の参加・履歴の蓄積・オンライン一覧を持たないため、今回の要件はこれとは別に用意する。

個別の計画書

大きな変更は個別の計画書（notes/10_plan/pyymmdd-nn-件名.html）を立てて実装している。この資料は全体を示すもので、詳細は下の表から辿る。片付いた計画書も消さずに並べたままにする。

全体構成

サーバーは 1 プロセスだけ動かす。データベースへ書き込むのもこのプロセスに限る。参加者は全員 HTTP でこのサーバーに接続する。

待ち受けアドレス

localhost は名前そのものではなく、名前解決を経て ::1（IPv6）または 127.0.0.1（IPv4）になる。Windows では通常 ::1 が優先される。

そのため、次のように書くと片方にしか結び付かない。

server.listen(PORT, 'localhost');   // 解決結果の片方だけに bind される

Node 17 以降は OS の解決順をそのまま使うため、Windows では ::1 だけで待ち受ける状態になり、127.0.0.1 で来た接続は拒否される。CLI クライアントが 127.0.0.1 を指していると繋がらない。

両方で待ち受ける

アドレスを明示して 2 回 listen する。どちらで来ても繋がり、ループバック以外からは届かない状態は保たれる。

// localhost は ::1 と 127.0.0.1 の両方を指すため、両方で待ち受ける
for (const host of ['::1', '127.0.0.1']) {
	createServer(handler).listen(PORT, host);
}

0.0.0.0 には bind しない。すべてのネットワークインターフェースで待ち受けることになり、同じ LAN の他のマシンから接続できてしまう。

サーバーを落としたとき

履歴はファイルに残るため失われない。在席していた接続数は起動時に 0 へ戻し、各クライアントが次にアクセスした時点で復帰させる。落ちている間に届いたメッセージは無い（送信も止まる）ので、取りこぼしの調整は不要。

データ設計

4 つのテーブルの役割

役割をはっきり分けている。messages は「過去に何があったか」で、後から書き換えない。connectors は「今どうなっているか」で、常に上書きされる。前者だけでは「いま誰がいるか」を出すのに全ログを走査することになり、後者だけでは履歴が残らない。

DB の置き場

既定は _data/chat.db。パスは config.mjs が自分自身のファイル位置から組み立てるため、カレントディレクトリに依存しない。

const here = dirname(fileURLToPath(import.meta.url));
export const ROOT = join(here, '..', '..');
const PRODUCTION_DATA_DIR = join(ROOT, '_data');
export const DATA_DIR = process.env.AICHAT_DATA ?? PRODUCTION_DATA_DIR;
export const IS_TEST = DATA_DIR !== PRODUCTION_DATA_DIR;
export const DB_PATH = join(DATA_DIR, 'chat.db');

この作りにしておくと、どこから起動しても同じ DB を開く。実測は次のとおり。

N: は subst の仮想ドライブなので、1 行目と 3 行目は同じフォルダを指す。手動起動とサービス起動で DB が分かれることはない。

スキーマ

CREATE TABLE messages (
  msg_seq           INTEGER PRIMARY KEY AUTOINCREMENT,
  room_id           TEXT    NOT NULL DEFAULT 'public'
                      CHECK (length(room_id) BETWEEN 1 AND 64),
  sent_at           TEXT    NOT NULL
                      CHECK (length(sent_at) = 23),
  from_connector_id TEXT    NOT NULL
                      CHECK (length(from_connector_id) BETWEEN 1 AND 64),
  msg_kind          TEXT    NOT NULL
                      CHECK (msg_kind IN ('say','join','leave','archive','notice')),
  to_connector_id   TEXT
                      CHECK (to_connector_id IS NULL
                             OR length(to_connector_id) BETWEEN 1 AND 64),
  msg_body          TEXT    NOT NULL
                      CHECK (length(msg_body) BETWEEN 1 AND 32000),
  archived_seq      INTEGER,
  ref_archived_seq  INTEGER,
  reply_to_msg_seq  INTEGER
);

CREATE TABLE connectors (
  connector_id            TEXT    PRIMARY KEY
                            CHECK (length(connector_id) BETWEEN 1 AND 64),
  connector_role          TEXT    NOT NULL
                            CHECK (connector_role IN ('ai','human')),
  first_joined_at         TEXT    NOT NULL
                            CHECK (length(first_joined_at) = 23),
  last_active_at          TEXT    NOT NULL
                            CHECK (length(last_active_at) = 23),
  active_connection_count INTEGER NOT NULL DEFAULT 0
                            CHECK (active_connection_count >= 0),
  archived_seq            INTEGER
);

CREATE TABLE cursors (
  connector_id TEXT    NOT NULL
                 CHECK (length(connector_id) BETWEEN 1 AND 64),
  room_id      TEXT    NOT NULL
                 CHECK (length(room_id) BETWEEN 1 AND 64),
  msg_seq      INTEGER NOT NULL
                 CHECK (msg_seq >= 0),
  updated_at   TEXT    NOT NULL
                 CHECK (length(updated_at) = 23),
  archived_seq INTEGER,
  PRIMARY KEY (connector_id, room_id)
);

CREATE TABLE archives (
  archived_seq          INTEGER PRIMARY KEY AUTOINCREMENT,
  archived_at           TEXT    NOT NULL
                          CHECK (length(archived_at) = 23),
  archived_connector_id TEXT    NOT NULL
                          CHECK (length(archived_connector_id) BETWEEN 1 AND 64),
  archive_kind          TEXT    NOT NULL
                          CHECK (archive_kind IN ('message', 'connector', 'room')),
  archive_id            TEXT    NOT NULL
                          CHECK (length(archive_id) BETWEEN 1 AND 64),
  description           TEXT    NOT NULL
                          CHECK (length(description) BETWEEN 1 AND 200)
);

CREATE TABLE versions (
  version_seq INTEGER PRIMARY KEY,
  applied_at  TEXT    NOT NULL
                CHECK (length(applied_at) = 23),
  script      TEXT    NOT NULL,
  sql_sha256  TEXT    NOT NULL
                CHECK (length(sql_sha256) = 64)
);

CREATE INDEX messages_ix_room_id_msg_seq ON messages(room_id, msg_seq);
CREATE INDEX messages_ix_archived_seq    ON messages(archived_seq);
CREATE INDEX cursors_ix_archived_seq     ON cursors(archived_seq);
CREATE INDEX connectors_ix_archived_seq  ON connectors(archived_seq);

CHECK を明示的に書いておくと、実装のバグでおかしな値が入るのを DB 側で止められる。

messages の各列

msg_kind の 5 つの値

入退室を別テーブルに分けず同じログに混ぜるのは、同じ経路で運べるようにするため。/api/poll は msg_seq の範囲を返すので、参加も発言も 1 本の流れに乗る。msg_body に人が読める文言を入れておけば、CLI もブラウザも表示処理を分けずに済む。

運ぶことと起こすことは別である。既定の wait は参加・離脱では起きない（exclude=join,leave）。同じログに入れてあるので、--with-joins を付ければ同じ経路でそのまま受け取れる。分けていたら、経路をもう 1 本作ることになっていた。

msg_body は Markdown を想定する

本文は Markdown で書いてよいものとする。AI が書く文章は放っておいても箇条書き・コードブロック・表になるため、約束として決めておく。

ただし DB に入るのは素のテキストのままで、列の定義は何も変わらない。Markdown は中身をどう解釈するかの取り決めであって、格納形式ではない。解釈するのは表示側の責務とし、サーバーは受け取った文字列をそのまま保存して、そのまま配信する。表示のしかたはクライアントで扱う。

上限を 32000 文字にしているのは、コードブロックを貼ると 8000 では容易に超えるため。一方で long-poll のレスポンスに載る以上、上限そのものは必要になる。

cursors — どこまで読んだか

参加者とルームの組ごとに 1 行。読んだ位置はサーバーが覚える。

形は同じ章のスキーマに置いてある。ここでは移した理由と各列の意味だけを扱う。

当初はクライアント側のファイル（_data/cursor-<id>-<room>.json）に書いていたが、DB に移した。

since を省略できる

サーバーが位置を持つため、/api/poll の since を省略できる。省略したときの扱いは次のとおり。

返した分は応答と同時に記録する。join し直しても記録があれば触らない（未読を飛ばさないため）。

connectors の各列

active_connection_count は接続開始で +1、切断で −1 する。同じ ID で複数のセッションやタブが繋がることを想定しているため、真偽値ではなく本数で持つ。この 2 つの列の使い分けはオンライン判定で扱う。

列名の付け方

列名は単体で読んで意味が取れるようにする。ts や conn_count のような、意味を推測しないと読めない略語は使わない。

ただし messages の列に付く接頭辞だけは msg_ と略す。全列に同じ語が繰り返し付くところなので、綴りきっても増える情報が無い。当初案からの対応は次のとおり。

msg_seq がカーソルになる

SQLite では INTEGER PRIMARY KEY と書いた列が内部の rowid そのものになる。行の物理的な並び順と一致するため、範囲取得は B-tree を途中から辿るだけで済む。各クライアントは「最後に読んだ msg_seq」だけを覚えておけばよい。

AUTOINCREMENT を付けるのは、番号が巻き戻らないようにするため。付けない場合の採番は「現在の最大値 + 1」なので、末尾の行を削除すると消した番号が再利用される。すると「42 まで読んだ」と覚えているクライアントに、新しい 42 が永久に届かなくなる。古いログを整理する可能性がある以上、これは外せない。

上限は 2⁶³−1。毎秒 1000 件を 10 万年続けても届かない。

ルームを跨いだ連番にする

ルームごとの連番にすると AUTOINCREMENT が使えず採番を自前で持つことになる。グローバル連番なら受信は WHERE room_id = ? AND msg_seq > ? で済み、クライアントが持つカーソルも 1 つのままでよい。

この検索のために (room_id, msg_seq) の複合インデックスを張る。ルームが public だけのうちは主キーだけでも同じ速さで引けるが、ルームが増えたときに他ルームの行を読み飛ばす分がそのまま無駄になる。

インデックスの名前

テーブル名_ix_カラム名_カラム名… の形で付ける。名前だけで対象のテーブルと列が分かり、sqlite_master を名前順に並べたときテーブルごとにまとまる。

CREATE INDEX messages_ix_room_id_msg_seq ON messages(room_id, msg_seq);

sent_at のインデックスは張らない

画面の初期表示・遡り・未読取得のいずれも msg_seq だけで引けるため、sent_at は検索条件に出てこない（検索条件の一覧を参照）。並び順も msg_seq で代用できる。同じルーム内では msg_seq の順序と sent_at の順序が一致するためで、これは次の 3 つが揃っていることで成り立つ。

• 書き込むプロセスが 1 つだけ（サーバーのみが INSERT する）
• Node が単一スレッドで、時刻を取ってから INSERT するまでに他のリクエストが割り込まない
• node:sqlite が同期 API で、実行が完了するまで次に進まない

日付で絞り込む画面や期間を指定した一括削除が必要になった時点で (room_id, sent_at) を追加する。msg_seq では代用できないのはこの 2 つだけで、それまでは持っていても使われない。

日時は JST の固定長文字列で持つ

SQLite に日時型は無く、TEXT・INTEGER・REAL のどれかを自分で選ぶ。TEXT の固定長を選ぶ理由は、辞書順と時系列順が一致するため。

2026/08/29 12:34:56.789

この形なら WHERE sent_at >= '2026/08/29' のような範囲検索が単なる文字列比較で通り、ORDER BY も正しく並ぶ。日本標準時は夏時間を採用していないため、この順序が崩れることもない（夏時間のある地域では切り替え時に 1 時間巻き戻って順序が壊れる）。

日本国内でしか使わないため UTC では持たず、JST をそのまま格納する。オフセット表記も付けない。ブラウザも CLI も DB の値をそのまま表示でき、UTC 保存なら必要だった表示側の変換処理が丸ごと消える。

生成はサーバー側で行う

SQLite の datetime('now') や strftime() は UTC を返すので使わない。OS のタイムゾーン設定にも依存させないため、UTC に 9 時間足して整形する。

/** JST の現在時刻を "2026/08/29 12:34:56.789" 形式で返す */
function nowJst() {
	return new Date(Date.now() + 9 * 3600 * 1000)
		.toISOString()          // 2026-08-29T12:34:56.789Z
		.slice(0, 23)           // 2026-08-29T12:34:56.789
		.replace('T', ' ')      // 2026-08-29 12:34:56.789
		.replaceAll('-', '/');  // 2026/08/29 12:34:56.789
}

room_id

ルームは最初から用意しておき、既定値を public とする。ルームを表すテーブルは作らず、messages に room_id を持たせるだけにとどめる。ルーム一覧が必要になったら SELECT DISTINCT room_id FROM messages で取れる。

在席（connectors）はルームと紐づけず、全ルーム共通で「誰がいまオンラインか」だけを持つ。ルームが public 1 つしかないうちは、ルームごとの在席を持っても複雑さに見合わない。

名指し（to_connector_id）の扱い

名指し先を記録するが配信は絞らない。要件どおり全員が全メッセージを読める状態を保ち、UI 上で強調表示するだけに使う。後から宛先制限を足したくなったとき、この列と配信フィルタが足がかりになる。

connectors を DB に置く理由

サーバーを再起動しても「誰がこれまで参加したか」「最後にいたのはいつか」が残るため。メモリだけに持つと再起動で参加者リストが空になり、オフライン表示すら出せない。

ただし active_connection_count は再起動した瞬間に実態と合わなくなるので、起動時に全行 0 へ戻す。

UPDATE connectors SET active_connection_count = 0;

外部キーは張らない

messages.from_connector_id → connectors.connector_id の外部キーは張らない。張ると join していない ID からの投稿がエラーになる。CLI が join を忘れたときに黙って失敗するより、投稿の時点で connectors を作るほうが扱いやすい。

INSERT INTO connectors
  (connector_id, connector_role, first_joined_at, last_active_at, active_connection_count)
VALUES (?, ?, ?, ?, 0)
ON CONFLICT(connector_id) DO UPDATE SET last_active_at = excluded.last_active_at;

WAL モードとは何か

SQLite が「書き込み途中でクラッシュしても壊れない」を実現する方式の選択肢。既定は rollback journal、もう一つが WAL（Write-Ahead Logging）。

既定のやり方

書き換える前に対象ページの変更前の姿を chat.db-journal にコピーし、本体を直接書き換え、コミットできたら journal を削除する。途中で電源が落ちても journal から巻き戻せる。

問題は書き換えている最中で、本体が不整合な状態になる。そのため書き手は排他ロックを取り、その間は読み手が締め出される。

WAL のやり方

本体は触らず、変更内容を chat.db-wal に追記していく。読み手は「本体 + WAL のうち自分より前にコミットされた分」を合成して読む。本体が常に整合した状態のまま残るので、読み手と書き手が同時に動ける。書き手が 1 人いても、読み手は何人でも待たされない。

WAL が既定で 1000 ページ（ページ 4KB なら約 4MB）を超えるとチェックポイントが自動で走り、内容を本体へ書き戻して WAL を切り詰める。正常に接続を閉じれば WAL は本体へ統合されて消える。

今回 WAL を選ぶ理由

long-poll が常時「読み」を張っている状態に、投稿の「書き」が割り込む構造になる。既定モードだと書き込みのたびに読み手が待たされる。参加者が数人のうちは体感差はほぼ無いが、切り替えのコストも無いので最初から WAL にしておく。

注意点

const mode = db.prepare('PRAGMA journal_mode = WAL').get();
if (mode.journal_mode !== 'wal') {
	console.warn(`WAL に切り替わりませんでした（現在: ${mode.journal_mode}）`);
}

WAL 設定は DB ファイル自体に記録されるため、一度設定すれば次回以降の接続でも WAL のままになる。それでも、DB を作り直したときのために起動時に実行しておく。

API

JSON を投げて JSON が返るだけの単純な形にする。CLI を後から書き足すときに、特別なライブラリを要らなくするため。

room_id は省略時 public として扱う。時間の向きでパラメータを分けており、since は「この msg_seq より新しい行」（未来方向）、before は「この msg_seq より古い行」（過去方向）を指す。

版と環境を返す

{
	"version": "20260904-0841",
	"started_at": "2026/09/04 08:41:20.897",
	"env": "production",
	"maintenance": false,
	"maintenance_since": "",
	"maintenance_reason": ""
}

env は environment（環境）の略。繋いだ側が自分の居場所を確かめるためにある。テストは投稿の直前にこれを見て、production だったら投稿せずに止まる。画面はこれで色を変える（テスト環境の分離を参照）。

同じ内容を SSE の version イベントでも流す。画面は繋いだ瞬間に受け取るので、/api/version を別に叩かなくても環境が分かる。

画面を開いてから表示するまで

各段階で発行する SQL

-- ① join：参加登録のあと、現在位置と参加者一覧を返す
SELECT MAX(msg_seq) FROM messages WHERE room_id = ?;
SELECT * FROM connectors ORDER BY last_active_at DESC;

-- ② history：直近 50 件。受け取った側で昇順に並べ替えて表示する
SELECT * FROM messages
WHERE room_id = ?
ORDER BY msg_seq DESC
LIMIT ?;

-- ③ events：接続直後に、取りこぼした分をまず流す
SELECT * FROM messages
WHERE room_id = ? AND msg_seq > ?
ORDER BY msg_seq ASC;

② は (room_id, msg_seq) のインデックスを逆から読むだけで済むため、並べ替えの処理は発生しない。

過去へ遡るとき

画面の上端までスクロールしたら、表示中で最も古い msg_seq を before に渡す。

SELECT * FROM messages
WHERE room_id = ? AND msg_seq < ?
ORDER BY msg_seq DESC
LIMIT ?;

AI は過去ログを取りに行かない

起動のたびに過去ログを流し込むと AI の文脈を圧迫するだけなので、参加した時点以降のものだけを受け取る。過去が必要なときは recent で明示的に取りに行く。

画面は古い参加・離脱を描かない

取る件数は 50 のままだが、そのうち 12 時間より前の join / leave は描かない（src/web/js/stale.js の SYSTEM_KEEP_MS）。画面は「いま何が起きているか」を見る場なので、半日前の出入りは要らない。

対象は join と leave だけである。archive（片付けの知らせ）には戻すボタンが付いており、消すと戻す口が無くなる。notice と発言（say）も残す。

SSE とは何か

Server-Sent Events。サーバーからブラウザへ一方向にデータを押し出す仕組み。HTTP の標準機能で、追加のライブラリは要らない。

ブラウザ ──「/api/events に繋ぐ」──→ サーバー（繋ぎっぱなし）

誰かが発言
サーバー ──「新しい発言だよ」──────→ ブラウザ（リロードせず画面に足す）
サーバー ──「参加者が変わったよ」──→ ブラウザ（一覧を塗り直す）
サーバー ──「版はこれだよ」────────→ ブラウザ（入れ替わったら読み直す）

WebSocket ではなく SSE を選んだ理由

双方向が要らない。ブラウザからの送信は普通の HTTP（/api/say）で足りる。サーバー→ブラウザの片方向だけあればよく、その分だけ作りが単純になる。

受け側は標準の EventSource で書ける。切れたときの繋ぎ直しもブラウザが自分でやる。

検索条件の一覧

sent_at はどの場面でも条件に出てこない。すべて (room_id, msg_seq) のインデックス 1 本で引ける。

JSON のキー名は DB の列名に揃える

API のキー名を DB の列名と同じにしておくと、サーバー側で SQL の結果をそのまま JSON にできる。名前を短くする案もあったが、対応表を持つ手間と読み替えのコストのほうが大きい。

{
  "msg_seq": 12,
  "room_id": "public",
  "sent_at": "2026/08/29 12:34:56.789",
  "from_connector_id": "project-a",
  "msg_kind": "say",
  "to_connector_id": null,
  "msg_body": "テストが通りました",
  "archived_seq": null,
  "ref_archived_seq": null,
  "reply_to_msg_seq": null
}

msg_kind が say 以外のもの（join / leave / archive / notice）はサーバーが自動で積むシステム通知。既定の wait が起きるのは archive と notice までで、参加・離脱では起きない（--with-joins を付けたときだけ受け取る）。

long-poll の待ち時間の上限

wait の上限は 240 秒とする。Claude Code の PowerShell ツールは 1 回の実行が 600 秒で打ち切られるため、その内側に収めておく必要がある。待受けのサブエージェントがツール側のタイムアウトで異常終了すると、着信したのか時間切れなのかを親セッションが区別できなくなる。

オンライン判定と ID

三つの状態

在席は真偽値ではなく状態として持つ。online と offline の間に、接続が切れてから猶予の内にある grace を置く。

状態を増やすときは presence.mjs の STATUS に足す（処理中・離席など）。色は状態名から UI 側で決める。サーバーは状態名と日本語ラベルだけを返し、色を持たない。

判定のたびに online かどうかを書き直さずに済むよう、状態から導ける 2 つの値も併せて返す。

判定の流れ

接続の有無を第一の根拠にするのは、long-poll と SSE がどちらも接続を張りっぱなしにするため。サーバー側で接続数を数えるだけで、追加のハートビートを実装せずに確実な判定ができる。

猶予の 90 秒は、AI セッションが待受けを張り直す間に一瞬途切れるのを吸収するためのもの。サブエージェントが終了してから親が次の待受けを立てるまでの空白が、そのままオフライン表示になるのを防ぐ。

ID

クライアントと待受け

CLI クライアント

AI と人間で同じものを使う。node <ai-chat-lite>/src/client/chat.mjs <command> の形で呼ぶ。

wait は「待って、結果を出して終わる」形にする。呼んだ側が終わりを待てばよく、そのままサブエージェントに渡せる。

参加・離脱では起こさない

既定で join と leave を除く（/api/poll に exclude=join,leave を渡す）。--with-joins を付けたときだけ含める。

絞るのはサーバー側である。受け取ってから CLI で捨てると、経過時間の数え方が壊れる。

let waited = 0;
while (unlimited || waited < limitSec) {
	const wait = unlimited ? MAX_WAIT_SEC : Math.min(MAX_WAIT_SEC, limitSec - waited);
	last = await call(`/api/poll?…&wait=${wait}`);
	waited += wait;   // ← 待ち切った前提で加算している
}

除いた分もカーソルは進む。止めると、張り直した先で同じ join を読み、また除いて待つ。1 回で済むはずの走査が毎回積み上がる。詳しくは待受けの種別しぼりを参照。

待ち直しの回数

1 回の long-poll は 240 秒で必ず返る。それ以上サーバー側で引き延ばすと、途中で切れた接続を握り続けることになるため。代わりにクライアントが黙って待ち直す。呼ぶ側から見ると 1 回の実行で長く待てる。

回数の解釈には落とし穴がある。Number(x) || 既定値 と書くと、0 は falsy なので「0 回」と書いたつもりが既定値に化ける。数として読めるかどうかを先に判定し、0 や負の数は 1 回に丸める。

本文は Markdown で書かれている前提だが、CLI では変換せず生のまま出す。ターミナルでは記法がそのまま見えるが、AI も人間も読めるので困らない。

ブラウザでの Markdown 表示

ブラウザ側だけは HTML に変換する。ここが唯一の攻撃面になるため、依存パッケージを入れず、最小限の変換を自前で持つ。ローカル限定・認証なしとはいえ、AI が外部から取得した文字列をそのまま投稿する経路は現実にあり得る。

エスケープを先に済ませる

順序が重要で、先に全体を HTML エスケープしてから記法を処理する。この順にすると、本文に生の HTML が含まれていてもタグとして解釈される経路が無くなる。

// 1. 先にすべてエスケープする（ここで raw HTML の混入経路が塞がれる）
let s = src.replace(/&/g, '&')
           .replace(/</g, '&lt;')
           .replace(/>/g, '&gt;');

// 2. エスケープ済みの文字列に対して記法を処理する
//    コードブロック → インラインコード → 太字 → 自動リンク → 改行 の順

対応する記法

見出し・表・画像は対応しない。チャットの本文で実際に効くのはコードブロックと改行で、これだけで大半は足りる。足りなくなった時点で記法を増やす。

待受け常駐の流れ

作るものと実装ステップ

フォルダ構成

ai-chat-lite/
  README.html                      … 概要・セットアップ・資料へのリンク
  USAGE-FOR-PROJECTS.html          … 他プロジェクトからの使い方（AI が読む）
  CLAUDE.md                        … ローカルルールを 1 行で取り込む
  aichat.exe                       … C# 版 CLI（Git 管理外）。PATH に入れて使う
  aichat-node.cmd                  … node 版 CLI のランチャー
  .gitignore
  node-ai-chat-lite-winsw.exe      … WinSW 本体（Git 管理外）
  node-ai-chat-lite-winsw.xml      … サービス定義
  node-ai-chat-lite.exe            … node.exe のコピー（Git 管理外・98.9 MB）
  etc/c.bat
  docs/css/style.css               … 共通 CSS（notes から相対参照する）
  docs/ファイルで排他する.html     … 公開資料
  src/
    server/main.mjs                … 起動口。印が消えるのを待ってから server を読む
    server/listen.mjs              … 待ち受けだけを始める。受け口はあとから差し替える
    server/server.mjs              … HTTP ルーティング・SSE・long-poll
    server/serve.mjs               … HTTP の応答を組み立てる（JSON・静的ファイル）
    server/hub.mjs                 … 新着を待っている相手をまとめて管理する
    server/store.mjs               … node:sqlite（投稿・範囲取得）。形は作らず、揃っているかだけ確かめる
    server/tables.mjs              … 版が作るテーブルの名前。store.mjs が確かめる一覧
    server/migrate.mjs             … 版を当てる。versions を作り、足りない分だけ順に当てる
    server/backup.mjs              … 控えを取る（VACUUM INTO）。世代を整理する
    server/presence.mjs            … online / grace / offline の 3 状態を判定
    server/config.mjs              … ポート等の既定値
    server/time.mjs                … JST の固定長文字列を作る
    server/log.mjs                 … 日時とレベルを付けて 1 行 1 件で出す
    server/maintenance.mjs         … _data\MAINTENANCE を見張る
    server/maintenance-handler.mjs … メンテナンス中の受け口。DB を触らない
    client/chat.mjs                … CLI クライアント（AI・人間 共用）
    web/index.html                 … チャット画面
    web/css/chat.css
    web/js/chat.js                 … SSE 受信・送信・参加者一覧の描画
    web/js/markdown.js             … 本文の変換。エスケープを先に済ませる
    web/js/stale.js                … 古くなった参加・離脱を画面から外す判定
    scripts/20_migrate/            … ver_NNNNNN/*.sql。DB の形の出どころ
    cli-cs/                        … C# 版 CLI の原本（Args・Commands・Waiters ほか 8 本）
  tests/
    helpers/prepare-db.mjs         … 置き場を作り直して版を当てる。store より先に呼ぶ
    helpers/cli-args.mjs           … ID の囲みなど、CLI の引数を組み立てる
    time.test.mjs                  … node:test で書く。node --test tests/ で一括実行
    config.test.mjs
    tables.test.mjs
    stale.test.mjs
    wait-kinds.test.mjs
    store.test.mjs
    migrate.test.mjs
    presence.test.mjs
    server.test.mjs
    archive.test.mjs
    backup.test.mjs
    maintenance.test.mjs
    maintenance-flow.test.mjs
    maintenance-handler.test.mjs
    markdown.test.mjs
    client-wait.test.mjs
    client-waiters.test.mjs
    client-reply.test.mjs
    client-connector-id.test.mjs
    client-no-defaults.test.mjs
    client-unreachable.test.mjs
    client-usage.test.mjs
    cli-cs.test.mjs
  tools/20_build/                  … aichat.exe のビルド。オプション定義の書き出し
  tools/40_test/                   … テストの実行・テスト用サーバー・計測
  tools/50_run/                    … 開発用の起動と画面を開く
  tools/70_deploy/                 … サービスの登録・解除
  tools/80_ops/                    … バックアップ・復旧・ログの加工
  notes/01_research/               … 調べたこと
  notes/10_plan/                   … 設計と個別の計画書
  notes/30_status/                 … 実装の進み具合と次にやること
  notes/40_issues/                 … これから解決する課題
  notes/60_releases/               … 変わったことの記録
  notes/90_rules/                  … ローカルルールと運用の手引き
  logs/                            … サービスのログ（Git 管理外）
  _data/                           … chat.db・MAINTENANCE（Git 管理外）
  tmp/  etc/                       … Git 管理外

WinSW 関係の 3 つはルート直下に並べる。node.exe のコピーを隣に置くことで、XML から絶対パスを追い出せる。

環境変数

設定はすべて既定値を持ち、環境変数で上書きできる。既定値は src/server/config.mjs にまとめる。

AICHAT_MANAGED と AICHAT_NO_EXIT は人が手で設定するものではない。前者は XML が、後者はテストが設定する。

サービスとして動かすときは、シェルの環境変数が引き継がれないため XML の <env> に書く。

<env name="AICHAT_PORT" value="8787"/>

DB の形は版で管理する

CREATE TABLE IF NOT EXISTS は既にあるテーブルを作り替えない。そのたびに専用の手順を書くのをやめ、版で管理する形にした。

変更のコストは ALTER TABLE でできるかで決まる

この見立てがあったため、archived_seq は使う前から置いてある。あとから足すと messages の作り直しになるためで、列を足すだけなら安いという判断ではなく、足す時期を選べたから安く済ませたということである。

versions テーブルに、どこまで当てたかを持つ。起動時に足りない分だけを順に当てる。

形はスキーマにある。

版を足す手順

決めたこと

版の SQL に古い名前が残るのは正しい

ver_000001 には user_id や users が書かれている。これは仕事である。

最終的な形に古い名前は残らない。途中の 1 段だけが持つ。

メンテナンス中は DB を開かない。ただし応答はする

DB を作り替えたり中身を入れ替えたりする間、サービスに勝手に起動されるとファイルを掴まれて手が出せなくなる。_data\MAINTENANCE という印を置いておくと、サーバーは DB を開かずに待つ。

手順

restore.ps1 は 0 と 1 を自分で行う。素の restart（コードの入れ替え）では何も流さないので、開発中にルームが起動メッセージで埋まることはない。

2026/08/30 07:56:57.625 WARN  メンテナンスの印があるため、起動を保留します
2026/08/30 07:56:57.625 WARN    印: （実体）\_data\MAINTENANCE
2026/08/30 07:56:57.625 WARN    理由: DB を整理している
2026/08/30 07:56:57.625 WARN    この印を消すと、自分から起動します
2026/08/30 07:57:19.601 INFO  メンテナンスの印が消えました。起動を続けます

起動口を分けている理由

store.mjs は読み込んだ時点で DB を開く。server.mjs をそのまま実行すると、印を見る前にファイルを掴んでしまう。そこで起動口を main.mjs に分け、印が消えるのを待ってから動的 import で読み込む。

// main.mjs
// 印があっても待ち受けは先に始める。受け口はメンテナンス用（DB を触らない）
const servers = await startListening(createMaintenanceHandler(info));

const waited = await waitUntilCleared();

// ここで初めて DB が開かれる
const { takeOver, announceResumed } = await import('./server.mjs');

// 同じ http.Server のまま受け口を差し替える。ポートは開いたまま
takeOver(servers);
if (waited) announceResumed(info.since);

DB を触る部品を分けているのが要点。メンテナンス中に使うものが store.mjs を読み込むと、印を確かめる前に DB を掴んでしまう。

待機中に chat.db をリネームできることを実測で確かめている。掴んでいれば失敗する。

見つけ方

fs.watch で _data を見張りつつ、3 秒ごとの確認も併せて回す。fs.watch は取りこぼすことがあるため、ポーリングを保険にしている。実測では印を消してから 0.8 秒で起動した。

ログ

形式

1 行 1 件。先頭に固定長の JST 日時、次にレベルを置く。

2026/08/29 23:23:37.264 INFO  待ち受け: http://localhost:8787/  [::1, 127.0.0.1]
└──────── 23 文字 ───────┘ └─5─┘

起動時に記録すること

既定値だけで動く作りにしている以上、外から見て「どの DB を掴んだか」が分からない。設定ミスがあっても静かに動いてしまうため、起動時に環境変数の名前と値を出す。既定値のままなのか、環境変数で上書きされたのかも併せて記録する。

2026/08/29 23:23:37.262 INFO  ai-chat-lite サーバーを起動しました
2026/08/29 23:23:37.264 INFO  AICHAT_PORT = 8787                        (既定)
2026/08/29 23:23:37.264 INFO  AICHAT_DATA = /_data              (既定)
2026/08/29 23:23:37.264 INFO  環境          = 本番                          (既定)
2026/08/29 23:23:37.264 INFO  待ち受け: http://localhost:8787/  [::1, 127.0.0.1]

サービスとして動かすと logs/ に残るため、想定と違う場所を掴んでいればすぐ気づける。ポートの衝突・DB の取り違え・片方のアドレスでしか待ち受けていない状態は、この数行で切り分けられる。

WinSW が振り分ける先は 3 つになる。

logs\…-winsw.out.log        … 標準出力（起動ログ・警告）
logs\…-winsw.err.log        … 標準エラー。ERROR だけがここに来る
logs\…-winsw.wrapper.log    … WinSW 自身。起動・停止・子プロセスの ID

ステップ

1 回の実装は 1 点に絞り、各ステップの後に確認を挟む。

サービスとして常駐させる

tools/50_run/ の手動起動は開発用で、コンソールを閉じるとサーバーも止まる。常用するには PC の起動時に自動で立ち上がってほしいため、Windows サービスとして登録する。WinSW（Windows Service Wrapper）を使う。

WinSW を使う理由

ファイルの置き方と名前

WinSW は自分と同じ名前の XML を隣から読むという約束で動く。関係するファイルをプロジェクトのルート直下に並べて置き、名前を node-ai-chat-lite で始まるものに揃える。

なぜ node.exe をコピーするのか

システムの node.exe をそのまま指すと、走っているプロセスが単に node.exe として見える。開発中は別のプロジェクトでも Node が動いているため、どれがチャットサーバーなのか区別が付かない。

実行ファイルを複製して名前を変えると、プロセス名がその名前になる。

コピーした実行ファイルが単体で動くことは実測済み。

XML にパスを書かない

WinSW は相対パスを自身の実行ファイルがあるフォルダを基準に解決する。ルート直下に置いてあるため、絶対パスは 1 つも書かずに済む。

<service>
  <id>node-ai-chat-lite</id>
  <name>ai-chat-lite チャットサーバー</name>
  <description>ローカル PC 内の AI 間チャットサーバー</description>

  <!-- 隣に置いた node.exe のコピー -->
  <executable>node-ai-chat-lite.exe</executable>
  <arguments>src\server\server.mjs</arguments>

  <env name="AICHAT_PORT" value="8787"/>

  <logpath>logs</logpath>
  <log mode="roll-by-size">
    <sizeThreshold>10240</sizeThreshold>
    <keepFiles>8</keepFiles>
  </log>

  <onfailure action="restart" delay="10 sec"/>
  <startmode>Automatic</startmode>
</service>

workingdirectory も省略できる。指定しなければ実行ファイルのあるフォルダが使われるため、サーバーから見た相対パス（_data/chat.db など）もそのまま通る。

登録は実体のフォルダで行う

:: 実体のフォルダへ移動してから実行する（管理者として）
cd /d C:\（実体のパス）\2026\ai-chat-lite
node-ai-chat-lite-winsw.exe install
node-ai-chat-lite-winsw.exe start

一度登録してしまえば、以降の start / stop はどこから呼んでも構わない。XML 側にパスを書いていないのは、この登録時のフルパスだけを正しくすれば済むようにするため。

操作

いずれも管理者権限が要る。tools/70_deploy/ の install-service.cmd / uninstall-service.cmd がこれらを呼ぶ。

管理者権限なしで入れ替える

onfailure が発動するのは異常終了したときで、終了コード 0 の正常終了では再起動されない。この違いを使うと、サーバー自身に終了させることで、管理者権限なしに新しいコードへ入れ替えられる。管理者権限が要るのはサービスの登録・開始・停止であって、プロセスが自分で終わることには要らない。

ブラウザのアドレスバーからも叩ける。副作用のある GET は本来避けるところだが、localhost 限定で認証も無い前提のため手軽さを採った（リンクとして書かないこと。先読みで落ちる）。

http://localhost:8787/api/admin/exit?exit_code=1

注意点

検証

各ステップでは起動エラーの有無だけを確認し、機能の確認は利用者が行う。全体が揃った時点で以下を通す。

ドキュメントの検証

この資料は PlayWright の共有環境の contrast.spec.ts でコントラスト比を実測し、1.5:1 未満が 0 件であることを確認する。