@fa-software/semi2-dsh 0.0.10-preview.20260920042705

package/lib/configuration/skill-resources.js

@@ -0,0 +1,218 @@
+// @fa-software/semi2-dsh/configuration/skill-resources —— 技能附属资源物化（hub 附件字节 → 宿主真实目录）。
+// dsh 只把 `resourceBase` 当提示文本渲染（`<skill_resources>`），模型最终用通用 read 读宿主路径，
+// 所以字节必须真正落盘；目录布局按版本分桶（`<root>/<id>/v<version>/files/<rel>`）。
+import { createHash, randomBytes } from 'node:crypto';
+import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/** 清单文件名：放版本目录根，不塞进 `files/`（那是模型可见的资源根，不混元数据）。 */
+const MANIFEST_NAME = '.manifest.json';
+/** 版本目录名（`v1`）与物化中间目录名（`v1.tmp-<hex>`）：GC 只认这两种，别的目录不碰。 */
+const VERSION_NAME = /^v\d+$/;
+const STAGING_NAME = /^v\d+\.tmp-[0-9a-f]+$/;
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 缓存根的选择理由：`DSH_HOME` 是宿主自己的状态根——跨进程复用、随宿主生命周期清理，
+ * 也不会像 /tmp 那样被系统按空闲时间半路收走；没有它（容器面 / 自定义 HOME）时退回系统临时目录。
+ * 两级都保留 `semi2-skills` 命名空间，GC 才敢对整个子树做删除。
+ */
+function cacheRoot(environment) {
+    const home = environment.DSH_HOME?.trim();
+    if (home === undefined || home === '')
+        return join(tmpdir(), 'semi2-skills');
+    return join(home, 'skills-cache', 'semi2-skills');
+}
+/** hub 侧已校验；这里是「hub 被绕过」时的第二道闸：拒绝对路径、`..`、NUL 与反斜杠。 */
+function safeRelativePath(path) {
+    if (path === '' || path.includes('\0') || path.includes('\\'))
+        return false;
+    if (path.startsWith('/') || /^[A-Za-z]:/.test(path))
+        return false;
+    return path
+        .split('/')
+        .every(segment => segment !== '' && segment !== '.' && segment !== '..');
+}
+/** skillId 要当目录名用：只接受 hub 的逻辑 id 形态，避免它顺带改写路径。 */
+function safeSegment(value) {
+    return /^[A-Za-z0-9._-]+$/.test(value) && value !== '.' && value !== '..';
+}
+/** 文本类附件是 UTF8（content 是原文），其余是 BASE64；两种都还原成字节再落盘。 */
+function decode(file) {
+    return file.encoding === 'BASE64'
+        ? Buffer.from(file.content, 'base64')
+        : Buffer.from(file.content, 'utf8');
+}
+/** 清单按 path 排序后序列化：同一份附件集合必须得到逐字节相同的文本，读回比较才等价于「逐项一致」。 */
+function serializeManifest(entries) {
+    const sorted = entries.toSorted((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 逐条复核路径与解码：任一条非法就整次放弃——半份资源树比没有更危险，
+ * 正文会按相对路径引用附件，缺文件的目录会让模型读到错误内容。
+ */
+function planFiles(files, warn) {
+    const plan = [];
+    for (const file of files) {
+        if (!safeRelativePath(file.path)) {
+            warn(`技能附件路径非法（${file.path}），放弃本次资源物化`);
+            return null;
+        }
+        const bytes = decode(file);
+        plan.push({
+            relativePath: file.path,
+            bytes,
+            entry: {
+                path: file.path,
+                sha256: createHash('sha256').update(bytes).digest('hex'),
+                // 用实际解码长度而非服务端声明的 sizeBytes：清单要描述磁盘现状，才配当复用依据。
+                sizeBytes: bytes.byteLength,
+                isExecutable: file.isExecutable,
+            },
+        });
+    }
+    return plan;
+}
+/**
+ * 写一棵新树再原子换入：先在 `<versionDir>.tmp-<random>` 里写全，最后 `rename` 到版本目录。
+ * 中途失败只留 staging（本函数负责删），已有版本目录在 rename 前一刻才被替换，不会出现半棵树。
+ */
+async function writeTree(plan, versionDir, manifest) {
+    const staging = `${versionDir}.tmp-${randomBytes(6).toString('hex')}`;
+    const stagingFiles = join(staging, 'files');
+    try {
+        for (const file of plan) {
+            const target = resolve(stagingFiles, file.relativePath);
+            // 落地前再核一次包含关系：路径已筛过，这里是「hub 侧被绕过」也不越界的最后一道闸。
+            if (target !== join(stagingFiles, ...file.relativePath.split('/')))
+                throw new Error('SKILL_FILE_UNSAFE_PATH');
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, file.bytes);
+            // 可执行位是附件语义的一部分（脚本类技能靠它直接跑）。
+            if (file.entry.isExecutable)
+                await chmod(target, 0o755);
+        }
+        await writeFile(join(staging, MANIFEST_NAME), manifest);
+        // 同目录 rename 不跨设备；POSIX 要求目标不存在，所以先把目标位置已有的目录删掉再换入。
+        await rm(versionDir, { recursive: true, force: true });
+        await rename(staging, versionDir);
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true }).catch(() => { });
+        throw error;
+    }
+}
+export function createSkillResourceStore(options) {
+    const root = cacheRoot(options.environment);
+    /** 同 `(skillId, version)` 并发去重：键是版本目录绝对路径，第二次调用复用同一次物化。 */
+    const inFlight = new Map();
+    /** 物化一个版本；所有失败都在这里收敛成 null，绝不把错误抛给会话。 */
+    const writeVersion = async (skill, versionDir) => {
+        const filesDir = join(versionDir, 'files');
+        try {
+            const fetched = await options.readFiles(skill.id);
+            if (fetched === null) {
+                options.warn(`技能 ${skill.name} 的附件读取失败，本次不带 resourceBase`);
+                return null;
+            }
+            const plan = planFiles(fetched, options.warn);
+            if (plan === null)
+                return null;
+            // 空清单不物化：没有 resourceBase 时 dsh 会渲染「资源由 provider 管理」的提示。
+            if (plan.length === 0)
+                return null;
+            const manifest = serializeManifest(plan.map(file => file.entry));
+            const manifestPath = join(versionDir, MANIFEST_NAME);
+            // 幂等：清单逐字节一致且资源根还在 → 直接复用（不写盘，目录 mtime / inode 不变）。
+            if (await isDirectory(filesDir)) {
+                const existing = await readFile(manifestPath, 'utf8').catch(() => null);
+                if (existing === manifest)
+                    return filesDir;
+            }
+            await writeTree(plan, versionDir, manifest);
+            return filesDir;
+        }
+        catch (error) {
+            options.warn(`技能 ${skill.name} 的资源物化失败（${message(error)}），本次不带 resourceBase`);
+            return null;
+        }
+    };
+    /** 清掉不在当前集合里的版本目录与中间目录；技能整个缺席时连它的容器目录一起收掉。 */
+    const sweep = async (keep) => {
+        const skillDirs = await readdir(root, { withFileTypes: true }).catch(() => []);
+        for (const skillDir of skillDirs) {
+            if (!skillDir.isDirectory())
+                continue;
+            const versions = await readdir(join(root, skillDir.name), {
+                withFileTypes: true,
+            }).catch(() => []);
+            let kept = false;
+            let busy = false;
+            for (const version of versions) {
+                if (!version.isDirectory())
+                    continue;
+                const staging = STAGING_NAME.test(version.name);
+                if (!staging && !VERSION_NAME.test(version.name))
+                    continue;
+                // 中间目录 `v2.tmp-<hex>` 属于版本 `v2`：in-flight 判定要按版本目录名，不能按目录本身。
+                const versionName = staging
+                    ? version.name.slice(0, version.name.indexOf('.'))
+                    : version.name;
+                // 正在物化的版本（含它的 staging）不动：删掉会让这次 rename 失败。
+                if (inFlight.has(join(root, skillDir.name, versionName))) {
+                    busy = true;
+                    continue;
+                }
+                if (!staging && keep.has(`${skillDir.name}/${versionName}`)) {
+                    kept = true;
+                    continue;
+                }
+                await rm(join(root, skillDir.name, version.name), {
+                    recursive: true,
+                    force: true,
+                });
+            }
+            if (!kept && !busy && ![...keep].some(key => key.startsWith(`${skillDir.name}/`)))
+                await rm(join(root, skillDir.name), { recursive: true, force: true });
+        }
+    };
+    return {
+        async materialize(skill) {
+            if (skill.files.length === 0)
+                return null;
+            if (!safeSegment(skill.id)) {
+                options.warn(`技能 id（${skill.id}）不能用作缓存目录名，跳过资源物化`);
+                return null;
+            }
+            const versionDir = join(root, skill.id, `v${skill.version}`);
+            const pending = inFlight.get(versionDir);
+            if (pending !== undefined)
+                return pending;
+            // 先登记再 await：同 tick 的第二个调用必须看到这次物化（去重靠这一步的同步性）。
+            const run = writeVersion(skill, versionDir).finally(() => {
+                inFlight.delete(versionDir);
+            });
+            inFlight.set(versionDir, run);
+            return run;
+        },
+        reconcile(skills) {
+            // 降级（skills = null）时当前集合未知：删任何目录都可能让 last-good 正文里的路径悬空。
+            if (skills === null)
+                return;
+            const keep = new Set(skills.map(skill => `${skill.id}/v${skill.version}`));
+            void sweep(keep).catch((error) => {
+                options.warn(`技能资源缓存清理失败（${message(error)}）`);
+            });
+        },
+    };
+}

