@gobing-ai/knowledge-kit 0.1.14 → 0.1.15

package/plugins/kk/skills/web-automation/references/browser-launch.md

@@ -1,71 +1,160 @@
 # Browser launch & cached-login recipes
 
-Everything here is measured on the kk channels (E92 discovery, 2026-10).
-The launcher is the proven pattern from `.spur/run/discovery/xhs-launch.ts` /
-`walk-wechatmp*.ts`; the profile matrix is the live
-`~/.config/kk/browser-profiles/` tree.
+Everything here is measured on the kk channels (E92 discovery, A22 named bots, and 0346 collection runner).
+The canonical tool for named session management is `kk bot`; the underlying libraries are `@gobing-ai/publish-harness`
+and `@gobing-ai/publish-harness/bot-collection`.
+
+## Named bot CLI suite (`kk bot`)
+
+The profile root `~/.config/kk/browser-profiles/<name>` is managed safely with transactional staging and leases:
+
+```bash
+kk bot list                        # List cached profiles, last login, and estimated expiry
+kk bot login <channel>             # Headed interactive login (delegates to matched channel adapter)
+kk bot login <url> --save <name>   # Generic headed login (operator terminal confirmation before save)
+kk bot open <name> [--login]       # Open saved page headed until window closes (--login re-authenticates)
+kk bot logout <name>               # Delete local profile directory behind the shared lease
+kk bot exec <name> <url> [opts]    # Single authenticated HTTP request with cached cookies (curl subset)
+kk bot plan <name> <plan.json> [opts] # Execute declarative collection plan under lease (-o, -m)
+```
+
+## Rendered collection runner substrate (task 0346)
 
-## The launcher (persistent context + CDP + stealth)
+For automated structured web data collection without raw browser scripting, use `@gobing-ai/publish-harness/bot-collection`.
+It executes a declarative JSON plan under a single profile lease and a single headless persistent context:
+
+```ts
+import { runBotCollection } from '@gobing-ai/publish-harness/bot-collection';
+
+const result = await runBotCollection('xhs', {
+    steps: [
+        { id: 'home', kind: 'navigate', url: 'https://creator.xiaohongshu.com/' },
+        { id: 'wait-nav', kind: 'wait', selector: '.creator-menu' },
+        { id: 'click-menu', kind: 'click', selector: '.creator-menu >> text="Publish"' },
+        { id: 'extract-data', kind: 'extract', selector: '.data-card', format: 'text' },
+    ],
+    responses: [
+        { id: 'creator-info', pathPrefix: '/api/galaxy/creator/info' },
+    ],
+    timeoutMs: 45_000,
+});
+```
+
+### Plan step grammar (`BotCollectionStep`)
+
+- `{ id, kind: 'navigate', url, waitUntil?: 'load'|'domcontentloaded'|'networkidle'|'commit' }`
+- `{ id, kind: 'wait', selector?, timeoutMs? }`
+- `{ id, kind: 'click', selector, timeoutMs? }`
+- `{ id, kind: 'scroll', deltaY, selector?, timeoutMs? }`
+- `{ id, kind: 'extract', selector, format: 'text'|'html'|'count', timeoutMs? }`
+- `{ id, kind: 'request', url, method?: 'GET'|'POST', headers?, data? }`
+- Capture: `responses: [{ id, origin?, pathPrefix, optional?: boolean }]`
+
+### Fail-closed error contract
+
+- `authentication`: Explicit 401/403 (request, navigation, or required response) or final navigation URL matching `/login|signin|sign-in|auth|sso/i`.
+- `empty`: A declared non-optional capture matched no response, or an extract/request step yielded an empty body. Prevents client-side rendered SPA shells from masquerading as a quiet day.
+- `browser`: Network/transport error, timeout, or uncaught DOM exception.
+
+### CLI Execution (`kk bot plan`) and Probe Script
+
+Run collection plans directly with the CLI:
+
+```bash
+# Output JSON result to stdout
+kk bot plan <channel> <plan.json> -m 60
+
+# Write individual 0600 artifacts and result.json / error.json into directory
+kk bot plan <channel> <plan.json> -o <output-dir> -m 60
+```
+
+Low-level debugging can also use `bot-collection-probe.ts`:
+
+```bash
+bun packages/publish-harness/scripts/bot-collection-probe.ts \
+  --profile <name> \
+  --plan <plan.json> \
+  --out <output-dir>
+```
+
+Outputs artifact files with 0600 permissions, `result.json` (metadata without bodies), or `error.json` on failure.
+
+## Direct Playwright launcher (persistent context + lease + CDP + stealth)
+
+When interactive discovery or custom CDP scripts are needed, always wrap execution with the profile lease:
 
 ```ts
 import { chromium } from 'playwright';
+import { withProfileLease } from '@gobing-ai/publish-harness';
 
-const profileDir = process.env.KK_WEB_PROFILE ?? `${process.env.HOME}/.config/kk/browser-profiles/<channel>`;
+const profileName = process.env.KK_WEB_BOT ?? '<channel>';
+const profileDir = `${process.env.HOME}/.config/kk/browser-profiles/${profileName}`;
 const port = process.env.KK_WEB_CDP ?? '9222';
 
-const ctx = await chromium.launchPersistentContext(profileDir, {
-    headless: process.env.KK_WEB_HEADLESS === 'true', // default headed
-    viewport: null,
-    args: [
-        `--remote-debugging-port=${port}`,              // agent-browser / external CDP clients attach here
-        '--disable-blink-features=AutomationControlled', // required at OAuth/bot-wall gates
-    ],
+await withProfileLease(profileName, async () => {
+    const ctx = await chromium.launchPersistentContext(profileDir, {
+        headless: process.env.KK_WEB_HEADLESS === 'true', // default headed
+        viewport: null,
+        args: [
+            `--remote-debugging-port=${port}`,              // agent-browser / external CDP clients attach here
+            '--disable-blink-features=AutomationControlled', // required at OAuth/bot-wall gates
+        ],
+    });
+    const page = ctx.pages()[0] ?? (await ctx.newPage());
+    console.log(JSON.stringify({ cdpPort: port, profile: profileDir, url: page.url() }));
+    process.on('SIGTERM', async () => { await ctx.close(); process.exit(0); });
+    await new Promise(() => {}); // stay up for CDP drivers
 });
-const page = ctx.pages()[0] ?? (await ctx.newPage());
-console.log(JSON.stringify({ cdpPort: port, profile: profileDir, url: page.url() }));
-process.on('SIGTERM', async () => { await ctx.close(); process.exit(0); });
-await new Promise(() => {}); // stay up for CDP drivers
 ```
 
 - The **profile dir is the credential cache** — cookies + storage survive runs;
   nothing else is persisted, no tokens are printed.
 - `agent-browser` (or any CDP client) attaches to the printed port; plain
   Playwright scripts can also import the same process's `page`.
