以 Kiro 支持 Kiro：飞书机器人通过 ACP 协议调用 Kiro-CLI 解答用户问题
本文实现了一个飞书 Kiro 技术支持机器人，即「Kiro助手」。与其它使用 Agent 框架开发聊天机器人的实现方式不同，本项目**不引入任何 Agent 框架**，而是通过 ACP 协议直接驱动 `kiro-cli` 作答。当飞书机器人收到提问后，通过 Web Socket（以下简称 WS ）发给 飞书 Gateway，然后 Gateway 使用 ACP 协议发给 `kiro-cli acp` 进程，由 Kiro 自身的 agent 能力（含内置联网工具）生成回答。系统提示词 System prompt、知识库、模型、工具范围全部挂在 `kiro-cli` 的自定义 agent 上。
本文实现了一个飞书 Kiro 技术支持机器人，即「Kiro助手」。与其它使用 Agent 框架开发聊天机器人的实现方式不同，本项目不引入任何 Agent 框架，而是通过 ACP（Agent Client Protocol） 协议直接驱动 kiro-cli 作答。当飞书机器人收到提问后，通过 Web Socket（以下简称 WS ）发给 飞书 Gateway，然后 Gateway 使用 ACP 协议发给 kiro-cli acp 进程，由 Kiro 自身的 agent 能力（含内置联网工具）生成回答。系统提示词 System prompt、知识库、模型、工具范围全部挂在 kiro-cli 的自定义 agent 上。
一、架构实现
1、工作流程
飞书用户 → 飞书 Web Socket (lark-oapi) → FeishuGateway
│ asyncio 桥接
▼
KiroAcpService（进程池 + 按聊天范围 session）
│ ACP / JSON-RPC over stdio
▼
kiro-cli acp --agent kiro-support
（Kiro 自带模型 + 内置 web_search/web_fetch + 知识库）
- ACP client 基于官方
agent-client-protocolPython SDK 实现，不手写 JSON-RPC。 - 飞书机器人的 Gateway 扮演 ACP 的 Client，
kiro-cli是被调用的 Agent。
2、文件说明 - 飞书机器人和ACP客户端程序
| 文件 | 职责 |
|---|---|
main.py |
入口：启动 asyncio 事件循环线程、拉起 ACP 进程池、启动飞书 Web Socket |
feishu_gateway.py |
飞书 WS 事件分发、消息去重、markdown→飞书富文本转换 |
kiro_acp_service.py |
kiro-cli acp 进程池、按聊天范围隔离的 ACP session、ask() 调度、超时取消、TTL 回收 |
acp_client.py |
SupportClient：只读权限策略（跳过提示）+ 回复文本聚合 |
config.py |
集中配置（进程池大小、超时、路径、凭证） |
logger.py |
统一日志（终端 + 按日期滚动文件） |
3、配置文件说明（config.py）
| 配置 | 说明 | 默认 |
|---|---|---|
KIRO_CLI_PATH |
kiro-cli 可执行文件路径（env） | kiro-cli |
KIRO_AGENT_NAME |
自定义 agent 名称 | kiro-support |
KIRO_MODEL_ID |
新建 ACP session 后强制设置的 Kiro 模型 ID | claude-sonnet-5 |
POOL_SIZE |
常驻 kiro-cli acp 进程数（env） | 1 |
PROMPT_TIMEOUT_SECONDS |
单次提问超时（秒） | 120 |
AGENT_TTL_SECONDS |
会话范围 session 不活跃回收时间 | 48h |
4、Kiro CLI 工作目录
以下目录和文件是 Kiro CLI 作为 Agent 运行需要的配置
| 文件 | 职责 |
|---|---|
.kiro/agents/kiro-support.json |
Kiro 自定义 agent：只读工具 + system prompt + 工作区知识库 + 模型 |
prompts/kiro_agent_prompt.md |
挂到 agent 的 system prompt |
agent_workspace/ |
ACP session 的工作目录，仅放置提供给 Kiro 读取的业务资料，隔离 bot 源码 |
agent_workspace/knowledge_base/*.md |
ACP 工作区中的知识库（以 file:// 资源挂载到 agent 上下文） |
5、关键设计特点
- 只读安全：agent 仅授
read/grep/glob/web_search/web_fetch/thinking，无 write/shell/aws；client 对一切写/执行类权限请求自动拒绝，initialize不声明 fs 写与 terminal 能力。 - 联网能力：复用 Kiro 内置
web_search/web_fetch（在 agent 配置里把 kiro.dev、github.com、docs.aws.amazon.com 设为可信域名自动放行）。 - 工作区隔离：ACP session 的
cwd指向agent_workspace/，知识库位于其中的knowledge_base/；机器人源码保留在工作区之外，降低 Kiro 误读代码的概率。 - 并发：默认单进程多 session；
POOL_SIZE调大后按session_key哈希分发到多个kiro-cli进程，获得并行与故障隔离。同一会话范围串行处理。 - 多轮与隔离：私聊使用
p2p:{open_id}作为会话键；群聊使用group:{chat_id}:{open_id}作为会话键。同一用户在同一群聊内保留多轮上下文，私聊、不同群聊以及同一群聊中的不同用户互不共享上下文；超AGENT_TTL_SECONDS回收。 - 超时：单次提问
PROMPT_TIMEOUT_SECONDS（默认 120s），超时调session/cancel。
二、部署和运行
本系统只需要一个小型的 2vCPU/4GB 内存的虚拟机和 Ubuntu 即可，支持在 ARM 处理器的虚拟机上运行。
1、前置条件
前置工作如下：
- (1) 在飞书开放平台，已经创建好飞书机器人，且机器人获得通过。从飞书开放平台上复制下来应用 ID 和密钥，下一步要更新到配置文件中。
- (2) 本机已安装并登录
kiro-cli。确认当前 CLI 可以正常对话。
2、克隆代码和环境安装
安装好 uv 即 Python 包管理工具。
# Linux 系统
curl -LsSf https://astral.sh/uv/install.sh | sh
克隆代码并安装 Python 环境：
# 获取代码
git clone https://github.com/aobao32/feishu-kiro-acp-bot.git
# 安装依赖包
cd feishu-kiro-acp-bot
uv sync
3、设置飞书机器人配置文件/环境变量
# 配置环境变量（复制 .env.example 为 .env 并填值）
cp .env.example .env
编辑 .env 文件，替换 APP_ID、APP_SECRET、KIRO_CLI_PATH 变量。
4、启动程序
uv run python main.py
保持窗口不要关闭。现在即可发起对话，可看到飞书机器人会根据知识库作出有效回答。
三、补充说明/注意事项
- 同一用户在同一群聊连续提问，将共享对话上下文，这样可确保机器人可澄清用户提问信息的完整性
- 当前实现没有长时记忆，和用户的过往对话保留在内存中，没有使用本地文件、数据库或者 Bedrock AgentCore Memory 等服务做持久化。如果用户输入信息不完整，机器人会询问用户请补充完整信息。但如果此时遇到运行环境重启，那么会话记录将会丢失。
- 48小时不活跃的对话将被回收
附录、飞书机器人/开放平台配置步骤参考
本节完整说明如何在飞书开放平台创建机器人、配置能力与权限、建立长连接并发布。完成后将得到 APP_ID 和 APP_SECRET 两个值，供本项目环境变量使用（见第二节的 3、设置飞书机器人配置文件/环境变量）。
1、创建企业自建应用
进入飞书开放平台，点击创建企业自建应用按钮。如下截图。
在创建自定义应用的弹出对话框内，输入名称，点击创建按钮。如下截图。
2、开启机器人能力
向导创建完成后会自动切换到能力界面，点击第一项，将此应用的能力设置为机器人。如下截图。
3、获取 App ID 和 App Secret
点击左侧的凭证与基础信息菜单，从右侧复制 App ID 和 App Secret 两个值，后续将作为本项目的环境变量 APP_ID 和 APP_SECRET 使用。如下截图。
4、配置权限
在左侧菜单开发配置下，点击权限管理，再点击右侧的开通权限按钮。如下截图。
在开通权限对话框内，搜索关键字找到下表权限后，点击确认开通权限按钮。如下截图。
要开通的权限列表包括：
| 权限 | 范围 | 说明 |
|---|---|---|
im:message |
消息 | 发送和接收消息 |
im:message:update |
编辑 | 更新/编辑已发送消息 |
im:message:readonly |
读取 | 获取历史消息 |
im:message:recall |
撤回 | 撤回已发送消息 |
im:message:send_as_bot |
发送 | 以机器人身份发送消息 |
im:message.group_at_msg:readonly |
群聊 | 接收群内 @机器人 的消息 |
im:message.group_msg |
群聊 | 读取所有群消息（敏感） |
im:message.p2p_msg:readonly |
私聊 | 读取发给机器人的私聊消息 |
im:message.reactions:read |
表情 | 查看消息表情回复 |
im:resource |
媒体 | 上传和下载图片/文件 |
contact:user.base:readonly |
用户信息 | 获取用户基本信息（用于解析发送者姓名，避免群聊/私聊把不同人当成同一说话者） |
全部添加后界面如下截图。
5、用测试代码建立长连接
接下来测试本项目与飞书后台 API 的连接。只有外部应用连接成功，才能继续在飞书开放平台配置事件功能；若未先建立连接，后续配置会提示尚未连接。
本项目已通过 uv sync 安装 lark-oapi，可直接在项目根目录创建一个临时测试文件 lark_test.py，内容如下：
import lark_oapi as lark
def do_p2_im_message_receive_v1(data: lark.im.v1.P2ImMessageReceiveV1) -> None:
print(f'[ receive ], data: {lark.JSON.marshal(data, indent=4)}')
event_handler = lark.EventDispatcherHandler.builder("", "") \
.register_p2_im_message_receive_v1(do_p2_im_message_receive_v1) \
.build()
cli = lark.ws.Client("YOUR_APP_ID", "YOUR_APP_SECRET",
event_handler=event_handler,
log_level=lark.LogLevel.DEBUG)
cli.start()
将 YOUR_APP_ID 和 YOUR_APP_SECRET 替换为第 3 步获取的真实值，然后执行：
uv run python lark_test.py
连接成功返回结果如下（信息已脱敏）：
[Lark] [2026-02-11 08:46:01,055] [INFO] connected to wss://msg-frontier.feishu.cn/ws/v2?fpid=111&aid=11111&device_id=1111111111111&access_key=1111111111111111111111111&service_id=1111111111118&ticket=11111111111111111111111111111111111111111 [conn_id=111111111111111]
[Lark] [2026-02-11 08:46:01,056] [DEBUG] ping success [conn_id=1111111111111111]
[Lark] [2026-02-11 08:46:01,305] [DEBUG] receive pong [conn_id=1111111111111111]
连接成功后，先不要停止程序，保持长连接活跃状态，回到飞书控制台继续配置。
6、配置事件长连接
确认上一步程序保持运行、长连接活跃。在飞书开放平台左侧点击事件与回调菜单，在右侧点击事件配置标签页，点击下方的订阅方式。如下截图。
在订阅方式位置，选择使用长连接接收事件（推荐），然后点击保存。如下截图。
此时需确保上一步的测试程序处于活跃状态，即可完成配置。
7、配置事件订阅
在事件与回调界面配置完长连接后，点击右下角的添加事件。如下截图。
在添加事件对话框中，通过关键字搜索添加下表事件。如下截图。
| 事件 | 说明 |
|---|---|
im.message.receive_v1 |
接收消息（必需） |
im.message.message_read_v1 |
消息已读回执 |
im.chat.member.bot.added_v1 |
机器人进群 |
im.chat.member.bot.deleted_v1 |
机器人被移出群 |
即可完成事件配置。配置完成后，可停止第 5 步的临时测试程序并删除 lark_test.py，改用第二节的 4、启动程序中的 uv run python main.py 启动正式服务。
8、向飞书企业管理员申请发布机器人
注意：飞书机器人要想被外部应用调用，必须进行版本发布操作。如果你是飞书企业用户，这一步需要企业管理员审批；如果你是飞书个人用户，那么创建的机器人只能和自己对话，无法添加到与他人的对话中。与他人互动的飞书机器人要求必须是企业账号且完成企业营业执照审核。
进入左侧应用发布菜单，点击版本管理与发布，在右侧点击创建版本并填写表单。注意版本号必须是 x.x.x 格式。如下截图。
在发布申请下方，可选择向整个组织发布还是只向部分成员发布、是否对外共享，这都需要管理员审批。填写完整的申请理由后，点击保存即提交申请。如下截图。
等待管理员完成审批即可。
最后修改于 2026-07-23