fix: simplify text view descriptions and expansion
This commit is contained in:
+7
-31
@@ -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>" { ... }`と表示する。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 "<reference>" { ... }`と表示する。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は対象の直前に`/// "<summary>"`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Object descriptionも同じ表記を使用するが、DescriptorのDocumentationへ変換するわけではない。
|
||||
Documentationは対象の直前に`/// "<summary>"`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Objectの説明はこの表記ではなく、Object Viewの`description` propertyで表示する。
|
||||
|
||||
通常表示では`summary`だけを使い、明示的な詳細表示では同じ対象のsummary行に続けて`/// details "<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の整備。
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user