funcoding-cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# funcoding-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[funcoding.ai](https://funcoding.ai) 的命令行工具，主要给 Claude Code、Codex、Cursor 等 AI 编程智能体使用。智能体可以用它：
+
+- 查找和安装 Agent Skills
+- 配置 MCP Server
+- 同步用户在网站上的收藏
+- 查看 AI 热点，搜索和阅读中文文档
+
+人也可以直接使用。需要 Node.js 18.17 及以上。
+
+## 让智能体用起来
+
+把这句话发给你的智能体：
+
+> 运行 `npx --yes funcoding-cli@latest setup`，然后帮我找一个处理 PDF 的 Skill 并安装。
+
+`setup` 会给当前智能体装上 funcoding Skill（[skill/funcoding/SKILL.md](skill/funcoding/SKILL.md)）。Skill 里写明了：
+
+- 什么时候用哪条命令
+- 安装前先用 `info` 检查内容，并征得用户同意
+- 缺少 MCP 密钥时向用户索取，不要编造
+
+也可以全局安装，之后的命令是 `funcoding`：
+
+```bash
+npm i -g funcoding-cli
+funcoding --help
+```
+
+## 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `search <关键词>` | 搜索 Skill 和 MCP Server |
+| `info <owner/repo/skill>` | 查看 Skill 的描述、文件清单和 SKILL.md 全文 |
+| `install <id…>` | 安装一个或多个 Skill，也可以粘贴网站上的详情页地址 |
+| `list` | 列出已安装的 Skill：默认列出全部智能体，包括用户目录和当前项目 |
+| `update [名称] [--check]` | 按原来源重新安装；`--check` 只比较远端的 SKILL.md，不安装 |
+| `remove <名称…>` | 删除通过 funcoding 安装的 Skill，删除前先备份；删除其他来源的 Skill 需要 `--force` |
+| `mcp info <owner/repo>` | 查看启动方式（远程地址、npm 或 PyPI 包），以及需要的环境变量或请求头 |
+| `mcp add <owner/repo>` | 写入智能体的 MCP 配置；必填项用 `--env KEY=VALUE` 或 `--header KEY=VALUE` 提供，`--via remote\|npm\|pypi` 指定启动方式 |
+| `mcp list` / `mcp remove <配置名…>` | 列出或删除 MCP 配置，修改前备份原文件 |
+| `login` / `logout` / `whoami` | 在浏览器中授权登录（设备码）、退出登录并使登录凭证失效、查看当前账号 |
+| `favorites` | 列出网站上收藏的 Skill 和 MCP Server |
+| `sync [--dry-run]` | 安装全部收藏，已安装的跳过；需要密钥的 MCP 会列出缺少哪些值 |
+| `news [--daily [YYYY-MM-DD]]` | 查看 AI 热榜，或某一天的 AI 日报 |
+| `docs search <关键词> [--agent <智能体>]` | 搜索中文文档 |
+| `docs read <智能体/路径>` | 读取文档的 Markdown 原文，开头附官方来源和核实日期 |
+| `setup` | 给智能体装上 funcoding Skill；`update` 时会一起更新到当前 CLI 版本 |
+
+## 给智能体的约定
+
+- **`--json`**：stdout 只输出一个 JSON 对象。
+  - 成功时为 `{ "ok": true, ... }`
+  - 失败时为 `{ "ok": false, "error": { "code", "message", "hint", ... } }`
+  - 过程提示一律写到 stderr。
+- **不交互**：需要确认的操作通过参数表达，比如覆盖时加 `--force`，`sync` 可以先加 `--dry-run` 预览。
+- **`--agent`**：可选 `claude-code`、`codex`、`cursor`，多个用逗号分隔。`all` 表示本机检测到的全部智能体，检测方法是看用户目录下有没有对应的配置目录。不指定时，在 Claude Code 中运行（`CLAUDECODE=1`）默认装给 Claude Code，其他情况也默认 Claude Code。Codex 和 Cursor 没有文档化的环境变量，CLI 不去猜，需要显式指定。
+- **范围**：`--project` 装到当前项目，不加时装到用户目录。`list`、`update`、`remove`、`mcp list`、`mcp remove` 默认同时查看两处，可以用 `--project` 或 `--user` 缩小范围。
+
+| 退出码 | 含义 |
+| --- | --- |
+| 0 | 成功 |
+| 1 | 一般错误 |
+| 2 | 参数错误，或缺少必填项（`error.missing`） |
+| 3 | 未找到（MCP 没有标准安装包时，`error.readme` 给出 README 地址） |
+| 4 | 目标已存在，需要 `--force` |
+| 5 | 未登录或登录已过期 |
+
+## 安装位置
+
+| `--agent` | Skill（用户目录 / 项目） | MCP（用户 / 项目） |
+| --- | --- | --- |
+| `claude-code` | `~/.claude/skills/<name>/` / `.claude/skills/<name>/` | 调用 `claude mcp add-json --scope user\|project`；本机没有 `claude` 命令时，项目范围直接写 `.mcp.json` |
+| `codex` | `~/.agents/skills/<name>/` / `.agents/skills/<name>/` | `$CODEX_HOME/config.toml`（默认 `~/.codex/config.toml`）/ `.codex/config.toml`；不支持 SSE |
+| `cursor` | `~/.cursor/skills/<name>/` / `.cursor/skills/<name>/` | `~/.cursor/mcp.json` / `.cursor/mcp.json` |
+
+以上位置取自各智能体的官方文档（2026-10-07 核实），以官方为准。
+
+## 安全
+
+- Skill 会按 SKILL.md 的指示执行操作，可能运行其中的脚本，安装前请先阅读。
+- CLI 只从 GitHub 下载 Skill 所在目录的文件，拒绝任何跳出目标目录的路径。单个 Skill 最多 200 个文件、10 MB。
+- 改写 MCP 配置时只改动对应的那一项，其他内容原样保留。
+- 覆盖、删除 Skill 和修改 MCP 配置前，都会把原内容备份到配置目录的 `backups/` 下。
+
+登录凭证保存在 `~/.config/funcoding/credentials.json`（设置了 `XDG_CONFIG_HOME` 时放在它下面；Windows 是 `%APPDATA%\funcoding`），文件权限为 600。
+
+环境变量：
+
+- `FUNCODING_URL`：更换站点地址，本地开发时用 `http://localhost:5173`
+- `FUNCODING_CONFIG_DIR`：更换配置目录

