Version 1.0.3 is expected to be released.

PythonnotJava · PythonnotJava · commit f77c50f47285 · 2026-06-25T11:14:09.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 - 提供了在线访问Agent的功能.
 - 优化了上下文压缩.
+- 在工作目录下创建、使用临时技能进行临时性自我进化
 
 ## en
 
diff --git a/assets/default_skills/toolshell/SKILL.md b/assets/default_skills/toolshell/SKILL.md
@@ -56,6 +56,25 @@
 - `*.pem` / `*.key` 私钥文件
 - 项目根目录之外的任何路径
 
+## 项目级临时技能 (.toolshell/skills/)
+
+当你需要为**当前工作目录**创建一个专属的、可复用的技能时（例如把一段常用流程固化成工具，或为这个项目沉淀一套操作规范），按以下约定放置，应用会在下次构建上下文时自动加载：
+
+```
+<工作目录>/.toolshell/skills/<技能名>/
+    SKILL.md       # 必需：技能说明与使用指南（会注入到系统提示词）
+    tools.json     # 可选：自定义工具定义（OpenAI function 格式）
+```
+
+规则：
+- **必需** `SKILL.md`，缺失则该目录不会被识别为技能
+- `tools.json` 可选；若提供，其中声明的工具会一并注册，仍通过 toolshell 执行并受权限约束
+- 这类技能**只在所属工作目录下生效**，恒定处于激活状态，无需用户在技能页手动启用
+- 切换到其他工作目录后自动消失，不影响全局技能
+- 不要把项目技能放到其他位置（如工作目录根、随意命名的文件夹）——只有 `.toolshell/skills/` 会被扫描
+
+创建技能后，告知用户该技能已就绪、将在新对话或下一轮上下文构建时自动加载。
+
 ## 记忆系统
 
 ### 存储位置
diff --git a/lib/core/agent/agent_context.dart b/lib/core/agent/agent_context.dart
@@ -14,6 +14,7 @@ import '../memory/memory_manager.dart';
 import '../memory/project_config.dart';
 import '../memory/qdrant_service.dart';
 import '../search/search_capability.dart';
+import '../skill/skill_model.dart';
 import '../toolshell/agent_loop.dart';
 import '../toolshell/executor.dart';
 import '../../providers/database_provider.dart';
@@ -210,9 +211,8 @@ class AgentContextBuilder {
         PermissionMiddleware(onPermissionRequest: onPermissionRequest),
     ];
 
-    // ─── 收集 skill 可读路径 ───
-    final skillsState = _ref.read(skillsProvider);
-    final activeSkillPaths = (skillsState.valueOrNull ?? [])
+    // ─── 收集 skill 可读路径 (全局 + 项目级) ───
+    final activeSkillPaths = _collectAllSkills()
         .where((s) => s.isActive && s.path.isNotEmpty)
         .map((s) => s.path)
         .toList();
