t3-code

t3-code のローカルナレッジ

T3 Code のローカル状態は ~/.t3/ にあります。セッション、コマンド、メッセージなどの実行データは SQLite に保存されます。振り返りや調査の際は、ログを読み返すよりデータベースを直接調べるほうが効率的です。

状態データベース

• 現在のデータベース：~/.t3/userdata/statev2.sqlite。state.sqlite は旧データベースです。
• v2 投影テーブル（orchestration_v2_projection_*）は 2025-10-03 以降の正規データです。v1 の projection_* テーブルへの書き込みは停止しており、さらに古い履歴を調べる場合にのみ参照します。
• 主なテーブル：
  • orchestration_v2_projection_threads：スレッド。列には thread_id、project_id、title、default_provider、runtime_mode、created_at、updated_at、archived_at が含まれます。
  • orchestration_v2_projection_turn_items：スレッド内のイベントストリーム。分析の中心となるテーブルです。列には thread_id、run_id、ordinal、type、status、updated_at、payload_json が含まれます。
  • orchestration_v2_projection_subagents / runs / run_attempts / provider_sessions：委任および実行の詳細です。
  • scheduled_tasks、projection_thread_pull_requests：定期タスク、スレッドに関連付けられた PR です。
• turn_items.type の一般的な値：assistant_message、command_execution、reasoning、dynamic_tool（MCP 呼び出し）、user_message、file_change、file_search、subagent、error。
• payload_json の内容は type によって異なります。command_execution には input / output / exitCode / startedAt / completedAt が含まれ、assistant_message / reasoning には本文テキストが含まれます。
• 保持上の制限：command_execution の約 87% は output に「Exited with code N」という 1 行だけを保存します。exitCode フィールドは省略されることが多く、完全な stdout/stderr は保存されません。成否の判定は主に output テキスト内の終了コードに基づきます。
• 委任タスクのサブエージェントは独立したスレッド（thread:delegated-task:* のような名前）です。サブエージェントの活動を調べるには、thread_id でフィルターします。
• Windows には sqlite3 CLI がないため、Python に組み込まれた sqlite3 モジュールを使ってデータベースを調べます。少し長いクエリは一時的な .py ファイルに書いてから実行してください。cmd 内で python -c を使うと引用符の扱いで失敗しやすくなります（実行シェルは cmd で、&& で連結し、; では連結しません）。

よく使うクエリ

DB=~/.t3/userdata/statev2.sqlite

# 最近活跃线程
sqlite3 $DB "SELECT thread_id, title, updated_at FROM orchestration_v2_projection_threads
  WHERE deleted_at IS NULL ORDER BY updated_at DESC LIMIT 20;"

# 某线程的命令执行（含退出码）
sqlite3 $DB "SELECT json_extract(payload_json,'$.input'), json_extract(payload_json,'$.exitCode')
  FROM orchestration_v2_projection_turn_items
  WHERE thread_id='<id>' AND type='command_execution' ORDER BY ordinal;"

# 失败的命令（全库）
sqlite3 $DB "SELECT thread_id, json_extract(payload_json,'$.input')
  FROM orchestration_v2_projection_turn_items
  WHERE type='command_execution' AND payload_json LIKE '%Exited with code%'
    AND payload_json NOT LIKE '%Exited with code 0%';"

# 事件类型分布
sqlite3 $DB "SELECT type, COUNT(*) FROM orchestration_v2_projection_turn_items GROUP BY 1 ORDER BY 2 DESC;"

オーケストレーションツール面（仕組みに関する事実）

作業の割り当て方針や操作手順（モデルの選択、タスクテンプレートの作成、経路の切り替え、受け入れ確認）は $t3-orchestrator スキルの担当です。ここではツール層の仕組みに関する事実のみ記載します。

• orchestrator_capabilities は、稼働中のプロバイダー／モデルのカタログ（カスタムモデルを含む）を返します。ハーネスに組み込まれたモデル一覧がすべてではありません。
• delegate_task のパラメーター：task、target:{providerInstanceId, model}、mode、clientRequestId。戻り値の taskId（task_status / task_cancel で管理）と childThreadId（サブエージェントの保存先スレッド。t3_thread_read で読み取り可能）が返されます。実際の割り当てルール——target のモデル選定、runtimeMode / interactionMode の扱い——は $t3-orchestrator の「割り当て」セクションに記載されています。呼び出す前に読んでください。
• スレッドとワークスペースの紐付けは、t3_thread_launch の workspaceStrategy（worktree / existing_worktree / root）でのみ設定できます。エージェント自身に git worktree add を実行させても、紐付けは変わりません。
• ACP チャネルのフォールバック：T3 MCP ツールがなく、環境に T3_ACP_MCP_NODE がある場合は、ターミナルから実行します。 ELECTRON_RUN_AS_NODE=1 "$T3_ACP_MCP_NODE" ${T3_ACP_MCP_ENTRYPOINT:+"$T3_ACP_MCP_ENTRYPOINT"} acp-mcp-call <tool> '<json>'。
• schedule_task の schedule には構造化オブジェクト（{"type":"interval","everyMs":N} / {"type":"fixed_time","timeOfDay":"HH:MM","weekdays":[...]}）を渡します。JSON 文字列ではありません。

