Onboarding: liyupi/ai-guide

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/liyupi/ai-guide shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Missing license — unclear to depend on

• Last commit 6d ago
• 3 active contributors
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 81% of recent commits
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live liyupi/ai-guide repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/liyupi/ai-guide.

What it runs against: a local clone of liyupi/ai-guide — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in liyupi/ai-guide | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>liyupi/ai-guide</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of liyupi/ai-guide. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/liyupi/ai-guide.git
#   cd ai-guide
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of liyupi/ai-guide and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "liyupi/ai-guide(\\.git)?\\b" \\
  && ok "origin remote is liyupi/ai-guide" \\
  || miss "origin remote is not liyupi/ai-guide (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".vuepress/config.ts" \\
  && ok ".vuepress/config.ts" \\
  || miss "missing critical file: .vuepress/config.ts"
test -f ".vuepress/navbar.ts" \\
  && ok ".vuepress/navbar.ts" \\
  || miss "missing critical file: .vuepress/navbar.ts"
test -f ".vuepress/sidebar.ts" \\
  && ok ".vuepress/sidebar.ts" \\
  || miss "missing critical file: .vuepress/sidebar.ts"
test -f ".vuepress/scripts/generateSidebar.js" \\
  && ok ".vuepress/scripts/generateSidebar.js" \\
  || miss "missing critical file: .vuepress/scripts/generateSidebar.js"
test -f ".vuepress/theme/layouts/Layout.vue" \\
  && ok ".vuepress/theme/layouts/Layout.vue" \\
  || miss "missing critical file: .vuepress/theme/layouts/Layout.vue"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/liyupi/ai-guide"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

A comprehensive open-source AI knowledge base and documentation site built with VuePress, curated by YouTuber 鱼皮 (Li Yupi). It serves as a free learning platform covering AI tools (DeepSeek, GPT, Claude, Gemini), the 'Vibe Coding' (氛围编程) zero-to-hero tutorial for AI-assisted programming, prompt engineering, AI frameworks (Spring AI, LangChain), and practical guides for monetizing AI projects. The site has evolved from a Markdown document repository into a full-featured navigation/learning hub at ai.codefather.cn. Classic VuePress static site structure: .vuepress/config.ts is the main config file; .vuepress/theme/components/ contains custom Vue SFC components (Navbar, ExtraSidebar, PageSidebarToc); .vuepress/sidebars/ai.ts defines the sidebar navigation; scripts in .vuepress/scripts/ (generateSidebar.js, genReadme.js, formatMdContent.js) auto-generate site structure from Markdown files in the /AI directory; public assets and favicons in .vuepress/public/. Content is organized as static Markdown files (.md) that VuePress converts to HTML.

Who it's for

Developers (especially junior/non-technical users) wanting to learn AI-assisted programming ('Vibe Coding') without prerequisites; content creators and entrepreneurs seeking to monetize AI products; programmers exploring LLM tools (Cursor, Claude Code, GitHub Copilot); and Chinese-speaking tech learners looking for free, aggregated AI education materials.

Maturity & risk

Active and mature: 224KB+ of JavaScript, 41KB+ of Vue, well-structured VuePress 1.9.10 configuration, automated CI/CD pipelines (.github/workflows/ for deployment and content syncing), SEO plugins (Algolia, Baidu, sitemap), and an established audience (thousands of GitHub stars). Recent bundled configs suggest active updates; however, single-maintainer risk (鱼皮 as primary curator) and reliance on external content ingestion pipelines indicate it's more of a curated knowledge platform than a software product.

Low technical risk but moderate maintenance burden: VuePress 1.x is stable but not cutting-edge (v2 exists); dependencies are standard ecosystem tools (plugin-based architecture reduces coupling). Main risks are curator burnout (single maintainer, large content surface area), content staleness if sync workflows (.github/workflows/sync-vibe-coding-course.yml) fail, and potential SEO volatility. No test suite visible; relies on build-time validation scripts (.vuepress/scripts/) and manual review of Markdown content.

Active areas of work

