91 lines
4.5 KiB
Markdown
91 lines
4.5 KiB
Markdown
# 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>`
|
|
|
|
- [x] **Step 1: Write failing unit tests**
|
|
- [x] **Step 2: Run tests and verify they fail because implementation is missing**
|
|
- [x] **Step 3: Implement the normalizer and OpenCLI command routing**
|
|
- [x] **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.
|
|
|
|
- [x] **Step 1: Write concise Skill instructions**
|
|
- [x] **Step 2: Add registry/install documentation**
|
|
- [x] **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.
|
|
|
|
- [x] **Step 1: Run OpenCLI help checks for required commands**
|
|
- [x] **Step 2: Run unit tests and skill validation**
|
|
- [x] **Step 3: Install Skill to `.agents\skills`**
|
|
- [x] **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`.
|
|
|
|
- [x] **Step 1: Route Zhihu answer URLs through `opencli zhihu answer-detail`**
|
|
- [x] **Step 2: Save only the target X status row, not replies**
|
|
- [x] **Step 3: Trim Zhihu pin page chrome and comment UI**
|
|
- [x] **Step 4: Shorten folder and Markdown file names**
|
|
- [x] **Step 5: Add batch URL support and custom output-root coverage**
|
|
- [x] **Step 6: Install and validate source plus installed Skill copies**
|