[阶段 1] 通过 NyxID 推荐 Skill 与通用工具完成服务读取

[louis4li]

用户可见结果

父 issue：#3660。阶段 1，后续阶段在本阶段的同一契约和执行路径上扩展。

用户在 Channel 对话中提出“查询明天的日程”，系统能够读取 NyxID 服务实例的有效 skill 引用，加载精确版本的 skill，通过固定通用工具执行读取，并把结果沿现有流式链路返回。该服务即使有数百个 endpoints，也不逐个展开为 LLM tools。

实施范围

1. 在 NyxID adapter 与 Protobuf 服务实例契约中承接有效 recommended_skill_refs、名称推荐、revision 和 manifest digest；尊重实例覆盖，不自行从 catalog 补入被覆盖的 refs。
2. 首版支持 Ornn 精确引用、一个明确的服务实例、无依赖 skill 和一个读取场景。核对 Ornn 当前公开版本及摘要契约，校验 source、ID、版本和摘要；只加载主文档，不把全部附件塞入上下文。
3. 复用 operation catalog 和现有 admission/request builder。通过固定通用入口读取指定操作定义并执行读取，method/path/schema 来自权威操作契约；服务身份及操作身份不能由名称猜测。
4. 在实际 Channel 工具组合中接通本路径。试点入口不再同时加载该服务全部 endpoint tools；保持现有工具权限、凭据和流式结果机制。
5. 没权限、无效引用、未知来源、不支持的版本或依赖、摘要不符、参数错误及下游失败均应明确失败。复杂自动修正与重试留到阶段 4，不能把错误吞成成功。

Agent Key 发现接口的版本与凭据前提

NyxID #1599 于北京时间 2026-09-17 22:42:28 合并，版本标记 0.23.3，才将 GET /api/v1/keys 等库存读取接口移出禁止 API key 的路由组。此前普通 Agent Key 会返回 403: API keys cannot access this endpoint。新实现允许普通 Agent Key 读取，并按有效服务 allowlist 过滤；写接口仍不在开放范围。

该结论已核对路由、中间件、handler 和 PR 历史，但尚未使用目标 Channel 的 Agent Key 对目标部署实测。不能把本机 CLI 登录查询成功当成 Agent Key 验证通过。Relay token 仍禁止访问；scheduled-invocation 专用 key 与普通 Agent Key 不可混同；delegated token 依其现有 account:read/路由策略判断。

代码开发可先使用已核对的契约与受控 fixture；首个联调步骤、且在真实服务验收前，必须验证目标部署能力和实际调用凭据类型。命中凭据类别/版本禁用错误时，不要求扩大 service allowlist 或写权限来修复，也不借用其他主体凭据。只在同一权威主体与已有授权链支持的现有发现入口内适配；没有支持入口时明确报告该发现路径不可用，不依赖修改 NyxID 来完成 Aevatar 功能。

首版发现与加载决策

• 主查询为当前执行身份可用的 service_instance_id → effective skill refs，附服务/账号标签和必要就绪信息；不默认扫描全部公共 catalog。
• 优先复用 NyxID skill 的服务列表 CLI/API 契约。只有宿主已有可正确绑定当前身份的受约束 CLI 执行能力才使用 CLI；否则扩展现有 nyxid_service_inventory，不新开通用 shell 或复制服务发现体系。
• 遵循父 issue 的“服务 ID 查询条件与授权事实分开”：可选 service_ids 只收窄查询；同一受限普通 Agent Key 的服务范围由 NyxID 权威过滤，不在 Aevatar 重建 allowlist。sender bearer 与 registration Agent Key 不同的 Channel 路径必须核对既有授权链，不能假设列表已按调用 key 过滤。
• 字段投影和必要权限/就绪过滤由运行时完成，LLM 负责任务匹配和选择引用。不要仅凭“在列表中”或 connected=true 判断当前应用拥有服务调用权限。
• LLM 显式触发加载一个所需 skill，主文档只返回资源目录；不因选择服务批量加载所有推荐。首版不实现资源正文按需读取，但响应契约需预留明确资源身份。
• 没有推荐不等于没有权限：服务仍可出现在可用列表。首版精确加载试点需有效 refs；缺失时明确报告缺少映射或使用既有正式操作说明，不要求用户扩大授权。
• 无可用匹配时，首版给出基于证据的原因或“当前身份未发现可用连接”。不要猜测未连接/权限不足；自动连接诊断与恢复留到后续阶段。

本阶段实施顺序与契约边界

