codemini-cli 0.4.1 → 0.4.2

package/OPERATIONS.md

@@ -202,8 +202,10 @@ or revise/discard before execution:
 ```powershell
 codemini skill list
 codemini skill inspect superpowers-lite
-codemini skill enable brainstorm
-codemini skill disable brainstorm
+codemini skill install .\my-skill
+codemini skill install --scope=global .\my-skill
+codemini skill enable my-skill
+codemini skill disable my-skill
 codemini skill reindex
 ```
 

package/README.md

@@ -16,7 +16,7 @@ CodeMini CLI is a terminal coding assistant built for teams that want a sharper,
 
 It is designed around a deliberate idea: most coding workflows do not need a huge default tool surface or unrestricted shell behavior. Instead, CodeMini starts with a compact core, loads advanced tools on demand, and keeps the agent grounded in structured code operations, session todos, lightweight project indexing, and shell-aware safety rules.
 
-**Contents** — [Why CodeMini CLI](#why-codemini-cli) · [Installation](#installation) · [Quick Start](#quick-start) · [Commands](#commands) · [Personalities (Souls)](#personalities-souls) · [Tool Model](#how-the-tool-model-works) · [Core Capabilities](#core-capabilities) · [Dream Loop (Built-in Memory Evolution)](#dream-loop-built-in-memory-evolution) · [Project Index](#project-index) · [Good Fit](#good-fit) · [Documentation](#documentation) · [Development](#development) · [License](#license)
+**Contents** — [Why CodeMini CLI](#why-codemini-cli) · [Installation](#installation) · [Quick Start](#quick-start) · [Commands](#commands) · [Personalities (Souls)](#personalities-souls) · [Tool Model](#how-the-tool-model-works) · [Core Capabilities](#core-capabilities) · [Reflect Skills](#reflect-skills) · [Dream Loop (Built-in Memory Evolution)](#dream-loop-built-in-memory-evolution) · [Project Index](#project-index) · [Good Fit](#good-fit) · [Documentation](#documentation) · [Development](#development) · [License](#license)
 
 ### Why CodeMini CLI
 
@@ -67,6 +67,17 @@ CodeMini CLI can optionally use `fff-mcp` as a faster backend for `grep`, `glob`
 - This means `fff-mcp` is an enhancement, not a hard dependency.
 - `codemini doctor` now reports `FFF MCP availability` so you can verify whether it is active.
 
+### Optional: Playwright Web Rendering
+
+`web_fetch` uses a lightweight `fetch` + HTML parser path by default, so Playwright is not installed as a default dependency.
+
+For JavaScript-rendered pages, install Playwright separately to enable richer browser-rendered fallback:
+
+```bash
+npm install -g playwright
+playwright install chromium
+```
+
 ### Commands
 
 | Command | Description |
@@ -106,10 +117,14 @@ Skills are reusable workflow patterns that guide how the agent approaches differ
 Skills are installed and managed via `codemini skill`:
 
 ```bash
-codemini skill list        # List all available skills
-codemini skill inspect <name>  # Inspect a skill's details
+codemini skill list                         # List builtin, project, and global skills
+codemini skill install <path>               # Install to .codemini/skills by default
+codemini skill install --scope=global <path> # Install to the global skills directory
+codemini skill inspect <name>               # Inspect a skill's details
 ```
 
+Bundled skills are built in, always enabled, and cannot be disabled or overwritten. Third-party skills live either in the project at `.codemini/skills/<name>/SKILL.md` or globally at `<base-config-dir>/skills/<name>/SKILL.md`, matching `/reflect`.
+
 ### How The Tool Model Works
 
 CodeMini CLI intentionally separates tools into two layers:
@@ -149,6 +164,30 @@ Typical flow:
 - Reply language control via `ui.reply_language`
 - Safe mode enabled by default
 
+### Reflect Skills
+
+`/reflect` turns a successful workflow from the current session into a reviewed, reusable `SKILL.md` draft.
+
+It is separate from the dream loop: reflect creates a skill draft, waits for review, and writes only after approval. It does not write inbox memories or run dream consolidation.
+
+Common forms:
+
+```text
+/reflect
+/reflect <what to preserve>
+/reflect --scope=global <what to preserve>
+```
+
+- `/reflect` is exploratory. CodeMini reviews recent context and proposes a skill only when there is a reusable pattern worth saving.
+- `/reflect <what to preserve>` is directed. Use it when you already know which successful chain should become a skill, such as `/reflect preserve the provider tool-call recovery workflow`.
+- `/reflect --scope=global <request>` writes the approved draft to the global skills directory instead of the current project.
+- The draft is previewed first. Use `/yes` to write it, `/edit <feedback>` to revise it, or `/no` to discard it.
+
+Approved skills are written to the same locations used by third-party skill install:
+
+- Project scope: `.codemini/skills/<skill-name>/SKILL.md`
+- Global scope: `<base-config-dir>/skills/<skill-name>/SKILL.md`
+
 ### Dream Loop (Built-in Memory Evolution)
 
 Dream loop is built into the runtime as native tools and slash commands (not a skill-only workflow).
@@ -300,6 +339,17 @@ CodeMini CLI 可以可选地使用 `fff-mcp` 作为 `grep`、`glob` 和部分 `l
 - 这意味着 `fff-mcp` 是增强项，不是硬依赖。
 - 现在可以通过 `codemini doctor` 里的 `FFF MCP availability` 看到它是否可用。
 
+### 可选：Playwright 网页渲染
+
+`web_fetch` 默认使用轻量的 `fetch` + HTML 解析路径，因此 Playwright 不再作为默认依赖安装。
+
+如果经常读取 JavaScript 渲染页面，可以单独安装 Playwright，让 `web_fetch` 在需要时回退到浏览器渲染：
+
+```bash
+npm install -g playwright
+playwright install chromium
+```
+
 ### 命令概览
 
 | 命令 | 说明 |
@@ -339,10 +389,14 @@ Skill 是可复用的工作流模式，指导 agent 如何处理不同类型的
 通过 `codemini skill` 管理技能：
 
 ```bash
-codemini skill list           # 列出所有可用 skill
-codemini skill inspect <name> # 查看某个 skill 的详细信息
+codemini skill list                          # 列出内置、项目级、全局 skill
+codemini skill install <path>                # 默认安装到 .codemini/skills
+codemini skill install --scope=global <path> # 安装到全局 skills 目录
+codemini skill inspect <name>                # 查看某个 skill 的详细信息
 ```
 
+内置 skill 是运行时能力，默认启用，不能禁用或被同名第三方 skill 覆盖。第三方 skill 分为项目级 `.codemini/skills/<name>/SKILL.md` 和全局 `<base-config-dir>/skills/<name>/SKILL.md`，与 `/reflect` 的写入位置一致。
+
 ### 工具模型怎么设计
 
 CodeMini CLI 把工具分成两层：
@@ -382,6 +436,30 @@ CodeMini CLI 把工具分成两层：
 - 支持通过 `ui.reply_language` 控制回复语言
 - safe mode 默认开启
 
+### Reflect Skills（复盘沉淀 Skill）
+
+`/reflect` 可以把当前会话中已经跑通的成功链路沉淀成一个可审阅、可复用的 `SKILL.md` 草稿。
+
+它和 dream loop 是分开的：reflect 只生成 skill 草稿，先让用户审阅，确认后才写文件；不会写入 inbox，也不会触发 dream consolidation。
+
+常用形式：
+
+```text
+/reflect
+/reflect <要沉淀的用户要求>
+/reflect --scope=global <要沉淀的用户要求>
+```
+
+- `/reflect` 是探索模式。CodeMini 会查看近期上下文，只有在确实有可复用模式时才提出 skill 草稿。
+- `/reflect <用户要求>` 是定向模式。适合你已经知道要沉淀哪条成功链路，例如 `/reflect 把刚才 provider tool_call 恢复链路沉淀成 skill`。
+- `/reflect --scope=global <用户要求>` 会把确认后的草稿写到全局 skill 目录，而不是当前项目。
+- 草稿会先预览。用 `/yes` 写入，用 `/edit <反馈>` 修改，用 `/no` 放弃。
+
+确认后的 skill 写入位置和第三方 skill 安装保持一致：
+
+- 项目级：`.codemini/skills/<skill-name>/SKILL.md`
+- 全局级：`<base-config-dir>/skills/<skill-name>/SKILL.md`
+
 ### Dream Loop（内置记忆演化）
 
 Dream loop 是运行时内置能力，不依赖 skill 才能使用。

package/deployment.md

@@ -13,13 +13,13 @@ npm pack
 Expected output:
 
 ```text
-codemini-cli-0.4.1.tgz
+codemini-cli-0.4.2.tgz
 ```
 
 If you want to verify the package contents:
 
 ```bash
-tar -tf codemini-cli-0.4.1.tgz
+tar -tf codemini-cli-0.4.2.tgz
 ```
 
 ## 2. Copy To The Target Machine
@@ -34,7 +34,7 @@ Copy the generated `.tgz` file to the Win10 machine by one of these methods:
 Recommended target path:
 
 ```powershell
-C:\temp\codemini-cli-0.4.1.tgz
+C:\temp\codemini-cli-0.4.2.tgz
 ```
 
 ## 3. Environment Requirements
@@ -58,7 +58,7 @@ npm -v
 Global install:
 
 ```powershell
-npm install -g C:\temp\codemini-cli-0.4.1.tgz
+npm install -g C:\temp\codemini-cli-0.4.2.tgz
 ```
 
 If global install is blocked by company policy, install in a working directory instead:
@@ -66,7 +66,7 @@ If global install is blocked by company policy, install in a working directory i
 ```powershell
 mkdir C:\temp\coder-test
 cd C:\temp\coder-test
-npm install C:\temp\codemini-cli-0.4.1.tgz
+npm install C:\temp\codemini-cli-0.4.2.tgz
 ```
 
 ## 5. Confirm Installation
@@ -158,6 +158,7 @@ Typical contents:
 - `config.json`
 - `sessions\`
 - `skills\`
+- project skills are stored per workspace under `.codemini\skills\`
 - `input-history.json`
 
 ## 9. Skills
@@ -168,13 +169,19 @@ List installed skills:
 codemini skill list
 ```
 
-Install a local skill:
+Install a local skill into the current project:
 
 ```powershell
 codemini skill install C:\path\to\skill-folder
 ```
 
-Rebuild the local registry:
+Install a local skill globally:
+
+```powershell
+codemini skill install --scope=global C:\path\to\skill-folder
+```
+
+Rebuild the global registry:
 
 ```powershell
 codemini skill reindex

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemini-cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Coding CLI optimized for small-model workflows and Windows PowerShell",
   "keywords": [
     "cli",
@@ -51,7 +51,6 @@
     "cli-truncate": "^6.0.0",
     "duck-duck-scrape": "^2.2.7",
     "ink": "^7.0.0",
-    "playwright": "^1.54.2",
     "react": "^19.2.5",
     "strip-ansi": "^7.2.0",
     "web-tree-sitter": "^0.26.8"

package/src/cli.js

@@ -17,7 +17,7 @@ Usage:
   codemini run --pipeline <task> [--model <name>]
   codemini config set|get|list <key> [value]
   codemini doctor
-  codemini skill list|install|enable|disable|inspect|reindex
+  codemini skill list|install|enable|disable|inspect|reindex [--scope=project|global]
   codemini --version
   codemini --help`);
 }

