@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/profile/catalog.js

@@ -0,0 +1,152 @@
+/**
+ * 数字人仓库（catalog）：从 git 仓库读取一批数字人定义。
+ *
+ * 与插件市场并列而非寄生：数字人有自己的一等分发原语（导入/导出 + 本仓库），
+ * 不需要先成为插件。仓库布局与 cjhyy/mimi-humans 一致：
+ *
+ *   humans.json          —— 目录清单（name/label/description/category/tags）
+ *   humans/<name>/profile.json —— WorkspaceProfile 定义（含可选 requires）
+ *
+ * 本模块只做**读取与校验**，克隆/更新由 host 驱动（涉及网络与磁盘写入）。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { WorkspaceProfileSchema } from "./types.js";
+/** `owner/repo`，与 SKILL_REPO_RE 同源，供仓库地址复用。 */
+export const CATALOG_REPO_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+/** 单个目录段的安全名，挡住 `..`、分隔符与 NUL。 */
+const SAFE_SEGMENT_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/**
+ * `owner/repo` → 一个安全的目录段。小写化保证同一仓库不同大小写写法命中同一份
+ * 缓存；斜杠换成 `-` 后仍需通过 SAFE_SEGMENT_RE，杜绝路径逃逸。
+ */
+export function sourceToRepoKey(repo) {
+    if (!CATALOG_REPO_RE.test(repo)) {
+        throw new Error(`invalid digital-human repo "${repo}" (expected owner/repo)`);
+    }
+    const key = repo
+        .toLowerCase()
+        .replace(/\.git$/, "")
+        .replace("/", "-");
+    if (!SAFE_SEGMENT_RE.test(key)) {
+        throw new Error(`digital-human repo "${repo}" does not map to a safe directory name`);
+    }
+    return key;
+}
+/** 解析 humans.json。缺 humans 数组按空目录处理；JSON 坏了才抛。 */
+export function parseHumansManifest(raw) {
+    const value = JSON.parse(raw);
+    const rawHumans = Array.isArray(value.humans) ? value.humans : [];
+    const humans = [];
+    for (const item of rawHumans) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const entry = item;
+        if (typeof entry.name !== "string" || !entry.name)
+            continue;
+        humans.push({
+            name: entry.name,
+            ...(typeof entry.label === "string" ? { label: entry.label } : {}),
+            ...(typeof entry.description === "string" ? { description: entry.description } : {}),
+            ...(typeof entry.category === "string" ? { category: entry.category } : {}),
+            tags: Array.isArray(entry.tags)
+                ? entry.tags.filter((t) => typeof t === "string")
+                : [],
+        });
+    }
+    const rawTeams = Array.isArray(value.teams) ? value.teams : [];
+    const teams = [];
+    for (const item of rawTeams) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const entry = item;
+        if (typeof entry.id !== "string" || !entry.id)
+            continue;
+        if (typeof entry.name !== "string" || !entry.name)
+            continue;
+        const rawMembers = Array.isArray(entry.members) ? entry.members : [];
+        const members = rawMembers.filter((m) => typeof m === "string" && m.length > 0);
+        if (members.length < 2)
+            continue;
+        teams.push({
+            id: entry.id,
+            name: entry.name,
+            ...(typeof entry.description === "string" ? { description: entry.description } : {}),
+            members,
+            ...(typeof entry.lead === "string" && entry.lead ? { lead: entry.lead } : {}),
+            ...(typeof entry.playbook === "string" && entry.playbook ? { playbook: entry.playbook } : {}),
+        });
+    }
+    return {
+        ...(typeof value.name === "string" ? { name: value.name } : {}),
+        ...(typeof value.description === "string" ? { description: value.description } : {}),
+        humans,
+        teams,
+    };
+}
+/** 读取一个已克隆的数字人仓库目录。 */
+export function readCatalogFromDir(dir, sourceRepo) {
+    const manifestPath = join(dir, "humans.json");
+    if (!existsSync(manifestPath)) {
+        return { entries: [], teams: [], errors: [`${sourceRepo}: humans.json not found`] };
+    }
+    let manifest;
+    try {
+        manifest = parseHumansManifest(readFileSync(manifestPath, "utf-8"));
+    }
+    catch (error) {
+        return {
+            entries: [],
+            teams: [],
+            errors: [`${sourceRepo}: humans.json is not valid JSON (${describe(error)})`],
+        };
+    }
+    const entries = [];
+    const errors = [];
+    for (const item of manifest.humans) {
+        // The manifest is untrusted input from a cloned repo — never join a name
+        // that could climb out of the humans/ directory.
+        if (!SAFE_SEGMENT_RE.test(item.name)) {
+            errors.push(`${sourceRepo}: entry "${item.name}" has an unsafe name`);
+            continue;
+        }
+        const profilePath = join(dir, "humans", item.name, "profile.json");
+        try {
+            const profile = WorkspaceProfileSchema.parse(JSON.parse(readFileSync(profilePath, "utf-8")));
+            entries.push({
+                profile,
+                sourceRepo,
+                ...(item.category ? { category: item.category } : {}),
+                tags: item.tags ?? [],
+            });
+        }
+        catch (error) {
+            errors.push(`${sourceRepo}: "${item.name}" is invalid (${describe(error)})`);
+        }
+    }
+    // A team is only usable if every member ships in this same repo — otherwise
+    // summoning it would create Sessions bound to digital humans that do not exist.
+    const shipped = new Set(entries.map((entry) => entry.profile.name));
+    const teams = [];
+    for (const team of manifest.teams) {
+        if (!SAFE_SEGMENT_RE.test(team.id)) {
+            errors.push(`${sourceRepo}: team "${team.id}" has an unsafe id`);
+            continue;
+        }
+        const missing = team.members.filter((member) => !shipped.has(member));
+        if (missing.length > 0) {
+            errors.push(`${sourceRepo}: team "${team.id}" references missing ${missing.join(", ")}`);
+            continue;
+        }
+        if (team.lead && !team.members.includes(team.lead)) {
+            errors.push(`${sourceRepo}: team "${team.id}" lead is not one of its members`);
+            continue;
+        }
+        teams.push({ ...team, sourceRepo });
+    }
+    return { entries, teams, errors };
+}
+function describe(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length > 200 ? `${message.slice(0, 200)}…` : message;
+}

