wechat-link 0.1.0__tar.gz

wechat_link-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/wechat-link/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

wechat_link-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.pytest_cache/
+__pycache__/
+.venv/
+.tmp-upstream/
+.state/
+dist/
+build/
+*.pyc

wechat_link-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,183 @@
+# Contributing to `wechat-link`
+
+感谢你愿意为 `wechat-link` 做贡献。
+
+这个项目欢迎协作，但它不是一个“什么都收”的大仓库。我们更重视 **协议正确性、SDK 边界清晰、媒体链路完整、Relay 保持轻薄**，而不是快速堆出一个复杂平台。
+
+如果你准备提交 Issue 或 PR，请先花 3 分钟看完这份文档。这样能显著减少来回沟通，也能帮助我们把项目长期保持在正确方向上。
+
+## 项目原则
+
+`wechat-link` 的核心目标是：
+
+> **把 iLink-compatible Weixin Bot 的关键协议整理成一个克制、可复用、可嵌入的 Python SDK，并提供一个可选的薄 Relay。**
+
+这意味着：
+
+- 欢迎让协议层更清晰、更稳定、更准确的改进
+- 欢迎提升媒体链路、错误语义、测试覆盖和文档质量的改进
+- 欢迎让 SDK 更容易被业务系统、LLM、工作流和服务端复用的改进
+- 不欢迎把项目快速推向“平台化”“后台化”“大而全框架化”
+
+## 我们特别欢迎的贡献
+
+### 1. 协议验证与纠偏
+
+例如：
+
+- 请求 / 响应字段语义修正
+- `context_token`、`get_updates_buf`、typing、media payload 等关键协议细节补充
+- 与上游行为不一致时的最小修复
+
+### 2. 媒体链路完善
+
+例如：
+
+- 图片 / 文件 / 视频 / 语音上传与发送流程的稳定性修复
+- CDN / AES 相关细节改进
+- 更清晰的参数校验、错误提示、边界处理
+
+### 3. SDK 可维护性
+
+例如：
+
+- 去重、瘦身、边界收紧
+- 更清楚的内部模块拆分
+- 不改变行为前提下的结构性整理
+
+### 4. 文档与示例
+
+例如：
+
+- README 勘误与补充
+- 更贴近真实使用场景的最小示例
+- 中英日文案一致性修正
+
+### 5. 测试
+
+例如：
+
+- 为已有行为补充回归测试
+- 为协议关键路径增加 fixture 或覆盖
+- 修正文档与代码不一致导致的测试盲区
+
+## 当前不建议提交的方向
+
+除非先讨论并达成共识，否则不建议直接提交以下类型的 PR：
+
+- 多账号管理平台
+- 大规模群控 / 运营后台
+- 营销自动化面板
+- 与协议层强耦合的大型 Bot Runtime
+- 过度抽象的插件系统
+- 自动转码 / 自动抽帧 / ffmpeg 重依赖链路
+- 没有明确上游依据的大面积“猜测式”协议扩展
+
+一句话：**优先补核心，不优先扩边界。**
+
+## 提交 Issue 之前
+
+请尽量提供以下信息：
+
+- 你使用的环境：Python 版本、安装方式、运行平台
+- 涉及的接口或模块：如 `get_updates`、`send_image`、`relay` 等
+- 复现步骤
+- 实际行为
+- 预期行为
+- 如涉及协议问题，最好附上脱敏后的请求 / 响应样例
+
+如果问题与媒体上传、CDN 或 AES 相关，附带文件类型、大小和调用参数会很有帮助。
+
+## 提交 PR 之前
+
+请先确认你的改动符合下面几个判断：
+
+- 这个改动是否让 SDK 更清晰，而不是更重？
+- 这个改动是否基于真实协议行为，而不是主观想象？
+- 这个改动是否适合作为“基础件”存在，而不是只适合某一个业务？
+- 这个改动是否保持 Relay 的薄封装定位？
+
+如果四个问题里有两个以上回答为“否”，建议先开 Issue 讨论。
+
+## 开发环境
+
+### 安装
+
+```bash
+git clone https://github.com/syusama/wechat-link.git
+cd wechat-link
+pip install -e .[dev]
+```
+
+### 运行测试
+
+```bash
+pytest -q
+```
+
+### 基本验证
+
+```bash
+python -m compileall src examples
+```
+
+## 代码与文档风格
+
+### 代码改动
+
+- 优先做小而清晰的改动
+- 尽量修根因，不做表面补丁
+- 不顺手重构无关模块
+- 不为了“未来可能会用到”引入复杂抽象
+- 保持现有 API 稳定，除非有充分理由
+
+### 文档改动
+
+- 中文文案默认作为主文案
+- 英文和日文版本应保持信息结构一致
+- 可以自然表达，但不要写成营销文案
+- 协议边界要说清楚，能力边界也要说清楚
+
+## 测试要求
+
+如果你的 PR 修改了行为或修复了问题，原则上应该：
+
+- 为该行为补测试，或补足已有测试
+- 优先写最靠近改动点的测试
+- 尽量使用最小复现，而不是构造过大的场景
+
+如果只是文档修正或纯重构，在不改变行为的前提下，也至少应确保现有测试通过。
+
+## PR Checklist
+
+提交前请自查：
+
+- [ ] 改动聚焦在一个清晰目标上
+- [ ] 没有把项目推向平台化或过度抽象
+- [ ] README / 示例 / 注释在必要时已同步
+- [ ] `pytest -q` 已运行
+- [ ] `python -m compileall src examples` 已运行（如适用）
+- [ ] 协议相关改动有依据，且描述清楚
+
+## 沟通约定
+
+- 中文 Issue / PR 欢迎
+- English Issues / PRs are also welcome
+- 如果你准备做较大的方向性改动，先开 Issue 讨论会更高效
+
+## 合规与边界
+
+`wechat-link` 是一个 **非官方项目**。
+
+请不要把它描述成腾讯官方产品、官方开放平台，或“官方替代品”。如果你的改动会影响这层定位，请在 PR 中明确说明。
+
+## 最后
+
+高质量贡献的标准，不是“功能更多”，而是：
+
+- 边界更清楚
+- 协议更准确
+- SDK 更干净
+- 使用者更容易接入
+
+如果你的 PR 往这个方向推进，它大概率就是这个项目真正需要的贡献。

