@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/profile/activation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 激活/切换/关闭事务。原子性来源：整个 `profile` 子树一次
+ * saveProjectSetting 写入（内部 tmp+rename）——切换即全量替换，
+ * 永远不存在“旧的撤一半、新的写一半”。
+ * mainInstruction / portableMemory 不落 settings：settings 只记 active
+ * 名字（+ preset/overrides 快照），活字段由 resolve.ts 从库读取。
+ */
+import type { SettingsManager } from "../settings/manager.js";
+import type { CapabilityOverrides } from "../settings/schema.js";
+import type { WorkspaceProfile } from "./types.js";
+/** settings.profile 子树的形状（与 settings/schema.ts 的 zod 定义一致）。 */
+export interface WorkspaceProfileSubtree {
+    active: string;
+    preset?: string;
+    overrides?: CapabilityOverrides;
+}
+/**
+ * 当前机器上可见的能力清单，用于 `exclusiveCapabilities` 决定「要关掉哪些」。
+ * 由 host 注入（core 不扫描磁盘）。缺省即无法独占，退回并集语义。
+ */
+export interface InstalledCapabilityNames {
+    skills?: readonly string[];
+    plugins?: readonly string[];
+    mcp?: readonly string[];
+    agents?: readonly string[];
+}
+/**
+ * 把 profile 声明的能力展开为 override 快照；空 bucket 不落键。
+ *
+ * 默认只产出 `"on"`（并集：保证该有的在，不动用户开的）。profile 声明
+ * `exclusiveCapabilities` 且 host 给出 `installed` 时，未声明的同类能力显式
+ * 落 `"off"`，形成独占工作面。
+ */
+export declare function profileOverridesFromDefinition(profile: WorkspaceProfile, installed?: InstalledCapabilityNames): NonNullable<CapabilityOverrides>;
+export declare function activateWorkspaceProfile(settings: SettingsManager, name: string, cwd: string, installed?: InstalledCapabilityNames): WorkspaceProfile;
+export declare function deactivateWorkspaceProfile(settings: SettingsManager, cwd: string): void;

package/dist/profile/activation.js

@@ -0,0 +1,57 @@
+import { readWorkspaceProfile } from "./store.js";
+/**
+ * 把 profile 声明的能力展开为 override 快照；空 bucket 不落键。
+ *
+ * 默认只产出 `"on"`（并集：保证该有的在，不动用户开的）。profile 声明
+ * `exclusiveCapabilities` 且 host 给出 `installed` 时，未声明的同类能力显式
+ * 落 `"off"`，形成独占工作面。
+ */
+// 返回 NonNullable：`CapabilityOverrides` 自身以 `.optional()` 结尾（settings 里
+// 整个 key 可以缺失），但这个函数**总是**构造一个对象字面量，永不返回 undefined。
+// 沿用可空别名会迫使每个调用方（含断言 `overrides.skills` 的测试）先做一次不可能
+// 为真的 null 检查。
+export function profileOverridesFromDefinition(profile, installed) {
+    const exclusive = profile.exclusiveCapabilities === true;
+    const bucket = (declared, available) => {
+        const entries = {};
+        for (const name of declared)
+            entries[name] = "on";
+        if (exclusive && available) {
+            const claimed = new Set(declared);
+            for (const name of available) {
+                if (!claimed.has(name))
+                    entries[name] = "off";
+            }
+        }
+        return Object.keys(entries).length > 0 ? entries : undefined;
+    };
+    const plugins = bucket(profile.plugins, installed?.plugins);
+    const skills = bucket(profile.skills, installed?.skills);
+    const mcp = bucket(profile.mcp, installed?.mcp);
+    const agents = bucket(profile.agents, installed?.agents);
+    return {
+        ...(plugins ? { plugins } : {}),
+        ...(skills ? { skills } : {}),
+        ...(mcp ? { mcp } : {}),
+        ...(agents ? { agents } : {}),
+    };
+}
+export function activateWorkspaceProfile(settings, name, cwd, installed) {
+    const profile = readWorkspaceProfile(name);
+    if (!profile) {
+        throw new Error(`Workspace profile "${name}" not found in the global library`);
+    }
+    const subtree = {
+        active: profile.name,
+        // A digital human contributes its role, capabilities, and memory. The
+        // CodeShell runtime base is a host concern and must not vary with imported
+        // definitions that happen to carry a legacy basePreset value.
+        preset: "general",
+        overrides: profileOverridesFromDefinition(profile, installed),
+    };
+    settings.saveProjectSetting("profile", subtree, cwd);
+    return profile;
+}
+export function deactivateWorkspaceProfile(settings, cwd) {
+    settings.deleteProjectSetting("profile", cwd);
+}

