@steerable/agent-shell 0.6.29 → 0.6.31

package/dist/host/runtime.js

@@ -207,7 +207,13 @@ export async function createHostRuntime(options) {
                 resolveProjectRoot: async (chatId) => (await localBackendRouter.resolveChatProject(chatId))?.folderPath ?? null,
                 // 项目模式下文件读写被围栏在项目目录内；会话附件目录是额外放行的
                 // 只读根，保证用户上传的文件即使在项目会话里也能被 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

@@ -106,6 +106,7 @@ export declare class LocalBackendRouter {
     resolveChatProject(chatId: string): Promise<{
         name: string;
         folderPath: string;
+        sourceFolders: string[];
     } | null>;
     /**
      * 解析本轮生效的智能体：人设前言、技能勾选、工具策略同源于这一次解析。

package/dist/local-backend/router.js

@@ -8,7 +8,7 @@ import { llmService, getSidecarSupervisor, whenSidecarSupervisor } from '../llm/
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 import { buildWorldState, getActiveCoreLoopStreamId, streamCoreLoopTurn, } from './coreloop-stream.js';
 import { driveWithAutoContinue, resolveAutoContinueMax, } from './auto-continue-helper.js';
-import { buildDelegateDispatchInstruction, buildMentionDelegateRoster, mergeTurnSubagentParam, } from './subagent-profiles.js';
+import { buildAmbientDelegateRoster, buildDelegateDispatchInstruction, buildDelegateRosterHint, buildMentionDelegateRoster, BUILTIN_SUBAGENT_PROFILES, mergeTurnSubagentParam, } from './subagent-profiles.js';
 import { resolveMentionedAgentIds } from './mention-targets.js';
 import { readSidecarHistoryEntries, timelineFromHistoryEntries, } from './task-process.js';
 import { appendTimelineDelta, freezeTimelineReasoning, sealLastTimelineBlock, syncTimelineTools, } from './turn-timeline.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, 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 } };
                 }
@@ -1989,7 +2006,8 @@ export class LocalBackendRouter {
         let currentUserMessageId;
         // 本轮被点名的智能体：菜单点选带来的 id 优先，手打的 `@名字` 从正文
         // 解析补齐（两者缺一，提及就在后端消失，只剩前端徽章）。
-        const mentionedAgentIds = resolveMentionedAgentIds(payload, userMessageText, await this.store.listChatAgents());
+        const chatAgents = await this.store.listChatAgents();
+        const mentionedAgentIds = resolveMentionedAgentIds(payload, userMessageText, chatAgents);
         if (!regenerateMatch && !isResume) {
             const userMeta = mentionedAgentIds.length > 0
                 ? JSON.stringify({ mentionedAgentIds })
@@ -2047,8 +2065,22 @@ export class LocalBackendRouter {
                 available: turnTools.some((t) => t.name === token),
             };
         }
-        const mentionRoster = await buildMentionDelegateRoster(turnAgents.delegates, turnTools.map((tool) => tool.name));
-        const { systemPrompt, messages, skillContext } = await this.buildConversationMessages(chatId, cleanUserMessageText, payload, turnTools, turnAgents, forcedSkillName, chatMode, forcedMcpTool, currentUserMessageId, mentionRoster);
+        const turnToolNames = turnTools.map((tool) => tool.name);
+        const mentionRoster = await buildMentionDelegateRoster(turnAgents.delegates, turnToolNames);
+        // 常驻可委派名单：其余智能体也进画像，技能/提示里的「交给 X」无需用户
+        // `@` 就能落成一次真实委派。父代理自己不进——它就是本轮的执行者，给它
+        // 一个自己的画像只会诱导无意义的自委派（`@自己` 走提及那条路，仍然可以）。
+        const ambientRoster = await buildAmbientDelegateRoster(chatAgents, turnToolNames, {
+            excludeAgentIds: [
+                ...mentionRoster.map((row) => row.agentId),
+                ...(turnAgents.parent ? [turnAgents.parent.id] : []),
+            ],
+            reservedProfileNames: [
+                ...Object.keys(BUILTIN_SUBAGENT_PROFILES),
+                ...mentionRoster.map((row) => row.profileName),
+            ],
+        });
+        const { systemPrompt, messages, skillContext } = await this.buildConversationMessages(chatId, cleanUserMessageText, payload, turnTools, turnAgents, forcedSkillName, chatMode, forcedMcpTool, currentUserMessageId, { mention: mentionRoster, ambient: ambientRoster });
         // A4: the sidecar-hosted CoreLoop is the only chat path (the TS loop
         // was deleted 2026-08-26 after default-on + canary verification). Tools
         // round-trip back to this process over the reverse channel. If the
@@ -2071,7 +2103,7 @@ export class LocalBackendRouter {
             shouldGenerateTitle,
             firstUserMessageForTitle,
             resume: isResume,
-            subagent: mergeTurnSubagentParam(Object.fromEntries(mentionRoster.map((row) => [row.profileName, row.profile]))),
+            subagent: mergeTurnSubagentParam(Object.fromEntries(mentionRoster.map((row) => [row.profileName, row.profile])), Object.fromEntries(ambientRoster.map((row) => [row.profileName, row.profile]))),
             parentAgentId: turnAgents.parent?.id ?? null,
         });
     }
@@ -2170,7 +2202,11 @@ 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 ?? [],
+        };
     }
     /**
      * 解析本轮生效的智能体：人设前言、技能勾选、工具策略同源于这一次解析。
@@ -2206,7 +2242,7 @@ export class LocalBackendRouter {
             capability: mergeAgentCapabilities(parent ? [parent] : []),
         };
     }
-    async buildConversationMessages(chatId, latestUserMessage, payload, turnTools, turnAgents, forcedSkillName, chatMode = 'agent', forcedMcpTool, currentUserMessageId, mentionRoster = []) {
+    async buildConversationMessages(chatId, latestUserMessage, payload, turnTools, turnAgents, forcedSkillName, chatMode = 'agent', forcedMcpTool, currentUserMessageId, delegates = { mention: [], ambient: [] }) {
         // 跨轮压缩由框架 CoreLoop 拥有：token 压力触发 CompactionHooks（已接真实
         // summarizer），压缩边界持久化到 durable record，W6-10 透视 reconcile 保证
         // 压缩跨轮存活。桌面把全量原始历史作为种子发给框架——不再维护桌面侧滚动
@@ -2276,7 +2312,11 @@ export class LocalBackendRouter {
             .join('\n\n');
         const polluted = this.detectToolDenialInHistory(historyAssistantTexts);
         const runtimeEnvironment = this.buildRuntimeEnvironmentContext(chatMode);
-        const realityCheck = runtimeEnvironment + this.buildToolRealityCheck(turnTools, polluted, chatMode);
+        // 名录进 realityCheck：两条系统提示拼装路径（技能拼装 / 用户整段覆盖）
+        // 都会带上它，且位置在末尾——不动技能正文那段 prompt cache 前缀。
+        const realityCheck = runtimeEnvironment +
+            this.buildToolRealityCheck(turnTools, polluted, chatMode) +
+            buildDelegateRosterHint([...delegates.mention, ...delegates.ambient]);
         // 用户显式覆盖（payload.systemPrompt 优先 / settings.systemPrompt 自定义了且非默认值次之）走
         // "整段替换"路径，保持旧行为可被外部完全控制；否则交给 skill-based
         // SystemPromptBuilder 根据本轮可用工具动态拼装。
@@ -2358,11 +2398,14 @@ export class LocalBackendRouter {
         const chatProject = await this.resolveChatProject(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）。信任状态持久化、
@@ -2407,8 +2450,8 @@ export class LocalBackendRouter {
         if (finalUserImages.notes.length > 0) {
             finalUserContent = `${finalUserContent}\n\n【附件图片】\n${finalUserImages.notes.join('\n')}`;
         }
-        if (mentionRoster.length > 0) {
-            finalUserContent = `${finalUserContent}\n\n${buildDelegateDispatchInstruction(mentionRoster.map((row) => ({
+        if (delegates.mention.length > 0) {
+            finalUserContent = `${finalUserContent}\n\n${buildDelegateDispatchInstruction(delegates.mention.map((row) => ({
                 name: row.name,
                 profileName: row.profileName,
                 toolFilter: row.profile.toolFilter,

package/dist/local-backend/subagent-profiles.d.ts

@@ -29,8 +29,14 @@ export interface SubagentAgentInput extends AgentCapabilityInput {
     name: string;
     rolePrompt: string | null;
     description?: string | null;
+    /** 画像缓存的失效依据：改配置即换键。缺省则该智能体的画像每轮重建。 */
+    updatedAt?: string;
 }
-/** 一次 `@` 提及转出的画像，连同显示名，供派发指令与 sidecar 参数共用。 */
+/**
+ * 一个可委派对象的画像，连同显示名，供派发指令、名录说明与 sidecar 参数
+ * 共用。两个来源共享这个结构：用户 `@` 点名的（强制派发）与常驻可委派
+ * 名单里的（模型自主判断）。
+ */
 export interface MentionDelegateProfile {
     /** 被提及智能体的 id——调用方据此认出自提及那一行。 */
     agentId: string;
@@ -83,6 +89,28 @@ export declare function buildMentionSubagentProfiles(delegates: readonly Subagen
  * @returns 提及顺序的画像花名册。
  */
 export declare function buildMentionDelegateRoster(delegates: readonly SubagentAgentInput[], parentToolNames: readonly string[]): Promise<MentionDelegateProfile[]>;
+/**
+ * 常驻可委派名单：会话里的其他智能体也转成画像，模型**无需用户 `@`** 就能
+ * 委派。技能正文或自定义提示里写「交给 X」因此能落成一次真实
+ * `delegate_subagent`——在此之前 `subagent_type` 的 enum 里只有内置三个画像，
+ * 这类指令 fail closed 报 `unknown subagent_type`，模型只能在正文里打出名字。
+ *
+ * 与提及名单的唯一区别是强制性：这里**不进** `requiredProfiles`。派不派由模型
+ * 按任务判断——技能的阶段条件（「阶段 C 才交给 Word 智能体」）在拼装画像时
+ * 还不可知，一律强制会把不该派的回合反复退回完成门。
+ *
+ * @param agents 会话可用的智能体（未归档）。
+ * @param parentToolNames 父本轮模型可见工具名。
+ * @param options.excludeAgentIds 不进名单的智能体：父代理自己与已在提及名单里的。
+ * @param options.reservedProfileNames 已占用的画像名（内置画像 + 提及画像），避免顶掉。
+ * @returns 画像花名册，按 `agents` 顺序。
+ */
+export declare function buildAmbientDelegateRoster(agents: readonly SubagentAgentInput[], parentToolNames: readonly string[], options?: {
+    excludeAgentIds?: readonly string[];
+    reservedProfileNames?: readonly string[];
+}): Promise<MentionDelegateProfile[]>;
+/** 清空画像缓存（测试用；生产靠 `updatedAt` 与存活时长失效）。 */
+export declare function resetDelegateProfileCache(): void;
 /**
  * 注入本轮最后一条用户消息的强制派发指令。
  *
@@ -99,6 +127,24 @@ export declare function buildDelegateDispatchInstruction(delegates: ReadonlyArra
     toolFilter?: string[];
     isSelf?: boolean;
 }>): string;
+/**
+ * 可委派智能体名录：注入系统提示（realityCheck 段）。
+ *
+ * 技能正文与自定义提示里写的是**显示名**（`@Word智能体`），而 `subagent_type`
+ * 只认 ASCII 画像名（`word-master`）。没有这张对照表，技能作者只能硬编码画像
+ * 名、智能体一改名就断；模型也无从知道正文里的「@某智能体」该落成一次
+ * `delegate_subagent`，于是只在回复里打出这个名字然后收尾。
+ *
+ * 与 {@link buildDelegateDispatchInstruction} 的分工：那份是用户点名后的**强制**
+ * 派发指令（配 `requiredProfiles` 完成门兜底），这份只说明「能派谁、怎么派」。
+ *
+ * @param delegates 本轮可委派的智能体（提及 + 常驻名单）。
+ * @returns 名录正文；空名单返回空串，本轮系统提示与改前逐字节一致。
+ */
+export declare function buildDelegateRosterHint(delegates: ReadonlyArray<{
+    name: string;
+    profileName: string;
+}>): string;
 export interface TurnSubagentParam {
     profiles: Record<string, BuiltinSubagentProfile>;
     maxParallel?: number;
@@ -106,12 +152,14 @@ export interface TurnSubagentParam {
     requiredProfiles?: string[];
 }
 /**
- * 内置画像 + 本轮提及画像。被 `@` 超过 4 个时抬高池的并行上限。
+ * 内置画像 + 常驻可委派画像 + 本轮提及画像。被 `@` 超过 4 个时抬高池的并行上限。
  *
- * 提及画像同时作为 `requiredProfiles` 下发：强制派发此前只是提示词里的
- * 一句话，模型跑了别的工具再叙述「已启动」就能蒙过所有既有纪律检查。
+ * 只有**提及**画像进 `requiredProfiles`：强制派发此前只是提示词里的一句话，
+ * 模型跑了别的工具再叙述「已启动」就能蒙过所有既有纪律检查。常驻画像刻意不进
+ * ——它们是「可以派」，不是「本轮必须派」。
  *
- * @param mentionProfiles 本轮提及转出的画像；空对象则与 {@link builtinSubagentParam} 相同。
+ * @param mentionProfiles 本轮提及转出的画像。
+ * @param ambientProfiles 常驻可委派画像；与提及画像同名时以提及为准。
  * @returns 下发给 sidecar 的 `subagent` 参数。
  */
-export declare function mergeTurnSubagentParam(mentionProfiles: Record<string, BuiltinSubagentProfile>): TurnSubagentParam;
+export declare function mergeTurnSubagentParam(mentionProfiles: Record<string, BuiltinSubagentProfile>, ambientProfiles?: Record<string, BuiltinSubagentProfile>): TurnSubagentParam;

package/dist/local-backend/subagent-profiles.js

@@ -148,9 +148,35 @@ export async function buildMentionSubagentProfiles(delegates, parentToolNames) {
  * @returns 提及顺序的画像花名册。
  */
 export async function buildMentionDelegateRoster(delegates, parentToolNames) {
+    return await buildRoster(delegates, parentToolNames, new Set());
+}
+/**
+ * 常驻可委派名单：会话里的其他智能体也转成画像，模型**无需用户 `@`** 就能
+ * 委派。技能正文或自定义提示里写「交给 X」因此能落成一次真实
+ * `delegate_subagent`——在此之前 `subagent_type` 的 enum 里只有内置三个画像，
+ * 这类指令 fail closed 报 `unknown subagent_type`，模型只能在正文里打出名字。
+ *
+ * 与提及名单的唯一区别是强制性：这里**不进** `requiredProfiles`。派不派由模型
+ * 按任务判断——技能的阶段条件（「阶段 C 才交给 Word 智能体」）在拼装画像时
+ * 还不可知，一律强制会把不该派的回合反复退回完成门。
+ *
+ * @param agents 会话可用的智能体（未归档）。
+ * @param parentToolNames 父本轮模型可见工具名。
+ * @param options.excludeAgentIds 不进名单的智能体：父代理自己与已在提及名单里的。
+ * @param options.reservedProfileNames 已占用的画像名（内置画像 + 提及画像），避免顶掉。
+ * @returns 画像花名册，按 `agents` 顺序。
+ */
+export async function buildAmbientDelegateRoster(agents, parentToolNames, options = {}) {
+    const excluded = new Set(options.excludeAgentIds ?? []);
+    const candidates = agents.filter((agent) => !excluded.has(agent.id));
+    if (candidates.length === 0)
+        return [];
+    return await buildRoster(candidates, parentToolNames, new Set(options.reservedProfileNames ?? []));
+}
+async function buildRoster(agents, parentToolNames, reserved) {
     const roster = [];
-    const used = new Set();
-    for (const agent of delegates) {
+    const used = new Set(reserved);
+    for (const agent of agents) {
         let profileName = profileNameForAgent(agent);
         if (used.has(profileName)) {
             const suffix = agent.id.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8);
@@ -161,12 +187,52 @@ export async function buildMentionDelegateRoster(delegates, parentToolNames) {
             agentId: agent.id,
             name: agent.name,
             profileName,
-            profile: await buildOneMentionProfile(agent, parentToolNames),
+            profile: await buildOneDelegateProfile(agent, parentToolNames),
         });
     }
     return roster;
 }
-async function buildOneMentionProfile(agent, parentToolNames) {
+/**
+ * 画像构建缓存的存活时长。
+ *
+ * 常驻名单让每轮的画像数量从「用户点了几个」变成「用户有几个智能体」，而
+ * 每份画像的 `systemPrompt` 都要过一次 `buildSystemPrompt`（内含技能目录
+ * 扫描）——不缓存就是每轮多做 N 次磁盘扫描，直接加在首个 token 之前。
+ *
+ * 缓存键带 `updatedAt`，所以改智能体立即生效；技能**正文**落盘不改
+ * `updatedAt`，靠这个存活时长兜底，最迟下一轮生效。
+ */
+const DELEGATE_PROFILE_TTL_MS = 15_000;
+const delegateProfileCache = new Map();
+/** 清空画像缓存（测试用；生产靠 `updatedAt` 与存活时长失效）。 */
+export function resetDelegateProfileCache() {
+    delegateProfileCache.clear();
+}
+async function buildOneDelegateProfile(agent, parentToolNames) {
+    // 键要完整描述这份画像的输入：身份（改名/换 slug 都会换画像名与人设）、
+    // `updatedAt`（改配置即失效）、父工具面（`toolFilter` 与画像 systemPrompt
+    // 里的工具名录都由它派生）。只用 id 的话，任何复用 id 的调用方（内存假
+    // 存储的测试）都会静默拿到另一个智能体的画像。
+    const cacheKey = agent.updatedAt
+        ? [
+            agent.id,
+            agent.updatedAt,
+            agent.slug ?? '',
+            agent.name,
+            parentToolNames.join(','),
+        ].join('\u0000')
+        : null;
+    if (cacheKey) {
+        const hit = delegateProfileCache.get(cacheKey);
+        if (hit && Date.now() - hit.builtAtMs < DELEGATE_PROFILE_TTL_MS)
+            return hit.profile;
+    }
+    const profile = await buildProfileUncached(agent, parentToolNames);
+    if (cacheKey)
+        delegateProfileCache.set(cacheKey, { builtAtMs: Date.now(), profile });
+    return profile;
+}
+async function buildProfileUncached(agent, parentToolNames) {
     const toolFilter = resolveChildToolFilter(agent.toolPolicy, parentToolNames);
     const domain = toolFilter ?? parentToolNames;
     const readOnly = isReadOnlyToolDomain(domain);
@@ -232,18 +298,54 @@ export function buildDelegateDispatchInstruction(delegates) {
     ].join('\n');
 }
 /**
- * 内置画像 + 本轮提及画像。被 `@` 超过 4 个时抬高池的并行上限。
+ * 可委派智能体名录：注入系统提示（realityCheck 段）。
+ *
+ * 技能正文与自定义提示里写的是**显示名**（`@Word智能体`），而 `subagent_type`
+ * 只认 ASCII 画像名（`word-master`）。没有这张对照表，技能作者只能硬编码画像
+ * 名、智能体一改名就断；模型也无从知道正文里的「@某智能体」该落成一次
+ * `delegate_subagent`，于是只在回复里打出这个名字然后收尾。
+ *
+ * 与 {@link buildDelegateDispatchInstruction} 的分工：那份是用户点名后的**强制**
+ * 派发指令（配 `requiredProfiles` 完成门兜底），这份只说明「能派谁、怎么派」。
+ *
+ * @param delegates 本轮可委派的智能体（提及 + 常驻名单）。
+ * @returns 名录正文；空名单返回空串，本轮系统提示与改前逐字节一致。
+ */
+export function buildDelegateRosterHint(delegates) {
+    if (delegates.length === 0)
+        return '';
+    const roster = delegates
+        .map((row) => `- ${row.name} → \`subagent_type="${row.profileName}"\``)
+        .join('\n');
+    return [
+        '',
+        '',
+        '## 可委派的智能体',
+        '',
+        '以下智能体可以通过 `delegate_subagent` 接活，画像名对照：',
+        '',
+        roster,
+        '',
+        '- 指令（含技能正文）里出现「@某智能体」或「交给某智能体」时，意思是**用 `delegate_subagent` 把这份活派给它**，`subagent_type` 填上表对应的画像名——不是在回复里打出这个名字。',
+        '- 每份 `task` 必须自包含（目标、输入、交付形式、验收标准）：子代理看不到本对话。',
+        '- 表里没有的名字不要猜着填，`subagent_type` 只接受上表与内置画像。',
+    ].join('\n');
+}
+/**
+ * 内置画像 + 常驻可委派画像 + 本轮提及画像。被 `@` 超过 4 个时抬高池的并行上限。
  *
- * 提及画像同时作为 `requiredProfiles` 下发：强制派发此前只是提示词里的
- * 一句话，模型跑了别的工具再叙述「已启动」就能蒙过所有既有纪律检查。
+ * 只有**提及**画像进 `requiredProfiles`：强制派发此前只是提示词里的一句话，
+ * 模型跑了别的工具再叙述「已启动」就能蒙过所有既有纪律检查。常驻画像刻意不进
+ * ——它们是「可以派」，不是「本轮必须派」。
  *
- * @param mentionProfiles 本轮提及转出的画像；空对象则与 {@link builtinSubagentParam} 相同。
+ * @param mentionProfiles 本轮提及转出的画像。
+ * @param ambientProfiles 常驻可委派画像；与提及画像同名时以提及为准。
  * @returns 下发给 sidecar 的 `subagent` 参数。
  */
-export function mergeTurnSubagentParam(mentionProfiles) {
+export function mergeTurnSubagentParam(mentionProfiles, ambientProfiles = {}) {
     const mentionNames = Object.keys(mentionProfiles);
     return {
-        profiles: { ...BUILTIN_SUBAGENT_PROFILES, ...mentionProfiles },
+        profiles: { ...BUILTIN_SUBAGENT_PROFILES, ...ambientProfiles, ...mentionProfiles },
         ...(mentionNames.length > 4 ? { maxParallel: mentionNames.length } : {}),
         ...(mentionNames.length > 0 ? { requiredProfiles: mentionNames } : {}),
     };

package/dist/project-home.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 项目默认家目录：`Documents/<应用名>/<项目名>/`。
+ *
+ * 新建项目不再等于「选一个已有文件夹」——项目是带名字的容器，
+ * 家目录由本模块分配并创建。用户另加的源文件夹是附加只读根，
+ * 不替代这个家目录。
+ */
+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;

package/dist/project-home.js

@@ -0,0 +1,47 @@
+/**
+ * 项目默认家目录：`Documents/<应用名>/<项目名>/`。
+ *
+ * 新建项目不再等于「选一个已有文件夹」——项目是带名字的容器，
+ * 家目录由本模块分配并创建。用户另加的源文件夹是附加只读根，
+ * 不替代这个家目录。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getBrand } from './brand.js';
+import { getDocumentsDir } from './runtime.js';
+const UNSAFE_DIR_CHARS = /[\\/:*?"<>|]/g;
+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 });
+}

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/sidecar/boot.d.ts

@@ -11,7 +11,7 @@ export interface HostSidecarDeps {
      * 项目模式之外额外放行的只读根（会话附件目录等）。文件写入仍只受
      * 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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.29",
+  "version": "0.6.31",
   "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.29",
-    "@steerable/pack-sdk": "0.6.29",
-    "@steerable/agent-protocol": "0.6.29"
+    "@steerable/agent-harness": "0.6.31",
+    "@steerable/pack-sdk": "0.6.31",
+    "@steerable/agent-protocol": "0.6.31"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",