npm - funcoding-cli - Versions diffs - 0.2.0 → 0.2.1 - Mend

funcoding-cli 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +40 -25
package/dist/api.js +1 -1
package/dist/auth.js +6 -6
package/dist/cli.js +288 -191
package/dist/content.js +39 -37
package/dist/info.js +40 -0
package/dist/init.js +90 -0
package/dist/install.js +8 -8
package/dist/mcp.js +1 -1
package/dist/setup.js +36 -7
package/dist/sync.js +2 -2
package/package.json +2 -1
package/skill/funcoding/SKILL.md +64 -29

package/README.md CHANGED Viewed

@@ -13,41 +13,56 @@
 把这句话发给你的智能体：
-> 运行 `npx --yes funcoding-cli@latest setup`，然后帮我找一个处理 PDF 的 Skill 并安装。
+> 运行 `npx --yes funcoding-cli@latest init`，然后帮我找一个处理 PDF 的 Skill 并安装。
-`setup` 会给当前智能体装上 funcoding Skill（[skill/funcoding/SKILL.md](skill/funcoding/SKILL.md)）。Skill 里写明了：
+`init` 做两件事：
-- 什么时候用哪条命令
-- 安装前先用 `info` 检查内容，并征得用户同意
-- 缺少 MCP 密钥时向用户索取，不要编造
+1. 没有全局安装时，用 npm 全局安装本工具，之后终端里可以直接用 `funcoding`，或者简写 `fun`。加 `--no-global` 跳过这一步。
+2. 给当前智能体装上 funcoding Skill（[skill/funcoding/SKILL.md](skill/funcoding/SKILL.md)）。Skill 里写明了：
+   - 什么时候用哪条命令
+   - 安装前先用 `skills info` 检查内容，并征得用户同意
+   - 缺少 MCP 密钥时向用户索取，不要编造
-也可以全局安装，之后的命令是 `funcoding`：
+也可以自己全局安装：
 ```bash
 npm i -g funcoding-cli
-funcoding --help
+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`。
 | 命令 | 说明 |
 | --- | --- |
-| `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 版本 |
+| `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 原文，开头附官方来源和核实日期 |
 ## 给智能体的约定
@@ -55,9 +70,9 @@ funcoding --help
   - 成功时为 `{ "ok": true, ... }`
   - 失败时为 `{ "ok": false, "error": { "code", "message", "hint", ... } }`
   - 过程提示一律写到 stderr。
-- **不交互**：需要确认的操作通过参数表达，比如覆盖时加 `--force`，`sync` 可以先加 `--dry-run` 预览。
+- **不交互**：需要确认的操作通过参数表达，比如覆盖时加 `--force`，`favorites 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` 缩小范围。
+- **范围**：`--project` 装到当前项目，不加时装到用户目录。`skills list`、`skills update`、`skills remove`、`mcp list`、`mcp remove` 默认同时查看两处，可以用 `--project` 或 `--user` 缩小范围。
 | 退出码 | 含义 |
 | --- | --- |

package/dist/api.js CHANGED Viewed

@@ -11,7 +11,7 @@ export class ApiError extends CliError {
     status;
     body;
     constructor(message, status, body) {
-        super(codeOf(status), message, status === 401 ? '运行 funcoding login 重新登录' : undefined);
+        super(codeOf(status), message, status === 401 ? '运行 funcoding auth login 重新登录' : undefined);
         this.status = status;
         this.body = body;
     }

package/dist/auth.js CHANGED Viewed

@@ -23,7 +23,7 @@ export async function login(opts) {
     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')}。`));
+            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 }) });
@@ -62,11 +62,11 @@ export async function login(opts) {
             if (e?.error === 'access_denied')
                 fail('auth', '你在浏览器里拒绝了这次登录。');
             if (e?.error === 'expired_token')
-                fail('auth', '验证码过期了。', '重新运行 funcoding login');
+                fail('auth', '验证码过期了。', '重新运行 funcoding auth login');
             throw err;
         }
     }
