dsh-attention-board 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 YG
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,226 @@
1
- # Temporary Holding Version
1
+ # dsh-attention · 阶段 1+2(数据层 + 面板)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 一个常驻的数字,告诉你**现在有几个会话在等你动手**。
4
+
5
+ ## 方向更正:票不用谁写
6
+
7
+ M1 最早的设想是自己维护一张票表(`state.json`),靠外部写入方往里填票。查过同类(agentpulse 等)之后改掉了:**这些事实本来就存在于会话里,不需要谁额外记账**。
8
+
9
+ `Waiting` 是算出来的:
10
+
11
+ ```
12
+ Waiting = (它跑完了一轮) × (你还没看过)
13
+ ```
14
+
15
+ agent 永远不知道自己在「等你」里——它跑完就结束了。所以这个数字不依赖任何 agent 配合,这是设计上最要紧的一点。
16
+
17
+ ## 四态
18
+
19
+ | state | 中文 | 判定 | 要不要你 |
20
+ |---|---|---|---|
21
+ | `error` | 出错 | 最后一轮 `turn/end` 的原因是 `error`,或停下后留着未读的工具错误 | **要** |
22
+ | `waiting` | 等你 | 跑完一轮且你没看过;或权限/提问挂着 | **要** |
23
+ | `working` | 在跑 | 有未结束的 turn | 不用 |
24
+ | `idle` | 空闲 | 剩下的一切(含用户自己喊停的 `aborted`) | 不用 |
25
+
26
+ 固定优先级:`error` > `waiting`(权限) > `working` > `error`(工具) > `waiting`(跑完) > `idle`。
27
+ 圆点上的数字只数前两种(`needsYou`)。
28
+
29
+ ## 数据从哪来
30
+
31
+ 只订阅一条:host 事件 `session/event`(`(session, event)`,post-commit 增量)。
32
+
33
+ | 事件 | 记账 |
34
+ |---|---|
35
+ | `turn/start` | 开轮 → 在跑;顺手清掉上一轮的错 |
36
+ | `turn/end` | 关轮;记 `reason.kind`,`error` 时存 message/code |
37
+ | `tool/result` | 有 `error` 就记下来(还在跑时不计入 error) |
38
+ | `user/message` | 人说话了 → 之前「等你」当场消解,不用谁去点已读 |
39
+
40
+ 不落盘、不起定时器、不写 `~/.dsh`。一个 `Map` 就是全部状态。
41
+
42
+ ## 文件
43
+
44
+ ```
45
+ lib/derive.js 纯函数:四态归约 + 计数 + 排序(零依赖,单测裸跑)
46
+ lib/probe.js 采集器:吃 session/event,喂 derive 认的行
47
+ lib/index.js 插件入口:订阅事件 + provide('attention') + /attention 命令 + 可选 HTTP
48
+ lib/http.js GET /dsh-attention/state(读快照)· POST /dsh-attention/seen(唯一写动作)
49
+ lib/store.js 旧的票表实现,不参与运行;declined 的账本形状当初就是照它定的
50
+ lib/client.js 浏览器半边:胶囊挂进 header slot + 分组面板 + ✓/✕/↺ 三个写动作(1158 行,无依赖,手写 DOM)
51
+ ```
52
+
53
+ ## 命令
54
+
55
+ ```
56
+ /attention # 全景:几件在等你 + 四态计数 + 点名到会话
57
+ /attention status # 同上
58
+ /attention seen <id> # 标记看过(水位只升不降)
59
+ /attention seen all # 全部标记看过
60
+ /attention raw # 核对:agents.list() 有几个活会话、采集到几行、各自内部状态
61
+ ```
62
+
63
+ `raw` 是给调试用的:它把 `agents.list()` 和采集行摊开对比,用来确认"数字对不上"是漏事件还是漏会话。
64
+
65
+ ## 测试
66
+
67
+ ```bash
68
+ cd projects/dsh-attention
69
+ node --test test/*.test.mjs # 67/67
70
+ ```
71
+
72
+ `test/derive.test.mjs` 21 例(归约、优先级、水位、清账、已拒、新事实顶掉拒绝)、`test/store.test.mjs` 10 例(旧票表,保留)、`test/index.test.mjs` 11 例(假宿主跑命令与 service 形状)、`test/http.test.mjs` 8 例(四条路由的真流桩:注册/鉴权/方法/体积上限)、`test/client.test.mjs` 17 例(浏览器半边:vm + 手写 DOM 桩,含 10 个变异体、3 条跨插件不变量、4 条交互链路)。
73
+
74
+ 注意必须显式给 `test/*.test.mjs`——`node --test test/` 会把目录当模块解析,直接 `MODULE_NOT_FOUND`。
75
+
76
+ ## 胶囊(阶段 3,`lib/client.js` 1158 行)
77
+
78
+ **它长在宿主的会话头里,不是浮在窗口上。** 通过 `conversation.session.header.utilities` 槽注册一个 React ref 壳,把原有的 DOM 实现原样塞进去(`useLayoutEffect` 里 `mount(host, { inline: true })`)。所以它跟着宿主布局走——侧栏收起、窗口变窄,它自己会挪,不用谁去算坐标。
79
+
80
+ 早先版本是 `position: fixed; right: 16px; top: 56px`,压住宿主自己的按钮,已废弃。
81
+
82
+ 胶囊本身**必须彻底无底**:主题 token、宿主按钮继承、浏览器默认样式,全部用内联 `!important` 压掉(`kill()` 逐条 `setProperty`)。CSS 优先级在这里靠不住——实测女仆主题下 `var(--attn-surface-hover)` 解析失败会让整条 `!important` 一起失效,所以悬浮色改成不依赖任何 token 的中性格灰 `rgba(140,140,140,0.18)`。
83
+
84
+ ### 六态
85
+
86
+ | 状态 | 长相 |
87
+ |---|---|
88
+ | 没事 | 一个灰点,透明底 |
89
+ | 悬浮 | 同上 + 浅灰方底 |
90
+ | 有人在等你 | 琥珀底 + 琥珀 `● 3` |
91
+ | 有东西坏了 | 红底 + 红 `● 2` |
92
+ | 只在跑 | 蓝点,透明底(不打扰) |
93
+ | 已拒 | 灰点,**不进数字**(你亲手拒的,不该再烦你) |
94
+
95
+ 有事才上色,没事全透明——**"没颜色"本身就是信息**。数字超过 99 显示 `99+`,免得把旁边两个 header 按钮挤歪。
96
+
97
+ 读不到的时候不装作没事,也不装作不知道:拿到过数字就继续显示那个数字(淡到 40%,标题写清"显示的还是上一次的"),只有从没拿到过才显示 `—`。闪成 `—` 会让人分不清"真没事"和"读不到"——这两种情况要的东西完全相反。
98
+
99
+ ### 点一下 `✓`
100
+
101
+ 每行右侧那颗 `✓` 是「我知道了」。
102
+
103
+ 只有 `error` / `waiting` 两态可点;`working` / `idle` 行是禁用的——它们没有等你消解的东西,给个能点的按钮只会骗你点。
104
+
105
+ 点击 → `POST /dsh-attention/seen {id}` → 成功后**立刻重拉快照**,数字当场变。不做乐观更新:本地路由几毫秒就回来了,先改 UI 反而会让失败的账对不上。
106
+
107
+ 失败时按钮恢复可点、那一行抖两下并变红。静默失败等于骗人。
108
+
109
+ 水位只升不降:点过就是点过了,要等下一次 `turn/end` 才重新计时。
110
+
111
+ ### 点一下 `✕`:拒绝并记账
112
+
113
+ `✓` 说「我知道了」,`✕` 说「这件事我不办」。后者是**唯一带理由的写动作**。
114
+
115
+ 点 `✕` 不会弹对话框——行内就地长出一个输入条问「为什么不要它?」,回车记账、Esc 取消。空着回车等于承认没写理由,那也算一条账(记账时写「没写理由」)。
116
+
117
+ ```
118
+ POST /dsh-attention/dismiss { id, reason } → 这一行变成「已拒」
119
+ POST /dsh-attention/undismiss { id } → 回到事实本身
120
+ ```
121
+
122
+ 三条规矩,都有用例钉着:
123
+
124
+ 1. **已拒的不进 `needsYou`**。你亲手拒掉的东西不该继续算在 `● N` 里,否则数字就失去了"要你处理"的含义。
125
+ 2. **拒绝 ≠ 静音**。它又跑完一轮、又报了个新错、又开了个新 turn——任何一条都算新事实,那条「不管了」自动作废,它会重新冒出来。静音是永远听不见,拒绝是听见了不管;代价就是它必须能自己回来。
126
+ 3. **撤销之后回到原来的样子**。所以 `markDeclined` **不动水位**——顺手推 `seenAt` 会把「跑完等你」这件事永久抹掉,撤销后只能落到 `idle`,那是假的。
127
+
128
+ 已拒的行整行退下去(名字变淡、理由变斜体),但理由留在原地:账本的意义就是事后还能看见为什么。
129
+
130
+ ### 主题
131
+
132
+ `[data-attn-root]` 上有一层变量映射,只认宿主的 `--dsw-alias-*` token:
133
+
134
+ | 本插件变量 | 宿主 token | 用途 |
135
+ |---|---|---|
136
+ | `--attn-bg` | `--dsw-alias-bg-overlay` | 面板/胶囊底 |
137
+ | `--attn-surface` | `--dsw-alias-bg-layer-1` | 行底 |
138
+ | `--attn-border` / `-strong` | `--dsw-alias-border-l1` / `-l2` | 描边 |
139
+ | `--attn-text` / `-sub` | `--dsw-alias-label-primary` / `-secondary` | 正文/次级 |
140
+ | `--attn-error` | `--dsw-alias-state-error-primary` | 出错 |
141
+ | `--attn-warn` | `--dsw-alias-state-warn-primary` | 等你 |
142
+ | `--attn-work` | `--dsw-alias-brand-primary` | 在跑 |
143
+ | `--attn-idle` | `--dsw-alias-state-idle-primary` | 空闲 |
144
+
145
+ 宿主切浅色主题时整块跟着变;宿主没给变量则回落到深色值。
146
+
147
+ 两处细节:**错误行的错因允许折到第二行**(`-webkit-line-clamp: 2`)——`TypeError: Cannot read properties of undefined` 这种最该读的话不该被一句省略号吞掉;行 `title` 是 cwd 加 why,悬停看全貌。
148
+
149
+ ## 与其他插件共存
150
+
151
+ 这个槽里已经站着别人了(grep 实测):
152
+
153
+ | 插件 | entry id | order |
154
+ |---|---|---|
155
+ | `dsh-better-sidebar` | `dsh-better-sidebar:context-diagnostics` | 20 |
156
+ | `dsh-better-sidebar` | `dsh-better-sidebar:bottom-toggle` | — |
157
+ | `dsh-purge-community` | `redteam-header-toggle` | 50 |
158
+ | **本插件** | `dsh-attention` | **60** |
159
+
160
+ order 没撞值,稳定落在最右。为此守了三条硬规矩(`test/client.test.mjs` 的 11–13 号用例钉着):
161
+
162
+ 1. **id 按实例派生**。`session.header.utilities` 是 session 作用域,分屏两个会话就有两个实例。第一个保留 `#dsh-attention-dot`,之后是 `-2`、`-3`;CSS 全部挂 `[data-attn-root]` 属性,所以序号怎么长都不影响样式命中。
163
+ 2. **`<style>` 按引用计数**。复用已存在的那份,最后一个实例卸载才真摘掉——否则先卸的那个会把别人的样式表一起删了。
164
+ 3. **slot 的 disposer 必须交回**。`slots.inject(...)` 有返回值,丢了就会在禁用/热重载后重复注册。
165
+
166
+ 另一条边界来自 better-sidebar 源码注释(他们踩过):**空白会话里宿主不渲染会话头,挂在 `header.utilities` 的入口跟着不可达**。所以新建空会话时胶囊不在,这是已知缺口,兜底排阶段 3。
167
+
168
+ ## 已知边界(阶段 1/2 故意留的)
169
+
170
+ 1. **加载前的历史不回放**。只监听增量,所以插件刚装上那一刻 `total = 0`,第一个 `session/event` 到达后立刻变准。`/attention raw` 能看出差多少。
171
+ 2. **`total` 是"我观察到几个会话"**,不是"你有几个会话"。措辞已经在命令里区分开,不假装知道全部。
172
+ 3. **权限/提问只看得见,点不了**。宿主那两个 waterfall 是"抢占回答权"的通道(见下节),我只记账不代答,所以面板里那行没有动作按钮——真要批准,去宿主自己的弹窗。
173
+ 4. **空白会话里胶囊的位置会换**:宿主不渲染会话头,槽入口跟着不可达,于是退回浮动件。浮动件不拍死在右上角——那儿站着宿主的「展开右侧栏」按钮,拍死就是又把别人盖住。它按那个按钮的 `aria-label`(中英文都认)认邻居,贴在它左边 8px;认不出来就往下让到 `top: 96px`,怎么都不压。会话头一出现,浮动件立刻让位。判据是「DOM 里有没有一个可见的 `[data-attn-root].is-inline`」,不是「我在哪个会话」——后者要轮询宿主状态,读失败还会按错的默认值降级(better-sidebar 的注释里记了这两个坑)。
174
+ **而且浮动件只在"真缺"时才出现**:必须这一版页面里亲眼见过 seat,之后它才消失,才挂浮标。冷启动时宿主主界面还没渲染出来,那种阶段宁可什么都没有——否则启动那一瞬间空白页上会凭空多一个孤立的小点,比不显示还难看。
175
+ 5. **面板里的行还差点"高级"**:行容器不可键盘聚焦(里面的 `✓` 按钮可以);30 秒轮询、失败无退避(页面藏起来时会停表,不在没人看的时候白烧)。
176
+ 6. **`lib/store.js` 不参与运行**:它是旧的票表实现,`declined` 的账本形状(`{reason, at}`)已落到 `derive.js` 的行上,这个文件留着当参照。
177
+
178
+ ## 路线
179
+
180
+ - **阶段 1**:数得准。纯逻辑 + 采集 + 命令。✅
181
+ - **阶段 2**:看得清。胶囊挂进宿主 header + 分组面板 + 跟随主题 + 跨插件共存。✅
182
+ - **阶段 3a**:动得了。面板里点 `✓` 直接标记已读(`POST /dsh-attention/seen` → 立刻重拉)。✅
183
+ - **阶段 3b**:拒绝并记账(`✕` → `POST /dsh-attention/dismiss`,带理由;`↺` 撤销)。✅
184
+ - **阶段 3c**:看得见"谁在卡住你"。权限与提问挂起时,那行变成 `等你批准 · Bash` / `等你回答 · 选哪个方案`,并且只显示不代答。✅
185
+ - **阶段 3d**:空白会话兜底。slot 注册成功不等于组件会被渲染,所以拿 DOM 存在性当判据:看不见就退回浮动件,看见就让位。比 better-sidebar 那套轻——首拍 600ms + DOM 变化 300ms 防抖,没有 500ms 周期表、没有命中测试走查。✅
186
+
187
+ ## 为什么权限只显示不代答
188
+
189
+ 宿主有两个 waterfall 事件:`approval/request` 和 `user-questions/request`。它们的签名是
190
+
191
+ ```js
192
+ (this, request, next) => Promise<Outcome>
193
+ ```
194
+
195
+ ——**不调 `next()` 直接返回一个值,就是把这条请求认领了**,宿主自己的弹窗根本不会出现。
196
+
197
+ 这条通道能拿到"一键批准",技术上没有门槛。但一个只读看板去接管权限闸,风险收益完全不匹配:
198
+
199
+ - 我在弹窗里替人点了"允许",人就真的没看见那条命令要干什么;
200
+ - 我要是卡住(网络、渲染、死循环),用户的审批流跟着断,而他不知道断在我这儿;
201
+ - 我要是猜错了 outcome 的取值,工具调用会拿到一个宿主没预期的答案。
202
+
203
+ 所以实现上只有三件事:**同步记一笔、立刻 `return next()`、请求落定或 abort 时清掉标记**。三个兜底都写了——记录抛错 try/catch 吞掉、`signal` 一 abort 就清、`next()` 的 promise `finally` 里再清一次。测试里钉死了"返回值必须就是 `next()` 的答案"和"观察者出错不改变审批结果"。
204
+
205
+ ## 装进 DSH
206
+
207
+ `cordis.patch.yml` 已经就绪:
208
+
209
+ ```yaml
210
+ - insert:
211
+ - id: dsh-attention-board
212
+ name: dsh-attention-board
213
+ config: {}
214
+ ```
215
+
216
+ 包名是 `dsh-attention-board`。`dsh-attention` 这个 npm 名字已经被别人占了(v0.4.1,一个通知/toast 形态的同类插件),所以这里加了 `-board`:**它是常驻看板,不是弹窗**。
217
+
218
+ 装法两种:
219
+
220
+ ```bash
221
+ # 市场里(需要先被 awesome-dsh-plugin 收录,见 PUBLISHING.md)
222
+ # 或直接给 npm 名
223
+ plugin_manager install_bundle target=dsh-attention-board
224
+ ```
225
+
226
+ 插件只读会话状态、只挂本地路由,不碰 `.npmrc` / `PATH` / git 全局配置。
@@ -0,0 +1,4 @@
1
+ - insert:
2
+ - id: dsh-attention-board
3
+ name: dsh-attention-board
4
+ config: {}