aiconductor-cli 1.1.0 → 1.2.0

package/CODEBUDDY.md

@@ -0,0 +1,79 @@
+# CODEBUDDY.md This file provides guidance to CodeBuddy when working with code in this repository.
+
+## Commands
+
+### 本地运行（开发调试）
+
+```bash
+node bin/aiconductor-cli.js --help                              # 查看所有命令
+node bin/aiconductor-cli.js html publish --help                 # 查看某命令选项
+node bin/aiconductor-cli.js search web "关键词" -n 3 -f text    # 运行网页搜索（text 输出）
+node bin/aiconductor-cli.js search image "关键词" -n 2          # 运行图片搜索（JSON 输出）
+```
+
+### 发布到 npm
+
+```bash
+npm version patch|minor|major    # 升版本号（新增功能升 minor，修复升 patch）
+npm pkg fix                      # 修复 package.json 格式问题
+npm publish                      # 发布（如开启 2FA 需加 --otp=<验证码>）
+```
+
+### 验证流程
+
+发布前必须对本轮新增/修改的每个命令执行真实调用，确认 exit code 0 且输出格式正确。用 `node bin/aiconductor-cli.js <command> --help` 检查选项完整性。
+
+## Architecture
+
+### 分层设计
+
+项目采用三层分离架构，每层职责明确：
+
+```
+bin/aiconductor-cli.js          ← 入口层：commander 注册子命令树，不含业务逻辑
+src/api.js                      ← API 层：HTTP 请求封装 + API Key 解析
+src/commands/<topic>.js         ← 命令层：参数组装、调用 API、格式化输出
+```
+
+**`bin/aiconductor-cli.js`** 是纯聚合入口，用 commander 的 `.command().addCommand()` 结构将各 topic 模块注册为子命令树。action 回调只做参数传递，不含业务逻辑。新增命令分类只需在此文件引入并注册。
+
+**`src/api.js`** 是所有外部 API 调用的底层封装：
+- `resolveApiKey(optionKey)` — 三级优先级查找 API Key：`-k` 参数 > `AICONDUCTOR_API_KEY` 环境变量 > 当前目录 `.env` 文件
+- `httpPost(host, path, body, headers)` — 通用 HTTP POST 封装，支持自定义 headers，统一处理 HTTP 错误（`type: "http_error"`）和网络错误（`type: "network_error"`）
+- 每个外部 API 对应一个独立函数（如 `publishHtml`、`webSearch`），函数内过滤 `billing` 字段后返回
+- 新增外部 API 渠道只改此文件
+
+**`src/commands/<topic>.js`** 是命令编排层，每个文件对应一个命令分组：
+- 接收业务参数 + options 对象
+- 调用 `resolveApiKey` 解析 Key（失败则 exit 1）
+- 组装参数调用 `api.js` 中的函数
+- 通过 `outputResult` / `outputError` 统一处理输出
+- 成功 `process.exit(0)`，失败 `process.exit(1)`
+
+### 命令文件命名规则
+
+`src/commands/` 下的文件名与 API 端点名一一对应：
+- `/api/html_publish` → `html_publish.js`
+- `/api/aic_web_search` → `web_search.js`
+
+新增命令时遵循同样规则：文件名 = API 端点名（snake_case）。
+
+### 输出格式约定
+
+所有命令支持 `-f json|text` 两种输出格式：
+- **JSON（默认）**：成功输出 `{ success: true, data: {...} }`，失败输出 `{ success: false, error: "..." }`，便于 AI Agent 解析
+- **text**：人类可读格式，成功以 `✓` 开头，失败以 `✗` 开头
+
+### API Key 鉴权
+
+不同 API 使用不同鉴权方式：
+- `html_publish`：api_key 放入请求 body
+- `aic_web_search`：使用 `Authorization: Bearer <api_key>` 请求头
+
+### 计费信息过滤
+
+所有 API 函数在返回前通过解构 `const { billing, ...safe } = resp` 过滤掉计费字段，不暴露给终端用户。
+
+### Skills
+
+`.codebuddy/skills/` 下存放 CodeBuddy Skill 文档（SKILL.md），描述 CLI 命令的使用方法供 AI Agent 调用。每个 Skill 对应一个 CLI 命令分组，目录名使用 kebab-case。此目录已被 `.npmignore` 排除，不会发布到 npm。

package/README.md