package/lib/configuration/skills.js

@@ -0,0 +1,185 @@
+import { isSkillName, } from '@deepseek-ai/dsh-skill';
+import { createSkillResourceStore } from './skill-resources.js';
+const HUB_SKILL_RANK = 240;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 一条技能事实 → dsh 候选；非法 name 或空 description 直接丢弃（服务端已校验，这里是防御：
+ * 坏条目不该进会话目录）。项目作用域由调用方决定顺序，候选本身不带作用域。
+ */
+function candidateOf(skill, warn) {
+    if (!isSkillName(skill.name)) {
+        warn(`技能 ${skill.id} 的 name 不是合法 kebab-case，已忽略`);
+        return null;
+    }
+    if (skill.description.trim() === '') {
+        warn(`技能 ${skill.name} 的 description 为空，已忽略`);
+        return null;
+    }
+    return {
+        name: skill.name,
+        description: skill.description,
+        // exactOptionalPropertyTypes：可选字段只能用条件展开，不能赋 undefined。
+        ...(skill.whenToUse ? { whenToUse: skill.whenToUse } : {}),
+        rank: HUB_SKILL_RANK,
+        locator: skill.id,
+        source: 'custom',
+        provider: 'semi2-hub',
+        invocation: { modelInvocable: true, userInvocable: true },
+    };
+}
+function definitionOf(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        ...(skill.whenToUse ? { whenToUse: skill.whenToUse } : {}),
+        content: skill.content,
+        source: 'custom',
+        provider: 'semi2-hub',
+        invocation: { modelInvocable: true, userInvocable: true },
+    };
+}
+export function installSkills(ctx, config, warn) {
+    // 附件字节 → 宿主目录的物化器：只在 get() 真正加载技能时才动它（list 只给清单）。
+    const resources = createSkillResourceStore({
+        readFiles: skillId => config.skillFiles(skillId),
+        environment: process.env,
+        warn,
+    });
+    /** 目录观测：先判运行面状态够不够权威，再判 cwd 有没有工作区身份。 */
+    const observe = async (cwd) => {
+        // 首装未落定前「未知」不能当权威空目录：先等这次领取结束（后续 reload 时 ready 已 settle）。
+        await config.ready;
+        const { status, skills } = config.state;
+        // 没接 hub = 权威地没有控制台技能；也顺带让上一个账号的 last-good 失效。
+        if (status === 'local')
+            return { candidates: [], complete: true };
+        // 读取中 / 整体失败 / 技能块降级：都还没拿到权威目录，交回不完整观测让 dsh 保留 last-good。
+        if (status !== 'ready' || skills === null) {
+            return { candidates: [], complete: false };
+        }
+        const project = await config.projectForCwd(cwd);
+        // 全仓统一口径：未登记目录一个技能都不给（全局技能也只是「在所有已登记工作区共享」）。
+        if (project === null)
+            return { candidates: [], complete: true };
+        const candidates = [];
+        const seen = new Set();
+        const push = (skill) => {
+            if (seen.has(skill.name))
+                return;
+            const candidate = candidateOf(skill, warn);
+            if (candidate === null)
+                return;
+            seen.add(skill.name);
+            candidates.push(candidate);
+        };
+        // 先项目命中、再全局未重名：更具体的作用域压过更通用的（同名裁决在插件侧做）。
+        for (const skill of skills)
+            if (skill.projectId === project.id)
+                push(skill);
+        for (const skill of skills)
+            if (skill.projectId === null)
+                push(skill);
+        return { candidates, complete: true };
+    };
+    const guardedObserve = async (cwd) => {
+        try {
+            return await observe(cwd);
+        }
+        catch (error) {
+            // 解析链（projectForCwd 会问 hub）出错也只是没拿到完整观测，绝不 reject 会话。
+            warn(`skills list failed: ${errorMessage(error)}`);
+            return { candidates: [], complete: false };
+        }
+    };
+    const provider = {
+        name: 'semi2-hub',
+        async list(options) {
+            const observation = await guardedObserve(options.cwd);
+            return {
+                candidates: observation.candidates,
+                complete: observation.complete,
+            };
+        },
+        async get(candidate, options) {
+            try {
+                await config.ready;
+                const { status, skills } = config.state;
+                if (status !== 'ready' || skills === null)
+                    return undefined;
+                const found = skills.find(skill => skill.id === String(candidate.locator));
+                // 目录已刷新且这一条不在其中：服务端已撤下 / 归档，点名加载也不给。
+                if (found === undefined)
+                    return undefined;
+                const cwd = options.cwd?.trim();
+                if (cwd !== undefined && cwd !== '') {
+                    const project = await config.projectForCwd(cwd);
+                    // 与 list 同口径：未登记目录连点名加载也不行；项目技能只在该项目的 cwd 里加载。
+                    if (project === null)
+                        return undefined;
+                    if (found.projectId !== null && found.projectId !== project.id)
+                        return undefined;
+                }
+                // 无 cwd（非会话调用）放行目录内已有条目：已列出的必须还能加载。
+                // 带附件的技能先把字节物化到宿主目录，再以 resourceBase 指给模型；失败只 warn 不带 base。
+                const definition = definitionOf(found);
+                const directory = await resources.materialize(found);
+                return directory === null
+                    ? definition
+                    : {
+                        ...definition,
+                        resourceBase: { kind: 'directory', path: directory },
+                    };
+            }
+            catch (error) {
+                warn(`skills get failed: ${errorMessage(error)}`);
+                return undefined;
+            }
+        },
+    };
+    let invalidate = () => {
+        // 注册失败前无缓存可失效。
+    };
+    const disposers = [];
+    try {
+        disposers.push(ctx.skills.registerProvider((control) => {
+            invalidate = () => {
+                control.invalidate();
+            };
+            return provider;
+        }));
+        // 目录随装配与工作区映射变化：两条事件都要丢 dsh 的按 cwd 缓存（cwd → 项目解析依赖后者），
+        // 并顺手清掉已不在当前 (skillId, version) 集合里的资源缓存（降级时 skills=null，物化器不删任何东西）。
+        const drop = (state) => {
+            invalidate();
+            resources.reconcile(state?.skills ?? null);
+        };
+        disposers.push(ctx.on('semi2/config-updated', drop));
+        disposers.push(ctx.on('semi2/workspaces-updated', drop));
+    }
+    catch (error) {
+        // fake ctx 可能没有 skills 服务：注册失败只 warn，其余能力照常。
+        warn(`hub skills provider register failed: ${errorMessage(error)}`);
+    }
+    return {
+        dispose: () => {
+            for (const dispose of disposers) {
+                try {
+                    dispose();
+                }
+                catch {
+                    // 收尾不抛。
+                }
+            }
+        },
+        invalidate: () => {
+            try {
+                invalidate();
+            }
+            catch {
+                // 缓存失效失败不影响会话。
+            }
+        },
+    };
+}

