funcoding-cli 0.3.0 → 0.4.0

package/dist/mcp.js

@@ -11,7 +11,7 @@ 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';
+import { bold, CliError, cyan, dim, done, fail, info, next, stars, success, warn } from './ui.js';
 /** 接受 owner/repo[/sub]，或者网站上的详情页地址 */
 export function parseMcpSpec(input) {
     const s = input.trim();
@@ -22,13 +22,13 @@ export function parseMcpSpec(input) {
 export async function fetchMcp(spec) {
     const id = parseMcpSpec(spec);
     if (!id)
-        return fail('usage', `MCP Server 要写成 owner/repo 或 owner/repo/sub，或者网站上的详情页地址：${spec}`);
+        return fail('usage', `无法识别的 MCP Server：${spec}`, '写成 owner/repo、owner/repo/sub，或网站上的详情页地址');
     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 <关键词> 查找');
+            fail('not_found', `没有找到 MCP Server：${id}`, '运行 funcoding mcp find <关键词>');
         throw err;
     }
 }
@@ -47,7 +47,7 @@ export async function mcpInfo(spec) {
         info(dim(page));
         info('');
         if (s.launches.length === 0)
-            return info(`没有登记标准安装包，配置方法见 README：${s.repo.url}`);
+            return info(`没有标准安装包，按 README 手动配置：${s.repo.url}`);
         info(bold(`启动方式（配置名 ${s.configName}）`));
         for (const l of s.launches) {
             info(`  ${describeLaunch(l)}`);
@@ -73,7 +73,7 @@ async function configuredNames(loc) {
         return loc.format === 'toml' ? tomlServerNames(text) : jsonServerNames(text);
     }
     catch {
-        warn(`无法解析 ${file}，已跳过`);
+        warn(`无法解析，已跳过：${file}`);
         return [];
     }
 }
@@ -96,7 +96,7 @@ async function writeConfig(loc, name, config) {
             next = setJsonServer(text, name, config ? jsonEntry(loc.agent, config) : null);
         }
         catch (err) {
-            return fail('error', `无法解析 ${loc.file}：${err.message}`, '请先修正这个文件');
+            return fail('error', `无法解析：${loc.file}（${err.message}）`, '修正这个文件后重试');
         }
     }
     const backup = await backupFile(loc.file, loc.agent);
@@ -147,25 +147,25 @@ export function toConfig(l, opts) {
 /** 配置一个 Server 到多个目标；失败抛 CliError */
 export async function addServer(s, opts) {
     if (s.devtool)
-        warn(`${s.name} 被归为 MCP 开发工具（SDK、框架等），可能不是可以直接运行的 Server。`);
+        warn(`${s.name} 属于 MCP 开发工具（SDK、框架等），可能不能直接运行`);
     if (s.launches.length === 0)
-        fail('not_found', `${s.name} 没有登记标准安装包，无法自动配置。`, `按 README 手动配置：${s.repo.url}`, { readme: s.repo.url });
+        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}`);
+        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}`);
+            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');
+            fail('exists', `${AGENTS[t.agent].label} 已配置 ${name}`, '覆盖请加 --force');
         plan.push({ loc, config: toConfig(picked.launch, opts), launch: picked.launch });
     }
     const results = [];
@@ -183,7 +183,7 @@ export async function addServer(s, opts) {
             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`);
+                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 } : {}) });
@@ -193,16 +193,11 @@ export async function addServer(s, opts) {
 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}`));
-        }
+        for (const r of results)
+            success(`已配置 ${r.name}（${AGENTS[r.agent].label}，${r.scope === 'user' ? '用户目录' : '当前项目'}）`, [r.launch, r.file, r.backup && `备份：${r.backup}`]);
         if (results.some((r) => r.agent === 'claude-code' && r.scope === 'project'))
-            info(dim('项目范围的 Server 需要在 Claude Code 里确认后才会启用。'));
-        info(dim('重启智能体或新开会话后生效。'));
+            warn('当前项目的 Server 需要在 Claude Code 里确认后才会启用');
+        next('重启智能体或新开会话');
     });
 }
 // ---------------- list / remove ----------------