package/dist/profile/index.d.ts

@@ -0,0 +1,7 @@
+export { SKILL_REPO_RE, WORKSPACE_PROFILE_NAME_RE, WorkspaceProfileRequirementsSchema, WorkspaceProfileSchema, type SkillRequirement, type ToolRequirement, type WorkspaceProfile, type WorkspaceProfileInput, type WorkspaceProfileRequirements, } from "./types.js";
+export { CATALOG_REPO_RE, parseHumansManifest, readCatalogFromDir, sourceToRepoKey, type CatalogEntry as DigitalHumanCatalogSourceEntry, type CatalogTeam as DigitalHumanCatalogTeam, type HumansManifestTeam, type CatalogReadResult, type HumansManifest, type HumansManifestEntry, } from "./catalog.js";
+export { addHumanRepo, humanRepoDir, humanReposRoot, listHumanRepoDetails, listHumanRepos, readAllHumanRepoEntries, removeHumanRepo, type HumanRepoListEntry, type RegisteredHumanRepo, } from "./catalog-store.js";
+export { buildSkillInstallArgs, planProfileRequirements, summarizeSkillConflicts, type KnownSkill, type MissingTool, type PlannedSkillInstall, type ProfileRequirementPlan, type SkillConflict, } from "./requirements.js";
+export { deleteWorkspaceProfile, listWorkspaceProfiles, readWorkspaceProfile, saveWorkspaceProfile, workspaceProfileDir, workspaceProfilesRoot, } from "./store.js";
+export { activateWorkspaceProfile, deactivateWorkspaceProfile, profileOverridesFromDefinition, type InstalledCapabilityNames, type WorkspaceProfileSubtree, } from "./activation.js";
+export { resolveActiveWorkspaceProfile, workspaceProfilePresetFor, type ResolveActiveWorkspaceProfileInput, } from "./resolve.js";

package/dist/profile/index.js

@@ -0,0 +1,7 @@
+export { SKILL_REPO_RE, WORKSPACE_PROFILE_NAME_RE, WorkspaceProfileRequirementsSchema, WorkspaceProfileSchema, } from "./types.js";
+export { CATALOG_REPO_RE, parseHumansManifest, readCatalogFromDir, sourceToRepoKey, } from "./catalog.js";
+export { addHumanRepo, humanRepoDir, humanReposRoot, listHumanRepoDetails, listHumanRepos, readAllHumanRepoEntries, removeHumanRepo, } from "./catalog-store.js";
+export { buildSkillInstallArgs, planProfileRequirements, summarizeSkillConflicts, } from "./requirements.js";
+export { deleteWorkspaceProfile, listWorkspaceProfiles, readWorkspaceProfile, saveWorkspaceProfile, workspaceProfileDir, workspaceProfilesRoot, } from "./store.js";
+export { activateWorkspaceProfile, deactivateWorkspaceProfile, profileOverridesFromDefinition, } from "./activation.js";
+export { resolveActiveWorkspaceProfile, workspaceProfilePresetFor, } from "./resolve.js";

