tavern2agent

Tavern → Agent

把 SillyTavern 卡编译成 pi-native 互动叙事 runtime。还原作者想做的游戏：prompt 描述世界，领域事件改变世界，engine/reducer 维护正确性，session 保存存档。不复刻 ST 宏、COT、JSON Patch、HTML 状态栏，不把状态栏字段搬进 patch_state。

开工

1. 解包卡片，确认输出目录。目录存在时先问：覆盖、增量、另建？
2. 先读 references/evented-runtime.md、references/card-ir.md、references/event-packs.md、references/design-principles.md。
3. 全量审计 data 字段、世界书、TH scripts、regex scripts、开场白。
4. 先输出或草拟 world-data/card-ir.json；不要直接从原卡文本生成代码。
5. 从 IR 形成 Runtime Plan：archetype、event packs、state roots、visibility policy、fact sources、tool surface、subagent roles、prompt modules、validation plan。
6. 写代码前先给用户看 Runtime Plan；复杂卡还要给 state schema、event catalog、reducer/API 清单、事实源边界和子代理边界。

增量更新：先看 git log -20 + git diff。只改本次需求相关文件；不碰 sessions/、runtime/、.pi/agent/。

探索命令

python3 scripts/extract_card.py <card.png|webp|jpg|json> card.json
python3 scripts/list_entries.py card.json
python3 scripts/list_entries.py card.json --filter mvu
python3 scripts/list_entries.py card.json --filter initvar
python3 scripts/get_entry.py card.json <index>

脚本支持 v1/v2/v3。v1 会归一化为 v2；v3 的 group_only_greetings 按 alternate_greetings 处理。

信息源 → IR

看什么	路径/信号	IR 产出
基础设定	description/personality/scenario/system_prompt	persona / settingFacts / style
开场	first_mes/alternate_greetings/group_only_greetings	openings / playerSetup / route signals
世界书	character_book.entries[]	worldbookEntries + disposition
初始状态	[initvar]、YAML、变量表	mutableConcepts initial values
规则更新	[mvu_update]、变量变化	mechanics + event candidates
不可逆拐点/隐藏真相	一次性开场分支、世界书一次性条目、creator_notes 秘密、阵营视角；可无 MVU	one-way / secret / hidden event candidates
TH scripts	Zod、外链、游戏脚本	schema / mechanics / reducer hints
regex scripts	非 UI 注入、状态栏	fields + triggers；丢 UI 外壳
作者说明	creator_notes	hidden rules / play constraints / visibility facts

世界书要全量审计，含 disabled。每条给去向：data、mechanic、event-pack、setup、progressive reveal、prompt-style、discarded。

方案

先过退出闸门：纯设定、无可变世界、无秘密边界的卡不转换——收益不抵成本，向用户说明并建议直接玩原卡。过闸的卡分两档：evented light（少量可变概念，无复杂公式）、evented standard（骰子/战斗/经济/多字段联动/时间压缩）。秘密视角叠加 secret / faction / offscreen pack 与 project subagent；现实题材叠加 web/fetch/code-search 只读事实源。主表与临界场景见 references/decision-tree.md。

分档信号不是「卡里有没有 MVU/公式」，而是「有没有承重且必须被后续可靠查询的转换或隐藏真相」——无任何 MVU 的不可逆拐点或隐藏真相照样进 evented，满屏 MVU 先祛魅只编译承重项。展开论证与信号清单的唯一权威是 references/decision-tree.md。

typed tools 与 CodeAct 只是执行载体之争，取舍见 decision-tree 第二问；无论载体如何，状态变化都落成 domain event 并经 reducer。

多 agent 判定

多 agent 只解决认知隔离。卡复杂本身不构成拆分理由。

信号	做法
NPC 少、无秘密	单 GM
NPC 有秘密/阵营/不同视角	拆 subagent
悬疑答案不该进 GM context	真相/凶手视角隔离
后台导演要读隐藏真相才有戏	engine spawn 密闭子进程（薄接缝，非框架）
只为「更聪明」	不拆

subagent 只给建议、候选事件或文本；状态写入仍由 GM 走主 engine。载体按「子代理要不要知道秘密」选：

