# Channel Adapter Contract

Each publishing channel is an independent adapter. A multi-channel request runs
selected adapters separately and aggregates evidence only at the end. When the
user does not name a channel, select only the Skill Publisher adapter for the
LovStudio official website. Select all supported channels only after an explicit
all-channel or multi-platform request.

## Required adapter fields

Before implementing or executing a new adapter, establish:

1. Stable channel ID and current official display name.
2. Official documentation and public product URL.
3. Whether the result is a package, personal-library import, private listing,
   public marketplace listing, or live hosted page.
4. Required account, credentials, source locator, metadata, icon, examples, and
   commercial fields.
5. The `lov-skill-pricing` Pricing Card that supplies the shared public price,
   billing model, free/paid funnel, confidence, evidence gaps, and review trigger.
6. Delivery mode: free source, protected encrypted bundle, or explicitly public
   paid source. Paid catalog visibility by itself is not an installable delivery.
7. Entitlement behavior: explicit Skill grants are fixed, while scopes named
   `global` or `all` dynamically cover every currently listed Skill and must not
   be expanded into a snapshot of current IDs.
8. Deterministic preparation and validation commands.
9. External actions such as repository creation, upload, review, or submission.
10. Observable completion evidence and rollback path.

## Adapter directory convention

Keep channel state outside canonical Skill source:

```text
<publisher-profile-root>/
└── <channel-id>/
    └── <skill-name>/
        ├── metadata.json
        ├── icon.svg
        └── release.json

<publisher-output-root>/
└── <channel-id>/<skill-name>/<version>/
```

Do not add platform frontmatter, credentials, upload state, or generated archives
to the source repository.

## Execution states

- `prepared`: metadata and artifacts exist locally and pass local validation.
- `uploaded`: bytes reached a target account or submission endpoint.
- `installed`: a personal library shows the Skill as usable.
- `listed`: a marketplace record exists.
- `live`: intended users can access the expected public version.
- `verified`: the adapter-specific completion gate passed.

Never collapse these states into a generic success label.

## Adding a channel

Use current official sources when platform names, URLs, schemas, review policies,
or APIs may have changed. Add one focused reference and deterministic helper only
after the official contract and completion signal are known. Illustrative user
names for a platform are discovery clues, not final identifiers.

# Publishing to Skill Publisher

This adapter turns validated local source into a GitHub-backed Skill Publisher release,
catalog entry, and verified live detail page.

## Inputs

- Local Skill source path.
- GitHub organization and desired repository visibility.
- The current `lov-skill-pricing` Pricing Card, including free/paid status,
  public CNY price or free-entry decision, confidence, and review trigger.
- The intended delivery mode for a paid Skill: protected encrypted bundle or
  explicitly public source.
- Unified `lovstudio/skills` catalog checkout.
- Expected version and a release-specific visible marker.
- Revalidation secret resolved as `LOVSTUDIO_REVALIDATE_SECRET` without printing it.

## Source repository and release

From the validated source directory:

```bash
python3 scripts/validate_skill.py .
git init -b main                         # only when source has no repository
git add -A
git commit -m "feat: initial release"
gh repo create ORG/NAME-skill --VISIBILITY --source=. --push
git tag vVERSION
git push origin vVERSION
gh release create vVERSION --generate-notes
```

For an existing repository, preserve its branch and history, update from the
remote first, commit only intended changes, then tag from the verified commit.

## Paid delivery contract

Resolve paid delivery before changing the catalog:

- **Protected delivery:** set `encrypted_bundle: true`; generate and locally
  decrypt the current-version bundle; register its server-side version manifest
  and key; copy the placeholder, `MANIFEST.enc.json`, and ciphertext into the
  catalog mirror. Never print or commit the decryption key.
- **Public-source delivery:** use only when the user explicitly keeps the paid
  Skill's source public. Set `public_source: true`, keep the repository public,
  and let the CLI install from the catalog-declared `repo` after its normal
  account ownership or Credits check. This mode provides no source secrecy and
  must not be described as encrypted protection.

Block publication when `paid: true` has neither a complete encrypted bundle nor
explicit `public_source: true`. A paid card, synced Credits price, or live detail
page is not delivery evidence.

## License entitlement contract

- `global` and `all` mean a dynamic license scope: while the license is active,
  they include every Skill that is currently listed in the canonical catalog.
- A new Skill becomes available to existing global licenses during catalog sync;
  no per-license grant row, Credits balance, or repurchase is required.
- A delisted Skill leaves the dynamic global scope. Explicit historical
  per-Skill purchases remain fixed unless their own license is revoked.
- Never implement `global` by materializing the current catalog into a fixed
  list of Skill IDs. Catalog sync must maintain the listed/delisted state that
  the entitlement resolver reads.
- Publication verification for a new paid Skill must cover three paths: a
  dynamic global license installs without Credits, an explicit owner installs
  without duplicate Credits, and an unentitled account reaches the purchase
  confirmation before source download.

## Catalog registration

Use the unified `lovstudio/skills` catalog; the former split General and Dev
catalogs are archived. Choose the entry category from product policy, not source
location. Transform the current Pricing Card's public fields into the catalog
manifest; do not independently invent or revise a price in this adapter. Add the
repository, version, category, description, and paid status, then run the
catalog's official mirror/render/validation scripts. Merge the catalog change
into its `main` branch before live revalidation.