@@ -0,0 +1,108 @@
+# AIConductor CLI
+
+AIConductor 平台命令行工具箱，提供 HTML 发布和网页/图片搜索功能。
+
+## 安装
+
+```bash
+npm install -g aiconductor-cli
+```
+
+**Node.js >= 16.0.0** 环境。
+
+## 配置 API Key
+
+前往 [https://dev.aiconductor.fun/register](https://dev.aiconductor.fun/register) 注册获取 API Key，然后配置环境变量：
+
+**macOS / Linux：**
+```bash
+echo 'export AICONDUCTOR_API_KEY="your-api-key"' >> ~/.zshrc && source ~/.zshrc
+```
+
+**Windows PowerShell：**
+```powershell
+[Environment]::SetEnvironmentVariable("AICONDUCTOR_API_KEY", "your-api-key", "User")
+```
+
+> 也可在项目目录创建 `.env` 文件写入 `AICONDUCTOR_API_KEY=your-api-key`。
+
+## 命令
+
+### 发布 HTML 网页
+
+```bash
+aiconductor-cli html publish <HTML代码或文件路径> -t <英文文件名>
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-t, --title` | 英文文件名（必填，小写+连字符） |
+| `-k, --api-key` | API Key（可选，默认读取环境变量） |
+| `-f, --format` | 输出格式：`json`（默认）或 `text` |
+
+示例：
+```bash
+aiconductor-cli html publish index.html -t my-page
+aiconductor-cli html publish "<h1>Hello</h1>" -t hello-page -f text
+```
+
+### 网页搜索
+
+```bash
+aiconductor-cli search web <关键词> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-n, --count` | 返回条数（最多50） | 5 |
+| `--time-range` | 时间范围：`OneDay`/`OneWeek`/`OneMonth`/`OneYear` | 无 |
+| `--no-summary` | 不返回内容摘要 | 默认返回 |
+| `--content-format` | 内容格式：`Text`/`Markdown` | Text |
+| `--auth-level` | 权威过滤：0=不过滤，1=优先权威来源 | 0 |
+| `--query-rewrite` | 开启 Query 改写 | 关闭 |
+
+示例：
+```bash
+aiconductor-cli search web "北京今日天气" -n 3 --auth-level 1
+```
+
+### 图片搜索
+
+```bash
+aiconductor-cli search image <关键词> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-n, --count` | 返回条数（最多5） | 5 |
+| `--time-range` | 时间范围 | 无 |
+
+示例：
+```bash
+aiconductor-cli search image "长城风景" -n 3 -f text
+```
+
+### 通用选项
+
+所有命令支持：
+- `-k, --api-key <key>` — API Key（优先级：参数 > 环境变量 > .env 文件）
+- `-f, --format <json|text>` — 输出格式，默认 JSON
+
+## 计费
+
+- HTML 发布：0.01 元/次
+- 网页/图片搜索：0.03 元/次
+- 搜索失败不扣费，仅成功时计费
+
+## 开发
+
+```bash
+git clone https://github.com/huyi9531/aiconductor-cli.git
+cd aiconductor-cli
+npm install
+node bin/aiconductor-cli.js --help    # 本地运行
+```
+
+## License
+
+MIT

package/bin/aiconductor-cli.js

@@ -2,6 +2,7 @@
 
 const { Command } = require("commander");
 const { publishCommand } = require("../src/commands/html_publish");
+const { publishCommand: webpagePublishCommand } = require("../src/commands/md_publish");
 const { searchCommand } = require("../src/commands/web_search");
 
 const program = new Command();
@@ -27,6 +28,24 @@ htmlCmd
     publishCommand(html, options);
   });
 