Active content curation and sync: .github/workflows/sync-vibe-coding-course.yml indicates ongoing integration of the 'Vibe Coding' course material; multiple bundled configs suggest recent builds/deployments; formatMdContent.js and generateSidebar.js are being used to keep the site structure synchronized with content updates. No visible open PRs or GitHub issue data in the provided snippet, but the rapid bundled-config updates suggest frequent deployment cycles.

Get running

git clone https://github.com/liyupi/ai-guide.git
cd ai-guide
npm install
npm run generate:sidebar ./AI
npm run docs:dev

Then open http://localhost:8080 in your browser. The site will hot-reload as you edit Markdown files in the /AI directory.

Daily commands: Development: npm run docs:dev (starts VuePress dev server on :8080) Production build: npm run pre-docs:build && npm run docs:build (generates sidebar/readme, then builds static HTML to .vuepress/dist/) Serve built site: npm serve (runs a simple HTTP server on the dist folder)

Map of the codebase

• .vuepress/config.ts — Main VuePress configuration—defines site metadata, plugins, and theme settings that every contributor must understand to properly build and deploy the documentation site.
• .vuepress/navbar.ts — Navigation bar configuration—essential for understanding how documentation is organized and linked at the top level of the site.
• .vuepress/sidebar.ts — Sidebar navigation structure—defines the entire left-side menu hierarchy that routes users through the AI knowledge base content.
• .vuepress/scripts/generateSidebar.js — Automatic sidebar generation script—automatically builds navigation from the directory structure, so contributors must understand this to properly organize new content.
• .vuepress/theme/layouts/Layout.vue — Root Vue component for page layout—defines the overall structure (header, sidebar, content, footer) that wraps all documentation pages.
• .github/workflows/deploy.yml — CI/CD deployment pipeline—automates building and deploying the site; critical for understanding how changes reach production.

Components & responsibilities

• VuePress core + plugins (VuePress, Vue, webpack) — Renders markdown into HTML, manages routing, provides search and SEO features
  • Failure mode: Build fails if markdown has syntax errors or plugins are misconfigured; site is not deployable
• Build automation scripts —

How to make changes

Add a new AI application guide or tutorial

1. Create a new markdown file in the appropriate subdirectory under AI/AI应用场景/ (e.g., AI + 编程开发/) (AI/AI应用场景/AI + 编程开发/new-guide.md)
2. Write your markdown content following the existing format (title, sections, code examples) (AI/AI应用场景/AI + 编程开发/new-guide.md)
3. Run npm run generate:sidebar to automatically rebuild the sidebar navigation from the updated directory (.vuepress/scripts/generateSidebar.js)
4. Run npm run generate:readme to auto-generate index README files for the category (.vuepress/scripts/genReadme.js)
5. Test locally with npm run docs:dev, then commit and push to trigger the GitHub Actions deploy workflow (.github/workflows/deploy.yml)

Add a new AI industry news/update

1. Create a new markdown file in AI/AI行业资讯/YYYY-MM/ directory (e.g., 2025-02/) (AI/AI行业资讯/2025-02/new-news.md)
2. Write the news article with title, date, and key points (AI/AI行业资讯/2025-02/new-news.md)
3. Run npm run generate:sidebar to rebuild sidebar with the new article (.vuepress/scripts/generateSidebar.js)
4. Verify in npm run docs:dev and deploy via git push (automatic via GitHub Actions) (.github/workflows/deploy.yml)

Customize navigation or styling

1. Edit .vuepress/navbar.ts to add/modify top-level navigation links (.vuepress/navbar.ts)
2. Edit .vuepress/footer.ts to update footer content and social links (.vuepress/footer.ts)
3. Edit .vuepress/theme/styles/wrapper.styl for global CSS customizations (.vuepress/theme/styles/wrapper.styl)
4. Edit .vuepress/config.ts to modify VuePress theme configuration and plugin settings (.vuepress/config.ts)
5. Test locally with npm run docs:dev before committing (.vuepress/config.ts)

Why these technologies

