Version 1.0.3 is expected to be released.

Author: PythonnotJava

assets/default_skills/toolshell/SKILL.md

@@ -81,12 +81,17 @@
 
 ### 1. 创建 (Create)
 
-在工作目录下选一个临时目录搭建技能骨架（推荐 `.toolshell/skills/<技能名>/`，便于即时调试）：
+在工作目录下的 **staging 目录** `.toolshell/_staging/<技能名>/` 搭建技能骨架：
 - `SKILL.md`（必需）：清晰写明技能用途、触发条件、使用指南
 - `tools.json`（可选）：若技能需要自定义工具，按 OpenAI function 格式声明
 
 用 `toolshell_write` 写入这些文件。
 
+> 为什么用 `.toolshell/_staging/` 而**不是** `.toolshell/skills/`？
+> `.toolshell/skills/` 会被扫描成"项目级临时技能"并恒定激活——若把 /skill-cti 的产物放那里，
+> 它既会作为项目技能加载、装到全局后又会作为全局技能加载，造成**双重加载**（工具名注册两遍）。
+> `_staging` 不会被扫描，纯粹用于搭建/自测；装到全局后该目录会被自动清理。
+
 ### 2. 测试 (Test)
 
 安装到全局**之前**必须自测，确认技能可用：
@@ -96,19 +101,20 @@
 
 ### 3. 安装到全局 (Install)
 
-自测通过后，调用 `toolshell_install_skill`，把临时技能目录提升为**全局技能**：
+自测通过后，调用 `toolshell_install_skill`，把 staging 技能目录提升为**全局技能**：
 
 ```
-toolshell_install_skill(source_dir="<技能目录绝对路径>", name="<技能名>")
+toolshell_install_skill(source_dir="<staging 技能目录绝对路径>", name="<技能名>")
 ```
 
-- 全局技能落在应用的 `Skills/` 目录，**不是** `.toolshell/skills/`
-- 安装后该技能出现在技能页，可在任意工作目录启用复用
-- 安装成功后告知用户技能名、用途，并提示可在技能页管理
+- 全局技能落在应用的 `Skills/` 目录，**不是** `.toolshell/`
+- 安装后该技能出现在技能页，由用户自行开关，可在任意工作目录复用
+- 安装成功后 `.toolshell/_staging/<技能名>/` 会被**自动清理**，不在工作目录留副本
+- 安装成功后告知用户技能名、用途，并提示可在技能页管理与开关
 
 注意区分两类技能去向：
-- **临时调试 / 仅本目录用** → 放 `.toolshell/skills/`（项目级，跟随工作目录）
-- **沉淀为可复用能力** → 用 `toolshell_install_skill` 装到全局 `Skills/`
+- **仅本目录长期使用的项目规范** → 放 `.toolshell/skills/`（项目级，跟随工作目录，恒定激活）
+- **沉淀为全局可复用能力**（/skill-cti 的目标）→ 在 `.toolshell/_staging/` 搭建并自测，再用 `toolshell_install_skill` 装到全局 `Skills/`，由用户开关
 
 ## 记忆系统
 

lib/core/agent/agent_context.dart

@@ -1,4 +1,5 @@
 import 'dart:convert';
+import 'dart:io';
 
 import 'package:flutter/services.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
@@ -15,6 +16,7 @@ import '../memory/project_config.dart';
 import '../memory/qdrant_service.dart';
 import '../search/search_capability.dart';
 import '../skill/skill_model.dart';
+import '../skill/skill_registry.dart';
 import '../toolshell/agent_loop.dart';
 import '../toolshell/executor.dart';
 import '../../providers/database_provider.dart';
