mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-09-05 17:03:49 +08:00
Yige
d76db984b6
## 问题 / Problem 市场 CI 要求每个 Agent 条目都有 catalog sidecar，但 sidecar 校验器只接受相邻的 agent.json。客户端已支持的 Agent entry.json 指针因此无法满足完整覆盖门禁。 The catalog completeness gate requires sidecars for every Agent, while the validator previously read only agent.json. Valid Agent pointer entries could not satisfy CI. ## 修改 / Changes - Agent 主文件严格二选一：内联 agent.json 或指针 entry.json；目录 slug 与安装源 UUID 保持分离。 - 使用从主仓固定提交导出的完整客户端 Agent entry Schema，先校验原始类型、字段、版本、路径和策略组合，再比较 sidecar。 - 对齐 latestVersion、固定来源、许可/治理、兼容性和有效的缺省 market/market 策略，拒绝 sidecar 单方面提升托管权限。 - 未修改产品条目、manifest、现有 sidecar Schema 或 CI 完整性要求。 Agent pointers now pass the pinned client input schema before source metadata consistency checks. Effective default policies are compared without promoting catalog metadata into authority. Existing inline Agents and Skills retain their validation paths; no entries or CI requirements change. ## 验证 / Validation - 29 + 4 + 9 项定向 Python 测试通过。 - 完整 i18n、catalog --require-complete、translation freshness 检查通过；116 条既有警告与基线一致，无新增。 - 原始客户端 Schema 与固定主仓来源逐项比较一致（仅增加溯源注释）。 - 独立代码审查发现的原始契约与缺省策略问题已修复并复核。 - 公开信息边界检查覆盖完整工作树、隐藏文件、链接目标与新增 Git 元数据，通过。 Targeted tests, full catalog/i18n/freshness validation, source-schema comparison and independent review passed. Existing warnings are unchanged. This PR repairs catalog validation; it does not claim runtime installation of a new product. --------- Co-authored-by: yige <yige@yigedeMacBook-Neo.local>
245 lines
9.7 KiB
Markdown
245 lines
9.7 KiB
Markdown
# DesireCore Market
|
||
|
||
DesireCore 官方市场仓库，存放官方维护的 Agent/Skill 定义，以及经过整理的第三方 Skill 入口。
|
||
|
||
## Repository Shape
|
||
|
||
```
|
||
.
|
||
├── manifest.json # Market metadata, supported locales, aggregate stats
|
||
├── categories.json # Category registry and localized labels
|
||
├── builtin-skills.json # Built-in local SKILL.md skills
|
||
├── agents/
|
||
│ └── desirecore/
|
||
│ └── agent.json
|
||
└── skills/
|
||
├── <local-skill>/
|
||
│ ├── SKILL.md
|
||
│ └── SKILL.<locale>.md
|
||
└── <external-entry>/
|
||
└── entry.json
|
||
```
|
||
|
||
The market currently contains:
|
||
|
||
- `1` Agent: `desirecore`
|
||
- `34` local built-in skills with `SKILL.md`
|
||
- `28` external skill entries with `entry.json`
|
||
- `62` publishable skills in total (`SKILL.md` + `entry.json`)
|
||
|
||
## Skill Sources
|
||
|
||
Local built-in skills are installable from this repository and must be listed in `builtin-skills.json`:
|
||
|
||
```text
|
||
code-intelligence, configuring-compute, create-agent, dashscope-image-gen, delete-agent,
|
||
dev-environment-setup, discover-agent, docx, frontend-design, guizang-ppt,
|
||
image-to-image, mail-operations, manage-skills, manage-teams, markdown,
|
||
minimax-music-gen, minimax-video-gen, nodejs-runtime, pdf, pptx,
|
||
presentation-forge, python-runtime, registering-services, s3-storage-operations, skill-creator,
|
||
tech-diagram, update-agent, using-services, web-access, workflow, workforce-optimization,
|
||
xiaomi-tts, xlsx
|
||
```
|
||
|
||
`builtin-skills.json#retired` lists old built-in Skill IDs that clients may safely retire during
|
||
startup. Clients only remove copies tracked in `skills.lock` as market/bundled content whose
|
||
`SKILL.md` hash still matches the installed record; manually installed or locally modified copies
|
||
are preserved. An ID must not appear in both `skills` and `retired`.
|
||
|
||
External entries are marketplace pointers to Git/Web/ZIP sources:
|
||
|
||
```text
|
||
agent-reach, ai-news-radar, amap-jsapi-skill, baoyu-skills, dingtalk-api,
|
||
flyai-skill, follow-builders, humanizer, humanizer-zh,
|
||
ian-xiaohei-illustrations, impeccable, karpathy-guidelines, khazix-skills,
|
||
larksuite-cli, last30days, luckin-my-coffee, marketingskills,
|
||
mattpocock-skills, minimax-image-gen, minimax-tts, mt-paotui-for-client,
|
||
netease-skills, nuwa-skill, taste-skill, watch, watchless,
|
||
wechatpay-skills, wecom-cli
|
||
```
|
||
|
||
## Data Formats
|
||
|
||
### Local Skill (`skills/<id>/SKILL.md`)
|
||
|
||
Local skills use YAML frontmatter plus Markdown body. The top-level `name` must equal the directory slug. Display strings live in `metadata.i18n`.
|
||
|
||
```yaml
|
||
---
|
||
name: web-access
|
||
description: >-
|
||
Use this skill when ...
|
||
version: 2.0.1
|
||
type: procedural
|
||
risk_level: low
|
||
status: enabled
|
||
metadata:
|
||
author: desirecore
|
||
updated_at: '2026-05-05'
|
||
i18n:
|
||
default_locale: en-US
|
||
source_locale: zh-CN
|
||
locales: [zh-CN, en-US]
|
||
zh-CN:
|
||
name: 联网访问
|
||
short_desc: 联网搜索、网页抓取、登录态浏览器访问
|
||
body: ./SKILL.zh-CN.md
|
||
translated_by: human
|
||
en-US:
|
||
name: Web Access
|
||
short_desc: Web search, page fetching, logged-in browser access
|
||
body: ./SKILL.md
|
||
source_hash: sha256:...
|
||
translated_by: human
|
||
market:
|
||
category: research
|
||
channel: latest
|
||
maintainer:
|
||
name: DesireCore Official
|
||
verified: true
|
||
---
|
||
```
|
||
|
||
### External Entry (`skills/<id>/entry.json`)
|
||
|
||
External entries point to upstream packages or repositories. They are counted in `manifest.stats.totalSkills` but are not included in `builtin-skills.json`.
|
||
|
||
```json
|
||
{
|
||
"id": "example-skill",
|
||
"name": "Example Skill",
|
||
"category": "development",
|
||
"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\">...</svg>",
|
||
"tags": ["example"],
|
||
"maintainer": {
|
||
"name": "Example",
|
||
"verified": false,
|
||
"account": "example",
|
||
"url": "https://github.com/example/example-skill"
|
||
},
|
||
"stewardship": "community",
|
||
"license": "MIT",
|
||
"redistribution": "allowed",
|
||
"source": {
|
||
"kind": "git",
|
||
"repoUrl": "https://github.com/example/example-skill.git",
|
||
"repoBranch": "main"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Catalog metadata sidecar (`catalog-metadata.v1.json`)
|
||
|
||
The versioned catalog metadata contract is stored at one fixed path next to each
|
||
legacy item:
|
||
|
||
```text
|
||
agents/<id>/catalog-metadata.v1.json
|
||
skills/<id>/catalog-metadata.v1.json
|
||
```
|
||
|
||
Legacy `agent.json`, `SKILL.md`, and `entry.json` files remain the compatibility
|
||
surface for older clients. New clients merge the sidecar through a deterministic
|
||
adapter. Any field repeated in both files must have the same value; the validator
|
||
rejects drift rather than choosing one copy silently.
|
||
|
||
Agent listings support exactly one of `agents/<slug>/agent.json` (inline metadata)
|
||
or `agents/<slug>/entry.json` (an external pointer), alongside the sidecar. Missing
|
||
or simultaneous primary files are rejected. For a pointer, `entry.id` and sidecar
|
||
`identity.id` use the catalog directory slug and `identity.kind` is `agent`; the
|
||
upstream AgentFS `agent.json.id` remains its own UUID and must not be rewritten.
|
||
|
||
Agent pointers first pass the complete raw client contract in
|
||
[`schemas/market-agent-entry.client.schema.json`](schemas/market-agent-entry.client.schema.json),
|
||
exported from `marketAgentEntrySchema` in the DesireCore repository at commit
|
||
`18bbb86f62e1288b1f945209bed74ec72620a9d4`. The schema's `$comment` records the
|
||
source blob as well. Refresh this generated snapshot from the TypeScript export
|
||
when changing client compatibility; do not replace it with permissive sidecar
|
||
validation. Version fields keep their original types and the client's supported
|
||
format. Installation/update policies must either both be absent (effective
|
||
`market/market`) or form a complete supported pair; the sidecar must preserve
|
||
that effective pair.
|
||
|
||
Agent pointer `latestVersion` maps to sidecar `release.version`; optional
|
||
`requiredClientVersion`, `installPolicy`, and `updatePolicy` must agree with the
|
||
sidecar compatibility/spec fields. Pointer source fields must describe the same
|
||
artifact as `provenance.content`, and `maintainer` maps to `upstreamMaintainer`.
|
||
An installable Agent pointer must itself pin `source.ref` (Git) or `source.sha256`
|
||
(Web/ZIP); an immutable ref supplied only by the sidecar cannot pin a mutable
|
||
entry. Existing immutable-source, license, governance-review and complete-coverage
|
||
checks still apply. Agent pointers do not receive the built-in Skill exceptions.
|
||
|
||
Agent 目录必须在 `agent.json` 内联元数据和 `entry.json` 外部指针中二选一，并提供 sidecar。
|
||
Pointer 原始 JSON 先通过固定客户端提交导出的完整 Schema；版本类型与格式、来源路径和策略组合不能由 sidecar 掩盖。
|
||
Pointer 的目录 slug、`entry.id`、sidecar `identity.id` 必须一致；上游 AgentFS 的 UUID 不改写。
|
||
安装/更新策略双缺省时有效值仍是 `market/market`，sidecar 不得将其改成系统条目。
|
||
`latestVersion`、最低客户端版本和安装/更新策略须与 sidecar 对齐；来源必须是同一个制品。
|
||
可安装指针自身必须固定 Git ref 或 Web/ZIP 摘要，不能只在 sidecar 宣称不可变版本。
|
||
现有许可、治理审查、不可变来源和完整覆盖门禁继续有效，不适用内置 Skill 的宽松例外。
|
||
|
||
The sidecar records source-owned presentation, release, timestamp, content
|
||
provenance, governance, compatibility, and type-specific facts. It deliberately
|
||
cannot declare `catalogSourceId`, catalog commit/path/trust, effective official
|
||
status, installation state, device state, health, URLs discovered at runtime, or
|
||
`syncedAt`. DesireCore injects trusted catalog provenance and runtime facts.
|
||
|
||
Time facts are explicit `known`/`unknown` values. A known day uses
|
||
`YYYY-MM-DD` with `precision: "day"`; a known second uses an RFC 3339 UTC value
|
||
ending in `Z` with `precision: "second"`. Never use the current date, clone time,
|
||
or synchronization time to fill an unknown catalog or release timestamp.
|
||
|
||
Collection children stay in their parent's sidecar. Each child declares the
|
||
canonical `skill + parentId + id` identity and its own release fact; a collection
|
||
parent may have an unknown version, and a child version must not be inferred from
|
||
the parent.
|
||
|
||
The strict source schema is
|
||
[`schemas/catalog-metadata.v1.schema.json`](schemas/catalog-metadata.v1.schema.json).
|
||
|
||
## Categories
|
||
|
||
Valid category slugs are declared in `categories.json`:
|
||
|
||
```text
|
||
productivity, development, business, creative, design, media,
|
||
communication, research, data, management
|
||
```
|
||
|
||
## Validation
|
||
|
||
Run these checks before submitting changes:
|
||
|
||
```bash
|
||
# Full market + i18n validation
|
||
uv run scripts/i18n/validate-i18n.py
|
||
|
||
# Catalog sidecar validator unit tests and standalone validation
|
||
uv run scripts/catalog/test_validate_catalog_metadata.py
|
||
uv run scripts/catalog/test_collection_generator.py
|
||
uv run scripts/catalog/validate_catalog_metadata.py
|
||
|
||
# Translation freshness check
|
||
uv run scripts/i18n/translate.py --check
|
||
|
||
# Verify pinned collection children without changing entry.json (network required;
|
||
# mutable collections are reported and skipped because their output is not reproducible)
|
||
uv run scripts/gen-collection-children.py --check
|
||
|
||
# Optional network check for entry.json source URLs
|
||
uv run scripts/i18n/validate-i18n.py --online
|
||
```
|
||
|
||
The validators check market stats, category references, `builtin-skills.json`,
|
||
`entry.json` structure, sidecar schema and legacy consistency, immutable source
|
||
evidence, collection identity, i18n completeness, and translation freshness.
|
||
Human-locked translations (`translated_by: human`) must keep `source_hash`
|
||
aligned after manual review. During a data migration,
|
||
`scripts/catalog/validate_catalog_metadata.py --require-complete` additionally
|
||
requires one sidecar for every top-level Agent and Skill.
|
||
|
||
Detailed i18n guidance is in [docs/I18N.md](docs/I18N.md).
|
||
|
||
## License
|
||
|
||
MIT License. See [LICENSE](LICENSE).
|