DSH 0.2.1-rc.2 在 fnOS 生产环境的三个兼容性问题（两处自 0.2.0 起即存在）与修复建议

[sanluoluo]

环境

fnOS 实机，DSH 安装于 /vol1 挂载树。/vol1 为 fnOS 系统挂载点，出厂权限 d--------- root:root（btrfs trimacl 挂载）——这是系统管理面的默认状态，应用与用户不应修改其权限位。运行用户为 fnOS 应用标准用户（uid 980，AppUsers 组），对其子目录读写正常。

2026-10-20 从 0.2.0-rc.2 升级到 0.2.1-rc.2 后暴露以下问题；经与 npm 上游 0.2.0-rc.2 包比对，问题 2、3 相关代码自 0.2.0 起即存在，非 0.2.1 引入，但升级/重部署使其必然暴露。

问题 1（0.2.1 引入）：提示词变量 {{cwd}} 移除，升级无检查

0.2.0 的 agent-loop 注册 ctx.systemPrompt.variable("cwd", …)，0.2.1 不再注册。旧 profile（由官方模板派生）的 persona 后缀含 Your working directory is {{cwd}}.，升级后提示词组装抛 unknown prompt variable "{{cwd}}"，请求不发送到模型；用户侧表现为发消息没有反应、未见明确错误提示。

dsh-system-prompt 的 README 有迁移指引，但升级过程不扫描用户 profile、无告警。

建议：升级时扫描用户 profile/preset 对已移除变量的引用并告警，或提供自动迁移。

问题 2（0.2.0 起存在，本次暴露）：会话历史图片引用悬空时无降级、无自愈

0.2.0 时代会话（2026-10-11）中的图片引用在 attachments/v1/objects/ 下无对应对象文件（对象在升级前即不存在，与问题 3 的落盘失败相关）。悬空引用使旧会话重放失败：发给视觉模型时抛 ATTACHMENT_NOT_FOUND，整轮请求失败；错误信息不指示「对象缺失、可重新上传」。

建议：对悬空附件引用降级为占位文本（可复用 offloadedImageText 机制），并使错误可读、可自愈（提示重新上传）。

问题 3（0.2.0 起存在，本次暴露）：附件落盘的持久性保证 fsync 到文件系统根，在受限挂载点上必然失败

dsh-attachment-local 的 ensureDurableHome（lib/index.js:402-407）调用 ensureDurableDirectory(home, parse(home).root)，把目录项持久性保证一路做到文件系统根（逐级 syncDirectory，行 352-360 以 O_RDONLY 打开目录后 fsync）。运行用户对 /vol1 连只读打开都被拒绝（EACCES），因此每次图片落盘必然失败。

实测复现（以 fnOS 应用标准用户执行）：

python3 -c "import os; os.open('/vol1', os.O_RDONLY|os.O_DIRECTORY)"
# PermissionError: [Errno 13] Permission denied

（对照：/vol1/@apphome 及更深目录、/var/lib 的 open + fsync 均正常，故障点隔离在 /vol1 一级。）

另：该失败被包装为 ATTACHMENT_WRITE_FAILED 后上报，message 不含 errno、cause 链被吞；客户端侧只见笼统的 prompt rejected 文案，排障时无法定位真实原因。

建议：

1. 祖先目录 fsync 失败按 errno（EACCES/EPERM）降级为警告，对象文件本身的 fsync 保持强制（避免把写侧报错转化为读侧悬空引用）；
2. 持久性边界止于 DSH_HOME 而非文件系统根；
3. errno 透传到错误消息与 RemoteError reason。

用户侧临时缓解：将 DSH_HOME 指向权限位正常生效的持久路径（如 /var/lib 下；/tmp 不可用，开机清空）。

其他

其余链路（对话、工具、搜索）在规避上述问题后实测正常。相关背景可见此前 Discussion #11（升级链路反馈）。

[sanluoluo]

感谢 v5.9.0 的 attachment-local 补丁——把持久性边界改为 TRIM_PKGVAR 后，/vol1 挂载点上祖先目录 fsync 被拒（EACCES）导致附件写入必然失败的问题已实测根治。这正是本贴问题 3 建议 ② 的方向，确认有效。

不过这次补丁带来一个新的升级阻断问题，建议优先处理：

附件根变更未迁移历史对象 ⇒ 升级后旧会话整轮失败

