飞书桥接 wanwang416/DSH-Wing

DSH-Wing

DeepSeek Harness 的飞书原生插件 — 过程透明 · 插话不打断 · 完整桥能力

DeepSeek Harness 飞书原生插件 — 过程透明 · 插话不打断 · 完整桥能力

✨ Core Features / 核心特性

🎯 Transparent Streaming / 过程透明

智能体的思考过程流式呈现，单卡打字机效果，告别黑盒。CardKit 流式引擎支持三级降级：CardKit 打字机 → 整卡更新 → 纯文本消息，任何环境下都能稳定输出。
思考过程流式呈现，单卡打字机效果，告别黑盒。CardKit 流式引擎支持三级降级。

💬 Non-Interruptive Follow-ups / 插话不打断

任务进行中可随时插话，主任务不丢上下文。四类中断分类器智能识别：任务进行中可随时插话，主任务不丢上下文。四类中断分类器智能识别：
- COMMAND（停止 / 改向）→ 立即中断 / 立即中断
- QUESTION / CONFIRM（疑问 / 确认）→ 排队注入，不打断主任务 / 排队注入，不打断主任务
- ORDINARY（推进词 / 纯确认）→ 推进词注入，纯确认仅回执 / 推进词注入，纯确认仅回执
- 设置 DSH_WING_INTERRUPT_CLASSIFIER=0 可回退经典模式 / 可通过环境变量回退经典模式

🎛️ Interactive Cards / 交互卡片

- 单选卡 — /preset /model /mode /permission 一键切换 / 单选卡一键切换
- 审批卡 — 危险操作四个按钮（仅本次允许 / 本会话允许 / 始终允许 / 拒绝），支持老板 open_id 限定，防止群聊他人越权批准 / 审批卡四按钮，支持老板 open_id 限定，防止群聊他人越权批准

🔒 Permission System / 权限控制

三档权限粒度，默认保守 / 三档权限粒度，默认保守：

| Mode / 模式 | Description / 说明 |
| read-only | 只读，禁止任何写操作 / 只读，禁止任何写操作 |
| workspace-write | 默认，仅允许工作区内写入 / 默认，仅允许工作区内写入 |
| danger-full-access | 完全访问，危险操作弹审批卡 |

🧭 意图路由

群聊命令、提问、闲聊智能分流，纯寒暄不误触发智能体。支持四种群聊触发策略：open / mention / keywords / reply。

🛡️ 可靠性

- 断线补偿 —— WS 断连期间消息不丢，重连后自动补偿
- 撤回即停 —— 用户撤回消息，立即取消对应智能体任务
- WAL 留痕 —— 入站消息预写日志，崩溃可恢复
- 连接自愈 —— WS 假死检测（60s ping 超时）+ 自动重连
- Outbox 重试 —— 出站消息失败自动重试，指数退避

🏗️ 架构设计

三层架构

┌─────────────────────────────────────────────────────────┐
│ Platform Adapter Layer / 平台接入层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │ Feishu │ │ WebSocket│ │ Event Dispatcher │ │ │ │ SDK │ │ Client │ │ │ │ │ └──────────┘ └──────────┘ └──────────────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ Core Engine Layer / 核心层 (platform-agnostic / 平台无关)│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │ │ │ Inbound │ │ Session │ │ Experience│ │ Outbound │ │ │ │ Pipeline │ │ Manager │ │ Layer │ │ Outbox │ │ │ │(parse/ │ │(map/ │ │(stream/ │ │(retry/ │ │ │ │ dedup/ │ │ persist/ │ │ interject│ │ degrade/ │ │ │ │ batch) │ │ serialize)│ │ /tools) │ │ shard) │ │ │ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │ ├─────────────────────────────────────────────────────────┤ │ Agent Driver Layer / Agent 驱动层 (DSH-native / DSH 原生)│ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │ DSH Agent│ │ Tool Call│ │ LLM / Reasoning │ │ │ │ Driver │ │ Stream │ │ │ │ │ └──────────┘ └──────────┘ └──────────────────────┘ │ └─────────────────────────────────────────────────────────┘

消息链路

Feishu message → WS → Dispatcher → Session Mapper → DSH Agent
→ Session Events (6 types) → Forwarder → Experience
→ Sender / Outbox → Feishu reply

🚀 快速开始

前置要求

- Node.js >= 24.0.0
- DeepSeek Harness (DSH) 运行环境
- 飞书自建应用（App ID + App Secret）

安装

Clone the repository / 克隆仓库bash
git clone https://github.com/wanwang416/DSH-Wing.git
cd DSH-Wing

Install dependencies / 安装依赖

npm install

Build (host tsc + client tsdown) / 构建

npm run build

Configuration / 配置 bash

1. Copy the config template / 复制配置模板

cp cordis.patch.example.yml cordis.patch.yml

