Pasta ソウルドキュメント

Defines the vision, core values, design principles, and architecture for the Pasta conversation scripting engine.

ekicyou

May 2, 2026

0 downloads

1 views

ai agent rag workflow

View source

What this file does

Defines the vision, core values, design principles, and architecture for the Pasta conversation scripting engine.

When to use it

Onboarding new contributors to understand project philosophy and constraints
Making design decisions that must align with the engine's constitution
Reviewing whether a feature or change fits the declared core values
Resolving conflicts between documentation layers by referencing the highest authority

Assumes this stack

LuaRustSHIORIMCP

Pasta ソウルドキュメント

Memories of pasta twine together—now and then a knot, yet always a delight.

このドキュメントは、pastaプロジェクトの「憲法」です。すべての設計判断、実装方針、開発活動の根拠となる「あるべき姿」を定義します。

ドキュメントヒエラルキー

pastaプロジェクトのドキュメントは、以下の優先順位と役割を持ちます：

Level 0: Entry Point

README.md - プロジェクト概要（導入・アーキテクチャ）

Level 1: Constitution

SOUL.md - プロジェクトの憲法（Why: ビジョン、コアバリュー、あるべき姿）
GRAMMAR.md - 利用者向けクイックリファレンス（例文豊富な学習用資料）
AGENTS.md - AI開発支援（Kiro workflow、ステアリング）

Level 2: Implementation Layer

実装層ドキュメント。技術的詳細と品質管理を担当。

クレートREADME:

pasta_dsl/README.md - DSLパーサーAPI
pasta_core/README.md - レジストリAPI
pasta_lua/README.md - Luaトランスパイラ・ランタイム
pasta-lua-coding skill - Lua APIリファレンス（references/に詳細）
pasta_lsp/README.md - Language Server Protocol実装
pasta_shiori/README.md - SHIORI DLLインターフェース
pasta_sample_ghost/README.md - サンプルゴースト

品質管理ドキュメント:

TEST_COVERAGE.md - テストカバレッジマップ
OPTIMIZATION.md - トランスパイラ最適化リファレンス
SCENE_TABLE_REVIEW.md - シーンテーブル設計レビュー

Level 3: Steering (AI向け)

.kiro/steering/ - AI向けプロジェクトルール（完全性優先）
doc/spec/ - 言語仕様書（章別分割、AI向け必要な章のみ参照）

ルール: 仕様の衝突時は doc/spec/ を優先し、GRAMMAR.md・README.md を修正する

1. ビジョン

プロジェクトの存在意義

pastaは、「伺か」のようなデスクトップマスコットや、シナリオ型ゲームを実現するための対話スクリプトエンジンです。

コア概念：「パスタのように絡み合う会話」

会話の記録というのは、長い長い一本の糸です。この糸は時に絡み合い、時に結び目を作りながら、パスタのように複雑に織りなされていきます。

この絡み合いこそが、会話の意外性と面白さを生み出します。前方一致によるランダムジャンプを主軸にすることで、スクリプト作者が意図した範囲内での自然な会話の揺らぎを実現します。

ミッション

ゴースト会話の記述基盤: デスクトップマスコットの掛け合い会話を直感的に記述できるスクリプト言語を提供する
シナリオエンジンとしての汎用性: ゲームエンジンとしても流用可能なデータ構造とランタイムを提供する
エコシステムとの統合: SHIORI.DLLインターフェースによる従来資産の活用と、arekaへの統合による次世代基盤の確立

2. コアバリュー

pastaの設計を貫く4つの柱：

2.1 日本語フレンドリー

原則: 日本語話者が直感的に使えること

全角キーワード対応: ＊、・、＠、＄、＞など、全角文字で記述可能
タイプ量削減: 全角文字なら1文字で済むマーカーを採用
読みやすさ: 日本語の文章の中に自然に溶け込む文法設計

例:

＊会話
  ぱすた：おはよう！
  ラザニア：ごきげんよう、今日も良い天気ですわね

2.2 UNICODE識別子

原則: グローバルな多言語対応

日本語シーン名: ＊挨拶、＊自己紹介など
日本語変数名: ＄カウンター、＄ユーザー名など
Unicode Identifier仕様: XID_START / XID_CONTINUE準拠
文化的柔軟性: 各言語圏のユーザーが母語で記述可能