package/src/commands/skill.js

@@ -3,7 +3,9 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { copyRecursive } from '../core/fs-utils.js';
-import { getSkillsDir } from '../core/paths.js';
+import { loadConfig, saveConfig } from '../core/config-store.js';
+import { loadCommandsAndSkills } from '../core/command-loader.js';
+import { getProjectSkillsDir, getSkillsDir } from '../core/paths.js';
 import {
   computeFileSha256,
   readSkillRegistry,
@@ -11,17 +13,85 @@ import {
   writeSkillRegistry
 } from '../core/skill-registry.js';
 
-async function listSkillEntries() {
-  const registry = await readSkillRegistry();
-  const byName = new Map((registry.skills || []).map((s) => [s.name, s]));
-  await fs.mkdir(getSkillsDir(), { recursive: true });
-  const entries = await fs.readdir(getSkillsDir(), { withFileTypes: true });
-  const names = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
-  return names.map((name) => byName.get(name) || { name, version: 'unknown', enabled: true });
+function parseScopeArgs(args = [], { defaultScope = 'project', allowAll = false } = {}) {
+  let scope = defaultScope;
+  const rest = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index] || '');
+    if (arg === '--global') {
+      scope = 'global';
+      continue;
+    }
+    if (arg === '--project') {
+      scope = 'project';
+      continue;
+    }
+    if (arg === '--scope') {
+      const next = String(args[index + 1] || '').toLowerCase();
+      if (['project', 'global', ...(allowAll ? ['all', 'builtin'] : [])].includes(next)) {
+        scope = next;
+        index += 1;
+        continue;
+      }
+    }
+    if (arg.startsWith('--scope=')) {
+      const value = arg.slice('--scope='.length).toLowerCase();
+      if (['project', 'global', ...(allowAll ? ['all', 'builtin'] : [])].includes(value)) {
+        scope = value;
+        continue;
+      }
+    }
+    rest.push(arg);
+  }
+  return { scope, rest };
+}
+
+function baseDirForScope(scope, cwd = process.cwd()) {
+  return scope === 'global' ? getSkillsDir() : getProjectSkillsDir(cwd);
+}
+
+function scopeFromSource(source = '') {
+  if (source === 'bundled-skill') return 'builtin';
+  if (source === 'project-skill') return 'project';
+  if (source === 'global-skill' || source === 'registry-skill') return 'global';
+  return source || 'unknown';
+}
+
+async function setSkillEnabledConfig(name, enabled) {
+  const config = await loadConfig();
+  config.skills = config.skills || {};
+  config.skills.enabled = config.skills.enabled || {};
+  config.skills.enabled[name] = enabled;
+  await saveConfig(config);
 }
 
