funcoding-cli 0.0.0-stage → 0.2.1

package/dist/mcp.js

@@ -0,0 +1,265 @@
+/**
+ * MCP Server：info / add / list / remove。配置位置和格式见 agents.ts 顶部的说明。
+ * Claude Code 优先调用它自己的 `claude mcp add-json` / `claude mcp remove`（用户范围的配置在 ~/.claude.json，
+ * 正在运行的 Claude Code 也会写这个文件，不能直接改）；Codex、Cursor 直接改配置文件，改之前备份。
+ */
+import { spawnSync } from 'node:child_process';
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { AGENT_IDS, AGENTS, codexHome } from './agents.js';
+import { api, siteUrl } from './api.js';
+import { jsonServerNames, setJsonServer, setTomlServer, tomlServerNames } from './config-files.js';
+import { configDir } from './credentials.js';
+import { bold, CliError, dim, done, fail, green, info, stars, warn } from './ui.js';
+/** 接受 owner/repo[/sub]，或者网站上的详情页地址 */
+export function parseMcpSpec(input) {
+    const s = input.trim();
+    const fromUrl = /\/mcp\/([^/?#]+\/[^/?#]+(?:\/[^/?#]+)?)\/?(?:[?#].*)?$/.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;
+}
+export async function fetchMcp(spec) {
+    const id = parseMcpSpec(spec);
+    if (!id)
+        return fail('usage', `MCP Server 要写成 owner/repo 或 owner/repo/sub，或者网站上的详情页地址：${spec}`);
+    try {
+        return await api(`/api/cli/mcp/${id}`);
+    }
+    catch (err) {
+        if (err instanceof CliError && err.code === 'not_found')
+            fail('not_found', `没有找到 MCP Server：${id}`, '运行 funcoding mcp find <关键词> 查找');
+        throw err;
+    }
+}
+const describeLaunch = (l) => (l.kind === 'remote' ? `远程服务（${l.transport}）${l.url}` : `${l.registry === 'npm' ? 'npm' : 'PyPI'} 包 ${l.package}${l.version ? `@${l.version}` : ''}`);
+const inputsOf = (l) => (l.kind === 'remote' ? l.headers : l.env);
+const flagOf = (l) => (l.kind === 'remote' ? '--header' : '--env');
+// ---------------- info ----------------
+export async function mcpInfo(spec) {
+    const s = await fetchMcp(spec);
+    const page = siteUrl(s.page);
+    done({ server: { ...s, page } }, () => {
+        info(`${bold(s.name)} ${dim(`${s.id} · ★ ${stars(s.stars)}${s.official ? ' · 官方' : ''}`)}`);
+        if (s.description)
+            info(s.description);
+        info(dim(s.repo.url));
+        info(dim(page));
+        info('');
+        if (s.launches.length === 0)
+            return info(`没有登记标准安装包，配置方法见 README：${s.repo.url}`);
+        info(bold(`启动方式（配置名 ${s.configName}）`));
+        for (const l of s.launches) {
+            info(`  ${describeLaunch(l)}`);
+            for (const i of inputsOf(l))
+                info(dim(`    ${flagOf(l)} ${i.name}=…${i.required ? '（必填）' : ''}${i.description ? ` ${i.description}` : ''}`));
+        }
+    });
+}
+function locationOf(agent, scope, cwd = process.cwd()) {
+    const home = homedir();
+    if (agent === 'codex')
+        return { agent, scope, format: 'toml', file: scope === 'project' ? resolve(cwd, '.codex', 'config.toml') : join(codexHome(), 'config.toml') };
+    if (agent === 'cursor')
+        return { agent, scope, format: 'json', file: scope === 'project' ? resolve(cwd, '.cursor', 'mcp.json') : join(home, '.cursor', 'mcp.json') };
+    return { agent, scope, format: 'json', file: scope === 'project' ? resolve(cwd, '.mcp.json') : null };
+}
+const readText = (file) => readFile(file, 'utf8').catch((err) => (err.code === 'ENOENT' ? null : Promise.reject(err)));
+async function configuredNames(loc) {
+    // Claude Code 用户范围的 Server 在 ~/.claude.json 的 mcpServers 里，只读
+    const file = loc.file ?? join(homedir(), '.claude.json');
+    const text = await readText(file);
+    try {
+        return loc.format === 'toml' ? tomlServerNames(text) : jsonServerNames(text);
+    }
+    catch {
+        warn(`无法解析 ${file}，已跳过`);
+        return [];
+    }
+}
+async function backupFile(file, agent) {
+    if ((await readText(file)) === null)
+        return null;
+    const backup = join(configDir(), 'backups', 'mcp', `${agent}-${basename(file)}-${new Date().toISOString().replace(/[:.]/g, '-')}`);
+    await mkdir(dirname(backup), { recursive: true });
+    await copyFile(file, backup);
+    return backup;
+}
+/** 写入或删除一项（config 为 null 时删除）；返回备份路径 */
+async function writeConfig(loc, name, config) {
+    const text = await readText(loc.file);
+    let next;
+    if (loc.format === 'toml')
+        next = setTomlServer(text, name, config);
+    else {
+        try {
+            next = setJsonServer(text, name, config ? jsonEntry(loc.agent, config) : null);
+        }
+        catch (err) {
+            return fail('error', `无法解析 ${loc.file}：${err.message}`, '请先修正这个文件');
+        }
+    }
+    const backup = await backupFile(loc.file, loc.agent);
+    await mkdir(dirname(loc.file), { recursive: true });
+    await writeFile(loc.file, next);
+    return backup;
+}
+function jsonEntry(agent, c) {
+    if (c.kind === 'stdio')
+        return { type: 'stdio', command: c.command, args: c.args, ...(Object.keys(c.env).length ? { env: c.env } : {}) };
+    // Cursor 的远程服务只写 url（文档示例没有 type）；Claude Code 要写 type
+    const headers = Object.keys(c.headers).length ? { headers: c.headers } : {};
+    return agent === 'cursor' ? { url: c.url, ...headers } : { type: c.transport, url: c.url, ...headers };
+}
+/** 调用 claude 命令；没装 claude 时返回 null */
+function runClaude(args) {
+    const r = spawnSync('claude', args, { encoding: 'utf8', shell: process.platform === 'win32' });
+    if (r.error && r.error.code === 'ENOENT')
+        return null;
+    return { ok: r.status === 0, output: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
+}
+const shellQuote = (s) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
+/** 选一种启动方式：智能体支持、符合 --via、必填项都已提供 */
+export function pickLaunch(launches, agent, opts) {
+    const candidates = launches.filter((l) => {
+        if (agent === 'codex' && l.kind === 'remote' && l.transport === 'sse')
+            return false;
+        if (!opts.via)
+            return true;
+        return opts.via === 'remote' ? l.kind === 'remote' : l.kind === 'stdio' && l.registry === opts.via;
+    });
+    if (candidates.length === 0)
+        return null;
+    for (const l of candidates) {
+        const given = l.kind === 'remote' ? opts.headers : opts.env;
+        if (inputsOf(l).every((i) => !i.required || given[i.name] !== undefined))
+            return { launch: l };
+    }
+    const first = candidates[0];
+    const given = first.kind === 'remote' ? opts.headers : opts.env;
+    return { missing: { launch: first, inputs: inputsOf(first).filter((i) => i.required && given[i.name] === undefined).map((i) => i.name) } };
+}
+export function toConfig(l, opts) {
+    if (l.kind === 'remote')
+        return { kind: 'remote', transport: l.transport, url: l.url, headers: opts.headers };
+    return { kind: 'stdio', command: l.command, args: l.args, env: opts.env };
+}
+/** 配置一个 Server 到多个目标；失败抛 CliError */
+export async function addServer(s, opts) {
+    if (s.devtool)
+        warn(`${s.name} 被归为 MCP 开发工具（SDK、框架等），可能不是可以直接运行的 Server。`);
+    if (s.launches.length === 0)
+        fail('not_found', `${s.name} 没有登记标准安装包，无法自动配置。`, `按 README 手动配置：${s.repo.url}`, { readme: s.repo.url });
+    const name = opts.name ?? s.configName;
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(name))
+        fail('usage', `配置名只能包含字母、数字、下划线和连字符：${name}`);
+    // 先检查所有目标，确定都能写再动手
+    const plan = [];
+    for (const t of opts.targets) {
+        const picked = pickLaunch(s.launches, t.agent, opts);
+        if (!picked)
+            fail('not_found', `${s.name} 没有 ${AGENTS[t.agent].label} 支持的启动方式${opts.via ? `（--via ${opts.via}）` : ''}。`, `可选的启动方式见 funcoding mcp info ${s.id}`);
+        if ('missing' in picked) {
+            const { launch, inputs } = picked.missing;
+            fail('usage', `${s.name} 需要提供：${inputs.join('、')}`, `向用户索取后运行 funcoding mcp add ${s.id} ${inputs.map((i) => `${flagOf(launch)} ${i}=<值>`).join(' ')}`, { missing: inputs, flag: flagOf(launch) });
+        }
+        const loc = locationOf(t.agent, t.scope);
+        if (!opts.force && (await configuredNames(loc)).includes(name))
+            fail('exists', `${AGENTS[t.agent].label} 里已经配置了 ${name}。`, '确认要覆盖就加 --force');
+        plan.push({ loc, config: toConfig(picked.launch, opts), launch: picked.launch });
+    }
+    const results = [];
+    for (const { loc, config, launch } of plan) {
+        const base = { id: s.id, name, agent: loc.agent, scope: loc.scope, launch: describeLaunch(launch) };
+        if (loc.agent === 'claude-code') {
+            const json = JSON.stringify(jsonEntry('claude-code', config));
+            if (opts.force)
+                runClaude(['mcp', 'remove', name, '--scope', loc.scope]);
+            const r = runClaude(['mcp', 'add-json', name, json, '--scope', loc.scope]);
+            if (r?.ok) {
+                results.push({ ...base, file: loc.file });
+                continue;
+            }
+            if (r)
+                fail('error', `claude mcp add-json 失败：${r.output}`);
+            if (!loc.file)
+                fail('error', '没有找到 claude 命令，无法写入 Claude Code 的用户范围配置。', `安装 Claude Code 后运行：claude mcp add-json ${name} ${shellQuote(json)} --scope user`);
+        }
+        const backup = await writeConfig(loc, name, config);
+        results.push({ ...base, file: loc.file, ...(backup ? { backup } : {}) });
+    }
+    return results;
+}
+export async function mcpAdd(spec, opts) {
+    const results = await addServer(await fetchMcp(spec), opts);
+    done({ added: results }, () => {
+        for (const r of results) {
+            info(green(`✓ 已在 ${AGENTS[r.agent].label}（${r.scope === 'user' ? '个人' : '项目'}）配置 ${r.name}`) + dim(` · ${r.launch}`));
+            if (r.file)
+                info(dim(`  ${r.file}`));
+            if (r.backup)
+                info(dim(`  原文件备份在 ${r.backup}`));
+        }
+        if (results.some((r) => r.agent === 'claude-code' && r.scope === 'project'))
+            info(dim('项目范围的 Server 需要在 Claude Code 里确认后才会启用。'));
+        info(dim('重启智能体或新开会话后生效。'));
+    });
+}
+// ---------------- list / remove ----------------
+export async function mcpList(sel) {
+    const servers = [];
+    for (const agent of sel.agents)
+        for (const scope of sel.scopes) {
+            const loc = locationOf(agent, scope);
+            for (const name of await configuredNames(loc))
+                servers.push({ agent, scope, name, file: loc.file ?? join(homedir(), '.claude.json') });
+        }
+    done({ servers }, () => {
+        if (servers.length === 0)
+            return info('还没有配置 MCP Server。');
+        for (const agent of AGENT_IDS)
+            for (const scope of sel.scopes) {
+                const group = servers.filter((s) => s.agent === agent && s.scope === scope);
+                if (group.length === 0)
+                    continue;
+                info(`${bold(AGENTS[agent].label)} ${dim(`${scope === 'user' ? '个人' : '项目'} · ${group[0].file}`)}`);
+                for (const s of group)
+                    info(`  ${s.name}`);
+                info('');
+            }
+    });
+}
+export async function mcpRemove(names, sel) {
+    if (names.length === 0)
+        fail('usage', '缺少要删除的 MCP Server 配置名。', '运行 funcoding mcp list 查看');
+    const removed = [];
+    for (const name of names) {
+        let found = false;
+        for (const agent of sel.agents)
+            for (const scope of sel.scopes) {
+                const loc = locationOf(agent, scope);
+                if (!(await configuredNames(loc)).includes(name))
+                    continue;
+                found = true;
+                if (agent === 'claude-code') {
+                    const r = runClaude(['mcp', 'remove', name, '--scope', scope]);
+                    if (r?.ok) {
+                        removed.push({ agent, scope, name, file: loc.file });
+                        continue;
+                    }
+                    if (r)
+                        fail('error', `claude mcp remove 失败：${r.output}`);
+                    if (!loc.file)
+                        fail('error', '没有找到 claude 命令，无法修改 Claude Code 的用户范围配置。', `安装 Claude Code 后运行：claude mcp remove ${name} --scope user`);
+                }
+                const backup = await writeConfig(loc, name, null);
+                removed.push({ agent, scope, name, file: loc.file, ...(backup ? { backup } : {}) });
+            }
+        if (!found)
+            fail('not_found', `没有找到配置名为 ${name} 的 MCP Server`, '运行 funcoding mcp list 查看');
+    }
+    done({ removed }, () => {
+        for (const r of removed)
+            info(`${green('✓ 已删除')} ${AGENTS[r.agent].label} ${r.name}${r.file ? dim(` · ${r.file}`) : ''}`);
+    });
+}

package/dist/paths.js

@@ -0,0 +1,18 @@
+/** 下载的文件路径来自网络，写盘前必须确认不会跑出目标目录 */
+import { isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+/** 合法的相对路径：不能是绝对路径、不能有 ..、不能有反斜杠和控制字符 */
+export function isSafeRelativePath(p) {
+    if (!p || p.length > 300 || isAbsolute(p) || /[\\\0-\x1f]/.test(p) || /^[a-zA-Z]:/.test(p))
+        return false;
+    return p.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
+/** 把相对路径落到 root 下；越界返回 null */
+export function resolveInside(root, p) {
+    if (!isSafeRelativePath(p))
+        return null;
+    const full = resolve(root, normalize(p));
+    const rel = relative(root, full);
+    return rel && !rel.startsWith('..') && !isAbsolute(rel) && !rel.split(sep).includes('..') ? full : null;
+}
+/** 目录名只允许小写字母、数字和连字符 */
+export const isSafeFolderName = (name) => /^[a-z0-9][a-z0-9-]{0,63}$/.test(name);

package/dist/setup.js

@@ -0,0 +1,78 @@
+/**
+ * setup：
+ * 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))));
+}
+/** 全局安装当前版本；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}（权限不足时参考 https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally）` };
+}
+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));
+        // 之前 setup 装的直接换成新版；同名的其他 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 setup 安装的。`, '确认要覆盖就加 --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 setup(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/sync.js

@@ -0,0 +1,86 @@
+import { siteUrl } from './api.js';
+import { fetchMe, requireToken } from './auth.js';
+import { fetchSkill, installSkill, scanAll } from './install.js';
+import { addServer, fetchMcp } from './mcp.js';
+import { bold, CliError, cyan, dim, done, green, info, stars, truncate, yellow } 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('');
+}
+export async function favorites() {
+    const me = await fetchMe(await requireToken());
+    const { skills, mcp } = me.favorites;
+    done({ skills, mcp }, () => {
+        if (skills.length + mcp.length === 0)
+            return info(`还没有收藏。可以在 ${siteUrl('/skills/')} 收藏 Skill 和 MCP Server。`);
+        printCards('收藏的 Skill', skills, (c) => `funcoding skills add ${c.id}`);
+        printCards('收藏的 MCP Server', mcp, (c) => `funcoding mcp add ${c.id}`);
+        info(dim(`运行 ${cyan('funcoding favorites sync')} 一次安装全部收藏。`));
+    });
+}
+export async function sync(targets, dryRun) {
+    const me = await fetchMe(await requireToken());
+    const items = [];
+    const agents = [...new Set(targets.map((t) => t.agent))];
+    const scopes = [...new Set(targets.map((t) => t.scope))];
+    const installed = await scanAll({ agents, scopes });
+    for (const card of me.favorites.skills) {
+        const missing = targets.filter((t) => !installed.some((s) => s.agent === t.agent && s.scope === t.scope && s.source?.id === card.id));
+        if (missing.length === 0) {
+            items.push({ kind: 'skill', id: card.id, status: 'present', agents });
+            continue;
+        }
+        if (dryRun) {
+            items.push({ kind: 'skill', id: card.id, status: 'planned', agents: missing.map((t) => t.agent) });
+            continue;
+        }
+        try {
+            // 同名目录可能是手动放的或别的来源，不覆盖
+            await installSkill(await fetchSkill(card.id), missing, false);
+            items.push({ kind: 'skill', id: card.id, status: 'installed', agents: missing.map((t) => t.agent) });
+        }
+        catch (err) {
+            if (!(err instanceof CliError))
+                throw err;
+            items.push({ kind: 'skill', id: card.id, status: 'skipped', agents: missing.map((t) => t.agent), reason: err.message, hint: err.hint });
+        }
+    }
+    for (const card of me.favorites.mcp) {
+        try {
+            const server = await fetchMcp(card.id);
+            if (dryRun) {
+                items.push({ kind: 'mcp', id: card.id, status: 'planned', agents });
+                continue;
+            }
+            await addServer(server, { targets, env: {}, headers: {}, force: false });
+            items.push({ kind: 'mcp', id: card.id, status: 'installed', agents });
+        }
+        catch (err) {
+            if (!(err instanceof CliError))
+                throw err;
+            // 已经配置过的算已装；缺少必填项、没有安装包等记为跳过
+            if (err.code === 'exists')
+                items.push({ kind: 'mcp', id: card.id, status: 'present', agents });
+            else
+                items.push({ kind: 'mcp', id: card.id, status: 'skipped', agents, reason: err.message, hint: err.hint ?? (err.code === 'usage' ? undefined : `funcoding mcp info ${card.id}`) });
+        }
+    }
+    done({ dryRun, items }, () => {
+        if (items.length === 0)
+            return info(`还没有收藏。可以在 ${siteUrl('/skills/')} 收藏 Skill 和 MCP Server。`);
+        const label = { installed: green('新装'), present: dim('已装'), skipped: yellow('跳过'), planned: cyan('将安装') };
+        for (const i of items) {
+            info(`${label[i.status]}  ${i.kind === 'skill' ? 'Skill' : 'MCP'} ${i.id}${i.reason ? dim(`：${i.reason}`) : ''}`);
+            if (i.hint)
+                info(dim(`        ${i.hint}`));
+        }
+    });
+}

package/dist/ui.js

@@ -0,0 +1,65 @@
+/**
+ * 输出层。CLI 主要给智能体用，约定：
+ * - 加 --json 时 stdout 只输出一个 JSON 对象（成功 { ok: true, ... }，失败 { ok: false, error: { code, message, hint } }），
+ *   过程提示一律写到 stderr；不加时是给人看的文字
+ * - 退出码固定（见 EXIT），智能体可以据此决定下一步
+ * - 颜色只在交互终端里用，NO_COLOR 或 --json 时关闭
+ */
+export const EXIT = { ok: 0, error: 1, usage: 2, not_found: 3, exists: 4, auth: 5 };
+export class CliError extends Error {
+    code;
+    /** 下一步可以运行的命令或可以做的事 */
+    hint;
+    details;
+    constructor(code, message, hint, details) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.details = details;
+    }
+}
+let json = false;
+export const setJsonMode = (v) => {
+    json = v;
+};
+export const isJsonMode = () => json;
+const color = () => !json && !!process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (color() ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const bold = wrap('1');
+export const dim = wrap('2');
+export const green = wrap('32');
+export const yellow = wrap('33');
+export const red = wrap('31');
+export const cyan = wrap('36');
+/** 给人看的输出：--json 时改写到 stderr，不污染 stdout 的 JSON */
+export const info = (msg) => (json ? console.error(msg) : console.log(msg));
+export const warn = (msg) => console.error(yellow(`! ${msg}`));
+export function fail(code, message, hint, details) {
+    throw new CliError(code, message, hint, details);
+}
+/** 命令的最终结果：--json 时输出 JSON，否则调用 human 打印文字 */
+export function done(data, human) {
+    if (json)
+        console.log(JSON.stringify({ ok: true, ...data }, null, 2));
+    else
+        human();
+}
+export function reportError(err) {
+    if (json) {
+        console.log(JSON.stringify({ ok: false, error: { code: err.code, message: err.message, ...(err.hint ? { hint: err.hint } : {}), ...(err.details ?? {}) } }, null, 2));
+    }
+    else {
+        console.error(red(`✗ ${err.message}`));
+        if (err.hint)
+            console.error(dim(`  ${err.hint}`));
+    }
+    process.exitCode = EXIT[err.code];
+}
+export function stars(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(n >= 10_000 ? 0 : 1)}k` : String(n);
+}
+/** 截断到终端宽度 */
+export function truncate(s, max = (process.stdout.columns || 100) - 4) {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "funcoding-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "funcoding.ai 的命令行：给 AI 编程智能体用，查找和安装 Agent Skills、配置 MCP Server、同步收藏、查看 AI 热点和中文文档",
+  "type": "module",
+  "bin": {
+    "funcoding": "dist/cli.js",
+    "fun": "dist/cli.js",
+    "funcoding-cli": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --experimental-strip-types --no-warnings --test 'src/**/*.test.ts'",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "agent-skills",
+    "mcp",
+    "claude-code",
+    "codex",
+    "cursor",
+    "skills",
+    "cli"
+  ],
+  "homepage": "https://funcoding.ai",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funcodingdev/funcoding_ai.git",
+    "directory": "packages/funcoding-cli"
+  }
+}

package/skill/funcoding/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: funcoding
+description: 用 funcoding 命令行（funcoding-cli）从 funcoding.ai 查找并安装 Agent Skills 和 MCP Server，管理已安装的 Skill，同步用户在网站上的收藏，查看 AI 热点和日报，搜索和阅读 Claude Code、Codex、Cursor 等智能体的中文文档。当用户想找某类 Skill 或 MCP Server、安装或更新 Skill、配置 MCP、同步收藏、了解 AI 圈最近的新闻，或查阅 AI 编程工具的中文文档时使用。
+---
+
+# funcoding
+
+本 Skill 说明如何使用 `funcoding` 命令行（npm 包 `funcoding-cli`，命令可简写为 `fun`）。
+
+## 安装
+
+如果 PATH 里找不到 `funcoding` 命令，运行下面的命令安装（需要 Node.js 18.17 及以上）：
+
+```bash
+npx --yes funcoding-cli@latest init --json
+```
+
+`init` 会全局安装本工具，并装上本 Skill。返回结果里 `cli.status` 为 `failed` 时（比如没有权限），把 `cli.hint` 告诉用户；在用户处理好之前，可以用 `npx --yes funcoding-cli@latest <命令>` 临时代替 `funcoding <命令>`。
+
+`funcoding update` 会把本工具更新到最新版本，并同时更新本 Skill。
+
+## 使用约定
+
+- **始终加 `--json`**：stdout 只输出一个 JSON 对象。成功时是 `{ "ok": true, ... }`，失败时是 `{ "ok": false, "error": { "code", "message", "hint" } }`。过程提示写在 stderr，可以忽略。
+- 出错时先看 `error.hint`，里面通常是下一步该运行的命令或该补的参数。
+- 退出码：0 成功，1 一般错误，2 参数错误或缺少必填项，3 未找到，4 目标已存在（需要 `--force`），5 未登录或登录已过期。
+- `--agent=<name>` 指定装给哪个智能体：`claude-code`、`codex`、`cursor`，多个用逗号分隔；`all` 表示本机检测到的全部智能体。不指定时默认装给 Claude Code。**如果你不是 Claude Code，请显式加上 `--agent`。**
+- `--project` 装到当前项目（可以随仓库提交，团队共用）；不加时装到用户目录，对所有项目生效。
+- 不确定某条命令的参数时，运行 `funcoding <命令> --help`，比如 `funcoding skills add --help`。
+- `funcoding info --json` 返回本机环境：已安装的智能体、各自的 Skill 目录、登录状态。
+
+## Skill 管理
+
+使用 `skills` 命令：
+
+1. `funcoding skills find <query>`：查找 Skill。结果里的 `skills[].id` 形如 `owner/repo/skill`。
+2. **安装前先检查**：`funcoding skills info <id>` 返回 SKILL.md 全文（`skill.content`）和文件清单（`skill.files`，其中的可执行脚本列在 `skill.scripts`）。用一两句话告诉用户这个 Skill 做什么；如果有执行任意命令、读取或外传密钥和个人数据、修改系统设置等危险操作，要明确指出。**得到用户确认后再安装。**
+3. `funcoding skills add <id>... [--agent=<name>] [--project]`：安装。目录已存在时会以退出码 4 停下；向用户确认后再加 `--force`，旧版本会备份到配置目录。
+4. 告诉用户装到了哪个目录（`installed[].dir`），以及如何调用：Claude Code 和 Cursor 输入 `/<目录名>`，Codex 输入 `$<目录名>`，也可以直接描述任务，让智能体自动选用。新装的 Skill 可能需要新开会话才会加载。
+
+管理已安装的 Skill：
+
+- `funcoding skills list`：列出所有智能体在用户目录和当前项目里的 Skill。`source` 不为空的是通过 funcoding 安装的。
+- `funcoding skills update --check`：检查远端 SKILL.md 是否有变化，不安装。`funcoding skills update [<name>]`：按原来源重新安装。
+- `funcoding skills remove <name>...`：删除前会先备份。只能删除通过 funcoding 安装的 Skill；删除其他 Skill 需要加 `--force`，务必先征得用户同意。
+
+## MCP 配置
+
+使用 `mcp` 命令：
+
+1. `funcoding mcp find <query>`：查找 MCP Server。结果里的 `servers[].id` 形如 `owner/repo`。
+2. `funcoding mcp info <id>`：查看可用的启动方式（`server.launches`），每种方式需要的环境变量（`env`）或请求头（`headers`），以及是否必填。
+3. `funcoding mcp add <id> [--agent=<name>] [--project] [--env=KEY=VALUE ...] [--header=KEY=VALUE ...] [--via=remote|npm|pypi]`：
+   - 缺少必填项时，会以退出码 2 返回，`error.missing` 列出缺少的项。**向用户索取这些值，不要编造。** 密钥只通过参数传入，不要写进其他文件。
+   - 没有登记标准安装包时，会以退出码 3 返回，`error.readme` 是 README 地址。这时按 README 手动配置。
+4. 配置在重启智能体或新开会话后生效。Claude Code 项目范围的 Server 需要用户在 Claude Code 里确认后才会启用。
+5. `funcoding mcp list` 列出已配置的 Server；`funcoding mcp remove <name>...` 删除，删除前会备份原文件。
+
+## 收藏
+
+用户在 funcoding.ai 上收藏的 Skill 和 MCP Server，需要先登录：
+
+- `funcoding auth status`：查看是否已登录。返回退出码 5 表示未登录。
+- `funcoding auth login`：会显示验证码和授权地址（在 stderr 中），并尝试打开浏览器。把地址和验证码告诉用户，请用户在浏览器中确认；命令会一直等到用户确认后才返回。
+- `funcoding favorites list`：列出收藏。
+- `funcoding favorites sync [--agent=<name>] [--project] [--dry-run]`：安装全部收藏，已装的跳过。建议先用 `--dry-run` 给用户看将要安装什么。`items[]` 里 `status` 为 `skipped` 的条目附有原因和提示，通常是 MCP 缺少必填的环境变量。
+
+## AI 热点
+
+- `funcoding news list [--limit=<n>]`：当前 AI 热榜（多家来源报道的事件，按热度排序，附中文标题和摘要）。
+- `funcoding news daily [<YYYY-MM-DD>]`：某一天的 AI 日报，不写日期时为最新一期。
+
+## 文档
+
+`docs` 命令用来查阅 AI 编程智能体的中文文档。这些文档按官方文档的章节结构整理，并标注了官方来源和核实日期。
+
+- `funcoding docs search <query> [--agent=<slug>]`：搜索文档。这里的 `--agent` 可以是站内任意智能体，比如 `claude-code`、`codex`、`cursor`、`gemini-cli`。
+- `funcoding docs fetch <agent>/<path>`：读取文档全文（Markdown），开头附官方来源链接和核实日期。命令、配置和价格以官方文档为准。
+
+## `funcoding help` 输出
+
+```
+Usage: funcoding [-hV] [--json] <command>
+
+Commands:
+  init       初始化：全局安装本工具（之后可用 funcoding 或 fun），并给智能体装上 funcoding Skill
+  update     把本工具更新到最新版本，并刷新已安装的 funcoding Skill
+  info       环境信息：版本、站点、登录状态、本机的智能体和 Skill 目录、配置目录
+  help       显示帮助
+  skills     查找、安装和管理 Agent Skills（find / info / add / list / update / remove）
+  mcp        查找 MCP Server，并写入各智能体的 MCP 配置（find / info / add / list / remove）
+  favorites  网站上收藏的 Skill 和 MCP Server（list / sync）
+  auth       登录 funcoding.ai（login / logout / status）
+  news       AI 热点（list / daily）
+  docs       AI 编程智能体的中文文档（search / fetch）
+```