@steerable/agent-shell 0.6.30 → 0.6.32

package/dist/host/runtime.js

@@ -28,6 +28,7 @@ import { createVisibleTerminalExec } from './visible-terminal-exec.js';
 import { createJsonStore } from '../json-store.js';
 import { bindWorkspaceSkillRoots } from '../local-backend/skill-loader.js';
 import { getChatAttachmentsDir } from '../attachments.js';
+import { ensureChatWorkspace } from '../project-home.js';
 import { recordInsightTurn } from '../insights/record.js';
 import { llmService } from '../llm/index.js';
 import { getPackAssemblies, } from './pack-assembly.js';
@@ -150,6 +151,12 @@ export async function createHostRuntime(options) {
         toolRouter,
         worktreeService,
         resolveChatProject: resolveChatProjectRoot,
+        resolveChatWorkspaceRoot: async (chatId) => {
+            const project = await resolveChatProjectRoot(chatId);
+            if (project)
+                return project.folderPath;
+            return ensureChatWorkspace(chatId);
+        },
         broadcast,
     });
     toolRouter.setTaskServices({ taskService, worktreeService });
@@ -204,10 +211,16 @@ export async function createHostRuntime(options) {
             void startHostSidecar({
                 store: defaultStore,
                 toolRouter,
-                resolveProjectRoot: async (chatId) => (await localBackendRouter.resolveChatProject(chatId))?.folderPath ?? null,
+                resolveProjectRoot: async (chatId) => localBackendRouter.resolveChatWorkspaceRoot(chatId),
                 // 项目模式下文件读写被围栏在项目目录内；会话附件目录是额外放行的
                 // 只读根，保证用户上传的文件即使在项目会话里也能被 agent 读回。
-                resolveAdditionalReadRoots: (chatId) => [getChatAttachmentsDir(chatId)],
+                resolveAdditionalReadRoots: async (chatId) => {
+                    const project = await localBackendRouter.resolveChatProject(chatId);
+                    return [
+                        getChatAttachmentsDir(chatId),
+                        ...(project?.sourceFolders ?? []),
+                    ];
+                },
                 approvalHandler: approvalBridge.handler,
                 askUserHandler: askUserBridge.handler,
                 // P2b: resume 时 sidecar 把记录里的读证据推给 LocalExecutor 的

package/dist/local-backend/router.d.ts

@@ -98,15 +98,19 @@ export declare class LocalBackendRouter {
     private runTitleGenInBackground;
     /**
      * 解析当前对话绑定的项目（项目模式）。chat 没绑项目、项目已被删除、或
-     * 注册表未注入时都返回 null（= 不沙箱，行为同旧版本）。
-     *
-     * Public: main.ts 的反向通道（reverse-tools.ts）经它给 CoreLoop 路径的
-     * 工具调用补上 projectRoot 围栏。
+     * 注册表未注入时都返回 null。无项目对话的可写根见
+     * {@link LocalBackendRouter.resolveChatWorkspaceRoot}。
      */
     resolveChatProject(chatId: string): Promise<{
         name: string;
         folderPath: string;
+        sourceFolders: string[];
     } | null>;
+    /**
+     * 本对话的可写根：绑了项目用项目家目录，否则在
+     * `Documents/<应用名>/conversations/<chatId>/` 建对话工作区。
+     */
+    resolveChatWorkspaceRoot(chatId: string): Promise<string>;
     /**
      * 解析本轮生效的智能体：人设前言、技能勾选、工具策略同源于这一次解析。
      *

package/dist/local-backend/router.js

@@ -38,12 +38,18 @@ import { detectInterruptedTurn } from './interrupted-helper.js';
 import { dropCurrentUserMessage } from './history-helper.js';
 import { parseImageAttachments, processImageAttachments } from '../image-attachment.js';
 import { loadProjectRuleFiles } from '../project-rules.js';
+import { allocateProjectHome, ensureChatWorkspace, ensureProjectHome, } from '../project-home.js';
 import { registerLiveStream, getLiveStream, removeLiveStream } from './live-stream.js';
 import { beginPackTurnObservers, collectPackExecWritableRoots, collectPackForcedSkillVars, collectPackWorldState, } from './pack-turn-hooks.js';
 import { matchPackBackendRoute } from './pack-backend-routes.js';
 import { collectTurnFiles } from './turn-files.js';
 import { resolveMentionedPaths } from './mentioned-paths.js';
 import { getAuthProvider } from '../auth/index.js';
+function parseSourceFolders(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'string' && item.trim() !== '');
+}
 /**
  * 把 CoreLoop/LLM 的底层错误翻译成适合直接显示在助手消息里的中文提示。
  * 原始错误仍保存在 messageMetadata.completionReason 里，便于排查。
@@ -431,9 +437,17 @@ export class LocalBackendRouter {
             if (method === 'POST') {
                 const payload = this.toRecord(request.body);
                 try {
+                    const name = String(payload.name || '');
+                    const sourceFolders = parseSourceFolders(payload.sourceFolders);
+                    let folderPath = typeof payload.folderPath === 'string' ? payload.folderPath.trim() : '';
+                    if (!folderPath) {
+                        folderPath = allocateProjectHome(name);
+                        ensureProjectHome(folderPath);
+                    }
                     const project = registry.create({
-                        name: String(payload.name || ''),
-                        folderPath: String(payload.folderPath || ''),
+                        name,
+                        folderPath,
+                        sourceFolders,
                     });
                     return { status: 200, data: { success: true, project } };
                 }
@@ -458,6 +472,9 @@ export class LocalBackendRouter {
                     const project = registry.update(projectId, {
                         name: typeof payload.name === 'string' ? payload.name : undefined,
                         folderPath: typeof payload.folderPath === 'string' ? payload.folderPath : undefined,
+                        sourceFolders: payload.sourceFolders === undefined
+                            ? undefined
+                            : parseSourceFolders(payload.sourceFolders),
                     });
                     return { status: 200, data: { success: true, project } };
                 }
@@ -1732,7 +1749,7 @@ export class LocalBackendRouter {
         }
         // 正文里提到的路径能否点击打开：渲染层把行内代码里「像路径」的字面量
         // 批量送来，这里落地成绝对路径并 stat 验证，只有真实存在的才回。相对
-        // 路径按对话绑定的项目根解析，无项目时按 home（同 exec 缺省 cwd 的回落）。
+        // 路径按对话绑定的项目根解析，无项目时按对话工作区。
         if (method === 'POST' && pathname === '/api/v2/local/resolve-paths') {
             const payload = this.toRecord(request.body);
             const candidates = Array.isArray(payload.candidates)
@@ -1742,7 +1759,9 @@ export class LocalBackendRouter {
                 return { status: 200, data: { resolved: [] } };
             }
             const chatId = typeof payload.chatId === 'string' ? payload.chatId : '';
-            const baseDir = (chatId ? (await this.resolveChatProject(chatId))?.folderPath : null) ?? os.homedir();
+            const baseDir = chatId
+                ? await this.resolveChatWorkspaceRoot(chatId)
+                : os.homedir();
             const resolved = await resolveMentionedPaths({ candidates, baseDir });
             return { status: 200, data: { resolved } };
         }
@@ -2173,10 +2192,8 @@ export class LocalBackendRouter {
     }
     /**
      * 解析当前对话绑定的项目（项目模式）。chat 没绑项目、项目已被删除、或
-     * 注册表未注入时都返回 null（= 不沙箱，行为同旧版本）。
-     *
-     * Public: main.ts 的反向通道（reverse-tools.ts）经它给 CoreLoop 路径的
-     * 工具调用补上 projectRoot 围栏。
+     * 注册表未注入时都返回 null。无项目对话的可写根见
+     * {@link LocalBackendRouter.resolveChatWorkspaceRoot}。
      */
     async resolveChatProject(chatId) {
         const projectId = (await this.store.getChat(chatId))?.projectId;
@@ -2185,7 +2202,21 @@ export class LocalBackendRouter {
         const project = this.toolRouter.projectRegistry?.get(projectId);
         if (!project)
             return null;
-        return { name: project.name, folderPath: project.folderPath };
+        return {
+            name: project.name,
+            folderPath: project.folderPath,
+            sourceFolders: project.sourceFolders ?? [],
+        };
+    }
+    /**
+     * 本对话的可写根：绑了项目用项目家目录，否则在
+     * `Documents/<应用名>/conversations/<chatId>/` 建对话工作区。
+     */
+    async resolveChatWorkspaceRoot(chatId) {
+        const project = await this.resolveChatProject(chatId);
+        if (project)
+            return project.folderPath;
+        return ensureChatWorkspace(chatId);
     }
     /**
      * 解析本轮生效的智能体：人设前言、技能勾选、工具策略同源于这一次解析。
@@ -2375,13 +2406,19 @@ export class LocalBackendRouter {
         // 都追加）。硬围栏在 ToolRouter/LocalExecutor，这里让模型事先知道边界，
         // 减少越界尝试。
         const chatProject = await this.resolveChatProject(chatId);
+        const workspaceRoot = chatProject
+            ? chatProject.folderPath
+            : await this.resolveChatWorkspaceRoot(chatId);
         if (chatProject) {
             systemPrompt +=
-                `\n\n【项目模式】当前对话绑定项目「${chatProject.name}」，根目录：${chatProject.folderPath}\n` +
-                    `你的文件读写（local_read_file / local_write_file）和命令执行（local_exec_shell）都被限制在该目录内：` +
-                    `文件路径越界会被拒绝；命令默认在项目根目录下运行，显式指定的 cwd 越界也会被拒绝。` +
-                    `请一律使用项目目录内的路径（相对路径按项目根目录解析）。` +
-                    `如确需访问项目外的文件，向用户说明该限制，并请其把文件放入项目目录后再操作。`;
+                `\n\n【项目模式】当前对话绑定项目「${chatProject.name}」，家目录：${chatProject.folderPath}\n` +
+                    `你的文件写入（local_write_file）和命令执行（local_exec_shell）都被限制在该家目录内：` +
+                    `写入路径越界会被拒绝；命令默认在家目录下运行，显式指定的 cwd 越界也会被拒绝。` +
+                    (chatProject.sourceFolders.length > 0
+                        ? `另有源文件夹（只读）：${chatProject.sourceFolders.join('、')}。`
+                        : '') +
+                    `请一律使用项目目录内的路径（相对路径按家目录解析）。` +
+                    `如确需访问项目外的文件，向用户说明该限制，或请其在项目里附加为源文件夹。`;
             // W6-5 + W6-7a：项目级规则文件（AGENTS.md / CLAUDE.md）是不可信输入，
             // 仅在用户显式信任该项目后才注入模型上下文——未信任一律不读取、不注入
             // （打开恶意仓库时，一段构造的规则文件不能劫持 agent）。信任状态持久化、
@@ -2399,6 +2436,14 @@ export class LocalBackendRouter {
                 }
             }
         }
+        else {
+            systemPrompt +=
+                `\n\n【对话工作区】当前对话没有绑定项目。工作区：${workspaceRoot}\n` +
+                    `你的文件写入（local_write_file）和命令执行（local_exec_shell）都被限制在该目录内：` +
+                    `写入路径越界会被拒绝；命令默认在工作区下运行，显式指定的 cwd 越界也会被拒绝。` +
+                    `请一律使用工作区内的路径（相对路径按工作区解析）。` +
+                    `用户若要把对话绑到已有项目，可在输入框上方选择项目。`;
+        }
         // @引用的历史对话（payload.referencedChatIds）：把被引用对话的最近消息
         // 摘录注入为 user 消息，放在本对话历史之前。
         const referencedChatMessages = await this.buildReferencedChatContextMessages(payload, chatId);
@@ -2853,16 +2898,18 @@ export class LocalBackendRouter {
         // spec (default.harness.yaml) is the single source of truth for
         // maxRounds / maxToolErrors, and an explicit request param overrides it.
         // W4-2: per-exec sandbox for shell tool calls, default-on. Writable
-        // roots = the chat's project root (project mode) — unbound chats get an
-        // empty list, so writes confine to system scratch dirs only.
+        // roots = 项目家目录，或无项目时 Documents/<应用>/conversations/<chatId>。
         // `execPolicy: 'full'`（输入框「完整权限」）关闭这一层，让 mkdir
-        // Downloads 这类项目外写入不再被 Seatbelt 拦成 Operation not permitted。
+        // Downloads 这类工作区外写入不再被 Seatbelt 拦成 Operation not permitted。
         const chatProject = await this.resolveChatProject(chatId);
+        const workspaceRoot = chatProject
+            ? chatProject.folderPath
+            : await this.resolveChatWorkspaceRoot(chatId);
         const execSandbox = buildExecSandbox([
             // 场景包声明的每会话可写根（如文档包在项目根之外落盘产物的
             // 工作区）。
             ...collectPackExecWritableRoots(chatId),
-            ...(chatProject ? [chatProject.folderPath] : []),
+            workspaceRoot,
         ], { policy: parseExecPolicy(payload.execPolicy) });
         // W4-1: approval algebra, host mode — every tool call is gated by the
         // Electron approval UI over the reverse channel. The durable scope
@@ -2905,7 +2952,7 @@ export class LocalBackendRouter {
         const turnStartedAtMs = Date.now();
         const turnFileRoots = [
             ...collectPackExecWritableRoots(chatId),
-            ...(chatProject ? [chatProject.folderPath] : []),
+            workspaceRoot,
         ];
         try {
             const coreLoopOptions = {
@@ -3195,7 +3242,7 @@ export class LocalBackendRouter {
                 roots: turnFileRoots,
                 sinceMs: turnStartedAtMs,
                 actions: executedActions,
-                projectRoot: chatProject?.folderPath ?? null,
+                projectRoot: workspaceRoot,
             });
         }
         catch (turnFilesErr) {

package/dist/local-backend/task-service.d.ts

@@ -55,6 +55,11 @@ export interface TaskServiceDeps {
         name: string;
         folderPath: string;
     } | null>;
+    /**
+     * 无项目对话的可写根（Documents/<应用>/conversations/<chatId>）。
+     * 测试可不传，围栏回落为仅 scratch。
+     */
+    resolveChatWorkspaceRoot?: (chatId: string) => Promise<string>;
     /** 任务终态 / 推理过程广播（renderer 任务面板与右侧过程栏）。 */
     broadcast?: (eventName: 'task-updated' | 'task-process', payload: Record<string, unknown>) => void;
     /** 测试缝：替换真实流驱动（默认 streamCoreLoopTurn）。 */

package/dist/local-backend/task-service.js

@@ -272,8 +272,12 @@ export class TaskService {
         const settings = llmService.getSettings();
         const project = await this.deps.resolveChatProject(chatId);
         // 4.6b 整合：worktree 任务的围栏根 = worktree 路径（更紧——任务摸不到
-        // 主检出）；否则沿用项目根。writableRoots 同理收窄。
-        const fenceRoot = worktreePath ?? project?.folderPath ?? null;
+        // 主检出）；否则项目家目录，再否则对话工作区。
+        const fenceRoot = worktreePath ??
+            project?.folderPath ??
+            (this.deps.resolveChatWorkspaceRoot
+                ? await this.deps.resolveChatWorkspaceRoot(chatId)
+                : null);
         const execSandbox = buildExecSandbox(fenceRoot ? [fenceRoot] : []);
         const approval = process.env.STEERABLE_APPROVAL === '0'
             ? undefined

package/dist/native-folder-dialog.d.ts

@@ -0,0 +1,14 @@
+export interface NativeFolderDialogResult {
+    canceled: boolean;
+    filePaths: string[];
+}
+export interface NativeFolderDialogOptions {
+    title?: string;
+}
+export interface NativeFolderDialogDeps {
+    platform?: NodeJS.Platform;
+    run?: (cmd: string, args: readonly string[]) => Promise<{
+        stdout: string;
+    }>;
+}
+export declare function selectNativeDirectory(options?: NativeFolderDialogOptions, deps?: NativeFolderDialogDeps): Promise<NativeFolderDialogResult>;

package/dist/native-folder-dialog.js

@@ -0,0 +1,62 @@
+/**
+ * BS 宿主没有 Electron `dialog.showOpenDialog`（`ELECTRON_RUN_AS_NODE=1`）。
+ * 本模块用各平台系统选择器弹出「选文件夹」，返回与 preload
+ * `local.selectDirectory` 相同的 `{ canceled, filePaths }`。
+ *
+ * 取消、无 DISPLAY、命令不存在都记为 canceled，让 UI 走手动输入路径。
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+function sanitizePrompt(title) {
+    const raw = (title ?? '选择文件夹').replace(/[\r\n]+/g, ' ').slice(0, 80);
+    return raw.replace(/["\\]/g, '');
+}
+function picked(stdout) {
+    const folder = stdout.trim().replace(/[/\\]+$/, '');
+    return folder ? { canceled: false, filePaths: [folder] } : { canceled: true, filePaths: [] };
+}
+export async function selectNativeDirectory(options = {}, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const run = deps.run ?? ((cmd, args) => execFileAsync(cmd, [...args]));
+    const title = sanitizePrompt(options.title);
+    try {
+        if (platform === 'darwin') {
+            const { stdout } = await run('osascript', [
+                '-e',
+                `POSIX path of (choose folder with prompt "${title}")`,
+            ]);
+            return picked(stdout);
+        }
+        if (platform === 'win32') {
+            const escaped = title.replace(/'/g, "''");
+            const script = [
+                'Add-Type -AssemblyName System.Windows.Forms',
+                '$d = New-Object System.Windows.Forms.FolderBrowserDialog',
+                `$d.Description = '${escaped}'`,
+                'if ($d.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { $d.SelectedPath }',
+            ].join('; ');
+            const { stdout } = await run('powershell.exe', ['-NoProfile', '-Command', script]);
+            return picked(stdout);
+        }
+        try {
+            const { stdout } = await run('zenity', [
+                '--file-selection',
+                '--directory',
+                `--title=${title}`,
+            ]);
+            return picked(stdout);
+        }
+        catch {
+            const { stdout } = await run('kdialog', [
+                '--getexistingdirectory',
+                process.env.HOME || '/',
+                title,
+            ]);
+            return picked(stdout);
+        }
+    }
+    catch {
+        return { canceled: true, filePaths: [] };
+    }
+}

package/dist/project-home.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 项目默认家目录：`Documents/<应用名>/<项目名>/`。
+ *
+ * 新建项目不再等于「选一个已有文件夹」——项目是带名字的容器，
+ * 家目录由本模块分配并创建。用户另加的源文件夹是附加只读根，
+ * 不替代这个家目录。
+ */
+/** 把 `~` / `~/…` 展开成绝对路径；其它输入原样（已 trim）。 */
+export declare function expandUserPath(folder: string): string;
+export declare function sanitizeProjectDirName(name: string): string;
+/** `Documents/<应用显示名>`：该应用下所有托管项目的父目录。 */
+export declare function appProjectsRoot(options?: {
+    documentsDir?: string;
+    appFolderName?: string;
+}): string;
+/**
+ * 为项目名分配尚未占用的家目录路径（不落盘）。
+ * 已存在同名目录时追加 `-2`、`-3`…
+ */
+export declare function allocateProjectHome(projectName: string, options?: {
+    documentsDir?: string;
+    appFolderName?: string;
+    exists?: (folderPath: string) => boolean;
+}): string;
+export declare function ensureProjectHome(folderPath: string): void;
+/** 无项目对话的工作区子目录名（与托管项目家目录并列，避免撞名）。 */
+export declare const CHAT_WORKSPACES_DIR = "conversations";
+/**
+ * 无项目对话的工作区路径：`Documents/<应用名>/conversations/<chatId>/`。
+ * 不落盘；调用方用 {@link ensureChatWorkspace} 创建。
+ */
+export declare function chatWorkspacePath(chatId: string, options?: {
+    documentsDir?: string;
+    appFolderName?: string;
+}): string;
+/** 确保无项目对话工作区存在，返回绝对路径。 */
+export declare function ensureChatWorkspace(chatId: string, options?: {
+    documentsDir?: string;
+    appFolderName?: string;
+}): string;

package/dist/project-home.js

@@ -0,0 +1,74 @@
+/**
+ * 项目默认家目录：`Documents/<应用名>/<项目名>/`。
+ *
+ * 新建项目不再等于「选一个已有文件夹」——项目是带名字的容器，
+ * 家目录由本模块分配并创建。用户另加的源文件夹是附加只读根，
+ * 不替代这个家目录。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getBrand } from './brand.js';
+import { getDocumentsDir } from './runtime.js';
+const UNSAFE_DIR_CHARS = /[\\/:*?"<>|]/g;
+/** 把 `~` / `~/…` 展开成绝对路径；其它输入原样（已 trim）。 */
+export function expandUserPath(folder) {
+    const trimmed = folder.trim();
+    if (trimmed === '~')
+        return os.homedir();
+    if (trimmed.startsWith('~/') || trimmed.startsWith('~\\')) {
+        return path.join(os.homedir(), trimmed.slice(2));
+    }
+    return trimmed;
+}
+export function sanitizeProjectDirName(name) {
+    const trimmed = name
+        .trim()
+        .replace(UNSAFE_DIR_CHARS, '-')
+        .replace(/\s+/g, ' ')
+        .replace(/\.+$/g, '');
+    return trimmed || '未命名项目';
+}
+/** `Documents/<应用显示名>`：该应用下所有托管项目的父目录。 */
+export function appProjectsRoot(options) {
+    const documents = options?.documentsDir ?? getDocumentsDir();
+    const appName = options?.appFolderName ?? getBrand().displayName;
+    return path.join(documents, sanitizeProjectDirName(appName));
+}
+/**
+ * 为项目名分配尚未占用的家目录路径（不落盘）。
+ * 已存在同名目录时追加 `-2`、`-3`…
+ */
+export function allocateProjectHome(projectName, options) {
+    const root = appProjectsRoot(options);
+    const base = sanitizeProjectDirName(projectName);
+    const exists = options?.exists ?? ((folderPath) => fs.existsSync(folderPath));
+    let candidate = path.join(root, base);
+    if (!exists(candidate))
+        return candidate;
+    for (let i = 2; i < 1000; i += 1) {
+        candidate = path.join(root, `${base}-${i}`);
+        if (!exists(candidate))
+            return candidate;
+    }
+    throw new Error('无法分配项目目录：重名过多');
+}
+export function ensureProjectHome(folderPath) {
+    fs.mkdirSync(folderPath, { recursive: true });
+}
+/** 无项目对话的工作区子目录名（与托管项目家目录并列，避免撞名）。 */
+export const CHAT_WORKSPACES_DIR = 'conversations';
+/**
+ * 无项目对话的工作区路径：`Documents/<应用名>/conversations/<chatId>/`。
+ * 不落盘；调用方用 {@link ensureChatWorkspace} 创建。
+ */
+export function chatWorkspacePath(chatId, options) {
+    const id = sanitizeProjectDirName(chatId);
+    return path.join(appProjectsRoot(options), CHAT_WORKSPACES_DIR, id);
+}
+/** 确保无项目对话工作区存在，返回绝对路径。 */
+export function ensureChatWorkspace(chatId, options) {
+    const folderPath = chatWorkspacePath(chatId, options);
+    ensureProjectHome(folderPath);
+    return folderPath;
+}

package/dist/project-registry.d.ts

@@ -1,10 +1,11 @@
 /**
  * 项目注册表（项目模式）。
  *
- * 项目 = 名字 + 绑定的本地文件夹。chat 通过 `chat_sessions.project_id` 绑定
- * 项目；绑定后该对话的文件读写与命令执行被硬限制在项目文件夹内（见
- * tool-router.ts 的 ToolExecContext.projectRoot 与 local-executor.ts 的
- * 路径围栏）。
+ * 项目 = 名字 + 托管家目录 + 可选源文件夹。家目录默认建在
+ * `Documents/<应用名>/<项目名>/`（见 project-home.ts）。chat 通过
+ * `chat_sessions.project_id` 绑定项目；绑定后文件读写与命令执行被硬限制
+ * 在家目录内（见 tool-router.ts 的 ToolExecContext.projectRoot）；源文件夹
+ * 只放宽 local_read_file。
  *
  * 持久化在 userData/agent-projects.json。存储通过 {@link ProjectKvStore}
  * 接口注入：main.ts 用 electron-store 实现，单测用内存实现——本模块不
@@ -14,8 +15,13 @@ export interface ProjectRecord {
     id: string;
     /** 用户可见名称（侧边栏分组标题）。 */
     name: string;
-    /** 绑定的项目文件夹（绝对路径）。 */
+    /** 托管家目录（绝对路径）。默认 `Documents/<应用名>/<项目名>/`。 */
     folderPath: string;
+    /**
+     * 附加源文件夹（已有代码目录）。只放宽读取，不替代家目录，也不放宽写入。
+     * 旧记录没有此字段，读取时按空列表处理。
+     */
+    sourceFolders?: string[];
     /**
      * W6-5 项目信任门控：项目目录里的 `AGENTS.md` / `CLAUDE.md` 等规则文件
      * 是「项目作者写给 agent 的指令」——打开一个恶意仓库时，一段精心构造的
@@ -30,6 +36,7 @@ export interface ProjectRecord {
 export interface CreateProjectInput {
     name: string;
     folderPath: string;
+    sourceFolders?: string[];
 }
 /** 最小 KV 存储接口，避免本模块直接依赖 electron-store。 */
 export interface ProjectKvStore {

package/dist/project-registry.js

@@ -1,10 +1,11 @@
 /**
  * 项目注册表（项目模式）。
  *
- * 项目 = 名字 + 绑定的本地文件夹。chat 通过 `chat_sessions.project_id` 绑定
- * 项目；绑定后该对话的文件读写与命令执行被硬限制在项目文件夹内（见
- * tool-router.ts 的 ToolExecContext.projectRoot 与 local-executor.ts 的
- * 路径围栏）。
+ * 项目 = 名字 + 托管家目录 + 可选源文件夹。家目录默认建在
+ * `Documents/<应用名>/<项目名>/`（见 project-home.ts）。chat 通过
+ * `chat_sessions.project_id` 绑定项目；绑定后文件读写与命令执行被硬限制
+ * 在家目录内（见 tool-router.ts 的 ToolExecContext.projectRoot）；源文件夹
+ * 只放宽 local_read_file。
  *
  * 持久化在 userData/agent-projects.json。存储通过 {@link ProjectKvStore}
  * 接口注入：main.ts 用 electron-store 实现，单测用内存实现——本模块不
@@ -34,11 +35,13 @@ export class ProjectRegistry {
             throw new Error('项目文件夹不能为空');
         if (this.get(name))
             throw new Error(`已存在同名项目「${name}」`);
+        const sourceFolders = normalizeSourceFolders(input.sourceFolders, folderPath);
         const now = new Date().toISOString();
         const entry = {
             id: randomUUID(),
             name,
             folderPath,
+            ...(sourceFolders.length > 0 ? { sourceFolders } : {}),
             createdAt: now,
             updatedAt: now,
         };
@@ -62,10 +65,14 @@ export class ProjectRegistry {
             : current.folderPath;
         if (!nextFolder)
             throw new Error('项目文件夹不能为空');
+        const sourceFolders = updates.sourceFolders !== undefined
+            ? normalizeSourceFolders(updates.sourceFolders, nextFolder)
+            : normalizeSourceFolders(current.sourceFolders, nextFolder);
         const next = {
             ...current,
             name: nextName,
             folderPath: nextFolder,
+            sourceFolders: sourceFolders.length > 0 ? sourceFolders : undefined,
             updatedAt: new Date().toISOString(),
         };
         projects[idx] = next;
@@ -104,3 +111,16 @@ export class ProjectRegistry {
         return next;
     }
 }
+function normalizeSourceFolders(folders, homePath) {
+    const home = homePath.trim();
+    const seen = new Set();
+    const out = [];
+    for (const raw of folders ?? []) {
+        const folder = raw.trim();
+        if (!folder || folder === home || seen.has(folder))
+            continue;
+        seen.add(folder);
+        out.push(folder);
+    }
+    return out;
+}

package/dist/runtime.d.ts

@@ -2,6 +2,12 @@
 export declare function isElectronRuntime(): boolean;
 /** 应用数据目录（SQLite、JSON store、用户技能目录的根）。 */
 export declare function getUserDataDir(): string;
+/**
+ * 用户文档目录。项目默认家目录建在这里的「应用名」文件夹下
+ * （见 project-home.ts）。测试可用 STEERABLE_DOCUMENTS_DIR 改锚点，
+ * 避免写进真实 Documents。
+ */
+export declare function getDocumentsDir(): string;
 /**
  * 注入应用根目录（产品组装根调用）。重复注入不同值抛错（组装期笔误，
  * fail fast——与 setProductBrand 同语义）。

package/dist/runtime.js

@@ -54,6 +54,25 @@ export function getUserDataDir() {
     const dirName = getProductConfig().dataDirName ?? '.agent-shell';
     return path.join(os.homedir(), dirName);
 }
+/**
+ * 用户文档目录。项目默认家目录建在这里的「应用名」文件夹下
+ * （见 project-home.ts）。测试可用 STEERABLE_DOCUMENTS_DIR 改锚点，
+ * 避免写进真实 Documents。
+ */
+export function getDocumentsDir() {
+    if (process.env.STEERABLE_DOCUMENTS_DIR)
+        return process.env.STEERABLE_DOCUMENTS_DIR;
+    const app = tryElectronApp();
+    if (app) {
+        try {
+            return app.getPath('documents');
+        }
+        catch {
+            // 个别环境 getPath('documents') 不可用，回落到 ~/Documents。
+        }
+    }
+    return path.join(os.homedir(), 'Documents');
+}
 /**
  * 应用根目录（消费产品的仓库/打包根：含 products/manifest.json、assets、
  * scripts 的那层）。3.2 起 shell 是被消费的框架包，本模块自己的位置

package/dist/server/http-server.js

@@ -34,6 +34,7 @@ import { getSidecarSupervisor } from '../llm/index.js';
 import { matchPackHttpRoute } from '../host/http-routes.js';
 import { getBrand } from '../brand.js';
 import { saveAttachmentFiles } from '../attachments.js';
+import { selectNativeDirectory } from '../native-folder-dialog.js';
 import { getAuthProvider } from '../auth/index.js';
 /** 与 router.handleStream 内部的路由正则保持一致——只有这些路径是流式。 */
 const STREAM_PATH_PATTERNS = [
@@ -250,6 +251,11 @@ export function createBsServer(deps) {
             return;
         }
         // ─── local（对齐 local:* IPC） ───
+        if (method === 'POST' && pathname === '/host/local/select-directory') {
+            const title = typeof body.title === 'string' ? body.title : undefined;
+            sendJson(res, 200, await selectNativeDirectory({ title }));
+            return;
+        }
         if (method === 'POST' && pathname === '/host/local/exec-shell') {
             const request = body;
             const viaTerminal = await maybeExecInTerminal(request);

package/dist/sidecar/boot.d.ts

@@ -5,13 +5,13 @@ import type { SidecarReverseHandler } from './types.js';
 export interface HostSidecarDeps {
     store: ScopedStore;
     toolRouter: ToolRouter;
-    /** W4-2 项目模式围栏：chatId → 项目根（无项目对话返回 null）。 */
+    /** W4-2 围栏：chatId → 项目家目录或无项目对话工作区。 */
     resolveProjectRoot: (chatId: string) => Promise<string | null>;
     /**
      * 项目模式之外额外放行的只读根（会话附件目录等）。文件写入仍只受
      * projectRoot 围栏约束；这些根只放宽 local_read_file 的读取范围。
      */
-    resolveAdditionalReadRoots?: (chatId: string) => string[];
+    resolveAdditionalReadRoots?: (chatId: string) => string[] | Promise<string[]>;
     /** W4-1 审批反向通道处理器（宿主审批弹窗的应答入口）。 */
     approvalHandler: ReturnType<typeof createApprovalBridge>['handler'];
     /**

package/dist/sidecar/reverse-tools.d.ts

@@ -16,7 +16,7 @@ export interface ReverseToolDeps {
     }) => void;
     /**
      * 项目模式：按 chatId 解析项目根（绝对路径），无绑定/已删除返回 null。
-     * main.ts 注入 LocalBackendRouter.resolveChatProject 的适配；未注入时
+     * main.ts 注入对话可写根（项目家目录或无项目对话工作区）；未注入时
      * 项目围栏不生效（CLI/test 场景）。
      */
     resolveProjectRoot?: (chatId: string) => Promise<string | null>;
@@ -24,6 +24,6 @@ export interface ReverseToolDeps {
      * 额外放行的只读根（会话附件目录等）。写入仍只受 projectRoot 围栏约束，
      * 这里只放宽 local_read_file 的读取范围。
      */
-    resolveAdditionalReadRoots?: (chatId: string) => string[];
+    resolveAdditionalReadRoots?: (chatId: string) => string[] | Promise<string[]>;
 }
 export declare function createToolInvokeHandler(deps: ReverseToolDeps): SidecarReverseHandler;

package/dist/sidecar/reverse-tools.js

@@ -56,7 +56,7 @@ export function createToolInvokeHandler(deps) {
                 ? (await deps.resolveProjectRoot?.(p.context.chatId) ?? null)
                 : null;
         const additionalReadRoots = p.context?.chatId
-            ? (deps.resolveAdditionalReadRoots?.(p.context.chatId) ?? [])
+            ? await Promise.resolve(deps.resolveAdditionalReadRoots?.(p.context.chatId) ?? [])
             : [];
         if (name === 'local_exec_shell') {
             const classification = classifyShellCommand(String(toolArgs.command ?? ''));

package/dist/storage/index.d.ts

@@ -12,7 +12,7 @@ export interface ChatSessionRecord {
     title: string;
     userId: string;
     agentId: string | null;
-    /** 项目模式：绑定的项目 id（ProjectRegistry）。null = 无项目对话（不沙箱）。 */
+    /** 项目模式：绑定的项目 id（ProjectRegistry）。null = 无项目对话（用对话工作区）。 */
     projectId: string | null;
     createdAt: string;
     updatedAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.30",
+  "version": "0.6.32",
   "description": "Steerable framework — product-neutral desktop/headless agent host (Tier 5). Electron main + preload + headless HTTP server (BS) sharing one storage/sidecar/tooling core; scenario packs extend it through the @steerable/pack-sdk contract and are composed at build time by the consuming product.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -49,9 +49,9 @@
     "electron-store": "^8.1.0",
     "he": "^1.2.0",
     "node-pty": "^1.1.0",
-    "@steerable/agent-harness": "0.6.30",
-    "@steerable/pack-sdk": "0.6.30",
-    "@steerable/agent-protocol": "0.6.30"
+    "@steerable/agent-protocol": "0.6.32",
+    "@steerable/pack-sdk": "0.6.32",
+    "@steerable/agent-harness": "0.6.32"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",