funcoding-cli 0.0.0-stage → 0.2.0

package/dist/content.js

@@ -0,0 +1,98 @@
+/** search / 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('');
+}
+export async function search(query, limit) {
+    if (!query)
+        fail('usage', '缺少搜索词。', '例如 funcoding search pdf');
+    const r = await api(`/api/cli/search?q=${encodeURIComponent(query)}&limit=${limit}`);
+    done({ skills: r.skills, mcp: r.mcp }, () => {
+        if (r.skills.length + r.mcp.length === 0)
+            return info(`没有找到「${query}」相关的 Skill 或 MCP Server。`);
+        printCards('Skills', r.skills, (c) => `funcoding install ${c.id}`);
+        printCards('MCP Server', r.mcp, (c) => `funcoding mcp 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 news(opts) {
+    if (opts.daily !== undefined) {
+        const day = opts.daily || 'latest';
+        if (day !== 'latest' && !/^\d{4}-\d{2}-\d{2}$/.test(day))
+            fail('usage', '日期要写成 YYYY-MM-DD。');
+        const issue = await api(`/api/cli/news?daily=${day}`);
+        return 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)}`);
+            }
+        });
+    }
+    const r = await api(`/api/cli/news?limit=${opts.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 read <id>')} 阅读全文。`));
+    });
+}
+export async function docsRead(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/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 './setup.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 search <关键词> 查找`);
+        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 install 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 search <关键词>')} 查找。`);
+        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 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 update')} 更新。`));
+    });
+}
+// ---------------- remove ----------------
+export async function remove(names, sel, force) {
+    if (names.length === 0)
+        fail('usage', '缺少要删除的 Skill。', '运行 funcoding 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 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}）`)}`);
+    });
+}

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 search <关键词> 查找');
+        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}`) : ''}`);
+    });
+}