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 +21 -0
- agylark-0.1.1/PKG-INFO +190 -0
- agylark-0.1.1/README.md +164 -0
- agylark-0.1.1/pyproject.toml +50 -0
- agylark-0.1.1/setup.cfg +4 -0
- agylark-0.1.1/src/agylark/__init__.py +158 -0
- agylark-0.1.1/src/agylark/acp_client.py +798 -0
- agylark-0.1.1/src/agylark/card_streamer.py +1171 -0
- agylark-0.1.1/src/agylark/config.py +322 -0
- agylark-0.1.1/src/agylark/daemon.py +2307 -0
- agylark-0.1.1/src/agylark/session_store.py +258 -0
- agylark-0.1.1/src/agylark.egg-info/PKG-INFO +190 -0
- agylark-0.1.1/src/agylark.egg-info/SOURCES.txt +20 -0
- agylark-0.1.1/src/agylark.egg-info/dependency_links.txt +1 -0
- agylark-0.1.1/src/agylark.egg-info/entry_points.txt +3 -0
- agylark-0.1.1/src/agylark.egg-info/requires.txt +5 -0
- agylark-0.1.1/src/agylark.egg-info/top_level.txt +1 -0
- agylark-0.1.1/tests/test_acp_client.py +472 -0
- agylark-0.1.1/tests/test_card_streamer.py +1003 -0
- agylark-0.1.1/tests/test_config.py +292 -0
- agylark-0.1.1/tests/test_daemon.py +3365 -0
- agylark-0.1.1/tests/test_session_store.py +231 -0
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
|
+
[](https://github.com/starswei/agy-lark/actions/workflows/ci.yml)
|
|
45
|
+
[](https://github.com/starswei/agy-lark/blob/main/LICENSE)
|
|
46
|
+
[](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)
|
agylark-0.1.1/README.md
ADDED
|
@@ -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
|
+
[](https://github.com/starswei/agy-lark/actions/workflows/ci.yml)
|
|
19
|
+
[](https://github.com/starswei/agy-lark/blob/main/LICENSE)
|
|
20
|
+
[](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"]
|
agylark-0.1.1/setup.cfg
ADDED
|
@@ -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
|
+
]
|