@leiyi-works/dsh-session-tmpdir 0.7.0 → 0.8.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.
Files changed (3) hide show
  1. package/README.md +190 -187
  2. package/index.js +2340 -2178
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,187 +1,190 @@
1
- # Task Temp Folder(session-task-tmpdir)v0.7.0
2
-
3
- 给每个 DSH 会话一个**任务临时目录**,并在**会话被删除 7 天后**自动清掉对应目录:
4
-
5
- ```
6
- <会话工作目录>/_tmp/<会话标题>/
7
- ```
8
-
9
- 同时守住工作区根目录:**临时文件只能进 `_tmp/`;长期文件必须用户点头后才能落盘**。
10
-
11
- v0.7 起,这条规则不再只靠 `write`/`edit`/`pwsh`/`bash` 四个工具名:**publish 交付复制、python/node 等代码执行工具、以及任何在 schema 里声明了路径参数的写类工具都会被纳入检查**,工作区之外的落点也一并纳入。
12
-
13
- ## 一句话规则(v0.7)
14
-
15
- - 临时产物(下载文件、中间数据、截图、调试日志、一次性稿)→ `_tmp/<会话标题>/`,**不问用户**,直接写;
16
- - 长期产物(跨会话复用/存档/交付成品)→ 先问用户(选择题);用户同意 → `longterm_approve` 登记其指定目录后写入;用户否定 → **退回 `_tmp`**;
17
- - 未经同意的长期落点(包括在工作区根新建文件夹、`publish` 到 `Download/`、python 写盘、工作区外任意位置)→ 在**工具层直接拒绝**,并给出纠正提示。
18
-
19
- ## 功能介绍
20
-
21
- | 功能 | 行为 |
22
- |---|---|
23
- | **任务临时目录** | 每个会话在**自己的工作目录**下得到 `_tmp/<会话标题>/`;换工作区也各自生效 |
24
- | **改名同步** | 会话标题就是任务名;改名时目录**自动重命名**(连同里面的文件) |
25
- | **重启可认领** | 目录内 `.dsh-task.json` 记录 session id;重启后靠标记文件对上 |
26
- | **取路径工具** | `task_tmpdir` 返回**当时**的准确路径(自动创建、跟随改名),可选 `sub` 建子目录 |
27
- | **长期落点审批** | `longterm_approve` 登记"本次会话已获用户同意的长期目录"(工作区内、工作区外都行),登记后该目录可写 |
28
- | **工作区拦截** | guard 覆盖 `write`/`edit` + `pwsh`/`bash`:未审批的 `_tmp` 之外落点一律拒绝 |
29
- | **写入通道覆盖(v0.7)** | publish 交付复制、python/node 代码写盘、schema 带路径参数的未知工具统一走同一判定 |
30
- | **工作区外判定(v0.7)** | 工作区外除 DSH 主目录/缓存/系统临时目录外一律视为长期落点,未登记即拒绝 |
31
- | **孤儿目录清理** | 会话被删除后,临时目录保留 7 天再删;会话还在的目录永不删 |
32
- | **手动清理** | `tmp_cleanup` 立刻跑一轮清理(`dryRun: true` 只报告) |
33
-
34
- ## 配置(cordis.patch.yml 的 config)
35
-
36
- | 字段 | 默认 | 说明 |
37
- |---|---|---|
38
- | `rootDirName` | `_tmp` | 临时目录根名(相对会话工作目录) |
39
- | `includeSubagents` | `false` | 是否给子代理会话也建目录 |
40
- | `maxNameLength` | `60` | 目录名最大长度 |
41
- | `orphanCleanupDays` | `7` | 会话被删除后保留多少天再清理;`0` = 关闭清理 |
42
- | `cleanupIntervalHours` | `24` | 清理扫描间隔(小时) |
43
- | `cleanupDryRun` | `false` | 只打印"会标记/会删哪些"、不动手 |
44
- | `guardWorkspaceRoot` | `true` | v1 临时文件规则总开关(根目录临时命名、`_tmp/` 根文件) |
45
- | `requireApprovalOutsideTmp` | `true` | 长期落点审批总开关(`false` 时 v0.5 + v0.7 全部通道的落点判定一并关闭,只留 v1 临时文件规则) |
46
- | `allowRootPatterns` | `['dsh-*']` | 无需审批的根目录名(glob,`*`/`?`) |
47
- | `allowRootFiles` | `['.dsh-standing-rules.md']` | 无需审批的工作区根文件 |
48
- | `commandGuard` | `deny` | pwsh/bash 命令守卫:`deny` / `warn`(只记日志)/ `off` |
49
- | `guardOutsideWorkspace` | `deny` | v0.7 工作区外写入:`deny` / `warn` / `off` |
50
- | `publishGuard` | `deny` | v0.7 `publish` 交付复制目标检查:`deny` / `warn` / `off` |
51
- | `guardCodeTools` | `true` | v0.7 静态扫描 `python`/`node` 等代码执行工具里的写文件语句 |
52
- | `guardUnknownTools` | `true` | v0.7 对"没按名字识别、但 schema 带路径参数"的写类工具做兜底检查 |
53
- | `outsideAllow` | 内置 | v0.7 追加"无需审批即可写"的工作区外目录(绝对路径或 glob,`**` 跨层;纯目录条目不含子项,用 `/**` 覆盖子文件) |
54
- | `publishBaseDir` | 无(= 会话 cwd) | v0.7 相对 `publish` 目标的解析基准(例如鸿蒙上实际交付根是 `Download/` 的父目录时填它) |
55
- | `writeToolNames` | 内置 | v0.7 追加写工具名(`write`/`edit` 已内置) |
56
- | `publishToolNames` | 内置 | v0.7 追加交付工具名(`publish`/`present` 已内置,`present` 只展示不复制) |
57
- | `codeToolNames` | 内置 | v0.7 追加代码执行工具名(`python`/`node` 等已内置) |
58
- | `attachmentCleanup` | `true` | v0.6 附件回收总开关(会话删除后回收其附件) |
59
- | `attachmentCleanupDays` | 同 `orphanCleanupDays` | 会话删除后多少天回收其附件;`0` = 只扫地孤儿 |
60
- | `attachmentSweepOrphans` | `true` | 是否同时清扫"无人引用且够旧"的历史孤儿附件 |
61
- | `attachmentsDir` | `<DSH_HOME>/attachments` | 附件仓库根目录(一般不用改) |
62
-
63
- ## 长期文件审批流程
64
-
65
- 1. 模型判断某文件需要长期保存,且不在任务指定位置;
66
- 2. 模型调用 `ask_user_question` 给用户选择题(标签只写 **A 不长期保存** / **B 工作区根目录保存**,细节放选项 description 小字;选 B 时模型自行起目录名、不再跟用户确认;其他位置由用户直接在输入框里写路径);
67
- 3. 用户选长期 + 给路径 → 模型调 `longterm_approve({ path, reason, basis })` 登记(**工作区外目录也能登记**,例如鸿蒙的 `Download/<包名>/`;但不能登记磁盘根目录、用户主目录本身或层级过浅的目录);
68
- 4. 之后 `write`/`edit`、shell 命令、`publish` 交付、python 等代码工具才能写该目录;用户否定 → 模型改用 `task_tmpdir` 写 `_tmp`。
69
-
70
- `longterm_approve` 的登记是**按会话内存保存**:Host 重启或会话结束即清空,需要时重新审批(不会把"同意"永久写死)。
71
-
72
- ## guard 行为边界(v0.7)
73
-
74
- 判定顺序:`_tmp` 段(只在**工作区内或系统临时目录**里算临时区,v0.7 收紧)→ 已登记目录 → 白名单;工作区内走长期落点判定,工作区外走外部落点判定。
75
-
76
- | 通道 | 判定方式 | 说明 |
77
- |---|---|---|
78
- | `write` / `edit` | 完整判定 | 工作区根新建、未登记子目录、工作区外未登记 → 拒绝 |
79
- | `pwsh` / `bash` | 命令文本启发式 | 含创建动词(`New-Item`/`cp`/`mv`/`sed`/`tee`…)或重定向(`>`/`>>`)时,扫描命令里的绝对路径(Windows 盘符;HarmonyOS/POSIX `/` 开头,先剥掉 `scheme://` URL);重定向目标即使已存在也判(覆盖/追加属长期写入),其它已存在路径不拦(多为 copy/读取源) |
80
- | `publish` | 复制目标判定 | 只检查 `target`/`destination`/`to`/`output`/`save_path` 等(`source` 是读侧,不拦);目标在工作区根、未登记子目录或工作区外 → 拒绝并提示先问用户 |
81
- | `present` | 不拦 | 只声明已有文件为交付物,不复制、不落盘 |
82
- | `python` / `node` 等 | 静态扫描 | 写信号(`open(...,'w')`、`write_text`、`shutil.copy`、`json.dump`、`Image.save`…)与同语句路径字面量(含 `sub/x.md` 这类相对路径)配对;动态拼路径拦不到(默认边界) |
83
- | 其它工具 | schema 兜底 | 工具名/描述含写语义(write/save/export/render/copy/install…)且**顶层**参数值像路径时,**只拦两类高危目标**:工作区根新条目、工作区外未登记位置;工作区内子目录放行,避免误伤 |
84
-
85
- **不误伤的设计**(v0.7 审查后加固):只读工具名(`read*`/`list*`/`get*`/`show*`/`view*`/`check*`/`status*`/`query*`/`search*`/`find*`/`glob`/`grep`/`count*`/`stat*`)一律跳过;本插件自己的 `task_tmpdir`/`longterm_approve`/`tmp_cleanup` 永远放行;schema 里声明为 `enum` 的参数、`@e3`/`#submit` 这类选择器、`this_session`/`new_once` 这类枚举值、`@scope/pkg` 包名和 URL 都不算路径;嵌套对象里的同名参数(`expect[].target`、workflow `args.files`)不算写目标。
86
-
87
- 工作区外"天然允许"范围(无需审批,`outsideAllow` 可追加):`<DSH_HOME>`(`~/.dsh`,含插件/密钥/配置)、`~/.cache`、`~/.npm`、`~/.config`、`~/.local/share`、`~/.flova`、系统临时目录;POSIX 设备上另有 `/tmp`、`/var/tmp`、`/dev/shm`、`/run/user`、`/data/local/tmp`、`/storage/emulated/0/Android/data`。`/dev/null`、`NUL`、`$null` 之类伪路径直接放行。
88
-
89
- 拦不到(fail-open,**不是安全边界**):变量/动态拼接的路径、脚本内部逻辑、外部程序、GUI 操作、绕过工具的 fs 调用;`warn` 模式只记日志不拦(`guardOutsideWorkspace`/`publishGuard`/`commandGuard` 的 `warn` 在四个通道统一生效)。
90
-
91
- 其它:**工作区内**的规则只在会话工作目录 = 已注册工作区根时生效(会话 `cd` 到子目录时不把项目顶层文件当成"工作区根新建条目");**工作区外**的判定不受 cwd 限制,`cd` 到子目录也照拦(v0.7 修复);guard 是**全局**的——队友/子代理/定时任务会话同样受约束。
92
-
93
- ## 回归测试(v0.7)
94
-
95
- `test/guard.test.mjs`(38 条纯函数用例)覆盖反馈里给的绕过场景 + 独立审查发现的问题:
96
-
97
- | # | 用例 | 期望 |
98
- |---|---|---|
99
- | 1 | `write` → `_tmp/<标题>/x.md` | 允许 |
100
- | 2 | `write` → `<cwd>/x.md` | 拒绝 + A/B 提示 |
101
- | 3 | `write` → `<cwd>/<未批准目录>/x.md` | 拒绝 |
102
- | 4 | `write` → 工作区外(`Download/…`) | 拒绝 |
103
- | 5 | `publish` → `Download/<包名>/x.md`(未登记) | 拒绝 |
104
- | 6 | `present` → 工作区外已有文件 | 允许(只展示) |
105
- | 7 | `python`:`open('/storage/…/工作区根/x.md','w')` | 拒绝 |
106
- | 8 | `python`:`open('…/_tmp/…/x.md','w')` | 允许 |
107
- | 9 | `bash -c 'echo hi > /storage/…/工作区根/x.md'`(POSIX) | 拒绝 |
108
- | 10 | `cp a.md /storage/…/Download/x.md`(POSIX) | 拒绝 |
109
- | 11 | 未识别工具 `output` → 工作区根 / 工作区外 | 拒绝 |
110
- | 12 | 未识别工具 `output` → 未批准子目录 | 允许(降误伤) |
111
- | 13 | `longterm_approve` 登记工作区外目录后再写 | 允许 |
112
- | 14 | `longterm_approve` 登记磁盘根 / `_tmp` | 抛错 |
113
- | 15 | `schedule_create` / `bsk_interact` 的 `target` 是枚举/选择器 | 不算写目标(允许) |
114
- | 16 | `plugin_manager` 的 `target` 是包名/entry id | 不算写目标(允许) |
115
- | 17 | `workflow` 的 `args.files`(嵌套) | 不算写目标(允许) |
116
- | 18 | `read_image`(描述含"不要 install/create") | 只读,跳过 |
117
- | 19 | 本插件自己的 `task_tmpdir`/`longterm_approve`/`tmp_cleanup` | 永远放行 |
118
- | 20 | `echo hi >> …`、`2>> …` | 拒绝(`>>` 正确解析) |
119
- | 21 | `> NUL`、`> $null`、`Write-Host "1 > 0"` | 放行(伪路径/引号内文本) |
120
- | 22 | `curl https://…`、`git clone https://…` | 放行(URL 不是盘符路径) |
121
- | 23 | 重定向到**已存在**的长期文件 | 仍拒绝(覆盖属长期写入) |
122
- | 24 | 工作区外 `Desktop/_tmp/x.md` | 拒绝(`_tmp` 段只在工作区内算临时) |
123
- | 25 | `python`:`open('sub/x.md','w')`(相对) | 拒绝 |
124
- | 26 | `res.write('ok')` + `'/api/v1/items'` | 放行(不再误伤流写入) |
125
- | 27 | `guardOutsideWorkspace: warn` 下 shell/code | 放行(只记日志) |
126
- | 28 | 子目录 cwd(`skipInside`) | 工作区内放宽、工作区外仍拒绝 |
127
-
128
- `test/integration.test.mjs`(14 条)用 stub Host 上下文真正跑注册进 `ctx.tools.guard` 的回调:`write`/`publish`/`present`/`python`/未知工具/`pwsh`、`longterm_approve` 登记后解锁、拒绝根目录与 `_tmp`、审查回归(审批工具不被自锁、标准工具不误伤、子目录 cwd 仍拦工作区外、`>>` 覆盖已存在文件、不存在文件路径登记其目录)。另可跑 `node test/live-matrix.mjs`(需要 `test/live-tools.json`)把当前 profile 的全部 live 工具灌进 guard 做误伤矩阵。
129
-
130
- ## 自动清理规则(安全边界)
131
-
132
- - 判定依据是「会话是否还存在」:先看活跃会话(`ctx.sessions`),再看已持久化会话(`sessionPersistence.list()`,取不到时回退扫描 `~/.dsh/sessions`)。
133
- - 会话还在 → 目录保留;会话已删除 → 首次扫描标记孤儿(`orphanedAt`),满 `orphanCleanupDays` 天后下一次扫描删除。
134
- - **只处理带本插件标记的目录**(`.dsh-task.json` 且含 sessionId);手工放进 `_tmp` 的其他目录不碰。
135
- - 启动后约 60 秒跑第一次,之后按 `cleanupIntervalHours` 周期跑;`orphanCleanupDays: 0` 关闭清理。
136
- - 删除是**整目录递归删除**,不备份;想先观察就把 `cleanupDryRun: true` 开着跑一轮。
137
-
138
- ## 附件回收规则(v0.6)
139
-
140
- Host 的附件仓库(`~/.dsh/attachments`)按内容 hash 存储、**自身没有任何回收机制**:删掉会话只删日志,图片会永远留在磁盘上。本插件把附件也接进同一条 7 天清理链路:
141
-
142
- 1. 每轮清理时,通过 `sessionPersistence` 读取**每个已存会话**的事件,收集 `attachmentId`(`sha256:<hash>`),写进台账 `~/.dsh/data/session-tmpdir-attachments.json`;
143
- 2. 台账按 `revision` 缓存——会话没变就不重读,稳态开销几乎为零;
144
- 3. 会话消失 → 台账记 `orphanedAt`;满 `attachmentCleanupDays` 天后,删除**只被该会话引用**的 blob;
145
- 4. 任何时候只要还有别的存活会话引用同一个 hash,就跳过(同一张图被多个会话用过的安全阀);
146
- 5. `attachmentSweepOrphans` 开启时,额外清扫「无任何会话引用 + 文件本身够旧」的历史孤儿(覆盖本功能上线前就残留的那批);
147
- 6. 最近 1 小时内写入的 blob 一律不碰;每次删除追加到 `~/.dsh/data/session-tmpdir-attachments-gc.jsonl`(hash / 大小 / 时间 / 原因),可审计。
148
-
149
- `tmp_cleanup` 的返回里多一个 `attachments` 字段(删除数、释放 MB、待回收会话数、跳过数);`dryRun: true` 只统计不动手。
150
-
151
- ## 开发
152
-
153
- ```powershell
154
- node --check index.js
155
- node --test "test/*.test.mjs" # 38 条纯函数用例 + 14 条集成用例(stub Host 上下文)
156
- node test/live-matrix.mjs # 可选:本机 live 工具误伤矩阵(需 test/live-tools.json)
157
- ```
158
-
159
- > POSIX 路径语义(`/storage/...`、大小写敏感)在 Windows 上只能验证解析器分支;真机行为请以 HarmonyOS Host 上的实际调用为准。
160
-
161
- v0.5 变更(2026-11-07):新增长期落点审批(`longterm_approve` + guard v2),覆盖 pwsh/bash 命令;修复 v1 只拦"临时命名文件"导致根目录被会话自建文件夹的问题。
162
-
163
- v0.5.2 变更(2026-11-12):长期落点选择题的选项顺序调整——A 改为"不长期保存,放 `_tmp/<会话标题>/`(临时)",C 改为"长期保存到本次任务指定的目录";B(新建归档目录)不变。落盘规则本身无变化。
164
-
165
- v0.5.3 变更(2026-11-12):B/C 选项文案按实际使用重写,消除语义重叠——B 改为"工作区根目录保存"(长期保存到会话工作区根目录下,一般新建一个目录,如 `归档/<主题>/`);C 改为"存到指定位置(写明路径)",并明确选 C 但未给路径时模型必须先向用户确认,不得自行猜路径。规则与 guard 未改。
166
-
167
- v0.5.4 变更(2026-11-12):按实际弹窗效果精简选项——删掉 C("存到指定位置"与输入框重复,用户改成在自由输入框写路径即可,模型收到非 A/B 答案时按指定位置处理,路径不清先追问);B 去掉括号说明,只留"工作区根目录保存"。规则与 guard 未改。
168
-
169
- v0.5.5 变更(2026-11-12):选项标签统一写短(A 只写"不长期保存",路径等说明移到选项 `description` 小字),并要求不许把路径细节塞进标签;避免长标签把 GUI 里的描述小字顶到下一行造成排版不一致。规则与 guard 未改。
170
-
171
- v0.5.6 变更(2026-11-12):选 B(工作区根目录保存)时不再要用户确认目录名——模型自行起一个清楚的目录名、`longterm_approve` 登记后直接写,跟 DSH 平时自己命名落盘一样;B 的小字改为"目录名自动起"。规则与 guard 未改。
172
-
173
- v0.5.7 变更(2026-11-12):微调选项小字——A 的说明改为"随会话删除后 N 天清理"(N 取 `orphanCleanupDays`,默认 7,不再写死"随会话删除清理");B 的说明删掉"目录名自动起"字样,只留"长期保存到会话工作区根目录下"(自动起名行为本身不变)。规则与 guard 未改。
174
-
175
- v0.6.0 变更(2026-11-13):新增**附件回收**——7 天清理会话目录时,一并回收该会话的附件 blob(台账 + 引用二次校验 + 扫描历史孤儿 + 审计日志),解决 `~/.dsh/attachments` 只增不减的问题。通过 `sessionPersistence` 读事件,不依赖日志格式、不自带 zstd 解码;`tmp_cleanup` 增加 `attachments` 参数与 `attachments` 输出字段。临时目录规则与 guard 未改。
176
-
177
- v0.7.0 变更(2026-11-15):按 HarmonyOS DSHM 真机反馈(桌面文件「临时目录插件-长期文件规则绕过分析.md」)补齐写入通道覆盖——原来 guard 只认硬编码的 `write`/`edit`/`pwsh`/`bash` 工具名、只认 `file_path`/`path` 参数、只判工作区内部、shell 只认 Windows 盘符路径,导致 `publish` 交付复制、`python` 写盘等通道静默绕过。本次改动:
178
-
179
- 1. **按能力识别工具**(`toolWritePlan`):写工具 / shell / 代码执行 / 交付(`publish`;`present` 只展示)/ 未知写类工具五类通道,未知工具从 schema 的路径参数识别,新增工具不再漏;
180
- 2. **工作区外也判**:除 DSH 主目录、缓存、系统临时目录和已登记目录外,工作区外写入一律视为长期落点(`guardOutsideWorkspace`,可 `warn`/`off`);
181
- 3. **`publish` 纳入判定**:复制目标(`target`/`destination`/`to`/`output`)未登记即拒绝,`source` 不拦;`present` 只展示不拦;
182
- 4. **`python`/`node` 静态扫描**:写信号 + 同语句路径字面量配对判定,动态拼接路径声明为已知边界;
183
- 5. **shell 平台适配**:HarmonyOS/POSIX 下解析 `/` 开头绝对路径与 `cp`/`mv`/`sed`/`tee` 等命令,`>` 重定向单独视为创建;
184
- 6. **`longterm_approve` 支持工作区外目录**(鸿蒙 `Download/<包名>/` 等),拒绝磁盘根目录/主目录/层级过浅目录;
185
- 7. 提示文本同步说明覆盖通道与 fail-open 边界;新增 38 条纯函数 + 14 条集成回归测试。
186
-
187
- **独立审查后加固(同发 0.7.0)**:`longterm_approve`/`task_tmpdir`/`tmp_cleanup` 永远不被自己的 guard 判定(否则审批通道自锁);未知工具通道只看顶层参数,跳过 enum、选择器、包名和 URL(否则 `schedule_create`/`bsk_interact`/`plugin_manager` 必被误拒);只读工具名白名单(`read_image` 等);`>>` 重定向正确解析、`NUL`/`$null`/引号内文本不误判、Windows 路径扫描先剥 URL;工作区外 `_tmp` 段不再算临时区;工作区外判定不再随 cwd 关闭;重定向到已存在长期文件仍拒绝;`longterm_approve` 传入不存在的文件路径时登记其目录、并拒绝登记工作区根本身;`toolWritePlan` 判定改用实际参数值,POSIX 大小写/分隔符语义按平台区分。审查时用本机 59 个 live 工具矩阵验证:53 个工具零误伤,仅真实写类工具(`write`/`edit`/`pwsh`)和参数值确实是路径的兜底工具被判定。
1
+ # Task Temp Folder(session-task-tmpdir)v0.8.0
2
+
3
+ 给每个 DSH 会话一个**任务临时目录**,并在**会话被删除 7 天后**自动清掉对应目录:
4
+
5
+ ```
6
+ <会话工作目录>/_tmp/<会话标题>/
7
+ ```
8
+
9
+ 同时守住工作区根目录:**临时文件只能进 `_tmp/`;长期文件必须用户点头后才能落盘**。
10
+
11
+ v0.7 起,这条规则不再只靠 `write`/`edit`/`pwsh`/`bash` 四个工具名:**publish 交付复制、python/node 等代码执行工具、以及任何在 schema 里声明了路径参数的写类工具都会被纳入检查**,工作区之外的落点也一并纳入。
12
+
13
+ ## 一句话规则(v0.7)
14
+
15
+ - 临时产物(下载文件、中间数据、截图、调试日志、一次性稿)→ `_tmp/<会话标题>/`,**不问用户**,直接写;
16
+ - 长期产物(跨会话复用/存档/交付成品)→ 先问用户(选择题);用户同意 → `longterm_approve` 登记其指定目录后写入;用户否定 → **退回 `_tmp`**;
17
+ - 未经同意的长期落点(包括在工作区根新建文件夹、`publish` 到 `Download/`、python 写盘、工作区外任意位置)→ 在**工具层直接拒绝**,并给出纠正提示。
18
+
19
+ ## 功能介绍
20
+
21
+ | 功能 | 行为 |
22
+ |---|---|
23
+ | **任务临时目录** | 每个会话在**自己的工作目录**下得到 `_tmp/<会话标题>/`;换工作区也各自生效 |
24
+ | **改名同步** | 会话标题就是任务名;改名时目录**自动重命名**(连同里面的文件) |
25
+ | **重启可认领** | 目录内 `.dsh-task.json` 记录 session id;重启后靠标记文件对上 |
26
+ | **写入即认领(v0.8)** | 用普通 `write`/shell 在临时根下自起目录名时,guard 顺手补写当前会话的标记,不再产生“永远不清理”的无主目录 |
27
+ | **取路径工具** | `task_tmpdir` 返回**当时**的准确路径(自动创建、跟随改名),可选 `sub` 建子目录 |
28
+ | **长期落点审批** | `longterm_approve` 登记"本次会话已获用户同意的长期目录"(工作区内、工作区外都行),登记后该目录可写 |
29
+ | **工作区拦截** | guard 覆盖 `write`/`edit` + `pwsh`/`bash`:未审批的 `_tmp` 之外落点一律拒绝 |
30
+ | **写入通道覆盖(v0.7)** | publish 交付复制、python/node 代码写盘、schema 带路径参数的未知工具统一走同一判定 |
31
+ | **工作区外判定(v0.7)** | 工作区外除 DSH 主目录/缓存/系统临时目录外一律视为长期落点,未登记即拒绝 |
32
+ | **孤儿目录清理** | 会话被删除后,临时目录保留 7 天再删;会话还在的目录永不删 |
33
+ | **手动清理** | `tmp_cleanup` 立刻跑一轮清理(`dryRun: true` 只报告) |
34
+
35
+ ## 配置(cordis.patch.yml 的 config)
36
+
37
+ | 字段 | 默认 | 说明 |
38
+ |---|---|---|
39
+ | `rootDirName` | `_tmp` | 临时目录根名(相对会话工作目录) |
40
+ | `includeSubagents` | `false` | 是否给子代理会话也建目录 |
41
+ | `maxNameLength` | `60` | 目录名最大长度 |
42
+ | `orphanCleanupDays` | `7` | 会话被删除后保留多少天再清理;`0` = 关闭清理 |
43
+ | `cleanupIntervalHours` | `24` | 清理扫描间隔(小时) |
44
+ | `cleanupDryRun` | `false` | 只打印"会标记/会删哪些"、不动手 |
45
+ | `guardWorkspaceRoot` | `true` | v1 临时文件规则总开关(根目录临时命名、`_tmp/` 根文件) |
46
+ | `requireApprovalOutsideTmp` | `true` | 长期落点审批总开关(`false` 时 v0.5 + v0.7 全部通道的落点判定一并关闭,只留 v1 临时文件规则) |
47
+ | `allowRootPatterns` | `['dsh-*']` | 无需审批的根目录名(glob,`*`/`?`) |
48
+ | `allowRootFiles` | `['.dsh-standing-rules.md']` | 无需审批的工作区根文件 |
49
+ | `commandGuard` | `deny` | pwsh/bash 命令守卫:`deny` / `warn`(只记日志)/ `off` |
50
+ | `guardOutsideWorkspace` | `deny` | v0.7 工作区外写入:`deny` / `warn` / `off` |
51
+ | `publishGuard` | `deny` | v0.7 `publish` 交付复制目标检查:`deny` / `warn` / `off` |
52
+ | `guardCodeTools` | `true` | v0.7 静态扫描 `python`/`node` 等代码执行工具里的写文件语句 |
53
+ | `guardUnknownTools` | `true` | v0.7 对"没按名字识别、但 schema 带路径参数"的写类工具做兜底检查 |
54
+ | `outsideAllow` | 内置 | v0.7 追加"无需审批即可写"的工作区外目录(绝对路径或 glob,`**` 跨层;纯目录条目不含子项,用 `/**` 覆盖子文件) |
55
+ | `publishBaseDir` | 无(= 会话 cwd) | v0.7 相对 `publish` 目标的解析基准(例如鸿蒙上实际交付根是 `Download/` 的父目录时填它) |
56
+ | `writeToolNames` | 内置 | v0.7 追加写工具名(`write`/`edit` 已内置) |
57
+ | `publishToolNames` | 内置 | v0.7 追加交付工具名(`publish`/`present` 已内置,`present` 只展示不复制) |
58
+ | `codeToolNames` | 内置 | v0.7 追加代码执行工具名(`python`/`node` 等已内置) |
59
+ | `attachmentCleanup` | `true` | v0.6 附件回收总开关(会话删除后回收其附件) |
60
+ | `attachmentCleanupDays` | 同 `orphanCleanupDays` | 会话删除后多少天回收其附件;`0` = 只扫地孤儿 |
61
+ | `attachmentSweepOrphans` | `true` | 是否同时清扫"无人引用且够旧"的历史孤儿附件 |
62
+ | `attachmentsDir` | `<DSH_HOME>/attachments` | 附件仓库根目录(一般不用改) |
63
+
64
+ ## 长期文件审批流程
65
+
66
+ 1. 模型判断某文件需要长期保存,且不在任务指定位置;
67
+ 2. 模型调用 `ask_user_question` 给用户选择题(标签只写 **A 不长期保存** / **B 工作区根目录保存**,细节放选项 description 小字;选 B 时模型自行起目录名、不再跟用户确认;其他位置由用户直接在输入框里写路径);
68
+ 3. 用户选长期 + 给路径 → 模型调 `longterm_approve({ path, reason, basis })` 登记(**工作区外目录也能登记**,例如鸿蒙的 `Download/<包名>/`;但不能登记磁盘根目录、用户主目录本身或层级过浅的目录);
69
+ 4. 之后 `write`/`edit`、shell 命令、`publish` 交付、python 等代码工具才能写该目录;用户否定 → 模型改用 `task_tmpdir` 写 `_tmp`。
70
+
71
+ `longterm_approve` 的登记是**按会话内存保存**:Host 重启或会话结束即清空,需要时重新审批(不会把"同意"永久写死)。
72
+
73
+ ## guard 行为边界(v0.7)
74
+
75
+ 判定顺序:`_tmp` 段(只在**工作区内或系统临时目录**里算临时区,v0.7 收紧)→ 已登记目录 → 白名单;工作区内走长期落点判定,工作区外走外部落点判定。
76
+
77
+ | 通道 | 判定方式 | 说明 |
78
+ |---|---|---|
79
+ | `write` / `edit` | 完整判定 | 工作区根新建、未登记子目录、工作区外未登记 → 拒绝 |
80
+ | `pwsh` / `bash` | 命令文本启发式 | 含创建动词(`New-Item`/`cp`/`mv`/`sed`/`tee`…)或重定向(`>`/`>>`)时,扫描命令里的绝对路径(Windows 盘符;HarmonyOS/POSIX `/` 开头,先剥掉 `scheme://` URL);重定向目标即使已存在也判(覆盖/追加属长期写入),其它已存在路径不拦(多为 copy/读取源) |
81
+ | `publish` | 复制目标判定 | 只检查 `target`/`destination`/`to`/`output`/`save_path` 等(`source` 是读侧,不拦);目标在工作区根、未登记子目录或工作区外 → 拒绝并提示先问用户 |
82
+ | `present` | 不拦 | 只声明已有文件为交付物,不复制、不落盘 |
83
+ | `python` / `node` 等 | 静态扫描 | 写信号(`open(...,'w')`、`write_text`、`shutil.copy`、`json.dump`、`Image.save`…)与同语句路径字面量(含 `sub/x.md` 这类相对路径)配对;动态拼路径拦不到(默认边界) |
84
+ | 其它工具 | schema 兜底 | 工具名/描述含写语义(write/save/export/render/copy/install…)且**顶层**参数值像路径时,**只拦两类高危目标**:工作区根新条目、工作区外未登记位置;工作区内子目录放行,避免误伤 |
85
+
86
+ **不误伤的设计**(v0.7 审查后加固):只读工具名(`read*`/`list*`/`get*`/`show*`/`view*`/`check*`/`status*`/`query*`/`search*`/`find*`/`glob`/`grep`/`count*`/`stat*`)一律跳过;本插件自己的 `task_tmpdir`/`longterm_approve`/`tmp_cleanup` 永远放行;schema 里声明为 `enum` 的参数、`@e3`/`#submit` 这类选择器、`this_session`/`new_once` 这类枚举值、`@scope/pkg` 包名和 URL 都不算路径;嵌套对象里的同名参数(`expect[].target`、workflow `args.files`)不算写目标。
87
+
88
+ 工作区外"天然允许"范围(无需审批,`outsideAllow` 可追加):`<DSH_HOME>`(`~/.dsh`,含插件/密钥/配置)、`~/.cache`、`~/.npm`、`~/.config`、`~/.local/share`、`~/.flova`、系统临时目录;POSIX 设备上另有 `/tmp`、`/var/tmp`、`/dev/shm`、`/run/user`、`/data/local/tmp`、`/storage/emulated/0/Android/data`。`/dev/null`、`NUL`、`$null` 之类伪路径直接放行。
89
+
90
+ 拦不到(fail-open,**不是安全边界**):变量/动态拼接的路径、脚本内部逻辑、外部程序、GUI 操作、绕过工具的 fs 调用;`warn` 模式只记日志不拦(`guardOutsideWorkspace`/`publishGuard`/`commandGuard` 的 `warn` 在四个通道统一生效)。
91
+
92
+ 其它:**工作区内**的规则只在会话工作目录 = 已注册工作区根时生效(会话 `cd` 到子目录时不把项目顶层文件当成"工作区根新建条目");**工作区外**的判定不受 cwd 限制,`cd` 到子目录也照拦(v0.7 修复);guard 是**全局**的——队友/子代理/定时任务会话同样受约束。
93
+
94
+ ## 回归测试(v0.7)
95
+
96
+ `test/guard.test.mjs`(38 条纯函数用例)覆盖反馈里给的绕过场景 + 独立审查发现的问题:
97
+
98
+ | # | 用例 | 期望 |
99
+ |---|---|---|
100
+ | 1 | `write` → `_tmp/<标题>/x.md` | 允许 |
101
+ | 2 | `write` → `<cwd>/x.md` | 拒绝 + A/B 提示 |
102
+ | 3 | `write` → `<cwd>/<未批准目录>/x.md` | 拒绝 |
103
+ | 4 | `write` → 工作区外(`Download/…`) | 拒绝 |
104
+ | 5 | `publish` → `Download/<包名>/x.md`(未登记) | 拒绝 |
105
+ | 6 | `present` → 工作区外已有文件 | 允许(只展示) |
106
+ | 7 | `python`:`open('/storage/…/工作区根/x.md','w')` | 拒绝 |
107
+ | 8 | `python`:`open('…/_tmp/…/x.md','w')` | 允许 |
108
+ | 9 | `bash -c 'echo hi > /storage/…/工作区根/x.md'`(POSIX) | 拒绝 |
109
+ | 10 | `cp a.md /storage/…/Download/x.md`(POSIX) | 拒绝 |
110
+ | 11 | 未识别工具 `output` → 工作区根 / 工作区外 | 拒绝 |
111
+ | 12 | 未识别工具 `output` → 未批准子目录 | 允许(降误伤) |
112
+ | 13 | `longterm_approve` 登记工作区外目录后再写 | 允许 |
113
+ | 14 | `longterm_approve` 登记磁盘根 / `_tmp` | 抛错 |
114
+ | 15 | `schedule_create` / `bsk_interact` 的 `target` 是枚举/选择器 | 不算写目标(允许) |
115
+ | 16 | `plugin_manager` 的 `target` 是包名/entry id | 不算写目标(允许) |
116
+ | 17 | `workflow` 的 `args.files`(嵌套) | 不算写目标(允许) |
117
+ | 18 | `read_image`(描述含"不要 install/create") | 只读,跳过 |
118
+ | 19 | 本插件自己的 `task_tmpdir`/`longterm_approve`/`tmp_cleanup` | 永远放行 |
119
+ | 20 | `echo hi >> …`、`2>> …` | 拒绝(`>>` 正确解析) |
120
+ | 21 | `> NUL`、`> $null`、`Write-Host "1 > 0"` | 放行(伪路径/引号内文本) |
121
+ | 22 | `curl https://…`、`git clone https://…` | 放行(URL 不是盘符路径) |
122
+ | 23 | 重定向到**已存在**的长期文件 | 仍拒绝(覆盖属长期写入) |
123
+ | 24 | 工作区外 `Desktop/_tmp/x.md` | 拒绝(`_tmp` 段只在工作区内算临时) |
124
+ | 25 | `python`:`open('sub/x.md','w')`(相对) | 拒绝 |
125
+ | 26 | `res.write('ok')` + `'/api/v1/items'` | 放行(不再误伤流写入) |
126
+ | 27 | `guardOutsideWorkspace: warn` 下 shell/code | 放行(只记日志) |
127
+ | 28 | 子目录 cwd(`skipInside`) | 工作区内放宽、工作区外仍拒绝 |
128
+
129
+ `test/integration.test.mjs`(14 条)用 stub Host 上下文真正跑注册进 `ctx.tools.guard` 的回调:`write`/`publish`/`present`/`python`/未知工具/`pwsh`、`longterm_approve` 登记后解锁、拒绝根目录与 `_tmp`、审查回归(审批工具不被自锁、标准工具不误伤、子目录 cwd 仍拦工作区外、`>>` 覆盖已存在文件、不存在文件路径登记其目录)。另可跑 `node test/live-matrix.mjs`(需要 `test/live-tools.json`)把当前 profile 的全部 live 工具灌进 guard 做误伤矩阵。
130
+
131
+ ## 自动清理规则(安全边界)
132
+
133
+ - 判定依据是「会话是否还存在」:先看活跃会话(`ctx.sessions`),再看已持久化会话(`sessionPersistence.list()`,取不到时回退扫描 `~/.dsh/sessions`)。
134
+ - 会话还在 → 目录保留;会话已删除 → 首次扫描标记孤儿(`orphanedAt`),满 `orphanCleanupDays` 天后下一次扫描删除。
135
+ - **只处理带本插件标记的目录**(`.dsh-task.json` 且含 sessionId);手工放进 `_tmp` 的其他目录不碰。
136
+ - 启动后约 60 秒跑第一次,之后按 `cleanupIntervalHours` 周期跑;`orphanCleanupDays: 0` 关闭清理。
137
+ - 删除是**整目录递归删除**,不备份;想先观察就把 `cleanupDryRun: true` 开着跑一轮。
138
+
139
+ ## 附件回收规则(v0.6)
140
+
141
+ Host 的附件仓库(`~/.dsh/attachments`)按内容 hash 存储、**自身没有任何回收机制**:删掉会话只删日志,图片会永远留在磁盘上。本插件把附件也接进同一条 7 天清理链路:
142
+
143
+ 1. 每轮清理时,通过 `sessionPersistence` 读取**每个已存会话**的事件,收集 `attachmentId`(`sha256:<hash>`),写进台账 `~/.dsh/data/session-tmpdir-attachments.json`;
144
+ 2. 台账按 `revision` 缓存——会话没变就不重读,稳态开销几乎为零;
145
+ 3. 会话消失 → 台账记 `orphanedAt`;满 `attachmentCleanupDays` 天后,删除**只被该会话引用**的 blob;
146
+ 4. 任何时候只要还有别的存活会话引用同一个 hash,就跳过(同一张图被多个会话用过的安全阀);
147
+ 5. `attachmentSweepOrphans` 开启时,额外清扫「无任何会话引用 + 文件本身够旧」的历史孤儿(覆盖本功能上线前就残留的那批);
148
+ 6. 最近 1 小时内写入的 blob 一律不碰;每次删除追加到 `~/.dsh/data/session-tmpdir-attachments-gc.jsonl`(hash / 大小 / 时间 / 原因),可审计。
149
+
150
+ `tmp_cleanup` 的返回里多一个 `attachments` 字段(删除数、释放 MB、待回收会话数、跳过数);`dryRun: true` 只统计不动手。
151
+
152
+ ## 开发
153
+
154
+ ```powershell
155
+ node --check index.js
156
+ node --test "test/*.test.mjs" # 38 条纯函数用例 + 14 条集成用例(stub Host 上下文)
157
+ node test/live-matrix.mjs # 可选:本机 live 工具误伤矩阵(需 test/live-tools.json)
158
+ ```
159
+
160
+ > POSIX 路径语义(`/storage/...`、大小写敏感)在 Windows 上只能验证解析器分支;真机行为请以 HarmonyOS Host 上的实际调用为准。
161
+
162
+ v0.5 变更(2026-11-07):新增长期落点审批(`longterm_approve` + guard v2),覆盖 pwsh/bash 命令;修复 v1 只拦"临时命名文件"导致根目录被会话自建文件夹的问题。
163
+
164
+ v0.5.2 变更(2026-11-12):长期落点选择题的选项顺序调整——A 改为"不长期保存,放 `_tmp/<会话标题>/`(临时)",C 改为"长期保存到本次任务指定的目录";B(新建归档目录)不变。落盘规则本身无变化。
165
+
166
+ v0.5.3 变更(2026-11-12):B/C 选项文案按实际使用重写,消除语义重叠——B 改为"工作区根目录保存"(长期保存到会话工作区根目录下,一般新建一个目录,如 `归档/<主题>/`);C 改为"存到指定位置(写明路径)",并明确选 C 但未给路径时模型必须先向用户确认,不得自行猜路径。规则与 guard 未改。
167
+
168
+ v0.5.4 变更(2026-11-12):按实际弹窗效果精简选项——删掉 C("存到指定位置"与输入框重复,用户改成在自由输入框写路径即可,模型收到非 A/B 答案时按指定位置处理,路径不清先追问);B 去掉括号说明,只留"工作区根目录保存"。规则与 guard 未改。
169
+
170
+ v0.5.5 变更(2026-11-12):选项标签统一写短(A 只写"不长期保存",路径等说明移到选项 `description` 小字),并要求不许把路径细节塞进标签;避免长标签把 GUI 里的描述小字顶到下一行造成排版不一致。规则与 guard 未改。
171
+
172
+ v0.5.6 变更(2026-11-12):选 B(工作区根目录保存)时不再要用户确认目录名——模型自行起一个清楚的目录名、`longterm_approve` 登记后直接写,跟 DSH 平时自己命名落盘一样;B 的小字改为"目录名自动起"。规则与 guard 未改。
173
+
174
+ v0.5.7 变更(2026-11-12):微调选项小字——A 的说明改为"随会话删除后 N 天清理"(N 取 `orphanCleanupDays`,默认 7,不再写死"随会话删除清理");B 的说明删掉"目录名自动起"字样,只留"长期保存到会话工作区根目录下"(自动起名行为本身不变)。规则与 guard 未改。
175
+
176
+ v0.6.0 变更(2026-11-13):新增**附件回收**——7 天清理会话目录时,一并回收该会话的附件 blob(台账 + 引用二次校验 + 扫描历史孤儿 + 审计日志),解决 `~/.dsh/attachments` 只增不减的问题。通过 `sessionPersistence` 读事件,不依赖日志格式、不自带 zstd 解码;`tmp_cleanup` 增加 `attachments` 参数与 `attachments` 输出字段。临时目录规则与 guard 未改。
177
+
178
+ v0.7.0 变更(2026-11-15):按 HarmonyOS DSHM 真机反馈(桌面文件「临时目录插件-长期文件规则绕过分析.md」)补齐写入通道覆盖——原来 guard 只认硬编码的 `write`/`edit`/`pwsh`/`bash` 工具名、只认 `file_path`/`path` 参数、只判工作区内部、shell 只认 Windows 盘符路径,导致 `publish` 交付复制、`python` 写盘等通道静默绕过。本次改动:
179
+
180
+ 1. **按能力识别工具**(`toolWritePlan`):写工具 / shell / 代码执行 / 交付(`publish`;`present` 只展示)/ 未知写类工具五类通道,未知工具从 schema 的路径参数识别,新增工具不再漏;
181
+ 2. **工作区外也判**:除 DSH 主目录、缓存、系统临时目录和已登记目录外,工作区外写入一律视为长期落点(`guardOutsideWorkspace`,可 `warn`/`off`);
182
+ 3. **`publish` 纳入判定**:复制目标(`target`/`destination`/`to`/`output`)未登记即拒绝,`source` 不拦;`present` 只展示不拦;
183
+ 4. **`python`/`node` 静态扫描**:写信号 + 同语句路径字面量配对判定,动态拼接路径声明为已知边界;
184
+ 5. **shell 平台适配**:HarmonyOS/POSIX 下解析 `/` 开头绝对路径与 `cp`/`mv`/`sed`/`tee` 等命令,`>` 重定向单独视为创建;
185
+ 6. **`longterm_approve` 支持工作区外目录**(鸿蒙 `Download/<包名>/` 等),拒绝磁盘根目录/主目录/层级过浅目录;
186
+ 7. 提示文本同步说明覆盖通道与 fail-open 边界;新增 38 条纯函数 + 14 条集成回归测试。
187
+
188
+ **独立审查后加固(同发 0.7.0)**:`longterm_approve`/`task_tmpdir`/`tmp_cleanup` 永远不被自己的 guard 判定(否则审批通道自锁);未知工具通道只看顶层参数,跳过 enum、选择器、包名和 URL(否则 `schedule_create`/`bsk_interact`/`plugin_manager` 必被误拒);只读工具名白名单(`read_image` 等);`>>` 重定向正确解析、`NUL`/`$null`/引号内文本不误判、Windows 路径扫描先剥 URL;工作区外 `_tmp` 段不再算临时区;工作区外判定不再随 cwd 关闭;重定向到已存在长期文件仍拒绝;`longterm_approve` 传入不存在的文件路径时登记其目录、并拒绝登记工作区根本身;`toolWritePlan` 判定改用实际参数值,POSIX 大小写/分隔符语义按平台区分。审查时用本机 59 个 live 工具矩阵验证:53 个工具零误伤,仅真实写类工具(`write`/`edit`/`pwsh`)和参数值确实是路径的兜底工具被判定。
189
+
190
+ v0.8.0 变更(2026-11-16):**写入即认领**(claim-on-write)。此前只有 `task_tmpdir` 会写 `.dsh-task.json`;模型若用普通 `write` 或 `pwsh New-Item` 在临时根下自起目录名,目录没有标记,按“手工目录不碰”原则永远不会被清理(本机实测积累 8 个、77 MB)。现在 guard 在**放行后**把写入目标里 `<临时根>/<目录>/…` 的直接子目录补写标记(含当前会话 id 与标题),覆盖 `write`/`edit`、`publish` 复制目标、`python`/`node` 代码里的静态路径、shell 命令的绝对路径与相对 `_tmp/…` 引用、未知写类工具的路径参数;目录不存在时先创建(写入本来就会创建,提前一步无副作用)。**放行/拒绝判定、清理宽限期与既有 marker 格式均未改变**;无标记目录一旦被认领,就按原规则在会话删除 7 天后清理。新增 `tmpClaimDirsForTargets` / `relativeTmpTargets` / `claimTmpDirsSync` 三个导出函数,便于单元测试。