2.3 yield型エンジン

原則: 継続可能な出力ストリーム

Generator/yieldパターン: イベント出力を逐次yield
チェイントーク対応: 連続した会話の中断・再開が可能
UI独立性: 出力ペース制御をエンジン外（areka層）に委譲

設計意図: スクリプトエンジンは純粋なロジック層として動作し、UI表現とのカップリングを排除

2.4 宣言的フロー

原則: if/while/forのない、シンプルな制御構造

Call/Jump制御: シーンへのジャンプ・呼び出しで会話を制御
属性フィルタリング: 条件判定は属性マッチングで表現
複雑ロジック: 必要ならLuaブロックで実装

設計意図: スクリプト作者が会話フローに集中できる、読みやすく保守しやすい文法

3. 設計原則

3.1 行指向文法

原則: 行頭の数文字で行属性が確定する

行の種類は冒頭インデント＋キーワードで判定
改行が行の区切り（明確な終端）
例外はLuaコードブロックのみ（複数行）

利点:

パーサー実装がシンプル
スクリプト作者が直感的に理解可能
エラーメッセージが行単位で明確

3.2 前方一致によるランダム選択

原則: 意外性と再生可能性の両立

シーン検索

＞挨拶 → 「挨拶」で始まるすべてのシーンが候補
候補からランダムに1つを選択
同名シーンの重複定義が意図的にサポートされる

単語選択

＠greeting → 登録された単語値リストからランダム抽出
前方一致により、関連語彙を柔軟にグルーピング可能

設計意図:

会話に自然な揺らぎを持たせる
スクリプト作者が意図した範囲内での変化を実現
繰り返し実行時の単調さを回避

3.3 UI独立性の原則

原則: Wait/Syncはマーカーのみ、制御はUI層が実装

スクリプトエンジンは Wait, Sync などのイベントをマーカーとして出力するのみ
実際の待機処理、同期処理はareka層（UI層）が実装
エンジンは純粋なロジック層として独立

利点:

エンジンのテスタビリティ向上
UI実装の自由度確保
プラットフォーム非依存性

4. 辞書アーキテクチャ

pastaの核となるデータ構造は「シーン辞書」と「単語辞書」です。

4.1 シーン辞書（Label Table）

シーンは会話の単位であり、前方一致検索とランダム選択の対象です。

グローバルシーン

定義: ＊シーン名

ファイル全体からアクセス可能
前方一致検索の基本単位
同名シーンの重複定義が可能（ランダム選択）

用途:

会話のエントリーポイント
独立したイベントハンドラ
再利用可能な会話パターン

例:

＊挨拶
  ぱすた：おはよう！

＊挨拶
  ぱすた：こんにちは！

＊挨拶_朝
  ぱすた：おはようございます！

→ ＞挨拶 は3つすべてが候補となりランダム選択

ローカルシーン

定義: ・シーン名（親シーン内でインデント）

親グローバルシーン内でのみアクセス可能
スコープが限定された、サブルーチン的な扱い
名前空間の汚染を防ぐ

用途:

選択肢の実装
親シーン固有のサブフロー
一時的な会話分岐

例:

＊メニュー
  ぱすた：何をする？
  ＞選択肢
  
  ・選択肢1
    ぱすた：選択肢1が選ばれました
  
  ・選択肢2
    ぱすた：選択肢2が選ばれました

4.2 単語辞書（Word Dictionary）

単語は文字列のリストであり、ランダム選択により会話に揺らぎを与えます。

グローバル単語

定義: ＠単語名：値1、値2、値3（ファイルレベル、インデントなし）

ファイル全体からアクセス可能
プロジェクト共通の語彙として機能

用途:

共通の挨拶表現
汎用的な相槌
複数箇所で使い回す定型句

例:

＠挨拶：おはよう、こんにちは、こんばんは
＠相槌：うん、そうだね、なるほど

シーン単語

定義: ＠単語名：値1、値2（グローバルシーン内、インデント）

親グローバルシーン内でのみアクセス可能
シーン固有の語彙として機能

用途:

