agylark 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
agylark-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 starswei
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
agylark-0.1.1/PKG-INFO ADDED
@@ -0,0 +1,190 @@
1
+ Metadata-Version: 2.4
2
+ Name: agylark
3
+ Version: 0.1.1
4
+ Summary: A lightweight, native-ACP bridge between Antigravity (agy) and Feishu / Lark via lark-oapi.
5
+ Author: starswei
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/starswei/agy-lark
8
+ Project-URL: Repository, https://github.com/starswei/agy-lark
9
+ Project-URL: Issues, https://github.com/starswei/agy-lark/issues
10
+ Keywords: antigravity,agy,acp,feishu,lark,bridge,chatbot
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Requires-Python: >=3.11
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: lark-oapi>=1.4.0
22
+ Provides-Extra: dev
23
+ Requires-Dist: pytest>=8.0; extra == "dev"
24
+ Requires-Dist: ruff>=0.6.0; extra == "dev"
25
+ Dynamic: license-file
26
+
27
+ <div align="center">
28
+
29
+ <picture>
30
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/Logo-dark.svg" />
31
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/Logo.svg" />
32
+ <img src="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/Logo.svg" alt="agy-lark Logo" width="180" />
33
+ </picture>
34
+
35
+ # agy-lark
36
+
37
+ **Chat with local Antigravity directly from Feishu / Lark.**
38
+
39
+ **在飞书里直接驱动本地 Antigravity,轻量直连。**
40
+
41
+ A lightweight, native-ACP Feishu / Lark bridge powered by the official Python `lark-oapi` SDK —
42
+ delivering live streaming cards, mid-turn steering, timely cancellation via `session/cancel`, and interactive `/model` & `/effort` selection.
43
+
44
+ [![CI](https://github.com/starswei/agy-lark/actions/workflows/ci.yml/badge.svg)](https://github.com/starswei/agy-lark/actions/workflows/ci.yml)
45
+ [![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/starswei/agy-lark/blob/main/LICENSE)
46
+ [![Version](https://img.shields.io/badge/version-0.1.1-blue)](https://github.com/starswei/agy-lark/releases)
47
+
48
+ [English](https://github.com/starswei/agy-lark/blob/main/README.md) | [中文](https://github.com/starswei/agy-lark/blob/main/README.zh-CN.md)
49
+
50
+ </div>
51
+
52
+ ---
53
+
54
+ > [!NOTE]
55
+ > **Project Status (`v0.1.1`)**: End-to-end Feishu / Lark ↔ local `agy acp --stdio` bridging is complete and verified across the offline unit/integration test suite and live Feishu sessions — featuring Fail-Closed `open_id` authorization, a single-process `lark-oapi` WebSocket daemon, persistent cross-restart ACP session recovery (`session/resume`), CardKit 2.0 streaming cards, mid-turn steering, `/stop` cancellation, and single-column `/model` & `/effort` interactive selector cards.
56
+
57
+ ## What You Get
58
+
59
+ | Scenario | What `agy-lark` Does | What You Get |
60
+ | :--- | :--- | :--- |
61
+ | **Remote Coding via Chat** | Maps Feishu / Lark DM, thread, or `@bot` messages to persistent `agy` ACP sessions | Drive your local project workspace right from mobile or desktop chat |
62
+ | **Mid-Turn Steering** | Delivers follow-up instructions via `session/prompt` while a turn is actively running | Redirect or refine long tasks on the fly without waiting or restarting |
63
+ | **Timely Cancellation** | Card stop actions or `/stop` issue native ACP `session/cancel` for the active turn | Halts the current task cleanly while keeping full conversation context intact |
64
+ | **Live Streaming Cards** | Sends and updates CardKit 2.0 interactive cards in-process via `lark-oapi` with throttling | Real-time progress and Markdown replies in one clean card |
65
+ | **Model & Effort Control** | Supports `AGY_MODEL` / `AGY_EFFORT` defaults plus decoupled `/model` & `/effort` single-column cards | Switch models or multi-level thinking intensity interactively per conversation |
66
+ | **Lightweight Setup** | Runs in a single Python process over WebSocket and auto-discovers `agy` from `PATH` | Requires only Python 3.11+, `lark-oapi`, and basic app configuration to start |
67
+
68
+ ## Architecture
69
+
70
+ `agy-lark` runs as a single Python process sitting cleanly between two protocol boundaries:
71
+
72
+ <p align="center">
73
+ <picture>
74
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/architecture-dark.svg" />
75
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/architecture-light.svg" />
76
+ <img src="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/architecture-light.svg" alt="agy-lark architecture: Feishu / Lark ↔ agy-lark ↔ Antigravity" width="100%" />
77
+ </picture>
78
+ </p>
79
+
80
+ - **Unified In-Process Feishu Transport (`lark-oapi`)**: Handles both message events (`im.message.receive_v1`) and card button callbacks (`card.action.trigger`) over a single WebSocket connection, while creating and streaming CardKit 2.0 updates over HTTPS.
81
+ - **Direct Native ACP (`agy acp --stdio`)**: Drives local sessions over bidirectional stdio JSON-RPC, enabling **mid-turn steering**, protocol-level **`session/cancel`**, and decoupled **`model` / `effort`** configuration.
82
+
83
+ <!--
84
+ ## Preview
85
+
86
+ Uncomment after adding real Feishu / Lark card captures under `docs/assets/`:
87
+
88
+ <table>
89
+ <tr>
90
+ <td><img src="docs/assets/01-streaming-card.png" alt="Streaming Card" width="100%"/><br/><sub>Live CardKit 2.0 streaming reply with stop control</sub></td>
91
+ <td><img src="docs/assets/02-steering.png" alt="Mid-Turn Steering" width="100%"/><br/><sub>Sending follow-up guidance mid-turn without losing context</sub></td>
92
+ </tr>
93
+ </table>
94
+ -->
95
+
96
+ ## Quick Start
97
+
98
+ ### Prerequisites
99
+
100
+ 1. **Python 3.11+** (developed & verified with `3.13.9`)
101
+ 2. **Antigravity CLI (`agy`)** installed locally and authenticated, with `agy` available on `PATH` (or configured via `AGY_EXE`)
102
+ 3. **A Feishu / Lark Custom App** with Bot capability enabled:
103
+ - Event subscription delivery mode: **Persistent Connection (WebSocket)**
104
+ - Subscribe to `im.message.receive_v1` and card callback `card.action.trigger`
105
+ - Required IM / CardKit bot permissions granted and app published
106
+
107
+ ### Installation & Configuration
108
+
109
+ **Option 1: Install from GitHub Releases or PyPI (after `agylark` is published to PyPI)**
110
+
111
+ ```bash
112
+ # Isolated CLI installation (recommended by PyPA once published to PyPI):
113
+ pipx install agylark
114
+ # or with uv:
115
+ uv tool install agylark
116
+ # or directly from a downloaded GitHub Release wheel inside a venv:
117
+ pip install ./agylark-<version>-py3-none-any.whl
118
+ ```
119
+
120
+ **Option 2: Install from Source**
121
+
122
+ ```bash
123
+ git clone https://github.com/starswei/agy-lark.git
124
+ cd agy-lark
125
+
126
+ python -m venv .venv
127
+ # Windows PowerShell: .venv\Scripts\Activate.ps1
128
+ # macOS / Linux: source .venv/bin/activate
129
+
130
+ pip install -e .
131
+ cp .env.example .env
132
+ # Fill in FEISHU_APP_ID, FEISHU_APP_SECRET, and AGY_LARK_ALLOWED_OPEN_IDS
133
+ ```
134
+
135
+ - **Optional presets**: Set `AGY_MODEL` and `AGY_EFFORT` in `.env` to auto-apply a preferred default model and thinking intensity on new ACP sessions, or leave them blank to use Antigravity's defaults.
136
+ - **Portable `.env` paths**: Relative paths configured inside `.env` (`AGY_DEFAULT_WORKSPACE`, `AGY_EXE`, `AGY_LARK_DATA_DIR`) resolve relative to the `.env` file's directory; externally set OS environment variables still resolve against the process current working directory (`CWD`).
137
+
138
+ > [!TIP]
139
+ > **`AGY_LARK_ALLOWED_OPEN_IDS` is your access allowlist**: list the Feishu / Lark user `open_id` values (`ou_...`, comma-separated) permitted to drive your local `agy`. Since the bridge grants chat access to your local workspace, leaving it empty rejects all requests by default for safety.
140
+
141
+ ### Starting the Daemon
142
+
143
+ ```bash
144
+ agylark --env-file .env -v
145
+ ```
146
+
147
+ - Also available via the compatible `agy-lark` CLI alias (`pip install -e .` installs both `agylark` and `agy-lark`).
148
+
149
+ - `--env-file`: Path to your `.env` file (defaults to `.env` in the current directory; pass `""` to skip loading a `.env` file and read process environment variables only).
150
+ - `--verbose` / `-v`: Enables `DEBUG`-level logging (overrides `AGY_LARK_LOG_LEVEL`).
151
+
152
+ ### Chat Commands
153
+
154
+ Send standalone slash commands in an authorized DM, group thread, or `@bot` mention (when enabled); text containing extra arguments passes through as a normal prompt:
155
+
156
+ - **`/stop`**: Issues ACP `session/cancel` for the active turn in the current conversation (equivalent to clicking the card's Stop button).
157
+ - **`/model`**: Sends a single-column CardKit 2.0 selector card listing available models; selecting a model updates only the session's model without overwriting thinking effort.
158
+ - **`/effort`**: Sends a single-column CardKit 2.0 selector card listing supported thinking intensity levels for the active model (including multi-level configurations such as 4 levels).
159
+
160
+ ### Running Tests
161
+
162
+ Run the offline unit and daemon integration suite directly from the repository root:
163
+
164
+ ```bash
165
+ python -W error -m unittest discover -s tests -v
166
+ ```
167
+
168
+ To also include the optional real `agy acp` cross-restart E2E test (requires a locally installed and authenticated `agy` CLI), set `AGY_LARK_REAL_AGY_E2E=1`.
169
+
170
+ ## Runtime & Safety Design
171
+
172
+ `agy-lark` is designed around explicit, fail-closed operational boundaries:
173
+
174
+ - **Fail-Closed Authorization**: If `AGY_LARK_ALLOWED_OPEN_IDS` is empty, **all** incoming messages and card actions (`stop`, `model`, `effort`) are rejected by default. Group `@mention` routing is disabled unless `AGY_LARK_ALLOW_GROUP_MENTION=true` is explicitly set.
175
+ - **Cross-Platform `agy` Discovery**: Resolves `AGY_EXE` first if set, otherwise looks up `agy` via `PATH` — no hardcoded OS-specific installation paths.
176
+ - **Throttled Streaming & Turn Safety**: Coalesces high-frequency ACP output chunks via `AGY_LARK_STREAM_THROTTLE` (default `0.25s`), enforces per-turn timeouts (`AGY_TURN_TIMEOUT_SECONDS`), and cleans up child pipes via ACP cancellation on `SIGINT` / `SIGTERM`.
177
+ - **Persistent Session & Config Recovery**: Atomically persists isolated conversation mappings (`p2p:<chat_id>`, thread aliases, and reply message bindings), workspace `cwd`, and selected model/effort in `{AGY_LARK_DATA_DIR}/sessions.json`. After a daemon or ACP subprocess restart, the first incoming turn or command resumes the prior session on demand via `session/resume` and replays its saved model and effort — safely falling back to a new session (or default settings) with an explicit diagnostic notice if the workspace changed, the session expired, or a saved option is unavailable.
178
+
179
+ ## Privacy Notice
180
+
181
+ `agy-lark` strictly separates **public repository assets** from **private local runtime state**:
182
+
183
+ - **Tracked in Git**: source code (`src/agylark/`), unit tests (`tests/`), `.env.example`, `pyproject.toml`, `LICENSE`, documentation, and logo assets.
184
+ - **Local-only (`.gitignore`)**: `.env`, `FEISHU_APP_SECRET`, authorized `open_id` lists, `.agy-lark/`, `sessions.json`, logs, state/database files, and `.venv/`.
185
+
186
+ **Never commit `.env` or runtime state files to a public repository.**
187
+
188
+ ## License
189
+
190
+ [MIT](https://github.com/starswei/agy-lark/blob/main/LICENSE)
@@ -0,0 +1,164 @@
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/Logo-dark.svg" />
5
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/Logo.svg" />
6
+ <img src="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/Logo.svg" alt="agy-lark Logo" width="180" />
7
+ </picture>
8
+
9
+ # agy-lark
10
+
11
+ **Chat with local Antigravity directly from Feishu / Lark.**
12
+
13
+ **在飞书里直接驱动本地 Antigravity,轻量直连。**
14
+
15
+ A lightweight, native-ACP Feishu / Lark bridge powered by the official Python `lark-oapi` SDK —
16
+ delivering live streaming cards, mid-turn steering, timely cancellation via `session/cancel`, and interactive `/model` & `/effort` selection.
17
+
18
+ [![CI](https://github.com/starswei/agy-lark/actions/workflows/ci.yml/badge.svg)](https://github.com/starswei/agy-lark/actions/workflows/ci.yml)
19
+ [![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/starswei/agy-lark/blob/main/LICENSE)
20
+ [![Version](https://img.shields.io/badge/version-0.1.1-blue)](https://github.com/starswei/agy-lark/releases)
21
+
22
+ [English](https://github.com/starswei/agy-lark/blob/main/README.md) | [中文](https://github.com/starswei/agy-lark/blob/main/README.zh-CN.md)
23
+
24
+ </div>
25
+
26
+ ---
27
+
28
+ > [!NOTE]
29
+ > **Project Status (`v0.1.1`)**: End-to-end Feishu / Lark ↔ local `agy acp --stdio` bridging is complete and verified across the offline unit/integration test suite and live Feishu sessions — featuring Fail-Closed `open_id` authorization, a single-process `lark-oapi` WebSocket daemon, persistent cross-restart ACP session recovery (`session/resume`), CardKit 2.0 streaming cards, mid-turn steering, `/stop` cancellation, and single-column `/model` & `/effort` interactive selector cards.
30
+
31
+ ## What You Get
32
+
33
+ | Scenario | What `agy-lark` Does | What You Get |
34
+ | :--- | :--- | :--- |
35
+ | **Remote Coding via Chat** | Maps Feishu / Lark DM, thread, or `@bot` messages to persistent `agy` ACP sessions | Drive your local project workspace right from mobile or desktop chat |
36
+ | **Mid-Turn Steering** | Delivers follow-up instructions via `session/prompt` while a turn is actively running | Redirect or refine long tasks on the fly without waiting or restarting |
37
+ | **Timely Cancellation** | Card stop actions or `/stop` issue native ACP `session/cancel` for the active turn | Halts the current task cleanly while keeping full conversation context intact |
38
+ | **Live Streaming Cards** | Sends and updates CardKit 2.0 interactive cards in-process via `lark-oapi` with throttling | Real-time progress and Markdown replies in one clean card |
39
+ | **Model & Effort Control** | Supports `AGY_MODEL` / `AGY_EFFORT` defaults plus decoupled `/model` & `/effort` single-column cards | Switch models or multi-level thinking intensity interactively per conversation |
40
+ | **Lightweight Setup** | Runs in a single Python process over WebSocket and auto-discovers `agy` from `PATH` | Requires only Python 3.11+, `lark-oapi`, and basic app configuration to start |
41
+
42
+ ## Architecture
43
+
44
+ `agy-lark` runs as a single Python process sitting cleanly between two protocol boundaries:
45
+
46
+ <p align="center">
47
+ <picture>
48
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/architecture-dark.svg" />
49
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/architecture-light.svg" />
50
+ <img src="https://raw.githubusercontent.com/starswei/agy-lark/main/docs/assets/architecture-light.svg" alt="agy-lark architecture: Feishu / Lark ↔ agy-lark ↔ Antigravity" width="100%" />
51
+ </picture>
52
+ </p>
53
+
54
+ - **Unified In-Process Feishu Transport (`lark-oapi`)**: Handles both message events (`im.message.receive_v1`) and card button callbacks (`card.action.trigger`) over a single WebSocket connection, while creating and streaming CardKit 2.0 updates over HTTPS.
55
+ - **Direct Native ACP (`agy acp --stdio`)**: Drives local sessions over bidirectional stdio JSON-RPC, enabling **mid-turn steering**, protocol-level **`session/cancel`**, and decoupled **`model` / `effort`** configuration.
56
+
57
+ <!--
58
+ ## Preview
59
+
60
+ Uncomment after adding real Feishu / Lark card captures under `docs/assets/`:
61
+
62
+ <table>
63
+ <tr>
64
+ <td><img src="docs/assets/01-streaming-card.png" alt="Streaming Card" width="100%"/><br/><sub>Live CardKit 2.0 streaming reply with stop control</sub></td>
65
+ <td><img src="docs/assets/02-steering.png" alt="Mid-Turn Steering" width="100%"/><br/><sub>Sending follow-up guidance mid-turn without losing context</sub></td>
66
+ </tr>
67
+ </table>
68
+ -->
69
+
70
+ ## Quick Start
71
+
72
+ ### Prerequisites
73
+
74
+ 1. **Python 3.11+** (developed & verified with `3.13.9`)
75
+ 2. **Antigravity CLI (`agy`)** installed locally and authenticated, with `agy` available on `PATH` (or configured via `AGY_EXE`)
76
+ 3. **A Feishu / Lark Custom App** with Bot capability enabled:
77
+ - Event subscription delivery mode: **Persistent Connection (WebSocket)**
78
+ - Subscribe to `im.message.receive_v1` and card callback `card.action.trigger`
79
+ - Required IM / CardKit bot permissions granted and app published
80
+
81
+ ### Installation & Configuration
82
+
83
+ **Option 1: Install from GitHub Releases or PyPI (after `agylark` is published to PyPI)**
84
+
85
+ ```bash
86
+ # Isolated CLI installation (recommended by PyPA once published to PyPI):
87
+ pipx install agylark
88
+ # or with uv:
89
+ uv tool install agylark
90
+ # or directly from a downloaded GitHub Release wheel inside a venv:
91
+ pip install ./agylark-<version>-py3-none-any.whl
92
+ ```
93
+
94
+ **Option 2: Install from Source**
95
+
96
+ ```bash
97
+ git clone https://github.com/starswei/agy-lark.git
98
+ cd agy-lark
99
+
100
+ python -m venv .venv
101
+ # Windows PowerShell: .venv\Scripts\Activate.ps1
102
+ # macOS / Linux: source .venv/bin/activate
103
+
104
+ pip install -e .
105
+ cp .env.example .env
106
+ # Fill in FEISHU_APP_ID, FEISHU_APP_SECRET, and AGY_LARK_ALLOWED_OPEN_IDS
107
+ ```
108
+
109
+ - **Optional presets**: Set `AGY_MODEL` and `AGY_EFFORT` in `.env` to auto-apply a preferred default model and thinking intensity on new ACP sessions, or leave them blank to use Antigravity's defaults.
110
+ - **Portable `.env` paths**: Relative paths configured inside `.env` (`AGY_DEFAULT_WORKSPACE`, `AGY_EXE`, `AGY_LARK_DATA_DIR`) resolve relative to the `.env` file's directory; externally set OS environment variables still resolve against the process current working directory (`CWD`).
111
+
112
+ > [!TIP]
113
+ > **`AGY_LARK_ALLOWED_OPEN_IDS` is your access allowlist**: list the Feishu / Lark user `open_id` values (`ou_...`, comma-separated) permitted to drive your local `agy`. Since the bridge grants chat access to your local workspace, leaving it empty rejects all requests by default for safety.
114
+
115
+ ### Starting the Daemon
116
+
117
+ ```bash
118
+ agylark --env-file .env -v
119
+ ```
120
+
121
+ - Also available via the compatible `agy-lark` CLI alias (`pip install -e .` installs both `agylark` and `agy-lark`).
122
+
123
+ - `--env-file`: Path to your `.env` file (defaults to `.env` in the current directory; pass `""` to skip loading a `.env` file and read process environment variables only).
124
+ - `--verbose` / `-v`: Enables `DEBUG`-level logging (overrides `AGY_LARK_LOG_LEVEL`).
125
+
126
+ ### Chat Commands
127
+
128
+ Send standalone slash commands in an authorized DM, group thread, or `@bot` mention (when enabled); text containing extra arguments passes through as a normal prompt:
129
+
130
+ - **`/stop`**: Issues ACP `session/cancel` for the active turn in the current conversation (equivalent to clicking the card's Stop button).
131
+ - **`/model`**: Sends a single-column CardKit 2.0 selector card listing available models; selecting a model updates only the session's model without overwriting thinking effort.
132
+ - **`/effort`**: Sends a single-column CardKit 2.0 selector card listing supported thinking intensity levels for the active model (including multi-level configurations such as 4 levels).
133
+
134
+ ### Running Tests
135
+
136
+ Run the offline unit and daemon integration suite directly from the repository root:
137
+
138
+ ```bash
139
+ python -W error -m unittest discover -s tests -v
140
+ ```
141
+
142
+ To also include the optional real `agy acp` cross-restart E2E test (requires a locally installed and authenticated `agy` CLI), set `AGY_LARK_REAL_AGY_E2E=1`.
143
+
144
+ ## Runtime & Safety Design
145
+
146
+ `agy-lark` is designed around explicit, fail-closed operational boundaries:
147
+
148
+ - **Fail-Closed Authorization**: If `AGY_LARK_ALLOWED_OPEN_IDS` is empty, **all** incoming messages and card actions (`stop`, `model`, `effort`) are rejected by default. Group `@mention` routing is disabled unless `AGY_LARK_ALLOW_GROUP_MENTION=true` is explicitly set.
149
+ - **Cross-Platform `agy` Discovery**: Resolves `AGY_EXE` first if set, otherwise looks up `agy` via `PATH` — no hardcoded OS-specific installation paths.
150
+ - **Throttled Streaming & Turn Safety**: Coalesces high-frequency ACP output chunks via `AGY_LARK_STREAM_THROTTLE` (default `0.25s`), enforces per-turn timeouts (`AGY_TURN_TIMEOUT_SECONDS`), and cleans up child pipes via ACP cancellation on `SIGINT` / `SIGTERM`.
151
+ - **Persistent Session & Config Recovery**: Atomically persists isolated conversation mappings (`p2p:<chat_id>`, thread aliases, and reply message bindings), workspace `cwd`, and selected model/effort in `{AGY_LARK_DATA_DIR}/sessions.json`. After a daemon or ACP subprocess restart, the first incoming turn or command resumes the prior session on demand via `session/resume` and replays its saved model and effort — safely falling back to a new session (or default settings) with an explicit diagnostic notice if the workspace changed, the session expired, or a saved option is unavailable.
152
+
153
+ ## Privacy Notice
154
+
155
+ `agy-lark` strictly separates **public repository assets** from **private local runtime state**:
156
+
157
+ - **Tracked in Git**: source code (`src/agylark/`), unit tests (`tests/`), `.env.example`, `pyproject.toml`, `LICENSE`, documentation, and logo assets.
158
+ - **Local-only (`.gitignore`)**: `.env`, `FEISHU_APP_SECRET`, authorized `open_id` lists, `.agy-lark/`, `sessions.json`, logs, state/database files, and `.venv/`.
159
+
160
+ **Never commit `.env` or runtime state files to a public repository.**
161
+
162
+ ## License
163
+
164
+ [MIT](https://github.com/starswei/agy-lark/blob/main/LICENSE)
@@ -0,0 +1,50 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "agylark"
7
+ version = "0.1.1"
8
+ description = "A lightweight, native-ACP bridge between Antigravity (agy) and Feishu / Lark via lark-oapi."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.11"
13
+ authors = [
14
+ { name = "starswei" },
15
+ ]
16
+ keywords = ["antigravity", "agy", "acp", "feishu", "lark", "bridge", "chatbot"]
17
+ classifiers = [
18
+ "Development Status :: 4 - Beta",
19
+ "Intended Audience :: Developers",
20
+ "Operating System :: OS Independent",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ ]
26
+ dependencies = [
27
+ "lark-oapi>=1.4.0",
28
+ ]
29
+
30
+ [project.optional-dependencies]
31
+ dev = [
32
+ "pytest>=8.0",
33
+ "ruff>=0.6.0",
34
+ ]
35
+
36
+ [project.scripts]
37
+ agylark = "agylark.daemon:main"
38
+ agy-lark = "agylark.daemon:main"
39
+
40
+ [project.urls]
41
+ Homepage = "https://github.com/starswei/agy-lark"
42
+ Repository = "https://github.com/starswei/agy-lark"
43
+ Issues = "https://github.com/starswei/agy-lark/issues"
44
+
45
+ [tool.setuptools.packages.find]
46
+ where = ["src"]
47
+
48
+ [tool.pytest.ini_options]
49
+ pythonpath = ["src"]
50
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,158 @@
1
+ """agy-lark 轻量级飞书 ↔ Antigravity (agy acp --stdio) 桥接器包。"""
2
+
3
+ from .acp_client import (
4
+ AcpError,
5
+ AcpPromptResult,
6
+ AcpSessionUpdate,
7
+ AgyAcpClient,
8
+ )
9
+ from .card_streamer import (
10
+ ACP_EFFORT_CONFIG_ID,
11
+ ACP_MODEL_CONFIG_ID,
12
+ CARD_SCHEMA_VERSION,
13
+ CONTENT_ELEMENT_ID,
14
+ EFFORT_HINT_ELEMENT_ID,
15
+ EFFORT_SELECT_ACTION_NAME,
16
+ EFFORT_STATUS_ELEMENT_ID,
17
+ MODEL_HINT_ELEMENT_ID,
18
+ MODEL_SELECT_ACTION_NAME,
19
+ MODEL_STATUS_ELEMENT_ID,
20
+ STATUS_ELEMENT_ID,
21
+ STOP_ACTION_NAME,
22
+ STOP_BUTTON_ELEMENT_ID,
23
+ AcpEffortOption,
24
+ AcpModelOption,
25
+ CardRunState,
26
+ CardTransport,
27
+ EffortSelectCallbackPayload,
28
+ ModelSelectCallbackPayload,
29
+ StopCallbackPayload,
30
+ StreamingCardUpdater,
31
+ build_create_card_payload,
32
+ build_effort_select_callback_value,
33
+ build_effort_selector_card_json,
34
+ build_model_select_callback_value,
35
+ build_model_selector_card_json,
36
+ build_stop_callback_value,
37
+ build_stream_content_payload,
38
+ build_streaming_card_json,
39
+ build_update_card_payload,
40
+ build_update_settings_payload,
41
+ has_config_option,
42
+ parse_available_efforts,
43
+ parse_available_models,
44
+ parse_current_effort_id,
45
+ parse_current_model_id,
46
+ parse_effort_select_callback_value,
47
+ parse_model_select_callback_value,
48
+ parse_stop_callback_value,
49
+ )
50
+ from .config import (
51
+ AgyLarkConfig,
52
+ is_authorized_open_id,
53
+ load_config,
54
+ load_dotenv_file,
55
+ parse_allowed_open_ids,
56
+ resolve_agy_executable,
57
+ )
58
+ from .daemon import (
59
+ AcpClientProtocol,
60
+ AgyLarkDaemon,
61
+ IncomingMention,
62
+ IncomingMessage,
63
+ LarkApiError,
64
+ LarkCardTransport,
65
+ LarkMessageSender,
66
+ MessageSender,
67
+ build_arg_parser,
68
+ build_event_dispatcher,
69
+ build_feishu_client,
70
+ build_ws_client,
71
+ extract_incoming_message,
72
+ main,
73
+ )
74
+ from .session_store import (
75
+ DEFAULT_MAPPING_CAPACITY,
76
+ DEFAULT_SESSIONS_FILENAME,
77
+ SESSION_STORE_SCHEMA_VERSION,
78
+ JsonSessionStore,
79
+ PersistedConversation,
80
+ PersistedSessionState,
81
+ SessionStore,
82
+ )
83
+
84
+ __version__ = "0.1.1"
85
+
86
+ __all__ = [
87
+ "ACP_EFFORT_CONFIG_ID",
88
+ "ACP_MODEL_CONFIG_ID",
89
+ "AcpClientProtocol",
90
+ "AcpEffortOption",
91
+ "AcpError",
92
+ "AcpModelOption",
93
+ "AcpPromptResult",
94
+ "AcpSessionUpdate",
95
+ "AgyAcpClient",
96
+ "AgyLarkConfig",
97
+ "AgyLarkDaemon",
98
+ "CARD_SCHEMA_VERSION",
99
+ "CONTENT_ELEMENT_ID",
100
+ "CardRunState",
101
+ "CardTransport",
102
+ "DEFAULT_MAPPING_CAPACITY",
103
+ "DEFAULT_SESSIONS_FILENAME",
104
+ "EFFORT_HINT_ELEMENT_ID",
105
+ "EFFORT_SELECT_ACTION_NAME",
106
+ "EFFORT_STATUS_ELEMENT_ID",
107
+ "EffortSelectCallbackPayload",
108
+ "IncomingMention",
109
+ "IncomingMessage",
110
+ "JsonSessionStore",
111
+ "LarkApiError",
112
+ "LarkCardTransport",
113
+ "LarkMessageSender",
114
+ "MODEL_HINT_ELEMENT_ID",
115
+ "MODEL_SELECT_ACTION_NAME",
116
+ "MODEL_STATUS_ELEMENT_ID",
117
+ "MessageSender",
118
+ "ModelSelectCallbackPayload",
119
+ "PersistedConversation",
120
+ "PersistedSessionState",
121
+ "SESSION_STORE_SCHEMA_VERSION",
122
+ "STATUS_ELEMENT_ID",
123
+ "STOP_ACTION_NAME",
124
+ "STOP_BUTTON_ELEMENT_ID",
125
+ "SessionStore",
126
+ "StopCallbackPayload",
127
+ "StreamingCardUpdater",
128
+ "__version__",
129
+ "build_arg_parser",
130
+ "build_create_card_payload",
131
+ "build_effort_select_callback_value",
132
+ "build_effort_selector_card_json",
133
+ "build_event_dispatcher",
134
+ "build_feishu_client",
135
+ "build_model_select_callback_value",
136
+ "build_model_selector_card_json",
137
+ "build_stop_callback_value",
138
+ "build_stream_content_payload",
139
+ "build_streaming_card_json",
140
+ "build_update_card_payload",
141
+ "build_update_settings_payload",
142
+ "build_ws_client",
143
+ "extract_incoming_message",
144
+ "has_config_option",
145
+ "is_authorized_open_id",
146
+ "load_config",
147
+ "load_dotenv_file",
148
+ "main",
149
+ "parse_allowed_open_ids",
150
+ "parse_available_efforts",
151
+ "parse_available_models",
152
+ "parse_current_effort_id",
153
+ "parse_current_model_id",
154
+ "parse_effort_select_callback_value",
155
+ "parse_model_select_callback_value",
156
+ "parse_stop_callback_value",
157
+ "resolve_agy_executable",
158
+ ]