-    fail('auth', '验证码过期了。', '重新运行 funcoding login');
+    fail('auth', '验证码过期了。', '重新运行 funcoding auth login');
 }
 export async function logout() {
     const c = await loadCredentials(SITE);
@@ -84,13 +84,13 @@ export async function fetchMe(token) {
 export async function requireToken() {
     const c = await loadCredentials(SITE);
     if (!c)
-        return fail('auth', '还没有登录。', '运行 funcoding login');
+        return fail('auth', '还没有登录。', '运行 funcoding auth login');
     return c.token;
 }
-export async function whoami() {
+export async function status() {
     const c = await loadCredentials(SITE);
     if (!c)
-        return fail('auth', '未登录。', '运行 funcoding login');
+        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})`) : ''}`);

package/dist/cli.js CHANGED Viewed

@@ -1,75 +1,71 @@
 #!/usr/bin/env node
-/** funcoding-cli：给 AI 编程智能体用的 funcoding.ai 命令行（人也能用） */
+/**
+ * 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, DEFAULT_AGENT, resolveAgents } from './agents.js';
+import { AGENT_IDS, 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 { 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 { 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
-`;
+/** 帮助和提示里统一写全名；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 list ?? []) {
+    for (const item of Array.isArray(list) ? list : []) {
         const i = item.indexOf('=');
         if (i <= 0)
             fail('usage', `${flag} 要写成 KEY=VALUE：${item}`);
@@ -77,144 +73,245 @@ function pairs(list, flag) {
     }
     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'));
-    // --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);
+    // 先宽松解析一遍，找出命令路径
+    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);
-    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 查看用法');
-    }
+    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'))
-        return reportError(new CliError('usage', err.message, '运行 funcoding --help 查看用法'));
+    // 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)));
 });

package/dist/content.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/** search / news / docs：只读查询网站内容 */
+/** skills find / mcp find / 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) {
@@ -13,15 +13,17 @@ function printCards(title, cards, hrefOf) {
     }
     info('');
 }
-export async function search(query, limit) {
+/** skills find / mcp find */
+export async function find(kind, query, limit) {
+    const cmd = kind === 'skill' ? 'skills' : 'mcp';
     if (!query)
-        fail('usage', '缺少搜索词。', '例如 funcoding search pdf');
+        fail('usage', '缺少关键词。', `例如 funcoding ${cmd} find 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}`);
+    const items = kind === 'skill' ? r.skills : r.mcp;
+    done({ [kind === 'skill' ? 'skills' : 'servers']: items }, () => {
+        if (items.length === 0)
+            return info(`没有找到「${query}」相关的${kind === 'skill' ? ' Skill' : ' MCP Server'}。`);
+        printCards(kind === 'skill' ? 'Skills' : 'MCP Server', items, (c) => `funcoding ${cmd} add ${c.id}`);
     });
 }
 function printStory(s, n) {
@@ -30,33 +32,33 @@ function printStory(s, n) {
         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));
+export async function newsDaily(date) {
+    const day = date || 'latest';
+    if (day !== 'latest' && !/^\d{4}-\d{2}-\d{2}$/.test(day))
+        fail('usage', `日期要写成 YYYY-MM-DD：${day}`);
+    const issue = await api(`/api/cli/news?daily=${day}`);
+    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('头条'));
-            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}`);
+            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)}`);
+        }
+    });
+}
+export async function newsList(limit) {
+    const r = await api(`/api/cli/news?limit=${limit}`);
     done({ updatedAt: r.updatedAt, stories: r.stories }, () => {
         if (r.stories.length === 0)
             return info('暂无热点。');
@@ -66,7 +68,7 @@ export async function news(opts) {
 }
 export async function docsSearch(query, agent, limit) {
     if (!query)
-        fail('usage', '缺少搜索词。', '例如 funcoding docs search hooks --agent claude-code');
+        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 }, () => {
@@ -78,10 +80,10 @@ export async function docsSearch(query, agent, limit) {
                 info(`  ${truncate(d.description, (process.stdout.columns || 100) - 4)}`);
         }
         info('');
-        info(dim(`运行 ${cyan('funcoding docs read <id>')} 阅读全文。`));
+        info(dim(`运行 ${cyan('funcoding docs fetch <id>')} 阅读全文。`));
     });
 }
-export async function docsRead(id) {
+export async function docsFetch(id) {
     const path = id
         .trim()
         .replace(/^https?:\/\/[^/]+/, '')

package/dist/info.js ADDED Viewed

@@ -0,0 +1,40 @@
+/** info：环境信息，只读本机状态，不访问网络 */
+import { AGENT_IDS, AGENTS, currentAgent, installedAgents, skillsRoot } from './agents.js';
+import { SITE, VERSION } from './api.js';
+import { configDir, credentialsPath, loadCredentials } from './credentials.js';
+import { onPath } from './init.js';
+import { bold, dim, done, fail, info } from './ui.js';
+export async function envInfo(field) {
+    const creds = await loadCredentials(SITE);
+    const found = installedAgents();
+    const data = {
+        version: VERSION,
+        site: SITE,
+        node: process.versions.node,
+        /** 是否已全局安装（终端里能直接用 funcoding / fun） */
+        global: onPath('funcoding'),
+        user: creds?.user ?? null,
+        currentAgent: currentAgent(),
+        agents: AGENT_IDS.map((id) => ({ id, installed: found.includes(id), skills: { user: skillsRoot(id, 'user'), project: skillsRoot(id, 'project') } })),
+        configDir: configDir(),
+        credentials: credentialsPath(),
+    };
+    if (field) {
+        if (!(field in data))
+            fail('usage', `没有这一项：${field}`, `可选：${Object.keys(data).join('、')}`);
+        const value = data[field];
+        return done({ [field]: value }, () => info(typeof value === 'object' && value !== null ? JSON.stringify(value, null, 2) : String(value)));
+    }
+    done(data, () => {
+        const row = (k, v) => info(`${bold(k.padEnd(14))}${v}`);
+        row('version', VERSION);
+        row('site', SITE);
+        row('node', process.versions.node);
+        row('global', data.global ? '已全局安装（funcoding / fun）' : '未全局安装，运行 npx --yes funcoding-cli@latest init');
+        row('user', creds?.user ? `${creds.user.name}${creds.user.githubLogin ? ` (@${creds.user.githubLogin})` : ''}` : '未登录');
+        row('currentAgent', data.currentAgent ? AGENTS[data.currentAgent].label : '无');
+        for (const id of AGENT_IDS)
+            row(id, `${found.includes(id) ? '已安装' : dim('未检测到')}  ${dim(skillsRoot(id, 'user'))}`);
+        row('configDir', configDir());
+    });
+}

package/dist/init.js ADDED Viewed

@@ -0,0 +1,90 @@
+/**
+ * init：
+ * 1. 没有全局安装时用 npm 全局安装本 CLI，之后终端里可以直接用 funcoding 或简写 fun（--no-global 跳过）
+ * 2. 把随 CLI 发布的 funcoding Skill（skill/funcoding/SKILL.md）装到智能体，让它知道什么时候、怎么用这个 CLI。
+ *    这个 Skill 不在网站目录里，来源记录标成 builtin，update 时从当前版本的 CLI 重新复制
+ */
+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 { USER_AGENT, VERSION } from './api.js';
+import { META_FILE, moveAway } from './install.js';
+import { cyan, dim, done, fail, green, info, warn } from './ui.js';
+const isWindows = process.platform === 'win32';
+/** PATH 上能不能找到这个命令；npx 运行时会把临时目录加进 PATH，那些目录不算 */
+export function onPath(command, env = process.env) {
+    const exts = isWindows ? ['.cmd', '.exe', ''] : [''];
+    return (env.PATH ?? '')
+        .split(delimiter)
+        .filter((dir) => dir && !/[\\/]_npx[\\/]/.test(dir))
+        .some((dir) => exts.some((ext) => existsSync(join(dir, command + ext))));
+}
+const EACCES_DOC = '权限不足时参考 https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally';
+/** 全局安装当前版本；npm 的输出写到 stderr，不影响 --json 的 stdout */
+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)
+        return { status: 'installed' };
+    return { status: 'failed', hint: `手动运行 npm install -g ${pkg}（${EACCES_DOC}）` };
+}
+/** update：全局安装最新版，再用新版刷新已安装的 funcoding Skill */
+export function selfUpdate() {
+    info(dim('正在用 npm 全局安装 funcoding-cli@latest…'));
+    const r = spawnSync('npm', ['install', '--global', 'funcoding-cli@latest'], { stdio: ['ignore', process.stderr, process.stderr], shell: isWindows });
+    if (r.status !== 0)
+        fail('error', '更新失败。', `手动运行 npm install -g funcoding-cli@latest（${EACCES_DOC}）`);
+    const version = spawnSync('funcoding', ['--version'], { encoding: 'utf8', shell: isWindows }).stdout?.trim() || null;
+    // 让新版本把随包的 funcoding Skill 复制过去；没装过这个 Skill 时会报未找到，忽略
+    spawnSync('funcoding', ['skills', 'update', BUILTIN_ID, '--json'], { stdio: 'ignore', shell: isWindows });
+    done({ from: VERSION, to: version }, () => info(green(version && version !== VERSION ? `✓ 已从 ${VERSION} 更新到 ${version}` : `✓ 已是最新版本 ${version ?? VERSION}`)));
+}
+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) }));
+    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));
+        // 之前 init 装的直接换成新版；同名的其他 Skill 要 --force，并且先备份
+        if (present && !(meta && JSON.parse(meta).builtin))
+            foreign.push(d);
+    }
+    if (foreign.length > 0 && !force)
+        fail('exists', `${foreign.map((d) => d.dir).join('、')} 已存在，且不是 funcoding init 安装的。`, '确认要覆盖就加 --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);
+    }
+    return dirs;
+}
+export async function init(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 })) }, () => {
+        if (cli.status === 'installed')
+            info(green(`✓ 已全局安装 funcoding-cli，在终端里输入 ${cyan('funcoding')} 或 ${cyan('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(' / ')} 主动调用。新开会话后生效。`));
+    });
+}