wechat_link-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 syusama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wechat_link-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: wechat-link
+Version: 0.1.0
+Summary: Unofficial Python SDK for the iLink-compatible Weixin bot protocol.
+Project-URL: Homepage, https://github.com/syusama/wechat-link
+Project-URL: Repository, https://github.com/syusama/wechat-link
+Project-URL: Issues, https://github.com/syusama/wechat-link/issues
+Project-URL: Documentation, https://github.com/syusama/wechat-link#readme
+Author: syusama
+License: MIT
+License-File: LICENSE
+Keywords: bot,fastapi,ilink,relay,sdk,wechat,weixin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: cryptography<47.0,>=46.0
+Requires-Dist: httpx<1.0,>=0.28
+Requires-Dist: pillow<12.0,>=11.3
+Provides-Extra: dev
+Requires-Dist: build<2.0,>=1.2; extra == 'dev'
+Requires-Dist: fastapi<1.0,>=0.128; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.3; extra == 'dev'
+Requires-Dist: python-multipart<1.0,>=0.0.20; extra == 'dev'
+Requires-Dist: twine<7.0,>=6.1; extra == 'dev'
+Requires-Dist: uvicorn<1.0,>=0.35; extra == 'dev'
+Provides-Extra: relay
+Requires-Dist: fastapi<1.0,>=0.128; extra == 'relay'
+Requires-Dist: python-multipart<1.0,>=0.0.20; extra == 'relay'
+Requires-Dist: uvicorn<1.0,>=0.35; extra == 'relay'
+Description-Content-Type: text/markdown
+
+# wechat-link
+
+Unofficial Python SDK for iLink-compatible Weixin Bot integration.
+
+`wechat-link` 是一个面向 iLink-compatible Weixin Bot 集成的 Python SDK，重点放在协议层、媒体链路和一个可选的轻量 Relay 上，而不是去做一个大而全的 Bot 平台。
+
+## What it currently provides
+
+- QR login primitives: `get_bot_qrcode()` / `get_qrcode_status()`
+- Long polling: `get_updates()`
+- Text messaging: `send_text()`
+- Typing support: `get_config()` / `send_typing()`
+- Media workflow:
+  - `get_upload_url()`
+  - `upload_image()` / `send_image()`
+  - `upload_file()` / `send_file()`
+  - `upload_video()` / `send_video()`
+  - `upload_voice()` / `send_voice()`
+- Optional FastAPI relay layer
+
+## Installation
+
+```bash
+pip install wechat-link
+```
+
+Relay extras:
+
+```bash
+pip install "wechat-link[relay]"
+```
+
+## Quick example
+
+```python
+import time
+
+from wechat_link import FileCursorStore, WeChatLinkClient
+
+client = WeChatLinkClient(bot_token="your-bot-token")
+store = FileCursorStore(".state/get_updates_buf.json")
+cursor = store.load() or ""
+
+try:
+    while True:
+        updates = client.get_updates(cursor=cursor)
+
+        if updates.next_cursor:
+            cursor = updates.next_cursor
+            store.save(cursor)
+
+        for message in updates.messages:
+            text = message.text().strip()
+            if not text or not message.from_user_id or not message.context_token:
+                continue
+
+            client.send_text(
+                to_user_id=message.from_user_id,
+                text=f"echo: {text}",
+                context_token=message.context_token,
+            )
+
+        time.sleep(1)
+finally:
+    client.close()
+```
+
+## Project links
+
+- Repository: <https://github.com/syusama/wechat-link>
+- Issues: <https://github.com/syusama/wechat-link/issues>
+- Chinese README: <https://github.com/syusama/wechat-link/blob/main/README.md>
+- English README: <https://github.com/syusama/wechat-link/blob/main/README.en.md>
+- Japanese README: <https://github.com/syusama/wechat-link/blob/main/README.ja.md>
+
+## Notes
+
+- This is an **unofficial** project.
+- It should not be described as a Tencent official SDK or official platform replacement.
+- The PyPI page keeps the package overview concise; the full documentation and examples live in the GitHub repository.

