funcoding-cli 0.0.0-stage → 0.2.1

package/dist/config-files.js

@@ -0,0 +1,84 @@
+/**
+ * 改写智能体的 MCP 配置文件：只动我们这一项，文件里的其他内容原样保留。
+ * - JSON（Cursor 的 mcp.json、Claude Code 的 .mcp.json）：{ "mcpServers": { "<name>": {...} } }
+ * - TOML（Codex 的 config.toml）：[mcp_servers.<name>] 一段（含 [mcp_servers.<name>.env] 等子表）。
+ *   不引入 TOML 解析库，只按表头定位这一段做替换或删除
+ */
+export function parseMcpJson(text) {
+    if (!text?.trim())
+        return {};
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        throw new Error('配置文件的顶层不是 JSON 对象');
+    return data;
+}
+export const jsonServerNames = (text) => Object.keys(parseMcpJson(text).mcpServers ?? {});
+/** 返回新的文件内容；entry 为 null 时删除这一项 */
+export function setJsonServer(text, name, entry) {
+    const data = parseMcpJson(text);
+    const servers = { ...(data.mcpServers ?? {}) };
+    if (entry)
+        servers[name] = entry;
+    else
+        delete servers[name];
+    return `${JSON.stringify({ ...data, mcpServers: servers }, null, 2)}\n`;
+}
+// ---------------- TOML ----------------
+const tomlKey = (k) => (/^[A-Za-z0-9_-]+$/.test(k) ? k : JSON.stringify(k));
+/** TOML 的基本字符串和 JSON 字符串的转义规则兼容 */
+const tomlString = (s) => JSON.stringify(s);
+const inlineTable = (o) => `{ ${Object.entries(o).map(([k, v]) => `${tomlKey(k)} = ${tomlString(v)}`).join(', ')} }`;
+/** 表头 [mcp_servers.<name>] 或 [mcp_servers.<name>.子表]，名称可以是裸键或带引号 */
+function headerMatches(line, name) {
+    const m = /^\s*\[\s*mcp_servers\s*\.\s*("(?:[^"\\]|\\.)*"|'[^']*'|[A-Za-z0-9_-]+)\s*(?:\.[^\]]*)?\]\s*(?:#.*)?$/.exec(line);
+    if (!m)
+        return false;
+    const raw = m[1];
+    const key = raw.startsWith('"') ? JSON.parse(raw) : raw.startsWith("'") ? raw.slice(1, -1) : raw;
+    return key === name;
+}
+const isHeader = (line) => /^\s*\[/.test(line);
+/** 列出 config.toml 里已配置的 MCP Server 名称 */
+export function tomlServerNames(text) {
+    const names = new Set();
+    for (const line of (text ?? '').split('\n')) {
+        const m = /^\s*\[\s*mcp_servers\s*\.\s*("(?:[^"\\]|\\.)*"|'[^']*'|[A-Za-z0-9_-]+)/.exec(line);
+        if (m)
+            names.add(m[1].startsWith('"') ? JSON.parse(m[1]) : m[1].replace(/^'|'$/g, ''));
+    }
+    return [...names];
+}
+/** 删除 [mcp_servers.<name>] 及其子表 */
+export function removeTomlServer(text, name) {
+    const out = [];
+    let skipping = false;
+    for (const line of (text ?? '').split('\n')) {
+        if (isHeader(line))
+            skipping = headerMatches(line, name);
+        if (!skipping)
+            out.push(line);
+    }
+    return out.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+export function renderTomlServer(name, c) {
+    const key = `mcp_servers.${tomlKey(name)}`;
+    const lines = [`[${key}]`];
+    if (c.kind === 'stdio') {
+        lines.push(`command = ${tomlString(c.command)}`, `args = [${c.args.map(tomlString).join(', ')}]`);
+        if (Object.keys(c.env).length > 0)
+            lines.push('', `[${key}.env]`, ...Object.entries(c.env).map(([k, v]) => `${tomlKey(k)} = ${tomlString(v)}`));
+    }
+    else {
+        lines.push(`url = ${tomlString(c.url)}`);
+        if (Object.keys(c.headers).length > 0)
+            lines.push(`http_headers = ${inlineTable(c.headers)}`);
+    }
+    return lines.join('\n');
+}
+/** 写入（已有同名的先删掉）；c 为 null 时只删除 */
+export function setTomlServer(text, name, c) {
+    const rest = removeTomlServer(text, name).replace(/\s+$/, '');
+    if (!c)
+        return rest ? `${rest}\n` : '';
+    return `${rest ? `${rest}\n\n` : ''}${renderTomlServer(name, c)}\n`;
+}

package/dist/content.js

@@ -0,0 +1,100 @@
+/** skills find / mcp find / news / docs：只读查询网站内容 */
+import { api, siteUrl } from './api.js';
+import { bold, CliError, cyan, dim, done, fail, info, stars, truncate } from './ui.js';
+function printCards(title, cards, hrefOf) {
+    if (cards.length === 0)
+        return;
+    info(bold(title));
+    for (const c of cards) {
+        info(`  ${cyan(c.id)} ${dim(`★ ${stars(c.stars)}${c.official ? ' · 官方' : ''}`)}`);
+        if (c.description)
+            info(`    ${truncate(c.description, (process.stdout.columns || 100) - 6)}`);
+        info(dim(`    ${hrefOf(c)}`));
+    }
+    info('');
+}
+/** skills find / mcp find */
+export async function find(kind, query, limit) {
+    const cmd = kind === 'skill' ? 'skills' : 'mcp';
+    if (!query)
+        fail('usage', '缺少关键词。', `例如 funcoding ${cmd} find pdf`);
+    const r = await api(`/api/cli/search?q=${encodeURIComponent(query)}&limit=${limit}`);
+    const items = kind === 'skill' ? r.skills : r.mcp;
+    done({ [kind === 'skill' ? 'skills' : 'servers']: items }, () => {
+        if (items.length === 0)
+            return info(`没有找到「${query}」相关的${kind === 'skill' ? ' Skill' : ' MCP Server'}。`);
+        printCards(kind === 'skill' ? 'Skills' : 'MCP Server', items, (c) => `funcoding ${cmd} add ${c.id}`);
+    });
+}
+function printStory(s, n) {
+    info(`${n ? `${String(n).padStart(2)}. ` : '  · '}${bold(s.title)}${dim(`  ${s.sourceCount} 家报道`)}`);
+    if (s.summary)
+        info(`    ${truncate(s.summary, (process.stdout.columns || 100) - 6)}`);
+    info(dim(`    ${s.url}`));
+}
+export async function newsDaily(date) {
+    const day = date || 'latest';
+    if (day !== 'latest' && !/^\d{4}-\d{2}-\d{2}$/.test(day))
+        fail('usage', `日期要写成 YYYY-MM-DD：${day}`);
+    const issue = await api(`/api/cli/news?daily=${day}`);
+    done({ daily: issue }, () => {
+        info(bold(`AI 日报 · 第 ${issue.no} 期 · ${issue.day}`));
+        info(dim(issue.url));
+        info('');
+        info(bold('头条'));
+        printStory(issue.headline);
+        for (const sec of issue.sections) {
+            info('');
+            info(bold(sec.label));
+            for (const s of sec.stories)
+                printStory(s);
+        }
+        if (issue.flash.length > 0) {
+            info('');
+            info(bold('快讯'));
+            for (const s of issue.flash)
+                info(`  · ${s.title} ${dim(s.url)}`);
+        }
+    });
+}
+export async function newsList(limit) {
+    const r = await api(`/api/cli/news?limit=${limit}`);
+    done({ updatedAt: r.updatedAt, stories: r.stories }, () => {
+        if (r.stories.length === 0)
+            return info('暂无热点。');
+        info(bold('AI 热榜') + dim(`  ${siteUrl('/news/')}`));
+        r.stories.forEach((s, i) => printStory(s, i + 1));
+    });
+}
+export async function docsSearch(query, agent, limit) {
+    if (!query)
+        fail('usage', '缺少搜索词。', '例如 funcoding docs search hooks --agent=claude-code');
+    const params = new URLSearchParams({ q: query, limit: String(limit), ...(agent ? { agent } : {}) });
+    const r = await api(`/api/cli/docs/search?${params}`);
+    done({ docs: r.docs }, () => {
+        if (r.docs.length === 0)
+            return info(`没有找到「${query}」相关的文档。`);
+        for (const d of r.docs) {
+            info(`${cyan(d.id)} ${bold(d.title)} ${dim(d.agent)}`);
+            if (d.description)
+                info(`  ${truncate(d.description, (process.stdout.columns || 100) - 4)}`);
+        }
+        info('');
+        info(dim(`运行 ${cyan('funcoding docs fetch <id>')} 阅读全文。`));
+    });
+}
+export async function docsFetch(id) {
+    const path = id
+        .trim()
+        .replace(/^https?:\/\/[^/]+/, '')
+        .replace(/^\/?agents\//, '')
+        .replace(/^\/+|\/+$/g, '');
+    if (!/^[a-z0-9][\w-]*(\/[\w.-]+)*$/i.test(path))
+        fail('usage', '文档要写成 <智能体>/<路径>，例如 claude-code/hooks。', '运行 funcoding docs search <关键词> 查找');
+    const markdown = await api(`/api/cli/docs/${path}`, { headers: { Accept: 'text/markdown' } }).catch((err) => {
+        if (err instanceof CliError && err.code === 'not_found')
+            fail('not_found', `没有找到文档：${path}`, '运行 funcoding docs search <关键词> 查找');
+        throw err;
+    });
+    done({ id: path, url: siteUrl(`/agents/${path}/`), markdown }, () => info(markdown));
+}

package/dist/credentials.js

@@ -0,0 +1,30 @@
+/** 登录凭证存在 ~/.config/funcoding/credentials.json（Windows 是 %APPDATA%\funcoding），只有自己可读 */
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** CLI 自己的配置目录：凭证、覆盖安装时的备份 */
+export function configDir() {
+    if (process.env.FUNCODING_CONFIG_DIR)
+        return process.env.FUNCODING_CONFIG_DIR;
+    if (process.platform === 'win32' && process.env.APPDATA)
+        return join(process.env.APPDATA, 'funcoding');
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'funcoding');
+}
+export const credentialsPath = () => join(configDir(), 'credentials.json');
+export async function loadCredentials(site) {
+    try {
+        const c = JSON.parse(await readFile(credentialsPath(), 'utf8'));
+        // 换了站点地址（比如本地开发）就不用之前的 token
+        return c.token && c.site === site ? c : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCredentials(c) {
+    const file = credentialsPath();
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    await writeFile(file, `${JSON.stringify(c, null, 2)}\n`, { mode: 0o600 });
+    await chmod(file, 0o600).catch(() => { });
+}
+export const clearCredentials = () => rm(credentialsPath(), { force: true });

package/dist/info.js

@@ -0,0 +1,40 @@
+/** info：环境信息，只读本机状态，不访问网络 */
+import { AGENT_IDS, AGENTS, currentAgent, installedAgents, skillsRoot } from './agents.js';
+import { SITE, VERSION } from './api.js';
+import { configDir, credentialsPath, loadCredentials } from './credentials.js';
+import { onPath } from './init.js';
+import { bold, dim, done, fail, info } from './ui.js';
+export async function envInfo(field) {
+    const creds = await loadCredentials(SITE);
+    const found = installedAgents();
+    const data = {
+        version: VERSION,
+        site: SITE,
+        node: process.versions.node,
+        /** 是否已全局安装（终端里能直接用 funcoding / fun） */
+        global: onPath('funcoding'),
+        user: creds?.user ?? null,
+        currentAgent: currentAgent(),
+        agents: AGENT_IDS.map((id) => ({ id, installed: found.includes(id), skills: { user: skillsRoot(id, 'user'), project: skillsRoot(id, 'project') } })),
+        configDir: configDir(),
+        credentials: credentialsPath(),
+    };
+    if (field) {
+        if (!(field in data))
+            fail('usage', `没有这一项：${field}`, `可选：${Object.keys(data).join('、')}`);
+        const value = data[field];
+        return done({ [field]: value }, () => info(typeof value === 'object' && value !== null ? JSON.stringify(value, null, 2) : String(value)));
+    }
+    done(data, () => {
+        const row = (k, v) => info(`${bold(k.padEnd(14))}${v}`);
+        row('version', VERSION);
+        row('site', SITE);
+        row('node', process.versions.node);
+        row('global', data.global ? '已全局安装（funcoding / fun）' : '未全局安装，运行 npx --yes funcoding-cli@latest init');
+        row('user', creds?.user ? `${creds.user.name}${creds.user.githubLogin ? ` (@${creds.user.githubLogin})` : ''}` : '未登录');
+        row('currentAgent', data.currentAgent ? AGENTS[data.currentAgent].label : '无');
+        for (const id of AGENT_IDS)
+            row(id, `${found.includes(id) ? '已安装' : dim('未检测到')}  ${dim(skillsRoot(id, 'user'))}`);
+        row('configDir', configDir());
+    });
+}

package/dist/init.js

@@ -0,0 +1,90 @@
+/**
+ * init：
+ * 1. 没有全局安装时用 npm 全局安装本 CLI，之后终端里可以直接用 funcoding 或简写 fun（--no-global 跳过）
+ * 2. 把随 CLI 发布的 funcoding Skill（skill/funcoding/SKILL.md）装到智能体，让它知道什么时候、怎么用这个 CLI。
+ *    这个 Skill 不在网站目录里，来源记录标成 builtin，update 时从当前版本的 CLI 重新复制
+ */
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { delimiter, dirname, join } from 'node:path';
+import { AGENTS, skillsRoot } from './agents.js';
+import { USER_AGENT, VERSION } from './api.js';
+import { META_FILE, moveAway } from './install.js';
+import { cyan, dim, done, fail, green, info, warn } from './ui.js';
+const isWindows = process.platform === 'win32';
+/** PATH 上能不能找到这个命令；npx 运行时会把临时目录加进 PATH，那些目录不算 */
+export function onPath(command, env = process.env) {
+    const exts = isWindows ? ['.cmd', '.exe', ''] : [''];
+    return (env.PATH ?? '')
+        .split(delimiter)
+        .filter((dir) => dir && !/[\\/]_npx[\\/]/.test(dir))
+        .some((dir) => exts.some((ext) => existsSync(join(dir, command + ext))));
+}
+const EACCES_DOC = '权限不足时参考 https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally';
+/** 全局安装当前版本；npm 的输出写到 stderr，不影响 --json 的 stdout */
+function installGlobal() {
+    if (onPath('funcoding'))
+        return { status: 'present' };
+    const pkg = `funcoding-cli@${VERSION}`;
+    info(dim(`正在全局安装 ${pkg}，之后可以直接使用 funcoding 或 fun 命令…`));
+    const r = spawnSync('npm', ['install', '--global', pkg], { stdio: ['ignore', process.stderr, process.stderr], shell: isWindows });
+    if (r.status === 0)
+        return { status: 'installed' };
+    return { status: 'failed', hint: `手动运行 npm install -g ${pkg}（${EACCES_DOC}）` };
+}
+/** update：全局安装最新版，再用新版刷新已安装的 funcoding Skill */
+export function selfUpdate() {
+    info(dim('正在用 npm 全局安装 funcoding-cli@latest…'));
+    const r = spawnSync('npm', ['install', '--global', 'funcoding-cli@latest'], { stdio: ['ignore', process.stderr, process.stderr], shell: isWindows });
+    if (r.status !== 0)
+        fail('error', '更新失败。', `手动运行 npm install -g funcoding-cli@latest（${EACCES_DOC}）`);
+    const version = spawnSync('funcoding', ['--version'], { encoding: 'utf8', shell: isWindows }).stdout?.trim() || null;
+    // 让新版本把随包的 funcoding Skill 复制过去；没装过这个 Skill 时会报未找到，忽略
+    spawnSync('funcoding', ['skills', 'update', BUILTIN_ID, '--json'], { stdio: 'ignore', shell: isWindows });
+    done({ from: VERSION, to: version }, () => info(green(version && version !== VERSION ? `✓ 已从 ${VERSION} 更新到 ${version}` : `✓ 已是最新版本 ${version ?? VERSION}`)));
+}
+export const BUILTIN_ID = 'funcoding';
+const SOURCE = new URL('../skill/funcoding/SKILL.md', import.meta.url);
+export const builtinContent = () => readFile(SOURCE, 'utf8');
+export async function installBuiltin(targets, force) {
+    const content = await builtinContent();
+    const dirs = targets.map((t) => ({ ...t, dir: join(skillsRoot(t.agent, t.scope), BUILTIN_ID) }));
+    const foreign = [];
+    for (const d of dirs) {
+        const meta = await readFile(join(d.dir, META_FILE), 'utf8').catch(() => null);
+        const present = meta !== null || (await stat(d.dir).then(() => true, () => false));
+        // 之前 init 装的直接换成新版；同名的其他 Skill 要 --force，并且先备份
+        if (present && !(meta && JSON.parse(meta).builtin))
+            foreign.push(d);
+    }
+    if (foreign.length > 0 && !force)
+        fail('exists', `${foreign.map((d) => d.dir).join('、')} 已存在，且不是 funcoding init 安装的。`, '确认要覆盖就加 --force（会先备份到配置目录）');
+    for (const d of dirs) {
+        const tmp = join(dirname(d.dir), `.funcoding-tmp-${randomBytes(4).toString('hex')}`);
+        await mkdir(tmp, { recursive: true });
+        await writeFile(join(tmp, 'SKILL.md'), content);
+        await writeFile(join(tmp, META_FILE), `${JSON.stringify({ id: BUILTIN_ID, name: BUILTIN_ID, builtin: true, installedAt: new Date().toISOString(), cli: USER_AGENT }, null, 2)}\n`);
+        if (foreign.includes(d))
+            await moveAway(d.dir, d.agent, BUILTIN_ID);
+        else
+            await rm(d.dir, { recursive: true, force: true });
+        await rename(tmp, d.dir);
+    }
+    return dirs;
+}
+export async function init(targets, force, global) {
+    const cli = global ? installGlobal() : { status: 'skipped' };
+    const dirs = await installBuiltin(targets, force);
+    done({ cli, installed: dirs.map((d) => ({ id: BUILTIN_ID, agent: d.agent, scope: d.scope, dir: d.dir })) }, () => {
+        if (cli.status === 'installed')
+            info(green(`✓ 已全局安装 funcoding-cli，在终端里输入 ${cyan('funcoding')} 或 ${cyan('fun')} 即可使用`));
+        if (cli.status === 'failed')
+            warn(`全局安装失败，${cli.hint}`);
+        for (const d of dirs)
+            info(green(`✓ 已把 funcoding Skill 装到 ${d.dir}`));
+        info(`之后可以直接让 ${dirs.map((d) => AGENTS[d.agent].label).join('、')} 帮你查找和安装 Skill、配置 MCP，例如「找一个处理 PDF 的 Skill 装上」。`);
+        info(dim(`也可以输入 ${[...new Set(dirs.map((d) => cyan(AGENTS[d.agent].invoke(BUILTIN_ID))))].join(' / ')} 主动调用。新开会话后生效。`));
+    });
+}

package/dist/install.js

@@ -0,0 +1,278 @@
+/**
+ * Skill 管理：info / install / list / update / remove。
+ * 安装时先下载到目标目录旁边的临时目录，全部成功后再整体移动过去，失败不会留下装了一半的目录；
+ * 覆盖和删除前把旧目录备份到 CLI 的配置目录（留在 skills 目录里会被智能体当成同名 Skill 加载）。
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { cp, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { AGENT_IDS, AGENTS, skillsRoot } from './agents.js';
+import { api, SITE, siteUrl, USER_AGENT } from './api.js';
+import { configDir } from './credentials.js';
+import { isSafeFolderName, resolveInside } from './paths.js';
+import { builtinContent, installBuiltin } from './init.js';
+import { bold, CliError, cyan, dim, done, fail, green, info, stars, warn } from './ui.js';
+/** 和服务端一致的上限 */
+const MAX_FILES = 200;
+const MAX_BYTES = 10 * 1024 * 1024;
+export const META_FILE = '.funcoding.json';
+/** 接受 owner/repo/skill，或者网站上的详情页地址 */
+export function parseSkillSpec(input) {
+    const s = input.trim();
+    const fromUrl = /\/skills\/([^/?#]+\/[^/?#]+\/[^/?#]+)\/?(?:install\.md)?(?:[?#].*)?$/.exec(s)?.[1];
+    const id = (fromUrl ?? s).replace(/^\/+|\/+$/g, '').toLowerCase();
+    // 每一段都以字母或数字开头：排除 . 和 .. 这类路径
+    return /^[a-z0-9][\w.-]*\/[a-z0-9][\w.-]*\/[a-z0-9][\w.-]*$/.test(id) ? id : null;
+}
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+const exists = (p) => stat(p).then(() => true, () => false);
+async function download(url, maxBytes) {
+    const res = await fetch(url, { headers: { 'User-Agent': USER_AGENT }, signal: AbortSignal.timeout(60_000) });
+    if (!res.ok) {
+        await res.body?.cancel();
+        throw new CliError('error', `下载失败（HTTP ${res.status}）：${url}`);
+    }
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength > maxBytes)
+        throw new CliError('error', `文件太大：${url}`);
+    return buf;
+}
+async function mapLimit(items, limit, fn) {
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length)
+            await fn(items[next++]);
+    }));
+}
+/** 把目录挪到备份位置；跨磁盘（比如 --project 装在另一块盘上）不能 rename，就先复制再删 */
+export async function moveAway(dir, agent, folder) {
+    const backup = join(configDir(), 'backups', agent, `${folder}-${new Date().toISOString().replace(/[:.]/g, '-')}`);
+    await mkdir(dirname(backup), { recursive: true });
+    await rename(dir, backup).catch(async (err) => {
+        if (err.code !== 'EXDEV')
+            throw err;
+        await cp(dir, backup, { recursive: true });
+        await rm(dir, { recursive: true, force: true });
+    });
+    return backup;
+}
+/** 取 Skill 的安装信息（含 SKILL.md 全文和文件清单） */
+export async function fetchSkill(spec) {
+    const id = parseSkillSpec(spec);
+    if (!id)
+        return fail('usage', `Skill 要写成 owner/repo/skill，或者 ${SITE}/skills/ 下的详情页地址：${spec}`);
+    try {
+        return await api(`/api/cli/skills/${id}`);
+    }
+    catch (err) {
+        if (err instanceof CliError && err.code === 'not_found')
+            fail('not_found', `没有找到 Skill：${id}`, '运行 funcoding skills find <关键词> 查找');
+        throw err;
+    }
+}
+// ---------------- info ----------------
+export async function skillInfo(spec) {
+    const s = await fetchSkill(spec);
+    const page = siteUrl(`/skills/${s.id}/`);
+    const scripts = s.files.filter((f) => /\.(sh|bash|zsh|py|js|mjs|cjs|ts|rb|pl|ps1|bat|cmd)$/i.test(f.path)).map((f) => f.path);
+    done({ skill: { id: s.id, name: s.name, description: s.description, folder: s.folder, repo: s.repo.url, path: s.path, stars: s.stars, official: s.official, page, files: s.files, truncated: s.truncated, scripts, content: s.content } }, () => {
+        info(`${bold(s.name)} ${dim(`${s.id} · ★ ${stars(s.stars)}${s.official ? ' · 官方' : ''}`)}`);
+        if (s.description)
+            info(s.description);
+        info(dim(`${s.repo.url}${s.path ? `/tree/${s.repo.branch}/${s.path}` : ''}`));
+        info(dim(page));
+        info('');
+        info(bold(`文件（${s.files.length}${s.truncated ? '，未列全' : ''}）`));
+        for (const f of s.files)
+            info(`  ${f.path}${scripts.includes(f.path) ? dim('  可执行脚本') : ''}`);
+        info('');
+        info(bold('SKILL.md'));
+        info(s.content);
+    });
+}
+/** 下载 Skill 的全部文件到 dir（dir 不能已存在） */
+async function downloadTo(skill, dir) {
+    let total = 0;
+    await mapLimit(skill.files, 4, async (f) => {
+        const target = resolveInside(dir, f.path);
+        if (!target)
+            throw new CliError('error', `拒绝写入可疑路径：${f.path}`);
+        const url = skill.rawBase + f.path.split('/').map(encodeURIComponent).join('/');
+        const data = await download(url, MAX_BYTES);
+        total += data.byteLength;
+        if (total > MAX_BYTES)
+            throw new CliError('error', 'Skill 总大小超过 10 MB，请手动安装。', `仓库地址：${skill.repo.url}`);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, data);
+    });
+    const md = await readFile(join(dir, 'SKILL.md'));
+    const meta = { id: skill.id, name: skill.name, repo: skill.repo.url, path: skill.path, branch: skill.repo.branch, installedAt: new Date().toISOString(), cli: USER_AGENT, skillHash: sha256(md) };
+    await writeFile(join(dir, META_FILE), `${JSON.stringify(meta, null, 2)}\n`);
+}
+/** 装到多个目标：只下载一次，其余目标复制 */
+export async function installSkill(skill, targets, force) {
+    if (!isSafeFolderName(skill.folder))
+        fail('error', `服务端返回的目录名不合法：${skill.folder}`);
+    if (skill.files.length === 0 || !skill.files.some((f) => f.path === 'SKILL.md'))
+        fail('not_found', `${skill.id} 没有 SKILL.md，可能已被仓库删除。`);
+    if (skill.files.length > MAX_FILES)
+        fail('error', `文件太多（${skill.files.length} 个），请手动安装。`, `仓库地址：${skill.repo.url}`);
+    if (skill.truncated)
+        warn(`${skill.id} 的文件太多，只会安装前一部分，缺少的请从仓库补齐。`);
+    const plan = targets.map((t) => ({ ...t, root: skillsRoot(t.agent, t.scope), dest: join(skillsRoot(t.agent, t.scope), skill.folder) }));
+    if (!force) {
+        const taken = [];
+        for (const p of plan)
+            if (await exists(p.dest))
+                taken.push(p.dest);
+        if (taken.length > 0)
+            fail('exists', `已经存在：${taken.join('、')}`, '确认要覆盖就加 --force（旧版本会备份到配置目录）', { paths: taken });
+    }
+    info(`${bold(skill.name)} ${dim(`${skill.repo.owner}/${skill.repo.name}${skill.path ? `/${skill.path}` : ''} · ${skill.files.length} 个文件`)}`);
+    const results = [];
+    let source = null;
+    for (const p of plan) {
+        await mkdir(p.root, { recursive: true });
+        const tmp = join(p.root, `.funcoding-tmp-${randomBytes(4).toString('hex')}`);
+        try {
+            if (source)
+                await cp(source, tmp, { recursive: true });
+            else
+                await downloadTo(skill, tmp);
+            const backup = (await exists(p.dest)) ? await moveAway(p.dest, p.agent, skill.folder) : undefined;
+            await rename(tmp, p.dest);
+            source = p.dest;
+            results.push({ id: skill.id, name: skill.name, agent: p.agent, scope: p.scope, dir: p.dest, files: skill.files.length, ...(backup ? { backup } : {}) });
+        }
+        catch (err) {
+            await rm(tmp, { recursive: true, force: true });
+            throw err;
+        }
+    }
+    return results;
+}
+function printInstalled(r) {
+    const a = AGENTS[r.agent];
+    info(green(`✓ 已安装到 ${r.dir}`));
+    if (r.backup)
+        info(dim(`  旧版本备份在 ${r.backup}`));
+    info(`  在 ${a.label} 里输入 ${cyan(a.invoke(r.dir.split(/[\\/]/).pop()))} 调用，或直接描述任务让它自动选用。`);
+}
+export async function install(specs, targets, force) {
+    if (specs.length === 0)
+        fail('usage', '缺少要安装的 Skill。', '例如 funcoding skills add anthropics/skills/pdf');
+    const installed = [];
+    for (const spec of specs)
+        installed.push(...(await installSkill(await fetchSkill(spec), targets, force)));
+    done({ installed }, () => {
+        for (const r of installed)
+            printInstalled(r);
+        info(dim('Skill 会按 SKILL.md 的指示行事，可能运行其中的脚本，使用前请先阅读 SKILL.md。'));
+    });
+}
+const frontmatter = (text, key) => new RegExp(`^${key}:\\s*["']?(.+?)["']?\\s*$`, 'm').exec(/^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? '')?.[1];
+async function scan(agent, scope) {
+    const root = skillsRoot(agent, scope);
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const out = [];
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith('.'))
+            continue;
+        const dir = join(root, e.name);
+        const md = await readFile(join(dir, 'SKILL.md'), 'utf8').catch(() => null);
+        if (md === null)
+            continue;
+        const source = await readFile(join(dir, META_FILE), 'utf8')
+            .then((t) => JSON.parse(t))
+            .catch(() => null);
+        out.push({ agent, scope, folder: e.name, dir, name: frontmatter(md, 'name') ?? e.name, description: frontmatter(md, 'description') ?? '', source });
+    }
+    return out.sort((a, b) => a.folder.localeCompare(b.folder));
+}
+export async function scanAll(sel) {
+    const out = [];
+    for (const agent of sel.agents)
+        for (const scope of sel.scopes)
+            out.push(...(await scan(agent, scope)));
+    return out;
+}
+export async function list(sel) {
+    const items = await scanAll(sel);
+    done({ skills: items }, () => {
+        if (items.length === 0)
+            return info(`还没有安装 Skill。可以运行 ${cyan('funcoding skills find <关键词>')} 查找。`);
+        for (const agent of AGENT_IDS) {
+            for (const scope of sel.scopes) {
+                const group = items.filter((s) => s.agent === agent && s.scope === scope);
+                if (group.length === 0)
+                    continue;
+                info(`${bold(AGENTS[agent].label)} ${dim(`${scope === 'user' ? '个人' : '项目'} · ${skillsRoot(agent, scope)}`)}`);
+                for (const s of group)
+                    info(`  ${s.folder}${s.source ? dim(`  ← ${s.source.id}`) : ''}`);
+                info('');
+            }
+        }
+    });
+}
+// ---------------- update ----------------
+const matches = (s, name) => !name || s.folder === name || s.source?.id === name.toLowerCase();
+/** 按 .funcoding.json 记录的来源重新安装；check 时只比较远端 SKILL.md 有没有变化 */
+export async function update(name, sel, check) {
+    const items = (await scanAll(sel)).filter((s) => s.source && matches(s, name));
+    if (items.length === 0)
+        fail('not_found', name ? `没有找到由 funcoding 安装的 ${name}` : '没有由 funcoding 安装的 Skill', '运行 funcoding skills list 查看已安装的 Skill');
+    const results = [];
+    const cache = new Map();
+    for (const s of items) {
+        const id = s.source.id;
+        if (s.source.builtin) {
+            const local = await readFile(join(s.dir, 'SKILL.md'), 'utf8').catch(() => null);
+            if (check)
+                results.push({ id, agent: s.agent, scope: s.scope, dir: s.dir, status: local === (await builtinContent()) ? 'up_to_date' : 'outdated' });
+            else {
+                await installBuiltin([{ agent: s.agent, scope: s.scope }], true);
+                results.push({ id, agent: s.agent, scope: s.scope, dir: s.dir, status: 'updated' });
+            }
+            continue;
+        }
+        const skill = cache.get(id) ?? (await fetchSkill(id));
+        cache.set(id, skill);
+        if (check) {
+            const local = await readFile(join(s.dir, 'SKILL.md')).catch(() => null);
+            const remote = await download(`${skill.rawBase}SKILL.md`, MAX_BYTES).catch(() => null);
+            const status = !local || !remote ? 'unknown' : sha256(local) === sha256(remote) ? 'up_to_date' : 'outdated';
+            results.push({ id, agent: s.agent, scope: s.scope, dir: s.dir, status });
+            continue;
+        }
+        await installSkill(skill, [{ agent: s.agent, scope: s.scope }], true);
+        results.push({ id, agent: s.agent, scope: s.scope, dir: s.dir, status: 'updated' });
+    }
+    done({ skills: results }, () => {
+        const label = { updated: green('已更新'), up_to_date: dim('已是最新'), outdated: cyan('有更新'), unknown: dim('无法比较') };
+        for (const r of results)
+            info(`${label[r.status]}  ${r.id} ${dim(r.dir)}`);
+        if (check && results.some((r) => r.status === 'outdated'))
+            info(dim(`运行 ${cyan('funcoding skills update')} 更新。`));
+    });
+}
+// ---------------- remove ----------------
+export async function remove(names, sel, force) {
+    if (names.length === 0)
+        fail('usage', '缺少要删除的 Skill。', '运行 funcoding skills list 查看已安装的 Skill');
+    const all = await scanAll(sel);
+    const removed = [];
+    for (const name of names) {
+        const found = all.filter((s) => s.folder === name || s.source?.id === name.toLowerCase());
+        if (found.length === 0)
+            fail('not_found', `没有找到已安装的 ${name}`, '运行 funcoding skills list 查看已安装的 Skill');
+        const manual = found.filter((s) => !s.source);
+        if (manual.length > 0 && !force)
+            fail('usage', `${manual.map((s) => s.dir).join('、')} 不是由 funcoding 安装的。`, '确认要删除就加 --force（会先备份到配置目录）', { paths: manual.map((s) => s.dir) });
+        for (const s of found)
+            removed.push({ id: s.source?.id ?? null, agent: s.agent, scope: s.scope, dir: s.dir, backup: await moveAway(s.dir, s.agent, s.folder) });
+    }
+    done({ removed }, () => {
+        for (const r of removed)
+            info(`${green('✓ 已删除')} ${r.dir} ${dim(`（备份在 ${r.backup}）`)}`);
+    });
+}