package/dist/install.js CHANGED Viewed

@@ -10,7 +10,7 @@ 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 { builtinContent, installBuiltin } from './init.js';
 import { bold, CliError, cyan, dim, done, fail, green, info, stars, warn } from './ui.js';
 /** 和服务端一致的上限 */
 const MAX_FILES = 200;
@@ -66,7 +66,7 @@ export async function fetchSkill(spec) {
     }
     catch (err) {
         if (err instanceof CliError && err.code === 'not_found')
-            fail('not_found', `没有找到 Skill：${id}`, `运行 funcoding search <关键词> 查找`);
+            fail('not_found', `没有找到 Skill：${id}`, '运行 funcoding skills find <关键词> 查找');
         throw err;
     }
 }
@@ -160,7 +160,7 @@ function printInstalled(r) {
 }
 export async function install(specs, targets, force) {
     if (specs.length === 0)
-        fail('usage', '缺少要安装的 Skill。', '例如 funcoding install anthropics/skills/pdf');
+        fail('usage', '缺少要安装的 Skill。', '例如 funcoding skills add anthropics/skills/pdf');
     const installed = [];
     for (const spec of specs)
         installed.push(...(await installSkill(await fetchSkill(spec), targets, force)));
@@ -200,7 +200,7 @@ export async function list(sel) {
     const items = await scanAll(sel);
     done({ skills: items }, () => {
         if (items.length === 0)
-            return info(`还没有安装 Skill。可以运行 ${cyan('funcoding search <关键词>')} 查找。`);
+            return info(`还没有安装 Skill。可以运行 ${cyan('funcoding skills find <关键词>')} 查找。`);
         for (const agent of AGENT_IDS) {
             for (const scope of sel.scopes) {
                 const group = items.filter((s) => s.agent === agent && s.scope === scope);
@@ -220,7 +220,7 @@ const matches = (s, name) => !name || s.folder === name || s.source?.id === name
 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');
+        fail('not_found', name ? `没有找到由 funcoding 安装的 ${name}` : '没有由 funcoding 安装的 Skill', '运行 funcoding skills list 查看已安装的 Skill');
     const results = [];
     const cache = new Map();
     for (const s of items) {
@@ -252,19 +252,19 @@ export async function update(name, sel, check) {
         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')} 更新。`));
+            info(dim(`运行 ${cyan('funcoding skills update')} 更新。`));
     });
 }
 // ---------------- remove ----------------
 export async function remove(names, sel, force) {
     if (names.length === 0)
-        fail('usage', '缺少要删除的 Skill。', '运行 funcoding list 查看已安装的 Skill');
+        fail('usage', '缺少要删除的 Skill。', '运行 funcoding skills 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');
+            fail('not_found', `没有找到已安装的 ${name}`, '运行 funcoding skills 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) });

package/dist/mcp.js CHANGED Viewed

@@ -28,7 +28,7 @@ export async function fetchMcp(spec) {
     }
     catch (err) {
         if (err instanceof CliError && err.code === 'not_found')
-            fail('not_found', `没有找到 MCP Server：${id}`, '运行 funcoding search <关键词> 查找');
+            fail('not_found', `没有找到 MCP Server：${id}`, '运行 funcoding mcp find <关键词> 查找');
         throw err;
     }
 }

package/dist/setup.js CHANGED Viewed

@@ -1,14 +1,38 @@
 /**
- * setup：把随 CLI 发布的 funcoding Skill（skill/funcoding/SKILL.md）装到智能体，让它知道什么时候、怎么用这个 CLI。
- * 这个 Skill 不在网站目录里，来源记录标成 builtin，update 时从当前版本的 CLI 重新复制。
+ * setup：
+ * 1. 没有全局安装时用 npm 全局安装本 CLI，之后终端里可以直接用 funcoding 或简写 fun（--no-global 跳过）
+ * 2. 把随 CLI 发布的 funcoding Skill（skill/funcoding/SKILL.md）装到智能体，让它知道什么时候、怎么用这个 CLI。
+ *    这个 Skill 不在网站目录里，来源记录标成 builtin，update 时从当前版本的 CLI 重新复制
  */
+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 { dirname, join } from 'node:path';
+import { delimiter, dirname, join } from 'node:path';
 import { AGENTS, skillsRoot } from './agents.js';
-import { USER_AGENT } from './api.js';
+import { USER_AGENT, VERSION } from './api.js';
 import { META_FILE, moveAway } from './install.js';
-import { cyan, dim, done, fail, green, info } from './ui.js';
+import { cyan, dim, done, fail, green, info, warn } from './ui.js';
+const isWindows = process.platform === 'win32';
+/** PATH 上能不能找到这个命令；npx 运行时会把临时目录加进 PATH，那些目录不算 */
+export function onPath(command, env = process.env) {
+    const exts = isWindows ? ['.cmd', '.exe', ''] : [''];
+    return (env.PATH ?? '')
+        .split(delimiter)
+        .filter((dir) => dir && !/[\\/]_npx[\\/]/.test(dir))
+        .some((dir) => exts.some((ext) => existsSync(join(dir, command + ext))));
+}
+/** 全局安装当前版本；npm 的输出写到 stderr，不影响 --json 的 stdout */
+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)
+        return { status: 'installed' };
+    return { status: 'failed', hint: `手动运行 npm install -g ${pkg}（权限不足时参考 https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally）` };
+}
 export const BUILTIN_ID = 'funcoding';
 const SOURCE = new URL('../skill/funcoding/SKILL.md', import.meta.url);
 export const builtinContent = () => readFile(SOURCE, 'utf8');
@@ -38,9 +62,14 @@ export async function installBuiltin(targets, force) {
     }
     return dirs;
 }
-export async function setup(targets, force) {
+export async function setup(targets, force, global) {
+    const cli = global ? installGlobal() : { status: 'skipped' };
     const dirs = await installBuiltin(targets, force);
-    done({ installed: dirs.map((d) => ({ id: BUILTIN_ID, agent: d.agent, scope: d.scope, dir: d.dir })) }, () => {
+    done({ cli, installed: dirs.map((d) => ({ id: BUILTIN_ID, agent: d.agent, scope: d.scope, dir: d.dir })) }, () => {
+        if (cli.status === 'installed')
+            info(green(`✓ 已全局安装 funcoding-cli，在终端里输入 ${cyan('funcoding')} 或 ${cyan('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 装上」。`);

package/dist/sync.js CHANGED Viewed

@@ -21,9 +21,9 @@ export async function favorites() {
     done({ skills, mcp }, () => {
         if (skills.length + mcp.length === 0)
             return info(`还没有收藏。可以在 ${siteUrl('/skills/')} 收藏 Skill 和 MCP Server。`);
-        printCards('收藏的 Skill', skills, (c) => `funcoding install ${c.id}`);
+        printCards('收藏的 Skill', skills, (c) => `funcoding skills add ${c.id}`);
         printCards('收藏的 MCP Server', mcp, (c) => `funcoding mcp add ${c.id}`);
-        info(dim(`运行 ${cyan('funcoding sync')} 一次安装全部收藏。`));
+        info(dim(`运行 ${cyan('funcoding favorites sync')} 一次安装全部收藏。`));
     });
 }
 export async function sync(targets, dryRun) {

package/package.json CHANGED Viewed

@@ -1,10 +1,11 @@
 {
   "name": "funcoding-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "funcoding.ai 的命令行：给 AI 编程智能体用，查找和安装 Agent Skills、配置 MCP Server、同步收藏、查看 AI 热点和中文文档",
   "type": "module",
   "bin": {
     "funcoding": "dist/cli.js",
+    "fun": "dist/cli.js",
     "funcoding-cli": "dist/cli.js"
   },
   "files": [

package/skill/funcoding/SKILL.md CHANGED Viewed

@@ -1,61 +1,96 @@
 ---
 name: funcoding
-description: 用 funcoding-cli 从 funcoding.ai 查找并安装 Agent Skills 和 MCP Server，管理已安装的 Skill，同步用户在网站上的收藏，查看 AI 热点和日报，搜索和阅读 Claude Code、Codex、Cursor 等智能体的中文文档。当用户想找某类 Skill 或 MCP Server、安装或更新 Skill、配置 MCP、同步收藏、了解 AI 圈最近的新闻，或查阅 AI 编程工具的中文文档时使用。
+description: 用 funcoding 命令行（funcoding-cli）从 funcoding.ai 查找并安装 Agent Skills 和 MCP Server，管理已安装的 Skill，同步用户在网站上的收藏，查看 AI 热点和日报，搜索和阅读 Claude Code、Codex、Cursor 等智能体的中文文档。当用户想找某类 Skill 或 MCP Server、安装或更新 Skill、配置 MCP、同步收藏、了解 AI 圈最近的新闻，或查阅 AI 编程工具的中文文档时使用。
 ---
-# funcoding-cli
+# funcoding
-funcoding-cli 是 funcoding.ai 的命令行工具。运行方式：
+本 Skill 说明如何使用 `funcoding` 命令行（npm 包 `funcoding-cli`，命令可简写为 `fun`）。
+## 安装
+如果 PATH 里找不到 `funcoding` 命令，运行下面的命令安装（需要 Node.js 18.17 及以上）：
 ```bash
-npx --yes funcoding-cli@latest <命令> --json
+npx --yes funcoding-cli@latest init --json
 ```
-已全局安装时（`npm i -g funcoding-cli`）可以直接用 `funcoding <命令>`。需要 Node.js 18.17 及以上。
+`init` 会全局安装本工具，并装上本 Skill。返回结果里 `cli.status` 为 `failed` 时（比如没有权限），把 `cli.hint` 告诉用户；在用户处理好之前，可以用 `npx --yes funcoding-cli@latest <命令>` 临时代替 `funcoding <命令>`。
+`funcoding update` 会把本工具更新到最新版本，并同时更新本 Skill。
 ## 使用约定
 - **始终加 `--json`**：stdout 只输出一个 JSON 对象。成功时是 `{ "ok": true, ... }`，失败时是 `{ "ok": false, "error": { "code", "message", "hint" } }`。过程提示写在 stderr，可以忽略。
 - 出错时先看 `error.hint`，里面通常是下一步该运行的命令或该补的参数。
 - 退出码：0 成功，1 一般错误，2 参数错误或缺少必填项，3 未找到，4 目标已存在（需要 `--force`），5 未登录或登录已过期。
-- `--agent` 指定装给哪个智能体：`claude-code`、`codex`、`cursor`，多个用逗号分隔；`all` 表示本机检测到的全部智能体。不指定时，在 Claude Code 里运行默认装给 Claude Code，其他情况也默认 Claude Code。如果你不是 Claude Code，请显式加上 `--agent`。
+- `--agent=<name>` 指定装给哪个智能体：`claude-code`、`codex`、`cursor`，多个用逗号分隔；`all` 表示本机检测到的全部智能体。不指定时默认装给 Claude Code。**如果你不是 Claude Code，请显式加上 `--agent`。**
 - `--project` 装到当前项目（可以随仓库提交，团队共用）；不加时装到用户目录，对所有项目生效。
+- 不确定某条命令的参数时，运行 `funcoding <命令> --help`，比如 `funcoding skills add --help`。
+- `funcoding info --json` 返回本机环境：已安装的智能体、各自的 Skill 目录、登录状态。
-## 安装 Skill
+## Skill 管理
-1. 查找：`search <关键词>`。结果里的 `skills[].id` 形如 `owner/repo/skill`。
-2. **安装前先检查**：`info <id>` 会返回 SKILL.md 全文（`skill.content`）和文件清单（`skill.files`，`skill.scripts` 是其中的可执行脚本）。用一两句话告诉用户这个 Skill 做什么；如果有执行任意命令、读取或外传密钥和个人数据、修改系统设置等危险操作，要明确指出。**得到用户确认后再安装。**
-3. 安装：`install <id> [--agent ...] [--project]`。目录已存在时会以退出码 4 停下；向用户确认后再加 `--force`，旧版本会备份到配置目录。
+使用 `skills` 命令：
+1. `funcoding skills find <query>`：查找 Skill。结果里的 `skills[].id` 形如 `owner/repo/skill`。
+2. **安装前先检查**：`funcoding skills info <id>` 返回 SKILL.md 全文（`skill.content`）和文件清单（`skill.files`，其中的可执行脚本列在 `skill.scripts`）。用一两句话告诉用户这个 Skill 做什么；如果有执行任意命令、读取或外传密钥和个人数据、修改系统设置等危险操作，要明确指出。**得到用户确认后再安装。**
+3. `funcoding skills add <id>... [--agent=<name>] [--project]`：安装。目录已存在时会以退出码 4 停下；向用户确认后再加 `--force`，旧版本会备份到配置目录。
 4. 告诉用户装到了哪个目录（`installed[].dir`），以及如何调用：Claude Code 和 Cursor 输入 `/<目录名>`，Codex 输入 `$<目录名>`，也可以直接描述任务，让智能体自动选用。新装的 Skill 可能需要新开会话才会加载。
 管理已安装的 Skill：
-- `list`：列出所有智能体在用户目录和当前项目里的 Skill。`source` 不为空的是通过 funcoding 安装的。
-- `update --check`：检查远端 SKILL.md 是否有变化，不安装。`update [名称]`：按原来源重新安装。
-- `remove <名称>`：删除前会先备份。只能删除通过 funcoding 安装的 Skill；删除其他 Skill 需要加 `--force`，务必先征得用户同意。
+- `funcoding skills list`：列出所有智能体在用户目录和当前项目里的 Skill。`source` 不为空的是通过 funcoding 安装的。
+- `funcoding skills update --check`：检查远端 SKILL.md 是否有变化，不安装。`funcoding skills update [<name>]`：按原来源重新安装。
+- `funcoding skills remove <name>...`：删除前会先备份。只能删除通过 funcoding 安装的 Skill；删除其他 Skill 需要加 `--force`，务必先征得用户同意。
+## MCP 配置
-## 配置 MCP Server
+使用 `mcp` 命令：
-1. `search <关键词>` 结果里的 `mcp[].id` 形如 `owner/repo`。
-2. `mcp info <id>`：查看可用的启动方式（`server.launches`），每种方式需要的环境变量（`env`）或请求头（`headers`），以及是否必填。
-3. `mcp add <id> [--agent ...] [--project] [--env KEY=VALUE ...] [--header KEY=VALUE ...] [--via remote|npm|pypi]`。
+1. `funcoding mcp find <query>`：查找 MCP Server。结果里的 `servers[].id` 形如 `owner/repo`。
+2. `funcoding mcp info <id>`：查看可用的启动方式（`server.launches`），每种方式需要的环境变量（`env`）或请求头（`headers`），以及是否必填。
+3. `funcoding mcp add <id> [--agent=<name>] [--project] [--env=KEY=VALUE ...] [--header=KEY=VALUE ...] [--via=remote|npm|pypi]`：
    - 缺少必填项时，会以退出码 2 返回，`error.missing` 列出缺少的项。**向用户索取这些值，不要编造。** 密钥只通过参数传入，不要写进其他文件。
    - 没有登记标准安装包时，会以退出码 3 返回，`error.readme` 是 README 地址。这时按 README 手动配置。
-4. 配置在重启智能体或新开会话后生效。Claude Code 的项目范围 Server 需要用户在 Claude Code 里确认后才会启用。
-5. `mcp list` 列出已配置的 Server，`mcp remove <配置名>` 删除，删除前会备份原文件。
+4. 配置在重启智能体或新开会话后生效。Claude Code 项目范围的 Server 需要用户在 Claude Code 里确认后才会启用。
+5. `funcoding mcp list` 列出已配置的 Server；`funcoding mcp remove <name>...` 删除，删除前会备份原文件。
 ## 收藏
-用户在 funcoding.ai 上收藏的 Skill 和 MCP Server：
+用户在 funcoding.ai 上收藏的 Skill 和 MCP Server，需要先登录：
+- `funcoding auth status`：查看是否已登录。返回退出码 5 表示未登录。
+- `funcoding auth login`：会显示验证码和授权地址（在 stderr 中），并尝试打开浏览器。把地址和验证码告诉用户，请用户在浏览器中确认；命令会一直等到用户确认后才返回。
+- `funcoding favorites list`：列出收藏。
+- `funcoding favorites sync [--agent=<name>] [--project] [--dry-run]`：安装全部收藏，已装的跳过。建议先用 `--dry-run` 给用户看将要安装什么。`items[]` 里 `status` 为 `skipped` 的条目附有原因和提示，通常是 MCP 缺少必填的环境变量。
-- `whoami`：查看是否已登录。返回退出码 5 表示未登录。
-- `login`：会显示验证码和授权地址（在 stderr 中），并尝试打开浏览器。把地址和验证码告诉用户，请用户在浏览器中确认；命令会一直等到用户确认后才返回。
-- `favorites`：列出收藏。
-- `sync [--agent ...] [--project] [--dry-run]`：安装全部收藏，已装的跳过。建议先用 `--dry-run` 给用户看将要安装什么。`items[]` 里 `status` 为 `skipped` 的条目附有原因和提示，通常是 MCP 缺少必填的环境变量。
+## AI 热点
-## 热点与文档
+- `funcoding news list [--limit=<n>]`：当前 AI 热榜（多家来源报道的事件，按热度排序，附中文标题和摘要）。
+- `funcoding news daily [<YYYY-MM-DD>]`：某一天的 AI 日报，不写日期时为最新一期。
-- `news [--limit N]`：当前 AI 热榜（多家来源报道的事件，按热度排序，中文标题和摘要）。
-- `news --daily [YYYY-MM-DD]`：某天的 AI 日报，不带日期时为最新一期。
-- `docs search <关键词> [--agent <智能体>]`：搜索中文文档。这里的 `--agent` 可以是站内任意智能体，比如 `claude-code`、`codex`、`cursor`、`gemini-cli`。
-- `docs read <id>`：读取文档全文（Markdown），开头附官方来源链接和核实日期。命令、配置和价格以官方文档为准。
+## 文档
+`docs` 命令用来查阅 AI 编程智能体的中文文档。这些文档按官方文档的章节结构整理，并标注了官方来源和核实日期。
+- `funcoding docs search <query> [--agent=<slug>]`：搜索文档。这里的 `--agent` 可以是站内任意智能体，比如 `claude-code`、`codex`、`cursor`、`gemini-cli`。
+- `funcoding docs fetch <agent>/<path>`：读取文档全文（Markdown），开头附官方来源链接和核实日期。命令、配置和价格以官方文档为准。
+## `funcoding help` 输出
+```
+Usage: funcoding [-hV] [--json] <command>
+Commands:
+  init       初始化：全局安装本工具（之后可用 funcoding 或 fun），并给智能体装上 funcoding Skill
+  update     把本工具更新到最新版本，并刷新已安装的 funcoding Skill
+  info       环境信息：版本、站点、登录状态、本机的智能体和 Skill 目录、配置目录
+  help       显示帮助
+  skills     查找、安装和管理 Agent Skills（find / info / add / list / update / remove）
+  mcp        查找 MCP Server，并写入各智能体的 MCP 配置（find / info / add / list / remove）
+  favorites  网站上收藏的 Skill 和 MCP Server（list / sync）
+  auth       登录 funcoding.ai（login / logout / status）
+  news       AI 热点（list / daily）
+  docs       AI 编程智能体的中文文档（search / fetch）
+```