@gobing-ai/knowledge-kit 0.1.13 → 0.1.15

package/plugins/kk/skills/web-automation/SKILL.md

@@ -1,101 +1,253 @@
 ---
 name: web-automation
 description: >-
-  Discover, enhance, and automate web tasks with Playwright (or agent-browser
-  over CDP) — "walk this console and record evidence", "figure out this site's
+  Discover, enhance, and automate web tasks with Playwright, kk bot, or agent-browser
+  over CDP — "walk this console and record evidence", "figure out this site's
   UI", "automate this web flow", "reuse my cached login on <channel>", "check
-  whether my session on <channel> is still valid", "fix this channel's
-  selectors", or when a spur workflow `agent.run` step targets the
-  web-automation skill. Owns method and evidence; transport stays in kk
-  plugins; orchestration is a @gobing-ai/ts-dual-workflow-engine
-  transition-flow (see docs/design/web-automation-engine.md).
-requires: [cli:spur, local-fs]
+  whether my session on <channel> is still valid", "run a browser collection plan",
+  "fix this channel's selectors", or when a spur workflow `agent.run` step targets the
+  web-automation skill. Coordinates with the kk bot session lifecycle and collection
+  substrate. Owns method and evidence; transport stays in kk plugins; orchestration is
+  a @gobing-ai/ts-dual-workflow-engine transition-flow (see docs/design/web-automation-engine.md).
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # web-automation — discover, enhance, automate with a real browser
 
 ## Purpose
 
-Three operations over one method: drive a **real Chromium on the channel's
-cached login profile**, record **evidence** (screenshots, DOM signals, JSON),
+Three operational lenses over one unified browser automation architecture: drive a **real Chromium on the named bot's
+cached login profile**, record **verifiable evidence** (screenshots, DOM signals, JSON responses),
 and never report an outcome that was not observed.
 
-| Operation | When | Output |
-| --- | --- | --- |
-| **discover** | new/changed site; "figure out this UI" | evidence dir + drift list (`docs/design/<channel>-ui-discovery.md` convention) |
-| **enhance** | selectors/signals drifted; a plugin or workflow fails on a live console | fixed selectors/signals in the owning plugin + updated discovery doc, same commit |
-| **automate** | a repeatable web task (login-gated save/draft/fill/read) | workflow-driven run with per-step Result/evidence; draft-safe by default |
+| Operation | When | Tier & Substrate | Output |
+| --- | --- | --- | --- |
+| **discover** | New/changed site; "figure out this UI", inspect selectors/shadow roots | **Tier 3** (`kk bot open` + CDP/Playwright) | Evidence dir (`frames/`, `signals.json`) + drift list (`docs/design/<channel>-ui-discovery.md`) |
+| **enhance** | Selectors drifted; a plugin or collection plan fails on a live console | **Tier 2 / 3** (`kk bot exec`, probe script) | Root-cause fix in plugin + updated discovery doc in same commit |
+| **automate** | Repeatable web task (data collection, form fill, draft save, health audit) | **Tier 1 / 2** (`kk bot exec`, `runBotCollection`) | Bounded Result + captured artifacts (draft-safe by default, fail-closed) |
 
-This skill owns **method**. It does not own transport (that is the
-`kind: publish`/`ingestion` plugins) or orchestration (that is the engine —
-`spur workflow` runs `@gobing-ai/ts-dual-workflow-engine`; see
-`docs/design/web-automation-engine.md` for the layering and the YAML).
+This skill owns **method**. It does not own transport (that belongs to `kind: publish` / `ingestion` plugins) or orchestration
+(that is the engine — `spur workflow` running `@gobing-ai/ts-dual-workflow-engine`; see `docs/design/web-automation-engine.md`).
 