リッスンとウェイクアップ

イベントが到着すると、T3 はこのスレッドをウェイクアップします。外部の結果を待つ場合はリッスンを登録してから、このターンを終了してください。このターンを終了することで制御が T3 に返され、イベントによって元の処理に戻ります。タスクが終了するわけではありません。

• PR レビュー、CI、競合：watch_pull_request（使い方は T3 が挿入する PR の説明を参照）。サブタスク：delegate_task の非同期完了イベント。
• 一部のハーネス（pi など）では MCP ツールの読み込みが遅延します。ツール一覧に watch_pull_request がない場合は、まず tool_search で検索し、見つからなければ前節の ACP フォールバックを使います。
• watch_pull_request は「自分の GitHub アカウントで投稿されたコメント」ではスレッドをウェイクアップしません（実測で確認済みです。watch の登録は成功し、結論が届いてもウェイクアップしません）。現在、クラウドレビュアーはそれぞれ自分の ID で発言するため、その結論では正常にウェイクアップします。「ユーザートークンを借りて発言する」アカウントだけがウェイクアップを取りこぼすため、そのような場合は schedule_task（{"type":"interval","everyMs":1800000}。現在のスレッドに戻る）を保険として設定します。時間になったら、$pr-review-loop の「レビューコメントは ID ごとに帰属させる」に従ってすべてのコメントを読み直し、今回のレビュー担当者が全員揃った場合、または無応答時のルールに従って待機を断念した場合に削除します。

子スレッドの証拠確認（t3_thread_read）

• デフォルト表示ではメッセージ項目のみが返されます。ツール呼び出しやファイルへの書き込みには view:"activity" を使います。サブエージェントの報告や特定の書き込みを探す場合は、末尾の position からさかのぼってください。0 からページ分割しないでください。
• 環境をまたいだ振り返りでは、まず node <技能目录>/scripts/t3-activity-scan.mjs --hours 24 --self <本线程 id> > scan.json を実行します。T3 MCP エンドポイント経由で、この環境および接続済みのすべての環境における期間内に活動したスレッドを収集します。各スレッドには、読み込んだ skillReads、$技能名 の言及、ユーザーメッセージが含まれます。活動の判定は、直近の run または作成時刻に基づきます。t3_thread_list の updatedAt は一括同期によって更新されるため、これを使って絞り込むと、古いスレッドが数百件も対象に含まれてしまいます。次に、確認したいスレッドについて t3_thread_read で詳細を補います。
• file_change 項目の originalFile には編集前の全スナップショットが含まれます。未追跡ファイルが変更によって壊れた場合は、そのファイルの最後の file_change の originalFile を使って復元します。これは、この種の事故に対する最後の復旧手段です。

ワークツリーの回収（t3-worktree-gc）

T3 スレッドに紐付けられたワークツリー（~/.t3/worktrees/<项目分组>/<名>）は、スレッド終了後も自動では削除されません。同じ紐付け先のワークツリーに、junction／シンボリックリンク経由で複数のパスから到達できる場合があります（データディレクトリの移行後によく見られます）。ワークツリーのパスが「変わった」ように見えても、まず同じディレクトリかどうかを確認してください（Windows では dir /al / fsutil reparsepoint query、POSIX では readlink / stat）。ディレクトリが移行したと判断しないでください。終了時には scripts/t3-worktree-gc.mjs を使い、「ほかの終了済みスレッド」のワークツリーのみを回収してください。自分がいるツリーは後続のセッション用に残し、紐付け中のツリーには決して触れないでください（紐付けられたディレクトリを削除すると、そのスレッドのターミナルは永久に使えなくなります）。