@@ -215,14 +210,16 @@ export async function mcpList(sel) {
                 servers.push({ agent, scope, name, file: loc.file ?? join(homedir(), '.claude.json') });
         }
     done({ servers }, () => {
-        if (servers.length === 0)
-            return info('还没有配置 MCP Server。');
+        if (servers.length === 0) {
+            info('暂无已配置的 MCP Server');
+            return next(cyan('funcoding mcp find <关键词>'));
+        }
         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}`)}`);
+                info(`${bold(AGENTS[agent].label)} ${dim(`${scope === 'user' ? '用户目录' : '当前项目'}  ${group[0].file}`)}`);
                 for (const s of group)
                     info(`  ${s.name}`);
                 info('');
@@ -231,7 +228,7 @@ export async function mcpList(sel) {
 }
 export async function mcpRemove(names, sel) {
     if (names.length === 0)
-        fail('usage', '缺少要删除的 MCP Server 配置名。', '运行 funcoding mcp list 查看');
+        fail('usage', '缺少要删除的配置名', '运行 funcoding mcp list');
     const removed = [];
     for (const name of names) {
         let found = false;
@@ -250,16 +247,16 @@ export async function mcpRemove(names, sel) {
                     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`);
+                        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 查看');
+            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}`) : ''}`);
+            success(`已删除 ${r.name}（${AGENTS[r.agent].label}）`, [r.file]);
     });
 }

package/dist/setup.js

@@ -0,0 +1,140 @@
+/**
+ * cli setup / cli upgrade，做法参照 sentry-cli（cli.sentry.dev/agentic-usage）：
+ * - setup：没有全局安装时用 npm 全局安装本 CLI（--no-global 跳过），再把随 CLI 发布的 funcoding-cli Skill
+ *   （skill/funcoding-cli/：SKILL.md + references/）装到本机检测到的各智能体的用户目录（--no-agent-skills 跳过），
+ *   让智能体知道什么时候、怎么用这个 CLI。Skill 打包在 CLI 里，不联网
+ * - upgrade：全局安装最新版，再用新版刷新已安装的 funcoding-cli Skill
+ * 旧版本装的 funcoding Skill（init 时代）在 setup 和刷新时一并删掉
+ */
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { cp, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { AGENT_IDS, AGENTS, DEFAULT_AGENT, installedAgents, skillsRoot } from './agents.js';
+import { USER_AGENT, VERSION } from './api.js';
+import { META_FILE, moveAway } from './install.js';
+import { done, fail, next, step, success, warn } from './ui.js';
+const isWindows = process.platform === 'win32';
+/** 随 CLI 发布的 Skill 的目录名，也是它的 name */
+export const AGENT_SKILL = 'funcoding-cli';
+/** 0.3 及以前 init 装的同类 Skill，setup 和刷新时删掉 */
+const LEGACY_SKILL = 'funcoding';
+const SOURCE_DIR = new URL('../skill/funcoding-cli/', import.meta.url);
+/** 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';
+function npmInstall(spec) {
+    // npm 的输出写到 stderr，不影响 --json 的 stdout
+    return spawnSync('npm', ['install', '--global', spec], { stdio: ['ignore', process.stderr, process.stderr], shell: isWindows }).status === 0;
+}
+function installGlobal() {
+    if (onPath('funcoding'))
+        return { status: 'present' };
+    const pkg = `funcoding-cli@${VERSION}`;
+    step(`正在全局安装 funcoding-cli ${VERSION}`);
+    if (npmInstall(pkg))
+        return { status: 'installed' };
+    return { status: 'failed', hint: `运行 npm install -g ${pkg}（权限不足见 ${EACCES_DOC}）` };
+}
+/**
+ * 要装 Skill 的智能体：本机检测到的全部；~/.agents 存在也算（Codex 和其他读 ~/.agents/skills 的智能体用它）；
+ * 一个都没检测到时装给默认的 Claude Code
+ */
+export function skillAgents(home = homedir()) {
+    const found = new Set(installedAgents({ home }));
+    if (existsSync(join(home, '.agents')))
+        found.add('codex');
+    return found.size > 0 ? AGENT_IDS.filter((a) => found.has(a)) : [DEFAULT_AGENT];
+}
+/** 随 CLI 发布的 SKILL.md（skills update --check 用来比较） */
+export const agentSkillContent = () => readFile(new URL('SKILL.md', SOURCE_DIR), 'utf8');
+const exists = (p) => stat(p).then(() => true, () => false);
+const isOurs = async (dir) => {
+    const meta = await readFile(join(dir, META_FILE), 'utf8').catch(() => null);
+    return !!meta && !!JSON.parse(meta).builtin;
+};
+/** 把 funcoding-cli Skill 装到这些智能体；同名但不是本 CLI 装的目录要 --force，并且先备份 */
+export async function installAgentSkill(targets, force) {
+    const plan = targets.map((t) => ({ ...t, root: skillsRoot(t.agent, t.scope), dir: join(skillsRoot(t.agent, t.scope), AGENT_SKILL) }));
+    const foreign = [];
+    for (const p of plan)
+        if ((await exists(p.dir)) && !(await isOurs(p.dir)))
+            foreign.push(p.dir);
+    if (foreign.length > 0 && !force)
+        fail('exists', `已存在同名 Skill：${foreign.join('、')}`, '覆盖请加 --force（会先备份）', { paths: foreign });
+    const results = [];
+    for (const p of plan) {
+        await mkdir(p.root, { recursive: true });
+        const tmp = join(p.root, `.funcoding-tmp-${randomBytes(4).toString('hex')}`);
+        await cp(SOURCE_DIR, tmp, { recursive: true });
+        await writeFile(join(tmp, META_FILE), `${JSON.stringify({ id: AGENT_SKILL, name: AGENT_SKILL, builtin: true, installedAt: new Date().toISOString(), cli: USER_AGENT }, null, 2)}\n`);
+        let backup;
+        if (await exists(p.dir)) {
+            if (await isOurs(p.dir))
+                await rm(p.dir, { recursive: true, force: true });
+            else
+                backup = await moveAway(p.dir, p.agent, AGENT_SKILL);
+        }
+        await rename(tmp, p.dir);
+        // 旧版 funcoding Skill：只删本 CLI 装的
+        const legacy = join(p.root, LEGACY_SKILL);
+        const removedLegacy = (await isOurs(legacy)) ? legacy : undefined;
+        if (removedLegacy)
+            await rm(removedLegacy, { recursive: true, force: true });
+        results.push({ agent: p.agent, scope: p.scope, dir: p.dir, ...(backup ? { backup } : {}), ...(removedLegacy ? { removedLegacy } : {}) });
+    }
+    return results;
+}
+export async function setup(opts) {
+    const cli = opts.global ? installGlobal() : { status: 'skipped' };
+    const skills = opts.agentSkills ? await installAgentSkill(skillAgents().map((agent) => ({ agent, scope: 'user' })), opts.force) : [];
+    done({ version: VERSION, cli, skills }, () => {
+        if (cli.status === 'installed')
+            success(`已全局安装 funcoding-cli ${VERSION}`, ['命令：funcoding（简写 fun）']);
+        if (cli.status === 'present')
+            success(`已全局安装 funcoding-cli`, ['命令：funcoding（简写 fun）']);
+        if (cli.status === 'failed')
+            warn(`全局安装失败。${cli.hint}`);
+        if (skills.length > 0) {
+            success(`已为 ${skills.map((s) => AGENTS[s.agent].label).join('、')} 安装智能体 Skill：${AGENT_SKILL}`, [
+                ...skills.map((s) => s.dir),
+                ...skills.flatMap((s) => (s.backup ? [`备份：${s.backup}`] : [])),
+            ]);
+            next('新开智能体会话，直接描述需求');
+        }
+    });
+}
+export function upgrade() {
+    step('正在全局安装 funcoding-cli@latest');
+    if (!npmInstall('funcoding-cli@latest'))
+        fail('error', '升级失败', `运行 npm install -g funcoding-cli@latest（权限不足见 ${EACCES_DOC}）`);
+    const version = spawnSync('funcoding', ['--version'], { encoding: 'utf8', shell: isWindows }).stdout?.trim() || null;
+    // 用新版本刷新已安装的智能体 Skill（包括旧版的 funcoding）；一个都没装过时会报未找到，忽略
+    const refreshed = spawnSync('funcoding', ['skills', 'update', AGENT_SKILL, '--json'], { encoding: 'utf8', shell: isWindows });
+    const skills = (() => {
+        try {
+            return JSON.parse(refreshed.stdout).skills ?? [];
+        }
+        catch {
+            return [];
+        }
+    })();
+    done({ from: VERSION, to: version, skills }, () => {
+        if (version && version !== VERSION)
+            success(`已升级到 funcoding-cli ${version}`, [`原版本 ${VERSION}`]);
+        else
+            success(`已是最新版本 ${version ?? VERSION}`);
+        if (skills.length > 0)
+            success('已刷新智能体 Skill', skills.map((s) => s.dir));
+    });
+}
+/** 用于 info：本机已装的 funcoding-cli Skill 目录 */
+export const agentSkillDirs = (home = homedir()) => AGENT_IDS.map((a) => join(home, ...AGENTS[a].skills, AGENT_SKILL)).filter((d) => existsSync(d));

package/dist/skill-docs.js

@@ -0,0 +1,36 @@
+/**
+ * 由命令表生成 funcoding-cli Skill 的 references/<分组>.md（每组命令一份，智能体按需读取），
+ * 并把 SKILL.md frontmatter 里的 version 同步成 package.json 的版本。
+ * 写文件在 scripts/gen-skill.ts（pnpm skill），skill-docs.test.ts 检查仓库里的文件是不是最新的
+ */
+import { BIN, COMMANDS, GLOBAL, OPTIONS } from './commands.js';
+function renderCommand(group, cmd) {
+    const params = (cmd.params ?? []).map(([p]) => p).join(' ');
+    const out = [`## ${[BIN, group.name, cmd.name, params].filter(Boolean).join(' ')}`, '', cmd.summary];
+    if (cmd.params?.length)
+        out.push('', '参数：', '', ...cmd.params.map(([p, d]) => `- \`${p}\`：${d}`));
+    if (cmd.options?.length)
+        out.push('', '选项：', '', ...cmd.options.map((k) => `- \`${OPTIONS[k].flag}\`：${OPTIONS[k].desc}`));
+    if (cmd.examples?.length)
+        out.push('', '示例：', '', '```bash', ...cmd.examples, '```');
+    return out.join('\n');
+}
+/** 文件名 → 内容 */
+export function renderReferences() {
+    const out = {};
+    const global = GLOBAL.map((k) => `\`${OPTIONS[k].flag}\``).join('、');
+    for (const group of COMMANDS.filter((c) => c.commands)) {
+        const body = [
+            `# ${BIN} ${group.name}`,
+            '',
+            group.summary,
+            '',
+            `所有命令都支持 ${global}。本文件由 scripts/gen-skill.ts 根据命令表生成。`,
+            ...group.commands.flatMap((cmd) => ['', renderCommand(group, cmd)]),
+        ];
+        out[`${group.name}.md`] = `${body.join('\n')}\n`;
+    }
+    return out;
+}
+/** 把 SKILL.md frontmatter 里的 version 换成 version */
+export const withVersion = (skillMd, version) => skillMd.replace(/^version: .*$/m, `version: ${version}`);

