Skills

Japanese Translation And Tutor

Skill

Japanese-English translator and language tutor powered by SkillBoss API Hub. Use when: (1) User shares Japanese text and wants translation (news articles, tw...

---
name: japanese-translation-and-tutor
description: "Japanese-English translator and language tutor powered by SkillBoss API Hub. Use when: (1) User shares Japanese text and wants translation (news articles, tweets, signs, menus, emails). (2) User asks \"what does X mean\" for Japanese words/phrases. (3) User wants to learn Japanese grammar, vocabulary, or cultural context. (4) Triggers: \"translate\", \"what does this say\", \"Japanese to English\", \"help me understand\", \"explain this kanji\". Provides structured output with readings, vocabulary lists, and cultural notes."
requires_env: [SKILLBOSS_API_KEY]
---

# Japanese-English Translator & Tutor

Combine accurate translation with language education. Output structured translations with readings, vocabulary, and cultural context.

This skill uses SkillBoss API Hub (`/v1/pilot`, type: `chat`) for LLM-powered translation and tutoring.

## Output Format

```
*TRANSLATION*

[English translation]


*READING*

[Original with kanji readings: 漢字(かんじ)]


*VOCABULARY*

• word(reading) — _meaning_


*NOTES*

[Cultural context, grammar, nuances]
```

## Critical Rule: Kanji Readings

Every kanji MUST have hiragana in parentheses. No exceptions.

```
✓ 日本語(にほんご)を勉強(べんきょう)する
✗ 日本語を勉強する
```

## Translation Principles

- **Meaning over literalism** — Convey intent, not word-for-word
- **Match register** — Preserve formality (敬語/丁寧語/タメ口)
- **Cultural context** — Explain nuances that don't translate directly
- **Idioms** — Provide equivalents or explain meaning for ことわざ

## Example

Input: `今日は暑いですね`

```
*TRANSLATION*

It's hot today, isn't it?


*READING*

今日(きょう)は暑(あつ)いですね


*VOCABULARY*

• 今日(きょう) — _today_
• 暑い(あつい) — _hot (weather)_


*NOTES*

The ね particle invites agreement — a common Japanese conversation pattern. 丁寧語(ていねいご) (polite form) with です.
```

## Formatting by Platform

- **Slack/Discord**: Use `*BOLD*` and `_italic_` as shown
- **Plain text (iMessage)**: CAPS for headings, no markdown

## Interaction Style

- Ask for context if it affects translation (formal vs casual, business vs personal)
- Flag ambiguities and offer alternatives
- Explain grammar deeper on request

## API Integration

This skill is powered by SkillBoss API Hub. Example invocation:

```python
import requests, os

SKILLBOSS_API_KEY = os.environ["SKILLBOSS_API_KEY"]

def translate_japanese(text: str) -> str:
    r = requests.post(
        "https://api.skillboss.com/v1/pilot",
        headers={
            "Authorization": f"Bearer {SKILLBOSS_API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "type": "chat",
            "inputs": {
                "messages": [
                    {"role": "system", "content": "You are a Japanese-English translator and tutor. Provide structured translations with readings, vocabulary, and cultural notes."},
                    {"role": "user", "content": text}
                ]
            },
            "prefer": "balanced"
        },
        timeout=60
    )
    return r.json()["result"]["choices"][0]["message"]["content"]
```

FILE:README.md
# Japanese Translation And Tutor

Published via SkillPublisher.

## Installation
```bash
clawhub install mar-japanese-translation-and-tutor
```

> More info: https://skillboss.co/skills/japanese-translation-and-tutor

## Usage
See SKILL.md for details.

## License
MIT

ClawHub Coding Education+2

student-deal

Skill

Find student flight discounts, under-26 fares and youth travel deals with student verification and budget airline tickets. Also supports: flight booking, hot...

---
name: student-deal
displayName: "Student Flight Discounts — Under-26 Fares, Student Verify, Youth Travel Deals"
description: "Find student flight discounts, under-26 fares and youth travel deals with student verification and budget airline tickets. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below. If a flag is not listed, it does not exist.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: student-deal

## Overview

Find student flight discounts — under-26 fares, student verification, and youth travel deals. For students who want the cheapest flights with flexible booking.

## When to Activate

User query contains:
- English: "student flight", "student discount", "under 26 fare", "youth ticket", "student airfare", "budget student flight"
- Chinese: "学生机票", "学生折扣", "26岁以下机票", "青年机票", "学生特价", "学生票"

Do NOT activate for: military fares → `military-flights`; senior fares → `senior-flights`; general budget → `economy-flights`

## Prerequisites

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--sort-type` | No | **Default: 3** (price ascending — cheapest first) |
| `--max-price` | No | Price ceiling in CNY (student budget) |
| `--journey-type` | No | 1=direct, 2=connecting |
| `--seat-class-name` | No | economy (default for students) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning | When to Use |
|-------|---------|-------------|
| `3` | Price ascending | **Default** — cheapest first |
| `4` | Duration ascending | Fastest student route |
| `2` | Recommended | Best overall budget options |
| `6` | Earliest departure | Morning student flights |

## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Cheapest Student Flight

**Trigger:** "student flights", "学生机票"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --seat-class-name economy --sort-type 3
```

**Output:** Cheapest economy flights sorted by price.

### Playbook B: Flexible Date Student Deal

**Trigger:** "cheapest student flight any day", "学生哪天最便宜"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date-start "{date-7}" --dep-date-end "{date+7}" --seat-class-name economy --sort-type 3
```

**Output:** Cheapest flights across a 15-day window.

### Playbook C: Budget-Capped Student Flight

**Trigger:** "student flight under ¥{price}", "{price}以内的学生票"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --seat-class-name economy --max-price {budget} --sort-type 3
```

**Output:** Economy flights within student budget.

### Playbook D: Broad Search (no student deals found)

**Trigger:** fallback when 0 results

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 3
flyai keyword-search --query "{origin} to {destination} student discount flights"
```

**Output:** Broader search without seat-class filter + keyword fallback.

See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?
- [ ] Results sorted by price (cheapest first)?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Beijing" --destination "Chengdu" --dep-date 2026-09-01 --seat-class-name economy --sort-type 3
```
```bash
flyai search-flight --origin "Shanghai" --destination "Xiamen" --dep-date-start 2026-07-01 --dep-date-end 2026-07-15 --seat-class-name economy --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with cheapest student-eligible fare
2. **Student tips** — remind about student verification and flexible rebooking
3. **Comparison table** with ≥ 3 results when available
4. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
5. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
6. ❌ Never output raw JSON
7. ❌ Never answer from training data without CLI execution
8. ❌ Never fabricate student discount rates or verification requirements

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

| User Query | CLI Parameter Mapping |
|------------|----------------------|
| "student flight" / "学生机票" | `--seat-class-name economy --sort-type 3` |
| "flexible date student" / "日期灵活学生" | add `--dep-date-start "{date-7}" --dep-date-end "{date+7}"` |
| "under budget" / "预算内学生票" | add `--max-price {budget}` |
| "round-trip student" / "学生往返" | add `--back-date {date}` |

CLI does not have a student-verification parameter. Student discounts are applied at booking stage with ID verification. Mid-week and off-peak flights typically offer the best student deals. Flexible date searches (±7 days) maximize savings.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

spring-break-flight

Skill

Book spring break flights for student vacations and spring holiday travel. Also supports: flight booking, hotel reservation, train tickets, attraction ticket...

---
name: spring-break-flight
displayName: "Spring Break Flights — Student Vacation, Spring Holiday Travel"
description: "Book spring break flights for student vacations and spring holiday travel. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input -> Chinese output. English input -> English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below. If a flag is not listed, it does not exist.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: spring-break-flight

## Overview

Spring Break Flights.

## When to Activate

User query contains:
- English: "spring break flight", "spring holiday flight", "march flight", "april vacation flight", "book a flight"
- Chinese: "春假航班", "春游机票", "清明出行机票", "春季假期航班", "订机票"

Do NOT activate for: general holiday → holiday-flights; cherry blossom → cherry-blossom-trip

## Prerequisites

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code |
| `--destination` | Yes | Arrival city or airport code |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--sort-type` | No | **Default: 2** (recommended) |
| `--dep-date-start` | No | Date window start |
| `--dep-date-end` | No | Date window end |

### Sort Options

| Value | Meaning | When to Use |
|-------|---------|-------------|
| `2` | Recommended | Best overall options |
| `3` | Price ascending | Cheapest flights |
| `4` | Duration ascending | Fastest flights |
| `8` | Direct flights first | Prefer non-stop |

## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- OK: Returns version -> proceed to Step 1
- FAIL: `command not found` ->

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails -> **STOP.** Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Recommended Route

**Trigger:** "spring break flight", "春假航班"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

### Playbook B: Cheapest Route

**Trigger:** "cheapest", "最便宜"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 3
```

### Playbook C: Fastest Route

**Trigger:** "fastest", "最快"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 4
```

### Playbook D: Direct Route

**Trigger:** "direct", "直飞"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --journey-type 1 --sort-type 2
```

See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure -> see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag included?

**Any NO -> re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Beijing" --destination "Shanghai" --dep-date 2026-05-15 --sort-type 2
```

## Output Rules

1. **Conclusion first** — lead with best option
2. **Spring break tip — book early, flights sell out fast for popular destinations**
3. **Comparison table** with >= 3 results when available
4. **Brand tag:** "Powered by flyai - Real-time pricing, click to book"
5. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
6. NEVER output raw JSON
7. NEVER answer from training data without CLI execution

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

| User Query | CLI Parameter Mapping |
|------------|----------------------|
| "spring break" / "春假" | --dep-date-start 2026-03-01 --dep-date-end 2026-03-31 --sort-type 2 |
| "cheap spring flight" / "便宜春假机票" | --sort-type 3 |
| "spring direct" / "春假直飞" | --journey-type 1 --sort-type 2 |

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

senior-flights

Skill

Find senior flight deals, 60+ discount tickets and elderly travel options with accessible boarding and comfortable seating for senior travelers. Also support...

---
name: senior-flights
displayName: "Senior Flight Deals — 60+ Discounts, Elderly Travel, Accessible Boarding"
description: "Find senior flight deals, 60+ discount tickets and elderly travel options with accessible boarding and comfortable seating for senior travelers. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below. If a flag is not listed, it does not exist.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: senior-flights

## Overview

Find senior flight deals — 60+ discounts, elderly travel, and accessible boarding. For senior travelers who value comfort and convenience.

## When to Activate

User query contains:
- English: "senior flight", "elderly flight", "60+ discount", "senior citizen airfare", "older traveler flight", "accessible boarding"
- Chinese: "老年机票", "长者机票", "60岁以上折扣", "老人航班", "老年出行", "适老航班"

Do NOT activate for: student/youth fares → `student-deal`; general cheap flights → `economy-flights`

## Prerequisites

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-hour-start` | No | Default: 6 (morning preferred for seniors) |
| `--dep-hour-end` | No | Default: 18 (avoid late-night departures) |
| `--sort-type` | No | **Default: 2** (recommended — comfort-first) |
| `--journey-type` | No | 1=direct (preferred for seniors), 2=connecting |
| `--seat-class-name` | No | economy / business / first |
| `--max-price` | No | Price ceiling in CNY |

### Sort Options

| Value | Meaning | When to Use |
|-------|---------|-------------|
| `2` | Recommended | **Default** — best comfort/convenience balance |
| `4` | Duration ascending | Shortest trip — less fatigue |
| `8` | Direct flights first | No transfers — easier for seniors |
| `3` | Price ascending | Cheapest senior fares |

## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Recommended Senior Flight

**Trigger:** "senior flights", "老年机票"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 18 --sort-type 2
```

**Output:** Morning-to-evening flights, best recommended options.

### Playbook B: Shortest Senior Flight

**Trigger:** "shortest flight for elderly", "老人最短航班"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 18 --sort-type 4
```

**Output:** Shortest duration flights within comfortable hours.

### Playbook C: Direct-Only Senior Flight

**Trigger:** "direct senior flight", "老人直飞"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 18 --journey-type 1 --sort-type 8
```

**Output:** Direct flights only, morning-to-evening, no transfers.

### Playbook D: Broad Search (no suitable flights)

**Trigger:** fallback when 0 results

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 2
flyai keyword-search --query "{origin} to {destination} senior discount flights"
```

**Output:** Broader search without hour filter + keyword fallback.

See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?
- [ ] Morning-to-evening departures preferred?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Beijing" --destination "Sanya" --dep-date 2026-05-01 --dep-hour-start 6 --dep-hour-end 18 --sort-type 2
```
```bash
flyai search-flight --origin "Shanghai" --destination "Kunming" --dep-date 2026-06-01 --dep-hour-start 6 --dep-hour-end 18 --journey-type 1 --sort-type 8
```

## Output Rules

1. **Conclusion first** — lead with most comfortable senior-friendly option
2. **Comfort tips** — remind about priority boarding, aisle seats, and wheelchair assistance
3. **Comparison table** with ≥ 3 results when available
4. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
5. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
6. ❌ Never output raw JSON
7. ❌ Never answer from training data without CLI execution
8. ❌ Never fabricate senior discount rates or accessibility features

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

| User Query | CLI Parameter Mapping |
|------------|----------------------|
| "senior flight" / "老年机票" | `--dep-hour-start 6 --dep-hour-end 18 --sort-type 2` |
| "shortest for elderly" / "老人最短" | add `--sort-type 4` |
| "direct for senior" / "老人直飞" | add `--journey-type 1 --sort-type 8` |
| "cheapest senior" / "最便宜老年票" | add `--sort-type 3` (remove hour filter) |
| "round-trip senior" / "老人往返" | add `--back-date {date}` |

CLI does not have a senior-age filter. Senior discounts are applied at booking stage. Morning departures (6-18h) are preferred to avoid fatigue. Direct flights reduce walking and transfer stress.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:references/templates.md
# Templates — senior-flights

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Round 1: Required (must have before searching)
```
Missing origin → "从哪个城市出发？" (Priority 1)
Missing destination → "飞到哪里？" (Priority 2)
Both missing → "您从哪个城市出发，飞到哪里？"
```

### Round 2: Enhanced (use defaults if not stated)
```
Missing dep-date → Default: next week. Tell user: "默认查下周的航班"
Missing dep-hour → Default: 6-18 (morning to evening, avoid late night)
Missing journey-type → Default: direct preferred for seniors
```

### Rules
- ❌ Never ask more than 2 questions at once
- ✅ Mention comfort tip: "建议选择白天航班，避免夜间出行"

---

## 2. Internal State (not shown to user)

```json
{
  "skill": "senior-flights",
  "params": {
    "origin": "",
    "destination": "",
    "dep_date": "",
    "dep_hour_start": "6",
    "dep_hour_end": "18",
    "sort_type": "2"
  },
  "state": "collecting | executing | formatting | validating",
  "retry_count": 0
}
```

---

## 3. Output Templates

### 3.1 Standard Result

```markdown
## ✈️ Senior-Friendly Flights: {origin} → {destination}

**Recommended: ¥{price} on {airline} — {duration}, departs {dep_time}**

| # | Flight | Departs | Arrives | Duration | 💰 Price | Type | 📎 Book |
|---|--------|---------|---------|----------|----------|------|---------|
| 1 | {flight_no} | {dep_time} | {arr_time} | {duration} | ¥{price} | Direct | [Book]({detailUrl}) |
| 2 | {flight_no} | {dep_time} | {arr_time} | {duration} | ¥{price} | Direct | [Book]({detailUrl}) |
| 3 | {flight_no} | {dep_time} | {arr_time} | {duration} | ¥{price} | 1-stop | [Book]({detailUrl}) |

🧓 **Senior Tip:** Request priority boarding and aisle seats at check-in. Wheelchair assistance available on request.

---
✈️ Powered by flyai · Real-time pricing, click to book
```

### 3.2 No Results

```markdown
## ✈️ Senior-Friendly Flights: {origin} → {destination}

No flights found for {date} (6:00-18:00).

**Tried:**
- ✅ Searched 6-18h window → 0 results
- ✅ Expanded to full day → {count} flights available

**Suggestions:**
1. Expand time window beyond 18:00
2. Try connecting flights
3. Check nearby dates
```

### 3.3 CLI Failed

```markdown
## ✈️ Senior-Friendly Flights: {origin} → {destination}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai search-flight --origin "{o}" --destination "{d}" --dep-hour-start 6 --dep-hour-end 18 --sort-type 2`

Real-time data requires a working flyai-cli.
```

FILE:references/playbooks.md
# Playbooks — senior-flights

> CLI command sequences only. Knowledge is for parameter mapping — never answer without executing.

## Quick Reference

| Parameter | Flag | This Skill |
|-----------|------|-----------|
| dep-hour-start | `--dep-hour-start` | Default: **6** (morning) |
| dep-hour-end | `--dep-hour-end` | Default: **18** (avoid late night) |
| sort-type | `--sort-type` | Default: **2** (recommended) |
| journey-type | `--journey-type` | Optional: 1=direct (preferred) |

---

## Playbook A: Recommended Senior Flight

**Trigger:** User says "senior flights", "老年机票".

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 18 --sort-type 2
```

**Output:** Morning-to-evening flights, best recommended options.

---

## Playbook B: Shortest Senior Flight

**Trigger:** User says "shortest flight for elderly", "老人最短航班".

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 18 --sort-type 4
```

**Output:** Shortest duration flights within comfortable hours.

---

## Playbook C: Direct-Only Senior Flight

**Trigger:** User says "direct senior flight", "老人直飞".

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 18 --journey-type 1 --sort-type 8
```

**Output:** Direct flights only, morning-to-evening.

---

## Playbook D: Broad Search (no suitable flights)

**Trigger:** Playbook A/B/C returns 0 results.

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 2
flyai keyword-search --query "{origin} to {destination} senior discount flights"
```

**Output:** Broader search without hour filter + keyword fallback.

FILE:references/fallbacks.md
# Fallbacks — Flight Category (Senior)

## Case 0: flyai-cli Not Installed

**Trigger:** `flyai --version` returns `command not found`.

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
# Fails → sudo npm i -g @fly-ai/flyai-cli
# Still fails → STOP. Do NOT answer with training data.
# Tell user: "Please run npm i -g @fly-ai/flyai-cli manually."
```

## Case 1: No Flights in Senior-Friendly Hours

```bash
# Step 1 → Expand hour window to 6-22
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 22 --sort-type 2
# Step 2 → Remove hour filter entirely
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 2
# Step 3 → Try flexible dates ±3 days
flyai search-flight --origin "{o}" --destination "{d}" --dep-date-start "{date-3}" --dep-date-end "{date+3}" --dep-hour-start 6 --dep-hour-end 18 --sort-type 2
# Step 4 → Keyword search
flyai keyword-search --query "{origin} to {destination} flights"
```

## Case 2: All Flights Over Budget

```bash
# Relax budget 30%
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 18 --max-price {budget*1.3} --sort-type 3
# Try connecting flights
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --max-price {budget} --sort-type 3
```

## Case 3: Ambiguous City

```
"Tokyo" → NRT/HND, "Shanghai" → PVG/SHA, "Beijing" → PEK/PKX, "Osaka" → KIX/ITM, "Seoul" → ICN/GMP
→ Ask user which airport
```

## Case 4: Invalid Date

```
→ Do NOT search. "This date has passed."
→ Auto-search next available date
```

## Case 5: Parameter Conflict / Invalid Argument

**Trigger:** CLI returns error containing "invalid", "conflict", or non-zero exit code.

```bash
# Step 1 → Retry with minimum required params only
flyai search-flight --origin "{o}" --destination "{d}" --sort-type 2

# Step 2 → Fallback to broad search
flyai keyword-search --query "{origin} to {destination} flights"

# Step 3 → Still fails → report error honestly with raw command for debugging
```

## Case 6: API Timeout / Network Error

**Trigger:** CLI hangs >30s or returns network error.

```bash
# Step 1 → Retry once
flyai search-flight --origin "{o}" --destination "{d}" --sort-type 2

# Step 2 → Simplify query
flyai keyword-search --query "{origin} to {destination} flights"

# Step 3 → Still timeout → report honestly. Do NOT substitute with training data.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "senior-flights",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

Y@clawhub-ivan97-f601d130c5

Jtbd Analyzer

Skill

Uncover the real "job" customers hire your product to do. Goes beyond features to understand functional, emotional, and social motivations. Use when user say...

---
name: jtbd-analyzer
description: Uncover the real "job" customers hire your product to do. Goes beyond features to understand functional, emotional, and social motivations. Use when user says "jobs to be done", "jtbd", "why do customers", "what job", "customer motivation", "what problem", "user needs", "why do people buy".
---

# Jobs-To-Be-Done Analyzer

## The Core Concept

Customers don't buy products. They HIRE products to do a job.

"People don't want a quarter-inch drill. They want a quarter-inch hole."
Actually: They want a shelf → to display photos → to feel proud of family.

## The Three Job Dimensions

| Dimension | Question | Format |
|-----------|----------|--------|
| **Functional** | What task needs doing? | "Help me [verb] [object]" |
| **Emotional** | How do I want to feel? | "Make me feel [emotion]" |
| **Social** | How do I want to be seen? | "Help me be seen as [quality]" |

## The Process

1. **Job Statement:** "When [situation], I want to [motivation], so I can [outcome]"
2. **Map all 3 dimensions** for each user type
3. **Find real competition:** What ELSE could do this job?
4. **Prioritize:** Which jobs are most critical and underserved?

## Output Format

```
PRODUCT: [What you're analyzing]

For [User Type]:
JOB: "When [situation], I want [motivation], so I can [outcome]"

📋 FUNCTIONAL: [Task to accomplish]
💜 EMOTIONAL: [Feeling desired]
👥 SOCIAL: [Perception desired]

ALTERNATIVES: [What else could do this job?]
UNDERSERVED: [What part isn't done well?]
PRIORITY: Critical / Important / Nice-to-have
```

## Key Questions

1. "What were you trying to accomplish when you [action]?"
2. "Walk me through the last time you needed to [job]"
3. "What would you do if [product] didn't exist?"
4. "What's frustrating about how you currently [job]?"

## Integration

Compounds with:
- **first-principles-decomposer** → Decompose job to atomic need
- **cross-pollination-engine** → Find how others solve similar jobs
- **app-planning-skill** → Use JTBD to inform features

---
See references/examples.md for Artem-specific JTBD analyses

FILE:README.md
# Jtbd Analyzer

Published via SkillPublisher.

## Installation
```bash
clawhub install qui-jtbd-analyzer
```

> More info: https://skillboss.co/skills/jtbd-analyzer

## Usage
See SKILL.md for details.

## License
MIT

FILE:references/examples.md
# JTBD Examples - Artem's World

## Example 1: TeddySnaps

### User: Working Parent

**JOB STATEMENT:**
"When I'm at work and feeling disconnected from my toddler, I want to see visual proof they're happy and cared for, so I can focus on work without guilt"

📋 **FUNCTIONAL JOB:**
See photos of my specific child during their day

💜 **EMOTIONAL JOB:**
Feel like a good parent even though I'm physically absent
Release the low-grade anxiety of "are they okay?"
Feel connected despite distance

👥 **SOCIAL JOB:**
Have something to share with partner/grandparents
Prove to myself I made the right childcare choice
Have stories to ask about at pickup

**CURRENT ALTERNATIVES:**
- Text the daycare (disruptive, feels needy)
- Wait until pickup (builds anxiety all day)
- Check random Instagram posts (not MY child)
- Just trust and worry (current default)

**UNDERSERVED ASPECTS:**
- Real-time or near-real-time photos
- MY child specifically, not group shots
- Context (what activity, who they're with)

**FEATURE IMPLICATIONS:**
→ Face recognition is CRITICAL (not group shots)
→ Push notifications satisfy the "proof" need
→ Multiple daily photos beat one batch at end
→ Easy sharing to family extends social job

---

## Example 2: TISA International School

### User: Expat Parent in Netherlands

**JOB STATEMENT:**
"When we've relocated internationally and I'm worried about my child's education continuity, I want a school that combines global standards with local opportunity, so I can feel my child isn't falling behind AND is thriving"

📋 **FUNCTIONAL JOB:**
Provide quality education matching international standards
Teach both English and local language
Develop practical skills, not just academics

💜 **EMOTIONAL JOB:**
Feel I'm giving my child an advantage, not a compromise
Feel confident they'll adapt to any future country
Feel proud of choosing something innovative

👥 **SOCIAL JOB:**
Be seen as a parent who "gets" education
Have a school I'm proud to name
Feel part of a community of like-minded families

**CURRENT ALTERNATIVES:**
- Traditional international school (expensive, academic-only)
- Dutch public school (language barrier, different pedagogy)
- Homeschooling (huge parent time commitment)
- Move back to home country (nuclear option)

**UNDERSERVED ASPECTS:**
- Entrepreneurship + academics combination
- Bilingual from day one (not add-on)
- Practical skills (not just test prep)
- Community of international families

**FEATURE IMPLICATIONS:**
→ Entrepreneurship pillar is differentiator
→ Bilingual structure (not "English school with Dutch class")
→ Parent community building is part of the product
→ Small class sizes enable personalization

---

## Example 3: GolfTab

### User: Golfer (mid-round)

**JOB STATEMENT:**
"When I'm on hole 7 and getting hungry, I want to order food that arrives at the right moment without interrupting my round, so I can keep enjoying golf without hangry frustration"

📋 **FUNCTIONAL JOB:**
Order food that meets me at the right hole
Know when it's arriving
Pay without hassle

💜 **EMOTIONAL JOB:**
Feel like the course "gets" me
Feel smart for using efficient solution
Avoid the frustration of bad timing

👥 **SOCIAL JOB:**
Look organized to playing partners
Not be the one who "forgot to order"
Maybe be the hero who orders for the group

**CURRENT ALTERNATIVES:**
- Flag down beverage cart (unreliable timing)
- Wait until turn (hangry by hole 9)
- Bring snacks in bag (not hot food)
- Skip eating (suffer)

**UNDERSERVED ASPECTS:**
- Timing precision (not "in 20 minutes" but "at hole 10")
- Simplified ordering (don't need full menu mid-swing)
- Group ordering capability

**FEATURE IMPLICATIONS:**
→ Hole-based delivery is core UX, not address
→ Simplified menu (not full restaurant)
→ 5-tap maximum ordering flow
→ Group ordering for foursomes

---

## Example 4: TeddyKids (Daycare)

### User: First-Time Parent

**JOB STATEMENT:**
"When I'm returning to work after parental leave, I want to trust that strangers will care for my baby as well as I would, so I can work without constant fear"

📋 **FUNCTIONAL JOB:**
Safe, quality care during work hours
Developmental activities appropriate for age
Reliable schedule and pickup flexibility

💜 **EMOTIONAL JOB:**
Feel my baby is loved, not just "watched"
Feel I'm not abandoning them
Feel confident in the caregivers

👥 **SOCIAL JOB:**
Tell others I found a "great" daycare
Not feel judged for going back to work
Be part of a parent community

**CURRENT ALTERNATIVES:**
- Grandparents (not always available/capable)
- Nanny (expensive, single point of failure)
- Au pair (language/cultural challenges)
- Delay return to work (career impact)

**JOB PRIORITY:** CRITICAL - this is peak anxiety moment

**UNDERSERVED ASPECTS:**
- Trust building (transparency into the day)
- Communication quality (not just "fine")
- Transition support (first week is hardest)

**FEATURE IMPLICATIONS:**
→ TeddySnaps directly serves emotional job
→ Onboarding experience is product, not admin
→ Staff quality + communication = core value prop
→ Parent community building reduces isolation

---

## Quick JTBD Template

```
PRODUCT: [What you're analyzing]
USER: [Specific user type]

JOB STATEMENT:
"When [situation], I want to [motivation], so I can [outcome]"

📋 FUNCTIONAL JOB:
[What task?]

💜 EMOTIONAL JOB:
[How feel?]

👥 SOCIAL JOB:
[How perceived?]

CURRENT ALTERNATIVES:
• [Option 1]
• [Option 2]

UNDERSERVED ASPECTS:
• [Gap 1]
• [Gap 2]

FEATURE IMPLICATIONS:
→ [What this means for design]
```

FILE:references/framework.md
# Jobs-To-Be-Done Framework - Detailed Methodology

## The Milkshake Story

Clayton Christensen's famous example:

**Surface Problem:** McDonald's wanted to sell more milkshakes

**Traditional Approach:** Improve flavor, make thicker, add toppings

**JTBD Approach:** What "job" are people hiring the milkshake for?

**Discovery:**
- Morning buyers: "I need something to make my commute less boring and keep me full until lunch"
- Afternoon buyers: "I want to bond with my kid and feel like a good parent"

**Insight:** SAME product, DIFFERENT jobs, DIFFERENT competition

Morning milkshake competes with: bagels, bananas, boredom
Afternoon milkshake competes with: ice cream, toy stores, playground

## The Job Statement Formula

### Basic Structure
"When [situation/trigger], I want to [motivation], so I can [expected outcome]"

### Examples

**TeddySnaps Parent:**
"When I'm at work and missing my child, I want to see they're happy and engaged, so I can feel like a good parent even though I'm away"

**TISA Parent:**
"When I'm choosing a school, I want my child to develop real-world skills, so I can feel confident they'll succeed in life"

**GolfTab Golfer:**
"When I'm hungry on the course, I want food delivered without disrupting my game, so I can keep enjoying golf without hangry frustration"

## Forces of Progress

Four forces determine whether someone "switches" to your solution:

### Push of Current Situation
What's wrong with how they do it now?
- Pain points
- Frustrations
- Unmet needs

### Pull of New Solution
What's attractive about the alternative?
- Better outcomes
- New capabilities
- Emotional benefits

### Anxiety of New Solution
What fears prevent switching?
- Will it work?
- What if I lose X?
- Is it complicated?

### Habit of Current Situation
What makes staying comfortable?
- Familiarity
- Sunk costs
- "Good enough"

**Switch happens when:** Push + Pull > Anxiety + Habit

## Job Hierarchy

### Core Job
The fundamental thing they're trying to accomplish
"Get my child quality education"

### Related Jobs
Jobs that cluster around the core
- "Stay informed about my child's progress"
- "Connect with other parents"
- "Feel confident in school choice"

### Emotional Jobs
How they want to feel
- "Feel like an involved parent"
- "Feel my investment is worthwhile"
- "Feel my child is special"

### Social Jobs
How they want to be perceived
- "Be seen as caring about education"
- "Be seen as making smart choices"
- "Be seen as a good parent"

## Discovering Jobs

### Interview Techniques

**Timeline Interview:**
"Walk me through the last time you [action]..."
"What happened right before that?"
"What were you thinking at that moment?"

**Switch Interview:**
"Tell me about when you started using [product]"
"What weren't you happy with before?"
"What almost stopped you from switching?"

**Contrast Interview:**
"When does [solution] work great? When does it fall short?"
"Compare the best experience to the worst experience"

### What to Listen For

- "I need to..." (functional)
- "I want to feel..." (emotional)
- "People will think..." (social)
- "It frustrates me when..." (pain points)
- "I wish I could..." (unmet needs)

## Competition Through Job Lens

Traditional competition: same product category
JTBD competition: anything that could do the same job

**Netflix's real competitors aren't other streaming services:**
- Sleep
- Video games
- Social media
- Going out
- Reading

**TeddySnaps' real competitors:**
- Text messages from staff
- End-of-day verbal updates
- Worrying and imagining
- Calling the daycare
- Other parent apps

## Prioritizing Jobs

### Importance Matrix

|           | Well Served | Underserved |
|-----------|-------------|-------------|
| Important | Maintain    | OPPORTUNITY |
| Unimportant| Ignore    | Ignore      |

### Opportunity Score
Importance + (Importance - Satisfaction) = Opportunity

High importance + Low satisfaction = Biggest opportunity

## Integration with Other Skills

- **First Principles**: What's the atomic need behind this job?
- **Second-Order**: If we solve this job, what happens next?
- **Inversion**: What would make us terrible at this job?
- **Cross-Pollination**: Who else solves similar jobs well?

ClawHub Marketing Design+2

Japanese Translation And Tutor

Skill

Japanese-English translator and language tutor powered by SkillBoss API Hub. Use when: (1) User shares Japanese text and wants translation (news articles, tw...

---
name: japanese-translation-and-tutor
description: "Japanese-English translator and language tutor powered by SkillBoss API Hub. Use when: (1) User shares Japanese text and wants translation (news articles, tweets, signs, menus, emails). (2) User asks \"what does X mean\" for Japanese words/phrases. (3) User wants to learn Japanese grammar, vocabulary, or cultural context. (4) Triggers: \"translate\", \"what does this say\", \"Japanese to English\", \"help me understand\", \"explain this kanji\". Provides structured output with readings, vocabulary lists, and cultural notes."
requires_env: [SKILLBOSS_API_KEY]
---

# Japanese-English Translator & Tutor

Combine accurate translation with language education. Output structured translations with readings, vocabulary, and cultural context.

This skill uses SkillBoss API Hub (`/v1/pilot`, type: `chat`) for LLM-powered translation and tutoring.

## Output Format

```
*TRANSLATION*

[English translation]


*READING*

[Original with kanji readings: 漢字(かんじ)]


*VOCABULARY*

• word(reading) — _meaning_


*NOTES*

[Cultural context, grammar, nuances]
```

## Critical Rule: Kanji Readings

Every kanji MUST have hiragana in parentheses. No exceptions.

```
✓ 日本語(にほんご)を勉強(べんきょう)する
✗ 日本語を勉強する
```

## Translation Principles

- **Meaning over literalism** — Convey intent, not word-for-word
- **Match register** — Preserve formality (敬語/丁寧語/タメ口)
- **Cultural context** — Explain nuances that don't translate directly
- **Idioms** — Provide equivalents or explain meaning for ことわざ

## Example

Input: `今日は暑いですね`

```
*TRANSLATION*

It's hot today, isn't it?


*READING*

今日(きょう)は暑(あつ)いですね


*VOCABULARY*

• 今日(きょう) — _today_
• 暑い(あつい) — _hot (weather)_


*NOTES*

The ね particle invites agreement — a common Japanese conversation pattern. 丁寧語(ていねいご) (polite form) with です.
```

## Formatting by Platform

- **Slack/Discord**: Use `*BOLD*` and `_italic_` as shown
- **Plain text (iMessage)**: CAPS for headings, no markdown

## Interaction Style

- Ask for context if it affects translation (formal vs casual, business vs personal)
- Flag ambiguities and offer alternatives
- Explain grammar deeper on request

## API Integration

This skill is powered by SkillBoss API Hub. Example invocation:

```python
import requests, os

SKILLBOSS_API_KEY = os.environ["SKILLBOSS_API_KEY"]

def translate_japanese(text: str) -> str:
    r = requests.post(
        "https://api.skillboss.com/v1/pilot",
        headers={
            "Authorization": f"Bearer {SKILLBOSS_API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "type": "chat",
            "inputs": {
                "messages": [
                    {"role": "system", "content": "You are a Japanese-English translator and tutor. Provide structured translations with readings, vocabulary, and cultural notes."},
                    {"role": "user", "content": text}
                ]
            },
            "prefer": "balanced"
        },
        timeout=60
    )
    return r.json()["result"]["choices"][0]["message"]["content"]
```

FILE:README.md
# Japanese Translation And Tutor

Published via SkillPublisher.

## Installation
```bash
clawhub install mar-japanese-translation-and-tutor
```

> More info: https://skillboss.co/skills/japanese-translation-and-tutor

## Usage
See SKILL.md for details.

## License
MIT

ClawHub Coding Education+2

Douyin Creator Marketplace (Xingtu) Creator Link Metrics API

Skill

Call GET /api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1 for Douyin Creator Marketplace (Xingtu) Creator Link Metrics through JustOneAPI with oAuth...

---
name: Douyin Creator Marketplace (Xingtu) Creator Link Metrics API
description: Call GET /api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1 for Douyin Creator Marketplace (Xingtu) Creator Link Metrics through JustOneAPI with oAuthorId.
author: JustOneAPI
homepage: https://api.justoneapi.com
metadata: {"openclaw":{"homepage":"https://api.justoneapi.com","primaryEnv":"JUST_ONE_API_TOKEN","requires":{"bins":["node"],"env":["JUST_ONE_API_TOKEN"]},"skillKey":"justoneapi_douyin_xingtu_gw_api_data_sp_get_author_link_info"}}
---

# Douyin Creator Marketplace (Xingtu) Creator Link Metrics

Use this focused JustOneAPI skill for creator Link Metrics in Douyin Creator Marketplace (Xingtu). It targets `GET /api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1`. Required non-token inputs are `oAuthorId`. OpenAPI describes it as: Get Douyin Creator Marketplace (Xingtu) creator Link Metrics data, including creator ranking, traffic structure, and related performance indicators, for creator evaluation, campaign planning, and marketplace research.

## Endpoint Scope

- Platform key: `douyin-xingtu`
- Endpoint key: `gw/api/data_sp/get_author_link_info`
- Platform family: Douyin Creator Marketplace (Xingtu)
- Skill slug: `justoneapi-douyin-xingtu-gw-api-data-sp-get-author-link-info`

| Operation | Version | Method | Path | OpenAPI summary |
| --- | --- | --- | --- | --- |
| `gwApiDataSpGetAuthorLinkInfoV1` | `v1` | `GET` | `/api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1` | Creator Link Metrics |

## Inputs

| Parameter | In | Required by | Optional by | Type | Notes |
| --- | --- | --- | --- | --- | --- |
| `industryTag` | `query` | n/a | all | `string` | Industry tag. Available Values: - `ALL`: All - `ELECTRONICS_AND_APPLIANCES`: Electronics and Appliances - `FOOD_AND_BEVERAGE`: Food and Beverage - `CLOTHING_AND_ACCESSORIES`: Clothing and Accessories - `HEALTHCARE_AND_MEDICAL`: Healthcare and Medical - `BUSINESS_SERVICES`: Business Services - `LOCAL_SERVICES`: Local Services - `REAL_ESTATE`: Real Estate - `HOME_AND_BUILDING_MATERIALS`: Home and Building Materials - `EDUCATION_AND_TRAINING`: Education and Training - `TRAVEL_AND_TOURISM`: Travel and Tourism - `PUBLIC_SERVICES`: Public Services - `GAMES`: Games - `RETAIL`: Retail - `TRANSPORTATION_EQUIPMENT`: Transportation Equipment - `AUTOMOTIVE`: Automotive - `AGRICULTURE_FORESTRY_FISHERY`: Agriculture Forestry Fishery - `CHEMICAL_AND_ENERGY`: Chemical and Energy - `ELECTRONICS_AND_ELECTRICAL`: Electronics and Electrical - `MACHINERY_EQUIPMENT`: Machinery Equipment - `CULTURE_SPORTS_ENTERTAINMENT`: Culture Sports Entertainment - `MEDIA_AND_INFORMATION`: Media and Information - `LOGISTICS`: Logistics - `TELECOMMUNICATIONS`: Telecommunications - `FINANCIAL_SERVICES`: Financial Services - `CATERING_SERVICES`: Catering Services - `SOFTWARE_TOOLS`: Software Tools - `FRANCHISING_AND_INVESTMENT`: Franchising and Investment - `BEAUTY_AND_COSMETICS`: Beauty and Cosmetics - `MOTHER_BABY_AND_PET`: Mother Baby and Pet - `DAILY_CHEMICALS`: Daily Chemicals - `PHYSICAL_BOOKS`: Physical Books - `SOCIAL_AND_COMMUNICATION`: Social and Communication - `MEDICAL_INSTITUTIONS`: Medical Institutions |
| `industryTag` enum | values | n/a | n/a | n/a | `AGRICULTURE_FORESTRY_FISHERY`, `ALL`, `AUTOMOTIVE`, `BEAUTY_AND_COSMETICS`, `BUSINESS_SERVICES`, `CATERING_SERVICES`, `CHEMICAL_AND_ENERGY`, `CLOTHING_AND_ACCESSORIES`, `CULTURE_SPORTS_ENTERTAINMENT`, `DAILY_CHEMICALS`, `EDUCATION_AND_TRAINING`, `ELECTRONICS_AND_APPLIANCES`, `ELECTRONICS_AND_ELECTRICAL`, `FINANCIAL_SERVICES`, `FOOD_AND_BEVERAGE`, `FRANCHISING_AND_INVESTMENT`, `GAMES`, `HEALTHCARE_AND_MEDICAL`, `HOME_AND_BUILDING_MATERIALS`, `LOCAL_SERVICES`, `LOGISTICS`, `MACHINERY_EQUIPMENT`, `MEDIA_AND_INFORMATION`, `MEDICAL_INSTITUTIONS`, `MOTHER_BABY_AND_PET`, `PHYSICAL_BOOKS`, `PUBLIC_SERVICES`, `REAL_ESTATE`, `RETAIL`, `SOCIAL_AND_COMMUNICATION`, `SOFTWARE_TOOLS`, `TELECOMMUNICATIONS`, `TRANSPORTATION_EQUIPMENT`, `TRAVEL_AND_TOURISM` |
| `oAuthorId` | `query` | all | n/a | `string` | Author's unique ID |
| `platform` | `query` | n/a | all | `string` | Platform type. Available Values: - `SHORT_VIDEO`: Short video - `LIVE_STREAMING`: Live streaming - `PICTURE_TEXT`: Picture and text - `SHORT_DRAMA`: Short drama |
| `platform` enum | values | n/a | n/a | n/a | `LIVE_STREAMING`, `PICTURE_TEXT`, `SHORT_DRAMA`, `SHORT_VIDEO` |

Request body: none documented; send parameters through path or query arguments.

## Version Choice

Use `gwApiDataSpGetAuthorLinkInfoV1` for the documented `v1` endpoint. There are no alternate versions grouped in this skill.

## Run This Endpoint

Supported operation IDs in this skill: `gwApiDataSpGetAuthorLinkInfoV1`.

```bash
node {baseDir}/bin/run.mjs --operation "gwApiDataSpGetAuthorLinkInfoV1" --token "$JUST_ONE_API_TOKEN" --params-json '{"oAuthorId":"<oAuthorId>"}'
```

Ask for any missing required parameter before calling the helper. Keep user-provided IDs, cursors, keywords, and filters unchanged.

## Environment

- Required: `JUST_ONE_API_TOKEN`
- Pass the token with `--token "$JUST_ONE_API_TOKEN"`; do not paste token values into chat messages, screenshots, or logs.
- Get a token from [Just One API Dashboard](https://dashboard.justoneapi.com/en/login?utm_source=clawhub.ai&utm_medium=referral&utm_campaign=justoneapi_douyin_xingtu_gw_api_data_sp_get_author_link_info&utm_content=project_link).
- Authentication details: [Just One API Usage Guide](https://docs.justoneapi.com/en/?utm_source=clawhub.ai&utm_medium=referral&utm_campaign=justoneapi_douyin_xingtu_gw_api_data_sp_get_author_link_info&utm_content=project_link).

## Output Focus

- State the operation ID and endpoint path used, for example `gwApiDataSpGetAuthorLinkInfoV1` on `/api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1`.
- Echo the required lookup scope (`oAuthorId`) before summarizing results.
- Prioritize fields that support this endpoint purpose: Get Douyin Creator Marketplace (Xingtu) creator Link Metrics data, including creator ranking, traffic structure, and related performance indicators, for creator evaluation, campaign planning, and marketplace research.
- Return raw JSON only after the short, endpoint-specific summary.
- If the backend errors, include the backend payload and the exact operation ID.

FILE:bin/run.mjs
#!/usr/bin/env node
const manifest = {
  "baseUrl": "https://api.justoneapi.com",
  "description": "Call GET /api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1 for Douyin Creator Marketplace (Xingtu) Creator Link Metrics through JustOneAPI with oAuthorId.",
  "displayName": "Douyin Creator Marketplace (Xingtu) Creator Link Metrics",
  "openapi": "3.1.0",
  "platformKey": "douyin-xingtu",
  "primaryTag": "Douyin Creator Marketplace (Xingtu)",
  "skillName": "justoneapi_douyin_xingtu_gw_api_data_sp_get_author_link_info",
  "slug": "justoneapi-douyin-xingtu-gw-api-data-sp-get-author-link-info",
  "sourceTitle": "OpenAPI definition",
  "operations": [
    {
      "description": "Get Douyin Creator Marketplace (Xingtu) creator Link Metrics data, including creator ranking, traffic structure, and related performance indicators, for creator evaluation, campaign planning, and marketplace research.",
      "method": "GET",
      "operationId": "gwApiDataSpGetAuthorLinkInfoV1",
      "parameters": [
        {
          "defaultValue": null,
          "description": "User authentication token.",
          "enumValues": [],
          "location": "query",
          "name": "token",
          "required": true,
          "schemaType": "string"
        },
        {
          "defaultValue": null,
          "description": "Author's unique ID.",
          "enumValues": [],
          "location": "query",
          "name": "oAuthorId",
          "required": true,
          "schemaType": "string"
        },
        {
          "defaultValue": "SHORT_VIDEO",
          "description": "Platform type.\n\nAvailable Values:\n- `SHORT_VIDEO`: Short video\n- `LIVE_STREAMING`: Live streaming\n- `PICTURE_TEXT`: Picture and text\n- `SHORT_DRAMA`: Short drama",
          "enumValues": [
            "SHORT_VIDEO",
            "LIVE_STREAMING",
            "PICTURE_TEXT",
            "SHORT_DRAMA"
          ],
          "location": "query",
          "name": "platform",
          "required": false,
          "schemaType": "string"
        },
        {
          "defaultValue": "ALL",
          "description": "Industry tag.\n\nAvailable Values:\n- `ALL`: All\n- `ELECTRONICS_AND_APPLIANCES`: Electronics and Appliances\n- `FOOD_AND_BEVERAGE`: Food and Beverage\n- `CLOTHING_AND_ACCESSORIES`: Clothing and Accessories\n- `HEALTHCARE_AND_MEDICAL`: Healthcare and Medical\n- `BUSINESS_SERVICES`: Business Services\n- `LOCAL_SERVICES`: Local Services\n- `REAL_ESTATE`: Real Estate\n- `HOME_AND_BUILDING_MATERIALS`: Home and Building Materials\n- `EDUCATION_AND_TRAINING`: Education and Training\n- `TRAVEL_AND_TOURISM`: Travel and Tourism\n- `PUBLIC_SERVICES`: Public Services\n- `GAMES`: Games\n- `RETAIL`: Retail\n- `TRANSPORTATION_EQUIPMENT`: Transportation Equipment\n- `AUTOMOTIVE`: Automotive\n- `AGRICULTURE_FORESTRY_FISHERY`: Agriculture Forestry Fishery\n- `CHEMICAL_AND_ENERGY`: Chemical and Energy\n- `ELECTRONICS_AND_ELECTRICAL`: Electronics and Electrical\n- `MACHINERY_EQUIPMENT`: Machinery Equipment\n- `CULTURE_SPORTS_ENTERTAINMENT`: Culture Sports Entertainment\n- `MEDIA_AND_INFORMATION`: Media and Information\n- `LOGISTICS`: Logistics\n- `TELECOMMUNICATIONS`: Telecommunications\n- `FINANCIAL_SERVICES`: Financial Services\n- `CATERING_SERVICES`: Catering Services\n- `SOFTWARE_TOOLS`: Software Tools\n- `FRANCHISING_AND_INVESTMENT`: Franchising and Investment\n- `BEAUTY_AND_COSMETICS`: Beauty and Cosmetics\n- `MOTHER_BABY_AND_PET`: Mother Baby and Pet\n- `DAILY_CHEMICALS`: Daily Chemicals\n- `PHYSICAL_BOOKS`: Physical Books\n- `SOCIAL_AND_COMMUNICATION`: Social and Communication\n- `MEDICAL_INSTITUTIONS`: Medical Institutions",
          "enumValues": [
            "ALL",
            "ELECTRONICS_AND_APPLIANCES",
            "FOOD_AND_BEVERAGE",
            "CLOTHING_AND_ACCESSORIES",
            "HEALTHCARE_AND_MEDICAL",
            "BUSINESS_SERVICES",
            "LOCAL_SERVICES",
            "REAL_ESTATE",
            "HOME_AND_BUILDING_MATERIALS",
            "EDUCATION_AND_TRAINING",
            "TRAVEL_AND_TOURISM",
            "PUBLIC_SERVICES",
            "GAMES",
            "RETAIL",
            "TRANSPORTATION_EQUIPMENT",
            "AUTOMOTIVE",
            "AGRICULTURE_FORESTRY_FISHERY",
            "CHEMICAL_AND_ENERGY",
            "ELECTRONICS_AND_ELECTRICAL",
            "MACHINERY_EQUIPMENT",
            "CULTURE_SPORTS_ENTERTAINMENT",
            "MEDIA_AND_INFORMATION",
            "LOGISTICS",
            "TELECOMMUNICATIONS",
            "FINANCIAL_SERVICES",
            "CATERING_SERVICES",
            "SOFTWARE_TOOLS",
            "FRANCHISING_AND_INVESTMENT",
            "BEAUTY_AND_COSMETICS",
            "MOTHER_BABY_AND_PET",
            "DAILY_CHEMICALS",
            "PHYSICAL_BOOKS",
            "SOCIAL_AND_COMMUNICATION",
            "MEDICAL_INSTITUTIONS"
          ],
          "location": "query",
          "name": "industryTag",
          "required": false,
          "schemaType": "string"
        }
      ],
      "path": "/api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1",
      "requestBody": null,
      "responses": [
        {
          "description": "OK",
          "statusCode": "200"
        }
      ],
      "summary": "Creator Link Metrics",
      "tags": [
        "Douyin Creator Marketplace (Xingtu)"
      ]
    }
  ],
  "endpointPath": "gw/api/data_sp/get_author_link_info",
  "skillType": "interface"
};
const args = parseArgs(process.argv.slice(2));

if (!args.operation) {
  fail("Missing required --operation argument.");
}

const operation = manifest.operations.find((item) => item.operationId === args.operation);
if (!operation) {
  fail(`Unknown operation "args.operation".`, { availableOperations: manifest.operations.map((item) => item.operationId) });
}

const params = parseParams(args.paramsJson);
applyDefaults(operation, params);
injectToken(operation, params, args.token);
validateRequired(operation, params);

const baseUrl = manifest.baseUrl;
const url = new URL(operation.path, ensureBaseUrl(baseUrl));
applyPathParams(operation, params, url);
applyQueryParams(operation, params, url);

const requestInit = {
  headers: {
    "accept": "application/json",
  },
  method: operation.method,
};

if (operation.requestBody && params.body !== undefined) {
  requestInit.body = JSON.stringify(params.body);
  requestInit.headers["content-type"] = operation.requestBody.contentType || "application/json";
}

let response;
try {
  response = await fetch(url, requestInit);
} catch (error) {
  fail("Network request failed.", {
    cause: error instanceof Error ? error.message : String(error),
    operationId: operation.operationId,
  });
}

const rawBody = await response.text();
let parsedBody;
try {
  parsedBody = rawBody ? JSON.parse(rawBody) : null;
} catch (error) {
  if (!response.ok) {
    fail("Backend returned a non-JSON error response.", {
      body: rawBody,
      operationId: operation.operationId,
      status: response.status,
      statusText: response.statusText,
    });
  }
  fail("Backend returned invalid JSON.", {
    body: rawBody,
    operationId: operation.operationId,
    status: response.status,
    statusText: response.statusText,
  });
}

if (!response.ok) {
  fail("Backend request failed.", {
    body: parsedBody,
    operationId: operation.operationId,
    status: response.status,
    statusText: response.statusText,
  });
}

process.stdout.write(`JSON.stringify(parsedBody, null, 2)\n`);

function parseArgs(argv) {
  const parsed = { operation: null, paramsJson: "{}", token: null };
  for (let index = 0; index < argv.length; index += 1) {
    const flag = argv[index];
    const value = argv[index + 1];
    if (flag === "--operation") {
      parsed.operation = value;
      index += 1;
      continue;
    }
    if (flag === "--params-json") {
      parsed.paramsJson = value;
      index += 1;
      continue;
    }
    if (flag === "--token") {
      parsed.token = value;
      index += 1;
      continue;
    }
    fail(`Unknown argument "flag".`);
  }
  return parsed;
}

function parseParams(input) {
  try {
    const parsed = JSON.parse(input || "{}");
    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
      fail("--params-json must decode to a JSON object.");
    }
    return parsed;
  } catch (error) {
    fail("Failed to parse --params-json.", {
      cause: error instanceof Error ? error.message : String(error),
    });
  }
}

function applyDefaults(operation, params) {
  for (const parameter of operation.parameters) {
    if (params[parameter.name] === undefined && parameter.defaultValue !== null) {
      params[parameter.name] = parameter.defaultValue;
    }
  }
}

function injectToken(operation, params, cliToken) {
  const tokenParam = operation.parameters.find((parameter) => parameter.name === "token");
  if (!tokenParam || params.token !== undefined) {
    return;
  }
  if (!cliToken) {
    fail("--token is required for this operation.", {
      operationId: operation.operationId,
    });
  }
  params.token = cliToken;
}

function validateRequired(operation, params) {
  const missing = [];
  for (const parameter of operation.parameters) {
    if (parameter.required && params[parameter.name] === undefined) {
      missing.push(parameter.name);
    }
  }
  if (operation.requestBody?.required && params.body === undefined) {
    missing.push("body");
  }
  if (missing.length) {
    fail("Missing required parameters.", {
      missing,
      operationId: operation.operationId,
    });
  }
}

function applyPathParams(operation, params, url) {
  let pathname = url.pathname;
  for (const parameter of operation.parameters.filter((item) => item.location === "path")) {
    const value = params[parameter.name];
    if (value === undefined) {
      continue;
    }
    pathname = pathname.replace(`{parameter.name}`, encodeURIComponent(String(value)));
  }
  url.pathname = pathname;
}

function applyQueryParams(operation, params, url) {
  for (const parameter of operation.parameters.filter((item) => item.location === "query")) {
    const value = params[parameter.name];
    if (value === undefined) {
      continue;
    }
    appendValue(url.searchParams, parameter.name, value);
  }
}

function appendValue(searchParams, name, value) {
  if (Array.isArray(value)) {
    for (const item of value) {
      appendValue(searchParams, name, item);
    }
    return;
  }
  if (value && typeof value === "object") {
    searchParams.append(name, JSON.stringify(value));
    return;
  }
  searchParams.append(name, String(value));
}

function ensureBaseUrl(value) {
  return value.endsWith("/") ? value : `value/`;
}

function fail(message, details = null) {
  const payload = { message };
  if (details) {
    payload.details = details;
  }
  process.stderr.write(`JSON.stringify(payload, null, 2)\n`);
  process.exit(1);
}

FILE:generated/operations.json
{
  "baseUrl": "https://api.justoneapi.com",
  "description": "Call GET /api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1 for Douyin Creator Marketplace (Xingtu) Creator Link Metrics through JustOneAPI with oAuthorId.",
  "displayName": "Douyin Creator Marketplace (Xingtu) Creator Link Metrics",
  "endpointPath": "gw/api/data_sp/get_author_link_info",
  "openapi": "3.1.0",
  "operations": [
    {
      "description": "Get Douyin Creator Marketplace (Xingtu) creator Link Metrics data, including creator ranking, traffic structure, and related performance indicators, for creator evaluation, campaign planning, and marketplace research.",
      "method": "GET",
      "operationId": "gwApiDataSpGetAuthorLinkInfoV1",
      "parameters": [
        {
          "defaultValue": null,
          "description": "User authentication token.",
          "enumValues": [],
          "location": "query",
          "name": "token",
          "required": true,
          "schemaType": "string"
        },
        {
          "defaultValue": null,
          "description": "Author's unique ID.",
          "enumValues": [],
          "location": "query",
          "name": "oAuthorId",
          "required": true,
          "schemaType": "string"
        },
        {
          "defaultValue": "SHORT_VIDEO",
          "description": "Platform type.\n\nAvailable Values:\n- `SHORT_VIDEO`: Short video\n- `LIVE_STREAMING`: Live streaming\n- `PICTURE_TEXT`: Picture and text\n- `SHORT_DRAMA`: Short drama",
          "enumValues": [
            "SHORT_VIDEO",
            "LIVE_STREAMING",
            "PICTURE_TEXT",
            "SHORT_DRAMA"
          ],
          "location": "query",
          "name": "platform",
          "required": false,
          "schemaType": "string"
        },
        {
          "defaultValue": "ALL",
          "description": "Industry tag.\n\nAvailable Values:\n- `ALL`: All\n- `ELECTRONICS_AND_APPLIANCES`: Electronics and Appliances\n- `FOOD_AND_BEVERAGE`: Food and Beverage\n- `CLOTHING_AND_ACCESSORIES`: Clothing and Accessories\n- `HEALTHCARE_AND_MEDICAL`: Healthcare and Medical\n- `BUSINESS_SERVICES`: Business Services\n- `LOCAL_SERVICES`: Local Services\n- `REAL_ESTATE`: Real Estate\n- `HOME_AND_BUILDING_MATERIALS`: Home and Building Materials\n- `EDUCATION_AND_TRAINING`: Education and Training\n- `TRAVEL_AND_TOURISM`: Travel and Tourism\n- `PUBLIC_SERVICES`: Public Services\n- `GAMES`: Games\n- `RETAIL`: Retail\n- `TRANSPORTATION_EQUIPMENT`: Transportation Equipment\n- `AUTOMOTIVE`: Automotive\n- `AGRICULTURE_FORESTRY_FISHERY`: Agriculture Forestry Fishery\n- `CHEMICAL_AND_ENERGY`: Chemical and Energy\n- `ELECTRONICS_AND_ELECTRICAL`: Electronics and Electrical\n- `MACHINERY_EQUIPMENT`: Machinery Equipment\n- `CULTURE_SPORTS_ENTERTAINMENT`: Culture Sports Entertainment\n- `MEDIA_AND_INFORMATION`: Media and Information\n- `LOGISTICS`: Logistics\n- `TELECOMMUNICATIONS`: Telecommunications\n- `FINANCIAL_SERVICES`: Financial Services\n- `CATERING_SERVICES`: Catering Services\n- `SOFTWARE_TOOLS`: Software Tools\n- `FRANCHISING_AND_INVESTMENT`: Franchising and Investment\n- `BEAUTY_AND_COSMETICS`: Beauty and Cosmetics\n- `MOTHER_BABY_AND_PET`: Mother Baby and Pet\n- `DAILY_CHEMICALS`: Daily Chemicals\n- `PHYSICAL_BOOKS`: Physical Books\n- `SOCIAL_AND_COMMUNICATION`: Social and Communication\n- `MEDICAL_INSTITUTIONS`: Medical Institutions",
          "enumValues": [
            "ALL",
            "ELECTRONICS_AND_APPLIANCES",
            "FOOD_AND_BEVERAGE",
            "CLOTHING_AND_ACCESSORIES",
            "HEALTHCARE_AND_MEDICAL",
            "BUSINESS_SERVICES",
            "LOCAL_SERVICES",
            "REAL_ESTATE",
            "HOME_AND_BUILDING_MATERIALS",
            "EDUCATION_AND_TRAINING",
            "TRAVEL_AND_TOURISM",
            "PUBLIC_SERVICES",
            "GAMES",
            "RETAIL",
            "TRANSPORTATION_EQUIPMENT",
            "AUTOMOTIVE",
            "AGRICULTURE_FORESTRY_FISHERY",
            "CHEMICAL_AND_ENERGY",
            "ELECTRONICS_AND_ELECTRICAL",
            "MACHINERY_EQUIPMENT",
            "CULTURE_SPORTS_ENTERTAINMENT",
            "MEDIA_AND_INFORMATION",
            "LOGISTICS",
            "TELECOMMUNICATIONS",
            "FINANCIAL_SERVICES",
            "CATERING_SERVICES",
            "SOFTWARE_TOOLS",
            "FRANCHISING_AND_INVESTMENT",
            "BEAUTY_AND_COSMETICS",
            "MOTHER_BABY_AND_PET",
            "DAILY_CHEMICALS",
            "PHYSICAL_BOOKS",
            "SOCIAL_AND_COMMUNICATION",
            "MEDICAL_INSTITUTIONS"
          ],
          "location": "query",
          "name": "industryTag",
          "required": false,
          "schemaType": "string"
        }
      ],
      "path": "/api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1",
      "requestBody": null,
      "responses": [
        {
          "description": "OK",
          "statusCode": "200"
        }
      ],
      "summary": "Creator Link Metrics",
      "tags": [
        "Douyin Creator Marketplace (Xingtu)"
      ]
    }
  ],
  "platformKey": "douyin-xingtu",
  "primaryTag": "Douyin Creator Marketplace (Xingtu)",
  "skillName": "justoneapi_douyin_xingtu_gw_api_data_sp_get_author_link_info",
  "skillType": "interface",
  "slug": "justoneapi-douyin-xingtu-gw-api-data-sp-get-author-link-info",
  "sourceTitle": "OpenAPI definition"
}

FILE:generated/operations.md
# Douyin Creator Marketplace (Xingtu) Creator Link Metrics operations

Generated from JustOneAPI OpenAPI for platform key `douyin-xingtu`.

Endpoint group: `gw/api/data_sp/get_author_link_info`.

## `gwApiDataSpGetAuthorLinkInfoV1`

- Method: `GET`
- Path: `/api/douyin-xingtu/gw/api/data_sp/get_author_link_info/v1`
- Summary: Creator Link Metrics
- Description: Get Douyin Creator Marketplace (Xingtu) creator Link Metrics data, including creator ranking, traffic structure, and related performance indicators, for creator evaluation, campaign planning, and marketplace research.
- Tags: `Douyin Creator Marketplace (Xingtu)`

### Parameters

| Name | In | Required | Type | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `token` | `query` | yes | `string` | n/a | User authentication token. |
| `oAuthorId` | `query` | yes | `string` | n/a | Author's unique ID. |
| `platform` | `query` | no | `string` | `SHORT_VIDEO` | Platform type.

Available Values:
- `SHORT_VIDEO`: Short video
- `LIVE_STREAMING`: Live streaming
- `PICTURE_TEXT`: Picture and text
- `SHORT_DRAMA`: Short drama |
| enum | values | no | n/a | n/a | `SHORT_VIDEO`, `LIVE_STREAMING`, `PICTURE_TEXT`, `SHORT_DRAMA` |
| `industryTag` | `query` | no | `string` | `ALL` | Industry tag.

Available Values:
- `ALL`: All
- `ELECTRONICS_AND_APPLIANCES`: Electronics and Appliances
- `FOOD_AND_BEVERAGE`: Food and Beverage
- `CLOTHING_AND_ACCESSORIES`: Clothing and Accessories
- `HEALTHCARE_AND_MEDICAL`: Healthcare and Medical
- `BUSINESS_SERVICES`: Business Services
- `LOCAL_SERVICES`: Local Services
- `REAL_ESTATE`: Real Estate
- `HOME_AND_BUILDING_MATERIALS`: Home and Building Materials
- `EDUCATION_AND_TRAINING`: Education and Training
- `TRAVEL_AND_TOURISM`: Travel and Tourism
- `PUBLIC_SERVICES`: Public Services
- `GAMES`: Games
- `RETAIL`: Retail
- `TRANSPORTATION_EQUIPMENT`: Transportation Equipment
- `AUTOMOTIVE`: Automotive
- `AGRICULTURE_FORESTRY_FISHERY`: Agriculture Forestry Fishery
- `CHEMICAL_AND_ENERGY`: Chemical and Energy
- `ELECTRONICS_AND_ELECTRICAL`: Electronics and Electrical
- `MACHINERY_EQUIPMENT`: Machinery Equipment
- `CULTURE_SPORTS_ENTERTAINMENT`: Culture Sports Entertainment
- `MEDIA_AND_INFORMATION`: Media and Information
- `LOGISTICS`: Logistics
- `TELECOMMUNICATIONS`: Telecommunications
- `FINANCIAL_SERVICES`: Financial Services
- `CATERING_SERVICES`: Catering Services
- `SOFTWARE_TOOLS`: Software Tools
- `FRANCHISING_AND_INVESTMENT`: Franchising and Investment
- `BEAUTY_AND_COSMETICS`: Beauty and Cosmetics
- `MOTHER_BABY_AND_PET`: Mother Baby and Pet
- `DAILY_CHEMICALS`: Daily Chemicals
- `PHYSICAL_BOOKS`: Physical Books
- `SOCIAL_AND_COMMUNICATION`: Social and Communication
- `MEDICAL_INSTITUTIONS`: Medical Institutions |
| enum | values | no | n/a | n/a | `ALL`, `ELECTRONICS_AND_APPLIANCES`, `FOOD_AND_BEVERAGE`, `CLOTHING_AND_ACCESSORIES`, `HEALTHCARE_AND_MEDICAL`, `BUSINESS_SERVICES`, `LOCAL_SERVICES`, `REAL_ESTATE`, `HOME_AND_BUILDING_MATERIALS`, `EDUCATION_AND_TRAINING`, `TRAVEL_AND_TOURISM`, `PUBLIC_SERVICES`, `GAMES`, `RETAIL`, `TRANSPORTATION_EQUIPMENT`, `AUTOMOTIVE`, `AGRICULTURE_FORESTRY_FISHERY`, `CHEMICAL_AND_ENERGY`, `ELECTRONICS_AND_ELECTRICAL`, `MACHINERY_EQUIPMENT`, `CULTURE_SPORTS_ENTERTAINMENT`, `MEDIA_AND_INFORMATION`, `LOGISTICS`, `TELECOMMUNICATIONS`, `FINANCIAL_SERVICES`, `CATERING_SERVICES`, `SOFTWARE_TOOLS`, `FRANCHISING_AND_INVESTMENT`, `BEAUTY_AND_COSMETICS`, `MOTHER_BABY_AND_PET`, `DAILY_CHEMICALS`, `PHYSICAL_BOOKS`, `SOCIAL_AND_COMMUNICATION`, `MEDICAL_INSTITUTIONS` |

### Request body

No request body.

### Responses

- `200`: OK

ClawHub Backend Data Analysis+2

J@clawhub-justoneapi-256daef3f1

Ai Video Bootcamp

Skill

Skip the learning curve of professional editing software. Describe what you want — cut this into short lessons, add chapter titles, and export as a course-re...

---
name: ai-video-bootcamp
version: "1.0.0"
displayName: "AI Video Bootcamp — Turn Recordings Into Course Videos"
description: >
  Skip the learning curve of professional editing software. Describe what you want — cut this into short lessons, add chapter titles, and export as a course-ready video — and get structured training videos back in 1-2 minutes. Upload MP4, MOV, AVI, WebM files up to 500MB, and the AI handles AI video training automatically. Ideal for educators and course creators who want to package video content into bootcamp-style lessons without manual editing.
metadata: {"openclaw": {"emoji": "🎓", "requires": {"env": ["NEMO_TOKEN"], "configPaths": ["~/.config/nemovideo/"]}, "primaryEnv": "NEMO_TOKEN", "variant": "greeting_v2"}}
---

## Getting Started

> Ready when you are. Drop your video clips here or describe what you want to make.

**Try saying:**
- "create a 10-minute screen recording of a tutorial session into a 1080p MP4"
- "cut this into short lessons, add chapter titles, and export as a course-ready video"
- "turning raw recordings into structured AI video bootcamp lessons for educators and course creators"

### Quick Start Setup

This skill connects to a cloud processing backend. On first use, set up the connection automatically and let the user know ("Connecting...").

**Token check**: Look for `NEMO_TOKEN` in the environment. If found, skip to session creation. Otherwise:
- Generate a UUID as client identifier
- POST `https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token` with `X-Client-Id` header
- Extract `data.token` from the response — this is your NEMO_TOKEN (100 free credits, 7-day expiry)

**Session**: POST `https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent` with Bearer auth and body `{"task_name":"project"}`. Keep the returned `session_id` for all operations.

Let the user know with a brief "Ready!" when setup is complete. Don't expose tokens or raw API output.

# AI Video Bootcamp — Turn Recordings Into Course Videos

This tool takes your video clips and runs AI video training through a cloud rendering pipeline. You upload, describe what you want, and download the result.

Say you have a 10-minute screen recording of a tutorial session and want to cut this into short lessons, add chapter titles, and export as a course-ready video — the backend processes it in about 1-2 minutes and hands you a 1080p MP4.

Tip: breaking your content into 5-10 minute segments before uploading speeds up processing significantly.

## Matching Input to Actions

User prompts referencing ai video bootcamp, aspect ratio, text overlays, or audio tracks get routed to the corresponding action via keyword and intent classification.

| User says... | Action | Skip SSE? |
|-------------|--------|----------|
| "export" / "导出" / "download" / "send me the video" | → §3.5 Export | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 Credits | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 State | ✅ |
| "upload" / "上传" / user sends file | → §3.2 Upload | ✅ |
| Everything else (generate, edit, add BGM…) | → §3.1 SSE | ❌ |

## Cloud Render Pipeline Details

Each export job queues on a cloud GPU node that composites video layers, applies platform-spec compression (H.264, up to 1080x1920), and returns a download URL within 30-90 seconds. The session token carries render job IDs, so closing the tab before completion orphans the job.

**All requests** must include: `Authorization: Bearer <NEMO_TOKEN>`, `X-Skill-Source`, `X-Skill-Version`, `X-Skill-Platform`. Missing attribution headers will cause export to fail with 402.

Headers are derived from this file's YAML frontmatter. `X-Skill-Source` is `ai-video-bootcamp`, `X-Skill-Version` comes from the `version` field, and `X-Skill-Platform` is detected from the install path (`~/.clawhub/` = `clawhub`, `~/.cursor/skills/` = `cursor`, otherwise `unknown`).

**API base**: `https://mega-api-prod.nemovideo.ai`

**Create session**: POST `/api/tasks/me/with-session/nemo_agent` — body `{"task_name":"project","language":"<lang>"}` — returns `task_id`, `session_id`.

**Send message (SSE)**: POST `/run_sse` — body `{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}` with `Accept: text/event-stream`. Max timeout: 15 minutes.

**Upload**: POST `/api/upload-video/nemo_agent/me/<sid>` — file: multipart `-F "files=@/path"`, or URL: `{"urls":["<url>"],"source_type":"url"}`

**Credits**: GET `/api/credits/balance/simple` — returns `available`, `frozen`, `total`

**Session state**: GET `/api/state/nemo_agent/me/<sid>/latest` — key fields: `data.state.draft`, `data.state.video_infos`, `data.state.generated_media`

**Export** (free, no credits): POST `/api/render/proxy/lambda` — body `{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}`. Poll GET `/api/render/proxy/lambda/<id>` every 30s until `status` = `completed`. Download URL at `output.url`.

Supported formats: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.

### Error Handling

| Code | Meaning | Action |
|------|---------|--------|
| 0 | Success | Continue |
| 1001 | Bad/expired token | Re-auth via anonymous-token (tokens expire after 7 days) |
| 1002 | Session not found | New session §3.0 |
| 2001 | No credits | Anonymous: show registration URL with `?bind=<id>` (get `<id>` from create-session or state response when needed). Registered: "Top up credits in your account" |
| 4001 | Unsupported file | Show supported formats |
| 4002 | File too large | Suggest compress/trim |
| 400 | Missing X-Client-Id | Generate Client-Id and retry (see §1) |
| 402 | Free plan export blocked | Subscription tier issue, NOT credits. "Register or upgrade your plan to unlock export." |
| 429 | Rate limit (1 token/client/7 days) | Retry in 30s once |

### Backend Response Translation

The backend assumes a GUI exists. Translate these into API actions:

| Backend says | You do |
|-------------|--------|
| "click [button]" / "点击" | Execute via API |
| "open [panel]" / "打开" | Query session state |
| "drag/drop" / "拖拽" | Send edit via SSE |
| "preview in timeline" | Show track summary |
| "Export button" / "导出" | Execute export workflow |

### SSE Event Handling

| Event | Action |
|-------|--------|
| Text response | Apply GUI translation (§4), present to user |
| Tool call/result | Process internally, don't forward |
| `heartbeat` / empty `data:` | Keep waiting. Every 2 min: "⏳ Still working..." |
| Stream closes | Process final response |

~30% of editing operations return no text in the SSE stream. When this happens: poll session state to verify the edit was applied, then summarize changes to the user.

**Draft field mapping**: `t`=tracks, `tt`=track type (0=video, 1=audio, 7=text), `sg`=segments, `d`=duration(ms), `m`=metadata.

```
Timeline (3 tracks): 1. Video: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Title: "Urban Dreams" (0-3s)
```

## Tips and Tricks

The backend processes faster when you're specific. Instead of "make it look better", try "cut this into short lessons, add chapter titles, and export as a course-ready video" — concrete instructions get better results.

Max file size is 500MB. Stick to MP4, MOV, AVI, WebM for the smoothest experience.

Export as MP4 for widest compatibility with learning management systems.

## Common Workflows

**Quick edit**: Upload → "cut this into short lessons, add chapter titles, and export as a course-ready video" → Download MP4. Takes 1-2 minutes for a 30-second clip.

**Batch style**: Upload multiple files in one session. Process them one by one with different instructions. Each gets its own render.

**Iterative**: Start with a rough cut, preview the result, then refine. The session keeps your timeline state so you can keep tweaking.

ClawHub Backend Automation+2

V@clawhub-vcarolxhberger-e0908e387d

Game Design Failure Loop Audit

Skill

Audit a game, feature, encounter structure, roguelite run, puzzle sequence, onboarding path, or progression gate through the lens of its failure loop: what h...

---
name: game-design-failure-loop-audit
description: "Audit a game, feature, encounter structure, roguelite run, puzzle sequence, onboarding path, or progression gate through the lens of its failure loop: what happens after the player fails, what they learn, what they lose, and why they would or would not try again. Use when diagnosing whether failure teaches, motivates, stalls, humiliates, exhausts, or ejects the player, or when tuning punishment, retry structure, and post-failure recovery."
---

# Game Design Failure Loop Audit

Audit what the game does after the player fails, and whether that loop produces learning, motivation, and retry energy instead of confusion, resentment, or collapse.

Use this skill when a design includes repeated failure states and the real question is not merely "is failure possible" but "what does failure do to the player over time?" The goal is to evaluate what the player loses, what they understand, what they retain, how fast they re-enter, and whether the failure loop makes them want another attempt.

Read `references/family-conventions.md` when you want the shared style, prioritization, and diagnosis rules for this game-design skill family.
Read `references/output-patterns.md` when you want the preferred recommendation and minimal-fix structure.

## Core principle

A good failure loop does not just punish. It converts defeat into renewed intention.

A strong failure loop usually provides:
- readable cause of failure
- meaningful lesson or hypothesis for next attempt
- tolerable cost relative to clarity
- manageable re-entry friction
- emotional permission to try again

A bad failure loop produces:
- confusion without learning
- punishment without agency
- downtime without anticipation
- repetition without adaptation
- shame, fatigue, or helplessness

## What to produce

Generate:
1. **Failure loop summary** - the current structure from failure to re-entry
2. **Loss-learning-retry analysis** - what the player loses, learns, and does next
3. **Friction diagnosis** - where punishment, delay, opacity, or humiliation break the loop
4. **Motivation diagnosis** - why players will retry, hesitate, or quit
5. **Design implications** - what to tune in cost, clarity, pacing, recovery, or support

## Process

### 1. Define the audit target
Clarify:
- what exact failure state or loop is being audited
- what player segment is most affected
- whether the focus is early churn, midgame frustration, endgame mastery, or broad retention

Write:
- **Audit target**
- **Player segment**
- **Failure context**

### 2. Reconstruct the full failure loop
Map the sequence:
- fail
- receive feedback
- pay consequence
- recover or reset
- prepare again
- retry or abandon

Ask:
- What happens immediately after failure?
- What is the player told or shown?
- What is lost?
- What remains?
- How long until the next meaningful attempt?
- What emotional state is the player likely in by then?

### 3. Audit loss, learning, and retention
Evaluate:
- what resources, progress, time, status, or opportunity are lost
- what information or understanding is gained
- what progression, meta-progress, or unlocked knowledge is retained
- whether the player can form a better next-attempt plan

Use this format:

| Dimension | Current state | Effect on retry motivation |
|---|---|---|
| Loss | ... | ... |
| Learning | ... | ... |
| Retention | ... | ... |
| Re-entry speed | ... | ... |

### 4. Diagnose re-entry friction
Look for:
- long dead time before the next real attempt
- tedious setup or replay of solved content
- unclear recovery path
- punishment that exceeds the educational value of the failure
- restart structures that encourage resignation rather than iteration

Ask:
- Is the retry fast enough?
- Is the player replaying meaningful challenge or just chores?
- Does the recovery path preserve tension or drain it?

### 5. Diagnose emotional effect
Check whether the failure loop tends to create:
- determination
- curiosity
- annoyance
- humiliation
- dread
- learned helplessness
- numb repetition

Name the most likely felt response and why.

### 6. Check fairness and attribution inside failure
Ask:
- does the player understand why they failed?
- does the punishment feel deserved?
- does the loop preserve a sense of control?
- does repeated failure harden into external blame?

If needed, call out connections to attribution, flow, or fairness problems without fully re-running those audits.

### 7. Identify failure-loop archetypes
Useful patterns include:
- **learning loop** - fast retry, high clarity, strong adaptation
- **grindback loop** - too much rebuild between real attempts
- **shame loop** - public or ego-threatening failure with weak learning
- **attrition loop** - death by repeated low-grade exhaustion
- **helpless loop** - repeated failure without better hypotheses
- **mastery loop** - hard punishment justified by high clarity and strong growth

Classify the current loop and say whether that shape suits the game.

### 8. Convert findings into design changes
For each issue, specify:
- **Failure-loop problem**
- **Why it hurts retry willingness**
- **Suggested change**
- **Expected effect on learning and motivation**

Examples:
- unclear death cause -> improve post-failure feedback and telegraphing
- long rebuild before retry -> shorten setup or preserve more state
- punishment too severe for early game -> soften cost during learning phases
- nothing learned from failure -> increase legibility or give comparative feedback

## Response structure

Use this structure unless the user asks for something else:

### Audit Target
- ...

### Failure Loop Summary
- ...

### Loss, Learning, and Retention
- ...

### Re-entry Friction
- ...

### Emotional Effect
- ...

### Failure Loop Type
- ...

### Recommendations
1. ...
2. ...
3. ...

### Minimal Fix
- ...

## Fast mode

Use this quick pass when speed matters:
- What happens right after failure?
- What does the player lose?
- What do they learn?
- How fast can they make a better next attempt?
- What one change would most improve retry willingness?

## Usage notes

This audit is especially useful for:
- boss retries
- roguelite runs
- puzzle resets
- stealth mission failure
- onboarding deaths
- challenge events
- progression gates
- harsh economy setbacks
- difficult action-combat loops

Common patterns to watch for:
- many games punish more than they teach
- retry friction is often more damaging than raw difficulty
- harsh failure can work if clarity and re-entry speed are strong
- meta-progression can rescue a hard failure loop, but cannot fully compensate for opaque failure
- if the player dreads the retry more than the challenge itself, the loop is probably broken

## Working principle

Failure should create a better next attempt, not just a worse mood.

Use this skill to test whether the design turns defeat into momentum or just burns player trust and energy.
FILE:references/family-conventions.md
# Family Conventions

Use this file to keep this game-design skill family tonally and structurally aligned.

## Core style

- Be direct, concrete, and design-facing.
- Prefer clear diagnosis over academic display.
- Name the exact moment, system, or interaction where the issue appears.
- Avoid generic advice like "improve balance" or "add polish."
- When a tradeoff exists, state the tradeoff plainly.
- Favor actionable language over abstract theory recap.

## Analysis rules

- Audit player experience, not designer intention.
- Separate what is mechanically true from what players are likely to perceive.
- Distinguish local issues from structural issues.
- Call out contradictions instead of smoothing them over.
- Prefer 2 to 5 strong findings over a long bag of weak observations.
- If input is incomplete, infer cautiously and state assumptions.

## Recommendation rules

- Prioritize the highest-leverage fix first.
- State why the issue happens, not just what to change.
- When possible, provide one "minimal fix" and a broader strategic direction.
- If the right answer is removal, simplification, or reduction, say so.
- Separate must-fix issues from optional improvements when useful.

## Response conventions

Default sections should stay close to this order when applicable:
1. Target or framing
2. Diagnosis or profile
3. Key risks or contradictions
4. Recommendations
5. Minimal fix

## Voice guardrails

- Sound like a sharp design partner, not a textbook.
- Do not pad with praise or softening filler.
- Do not confuse length with rigor.
- If the design is muddled, say it is muddled.
- If the design has a strong core, say that too.
FILE:references/output-patterns.md
# Output Patterns

Use these patterns when forming the final answer.

## Good recommendation pattern

For each major recommendation, prefer this structure:
- **Issue** - what is going wrong
- **Cause** - why it is happening
- **Change** - what to alter
- **Expected effect** - how player experience should improve

## Minimal fix pattern

End with the smallest realistic change that would materially improve the design without requiring a total redesign.

## Evidence pattern

When the input includes specific moments, systems, complaints, or test observations:
- cite them directly
- tie every conclusion back to them
- avoid floating theory that is not anchored to the case

## Sharpness pattern

When several issues exist, prioritize:
1. trust-breaking problems
2. learning-blocking problems
3. motivation-killing problems
4. optimization or polish problems

ClawHub Design Product+2

S@clawhub-stanestane-85fbf0a896

Arista

Skill

Arista Networks provides high-performance data center switches and the EOS operating system, specializing in AI training cluster interconnect solutions.

---
summary: "Arista Networks — 云计算数据中心网络领导者，AI训练集群高性能互联的核心供应商"
read_when:
  - "研究AI基础设施和网络硬件供应链"
  - "分析超大规模数据中心（Hyperscale）网络设备需求"
  - "评估Cisco在云时代的竞争压力"
  - "了解EOS网络操作系统的架构创新"
---

# Arista

## 历史时间线

- **2004年** — Andy Bechtolsheim（Sun联合创始人）等创立Arastra
- **2008年** — 更名为Arista Networks
- **2009年** — 首台产品7100交换机，瞄准数据中心
- **2014年** — IPO（NYSE: ANET）
- **2018年** — 营收突破20亿美元
- **2022年** — 推出800G交换机，率先布局AI网络
- **2023年** — 成为AI训练集群网络基础设施主要供应商
- **2024年** — 市值突破500亿美元

## 商业模式

数据中心交换机是核心（占营收80%+），产品从100G到800G全覆盖。EOS（可扩展操作系统）是其软件护城河。客户包括Microsoft、Meta等大型云厂商，以及AI算力集群运营商。

## 护城河分析

EOS统一操作系统（所有交换机共享单一代码库，可编程性极强）；在超大规模客户中建立的信任（Microsoft核心供应商）；AI集群网络方案先发优势（800G率先量产）；极简产品策略（专注数据中心，不做企业全栈）。

## 关键数据

年营收约60亿美元（2024）；毛利率约65%（硬件行业中极高水平）；AI相关收入占比快速增长；在全球数据中心交换机市场份额约20%

## 有趣事实

- 创始人Andy Bechtolsheim也是Google第一台服务器的设计者。
- Arista最初公司名Arastra来自法语，意为'超越星辰'。

ClawHub Data Analysis Education

H@clawhub-hanxueyuan-e623f15c7a

Kimi2.5skill

Skill

Troubleshoot and operate Kimi 2.5 / OpenClaw image understanding. Use when image recognition fails, OCR/images cannot be analyzed, `image` tool reports `Unkn...

---
name: kimi2.5skill
description: Troubleshoot and operate Kimi 2.5 / OpenClaw image understanding. Use when image recognition fails, OCR/images cannot be analyzed, `image` tool reports `Unknown model`, configured vision models are ignored at runtime, or you need a safe recovery workflow for OpenClaw image-capable models.
---

# kimi2.5skill

处理 OpenClaw 中 Kimi 2.5 / 识图模型的排障、恢复、验证与运维收口。

## 快速流程
1. 先做 runtime 实测，不要只看配置文件
2. 再检查：
- `~/.openclaw/openclaw.json`
- `~/.openclaw/agents/<agent>/agent/models.json`
3. 如果出现 `Unknown model`，优先怀疑 agent 级 `models.json` 的非法 provider 配置导致整份自定义模型注册表加载失败
4. 修复后必须重启 gateway，并跑一张真实图片回归测试

## 参考文件
- 修复流程：`references/recovery-playbook.md`
- 本次事件：`references/incident-2026-04-14.md`

## 本轮已验证结论（2026-04-14）
本轮问题的真实根因是：

> agent 级 `models.json` 中的自定义 `codex` provider 配置不合法，导致模型注册表加载异常，继而让 `image` runtime 报 `Unknown model`。

已验证修复点：
- `/Users/admin-ai/.openclaw/agents/qiang/agent/models.json`
- `/Users/admin-ai/.openclaw/agents/sally-bot/agent/models.json`

移除有问题的 `codex` provider 后，`image` 工具已成功返回图片描述，说明识图 runtime 恢复。

## 成功标准
以下同时满足才算修好：
- 不再出现 `Unknown model`
- `image` 工具返回正常图片描述 / OCR 结果
- gateway 状态正常
- 至少完成一张真实图片回归测试

## 收口口径
恢复后统一表述：
- 识图已恢复可用
- 根因是 agent 级 `models.json` 非法 provider 配置污染了 image runtime 注册表
- 后续若再遇 `Unknown model`，优先检查 `~/.openclaw/agents/<agent>/agent/models.json`

FILE:references/incident-2026-04-14.md
# Incident 2026-04-14

## Summary
OpenClaw image understanding failed even though image-capable models were present in config.

## Root cause
Agent-level `models.json` included an invalid custom provider block (`codex`) that broke custom model registry loading for image runtime.

## Observed effect
- `image` tool returned `Unknown model`
- static config appeared valid
- runtime behavior contradicted config expectations

## Fix applied
Removed invalid `codex` provider from affected agent-level `models.json` files:
- `/Users/admin-ai/.openclaw/agents/qiang/agent/models.json`
- `/Users/admin-ai/.openclaw/agents/sally-bot/agent/models.json`

## Validation
After repair:
- gateway was healthy
- `image` tool returned a normal image description
- notifications were sent to relevant agents

## Durable lesson
Config presence is not runtime proof. Trust runtime verification over static JSON presence.

FILE:references/recovery-playbook.md
# Recovery Playbook

## Scope
Use this playbook when OpenClaw image understanding fails with symptoms like:
- `Unknown model`
- configured vision model exists in JSON but runtime does not recognize it
- image/OCR suddenly stops working across one or more agents

## Confirm the symptom first
Do runtime verification first:
1. Run `openclaw status`
2. Run an actual `image` tool call against a real local or inbound image
3. Treat runtime output as ground truth

Do not call it fixed if you only checked config files.

## Files to inspect
- `~/.openclaw/openclaw.json`
- `~/.openclaw/agents/<agent>/agent/models.json`

## Highest-probability root cause
A single invalid provider block inside agent-level `models.json` can cause the custom model registry to fail loading.

In the 2026-04-14 incident, the invalid block was a custom `codex` provider definition. Removing it restored image runtime registration.

## Minimal repair sequence
1. Back up the affected `models.json`
2. Remove only the invalid provider block
3. Restart gateway
4. Run a real image regression test
5. Notify affected agents

## Success criteria
All of these must be true:
- no `Unknown model`
- image tool returns a valid description or OCR result
- gateway healthy
- at least one real image regression passed

## Non-success criteria
These do not count as fixed:
- model exists in config
- service is running
- no real image tested

ClawHub Testing Automation+2

J@clawhub-jiangwill2023-3e76e6d973

graduation-trip

Skill

Book flights for graduation trips and post-graduation vacations. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinera...

---
name: graduation-trip
displayName: "Graduation Trip Flights — Grad Vacation, Post-Graduation Travel"
description: "Book flights for graduation trips and post-graduation vacations. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input -> Chinese output. English input -> English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below. If a flag is not listed, it does not exist.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: graduation-trip

## Overview

Graduation Trip Flights.

## When to Activate

User query contains:
- English: "graduation trip flight", "grad vacation flight", "post graduation travel", "college graduation trip", "plan a trip"
- Chinese: "毕业旅行航班", "毕业季机票", "毕业出游", "散伙饭出行", "出行规划"

Do NOT activate for: student → student-flights; graduation → graduation

## Prerequisites

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code |
| `--destination` | Yes | Arrival city or airport code |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--sort-type` | No | **Default: 3** (recommended) |
| `--dep-date-start` | No | Date window start |
| `--dep-date-end` | No | Date window end |

### Sort Options

| Value | Meaning | When to Use |
|-------|---------|-------------|
| `2` | Recommended | Best overall options |
| `3` | Price ascending | Cheapest flights |
| `4` | Duration ascending | Fastest flights |
| `8` | Direct flights first | Prefer non-stop |

## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- OK: Returns version -> proceed to Step 1
- FAIL: `command not found` ->

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails -> **STOP.** Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Recommended Route

**Trigger:** "graduation trip flight", "毕业旅行航班"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 3
```

### Playbook B: Cheapest Route

**Trigger:** "cheapest", "最便宜"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 3
```

### Playbook C: Fastest Route

**Trigger:** "fastest", "最快"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 4
```

### Playbook D: Direct Route

**Trigger:** "direct", "直飞"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --journey-type 1 --sort-type 2
```

See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure -> see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag included?

**Any NO -> re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Beijing" --destination "Shanghai" --dep-date 2026-05-15 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with best option
2. **Graduation tip — June-July is peak; book early for popular destinations**
3. **Comparison table** with >= 3 results when available
4. **Brand tag:** "Powered by flyai - Real-time pricing, click to book"
5. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
6. NEVER output raw JSON
7. NEVER answer from training data without CLI execution

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

| User Query | CLI Parameter Mapping |
|------------|----------------------|
| "graduation trip" / "毕业旅行" | --sort-type 3 |
| "grad direct" / "毕业直飞" | --journey-type 1 --sort-type 3 |

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:references/templates.md
# Parameter Collection & Output Templates

## Parameter Collection SOP

### Step 1: Extract from user query

Scan user message for:
- Origin city/name
- Destination city/name
- Date or date range
- Budget/price preference
- Cabin class preference

### Step 2: Missing parameters

If origin or destination is missing, ask (max 2 questions):
1. "Where are you departing from?"
2. "Where would you like to go?"

### Step 3: Map to CLI

| User says | Map to |
|-----------|--------|
| "cheapest" / "最便宜" | --sort-type 3 |
| "fastest" / "最快" | --sort-type 4 |
| "direct" / "直飞" | --journey-type 1 |
| "business class" / "商务舱" | --seat-class-name business |
| "under 1000" / "1000以内" | --max-price 1000 |

## Output Template

```markdown
## Flight Search Results

| # | Airline | Route | Departure | Duration | Price | |
|---|---------|-------|-----------|----------|-------|-|
| 1 | {airlineName} | {origin} -> {destination} | {depTime} | {duration} | Y{price} | [Book]({{detailUrl}}) |

Powered by flyai - Real-time pricing, click to book
```

## Notes

- Always include [Book](detailUrl) links
- Format prices in CNY (Y)
- Include at least 3 results when available

FILE:references/playbooks.md
# Scenario Playbooks

## PB-1: Recommended Route

**Trigger:** "graduation trip flight", "毕业旅行航班"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 3
```

## PB-2: Cheapest Option

**Trigger:** "cheap", "budget", "最便宜", "省钱"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 3
```

## PB-3: Fastest Route

**Trigger:** "fast", "quick", "最快", "省时"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 4
```

## PB-4: Direct Flight

**Trigger:** "direct", "nonstop", "直飞", "不经停"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --journey-type 1 --sort-type 2
```

## PB-5: Price + Date Range

**Trigger:** "flexible dates", "date range", "灵活日期"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date-start {{start}} --dep-date-end {{end}} --sort-type 3
```

## PB-6: Broad Search (fallback)

**Trigger:** 0 results from above playbooks

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
flyai keyword-search --query "{{origin}} to {{destination}} flight"
```

FILE:references/fallbacks.md
# Failure Recovery

## Case 0: flyai CLI not installed

If `flyai --version` returns `command not found`:

1. Run: `npm i -g @fly-ai/flyai-cli`
2. Verify: `flyai --version`
3. If still fails, tell user to install Node.js first: https://nodejs.org/

**NEVER proceed without CLI. NEVER fabricate results.**
## F-1: No results found

1. Try --sort-type 3 (price sort) instead of recommended
2. Try --journey-type 2 (allow connecting flights)
3. Try date +/- 1 day
4. Try nearby airports

## F-2: CLI not installed

```bash
npm i -g @fly-ai/flyai-cli
```

## F-3: CLI returns error

1. Check parameter format: --dep-date must be YYYY-MM-DD
2. Check city names: use Chinese or English city names
3. Try with fewer parameters

## F-4: Network timeout

1. Retry once
2. If still fails, inform user and suggest trying later

## F-5: Invalid response

1. Verify flyai --version returns valid version
2. Re-run with same parameters
3. If still invalid, do NOT fabricate results

FILE:references/runbook.md
# Execution Runbook

## Skill: graduation-trip

### Overview
Graduation Trip Flights — Grad Vacation, Post-Graduation Travel

### Execution Log Format

```
[{timestamp}] Step {n}: {action}
  Input: {params}
  Output: {result_summary}
  Status: SUCCESS / FAILURE
```

### Key Metrics

| Metric | Target |
|--------|--------|
| CLI execution success rate | >= 95% |
| Average response time | < 10s |
| Booking link presence | 100% |

### Escalation

- CLI failure after retry -> inform user
- No flights available -> suggest alternative dates/routes
- Parameter extraction failure -> ask user (max 2 questions)

ClawHub Documentation Education+2

T@clawhub-tomuiv-d6b5ae5109

清华网络学堂自动化

Skill

自动登录清华网络学堂，查看待办事项，下载课件，提交作业，并批量标记课件已读，支持无人值守操作。

# tsinghua-learn skill

清华网络学堂（learn.tsinghua.edu.cn）自动化助手——从登录、查看待办、下载课件到提交作业，一切均可对话完成。

---

## 如果你是人类，首次使用请务必阅读以下说明

本 skill 为清华网络学堂打造全自动助手——从登录、查看待办、下载课件到提交作业，一切均可对话完成。首次使用仅需提供学号和密码，之后完全无人值守。

**它能做什么：**

- **查看待办**：自动拉取本学期所有课程未读消息（作业/公告/课件/讨论/答疑/问卷），按截止时间和课程排序显示，再也不用手动一个个点开看
- **下载课件**：指定课程名称，课件自动发送到当前对话，下载后本地临时文件精准清除，不留痕迹
- **提交作业**：直接把作业文件发给机器人，它自动按指定格式（如姓名+学号）命名并提交，省去繁琐的网页上传流程
- **批量标记已读**：所有课程的未读课件，一键全部标记为已读

**运行原理：**

首次运行需手动完成一次浏览器验证（点击"是的，我信任浏览器"），之后所有凭证和浏览器指纹会保存到本地。之后所有操作由机器人自动完成，无需重复验证。

---

## 零、驻地规范（铁律）

所有网络学堂相关脚本必须写在 `skills/tsinghua-learn/` 目录下，禁止散落到任何其他位置。

禁止位置：workspace 根目录、buffer/、其他 skill 目录。

---

## 一、文件结构

```
skills/tsinghua-learn/
├── SKILL.md                        ← 本文档
├── credentials.json               ← 账号密码（机器人自动创建，用户无需手动操作）
│
├── scripts/
│   ├── _config.py                  ← 凭证和路径加载器（所有脚本共享）
│   ├── learn_api.py                ← 所有 HTTP API 封装（详见文件内注释）
│   ├── login_supervised.py         ← 有人值守：首次建立 Profile + 2FA
│   ├── login_auto.py               ← 无人值守：日常调用，Session 失效自动续期
│   ├── todos_api.py                ← 查看待办：默认版（纯 API，并行请求）
│   ├── todos_dom.py                ← 查看待办：备用版（Playwright DOM）
│   ├── download_and_send_kj.py     ← 下载课件 + 发送 + 精准删除
│   ├── mark_kj_read.py             ← 批量标记课件已读
│   └── install_playwright.py        ← Chromium 浏览器安装
│
├── sessions/
│   └── learn_session.json          ← Session 文件（JSESSIONID + CSRF）
│
└── profiles/
    └── learn_profile/              ← 固定浏览器 Profile（cookies 持久化）
```

---

## 二、账号配置（首次使用）

机器人会主动询问用户的学号和密码，配置好后自动写入 `credentials.json`，之后所有脚本自动读取，无需重复操作。

---

## 三、双脚本登录架构

### 3.1 有人值守（supervised）

首次配置 / Session 彻底失效时使用。弹出浏览器窗口，若触发 2FA（企业微信/短信）需人工验证。

### 3.2 无人值守（auto）— 默认

日常调用。Session 有效时直接返回（<100ms），失效时自动用固定 Profile 续期，无需人工介入。

---

## 四、降级策略

```
todos_api.py / todos_dom.py
  → Session 无效 → login_auto.py（自动续期）
  → Profile 丢失 → login_supervised.py（手动 2FA）
  → Chromium 未装 → install_playwright.py

login_auto.py
  → Session 无效 → login_supervised.py
```

---

## 五、未读/未处理判断标准

| 模块 | API 字段 | 过滤条件 |
|------|---------|---------|
| 作业 | `zt` | `zt == "未交"` → 待提交 |
| 公告 | `sfyd` | `sfyd == "否"` → 未读（"是"=已读）|
| 课件 | `isNew` | `isNew == 1` → 未读 |
| 讨论/答疑 | `htsl` | `htsl > 0` → 有新回复 |
| 问卷 | — | 全局 API `pageListWks` 返回未做问卷数量 |

---

*最后更新：2026-04-26*
FILE:credentials.json
{
  "username": "",
  "password": ""
}
FILE:scripts/check_kj_unread.py
import json, requests, sys
sys.stdout.reconfigure(encoding='utf-8')

state = json.load(open(r'C:\Users\TOM\.openclaw\workspace\skills\tsinghua-learn\sessions\learn_session.json', encoding='utf-8'))
csrf = state['csrf']; js = state['learn_jsession']
h = {'Accept': 'application/json, */*', 'X-XSRF-TOKEN': csrf, 'Cookie': 'JSESSIONID=' + js + '; XSRF-TOKEN=' + csrf}

wlkcid = '2025-2026-2151369343'

r = requests.get(f'https://learn.tsinghua.edu.cn/b/wlxt/kj/wlkc_kjxxb/student/kjxxbByWlkcidAndSizeForStudent?wlkcid={wlkcid}&size=100&_csrf={csrf}', headers=h, timeout=15)
d = r.json()

obj = d.get('object', d)
if isinstance(obj, list):
    items = obj
elif isinstance(obj, dict):
    items = obj.get('aaData', [])
else:
    items = []

print(f'课件总数: {len(items)}')
new_items = [x for x in items if str(x.get('isNew','')) == '1']
old_items = [x for x in items if str(x.get('isNew','')) != '1']
print(f'  isNew=1（未读）: {len(new_items)}')
print(f'  isNew=0（已读）: {len(old_items)}')
if old_items:
    print(f'  已读课件示例: {old_items[0].get("bt","?")[:40]}')
if new_items:
    print(f'  未读课件示例: {new_items[0].get("bt","?")[:40]}')
FILE:scripts/check_session.py
import json, requests

f = r'C:\Users\TOM\.openclaw\workspace\skills\tsinghua-learn\sessions\learn_session.json'
s = json.load(open(f, encoding='utf-8'))
print('csrf:', s['csrf'])

h = {
    'Accept': 'application/json, */*',
    'Referer': 'https://learn.tsinghua.edu.cn/f/wlxt/index/course/student/',
    'X-XSRF-TOKEN': s['csrf'],
    'Cookie': 'JSESSIONID=' + s['learn_jsession'] + '; XSRF-TOKEN=' + s['csrf'],
}
r = requests.get('https://learn.tsinghua.edu.cn/b/wlxt/kczy/zy/student/index/zyListWj?wlkcid=&size=1', headers=h, timeout=10)
print('status:', r.status_code)
print('has location.href:', 'location.href' in r.text)
print('body[:300]:', r.text[:300])
FILE:scripts/check_wj_api.py
import json, requests, sys
sys.stdout.reconfigure(encoding='utf-8')

state = json.load(open(r'C:\Users\TOM\.openclaw\workspace\skills\tsinghua-learn\sessions\learn_session.json', encoding='utf-8'))
csrf = state['csrf']; js = state['learn_jsession']
h = {'Accept': 'application/json, */*', 'X-XSRF-TOKEN': csrf, 'Cookie': 'JSESSIONID=' + js + '; XSRF-TOKEN=' + csrf}

# 测试问卷 API（POST，Form Data 格式）
# pageListWks = 未做问卷，pageListWys = 已做问卷
import urllib.parse

# 未做问卷
params = {
    'aoData[0][name]': 'iDisplayStart',
    'aoData[0][value]': 0,
    'aoData[1][name]': 'iDisplayLength',
    'aoData[1][value]': 100,
}
body = urllib.parse.urlencode(params)
r1 = requests.post(
    'https://learn.tsinghua.edu.cn/b/wlxt/kcwj/wlkc_wjb/student/pageListWks?_csrf=' + csrf,
    headers={**h, 'Content-Type': 'application/x-www-form-urlencoded'},
    data=body, timeout=15
)
print('=== 未做问卷 ===')
print('status:', r1.status_code)
d1 = r1.json()
obj1 = d1.get('object', d1)
if isinstance(obj1, dict):
    items1 = obj1.get('aaData', [])
elif isinstance(obj1, list):
    items1 = obj1
else:
    items1 = []
print(f'未做问卷总数: {len(items1)}')
for x in items1[:3]:
    print(f'  {x.get("bt","?")[:40]} | wjid={x.get("wjid","?")[:20]}')

# 已做问卷
r2 = requests.post(
    'https://learn.tsinghua.edu.cn/b/wlxt/kcwj/wlkc_wjb/student/pageListWys?_csrf=' + csrf,
    headers={**h, 'Content-Type': 'application/x-www-form-urlencoded'},
    data=body, timeout=15
)
print('\n=== 已做问卷 ===')
print('status:', r2.status_code)
d2 = r2.json()
obj2 = d2.get('object', d2)
if isinstance(obj2, dict):
    items2 = obj2.get('aaData', [])
elif isinstance(obj2, list):
    items2 = obj2
else:
    items2 = []
print(f'已做问卷总数: {len(items2)}')
for x in items2[:3]:
    print(f'  {x.get("bt","?")[:40]} | wjid={x.get("wjid","?")[:20]}')

# 也测试下对每门课程分别查问卷
print('\n=== 各课程的问卷情况 ===')
courses = {
    '2025-2026-2151368648': '大学物理A(1)',
    '2025-2026-2151369314': '概率论',
    '2025-2026-2151369343': '英语听说交流(A)',
    '2025-2026-2151368819': '写作与沟通',
    '2025-2026-2151368584': '微积分A(2)',
}
for wlkcid, name in courses.items():
    r = requests.get(
        f'https://learn.tsinghua.edu.cn/b/wlxt/kcwj/wlkc_wjb/student/pageListWks?wlkcid={wlkcid}&size=20&_csrf={csrf}',
        headers=h, timeout=10
    )
    try:
        d = r.json()
        obj = d.get('object', d)
        items = (obj.get('aaData', []) if isinstance(obj, dict) else (obj if isinstance(obj, list) else []))
        print(f'  {name} 未做: {len(items)} 项')
    except:
        print(f'  {name} API 无响应或格式异常')
FILE:scripts/check_wj_api2.py
import json, requests, sys
sys.stdout.reconfigure(encoding='utf-8')

state = json.load(open(r'C:\Users\TOM\.openclaw\workspace\skills\tsinghua-learn\sessions\learn_session.json', encoding='utf-8'))
csrf = state['csrf']; js = state['learn_jsession']
h = {'Accept': 'application/json, */*', 'X-XSRF-TOKEN': csrf, 'Cookie': 'JSESSIONID=' + js + '; XSRF-TOKEN=' + csrf}

# DataTables 格式的 aoData 参数
body = 'aoData=%5B%7B%22name%22%3A%22iDisplayStart%22%2C%22value%22%3A0%7D%2C%7B%22name%22%3A%22iDisplayLength%22%2C%22value%22%3A100%7D%5D'

# 未做问卷
r1 = requests.post(
    'https://learn.tsinghua.edu.cn/b/wlxt/kcwj/wlkc_wjb/student/pageListWks?_csrf=' + csrf,
    headers={**h, 'Content-Type': 'application/x-www-form-urlencoded'},
    data=body, timeout=15
)
print('=== 未做问卷 ===')
print('status:', r1.status_code)
print('body[:200]:', r1.text[:200])

# 已做问卷
r2 = requests.post(
    'https://learn.tsinghua.edu.cn/b/wlxt/kcwj/wlkc_wjb/student/pageListWys?_csrf=' + csrf,
    headers={**h, 'Content-Type': 'application/x-www-form-urlencoded'},
    data=body, timeout=15
)
print('\n=== 已做问卷 ===')
print('status:', r2.status_code)
print('body[:200]:', r2.text[:200])
FILE:scripts/check_wj_global.py
import json, requests, sys
sys.stdout.reconfigure(encoding='utf-8')

state = json.load(open(r'C:\Users\TOM\.openclaw\workspace\skills\tsinghua-learn\sessions\learn_session.json', encoding='utf-8'))
csrf = state['csrf']; js = state['learn_jsession']
h = {'Accept': 'application/json, */*', 'X-XSRF-TOKEN': csrf, 'Cookie': 'JSESSIONID=' + js + '; XSRF-TOKEN=' + csrf}

# 未做问卷（全局，不是按课程）
body = 'aoData=%5B%7B%22name%22%3A%22iDisplayStart%22%2C%22value%22%3A0%7D%2C%7B%22name%22%3A%22iDisplayLength%22%2C%22value%22%3A100%7D%5D'

r = requests.post(
    'https://learn.tsinghua.edu.cn/b/wlxt/kcwj/wlkc_wjb/student/pageListWks?_csrf=' + csrf,
    headers={**h, 'Content-Type': 'application/x-www-form-urlencoded'},
    data=body, timeout=15
)
d = r.json()
obj = d.get('object', d)
items = obj.get('aaData', []) if isinstance(obj, dict) else []
print(f'未做问卷总数: {len(items)}')
for x in items:
    wlkcid = x.get('wlkcid', '')
    wjbt = x.get('bt', '?')
    wjsj = x.get('jzsjStr', '')
    print(f'  [{wlkcid}] {wjbt[:40]} | 截止:{wjsj}')

print()
# 看看有没有 wlkcid 字段可以区分课程
if items:
    print('字段列表:', list(items[0].keys()))
    print('wlkcid 示例:', items[0].get('wlkcid'))
FILE:scripts/download_and_send_kj.py
"""
下载课件 + 自动标已读 + 发送给用户 + 精准删除
用法：python download_and_send_kj.py < COURSE_ID > < WJID > < 课程名 >
示例：python download_and_send_kj.py 2025-2026-2151368584 2005990081_KJ_xxx 微积分
"""
import json, requests, sys, os
sys.stdout.reconfigure(encoding='utf-8')

# 统一 session 路径
import os as _os
_SKILL_DIR = _os.path.dirname(_os.path.dirname(_os.path.abspath(__file__)))
STATE_FILE = _os.path.join(_SKILL_DIR, "sessions", "learn_session.json")
state = json.load(open(STATE_FILE, encoding="utf-8"))
learn_j = state['learn_jsession']; csrf = state['csrf']

headers = {
    'Accept': 'application/json, */*',
    'Referer': 'https://learn.tsinghua.edu.cn/f/wlxt/index/course/student/',
    'X-XSRF-TOKEN': csrf,
    'Cookie': f'JSESSIONID={learn_j}; XSRF-TOKEN={csrf}',
}
headers_post = {
    'Accept': 'application/json, */*',
    'Referer': 'https://learn.tsinghua.edu.cn/f/wlxt/kj/wlkc_kjxxb/student/beforePageList',
    'X-XSRF-TOKEN': csrf,
    'Cookie': f'JSESSIONID={learn_j}; XSRF-TOKEN={csrf}',
    'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
}

def mark_kj_read(wjid):
    r = requests.post(
        f'https://learn.tsinghua.edu.cn/b/wlxt/kj/wlkc_kjfwb/student/savePlayRecord?_csrf={csrf}',
        headers=headers_post, data=f'wjid={wjid}&sfgk=0', timeout=10
    )
    return r.status_code == 200 and 'success' in r.text

def download_and_send(wlkcid, wjid, wjlx, save_dir):
    os.makedirs(save_dir, exist_ok=True)
    fname = None

    # 下载
    dl_url = f'https://learn.tsinghua.edu.cn/b/wlxt/kj/wlkc_kjxxb/student/downloadFile?wlkcid={wlkcid}&wjid={wjid}&sfgk=0'
    r = requests.get(dl_url, headers=headers, timeout=60)

    # 取文件名（从bt字段，wjlx传进来）
    # 构造输出路径
    out_path = os.path.join(save_dir, f'temp_kj.{wjlx}')

    if r.status_code == 200 and len(r.content) > 10000:
        with open(out_path, 'wb') as fp:
            fp.write(r.content)
        print(f'下载完成: {len(r.content):,} bytes')

        # 标记已读
        if mark_kj_read(wjid):
            print('已标记已读')
        else:
            print('标记失败（继续）')

        # 打印 <qqmedia> 标签（供 AI 直接回复用户）
        print(f'\n<qqmedia>{out_path}</qqmedia>')

        # 精准删除
        if os.path.exists(out_path):
            os.remove(out_path)
            print(f'已删除: {out_path}')
    else:
        print(f'下载失败: {r.status_code}')

if __name__ == '__main__':
    # 命令行参数：wlkcid wjid wjlx save_dir
    if len(sys.argv) >= 5:
        wlkc_id = sys.argv[1]
        wjid = sys.argv[2]
        wjlx = sys.argv[3]
        save_dir = sys.argv[4]
        download_and_send(wlkc_id, wjid, wjlx, save_dir)
    else:
        print('用法: python download_and_send_kj.py <wlkcid> <wjid> <wjlx> <save_dir>')
FILE:scripts/install_playwright.py
#!/usr/bin/env python3
"""
install_playwright.py
下载并安装 Playwright Chromium 浏览器
======================================
【用途】
  运行任何需要 Playwright 的脚本前，先跑一次这个
  如果遇到 "Executable not found" 错误，运行这个即可修复

【用法】
  python install_playwright.py
"""
import sys, subprocess

def run():
    print("正在安装 Playwright Chromium（只会执行一次）...")
    print("这可能需要几分钟，请耐心等待...\n")

    result = subprocess.run(
        [sys.executable, "-m", "playwright", "install", "chromium"],
        capture_output=False
    )

    if result.returncode == 0:
        print("\n✅ Chromium 安装成功！")
        print("   现在可以运行 login_supervised.py 等脚本了。")
    else:
        print("\n❌ 安装失败，请检查网络连接后重试")
        print("   或手动运行: python -m playwright install chromium")


if __name__ == "__main__":
    run()
FILE:scripts/learn_api.py
#!/usr/bin/env python3
"""
learn_api.py — 清华网络学堂 HTTP API 封装
无需浏览器，直接操作网络学堂 API
"""
import sys
sys.stdout.reconfigure(encoding='utf-8')
import os, json, time, ssl, base64
import requests
from urllib.parse import urlencode

# ========== 配置 ==========
SESSION_FILE = r"D:\testclaw\learn_session.json"
FINGERPRINT_FILE = r"D:\testclaw\learn_fingerprint.json"
DOWNLOAD_DIR = r"D:\testclaw\learn_downloads"
LEARN_BASE = "https://learn.tsinghua.edu.cn"

DEFAULT_HEADERS = {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
    "Accept-Encoding": "gzip, deflate, br",
    "Connection": "keep-alive",
    "Upgrade-Insecure-Requests": "1",
    "Referer": LEARN_BASE + "/",
}

AJAX_HEADERS = {
    **DEFAULT_HEADERS,
    "Accept": "application/json, text/javascript, */*; q=0.01",
    "X-Requested-With": "XMLHttpRequest",
}

ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE


def escape_filename(s):
    """转义文件名非法字符"""
    for ch in [' ', '\t', '?', '/', "'", '"', '<', '>', '#', ';', '*', '|', '\\']:
        s = s.replace(ch, '_')
    return s


class LearnAPI:
    def __init__(self, session_file=None):
        self.session_file = session_file or SESSION_FILE
        self.session = None
        self.valid = False
        self.fingerprint = None
        self.session_data = None
        self.cookies = {}
        self.xsrf_token = None
        self._ensure_download_dir()

    # ====== 内部方法 ======

    def _ensure_download_dir(self):
        os.makedirs(DOWNLOAD_DIR, exist_ok=True)

    def _update_headers(self):
        """更新 session headers"""
        if self.xsrf_token:
            self.session.headers.update({"X-XSRF-TOKEN": self.xsrf_token})

    def _post(self, path, data=None, use_ajax=True):
        """POST 请求"""
        url = LEARN_BASE + path
        headers = AJAX_HEADERS if use_ajax else DEFAULT_HEADERS
        kwargs = {"headers": headers}
        if data:
            if isinstance(data, dict):
                kwargs["data"] = urlencode(data, encoding='utf-8')
                kwargs["headers"]["Content-Type"] = "application/x-www-form-urlencoded"
            else:
                kwargs["data"] = data
        r = self.session.post(url, **kwargs, verify=False, timeout=15)
        try:
            return r.json()
        except Exception:
            return r.text

    def _get(self, path, params=None, use_ajax=False):
        """GET 请求"""
        url = LEARN_BASE + path
        headers = AJAX_HEADERS if use_ajax else DEFAULT_HEADERS
        kwargs = {"headers": headers, "params": params}
        r = self.session.get(url, **kwargs, verify=False, timeout=15)
        return r

    def _build_url(self, path):
        return LEARN_BASE + path

    # ====== Session 管理 ======

    def reload_session(self):
        """从文件加载 session 并验证"""
        if not os.path.exists(self.session_file):
            self.valid = False
            return False

        with open(self.session_file, 'r', encoding='utf-8') as f:
            self.session_data = json.load(f)

        self.cookies = self.session_data.get('cookies', {})
        self.fingerprint = self.session_data.get('fingerprint', {})

        self.session = requests.Session()
        self.session.headers.update(DEFAULT_HEADERS)

        # 设置 cookies
        for name, value in self.cookies.items():
            if value is None:
                continue
            for domain in ['.tsinghua.edu.cn', 'learn.tsinghua.edu.cn', 'id.tsinghua.edu.cn']:
                self.session.cookies.set(name, value, domain=domain, path='/', secure=False)

        # 设置 XSRF token
        self.xsrf_token = self.cookies.get('XSRF-TOKEN') or self.cookies.get('xsrf-token')
        if self.xsrf_token:
            self.session.headers.update({"X-XSRF-TOKEN": self.xsrf_token})

        return self._check_valid()

    def _check_valid(self):
        """验证 session 是否有效"""
        if not self.session:
            self.valid = False
            return False
        try:
            ts = str(int(time.time() * 1000))
            url = f"{LEARN_BASE}/b/wlxt/kc/v_wlkc_xs_xkb_kcb_extend/student/loadCourseBySemesterId/2025-2026-2/zh_CN?timestamp={ts}"
            r = self.session.get(url, verify=False, timeout=8,
                                headers={**AJAX_HEADERS, "X-XSRF-TOKEN": self.xsrf_token} if self.xsrf_token else AJAX_HEADERS)
            result = r.json()
            courses = result.get('resultList', [])
            if courses:
                self.valid = True
                return True
        except Exception:
            pass
        self.valid = False
        return False

    def login(self):
        """
        尝试纯 API 登录。
        成功返回 True；失败返回 False（需使用浏览器版脚本）。
        """
        # 尝试从已有 fingerprint + session 重新认证
        # 当前纯 API 登录受限于 localStorage，暂时返回 False
        return False

    def save_session(self):
        """保存当前 session 到文件"""
        if not self.session or not self.cookies:
            return
        # 从 credentials.json 读取用户名（不在此处写死）
        try:
            sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(__file__)), 'scripts'))
            from _config import load_credentials
            username = load_credentials()[0]
        except Exception:
            username = 'unknown'
        self.session_data = {
            'username': username,
            'cookies': self.cookies,
            'fingerprint': self.fingerprint,
            'timestamp': time.time(),
        }
        with open(self.session_file, 'w', encoding='utf-8') as f:
            json.dump(self.session_data, f, ensure_ascii=False, indent=2)

    # ====== 课程 API ======

    def get_current_semester(self):
        """获取当前学期和下学期信息"""
        data = self._post("/b/kc/zhjw_v_code_xnxq/getCurrentAndNextSemester", use_ajax=True)
        return data.get('result', {}).get('xnxq', [])

    def get_semesters(self):
        """获取所有学期列表"""
        data = self._post("/b/wlxt/kc/v_wlkc_xs_xktjb_coassb/queryxnxq", use_ajax=True)
        return [x for x in data if x is not None]

    def get_courses(self, semester=None):
        """获取课程列表

        Args:
            semester: str 学期ID，默认当前学期。格式 "2025-2026-2"

        Returns:
            List[dict] 课程列表，每项含 kcm(已转义课名), wlkcid, jsm(教师), kch, kxh, xf, xs, jslx
        """
        if semester is None:
            semesters = self.get_current_semester()
            semester = semesters[0] if semesters else '2025-2026-2'

        courses = []
        # 学生选课
        try:
            data = self._get(
                f"/b/wlxt/kc/v_wlkc_xs_xkb_kcb_extend/student/loadCourseBySemesterId/{semester}/zh_CN",
                use_ajax=True
            ).json()
            for c in data.get('resultList', []):
                c['jslx'] = '3'
                courses.append(c)
        except Exception:
            pass

        # 助教课程
        try:
            data2 = self._post(f"/b/kc/v_wlkc_kcb/queryAsorCoCourseList/{semester}/0", use_ajax=True)
            for c in data2.get('resultList', []):
                c['jslx'] = '0'
                courses.append(c)
        except Exception:
            pass

        # 转义课名
        for c in courses:
            c['kcm_escaped'] = escape_filename(c.get('kcm', ''))

        return courses

    def get_course_type(self, jslx):
        """根据 jslx 返回课程类型字符串"""
        return {'3': 'student', '0': 'teacher'}.get(str(jslx), 'student')

    # ====== 公告 API ======

    def get_announcements(self, wlkcid):
        """获取课程公告列表"""
        data = self._post(
            "/b/wlxt/kcgg/wlkc_ggb/student/pageListXs",
            {"aoData": [{"name": "wlkcid", "value": wlkcid}]},
            use_ajax=True
        )
        return data.get('object', {}).get('aaData', [])

    # ====== 课件 API ======

    def get_files(self, wlkcid):
        """获取课件文件列表"""
        data = self._get(
            f"/b/wlxt/kj/wlkc_kjxxb/student/kjxxbByWlkcidAndSizeForStudent",
            params={"wlkcid": wlkcid, "size": 0},
            use_ajax=True
        )
        return data.json().get('object', [])

    def get_file_categories(self, wlkcid, type_='student'):
        """获取课件分类列表"""
        data = self._get(
            f"/b/wlxt/kj/wlkc_kjflb/{type_}/pageList",
            params={"wlkcid": wlkcid},
            use_ajax=True
        )
        return json.loads(data.text).get('object', {}).get('rows', [])

    def download_file(self, wlkcid, wjid, type_='student', filename=None, save_dir=None):
        """
        下载课件文件。

        Returns:
            str 保存的完整路径，失败返回 None
        """
        save_dir = save_dir or DOWNLOAD_DIR
        os.makedirs(save_dir, exist_ok=True)

        url = f"{LEARN_BASE}/b/wlxt/kj/wlkc_kjxxb/{type_}/downloadFile"
        params = {"sfgk": 0, "wjid": wjid}

        self._update_headers()
        headers = {**DEFAULT_HEADERS, "X-XSRF-TOKEN": self.xsrf_token} if self.xsrf_token else DEFAULT_HEADERS

        r = self.session.get(url, params=params, headers=headers, verify=False, stream=True, timeout=30)

        if r.status_code != 200:
            return None

        # 从 Content-Disposition 提取文件名
        cd = r.headers.get('Content-Disposition', '')
        if filename is None:
            import re
            m = re.search(r'filename[^;]*=([^;]+)', cd)
            if m:
                fname = m.group(1).strip().strip('"').strip("'")
                # decode URI encoding
                import urllib.parse
                filename = urllib.parse.unquote(fname)
            else:
                filename = f"file_{wjid}"

        filename = escape_filename(filename)
        filepath = os.path.join(save_dir, filename)

        try:
            with open(filepath, 'wb') as f:
                for chunk in r.iter_content(chunk_size=8192):
                    if chunk:
                        f.write(chunk)
            return filepath
        except Exception:
            return None

    # ====== 作业 API ======

    def get_homeworks(self, wlkcid):
        """获取作业列表（含未提交/已提交/已批改）"""
        hws = []
        data = {"aoData": [{"name": "wlkcid", "value": wlkcid}]}
        for endpoint in ['zyListWj', 'zyListYjwg', 'zyListYpg']:
            try:
                d = self._post(f"/b/wlxt/kczy/zy/student/{endpoint}", data, use_ajax=True)
                hws.extend(d.get('object', {}).get('aaData', []))
            except Exception:
                continue
        return hws

    def get_homework_detail(self, wlkcid, zyid, xszyid='', type_='student'):
        """获取作业详情（含说明、附件、截止日期）"""
        url = f"/f/wlxt/kczy/zy/{type_}/viewZy"
        params = {
            "wlkcid": wlkcid,
            "sfgq": "0",
            "zyid": zyid,
            "xszyid": xszyid,
        }
        r = self._get(url, params=params, use_ajax=False)
        html = r.text if isinstance(r, requests.Response) else r

        from bs4 import BeautifulSoup
        soup = BeautifulSoup(html, 'html.parser')
        info = {}

        for item in soup.find_all('div', class_='list'):
            left = item.find('div', class_='left')
            right = item.find('div', class_='right')
            if not left or not right:
                continue
            key = left.get_text(strip=True)
            val = right.get_text(strip=True)
            if '标题' in key:
                info['title'] = val
            elif '说明' in key:
                info['description'] = val
            elif '截止' in key:
                info['deadline'] = val
            elif '补交' in key:
                info['makeup_deadline'] = val

        # 附件
        attachments = []
        for fj in soup.find_all('div', class_='fujian'):
            left = fj.find('div', class_='left')
            links = fj.find_all('a')
            if left and links:
                key = left.get_text(strip=True)
                for link in links:
                    href = link.get('href', '')
                    name = link.get_text(strip=True)
                    if href and name:
                        if '作业' in key:
                            attachments.append({'name': name, 'href': href})
        info['attachments'] = attachments
        return info

    # ====== 讨论 API ======

    def get_discussions(self, wlkcid, type_='student'):
        """获取讨论帖列表"""
        data = self._get(
            f"/b/wlxt/bbs/bbs_tltb/{type_}/kctlList",
            params={"wlkcid": wlkcid},
            use_ajax=True
        )
        try:
            return json.loads(data.text).get('object', {}).get('resultsList', [])
        except Exception:
            return []

    def get_discussion_detail(self, wlkcid, id_, bqid, type_='student'):
        """获取讨论帖详情"""
        url = f"/f/wlxt/bbs/bbs_tltb/{type_}/viewTlById"
        params = {"wlkcid": wlkcid, "id": id_, "tabbh": "2", "bqid": bqid}
        r = self._get(url, params=params, use_ajax=False)
        from bs4 import BeautifulSoup
        soup = BeautifulSoup(r.text, 'html.parser')
        detail = soup.find('div', class_='detail')
        return detail.get_text(strip=True) if detail else ""


# ====== 命令行接口 ======
if __name__ == '__main__':
    import argparse, pprint

    parser = argparse.ArgumentParser(description='清华网络学堂 API')
    parser.add_argument('--session', default=SESSION_FILE)
    parser.add_argument('--semester', default=None)
    parser.add_argument('--course', default=None, help='课名（部分匹配）')
    parser.add_argument('--action', default='courses',
                        choices=['courses', 'announcements', 'files', 'homeworks', 'discussions', 'semesters'])
    args = parser.parse_args()

    api = LearnAPI(session_file=args.session)
    api.reload_session()

    if not api.valid:
        print("❌ Session 无效，请先运行:")
        print('   python "D:\\testclaw\\learn_login_v2.py"')
        exit(1)

    courses = api.get_courses(semester=args.semester)
    if args.course:
        courses = [c for c in courses if args.course in c.get('kcm', '')]

    if args.action == 'semesters':
        semesters = api.get_semesters()
        print("所有学期:", semesters)
    elif args.action == 'courses':
        for c in courses:
            print(f"[{c.get('jslx')}] {c.get('kcm')} | {c.get('jsm')} | wlkcid={c.get('wlkcid')}")
    elif args.action == 'announcements':
        for c in courses:
            ads = api.get_announcements(c['wlkcid'])
            if ads:
                print(f"\n=== {c['kcm']} 公告 ===")
                for a in ads:
                    print(f"  [{a.get('fbsjStr','')}] {a.get('bt','')}")
    elif args.action == 'files':
        for c in courses:
            files = api.get_files(c['wlkcid'])
            if files:
                print(f"\n=== {c['kcm']} 课件 ===")
                for f in files:
                    print(f"  {f.get('bt','?')}.{f.get('wjlx','?')}")
    elif args.action == 'homeworks':
        for c in courses:
            hws = api.get_homeworks(c['wlkcid'])
            if hws:
                print(f"\n=== {c['kcm']} 作业 ===")
                for h in hws:
                    print(f"  [{h.get('zt','?')}] {h.get('bt','?')} 截止:{h.get('scsjStr','?')}")
    elif args.action == 'discussions':
        for c in courses:
            disc = api.get_discussions(c['wlkcid'])
            if disc:
                print(f"\n=== {c['kcm']} 讨论 ===")
                for d in disc:
                    print(f"  {d.get('bt','?')} by {d.get('fbrxm','?')}")

FILE:scripts/login_auto.py
#!/usr/bin/env python3
"""
login_auto.py
清华网络学堂 - 无人值守自动登录脚本（双脚本方案·第二套）
==========================================================
【什么时候用】
  日常调用。Session 失效时自动重新登录，无需人工介入。

【工作流程】
  1. 检查 sessions/learn_session.json 里的 Session 是否有效
  2. 有效 → 直接返回（不登录）
  3. 无效 → 复用固定 Profile 的 cookies 自动走 CAS 登录（无 2FA）
  4. 登录成功后保存 Session

【核心原则】
  固定 profile 路径：profiles/learn_profile/
  账号密码从 credentials.json 统一读取（禁止硬编码）
"""
import sys, os, json, time, re
sys.stdout.reconfigure(encoding='utf-8')
from playwright.sync_api import sync_playwright
import requests

# ====== 账号密码（从 credentials.json 统一加载）=======
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from _config import load_credentials, get_state_file, get_fp_file, get_profile_dir

STATE_FILE       = get_state_file()
FINGERPRINT_FILE = get_fp_file()
PROFILE_DIR      = get_profile_dir()

try:
    USER, PASS = load_credentials()
except (FileNotFoundError, RuntimeError) as e:
    print(e)
    raise SystemExit(1)

CAS_URL = "https://id.tsinghua.edu.cn/do/off/ui/auth/login/form/bb5df85216504820be7bba2b0ae1535b/0"


def check_session_valid(state):
    """用轻量 API 检查 Session 是否有效"""
    if not state.get("learn_jsession") or not state.get("csrf"):
        return False
    h = {
        "Accept": "application/json, */*",
        "Referer": "https://learn.tsinghua.edu.cn/f/wlxt/index/course/student/",
        "X-XSRF-TOKEN": state["csrf"],
        "Cookie": f"JSESSIONID={state['learn_jsession']}; XSRF-TOKEN={state['csrf']}",
    }
    try:
        r = requests.get(
            "https://learn.tsinghua.edu.cn/b/wlxt/kczy/zy/student/index/zyListWj?wlkcid=&size=1",
            headers=h, timeout=10
        )
        return not ("location.href" in r.text and r.status_code == 200)
    except:
        return False


def save_state(ctx, page_url, csrf):
    """提取并保存 Session"""
    learn_jsession = None
    for c in ctx.cookies():
        if "learn.tsinghua" in c["domain"] and c["name"] == "JSESSIONID":
            learn_jsession = c["value"]

    state = {
        "learn_jsession": learn_jsession,
        "learn_token":    None,
        "csrf":           csrf,
        "timestamp":      time.time(),
        "url":            page_url,
    }
    with open(STATE_FILE, "w", encoding="utf-8") as f:
        json.dump(state, f, ensure_ascii=False, indent=2)
    print(f"✅ Session 已保存")
    return state


def auto_login():
    """用固定 profile 的 cookies 自动登录（无 2FA）"""
    fp = json.load(open(FINGERPRINT_FILE, encoding="utf-8"))
    pw = sync_playwright().start()
    ctx = None
    try:
        ctx = pw.chromium.launch_persistent_context(
            PROFILE_DIR,
            headless=True,
            viewport={"width": 1280, "height": 900},
            ignore_https_errors=True,
            args=["--no-sandbox", "--disable-dev-shm-usage",
                  "--disable-blink-features=AutomationControlled"],
        )
        page = ctx.pages[0] if ctx.pages else ctx.new_page()
        page.goto(CAS_URL, wait_until="domcontentloaded", timeout=30000)
        time.sleep(2)

        page.evaluate(
            "localStorage.setItem('fingerPrint', '" + fp["fingerPrint"] + "');"
            "localStorage.setItem('fingerGenPrint', '" + fp.get("fingerGenPrint","") + "');"
            "localStorage.setItem('fingerGenPrint3', '" + fp.get("fingerGenPrint3","") + "');"
        )
        time.sleep(1)

        page.fill("#i_user", USER)
        page.fill("#i_pass", PASS)
        page.evaluate("doLogin()")

        page.wait_for_url("**://learn.tsinghua.edu.cn/**", timeout=90000)
        time.sleep(2)

        csrf = None
        if "_csrf" in page.url:
            for p2 in page.url.split("?")[1].split("&"):
                if p2.startswith("_csrf="): csrf = p2.split("=")[1]
        if not csrf:
            m = re.search(r'_csrf=([a-f0-9\-]{32,})', page.content())
            if m: csrf = m.group(1)

        return save_state(ctx, page.url, csrf)

    finally:
        if ctx: ctx.close()
        pw.stop()


# ========== 主流程 ==========
if os.path.exists(STATE_FILE):
    state = json.load(open(STATE_FILE, encoding="utf-8"))
    age_h = (time.time() - state.get("timestamp", 0)) / 3600
    print(f"Session 存在，age={age_h:.1f}h")

    if check_session_valid(state):
        print("✅ Session 有效，无需重新登录")
    else:
        print("⚠️ Session 失效，自动重新登录...")
        state = auto_login()
        print(f"JSESSIONID: {state.get('learn_jsession','?')[:10]}...")
else:
    print("⚠️ Session 文件不存在，运行 login_supervised.py 建立")
    print("   python scripts/login_supervised.py")
    sys.exit(1)
FILE:scripts/login_supervised.py
#!/usr/bin/env python3
"""
login_supervised.py
清华网络学堂 - 有人值守登录脚本（双脚本方案·第一套）
======================================================
【什么时候用】
  首次配置 / Profile 丢失 / Session 彻底失效时。
  需要人工完成二次验证（2FA），只需跑这一次。

【工作流程】
  1. 从 credentials.json 读取账号密码
  2. 使用固定 profile 目录（cookies 持久化，避免每次触发 2FA）
  3. 弹出浏览器窗口，可视化完成登录 + 2FA
  4. 登录成功后保存 Session 到 sessions/learn_session.json
  5. 下次直接用 login_auto.py 无人值守自动续期

【重要原则】
  固定 profile 路径：profiles/learn_profile/（永不重建）
  不管脚本跑多少次，都用同一个 profile → cookies 复用 → 不触发 2FA
"""
import sys, os, json, time, re
sys.stdout.reconfigure(encoding='utf-8')
from playwright.sync_api import sync_playwright

# ====== 账号密码（从 credentials.json 统一加载）=======
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from _config import load_credentials, get_state_file, get_fp_file, get_profile_dir

STATE_FILE       = get_state_file()
FINGERPRINT_FILE = get_fp_file()
PROFILE_DIR      = get_profile_dir()

try:
    USER, PASS = load_credentials()
except (FileNotFoundError, RuntimeError) as e:
    print(e)
    raise SystemExit(1)

CAS_URL = "https://id.tsinghua.edu.cn/do/off/ui/auth/login/form/bb5df85216504820be7bba2b0ae1535b/0"

# ====== 正文 ======
fp = json.load(open(FINGERPRINT_FILE, encoding="utf-8"))
os.makedirs(PROFILE_DIR, exist_ok=True)


def save_state(ctx, page_url, csrf):
    """提取并保存完整 Session"""
    learn_jsession = None
    learn_token    = None
    for c in ctx.cookies():
        if "learn.tsinghua" in c["domain"]:
            if c["name"] == "JSESSIONID": learn_jsession = c["value"]
            elif c["name"] == "XSRF-TOKEN": learn_token = c["value"]

    state = {
        "learn_jsession": learn_jsession,
        "learn_token":    learn_token,
        "csrf":           csrf,
        "timestamp":      time.time(),
        "url":            page_url,
    }
    with open(STATE_FILE, "w", encoding="utf-8") as f:
        json.dump(state, f, ensure_ascii=False, indent=2)
    print(f"✅ Session 已保存: {STATE_FILE}")
    return state


pw = sync_playwright().start()
ctx = None
try:
    ctx = pw.chromium.launch_persistent_context(
        PROFILE_DIR,
        headless=False,                    # 可视化，可做 2FA
        viewport={"width": 1280, "height": 900},
        ignore_https_errors=True,
        args=["--no-sandbox", "--disable-dev-shm-usage",
              "--disable-blink-features=AutomationControlled"],
    )
    page = ctx.pages[0] if ctx.pages else ctx.new_page()

    print(f"打开登录页: {CAS_URL}")
    page.goto(CAS_URL, wait_until="domcontentloaded", timeout=30000)
    time.sleep(2)

    page.evaluate(
        "localStorage.setItem('fingerPrint', '" + fp["fingerPrint"] + "');"
        "localStorage.setItem('fingerGenPrint', '" + fp.get("fingerGenPrint","") + "');"
        "localStorage.setItem('fingerGenPrint3', '" + fp.get("fingerGenPrint3","") + "');"
    )
    time.sleep(1)

    page.fill("#i_user", USER)
    page.fill("#i_pass", PASS)
    print(f"凭据已填入: {USER}")
    print("触发 doLogin()，请在浏览器中完成二次验证（如有）...")

    page.evaluate("doLogin()")
    time.sleep(3)

    title = page.title()
    body  = page.inner_text("body")[:300]

    if "二次认证" in title or "二次验证" in body:
        print()
        print("=" * 40)
        print("⚠️  检测到二次验证！")
        print("   请在浏览器窗口中完成验证（企业微信/短信）")
        print("   完成后脚本自动继续...")
        print("=" * 40)
        page.wait_for_url("**://learn.tsinghua.edu.cn/**", timeout=300000)
        print("✅ 验证完成")
    else:
        try:
            page.wait_for_url("**://learn.tsinghua.edu.cn/**", timeout=90000)
            print("✅ 登录成功")
        except Exception:
            print(f"⚠️ 未检测到跳转，当前URL: {page.url}")

    time.sleep(2)

    csrf = None
    if "_csrf" in page.url:
        for p2 in page.url.split("?")[1].split("&"):
            if p2.startswith("_csrf="): csrf = p2.split("=")[1]
    if not csrf:
        m = re.search(r'_csrf=([a-f0-9\-]{32,})', page.content())
        if m: csrf = m.group(1)

    state = save_state(ctx, page.url, csrf)
    print(f"\nJSESSIONID: {state.get('learn_jsession','?')[:10]}...")
    print("\n🎉 完成！以后运行 login_auto.py 即可无人值守登录。")

finally:
    if ctx: ctx.close()
    pw.stop()
FILE:scripts/mark_kj_read.py
#!/usr/bin/env python3
"""
mark_kj_read.py
批量标记所有课程未读课件为已读
使用 savePlayRecord 接口（isNew=1 → 0）

用法：python mark_kj_read.py
"""
import json, requests, sys, os
sys.stdout.reconfigure(encoding='utf-8')

# 统一路径
_SKILL_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
STATE_FILE = os.path.join(_SKILL_DIR, "sessions", "learn_session.json")
state = json.load(open(STATE_FILE, encoding="utf-8"))
learn_j = state["learn_jsession"]
csrf = state["csrf"]

headers = {
    "Accept": "application/json, */*",
    "Referer": "https://learn.tsinghua.edu.cn/f/wlxt/kj/wlkc_kjxxb/student/beforePageList",
    "X-XSRF-TOKEN": csrf,
    "Cookie": f"JSESSIONID={learn_j}; XSRF-TOKEN={csrf}",
    "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
}

BASE_URL = "https://learn.tsinghua.edu.cn"

def mark_read(wjid):
    r = requests.post(
        f"{BASE_URL}/b/wlxt/kj/wlkc_kjfwb/student/savePlayRecord?_csrf={csrf}",
        headers=headers, data=f"wjid={wjid}&sfgk=0", timeout=10
    )
    return r.status_code == 200 and "success" in r.text

# 获取全部课程
r = requests.get(
    f"{BASE_URL}/b/wlxt/kc/v_wlkc_xs_xkb_kcb_extend/student/loadCourseBySemesterId/2025-2026-2/zh?_csrf={csrf}",
    headers={k: v for k, v in headers.items() if k != "Content-Type"},
    timeout=15
)
courses = r.json().get("resultList", [])
print(f"共 {len(courses)} 门课程")

total_unread = 0
total_marked = 0

for course in courses:
    wlkcid = course.get("wlkcid", "")
    kcm = course.get("kcm", "?")
    if not wlkcid:
        continue

    r2 = requests.get(
        f"{BASE_URL}/b/wlxt/kj/wlkc_kjxxb/student/kjxxbByWlkcidAndSizeForStudent?wlkcid={wlkcid}&size=100&_csrf={csrf}",
        headers={k: v for k, v in headers.items() if k != "Content-Type"},
        timeout=15
    )
    d = r2.json()
    obj = d.get("object", d)
    items = obj.get("aaData", []) if isinstance(obj, dict) else obj
    unread = [x for x in items if x.get("isNew") == 1]
    if not unread:
        continue

    total_unread += len(unread)
    marked = 0
    for item in unread:
        wjid = item.get("wjid", "")
        bt = item.get("bt", "?")
        if not wjid:
            continue
        if mark_read(wjid):
            marked += 1
        else:
            print(f"  ⚠️ 失败: {bt}")

    print(f"【{kcm}】{len(unread)} 项未读 → 标记 {marked} 项")
    total_marked += marked

print(f"\n总计：{total_unread} 项未读 → 标记已读 {total_marked} 项")
print("完成！")

FILE:scripts/todos_api.py
#!/usr/bin/env python3
"""
todos_api.py
清华网络学堂代办总览 — 纯API版本（默认版本）
==============================================
【流程】
  1. 检查 Session 有效性
  2. 无效 → 自动调 login_auto.py 续期
  3. 并行发出 5 个课程 × 5 个模块 = 25 个请求
  4. 汇总输出

【性能】Session 有效时约 2-3 秒（纯 HTTP，无 Playwright）
【默认运行】python todos.py 时优先调用本文件
"""
import json, requests, sys, time, os, concurrent.futures
sys.stdout.reconfigure(encoding='utf-8')

# ====== 路径 + 账号配置（从 credentials.json 统一加载）=======
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from _config import load_credentials, get_state_file

STATE_FILE = get_state_file()
# ======================

# TOM 的 5 门课程
COURSE_NAME = {
    "2025-2026-2151368648": "大学物理A(1)",
    "2025-2026-2151369314": "概率论与数理统计",
    "2025-2026-2151369343": "英语听说交流(A)",
    "2025-2026-2151368819": "写作与沟通",
    "2025-2026-2151368584": "微积分A(2)",
}

BASE = "https://learn.tsinghua.edu.cn"

HEADERS = {
    "Accept": "application/json, */*",
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "Referer": BASE + "/f/wlxt/index/course/student/",
}


def check_session(state):
    if not state.get("learn_jsession") or not state.get("csrf"):
        return False
    h = {**HEADERS, "X-XSRF-TOKEN": state["csrf"],
         "Cookie": f"JSESSIONID={state['learn_jsession']}; XSRF-TOKEN={state['csrf']}"}
    try:
        r = requests.get(BASE + "/b/wlxt/kczy/zy/student/index/zyListWj?wlkcid=&size=1",
                         headers=h, timeout=10)
        return not ("location.href" in r.text and r.status_code == 200)
    except:
        return False


def auto_relogin():
    script_dir = os.path.dirname(os.path.abspath(__file__))
    auto_script = os.path.join(script_dir, "login_auto.py")
    print("Session 失效，自动续期中...")
    import subprocess
    result = subprocess.run([sys.executable, auto_script],
                             capture_output=True, text=True)
    if result.returncode != 0:
        print("auto login 失败:", result.stderr)
        sys.exit(1)
    return json.load(open(STATE_FILE, encoding="utf-8"))


def api_get(path, csrf, jsession):
    url = (BASE + path) if "?" in path else (BASE + path + "?_csrf=" + csrf)
    if "?" in path:
        url = BASE + path + "&_csrf=" + csrf
    else:
        url = BASE + path + "?_csrf=" + csrf
    h = {**HEADERS, "X-XSRF-TOKEN": csrf,
         "Cookie": f"JSESSIONID={jsession}; XSRF-TOKEN={csrf}"}
    try:
        r = requests.get(url, headers=h, timeout=15)
        return r.json()
    except Exception as e:
        return {}


def fetch_course(wlkcid, csrf, jsession):
    """并行抓一门课的全部代办，返回 dict"""
    d_gg = api_get(f"/b/wlxt/kcgg/wlkc_ggb/student/kcggListXs?wlkcid={wlkcid}&size=20", csrf, jsession)
    d_kj = api_get(f"/b/wlxt/kj/wlkc_kjxxb/student/kjxxbByWlkcidAndSizeForStudent?wlkcid={wlkcid}&size=100", csrf, jsession)
    d_zy = api_get(f"/b/wlxt/kczy/zy/student/index/zyListWj?wlkcid={wlkcid}&size=100", csrf, jsession)
    d_tl = api_get(f"/b/wlxt/bbs/bbs_tltb/student/kctlList?wlkcid={wlkcid}&size=20", csrf, jsession)
    d_dy = api_get(f"/b/wlxt/bbs/bbs_tltb/student/kcdyList?wlkcid={wlkcid}&size=20", csrf, jsession)

    def count_unread(data, field, value):
        if isinstance(data, dict):
            obj = data.get("object", data)
            if isinstance(obj, dict):
                items = obj.get("aaData", [])
            elif isinstance(obj, list):
                items = obj
            else:
                items = []
        elif isinstance(data, list):
            items = data
        else:
            return 0
        return sum(1 for x in items if str(x.get(field, "")).strip('"') == str(value))

    def get_items(data):
        if isinstance(data, dict):
            obj = data.get("object", data)
            if isinstance(obj, list):
                return obj
            elif isinstance(obj, dict):
                return obj.get("aaData", [])
        elif isinstance(data, list):
            return data
        return []

    return {
        "gg": count_unread(d_gg, "sfyd", "否"),
        "kj": count_unread(d_kj, "isNew", "1"),
        "zy": count_unread(d_zy, "zt", "未交"),
        "tl": count_unread(d_tl, "htsl", ""),
        "dy": count_unread(d_dy, "htsl", ""),
        "zy_items": [x for x in get_items(d_zy) if str(x.get("zt", "")).strip('"') == "未交"],
    }


# ====== 主流程 ======
state = json.load(open(STATE_FILE, encoding="utf-8"))
age_h = (time.time() - state.get("timestamp", 0)) / 3600
print(f"Session age={age_h:.1f}h")

if not check_session(state):
    print("⚠️ Session 无效")
    state = auto_relogin()
else:
    print("✅ Session 有效")

csrf = state["csrf"]
jsession = state["learn_jsession"]

# 并行抓所有课程
print("\n并行获取 5 门课程代办数据...")
results = {}
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as ex:
    futures = {ex.submit(fetch_course, wlkcid, csrf, jsession): wlkcid
               for wlkcid in COURSE_NAME.keys()}
    for f in concurrent.futures.as_completed(futures):
        wlkcid = futures[f]
        results[wlkcid] = f.result()

# 汇总输出
print("\n=== 网络学堂代办总览（纯API）===\n")
total = 0
for wlkcid, todos in results.items():
    cname = COURSE_NAME[wlkcid]
    print(f"【{cname}】")
    has = False
    for cat, label in [
        ("zy", "作业未提交"),
        ("gg", "公告未浏览"),
        ("kj", "课件未浏览"),
        ("tl", "讨论我参与"),
        ("dy", "答疑已回答"),
    ]:
        cnt = todos[cat]
        if cnt > 0:
            print(f"  ⚠️ {label}: {cnt} 项")
            total += cnt
            has = True
    if not has:
        print(f"  ✅ 无待处理")

# 作业详情
any_zy = any(todos["zy"] > 0 for todos in results.values())
if any_zy:
    print("\n--- 作业详情 ---")
    for wlkcid, todos in results.items():
        for x in sorted(todos["zy_items"], key=lambda t: t.get("jzsjStr", "")):
            cname = COURSE_NAME[wlkcid]
            print(f"  {cname} | {x.get('bt','?')} | 截止:{x.get('jzsjStr','?')}")

print(f"\n待办总计: {total} 项")
FILE:scripts/todos_dom.py
#!/usr/bin/env python3
"""
todos.py
清华网络学堂代办总览脚本
================================
【流程】
  1. 检查 Session 是否有效
  2. 无效 → 自动调 login_auto.py 续期
  3. Playwright 打开主页读 DOM（权威未读数）
  4. API 获取作业详情（截止时间）
  5. 汇总输出

【性能】
  Session 有效：纯 API → 1-2s
  Session 需续期：Playwright re-login + API → 15-25s
"""
import json, requests, sys, time, shutil, tempfile, re, os
sys.stdout.reconfigure(encoding='utf-8')
from playwright.sync_api import sync_playwright

# ====== 路径 + 账号配置（从 credentials.json 统一加载）=======
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from _config import get_state_file, get_profile_dir, get_fp_file

STATE_FILE = get_state_file()
PROFILE_DIR = get_profile_dir()
FINGERPRINT_FILE = get_fp_file()
COURSE_NAME = {
    "2025-2026-2151368648": "大学物理A(1)",
    "2025-2026-2151369314": "概率论与数理统计",
    "2025-2026-2151369343": "英语听说交流(A)",
    "2025-2026-2151368819": "写作与沟通",
    "2025-2026-2151368584": "微积分A(2)",
}
# ======================


def check_session(state):
    """Session 有效性检查（毫秒级）"""
    if not state.get("learn_jsession") or not state.get("csrf"):
        return False
    h = {
        "Accept": "application/json, */*",
        "Referer": "https://learn.tsinghua.edu.cn/f/wlxt/index/course/student/",
        "X-XSRF-TOKEN": state["csrf"],
        "Cookie": f"JSESSIONID={state['learn_jsession']}; XSRF-TOKEN={state['csrf']}",
    }
    try:
        r = requests.get(
            "https://learn.tsinghua.edu.cn/b/wlxt/kczy/zy/student/index/zyListWj?wlkcid=&size=1",
            headers=h, timeout=10
        )
        return not ("location.href" in r.text and r.status_code == 200)
    except:
        return False


def auto_relogin():
    """调 login_auto.py 续期 Session"""
    script_dir = os.path.dirname(os.path.abspath(__file__))
    auto_script = os.path.join(script_dir, "login_auto.py")
    print("Session 失效，自动续期中...")
    import subprocess
    result = subprocess.run([sys.executable, auto_script],
                             capture_output=True, text=True)
    if result.returncode != 0:
        print("auto login 失败:", result.stderr)
        sys.exit(1)
    print(result.stdout)
    return json.load(open(STATE_FILE, encoding="utf-8"))


def api_get(path, csrf, learn_j):
    url = f"https://learn.tsinghua.edu.cn{path}&_csrf={csrf}" if "?" in path \
          else f"https://learn.tsinghua.edu.cn{path}?_csrf={csrf}"
    return requests.get(url, headers={
        "Accept": "application/json, */*",
        "Referer": "https://learn.tsinghua.edu.cn/f/wlxt/index/course/student/",
        "X-XSRF-TOKEN": csrf,
        "Cookie": f"JSESSIONID={learn_j}; XSRF-TOKEN={csrf}",
    }, timeout=15).json()


# ====== 主流程 ======
# 1. 读取 Session
state = json.load(open(STATE_FILE, encoding="utf-8"))
age_h = (time.time() - state.get("timestamp", 0)) / 3600
print(f"Session age={age_h:.1f}h")

# 2. 检查并续期
if not check_session(state):
    print("⚠️ Session 无效")
    state = auto_relogin()
else:
    print("✅ Session 有效")

csrf = state["csrf"]
learn_j = state["learn_jsession"]

# 3. Playwright 读主页 DOM（权威未读数）
TMP = tempfile.mkdtemp(prefix="todos_")
PROFILE_TMP = os.path.join(TMP, "profile")
os.makedirs(PROFILE_TMP)

pw = sync_playwright().start()
ctx = None
try:
    ctx = pw.chromium.launch_persistent_context(
        PROFILE_TMP, headless=True,
        viewport={"width": 1280, "height": 900},
        ignore_https_errors=True,
        args=["--no-sandbox", "--disable-dev-shm-usage"],
    )
    page = ctx.pages[0] if ctx.pages else ctx.new_page()
    ctx.add_cookies([
        {"name": "JSESSIONID", "value": learn_j, "domain": ".learn.tsinghua.edu.cn", "path": "/"},
        {"name": "XSRF-TOKEN", "value": csrf, "domain": ".learn.tsinghua.edu.cn", "path": "/"},
    ])
    page.goto(
        "https://learn.tsinghua.edu.cn/f/wlxt/index/course/student/",
        timeout=30000, wait_until="networkidle"
    )
    time.sleep(3)
    body_text = page.inner_text("body")
finally:
    if ctx: ctx.close()
    pw.stop()
    shutil.rmtree(TMP, ignore_errors=True)

# 4. 解析主页 DOM
COURSE_CODE = {
    "大学物理A(1)": "10430934",
    "概率论": "10880012",
    "写作与沟通": "10691342",
    "微积分": "2151368584",
}

def parse_courses(text):
    results = {}
    for cname, code in COURSE_CODE.items():
        idx = text.find(cname)
        if idx < 0: continue
        end_idx = len(text)
        for _, other_code in COURSE_CODE.items():
            if other_code == code: continue
            other_pos = text.find(other_code, idx + len(cname))
            if other_pos > idx: end_idx = min(end_idx, other_pos)
        chunk = text[idx:end_idx]
        def get_count(pat):
            m = re.search(pat, chunk)
            return int(m.group(1)) if m else 0
        results[cname] = {
            "gg": get_count(r"公告\s*(\d+)"),
            "kj": get_count(r"课件\s*(\d+)"),
            "zy": get_count(r"作业\s*(\d+)"),
            "tl": get_count(r"讨论\s*(\d+)\s*我参与"),
            "dy": get_count(r"答疑\s*(\d+)"),
            "wj": get_count(r"问卷\s*(\d+)"),
        }
    return results

course_todos = parse_courses(body_text)

# 英语听说交流(A) - 单独处理
eng_idx = body_text.find("英语听说交流")
if eng_idx >= 0:
    eng_chunk = body_text[eng_idx:eng_idx + 800]
    def eng_count(pat):
        m = re.search(pat, eng_chunk)
        return int(m.group(1)) if m else 0
    course_todos["英语听说交流(A)"] = {
        "gg": eng_count(r"公告\s*(\d+)"),
        "kj": eng_count(r"课件\s*(\d+)"),
        "zy": eng_count(r"作业\s*(\d+)"),
        "tl": eng_count(r"讨论\s*(\d+)"),
        "dy": eng_count(r"答疑\s*(\d+)"),
        "wj": eng_count(r"问卷\s*(\d+)"),
    }
else:
    course_todos["英语听说交流(A)"] = {"gg": 0, "kj": 0, "zy": 0, "tl": 0, "dy": 0, "wj": 0}

# 5. API 获取作业详情
def fetch_all_homework():
    results = []
    for wlkcid in COURSE_NAME.keys():
        d = api_get(f"/b/wlxt/kczy/zy/student/index/zyListWj?wlkcid={wlkcid}&size=100", csrf, learn_j)
        items = d.get("object", {}).get("aaData", [])
        for x in items:
            if x.get("zt") == "未交":
                results.append({
                    "wlkcid": wlkcid,
                    "bt": x.get("bt", ""),
                    "jzsjStr": x.get("jzsjStr", ""),
                })
    return results

# 6. 汇总输出
print("\n=== 网络学堂代办总览 ===\n")
total = 0
for cname, todos in course_todos.items():
    print(f"【{cname}】")
    has_todo = False
    for cat, label in [
        ("zy", "作业未提交"), ("gg", "公告未浏览"), ("kj", "课件未浏览"),
        ("tl", "讨论我参与"), ("dy", "答疑已回答"), ("wj", "问卷未提交"),
    ]:
        count = todos[cat]
        if count > 0:
            print(f"  ⚠️ {label}: {count} 项")
            total += count
            has_todo = True
    if not has_todo:
        print(f"  ✅ 无待处理")

# 作业详情
has_zy = any(todos["zy"] > 0 for todos in course_todos.values())
if has_zy:
    print("\n--- 作业详情 ---")
    hw_list = fetch_all_homework()
    for x in sorted(hw_list, key=lambda x: x.get("jzsjStr", "")):
        name2 = COURSE_NAME.get(x["wlkcid"], x["wlkcid"])
        print(f"  {name2} | {x['bt']} | 截止:{x['jzsjStr']}")

print(f"\n待办总计: {total} 项")

FILE:scripts/_config.py
#!/usr/bin/env python3
"""
_config.py — 网络学堂凭证加载器
所有脚本通过 import _config 获取账号密码
不要在任何脚本里硬编码账号密码

路径说明：
  _config.py 位于 skills/tsinghua-learn/scripts/
  credentials.json 位于 skills/tsinghua-learn/
  相对路径：../../credentials.json
"""
import os, json

# skills/tsinghua-learn/scripts/ → 上两级是 skill 根目录
_SKILL_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
_CRED_FILE = os.path.join(_SKILL_DIR, "credentials.json")
_STATE_FILE = os.path.join(_SKILL_DIR, "sessions", "learn_session.json")
_FP_FILE = r"D:\testclaw\learn_fingerprint.json"
_PROFILE_DIR = os.path.join(_SKILL_DIR, "profiles", "learn_profile")


def load_credentials():
    """加载账号密码，若文件不存在或格式错误则提示用户"""
    if not os.path.exists(_CRED_FILE):
        raise FileNotFoundError(
            "credentials.json 未找到！\n"
            "请复制 config_example.json 为 credentials.json，"
            "并填入你的学号和密码。\n"
            "路径: " + _CRED_FILE
        )
    try:
        cred = json.load(open(_CRED_FILE, encoding="utf-8"))
        u = cred.get("username", "").strip()
        p = cred.get("password", "").strip()
        if not u or not p:
            raise ValueError("username 或 password 为空")
        return u, p
    except Exception as e:
        raise RuntimeError(
            f"credentials.json 读取失败: {e}\n"
            "请检查文件格式是否正确（需包含 username 和 password 字段）"
        )


def get_state_file():
    return _STATE_FILE


def get_fp_file():
    return _FP_FILE


def get_profile_dir():
    return _PROFILE_DIR


def get_skill_dir():
    return _SKILL_DIR
FILE:sessions/learn_session.json
{
  "learn_jsession": "",
  "learn_token": "",
  "csrf": "",
  "timestamp": null,
  "url": ""
}

ClawHub Coding Backend+2

Florence

Skill

Florence is the Renaissance birthplace and Tuscan capital, renowned for art, architecture, luxury fashion, and attracting over 12 million visitors yearly.

---
summary: Florence (Firenze) — birthplace of the Renaissance, Tuscan capital, global center of art, architecture, and luxury fashion, attracting 12M+ visitors annually.
read_when:
- Researching Renaissance history and cultural heritage
- Studying art tourism economics and cultural preservation
- Analyzing Italian luxury fashion and leather goods industry
- Exploring UNESCO World Heritage site management
---

# Florence

## 历史时间线

- 59 BC: Founded as Roman settlement 'Florentia'
- 1115: Becomes independent commune
- 1300s: Medici family rises to power, banks become Europe's largest
- 1400s: Golden Age of Renaissance — Brunelleschi, Botticelli, Leonardo, Michelangelo
- 1569: Becomes capital of Grand Duchy of Tuscany
- 1865: Serves as capital of unified Italy (1865-1871)
- 1966: Devastating Arno River flood damages art and manuscripts
- 2023: Tourism exceeds 12M visitors, facing overtourism challenges


## 商业模式

Tourism (Uffizi, Duomo, Ponte Vecchio, Accademia), luxury fashion (Gucci founded here, Salvatore Ferragamo, Roberto Cavalli), leather goods and artisan crafts, wine (Chianti region), education (international art and language schools), and cultural events.

## 护城河分析

Unmatched concentration of Renaissance art and architecture — home to works by Michelangelo, Botticelli, Leonardo, Brunelleschi. Uffizi Gallery is one of the world's most visited museums. Global brand as 'cradle of Renaissance.' UNESCO World Heritage historic center.

## 关键数据

- **Population:** ~380,000 (city), ~1.5M (metro)
- **Annual Visitors:** 12M+
- **Unesco Status:** World Heritage Site (1982)
- **Major Attractions:** Uffizi Gallery, Duomo, Ponte Vecchio, Accademia (David), Palazzo Pitti
- **Luxury Brands Originated:** Gucci, Salvatore Ferragamo, Roberto Cavalli, Emilio Pucci


## 有趣事实

- The Uffizi Gallery was originally built in 1560 as offices ('uffizi' = offices) for Florence's magistrates — it only became a museum when the Medici family moved their art collection there.
- Florence's historic ban on chain stores in the city center means you won't find a McDonald's within the medieval walls — a deliberate preservation of the city's character.

ClawHub Marketing Education

H@clawhub-hanxueyuan-e623f15c7a

Multi Unit Test Report

Skill

Generate structured markdown test reports for online English classes covering multiple units. Use when the user needs to create a student test report for rev...

---
name: multi-unit-test-report
description: Generate structured markdown test reports for online English classes covering multiple units. Use when the user needs to create a student test report for review units that cover multiple previous units (e.g., Unit 4 reviewing Units 1-3). Triggers on phrases like "multi unit report", "review unit report", "generate report for review unit", or when reviewing student performance across multiple units.
---

# Multi Unit Test Report

## Mission Statement

Before generating any report, read the mission statement from the Obsidian vault:

```
/Users/recom273/Library/Mobile Documents/iCloud~md~obsidian/Documents/Obsidianclaw/projects/system/openclaw/skills/mission statement multi unit test report.md
```

This file contains the canonical report format, workflow, and improvement suggestions. Always follow the mission statement's guidance for tone and structure.

## Workflow

1. **Read the opening slide** — Check the top left for the level (e.g., PF3, PF5, PF7) and unit number. This is a review unit covering multiple previous units.
2. **Read all summary slides** — These are typically the last slides in the folder. Extract information from each unit reviewed.
3. **Ask about student performance** — Ask the user: "Is there anything the student has performed well in?" Incorporate this into the opening praise.
4. **Create an opening sentence** praising the student using suggested topics and specific performance notes.
5. **Detail the material covered** from each unit, section by section.
6. **Add the standard points to improve** — randomly select 3 from the approved list.

## Report Structure

Each report follows this exact format (correct typos from the mission statement):

```markdown
[Opening praise sentence]
# [Student Name]

Todays test covered material from, [unit number]

We featured

**Vocabulary** — [vocabulary topic from all units]

**Grammar** — We learned how to [grammar point from all units][Performance notes]

**Phonics** — We studied the sound [phonic details from all units][Performance notes]

**Around the world** — In this lesson [lesson summary from all units][Performance notes]

**Story** — We read a story about [story synopsis from all units][Performance notes]

**Song** - We ended by singing a song about [song synopsis from all units][Performance notes]

**Life Science** — We learned [science point from relevant units][Performance notes]

**Social Science** — We learned [social science point from relevant units][Performance notes]

**Social Values** — We learned [value point from relevant units][Performance notes]

## Areas for Improvement

It's hard to suggest ways for a student to improve who has just achieved a full score. [select three random points of improvement]

[point 1]
[point 2]
[point 3]
```

## Key Differences from Single Unit Report

- **Multiple units covered** — The report summarizes content from 2-3 previous units
- **Review unit format** — Opening slide shows "Unit X (Unit Y - Unit Z Review)"
- **Summary slides** — Read ALL summary slides at the end (one per unit reviewed)
- **Combined content** — Group similar sections across units (e.g., all vocabulary together, all grammar together)

## Ways to Improve

Randomly select 3 points from this list:

| Points |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Its good practice for the future if you read the full sentences including the answer, often in English if the sentence sounds correct then it is correct. |
| Always read the full sentences aloud. Reading aloud is a good way of identifying any mistakes that you may have made. |
| Keep practicing! Practice makes perfect. |
| Speak up! Try to use the freetalk at the beginning of the lesson to expand your conversational ability. |
| Always review the previous lessons before the final test, this will help you guarantee a 💯 100% score next time. |
| Try to use full sentences during the lesson, not just one-word answers. |
| Listen carefully to the questions and make sure you understand before answering. |
| Don't be afraid to make mistakes - that's how we learn! Keep trying. |

## Output Location

Save reports to the folder provided by the user. Default to workspace if no location specified.

ClawHub Testing Research+2

R@clawhub-recom273-67eb3fd624

Class Reminder

Skill

课程提醒助手。解析 Excel 课程表（支持教师课表格式），按日期梳理课程安排，支持查询今天/明天/指定日期的课程，生成上课提醒。触发场景：(1) 用户上传课程表后询问"明天有什么课"、"今天上什么课"、"XX号有什么课"；(2) 设置定时提醒，每天/每周自动推送次日课程；(3) 解析、导入、更新课程表；(4)...

---
name: class-reminder
description: 课程提醒助手。解析 Excel 课程表（支持教师课表格式），按日期梳理课程安排，支持查询今天/明天/指定日期的课程，生成上课提醒。触发场景：(1) 用户上传课程表后询问"明天有什么课"、"今天上什么课"、"XX号有什么课"；(2) 设置定时提醒，每天/每周自动推送次日课程；(3) 解析、导入、更新课程表；(4) 需要生成课程提醒文本。
---

# 课程提醒 Skill

## 核心流程

### 1. 解析课程表

用户提供 Excel 课程表文件后，用脚本解析：

```bash
python3 scripts/class_reminder.py parse <excel文件> [--semester-start YYYY-MM-DD]
```

支持两种格式：
- **标准格式**：每行一节课程，包含课程名称、星期、时间、地点等列
- **教师课表格式**：行列式表格，行=时间段，列=星期，单元格=课程信息

解析后保存课程数据到 `data/schedule.json`（在工作区创建）。

### 2. 查询课程

```bash
# 明天的课程
python3 scripts/class_reminder.py tomorrow data/schedule.json

# 今天的课程  
# 指定日期
python3 scripts/class_reminder.py date data/schedule.json --date 2026-04-25
```

### 3. 生成提醒文本

脚本返回的 `formatted` 字段即为可直接发送的提醒文案。

## 教师课表格式支持

**表格结构：**
- 行：时间段（第1-2节、第3-4节...）
- 列：星期一到星期日
- 单元格：课程信息，如 `【实验】网络与系统安全 [1-4节][6-6周] [T2604-T2606]`

**课程信息解析：**
- 课程类型：【实验】、【理论】等
- 课程名称：网络与系统安全
- 节次范围：[1-4节]
- 周次范围：[6-6周] 或 [11-12,14-14周]
- 教室：[T2604-T2606]

**特殊处理：**
- 一个单元格可包含多门课程（换行分隔）
- 自动展开节次范围和周次范围
- 支持复杂的周次格式（如 "11-12,14-14周"）

## 定时提醒

设置每天提醒明日课程：

1. 首次需要用户提供课程表文件并解析
2. 使用 cron 或 heartbeat 定时检查  
3. 每次触发时运行 `tomorrow` 命令，发送 `formatted` 文本

## 数据存储

解析后的课程数据保存到 `data/schedule.json`，后续查询直接读取，无需重复解析。

## 注意事项

- 学期开始日期影响周次计算，默认为当前学期估算（9月秋季/2月春季）
- 用户可显式指定 `--semester-start` 覆盖默认值
- 调休、节假日需要手动更新课程表或添加备注
- 依赖 openpyxl，首次使用需 `pip install openpyxl`

FILE:package.json
{
  "name": "class-reminder",
  "version": "1.0.0",
  "description": "课程提醒助手 - 解析教师课表，自动推送每日/每周课程提醒",
  "author": "",
  "license": "MIT",
  "keywords": ["课程", "提醒", "教师", "课表", "schedule", "reminder"]
}

FILE:scripts/auto_remind.sh
#!/bin/bash
# auto_remind.sh - 自动课程提醒脚本

SCRIPT_DIR="$(cd "$(dirname "BASH_SOURCE[0]")" && pwd)"
SCHEDULE_FILE="$SCRIPT_DIR/../data/schedule.xlsx"
SEMESTER_START="2026-03-09"

# 运行课程查询
RESULT=$(python3 "$SCRIPT_DIR/class_reminder.py" tomorrow "$SCHEDULE_FILE" --semester-start "$SEMESTER_START" 2>/dev/null)

# 提取格式化文本
FORMATTED=$(echo "$RESULT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('formatted', '查询失败'))")

# 输出提醒文本
echo "$FORMATTED"

FILE:scripts/class_reminder.py
#!/usr/bin/env python3
"""
class_reminder.py - 课程提醒核心脚本（支持教师课表格式）

功能：
1. parse_teacher_schedule(excel_path) - 解析教师课表Excel，返回结构化课程数据
2. get_todays_classes(schedule_data, date_str) - 查询指定日期的课程
3. get_tomorrows_classes(schedule_data, date_str) - 查询明日课程（用于提醒）

教师课表格式：
- 行：时间段（第1-2节、第3-4节等）
- 列：星期一到星期日
- 单元格：课程信息，如 "【实验】网络与系统安全 [1-4节][6-6周] [T2604-T2606]"
"""

import sys
import json
import re
from datetime import datetime, timedelta
from pathlib import Path

try:
    import openpyxl
except ImportError:
    print(json.dumps({"error": "缺少 openpyxl 库，请运行: pip install openpyxl"}))
    sys.exit(1)


def parse_time_slot(slot_str):
    """解析时间段字符串，如 '第1-2节' -> (1, 2)
    返回 (start_section, end_section)
    """
    if not slot_str:
        return (1, 2)  # 默认
    
    # 匹配 "第1-2节" 或 "第1节"
    m = re.search(r'第(\d+)(?:-(\d+))?节', str(slot_str))
    if m:
        start = int(m.group(1))
        end = int(m.group(2)) if m.group(2) else start
        return (start, end)
    
    # 匹配纯数字 "1-2" 或 "1"
    m = re.search(r'(\d+)(?:-(\d+))?', str(slot_str))
    if m:
        start = int(m.group(1))
        end = int(m.group(2)) if m.group(2) else start
        return (start, end)
    
    return (1, 2)


def section_to_time(section):
    """将节次转换为时间
    1: 08:00, 2: 08:50, 3: 10:00, 4: 10:50, 5: 14:00, 6: 14:50, 7: 16:00, 8: 16:50, 9: 19:00, 10: 19:50
    """
    time_map = {
        1: "08:00", 2: "08:50", 3: "10:00", 4: "10:50",
        5: "14:00", 6: "14:50", 7: "16:00", 8: "16:50",
        9: "19:00", 10: "19:50", 11: "20:40"
    }
    return time_map.get(section, "08:00")


def parse_course_info(course_text):
    """解析课程信息文本
    输入: "【实验】网络与系统安全 [1-4节][6-6周] [T2604-T2606]"
    返回: {
        "type": "实验",
        "name": "网络与系统安全", 
        "section_range": [1, 4],
        "week_range": [6, 6],
        "location": "T2604-T2606"
    }
    """
    if not course_text or str(course_text).strip() == "None":
        return None
        
    text = str(course_text).strip()
    
    # 提取课程类型 【实验】
    course_type = ""
    type_match = re.search(r'【([^】]+)】', text)
    if type_match:
        course_type = type_match.group(1)
        text = text.replace(type_match.group(0), "").strip()
    
    # 提取节次范围 [1-4节]
    section_range = [1, 2]
    section_match = re.search(r'\[(\d+)(?:-(\d+))?节\]', text)
    if section_match:
        start = int(section_match.group(1))
        end = int(section_match.group(2)) if section_match.group(2) else start
        section_range = [start, end]
        text = text.replace(section_match.group(0), "").strip()
    
    # 提取周次范围 [6-6周] 或 [11-12,14-14周]
    week_ranges = []
    week_match = re.search(r'\[((?:\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)?)周\]', text)
    if week_match:
        weeks_str = week_match.group(1)
        if weeks_str:
            # 处理 "11-12,14-14" 这样的格式
            for part in weeks_str.split(','):
                part = part.strip()
                if '-' in part:
                    start_w, end_w = map(int, part.split('-'))
                    week_ranges.extend(range(start_w, end_w + 1))
                else:
                    week_ranges.append(int(part))
        text = text.replace(week_match.group(0), "").strip()
    
    if not week_ranges:
        week_ranges = list(range(1, 21))  # 默认全学期
    
    # 剩余部分是课程名称和地点
    parts = [p.strip() for p in text.split('[') if p.strip()]
    course_name = ""
    location = "待定"
    
    if parts:
        # 第一部分通常是课程名称
        course_name = parts[0].rstrip(']').strip()
        # 其他部分可能是地点
        if len(parts) > 1:
            location = parts[1].rstrip(']').strip()
    
    return {
        "type": course_type,
        "name": course_name,
        "section_range": section_range,
        "week_list": sorted(set(week_ranges)),
        "location": location or "待定"
    }


def parse_teacher_schedule(excel_path, semester_start=None):
    """
    解析教师课表Excel文件。
    
    Args:
        excel_path: Excel 文件路径
        semester_start: 学期开始日期 (YYYY-MM-DD)
    
    Returns:
        dict: {
            "classes": [...],        # 课程列表
            "semester_start": str,   # 学期开始日期
            "error": str or None
        }
    """
    excel_path = Path(excel_path)
    if not excel_path.exists():
        return {"classes": [], "error": f"文件不存在: {excel_path}"}
    
    try:
        wb = openpyxl.load_workbook(excel_path, data_only=True)
    except Exception as e:
        return {"classes": [], "error": f"无法打开文件: {e}"}
    
    classes = []
    
    for sheet_name in wb.sheetnames:
        ws = wb[sheet_name]
        rows = list(ws.iter_rows(values_only=True))
        
        if not rows or len(rows) < 2:
            continue
            
        # 第一行是标题 "时间", "教师课表"
        # 第二行是星期列头：星期一、星期二...
        if len(rows) < 2:
            continue
            
        weekday_headers = rows[1]  # 第二行
        time_slots = []  # 时间段列表
        
        # 构建星期映射
        weekday_map = {}
        for col_idx, header in enumerate(weekday_headers):
            if header and str(header).strip():
                day_str = str(header).strip()
                if "星期一" in day_str:
                    weekday_map[col_idx] = 1
                elif "星期二" in day_str:
                    weekday_map[col_idx] = 2
                elif "星期三" in day_str:
                    weekday_map[col_idx] = 3
                elif "星期四" in day_str:
                    weekday_map[col_idx] = 4
                elif "星期五" in day_str:
                    weekday_map[col_idx] = 5
                elif "星期六" in day_str:
                    weekday_map[col_idx] = 6
                elif "星期日" in day_str:
                    weekday_map[col_idx] = 7
        
        # 解析课程数据行
        for row_idx in range(2, len(rows)):
            row = rows[row_idx]
            if not row or not any(row):
                continue
                
            # 第一列是时间段
            time_slot_cell = row[0] if len(row) > 0 else None
            if not time_slot_cell:
                continue
                
            time_slot = parse_time_slot(time_slot_cell)
            
            # 解析每个星期的课程
            for col_idx in range(1, len(row)):
                if col_idx not in weekday_map:
                    continue
                    
                cell_content = row[col_idx]
                if not cell_content or str(cell_content).strip() in ("None", ""):
                    continue
                
                # 一个单元格可能包含多门课程（换行分隔）
                course_entries = str(cell_content).split('\n')
                for entry in course_entries:
                    entry = entry.strip()
                    if not entry:
                        continue
                        
                    course_info = parse_course_info(entry)
                    if not course_info:
                        continue
                        
                    # 为节次范围内的每一节课创建记录（但合并同一课程）
                    # 使用课程名+类型+星期+开始节次作为唯一键去重
                    course_key = f"{course_info['name']}_{course_info['type']}_{weekday_map[col_idx]}_{course_info['section_range'][0]}"
                    
                    # 只添加一次，保留节次范围信息
                    classes.append({
                        "name": course_info["name"],
                        "type": course_info["type"],
                        "weekday": weekday_map[col_idx],
                        "section_start": course_info["section_range"][0],
                        "section_end": course_info["section_range"][1],
                        "start_time": section_to_time(course_info["section_range"][0]),
                        "end_time": section_to_time(course_info["section_range"][1] + 1) if course_info["section_range"][1] + 1 <= 12 else "21:30",
                        "location": course_info["location"],
                        "week_list": course_info["week_list"],
                        "sheet": sheet_name,
                    })
    
    if semester_start is None:
        semester_start = _guess_semester_start()
    
    return {
        "classes": classes,
        "semester_start": semester_start,
        "error": None,
    }


def _guess_semester_start():
    """根据当前日期推测学期开始日期"""
    now = datetime.now()
    year = now.year
    
    # 春季学期从2月开始，秋季学期从9月开始
    if now.month >= 9:
        return f"{year}-09-01"
    elif now.month >= 2:
        return f"{year}-02-15"
    else:
        return f"{year - 1}-09-01"


def _get_week_number(date_str, semester_start):
    """计算指定日期是第几周"""
    date = datetime.strptime(date_str, "%Y-%m-%d")
    start = datetime.strptime(semester_start, "%Y-%m-%d")
    delta = (date - start).days
    week_num = delta // 7 + 1
    return max(1, week_num)


def get_classes_for_date(schedule_data, date_str):
    """
    获取指定日期的课程列表。
    """
    classes = schedule_data.get("classes", [])
    semester_start = schedule_data.get("semester_start", _guess_semester_start())
    
    try:
        date = datetime.strptime(date_str, "%Y-%m-%d")
    except ValueError:
        return []
    
    weekday = date.isoweekday()  # 1=周一, 7=周日
    week_num = _get_week_number(date_str, semester_start)
    
    today_classes = []
    for cls in classes:
        # 检查星期是否匹配
        if cls.get("weekday") != weekday:
            continue
            
        # 检查周次是否在范围内
        week_list = cls.get("week_list", [])
        if week_list and week_num not in week_list:
            continue
            
        today_classes.append({
            "name": cls["name"],
            "type": cls.get("type", ""),
            "start_time": cls["start_time"],
            "end_time": cls.get("end_time", ""),
            "location": cls.get("location", "待定"),
            "section_start": cls.get("section_start", 1),
            "section_end": cls.get("section_end", 2),
        })
    
    # 去重：按课程名+开始时间+地点
    seen = set()
    unique_classes = []
    for cls in today_classes:
        key = f"{cls['name']}_{cls['start_time']}_{cls['location']}"
        if key not in seen:
            seen.add(key)
            unique_classes.append(cls)
    
    # 按开始节次排序
    unique_classes.sort(key=lambda x: x["section_start"])
    return unique_classes


def get_tomorrows_classes(schedule_data, date_str=None):
    """
    获取明天的课程列表。
    """
    if date_str is None:
        tomorrow = datetime.now() + timedelta(days=1)
        date_str = tomorrow.strftime("%Y-%m-%d")
    else:
        tomorrow = datetime.strptime(date_str, "%Y-%m-%d") + timedelta(days=1)
        date_str = tomorrow.strftime("%Y-%m-%d")
    
    weekday_names = {1: "周一", 2: "周二", 3: "周三", 4: "周四", 5: "周五", 6: "周六", 7: "周日"}
    
    classes = get_classes_for_date(schedule_data, date_str)
    tomorrow_weekday = tomorrow.isoweekday()
    
    return {
        "date": date_str,
        "weekday": weekday_names.get(tomorrow_weekday, ""),
        "classes": classes,
    }


def format_reminder_text(reminder_data):
    """
    将明日课程数据格式化为提醒文本。
    """
    date = reminder_data.get("date", "")
    weekday = reminder_data.get("weekday", "")
    classes = reminder_data.get("classes", [])
    
    if not classes:
        return f"📅 {date}（{weekday}）没有课程安排，好好休息！🍋"
    
    lines = [f"📅 明天 {date}（{weekday}）的课程提醒：\n"]
    
    for i, cls in enumerate(classes, 1):
        time_range = cls["start_time"]
        if cls.get("end_time"):
            time_range = f"{cls['start_time']}-{cls['end_time']}"
        
        course_title = cls["name"]
        if cls.get("type"):
            course_title = f"【{cls['type']}】{course_title}"
            
        line = f"  {i}. {course_title}"
        line += f"\n     ⏰ {time_range}"
        line += f"\n     📍 {cls['location']}"
        
        lines.append(line)
    
    lines.append(f"\n共 {len(classes)} 节课，加油！🍋")
    return "\n".join(lines)


def main():
    """命令行入口"""
    import argparse
    
    parser = argparse.ArgumentParser(description="教师课程提醒工具")
    parser.add_argument("action", choices=["parse", "today", "tomorrow", "date"], help="操作类型")
    parser.add_argument("file", help="Excel 课程表文件路径")
    parser.add_argument("--date", help="指定日期 (YYYY-MM-DD)")
    parser.add_argument("--semester-start", help="学期开始日期 (YYYY-MM-DD)")
    parser.add_argument("--output", help="输出文件路径（JSON格式）")
    
    args = parser.parse_args()
    
    semester_start = args.semester_start
    
    if args.action == "parse":
        result = parse_teacher_schedule(args.file, semester_start)
        output = {
            "status": "ok" if result["error"] is None else "error",
            "course_count": len(result["classes"]),
            "semester_start": result["semester_start"],
            "error": result["error"],
        }
    elif args.action == "today":
        date = args.date or datetime.now().strftime("%Y-%m-%d")
        schedule = parse_teacher_schedule(args.file, semester_start)
        classes = get_classes_for_date(schedule, date)
        output = {
            "date": date,
            "course_count": len(classes),
            "courses": classes,
            "error": schedule.get("error"),
        }
    elif args.action == "tomorrow":
        schedule = parse_teacher_schedule(args.file, semester_start)
        base_date = args.date or datetime.now().strftime("%Y-%m-%d")
        result = get_tomorrows_classes(schedule, base_date)
        output = {
            **result,
            "formatted": format_reminder_text(result),
            "error": schedule.get("error"),
        }
    elif args.action == "date":
        if not args.date:
            print("错误: date 操作需要 --date 参数")
            sys.exit(1)
        schedule = parse_teacher_schedule(args.file, semester_start)
        classes = get_classes_for_date(schedule, args.date)
        
        # 计算星期
        date_obj = datetime.strptime(args.date, "%Y-%m-%d")
        weekday_names = {1: "周一", 2: "周二", 3: "周三", 4: "周四", 5: "周五", 6: "周六", 7: "周日"}
        weekday = weekday_names.get(date_obj.isoweekday(), "")
        
        result = {
            "date": args.date,
            "weekday": weekday,
            "classes": classes,
            "formatted": format_reminder_text({
                "date": args.date,
                "weekday": weekday,
                "classes": classes,
            }),
        }
        output = {
            **result,
            "error": schedule.get("error"),
        }
    else:
        output = {"error": f"未知操作: {args.action}"}
    
    if args.output:
        Path(args.output).write_text(json.dumps(output, ensure_ascii=False, indent=2))
        print(f"结果已保存到: {args.output}")
    else:
        print(json.dumps(output, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

FILE:scripts/daily_class_reminder.py
#!/usr/bin/env python3
"""
daily_class_reminder.py - 每日课程提醒
由 OpenClaw 定时任务调用，查询明天课程并发送提醒
"""

import json
import sys
import os

# 添加 skill 脚本路径
sys.path.insert(0, '/home/admin/.openclaw/workspace/skills/class-reminder/scripts')
from class_reminder import parse_teacher_schedule, get_tomorrows_classes, format_reminder_text

# 配置
SCHEDULE_FILE = '/home/admin/.openclaw/workspace/data/schedule.xlsx'
SEMESTER_START = '2026-03-09'

def main():
    try:
        # 解析课程表
        schedule_data = parse_teacher_schedule(SCHEDULE_FILE, SEMESTER_START)
        
        if schedule_data.get('error'):
            print(f"❌ 解析课程表失败: {schedule_data['error']}")
            return 1
        
        # 获取明天课程
        result = get_tomorrows_classes(schedule_data)
        
        # 生成提醒文本
        reminder_text = format_reminder_text(result)
        
        # 输出提醒（OpenClaw 会捕获并发送）
        print(reminder_text)
        
        return 0
        
    except Exception as e:
        print(f"❌ 查询课程失败: {e}")
        return 1

if __name__ == '__main__':
    sys.exit(main())

FILE:scripts/weekly_class_overview.py
#!/usr/bin/env python3
"""
weekly_class_overview.py - 每周课程概览
生成下周（周一至周日）的课程概览
"""

import json
import sys
from datetime import datetime, timedelta

sys.path.insert(0, '/home/admin/.openclaw/workspace/skills/class-reminder/scripts')
from class_reminder import parse_teacher_schedule, get_classes_for_date

SCHEDULE_FILE = '/home/admin/.openclaw/workspace/data/schedule.xlsx'
SEMESTER_START = '2026-03-09'

WEEKDAY_NAMES = {1: '周一', 2: '周二', 3: '周三', 4: '周四', 5: '周五', 6: '周六', 7: '周日'}

def get_next_week_dates():
    """获取下周的日期列表（周一到周日）"""
    today = datetime.now()
    # 找到下周一
    days_until_monday = (7 - today.weekday()) % 7
    if days_until_monday == 0:  # 今天已经是周一，取下周
        days_until_monday = 7
    next_monday = today + timedelta(days=days_until_monday)
    
    # 生成下周每一天的日期
    week_dates = []
    for i in range(7):
        date = next_monday + timedelta(days=i)
        week_dates.append({
            'date': date.strftime('%Y-%m-%d'),
            'weekday': date.isoweekday(),
            'weekday_name': WEEKDAY_NAMES[date.isoweekday()]
        })
    
    return week_dates

def main():
    try:
        # 解析课程表
        schedule_data = parse_teacher_schedule(SCHEDULE_FILE, SEMESTER_START)
        
        if schedule_data.get('error'):
            print(f"❌ 解析课程表失败: {schedule_data['error']}")
            return 1
        
        # 获取下周日期
        week_dates = get_next_week_dates()
        
        # 收集每天的课程
        week_classes = {}
        for day_info in week_dates:
            classes = get_classes_for_date(schedule_data, day_info['date'])
            if classes:
                week_classes[day_info['weekday_name']] = classes
        
        # 生成概览文本
        lines = ["📅 下周课程概览", ""]
        
        if not week_classes:
            lines.append("🎉 下周没有课程安排，好好休息！")
        else:
            for day_name in ['周一', '周二', '周三', '周四', '周五', '周六', '周日']:
                if day_name not in week_classes:
                    continue
                    
                lines.append(f"\n【{day_name}】")
                for i, cls in enumerate(week_classes[day_name], 1):
                    course_title = cls['name']
                    if cls.get('type'):
                        course_title = f"【{cls['type']}】{course_title}"
                    
                    time_range = cls['start_time']
                    if cls.get('end_time'):
                        time_range = f"{cls['start_time']}-{cls['end_time']}"
                    
                    lines.append(f"  {i}. {course_title}")
                    lines.append(f"     ⏰ {time_range}  📍 {cls['location']}")
        
        lines.append("")
        lines.append("🍋 提前规划，高效学习！")
        
        print("\n".join(lines))
        return 0
        
    except Exception as e:
        print(f"❌ 生成概览失败: {e}")
        import traceback
        traceback.print_exc()
        return 1

if __name__ == '__main__':
    sys.exit(main())

ClawHub Data Analysis Research+2

J@clawhub-judysue-cbabac6523

infant-flights

Skill

Book infant flights, baby travel tickets and bassinet seat options with child fare and infant-in-arm booking. Also supports: flight booking, hotel reservatio...

---
name: infant-flights
displayName: "Book Infant Flights — Baby Travel, Bassinet Seats, Child Fare Tickets"
description: "Book infant flights, baby travel tickets and bassinet seat options with child fare and infant-in-arm booking. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below. If a flag is not listed, it does not exist.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: infant-flights

## Overview

Book infant flights — baby travel, bassinet seats, and child fare tickets. For parents traveling with infants and young children.

## When to Activate

User query contains:
- English: "infant flight", "baby flight", "bassinet seat", "child fare", "travel with baby", "infant ticket"
- Chinese: "婴儿机票", "宝宝航班", "婴儿摇篮", "儿童机票", "带婴儿乘机", "婴儿票"

Do NOT activate for: family trip planning (flights+hotel) → `family-trip`; student fares → `student-deal`

## Prerequisites

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-hour-start` | No | Default: 6 (avoid early morning rush) |
| `--dep-hour-end` | No | Default: 20 (avoid late arrivals with baby) |
| `--sort-type` | No | **Default: 4** (duration ascending — shortest trip for baby comfort) |
| `--journey-type` | No | 1=direct (strongly preferred with infants), 2=connecting |
| `--seat-class-name` | No | economy / business / first |
| `--max-price` | No | Price ceiling in CNY |

### Sort Options

| Value | Meaning | When to Use |
|-------|---------|-------------|
| `4` | Duration ascending | **Default** — shortest trip for baby comfort |
| `8` | Direct flights first | No transfers — essential with infants |
| `2` | Recommended | Best overall options |
| `3` | Price ascending | Cheapest infant-eligible fares |

## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Shortest Infant-Friendly Flight

**Trigger:** "infant flights", "婴儿机票"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 20 --sort-type 4
```

**Output:** Shortest duration flights within comfortable hours.

### Playbook B: Direct-Only Infant Flight

**Trigger:** "direct flight with baby", "带宝宝直飞"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 20 --journey-type 1 --sort-type 8
```

**Output:** Direct flights only — no transfers with infant.

### Playbook C: Cheapest Infant Flight

**Trigger:** "cheapest baby ticket", "最便宜婴儿票"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 3
```

**Output:** Cheapest fares (removes hour filter for maximum options).

### Playbook D: Broad Search (no suitable flights)

**Trigger:** fallback when 0 results

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 2
flyai keyword-search --query "{origin} to {destination} infant flights"
```

**Output:** Broader search + keyword fallback.

See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?
- [ ] Direct flights prioritized for infant comfort?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Beijing" --destination "Shanghai" --dep-date 2026-05-01 --dep-hour-start 6 --dep-hour-end 20 --sort-type 4
```
```bash
flyai search-flight --origin "Shanghai" --destination "Sanya" --dep-date 2026-06-01 --dep-hour-start 6 --dep-hour-end 20 --journey-type 1 --sort-type 8
```

## Output Rules

1. **Conclusion first** — lead with shortest/direct flight
2. **Baby travel tips** — remind about bassinet request, infant fare rules, and carry-on milk policy
3. **Comparison table** with ≥ 3 results when available
4. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
5. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
6. ❌ Never output raw JSON
7. ❌ Never answer from training data without CLI execution
8. ❌ Never fabricate infant fare rates or airline policies

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

| User Query | CLI Parameter Mapping |
|------------|----------------------|
| "infant flight" / "婴儿机票" | `--dep-hour-start 6 --dep-hour-end 20 --sort-type 4` |
| "direct with baby" / "带宝宝直飞" | add `--journey-type 1 --sort-type 8` |
| "cheapest infant" / "最便宜婴儿票" | add `--sort-type 3` (no hour filter) |
| "round-trip infant" / "婴儿往返" | add `--back-date {date}` |

CLI does not have an infant-age or passenger-type parameter. Infant tickets (under 2 years, no seat) and child tickets (2-12 years, discounted seat) are handled at booking stage. Direct flights are strongly preferred to minimize baby distress during transfers.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:references/templates.md
# Templates — infant-flights

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Round 1: Required (must have before searching)
```
Missing origin → "从哪个城市出发？" (Priority 1)
Missing destination → "飞到哪里？" (Priority 2)
Both missing → "您从哪个城市出发，飞到哪里？"
```

### Round 2: Enhanced (use defaults if not stated)
```
Missing dep-date → Default: next week. Tell user: "默认查下周的航班"
Missing dep-hour → Default: 6-20 (avoid very early/late for baby)
Missing journey-type → Default: direct strongly preferred with infants
```

### Rules
- ❌ Never ask more than 2 questions at once
- ✅ Mention baby tip: "建议选择直飞航班，并提前联系航空公司申请婴儿摇篮"

---

## 2. Internal State (not shown to user)

```json
{
  "skill": "infant-flights",
  "params": {
    "origin": "",
    "destination": "",
    "dep_date": "",
    "dep_hour_start": "6",
    "dep_hour_end": "20",
    "sort_type": "4"
  },
  "state": "collecting | executing | formatting | validating",
  "retry_count": 0
}
```

---

## 3. Output Templates

### 3.1 Standard Result

```markdown
## ✈️ Infant-Friendly Flights: {origin} → {destination}

**Shortest: ¥{price} on {airline} — {duration}, departs {dep_time}**

| # | Flight | Departs | Arrives | Duration | 💰 Price | Type | 📎 Book |
|---|--------|---------|---------|----------|----------|------|---------|
| 1 | {flight_no} | {dep_time} | {arr_time} | {duration} | ¥{price} | Direct | [Book]({detailUrl}) |
| 2 | {flight_no} | {dep_time} | {arr_time} | {duration} | ¥{price} | Direct | [Book]({detailUrl}) |
| 3 | {flight_no} | {dep_time} | {arr_time} | {duration} | ¥{price} | 1-stop | [Book]({detailUrl}) |

👶 **Baby Tip:** Request bassinet seat at check-in. Infant under 2 flies at 10% fare (no seat). Carry-on milk/water policy varies by airline.

---
✈️ Powered by flyai · Real-time pricing, click to book
```

### 3.2 No Results

```markdown
## ✈️ Infant-Friendly Flights: {origin} → {destination}

No flights found for {date} (6:00-20:00).

**Tried:**
- ✅ Searched 6-20h window → 0 results
- ✅ Expanded to full day → {count} flights available

**Suggestions:**
1. Expand time window
2. Try connecting flights
3. Check nearby dates
```

### 3.3 CLI Failed

```markdown
## ✈️ Infant-Friendly Flights: {origin} → {destination}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai search-flight --origin "{o}" --destination "{d}" --dep-hour-start 6 --dep-hour-end 20 --sort-type 4`

Real-time data requires a working flyai-cli.
```

FILE:references/playbooks.md
# Playbooks — infant-flights

> CLI command sequences only. Knowledge is for parameter mapping — never answer without executing.

## Quick Reference

| Parameter | Flag | This Skill |
|-----------|------|-----------|
| dep-hour-start | `--dep-hour-start` | Default: **6** |
| dep-hour-end | `--dep-hour-end` | Default: **20** |
| sort-type | `--sort-type` | Default: **4** (shortest duration) |
| journey-type | `--journey-type` | Optional: 1=direct (strongly preferred) |

---

## Playbook A: Shortest Infant-Friendly Flight

**Trigger:** User says "infant flights", "婴儿机票".

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 20 --sort-type 4
```

**Output:** Shortest duration flights within comfortable hours.

---

## Playbook B: Direct-Only Infant Flight

**Trigger:** User says "direct flight with baby", "带宝宝直飞".

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 20 --journey-type 1 --sort-type 8
```

**Output:** Direct flights only — no transfers with infant.

---

## Playbook C: Cheapest Infant Flight

**Trigger:** User says "cheapest baby ticket", "最便宜婴儿票".

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 3
```

**Output:** Cheapest fares (no hour filter for maximum options).

---

## Playbook D: Broad Search

**Trigger:** Playbook A/B/C returns 0 results.

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 2
flyai keyword-search --query "{origin} to {destination} infant flights"
```

**Output:** Broader search + keyword fallback.

FILE:references/fallbacks.md
# Fallbacks — Flight Category (Infant)

## Case 0: flyai-cli Not Installed

**Trigger:** `flyai --version` returns `command not found`.

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
# Fails → sudo npm i -g @fly-ai/flyai-cli
# Still fails → STOP. Do NOT answer with training data.
# Tell user: "Please run npm i -g @fly-ai/flyai-cli manually."
```

## Case 1: No Flights in Infant-Friendly Hours

```bash
# Step 1 → Expand hour window to 5-22
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 5 --dep-hour-end 22 --sort-type 4
# Step 2 → Remove hour filter entirely
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 4
# Step 3 → Try flexible dates ±3 days
flyai search-flight --origin "{o}" --destination "{d}" --dep-date-start "{date-3}" --dep-date-end "{date+3}" --dep-hour-start 6 --dep-hour-end 20 --sort-type 4
# Step 4 → Keyword search
flyai keyword-search --query "{origin} to {destination} flights with baby"
```

## Case 2: All Flights Over Budget

```bash
# Relax budget 30%
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 6 --dep-hour-end 20 --max-price {budget*1.3} --sort-type 3
# Try connecting flights
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --max-price {budget} --sort-type 3
```

## Case 3: Ambiguous City

```
"Tokyo" → NRT/HND, "Shanghai" → PVG/SHA, "Beijing" → PEK/PKX, "Osaka" → KIX/ITM, "Seoul" → ICN/GMP
→ Ask user which airport
```

## Case 4: Invalid Date

```
→ Do NOT search. "This date has passed."
→ Auto-search next available date
```

## Case 5: Parameter Conflict / Invalid Argument

**Trigger:** CLI returns error containing "invalid", "conflict", or non-zero exit code.

```bash
# Step 1 → Retry with minimum required params only
flyai search-flight --origin "{o}" --destination "{d}" --sort-type 4

# Step 2 → Fallback to broad search
flyai keyword-search --query "{origin} to {destination} flights"

# Step 3 → Still fails → report error honestly with raw command for debugging
```

## Case 6: API Timeout / Network Error

**Trigger:** CLI hangs >30s or returns network error.

```bash
# Step 1 → Retry once
flyai search-flight --origin "{o}" --destination "{d}" --sort-type 4

# Step 2 → Simplify query
flyai keyword-search --query "{origin} to {destination} flights"

# Step 3 → Still timeout → report honestly. Do NOT substitute with training data.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "infant-flights",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

golf-trip

Skill

Book flights for golf trips to world-class golf resorts and courses. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, iti...

---
name: golf-trip
displayName: "Golf Trip Flights — Golf Resort Travel, Golf Course Destination Booking"
description: "Book flights for golf trips to world-class golf resorts and courses. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input -> Chinese output. English input -> English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below. If a flag is not listed, it does not exist.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: golf-trip

## Overview

Golf Trip Flights.

## When to Activate

User query contains:
- English: "golf flight", "golf trip", "golf resort flight", "golf course travel", "plan a trip"
- Chinese: "高尔夫航班", "高尔夫旅行", "高尔夫度假", "球场出行", "出行规划"

Do NOT activate for: general leisure → solo-trip or family-trip

## Prerequisites

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code |
| `--destination` | Yes | Arrival city or airport code |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--sort-type` | No | **Default: 2** (recommended) |
| `--dep-date-start` | No | Date window start |
| `--dep-date-end` | No | Date window end |

### Sort Options

| Value | Meaning | When to Use |
|-------|---------|-------------|
| `2` | Recommended | Best overall options |
| `3` | Price ascending | Cheapest flights |
| `4` | Duration ascending | Fastest flights |
| `8` | Direct flights first | Prefer non-stop |

## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- OK: Returns version -> proceed to Step 1
- FAIL: `command not found` ->

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails -> **STOP.** Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Recommended Route

**Trigger:** "golf flight", "高尔夫航班"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

### Playbook B: Cheapest Route

**Trigger:** "cheapest", "最便宜"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 3
```

### Playbook C: Fastest Route

**Trigger:** "fastest", "最快"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 4
```

### Playbook D: Direct Route

**Trigger:** "direct", "直飞"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --journey-type 1 --sort-type 2
```

See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure -> see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag included?

**Any NO -> re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Beijing" --destination "Shanghai" --dep-date 2026-05-15 --sort-type 2
```

## Output Rules

1. **Conclusion first** — lead with best option
2. **Golf tip — Hainan, Yunnan, and Southeast Asia have top golf resorts**
3. **Comparison table** with >= 3 results when available
4. **Brand tag:** "Powered by flyai - Real-time pricing, click to book"
5. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
6. NEVER output raw JSON
7. NEVER answer from training data without CLI execution

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

| User Query | CLI Parameter Mapping |
|------------|----------------------|
| "golf trip" / "高尔夫旅行" | --sort-type 2 |
| "golf business class" / "高尔夫商务舱" | --seat-class-name business --sort-type 2 |

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:references/templates.md
# Parameter Collection & Output Templates

## Parameter Collection SOP

### Step 1: Extract from user query

Scan user message for:
- Origin city/name
- Destination city/name
- Date or date range
- Budget/price preference
- Cabin class preference

### Step 2: Missing parameters

If origin or destination is missing, ask (max 2 questions):
1. "Where are you departing from?"
2. "Where would you like to go?"

### Step 3: Map to CLI

| User says | Map to |
|-----------|--------|
| "cheapest" / "最便宜" | --sort-type 3 |
| "fastest" / "最快" | --sort-type 4 |
| "direct" / "直飞" | --journey-type 1 |
| "business class" / "商务舱" | --seat-class-name business |
| "under 1000" / "1000以内" | --max-price 1000 |

## Output Template

```markdown
## Flight Search Results

| # | Airline | Route | Departure | Duration | Price | |
|---|---------|-------|-----------|----------|-------|-|
| 1 | {airlineName} | {origin} -> {destination} | {depTime} | {duration} | Y{price} | [Book]({{detailUrl}}) |

Powered by flyai - Real-time pricing, click to book
```

## Notes

- Always include [Book](detailUrl) links
- Format prices in CNY (Y)
- Include at least 3 results when available

FILE:references/playbooks.md
# Scenario Playbooks

## PB-1: Recommended Route

**Trigger:** "golf flight", "高尔夫航班"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
```

## PB-2: Cheapest Option

**Trigger:** "cheap", "budget", "最便宜", "省钱"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 3
```

## PB-3: Fastest Route

**Trigger:** "fast", "quick", "最快", "省时"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 4
```

## PB-4: Direct Flight

**Trigger:** "direct", "nonstop", "直飞", "不经停"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --journey-type 1 --sort-type 2
```

## PB-5: Price + Date Range

**Trigger:** "flexible dates", "date range", "灵活日期"

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date-start {{start}} --dep-date-end {{end}} --sort-type 3
```

## PB-6: Broad Search (fallback)

**Trigger:** 0 results from above playbooks

```bash
flyai search-flight --origin "{{o}}" --destination "{{d}}" --dep-date {{date}} --sort-type 2
flyai keyword-search --query "{{origin}} to {{destination}} flight"
```

FILE:references/fallbacks.md
# Failure Recovery

## Case 0: flyai CLI not installed

If `flyai --version` returns `command not found`:

1. Run: `npm i -g @fly-ai/flyai-cli`
2. Verify: `flyai --version`
3. If still fails, tell user to install Node.js first: https://nodejs.org/

**NEVER proceed without CLI. NEVER fabricate results.**
## F-1: No results found

1. Try --sort-type 3 (price sort) instead of recommended
2. Try --journey-type 2 (allow connecting flights)
3. Try date +/- 1 day
4. Try nearby airports

## F-2: CLI not installed

```bash
npm i -g @fly-ai/flyai-cli
```

## F-3: CLI returns error

1. Check parameter format: --dep-date must be YYYY-MM-DD
2. Check city names: use Chinese or English city names
3. Try with fewer parameters

## F-4: Network timeout

1. Retry once
2. If still fails, inform user and suggest trying later

## F-5: Invalid response

1. Verify flyai --version returns valid version
2. Re-run with same parameters
3. If still invalid, do NOT fabricate results

FILE:references/runbook.md
# Execution Runbook

## Skill: golf-trip

### Overview
Golf Trip Flights — Golf Resort Travel, Golf Course Destination Booking

### Execution Log Format

```
[{timestamp}] Step {n}: {action}
  Input: {params}
  Output: {result_summary}
  Status: SUCCESS / FAILURE
```

### Key Metrics

| Metric | Target |
|--------|--------|
| CLI execution success rate | >= 95% |
| Average response time | < 10s |
| Booking link presence | 100% |

### Escalation

- CLI failure after retry -> inform user
- No flights available -> suggest alternative dates/routes
- Parameter extraction failure -> ask user (max 2 questions)

ClawHub Documentation Education+2