package/dist/profile/requirements.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 数字人依赖：把 profile.requires 解析成「将要发生什么」的计划，供 UI 先展示、
+ * 用户确认后再执行。
+ *
+ * 为什么需要这一层：plugins/skills/mcp/agents 四个字段只是 force-enable 开关，
+ * 只能打开磁盘上已存在的能力。没有获取步骤，一个声明了 skill 的数字人在新机器上
+ * 会静默变成空壳（能力名写着，实际什么都没启用）。
+ *
+ * 安全边界：安装会克隆远程仓库并执行 `npx skills add`，属于运行远程代码。本模块
+ * 只负责**计划与校验**，从不自行执行；执行由 host 在拿到用户确认后驱动
+ * ({@link buildSkillInstallArgs} 给出确切 argv)。
+ */
+import type { SkillRequirement, WorkspaceProfileRequirements } from "./types.js";
+/** scanner 已发现的一条 skill（`plugin:skill` 形式代表插件来源）。 */
+export interface KnownSkill {
+    name: string;
+    source: "project" | "user" | "plugin" | "panel-app";
+}
+export interface SkillConflict {
+    name: string;
+    /** 已占用该名字的来源。安装到 project 根后它会被遮蔽。 */
+    existingSource: KnownSkill["source"];
+}
+export interface PlannedSkillInstall {
+    requirement: SkillRequirement;
+    /** 具名子集里确实缺失的那些；整仓安装（--all）时为 undefined。 */
+    missing?: string[];
+}
+export type MissingToolReason = "not-found" | "too-old";
+export interface MissingTool {
+    bin: string;
+    reason: MissingToolReason;
+    /** reason=too-old 时实际探到的版本。 */
+    found?: string;
+    /** reason=too-old 时 profile 要求的版本。 */
+    required?: string;
+    hint?: string;
+}
+export interface ProfileRequirementPlan {
+    skillInstalls: PlannedSkillInstall[];
+    missingTools: MissingTool[];
+    conflicts: SkillConflict[];
+    /** 是否有需要用户确认后执行的安装动作。 */
+    needsInstall: boolean;
+}
+export interface PlanRequirementsContext {
+    /** 当前 scanner 能看到的全部 skill。 */
+    installedSkills: readonly KnownSkill[];
+    /** 探测一个外部命令的版本输出；不存在返回 null。 */
+    toolProbe: (bin: string) => string | null;
+}
+/**
+ * 组装 `npx skills add` 的 argv。
+ *
+ * 两条硬约束：
+ * 1. **绝不加 `-g`** —— 全局安装落在 `~/.claude/skills`，而 scanner 只读
+ *    `<cwd>/.code-shell/skills`、`<cwd>/.agents/skills`、`~/.code-shell/skills`
+ *    三个根。装了却扫不到，就是又一个"配了等于没配"。
+ * 2. repo 与 skill 名各自占独立 argv 槽，不拼 shell 字符串；配合 schema 的
+ *    `SKILL_REPO_RE` 挡住 `--flag` / `../` / `;rm -rf` 一类注入。
+ */
+export declare function buildSkillInstallArgs(requirement: SkillRequirement): string[];
+/** 从 `--version` 输出里取第一个点分版本号。 */
+export declare function parseToolVersion(output: string): string | undefined;
+/** 按数字段比较；返回 <0 / 0 / >0。缺省段视为 0，故 "22" == "22.0.0"。 */
+export declare function compareToolVersions(a: string, b: string): number;
+/**
+ * 找出即将安装的裸名与已有 skill 的撞名。
+ *
+ * scanner 的去重是「先到先得且静默」——同名后来者直接被丢弃，不告警。所以要在
+ * 安装前把遮蔽关系摊开给用户看。插件 skill 带 `plugin:` 命名空间、走独立 dedup
+ * 集合，永远不会与裸名互相覆盖，故排除。
+ */
+export declare function summarizeSkillConflicts(incoming: readonly string[], installed: readonly KnownSkill[]): SkillConflict[];
+/** 纯函数：不碰磁盘、不起进程，全部输入经 context 注入，便于测试。 */
+export declare function planProfileRequirements(requires: WorkspaceProfileRequirements | undefined, context: PlanRequirementsContext): ProfileRequirementPlan;

