funcoding-cli 0.0.0-stage → 0.2.0

package/dist/paths.js

@@ -0,0 +1,18 @@
+/** 下载的文件路径来自网络，写盘前必须确认不会跑出目标目录 */
+import { isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+/** 合法的相对路径：不能是绝对路径、不能有 ..、不能有反斜杠和控制字符 */
+export function isSafeRelativePath(p) {
+    if (!p || p.length > 300 || isAbsolute(p) || /[\\\0-\x1f]/.test(p) || /^[a-zA-Z]:/.test(p))
+        return false;
+    return p.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
+/** 把相对路径落到 root 下；越界返回 null */
+export function resolveInside(root, p) {
+    if (!isSafeRelativePath(p))
+        return null;
+    const full = resolve(root, normalize(p));
+    const rel = relative(root, full);
+    return rel && !rel.startsWith('..') && !isAbsolute(rel) && !rel.split(sep).includes('..') ? full : null;
+}
+/** 目录名只允许小写字母、数字和连字符 */
+export const isSafeFolderName = (name) => /^[a-z0-9][a-z0-9-]{0,63}$/.test(name);

package/dist/setup.js

@@ -0,0 +1,49 @@
+/**
+ * setup：把随 CLI 发布的 funcoding Skill（skill/funcoding/SKILL.md）装到智能体，让它知道什么时候、怎么用这个 CLI。
+ * 这个 Skill 不在网站目录里，来源记录标成 builtin，update 时从当前版本的 CLI 重新复制。
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { AGENTS, skillsRoot } from './agents.js';
+import { USER_AGENT } from './api.js';
+import { META_FILE, moveAway } from './install.js';
+import { cyan, dim, done, fail, green, info } from './ui.js';
+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));
+        // 之前 setup 装的直接换成新版；同名的其他 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 setup 安装的。`, '确认要覆盖就加 --force（会先备份到配置目录）');
+    for (const d of dirs) {
+        const tmp = join(dirname(d.dir), `.funcoding-tmp-${randomBytes(4).toString('hex')}`);
+        await mkdir(tmp, { recursive: true });
+        await writeFile(join(tmp, 'SKILL.md'), content);
+        await writeFile(join(tmp, META_FILE), `${JSON.stringify({ id: BUILTIN_ID, name: BUILTIN_ID, builtin: true, installedAt: new Date().toISOString(), cli: USER_AGENT }, null, 2)}\n`);
+        if (foreign.includes(d))
+            await moveAway(d.dir, d.agent, BUILTIN_ID);
+        else
+            await rm(d.dir, { recursive: true, force: true });
+        await rename(tmp, d.dir);
+    }
+    return dirs;
+}
+export async function setup(targets, force) {
+    const dirs = await installBuiltin(targets, force);
+    done({ installed: dirs.map((d) => ({ id: BUILTIN_ID, agent: d.agent, scope: d.scope, dir: d.dir })) }, () => {
+        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/sync.js

@@ -0,0 +1,86 @@
+import { siteUrl } from './api.js';
+import { fetchMe, requireToken } from './auth.js';
+import { fetchSkill, installSkill, scanAll } from './install.js';
+import { addServer, fetchMcp } from './mcp.js';
+import { bold, CliError, cyan, dim, done, green, info, stars, truncate, yellow } from './ui.js';
+function printCards(title, cards, hrefOf) {
+    if (cards.length === 0)
+        return;
+    info(bold(title));
+    for (const c of cards) {
+        info(`  ${cyan(c.id)} ${dim(`★ ${stars(c.stars)}${c.official ? ' · 官方' : ''}`)}`);
+        if (c.description)
+            info(`    ${truncate(c.description, (process.stdout.columns || 100) - 6)}`);
+        info(dim(`    ${hrefOf(c)}`));
+    }
+    info('');
+}
+export async function favorites() {
+    const me = await fetchMe(await requireToken());
+    const { skills, mcp } = me.favorites;
+    done({ skills, mcp }, () => {
+        if (skills.length + mcp.length === 0)
+            return info(`还没有收藏。可以在 ${siteUrl('/skills/')} 收藏 Skill 和 MCP Server。`);
+        printCards('收藏的 Skill', skills, (c) => `funcoding install ${c.id}`);
+        printCards('收藏的 MCP Server', mcp, (c) => `funcoding mcp add ${c.id}`);
+        info(dim(`运行 ${cyan('funcoding sync')} 一次安装全部收藏。`));
+    });
+}
+export async function sync(targets, dryRun) {
+    const me = await fetchMe(await requireToken());
+    const items = [];
+    const agents = [...new Set(targets.map((t) => t.agent))];
+    const scopes = [...new Set(targets.map((t) => t.scope))];
+    const installed = await scanAll({ agents, scopes });
+    for (const card of me.favorites.skills) {
+        const missing = targets.filter((t) => !installed.some((s) => s.agent === t.agent && s.scope === t.scope && s.source?.id === card.id));
+        if (missing.length === 0) {
+            items.push({ kind: 'skill', id: card.id, status: 'present', agents });
+            continue;
+        }
+        if (dryRun) {
+            items.push({ kind: 'skill', id: card.id, status: 'planned', agents: missing.map((t) => t.agent) });
+            continue;
+        }
+        try {
+            // 同名目录可能是手动放的或别的来源，不覆盖
+            await installSkill(await fetchSkill(card.id), missing, false);
+            items.push({ kind: 'skill', id: card.id, status: 'installed', agents: missing.map((t) => t.agent) });
+        }
+        catch (err) {
+            if (!(err instanceof CliError))
+                throw err;
+            items.push({ kind: 'skill', id: card.id, status: 'skipped', agents: missing.map((t) => t.agent), reason: err.message, hint: err.hint });
+        }
+    }
+    for (const card of me.favorites.mcp) {
+        try {
+            const server = await fetchMcp(card.id);
+            if (dryRun) {
+                items.push({ kind: 'mcp', id: card.id, status: 'planned', agents });
+                continue;
+            }
+            await addServer(server, { targets, env: {}, headers: {}, force: false });
+            items.push({ kind: 'mcp', id: card.id, status: 'installed', agents });
+        }
+        catch (err) {
+            if (!(err instanceof CliError))
+                throw err;
+            // 已经配置过的算已装；缺少必填项、没有安装包等记为跳过
+            if (err.code === 'exists')
+                items.push({ kind: 'mcp', id: card.id, status: 'present', agents });
+            else
+                items.push({ kind: 'mcp', id: card.id, status: 'skipped', agents, reason: err.message, hint: err.hint ?? (err.code === 'usage' ? undefined : `funcoding mcp info ${card.id}`) });
+        }
+    }
+    done({ dryRun, items }, () => {
+        if (items.length === 0)
+            return info(`还没有收藏。可以在 ${siteUrl('/skills/')} 收藏 Skill 和 MCP Server。`);
+        const label = { installed: green('新装'), present: dim('已装'), skipped: yellow('跳过'), planned: cyan('将安装') };
+        for (const i of items) {
+            info(`${label[i.status]}  ${i.kind === 'skill' ? 'Skill' : 'MCP'} ${i.id}${i.reason ? dim(`：${i.reason}`) : ''}`);
+            if (i.hint)
+                info(dim(`        ${i.hint}`));
+        }
+    });
+}

package/dist/ui.js

@@ -0,0 +1,65 @@
+/**
+ * 输出层。CLI 主要给智能体用，约定：
+ * - 加 --json 时 stdout 只输出一个 JSON 对象（成功 { ok: true, ... }，失败 { ok: false, error: { code, message, hint } }），
+ *   过程提示一律写到 stderr；不加时是给人看的文字
+ * - 退出码固定（见 EXIT），智能体可以据此决定下一步
+ * - 颜色只在交互终端里用，NO_COLOR 或 --json 时关闭
+ */
+export const EXIT = { ok: 0, error: 1, usage: 2, not_found: 3, exists: 4, auth: 5 };
+export class CliError extends Error {
+    code;
+    /** 下一步可以运行的命令或可以做的事 */
+    hint;
+    details;
+    constructor(code, message, hint, details) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.details = details;
+    }
+}
+let json = false;
+export const setJsonMode = (v) => {
+    json = v;
+};
+export const isJsonMode = () => json;
+const color = () => !json && !!process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (color() ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const bold = wrap('1');
+export const dim = wrap('2');
+export const green = wrap('32');
+export const yellow = wrap('33');
+export const red = wrap('31');
+export const cyan = wrap('36');
+/** 给人看的输出：--json 时改写到 stderr，不污染 stdout 的 JSON */
+export const info = (msg) => (json ? console.error(msg) : console.log(msg));
+export const warn = (msg) => console.error(yellow(`! ${msg}`));
+export function fail(code, message, hint, details) {
+    throw new CliError(code, message, hint, details);
+}
+/** 命令的最终结果：--json 时输出 JSON，否则调用 human 打印文字 */
+export function done(data, human) {
+    if (json)
+        console.log(JSON.stringify({ ok: true, ...data }, null, 2));
+    else
+        human();
+}
+export function reportError(err) {
+    if (json) {
+        console.log(JSON.stringify({ ok: false, error: { code: err.code, message: err.message, ...(err.hint ? { hint: err.hint } : {}), ...(err.details ?? {}) } }, null, 2));
+    }
+    else {
+        console.error(red(`✗ ${err.message}`));
+        if (err.hint)
+            console.error(dim(`  ${err.hint}`));
+    }
+    process.exitCode = EXIT[err.code];
+}
+export function stars(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(n >= 10_000 ? 0 : 1)}k` : String(n);
+}
+/** 截断到终端宽度 */
+export function truncate(s, max = (process.stdout.columns || 100) - 4) {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "funcoding-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "funcoding.ai 的命令行：给 AI 编程智能体用，查找和安装 Agent Skills、配置 MCP Server、同步收藏、查看 AI 热点和中文文档",
+  "type": "module",
+  "bin": {
+    "funcoding": "dist/cli.js",
+    "funcoding-cli": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --experimental-strip-types --no-warnings --test 'src/**/*.test.ts'",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "agent-skills",
+    "mcp",
+    "claude-code",
+    "codex",
+    "cursor",
+    "skills",
+    "cli"
+  ],
+  "homepage": "https://funcoding.ai",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funcodingdev/funcoding_ai.git",
+    "directory": "packages/funcoding-cli"
+  }
+}

package/skill/funcoding/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: funcoding
+description: 用 funcoding-cli 从 funcoding.ai 查找并安装 Agent Skills 和 MCP Server，管理已安装的 Skill，同步用户在网站上的收藏，查看 AI 热点和日报，搜索和阅读 Claude Code、Codex、Cursor 等智能体的中文文档。当用户想找某类 Skill 或 MCP Server、安装或更新 Skill、配置 MCP、同步收藏、了解 AI 圈最近的新闻，或查阅 AI 编程工具的中文文档时使用。
+---
+
+# funcoding-cli
+
+funcoding-cli 是 funcoding.ai 的命令行工具。运行方式：
+
+```bash
+npx --yes funcoding-cli@latest <命令> --json
+```
+
+已全局安装时（`npm i -g funcoding-cli`）可以直接用 `funcoding <命令>`。需要 Node.js 18.17 及以上。
+
+## 使用约定
+
+- **始终加 `--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`。
+- `--project` 装到当前项目（可以随仓库提交，团队共用）；不加时装到用户目录，对所有项目生效。
+
+## 安装 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`，旧版本会备份到配置目录。
+4. 告诉用户装到了哪个目录（`installed[].dir`），以及如何调用：Claude Code 和 Cursor 输入 `/<目录名>`，Codex 输入 `$<目录名>`，也可以直接描述任务，让智能体自动选用。新装的 Skill 可能需要新开会话才会加载。
+
+管理已安装的 Skill：
+
+- `list`：列出所有智能体在用户目录和当前项目里的 Skill。`source` 不为空的是通过 funcoding 安装的。
+- `update --check`：检查远端 SKILL.md 是否有变化，不安装。`update [名称]`：按原来源重新安装。
+- `remove <名称>`：删除前会先备份。只能删除通过 funcoding 安装的 Skill；删除其他 Skill 需要加 `--force`，务必先征得用户同意。
+
+## 配置 MCP Server
+
+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]`。
+   - 缺少必填项时，会以退出码 2 返回，`error.missing` 列出缺少的项。**向用户索取这些值，不要编造。** 密钥只通过参数传入，不要写进其他文件。
+   - 没有登记标准安装包时，会以退出码 3 返回，`error.readme` 是 README 地址。这时按 README 手动配置。
+4. 配置在重启智能体或新开会话后生效。Claude Code 的项目范围 Server 需要用户在 Claude Code 里确认后才会启用。
+5. `mcp list` 列出已配置的 Server，`mcp remove <配置名>` 删除，删除前会备份原文件。
+
+## 收藏
+
+用户在 funcoding.ai 上收藏的 Skill 和 MCP Server：
+
+- `whoami`：查看是否已登录。返回退出码 5 表示未登录。
+- `login`：会显示验证码和授权地址（在 stderr 中），并尝试打开浏览器。把地址和验证码告诉用户，请用户在浏览器中确认；命令会一直等到用户确认后才返回。
+- `favorites`：列出收藏。
+- `sync [--agent ...] [--project] [--dry-run]`：安装全部收藏，已装的跳过。建议先用 `--dry-run` 给用户看将要安装什么。`items[]` 里 `status` 为 `skipped` 的条目附有原因和提示，通常是 MCP 缺少必填的环境变量。
+
+## 热点与文档
+
+- `news [--limit N]`：当前 AI 热榜（多家来源报道的事件，按热度排序，中文标题和摘要）。
+- `news --daily [YYYY-MM-DD]`：某天的 AI 日报，不带日期时为最新一期。
+- `docs search <关键词> [--agent <智能体>]`：搜索中文文档。这里的 `--agent` 可以是站内任意智能体，比如 `claude-code`、`codex`、`cursor`、`gemini-cli`。
+- `docs read <id>`：读取文档全文（Markdown），开头附官方来源链接和核实日期。命令、配置和价格以官方文档为准。