qiaoya-community-cli 1.1.11

package/README.md

@@ -0,0 +1,159 @@
+# qiaoya-cli
+
+敲鸭社区 Go 版 agent skill 安装器与公开信息 runtime。
+
+目标体验：
+
+```bash
+# 推荐：已安装 Node.js / npm
+npx qiaoya-community-cli@latest install
+```
+
+```bash
+# macOS / Linux，无需 Node.js
+curl -fsSL https://code.xhyovo.cn/install | sh
+```
+
+```powershell
+# Windows PowerShell，无需 Node.js
+irm https://code.xhyovo.cn/install.ps1 | iex
+```
+
+用户执行一行命令后，安装器会把敲鸭社区能力写入常用 AI agent 的 skill/rules 目录。之后用户直接在 Codex、Claude Code、Cursor、Windsurf、OpenClaw 里对话即可了解社区。
+
+## 主链路
+
+`qiaoya` 是一个单文件 Go binary，同时负责：
+
+- 安装 skill/rules：`qiaoya install`
+- 自检：`qiaoya doctor`
+- 卸载：`qiaoya uninstall`
+- 提示更新：`qiaoya update`
+- 浏览器授权登录：`qiaoya auth login`
+- 查询公开信息：`qiaoya --json public overview`
+- 查询课程：`qiaoya --json public courses`
+- 查询 AI 日报：`qiaoya --json ai-news today`
+
+推荐入口是 `npx qiaoya-community-cli@latest install`。如果用户没有 Node、npm 或 npx，则使用 macOS/Linux 的 `curl | sh` 或 Windows PowerShell 的 `irm | iex` 零依赖安装脚本。脚本只依赖系统自带 shell、curl 和 SHA256 校验命令。
+
+## 支持的 Agent
+
+默认安装：
+
+```bash
+qiaoya install --agents auto
+```
+
+写入位置：
+
+```text
+Codex        ~/.codex/skills/qiaoya/SKILL.md
+Claude Code  ~/.claude/skills/qiaoya/SKILL.md
+OpenClaw     ~/.openclaw/skills/qiaoya/SKILL.md
+Cursor       <project>/.cursor/rules/qiaoya.mdc
+Windsurf     ~/.codeium/windsurf/memories/global_rules.md
+Windsurf     <project>/.windsurf/rules/qiaoya.md
+```
+
+Cursor 是项目级 rules。Windsurf 会写入全局规则；如果检测到项目目录，也会同时写入工作区规则。若要显式安装项目规则：
+
+```bash
+qiaoya install --agents cursor,windsurf --project-dir /path/to/project
+```
+
+## 安装脚本
+
+推荐：
+
+```bash
+npx qiaoya-community-cli@latest install
+```
+
+macOS / Linux：
+
+```bash
+curl -fsSL https://code.xhyovo.cn/install | sh
+```
+
+Windows PowerShell：
+
+```powershell
+irm https://code.xhyovo.cn/install.ps1 | iex
+```
+
+脚本会：
+
+1. 识别系统和 CPU 架构
+2. 下载对应 `qiaoya-*` 单文件 binary
+3. 下载并校验 `checksums.txt`
+4. 运行 `qiaoya install --agents auto`
+5. 把 runtime 固定安装到 `~/.qiaoya/bin/qiaoya`
+
+`npx` 入口会下载同一组 release binary 和 `checksums.txt`，校验通过后把参数转交给临时 `qiaoya` runtime；实际安装后的 runtime 仍固定在 `~/.qiaoya/bin/qiaoya`。
+
+可选环境变量：
+
+```bash
+QIAOYA_RELEASE_BASE_URL=https://github.com/xhyqaq/qiaoya-cli/releases/latest/download
+QIAOYA_AGENTS=codex,claude,cursor,windsurf,openclaw
+QIAOYA_PROJECT_DIR=/path/to/project
+```
+
+## 登录设计
+
+登录态能力走浏览器授权，不让 AI 或 CLI 直接接触用户密码。
+
+1. CLI 执行 `qiaoya auth login`
+2. CLI 在本机随机打开一个临时 callback 端口，例如 `http://127.0.0.1:<port>/callback`
+3. CLI 生成 `state`、PKCE `code_verifier/code_challenge`
+4. CLI 打开敲鸭现有授权链接，例如 `https://code.xhyovo.cn/api/public/oauth2/authorize?...`
+5. 用户在浏览器里使用已有敲鸭账号登录；如果已经登录，直接进入授权确认页
+6. 用户确认授权后，网站把一次性授权码重定向回本机 callback
+7. CLI 校验 `state`，再用授权码和 `code_verifier` 换取短期、低权限 token，并存到本机安全位置
+
+常用命令：
+
+```bash
+qiaoya auth login
+qiaoya auth status
+qiaoya auth logout
+```
+
+Access Token 默认短期有效，Refresh Token 默认长期有效。CLI 会在登录态命令执行前自动刷新 Access Token；只有 Refresh Token 也失效或被撤销时，用户才需要重新执行 `qiaoya auth login`。
+
+无论哪种方案，skill 都不应该要求邮箱、密码、token 或 Cookie。登录态能力默认按 scope 授权，并对写操作继续要求用户确认。
+
+社区项目已经有 `/oauth2/authorize` 授权页和 `/api/public/oauth2/token` 令牌端点。`qiaoya-cli` 注册为 public OAuth2 client，使用 `client_authentication_method=none + PKCE`，CLI 不内置 `client_secret`。CLI 本机 callback 使用随机端口，因此后端 redirect URI 校验只允许 `127.0.0.1` 或 `localhost` 加固定 path，端口允许变化。
+
+## 开发
+
+```bash
+go test ./...
+go vet ./...
+go build -o /tmp/qiaoya ./cmd/qiaoya
+/tmp/qiaoya --help
+/tmp/qiaoya install --dry-run --agents all --project-dir "$PWD"
+```
+
+## Release
+
+推送 `v*` tag 或手动触发 `.github/workflows/release-binaries.yml` 会构建：
+
+```text
+qiaoya-darwin-arm64
+qiaoya-darwin-amd64
+qiaoya-linux-amd64
+qiaoya-linux-arm64
+qiaoya-windows-amd64.exe
+qiaoya-windows-arm64.exe
+checksums.txt
+```
+
+安装脚本默认从 GitHub Release `latest/download` 下载这些资产。后续如果要使用自有域名或 CDN，只需要让 `https://code.xhyovo.cn/install` 返回 `scripts/install.sh`，并把 release asset 反代或同步到稳定地址。
+
+npm wrapper 从仓库根目录发布：
+
+```bash
+npm test
+npm publish
+```