package/lib/configuration/status.js

@@ -0,0 +1,57 @@
+/** 设置命名空间 `semi2` 的状态字段（顺序 = UI 展示顺序）；`reload` 由 UI 写，不在此列。 */
+export const STATUS_FIELDS = [
+    'status',
+    'error',
+    'loadedAt',
+    'consoleUrl',
+    'identity',
+    'credentialSource',
+    'platform',
+    'startupDir',
+    'workspaceCount',
+    'workspaces',
+    'projectCount',
+    'projects',
+    'model',
+    'skills',
+];
+/** 状态里最多列几个工作区：这段字符串要落 YAML，超出只报增量。 */
+const MAX_LISTED_WORKSPACES = 20;
+/** `标题 → slug(项目名)`：只有命中 hub 项目的工作区才进这里，读一行就知道同步到了什么。 */
+function renderWorkspaces(workspaces) {
+    const listed = workspaces.slice(0, MAX_LISTED_WORKSPACES).map((entry) => {
+        const slug = entry.slug ?? '未解析';
+        const project = entry.name ?? '未匹配';
+        return `${entry.title} → ${slug}(${project})`;
+    });
+    const hidden = workspaces.length - listed.length;
+    return hidden > 0 ? `${listed.join(' | ')} | …+${String(hidden)}` : listed.join(' | ');
+}
+/** 身份 = hub 当前账户：展示名与用户名不同时并列，未就绪（未登录 / 读失败）为空串。 */
+function identityText(identity) {
+    if (identity === null)
+        return '';
+    return identity.displayName !== '' && identity.displayName !== identity.username
+        ? `${identity.displayName} (${identity.username})`
+        : identity.username;
+}
+export function statusFields(state, facts = {}) {
+    const workspaces = state.workspaces;
+    return {
+        status: state.status,
+        error: state.error ?? '',
+        loadedAt: state.loadedAt ?? '',
+        consoleUrl: state.consoleUrl ?? '',
+        identity: identityText(state.identity),
+        credentialSource: facts.credentialSource ?? '',
+        platform: facts.platform ?? '',
+        startupDir: process.cwd(),
+        workspaceCount: String(workspaces.length),
+        workspaces: renderWorkspaces(workspaces),
+        projectCount: String(state.projects.length),
+        projects: state.projects.map(project => project.slug).join(','),
+        model: state.model ? `${state.model.provider}/${state.model.id}` : '',
+        // 控制台技能目录条数；null = 没拿到权威目录（≠ 空目录），落空串。
+        skills: state.skills == null ? '' : String(state.skills.length),
+    };
+}