そのシーンでのみ使う専門用語
文脈依存の表現バリエーション

例:

＊料理の会話
  ＠食材：トマト、玉ねぎ、じゃがいも
  ぱすた：今日は＠食材　を使って料理するよ

アクター単語

定義: ＠単語名：値（アクタースコープ内）

特定アクター固有の表現・表情として機能
さくらスクリプトの\s[表情ID]などを格納

用途:

アクター固有の表情定義
キャラクター特有の口癖バリエーション

例:

％ぱすた
  ＠通常：\s[0]
  ＠照れ：\s[1]
  ＠驚き：\s[2]

＊会話
  ぱすた：＠驚き　えっ、本当！？

5. シーン実行アーキテクチャ

pastaの核心は、静的な「辞書」（シーン辞書・単語辞書）だけでなく、それらが実行時にどのように動作するかにあります。本章では、シーン関数のLua実行モデルを映画撮影のメタファーで説明します。

5.1 映画撮影のメタファー

pastaは「台本DSL」として設計されており、実行モデルは映画撮影に喩えることができます。

要素	メタファー	Lua実体	役割
シーン	台本（脚本）	`function SCENE.__シーン名__(act, ...)`	会話の台本、Lua関数として定義
アクター	役者	`act.アクター`	発話者、表情変更の主体
アクション	演技	`talk()`, `word()`	実際の発話・動作
act	カメラ	`act` オブジェクト	撮影装置、出力の受け皿

映画撮影の流れ:

台本準備: シーン（Lua関数）が定義される
撮影開始: 監督の「アクション！」でシーン関数が呼び出される
演技: アクター（役者）がact（カメラ）に向かって発話・動作する
記録: actオブジェクトがすべての出力を記録（撮影）する
カット: シーン関数が終了または次のシーンへ遷移

この4要素の関係性が、pastaの実行モデルの本質です。

5.2 シーン関数の構造

Pasta DSLで定義されたシーンは、トランスパイラによりLua関数に変換されます。

関数シグネチャ

function SCENE.__シーン名__(act, ...)
    local args = { ... }
    local save, var = act:init_scene(SCENE)
    -- シーンの本体
end

各要素の役割:

act: カメラオブジェクト。すべての出力の受け皿
...: シーン呼び出し時に渡された引数
save: グローバル変数（＄＊変数名）へのアクセス
var: ローカル変数（＄変数名）へのアクセス

coroutine/yieldパターン

pastaはLuaのコルーチンとyieldを活用し、継続可能な出力ストリームを実現します。

シーン実行中、発話やイベントは逐次yieldされる
UI層（areka）が出力ペースを制御
チェイントーク（連続会話）の中断・再開が可能

これにより、スクリプトエンジンは純粋なロジック層として動作し、UI表現とのカップリングを排除しています。

5.3 アクター発話の実行モデル

アクターの発話は、actオブジェクト（カメラ）への「撮影」として記録されます。

発話の記録

act.ぱすた:talk(act.ぱすた:word("通常"))
act.ぱすた:talk("こんにちは！")

発話シーケンス:

アクター選択: act.ぱすた でアクターオブジェクトを取得
表情変更: word("通常") で表情コード（\s[0]等）を解決
テキスト出力: talk(...) でactに発話を記録

単語展開による動的テキスト

＠単語名 の参照は、実行時に act:word("単語名") として解決されます。

スコープ解決順序:

アクタースコープ: 現在発話中のアクターの単語辞書
シーンスコープ: 現在実行中のシーンの単語辞書
グローバルスコープ: ファイルレベルの単語辞書

同名の単語が複数スコープに存在する場合、より狭いスコープが優先されます。

5.4 シーン呼び出しと制御フロー

シーン間の遷移は、Call文（＞シーン名）によって実現されます。

Callによるサブルーチン呼び出し

act:call(SCENE.__global_name__, "ローカルシーン", {})

指定シーンを呼び出し、実行後に復帰
実行スタックにコンテキストが積まれる
選択肢実装やサブフロー分岐に使用

末尾呼び出し（Jump相当）

return act:call(SCENE.__global_name__, "次のシーン", {})

return を付けることで末尾呼び出し最適化が適用
スタックを消費せずにシーン遷移
長時間シナリオでのスタックオーバーフローを防止

