dsh-task-cat 0.0.0-stage → 1.0.1

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/README.md CHANGED
@@ -1,3 +1,97 @@
1
- # Temporary Holding Version
1
+ # 任务宠物(dsh-task-cat)
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
+ 猫有两种出现方式:
8
+
9
+ - **窗口内(默认)**:浮在 Harness 窗口右下角,展开后是任务清单。
10
+ - **桌面浮窗**:浮在**整块屏幕**上、位于其它软件之上,即使 Harness 被最小化或被别的窗口盖住也仍然可见。**默认关闭**,需要在清单头部点显示器按钮,并在弹出的说明里确认一次才会启用(第一次启用会在后台编译一个小助手,通常几秒钟)。
11
+
12
+ ## 它显示什么
13
+
14
+ | 信息 | 来源 | 说明 |
15
+ | --- | --- | --- |
16
+ | 进行中 | 会话运行状态 + `taskPet` 投影 | 宠物呼吸加快,徽章显示运行中的会话数 |
17
+ | 进度 | `todo_write` 的待办列表 | 行内进度条与 `已完成/总数`,运行中显示已用时长、当前步骤与最近工具(工具报错时补一个 `⚠`) |
18
+ | 待查看 | 会话状态(完成未读、待回答问题) | 徽章变成琥珀色,宠物张大嘴「!」 |
19
+ | 失败 | 上一轮 `turn/end` 语义 | 红点 + 「上次运行失败」,不进入徽章计数 |
20
+ | 目标 | 该会话的 goal 投影 | 无待办时显示当前目标 |
21
+
22
+ 徽章是「需要你」的优先计数(待查看),没有待查看时才退回运行中数量;超过 9 显示 `9+`。标题下方还有一句汇总,说明当前整体状态(例如「1 个会话进行中 · 1 个待查看」),因为一个数字说不清两件事。
23
+
24
+ ## 桌面浮窗(macOS)
25
+
26
+ Harness 的桌面外壳并没有向插件开放窗口 API(preload 只暴露文件、内嵌浏览器、快捷键与更新),Chromium 的 Document Picture-in-Picture 在 Electron 里没有实现,页面里的 `window.open` 又会被外壳一律拒绝——所以页面自己无论怎么写都只能在自己的窗口里浮动。
27
+
28
+ 因此真正的屏幕级浮窗由一个原生小助手承担:
29
+
30
+ - `overlay/TaskPetOverlay.swift`:一个无边框、置顶、不抢焦点的 `NSPanel`(`.statusWindow` 之上、不抢焦点、跨空间、全屏可见),用 AppKit/CoreGraphics 直接绘制宠物。
31
+ - `desktop.js`:首次使用时用系统的 `swiftc` 把它编译到 `$DSH_HOME/cache/dsh-task-pet/TaskPetOverlay`(源码不变就不重复编译),然后以子进程运行。
32
+ - 通信只有一条管道:状态以 JSON 行写入它的 stdin,点击意图以 JSON 行从 stdout 读回。**没有端口、没有令牌**,也就没有任何需要鉴权的东西。
33
+ - 页面与 Host 之间走一条只允许本机回环的受保护路由 `/dsh-task-pet/overlay`:POST 推送状态,GET 长轮询取回点击意图。
34
+
35
+ 行为细节:
36
+
37
+ - 点一下桌面宠物 → 在**宠物正上方**弹出会话卡片,再点一下关闭(空间不够时自动翻到下方,并始终留在屏幕内)。卡片的层级和窗口内那份面板一致:标题「任务宠物」+ 一句话汇总 + 一句说明,下面依次是会话,每行是「状态点 + 标题 + 状态行 + 进度条」,当前打开的那一行用一张圆角卡片标出来,并带「· 当前会话」。状态点按类型上色(进行中=蓝色实心带呼吸光晕、待查看=琥珀、失败=红、已完成=绿、推进中但没在跑=薄荷空心、空闲=灰空心),状态行和窗口内那只宠物用的是同一句话(例如 `4m · 2/5 · bash`、`待查看`、`上次运行失败`),有 todo 的行下面还有一条进度条。清单**按最近更新排序**(新开的会话排在最上面),默认显示 **5 个**,更多的收在底部「还有 N 个会话…」里,点一下展开全部、再点收起。点其中一行跳到那个对话,并把 Harness 窗口带到前台。卡片跟随应用的浅色/深色主题(页面把当前明暗传给助手),不会出现深色卡片压在白底应用上。
38
+ - 宠物本身下方也有一条细进度条,显示「点它就会跳到的那个会话」的完成度;不用打开清单就能看出走到哪一步了。
39
+ - 按住拖动可换位置;位置记在 `$DSH_HOME/cache/dsh-task-pet/position.txt`,换屏、拔掉显示器后会自动拉回可视区域。
40
+ - 菜单栏也有一项「任务宠物」:图标是那只宠物,待处理时带上数字,点开能看汇总和说明,以及隐藏 / 移到当前屏幕 / 打开 Harness。
41
+ - 右键:动作菜单(打开 Harness / 移到当前屏幕 / 隐藏桌面宠物)。
42
+ - 卡片不会抢焦点:鼠标移开卡片和宠物一会儿就自动收起,再点宠物也能收起。
43
+ - 「隐藏桌面宠物」只对本次运行生效;清单头部的显示器按钮随时能把它叫回来,重启 Harness 也会恢复你之前的设置。
44
+ - 桌面宠物每 15 秒被探活一次;如果它卡死不应答,会被自动重启(连续三次起不来就关掉桌面模式并在清单里说明原因)。页面关掉后它也检测不到心跳,五分钟后自动退出,不会留下一只点不动的宠物。
45
+ - 同一台机器同时只保留一只桌面宠物:多个 Harness 窗口时,先拿到的那只负责显示,其余窗口会在清单里说明,并且每 12 秒重试一次,那个窗口一关就自动接管。
46
+ - 帮助面板里的提示只在这只宠物真的在屏幕上时出现;编译失败、系统不支持或与另一个窗口冲突,都会在清单里直接写明原因,而不是静默失败。
47
+ - 桌面浮窗真正在屏幕上时,窗口内这只**完全不渲染**(空的,不是变淡);桌面浮窗没启动或失败时,窗口内这只照常出现,不会两头空。
48
+ - 桌面宠物支持 VoiceOver(朗读当前最要紧的会话),菜单可用键盘方向键操作;第一次出现的位置在鼠标所在的那块屏幕右下角,之后跟随上次的位置。
49
+ - 助手的菜单语言跟随应用当前语言(由页面把 locale 传下来),不受 `LANG=C.UTF-8` 影响。
50
+ - 非 macOS 系统上这个按钮不出现,宠物只在窗口内漂浮;编译器缺失或编译失败时按钮同样不出现,并在清单里说明原因。
51
+
52
+ ## 这只猫
53
+
54
+ 按参考图重画的长毛白猫:绒球似的轮廓(头部和身体都有毛簇)、琥珀色眼睛、粉鼻头、胡须,尾巴一直在慢慢摆。它在两种尺寸上是同一只猫——桌面那只由 AppKit 绘制,窗口内那只是同一套几何的 SVG,配色和比例对齐。
55
+
56
+ 动作都在「没有状态变化时」也保持活着:呼吸(身体轻微起伏)、尾巴按自己的节奏摆动(工作时更快)、偶尔眨眼、耳朵偶尔抖一下;睡着时闭眼并冒出 `z`,需要你时瞳孔放大、右上角弹出感叹号圆盘。
57
+
58
+ ## 交互
59
+
60
+ - **点宠物**:展开/收起任务清单,按紧急程度排序:进行中 → 待查看 → 有进度 → 失败 → 已完成 → 空闲。
61
+ - **点清单行**:直接切换到那个对话(和侧边栏打开会话是同一条路径)。
62
+ - **拖动**:按住宠物拖动可换位置,位置会被限制在窗口内;窗口缩小后会自动拉回可视区域。
63
+ - **收起**:清单头部的「—」把宠物收成一个小图标(徽章仍保留),再点即恢复。
64
+ - **关闭**:清单头部的「×」、`Esc`、或点击清单外部任意位置。
65
+ - 清单最多列出 8 个会话,超出时底部出现「还有 N 个会话」,点一下展开全部、再点收起。
66
+
67
+ 已归档的会话不会出现在清单里,避免误点把它重新拉回工作区。
68
+
69
+ ## 结构
70
+
71
+ - `index.js`:Host 半边,注册 `taskPet` 会话投影(`todo/write`、`goal/change`、`turn/*`、`tool/call`、`tool/result`、`user/message`),把视图放进每个会话列表行的 summary,因此前端不需要按会话单独拉取。
72
+ - `client.js`:浏览器半边,注册到 `shell.overlay`,只读 `useSessions` / `useWorkspaces` / `useSessionStatus` 三个标准数据源,不轮询、不写 DOM。样式使用主题 token(`--dsw-alias-*`、`--dsw-specific-menu`、`--dsw-elevation-*`),浅色/深色都跟随应用。
73
+ - `desktop.js`:桌面浮窗的宿主端托管(编译、启动、JSON 行协议、空闲回落、心跳与崩溃退避)。
74
+ - `overlay/TaskPetOverlay.swift`:桌面浮窗本体(AppKit),自己也会读取偏好文件,没被启用时直接退出。会话清单是一块自绘的卡片(`NSPanel` + 滚动视图),每行是自绘视图(状态点、标题、状态行、进度条),所以不打开 Harness 也能看清真实进度。
75
+ - `cordis.patch.yml`:bundle 的 Loader 条目。
76
+ - `locale/*.json`:插件标题与描述(中文、英文)。
77
+ - `icon.svg`:插件图标。
78
+
79
+ 界面文案提供 8 种语言:`zh`、`en`、`ja`、`es`、`fr`、`de`、`ru`、`pt`,与应用的共同词条语言集合一致。
80
+
81
+ ## 安装
82
+
83
+ 从 npm 安装:
84
+
85
+ ```bash
86
+ dsh plugin add dsh-task-cat
87
+ ```
88
+
89
+ 或在「设置 → 插件」里搜索 `dsh-task-cat` 安装。安装后立即生效,无需重启。
90
+
91
+ 也可以直接从本目录安装(开发用):
92
+
93
+ ```bash
94
+ dsh plugin add /path/to/dsh-task-cat
95
+ ```
96
+
97
+ macOS 上首次启用桌面浮窗时,会用系统的 `swiftc` 在 `$DSH_HOME/cache/dsh-task-cat` 里编译一次原生的浮窗助手(几秒钟),之后复用。