Merge pull request #561 from Cai-Tang-www/feat/feishu-2

feat(feishu): 接入 Gateway-backed 飞书 Adapter（Webhook + SDK 长连接）

Author: phantom5099

README.md

@@ -55,6 +55,7 @@ NeoCode 是一个运行在本地开发环境中的 AI Coding Agent。
 - Skills 系统：为不同任务启用专用行为和流程。
 - MCP 接入：通过 MCP stdio server 扩展外部工具能力。
 - Gateway 模式：通过本地 JSON-RPC / SSE / WebSocket 接口连接桌面端、脚本和第三方客户端。
+- Feishu Adapter：支持 Webhook 与 SDK 长连接接入，并用单张状态卡片持续回传 run 状态。
 
 ---
 
@@ -254,6 +255,7 @@ go run ./cmd/neocode --session <session_id>
 - [MCP 工具接入（Guide）](https://neocode-docs.pages.dev/guide/mcp)
 - [Skills 使用（Guide）](https://neocode-docs.pages.dev/guide/skills)
 - [飞书远程接入配置（Guide）](https://neocode-docs.pages.dev/guide/feishu-remote-setup)
+- [飞书本地 SDK 长连接（免公网，个人开发推荐）](https://neocode-docs.pages.dev/guide/feishu-remote-setup)
 - [Hooks 使用（Guide）](https://neocode-docs.pages.dev/guide/hooks)
 - [工具与权限（Guide）](https://neocode-docs.pages.dev/guide/tools-permissions)
 - [Runtime / Provider 事件流（Repo Doc）](docs/runtime-provider-event-flow.md)

docs/examples/feishu.yaml

@@ -1,9 +1,11 @@
 feishu:
   enabled: true
+  ingress: "webhook" # webhook | sdk
   app_id: "cli_xxx"
-  app_secret: "cli_secret_xxx"
+  # 群聊 @ 命中建议配置 bot 身份标识（至少一个）
+  bot_user_id: "ou_xxx"
+  bot_open_id: "ou_xxx"
   verify_token: "verify_token_xxx"
-  signing_secret: "signing_secret_xxx"
   insecure_skip_signature_verify: false
   adapter:
     listen: "127.0.0.1:18080"
@@ -17,3 +19,23 @@ feishu:
   gateway:
     listen: "127.0.0.1:8080"
     token_file: "~/.neocode/auth.json"
+
+# SDK 本地模式最小示例（无需公网回调）：
+# feishu:
+#   enabled: true
+#   ingress: "sdk"
+#   app_id: "cli_xxx"
+#   bot_user_id: "ou_xxx"
+#   bot_open_id: "ou_xxx"
+#   request_timeout_sec: 8
+#   idempotency_ttl_sec: 600
+#   reconnect_backoff_min_ms: 500
+#   reconnect_backoff_max_ms: 10000
+#   rebind_interval_sec: 15
+#   gateway:
+#     listen: "127.0.0.1:8080"
+#     token_file: "~/.neocode/auth.json"
+
+# 运行前请设置环境变量：
+#   export FEISHU_APP_SECRET="cli_secret_xxx"
+#   export FEISHU_SIGNING_SECRET="signing_secret_xxx" # 仅 webhook 必需

docs/guides/configuration.md

@@ -349,10 +349,12 @@ go run ./cmd/neocode --workdir /path/to/workspace
 ```yaml
 feishu:
   enabled: true
+  ingress: "webhook" # webhook | sdk
   app_id: "cli_xxx"
-  app_secret: "cli_secret_xxx"
+  # 群聊 @ 命中建议至少配置一个
+  bot_user_id: "ou_xxx"
+  bot_open_id: "ou_xxx"
   verify_token: "verify_token_xxx"
-  signing_secret: "signing_secret_xxx"
   insecure_skip_signature_verify: false
   adapter:
     listen: "127.0.0.1:18080"
@@ -371,6 +373,8 @@ feishu:
 启动命令：
 
 ```bash
+export FEISHU_APP_SECRET="cli_secret_xxx"
+export FEISHU_SIGNING_SECRET="signing_secret_xxx" # 仅 webhook 模式需要
 neocode feishu-adapter
 ```
 

docs/guides/feishu-adapter.md

@@ -1,93 +1,107 @@
-# Feishu Adapter 接入指南（Phase 1）
+# Feishu Adapter 接入指南（#554 + #557）
 
-本文档描述 #554 Phase 1 的最小可用接入方式：通过 `neocode feishu-adapter` 把飞书消息桥接到现有 Gateway。
+本文档说明 NeoCode Feishu Adapter 的两种入站模式：
 
-## 1. 边界说明
+- `webhook`：飞书回调到开发者服务（通常需要公网 HTTPS）。
+- `sdk`：本机 Adapter 通过飞书 SDK 长连接接收事件（无需公网回调）。
 
-- 本阶段只实现云端控制面桥接（Adapter）。
-- 不新增任何 Gateway RPC action。
-- 仅复用：
+## 1. 架构边界
+
+- Adapter 不直接调用 runtime 私有接口，只复用 Gateway 已有协议：
   - `gateway.authenticate`
   - `gateway.bindStream`
   - `gateway.run`
   - `gateway.resolvePermission`
-  - `gateway.event`（通知）
-- 不依赖 `gateway.createSession`。
-- 真正“云端飞书 -> 用户本机执行”的主动长连通道属于 #555，不在本阶段内。
-
-## 2. 会话与运行 ID 规则
-
-- `session_id = "feishu_" + stableHash(chat_id)`
-- `run_id = "feishu_" + stableHash(message_id)`
+  - `gateway.event`
+- 会话与运行 ID 保持实现一致：
+  - `session_id = "feishu_" + stableHash(chat_id)`
+  - `run_id = "feishu_" + stableHash(message_id)`
+- #557 只新增 SDK 入站，不包含 #555 Local Runner 主动长连。
 
-这两个 ID 都是确定性生成，便于幂等和追踪。
+## 2. 事件执行顺序
 
-## 3. 事件处理顺序
-
-飞书消息进入后，适配器固定执行：
+每条消息都按固定顺序执行：
 
 1. `authenticate`
 2. `bindStream(session_id, run_id)`
 3. `run(session_id, run_id, input_text)`
-4. 持续消费 `gateway.event`
+4. 持续消费 `gateway.event` 并回传飞书
 
-说明：必须先 `bindStream` 再 `run`，避免丢失 run 早期事件。
+## 3. 配置示例
 
-## 4. 幂等与重放防护
+完整示例见 [../examples/feishu.yaml](../examples/feishu.yaml)。
 
-- 消息事件去重键：`event_id + message_id`（TTL 内只执行一次 run）。
-- 卡片回调去重键：`request_id + decision`（TTL 内只提交一次审批）。
-- 去重在 `run` 被网关受理后才标记成功；若受理失败会释放去重键，允许飞书重试恢复。
+关键字段：
 
-## 5. 审批闭环
+- `feishu.ingress`：`webhook` 或 `sdk`，默认 `webhook`
+- `feishu.app_id`
+- `FEISHU_APP_SECRET`（固定环境变量，启动时必检）
+- `feishu.bot_user_id` / `feishu.bot_open_id`（群聊 @ 命中建议至少配置一个）
+- `feishu.verify_token`
+- `FEISHU_SIGNING_SECRET`（仅 `webhook` 强制，固定环境变量）
 
-Phase 1 仅支持最小动作：
+## 4. 启动方式
 
-- `allow_once`
-- `reject`
+### 4.1 Webhook 模式（#554）
 
-当收到 `permission_requested` 事件时，适配器发送最小审批卡片；用户点击后回调 `gateway.resolvePermission`。
+```bash
+neocode feishu-adapter --ingress webhook
+```
+
+通常还会覆盖地址参数：
+
+```bash
+neocode feishu-adapter \
+  --ingress webhook \
+  --listen 127.0.0.1:18080 \
+  --event-path /feishu/events \
+  --card-path /feishu/cards
+```
 
-## 6. 安全要求
+### 4.2 SDK 模式（#557，本地无公网）
 
-适配器日志不会打印以下敏感信息：
+```bash
+export FEISHU_APP_SECRET="cli_secret_xxx"
+neocode feishu-adapter --ingress sdk
+```
 
-- `app_secret`
-- `verify_token`
-- `signing_secret`
-- `gateway token`
-- `Authorization` 头
+SDK 模式下不要求公网回调地址，不要求 `adapter.listen/event_path/card_path`。
+如果缺少 `FEISHU_APP_SECRET`，启动会直接失败，避免把明文 secret 落到 `config.yaml`。
 
-默认要求签名校验与回调 token 校验都开启：
+## 5. 群聊触发规则
 
-- `verify_token` 必填
-- `signing_secret` 必填
+- 私聊：默认处理。
+- 群聊：必须 `@` 当前 bot 才会触发 run，建议配置 `bot_user_id` 或 `bot_open_id` 作为命中目标。
+- 任意 mention（@其他用户）不会触发 NeoCode。
 
-仅在联调场景可显式设置 `insecure_skip_signature_verify=true` 跳过签名校验（不建议生产使用）。
+## 6. 幂等与重试
 
-群聊消息默认仅在检测到 `@` 机器人时受理；私聊消息默认受理。
+- 消息去重键：`event_id + message_id`
+- 卡片去重键：`request_id + decision`
+- 仅当 `gateway.run` 成功受理后才标记成功；
+- 若 `run` 失败会释放去重状态，Webhook 返回 `HTTP 500`，SDK 长连接回调返回失败 ACK，允许飞书重试恢复。
 
-用户可见错误仅返回摘要，不回传内部堆栈。
+## 6.1 轻量级状态卡片
 
-## 7. 启动方式
+- 每个 run 会创建一个独立状态卡片，并复用同一个 `card_id` 更新：
+  - `任务`
+  - `状态`：`thinking / planning / running`
+  - `审批`：`none / pending / approved / rejected`
+  - `结果`：`pending / success / failure`
+- `permission_requested`、`hook_notification(async_rewake)`、`run_done`、`run_error` 都会更新同一张卡片，不额外刷多条进度文本。
+- 最终完成/失败仅更新卡片结果与摘要区，不额外回传独立文本消息。
 
-```bash
-neocode feishu-adapter
-```
+## 7. 审批能力边界
 
-也可以通过命令行参数覆盖配置：
+- Webhook 模式：支持卡片回调 -> `resolvePermission`。
+- SDK 模式：优先支持 SDK 卡片动作事件；若租户侧不可用，支持文本审批降级：
+  - `允许 <request_id>`
+  - `拒绝 <request_id>`
 
-```bash
-neocode feishu-adapter \
-  --listen 127.0.0.1:18080 \
-  --event-path /feishu/events \
-  --card-path /feishu/cards \
-  --app-id xxx \
-  --app-secret yyy \
-  --verify-token zzz \
-  --signing-secret sss
-```
+以上两种路径都复用 `gateway.resolvePermission`，不新增 Gateway action。
 
-## 8. 配置示例
+## 8. 安全要求
 
-参考 [../examples/feishu.yaml](../examples/feishu.yaml)。
+- 默认启用签名校验（Webhook）；
+- 日志不会输出 `app_secret`、签名密钥、gateway token、Authorization 等敏感信息；
+- 用户侧只回关键状态（受理、权限请求、完成、失败），不暴露内部堆栈和控制面细节。

go.mod

@@ -3,21 +3,28 @@ module neo-code
 go 1.25.0
 
 require (
+	github.com/Masterminds/semver/v3 v3.4.0
 	github.com/Microsoft/go-winio v0.6.2
 	github.com/anthropics/anthropic-sdk-go v1.37.0
 	github.com/atotto/clipboard v0.1.4
 	github.com/charmbracelet/bubbles v1.0.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/glamour v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
+	github.com/charmbracelet/x/ansi v0.11.6
+	github.com/creack/pty v1.1.24
 	github.com/creativeprojects/go-selfupdate v1.5.2
+	github.com/larksuite/oapi-sdk-go/v3 v3.6.1
 	github.com/openai/openai-go/v3 v3.32.0
+	github.com/pmezard/go-difflib v1.0.0
 	github.com/prometheus/client_golang v1.23.2
+	github.com/sahilm/fuzzy v0.1.1
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	golang.design/x/clipboard v0.7.1
 	golang.org/x/net v0.52.0
 	golang.org/x/sys v0.42.0
+	golang.org/x/term v0.41.0
 	google.golang.org/genai v1.54.0
 	gopkg.in/yaml.v3 v3.0.1
 	modernc.org/sqlite v1.48.2
@@ -29,28 +36,26 @@ require (
 	cloud.google.com/go/compute/metadata v0.5.0 // indirect
 	code.gitea.io/sdk/gitea v0.22.1 // indirect
 	github.com/42wim/httpsig v1.2.3 // indirect
-	github.com/Masterminds/semver/v3 v3.4.0 // indirect
 	github.com/alecthomas/chroma/v2 v2.20.0 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/charmbracelet/colorprofile v0.4.3 // indirect
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
-	github.com/charmbracelet/x/ansi v0.11.6 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
 	github.com/charmbracelet/x/exp/slice v0.0.0-20250327172914-2fdc97757edf // indirect
 	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/clipperhouse/displaywidth v0.11.0 // indirect
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
-	github.com/creack/pty v1.1.24 // indirect
 	github.com/davidmz/go-pageant v1.0.2 // indirect
 	github.com/dlclark/regexp2 v1.11.5 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/go-fed/httpsig v1.1.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/go-github/v74 v74.0.0 // indirect
@@ -76,14 +81,12 @@ require (
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/common v0.66.1 // indirect
 	github.com/prometheus/procfs v0.16.1 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/sagikazarmark/locafero v0.11.0 // indirect
-	github.com/sahilm/fuzzy v0.1.1 // indirect
 	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
@@ -107,7 +110,6 @@ require (
 	golang.org/x/mobile v0.0.0-20250606033058-a2a15c67f36f // indirect
 	golang.org/x/oauth2 v0.34.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/term v0.41.0 // indirect
 	golang.org/x/text v0.35.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250811230008-5f3141c8851a // indirect