node <技能目录>/scripts/t3-worktree-gc.mjs               # dry-run：逐目录打印结论
node <技能目录>/scripts/t3-worktree-gc.mjs --apply       # 真正执行回收
node <技能目录>/scripts/t3-worktree-gc.mjs --root <dir>  # 单独指定扫描根
node <技能目录>/scripts/t3-worktree-gc.mjs --purge-build [--apply]  # 附带清理保留树的构建产物
node <技能目录>/scripts/t3-worktree-gc.mjs --purge-build --measure-size  # 显式统计候选产物大小
node <技能目录>/scripts/t3-worktree-gc.mjs --diagnose    # 对已阻断的树也收集 git 原因

スキャン対象のルートと各ツリーの結果は stdout にリアルタイムで書き出され、各段階の開始／終了、コマンドの所要時間、タイムアウトによる失敗は stderr に書き出されます。完全なログが必要な場合は > gc.log 2>&1 を使ってください。パイプで出力を切り詰めて終了コードを失わないようにしてください。デフォルトでは self、スレッド／使用中状態、またはデータベースによるブロックがあると、git の再確認をスキップします。すべての原因を調査する場合は --diagnose を使います（走査とネットワークの負荷が増えます）。 --purge-build：工作树因 git 原因保留（脏树、未推送、珍贵文件、unbound 半删残留）、但没有未终结线程、活跃 run 或不可归因的进程占用时，只删其中可重建的构建产物：cargo target（带 .rustc_info.json/CACHEDIR.TAG/.fingerprint）、.build、node_modules、.gradle、Xcode 派生数据（DerivedData，或含 ModuleCache.noindex/Build/Intermediates.noindex 的目录，在 ignored 目录内最多向下找两层）。只认 ignored 目录，不碰跟踪文件、未提交文件和其他 ignored 内容。多个工作树并行、磁盘吃紧时，用它代替删树来回收空间。默认只列目标，不运行 du；需要空间估算才加 --measure-size（逐目标遍历可能很慢，失败显示「未知」，不影响清理资格）。每棵树进入产物删除阶段时重拍一次进程占用快照，避免逐产物重复全机扫描；每个目标删除前刷新绑定并结合该占用快照检查，再核验 ignored 规则、跟踪与非 ignored 文件、产物标记和路径边界；目标及树内祖先是符号链接/junction 时保留。复查收窄并发窗口，不是原子锁；不要同时手动改写正在清理的目录。

全部满足才删，任一不满足则 skip 并注明原因：

