jdbuyskill 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# jdbuyskill
+
+A Codex skill for running JD.com product monitoring and checkout tasks through a visible browser harness.
+
+This skill is designed for agent-operated browser sessions: Codex performs scheduled checks and page actions step by step, while the user manually handles login, CAPTCHA, SMS verification, risk-control prompts, address blockers, and payment.
+
+## What It Does
+
+- Parses JD product monitoring or checkout requests into a structured task object.
+- Runs stock checks in a visible browser or local Chrome CDP session.
+- Supports aligned polling intervals such as every 5 or 10 minutes.
+- Supports three purchase strategies:
+  - `notify_only`: notify when the product appears available.
+  - `dry_run`: enter checkout and stop before final submit.
+  - `submit_order`: click final submit once, then stop before payment.
+- Uses a strict state-machine protocol for browser actions and status reporting.
+
+## Safety Boundaries
+
+This skill does not support:
+
+- CAPTCHA solving
+- login, SMS, or risk-control bypass
+- bot evasion or stealth browser patches
+- request-header spoofing
+- JD internal API automation
+- unattended background purchasing
+- automatic payment
+
+Protected steps must be handled manually by the user in the visible browser.
+
+## Install From npm
+
+Install globally:
+
+```bash
+npm install -g jdbuyskill
+jdbuyskill install
+```
+
+Or run without a global install:
+
+```bash
+npx jdbuyskill install
+```
+
+Then restart Codex so it can discover the skill.
+
+By default, the installer copies the skill to:
+
+```text
+$CODEX_HOME/skills/jdbuyskill
+```
+
+If `CODEX_HOME` is unset, it installs to:
+
+```text
+~/.codex/skills/jdbuyskill
+```
+
+Use a custom skills directory:
+
+```bash
+jdbuyskill install --dest /path/to/skills
+```
+
+Replace an existing installed copy:
+
+```bash
+jdbuyskill install --force
+```
+
+## Install From GitHub
+
+Clone the repository and symlink it into your Codex skills directory:
+
+```bash
+git clone https://github.com/<owner>/<repo>.git
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+ln -sfn "$(pwd)/<repo>" "${CODEX_HOME:-$HOME/.codex}/skills/jdbuyskill"
+```
+
+Or copy it:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R /path/to/jdbuyskill "${CODEX_HOME:-$HOME/.codex}/skills/jdbuyskill"
+```
+
+Restart Codex after installing.
+
+## Usage
+
+Invoke the skill in Codex:
+
+```text
+Use $jdbuyskill to monitor https://item.jd.com/100012043978.html every 10 minutes and notify me when it is available.
+```
+
+Dry-run checkout:
+
+```text
+Use $jdbuyskill to check this JD item with quantity 2 and go to checkout, but do not submit the order.
+```
+
+Submit once, then stop before payment:
+
+```text
+Use $jdbuyskill to submit the order once if this JD item is available. I will pay manually.
+```
+
+## Local Chrome CDP Mode
+
+For CDP mode, start Chrome with:
+
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/jdbuy-chrome-profile
+```
+
+If that path does not exist on your machine, start Chrome with equivalent `--remote-debugging-port=9222` and `--user-data-dir` flags.
+
+## Project Structure
+
+```text
+jdbuyskill/
+  SKILL.md
+  agents/
+    openai.yaml
+  references/
+    task-schema.md
+    harness-protocol.md
+    examples.md
+  bin/
+    jdbuyskill.mjs
+  package.json
+```
+
+## Publish to npm
+
+Before publishing, update `package.json` if needed:
+
+- Change `name` if `jdbuyskill` is already taken.
+- Change `version` for each release.
+- Set an appropriate license if you want others to reuse the package.
+
+Publish:
+
+```bash
+npm login
+npm whoami
+npm publish --access public
+```
+
+Preview published files:
+
+```bash
+npm pack --dry-run
+```
+
+If your local npm cache has permission issues, use a temporary cache:
+
+```bash
+npm --cache /tmp/npm-cache-jdbuyskill pack --dry-run
+```
+
+## Publish to GitHub
+
+Initialize and push:
+
+```bash
+git init
+git add .
+git commit -m "Add jdbuyskill"
+git branch -M main
+git remote add origin https://github.com/<owner>/<repo>.git
+git push -u origin main
+```
+
+## License
+
+The npm package currently uses `UNLICENSED` in `package.json`. Add a `LICENSE` file and update `package.json` before publishing if you want to distribute it under an open-source license such as MIT.