package/lib/configuration/workspace.js

@@ -0,0 +1,55 @@
+// @fa-software/semi2-dsh/configuration/workspace —— 会话 cwd → 项目 slug（进程内缓存）。
+// git origin 反解失败（非 git 仓库 / 无 origin / 无 git 可执行文件）回落 CNB_REPO_SLUG。
+import { execFile } from 'node:child_process';
+const GIT_TIMEOUT_MS = 2_000;
+const cache = new Map();
+/** 从 git remote URL 提取 org/repo（https 与 scp 风格皆可），小写规范化。 */
+export function slugFromRemoteUrl(url) {
+    let rest = url
+        .trim()
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, '')
+        .replace(/^[^@/]*@/, '');
+    const colon = rest.indexOf(':');
+    const slash = rest.indexOf('/');
+    if (colon !== -1 && (slash === -1 || colon < slash))
+        rest = rest.slice(colon + 1); // scp 风格 git@host:org/repo
+    else if (slash !== -1)
+        rest = rest.slice(slash + 1);
+    else
+        return null;
+    const path = rest
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/i, '');
+    return path === '' ? null : path.toLowerCase();
+}
+/** 在 config.state.projects 里按 slug 精确匹配。 */
+export function matchProject(projects, slug) {
+    if (slug === null)
+        return null;
+    return projects.find(project => project.slug.toLowerCase() === slug) ?? null;
+}
+/** CNB 面兜底：容器里工作区就是被触发的仓库，slug 由触发 env 给出。 */
+function fallbackSlug(env) {
+    const slug = env.CNB_REPO_SLUG?.trim().toLowerCase();
+    return slug !== undefined && slug !== '' ? slug : null;
+}
+function gitOriginSlug(directory) {
+    const { promise, resolve } = Promise.withResolvers();
+    execFile('git', ['-C', directory, 'remote', 'get-url', 'origin'], { timeout: GIT_TIMEOUT_MS, encoding: 'utf8' }, (error, stdout) => {
+        resolve(error === null ? slugFromRemoteUrl(stdout) : null);
+    });
+    return promise;
+}
+/** cwd → git origin slug；进程内按 cwd 缓存。 */
+export async function workspaceSlug(cwd, env) {
+    const directory = cwd?.trim();
+    if (directory === undefined || directory === '')
+        return fallbackSlug(env);
+    const cached = cache.get(directory);
+    if (cached !== undefined)
+        return cached;
+    const slug = (await gitOriginSlug(directory)) ?? fallbackSlug(env);
+    cache.set(directory, slug);
+    return slug;
+}

