From 42c489bc52273d87f4466fb4be45366165135cea Mon Sep 17 00:00:00 2001 From: Hare Date: Wed, 7 Oct 2026 02:46:25 +0900 Subject: [PATCH] docs: draft object and interface text views --- 2.2-operation.md | 2 +- 4.1-ai-tools-example.md | 2 + draft/text-view.md | 218 +++++++++++++++++++++++++++++++++++++ draft/unresolved-issues.md | 2 +- 4 files changed, 222 insertions(+), 2 deletions(-) create mode 100644 draft/text-view.md diff --git a/2.2-operation.md b/2.2-operation.md index baa1a32..54b3fe1 100644 --- a/2.2-operation.md +++ b/2.2-operation.md @@ -44,7 +44,7 @@ operation get_related_items( }; ``` -Signature ViewはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。 +Signature ViewはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。ObjectとInterfaceをAIおよび人間向けのplain textへ投影する表示サブ仕様案は、[WIP Text View（草案）](draft/text-view.md)で扱う。 Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter listとして表し、`call_operation`には空のrecordを渡す。 diff --git a/4.1-ai-tools-example.md b/4.1-ai-tools-example.md index 2f28edb..764771a 100644 --- a/4.1-ai-tools-example.md +++ b/4.1-ai-tools-example.md @@ -31,6 +31,8 @@ Operationの関数宣言と短いdocumentationは、Objectが参照する各[Int Clientは検証済みDescriptorからIDL風のSignature Viewを生成し、人間とAIへ提示する。利用するAI providerがTool schemaを要求する場合、Client adapterがDescriptorからJSON Schema等へ変換する。Provider固有schemaをHostがWIP Interfaceとして提供する必要はない。 +Objectの概要とInterfaceのSignature Viewを組み合わせるplain text表示のたたき台は、[WIP Text View（草案）](draft/text-view.md)で扱う。これは`inspect`結果に使える表示形式の一種であり、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を構築する。 diff --git a/draft/text-view.md b/draft/text-view.md new file mode 100644 index 0000000..0cdcefc --- /dev/null +++ b/draft/text-view.md @@ -0,0 +1,218 @@ +# WIP Text View（草案） + +## 位置付け + +WIP Text Viewは、ObjectとInterfaceをAIおよび人間へ提示するための、プレーンテキスト表示フォーマットのサブ仕様案である。Clientの`inspect`結果、CLI、GUIのテキスト表示などで共通に利用できる。Interfaceの型とOperationを示す部分をSignature Viewと呼ぶ。 + +この文書は標準化のたたき台であり、以下の表記とrendering ruleは採用候補である。Protocolの必須機能や新しいdata structureを追加するものではない。 + +正本は[3. Protocol](../3-protocol.md)のObjectおよびInterface Descriptorであり、Text Viewは検証済みの観測から一方向に生成する表示である。 + +- Interfaceの交換形式、手書きのschema言語、Objectのserializationではない。 +- Parser、round-trip、表示textからのDescriptor復元は要求しない。 +- Operationの実行言語ではない。Clientは保持するInterface参照とOperation名を別々に扱い、表示textを再parseしてProtocol requestを構築しない。 +- Textの一致をObject identity、Descriptorの同一性、validator、digestの代用にしない。 +- HostへText Viewの生成・配信を要求せず、Transport BindingやAI providerのTool schemaとは独立させる。 + +旧`draft/wip-idl.md`（削除直前: `7567007^:draft/wip-idl.md`）から、`operation`、`type`、record、list、enum、union、`entry`、documentationの表記を引き継ぐ。IDL sourceを交換する設計、language identifier、source digest、parser用EBNFは引き継がない。旧文書のeffect annotation案も、現行Descriptorに対応する情報がないため表示へ持ち込まない。 + +## 表示対象と入力 + +Rendererが利用するのは、Clientが既に保持する次の情報である。Rendererの呼び出しAPIや内部structは規定しない。 + +- 検証済みObject。 +- Objectを観測したpath（分かる場合）。PathはObjectのfieldではなく配置contextである。 +- ObjectのInterface参照に対応する、検証済みかつ対応formatのInterface Descriptor。 +- Clientが選んだ表示範囲およびdocumentationの展開方針。 + +Interface単独の表示も可能とする。その場合は、取得時のInterface参照とDescriptorを使用する。Interface参照はDescriptor自身のfieldではない。 + +表示は観測時点の公開情報であり、最新状態、Operationの実行権限、実行成功を保証しない。再観測やDescriptor取得のタイミングはClient policyのままとし、表示形式から暗黙のnetwork取得を要求しない。 + +この草案の対象はObjectの概要とInterfaceの宣言である。Object tree全体の描画、Operation arguments / resultのvalue表示、Protocol errorや診断metadataの表示は対象に含めない。 + +## 全体例 + +以下は一つのObjectと、そのObjectが公開する二つのInterfaceを展開した表示である。例中のInterface参照はopaque stringの例であり、参照の命名規則を定めない。 + +```text +object at "/issues/123" { + name: "123"; + /// "Issue 123の公開操作。本文はOperationで取得する。" + interfaces: ["issue.read", "issue.lifecycle"]; +} + +/// "Issueの内容と関連項目を読む。" +interface "issue.read" { + type Relation = enum { parent, sibling, related }; + + type RelatedItems = { + /// "同じWorldspace内の関連項目。" + items: [entry], + next_cursor?: string, + }; + + /// "本文を取得する。" + operation read_body() -> { body: string }; + + /// "関係を指定して関連項目を取得する。" + operation get_related_items( + relation: Relation, + limit?: integer, + ) -> RelatedItems; +} + +/// "Issueのライフサイクルを操作する。" +interface "issue.lifecycle" { + type CloseResult = union { + closed, + blocked({ dependencies: [entry] }), + }; + + /// "理由を添えてIssueをクローズする。" + operation close(reason: string) -> CloseResult; +} +``` + +ObjectとInterfaceは別blockにする。Object blockはInterface参照を示し、後続のInterface blockはその宣言を展開する。この並置は表示上の合成であり、HostがObjectへDescriptorを同梱する仕様ではない。 + +## Object View + +Objectは`object at "" { ... }`と表示する。Pathが分からない場合は`object { ... }`とし、`name`や`ref`からpathを推測しない。 + +- `name: "...";`にObjectの`name`をそのまま表示する。自由なtitleへ置き換えない。 +- `description`がある場合は`name`の後に`/// "..."`で表示する。これはObject全体の説明である。 +- `interfaces: ["...", "..."];`に全Interface参照をHostの立項順で表示する。空集合は`interfaces: [];`と明示する。 +- `ref`とvalidatorは通常表示へ含めない。同一性管理と条件付き実行はClient runtimeの責務のままである。 +- Objectの本文やdomain metadataを推測してpropertyとして追加しない。 + +Rootは`object at "/"`かつ`name: "";`となる。Descriptionがない場合は説明行を省略する。説明の欠落からObjectの用途を補完しない。 + +ChildrenはこのObject Viewに含めない。表示にchildrenがないことは、未観測、観測済みの空集合、表示対象外を区別する情報にはならない。将来tree表示を追加する場合も、Protocolの未観測と空集合の違いを維持する必要がある。 + +## Interface / Signature View + +Interfaceは`interface "" { ... }`と表示する。Objectと併記するときは、そのObjectの`interfaces`順で展開する。異なるInterfaceの宣言を一つのnamespaceへ平坦化しない。 + +Block内では、Descriptorの`types`を宣言順に、続いて`operations`を宣言順に表示する。Record field、parameter、enum / union caseも元の順序を保持する。この順序は表示上の規則であり、Protocol上の名前解決やvalidationを変更しない。 + +同名Operationが異なるInterfaceにある場合も、それぞれのblock内に表示する。BlockのInterface参照が出所を示すため、Operation名を改名したり、参照をOperation名へ連結したりしない。単独のOperation抜粋でもInterface blockを残す。 + +### 型の表記 + +| DescriptorのTypeExpr | 表示 | +| --- | --- | +| Unit / Boolean / Integer / Number | `unit` / `boolean` / `integer` / `number` | +| String / Bytes / Json / Entry | `string` / `bytes` / `json` / `entry` | +| Named | 参照先typeの名前 | +| Record | `{ field: Type, optional_field?: Type }` | +| List | `[Type]` | +| Enum | `enum { first, second }` | +| Union | `union { empty, found(Type) }` | + +Named type declarationは`type Name = Type;`とする。Enum、unionを含むすべてのTypeExprを、Descriptorで現れる位置にそのまま表示できる。Named typeを別Interfaceの同名typeと混同しない。 + +`?`は`required = false`のfieldまたはparameterにだけ付ける。Nullable、default value、一般化したoptional型は意味しない。`unit`とoptionalの違いを維持する。 + +Payloadのないunion caseは`empty`、payloadがあるcaseは`found(Type)`とする。`empty`と`empty(unit)`を区別する。空record、空enum、空unionが検証済みDescriptorに現れる場合は、それぞれ`{}`、`enum {}`、`union {}`と表示し、caseを補わない。 + +型の意味、numeric range、validationはProtocolに従い、表示仕様で再定義しない。特に`entry`はWorldspaceのpath型であり、`string`へ置き換えない。Unionのwire discriminatorやbytesのwire encodingはSignature Viewに混ぜない。 + +### Operationの表記 + +```text +operation get_related_items( + relation: Relation, + limit?: integer, +) -> { + items: [entry], + next_cursor?: string, +}; + +operation refresh() -> unit; +``` + +Operationは`operation Name(parameters) -> ReturnType;`とする。Parameterは名前付きであり、並び順から位置引数を導入しない。引数がない場合は`()`、return typeは`unit`を含め必ず表示する。 + +Operation名からread / write、idempotency、retry可否、domain failure、実行可能状態を推測してannotationを付けない。Domain failureがreturn typeのUnionとして宣言されていれば、そのUnionを通常どおり表示する。 + +## 名前と文字列 + +Path、Object name、Interface参照、説明文は、二重引用符で囲んだJSON stringのescape規則を使って表示する。これは文字列を安全に区切るための表記の借用であり、View全体をJSONにするものではない。Unicode normalization、case変換、pathのURL encodingを行わない。 + +Type名、Operation名、parameter名、field名、case名は次のように表示する。 + +- `[A-Za-z_][A-Za-z0-9_]*`に一致し、下記の表示keywordでなければ、そのまま表示する。 +- それ以外はbacktickで囲む。内部のbacktickは`` \` ``、backslashは`\\`、改行・tab等はJSON stringと同じescapeで表示する。 +- 表示keywordは`object`、`at`、`name`、`interfaces`、`interface`、`type`、`operation`、`enum`、`union`、および`unit`、`boolean`、`integer`、`number`、`string`、`bytes`、`json`、`entry`とする。 + +```text +interface "example" { + type `string` = { `表示名`: string }; + operation `find-item`(`search term`: string) -> `string`; +} +``` + +この規則はProtocolへidentifierの文字種制限を追加しない。旧IDLのUpperCamelCase / snake_caseを表示時の強制変換として復活させない。 + +すべてのHost由来文字列について、改行や制御文字が表示の構造、端末制御列、別の宣言を作らないようescapeする。JSON stringの標準escapeに加えて、DEL、C1制御文字、Unicodeの改行文字（U+2028 / U+2029）と双方向表示制御文字は`\uXXXX`表記にする。改行escapeは表示上のものであり、元の値は変更しない。 + +## Documentation + +Documentationは対象の直前に`/// ""`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Object descriptionも同じ表記を使用するが、DescriptorのDocumentationへ変換するわけではない。 + +通常表示では`summary`だけを使い、明示的な詳細表示では同じ対象のsummary行に続けて`/// details "
"`を追加する。Documentationがない対象へ説明を生成しない。Empty stringとfieldの欠落は区別し、存在する空文字列は`""`として表示する。 + +ReturnDeclarationのdocumentationは、parameter listの閉じ括弧の後、return arrowの直前に置く。 + +```text +/// "対象を検索する。" +/// details "結果には同じWorldspace内のpathだけを含む。\n本文は別途取得する。" +operation search( + /// "検索語。" + query: string, +) +/// "条件に一致する項目。" +-> { items: [entry] }; +``` + +説明はすべてHost由来のplain text dataであり、system instruction、rendererの指示、markupとして解釈しない。引用やescapeだけでprompt injectionを防げるとはみなさず、AIへ渡すadapterもTool結果と信頼済みinstructionの境界を維持する。Markdown内へ埋め込む場合はadapterが内容に衝突しないcode fence等を選ぶ。 + +## 表示範囲と省略 + +基本表示はObjectの概要と、展開対象に選ばれた各Interfaceの全type / Operationおよびsummaryで構成する。Details、`ref`、validator、childrenを通常表示しないことは、このViewの範囲定義であって、欠損したProtocol responseを意味しない。 + +Interface参照の一覧とDescriptorの展開は別である。Descriptorを展開していないInterfaceはObjectの一覧から消さず、blockの代わりに次のrenderer注記を置く。 + +```text +// view: interface "issue.lifecycle" not expanded +``` + +これは未取得、未対応format、取得失敗、表示範囲外等を区別するProtocol statusではない。いずれの場合も、空のInterface blockとして表示して「Operationがない」と見せてはならない。検証に失敗したDescriptorから宣言を生成しない。理由を提示する場合はClientの診断表示として分離する。 + +Operation選択や表示budgetによって宣言を省略したInterface blockの先頭には`// view: partial`を置く。表示するOperationから参照するNamed typeは推移的に含める。型依存も含めて収まらない場合は、そのOperation全体を省略するか、Interfaceを展開しない。 + +```text +interface "issue.read" { + // view: partial + operation read_body() -> { body: string }; +} +``` + +Field、parameter、caseを黙って削ったり、型を`...`へ置き換えて完全なsignatureのように見せたりしない。説明を短縮する場合は、対象の説明行の直後に`// view: documentation shortened`を置く。出力上限でblockやescapeの途中を切らず、必要ならView全体を出さずにClientの診断を返す。 + +`// view:`はrendererが生成する表示上の注記であり、Hostのdocumentationとは区別する。取得済みの公開情報についての省略だけを示し、非公開Object、Interface、Operationの存在や件数を推測して示さない。 + +## Layout + +Text ViewはUTF-8 plain textとし、ANSI color、Markdown、syntax highlightingがなくても読めるようにする。文書中のcode fenceは説明用であり、Viewそのものの一部ではない。 + +標準的なlayoutはLF、2 space indent、block間の空行とする。短いrecord、parameter list、enum / unionは1行に置ける。Documentationを持つfieldやcaseは別行に置く。改行幅や空白の違いは意味を持たず、byte単位のcanonical renderingは要求しない。 + +## 今後詰める点 + +- 名称をWIP Text Viewとするか、Object View / Signature Viewを別々の表示仕様として公開するか。 +- 名前のquoteとdocumentationの引用表記の読みやすさ。特に旧IDLの非引用`///`表記との使い分け。 +- 抜粋、未展開、説明短縮の注記をどこまで固定するか。 +- Object treeやvalue表示を別profileとして追加するか。 +- 共通rendererのgolden exampleと、Unicode・制御文字・同名Operation・大きなDescriptorに対する表示testの整備。 diff --git a/draft/unresolved-issues.md b/draft/unresolved-issues.md index 62580ce..6d7cfbb 100644 --- a/draft/unresolved-issues.md +++ b/draft/unresolved-issues.md @@ -11,7 +11,7 @@ - Interface参照をcontent-addressedにし、Descriptor digestをProtocolへ導入するか。 - Descriptor version間の互換性規則。 - 現在plain textであるDocumentationへmarkup、localization、構造化exampleを追加するか。 -- Signature Viewのfull renderingをどこまで標準化するか。 +- Object / InterfaceのAI・人間向けplain text表示。[WIP Text View（草案）](text-view.md)をたたき台に、表示サブ仕様としての表記と省略規則を詰める。 - 現在Unionで表すDomain failureへ専用declarationを追加するか。 ## 3. Protocol