For a public-source paid Skill, add `public_source: true` and keep it out of the
aggregate plaintext mirror; the CLI installs the declared source repository
directly after entitlement. For a protected paid Skill, add
`encrypted_bundle: true` only after the committed encrypted files and registered
server version are both ready.

For generated aggregate catalogs, update metadata and run their official sync
and render scripts. Do not hand-edit generated mirror directories.

## Revalidate

Replace `NAME` and the site URL with configured values:

```bash
test -n "$LOVSTUDIO_REVALIDATE_SECRET"

curl -fsS -X POST "SITE_URL/api/revalidate" \
  -H "x-revalidate-secret: $LOVSTUDIO_REVALIDATE_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "tags":[
      "skills-index",
      "skills-index:lovstudio",
      "skills-updates",
      "skill:NAME",
      "skill-cases:NAME"
    ],
    "paths":["/skills","/skills/NAME","/agent"]
  }'
```

## Verify the visible result

```bash
curl -fsS -o /tmp/lov-skill-page.html \
  -w '%{http_code}\n' "SITE_URL/skills/NAME"
rg -n 'Version|EXPECTED_VERSION|EXPECTED_MARKER' \
  /tmp/lov-skill-page.html
```

Completion requires the intended catalog to list the Skill, the detail page to
return HTTP 200, the visible version plus marker to match the release, and the
exact catalog install command to pass from a clean isolated directory. For paid
delivery, verify with an already-owned test account so the run proves source
selection without a duplicate purchase.

# Alipay SkillPay Distribution Standard

Use this adapter when the user selects 支付宝 SkillPay or requests all configured
channels. SkillPay is a paid-product submission channel: packaging, upload,
parsing, form submission, review, and live listing are separate states.

## Inputs

- A canonical Skill source that passes `scripts/validate_skill.py`.
- Product title and concise user-facing description.
- Public CNY price from the current `lov-skill-pricing` Pricing Card. When the
  user supplied an explicit price, the card preserves it as a publishing
  constraint and explains any difference from its model recommendation.
- Current version and source locator for release traceability.
- An authenticated SkillPay merchant session.

## Product package

Create the archive outside canonical source. Use one root directory named after
the Skill and include the complete runnable source while excluding `.git`, local
credentials, caches, build outputs, and channel profiles. Test the ZIP before
upload and record its SHA-256 checksum.

## Submission workflow

1. Open `https://skillpay.alipay.com/ais/products` in the configured merchant
   browser session.
2. Start a new product submission and select the Skill ZIP through the page's
   file chooser.
3. Wait until the page explicitly reports that Skill parsing has completed.
4. Review parsed metadata, then fill the public title, description, and exact CNY
   price from the release manifest generated from the current Pricing Card.
5. Submit the form and wait for the product-success notice.
6. Re-open the product list and record whether the product is reviewing or live.

Do not expose browser credentials, session data, or merchant identifiers in
logs. Do not report `review` before the form submission succeeds, and do not
report `live` until the public product state shows it.

## Completion evidence

- `prepared`: ZIP integrity, file count, and checksum recorded.
- `uploaded`: the page reports parsing completed.
- `review`: the submission success notice is visible and the product appears in
  the merchant list with a review state.
- `live`: the marketplace exposes a purchasable public product entry.

# Publisher User Configuration

Publishing needs persistent channel settings, while secrets remain in environment
variables or credential stores.

## First-run initialization

1. Prefill source roots and target accounts from the current request.
2. Read environment variables and the shared profile.
3. Infer safe local output directories.
4. Ask once only for required channel values still missing.
5. Show non-secret values before saving them to the profile.

## Shared profile

```bash
${SKILL_PROFILE_PATH:-$HOME/.skill-publisher/skills/profile.json}
```

Recommended shape:

```json
{
  "publisher": {
    "github_org": "YOUR_ORG",
    "default_visibility": "private",
    "output_dir": "$HOME/Documents/skill-releases",
    "skill-publisher": {
      "catalog": "$HOME/projects/skills",
      "catalog_repo": "lovstudio/skills",
      "site_url": "https://example.com/skills"
    },
    "workbuddy": {
      "profile_dir": "$HOME/.skill-publisher/skills/publish/workbuddy"
    }
  }
}
```

## Secret handling

- Use `gh auth` for GitHub credentials.
- Resolve revalidation and platform tokens from environment or a credential store.
- Never print, persist into the shared JSON profile, or copy secrets into source.
- Channel adapters should name the missing environment variable without echoing
  its value.

# WorkBuddy（CodeBuddy 开放平台）发布标准

This adapter builds a self-contained Connector ZIP from portable local source.
Platform metadata, icon, staging directory, and archives stay outside source.

## Inputs

```text
<local-source>/
├── SKILL.md
├── README.md
├── kit.yaml                 # Skill Kit only
└── skills/                  # Skill Kit only

<publisher-profile>/workbuddy/<skill-name>/
├── connector-meta.json
└── icon.svg
```

`connector-meta.json` includes:

- `name`, `name_zh`, `name_en`
- `description`, `description_zh`, `description_en`
- globally unique kebab-case `source`
- `type: "skill-only"`
- SemVer `version`
- `source_type` plus one supported source locator
- two to five Chinese and English examples
- `minWorkbuddyVersion` when a version-gated field is used

For an update to an existing WorkBuddy listing whose historical internal Skill
ID differs from the canonical source ID, set optional `raw_name` to that exact
legacy ID. The builder applies it only to the root WorkBuddy package directory
and frontmatter; canonical source and user-facing display names stay unchanged.

Display names should contain 2–20 characters. Chinese and English descriptions
should each contain 20–100 characters and describe the user outcome.

## Package transformation

The builder copies portable source to staging and converts package frontmatter
to WorkBuddy fields without mutating canonical source. For Skill Kits, every
declared module is included and every named pipeline must reference known module
IDs.

## Build

Choose a new output path for each build:

```bash
python3 "$SKILL_DIR/scripts/build_workbuddy.py" SOURCE \
  --meta PUBLISHER_PROFILE/connector-meta.json \
  --icon PUBLISHER_PROFILE/icon.svg \
  --output-dir OUTPUT_DIR
```

The builder emits a combined Connector ZIP and individual Skill ZIPs, validates
the staged package, and rejects broken references, private paths, placeholders,
caches, compiled Python artifacts, missing metadata, or missing modules.

## Evidence

## CodeBuddy 上架

1. 打开 `https://www.codebuddy.cn/open/console/dashboard`，选择“上架新 Skill”。
2. 上传 builder 输出的 `*-individual/<skill-name>.zip`；聚合 Connector ZIP 不用于单项上架。
3. 等待“解析成功”，填写中英文展示名与用户价值描述，提交审核。
4. 记录审核中、已上架或已驳回状态；微信群审核沟通不等同于公开上架证据。

Record source version and commit when available, source and package validation,
ZIP paths and SHA-256 checksums, archive listing, module count, metadata, and icon
presence.

`prepared` means the package exists and passes local gates. If personal-library
import is requested, continue until the installed list shows the Skill. Public
marketplace publication requires separate evidence from the public marketplace.

#!/usr/bin/env python3
"""Build a self-contained WorkBuddy Connector ZIP from local Skill source."""

from __future__ import annotations

import argparse
import hashlib
import json
import shutil
import sys
import zipfile
from pathlib import Path
from typing import Any

try:
    from validate_skill import (
        ValidationFailure,
        compact_text,
        split_frontmatter,
        validate_connector_meta,
        validate_source,
        validate_workbuddy_package,
    )
except ImportError as exc:
    print(
        "ERROR: scripts/validate_skill.py must be present next to this builder",
        file=sys.stderr,
    )
    raise SystemExit(2) from exc


RESOURCE_DIRS = ("assets", "cases", "prompts", "references", "scripts", "skills")
RESOURCE_FILES = ("kit.yaml",)
SKIP_DIRS = {".git", "dist", ".venv", "venv", "node_modules", "__pycache__"}
SKIP_FILES = {
    ".DS_Store",
    "build_workbuddy.py",
    "validate_skill.py",
}
SKIP_SUFFIXES = {".pyc", ".pyo"}
PUBLISHER_SOURCE = Path(__file__).resolve().parent.parent


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "source",
        nargs="?",
        type=Path,
        default=Path.cwd(),
        help="Skill source repository (default: current directory)",
    )
    parser.add_argument(
        "--meta",
        type=Path,
        required=True,
        help="External WorkBuddy connector-meta.json",
    )
    parser.add_argument(
        "--icon",
        type=Path,
        required=True,
        help="External market icon (.svg, .png, .jpg, or .jpeg)",
    )
    parser.add_argument(
        "--output-dir",
        type=Path,
        required=True,
        help="New staging directory to create",
    )
    parser.add_argument(
        "--zip-path",
        type=Path,
        help="ZIP destination (default: OUTPUT_DIR.zip)",
    )
    parser.add_argument(
        "--individual-dir",
        type=Path,
        help="Directory for independently installable Skill ZIPs",
    )
    return parser.parse_args()


def fail_on_errors(errors: list[str], label: str) -> None:
    if errors:
        raise ValueError(f"{label} failed:\n- " + "\n- ".join(errors))


def ignore_resources(_directory: str, names: list[str]) -> set[str]:
    ignored = set()
    for name in names:
        path = Path(name)
        if (
            name in SKIP_DIRS
            or name in SKIP_FILES
            or path.suffix.lower() in SKIP_SUFFIXES
        ):
            ignored.add(name)
    return ignored


def copy_source_resources(source: Path, target: Path) -> None:
    shutil.copy2(source / "SKILL.md", target / "SKILL.md")
    for filename in RESOURCE_FILES:
        candidate = source / filename
        if candidate.is_file():
            shutil.copy2(candidate, target / filename)
    for dirname in RESOURCE_DIRS:
        candidate = source / dirname
        if candidate.is_dir():
            # The publisher is itself a distributable Skill. Its validation and
            # WorkBuddy-builder scripts are runtime dependencies, while those
            # same files remain distribution tooling for every other Skill.
            ignore = None if source.resolve() == PUBLISHER_SOURCE else ignore_resources
            shutil.copytree(
                candidate,
                target / dirname,
                ignore=ignore,
            )