設計意図: Luaの末尾呼び出し最適化（Tail Call Optimization）を活用し、if/while/forのない宣言的フローを維持しながら、無限に続くシナリオを安全に実行できます。

6. Phase 0: あるべき基盤（完了）

Phase 0（一次設計の再構築）は完了しました。以下は各要素の「あるべき姿」とその達成状況です。

5.1 DSL文法の理想形

あるべき姿: 曖昧性のない、一貫した文法仕様

すべてのマーカーが明確に定義されている
全角/半角の対応が完全
パーサーが一意に解釈可能な文法
エラーメッセージが具体的で理解しやすい

現状の課題:

一部文法の曖昧性・不完全性
エッジケースでの解釈の不一致

5.2 トランスパイル品質基準

あるべき姿: 期待されるLuaコードを確実に生成

パスタスクリプトの意図が正確にLuaコードに変換される
最適化されたコード生成（不要な中間変数なし）
デバッグ可能なコード（行番号対応、コメント保持）
統合テストでの完全一致検証（comprehensive_control_flow.pasta）

現状の課題:

トランスパイル結果の品質問題
一部機能で期待される出力との乖離

5.3 シーンテーブル設計

あるべき姿: 前方一致検索を効率的に実現

Radix Trie等の高効率データ構造
O(log n)以下の検索時間
メモリ効率の最適化

現状の課題:

シーンテーブル設計の不備
検索アルゴリズムの最適化不足

5.4 宣言的制御フロー

あるべき姿: Callによる明快な制御

Call: サブルーチン呼び出し、実行後復帰
末尾Call（旧Jump）: トランスパイラが自動判定し最適化
属性フィルタリングによる条件分岐
ネストした制御フローの明確な実装

現状の課題:

Call文の実装品質
戻り値の扱いの不整合

5.5 過去完了仕様31件からの知見

教訓:

要件と実装の一致: 仕様書と実装の乖離を継続的に検証
テストファースト: 新機能は必ずテストを先に書く
段階的な進化: 大規模な変更は小さなステップに分割
回帰防止: リグレッションテストの徹底

5.6 Phase 0完了基準（Definition of Done）

以下すべてを満たした時点でPhase 0完了とする：

文法・パーサー

SPECIFICATION.md 全マーカー定義完了
全角/半角対応表の完全性
cargo test pasta_core 100%パス（94テスト）
cargo test pasta_lua 100%パス（249テスト）
cargo test pasta_shiori 100%パス（28テスト）

トランスパイル品質

comprehensive_control_flow.pasta の期待出力検証（Lua版Golden Test）
- 8つのスナップショットテスト実装済み
- comprehensive_control_flow.pastaは旧文法のためスキップ（TODO: 更新予定）
スナップショットテスト整備（insta crate使用）
最適化レベルの文書化（OPTIMIZATION.md）

ドキュメント整合性

SOUL.md ⇔ SPECIFICATION.md 一貫性検証（完全）
Gap Analysis完了
ドキュメントヒエラルキー明文化
TEST_COVERAGE.md 更新済み

テストカバレッジ

TEST_COVERAGE.md 作成（機能⇔テストマッピング）
未テスト領域の特定と受容判断
Runtime E2E テスト整備（16テスト）

設計品質

シーンテーブル設計レビュー完了（SCENE_TABLE_REVIEW.md）
Call文の実装（末尾Call自動判定含む）
リグレッションテスト整備（483テスト）

7. 開発哲学

7.1 テストファースト

原則: 実装よりもテストを先に書く

新機能は必ずテストケースから始める
リグレッションテストで品質を保証
cargo test --workspace が常にパスする状態を維持

7.2 段階的な進化

原則: 大きな変更は小さなステップで

Phase単位での機能追加
各Phaseでの品質ゲート通過
MVP禁止：中途半端な完成は認めない

7.3 仕様と実装の一致

原則: ドキュメントとコードは常に同期

SPECIFICATION.mdが権威的ソース
実装変更時は必ず仕様書を更新
Gap Analysisによる定期的な整合性検証

7.4 UI独立性の徹底

原則: エンジンは純粋なロジック層