-async function readSkillMeta(name) {
-  const dir = path.join(getSkillsDir(), name);
+async function listSkillEntries({ scope = 'all', cwd = process.cwd() } = {}) {
+  const commands = await loadCommandsAndSkills(cwd);
+  const config = await loadConfig();
+  const entries = [];
+  for (const command of commands.values()) {
+    if (command.metadata?.type !== 'skill') continue;
+    const itemScope = scopeFromSource(command.source);
+    if (scope !== 'all' && itemScope !== scope) continue;
+    entries.push({
+      name: command.name,
+      version: command.metadata?.version || '0.0.0',
+      description: command.metadata?.description || '',
+      scope: itemScope,
+      path: command.path,
+      enabled: itemScope === 'builtin' ? true : config.skills?.enabled?.[command.name] !== false
+    });
+  }
+  return entries.sort((a, b) => `${a.scope}:${a.name}`.localeCompare(`${b.scope}:${b.name}`));
+}
+
+async function readSkillMeta(name, { scope = 'all', cwd = process.cwd() } = {}) {
+  const entries = await listSkillEntries({ scope, cwd });
+  const found = entries.find((item) => item.name === name);
+  if (!found) {
+    return { exists: false, path: '', preview: '', manifest: null };
+  }
+  const dir = path.dirname(found.path);
   const manifestPath = path.join(dir, 'manifest.json');
   let manifest = null;
   try {
@@ -30,13 +100,13 @@ async function readSkillMeta(name) {
     manifest = null;
   }
   const entryFile = manifest?.entry || 'SKILL.md';
-  const skillPath = path.join(dir, entryFile);
+  const skillPath = found.path || path.join(dir, entryFile);
   try {
     const content = await fs.readFile(skillPath, 'utf8');
     const firstLines = content.split('\n').slice(0, 20).join('\n');
-    return { exists: true, path: skillPath, preview: firstLines, manifest };
+    return { exists: true, path: skillPath, preview: firstLines, manifest, scope: found.scope };
   } catch {
-    return { exists: false, path: skillPath, preview: '', manifest };
+    return { exists: false, path: skillPath, preview: '', manifest, scope: found.scope };
   }
 }
 
@@ -104,11 +174,15 @@ async function resolveSkillSourceDir(sourcePath) {
   throw new Error('skill install supports <skill-dir>, <SKILL.md>, or <skill.tgz>');
 }
 
-async function installSkill(sourcePath) {
+async function installSkill(sourcePath, { scope = 'project', cwd = process.cwd() } = {}) {
   const resolved = await resolveSkillSourceDir(sourcePath);
   const manifest = await readManifestSafe(resolved.dir);
   const folderName = manifest?.name || path.basename(resolved.dir);
-  const targetDir = path.join(getSkillsDir(), folderName);
+  const bundled = (await listSkillEntries({ scope: 'builtin', cwd })).find((item) => item.name === folderName);
+  if (bundled) {
+    throw new Error(`cannot install over builtin skill: ${folderName}`);
+  }
+  const targetDir = path.join(baseDirForScope(scope, cwd), folderName);
   await fs.rm(targetDir, { recursive: true, force: true });
   await copyRecursive(resolved.dir, targetDir);
 
@@ -117,16 +191,19 @@ async function installSkill(sourcePath) {
   await fs.access(entryPath);
 
   const hash = await computeFileSha256(entryPath);
-  await upsertSkillRegistryEntry(undefined, {
-    name: folderName,
-    version: manifest?.version || '0.0.0',
-    description: manifest?.description || '',
-    enabled: true,
-    source: sourcePath,
-    entryFile,
-    sha256: hash,
-    installedAt: new Date().toISOString()
-  });
+  if (scope === 'global') {
+    await upsertSkillRegistryEntry(undefined, {
+      name: folderName,
+      version: manifest?.version || '0.0.0',
+      description: manifest?.description || '',
+      enabled: true,
+      source: sourcePath,
+      entryFile,
+      sha256: hash,
+      installedAt: new Date().toISOString()
+    });
+  }
+  await setSkillEnabledConfig(folderName, true);
 
   if (resolved.cleanupDir) {
     await fs.rm(resolved.cleanupDir, { recursive: true, force: true });
@@ -135,19 +212,28 @@ async function installSkill(sourcePath) {
   return folderName;
 }
 
-async function setEnabled(name, enabled) {
+async function setEnabled(name, enabled, { cwd = process.cwd() } = {}) {
+  const entries = await listSkillEntries({ scope: 'all', cwd });
+  const found = entries.find((item) => item.name === name);
+  if (!found) {
+    throw new Error(`skill not found: ${name}`);
+  }
+  if (found.scope === 'builtin') {
+    throw new Error(`builtin skill cannot be ${enabled ? 'enabled' : 'disabled'}: ${name}`);
+  }
+  await setSkillEnabledConfig(name, enabled);
   const registry = await readSkillRegistry();
   const idx = registry.skills.findIndex((s) => s.name === name);
-  if (idx === -1) {
-    throw new Error(`skill not found: ${name}`);
+  if (idx !== -1) {
+    registry.skills[idx].enabled = enabled;
+    await writeSkillRegistry(undefined, registry);
   }
-  registry.skills[idx].enabled = enabled;
-  await writeSkillRegistry(undefined, registry);
 }
 
-async function reindexSkills() {
-  await fs.mkdir(getSkillsDir(), { recursive: true });
-  const entries = await fs.readdir(getSkillsDir(), { withFileTypes: true });
+async function reindexSkills({ scope = 'global', cwd = process.cwd() } = {}) {
+  const baseDir = baseDirForScope(scope, cwd);
+  await fs.mkdir(baseDir, { recursive: true });
+  const entries = await fs.readdir(baseDir, { withFileTypes: true });
   const registry = await readSkillRegistry();
   const byName = new Map((registry.skills || []).map((s) => [s.name, s]));
   const rebuilt = [];
@@ -155,7 +241,7 @@ async function reindexSkills() {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const name = entry.name;
-    const dir = path.join(getSkillsDir(), name);
+    const dir = path.join(baseDir, name);
     const manifest = await readManifestSafe(dir);
     const entryFile = manifest?.entry || 'SKILL.md';
     const entryPath = path.join(dir, entryFile);
@@ -178,22 +264,24 @@ async function reindexSkills() {
     });
   }
 
-  await writeSkillRegistry(undefined, {
-    version: 1,
-    skills: rebuilt
-  });
+  if (scope === 'global') {
+    await writeSkillRegistry(undefined, {
+      version: 1,
+      skills: rebuilt
+    });
+  }
 
   return rebuilt.length;
 }
 
 function usage() {
   console.log(`Usage:
-  codemini skill list
-  codemini skill install <path>
+  codemini skill list [--scope=all|project|global|builtin]
+  codemini skill install [--scope=project|global] <path>
   codemini skill enable <name>
   codemini skill disable <name>
-  codemini skill inspect <name>
-  codemini skill reindex`);
+  codemini skill inspect [--scope=all|project|global|builtin] <name>
+  codemini skill reindex [--scope=project|global]`);
 }
 
 export async function handleSkill(args) {
@@ -204,26 +292,27 @@ export async function handleSkill(args) {
   }
 
   if (sub === 'list') {
-    const entries = await listSkillEntries();
+    const { scope } = parseScopeArgs(rest, { defaultScope: 'all', allowAll: true });
+    const entries = await listSkillEntries({ scope });
     if (entries.length === 0) {
       console.log('No installed skills');
       return;
     }
     for (const item of entries) {
-      const state = item.enabled !== false ? 'enabled' : 'disabled';
-      console.log(`${item.name}@${item.version || '0.0.0'} (${state})`);
+      const state = item.scope === 'builtin' ? 'builtin/default' : (item.enabled !== false ? 'enabled' : 'disabled');
+      console.log(`${item.name}@${item.version || '0.0.0'} [${item.scope}] (${state})`);
     }
     return;
   }
 
   if (sub === 'install') {
-    const sourcePath = rest[0];
+    const { scope, rest: positional } = parseScopeArgs(rest, { defaultScope: 'project' });
+    const sourcePath = positional[0];
     if (!sourcePath) {
       throw new Error('skill install requires <path>');
     }
-    const installedName = await installSkill(sourcePath);
-    await setEnabled(installedName, true);
-    console.log(`Installed skill: ${installedName}`);
+    const installedName = await installSkill(sourcePath, { scope });
+    console.log(`Installed skill: ${installedName} (${scope})`);
     return;
   }
 
@@ -238,25 +327,28 @@ export async function handleSkill(args) {
   }
 
   if (sub === 'inspect') {
-    const name = rest[0];
+    const { scope, rest: positional } = parseScopeArgs(rest, { defaultScope: 'all', allowAll: true });
+    const name = positional[0];
     if (!name) {
       throw new Error('skill inspect requires <name>');
     }
-    const meta = await readSkillMeta(name);
+    const meta = await readSkillMeta(name, { scope });
     if (!meta.exists) {
       throw new Error(`skill not found: ${name}`);
     }
     if (meta.manifest) {
       console.log(`Manifest: ${JSON.stringify(meta.manifest, null, 2)}\n`);
     }
+    console.log(`Scope: ${meta.scope}\n`);
     console.log(`Path: ${meta.path}\n`);
     console.log(meta.preview);
     return;
   }
 
   if (sub === 'reindex') {
-    const count = await reindexSkills();
-    console.log(`Reindexed skills: ${count}`);
+    const { scope } = parseScopeArgs(rest, { defaultScope: 'global' });
+    const count = await reindexSkills({ scope });
+    console.log(`Reindexed skills: ${count} (${scope})`);
     return;
   }