• VuePress 1.9.10 — Static site generator optimized for markdown-based documentation with built-in SEO plugins and theme customization
• Vue.js (via VuePress theme) — Interactive components for sidebar, navbar, search, and custom layouts while maintaining static output
• Node.js build scripts (generateSidebar.js, genReadme.js) — Automate sidebar and README generation from directory structure to keep navigation in sync with content
• GitHub Actions — Automated CI/CD pipeline for building and deploying to production on every push to main branch
• Algolia Search (plugin) — Full-text search across all documentation pages without backend server

Trade-offs already made

• Static site generation (VuePress) instead of dynamic CMS

  • Why: Git-native content management, version control, and free hosting; lower infrastructure complexity
  • Consequence: Must rebuild and redeploy on every content change; no real-time updates; less flexible for complex queries

• Auto-generated sidebar and README from directory structure

  • Why: Reduces manual effort and keeps navigation always in sync with content organization
  • Consequence: File naming and folder structure become part of the API; renaming requires script re-runs

• Markdown-only content format

  • Why: Easy to write, version control friendly, and portable across platforms
  • Consequence: Limited rich media support; complex layouts require custom Vue components or HTML

Non-goals (don't propose these)

• This is not a real-time interactive learning platform—it is read-only documentation/knowledge base with no user accounts, quizzes, or progress tracking
• This is not a backend service or API—all content is statically generated and served as HTML/CSS/JS
• This does not manage API keys, credentials, or user data—it is a public documentation site with no authentication
• This does not index or crawl external AI tools in real-time—content is manually curated and updated by contributors

Traps & gotchas

1. Sidebar regeneration is required: The pre-docs:build script must run before docs:build; skipping it leaves old sidebar.ts in place. 2. Content directory assumption: The generate:sidebar and generate:readme scripts assume Markdown files exist in ./AI; if you reorganize content, update script paths. 3. VuePress 1.x asset handling: Static assets in .vuepress/public/ need explicit references in markdown or config (no automatic asset bundling). 4. Deployment base path: If the site doesn't deploy to the root (e.g., github.io/ai-guide), the base URL in config.ts must match or routes will 404. 5. Algolia search requires external setup: AlgoliaSearchBox.vue expects ALGOLIA_APP_ID and ALGOLIA_API_KEY env vars or config; without them, search is broken but site still builds.

Architecture

Concepts to learn

• Vibe Coding (氛围编程) — The central pedagogical concept of this repository; Vibe Coding is the practice of letting AI (via prompts and context) do most of the coding while humans guide direction — understanding this paradigm shift is key to grasping why the guide exists
• Prompt Engineering — Core skill for effective Vibe Coding; the guide extensively covers how to write effective prompts to steer AI models (DeepSeek, GPT, Claude) toward desired outputs
• Context Management in LLMs — Advanced technique specific to Vibe Coding; the guide teaches how to structure conversation history and file context to avoid hallucinations and maintain code coherence across multi-turn interactions
• Retrieval-Augmented Generation (RAG) — Covered in the AI knowledge encyclopedia; RAG is how AI systems fetch external knowledge (documentation, codebase) to ground responses, relevant to building custom AI tools mentioned in the guide
• Multi-turn conversation design — The guide emphasizes how to structure multi-turn interactions with AI (Cursor, Claude) to iteratively refine code; this is distinct from single-prompt usage and requires understanding conversation state and feedback loops
• Static Site Generation (SSG) with VuePress — The entire site is built via VuePress SSG; understanding how Markdown → HTML transformation works is crucial for contributing content and debugging build failures
• Product monetization strategies for AI tools — The guide includes a section on turning AI-built products into revenue (SaaS, one-time sales, API services); this goes beyond coding and into business strategy, reflecting the guide's holistic approach

Related repos

• vuejs/vuepress — The core static site generator this project is built on; understanding VuePress plugins and theme structure is essential for customizing this site
• docsify/docsify — Alternative lightweight documentation site generator; if you want to fork this knowledge base with a different build system, docsify is a common choice
• liyupi/code-nav — Sister project by the same author (Li Yupi); a web-based navigator for coding resources, shares similar curation philosophy and audience
• liyupi/codefather — Companion project by Li Yupi; 'CodeFather' brand encompasses multiple educational resources, and this AI guide is part of that ecosystem
• chatchat-space/Langchain-Chatchat — Popular LangChain + LLM Q&A system in Chinese; relevant to AI knowledge base content (RAG, LangChain frameworks covered in this guide)

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add automated sidebar generation validation workflow

The repo has a generateSidebar.js script that manually generates sidebars, but no CI workflow validates that the sidebar matches the actual directory structure. This causes sidebar desync issues when contributors add files without regenerating. Add a GitHub Action that runs on PR to validate sidebar consistency against the AI/ directory structure.

• [ ] Create .github/workflows/validate-sidebar.yml that runs npm run generate:sidebar ./AI on each PR
• [ ] Compare generated sidebar output against .vuepress/sidebars/ai.ts to detect mismatches
• [ ] Add check to ensure all .md files in AI/ directory are referenced in the sidebar config
• [ ] Add PR comment notification if sidebar generation is needed

Implement automated README synchronization for subdirectory changes

The repo has genReadme.js to generate READMEs, but the sync workflow at .github/workflows/sync-vibe-coding-course.yml only handles Vibe Coding course. Create a general-purpose workflow that auto-generates category READMEs (e.g., AI/AI应用场景/README.md) whenever files are added/modified in those directories, improving navigation and discoverability.

• [ ] Create .github/workflows/sync-category-readmes.yml triggered on changes to AI/**/*.md files
• [ ] Enhance .vuepress/scripts/genReadme.js to support generating category-level READMEs with file listings and metadata
• [ ] Add logic to extract frontmatter/first-line titles from .md files to populate category README tables
• [ ] Commit auto-generated READMEs back to PR branch for contributor review

Add SEO metadata validation and enforcement in pre-build checks

The project uses SEO and Sitemap plugins but has no validation that markdown files contain recommended metadata (title, description, keywords, tags). This reduces SEO effectiveness inconsistently. Add a pre-build script that validates all .md files contain proper frontmatter and suggests improvements.

• [ ] Create .vuepress/scripts/validateSeoMetadata.js to check for required frontmatter fields (title, description, tags) in all .md files
• [ ] Integrate validation into pre-docs:build npm script before sidebar/README generation
• [ ] Generate a report identifying files missing metadata, with suggested fixes
• [ ] Add .github/workflows/seo-validation.yml to warn on PR if critical metadata is missing from new/modified files

Good first issues

• Add missing unit tests for .vuepress/scripts/generateSidebar.js and generateReadme.js: these critical build scripts lack test coverage, making refactoring risky. Create a test/ directory with Jest or Mocha tests covering edge cases like nested directories, missing files, and malformed Markdown.
• Improve Markdown content validation in the pre-build step: formatMdContent.js exists but the build doesn't validate frontmatter, broken links, or missing headers. Add a linting step (e.g., remark-lint) to catch common issues before deployment.
• Document the sidebar and navbar configuration structure: .vuepress/sidebar.ts and navbar.ts are auto-generated/manually maintained but lack inline comments or a README explaining how to add new sections, adjust ordering, or link to external resources.

Top contributors

• @yupi-translate-app[bot] — 81 commits
• @liyupi — 18 commits
• @cq2021-coder — 1 commits

Recent commits

• 1ce719f — docs: 新增 4 篇文章并更新教程体系 (liyupi)
• 420d316 — docs: 整合 7 篇新文章到教程体系，新增概念条目和创意项目 (liyupi)
• 12d80d2 — docs: 新增 AI 万能视频下载总结器项目实战 + GEO 文章 + 概念大全扩充 (liyupi)
• b0a8343 — docs: 新增 OpenClaw 接入微信保姆级教程，纳入教程体系 (liyupi)
• 0d5a17e — docs: 新增 OpenClaw 一键卸载脚本教程，纳入保姆级教程体系 (liyupi)
• 25344d3 — docs: OpenClaw 教程每篇标题和文件名统一加上 OpenClaw 关键词 (liyupi)
• a9f033c — docs: 新增 OpenClaw 保姆级教程系列，17 篇从入门到进阶的完整教程 (liyupi)
• 3c34dc6 — docs: 新增 OpenClaw 保姆级安装教程，作为编程工具板块第 7 篇主线文章 (liyupi)
• 940b852 — docs: 更新 Vibe Coding 成本控制技巧文章内容 (liyupi)
• 94a7c0a — docs: 新增 AI 热点监控、GitHub 文档翻译、AI 塔罗占卜项目实战文章，完善教程体系 (liyupi)

Security observations

This is a documentation website with moderate security concerns. The primary issue is the use of significantly outdated dependencies (VuePress 1.9.10 with end-of-life status) which likely contains known vulnerabilities. The project lacks visible security header configuration and proper dependency management practices. While the codebase appears to be primarily static content without database or authentication components, the outdated dependency chain presents significant risk. Immediate actions should include upgrading VuePress to v2.x, auditing third-party plugins, reviewing shell scripts for injection risks, and implementing security headers. The repository structure is generally safe from common web vulnerabilities due to its static nature, but infrastructure hardening is needed.

• High · Outdated VuePress Dependencies — package.json - devDependencies. The project uses VuePress 1.9.10 and associated plugins that are significantly outdated. VuePress 1.x reached end-of-life and may contain known security vulnerabilities. Newer versions (VuePress 2.x) include security patches and improvements. Fix: Upgrade to VuePress 2.x and update all associated plugins to their latest versions. Review the VuePress migration guide for compatibility changes.
• Medium · Unverified Third-Party Plugins — package.json - devDependencies and dependencies. The project includes several third-party VuePress plugins (baidu-autopush, feed, seo, sitemap, tags, code-copy, img-lazy) with minimal version pinning. Some plugins like 'vuepress-plugin-baidu-autopush' may have limited maintenance or security oversight. Fix: Audit each plugin for active maintenance and known vulnerabilities. Consider using npm audit and Snyk to identify issues. Pin exact versions and establish a dependency update schedule.
• Medium · Potential XSS Risk in Vue Components — .vuepress/theme/components/. Custom Vue theme components exist (.vuepress/theme/components/) but the code content is not visible. Vue components that dynamically render user-generated content or markdown could be vulnerable to XSS if not properly sanitized. Fix: Ensure all dynamic content rendering uses Vue's built-in escaping. Avoid using v-html with untrusted content. Sanitize markdown output using libraries like DOMPurify if rendering user input.
• Medium · Scripts with Potential Security Risks — .vuepress/scripts/. Several Node.js scripts in .vuepress/scripts/ (formatMdContent.js, send-email.js, genReadme.js) are present but their content is not visible. These scripts may contain hardcoded credentials, unsafe file operations, or command injection vulnerabilities. Fix: Review all scripts for: hardcoded credentials/API keys, unsafe file/directory operations, lack of input validation, and command injection risks. Use environment variables for sensitive data. Implement proper error handling.
• Low · Bundled Configuration Files in Repository — .vuepress/config.bundled_*.mjs files. Multiple bundled config files exist (.vuepress/config.bundled_*.mjs) which appear to be generated artifacts. These should typically not be committed to version control. Fix: Add these bundled files to .gitignore. Use a build process to generate these files as needed. Keep only the source config.ts in version control.
• Low · Public Verification Files Exposed — .vuepress/public/. Bing and Baidu verification files are committed to the repository (.vuepress/public/BingSiteAuth.xml, baidu_verify_*.html). While not critical, these should ideally be handled through hosting platform settings rather than repository. Fix: Consider moving verification files to the hosting platform's configuration system if available, rather than committing them to the repository.
• Low · Missing Security Headers Configuration — .vuepress/config.ts. No visible security headers configuration (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in VuePress config files. The project serves a documentation website that should have security headers. Fix: Configure security headers in the VuePress config or web server. Implement Content Security Policy (CSP), X-Frame-Options, X-Content-Type-Options, and other OWASP recommended headers.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.