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/chyingp/nodejs-learning-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.

WAIT — Stale — last commit 3y ago

• 6 active contributors
• Other licensed
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected

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

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

What it runs against: a local clone of chyingp/nodejs-learning-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 chyingp/nodejs-learning-guide | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1022 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of chyingp/nodejs-learning-guide. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/chyingp/nodejs-learning-guide.git
#   cd nodejs-learning-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 chyingp/nodejs-learning-guide and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

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

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "SUMMARY.md" \\
  && ok "SUMMARY.md" \\
  || miss "missing critical file: SUMMARY.md"
test -f "book.json" \\
  && ok "book.json" \\
  || miss "missing critical file: book.json"
test -f "examples/2016.11.07-advanced-express-multer/package.json" \\
  && ok "examples/2016.11.07-advanced-express-multer/package.json" \\
  || miss "missing critical file: examples/2016.11.07-advanced-express-multer/package.json"
test -f "examples/2016.11.08-node-http/http.js" \\
  && ok "examples/2016.11.08-node-http/http.js" \\
  || miss "missing critical file: examples/2016.11.08-node-http/http.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1022 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~992d)"
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/chyingp/nodejs-learning-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).

A comprehensive Chinese-language learning guide for Node.js core modules and advanced patterns, structured as an interactive GitBook with ~30 documented modules (zlib, fs, dns, http, crypto, stream, cluster, etc.) and 50+ runnable example directories. It teaches both foundational APIs (with inline demos) and production patterns (Express middleware, file uploads with multer, session auth, logging with morgan/log4js). Single-package structure: /examples contains 10+ dated directories (e.g., examples/2016.11.03-node-dns/, examples/2016.11.07-advanced-express-multer/) with self-contained runnable .js files, paired with /docs (or inline in repo root) containing Markdown documentation. GitBook config (_config.yml, book.json, SUMMARY.md) structures the docs as a navigable online book at docs.chyingp.com; assets/ holds diagrams (cluster.mdj, session-lifecycle PNGs) and media.

Chinese-speaking Node.js developers (especially junior engineers and bootcamp graduates) who need concrete, working examples of built-in module APIs and real-world patterns like authentication, file handling, compression, and process clustering—the repo is maintained as a public knowledge base by a WeChat public account "程序猿小卡" (Programmer Xiaoka).

Actively maintained educational content, not a production library. The repo has been built incrementally since ~2016 with comprehensive coverage of Node.js core APIs (marked "ok" in SUMMARY.md for ~25 modules), but there are no automated tests, CI/CD pipelines, or version releases—it's a documentation project with executable examples rather than a package meant for dependency installation.

Very low risk as a learning resource since it's not a dependency—you consume examples, not import it. Risks: (1) Node.js API docs it mirrors may drift (e.g., deprecated APIs not updated), (2) old example code (earliest commits ~2016) may use outdated patterns (e.g., callbacks vs. promises/async-await), (3) single maintainer (@chyingp) with no visible CI, so submitted PRs may have slow turnaround.

No visible active development in the provided snapshot—repo appears to be in maintenance mode as a reference guide. The README mentions 2023 internship recruitment (likely outdated), suggesting last updates were several years ago. No pending PRs, open issues, or recent commits are evident from the file list.

Clone the repo and navigate to a specific example: git clone https://github.com/chyingp/nodejs-learning-guide.git && cd nodejs-learning-guide/examples/2016.11.03-node-dns && node lookup.js. For Express examples: cd examples/2016.11.07-advanced-express-multer && npm install && node app.js, then visit http://localhost:3000.

Daily commands: Per-example basis. Core examples: (1) DNS: node examples/2016.11.03-node-dns/lookup.js; (2) Compression: node examples/2016.11.03-node-zlib/gzip.js; (3) Express+multer: cd examples/2016.11.07-advanced-express-multer && npm install && npm start (if start script defined, else node app.js). Docs are read-only; to view online, visit the GitBook at docs.chyingp.com or build locally with gitbook install && gitbook serve.

