mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-07-23 06:03:45 +08:00

Files

Yige 2899247128 feat: 补全 registering-services / using-services 缺失的图标 (#34 )

为两个缺 market.icon 的技能补 24×24 线性 SVG（icon: >- 折叠标量，置于 category 前，对齐仓库约定）；version 1.0.0→1.0.1。其余无图标条目为 pointer entry.json，需先扩 entry schema，另行处理。

2026-06-29 17:59:16 +08:00

6.5 KiB

Raw Blame History

name, description, version, type, risk_level, status, disable-model-invocation, tags, metadata, market

name

description

version

type

risk_level

status

disable-model-invocation

using-services Skill

L0: One-line Summary

Teach the Agent how to look up and call services from the global "Apps & Services" catalog.

L1: Overview

The "Apps & Services" catalog stores all registered HTTP/MCP services. This meta-skill is your manual for finding the right service and invoking it correctly. Each non-trivial registered service also has its own svc-<id> Skill auto-generated from its operations — prefer that when it exists; this meta-skill is the fallback for ad-hoc discovery.

When to use

The user asks you to do something that might already have a registered service (e.g. "search the product database", "send a notification")
You see svc-<id> Skill in your available skills list — activate it directly
You need to call an HTTP API and want to check if it's been registered (to benefit from governance, credential injection, and audit)

When NOT to use

The user gives you a one-off URL to fetch — use HttpRequest directly
You already have the per-service svc-<id> Skill activated — follow it instead, it's more specific

L2: How to discover and call

Step 1 — List the catalog

Fetch the registry:

tool: HttpRequest
parameters:
  url: http://127.0.0.1:<agent-service-port>/api/registry/services
  method: GET

Response shape (excerpt):

{
  "data": {
    "services": [
      {
        "id": "acme-search-api",
        "name": "Acme Search API",
        "protocol": "http",
        "endpoint": "https://api.acme.example/search",
        "tags": ["search", "products"],
        "status": "online",
        "origin": "agent",
        "reviewStatus": "approved",
        "riskLevel": "medium",
        "operations": [...]
      }
    ],
    "total": 1,
    "source": "official"
  }
}

Step 2 — Pick a candidate

Filter by tags, protocol, name. Important checks before invoking:

status === 'online' → safe to call
status === 'offline' / 'error' → tell the user the service is down, don't retry blindly
status === 'degraded' → degrade gracefully, mention it to the user
reviewStatus === 'pending' (only origin='agent') → you can only call it if registeredBy is you; otherwise ask the user to promote it
riskLevel === 'critical' → expect a human approval prompt on every call

Step 3 — Build the request (HTTP services)

If the service has operations, prefer them — they define stable contract points. Build the URL as <endpoint><operation.path>.

tool: HttpRequest
parameters:
  url: https://api.acme.example/search/v1/items?q=widget
  method: GET
  headers:
    Authorization: "Bearer ${secrets/api-keys/acme}"  # resolved at call time

If the service declares auth.secretRef, do not prompt the user for the secret value during chat. The HttpRequest tool resolves it automatically.

Step 4 — Build the request (MCP services)

MCP services aren't called via HttpRequest — they are tools exposed through the Agent's mcp_servers config:

If you haven't added the MCP service to your Agent yet, POST to http://127.0.0.1:<agent-service-port>/api/agents/<your-id>/mcp-servers with { serverId: '<service.id>', config: <connection> }
Next query, MCP discovery will auto-expose tools from the server
Call the tools by their MCP-declared names directly

Step 5 — Handle the response

2xx → parse and use
4xx → likely a client error (bad params, missing auth); fix the request, then retry once; if it still fails, report to the user
5xx → server-side problem, report status of the service back so the user knows
Service-approval rejected → response will contain "decision":"rejected"; do not retry, ask the user how to proceed

Step 6 — Don't fall through to raw URL fetching

If the catalog has a service for what you need, use it. Don't bypass governance by calling an undeclared URL directly — HttpRequest will still work, but you lose:

Approval gating for high-risk operations
Credential injection (you'd need to ask the user for keys yourself)
Audit trail and lastUsed tracking
Other Agents being able to reuse your call patterns

Failure modes

Catalog read fails: just fall back to direct HttpRequest and warn the user that governance is bypassed.
No matching service: ask the user if they want to register a new one — activate registering-services skill.
status === 'offline': report the situation, suggest checking the underlying service, don't call anyway.

6.5 KiB Raw Blame History Unescape Escape