@univedge/self-study-cli

中文 README

A small, file-based CLI for AI Agents to manage self-study courses, schedules, and homework progress.

Important: This tool is designed for AI Agents (like OpenClaw / PicoClaw), not end-users. Agents call this CLI to persist state, while they themselves handle content generation, IM interactions, and cron scheduling.

Installation

# Run directly with npx
npx @univedge/self-study-cli <command>

# Or install globally
npm install -g @univedge/self-study-cli
self-study-cli <command>

Data Directory

All data is stored as local YAML/Markdown files.

• Default: ~/.self-study/
• Override via CLI: --data-dir /path/to/dir
• Override via env: SELF_STUDY_DATA_DIR=/path/to/dir

CLI --data-dir takes precedence over the environment variable.

File Organization

~/.self-study/
├── config.yaml
├── schedule.yaml          # daily time slots & topic assignments
├── data.yaml              # course state: next-course, homework status
└── courses/
    └── <topic-id>/
        ├── course.yaml    # metadata: id, description, status, streakDays
        └── <date>/
            ├── <HH-MM>.md # lesson content (Agent writes directly)
            └── homework.yaml

Commands

Course Management

# Create a course (idempotent)
self-study-cli course create <topic-id> [--desc "..."]

# List all courses
self-study-cli course list [--status active|waiting-homework-done|finished]

# Show course details
self-study-cli course show <topic-id>

# Update course status
self-study-cli course update <topic-id> --status <status>

# Delete a course
self-study-cli course delete <topic-id> [--force]

Schedule Management

# Set daily time rules (overwrites old schedule slots)
self-study-cli schedule \
  --start-time 09:00 \
  --end-time 17:00 \
  --interval 30 \
  --breaks 12:00-13:30,15:30-16:00

# Show current schedule
self-study-cli schedule show

# Assign a topic to a slot (or null to clear)
self-study-cli schedule set --time 09:00 --topic <topic-id>

# Read-only query at a specific datetime
self-study-cli schedule query --datetime 2026-04-11T09:00:00+08:00

Lesson Planning & Execution

# Prepare an empty lesson slot (returns absolute .md path)
self-study-cli course plan <topic-id> --date 2026-04-11 --time 09:00 [--has-homework]

# Consume a slot (advances next-course, checks homework status)
self-study-cli go --datetime 2026-04-11T09:00:00+08:00

go will output WAITING_HOMEWORK if the course is blocked by pending homework.

Homework & Progress

# Submit homework (Agent collects answers and calls this)
self-study-cli homework submit <topic-id> \
  --date 2026-04-11 \
  --user-answer "q1: D\nq2: true" \
  --comment "Good job"

# Check recent homework status (default last 7 days)
self-study-cli homework status <topic-id> [--last-n 7]

# Show overall progress across all courses
self-study-cli progress

Naming Rules

• Topic ID: must match ^[a-zA-Z_-]+$
  • ✅ economics-theory, TypeScript, go_lang
  • ❌ 经济学, type script, k8s!

Development

This project uses pnpm.

# Install dependencies
pnpm install

# Build to dist/
pnpm run build

# Type check
pnpm run typecheck

# Run integration tests
pnpm test

Tech Stack

• citty — CLI framework
• yaml — YAML parser/stringifier
• tsdown — ESM bundler
• vitest — Testing framework

License

MIT