wechat_link-0.1.0/README.assets/overview.svg

@@ -0,0 +1,97 @@
+<svg width="1200" height="760" viewBox="0 0 1200 760" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1200" height="760" rx="24" fill="#F8FAFC"/>
+  <rect x="32" y="32" width="1136" height="696" rx="20" fill="white" stroke="#E2E8F0" stroke-width="2"/>
+
+  <text x="72" y="96" fill="#0F172A" font-family="Segoe UI, Arial, sans-serif" font-size="34" font-weight="700">
+    wechat-link overview
+  </text>
+  <text x="72" y="132" fill="#475569" font-family="Segoe UI, Arial, sans-serif" font-size="18">
+    Protocol-first Python SDK for iLink-compatible Weixin Bot integration
+  </text>
+
+  <rect x="72" y="170" width="186" height="36" rx="18" fill="#EFF6FF"/>
+  <text x="103" y="193" fill="#1D4ED8" font-family="Segoe UI, Arial, sans-serif" font-size="16" font-weight="600">
+    SDK-first boundary
+  </text>
+
+  <rect x="274" y="170" width="176" height="36" rx="18" fill="#ECFDF5"/>
+  <text x="305" y="193" fill="#047857" font-family="Segoe UI, Arial, sans-serif" font-size="16" font-weight="600">
+    Thin relay only
+  </text>
+
+  <rect x="468" y="170" width="222" height="36" rx="18" fill="#F5F3FF"/>
+  <text x="500" y="193" fill="#6D28D9" font-family="Segoe UI, Arial, sans-serif" font-size="16" font-weight="600">
+    Media path included
+  </text>
+
+  <rect x="72" y="252" width="370" height="104" rx="22" fill="#F8FAFC" stroke="#CBD5E1" stroke-width="2"/>
+  <text x="108" y="298" fill="#0F172A" font-family="Segoe UI, Arial, sans-serif" font-size="28" font-weight="700">
+    Your App / LLM / Workflow
+  </text>
+  <text x="108" y="330" fill="#475569" font-family="Segoe UI, Arial, sans-serif" font-size="18">
+    Business logic, AI orchestration, internal services
+  </text>
+
+  <rect x="72" y="414" width="370" height="124" rx="22" fill="#EEF4FF" stroke="#93C5FD" stroke-width="2"/>
+  <text x="108" y="468" fill="#1D4ED8" font-family="Segoe UI, Arial, sans-serif" font-size="30" font-weight="700">
+    wechat-link SDK
+  </text>
+  <text x="108" y="500" fill="#1E40AF" font-family="Segoe UI, Arial, sans-serif" font-size="18">
+    Login primitives, polling, typing, media upload, sendmessage
+  </text>
+
+  <rect x="504" y="394" width="232" height="76" rx="18" fill="#F8FAFC" stroke="#CBD5E1" stroke-width="2"/>
+  <text x="549" y="439" fill="#0F172A" font-family="Segoe UI, Arial, sans-serif" font-size="24" font-weight="700">
+    Optional Relay
+  </text>
+
+  <rect x="72" y="594" width="256" height="92" rx="22" fill="#EFF6FF" stroke="#93C5FD" stroke-width="2"/>
+  <text x="108" y="645" fill="#1E3A8A" font-family="Segoe UI, Arial, sans-serif" font-size="28" font-weight="700">
+    iLink Bot API
+  </text>
+
+  <rect x="358" y="594" width="320" height="92" rx="22" fill="#ECFDF5" stroke="#86EFAC" stroke-width="2"/>
+  <text x="398" y="645" fill="#047857" font-family="Segoe UI, Arial, sans-serif" font-size="28" font-weight="700">
+    CDN Upload / Download
+  </text>
+
+  <rect x="712" y="594" width="216" height="92" rx="22" fill="#F5F3FF" stroke="#C4B5FD" stroke-width="2"/>
+  <text x="742" y="633" fill="#6D28D9" font-family="Segoe UI, Arial, sans-serif" font-size="24" font-weight="700">
+    AES-128-ECB
+  </text>
+  <text x="751" y="660" fill="#7C3AED" font-family="Segoe UI, Arial, sans-serif" font-size="16">
+    media encryption path
+  </text>
+
+  <rect x="804" y="252" width="302" height="80" rx="18" fill="#F8FAFC" stroke="#E2E8F0" stroke-width="2"/>
+  <circle cx="840" cy="292" r="8" fill="#2563EB"/>
+  <text x="862" y="299" fill="#0F172A" font-family="Segoe UI, Arial, sans-serif" font-size="20" font-weight="600">
+    QR login primitives
+  </text>
+
+  <rect x="804" y="350" width="302" height="80" rx="18" fill="#F8FAFC" stroke="#E2E8F0" stroke-width="2"/>
+  <circle cx="840" cy="390" r="8" fill="#0F766E"/>
+  <text x="862" y="397" fill="#0F172A" font-family="Segoe UI, Arial, sans-serif" font-size="20" font-weight="600">
+    Long polling + cursor store
+  </text>
+
+  <rect x="804" y="448" width="302" height="80" rx="18" fill="#F8FAFC" stroke="#E2E8F0" stroke-width="2"/>
+  <circle cx="840" cy="488" r="8" fill="#7C3AED"/>
+  <text x="862" y="495" fill="#0F172A" font-family="Segoe UI, Arial, sans-serif" font-size="20" font-weight="600">
+    Text, typing, context_token
+  </text>
+
+  <rect x="804" y="546" width="302" height="80" rx="18" fill="#F8FAFC" stroke="#E2E8F0" stroke-width="2"/>
+  <circle cx="840" cy="586" r="8" fill="#DC2626"/>
+  <text x="862" y="593" fill="#0F172A" font-family="Segoe UI, Arial, sans-serif" font-size="20" font-weight="600">
+    Image, file, video, voice
+  </text>
+
+  <path d="M256 356L256 414" stroke="#94A3B8" stroke-width="4" stroke-linecap="round"/>
+  <path d="M620 470L620 594" stroke="#94A3B8" stroke-width="4" stroke-linecap="round"/>
+  <path d="M256 538L256 594" stroke="#94A3B8" stroke-width="4" stroke-linecap="round"/>
+  <path d="M442 470L504 432" stroke="#94A3B8" stroke-width="4" stroke-linecap="round"/>
+  <path d="M736 432L804 432" stroke="#94A3B8" stroke-width="4" stroke-linecap="round"/>
+  <path d="M442 500L804 500" stroke="#94A3B8" stroke-width="4" stroke-linecap="round"/>
+  <path d="M678 640L712 640" stroke="#94A3B8" stroke-width="4" stroke-linecap="round"/>
+</svg>