4.5 KiB
Clip Web Article Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Build a lightweight clip-web-article Skill that saves one visible web article URL as one local Markdown file plus sibling image files.
Architecture: Use OpenCLI as the browser/login/article extraction substrate, then run a small Python normalizer to flatten OpenCLI output into the user's knowledge-vault article-reference shape. Keep deterministic naming, image rewrites, and safety checks in the script; keep platform policy and fallback routing in SKILL.md.
Tech Stack: OpenCLI @jackwener/opencli, Python 3.11 stdlib, unittest, existing scripts/quick_validate.py.
Global Constraints
- Skill source lives under
C:\Users\wangq\Documents\Codex\skills-vault\skills\clip-web-article. - Default output root is
C:\Users\wangq\Documents\Codex\knowledge-vault\sources\clipped-articles\文章参考. - Output article folder contains only Markdown and local image files by default.
- Do not create output logs, metadata JSON, raw HTML archives, screenshots, or platform subfolders by default.
- Do not read, save, or ask the user to paste cookies, localStorage, passwords, session stores, or tokens.
- Preserve existing outputs by creating a non-colliding folder.
- Run tests with
conda run -n skills-vault python -B -m unittest discover -s skills\clip-web-article\tests -v.
Task 1: Deterministic Normalizer
Files:
- Create:
skills/clip-web-article/scripts/clip_web_article.py - Create:
skills/clip-web-article/tests/test_clip_web_article.py - Create:
skills/clip-web-article/fixtures/simple-opencli-output/
Interfaces:
-
Produces:
normalize_opencli_article(opencli_dir: Path, output_root: Path, capture_date: date) -> ClipResult -
Produces:
save_twitter_rows(rows: list[dict], output_root: Path, url: str, capture_date: date) -> ClipResult -
Produces: CLI
python clip_web_article.py <url> --output-root <path> -
Step 1: Write failing unit tests
-
Step 2: Run tests and verify they fail because implementation is missing
-
Step 3: Implement the normalizer and OpenCLI command routing
-
Step 4: Run unit tests and verify they pass
Task 2: Skill Surface
Files:
- Create:
skills/clip-web-article/SKILL.md - Create:
skills/clip-web-article/README.md - Create:
skills/clip-web-article/agents/openai.yaml - Modify:
registry/skills-index.md - Modify:
docs/install-sync.md
Interfaces:
-
Consumes: script CLI from Task 1.
-
Produces: installed agent-facing Skill instructions and registry row.
-
Step 1: Write concise Skill instructions
-
Step 2: Add registry/install documentation
-
Step 3: Validate with
scripts/quick_validate.py
Task 3: Smoke And Install
Files:
- Installed copy target:
C:\Users\wangq\.agents\skills\clip-web-article
Interfaces:
-
Consumes: source Skill directory and install script.
-
Produces: installed runtime Skill.
-
Step 1: Run OpenCLI help checks for required commands
-
Step 2: Run unit tests and skill validation
-
Step 3: Install Skill to
.agents\skills -
Step 4: Attempt real URL smoke tests without saving cookies
Smoke note: after installing the OpenCLI Chrome extension, opencli doctor reported daemon and extension connected. Real URL smoke tests passed for WeChat, Zhihu answer, Zhihu pin, and X/Twitter without manual cookies. Later refinement smoke tests verified batch clipping, custom --output-root, short names, no extra JSON/log/raw files, no Zhihu sibling answers, and no X replies.
Task 4: User Feedback Refinements
Files:
- Modify:
skills/clip-web-article/scripts/clip_web_article.py - Modify:
skills/clip-web-article/tests/test_clip_web_article.py - Modify:
skills/clip-web-article/SKILL.md - Modify:
skills/clip-web-article/README.md
Interfaces:
-
Produces: multi-URL CLI
python clip_web_article.py <url1> <url2> ... --output-root <path>. -
Produces: OpenCLI browser-backed commands with
--keep-tab false. -
Step 1: Route Zhihu answer URLs through
opencli zhihu answer-detail -
Step 2: Save only the target X status row, not replies
-
Step 3: Trim Zhihu pin page chrome and comment UI
-
Step 4: Shorten folder and Markdown file names
-
Step 5: Add batch URL support and custom output-root coverage
-
Step 6: Install and validate source plus installed Skill copies