Add OpenClaw skills, platform kit, and template docs

Made-with: Cursor

logistics-tracker/.github/workflows/release_skill.yaml

@@ -0,0 +1,11 @@
+name: 技能自动化发布
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    uses: admin/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml@main
+    with:
+      artifact_platform: windows
+      pyarmor_platform: windows.x86_64

logistics-tracker/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: 物流轨迹查询
+description: 物流轨迹查询。当用户发送物流单号、询问包裹状态、问"货到哪了"、"帮我查单号"等时使用。调用17Track API查询最新轨迹并用中文回复。支持全球200+承运商。
+version: 1.0.0
+author: 深圳匠厂科技有限公司
+metadata:
+  openclaw:
+    slug: logistics-tracker
+    emoji: "📦"
+    category: "通用"
+    requires:
+      env:
+        - TRACK17_API_KEY
+      bins:
+        - python3
+allowed-tools:
+  - bash
+---
+
+# 物流轨迹查询
+
+## 使用时机
+
+当用户发送以下内容时触发本Skill：
+- 包含物流单号（字母+数字组合，如 `RR123456789CN`、`UPS1234567890`）
+- 询问"我的货到哪了"、"帮我查单号"、"物流查询"、"查一下快递"等
+
+## 执行步骤
+
+1. 从用户消息中提取物流单号
+2. 执行查询脚本：
+```bash
+python3 {baseDir}/scripts/main.py <单号>
+```
+
+3. 将脚本返回结果直接回复给用户
+4. 如果用户没有提供单号，回复："请发送您要查询的物流单号，我来帮您查询最新状态。"
+
+## 输出格式
+
+脚本会返回格式化好的中文结果，直接发送给用户即可，无需二次处理。
+
+## 错误处理
+
+- 查询失败：告知用户"该单号暂时查询不到，可能未入网，请稍后再试"
+- 网络超时：告知用户"网络连接超时，请稍后重试"
+- 无效单号：告知用户"单号格式不正确，请检查后重新发送"
+
+## 注意事项
+
+- 每次只处理一个单号
+- API Key 通过环境变量 `TRACK17_API_KEY` 读取，不要硬编码在脚本里
+- 免费套餐每月100次查询，正式使用需升级

logistics-tracker/release.ps1

@@ -0,0 +1,220 @@
+<#
+.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"
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$sharedScript = Join-Path $scriptDir "..\jiangchang-platform-kit\tools\release.ps1"
+$sharedScript = [System.IO.Path]::GetFullPath($sharedScript)
+if (Test-Path $sharedScript) {
+  & $sharedScript @PSBoundParameters
+  exit $LASTEXITCODE
+}
+
+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
+}

logistics-tracker/scripts/main.py

@@ -0,0 +1,142 @@
+import requests
+import sys
+import os
+import subprocess
+
+
+def get_api_key(key_name):
+    """从api-key-vault读取Key"""
+    vault_path = os.path.join(
+        os.path.dirname(__file__),
+        "..", "..",          # 从scripts/退到logistics-tracker/再退到OpenClaw/
+        "api-key-vault", "scripts", "vault.py"
+    )
+    vault_path = os.path.normpath(vault_path)
+
+    result = subprocess.run(
+        ["python", vault_path, "get", key_name],
+        capture_output=True, text=True
+    )
+    key = result.stdout.strip()
+
+    if not key or key == "ERROR:KEY_NOT_FOUND":
+        return None
+    return key
+
+
+def check_entitlement(skill_slug):
+    auth_base = (os.getenv("JIANGCHANG_AUTH_BASE_URL") or "").strip().rstrip("/")
+    if not auth_base:
+        return True, ""
+
+    user_id = (os.getenv("JIANGCHANG_USER_ID") or "").strip()
+    if not user_id:
+        return False, "鉴权失败：缺少用户身份（JIANGCHANG_USER_ID）"
+
+    auth_api_key = (os.getenv("JIANGCHANG_AUTH_API_KEY") or "").strip()
+    timeout = int((os.getenv("JIANGCHANG_AUTH_TIMEOUT_SECONDS") or "5").strip())
+    headers = {"Content-Type": "application/json"}
+    if auth_api_key:
+        headers["Authorization"] = f"Bearer {auth_api_key}"
+
+    payload = {
+        "user_id": user_id,
+        "skill_slug": skill_slug,
+        "trace_id": (os.getenv("JIANGCHANG_TRACE_ID") or "").strip(),
+        "context": {"entry": "main.py"},
+    }
+    try:
+        res = requests.post(
+            f"{auth_base}/api/entitlements/check",
+            json=payload,
+            headers=headers,
+            timeout=timeout,
+        )
+    except requests.RequestException as exc:
+        return False, f"鉴权请求失败：{exc}"
+
+    if res.status_code != 200:
+        return False, f"鉴权服务异常：HTTP {res.status_code}"
+    try:
+        body = res.json()
+    except ValueError:
+        return False, "鉴权服务异常：返回非 JSON"
+
+    code = body.get("code")
+    data = body.get("data") or {}
+    if code != 200:
+        return False, str(body.get("msg") or "鉴权失败")
+    if not data.get("allow", False):
+        return False, str(data.get("reason") or "未购买或已过期")
+    return True, ""
+
+
+def query_tracking(tracking_number):
+    api_key = get_api_key("17track")
+    if not api_key:
+        return "错误：未找到17track的API Key，请先运行：\npython api-key-vault/scripts/vault.py set 17track 你的Key"
+
+    url = "https://api.17track.net/track/v2.2/gettrackinfo"
+    headers = {
+        "Content-Type": "application/json",
+        "17token": api_key
+    }
+    body = {
+        "data": [{"number": tracking_number}]
+    }
+
+    try:
+        response = requests.post(url, json=body, headers=headers, timeout=10)
+        result = response.json()
+
+        accepted = result.get("data", {}).get("accepted", [])
+        if not accepted:
+            return f"抱歉，单号 {tracking_number} 查询不到信息，可能还未入网，请稍后再试。"
+
+        track_info = accepted[0].get("track", {})
+        providers = track_info.get("tracking", {}).get("providers", [])
+
+        if not providers or not providers[0].get("events"):
+            return f"📦 单号：{tracking_number}\n该单号已入网，暂无轨迹更新，请稍后再查。"
+
+        events = providers[0]["events"]
+        latest = events[0]
+
+        recent_lines = []
+        for e in events[:3]:
+            time = e.get("time_iso", "")
+            location = e.get("location", "") or "未知"
+            desc = e.get("description", "")
+            recent_lines.append(f"  · {time}  {location}  {desc}")
+
+        recent_text = "\n".join(recent_lines)
+
+        return (
+            f"📦 单号：{tracking_number}\n"
+            f"📍 最新状态：{latest.get('description', '未知')}\n"
+            f"🕐 更新时间：{latest.get('time_iso', '未知')}\n"
+            f"🗺  最新位置：{latest.get('location', '未知')}\n\n"
+            f"最近轨迹：\n{recent_text}"
+        )
+
+    except requests.exceptions.Timeout:
+        return "查询超时，请稍后重试。"
+    except Exception as e:
+        return f"查询失败：{str(e)}"
+
+
+def main(argv=None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    if len(args) < 1:
+        print("用法：python main.py <单号>")
+        return 1
+    ok, reason = check_entitlement("logistics-tracker")
+    if not ok:
+        print(f"❌ {reason}")
+        return 1
+    print(query_tracking(args[0]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())