Add OpenClaw skills, platform kit, and template docs

Made-with: Cursor

jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml

@@ -0,0 +1,139 @@
+name: Reusable Skill Release
+
+on:
+  workflow_call:
+    inputs:
+      artifact_platform:
+        required: false
+        type: string
+        default: windows
+      pyarmor_platform:
+        required: false
+        type: string
+        default: windows.x86_64
+      upload_url:
+        required: false
+        type: string
+        default: https://jc2009.com/api/upload
+      sync_url:
+        required: false
+        type: string
+        default: https://jc2009.com/api/skill/update
+      prune_url:
+        required: false
+        type: string
+        default: https://jc2009.com/api/artifacts/prune-old-versions
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    env:
+      ARTIFACT_PLATFORM: ${{ inputs.artifact_platform }}
+      PYARMOR_PLATFORM: ${{ inputs.pyarmor_platform }}
+      PIP_BREAK_SYSTEM_PACKAGES: "1"
+    steps:
+      - uses: http://120.25.191.12:3000/admin/actions-checkout@v4
+
+      - name: Setup Tools
+        run: pip install "pyarmor>=8.5" requests python-frontmatter --break-system-packages -i https://pypi.tuna.tsinghua.edu.cn/simple
+
+      - name: Encrypt Source Code
+        run: |
+          mkdir -p dist/package
+          pyarmor gen --platform "${PYARMOR_PLATFORM}" -O dist/package scripts/*.py
+          cp SKILL.md dist/package/
+
+      - name: Parse Metadata and Pack
+        id: build_task
+        run: |
+          python -c "
+          import frontmatter, os, json, shutil
+          post = frontmatter.load('SKILL.md')
+          metadata = dict(post.metadata or {})
+          metadata['readme_md'] = (post.content or '').strip()
+          openclaw_meta = metadata.get('metadata', {}).get('openclaw', {})
+          slug = (openclaw_meta.get('slug') or metadata.get('slug') or metadata.get('name') or '').strip()
+          if not slug:
+              raise Exception('SKILL.md 缺少 slug/name')
+          ref_name = (os.environ.get('GITHUB_REF_NAME') or '').strip()
+          if not ref_name.startswith('v'):
+              raise Exception(f'非法标签: {ref_name}')
+          version = ref_name.lstrip('v')
+          metadata['version'] = version
+          artifact_platform = (os.environ.get('ARTIFACT_PLATFORM') or 'windows').strip()
+          zip_base = f'{slug}-{artifact_platform}'
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
+              f.write(f'slug={slug}\n')
+              f.write(f'version={version}\n')
+              f.write(f'zip_base={zip_base}\n')
+              f.write(f'artifact_platform={artifact_platform}\n')
+              f.write(f'metadata={json.dumps(metadata, ensure_ascii=False)}\n')
+          shutil.make_archive(zip_base, 'zip', 'dist/package')
+          "
+
+      - name: Sync Database
+        env:
+          METADATA_JSON: ${{ steps.build_task.outputs.metadata }}
+          SYNC_URL: ${{ inputs.sync_url }}
+        run: |
+          python -c "
+          import requests, json, os
+          metadata = json.loads(os.environ['METADATA_JSON'])
+          res = requests.post(os.environ['SYNC_URL'], json=metadata)
+          if res.status_code != 200:
+              exit(1)
+          body = res.json()
+          if body.get('code') != 200:
+              exit(1)
+          "
+
+      - name: Upload Encrypted ZIP
+        env:
+          SLUG: ${{ steps.build_task.outputs.slug }}
+          VERSION: ${{ steps.build_task.outputs.version }}
+          ZIP_BASE: ${{ steps.build_task.outputs.zip_base }}
+          ARTIFACT_PLATFORM: ${{ steps.build_task.outputs.artifact_platform }}
+          UPLOAD_URL: ${{ inputs.upload_url }}
+        run: |
+          python -c "
+          import requests, os
+          slug = os.environ['SLUG']
+          version = os.environ['VERSION']
+          zip_path = f\"{os.environ['ZIP_BASE']}.zip\"
+          payload = {
+              'plugin_name': slug,
+              'version': version,
+              'artifact_type': 'skill',
+              'artifact_platform': os.environ.get('ARTIFACT_PLATFORM', 'windows'),
+          }
+          filename = os.path.basename(zip_path)
+          with open(zip_path, 'rb') as f:
+              res = requests.post(os.environ['UPLOAD_URL'], data=payload, files={'file': (filename, f)})
+          if res.status_code != 200:
+              exit(1)
+          body = res.json()
+          if body.get('code') != 200:
+              exit(1)
+          "
+
+      - name: Prune Old Versions
+        env:
+          SLUG: ${{ steps.build_task.outputs.slug }}
+          VERSION: ${{ steps.build_task.outputs.version }}
+          PRUNE_URL: ${{ inputs.prune_url }}
+        run: |
+          python -c "
+          import requests, os
+          payload = {
+            'name': os.environ['SLUG'],
+            'artifact_type': 'skill',
+            'keep_count': 1,
+            'protect_version': os.environ['VERSION']
+          }
+          res = requests.post(os.environ['PRUNE_URL'], json=payload)
+          if res.status_code != 200:
+              exit(1)
+          body = res.json()
+          if body.get('code') != 200:
+              exit(1)
+          "

jiangchang-platform-kit/README.md

@@ -0,0 +1,7 @@
+# jiangchang-platform-kit
+
+Shared platform components for Jiangchang skills:
+
+- `sdk/jiangchang_skill_core`: entitlement SDK package.
+- `.github/workflows/reusable-release-skill.yaml`: reusable CI release workflow.
+- `examples/workflows/use-reusable-release-skill.yaml`: caller workflow sample.

jiangchang-platform-kit/examples/flask_skill_update_or_create.py

@@ -0,0 +1,84 @@
+# 将此路由合并进你的 skill 蓝图。
+# CI 不再写入 skill_type / monthly_price / yearly_price，避免每次发布覆盖后台手工配置。
+#
+# 要求：SkillModel.update_or_create 在「更新」时对 data 中未出现的列应保留数据库原值；
+# 若当前是整行覆盖，请在 Model 层改为按字段合并或白名单更新。
+# 若表对这三列 NOT NULL 且无默认值，仅在「首次插入」时在 Model 内写死默认即可。
+
+import json
+import re
+from datetime import datetime
+
+from flask import jsonify, request
+
+# from your_app import skill_bp, SkillModel  # 按你项目实际导入
+
+
+@skill_bp.route("/api/skill/update", methods=["POST"])
+def update_or_create_skill():
+    """CI/CD 自动化注册接口（可选携带 readme_md = SKILL.md 正文 Markdown）"""
+    try:
+        data = request.get_json(silent=True) or {}
+        if not data:
+            return jsonify({"code": 400, "msg": "请求体为空", "data": None}), 400
+
+        openclaw_meta = data.get("metadata", {}).get("openclaw", {})
+
+        slug = (
+            (data.get("slug") or "").strip()
+            or (openclaw_meta.get("slug") or "").strip()
+            or (data.get("name") or "").strip()
+        )
+        name = (data.get("name") or slug).strip()
+        version = str(data.get("version") or "").strip()
+        category = (openclaw_meta.get("category") or "").strip()
+
+        if not all([slug, name, version, category]):
+            return jsonify(
+                {
+                    "code": 400,
+                    "msg": "元数据不完整（需包含 slug/name/version/category）",
+                    "data": None,
+                }
+            ), 400
+
+        slug = slug.lower()
+
+        if not re.match(r"^[a-z0-9-]+$", slug):
+            return jsonify(
+                {
+                    "code": 400,
+                    "msg": "slug 格式非法，仅允许小写字母、数字和中划线",
+                    "data": None,
+                }
+            ), 400
+
+        skill_data = {
+            "slug": slug,
+            "name": name,
+            "description": data.get("description"),
+            "version": version,
+            "category": category,
+            "developer_name": data.get("author", "匠厂开发者"),
+            "tags": json.dumps(data.get("tags", []), ensure_ascii=False),
+            "status": 2,
+            "updated_at": datetime.now(),
+        }
+
+        if "readme_md" in data:
+            rm = data.get("readme_md")
+            skill_data["readme_md"] = "" if rm is None else str(rm)
+
+        success = SkillModel.update_or_create(slug=slug, data=skill_data)
+        if success:
+            return jsonify(
+                {
+                    "code": 200,
+                    "msg": "注册成功",
+                    "data": {"slug": slug, "name": name, "version": version},
+                }
+            ), 200
+        return jsonify({"code": 500, "msg": "数据持久化失败", "data": None}), 500
+
+    except Exception as e:
+        return jsonify({"code": 500, "msg": str(e), "data": None}), 500

jiangchang-platform-kit/examples/workflows/use-reusable-release-skill.yaml

@@ -0,0 +1,12 @@
+name: Skill Release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    uses: admin/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml@v0.1.0
+    with:
+      artifact_platform: windows
+      pyarmor_platform: windows.x86_64
+      include_readme_md: false

jiangchang-platform-kit/sdk/jiangchang_skill_core/__init__.py

@@ -0,0 +1,9 @@
+from .client import EntitlementClient
+from .guard import enforce_entitlement
+from .models import EntitlementResult
+
+__all__ = [
+    "EntitlementClient",
+    "EntitlementResult",
+    "enforce_entitlement",
+]

jiangchang-platform-kit/sdk/jiangchang_skill_core/client.py

@@ -0,0 +1,63 @@
+import os
+from typing import Any
+
+import requests
+
+from .errors import EntitlementServiceError
+from .models import EntitlementResult
+
+
+class EntitlementClient:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout_seconds: int | None = None,
+    ) -> None:
+        self.base_url = (base_url or os.getenv("JIANGCHANG_AUTH_BASE_URL", "")).rstrip("/")
+        self.api_key = api_key or os.getenv("JIANGCHANG_AUTH_API_KEY", "")
+        self.timeout_seconds = timeout_seconds or int(
+            os.getenv("JIANGCHANG_AUTH_TIMEOUT_SECONDS", "5")
+        )
+        if not self.base_url:
+            raise EntitlementServiceError("missing JIANGCHANG_AUTH_BASE_URL")
+
+    def check_entitlement(
+        self,
+        user_id: str,
+        skill_slug: str,
+        trace_id: str = "",
+        context: dict[str, Any] | None = None,
+    ) -> EntitlementResult:
+        url = f"{self.base_url}/api/entitlements/check"
+        payload = {
+            "user_id": user_id,
+            "skill_slug": skill_slug,
+            "trace_id": trace_id,
+            "context": context or {},
+        }
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        try:
+            res = requests.post(
+                url,
+                json=payload,
+                headers=headers,
+                timeout=self.timeout_seconds,
+            )
+        except requests.RequestException as exc:
+            raise EntitlementServiceError(f"entitlement request failed: {exc}") from exc
+
+        if res.status_code != 200:
+            raise EntitlementServiceError(f"entitlement http status {res.status_code}")
+        try:
+            body = res.json()
+        except ValueError as exc:
+            raise EntitlementServiceError("entitlement response is not json") from exc
+
+        data = body.get("data") or {}
+        allow = bool(data.get("allow", False))
+        reason = str(data.get("reason") or body.get("msg") or "")
+        expire_at = str(data.get("expire_at") or "")
+        return EntitlementResult(allow=allow, reason=reason, expire_at=expire_at, raw=body)

jiangchang-platform-kit/sdk/jiangchang_skill_core/errors.py

@@ -0,0 +1,10 @@
+class EntitlementError(Exception):
+    pass
+
+
+class EntitlementDeniedError(EntitlementError):
+    pass
+
+
+class EntitlementServiceError(EntitlementError):
+    pass

jiangchang-platform-kit/sdk/jiangchang_skill_core/guard.py

@@ -0,0 +1,22 @@
+from .client import EntitlementClient
+from .errors import EntitlementDeniedError
+from .models import EntitlementResult
+
+
+def enforce_entitlement(
+    user_id: str,
+    skill_slug: str,
+    trace_id: str = "",
+    context: dict | None = None,
+    client: EntitlementClient | None = None,
+) -> EntitlementResult:
+    c = client or EntitlementClient()
+    result = c.check_entitlement(
+        user_id=user_id,
+        skill_slug=skill_slug,
+        trace_id=trace_id,
+        context=context or {},
+    )
+    if not result.allow:
+        raise EntitlementDeniedError(result.reason or "skill not purchased or expired")
+    return result

jiangchang-platform-kit/sdk/jiangchang_skill_core/models.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class EntitlementResult:
+    allow: bool
+    reason: str = ""
+    expire_at: str = ""
+    raw: dict[str, Any] | None = None

jiangchang-platform-kit/sdk/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jiangchang-skill-core"
+version = "0.1.0"
+description = "Common entitlement SDK for Jiangchang skills"
+requires-python = ">=3.10"
+dependencies = [
+  "requests>=2.31.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "."}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["jiangchang_skill_core*"]

jiangchang-platform-kit/tools/release.ps1

@@ -0,0 +1,216 @@
+<#
+.SYNOPSIS
+  One-command release script for skill repos.
+
+.DESCRIPTION
+  - Optional auto-commit
+  - Push current branch
+  - Auto-increment semantic tag (vX.Y.Z)
+  - Create & push tag
+  - Fail fast on unsafe states
+
+.EXAMPLES
+  # Safe mode (recommended): requires clean working tree
+  .\release.ps1
+
+  # Auto commit tracked/untracked changes then release
+  .\release.ps1 -AutoCommit -CommitMessage "chore: update skill config"
+
+  # Dry run (show what would happen)
+  .\release.ps1 -DryRun
+
+  # Custom tag prefix
+  .\release.ps1 -Prefix "v" -Message "正式发布"
+
+.NOTES
+  Requires: git, PowerShell 5+
+#>
+
+[CmdletBinding()]
+param(
+  [string]$Prefix = "v",
+  [string]$Message = "正式发布",
+  [switch]$AutoCommit,
+  [switch]$RequireClean,
+  [string]$CommitMessage,
+  [switch]$DryRun
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Invoke-Git {
+  param([Parameter(Mandatory = $true)][string]$Args)
+  Write-Host ">> git $Args" -ForegroundColor DarkGray
+  & cmd /c "git $Args"
+  if ($LASTEXITCODE -ne 0) {
+    throw "git command failed: git $Args"
+  }
+}
+
+
+function Get-GitOutput {
+  param([Parameter(Mandatory = $true)][string]$Args)
+  $output = & cmd /c "git $Args" 2>$null
+  if ($LASTEXITCODE -ne 0) {
+    throw "git command failed: git $Args"
+  }
+  return @($output)
+}
+
+function Test-Repo {
+  & git rev-parse --is-inside-work-tree *> $null
+  return ($LASTEXITCODE -eq 0)
+}
+
+function Get-CurrentBranch {
+  $b = (Get-GitOutput "branch --show-current" | Select-Object -First 1).Trim()
+  return $b
+}
+
+
+function Get-StatusPorcelain {
+  $lines = @(Get-GitOutput "status --porcelain")
+  return $lines
+}
+
+function Parse-SemVerTag {
+  param(
+    [string]$Tag,
+    [string]$TagPrefix
+  )
+  $escaped = [regex]::Escape($TagPrefix)
+  $m = [regex]::Match($Tag, "^${escaped}(\d+)\.(\d+)\.(\d+)$")
+  if (-not $m.Success) { return $null }
+
+  return [pscustomobject]@{
+    Raw   = $Tag
+    Major = [int]$m.Groups[1].Value
+    Minor = [int]$m.Groups[2].Value
+    Patch = [int]$m.Groups[3].Value
+  }
+}
+
+function Get-NextTag {
+  param([string]$TagPrefix)
+
+  $tags = Get-GitOutput "tag --list"
+  $parsed = @()
+
+  foreach ($t in $tags) {
+    $t = $t.Trim()
+    if (-not $t) { continue }
+    $obj = Parse-SemVerTag -Tag $t -TagPrefix $TagPrefix
+    if ($null -ne $obj) { $parsed += $obj }
+  }
+
+  if ($parsed.Count -eq 0) {
+    return "${TagPrefix}1.0.1"
+  }
+
+  $latest = $parsed | Sort-Object Major, Minor, Patch | Select-Object -Last 1
+  return "$TagPrefix$($latest.Major).$($latest.Minor).$([int]$latest.Patch + 1)"
+}
+
+
+function Ensure-CleanOrAutoCommit {
+  param(
+    [switch]$DoAutoCommit,
+    [switch]$NeedClean,
+    [switch]$IsDryRun,
+    [string]$Msg
+  )
+
+  $status = @(Get-StatusPorcelain)
+  if ($status.Length -eq 0) { return }
+
+  if ($NeedClean) {
+    Write-Host "Working tree is not clean and -RequireClean is enabled." -ForegroundColor Yellow
+    & git status --short
+    throw "Abort: dirty working tree."
+  }
+
+  # 默认一键发布：有改动就自动提交；也可用 -AutoCommit 显式开启
+  $commitMsg = $Msg
+  if ([string]::IsNullOrWhiteSpace($commitMsg)) {
+    $commitMsg = "chore: auto release commit ($(Get-Date -Format 'yyyy-MM-dd HH:mm:ss'))"
+  }
+
+  if (-not $DoAutoCommit) {
+    Write-Host "Detected uncommitted changes, auto-committing before release..." -ForegroundColor Yellow
+  }
+
+  if ($IsDryRun) {
+    Write-Host "[DryRun] Would run: git add -A" -ForegroundColor Yellow
+    Write-Host "[DryRun] Would run: git commit -m `"$commitMsg`"" -ForegroundColor Yellow
+    return
+  }
+
+  Invoke-Git "add -A"
+  Invoke-Git "commit -m `"$commitMsg`""
+}
+
+
+try {
+  Write-Host "=== Release Script Start ===" -ForegroundColor Cyan
+
+  if (-not (Test-Repo)) {
+    throw "Current directory is not a git repository."
+  }
+
+  $branch = Get-CurrentBranch
+  if ([string]::IsNullOrWhiteSpace($branch)) {
+    throw "Unable to determine current branch."
+  }
+
+  if ($branch -notin @("main", "master")) {
+    throw "Current branch is '$branch'. Release is only allowed from main/master."
+  }
+
+  Invoke-Git "fetch --tags --prune origin"
+
+  Ensure-CleanOrAutoCommit -DoAutoCommit:$AutoCommit -NeedClean:$RequireClean -IsDryRun:$DryRun -Msg $CommitMessage
+
+  $upstream = (& git rev-parse --abbrev-ref --symbolic-full-name "@{u}" 2>$null)
+  $hasUpstream = ($LASTEXITCODE -eq 0)
+
+  if ($DryRun) {
+    if ($hasUpstream) {
+      Write-Host "[DryRun] Would run: git push" -ForegroundColor Yellow
+    } else {
+      Write-Host "[DryRun] Would run: git push -u origin $branch" -ForegroundColor Yellow
+    }
+  } else {
+    if ($hasUpstream) {
+      Invoke-Git "push"
+    } else {
+      Invoke-Git "push -u origin $branch"
+    }
+  }
+
+  $nextTag = Get-NextTag -TagPrefix $Prefix
+  Write-Host "Next tag: $nextTag" -ForegroundColor Green
+
+  $existing = @(Get-GitOutput "tag --list `"$nextTag`"")
+  if ($existing.Length -gt 0) {
+    throw "Tag already exists: $nextTag"
+  }
+
+  if ($DryRun) {
+    Write-Host "[DryRun] Would run: git tag -a $nextTag -m `"$Message`"" -ForegroundColor Yellow
+    Write-Host "[DryRun] Would run: git push origin $nextTag" -ForegroundColor Yellow
+    Write-Host "=== DryRun Complete ===" -ForegroundColor Cyan
+    exit 0
+  }
+
+  Invoke-Git "tag -a $nextTag -m `"$Message`""
+  Invoke-Git "push origin $nextTag"
+
+  Write-Host "Release success: $nextTag" -ForegroundColor Green
+  Write-Host "=== Release Script Done ===" -ForegroundColor Cyan
+  exit 0
+}
+catch {
+  Write-Host "Release failed: $($_.Exception.Message)" -ForegroundColor Red
+  exit 1
+}