package/dist/profile/catalog-store.d.ts

@@ -0,0 +1,77 @@
+import { type CatalogEntry, type CatalogTeam } from "./catalog.js";
+export interface RegisteredHumanRepo {
+    /** `owner/repo` */
+    repo: string;
+    addedAt: number;
+}
+export interface HumanRepoListEntry extends RegisteredHumanRepo {
+    /** 该仓库当前提供的数字人数量。 */
+    count: number;
+    /** 读取过程中的问题（坏定义、缺 manifest）。 */
+    errors: string[];
+    cloned: boolean;
+}
+export declare function humanReposRoot(): string;
+export declare function humanRepoDir(repo: string): string;
+export declare function listHumanRepos(): RegisteredHumanRepo[];
+/**
+ * 注册并克隆一个数字人仓库。已存在则拉取更新。
+ *
+ * 克隆是网络+磁盘写入操作，调用方应已取得用户确认。
+ */
+export declare function addHumanRepo(repo: string): Promise<{
+    ok: true;
+    entry: HumanRepoListEntry;
+} | {
+    ok: false;
+    error: string;
+}>;
+/**
+ * Swap a validated staging tree into place.
+ *
+ * Ordering matters for crash safety: promote FIRST (rename staging over a
+ * now-absent `dir`), and only retire the old tree around it. The previous
+ * `dir → retired` then `staging → dir` sequence left no tree at `dir` at all if
+ * the process died in between, and nothing scanned for `.retired-*` on startup,
+ * so the UI showed "尚未克隆" with the data still on disk under a name nobody
+ * looked for. Here the only window is one where BOTH the old tree (at `retired`)
+ * and the new tree (at `staging`) still exist, and `reclaimOrphanedTrees`
+ * cleans up whatever is left over on the next call.
+ */
+declare function promoteStagedRepo(staging: string, dir: string): void;
+/**
+ * Recover from a crash during a previous swap.
+ *
+ * If `dir` is missing but a `.retired-*` sibling exists, a process died between
+ * retiring the old tree and promoting the new one. Restore the newest retired
+ * tree rather than leaving the repo looking un-cloned, then drop the rest.
+ * Runs under the repo lock, so no concurrent swap can be mid-flight.
+ */
+declare function reclaimOrphanedTrees(dir: string): void;
+/**
+ * Crash-safety internals, exposed for tests only.
+ *
+ * `promoteStagedRepo`/`reclaimOrphanedTrees` implement the swap-and-recover
+ * protocol. Exercising them through `addHumanRepo` would require network git, so
+ * the recovery cases (interrupted swap, stale retired trees) are tested here
+ * directly. Not part of the package's public surface.
+ */
+export declare const __testables: {
+    promoteStagedRepo: typeof promoteStagedRepo;
+    reclaimOrphanedTrees: typeof reclaimOrphanedTrees;
+};
+export declare function removeHumanRepo(repo: string): void;
+/** 注册表 + 每个仓库的读取结果，供设置页展示。 */
+export declare function listHumanRepoDetails(): HumanRepoListEntry[];
+/**
+ * 所有已注册仓库提供的数字人。
+ *
+ * 同名定义按注册顺序先到先得，并记一条冲突说明——静默覆盖会让用户以为装的是
+ * 另一个仓库的版本。
+ */
+export declare function readAllHumanRepoEntries(): {
+    entries: CatalogEntry[];
+    teams: CatalogTeam[];
+    errors: string[];
+};
+export {};

