@jiangzhx/adcli 0.1.1 → 0.1.2

package/README.md

@@ -36,12 +36,28 @@ adcli doc search "广告消耗"
 https://adcli.jiangzhx.com/search-index.json
 ```
 
+首次搜索会下载索引并缓存到系统标准缓存目录。也可以手动更新：
+
+```bash
+adcli doc sync
+adcli doc search "广告消耗" --refresh
+```
+
 本地调试可指定索引：
 
 ```bash
 adcli doc search "广告消耗" --index public/search-index.json
 ```
 
+给 AI / Agent 使用文档包：
+
+```bash
+adcli list
+adcli list kuaishou
+adcli llms
+adcli prompt
+```
+
 ## 常用命令
 
 ```bash
@@ -67,7 +83,7 @@ bun run build:search-index
 本地搜索已发布文档：
 
 ```bash
-bun run adcli doc search "广告消耗"
+adcli doc search "广告消耗"
 ```
 
 完整命令清单见 [docs/commands.md](docs/commands.md)。

package/dist/cli.js

@@ -1,9 +1,159 @@
 #!/usr/bin/env node
 // @bun
 
-// src/cli.ts
-import { readFile } from "fs/promises";
-import path from "path";
+// src/lib/search/cache.ts
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path2 from "node:path";
+
+// node_modules/env-paths/index.js
+import path from "node:path";
+import os from "node:os";
+import process2 from "node:process";
+
+// node_modules/is-safe-filename/index.js
+var unsafeFilenameFixtures = Object.freeze([
+  "",
+  "   ",
+  ".",
+  "..",
+  " .",
+  ". ",
+  " ..",
+  ".. ",
+  "../",
+  "../foo",
+  "foo/../bar",
+  "foo/bar",
+  "foo\\bar",
+  "foo\x00bar"
+]);
+function isSafeFilename(filename) {
+  if (typeof filename !== "string") {
+    return false;
+  }
+  const trimmed = filename.trim();
+  return trimmed !== "" && trimmed !== "." && trimmed !== ".." && !filename.includes("/") && !filename.includes("\\") && !filename.includes("\x00");
+}
+function assertSafeFilename(filename) {
+  if (typeof filename !== "string") {
+    throw new TypeError("Expected a string");
+  }
+  if (!isSafeFilename(filename)) {
+    throw new Error(`Unsafe filename: ${JSON.stringify(filename)}`);
+  }
+}
+
+// node_modules/env-paths/index.js
+var homedir = os.homedir();
+var tmpdir = os.tmpdir();
+var { env } = process2;
+var macos = (name) => {
+  const library = path.join(homedir, "Library");
+  return {
+    data: path.join(library, "Application Support", name),
+    config: path.join(library, "Preferences", name),
+    cache: path.join(library, "Caches", name),
+    log: path.join(library, "Logs", name),
+    temp: path.join(tmpdir, name)
+  };
+};
+var windows = (name) => {
+  const appData = env.APPDATA || path.join(homedir, "AppData", "Roaming");
+  const localAppData = env.LOCALAPPDATA || path.join(homedir, "AppData", "Local");
+  return {
+    data: path.join(localAppData, name, "Data"),
+    config: path.join(appData, name, "Config"),
+    cache: path.join(localAppData, name, "Cache"),
+    log: path.join(localAppData, name, "Log"),
+    temp: path.join(tmpdir, name)
+  };
+};
+var linux = (name) => {
+  const username = path.basename(homedir);
+  return {
+    data: path.join(env.XDG_DATA_HOME || path.join(homedir, ".local", "share"), name),
+    config: path.join(env.XDG_CONFIG_HOME || path.join(homedir, ".config"), name),
+    cache: path.join(env.XDG_CACHE_HOME || path.join(homedir, ".cache"), name),
+    log: path.join(env.XDG_STATE_HOME || path.join(homedir, ".local", "state"), name),
+    temp: path.join(tmpdir, username, name)
+  };
+};
+function envPaths(name, { suffix = "nodejs" } = {}) {
+  assertSafeFilename(name);
+  if (suffix) {
+    name += `-${suffix}`;
+  }
+  assertSafeFilename(name);
+  if (process2.platform === "darwin") {
+    return macos(name);
+  }
+  if (process2.platform === "win32") {
+    return windows(name);
+  }
+  return linux(name);
+}
+
+// src/lib/search/cache.ts
+var defaultSearchIndexUrl = "https://adcli.jiangzhx.com/search-index.json";
+function getSearchIndexCacheInfo(options = {}) {
+  const cacheDir = options.cacheDir ?? envPaths("adcli", { suffix: "" }).cache;
+  return {
+    cachePath: path2.join(cacheDir, "search-index.json"),
+    indexUrl: options.indexUrl ?? defaultSearchIndexUrl
+  };
+}
+async function loadSearchIndex(options = {}) {
+  if (options.index) {
+    return await loadExplicitSearchIndex(options.index, options.fetcher);
+  }
+  const cacheInfo = getSearchIndexCacheInfo(options);
+  if (!options.refresh) {
+    try {
+      return JSON.parse(await readFile(cacheInfo.cachePath, "utf8"));
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        throw error;
+      }
+    }
+  }
+  return await refreshSearchIndex(options);
+}
+async function refreshSearchIndex(options = {}) {
+  const cacheInfo = getSearchIndexCacheInfo(options);
+  const index = await fetchSearchIndex(cacheInfo.indexUrl, options.fetcher);
+  await writeCachedSearchIndex(cacheInfo.cachePath, index);
+  return index;
+}
+async function loadExplicitSearchIndex(index, fetcher = fetch) {
+  if (/^https?:\/\//i.test(index)) {
+    return await fetchSearchIndex(index, fetcher);
+  }
+  try {
+    return JSON.parse(await readFile(path2.resolve(index), "utf8"));
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      throw new Error(`missing search index: ${path2.relative(process.cwd(), path2.resolve(index))}`);
+    }
+    throw error;
+  }
+}
+async function fetchSearchIndex(indexUrl, fetcher = fetch) {
+  const response = await fetcher(indexUrl);
+  if (!response.ok) {
+    throw new Error(`failed to fetch search index: ${indexUrl} (${response.status})`);
+  }
+  return await response.json();
+}
+async function writeCachedSearchIndex(cachePath, index) {
+  await mkdir(path2.dirname(cachePath), { recursive: true });
+  const tempPath = `${cachePath}.${process.pid}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(index)}
+`, "utf8");
+  await rename(tempPath, cachePath);
+}
+function isNotFoundError(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
 
 // node_modules/minisearch/dist/es/index.js
 var ENTRIES = "ENTRIES";
@@ -131,9 +281,9 @@ class SearchableMap {
     if (!prefix.startsWith(this._prefix)) {
       throw new Error("Mismatched prefix");
     }
-    const [node, path] = trackDown(this._tree, prefix.slice(this._prefix.length));
+    const [node, path3] = trackDown(this._tree, prefix.slice(this._prefix.length));
     if (node === undefined) {
-      const [parentNode, key] = last(path);
+      const [parentNode, key] = last(path3);
       for (const k of parentNode.keys()) {
         if (k !== LEAF && k.startsWith(key)) {
           const node2 = new Map;
@@ -231,18 +381,18 @@ class SearchableMap {
     return SearchableMap.from(Object.entries(object));
   }
 }
-var trackDown = (tree, key, path = []) => {
+var trackDown = (tree, key, path3 = []) => {
   if (key.length === 0 || tree == null) {
-    return [tree, path];
+    return [tree, path3];
   }
   for (const k of tree.keys()) {
     if (k !== LEAF && key.startsWith(k)) {
-      path.push([tree, k]);
-      return trackDown(tree.get(k), key.slice(k.length), path);
+      path3.push([tree, k]);
+      return trackDown(tree.get(k), key.slice(k.length), path3);
     }
   }
-  path.push([tree, key]);
-  return trackDown(undefined, "", path);
+  path3.push([tree, key]);
+  return trackDown(undefined, "", path3);
 };
 var lookup = (tree, key) => {
   if (key.length === 0 || tree == null) {
@@ -285,38 +435,38 @@ var createPath = (node, key) => {
   return node;
 };
 var remove = (tree, key) => {
-  const [node, path] = trackDown(tree, key);
+  const [node, path3] = trackDown(tree, key);
   if (node === undefined) {
     return;
   }
   node.delete(LEAF);
   if (node.size === 0) {
-    cleanup(path);
+    cleanup(path3);
   } else if (node.size === 1) {
     const [key2, value] = node.entries().next().value;
-    merge(path, key2, value);
+    merge(path3, key2, value);
   }
 };
-var cleanup = (path) => {
-  if (path.length === 0) {
+var cleanup = (path3) => {
+  if (path3.length === 0) {
     return;
   }
-  const [node, key] = last(path);
+  const [node, key] = last(path3);
   node.delete(key);
   if (node.size === 0) {
-    cleanup(path.slice(0, -1));
+    cleanup(path3.slice(0, -1));
   } else if (node.size === 1) {
     const [key2, value] = node.entries().next().value;
     if (key2 !== LEAF) {
-      merge(path.slice(0, -1), key2, value);
+      merge(path3.slice(0, -1), key2, value);
     }
   }
 };
-var merge = (path, key, value) => {
-  if (path.length === 0) {
+var merge = (path3, key, value) => {
+  if (path3.length === 0) {
     return;
   }
-  const [node, nodeKey] = last(path);
+  const [node, nodeKey] = last(path3);
   node.set(nodeKey + key, value);
   node.delete(nodeKey);
 };
@@ -1274,14 +1424,29 @@ function compact(value) {
 }
 
 // src/cli.ts
-var defaultSearchIndexUrl = "https://adcli.jiangzhx.com/search-index.json";
 var help = `adcli
 
 Usage:
-  adcli doc search <query> [--index ${defaultSearchIndexUrl}] [--platform tencent_ads] [--limit 10] [--json]
+  adcli list [platform] [--json]
+  adcli doc <command>
+  adcli prompt
+  adcli llms
 
 Commands:
-  doc search    Search published advertising API docs
+  list          List supported advertising platforms and capabilities
+  doc           Search and sync published advertising API docs
+  prompt        Print an AI/Agent instruction prompt for using the docs pack
+  llms          Print LLM-readable docs pack entry URLs
+`;
+var docHelp = `adcli doc
+
+Usage:
+  adcli doc search <query> [--platform tencent_ads] [--limit 10] [--json] [--refresh]
+  adcli doc sync
+
+Commands:
+  search    Search published advertising API docs
+  sync      Download and cache the latest search index
 `;
 async function main() {
   const args = parseArgs(process.argv.slice(2));
@@ -1289,6 +1454,34 @@ async function main() {
     console.log(help.trim());
     return;
   }
+  if (args.domain === "list") {
+    const index2 = await loadSearchIndex({ index: args.index, refresh: args.refresh });
+    printDocList(index2, args);
+    return;
+  }
+  if (args.domain === "doc" && (!args.command || args.command === "--help" || args.command === "-h" || args.command === "help")) {
+    console.log(docHelp.trim());
+    return;
+  }
+  if (args.domain === "doc" && args.command === "sync") {
+    const index2 = await refreshSearchIndex();
+    const cache = getSearchIndexCacheInfo();
+    console.log(`Synced ${index2.documents.length} docs to ${cache.cachePath}`);
+    return;
+  }
+  if (args.domain === "doc" && args.command === "list") {
+    const index2 = await loadSearchIndex({ index: args.index, refresh: args.refresh });
+    printDocList(index2, args);
+    return;
+  }
+  if (args.domain === "prompt") {
+    printLlms({ ...args, domain: "llms", command: "prompt" });
+    return;
+  }
+  if (args.domain === "llms") {
+    printLlms(args);
+    return;
+  }
   if (args.domain !== "doc" || args.command !== "search") {
     throw new Error(`unknown command: ${[args.domain, args.command].filter(Boolean).join(" ")}`);
   }
@@ -1296,7 +1489,7 @@ async function main() {
   if (!query) {
     throw new Error("missing search query");
   }
-  const index = await loadSearchIndex(args.index);
+  const index = await loadSearchIndex({ index: args.index, refresh: args.refresh });
   const results = await searchDocuments({
     query,
     documents: index.documents,
@@ -1322,14 +1515,102 @@ async function main() {
     console.log(`   Score: ${result.score.toFixed(2)}`);
   }
 }
+function printDocList(index, args) {
+  const platformFilter = args.command;
+  const platforms = [...new Set(index.documents.map((document) => document.platform))].sort().filter((platform) => !platformFilter || platform === platformFilter).map((platform) => {
+    const documents = index.documents.filter((document) => document.platform === platform);
+    return {
+      platform,
+      capabilities: [
+        {
+          name: "doc",
+          documents: documents.length,
+          index_url: `https://adcli.jiangzhx.com/${platform}/index.md`,
+          commands: [
+            `adcli doc search <query> --platform ${platform}`
+          ]
+        }
+      ]
+    };
+  });
+  if (platformFilter && platforms.length === 0) {
+    throw new Error(`unsupported platform: ${platformFilter}`);
+  }
+  if (args.json) {
+    console.log(JSON.stringify({ platforms }, null, 2));
+    return;
+  }
+  for (const item of platforms) {
+    console.log(item.platform);
+    for (const capability of item.capabilities) {
+      console.log(`  ${capability.name}`);
+      for (const command of capability.commands) {
+        console.log(`    ${command}`);
+      }
+      console.log(`    docs: ${capability.documents}`);
+      console.log(`    index: ${capability.index_url}`);
+    }
+  }
+}
+function printLlms(args) {
+  const payload = {
+    name: "AdCLI Docs Pack",
+    base_url: "https://adcli.jiangzhx.com",
+    llms_txt: "https://adcli.jiangzhx.com/llms.txt",
+    llms_full_txt: "https://adcli.jiangzhx.com/llms-full.txt",
+    search_index: "https://adcli.jiangzhx.com/search-index.json",
+    platform_indexes: [
+      "https://adcli.jiangzhx.com/kuaishou/index.md",
+      "https://adcli.jiangzhx.com/oceanengine/index.md",
+      "https://adcli.jiangzhx.com/tencent_ads/index.md"
+    ]
+  };
+  if (args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (args.command === "prompt") {
+    console.log([
+      "Use the AdCLI advertising API docs pack when answering advertising platform API questions.",
+      "",
+      `Start with: ${payload.llms_txt}`,
+      `Use full index when needed: ${payload.llms_full_txt}`,
+      `Use search index for local/tool search: ${payload.search_index}`,
+      "",
+      "Rules:",
+      "- Prefer the Markdown docs from this docs pack over memory.",
+      "- Cite the specific platform document URL or source URL used.",
+      "- If a query names a platform, keep that platform as the primary context but do not ignore relevant cross-platform differences.",
+      "- For API testing or implementation, identify method, path, auth requirement, parameters, response fields, and known limits.",
+      "- If the docs are incomplete or ambiguous, say what is missing instead of guessing."
+    ].join(`
+`));
+    return;
+  }
+  console.log([
+    "AdCLI Docs Pack",
+    "",
+    `llms.txt:       ${payload.llms_txt}`,
+    `llms-full.txt:  ${payload.llms_full_txt}`,
+    `search index:   ${payload.search_index}`,
+    "",
+    "Platform indexes:",
+    ...payload.platform_indexes.map((url) => `- ${url}`),
+    "",
+    "Prompt for AI/Agent:",
+    "  adcli llms prompt"
+  ].join(`
+`));
+}
 function parseArgs(argv) {
   const args = {
     domain: argv[0],
     command: argv[1],
     query: [],
-    index: process.env.ADCLI_SEARCH_INDEX ?? defaultSearchIndexUrl,
+    index: process.env.ADCLI_SEARCH_INDEX,
     limit: 10,
-    json: false
+    json: false,
+    refresh: false
   };
   for (let index = 2;index < argv.length; index += 1) {
     const value = argv[index];
@@ -1342,6 +1623,10 @@ function parseArgs(argv) {
       index += 1;
       continue;
     }
+    if (value === "--refresh") {
+      args.refresh = true;
+      continue;
+    }
     if (value === "--limit") {
       args.limit = Number.parseInt(argv[index + 1] ?? "", 10);
       index += 1;
@@ -1359,24 +1644,6 @@ function parseArgs(argv) {
   }
   return args;
 }
-async function loadSearchIndex(index) {
-  if (/^https?:\/\//i.test(index)) {
-    const response = await fetch(index);
-    if (!response.ok) {
-      throw new Error(`failed to fetch search index: ${index} (${response.status})`);
-    }
-    return await response.json();
-  }
-  const indexPath = path.resolve(index);
-  try {
-    return JSON.parse(await readFile(indexPath, "utf8"));
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      throw new Error(`missing search index: ${path.relative(process.cwd(), indexPath)}. Use --index ${defaultSearchIndexUrl} or run: bun run build:search-index`);
-    }
-    throw error;
-  }
-}
 main().catch((error) => {
   console.error(error instanceof Error ? error.message : error);
   process.exit(1);

package/docs/commands.md

@@ -7,27 +7,43 @@
 
 ## 对外 CLI
 
-### `adcli doc search`
+### `adcli list`
 
-搜索已经发布到线上 docs pack 的广告平台文档。全局安装后直接使用：
+列出当前支持的广告平台和能力。
 
 ```bash
-adcli doc search "广告消耗"
+adcli list
+adcli list kuaishou
+adcli list --json
 ```
 
-项目内开发时也可以用：
+当前能力：
+
+- `doc`: 已发布的文档查询能力，对应命令形态是 `adcli doc search <query> --platform <platform>`。
+
+这个命令会读取本地缓存；缓存不存在时会下载线上 `search-index.json`。
+
+兼容命令：
 
 ```bash
-bun run adcli doc search "广告消耗"
+adcli doc list
+```
+
+### `adcli doc search`
+
+搜索已经发布到线上 docs pack 的广告平台文档。全局安装后直接使用：
+
+```bash
+adcli doc search "广告消耗"
 ```
 
 支持参数：
 
 ```bash
-bun run adcli doc search "广告消耗" --limit 5
-bun run adcli doc search "广告消耗" --json
-bun run adcli doc search "广告消耗" --index public/search-index.json
-bun run adcli doc search "广告消耗" --platform tencent_ads
+adcli doc search "广告消耗" --limit 5
+adcli doc search "广告消耗" --json
+adcli doc search "广告消耗" --index public/search-index.json
+adcli doc search "广告消耗" --platform tencent_ads
 ```
 
 全局 CLI 默认读取：
@@ -36,6 +52,19 @@ bun run adcli doc search "广告消耗" --platform tencent_ads
 https://adcli.jiangzhx.com/search-index.json
 ```
 
+第一次搜索会下载索引并写入系统标准缓存目录：
+
+- macOS: `~/Library/Caches/adcli/search-index.json`
+- Linux: `${XDG_CACHE_HOME:-~/.cache}/adcli/search-index.json`
+- Windows: `%LOCALAPPDATA%/adcli/Cache/search-index.json`
+
+主动更新缓存：
+
+```bash
+adcli doc sync
+adcli doc search "广告消耗" --refresh
+```
+
 也可以用环境变量覆盖：
 
 ```bash
@@ -54,6 +83,38 @@ ADCLI_SEARCH_INDEX=https://example.com/search-index.json adcli doc search "广
 
 查询词中包含平台别名时会提升对应平台的排序权重，例如 `广点通`、`腾讯广告` 会提升 `tencent_ads` 文档，但不会硬过滤其他平台。需要明确限制平台时，使用 `--platform tencent_ads`。
 
+### `adcli llms`
+
+输出给 AI / Agent 使用的 docs pack 入口。
+
+```bash
+adcli llms
+adcli llms --json
+```
+
+输出包括：
+
+- `llms.txt`
+- `llms-full.txt`
+- `search-index.json`
+- 各平台 index
+
+### `adcli prompt`
+
+输出一段可复制给 AI / Agent 的使用说明。
+
+```bash
+adcli prompt
+```
+
+这段 prompt 会要求 AI 优先使用 AdCLI 发布的 Markdown 文档，引用具体来源，并在文档不足时明确说明缺口。
+
+兼容命令：
+
+```bash
+adcli llms prompt
+```
+
 ## 采集命令
 
 ### `bun run discover:sources`
@@ -195,7 +256,7 @@ bun run lint
 
 ## 当前边界
 
-`adcli` CLI 当前只支持 `doc search`。采集、构建和校验还停留在 `bun run ...` 工程命令层。
+`adcli` CLI 当前支持 `doc search`、`doc sync` 和 `llms` 入口。采集、构建和校验还停留在 `bun run ...` 工程命令层。
 
 后续如果要把项目产品化成完整 CLI，可以逐步把这些能力收进 `adcli`：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiangzhx/adcli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI for searching hosted advertising platform API docs.",
   "type": "module",
   "packageManager": "bun@1.3.10",
@@ -49,6 +49,7 @@
     "typescript-eslint": "^8.59.3"
   },
   "dependencies": {
+    "env-paths": "^4.0.0",
     "minisearch": "^7.2.0"
   }
 }