Skip to content

[MCP Sink] 支持从零开始发现 InKCre 类型、资源与数据 #185

New issue
New issue
Closed
Feature
#189
Closed
[MCP Sink] 支持从零开始发现 InKCre 类型、资源与数据#185
Feature
#189
Assignees
xiaoland

Description

@xiaoland
xiaoland
opened on Nov 10, 2026

背景

当前 MCP Sink 的读取入口大多要求调用者预先知道 Block ID、Resolver ID 或其它资源 ID。对于一个刚接入 InKCre、对当前 Info-base 和运行环境一无所知的 Agent，缺少一个可靠的起点。

例如，Agent 可能需要先了解当前有哪些 Resolver、Source type、Storage type，以及已经配置了哪些 Source / Storage instances；随后才能选择某一类数据继续探索。即使已经知道某个 Resolver ID，目前也没有通用方式枚举使用它的 Blocks。

相关实现：

需要解决的问题

为 Agent 提供从零开始、逐步深入的发现能力：先了解当前有哪些类型和资源，再根据发现结果定位具体实例或数据实体，并继续使用现有读取能力。

首批需要考虑的发现对象包括：

  • Resolver IDs：当前运行环境注册了哪些 Resolver，以及它们提供什么基本能力。
  • Source types / instances：有哪些 Source 类型，以及当前有哪些已配置的 Source 实例。
  • Storage types / instances：有哪些 Storage 类型，以及当前有哪些已配置的 Storage 实例（包括可供后续操作使用的 Storage ID）。
  • Blocks：能够根据已知 Resolver ID 发现使用该 Resolver 的 Blocks，而不要求事先知道 Block ID。

这里需要区分 type catalog、当前 Peer 实际加载/可执行的实现、已配置的 instance，以及 Block 上持久化的 resolver 值。它们不是同一件事；例如历史 Block 可能仍使用当前 Peer 未注册的 Resolver ID。

这不是要求一次性导出整个 Info-base，也不是建设一个任意数据库查询接口。目标是让 Agent 能够通过有限、可组合的发现步骤逐渐建立对当前环境的认识。

预期结果

  • Agent 在没有预先掌握任何 ID 的情况下，可以发现有用的 Resolver、Source、Storage 类型和已配置实例。
  • Agent 可以从发现的 Resolver ID 继续定位相应 Blocks，并通过现有实体读取和 Resolver method 能力深入查看。
  • 发现结果提供足够的标识和安全的描述信息，帮助 Agent 决定下一步；不需要在发现阶段读取完整内容。
  • 不同目录和实例的可用性边界清楚，不把“目录中存在”误解为“当前 Peer 一定能执行”。
  • 发现过程有界、可分页、只读，不意外暴露凭据或配置秘密，也不触发昂贵的内容解析、外部资源读取或数据写入。
  • 该能力面向 InKCre 的通用信息与运行资源，不为 Twitter 或任何单一 Extension 添加特例。

验收标准

  • Agent 能从零开始发现当前可用的 Resolver IDs、Source types 和 Storage types。
  • Agent 能发现已配置的 Source / Storage instances 及其可安全公开的基本信息和 ID。
  • Agent 能根据 Resolver ID 发现对应 Blocks，并继续使用现有 MCP Tools 读取。
  • 类型目录、运行时实现和已持久化数据之间的差异不会被隐藏或混淆。
  • 大型结果集支持有界、可继续的分页发现。
  • 发现过程不会暴露 credentials、敏感 config/state，不修改数据，也不隐式触发内容 materialization 或外部网络读取。
  • 测试覆盖空目录、多个类型/实例、分页，以及历史 Block 使用当前未注册 Resolver 的情况。

参考

