@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/settings/schema.js

@@ -2,7 +2,35 @@
  * Settings schema with Zod validation.
  */
 import { z } from "zod";
-import { DEFAULT_WORKTREE_BRANCH_PREFIX, isValidWorktreeBranchPrefix, normalizeWorktreeBranchPrefix, } from "../git/worktree/slug.js";
+import { WorkspaceSourceBindingSchema } from "../sources/types.js";
+const DEFAULT_WORKTREE_BRANCH_PREFIX = "worktree/";
+const McpToolNameListSchema = z
+    .array(z
+    .string()
+    .min(1)
+    .max(256)
+    .refine((value) => !value.includes("\0"), "Invalid MCP tool name"))
+    .max(256);
+function isValidWorktreeBranchPrefix(prefix) {
+    const raw = prefix.trim();
+    if (!raw || raw.startsWith("/") || raw.includes("//"))
+        return false;
+    if (raw.includes("..") || raw.includes("@{"))
+        return false;
+    if (/[\x00-\x20~^:?*[\]\\]/.test(raw))
+        return false;
+    const value = raw.endsWith("/") ? raw.slice(0, -1) : raw;
+    return (value.length > 0 &&
+        value
+            .split("/")
+            .every((part) => Boolean(part) && !part.startsWith(".") && !part.endsWith(".") && !part.endsWith(".lock")));
+}
+function normalizeWorktreeBranchPrefix(prefix) {
+    const raw = prefix.trim();
+    if (!isValidWorktreeBranchPrefix(raw))
+        throw new Error(`Invalid worktree branch prefix: ${prefix}`);
+    return raw.endsWith("/") ? raw : `${raw}/`;
+}
 /**
  * Tri-state project capability overlay. Lives in PROJECT settings only and
  * layers over the global baseline (disabledSkills / disabledPlugins /
@@ -21,6 +49,8 @@ export const CapabilityOverridesSchema = z
     agents: z.record(CapabilityOverrideSchema).optional(),
     mcp: z.record(CapabilityOverrideSchema).optional(),
     builtin: z.record(CapabilityOverrideSchema).optional(),
+    /** Per-project Pet capability preferences layered over the user baseline. */
+    pet: z.record(CapabilityOverrideSchema).optional(),
     /**
      * Per-hook overlay for PLUGIN-provided hooks, keyed by
      * `pluginHookKey()` (`<plugin>:<RawEvent>:<command>`). Finer-grained
@@ -42,7 +72,9 @@ export const SettingsSchema = z
     agent: z
         .object({
         // Use z.string() instead of z.enum() to allow custom presets registered via registerPreset()
-        preset: z.string().default("terminal-coding"),
+        // No domain preset is baked into core. Installed capabilities may
+        // contribute a host default.
+        preset: z.string().optional(),
         enabledBuiltinTools: z.array(z.string()).default([]),
         disabledBuiltinTools: z.array(z.string()).default([]),
         customSystemPrompt: z.string().optional(),
@@ -65,6 +97,27 @@ export const SettingsSchema = z
      * Can also be disabled via env var `DISABLE_AUTOUPDATER=1`.
      */
     autoUpdates: z.boolean().default(true),
