@aalis/plugin-storage-local 0.12.2 → 0.14.0

package/dist/index.js

@@ -1,34 +1,38 @@
 import { randomBytes } from 'node:crypto';
 import { createReadStream, watch as fsWatch, statSync } from 'node:fs';
 import { chmod, lstat, mkdir, open, readdir, readFile, realpath, rename, rm, stat, unlink, writeFile, } from 'node:fs/promises';
-import { basename, dirname, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { checkpoint } from '@aalis/api-checkpoint';
 import { doctor } from '@aalis/api-doctor';
+import { hostPaths } from '@aalis/api-host-paths';
 import { storage, } from '@aalis/api-storage';
 import { config, definePlugin, lifecycle, logger, optional, provide, services, } from '@aalis/core';
 import { defineConfig, parseConfig } from '@aalis/schema-config';
+import { TextError, textOf } from '@aalis/schema-i18n';
+import { t } from './texts.js';
 const PLUGIN_NAME = '@aalis/plugin-storage-local';
 /**
- * 这个插件不是沙箱。它做三件事：
+ * 这个插件不是沙箱。它做四件事：
  *
- * 1. 给若干本机目录起稳定的名字（roots 数组里声明，包括默认 workspace/data/tmp/
- *    pluginData/logs，以及用户加的任何根），让上层用 URI 表示文件，避免到处写
- *    宿主机绝对路径。
+ * 1. 给若干本机目录起稳定的名字：插件自己的数据在按家目录布局派生的内置根里，文件工具用的根在 roots 数组里声明
+ *    （缺省只有 workspace），让上层用 URI 表示文件，避免到处写宿主机绝对路径。
  * 2. 在每条 API 内对 `..` 穿越做规范化与校验，防止"workspace:/../../etc/passwd"
  *    这类逻辑越界 bug。
  * 3. 把所有读/写/删过一道 logger，作为统一审计点。
+ * 4. 宿主控制文件的执行点兜底：不管经哪个根进来，密钥文件读写都拒，主配置拒写（见 {@link HostFileGuard}）。
  *
  * 它无法阻止 run_python / shell 等子进程在拿到 cwd 之后访问 OS 用户可访问的任何文件——
  * 这种隔离只能靠 OS 用户权限或容器层。请按这个边界来理解和配置。
  *
- * 关于 browsable：仅是给"文件浏览器类 UI"的 hint。当前 plugin-webui-server 的文件页
- * 实际只显示其 fileRoot 配置指向的那一个根（默认 workspace），其它根的 browsable=true
- * 不会让它们出现在文件页里——那些根仅供 agent/工具按 URI 寻址使用。
+ * 关于 browsable：仅是给"文件浏览器类 UI"的 hint。WebUI 没有文件浏览页，不读它；
+ * 这些根供 agent 与工具按 URI 寻址。
  *
- * 当 agent 需要访问"内置 5 个根之外"的目录时：
+ * 当 agent 需要访问默认根之外的目录时：
  *   - 推荐：在 roots 里加一条具名根（如 share / project_x），路径限定到目标目录
  *   - 一刀切：在 roots 里加 { name: host, path: '/' }，agent 即可用 host:/绝对路径 访问
  *     宿主机任何位置（高危，启动时会有 WARN 日志）
  */
+/** 用户 roots 缺省时注册的根：只有文件工具的工作根。插件自己的数据都在下面的内部路由根里 */
 const DEFAULT_ROOTS = [
     {
         name: 'workspace',
@@ -40,94 +44,85 @@ const DEFAULT_ROOTS = [
         writable: true,
         deletable: true,
     },
-    {
-        name: 'data',
-        path: 'data',
-        label: 'Data',
-        kind: 'data',
-        browsable: false,
-        readable: true,
-        writable: true,
-        // 可删：/clear 的附件清理（data/images 等）依赖它，关掉会让开箱用户连手动清理都失败。
-        // deletable 是能力位不是权限闸——agent 侧删除面由各工具自身档位把关
-        // （file_delete=restricted+confirm+allowedRoots、skill_delete=sensitive 等，档位各异）。
-        deletable: true,
-    },
-    {
-        name: 'tmp',
-        path: 'workspace/.tmp',
-        label: '临时文件',
-        kind: 'tmp',
-        browsable: false,
-        readable: true,
-        writable: true,
-        deletable: true,
-    },
-    {
-        name: 'pluginData',
-        path: 'data/plugins',
-        label: '插件数据',
-        kind: 'pluginData',
-        browsable: false,
-        readable: true,
-        writable: true,
-        deletable: true,
-    },
-    {
-        name: 'logs',
-        path: 'data',
-        label: '日志',
-        kind: 'logs',
-        browsable: false,
-        readable: true,
-        writable: false,
-        deletable: false,
-    },
     // 高危直通：取消注释或改 enabled 字段无意义——存在即注册。如需 host:/ 直通根，把下行加进 roots：
     // { name: 'host', path: '/', label: '宿主机根', kind: 'host', browsable: false, readable: true, writable: false, deletable: false },
 ];
+/** 插件读写、可删的内部根的权限位 */
+const PRIVATE = { browsable: false, readable: true, writable: true, deletable: true };
+/**
+ * 插件内置的内部路由根：按家目录布局（host-paths）派生，不受用户 roots 影响，不在文件页出现。在用户根之后注册；
+ * 用户 roots 里与内部根同名的项被跳过并告警（内部根优先）。见计划书「插件数据约定」。
+ * - data：插件状态（数据库、向量库、checkpoint、会话与附件……）。附件句柄里的根名 data 保留，映射到 state/，
+ *   不改写历史。可删：/clear 的附件清理依赖它；删除面由各工具自身档位把关。
+ * - pluginData：各插件的私有数据目录 state/plugins。
+ * - tmp、cache：临时区与缓存；logs：runtime 写文件日志的目录，WebUI 与 CLI 的日志页从这里读，只读。
+ * - personas、skills、workflows：self 下按用途分开的三个根，一个根里的路径拼接失误到不了另一个根。
+ * - paper：白纸枢纽存放远端任务成品；public：发布服务存放审核通过的作品，作品站从这里读出来部署。
+ * kind 供 checkpoint 等按类判断：data、pluginData、tmp、cache、logs、paper、public、self 都不记账
+ * （self 等访问层限定写入者后再记，见 plugin-checkpoint）。
+ */
+function internalRoots(paths) {
+    return [
+        { name: 'data', path: paths.state, label: '状态', kind: 'data', ...PRIVATE },
+        { name: 'pluginData', path: join(paths.state, 'plugins'), label: '插件数据', kind: 'pluginData', ...PRIVATE },
+        { name: 'tmp', path: paths.tmp, label: '临时文件', kind: 'tmp', ...PRIVATE },
+        { name: 'cache', path: paths.cache, label: '缓存', kind: 'cache', ...PRIVATE },
+        {
+            name: 'logs',
+            path: paths.logs,
+            label: '日志',
+            kind: 'logs',
+            browsable: false,
+            readable: true,
+            writable: false,
+            deletable: false,
+        },
+        { name: 'personas', path: paths.self.personas, label: '人设卡', kind: 'self', ...PRIVATE },
+        { name: 'skills', path: paths.self.skills, label: '技能', kind: 'self', ...PRIVATE },
+        { name: 'workflows', path: paths.self.workflows, label: '编排定义', kind: 'self', ...PRIVATE },
+        { name: 'paper', path: paths.stage.paper, label: '白纸', kind: 'paper', ...PRIVATE },
+        { name: 'public', path: paths.stage.public, label: '公开作品', kind: 'public', ...PRIVATE },
+    ];
+}
 const configSchema = defineConfig({
     roots: {
         type: 'array',
-        label: '存储根目录',
-        description: '所有可用根都在这里声明（包括 workspace/data/tmp 等内置根）。' +
-            '直接编辑这个数组：删除不要的、修改 path、加自定义根、加 host:/ 直通根。' +
-            'browsable 是给 WebUI 等浏览器类组件的 hint（注意：当前 WebUI 文件页固定显示 fileRoot 配置指向的那一个根，' +
-            '其它根仅作为工具/agent 寻址使用）。',
+        label: t('rootsLabel'),
+        description: t('rootsDescription'),
         default: DEFAULT_ROOTS,
         onInvalid: 'error',
         items: {
             name: {
                 type: 'string',
-                label: '根名 (URI scheme)',
+                label: t('nameLabel'),
                 required: true,
                 onInvalid: 'error',
-                description: '只允许字母/数字/下划线/连字符，且需以字母开头；如 workspace、share',
+                description: t('nameDescription'),
             },
             path: {
                 type: 'string',
-                label: '本机路径',
+                label: t('pathLabel'),
                 required: true,
                 onInvalid: 'error',
-                description: '可绝对，亦可相对项目根；不存在时自动创建。指向 / 即注册宿主机直通根（高危）。',
+                description: t('pathDescription'),
             },
-            label: { type: 'string', label: '展示名称', default: '' },
+            label: { type: 'string', label: t('labelLabel'), default: '' },
             kind: {
                 type: 'string',
-                label: '类型标签',
+                label: t('kindLabel'),
                 default: 'custom',
-                description: '语义提示：workspace / data / tmp / pluginData / logs / custom / external / shared / host',
+                description: t('kindDescription'),
             },
             browsable: {
                 type: 'boolean',
-                label: 'WebUI 浏览器可见 (hint)',
+                label: t('browsableLabel'),
                 default: false,
                 onInvalid: 'error',
-                description: 'hint：当前实现下仅当 webui-server.fileRoot 指向本根时此开关才生效',
+                description: t('browsableDescription'),
             },
-            readable: { type: 'boolean', label: '允许读', default: true, onInvalid: 'error' },
-            writable: { type: 'boolean', label: '允许写', default: false, onInvalid: 'error' },
-            deletable: { type: 'boolean', label: '允许删除', default: false, onInvalid: 'error' },
+            readable: { type: 'boolean', label: t('readableLabel'), default: true, onInvalid: 'error' },
+            writable: { type: 'boolean', label: t('writableLabel'), default: false, onInvalid: 'error' },
+            deletable: { type: 'boolean', label: t('deletableLabel'), default: false, onInvalid: 'error' },
         },
     },
 });
@@ -145,29 +140,110 @@ function toUri(root, relPath) {
 function parseUri(uri) {
     const idx = uri.indexOf(':/');
     if (idx <= 0)
-        throw new Error(`存储 URI 不合法: ${uri}`);
+        throw new TextError(t('badUri', { uri }));
     const root = uri.slice(0, idx);
     const relPath = normalizeRelPath(uri.slice(idx + 2));
     return { root, relPath };
 }
 /**
- * Per-root 存储服务：每个 root 一个实例 + 一个 ServiceContainer entry。
- *
- * 与 service-granularity 整体方向对齐：每个 root 的真实权限由 StorageRootInfo 的
- * readable/writable/deletable 位携带；storage-api 网关按位路由，按 URI 调度交给
- * `createStorageGateway(storage)` helper。
- *
- * 自包含设计：URI→root 分发不依赖外部 router 插件，单文件即可理解整条数据流。
+ * 宿主控制文件的执行点兜底：密钥文件读写都拒，主配置拒写，只许 runtime 自己读写它们（见计划书「执行点兜底」）。
+ * 不管目标经哪个根进来都查：
+ * - 文件本身：按 (dev, ino) 比，硬链接与符号链接都挡得住；文件还不存在时按真实路径比（不分大小写，
+ *   macOS 与 Windows 的卷默认不分），落在控制文件路径之下的也拒（不许把它建成目录）；
+ *   ino 按 bigint 取：Windows 的 64 位文件 ID 转成 number 会丢低位，不同文件可能撞号；
+ * - 整个子树：删除、移动、改名一个目录，或以写、删的方式把目录的本地路径交给别的工具时，按目录身份 (dev, ino)
+ *   看它是不是控制文件的祖先目录。按身份而不按路径比：macOS 的 firmlink 与 bind mount 给同一个目录不同的路径。
+ * 控制文件每次现查：主配置保存时整份换掉，inode 会变。
+ */
+class HostFileGuard {
+    files;
+    constructor(files) {
+        this.files = files;
+    }
+    /**
+     * `read`：读内容（只挡密钥文件）；`write`：写、删、移动（两个都挡）；`subtree`：目标是目录时连子树一起查。
+     */
+    async check(abs, mode, subtree = false) {
+        const guarded = mode === 'read' ? [this.files.secrets] : [this.files.secrets, this.files.config];
+        const target = await identify(abs);
+        for (const file of guarded) {
+            const control = await identify(file);
+            const sameFile = target.stat !== undefined &&
+                control.stat !== undefined &&
+                target.stat.dev === control.stat.dev &&
+                target.stat.ino === control.stat.ino;
+            // 含路径相同（isInside 对同一路径判内）
+            const underControl = isInside(foldCase(control.real), foldCase(target.real));
+            const containsControl = subtree && target.stat?.isDirectory() === true && (await ancestorIds(control.real)).has(idOf(target.stat));
+            if (sameFile || underControl) {
+                // 读时只查密钥文件：主配置只在写时拦
+                if (file !== this.files.secrets)
+                    throw new TextError(t('writeConfig'));
+                throw new TextError(t(mode === 'read' ? 'readSecrets' : 'writeSecrets'));
+            }
+            if (containsControl)
+                throw new TextError(t('containsControl'));
+        }
+    }
+}
+const foldCase = (p) => p.toLowerCase();
+const idOf = (s) => `${s.dev}:${s.ino}`;
+/** 路径的真实路径与 stat；不存在时从最近的已存在祖先算真实路径、不给 stat */
+async function identify(abs) {
+    try {
+        return { real: await realpath(abs), stat: await stat(abs, { bigint: true }) };
+    }
+    catch {
+        /* 不存在或读不了：往上找 */
+    }
+    const missing = [];
+    let dir = abs;
+    for (;;) {
+        missing.unshift(basename(dir));
+        const parent = dirname(dir);
+        if (parent === dir)
+            return { real: abs };
+        dir = parent;
+        try {
+            return { real: join(await realpath(dir), ...missing) };
+        }
+        catch {
+            /* 继续往上 */
+        }
+    }
+}
+/** 控制文件的各级祖先目录的身份（找得到的那些） */
+async function ancestorIds(real) {
+    const ids = new Set();
+    let dir = dirname(real);
+    for (;;) {
+        try {
+            ids.add(idOf(await stat(dir, { bigint: true })));
+        }
+        catch {
+            /* 不存在的跳过 */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return ids;
+        dir = parent;
+    }
+}
+/**
+ * 一个根的存储操作：真实权限由 StorageRootInfo 的 readable/writable/deletable 位携带，每个操作先核对。
+ * 不单独登记：{@link LocalStorage} 按 URI 的根名分给它。
  */
 class ScopedStorageService {
     root;
+    guard;
     logger;
     services;
     onDispose;
-    constructor(root, logger, services, 
+    constructor(root, guard, logger, services, 
     /** 本次激活的清理登记：watch 建的 fs 监听器归提供者所有，提供者关闭时一并关闭 */
     onDispose) {
         this.root = root;
+        this.guard = guard;
         this.logger = logger;
         this.services = services;
         this.onDispose = onDispose;
@@ -199,13 +275,12 @@ class ScopedStorageService {
         this.recentLogAt.set(key, now);
         this.logger.debug(msg);
     }
-    /** 懒解析 checkpoint 服务；仅当回合活跃时调用 beforeMutate */
+    /** 懒解析 checkpoint 服务，在场就调 beforeMutate：写入是否处在回合里、要不要快照由它判断 */
     async snapshot(uri, op, abs, targetUri) {
-        // 按名动态查：checkpoint 的描述符在实现包里，而 checkpoint 自己要用存储——
-        // 声明它会让两个实现包互指。动态查到的不算声明依赖，与这里需要的语义一致
-        // （快照能力有就用、没有就直接落盘，不设激活闸）。
-        const cp = this.services.get('checkpoint');
-        if (!cp?.isActive())
+        // 动态查而不写进 uses：checkpoint 自己要用存储，声明它会让两者互为依赖。动态查到的不算声明依赖，
+        // 与这里需要的语义一致（快照能力有就用、没有就直接落盘，不设激活闸）。
+        const cp = this.services.get(checkpoint);
+        if (!cp)
             return;
         await cp.beforeMutate(uri, op, async () => {
             // 只有「目录」与「文件不存在」才返回 null —— checkpoint 据此判定为本回合新建。
@@ -234,7 +309,7 @@ class ScopedStorageService {
         const abs = await this.resolveExisting(relPath);
         const s = await stat(abs);
         if (!s.isDirectory())
-            throw new Error('不是目录');
+            throw new TextError(t('notDirectory'));
         const dispUri = toUri(this.root.name, relPath);
         this.debugSampled(`list:${dispUri}`, `storage.list ${dispUri}`);
         const entries = await readdir(abs);
@@ -281,9 +356,10 @@ class ScopedStorageService {
         const relPath = this.parseSelfUri(uri);
         this.requirePermission('readable');
         const abs = await this.resolveExisting(relPath);
+        await this.guard.check(abs, 'read');
         const s = await stat(abs);
         if (s.isDirectory())
-            throw new Error('不能读取目录');
+            throw new TextError(t('readDirectory'));
         const dispUri = toUri(this.root.name, relPath);
         this.debugSampled(`read:${dispUri}`, `storage.read ${dispUri} size=${s.size}`);
         return encoding ? readFile(abs, encoding) : readFile(abs);
@@ -293,9 +369,10 @@ class ScopedStorageService {
         const relPath = this.parseSelfUri(uri);
         this.requirePermission('readable');
         const abs = await this.resolveExisting(relPath);
+        await this.guard.check(abs, 'read');
         const s = await stat(abs);
         if (s.isDirectory())
-            throw new Error('不能读取目录');
+            throw new TextError(t('readDirectory'));
         const from = Math.max(0, Math.floor(start));
         const to = Math.min(s.size, Math.floor(end));
         if (to <= from)
@@ -314,37 +391,39 @@ class ScopedStorageService {
         const relPath = this.parseSelfUri(uri);
         this.requirePermission('readable');
         const abs = await this.resolveExisting(relPath);
+        await this.guard.check(abs, 'read');
         const fileStat = await this.statFromAbs(abs, relPath);
         if (fileStat.isDirectory)
-            throw new Error('不能下载目录');
+            throw new TextError(t('downloadDirectory'));
         this.logger.info(`storage.download ${toUri(this.root.name, relPath)} size=${fileStat.size}`);
         return { stream: createReadStream(abs), stat: fileStat };
     }
-    async writeFile(uri, data) {
+    async writeFile(uri, data, options) {
         const relPath = this.parseSelfUri(uri);
         this.requirePermission('writable');
         if (!relPath)
-            throw new Error('不能覆盖根目录');
+            throw new TextError(t('overwriteRoot'));
         const abs = await this.resolveForWrite(relPath);
+        await this.guard.check(abs, 'write');
         // 目标是目录 → 在快照之前就拒。写目录反正必失败（rename 覆盖不了非空目录），
         // 但放它走到 snapshot 会让 checkpoint 记一条幽灵 write-new（loadOriginal 对目录返回 null），
         // 回滚时按 write-new 把整棵目录删掉。
         const existing = await stat(abs).catch(() => undefined);
         if (existing?.isDirectory())
-            throw new Error('不能覆盖目录');
+            throw new TextError(t('overwriteDirectory'));
         await this.snapshot(toUri(this.root.name, relPath), 'write', abs);
         await mkdir(dirname(abs), { recursive: true });
         // 原子写：先写临时文件再 rename（同分区原子覆盖），防崩溃/并发半写损坏关键持久化（users.json/scheduler-jobs 等）。
         // 随机段避免同进程同毫秒并发写同一路径撞出同名 tmp（一方 rename 后另一方 ENOENT，或串写对方内容）。
         const tmp = `${abs}.tmp.${process.pid}.${Date.now()}.${randomBytes(4).toString('hex')}`;
-        // 覆盖已有文件时沿用它的权限位：tmp 按默认 mode 创建，rename 后目标继承之，
-        // 可执行脚本写一次就从 755 掉到 644。chmod 打在 tmp 上而非 rename 后的目标，
-        // 避开两步之间的窗口；目标不存在则保持默认，stat/chmod 失败不拖累写入本身。
-        const prevMode = existing ? existing.mode & 0o777 : undefined;
+        // rename 后目标继承 tmp 的权限位：凭据一律 0600；覆盖已有文件时沿用它的权限位，否则可执行脚本写一次就从 755
+        // 掉到 644；其余按默认。权限位在建 tmp 时就给上，内容从不以更宽的权限落盘；chmod 再对齐被 umask 收窄的部分
+        //（只会比给定的窄），打在 tmp 上而非 rename 后的目标，避开两步之间的窗口，失败不拖累写入本身。
+        const mode = options?.secret ? 0o600 : existing ? existing.mode & 0o777 : undefined;
         try {
-            await writeFile(tmp, data);
-            if (prevMode !== undefined)
-                await chmod(tmp, prevMode).catch(() => { });
+            await writeFile(tmp, data, { mode });
+            if (mode !== undefined)
+                await chmod(tmp, mode).catch(() => { });
             await rename(tmp, abs);
         }
         catch (err) {
@@ -355,18 +434,20 @@ class ScopedStorageService {
     }
     async rename(uri, newName) {
         if (!newName || newName.includes('/') || newName.includes('\\') || newName === '.' || newName === '..') {
-            throw new Error('文件名不合法');
+            throw new TextError(t('badFileName'));
         }
         const relPath = this.parseSelfUri(uri);
         this.requirePermission('writable');
         if (!relPath)
-            throw new Error('不能重命名根目录');
+            throw new TextError(t('renameRoot'));
         const abs = await this.resolveExisting(relPath);
         const newRel = normalizeRelPath(`${dirname(relPath) === '.' ? '' : dirname(relPath)}/${newName}`);
         const target = await this.resolveForWrite(newRel);
+        await this.guard.check(abs, 'write', true);
+        await this.guard.check(target, 'write');
         try {
             await lstat(target);
-            throw new Error('目标名称已存在');
+            throw new TextError(t('nameExists'));
         }
         catch (err) {
             if (err.code !== 'ENOENT')
@@ -387,14 +468,16 @@ class ScopedStorageService {
         const toRel = this.parseSelfUri(targetUri); // 跨根 → root 不匹配抛错
         this.requirePermission('writable');
         if (!fromRel)
-            throw new Error('不能移动根目录');
+            throw new TextError(t('moveRoot'));
         if (!toRel)
-            throw new Error('目标不能是根目录');
+            throw new TextError(t('targetRoot'));
         const absFrom = await this.resolveExisting(fromRel);
         const absTo = await this.resolveForWrite(toRel);
+        await this.guard.check(absFrom, 'write', true);
+        await this.guard.check(absTo, 'write');
         try {
             await lstat(absTo);
-            throw new Error('目标已存在');
+            throw new TextError(t('targetExists'));
         }
         catch (err) {
             if (err.code !== 'ENOENT')
@@ -414,8 +497,9 @@ class ScopedStorageService {
         const relPath = this.parseSelfUri(uri);
         this.requirePermission('writable');
         if (!relPath)
-            throw new Error('根目录已存在，无需创建');
+            throw new TextError(t('rootExists'));
         const abs = await this.resolveForWrite(relPath);
+        await this.guard.check(abs, 'write');
         await mkdir(abs, { recursive: true }); // recursive：建全路径；已存在则 no-op（幂等）
         this.logger.info(`storage.mkdir ${toUri(this.root.name, relPath)}`);
         return toUri(this.root.name, relPath);
@@ -424,12 +508,13 @@ class ScopedStorageService {
         const relPath = this.parseSelfUri(uri);
         this.requirePermission('deletable');
         if (!relPath)
-            throw new Error('不能删除根目录');
+            throw new TextError(t('deleteRoot'));
         const abs = await this.resolveExisting(relPath);
         // `sub/..` 这类解析回根本身的路径同样是删根——上面的字面空路径守卫挡不住
         // （isInside 对 rel==='' 判内、normalizeRelPath 不中和 `..`；审计发现的旁路）。
         if (abs === (await realpath(this.root.realPath)))
-            throw new Error('不能删除根目录');
+            throw new TextError(t('deleteRoot'));
+        await this.guard.check(abs, 'write', true);
         await this.snapshot(toUri(this.root.name, relPath), 'delete', abs);
         await rm(abs, { recursive: true, force: false });
         this.logger.info(`storage.delete ${toUri(this.root.name, relPath)}`);
@@ -439,6 +524,9 @@ class ScopedStorageService {
         const permission = access === 'delete' ? 'deletable' : access === 'write' ? 'writable' : 'readable';
         this.requirePermission(permission);
         const abs = access === 'write' ? await this.resolveForWrite(relPath) : await this.resolveExisting(relPath);
+        // 以写、删的方式交出目录时连子树一起查。以读的方式交出目录（命令的工作目录等）不查子树：拿到目录的工具
+        // 本来就能按绝对路径读任何文件，挡它们靠沙箱的拒读清单，在这里拒只会让家目录的上级目录用不了
+        await this.guard.check(abs, access === 'read' ? 'read' : 'write', access !== 'read');
         this.logger.debug(`storage.resolveLocalPath ${toUri(this.root.name, relPath)} access=${access}`);
         return abs;
     }
@@ -454,7 +542,7 @@ class ScopedStorageService {
         this.requirePermission('readable');
         const absBase = resolve(this.root.realPath, normalizeRelPath(relPath));
         if (!isInside(this.root.realPath, absBase)) {
-            throw new Error('路径不合法');
+            throw new TextError(t('badPath'));
         }
         const debounceMs = 50;
         const pending = new Map();
@@ -547,37 +635,37 @@ class ScopedStorageService {
     parseSelfUri(uri) {
         const { root, relPath } = parseUri(uri);
         if (root !== this.root.name) {
-            throw new Error(`URI 根 "${root}" 不属于本 entry (${this.root.name})`);
+            throw new TextError(t('otherRoot', { root, name: this.root.name }));
         }
         return relPath;
     }
     requirePermission(permission) {
         if (!this.root[permission]) {
-            throw new Error(`存储根 ${this.root.name} 不允许该操作 (${permission})`);
+            throw new TextError(t('notAllowed', { name: this.root.name, permission }));
         }
     }
     async resolveExisting(relPath) {
         const lexical = resolve(this.root.realPath, normalizeRelPath(relPath));
         if (!isInside(this.root.realPath, lexical))
-            throw new Error('路径不合法');
+            throw new TextError(t('badPath'));
         const resolved = await realpath(lexical);
         if (!isInside(this.root.realPath, resolved))
-            throw new Error('路径不合法');
+            throw new TextError(t('badPath'));
         return resolved;
     }
     async resolveForWrite(relPath) {
         const normalized = normalizeRelPath(relPath);
         const lexical = resolve(this.root.realPath, normalized);
         if (!isInside(this.root.realPath, lexical))
-            throw new Error('路径不合法');
+            throw new TextError(t('badPath'));
         const existingParent = await this.findExistingParent(dirname(lexical));
         const parent = await realpath(existingParent);
         if (!isInside(this.root.realPath, parent))
-            throw new Error('路径不合法');
+            throw new TextError(t('badPath'));
         try {
             const target = await lstat(lexical);
             if (target.isSymbolicLink())
-                throw new Error('不允许写入符号链接');
+                throw new TextError(t('symlink'));
         }
         catch (err) {
             if (err.code !== 'ENOENT')
@@ -591,7 +679,7 @@ class ScopedStorageService {
             try {
                 const s = await lstat(current);
                 if (!s.isDirectory())
-                    throw new Error('父路径不是目录');
+                    throw new TextError(t('parentNotDirectory'));
                 return current;
             }
             catch (err) {
@@ -623,8 +711,68 @@ class ScopedStorageService {
         return info;
     }
 }
-async function createRoot(name, label, kind, rootPath, options) {
-    const abs = resolve(process.cwd(), rootPath);
+/**
+ * 本插件登记的唯一一个 storage 提供者：按 URI 的根名分给各根的 {@link ScopedStorageService}。根表在登记之前就建好，
+ * 依赖方激活时所有根都在。根名不认识时同步抛错并列出已有的根
+ */
+class LocalStorage {
+    roots;
+    constructor(roots) {
+        this.roots = roots;
+    }
+    route(uri) {
+        const { root } = parseUri(uri);
+        const scoped = this.roots.get(root);
+        if (!scoped) {
+            const names = [...this.roots.keys()];
+            throw new TextError(names.length > 0 ? t('unknownRoot', { root, roots: names.join(', ') }) : t('unknownRootNone', { root }));
+        }
+        return scoped;
+    }
+    listRoots() {
+        return [...this.roots.values()].flatMap(scoped => scoped.listRoots());
+    }
+    list(uri) {
+        return this.route(uri).list(uri);
+    }
+    stat(uri) {
+        return this.route(uri).stat(uri);
+    }
+    readFile(uri, encoding) {
+        return this.route(uri).readFile(uri, encoding);
+    }
+    readFileRange(uri, start, end) {
+        return this.route(uri).readFileRange(uri, start, end);
+    }
+    createReadStream(uri) {
+        return this.route(uri).createReadStream(uri);
+    }
+    writeFile(uri, data, options) {
+        return this.route(uri).writeFile(uri, data, options);
+    }
+    rename(uri, newName) {
+        return this.route(uri).rename(uri, newName);
+    }
+    /** 只在同一个根里移动：目标的根由那个根自己核对 */
+    move(fromUri, toUri) {
+        return this.route(fromUri).move(fromUri, toUri);
+    }
+    mkdir(uri) {
+        return this.route(uri).mkdir(uri);
+    }
+    delete(uri) {
+        return this.route(uri).delete(uri);
+    }
+    resolveLocalPath(uri, access) {
+        return this.route(uri).resolveLocalPath(uri, access);
+    }
+    watch(uri, listener) {
+        return this.route(uri).watch(uri, listener);
+    }
+}
+async function createRoot(home, name, label, kind, rootPath, options) {
+    // 相对路径按家目录解析：进程的 cwd 不带语义
+    const abs = resolve(home, rootPath);
     // path 已是文件系统根（'/'）等存在的目录时不需要创建；其它情况 mkdir -p
     if (rootPath !== '/') {
         await mkdir(abs, { recursive: true });
@@ -638,11 +786,41 @@ async function createRoot(name, label, kind, rootPath, options) {
     };
 }
 const ROOT_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
-/** 从解析后的 roots 构造可用根。显式空数组沿用内置根。 */
-async function buildRoots(parsedRoots, logger) {
+/** 按一条根配置建目录、解析真实路径并打注册日志；失败时告警并返回 undefined */
+async function openRoot(home, item, logger) {
+    const { name } = item;
+    try {
+        const root = await createRoot(home, name, item.label || name, item.kind || 'custom', item.path, {
+            browsable: item.browsable === true,
+            readable: item.readable !== false,
+            writable: item.writable === true,
+            deletable: item.deletable === true,
+        });
+        // 按路径**深度**判定，不按字符串长度：`/x` 只是个普通目录却因为长度 2 被误报，
+        // 而 `/etc`（长度 4）这种真该提醒的反而漏报。深度 ≤ 1 才是「根或根下一层」。
+        // 这只影响日志级别与提示文案，不参与任何 grant/deny —— 能访问什么由 realPath
+        // 加根的 read/write/delete 位决定，与本判断无关。
+        const depth = root.realPath.split('/').filter(Boolean).length;
+        const isHostScope = depth <= 1;
+        const log = isHostScope ? logger.warn.bind(logger) : logger.info.bind(logger);
+        log(`root ${name}:/ -> ${root.realPath}` +
+            ` (browsable=${root.browsable} read=${root.readable} write=${root.writable} delete=${root.deletable})` +
+            (isHostScope ? '  注意：该根接近/等于文件系统根，agent 通过此根可访问宿主机大量文件' : ''));
+        return root;
+    }
+    catch {
+        logger.warn(`root ${name} 注册失败，请检查 path 与目录权限`);
+        return undefined;
+    }
+}
+/**
+ * 从已校验的 roots 构造用户根；空数组时注册默认的 workspace 根。与内部根同名的项跳过并告警，告警里写明配置的路径
+ * 与内部根实际指向的位置：升级前把 data、tmp 等根指到别处的配置，那里的数据要搬过去。
+ */
+async function buildRoots(home, parsedRoots, internal, logger) {
     let entries = parsedRoots.slice();
     if (entries.length === 0) {
-        logger.warn('storage roots 配置为空，将注册默认 5 个内置根（workspace/data/tmp/pluginData/logs）');
+        logger.warn('storage roots 配置为空，将注册默认根 workspace');
         entries = DEFAULT_ROOTS.slice();
     }
     const out = [];
@@ -658,75 +836,67 @@ async function buildRoots(parsedRoots, logger) {
             logger.warn('roots 跳过非法根名（仅允许字母/数字/下划线/连字符，且需以字母开头）');
             continue;
         }
+        const internalPath = internal.get(name);
+        if (internalPath !== undefined) {
+            logger.warn(`roots 跳过 ${name}（配置的 path：${path}）：与插件内部根同名，${name}:/ 指向 ${internalPath}；` +
+                '配置里的这一项可以删掉，原来放在别处的数据要搬到这里');
+            continue;
+        }
         if (seen.has(name)) {
             logger.warn(`roots 跳过重复根名 ${name}`);
             continue;
         }
         seen.add(name);
-        try {
-            const root = await createRoot(name, item.label || name, item.kind || 'custom', path, {
-                browsable: item.browsable === true,
-                readable: item.readable !== false,
-                writable: item.writable === true,
-                deletable: item.deletable === true,
-            });
-            // 按路径**深度**判定，不按字符串长度：`/x` 只是个普通目录却因为长度 2 被误报，
-            // 而 `/etc`（长度 4）这种真该提醒的反而漏报。深度 ≤ 1 才是「根或根下一层」。
-            // 这只影响日志级别与提示文案，不参与任何 grant/deny —— 能访问什么由 realPath
-            // 加根的 read/write/delete 位决定，与本判断无关。
-            const depth = root.realPath.split('/').filter(Boolean).length;
-            const isHostScope = depth <= 1;
-            const log = isHostScope ? logger.warn.bind(logger) : logger.info.bind(logger);
-            log(`root ${name}:/ -> ${root.realPath}` +
-                ` (browsable=${root.browsable} read=${root.readable} write=${root.writable} delete=${root.deletable})` +
-                (isHostScope ? '  ⚠ 该根接近/等于文件系统根，agent 通过此根可访问宿主机大量文件' : ''));
+        const root = await openRoot(home, { ...item, name, path }, logger);
+        if (root)
             out.push(root);
-        }
-        catch {
-            logger.warn(`root ${name} 注册失败，请检查 path 与目录权限`);
-        }
     }
     return out;
 }
-const uses = { provide, services, logger, lifecycle, config, doctor: optional(doctor) };
+const uses = { provide, services, logger, lifecycle, config, paths: hostPaths, doctor: optional(doctor) };
 export default definePlugin({
     name: PLUGIN_NAME,
-    displayName: '本地存储根（命名 + 路径解析）',
+    displayName: t('displayName'),
     subsystem: 'storage',
     configSchema,
     provides: [storage],
     uses,
     async apply(caps) {
-        const logger = caps.logger.child('storage');
-        const cfg = parseConfig(configSchema, caps.config, logger);
-        const roots = await buildRoots(cfg.roots, logger);
+        const logger = caps.logger.use.child('storage');
+        const cfg = parseConfig(configSchema, caps.config.use, logger);
+        const paths = caps.paths.use;
+        const home = paths.home;
+        const guard = new HostFileGuard({ secrets: paths.secrets, config: paths.config });
+        const internal = internalRoots(paths);
+        const roots = await buildRoots(home, cfg.roots, new Map(internal.map(r => [r.name, r.path])), logger);
+        // 插件自己的数据都在内部根里；用户根一个都没有时只是缺了文件工具的工作根，照常提供存储
         if (roots.length === 0)
-            throw new Error('plugin-storage-local: 没有任何可用根，请检查 roots 配置');
-        // service-granularity：每个 root 单独注册一个 entry。
-        // - entryId = `${实例 id}/${root.name}`，便于在 ServiceContainer 中按根定位、避免跨实例同名冲突；
-        // - 权限由 root 的 readable/writable/deletable 位携带（StorageRootInfo），storage-api 网关按位路由；
-        // - URI 路由由 createStorageGateway(storage) helper 在调用方完成，不再有 facade。
+            logger.warn('没有可用的用户根（文件工具的工作根），请检查 roots 配置');
+        for (const item of internal) {
+            const root = await openRoot(home, item, logger);
+            if (root)
+                roots.push(root);
+        }
+        // 全部根就绪之后整体登记一个提供者，根在它内部路由：依赖方激活时就看得到每一个根
+        const scoped = new Map();
         for (const root of roots) {
             if (!root.readable && !root.writable && !root.deletable) {
                 logger.warn(`root ${root.name} 没有任何权限位，跳过注册`);
                 continue;
             }
-            const scoped = new ScopedStorageService(root, logger, caps.services, caps.lifecycle.onDispose);
-            caps.provide(storage, scoped, {
-                entryId: `${caps.lifecycle.id}/${root.name}`,
-                label: root.label || `本地根 ${root.name}`,
-            });
+            scoped.set(root.name, new ScopedStorageService(root, guard, logger, caps.services.use, caps.lifecycle.use.onDispose));
         }
+        caps.provide.use(storage, new LocalStorage(scoped), { label: t('provideLabel') });
         // 诊断检查项：探测每个 writable root 是否真的可写。
-        // 由 storage 插件按当前 roots 配置上报，而非 doctor 硬编码 fs.data：data/ 仅是默认 root 之一，
-        // 不应由 doctor 单独「祝福」；按 roots 上报才能反映用户自定义根（如 host:/、project_x）的真实状态。
-        caps.doctor.registerCheck({
+        // 由 storage 插件按全部根（含内置根）上报，而非 doctor 硬编码 fs.data：
+        // 按根上报才能反映用户自定义根（如 host:/、project_x）的真实状态。
+        caps.doctor.use.registerCheck({
             id: 'storage.roots',
             category: 'filesystem',
             async run() {
                 const targets = roots.filter(r => r.writable);
                 if (targets.length === 0) {
-                    return { id: 'storage.roots', category: 'filesystem', level: 'warn', message: '没有任何 writable 存储根' };
+                    return { id: 'storage.roots', category: 'filesystem', level: 'warn', message: t('noWritableRoots') };
                 }
                 const results = [];
                 for (const root of targets) {
@@ -746,15 +916,15 @@ async function probeRootWritable(rootName, dir) {
         await writeFile(probe, 'ok');
         await stat(probe);
         await unlink(probe);
-        return { id, category: 'filesystem', level: 'ok', message: `根 ${rootName} (${dir}) 可写` };
+        return { id, category: 'filesystem', level: 'ok', message: t('rootWritable', { name: rootName, dir }) };
     }
     catch (err) {
         return {
             id,
             category: 'filesystem',
             level: 'error',
-            message: `根 ${rootName} (${dir}) 不可写`,
-            detail: err instanceof Error ? err.message : String(err),
+            message: t('rootNotWritable', { name: rootName, dir }),
+            detail: textOf(err),
         };
     }
 }