• in-process 顾问型（审计、视角反应、无密候选）：project-scope、显式 tools、显式 extensions、不继承完整项目上下文/技能目录；候选类输出 bare JSON；state 投影由主进程在 tool_call hook 里注入 task（不自读 debug 快照）。
• detached 密闭导演型（知密后台平行线）：engine 自持薄 spawn 接缝——pi -p --no-tools --no-approve --no-context-files 密闭子进程 + engine 收割 + pending-harvest 台账；不用 subagent 框架。

详见 references/multi-agent-architecture.md。

リファレンスのルーティング

タスク	参照先
v2 の憲法	references/evented-runtime.md
Card Semantic IR	references/card-ir.md
event pack の選択	references/event-packs.md
全体原則	references/design-principles.md
案の段階分けと臨界判定	references/decision-tree.md
TH/regex スクリプト	references/script-analysis.md
世界書/MVU/initvar	references/mvu-mapping.md（MVU の概要を説明する前に「MVU の実情」節を必ず読むこと。確信が持てない場合は公式の原文を fetch し、記憶を頼りに作り上げないこと）
開始時の setup	references/setup.md
ツールの抽象化 / typed tools vs CodeAct / 入口の集約	references/tool-abstraction.md
CodeAct サンドボックス契約 / .d.ts	references/codeact.md
データクエリ層 / external research	references/data-layer.md
session state / 軽量エンジン / 記憶の階層化	references/ts-engine.md
schema/migration	references/state-schema-migrations.md
pi extension/tools/prompt	references/pi-integration.md
prompt orchestrator / ST prompt_order の移行	references/prompt-composition.md
GM の物語の節目となる素材（GM prompt を生成するときに参照し、GM が行き詰まったときに読む）	references/storytelling.md
複数 agent / 密閉型ディレクターの spawn 接合部	references/multi-agent-architecture.md
2段階の精算/レンダリング、2モデル、compaction の引き継ぎ	references/two-pass-rendering.md
実戦テスト / 3層のテスト軸	references/validation.md
エンジニアリング規律 / ディレクトリの命名	references/engineering-discipline.md

成果物

evented light の基本：

prompts/preset.json
prompts/gm-*.md
world-data/card-ir.json
world-data/runtime-plan.json
world-data/world.json
skills/start-game/SKILL.md
start.sh
extension.ts
tools/registry.ts
engine/events.ts
engine/reducers.ts
engine/state.ts
.pi/settings.json
package.json
tsconfig.json

standard に必要に応じて追加：

engine/codeact.ts
engine/codeact-sandbox.d.ts
engine/migrations.ts

