@jiangzhx/adcli 0.1.2 → 0.1.4

package/docs/commands.md

@@ -75,7 +75,7 @@ ADCLI_SEARCH_INDEX=https://example.com/search-index.json adcli doc search "广
 
 - 平台 ID。
 - 文档标题。
-- `public/` 下的 Markdown 路径。
+- 线上 Markdown URL 和 `public/` 下的 Markdown 路径。
 - 原始官方文档 URL。
 - 搜索分数。
 
@@ -83,6 +83,52 @@ ADCLI_SEARCH_INDEX=https://example.com/search-index.json adcli doc search "广
 
 查询词中包含平台别名时会提升对应平台的排序权重，例如 `广点通`、`腾讯广告` 会提升 `tencent_ads` 文档，但不会硬过滤其他平台。需要明确限制平台时，使用 `--platform tencent_ads`。
 
+## 维护者采集命令
+
+### `bun run ingest:url`
+
+采集导航树未收录但可直达的单个官方文档页面，例如巨量开放平台里不出现在左侧树、但 URL 可直接打开的文档。
+
+```bash
+bun run ingest:url https://open.oceanengine.com/labels/7/docs/1865873315616282
+bun run ingest:url https://open.oceanengine.com/labels/7/docs/1865873315616282 --platform oceanengine
+```
+
+当前支持：
+
+- `oceanengine`: `https://open.oceanengine.com/labels/<label_id>/docs/<doc_id>`
+
+命令会自动从 URL 识别平台和 `doc_id`，写入 `data/sources/{platform}/...`，并从页面内容解析标题。`--title` 不受支持；如果标题或正文无法从页面解析出来，应视为采集质量问题。
+
+采集完成后，命令会提示下一步：
+
+```bash
+bun run build:llms --url https://open.oceanengine.com/labels/7/docs/1865873315616282
+```
+
+需要发布到 `public/` 文档包、`llms-full.txt` 和 `search-index.json` 时再执行这一步。
+
+### `bun run build:llms --url`
+
+只发布单个已采集 URL 对应的 Markdown 文档，并更新依赖它的汇总产物。
+
+```bash
+bun run build:llms --url https://open.oceanengine.com/labels/7/docs/1865873315616282
+bun run build:llms --url https://open.oceanengine.com/labels/7/docs/1865873315616282 --platform oceanengine
+```
+
+当前支持：
+
+- `oceanengine`: `https://open.oceanengine.com/labels/<label_id>/docs/<doc_id>`
+
+命令要求对应源数据已经存在于 `data/sources/{platform}/...`，通常先执行 `bun run ingest:url <url>`。它只重写目标文档 Markdown 文件，同时更新：
+
+- `public/{platform}/index.md`
+- `public/{platform}/manifest.json`
+- `public/llms.txt`
+- `public/llms-full.txt`
+- `public/search-index.json`
+
 ### `adcli llms`
 
 输出给 AI / Agent 使用的 docs pack 入口。
