mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-10-22 06:13:42 +08:00

Files

Yige 8f7953948f fix: 补齐市场静态事实并保持旧客户端兼容 (#184 )

## 中文

补齐已有 owner 与已锁定上游内容可证明的许可证、技能类型和收录版本。保留 Anthropic Source Available
和其他附加条件，不把所有内容统一标为 MIT，不提升 listing-only 的安装准入。

README 保留最新的双语结构及以 manifest 为准的数量口径，增加静态目录不存访问量、下载量、评分或 Stars 的边界。

发布兼容性：**本 PR 不包含**两支团队新增的本地化字段，也不包含微信支付 `latestVersion:
1.0`；旧客户端会拒绝这些新字段，另以待发布 PR 保留，等匹配客户端发布后再合并。

验证：47 项目录校验测试、19 项 i18n 测试、5 项合集生成测试通过；完整目录/i18n/翻译新鲜度检查通过，6
个固定来源合集的生成检查通过，2 个浮动来源按既有规则明确跳过。发现并修复了生成器在 Windows 使用反斜杠造成的误报：输出改为 POSIX
路径，比较规则不放宽、不重写合集数据。

## English

Fill only license, type and listed-release facts supported by existing
owners or pinned upstream content. Preserve custom license restrictions
and acquisition eligibility. Keep the current bilingual README and
manifest-derived inventory; do not author usage analytics.

This PR deliberately excludes localized team fields and the two-part
WeChat Pay version that older clients reject. Those changes remain
pending a compatible client release.

Validation passes: 47 catalog-validator tests, 19 i18n tests, five
collection-generator tests, complete catalog and translation checks, and
generated inventory checks for six pinned collections. Two mutable
sources remain explicitly skipped. Fix Windows-generated path separators
without weakening comparison or changing declared children.

2026-09-22 01:09:03 +08:00

8.1 KiB

Raw Blame History

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

license

name

description

version

type

risk_level

status

disable-model-invocation

registering-services Skill

Native applications are not internal services

A native-app such as DesireCore Control is installed and managed through the App acquisition flow and app-install-manager (1.5.2 or newer). Its outward MCP endpoint is for external agents, not permission to register it in DesireCore's service catalog or an Agent's MCP configuration. Do not convert it to mcp/docker-app, derive services, or call service-registration APIs for it. Runtime GUI access still uses the governed ControlDesireCoreGui tool.

L0: One-line Summary

Tell the Agent how to register an external HTTP/MCP service into the global catalog with human governance.

L1: Overview

This meta-skill teaches you (the Agent) how to add a new service to the shared "Apps & Services" catalog. It does not invoke external services itself — once registered, use the per-service Skill at ~/.desirecore/skills/svc-<id>/ or the using-services meta-skill to actually call them.

When to use this skill

The user asks to register an API or service (e.g. "add the Acme search endpoint to our catalog")
You just deployed a backend you want other Agents to be able to reach
You discover a useful public API and want to make it shareable

When NOT to use it

One-off HTTP calls that nobody else needs to repeat — just call HttpRequest directly
Adding an MCP server to your own agent only — POST to /api/agents/<your-id>/mcp-servers instead, no catalog entry needed
Modifying an existing catalog entry — the user must promote/reject through the Store UI

L2: How to register a service

Step 1 — Gather the required fields

Before calling the API, collect:

Field	Required	Notes
`id`	yes	kebab-case, globally unique (e.g. `acme-search-api`)
`name`	yes	Human-readable display name
`description`	yes	One sentence — what it does
`protocol`	yes	`'http'` or `'mcp'`
`tags`	yes	Searchable list, e.g. `['search', 'web']`
`registeredBy`	yes	Your own agent id
`endpoint`	required when `protocol='http'`	Base URL of the API
`riskLevel`	recommended	`low` / `medium` / `high` / `critical`
`auth`	when API requires auth	`{ type, secretRef }` — see below
`operations`	recommended	Operations list for the per-service Skill
`capabilities`	optional	What this service can do

Step 2 — Choose `riskLevel` honestly

riskLevel decides whether future calls to this service trigger an approval gate:

low — read-only data that's safe to invoke without prompting (e.g. public weather API)
medium — default for most APIs; first invoke per session may prompt
high — services that move money, send emails, mutate user data
critical — services that can cause irreversible harm; every call requires human approval

Bias toward higher risk if uncertain. Under-classifying is worse than over-classifying.

Step 3 — Reference credentials with `secretRef`, never inline

Do not put API keys/tokens into the catalog entry. The catalog is global, visible in the Store UI, and may be inspected by future people. Instead:

{
  "auth": {
    "type": "bearer",
    "secretRef": "secrets/api-keys/acme"  // pointer, not the actual key
  }
}

HttpRequest resolves secretRef at call time. If the secret doesn't exist yet, ask the user to provide it through their own secrets manager — not through the chat.

Step 4 — Call the registration API

Use the HttpRequest tool to POST to the local Agent Service:

tool: HttpRequest
parameters:
  url: http://127.0.0.1:<agent-service-port>/api/registry/agent-services
  method: POST
  body:
    id: acme-search-api
    name: "Acme Search API"
    description: "Full-text search across Acme's product catalog"
    protocol: http
    endpoint: https://api.acme.example/search
    tags: ["search", "products"]
    registeredBy: "<your-agent-id>"
    riskLevel: medium
    auth:
      type: bearer
      secretRef: secrets/api-keys/acme
    operations:
      - name: search
        method: GET
        path: /v1/items
        description: "Search products by query string"
      - name: getDetail
        method: GET
        path: /v1/items/{id}
        description: "Get a single product by id"

(The Agent Service port is available via the runtime; ask request-help skill if you're unsure how to discover it.)

Step 5 — Wait for human approval

The endpoint triggers a service-approval request to the human user. The HTTP call will block until they approve or reject through the Store UI.

Approved → entry is written to ~/.desirecore/config/registry-agent-services.json with reviewStatus: 'pending'. While pending, only you (the registering Agent) can call it.
Rejected → the API returns 403; do not retry, ask the user how to proceed.

After approval, the human can later promote the entry from pending to approved in the Store UI. Promotion makes the service callable by all Agents and triggers service-skill-generator to write ~/.desirecore/skills/svc-<id>/SKILL.md with concrete examples derived from the operations you provided.

Step 6 — Don't re-register

If POST /api/registry/agent-services returns 409 Conflict, the service already exists. Do not try alternative ids unless the user explicitly asks you to register a separate variant — silently shadowing an existing service is a governance failure.

Failure modes

Endpoint blocked by SSRF guard: the registration API rejects private network addresses (10.x / 172.16-31.x / 192.168.x / 169.254.x) except localhost. Public IPs and DNS names are allowed.
Missing registeredBy: the API returns 400. Always include your own agent id — there is no anonymous registration.
Approval timeout: the broker times out after the user is idle long enough; treat this as rejected.

8.1 KiB Raw Blame History