package/dist/agents.js

@@ -0,0 +1,55 @@
+/**
+ * 各智能体的 Skill 目录和 MCP 配置位置（对照官方文档核实，2026-10-07），Skill 目录和网站的 src/lib/agent-targets.ts 是同一份表：
+ * - Claude Code：Skill 在 ~/.claude/skills/<name>/、项目 .claude/skills/<name>/（code.claude.com/docs/en/skills）；
+ *   MCP 用 `claude mcp add-json <name> <json> --scope user|project`，项目范围写在 .mcp.json（code.claude.com/docs/en/mcp）
+ * - Codex：Skill 在 ~/.agents/skills/、项目 .agents/skills/（developers.openai.com/codex/skills）；
+ *   MCP 写在 $CODEX_HOME/config.toml（默认 ~/.codex/config.toml）或项目 .codex/config.toml 的 [mcp_servers.<name>]，
+ *   支持 stdio 和 Streamable HTTP，不支持 SSE（developers.openai.com/codex/mcp）
+ * - Cursor：Skill 在 ~/.cursor/skills/、项目 .cursor/skills/（cursor.com/docs/skills）；
+ *   MCP 写在 ~/.cursor/mcp.json 或项目 .cursor/mcp.json 的 mcpServers（cursor.com/docs/mcp）
+ * 运行环境识别：只有 Claude Code 文档写明会给子进程设置 CLAUDECODE=1；Codex、Cursor 没有文档化的变量，不猜。
+ */
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+export const AGENTS = {
+    'claude-code': { label: 'Claude Code', home: '.claude', skills: ['.claude', 'skills'], invoke: (n) => `/${n}` },
+    codex: { label: 'Codex', home: '.codex', skills: ['.agents', 'skills'], invoke: (n) => `$${n}` },
+    cursor: { label: 'Cursor', home: '.cursor', skills: ['.cursor', 'skills'], invoke: (n) => `/${n}` },
+};
+export const AGENT_IDS = Object.keys(AGENTS);
+export const DEFAULT_AGENT = 'claude-code';
+export function isAgentId(s) {
+    return s in AGENTS;
+}
+/** 当前运行在哪个智能体里（只认文档化的环境变量） */
+export function currentAgent({ env = process.env } = {}) {
+    return env.CLAUDECODE === '1' ? 'claude-code' : null;
+}
+/** Codex 的配置目录：CODEX_HOME，默认 ~/.codex */
+export const codexHome = ({ env = process.env, home = homedir() } = {}) => env.CODEX_HOME || join(home, '.codex');
+/** 本机装了哪些智能体：看用户目录下有没有它们的配置目录 */
+export function installedAgents(e = {}) {
+    const home = e.home ?? homedir();
+    return AGENT_IDS.filter((a) => existsSync(a === 'codex' ? codexHome(e) : join(home, AGENTS[a].home)));
+}
+/**
+ * --agent 的取值：显式指定 > 当前运行的智能体 > Claude Code；`all` 表示本机检测到的全部（一个都没检测到时退回默认）。
+ * 返回 null 表示取值不合法
+ */
+export function resolveAgents(value, e = {}) {
+    if (value === 'all') {
+        const found = installedAgents(e);
+        return found.length > 0 ? found : [currentAgent(e) ?? DEFAULT_AGENT];
+    }
+    if (value) {
+        const ids = value.split(',').map((s) => s.trim());
+        return ids.every(isAgentId) ? [...new Set(ids)] : null;
+    }
+    return [currentAgent(e) ?? DEFAULT_AGENT];
+}
+/** Skill 根目录：project 时是当前目录下的项目目录，否则是用户主目录下的 */
+export function skillsRoot(agent, scope, e = {}) {
+    const dirs = AGENTS[agent].skills;
+    return scope === 'project' ? resolve(e.cwd ?? process.cwd(), ...dirs) : join(e.home ?? homedir(), ...dirs);
+}

