@weibaohui/dsh-kite
放风筝引擎:agent 编程时,屏幕上空放一只动画风筝——token 越多、事件越密飞得越高;工具调用是阵风、失败会俯冲、里程碑空中翻滚、收工双圈庆祝;潍坊谱系框架卡组(硬翅沙燕/软翅金鱼/板式八卦/立体宫灯/串式飞龙……),支持把照片糊上风筝面、贴图随侧正斜姿态实时变换。
效果演示
核心功能
- 活动度 → 高度的规律:每轮 token 经 log 曲线累入按 τ≈75s 衰减的能量池,映射成 0..1 活动度,直接决定飞行高度(升快落慢);agent 停手约一分钟,风筝缓缓落回低空滑翔
- 事件 → 动作:回合完成上升冲量、工具成功扑翼抖擞(合批)、失败俯冲、里程碑抬升「高度地板」+空中翻滚(2k/8k/20k/50k/120k/300k 六档)、todo 清完双圈庆祝、新会话换新风筝
- 潍坊谱系卡组,换新不重样:15 骨架(硬翅:沙燕/龙头;软翅:金鱼/蝴蝶/老鹰/蜻蜓;板子:菱形/八卦/六角/圆月/蝙蝠;立体:宫灯;串式:飞龙;仿生:蝉/热带鱼)× 11 种图案画师(燕面/梅花/祥云/鳞纹/海水纹/羽纹/放射线/牡丹/满天星/横纹/虹谱)× 12 套传统配色 = 26 张策展卡;换风筝走洗牌袋不放回抽取,稀有度 1–5 加权,绝不与上一只重复
- 七彩流转与串式飞龙:「七彩鲢·虹」的帆面色相随活动度连续流转(
dynamicHue,越忙转得越急);「飞龙」以 verlet 链物理拖曳串式龙身,里程碑每升一档 +2 节、越长越威风
- 鼠标联动:风场朝指针方向偏置——风筝追着鼠标漂、抬头低头追随,快划掀起阵风,指针贴近还会抖擞;设置页「鼠标联动」可关
- 风筝线墨色:随主题(默认)/彩虹流转(速率随活动度,越忙转得越快)/自定义纯色,三选一;主线、尾链、龙身连接线统一用色
- 事件换新:不止新会话换风筝——轮次结束、报错、子代理启动、里程碑跨档、收工都可以当场换一只(翻滚揭晓,洗牌袋不重样);设置页「换新时机」逐项勾选,默认全开(普通工具调用除外),10 秒冷却防连换
- 形状 × 图案 × 配色全数据化:
client/kite-cards.js 里 FRAMES(轮廓/竹条/图案分区/贴图映射区/尾链挂点)、PATTERNS(在任意闭合分区内作画)、PALETTES、ALL_CARDS 全是纯数据——加一只新风筝只需追加一条数据
- 自定义贴图,姿态跟随:设置页上传照片(客户端压到 ≤640px,持久化),贴图糊进骨架映射区、与帆面共用同一仿射位姿矩阵——正身是照片,侧身压窄变暗,翻面透出半透明帆布背面与竹条
- 活的物理:噪声风场漫游、随机摆动、布料沿翼尖扑动、verlet 尾链挂红黄蝴蝶结、线绳低空松垂高空绷直并带微风抖动
- 共享事件通道:事件经 dsh-event-hub 枢纽单连接(ws 主通道,握手后豁免于 h1.1 的 6 连接预算)推送,与烟花/矩阵/进程共用;枢纽缺席自动降级自有 SSE/轮询,独立安装不受影响
- 透明浮层零侵入:
position:fixed; pointer-events:none,不挡任何点击;显示范围可选全屏/左右侧边栏/四角
- 明暗主题跟随:挂在 dsh 官方主题属性上事件驱动切换,浅色主题用墨线重烘焙帆面、换深色线绳
- 开箱即管:设置页总开关、风力/体型、高度响应、鼠标联动、换新时机、风筝线、显示范围、按骨架分组钉住任意一只形象、逐骨架开关(带缩略图)、贴图上传/启停/浓淡、试飞按钮(升空/俯冲/翻滚/换一只)、实时状态
- 性能自律:常驻动画 30fps 节流、帆面纹理按渲染倍率超采样(低 DPR 屏强制 1.3–1.6× 抗锯齿)、
imageSmoothingQuality: high、页面隐藏暂停、prefers-reduced-motion 自动停放
安装
dsh plugin --profile web add @weibaohui/dsh-kite -w
装完重启 dsh web 即生效。入口:设置 → 放风筝(管理面板 + 试飞按钮)。
使用
- 正常编程即可,风筝自己飞:token 涌入攀升 → 工具调用抖擞 → 跨里程碑翻跟头并抬高地板 → 收工双圈庆祝 → 新会话自动换新
- 嫌吵:设置页收窄显示范围、调低「高度响应」,或直接收线(总开关)
- 想让自己(的猫/表情包)上天:设置 → 自定义贴图 → 上传图片 → 勾「使用贴图」
- 只想放某一只:设置 → 当前风筝 → 钉住(如「沙燕 Swallow」);或关掉谱系里不喜欢的骨架
- 控制台彩蛋:
__dshKite.next() 换一只、__dshKite.pulse('milestone') 手动来风、__dshKite.stats() 看飞行状态
- 不装插件也能预览引擎:浏览器打开
demo/demo.html(?act=0..1 锁定活动度、?frame=shayan 钉住骨架,右上角可传贴图)
事件 → 风筝行为
| 事件 | 行为 |
|---|
assistant/message(token 用量) | 累入能量池 → 活动度 → 目标高度 |
turn/end | 上升冲量(规模随本回合 token) |
tool/result 成功 | 扑翼抖擞 + 微风(合批) |
tool/result 失败 | 俯冲 + 乱流(合批,克制) |
| 累计 output 跨档 | 空中翻滚 + 高度地板永久抬升 |
todo/write 全完成 | 双圈翻滚庆祝(5 分钟冷却) |
session/created | 换一只新风筝(洗牌袋不重样) |
框架卡组 schema(client/kite-cards.js)
骨架/图案/配色/卡全部是纯数据,引擎只消费 resolveCard() 的落定谱与
paintSail() 的帆面绘制。新增一只风筝 = 追加一条数据,不改引擎。
// 骨架:单位空间 x∈[-1,1] 向右、y∈[-1,1] 向下(尾巴挂在 +y)
FRAMES.myframe = {
id: 'myframe', name: '我的', nameEn: 'My Kite',
family: 'board', // hard 硬翅 | soft 软翅 | board 板子 | box 立体
size: 1, // 相对翼展
outline: [[0, -1], [0.62, 0], [0, 1], [-0.62, 0]], // 帆面轮廓
cells: [{ role: 'body', poly: [...] }], // 图案分区(role: head/wing/body/tail/panel/core)
spars: [[0, -1, 0, 1]], // 竹条(线段)
decalQuad: [[-0.62, -1], [0.62, -1], [0.62, 1], [-0.62, 1]], // 贴图映射区
tail: { attach: [[0, 1]], segs: 12, segLen: 0.11, bows: true, width: 3 },
flap: { amp: 0.05, k: 2.2 }, // 布料扑动
bridle: [0, -0.12], // 线绳拴点
}
// 图案画师:在任意分区内作画,(u,v)∈[-1,1] 指分区自身包围盒
PATTERNS.mypattern = ({ g, P, hw, hh, rng, pal, ink, role }) => { /* … */ }
// 卡:骨架 × 图案 × 配色(可按 role 组合/覆盖),进洗牌袋
ALL_CARDS.push({
id: 'myframe-plum', name: '我的·梅', nameEn: 'Plum MyKite',
frame: 'myframe', pattern: 'plum', palette: PALETTES.cinnabar,
cellPatterns: { head: 'face' }, rolePalettes: { body: PALETTES.pearl },
rarity: 2, flavor: '……',
})
设置页可按骨架开关(config.frames)、钉住某只(config.preferredFrame);被关掉的骨架不再进洗牌袋。
配置项
| 键 | 默认 | 说明 |
|---|
enabled | true | 总开关(收线落地) |
intensity | 1 | 风力/体型缩放 0.3–2 |
responsiveness | 1 | 活动度→高度响应 0.3–2 |
region | fullscreen | fullscreen / left / right / bottom-left / bottom-right |
preferredFrame | auto | auto(洗牌袋)或骨架 id |
frames | {} | 按骨架开关,如 { bat: false } |
decalEnabled | false | 把用户贴图糊上帆面 |
decalOpacity | 0.9 | 贴图浓淡 0.3–1 |
ignoreReducedMotion | false | 无视系统减弱动态效果偏好 |
实现说明
宿主(src/index.js) 客户端(client/)
───────────────── ─────────────────
session/event 事件流 全屏/区域透明 canvas 浮层
↓ 能量池(τ≈75s 衰减)/分类 (fixed, pointer-events:none)
dsh-event-hub 枢纽单连接 ──→ PluginKit.connectEvents 订阅
{activity, tier} + 阵风脉冲 ↓ 活动度→高度 / 脉冲→动作
姿态矩阵(朝向/侧倾/俯仰/翻滚)
├ 帆面纹理 drawImage(npm 包烘焙)
└ 贴图仿射变换 + verlet 尾链
- 宿主:订阅
session/event 做能量累计与事件分类,状态/脉冲经 dsh-event-hub
枢纽单连接广播( shortage 时回退自有 SSE,/dsh-kite/api/updates 增量轮询兜底);
配置与贴图存 storageDomain(域 dsh_kite)持久化
- 姿态与贴图:贴图与帆面纹理共用同一仿射位姿矩阵(朝向 face/侧倾 roll/俯仰
pitch/翻滚 spin),帆面图案按骨架分区烘焙进离屏纹理,逐帧仅一次 drawImage;
贴图经 cover 裁剪进 decalQuad,背面自动镜像减淡
- 构建:
client/kite-cards.js + kite-engine.js + index.js 由
scripts/build-client.mjs 内联进 bundle 工厂作用域(含 dsh-plugin-kit 客户端源码)
HTTP API(宿主)
| 路由 | 说明 |
|---|
WS /dsh-event-hub/ws | 共享事件推送主通道(枢纽;首个消费者注册) |
GET /dsh-kite/api/updates?since= | 增量状态+补帧(轮询回退通道,毫秒级返回) |
GET /dsh-kite/api/stream | 自有 SSE(枢纽缺席时的回退) |
GET /dsh-kite/api/config | 读配置 |
POST /dsh-kite/api/config | 存配置(storageDomain 持久化) |
GET /dsh-kite/api/decal | 读用户贴图(data URL) |
PUT /dsh-kite/api/decal | 上传/替换贴图(≤660KB,png/jpeg/webp) |
DELETE /dsh-kite/api/decal | 移除贴图 |
POST /dsh-kite/api/test | 试飞 { kind?, magnitude? } |
开发
npm run check # 语法检查
npm test # 13 项离线测试(卡组完整性/洗牌袋/缩放/宿主契约/存根渲染)
npm run build:client # kite-cards + kit client + kite-engine + index → client/bundle.js
link 安装的实例改完源码 npm run build:client 后刷新页面即生效。
联系我 :飞书群
link
版本兼容性
本插件与 DeepSeek Harness(@deepseek-ai/dsh)的版本对应关系:
| 插件版本 | 适配 dsh 版本 | 备注 |
|---|
| 0.1.0 | 0.1.7-rc.2 | 首个公开发布;含共享事件枢纽接入(经 dsh-plugin-kit 0.5.x)、贴图姿态跟随、30fps 节流渲染 |
发版约定:每次发布新版本时,请在上表追加一行,记录该插件版本实际验证所用的 @deepseek-ai/dsh 版本。package.json 的 engines.dsh 声明最低支持版本;本表记录实际验证版本,二者配合使用。
License
MIT
