Imported from wingsky-1/dsh-plugin-hub (
packages/dsh-notifier/AGENTS.md). Install upstream withnpx skills add wingsky-1/dsh-plugin-hub --skill dsh-notifier. Copyright stays with the author.
AGENTS.md — dsh-notifier 包规则
本文件是
@wingsky-1/dsh-notifier的包级规范(叠加层)。改动本包src/、test/、cordis.patch.yml、package.json前必读。上层规则见仓库根AGENTS.md(硬性)与docs/DEVELOPMENT.md(权威详细版)。
定位
审批 / 提问 / 完成 / 出错事件通知:宿主事件经裁决管线投递到浏览器通知、系统 toast、
Bark / webhook 出站实例三类出口。配置自持于 <DSH_HOME>/@wingsky-1/dsh-notifier/,
设置卡片与宿主端读同一份设置形状(见 src/server/config/impl/model/type.ts)。
目录结构
src/index.ts— 组合根:本地FrameBus(裁决管线 → 浏览器出口的帧旁路)与各域装配。src/server/config/— 配置域:impl/model/(形状与DEFAULT_CONFIG默认表)、impl/input/(归一化、RETIRED_KEYS退役键 400 话术)、impl/redact/(凭据掩码)。src/server/upgrade/— 升级链:0.2.3 顶层渠道键搬进channels内置条目后删除。src/server/channels/— 渠道出口(system / browser / bark / webhook)与投递管线。src/server/api/— loopback 路由(含/eventsSSE 与/config掩码视图)。src/shared/— 两端共享叶子(sounds.ts音色白名单、webhooks.ts认证与预设)。src/client/notify/— 客户端通知面:audio.ts(节流PLAY_THROTTLE_MS、手势解锁)、session.ts(EventSource 订阅、since补拉与 seq 去重)。docs/sound-playback-design.md— 系统提示音语义与回退链的决策沉淀。
改动前必守(本包特有)
- 改
src/必须 build 才生效:dsh 经 profile 直读lib/产物,不自动编译。 - loopback 围栏:全部路由仅接受回环调用(非回环 403);smoke 必须含 403 / 405
围栏用例。经
dsh-lan-proxy转发的请求按设计视为受信,语义只引用该包 README。 - 凭据红线:凭据只走请求头与已知 secret 字段(
CHANNEL_SECRET_FIELDS单一事实源), 不拼 URL;GET /config与 PUT 成功响应一律掩码;新实例提交掩码 400;错误detail按原文截断、不做凭据替换(见包 README「安全模型」)。 - D-Bus 残余信任面:Linux 通知正文交给
org.freedesktop.Notifications当前 owner (同 UID 可抢占);能力探测只发NameHasOwner与ListActivatableNames两个只读查询, 不触发服务激活。改动探测或通知投递前重读包 README「安全模型」对应条目。 - 安全语义变更同步包 README 的「安全模型」节与测试(仓库硬性要求)。
文档指针
- 用户面:包
README.md(中文)/README.en.md(英文),节标题 1:1 对齐。 - 发声决策:
docs/sound-playback-design.md;架构总览:docs/architecture/dsh-notifier.md。 - 评审样本
docs/dsh-notifier-uiux-v022-sample.html为 v0.2.2 归档 mock,不代表现行设置卡。
验证(提交前全跑)
完成定义以根
AGENTS.md门禁矩阵为单一事实源;下列命令只作提交前自查。
pnpm --filter @wingsky-1/dsh-notifier build
pnpm --filter @wingsky-1/dsh-notifier test
提交
Conventional Commits(如 docs(dsh-notifier): ...),中文 subject,禁 emoji;
不 commit(由主代理整合提交)。