package/dist/sync.js

@@ -2,7 +2,7 @@ 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';
+import { bold, CliError, cyan, dim, done, green, info, next, stars, truncate, yellow } from './ui.js';
 export function printCards(title, cards, hrefOf) {
     if (cards.length === 0)
         return;
@@ -19,19 +19,23 @@ 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。`);
+        if (skills.length + mcp.length === 0) {
+            info('暂无收藏');
+            return next(`在 ${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')} 一次安装全部收藏。`));
+        next(cyan('funcoding favorites sync'));
     });
 }
 export async function sync(targets, dryRun) {
     const me = await fetchMe(await requireToken());
     const items = await installCards(me.favorites, targets, dryRun);
     done({ dryRun, items }, () => {
-        if (items.length === 0)
-            return info(`还没有收藏。可以在 ${siteUrl('/skills/')} 收藏 Skill 和 MCP Server。`);
+        if (items.length === 0) {
+            info('暂无收藏');
+            return next(`在 ${siteUrl('/skills/')} 收藏 Skill 或 MCP Server`);
+        }
         printItems(items);
     });
 }
@@ -84,9 +88,9 @@ export async function installCards(cards, targets, dryRun) {
     }
     return items;
 }
-/** 按「新装 / 已装 / 跳过 / 将安装」逐行打印 installCards 的结果 */
+/** 按「已安装 / 已存在 / 跳过 / 待安装」逐行打印 installCards 的结果 */
 export function printItems(items) {
-    const label = { installed: green('新装'), present: dim('已装'), skipped: yellow('跳过'), planned: cyan('将安装') };
+    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)

