@eoasmxd/freya 0.3.0 → 0.4.1

package/README.md

@@ -59,11 +59,17 @@ pnpm start
 
 为了便于开发者深入了解 Freya 的底座原理与扩展机制，系统在 [doc/](doc/_index.md) 物理目录下提供了完整的技术文档库：
 
-* 🏗️ **[架构设计说明](doc/architecture-design.md)**：包含 Monorepo 物理结构、核心 ReAct 调用链路图、核心组件职责及 EventBus 异步通信机制。
-* ⚙️ **[配置与数据隔离规范](doc/config-spec.md)**：介绍 `~/.freya/` 运行时目录结构、配置/数据物理隔离及 Schema 动态合并策略。
-* 📝 **[提示词管理系统](doc/prompt-system.md)**：介绍 6 大维度提示词管理方案、动态 Prompt Composer 拼装结构与 Dual-Read 探针机制。
+### 🛠️ 技术规范与指南
+
 * 🚀 **[快速使用指引](doc/getting-started.md)**：图形化 LLM 提供商配置、插件开启控制与会话快捷指令。
 * 🛠️ **[安装与构建运行](doc/installation-guide.md)**：分步说明环境准备、安装、编译与控制台开发模式。
+* 🏗️ **[架构设计说明](doc/specifications/architecture-design.md)**：包含 Monorepo 物理结构、核心 ReAct 调用链路图、核心组件职责及 EventBus 异步通信机制。
+* ⚙️ **[配置与数据隔离规范](doc/specifications/config-spec.md)**：介绍 `~/.freya/` 运行时目录结构、配置/数据物理隔离及 Schema 动态合并策略。
+* 📝 **[提示词管理系统](doc/specifications/prompt-system.md)**：介绍 6 大维度提示词管理方案、动态 Prompt Composer 拼装结构与 Dual-Read 探针机制。
+
+### 🎓 白盒开发教程
+
+* 👉 **[智能体开发实战教程](doc/tutorials/_index.md)**：白盒解剖智能体底座，包含 13 个章节硬核教程，从 Next-Token Prediction 到底层 ReAct 循环、多轮会话以及多智能体协同协作等原理解密。
 
 ---
 

package/core/dist/command/commands/skill-commands.js

