[Feature] 评估提供 Python SDK / Python 调用示例

[FenjuFu]

Problem

SkillHub already exposes a complete REST API, but the repository has no Python SDK or Python calling examples. Recent real stargazer samples skew strongly toward Python, so Python developers currently have no code-level onboarding path and must translate the API documentation themselves or shell out to the CLI.

Proposed solution

Land the low-cost first step in #702: a requests-only Python client and runnable examples for search, detail, resolve, download, publish, star, and rate. Treat a published pip install skillhub SDK as a separate maintainer decision because packaging, semantic versioning, release CI, and long-term API compatibility add ongoing maintenance cost; an OpenAPI-generated client is another option to evaluate.

背景 / 动机

近期一批真实新 Star 用户样本（60 人）的兴趣语言分布中，Python 遥遥领先（约 481）而 Java 仅约 77——与 SkillHub 自身 Java 后端的定位存在明显偏移。也就是说，被 SkillHub 吸引来的受众里，Python 开发者占绝对多数，但仓库当前没有面向 Python 的接入路径，容易造成「看了文档但不上手」的流量浪费。

现状核查（提交前已查）

• ✅ REST API 已完整：公开 API（搜索/详情/版本/解析/下载）+ 认证 API（发布/收藏/评分/命名空间）+ ClawHub CLI 兼容层，见 document/docs/04-developer/api。
• ✅ Web 端有 OpenAPI TypeScript 类型；CLI 走 ClawHub 兼容。
• ❌ 仓库内没有任何 Python SDK 或 Python 调用示例（scanner/ 是 Python 写的安全扫描服务，不是集成 SDK）。
• 🔎 已搜 open/closed issues（python/SDK/客户端/调用示例/pip）、已合并与在途 PR、以及 releases 到 v0.2.16 —— 均无 Python SDK/示例，也无重复提案。

建议（分两步）

第一步（低成本、马上可用）：提供轻量 Python 调用示例，放在 examples/python/，仅依赖 requests，覆盖 search / detail / resolve / download / publish / star / rate，作为 Python 集成的起点，同时充当「参考 SDK 种子」。

• 已附带 PR 实现：docs(examples): add Python client and usage examples #702。

第二步（需 maintainer 决策）：评估是否投入正式发布的 pip SDK（pip install skillhub）。这涉及打包、语义版本、发布 CI、以及长期维护成本，建议由维护者权衡后再定；也可考虑用 OpenAPI 规范自动生成客户端以降低维护负担。

收益

• 直接承接占多数的 Python 受众，降低「Java 定位 vs Python 受众」的错位带来的流量流失。
• 让自动化 / Agent 编排场景（Python 生态最活跃）能直接以代码方式调用 SkillHub，而不必 shell out 到 CLI。

如果方向 OK，第一步的示例 PR 可以直接合入；第二步的 pip SDK 想听听维护者意见。

[github-actions]

Issue Triage

• Route: triage/core
• Priority: priority/p1 (3.8/5)
• Effort: effort/l (4/5)
• Confidence: 4/5
• Risk: high
• Analysis Mode: rules-only

Why

• Touches core SkillHub workflows (publish, search, scanner).
• Text suggests a bounded change (docs, documentation).
• Thread already has follow-up discussion, so backlog pressure is rising.

High-Risk Signals

• Mentions sensitive areas (openapi, sdk).

Maintainer Brief

Summary: SkillHub already exposes a complete REST API, but the repository has no Python SDK or Python calling examples. Recent real stargazer samples skew strongly toward Python, so Python developers currently have no code-level onboarding path and must translate the API documentation themselves or shell out to the CLI.
Why core:

• Touches a higher-risk area where automated fixes should not be trusted without maintainer review.
• Likely spans multiple modules or a public compatibility surface.
• Mentions sensitive areas (openapi, sdk).
  Reproduction or operator path:
• SkillHub already exposes a complete REST API, but the repository has no Python SDK or Python calling examples. Recent real stargazer samples skew strongly toward Python, so Python developers currently have no code-level onboarding path and must translate the API documentation themselves or shell out to the CLI.
  Suspected areas:
• Public API contract, generated SDKs, and compatibility surface
• Documentation, operator guidance, and CLI help output
  Risks to watch:
• Mentions sensitive areas (openapi, sdk).
  Validation checklist:
• Validate the primary reported workflow end-to-end after the fix.
• Update or verify documentation and CLI help output so they match the implemented behavior.
• Check for downstream API/SDK/CLI compatibility expectations before shipping.

Next Action

• Hand the issue to a core maintainer and use a local programming agent for reproduction, scoping, and validation.

---

问题分流结果

• 路由: triage/core
• 优先级: priority/p1 (3.8/5)
• 修复投入: effort/l (4/5)
• 信息完整度: 4/5
• 风险: 高
• 分析模式: rules-only

原因

• 涉及 SkillHub 核心流程（publish, search, scanner）
• 文本显示改动范围较可控（docs, documentation）
• 已有后续讨论，积压压力在上升

高风险信号

• 提到敏感区域（openapi, sdk）

维护者交接摘要

概要: SkillHub already exposes a complete REST API, but the repository has no Python SDK or Python calling examples. Recent real stargazer samples skew strongly toward Python, so Python developers currently have no code-level onboarding path and must translate the API documentation themselves or shell out to the CLI.
为何进入 core:

• 触及高风险区域，未经 maintainer 审查不应直接信任自动修复
• 大概率跨多个模块或公共兼容面
• 提到敏感区域（openapi, sdk）
  复现路径或操作路径:
• SkillHub already exposes a complete REST API, but the repository has no Python SDK or Python calling examples. Recent real stargazer samples skew strongly toward Python, so Python developers currently have no code-level onboarding path and must translate the API documentation themselves or shell out to the CLI.
  怀疑影响区域:
• 公开 API 契约、生成 SDK 与兼容性表面
• 文档、操作指引与 CLI help 输出
  重点风险:
• 提到敏感区域（openapi, sdk）
  验证清单:
• 修复后端到端验证主报告流程
• 更新或核对文档与 CLI help 输出，确保其与实现行为一致
• 发布前检查下游 API/SDK/CLI 的兼容性预期

下一步

• 交给 core maintainer，并结合本地编程Agent协助完成复现、收敛范围与验证闭环

[FenjuFu]

/retriage

[FenjuFu]

/retriage

[FenjuFu]

/retriage

[FenjuFu]

/retriage