# jiangchang-platform-kit

## 1. 项目简介

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

## 2. 安装方式

```bash
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

```python
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

```python
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. 发版流程（维护者）

### main 分支自动预发布

每次推送到 `main` 会触发 `.github/workflows/publish.yml`，自动构建并发布 **唯一** 的 post 版本（基于 `pyproject.toml` 中的基础版本，例如 `0.1.0.post42`）。版本号不会写回仓库，仅在 CI 构建前临时改写 `pyproject.toml` 与 `jiangchang_desktop_sdk.__version__`。

```bash
git push origin main
```

测试人员升级安装：

```bash
python -m pip install --upgrade \
  --index-url https://git.jc2009.com/api/packages/client-jiangchang/pypi/simple/ \
  --extra-index-url https://pypi.org/simple \
  jiangchang-platform-kit
```

### 正式版本（tag）

打 tag 并推送后，发布 **去掉 `v` 前缀** 的正式版本号（例如 `v0.1.1` → PyPI 包 `0.1.1`）：

```bash
git tag v0.1.1
git push origin v0.1.1
```

### 安装后验证

```bash
python -c "from jiangchang_desktop_sdk.e2e_helpers import send_prompt_via_composer; print('e2e_helpers OK')"
python -c "from screencast import run_screencast; print('screencast OK')"
```

仓库内还保留 `examples/`、`tools/`、`python-runtime/` 目录及既有 Skill / 前端相关的 GitHub Actions 工作流，与本 PyPI 包的发布彼此独立。`tools/screencast/` 为兼容薄壳，pip 包内实现位于 `screencast` 包（`src/screencast/`）。

## 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 步,确认基础流程通:

```python
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])
```