• 调用者 cwd 不在该工作树内（self 永不删）；
• 是 git 链接工作树（独立 clone skip）。非 git/gitfile 失效的残留里，整树只含占位/系统垃圾文件（T3 合并 PR 后留的 .keep/.worktree-placeholder、.DS_Store 等）的占位目录同样过绑定/占用检查后删除；含其他内容标 not-a-worktree 只报告。--apply 收尾顺带 rmdir 本轮删空的二层分组目录；
• 绑定的线程全部已终结（settled / archived / deleted 任一；委派子线程的 settledOverride 永不写入，改看 subagents 表 child_thread_id/provider_thread_id 关联行——全部终态即算终结，无关联行仍算未终结；零绑定标 unbound 可删），且未终结线程没有 queued/preparing/starting/running/waiting 状态的 run——已终结线程上的 running 行是投影滞留（见「已观察到的坑」），降级为备注放行；
• git status --porcelain -uall 为空（-uall 覆盖 status.showUntrackedFiles 配置；所有读工作树状态的调用带 -c core.fsmonitor=false -c core.untrackedCache=false，防 fsmonitor 钩子/未跟踪缓存误报把本地编辑藏掉）；ignored 逐文件展开里没有命中「珍贵模式」的条目——珍贵模式 = 凭据类文件类型（.env、密钥/证书/keystore、*.properties、kubeconfig、.kube/.docker/.azure 等云凭据目录、.config/gh/gcloud（项目本地 GH_CONFIG_DIR 等 CLI 凭据区）、*.tfstate*/local.settings.json、hosts.yml、.git-crypt、凭据命名、本地数据库等，全集见脚本里 PRECIOUS_PATTERNS/PRECIOUS_SUBSTRINGS）；命中前先过 BENIGN_DIR_SEGMENTS 良性目录段滤掉产物/依赖目录（含 .build/.tmp/Pods/Carthage/SourcePackages 等 SwiftPM、CocoaPods 检出与派生数据），命中列出文件，其余 ignored 条目收敛到顶层名进报告、超 8 个截断。*.properties 命中再过内容级豁免：整文件键都在工具链白名单（sdk.dir/ndk.dir/cmake.dir/flutter.*）的是 IDE 生成的 SDK 指针而非凭据（local.properties 常态），放行进报告；其他键、不可解析行、读取失败维持阻断；
• 没有 ls-files 下探不了的目录（嵌套 git 仓库等尾斜杠条目；良性目录段内的豁免——.build/checkouts 这类依赖检出不算用户仓库）、没有 git 子模块（索引里没有 mode 160000 的 gitlink）、没有 assume-unchanged/skip-worktree 标记文件（ls-files -v 小写或 S 标签；两项合并成一次 ls-files -s -v）——这些路径的内部状态对所有检查不可见，一律不删；
• HEAD 改动已在远端：HEAD 是某 refs/remotes/origin/* 的祖先，或 git cherry 逐提交 patch 等价（rebase/单提交 squash 合并），或整支 diff(base..HEAD) 的 patch-id 命中 base..ref 上某提交（多提交 squash 合并，上游比对封顶 400 个提交），或对 base 无净改动。patch 等价放行的是改动内容——提交对象仍丢弃，squash 工作流正是如此；内容对不上的孤立提交仍阻断。判定前先对该仓库跑一次 fetch origin --prune 刷新本地跟踪引用——远端删过分支后残留的 tracking ref 不代表已推送；远端不可达即 skip。注意 dry-run 也会执行这一步：fetch 需要联网、会更新本地 refs/remotes/origin/*（已禁交互凭据提示，缺凭据直接判不可达不卡终端）。patch 等价的分支在 --apply 后用 branch -D 强删（git 视角是未合并分支，但内容已在远端）；
• 没有进程以它为 cwd（POSIX 用 lsof，缺席时 Linux 退 /proc；检查不可用仍是阻断——看不到占用无从归因。例外：绑定线程全部终结时，占用者只可能是已终结线程的残留进程——孤儿代理/模拟器/守护进程——降级为备注放行，删掉干净且已推送的目录只让残留进程 cwd 失效；未绑定目录的占用无法归因——可能是闲逛进去的活线程——维持阻断。Windows 不查，靠删除失败兜底）。

--apply 在真正删除前对该目录重拍线程绑定/活跃 run/进程占用快照并重查 git 侧全部条件，收窄扫描与执行之间的并发窗口。报告末尾汇总行附「在用工作树」计数（有未终结绑定线程或进行中 run 的目录数）。

数据库 userdata/statev2.sqlite 只读打开（node:sqlite 优先，退回 sqlite3 CLI）；缺席或打不开时此根下全部 skip，不做删除。--apply 下用 rmSync 删目录后 git worktree prune 注销（不用 worktree remove：spawn 超时会把数万文件的递归删除砍在半途，留下半删残留），再用 git branch -d 兜底删本地分支（改动已验证在远端的分支 -d 拒删时改用 -D——patch 等价与已推送未合入当前 HEAD 都算，失败保留并注明）；任一步失败标 failed 继续下一个，退出码置非 0；绝不结束进程、不换更强硬的命令重试。

测试：node <技能目录>/scripts/t3-worktree-gc.test.mjs——在临时目录造夹具（git 仓库 + 假 origin + 最小 statev2.sqlite），覆盖每条 skip 原因；不碰真实 ~/.t3。

外部依赖：T3 目前不能解除线程与工作树的绑定、也没有「退回 root」的接口（t3_worktree_handoff 只能转入新工作树）；绑定中的工作树只能等线程终结后由 gc 回收，解绑能力依赖 T3 产品改动。

観測された落とし穴

• 一部の ACP エージェントは MCP の注入を受け付けてもツールを公開しません。結論を出す前に、まず上記の acp-mcp-call を使ってフォールバック検証してください。
• 委譲された子エージェントがまれに通知なく失われるため、メインエージェントは降格時の自己レビューに備えてください。
• subagents／runs の投影が running のまま止まる原因は2つあります。実際には子スレッドが完了している（投影が滞留している）か、子エージェントが承認待ちで停止しているかです。子スレッド末尾のイベントが approval_request／waiting の場合、approval-required モードのバックグラウンド子エージェントは、誰も承認しなければ永久に停止し、task_status は running のままです。状態のポーリングだけを信頼せず、t3_thread_read で childThreadId の末尾を読み取り、実際の進捗を判断してください。承認待ちで停止している場合は、承認して続行するか、task_cancel の後、継承モードで再割り当てしてください。
• mcp__t3-code__* がまれに「Failed to connect to MCP server 't3-code'」と報告しますが、再試行すると復旧します。復旧しない場合は ACP のフォールバックを利用してください。
• mcp_list_tools はセッションごとに完全なディレクトリを再確認するため、トークンの消費が少なくありません。
• command_execution の出力は完全には保持されません（前節を参照）。失敗したコマンドを分析する際、stderr はほとんど取得できず、終了コードしか確認できない場合があります。