funcoding-cli 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,108 @@
-# 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 init`，然后帮我找一个处理 PDF 的 Skill 并安装。
+
+`init` 做两件事：
+
+1. 没有全局安装时，用 npm 全局安装本工具，之后终端里可以直接用 `funcoding`，或者简写 `fun`。加 `--no-global` 跳过这一步。
+2. 给当前智能体装上 funcoding Skill（[skill/funcoding/SKILL.md](skill/funcoding/SKILL.md)）。Skill 里写明了：
+   - 什么时候用哪条命令
+   - 安装前先用 `skills info` 检查内容，并征得用户同意
+   - 缺少 MCP 密钥时向用户索取，不要编造
+
+也可以自己全局安装：
+
+```bash
+npm i -g funcoding-cli
+fun --help
+```
+
+没有用简写 `fc`：它是 zsh 和 bash 的内建命令（编辑历史命令用），shell 会优先执行内建命令。
+
+## 命令
+
+格式参照 [android CLI](https://github.com/android/skills/blob/main/devtools/android-cli/SKILL.md)：
+
+- 顶层是 `init`、`update`、`info`、`help` 这几条。
+- 其余命令按「名词 动词」分组。
+- 每条命令都可以加 `--help`，查看它的用法、选项和位置参数，比如 `funcoding skills add --help`。
+- 选项可以写成 `--agent=codex`，也可以写成 `--agent codex`。
+
+| 命令 | 说明 |
+| --- | --- |
+| `init` | 全局安装本工具，并给智能体装上 funcoding Skill |
+| `update` | 把本工具更新到最新版本，并刷新已安装的 funcoding Skill |
+| `info [<field>]` | 环境信息：版本、站点、是否全局安装、登录状态、本机的智能体和 Skill 目录、配置目录 |
+| `help [<command>]` | 显示帮助 |
+| `skills find <query>` | 查找 Skill |
+| `skills info <id>` | 查看 Skill 的描述、文件清单和 SKILL.md 全文 |
+| `skills add <id>...` | 安装一个或多个 Skill，也可以粘贴网站上的详情页地址 |
+| `skills list` | 列出已安装的 Skill：默认列出全部智能体，包括用户目录和当前项目 |
+| `skills update [<name>] [--check]` | 按原来源重新安装；`--check` 只比较远端的 SKILL.md，不安装 |
+| `skills remove <name>...` | 删除通过 funcoding 安装的 Skill，删除前先备份；删除其他来源的 Skill 需要 `--force` |
+| `mcp find <query>` | 查找 MCP Server |
+| `mcp info <id>` | 查看启动方式（远程地址、npm 或 PyPI 包），以及需要的环境变量或请求头 |
+| `mcp add <id>` | 写入智能体的 MCP 配置；必填项用 `--env=KEY=VALUE` 或 `--header=KEY=VALUE` 提供，`--via=remote\|npm\|pypi` 指定启动方式 |
+| `mcp list` / `mcp remove <name>...` | 列出或删除 MCP 配置，修改前备份原文件 |
+| `favorites list` | 列出网站上收藏的 Skill 和 MCP Server |
+| `favorites sync [--dry-run]` | 安装全部收藏，已安装的跳过；需要密钥的 MCP 会列出缺少哪些值 |
+| `auth login` / `auth logout` / `auth status` | 在浏览器中授权登录（设备码）、退出登录并使登录凭证失效、查看当前账号 |
+| `news list` / `news daily [<YYYY-MM-DD>]` | AI 热榜，或某一天的 AI 日报 |
+| `docs search <query> [--agent=<slug>]` | 搜索中文文档 |
+| `docs fetch <agent>/<path>` | 读取文档的 Markdown 原文，开头附官方来源和核实日期 |
+
+## 给智能体的约定
+
+- **`--json`**：stdout 只输出一个 JSON 对象。
+  - 成功时为 `{ "ok": true, ... }`
+  - 失败时为 `{ "ok": false, "error": { "code", "message", "hint", ... } }`
+  - 过程提示一律写到 stderr。
+- **不交互**：需要确认的操作通过参数表达，比如覆盖时加 `--force`，`favorites sync` 可以先加 `--dry-run` 预览。
+- **`--agent`**：可选 `claude-code`、`codex`、`cursor`，多个用逗号分隔。`all` 表示本机检测到的全部智能体，检测方法是看用户目录下有没有对应的配置目录。不指定时，在 Claude Code 中运行（`CLAUDECODE=1`）默认装给 Claude Code，其他情况也默认 Claude Code。Codex 和 Cursor 没有文档化的环境变量，CLI 不去猜，需要显式指定。
+- **范围**：`--project` 装到当前项目，不加时装到用户目录。`skills list`、`skills update`、`skills 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 auth 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 auth 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 auth login');
+            throw err;
+        }
+    }
+    fail('auth', '验证码过期了。', '重新运行 funcoding auth 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 auth login');
+    return c.token;
+}
+export async function status() {
+    const c = await loadCredentials(SITE);
+    if (!c)
+        return fail('auth', '未登录。', '运行 funcoding auth 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,317 @@
+#!/usr/bin/env node
+/**
+ * funcoding-cli：给 AI 编程智能体用的 funcoding.ai 命令行（人也能用），命令是 funcoding，简写 fun。
+ * 命令格式参照 android CLI：顶层是 init / update / info / help，其余按「名词 动词」分组（skills add、mcp list…），
+ * 每条命令都有自己的 --help。命令表 COMMANDS 同时用来解析参数和生成帮助
+ */
+import { parseArgs } from 'node:util';
+import { AGENT_IDS, resolveAgents } from './agents.js';
+import { SITE, VERSION } from './api.js';
+import { login, logout, status } from './auth.js';
+import { docsFetch, docsSearch, find, newsDaily, newsList } from './content.js';
+import { envInfo } from './info.js';
+import { init, selfUpdate } from './init.js';
+import { install, list, remove, skillInfo, update } from './install.js';
+import { mcpAdd, mcpInfo, mcpList, mcpRemove } from './mcp.js';
+import { favorites, sync } from './sync.js';
+import { bold, CliError, dim, fail, info, reportError, setJsonMode } from './ui.js';
+/** 帮助和提示里统一写全名；fun 是同一个命令的简写 */
+const BIN = 'funcoding';
+const OPTIONS = {
+    json: { type: 'boolean', flag: '--json', desc: '只向 stdout 输出一个 JSON 对象（给智能体用）' },
+    help: { type: 'boolean', short: 'h', flag: '-h, --help', desc: '显示这条命令的帮助' },
+    version: { type: 'boolean', short: 'V', flag: '-V, --version', desc: '显示版本' },
+    agent: { type: 'string', short: 'a', flag: '-a, --agent=<name>', desc: `目标智能体：${AGENT_IDS.join('、')}，多个用逗号分隔，all 表示本机检测到的全部（默认：当前所在的智能体，否则 claude-code）` },
+    'scope-agent': { type: 'string', short: 'a', flag: '-a, --agent=<name>', desc: `只看这些智能体：${AGENT_IDS.join('、')}，多个用逗号分隔（默认全部）` },
+    'doc-agent': { type: 'string', short: 'a', flag: '-a, --agent=<slug>', desc: '只搜这个智能体的文档，比如 claude-code、codex、gemini-cli' },
+    project: { type: 'boolean', short: 'p', flag: '-p, --project', desc: '装到当前项目（可随仓库提交），不加时装到用户目录' },
+    'only-project': { type: 'boolean', short: 'p', flag: '-p, --project', desc: '只看当前项目' },
+    user: { type: 'boolean', short: 'u', flag: '-u, --user', desc: '只看用户目录（默认用户目录和当前项目都看）' },
+    force: { type: 'boolean', short: 'f', flag: '-f, --force', desc: '目标已存在时覆盖（原内容先备份到配置目录）' },
+    env: { type: 'string', short: 'e', multiple: true, flag: '-e, --env=<KEY=VALUE>', desc: 'stdio Server 的环境变量，可重复' },
+    header: { type: 'string', multiple: true, flag: '--header=<KEY=VALUE>', desc: '远程 Server 的请求头，可重复' },
+    via: { type: 'string', flag: '--via=<kind>', desc: '指定启动方式：remote、npm 或 pypi' },
+    name: { type: 'string', flag: '--name=<name>', desc: '自定义配置名（默认取自 Server 名称）' },
+    'dry-run': { type: 'boolean', flag: '--dry-run', desc: '只列出将要执行的操作' },
+    check: { type: 'boolean', flag: '--check', desc: '只检查远端有没有更新，不安装' },
+    limit: { type: 'string', flag: '--limit=<n>', desc: '返回条数（1–30，默认 10）' },
+    'no-browser': { type: 'boolean', flag: '--no-browser', desc: '不自动打开浏览器' },
+    'no-global': { type: 'boolean', flag: '--no-global', desc: '不全局安装，只装 funcoding Skill' },
+};
+const GLOBAL = ['json', 'help', 'version'];
+const str = (v) => (typeof v === 'string' ? v : undefined);
+const limitOf = (v) => Math.min(30, Math.max(1, Number(str(v.limit)) || 10));
+const need = (args, what, example) => {
+    if (!args[0])
+        fail('usage', `缺少${what}。`, `例如 ${example}`);
+    return args;
+};
+/** 写入类命令的目标：智能体 × 一个范围 */
+function targets(v) {
+    const agents = resolveAgents(str(v.agent));
+    if (!agents)
+        return fail('usage', `不认识的智能体：${str(v.agent)}`, `可选：${AGENT_IDS.join('、')}、all`);
+    const scope = v.project ? 'project' : 'user';
+    return agents.map((agent) => ({ agent, scope }));
+}
+/** 读取和维护类命令的范围：默认全部智能体、两个范围 */
+function selection(v) {
+    const agents = str(v.agent) ? resolveAgents(str(v.agent)) : AGENT_IDS;
+    if (!agents)
+        return fail('usage', `不认识的智能体：${str(v.agent)}`, `可选：${AGENT_IDS.join('、')}、all`);
+    const scopes = v.project && !v.user ? ['project'] : v.user && !v.project ? ['user'] : ['user', 'project'];
+    return { agents, scopes };
+}
+/** KEY=VALUE 列表转成对象 */
+function pairs(list, flag) {
+    const out = {};
+    for (const item of Array.isArray(list) ? 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;
+}
+const COMMANDS = [
+    {
+        name: 'init',
+        summary: '初始化：全局安装本工具（之后可用 funcoding 或 fun），并给智能体装上 funcoding Skill',
+        options: ['agent', 'project', 'force', 'no-global'],
+        examples: ['npx --yes funcoding-cli@latest init', `${BIN} init --agent=all`],
+        run: ({ values: v }) => init(targets(v), !!v.force, !v['no-global']),
+    },
+    {
+        name: 'update',
+        summary: '把本工具更新到最新版本，并刷新已安装的 funcoding Skill',
+        run: () => selfUpdate(),
+    },
+    {
+        name: 'info',
+        summary: '环境信息：版本、站点、登录状态、本机的智能体和 Skill 目录、配置目录',
+        params: [['<field>', '只输出这一项，比如 version、user、agents；不写时输出全部']],
+        run: ({ args }) => envInfo(args[0]),
+    },
+    {
+        name: 'help',
+        summary: '显示帮助',
+        params: [['<command>', '要查看帮助的命令，比如 skills add']],
+    },
+    {
+        name: 'skills',
+        summary: '查找、安装和管理 Agent Skills',
+        commands: [
+            { name: 'find', summary: '按关键词查找 Skill', params: [['<query>', '关键词']], options: ['limit'], run: ({ args, values }) => find('skill', args.join(' '), limitOf(values)) },
+            {
+                name: 'info',
+                summary: '查看 Skill 的描述、文件清单和 SKILL.md 全文（安装前检查用）',
+                params: [['<id>', 'owner/repo/skill，或网站上的详情页地址']],
+                run: ({ args }) => skillInfo(need(args, ' Skill', `${BIN} skills info anthropics/skills/pdf`)[0]),
+            },
+            {
+                name: 'add',
+                summary: '安装一个或多个 Skill',
+                params: [['<id>...', 'owner/repo/skill，或网站上的详情页地址']],
+                options: ['agent', 'project', 'force'],
+                examples: [`${BIN} skills add anthropics/skills/pdf`, `${BIN} skills add anthropics/skills/pdf --agent=codex,cursor --project`],
+                run: ({ args, values: v }) => install(need(args, '要安装的 Skill', `${BIN} skills add anthropics/skills/pdf`), targets(v), !!v.force),
+            },
+            { name: 'list', summary: '列出已安装的 Skill', options: ['scope-agent', 'only-project', 'user'], run: ({ values }) => list(selection(values)) },
+            {
+                name: 'update',
+                summary: '按原来源重新安装由 funcoding 安装的 Skill',
+                params: [['<name>', '目录名或 Skill id；不写时更新全部']],
+                options: ['check', 'scope-agent', 'only-project', 'user'],
+                run: ({ args, values: v }) => update(args[0], selection(v), !!v.check),
+            },
+            {
+                name: 'remove',
+                summary: '删除由 funcoding 安装的 Skill（先备份）',
+                params: [['<name>...', '目录名或 Skill id']],
+                options: ['force', 'scope-agent', 'only-project', 'user'],
+                run: ({ args, values: v }) => remove(need(args, '要删除的 Skill', `${BIN} skills remove pdf`), selection(v), !!v.force),
+            },
+        ],
+    },
+    {
+        name: 'mcp',
+        summary: '查找 MCP Server，并写入各智能体的 MCP 配置',
+        commands: [
+            { name: 'find', summary: '按关键词查找 MCP Server', params: [['<query>', '关键词']], options: ['limit'], run: ({ args, values }) => find('mcp', args.join(' '), limitOf(values)) },
+            {
+                name: 'info',
+                summary: '查看启动方式，以及需要提供的环境变量或请求头',
+                params: [['<id>', 'owner/repo 或 owner/repo/sub，或网站上的详情页地址']],
+                run: ({ args }) => mcpInfo(need(args, ' MCP Server', `${BIN} mcp info github/github-mcp-server`)[0]),
+            },
+            {
+                name: 'add',
+                summary: '把 MCP Server 写入智能体的配置',
+                params: [['<id>', 'owner/repo 或 owner/repo/sub，或网站上的详情页地址']],
+                options: ['agent', 'project', 'force', 'env', 'header', 'via', 'name'],
+                examples: [`${BIN} mcp add vexa-ai/vexa --header=Authorization="Bearer <key>" --agent=cursor`],
+                run: ({ args, values: v }) => {
+                    const via = str(v.via);
+                    if (via && !['remote', 'npm', 'pypi'].includes(via))
+                        fail('usage', `--via 只能是 remote、npm 或 pypi：${via}`);
+                    return mcpAdd(need(args, ' MCP Server', `${BIN} mcp add github/github-mcp-server`)[0], {
+                        targets: targets(v),
+                        env: pairs(v.env, '--env'),
+                        headers: pairs(v.header, '--header'),
+                        via: via,
+                        name: str(v.name),
+                        force: !!v.force,
+                    });
+                },
+            },
+            { name: 'list', summary: '列出已配置的 MCP Server', options: ['scope-agent', 'only-project', 'user'], run: ({ values }) => mcpList(selection(values)) },
+            {
+                name: 'remove',
+                summary: '删除 MCP Server 配置（先备份原文件）',
+                params: [['<name>...', '配置名，见 mcp list']],
+                options: ['scope-agent', 'only-project', 'user'],
+                run: ({ args, values }) => mcpRemove(need(args, '要删除的配置名', `${BIN} mcp remove vexa`), selection(values)),
+            },
+        ],
+    },
+    {
+        name: 'favorites',
+        summary: '网站上收藏的 Skill 和 MCP Server（需要登录）',
+        commands: [
+            { name: 'list', summary: '列出收藏', run: () => favorites() },
+            { name: 'sync', summary: '安装全部收藏，已安装的跳过', options: ['agent', 'project', 'dry-run'], run: ({ values: v }) => sync(targets(v), !!v['dry-run']) },
+        ],
+    },
+    {
+        name: 'auth',
+        summary: '登录 funcoding.ai',
+        commands: [
+            { name: 'login', summary: '在浏览器中授权登录（设备码）', options: ['no-browser'], run: ({ values }) => login({ browser: !values['no-browser'] }) },
+            { name: 'logout', summary: '退出登录，并使登录凭证失效', run: () => logout() },
+            { name: 'status', summary: '查看当前登录的账号', run: () => status() },
+        ],
+    },
+    {
+        name: 'news',
+        summary: 'AI 热点',
+        commands: [
+            { name: 'list', summary: '当前 AI 热榜：多家来源报道的事件，按热度排序', options: ['limit'], run: ({ values }) => newsList(limitOf(values)) },
+            { name: 'daily', summary: '某一天的 AI 日报', params: [['<date>', 'YYYY-MM-DD；不写时为最新一期']], run: ({ args }) => newsDaily(args[0]) },
+        ],
+    },
+    {
+        name: 'docs',
+        summary: 'AI 编程智能体的中文文档',
+        commands: [
+            { name: 'search', summary: '搜索文档', params: [['<query>', '关键词']], options: ['doc-agent', 'limit'], run: ({ args, values }) => docsSearch(args.join(' '), str(values.agent)?.toLowerCase(), limitOf(values)) },
+            {
+                name: 'fetch',
+                summary: '读取文档全文（Markdown），开头附官方来源和核实日期',
+                params: [['<path>', '<智能体>/<路径>，比如 claude-code/build/hooks；也可以是网站上的文档地址']],
+                run: ({ args }) => docsFetch(need(args, '文档路径', `${BIN} docs fetch claude-code/build/hooks`)[0]),
+            },
+        ],
+    },
+];
+// ---------------- 帮助 ----------------
+const pad = (rows, indent = '  ') => {
+    const w = Math.max(...rows.map(([a]) => a.length)) + 2;
+    return rows.map(([a, b]) => `${indent}${a.padEnd(w)}${b}`).join('\n');
+};
+function usageLine(path) {
+    const cmd = path.at(-1);
+    const names = path.map((c) => c.name).join(' ');
+    if (!cmd)
+        return `${BIN} [-hV] [--json] <command>`;
+    if (cmd.commands)
+        return `${BIN} ${names} <command> [options]`;
+    const opts = (cmd.options ?? []).map((k) => `[${OPTIONS[k].flag.split(', ').pop()}]`).join(' ');
+    const params = (cmd.params ?? []).map(([p]) => (cmd.name === 'help' || cmd.name === 'info' || p === '<name>' || p === '<date>' ? `[${p}]` : p)).join(' ');
+    return [BIN, names, opts, params].filter(Boolean).join(' ');
+}
+function helpText(path) {
+    const cmd = path.at(-1);
+    const out = [`${bold('Usage:')} ${usageLine(path)}`];
+    if (!cmd) {
+        out.push(`${dim(`funcoding v${VERSION}`)} — 从 ${SITE} 查找和安装 Agent Skills、配置 MCP Server、查看 AI 热点和中文文档`);
+        out.push(dim('可以简写为 fun，比如 fun skills find pdf；给智能体用时加 --json'));
+    }
+    else
+        out.push(cmd.summary);
+    const options = cmd?.options ?? [];
+    if (options.length)
+        out.push('', bold('Options:'), pad(options.map((k) => [OPTIONS[k].flag, OPTIONS[k].desc])));
+    out.push('', bold(cmd ? 'Global options:' : 'Options:'), pad(GLOBAL.map((k) => [OPTIONS[k].flag, OPTIONS[k].desc])));
+    if (cmd?.params)
+        out.push('', bold('Positional parameters:'), pad(cmd.params));
+    const subs = cmd ? cmd.commands : COMMANDS;
+    if (subs)
+        out.push('', bold('Commands:'), pad(subs.map((c) => [c.name, c.summary])));
+    if (cmd?.examples)
+        out.push('', bold('Examples:'), cmd.examples.map((e) => `  ${e}`).join('\n'));
+    if (!cmd) {
+        out.push('', bold('Exit codes:'), '  0 成功  1 一般错误  2 参数错误或缺少必填项  3 未找到  4 目标已存在  5 未登录或登录已过期');
+        out.push('', `运行 ${BIN} <command> --help 查看每条命令的用法。`);
+    }
+    return out.join('\n');
+}
+/** 从位置参数里找出命令路径，剩下的是这条命令的参数 */
+function resolve(words) {
+    const path = [];
+    let list = COMMANDS;
+    let i = 0;
+    while (list && i < words.length) {
+        const c = list.find((x) => x.name === words[i]);
+        if (!c) {
+            const where = path.map((p) => p.name).join(' ');
+            fail('usage', `不认识的命令：${[where, words[i]].filter(Boolean).join(' ')}`, `运行 ${BIN} ${where ? `${where} ` : ''}--help 查看可用命令`);
+        }
+        path.push(c);
+        list = c.commands;
+        i++;
+    }
+    return { path, rest: words.slice(i) };
+}
+function parserConfig(keys) {
+    const out = {};
+    for (const k of keys) {
+        const { type, ...o } = OPTIONS[k];
+        // scope-agent / doc-agent 等是同一个 --agent 的不同说明
+        const name = k === 'scope-agent' || k === 'doc-agent' ? 'agent' : k === 'only-project' ? 'project' : k;
+        out[name] = { type, ...(o.short ? { short: o.short } : {}), ...(o.multiple ? { multiple: true } : {}) };
+    }
+    return out;
+}
+// ---------------- 入口 ----------------
+async function main() {
+    const argv = process.argv.slice(2);
+    // 参数解析出错时也要按 JSON 输出
+    setJsonMode(argv.includes('--json'));
+    // 先宽松解析一遍，找出命令路径
+    const loose = parseArgs({ args: argv, allowPositionals: true, strict: false, options: parserConfig(Object.keys(OPTIONS)) });
+    const { path, rest } = resolve(loose.positionals);
+    const cmd = path.at(-1);
+    if (cmd?.name === 'help' && path.length === 1)
+        return info(helpText(resolve(rest).path));
+    // 再按这条命令允许的选项严格解析
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: parserConfig([...GLOBAL, ...(cmd?.options ?? [])]) });
+    const values = parsed.values;
+    const positionals = parsed.positionals;
+    if (values.version)
+        return info(VERSION);
+    if (values.help || !cmd?.run)
+        return info(helpText(path));
+    await cmd.run({ args: positionals.slice(path.length), values });
+}
+main().catch((err) => {
+    if (err instanceof CliError)
+        return reportError(err);
+    // parseArgs 的参数错误，比如这条命令不支持的选项
+    if (err instanceof TypeError && err.code?.startsWith('ERR_PARSE_ARGS')) {
+        const unknown = /Unknown option '([^']+)'/.exec(err.message)?.[1];
+        const missing = /Option '([^']+)' argument missing/.exec(err.message)?.[1];
+        const message = unknown ? `这条命令不支持选项 ${unknown}` : missing ? `选项 ${missing.split(', ').pop()?.replace(' <value>', '')} 缺少取值` : err.message;
+        return reportError(new CliError('usage', message, `运行 ${BIN} <command> --help 查看这条命令支持的选项`));
+    }
+    reportError(new CliError('error', err instanceof Error ? err.message : String(err)));
+});