重构项目路径

README.md

@@ -1,8 +1,65 @@
 # jiangchang-platform-kit
 
-Shared platform components for Jiangchang skills:
+## 1. 项目简介
 
-- `sdk/jiangchang_skill_core`: entitlement SDK package.
-- `python-runtime/`: **shared third-party dependencies** (`pyproject.toml` + `uv.lock`) for all skills; keep in sync with the desktop app `resources/jiangchang-python-runtime/`.
-- `.github/workflows/reusable-release-skill.yaml`: reusable CI release workflow.
-- `examples/workflows/use-reusable-release-skill.yaml`: caller workflow sample.
+匠厂平台共享 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. 发版流程（维护者）
+
+```bash
+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 包的发布彼此独立。