@@ -179,6 +181,15 @@ class AgentContextBuilder {
     final capabilities = _collectCapabilities();
     final customHandlers = <String, CustomToolHandler>{};
 
+    // 技能安装工具 (toolshell_install_skill): 把工作目录里临时做好的技能
+    // 提升到全局技能库。仅在工作目录模式注册 (其工具定义也只在 toolshell/tools.json)。
+    if (_ref.read(workingDirectoryProvider).isNotEmpty) {
+      final registry = _ref.read(skillRegistryProvider);
+      customHandlers['toolshell_install_skill'] = (args) =>
+          _installSkill(registry, args);
+      toolSourceMapping['toolshell_install_skill'] = '元技能:ToolShell';
+    }
+
     for (final cap in capabilities) {
       if (!cap.isActive) continue;
       // 注册工具定义
@@ -291,15 +302,109 @@ class AgentContextBuilder {
 
   Map<String, String> _lastSourceMapping = {};
 
+  /// 自定义工具 `toolshell_install_skill` 的执行体。
+  ///
+  /// 把工作目录里临时做好的技能目录 (须直接含 SKILL.md) 提升为全局技能，
+  /// 落在 `Skills/` 目录、出现在技能页。安装后刷新 [skillsProvider] 让技能页即时更新。
+  ///
+  /// 安装成功后，若源目录位于 `<工作目录>/.toolshell/` 内（即模型用 /skill-cti 流程
+  /// 搭建的临时 staging 目录），会删除该源目录——技能从"项目临时"毕业为"全局可复用"，
+  /// 不在工作目录留副本。这样避免同一技能被项目技能扫描器重复加载（双载）。
+  /// 内容已存入全局 Skills/，删除不丢数据；仅删模型显式传入、且确属工作目录 .toolshell 下的目录。
+  ///
+  /// 返回 JSON 字符串供模型解析。
+  Future<String> _installSkill(
+    SkillRegistry registry,
+    Map<String, dynamic> args,
+  ) async {
+    final sourceDir = (args['source_dir'] as String?)?.trim() ?? '';
+    final name = (args['name'] as String?)?.trim();
+    if (sourceDir.isEmpty) {
+      return jsonEncode({
+        'status': 'error',
+        'message': '缺少必需参数 source_dir (技能源目录的绝对路径)',
+      });
+    }
+    try {
+      final skill = await registry.installFromDirectory(
+        sourceDir,
+        name: (name != null && name.isNotEmpty) ? name : null,
+      );
+      // 刷新技能页数据源，让新技能立即出现在技能管理 UI
+      _ref.invalidate(skillsProvider);
+      AppLogger.instance.log(
+        '[AgentContext] 技能已安装到全局: ${skill.name} (${skill.path})',
+      );
+
+      // 清理 staging 源目录：仅当其位于 <工作目录>/.toolshell/ 内时删除，
+      // 避免技能在工作目录里残留成无法关闭的项目临时副本（导致双载）。
+      final cleaned = await _cleanupStagingDir(sourceDir);
+      if (cleaned) {
+        _ref.invalidate(projectSkillsProvider);
+      }
+
+      return jsonEncode({
+        'status': 'ok',
+        'name': skill.name,
+        'path': skill.path,
+        'tool_count': skill.toolCount,
+        'staging_cleaned': cleaned,
+        'message': '技能「${skill.name}」已安装到全局技能库，可在技能页管理并在任意工作目录复用'
+            '${cleaned ? "（工作目录的临时副本已清理）" : ""}。',
+      });
+    } catch (e) {
+      AppLogger.instance.log('[AgentContext] 技能安装失败: $e');
+      return jsonEncode({'status': 'error', 'message': '安装失败: $e'});
+    }
+  }
+
+  /// 若 [sourceDir] 位于当前工作目录的 `.toolshell/` 下，则删除它并返回 true；
+  /// 否则不动并返回 false。用于 /skill-cti 安装后清理临时 staging 目录。
+  ///
+  /// 边界保护：解析为绝对/规范化路径后，严格校验 sourceDir 在
+  /// `<工作目录>/.toolshell/` 之内，绝不删除工作目录本身或其外部路径。
+  Future<bool> _cleanupStagingDir(String sourceDir) async {
+    try {
+      final workDir = _ref.read(workingDirectoryProvider);
+      if (workDir.isEmpty) return false;
+
+      final toolshellRoot = p.canonicalize(p.join(workDir, '.toolshell'));
+      final src = p.canonicalize(sourceDir);
+
+      // src 必须严格在 .toolshell/ 之内（且不等于 .toolshell 本身）
+      final isInside = p.isWithin(toolshellRoot, src);
+      if (!isInside) return false;
+
+      final dir = Directory(src);
+      if (await dir.exists()) {
+        await dir.delete(recursive: true);
+        AppLogger.instance.log('[AgentContext] 已清理 staging 技能目录: $src');
+        return true;
+      }
+      return false;
+    } catch (e) {
+      AppLogger.instance.log('[AgentContext] 清理 staging 目录失败(忽略): $e');
+      return false;
+    }
+  }
+
   /// 合并全局技能与项目级临时技能，供 Agent 运行时统一消费。
   ///
   /// 全局技能来自 [skillsProvider]（技能页可管理），项目技能来自
   /// [projectSkillsProvider]（仅扫描工作目录 `.toolshell/skills/`，恒定激活）。
   /// 两者数据源隔离：项目技能只在此处合并挂载，不污染任何全局技能管理 UI。
+  ///
+  /// 去重安全网：项目技能与全局技能同名时丢弃项目版（全局优先）。避免某技能既装到
+  /// 全局、又在工作目录 `.toolshell/skills/` 留有同名副本时被重复加载（工具名注册两遍、
+  /// 提示词注入两段）。这是纯内存去重，不删除任何文件。
   List<Skill> _collectAllSkills() {
     final global = _ref.read(skillsProvider).valueOrNull ?? const [];
     final project = _ref.read(projectSkillsProvider).valueOrNull ?? const [];
-    return [...global, ...project];
+    final globalNames = global.map((s) => s.name).toSet();
+    final dedupedProject = project
+        .where((s) => !globalNames.contains(s.name))
+        .toList();
+    return [...global, ...dedupedProject];
   }
 
   Future<List<Map<String, dynamic>>> _loadTools() async {

lib/core/skill/skill_registry.dart

@@ -194,6 +194,68 @@ class SkillRegistry {
     return skill;
   }
 
+  /// 从普通目录安装技能到全局技能库 (应用支持目录/Skills 或设置指定目录)。
+  ///
+  /// 用于把工作目录里临时做好的技能 (如 `.toolshell/skills/<名字>/`) "提升"为
+  /// 全局技能：递归复制目录内容到 `Skills/<名字>/`，并补写 `.skill_meta.json`。
+  /// 与 [importFromZip] 共享同一套元数据与加载逻辑，安装后即出现在技能页。
+  ///
+  /// [sourceDir] 源技能目录，必须直接包含 SKILL.md。
+  /// [name] 可选的目标技能名 (默认取源目录名)。
+  /// 已存在同名全局技能目录时覆盖。
+  Future<Skill> installFromDirectory(String sourceDir, {String? name}) async {
+    final src = Directory(sourceDir);
+    if (!await src.exists()) {
+      throw Exception('源目录不存在: $sourceDir');
+    }
+    final srcSkillMd = File(p.join(src.path, 'SKILL.md'));
+    if (!await srcSkillMd.exists()) {
+      throw Exception('源目录缺少 SKILL.md，无法识别为技能: $sourceDir');
+    }
+
+    final skillName = (name != null && name.trim().isNotEmpty)
+        ? name.trim()
+        : p.basename(src.path);
+    final skillId = _uuid.v4();
+    final skillsDir = await getSkillsDir();
+    final skillDir = Directory(p.join(skillsDir.path, skillName));
+
+    // 已存在同名目录则覆盖
+    if (await skillDir.exists()) {
+      await skillDir.delete(recursive: true);
+    }
+    await skillDir.create(recursive: true);
+
+    // 递归复制源目录内容 (跳过源自带的 .skill_meta.json，下面重写)
+    await for (final entity in src.list(recursive: true)) {
+      final rel = p.relative(entity.path, from: src.path);
+      if (rel == '.skill_meta.json') continue;
+      final outPath = p.join(skillDir.path, rel);
+      if (entity is Directory) {
+        await Directory(outPath).create(recursive: true);
+      } else if (entity is File) {
+        await File(outPath).parent.create(recursive: true);
+        await entity.copy(outPath);
+      }
+    }
+
+    // 写入元数据
+    final meta = {
+      'id': skillId,
+      'installed_at': DateTime.now().toIso8601String(),
+      'is_active': true,
+      'sort_index': await _nextSortIndex(),
+    };
+    final metaFile = File(p.join(skillDir.path, '.skill_meta.json'));
+    await metaFile.writeAsString(jsonEncode(meta));
+
+    final skill = await _loadSkillFromDir(skillDir);
+    if (skill == null) {
+      throw Exception('技能加载失败');
+    }
+    return skill;
+  }
+
   /// 删除技能
   Future<void> remove(String skillId) async {
     final skills = await listInstalled();