yaohao 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chaos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# yaohao
+
+[![npm version](https://img.shields.io/npm/v/yaohao.svg)](https://www.npmjs.com/package/yaohao)
+[![npm downloads](https://img.shields.io/npm/dm/yaohao.svg)](https://www.npmjs.com/package/yaohao)
+[![CI](https://github.com/GuangyuZhan/yaohao/actions/workflows/ci.yml/badge.svg)](https://github.com/GuangyuZhan/yaohao/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/node/v/yaohao.svg)](https://nodejs.org/)
+
+国内城市车牌摇号 CLI 工具 —— 让人类和 AI Agent 都能在终端做资格自检、查询摇号形势、订阅开奖结果与政策变化。
+
+支持城市：**北京** · **广州** · **深圳** · **杭州**
+
+> ⚠️ **不保证持续可用**：本工具依赖各城官方公告页结构，官网改版可能导致部分功能失效。Issue 跟踪修复，无 SLA 承诺。
+
+## 安装
+
+```bash
+npm install -g yaohao
+```
+
+要求 Node.js >= 20。
+
+## 快速开始
+
+```bash
+# 1. 初始化（交互式选默认城市 / 指标类型 / 申请人类型）
+yaohao init
+
+# 2. 看本年关键日历（窗口期、摇号日）
+yaohao calendar                    # 默认城市
+yaohao calendar --city shenzhen    # 指定城市
+
+# 3. 自己能不能摇号
+yaohao eligibility --city beijing
+
+# 4. 当期形势
+yaohao market --city guangzhou
+
+# 5. 订阅开奖 + 政策推送
+yaohao notify add bark://your-bark-key
+yaohao watch result --city beijing    # 首次记录历史，下次起检测新增
+yaohao cron setup                     # 写 crontab，默认每天 9:00 检查
+```
+
+## 城市能力矩阵
+
+| 命令 | 北京 | 广州 | 深圳 | 杭州 |
+|---|---|---|---|---|
+| `calendar` 关键日历 | ✅ | ✅ | ✅ | ✅ |
+| `eligibility` 资格自检 | ✅ | ✅ | ✅ | ✅ |
+| `market` 形势播报 | ✅ 含 PDF 中签率 | ✅ HTML 字段 | ✅ HTML 字段 | ✅ HTML 字段 |
+| `watch result` 开奖订阅 | ✅ | ✅ | ✅ | ✅ |
+| `watch policy` 政策订阅 | ✅ | ✅ | ✅ | ✅ |
+| `watch window` 窗口期订阅 | ✅ | ✅ | ✅ | ✅ |
+
+各城节奏差异：
+
+| 城市 | 申请窗口 | 摇号日 |
+|---|---|---|
+| 北京 | 每年 1/1-3/8、8/1-10/8 | 4 月、12 月 |
+| 广州 | 每月 12 日截止 | 每月 25 日 |
+| 深圳 | 每月 8 日截止（9 日入次月） | 每月 26 日 |
+| 杭州 | 每月 1-8 日申报 | 每月 26 日 + 阶梯摇号年度专场 |
+
+## 命令参考
+
+### 全局选项
+
+所有命令支持 `--city <beijing|guangzhou|shenzhen|hangzhou>`，缺省走 `yaohao init` 设置的默认城市。
+
+### `calendar` 关键日历
+
+```bash
+yaohao calendar [--city <city>] [--year <year>]
+```
+
+输出：当前及未来几个月的关键日期（申请截止 / 资格审核 / 摇号日）+ 距离今天的天数。
+
+### `eligibility` 资格自检
+
+```bash
+yaohao eligibility [--city <city>]
+```
+
+交互式问答：户籍类型 → 年龄 → 驾照 → 名下车牌 → 现有指标 → 社保（非户籍）→ 家庭/阶梯/人才（按城市差异）。
+
+输出：能不能摇号、能摇哪类（普通/新能源/混合动力/家庭等）。
+
+### `market` 形势播报
+
+```bash
+yaohao market [--city <city>] [--no-pdf] [--no-cache] [--json]
+```
+
+输出：当期申请人数、配置数量、中签率（北京含 PDF 解析的精确数字）、相关公告链接。
+
+### `watch` 订阅
+
+```bash
+yaohao watch result   [--city <city>] [--no-notify] [--no-cache] [--json]   # 开奖结果
+yaohao watch policy   [--city <city>]                                        # 政策变化
+yaohao watch window   [--city <city>]                                        # 申请窗口/资格审核
+```
+
+首次运行只记录当前历史不推送；后续运行检测新增并通过通知渠道推送。
+
+### `init` / `set` / `notify` / `cron`
+
+```bash
+yaohao init                                # 交互式初始化
+yaohao init --city beijing --reg-type PTC --apply-type person --notify <url>
+
+yaohao set default-city <city>             # 改默认城市
+yaohao set reg-type <PTC|XNY>              # 改指标类型
+yaohao set apply-type <person|family>      # 改申请人类型
+
+yaohao notify add <url>                    # 添加通知渠道
+yaohao notify remove <url>
+yaohao notify test
+
+yaohao cron setup [--schedule '0 9 * * *'] # 一键写 crontab
+yaohao cron status
+yaohao cron remove
+```
+
+通知 URL 兼容 [Apprise](https://github.com/caronc/apprise) 格式，支持 Bark / Telegram / 钉钉 / 企微 / 飞书 / Slack / Webhook。
+
+## v1 不支持
+
+以下命令在 v1 不实现（出于隐私和合规考虑，工具不持有用户密码）：
+
+| 命令 | 提示 |
+|---|---|
+| `status` / `family` / `result` / `history` / `waitlist` | 本人账号查询请直接登录各城官网 |
+| `watch renewal` / `watch expiry` / `watch ranking` | 同上 |
+
+## 配置
+
+存储在 `~/.yaohao/config.json`，`yaohao init` 自动创建。缓存在 `~/.yaohao/cache/`。
+
+## AI Agent
+
+Skill 文件位于 `skills/yaohao/SKILL.md`，触发关键词包括：摇号、指标、申请编码、家庭摇号、新能源指标、阶梯、中签、北京/广州/深圳/杭州买车等。
+
+```bash
+npx skills add yaohao -g
+```
+
+## 边界
+
+- **仅用公开数据**：所有数据来自各城官方公告页（公开 HTML + PDF），不调用任何需要登录的接口
+- **不持有用户密码**：所有配置仅存本地，请求直连官方域名，不经任何第三方中转
+- **不做任何写入操作**：不替用户提交申请、不修改身份信息、不代他人查询
+- **MIT 开源 + 无变现**
+
+## 致谢
+
+- [`fichas/cross_beijing_cli`](https://github.com/fichas/cross_beijing_cli) — 进京证 CLI，本项目脚手架来源
+- [`JimmyLiang-lzm/BJJTW_Get`](https://github.com/JimmyLiang-lzm/BJJTW_Get) — 北京交通委接口参考
+
+## License
+
+MIT

package/bin/yaohao.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+import { program } from 'commander';
+
+program
+  .name('yaohao')
+  .description('国内城市车牌摇号 CLI - 资格自检、形势播报、开奖订阅、政策提醒（北京 / 广州 / 深圳 / 杭州）')
+  .version(version);
+
+import { registerInitCommand } from '../src/commands/init.js';
+import { registerEligibilityCommand } from '../src/commands/eligibility.js';
+import { registerCalendarCommand } from '../src/commands/calendar.js';
+import { registerMarketCommand } from '../src/commands/market.js';
+import { registerWatchCommand } from '../src/commands/watch.js';
+import { registerStatusCommand } from '../src/commands/status.js';
+import { registerFamilyCommand } from '../src/commands/family.js';
+import { registerResultCommand } from '../src/commands/result.js';
+import { registerHistoryCommand } from '../src/commands/history.js';
+import { registerWaitlistCommand } from '../src/commands/waitlist.js';
+import { registerNotifyCommand } from '../src/commands/notify.js';
+import { registerSetCommand } from '../src/commands/set.js';
+import { registerCronCommand } from '../src/commands/cron.js';
+
+// 无登录态（任何人能用）
+registerEligibilityCommand(program);
+registerCalendarCommand(program);
+registerMarketCommand(program);
+registerWatchCommand(program);
+
+// 登录态查询
+registerInitCommand(program);
+registerStatusCommand(program);
+registerFamilyCommand(program);
+registerResultCommand(program);
+registerHistoryCommand(program);
+registerWaitlistCommand(program);
+
+// 脚手架
+registerNotifyCommand(program);
+registerSetCommand(program);
+registerCronCommand(program);
+
+program.parse();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "yaohao",
+  "version": "1.0.0",
+  "description": "国内城市车牌摇号 CLI（北京 / 广州 / 深圳 / 杭州）- 资格自检、关键日历、形势播报、开奖订阅、政策提醒。AI Agent 友好。",
+  "type": "module",
+  "bin": {
+    "yaohao": "bin/yaohao.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "摇号",
+    "小客车",
+    "指标",
+    "车牌",
+    "新能源",
+    "家庭摇号",
+    "北京",
+    "广州",
+    "深圳",
+    "杭州",
+    "beijing",
+    "guangzhou",
+    "shenzhen",
+    "hangzhou",
+    "lottery",
+    "cli",
+    "agent"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/GuangyuZhan/yaohao#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuangyuZhan/yaohao.git"
+  },
+  "bugs": {
+    "url": "https://github.com/GuangyuZhan/yaohao/issues"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
+    "commander": "^14.0.3",
+    "pdfjs-dist": "^4.10.38",
+    "undici": "^6.0.0"
+  }
+}

package/skills/yaohao/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: yaohao
+version: 1.0.0
+description: "国内城市车牌摇号 CLI：资格自检、关键日历、形势播报、开奖订阅、政策提醒。覆盖北京、广州、深圳、杭州。当用户提到摇号、指标、申请编码、家庭摇号、新能源指标、阶梯、中签、京牌/粤A/深圳籍/浙A、北京/广州/深圳/杭州买车等关键词时触发。"
+---
+
+# yaohao 国内城市车牌摇号 CLI
+
+帮助用户通过命令行查询和订阅国内 4 城（北京、广州、深圳、杭州）的小客车摇号公开数据。
+
+## 安装检测
+
+```bash
+which yaohao
+```
+
+如未安装：
+
+```bash
+npm install -g yaohao
+```
+
+## 支持的城市
+
+| 城市 | --city 值 | 节奏 |
+|---|---|---|
+| 北京 | `beijing` | 半年制：1/1-3/8、8/1-10/8 申请，4/12 月摇号 |
+| 广州 | `guangzhou` | 月度：每月 12 日截止申请，25 日摇号 |
+| 深圳 | `shenzhen` | 月度：每月 8 日截止申请，26 日摇号 |
+| 杭州 | `hangzhou` | 月度 + 阶梯：每月 26 日摇号，阶梯摇号每年一次 |
+
+## 核心命令
+
+所有命令支持 `--city <city>` 切换城市，缺省走默认城市。
+
+### 资格自检
+
+```bash
+yaohao eligibility --city <city>
+```
+
+交互式问答：户籍 / 年龄 / 驾照 / 名下车牌 / 社保（非户籍）等，输出能不能摇号、能摇哪类。
+
+### 关键日历
+
+```bash
+yaohao calendar --city <city>
+```
+
+输出当前及未来几个月的申请截止 / 摇号日，附"距今天还有 N 天"。
+
+### 形势播报
+
+```bash
+yaohao market --city <city>
+```
+
+输出当期申请人数、配置指标、中签率（北京含 PDF 解析的精确数字）、最新公告链接。
+
+### 订阅推送
+
+```bash
+yaohao watch result --city <city>    # 开奖结果
+yaohao watch policy --city <city>    # 政策变化
+yaohao watch window --city <city>    # 申请窗口 / 资格审核
+```
+
+首次运行只记录历史，下次起检测新增并通过通知渠道推送。
+
+## 初始化检测
+
+```bash
+yaohao init   # 没初始化时提示用户跑这个
+```
+
+也支持非交互式：
+
+```bash
+yaohao init --city beijing --reg-type PTC --apply-type person
+```
+
+## 通知渠道
+
+```bash
+yaohao notify add <url>     # URL 格式兼容 Apprise: bark://, tgram://, dingtalk://, wecom://, feishu://, slack://
+yaohao notify test
+```
+
+## 定时
+
+```bash
+yaohao cron setup           # 默认每天 9:00 检查公告
+yaohao cron status
+yaohao cron remove
+```
+
+## 用户场景示例
+
+### 场景 A：刚来北京 / 广州 / 深圳 / 杭州，想知道能不能摇号
+
+```bash
+yaohao eligibility --city beijing
+yaohao calendar --city beijing
+```
+
+### 场景 B：已经在摇，想被开奖结果通知
+
+```bash
+yaohao notify add bark://xxx
+yaohao watch result --city shenzhen
+yaohao cron setup
+```
+
+### 场景 C：政策可能要变，想被通知
+
+```bash
+yaohao watch policy --city guangzhou
+```
+
+## 边界
+
+- v1 仅做公开数据查询和推送，**不做任何登录态查询**（不持有用户密码，不查本人状态/排名）
+- 本人申请状态请直接登录各城官网：
+  - 北京：https://apply.jtw.beijing.gov.cn/apply/
+  - 广州：https://jtzl.jtj.gz.gov.cn/
+  - 深圳：https://xqctk.jtys.sz.gov.cn/
+  - 杭州：https://hzxkctk.cn/（或浙里办 APP）
+- 不保证持续可用 —— 依赖官方公告页结构，改版可能导致部分功能失效

package/src/commands/calendar.js

@@ -0,0 +1,29 @@
+import { getSource, listImplemented, getCityLabel } from '../source/index.js';
+import { getUser } from '../lib/config-manager.js';
+import { DEFAULT_CITY } from '../constants.js';
+import { output, success, error } from '../output.js';
+
+function resolveCity(opts) {
+  if (opts.city) return opts.city;
+  const user = getUser();
+  return user?.default_city || DEFAULT_CITY;
+}
+
+export function registerCalendarCommand(program) {
+  program
+    .command('calendar')
+    .description('关键日历：申请窗口、摇号日、资格审核结果公布日')
+    .option('--city <city>', `城市 (${listImplemented().join('|')})`)
+    .option('--year <year>', '查询年份', String(new Date().getFullYear()))
+    .action(async (opts) => {
+      try {
+        const city = resolveCity(opts);
+        const source = getSource(city);
+        const result = source.getCalendar(Number(opts.year));
+        output(success({ city, ...result }, result.lines.join('\n')));
+      } catch (err) {
+        output(error(err.message));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/cron.js

@@ -0,0 +1,87 @@
+import { execSync } from 'node:child_process';
+import { output, success, error } from '../output.js';
+
+const MARKER = '# yaohao auto watch';
+const SCHEDULE = '0 9 * * *';
+
+function getCurrentCrontab() {
+  try {
+    return execSync('crontab -l', { encoding: 'utf-8' });
+  } catch {
+    return '';
+  }
+}
+
+function getBinPath() {
+  try {
+    return execSync('which yaohao', { encoding: 'utf-8' }).trim();
+  } catch {
+    return 'yaohao';
+  }
+}
+
+export function registerCronCommand(program) {
+  const cron = program.command('cron').description('定时任务管理');
+
+  cron
+    .command('setup')
+    .description('设置每日定时检查公告 + 推送（默认每天 9:00）')
+    .option('--schedule <cron>', 'cron 表达式（如 "0 9 * * *"）', SCHEDULE)
+    .action(async (options) => {
+      try {
+        let current = getCurrentCrontab();
+        if (current.includes(MARKER)) {
+          current = current.split('\n').filter((l) => !l.includes(MARKER)).join('\n');
+        }
+        const binPath = getBinPath();
+        const schedule = options.schedule;
+        const cronLine = `${schedule} ${binPath} watch result --json >> /tmp/yaohao.log 2>&1 ${MARKER}`;
+        const newCrontab = current.trimEnd() + (current.trim() ? '\n' : '') + cronLine + '\n';
+        const escapedCrontab = newCrontab.replace(/'/g, "'\\''");
+        execSync(`printf '%s' '${escapedCrontab}' | crontab -`, { encoding: 'utf-8' });
+        output(success({ schedule, command: cronLine }, `定时任务已设置: ${schedule}`));
+      } catch (err) {
+        output(error(`设置定时任务失败: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cron
+    .command('remove')
+    .description('移除定时任务')
+    .action(async () => {
+      try {
+        const current = getCurrentCrontab();
+        if (!current.includes(MARKER)) {
+          output(success(null, '未找到 yaohao 定时任务'));
+          return;
+        }
+        const filtered = current.split('\n').filter((l) => !l.includes(MARKER)).join('\n');
+        const escapedCrontab = filtered.replace(/'/g, "'\\''");
+        execSync(`printf '%s' '${escapedCrontab}' | crontab -`, { encoding: 'utf-8' });
+        output(success(null, '定时任务已移除'));
+      } catch (err) {
+        output(error(`移除定时任务失败: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cron
+    .command('status')
+    .description('查看定时任务状态')
+    .action(async () => {
+      try {
+        const current = getCurrentCrontab();
+        const exists = current.includes(MARKER);
+        if (exists) {
+          const line = current.split('\n').find((l) => l.includes(MARKER));
+          output(success({ active: true, line }, `定时任务已启用: ${line}`));
+        } else {
+          output(success({ active: false }, '定时任务未设置'));
+        }
+      } catch (err) {
+        output(error(`查询定时任务状态失败: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/eligibility.js

@@ -0,0 +1,28 @@
+import { getSource, listImplemented } from '../source/index.js';
+import { getUser } from '../lib/config-manager.js';
+import { DEFAULT_CITY } from '../constants.js';
+import { output, success, error } from '../output.js';
+
+function resolveCity(opts) {
+  if (opts.city) return opts.city;
+  const user = getUser();
+  return user?.default_city || DEFAULT_CITY;
+}
+
+export function registerEligibilityCommand(program) {
+  program
+    .command('eligibility')
+    .description('资格自检：回答几个问题判断是否满足摇号申请条件')
+    .option('--city <city>', `城市 (${listImplemented().join('|')})`)
+    .action(async (opts) => {
+      try {
+        const city = resolveCity(opts);
+        const source = getSource(city);
+        const result = await source.checkEligibility();
+        output(success({ city, ...result }, result.lines.join('\n')));
+      } catch (err) {
+        output(error(err.message));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/family.js

@@ -0,0 +1,17 @@
+import { output, success } from '../output.js';
+
+// v1 范围：仅做公开数据查询和提醒。家庭积分/排名查询请登录官网。
+export function registerFamilyCommand(program) {
+  program
+    .command('family')
+    .description('（v1 不支持）家庭摇号积分、阶梯、当前排名')
+    .action(async () => {
+      output(success(
+        { supported: false },
+        [
+          '家庭摇号积分和排名查询 v1 不支持（基于隐私和合规考虑）。',
+          '请直接登录官网查看：https://apply.jtw.beijing.gov.cn/apply/',
+        ].join('\n'),
+      ));
+    });
+}

package/src/commands/history.js

@@ -0,0 +1,17 @@
+import { output, success } from '../output.js';
+
+// v1 范围：本人历史参与记录查询请登录官网。
+export function registerHistoryCommand(program) {
+  program
+    .command('history')
+    .description('（v1 不支持）历史参与记录（参与了多少期、什么时候开始）')
+    .action(async () => {
+      output(success(
+        { supported: false },
+        [
+          '本人历史参与记录 v1 不支持（基于隐私和合规考虑）。',
+          '请直接登录官网查看：https://apply.jtw.beijing.gov.cn/apply/',
+        ].join('\n'),
+      ));
+    });
+}