package/dist/profile/requirements.js

@@ -0,0 +1,117 @@
+/**
+ * 组装 `npx skills add` 的 argv。
+ *
+ * 两条硬约束：
+ * 1. **绝不加 `-g`** —— 全局安装落在 `~/.claude/skills`，而 scanner 只读
+ *    `<cwd>/.code-shell/skills`、`<cwd>/.agents/skills`、`~/.code-shell/skills`
+ *    三个根。装了却扫不到，就是又一个"配了等于没配"。
+ * 2. repo 与 skill 名各自占独立 argv 槽，不拼 shell 字符串；配合 schema 的
+ *    `SKILL_REPO_RE` 挡住 `--flag` / `../` / `;rm -rf` 一类注入。
+ */
+export function buildSkillInstallArgs(requirement) {
+    const args = ["skills", "add", requirement.repo];
+    if (requirement.skills && requirement.skills.length > 0) {
+        // 具名子集：只装需要的，避免把整个仓库几十个 skill 都拖进项目。
+        args.push("--skill", requirement.skills.join(","), "--agent", "*", "--yes");
+    }
+    else {
+        // --all === --skill '*' --agent '*' -y
+        args.push("--all");
+    }
+    if (requirement.fullDepth)
+        args.push("--full-depth");
+    return args;
+}
+/** 从 `--version` 输出里取第一个点分版本号。 */
+export function parseToolVersion(output) {
+    const match = /(\d+(?:\.\d+){0,2})/.exec(output);
+    return match?.[1];
+}
+/** 按数字段比较；返回 <0 / 0 / >0。缺省段视为 0，故 "22" == "22.0.0"。 */
+export function compareToolVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * 找出即将安装的裸名与已有 skill 的撞名。
+ *
+ * scanner 的去重是「先到先得且静默」——同名后来者直接被丢弃，不告警。所以要在
+ * 安装前把遮蔽关系摊开给用户看。插件 skill 带 `plugin:` 命名空间、走独立 dedup
+ * 集合，永远不会与裸名互相覆盖，故排除。
+ */
+export function summarizeSkillConflicts(incoming, installed) {
+    const conflicts = [];
+    for (const name of incoming) {
+        const hit = installed.find((s) => s.source !== "plugin" && s.name === name);
+        if (hit)
+            conflicts.push({ name, existingSource: hit.source });
+    }
+    return conflicts;
+}
+/** 纯函数：不碰磁盘、不起进程，全部输入经 context 注入，便于测试。 */
+export function planProfileRequirements(requires, context) {
+    const skillInstalls = [];
+    const conflicts = [];
+    const missingTools = [];
+    for (const requirement of requires?.skills ?? []) {
+        if (requirement.skills && requirement.skills.length > 0) {
+            // 只有落在 project 根（安装目标）的同名 skill 才算"已具备"；命中更低优先级的
+            // user 根不算——那份会被这次安装遮蔽，属于要提示的冲突而非可跳过的满足。
+            const satisfied = (name) => context.installedSkills.some((s) => s.name === name && s.source === "project");
+            const missing = requirement.skills.filter((name) => !satisfied(name));
+            const shadowed = summarizeSkillConflicts(requirement.skills.filter((name) => !satisfied(name)), context.installedSkills);
+            conflicts.push(...shadowed);
+            // 具名子集全在了就不必再跑安装。
+            if (missing.length === 0)
+                continue;
+            // Keep the reviewed command and the executed argv aligned: if part of a
+            // multi-Skill requirement is already present, only pass the genuinely
+            // missing names to the installer. Re-sending the full authored subset
+            // could unnecessarily replace a working project Skill while the UI said
+            // it was only going to install the missing one.
+            skillInstalls.push({
+                requirement: { ...requirement, skills: missing },
+                missing,
+            });
+        }
+        else {
+            // 整仓安装无法预判会带来哪些名字，只能照跑；`skills add` 自身是幂等的。
+            skillInstalls.push({ requirement });
+        }
+    }
+    for (const tool of requires?.tools ?? []) {
+        const output = context.toolProbe(tool.bin);
+        if (output === null) {
+            missingTools.push({
+                bin: tool.bin,
+                reason: "not-found",
+                ...(tool.hint ? { hint: tool.hint } : {}),
+            });
+            continue;
+        }
+        if (!tool.minVersion)
+            continue;
+        const found = parseToolVersion(output);
+        if (found && compareToolVersions(found, tool.minVersion) < 0) {
+            missingTools.push({
+                bin: tool.bin,
+                reason: "too-old",
+                found,
+                required: tool.minVersion,
+                ...(tool.hint ? { hint: tool.hint } : {}),
+            });
+        }
+    }
+    return {
+        skillInstalls,
+        missingTools,
+        conflicts,
+        needsInstall: skillInstalls.length > 0,
+    };
+}