-- One context per channel. Two concurrent launches on one profile corrupt it.
+- **Profile lease required**: `withProfileLease` ensures single-process access.
+  Two concurrent launches on one profile corrupt it.
 
 ## Headless vs headed
 
 | Situation | Mode | Why |
 | --- | --- | --- |
-| Session probe / preflight | headless OK | read-only, cheap |
+| Session probe / preflight (`kk bot list`, `check`) | headless OK | read-only, cheap |
+| `kk bot exec` single-request fetch | headless | persistent context attaches cookies automatically |
+| `runBotCollection` automated collection | headless | bounded steps and required response captures |
 | Automated drive on a proven session | headless OK | measured: infoq/juejin/substack/x/wechatmp drives work headless post-login |
-| `auth: fresh` login | **headed** | operator completes QR/OAuth by hand |
-| xhs any operation | **headed** | bot-walls headless loads (measured); shadow-root clicks need CDP anyway |
+| `kk bot login` / fresh authentication | **headed** | operator completes QR/OAuth/password by hand |
+| `kk bot open` inspection | **headed** | operator views page and DOM |
+| xhs any publish/drive | **headed** | bot-walls headless loads (measured); shadow-root clicks need CDP anyway |
 | Any step that might trip a bot wall first time | **headed** | watch it once, record, then automate |
 
 ## Profile matrix (as shipped)
 
-| Channel | Profile dir | Notes |
-| --- | --- | --- |
-| xhs | `browser-profiles/xhs` | headed always; shadow-root controls via CDP box models |
-| infoq | `browser-profiles/infoq` | draft save = `/draft/<id>` URL |
-| juejin | `browser-profiles/juejin` | draft id from post-save URL |
-| substack | `browser-profiles/substack` | robinmin.substack.com; post id in `/publish/post/<id>` |
-| x | `browser-profiles/x` | article edit URL carries draft id |
-| wechatmp | `browser-profiles/wechatmp` | QR login; draft id from draft/add response + editor URL |
+| Channel | Profile dir | Login command | Notes |
+| --- | --- | --- | --- |
+| xhs | `browser-profiles/xhs` | `kk bot login xhs` | headed always; shadow-root controls via CDP box models |
+| infoq | `browser-profiles/infoq` | `kk bot login infoq` | draft save = `/draft/<id>` URL |
+| juejin | `browser-profiles/juejin` | `kk bot login juejin` | draft id from post-save URL |
+| substack | `browser-profiles/substack` | `kk bot login substack` | robinmin.substack.com; post id in `/publish/post/<id>` |
+| x | `browser-profiles/x` | `kk bot login x` | article edit URL carries draft id |
+| wechatmp | `browser-profiles/wechatmp` | `kk bot login wechatmp` | QR login; draft id from draft/add response + editor URL |
+| weibo | `browser-profiles/weibo` | `kk bot login weibo` | 头条文章 editor |
 