package/npm/bin/qiaoya-community-cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict";
+
+const { run } = require("../lib/installer");
+
+run(process.argv.slice(2)).catch((error) => {
+  const message = error && error.message ? error.message : String(error);
+  console.error(`qiaoya-community-cli: ${message}`);
+  process.exit(1);
+});

package/npm/lib/installer.js

@@ -0,0 +1,169 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { fileURLToPath } = require("url");
+
+const DEFAULT_RELEASE_BASE_URL = "https://code.xhyovo.cn/downloads/qiaoya/latest";
+
+function assetName(platform = process.platform, arch = process.arch) {
+  let osName;
+  switch (platform) {
+    case "darwin":
+      osName = "darwin";
+      break;
+    case "linux":
+      osName = "linux";
+      break;
+    case "win32":
+      osName = "windows";
+      break;
+    default:
+      throw new Error(`暂不支持当前系统: ${platform}`);
+  }
+
+  let cpu;
+  switch (arch) {
+    case "x64":
+    case "amd64":
+      cpu = "amd64";
+      break;
+    case "arm64":
+    case "aarch64":
+      cpu = "arm64";
+      break;
+    default:
+      throw new Error(`暂不支持当前架构: ${arch}`);
+  }
+
+  const suffix = osName === "windows" ? ".exe" : "";
+  return `qiaoya-${osName}-${cpu}${suffix}`;
+}
+
+function joinURL(base, segment) {
+  return `${String(base).replace(/\/+$/, "")}/${segment}`;
+}
+
+function readLocalFile(url) {
+  return fs.promises.readFile(fileURLToPath(url));
+}
+
+function fetchURL(url, redirects = 0) {
+  const parsed = new URL(url);
+  if (parsed.protocol === "file:") {
+    return readLocalFile(parsed);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(`不支持的下载协议: ${parsed.protocol}`);
+  }
+  if (redirects > 5) {
+    throw new Error(`下载重定向过多: ${url}`);
+  }
+
+  const client = parsed.protocol === "https:" ? https : http;
+  return new Promise((resolve, reject) => {
+    const request = client.get(parsed, (response) => {
+      const statusCode = response.statusCode || 0;
+      const location = response.headers.location;
+      if (statusCode >= 300 && statusCode < 400 && location) {
+        response.resume();
+        const next = new URL(location, parsed).toString();
+        fetchURL(next, redirects + 1).then(resolve, reject);
+        return;
+      }
+      if (statusCode < 200 || statusCode >= 300) {
+        response.resume();
+        reject(new Error(`下载失败 ${url}: HTTP ${statusCode}`));
+        return;
+      }
+      const chunks = [];
+      response.on("data", (chunk) => chunks.push(chunk));
+      response.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+    request.on("error", reject);
+    request.setTimeout(30000, () => {
+      request.destroy(new Error(`下载超时: ${url}`));
+    });
+  });
+}
+
+function expectedChecksum(checksums, name) {
+  for (const rawLine of String(checksums).split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+    const parts = line.split(/\s+/);
+    if (parts.length >= 2 && parts[1] === name) {
+      return parts[0].toLowerCase();
+    }
+  }
+  throw new Error(`checksums.txt 中未找到 ${name}`);
+}
+
+function verifyChecksum(buffer, checksums, name) {
+  const expected = expectedChecksum(checksums, name);
+  const actual = crypto.createHash("sha256").update(buffer).digest("hex");
+  if (actual !== expected) {
+    throw new Error(`SHA256 校验失败: ${name}`);
+  }
+}
+
+async function downloadRuntime(options = {}) {
+  const releaseBaseURL = options.releaseBaseURL || process.env.QIAOYA_RELEASE_BASE_URL || DEFAULT_RELEASE_BASE_URL;
+  const name = options.assetName || assetName(options.platform, options.arch);
+  const [binary, checksums] = await Promise.all([
+    fetchURL(joinURL(releaseBaseURL, name)),
+    fetchURL(joinURL(releaseBaseURL, "checksums.txt")),
+  ]);
+  verifyChecksum(binary, checksums.toString("utf8"), name);
+  return { name, binary };
+}
+
+async function prepareRuntime(options = {}) {
+  const runtime = await downloadRuntime(options);
+  const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "qiaoya-npx-"));
+  const binaryPath = path.join(tempDir, process.platform === "win32" ? "qiaoya.exe" : "qiaoya");
+  await fs.promises.writeFile(binaryPath, runtime.binary, { mode: 0o755 });
+  if (process.platform !== "win32") {
+    await fs.promises.chmod(binaryPath, 0o755);
+  }
+  return { binaryPath, tempDir, assetName: runtime.name };
+}
+
+function cleanup(tempDir) {
+  if (!tempDir) {
+    return;
+  }
+  fs.rmSync(tempDir, { recursive: true, force: true });
+}
+
+async function run(args) {
+  const { binaryPath, tempDir, assetName: name } = await prepareRuntime();
+  try {
+    console.error(`下载 qiaoya: ${name}`);
+    const result = spawnSync(binaryPath, args, { stdio: "inherit" });
+    if (result.error) {
+      throw result.error;
+    }
+    process.exitCode = typeof result.status === "number" ? result.status : 1;
+  } finally {
+    cleanup(tempDir);
+  }
+}
+
+module.exports = {
+  DEFAULT_RELEASE_BASE_URL,
+  assetName,
+  expectedChecksum,
+  fetchURL,
+  joinURL,
+  prepareRuntime,
+  run,
+  verifyChecksum,
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "qiaoya-community-cli",
+  "version": "1.1.11",
+  "description": "Cross-platform npx installer for the Qiaoya Community agent skill runtime.",
+  "bin": {
+    "qiaoya-community-cli": "npm/bin/qiaoya-community-cli.js"
+  },
+  "files": [
+    "npm/bin",
+    "npm/lib",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "npm run test:npm",
+    "test:npm": "node --test npm/test/*.test.js",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "qiaoya",
+    "agent",
+    "skill",
+    "codex",
+    "claude"
+  ],
+  "author": "xhyovo",
+  "license": "MIT",
+  "homepage": "https://code.xhyovo.cn",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xhyqaq/qiaoya-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xhyqaq/qiaoya-cli/issues"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}