-## Cached login (`auth: cached` — the default)
+---
+
+## The 3-Tier Web Automation Model
+
+To keep workflows clean, safe, and robust against anti-bot friction, all web automation tasks follow a strict 3-tier hierarchy:
+
+```text
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Tier 1: Session & Probe Gateway (kk bot CLI)                                  │
+│   • Profile inventory & expiry estimates: kk bot list                        │
+│   • Headed login & transactional staging:  kk bot login <channel>            │
+│   • Single-request authenticated queries:  kk bot exec <name> <url>          │
+│   • Local credential wipe:                 kk bot logout <name>              │
+└──────────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Tier 2: Declarative Headless Automation (kk bot plan / bot-collection)       │
+│   • Canonical CLI runner: kk bot plan <bot> <plan.json> [-o <dir>] [-m <sec>]│
+│   • Bounded multi-step JSON plans (navigate, wait, click, scroll, extract)   │
+│   • Declarative network response captures (responses: [{pathPrefix}])        │
+│   • Single profile lease + single headless context launch                    │
+│   • Fail-closed errors: authentication (auth walls) vs empty vs browser      │
+│   • Programmatic runner: runBotCollection in @gobing-ai/publish-harness      │
+│   • Low-level probe tool: bun packages/publish-harness/scripts/bot-collection-probe.ts │
+└──────────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Tier 3: Deep Interactive Automation (Playwright / CDP under withProfileLease)│
+│   • Headed visual inspection & interaction: kk bot open <name> [--login]     │
+│   • File uploads (setInputFiles) & shadow-root coordinate clicks via CDP     │
+│   • Live DOM accessibility dumps & interactive selector reverse-engineering  │
+│   • Strict lease enforcement: withProfileLease prevents concurrent corruption │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Tier 1: Session & Profile Lifecycle (`kk bot`)
+
+All browser sessions live under the fixed default root:
+
+```text
+~/.config/kk/browser-profiles/<name>       # persistent profiles (xhs, infoq, juejin, substack, x, wechatmp, etc.)
+~/.config/kk/browser-transactions/         # crash-safe staging and atomic promotion for logins
+~/.config/kk/browser-leases/               # shared lease locks preventing concurrent profile corruption
+```
+
+### CLI Command Reference
 
-Login state is cached **per channel** as a persistent Playwright profile dir —
-cookies, localStorage, and session live on disk outside git:
+| Command | Purpose | Input / Options | Behavior |
+| --- | --- | --- | --- |
+| `kk bot list` | Inventory | None | Prints tab-separated columns: `name`, `cached`, `defaultUrl`, `identity`, `lastLogin`, `expires`. Browser-free. |
+| `kk bot login <channel>` / `<url> --save <name>` | Fresh authentication | Channel name or URL (`--save <name>`) | Opens headed in isolated staging; saves adapter-verified evidence or waits for operator confirmation; promotes atomically. |
+| `kk bot open <name> [--login]` | Inspection | Bot name (`--login` optional) | Opens saved default URL headed until operator closes browser. `--login` re-authenticates first. |
+| `kk bot logout <name>` | Wipe credentials | Bot name | Deletes local profile directory behind shared lease. Idempotent. |
+| `kk bot exec <name> <url> [opts]` | Authenticated HTTP | `-X`, `-H`, `-d`, `-o`, `-i`, `-L`, `-f`, `-m` | One headless persistent launch; sends request with profile's cached cookies; writes body as raw bytes. |
+| `kk bot plan <name> <plan.json> [opts]` | Declarative Collection | `-o, --output <dir>`, `-m, --max-time <sec>` | Headless persistent launch under shared lease; runs declarative plan steps and captures; writes artifacts or prints JSON result. |
 
+### Session Preflight & Health Check
+
+Before triggering automated runs, perform a fast probe. Age-guessing timestamps is banned — probe, don't predict:
+
+```bash
+# 1. Check local profile inventory
+kk bot list
+
+# 2. Lightweight authenticated query probe (returns status + headers)
+kk bot exec <channel> <console-url> -i -m 15 -o /tmp/probe.txt
+
+# 3. If expired or unauthenticated (HTTP 401/403 or redirect to login):
+kk bot login <channel>
 ```
-~/.config/kk/browser-profiles/<channel>   # xhs, infoq, juejin, substack, x, wechatmp
+
+---
+
+## Tier 2: Declarative Headless Automation (`bot-collection`)
+
+For data collection, scraping, site audits, and structured form workflows, **do not write ad-hoc Playwright scripts**.
+Use the declarative `@gobing-ai/publish-harness/bot-collection` substrate:
+
+```ts
+import { runBotCollection } from '@gobing-ai/publish-harness/bot-collection';
+
+const result = await runBotCollection('wechatmp', {
+    steps: [
+        { id: 'nav-home', kind: 'navigate', url: 'https://mp.weixin.qq.com/' },
+        { id: 'wait-dashboard', kind: 'wait', selector: '.weui-desktop-layout', timeoutMs: 15_000 },
+        { id: 'extract-stats', kind: 'extract', selector: '.weui-desktop-mass__item', format: 'text' },
+    ],
+    responses: [
+        { id: 'appmsg-list', pathPrefix: '/cgi-bin/appmsg' },
+    ],
+    timeoutMs: 30_000,
+});
 ```
 
-| `auth` | Behavior |
-| --- | --- |
-| `cached` (default) | Preflight the profile; reuse it read-only. Launch with `launchPersistentContext` (see `references/browser-launch.md`). No credentials are typed, read, or stored by any script. |
-| `fresh` | Profile missing/expired → **headed** launch, operator completes login by hand (QR/OAuth/password), then the profile is the cache again. Never auto-type credentials; OAuth gates need the stealth args. |
+### Plan Grammar (`BotCollectionPlan`)
+
+A plan is a frozen JSON object with `steps[]`, optional `responses[]` captures, and an optional whole-run `timeoutMs`:
+
+- **`navigate`**: `{ id, kind: 'navigate', url, waitUntil?: 'load'|'domcontentloaded'|'networkidle'|'commit' }`
+- **`wait`**: `{ id, kind: 'wait', selector?, timeoutMs? }`
+- **`click`**: `{ id, kind: 'click', selector, timeoutMs? }`
+- **`scroll`**: `{ id, kind: 'scroll', deltaY, selector?, timeoutMs? }`
+- **`extract`**: `{ id, kind: 'extract', selector, format: 'text'|'html'|'count', timeoutMs? }`
+- **`request`**: `{ id, kind: 'request', url, method?: 'GET'|'POST', headers?, data? }`
+- **`responses`**: `[{ id, origin?, pathPrefix, optional?: boolean }]`
 
-Preflight before any drive — cheap and headless:
+### Fail-Closed Integrity Rules
+
+- **`authentication`**: Fails immediately when an explicit 401/403 occurs on a request, navigation, or required response, or when the final navigation URL path matches `/login|signin|sign-in|auth|sso/i`. Action: alert operator to run `kk bot login <channel>`.
+- **`empty`**: Fails immediately when a declared non-optional capture receives no response, or an `extract`/`request` step yields an empty body. Prevents client-side rendered SPA shells from masquerading as a successful quiet run.
+- **`browser`**: Transport faults, timeouts, navigation drops, and DOM exceptions.
+
+### Running Plans via CLI (`kk bot plan`)
+
+Execute a collection plan directly from the terminal or a workflow script:
+
+```bash
+# Run plan and stream JSON result to stdout
+kk bot plan <channel> <path/to/plan.json> -m 60
+
+# Run plan and write 0600 artifact files + result.json / error.json into output dir
+kk bot plan <channel> <path/to/plan.json> -o <path/to/evidence-dir> -m 60
+```
+
+Exit codes: `0` = success, `1` = operational failure (`authentication`, `empty`, or `browser`), `2` = usage error (invalid JSON, missing profile, invalid timeout).
+
+Low-level debugging can also use the repository probe script:
 
 ```bash