-New channel ⇒ one-time headed `fresh` login on that dir, then it becomes the cache.
+New channel ⇒ one-time headed `kk bot login <url> --save <name>` or `kk bot login <channel>`, then it becomes the cache.
 
 ## Session probe (cached-auth validity)
 
-Don't age-guess — probe a signed-in-only selector on the channel's console URL:
+Don't age-guess — probe a signed-in-only selector or run the plugin's probe:
 
-```ts
-const ok = await page.locator('<signed-in-only selector>').first().isVisible({ timeout: 10_000 });
-if (!ok) throw new Error('auth=expired: fresh login required');
-```
+```bash
+# Fast metadata check
+kk bot list
+
+# Lightweight authenticated request test
+kk bot exec <name> <console-url>
 
-Per-channel selectors live in the channel's `docs/design/<channel>-ui-discovery.md`.
+# Reopen or re-authenticate
+kk bot open <name> --login
+```
 
 ## storageState vs profile dir
 
@@ -84,3 +173,5 @@ assumed.
   timeout (e.g. wechatmp `.weui-desktop-toast` ≤ 15 s) — loud on miss.
 - Always `ctx.close()` on SIGTERM/exit paths; orphaned Chromiums hold the
   profile lock and the next run fails confusingly.
+- In collection plans (`runBotCollection`), differentiate `authentication` (action: run `kk bot login`),
+  `empty` (action: check site selector/API path drift), and `browser` (action: investigate transport/timeout).

package/plugins/kk/workflows/kk-daily-ai-voice2.yaml

@@ -50,12 +50,9 @@ vars:
   cover_fallback: ""
   # 0219 R3: image-gen vendor fallback for the XHS render; "" restores strict fail-fast.
   xhs_fallback: "true"
-  # 2026-10-21 operator decision: OFF for now (was on since 2026-09-29). The plugin reported today's
-  # draft as saved (`草稿箱` 12 -> 13 plus a scoped `保存成功` toast) while the console showed the
-  # operator no draft, so the channel's success evidence is not trustworthy until that is resolved.
-  # Flip back to "true" to resume the card plan/render/draft series; `xhs_live` stays a separate
-  # launch-time switch and nothing else in the run depends on this target.
-  xhs_enabled: "false"
+  # 2026-11-09 operator decision: turned on by default for 上传图文 (cards) and 发播客 (episode note);
+  # `xhs_live` stays a separate launch-time switch (draft by default) and nothing else in the run depends on this target.
+  xhs_enabled: "true"
   xhs_cards: "4"
   xhs_style: "xhs-knowledge"
   xhs_provider: "minimax"
@@ -391,6 +388,7 @@ nodes:
         input: &article-write-input |
           Read ${vars.work_dir}/21-plan/${vars.run_date}_03_plan_plan.json — metadata.docs (Doc[]) is the translated plan; don't edit it.
           Write vivid simplified-Chinese tech news for 咸话咸说之每日AI乱炖 (column 每日AI乱炖, host Robin). No title line. Open with exactly「这里是由Robin为你带来的咸话咸说之每日AI乱炖」。Never「我是咸话咸说」or an AI-production footer. Each ## section: what happened, why it matters, one concrete detail — a human reporter, not a telegram. Inline [来源：<label>](<sourceUri>). Close by tying the items together.
+          标题纪律（站点 digest 契约，不满足则 refine 拒绝发布）：每个 ## 标题必须以主体起头，第一个逗号/冒号之前的那段不超过 14 个汉字（英文专名与数字各算 1 个字位），且是一个名词短语——如「TSMC 把存储搬进逻辑芯片」「OpenAI 新证明」「Qwen3.5 纯汇编推理」。禁止以动词或「上周/一条/再」这类虚词起头的整句式标题；冒号之后可自由展开。
           选题边界：只写技术内容；某条主线若属政治/外交或贸易管制/军事/公共政策争议/社会公共事件，跳过该条并在文末加一行「> 注：<N> 条条目因选题边界未写入：<id>（<原因>）、<id>（<原因>）」。
           事实纪律：每个事实取自该条计划内容，不虚构、不引他处；数字与主体不得放大；引语只能归属其原句主语；保留「据报道/称/承诺」等限定词；导语/收束不加计划外程度词；材料不足就少写或不写，不凑数。
           Narrative register — smooth transitions, no list-like bulleting, no scaffold labels (「可做角度」「背景」「潜在影响」), no hedging (「读者宜另行核实」「仍待验证」). 「」 quotes.