package/dist/ui.js

@@ -4,7 +4,14 @@
  *   过程提示一律写到 stderr；不加时是给人看的文字
  * - 退出码固定（见 EXIT），智能体可以据此决定下一步
  * - 颜色只在交互终端里用，NO_COLOR 或 --json 时关闭
+ * 给人看的文字统一用这几种行（写法规则见 README「输出」）：
+ *   正在…            step()     进度，灰色
+ *   ✓ 已<动词><对象>  success()  结果；下面缩进两格、灰色的是细节（路径、版本、备份位置）
+ *   ! …              warn()     提醒
+ *   ✗ …              reportError()  错误，下一行是怎么办
+ *   下一步：…         next()     只在确实需要时出现
  */
+import { homedir } from 'node:os';
 export const EXIT = { ok: 0, error: 1, usage: 2, not_found: 3, exists: 4, auth: 5 };
 export class CliError extends Error {
     code;
@@ -22,6 +29,11 @@ let json = false;
 export const setJsonMode = (v) => {
     json = v;
 };
+/** --quiet：不输出给人看的文字（--json 的结果照常输出） */
+let quiet = false;
+export const setQuiet = (v) => {
+    quiet = 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);
@@ -32,8 +44,37 @@ 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 const info = (msg) => {
+    if (quiet)
+        return;
+    if (json)
+        console.error(msg);
+    else
+        console.log(msg);
+};
+export const warn = (msg) => {
+    if (!quiet)
+        console.error(yellow(`! ${msg}`));
+};
+/** 进度：正在做什么 */
+export const step = (msg) => info(dim(`${msg}…`));
+/** 给人看的文字里，用户主目录写成 ~（细节行里可能是「备份：<路径>」） */
+export const tildify = (text) => {
+    const home = homedir();
+    return text.replace(new RegExp(`${home.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[\\/]|$)`, 'g'), '~');
+};
+/** 结果：✓ 一行，下面是缩进的细节（路径里的用户主目录写成 ~） */
+export const success = (msg, details = []) => {
+    info(green(`✓ ${msg}`));
+    for (const d of details)
+        if (d)
+            info(dim(`  ${tildify(d)}`));
+};
+/** 下一步：一条一行 */
+export const next = (...lines) => {
+    for (const l of lines)
+        info(`${dim('下一步：')}${l}`);
+};
 export function fail(code, message, hint, details) {
     throw new CliError(code, message, hint, details);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "funcoding-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "funcoding.ai 的命令行：给 AI 编程智能体用，查找和安装 Agent Skills、配置 MCP Server、同步收藏、查看 AI 热点和中文文档",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "skill"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "skill": "node --experimental-strip-types --no-warnings scripts/gen-skill.ts",
+    "build": "pnpm skill && rm -rf dist && tsc -p tsconfig.json",
     "test": "node --experimental-strip-types --no-warnings --test 'src/**/*.test.ts'",
     "prepublishOnly": "pnpm build && pnpm test"
   },

package/skill/funcoding-cli/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: funcoding-cli
+version: 0.4.0
+description: 用 funcoding 命令行（funcoding-cli）从 funcoding.ai 查找并安装 Agent Skills 和 MCP Server，管理已安装的 Skill，同步用户在网站上的收藏和别人分享的清单，查看 AI 热点和日报，搜索和阅读 Claude Code、Codex、Cursor 等智能体的中文文档。当用户想找某类 Skill 或 MCP Server、安装或更新 Skill、配置 MCP、同步收藏，了解最近的 AI 新闻，或查阅 AI 编程工具的中文文档时使用。
+requires:
+  bins: ["funcoding"]
+---
+
+# funcoding-cli
+
+`funcoding` 命令（npm 包 `funcoding-cli`，简写 `fun`）连接 funcoding.ai：Skill 和 MCP Server 目录、用户的收藏、AI 热点、中文文档。
+
+> **核心规则：直接运行命令，始终加 `--json`。** 不要自己拼网站接口、不要去 GitHub 上找文件、不要手改各智能体的配置文件，这些 CLI 都会做，并且会先备份。
+
+## 约定
+
+- **`--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`，**在其他智能体里必须写**。
+- **`--project`**：安装到当前项目（可以随仓库提交）；不加时安装到用户目录。
+- **不确定参数时**：先读 `references/` 下对应的文件，或运行 `funcoding <命令> --help`。
+- **环境**：`funcoding info --json` 返回版本、登录状态、本机检测到的智能体和各自的 Skill 目录。
+
+没有 `funcoding` 命令时运行 `npx --yes funcoding-cli@latest cli setup --json`；`cli.status` 为 `failed` 时把 `cli.hint` 告诉用户，在那之前用 `npx --yes funcoding-cli@latest <命令>` 代替。
+
+## 安装 Skill
+
+1. `funcoding skills find <关键词> --json`：结果的 `skills[].id` 形如 `owner/repo/skill`。
+2. **安装前检查**：`funcoding skills info <id> --json` 返回 SKILL.md 全文（`skill.content`）和文件清单（`skill.files`，可执行脚本在 `skill.scripts`）。用一两句话告诉用户它做什么；有执行任意命令、读取或外传密钥和个人数据、修改系统设置等操作时要明确指出。**得到用户确认后再安装。**
+3. `funcoding skills add <id> --json`：目录已存在时以退出码 4 停下，向用户确认后再加 `--force`（旧版本会先备份）。
+4. 告诉用户安装位置（`installed[].dir`）和调用方式：Claude Code、Cursor 输入 `/<目录名>`，Codex 输入 `$<目录名>`，也可以直接描述任务。新开会话后生效。
+
+`skills list` 列出已安装的 Skill（`source` 不为空的是 funcoding 安装的）；`skills update [--check]` 检查或更新；`skills remove` 删除前会备份，删除其他来源的 Skill 要 `--force`，先征得用户同意。
+
+## 配置 MCP Server
+
+1. `funcoding mcp find <关键词> --json`，再用 `funcoding mcp info <id> --json` 看启动方式（`server.launches`）和需要的环境变量（`env`）或请求头（`headers`）。
+2. `funcoding mcp add <id> --env=KEY=VALUE --header=KEY=VALUE --json`：
+   - 缺少必填项时以退出码 2 返回，`error.missing` 列出缺少的项。**向用户索取，不要编造**；密钥只通过参数传入，不要写进别的文件。
+   - 没有标准安装包时以退出码 3 返回，`error.readme` 是 README 地址，按 README 手动配置。
+3. 重启智能体或新开会话后生效。Claude Code 当前项目的 Server 需要用户在 Claude Code 里确认。
+
+## 收藏和清单
+
+- 收藏需要登录：`funcoding auth status --json` 退出码 5 表示未登录；`funcoding auth login` 会在 stderr 输出验证码和链接，并尝试打开浏览器，把链接和验证码告诉用户，命令会等到用户确认后才返回。
+- `funcoding favorites sync --dry-run --json` 先给用户看会安装什么，再去掉 `--dry-run` 执行。
+- 用户发来 `https://funcoding.ai/share/<id>/` 时：`funcoding lists info <链接> --json` 查看，`funcoding lists add <链接> --dry-run --json` 预览后安装。不需要登录。
+- 两者结果的 `items[].status`：`installed` 已安装，`present` 已存在，`skipped` 跳过（附 `reason` 和 `hint`，多半是 MCP 缺少必填的环境变量），`planned` 待安装（`--dry-run`）。
+
+## 热点和文档
+
+- `funcoding news list --json`：当前 AI 热榜；`funcoding news daily [YYYY-MM-DD] --json`：AI 日报。数据来自 AIHOT，转述时保留来源。
+- `funcoding docs search <关键词> [--agent=<slug>] --json`，`funcoding docs fetch <智能体>/<路径> --json`：中文文档全文，附官方来源和核实日期；命令、配置和价格以官方文档为准。
+
+## 命令参考
+
+| 文件 | 命令 |
+| --- | --- |
+| [references/cli.md](references/cli.md) | `cli setup`、`cli upgrade` |
+| [references/skills.md](references/skills.md) | `skills find / info / add / list / update / remove` |
+| [references/mcp.md](references/mcp.md) | `mcp find / info / add / list / remove` |
+| [references/favorites.md](references/favorites.md) | `favorites list / sync` |
+| [references/lists.md](references/lists.md) | `lists info / add` |
+| [references/auth.md](references/auth.md) | `auth login / logout / status` |
+| [references/news.md](references/news.md) | `news list / daily` |
+| [references/docs.md](references/docs.md) | `docs search / fetch` |

package/skill/funcoding-cli/references/auth.md

@@ -0,0 +1,21 @@
+# funcoding auth
+
+登录 funcoding.ai
+
+所有命令都支持 `--json`、`-h, --help`、`-V, --version`。本文件由 scripts/gen-skill.ts 根据命令表生成。
+
+## funcoding auth login
+
+在浏览器中授权登录（设备码）
+
+选项：
+
+- `--no-browser`：不自动打开浏览器
+
+## funcoding auth logout
+
+退出登录，并使登录凭证失效
+
+## funcoding auth status
+
+查看当前登录的账号

package/skill/funcoding-cli/references/cli.md

@@ -0,0 +1,27 @@
+# funcoding cli
+
+安装、升级本工具
+
+所有命令都支持 `--json`、`-h, --help`、`-V, --version`。本文件由 scripts/gen-skill.ts 根据命令表生成。
+
+## funcoding cli setup
+
+全局安装本工具，并为本机的智能体安装 funcoding-cli Skill
+
+选项：
+
+- `--no-global`：不全局安装
+- `--no-agent-skills`：不为智能体安装 funcoding-cli Skill
+- `-f, --force`：目标已存在时覆盖（原内容先备份到配置目录）
+- `-q, --quiet`：不输出给人看的文字（脚本里用）
+
+示例：
+
+```bash
+npx --yes funcoding-cli@latest cli setup
+funcoding cli setup --no-agent-skills
+```
+
+## funcoding cli upgrade
+
+升级到最新版本，并刷新已安装的 funcoding-cli Skill

package/skill/funcoding-cli/references/docs.md

@@ -0,0 +1,26 @@
+# funcoding docs
+
+AI 编程智能体的中文文档
+
+所有命令都支持 `--json`、`-h, --help`、`-V, --version`。本文件由 scripts/gen-skill.ts 根据命令表生成。
+
+## funcoding docs search <query>
+
+搜索文档
+
+参数：
+
+- `<query>`：关键词
+
+选项：
+
+- `-a, --agent=<slug>`：只搜这个智能体的文档，比如 claude-code、codex、gemini-cli
+- `--limit=<n>`：返回条数（1–30，默认 10）
+
+## funcoding docs fetch <path>
+
+读取文档全文（Markdown），开头附官方来源和核实日期
+
+参数：
+
+- `<path>`：<智能体>/<路径>，比如 claude-code/build/hooks；也可以是网站上的文档地址

package/skill/funcoding-cli/references/favorites.md

@@ -0,0 +1,19 @@
+# funcoding favorites
+
+网站上收藏的 Skill 和 MCP Server（需要登录）
+
+所有命令都支持 `--json`、`-h, --help`、`-V, --version`。本文件由 scripts/gen-skill.ts 根据命令表生成。
+
+## funcoding favorites list
+
+列出收藏
+
+## funcoding favorites sync
+
+安装全部收藏，已安装的跳过
+
+选项：
+
+- `-a, --agent=<name>`：目标智能体：claude-code、codex、cursor，多个用逗号分隔，all 表示本机检测到的全部（默认：当前所在的智能体，否则 claude-code）
+- `-p, --project`：安装到当前项目（可随仓库提交），不加时安装到用户目录
+- `--dry-run`：只列出将要执行的操作