funcoding-cli 0.2.1 → 0.4.0

package/dist/lists.js

@@ -0,0 +1,42 @@
+import { api } from './api.js';
+import { installCards, printCards, printItems } from './sync.js';
+import { bold, cyan, dim, done, fail, info, next } from './ui.js';
+const SHARE_ID = /^[23456789abcdefghijkmnpqrstuvwxyz]{10}$/;
+/** 从分享链接或裸 id 里取出清单 id，不合法返回 undefined */
+export function parseShareId(input) {
+    const s = input.trim();
+    const m = /\/share\/([^/?#]+)/.exec(s);
+    const id = (m ? m[1] : s).toLowerCase();
+    return SHARE_ID.test(id) ? id : undefined;
+}
+async function fetchList(input) {
+    const id = parseShareId(input);
+    if (!id)
+        fail('usage', `无法识别的清单链接：${input}`, '链接形如 https://funcoding.ai/share/k3x9q2abcd/');
+    return api(`/api/cli/lists/${id}`);
+}
+export async function listInfo(input) {
+    const list = await fetchList(input);
+    done({ ...list }, () => {
+        info(`${bold(list.title)} ${dim(`· ${list.owner.name} 分享`)}`);
+        if (list.description)
+            info(list.description);
+        info(dim(list.url));
+        info('');
+        if (list.skills.length + list.mcp.length === 0)
+            return info('清单为空');
+        printCards('Skill', list.skills, (c) => `funcoding skills add ${c.id}`);
+        printCards('MCP Server', list.mcp, (c) => `funcoding mcp add ${c.id}`);
+        next(cyan(`funcoding lists add ${list.shareId}`));
+    });
+}
+export async function listAdd(input, targets, dryRun) {
+    const list = await fetchList(input);
+    const items = await installCards(list, targets, dryRun);
+    done({ dryRun, list: { shareId: list.shareId, title: list.title, url: list.url }, items }, () => {
+        info(`${bold(list.title)} ${dim(`· ${list.owner.name} 分享`)}`);
+        if (items.length === 0)
+            return info('清单为空');
+        printItems(items);
+    });
+}

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

@@ -1,19 +1,27 @@
 /**
- * setup：
- * 1. 没有全局安装时用 npm 全局安装本 CLI，之后终端里可以直接用 funcoding 或简写 fun（--no-global 跳过）
- * 2. 把随 CLI 发布的 funcoding Skill（skill/funcoding/SKILL.md）装到智能体，让它知道什么时候、怎么用这个 CLI。
- *    这个 Skill 不在网站目录里，来源记录标成 builtin，update 时从当前版本的 CLI 重新复制
+ * 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 { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { delimiter, dirname, join } from 'node:path';
-import { AGENTS, skillsRoot } from './agents.js';
+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 { cyan, dim, done, fail, green, info, warn } from './ui.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', ''] : [''];
@@ -22,57 +30,111 @@ export function onPath(command, env = process.env) {
         .filter((dir) => dir && !/[\\/]_npx[\\/]/.test(dir))
         .some((dir) => exts.some((ext) => existsSync(join(dir, command + ext))));
 }
-/** 全局安装当前版本；npm 的输出写到 stderr，不影响 --json 的 stdout */
+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}`;
-    info(dim(`正在全局安装 ${pkg}，之后可以直接使用 funcoding 或 fun 命令…`));
-    const r = spawnSync('npm', ['install', '--global', pkg], { stdio: ['ignore', process.stderr, process.stderr], shell: isWindows });
-    if (r.status === 0)
+    step(`正在全局安装 funcoding-cli ${VERSION}`);
+    if (npmInstall(pkg))
         return { status: 'installed' };
-    return { status: 'failed', hint: `手动运行 npm install -g ${pkg}（权限不足时参考 https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally）` };
+    return { status: 'failed', hint: `运行 npm install -g ${pkg}（权限不足见 ${EACCES_DOC}）` };
 }
-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) }));
+/**
+ * 要装 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 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);
-    }
+    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', `${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);
+        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 dirs;
+    return results;
 }
-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 })) }, () => {
+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')
-            info(green(`✓ 已全局安装 funcoding-cli，在终端里输入 ${cyan('funcoding')} 或 ${cyan('fun')} 即可使用`));
+            success(`已全局安装 funcoding-cli ${VERSION}`, ['命令：funcoding（简写 fun）']);
+        if (cli.status === 'present')
+            success(`已全局安装 funcoding-cli`, ['命令：funcoding（简写 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(' / ')} 主动调用。新开会话后生效。`));
+            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,8 +2,8 @@ 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) {
+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;
     info(bold(title));
@@ -19,20 +19,33 @@ 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) {
+            info('暂无收藏');
+            return next(`在 ${siteUrl('/skills/')} 收藏 Skill 或 MCP Server`);
+        }
+        printItems(items);
+    });
+}
+/** 把一组 Skill 和 MCP Server 装到 targets，已装的跳过；单个条目失败只记为跳过 */
+export async function installCards(cards, targets, dryRun) {
     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) {
+    for (const card of cards.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 });
@@ -53,7 +66,7 @@ export async function sync(targets, dryRun) {
             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) {
+    for (const card of cards.mcp) {
         try {
             const server = await fetchMcp(card.id);
             if (dryRun) {
@@ -73,14 +86,14 @@ export async function sync(targets, dryRun) {
                 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}`));
-        }
-    });
+    return items;
+}
+/** 按「已安装 / 已存在 / 跳过 / 待安装」逐行打印 installCards 的结果 */
+export function printItems(items) {
+    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

@@ -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.2.1",
+  "version": "0.4.0",
   "description": "funcoding.ai 的命令行：给 AI 编程智能体用，查找和安装 Agent Skills、配置 MCP Server、同步收藏、查看 AI 热点和中文文档",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "skill"
   ],
   "scripts": {
-    "build": "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"
   },