feat: add standalone channel sdk

.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - "feat/**"
+      - "release/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.8"
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: setup.py
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest -q
+
+  package:
+    name: Build package
+    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.11"
+          cache: pip
+          cache-dependency-path: setup.py
+
+      - name: Install packaging tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build wheel and source distribution
+        run: python -m build --sdist --wheel --outdir dist .
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: lark-channel-sdk-dist
+          path: dist/*

.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Test and coverage artifacts
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Build and packaging artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Local environment files
+.env
+.env.*
+!.env.example
+
+# Python tooling caches
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# OS and editor noise
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo

MANIFEST.in

@@ -0,0 +1,10 @@
+global-exclude */__pycache__/*
+global-exclude *.pyc
+global-exclude .pytest_cache/*
+include LICENSE
+include THIRD_PARTY_NOTICES.md
+include README.md
+include README.zh.md
+recursive-include docs *.md
+recursive-include samples/channel *.py
+prune tests

README.md

@@ -0,0 +1,103 @@
+# Lark Channel SDK for Python
+
+`lark-channel-sdk` is a Python package for building Feishu and Lark
+conversational bots. It provides `FeishuChannel` as the main entry point for
+event listening, message normalization, policy control, outbound messaging,
+media handling, card callbacks, and streaming replies.
+
+## Install
+
+```bash
+pip install lark-channel-sdk
+```
+
+## Minimal Example
+
+```python
+import asyncio
+import os
+
+from lark_channel import FeishuChannel
+
+channel = FeishuChannel(
+    app_id=os.environ["LARK_APP_ID"],
+    app_secret=os.environ["LARK_APP_SECRET"],
+)
+
+
+async def on_message(msg):
+    await channel.send(
+        msg.chat_id,
+        {"markdown": f"received: {msg.content_text}"},
+        {"reply_to": msg.message_id},
+    )
+
+
+channel.on("message", on_message)
+asyncio.run(channel.connect())
+```
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Migration from `lark_oapi.channel`](docs/migration-from-lark-oapi.md)
+- [API reference](docs/reference.md)
+- [Security configuration](docs/security.md)
+- [Markdown messages](docs/markdown.md)
+- [Webhook server adapter](docs/webhook-server.md)
+- [CardKit streaming](docs/cardkit-streaming.md)
+- [Deduplication architecture](docs/dedup-architecture.md)
+- [Release notes](docs/release-notes/v1.0.0.md)
+- [Echo bot sample](samples/channel/echo_bot.py)
+
+## Migration from `lark_oapi.channel`
+
+Install the standalone package and update the import path:
+
+```bash
+pip install lark-channel-sdk
+```
+
+```python
+from lark_channel import FeishuChannel
+```
+
+`lark-channel-sdk` can be installed alongside `lark-oapi`. Use
+`lark-channel-sdk` for Channel bot workflows and keep using `lark-oapi` when
+your application needs the full OpenAPI SDK surface.
+
+See the [migration guide](docs/migration-from-lark-oapi.md) for import mapping,
+runtime compatibility notes, and a migration checklist.
+
+## Security Mode
+
+`SecurityConfig` defaults to compatibility mode so existing bots continue to
+run during migration. For production rollout, start with audit mode and then
+move to strict mode after reviewing audit events:
+
+```python
+from lark_channel import FeishuChannel, SecurityConfig
+
+channel = FeishuChannel(
+    app_id="cli_xxx",
+    app_secret="***",
+    security=SecurityConfig(mode="audit"),
+)
+```
+
+See [Security configuration](docs/security.md) for strict-mode behavior and
+webhook compatibility switches.
+
+## Local Development
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+## License
+
+This distribution is licensed as `MIT AND BSD-3-Clause`: project code is
+licensed under the MIT License as described in [LICENSE](LICENSE), and vendored
+third-party code is documented in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

README.zh.md

@@ -0,0 +1,98 @@
+# Lark Channel Python SDK
+
+`lark-channel-sdk` 是用于构建飞书和 Lark 会话式机器人的 Python 包。它以
+`FeishuChannel` 为主要入口，封装事件监听、消息归一化、策略控制、出站消息、
+媒体处理、卡片回调和流式回复。
+
+## 安装
+
+```bash
+pip install lark-channel-sdk
+```
+
+## 最小示例
+
+```python
+import asyncio
+import os
+
+from lark_channel import FeishuChannel
+
+channel = FeishuChannel(
+    app_id=os.environ["LARK_APP_ID"],
+    app_secret=os.environ["LARK_APP_SECRET"],
+)
+
+
+async def on_message(msg):
+    await channel.send(
+        msg.chat_id,
+        {"markdown": f"received: {msg.content_text}"},
+        {"reply_to": msg.message_id},
+    )
+
+
+channel.on("message", on_message)
+asyncio.run(channel.connect())
+```
+
+## 文档
+
+- [快速开始](docs/quickstart.md)
+- [从 `lark_oapi.channel` 迁移](docs/migration-from-lark-oapi.md)
+- [API 参考](docs/reference.md)
+- [安全配置](docs/security.md)
+- [Markdown 消息](docs/markdown.md)
+- [Webhook 服务适配](docs/webhook-server.md)
+- [CardKit 流式回复](docs/cardkit-streaming.md)
+- [去重架构](docs/dedup-architecture.md)
+- [发布说明](docs/release-notes/v1.0.0.md)
+- [Echo bot 示例](samples/channel/echo_bot.py)
+
+## 从 `lark_oapi.channel` 迁移
+
+安装独立包并更新 import 路径：
+
+```bash
+pip install lark-channel-sdk
+```
+
+```python
+from lark_channel import FeishuChannel
+```
+
+`lark-channel-sdk` 可以与 `lark-oapi` 安装在同一环境中。Channel bot 工作流使用
+`lark-channel-sdk`；如果应用需要完整 OpenAPI SDK 能力，继续使用 `lark-oapi`。
+
+详见 [迁移手册](docs/migration-from-lark-oapi.md)，其中包含 import 映射、运行时兼容
+说明和迁移检查清单。
+
+## 安全模式
+
+`SecurityConfig` 默认使用兼容模式，便于已有机器人平滑迁移。生产发布建议先使用
+audit 模式观察安全审计事件，再切换到 strict 模式：
+
+```python
+from lark_channel import FeishuChannel, SecurityConfig
+
+channel = FeishuChannel(
+    app_id="cli_xxx",
+    app_secret="***",
+    security=SecurityConfig(mode="audit"),
+)
+```
+
+strict 模式行为和 webhook 兼容开关详见 [安全配置](docs/security.md)。
+
+## 本地开发
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+## 许可证
+
+本发布包的许可证表达式为 `MIT AND BSD-3-Clause`：项目主体代码使用
+MIT License，详见 [LICENSE](LICENSE)；vendored 第三方代码详见
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,46 @@
+# Third-party notices
+
+This distribution includes vendored third-party code. The project code is
+licensed under the MIT License as described in `LICENSE`; the third-party code
+listed below remains under its own license.
+
+## Protocol Buffers Python runtime
+
+- Path: `lark_channel/ws/pb/google/protobuf`
+- Version: 3.20.3
+- License: BSD-3-Clause
+- Source project: https://github.com/protocolbuffers/protobuf
+
+```text
+Protocol Buffers - Google's data interchange format
+Copyright 2008 Google Inc.  All rights reserved.
+https://developers.google.com/protocol-buffers/
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+    * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Copyright 2007 Google Inc. All Rights Reserved.
+```