def make_module_self_contained(source: Path, target: Path) -> None:
    """Copy shared kit resources into a standalone module package.

    The combined entrypoint keeps `$KIT_DIR` semantics. WorkBuddy also emits
    every module as an independently installable Skill, so those siblings need
    their own copy of shared references/assets/scripts and local `$SKILL_DIR`
    references.
    """
    for dirname in ("assets", "cases", "prompts", "references", "scripts"):
        candidate = source / dirname
        if candidate.is_dir():
            shutil.copytree(
                candidate,
                target / dirname,
                dirs_exist_ok=True,
                ignore=ignore_resources,
            )
    for path in target.rglob("*.md"):
        original = path.read_text(encoding="utf-8")
        updated = original.replace("$KIT_DIR/", "$SKILL_DIR/")
        if updated != original:
            path.write_text(updated, encoding="utf-8")


def workbuddy_frontmatter(
    source_skill: Path,
    connector: dict[str, Any],
    root_source_name: str,
) -> tuple[str, str]:
    data, body = split_frontmatter(source_skill)
    metadata = data.get("metadata")
    if not isinstance(metadata, dict):
        raise ValidationFailure(f"{source_skill}: metadata must be a mapping")
    source_name = compact_text(data.get("name"))
    raw_name = compact_text(connector.get("raw_name"))
    package_name = (
        raw_name
        if raw_name and source_name == root_source_name
        else source_name
    )
    fields: list[tuple[str, str]] = [
        ("name", package_name),
        ("description", compact_text(data.get("description"))),
        ("version", compact_text(metadata.get("version"))),
        ("author", compact_text(metadata.get("author"))),
        ("source_type", compact_text(connector.get("source_type"))),
    ]
    for locator in ("clawhub_slug", "skillhub_slug", "git_url"):
        value = compact_text(connector.get(locator))
        if value:
            fields.append((locator, value))
    lines = ["---"]
    for key, value in fields:
        lines.append(f"{key}: {json.dumps(value, ensure_ascii=False)}")
    lines.extend(("---", ""))
    return "\n".join(lines), body


def transform_skills(
    target: Path,
    connector: dict[str, Any],
    root_source_name: str,
) -> None:
    for skill_file in sorted(target.rglob("SKILL.md")):
        frontmatter, body = workbuddy_frontmatter(
            skill_file,
            connector,
            root_source_name,
        )
        skill_file.write_text(frontmatter + body, encoding="utf-8")


