@eoasmxd/freya 0.4.3 → 0.5.0

package/core/dist/config/config-manager.js

@@ -1,7 +1,7 @@
 import { FreyaConfigFileHandler } from './file-handler.js';
 import { FreyaConfigSchemaRegistry } from './schema-registry.js';
 import path from 'node:path';
-import { PROJECT_ROOT } from '../utils/paths.js';
+import { FREYA_HOME } from '../utils/paths.js';
 function cleanPathFromError(err) {
     const rawMessage = err?.message || String(err);
     const escapedCwd = process.cwd().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -195,11 +195,11 @@ export class FreyaConfigManager {
         const cloned = JSON.parse(JSON.stringify(config));
         if (cloned.workspace && typeof cloned.workspace === 'string') {
             if (!path.isAbsolute(cloned.workspace)) {
-                cloned.workspace = path.resolve(PROJECT_ROOT, cloned.workspace);
+                cloned.workspace = path.resolve(FREYA_HOME, cloned.workspace);
             }
         }
         else {
-            cloned.workspace = path.join(PROJECT_ROOT, 'workspace');
+            cloned.workspace = path.join(FREYA_HOME, 'workspace');
         }
         this.context.config = deepFreeze(cloned);
     }

package/core/dist/config/file-handler.js

@@ -1,10 +1,10 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { PROJECT_ROOT } from '../utils/paths.js';
+import { FREYA_HOME } from '../utils/paths.js';
 /** 配置文件底层 IO 处理器 */
 export class FreyaConfigFileHandler {
     async readFreyaConfig() {
-        const filePath = path.join(PROJECT_ROOT, 'config', 'freya.json');
+        const filePath = path.join(FREYA_HOME, 'config', 'freya.json');
         try {
             const data = await fs.readFile(filePath, 'utf-8');
             return JSON.parse(data);
@@ -14,12 +14,12 @@ export class FreyaConfigFileHandler {
         }
     }
     async writeFreyaConfig(config) {
-        const filePath = path.join(PROJECT_ROOT, 'config', 'freya.json');
+        const filePath = path.join(FREYA_HOME, 'config', 'freya.json');
         await fs.mkdir(path.dirname(filePath), { recursive: true });
         await fs.writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
     }
     async readProviders() {
-        const filePath = path.join(PROJECT_ROOT, 'config', 'providers.json');
+        const filePath = path.join(FREYA_HOME, 'config', 'providers.json');
         try {
             const data = await fs.readFile(filePath, 'utf-8');
             return JSON.parse(data);
@@ -29,16 +29,16 @@ export class FreyaConfigFileHandler {
         }
     }
     async writeProviders(providers) {
-        const filePath = path.join(PROJECT_ROOT, 'config', 'providers.json');
+        const filePath = path.join(FREYA_HOME, 'config', 'providers.json');
         await fs.mkdir(path.dirname(filePath), { recursive: true });
         await fs.writeFile(filePath, JSON.stringify(providers, null, 2) + '\n', 'utf-8');
     }
     async readPromptFile(name) {
-        const filePath = path.join(PROJECT_ROOT, 'config', `${name.toUpperCase()}.md`);
+        const filePath = path.join(FREYA_HOME, 'config', `${name.toUpperCase()}.md`);
         return await fs.readFile(filePath, 'utf-8');
     }
     async writePromptFile(name, content) {
-        const filePath = path.join(PROJECT_ROOT, 'config', `${name.toUpperCase()}.md`);
+        const filePath = path.join(FREYA_HOME, 'config', `${name.toUpperCase()}.md`);
         await fs.mkdir(path.dirname(filePath), { recursive: true });
         await fs.writeFile(filePath, content.trim() + '\n', 'utf-8');
     }

package/core/dist/context.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { APP_ROOT, PROJECT_ROOT } from './utils/paths.js';
+import { FREYA_APP, FREYA_HOME, FREYA_WORKSPACE } from './utils/paths.js';
 export class DefaultFreyaContext {
     logger;
     eventBus;
@@ -7,16 +7,17 @@ export class DefaultFreyaContext {
     llm;
     get paths() {
         const configWorkspace = this.config?.workspace;
-        let workspaceDir = path.join(PROJECT_ROOT, 'workspace');
+        let workspaceDir = path.join(FREYA_HOME, 'workspace');
         if (configWorkspace && typeof configWorkspace === 'string') {
             workspaceDir = path.isAbsolute(configWorkspace)
                 ? configWorkspace
-                : path.resolve(PROJECT_ROOT, configWorkspace);
+                : path.resolve(FREYA_HOME, configWorkspace);
         }
         return {
-            appRoot: APP_ROOT,
-            projectRoot: PROJECT_ROOT,
-            dataDir: path.join(PROJECT_ROOT, 'data'),
+            appRoot: FREYA_APP,
+            homeDir: FREYA_HOME,
+            workspaceRoot: FREYA_WORKSPACE,
+            dataDir: path.join(FREYA_HOME, 'data'),
             workspaceDir,
         };
     }

package/core/dist/llm/llm-logger.js

@@ -1,12 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { PROJECT_ROOT } from '../utils/paths.js';
+import { FREYA_HOME } from '../utils/paths.js';
 /** LLM 交互日志器，按日期写入 logs/llm-YYYY-MM-DD.log */
 export class FreyaLLMLogger {
     logsDir;
     _enabled;
     constructor(enabled) {
-        this.logsDir = path.join(PROJECT_ROOT, 'logs');
+        this.logsDir = path.join(FREYA_HOME, 'logs');
         this._enabled = enabled;
         fs.mkdirSync(this.logsDir, { recursive: true });
     }

package/core/dist/logger.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import fsPromises from 'node:fs/promises';
 import path from 'node:path';
 import { inspect } from 'node:util';
-import { PROJECT_ROOT } from './utils/paths.js';
+import { FREYA_HOME } from './utils/paths.js';
 /** 双轨日志器：按日期滚动写入文件，按配置输出至控制台 */
 export class FreyaLogger {
     logsDir;
@@ -15,7 +15,7 @@ export class FreyaLogger {
     currentDay = '';
     currentLogFilePath = '';
     constructor() {
-        this.logsDir = path.join(PROJECT_ROOT, 'logs');
+        this.logsDir = path.join(FREYA_HOME, 'logs');
         fs.mkdirSync(this.logsDir, { recursive: true });
     }
     /** 设置各日志级别是否输出至控制台 */

package/core/dist/plugin/plugin-manager.d.ts

@@ -12,7 +12,7 @@ export interface PluginConfigEntry {
     displayName?: string;
     description?: string;
     version?: string;
-    source?: 'builtin' | 'runtime' | 'npm';
+    source?: 'builtin' | 'workspace' | 'runtime' | 'npm';
 }
 /**
  * Freya 插件生命周期与模块管理器

package/core/dist/plugin/plugin-manager.js

@@ -5,7 +5,7 @@ import { pathToFileURL } from 'node:url';
 import { FreyaCommandRegistry } from '../command/command-registry.js';
 import { FreyaConfigSchemaRegistry } from '../config/schema-registry.js';
 import { FreyaPromptRegistry } from '../prompt/prompt-registry.js';
-import { APP_ROOT, PROJECT_ROOT } from '../utils/paths.js';
+import { FREYA_APP, FREYA_HOME, FREYA_WORKSPACE } from '../utils/paths.js';
 import { FreyaPluginRegistry } from './plugin-registry.js';
 /**
  * Freya 插件生命周期与模块管理器
@@ -115,7 +115,7 @@ export class FreyaPluginManager {
         }
         entry.enabled = enabled;
         entry.status = enabled ? 'active' : 'disabled';
-        const configPluginsPath = path.join(PROJECT_ROOT, 'config', 'plugins.json');
+        const configPluginsPath = path.join(FREYA_HOME, 'config', 'plugins.json');
         try {
             await fs.mkdir(path.dirname(configPluginsPath), { recursive: true });
             const rawEntries = this.pluginEntries.map((e) => ({ id: e.id, enabled: e.enabled }));
@@ -188,7 +188,7 @@ export class FreyaPluginManager {
             const displayName = String(pkg.freya?.displayName || pkg.displayName || id);
             const description = String(pkg.description || '');
             const version = String(pkg.version || '0.1.0');
-            const defaultEnabled = (source === 'builtin' && pkg.freya?.defaultEnabled === true);
+            const defaultEnabled = ((source === 'builtin' || source === 'workspace') && pkg.freya?.defaultEnabled === true);
             const rawPrompts = pkg.freya?.prompts;
             const prompts = Array.isArray(rawPrompts) ? rawPrompts.map(String) : [];
             const isFreyaPlugin = Boolean(pkg.freya ||
@@ -288,7 +288,7 @@ export class FreyaPluginManager {
             let pkgJsonPath = '';
             try {
                 pkgJsonPath = req.resolve(`${pkgName}/package.json`, {
-                    paths: [path.join(PROJECT_ROOT), path.join(APP_ROOT), process.cwd()]
+                    paths: [path.join(FREYA_WORKSPACE), path.join(FREYA_HOME), path.join(FREYA_APP), process.cwd()]
                 });
             }
             catch {
@@ -340,7 +340,7 @@ export class FreyaPluginManager {
      */
     async scanAllChannels(configuredIds) {
         const map = new Map();
-        const builtinDir = path.join(APP_ROOT, 'plugins');
+        const builtinDir = path.join(FREYA_APP, 'plugins');
         try {
             const entries = await fs.readdir(builtinDir, { withFileTypes: true });
             for (const entry of entries) {
@@ -352,14 +352,41 @@ export class FreyaPluginManager {
             }
         }
         catch { }
-        const runtimeDir = path.join(PROJECT_ROOT, 'plugins');
+        const workspaceDir = path.join(FREYA_WORKSPACE, 'plugins');
+        const resolvedBuiltin = path.resolve(builtinDir);
+        const resolvedWorkspace = path.resolve(workspaceDir);
+        const resolvedRuntime = path.resolve(path.join(FREYA_HOME, 'plugins'));
+        if (resolvedWorkspace !== resolvedBuiltin && resolvedWorkspace !== resolvedRuntime) {
+            try {
+                const entries = await fs.readdir(workspaceDir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        const info = await this.inspectPluginPackage(path.join(workspaceDir, entry.name), 'workspace');
+                        if (info) {
+                            const existing = map.get(info.id);
+                            if (existing?.source === 'builtin') {
+                                info.source = 'builtin';
+                            }
+                            map.set(info.id, info);
+                        }
+                    }
+                }
+            }
+            catch { }
+        }
+        const runtimeDir = path.join(FREYA_HOME, 'plugins');
         try {
             const entries = await fs.readdir(runtimeDir, { withFileTypes: true });
             for (const entry of entries) {
                 if (entry.isDirectory()) {
                     const info = await this.inspectPluginPackage(path.join(runtimeDir, entry.name), 'runtime');
-                    if (info)
+                    if (info) {
+                        const existing = map.get(info.id);
+                        if (existing?.source === 'builtin') {
+                            info.source = 'builtin';
+                        }
                         map.set(info.id, info);
+                    }
                 }
             }
         }
@@ -378,7 +405,7 @@ export class FreyaPluginManager {
     async loadConfiguredPlugins(pluginRegistry, ctx) {
         this.ctx = ctx;
         this.pluginRegistry = pluginRegistry;
-        const configPluginsPath = path.join(PROJECT_ROOT, 'config', 'plugins.json');
+        const configPluginsPath = path.join(FREYA_HOME, 'config', 'plugins.json');
         let configList = [];
         try {
             const raw = await fs.readFile(configPluginsPath, 'utf-8');

package/core/dist/prompt/prompt-manager.js

@@ -1,14 +1,14 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { APP_ROOT, PROJECT_ROOT } from '../utils/paths.js';
+import { FREYA_APP, FREYA_HOME } from '../utils/paths.js';
 import { FreyaPromptRegistry } from './prompt-registry.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /** 提示词物理文件管理器，负责加载、缺失拷贝与持久化覆写 */
 export class FreyaPromptManager {
     promptRegistry;
     logger;
-    defaultDirPath = path.join(APP_ROOT, 'config', 'prompts');
+    defaultDirPath = path.join(FREYA_APP, 'config', 'prompts');
     constructor(promptRegistry, logger) {
         this.promptRegistry = promptRegistry;
         this.logger = logger;
@@ -26,7 +26,7 @@ export class FreyaPromptManager {
         if (!isCorePrompt) {
             throw new Error(`拒绝执行：配置管理工具仅允许管理核心提示词`);
         }
-        const runFilePath = path.join(PROJECT_ROOT, 'config', `${name.toUpperCase()}.md`);
+        const runFilePath = path.join(FREYA_HOME, 'config', `${name.toUpperCase()}.md`);
         await fs.mkdir(path.dirname(runFilePath), { recursive: true });
         await fs.writeFile(runFilePath, content, 'utf-8');
         const registryKey = `core.prompt.${name.toLowerCase()}`;
@@ -38,7 +38,7 @@ export class FreyaPromptManager {
         if (!isCorePrompt) {
             throw new Error(`拒绝执行：配置管理工具仅允许管理核心提示词`);
         }
-        const runFilePath = path.join(PROJECT_ROOT, 'config', `${name.toUpperCase()}.md`);
+        const runFilePath = path.join(FREYA_HOME, 'config', `${name.toUpperCase()}.md`);
         const registryKey = `core.prompt.${name.toLowerCase()}`;
         const currentText = this.promptRegistry.get(registryKey);
         if (!currentText.includes(targetContent)) {

package/core/dist/prompt/prompt-registry.js

@@ -1,11 +1,11 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { APP_ROOT, PROJECT_ROOT } from '../utils/paths.js';
+import { FREYA_APP, FREYA_HOME } from '../utils/paths.js';
 /** 提示词内存注册表，管理所有系统及插件级提示词的分类检索 */
 export class FreyaPromptRegistry {
     prompts = new Map();
     getRunFilePath(prompt) {
-        return prompt.runPath || path.join(PROJECT_ROOT, 'config', 'prompts', path.basename(prompt.defaultPath));
+        return prompt.runPath || path.join(FREYA_HOME, 'config', 'prompts', path.basename(prompt.defaultPath));
     }
     /** 注册提示词元数据声明并执行异步双读载入 */
     async register(prompt) {
@@ -46,14 +46,14 @@ export class FreyaPromptRegistry {
     }
     /** 扫描并装载所有内核提示词，支持运行时提示词覆盖默认提示词 */
     async loadKernelPrompts() {
-        const defaultDirPath = path.join(APP_ROOT, 'config', 'prompts');
+        const defaultDirPath = path.join(FREYA_APP, 'config', 'prompts');
         try {
             const corePrompts = ['identity', 'soul', 'tools', 'agents', 'user', 'memory'];
             for (const name of corePrompts) {
                 await this.register({
                     key: `core.prompt.${name}`,
                     defaultPath: path.join(defaultDirPath, `core.prompt.${name}.md`),
-                    runPath: path.join(PROJECT_ROOT, 'config', `${name.toUpperCase()}.md`)
+                    runPath: path.join(FREYA_HOME, 'config', `${name.toUpperCase()}.md`)
                 });
             }
             try {

package/core/dist/session/persistence.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { PROJECT_ROOT } from '../utils/paths.js';
-const DATA_DIR = path.resolve(PROJECT_ROOT, 'data');
+import { FREYA_HOME } from '../utils/paths.js';
+const DATA_DIR = path.resolve(FREYA_HOME, 'data');
 const SESSIONS_DIR = path.resolve(DATA_DIR, 'sessions');
 const INDEX_FILE = path.resolve(DATA_DIR, 'sessions.json');
 const sessionDirByUuid = (uuid) => path.resolve(SESSIONS_DIR, uuid);

package/core/dist/skill/skill-registry.d.ts

@@ -5,7 +5,7 @@ export interface FreyaSkill {
     description: string;
     content: string;
     enabled: boolean;
-    source: 'builtin' | 'runtime';
+    source: 'builtin' | 'workspace' | 'runtime';
 }
 /** 技能注册表，从 skills/ 目录加载 Markdown 格式技能并管理软开关状态 */
 export declare class FreyaSkillRegistry {

package/core/dist/skill/skill-registry.js

@@ -1,18 +1,25 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { APP_ROOT, PROJECT_ROOT } from '../utils/paths.js';
+import { FREYA_APP, FREYA_HOME, FREYA_WORKSPACE } from '../utils/paths.js';
 /** 技能注册表，从 skills/ 目录加载 Markdown 格式技能并管理软开关状态 */
 export class FreyaSkillRegistry {
     skills = new Map();
     context;
     async loadSkills(context) {
         this.context = context;
-        const runtimeSkillsDir = path.join(PROJECT_ROOT, 'skills');
-        const defaultSkillsDir = path.join(APP_ROOT, 'skills');
-        const configSkillsPath = path.join(PROJECT_ROOT, 'config', 'skills.json');
+        const defaultSkillsDir = path.join(FREYA_APP, 'skills');
+        const workspaceSkillsDir = path.join(FREYA_WORKSPACE, 'skills');
+        const runtimeSkillsDir = path.join(FREYA_HOME, 'skills');
+        const configSkillsPath = path.join(FREYA_HOME, 'config', 'skills.json');
         try {
             await fs.mkdir(runtimeSkillsDir, { recursive: true });
             await this.loadSkillsFromDirectory(defaultSkillsDir, 'builtin', context);
+            const resolvedDefault = path.resolve(defaultSkillsDir);
+            const resolvedWorkspace = path.resolve(workspaceSkillsDir);
+            const resolvedRuntime = path.resolve(runtimeSkillsDir);
+            if (resolvedWorkspace !== resolvedDefault && resolvedWorkspace !== resolvedRuntime) {
+                await this.loadSkillsFromDirectory(workspaceSkillsDir, 'workspace', context);
+            }
             await this.loadSkillsFromDirectory(runtimeSkillsDir, 'runtime', context);
             let configList = [];
             try {
@@ -61,14 +68,17 @@ export class FreyaSkillRegistry {
                     if (metadata.id) {
                         const defaultEnabled = metadata.defaultEnabled !== undefined
                             ? metadata.defaultEnabled !== 'false'
-                            : source === 'builtin';
+                            : source !== 'runtime';
+                        const existing = this.skills.get(metadata.id);
+                        const finalSource = existing?.source === 'builtin' ? 'builtin' : source;
+                        const finalEnabled = existing !== undefined ? existing.enabled : defaultEnabled;
                         this.skills.set(metadata.id, {
                             id: metadata.id,
                             name: metadata.name || file.replace('.md', ''),
                             description: metadata.description || '',
                             content: content.trim(),
-                            enabled: defaultEnabled,
-                            source
+                            enabled: finalEnabled,
+                            source: finalSource
                         });
                     }
                 }
@@ -105,7 +115,7 @@ export class FreyaSkillRegistry {
             return `ℹ️ 技能 "${skill.name || skillId}" 状态已是 ${enabled ? '启用' : '禁用'}。`;
         }
         skill.enabled = enabled;
-        const configSkillsPath = path.join(PROJECT_ROOT, 'config', 'skills.json');
+        const configSkillsPath = path.join(FREYA_HOME, 'config', 'skills.json');
         try {
             await this.persistSkillsConfig(configSkillsPath);
             this.context?.logger.info(`技能 "${skill.name || skillId}" 已切换为: ${enabled ? '启用' : '禁用'}`);

package/core/dist/utils/paths.d.ts

@@ -1,4 +1,6 @@
-/** 运行态下的项目根目录（数据与配置存放区） */
-export declare const PROJECT_ROOT: string;
+/** 运行态持久化主目录（数据与配置存放区） */
+export declare const FREYA_HOME: string;
 /** 程序代码物理安装根目录（只读代码与包内默认资源区） */
-export declare const APP_ROOT: string;
+export declare const FREYA_APP: string;
+/** 宿主工程/工作区根目录（业务工程代码与定制资源区） */
+export declare const FREYA_WORKSPACE: string;

package/core/dist/utils/paths.js

@@ -3,11 +3,9 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import fs from 'node:fs';
 const customHome = process.env.FREYA_HOME;
+const customApp = process.env.FREYA_APP;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function resolveAppRoot() {
-    if (process.env.FREYA_APP_ROOT) {
-        return path.resolve(process.env.FREYA_APP_ROOT);
-    }
     let current = __dirname;
     let coreDir = current;
     while (current) {
@@ -32,9 +30,15 @@ function resolveAppRoot() {
     }
     return coreDir;
 }
-/** 运行态下的项目根目录（数据与配置存放区） */
-export const PROJECT_ROOT = customHome
+/** 运行态持久化主目录（数据与配置存放区） */
+export const FREYA_HOME = customHome
     ? path.resolve(customHome)
     : path.join(os.homedir(), '.freya');
 /** 程序代码物理安装根目录（只读代码与包内默认资源区） */
-export const APP_ROOT = resolveAppRoot();
+export const FREYA_APP = customApp
+    ? path.resolve(customApp)
+    : resolveAppRoot();
+/** 宿主工程/工作区根目录（业务工程代码与定制资源区） */
+export const FREYA_WORKSPACE = process.env.FREYA_WORKSPACE
+    ? path.resolve(process.env.FREYA_WORKSPACE)
+    : process.cwd();

package/core/dist/web/web-container.js

@@ -3,7 +3,7 @@ import fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import http from 'node:http';
 import path from 'node:path';
-import { APP_ROOT } from '../utils/paths.js';
+import { FREYA_APP } from '../utils/paths.js';
 const mimeTypes = {
     '.html': 'text/html; charset=utf-8',
     '.css': 'text/css; charset=utf-8',
@@ -36,7 +36,7 @@ export class FreyaWebContainer {
     async start(ctx, configManager) {
         this.port = ctx.config?.server?.port ?? 3000;
         this.configApi = new FreyaConfigApi(configManager);
-        const uiDist = this.getUiDistPath(APP_ROOT);
+        const uiDist = this.getUiDistPath(FREYA_APP);
         const safePrefix = uiDist.endsWith(path.sep) ? uiDist : uiDist + path.sep;
         this.httpServer = http.createServer(async (req, res) => {
             if (this.configApi) {
@@ -103,9 +103,9 @@ export class FreyaWebContainer {
             }
         });
     }
-    getUiDistPath(projectRoot) {
-        const devPath = path.join(projectRoot, 'packages', 'ui', 'dist');
-        const prodPath = path.join(projectRoot, 'ui');
+    getUiDistPath(appRoot) {
+        const devPath = path.join(appRoot, 'packages', 'ui', 'dist');
+        const prodPath = path.join(appRoot, 'ui');
         if (fsSync.existsSync(devPath))
             return devPath;
         return prodPath;

package/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eoasmxd/freya-core",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -16,7 +16,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.3",
+    "@eoasmxd/freya-sdk": "^0.5.0",
     "ws": "^8.18.0"
   },
   "devDependencies": {

package/doc/specifications/config-spec.md

@@ -46,7 +46,7 @@ Freya 规范在项目运行根目录下划分了四个功能性区域：
 1.  **Workspace（工作区）**：与宿主隔离的沙箱目录，默认 FS 工具只能读写此目录（`~/.freya/workspace/`）下的文件。
 2.  **Runtime Config（配置目录）**：存放用户的个性化配置，统一保存在运行时目录的 `~/.freya/config/` 下。
 3.  **Runtime Data（数据目录）**：存放运行时持久化的业务状态、历史记录及数据库文件，统一保存在运行时目录的 `~/.freya/data/` 下。
-4.  **Runtime Skills（运行时技能卡）**：存放用户自定义技能卡的目录，位于 `~/.freya/skills/` 下。系统在启动时，会同时扫描程序包内置技能目录（`APP_ROOT/skills/`）与此目录下的 Markdown 文件进行双通道动态合并加载。
+4.  **Runtime Skills（运行时技能卡）**：存放用户自定义技能卡的目录，位于 `~/.freya/skills/` 下。系统在启动时，会同时扫描程序包内置技能目录（`FREYA_APP/skills/`）与此目录下的 Markdown 文件进行双通道动态合并加载。
 
 ---
 

package/doc/tutorials/part1_react/3.2_decoupled_architecture.md

@@ -114,7 +114,7 @@ export class FreyaPromptManager {
   constructor(private promptRegistry: FreyaPromptRegistry) {}
 
   async writePrompt(name: string, content: string): Promise<string> {
-    const runFilePath = path.join(PROJECT_ROOT, 'config', `${name.toUpperCase()}.md`);
+    const runFilePath = path.join(FREYA_HOME, 'config', `${name.toUpperCase()}.md`);
 
     // 1. 异步物理落盘保存
     await fs.mkdir(path.dirname(runFilePath), { recursive: true });

package/doc/tutorials/part1_react/3.3_freya_dual_read_probe.md

@@ -61,7 +61,7 @@ export class FreyaPromptRegistry {
 ### 物理设计优势：
 这种双读探针（Dual-Read）的设计在生产部署中极为强大：
 1.  **物理防呆与降级**：即使管理员在运行时把外置的配置文件误删了，底座也不会挂起报错，而是会自动回退加载只读包内的默认模板。
-2.  **安全隔离**：核心程序包（`APP_ROOT`）可以被设置为只读挂载（在 Docker 容器等环境中），而所有用户配置（`PROJECT_ROOT`）写在隔离的宿主持久化目录中。
+2.  **安全隔离**：核心程序包（`FREYA_APP`）可以被设置为只读挂载（在 Docker 容器等环境中），而所有用户配置（`FREYA_HOME`）写在隔离的宿主持久化目录中。
 
 ---
 

package/doc/tutorials/part3_memory/6.2_physical_sandbox_separation.md

@@ -69,18 +69,18 @@ description: "阐述数据（Data）、配置（Config）与源码（Code）物
 为了让这一套沙箱架构在开发环境和云端生产环境都能“开箱即用”，底座必须在启动时能够动态定位并自初始化这一套目录结构。
 
 ### 1. 动态定位机制
-在 Freya 源码 `packages/core/src/utils/paths.ts` 中，底座通过检测环境变量 `FREYA_HOME` 或用户系统 Home 目录，定义了运行态根目录 `PROJECT_ROOT` 以及程序代码物理安装根目录 `APP_ROOT`：
+在 Freya 源码 `packages/core/src/utils/paths.ts` 中，底座通过检测环境变量 `FREYA_HOME` 或用户系统 Home 目录，定义了运行态根目录 `FREYA_HOME` 以及程序代码物理安装根目录 `FREYA_APP`：
 
 ```typescript
 const customHome = process.env.FREYA_HOME;
 
 /** 运行态下的项目根目录（数据与配置存放区） */
-export const PROJECT_ROOT = customHome
+export const FREYA_HOME = customHome
   ? path.resolve(customHome)
   : path.join(os.homedir(), '.freya');
 
 /** 程序代码物理安装根目录（只读代码与包内默认资源区） */
-export const APP_ROOT = resolveAppRoot();
+export const FREYA_APP = resolveAppRoot();
 ```
 
 ### 2. 各模块按需自检初始化 (On-Demand Initialization)
@@ -89,7 +89,7 @@ export const APP_ROOT = resolveAppRoot();
 例如，在负责多轮会话持久化存储的 `packages/core/src/session/persistence.ts` 模块中：
 
 ```typescript
-const sessionDirByUuid = (uuid: string) => path.join(PROJECT_ROOT, 'data', 'sessions', uuid);
+const sessionDirByUuid = (uuid: string) => path.join(FREYA_HOME, 'data', 'sessions', uuid);
 
 // 在写入会话时，若相应目录不存在，则在底层自动按需创建
 await fs.mkdir(sessionDirByUuid(uuid), { recursive: true });
@@ -98,7 +98,7 @@ await fs.mkdir(sessionDirByUuid(uuid), { recursive: true });
 同样地，在负责动态技能扫描的 `packages/core/src/skill/skill-registry.ts` 模块中：
 
 ```typescript
-const runtimeSkillsDir = path.join(PROJECT_ROOT, 'skills');
+const runtimeSkillsDir = path.join(FREYA_HOME, 'skills');
 // 自检并按需自动创建运行时用户技能卡目录
 await fs.mkdir(runtimeSkillsDir, { recursive: true });
 ```

package/doc/tutorials/part5_plugins/10.1_microkernel_decoupling.md

@@ -83,10 +83,11 @@ export interface Logger {
 }
 
 export interface FreyaPaths {
-  appRoot: string;      // 程序物理安装根目录
-  projectRoot: string;  // 运行态主目录 (默认 ~/.freya)
-  dataDir: string;      // 运行时数据持久化目录
-  workspaceDir: string; // 隔离的读写文件沙箱
+  appRoot: string;       // 程序物理安装根目录
+  homeDir: string;       // 运行态持久化主目录 (默认 ~/.freya)
+  workspaceRoot: string; // 宿主工程根目录 (默认 process.cwd())
+  dataDir: string;       // 运行时数据持久化目录
+  workspaceDir: string;  // 隔离的读写文件沙箱
 }
 
 export interface FreyaContext {

package/freya.js

@@ -106,13 +106,24 @@ await checkSingleInstance();
 const cliEnabled = await getCliEnabled(process.argv);
 const isForeground = isForegroundMode(process.argv);
 
+let appRoot = __dirname;
+try {
+  const stat = await fs.stat(path.join(__dirname, 'plugins'));
+  if (!stat.isDirectory()) {
+    appRoot = path.resolve(__dirname, '..');
+  }
+} catch {
+  appRoot = path.resolve(__dirname, '..');
+}
+
 if (!cliEnabled && !isForeground) {
   const child = fork(coreIndex, process.argv.slice(2), {
     detached: true,
     stdio: 'ignore',
     env: {
       ...process.env,
-      FREYA_APP_ROOT: __dirname
+      FREYA_APP: process.env.FREYA_APP || appRoot,
+      FREYA_WORKSPACE: process.env.FREYA_WORKSPACE || process.cwd()
     }
   });
 
@@ -130,7 +141,8 @@ if (!cliEnabled && !isForeground) {
     stdio: 'inherit',
     env: {
       ...process.env,
-      FREYA_APP_ROOT: __dirname
+      FREYA_APP: process.env.FREYA_APP || appRoot,
+      FREYA_WORKSPACE: process.env.FREYA_WORKSPACE || process.cwd()
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eoasmxd/freya",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "Freya - 微内核智能体系统",
@@ -35,7 +35,7 @@
     "src"
   ],
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.3",
+    "@eoasmxd/freya-sdk": "^0.5.0",
     "ws": "^8.18.0",
     "mysql2": "^3.11.0",
     "qrcode": "^1.5.4"

package/plugins/plugin-gemini/package.json

@@ -18,7 +18,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.3"
+    "@eoasmxd/freya-sdk": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",