Wait/Syncはマーカー出力のみ
UI制御はareka層に委譲
ユニットテスト可能性を最優先

8. ターゲットユーザー

デスクトップマスコット作者: 伺か互換環境での会話スクリプト記述
ゲーム開発者: シナリオ型ゲームの対話エンジンとして活用
LLM統合開発者: MCP連携による動的対話システムの構築

9. ロードマップ

現在地: Phase 2（コア機能実装）

Phase 0, Phase 1は完了し、現在はPhase 2（コア機能実装）を進行中です。

Phase 1: 基盤確立（完了）

安定したDSL文法
信頼性の高いトランスパイラ
効率的なシーン検索

Phase 2: コア機能実装（進行中）

シーン継続チェーン
インライン多段解決
Luaランタイム拡充

Phase 3: 高度機能

イベントハンドリング拡充
永続化機能
デバッグツール

Phase 4: エコシステム統合

SHIORI.DLL完全対応
areka統合
MCP/LLM連携

最終更新: 2026-03-07 ステータス: Phase 2進行中 - コア機能実装フェーズ

What's inside

9 sections covering vision, 4 core values, 3 design principles, dictionary architecture, execution model, Phase 0 status, development philosophy, target users, and roadmap

Change this for your project

Replace ekicyou/pasta with your own repository name and project name throughout
Replace pasta_dsl, pasta_core, pasta_lua, pasta_lsp, pasta_shiori, pasta_sample_ghost with your own crate names
Replace areka with your own UI layer name
Replace Kiro and .kiro/steering/ with your own AI workflow tool and path

Where it goes

Keep it in your repository where the agent or team that needs it will read it.

Worth borrowing

Document hierarchy with explicit priority rules (Level 0, 3) for resolving specification conflicts
Constitution document that captures non-negotiable design decisions and their rationale
Phase-based roadmap with explicit Definition of Done checklists for each phase

Pasta ソウルドキュメント

What this file does

When to use it

Assumes this stack

Pasta ソウルドキュメント

ドキュメントヒエラルキー

Level 0: Entry Point

Level 1: Constitution

Level 2: Implementation Layer

Level 3: Steering (AI向け)

1. ビジョン

プロジェクトの存在意義

コア概念：「パスタのように絡み合う会話」

ミッション

2. コアバリュー

2.1 日本語フレンドリー

2.2 UNICODE識別子

2.3 yield型エンジン

2.4 宣言的フロー

3. 設計原則

3.1 行指向文法

3.2 前方一致によるランダム選択

シーン検索

単語選択

3.3 UI独立性の原則

4. 辞書アーキテクチャ

4.1 シーン辞書（Label Table）

グローバルシーン

ローカルシーン

4.2 単語辞書（Word Dictionary）

グローバル単語

シーン単語

アクター単語

5. シーン実行アーキテクチャ

5.1 映画撮影のメタファー

5.2 シーン関数の構造

関数シグネチャ

coroutine/yieldパターン

5.3 アクター発話の実行モデル

発話の記録

単語展開による動的テキスト

5.4 シーン呼び出しと制御フロー

Callによるサブルーチン呼び出し

末尾呼び出し（Jump相当）

6. Phase 0: あるべき基盤（完了）

5.1 DSL文法の理想形

5.2 トランスパイル品質基準

5.3 シーンテーブル設計

5.4 宣言的制御フロー

5.5 過去完了仕様31件からの知見

5.6 Phase 0完了基準（Definition of Done）

文法・パーサー

トランスパイル品質

ドキュメント整合性

テストカバレッジ

設計品質

7. 開発哲学

7.1 テストファースト

7.2 段階的な進化

7.3 仕様と実装の一致

7.4 UI独立性の徹底

8. ターゲットユーザー

9. ロードマップ

現在地: Phase 2（コア機能実装）

Phase 1: 基盤確立（完了）

Phase 2: コア機能実装（進行中）

Phase 3: 高度機能

Phase 4: エコシステム統合

What's inside

Change this for your project

Where it goes

Worth borrowing

Related Documents

SOUL

AEGIS SOUL.MD — SECURITY OPERATIONS CENTER (SOC) V4

SOUL , Sable

SysAdmin AI — Safety Rules