@@ -115,11 +161,182 @@ adcli prompt
 adcli llms prompt
 ```
 
+### `adcli oceanengine auth`
+
+保存巨量引擎 access token。保存后，巨量引擎相关命令可以不再重复传 `--access-token`。
+
+```bash
+adcli oceanengine auth <token>
+```
+
+token 会按 CLI 缓存处理，保存到 AdCLI 缓存目录下的 `oceanengine.json`。macOS 默认路径：
+
+```text
+~/Library/Caches/adcli/oceanengine.json
+```
+
+token 优先级：
+
+1. `--access-token`
+2. `OCEANENGINE_ACCESS_TOKEN`
+3. `adcli oceanengine auth <token>` 保存的本地 token
+
+### `adcli oceanengine advertiser list`
+
+通过当前仓库内的巨量引擎 Node.js SDK 拉取授权广告主列表。
+默认输出 `advertiser_id` 和 `name` 两列；需要完整响应时加 `--json`。
+
+```bash
+adcli oceanengine advertiser list --access-token <token>
+adcli oceanengine advertiser list --json
+```
+
+也可以用环境变量提供 token，或先通过 `adcli oceanengine auth <token>` 保存 token：
+
+```bash
+OCEANENGINE_ACCESS_TOKEN=<token> adcli oceanengine advertiser list --json
+```
+
+对应 SDK/API：
+
+- SDK: `Oauth2AdvertiserGetApi`
+- API: `GET /open_api/oauth2/advertiser/get/`
+
+### `adcli oceanengine project list`
+
+通过当前仓库内的巨量引擎 Node.js SDK 拉取广告主下的项目列表，对应巨量引擎 OpenAPI 的 `project/list`。
+
+```bash
+adcli oceanengine project list --advertiser-id <advertiser_id> --access-token <token>
+adcli oceanengine project list --advertiser-id <advertiser_id> --page 1 --page-size 20
+adcli oceanengine project list --advertiser-id <advertiser_id> --json
+adcli oceanengine project list --advertiser-id <advertiser_id> --filtering '{"status":"PROJECT_STATUS_ALL"}'
+adcli oceanengine project list --advertiser-id <advertiser_id> --filtering '{"status_first":"PROJECT_STATUS_ENABLE"}'
+```
+
+默认输出只包含 `project_id` 和 `name` 两列；使用 `--json` 打印完整原始响应。
+巨量接口默认不返回已删除项目；需要和 fujian 同步口径一致时，使用 `--filtering '{"status":"PROJECT_STATUS_ALL"}'` 拉取包含已删除项目的全量列表。
+
+对应 SDK/API：
+
+- SDK: `ProjectListV30Api`
+- API: `GET /open_api/v3.0/project/list/`
+
+### `adcli oceanengine promotion list`
+
+通过当前仓库内的巨量引擎 Node.js SDK 拉取广告主下的广告列表，对应巨量引擎 OpenAPI 的 `promotion/list`。
+
+```bash
+adcli oceanengine promotion list --advertiser-id <advertiser_id> --access-token <token>
+adcli oceanengine promotion list --advertiser-id <advertiser_id> --project-id <project_id>
+adcli oceanengine promotion list --advertiser-id <advertiser_id> --project-id <project_id> --json
+adcli oceanengine promotion list --advertiser-id <advertiser_id> --fields promotion_id,name,status_first
+adcli oceanengine promotion list --advertiser-id <advertiser_id> --filtering '{"status_first":"PROMOTION_STATUS_ENABLE"}'
+```
+
+默认输出只包含 `promotion_id` 和 `name` 两列；使用 `--json` 打印完整原始响应。
+
+对应 SDK/API：
+
+- SDK: `PromotionListV30Api`
+- API: `GET /open_api/v3.0/promotion/list/`
+
+### `adcli tencent-ads auth`
+
+保存腾讯广告 access token。保存后，腾讯广告相关命令可以不再重复传 `--access-token`。
+
+```bash
+adcli tencent-ads auth <token>
+```
+
+token 会按 CLI 缓存处理，保存到 AdCLI 缓存目录下的 `tencent-ads.json`。macOS 默认路径：
+
+```text
+~/Library/Caches/adcli/tencent-ads.json
+```
+
+token 优先级：
+
+1. `--access-token`
+2. `TENCENT_ADS_ACCESS_TOKEN`
+3. `adcli tencent-ads auth <token>` 保存的本地 token
+
+### `adcli tencent-ads advertiser list`
+
+通过当前仓库内的腾讯广告 Node.js SDK 拉取 BM/管家账号下的账号列表。
+默认输出 `account_id` 和 `name` 两列；需要完整响应时加 `--json`。
+
+```bash
+adcli tencent-ads advertiser list --access-token <token>
+adcli tencent-ads advertiser list --json
+adcli tencent-ads advertiser list --fields account_id,corporation_name,is_bid,is_mp,is_adx,comment_list
+```
+
+这个命令对齐 fujian 的广告主同步逻辑，默认调用 `organization_account_relation/get`，不是 `advertiser/get`。
+
+对应 SDK/API：
+
+- SDK: `api/v3.OrganizationAccountRelationApi`
+- API: `GET /organization_account_relation/get`
+
+### `adcli tencent-ads advertiser get`
+
+通过当前仓库内的腾讯广告 Node.js SDK 拉取单个账号详情，对应腾讯广告 OpenAPI 的 `advertiser/get`。
+
+```bash
+adcli tencent-ads advertiser get --account-id <account_id> --access-token <token>
+adcli tencent-ads advertiser get --account-id <account_id> --json
+adcli tencent-ads advertiser get --account-id <account_id> --fields account_id,account_name
+```
+
+对应 SDK/API：
+
+- SDK: `api/v3.AdvertiserApi`
+- API: `GET /advertiser/get`
+
+### `adcli tencent-ads adgroup list`
+
+通过当前仓库内的腾讯广告 Node.js SDK 拉取账号下的营销单元列表，对应腾讯广告 v3 API 的 `adgroups/get`。
+
+```bash
+adcli tencent-ads adgroup list --account-id <account_id> --access-token <token>
+adcli tencent-ads adgroup list --account-id <account_id> --page 1 --page-size 20
+adcli tencent-ads adgroup list --account-id <account_id> --json
+adcli tencent-ads adgroup list --account-id <account_id> --fields adgroup_id,adgroup_name
+adcli tencent-ads adgroup list --account-id <account_id> --filtering '{"configured_status":"AD_STATUS_NORMAL"}'
+```
+
+`--advertiser-id` 可作为 `--account-id` 的别名。默认输出只包含 `adgroup_id` 和 `name` 两列；使用 `--json` 打印完整原始响应。资源过滤统一传 `--filtering` JSON。
+
+对应 SDK/API：
+
+- SDK: `api/v3.AdgroupsApi`
+- API: `GET /v3.0/adgroups/get`
+
+### `adcli tencent-ads dynamic-creative list`
+
+通过当前仓库内的腾讯广告 Node.js SDK 拉取账号下的创意列表，对应腾讯广告 v3 API 的 `dynamic_creatives/get`。
+
+```bash
+adcli tencent-ads dynamic-creative list --account-id <account_id> --access-token <token>
+adcli tencent-ads dynamic-creative list --account-id <account_id> --page 1 --page-size 20
+adcli tencent-ads dynamic-creative list --account-id <account_id> --json
+adcli tencent-ads dynamic-creative list --account-id <account_id> --fields dynamic_creative_id,dynamic_creative_name
+adcli tencent-ads dynamic-creative list --account-id <account_id> --filtering '{"adgroup_id":"<adgroup_id>"}'
+```
+
+`--advertiser-id` 可作为 `--account-id` 的别名。默认输出只包含 `dynamic_creative_id` 和 `name` 两列；使用 `--json` 打印完整原始响应。资源过滤统一传 `--filtering` JSON。
+
+对应 SDK/API：
+
+- SDK: `api/v3.DynamicCreativesApi`
+- API: `GET /v3.0/dynamic_creatives/get`
+
 ## 采集命令
 
 ### `bun run discover:sources`
 
-从 collection recipe 入口发现文档列表，生成 collection manifest。
+从 collection recipe 入口发现文档列表，生成 collection manifest。一个 recipe 文件对应一个平台，多个发现来源放在顶层 `sources` 数组里。
 
 ```bash
 bun run discover:sources recipes/oceanengine-open-platform-docs.json