package/dist/profile/resolve.d.ts

@@ -0,0 +1,11 @@
+import type { SettingsManager } from "../settings/manager.js";
+import type { WorkspaceProfile } from "./types.js";
+export interface ResolveActiveWorkspaceProfileInput {
+    /** Session-bound digital-human profile; wins over the project default. */
+    sessionProfile?: string;
+    cwd: string;
+    settings: SettingsManager;
+}
+export declare function resolveActiveWorkspaceProfile(input: ResolveActiveWorkspaceProfileInput): WorkspaceProfile | undefined;
+/** preset 解析用的快照读取（优先级：agent.preset > 本值 > capability 默认）。 */
+export declare function workspaceProfilePresetFor(settings: SettingsManager, cwd: string): string | undefined;

package/dist/profile/resolve.js

@@ -0,0 +1,41 @@
+/**
+ * “当前激活的是谁 + 它的活字段”的唯一入口。除 overrides 折叠
+ * （读 settings 持久化快照，见 overlay.ts）之外，任何代码不得自行读
+ * profile.active 拼路径。Session 绑定的 profile 显式优先于项目默认，
+ * 让同一项目内的 PM / UI / 工程 Session 可以各自持有稳定数字人身份。
+ */
+import { logger } from "../logging/logger.js";
+import { readWorkspaceProfile } from "./store.js";
+function readSubtree(settings, cwd) {
+    try {
+        return settings.getForScope("project", cwd).profile;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveActiveWorkspaceProfile(input) {
+    const name = input.sessionProfile ?? readSubtree(input.settings, input.cwd)?.active;
+    if (!name)
+        return undefined;
+    let workspaceProfile;
+    try {
+        workspaceProfile = readWorkspaceProfile(name);
+    }
+    catch (error) {
+        logger.warn("profile.active_invalid", {
+            cat: "profile",
+            name,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    if (!workspaceProfile) {
+        logger.warn("profile.active_missing_from_library", { cat: "profile", name });
+    }
+    return workspaceProfile;
+}
+/** preset 解析用的快照读取（优先级：agent.preset > 本值 > capability 默认）。 */
+export function workspaceProfilePresetFor(settings, cwd) {
+    return readSubtree(settings, cwd)?.preset;
+}

package/dist/profile/store.d.ts

@@ -0,0 +1,17 @@
+import { type WorkspaceProfile, type WorkspaceProfileInput } from "./types.js";
+export declare function workspaceProfilesRoot(): string;
+/** 该数字人的根目录 —— 同时也是它可移植记忆层的 MemoryManager baseDir。 */
+export declare function workspaceProfileDir(name: string): string;
+export declare function readWorkspaceProfile(name: string): WorkspaceProfile | undefined;
+export declare function listWorkspaceProfiles(): WorkspaceProfile[];
+/**
+ * 原子写（tmp+rename），与 SettingsManager 的写法一致。
+ *
+ * 接收 `WorkspaceProfileInput`（而不是解析后的 `WorkspaceProfile`）：这个函数
+ * 本来就会 `parse()`，所以带 default 的字段由 schema 负责填。用输出类型标注会
+ * 让调用方必须手写它们，也会在 schema 新增带 default 的字段时把所有调用方一起
+ * 弄红——尽管运行时完全没变。
+ */
+export declare function saveWorkspaceProfile(profile: WorkspaceProfileInput): void;
+/** 删除前再次执行目录 containment 校验；不会跟随 profile 目录 symlink。 */
+export declare function deleteWorkspaceProfile(name: string): boolean;

package/dist/profile/store.js

@@ -0,0 +1,167 @@
+/**
+ * 全局数字人库：~/.code-shell/profiles/<name>/profile.json。
+ * 路径一律经 codeShellHome() 解析（CODE_SHELL_HOME / identity dataRoot 生效）。
+ * core 不内置任何领域 profile；样例见 docs/examples/workspace-profile-sample.md。
+ */
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { logger } from "../logging/logger.js";
+import { codeShellHome } from "../session/session-manager.js";
+import { WORKSPACE_PROFILE_NAME_RE, WorkspaceProfileSchema, } from "./types.js";
+export function workspaceProfilesRoot() {
+    return join(codeShellHome(), "profiles");
+}
+/** 该数字人的根目录 —— 同时也是它可移植记忆层的 MemoryManager baseDir。 */
+export function workspaceProfileDir(name) {
+    return join(workspaceProfilesRoot(), name);
+}
+function isContained(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function lstatIfPresent(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function checkedProfilesRoot(create = false) {
+    const root = workspaceProfilesRoot();
+    let info = lstatIfPresent(root);
+    if (!info && create) {
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        info = lstatSync(root);
+    }
+    if (!info)
+        return undefined;
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+        throw new Error(`Invalid workspace profiles root: ${root}`);
+    }
+    return root;
+}
+function checkedProfileDirectory(name, create = false) {
+    const root = checkedProfilesRoot(create);
+    if (!root)
+        return undefined;
+    const dir = join(root, name);
+    let info = lstatIfPresent(dir);
+    if (!info && create) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        info = lstatSync(dir);
+    }
+    if (!info)
+        return undefined;
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+        throw new Error(`Invalid workspace profile directory: ${dir}`);
+    }
+    if (!isContained(realpathSync(root), realpathSync(dir))) {
+        throw new Error(`Workspace profile directory escapes the profiles root: ${dir}`);
+    }
+    return dir;
+}
+function checkedProfileFile(name) {
+    const dir = checkedProfileDirectory(name);
+    if (!dir)
+        return undefined;
+    const path = join(dir, "profile.json");
+    const info = lstatIfPresent(path);
+    if (!info)
+        return undefined;
+    if (info.isSymbolicLink() || !info.isFile()) {
+        throw new Error(`Invalid workspace profile file: ${path}`);
+    }
+    return path;
+}
+export function readWorkspaceProfile(name) {
+    if (!WORKSPACE_PROFILE_NAME_RE.test(name))
+        return undefined;
+    const path = join(workspaceProfileDir(name), "profile.json");
+    try {
+        const checkedPath = checkedProfileFile(name);
+        if (!checkedPath)
+            return undefined;
+        return WorkspaceProfileSchema.parse(JSON.parse(readFileSync(checkedPath, "utf-8")));
+    }
+    catch (error) {
+        throw new Error(`Invalid workspace profile "${name}" at ${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+export function listWorkspaceProfiles() {
+    const root = checkedProfilesRoot();
+    if (!root)
+        return [];
+    const out = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            if (entry.isSymbolicLink()) {
+                logger.warn("profile.library_entry_invalid", {
+                    cat: "profile",
+                    name: entry.name,
+                    error: "symbolic links are not allowed",
+                });
+            }
+            continue;
+        }
+        try {
+            const profile = readWorkspaceProfile(entry.name);
+            if (profile)
+                out.push(profile);
+        }
+        catch (error) {
+            logger.warn("profile.library_entry_invalid", {
+                cat: "profile",
+                name: entry.name,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * 原子写（tmp+rename），与 SettingsManager 的写法一致。
+ *
+ * 接收 `WorkspaceProfileInput`（而不是解析后的 `WorkspaceProfile`）：这个函数
+ * 本来就会 `parse()`，所以带 default 的字段由 schema 负责填。用输出类型标注会
+ * 让调用方必须手写它们，也会在 schema 新增带 default 的字段时把所有调用方一起
+ * 弄红——尽管运行时完全没变。
+ */
+export function saveWorkspaceProfile(profile) {
+    const parsed = WorkspaceProfileSchema.parse(profile);
+    const dir = checkedProfileDirectory(parsed.name, true);
+    if (!dir)
+        throw new Error(`Could not create workspace profile directory for "${parsed.name}"`);
+    const path = join(dir, "profile.json");
+    const existing = lstatIfPresent(path);
+    if (existing) {
+        if (existing.isSymbolicLink() || !existing.isFile()) {
+            throw new Error(`Invalid workspace profile file: ${path}`);
+        }
+    }
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(parsed, null, 2)}\n`, {
+            encoding: "utf-8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        renameSync(tmp, path);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+/** 删除前再次执行目录 containment 校验；不会跟随 profile 目录 symlink。 */
+export function deleteWorkspaceProfile(name) {
+    if (!WORKSPACE_PROFILE_NAME_RE.test(name))
+        return false;
+    const dir = checkedProfileDirectory(name);
+    if (!dir)
+        return false;
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+}