package/dist/profile/catalog-store.js

@@ -0,0 +1,346 @@
+/**
+ * 已注册的数字人仓库：注册表 + 克隆缓存 + 读取。
+ *
+ * 与插件市场并列的一等分发通道。数字人不必先成为插件——它有自己的定义格式和
+ * 导入/导出原语，仓库只是把「一批定义」打包分发。
+ *
+ * 磁盘布局：
+ *   ~/.code-shell/human-repos.json        —— 注册表（owner/repo 列表）
+ *   ~/.code-shell/human-repos/<key>/      —— 各仓库的浅克隆
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import { codeShellHome } from "../session/session-manager.js";
+import { acquireLockOnPath, mutateJsonFile } from "../utils/file-mutex.js";
+// gitFetchAndReset is deliberately NOT used any more: updating in place is what
+// destroyed the last-known-good tree on a bad upstream commit. Updates clone to
+// a staging dir and swap (see addHumanRepo).
+import { gitClone, githubRepoToCloneUrl } from "../plugins/gitOps.js";
+import { CATALOG_REPO_RE, readCatalogFromDir, sourceToRepoKey, } from "./catalog.js";
+const MAX_REPOS = 32;
+export function humanReposRoot() {
+    return join(codeShellHome(), "human-repos");
+}
+function registryPath() {
+    return join(codeShellHome(), "human-repos.json");
+}
+export function humanRepoDir(repo) {
+    return join(humanReposRoot(), sourceToRepoKey(repo));
+}
+export function listHumanRepos() {
+    try {
+        // Missing or corrupt registry reads as "no repos" — never fatal.
+        return parseRegistry(readFileSync(registryPath(), "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function parseRegistry(raw) {
+    if (raw === undefined)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.repos))
+            return [];
+        return parsed.repos
+            .filter((r) => !!r &&
+            typeof r === "object" &&
+            typeof r.repo === "string" &&
+            CATALOG_REPO_RE.test(r.repo))
+            .map((r) => ({ repo: r.repo, addedAt: Number(r.addedAt) || 0 }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Serialize add/update/remove of ONE repo across processes.
+ *
+ * Distinct from the registry lock inside `updateRegistry`: that one only guards
+ * the JSON file, and is held for a moment. This one spans the whole mutation —
+ * capacity check, directory swap, registry write — so two processes cannot both
+ * decide the repo is absent and clone into the same path, and cannot both slip
+ * past MAX_REPOS. Keyed per repo, so unrelated repos still install in parallel.
+ *
+ * The lock file lives next to the clones and is never the clone dir itself
+ * (proper-lockfile creates `<path>.lock`, which must not collide with a tree we
+ * rename over).
+ */
+function withHumanRepoLock(repo, run) {
+    const root = humanReposRoot();
+    mkdirSync(root, { recursive: true });
+    const lockTarget = join(root, `.${sourceToRepoKey(repo)}.repo-lock`);
+    if (!existsSync(lockTarget))
+        writeFileSync(lockTarget, "", { mode: 0o600 });
+    // Lock the marker FILE, not humanReposRoot(): a directory lock would serialize
+    // unrelated repos and deadlock against the registry lock taken below.
+    // 30s covers a swap that waits behind another process's publish step.
+    const release = acquireLockOnPath(lockTarget, 30_000);
+    try {
+        return run();
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Read-modify-write the registry under a cross-process lock.
+ *
+ * add/remove used to be `listHumanRepos()` in the caller followed by a bare
+ * `writeFileSync` of the whole array. Two windows (or a window plus an agent)
+ * mutating different repos would each write back their own stale snapshot, so
+ * one of the entries silently disappeared. The single-window UI operation lock
+ * did not help, because it does not span processes.
+ */
+function updateRegistry(change) {
+    mkdirSync(codeShellHome(), { recursive: true });
+    mutateJsonFile(registryPath(), {
+        parse: parseRegistry,
+        serialize: (repos) => `${JSON.stringify({ repos }, null, 2)}\n`,
+        mutation: (current) => ({ value: change(current) }),
+        mode: 0o600,
+    });
+}
+/**
+ * 注册并克隆一个数字人仓库。已存在则拉取更新。
+ *
+ * 克隆是网络+磁盘写入操作，调用方应已取得用户确认。
+ */
+export async function addHumanRepo(repo) {
+    if (!CATALOG_REPO_RE.test(repo)) {
+        return { ok: false, error: `"${repo}" 不是合法的仓库地址（应为 owner/repo）` };
+    }
+    const dir = humanRepoDir(repo);
+    mkdirSync(humanReposRoot(), { recursive: true });
+    // Clone into a private staging dir FIRST, outside the lock — this is the slow
+    // network step and must not hold the lock for the duration. Both the add and
+    // the update path stage: cloning straight into `dir` let two processes race
+    // into the same path, and the loser's `rmSync(dir)` then deleted the winner's
+    // perfectly good clone.
+    const staging = `${dir}.staging-${process.pid}-${randomUUID()}`;
+    try {
+        const cloned = await gitClone(githubRepoToCloneUrl(repo), staging, { full: true });
+        if (!cloned.ok) {
+            // Only ever removes OUR staging dir (finally below); `dir` is untouched.
+            return { ok: false, error: explainGitFailure(cloned.error, repo) };
+        }
+        const staged = readCatalogFromDir(staging, repo);
+        if (staged.entries.length === 0 && staged.errors.length > 0) {
+            // A repo that yields nothing usable is a mistake worth surfacing now
+            // rather than leaving an empty row in the list. On update this also keeps
+            // the last known good tree in place.
+            const hadPrevious = existsSync(dir);
+            return {
+                ok: false,
+                error: hadPrevious
+                    ? `更新 ${repo} 失败，已保留上一个可用版本：${staged.errors[0]}`
+                    : staged.errors[0],
+            };
+        }
+        // Publish under the repo lock: capacity check, directory swap and registry
+        // write must be one critical section. Checking MAX_REPOS before the lock
+        // let N processes each observe 31 repos and all proceed past the cap.
+        const published = withHumanRepoLock(repo, () => {
+            const current = listHumanRepos();
+            const alreadyRegistered = current.some((r) => r.repo === repo);
+            if (current.length >= MAX_REPOS && !alreadyRegistered) {
+                return { ok: false, error: `最多只能添加 ${MAX_REPOS} 个数字人仓库` };
+            }
+            promoteStagedRepo(staging, dir);
+            updateRegistry((repos) => [
+                ...repos.filter((r) => r.repo !== repo),
+                { repo, addedAt: Date.now() },
+            ]);
+            return { ok: true };
+        });
+        if (!published.ok)
+            return published;
+        return {
+            ok: true,
+            entry: {
+                repo,
+                addedAt: Date.now(),
+                count: staged.entries.length,
+                errors: staged.errors,
+                cloned: true,
+            },
+        };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+/**
+ * Swap a validated staging tree into place.
+ *
+ * Ordering matters for crash safety: promote FIRST (rename staging over a
+ * now-absent `dir`), and only retire the old tree around it. The previous
+ * `dir → retired` then `staging → dir` sequence left no tree at `dir` at all if
+ * the process died in between, and nothing scanned for `.retired-*` on startup,
+ * so the UI showed "尚未克隆" with the data still on disk under a name nobody
+ * looked for. Here the only window is one where BOTH the old tree (at `retired`)
+ * and the new tree (at `staging`) still exist, and `reclaimOrphanedTrees`
+ * cleans up whatever is left over on the next call.
+ */
+function promoteStagedRepo(staging, dir) {
+    reclaimOrphanedTrees(dir);
+    if (!existsSync(dir)) {
+        renameSync(staging, dir);
+        return;
+    }
+    const retired = `${dir}.retired-${process.pid}-${randomUUID()}`;
+    renameSync(dir, retired);
+    try {
+        renameSync(staging, dir);
+    }
+    catch (err) {
+        // Promotion failed — put the good tree back before surfacing the error.
+        try {
+            renameSync(retired, dir);
+        }
+        catch {
+            // Best effort; the retired copy is still on disk for manual recovery.
+        }
+        throw err;
+    }
+    rmSync(retired, { recursive: true, force: true });
+}
+/**
+ * Recover from a crash during a previous swap.
+ *
+ * If `dir` is missing but a `.retired-*` sibling exists, a process died between
+ * retiring the old tree and promoting the new one. Restore the newest retired
+ * tree rather than leaving the repo looking un-cloned, then drop the rest.
+ * Runs under the repo lock, so no concurrent swap can be mid-flight.
+ */
+function reclaimOrphanedTrees(dir) {
+    const parent = dirname(dir);
+    const prefix = `${basename(dir)}.retired-`;
+    let orphans;
+    try {
+        orphans = readdirSync(parent).filter((name) => name.startsWith(prefix));
+    }
+    catch {
+        return;
+    }
+    if (orphans.length === 0)
+        return;
+    orphans.sort();
+    if (!existsSync(dir)) {
+        const restore = orphans.pop();
+        try {
+            renameSync(join(parent, restore), dir);
+        }
+        catch {
+            // Fall through: leave it for manual recovery rather than deleting data.
+        }
+    }
+    for (const stale of orphans) {
+        rmSync(join(parent, stale), { recursive: true, force: true });
+    }
+}
+/**
+ * Crash-safety internals, exposed for tests only.
+ *
+ * `promoteStagedRepo`/`reclaimOrphanedTrees` implement the swap-and-recover
+ * protocol. Exercising them through `addHumanRepo` would require network git, so
+ * the recovery cases (interrupted swap, stale retired trees) are tested here
+ * directly. Not part of the package's public surface.
+ */
+export const __testables = { promoteStagedRepo, reclaimOrphanedTrees };
+/**
+ * Turn a raw git failure into something a user can act on.
+ *
+ * gitOps deliberately returns the full command line (`git clone --depth 1
+ * --filter=blob:none … exited 128: …`) because it serves low-level callers.
+ * Pasting that into an "add a repo" box tells the user nothing about the actual
+ * problem — usually just a typo in the name.
+ */
+function explainGitFailure(error, repo) {
+    if (/repository not found|could not read from remote|remote: not found/i.test(error)) {
+        return `找不到仓库 ${repo}。请检查拼写，并确认它是公开仓库。`;
+    }
+    if (/authentication failed|permission denied|terminal prompts disabled/i.test(error)) {
+        return `无权访问 ${repo}。私有仓库需要先配置 git 凭据。`;
+    }
+    if (/could not resolve host|network is unreachable|timed out|operation timed out/i.test(error)) {
+        return `无法连接 GitHub，请检查网络后重试。`;
+    }
+    if (error.startsWith("GIT_NOT_FOUND")) {
+        // Already a written, actionable message from gitOps.
+        return error;
+    }
+    // Unrecognized: keep the tail (the actual stderr) and drop the command line,
+    // so the user sees the cause rather than our argv.
+    const tail = error.includes(": ") ? error.slice(error.lastIndexOf(": ") + 2) : error;
+    return `克隆 ${repo} 失败：${tail.trim() || "未知错误"}`;
+}
+export function removeHumanRepo(repo) {
+    if (!CATALOG_REPO_RE.test(repo))
+        throw new Error("invalid digital-human repo");
+    // Same repo lock as add/update: otherwise a remove can delete the tree a
+    // concurrent add just published, leaving a registered repo with no clone.
+    withHumanRepoLock(repo, () => {
+        // Filter inside the registry lock so a concurrent add of a DIFFERENT repo
+        // is not lost.
+        updateRegistry((repos) => repos.filter((r) => r.repo !== repo));
+        const dir = humanRepoDir(repo);
+        rmSync(dir, { recursive: true, force: true });
+        // Drop any tree a crashed swap left behind, so a later re-add does not
+        // resurrect the old contents via reclaimOrphanedTrees.
+        reclaimOrphanedTrees(dir);
+        rmSync(dir, { recursive: true, force: true });
+    });
+}
+/** 注册表 + 每个仓库的读取结果，供设置页展示。 */
+export function listHumanRepoDetails() {
+    return listHumanRepos().map((registered) => {
+        const dir = humanRepoDir(registered.repo);
+        if (!existsSync(dir)) {
+            return { ...registered, count: 0, errors: ["尚未克隆"], cloned: false };
+        }
+        const read = readCatalogFromDir(dir, registered.repo);
+        return { ...registered, count: read.entries.length, errors: read.errors, cloned: true };
+    });
+}
+/**
+ * 所有已注册仓库提供的数字人。
+ *
+ * 同名定义按注册顺序先到先得，并记一条冲突说明——静默覆盖会让用户以为装的是
+ * 另一个仓库的版本。
+ */
+export function readAllHumanRepoEntries() {
+    const entries = [];
+    const teams = [];
+    const errors = [];
+    const seen = new Map();
+    const seenTeams = new Map();
+    for (const { repo } of listHumanRepos()) {
+        const dir = humanRepoDir(repo);
+        if (!existsSync(dir))
+            continue;
+        const read = readCatalogFromDir(dir, repo);
+        errors.push(...read.errors);
+        for (const entry of read.entries) {
+            const owner = seen.get(entry.profile.name);
+            if (owner) {
+                errors.push(`"${entry.profile.name}" 同时存在于 ${owner} 与 ${repo}，已采用前者`);
+                continue;
+            }
+            seen.set(entry.profile.name, repo);
+            entries.push(entry);
+        }
+        for (const team of read.teams) {
+            const owner = seenTeams.get(team.id);
+            if (owner) {
+                errors.push(`团队 "${team.id}" 同时存在于 ${owner} 与 ${repo}，已采用前者`);
+                continue;
+            }
+            seenTeams.set(team.id, repo);
+            teams.push(team);
+        }
+    }
+    return { entries, teams, errors };
+}

package/dist/profile/catalog.d.ts

@@ -0,0 +1,54 @@
+import { type WorkspaceProfile } from "./types.js";
+/** `owner/repo`，与 SKILL_REPO_RE 同源，供仓库地址复用。 */
+export declare const CATALOG_REPO_RE: RegExp;
+export interface HumansManifestEntry {
+    name: string;
+    label?: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+}
+export interface HumansManifest {
+    name?: string;
+    description?: string;
+    humans: HumansManifestEntry[];
+    teams: HumansManifestTeam[];
+}
+/**
+ * A team shipped by a repo. Same shape as a locally-authored team minus `mode`
+ * (the dead enum): `lead` picks the coordinator, `playbook` is the collaboration
+ * rules injected into its opening briefing.
+ */
+export interface HumansManifestTeam {
+    id: string;
+    name: string;
+    description?: string;
+    members: string[];
+    lead?: string;
+    playbook?: string;
+}
+export interface CatalogTeam extends HumansManifestTeam {
+    sourceRepo: string;
+}
+export interface CatalogEntry {
+    profile: WorkspaceProfile;
+    /** 来源仓库 `owner/repo`，用于展示与去重。 */
+    sourceRepo: string;
+    category?: string;
+    tags: string[];
+}
+export interface CatalogReadResult {
+    entries: CatalogEntry[];
+    teams: CatalogTeam[];
+    /** 逐条目的失败原因；一个坏定义不该让整个仓库不可用。 */
+    errors: string[];
+}
+/**
+ * `owner/repo` → 一个安全的目录段。小写化保证同一仓库不同大小写写法命中同一份
+ * 缓存；斜杠换成 `-` 后仍需通过 SAFE_SEGMENT_RE，杜绝路径逃逸。
+ */
+export declare function sourceToRepoKey(repo: string): string;
+/** 解析 humans.json。缺 humans 数组按空目录处理；JSON 坏了才抛。 */
+export declare function parseHumansManifest(raw: string): HumansManifest;
+/** 读取一个已克隆的数字人仓库目录。 */
+export declare function readCatalogFromDir(dir: string, sourceRepo: string): CatalogReadResult;