def write_zip(output_dir: Path, zip_path: Path) -> None:
    if zip_path.exists():
        raise FileExistsError(f"ZIP already exists: {zip_path}")
    zip_path.parent.mkdir(parents=True, exist_ok=True)
    with zipfile.ZipFile(zip_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
        for path in sorted(output_dir.rglob("*")):
            if path.is_file():
                archive.write(
                    path,
                    Path(output_dir.name) / path.relative_to(output_dir),
                )


def write_individual_zips(skills_dir: Path, individual_dir: Path) -> None:
    if individual_dir.exists():
        raise FileExistsError(
            f"individual ZIP directory already exists: {individual_dir}"
        )
    individual_dir.mkdir(parents=True)
    for skill_dir in sorted(skills_dir.iterdir()):
        if not (skill_dir / "SKILL.md").is_file():
            continue
        zip_path = individual_dir / f"{skill_dir.name}.zip"
        with zipfile.ZipFile(
            zip_path, "w", compression=zipfile.ZIP_DEFLATED
        ) as archive:
            for path in sorted(skill_dir.rglob("*")):
                if path.is_file():
                    archive.write(
                        path,
                        Path(skill_dir.name) / path.relative_to(skill_dir),
                    )


def sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def build(
    source: Path,
    meta_path: Path,
    icon_path: Path,
    output_dir: Path,
    zip_path: Path,
    individual_dir: Path,
) -> None:
    source_errors: list[str] = []
    validate_source(source, source_errors, require_self_contained=True)
    validate_connector_meta(meta_path, source_errors)
    if not icon_path.is_file():
        source_errors.append(f"{icon_path}: market icon is required")
    elif icon_path.suffix.lower() not in {".svg", ".png", ".jpg", ".jpeg"}:
        source_errors.append(f"{icon_path}: unsupported market icon format")
    fail_on_errors(source_errors, "WorkBuddy input validation")

    if output_dir.exists():
        raise FileExistsError(f"output directory already exists: {output_dir}")
    if zip_path.exists():
        raise FileExistsError(f"ZIP already exists: {zip_path}")
    if individual_dir.exists():
        raise FileExistsError(
            f"individual ZIP directory already exists: {individual_dir}"
        )

    connector = json.loads(meta_path.read_text(encoding="utf-8"))
    source_data, _ = split_frontmatter(source / "SKILL.md")
    root_source_name = compact_text(source_data.get("name"))
    root_skill_name = compact_text(connector.get("raw_name")) or root_source_name

    output_dir.mkdir(parents=True)
    shutil.copy2(meta_path, output_dir / "connector-meta.json")
    shutil.copy2(icon_path, output_dir / f"icon{icon_path.suffix.lower()}")

    skills_target = output_dir / "skills"
    skill_target = skills_target / root_skill_name
    skill_target.mkdir(parents=True)
    copy_source_resources(source, skill_target)

    source_modules = source / "skills"
    if source_modules.is_dir():
        for module_source in sorted(source_modules.iterdir()):
            module_skill = module_source / "SKILL.md"
            if not module_skill.is_file():
                continue
            module_data, _ = split_frontmatter(module_skill)
            module_name = compact_text(module_data.get("name"))
            module_target = skills_target / module_name
            module_target.mkdir(parents=True)
            copy_source_resources(module_source, module_target)
            make_module_self_contained(source, module_target)

    transform_skills(skills_target, connector, root_source_name)

    package_errors: list[str] = []
    validate_workbuddy_package(output_dir, package_errors)
    fail_on_errors(package_errors, "WorkBuddy package validation")
    write_zip(output_dir, zip_path)
    write_individual_zips(skills_target, individual_dir)

    print(f"connector_dir={output_dir}")
    print(f"connector_zip={zip_path}")
    print(f"connector_sha256={sha256(zip_path)}")
    print(f"individual_zips={individual_dir}")
    print(f"entrypoint={root_skill_name}")
    print(
        "top_level_skills="
        f"{len(list(skills_target.glob('*/SKILL.md')))}"
    )
    print("validation=passed")


def main() -> int:
    args = parse_args()
    source = args.source.expanduser().resolve()
    meta_path = args.meta.expanduser().resolve()
    icon_path = args.icon.expanduser().resolve()
    output_dir = args.output_dir.expanduser().resolve()
    zip_path = (
        args.zip_path.expanduser().resolve()
        if args.zip_path
        else output_dir.parent / f"{output_dir.name}.zip"
    )
    individual_dir = (
        args.individual_dir.expanduser().resolve()
        if args.individual_dir
        else output_dir.parent / f"{output_dir.name}-individual"
    )
    if not source.is_dir():
        print(f"ERROR: source directory does not exist: {source}", file=sys.stderr)
        return 2
    try:
        build(source, meta_path, icon_path, output_dir, zip_path, individual_dir)
    except (FileExistsError, ValidationFailure, ValueError) as exc:
        print(f"ERROR: {exc}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Validate Skill Publisher source Skills and WorkBuddy distributions."""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Any, Iterable

try:
    import yaml
except ImportError:
    print(
        "ERROR: PyYAML is required for standards-compliant frontmatter parsing. "
        "Install it with: python3 -m pip install PyYAML",
        file=sys.stderr,
    )
    raise SystemExit(2)


SOURCE_FRONTMATTER_KEYS = {
    "name",
    "description",
    "license",
    "compatibility",
    "allowed-tools",
    "metadata",
}
WORKBUDDY_FRONTMATTER_KEYS = {
    "name",
    "description",
    "version",
    "author",
    "source_type",
    "clawhub_slug",
    "skillhub_slug",
    "git_url",
}
SOURCE_LOCATORS = ("clawhub_slug", "skillhub_slug", "git_url")
TEXT_SUFFIXES = {".md", ".json", ".yaml", ".yml", ".txt", ".svg", ".py"}
JUNK_NAMES = {"__pycache__", ".DS_Store"}
JUNK_SUFFIXES = {".pyc", ".pyo"}
SKIP_DIRS = {".git", "dist", ".venv", "venv", "node_modules"}
SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$")
NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
MARKDOWN_LINK_RE = re.compile(r"!?\[[^\]]*]\(([^)]+)\)")
SKILL_PATH_RE = re.compile(
    r"\$(SKILL_DIR|KIT_DIR)/([A-Za-z0-9_./-]+)"
)


class ValidationFailure(Exception):
    """Raised when a validation input cannot be parsed."""


def read_text(path: Path) -> str:
    return path.read_text(encoding="utf-8")


def split_frontmatter(path: Path) -> tuple[dict[str, Any], str]:
    text = read_text(path)
    if not text.startswith("---\n"):
        raise ValidationFailure(f"{path}: missing YAML frontmatter")
    marker = text.find("\n---\n", 4)
    if marker < 0:
        raise ValidationFailure(f"{path}: frontmatter is not closed")
    raw = text[4:marker]
    try:
        data = yaml.safe_load(raw)
    except yaml.YAMLError as exc:
        raise ValidationFailure(
            f"{path}: standard YAML parser rejected frontmatter: {exc}"
        ) from exc
    if not isinstance(data, dict):
        raise ValidationFailure(f"{path}: frontmatter must be a YAML mapping")
    return data, text[marker + 5 :]


def compact_text(value: Any) -> str:
    return re.sub(r"\s+", " ", value).strip() if isinstance(value, str) else ""


def is_relative_to(path: Path, parent: Path) -> bool:
    try:
        path.relative_to(parent)
        return True
    except ValueError:
        return False


def iter_files(root: Path) -> Iterable[Path]:
    for path in root.rglob("*"):
        if any(part in SKIP_DIRS for part in path.relative_to(root).parts):
            continue
        if path.is_file():
            yield path


def validate_name(name: Any, label: str, errors: list[str]) -> None:
    if not isinstance(name, str) or not NAME_RE.fullmatch(name):
        errors.append(f"{label}: name must be kebab-case")
    elif len(name) > 64:
        errors.append(f"{label}: name must be at most 64 characters")


def validate_description(
    value: Any,
    label: str,
    errors: list[str],
    minimum: int = 50,
    maximum: int = 200,
) -> None:
    description = compact_text(value)
    if not minimum <= len(description) <= maximum:
        errors.append(
            f"{label}: description must contain {minimum}-{maximum} characters "
            f"(found {len(description)})"
        )
    if "<" in description or ">" in description:
        errors.append(f"{label}: description must not contain angle brackets")


def validate_triggers(body: str, label: str, errors: list[str]) -> None:
    if not re.search(r"(?mi)^##\s+Triggers\s*$", body):
        errors.append(f"{label}: add an explicit '## Triggers' section")
    if not re.search(
        (
            r"(?mi)^###\s+(?:Do not activate when|Non-triggers?|"
            r"不应触发|不要触发)\s*$"
        ),
        body,
    ):
        errors.append(
            f"{label}: Triggers must include explicit non-trigger conditions"
        )
    trigger_block = re.search(
        r"(?ms)^##\s+Triggers\s*$([\s\S]*?)(?=^##\s+|\Z)", body
    )
    if trigger_block and len(re.findall(r"(?m)^\s*-\s+\S", trigger_block.group(1))) < 3:
        errors.append(
            f"{label}: Triggers should include at least two activation examples "
            "and one non-trigger condition"
        )


def validate_frontmatter(
    path: Path, target: str, errors: list[str]
) -> tuple[dict[str, Any], str] | None:
    try:
        data, body = split_frontmatter(path)
    except ValidationFailure as exc:
        errors.append(str(exc))
        return None

    allowed = (
        SOURCE_FRONTMATTER_KEYS
        if target == "source"
        else WORKBUDDY_FRONTMATTER_KEYS
    )
    unexpected = sorted(set(data) - allowed)
    if unexpected:
        errors.append(
            f"{path}: unsupported {target} frontmatter keys: "
            + ", ".join(unexpected)
        )

    validate_name(data.get("name"), str(path), errors)
    validate_description(data.get("description"), str(path), errors)
    validate_triggers(body, str(path), errors)
    if not body.strip():
        errors.append(f"{path}: body is empty")

    if target == "source":
        metadata = data.get("metadata")
        if not isinstance(metadata, dict):
            errors.append(f"{path}: metadata must be a mapping")
        else:
            if not compact_text(metadata.get("author")):
                errors.append(f"{path}: metadata.author is required")
            version = compact_text(metadata.get("version"))
            if not SEMVER_RE.fullmatch(version):
                errors.append(f"{path}: metadata.version must use SemVer")
            tags = metadata.get("tags")
            if not isinstance(tags, list) or not tags or not all(
                isinstance(tag, str) and tag.strip() for tag in tags
            ):
                errors.append(f"{path}: metadata.tags must be a non-empty list")
    else:
        version = compact_text(data.get("version"))
        if not SEMVER_RE.fullmatch(version):
            errors.append(f"{path}: version must use SemVer")
        if not compact_text(data.get("author")):
            errors.append(f"{path}: author is required")
        if data.get("source_type") not in {"git", "clawhub", "skillhub"}:
            errors.append(
                f"{path}: source_type must be git, clawhub, or skillhub"
            )
        if not any(compact_text(data.get(key)) for key in SOURCE_LOCATORS):
            errors.append(
                f"{path}: add one source locator: " + ", ".join(SOURCE_LOCATORS)
            )
    return data, body


def validate_todos(paths: Iterable[Path], errors: list[str]) -> None:
    for path in paths:
        if path.is_file() and re.search(r"\bTODO\s*[:：]", read_text(path)):
            errors.append(f"{path}: unresolved TODO placeholder")


def validate_junk(root: Path, errors: list[str]) -> None:
    for path in root.rglob("*"):
        if any(part in SKIP_DIRS for part in path.relative_to(root).parts):
            continue
        if path.name in JUNK_NAMES or path.suffix.lower() in JUNK_SUFFIXES:
            errors.append(f"{path}: generated/cache artifact must not be released")


def validate_private_paths(root: Path, errors: list[str]) -> None:
    private_path = re.compile(
        r"(?:/Users/[^/\s]+/|[A-Za-z]:\\\\Users\\\\[^\\\\\s]+\\\\)"
    )
    for path in iter_files(root):
        if path.suffix.lower() not in TEXT_SUFFIXES:
            continue
        if path.name == "validate_skill.py":
            continue
        if private_path.search(read_text(path)):
            errors.append(f"{path}: contains a private absolute user path")


def normalize_link_target(raw: str) -> str:
    target = raw.strip().split(maxsplit=1)[0].strip("<>")
    return target.split("#", 1)[0]


def validate_local_references(root: Path, errors: list[str]) -> None:
    for path in iter_files(root):
        if path.suffix.lower() != ".md":
            continue
        text = read_text(path)
        for raw in MARKDOWN_LINK_RE.findall(text):
            target = normalize_link_target(raw)
            if (
                not target
                or re.match(r"^[a-z][a-z0-9+.-]*:", target, re.I)
                or target.startswith("#")
                or any(token in target for token in ("TODO", "{", "}"))
            ):
                continue
            resolved = (path.parent / target).resolve()
            if not resolved.exists():
                errors.append(f"{path}: broken local link '{target}'")
        skill_root = path.parent
        current = path.parent
        while current != root.parent:
            if (current / "SKILL.md").is_file():
                skill_root = current
                break
            if current == root:
                break
            current = current.parent
        kit_root = skill_root
        current = path.parent
        while current != root.parent:
            if (current / "kit.yaml").is_file():
                kit_root = current
                break
            if current == root:
                break
            current = current.parent
        for variable, target in SKILL_PATH_RE.findall(text):
            if "TODO" in target:
                continue
            base = skill_root if variable == "SKILL_DIR" else kit_root
            resolved = (base / target.rstrip(".,;:)")).resolve()
            if not is_relative_to(resolved, root.resolve()) or not resolved.exists():
                errors.append(
                    f"{path}: missing or external required resource "
                    f"'${variable}/{target}'"
                )


def load_yaml(path: Path, errors: list[str]) -> dict[str, Any] | None:
    try:
        data = yaml.safe_load(read_text(path))
    except yaml.YAMLError as exc:
        errors.append(f"{path}: standard YAML parser rejected file: {exc}")
        return None
    if not isinstance(data, dict):
        errors.append(f"{path}: expected a YAML mapping")
        return None
    return data


def validate_kit(root: Path, skill_names: set[str], errors: list[str]) -> None:
    manifest = root / "kit.yaml"
    if not manifest.exists():
        return
    data = load_yaml(manifest, errors)
    if data is None:
        return
    modules = data.get("modules")
    if not isinstance(modules, list) or not modules:
        errors.append(f"{manifest}: modules must be a non-empty list")
        return
    module_ids: set[str] = set()
    for index, module in enumerate(modules):
        label = f"{manifest}: modules[{index}]"
        if not isinstance(module, dict):
            errors.append(f"{label} must be a mapping")
            continue
        module_id = compact_text(module.get("id"))
        skill = compact_text(module.get("skill"))
        relative = compact_text(module.get("path"))
        if not module_id or module_id in module_ids:
            errors.append(f"{label}: id is required and must be unique")
        module_ids.add(module_id)
        if skill not in skill_names:
            errors.append(f"{label}: unresolved child skill '{skill}'")
        module_path = (root / relative).resolve()
        if (
            not relative
            or not is_relative_to(module_path, root.resolve())
            or not (module_path / "SKILL.md").is_file()
        ):
            errors.append(
                f"{label}: missing self-contained module at '{relative}/SKILL.md'"
            )
        else:
            try:
                module_data, _ = split_frontmatter(module_path / "SKILL.md")
            except ValidationFailure as exc:
                errors.append(str(exc))
            else:
                actual_name = compact_text(module_data.get("name"))
                if actual_name != skill:
                    errors.append(
                        f"{label}: expected Skill name '{skill}' at "
                        f"'{relative}/SKILL.md', found '{actual_name}'"
                    )
    pipelines = data.get("pipelines")
    if pipelines is not None:
        if not isinstance(pipelines, dict):
            errors.append(f"{manifest}: pipelines must be a mapping")
        else:
            for pipeline, sequence in pipelines.items():
                if not isinstance(sequence, list) or not sequence:
                    errors.append(
                        f"{manifest}: pipeline '{pipeline}' must be a non-empty list"
                    )
                    continue
                missing = [item for item in sequence if item not in module_ids]
                if missing:
                    errors.append(
                        f"{manifest}: pipeline '{pipeline}' has unknown modules: "
                        + ", ".join(map(str, missing))
                    )


def validate_dependencies(
    skill_data: list[tuple[Path, dict[str, Any]]],
    names: set[str],
    errors: list[str],
    require_self_contained: bool,
) -> None:
    for path, data in skill_data:
        metadata = data.get("metadata")
        if not isinstance(metadata, dict):
            continue
        dependencies = metadata.get("dependencies", [])
        if not isinstance(dependencies, list):
            errors.append(f"{path}: metadata.dependencies must be a list")
            continue
        for dependency in dependencies:
            name = (
                dependency
                if isinstance(dependency, str)
                else dependency.get("skill")
                if isinstance(dependency, dict)
                else ""
            )
            if not name:
                errors.append(f"{path}: dependency entries need a skill name")
            elif not isinstance(name, str) or not NAME_RE.fullmatch(name):
                errors.append(f"{path}: dependency names must be kebab-case")
            elif require_self_contained and name not in names:
                errors.append(
                    f"{path}: unresolved required dependency '{name}'; "
                    "embed it in the Skill Kit before release"
                )


def validate_readme_version(
    root: Path, root_data: dict[str, Any] | None, errors: list[str]
) -> None:
    readme = root / "README.md"
    if not readme.is_file():
        errors.append(f"{readme}: required for Skill Publisher source repositories")
        return
    if root_data is None:
        return
    metadata = root_data.get("metadata")
    if not isinstance(metadata, dict):
        return
    version = compact_text(metadata.get("version"))
    if version and f"version-{version}-" not in read_text(readme):
        errors.append(
            f"{readme}: version badge does not match SKILL.md version {version}"
        )


def validate_source(
    root: Path,
    errors: list[str],
    require_self_contained: bool = False,
) -> None:
    skill_files = [root / "SKILL.md", *sorted((root / "skills").glob("*/SKILL.md"))]
    if not skill_files[0].is_file():
        errors.append(f"{skill_files[0]}: file is required")
        return
    parsed: list[tuple[Path, dict[str, Any]]] = []
    root_data: dict[str, Any] | None = None
    for path in skill_files:
        result = validate_frontmatter(path, "source", errors)
        if result:
            data, _ = result
            parsed.append((path, data))
            if path == root / "SKILL.md":
                root_data = data
    names = {
        compact_text(data.get("name"))
        for _, data in parsed
        if compact_text(data.get("name"))
    }
    if len(names) != len(parsed):
        errors.append(f"{root}: every embedded Skill must have a unique name")
    validate_dependencies(parsed, names, errors, require_self_contained)
    validate_kit(root, names, errors)
    validate_readme_version(root, root_data, errors)
    validate_todos([root / "SKILL.md", root / "README.md", *skill_files[1:]], errors)
    validate_junk(root, errors)
    validate_private_paths(root, errors)
    validate_local_references(root, errors)
    if (root / "workbuddy").exists():
        errors.append(
            f"{root / 'workbuddy'}: keep platform metadata outside canonical source"
        )


def validate_connector_meta(path: Path, errors: list[str]) -> dict[str, Any] | None:
    if not path.is_file():
        errors.append(f"{path}: required for WorkBuddy distribution")
        return None
    try:
        data = json.loads(read_text(path))
    except json.JSONDecodeError as exc:
        errors.append(f"{path}: invalid JSON: {exc}")
        return None
    if not isinstance(data, dict):
        errors.append(f"{path}: expected a JSON object")
        return None
    required = (
        "name",
        "name_zh",
        "name_en",
        "description",
        "description_zh",
        "description_en",
        "source",
        "type",
        "version",
        "examples_zh",
        "examples_en",
        "source_type",
    )
    for field in required:
        if field not in data:
            errors.append(f"{path}: missing '{field}'")
    if not 2 <= len(compact_text(data.get("name"))) <= 20:
        errors.append(f"{path}: name should contain 2-20 characters")
    for field in ("description_zh", "description_en"):
        value = compact_text(data.get(field))
        if not 20 <= len(value) <= 100:
            errors.append(f"{path}: {field} should contain 20-100 characters")
    source = compact_text(data.get("source"))
    if not NAME_RE.fullmatch(source):
        errors.append(f"{path}: source must be a globally unique kebab-case ID")
    raw_name = compact_text(data.get("raw_name"))
    if raw_name and not NAME_RE.fullmatch(raw_name):
        errors.append(f"{path}: raw_name must be a kebab-case Skill ID")
    if data.get("type") != "skill-only":
        errors.append(f"{path}: type must be 'skill-only'")
    if not SEMVER_RE.fullmatch(compact_text(data.get("version"))):
        errors.append(f"{path}: version must use SemVer")
    if data.get("source_type") not in {"git", "clawhub", "skillhub"}:
        errors.append(f"{path}: source_type must be git, clawhub, or skillhub")
    if not any(compact_text(data.get(key)) for key in SOURCE_LOCATORS):
        errors.append(
            f"{path}: add one source locator: " + ", ".join(SOURCE_LOCATORS)
        )
    for field in ("examples_zh", "examples_en"):
        examples = data.get(field)
        if not isinstance(examples, list) or not 2 <= len(examples) <= 5:
            errors.append(f"{path}: {field} must contain 2-5 examples")
    if re.search(r"\bTODO\s*[:：]", read_text(path)):
        errors.append(f"{path}: unresolved TODO placeholder")
    return data


def validate_workbuddy_package(root: Path, errors: list[str]) -> None:
    validate_connector_meta(root / "connector-meta.json", errors)
    icons = [root / f"icon{suffix}" for suffix in (".svg", ".png", ".jpg", ".jpeg")]
    if not any(path.is_file() for path in icons):
        errors.append(f"{root}: missing market icon")
    skills_root = root / "skills"
    skill_files = sorted(skills_root.glob("*/SKILL.md"))
    if not skill_files:
        errors.append(f"{skills_root}: package must contain at least one Skill")
        return
    names: set[str] = set()
    for path in sorted(skills_root.rglob("SKILL.md")):
        result = validate_frontmatter(path, "workbuddy", errors)
        if result:
            data, _ = result
            name = compact_text(data.get("name"))
            names.add(name)
    for root_skill in skill_files:
        validate_kit(root_skill.parent, names, errors)
    validate_junk(root, errors)
    validate_private_paths(root, errors)
    validate_local_references(root, errors)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("path", type=Path, help="Skill source or package directory")
    parser.add_argument(
        "--target",
        choices=("source", "workbuddy-package"),
        default="source",
        help="Validation profile",
    )
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    root = args.path.expanduser().resolve()
    if not root.is_dir():
        print(f"ERROR: directory does not exist: {root}", file=sys.stderr)
        return 2
    errors: list[str] = []
    if args.target == "source":
        validate_source(root, errors)
    else:
        validate_workbuddy_package(root, errors)
    if errors:
        print(f"FAILED: {len(errors)} issue(s)")
        for error in errors:
            print(f"- {error}")
        return 1
    print(f"PASSED: {args.target} validation ({root})")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())