• README.md — Entry point documenting the entire learning guide structure, module organization, and how to navigate the 600+ files of Node.js examples and tutorials.
• SUMMARY.md — Table of contents mapping all learning modules and examples; essential for understanding the repo's logical organization across core modules, networking, and advanced topics.
• book.json — GitBook configuration file that defines how the learning guide is published and organized; critical for maintaining documentation build pipeline.
• examples/2016.11.07-advanced-express-multer/package.json — Representative example of dependencies used across the learning guide; shows Express and Multer setup patterns replicated throughout the codebase.
• examples/2016.11.08-node-http/http.js — Core HTTP module example demonstrating Node.js built-in networking fundamentals; foundational for understanding server implementation patterns throughout the guide.
• examples/2016.11.16-node-net/basic/server.js — Low-level TCP socket example showing Net module usage; demonstrates network programming concepts that underpin higher-level HTTP examples.
• _config.yml — Static site configuration for Jekyll/GitBook rendering; controls site metadata, theme, and publication settings for the learning guide.

• Built-in Module Examples (Node.js built-in modules) — Demonstrate core Node.js APIs (http, net, fs, zlib, dns, crypto, buffer, etc.) with minimal external dependencies
  • Failure mode: Examples break if Node.js core API changes; outdated version may not reflect current semver
• Express + Multer Examples (Express 4.14.0, Multer 1.2.0) — Show web server and file upload patterns using third-party dependencies; real-world application context
  • Failure mode: Examples may fail if dependencies update incompatibly; Multer API changes break upload handlers
• Documentation Layer (GitBook, Jekyll, Markdown) — Narrative guides in markdown explaining each module, pattern, and best practice; indexed via SUMMARY.md
  • Failure mode: Broken links in table of contents; orphaned or outdated documentation files

Add a new built-in module example

1. Create a new directory under examples/ with date prefix (e.g., examples/2016.11.XX-node-modulename/) (examples/)
2. Create executable .js files demonstrating the module's key APIs (examples/2016.11.XX-node-modulename/example.js)
3. Add module documentation in the 模块/ directory with markdown file (模块/modulename.md)
4. Update SUMMARY.md to include new module in the table of contents (SUMMARY.md)

Add a new Express framework pattern example

1. Create directory under examples/2016.11.07-advanced-express-multer/ or sibling date-versioned directory (examples/2016.11.07-advanced-express-multer/)
2. Create app.js with Express server setup and route handlers (examples/2016.11.07-advanced-express-multer/app.js)
3. Create form.html or other HTML/client files demonstrating the pattern (examples/2016.11.07-advanced-express-multer/form.html)
4. Add package.json with required dependencies (express, any middleware) (examples/2016.11.07-advanced-express-multer/package.json)

Add a networking (HTTP/TCP) example

1. Create or use existing directory under examples/2016.11.08-node-http/ or examples/2016.11.16-node-net/ (examples/2016.11.08-node-http/)
2. Create server.js implementing the network pattern (HTTP handler or TCP listener) (examples/2016.11.08-node-http/server/eventRequest.js)
3. Create client.js or request file demonstrating client-side interaction (examples/2016.11.08-node-http/client/requestGet.js)
4. Update README.md or relevant module documentation in 模块/ directory (README.md)

• Node.js built-in modules (http, net, fs, zlib, crypto, etc.) — Core learning objectives; examples demonstrate how to use Node.js internal APIs directly without external frameworks
• Express.js — Industry-standard web framework; used in advanced examples to show practical patterns like file uploads with Multer
• GitBook — Documentation platform enabling structured, navigable learning guide with version control integration
• Multer — Demonstrates middleware pattern for handling file uploads in Express; key real-world Node.js use case

• 100+ standalone example files rather than single monolithic project

  • Why: Isolates each concept for focused learning; readers can copy/run individual examples without dependency bloat
  • Consequence: No shared codebase across examples; duplication of boilerplate; harder to show how modules integrate in large systems

• Mix of built-in module examples and third-party framework examples (Express)

  • Why: Covers both foundational Node.js knowledge and practical framework usage needed for real-world applications
  • Consequence: Scope complexity; requires learners to understand both low-level and high-level abstractions

• Documentation-first approach (GitBook) with example code as secondary artifacts

  • Why: Aligns with learning guide intent: structured narrative with supporting code samples
  • Consequence: Code examples may become outdated faster than documentation; examples may not reflect latest library versions