2. Edit the config / 编辑配置

- workspaceRoot: your workspace path / 你的工作区路径

- groupPolicy: group-chat trigger strategy (open/mention/keywords/reply) / 群聊触发策略

- permissionMode: permission mode (read-only/workspace-write/danger-full-access) / 权限模式

Credential configuration (choose one) / 凭据配置（二选一）：

Option A — DSH credential system (recommended) / 方式 A — DSH 凭据系统（推荐）：bash

Register in the DSH credential system / 在 DSH 凭据系统中注册

credentialRef: WING_LARK_APP

value: {"appId":"cli_xxx","appSecret":"xxx","domain":"feishu"}

Option B — Environment variables / 方式 B — 环境变量：bash
export DSH_WING_APP_ID=cli_xxxxxxxxxxxx
export DSH_WING_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Setup Feishu Application / 初始化飞书应用 bash

Run interactive setup (generates a QR code, scan to register the Feishu app)

运行交互式 setup（生成 QR 码，扫码注册飞书应用）

npx dsh-wing setup

Or trigger via the /setup command in a Feishu chat

或使用 /setup 命令在飞书聊天中触发

Diagnostics / 诊断 bash

Environment check / 环境检查

npx dsh-wing doctor

WebSocket connection test / WebSocket 连接测试

node scripts/diag-ws.mjs

Message listener test / 消息监听测试

node scripts/diag-listen.mjs

💬 WeCom (WeChat Work) Intelligent Bot Line / 企业微信智能机器人线路

长连接（WebSocket）双向对话，与飞书线路并存；单聊（p2p）直通为主场景，群聊走 groupPolicy（@机器人名精确触发）。

Enable / 启用（二选一）

1. 扫码绑定（默认）：浏览器打开 GET /plugins/dsh-wing/wecom/qr（无活跃流程自动发起扫码；已绑定返回 409，?force=1 重新绑定）→ 企微 App 扫码 → 凭据写入 WING_WECOM_BOT → 自动重启桥生效（无需重启宿主）。
2. 手填兜底：配置 wecom.botId / wecom.secret，或环境变量 WECOM_BOT_ID / WECOM_BOT_SECRET。

Config / 配置 yaml wecom: enabled: true # true=开；缺省=有凭据即开；false=显式关闭 botName: '' # 群聊 @机器人名（精确触发，需与企微后台显示名一致） source: dsh-wing # 扫码绑定来源标识（多 Agent 隔离） welcomeText: '你好，我是 DSH 智能助手。直接发消息即可开始对话。'

Notes / 说明

- 群聊仅「@机器人名」触发（未配置 botName 时维持宽松并提示）；首条群聊消息输出诊断日志核对名字拼写。
- 帧回复按字节分片（4000B/片，超 13 片截断提示）；流式单帧 19000B，仅末片 finish；欢迎语受企微 5 秒窗口约束保持单片。
- 单会话限频 30 条/分钟，长回答自动分片共用配额。
- Web 面板前端企微入口（D7b）另立工单。

📋 Command Reference / 命令参考

| Command / 命令 | Description / 说明 |
| /preset | Switch Agent Preset (code / general / ...) / 切换 Agent Preset |
| /model | Switch LLM model / 切换 LLM 模型 |
| /mode | Switch runtime mode / 切换运行模式 |
| /permission | Switch permission mode / 切换权限模式 |
| /resume | Resume a historical session / 恢复历史会话 |
| /workspace | View / switch workspace / 查看/切换工作区 |
| /steer | Gently interrupt the current task / 温和打断当前任务 |
| /stop | Immediately stop the current task / 立即停止当前任务 |
| /setup | Initialize Feishu application config / 初始化飞书应用配置 |
| /status | View current status / 查看当前状态 |
| /doctor | 环境诊断检查 |
| /new | 开启新会话 |
| /help | 显示帮助 |

⚙️ 配置详解

cordis.patch.yml
yaml
- insert:
- id: wing
name: 'dsh-wing'
config:
enabled: true
credentialRef: WING_LARK_APP # DSH 凭据引用名 appId: '' # 或环境变量 DSH_WING_APP_ID appSecret: '' # 或环境变量 DSH_WING_APP_SECRET groupPolicy: mention # open/mention/keywords/reply workspaceRoot: /path/to/workspace # 工作区根目录 streaming: enabled: true # 默认开启流式 flushMs: 500 # 流式刷新间隔 permissionMode: workspace-write # 默认保守权限 turnTimeoutMs: 600000 # 轮次超时（10分钟） agentPreset: code # 默认 Agent Preset bossOpenId: '' # 老板 open_id（审批卡片限制） steerDiagLogPath: '' # steer 诊断日志路径（默认关闭）

环境变量

