@ww_nero/mini-cli 1.0.77 → 1.0.78

package/README.md

@@ -22,3 +22,19 @@
 ## 会话历史
 - 每个工作目录的历史记录保存在 `~/.mini/cli/<workspace-hash>/YYYYMMDDHHMMSS.json` 中。
 - 可通过 `mini --resume` 自动载入最近一次会话，或在对话中使用 `/resume` 按序号恢复。
+
+## Skills 支持
+- `mini` 会自动扫描 `~/.mini/skills/*/SKILL.md` 作为可用 skills。
+- 当你在提问中明确提到某个 skill 名称，或任务明显匹配某个 skill 描述时，模型会优先读取并遵循对应 skill。
+- 运行时可通过内置 `skills` 工具读取指定 skill 下的文件（默认 `SKILL.md`）。
+- 推荐目录结构示例：
+
+```text
+~/.mini/skills/
+  algorithmic-art/
+    SKILL.md
+    assets/
+    scripts/
+  docx/
+    SKILL.md
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ww_nero/mini-cli",
-  "version": "1.0.77",
+  "version": "1.0.78",
   "description": "极简的 AI 命令行助手",
   "bin": {
     "mini": "bin/mini.js"

package/src/chat.js

@@ -38,6 +38,7 @@ const {
   refreshHistoryFilePath
 } = require('./utils/history');
 const { selectFromList } = require('./utils/menu');
+const { discoverSkills, buildSkillsSystemPrompt } = require('./utils/skills');
 
 const CURSOR_STYLE_CODES = {
   default: '\u001B[0 q',
@@ -81,6 +82,25 @@ const appendMiniInstructions = (baseContent, workspaceRoot) => {
   return `${baseContent}\n\n${sections.join('\n\n')}`;
 };
 
+const appendSkillsInstructions = (baseContent) => {
+  const snapshot = discoverSkills();
+  const skillsSection = buildSkillsSystemPrompt(snapshot);
+
+  if (!skillsSection) {
+    return {
+      content: baseContent,
+      snapshot,
+      enabled: false
+    };
+  }
+
+  return {
+    content: `${baseContent}\n\n${skillsSection}`,
+    snapshot,
+    enabled: true
+  };
+};
+
 const formatWriteOutput = (result) => {
   if (!result || typeof result !== 'object' || !result.success) {
     return null;
@@ -254,7 +274,9 @@ const startChatSession = async ({
   if (initialCommitCreated) {
     console.log(chalk.gray('已创建初始提交：init project。'));
   }
-  const systemPromptContent = appendMiniInstructions(toolSystemPrompt, workspaceRoot);
+  const basePromptContent = appendMiniInstructions(toolSystemPrompt, workspaceRoot);
+  const skillsPromptResult = appendSkillsInstructions(basePromptContent);
+  const systemPromptContent = skillsPromptResult.content;
 
   // Load settings to get toolOutputTokenLimit and compactTokenThreshold
   const { settings } = loadSettings();
@@ -557,6 +579,15 @@ const startChatSession = async ({
     console.log(chalk.gray('未启用任何 MCP 服务器'));
   }
 
+  if (skillsPromptResult.snapshot && skillsPromptResult.snapshot.error) {
+    console.log(chalk.yellow(`skills 初始化失败: ${skillsPromptResult.snapshot.error}`));
+  } else if (skillsPromptResult.enabled) {
+    const skillNames = (skillsPromptResult.snapshot.skills || []).map((item) => item.name);
+    console.log(chalk.gray(`可用 skills (${skillNames.length}): ${skillNames.join(', ')}`));
+  } else {
+    console.log(chalk.gray('未发现可用 skills（可在 ~/.mini/skills/<skill>/SKILL.md 添加）'));
+  }
+
   const startupOptions = (Array.isArray(cliOptions) && cliOptions.length > 0) ? cliOptions : CLI_OPTIONS;
   if (startupOptions.length > 0) {
     console.log(chalk.gray('启动参数：'));
@@ -976,6 +1007,11 @@ const startChatSession = async ({
               if (toolContent) {
                 console.log(chalk.gray(`  ${toolContent}`));
               }
+            } else if (functionName === 'skills') {
+              const preview = truncateForDisplay(toolContent, 200);
+              if (preview) {
+                console.log(chalk.gray(`  ${preview}`));
+              }
             } else {
               // For other tools, show preview in gray
               const preview = truncateForDisplay(toolContent, 100);

package/src/tools/bash.js

@@ -106,7 +106,7 @@ const executeCommand = async ({ command, workingDirectory = '.', isService = fal
 
 const createBashToolSchema = () => {
   const descriptionParts = ['在指定目录运行 bash 命令，支持使用 && / || 连接多个命令。'];
-  descriptionParts.push('isService=true 时在后台运行服务，等待 5 秒返回初始输出，进程继续运行并持续捕获输出；默认等待命令执行完成，超时为 300 秒。');
+  descriptionParts.push('isService=true 时在后台运行服务，等待 5 秒返回初始输出，之后服务进程继续运行；默认等待命令执行完成，超时为 300 秒。');
 
   return {
     type: 'function',

package/src/tools/index.js

@@ -3,10 +3,11 @@ const read = require('./read');
 const write = require('./write');
 const replace = require('./replace');
 const todos = require('./todos');
+const skills = require('./skills');
 const { createMcpManager } = require('./mcp');
 const { loadSettings } = require('../config');
 
-const TOOL_MODULES = [bash, read, write, replace, todos];
+const TOOL_MODULES = [bash, read, write, replace, todos, skills];
 
 const createToolRuntime = async (workspaceRoot, options = {}) => {
   const defaultToolNames = TOOL_MODULES.map((tool) => tool.name);

package/src/tools/skills.js

@@ -0,0 +1,49 @@
+const { readSkillFile, toDisplayPath, SKILL_ENTRY_FILE } = require('../utils/skills');
+
+const handler = async ({ skillName, filePath } = {}) => {
+  try {
+    const result = readSkillFile({
+      skillName,
+      filePath
+    });
+
+    return {
+      success: true,
+      skillsRoot: toDisplayPath(result.skillsRoot),
+      skillName: result.skillName,
+      filePath: result.filePath,
+      absolutePath: result.absoluteFilePath,
+      content: result.content
+    };
+  } catch (error) {
+    return `读取 skill 失败：${error.message}`;
+  }
+};
+
+const schema = {
+  type: 'function',
+  function: {
+    name: 'skills',
+    description: '读取 ~/.mini/skills 下指定 skill 的文件内容（默认入口文件为 SKILL.md）',
+    parameters: {
+      type: 'object',
+      properties: {
+        skillName: {
+          type: 'string',
+          description: 'skill 名称'
+        },
+        filePath: {
+          type: 'string',
+          description: `相对于 skill 目录的文件路径，默认 ${SKILL_ENTRY_FILE}`
+        }
+      },
+      required: ['skillName']
+    }
+  }
+};
+
+module.exports = {
+  name: 'skills',
+  schema,
+  handler
+};

package/src/utils/skills.js

@@ -0,0 +1,250 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MINI_DIR_NAME = '.mini';
+const SKILLS_DIR_NAME = 'skills';
+const SKILL_ENTRY_FILE = 'SKILL.md';
+const MAX_DESCRIPTION_LENGTH = 160;
+
+const getSkillsRoot = () => path.join(os.homedir(), MINI_DIR_NAME, SKILLS_DIR_NAME);
+
+const toDisplayPath = (targetPath = '') => {
+  const absolutePath = path.resolve(String(targetPath || ''));
+  const homePath = path.resolve(os.homedir());
+  const relativePath = path.relative(homePath, absolutePath);
+
+  if (relativePath === '') {
+    return '~';
+  }
+
+  if (!relativePath.startsWith('..') && !path.isAbsolute(relativePath)) {
+    return `~/${relativePath.split(path.sep).join('/')}`;
+  }
+
+  return absolutePath;
+};
+
+const isPathInside = (basePath, targetPath) => {
+  const relativePath = path.relative(path.resolve(basePath), path.resolve(targetPath));
+  return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+};
+
+const trimDescription = (text = '') => {
+  const normalized = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!normalized) {
+    return '';
+  }
+  if (normalized.length <= MAX_DESCRIPTION_LENGTH) {
+    return normalized;
+  }
+  return `${normalized.slice(0, MAX_DESCRIPTION_LENGTH)}...`;
+};
+
+const extractDescription = (content = '') => {
+  const normalized = String(content || '').replace(/\r/g, '');
+  if (!normalized.trim()) {
+    return '';
+  }
+
+  const taggedPattern = /^\s*(?:description|desc|简介|说明)\s*[:：]\s*(.+)$/im;
+  const taggedMatch = normalized.match(taggedPattern);
+  if (taggedMatch && taggedMatch[1]) {
+    return trimDescription(taggedMatch[1]);
+  }
+
+  const lines = normalized.split('\n');
+  let inCodeBlock = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (line.startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+
+    if (!line || inCodeBlock) {
+      continue;
+    }
+
+    if (
+      line.startsWith('#')
+      || line.startsWith('-')
+      || line.startsWith('*')
+      || line.startsWith('>')
+      || /^\d+[.)]\s/.test(line)
+    ) {
+      continue;
+    }
+
+    return trimDescription(line);
+  }
+
+  return '';
+};
+
+const discoverSkills = () => {
+  const skillsRoot = getSkillsRoot();
+
+  if (!fs.existsSync(skillsRoot)) {
+    return {
+      skillsRoot,
+      skills: []
+    };
+  }
+
+  let entries = [];
+
+  try {
+    entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+  } catch (error) {
+    return {
+      skillsRoot,
+      skills: [],
+      error: `读取 skills 目录失败：${error.message}`
+    };
+  }
+
+  const skills = entries
+    .filter((entry) => entry && entry.isDirectory() && !entry.name.startsWith('.'))
+    .map((entry) => {
+      const skillDirPath = path.join(skillsRoot, entry.name);
+      const entryFilePath = path.join(skillDirPath, SKILL_ENTRY_FILE);
+
+      if (!fs.existsSync(entryFilePath)) {
+        return null;
+      }
+
+      let description = '';
+      try {
+        const content = fs.readFileSync(entryFilePath, 'utf8');
+        description = extractDescription(content);
+      } catch (_) {
+        description = '';
+      }
+
+      return {
+        name: entry.name,
+        description,
+        dirPath: skillDirPath,
+        entryFilePath
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  return {
+    skillsRoot,
+    skills
+  };
+};
+
+const resolveSkillDirectory = (skillsRoot, skillName) => {
+  if (typeof skillName !== 'string' || !skillName.trim()) {
+    throw new Error('skillName 参数不能为空');
+  }
+
+  const normalizedName = skillName.trim();
+  const skillDirPath = path.resolve(skillsRoot, normalizedName);
+
+  if (!isPathInside(skillsRoot, skillDirPath)) {
+    throw new Error('skillName 非法，不能超出 skills 目录');
+  }
+
+  if (path.resolve(path.dirname(skillDirPath)) !== path.resolve(skillsRoot)) {
+    throw new Error('skillName 必须是 skills 目录下的直接子目录名');
+  }
+
+  if (!fs.existsSync(skillDirPath) || !fs.statSync(skillDirPath).isDirectory()) {
+    throw new Error(`skill 不存在: ${normalizedName}`);
+  }
+
+  return {
+    skillName: normalizedName,
+    skillDirPath
+  };
+};
+
+const resolveSkillFilePath = (skillDirPath, filePath = SKILL_ENTRY_FILE) => {
+  const normalizedFilePath = typeof filePath === 'string' && filePath.trim()
+    ? filePath.trim()
+    : SKILL_ENTRY_FILE;
+
+  if (path.isAbsolute(normalizedFilePath)) {
+    throw new Error('filePath 必须是相对于 skill 目录的路径');
+  }
+
+  const absoluteFilePath = path.resolve(skillDirPath, normalizedFilePath);
+
+  if (!isPathInside(skillDirPath, absoluteFilePath)) {
+    throw new Error('filePath 非法，不能超出 skill 目录');
+  }
+
+  if (!fs.existsSync(absoluteFilePath) || !fs.statSync(absoluteFilePath).isFile()) {
+    throw new Error(`文件不存在: ${normalizedFilePath}`);
+  }
+
+  const relativeFilePath = path.relative(skillDirPath, absoluteFilePath).split(path.sep).join('/');
+
+  return {
+    absoluteFilePath,
+    relativeFilePath
+  };
+};
+
+const readSkillFile = ({ skillName, filePath } = {}) => {
+  const skillsRoot = getSkillsRoot();
+  if (!fs.existsSync(skillsRoot)) {
+    throw new Error(`skills 目录不存在: ${toDisplayPath(skillsRoot)}`);
+  }
+
+  const { skillName: normalizedSkillName, skillDirPath } = resolveSkillDirectory(skillsRoot, skillName);
+  const { absoluteFilePath, relativeFilePath } = resolveSkillFilePath(skillDirPath, filePath);
+  const content = fs.readFileSync(absoluteFilePath, 'utf8');
+
+  return {
+    skillsRoot,
+    skillName: normalizedSkillName,
+    skillDirPath,
+    filePath: relativeFilePath,
+    absoluteFilePath,
+    content
+  };
+};
+
+const buildSkillsSystemPrompt = (snapshot = {}) => {
+  const skills = Array.isArray(snapshot.skills) ? snapshot.skills : [];
+  if (skills.length === 0) {
+    return '';
+  }
+
+  const lines = [
+    '<skills>',
+    `skills 目录: ${toDisplayPath(snapshot.skillsRoot || getSkillsRoot())}`,
+    '当用户明确提到某个 skill，或任务明显匹配某个 skill 描述时，优先使用该 skill。',
+    'skill 使用流程：',
+    '1. 先调用 skills 工具读取对应 skill 的 SKILL.md。',
+    '2. 若 SKILL.md 引用其他文件，再调用 skills 工具按需读取。',
+    '3. 仅加载当前任务需要的内容，避免无关读取。',
+    '可用 skills：'
+  ];
+
+  skills.forEach((skill) => {
+    const description = skill.description || '（暂无描述）';
+    lines.push(`- ${skill.name}: ${description}`);
+  });
+
+  lines.push('</skills>');
+
+  return lines.join('\n');
+};
+
+module.exports = {
+  SKILL_ENTRY_FILE,
+  getSkillsRoot,
+  discoverSkills,
+  readSkillFile,
+  toDisplayPath,
+  buildSkillsSystemPrompt
+};