• Does not provide a production-ready framework or application template
• Does not include automated test suite or test patterns (mentioned in some package.json files but not demonstrated)
• Does not cover frontend frameworks or client-side JavaScript
• Does not provide deployment or DevOps automation guides beyond high-level documentation mentions
• Does not include performance benchmarks or optimization guides
• Does not demonstrate database integration patterns

No obvious hidden traps—this is a documentation repo, not a runtime application. Gotchas: (1) Examples assume Node.js versions from 2016–2017 era; APIs like fs.promises or async/await patterns are either absent or minimal, (2) some examples may require specific file system state (e.g., examples/2016.11.03-node-zlib/extra/ has pre-existing .gz files), (3) GitBook build requires Ruby (Gemfile present) or Node-based gitbook-cli, (4) multer examples write to disk—ensure upload/ directories are writable.

• Stream backpressure & highWaterMark — Core to efficient file I/O and HTTP handling in Node.js examples; misunderstanding leads to memory leaks when piping large files
• Event emitter pattern (EventEmitter) — Foundational to all async operations in Node.js (HTTP, streams, child processes); the events module is core to understanding how this repo's examples work
• Buffer encoding (UTF-8, Base64, hex) — String/binary conversion is critical for crypto, compression, and file operations; charset mismatches are a common production bug this repo explicitly addresses
• Express middleware chain & req/res lifecycle — Used in 15+ advanced examples (multer, body-parser, morgan, cookie-parser); understanding middleware order is essential for real applications
• Child processes & IPC (Inter-Process Communication) — cluster.js examples show how Node.js achieves multi-core scaling; IPC messages are how the master communicates with workers
• Symmetric vs. asymmetric encryption (RSA, ECDSA, AES) — crypto module covers both; learners need to know when to use each (passwords → hashing, data → symmetric, key exchange → asymmetric)
• DNS resolution (lookup vs. resolve4 vs. resolveCname) — Subtle differences (blocking vs. async, system getaddrinfo vs. DNS server query) are explained with examples; critical for networked apps

• nodejs/node — Official Node.js repository; this guide documents its built-in modules and their APIs
• goldbergyoni/nodebestpractices — Comprehensive best practices guide for Node.js (in English); complements this repo's module fundamentals with production patterns like error handling and testing
• expressjs/express — The Express.js framework is central to 50+ examples in this guide; source reading helps understand middleware and routing deeply
• mysqljs/mysql — A commonly paired dependency for Node.js backends; many learners from this guide will want to see how to query databases using the patterns taught here
• wuyuan1992/nodejs-learning — Similar Chinese Node.js learning guide; alternative resource for comparative learning and cross-referencing explanations

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 missing documentation for crypto module completion

The README.md shows '数据加密-crypto(OK)' is cut off mid-line, and there's no 模块/crypto.md file listed in the structure. This is a core Node.js module that should have comprehensive documentation like the other completed modules (zlib, dns, http, net, dgram, url). This would complete the internal modules section.

• [ ] Create 模块/crypto.md with sections covering: hash functions, HMAC, cipher/decipher, and key generation
• [ ] Add 5-7 runnable examples to examples/2016.11.XX-node-crypto/ directory (covering md5, sha256, AES encryption, key derivation)
• [ ] Update SUMMARY.md to include the new crypto module documentation link
• [ ] Update README.md to complete the cut-off crypto line with proper markdown formatting

Create integration examples for common Express + Node patterns

The repo has isolated examples for multer, http, zlib, etc., but lacks end-to-end examples combining multiple modules (e.g., file upload with compression, HTTPS server with crypto). Contributors could add practical full-stack examples that demonstrate real-world patterns using multiple internal modules together.

• [ ] Create examples/2016.11.XX-express-secure-upload/ with file upload + compression + crypto hash verification
• [ ] Create examples/2016.11.XX-https-server/ demonstrating https module with certificate handling and crypto
• [ ] Add README.md to each example directory explaining the pattern and which modules are used
• [ ] Reference these integration examples in the main README.md under a new 'Advanced Patterns' section

Add package.json and execution instructions to all example directories

Many example directories (like examples/2016.11.03-node-dns/ and examples/2016.11.08-node-http/) lack package.json files and clear run instructions. This creates friction for learners trying to execute examples. Standardizing this across all ~12 example directories would improve the learning experience.

