diff --git a/draft/text-view.md b/draft/text-view.md index 0cdcefc..45847cb 100644 --- a/draft/text-view.md +++ b/draft/text-view.md @@ -27,6 +27,8 @@ Rendererが利用するのは、Clientが既に保持する次の情報である Interface単独の表示も可能とする。その場合は、取得時のInterface参照とDescriptorを使用する。Interface参照はDescriptor自身のfieldではない。 +Interfaceを展開するか、どのInterfaceを表示するかは呼び出し側が選択する。展開しないInterfaceもObjectの`interfaces`に参照が示されるため、未展開の注記は追加しない。選択したInterfaceは全宣言を表示し、表示側での折りたたみ、抜粋、budgetによる省略は行わない。 + 表示は観測時点の公開情報であり、最新状態、Operationの実行権限、実行成功を保証しない。再観測やDescriptor取得のタイミングはClient policyのままとし、表示形式から暗黙のnetwork取得を要求しない。 この草案の対象はObjectの概要とInterfaceの宣言である。Object tree全体の描画、Operation arguments / resultのvalue表示、Protocol errorや診断metadataの表示は対象に含めない。 @@ -38,7 +40,7 @@ Interface単独の表示も可能とする。その場合は、取得時のInter ```text object at "/issues/123" { name: "123"; - /// "Issue 123の公開操作。本文はOperationで取得する。" + description: "Issue 123の公開操作。本文はOperationで取得する。"; interfaces: ["issue.read", "issue.lifecycle"]; } @@ -81,7 +83,7 @@ ObjectとInterfaceは別blockにする。Object blockはInterface参照を示し Objectは`object at "" { ... }`と表示する。Pathが分からない場合は`object { ... }`とし、`name`や`ref`からpathを推測しない。 - `name: "...";`にObjectの`name`をそのまま表示する。自由なtitleへ置き換えない。 -- `description`がある場合は`name`の後に`/// "..."`で表示する。これはObject全体の説明である。 +- `description`がある場合は`name`の後に`description: "...";`で表示する。Object全体の説明を通常のpropertyとして示す。 - `interfaces: ["...", "..."];`に全Interface参照をHostの立項順で表示する。空集合は`interfaces: [];`と明示する。 - `ref`とvalidatorは通常表示へ含めない。同一性管理と条件付き実行はClient runtimeの責務のままである。 - Objectの本文やdomain metadataを推測してpropertyとして追加しない。 @@ -96,7 +98,7 @@ Interfaceは`interface "" { ... }`と表示する。Objectと併記 Block内では、Descriptorの`types`を宣言順に、続いて`operations`を宣言順に表示する。Record field、parameter、enum / union caseも元の順序を保持する。この順序は表示上の規則であり、Protocol上の名前解決やvalidationを変更しない。 -同名Operationが異なるInterfaceにある場合も、それぞれのblock内に表示する。BlockのInterface参照が出所を示すため、Operation名を改名したり、参照をOperation名へ連結したりしない。単独のOperation抜粋でもInterface blockを残す。 +同名Operationが異なるInterfaceにある場合も、それぞれのblock内に表示する。BlockのInterface参照が出所を示すため、Operation名を改名したり、参照をOperation名へ連結したりしない。 ### 型の表記 @@ -144,7 +146,7 @@ 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`とする。 +- 表示keywordは`object`、`at`、`name`、`description`、`interfaces`、`interface`、`type`、`operation`、`enum`、`union`、および`unit`、`boolean`、`integer`、`number`、`string`、`bytes`、`json`、`entry`とする。 ```text interface "example" { @@ -159,7 +161,7 @@ interface "example" { ## Documentation -Documentationは対象の直前に`/// ""`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Object descriptionも同じ表記を使用するが、DescriptorのDocumentationへ変換するわけではない。 +Documentationは対象の直前に`/// ""`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Objectの説明はこの表記ではなく、Object Viewの`description` propertyで表示する。 通常表示では`summary`だけを使い、明示的な詳細表示では同じ対象のsummary行に続けて`/// details "
"`を追加する。Documentationがない対象へ説明を生成しない。Empty stringとfieldの欠落は区別し、存在する空文字列は`""`として表示する。 @@ -178,31 +180,6 @@ operation search( 説明はすべて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そのものの一部ではない。 @@ -213,6 +190,5 @@ Text ViewはUTF-8 plain textとし、ANSI color、Markdown、syntax highlighting - 名称を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 6d7cfbb..4594af7 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を追加するか。 -- Object / InterfaceのAI・人間向けplain text表示。[WIP Text View(草案)](text-view.md)をたたき台に、表示サブ仕様としての表記と省略規則を詰める。 +- Object / InterfaceのAI・人間向けplain text表示。[WIP Text View(草案)](text-view.md)をたたき台に、表示サブ仕様としての表記を詰める。 - 現在Unionで表すDomain failureへ専用declarationを追加するか。 ## 3. Protocol