package/lib/configuration/workspaces.js

@@ -0,0 +1,169 @@
+// @fa-software/semi2-dsh/configuration/workspaces —— 工作区登记（dsh 工作区 → git 项目映射）。
+// Web 面消费 dsh 的 workspaceController.follow（基线 + 增量），headless 面服务缺席时退化为单条隐式工作区（cwd / CNB_REPO_SLUG）。
+// 登记表只存本地映射事实（目录与解析结果，密钥绝不落盘）；所有失败都落成条目上的 error，绝不抛。
+import { realpath } from 'node:fs/promises';
+import { basename } from 'node:path';
+/** 未解析条目的起点：映射三件套留空，等一次同步填。 */
+export function pendingEntry(path, title, implicit = false) {
+    return {
+        path,
+        title,
+        slug: null,
+        projectId: null,
+        name: null,
+        syncedAt: null,
+        implicit,
+    };
+}
+/** headless 面没有 dsh 工作区服务：启动目录就是唯一工作区。 */
+export function implicitWorkspace(cwd) {
+    return pendingEntry(cwd, basename(cwd) || cwd, true);
+}
+/**
+ * 参与状态展示与持久化的工作区：只有命中 hub 项目的才算数。反解不出 slug（非 git）与
+ * hub 里查无此项目一样，都是「不归我们管」——簿记里留着等一次重解析（git init / 加
+ * remote / hub 补建项目都能上账），但不占状态、不入库。
+ */
+export function trackedWorkspaces(entries) {
+    return entries.filter(entry => entry.projectId !== null);
+}
+/**
+ * cwd → canonical 路径。dsh registry 存的已是 realpath 结果，而会话 header 的 cwd 可能是
+ * 软链或带 `..` 的拼写，两边必须经同一把尺子才比得上；目录不在（已删 / 无权限）保留原拼写，
+ * 好让条目仍能定位与展示——失败结果不缓存，目录出现后还能纠正。
+ */
+const canonical = new Map();
+export async function canonicalPath(directory) {
+    const cached = canonical.get(directory);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const resolved = await realpath(directory);
+        canonical.set(directory, resolved);
+        return resolved;
+    }
+    catch {
+        return directory;
+    }
+}
+/**
+ * 工作区登记表：canonical path 为键，另记 workspaceId → path 以便 remove / 改名定位。
+ * 只由配置运行时单线程驱动（feed 帧与同步排在同一条队列上），故不做并发保护。
+ */
+export class WorkspaceBook {
+    byPath = new Map();
+    pathById = new Map();
+    /** 播下 dsh 基线：registry 是权威列表，不在基线里的陈旧条目（隐式条目除外）撤下。 */
+    applyBaseline(items) {
+        const seen = new Set();
+        for (const item of items) {
+            seen.add(item.path);
+            this.pathById.set(item.workspaceId, item.path);
+            const previous = this.byPath.get(item.path);
+            this.byPath.set(item.path, previous === undefined
+                ? pendingEntry(item.path, item.title)
+                : { ...previous, title: item.title, implicit: false });
+        }
+        for (const [path, entry] of [...this.byPath])
+            if (!entry.implicit && !seen.has(path))
+                this.byPath.delete(path);
+    }
+    /** 新增或改名：保留既有解析结果（同步很贵），只换标题。 */
+    upsertWorkspace(view) {
+        this.pathById.set(view.workspaceId, view.path);
+        const previous = this.byPath.get(view.path);
+        const next = previous === undefined
+            ? pendingEntry(view.path, view.title)
+            : { ...previous, title: view.title, implicit: false };
+        this.byPath.set(view.path, next);
+        return next;
+    }
+    /** 移除一个工作区；未知 id 返回 undefined（幂等）。 */
+    removeWorkspace(workspaceId) {
+        const path = this.pathById.get(workspaceId);
+        if (path === undefined)
+            return undefined;
+        this.pathById.delete(workspaceId);
+        const entry = this.byPath.get(path);
+        this.byPath.delete(path);
+        return entry;
+    }
+    /** 隐式工作区：同路径已有条目就保留（不把已解析结果降级回未解析）。 */
+    ensureImplicit(cwd) {
+        const existing = this.byPath.get(cwd);
+        if (existing !== undefined)
+            return existing;
+        const entry = implicitWorkspace(cwd);
+        this.byPath.set(cwd, entry);
+        return entry;
+    }
+    /** 从持久化事实恢复（启动一次）；解析结果保留，项目绑定等一次同步补齐。 */
+    restore(entries) {
+        for (const entry of entries)
+            this.byPath.set(entry.path, entry);
+    }
+    get(path) {
+        return this.byPath.get(path);
+    }
+    set(entry) {
+        this.byPath.set(entry.path, entry);
+    }
+    entries() {
+        return [...this.byPath.values()];
+    }
+}
+export function persistedWorkspaces(entries) {
+    return entries
+        .filter(entry => !entry.implicit)
+        .map(entry => ({
+        path: entry.path,
+        title: entry.title,
+        slug: entry.slug ?? '',
+        projectId: entry.projectId ?? '',
+        name: entry.name ?? '',
+        syncedAt: entry.syncedAt ?? '',
+    }));
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 订阅 dsh 工作区变更。服务缺席（headless 面）时回调永不执行，由调用方播一条隐式工作区兜底；
+ * 消费异常只 warn——已登记的工作区继续可用，绝不因订阅中断阻断会话。
+ */
+export function installWorkspaceFeed(ctx, handlers, warn) {
+    ctx.inject(['workspaceController'], (scoped) => {
+        const controller = scoped.get('workspaceController');
+        if (controller === undefined)
+            return;
+        const abort = new AbortController();
+        scoped.effect(() => () => {
+            abort.abort();
+        });
+        void (async () => {
+            // 单帧失败只记一条：丢掉订阅会让后续工作区再也不同步（降级是硬规则）。
+            const apply = async (work) => {
+                try {
+                    await work();
+                }
+                catch (error) {
+                    warn(`工作区帧处理失败：${describe(error)}`);
+                }
+            };
+            try {
+                for await (const frame of controller.follow(abort.signal)) {
+                    if (frame.type === 'baseline')
+                        await apply(() => handlers.baseline(frame.value.items));
+                    else if (frame.type === 'upsert')
+                        await apply(() => handlers.upsert(frame.workspace));
+                    else if (frame.type === 'remove')
+                        await apply(() => handlers.remove(frame.workspaceId));
+                }
+            }
+            catch (error) {
+                if (!abort.signal.aborted)
+                    warn(`工作区变更订阅中断：${describe(error)}`);
+            }
+        })();
+    });
+}