• [ ] Add package.json to examples/2016.11.03-node-dns/, examples/2016.11.03-node-zlib/, examples/2016.11.08-node-http/, examples/2016.11.08-node-http/client/, and examples/2016.11.08-node-http/server/
• [ ] Create README.md in each example directory with: purpose, dependencies, and 'How to Run' instructions (e.g., 'node filename.js' or 'npm install && npm start')
• [ ] Update root README.md with a 'Running Examples' section explaining the consistent structure

• Add a runnable crypto RSA/ECDSA example under examples/crypto-asymmetric/ to complement the existing MD5 and symmetric examples referenced in 进阶/asymmetric-enc-dec.md—many learners struggle with key generation and signing
• Create an examples/2024.XX.XX-stream-pipeline directory with concrete, annotated examples of .pipe() chains (readable → transform → writable) matching the stream.md docs, since stream mechanics are conceptually hard without visual examples
• Audit and update SUMMARY.md to mark which modules are fully working (ok) vs. incomplete—several entries lack (ok) status, and comments in the file suggest error handling and global object docs are stub sections

This codebase is primarily an educational learning guide with example code. The main security concerns are: (1) Severely outdated dependencies (express 4.14.0 from 2015, multer 1.2.0 from 2016) with known vulnerabilities, (2) Missing security middleware and headers implementation, (3) Potential lack of input validation and file upload security measures in example code, (4) No visible CSRF protection. As this is a learning repository, the examples lack production-ready security hardening. For any real-world use, all dependencies must be updated immediately, and security best practices (input validation, CSRF protection,

• High · Outdated Express Dependency — examples/2016.11.07-advanced-express-multer/package.json. The package.json specifies express ^4.14.0, which was released in November 2015. This version is severely outdated and contains multiple known security vulnerabilities including HTTP response splitting, open redirect, and middleware bypass issues. Fix: Update express to the latest stable version (4.18.x or 5.x). Run 'npm update express' or manually specify a more recent version like '^4.18.2'.
• High · Outdated Multer Dependency — examples/2016.11.07-advanced-express-multer/package.json. The package.json specifies multer ^1.2.0, released in August 2016. This version is outdated and may contain security vulnerabilities related to file upload handling, including potential directory traversal issues. Fix: Update multer to the latest stable version (1.4.5 or higher). Run 'npm update multer' or specify '^1.4.5' or higher.
• Medium · Missing File Upload Validation in Multer Examples — examples/2016.11.07-advanced-express-multer/*/app.js. The multer example files (upload-single/app.js, upload-multi/app.js, upload-custom-filename/app.js) are not visible in the provided content, but multer configurations often lack proper file type validation, file size limits, and filename sanitization, which could lead to security issues. Fix: Implement file validation: (1) Set fileFilter to whitelist allowed MIME types, (2) Enforce maxFileSize limits, (3) Sanitize uploaded filenames to prevent directory traversal attacks, (4) Use diskStorage with safe destination and filename handlers.
• Medium · Potential XSS Risk in HTML Forms — examples/2016.11.07-advanced-express-multer/*/form.html. Multiple form.html files exist in upload examples. Forms may not properly escape or sanitize user input before processing, and corresponding Express handlers may render user input without proper escaping. Fix: Ensure all user input is properly escaped before rendering in HTML responses. Use template engines with auto-escaping (like EJS with default settings) or implement explicit HTML entity encoding.
• Medium · No CSRF Protection Configuration — examples/2016.11.07-advanced-express-multer/. The example applications contain HTML forms without visible CSRF token implementation. Express applications should include CSRF protection middleware, especially for file upload operations. Fix: Implement CSRF protection using middleware like 'csurf'. Add CSRF tokens to all state-changing forms and validate them on the server side.
• Low · No Security Headers Configuration — examples/2016.11.07-advanced-express-multer/app.js and all other Express examples. The example Express applications do not appear to implement security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) based on the file structure. Fix: Implement security headers using middleware like 'helmet'. This will add critical security headers to all HTTP responses.
• Low · Missing Input Validation on HTTP Endpoints — examples/2016.11.08-node-http/ and examples/2016.11.07-advanced-express-multer/. HTTP examples and multer examples may process user input without proper validation, particularly query parameters and POST body data. Fix: Implement input validation using libraries like 'joi', 'express-validator', or 'validator.js'. Validate all user inputs before processing.

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

• 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.