+    /**
+     * Pet (Mimi) global-view preferences.
+     */
+    pet: z
+        .object({
+        /**
+         * Show external Codex CLI/App sessions in the Pet global view. When off,
+         * the host does not scan or tail Codex session files at all. Default off.
+         */
+        showExternalCodexSessions: z.boolean().default(false),
+        /** Same, for external Claude Code CLI sessions. Default off. */
+        showExternalClaudeSessions: z.boolean().default(false),
+        /**
+         * Auto-extract durable memories + an event-journal entry from each closed
+         * Mimi topic segment. When off, segment closure still archives the model
+         * context (so it cannot grow without bound) but writes no journal/memory.
+         * Default on.
+         */
+        memoryAutoExtract: z.boolean().default(true),
+    })
+        .default({}),
     /**
      * Image generation is a general capability, decoupled from LLM providers
      * (TODO 7.1): a vendor may use different keys/endpoints/models for chat vs
@@ -267,18 +320,23 @@ export const SettingsSchema = z
         // Codex-style on/off switch. Absent or true → connected; only
         // literal false disables. Filtered in MCPManager.connectAll.
         enabled: z.boolean().optional(),
+        allowedTools: McpToolNameListSchema.optional(),
+        disabledTools: McpToolNameListSchema.optional(),
     })))
         .default({}),
     /**
-     * User supplements for PLUGIN-provided MCP servers, keyed by the server's
-     * `<plugin>:<server>` name. Layered onto the plugin config at merge time
-     * (mergePluginMcpServers). Only env/credential fields are accepted —
-     * command/args/url/transport are intentionally absent and `.strict()`
-     * rejects them, so a plugin update is never shadowed by a stale copy.
+     * User policy/supplements for PLUGIN-provided MCP servers, keyed by the
+     * server's `<plugin>:<server>` name. Layered onto the plugin config at merge
+     * time (mergePluginMcpServers). Only server/tool policy + env/credential
+     * fields are accepted — command/args/url/transport are intentionally absent and
+     * `.strict()` rejects them, so an update is never shadowed by a stale copy.
      */
     mcpServerOverrides: z
         .record(z
         .object({
+        enabled: z.boolean().optional(),
+        allowedTools: McpToolNameListSchema.optional(),
+        disabledTools: McpToolNameListSchema.optional(),
         env: z.record(z.string()).optional(),
         envVars: z.array(z.string()).optional(),
         credentialRef: z.string().optional(),
@@ -301,6 +359,19 @@ export const SettingsSchema = z
      * names (no colon suffix). See scanSkills(opts.disabledPlugins).
      */
     disabledPlugins: z.array(z.string()).default([]),
+    /** Globally disabled Panel Apps, including their declared tools and bundled Skills. */
+    disabledPanelApps: z.array(z.string()).default([]),
+    /**
+     * Explicit project binding for installed Panel Apps. Installed apps form a
+     * global catalog, but only IDs in this project-owned list contribute panel
+     * UI, Agent tools, bundled Skills, or project-scoped storage.
+     */
+    panelAppBindings: z.array(z.string()).default([]),
+    /**
+     * Legacy per-project Panel App policy. `on` is read as an explicit binding
+     * during migration; new writes use panelAppBindings.
+     */
+    panelAppOverrides: z.record(CapabilityOverrideSchema).default({}),
     /**
      * Sub-agent role names (the `name` in .code-shell/agents/*.md) to
      * hide from the registry. A disabled role is filtered out at load
@@ -315,6 +386,26 @@ export const SettingsSchema = z
      * capability-assembly time. Optional — absence === everything inherits.
      */
     capabilityOverrides: CapabilityOverridesSchema,
+    /**
+     * 由 WorkspaceProfile 激活事务整体拥有的子树（profile/activation.ts）。
+     * 激活/切换 = 原子全量重写本子树；关闭 = 删除本子树。
+     * `overrides` 是 profile 声明展开的 force-enable 快照，折叠时排在
+     * 用户手写 capabilityOverrides 之下（用户按 key 永远赢，见 overlay.ts
+     * 的 effectiveProjectOverrides）。只存在于 PROJECT settings。
+     */
+    profile: z
+        .object({
+        active: z.string(),
+        preset: z.string().optional(),
+        overrides: CapabilityOverridesSchema,
+    })
+        .optional(),
+    /**
+     * Workspace 数据源绑定（只存 ref/scope/readPolicy，绝不存 secret）。
+     * 语义见 docs/todo/workspace-datasource-binding-adr.md §1.2。
+     * 只存在于 PROJECT settings。
+     */
+    sources: z.array(WorkspaceSourceBindingSchema).optional(),
     /**
      * Feature flags overlay: a map of flag name → boolean that overrides the
      * compiled-in defaults (see settings/feature-flags.ts FEATURE_FLAGS).
@@ -349,24 +440,6 @@ export const SettingsSchema = z
         ignoreGitBoundary: z.boolean().default(false),
     })
         .default({}),
-    arena: z
-        .object({
-        participants: z
-            .array(z.union([
-            // Short form: just a model pool key
-            z.string(),
-            // Full form: explicit config (backward compat)
-            z.object({
-                name: z.string(),
-                model: z.string(),
-                provider: z.string().optional(),
-                apiKey: z.string().optional(),
-                baseUrl: z.string().optional(),
-            }),
-        ]))
-            .default([]),
-    })
-        .default({}),
     search: z
         .object({
         provider: z.enum(["serper", "tavily", "searxng"]).default("serper"),

package/dist/skills/scanner.d.ts

@@ -1,10 +1,11 @@
 /**
  * Skill scanner — discovers <base>/<name>/SKILL.md files from project
  * `.code-shell/skills`, project `.agents/skills`, user `.code-shell/skills`,
- * and installed plugins. Mirrors Claude Code's
+ * installed plugins, and schema-v2 Panel Apps. Mirrors Claude Code's
  * `loadSkillsFromSkillsDir` (skills/loadSkillsDir.ts:407) plus plugin
  * integration (utils/plugins/pluginLoader.ts).
  */
+type SkillSource = "project" | "user" | "plugin" | "panel-app";
 export interface SkillDefinition {
     /** Directory name; authoritative regardless of frontmatter.name. */
     name: string;
@@ -15,7 +16,7 @@ export interface SkillDefinition {
     /** Absolute path to the SKILL.md file. */
     filePath: string;
     /** Where the skill was loaded from. */
-    source: "project" | "user" | "plugin";
+    source: SkillSource;
 }
 /**
  * Options accepted by scanSkills. Both filters are applied after the
@@ -34,6 +35,8 @@ export interface SkillDefinition {
 export interface ScanSkillsOptions {
     disabledSkills?: string[];
     disabledPlugins?: string[];
+    /** Include skills owned by Panel Apps disabled or unbound for this project. */
+    includeDisabledPanelApps?: boolean;
     /**
      * Hard skill isolation for sub-agents. When set, ONLY skills whose name is
      * in this list survive — every other skill is dropped from the result
@@ -46,3 +49,4 @@ export interface ScanSkillsOptions {
 }
 export declare function scanSkills(cwd: string, opts?: ScanSkillsOptions): SkillDefinition[];
 export declare function invalidateSkillCache(): void;
+export {};

package/dist/skills/scanner.js

@@ -1,16 +1,20 @@
 /**
  * Skill scanner — discovers <base>/<name>/SKILL.md files from project
  * `.code-shell/skills`, project `.agents/skills`, user `.code-shell/skills`,
- * and installed plugins. Mirrors Claude Code's
+ * installed plugins, and schema-v2 Panel Apps. Mirrors Claude Code's
  * `loadSkillsFromSkillsDir` (skills/loadSkillsDir.ts:407) plus plugin
  * integration (utils/plugins/pluginLoader.ts).
  */
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { homedir } from "node:os";
 import { memoize } from "../utils/memoize.js";
 import { parseFrontmatter, coerceDescription } from "./frontmatter.js";
 import { installedPluginsPath, readInstalledPlugins } from "../plugins/installedPlugins.js";
+import { PANEL_APP_MANIFEST_FILE, PanelAppManifest } from "../panel-apps/manifest.js";
+import { panelAppsRegistryPath, panelAppsRoot } from "../panel-apps/paths.js";
+import { isPanelAppBound, resolvePanelAppBindingPolicy, resolvePanelAppBindingProjectPath, } from "../panel-apps/bindings.js";
+import { SettingsManager } from "../settings/manager.js";
 function userHome() {
     // Honor process.env.HOME so tests (and shell overrides) can redirect the
     // user-skills lookup. node:os homedir() reads from getpwuid and ignores
@@ -49,6 +53,19 @@ function readSkillFile(skillFile) {
         throw e;
     }
 }
+function resolveContainedPath(root, candidate) {
+    try {
+        const realRoot = realpathSync(root);
+        const realCandidate = realpathSync(candidate);
+        const rel = relative(realRoot, realCandidate);
+        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+            return null;
+        return realCandidate;
+    }
+    catch {
+        return null;
+    }
+}
 function buildSkillFromFile(filePath, defaultName, source, raw, namePrefix) {
     const { frontmatter, body } = parseFrontmatter(raw);
     const fmName = typeof frontmatter.name === "string" ? frontmatter.name : undefined;
@@ -114,14 +131,17 @@ function scanInstalledPlugins(results) {
             const skillsDir = join(entry.installPath, "skills");
             if (!existsSync(skillsDir))
                 continue;
+            const resolvedSkillsDir = resolveContainedPath(entry.installPath, skillsDir);
+            if (!resolvedSkillsDir)
+                continue;
             let dirEntries;
             try {
-                dirEntries = readdirSync(skillsDir, { withFileTypes: true });
+                dirEntries = readdirSync(resolvedSkillsDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
             }
             catch (e) {
                 if (isInaccessible(e)) {
                     // eslint-disable-next-line no-console
-                    console.warn(`[skills] cannot read ${skillsDir}: ${e.message}`);
+                    console.warn(`[skills] cannot read ${resolvedSkillsDir}: ${e.message}`);
                     continue;
                 }
                 throw e;
@@ -132,7 +152,26 @@ function scanInstalledPlugins(results) {
                 const namespacedName = `${pluginName}:${dirent.name}`;
                 if (pluginSeen.has(namespacedName))
                     continue;
-                const skillFile = join(skillsDir, dirent.name, "SKILL.md");
+                const skillDir = resolveContainedPath(resolvedSkillsDir, join(resolvedSkillsDir, dirent.name));
+                if (!skillDir)
+                    continue;
+                try {
+                    if (!statSync(skillDir).isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const skillFile = resolveContainedPath(skillDir, join(skillDir, "SKILL.md"));
+                if (!skillFile)
+                    continue;
+                try {
+                    if (!statSync(skillFile).isFile())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
                 const raw = readSkillFile(skillFile);
                 if (raw === null)
                     continue;
@@ -142,14 +181,98 @@ function scanInstalledPlugins(results) {
         }
     }
 }
+function scanInstalledPanelApps(results) {
+    const root = panelAppsRoot();
+    if (!existsSync(root))
+        return;
+    let installedIds;
+    try {
+        const registry = JSON.parse(readFileSync(panelAppsRegistryPath(), "utf-8"));
+        if (registry.version !== 1 || !Array.isArray(registry.apps))
+            return;
+        installedIds = new Set(registry.apps
+            .map((entry) => entry &&
+            typeof entry === "object" &&
+            "id" in entry &&
+            typeof entry.id === "string" &&
+            /^[a-z][a-z0-9-]{0,63}$/.test(entry.id)
+            ? entry.id
+            : null)
+            .filter((id) => id !== null));
+    }
+    catch {
+        return;
+    }
+    let appDirectories;
+    try {
+        appDirectories = readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && installedIds.has(entry.name))
+            .sort((left, right) => left.name.localeCompare(right.name));
+    }
+    catch (error) {
+        if (isInaccessible(error))
+            return;
+        throw error;
+    }
+    const seen = new Set(results.map((skill) => skill.name));
+    for (const directory of appDirectories) {
+        const appRoot = join(root, directory.name);
+        let manifest;
+        try {
+            manifest = PanelAppManifest.parse(JSON.parse(readFileSync(join(appRoot, PANEL_APP_MANIFEST_FILE), "utf-8")));
+        }
+        catch {
+            continue;
+        }
+        if (manifest.id !== directory.name || manifest.schemaVersion !== 2 || !manifest.agent)
+            continue;
+        for (const relativeEntry of manifest.agent.skills) {
+            const segments = relativeEntry.split("/");
+            const defaultName = segments[2];
+            if (!defaultName)
+                continue;
+            const namespacedName = `${manifest.id}:${defaultName}`;
+            if (seen.has(namespacedName))
+                continue;
+            const skillFile = resolveContainedPath(appRoot, join(appRoot, ...relativeEntry.split("/")));
+            if (!skillFile)
+                continue;
+            try {
+                if (!statSync(skillFile).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const raw = readSkillFile(skillFile);
+            if (raw === null)
+                continue;
+            results.push(buildSkillFromFile(skillFile, defaultName, "panel-app", raw, manifest.id));
+            seen.add(namespacedName);
+        }
+    }
+}
 function scanOnce(cwd) {
     const results = [];
     const seen = new Set();
     const seenBaseDirs = new Set();
     scanDirBases(bases(cwd), results, seen, seenBaseDirs);
     scanInstalledPlugins(results);
+    scanInstalledPanelApps(results);
     return results;
 }
+function installedPanelAppsMtime() {
+    return [panelAppsRoot(), panelAppsRegistryPath()]
+        .map((path) => {
+        try {
+            return statSync(path).mtimeMs.toString();
+        }
+        catch {
+            return "0";
+        }
+    })
+        .join("|");
+}
 function installedPluginsMtime() {
     const p = installedPluginsPath();
     try {
@@ -181,28 +304,56 @@ function skillsDirsMtime(cwd) {
     })
         .join("|");
 }
-const memoized = memoize(scanOnce, (cwd) => `${cwd}\0${userHome()}\0${installedPluginsMtime()}\0${skillsDirsMtime(cwd)}`);
+const memoized = memoize(scanOnce, (cwd) => `${cwd}\0${userHome()}\0${installedPluginsMtime()}\0${installedPanelAppsMtime()}\0${skillsDirsMtime(cwd)}`);
+function panelAppBindingPolicy(cwd) {
+    try {
+        const projectPath = resolvePanelAppBindingProjectPath(cwd);
+        const settings = new SettingsManager(projectPath, "full");
+        return resolvePanelAppBindingPolicy(settings.getForScope("user"), settings.getForScope("project", projectPath), Boolean(projectPath));
+    }
+    catch {
+        // Binding failures must not leak every installed Panel App Skill into the
+        // project prompt. Fail closed with an empty binding set.
+        return resolvePanelAppBindingPolicy(undefined, undefined, false);
+    }
+}
 export function scanSkills(cwd, opts) {
     const all = memoized(cwd);
     const disabledSkills = opts?.disabledSkills;
     const disabledPlugins = opts?.disabledPlugins;
     const skillAllowlist = opts?.skillAllowlist;
+    const panelPolicy = opts?.includeDisabledPanelApps ? null : panelAppBindingPolicy(cwd);
     const hasSkillFilter = disabledSkills && disabledSkills.length > 0;
     const hasPluginFilter = disabledPlugins && disabledPlugins.length > 0;
     // An allowlist of [] is meaningful (no skills at all), so check for
     // presence with !== undefined, not truthiness/length.
     const hasAllowlist = skillAllowlist !== undefined;
-    if (!hasSkillFilter && !hasPluginFilter && !hasAllowlist)
-        return all;
+    if (!hasSkillFilter && !hasPluginFilter && !hasAllowlist) {
+        if (panelPolicy === null)
+            return all;
+        const hasUnboundPanelSkill = all.some((skill) => {
+            if (skill.source !== "panel-app")
+                return false;
+            const colon = skill.name.indexOf(":");
+            return colon <= 0 || !isPanelAppBound(skill.name.slice(0, colon), panelPolicy);
+        });
+        if (!hasUnboundPanelSkill)
+            return all;
+    }
     const skillSet = hasSkillFilter ? new Set(disabledSkills) : null;
     const pluginSet = hasPluginFilter ? new Set(disabledPlugins) : null;
     const allowSet = hasAllowlist ? new Set(skillAllowlist) : null;
     return all.filter((s) => {
+        if (panelPolicy && s.source === "panel-app") {
+            const colon = s.name.indexOf(":");
+            if (colon <= 0 || !isPanelAppBound(s.name.slice(0, colon), panelPolicy))
+                return false;
+        }
         if (allowSet && !allowSet.has(s.name))
             return false;
         if (skillSet && skillSet.has(s.name))
             return false;
-        if (pluginSet) {
+        if (pluginSet && s.source === "plugin") {
             // Use indexOf, not split — skill names may theoretically contain
             // more colons after the first; the namespace boundary is the
             // first ":" only.

package/dist/sources/adapter.d.ts

@@ -0,0 +1,14 @@
+/** provider 无关的连接器边界（ADR §4）。core 不出现任何具体 provider 名。 */
+import type { SourceContent, SourceDefinition, SourceResourceMeta, SourceScope } from "./types.js";
+export interface ConnectorAdapter {
+    kind: string;
+    listScopes(definition: SourceDefinition): Promise<SourceScope[]>;
+    listResources(definition: SourceDefinition, scopeId: string): Promise<SourceResourceMeta[]>;
+    read(definition: SourceDefinition, resourceId: string, options: {
+        maxBytes: number;
+        signal?: AbortSignal;
+        cwd?: string;
+    }): Promise<SourceContent>;
+}
+export declare function registerConnectorAdapter(adapter: ConnectorAdapter): void;
+export declare function connectorAdapterFor(kind: string): ConnectorAdapter | undefined;

package/dist/sources/adapter.js

@@ -0,0 +1,7 @@
+const registry = new Map();
+export function registerConnectorAdapter(adapter) {
+    registry.set(adapter.kind, adapter);
+}
+export function connectorAdapterFor(kind) {
+    return registry.get(kind);
+}

package/dist/sources/adapters/local-files.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectorAdapter } from "../adapter.js";
+import type { SourceDefinition, SourceResourceMeta } from "../types.js";
+export declare const LOCAL_FILES_SOURCE_ID = "project-uploads";
+export declare function uploadsDir(cwd: string): string;
+/** Validate a write/delete basename and resolve it inside the workspace uploads directory. */
+export declare function resolveUploadTarget(cwd: string, name: string): string;
+export declare function localFilesSourceFor(cwd: string): SourceDefinition;
+export declare const localFilesAdapter: ConnectorAdapter;
+/** cwd 维度的文件列举；隐式源不在 definition 里携带路径。 */
+export declare function listLocalFiles(cwd: string): SourceResourceMeta[];

package/dist/sources/adapters/local-files.js

@@ -0,0 +1,127 @@
+/**
+ * 上传文件源（ADR §4.3）：每个 workspace 隐式自带，不进全局 catalog。
+ * 文件在 ${cwd}/.code-shell/uploads/ 内；读取前规范化 resourceId，
+ * 并校验消解 symlink 后的真实路径仍在 uploads 目录内。
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { truncateUtf8Bytes } from "../truncate-utf8.js";
+export const LOCAL_FILES_SOURCE_ID = "project-uploads";
+export function uploadsDir(cwd) {
+    return join(cwd, ".code-shell", "uploads");
+}
+/** Validate a write/delete basename and resolve it inside the workspace uploads directory. */
+export function resolveUploadTarget(cwd, name) {
+    let decoded = name;
+    try {
+        for (let pass = 0; pass < 3; pass += 1) {
+            const next = decodeURIComponent(decoded);
+            if (next === decoded)
+                break;
+            decoded = next;
+        }
+    }
+    catch {
+        throw new Error(`invalid upload name: ${name}`);
+    }
+    if (!name ||
+        name !== decoded ||
+        name.startsWith(".") ||
+        name.includes("/") ||
+        name.includes("\\") ||
+        name.includes("\0") ||
+        basename(name) !== name) {
+        throw new Error(`invalid upload name: ${name}`);
+    }
+    const root = resolve(uploadsDir(cwd));
+    const target = resolve(root, name);
+    if (dirname(target) !== root)
+        throw new Error(`invalid upload name: ${name}`);
+    return target;
+}
+export function localFilesSourceFor(cwd) {
+    return {
+        id: LOCAL_FILES_SOURCE_ID,
+        kind: "local-files",
+        label: "项目文件",
+        description: `本 workspace 上传的文件（${uploadsDir(cwd)}）`,
+        adapterConfig: {},
+        enabled: true,
+    };
+}
+function canonicalResourceId(resourceId) {
+    let decoded = resourceId;
+    try {
+        for (let pass = 0; pass < 3; pass += 1) {
+            const next = decodeURIComponent(decoded);
+            if (next === decoded)
+                break;
+            decoded = next;
+        }
+    }
+    catch {
+        throw new Error(`invalid local-files resource path: ${resourceId}`);
+    }
+    if (decoded.length === 0 ||
+        decoded.includes("\0") ||
+        decoded.includes("\\") ||
+        isAbsolute(decoded) ||
+        /^[a-zA-Z]:[\\/]/.test(decoded)) {
+        throw new Error(`invalid local-files resource path: ${resourceId}`);
+    }
+    const canonical = normalize(decoded);
+    if (canonical === "." || canonical === ".." || canonical.startsWith(`..${sep}`)) {
+        throw new Error(`resource escapes uploads dir: ${resourceId}`);
+    }
+    return canonical.split(sep).join("/");
+}
+function resolveInsideUploads(cwd, resourceId) {
+    const root = realpathSync(uploadsDir(cwd));
+    const canonicalId = canonicalResourceId(resourceId);
+    const candidate = resolve(root, ...canonicalId.split("/"));
+    const real = realpathSync(candidate);
+    if (real !== root && !real.startsWith(`${root}${sep}`)) {
+        throw new Error(`resource escapes uploads dir: ${resourceId}`);
+    }
+    const finalId = relative(root, real).split(sep).join("/");
+    if (!finalId || finalId === ".." || finalId.startsWith("../")) {
+        throw new Error(`invalid local-files resource path: ${resourceId}`);
+    }
+    return { path: real, resourceId: finalId };
+}
+export const localFilesAdapter = {
+    kind: "local-files",
+    async listScopes() {
+        return [{ id: "uploads", label: "上传文件" }];
+    },
+    async listResources() {
+        throw new Error("use listLocalFiles(cwd) — local-files listing is cwd-scoped");
+    },
+    async read(_definition, resourceId, options) {
+        if (!options.cwd) {
+            throw new Error("local-files read requires cwd");
+        }
+        const resolved = resolveInsideUploads(options.cwd, resourceId);
+        const buffer = readFileSync(resolved.path);
+        const truncated = truncateUtf8Bytes(buffer, options.maxBytes);
+        return {
+            resourceId: resolved.resourceId,
+            ...truncated,
+        };
+    },
+};
+/** cwd 维度的文件列举；隐式源不在 definition 里携带路径。 */
+export function listLocalFiles(cwd) {
+    const directory = uploadsDir(cwd);
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((entry) => ({
+        id: entry.name,
+        scopeId: "uploads",
+        name: entry.name,
+        sizeBytes: statSync(join(directory, entry.name)).size,
+    }));
+}

package/dist/sources/adapters/mcp-resource.d.ts

@@ -0,0 +1,17 @@
+/** MCP resource 包装 adapter：MCP 只是 kind 之一，不塞 mcpServers（ADR §1/§4）。 */
+import type { ConnectorAdapter } from "../adapter.js";
+interface McpResourceInfo {
+    uri: string;
+    name?: string;
+    description?: string;
+    serverName: string;
+}
+interface McpLike {
+    listResources(server?: string, signal?: AbortSignal): Promise<McpResourceInfo[]>;
+    readResource(server: string, uri: string, signal?: AbortSignal): Promise<string>;
+}
+type McpManagerFactory = () => McpLike | Promise<McpLike>;
+export declare function createMcpResourceAdapter(getManager: McpManagerFactory): ConnectorAdapter;
+/** 生产默认：方法首次执行时才加载真 MCPManager，避免静态模块环。 */
+export declare function defaultMcpResourceAdapter(): ConnectorAdapter;
+export {};