package/dist/api.js

@@ -0,0 +1,51 @@
+/** 和 funcoding.ai 通信：地址可以用 FUNCODING_URL 改（本地开发时指向 http://localhost:5173） */
+import { readFileSync } from 'node:fs';
+import { CliError } from './ui.js';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const VERSION = pkg.version;
+export const SITE = (process.env.FUNCODING_URL ?? 'https://funcoding.ai').replace(/\/+$/, '');
+export const USER_AGENT = `funcoding-cli/${VERSION} (node ${process.versions.node}; ${process.platform})`;
+const codeOf = (status) => (status === 401 ? 'auth' : status === 404 ? 'not_found' : status === 400 ? 'usage' : 'error');
+/** 接口出错：按 HTTP 状态映射到 CLI 的错误码，body 留给需要细看的调用方（如设备码登录轮询） */
+export class ApiError extends CliError {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(codeOf(status), message, status === 401 ? '运行 funcoding login 重新登录' : undefined);
+        this.status = status;
+        this.body = body;
+    }
+}
+export async function api(path, init = {}) {
+    const { token, headers, ...rest } = init;
+    let res;
+    try {
+        res = await fetch(`${SITE}${path}`, {
+            ...rest,
+            headers: {
+                'User-Agent': USER_AGENT,
+                Accept: 'application/json',
+                ...(rest.body ? { 'Content-Type': 'application/json' } : {}),
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                ...headers,
+            },
+            signal: rest.signal ?? AbortSignal.timeout(30_000),
+        });
+    }
+    catch (err) {
+        throw new ApiError(`连不上 ${SITE}：${err.message}`, 0);
+    }
+    const text = await res.text();
+    let body = text;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch { }
+    if (!res.ok) {
+        const b = body;
+        throw new ApiError(b?.error_description || b?.message || b?.error || `HTTP ${res.status}`, res.status, body);
+    }
+    return body;
+}
+/** 网站接口返回的完整网址（本地开发时跟随 FUNCODING_URL） */
+export const siteUrl = (path) => new URL(path, `${SITE}/`).href;