+// webpage 子命令组（统一发布 Markdown/HTML 为在线网页）
+const webpageCmd = program
+  .command("webpage")
+  .description("网页发布（支持 Markdown 和 HTML）");
+
+webpageCmd
+  .command("publish")
+  .description("将 Markdown 或 HTML 发布为在线网页（自动识别类型）")
+  .argument("<input>", "Markdown/HTML 文本字符串或文件路径")
+  .option("-k, --api-key <key>", "AIConductor API Key（也可通过 AICONDUCTOR_API_KEY 环境变量或 .env 文件提供）")
+  .option("-t, --title <title>", "文件名（不含 .html 后缀）")
+  .option("--type <type>", "强制指定类型：md 或 html（默认自动识别）")
+  .option("--copy-button", "添加代码复制按钮（仅 Markdown 类型生效）")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .action((input, options) => {
+    webpagePublishCommand(input, options);
+  });
+
 // search 子命令组
 const searchCmd = program
   .command("search")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiconductor-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "AIConductor CLI 工具箱",
   "keywords": [
     "aiconductor",

package/src/api.js

@@ -4,6 +4,7 @@ const path = require("path");
 
 const API_HOST = "plugin.aiconductor.fun";
 const API_PATH = "/api/html_publish";
+const MD_TO_HTML_API_PATH = "/api/md_to_html";
 const SEARCH_API_PATH = "/api/aic_web_search";
 
 /**
@@ -137,4 +138,26 @@ async function webSearch(apiKey, params) {
   return safe;
 }
 
-module.exports = { resolveApiKey, publishHtml, webSearch };
+/**
+ * Markdown 转 HTML 并发布
+ * @param {string} apiKey
+ * @param {string} mdText
+ * @param {string} [filename]
+ * @param {boolean} [addCopyButton=true]
+ * @returns {Promise<{success: boolean, message: string, file_url: string, online_url: string}>}
+ */
+async function publishMdToHtml(apiKey, mdText, filename, addCopyButton = false) {
+  const reqBody = {
+    api_key: apiKey,
+    md_text: mdText,
+    add_copy_button: addCopyButton,
+  };
+  if (filename) reqBody.filename = filename;
+
+  const resp = await httpPost(API_HOST, MD_TO_HTML_API_PATH, reqBody);
+
+  const { billing, ...safe } = resp;
+  return safe;
+}
+
+module.exports = { resolveApiKey, publishHtml, publishMdToHtml, webSearch };

package/src/commands/md_publish.js

@@ -0,0 +1,118 @@
+const fs = require("fs");
+const path = require("path");
+const { resolveApiKey, publishHtml, publishMdToHtml } = require("../api");
+
+/**
+ * 解析输入内容：如果是已存在的文件路径则读取，否则当作原始字符串
+ * @param {string} input
+ * @returns {{ content: string, filePath: string|null }}
+ */
+function resolveInput(input) {
+  const trimmed = input.trim();
+  try {
+    const filePath = path.resolve(trimmed);
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+      return { content: fs.readFileSync(filePath, "utf-8"), filePath };
+    }
+  } catch (_) {}
+  return { content: trimmed, filePath: null };
+}
+
+/**
+ * 自动检测内容类型：Markdown 或 HTML
+ * @param {string} content
+ * @param {string|null} filePath
+ * @returns {"md"|"html"}
+ */
+function detectType(content, filePath) {
+  // 优先用文件扩展名判断
+  if (filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".md" || ext === ".markdown") return "md";
+    if (ext === ".html" || ext === ".htm") return "html";
+  }
+  // 内容特征判断
+  const trimmed = content.trim();
+  if (trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<head")) {
+    return "html";
+  }
+  if (trimmed.startsWith("<") && /<\w+[^>]*>/.test(trimmed.substring(0, 200))) {
+    return "html";
+  }
+  // 默认 Markdown
+  return "md";
+}
+
+function outputResult(data, format) {
+  if (format === "json") {
+    process.stdout.write(JSON.stringify({ success: true, data }, null, 2) + "\n");
+  } else {
+    process.stdout.write(`✓ 发布成功\n`);
+    process.stdout.write(`  URL: ${data.online_url}\n`);
+    if (data.message) {
+      process.stdout.write(`  信息: ${data.message}\n`);
+    }
+  }
+}
+
+function outputError(err, format) {
+  if (format === "json") {
+    process.stderr.write(JSON.stringify({ success: false, error: err.message || String(err) }, null, 2) + "\n");
+  } else {
+    process.stderr.write(`✗ 错误: ${err.message || err}\n`);
+  }
+}
+
+/**
+ * webpage publish 命令 — 统一发布 Markdown 或 HTML 为在线网页
+ * @param {string} input - Markdown/HTML 代码或文件路径
+ * @param {{ apiKey?: string, format?: string, title?: string, copyButton?: boolean, type?: string }} options
+ */
+async function publishCommand(input, options = {}) {
+  const format = options.format || "json";
+  const resolvedKey = resolveApiKey(options.apiKey);
+
+  if (!resolvedKey) {
+    outputError(
+      { message: "缺少 API Key。请通过 -k 参数、AICONDUCTOR_API_KEY 环境变量或 .env 文件提供。" },
+      format
+    );
+    process.exit(1);
+  }
+
+  try {
+    const { content, filePath } = resolveInput(input);
+    // 确定类型：--type 显式指定优先，否则自动检测
+    let type = options.type;
+    if (!type) {
+      type = detectType(content, filePath);
+    } else if (type !== "md" && type !== "html") {
+      outputError({ message: `无效的 --type 值: "${type}"，可选: md 或 html` }, format);
+      process.exit(1);
+    }
+
+    let result;
+    if (type === "html") {
+      result = await publishHtml(resolvedKey, content, options.title);
+    } else {
+      const addCopyButton = options.copyButton === true;
+      result = await publishMdToHtml(resolvedKey, content, options.title, addCopyButton);
+    }
+    outputResult(result, format);
+    process.exit(0);
+  } catch (err) {
+    if (err.type === "http_error") {
+      outputError(
+        { message: `API 返回错误 (HTTP ${err.statusCode}): ${err.body?.message || JSON.stringify(err.body)}` },
+        format
+      );
+    } else if (err.type === "network_error") {
+      outputError({ message: `网络错误: ${err.message}` }, format);
+    } else {
+      outputError({ message: `未知错误: ${err.message || err}` }, format);
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = { publishCommand };