prts-terrarchive 0.2.0

package/contracts/corpus_tools_v1.schema.json

@@ -0,0 +1,1801 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://prts.chat/schemas/corpus-tools-v1.schema.json",
+  "title": "PRTS.chat local corpus tool contracts v1",
+  "description": "Packaged Agent-subproject request and response contracts for corpus_search and corpus_read over official-game-corpus-index-v1.",
+  "$defs": {
+    "intentId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+    },
+    "requestId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+    },
+    "sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": ".*\\S.*"
+    },
+    "documentUid": {
+      "type": "string",
+      "pattern": "^doc_[A-Za-z0-9_-]{16}$"
+    },
+    "identifierList": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 100,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/identifier"
+      }
+    },
+    "cursor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 65536
+    },
+    "searchPageAnchor": {
+      "description": "corpus_search 的自然标题续页锚点；必须与原搜索条件一起原样提交，且只对签发它的资料版本有效。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "data_version",
+        "resource_type",
+        "title",
+        "position"
+      ],
+      "properties": {
+        "data_version": {
+          "$ref": "#/$defs/sha256"
+        },
+        "resource_type": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "position": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10000000
+        }
+      }
+    },
+    "corpusSearchRequest": {
+      "description": "corpus_search 请求（v4 扁平参数面）：query 与各过滤数组均位于顶层；query 缺省时至少需要一个过滤条件；after 与原条件一起提交，旧 cursor 兼容路径必须单独提交。过滤值为 NFKC 归一化后的展示名。",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "query": {
+          "description": "搜索词（≤512 码点）。优先使用实体名、篇名、活动名或原句片段，不要提交整句研究问题；match_mode=regex 时仅支持线性安全子集（≤256 字符；字面量、锚点、点号、字符类、转义和固定次数 {n}）。匹配在 NFKC 归一化 + 小写后的文本上进行。",
+          "type": "string",
+          "maxLength": 2048
+        },
+        "match_mode": {
+          "type": "string",
+          "enum": [
+            "literal",
+            "regex"
+          ],
+          "default": "literal"
+        },
+        "resource_types": {
+          "description": "资料类型过滤（数组内 OR）。original_story=两款游戏的官方剧情原文；archive=终末地官方档案库；character_profile/character_voice=官方角色档案与语音；character_bundle=角色官方资料合集；character_wiki/story_wiki/knowledge=审校整理资料；其余旧类型保持兼容。",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": [
+              "story",
+              "character_profile",
+              "character_module",
+              "character_voice",
+              "character_skin",
+              "operator_record",
+              "character_bundle",
+              "character_wiki",
+              "story_wiki",
+              "character_activity_wiki",
+              "reviewed_wiki",
+              "terra_journey",
+              "entity_profile",
+              "reference",
+              "original_story",
+              "archive",
+              "knowledge",
+              "wiki",
+              "character_story",
+              "timeline"
+            ]
+          }
+        },
+        "character_names": {
+          "description": "角色展示名过滤，如“凯尔希”。",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": ".*\\S.*"
+          }
+        },
+        "story_names": {
+          "description": "剧情篇章展示名过滤；不要填写内部 story_id 或路径。",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": ".*\\S.*"
+          }
+        },
+        "activity_names": {
+          "description": "活动展示名过滤。",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": ".*\\S.*"
+          }
+        },
+        "entity_names": {
+          "description": "只返回出现指定实体的行（自动展开别名）。",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": ".*\\S.*"
+          }
+        },
+        "speakers": {
+          "description": "结构化说话人过滤，只匹配亲口台词。",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": ".*\\S.*"
+          }
+        },
+        "wiki_sections": {
+          "description": "Wiki 标签字段过滤（可与资料类型、角色、活动、query 组合）；无 query 的完整字段查询一次只能选一个值。",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": [
+              "简要介绍",
+              "相关角色",
+              "详细介绍",
+              "剧情高光",
+              "战斗表现",
+              "相关活动",
+              "trivia",
+              "角色点评",
+              "剧情总结",
+              "关键人物",
+              "角色剧情概括",
+              "所有相关的活动剧情总结",
+              "相关剧情总结",
+              "相关剧情高光",
+              "相关trivia",
+              "相关角色总结"
+            ]
+          }
+        },
+        "context_terms": {
+          "description": "要求命中附近同时出现的语境词；需要 query、speakers 或 entity_names 作为主条件。",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          }
+        },
+        "after": {
+          "description": "与原 query 和过滤条件一起原样提交上一页的 page.next_after。",
+          "$ref": "#/$defs/searchPageAnchor"
+        },
+        "cursor": {
+          "description": "下一页原样复制上一页返回的 page.next_cursor；必须单独提交。",
+          "$ref": "#/$defs/cursor"
+        }
+      },
+      "anyOf": [
+        {
+          "required": [
+            "query"
+          ]
+        },
+        {
+          "required": [
+            "resource_types"
+          ]
+        },
+        {
+          "required": [
+            "character_names"
+          ]
+        },
+        {
+          "required": [
+            "story_names"
+          ]
+        },
+        {
+          "required": [
+            "activity_names"
+          ]
+        },
+        {
+          "required": [
+            "entity_names"
+          ]
+        },
+        {
+          "required": [
+            "speakers"
+          ]
+        },
+        {
+          "required": [
+            "wiki_sections"
+          ]
+        },
+        {
+          "required": [
+            "cursor"
+          ]
+        }
+      ],
+      "allOf": [
+        {
+          "if": {
+            "required": [
+              "cursor"
+            ]
+          },
+          "then": {
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "query"
+                  ]
+                },
+                {
+                  "required": [
+                    "match_mode"
+                  ]
+                },
+                {
+                  "required": [
+                    "resource_types"
+                  ]
+                },
+                {
+                  "required": [
+                    "character_names"
+                  ]
+                },
+                {
+                  "required": [
+                    "story_names"
+                  ]
+                },
+                {
+                  "required": [
+                    "activity_names"
+                  ]
+                },
+                {
+                  "required": [
+                    "entity_names"
+                  ]
+                },
+                {
+                  "required": [
+                    "speakers"
+                  ]
+                },
+                {
+                  "required": [
+                    "wiki_sections"
+                  ]
+                },
+                {
+                  "required": [
+                    "context_terms"
+                  ]
+                },
+                {
+                  "required": [
+                    "after"
+                  ]
+                }
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "sourceRef": {
+      "type": "string",
+      "maxLength": 1024,
+      "pattern": "^(?:(?:official_game:(?:story:[^:]+|character:[^:]+:[^:]+)|client_data:(?:reviewed_wiki|terra_journey|entities|references):[0-9a-f]{24})|prts:(?:arknights|endfield):[A-Za-z0-9._:%/-]+):L[1-9][0-9]*$"
+    },
+    "documentSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "document_uid",
+        "game",
+        "resource_type",
+        "content_type",
+        "collection_name",
+        "collection_type",
+        "document_id",
+        "document_type",
+        "document_category",
+        "document_kind",
+        "display_title",
+        "collection_id",
+        "activity_id",
+        "activity_name",
+        "source_story_id",
+        "story_id",
+        "story_code",
+        "story_name",
+        "part_type",
+        "part_label",
+        "char_id",
+        "character_name",
+        "path",
+        "text_sha256",
+        "line_count",
+        "sequence_index",
+        "sequence_source",
+        "sequence_confidence",
+        "previous_document_id",
+        "next_document_id",
+        "source_ref_prefix",
+        "entity_id"
+      ],
+      "properties": {
+        "document_uid": {
+          "type": "string"
+        },
+        "game": {
+          "type": "string",
+          "enum": [
+            "arknights",
+            "endfield"
+          ]
+        },
+        "resource_type": {
+          "type": "string"
+        },
+        "content_type": {
+          "type": "string"
+        },
+        "collection_name": {
+          "type": "string"
+        },
+        "collection_type": {
+          "type": "string"
+        },
+        "document_id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "document_type": {
+          "type": "string",
+          "enum": [
+            "story",
+            "character",
+            "knowledge",
+            "entity",
+            "reference"
+          ]
+        },
+        "document_category": {
+          "type": "string"
+        },
+        "document_kind": {
+          "type": "string",
+          "enum": [
+            "story",
+            "synopsis",
+            "tutorial",
+            "character_material",
+            "official_archive",
+            "profiles",
+            "voices",
+            "wiki",
+            "terra_journey",
+            "entity_profile",
+            "reference"
+          ]
+        },
+        "display_title": {
+          "type": "string"
+        },
+        "collection_id": {
+          "type": "string"
+        },
+        "activity_id": {
+          "type": "string"
+        },
+        "activity_name": {
+          "type": "string"
+        },
+        "source_story_id": {
+          "type": "string"
+        },
+        "story_id": {
+          "type": "string"
+        },
+        "story_code": {
+          "type": "string"
+        },
+        "story_name": {
+          "type": "string"
+        },
+        "part_type": {
+          "type": "string",
+          "enum": [
+            "before",
+            "interlude",
+            "after",
+            "body",
+            "synopsis",
+            "profiles",
+            "voices"
+          ]
+        },
+        "part_label": {
+          "type": "string"
+        },
+        "char_id": {
+          "type": "string"
+        },
+        "character_name": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string"
+        },
+        "text_sha256": {
+          "$ref": "#/$defs/sha256"
+        },
+        "line_count": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "sequence_index": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "sequence_source": {
+          "type": "string"
+        },
+        "sequence_confidence": {
+          "type": "string",
+          "enum": [
+            "official",
+            "derived",
+            "source_order",
+            "catalog_order"
+          ]
+        },
+        "previous_document_id": {
+          "type": "string"
+        },
+        "next_document_id": {
+          "type": "string"
+        },
+        "source_ref_prefix": {
+          "type": "string"
+        },
+        "entity_id": {
+          "type": "string"
+        }
+      }
+    },
+    "lineEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "line_number",
+        "line_type",
+        "speaker_raw",
+        "text",
+        "source_ref"
+      ],
+      "properties": {
+        "line_number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "source_line_id": {
+          "type": "string"
+        },
+        "line_type": {
+          "type": "string",
+          "enum": [
+            "dialogue",
+            "narration",
+            "heading",
+            "knowledge",
+            "archive",
+            "voice"
+          ]
+        },
+        "speaker_raw": {
+          "type": "string"
+        },
+        "speaker_id": {
+          "type": "string"
+        },
+        "text": {
+          "type": "string"
+        },
+        "source_ref": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "audio": {
+          "type": "string"
+        },
+        "hint": {
+          "type": "string"
+        },
+        "document_title": {
+          "description": "activity/collection 模式中该行所属的自然篇章标题。",
+          "type": "string"
+        },
+        "document_id": {
+          "description": "activity/collection 执行层用于逐篇覆盖与展示卡的内部稳定 ID。",
+          "$ref": "#/$defs/identifier"
+        },
+        "document_uid": {
+          "description": "activity/collection 模式中该行所属篇章的公开同名消歧定位。",
+          "$ref": "#/$defs/documentUid"
+        },
+        "stream_position": {
+          "description": "activity/collection 合集中的一基连续位置。",
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "warning": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "pageInfo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "limit",
+        "returned",
+        "has_more",
+        "next_cursor",
+        "total",
+        "total_relation"
+      ],
+      "properties": {
+        "limit": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "returned": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "has_more": {
+          "type": "boolean"
+        },
+        "next_cursor": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/cursor"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "total": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "total_relation": {
+          "type": "string",
+          "enum": [
+            "eq",
+            "gte",
+            "unknown"
+          ]
+        }
+      }
+    },
+    "searchPageInfo": {
+      "description": "corpus_search 的扫描进度；新查询使用 next_after，旧排序分页链仅使用 next_cursor。has_more 为 false 时没有下一页。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "returned_documents",
+        "total_relation",
+        "has_more",
+        "exhausted",
+        "next_after"
+      ],
+      "properties": {
+        "returned_documents": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "total_documents": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "total_relation": {
+          "type": "string",
+          "enum": [
+            "eq",
+            "unknown"
+          ]
+        },
+        "has_more": {
+          "type": "boolean"
+        },
+        "exhausted": {
+          "type": "boolean"
+        },
+        "next_after": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/searchPageAnchor"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "next_cursor": {
+          "type": "string",
+          "description": "仅旧会话排序分页链返回；单独作为 cursor 续查。"
+        }
+      }
+    },
+    "corpusSearchOkResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "result_kind",
+        "documents",
+        "page",
+        "truncated",
+        "truncation_reasons"
+      ],
+      "properties": {
+        "result_kind": {
+          "type": "string",
+          "enum": [
+            "text_matches",
+            "structured_matches",
+            "complete_sections",
+            "documents"
+          ]
+        },
+        "documents": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "page": {
+          "$ref": "#/$defs/searchPageInfo"
+        },
+        "truncated": {
+          "type": "boolean"
+        },
+        "truncation_reasons": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "retraveler_relations": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "executionStats": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "elapsed_ms",
+        "scanned_documents",
+        "scanned_lines",
+        "returned_chars",
+        "estimated_input_tokens",
+        "truncated"
+      ],
+      "properties": {
+        "elapsed_ms": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "scanned_documents": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "scanned_lines": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "returned_chars": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "estimated_input_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "truncated": {
+          "type": "boolean"
+        },
+        "truncation_reason": {
+          "type": "string"
+        }
+      }
+    },
+    "readLocator": {
+      "description": "读取定位器：单篇文档、明日方舟活动或终末地剧情集合必须三选一。",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "source_ref"
+          ],
+          "properties": {
+            "source_ref": {
+              "description": "完整稳定行引用；around 模式的中心行直接取自这里。",
+              "$ref": "#/$defs/sourceRef"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "document_id"
+          ],
+          "properties": {
+            "document_id": {
+              "description": "稳定文档 ID；around 模式配合它使用时必须提供 center_line。",
+              "$ref": "#/$defs/identifier"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "document_uid"
+          ],
+          "properties": {
+            "document_uid": {
+              "description": "搜索结果返回的稳定短定位；可读取单篇，也可配合 activity/collection 选择所属合集。",
+              "$ref": "#/$defs/documentUid"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "display_title"
+          ],
+          "properties": {
+            "display_title": {
+              "description": "资料中的完整展示标题；资料层将直接解析，无需预先搜索。",
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        {
+          "description": "按活动通读：定位到某个活动（活动 ID 或展示名），读取该活动全部剧情原文。",
+          "type": "object",
+          "additionalProperties": false,
+          "anyOf": [
+            {
+              "required": [
+                "activity_id"
+              ]
+            },
+            {
+              "required": [
+                "activity_name"
+              ]
+            }
+          ],
+          "properties": {
+            "activity_id": {
+              "description": "活动内部 ID（如 event:main_6，即 story 文档的 collection_id）。",
+              "$ref": "#/$defs/identifier"
+            },
+            "activity_name": {
+              "description": "活动展示名，如“局部坏死”“孤星”；活动 ID 与展示名至少给一个。",
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        {
+          "description": "按终末地任务或剧情集合展示名连续读取全部官方剧情碎片。",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "collection_name"
+          ],
+          "properties": {
+            "collection_name": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      ]
+    },
+    "readSelection": {
+      "description": "读取范围：around 看锚点上下文，range 读已知行区间，section 精确读 Wiki 字段，document 分页读整篇。",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mode",
+            "section"
+          ],
+          "properties": {
+            "mode": {
+              "const": "section",
+              "description": "精确读取一篇 Wiki 中指定标签字段，不包含标签行。"
+            },
+            "section": {
+              "type": "string",
+              "enum": [
+                "简要介绍",
+                "相关角色",
+                "详细介绍",
+                "剧情高光",
+                "战斗表现",
+                "相关活动",
+                "trivia",
+                "角色点评",
+                "剧情总结",
+                "关键人物",
+                "角色剧情概括",
+                "所有相关的活动剧情总结",
+                "相关剧情总结",
+                "相关剧情高光",
+                "相关trivia",
+                "相关角色总结"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mode"
+          ],
+          "properties": {
+            "mode": {
+              "const": "around",
+              "description": "读取中心行前后的上下文。"
+            },
+            "center_line": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "仅 locator 使用 document_id 时必填；locator 使用 source_ref 时省略。"
+            },
+            "before_lines": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100,
+              "default": 3
+            },
+            "after_lines": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100,
+              "default": 3
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mode",
+            "start_line",
+            "end_line"
+          ],
+          "properties": {
+            "mode": {
+              "const": "range",
+              "description": "读取包含起止行的闭区间。"
+            },
+            "start_line": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "end_line": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mode"
+          ],
+          "properties": {
+            "mode": {
+              "const": "document",
+              "description": "分页读取整篇文档。"
+            },
+            "cursor": {
+              "description": "下一页使用上一页响应的 next_cursor；首次省略。",
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/cursor"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null
+            },
+            "start_line": {
+              "description": "公开自然续页定位器换算出的篇内起始行；与 cursor 不同时使用。",
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mode"
+          ],
+          "properties": {
+            "mode": {
+              "const": "activity",
+              "description": "按活动通读：配合 activity locator，按篇章顺序读取该活动全部剧情原文，跨多篇文档分页。"
+            },
+            "cursor": {
+              "description": "下一页使用上一页响应的 next_cursor；首次省略。",
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/cursor"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null
+            },
+            "start_position": {
+              "description": "公开自然续页定位器换算出的活动连续位置；与 cursor 不同时使用。",
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mode"
+          ],
+          "properties": {
+            "mode": {
+              "const": "collection",
+              "description": "按终末地任务/剧情集合的资料顺序跨文档连续读取。"
+            },
+            "cursor": {
+              "description": "旧客户端下一页游标；Agent 使用 start_position。",
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/cursor"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null
+            },
+            "start_position": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "content_types": {
+              "type": "array",
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "enum": [
+                  "dialogue",
+                  "cutscene",
+                  "radio",
+                  "remote_comm",
+                  "black_screen",
+                  "environment_talk",
+                  "sns_topic",
+                  "sns_chat",
+                  "narration"
+                ]
+              }
+            }
+          }
+        }
+      ]
+    },
+    "readLimits": {
+      "description": "单次本地读取的行数和字符硬上限；大范围请求可能触发用户审批。",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_lines": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 500,
+          "default": 100
+        },
+        "max_chars": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 100000,
+          "default": 12000
+        }
+      }
+    },
+    "corpusReadRequest": {
+      "description": "读取本地资料正文并获得可引用的逐行 source_ref。搜索预览或云端候选不能替代本工具的原文核验。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "intent_id",
+        "locator",
+        "selection"
+      ],
+      "properties": {
+        "intent_id": {
+          "description": "当前用户检索意图的稳定 ID，由运行时注入。",
+          "$ref": "#/$defs/intentId"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        },
+        "expected_data_version": {
+          "$ref": "#/$defs/sha256"
+        },
+        "locator": {
+          "description": "定位单篇文档、明日方舟活动或终末地剧情集合。",
+          "$ref": "#/$defs/readLocator"
+        },
+        "selection": {
+          "description": "选择 around、range、section、document、activity 或 collection 读取方式。",
+          "$ref": "#/$defs/readSelection"
+        },
+        "format": {
+          "description": "lines 保留每行 source_ref 并可引用；plain_text 仅适合连续阅读。",
+          "type": "string",
+          "enum": [
+            "lines",
+            "plain_text"
+          ],
+          "default": "lines"
+        },
+        "include_adjacent_documents": {
+          "type": "boolean",
+          "default": true
+        },
+        "limits": {
+          "$ref": "#/$defs/readLimits"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "locator": {
+                "anyOf": [
+                  { "required": ["document_id"] },
+                  { "required": ["document_uid"] }
+                ]
+              },
+              "selection": {
+                "properties": {
+                  "mode": {
+                    "const": "around"
+                  }
+                },
+                "required": [
+                  "mode"
+                ]
+              }
+            },
+            "required": [
+              "locator",
+              "selection"
+            ]
+          },
+          "then": {
+            "properties": {
+              "selection": {
+                "required": [
+                  "center_line"
+                ]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "locator": {
+                "required": [
+                  "source_ref"
+                ]
+              },
+              "selection": {
+                "properties": {
+                  "mode": {
+                    "const": "around"
+                  }
+                },
+                "required": [
+                  "mode"
+                ]
+              }
+            },
+            "required": [
+              "locator",
+              "selection"
+            ]
+          },
+          "then": {
+            "properties": {
+              "selection": {
+                "not": {
+                  "required": [
+                    "center_line"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "actualSelection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "line_start",
+        "line_end",
+        "line_count",
+        "character_count",
+        "truncated"
+      ],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "around",
+            "range",
+            "section",
+            "document",
+            "activity",
+            "collection"
+          ]
+        },
+        "line_start": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "line_end": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "line_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "character_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "truncated": {
+          "type": "boolean"
+        },
+        "truncation_reason": {
+          "type": "string"
+        },
+        "wiki_section": {
+          "description": "section 模式实际读取的 Wiki 字段名。",
+          "type": "string"
+        }
+      }
+    },
+    "linesContent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "format",
+        "lines"
+      ],
+      "properties": {
+        "format": {
+          "const": "lines"
+        },
+        "lines": {
+          "type": "array",
+          "maxItems": 500,
+          "items": {
+            "$ref": "#/$defs/lineEntry"
+          }
+        }
+      }
+    },
+    "plainTextContent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "format",
+        "text"
+      ],
+      "properties": {
+        "format": {
+          "const": "plain_text"
+        },
+        "text": {
+          "type": "string",
+          "maxLength": 100000
+        }
+      }
+    },
+    "corpusReadOkResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "contract_version",
+        "status",
+        "request_id",
+        "data_version",
+        "package_schema_version",
+        "index_schema_version",
+        "normalized_request",
+        "document",
+        "selection",
+        "content",
+        "page",
+        "integrity",
+        "stats",
+        "warnings"
+      ],
+      "properties": {
+        "contract_version": {
+          "const": "prts-corpus-tools-v1"
+        },
+        "status": {
+          "const": "ok"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        },
+        "data_version": {
+          "$ref": "#/$defs/sha256"
+        },
+        "package_schema_version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "index_schema_version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "normalized_request": {
+          "$ref": "#/$defs/corpusReadRequest"
+        },
+        "document": {
+          "$ref": "#/$defs/documentSummary"
+        },
+        "selection": {
+          "$ref": "#/$defs/actualSelection"
+        },
+        "content": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/linesContent"
+            },
+            {
+              "$ref": "#/$defs/plainTextContent"
+            }
+          ]
+        },
+        "page": {
+          "$ref": "#/$defs/pageInfo"
+        },
+        "activity": {
+          "description": "仅 activity 模式返回：当前读取活动的汇总。",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "activity_id",
+            "activity_name",
+            "story_count",
+            "total_lines"
+          ],
+          "properties": {
+            "activity_id": {
+              "type": "string"
+            },
+            "activity_name": {
+              "type": "string"
+            },
+            "story_count": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "total_lines": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "stream": {
+          "description": "仅 activity/collection 模式返回的自然连续位置信息。",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mode",
+            "game",
+            "name",
+            "document_count",
+            "total_lines",
+            "position_start",
+            "position_end",
+            "next_position",
+            "order_kind",
+            "order_confidence",
+            "order_note",
+            "anchor_document_uid",
+            "sources"
+          ],
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "activity",
+                "collection"
+              ]
+            },
+            "game": {
+              "type": "string",
+              "enum": [
+                "arknights",
+                "endfield"
+              ]
+            },
+            "name": {
+              "type": "string"
+            },
+            "document_count": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "total_lines": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "position_start": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "position_end": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "next_position": {
+              "oneOf": [
+                {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "order_kind": {
+              "type": "string",
+              "enum": ["source_sequence", "derived_content_grouping"]
+            },
+            "order_confidence": {
+              "type": "string",
+              "enum": ["source_backed", "derived"]
+            },
+            "order_note": {
+              "type": "string"
+            },
+            "anchor_document_uid": {
+              "$ref": "#/$defs/documentUid"
+            },
+            "sources": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["document_id", "document_uid", "title", "line_start", "line_end"],
+                "properties": {
+                  "document_id": { "$ref": "#/$defs/identifier" },
+                  "document_uid": { "$ref": "#/$defs/documentUid" },
+                  "title": { "type": "string" },
+                  "line_start": { "type": "integer", "minimum": 1 },
+                  "line_end": { "type": "integer", "minimum": 1 }
+                }
+              }
+            },
+            "content_types": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "adjacent_documents": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "previous": {
+              "oneOf": [
+                {
+                  "$ref": "#/$defs/documentSummary"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "next": {
+              "oneOf": [
+                {
+                  "$ref": "#/$defs/documentSummary"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          }
+        },
+        "integrity": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "verified",
+            "expected_text_sha256",
+            "actual_text_sha256"
+          ],
+          "properties": {
+            "verified": {
+              "type": "boolean"
+            },
+            "expected_text_sha256": {
+              "$ref": "#/$defs/sha256"
+            },
+            "actual_text_sha256": {
+              "$ref": "#/$defs/sha256"
+            }
+          }
+        },
+        "stats": {
+          "$ref": "#/$defs/executionStats"
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/warning"
+          }
+        }
+      }
+    },
+    "approvalRequiredResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "contract_version",
+        "status",
+        "request_id",
+        "data_version",
+        "normalized_request",
+        "approval"
+      ],
+      "properties": {
+        "contract_version": {
+          "const": "prts-corpus-tools-v1"
+        },
+        "status": {
+          "const": "approval_required"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        },
+        "data_version": {
+          "$ref": "#/$defs/sha256"
+        },
+        "normalized_request": {
+          "$ref": "#/$defs/corpusReadRequest"
+        },
+        "approval": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "approval_request_id",
+            "request_sha256",
+            "reason",
+            "requested_documents",
+            "requested_lines",
+            "requested_characters",
+            "intent_cumulative_characters",
+            "estimated_input_tokens",
+            "estimated_cost",
+            "allowed_actions"
+          ],
+          "properties": {
+            "approval_request_id": {
+              "$ref": "#/$defs/requestId"
+            },
+            "request_sha256": {
+              "$ref": "#/$defs/sha256"
+            },
+            "reason": {
+              "type": "string",
+              "enum": [
+                "raw_text_count",
+                "raw_text_characters",
+                "estimated_input_tokens",
+                "estimated_cost"
+              ]
+            },
+            "requested_documents": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "requested_lines": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "requested_characters": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "intent_cumulative_characters": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "intent_cumulative_records": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "intent_cumulative_lines": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "intent_cumulative_tokens": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "estimated_input_tokens": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "estimated_cost": {
+              "type": [
+                "number",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "currency": {
+              "type": "string"
+            },
+            "allowed_actions": {
+              "type": "array",
+              "minItems": 3,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "enum": [
+                  "approve_once",
+                  "increase_intent_budget",
+                  "reject"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "toolError": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "code",
+        "message",
+        "retryable"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "enum": [
+            "INVALID_REQUEST",
+            "PACKAGE_NOT_INSTALLED",
+            "PACKAGE_VERSION_MISMATCH",
+            "INDEX_UNAVAILABLE",
+            "INDEX_CORRUPT",
+            "DOCUMENT_NOT_FOUND",
+            "SOURCE_REF_INVALID",
+            "LINE_RANGE_INVALID",
+            "CURSOR_INVALID",
+            "CURSOR_VERSION_MISMATCH",
+            "CURSOR_POLICY_MISMATCH",
+            "PAGE_ANCHOR_INVALID",
+            "PAGE_ANCHOR_MISMATCH",
+            "PAGE_ANCHOR_NOT_FOUND",
+            "PAGE_ANCHOR_VERSION_MISMATCH",
+            "REGEX_REJECTED",
+            "TIMEOUT",
+            "BUDGET_EXCEEDED",
+            "CANCELLED",
+            "INTERNAL_ERROR"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "retryable": {
+          "type": "boolean"
+        },
+        "details": {
+          "type": "object"
+        }
+      }
+    },
+    "errorResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "contract_version",
+        "status",
+        "request_id",
+        "data_version",
+        "error"
+      ],
+      "properties": {
+        "contract_version": {
+          "const": "prts-corpus-tools-v1"
+        },
+        "status": {
+          "const": "error"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        },
+        "data_version": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/sha256"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "error": {
+          "$ref": "#/$defs/toolError"
+        }
+      }
+    },
+    "corpusSearchResponse": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/corpusSearchOkResponse"
+        },
+        {
+          "$ref": "#/$defs/errorResponse"
+        }
+      ]
+    },
+    "corpusReadResponse": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/corpusReadOkResponse"
+        },
+        {
+          "$ref": "#/$defs/approvalRequiredResponse"
+        },
+        {
+          "$ref": "#/$defs/errorResponse"
+        }
+      ]
+    }
+  }
+}