client-jiangchang/jiangchang-platform-kit

Files

chendelian 4fc4cfb802 refactor(sdk): drop data-jcid, switch to semantic anchors + ClawX testids

- Introduce centralized SELECTOR constant table at top of client.py
- Replace all [data-jcid=...] selectors with:
  * Semantic anchors (data-role / data-message-id / data-streaming /
    data-sending / data-message-count) guarded by jiangchang main repo
  * ClawX upstream data-testids (chat-page / chat-composer-* / etc.)
- _latest_assistant_after: has_body now judged by inner_text non-empty
  (no longer depends on message-body sub-element)
- _gateway_state: degrade to window.__jc_gateway_state__ readback,
  returns 'unknown' until host exposes it
- new_task: rely solely on data-message-count==0 (welcome-screen no
  longer has a testid)
- wait_gateway_ready: degrade to chat-page selector wait
- send_file: raise NotImplementedError (Electron IPC hook missing)

Public API signatures unchanged. window.__jc_sending__ remains the
core sending signal.

Compatibility: jiangchang v2.0.17+ only.
Refs: jiangchang/docs/sdk-migration-discovery.md
      jiangchang/docs/JIANGCHANG_CUSTOM_ANCHORS.md
Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-18 16:05:04 +08:00

4.2 KiB

Raw Blame History

jiangchang-platform-kit

1. 项目简介

匠厂平台共享 Python SDK：在同一发行包中提供 Skill 侧通用能力（权益校验、统一日志与运行环境解析）与 桌面应用自动化能力（通过 CDP 连接匠厂客户端，驱动聊天与断言）。

2. 安装方式

pip install jiangchang-platform-kit --index-url https://git.jc2009.com/api/packages/client-jiangchang/pypi/simple/

3. 包含的模块

jiangchang_skill_core：权益 HTTP 客户端、enforce_entitlement、统一文件日志、JIANGCHANG_* 数据根与技能根路径解析等，供 Skill CLI / 服务进程使用。
jiangchang_desktop_sdk：匠厂桌面应用自动化客户端（基于 CDP + Playwright 同步 API）。本包不声明 Playwright 依赖；请在运行环境中自行安装 Playwright，以便 import playwright 可用。

4. 快速开始

jiangchang_skill_core

import os
from jiangchang_skill_core import (
    EntitlementClient,
    enforce_entitlement,
    setup_skill_logging,
    get_skill_logger,
)

os.environ.setdefault("JIANGCHANG_AUTH_BASE_URL", "https://auth.example.com")
os.environ.setdefault("JIANGCHANG_AUTH_API_KEY", "secret")

setup_skill_logging(skill_slug="demo-skill", logger_name="demo")
log = get_skill_logger()
log.info("skill started")

# client = EntitlementClient()
# enforce_entitlement(user_id="u1", skill_slug="demo-skill")

jiangchang_desktop_sdk

from jiangchang_desktop_sdk import JiangchangDesktopClient, AskOptions

# 需已安装 playwright，且匠厂客户端可按 CDP 端口暴露调试接口
client = JiangchangDesktopClient()
client.ensure_app_running(wait_timeout_s=30.0)
try:
    answer = client.ask("你好", options=AskOptions(new_task=True))
    print(answer)
finally:
    client.disconnect()

5. 发版流程（维护者）

git tag v0.1.0
git push origin v0.1.0
# CI 自动打包并发布到 Gitea Package Registry（见 .github/workflows/publish.yml）

仓库内还保留 examples/、tools/、python-runtime/ 目录及既有 Skill / 前端相关的 GitHub Actions 工作流，与本 PyPI 包的发布彼此独立。

v0.2.0 — data-jcid migration (internal refactor)

TL;DR

本次内部重构:SDK 不再依赖匠厂主仓库的 data-jcid 属性。所有公开 API(ask / read / new_task / wait_gateway_ready 等) 签名与行为保持不变,只有内部选择器实现切换到新的语义锚点 + ClawX testid。

改变了什么

client.py 内所有 [data-jcid="..."] 选择器已移除
改用匠厂主仓库为 SDK 承诺的语义锚点:data-role / data-message-id / data-streaming(在 ChatMessage 上)、data-sending / data-message-count (在 chat-page 根上)
window.__jc_sending__ 仍是核心 sending 信号,保持不变
这些锚点由匠厂主仓库的以下机制守护:
- docs/JIANGCHANG_CUSTOM_ANCHORS.md 中央清单
- 源码内 JIANGCHANG CUSTOM ANCHOR 边界注释
- harness/specs/jiangchang-custom-anchors.spec.ts E2E 守护测试
- Gitea CI grep 检查 step

已知限制

send_file() 暂未实现,抛 NotImplementedError。原因:附件上传走 Electron IPC,SDK 需要主仓库提供新 hook。
_gateway_state() 永远返回 'unknown'。原因:gateway 状态不再暴露 DOM data-state;本方法已预留未来通过 window.__jc_gateway_state__ 读取的实现路径。

这两个限制对常规 ask/read 工作流无影响,sending 完成判定依靠 window.__jc_sending__ + data-sending + 文本稳定性合流即可。

升级影响

在 jiangchang v2.0.17(含)以上版本上跑:应正常工作
在 jiangchang v2.0.16(及更早含 data-jcid 的版本)上跑:不再兼容如果需要在旧版本上跑,固定 SDK 版本到 v0.1.x

验证清单(集成方建议跑一次)

打开匠厂客户端 → 用 SDK 跑下面 3 步,确认基础流程通:

from jiangchang_desktop_sdk import JiangchangDesktopClient

with JiangchangDesktopClient() as c:
    c.ensure_app_running()
    c.wait_gateway_ready()
    c.new_task()
    answer = c.ask("你好,请回复确认 SDK 可用")
    assert answer, f"Empty answer: {answer!r}"
    print("OK:", answer[:200])

4.2 KiB Raw Blame History Unescape Escape