Activity

  1. xiaoland
    changed the title [-][MCP Sink] 增加按 Resolver 分页枚举 Block 的只读发现能力[/-] [+][MCP Sink] 支持按 Resolver 发现和分页读取 Blocks[/+] on Nov 10, 2026
  2. xiaoland
    changed the title [-][MCP Sink] 支持按 Resolver 发现和分页读取 Blocks[/-] [+][MCP Sink] 支持从零开始发现 InKCre 类型、资源与数据[/+] on Nov 10, 2026
  3. xiaoland
    added the
    Feature
    issue type on Nov 10, 2026

  4. xiaoland commented on Nov 10, 2026

    @xiaoland
    xiaoland
    on Nov 10, 2026
    MemberAuthor

    @braid 请按本 Issue 的验收标准实际完成设计、实现和必要验证，并创建关联 #185 的 PR。请先核对仓库 AGENTS.md、现有 MCP Sink 契约与相关类型/实例/Block 数据路径。若遇到会改变产品范围的决策，请在此 Issue 说明具体分歧与依据。

  5. xiaoland commented on Nov 10, 2026

    @xiaoland
    xiaoland
    on Nov 10, 2026
    MemberAuthor

    @braid 网络已恢复，请开始执行上条实现指令，完成 #185 并创建 PR。

  6. braid-of-inkcre commented on Nov 10, 2026

    @braid-of-inkcre
    braid-of-inkcreBot
    on Nov 10, 2026
    Contributor

    Braid Agent · Braid issue (impl-py)
    Issue Agent

    已完成设计、实现及本地验证，关联 Draft PR：#189（提交 e087bde）。新增分页 inkcre_discover，明确本地实现/持久目录/实例/历史 Resolver 的区别，发现不读取配置秘密或内容、不触发解析或外部读取。pdm run check 通过；真实 MCP/PostgreSQL 集成与迁移相关检查为 12 passed、6 skipped（缺本机 PostgreSQL binaries）；新增迁移往返及 mounted HTTP/PAT 探测通过。详细证据和索引部署维护窗口风险已记录在 PR，等待 required checks 与审阅。

  7. xiaoland commented on Nov 11, 2026

    @xiaoland
    xiaoland
    on Nov 11, 2026 – with ChatGPT Codex Connector
    MemberAuthor

    MCP Tool 命名与 namespace

    建议统一调整全部 MCP Tool 名称，移除 inkcre_ 前缀。

    MCP Server 本身已经标识为 InKCre；Tool 名称应描述 Agent 可以执行的动作，而不是再次编码所属 Server。跨 Server 的 namespace / collision 处理交给 MCP Client。

    因此，这不是只把新增 Tool 改成 meta_discover，而是统一调整整个现有 Tool surface：

    • recall（后续拟调整为 query）
    • open_entities
    • read_blocks
    • expand_entities
    • find_path
    • resolver_methods
    • invoke_resolver_methods
    • meta_discover

    目前这套接口尚未合并，建议直接采用统一的新名称，不额外保留旧名称 alias。

  8. xiaoland commented on Nov 11, 2026

    @xiaoland
    xiaoland
    on Nov 11, 2026 – with ChatGPT Codex Connector
    MemberAuthor

    meta_discover 的职责与发现范围

    建议将新增 Tool 命名为 meta_discover，并重新收敛其 collection。它的职责是向 Agent 提供构造后续 InKCre 查询所需的类型与标识信息，不是一个通用的实例详情读取 API，也不应把删减字段后的实例对象包装成所谓的“安全描述信息”。

    建议保留：

    • resolvers：当前 Peer registry 中的 Resolver identities。
    • source_types：Source 类型目录。
    • storage_types：Storage 类型目录。
    • storages：Storage 实例的可查询标识。Storage ID 是后续按 storage.eq 查询 Blocks 的前置知识，因此 Storage 实例标识本身属于 Agent 需要发现的 meta。

    这里需要特别区分 Resolver catalog 与 Resolver behavior capability：暴露 Resolver IDs 并不决定或授予 Agent 可以使用哪些 Resolver 行为。具体行为仍由既有的 resolver_methods / invoke_resolver_methods 发现与调用；meta_discover(resolvers) 只是提供当前 Peer 的 Resolver identity 信息，不应被描述成 capability 授权入口。历史 Block 上的 Resolver ID 也不因此自动进入当前 Peer 的 Resolver catalog。

    当前 MVP 暂不需要 sources 实例 collection；保留 source_types 即可。与此同时，blocks collection 应由下述 query 的精确过滤能力取代，避免同时维护两套 Block 枚举入口。

    Storage 实例在这里的角色是提供可用于查询的 Storage identity，而不是展示一个被删减字段的 StorageModel。具体返回字段应围绕 Agent 识别和使用 Storage ID 的需要定义，不应把它扩展成配置/状态读取接口。

  9. xiaoland commented on Nov 11, 2026

    @xiaoland
    xiaoland
    on Nov 11, 2026 – with ChatGPT Codex Connector
    MemberAuthor

    将 recall 收敛为 query：支持文本检索与精确条件查询

    建议将现有 recall Tool 重命名为 query。当前 Tool 只表达 lexical / semantic relevance retrieval；但新增需求已经包括按 Block 的结构化字段定位数据，query 更准确地覆盖这两种使用方式。

    至少支持以下精确过滤条件：

    {
  "query": "SQLite database architecture",
  "modes": ["lexical", "semantic"],
  "filters": {
    "resolver": { "eq": "core.text.v1" },
    "storage": { "eq": 10 }
  },
  "limit": 20
}

    语义约束：

    • resolver.eq 对应 Block 的 exact Resolver ID。
    • storage.eq 对应 Block 的 Storage instance ID，而不是 Storage type。
    • 多个过滤条件按 AND 组合。
    • 过滤必须在数据库候选选择阶段执行，并先于 lexical / semantic ranking 和 top-k limit；不能先取全局 Top-K 再在 MCP 层过滤。
    • 这些字段属于 Block。使用任一 Block-specific filter 时，结果应只包含满足条件的 Blocks，不应混入没有相应字段语义的 Relations。
    • 已知但当前 Peer 未注册的历史 Resolver ID 仍然可以作为 resolver.eq 查询值；是否能调用它的 Resolver methods 是另一项独立判断。

    另外，既然 Tool 名称是 query，建议支持不带文本 query、仅带一个或多个精确条件的查询。否则 Agent 虽然从 meta_discover 获得了 Storage ID，却仍然不能仅凭该 ID 找到对应 Blocks。纯条件查询应有界，并使用确定的排序和可继续分页；它不应伪造 lexical / semantic relevance score。

    文本检索与纯条件查询可以共享一个 Agent-facing query surface，但两种模式的排序语义必须明确区分。

  10. xiaoland commented on Nov 11, 2026

    @xiaoland
    xiaoland
    on Nov 11, 2026 – with ChatGPT Codex Connector
    MemberAuthor

    更新端到端验收：meta discovery → query → open → read

    产品验收不应停留在单独调用 meta_discover 并检查 JSON。需要证明 Agent 能把发现结果实际用于后续查询和读取。

    建议在本 Issue 的验收标准中加入一条完整 Journey：

    1. 使用独立 MCP Client，通过真实挂载的 Streamable HTTP endpoint 和有效 PAT 连接 Core；执行 initialize / tools/list，确认统一命名后的 Tool surface。
    2. 调用 meta_discover，获得 Resolver、Source type、Storage type，以及可供查询使用的 Storage IDs。
    3. 使用发现到的 Storage ID 构造 query(filters.storage.eq=...)；同时验证 resolver.eq、多条件 AND 和纯条件查询。
    4. 对结果进行分页，确认 cursor 能经由真实 MCP 请求往返，并且不同页无重复。
    5. 将返回的 block:<id> 直接交给 open_entities，再交给 read_blocks，确认读到预先准备的真实内容。
    6. 对一个当前 Peer 未注册、但已知其历史 ID 的 Resolver 执行 resolver.eq 查询，确认仍能找到历史 Blocks；不要把它错误地当作当前 Resolver capability。

    自动化验收应使用 disposable PostgreSQL、正常 Core / Sink lifecycle、真实挂载的 HTTP transport 和独立 MCP Client。现有 Client(server, mode="legacy") 进程内直连测试可以保留为较低层测试，但不能单独作为这条产品 E2E 的证据。测试 corpus 应尽可能通过正常 producer / Manager 路径建立，而不是让直接 SQL fixture 插入成为唯一的产品旅程。

    ChatGPT Developer Mode / Secure MCP Tunnel 的真实产品体验仍作为独立手动验收；不需要把模型是否选择某个 Tool 写成脆弱的自动化断言。

  11. braid-of-inkcre commented on Nov 11, 2026

    @braid-of-inkcre
    braid-of-inkcreBot
    on Nov 11, 2026
    Contributor

    Braid Agent · Braid issue (impl-py)
    Issue Agent

    采纳这四条修订；已核对当前 PR 并完成独立设计咨询。以下作为 #185 当前 MVP 验收基线，替代正文中 Source instances、独立 Block 枚举及旧工具名称的对应要求；现有 PR 还需按此修改，之前的通过记录不代表新验收已通过。

    接口与范围

    • 最终八个工具：meta_discover、query、open_entities、read_blocks、expand_entities、find_path、resolver_methods、invoke_resolver_methods。不保留旧名称 alias；不顺带改 Sink type、endpoint 或 Resource URI。
    • meta_discover 仅保留 resolvers/source_types/storage_types/storages。Resolver identities 只来自当前 Peer registry，不由历史 Block 值补齐，也不授予行为能力。行为继续通过两个 Resolver method 工具发现/调用。
    • Storage identity 以 id 为查询键，type 用于辨别类型，nullable、有界且非唯一的 nickname 用于辨认；不扩展为实例详情读取。目录中的本地注册标记不代表运行状态、健康或执行保证。不读取 config/state/schema/URL 等配置内容。

    query 的两个分支

    • 文本分支：保持显式非空 modes、mode-local evidence/排序；可加 exact filters，不新增跨模式融合分数或文本结果 cursor。
    • 纯条件分支：无有效文本时必须至少一个实际 filter，不接受检索 modes；由 info-base 直接查询 Block 行，不调用检索/embedding/Resolver。按 id ASC 有界 keyset 分页，不伪造 relevance score/rank，也不依赖索引记录已存在。
    • resolver.eq 为 exact ID，未知历史 ID 也合法；storage.eq 为严格 INTEGER 范围内的实例 ID，允许负数，不接受 bool/字符串/null。本次不增加 inline-storage null 筛选或其他查询运算符。多个条件 AND，未知字段/运算符明确拒绝。
    • lexical/semantic owners 在各自数据库候选查询内对 Block 字段加 WHERE，先于 ranking/top-K；任何 Block filter 都将结果域限制为 Blocks，不在返回后丢弃 Relations 或做 oversampling 补救。检查 SDK/route 转发点，不静默丢过滤条件，也不顺带重设计 Peer 协议。
    • cursor 绑定版本、工具/纯条件分支、完整有效 filters、排序及最后 ID；改条件或跨 meta/query 使用要报错。分页为 live traversal，不承诺快照；评估 storage-only seek 的索引需求。

    新增验收 Journey

    • disposable PostgreSQL + 正常 Core/SinkManager 创建/启停 + 独立 MCP Client，经实际挂载的 Streamable HTTP endpoint/PAT 执行 initialize/tools/list，确认且仅有上述八个名称。
    • 通过正常 producer/graph Manager 建立语料，完成四类 meta → 发现的 Storage ID → storage/resolver/AND 纯条件 query → 跨 HTTP 分页且页间无重复 → open_entities → read_blocks，读到预置真实内容；并验证已知历史 Resolver 不在 catalog 但可查询。
    • 文本检索为 lexical、semantic 分别准备“排名更高但不匹配的候选超过 K”的对抗语料，以及高分 Relation，断言仍返回预期匹配 Block 的 ID/数量，证明不是 post-top-K 过滤；可使用确定性测试 provider，不以 mock retrieval Manager 或直接 SQL 索引造数替代旅程。
    • 保留 metadata 不加载敏感列、不构造 handler 的证明，并覆盖无/错 PAT 与 Sink 关闭清理。进程内 legacy 测试仅作低层证据；新 E2E 被 skip 不算验收完成。

    ChatGPT Developer Mode / Secure MCP Tunnel 仍独立手动验收。后续实现由现有 #189 PR Agent 单写执行，Issue 侧不另开竞争实现分支。

  12. xiaoland
    closed this as completedin #189on Nov 12, 2026

  13. braid-of-inkcre commented on Nov 12, 2026

    @braid-of-inkcre
    braid-of-inkcreBot
    on Nov 12, 2026
    Contributor

    Braid Agent · Braid issue (impl-py)
    Issue Agent

    收口：#189 已合并（9f75cbb）。最终交付为八个无前缀工具、四类 meta_discover，以及支持 resolver/storage 精确 AND 过滤与纯条件分页的 query。真实 HTTP/PAT 的 meta → query → open → read 和生命周期旅程已纳入自动化；最终 HEAD 的 checks/E2E/CLI 检查通过，详细证据见 #189 (comment) 。ChatGPT/Secure MCP Tunnel 的手动体验验收未执行，不将合并等同于生产验收；大库索引构建仍需维护窗口。本 Issue 按当前 completed 状态收口，不再启动实现。

  14. xiaoland
    self-assigned this
    on Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Feature

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions