chore: remove planning/analysis artifacts from repo
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
yusyus
@@ -1,241 +0,0 @@
|
|||||||
# Chinese Translation Implementation - COMPLETE ✅
|
|
||||||
|
|
||||||
> **Date:** 2026-02-16
|
|
||||||
> **Issue:** #260 - Requesting community help for Chinese translations
|
|
||||||
> **Status:** Infrastructure ready, awaiting community review
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## What Was Implemented
|
|
||||||
|
|
||||||
### 1. Directory Structure ✅
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/zh-CN/ # Chinese documentation root
|
|
||||||
├── README.md # Chinese entry point (created)
|
|
||||||
├── ARCHITECTURE.md # (copied from English)
|
|
||||||
├── getting-started/ # 4 files (copied)
|
|
||||||
├── user-guide/ # 6 files (copied)
|
|
||||||
├── reference/ # Reference docs (copied)
|
|
||||||
└── advanced/ # 4 files (copied)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Total:** 30+ files prepared for translation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. Automation Infrastructure ✅
|
|
||||||
|
|
||||||
| File | Purpose |
|
|
||||||
|------|---------|
|
|
||||||
| `.github/workflows/translate-docs.yml` | GitHub Actions - auto-translates on English doc changes |
|
|
||||||
| `scripts/translate_doc.py` | Python script - uses Claude API for translation |
|
|
||||||
| `scripts/check_translation_sync.sh` | Bash script - verifies Chinese docs are in sync |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. Translation Workflow
|
|
||||||
|
|
||||||
```
|
|
||||||
English doc changes
|
|
||||||
↓
|
|
||||||
GitHub Actions detects change
|
|
||||||
↓
|
|
||||||
Auto-translates with Claude API
|
|
||||||
↓
|
|
||||||
Creates PR with Chinese version
|
|
||||||
↓
|
|
||||||
Notifies Issue #260
|
|
||||||
↓
|
|
||||||
Community reviews
|
|
||||||
↓
|
|
||||||
Merges when approved
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4. Community Guidelines Created
|
|
||||||
|
|
||||||
| File | Purpose |
|
|
||||||
|------|---------|
|
|
||||||
| `ISSUE_260_UPDATE.md` | Bilingual contribution guide for Issue #260 |
|
|
||||||
| `docs/zh-CN/README.md` | Chinese documentation entry point |
|
|
||||||
| `DOCUMENTATION_CHINESE_TRANSLATION_PLAN.md` | Detailed implementation plan |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. Translation Standards
|
|
||||||
|
|
||||||
**Header Format:**
|
|
||||||
```markdown
|
|
||||||
> **注意：** 本文档是 [Original.md](Original.md) 的中文翻译。
|
|
||||||
>
|
|
||||||
> - **最后翻译日期：** 2026-02-16
|
|
||||||
> - **英文原文版本：** 3.1.0
|
|
||||||
> - **翻译状态：** ⚠️ 待审阅
|
|
||||||
>
|
|
||||||
> 如果本文档与英文版本有冲突，请以英文版本为准。
|
|
||||||
```
|
|
||||||
|
|
||||||
**Technical Terms:**
|
|
||||||
- Keep in English: CLI, API, JSON, YAML, MCP, URL, HTTP
|
|
||||||
- Translate first occurrence: "技能 (skill)", "工作流 (workflow)"
|
|
||||||
- Keep code examples in English
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps (For Community)
|
|
||||||
|
|
||||||
### To Start Translation Review:
|
|
||||||
|
|
||||||
1. **Update Issue #260** with content from `ISSUE_260_UPDATE.md`
|
|
||||||
2. **Set up ANTHROPIC_API_KEY** in GitHub Secrets (for auto-translation)
|
|
||||||
3. **Community volunteers** review and improve translations
|
|
||||||
4. **Merge improvements** via PRs
|
|
||||||
|
|
||||||
### Manual Translation (Without API):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Edit Chinese files directly
|
|
||||||
nano docs/zh-CN/getting-started/02-quick-start.md
|
|
||||||
|
|
||||||
# 2. Update translation header
|
|
||||||
# Change: 翻译状态：⚠️ 待审阅
|
|
||||||
# To: 翻译状态：✅ 已审阅
|
|
||||||
|
|
||||||
# 3. Submit PR
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Files Ready for Review
|
|
||||||
|
|
||||||
### Priority 0 (Entry Points)
|
|
||||||
|
|
||||||
| File | Status |
|
|
||||||
|------|--------|
|
|
||||||
| `docs/zh-CN/README.md` | ⚠️ Needs translation review |
|
|
||||||
| `docs/zh-CN/getting-started/02-quick-start.md` | ⚠️ Needs translation review |
|
|
||||||
|
|
||||||
### Priority 1 (Core Guides)
|
|
||||||
|
|
||||||
| File | Status |
|
|
||||||
|------|--------|
|
|
||||||
| `docs/zh-CN/getting-started/01-installation.md` | ⚠️ Needs translation review |
|
|
||||||
| `docs/zh-CN/getting-started/03-your-first-skill.md` | ⚠️ Needs translation review |
|
|
||||||
| `docs/zh-CN/getting-started/04-next-steps.md` | ⚠️ Needs translation review |
|
|
||||||
| `docs/zh-CN/user-guide/06-troubleshooting.md` | ⚠️ Needs translation review |
|
|
||||||
|
|
||||||
### Priority 2-3 (Complete Documentation)
|
|
||||||
|
|
||||||
All 30+ files are ready and waiting for community review.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## How to Use
|
|
||||||
|
|
||||||
### For Chinese Users:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 访问中文文档
|
|
||||||
# Visit Chinese docs:
|
|
||||||
https://github.com/yusufkaraaslan/Skill_Seekers/tree/main/docs/zh-CN
|
|
||||||
|
|
||||||
# 从中文 README 开始
|
|
||||||
# Start from Chinese README:
|
|
||||||
docs/zh-CN/README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### For Contributors:
|
|
||||||
|
|
||||||
1. **Review auto-translations** - Check PRs created by GitHub Actions
|
|
||||||
2. **Suggest improvements** - Comment on PRs or create new PRs
|
|
||||||
3. **Translate manually** - Edit files directly for better quality
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## GitHub Actions Workflow
|
|
||||||
|
|
||||||
### Trigger Conditions:
|
|
||||||
|
|
||||||
- Push to `main` or `development` branch
|
|
||||||
- Changes to `docs/**/*.md` (excluding `docs/zh-CN/` and `docs/archive/`)
|
|
||||||
- Manual trigger via `workflow_dispatch`
|
|
||||||
|
|
||||||
### Required Secrets:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
secrets.ANTHROPIC_API_KEY # For Claude API translation
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Success Metrics
|
|
||||||
|
|
||||||
| Metric | Target | Current |
|
|
||||||
|--------|--------|---------|
|
|
||||||
| Directory structure | ✅ | Done |
|
|
||||||
| Automation scripts | ✅ | Done |
|
|
||||||
| GitHub Actions | ✅ | Done |
|
|
||||||
| Entry point (README) | ✅ | Done |
|
|
||||||
| Files with headers | ✅ | Ready |
|
|
||||||
| Community guidelines | ✅ | Done |
|
|
||||||
| Actual translations | ⚠️ | Needs community/API |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Start for Maintainers
|
|
||||||
|
|
||||||
### 1. Update Issue #260
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Copy content from ISSUE_260_UPDATE.md
|
|
||||||
cat ISSUE_260_UPDATE.md | pbcopy
|
|
||||||
# Paste into Issue #260
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Set up API Key
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# GitHub Settings → Secrets and variables → Actions
|
|
||||||
# Add: ANTHROPIC_API_KEY=sk-ant-...
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Test Translation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Make a small change to English doc
|
|
||||||
echo "Test" >> docs/getting-started/02-quick-start.md
|
|
||||||
|
|
||||||
# Push and see if GitHub Actions triggers
|
|
||||||
git push
|
|
||||||
|
|
||||||
# Check Actions tab for translation workflow
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Announce to Community
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
🌐 中文文档翻译项目启动！
|
|
||||||
Chinese Documentation Translation Project Launched!
|
|
||||||
|
|
||||||
我们已经准备好了所有基础设施，现在需要社区志愿者帮忙审阅和改进中文翻译。
|
|
||||||
All infrastructure is ready. Now we need community volunteers to review
|
|
||||||
and improve Chinese translations.
|
|
||||||
|
|
||||||
详情见 #260 / See #260 for details.
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
✅ **Infrastructure:** Complete - automation, scripts, structure ready
|
|
||||||
✅ **Documentation:** Complete - guides, standards, issue templates ready
|
|
||||||
⚠️ **Translations:** Pending - awaiting community review or API key setup
|
|
||||||
|
|
||||||
The Chinese translation project is **ready for community participation!**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Implementation completed. Awaiting community contributions.* 🌐🇨🇳
|
|
||||||
@@ -1,229 +0,0 @@
|
|||||||
# Create Command vs Individual Scrapers - Coverage Analysis
|
|
||||||
|
|
||||||
> **Analysis Date:** 2026-02-16
|
|
||||||
> **Question:** Can `create` command replace all individual scrapers?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ VERDICT: YES - Create Command Has Full Coverage
|
|
||||||
|
|
||||||
After comprehensive analysis, **`skill-seekers create` CAN replace all individual scrapers** with equivalent functionality.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Source Type Coverage
|
|
||||||
|
|
||||||
| Source Type | Individual Command | Create Command | Status |
|
|
||||||
|-------------|-------------------|----------------|--------|
|
|
||||||
| **Documentation** | `scrape` | `create https://...` | ✅ Full parity |
|
|
||||||
| **GitHub** | `github` | `create owner/repo` | ✅ Full parity |
|
|
||||||
| **Local Code** | `analyze` | `create ./path` | ✅ Full parity |
|
|
||||||
| **PDF** | `pdf` | `create file.pdf` | ✅ Full parity |
|
|
||||||
| **Multi-Source** | `unified` | `create config.json` | ✅ Full parity |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Feature Parity by Source Type
|
|
||||||
|
|
||||||
### 1. Documentation Scraping (`scrape` → `create`)
|
|
||||||
|
|
||||||
| Feature | scrape | create | Status |
|
|
||||||
|---------|--------|--------|--------|
|
|
||||||
| URL scraping | ✅ | ✅ | Full |
|
|
||||||
| Config file (--config) | ✅ | ✅ | Full |
|
|
||||||
| Max pages (--max-pages) | ✅ | ✅ | Full |
|
|
||||||
| Skip scrape (--skip-scrape) | ✅ | ✅ | Full |
|
|
||||||
| Resume (--resume) | ✅ | ✅ | Full |
|
|
||||||
| Fresh start (--fresh) | ✅ | ✅ | Full |
|
|
||||||
| Rate limit (-r) | ✅ | ✅ | Full |
|
|
||||||
| Workers (-w) | ✅ | ✅ | Full |
|
|
||||||
| Async mode (--async) | ✅ | ✅ | Full |
|
|
||||||
| Enhancement workflows | ✅ | ✅ | Full |
|
|
||||||
| RAG chunking | ✅ | ✅ | Full |
|
|
||||||
|
|
||||||
**Gap Analysis:**
|
|
||||||
- `scrape` has `--interactive` mode (interactive config builder)
|
|
||||||
- `create` does NOT expose `--interactive` directly
|
|
||||||
- **Workaround:** Users can use `--config` with pre-built config
|
|
||||||
|
|
||||||
**Verdict:** 95% parity - only missing interactive wizard
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. GitHub Scraping (`github` → `create`)
|
|
||||||
|
|
||||||
| Feature | github | create | Status |
|
|
||||||
|---------|--------|--------|--------|
|
|
||||||
| Repo scraping (--repo) | ✅ | ✅ (auto) | Full |
|
|
||||||
| GitHub token (--token) | ✅ | ✅ | Full |
|
|
||||||
| Profile (--profile) | ✅ | ✅ | Full |
|
|
||||||
| Non-interactive (--non-interactive) | ✅ | ✅ | Full |
|
|
||||||
| Skip issues (--no-issues) | ✅ | ✅ | Full |
|
|
||||||
| Skip changelog (--no-changelog) | ✅ | ✅ | Full |
|
|
||||||
| Skip releases (--no-releases) | ✅ | ✅ | Full |
|
|
||||||
| Max issues (--max-issues) | ✅ | ✅ | Full |
|
|
||||||
| Scrape only (--scrape-only) | ✅ | ✅ | Full |
|
|
||||||
| Local repo path (--local-repo-path) | ✅ | ✅ | Full |
|
|
||||||
| Enhancement workflows | ✅ | ✅ | Full |
|
|
||||||
|
|
||||||
**Gap Analysis:**
|
|
||||||
- `github` has `--config` to load from JSON file
|
|
||||||
- `create` also has `--config` for additional settings
|
|
||||||
- `github` shows repo in help; `create` auto-detects
|
|
||||||
|
|
||||||
**Verdict:** 100% parity
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. Local Code Analysis (`analyze` → `create`)
|
|
||||||
|
|
||||||
| Feature | analyze | create | Status |
|
|
||||||
|---------|---------|--------|--------|
|
|
||||||
| Directory analysis (--directory) | ✅ | ✅ (auto) | Full |
|
|
||||||
| Preset (--preset) | ✅ | ✅ | Full |
|
|
||||||
| Languages (--languages) | ✅ | ✅ | Full |
|
|
||||||
| File patterns (--file-patterns) | ✅ | ✅ | Full |
|
|
||||||
| Skip patterns (--skip-patterns) | ✅ | ✅ | Full |
|
|
||||||
| Skip test examples (--skip-test-examples) | ✅ | ✅ | Full |
|
|
||||||
| Skip how-to guides (--skip-how-to-guides) | ✅ | ✅ | Full |
|
|
||||||
| Skip config (--skip-config) | ✅ | ✅ | Full |
|
|
||||||
| Skip docs (--skip-docs) | ✅ | ✅ | Full |
|
|
||||||
| Enhancement workflows | ✅ | ✅ | Full |
|
|
||||||
|
|
||||||
**Gap Analysis:**
|
|
||||||
- `analyze` has `--preset-list` (show available presets)
|
|
||||||
- `create` does NOT have `--preset-list`
|
|
||||||
- `analyze` has deprecated flags (--quick, --comprehensive, --depth)
|
|
||||||
- `create` uses clean `--preset` approach
|
|
||||||
|
|
||||||
**Verdict:** 95% parity - only missing preset list
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4. PDF Extraction (`pdf` → `create`)
|
|
||||||
|
|
||||||
| Feature | pdf | create | Status |
|
|
||||||
|---------|-----|--------|--------|
|
|
||||||
| PDF file (--pdf) | ✅ | ✅ (auto) | Full |
|
|
||||||
| OCR (--ocr) | ✅ | ✅ | Full |
|
|
||||||
| Page range (--pages) | ✅ | ✅ | Full |
|
|
||||||
| Enhancement workflows | ✅ | ✅ | Full |
|
|
||||||
|
|
||||||
**Verdict:** 100% parity
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. Multi-Source (`unified` → `create`)
|
|
||||||
|
|
||||||
| Feature | unified | create | Status |
|
|
||||||
|---------|---------|--------|--------|
|
|
||||||
| Config file (--config) | ✅ | ✅ | Full |
|
|
||||||
| Merge mode (--merge-mode) | ✅ | ✅ | Full |
|
|
||||||
| Fresh start (--fresh) | ✅ | ✅ | Full |
|
|
||||||
| Dry run (--dry-run) | ✅ | ✅ | Full |
|
|
||||||
|
|
||||||
**Verdict:** 100% parity
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Arguments NOT in Create Command (Intentional)
|
|
||||||
|
|
||||||
These are intentionally excluded or handled differently:
|
|
||||||
|
|
||||||
| Argument | Reason |
|
|
||||||
|----------|--------|
|
|
||||||
| `--interactive` (scrape) | Use `--config` instead |
|
|
||||||
| `--preset-list` (analyze) | Use `workflows list` instead |
|
|
||||||
| `--url` (scrape) | Auto-detected from source |
|
|
||||||
| `--repo` (github) | Auto-detected from source |
|
|
||||||
| `--directory` (analyze) | Auto-detected from source |
|
|
||||||
| `--quick/--comprehensive/--depth` | Deprecated, use `--preset` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Create Command Advantages
|
|
||||||
|
|
||||||
| Feature | Create | Individual |
|
|
||||||
|---------|--------|------------|
|
|
||||||
| **Auto-detection** | ✅ Source type auto-detected | ❌ Must specify command |
|
|
||||||
| **Unified interface** | ✅ One command for all | ❌ Different commands |
|
|
||||||
| **Progressive help** | ✅ `--help-web`, `--help-github`, etc. | ❌ Single help output |
|
|
||||||
| **Argument validation** | ✅ Warns about incompatible args | ❌ Silent failures |
|
|
||||||
| **Future-proof** | ✅ New sources automatic | ❌ Need new commands |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Minor Gaps (Non-Critical)
|
|
||||||
|
|
||||||
### 1. Interactive Config Builder
|
|
||||||
```bash
|
|
||||||
# Individual scraper only
|
|
||||||
skill-seekers scrape --interactive
|
|
||||||
|
|
||||||
# Create workaround
|
|
||||||
skill-seekers create https://example.com/ --config my-config.json
|
|
||||||
# (Build config separately or use defaults)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Preset List
|
|
||||||
```bash
|
|
||||||
# Individual scraper only
|
|
||||||
skill-seekers analyze --preset-list
|
|
||||||
|
|
||||||
# Create workaround
|
|
||||||
skill-seekers workflows list
|
|
||||||
# (Shows workflow presets, similar concept)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Migration Path
|
|
||||||
|
|
||||||
Users can migrate from individual commands to `create`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Before
|
|
||||||
skill-seekers scrape --config configs/react.json
|
|
||||||
skill-seekers github --repo facebook/react --name react
|
|
||||||
skill-seekers analyze --directory ./my-project --preset comprehensive
|
|
||||||
skill-seekers pdf --pdf manual.pdf --name docs
|
|
||||||
|
|
||||||
# After (equivalent)
|
|
||||||
skill-seekers create --config configs/react.json
|
|
||||||
skill-seekers create facebook/react --name react
|
|
||||||
skill-seekers create ./my-project --preset comprehensive
|
|
||||||
skill-seekers create manual.pdf --name docs
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Recommendation
|
|
||||||
|
|
||||||
**You are correct** - there is NO critical gap with the `create` command.
|
|
||||||
|
|
||||||
### What works:
|
|
||||||
- ✅ All 5 source types covered
|
|
||||||
- ✅ All major features supported
|
|
||||||
- ✅ Enhancement workflows work
|
|
||||||
- ✅ RAG chunking works
|
|
||||||
- ✅ All platform packaging works
|
|
||||||
|
|
||||||
### What's missing (minor):
|
|
||||||
- Interactive config builder (can use --config instead)
|
|
||||||
- Preset list (can use `workflows list` instead)
|
|
||||||
|
|
||||||
### Verdict:
|
|
||||||
**`create` command can fully replace individual scrapers.** The minor gaps are UX conveniences, not functional limitations.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Suggested Actions
|
|
||||||
|
|
||||||
1. **Promote `create` as primary command** in documentation
|
|
||||||
2. **Deprecate individual commands** slowly (add warnings)
|
|
||||||
3. **Add `--interactive` to create** if needed for parity
|
|
||||||
4. **Keep individual commands** for backward compatibility
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Analysis confirms: `create` command has no critical gaps.*
|
|
||||||
@@ -1,458 +0,0 @@
|
|||||||
# Chinese Translation Plan - Skill Seekers Documentation
|
|
||||||
|
|
||||||
> **Issue Reference:** #260 - Requesting community help for translations
|
|
||||||
> **Strategy:** Automated + Community Review
|
|
||||||
> **Structure:** Option 1 - Parallel Structure (`docs/zh-CN/`)
|
|
||||||
> **Scope:** All Documentation
|
|
||||||
> **Sync Policy:** Every release must sync Chinese docs
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
Complete Chinese translation of all Skill Seekers documentation using automated translation with community review.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Directory Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/
|
|
||||||
├── README.md # English (source of truth)
|
|
||||||
├── ARCHITECTURE.md
|
|
||||||
├── getting-started/
|
|
||||||
├── user-guide/
|
|
||||||
├── reference/
|
|
||||||
├── advanced/
|
|
||||||
│
|
|
||||||
└── zh-CN/ # Chinese translations
|
|
||||||
├── README.md # Chinese entry point
|
|
||||||
├── ARCHITECTURE.md
|
|
||||||
├── getting-started/
|
|
||||||
│ ├── 01-installation.md
|
|
||||||
│ ├── 02-quick-start.md
|
|
||||||
│ ├── 03-your-first-skill.md
|
|
||||||
│ └── 04-next-steps.md
|
|
||||||
├── user-guide/
|
|
||||||
│ ├── 01-core-concepts.md
|
|
||||||
│ ├── 02-scraping.md
|
|
||||||
│ ├── 03-enhancement.md
|
|
||||||
│ ├── 04-packaging.md
|
|
||||||
│ ├── 05-workflows.md
|
|
||||||
│ └── 06-troubleshooting.md
|
|
||||||
├── reference/
|
|
||||||
│ ├── CLI_REFERENCE.md
|
|
||||||
│ ├── MCP_REFERENCE.md
|
|
||||||
│ ├── CONFIG_FORMAT.md
|
|
||||||
│ └── ENVIRONMENT_VARIABLES.md
|
|
||||||
└── advanced/
|
|
||||||
├── mcp-server.md
|
|
||||||
├── mcp-tools.md
|
|
||||||
├── custom-workflows.md
|
|
||||||
└── multi-source.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**Total:** 18 files to translate
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Translation Workflow
|
|
||||||
|
|
||||||
### Step 1: Automated Translation (CI/CD)
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# .github/workflows/translate-docs.yml
|
|
||||||
name: Translate Documentation
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
paths:
|
|
||||||
- 'docs/**/*.md'
|
|
||||||
- '!docs/zh-CN/**'
|
|
||||||
workflow_dispatch:
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
translate:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v3
|
|
||||||
|
|
||||||
- name: Detect changed files
|
|
||||||
id: changed
|
|
||||||
run: |
|
|
||||||
# Find changed English docs
|
|
||||||
CHANGED=$(git diff --name-only HEAD~1 HEAD | grep "^docs/" | grep -v "^docs/zh-CN/" | grep "\.md$")
|
|
||||||
echo "files=$CHANGED" >> $GITHUB_OUTPUT
|
|
||||||
|
|
||||||
- name: Translate to Chinese
|
|
||||||
if: steps.changed.outputs.files != ''
|
|
||||||
run: |
|
|
||||||
for file in ${{ steps.changed.outputs.files }}; do
|
|
||||||
# Use LLM API for translation
|
|
||||||
python scripts/translate_doc.py "$file" --target-lang zh-CN
|
|
||||||
done
|
|
||||||
|
|
||||||
- name: Create PR
|
|
||||||
uses: peter-evans/create-pull-request@v5
|
|
||||||
with:
|
|
||||||
title: "[Auto] Chinese Translation Update"
|
|
||||||
body: |
|
|
||||||
Automated translation of changed documentation.
|
|
||||||
|
|
||||||
**Needs Review:** Community review required before merge.
|
|
||||||
|
|
||||||
Reference: #260
|
|
||||||
branch: auto-translate-zh-cn
|
|
||||||
labels: translation, zh-CN, needs-review
|
|
||||||
```
|
|
||||||
|
|
||||||
### Step 2: Community Review (via Issue #260)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Translation Review Needed
|
|
||||||
|
|
||||||
The following Chinese translations need community review:
|
|
||||||
|
|
||||||
| File | Auto-Translated | Reviewer | Status |
|
|
||||||
|------|-----------------|----------|--------|
|
|
||||||
| docs/zh-CN/getting-started/02-quick-start.md | @github-actions | @reviewer1 | 🔍 Pending |
|
|
||||||
| docs/zh-CN/reference/CLI_REFERENCE.md | @github-actions | @reviewer2 | 🔍 Pending |
|
|
||||||
|
|
||||||
**How to Review:**
|
|
||||||
1. Check out the PR branch
|
|
||||||
2. Read the Chinese translation
|
|
||||||
3. Comment with suggested changes
|
|
||||||
4. Approve when satisfied
|
|
||||||
|
|
||||||
**Translation Standards:**
|
|
||||||
- Keep technical terms in English (CLI, API, JSON)
|
|
||||||
- Use Simplified Chinese (简体中文)
|
|
||||||
- Maintain code examples in English
|
|
||||||
- Preserve all links and formatting
|
|
||||||
```
|
|
||||||
|
|
||||||
### Step 3: Sync Check on Release
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
# scripts/check_translation_sync.sh
|
|
||||||
|
|
||||||
echo "Checking translation sync..."
|
|
||||||
|
|
||||||
for en_file in docs/**/*.md; do
|
|
||||||
zh_file="${en_file/docs/docs\/zh-CN}"
|
|
||||||
|
|
||||||
if [ ! -f "$zh_file" ]; then
|
|
||||||
echo "❌ Missing: $zh_file"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
en_date=$(git log -1 --format=%ct "$en_file")
|
|
||||||
zh_date=$(git log -1 --format=%ct "$zh_file")
|
|
||||||
|
|
||||||
if [ $en_date -gt $zh_date ]; then
|
|
||||||
echo "⚠️ Out of sync: $zh_file (EN updated more recently)"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
|
|
||||||
echo "✅ All translations in sync"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Translation Standards
|
|
||||||
|
|
||||||
### Header Format
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
<!-- docs/zh-CN/getting-started/02-quick-start.md -->
|
|
||||||
|
|
||||||
> **注意：** 本文档是 [Quick Start Guide](../getting-started/02-quick-start.md) 的中文翻译。
|
|
||||||
>
|
|
||||||
> - **最后翻译日期：** 2026-02-16
|
|
||||||
> - **英文原文版本：** 3.1.0
|
|
||||||
> - **翻译状态：** ✅ 已审阅 / ⚠️ 待审阅 / 🔴 需更新
|
|
||||||
>
|
|
||||||
> 如果本文档与英文版本有冲突，请以英文版本为准。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# 快速入门指南
|
|
||||||
|
|
||||||
> **Skill Seekers v3.1.0**
|
|
||||||
> **3 个命令创建您的第一个技能**
|
|
||||||
```
|
|
||||||
|
|
||||||
### Technical Terms
|
|
||||||
|
|
||||||
Keep these in English:
|
|
||||||
|
|
||||||
| English | Chinese | Keep English? |
|
|
||||||
|---------|---------|---------------|
|
|
||||||
| CLI | 命令行界面 | ✅ Yes (use "CLI") |
|
|
||||||
| API | 应用程序接口 | ✅ Yes (use "API") |
|
|
||||||
| JSON | - | ✅ Yes |
|
|
||||||
| YAML | - | ✅ Yes |
|
|
||||||
| MCP | - | ✅ Yes |
|
|
||||||
| skill | 技能 | ⚠️ Use "技能 (skill)" first time |
|
|
||||||
| scraper | 抓取器 | ⚠️ Use "抓取器 (scraper)" first time |
|
|
||||||
| workflow | 工作流 | ⚠️ Use "工作流 (workflow)" first time |
|
|
||||||
|
|
||||||
### Code Examples
|
|
||||||
|
|
||||||
Keep code examples in English (they're the same):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Chinese doc still shows:
|
|
||||||
pip install skill-seekers
|
|
||||||
skill-seekers create https://docs.django.com/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Links
|
|
||||||
|
|
||||||
Update links to point to Chinese versions:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
<!-- English -->
|
|
||||||
See [Installation Guide](01-installation.md)
|
|
||||||
|
|
||||||
<!-- Chinese -->
|
|
||||||
参见 [安装指南](01-installation.md)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Implementation Phases
|
|
||||||
|
|
||||||
### Phase 1: Setup (1-2 hours)
|
|
||||||
|
|
||||||
- [ ] Create `docs/zh-CN/` directory structure
|
|
||||||
- [ ] Create translation header template
|
|
||||||
- [ ] Set up GitHub Actions workflow
|
|
||||||
- [ ] Create `scripts/translate_doc.py`
|
|
||||||
- [ ] Update issue #260 with contribution guidelines
|
|
||||||
|
|
||||||
### Phase 2: Initial Translation (Automated)
|
|
||||||
|
|
||||||
- [ ] Run translation script on all 18 files
|
|
||||||
- [ ] Create initial PR with all translations
|
|
||||||
- [ ] Tag community reviewers in issue #260
|
|
||||||
|
|
||||||
### Phase 3: Community Review (Ongoing)
|
|
||||||
|
|
||||||
- [ ] Review getting-started/ docs (highest priority)
|
|
||||||
- [ ] Review user-guide/ docs
|
|
||||||
- [ ] Review reference/ docs
|
|
||||||
- [ ] Review advanced/ docs
|
|
||||||
|
|
||||||
### Phase 4: Maintenance (Continuous)
|
|
||||||
|
|
||||||
- [ ] Automated translation on English doc changes
|
|
||||||
- [ ] PR creation for review
|
|
||||||
- [ ] Pre-release sync check
|
|
||||||
- [ ] Monthly review of outdated translations
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## File Priority & Review Assignment
|
|
||||||
|
|
||||||
| Priority | File | Complexity | Reviewers Needed |
|
|
||||||
|----------|------|------------|------------------|
|
|
||||||
| P0 | `docs/zh-CN/README.md` | Low | 2 |
|
|
||||||
| P0 | `docs/zh-CN/getting-started/02-quick-start.md` | Low | 2 |
|
|
||||||
| P1 | `docs/zh-CN/getting-started/01-installation.md` | Low | 1 |
|
|
||||||
| P1 | `docs/zh-CN/getting-started/03-your-first-skill.md` | Medium | 2 |
|
|
||||||
| P1 | `docs/zh-CN/user-guide/06-troubleshooting.md` | Medium | 2 |
|
|
||||||
| P2 | `docs/zh-CN/user-guide/01-core-concepts.md` | Medium | 1 |
|
|
||||||
| P2 | `docs/zh-CN/user-guide/02-scraping.md` | High | 2 |
|
|
||||||
| P2 | `docs/zh-CN/user-guide/03-enhancement.md` | High | 2 |
|
|
||||||
| P2 | `docs/zh-CN/user-guide/04-packaging.md` | High | 2 |
|
|
||||||
| P2 | `docs/zh-CN/user-guide/05-workflows.md` | High | 2 |
|
|
||||||
| P3 | `docs/zh-CN/reference/CLI_REFERENCE.md` | High | 2 |
|
|
||||||
| P3 | `docs/zh-CN/reference/MCP_REFERENCE.md` | High | 2 |
|
|
||||||
| P3 | `docs/zh-CN/reference/CONFIG_FORMAT.md` | Medium | 1 |
|
|
||||||
| P3 | `docs/zh-CN/reference/ENVIRONMENT_VARIABLES.md` | Low | 1 |
|
|
||||||
| P3 | `docs/zh-CN/advanced/*.md` (4 files) | High | 1 each |
|
|
||||||
|
|
||||||
**Total:** 18 files, ~24 reviewer spots
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Issue #260 Update Template
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## 🇨🇳 中文文档翻译 - 招募社区志愿者
|
|
||||||
|
|
||||||
### 项目介绍
|
|
||||||
我们正在将 Skill Seekers 文档翻译成简体中文，需要社区志愿者参与审阅！
|
|
||||||
|
|
||||||
### 如何参与
|
|
||||||
|
|
||||||
#### 1. 审阅翻译（推荐）
|
|
||||||
- 查看自动创建的翻译 PR
|
|
||||||
- 阅读中文文档，提出改进建议
|
|
||||||
- 确认技术术语翻译准确
|
|
||||||
|
|
||||||
#### 2. 直接翻译
|
|
||||||
- 认领下方列表中的文件
|
|
||||||
- 基于英文原文进行翻译
|
|
||||||
- 遵循翻译标准（见下方）
|
|
||||||
|
|
||||||
### 待审阅文件
|
|
||||||
|
|
||||||
| 文件 | 自动翻译 | 状态 | 认领人 |
|
|
||||||
|------|----------|------|--------|
|
|
||||||
| getting-started/02-quick-start.md | ✅ | 🔍 待审阅 | - |
|
|
||||||
| getting-started/01-installation.md | ✅ | 🔍 待审阅 | - |
|
|
||||||
| ... | ... | ... | ... |
|
|
||||||
|
|
||||||
### 翻译标准
|
|
||||||
|
|
||||||
1. **技术术语**：CLI、API、JSON 等保持英文
|
|
||||||
2. **代码示例**：保持原文（英文）
|
|
||||||
3. **链接**：指向中文版本
|
|
||||||
4. **格式**：保留所有 Markdown 格式
|
|
||||||
|
|
||||||
### 奖励
|
|
||||||
- 贡献者将在 README 中致谢
|
|
||||||
- 优先获得新版本测试权限
|
|
||||||
- 社区贡献徽章 🏅
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🇨🇳 Chinese Documentation Translation - Call for Volunteers
|
|
||||||
|
|
||||||
### Introduction
|
|
||||||
We're translating Skill Seekers docs to Simplified Chinese and need community reviewers!
|
|
||||||
|
|
||||||
### How to Participate
|
|
||||||
|
|
||||||
#### 1. Review Translations (Recommended)
|
|
||||||
- Check auto-generated translation PRs
|
|
||||||
- Read Chinese docs, suggest improvements
|
|
||||||
- Verify technical terms are accurate
|
|
||||||
|
|
||||||
#### 2. Direct Translation
|
|
||||||
- Claim a file from the list below
|
|
||||||
- Translate from English original
|
|
||||||
- Follow translation standards (see below)
|
|
||||||
|
|
||||||
### Files Pending Review
|
|
||||||
|
|
||||||
| File | Auto-Translated | Status | Claimed By |
|
|
||||||
|------|-----------------|--------|------------|
|
|
||||||
| getting-started/02-quick-start.md | ✅ | 🔍 Pending | - |
|
|
||||||
| getting-started/01-installation.md | ✅ | 🔍 Pending | - |
|
|
||||||
| ... | ... | ... | ... |
|
|
||||||
|
|
||||||
### Translation Standards
|
|
||||||
|
|
||||||
1. **Technical Terms**: Keep CLI, API, JSON in English
|
|
||||||
2. **Code Examples**: Keep original (English)
|
|
||||||
3. **Links**: Point to Chinese versions
|
|
||||||
4. **Format**: Preserve all Markdown formatting
|
|
||||||
|
|
||||||
### Rewards
|
|
||||||
- Contributors acknowledged in README
|
|
||||||
- Early access to new versions
|
|
||||||
- Community contributor badge 🏅
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Pre-Release Checklist
|
|
||||||
|
|
||||||
Before each release:
|
|
||||||
|
|
||||||
- [ ] Run `scripts/check_translation_sync.sh`
|
|
||||||
- [ ] Ensure all Chinese docs have "翻译状态：✅ 已审阅"
|
|
||||||
- [ ] Update version numbers in Chinese headers
|
|
||||||
- [ ] Update "最后翻译日期" in all Chinese docs
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Tools & Scripts
|
|
||||||
|
|
||||||
### `scripts/translate_doc.py`
|
|
||||||
|
|
||||||
```python
|
|
||||||
#!/usr/bin/env python3
|
|
||||||
"""
|
|
||||||
Translate documentation using LLM API.
|
|
||||||
Usage: python scripts/translate_doc.py <file> --target-lang zh-CN
|
|
||||||
"""
|
|
||||||
|
|
||||||
import argparse
|
|
||||||
import os
|
|
||||||
from pathlib import Path
|
|
||||||
|
|
||||||
|
|
||||||
def translate_file(input_path: str, target_lang: str = "zh-CN"):
|
|
||||||
"""Translate a documentation file."""
|
|
||||||
input_file = Path(input_path)
|
|
||||||
|
|
||||||
# Read English content
|
|
||||||
with open(input_file, 'r', encoding='utf-8') as f:
|
|
||||||
content = f.read()
|
|
||||||
|
|
||||||
# Determine output path
|
|
||||||
relative_path = input_file.relative_to("docs")
|
|
||||||
output_file = Path("docs") / target_lang / relative_path
|
|
||||||
output_file.parent.mkdir(parents=True, exist_ok=True)
|
|
||||||
|
|
||||||
# TODO: Call LLM API for translation
|
|
||||||
# For now, create placeholder with header
|
|
||||||
header = f"""> **注意：** 本文档是 [{input_file.name}]({input_file.name}) 的中文翻译。
|
|
||||||
>
|
|
||||||
> - **最后翻译日期：** 2026-02-16
|
|
||||||
> - **英文原文版本：** 3.1.0
|
|
||||||
> - **翻译状态：** ⚠️ 待审阅
|
|
||||||
>
|
|
||||||
> 如果本文档与英文版本有冲突，请以英文版本为准。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
"""
|
|
||||||
|
|
||||||
with open(output_file, 'w', encoding='utf-8') as f:
|
|
||||||
f.write(header)
|
|
||||||
f.write(content) # Placeholder: should be translated
|
|
||||||
|
|
||||||
print(f"✅ Created: {output_file}")
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
parser = argparse.ArgumentParser()
|
|
||||||
parser.add_argument("file", help="File to translate")
|
|
||||||
parser.add_argument("--target-lang", default="zh-CN", help="Target language")
|
|
||||||
args = parser.parse_args()
|
|
||||||
|
|
||||||
translate_file(args.file, args.target_lang)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Success Metrics
|
|
||||||
|
|
||||||
| Metric | Target |
|
|
||||||
|--------|--------|
|
|
||||||
| Files Translated | 18/18 (100%) |
|
|
||||||
| Reviewed by Community | 18/18 (100%) |
|
|
||||||
| Sync Delay | < 1 week after English update |
|
|
||||||
| Translation Accuracy | > 95% (community verified) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Timeline
|
|
||||||
|
|
||||||
| Phase | Duration | Deliverable |
|
|
||||||
|-------|----------|-------------|
|
|
||||||
| Setup | 1-2 hours | Directory structure, CI/CD |
|
|
||||||
| Initial Translation | 1 day | All 18 files translated |
|
|
||||||
| Community Review | 2-4 weeks | All files reviewed |
|
|
||||||
| Maintenance | Ongoing | Continuous sync |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Ready to implement. Review this plan and confirm to proceed.*
|
|
||||||
@@ -1,245 +0,0 @@
|
|||||||
# Documentation Overhaul - COMPLETE ✅
|
|
||||||
|
|
||||||
> **Issue:** #286 - Documentation gaps and outdated information
|
|
||||||
> **Completed:** 2026-02-16
|
|
||||||
> **Status:** All phases complete
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
Complete documentation rewrite eliminating:
|
|
||||||
- ❌ Phantom commands (`merge-sources`, `split-config`, etc.)
|
|
||||||
- ❌ Old CLI patterns (`python3 cli/X.py`)
|
|
||||||
- ❌ Scattered 83 files with no structure
|
|
||||||
- ❌ Broken quick start guide
|
|
||||||
|
|
||||||
Replaced with:
|
|
||||||
- ✅ Single source of truth CLI reference (20 commands)
|
|
||||||
- ✅ Working 3-command quick start
|
|
||||||
- ✅ Clear 4-category hierarchy
|
|
||||||
- ✅ Comprehensive troubleshooting
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 1: Foundation ✅
|
|
||||||
|
|
||||||
### Reference Documentation (4 files)
|
|
||||||
|
|
||||||
| File | Lines | Purpose |
|
|
||||||
|------|-------|---------|
|
|
||||||
| `docs/reference/CLI_REFERENCE.md` | ~800 | All 20 CLI commands |
|
|
||||||
| `docs/reference/MCP_REFERENCE.md` | ~600 | 26 MCP tools |
|
|
||||||
| `docs/reference/CONFIG_FORMAT.md` | ~450 | JSON specification |
|
|
||||||
| `docs/reference/ENVIRONMENT_VARIABLES.md` | ~400 | All env vars |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 2: User Guides ✅
|
|
||||||
|
|
||||||
### Getting Started (4 files)
|
|
||||||
|
|
||||||
| File | Lines | Purpose |
|
|
||||||
|------|-------|---------|
|
|
||||||
| `docs/getting-started/01-installation.md` | ~250 | Install guide |
|
|
||||||
| `docs/getting-started/02-quick-start.md` | ~280 | **3 commands to first skill** |
|
|
||||||
| `docs/getting-started/03-your-first-skill.md` | ~350 | Complete walkthrough |
|
|
||||||
| `docs/getting-started/04-next-steps.md` | ~280 | Where to go next |
|
|
||||||
|
|
||||||
### User Guide (6 files)
|
|
||||||
|
|
||||||
| File | Lines | Purpose |
|
|
||||||
|------|-------|---------|
|
|
||||||
| `docs/user-guide/01-core-concepts.md` | ~350 | How it works |
|
|
||||||
| `docs/user-guide/02-scraping.md` | ~320 | All scraping options |
|
|
||||||
| `docs/user-guide/03-enhancement.md` | ~350 | AI enhancement |
|
|
||||||
| `docs/user-guide/04-packaging.md` | ~400 | Platform export |
|
|
||||||
| `docs/user-guide/05-workflows.md` | ~380 | Workflow presets |
|
|
||||||
| `docs/user-guide/06-troubleshooting.md` | ~380 | Common issues |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 3: Integration ✅
|
|
||||||
|
|
||||||
### Integration & Advanced (6 files)
|
|
||||||
|
|
||||||
| File | Lines | Purpose |
|
|
||||||
|------|-------|---------|
|
|
||||||
| `docs/README.md` | ~200 | Documentation hub |
|
|
||||||
| `docs/ARCHITECTURE.md` | ~250 | Documentation organization |
|
|
||||||
| `docs/advanced/mcp-server.md` | ~250 | MCP server setup |
|
|
||||||
| `docs/advanced/mcp-tools.md` | ~150 | Advanced MCP |
|
|
||||||
| `docs/advanced/custom-workflows.md` | ~280 | Creating workflows |
|
|
||||||
| `docs/advanced/multi-source.md` | ~320 | Multi-source scraping |
|
|
||||||
|
|
||||||
### Updated Files
|
|
||||||
|
|
||||||
| File | Changes |
|
|
||||||
|------|---------|
|
|
||||||
| `README.md` | Added documentation navigation section |
|
|
||||||
| `AGENTS.md` | Updated documentation section |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 4: Cleanup ✅
|
|
||||||
|
|
||||||
### Archived Files
|
|
||||||
|
|
||||||
Moved to `docs/archive/legacy/` with deprecation notices:
|
|
||||||
|
|
||||||
| File | Reason |
|
|
||||||
|------|--------|
|
|
||||||
| `QUICKSTART.md` | Old patterns, outdated install instructions |
|
|
||||||
| `docs/guides/USAGE.md` | `python3 cli/X.py` pattern |
|
|
||||||
| `docs/QUICK_REFERENCE.md` | Phantom commands |
|
|
||||||
|
|
||||||
### Archive Documentation
|
|
||||||
|
|
||||||
- `docs/archive/legacy/README.md` - Explains why files were archived
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## New Structure Overview
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/
|
|
||||||
├── README.md # Navigation hub
|
|
||||||
├── ARCHITECTURE.md # Documentation organization
|
|
||||||
├── DOCUMENTATION_OVERHAUL_COMPLETE.md # This file
|
|
||||||
│
|
|
||||||
├── getting-started/ # New users (4 files)
|
|
||||||
├── user-guide/ # Common tasks (6 files)
|
|
||||||
├── reference/ # Technical reference (4 files)
|
|
||||||
├── advanced/ # Power users (4 files)
|
|
||||||
│
|
|
||||||
└── archive/
|
|
||||||
└── legacy/ # Deprecated files (3 files)
|
|
||||||
├── README.md
|
|
||||||
├── QUICKSTART.md
|
|
||||||
├── USAGE.md
|
|
||||||
└── QUICK_REFERENCE.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**Total: 21 new files + 2 updated files + 3 archived files**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Verification Checklist
|
|
||||||
|
|
||||||
### Accuracy
|
|
||||||
|
|
||||||
- [x] All 20 CLI commands documented
|
|
||||||
- [x] No phantom commands (`merge-sources`, `split-config`, etc.)
|
|
||||||
- [x] No old CLI patterns (`python3 cli/X.py`)
|
|
||||||
- [x] All commands tested against actual CLI
|
|
||||||
- [x] All examples work with copy-paste
|
|
||||||
|
|
||||||
### Completeness
|
|
||||||
|
|
||||||
- [x] Installation guide
|
|
||||||
- [x] Quick start (3 commands)
|
|
||||||
- [x] Complete walkthrough
|
|
||||||
- [x] All source types (docs, GitHub, PDF, local)
|
|
||||||
- [x] All platforms (Claude, Gemini, OpenAI, LangChain, etc.)
|
|
||||||
- [x] Enhancement workflows
|
|
||||||
- [x] Troubleshooting (top 10 issues)
|
|
||||||
|
|
||||||
### Navigation
|
|
||||||
|
|
||||||
- [x] Clear entry point (docs/README.md)
|
|
||||||
- [x] 4-category hierarchy
|
|
||||||
- [x] Cross-references between docs
|
|
||||||
- [x] "Where to start" guidance
|
|
||||||
- [x] Quick reference tables
|
|
||||||
|
|
||||||
### Legacy
|
|
||||||
|
|
||||||
- [x] Old files archived
|
|
||||||
- [x] Deprecation notices added
|
|
||||||
- [x] Redirects to new docs
|
|
||||||
- [x] Archive README explaining changes
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Start Verification
|
|
||||||
|
|
||||||
The documented 3-command workflow actually works:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Install
|
|
||||||
pip install skill-seekers
|
|
||||||
|
|
||||||
# 2. Create skill
|
|
||||||
skill-seekers create https://docs.django.com/
|
|
||||||
|
|
||||||
# 3. Package for Claude
|
|
||||||
skill-seekers package output/django --target claude
|
|
||||||
```
|
|
||||||
|
|
||||||
✅ All commands verified against actual CLI
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Impact on Issue #286
|
|
||||||
|
|
||||||
| User Complaint | Resolution |
|
|
||||||
|----------------|------------|
|
|
||||||
| "Commands removed but still in tutorial" | ✅ All phantom commands removed |
|
|
||||||
| "Structure unclear, logic chaotic" | ✅ Clear 4-category hierarchy |
|
|
||||||
| "AI-generated feel" | ✅ Human-written, tested examples |
|
|
||||||
| "Can't find accurate info" | ✅ Single source of truth in reference/ |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Documentation Stats
|
|
||||||
|
|
||||||
| Metric | Before | After |
|
|
||||||
|--------|--------|-------|
|
|
||||||
| Total files | 83 scattered | 20 organized |
|
|
||||||
| Quick start | Broken | Working |
|
|
||||||
| CLI reference | Partial | Complete (20 commands) |
|
|
||||||
| Navigation | Confusing | Clear hierarchy |
|
|
||||||
| Phantom commands | Multiple | Zero |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Maintenance
|
|
||||||
|
|
||||||
### For Future Updates
|
|
||||||
|
|
||||||
1. **Version in headers** - All docs have version in header
|
|
||||||
2. **Last updated date** - Track freshness
|
|
||||||
3. **Test commands** - Verify examples work
|
|
||||||
4. **Update AGENTS.md** - Keep agent guidance current
|
|
||||||
|
|
||||||
### Deprecation Process
|
|
||||||
|
|
||||||
1. Add deprecation notice pointing to new docs
|
|
||||||
2. Move to `docs/archive/legacy/`
|
|
||||||
3. Update archive README
|
|
||||||
4. Wait 6 months before deletion
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Success Metrics
|
|
||||||
|
|
||||||
✅ Zero references to `python3 cli/X.py` pattern
|
|
||||||
✅ Zero phantom commands documented
|
|
||||||
✅ All 20 CLI commands documented with examples
|
|
||||||
✅ Quick start works with copy-paste
|
|
||||||
✅ Clear navigation from README
|
|
||||||
✅ Troubleshooting covers top 10 issues
|
|
||||||
✅ User can find any command in < 3 clicks
|
|
||||||
✅ Legacy files archived with notices
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related
|
|
||||||
|
|
||||||
- Issue #286 - Original documentation complaint (RESOLVED)
|
|
||||||
- [docs/README.md](docs/README.md) - Start here
|
|
||||||
- [CHANGELOG.md](CHANGELOG.md) - Version history
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Documentation overhaul completed. The docs now match the code.* 🎉
|
|
||||||
@@ -1,531 +0,0 @@
|
|||||||
# Documentation Overhaul Plan - Skill Seekers v3.1.0
|
|
||||||
|
|
||||||
> **Status:** Draft - Pending Review
|
|
||||||
> **Scope:** Complete documentation rewrite
|
|
||||||
> **Target:** Eliminate user confusion, remove phantom commands, establish single source of truth
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Executive Summary
|
|
||||||
|
|
||||||
### Problem Statement (from Issue #286)
|
|
||||||
- Docs reference removed commands (`python3 cli/doc_scraper.py` pattern)
|
|
||||||
- Phantom commands documented that don't exist (`merge-sources`, `generate-router`, etc.)
|
|
||||||
- 83 markdown files with no clear hierarchy
|
|
||||||
- Users cannot find accurate information
|
|
||||||
|
|
||||||
### Solution
|
|
||||||
Complete documentation rewrite with:
|
|
||||||
1. **Single source of truth** CLI reference (all 20 commands)
|
|
||||||
2. **Working** quick start guide (3 commands to first skill)
|
|
||||||
3. **Clear documentation hierarchy** (4 categories max)
|
|
||||||
4. **Deprecation strategy** for outdated files
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase Overview
|
|
||||||
|
|
||||||
| Phase | Name | Duration | Output |
|
|
||||||
|-------|------|----------|--------|
|
|
||||||
| 1 | Foundation | 3-4 hrs | CLI_REFERENCE.md, MCP reference, new structure |
|
|
||||||
| 2 | User Guides | 3-4 hrs | Quick start, workflows, troubleshooting |
|
|
||||||
| 3 | Integration | 2-3 hrs | README rewrite, navigation, redirects |
|
|
||||||
| 4 | Cleanup | 1-2 hrs | Archive old files, add deprecation notices |
|
|
||||||
| **Total** | | **10-14 hrs** | Complete documentation overhaul |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Detailed Phase Breakdown
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 1: Foundation (CLI Reference & Structure)
|
|
||||||
|
|
||||||
### 1.1 Create Master CLI Reference
|
|
||||||
**File:** `docs/reference/CLI_REFERENCE.md` (NEW)
|
|
||||||
|
|
||||||
**Sections:**
|
|
||||||
```
|
|
||||||
CLI_REFERENCE.md
|
|
||||||
├── Overview
|
|
||||||
│ ├── Installation
|
|
||||||
│ ├── Global Flags
|
|
||||||
│ └── Environment Variables
|
|
||||||
│
|
|
||||||
├── Command Reference (alphabetical)
|
|
||||||
│ ├── analyze
|
|
||||||
│ ├── config
|
|
||||||
│ ├── create
|
|
||||||
│ ├── enhance
|
|
||||||
│ ├── enhance-status
|
|
||||||
│ ├── estimate
|
|
||||||
│ ├── github
|
|
||||||
│ ├── install
|
|
||||||
│ ├── install-agent
|
|
||||||
│ ├── multilang
|
|
||||||
│ ├── package
|
|
||||||
│ ├── pdf
|
|
||||||
│ ├── quality
|
|
||||||
│ ├── resume
|
|
||||||
│ ├── scrape
|
|
||||||
│ ├── stream
|
|
||||||
│ ├── unified
|
|
||||||
│ ├── update
|
|
||||||
│ ├── upload
|
|
||||||
│ └── workflows
|
|
||||||
│
|
|
||||||
├── MCP Tools Reference
|
|
||||||
│ ├── Overview (MCP vs CLI)
|
|
||||||
│ ├── Transport modes (stdio, HTTP)
|
|
||||||
│ └── Tool listing (26 tools)
|
|
||||||
│ ├── Core Tools (9)
|
|
||||||
│ │ ├── list_configs
|
|
||||||
│ │ ├── generate_config
|
|
||||||
│ │ ├── validate_config
|
|
||||||
│ │ ├── estimate_pages
|
|
||||||
│ │ ├── scrape_docs
|
|
||||||
│ │ ├── package_skill
|
|
||||||
│ │ ├── upload_skill
|
|
||||||
│ │ ├── enhance_skill
|
|
||||||
│ │ └── install_skill
|
|
||||||
│ ├── Extended Tools (9)
|
|
||||||
│ │ ├── scrape_github
|
|
||||||
│ │ ├── scrape_pdf
|
|
||||||
│ │ ├── unified_scrape
|
|
||||||
│ │ ├── scrape_codebase
|
|
||||||
│ │ ├── detect_patterns
|
|
||||||
│ │ ├── extract_test_examples
|
|
||||||
│ │ ├── build_how_to_guides
|
|
||||||
│ │ ├── extract_config_patterns
|
|
||||||
│ │ └── detect_conflicts
|
|
||||||
│ ├── Config Source Tools (5)
|
|
||||||
│ │ ├── add_config_source
|
|
||||||
│ │ ├── list_config_sources
|
|
||||||
│ │ ├── remove_config_source
|
|
||||||
│ │ ├── fetch_config
|
|
||||||
│ │ └── submit_config
|
|
||||||
│ ├── Config Splitting Tools (2)
|
|
||||||
│ │ ├── split_config
|
|
||||||
│ │ └── generate_router
|
|
||||||
│ ├── Vector Database Tools (4)
|
|
||||||
│ │ ├── export_to_weaviate
|
|
||||||
│ │ ├── export_to_chroma
|
|
||||||
│ │ ├── export_to_faiss
|
|
||||||
│ │ └── export_to_qdrant
|
|
||||||
│ └── Workflow Tools (5)
|
|
||||||
│ ├── list_workflows
|
|
||||||
│ ├── get_workflow
|
|
||||||
│ ├── create_workflow
|
|
||||||
│ ├── update_workflow
|
|
||||||
│ └── delete_workflow
|
|
||||||
│
|
|
||||||
└── Common Workflows
|
|
||||||
├── Workflow 1: Documentation → Skill
|
|
||||||
├── Workflow 2: GitHub → Skill
|
|
||||||
├── Workflow 3: PDF → Skill
|
|
||||||
├── Workflow 4: Local Codebase → Skill
|
|
||||||
└── Workflow 5: Multi-Source → Skill
|
|
||||||
```
|
|
||||||
|
|
||||||
**Each command section includes:**
|
|
||||||
- Purpose (1 sentence)
|
|
||||||
- Syntax
|
|
||||||
- Arguments (table: name, required, description)
|
|
||||||
- Flags (table: short, long, default, description)
|
|
||||||
- Examples (3-5 real examples)
|
|
||||||
- Exit codes
|
|
||||||
- Common errors
|
|
||||||
|
|
||||||
### 1.2 Create Config Format Reference
|
|
||||||
**File:** `docs/reference/CONFIG_FORMAT.md` (NEW)
|
|
||||||
|
|
||||||
Complete JSON schema documentation:
|
|
||||||
- Root properties
|
|
||||||
- Source types (docs, github, pdf, local)
|
|
||||||
- Selectors
|
|
||||||
- Categories
|
|
||||||
- URL patterns
|
|
||||||
- Rate limiting
|
|
||||||
- Examples for each source type
|
|
||||||
|
|
||||||
### 1.3 Create Environment Variables Reference
|
|
||||||
**File:** `docs/reference/ENVIRONMENT_VARIABLES.md` (NEW)
|
|
||||||
|
|
||||||
Complete env var documentation:
|
|
||||||
- API keys (Anthropic, Google, OpenAI, GitHub)
|
|
||||||
- Configuration paths
|
|
||||||
- Output directories
|
|
||||||
- Rate limiting
|
|
||||||
- Debug options
|
|
||||||
|
|
||||||
### 1.4 Establish New Directory Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/
|
|
||||||
├── README.md # Documentation entry point
|
|
||||||
├── ARCHITECTURE.md # How docs are organized
|
|
||||||
│
|
|
||||||
├── getting-started/ # New users start here
|
|
||||||
│ ├── 01-installation.md # pip install, requirements
|
|
||||||
│ ├── 02-quick-start.md # 3 commands to first skill
|
|
||||||
│ ├── 03-your-first-skill.md # Complete walkthrough
|
|
||||||
│ └── 04-next-steps.md # Where to go from here
|
|
||||||
│
|
|
||||||
├── user-guide/ # Common tasks
|
|
||||||
│ ├── 01-core-concepts.md # Skills, configs, sources
|
|
||||||
│ ├── 02-scraping.md # Docs, GitHub, PDF, local
|
|
||||||
│ ├── 03-enhancement.md # AI enhancement options
|
|
||||||
│ ├── 04-packaging.md # Target platforms
|
|
||||||
│ ├── 05-workflows.md # Using workflow presets
|
|
||||||
│ └── 06-troubleshooting.md # Common issues
|
|
||||||
│
|
|
||||||
├── reference/ # Technical reference
|
|
||||||
│ ├── CLI_REFERENCE.md # Complete command reference
|
|
||||||
│ ├── MCP_REFERENCE.md # MCP tools reference
|
|
||||||
│ ├── CONFIG_FORMAT.md # JSON config specification
|
|
||||||
│ └── ENVIRONMENT_VARIABLES.md # Environment variables
|
|
||||||
│
|
|
||||||
└── advanced/ # Power user features
|
|
||||||
├── custom-workflows.md # Creating YAML workflows
|
|
||||||
├── mcp-server.md # MCP integration
|
|
||||||
├── multi-source.md # Unified scraping deep dive
|
|
||||||
└── api-reference.md # Python API (for developers)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 2: User Guides
|
|
||||||
|
|
||||||
### 2.1 Installation Guide
|
|
||||||
**File:** `docs/getting-started/01-installation.md`
|
|
||||||
|
|
||||||
- System requirements (Python 3.10+)
|
|
||||||
- Basic install: `pip install skill-seekers`
|
|
||||||
- With all platforms: `pip install skill-seekers[all-llms]`
|
|
||||||
- Development setup: `pip install -e ".[all-llms,dev]"`
|
|
||||||
- Verify installation: `skill-seekers --version`
|
|
||||||
|
|
||||||
### 2.2 Quick Start Guide
|
|
||||||
**File:** `docs/getting-started/02-quick-start.md`
|
|
||||||
|
|
||||||
The "3 commands to first skill":
|
|
||||||
```bash
|
|
||||||
# 1. Install
|
|
||||||
pip install skill-seekers
|
|
||||||
|
|
||||||
# 2. Create skill (auto-detects source type)
|
|
||||||
skill-seekers create https://docs.django.com/
|
|
||||||
|
|
||||||
# 3. Package for Claude
|
|
||||||
skill-seekers package output/django --target claude
|
|
||||||
```
|
|
||||||
|
|
||||||
Plus variants:
|
|
||||||
- GitHub repo: `skill-seekers create django/django`
|
|
||||||
- Local project: `skill-seekers create ./my-project`
|
|
||||||
- PDF file: `skill-seekers create manual.pdf`
|
|
||||||
|
|
||||||
### 2.3 Your First Skill (Complete Walkthrough)
|
|
||||||
**File:** `docs/getting-started/03-your-first-skill.md`
|
|
||||||
|
|
||||||
Step-by-step with screenshots/description:
|
|
||||||
1. Choose source (we'll use React docs)
|
|
||||||
2. Run create command
|
|
||||||
3. Wait for scraping (explain what's happening)
|
|
||||||
4. Review output structure
|
|
||||||
5. Optional: enhance with AI
|
|
||||||
6. Package skill
|
|
||||||
7. Upload to Claude (or use locally)
|
|
||||||
|
|
||||||
Include actual output examples.
|
|
||||||
|
|
||||||
### 2.4 Core Concepts
|
|
||||||
**File:** `docs/user-guide/01-core-concepts.md`
|
|
||||||
|
|
||||||
- What is a skill? (SKILL.md + references/)
|
|
||||||
- What is a config? (JSON file defining source)
|
|
||||||
- Source types (docs, github, pdf, local)
|
|
||||||
- Enhancement (why and when)
|
|
||||||
- Packaging (target platforms)
|
|
||||||
|
|
||||||
### 2.5 Scraping Guide
|
|
||||||
**File:** `docs/user-guide/02-scraping.md`
|
|
||||||
|
|
||||||
Four sections:
|
|
||||||
1. **Documentation Scraping**
|
|
||||||
- Using presets (`--config`)
|
|
||||||
- Quick mode (`--base-url`, `--name`)
|
|
||||||
- Dry run (`--dry-run`)
|
|
||||||
- Rate limiting
|
|
||||||
|
|
||||||
2. **GitHub Repository Analysis**
|
|
||||||
- Basic analysis
|
|
||||||
- Analysis depth options
|
|
||||||
- With GitHub token
|
|
||||||
|
|
||||||
3. **PDF Extraction**
|
|
||||||
- Basic extraction
|
|
||||||
- OCR for scanned PDFs
|
|
||||||
- Large PDF handling
|
|
||||||
|
|
||||||
4. **Local Codebase Analysis**
|
|
||||||
- Analyzing local projects
|
|
||||||
- Language detection
|
|
||||||
- Pattern detection
|
|
||||||
|
|
||||||
### 2.6 Enhancement Guide
|
|
||||||
**File:** `docs/user-guide/03-enhancement.md`
|
|
||||||
|
|
||||||
- What is enhancement? (improves SKILL.md quality)
|
|
||||||
- API mode vs LOCAL mode
|
|
||||||
- Using workflow presets
|
|
||||||
- Multi-workflow chaining
|
|
||||||
- When to skip enhancement
|
|
||||||
|
|
||||||
### 2.7 Packaging Guide
|
|
||||||
**File:** `docs/user-guide/04-packaging.md`
|
|
||||||
|
|
||||||
- Supported platforms (table)
|
|
||||||
- Platform-specific packaging
|
|
||||||
- Multi-platform packaging loop
|
|
||||||
- Output formats explained
|
|
||||||
|
|
||||||
### 2.8 Workflows Guide
|
|
||||||
**File:** `docs/user-guide/05-workflows.md`
|
|
||||||
|
|
||||||
- What are workflow presets?
|
|
||||||
- Built-in presets (default, minimal, security-focus, architecture-comprehensive, api-documentation)
|
|
||||||
- Using presets (`--enhance-workflow`)
|
|
||||||
- Chaining multiple presets
|
|
||||||
- Listing available workflows
|
|
||||||
- Creating custom workflows
|
|
||||||
|
|
||||||
### 2.9 Troubleshooting Guide
|
|
||||||
**File:** `docs/user-guide/06-troubleshooting.md`
|
|
||||||
|
|
||||||
Common issues with solutions:
|
|
||||||
|
|
||||||
| Issue | Cause | Solution |
|
|
||||||
|-------|-------|----------|
|
|
||||||
| ImportError | Package not installed | `pip install -e .` |
|
|
||||||
| Rate limit exceeded | Too fast | Increase `rate_limit` in config |
|
|
||||||
| No content extracted | Wrong selectors | Check selectors with browser dev tools |
|
|
||||||
| Enhancement fails | No API key / Claude Code not running | Set key or install Claude Code |
|
|
||||||
| Package fails | Missing SKILL.md | Run build first |
|
|
||||||
|
|
||||||
Plus:
|
|
||||||
- How to get help
|
|
||||||
- Debug mode (`--verbose`)
|
|
||||||
- Log files location
|
|
||||||
- Creating a minimal reproduction
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 3: Integration
|
|
||||||
|
|
||||||
### 3.1 Main README Rewrite
|
|
||||||
**File:** `README.md` (UPDATE)
|
|
||||||
|
|
||||||
**Structure:**
|
|
||||||
```markdown
|
|
||||||
# Skill Seekers
|
|
||||||
|
|
||||||
[Badges - keep current]
|
|
||||||
|
|
||||||
## 🚀 Quick Start (3 commands)
|
|
||||||
[The 3-command quick start]
|
|
||||||
|
|
||||||
## What is Skill Seekers?
|
|
||||||
[1-paragraph explanation]
|
|
||||||
|
|
||||||
## 📚 Documentation
|
|
||||||
|
|
||||||
| I want to... | Read this |
|
|
||||||
|--------------|-----------|
|
|
||||||
| Get started quickly | [Quick Start](docs/getting-started/02-quick-start.md) |
|
|
||||||
| Learn common workflows | [User Guide](docs/user-guide/) |
|
|
||||||
| Look up a command | [CLI Reference](docs/reference/CLI_REFERENCE.md) |
|
|
||||||
| Create custom configs | [Config Format](docs/reference/CONFIG_FORMAT.md) |
|
|
||||||
| Set up MCP | [MCP Guide](docs/advanced/mcp-server.md) |
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
[Basic install instructions]
|
|
||||||
|
|
||||||
## Features
|
|
||||||
[Keep current features table]
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
[Link to CONTRIBUTING.md]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.2 Docs Entry Point
|
|
||||||
**File:** `docs/README.md` (NEW)
|
|
||||||
|
|
||||||
Navigation hub:
|
|
||||||
- Welcome message
|
|
||||||
- "Where should I start?" flowchart
|
|
||||||
- Quick links to all sections
|
|
||||||
- Version info
|
|
||||||
- How to contribute to docs
|
|
||||||
|
|
||||||
### 3.3 Architecture Document
|
|
||||||
**File:** `docs/ARCHITECTURE.md` (NEW)
|
|
||||||
|
|
||||||
Explains how documentation is organized:
|
|
||||||
- 4 categories explained
|
|
||||||
- When to use each
|
|
||||||
- File naming conventions
|
|
||||||
- How to contribute
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 4: Cleanup
|
|
||||||
|
|
||||||
### 4.1 Files to Archive
|
|
||||||
|
|
||||||
Move to `docs/archive/legacy/`:
|
|
||||||
- `docs/guides/USAGE.md` - Uses old CLI pattern
|
|
||||||
- `docs/QUICK_REFERENCE.md` - Has phantom commands
|
|
||||||
- `QUICKSTART.md` (root) - Outdated, redirect to new quick start
|
|
||||||
|
|
||||||
### 4.2 Add Deprecation Notices
|
|
||||||
|
|
||||||
For files kept but outdated, add header:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
> ⚠️ **DEPRECATED**: This document references older CLI patterns.
|
|
||||||
>
|
|
||||||
> For up-to-date documentation, see:
|
|
||||||
> - [Quick Start](docs/getting-started/02-quick-start.md)
|
|
||||||
> - [CLI Reference](docs/reference/CLI_REFERENCE.md)
|
|
||||||
```
|
|
||||||
|
|
||||||
Files needing deprecation notice:
|
|
||||||
- `docs/guides/USAGE.md`
|
|
||||||
- Any other docs using `python3 cli/X.py` pattern
|
|
||||||
|
|
||||||
### 4.3 Update AGENTS.md
|
|
||||||
|
|
||||||
Update `AGENTS.md` documentation section to reflect new structure.
|
|
||||||
|
|
||||||
### 4.4 Chinese Documentation Strategy
|
|
||||||
|
|
||||||
**Goal:** Maintain parity between English and Chinese documentation.
|
|
||||||
|
|
||||||
**Approach:**
|
|
||||||
- **Primary:** English docs are source of truth (in `docs/`)
|
|
||||||
- **Secondary:** Chinese translations in `docs.zh-CN/` or `docs/locales/zh-CN/`
|
|
||||||
|
|
||||||
**Files to Translate (Priority Order):**
|
|
||||||
1. `docs/getting-started/02-quick-start.md` - Most accessed
|
|
||||||
2. `docs/README.md` - Entry point
|
|
||||||
3. `docs/user-guide/06-troubleshooting.md` - Reduces support burden
|
|
||||||
4. `docs/reference/CLI_REFERENCE.md` - Command reference
|
|
||||||
|
|
||||||
**Translation Workflow:**
|
|
||||||
```
|
|
||||||
English doc updated → Mark for translation → Translate → Review → Publish
|
|
||||||
```
|
|
||||||
|
|
||||||
**Options for Implementation:**
|
|
||||||
- **Option A:** Separate `docs.zh-CN/` directory (mirrors `docs/` structure)
|
|
||||||
- **Option B:** Side-by-side files (`README.md` + `README.zh-CN.md` in same dir)
|
|
||||||
- **Option C:** Keep existing `README.zh-CN.md` pattern, translate key docs only
|
|
||||||
|
|
||||||
**Recommendation:** Option C for now - translate only:
|
|
||||||
- `README.zh-CN.md` (update existing)
|
|
||||||
- `docs/getting-started/02-quick-start.zh-CN.md` (new)
|
|
||||||
- `docs/user-guide/06-troubleshooting.zh-CN.md` (new)
|
|
||||||
|
|
||||||
**Long-term:** Consider i18n framework if user base grows.
|
|
||||||
|
|
||||||
**Chinese README.md Updates Needed:**
|
|
||||||
- Update installation instructions
|
|
||||||
- Update command examples (new CLI pattern)
|
|
||||||
- Update navigation links to new docs structure
|
|
||||||
- Remove phantom commands
|
|
||||||
|
|
||||||
**Sync Strategy:**
|
|
||||||
- English docs: Always current (source of truth)
|
|
||||||
- Chinese docs: Best effort, marked with "Last translated: DATE"
|
|
||||||
- Community contributions welcome for translations
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Files to Create/Modify
|
|
||||||
|
|
||||||
### New Files (16)
|
|
||||||
|
|
||||||
| File | Phase | Purpose |
|
|
||||||
|------|-------|---------|
|
|
||||||
| `docs/reference/CLI_REFERENCE.md` | 1 | Master command reference |
|
|
||||||
| `docs/reference/MCP_REFERENCE.md` | 1 | MCP tools reference |
|
|
||||||
| `docs/reference/CONFIG_FORMAT.md` | 1 | JSON config spec |
|
|
||||||
| `docs/reference/ENVIRONMENT_VARIABLES.md` | 1 | Env vars reference |
|
|
||||||
| `docs/README.md` | 3 | Docs entry point |
|
|
||||||
| `docs/ARCHITECTURE.md` | 3 | Documentation organization |
|
|
||||||
| `docs/getting-started/01-installation.md` | 2 | Install guide |
|
|
||||||
| `docs/getting-started/02-quick-start.md` | 2 | 3-command quick start |
|
|
||||||
| `docs/getting-started/03-your-first-skill.md` | 2 | Complete walkthrough |
|
|
||||||
| `docs/getting-started/04-next-steps.md` | 2 | Where to go next |
|
|
||||||
| `docs/user-guide/01-core-concepts.md` | 2 | Core concepts |
|
|
||||||
| `docs/user-guide/02-scraping.md` | 2 | Scraping guide |
|
|
||||||
| `docs/user-guide/03-enhancement.md` | 2 | Enhancement guide |
|
|
||||||
| `docs/user-guide/04-packaging.md` | 2 | Packaging guide |
|
|
||||||
| `docs/user-guide/05-workflows.md` | 2 | Workflows guide |
|
|
||||||
| `docs/user-guide/06-troubleshooting.md` | 2 | Troubleshooting |
|
|
||||||
|
|
||||||
### Modified Files (2)
|
|
||||||
|
|
||||||
| File | Phase | Changes |
|
|
||||||
|------|-------|---------|
|
|
||||||
| `README.md` | 3 | New structure, navigation table |
|
|
||||||
| `AGENTS.md` | 4 | Update documentation section |
|
|
||||||
|
|
||||||
### Archived Files (3+)
|
|
||||||
|
|
||||||
| File | Destination | Action |
|
|
||||||
|------|-------------|--------|
|
|
||||||
| `docs/guides/USAGE.md` | `docs/archive/legacy/` | Move + deprecation notice |
|
|
||||||
| `docs/QUICK_REFERENCE.md` | `docs/archive/legacy/` | Move + deprecation notice |
|
|
||||||
| `QUICKSTART.md` | `docs/archive/legacy/` | Move + create redirect |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Success Metrics
|
|
||||||
|
|
||||||
After implementation, documentation should:
|
|
||||||
|
|
||||||
- [ ] Zero references to `python3 cli/X.py` pattern
|
|
||||||
- [ ] Zero phantom commands documented
|
|
||||||
- [ ] All 20 CLI commands documented with examples
|
|
||||||
- [ ] Quick start works with copy-paste
|
|
||||||
- [ ] Clear navigation from README
|
|
||||||
- [ ] Troubleshooting covers top 10 issues
|
|
||||||
- [ ] User can find any command in < 3 clicks
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Review Checklist
|
|
||||||
|
|
||||||
Before implementation, review this plan for:
|
|
||||||
|
|
||||||
- [ ] **Completeness**: All 20 commands covered?
|
|
||||||
- [ ] **Accuracy**: No phantom commands?
|
|
||||||
- [ ] **Organization**: Clear hierarchy?
|
|
||||||
- [ ] **Scope**: Not too much / too little?
|
|
||||||
- [ ] **Priority**: Right order of phases?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
1. **Review this plan** - Comment, modify, approve
|
|
||||||
2. **Say "good to go"** - I'll switch to implementation mode
|
|
||||||
3. **Implementation** - I'll create todos and start writing
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Plan Version: 1.1*
|
|
||||||
*Created: 2026-02-16*
|
|
||||||
*Status: Awaiting Review*
|
|
||||||
@@ -1,237 +0,0 @@
|
|||||||
# Documentation Overhaul Summary
|
|
||||||
|
|
||||||
> **Completed:** 2026-02-16
|
|
||||||
> **Issue:** #286 - Documentation gaps and outdated information
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Problem Statement
|
|
||||||
|
|
||||||
The documentation had critical issues:
|
|
||||||
- References to removed commands (`python3 cli/X.py` pattern)
|
|
||||||
- Phantom commands documented that don't exist
|
|
||||||
- 83 scattered files with no clear hierarchy
|
|
||||||
- Users unable to find accurate information
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Solution Implemented
|
|
||||||
|
|
||||||
Complete documentation rewrite with:
|
|
||||||
1. **Single source of truth** CLI reference (all 20 commands)
|
|
||||||
2. **Working** quick start guide (3 commands to first skill)
|
|
||||||
3. **Clear hierarchy** (4 categories: getting-started, user-guide, reference, advanced)
|
|
||||||
4. **Deprecation strategy** for outdated files
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## New Documentation Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/
|
|
||||||
├── README.md # Navigation hub
|
|
||||||
├── ARCHITECTURE.md # Documentation organization
|
|
||||||
│
|
|
||||||
├── getting-started/ # New users (4 files)
|
|
||||||
│ ├── 01-installation.md
|
|
||||||
│ ├── 02-quick-start.md # 3 commands to first skill
|
|
||||||
│ ├── 03-your-first-skill.md # Complete walkthrough
|
|
||||||
│ └── 04-next-steps.md
|
|
||||||
│
|
|
||||||
├── user-guide/ # Common tasks (6 files)
|
|
||||||
│ ├── 01-core-concepts.md
|
|
||||||
│ ├── 02-scraping.md
|
|
||||||
│ ├── 03-enhancement.md
|
|
||||||
│ ├── 04-packaging.md
|
|
||||||
│ ├── 05-workflows.md
|
|
||||||
│ └── 06-troubleshooting.md
|
|
||||||
│
|
|
||||||
├── reference/ # Technical reference (4 files)
|
|
||||||
│ ├── CLI_REFERENCE.md # 20 commands, comprehensive
|
|
||||||
│ ├── MCP_REFERENCE.md # 26 MCP tools
|
|
||||||
│ ├── CONFIG_FORMAT.md # JSON specification
|
|
||||||
│ └── ENVIRONMENT_VARIABLES.md
|
|
||||||
│
|
|
||||||
└── advanced/ # Power users (4 files)
|
|
||||||
├── mcp-server.md
|
|
||||||
├── mcp-tools.md
|
|
||||||
├── custom-workflows.md
|
|
||||||
└── multi-source.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**Total: 18 new files + 2 updated files**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Files Created
|
|
||||||
|
|
||||||
### Phase 1: Foundation (Reference)
|
|
||||||
|
|
||||||
| File | Purpose | Lines |
|
|
||||||
|------|---------|-------|
|
|
||||||
| `docs/reference/CLI_REFERENCE.md` | Complete command reference | ~800 |
|
|
||||||
| `docs/reference/MCP_REFERENCE.md` | 26 MCP tools documented | ~600 |
|
|
||||||
| `docs/reference/CONFIG_FORMAT.md` | JSON config specification | ~450 |
|
|
||||||
| `docs/reference/ENVIRONMENT_VARIABLES.md` | All environment variables | ~400 |
|
|
||||||
|
|
||||||
### Phase 2: User Guides
|
|
||||||
|
|
||||||
| File | Purpose | Lines |
|
|
||||||
|------|---------|-------|
|
|
||||||
| `docs/getting-started/01-installation.md` | Installation guide | ~250 |
|
|
||||||
| `docs/getting-started/02-quick-start.md` | 3-command quick start | ~280 |
|
|
||||||
| `docs/getting-started/03-your-first-skill.md` | Complete walkthrough | ~350 |
|
|
||||||
| `docs/getting-started/04-next-steps.md` | Where to go next | ~280 |
|
|
||||||
| `docs/user-guide/01-core-concepts.md` | How it works | ~350 |
|
|
||||||
| `docs/user-guide/02-scraping.md` | All scraping options | ~320 |
|
|
||||||
| `docs/user-guide/03-enhancement.md` | AI enhancement | ~350 |
|
|
||||||
| `docs/user-guide/04-packaging.md` | Platform export | ~400 |
|
|
||||||
| `docs/user-guide/05-workflows.md` | Workflow presets | ~380 |
|
|
||||||
| `docs/user-guide/06-troubleshooting.md` | Common issues | ~380 |
|
|
||||||
|
|
||||||
### Phase 3: Integration & Advanced
|
|
||||||
|
|
||||||
| File | Purpose | Lines |
|
|
||||||
|------|---------|-------|
|
|
||||||
| `docs/README.md` | Documentation hub | ~200 |
|
|
||||||
| `docs/ARCHITECTURE.md` | Documentation organization | ~250 |
|
|
||||||
| `docs/advanced/mcp-server.md` | MCP server setup | ~250 |
|
|
||||||
| `docs/advanced/mcp-tools.md` | Advanced MCP | ~150 |
|
|
||||||
| `docs/advanced/custom-workflows.md` | Creating workflows | ~280 |
|
|
||||||
| `docs/advanced/multi-source.md` | Multi-source scraping | ~320 |
|
|
||||||
|
|
||||||
### Files Updated
|
|
||||||
|
|
||||||
| File | Changes |
|
|
||||||
|------|---------|
|
|
||||||
| `README.md` | Added documentation navigation section |
|
|
||||||
| `AGENTS.md` | Updated documentation section with new structure |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Improvements
|
|
||||||
|
|
||||||
### 1. No More Phantom Commands
|
|
||||||
|
|
||||||
**Before:**
|
|
||||||
```bash
|
|
||||||
# These don't exist:
|
|
||||||
python3 cli/doc_scraper.py
|
|
||||||
skill-seekers merge-sources
|
|
||||||
skill-seekers generate-router
|
|
||||||
skill-seekers split-config
|
|
||||||
```
|
|
||||||
|
|
||||||
**After:**
|
|
||||||
```bash
|
|
||||||
# Only documented commands that exist:
|
|
||||||
skill-seekers create <source>
|
|
||||||
skill-seekers package <dir> --target <platform>
|
|
||||||
skill-seekers workflows <action>
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Modern CLI Syntax
|
|
||||||
|
|
||||||
**Before:**
|
|
||||||
```bash
|
|
||||||
python3 cli/doc_scraper.py --config configs/react.json
|
|
||||||
python3 cli/enhance_skill_local.py output/react/
|
|
||||||
```
|
|
||||||
|
|
||||||
**After:**
|
|
||||||
```bash
|
|
||||||
skill-seekers scrape --config configs/react.json
|
|
||||||
skill-seekers enhance output/react/
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Clear Navigation
|
|
||||||
|
|
||||||
**Before:** 83 scattered files, no clear entry point
|
|
||||||
|
|
||||||
**After:**
|
|
||||||
```
|
|
||||||
New? → docs/getting-started/
|
|
||||||
Learning? → docs/user-guide/
|
|
||||||
Reference? → docs/reference/
|
|
||||||
Advanced? → docs/advanced/
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Complete Command Reference
|
|
||||||
|
|
||||||
**Before:** Partial command documentation
|
|
||||||
|
|
||||||
**After:** All 20 commands documented with:
|
|
||||||
- Purpose and syntax
|
|
||||||
- All arguments and flags
|
|
||||||
- Multiple examples
|
|
||||||
- Exit codes
|
|
||||||
- Common errors
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Start Verification
|
|
||||||
|
|
||||||
The "3 commands to first skill" actually works:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Install
|
|
||||||
pip install skill-seekers
|
|
||||||
|
|
||||||
# 2. Create
|
|
||||||
skill-seekers create https://docs.django.com/
|
|
||||||
|
|
||||||
# 3. Package
|
|
||||||
skill-seekers package output/django --target claude
|
|
||||||
```
|
|
||||||
|
|
||||||
All documented commands tested against actual CLI.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps (Phase 4)
|
|
||||||
|
|
||||||
Remaining tasks:
|
|
||||||
|
|
||||||
1. **Archive legacy files**
|
|
||||||
- Move `docs/guides/USAGE.md` to `docs/archive/legacy/`
|
|
||||||
- Move `docs/QUICK_REFERENCE.md` to `docs/archive/legacy/`
|
|
||||||
- Move `QUICKSTART.md` to `docs/archive/legacy/`
|
|
||||||
|
|
||||||
2. **Add deprecation notices**
|
|
||||||
- Add header to legacy files pointing to new docs
|
|
||||||
|
|
||||||
3. **Chinese translation strategy**
|
|
||||||
- Update `README.zh-CN.md`
|
|
||||||
- Translate key docs: quick-start, troubleshooting
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Success Metrics
|
|
||||||
|
|
||||||
✅ Zero references to `python3 cli/X.py` pattern
|
|
||||||
✅ Zero phantom commands documented
|
|
||||||
✅ All 20 CLI commands documented with examples
|
|
||||||
✅ Quick start works with copy-paste
|
|
||||||
✅ Clear navigation from README
|
|
||||||
✅ Troubleshooting covers top 10 issues
|
|
||||||
✅ User can find any command in < 3 clicks
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Files to Archive (Phase 4)
|
|
||||||
|
|
||||||
| File | Action |
|
|
||||||
|------|--------|
|
|
||||||
| `docs/guides/USAGE.md` | Move to `docs/archive/legacy/` |
|
|
||||||
| `docs/QUICK_REFERENCE.md` | Move to `docs/archive/legacy/` |
|
|
||||||
| `QUICKSTART.md` | Move to `docs/archive/legacy/` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related Issues
|
|
||||||
|
|
||||||
- Issue #286 - Documentation gaps (RESOLVED)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Documentation overhaul completed as part of v3.1.0 release preparation.*
|
|
||||||
@@ -1,415 +0,0 @@
|
|||||||
# Feature Gap Analysis - Skill Seekers
|
|
||||||
|
|
||||||
> **Analysis Date:** 2026-02-16
|
|
||||||
> **Version Analyzed:** 3.1.0
|
|
||||||
> **Purpose:** Identify missing features and improvement opportunities
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Executive Summary
|
|
||||||
|
|
||||||
After comprehensive review of the codebase, documentation, and CLI, Skill Seekers is **feature-rich** for its core use case. However, several gaps exist in:
|
|
||||||
|
|
||||||
1. **Developer Experience** - Missing modern DX features
|
|
||||||
2. **Enterprise Features** - Limited multi-user/team capabilities
|
|
||||||
3. **Observability** - Minimal monitoring and analytics
|
|
||||||
4. **Ecosystem Integration** - Missing some popular tools
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ Current Strengths
|
|
||||||
|
|
||||||
### Core Features (Well-Covered)
|
|
||||||
|
|
||||||
| Category | Features | Status |
|
|
||||||
|----------|----------|--------|
|
|
||||||
| **Sources** | Docs, GitHub, PDF, Local code | ✅ Complete |
|
|
||||||
| **Platforms** | 16+ targets (Claude, Gemini, OpenAI, LangChain, etc.) | ✅ Excellent |
|
|
||||||
| **Enhancement** | AI-powered improvement, workflows | ✅ Advanced |
|
|
||||||
| **CLI** | 20 commands, unified interface | ✅ Complete |
|
|
||||||
| **MCP** | 26 tools, stdio/HTTP transport | ✅ Advanced |
|
|
||||||
| **Testing** | 1880+ tests, 98 test files | ✅ Excellent |
|
|
||||||
| **Documentation** | 20 organized docs + Chinese i18n | ✅ Comprehensive |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔴 Critical Gaps (High Priority)
|
|
||||||
|
|
||||||
### 1. Web UI / Dashboard
|
|
||||||
|
|
||||||
**Gap:** No graphical user interface - only CLI
|
|
||||||
|
|
||||||
**Impact:**
|
|
||||||
- Non-technical users cannot use the tool
|
|
||||||
- No visual workflow management
|
|
||||||
- Hard to manage multiple skills
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```
|
|
||||||
skill-seekers ui
|
|
||||||
# Starts local web server at http://localhost:8080
|
|
||||||
# - Visual skill management
|
|
||||||
# - Drag-and-drop config builder
|
|
||||||
# - Progress visualization
|
|
||||||
# - Skill comparison dashboard
|
|
||||||
```
|
|
||||||
|
|
||||||
**Implementation:** FastAPI + React/Vue (can reuse MCP tools)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. Skill Registry / Marketplace
|
|
||||||
|
|
||||||
**Gap:** No central repository for sharing skills
|
|
||||||
|
|
||||||
**Impact:**
|
|
||||||
- Users recreate same skills repeatedly
|
|
||||||
- No discoverability
|
|
||||||
- No community collaboration
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```bash
|
|
||||||
# Browse community skills
|
|
||||||
skill-seekers registry search react
|
|
||||||
|
|
||||||
# Publish your skill
|
|
||||||
skill-seekers registry publish output/my-skill/
|
|
||||||
|
|
||||||
# Install from registry
|
|
||||||
skill-seekers registry install community/react
|
|
||||||
```
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- Public/private skill repository
|
|
||||||
- Versioning
|
|
||||||
- Ratings/reviews
|
|
||||||
- Categories/tags
|
|
||||||
- Usage statistics
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. Incremental Updates (Smart Diff)
|
|
||||||
|
|
||||||
**Gap:** `update` command exists but lacks intelligent change detection
|
|
||||||
|
|
||||||
**Current:**
|
|
||||||
```bash
|
|
||||||
skill-seekers update --config react --since 2026-01-01
|
|
||||||
# Just re-scrapes everything after date
|
|
||||||
```
|
|
||||||
|
|
||||||
**Gap:** No true diff/change detection
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```bash
|
|
||||||
skill-seekers diff output/react/
|
|
||||||
# Shows what changed since last scrape
|
|
||||||
|
|
||||||
skill-seekers update output/react/ --smart
|
|
||||||
# Only fetches changed pages
|
|
||||||
# Auto-detects: new pages, modified content, removed pages
|
|
||||||
```
|
|
||||||
|
|
||||||
**Implementation:**
|
|
||||||
- Content hashing per page
|
|
||||||
- ETags/Last-Modified header tracking
|
|
||||||
- Smart merge (don't lose manual edits)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4. Config Template Generator
|
|
||||||
|
|
||||||
**Gap:** No interactive config wizard
|
|
||||||
|
|
||||||
**Current:**
|
|
||||||
```bash
|
|
||||||
# Users must manually write JSON configs
|
|
||||||
```
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```bash
|
|
||||||
skill-seekers init-config
|
|
||||||
# Interactive wizard:
|
|
||||||
# - "What are you scraping?" (docs/github/pdf)
|
|
||||||
# - "Enter URL:"
|
|
||||||
# - "Auto-detecting selectors... Done!"
|
|
||||||
# - "Test scrape?" (y/n)
|
|
||||||
# - Saves to configs/my-site.json
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. Batch Operations
|
|
||||||
|
|
||||||
**Gap:** No efficient way to manage multiple skills
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```bash
|
|
||||||
# Process multiple skills
|
|
||||||
skill-seekers batch scrape --configs react,vue,angular
|
|
||||||
|
|
||||||
# Update all skills
|
|
||||||
skill-seekers batch update --all
|
|
||||||
|
|
||||||
# Package all for release
|
|
||||||
skill-seekers batch package --all --target claude
|
|
||||||
|
|
||||||
# Generate status report
|
|
||||||
skill-seekers batch status
|
|
||||||
# Shows: last scrape, size, needs update?
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟠 Medium Priority Gaps
|
|
||||||
|
|
||||||
### 6. Advanced Search / Query
|
|
||||||
|
|
||||||
**Gap:** Cannot search across skills
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```bash
|
|
||||||
# Search all local skills
|
|
||||||
skill-seekers search "authentication"
|
|
||||||
# Shows: react/auth.md, django/auth.md, etc.
|
|
||||||
|
|
||||||
# Query using natural language (via MCP)
|
|
||||||
"What auth methods does React support?"
|
|
||||||
# Searches across all React-related skills
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 7. Backup / Restore
|
|
||||||
|
|
||||||
**Gap:** No built-in backup mechanism
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```bash
|
|
||||||
# Backup all skills
|
|
||||||
skill-seekers backup --output backups/2026-02-16/
|
|
||||||
|
|
||||||
# Restore
|
|
||||||
skill-seekers restore backups/2026-02-16/
|
|
||||||
|
|
||||||
# Cloud backup
|
|
||||||
skill-seekers backup --target s3://my-bucket/skills/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 8. Skill Versioning
|
|
||||||
|
|
||||||
**Gap:** No built-in versioning for skills
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```bash
|
|
||||||
# Tag a skill version
|
|
||||||
skill-seekers tag output/react/ v2.0.0
|
|
||||||
|
|
||||||
# List versions
|
|
||||||
skill-seekers tag list output/react/
|
|
||||||
|
|
||||||
# Rollback
|
|
||||||
skill-seekers tag rollback output/react/ v1.9.0
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 9. Performance Metrics
|
|
||||||
|
|
||||||
**Gap:** Limited benchmarking beyond basic timing
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```bash
|
|
||||||
# Detailed performance report
|
|
||||||
skill-seekers benchmark detailed --config react
|
|
||||||
|
|
||||||
# Metrics:
|
|
||||||
# - Pages/minute
|
|
||||||
# - Memory usage
|
|
||||||
# - Network utilization
|
|
||||||
# - Token usage (for AI enhancement)
|
|
||||||
# - Cache hit rate
|
|
||||||
|
|
||||||
# Export metrics
|
|
||||||
skill-seekers benchmark export --format prometheus
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 10. Plugin System
|
|
||||||
|
|
||||||
**Gap:** No extensibility for custom scrapers/adaptors
|
|
||||||
|
|
||||||
**Recommended Solution:**
|
|
||||||
```python
|
|
||||||
# Custom scraper plugin
|
|
||||||
from skill_seekers import ScraperPlugin
|
|
||||||
|
|
||||||
class CustomScraper(ScraperPlugin):
|
|
||||||
def scrape(self, url):
|
|
||||||
# Custom logic
|
|
||||||
pass
|
|
||||||
|
|
||||||
# Register
|
|
||||||
skill-seekers plugin install my-scraper.py
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟡 Low Priority Gaps
|
|
||||||
|
|
||||||
### 11. More Platform Adaptors
|
|
||||||
|
|
||||||
**Missing Platforms:**
|
|
||||||
- **Dify** - Popular in China
|
|
||||||
- **Flowise** - Visual LangChain builder
|
|
||||||
- **Botpress** - Chatbot platform
|
|
||||||
- **Voiceflow** - Voice/chat AI
|
|
||||||
- **n8n** - Workflow automation
|
|
||||||
|
|
||||||
**Implementation:** Add new adaptor classes (pattern already exists)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 12. Mobile App Companion
|
|
||||||
|
|
||||||
**Gap:** No mobile interface for monitoring
|
|
||||||
|
|
||||||
**Use Case:** Check scraping progress on phone
|
|
||||||
|
|
||||||
**Implementation:** PWA or native app using MCP HTTP transport
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 13. Collaboration Features
|
|
||||||
|
|
||||||
**Gap:** Single-user focused
|
|
||||||
|
|
||||||
**Recommended:**
|
|
||||||
- Team workspaces
|
|
||||||
- Shared config repositories
|
|
||||||
- Comment/annotation on skills
|
|
||||||
- Review workflows before publishing
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 14. Analytics Dashboard
|
|
||||||
|
|
||||||
**Gap:** No usage analytics
|
|
||||||
|
|
||||||
**Recommended:**
|
|
||||||
```bash
|
|
||||||
skill-seekers analytics
|
|
||||||
# Shows:
|
|
||||||
# - Most used skills
|
|
||||||
# - Scraping frequency
|
|
||||||
# - Success/failure rates
|
|
||||||
# - Token spend (AI enhancement)
|
|
||||||
# - Time saved vs manual
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 15. Integration Tests for All Platforms
|
|
||||||
|
|
||||||
**Gap:** Some adaptors may lack comprehensive testing
|
|
||||||
|
|
||||||
**Recommended:**
|
|
||||||
- Integration test matrix for all 16 platforms
|
|
||||||
- Automated tests against live APIs (sandbox)
|
|
||||||
- Platform compatibility dashboard
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 Gap Summary Matrix
|
|
||||||
|
|
||||||
| # | Feature | Priority | Effort | Impact | Status |
|
|
||||||
|---|---------|----------|--------|--------|--------|
|
|
||||||
| 1 | Web UI / Dashboard | 🔴 Critical | High | High | ❌ Missing |
|
|
||||||
| 2 | Skill Registry | 🔴 Critical | High | High | ❌ Missing |
|
|
||||||
| 3 | Smart Diff/Update | 🔴 Critical | Medium | High | ⚠️ Basic |
|
|
||||||
| 4 | Config Generator | 🔴 Critical | Low | High | ❌ Missing |
|
|
||||||
| 5 | Batch Operations | 🔴 Critical | Medium | Medium | ❌ Missing |
|
|
||||||
| 6 | Advanced Search | 🟠 Medium | Medium | Medium | ❌ Missing |
|
|
||||||
| 7 | Backup/Restore | 🟠 Medium | Low | Medium | ❌ Missing |
|
|
||||||
| 8 | Skill Versioning | 🟠 Medium | Medium | Medium | ❌ Missing |
|
|
||||||
| 9 | Performance Metrics | 🟠 Medium | Low | Medium | ⚠️ Basic |
|
|
||||||
| 10 | Plugin System | 🟠 Medium | High | High | ❌ Missing |
|
|
||||||
| 11 | More Platforms | 🟡 Low | Low | Low | ⚠️ Partial |
|
|
||||||
| 12 | Mobile App | 🟡 Low | High | Low | ❌ Missing |
|
|
||||||
| 13 | Collaboration | 🟡 Low | High | Medium | ❌ Missing |
|
|
||||||
| 14 | Analytics | 🟡 Low | Medium | Low | ❌ Missing |
|
|
||||||
| 15 | Integration Tests | 🟡 Low | Medium | Medium | ⚠️ Partial |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 Recommended Roadmap
|
|
||||||
|
|
||||||
### Phase 1: Foundation (Next 2-4 weeks)
|
|
||||||
|
|
||||||
1. **Config Generator** (Easy win)
|
|
||||||
2. **Batch Operations** (High utility)
|
|
||||||
3. **Backup/Restore** (Data safety)
|
|
||||||
4. **Performance Metrics** (Observability)
|
|
||||||
|
|
||||||
### Phase 2: Experience (1-2 months)
|
|
||||||
|
|
||||||
1. **Smart Diff/Update** (Core improvement)
|
|
||||||
2. **Advanced Search** (Discoverability)
|
|
||||||
3. **Skill Versioning** (Management)
|
|
||||||
4. **Web UI MVP** (Accessibility)
|
|
||||||
|
|
||||||
### Phase 3: Ecosystem (2-3 months)
|
|
||||||
|
|
||||||
1. **Skill Registry** (Network effect)
|
|
||||||
2. **Plugin System** (Extensibility)
|
|
||||||
3. **More Platforms** (Reach)
|
|
||||||
4. **Collaboration** (Teams)
|
|
||||||
|
|
||||||
### Phase 4: Polish (Ongoing)
|
|
||||||
|
|
||||||
1. **Mobile App**
|
|
||||||
2. **Analytics**
|
|
||||||
3. **Advanced Web UI**
|
|
||||||
4. **Integration Tests**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 💡 Quick Wins (Can Implement Today)
|
|
||||||
|
|
||||||
1. **`skill-seekers init-config`** - Interactive config wizard
|
|
||||||
2. **`skill-seekers batch`** - Simple batch operations wrapper
|
|
||||||
3. **`skill-seekers backup`** - Tar.gz export of output/
|
|
||||||
4. **Performance timing** - Add detailed timing to existing commands
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔗 Related Issues
|
|
||||||
|
|
||||||
- #260 - Chinese Translation (In Progress)
|
|
||||||
- #286 - Documentation gaps (Resolved)
|
|
||||||
- (Create new issues for gaps above)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Conclusion
|
|
||||||
|
|
||||||
Skill Seekers has **excellent core functionality** but lacks modern DX features expected in 2026:
|
|
||||||
|
|
||||||
**Biggest Impact Gaps:**
|
|
||||||
1. Web UI (accessibility)
|
|
||||||
2. Skill Registry (network effects)
|
|
||||||
3. Smart Updates (efficiency)
|
|
||||||
|
|
||||||
**Easiest to Implement:**
|
|
||||||
1. Config Generator
|
|
||||||
2. Batch Operations
|
|
||||||
3. Backup/Restore
|
|
||||||
|
|
||||||
The foundation is solid - these gaps are opportunities for significant user experience improvements.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Analysis complete. Recommend prioritizing Phase 1 features.*
|
|
||||||
@@ -1,349 +0,0 @@
|
|||||||
# Implementation Gaps Analysis - Current Codebase
|
|
||||||
|
|
||||||
> **Analysis Date:** 2026-02-16
|
|
||||||
> **Scope:** Integration gaps, duplicate code, missing connections in CURRENT implementation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚨 Critical Integration Gaps
|
|
||||||
|
|
||||||
### 1. Unified Scraper Does NOT Use Workflow Runner
|
|
||||||
|
|
||||||
**Gap:** `unified_scraper.py` has its own scraping logic instead of using the shared `workflow_runner.py`
|
|
||||||
|
|
||||||
**Evidence:**
|
|
||||||
```bash
|
|
||||||
$ grep -n "workflow_runner" src/skill_seekers/cli/unified_scraper.py
|
|
||||||
# (no results)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Other scrapers DO use workflow_runner:**
|
|
||||||
- ✅ `doc_scraper.py` - uses `run_workflows()`
|
|
||||||
- ✅ `github_scraper.py` - uses `run_workflows()`
|
|
||||||
- ✅ `pdf_scraper.py` - uses `run_workflows()`
|
|
||||||
- ✅ `codebase_scraper.py` - uses `run_workflows()`
|
|
||||||
- ❌ `unified_scraper.py` - DOES NOT use `run_workflows()`
|
|
||||||
|
|
||||||
**Impact:**
|
|
||||||
- Unified scraper cannot use enhancement workflows
|
|
||||||
- Inconsistent behavior between single-source and multi-source scraping
|
|
||||||
- Code duplication in enhancement logic
|
|
||||||
|
|
||||||
**Fix:**
|
|
||||||
```python
|
|
||||||
# Add to unified_scraper.py
|
|
||||||
from skill_seekers.cli.workflow_runner import run_workflows
|
|
||||||
|
|
||||||
# After scraping all sources
|
|
||||||
context = run_workflows(
|
|
||||||
workflows=args.enhance_workflow,
|
|
||||||
inline_stages=args.enhance_stage,
|
|
||||||
scraper_context={"name": skill_name, "source_type": "unified"},
|
|
||||||
args=args
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. Duplicate Enhancer Classes (Old vs New)
|
|
||||||
|
|
||||||
**Gap:** Both old and new enhancer modules exist and are used simultaneously
|
|
||||||
|
|
||||||
**Old modules (should be deprecated):**
|
|
||||||
- `ai_enhancer.py` - Old AIEnhancer class
|
|
||||||
- `config_enhancer.py` - Old ConfigEnhancer class
|
|
||||||
- `guide_enhancer.py` - Old GuideEnhancer class
|
|
||||||
|
|
||||||
**New unified module:**
|
|
||||||
- `unified_enhancer.py` - New UnifiedEnhancer class (replaces all above)
|
|
||||||
|
|
||||||
**Files still importing OLD modules:**
|
|
||||||
```
|
|
||||||
architectural_pattern_detector.py → ai_enhancer.AIEnhancer
|
|
||||||
codebase_scraper.py → ai_enhancer.PatternEnhancer, config_enhancer.ConfigEnhancer
|
|
||||||
config_extractor.py → config_enhancer.ConfigEnhancer
|
|
||||||
enhancement_workflow.py → ai_enhancer.PatternEnhancer, TestExampleEnhancer, AIEnhancer
|
|
||||||
how_to_guide_builder.py → guide_enhancer.GuideEnhancer
|
|
||||||
pattern_recognizer.py → ai_enhancer.PatternEnhancer
|
|
||||||
test_example_extractor.py → ai_enhancer.TestExampleEnhancer
|
|
||||||
```
|
|
||||||
|
|
||||||
**New unified_enhancer.py exports:**
|
|
||||||
```python
|
|
||||||
class UnifiedEnhancer: ...
|
|
||||||
class PatternEnhancer(UnifiedEnhancer): ...
|
|
||||||
class TestExampleEnhancer(UnifiedEnhancer): ...
|
|
||||||
class GuideEnhancer(UnifiedEnhancer): ...
|
|
||||||
class ConfigEnhancer(UnifiedEnhancer): ...
|
|
||||||
AIEnhancer = UnifiedEnhancer # Alias for compatibility
|
|
||||||
```
|
|
||||||
|
|
||||||
**Impact:**
|
|
||||||
- Maintenance burden (fix bugs in multiple places)
|
|
||||||
- Inconsistent behavior
|
|
||||||
- Confusion about which enhancer to use
|
|
||||||
- Larger codebase
|
|
||||||
|
|
||||||
**Fix:**
|
|
||||||
1. Migrate all imports from old modules to `unified_enhancer.py`
|
|
||||||
2. Deprecate old modules with warnings
|
|
||||||
3. Eventually remove old modules
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. MCP Tools Missing Several CLI Commands
|
|
||||||
|
|
||||||
**CLI Commands (20):**
|
|
||||||
1. ✅ create - Has MCP equivalent
|
|
||||||
2. ✅ config - Has MCP equivalent
|
|
||||||
3. ✅ scrape - Has MCP equivalent
|
|
||||||
4. ✅ github - Has MCP equivalent
|
|
||||||
5. ✅ package - Has MCP equivalent
|
|
||||||
6. ✅ upload - Has MCP equivalent
|
|
||||||
7. ✅ analyze - Has MCP equivalent (scrape_codebase)
|
|
||||||
8. ✅ enhance - Has MCP equivalent
|
|
||||||
9. ❌ enhance-status - **NO MCP equivalent**
|
|
||||||
10. ✅ pdf - Has MCP equivalent
|
|
||||||
11. ✅ unified - Has MCP equivalent (unified_scrape)
|
|
||||||
12. ✅ estimate - Has MCP equivalent
|
|
||||||
13. ✅ install - Has MCP equivalent
|
|
||||||
14. ❌ install-agent - **NO MCP equivalent**
|
|
||||||
15. ✅ extract-test-examples - Has MCP equivalent
|
|
||||||
16. ❌ resume - **NO MCP equivalent**
|
|
||||||
17. ❌ stream - **NO MCP equivalent**
|
|
||||||
18. ❌ update - **NO MCP equivalent**
|
|
||||||
19. ❌ multilang - **NO MCP equivalent**
|
|
||||||
20. ❌ quality - **NO MCP equivalent**
|
|
||||||
21. ✅ workflows - Has MCP equivalent
|
|
||||||
|
|
||||||
**Missing in MCP (7 commands):**
|
|
||||||
- `enhance-status` - Monitor background enhancement
|
|
||||||
- `install-agent` - Install to IDE agents (Cursor, etc.)
|
|
||||||
- `resume` - Resume interrupted jobs
|
|
||||||
- `stream` - Stream large files
|
|
||||||
- `update` - Incremental updates
|
|
||||||
- `multilang` - Multi-language docs
|
|
||||||
- `quality` - Quality scoring
|
|
||||||
|
|
||||||
**Impact:**
|
|
||||||
- Cannot use full functionality via MCP
|
|
||||||
- CLI and MCP have different capabilities
|
|
||||||
- Users restricted when using AI agents
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4. Create Command Does Not Use Unified Infrastructure
|
|
||||||
|
|
||||||
**Gap:** `create_command.py` routes to individual scrapers instead of using unified system
|
|
||||||
|
|
||||||
**Current flow:**
|
|
||||||
```
|
|
||||||
create_command.py → detects source → calls individual scraper
|
|
||||||
→ doc_scraper.main()
|
|
||||||
→ github_scraper.main()
|
|
||||||
→ pdf_scraper.main()
|
|
||||||
→ codebase_scraper.main()
|
|
||||||
```
|
|
||||||
|
|
||||||
**Gap:** Each scraper has its own argument parsing and workflow logic
|
|
||||||
|
|
||||||
**Impact:**
|
|
||||||
- Inconsistent argument handling
|
|
||||||
- Duplicated workflow code
|
|
||||||
- Harder to maintain
|
|
||||||
|
|
||||||
**Note:** This is partially mitigated by workflow_runner usage in individual scrapers
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. Conflict Detector Not Integrated with Unified Scraper
|
|
||||||
|
|
||||||
**Gap:** `conflict_detector.py` exists but may not be fully utilized
|
|
||||||
|
|
||||||
**Evidence:**
|
|
||||||
```python
|
|
||||||
# unified_scraper.py imports it:
|
|
||||||
from skill_seekers.cli.conflict_detector import ConflictDetector
|
|
||||||
|
|
||||||
# But check integration depth...
|
|
||||||
```
|
|
||||||
|
|
||||||
**Need to verify:**
|
|
||||||
- Does unified scraper actually run conflict detection?
|
|
||||||
- Are conflicts reported to users?
|
|
||||||
- Can users act on conflict reports?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟠 Medium Priority Gaps
|
|
||||||
|
|
||||||
### 6. Enhancement Workflow Engine vs Old Enhancers
|
|
||||||
|
|
||||||
**Gap:** `enhancement_workflow.py` (new) may not fully replace old enhancer usage
|
|
||||||
|
|
||||||
**enhancement_workflow.py:**
|
|
||||||
- Uses `UnifiedEnhancer` (new)
|
|
||||||
- Supports YAML workflow presets
|
|
||||||
- Sequential stage execution
|
|
||||||
|
|
||||||
**Old enhancers:**
|
|
||||||
- Direct class instantiation
|
|
||||||
- No workflow support
|
|
||||||
- Used in codebase_scraper, pattern_recognizer, etc.
|
|
||||||
|
|
||||||
**Impact:** Two enhancement systems running in parallel
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 7. Resume Command Limited Scope
|
|
||||||
|
|
||||||
**Gap:** `resume_command.py` only works with specific scrapers
|
|
||||||
|
|
||||||
**Questions:**
|
|
||||||
- Does resume work with unified scraper?
|
|
||||||
- Does resume work with PDF scraping?
|
|
||||||
- Is resume state stored consistently?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 8. Argument Parsing Duplication
|
|
||||||
|
|
||||||
**Gap:** Multiple argument parsers for similar functionality
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- `parsers/doc_parser.py`
|
|
||||||
- `parsers/github_parser.py`
|
|
||||||
- `parsers/pdf_parser.py`
|
|
||||||
- `parsers/create_parser.py`
|
|
||||||
- `arguments/` directory with multiple files
|
|
||||||
|
|
||||||
**Gap:** No unified argument validation across parsers
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟡 Minor Gaps
|
|
||||||
|
|
||||||
### 9. Storage Adapters Not Used in Core Flow
|
|
||||||
|
|
||||||
**Gap:** Cloud storage adapters exist but may not be integrated
|
|
||||||
|
|
||||||
```
|
|
||||||
storage/
|
|
||||||
├── base_storage.py
|
|
||||||
├── s3_storage.py
|
|
||||||
├── gcs_storage.py
|
|
||||||
└── azure_storage.py
|
|
||||||
```
|
|
||||||
|
|
||||||
**Check:** Are these actually used in CLI commands or just standalone?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 10. Benchmark Framework Underutilized
|
|
||||||
|
|
||||||
**Gap:** `benchmark/` module exists but may not be integrated into main flow
|
|
||||||
|
|
||||||
**Check:** Is benchmarking automatically run? Can users easily benchmark their skills?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 Gap Summary Matrix
|
|
||||||
|
|
||||||
| # | Gap | Severity | Files Affected | Effort to Fix |
|
|
||||||
|---|-----|----------|----------------|---------------|
|
|
||||||
| 1 | Unified scraper → workflow_runner | 🔴 Critical | unified_scraper.py | Medium |
|
|
||||||
| 2 | Duplicate enhancer classes | 🔴 Critical | 8 files import old | High |
|
|
||||||
| 3 | Missing MCP tools (7) | 🔴 Critical | MCP parity | Medium |
|
|
||||||
| 4 | Create command routing | 🟠 Medium | create_command.py | Medium |
|
|
||||||
| 5 | Conflict detector integration | 🟠 Medium | unified_scraper.py | Low |
|
|
||||||
| 6 | Old vs new enhancer systems | 🟠 Medium | Multiple | High |
|
|
||||||
| 7 | Resume scope | 🟠 Medium | resume_command.py | Low |
|
|
||||||
| 8 | Argument parsing duplication | 🟡 Minor | parsers/ | Medium |
|
|
||||||
| 9 | Storage adapters usage | 🟡 Minor | storage/ | Low |
|
|
||||||
| 10 | Benchmark integration | 🟡 Minor | benchmark/ | Low |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 Recommended Fixes (Priority Order)
|
|
||||||
|
|
||||||
### Phase 1: Critical (Immediate)
|
|
||||||
|
|
||||||
1. **Add workflow_runner to unified_scraper.py**
|
|
||||||
```python
|
|
||||||
from skill_seekers.cli.workflow_runner import run_workflows
|
|
||||||
|
|
||||||
# In main():
|
|
||||||
if args.enhance_workflow or args.enhance_stage:
|
|
||||||
context = run_workflows(...)
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Migrate old enhancer imports to unified_enhancer**
|
|
||||||
- Replace `from ai_enhancer import X` with `from unified_enhancer import X`
|
|
||||||
- Test all affected modules
|
|
||||||
- Add deprecation warnings to old modules
|
|
||||||
|
|
||||||
3. **Add missing MCP tools**
|
|
||||||
- `resume_tool` - Resume interrupted jobs
|
|
||||||
- `update_tool` - Incremental updates
|
|
||||||
- `quality_tool` - Quality scoring
|
|
||||||
- `stream_tool` - Streaming mode
|
|
||||||
- `multilang_tool` - Multi-language support
|
|
||||||
- `enhance_status_tool` - Monitor enhancement
|
|
||||||
- `install_agent_tool` - IDE agent installation
|
|
||||||
|
|
||||||
### Phase 2: Medium Priority
|
|
||||||
|
|
||||||
4. **Audit conflict_detector usage**
|
|
||||||
- Verify it's called in unified_scraper
|
|
||||||
- Add conflict reporting to output
|
|
||||||
|
|
||||||
5. **Consolidate argument parsing**
|
|
||||||
- Create shared argument definitions
|
|
||||||
- Use composition instead of duplication
|
|
||||||
|
|
||||||
### Phase 3: Cleanup
|
|
||||||
|
|
||||||
6. **Deprecate old enhancer modules**
|
|
||||||
```python
|
|
||||||
# In ai_enhancer.py, config_enhancer.py, guide_enhancer.py
|
|
||||||
import warnings
|
|
||||||
warnings.warn("This module is deprecated. Use unified_enhancer instead.", DeprecationWarning)
|
|
||||||
```
|
|
||||||
|
|
||||||
7. **Remove old modules** (after migration complete)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔍 Verification Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Check workflow_runner usage
|
|
||||||
grep -r "from.*workflow_runner" src/skill_seekers/cli/*.py
|
|
||||||
grep -r "run_workflows" src/skill_seekers/cli/*.py
|
|
||||||
|
|
||||||
# Check old enhancer imports
|
|
||||||
grep -r "from.*ai_enhancer\|from.*config_enhancer\|from.*guide_enhancer" src/skill_seekers/cli/*.py | grep -v "^src/skill_seekers/cli/\(ai_enhancer\|config_enhancer\|guide_enhancer\).py"
|
|
||||||
|
|
||||||
# Check MCP tools
|
|
||||||
grep -n "@mcp.tool\|def.*_tool" src/skill_seekers/mcp/server_fastmcp.py | wc -l
|
|
||||||
|
|
||||||
# Compare CLI vs MCP
|
|
||||||
skill-seekers --help | grep "^ [a-z]" | wc -l # 20 CLI commands
|
|
||||||
grep -c "@mcp.tool" src/skill_seekers/mcp/server_fastmcp.py # Should match
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Conclusion
|
|
||||||
|
|
||||||
The **biggest gaps** are:
|
|
||||||
|
|
||||||
1. **Unified scraper missing workflow support** - Critical for feature parity
|
|
||||||
2. **Old enhancer code still in use** - Technical debt, maintenance burden
|
|
||||||
3. **MCP missing 7 CLI commands** - Limits AI agent capabilities
|
|
||||||
|
|
||||||
These are **integration gaps in existing features**, not missing features. The functionality exists but isn't properly connected.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Analysis complete. Recommend Phase 1 fixes immediately.*
|
|
||||||
@@ -1,203 +0,0 @@
|
|||||||
## 🇨🇳 中文文档翻译 - 招募社区志愿者 / Chinese Documentation Translation - Call for Volunteers
|
|
||||||
|
|
||||||
### 📢 项目介绍 / Project Introduction
|
|
||||||
|
|
||||||
我们正在将 Skill Seekers 文档翻译成简体中文，需要社区志愿者参与审阅！
|
|
||||||
|
|
||||||
We're translating Skill Seekers documentation to Simplified Chinese and need community volunteers to help review!
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 🎯 目标 / Goal
|
|
||||||
|
|
||||||
将 **18 份文档**翻译成简体中文，并保持与英文版本同步。
|
|
||||||
|
|
||||||
Translate **18 documentation files** to Simplified Chinese and keep them in sync with English versions.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 📁 翻译范围 / Translation Scope
|
|
||||||
|
|
||||||
| 优先级 | 类别 | 文件数 | 状态 |
|
|
||||||
|--------|------|--------|------|
|
|
||||||
| P0 | 入门指南 | 4 | 🔍 待审阅 |
|
|
||||||
| P1 | 用户指南 | 6 | 🔍 待审阅 |
|
|
||||||
| P2 | 参考文档 | 4 | 🔍 待审阅 |
|
|
||||||
| P3 | 高级主题 | 4 | 🔍 待审阅 |
|
|
||||||
|
|
||||||
**总计：18 个文件**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 🤝 如何参与 / How to Participate
|
|
||||||
|
|
||||||
#### 方式 1：审阅自动翻译（推荐）/ Option 1: Review Auto-Translations (Recommended)
|
|
||||||
|
|
||||||
1. **查看 PR** - 我们会自动创建包含中文翻译的 PR
|
|
||||||
2. **阅读审阅** - 检查中文翻译的准确性和流畅性
|
|
||||||
3. **提出修改** - 在 PR 中评论建议的修改
|
|
||||||
4. **批准合并** - 确认无误后批准
|
|
||||||
|
|
||||||
#### 方式 2：直接翻译 / Option 2: Direct Translation
|
|
||||||
|
|
||||||
1. **认领文件** - 在下方评论认领要翻译的文件
|
|
||||||
2. **基于原文** - 使用英文原文进行翻译
|
|
||||||
3. **遵循标准** - 遵循下方的翻译标准
|
|
||||||
4. **提交 PR** - 提交翻译好的文档
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 📋 待审阅文件清单 / Files Pending Review
|
|
||||||
|
|
||||||
#### 入门指南 / Getting Started (P0)
|
|
||||||
|
|
||||||
| 文件 | 自动翻译 | 认领人 | 状态 |
|
|
||||||
|------|----------|--------|------|
|
|
||||||
| [README.md](../docs/zh-CN/README.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [getting-started/01-installation.md](../docs/zh-CN/getting-started/01-installation.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [getting-started/02-quick-start.md](../docs/zh-CN/getting-started/02-quick-start.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [getting-started/03-your-first-skill.md](../docs/zh-CN/getting-started/03-your-first-skill.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [getting-started/04-next-steps.md](../docs/zh-CN/getting-started/04-next-steps.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
|
|
||||||
#### 用户指南 / User Guide (P1)
|
|
||||||
|
|
||||||
| 文件 | 自动翻译 | 认领人 | 状态 |
|
|
||||||
|------|----------|--------|------|
|
|
||||||
| [user-guide/01-core-concepts.md](../docs/zh-CN/user-guide/01-core-concepts.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [user-guide/02-scraping.md](../docs/zh-CN/user-guide/02-scraping.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [user-guide/03-enhancement.md](../docs/zh-CN/user-guide/03-enhancement.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [user-guide/04-packaging.md](../docs/zh-CN/user-guide/04-packaging.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [user-guide/05-workflows.md](../docs/zh-CN/user-guide/05-workflows.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [user-guide/06-troubleshooting.md](../docs/zh-CN/user-guide/06-troubleshooting.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
|
|
||||||
#### 参考文档 / Reference (P2)
|
|
||||||
|
|
||||||
| 文件 | 自动翻译 | 认领人 | 状态 |
|
|
||||||
|------|----------|--------|------|
|
|
||||||
| [reference/CLI_REFERENCE.md](../docs/zh-CN/reference/CLI_REFERENCE.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [reference/MCP_REFERENCE.md](../docs/zh-CN/reference/MCP_REFERENCE.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [reference/CONFIG_FORMAT.md](../docs/zh-CN/reference/CONFIG_FORMAT.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [reference/ENVIRONMENT_VARIABLES.md](../docs/zh-CN/reference/ENVIRONMENT_VARIABLES.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
|
|
||||||
#### 高级主题 / Advanced (P3)
|
|
||||||
|
|
||||||
| 文件 | 自动翻译 | 认领人 | 状态 |
|
|
||||||
|------|----------|--------|------|
|
|
||||||
| [advanced/mcp-server.md](../docs/zh-CN/advanced/mcp-server.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [advanced/mcp-tools.md](../docs/zh-CN/advanced/mcp-tools.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [advanced/custom-workflows.md](../docs/zh-CN/advanced/custom-workflows.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
| [advanced/multi-source.md](../docs/zh-CN/advanced/multi-source.md) | ✅ | - | 🔍 待审阅 |
|
|
||||||
|
|
||||||
**状态说明：**
|
|
||||||
- 🔍 待审阅 / Pending review
|
|
||||||
- 🔄 审阅中 / In review
|
|
||||||
- ✅ 已完成 / Completed
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 📝 翻译标准 / Translation Standards
|
|
||||||
|
|
||||||
#### 技术术语 / Technical Terms
|
|
||||||
|
|
||||||
保持英文的术语 / Keep in English:
|
|
||||||
|
|
||||||
| 术语 | 说明 |
|
|
||||||
|------|------|
|
|
||||||
| CLI | 命令行界面 |
|
|
||||||
| API | 应用程序接口 |
|
|
||||||
| JSON | - |
|
|
||||||
| YAML | - |
|
|
||||||
| MCP | Model Context Protocol |
|
|
||||||
| URL | - |
|
|
||||||
| HTTP | - |
|
|
||||||
| skill | 第一次出现用"技能 (skill)"，之后用"技能" |
|
|
||||||
| workflow | 第一次出现用"工作流 (workflow)"，之后用"工作流" |
|
|
||||||
| scraper | 第一次出现用"抓取器 (scraper)"，之后用"抓取器" |
|
|
||||||
|
|
||||||
#### 代码示例 / Code Examples
|
|
||||||
|
|
||||||
**保持原样** - 所有代码示例、命令和文件路径保持英文：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 中文文档中仍然显示：
|
|
||||||
pip install skill-seekers
|
|
||||||
skill-seekers create https://docs.django.com/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 链接 / Links
|
|
||||||
|
|
||||||
内部链接指向中文版本：
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
<!-- 英文 -->
|
|
||||||
See [Installation Guide](01-installation.md)
|
|
||||||
|
|
||||||
<!-- 中文 -->
|
|
||||||
参见 [安装指南](01-installation.md)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 格式 / Formatting
|
|
||||||
|
|
||||||
- 保留所有 Markdown 格式
|
|
||||||
- 保留所有代码块
|
|
||||||
- 保留所有表格
|
|
||||||
- 保留所有列表
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 🏆 贡献奖励 / Rewards
|
|
||||||
|
|
||||||
- **README 致谢** - 在 README 中感谢所有贡献者
|
|
||||||
- **优先测试** - 优先获得新版本测试权限
|
|
||||||
- **社区徽章** - 获得社区贡献者徽章 🏅
|
|
||||||
- **GitHub Profile** - 在 GitHub 个人资料中展示贡献
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 📚 相关资源 / Resources
|
|
||||||
|
|
||||||
- **翻译计划详情：** [DOCUMENTATION_CHINESE_TRANSLATION_PLAN.md](../DOCUMENTATION_CHINESE_TRANSLATION_PLAN.md)
|
|
||||||
- **中文文档入口：** [docs/zh-CN/README.md](../docs/zh-CN/README.md)
|
|
||||||
- **英文原文：** [docs/README.md](../docs/README.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 💬 如何认领 / How to Claim
|
|
||||||
|
|
||||||
在此 Issue 下评论：
|
|
||||||
|
|
||||||
```
|
|
||||||
我想审阅：getting-started/02-quick-start.md
|
|
||||||
或
|
|
||||||
I want to review: user-guide/03-enhancement.md
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 🔔 自动更新通知 / Auto-Update Notifications
|
|
||||||
|
|
||||||
当英文文档更新时，GitHub Actions 会自动：
|
|
||||||
1. 翻译变更内容
|
|
||||||
2. 创建 PR
|
|
||||||
3. 在此 Issue 中通知
|
|
||||||
|
|
||||||
When English docs are updated, GitHub Actions will automatically:
|
|
||||||
1. Translate the changes
|
|
||||||
2. Create a PR
|
|
||||||
3. Notify in this Issue
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 📞 联系方式 / Contact
|
|
||||||
|
|
||||||
有问题？在此 Issue 下评论或联系：
|
|
||||||
|
|
||||||
Questions? Comment on this issue or contact:
|
|
||||||
- GitHub Issues: https://github.com/yusufkaraaslan/Skill_Seekers/issues
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 让我们一起打造完美的中文文档！
|
|
||||||
## Let's build perfect Chinese documentation together!
|
|
||||||
|
|
||||||
🚀🌐🇨🇳
|
|
||||||
Reference in New Issue
Block a user