@@ -129,16 +346,51 @@ bun run discover:sources recipes/oceanengine-open-platform-docs.json
 
 - `recipes/{platform}-*.json`
 
+配置示例：
+
+```json
+{
+  "platform": "oceanengine",
+  "sources": [
+    {
+      "url": "https://open.oceanengine.com/labels/7/docs/1839621283557572",
+      "discover": {
+        "mode": "playwright",
+        "link_patterns": ["/labels/7/docs/"],
+        "wait_for": "body",
+        "max_items": "all"
+      }
+    },
+    {
+      "url": "https://bytedance.larkoffice.com/docx/BH6zdu3j2o9hiGxr4oucedjFnGb",
+      "discover": {
+        "link_patterns": ["https://open.oceanengine.com/labels/7/docs/"],
+        "max_items": "all"
+      }
+    }
+  ]
+}
+```
+
+飞书/Lark 文档 URL 会自动按 `lark_doc` 来源处理，只把飞书文档作为 URL 来源；实际采集正文时仍采集 `link_patterns` 匹配到的官方文档地址。
+
+`lark_doc` 来源依赖 `lark-cli` 读取飞书文档内容。项目已把 `@larksuite/cli` 放在 devDependencies，`bun install` 后会安装本地 `lark-cli`。首次使用前需要完成飞书配置和授权：
+
+```bash
+bunx lark-cli config init --new
+bunx lark-cli auth login --recommend
+```
+
 输出：
 
-- `data/sources/{platform}/_collections/{collection_id}/manifest.json`
+- `data/sources/{platform}/_collections/manifest.json`
 
 ### `bun run ingest:collection`
 
 按 collection manifest 批量采集文档。
 
 ```bash
-bun run ingest:collection data/sources/oceanengine/_collections/oceanengine_open_platform_docs/manifest.json
+bun run ingest:collection data/sources/oceanengine/_collections/manifest.json
 ```
 
 支持参数：
@@ -172,6 +424,7 @@ bun run ingest:source recipes/some-single-source.json
 ### `bun run build:llms`
 
 把 `data/sources/` 编译成 `public/` 静态文档包。