| 变量 | 说明 | Default |
| DSH_WING_APP_ID | 飞书 App ID 覆盖 | — |
| DSH_WING_APP_SECRET | 飞书 App Secret 覆盖 | — |
| DSH_WING_INTERRUPT_CLASSIFIER | 中断分类器开关（0=关闭） | 1 |
| DSH_WING_SDK_LOG | 飞书 SDK 日志文件路径 | — |
| DSH_HOME | DSH 主目录（诊断脚本用） | — |

🛠️ 开发 bash

类型检查

npm run typecheck

仅构建 host

npm run build:host

仅构建 client

npm run build:client

完整构建（host + client）

npm run build

运行测试

npm test

监听模式测试

npm run test:watch

覆盖率报告

npm run coverage

项目结构

DSH-Wing/
├── src/
│ ├── index.ts # 插件入口，组装所有模块 │ ├── agent/ # Agent 驱动层 │ │ ├── caller.ts # Agent 调用封装 │ │ ├── experience.ts # 体验契约（stream/interject/tool-visible） │ │ ├── forwarder.ts # 事件转发器 │ │ ├── intent.ts # 意图识别 │ │ ├── model.ts # 模型管理 │ │ ├── permission.ts # 权限判断 │ │ ├── preset.ts # Preset 管理 │ │ ├── turn-supervisor.ts # 轮次监督器 │ │ └── user-questions.ts # 用户问题处理 │ ├── client/ # 前端客户端（DSH ModuleLoader） │ │ ├── index.ts │ │ └── icons.ts │ ├── commands/ # 斜杠命令 │ ├── config/ # 配置默认值 │ ├── doctor/ # 环境诊断 │ ├── host/ # 平台接入层 │ │ ├── client.ts # 飞书 SDK 客户端 │ │ ├── credentials.ts # 凭据管理 │ │ ├── quota.ts # 配额治理 │ │ ├── status.ts # 状态存储 │ │ ├── supervisor.ts # 连接监督器 │ │ └── websocket.ts # WebSocket 传输 │ ├── inbound/ # 入站管道 │ │ ├── batching.ts # 消息批处理 │ │ ├── chat-type.ts # 聊天类型判断 │ │ ├── compensation.ts # 断线补偿 │ │ ├── dedup.ts # 消息去重 │ │ ├── dispatcher.ts # 事件分发 │ │ ├── event-handler.ts # 事件处理器 │ │ ├── group-policy.ts # 群聊策略 │ │ ├── interrupt-classify.ts # 中断分类器 │ │ ├── parser.ts # 消息解析 │ │ └── wal.ts # 预写日志 │ ├── interactive/ # 交互卡片 │ │ ├── approval.ts # 审批卡 │ │ ├── reaction.ts # 表情回应 │ │ ├── router.ts # 交互路由 │ │ └── selector.ts # 单选卡 │ ├── outbound/ # 出站管道 │ │ ├── cardkit.ts # CardKit 封装 │ │ ├── chunker.ts # 消息分片 │ │ ├── fallback.ts # 降级策略 │ │ ├── outbox.ts # 出站队列 │ │ ├── sender.ts # 消息发送 │ │ ├── streaming-card.ts # 流式卡片引擎 │ │ └── tool-step.ts # 工具步骤渲染 │ ├── session/ # 会话管理 │ ├── setup/ # 初始化流程 │ └── web/ # Web 面板 ├── tests/ # 562 个单元测试 ├── scripts/ # 诊断脚本 ├── docs/assets/ # 文档素材 ├── .github/workflows/ci.yml # CI 配置 ├── package.json ├── tsconfig.json ├── tsdown.config.ts └── cordis.patch.example.yml

🗺️ 路线图

| 里程碑 | 内容 | 状态 |
| M0 | 骨架 + API 签名 + 插话验证 | ✅ 完成 |
| M1 | 最小可用 + 体验先行（流式 / 插话 / 保守权限 / Outbox） | ✅ 完成 |
| M2 | 可靠性 + 富文本 + 全事件 | ✅ 完成 |
| M3 | 交互 + 权限 + 插话增强（CardKit 流式 / ToolStep 富卡片） | ✅ 完成 |
| M4 | 易用性 + 诊断 + 完整度补齐 | ✅ 完成 |
| M4.1 | 单选卡 + 审批卡 + 意图桥 + 第二批命令 | ✅ 完成 · 562 项测试 |
| M4.2 | /doctor 诊断包 + Web 扫码面板 | ✅ 完成 |
| M5 | 多平台扩展（Discord / Telegram / Slack） | 📋 规划中 |
| M6 | 插件市场 + 可视化配置面板 | 📋 规划中 |

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 开启 Pull Request

📄 许可证

本项目采用 MIT License 开源协议。

用 ❤️ 和 TypeScript 构建

由 DeepSeek Harness 驱动 · 飞书开放平台