1. 确定试点与身份链：选择一个明确服务实例、一个主文档足以指导读取的已发布 Ornn skill 和一个现有 schema 校验器支持的只读 operation；记录 Channel 发现、skill 读取、执行各自的凭据来源与授权关系，不记录秘密。先用 fixture 固定外部响应，再完成目标部署只读联调。
2. 落地强类型契约与 adapter：区分服务实例、catalog 定义、skill 精确引用和 operation 身份；精确引用包括来源、ID、版本与摘要，资源目录项绑定精确引用和资源身份。调用模式沿用已有 PublishedEndpoint / AuthoredRequest 语义，本阶段仅启用前者；资源正文读取和文档请求执行在阶段 3 开放，不提前做空实现或第二套模型。
3. 接通目录与精确加载：扩展现有 inventory 和 skill loader，初始只提供必要发现/加载指引；由 LLM 选择精确引用，加载主文档与资源目录。核对 Ornn 摘要的对象与验证方法；若来源定义的是 ZIP 字节摘要，不能用主文档摘要替代。现有读取接口无法提供可验证内容时，返回明确未支持，不把服务端 hash 字符串当作已验证内容。
4. 接通统一读取与 Channel：复用权威 operation 解析、admission、参数校验及现有执行/流式观察；给出已知 operation 的按需读取入口，复杂搜索留到阶段 3。现有校验器不支持的 schema 明确拒绝，不宣称支持完整 OpenAPI，也不降级 raw proxy 绕过。移除试点路径中的 endpoint tools 默认展开，保留原有明确授权策略。
5. 完成一条闭环后验收：覆盖身份、引用、参数与输出预算的正常/拒绝路径，对比少量和数百个 operations 的固定 tool catalog；更新架构文档，运行相关构建、测试和门禁，再记录真实服务结果。

可以现在开始上述代码与测试工作，不要求先建 skill 自动生成平台，也不要求先实现阶段 3 / 4。阶段 1 必须具备基本结构化失败结果；后续只扩展选择和恢复行为。

真实服务验收仍需要两项明确证据：目标部署支持实际凭据的发现路径，以及试点服务存在可解析、可验证的有效 skill ref。本机已观察到的样本 refs 全为空，不能当作已具备试点数据；fixture 通过只证明受控闭环，不能勾选真实服务验收。如果联调条件未满足，应记录具体阻塞，同时继续可独立完成的实现和测试。

相关入口

• src/Aevatar.AI.ToolProviders.NyxId/ConnectedServices/nyxid_service_tools.proto
• src/Aevatar.AI.ToolProviders.NyxId/ConnectedServices/NyxIdServiceInstanceClient.cs
• src/Aevatar.AI.ToolProviders.NyxId/NyxIdConnectedServiceToolSource.cs
• src/Aevatar.AI.ToolProviders.NyxId/ConnectedServices/NyxIdConnectedServiceOperationTool.cs
• src/Aevatar.AI.ToolProviders.Ornn/OrnnExactRemoteSkillFetcher.cs
• src/Aevatar.AI.ToolProviders.Skills/UseSkillTool.cs
• agents/Aevatar.GAgents.NyxidChat/AgentProfiles/ChannelRuntimeToolCatalogMaterializer.cs

验收

• 从 Channel 用户请求到 skill 加载、实际 adapter 调用和流式结果形成端到端闭环，不能只测试独立 loader。
• 相同通用工具配置下，1 个与数百个 operations 的工具名称及 schema 不随 endpoint 数量增长。
• 证明请求使用正确服务实例、正确 operation 和有效参数；错误权限、引用、摘要及参数不会发出下游请求。
• 主文档加载不输出全部关联文件，输入与输出有明确大小限制。
• 查询只返回必要实例信息及推荐引用，不拉取全部 skill；当前身份无服务权限时不借用更高权限身份。
• 可选 service_ids 只能收窄结果，不能扩大授权；同一受限 Agent Key 不产生第二份权限注册表，sender/key 不同的路径有明确授权边界测试。
• 可用服务 refs 为空与权限不足是不同结果，不误导用户加权限；未知可用性不伪装为可执行。
• 不通过提高 schema 预算、开放无限制 raw proxy、静默加载最新版来通过验收。
• 更新架构文档与流程图；相关 build/test、架构和测试稳定性门禁通过。
• 记录实际验证证据；若仅完成受控集成测试，不冒充已经验证线上服务。

首版不包含

多账号自动选择、公共 skill 搜索或自动生成、复杂依赖加载、通用 operation 搜索排序、写入和自动恢复。后续能力扩展同一入口，不创建平行执行体系。