@@ -10,10 +10,11 @@ export function registerSkillCommands(deps) {
         return '🔧 当前未激活任何技能。';
     };
     const handleList = async () => {
-        if (skills.size === 0) {
+        const activeSkills = Array.from(skills.values()).filter((s) => s.enabled !== false);
+        if (activeSkills.length === 0) {
             return '📋 暂无可用技能。';
         }
-        const lines = Array.from(skills.values()).map((s) => `- **${s.name}** — ${s.description || '无描述'}`).join('\n');
+        const lines = activeSkills.map((s) => `- **${s.name}** \`${s.id}\` — ${s.description || '无描述'}`).join('\n');
         return `### 📋 可用技能\n\n${lines}`;
     };
     const handleSet = async (skillId, sessionId) => {
@@ -21,8 +22,8 @@ export function registerSkillCommands(deps) {
             return '❌ 用法：`\`/skill set <skillId>\``。';
         }
         const skill = skills.get(skillId);
-        if (!skill) {
-            return `❌ 技能 \`${skillId}\` 不存在。请使用 \`/skill list\` 查看可用技能。`;
+        if (!skill || skill.enabled === false) {
+            return `❌ 技能 \`${skillId}\` 不存在或未启用。请使用 \`/skill list\` 查看可用技能。`;
         }
         await sessionManager.updateSession(sessionId, { activeSkillId: skillId });
         return `✅ 已激活技能: **${skill.name}** \`${skillId}\`。`;

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

@@ -3,6 +3,7 @@ import type { FreyaLLMRegistry } from '../llm/llm-registry.js';
 import type { FreyaPluginManager } from '../plugin/plugin-manager.js';
 import type { FreyaPromptManager } from '../prompt/prompt-manager.js';
 import { FreyaConfigSchemaRegistry } from './schema-registry.js';
+import type { FreyaSkillRegistry, FreyaSkill } from '../skill/skill-registry.js';
 /** 核心统一配置管理器 */
 export declare class FreyaConfigManager {
     private context;
@@ -11,7 +12,8 @@ export declare class FreyaConfigManager {
     private llmRegistry;
     private pluginManager;
     private promptManager;
-    constructor(context: FreyaContext, schemaRegistry: FreyaConfigSchemaRegistry, promptManager: FreyaPromptManager, llmRegistry: FreyaLLMRegistry, pluginManager: FreyaPluginManager);
+    private skillRegistry?;
+    constructor(context: FreyaContext, schemaRegistry: FreyaConfigSchemaRegistry, promptManager: FreyaPromptManager, llmRegistry: FreyaLLMRegistry, pluginManager: FreyaPluginManager, skillRegistry?: FreyaSkillRegistry);
     /** 获取全部敏感字段的 keyPath 列表 */
     getSensitiveKeys(): string[];
     loadAndInit(): Promise<void>;
@@ -38,6 +40,8 @@ export declare class FreyaConfigManager {
     removeModel(providerId: string, modelId: string): Promise<string>;
     listPlugins(): Promise<any[]>;
     togglePlugin(pluginId: string, enabled: boolean): Promise<string>;
+    listSkills(): FreyaSkill[];
+    toggleSkill(skillId: string, enabled: boolean): Promise<string>;
     readPrompt(name: string): Promise<string>;
     writePrompt(name: string, content: string): Promise<string>;
     editPrompt(name: string, targetContent: string, replacementContent: string): Promise<string>;

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

@@ -138,12 +138,14 @@ export class FreyaConfigManager {
     llmRegistry;
     pluginManager;
     promptManager;
-    constructor(context, schemaRegistry, promptManager, llmRegistry, pluginManager) {
+    skillRegistry;
+    constructor(context, schemaRegistry, promptManager, llmRegistry, pluginManager, skillRegistry) {
         this.context = context;
         this.schemaRegistry = schemaRegistry;
         this.promptManager = promptManager;
         this.llmRegistry = llmRegistry;
         this.pluginManager = pluginManager;
+        this.skillRegistry = skillRegistry;
     }
     /** 获取全部敏感字段的 keyPath 列表 */
     getSensitiveKeys() {
@@ -475,6 +477,16 @@ export class FreyaConfigManager {
             return '❌ 插件服务未初始化。';
         return await this.pluginManager.togglePlugin(pluginId, enabled);
     }
+    listSkills() {
+        if (!this.skillRegistry)
+            return [];
+        return this.skillRegistry.getAllSkills();
+    }
+    async toggleSkill(skillId, enabled) {
+        if (!this.skillRegistry)
+            return '❌ 技能注册表服务未初始化。';
+        return await this.skillRegistry.toggleSkill(skillId, enabled);
+    }
     async readPrompt(name) {
         const promptName = String(name).trim().toUpperCase();
         if (!ALLOWED_PROMPTS.has(promptName)) {

package/core/dist/kernel.js

@@ -54,7 +54,7 @@ export class FreyaKernel {
         const promptManager = new FreyaPromptManager(promptRegistry, ctx.logger);
         this.pluginManager = new FreyaPluginManager(configSchemaRegistry, commandRegistry, promptRegistry);
         await this.pluginManager.loadConfiguredPlugins(pluginRegistry, ctx);
-        const configManager = new FreyaConfigManager(ctx, configSchemaRegistry, promptManager, llmRegistry, this.pluginManager);
+        const configManager = new FreyaConfigManager(ctx, configSchemaRegistry, promptManager, llmRegistry, this.pluginManager, skillRegistry);
         configManager.registerCoreSchema();
         await configManager.loadAndInit();
         await configManager.resolveAndFreeze();
@@ -72,7 +72,7 @@ export class FreyaKernel {
         this.connectionManager = new FreyaConnectionManager(ctx.eventBus, ctx.logger);
         const configToolbox = new ConfigToolbox(configManager, ctx);
         const sessionToolbox = new SessionToolbox(this.sessionManager);
-        const metaToolbox = new FreyaMetaToolbox(this.sessionManager, toolRegistry);
+        const metaToolbox = new FreyaMetaToolbox(this.sessionManager, toolRegistry, skillRegistry);
         toolRegistry.registerToolbox(configToolbox);
         toolRegistry.registerToolbox(sessionToolbox);
         toolRegistry.registerToolbox(metaToolbox);

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

@@ -4,14 +4,24 @@ export interface FreyaSkill {
     name: string;
     description: string;
     content: string;
+    enabled: boolean;
+    source: 'builtin' | 'runtime';
 }
-/** 技能注册表，从 skills/ 目录加载 Markdown 格式技能 */
+/** 技能注册表，从 skills/ 目录加载 Markdown 格式技能并管理软开关状态 */
 export declare class FreyaSkillRegistry {
     private skills;
+    private context?;
     loadSkills(context: FreyaContext): Promise<void>;
     /** 从指定目录加载技能到内存注册表中 */
     private loadSkillsFromDirectory;
-    getSkills(): Map<string, FreyaSkill>;
+    /** 获取技能列表（默认只返回启用状态的技能） */
+    getSkills(onlyEnabled?: boolean): Map<string, FreyaSkill>;
+    /** 获取全量技能数组（供管理控制台使用） */
+    getAllSkills(): FreyaSkill[];
+    /** 切换技能的启用/禁用状态并持久化 */
+    toggleSkill(skillId: string, enabled: boolean): Promise<string>;
+    /** 持久化当前所有技能启停状态至 skills.json */
+    private persistSkillsConfig;
     get(id: string): FreyaSkill | undefined;
     has(id: string): boolean;
     /** 解析技能文件的 YAML Frontmatter */

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

@@ -1,24 +1,57 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { APP_ROOT, PROJECT_ROOT } from '../utils/paths.js';
-/** 技能注册表，从 skills/ 目录加载 Markdown 格式技能 */
+/** 技能注册表，从 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');
         try {
             await fs.mkdir(runtimeSkillsDir, { recursive: true });
-            await this.loadSkillsFromDirectory(defaultSkillsDir, context);
-            await this.loadSkillsFromDirectory(runtimeSkillsDir, context);
-            context.logger.info(`动态技能扫描完成。共加载了 ${this.skills.size} 个物理技能。`);
+            await this.loadSkillsFromDirectory(defaultSkillsDir, 'builtin', context);
+            await this.loadSkillsFromDirectory(runtimeSkillsDir, 'runtime', context);
+            let configList = [];
+            try {
+                const raw = await fs.readFile(configSkillsPath, 'utf-8');
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed)) {
+                    configList = parsed;
+                }
+            }
+            catch {
+                configList = [];
+            }
+            const configMap = new Map();
+            for (const item of configList) {
+                if (item && typeof item.id === 'string' && typeof item.enabled === 'boolean') {
+                    configMap.set(item.id, item.enabled);
+                }
+            }
+            let configChanged = false;
+            for (const skill of this.skills.values()) {
+                if (configMap.has(skill.id)) {
+                    skill.enabled = configMap.get(skill.id);
+                }
+                else {
+                    configChanged = true;
+                }
+            }
+            if (configChanged || configList.length !== this.skills.size) {
+                await this.persistSkillsConfig(configSkillsPath);
+            }
+            const enabledCount = Array.from(this.skills.values()).filter((s) => s.enabled).length;
+            context.logger.info(`动态技能扫描完成。共加载 ${this.skills.size} 个物理技能 (已启用: ${enabledCount})。`);
         }
         catch (err) {
             context.logger.error('扫描物理技能 skills 目录遭遇故障:', err);
         }
     }
     /** 从指定目录加载技能到内存注册表中 */
-    async loadSkillsFromDirectory(dirPath, context) {
+    async loadSkillsFromDirectory(dirPath, source, context) {
         try {
             const files = await fs.readdir(dirPath);
             for (const file of files) {
@@ -26,11 +59,16 @@ export class FreyaSkillRegistry {
                     const rawContent = await fs.readFile(path.join(dirPath, file), 'utf-8');
                     const { metadata, content } = this.parseFrontmatter(rawContent);
                     if (metadata.id) {
+                        const defaultEnabled = metadata.defaultEnabled !== undefined
+                            ? metadata.defaultEnabled !== 'false'
+                            : source === 'builtin';
                         this.skills.set(metadata.id, {
                             id: metadata.id,
                             name: metadata.name || file.replace('.md', ''),
                             description: metadata.description || '',
-                            content: content.trim()
+                            content: content.trim(),
+                            enabled: defaultEnabled,
+                            source
                         });
                     }
                 }
@@ -40,8 +78,51 @@ export class FreyaSkillRegistry {
             context.logger.warn(`扫描技能目录失败: ${dirPath}`, err);
         }
     }
-    getSkills() {
-        return this.skills;
+    /** 获取技能列表（默认只返回启用状态的技能） */
+    getSkills(onlyEnabled = true) {
+        if (!onlyEnabled) {
+            return this.skills;
+        }
+        const filtered = new Map();
+        for (const [id, skill] of this.skills.entries()) {
+            if (skill.enabled) {
+                filtered.set(id, skill);
+            }
+        }
+        return filtered;
+    }
+    /** 获取全量技能数组（供管理控制台使用） */
+    getAllSkills() {
+        return Array.from(this.skills.values());
+    }
+    /** 切换技能的启用/禁用状态并持久化 */
+    async toggleSkill(skillId, enabled) {
+        const skill = this.skills.get(skillId);
+        if (!skill) {
+            return `❌ 未找到 ID 为 "${skillId}" 的技能，请检查名称是否正确。`;
+        }
+        if (skill.enabled === enabled) {
+            return `ℹ️ 技能 "${skill.name || skillId}" 状态已是 ${enabled ? '启用' : '禁用'}。`;
+        }
+        skill.enabled = enabled;
+        const configSkillsPath = path.join(PROJECT_ROOT, 'config', 'skills.json');
+        try {
+            await this.persistSkillsConfig(configSkillsPath);
+            this.context?.logger.info(`技能 "${skill.name || skillId}" 已切换为: ${enabled ? '启用' : '禁用'}`);
+            return `✅ 技能 "${skill.name || skillId}" 已成功${enabled ? '启用' : '禁用'}。`;
+        }
+        catch (err) {
+            return `❌ 技能状态变更成功，但写入 skills.json 失败: ${err.message}`;
+        }
+    }
+    /** 持久化当前所有技能启停状态至 skills.json */
+    async persistSkillsConfig(configSkillsPath) {
+        await fs.mkdir(path.dirname(configSkillsPath), { recursive: true });
+        const payload = Array.from(this.skills.values()).map((s) => ({
+            id: s.id,
+            enabled: s.enabled
+        }));
+        await fs.writeFile(configSkillsPath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
     }
     get(id) {
         return this.skills.get(id);

package/core/dist/tools/meta/index.d.ts

@@ -1,10 +1,12 @@
 import type { FreyaTool, FreyaToolbox } from '@eoasmxd/freya-sdk';
 import type { FreyaSessionManager } from '../../session/session-manager.js';
 import type { FreyaToolRegistry } from '../tool-registry.js';
+import type { FreyaSkillRegistry } from '../../skill/skill-registry.js';
 export declare class FreyaMetaToolbox implements FreyaToolbox {
     private sessionManager;
     private toolRegistry?;
-    constructor(sessionManager: FreyaSessionManager, toolRegistry?: FreyaToolRegistry | undefined);
+    private skillRegistry?;
+    constructor(sessionManager: FreyaSessionManager, toolRegistry?: FreyaToolRegistry | undefined, skillRegistry?: FreyaSkillRegistry | undefined);
     getId(): string;
     getInstructionPrompt(): string;
     getTools(): FreyaTool[];

package/core/dist/tools/meta/index.js

@@ -1,9 +1,11 @@
 export class FreyaMetaToolbox {
     sessionManager;
     toolRegistry;
-    constructor(sessionManager, toolRegistry) {
+    skillRegistry;
+    constructor(sessionManager, toolRegistry, skillRegistry) {
         this.sessionManager = sessionManager;
         this.toolRegistry = toolRegistry;
+        this.skillRegistry = skillRegistry;
     }
     getId() {
         return 'meta';
@@ -99,6 +101,12 @@ export class FreyaMetaToolbox {
                     if (!sessionId) {
                         return '❌ 错误：无法从执行上下文中提取当前会话ID。';
                     }
+                    if (this.skillRegistry) {
+                        const skill = this.skillRegistry.get(skillId);
+                        if (!skill || !skill.enabled) {
+                            return `❌ 错误：技能 [${skillId}] 不存在或已被系统管理员禁用，无法切入该模式。`;
+                        }
+                    }
                     await this.sessionManager.updateSession(sessionId, { activeSkillId: skillId });
                     return `已成功切入 [${skillId}] 技能特长工作模式。`;
                 }

package/core/dist/web/config-api.js

@@ -177,6 +177,24 @@ export class FreyaConfigApi {
                 res.end(JSON.stringify({ success: !msg.startsWith('❌'), message: msg }));
                 return true;
             }
+            if (pathname === '/api/config/skills' && req.method === 'GET') {
+                const skills = this.configManager.listSkills();
+                res.writeHead(200, this.headers);
+                res.end(JSON.stringify({ success: true, data: skills }));
+                return true;
+            }
+            if (pathname === '/api/config/skills/toggle' && req.method === 'POST') {
+                const { skillId, enabled } = await this.getBody(req);
+                if (!skillId) {
+                    res.writeHead(200, this.headers);
+                    res.end(JSON.stringify({ success: false, error: '缺少必要参数: skillId' }));
+                    return true;
+                }
+                const msg = await this.configManager.toggleSkill(skillId, enabled);
+                res.writeHead(200, this.headers);
+                res.end(JSON.stringify({ success: !msg.startsWith('❌'), message: msg }));
+                return true;
+            }
             const promptMatch = pathname.match(/^\/api\/config\/prompts\/([^/]+)$/);
             if (promptMatch && req.method === 'GET') {
                 const promptName = decodeURIComponent(promptMatch[1]);

package/core/package.json

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

package/doc/_index.md

@@ -10,17 +10,30 @@ description: "Freya 项目技术文档与开发使用指南。"
 
 ## 📖 文档导航
 
-- 🏗️ **[Freya 架构设计说明](architecture-design.md)**
+### 🚀 快速开始
+
+- 🧭 **[快速使用指引](getting-started.md)**
+  提供系统首次启动配置、插件管理与日常操作快捷指令。
+
+- 🛠️ **[安装与构建运行](installation-guide.md)**
+  提供开发环境要求、本地依赖安装、项目编译打包与服务运行调试指南。
+
+### 🏗️ 技术规范与设计参考
+
+- 🧱 **[Freya 架构设计说明](specifications/architecture-design.md)**
   介绍系统的物理模块划分、核心组件职责分工、调用执行链路与异步通信机制。
 
-- ⚙️ **[配置与数据隔离规范](config-spec.md)**
+- ⚙️ **[配置与数据隔离规范](specifications/config-spec.md)**
   介绍系统的运行时目录结构、配置与数据的隔离设计及初始化合并规范。
 
-- 📝 **[提示词管理系统说明](prompt-system.md)**
+- 📝 **[提示词管理系统说明](specifications/prompt-system.md)**
   介绍多维度提示词管理方案、运行时 Prompt 拼装结构与动态加载覆盖机制。
 
-- 🚀 **[快速使用指引](getting-started.md)**
-  提供系统首次启动配置、插件管理与日常操作快捷指令。
+- 🎛️ **[大模型接口参数规范](specifications/llm-interface-params.md)**
+  介绍大语言模型统一代理层的配置参数与多厂商协议适配规则。
+
+### 🎓 开发实战教程
+
+- 📚 **[智能体通用原理与开发实战](tutorials/_index.md)**
+  完全以智能体通用底层原理、通信协议与架构机制为主线的白盒实战开发教程。
 
-- 🛠️ **[安装与构建运行](installation-guide.md)**
-  提供开发环境要求、本地依赖安装、项目编译打包与服务运行调试指南。

package/doc/getting-started.md

@@ -1,5 +1,5 @@
 ---
-title: "Freya 快速使用指引"
+title: "快速使用指引"
 weight: 30
 description: "介绍如何配置大模型 API Key、开启插件功能以及在控制台使用快捷指令。"
 ---

package/doc/installation-guide.md

@@ -1,10 +1,10 @@
 ---
-title: "Freya 安装与维护完全指南"
+title: "安装与构建运行"
 weight: 20
 description: "提供环境准备、NPM 全局安装与源码构建运行的完整安装、日常启动、服务停止及手动版本更新指南。"
 ---
 
-# Freya 安装与维护完全指南
+# Freya 安装与构建运行
 
 ## 1. 环境准备
 

package/doc/{architecture-design.md → specifications/architecture-design.md}

@@ -1,5 +1,5 @@
 ---
-title: "Freya 架构设计说明"
+title: "架构设计说明"
 weight: 10
 description: "说明项目目录结构、~/.freya 运行时存放规则、插件依赖界限、核心 ReAct 调用链路与 EventBus 异步解耦模式。"
 ---
@@ -41,15 +41,18 @@ freya/
 │   ├── sdk/                     # 插件开发标准 SDK
 │   │   ├── src/
 │   │   │   ├── index.ts         # 模块入口与集中导出
-│   │   │   └── types.ts         # 统一的接口定义
+│   │   │   └── types/           # 统一的接口定义目录
 │   │   └── package.json
 │   │
 │   └── ui/                      # 独立的前端 Web 交互页面
 │       └── package.json
 │
 ├── plugins/                     # 插件根目录
+│   ├── plugin-gemini/           # Gemini 大模型插件
 │   ├── plugin-openai/           # 对接 OpenAI 标准 API 的大模型插件
 │   ├── plugin-telegram-channel/ # Telegram 频道插件
+│   ├── plugin-wecom-channel/    # 企业微信频道插件
+│   ├── plugin-weixin-channel/   # 微信频道插件
 │   ├── plugin-tool-fs/          # 文件系统工具插件
 │   ├── plugin-tool-memory/      # 记忆工具插件
 │   └── plugin-tool-web/         # 网页工具插件
@@ -115,8 +118,8 @@ graph TD
 
 底座组件之间跨边界异步通信统一通过 **`EventBus` (事件总线)** 异步事件驱动：
 
-*   **出站路由**：`Agent` 推理产生的流式 Delta 或最终文本不会被直接投递给 `Channel`。底座仅需广播 `'connection:reply'` / `'connection:reply:delta'` 事件；各个 `Channel` 插件自行订阅事件，读取对应的 `channelId` 并各自向用户的物理长连接发送。
-*   **多方协同与计费解耦**：当大模型输出产生 `'token:consumed'` 事件时，计费服务（Billing）通过订阅该事件核算费用并广播计费结果，底座连接层再通过 `'connection:event'` 向前端 WebSocket 实时推送 Token 账单与费用通知。
+*   **出站路由**：`Agent` 推理产生的流式 Delta 或最终文本不会被直接投递给 `Channel`。底座仅需广播 `'connection:reply'` / `'connection:reply:delta'` 事件；各个 `Channel` 插件自行订阅事件，读取对应的 `connectionId`（连接 ID）过滤并各自向用户的物理长连接发送。
+*   **多方协同与计费解耦**：当大模型输出产生 `'token:consumed'` 事件时，计费服务（Billing）通过订阅该事件核算费用并触发 `'billing:session:add'`。会话管理器（SessionManager）监听该事件累加更新会话数据后广播 `'session:billing:update'`，最终底座连接层捕获此更新并通过 `'connection:event'` 向前端 WebSocket 实时推送 `server:billing` 事件。
 
 
 ---

package/doc/{config-spec.md → specifications/config-spec.md}

@@ -1,5 +1,5 @@
 ---
-title: "Freya 配置与数据隔离规范"
+title: "配置与数据隔离规范"
 weight: 15
 description: "介绍 ~/.freya/ 运行时目录结构、配置/数据物理隔离及 Schema 动态合并策略。"
 ---

package/doc/{llm-interface-params.md → specifications/llm-interface-params.md}

@@ -1,5 +1,5 @@
 ---
-title: "Freya LLM 插件调用接口与参数规范"
+title: "LLM 插件调用接口与参数规范"
 weight: 18
 description: "定义 Freya 统一的大模型（LLM）插件调用接口参数规范。"
 ---
@@ -18,7 +18,7 @@ description: "定义 Freya 统一的大模型（LLM）插件调用接口参数
 async chat(
   messages: LLMMessage[],
   tools?: ToolDefinition[],
-  options?: LLMOptions
+  options?: LLMPluginOptions
 ): Promise<{
   message: LLMMessage;
   usage?: LLMTokenUsage;
@@ -31,7 +31,7 @@ async chat(
 
 为了屏蔽不同大模型服务商在参数命名上的差异（如 `max_tokens` 与 `maxOutputTokens`），Freya 规定了一套**驼峰命名（CamelCase）**的通用生成参数标准。
 
-在调用 `llm.chat` 时，应通过 `options.modelParams` 传递这些参数。各插件仅负责从其中提取支持的驼峰属性，并准确转换为服务商 API 要求的格式。
+在调用 `llm.chat` 时，应通过 `options.modelParams` 传递这些参数。各插件仅负责从其中提取支持的属性，并准确转换为服务商 API 要求的格式。
 
 ### 统一参数字段一览
 
@@ -87,22 +87,22 @@ if (typeof params.maxTokens === 'number' && params.maxTokens > 0) {
 
 ---
 
-## 4. 大模型消息结构与属性规范 (`LLMMessage`)
+## 5. 大模型消息结构与属性规范 (`LLMMessage`)
 
 Freya 内核通过统一的 `LLMMessage` 对象来表示对话历史中的每一个消息节点。为了兼容和抽象不同大模型服务商在多轮工具调用（Function Calling）以及推理校验上的核心流派差异，`LLMMessage` 中的主要属性字段定义及职责如下：
 
-### 4.1 基础属性
+### 5.1 基础属性
 *   **`role`** (`'user' | 'assistant' | 'system' | 'tool'`)：消息在对话中的角色。
     *   *映射规范*：对于不支持显式 `'tool'` 角色的厂商 API（如 Gemini REST 接口），插件层应当在转换对话历史时将其统一映射为 `"user"` 以符合接口的协议规范。
 *   **`content`** (`string`)：消息的文本正文。
-*   **`attachments`** (`ChannelAttachment[]`)：消息附带的多模态附件（如图像等）。
+*   **`attachments`** (`FreyaAttachment[]`)：消息附带的多模态附件（如图像等）。
 
-### 4.2 工具调用关联属性（基于 ID 关联流派）
+### 5.2 工具调用关联属性（基于 ID 关联流派）
 主要服务于以 OpenAI 协议为代表、在多轮工具调用中通过特定的**唯一 ID** 关联工具调用与工具执行结果的流派：
 *   **`toolCalls`** (`LLMToolCall[]`)：大模型在 `'assistant'` 消息中输出的工具调用指令列表。每个 `LLMToolCall` 包含 `id`、`name`（工具名）与 `arguments`（参数）。
 *   **`toolCallId`** (`string`)：在 `'tool'` 角色的消息中，用来指定该条工具执行结果所对应的工具调用 `id`。
 
-### 4.3 推理校验与工具原名属性（基于名称与签名校验流派）
+### 5.3 推理校验与工具原名属性（基于名称与签名校验流派）
 主要服务于以 Gemini 协议为代表、在多轮工具调用中通过**工具名称**关联响应，且必须回传推理状态签名的流派：
 *   **`thoughtSignature`** (`string`)：由支持 stateless 思考（Reasoning）的模型在响应中输出的加密思考签名。
     *   *插件职责*：解析响应时，将模型返回的签名捕获并挂载在 `message.thoughtSignature` 根属性上；回传历史消息时，按照厂商 API 规定的结构（如 Gemini 要求其作为同级属性嵌套在对应的 `functionCall` Part 元素中并列发送）回传。

package/doc/{prompt-system.md → specifications/prompt-system.md}

@@ -1,5 +1,5 @@
 ---
-title: "Freya 提示词管理系统说明"
+title: "提示词管理系统说明"
 weight: 16
 description: "介绍 6 大维度提示词管理方案、动态 Prompt Composer 拼装结构与 Dual-Read 探针机制。"
 ---