package/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: jdbuyskill
+description: Use when a user asks Codex to run a JD.com product monitoring, availability check, cart, or checkout task in a visible browser with a product URL, quantity, purchase strategy, local CDP browser, or aligned polling interval. Do not use for CAPTCHA solving, risk-control bypass, bot evasion, stealth automation, internal API automation, or payment verification.
+---
+
+# JD Buy Harness Runbook
+
+Operate JD.com purchase tasks as a visible-browser harness. Codex performs each check and browser action itself under the protocol; do not generate a long-running automation program, cron job, daemon, or request-level bot.
+
+## Required References
+
+Read these before acting:
+
+1. `references/task-schema.md` for task parsing and validation.
+2. `references/harness-protocol.md` for allowed states, transitions, page signals, and evidence rules.
+3. `references/examples.md` when the user request is ambiguous or you need parsing examples.
+
+## Operating Rules
+
+- Keep exactly one current protocol state from `references/harness-protocol.md`.
+- Report every state transition with the format in `Status Format`.
+- Run the first stock check immediately; only repeat checks at aligned wall-clock boundaries.
+- Default to `dry_run` unless the user explicitly requests `submit_order`.
+- Pause for manual login, CAPTCHA, SMS, risk-control, address blockers, and payment prompts.
+- Stop before payment. For `submit_order`, click final submit at most once, then stop.
+- Do not continue from an unexpected page by guessing. Capture evidence and ask the user.
+
+## Refuse Or Narrow
+
+Refuse only the unsafe part when possible. Offer a compliant alternative such as `notify_only`, `dry_run`, screenshots, HTML snapshots, slower aligned checks, or pausing for manual intervention.
+
+Reject requests to:
+
+- bypass CAPTCHA, login, SMS, risk control, bot detection, or payment confirmation
+- spoof headers, patch browser stealth signals, or use internal JD APIs
+- run unattended background purchasing or automatic payment
+- disable manual intervention for protected steps
+
+## Task Setup
+
+Build an in-memory task object before opening the browser:
+
+- `product_url`: JD product detail URL.
+- `quantity`: purchase quantity, default `1`.
+- `purchase_strategy`: `notify_only`, `dry_run`, or `submit_order`; default `dry_run`.
+- `poll_aligned_minutes`: default `5`.
+- `max_attempts`: default `0`, meaning no fixed cap while the session remains active.
+- `browser.mode`: `cdp` or `visible`; prefer `cdp` only when a local endpoint is available.
+
+If any required or safety-relevant field is ambiguous, show the interpreted task object and ask for confirmation before continuing.
+
+For CDP mode, ask the user to start Chrome when no endpoint is available:
+
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/jdbuy-chrome-profile
+```
+
+Connect to `http://127.0.0.1:9222` with the available browser-control tool. If connection fails, stop and ask the user to restart Chrome with the command above.
+
+## Execution Loop
+
+Run exactly this high-level loop:
+
+1. Open the product URL.
+2. Run one immediate stock check.··
+3. If unavailable, wait until the next aligned wall-clock boundary.
+4. Repeat checks only on aligned boundaries.
+5. If available, apply `purchase_strategy`.
+6. If manual login, CAPTCHA, SMS, or risk prompt appears, pause and ask the user to handle it.
+7. If `dry_run`, stop before final order submission.
+8. If `submit_order`, click submit order once, then stop for manual payment.
+
+## Status Format
+
+At every state transition, report one short block:
+
+```text
+state: <STATE>
+page: <current URL or page label>
+signal: <visible button/text/challenge/checkout marker>
+next: <next action or next scheduled check time>
+```
+
+## Stop Conditions
+
+Stop immediately when:
+
+- the protocol reaches `STOPPED`
+- the page requires phone-only purchase
+- browser control or CDP connection is unavailable
+- the user must handle login, CAPTCHA, SMS, risk control, address selection, or payment
+- the task violates the safety boundary
+- evidence is insufficient to classify the page state
+
+When stopped, summarize the last state, last observed signal, and what user action is needed next.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "JD Buy Harness"
+  short_description: "Run visible-browser JD checkout tasks"
+  default_prompt: "Use $jdbuyskill to run a JD visible-browser product monitoring or checkout task."

