aai-lark-bridge 0.1.0
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.
- package/README.md +208 -0
- package/bin/aai-lark-bridge.mjs +3 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +17429 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +198 -0
- package/dist/index.js +1535 -0
- package/dist/index.js.map +1 -0
- package/package.json +63 -0
package/README.md
ADDED
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
# aai-lark-bridge
|
|
2
|
+
|
|
3
|
+
在飞书 / Lark 里直接和本机的编程助手(Claude Code / Codex CLI)对话。
|
|
4
|
+
私聊发消息或群里 `@bot`,任务交给本机 agent 执行,结果回到飞书。
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 给 AI agent 的安装说明
|
|
9
|
+
|
|
10
|
+
> 如果你是 AI agent,按本节从上到下执行。每步都有验证命令,**验证通过再进入下一步**。
|
|
11
|
+
> 人类读者可以直接跳到 [命令参考](#命令参考)。
|
|
12
|
+
|
|
13
|
+
### 第 0 步:先读这三条硬约束
|
|
14
|
+
|
|
15
|
+
1. **`run` 会一直阻塞。** 它在前台运行 bridge,不会自己退出。
|
|
16
|
+
**不要在非交互会话里执行 `run`** —— 你会挂住。
|
|
17
|
+
无人值守场景用 `start`(注册成系统服务后立即返回)。
|
|
18
|
+
2. **首次初始化默认走扫码,需要真实终端。** 非交互环境下必须显式传
|
|
19
|
+
`--app-id` 和 `--app-secret`,否则命令会**报错退出**(错误原文见第 4 步)。
|
|
20
|
+
3. **本机装了多个 agent 时,非交互环境必须显式传 `--agent`。**
|
|
21
|
+
否则选择步骤会静默返回空,初始化不完整。
|
|
22
|
+
|
|
23
|
+
### 第 1 步:确认前置条件
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
node --version # 必须 >= 20.12.0
|
|
27
|
+
claude --version # 或 codex --version,至少要有一个
|
|
28
|
+
lark-cli --version # 见下方说明
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- **Node.js < 20.12.0 → 停止**,先升级 Node,不要继续。
|
|
32
|
+
- **`claude` 和 `codex` 都没有 → 停止**,先安装并登录其中一个。
|
|
33
|
+
这个包只是桥接层,不自带 agent。
|
|
34
|
+
- **`lark-cli` 不存在**:交互式终端里启动时会自动安装;
|
|
35
|
+
**非交互环境不会自动安装**,会打印 `(non-interactive mode; skipping auto-install)`
|
|
36
|
+
并给出手工安装提示。所以非交互场景请先手工装好 `lark-cli`。
|
|
37
|
+
|
|
38
|
+
### 第 2 步:安装
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npm i -g aai-lark-bridge
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
验证:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
aai-lark-bridge --version
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
预期输出一个版本号(如 `0.1.0`)。命令找不到就是全局 bin 目录不在 `PATH` 里。
|
|
51
|
+
|
|
52
|
+
### 第 3 步:准备飞书应用凭据
|
|
53
|
+
|
|
54
|
+
你需要一个飞书 / Lark 应用的 **App ID** 和 **App Secret**。
|
|
55
|
+
|
|
56
|
+
- 已经有 → 进入第 4 步。
|
|
57
|
+
- 没有 → **需要人工介入**。让用户在真实终端里运行 `aai-lark-bridge run`
|
|
58
|
+
完成扫码创建,或让用户到飞书开放平台自行创建应用后把凭据给你。
|
|
59
|
+
**你无法在非交互环境里完成这一步**,不要尝试。
|
|
60
|
+
|
|
61
|
+
> `cli_xxxxxxxxxxxx` 这类形如占位符的值**就是占位符**。
|
|
62
|
+
> 不要原样执行,必须替换成真实的 App ID。
|
|
63
|
+
|
|
64
|
+
### 第 4 步:初始化并启动
|
|
65
|
+
|
|
66
|
+
**无人值守(推荐给 AI agent)** —— 注册成 OS 托管服务,命令立即返回:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
aai-lark-bridge start \
|
|
70
|
+
--app-id <真实的 App ID> \
|
|
71
|
+
--app-secret <真实的 App Secret> \
|
|
72
|
+
--agent claude
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
参数说明:
|
|
76
|
+
|
|
77
|
+
| 参数 | 何时必须 |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| `--app-id` | 非交互环境必须 |
|
|
80
|
+
| `--app-secret` | 非交互环境必须 |
|
|
81
|
+
| `--agent claude` 或 `--agent codex` | 本机有多个 agent 时必须 |
|
|
82
|
+
| `--workspace <绝对路径>` | 想指定 agent 的初始工作目录时 |
|
|
83
|
+
| `--tenant lark` | Lark 国际版(默认 `feishu`) |
|
|
84
|
+
|
|
85
|
+
**如果命令报下面这些错,按对应处理:**
|
|
86
|
+
|
|
87
|
+
| 错误信息(原文片段) | 原因 | 处理 |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| `当前没有配置,非交互模式无法完成扫码创建应用` | 没传 `--app-id` | 补上 `--app-id` 和 `--app-secret`,或请人工在终端完成初始化 |
|
|
90
|
+
| `非交互模式缺少 App Secret` | 传了 `--app-id` 但没传 `--app-secret` | 补上 `--app-secret` |
|
|
91
|
+
| `非交互模式无法确认停止,请先用 ... ps ... kill` | 已有 bridge 进程占用 | 先跑 `ps` 看清楚,再 `kill <bot id>`,然后重试 |
|
|
92
|
+
| `⚠️ 当前不是交互式启动,已自动取消` | 已有 bot 在跑,需要确认替换 | 同上,先 `kill` 掉旧的 |
|
|
93
|
+
|
|
94
|
+
### 第 5 步:验证安装成功
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
aai-lark-bridge status
|
|
98
|
+
aai-lark-bridge ps
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**成功标准**(两个都要满足):
|
|
102
|
+
|
|
103
|
+
- `status` 显示服务已注册且有 pid
|
|
104
|
+
- `ps` 列出至少一个在跑的 bot,且带 bot 名称和 App ID
|
|
105
|
+
|
|
106
|
+
`ps` 输出里没有任何条目 = **没成功**,去看 `status` 给出的日志路径。
|
|
107
|
+
|
|
108
|
+
### 第 6 步:告诉用户怎么用
|
|
109
|
+
|
|
110
|
+
初始化完成后,用户在飞书里:
|
|
111
|
+
|
|
112
|
+
- 私聊 bot 直接发消息
|
|
113
|
+
- 群里 `@bot` 加内容
|
|
114
|
+
- 发 `/help` 会返回一张带按钮的卡片,列出所有可用指令
|
|
115
|
+
|
|
116
|
+
配置文件在 `~/.aai-lark-bridge/`。App Secret 加密存放在 `~/.aai-lark-bridge/secrets.enc`。
|
|
117
|
+
|
|
118
|
+
### 不要做这些
|
|
119
|
+
|
|
120
|
+
- ❌ **不要在非交互会话里跑 `run`** —— 会永久阻塞。用 `start`。
|
|
121
|
+
- ❌ **不要跑 `pnpm install`** —— 那是本仓库开发者的命令,和安装这个包无关。
|
|
122
|
+
- ❌ **不要原样执行 `cli_xxxxxxxxxxxx` 之类的占位符**。
|
|
123
|
+
- ❌ **不要把 App Secret 写进命令历史能看到的地方**就算完 —— 共享机器上改用
|
|
124
|
+
`aai-lark-bridge secrets set --app-id <id>`(输入不回显)。
|
|
125
|
+
- ❌ **不要假设初始化成功** —— 一定跑第 5 步的验证。
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## 命令参考
|
|
130
|
+
|
|
131
|
+
`aai-lark-bridge <命令> --help` 查看每个命令的完整选项。
|
|
132
|
+
|
|
133
|
+
### 进程级
|
|
134
|
+
|
|
135
|
+
| 命令 | 说明 | 阻塞? |
|
|
136
|
+
| --- | --- | --- |
|
|
137
|
+
| `run` | 前台运行 bridge | **是,永久阻塞** |
|
|
138
|
+
| `ps` | 列出本机在跑的 bridge 进程 | 否 |
|
|
139
|
+
| `kill <target>` | 按短 id 或列表序号结束进程 | 否 |
|
|
140
|
+
| `ui` | 打开本地 Web 控制台 | 否 |
|
|
141
|
+
| `migrate` | 把旧版配置 / 状态迁移到当前 profile 布局 | 否 |
|
|
142
|
+
|
|
143
|
+
### 服务级(OS 托管:launchd / systemd / schtasks)
|
|
144
|
+
|
|
145
|
+
| 命令 | 说明 |
|
|
146
|
+
| --- | --- |
|
|
147
|
+
| `start` | 安装并启动为系统服务(不阻塞) |
|
|
148
|
+
| `stop` | 停止并关闭自启(服务定义保留) |
|
|
149
|
+
| `restart` | 重启 |
|
|
150
|
+
| `status` | 查看 pid、上次退出、日志路径 |
|
|
151
|
+
| `unregister` | 移除服务注册 |
|
|
152
|
+
|
|
153
|
+
### Profile
|
|
154
|
+
|
|
155
|
+
支持多套配置(不同应用 / 不同工作目录 / 不同权限)。
|
|
156
|
+
|
|
157
|
+
| 命令 | 说明 |
|
|
158
|
+
| --- | --- |
|
|
159
|
+
| `profile list` | 列出已配置的 profile |
|
|
160
|
+
| `profile create <name>` | 扫码或用已有凭据创建 |
|
|
161
|
+
| `profile use <name>` | 切换当前 profile |
|
|
162
|
+
| `profile remove <name>` | 归档 profile 及其本地状态 |
|
|
163
|
+
| `profile export <name>` | 导出为 JSON |
|
|
164
|
+
|
|
165
|
+
### 密钥
|
|
166
|
+
|
|
167
|
+
加密存放在 `~/.aai-lark-bridge/secrets.enc`。
|
|
168
|
+
|
|
169
|
+
| 命令 | 说明 |
|
|
170
|
+
| --- | --- |
|
|
171
|
+
| `secrets set --app-id <id>` | 存入 App Secret(输入不回显) |
|
|
172
|
+
| `secrets list` | 列出条目 id(不显示密钥) |
|
|
173
|
+
| `secrets remove --app-id <id>` | 删除条目 |
|
|
174
|
+
| `secrets get` | exec-provider 协议,供 `lark-cli config bind` 调用 |
|
|
175
|
+
|
|
176
|
+
### Web 控制台
|
|
177
|
+
|
|
178
|
+
配置、profile 管理、在线 bot 一览:
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
aai-lark-bridge run --web-ui # 前台运行并开控制台(阻塞)
|
|
182
|
+
aai-lark-bridge ui # 对已在跑的实例打开控制台
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## 作为库使用
|
|
188
|
+
|
|
189
|
+
**当前公共导出面很窄**,只有 agent 适配器:
|
|
190
|
+
|
|
191
|
+
```typescript
|
|
192
|
+
import { ClaudeAdapter, CodexAdapter } from 'aai-lark-bridge';
|
|
193
|
+
import type { AgentAdapter, AgentEvent, AgentRun, AgentRunOptions } from 'aai-lark-bridge';
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
这个包的主要价值在 CLI。其余模块(bot / card / config / runtime 等)目前是内部实现,
|
|
197
|
+
不在公共导出里。需要哪个可以提 issue。
|
|
198
|
+
|
|
199
|
+
## 系统要求
|
|
200
|
+
|
|
201
|
+
- Node.js `>= 20.12.0`
|
|
202
|
+
- macOS / Linux / Windows
|
|
203
|
+
- 本机装好并登录 Claude Code(`claude`)或 Codex CLI(`codex`)
|
|
204
|
+
- `lark-cli`
|
|
205
|
+
|
|
206
|
+
## License
|
|
207
|
+
|
|
208
|
+
MIT
|
package/dist/cli.d.ts
ADDED