+如果平台存在 `data/sources/{platform}/_collections/manifest.json`，全量构建只发布该 manifest 中的 source，并清理 `public/{platform}/docs/` 下不在当前 source 集合里的历史 Markdown。
 
 ```bash
 bun run build:llms all
@@ -187,6 +440,20 @@ bun run build:llms oceanengine
 - `public/{platform}/manifest.json`
 - `public/{platform}/docs/{doc_id}.md`
 
+### `bun run deploy:cloudflare`
+
+校验 `public/` 后发布到 Cloudflare Pages 的 `adcli` 项目。
+
+```bash
+CLOUDFLARE_API_TOKEN=<token> bun run deploy:cloudflare
+```
+
+实际执行：
+
+```bash
+bun run verify:public && bunx wrangler pages deploy public --project-name adcli --branch main
+```
+
 ### `bun run build:search-index`
 
 只基于当前 `public/` 重新生成搜索索引。

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@jiangzhx/adcli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI for searching hosted advertising platform API docs.",
   "type": "module",
   "packageManager": "bun@1.3.10",
+  "workspaces": [
+    "packages/*"
+  ],
   "homepage": "https://github.com/jiangzhx/adcli#readme",
   "repository": {
     "type": "git",
@@ -29,18 +32,37 @@
     "discover:sources": "bun scripts/discover-sources.ts",
     "ingest:collection": "bun scripts/ingest-collection.ts",
     "ingest:source": "bun scripts/ingest-source.ts",
+    "ingest:url": "bun scripts/ingest-url.ts",
     "rebuild:source-blocks": "bun scripts/rebuild-source-blocks.ts",
     "build:llms": "bun scripts/build-llms.ts",
     "build:search-index": "bun scripts/build-search-index.ts",
     "verify:public": "bun scripts/verify-public.ts",
+    "deploy:cloudflare": "bun run verify:public && bunx wrangler pages deploy public --project-name adcli --branch main",
     "adcli": "bun src/cli.ts",
     "prepack": "bun run build:cli",
-    "test": "bun test tests/**/*.test.ts",
+    "test": "bun test tests",
+    "test:all": "bun run test && bun run sdk:test && bun run codegen:test",
     "typecheck": "tsc --noEmit",
+    "typecheck:all": "bun run typecheck && bun run sdk:typecheck && bun run codegen:typecheck",
+    "sdk:oceanengine:test": "bun run --cwd packages/oceanengine-ad-open-sdk test",
+    "sdk:oceanengine:typecheck": "bun run --cwd packages/oceanengine-ad-open-sdk typecheck",
+    "sdk:tencent-ads:test": "bun run --cwd packages/tencent-ads-marketing-api-sdk test",
+    "sdk:tencent-ads:typecheck": "bun run --cwd packages/tencent-ads-marketing-api-sdk typecheck",
+    "sdk:test": "bun run sdk:oceanengine:test && bun run sdk:tencent-ads:test",
+    "sdk:typecheck": "bun run sdk:oceanengine:typecheck && bun run sdk:tencent-ads:typecheck",
+    "codegen:oceanengine:generate": "bun run --cwd packages/codegen generate:oceanengine",
+    "codegen:oceanengine:generate:go": "bun run --cwd packages/codegen generate:oceanengine:go",
+    "codegen:oceanengine:test": "bun run --cwd packages/codegen test:oceanengine",
+    "codegen:tencent-ads:generate": "bun run --cwd packages/codegen generate:tencent-ads",
+    "codegen:tencent-ads:generate:go": "bun run --cwd packages/codegen generate:tencent-ads:go",
+    "codegen:tencent-ads:test": "bun run --cwd packages/codegen test:tencent-ads",
+    "codegen:test": "bun run --cwd packages/codegen test",
+    "codegen:typecheck": "bun run --cwd packages/codegen typecheck",
     "lint": "eslint"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@larksuite/cli": "^1.0.66",
     "@types/node": "^20",
     "crawlee": "^3.16.0",
     "eslint": "^9",
@@ -49,6 +71,8 @@
     "typescript-eslint": "^8.59.3"
   },
   "dependencies": {
+    "@jiangzhx/oceanengine-ad-open-sdk": "1.1.88-port.1",
+    "@jiangzhx/tencent-ads-marketing-api-sdk": "1.7.85-port.1",
     "env-paths": "^4.0.0",
     "minisearch": "^7.2.0"
   }