package/dist/auth.js

@@ -0,0 +1,99 @@
+/**
+ * 设备码登录（RFC 8628）：CLI 申请验证码 → 用户在浏览器打开 /device/ 确认 → CLI 轮询拿到会话 token。
+ * 服务端是 better-auth 的 device-authorization 插件，client_id 固定为 funcoding-cli。
+ */
+import { spawn } from 'node:child_process';
+import { api, SITE } from './api.js';
+import { clearCredentials, credentialsPath, loadCredentials, saveCredentials } from './credentials.js';
+import { bold, cyan, dim, done, fail, green, info, warn } from './ui.js';
+const CLIENT_ID = 'funcoding-cli';
+const absolute = (u) => new URL(u, SITE).href;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 显示成 ABCD-EFGH，方便核对 */
+const pretty = (code) => (code.length === 8 ? `${code.slice(0, 4)}-${code.slice(4)}` : code);
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+    try {
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => { }).unref();
+    }
+    catch { }
+}
+export async function login(opts) {
+    const existing = await loadCredentials(SITE);
+    if (existing) {
+        const me = await fetchMe(existing.token).catch(() => null);
+        if (me) {
+            return done({ user: me.user, alreadyLoggedIn: true }, () => info(`已经登录：${bold(me.user.name)}${me.user.githubLogin ? dim(` (@${me.user.githubLogin})`) : ''}。要换账号先运行 ${cyan('funcoding logout')}。`));
+        }
+    }
+    const code = await api('/api/auth/device/code', { method: 'POST', body: JSON.stringify({ client_id: CLIENT_ID }) });
+    const url = absolute(code.verification_uri_complete ?? `${code.verification_uri}?user_code=${code.user_code}`);
+    info('');
+    info(`  在浏览器里确认这个验证码：${bold(pretty(code.user_code))}`);
+    info(`  ${cyan(url)}`);
+    info('');
+    if (opts.browser)
+        openBrowser(url);
+    info(dim('等待浏览器里确认…（Ctrl+C 取消）'));
+    let interval = Math.max(code.interval ?? 5, 1) * 1000;
+    const deadline = Date.now() + code.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval);
+        try {
+            const token = await api('/api/auth/device/token', {
+                method: 'POST',
+                body: JSON.stringify({ grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: code.device_code, client_id: CLIENT_ID }),
+            });
+            const me = await fetchMe(token.access_token);
+            await saveCredentials({ token: token.access_token, site: SITE, user: { name: me.user.name, githubLogin: me.user.githubLogin }, savedAt: new Date().toISOString() });
+            return done({ user: me.user, credentials: credentialsPath() }, () => {
+                info(green(`✓ 已登录：${me.user.name}${me.user.githubLogin ? ` (@${me.user.githubLogin})` : ''}`));
+                info(dim(`凭证保存在 ${credentialsPath()}`));
+            });
+        }
+        catch (err) {
+            const e = err.body;
+            if (e?.error === 'authorization_pending')
+                continue;
+            if (e?.error === 'slow_down') {
+                interval += 5000;
+                continue;
+            }
+            if (e?.error === 'access_denied')
+                fail('auth', '你在浏览器里拒绝了这次登录。');
+            if (e?.error === 'expired_token')
+                fail('auth', '验证码过期了。', '重新运行 funcoding login');
+            throw err;
+        }
+    }
+    fail('auth', '验证码过期了。', '重新运行 funcoding login');
+}
+export async function logout() {
+    const c = await loadCredentials(SITE);
+    if (!c)
+        return done({ loggedOut: true, wasLoggedIn: false }, () => info('当前没有登录。'));
+    // 顺便让服务端的会话失效；失败也照样删除本地凭证
+    await api('/api/auth/sign-out', { method: 'POST', token: c.token, body: '{}' }).catch(() => warn('没能通知服务端退出，本地凭证已删除。'));
+    await clearCredentials();
+    done({ loggedOut: true, wasLoggedIn: true }, () => info(green('✓ 已退出登录')));
+}
+export async function fetchMe(token) {
+    return api('/api/cli/me', { token });
+}
+/** 需要登录的命令：没登录直接报错 */
+export async function requireToken() {
+    const c = await loadCredentials(SITE);
+    if (!c)
+        return fail('auth', '还没有登录。', '运行 funcoding login');
+    return c.token;
+}
+export async function whoami() {
+    const c = await loadCredentials(SITE);
+    if (!c)
+        return fail('auth', '未登录。', '运行 funcoding login');
+    const me = await fetchMe(c.token);
+    done({ user: me.user, favorites: { skills: me.favorites.skills.length, mcp: me.favorites.mcp.length }, site: SITE }, () => {
+        info(`${bold(me.user.name)}${me.user.githubLogin ? dim(` (@${me.user.githubLogin})`) : ''}`);
+        info(dim(`${me.favorites.skills.length} 个收藏的 Skill，${me.favorites.mcp.length} 个收藏的 MCP · ${SITE}`));
+    });
+}

package/dist/cli.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/** funcoding-cli：给 AI 编程智能体用的 funcoding.ai 命令行（人也能用） */
+import { parseArgs } from 'node:util';
+import { AGENT_IDS, DEFAULT_AGENT, resolveAgents } from './agents.js';
+import { SITE, VERSION } from './api.js';
+import { login, logout, whoami } from './auth.js';
+import { docsRead, docsSearch, news, search } from './content.js';
+import { install, list, remove, skillInfo, update } from './install.js';
+import { mcpAdd, mcpInfo, mcpList, mcpRemove } from './mcp.js';
+import { setup } from './setup.js';
+import { favorites, sync } from './sync.js';
+import { bold, CliError, dim, fail, info, reportError, setJsonMode } from './ui.js';
+const HELP = `${bold('funcoding')} ${dim(`v${VERSION}`)} — 从 ${SITE} 查找和安装 Agent Skills、MCP Server
+
+${bold('Skill')}
+  search <关键词>              搜索 Skill 和 MCP Server
+  info <owner/repo/skill>      查看 Skill：描述、文件清单和 SKILL.md 全文（安装前检查用）
+  install <id…>                安装 Skill（也可以粘贴网站上的详情页地址）
+  list                         列出已安装的 Skill
+  update [名称] [--check]      按原来源重新安装；--check 只检查有没有更新
+  remove <名称…>               删除由 funcoding 安装的 Skill（先备份）
+
+${bold('MCP')}
+  mcp info <owner/repo>        查看启动方式和需要的环境变量
+  mcp add <owner/repo>         写入智能体的 MCP 配置（--env / --header 提供必填项）
+  mcp list                     列出已配置的 MCP Server
+  mcp remove <配置名…>         删除配置（先备份）
+
+${bold('收藏')}
+  login / logout / whoami      在浏览器中授权登录 / 退出 / 查看当前账号
+  favorites                    列出网站上收藏的 Skill 和 MCP Server
+  sync [--dry-run]             安装全部收藏，已装的跳过
+
+${bold('热点与文档')}
+  news [--daily [日期]]        AI 热榜，或某天的 AI 日报
+  docs search <关键词>         搜索中文文档（--agent 可按智能体筛选）
+  docs read <智能体/路径>      读取文档全文（Markdown）
+
+${bold('其他')}
+  setup                        给智能体装上 funcoding Skill，让它学会使用本工具
+
+${bold('选项')}
+  --json                 只向 stdout 输出一个 JSON 对象（给智能体用）
+  -a, --agent <名称>     ${AGENT_IDS.join(' | ')} | all，多个用逗号分隔（默认：当前所在的智能体，否则 ${DEFAULT_AGENT}）
+  -p, --project          装到当前项目；list / update / remove / mcp list 时只看当前项目
+  -u, --user             list / update / remove / mcp list 时只看用户目录（默认两处都看）
+  -f, --force            目标已存在时覆盖（旧版本先备份）
+  -e, --env KEY=VALUE    mcp add：stdio Server 的环境变量，可重复
+      --header KEY=VALUE mcp add：远程 Server 的请求头，可重复
+      --via <方式>       mcp add：remote | npm | pypi
+      --name <配置名>    mcp add：自定义配置名
+      --dry-run          sync：只列出将要执行的操作
+      --check            update：只检查不安装
+      --daily [日期]     news：日报，YYYY-MM-DD，不写为最新一期
+      --limit <N>        search / news / docs search：返回条数
+      --no-browser       login：不自动打开浏览器
+  -h, --help             显示帮助
+  -v, --version          显示版本
+
+${bold('退出码')}
+  0 成功  1 一般错误  2 参数错误或缺少必填项  3 未找到  4 目标已存在  5 未登录或登录已过期
+
+${bold('例子')}
+  npx funcoding-cli search pdf --json
+  npx funcoding-cli info anthropics/skills/pdf --json
+  npx funcoding-cli install anthropics/skills/pdf --agent codex --project
+  npx funcoding-cli mcp add upstash/context7 --agent all
+`;
+/** KEY=VALUE 列表转成对象 */
+function pairs(list, flag) {
+    const out = {};
+    for (const item of list ?? []) {
+        const i = item.indexOf('=');
+        if (i <= 0)
+            fail('usage', `${flag} 要写成 KEY=VALUE：${item}`);
+        out[item.slice(0, i)] = item.slice(i + 1);
+    }
+    return out;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    // 参数解析出错时也要按 JSON 输出
+    setJsonMode(argv.includes('--json'));
+    // --daily 后面的日期可选：没跟日期时补一个空串，避免把后面的参数当成日期
+    const i = argv.indexOf('--daily');
+    if (i >= 0 && !/^\d{4}-\d{2}-\d{2}$|^latest$/.test(argv[i + 1] ?? ''))
+        argv.splice(i + 1, 0, '');
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            json: { type: 'boolean', default: false },
+            agent: { type: 'string', short: 'a' },
+            project: { type: 'boolean', short: 'p', default: false },
+            user: { type: 'boolean', short: 'u', default: false },
+            force: { type: 'boolean', short: 'f', default: false },
+            env: { type: 'string', short: 'e', multiple: true },
+            header: { type: 'string', multiple: true },
+            via: { type: 'string' },
+            name: { type: 'string' },
+            'dry-run': { type: 'boolean', default: false },
+            check: { type: 'boolean', default: false },
+            daily: { type: 'string' },
+            limit: { type: 'string' },
+            'no-browser': { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+        },
+    });
+    setJsonMode(values.json);
+    if (values.version)
+        return info(VERSION);
+    const [command, ...args] = positionals;
+    if (values.help || !command)
+        return info(HELP);
+    const limit = Math.min(30, Math.max(1, Number(values.limit) || 10));
+    /** 写入类命令的目标：智能体 × 一个范围 */
+    const targets = () => {
+        const agents = resolveAgents(values.agent);
+        if (!agents)
+            return fail('usage', `不认识的智能体：${values.agent}`, `可选：${AGENT_IDS.join('、')}、all`);
+        const scope = values.project ? 'project' : 'user';
+        return agents.map((agent) => ({ agent, scope }));
+    };
+    /** 读取和维护类命令的范围：默认全部智能体、两个范围 */
+    const selection = () => {
+        const agents = values.agent ? resolveAgents(values.agent) : AGENT_IDS;
+        if (!agents)
+            return fail('usage', `不认识的智能体：${values.agent}`, `可选：${AGENT_IDS.join('、')}、all`);
+        const scopes = values.project && !values.user ? ['project'] : values.user && !values.project ? ['user'] : ['user', 'project'];
+        return { agents, scopes };
+    };
+    switch (command) {
+        case 'search':
+        case 's':
+            return search(args.join(' '), limit);
+        case 'info':
+            if (!args[0])
+                fail('usage', '缺少 Skill。', '例如 funcoding info anthropics/skills/pdf');
+            return skillInfo(args[0]);
+        case 'install':
+        case 'add':
+        case 'i':
+            return install(args, targets(), values.force);
+        case 'list':
+        case 'ls':
+            return list(selection());
+        case 'update':
+        case 'up':
+            return update(args[0], selection(), values.check);
+        case 'remove':
+        case 'uninstall':
+        case 'rm':
+            return remove(args, selection(), values.force);
+        case 'mcp': {
+            const [sub, ...rest] = args;
+            if (sub === 'info') {
+                if (!rest[0])
+                    fail('usage', '缺少 MCP Server。', '例如 funcoding mcp info upstash/context7');
+                return mcpInfo(rest[0]);
+            }
+            if (sub === 'add' || sub === 'install') {
+                if (!rest[0])
+                    fail('usage', '缺少 MCP Server。', '例如 funcoding mcp add upstash/context7');
+                if (values.via && !['remote', 'npm', 'pypi'].includes(values.via))
+                    fail('usage', `--via 只能是 remote、npm 或 pypi：${values.via}`);
+                return mcpAdd(rest[0], {
+                    targets: targets(),
+                    env: pairs(values.env, '--env'),
+                    headers: pairs(values.header, '--header'),
+                    via: values.via,
+                    name: values.name,
+                    force: values.force,
+                });
+            }
+            if (sub === 'list' || sub === 'ls')
+                return mcpList(selection());
+            if (sub === 'remove' || sub === 'rm')
+                return mcpRemove(rest, selection());
+            return fail('usage', `不认识的命令：mcp ${sub ?? ''}`.trim(), '可用：mcp info / add / list / remove');
+        }
+        case 'login':
+            return login({ browser: !values['no-browser'] });
+        case 'logout':
+            return logout();
+        case 'whoami':
+            return whoami();
+        case 'favorites':
+        case 'fav':
+            return favorites();
+        case 'sync':
+            return sync(targets(), values['dry-run']);
+        case 'news':
+            return news({ daily: values.daily, limit });
+        case 'docs': {
+            const [sub, ...rest] = args;
+            // 文档的 --agent 是站内任意智能体的 slug，不限于能装 Skill 的三个
+            if (sub === 'search')
+                return docsSearch(rest.join(' '), values.agent?.toLowerCase(), limit);
+            if (sub === 'read') {
+                if (!rest[0])
+                    fail('usage', '缺少文档。', '例如 funcoding docs read claude-code/hooks');
+                return docsRead(rest[0]);
+            }
+            return fail('usage', `不认识的命令：docs ${sub ?? ''}`.trim(), '可用：docs search / read');
+        }
+        case 'setup':
+            return setup(targets(), values.force);
+        default:
+            return fail('usage', `不认识的命令：${command}`, '运行 funcoding --help 查看用法');
+    }
+}
+main().catch((err) => {
+    if (err instanceof CliError)
+        return reportError(err);
+    // parseArgs 的参数错误
+    if (err instanceof TypeError && err.code?.startsWith('ERR_PARSE_ARGS'))
+        return reportError(new CliError('usage', err.message, '运行 funcoding --help 查看用法'));
+    reportError(new CliError('error', err instanceof Error ? err.message : String(err)));
+});

package/dist/config-files.js

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