@@ -291,6 +291,17 @@ class AgentContextBuilder {
 
   Map<String, String> _lastSourceMapping = {};
 
+  /// 合并全局技能与项目级临时技能，供 Agent 运行时统一消费。
+  ///
+  /// 全局技能来自 [skillsProvider]（技能页可管理），项目技能来自
+  /// [projectSkillsProvider]（仅扫描工作目录 `.toolshell/skills/`，恒定激活）。
+  /// 两者数据源隔离：项目技能只在此处合并挂载，不污染任何全局技能管理 UI。
+  List<Skill> _collectAllSkills() {
+    final global = _ref.read(skillsProvider).valueOrNull ?? const [];
+    final project = _ref.read(projectSkillsProvider).valueOrNull ?? const [];
+    return [...global, ...project];
+  }
+
   Future<List<Map<String, dynamic>>> _loadTools() async {
     final tools = <Map<String, dynamic>>[];
     final sourceMapping = <String, String>{};
@@ -332,10 +343,9 @@ class AgentContextBuilder {
       tools.addAll(sysTools);
     }
 
-    // 用户技能
+    // 用户技能 (全局 + 项目级临时技能)
     final registry = _ref.read(skillRegistryProvider);
-    final skillsState = _ref.read(skillsProvider);
-    final skills = skillsState.valueOrNull ?? [];
+    final skills = _collectAllSkills();
     final allSkillNames = skills
         .map((s) => '${s.name}(${s.isActive ? "激活" : "未启用"})')
         .toList();
@@ -382,9 +392,9 @@ class AgentContextBuilder {
 
   /// 计算当前激活用户技能的轻量签名。
   /// 用于判断会话中途技能集合是否变化，决定是否需要刷新 system prompt。
-  /// 与 [_buildSkillsSection] 的数据来源保持一致。
+  /// 与 [_buildSkillsSection] 的数据来源保持一致（全局 + 项目级）。
   String computeSkillSignature() {
-    final skills = _ref.read(skillsProvider).valueOrNull ?? [];
+    final skills = _collectAllSkills();
     final active =
         skills
             .where((s) => s.isActive)
@@ -438,8 +448,7 @@ class AgentContextBuilder {
   Future<String> _buildSkillsSection() async {
     final parts = <String>[];
     final registry = _ref.read(skillRegistryProvider);
-    final skillsState = _ref.read(skillsProvider);
-    final skills = skillsState.valueOrNull ?? [];
+    final skills = _collectAllSkills();
     for (final skill in skills) {
       if (!skill.isActive) continue;
       final prompt = await registry.loadSkillPrompt(skill);
diff --git a/lib/core/skill/skill_model.dart b/lib/core/skill/skill_model.dart
@@ -10,6 +10,11 @@ class Skill {
   final DateTime installedAt;
   final int sortIndex;
 
+  /// 是否为项目级临时技能 (来自工作目录的 .toolshell/skills/)。
+  /// 此类技能在所属工作目录下恒定激活，不参与全局启用/停用，
+  /// 且生命周期跟随工作目录 (切换目录即消失，不可删除/排序)。
+  final bool isProjectLevel;
+
   const Skill({
     required this.id,
     required this.name,
@@ -20,6 +25,7 @@ class Skill {
     this.isBuiltIn = false,
     required this.installedAt,
     this.sortIndex = 0,
+    this.isProjectLevel = false,
   });
 
   Skill copyWith({bool? isActive, int? sortIndex}) {
@@ -33,6 +39,7 @@ class Skill {
       isBuiltIn: isBuiltIn,
       installedAt: installedAt,
       sortIndex: sortIndex ?? this.sortIndex,
+      isProjectLevel: isProjectLevel,
     );
   }
 }
diff --git a/lib/core/skill/skill_registry.dart b/lib/core/skill/skill_registry.dart
@@ -64,6 +64,68 @@ class SkillRegistry {
     return skills;
   }
 
+  /// 项目级临时技能目录的相对路径约定: `<workDir>/.toolshell/skills/`
+  static const projectSkillsRelPath = '.toolshell/skills';
+
+  /// 扫描工作目录下的项目级临时技能 (`.toolshell/skills/<名字>/`)。
+  ///
+  /// 与全局技能不同:
+  /// - 不要求 .skill_meta.json (模型/用户手建时通常不会写)
+  /// - 恒定 isActive=true、isProjectLevel=true
+  /// - id 用 "project:<目录名>" 前缀，避免与全局技能 id 冲突
+  /// - 生命周期跟随工作目录，不写入/不修改任何元数据
+  ///
+  /// [workDir] 为空或目录不存在时返回空列表。
+  Future<List<Skill>> listProjectSkills(String workDir) async {
+    if (workDir.isEmpty) return [];
+
+    final dir = Directory(p.join(workDir, '.toolshell', 'skills'));
+    if (!await dir.exists()) return [];
+
+    final skills = <Skill>[];
+    await for (final entity in dir.list()) {
+      if (entity is! Directory) continue;
+      final skillMdFile = File(p.join(entity.path, 'SKILL.md'));
+      if (!await skillMdFile.exists()) continue;
+
+      final name = p.basename(entity.path);
+
+      // 统计工具数量 (tools.json 可选)
+      int toolCount = 0;
+      final toolsJsonFile = File(p.join(entity.path, 'tools.json'));
+      if (await toolsJsonFile.exists()) {
+        try {
+          final tools = jsonDecode(await toolsJsonFile.readAsString()) as List;
+          toolCount = tools.length;
+        } catch (_) {}
+      }
+
+      DateTime installedAt = DateTime.now();
+      try {
+        installedAt = await skillMdFile
+            .lastModified()
+            .timeout(const Duration(seconds: 2));
+      } catch (_) {}
+
+      skills.add(
+        Skill(
+          id: 'project:$name',
+          name: name,
+          description: '',
+          path: entity.path,
+          toolCount: toolCount,
+          isActive: true, // 项目技能恒定激活
+          installedAt: installedAt,
+          sortIndex: 0,
+          isProjectLevel: true,
+        ),
+      );
+    }
+
+    skills.sort((a, b) => a.name.compareTo(b.name));
+    return skills;
+  }
+
   /// 从 ZIP 文件导入技能
   Future<Skill> importFromZip(String zipPath) async {
     final zipFile = File(zipPath);
diff --git a/lib/features/chat/chat_provider.dart b/lib/features/chat/chat_provider.dart
@@ -17,6 +17,7 @@ import '../../core/utils/file_processor.dart';
 import '../../core/pet/pet_observer.dart';
 import '../../providers/database_provider.dart';
 import '../../providers/settings_provider.dart';
+import '../../providers/skills_provider.dart';
 export '../../providers/session_provider.dart';
 
 /// UI 中用于展示的工具调用信息
@@ -386,6 +387,19 @@ class ChatNotifier extends StateNotifier<ChatState> {
       ];
     }
 
+    // ─── 重扫项目级临时技能目录,感知中途变化 ───
+    // 模型可能在上一轮用 toolshell_write 往工作目录的 .toolshell/skills/
+    // 写入了新的项目级技能。这里强制重建 projectSkillsProvider 让其重扫磁盘,
+    // 使新技能的工具与 SKILL.md 在本轮就能生效。
+    // 项目技能与全局技能数据源隔离,重扫不影响全局技能管理 UI。
+    // 技能集合未变时,下方的签名比对会保持 prompt cache,无额外开销。
+    try {
+      _ref.invalidate(projectSkillsProvider);
+      await _ref.read(projectSkillsProvider.future);
+    } catch (e) {
+      print('[SKILL] 重扫项目技能失败(忽略): $e');
+    }
+
     // ─── 使用 AgentContext 构建执行环境 ───
     final contextBuilder = AgentContextBuilder(_ref);
     final agentContext = await contextBuilder.build(
diff --git a/lib/features/skills/skills_page.dart b/lib/features/skills/skills_page.dart
@@ -189,7 +189,9 @@ class _SkillCardTile extends ConsumerWidget {
             Row(
               children: [
                 Icon(
-                  skill.isBuiltIn ? Icons.lock : Icons.extension,
+                  skill.isProjectLevel
+                      ? Icons.folder_special
+                      : (skill.isBuiltIn ? Icons.lock : Icons.extension),
                   size: 18,
                   color: skill.isActive ? colorScheme.primary : Colors.grey,
                 ),
@@ -204,7 +206,25 @@ class _SkillCardTile extends ConsumerWidget {
                     overflow: TextOverflow.ellipsis,
                   ),
                 ),
-                if (skill.isBuiltIn)
+                if (skill.isProjectLevel)
+                  Container(
+                    padding: const EdgeInsets.symmetric(
+                      horizontal: 6,
+                      vertical: 2,
+                    ),
+                    decoration: BoxDecoration(
+                      color: colorScheme.tertiaryContainer,
+                      borderRadius: BorderRadius.circular(4),
+                    ),
+                    child: Text(
+                      '项目',
+                      style: TextStyle(
+                        fontSize: 10,
+                        color: colorScheme.onTertiaryContainer,
+                      ),
+                    ),
+                  )
+                else if (skill.isBuiltIn)
                   Container(
                     padding: const EdgeInsets.symmetric(
                       horizontal: 6,
@@ -246,7 +266,7 @@ class _SkillCardTile extends ConsumerWidget {
               children: [
                 Switch(
                   value: skill.isActive,
-                  onChanged: skill.isBuiltIn
+                  onChanged: (skill.isBuiltIn || skill.isProjectLevel)
                       ? null
                       : (_) => ref
                             .read(skillsProvider.notifier)
@@ -259,14 +279,14 @@ class _SkillCardTile extends ConsumerWidget {
                   visualDensity: VisualDensity.compact,
                   onPressed: () => _showSkillMd(context, ref),
                 ),
-                if (!skill.isBuiltIn)
+                if (!skill.isBuiltIn && !skill.isProjectLevel)
                   IconButton(
                     icon: const Icon(Icons.edit_outlined, size: 18),
                     tooltip: context.s.skillsEditDesc,
                     visualDensity: VisualDensity.compact,
                     onPressed: () => _editDescription(context, ref),
                   ),
-                if (!skill.isBuiltIn)
+                if (!skill.isBuiltIn && !skill.isProjectLevel)
                   IconButton(
                     icon: const Icon(Icons.delete_outline, size: 18),
                     tooltip: context.s.commonDelete,
diff --git a/lib/providers/skills_provider.dart b/lib/providers/skills_provider.dart
@@ -2,6 +2,7 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../core/skill/skill_model.dart';
 import '../core/skill/skill_registry.dart';
+import '../features/chat/chat_provider.dart';
 import 'settings_provider.dart';
 
 /// 技能注册表 Provider
@@ -11,7 +12,11 @@ final skillRegistryProvider = Provider<SkillRegistry>((ref) {
   return SkillRegistry(skillsPath: skillsPath);
 });
 
-/// 技能列表 Provider
+/// 全局技能列表 Provider
+///
+/// 仅包含用户安装的全局技能 (应用支持目录/Skills)。
+/// 不含项目级临时技能 —— 后者由 [projectSkillsProvider] 单独管理，
+/// 避免污染全局技能管理 UI (技能页、对话框技能栏、在线服务技能选择)。
 final skillsProvider = AsyncNotifierProvider<SkillsNotifier, List<Skill>>(
   SkillsNotifier.new,
 );
@@ -66,3 +71,25 @@ class SkillsNotifier extends AsyncNotifier<List<Skill>> {
     await _registry.reorder(ordered.map((s) => s.id).toList());
   }
 }
+
+/// 项目级临时技能 Provider
+///
+/// 扫描当前工作目录的 `.toolshell/skills/`，与全局技能完全隔离。
+/// 这类技能恒定激活、生命周期跟随工作目录，仅供 Agent 运行时挂载，
+/// 不出现在任何全局技能管理 UI 中。
+///
+/// 切换工作目录时自动重建。中途新增技能可由消费方 invalidate 触发重扫。
+final projectSkillsProvider =
+    AsyncNotifierProvider<ProjectSkillsNotifier, List<Skill>>(
+      ProjectSkillsNotifier.new,
+    );
+
+class ProjectSkillsNotifier extends AsyncNotifier<List<Skill>> {
+  @override
+  Future<List<Skill>> build() async {
+    final registry = ref.watch(skillRegistryProvider);
+    // 订阅工作目录：切换目录时项目级技能列表自动重建
+    final workDir = ref.watch(workingDirectoryProvider);
+    return registry.listProjectSkills(workDir);
+  }
+}