必要に応じて追加：world-data/*_index.json、extensions/subagents/*.ts、.pi/agents/*.md、migration/debug ツール、event-pack テスト。

小規模なプロジェクトならフラットなレイアウトで十分です。プロジェクトが大きくなったら、領域ごとに engine のサブディレクトリを分け、prompt 素材を pass ごとのディレクトリに分けてください。また、曖昧で汎用的すぎるディレクトリ名は避けてください（data/ とランタイム state、agents/ と .pi/agents/ の名前の衝突などによる手戻りの教訓は、references/engineering-discipline.md の構成規律を参照してください）。

start.sh はこのリポジトリの scripts/start.sh をコピーし、プロジェクト単位で隔離する PI_CODING_AGENT_DIR を維持してください。

厳守事項

各項目の唯一の正規な定義は対応する reference にあります。ここでは越えてはならない一線のみを示します。

State と engine

• prompt は最小限にし、計算は engine に、大量データは data + lookup に、状態変化は domain event に入れてください。
• mutable な各概念には、event pack を用意するか、immutable data にするか、明確な破棄理由を設ける必要があります。判断基準はクエリ可能性です。下流が正確性を保証する方法でそれを照会する必要がある（gate の動作／重複トリガーの防止／ロックの一方向ゲート／秘密の分離など）場合に限り、イベントにしてください。本文から再度読み取れるものや、次の段落の雰囲気付けにしか使わないものは prose に残してください。カードに MVU があるかどうかは関係ありません。
• state への書き込みは単一の runner に集約します：draft を clone → 純粋な (draft, event) ドメイン関数 → 検証 → commit。ドメイン関数は store に触れず、失敗した場合は commit しません。
• state の真実のソースは pi session custom entry です。debug のエクスポートディレクトリは debug 専用とし、公開しません。
• schema を変更する場合は version を上げ、deterministic migration を行います。state の型は schema の Static<> から派生させ、手書きの並行型を維持しないでください。
• patch の規律に関する唯一の正規な定義は references/evented-runtime.md を参照してください。通常のプレイでは汎用 setter を公開せず、raw patch で保護対象パスを変更しないでください。
• prompt は防壁ではありません。計上可能な GM の規律は state-backed ledger に記録し、engine で強制してください。強制の強さは検証可能性に合わせます（機械チェック項目は拒否し、物語上の項目は促しと記録を行います）。記憶についても同様です。立証コストを記憶の重さに合わせてください（references/ts-engine.md を参照）。

ツール面

• ツールの契約と実装は同じファイルに置きます。tools/registry.ts は登録一覧に限ります。
• ツール一覧はゲーム全体を通じて固定します。実行時に toolset を切り替えず、ツールを動的に追加・削除しないでください。prompt cache が壊れます。
• 入口を集約します。同じ物語上のアクションに対し、LLM から見える入口は1つだけにします。コマンドパネル形式か one-commit-per-turn 形式のどちらか一方を選び、併用しないでください（references/tool-abstraction.md の入口集約節を参照）。
• ツールの description は「用途を1行 + 境界の bullet + 禁止事項の bullet」にまとめます。長い checklist は reasoning-bait です（論拠は references/engineering-discipline.md の規模に関する規律の節を参照）。構造化データを details のみに置いてはいけません。大きなツール出力には共有の renderResult を用意し、折りたたみ時は要約、展開時は完全な content を表示してください。
• LLM 向けツール schema を serde として扱わないでください。schema では基本的な形状をチェックし、ツールの入口で unknown → typed input に変換します。正規化には手書きの assert の複製ではなく、共有 schema モジュールを使い、エラーはドメインの言葉で表現してください。engine/state は引き続き厳格に保ちます。

Prompt 面

• prompt の注入スタックはゲーム全体を通じて静的に保ちます。モジュールの有効・無効は設定時に決定し、そのターンの入力に応じて前置きを変えると prefix cache が破損します。注入するモジュール数はテストで固定してください。ルールは一度明確に説明すれば十分です。規模を減らす必要がある場合は静的に減らし、動作/schema はテストで変更されないよう固定します（教訓と実測については references/engineering-discipline.md の規模に関する規律の節を参照）。
• prompt orchestrator は Runtime Plan + state projection のみをレンダリングします。canonical state の読み書きをせず、ドメインルールを補完せず、hidden-canonical を漏らしません。
• モデルから見えるテキスト（身元の宣言、tool label、プレイヤーパネル、suggestedActions）には、エンジニアリングの足場となる表現（sandbox/framework/「本モジュールは…を担当します」などの自己紹介）を使わず、世界内・物語上の表現に置き換えます。内部のパッケージ名、ディレクトリ、tool id は変更しません。構造化された提案フィールドでは主語を省いた動作句を使い、プレイヤーキャラクターの身元や視点の人称との不一致を避けます。
• ST マクロ、強化された思考連鎖、JSON Patch 出力形式、HTML ステータスバーはデフォルトで取り除き、意味だけを移行します。

事実のソースと subagent

• 現実を題材にする場合は、手作業のナレッジベースの代わりに web/fetch/code-search を使用できます。架空の canonical facts は、デフォルトでローカルの world-data/lookup のみを参照します。
• subagent は state に書き込まず、CodeAct を使わず、雑談相手の NPC にもしません。バックグラウンドの候補はドメインイベントに変換できる必要があり、反映前に審査し、保存時の secrets は gitignored にします。利用形態に関する越えてはならない一線は「複数 agent の判定」を参照してください。詳細の唯一の正規な定義は references/multi-agent-architecture.md です。

アーキテクチャとエンジニアリング

• 物語性の強いカードでは、2段階の精算とレンダリングの分離を検討してください。採用するかどうかとその境界については references/two-pass-rendering.md を参照してください。
• TS の成果物では厳格なエンジニアリングの基本要件を有効にしてください。typecheck/lint/format が通らなければ完了とはみなしません。

完了

完了判定の唯一の正規な定義は references/validation.md を参照してください。残存項目のスキャン、手動チェックリスト、テストプレイヤー Agent として20〜30ターン実際にプレイし、すべて通過して初めて完了です。報告には完了した項目とファイルパスのみを記載してください。未完了の場合は作業を続けてください。

完了後に任意で行う追加の確認：元のカードを再確認する。判断基準と手順については references/validation.md の「元のカードを再確認する」節を参照してください。