mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-10-21 07:24:00 +08:00
docs: split and expand English and Chinese market READMEs (#183)
Split the market documentation into synchronized English and Simplified Chinese READMEs. Expand getting started, catalog contracts, localization, contribution and validation guidance, security boundaries, and licensing. Replace stale inventory snapshots with authoritative references.
This commit is contained in:
GitHub
489
README.md
489
README.md
@@ -1,370 +1,253 @@
|
|||||||
# DesireCore Market
|
# DesireCore Market
|
||||||
|
|
||||||
DesireCore 官方市场仓库，存放官方维护的 Agent/Team/Skill 定义，以及经过整理的第三方 Skill 入口。
|
**English** | [简体中文](README.zh-CN.md)
|
||||||
|
|
||||||
## Repository Shape
|
The official, version-controlled catalog of **Agents, Teams, and Skills for DesireCore**.
|
||||||
|
|
||||||
|
Discover reusable assistants, coordinated agent teams, and task-specific skills in one place. This repository maintains catalog metadata, locally bundled skills, and curated pointers to upstream content, together with schemas and validation tools for consistent publication.
|
||||||
|
|
||||||
|
[Overview](#overview) · [Getting started](#getting-started) · [Repository layout](#repository-layout) · [Listing contracts](#listing-contracts) · [Localization](#localization) · [Contributing](#contributing) · [Validation](#validation) · [Security and trust](#security-and-trust) · [Related projects](#related-projects) · [License](#license)
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
| Resource | Purpose | Where to explore |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| **Agents** | Individual assistants with a defined role, capabilities, and configuration; published as inline metadata or an upstream pointer. | [`agents/`](agents/) |
|
||||||
|
| **Teams** | Groups of agents coordinated by a supervisor; published as pointers to repositories that the client forks. | [`teams/`](teams/) |
|
||||||
|
| **Skills** | Reusable task instructions and supporting resources; bundled locally or discovered through upstream Git, Web, or ZIP sources. | [`skills/`](skills/) |
|
||||||
|
|
||||||
|
The market is a **content catalog, not a standalone application or execution runtime**. A listing describes what a resource is, where it comes from, and the conditions under which it can be used. Installation and execution belong to a compatible DesireCore client and the resource's dependencies.
|
||||||
|
|
||||||
|
### Catalog sources of truth
|
||||||
|
|
||||||
|
| File | What it defines |
|
||||||
|
| --- | --- |
|
||||||
|
| [`manifest.json`](manifest.json) | Market identity, schema version, supported locales, default locale, and aggregate statistics. |
|
||||||
|
| [`categories.json`](categories.json) | Valid category IDs and their localized labels and descriptions. |
|
||||||
|
| [`builtin-skills.json`](builtin-skills.json) | Local built-in skill IDs and the retirement list. |
|
||||||
|
| `catalog-metadata.v1.json` beside each listing | Versioned presentation, release, provenance, governance, and compatibility facts. |
|
||||||
|
|
||||||
|
Use the manifest and actual catalog directories for the current inventory rather than maintaining a second list of counts in this README. `totalSkills` counts top-level local `SKILL.md` listings plus external `entry.json` listings, not every child inside a skill collection. `totalTeams` may be omitted for a catalog with no teams; when present, it must match the catalog exactly.
|
||||||
|
|
||||||
|
Categories cover productivity, development, business, creative work, design, media, communication, research, data, and management. Use the IDs in `categories.json` when publishing; display labels are not category IDs.
|
||||||
|
|
||||||
|
## Getting started
|
||||||
|
|
||||||
|
### Use the market in DesireCore
|
||||||
|
|
||||||
|
1. Open the market in a compatible DesireCore client and synchronize the official catalog.
|
||||||
|
2. Inspect the resource's description, source, release information, client requirements, license, and external dependencies before installation. Read any available usage notes.
|
||||||
|
3. Follow the client's installation flow when the listing is installable, then complete any required local setup or authorization. Keep credentials and private configuration outside this public repository.
|
||||||
|
|
||||||
|
**Listed does not necessarily mean installable.** Catalog metadata can describe listing-only resources; compatibility, governance, source reproducibility, or licensing requirements may prevent installation. Catalog synchronization also does not upgrade the desktop client or provision third-party services.
|
||||||
|
|
||||||
|
### Explore or contribute locally
|
||||||
|
|
||||||
|
For repository maintenance, use Git, Python **3.10 or newer**, and `uv`. The Python scripts declare their dependencies inline; `uv run` manages their execution environments.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/desirecore/market.git
|
||||||
|
cd market
|
||||||
|
|
||||||
|
# Validate market structure and skill localization.
|
||||||
|
uv run scripts/i18n/validate-i18n.py
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Initial environment setup may download Python packages. The validation command above does not require model API credentials or fetch upstream content unless `--online` is supplied. See [Validation](#validation) for coverage checks, translation freshness, and focused commands.
|
||||||
|
|
||||||
|
Cloning this repository only downloads the catalog and bundled files; it does not install the DesireCore client, agents, teams, or external products.
|
||||||
|
|
||||||
|
## Repository layout
|
||||||
|
|
||||||
|
```text
|
||||||
.
|
.
|
||||||
├── manifest.json # Market metadata, supported locales, aggregate stats
|
├── README.md # English overview and contributor guide
|
||||||
├── categories.json # Category registry and localized labels
|
├── README.zh-CN.md # Simplified Chinese counterpart
|
||||||
├── builtin-skills.json # Built-in local SKILL.md skills
|
├── manifest.json # Market metadata, locales, and statistics
|
||||||
├── agents/
|
├── categories.json # Category registry
|
||||||
│ ├── desirecore/
|
├── builtin-skills.json # Built-in skills and retirement policy
|
||||||
│ │ └── agent.json
|
├── agents/<id>/
|
||||||
│ └── <agent-listing>/
|
│ ├── agent.json OR entry.json # Exactly one primary listing file
|
||||||
│ ├── agent.json
|
│ ├── catalog-metadata.v1.json # Versioned catalog metadata
|
||||||
|
│ └── USAGE[.<locale>].md # Optional inline-agent usage notes
|
||||||
|
├── teams/<id>/
|
||||||
|
│ ├── entry.json # Upstream Git fork pointer only
|
||||||
|
│ └── catalog-metadata.v1.json
|
||||||
|
├── skills/<id>/
|
||||||
|
│ ├── SKILL.md OR entry.json # Local skill or external source pointer
|
||||||
│ ├── catalog-metadata.v1.json
|
│ ├── catalog-metadata.v1.json
|
||||||
│ └── USAGE.md # Optional usage notes (USAGE.<locale>.md for variants)
|
│ ├── SKILL.<locale>.md # Localized body for a local skill
|
||||||
├── teams/
|
│ ├── references/ # Optional supporting documentation
|
||||||
│ └── <team>/
|
│ └── scripts/ # Optional skill-specific helpers
|
||||||
│ └── entry.json
|
├── schemas/ # Catalog and exported client contracts
|
||||||
└── skills/
|
├── scripts/
|
||||||
├── <local-skill>/
|
│ ├── catalog/ # Catalog validation and focused tests
|
||||||
│ ├── SKILL.md
|
│ ├── i18n/ # Localization schema, validation, translation
|
||||||
│ └── SKILL.<locale>.md
|
│ └── gen-collection-children.py # Upstream collection inventory generation
|
||||||
└── <external-entry>/
|
├── docs/ # Authoring and application guides
|
||||||
└── entry.json
|
├── .github/workflows/ # Validation, translation, and review automation
|
||||||
|
├── AGENTS.md / CLAUDE.md # Equivalent repository contribution policies
|
||||||
|
├── LICENSE # License for repository-original content
|
||||||
|
└── THIRD_PARTY_NOTICES.md # Third-party licensing qualifications
|
||||||
```
|
```
|
||||||
|
|
||||||
The market currently contains:
|
The tree illustrates supported shapes, not files required in every directory. Localized bodies, helper scripts, and references belong to local skills; external pointers keep their implementation upstream. A team directory contains `entry.json` and its sidecar, not an inline `team.json`.
|
||||||
|
|
||||||
- `7` Agents: `desirecore`, `dingtalk-workspace`, `feishu-orchestrator`, `invoice-organizer`, `mimo-model-quota-monitor`, `tender-review-assistant`, `wecom-assistant`
|
## Listing contracts
|
||||||
- `2` Teams: `biao-shu-lian-he-shen-cha`, `contract-review-team`
|
|
||||||
- `40` local built-in skills with `SKILL.md`
|
|
||||||
- `31` external skill entries with `entry.json`
|
|
||||||
- `71` publishable skills in total (`SKILL.md` + `entry.json`)
|
|
||||||
|
|
||||||
## Skill Sources
|
Use the schemas and existing listings as implementation references. A shortened JSON example is not a substitute for the complete client contract.
|
||||||
|
|
||||||
Local built-in skills are installable from this repository and must be listed in `builtin-skills.json`:
|
### Local skills
|
||||||
|
|
||||||
```text
|
A local skill lives at `skills/<id>/SKILL.md` and combines YAML frontmatter with a Markdown instruction body. Its top-level `name` must match the directory's lowercase ASCII slug; localized display names belong in `metadata.i18n`.
|
||||||
baidu-poi-search, ccgp-gov-procurement, clone-agent, cnipa-patent-search, code-intelligence,
|
|
||||||
configuring-compute, create-agent, creditchina-query, 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, multi-source-sentiment, nodejs-runtime, pdf, pptx,
|
|
||||||
presentation-forge, python-runtime, registering-services, s3-storage-operations, skill-creator,
|
|
||||||
tech-diagram, tianyancha-risk, 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
|
Only `SKILL.md` carries frontmatter. Localized `SKILL.<locale>.md` files contain the body, start with the corresponding locale comment, and are referenced by the i18n metadata. For example, `SKILL.zh-CN.md` starts with `<!-- locale: zh-CN -->`. Market skills must set `disable-model-invocation: true` or omit the field; `false` is rejected.
|
||||||
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:
|
Register every local built-in skill in `builtin-skills.json.skills`, supply its sidecar, and use a valid market category. See the [frontmatter schema](scripts/i18n/schema/skill-frontmatter.schema.json), [Web Access example](skills/web-access/SKILL.md), and [i18n authoring guide](docs/I18N.md) (Chinese).
|
||||||
|
|
||||||
```text
|
The `retired` list identifies former built-in skills that clients may retire at startup. Clients remove only market/bundled copies tracked in `skills.lock` whose `SKILL.md` hash still matches the installation record. Manually installed or locally modified copies are preserved. An ID must never appear in both `skills` and `retired`.
|
||||||
agent-reach, ai-news-radar, amap-jsapi-skill, archify, baoyu-skills, dingtalk-api,
|
|
||||||
dingtalk-cli, flyai-skill, follow-builders, humanizer, humanizer-zh,
|
|
||||||
ian-xiaohei-illustrations, impeccable, karpathy-guidelines, khazix-skills,
|
|
||||||
larksuite-cli, last30days, luckin-my-coffee, lumarescue, 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
|
### External skills and collections
|
||||||
|
|
||||||
### Local Skill (`skills/<id>/SKILL.md`)
|
An external skill uses `skills/<id>/entry.json` to describe its upstream source, presentation, maintainer, category, license, and redistribution terms. Skill listings require an inline SVG `icon`. Supported source kinds are `git`, `web`, and `zip`; external listings count toward `manifest.stats.totalSkills` but do not belong in the built-in skill index.
|
||||||
|
|
||||||
Local skills use YAML frontmatter plus Markdown body. The top-level `name` must equal the directory slug. Display strings live in `metadata.i18n`.
|
A collection groups multiple upstream skills under one listing, with a declared `children` inventory for discovery. Keep the children's metadata in the parent's sidecar. Each child has its own `skill + parentId + id` identity and release fact; never infer a child's version from its parent, whose version may be unknown.
|
||||||
|
|
||||||
```yaml
|
See the [Lark Suite CLI entry](skills/larksuite-cli/entry.json) and [sidecar](skills/larksuite-cli/catalog-metadata.v1.json). The [collection generator](scripts/gen-collection-children.py) derives children from upstream `SKILL.md` files; its `--check` mode verifies reproducible, pinned collections without rewriting entries.
|
||||||
---
|
|
||||||
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`)
|
### Agents
|
||||||
|
|
||||||
External entries point to upstream packages or repositories. They are counted in `manifest.stats.totalSkills` but are not included in `builtin-skills.json`.
|
An agent directory must contain exactly one primary file: `agent.json` for inline metadata **or** `entry.json` for an external pointer, plus `catalog-metadata.v1.json`. Neither a missing primary file nor both files together is valid.
|
||||||
|
|
||||||
```json
|
For pointers, the directory slug, `entry.id`, and sidecar `identity.id` must agree, and `identity.kind` is `agent`. The upstream AgentFS `agent.json.id` is a separate UUID and must not be rewritten to match the catalog slug.
|
||||||
{
|
|
||||||
"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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Team Listing (`teams/<id>/entry.json`)
|
The raw pointer must pass the [exported agent client schema](schemas/market-agent-entry.client.schema.json) before sidecar validation. Preserve version types and supported formats. `installPolicy` and `updatePolicy` must either both be absent, with effective values `market/market`, or form a complete supported pair. The sidecar must preserve that effective pair rather than reclassifying the resource as a system item.
|
||||||
|
|
||||||
A Team is a group of Agents with a supervisor. It is published as a **fork pointer
|
`latestVersion` maps to `release.version`; client requirements, policies, and source fields must agree across the pointer and sidecar. `maintainer` maps to `upstreamMaintainer`. An installable pointer must itself pin a full Git commit in `source.ref`, or a Web/ZIP digest in `source.sha256`; a pin declared only in the sidecar is insufficient. Agent pointers do not receive the built-in skill exceptions to source, license, or review requirements.
|
||||||
only**: the team body (`team.json`, `members.json`, `shared/`) always stays in the
|
|
||||||
upstream team repository, and the catalog registers just "what it is and where to
|
|
||||||
fork it from". Installation forks that repository and installs the declared members;
|
|
||||||
updates are a `git pull` on the fork. Because both actions are Git actions,
|
|
||||||
`source.kind` must be `git` and `source.repoUrl` is required — `zip` and `web` cannot
|
|
||||||
express either one — and a Team deliberately has **no** `installPolicy` /
|
|
||||||
`updatePolicy` pair: it is always market-initiated fork plus repository-driven update.
|
|
||||||
|
|
||||||
`teams/<id>/` therefore holds exactly `entry.json` plus the sidecar. There is no
|
An inline agent may include concise, text-only `USAGE.md` notes for prerequisites, authorization, and safety boundaries. Localized variants use `USAGE.<locale>.md`, resolved by requested locale → source locale → default locale → unsuffixed file. Usage is displayed separately from `fullDesc`, which also enters the agent's runtime context. Clients may truncate long notes; put extensive supporting material in skill `references/` instead. Relative images do not render in the usage section.
|
||||||
inline form; a `team.json` in the catalog is rejected.
|
|
||||||
|
|
||||||
```json
|
Examples: [inline DesireCore agent](agents/desirecore/agent.json) and [DingTalk Workspace pointer](agents/dingtalk-workspace/entry.json).
|
||||||
{
|
|
||||||
"id": "example-team",
|
|
||||||
"name": "Example Team",
|
|
||||||
"category": "development",
|
|
||||||
"tags": ["example"],
|
|
||||||
"latestVersion": "0.1.0",
|
|
||||||
"maintainer": {
|
|
||||||
"name": "Example",
|
|
||||||
"verified": false,
|
|
||||||
"account": "example",
|
|
||||||
"url": "https://github.com/example"
|
|
||||||
},
|
|
||||||
"stewardship": "community",
|
|
||||||
"license": "MIT",
|
|
||||||
"redistribution": "source-pointer-only",
|
|
||||||
"source": {
|
|
||||||
"kind": "git",
|
|
||||||
"repoUrl": "https://github.com/example/example-team.git",
|
|
||||||
"repoBranch": "main",
|
|
||||||
"ref": "0123456789abcdef0123456789abcdef01234567"
|
|
||||||
},
|
|
||||||
"requiredClientVersion": "10.0.0",
|
|
||||||
"avatar": { "t": "示", "bg": "linear-gradient(135deg, #5856D6, #3634A3)" },
|
|
||||||
"supervisorName": "Example Supervisor",
|
|
||||||
"supervisorAgentId": "example-lead",
|
|
||||||
"memberCount": 3,
|
|
||||||
"memberNames": ["Example Member One", "Example Member Two"]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
A Team card is rendered from `avatar`, not from `icon`. The client's runtime
|
### Teams
|
||||||
projection `marketTeamSchema` requires `avatar` and has no `icon` property at all —
|
|
||||||
the same is true of `marketAgentSchema`, while only `marketSkillSchema` exposes
|
|
||||||
`icon`. The entry contract inherits `icon` from the shared common properties, so it
|
|
||||||
is *accepted*, but it can never reach a card. The validator therefore requires `icon`
|
|
||||||
on Skill listings only, and warns when an Agent or Team listing declares one.
|
|
||||||
|
|
||||||
`redistribution` stays `source-pointer-only` for a Team even under a permissive
|
A team is a supervisor-led group of agents, published **only as a Git fork pointer** at `teams/<id>/entry.json`, alongside its sidecar. The implementation (`team.json`, `members.json`, and `shared/`) stays upstream. Installation forks that repository and installs its declared members; subsequent updates use `git pull` on the fork.
|
||||||
license: the market never ships the team body, it only points at the repository the
|
|
||||||
client forks. The license governs what a fork may do; `redistribution` describes how
|
|
||||||
the content is delivered, and for teams that is always "fetch from upstream".
|
|
||||||
|
|
||||||
`supervisorName`, `supervisorAgentId`, `memberCount`, `memberNames` and
|
Consequently, `source.kind` must be `git`, `source.repoUrl` is required, and an installable pointer must pin a full commit SHA in `source.ref`. Branches and tags are mutable and do not satisfy that pin. Teams have no `installPolicy` / `updatePolicy` pair, and `redistribution` remains `source-pointer-only` even when the upstream license is permissive.
|
||||||
`requiredSkills` are display metadata declared by the publisher. They may drift from
|
|
||||||
the upstream repository, so installation, permissions and member resolution must read
|
|
||||||
the forked `team.json` / `members.json` instead. Teams are counted in
|
|
||||||
`manifest.stats.totalTeams`, which the client keeps optional: a catalog with no teams
|
|
||||||
may omit it, and once the key is present it must be exact.
|
|
||||||
|
|
||||||
### Catalog metadata sidecar (`catalog-metadata.v1.json`)
|
The raw pointer must pass the [exported team client schema](schemas/market-team-entry.client.schema.json). The directory slug, `entry.id`, and sidecar `identity.id` must agree; `identity.kind` is `team`, and `latestVersion` maps to `release.version`. Source fields must describe the same artifact as `provenance.content`.
|
||||||
|
|
||||||
The versioned catalog metadata contract is stored at one fixed path next to each
|
`supervisorName`, `supervisorAgentId`, `memberCount`, `memberNames`, `requiredSkills`, and `requiredClientVersion` must agree symmetrically with the sidecar: it may neither drop declared facts nor invent absent ones. Member and supervisor display metadata is not installation or permission authority; resolve those facts from the forked `team.json` and `members.json`.
|
||||||
legacy item:
|
|
||||||
|
|
||||||
```text
|
Agent and team cards use `avatar`, not the skill-only `icon` presentation. An `icon` accepted by a shared entry contract still does not reach these cards, and the validator warns about it. See the [Contract Review Team entry](teams/contract-review-team/entry.json).
|
||||||
agents/<id>/catalog-metadata.v1.json
|
|
||||||
teams/<id>/catalog-metadata.v1.json
|
|
||||||
skills/<id>/catalog-metadata.v1.json
|
|
||||||
```
|
|
||||||
|
|
||||||
Legacy `agent.json`, `SKILL.md`, and `entry.json` files remain the compatibility
|
### Versioned catalog metadata
|
||||||
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)
|
Every top-level listing must have `catalog-metadata.v1.json` at the fixed location beside its primary file. This **sidecar** supplements the legacy compatibility file; it does not replace `agent.json`, `entry.json`, or `SKILL.md`. New clients merge it through a deterministic adapter, and validators reject inconsistent duplicated fields.
|
||||||
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.
|
|
||||||
|
|
||||||
An agent listing may also carry an optional `USAGE.md` next to `agent.json`. The
|
The [catalog metadata schema](schemas/catalog-metadata.v1.schema.json) covers presentation, releases, explicit timestamp facts, content provenance, governance, compatibility, and type-specific metadata. Keep these boundaries intact:
|
||||||
client renders it as a separate "Usage" section on the agent detail page, kept
|
|
||||||
apart from `fullDesc` (which is persona text and also enters the agent's runtime
|
|
||||||
context). Localized variants use `USAGE.<locale>.md`, resolved through the same
|
|
||||||
fallback chain as the `i18n` block: requested locale, then `i18n.source_locale`,
|
|
||||||
then `i18n.default_locale`, then the unsuffixed file. Its scope is what a reader
|
|
||||||
needs *before* installing — prerequisites, authorization steps, capability and
|
|
||||||
safety boundaries — not full documentation; clients truncate overlong content.
|
|
||||||
Longer material belongs in a skill's `references/` directory, which the agent
|
|
||||||
loads on demand. Listings without the file are unaffected and render no section.
|
|
||||||
Relative image references do not render on the detail page, so keep `USAGE.md`
|
|
||||||
text-only. See ADR-143 in the DesireCore repository.
|
|
||||||
|
|
||||||
Agent pointers first pass the complete raw client contract in
|
- **Source facts versus runtime facts.** A sidecar cannot declare trusted catalog identity (`catalogSourceId`), catalog commit/path/trust, effective official status, installed state, device state, health, runtime-discovered URLs, or `syncedAt`. DesireCore supplies trusted catalog provenance and runtime observations.
|
||||||
[`schemas/market-agent-entry.client.schema.json`](schemas/market-agent-entry.client.schema.json),
|
- **Evidence paths follow the content.** `license.evidencePath`, `compliance.licenseEvidencePath`, and `compliance.noticePath` are relative to the item directory for vendored content, and the files must exist. For pointers they refer to the upstream snapshot; offline validation cannot fetch that evidence and warns about claims against unpinned sources.
|
||||||
exported from `marketAgentEntrySchema` in the DesireCore repository at commit
|
- **Unknown is a valid fact.** Use explicit `known` / `unknown` states. A known day uses `YYYY-MM-DD` with `precision: "day"`; a known second uses an RFC 3339 UTC timestamp ending in `Z` with `precision: "second"`. Never fill an unknown release or catalog timestamp with the current date, clone time, or synchronization time.
|
||||||
`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
|
The agent and team client schemas are generated compatibility snapshots. Their `$comment` records the upstream source commit and blob. Refresh them from the corresponding TypeScript exports when compatibility changes; do not weaken them or substitute sidecar-only validation.
|
||||||
`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。
|
## Localization
|
||||||
Pointer 原始 JSON 先通过固定客户端提交导出的完整 Schema；版本类型与格式、来源路径和策略组合不能由 sidecar 掩盖。
|
|
||||||
Pointer 的目录 slug、`entry.id`、sidecar `identity.id` 必须一致；上游 AgentFS 的 UUID 不改写。
|
|
||||||
安装/更新策略双缺省时有效值仍是 `market/market`，sidecar 不得将其改成系统条目。
|
|
||||||
`latestVersion`、最低客户端版本和安装/更新策略须与 sidecar 对齐；来源必须是同一个制品。
|
|
||||||
可安装指针自身必须固定 Git ref 或 Web/ZIP 摘要，不能只在 sidecar 宣称不可变版本。
|
|
||||||
现有许可、治理审查、不可变来源和完整覆盖门禁继续有效，不适用内置 Skill 的宽松例外。
|
|
||||||
|
|
||||||
Team listings are pointer-only, so `teams/<slug>/` carries exactly `entry.json` plus
|
The market declares its languages in `manifest.json.supportedLocales`, currently `en-US` and `zh-CN`, with English as the default. Local skill display text lives in `metadata.i18n`; listing JSON and sidecars retain their own schema-defined i18n shapes rather than sharing interchangeable field names.
|
||||||
the sidecar; an inline `team.json` is rejected. Team pointers first pass the complete
|
|
||||||
raw client contract in
|
|
||||||
[`schemas/market-team-entry.client.schema.json`](schemas/market-team-entry.client.schema.json),
|
|
||||||
exported from `marketTeamEntrySchema` the same way as the Agent snapshot; its
|
|
||||||
`$comment` records the source commit and blob. `entry.id`, the directory slug and
|
|
||||||
sidecar `identity.id` must agree, `identity.kind` is `team`, and `latestVersion` maps
|
|
||||||
to `release.version`. `supervisorName`, `supervisorAgentId`, `memberCount`,
|
|
||||||
`memberNames`, `requiredSkills` and `requiredClientVersion` are compared symmetrically:
|
|
||||||
the sidecar may neither drop a fact the pointer declares nor invent one it omits,
|
|
||||||
because the client reads the pointer and a version gate that exists only in the
|
|
||||||
sidecar would not gate anything. Pointer source fields must describe the same
|
|
||||||
artifact as `provenance.content`, and an installable Team pointer must itself pin a
|
|
||||||
full-SHA `source.ref` — a tag is not a reproducible pin, because a tag can be moved
|
|
||||||
to a different commit after the listing is reviewed.
|
|
||||||
|
|
||||||
团队条目只有指针形态：`teams/<slug>/` 仅放 `entry.json` 与 sidecar，目录内出现 `team.json` 直接判非法。
|
For skill bodies, resolve the requested locale, then the source locale, then the default locale. Keep the default body in `SKILL.md`, reference localized bodies explicitly, and keep heading structure aligned across languages. The [glossary](scripts/i18n/glossary.json) records shared terminology.
|
||||||
Pointer 原始 JSON 先通过由 `marketTeamEntrySchema` 导出的完整客户端 Schema；
|
|
||||||
`source.kind` 恒为 `git` 且必须有 `repoUrl`，团队没有 `installPolicy` / `updatePolicy` 组合。
|
|
||||||
目录 slug、`entry.id`、sidecar `identity.id` 必须一致，`identity.kind` 为 `team`。
|
|
||||||
展示字段与最低客户端版本双向比对：sidecar 既不得丢弃指针声明的事实，也不得凭空补上指针没有的事实。
|
|
||||||
可安装团队指针自身必须固定完整 SHA 的 `source.ref`，tag 或分支不算可复现锁定。
|
|
||||||
|
|
||||||
The sidecar records source-owned presentation, release, timestamp, content
|
The [translation workflow](.github/workflows/i18n-translate.yml) translates eligible missing or stale skill locales using configured model credentials. Review its output for terminology, structure, and factual accuracy; automation is not a substitute for review. `translated_by: human` locks a translation against automatic replacement. After a source change, manually synchronize that translation and refresh `source_hash` only after review; never use a fabricated hash to silence a freshness failure.
|
||||||
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.
|
|
||||||
|
|
||||||
`license.evidencePath`, `compliance.licenseEvidencePath` and `compliance.noticePath`
|
Run `translate.py --check` to inspect freshness without calling a model API or rewriting translations. Backend configuration and the authoring workflow are documented in the [i18n guide](docs/I18N.md) (Chinese); the workflow and script are authoritative for current behavior. These two README files are maintained together manually and are not inputs to the skill translation pipeline.
|
||||||
resolve differently by item shape, because the schema constrains only the string
|
|
||||||
form. Vendored content (built-in Skills, inline Agents) ships inside this repository,
|
|
||||||
so the path is relative to the catalog item directory and the file must actually be
|
|
||||||
there — a missing file is an error. A pointer distributes nothing, so its evidence
|
|
||||||
can only be inside the upstream snapshot at the pinned revision; the validator cannot
|
|
||||||
read that offline, so it warns when such a claim is made against an unpinned pointer.
|
|
||||||
Pin `source.ref` to a full commit SHA and the claim becomes falsifiable by anyone who
|
|
||||||
fetches it.
|
|
||||||
|
|
||||||
Time facts are explicit `known`/`unknown` values. A known day uses
|
## Contributing
|
||||||
`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
|
Contributions can add reusable resources, improve existing listings, correct metadata, strengthen validation, or improve translations and documentation.
|
||||||
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
|
1. **Choose the right destination.** Agents, teams, and skills belong here; application entries belong in [DesireCore Registry](https://github.com/desirecore/registry). Read [AGENTS.md](AGENTS.md) or [CLAUDE.md](CLAUDE.md) before editing.
|
||||||
[`schemas/catalog-metadata.v1.schema.json`](schemas/catalog-metadata.v1.schema.json).
|
2. **Work from the current `main` branch.** Use a focused branch or isolated worktree. Select the correct listing shape, a stable public slug, and a valid category. Reuse existing examples without copying their identities, review status, or licensing claims.
|
||||||
|
3. **Publish a complete, consistent listing.** Keep the primary file and sidecar aligned; supply localization, provenance, license evidence, compatibility, and dependency disclosures. Update `builtin-skills.json` for local skills and `manifest.json` statistics when the inventory changes. Do not invent unknown dates or versions.
|
||||||
|
4. **Verify before publication.** Run the applicable checks below, review translations, and follow the private-token and public-information checks in the repository policy. Scan the working tree, including hidden files except `.git`, as well as new paths, branch names, commit messages, and proposed PR text. Keep confidential search tokens outside the repository.
|
||||||
|
5. **Open a pull request against `main`.** Explain the reusable use case, source and licensing decisions, compatibility impact, and validation performed. Use generic examples, keep both README languages synchronized when changing this guide, and wait for required checks and review before merging.
|
||||||
|
|
||||||
## Applications: DesireCore Control
|
For catalog errors, broken pointers, or documentation issues, open an [issue](https://github.com/desirecore/market/issues) with the listing ID, relevant client version, expected behavior, and sanitized reproduction details. Report upstream implementation bugs to the upstream project when appropriate. Never include credentials, private customer data, or confidential incident evidence in a public issue.
|
||||||
|
|
||||||
Applications shown in the DesireCore marketplace are indexed by [DesireCore Registry](https://github.com/desirecore/registry), not by adding a Skill or MCP entry to this repository. [DesireCore Control 1.4.0](https://github.com/desirecore/registry/tree/main/entries/desirecore-control) is a native application for external agents, with ChatGPT tunnel management; installation never registers internal MCP tools. Its catalog declares the required client and installation-skill versions. Catalog publication does not update the desktop client automatically.
|
|
||||||
|
|
||||||
See the [installation guide](docs/desirecore-control.md) / [中文安装说明](docs/desirecore-control.zh-CN.md). Registry maintains the immutable release URL, checksum, application metadata and install/uninstall guide; the open-source implementation stays in `desirecore-agent/desirecore-cdp-mcp`.
|
|
||||||
|
|
||||||
## Categories
|
|
||||||
|
|
||||||
Valid category slugs are declared in `categories.json`:
|
|
||||||
|
|
||||||
```text
|
|
||||||
productivity, development, business, creative, design, media,
|
|
||||||
communication, research, data, management
|
|
||||||
```
|
|
||||||
|
|
||||||
## Validation
|
## Validation
|
||||||
|
|
||||||
Run these checks before submitting changes:
|
Run commands from the repository root. The scripts use their inline dependency declarations, so a separate application build or Node.js dependency installation is not required for catalog validation.
|
||||||
|
|
||||||
|
### Catalog and translation checks
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Full market + i18n validation
|
# Market statistics, categories, built-in index, entries, sidecars, and skill i18n.
|
||||||
uv run scripts/i18n/validate-i18n.py
|
uv run scripts/i18n/validate-i18n.py
|
||||||
|
|
||||||
# Catalog sidecar validator unit tests and standalone validation
|
# Strict sidecar contracts and complete top-level listing coverage, as required by CI.
|
||||||
|
uv run scripts/catalog/validate_catalog_metadata.py --require-complete
|
||||||
|
|
||||||
|
# Missing or stale translations; no model API calls and no file changes.
|
||||||
|
uv run scripts/i18n/translate.py --check
|
||||||
|
```
|
||||||
|
|
||||||
|
The checks above do not fetch upstream source repositories. Package installation during environment setup may still require network access. A successful schema check is not proof of upstream license validity, external service availability, or successful installation in every client.
|
||||||
|
|
||||||
|
### Focused authoring and validator tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Limit skill-body validation and translation inspection to one existing skill.
|
||||||
|
uv run scripts/i18n/validate-i18n.py skills/web-access
|
||||||
|
uv run scripts/i18n/translate.py --check skills/web-access
|
||||||
|
|
||||||
|
# Run the relevant single-file suite when changing its validator or generator.
|
||||||
|
uv run scripts/i18n/test_validate_i18n.py
|
||||||
uv run scripts/catalog/test_validate_catalog_metadata.py
|
uv run scripts/catalog/test_validate_catalog_metadata.py
|
||||||
uv run scripts/catalog/test_collection_generator.py
|
uv run scripts/catalog/test_collection_generator.py
|
||||||
uv run scripts/catalog/validate_catalog_metadata.py
|
```
|
||||||
|
|
||||||
# Translation freshness check
|
Passing a skill path narrows skill-body validation, but market-level and sidecar checks still run. Choose the relevant test file for your change rather than treating every documentation edit as a reason to run all test suites.
|
||||||
uv run scripts/i18n/translate.py --check
|
|
||||||
|
|
||||||
# Verify pinned collection children without changing entry.json (network required;
|
### Network-dependent checks
|
||||||
# mutable collections are reported and skipped because their output is not reproducible)
|
|
||||||
|
```bash
|
||||||
|
# Compare declared children with pinned upstream collections without rewriting entries.
|
||||||
uv run scripts/gen-collection-children.py --check
|
uv run scripts/gen-collection-children.py --check
|
||||||
|
|
||||||
# Optional network check for entry.json source URLs
|
# Optional source-URL availability checks in addition to normal validation.
|
||||||
uv run scripts/i18n/validate-i18n.py --online
|
uv run scripts/i18n/validate-i18n.py --online
|
||||||
```
|
```
|
||||||
|
|
||||||
The validators check market stats, category references, `builtin-skills.json`,
|
Collection checking requires Git and network access. Mutable collections are reported and skipped because their generated inventory is not reproducible. Omitting `--check` runs the generator in write mode; review both the regenerated children and the corresponding sidecar facts before committing.
|
||||||
`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, Team and Skill.
|
|
||||||
|
|
||||||
Detailed i18n guidance is in [docs/I18N.md](docs/I18N.md).
|
The [validation workflow](.github/workflows/i18n-validate.yml) is the source of truth for CI. It detects relevant paths and can skip catalog validation for documentation-only changes. A green skipped job is not evidence that Markdown links or bilingual documentation were checked; review those separately.
|
||||||
|
|
||||||
|
## Security and trust
|
||||||
|
|
||||||
|
**Official catalog hosting does not make every upstream resource DesireCore-authored, unrestricted, or ready to execute.** Review each resource's provenance, governance, availability, license, and compatibility rather than inferring trust from its directory or display name.
|
||||||
|
|
||||||
|
All contributions must be reusable, customer-neutral, and safe for public indexing. Keep tenant identities, private organization structures, customer-specific prompts, account mappings, credentials, and deployment details in private AgentFS homes, private repositories, or private runtime configuration. The same boundary applies to Git and GitHub metadata.
|
||||||
|
|
||||||
|
A connector or adapter does not bundle, license, install, pay for, or operate the third-party product it accesses. Disclose separately licensed, purchased, hosted, or deployed dependencies in discovery descriptions, compatibility information, localized text, and execution instructions. State operator prerequisites, applicable terms, relevant costs, readiness checks, and safe degraded behavior. When a required dependency is unavailable, stop before the external call and never fabricate success.
|
||||||
|
|
||||||
|
If confidential data is exposed, follow the incident-response policy in [AGENTS.md](AGENTS.md). Removing a current file or rewriting a branch does not by itself remove pull-request references, notifications, caches, or other copies.
|
||||||
|
|
||||||
|
## Related projects
|
||||||
|
|
||||||
|
| Project or guide | Responsibility |
|
||||||
|
| --- | --- |
|
||||||
|
| [DesireCore Registry](https://github.com/desirecore/registry) | Application catalog entries and authorized lifecycle metadata, separate from this Agent/Team/Skill catalog. |
|
||||||
|
| [DesireCore Control listing](https://github.com/desirecore/registry/tree/main/entries/desirecore-control) | Authoritative release source, checksum, compatibility requirements, and installation/uninstallation guide for Control. |
|
||||||
|
| [Control installation guide](docs/desirecore-control.md) | Using the native application from a compatible DesireCore client. |
|
||||||
|
| [Control implementation](https://github.com/desirecore-agent/desirecore-cdp-mcp) | Application source and releases. |
|
||||||
|
|
||||||
|
DesireCore Control is a native application for external agents. Its application listing belongs in Registry, not in a duplicate Skill or internal MCP service entry here. Installing Control does not register internal MCP tools, and publishing a catalog entry does not deploy a compatible desktop client or installation skill. Consult the authoritative listing and guide for current requirements rather than copying a release number into this overview.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT License. See [LICENSE](LICENSE).
|
DesireCore-authored repository content is licensed under the [MIT License](LICENSE). **That license does not override the terms of bundled third-party content or external resources.**
|
||||||
|
|
||||||
|
Read [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), the resource's own license files, and its `license` / `redistribution` metadata. In particular, the notices identify the bundled `docx`, `pdf`, `pptx`, and `xlsx` skills as source-available reference implementations, not MIT-licensed open-source content; other bundled material may use Apache-2.0 or separate terms. External pointers remain governed by their upstream licenses.
|
||||||
|
|
||||||
|
A redistribution mode describes how content is delivered, not a replacement license. Verify the applicable upstream terms before redistribution or production use.
|
||||||
|
|||||||
253
README.zh-CN.md
Normal file
253
README.zh-CN.md
Normal file
@@ -0,0 +1,253 @@
|
|||||||
|
# DesireCore Market
|
||||||
|
|
||||||
|
[English](README.md) | **简体中文**
|
||||||
|
|
||||||
|
**DesireCore 官方 Agent、Team 与 Skill 市场目录，以 Git 进行版本管理。**
|
||||||
|
|
||||||
|
在这里发现可复用的智能体、协作团队和任务技能。本仓库统一维护市场元数据、本地随仓库分发的技能，以及经过整理的上游内容入口，并提供 Schema 和校验工具，支持一致、可核验的内容发布。
|
||||||
|
|
||||||
|
[项目概览](#项目概览) · [快速开始](#快速开始) · [仓库结构](#仓库结构) · [条目格式与契约](#条目格式与契约) · [多语言维护](#多语言维护) · [参与贡献](#参与贡献) · [校验与测试](#校验与测试) · [安全与信任边界](#安全与信任边界) · [相关项目](#相关项目) · [许可证](#许可证)
|
||||||
|
|
||||||
|
## 项目概览
|
||||||
|
|
||||||
|
| 资源类型 | 用途 | 浏览入口 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| **Agent（智能体）** | 具有明确角色、能力和配置的独立助手，以内联元数据或上游指针发布。 | [`agents/`](agents/) |
|
||||||
|
| **Team（团队）** | 由监督者协调的多个智能体，通过指向上游仓库的指针发布，供客户端 fork 安装。 | [`teams/`](teams/) |
|
||||||
|
| **Skill（技能）** | 可复用的任务指令和辅助资源，既可随仓库分发，也可指向上游 Git、Web 或 ZIP 来源。 | [`skills/`](skills/) |
|
||||||
|
|
||||||
|
本仓库是**内容目录，不是独立应用或执行运行时**。市场条目描述资源是什么、来自哪里，以及满足哪些条件才能使用；安装和执行由兼容的 DesireCore 客户端及资源所依赖的环境负责。
|
||||||
|
|
||||||
|
### 目录信息的权威来源
|
||||||
|
|
||||||
|
| 文件 | 定义的内容 |
|
||||||
|
| --- | --- |
|
||||||
|
| [`manifest.json`](manifest.json) | 市场身份、Schema 版本、支持语言、默认语言和汇总统计。 |
|
||||||
|
| [`categories.json`](categories.json) | 合法分类 ID，以及对应的多语言名称与说明。 |
|
||||||
|
| [`builtin-skills.json`](builtin-skills.json) | 本地内置技能 ID 和退役清单。 |
|
||||||
|
| 各条目旁的 `catalog-metadata.v1.json` | 版本化的展示信息、发布信息、来源、治理和兼容性事实。 |
|
||||||
|
|
||||||
|
当前资源清单与数量以 manifest 和实际目录为准，README 不再维护容易过期的第二份统计。`totalSkills` 统计顶层本地 `SKILL.md` 条目与外部 `entry.json` 条目，不逐个累计技能集合中的子技能。没有团队的目录可以省略 `totalTeams`；只要声明该字段，其值就必须与实际目录完全一致。
|
||||||
|
|
||||||
|
分类覆盖效率、开发、商业、创意、设计、媒体、沟通、研究、数据和管理。发布时应使用 `categories.json` 中的分类 ID，不要将本地化显示名称作为 ID。
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 在 DesireCore 中使用市场
|
||||||
|
|
||||||
|
1. 在兼容的 DesireCore 客户端中打开市场，并同步官方目录。
|
||||||
|
2. 安装前阅读资源说明、来源、发布信息、客户端要求、许可证和外部依赖；条目提供使用说明时，一并查看。
|
||||||
|
3. 对可安装条目，按照客户端流程安装，再完成必要的本地配置或授权。凭据和私有配置不得写入本公共仓库。
|
||||||
|
|
||||||
|
**已收录不等于可安装。** 目录可以包含仅供展示的资源；兼容性、治理、来源可复现性或许可条件可能限制安装。同步目录也不会自动升级桌面客户端，或替用户开通第三方服务。
|
||||||
|
|
||||||
|
### 在本地浏览或参与维护
|
||||||
|
|
||||||
|
维护仓库需要 Git、**Python 3.10 或更新版本**以及 `uv`。Python 脚本通过文件内的依赖声明描述运行环境，由 `uv run` 管理。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/desirecore/market.git
|
||||||
|
cd market
|
||||||
|
|
||||||
|
# 校验市场结构和技能多语言内容。
|
||||||
|
uv run scripts/i18n/validate-i18n.py
|
||||||
|
```
|
||||||
|
|
||||||
|
首次准备环境可能需要下载 Python 依赖包。上述校验不需要模型 API 凭据，未指定 `--online` 时也不会获取上游内容。完整覆盖检查、翻译新鲜度检查和定向命令见[校验与测试](#校验与测试)。
|
||||||
|
|
||||||
|
克隆仓库只会下载目录和随仓库分发的文件，不会安装 DesireCore 客户端、智能体、团队或外部产品。
|
||||||
|
|
||||||
|
## 仓库结构
|
||||||
|
|
||||||
|
```text
|
||||||
|
.
|
||||||
|
├── README.md # 英文概览与贡献指南
|
||||||
|
├── README.zh-CN.md # 对应的简体中文文档
|
||||||
|
├── manifest.json # 市场元数据、语言与统计
|
||||||
|
├── categories.json # 分类注册表
|
||||||
|
├── builtin-skills.json # 内置技能与退役策略
|
||||||
|
├── agents/<id>/
|
||||||
|
│ ├── agent.json 或 entry.json # 主条目文件必须二选一
|
||||||
|
│ ├── catalog-metadata.v1.json # 版本化目录元数据
|
||||||
|
│ └── USAGE[.<locale>].md # 内联智能体的可选使用说明
|
||||||
|
├── teams/<id>/
|
||||||
|
│ ├── entry.json # 仅支持上游 Git fork 指针
|
||||||
|
│ └── catalog-metadata.v1.json
|
||||||
|
├── skills/<id>/
|
||||||
|
│ ├── SKILL.md 或 entry.json # 本地技能或外部来源指针
|
||||||
|
│ ├── catalog-metadata.v1.json
|
||||||
|
│ ├── SKILL.<locale>.md # 本地技能的多语言正文
|
||||||
|
│ ├── references/ # 可选的扩展文档
|
||||||
|
│ └── scripts/ # 可选的技能辅助脚本
|
||||||
|
├── schemas/ # 目录契约及导出的客户端契约
|
||||||
|
├── scripts/
|
||||||
|
│ ├── catalog/ # 目录校验与定向测试
|
||||||
|
│ ├── i18n/ # 多语言 Schema、校验与翻译
|
||||||
|
│ └── gen-collection-children.py # 上游技能集合清单生成器
|
||||||
|
├── docs/ # 编写指南与应用说明
|
||||||
|
├── .github/workflows/ # 校验、翻译和评审自动化
|
||||||
|
├── AGENTS.md / CLAUDE.md # 内容等价的仓库贡献规范
|
||||||
|
├── LICENSE # 仓库原创内容的许可证
|
||||||
|
└── THIRD_PARTY_NOTICES.md # 第三方许可的补充说明
|
||||||
|
```
|
||||||
|
|
||||||
|
目录树展示的是支持的组织形式，并非每个目录都必须包含全部文件。多语言正文、辅助脚本和扩展文档属于本地技能；外部指针的实现保留在上游。团队目录只放 `entry.json` 和对应的 sidecar，不放内联 `team.json`。
|
||||||
|
|
||||||
|
## 条目格式与契约
|
||||||
|
|
||||||
|
以 Schema 和已有条目作为实现参考。精简的 JSON 示例不能替代完整客户端契约。
|
||||||
|
|
||||||
|
### 本地技能
|
||||||
|
|
||||||
|
本地技能位于 `skills/<id>/SKILL.md`，由 YAML frontmatter 和 Markdown 指令正文组成。顶层 `name` 必须与目录的小写 ASCII slug 一致；多语言显示名称放在 `metadata.i18n` 中。
|
||||||
|
|
||||||
|
只有 `SKILL.md` 包含 frontmatter。`SKILL.<locale>.md` 仅包含对应语言正文，以匹配的语言注释开头，并由 i18n 元数据引用。例如，`SKILL.zh-CN.md` 的首行是 `<!-- locale: zh-CN -->`。市场技能的 `disable-model-invocation` 只能设为 `true` 或省略，`false` 会被拒绝。
|
||||||
|
|
||||||
|
每个本地内置技能都必须登记到 `builtin-skills.json.skills`，提供 sidecar，并使用有效分类。参考 [frontmatter Schema](scripts/i18n/schema/skill-frontmatter.schema.json)、[联网访问技能](skills/web-access/SKILL.md)和[多语言作者指南](docs/I18N.md)。
|
||||||
|
|
||||||
|
`retired` 用于声明客户端可在启动时退役的旧内置技能。客户端只删除同时满足以下条件的副本：由 `skills.lock` 记录为市场或随包内容，且 `SKILL.md` 哈希仍与安装记录一致。手动安装或经过本地修改的副本会被保留。同一个 ID 不得同时出现在 `skills` 和 `retired` 中。
|
||||||
|
|
||||||
|
### 外部技能与技能集合
|
||||||
|
|
||||||
|
外部技能使用 `skills/<id>/entry.json` 描述上游来源、展示信息、维护者、分类、许可证和再分发方式。技能条目必须提供内联 SVG `icon`，来源支持 `git`、`web` 和 `zip`。外部条目计入 `manifest.stats.totalSkills`，但不进入内置技能索引。
|
||||||
|
|
||||||
|
技能集合通过一个市场条目组织多个上游技能，并声明 `children` 清单供发现和展示。子技能的元数据保留在父条目的 sidecar 中；每个子技能都有独立的 `skill + parentId + id` 身份和发布事实。父条目的版本可以未知，不得用父版本推断子技能版本。
|
||||||
|
|
||||||
|
参考[飞书 CLI 条目](skills/larksuite-cli/entry.json)及其 [sidecar](skills/larksuite-cli/catalog-metadata.v1.json)。[集合生成器](scripts/gen-collection-children.py)从上游 `SKILL.md` 提取子技能，`--check` 模式只验证固定版本、可复现的集合，不重写条目。
|
||||||
|
|
||||||
|
### 智能体
|
||||||
|
|
||||||
|
智能体目录必须包含一个主文件：内联元数据 `agent.json` **或**外部指针 `entry.json`，并同时提供 `catalog-metadata.v1.json`。主文件缺失或两种主文件同时存在均不合法。
|
||||||
|
|
||||||
|
对外部指针，目录 slug、`entry.id` 和 sidecar 的 `identity.id` 必须一致，`identity.kind` 为 `agent`。上游 AgentFS 的 `agent.json.id` 是独立 UUID，不得为了匹配市场目录而改写。
|
||||||
|
|
||||||
|
指针原始数据必须先通过[导出的智能体客户端 Schema](schemas/market-agent-entry.client.schema.json)，再进行 sidecar 校验。版本字段保留客户端要求的类型与格式。`installPolicy` 和 `updatePolicy` 必须同时缺省，或构成受支持的完整组合；双缺省时的有效策略为 `market/market`，sidecar 不得将其改成系统条目。
|
||||||
|
|
||||||
|
`latestVersion` 映射到 `release.version`；客户端要求、策略和来源字段必须在指针与 sidecar 之间保持一致；`maintainer` 映射到 `upstreamMaintainer`。可安装指针自身必须在 `source.ref` 中固定完整 Git 提交，或在 `source.sha256` 中固定 Web/ZIP 摘要，仅在 sidecar 中声明固定版本不够。智能体指针不适用内置技能在来源、许可或审查要求上的例外。
|
||||||
|
|
||||||
|
内联智能体可以提供简短、纯文本的 `USAGE.md`，说明前置条件、授权步骤和安全边界。多语言版本使用 `USAGE.<locale>.md`，回退顺序为请求语言 → 源语言 → 默认语言 → 无后缀文件。使用说明独立展示，不混入同时会进入智能体运行上下文的 `fullDesc`。客户端可能截断过长内容；详细资料应放入技能的 `references/`。使用说明中的相对路径图片不会渲染。
|
||||||
|
|
||||||
|
参考 [DesireCore 内联智能体](agents/desirecore/agent.json)和[钉钉工作台指针](agents/dingtalk-workspace/entry.json)。
|
||||||
|
|
||||||
|
### 团队
|
||||||
|
|
||||||
|
团队由监督者协调多个智能体，**只能以 Git fork 指针发布**：在 `teams/<id>/entry.json` 中登记来源，并提供 sidecar。团队实现，即 `team.json`、`members.json` 和 `shared/`，保留在上游；安装时 fork 该仓库并安装其声明的成员，之后通过 fork 仓库中的 `git pull` 更新。
|
||||||
|
|
||||||
|
因此，`source.kind` 必须为 `git`，必须提供 `source.repoUrl`，可安装指针还必须以 `source.ref` 固定完整提交 SHA。分支和标签可移动，不能满足不可变锁定要求。团队没有 `installPolicy` / `updatePolicy` 组合；即使上游使用宽松许可证，`redistribution` 仍为 `source-pointer-only`。
|
||||||
|
|
||||||
|
指针原始数据必须通过[导出的团队客户端 Schema](schemas/market-team-entry.client.schema.json)。目录 slug、`entry.id` 和 sidecar 的 `identity.id` 必须一致；`identity.kind` 为 `team`，`latestVersion` 映射到 `release.version`，来源字段必须与 `provenance.content` 指向同一制品。
|
||||||
|
|
||||||
|
`supervisorName`、`supervisorAgentId`、`memberCount`、`memberNames`、`requiredSkills` 和 `requiredClientVersion` 与 sidecar 进行双向一致性校验：既不能丢弃已声明事实，也不能补出原指针没有的事实。成员与监督者的展示元数据不具有安装或权限授权效力；这些事实应从 fork 后的 `team.json` 和 `members.json` 中解析。
|
||||||
|
|
||||||
|
智能体与团队卡片使用 `avatar`，而不是技能卡片的 `icon`。即使共享条目契约接受 `icon`，该字段也不会进入这些卡片，校验器会给出警告。参考[合同审查团队条目](teams/contract-review-team/entry.json)。
|
||||||
|
|
||||||
|
### 版本化目录元数据
|
||||||
|
|
||||||
|
每个顶层条目都必须在主文件旁的固定位置提供 `catalog-metadata.v1.json`。这个伴随元数据文件称为 **sidecar**，用于补充旧客户端兼容文件，而不是替代 `agent.json`、`entry.json` 或 `SKILL.md`。新客户端通过确定性适配器合并信息；重复字段不一致时，校验器直接拒绝，而不是静默选择其中一份。
|
||||||
|
|
||||||
|
[目录元数据 Schema](schemas/catalog-metadata.v1.schema.json)覆盖展示、发布、显式时间事实、内容来源、治理、兼容性及类型专属信息。必须保持以下边界：
|
||||||
|
|
||||||
|
- **来源事实与运行时事实分离。** sidecar 不能自报可信目录身份 `catalogSourceId`、目录提交/路径/信任等级、最终官方身份、安装状态、设备状态、健康状态、运行时发现的 URL 或 `syncedAt`。可信目录来源和运行时观察由 DesireCore 注入。
|
||||||
|
- **证据路径跟随实际内容。** 对随仓库分发的内容，`license.evidencePath`、`compliance.licenseEvidencePath` 和 `compliance.noticePath` 相对于条目目录解析，且文件必须真实存在。对指针，这些路径指向上游快照；离线校验无法获取该证据，并会对未固定来源的证据声明给出警告。
|
||||||
|
- **未知也是有效事实。** 使用显式 `known` / `unknown` 状态。已知日期使用 `YYYY-MM-DD` 和 `precision: "day"`；已知秒级时间使用以 `Z` 结尾的 RFC 3339 UTC 时间戳和 `precision: "second"`。不得用当前日期、克隆时间或同步时间填补未知的发布或目录时间。
|
||||||
|
|
||||||
|
智能体与团队客户端 Schema 是生成的兼容性快照，其 `$comment` 记录上游来源提交和 blob。兼容性变更时，应从相应 TypeScript 导出重新生成，不得放宽契约或用仅校验 sidecar 的方式替代。
|
||||||
|
|
||||||
|
## 多语言维护
|
||||||
|
|
||||||
|
市场语言由 `manifest.json.supportedLocales` 声明，目前为 `en-US` 和 `zh-CN`，默认语言为英文。本地技能显示文案放在 `metadata.i18n`；条目 JSON 和 sidecar 使用各自 Schema 定义的 i18n 结构，不能混用字段名称。
|
||||||
|
|
||||||
|
技能正文按照请求语言、源语言、默认语言的顺序回退。默认语言正文保留在 `SKILL.md` 中，其他正文通过路径明确引用，各语言的标题结构需要一致。[术语表](scripts/i18n/glossary.json)维护共享术语。
|
||||||
|
|
||||||
|
[翻译工作流](.github/workflows/i18n-translate.yml)使用已配置的模型凭据，处理符合条件的缺失或过期技能译文。生成后仍需人工检查术语、结构和事实准确性，自动化不能替代评审。`translated_by: human` 会锁定译文，阻止自动覆盖；源内容变更后，应先人工同步该译文，再在审查通过后更新 `source_hash`，不得伪造哈希来消除过期检查失败。
|
||||||
|
|
||||||
|
`translate.py --check` 只检查新鲜度，不调用模型 API，也不重写译文。后端配置和编写流程见[多语言作者指南](docs/I18N.md)；当前执行行为以工作流和脚本为准。两份 README 需要人工同步维护，不属于技能翻译流水线的输入。
|
||||||
|
|
||||||
|
## 参与贡献
|
||||||
|
|
||||||
|
欢迎新增可复用资源、完善现有条目、纠正元数据、增强校验，以及改进翻译与文档。
|
||||||
|
|
||||||
|
1. **确认内容归属。** 智能体、团队和技能放在本仓库；应用条目放在 [DesireCore Registry](https://github.com/desirecore/registry)。修改前阅读 [AGENTS.md](AGENTS.md) 或 [CLAUDE.md](CLAUDE.md)。
|
||||||
|
2. **基于最新 `main` 开始工作。** 使用职责单一的分支或独立 worktree，选择正确的条目形态、稳定的公开 slug 和有效分类。参考已有条目时，不要照搬其身份、审查状态或许可声明。
|
||||||
|
3. **提交完整且一致的条目。** 保持主文件与 sidecar 一致，提供多语言、来源、许可证据、兼容性和外部依赖说明。新增本地技能时更新 `builtin-skills.json`，资源清单变化时更新 `manifest.json` 统计；不要编造未知的日期或版本。
|
||||||
|
4. **发布前完成检查。** 运行下文适用的校验、审查译文，并遵循仓库规范中的私密词表与公开信息检查要求。扫描完整工作树，包括除 `.git` 外的隐藏文件，同时检查新增路径、分支名、提交信息和拟发布的 PR 文本。保密检索词必须保留在仓库外。
|
||||||
|
5. **向 `main` 提交 Pull Request。** 说明可复用场景、来源与许可选择、兼容性影响和已执行校验。示例保持通用；修改本指南时同步两种语言；合并前完成必需检查与评审。
|
||||||
|
|
||||||
|
目录错误、失效指针或文档问题可通过 [Issue](https://github.com/desirecore/market/issues) 反馈，提供条目 ID、相关客户端版本、预期行为和脱敏复现信息。上游实现问题应酌情反馈给上游项目。公开 Issue 中不得包含凭据、客户私有数据或保密事件证据。
|
||||||
|
|
||||||
|
## 校验与测试
|
||||||
|
|
||||||
|
从仓库根目录运行命令。脚本使用文件内的依赖声明，目录校验不需要先构建应用或安装 Node.js 项目依赖。
|
||||||
|
|
||||||
|
### 目录与翻译检查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 校验市场统计、分类、内置索引、条目、sidecar 和技能多语言内容。
|
||||||
|
uv run scripts/i18n/validate-i18n.py
|
||||||
|
|
||||||
|
# 严格校验 sidecar，并按 CI 要求检查所有顶层条目的完整覆盖。
|
||||||
|
uv run scripts/catalog/validate_catalog_metadata.py --require-complete
|
||||||
|
|
||||||
|
# 检查缺失或过期译文，不调用模型 API，也不改写文件。
|
||||||
|
uv run scripts/i18n/translate.py --check
|
||||||
|
```
|
||||||
|
|
||||||
|
以上检查不会拉取上游来源仓库，但首次准备运行环境、安装依赖时仍可能需要联网。Schema 校验成功不代表上游许可已经核实、外部服务当前可用，或所有客户端都能成功安装。
|
||||||
|
|
||||||
|
### 定向编写检查与校验器测试
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 只检查一个现有技能的正文和翻译状态。
|
||||||
|
uv run scripts/i18n/validate-i18n.py skills/web-access
|
||||||
|
uv run scripts/i18n/translate.py --check skills/web-access
|
||||||
|
|
||||||
|
# 修改校验器或生成器时，选择运行对应的单文件测试。
|
||||||
|
uv run scripts/i18n/test_validate_i18n.py
|
||||||
|
uv run scripts/catalog/test_validate_catalog_metadata.py
|
||||||
|
uv run scripts/catalog/test_collection_generator.py
|
||||||
|
```
|
||||||
|
|
||||||
|
传入技能路径只缩小技能正文的校验范围，市场级与 sidecar 检查仍会执行。应根据改动选择相关测试文件，而不是每次修改文档都运行全部测试。
|
||||||
|
|
||||||
|
### 需要联网的检查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 对照固定版本的上游集合检查 children，不重写条目。
|
||||||
|
uv run scripts/gen-collection-children.py --check
|
||||||
|
|
||||||
|
# 可选：在常规校验之外检查来源 URL 是否可访问。
|
||||||
|
uv run scripts/i18n/validate-i18n.py --online
|
||||||
|
```
|
||||||
|
|
||||||
|
集合检查需要 Git 和网络。可变来源集合会被报告并跳过，因为无法保证生成清单可复现。省略 `--check` 会进入写入模式；提交前应同时检查重新生成的子技能和对应 sidecar 事实。
|
||||||
|
|
||||||
|
[校验工作流](.github/workflows/i18n-validate.yml)是 CI 行为的权威来源。它会检测相关路径，纯文档改动可能跳过目录校验。跳过后显示成功的任务，不代表 Markdown 链接或中英文文档已被检查；这些内容仍需单独审查。
|
||||||
|
|
||||||
|
## 安全与信任边界
|
||||||
|
|
||||||
|
**由官方目录收录，不代表每个上游资源都由 DesireCore 编写、没有使用限制，或已经具备执行条件。** 应检查条目的来源、治理、可用性、许可证和兼容性，不能仅凭目录位置或显示名称推断信任。
|
||||||
|
|
||||||
|
所有贡献都必须可复用、不依赖特定客户，并适合公开索引。租户身份、私有组织结构、客户专属提示词、账号映射、凭据和部署细节只能保留在私有 AgentFS home、私有仓库或私有运行配置中。Git 与 GitHub 元数据同样受此边界约束。
|
||||||
|
|
||||||
|
连接器或适配器不等于已经打包、授权、安装、付费或托管它连接的第三方产品。依赖另行许可、购买、托管或部署的软件时，必须在发现描述、兼容性信息、多语言文案和执行指令中披露，并说明操作者前置条件、适用条款、相关费用、就绪检查和安全降级行为。必要依赖不可用时，应在外部调用前停止，不得伪造成功结果。
|
||||||
|
|
||||||
|
发生保密数据暴露时，按照 [AGENTS.md](AGENTS.md) 中的事件响应流程处理。删除当前文件或重写分支，本身并不能移除 PR 引用、通知、缓存或其他副本。
|
||||||
|
|
||||||
|
## 相关项目
|
||||||
|
|
||||||
|
| 项目或指南 | 职责 |
|
||||||
|
| --- | --- |
|
||||||
|
| [DesireCore Registry](https://github.com/desirecore/registry) | 应用目录及经过授权的生命周期元数据，与本仓库的 Agent/Team/Skill 目录分离。 |
|
||||||
|
| [DesireCore Control 条目](https://github.com/desirecore/registry/tree/main/entries/desirecore-control) | Control 发布来源、校验和、兼容性要求及安装/卸载指南的权威入口。 |
|
||||||
|
| [Control 安装说明](docs/desirecore-control.zh-CN.md) | 在兼容 DesireCore 客户端中使用该原生应用的说明。 |
|
||||||
|
| [Control 实现仓库](https://github.com/desirecore-agent/desirecore-cdp-mcp) | 应用源码与发布版本。 |
|
||||||
|
|
||||||
|
DesireCore Control 是面向外部智能体的原生应用，其应用条目属于 Registry，不应在此重复创建 Skill 或内部 MCP 服务条目。安装 Control 不会注册内部 MCP 工具，发布目录条目也不会自动部署兼容的桌面客户端或安装技能。当前要求以权威条目和安装指南为准，不在本概览中重复维护具体发布版本号。
|
||||||
|
|
||||||
|
## 许可证
|
||||||
|
|
||||||
|
DesireCore 编写的仓库原创内容采用 [MIT License](LICENSE)。**该许可证不会覆盖随仓库分发的第三方内容或外部资源自身的条款。**
|
||||||
|
|
||||||
|
使用前阅读 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)、资源自身的许可文件，以及 `license` / `redistribution` 元数据。特别是，第三方声明将随仓库分发的 `docx`、`pdf`、`pptx` 和 `xlsx` 技能列为源码可见的参考实现，而非 MIT 许可的开源内容；其他随仓库分发的内容可能使用 Apache-2.0 或独立条款。外部指针始终受上游许可证约束。
|
||||||
|
|
||||||
|
再分发模式描述内容如何交付，不能替代许可证。再分发或用于生产环境前，应核实适用的上游条款。
|
||||||
Reference in New Issue
Block a user