diff --git a/2-core-model.md b/2-core-model.md index 340b7e7..74324cc 100644 --- a/2-core-model.md +++ b/2-core-model.md @@ -56,7 +56,7 @@ ObjectはOperation定義を直接持たず、0個以上のInterface参照をorde Interface集合のmembershipはset semanticsを持ち、同じ参照を重複して含めない。列挙順はOperation解決には影響しないが、HostがInterfaceを公開した順序としてUI表示に使用できる。 -InterfaceとOperationの意味論は[2.2. Interface / Operation](2.2-operation.md)、Descriptorのlogical structは[3. Protocol](3-protocol.md)、人間とAIへの表示は[4.1. AI用Tools](4.1-ai-tools-example.md)で扱う。 +InterfaceとOperationの意味論は[2.2. Interface / Operation](2.2-operation.md)、Descriptorのlogical structは[3. Protocol](3-protocol.md)、AI向け操作は[4.1. AI Tools](4.1-ai-tools.md)、人間とAIへのsignature表記は[4.2. Text View](4.2-text-view.md)で扱う。 ## Core interaction diff --git a/2.2-operation.md b/2.2-operation.md index c3584ce..e9974fa 100644 --- a/2.2-operation.md +++ b/2.2-operation.md @@ -160,7 +160,7 @@ Operation Resultには、Descriptorの`entry`型として新しいエントリ `entry`は同じWorldspace内のcanonical absolute pathである。Clientはreturn typeに従って`entry`型の位置を認識する。通常の`string`やopaqueな`json`に含まれるpathらしい文字列を、エントリとして推測してはならない。 -Clientは発見したpathを必要な深さで`observe`する。Operation ResultへObject公開情報やInterface Descriptorを先行同梱しない。 +Clientは発見したpathを参照として利用でき、Objectの公開情報が必要になったときに、必要な深さで`observe`する。発見したすべてのpathの即時取得は要求しない。Operation ResultへObject公開情報やInterface Descriptorを先行同梱しない。 Operationの実行対象と、結果として発見されたエントリのTree上の位置は独立している。発見されたエントリは実行対象の子である必要はなく、親、兄弟、またはWorldspace内の任意の位置にあってよい。 diff --git a/4-client.md b/4-client.md index 7756a65..26d627d 100644 --- a/4-client.md +++ b/4-client.md @@ -23,6 +23,16 @@ Operationを通して発見されたpathは、必ずしもKnown Spaceへ追加 既知エントリ間の移動や参照はClient側で処理できる。既知の空間を辿るたびにHostへ問い合わせる必要はない。 +## 取得・保持・提示の分離 + +ユーザーやAIがpathを知っていること、ClientがObjectを観測・保持していること、Clientがindexable edgeも観測・保持していることは別の状態である。 + +ClientはKnown Spaceにない有効なpathも取得対象にできる。過去に観測していないことだけを理由に取得を拒否せず、現在のHostの公開状態に従って`observe`する。取得前に仮のObjectをKnown Spaceへ登録する必要はない。Pathを知っていること自体は公開可視性や実行権限を保証しない。 + +観測したObjectのどの情報を提示するかは、上位インターフェースの責務である。ClientがObject情報を保持していても、配置だけを提示する場面ですべての説明やInterfaceを展開する必要はない。提示済みの情報とcache内容を同一視しない。 + +Objectを観測・保持したことだけでは、そのpathを既知のtreeへ接続するindexable edgeを得たことにはならない。Treeの構成には観測済みのedgeを使い、pathのprefixや階層関係からedgeを推測しない。 + ## Entry TreeとObject observation Clientは、観測したObjectをcanonical path上のEntryへ対応付け、観測済みのindexable child edgeとともに保持できる。具体的なcache表現は規定しない。Clientは`ObjectObservation`に近い入れ子構造またはforestを保持しても、path index、flatなObject store、Entry Treeへnormalizeしてもよい。 @@ -61,7 +71,7 @@ ClientはDescriptorが必要なInterface参照とcacheを比較し、未知のIn Clientは、Hostから`observe`で取得したindexableなエントリツリーをDiscoverable Spaceとして保持する。Discoverable Spaceとして扱う間、Clientはその観測済みtreeの構造を保持する必要がある。 -Discoverable SpaceはKnown Spaceの部分集合であり、AI向け`discover`などの機械的探索に利用する。Worldspace rootまたはClientが選択した起点からindexable edgeで到達できる、materialize済みの範囲によって構成される。 +Discoverable SpaceはKnown Spaceの部分集合であり、AI向けの`tree`など、indexableな配置の探索に利用する。Worldspace rootまたはClientが選択した起点からindexable edgeで到達できる、materialize済みの範囲によって構成される。 Clientが`observe`結果をmergeし、`children`が存在するparent nodeから以前のindexable edgeが返されなくなった場合、その子エントリをDiscoverable Spaceから除外する。その結果、保持しているどの起点からも到達不能になったsubtreeは、その場で破棄できる。ただし、別の経路から到達できるエントリ、Clientがpinしたエントリ、実行中のOperationが参照しているエントリは引き続き保持してよい。`children`が省略されたnodeはedge削除の根拠にしない。 @@ -69,7 +79,9 @@ Operationを通して発見されたpathは、それだけではDiscoverable Spa ## 一時的な発見とpin -Clientは、Operation Resultの`entry`型として発見したpathを現在の結果として一時的に扱える。標準的なClientはOperationのreturn typeからentry pathを抽出して重複を除去し、Known Spaceと比較して必要なpathだけを`depth = 0`で観測する。複数の`observe`が必要な場合、それぞれを個別のrequestとして並行実行できる。 +Clientは、Operation Resultの`entry`型として発見したpathを、そのObjectを即時に観測せず、現在の結果として提示・利用できる。結果のpathを提示することと、Objectを取得することは別であり、発見したすべてのpathの即時取得は要求しない。 + +Objectの公開情報が必要になった時点で、Clientは必要なpathを観測できる。対象Objectだけが必要なら`depth = 0`を使う。Client policyとして先行取得してもよく、その場合はOperationのreturn typeからentry pathを抽出して重複を除去し、保持済みの観測と比較して必要な取得を行う。複数の`observe`が必要な場合、それぞれを個別のrequestとして並行実行できる。 一時的に取得したエントリは、結果の利用が終わった時点で破棄してよい。 @@ -137,6 +149,8 @@ ClientはHostが返すProtocol errorの`code`で回復actionを決定し、人 `OperationOutcomeUnknown`では、Operationが未実行またはrollback済みであることが保証されない。ClientはOperationを自動再実行せず、対象Objectをstaleとして再観測するか、domain固有の照会手段を提示する。`Internal`、Transport timeout、connection lossの場合もOperationを自動再実行しない。Response不達はProtocol errorへ変換せず、Transport failureとOperation outcomeが不明な状態をClient内部で保持する。WIPはOperationをObject stateへのeffectで分類してretry可否を推測しない。 +ClientがOperation結果の`entry`を付随的に取得する場合、その取得の成否は元のOperationの成否と分けて扱う。参照先の`observe`が失敗しても、成功済みOperationを失敗扱いしたり、そのOperationを再実行したりしてはならない。取得失敗は、その参照先への別のinteractionの失敗として提示・処理する。 + HTTP authentication failureとWorldspace endpoint全体のaccess denialはTransport layerのfailureであり、WIPの`PermissionDenied`へ変換しない。 ## 想定実装 @@ -144,7 +158,15 @@ HTTP authentication failureとWorldspace endpoint全体のaccess denialはTransp Clientは用途に応じて複数の上位インターフェースを提供できる。 - GUI上のWorldspace View -- AI向けTools +- [AI Tools](4.1-ai-tools.md) - PTC / REPL向けスクリプティングAPI -これらは同一のKnown Space、Discoverable Space、Object identity、観測整合性管理を共有してよい。 \ No newline at end of file +これらは同一のKnown Space、Discoverable Space、Object identity、観測整合性管理を共有してよい。 + +PTC / REPL bindingでは、Operationを通常のメソッド呼び出しへ投影してよい。 + +```python +issue.close(reason="duplicate") +``` + +この場合もClientがInterfaceとOperationを解決して`call_operation`を利用し、Object identityと観測整合性を管理する。AI Toolsの3操作は、そのAI向けインターフェースの契約であり、PTC / REPLの呼び出し構文を制限しない。 \ No newline at end of file diff --git a/4.1-ai-tools-example.md b/4.1-ai-tools-example.md deleted file mode 100644 index bf03967..0000000 --- a/4.1-ai-tools-example.md +++ /dev/null @@ -1,62 +0,0 @@ -# 4.1. 例：AI用Tools - -## 目的 - -AI用Toolsは、WIP ClientがAIへ提供する想定インターフェースである。Protocol structをそのまま露出せず、Clientが保持するKnown Space / Discoverable Spaceと組み合わせて、AIがWorldspaceを理解・探索・操作しやすい形へ投影する。 - -現時点では、**discover / inspect / invoke** の3操作を基本とする。 - -## `discover` - -`discover(scope, query)` は、Clientが保持するDiscoverable Spaceから目的に関連するエントリを探す。 - -検索対象は、Hostから`observe`によって取得されたindexableなエントリ公開情報に限定する。Operationによって新たに発見されたentry pathは、一時的な結果として扱うか、観測してKnown Spaceへ保持できるが、それだけでは`discover`の検索対象にはならない。 - -`discover`はドメインデータを検索する操作ではない。Issue本文やRAG corpusなどを検索する場合は、その能力を持つObjectのOperationを`invoke`する。 - -## `inspect` - -`inspect(target)` は、対象エントリ / Objectについて**何ができるか**を把握するための操作である。ClientはObjectのInterface参照のordered setを解決し、各Interface Descriptorに宣言されたOperationを提示する。 - -Objectのドメインデータをpropertiesとして直接公開することは前提としない。データを読む行為もOperationとして表現する。 - -例えばIssueでは、次のような操作が示され得る。 - -- `read_body()` — 本文を読む。 -- `get_metadata()` — 期日、担当者、ラベルなどを取得する。 -- `get_related_items()` — 関連Objectのentry pathを取得する。 -- `close(reason: string)` — 理由を添えてIssueをクローズする。 - -Operationの関数宣言と短いdocumentationは、Objectが参照する各[Interface Descriptor](2.2-operation.md)から取得する。ClientはObjectの立項順でInterfaceを表示し、異なるInterfaceで同じOperation名が存在する場合や出所を明示したい場合は、`.`の形でqualifyできる。この表記は表示用であり、Protocol callではInterface参照とOperation名を別fieldとして送る。 - -Clientは検証済みDescriptorからIDL風のInterface signatureを生成し、人間とAIへ提示する。利用するAI providerがTool schemaを要求する場合、Client adapterがDescriptorからJSON Schema等へ変換する。Provider固有schemaをHostがWIP Interfaceとして提供する必要はない。 - -Object signatureとInterface signatureのplain text表記は、[4.2. Text View](4.2-text-view.md)で定義する。これは`inspect`結果に使える表示形式の一種であり、signatureの組み合わせ、Tool responseのdata structure、Protocolの交換形式を定義するものではない。 - -## `invoke` - -`invoke(target, interface, operation, arguments)` は、`inspect`によって発見したInterfaceとOperationの組を実行する。`arguments`はOperationのparameter declarationに従う名前付きfieldのrecordであり、位置引数は用いない。引数を持たないOperationには空のrecordを渡す。Clientはargumentsを検証し、対象path、観測したObjectのoptionalなvalidator、選択したInterface参照とvalidatorから`call_operation` requestを構築する。 - -PTC / REPL bindingでは、通常のメソッド呼び出しへ投影してよい。 - -```python -issue.close(reason="duplicate") -``` - -ClientはエントリをObjectへ解決し、WIPの`call_operation`を利用して実行する。Object同一性やエントリとObjectの観測整合性はClient側で処理し、AI自身に追跡させない。 - -## エントリの発見 - -AIが新しいエントリを知る経路は複数ある。 - -- `discover`によってDiscoverable Spaceから見つける。 -- Known Space上の既知エントリを辿る。 -- Operation Resultの`entry`型としてpathを受け取る。 - -ClientはOperation Resultからentry pathを抽出し、必要なdepthでそのpathを`observe`する。新たに取得したエントリの保持、Treeへの統合、indexableな範囲の管理はClientの責務とし、このページではAI向けToolの意味論だけを扱う。 - -## ドメイン検索 - -全文検索、semantic retrieval、外部API検索などはWIP固有のToolにはしない。 - -検索能力を持つObjectのInterfaceが`query`や`search`などのOperationを宣言し、AIはそれを`invoke`する。結果として`entry`型のpathが返された場合、Clientは必要なpathを取得し、一時的な発見結果として利用するかKnown Spaceへ保持できる。 \ No newline at end of file diff --git a/4.1-ai-tools.md b/4.1-ai-tools.md new file mode 100644 index 0000000..af5456f --- /dev/null +++ b/4.1-ai-tools.md @@ -0,0 +1,105 @@ +# 4.1. AI Tools + +## 目的と適用範囲 + +AI Toolsは、WIP ClientがAIへ提供する、対象の配置を見て、できることを理解し、操作するための上位インターフェースである。本章で定義するAI向けの基礎ツールは **tree / inspect / invoke** の3操作に固定する。 + +Protocol interactionをそのままToolとして公開するものではない。Protocolの`observe` / `fetch_interface` / `call_operation`は[3. Protocol](3-protocol.md)、取得・cache・観測整合性の責務は[4. Client](4-client.md)に従う。GUIやPTC / REPLなど、他のClientインターフェースの構成は本章で制限しない。 + +## 基本的な利用モデル + +| AI向け操作 | AIが行うこと | Clientが引き受けること | +| --- | --- | --- | +| `tree(path, depth)` | indexableな対象の配置を見る | 必要なdepthの観測とtree表示 | +| `inspect(path)` | 対象の説明とできることを知る | Object観測、Interface集合の解決、signature生成 | +| `invoke(target, interface, operation, arguments)` | 選択した操作を名前付き引数で呼ぶ | 引数検証、観測との対応、validator、Protocol requestと結果の処理 | + +これらはProtocol interactionとの一対一対応ではない。特に`inspect`の対象はInterface参照ではなく、Objectを指すpathである。必要な`observe`と複数の`fetch_interface`はClient内部で行う。 + +Inspectで見つけたOperationも`invoke`から呼び出し、Operationごとに新しいToolを登録しない。 + +大量のObjectの発見は、各ドメインのObjectが公開する`list` / `search` / `query`等のOperationで行う。件数制限、検索条件、ページング等は、そのドメインに応じて各Operationが管理する。AIはこれらのOperationも`inspect`で確認し、`invoke`で呼び出す。発見方法が増えても基礎ツールは追加・変更しない。 + +## `tree`: indexableな配置を見る + +`tree(path, depth)`は、起点をdepth 0として、指定depth内のindexableなツリーを全量取得・表示する。 + +- 必要なcoverageを持つ観測を再利用できる。不足する場合はClientが`observe`で取得する。 +- 全量とは、指定した起点・depth・主体に公開されたindexableな範囲の全量であり、Worldspace全体ではない。 +- 名前、path、親子構造を中心に提示する。すべてのObjectのDescriptorやドメインデータを展開しない。 +- Protocolのdepth境界にある未観測のchildrenと、観測済みの空のindexable childrenを混同しない。 +- 指定depth内の一部を黙って省略して完全なtreeとして返さない。既存のresource limit内で成立しない場合は、その失敗を伝える。 +- Cacheに保持されたpathを単にprefixで集めてtreeにしない。Hostから観測したindexable edgeに従い、指定depth外やOperation経由で知っただけのentryを混ぜない。 + +HostがTreeへ公開する範囲は、[Indexable childrenの条件](2.1-object-tree-schema.md#indexable-children)に従う。 + +## `inspect`: 対象の説明とできることを知る + +`inspect(path)`は、そのpathで公開されているObjectの説明と操作を返す。 + +AIがそのpathをtree、会話、Operation結果のいずれから知ったかは、事前条件にしない。ClientがまだObjectを観測していなくても、有効なpathを直接指定できる。Known Spaceにないことだけを理由に拒否せず、現在のHostの公開状態に従って観測する。 + +Clientは次の情報を保持済みの観測から解決し、不足するものを取得する。 + +1. 対象pathのObject。対象だけが必要なら`observe`の`depth = 0`を使用する。 +2. Objectが公開するInterface参照のordered set。 +3. 表示対象のInterfaceに対応する、取得・検証済みのDescriptor。 + +Clientはこれらの情報から、Objectの説明とInterfaceごとの操作を提示する。AIに「先にObjectをobserveして、Interface参照を抜き出し、一つずつfetchする」という手順を要求しない。一方で、Objectの本文やドメインmetadataまで暗黙に読み込むわけではない。それらの取得は対象のOperationとして扱う。 + +### 表示に必要な情報 + +- 対象のpathと、公開されているObjectの説明。 +- InterfaceとOperationの対応。 +- Operation名、短い用途説明、名前付き引数、必須性、引数・結果の型。 +- 操作を理解するために必要な名前付き型・複合型の定義。 + +生のDescriptor JSONを返すだけではなく、検証済みの情報から読みやすいObject signatureとInterface signatureを生成する。各signatureの表記は[4.2. Text View](4.2-text-view.md)に従う。同名Operationが複数Interfaceに存在しても、一つへ平坦化したり、出所を失ったりしない。 + +Invokeへ渡すInterface参照とOperation名は区別して保持し、表示textを再parseして呼出先を決めない。Interfaceの未展開や取得失敗を「操作が存在しない」と誤表示しない。 + +Signatureの配置や、詳細表示・表示対象を選択する具体的なTool引数は本章で固定しない。個々のsignatureを生成するときの全宣言の表示規則はText Viewに従い、表示側でInterface内部を切り詰めない。 + +## `invoke`: 選んだ操作を実行する + +`invoke(target, interface, operation, arguments)`は、対象ObjectのInterfaceとOperationを明示して呼び出す。`target`は対象Objectのpathを指定するものであり、AIにProtocolのvalidator付きTargetを組み立てさせるものではない。 + +`arguments`はOperationのparameter declarationに従う名前付きfieldのrecordであり、位置引数ではない。引数を持たないOperationには空のrecordを渡す。 + +Interfaceを明示するのは、同じObjectの複数Interfaceに同名Operationがあり得るためである。Interfaceの選択をAIへ示すことと、Descriptorの取得手順をAIに管理させることは別である。 + +ClientはObjectとDescriptorの観測を保持し、引数を検証し、path、Object validator、Interface参照とvalidatorをProtocol requestへ設定する。AIにvalidatorの取得・コピー・更新をさせない。同一性管理やvalidatorはsignatureに含めない。 + +Pathを知っていることやInterfaceが表示されたことは、実行権限を意味しない。Hostは呼出時の公開状態、権限、capability、実行条件を引き続き検証する。ClientはresultをDescriptorに従って検証してから提示する。 + +再観測とOperationの再実行を同一視しない。Stale、取消、拒否、結果不明などの扱いはProtocolと[ClientのFailure handling](4-client.md#failure-handling)に従う。結果不明のOperationを自動再実行せず、Operation名からread / writeやretry可否を推測しない。 + +## Pathの発見と移動 + +AIはtree、会話で示されたpath、Operation結果の`entry`などから次の対象を知ることができる。Pathを知っていること、ClientがObjectを観測・保持していること、indexable edgeも観測していることは別の状態である。[Clientの取得・保持・提示の分離](4-client.md#取得保持提示の分離)に従い、未観測のpathは必要になった時点でinspectできる。 + +Clientが内部で保持する情報とAIに表示済みの情報は一致する必要がない。Treeの取得でObject情報を保持していても、AIには名前と構造だけを見せ、詳しい説明と操作はinspectで提示できる。 + +Operation結果の`entry`型pathは、そのまま次の対象への参照として提示できる。すべての結果を即時に観測したり、再帰展開したりすることを必須にしない。AIが必要なpathを選んでinspectするときに、Clientが観測できる。 + +Entryの抽出はDescriptorの型に従う。普通のstringを内容だけからpathと推測しない。結果のentryを観測・保持しても、それだけでindexable edgeを追加しない。 + +Clientが付随的なentry取得を行う場合、その取得失敗と元のOperationの成否を混同しない。成功済みOperationを、結果の参照先が取得できなかったために失敗扱いして再実行させてはならない。 + +## Tool bindingと表示 + +本章の小文字表記は操作の呼称であり、providerごとのTool登録名の大文字・小文字やProtocol名の接頭辞は規定しない。AI providerがTool schemaを要求する場合は、Client adapterがこの3操作のschemaを提供する。Hostにprovider固有のTool schemaを提供させたり、取得したDescriptorごとにToolを追加登録したりしない。DescriptorはClient内部のOperation validationとsignature生成に用いる。 + +Treeの具体的なtext layout、`depth`等の引数のdefault、inspectの表示選択引数、Tool response envelopeについて、本章は共通の具体schemaを定義しない。各bindingは、それらを提供するときにAIへ明示する契約として定め、本章の操作の意味を変えない。Text Viewもsignatureを包むresponse構造や配置を定義するものではない。 + +取得・表示・cache保持を分離するが、特定の内部class構成、eviction algorithm、prefetch schedulerは要求しない。 + +## 検証する利用シナリオ + +- 観測が空のClientで既知pathを直接inspectし、説明と操作を取得できる。 +- Treeが指定depthのindexable範囲を完全に提示し、cache内の他のpathを混ぜない。 +- 複数Interfaceに同名Operationがあっても、正しいInterfaceとOperationを選んでinvokeできる。 +- Search / list結果から必要なentryだけをinspectでき、全件先行取得を要求しない。 +- 非indexableなentryを観測した後も、rootからのtreeにそのentryが混入しない。 +- 参照先の取得失敗を、成功済みOperationの失敗や再実行の理由にしない。 +- 表示やcache利用によって、権限・観測整合性・結果不明の扱いを弱めない。 diff --git a/draft/ai-tools-interaction.md b/draft/ai-tools-interaction.md deleted file mode 100644 index ec2cdc4..0000000 --- a/draft/ai-tools-interaction.md +++ /dev/null @@ -1,115 +0,0 @@ -# AI Tools: tree / inspect / invoke（草案） - -## 位置付け - -この文書は、Yoiでの利用・実装検討を通して決めた、WIP ClientのAI向け操作仕様を記録するdraftである。Protocol interactionをそのままToolとして公開するのではなく、AIが対象の配置を見て、できることを理解し、操作するための上位インターフェースを定める。 - -基本操作は **tree / inspect / invoke** とする。Tool名にProtocol名の接頭辞を付ける必要はない。ここでの小文字表記は操作の呼称であり、providerごとのTool登録名の大文字・小文字やTool response envelopeまでは規定しない。 - -[AI用Toolsの例](../4.1-ai-tools-example.md)にある `discover(scope, query)` に対し、本draftでは `tree(path, depth)` を基本とする。既存章を書き換え済み、またはすべてのWIP Clientへ採用済みという意味ではない。Protocolの `observe` / `fetch_interface` / `call_operation` は変更しない。 - -関連する責務は[Client](../4-client.md)、Object signatureとInterface signatureの表示書式は[4.2. Text View](../4.2-text-view.md)、FSの探索境界は[Filesystem Discovery](filesystem-discovery.md)を参照する。Yoi側の実装追跡はT-713で行う。 - -## 基本的な利用モデル - -| AI向け操作 | AIが行うこと | Clientが引き受けること | -| --- | --- | --- | -| `tree(path, depth)` | indexableな対象の配置を見る | 必要なdepthの観測とtree表示 | -| `inspect(path)` | 対象の説明とできることを知る | Object観測、Interface集合の解決、Interface signature生成 | -| `invoke(target, interface, operation, arguments)` | 選択した操作を名前付き引数で呼ぶ | 引数検証、観測との対応、validator、Protocol requestと結果の処理 | - -これらはProtocol interactionとの一対一対応ではない。特に `inspect` の対象はInterface参照ではなく、Objectを指すpathである。必要な `observe` と複数の `fetch_interface` はClient内部で行う。 - -AI向けの基礎ツールは `tree` / `inspect` / `invoke` の3操作に固定する。Inspectで見つけたOperationも `invoke` から呼び出し、Operationごとに新しいToolを登録しない。 - -大量のObjectの発見は、各ドメインのObjectが公開する `list` / `search` / `query` 等のOperationで行う。件数制限、検索条件、ページング等は、そのドメインに応じて各Operationが管理する。AIはこれらのOperationも `inspect` で確認し、`invoke` で呼び出す。発見方法が増えても基礎ツールは追加・変更しない。 - -## tree: indexableな配置を見る - -`tree(path, depth)` は、起点をdepth 0として、指定depth内のindexableなツリーを全量取得・表示する。 - -- 必要なcoverageを持つ観測を再利用できる。不足する場合はClientが取得する。 -- 全量とは、指定した起点・depth・主体に公開されたindexableな範囲の全量であり、Worldspace全体やすべてのドメインデータではない。 -- 名前、path、親子構造を中心に提示する。すべてのObjectのDescriptorやドメインデータを展開しない。 -- Protocolのdepth境界にある未観測のchildrenと、観測済みの空のindexable childrenを混同しない。 -- 指定depth内の一部を黙って省略して完全なtreeとして返さない。既存のresource limit内で成立しない場合は、その失敗を伝える。 -- Cacheに保持されたpathを単にprefixで集めてtreeにしない。Hostから観測したindexable edgeに従い、指定depth外やOperation経由で知っただけのentryを混ぜない。 - -HostがTreeへ公開する範囲は、[Indexable childrenの条件](../2.1-object-tree-schema.md#indexable-children)に従う。 - -## inspect: 対象の説明とできることを知る - -`inspect(path)` は、そのpathで公開されているObjectの説明と操作を返す。 - -AIがそのpathをtree、会話、Operation結果のいずれから知ったかは、事前条件にしない。ClientがまだObjectを観測していなくても、有効なpathを直接指定できる。 - -Clientは必要に応じて次を行う。 - -1. 対象pathのObjectを観測する。対象だけが必要なら `depth = 0` を使用する。 -2. Objectが公開するInterface参照のordered setを取得する。 -3. 必要なDescriptorをcacheから解決し、不足するものを取得・検証する。 -4. Objectの説明と、InterfaceごとのInterface signatureをまとめて提示する。 - -AIに「先にObjectをobserveして、Interface参照を抜き出し、一つずつfetchする」という手順を要求しない。一方で、Objectの本文やドメインmetadataまで暗黙に読み込むわけではない。それらの取得は対象のOperationとして扱う。 - -### 表示に必要な情報 - -- 対象のpathと、公開されているObjectの説明。 -- InterfaceとOperationの対応。 -- Operation名、短い用途説明、名前付き引数、必須性、引数・結果の型。 -- 操作を理解するために必要な名前付き型・複合型の定義。 - -生のDescriptor JSONを返すだけではなく、検証済みの情報から読みやすいInterface signatureを生成する。同名Operationが複数Interfaceに存在しても、一つへ平坦化したり、出所を失ったりしない。Invokeへ渡すInterface参照とOperation名は区別して保持し、表示textを再parseして呼出先を決めない。 - -具体的なObject signature、Interface signature、型、documentationの表記は、[4.2. Text View](../4.2-text-view.md)を参照する。Text Viewは個々のsignatureの表記を定義し、inspectでの表示対象や配置はAI Tools側で扱う。未展開や取得失敗を「操作が存在しない」と誤表示しないことは、取得側と表示側の共通条件である。 - -## invoke: 選んだ操作を実行する - -`invoke(target, interface, operation, arguments)` は、対象のInterfaceとOperationを明示して呼び出す。Argumentsはparameter declarationに従う名前付きfieldのrecordであり、位置引数ではない。 - -Interfaceを明示するのは、同じObjectの複数Interfaceに同名Operationがあり得るためである。Interfaceの選択をAIへ示すことと、Descriptorの取得手順をAIに管理させることは別である。 - -ClientはObjectとDescriptorの観測を保持し、引数を検証し、path、Object validator、Interface参照とvalidatorをProtocol requestへ設定する。AIにvalidatorの取得・コピー・更新をさせない。通常のInterface signatureへ同一性管理やvalidatorを混ぜる必要もない。 - -Pathを知っていることやInterfaceが表示されたことは、実行権限を意味しない。Hostは呼出時の公開状態、権限、capability、実行条件を引き続き検証する。 - -再観測とOperationの再実行を同一視しない。Stale、取消、拒否、結果不明などの扱いは既存Protocolに従う。結果不明のOperationを自動再実行せず、Operation名からread/writeやretry可否を推測しない。 - -## AIのpath認知とClientの観測状態 - -次の状態は別のものとして扱う。 - -1. AIがpathを参照できるが、ClientはそのObjectをまだ観測していない。 -2. ClientがObjectを観測し、Known Spaceへ保持している。 -3. Clientがindexable edgeも観測し、Discoverable Spaceとして保持している。 - -1は正常な利用状態である。未観測のpathを偽のObjectとしてKnown Spaceへ登録する必要はないし、Known Spaceにないという理由でそのpathのinspectを拒否する必要もない。 - -Clientが内部で保持する情報とAIに表示済みの情報も一致する必要はない。Treeの取得でObject情報を保持していても、AIには名前と構造だけを見せ、詳しい説明と操作はinspectで提示できる。 - -Known Spaceは過去の全pathの台帳でも、Host状態のreplicaでもない。非indexableなObjectを観測してKnown Spaceへ保持しても、その事実だけでtreeの子にはならない。Cacheは接続先・主体・security contextごとに分離する。 - -## Operation結果からの移動 - -Operation結果の `entry` 型pathは、そのまま次の対象への参照として提示できる。すべての結果を即時に観測したり、再帰展開したりすることを必須にしない。AIが必要なpathを選んでinspectするときに、Clientが観測できる。 - -Entryの抽出はDescriptorの型に従う。普通のstringを内容だけからpathと推測しない。結果のentryを観測・保持しても、それだけでindexable edgeを追加しない。 - -Clientが付随的なentry取得を行う場合、その取得失敗と元のOperationの成否を混同しない。成功済みOperationを、結果の参照先が取得できなかったために失敗扱いして再実行させてはならない。 - -## 検証する利用シナリオ - -- 観測が空のClientで既知pathを直接inspectし、説明と操作を取得できる。 -- Treeが指定depthのindexable範囲を完全に提示し、cache内の他のpathを混ぜない。 -- 複数Interfaceに同名Operationがあっても、表示から正しいInterfaceとOperationを選んでinvokeできる。 -- Search/list結果から必要なentryだけをinspectでき、全件先行取得を要求しない。 -- 非indexableなentryを観測した後も、rootからのtreeにそのentryが混入しない。 -- 表示やcache利用によって、権限・観測整合性・結果不明の扱いを弱めない。 - -## 未決事項と既存文書への反映 - -- Treeの具体的なtext layout、Tool引数のdefault、Tool response envelope。 -- Inspectでの詳細表示・表示対象の選択方法とsignatureの配置。 -- 既存の `discover(scope, query)` 例を、汎用Clientの別の投影例として残すか、tree中心の説明へ改訂するか。 - -取得・表示・cache保持を分離することは決定事項だが、特定の内部class構成、eviction algorithm、prefetch schedulerを採用することは、このdraftの決定に含めない。 diff --git a/draft/filesystem-discovery.md b/draft/filesystem-discovery.md index 3e42686..0f91c30 100644 --- a/draft/filesystem-discovery.md +++ b/draft/filesystem-discovery.md @@ -6,7 +6,7 @@ Indexableな範囲の全量取得をClientで縮めるのではなく、Hostが何をindexableとして公開するかを修正する。個々のファイル・フォルダは非indexableなObjectとして要求時に直接解決できる。 -[Object tree / SchemaのIndexable children](../2.1-object-tree-schema.md#indexable-children)、[Client](../4-client.md)、[AI Toolsの操作仕様](ai-tools-interaction.md)を前提とする。Yoi側の実装追跡はT-714、既存投影はT-699である。本稿は仕様決定の記録であり、実装済みであることを示さない。 +[Object tree / SchemaのIndexable children](../2.1-object-tree-schema.md#indexable-children)、[Client](../4-client.md)、[4.1. AI Tools](../4.1-ai-tools.md)を前提とする。Yoi側の実装追跡はT-714、既存投影はT-699である。本稿は仕様決定の記録であり、実装済みであることを示さない。 ## なぜFS全体をindexableにしないか