-test -d ~/.config/kk/browser-profiles/<channel> && echo cached || echo fresh-required
+bun packages/publish-harness/scripts/bot-collection-probe.ts \
+  --profile <name> \
+  --plan <path/to/plan.json> \
+  --out <path/to/evidence-dir>
 ```
 
-A profile dir existing is necessary, not sufficient: before `automate` runs,
-do a read-only session probe (open the console URL, check a signed-in-only
-selector) and route to `fresh` on failure. Age-guessing timestamps is banned —
-probe, don't predict.
-
-## Method
-
-1. **Launch** — `chromium.launchPersistentContext(profileDir, { headless, args: [CDP port, stealth] })`.
-   Decision table and the exact snippet: `references/browser-launch.md`.
-2. **Discover** — screenshot first, then read DOM (selectors, shadow roots,
-   iframes, counts) with small throwaway scripts; save frames + a signals JSON
-   into the run's evidence dir; write/refresh the channel's
-   `docs/design/<channel>-ui-discovery.md` (selectors, drift list, date).
-3. **Enhance** — diff observed DOM against the plugin's encoded
-   selectors/signals; fix the plugin (root cause — one shared helper, not
-   every caller), re-walk to prove it, update the discovery doc in the same
-   commit.
-4. **Automate** — encode the flow as engine workflow nodes (preflight →
-   launch → drive → verify → record); `drive` steps run the measured
-   selectors and **assert an observed outcome signal** (toast, counter delta,
-   URL change). An unobserved outcome is reported as failure, never success.
-5. **Confidence-verified verdicts** — every outcome verdict carries
-   `confidence: HIGH | MEDIUM | LOW` (HIGH = measured signal observed;
-   MEDIUM = indirect signal, e.g. counter delta without toast; LOW = partial
-   evidence, one check passed). **Missing or out-of-enum confidence is itself
-   a failure** — the verify gate blocks it, mirroring the safety-verdict
-   convention (`kk-daily-ai-voice.md`, 20261003).
-
-## Safety rails (non-negotiable)
-
-- **Never click publish/send/submit/delete** unless the task explicitly
-  authorizes live publishing. Default target: draft/save/暂存.
-- Bot-walled channels (xhs) and fresh logins stay **headed**; headless only
-  after the session is proven.
-- Every reported success cites observed evidence (signal, screenshot, JSON).
-  No evidence → it is a failure with the reason — and every verdict states
-  its `HIGH | MEDIUM | LOW` confidence; a verdict without a valid level
-  fails the gate like a missing verdict.
-- Secrets stay out of repo, YAML, and vars. Login state lives only in the
-  profile dir under `~/.config` (outside git); scripts print paths, never tokens.
-- One browser per channel/profile at a time; close contexts you launched.
-
-## Engine invocation (summary)
-
-Orchestration is a `kind: transition-flow` workflow; `startable` nodes let a
-run re-enter at `drive` after a manual login without redoing earlier nodes.
-Full YAML, node contract, and the option-B (in-process runners) design:
-`docs/design/web-automation-engine.md`.
+---
+
+## Tier 3: Deep Interactive Automation (Playwright / CDP)
+
+When an activity requires capabilities outside Tier 2 — specifically:
+1. **Interactive UI discovery** (navigating unknown layouts, recording screenshots).
+2. **Shadow-root component piercing** (e.g. XHS creator console shadow boundaries).
+3. **File uploads** (attaching images/videos via `page.setInputFiles`).
+4. **Canvas / complex coordinate dragging**.
+
+You MUST wrap the run inside the shared profile lease to prevent profile corruption:
+
+```ts
+import { chromium } from 'playwright';
+import { withProfileLease } from '@gobing-ai/publish-harness';
+
+const profileName = 'xhs';
+const profileDir = `${process.env.HOME}/.config/kk/browser-profiles/${profileName}`;
+const port = process.env.KK_WEB_CDP ?? '9222';
+
+await withProfileLease(profileName, async () => {
+    const ctx = await chromium.launchPersistentContext(profileDir, {
+        headless: process.env.KK_WEB_HEADLESS === 'true',
+        viewport: null,
+        args: [
+            `--remote-debugging-port=${port}`,
+            '--disable-blink-features=AutomationControlled',
+        ],
+    });
+    try {
+        const page = ctx.pages()[0] ?? (await ctx.newPage());
+        // Drive page actions, upload files, or attach agent-browser via CDP...
+    } finally {
+        await ctx.close();
+    }
+});
+```
+
+---
+
+## Playbook: Common Automation Scenarios
+
+### Scenario A: Site Discovery & Reverse-Engineering
+1. Check cached session: `kk bot list`.
+2. Open target page headed: `kk bot open <channel>`.
+3. Inspect DOM, capture layout, dump accessibility tree, take screenshots.
+4. Document selectors, shadow roots, and observed signals into `docs/design/<channel>-ui-discovery.md`.
+5. Close window; `kk bot open` outputs `<name>\tclosed`.
+
+### Scenario B: Lightweight Authenticated Scraping
+1. Send direct authenticated request:
+   ```bash
+   kk bot exec <channel> "https://target.com/api/data" -H "Accept: application/json" -o data.json
+   ```
+2. If the endpoint returns client-rendered HTML shell rather than JSON, escalate to **Scenario C**.
+
+### Scenario C: Declarative Headless Data Collection
+1. Draft a `plan.json` with required navigation, waits, and response captures.
+2. Probe run:
+   ```bash
+   bun packages/publish-harness/scripts/bot-collection-probe.ts --profile <channel> --plan plan.json --out .spur/run/evidence
+   ```
+3. Verify `result.json` shows all artifacts captured with non-empty bodies.
+4. Wire into ingestion plugin or workflow.
+
+### Scenario D: Broken Selector Repair (`enhance`)
+1. Replay failing plan or run `kk bot exec`.
+2. Inspect `error.json` / diagnostics (is it `authentication`, `empty`, or `browser`?).
+3. If selector changed, launch `kk bot open <channel>`, observe the updated DOM element.
+4. Update selector in shared helper, re-verify with probe script, commit alongside discovery doc.
+
+---
+
+## Safety Rails (Non-Negotiable)
+
+- **Draft-Safe by Default**: Never click publish/send/submit/delete unless the task explicitly authorizes live actions.
+- **Lease Invariant**: Every browser context touching `~/.config/kk/browser-profiles/<name>` must be acquired through `kk bot`, `runBotCollection`, or `withProfileLease`. Direct un-leased `launchPersistentContext` is banned.
+- **Fail Closed on Quiet Failures**: Missing data and auth walls must fail loud (`authentication` or `empty`). Never treat an empty SPA shell or an auth redirect as a normal quiet response.
+- **Headed vs Headless**:
+  - Headless: Session probes (`kk bot list`), authenticated queries (`kk bot exec`), declarative collection (`runBotCollection`).
+  - Headed: First-time logins (`kk bot login`), interactive discovery (`kk bot open`), and bot-walled platforms (XHS).
+- **Secrets Invariant**: Zero credentials in repo, code, or logs. All state lives exclusively in `~/.config/kk/` outside Git.
+- **Confidence-Verified Verdicts**: Every workflow outcome verdict must declare `confidence: HIGH | MEDIUM | LOW`. Missing or out-of-enum confidence halts execution.

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.