package/bin/jdbuyskill.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, "..");
+const skillName = "jdbuyskill";
+
+function usage() {
+  console.log(`Usage:
+  jdbuyskill install [--dest <skills-dir>] [--force]
+  jdbuyskill --help
+
+Installs ${skillName} into:
+  $CODEX_HOME/skills/${skillName}
+or, when CODEX_HOME is unset:
+  ~/.codex/skills/${skillName}
+
+Options:
+  --dest <dir>  Install into a custom skills directory.
+  --force       Replace an existing installed copy.
+`);
+}
+
+function defaultSkillsDir() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "skills");
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const command = args[0] && !args[0].startsWith("-") ? args.shift() : "install";
+  const options = {
+    command,
+    dest: defaultSkillsDir(),
+    force: false
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      options.command = "help";
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "--dest") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("--dest requires a directory path");
+      }
+      options.dest = resolve(value);
+      i += 1;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function copySkill(destDir, force) {
+  const installDir = join(destDir, skillName);
+  const entries = ["SKILL.md", "agents", "references"];
+
+  for (const entry of entries) {
+    const source = join(packageRoot, entry);
+    if (!existsSync(source)) {
+      throw new Error(`Package is missing required skill file: ${entry}`);
+    }
+  }
+
+  if (existsSync(installDir)) {
+    if (!force) {
+      throw new Error(`${installDir} already exists. Re-run with --force to replace it.`);
+    }
+    rmSync(installDir, { recursive: true, force: true });
+  }
+
+  mkdirSync(installDir, { recursive: true });
+  for (const entry of entries) {
+    cpSync(join(packageRoot, entry), join(installDir, entry), { recursive: true });
+  }
+
+  console.log(`Installed ${skillName} to ${installDir}`);
+  console.log("Restart Codex to pick up the skill.");
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.command === "help") {
+    usage();
+  } else if (options.command === "install") {
+    copySkill(options.dest, options.force);
+  } else {
+    throw new Error(`Unknown command: ${options.command}`);
+  }
+} catch (error) {
+  console.error(`jdbuyskill: ${error.message}`);
+  console.error("Run `jdbuyskill --help` for usage.");
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "jdbuyskill",
+  "version": "0.1.0",
+  "description": "Codex skill for visible-browser JD.com product monitoring and checkout harness tasks.",
+  "type": "module",
+  "bin": {
+    "jdbuyskill": "bin/jdbuyskill.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "agents/",
+    "references/",
+    "bin/jdbuyskill.mjs"
+  ],
+  "scripts": {
+    "install-skill": "node bin/jdbuyskill.mjs install",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "codex",
+    "skill",
+    "jd",
+    "browser",
+    "harness"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/references/examples.md

@@ -0,0 +1,59 @@
+# JD Buy Harness Examples
+
+Use these examples to parse user requests into task objects. They are examples only; still validate the live request against `task-schema.md`.
+
+## Notify Only
+
+User: "Monitor this JD item every 10 minutes and tell me when it is available: https://item.jd.com/100012043978.html"
+
+```json
+{
+  "product_url": "https://item.jd.com/100012043978.html",
+  "quantity": 1,
+  "purchase_strategy": "notify_only",
+  "poll_aligned_minutes": 10,
+  "max_attempts": 0,
+  "browser": {
+    "mode": "cdp",
+    "cdp_endpoint": "http://127.0.0.1:9222"
+  },
+  "manual_intervention": {
+    "login": true,
+    "captcha": true,
+    "sms": true,
+    "risk_control": true,
+    "address": true,
+    "payment": true
+  }
+}
+```
+
+## Dry Run Checkout
+
+User: "Use visible Chrome to check this item now, quantity 2, and go as far as checkout but don't submit."
+
+Set `purchase_strategy` to `dry_run` and `quantity` to `2`. If the URL is missing, ask for it before opening the browser.
+
+## Submit Once
+
+User: "If this JD item is available, submit the order once. I will pay manually."
+
+Set `purchase_strategy` to `submit_order` only if the user provided a valid JD product URL or confirms the parsed URL. Stop immediately after one final submit click.
+
+## Ambiguous Automatic Request
+
+User: "Automatically buy this when it drops."
+
+Ask whether they mean:
+
+- `notify_only`: notify on availability
+- `dry_run`: reach checkout and stop before submit
+- `submit_order`: submit once, then stop before payment
+
+Do not create unattended background automation.
+
+## Unsafe Request
+
+User: "Bypass CAPTCHA and use headers so JD thinks this is a normal browser."
+
+Refuse the bypass/header-spoofing portion. Offer visible-browser monitoring with manual CAPTCHA handling, slower aligned checks, screenshots, or `notify_only`.

package/references/harness-protocol.md

@@ -0,0 +1,155 @@
+# JD Buy Harness Protocol
+
+The agent must operate the task as a strict state machine. At any time, the task is in exactly one state.
+
+## States
+
+1. `TASK_PARSED`
+2. `BROWSER_READY`
+3. `PRODUCT_OPENED`
+4. `CHECKING_STOCK`
+5. `WAITING_FOR_BOUNDARY`
+6. `MANUAL_INTERVENTION`
+7. `AVAILABLE_FOUND`
+8. `CHECKOUT_STARTED`
+9. `DRY_RUN_STOP`
+10. `ORDER_SUBMITTED`
+11. `STOPPED`
+
+## Allowed Transitions
+
+- `TASK_PARSED -> BROWSER_READY`
+- `BROWSER_READY -> PRODUCT_OPENED`
+- `PRODUCT_OPENED -> CHECKING_STOCK`
+- `CHECKING_STOCK -> AVAILABLE_FOUND`
+- `CHECKING_STOCK -> WAITING_FOR_BOUNDARY`
+- `CHECKING_STOCK -> MANUAL_INTERVENTION`
+- `WAITING_FOR_BOUNDARY -> PRODUCT_OPENED`
+- `MANUAL_INTERVENTION -> PRODUCT_OPENED`
+- `AVAILABLE_FOUND -> STOPPED` for `notify_only`
+- `AVAILABLE_FOUND -> CHECKOUT_STARTED` for `dry_run` or `submit_order`
+- `CHECKOUT_STARTED -> DRY_RUN_STOP` for `dry_run`
+- `CHECKOUT_STARTED -> ORDER_SUBMITTED` for `submit_order`
+- `DRY_RUN_STOP -> STOPPED`
+- `ORDER_SUBMITTED -> STOPPED`
+
+Any other transition is a protocol violation.
+
+## State Duties
+
+| State | Duties | Exit condition |
+| --- | --- | --- |
+| `TASK_PARSED` | Validate the task object and safety boundary. | Browser tool or CDP endpoint is ready. |
+| `BROWSER_READY` | Confirm visible browser control works. | Product URL can be opened. |
+| `PRODUCT_OPENED` | Load or reload the product page at an allowed check time. | Primary product area is inspectable. |
+| `CHECKING_STOCK` | Classify availability from visible primary controls. | Available, unavailable, or intervention signal is observed. |
+| `WAITING_FOR_BOUNDARY` | Wait without refreshing or clicking. | Next aligned wall-clock boundary arrives. |
+| `MANUAL_INTERVENTION` | Ask the user to handle a protected prompt. | User confirms the browser is ready to continue. |
+| `AVAILABLE_FOUND` | Report evidence and apply strategy. | Stop for notify-only or enter checkout. |
+| `CHECKOUT_STARTED` | Confirm checkout page marker and strategy stop point. | Stop before submit or submit once. |
+| `DRY_RUN_STOP` | Report that final submit was not clicked. | Stop. |
+| `ORDER_SUBMITTED` | Report that final submit was clicked once. | Stop for manual payment. |
+| `STOPPED` | No further page actions. | None. |
+
+## Stock Signals
+
+Treat the product as available when the primary product area shows a visible, enabled purchase button:
+
+- `立即购买`
+- `加入购物车`
+
+Treat the product as unavailable when the primary product area shows:
+
+- `无货`
+- `暂无货`
+- `到货通知`
+- `商品已售完`
+- disabled purchase controls
+
+If both available and unavailable words appear, prefer the visible enabled primary purchase button over page-wide text. Page-wide text may include unrelated recommendations.
+
+If the page says `前往手机购买`, `手机购买`, or `仅支持手机`, stop or ask the user whether to switch to manual phone purchase. Do not claim desktop checkout is possible.
+
+Do not treat recommendation cards, ads, search results, or page-wide text outside the primary product area as product availability.
+
+## Boundary Timing
+
+Run the first check immediately.
+
+For subsequent checks, compute the next wall-clock boundary:
+
+- `poll_aligned_minutes = 5`: `00/05/10/15/...`
+- `poll_aligned_minutes = 10`: `00/10/20/30/...`
+
+When waiting:
+
+1. Report the next check time.
+2. Do not refresh or click during the wait.
+3. Resume only at the boundary unless the user interrupts.
+
+If `max_attempts > 0`, count each `CHECKING_STOCK` entry as one attempt. Stop after the final unavailable check and summarize the last evidence.
+
+## Checkout Rules
+
+Before checkout:
+
+- Confirm current state is `AVAILABLE_FOUND`.
+- Set quantity if the visible page supports it.
+- Prefer `立即购买` over `加入购物车`.
+
+After clicking checkout:
+
+- Confirm a checkout marker such as `提交订单`, `收货地址`, or `填写并核对订单信息`.
+- Use JD's current default address. Do not force address selection unless the user explicitly requests it.
+- For `dry_run`, stop before clicking final submit.
+- For `submit_order`, click final submit once, then stop for manual payment.
+
+If quantity cannot be set visibly, report the observed quantity control state and ask the user whether to continue with the current quantity.
+
+## Manual Intervention
+
+Enter `MANUAL_INTERVENTION` when observing:
+
+- login prompt
+- CAPTCHA
+- SMS verification
+- security/risk prompt
+- address selection blocker
+- payment prompt
+- unknown checkout blocker
+
+Ask the user to handle it in the visible browser, then continue only after the user confirms.
+
+## Browser And Page Failures
+
+Stop and report evidence when:
+
+- browser control disconnects or the CDP endpoint is unavailable
+- the product page fails to load after a normal retry
+- the page is not a JD product page after navigation
+- the visible page language or layout prevents identifying the primary product controls
+- the checkout page lacks a clear checkout marker after a click
+
+Do not compensate by using JD internal APIs, direct HTTP requests, header spoofing, or stealth browser patches.
+
+## Evidence
+
+When a page state is unexpected, capture or request:
+
+- screenshot
+- current URL
+- visible text around the relevant control
+- if available, page HTML or accessibility tree snippet
+
+Do not continue by guessing.
+
+## Status Report Contract
+
+Every transition report must include:
+
+- state
+- current URL or page label
+- observed signal
+- next action or scheduled check time
+
+Keep the report factual. Do not claim purchase success after `ORDER_SUBMITTED`; payment and final merchant confirmation are outside this harness.

package/references/task-schema.md

@@ -0,0 +1,81 @@
+# JD Buy Harness Task Schema
+
+Use this schema as the in-memory task object for the agent-run harness. It is not a Python application config.
+
+```json
+{
+  "product_url": "https://item.jd.com/100012043978.html",
+  "quantity": 1,
+  "purchase_strategy": "dry_run",
+  "poll_aligned_minutes": 5,
+  "max_attempts": 0,
+  "browser": {
+    "mode": "cdp",
+    "cdp_endpoint": "http://127.0.0.1:9222"
+  },
+  "manual_intervention": {
+    "login": true,
+    "captcha": true,
+    "sms": true,
+    "risk_control": true,
+    "address": true,
+    "payment": true
+  }
+}
+```
+
+## Defaults
+
+Use these defaults when the user does not specify a value:
+
+| Field | Default |
+| --- | --- |
+| `quantity` | `1` |
+| `purchase_strategy` | `dry_run` |
+| `poll_aligned_minutes` | `5` |
+| `max_attempts` | `0` |
+| `browser.mode` | `cdp` when a local endpoint is available, otherwise `visible` |
+| `browser.cdp_endpoint` | `http://127.0.0.1:9222` |
+| `manual_intervention.*` | `true` |
+
+## Field Rules
+
+- `product_url`: required `item.jd.com` or `re.jd.com` URL.
+- `quantity`: integer, at least `1`.
+- `purchase_strategy`: one of `notify_only`, `dry_run`, or `submit_order`.
+- `poll_aligned_minutes`: integer that divides 60; commonly `5` or `10`.
+- `max_attempts`: integer at least `0`; `0` means no fixed cap while the agent session remains active.
+- `browser.mode`: `cdp` for a user-started Chrome endpoint, or `visible` for another available visible browser tool.
+- `manual_intervention`: all entries must remain `true`; do not automate login, CAPTCHA, SMS, risk control, address blockers, or payment.
+
+## Purchase Strategies
+
+| Strategy | Allowed behavior | Stop point |
+| --- | --- | --- |
+| `notify_only` | Monitor and notify when the product appears available. | Stop at `AVAILABLE_FOUND`. |
+| `dry_run` | Start checkout to verify the path. | Stop before clicking final submit order. |
+| `submit_order` | Click final submit order once. | Stop immediately after submit; payment remains manual. |
+
+## Validation Rules
+
+Reject the task before browser actions when:
+
+- `product_url` is missing or is not a JD product URL.
+- `quantity < 1` or quantity is not an integer.
+- `purchase_strategy` is outside `notify_only`, `dry_run`, or `submit_order`.
+- `poll_aligned_minutes` does not divide 60.
+- `max_attempts < 0`.
+- the user asks to disable manual intervention for login, CAPTCHA, SMS, risk control, address blockers, or payment.
+- the user requests bypass, stealth, header spoofing, internal API automation, unattended background purchase, or automatic payment.
+
+## Ambiguity Handling
+
+Ask for confirmation before acting when:
+
+- the URL is a JD search, campaign, or cart page rather than an item page.
+- the user says "buy" but does not specify whether final submit is allowed.
+- the user asks for "automatic" behavior that could mean either aligned agent checks or unattended code automation.
+- the requested polling interval is expressed informally and cannot be converted to a divisor of 60.
+- the browser mode is requested but the corresponding tool or CDP endpoint is unavailable.
+
+When asking, show the parsed task object and state which fields need confirmation.