• 补丁把附件根从 $DSH_HOME 改为 TRIM_PKGVAR || config.dshHome。
• 本机生产实例从 v5.8.x 升级到 v5.9.0-0.2.1-rc.2.12 后，生效根切换，历史图片对象留在旧根 ⇒ 3 个会话（历史中带图片的）发送任何消息（含纯文本）都失败，客户端仅显示 Attachment object is missing.（UNKNOWN），无占位降级、也不提示如何恢复。
• 复现条件：任何历史上写过附件、且对象落在旧根下的实例，升级到 v5.9.0 必中。从未写过附件或清理过附件库的实例不受影响——所以这不是个别环境问题，是升级路径的普遍风险。

建议（按侵入性从小到大）

1. 升级回调里做一次对象库合并：旧根 attachments/v1/objects/*/* 中缺失的对象 cp -p 到新根（内容寻址天然幂等，已存在的不必覆盖），旧库保留作回滚点。本机实测合并 19 个对象 / 3 个会话即恢复。
2. 启动时自检：解析出生效根后抽查若干会话引用的 attachmentId 是否可达；下降就在日志与 Web 上给出明确告警，而不是等用户发消息时才报 Attachment object is missing.。
3. 长期：附件读取增加「多根回退」（先当前根、后历史根），使根迁移对用户透明。

附：我们的临时处置（供参考）

写了一个三断言门禁：① 解析运行进程实际生效的附件根（不读配置猜）② 全会话引用可达 ③ 对象名 = 内容 sha256。升级前后各跑一次并对比根路径与对象数，漂移即 FAIL。目前 209 对象 / 81 引用全可达。如需要，我可以把脚本整理成 PR 贡献到本仓库 scripts/ 下。

补充一条给后来者的提醒：配置文件里写 attachment-local.dshHome 不会生效（被 TRIM_PKGVAR 短路），我们此前按配置判断生效根，踩过一次误判。

[tnnevol]

@sanluoluo 感谢这份排查，问题 3 的根治确认让我们松了半口气——TRIM_PKGVAR 作为持久性边界是正确方向，祖先目录 fsync 遇 EACCES 降级为警告、而对象文件本身的 fsync 保持强制，这个取舍也正是你建议里的要点。

你补充的升级阻断问题，我们已关注，暂作待定规划处理，先把我们对现状的判断和后续安排讲清楚，避免你按「已修复」理解：

• 对象库合并（建议①）方向认同。内容寻址天然幂等，「缺失才补、旧库留作回滚点」的思路与我们对升级链路的既有原则一致（升级只做可回滚的增量，不做破坏性迁移）。但落点需要先厘清：新旧根的判定、合并的触发条件（是否每次升级都做、还是只在检测到根切换时做）、以及失败时的降级行为，这几点需要与你实测的门禁对齐后再定，所以暂不排期。
• 启动自检（建议②）与多根回退（建议③） 同属长期项，暂列待定。二者都会引入新的常态开销或长期兼容负担，需要评估后再决定是否长期保留。
• TRIM_PKGVAR 短路 attachment-local.dshHome 这条提醒很关键，我们会一并核对补丁实现里的生效根解析顺序，确认这是有意的优先级设计还是需要调整。

问题 1（{{cwd}} 移除后旧 profile 无声失败）与问题 2（悬空附件引用无降级）同样已记录在案，与上面的升级阻断一并纳入待定规划范围。问题 2 与附件根迁移直接相关，若后续推进合并，悬空引用的可读错误与占位降级会一并考虑。

这批反馈目前均为「已关注、待定规划」，不是已排期。我们会在需求与计划文档正式登记后再回来同步；在此之前，若你那边有新的实测数据（尤其是不同挂载点、不同历史附件规模的样本），欢迎继续贴上来。

另感谢你提出把三断言门禁脚本整理成 PR 的意向——我们会在明确附件根的判定口径之后再评估是否合入，避免门禁规则先于实现定型。

[sanluoluo]

@tnnevol 收到，「待定规划、不是已排期」我记下了，后续按这个前提走——不当成排期，也不据此催进度。你在 10-22 说的三点（新旧根判定、触发条件、失败降级）我按你邀请补两组实测，另外主动收窄一条建议的范围。

一、先在你们这个补丁上做的验证：boundary v2 在我们实例上的效果

你们在 dsh-attachment-local 里落的补丁（lib/index.js:402/404 的 attachmentDurabilityBoundary → resolve(process.env.TRIM_PKGVAR)，:1004-1005 的 TRIM_PKGVAR || config.dshHome）生效后，我逐级测了目录句柄——以应用运行用户（本机 uid 980，非 root、无提权）直接执行 open(O_RDONLY|O_DIRECTORY) + fsync：

路径	mode	X_OK	R_OK	open	fsync
/vol1（btrfs, trimacl）	0o0	True	False	EACCES(13)	无句柄
/vol2（ext4, trimacl, prjquota）	0o0	True	False	EACCES(13)	无句柄
/vol1/@appdata	0o755	True	True	OK	OK
/vol1/@appdata/fn-deepseek-harness ← 当前边界	0o700	True	True	OK	OK
/vol1/@appdata/fn-deepseek-harness/attachments/v1	0o700	True	True	OK	OK
/var/lib（非 trimacl，对照）	0o755	True	True	OK	OK

两点补充，可能对你们写文档有用：

1. trimacl 对卷根是「给 search(x)、不给 read(r)」——所以 mode 0o0 却能穿到子目录，但 open(O_DIRECTORY) 要 read 就必然 EACCES。这解释了为什么 /vol1 与 /vol2（两个不同文件系统）行为完全一致：是 trimacl 层的特性，不是 btrfs 的特性。
2. 在原版实现下，逐级 open 在卷根这一级就取不到句柄，fsync 根本走不到。边界止于 TRIM_PKGVAR 后，逐级链最长到 /vol1/@appdata/fn-deepseek-harness，全程有句柄——机制上确实越不过这一层，不是绕开。

结论：v5.9.0 那次「附件根漂到卷根、祖先 fsync 必败」的直接原因，在这个补丁下不再出现。我们这边 10-21 到 10-25 连续 4 天没有复发。

二、连续运行数据（附样本局限）

同一实例，升级后连续使用：

采集时刻	objects	file-objects	唯一引用	会话文件(.zstd)	sha 校验（objects+file-objects）
2026-10-21 16:26	209	3	81	218	212/212 一致
2026-10-25 12:08	225	3	97	301	228/228 一致，引用零悬空

• 两端增量都是 16（对象 209→225，唯一引用 81→97），加上悬空引用 0，可以直接排除孤儿对象与悬空引用。
• 最后一次对象写入是 10-24 08:28；此后 28 小时没有新增对象。我逐个核了这期间被引用的 30 个唯一 attachmentId：全部命中已有对象、零悬空，且它们对应对象的写入时间都落在 10-20 21:26 ~ 10-24 08:28 之间——也就是说这 28 小时没有新内容写入（内容寻址下去重命中不会新增对象），不是写入失败。

样本局限我主动说清楚：这是一条纵向单实例、4 天、225 对象的记录，只能说明「这条路径上没再出问题」，够不上「长期有效」。你邀请的不同挂载点样本见上表（btrfs/ext4 各一，都开了 trimacl），不同历史规模我只有这一档，有第二台机器我再补。

复算命令：

R=/vol1/@appdata/fn-deepseek-harness/attachments/v1
find "$R/objects" -type f | wc -l                                            # 225
find "$R/file-objects" -type f | wc -l                                       # 3
find sessions -mindepth 3 -maxdepth 3 -name 'session.v4.jsonl.zstd' | wc -l  # 301
# 悬空核查：抽全部会话里的 attachmentId，逐个查 $R/objects/<前2位>/<id> 是否存在
zstd -dc <会话文件> | grep -oE '"attachmentId"[[:space:]]*:[[:space:]]*"sha256:[0-9a-f]{64}"'

三、收窄建议③，并回答你能用的两点

看到 #23 之后我核了一遍自己的三条建议落在哪一层：

• 建议①（升级回调补缺失对象）②（启动自检）：都在应用层，改的是安装/升级流程，不动上游。补充一句：我那条合并逻辑其实只解决「旧根缺失对象 cp -p 到新根」，边界完全依赖「如何确定旧根」，也就是你指出的那个未定点。所以在口径定下来之前它算不上可实施方案——你说先不排期，我同意。
• 建议③（读附件多根回退）：要改 dsh-attachment-local 的读取逻辑。我按 【公告】不接受以「修改 DSH 官方代码」为前提的建议；如需改动请 fork 官方仓库自行魔改 #23 理解为不该由我在这个仓库提，所以撤回、不附 PR；这条线我先放下，不在本仓库提。

关于你提的三点，我们这边实测能给两条（第三条给不出，如实说）：

1. 新旧根判定：TRIM_PKGVAR 优先级高于 config.dshHome。我们曾在配置里写 attachment-local.dshHome: /var/lib/fn-deepseek-harness 并重启，读回来的 attachmentHome 仍是 $TRIM_PKGVAR 下的路径——而那个目录当时已被删掉，若真被采用会直接报错，所以可以确定它没有被采用。判定只能看运行进程的 environ，不能读配置文件。
2. 失败降级：旧会话遇到悬空引用时 ATTACHMENT_NOT_FOUND 会让整轮失败，客户端只显示 Attachment object is missing.（UNKNOWN），没有占位降级、也不提示重新上传；纯文本消息同样失败，因为重放历史时就卡住了。这条只是把现象说清，没有要本仓库改的意思。
3. 触发条件：只想到「升级前后对象数量对比」，但升级前未留基线时无从判断。我们自己那边只能补一道快照/对比，只对自己生效。这条我没法给出通用解。

四、PR 意向

按你的排序：等附件根判定口径明确后再评估合入，这期间我不提。门禁脚本本身已经在我们仓库里跑着，如果需要现状数据随时说。

[dsh-agent-bot]

感谢你这一轮把机制层面钉死，尤其两条补充对我们是结论级的：

• trimacl 对卷根是「给 search(x)、不给 read(r)」：mode 0o0 仍能穿透到子目录，但 open(O_DIRECTORY) 必然 EACCES。这解释了 btrfs 与 ext4 表现完全一致——是 trimacl 层的特性，不是文件系统的特性。
• 边界止于 TRIM_PKGVAR 后逐级链最长到应用自己的 @appdata 目录，全程有句柄：印证了补丁是「把持久化边界收在不越权处」，不是绕开权限。

一、附件存储位置定稿：TRIM_PKGVAR

据此我们把附件存储位置定为 TRIM_PKGVAR（应用自有可写目录），不再考虑放到卷内其它位置。你的 4 天 / 225 对象记录加上上面两条机制事实，足以支撑这个口径；样本局限（单实例纵向、225 对象）我们按你写的理解，不当作长期有效性证据。

另外我们复核了补丁在新基线上的可用性：DSH 0.2.1-rc.3 的产物上，三个锚点（node:path 导入、ensureDurableDirectory(home, parse(home).root)、构造器里的 dshHome／cacheRoot）仍各命中一次；补丁带版本校验与「锚点缺失即抛错」的保护，所以基线升级不会静默失效——要么正常应用，要么安装明确失败，不会装出一个「看似有补丁」的隐患版本。

二、你的三条建议：现在的口径

建议	状态	说明
① 升级回调补缺失对象	不排期	与你的判断一致：边界完全取决于「如何确定旧根」，该未定点未解决前不算可实施方案
② 启动自检	不排期	同属长期项
③ 读附件多根回退	不在本仓库做	按 #23 口径，改上游读取逻辑不属于本仓库范围；你已撤回、不附 PR，这条线就此放下

「新旧根判定只能看运行进程 environ、写配置文件不生效」这条我们接受，作为将来若重启 ① 的前提输入。

三、新进展：问题 1（{{cwd}}）已实现，随下一版本发布

你报的第一个问题——0.2.1 移除内置提示词变量后，旧 profile 发消息静默失败——已在主分支实现：

• 做法：升级回调扫描 profile 的 cordis.patch.yml 与 package.json，移除含该变量的整句（不是只删变量名，否则会留下 Your working directory is . 这类残句），改写前写带时间戳备份、原子写回。
• 约束：未命中的 profile 零改动（不写文件、不写备份）；迁移异常只记日志、不阻塞安装；重复执行幂等（不产生新备份）。
• 验证（已验证）：包级 15 条用例——命中改写、多行文本逐字保真、YAML 引号结构不被破坏、package.json 只改目标字段、备份内容等于原文、幂等、损坏文件只告警跳过；实测 147 条包级用例全绿。真实 fnOS NAS 上装过两版，每次安装的两次回调都执行了迁移步骤并留日志，profile 两个候选文件的内容校验和升级前后一致、无备份文件产生。
• 未验证项（如实说明）：真机上没有构造「含该变量的 profile」去复现原症状——构造它需要改写测试设备的用户数据，超出我们允许的验证手段。移除逻辑本身由上面的包级用例覆盖，真机侧验证的是「迁移确实执行且不破坏用户 profile」。

实现细节与验收口径见 docs/requirements/FNOS-031-cwd-prompt-variable-migration.md、docs/plans/PLAN-FNOS-031-cwd-prompt-variable-migration.md、docs/tests/FNOS-031-cwd-prompt-variable-migration.md。

四、问题 2（悬空引用无降级）

仍是上游读侧行为：ATTACHMENT_NOT_FOUND 让整轮失败、客户端只显示 Attachment object is missing.；你补的「纯文本消息同样失败（重放历史时就卡住）」也记下了。按 #23 口径本仓库不改上游读取逻辑，应用层两条缓解（①②）暂不排期——所以问题 2 目前没有本仓库侧的改动计划，不是已修复。

顺带说明：问题 3 的直接原因（附件根漂到卷根、祖先 fsync 必败）在当前发布线上不再出现，这一点与你的复测一致。