[{"content":"Overview of Three Sharing Modes Mode Also Known As Description Proxy Sharing Mode Allow LAN Devices forward requests through proxy software Gateway Sharing Mode Bypass Gateway, Transparent Proxy Devices point their gateway to the proxy host Routing Sharing Mode WiFi Hotspot Host creates an independent subnet and assigns IPs Overview diagram: Proxy Sharing Mode How It Works Suppose your computer is running Clash or V2Ray with proxy sharing enabled. You can set up your phone to route its requests through your computer. The flow is as follows:\nPhone access request → Computer (processed by V2Ray/Clash) → Gateway (Router) → Internet Internet response → Gateway (Router) → Computer → Phone This is how proxy sharing mode works.\nExample: Phone Accessing the Internet Through Computer Proxy In V2Ray, enable LAN connections to see the SOCKS5 and HTTP ports The computer uses HTTP proxy, so port 10809 is used\nCheck the WiFi connection info on your phone to get its IP address Enter the phone\u0026rsquo;s IP and port in your computer\u0026rsquo;s proxy settings Now your computer\u0026rsquo;s requests will be handled by your phone—your computer can access Google. If you turn off the phone\u0026rsquo;s VPN, the computer loses access too.\nExample: Computer Proxying Phone Requests (Reverse) The reverse setup—using your computer to proxy your phone\u0026rsquo;s requests—works the same way:\nOpen V2Ray settings and allow LAN connections The proxy port is displayed in the lower-left corner Go to your phone\u0026rsquo;s WiFi proxy settings, enter the computer\u0026rsquo;s IP as the server address and the port shown in the screenshot\nAbout UDP Proxy Note: The system proxy configured in phone settings is typically an HTTP proxy, which does not support UDP transport. To proxy UDP traffic, you need a SOCKS proxy. Since system proxy settings don\u0026rsquo;t support SOCKS, you\u0026rsquo;ll need a third-party VPN tool.\nCreate a SOCKS proxy in V2Ray on your phone:\nServer: Enter your computer\u0026rsquo;s IP address Port: Enter your computer\u0026rsquo;s V2Ray SOCKS port This allows UDP data to be proxied. However, whether UDP proxying actually works depends on whether your server node supports UDP.\nPros and Cons Pros:\nAlmost all proxy tools support enabling proxy sharing mode Cons:\nEach network device needs to be configured individually Some devices (e.g., TV boxes) don\u0026rsquo;t support proxy configuration, making this method unusable for them Gateway Sharing Mode How It Works Gateway sharing mode is also called bypass gateway, transparent proxy, or transparent gateway.\nTypically, the router assigns IPs to each device. In gateway mode, the router assigns the computer\u0026rsquo;s IP to every device as their gateway.\nWorkflow: When your phone wants to access Google → data is sent to the gateway (the computer) → the computer processes the data and forwards it to the router\nKey point: All internet traffic from devices on the LAN goes through the gateway.\nPros and Cons Advantages:\nFlexible configuration—you can set the gateway individually per device, or have the router change the gateway for all devices on the LAN at once The biggest advantage: a gateway-level system proxy can intercept all traffic on the system. Even if some applications don\u0026rsquo;t use a proxy or certain devices don\u0026rsquo;t support proxy settings, any internet access still passes through the gateway. The devices themselves don\u0026rsquo;t even know they\u0026rsquo;re being proxied This is why it\u0026rsquo;s called transparent proxy or transparent gateway Disadvantages:\nNot all operating systems support it. Windows does not support this mode; macOS and Linux do Implementation via Linux Virtual Machine Since Windows doesn\u0026rsquo;t support gateway sharing mode, you can install a Linux virtual machine to achieve it.\nUse bridged networking for the VM (same LAN as the host) Enable the root user Enable IP forwarding and TUN mode: 1 sysctl -w net.ipv4.ip_forward=1 Go to your computer\u0026rsquo;s IP settings and set the default gateway to the Linux VM\u0026rsquo;s IP address Limitation: This won\u0026rsquo;t work without a LAN.\nRouting Sharing Mode How It Works When routing sharing mode is enabled, the computer creates an independent subnet (shown as 192.168.137.1 in green in the diagram). When other devices connect to this computer, the computer assigns them IPs, gateways, and other network info. The computer essentially takes over the router\u0026rsquo;s job—hence the name routing sharing mode.\nPros and Cons Pros:\nMany advantages, widely applicable Cons:\nAdds an extra NAT layer, requiring some performance overhead Creates two different LAN segments that cannot communicate with each other by default Most phones don\u0026rsquo;t support sharing VPN networks through routing mode without Root access Configuration on Windows Enabling routing sharing mode on Windows requires two network interfaces. Most computers have only one, so you may need to purchase a USB Ethernet adapter to add an extra port.\nSetup steps:\nAssume the first NIC connects to your LAN and the second is idle Enable TUN mode Clash will create a virtual network adapter Right-click the virtual adapter → Properties → Sharing → Select \u0026ldquo;Allow other network users\u0026hellip;\u0026rdquo; and choose the idle NIC This creates a new subnet, sharing Clash\u0026rsquo;s proxy environment with the idle NIC Use Cases This idle NIC can be connected to another computer via an Ethernet cable, and that computer can access the internet through the proxy without any configuration. A more common scenario is connecting it to a wireless access point (AP) to broadcast WiFi.\n","date":"2026-06-11T23:00:00+08:00","image":"/p/%E7%A7%91%E5%AD%A6%E4%B8%8A%E7%BD%91%E7%8E%AF%E5%A2%83%E5%85%B1%E4%BA%AB%E6%96%B9%E5%BC%8F/cover.svg","permalink":"/en/p/%E7%A7%91%E5%AD%A6%E4%B8%8A%E7%BD%91%E7%8E%AF%E5%A2%83%E5%85%B1%E4%BA%AB%E6%96%B9%E5%BC%8F/","title":"Methods for Sharing VPN and Proxy Connections Across Devices"},{"content":"Background Running out of space on the C drive is a classic pain point for Windows users. The usual culprits are:\nWeChat/QQ chat history and file caches (easily tens of GB) Browser caches and user data Global caches from package managers (pip, npm, conda, cargo, etc.) Default installation/data directories for Adobe, Office, games, and other large software Windows update leftovers and temporary files Most of these programs default to writing data to the C drive and don\u0026rsquo;t provide an option to change the path. Reinstalling software or editing the registry is both troublesome and risky.\nThe mklink command offers an elegant solution — store the data on your D or E drive, while the software \u0026ldquo;thinks\u0026rdquo; it\u0026rsquo;s still on the C drive.\nWhat is mklink? mklink is a built-in Windows command-line tool (available since Vista) for creating links. It\u0026rsquo;s essentially a path alias/pointer, similar to Linux\u0026rsquo;s ln -s.\n🧊 Analogy: Think of a desktop shortcut — when you double-click the icon on your desktop, it actually opens a file located elsewhere. mklink does the same thing, connecting the \u0026ldquo;real storage location\u0026rdquo; with the \u0026ldquo;path the software expects.\u0026rdquo;\nThree Types of Links Type Command Target Characteristics Symbolic Link /D Directory Can cross partitions, most commonly used, like a \u0026ldquo;directory shortcut\u0026rdquo; Hard Link /H File Same partition only, multiple paths pointing to the same data Directory Junction /J Directory Cross-partition, older NTFS technology, better compatibility ⭐ For everyday use, prefer /J (Directory Junction) or /D (Directory Symbolic Link). For moving software data directories, they work almost identically.\nStep-by-Step Instructions Close the Target Software Make sure the software you\u0026rsquo;re migrating data from is completely closed (including background processes), otherwise files will be locked and cannot be moved.\nMove the Original Folder 1 2 # Move/cut the original C drive directory to the target drive move \u0026#34;C:\\original-path\u0026#34; \u0026#34;D:\\new-path\u0026#34; ⚠️ Don\u0026rsquo;t copy! Use move (or cut) to ensure the original path no longer exists.\nCreate the Link 1 2 # Create a Directory Junction with /J mklink /J \u0026#34;C:\\original-path\u0026#34; \u0026#34;D:\\new-path\u0026#34; Or use /D:\n1 mklink /D \u0026#34;C:\\original-path\u0026#34; \u0026#34;D:\\new-path\u0026#34; Verify Open the original C drive path and confirm you can access the files on the D drive.\n🔍 In CMD, navigate to the parent directory and run dir. Linked items will show the \u0026lt;JUNCTION\u0026gt; or \u0026lt;SYMLINKD\u0026gt; marker.\nCommon Use Cases WeChat Data Migration ⭐ WeChat is the number one C drive killer — chat history and file caches can easily reach tens of GB.\n1 2 3 4 5 6 # Close WeChat # Move the data directory move \u0026#34;%USERPROFILE%\\Documents\\WeChat Files\u0026#34; \u0026#34;D:\\Data\\WeChat Files\u0026#34; # Create the link mklink /J \u0026#34;%USERPROFILE%\\Documents\\WeChat Files\u0026#34; \u0026#34;D:\\Data\\WeChat Files\u0026#34; The new version of WeChat stores data at C:\\Users\\username\\Documents\\WeChat Files, while older versions store it in the installation directory under WeChat Files.\nQQ Data Migration 1 2 3 4 5 # QQ personal folder is usually at # C:\\Users\\username\\Documents\\Tencent Files move \u0026#34;C:\\Users\\your-username\\Documents\\Tencent Files\u0026#34; \u0026#34;D:\\Data\\Tencent Files\u0026#34; mklink /J \u0026#34;C:\\Users\\your-username\\Documents\\Tencent Files\u0026#34; \u0026#34;D:\\Data\\Tencent Files\u0026#34; Chrome / Edge Browser Cache 1 2 3 4 5 6 7 # Chrome user data move \u0026#34;%LOCALAPPDATA%\\Google\\Chrome\\User Data\u0026#34; \u0026#34;D:\\BrowserData\\Chrome\u0026#34; mklink /J \u0026#34;%LOCALAPPDATA%\\Google\\Chrome\\User Data\u0026#34; \u0026#34;D:\\BrowserData\\Chrome\u0026#34; # Edge user data move \u0026#34;%LOCALAPPDATA%\\Microsoft\\Edge\\User Data\u0026#34; \u0026#34;D:\\BrowserData\\Edge\u0026#34; mklink /J \u0026#34;%LOCALAPPDATA%\\Microsoft\\Edge\\User Data\u0026#34; \u0026#34;D:\\BrowserData\\Edge\u0026#34; Development Tool Caches 1 2 3 4 5 6 7 8 9 10 11 # pip cache move \u0026#34;%LOCALAPPDATA%\\pip\\cache\u0026#34; \u0026#34;D:\\DevCache\\pip\u0026#34; mklink /J \u0026#34;%LOCALAPPDATA%\\pip\\cache\u0026#34; \u0026#34;D:\\DevCache\\pip\u0026#34; # npm cache move \u0026#34;%LOCALAPPDATA%\\npm-cache\u0026#34; \u0026#34;D:\\DevCache\\npm\u0026#34; mklink /J \u0026#34;%LOCALAPPDATA%\\npm-cache\u0026#34; \u0026#34;D:\\DevCache\\npm\u0026#34; # Maven local repository move \u0026#34;%USERPROFILE%\\.m2\\repository\u0026#34; \u0026#34;D:\\DevCache\\maven\u0026#34; mklink /J \u0026#34;%USERPROFILE%\\.m2\\repository\u0026#34; \u0026#34;D:\\DevCache\\maven\u0026#34; A better approach is to configure the package manager\u0026rsquo;s cache path directly (e.g., npm config set cache). Environment variable solutions are more stable, with mklink as a fallback.\nWindows Store Apps / Large Games Some UWP apps and Xbox Game Pass games don\u0026rsquo;t allow you to change the installation path, but mklink can help migrate them.\n1 2 3 # For Forza Horizon and similar games # Usually located at C:\\Program Files\\WindowsApps or C:\\XboxGames # You\u0026#39;ll need to obtain folder permissions (TrustedInstaller) first ⚠️ Operating on the WindowsApps directory is more complex and involves permission management. Proceed with caution.\nOneDrive / iCloud Sync Directories 1 2 move \u0026#34;C:\\Users\\your-username\\OneDrive\u0026#34; \u0026#34;D:\\OneDrive\u0026#34; mklink /J \u0026#34;C:\\Users\\your-username\\OneDrive\u0026#34; \u0026#34;D:\\OneDrive\u0026#34; Important Notes \u0026amp; Pitfalls Issue Explanation Must move first, then link mklink requires that the target path does not exist, otherwise it will error File already exists Back up before moving Although the operation is reversible, it\u0026rsquo;s recommended to back up important data first Don\u0026rsquo;t touch system directories Avoid C:\\Windows, C:\\Program Files, and other system directories Deleting a link ≠ deleting data Removing the \u0026ldquo;shortcut\u0026rdquo; on the C drive only deletes the link; the data on the D drive remains Correct way to delete a link rmdir \u0026quot;C:\\link-path\u0026quot; (not del) Run CMD as Administrator Some directories require admin privileges to create links NTFS file system required Only supported on NTFS, not FAT32 or exFAT Restoring Delete the link → move the D drive data back to the original C drive path Deleting / Restoring a Link 1 2 3 4 5 # Delete the link (does NOT delete the original data on the D drive) rmdir \u0026#34;C:\\original-path\u0026#34; # To restore: move the data back move \u0026#34;D:\\new-path\u0026#34; \u0026#34;C:\\original-path\u0026#34; Quick Diagnosis: What\u0026rsquo;s Eating Your C Drive? Before using mklink, analyze your C drive to find the real culprit:\nTool Features WizTree Blazing fast scan, intuitive treemap, free SpaceSniffer Visual block chart, intuitive TreeSize Free Classic tool, sorted by folder size Windows Disk Cleanup cleanmgr, cleans temp files and update leftovers 🔥 WizTree is recommended — it uses MFT parsing directly, scanning an entire hard drive in seconds.\nSummary The core idea of mklink is:\n1 2 3 Software thinks data is still at C:\\some-path ↓ (the link created by mklink) Data is actually stored at D:\\some-path The operation mantra: Close the software → Move the folder → Create the mklink link → Verify it works\nIt\u0026rsquo;s safer, reversible, and more efficient than \u0026ldquo;editing the registry\u0026rdquo; or \u0026ldquo;reinstalling to another drive.\u0026rdquo; Master this command, and your C drive will never mysteriously turn red again. 🎉\nFurther Reading Disk cleanup tools: WizTree / SpaceSniffer Package manager cache path configuration: npm, pip, cargo official documentation ","date":"2026-06-02T00:00:00+08:00","image":"/p/c-%E7%9B%98%E7%BB%8F%E5%B8%B8%E7%88%86%E6%BB%A1%E6%95%99%E4%BD%A0%E7%AE%80%E5%8D%95%E7%9A%84-dos-%E5%91%BD%E4%BB%A4-mklink-%E6%8B%AF%E6%95%91-c-%E7%9B%98/cover.svg","permalink":"/en/p/c-drive-always-full-use-the-simple-mklink-dos-command-to-save-your-c-drive/","title":"C Drive Always Full? Use the Simple mklink DOS Command to Save Your C Drive!"},{"content":"Web Design Skill Practical Manual (Detailed Version) Tools: Claude Code / OpenCode Goal: Following this guide, you will use AI to generate a high-quality space exploration museum webpage Estimated time: 40-90 minutes\nBefore We Start - Understanding What We\u0026rsquo;re Going to Do Overall Process Overview 1 Set up environment → Install Skill → Create project → Bare run experience → Skill enhancement → Compare Why \u0026ldquo;Bare Run\u0026rdquo; First Before Using Skill? This is a comparison experiment:\nIf you use Skill directly, you won\u0026rsquo;t appreciate its value Let AI work freely first → You\u0026rsquo;ll see typical AI-style webpages (purple-pink-blue gradients, large rounded cards, emoji icons\u0026hellip;) Then use Skill to do it again → You\u0026rsquo;ll witness the same topic, same model producing completely different results Tools You\u0026rsquo;ll Need Tool What It Is Where to Get It Terminal Where you chat with AI Windows: PowerShell / Terminal; macOS: Terminal Claude Code or OpenCode AI coding Agent See installation instructions below Git Download Skill files from GitHub winget install Git.Git (Win) / brew install git (macOS) Browser Preview webpage effects Chrome / Edge / Firefox Screen recorder (optional) Record the process OBS Studio (free) / System built-in Confirm Agent is Ready If You\u0026rsquo;re Using Claude Code What it is: Anthropic\u0026rsquo;s official terminal AI coding tool. You type in the terminal, it helps you read files, write code, and execute commands.\nConfirm installation:\nOpen terminal (Windows: PowerShell, macOS: Terminal), type:\n1 claude --version If it shows a version number (like 1.0.x), it\u0026rsquo;s installed.\nIf not installed:\n1 2 # Need to install Node.js first (https://nodejs.org), then: npm install -g @anthropic-ai/claude-code Confirm API Key is configured:\nClaude Code needs an Anthropic API Key. In terminal:\n1 claude config list If you see apiKey is set, you\u0026rsquo;re good. If not:\n1 claude config set apiKey sk-ant-xxxxx (Replace sk-ant-xxxxx with your real key)\nIf You\u0026rsquo;re Using OpenCode What it is: An open-source terminal AI coding tool by SST team, similar to Claude Code but supports multiple models.\nConfirm installation:\n1 opencode --version If not installed:\n1 2 3 4 5 # Method 1: Install via Go go install github.com/sst/opencode@latest # Method 2: Install via Homebrew (macOS/Linux) brew install sst/tap/opencode Create Project Directory Create Working Folder 1 2 3 cd ~/Desktop mkdir space-museum-demo cd space-museum-demo Initialize Git Repository 1 git init Create Initial File Create an empty HTML file:\nClaude Code:\n1 claude Then input:\n1 Please create an index.html file in the current directory with only the basic HTML5 structure (DOCTYPE, head, body), no styles or content. HTML lang set to zh-CN, title set to \u0026#34;Space Exploration Museum\u0026#34;. Or manually:\n1 2 3 4 5 6 7 8 9 10 11 12 cat \u0026gt; index.html \u0026lt;\u0026lt; \u0026#39;EOF\u0026#39; \u0026lt;!DOCTYPE html\u0026gt; \u0026lt;html lang=\u0026#34;zh-CN\u0026#34;\u0026gt; \u0026lt;head\u0026gt; \u0026lt;meta charset=\u0026#34;UTF-8\u0026#34;\u0026gt; \u0026lt;meta name=\u0026#34;viewport\u0026#34; content=\u0026#34;width=device-width, initial-scale=1.0\u0026#34;\u0026gt; \u0026lt;title\u0026gt;Space Exploration Museum\u0026lt;/title\u0026gt; \u0026lt;/head\u0026gt; \u0026lt;body\u0026gt; \u0026lt;/body\u0026gt; \u0026lt;/html\u0026gt; EOF Start Local Preview Server 1 npx serve . Visit http://localhost:3000 in your browser.\nDownload web-design-skill Clone Repository 1 2 cd ~/Desktop/space-museum-demo git clone https://github.com/ConardLi/web-design-skill.git Bare Run Experience - See AI\u0026rsquo;s \u0026ldquo;Native Aesthetics\u0026rdquo; 🎯 Purpose: Let AI generate a webpage using default behavior, observe its \u0026ldquo;native aesthetics.\u0026rdquo;\nStart Agent (Without Loading Skill) 1 2 3 claude # or opencode Input Design Requirements 1 2 3 4 5 6 7 8 9 10 Please help me create a space exploration museum online exhibition webpage. All code in one index.html file (HTML + CSS + JS inline), requirements: 1. Dark theme, with cosmic feel and sci-fi atmosphere 2. Hero area showing museum name \u0026#34;Interstellar Exploration Museum\u0026#34; and a slogan 3. Exhibition card area showing 4 space exploration milestones (Gagarin, Apollo 11, Hubble Telescope, James Webb Telescope) 4. Timeline area showing key years of space exploration 5. Scroll animation effects (elements fade in on scroll) 6. Responsive layout, works on mobile Please generate complete code and write to index.html. Wait for AI to Generate This takes about 1-3 minutes.\nCheck Result Refresh http://localhost:3000 in your browser.\nObservation checklist:\nColors: Is there a purple-pink-blue gradient? Layout: Is it standard \u0026ldquo;centered title + subtitle\u0026rdquo;? AI-style features: Emoji icons? Large rounded cards? Save Bare Run Version 1 Please copy the current index.html and name it index-no-skill.html Install Skill to Agent 🎯 Purpose: Inject web-design-skill rules into Agent\u0026rsquo;s system prompt.\nClaude Code - Two Installation Methods Method A: Write to CLAUDE.md (Recommended, Permanent) 1 Please read the entire content of web-design-skill/skill.md, then create a CLAUDE.md file with the skill.md content. Method B: Reference in Conversation (Temporary) 1 @web-design-skill/skill.md Please design the webpage according to this Skill file\u0026#39;s rules. OpenCode - Installation Method A: Write to AGENTS.md (Recommended) 1 cp web-design-skill/skill.md AGENTS.md Verify Skill is Active Start Agent, input:\n1 Before starting design, please tell me: According to your design system, what color scheme will you use? What fonts? What spacing rules? What are the absolute no-goes? If Skill is active, AI will mention OKLCH color space, specific font recommendations, and \u0026ldquo;remove AI-style\u0026rdquo; rules.\nSkill Enhancement - Polish the Premium Feel 🎯 Purpose: Use the same requirements, let Skill guide AI to create a completely different webpage.\nStart New Conversation Important: Must start a new conversation!\nInput Design Requirements This time we deliberately give minimal requirements:\n1 Help me create a space exploration museum online exhibition webpage, all code in one index.html file. Phase A: AI Asks Questions AI may ask clarifying questions first.\nPhase B: AI Explains Design System AI describes its design system before writing code:\n1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Design System: ━━━━━━━━━━━━ Color scheme (based on OKLCH): - Background: oklch(15% 0.02 260) — Deep space blue - Primary: oklch(70% 0.15 250) — Cold blue - Secondary: oklch(60% 0.12 310) — Deep purple - Text: oklch(95% 0.01 260) — Near white Fonts: - Headings: Orbitron (tech feel) - Body: Space Grotesk (good readability) Spacing system: Based on 8px grid Layout strategy: Magazine-style large image layout, non-traditional card grid Phase C: AI Outputs V0 (Rough Initial Version) Check browser, confirm if direction is correct.\nPhase D: Iterative Refinement Give 1-2 feedback points per round.\nPhase E: Final Verification 1 2 3 4 5 6 7 Please review this webpage as a fresh design expert: 1. Any \u0026#34;obviously AI-made\u0026#34; features? List them all. 2. Is the color scheme harmonious? Using OKLCH? 3. Is font usage appropriate? Any overused fonts? 4. Is layout creative? Or standard Hero + card grid? 5. Are animations natural? Any overuse of glow effects? 6. Is mobile adaptation working? Save Skill Version After AI completes, save the final version:\n1 2 3 4 5 # If you\u0026#39;re still in the Agent conversation, ask AI to copy: # \u0026#34;Please copy the current index.html and name it index-with-skill.html\u0026#34; # Or manually copy after exiting Agent: cp index.html index-with-skill.html Compare Two Versions Open both files in browser:\n1 2 http://localhost:3000/index-no-skill.html ← Bare run version http://localhost:3000/index.html ← Skill version Record as Video (Optional) Suggested Shots 1 2 3 4 5 Shot 1: Final showcase (30 seconds) Shot 2: Comparison display (1 minute) Shot 3: Process replay (2-3 minutes) Shot 4: Design details explanation (1 minute) Shot 5: Summary (30 seconds) Appendix A: Common Prompt Templates Ask AI to Explain Design System First 1 2 3 4 5 6 7 Before writing any code, please describe your design system in natural language, including: 1. Color scheme (using OKLCH) 2. Font choices (what for headings and body) 3. Spacing system 4. Layout strategy 5. Absolute no-gos I\u0026#39;ll confirm before you start coding. Request Quick V0 1 2 3 4 Give me a minimum viable version (V0) first. Placeholders and incomplete parts are fine. I\u0026#39;ll confirm direction before you refine details. Don\u0026#39;t spend too much time on details. Trigger Full Verification 1 2 3 4 Please review the current webpage as a fresh design expert. List all \u0026#34;obviously AI-made\u0026#34; features, and all issues with colors, fonts, layout. Then fix them one by one. Final Summary 1 2 Core web design workflow: Understand requirements → Confirm design system → Quick V0 → Iterate and refine → Verify Three sentences to remember Skill\u0026rsquo;s essence:\nDesign system first, code second — Wrong direction means wasted code Rough V0 first, then polish — Quick iteration, lowest cost Bold whitespace, every element must prove itself — Restraint is premium ","date":"2026-05-27T00:00:00+08:00","image":"/p/web-design-skill-%E5%AE%9E%E6%93%8D%E6%89%8B%E5%86%8C%E8%AF%A6%E7%BB%86%E7%89%88/cover.svg","permalink":"/en/p/web-design-skill-practical-manual-detailed-version/","title":"Web Design Skill Practical Manual (Detailed Version)"},{"content":"Web Design Skill Learning Notes What is Claude Design? Claude Design is a design tool released by Anthropic that caused Figma\u0026rsquo;s stock price to plummet on the day of its release.\nCore concept: Type on the left, get a design draft on the right (essentially runnable webpages, not images)\nDifferences from Traditional Design Tools Dimension Traditional Design Tools (e.g., Figma) Claude Design Lead Human operates on canvas, AI assists AI is the main generator, human reviews Output Design images Real runnable code Interaction Manual drawing Text description → Auto generation Version control Manual operation Clickable links, tag-based version switching Essence: Claude Design is more like Claude Code (designer version) rather than an AI version of Figma.\nCore Prompt Breakdown (6 Key Points) The video deeply analyzed Claude Design\u0026rsquo;s leaked prompts and extracted 6 core design principles:\nRole Positioning — Dynamic Identity Switching Original prompt essence: \u0026ldquo;You are an expert designer, and the user is your product manager\u0026rdquo;\nKey insights:\n❌ Don\u0026rsquo;t say \u0026ldquo;you are an AI assistant\u0026rdquo; ✅ Establish a designer ↔ product manager collaboration Two benefits:\nAI makes decisions more decisively — Designers should have judgment, no need to ask about everything Key points will be asked — Because the user is the product manager, they make final decisions Dynamic identity switching:\nMaking animations → Motion designer Making prototypes → UX designer Making presentations → Deck designer 💡 Insight: Many people\u0026rsquo;s prompts just say \u0026ldquo;you are a frontend developer\u0026rdquo; and that\u0026rsquo;s it. Good role positioning should be dynamic, flexibly switching identities based on specific tasks.\nWorkflow — Six-Step Process 1 Understand requirements → Explore resources → Make plan → Build structure → Complete verification → Brief summary Detail 1: The Art of Questioning (When to ask? When to just do it?) Problem: Many Agents either ask you a bunch of questions first or just do everything without asking.\nClaude Design\u0026rsquo;s strategy:\nInput \u0026ldquo;Help me make a PPT\u0026rdquo; → Ask a few questions first (insufficient information) Input \u0026ldquo;Help me make a PPT, needed for the National Games in 10 minutes\u0026rdquo; → Just do it (urgent scenario, sufficient information) 💡 Insight: Based on the urgency and information completeness of the context, flexibly decide whether to ask or execute.\nDetail 2: Summary Principles ✅ Only mention key considerations and next steps ❌ Don\u0026rsquo;t repeat what you\u0026rsquo;ve already done 💡 Insight: This principle can effectively prevent AI from generating excessive nonsense.\nRemoving AI-Style (Most Valuable Part) Typical AI-generated webpage characteristics:\nPurple-pink-blue gradient backgrounds Large rounded cards Using emojis as icons Fake data everywhere Left-side colored border rounded cards Overused fonts Meaningless data and icon stacking It\u0026rsquo;s like having \u0026ldquo;furthermore,\u0026rdquo; \u0026ldquo;notably,\u0026rdquo; \u0026ldquo;in summary\u0026rdquo; throughout an article —一眼就能看出是 AI 写的。\nClaude Design\u0026rsquo;s approach: List a complete \u0026ldquo;minefield checklist\u0026rdquo;, telling AI one by one not to use these clichés.\nFont recommendations are also carefully considered:\nClearly list fonts that must never be used + alternatives Recommend niche but high-quality fonts Color System — OKLCH Color Space Color strategy priority:\n1 Brand color → OKLCH-derived colors → Never invent new colors Why OKLCH instead of HSL?\nHSL OKLCH Perceptual uniformity ❌ Not uniform (same brightness value, yellow is much brighter than blue) ✅ Uniform AI color effect Values look fine but uncomfortable Keep lightness and chroma constant, only change hue, colors naturally harmonious 💡 Insight: OKLCH, this seemingly small detail, can directly elevate a webpage\u0026rsquo;s premium feel by a level.\nContent Principles — \u0026ldquo;1000 NOs for One YES\u0026rdquo; Quoting Steve Jobs\u0026rsquo; classic quote.\nAI\u0026rsquo;s traditional problem with webpages: Wants to fill every space — Hero, features, reviews, data, FAQ, contact info\u0026hellip; everything goes in, but everything is mediocre.\nClaude Design\u0026rsquo;s attitude:\nEvery element must prove why it should be there If the page feels empty → May be a layout issue, use whitespace to solve One bold whitespace \u0026gt; Ten filler sections Verification Mechanism — Sub-Agent Check Principle: After development, fork an independent sub-Agent to do a comprehensive check on the webpage.\nWhy an independent sub-Agent?\nAI in the same context tends to \u0026ldquo;feel good about itself\u0026rdquo; Independent sub-Agent has no \u0026ldquo;emotional baggage\u0026rdquo;, easier to find problems Verification content:\nAny AI-style features? Is the color scheme harmonious? Are fonts appropriate? Is layout creative? Core Optimizations of Skill File The Skill file made three key optimizations based on Claude Design\u0026rsquo;s prompts:\nDesign System First, Code Later Before starting coding, require AI to clearly list:\nColor scheme Font choices Spacing system \u0026hellip; Why? If not clarified, AI will silently make decisions and write code. When you see the result, if direction is wrong, you have to redo everything. Clarifying upfront means no cost to correct direction before coding.\nOutput Minimum Viable Version Early Require AI to first produce a rough V0 version with assumptions and placeholders A rough V0 \u0026gt; Spending multiples of time to make a polished V1 Why? If the entire direction is wrong, no matter how polished V1 is, it\u0026rsquo;s all wasted.\nAdditional Supplements Added more items for removing AI-style Added several verified font and color reference tables Included reference files (typical code templates, from the \u0026ldquo;copy study the component\u0026rdquo; part of the prompt) Effect Comparison Demo Test environment: Cursor + Claude 4.7 (with Skill vs without Skill)\nSpace Exploration Museum Online Exhibition Page Without Skill With Skill Colors Cyan-purple-pink gradient, typical AI neon feel OKLCH defined, close to magazine printing\u0026rsquo;s deep tones Fonts Relatively outdated Headings and body text have character, tech feel Layout Standard Hero + cards, textbook landing page Non-traditional card style, creative Animation Starry sky and planet animations, but with excessive glow effects Comfortable, creative Overall Has space feel, lacks creativity Like a very experienced designer\u0026rsquo;s masterpiece Independent Photographer Portfolio (Minimal Prompt) Without Skill With Skill Design style Dark background + neon glow + semi-transparent cards, outdated Fictionalized a Nordic photographer, designed complete visual style from scratch Copy Full of AI feel — Emotional expression The freedom a photographer should have is completely missing Like flipping through a high-end photography album Decision strategy Just did it, didn\u0026rsquo;t ask questions Proactively asked about color preferences, core elements, etc. Final Conclusion 1 2 Without Skill: 85 points → Usable, complete, passing With Skill: 95 points → Beautiful, polished, stylish Each rule in Skill seems small individually, but combined they produce qualitative change. This is the gap from \u0026ldquo;usable\u0026rdquo; to \u0026ldquo;beautiful\u0026rdquo;, from \u0026ldquo;complete\u0026rdquo; to \u0026ldquo;polished\u0026rdquo;, from \u0026ldquo;passing\u0026rdquo; to \u0026ldquo;stylish\u0026rdquo;.\nCore Knowledge Quick Reference # Knowledge Point One-Sentence Summary 1 Dynamic role positioning Flexibly switch AI identity based on tasks, not just \u0026ldquo;you are a frontend developer\u0026rdquo; 2 Six-step workflow Understand requirements → Explore resources → Make plan → Build structure → Complete verification → Brief summary 3 Art of questioning Decide whether to ask or act based on information completeness and urgency 4 Remove AI-style List minefield checklist, ban gradients/emojis/large rounded cards and other clichés 5 OKLCH color Perceptually uniform color space, produces more harmonious colors than HSL 6 Content restraint Every element must prove its reason for existence, bold whitespace 7 Sub-Agent verification Check with independent context, avoid \u0026ldquo;feeling good about yourself\u0026rdquo; 8 Design system first, code later Expose design decisions early, avoid directional errors 9 Quick V0 Rough but fast prototype \u0026gt; Polished but directionally wrong product Related Resources Open source repository: ConardLi/web-design-skill ","date":"2026-05-26T00:00:00+08:00","image":"/p/web-design-skill-%E5%AD%A6%E4%B9%A0%E7%AC%94%E8%AE%B0/cover.svg","permalink":"/en/p/web-design-skill-learning-notes/","title":"Web Design Skill Learning Notes"},{"content":"One-Sentence Summary An Agent solves how AI gets work done; a Harness solves how AI does work reliably. Together, they form the foundation of products like Claude Code, Codex, Open Cloud, and Qwen.\n1. From ChatGPT to AI Agent The Original Problem Asking ChatGPT to create an animation with HTML + SVG (e.g., an Apple logo drawn with lines) often produces poor results — even in 2026, AI struggles with even a minimalist logo.\nManual Improvement Search for Apple SVG assets on sites like iconfont Feed the SVG code to AI and ask it to recreate it Results improve significantly, but manually finding assets every time is tedious Automated Improvement — Wrapper Sites (Earliest Agent Prototype) Build a website that wraps ChatGPT via API calls, adding backend functions:\nUser submits request → The site tells AI: \u0026ldquo;Here\u0026rsquo;s the user\u0026rsquo;s prompt. I also have a logo search function you can call when needed.\u0026rdquo; AI analyzes → Determines it needs an Apple logo, responds: \u0026ldquo;Call the asset search tool with parameter: Apple logo\u0026rdquo; Site executes → Backend runs the search function and finds SVG assets Final generation → The site sends assets + user prompt to AI to complete the animation 2. Two Core Working Modes of Agent 1. ReAct (Reasoning + Acting) — Step by Step Three-step loop:\nThink: AI analyzes the request, determines what\u0026rsquo;s needed and which tool to call Act: AI tells the backend to call a tool (e.g., search for assets) Observe: Backend returns results; AI sees them and continues The loop repeats: Think → Act → Observe, until the task is complete.\nThis is the most fundamental working pattern of almost all AI Agents, including Claude Code, Codex, and Open Cloud.\n2. Plan \u0026amp; Execute — Plan First, Then Execute Plan first: Generate a work list / step sequence upon receiving the task Execute: Follow the checklist step by step Mode Analogy Characteristic ReAct Improvise as you go Flexible, adjust on the fly Plan \u0026amp; Execute Research before traveling Structured, suited for complex tasks Real agents combine both. For example, Qwen\u0026rsquo;s \u0026ldquo;Task Assistant\u0026rdquo; mode: first analyzes requirements and creates steps (Plan), then proactively searches, writes code, and adjusts (Act).\n3. Advanced Agent Capabilities Tool Calling / Function Calling The Agent determines which tools to call based on the user prompt; the backend executes them and returns results.\nContext Management and Compression Large models have no memory — each conversation starts fresh The Agent must send the entire conversation history to the AI each time, which grows longer over time Context window = AI\u0026rsquo;s workspace, limited in size Context compression: When the conversation exceeds the window, earlier content is summarized into a condensed version Trade-off: compression loses information, potentially causing the AI to forget previous instructions Multi-Agent Collaboration One AI acts as the project manager (understanding requirements, breaking down tasks, assigning work), while other AIs execute subtasks.\nEach sub-AI has its own independent context window The project manager only sees final results, not intermediate steps Improves efficiency while mitigating context explosion 4. Harness — The Safety Net for Reliable AI When Agents run in production, they encounter various issues that need a Harness to solve.\nEngineering Checkpoints in a Harness Checkpoint Problem Solution Format Sanitization AI adds \u0026ldquo;okay\u0026rdquo;, markdown code blocks, or extra newlines when returning JSON Clean: remove fluff, wrapping symbols, extra newlines; send errors back for regeneration if still failing Parameter Validation Tool call parameters are invalid (e.g., city field contains a non-city name) Validate format/range before calling; reject and request refill if invalid Input Filtering Prompt injection attacks (\u0026ldquo;ignore all previous instructions\u0026rdquo;) / malicious SVG uploads Scan user input for suspicious instructions and asset safety before processing Output Filtering AI-generated content may contain malicious code Scan output content for threats Hard-Coded Validation AI repeatedly makes the same error (e.g., always using pure white backgrounds) Enforce with code: auto-detect SVG background color and replace white with dark Core Principle of Harness Engineering If you can enforce it with code, never rely on prompting alone.\n5. Complete Architecture Summary One Sentence to Elevate Agent is the horse; Harness is the tack. A horse without tack runs into problems; tack without a horse does nothing. Together, they transform AI from a chat-only chatbot into a worker that gets things done in the real world.\n","date":"2026-05-25T02:00:00+08:00","image":"/p/agent-%E5%92%8C-harness-%E5%88%B0%E5%BA%95%E6%98%AF%E4%BB%80%E4%B9%88-%E8%A7%86%E9%A2%91%E7%AC%94%E8%AE%B0%E6%95%B4%E7%90%86/cover.svg","permalink":"/en/p/what-are-agent-and-harness-video-notes/","title":"What Are Agent and Harness? — Video Notes"},{"content":" C drive turning red is a common headache for Windows users—system update cache, temp files, desktop files, WeChat chat records\u0026hellip; Before you know it, your C drive is packed. Replacing the hard drive is expensive, and cleaning only treats the symptoms. The most thorough solution is: borrow space from other drives for your C drive.\n📖 Table of Contents (click to expand) # Section Description 1 Preparation Download, install, enter PE environment 2 Resize 8-step guide with Partition Assistant 3 Reboot \u0026amp; Cleanup Return to Windows, clean boot menu 4 Tips Additional advice and FAQs 📦 Preparation ⚡ In a nutshell: Put Windows into a \u0026ldquo;hibernation box\u0026rdquo; so the C drive isn\u0026rsquo;t occupied.\n① Download WePE Toolbox WePE Toolbox — a lightweight PE (Preinstallation Environment) tool, clean and ad-free.\n② Install to System Open the downloaded program and click 「Install into System Now」. It will automatically write the boot entry.\n③ Reboot into Boot Menu After installation, restart your computer. You\u0026rsquo;ll see the system boot selection screen.\n⏱ Note: The countdown is only a few seconds. If it times out, it will boot into the current system. Watch closely and select quickly!\n④ Enter PE Environment Use arrow keys to select WePE Toolbox and press Enter.\n💡 Why enter PE?\nIn the PE environment, your Windows system is completely \u0026ldquo;hibernated\u0026rdquo;—the C drive is not occupied by any process. This allows safe partition resizing. Think of it like surgery: the patient must be anesthetized before the operation. Other partition tools work on the same principle.\n🛠️ Resize Once in PE, the tool menu will pop up automatically. Click 「Partition Assistant」.\nStep 1 · Check Disk Layout Partition Assistant will show you the layout of all disk partitions. Identify which drive has free space to \u0026ldquo;donate\u0026rdquo; to the C drive.\nStep 2 · Choose the Drive to Shrink Here we use Software (D drive) as an example. We\u0026rsquo;ll \u0026ldquo;cut\u0026rdquo; some space from D drive to give to C drive.\n💡 Which drive to choose?\n✅ Prefer drives with plenty of free space that you don\u0026rsquo;t use often ❌ Avoid touching system recovery partitions or EFI partitions Step 3 · Adjust Partition Right-click D drive → 「Adjust Partition」.\nStep 4 · Shrink the Drive In the popup window, drag the slider or enter a value to decide how much space to take from D drive.\n✅ Example: If you want to add 50GB to C drive, shrink D drive by 50GB here.\n⚠️ Note: The shrink value must not exceed the used space on D drive, or it will error.\nClick 「OK」 when done.\nStep 5 · Merge into C Drive You\u0026rsquo;ll now see a block of 「Unallocated Space」 next to D drive.\nStep Action 1 Right-click C drive → 「Adjust Partition」 2 Drag the slider all the way to the right to merge all unallocated space into C drive 3 Click 「OK」 Step 6 · Submit Task Click 「Submit」 in the top-left corner.\n⚠️ Critical Reminder\nAll the adjustments so far are just \u0026ldquo;plans\u0026rdquo; — they haven\u0026rsquo;t taken effect yet.\nOnly after clicking 「Submit」 will the system actually execute the partition operations. Double-check before submitting!\nStep 7 · Wait for Execution Partition Assistant will begin executing the adjustments. This may take several minutes to over ten minutes, depending on your disk size and speed.\n⚠️ 🔴 Do NOT power off or force shutdown during this process! Otherwise, the partition table may be corrupted, causing data loss Plug in the power adapter (laptop users) Grab a cup of tea and wait patiently 🍵 Step 8 · Done 🎉 When you see the success message, the expansion is complete!\n🚀 Reboot \u0026amp; Cleanup # Action ① Click 「Restart」 ② At the boot menu, select your Windows system to boot normally ③ Open This PC and verify that C drive space has increased ✅ 🧹 Final step: If you don\u0026rsquo;t want to see the boot selection screen every time, open WePE Toolbox → click 「Uninstall」 to restore the original state.\n📌 Tips Scenario Recommendation 🟢 C drive is too small (\u0026lt; 30GB) Expand to at least 80 ~ 100GB 🟡 D drive also has no free space Clean up D drive, or use an external drive to transfer large files 🔴 Worried about data loss before operation Strongly recommend backing up important files first! Partition Assistant is stable, but better safe than sorry ✨ That's the complete guide to expanding your C drive. May your computer never see red again! ","date":"2026-05-24T16:00:00+08:00","image":"/p/c-%E7%9B%98%E7%88%86%E6%BB%A1%E7%94%A8%E5%85%B6%E4%BB%96%E7%9B%98%E7%BB%99-c-%E7%9B%98%E6%89%A9%E5%AE%B9/cover.svg","permalink":"/en/p/c-drive-full-expand-it-using-other-drives/","title":"C Drive Full? Expand It Using Other Drives"},{"content":"Overview Ever had this experience: you ask AI to write some code, it churns out a bunch, then you run it and get errors. Or you call an API that\u0026rsquo;s clearly documented, but the AI says it \u0026ldquo;doesn\u0026rsquo;t exist.\u0026rdquo;\nIt\u0026rsquo;s not that the AI is dumb — it\u0026rsquo;s that its training data has an expiration date. The data might be months or even years old, and frameworks have been updated several times since.\nContext7 solves exactly this. Built by the Upstash team, it fetches the latest official docs when you ask a question, injects them into the AI\u0026rsquo;s context, and lets the AI answer based on the current version.\nUsage is simple: just add use context7 at the end of your prompt. It\u0026rsquo;s like telling the AI: \u0026ldquo;Don\u0026rsquo;t guess — check the latest docs first before answering.\u0026rdquo;\nWhy Do You Need It? 💥 One Example Is Enough Say you want to add a \u0026ldquo;Back to Top\u0026rdquo; button to your personal website — when you scroll down, a button appears in the bottom-right corner; click it and you go back to the top.\nWhat AI writes with outdated knowledge: First load a几十 KB third-party library, then write a bunch of code to use it. The feature works, but for a single button, the page gets slower and the code is bloated.\nThe truth is, it\u0026rsquo;s much simpler now: Modern browsers already have smooth scrolling and scroll listening built in — a few lines of code, no extra libraries needed.\nAI doesn\u0026rsquo;t know this because it learned from教材 that\u0026rsquo;s years old.\nWith use context7, Context7 checks the latest docs and finds that native features are sufficient. So the AI chooses a lighter approach instead of giving you the old clunky solution.\nIt\u0026rsquo;s like asking a friend to fix your phone — they try to拆 it from memory, following steps from 3 years ago. The screw positions have changed. If they\u0026rsquo;d checked the latest tutorial first, they wouldn\u0026rsquo;t have broken it.\nWith vs Without Context7 Without With Information source Stale knowledge in AI\u0026rsquo;s brain, potentially outdated Real-time docs fetched from official sources API accuracy Often wrong or uses deprecated APIs Guaranteed to use current version APIs Code quality May use outdated patterns from years ago Follows latest recommended practices Version handling Guesses regardless of version Checks the version you specify 🔄 How It Works Just a few steps:\n1 2 3 4 5 6 7 8 9 You ask a question (add use context7 at the end) ↓ Context7 identifies which package you\u0026#39;re asking about ↓ Fetches the latest content from GitHub and official docs ↓ Filters the most relevant snippets, injects them into the AI\u0026#39;s \u0026#34;context\u0026#34; ↓ AI answers with the latest docs \u0026ldquo;Context\u0026rdquo; is everything the AI can \u0026ldquo;see\u0026rdquo; in your current conversation. Injecting docs is like opening a reference book on the table — the AI reads and answers at the same time.\nWhere does the doc come from? GitHub repos, official doc sites, and llms.txt files (a special doc index format for AI).\nAfter fetching results, Context7 uses an LLM to intelligently rank them and picks the most relevant snippets for you.\nTwo ways to use it:\nMethod Description MCP Mode (recommended) Install once, AI coding assistant calls it automatically. MCP is like a plugin for AI — set it and forget it CLI Manual Mode Query docs manually in the terminal, for those who like tinkering Core Capabilities Smart Matching: You Say the Name, It Finds the Place When you ask AI how to use a tool, Context7 needs to find the latest manual online. But multiple things can share the same name — it needs to know which one you mean.\nCommon names it can identify on its own. For ambiguous or common names, use the owner/repo format to be precise:\n1 Use /tailwindlabs/tailwindcss to add a navbar to my page. use context7 Here tailwindlabs is the author name, tailwindcss is the project name. Like searching for \u0026ldquo;Apple\u0026rdquo; — it could be fruit or a phone. Be specific and you won\u0026rsquo;t go wrong.\nSupported Libraries All popular ones are included: React, Next.js, Vue, Tailwind CSS, Express, Prisma, Supabase, TypeScript\u0026hellip; Full list at context7.com/rankings.\nVersion Awareness Different versions can have vastly different APIs. Just specify the version and Context7 will fetch docs for that version:\n1 2 3 Write a counter with Vue 3. use context7 Write an API route using Next.js 14\u0026#39;s Pages Router. use context7 Configure dark mode with Tailwind CSS v4. use context7 If you ask for an iPhone 12 teardown guide, nobody will hand you the iPhone 15 version.\nInstallation One-Click Install 1 npx ctx7 setup npx comes with Node.js, no extra installation needed. If you haven\u0026rsquo;t installed Node.js yet, go to nodejs.org to download it — once installed, you\u0026rsquo;ll have npx.\nRunning it will:\nOpen a browser for you to log in and authorize (OAuth) Generate an API Key (your \u0026ldquo;identity credential\u0026rdquo;) Auto-configure your editor Three steps and you\u0026rsquo;re done.\nTo specify an editor, add a parameter:\n1 2 3 npx ctx7 setup --claude # Claude Code npx ctx7 setup --cursor # Cursor npx ctx7 setup --opencode # OpenCode Uninstall: npx ctx7 remove\nManual Configuration If auto-install doesn\u0026rsquo;t work, manually add the MCP Server:\n1 2 3 4 5 6 7 8 9 10 { \u0026#34;mcpServers\u0026#34;: { \u0026#34;context7\u0026#34;: { \u0026#34;url\u0026#34;: \u0026#34;https://mcp.context7.com/mcp\u0026#34;, \u0026#34;headers\u0026#34;: { \u0026#34;CONTEXT7_API_KEY\u0026#34;: \u0026#34;your API key\u0026#34; } } } } Configuration file locations for different tools (~ represents your user directory, e.g., C:\\Users\\yourusername on Windows):\nTool Config Location Cursor Settings → MCP, or ~/.cursor/mcp.json Claude Code ~/.claude/settings.json (global) or .claude/settings.json (project) Windsurf Settings → Cascade → MCP servers Cline VS Code extension → MCP Servers → Configure OpenCode Project root opencode.json Get your API Key at context7.com/dashboard. Format is ctx7sk..., free users get quota too.\n✅ Verification Send a test:\n1 Write a counter webpage with a button. use context7 If the AI gives clean, modern code without loading extra libraries, it\u0026rsquo;s working.\nUsage Basic Usage Add use context7 at the end of your prompt:\n1 2 Write a clean personal resume page. use context7 Write a countdown tool that counts down from a given number of seconds. use context7 Specify a Library Precisely Use the /owner/repo format to skip name matching:\n1 Use /tailwindlabs/tailwindcss to add a navbar to my page. use context7 Recommended when the library name is ambiguous.\nSpecify a Version 1 2 Write a card layout using Bootstrap 4 instead of 5. use context7 Write a todo list using Vue 3\u0026#39;s Composition API. use context7 Combine Multiple Libraries 1 Build an icon showcase page with Bootstrap + Font Awesome. use context7 Configure Auto-Trigger If you don\u0026rsquo;t want to type use context7 every time, configure it in your rules file:\n→ Cursor in .cursorrules:\n1 When user questions involve third-party framework/library API usage, automatically use Context7 to query the latest docs. → Claude Code in CLAUDE.md:\n1 2 3 ## Documentation Query Rules - For third-party libraries/frameworks, first use Context7 to query latest docs - Prioritize generating code based on Context7 results CLI Commands If you only use Context7 in AI conversations, you can skip this. CLI is for those who like terminal commands.\nnpm is Node.js\u0026rsquo;s built-in package manager, -g means \u0026ldquo;global install\u0026rdquo; — install once, use everywhere.\n1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 # Install CLI npm install -g ctx7 # Search libraries ctx7 library react ctx7 library nextjs \u0026#34;middleware\u0026#34; # Get docs ctx7 docs /facebook/react \u0026#34;hooks state management\u0026#34; ctx7 docs /vercel/next.js \u0026#34;middleware authentication\u0026#34; # Skills management ctx7 skills search # Search available Skills ctx7 skills install # Install Skill ctx7 skills list # View installed ctx7 skills remove # Uninstall # Authentication ctx7 login # Login ctx7 whoami # View status ctx7 logout # Logout ❓ FAQ How is this different from AI\u0026rsquo;s built-in web search? Web search returns blog posts and forum threads of varying quality — you still have to judge credibility yourself. Context7 only pulls from official docs, uses an LLM to filter the most relevant snippets, and feeds them directly to the AI.\n💰 Will use context7 cost more? No. Although there\u0026rsquo;s an extra doc lookup step, the AI gets accurate information so it doesn\u0026rsquo;t have to guess, rewrite, or produce long, buggy code. Overall token consumption is actually lower.\nWhat if my library isn\u0026rsquo;t listed? Go to context7.com and click \u0026ldquo;Add Docs\u0026rdquo; to submit it, or skip use context7 and let the AI fall back to its own knowledge.\nI installed it but it doesn\u0026rsquo;t work? Check these one by one:\nDid npx ctx7 setup report any errors Is the MCP config JSON format correct (even one extra comma will break it) Is the API Key valid (starts with ctx7sk...) Did you completely close and reopen your editor Is the MCP status light green Did you include use context7 in your prompt Does it affect response speed? It adds one or two seconds of wait time, but you get accurate answers without back-and-forth corrections. One debug-compile-fix cycle takes way longer than that.\nSummary Item Content What it is A platform providing real-time, up-to-date documentation for AI coding assistants Problem it solves AI giving incorrect code due to outdated training data Core principle Fetch official docs in real-time, inject into AI context Installation npx ctx7 setup — one command and done Usage Add use context7 at the end of your prompt Pricing Free tier available, sufficient for personal use Website context7.com GitHub github.com/upstash/context7 Once installed, you\u0026rsquo;ll never have to worry about AI giving you outdated knowledge again.\n","date":"2026-05-02T19:51:00+08:00","image":"/p/context7%E6%8C%87%E5%8D%97%E8%AE%A9ai%E7%BC%96%E7%A8%8B%E5%8A%A9%E6%89%8B%E8%AF%BB%E6%87%82%E6%9C%80%E6%96%B0%E6%96%87%E6%A1%A3/cover.svg","permalink":"/en/p/context7-guide-help-your-ai-coding-assistant-read-the-latest-docs/","title":"Context7 Guide: Help Your AI Coding Assistant Read the Latest Docs"},{"content":" 📋 Table of Contents 1. What is the opencode-obsidian Plugin? 2. Environment Preparation 3. Installing the BRAT Plugin 4. Installing opencode-obsidian via BRAT 5. Installing OpenCode CLI 6. Plugin Settings Explained 7. First Use 8. Context Injection (Experimental Feature) 9. Custom Command Mode 10. FAQ and Troubleshooting 1. What is the opencode-obsidian Plugin? opencode-obsidian is a third-party community plugin that embeds the OpenCode AI assistant directly into the Obsidian window. Unlike traditional terminal integration solutions, this plugin uses OpenCode\u0026rsquo;s Web view for direct embedding — what you see is the complete OpenCode interface, with no need to switch back and forth between terminal and Obsidian.\nCore Features:\n🖥️ OpenCode interface directly embedded in Obsidian sidebar or main editor 🔄 Automatic server management — starts when panel opens, stops when closed 📄 Experimental context injection — automatically passes current notes and selected text to AI ⌨️ Shortcut Ctrl/Cmd + Shift + O for quick panel toggle Use Cases:\nSummarizing and distilling long-form content Drafting, editing, and polishing writing Querying and exploring your knowledge base Generating outlines and structured notes\n⚠️ The plugin author is not affiliated with OpenCode or Obsidian — this is an independent third-party project. Current version is 0.2.1 (Beta stage), desktop only.\n2. Environment Preparation Before starting, ensure you have the following ready:\nItem Requirement Notes Obsidian ≥ 1.4.0 Download Node.js ≥ 18+ Download, for OpenCode installation Once ready, follow the steps below.\n3. Installing the BRAT Plugin BRAT (Beta Reviewer\u0026rsquo;s Auto-update Tool) is an Obsidian community plugin specifically for installing Beta plugins not yet listed in the community plugin marketplace. opencode-obsidian isn\u0026rsquo;t officially listed yet, so installation via BRAT is required.\nStep 1: Open Community Plugin Marketplace In Obsidian, click: Settings → Third-party plugins → Turn off \u0026ldquo;Safe mode\u0026rdquo; → Community plugin marketplace\nStep 2: Search and Install BRAT Search for BRAT (full name: Obsidian42 - BRAT) in the community marketplace, click \u0026ldquo;Install\u0026rdquo; → \u0026ldquo;Enable\u0026rdquo;.\n💡 BRAT stands for Beta Reviewer\u0026rsquo;s Auto-update Tool, developed by TfTHacker. It automatically checks for Beta plugin updates and notifies you to upgrade.\n4. Installing opencode-obsidian via BRAT Once BRAT is installed, use it to install the opencode-obsidian plugin.\nStep 1: Open BRAT Settings Settings → Third-party plugins → Find installed BRAT, click the gear icon on the right to enter settings.\nStep 2: Add Beta Plugin In the BRAT settings page, click the \u0026ldquo;Add Beta plugin\u0026rdquo; button.\nStep 3: Enter Repository Address In the popup input box, enter:\n1 mtymek/opencode-obsidian Click \u0026ldquo;Add Plugin\u0026rdquo;.\nBRAT will automatically pull the latest release version from GitHub and install it.\nStep 4: Enable the Plugin After installation, go to Settings → Third-party plugins → Find OpenCode-Obsidian in the \u0026ldquo;Installed plugins\u0026rdquo; list and toggle it on.\n✅ Once enabled, a terminal-style icon appears in Obsidian\u0026rsquo;s left sidebar — this is the OpenCode entry point.\nAuto-Update BRAT periodically checks GitHub for new versions. When an update is available, it shows a notification in Obsidian — just click to confirm and auto-upgrade.\n5. Installing OpenCode CLI The plugin itself is just a \u0026ldquo;shell\u0026rdquo; — it starts opencode serve in the background and embeds OpenCode\u0026rsquo;s web interface into Obsidian. So you only need to install the OpenCode CLI via npm.\nOpen your system terminal (PowerShell for Windows, Terminal for macOS/Linux):\n1 npm i -g opencode-ai Verify installation:\n1 2 opencode --version # Expected output like: 1.14.39 ⚠️ Windows users: If the plugin shows \u0026ldquo;Executable not found at \u0026lsquo;opencode\u0026rsquo;\u0026rdquo;, jump to Section 10 for the solution.\n6. Plugin Settings Explained After enabling the plugin, go to Settings → Third-party plugins → OpenCode-Obsidian gear icon to see these configuration options:\nBasic Settings Setting Default Description OpenCode executable path opencode Enter full path if not found in system PATH Port 14096 Port number the OpenCode service listens on Hostname 127.0.0.1 Address the service binds to Project directory (Auto from Vault path) Working directory for OpenCode Startup timeout 45000 (45s) Max milliseconds to wait for service startup Interface Settings Setting Default Description Default view position sidebar sidebar = sidebar, main = main editor area Auto-start Off Auto-start OpenCode service when Obsidian opens Context Injection (Experimental) Setting Default Description Inject workspace context Off Auto-pass current note info to OpenCode Max notes 20 Maximum notes included in context Max selection length 2000 Character limit for text passed to AI Custom Commands Setting Default Description Use custom command Off Enable to customize OpenCode launch command Custom command (empty) Custom launch command (see Section 9) 7. First Use Opening the OpenCode Panel Three ways to open OpenCode:\nClick sidebar icon: Click the terminal icon in the left sidebar Shortcut: Ctrl + Shift + O (macOS: Cmd + Shift + O) Command palette: Ctrl/Cmd + P → type Toggle OpenCode panel First Launch Flow After opening the panel, the plugin automatically:\nDetects the OpenCode executable path Starts the OpenCode service (opencode serve) Loads the OpenCode interface in an embedded web view Once started, you\u0026rsquo;ll see the complete OpenCode dialog interface — type prompts directly.\nVerify Everything Works In the OpenCode interface, type:\n1 /help If you see the command list, everything is working. You can also type:\n1 /models to view available AI models. OpenCode has built-in free models (GLM-4.7, MiniMax-2.1) — no configuration needed.\nShortcut Reference Shortcut Function Ctrl/Cmd + Shift + O Toggle OpenCode panel 8. Context Injection (Experimental Feature) This is one of the opencode-obsidian plugin\u0026rsquo;s most unique features — it can automatically pass Obsidian\u0026rsquo;s working context to OpenCode.\nHow to Enable In plugin settings, toggle on \u0026ldquo;Inject workspace context\u0026rdquo;.\nWhat Gets Injected When enabled, the plugin automatically passes this information to the running OpenCode instance:\n📂 Currently open notes list: Which files you\u0026rsquo;re editing 📝 Selected text: Text you\u0026rsquo;ve highlighted in notes Use Cases Select some text, open the OpenCode panel, say \u0026ldquo;polish this paragraph\u0026rdquo; — AI already knows which text you mean Open multiple notes, ask AI \u0026ldquo;compare the differences between these two notes\u0026rdquo; — AI already knows which files are open Limitations ⚠️ This is an experimental feature with some current limitations:\nContext doesn\u0026rsquo;t auto-inject when creating a new Session in the OpenCode interface Context updates have some latency 9. Custom Command Mode By default, the plugin calls opencode serve to start the service. If you need more control, enable custom command mode.\nWhen Do You Need Custom Commands? Adding extra CLI arguments Using custom startup scripts Running OpenCode through containers or virtual environments OpenCode installed in non-standard paths Configuration Steps In plugin settings, turn on \u0026ldquo;Use custom command\u0026rdquo; Enter the complete command in the \u0026ldquo;Custom command\u0026rdquo; input field Command Template 1 opencode serve --port 14096 --hostname 127.0.0.1 --cors app://obsidian.md ⚠️ Important Notes Port and hostname must match the values in settings Must include --cors app://obsidian.md — otherwise Obsidian cannot embed the OpenCode web interface 10. FAQ and Troubleshooting ❌ OpenCode Executable Not Found Symptom: Panel shows \u0026ldquo;Executable not found at \u0026lsquo;opencode\u0026rsquo;\u0026rdquo;, but opencode works fine in terminal.\nCause: Electron (Obsidian\u0026rsquo;s underlying framework) doesn\u0026rsquo;t fully inherit system PATH environment variables on Windows.\nSolution:\nFind the full path of opencode.cmd in terminal: 1 where opencode.cmd Paste the full path into the plugin setting \u0026ldquo;OpenCode executable path\u0026rdquo;, e.g.: 1 C:\\Users\\YourUsername\\AppData\\Roaming\\npm\\opencode.cmd ❌ Service Startup Timeout Possible causes: Network issues, slow model loading, port in use.\nSolution:\nCheck if port 14096 is occupied by another program Try changing the port number (e.g., to 15096) Increase the startup timeout\n❌ Panel Shows Blank Possible cause: CORS configuration incorrect.\nSolution:\nIf using a custom command, ensure it includes --cors app://obsidian.md.\n❌ Panel Cannot Embed Possible cause: OpenCode version too old.\nSolution:\n1 npm i -g opencode-ai@latest ❌ Chinese Filename Garbled (Windows) Solution: Run in PowerShell:\n1 chcp 65001 Then restart Obsidian.\n❌ Plugin Needs Reconfiguration After Update BRAT preserves your settings data when updating. If settings are lost, just re-enter the settings page to reconfigure.\nSummary The entire installation flow in one diagram:\n1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 ┌──────────────────────────────────────────┐ │ Install BRAT Plugin │ │ Settings → Community marketplace │ │ → Search BRAT → Install │ └──────────────────┬───────────────────────┘ │ ▼ ┌──────────────────────────────────────────┐ │ Install opencode-obsidian via BRAT │ │ BRAT Settings → Add Beta plugin │ │ Enter: mtymek/opencode-obsidian │ └──────────────────┬───────────────────────┘ │ ▼ ┌──────────────────────────────────────────┐ │ Install OpenCode CLI │ │ npm i -g opencode-ai │ └──────────────────┬───────────────────────┘ │ ▼ ┌──────────────────────────────────────────┐ │ Enable plugin, start using │ │ Ctrl+Shift+O to open panel │ │ Use OpenCode directly in Obsidian │ └──────────────────────────────────────────┘ One-line summary: Install BRAT → Search mtymek/opencode-obsidian → Install OpenCode CLI → Ctrl+Shift+O and you\u0026rsquo;re set. It\u0026rsquo;s that simple.\n📚 Sources:\nopencode-obsidian GitHub Repository BRAT Plugin GitHub Repository OpenCode Official Documentation ","date":"2026-04-30T02:00:15+08:00","image":"/p/opencode--obsidian%E6%89%93%E9%80%A0%E4%BD%A0%E7%9A%84ai%E9%A9%B1%E5%8A%A8%E7%9F%A5%E8%AF%86%E7%AE%A1%E7%90%86%E5%B7%A5%E4%BD%9C%E6%B5%81/cover.svg","permalink":"/en/p/opencode--obsidian-build-your-ai-powered-knowledge-management-workflow/","title":"OpenCode + Obsidian: Build Your AI-Powered Knowledge Management Workflow"},{"content":"📋 Table of Contents 1. Session Parallelism: Let AI Handle Multiple Tasks Simultaneously 2. Ultra Work: One-Click AI Programming Team 3. @ Designate Agent: Let Experts Do What They Do Best 4. Timeline Time Machine: Experiment Freely, Rollback Anytime 5. Ralph Loop: Let AI Push Through to the End 6. Daily Speed Tips 7. Recommended Workflow for Beginners 8. A Real-World Case Study 📌 Key Points Summary Feature One-Line Description Session Parallelism OpenCode\u0026rsquo;s killer feature — multiple tasks running simultaneously, no interference, double efficiency Ultra Work Mode Type ULW, the main agent auto-breaks tasks and dispatches sub-agents to work in parallel @ Designate Agent Let the frontend expert do frontend, the architect do reviews — everyone does what they\u0026rsquo;re best at Timeline Time Machine Roll back to any historical checkpoint anytime, zero-cost experimentation Ralph Loop Let AI work in loops for hours, tackling the hardest tasks 1. Session Parallelism: Let AI Handle Multiple Tasks Simultaneously This is OpenCode\u0026rsquo;s greatest differentiating advantage over other AI programming tools. Traditional tools can only work sequentially — one task must finish before the next begins. OpenCode can run multiple Sessions simultaneously without interference.\nBasic Operations 1 2 3 4 /new # Create a new Session /sessions # View all Session statuses (spinning = running) /session \u0026lt;id\u0026gt; # Switch to a specific Session /session prev # Return to the previous Session Real-World Scenario Suppose you\u0026rsquo;re developing a \u0026ldquo;Draw and Guess\u0026rdquo; game with two independent requirements:\nRequirement A: Add a timer that starts on first brush stroke, game fails after 20 seconds Requirement B: Brush color adjustment Traditional Approach Finish A first, then B → Requirement B waits 5-10 minutes for nothing.\nOpenCode Approach 1 2 3 4 5 6 7 1. Enter requirement A, AI starts working 2. Enter /new, create a new Session 3. Enter requirement B, AI starts working 4. Enter /sessions to check progress: Session 1 ◐ Adding timer logic... Session 2 ◐ Adding color picker... Both requirements developed in parallel, total time compressed from 15 minutes to 8 minutes.\nNotes ⚠️ Sessions are completely isolated — modifying the same file may cause conflicts, assign to different modules ⚠️ Background Sessions don\u0026rsquo;t auto-notify completion, manually check with /sessions ✅ You can /new anytime to open a third, fourth\u0026hellip; no limit 2. Ultra Work: One-Click AI Programming Team If Session parallelism is \u0026ldquo;manual transmission,\u0026rdquo; then Ultra Work is \u0026ldquo;full self-driving.\u0026rdquo; Enter a magic word and AI automatically splits tasks, assigns them to the most suitable agents, and executes in parallel.\nTrigger Method Include any of these keywords in your prompt:\n1 2 3 ULW ultrawork Ultra Work How It Works 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Your requirement: Help me build a pet store website │ ▼ ┌─────────────────────────────┐ │ Sisyphus (Main Agent) │ │ 1. Break down → Todo List │ │ 2. Assign subtasks │ └──────┬──────────┬───────────┘ │ │ ┌────▼───┐ ┌───▼────┐ ┌────────▼────┐ │ Prophet │ │ Frontend│ │ Doc Writer │ │ Arch. │ │ UI Dev │ │ Docs Gen │ └────────┘ └────────┘ └─────────────┘ │ │ │ └──────────┴────────────┘ │ ▼ Complete Project Delivery Auto-split into Todo List Launch 3 background tasks running in parallel Main agent orchestrates from center Final delivery of complete project When to Use? Scenario Suitable Notes Create complete project from scratch ✅ Excellent Auto-splits frontend, backend, docs Multi-module parallel development ✅ Excellent Clear agent division of labor Single-file small changes ❌ Not recommended Overkill, actually slower Simple bug fix ❌ Not recommended Regular chat is faster 💡 The higher the complexity, the greater Ultra Work\u0026rsquo;s value. Simple tasks get slower due to scheduling overhead.\nActual Results Used Ultra Work mode to create a pet store website:\n✅ Used emojis as decorations with no image assets ✅ Clean interface, smooth interactions, complete animations 3. @ Designate Agent: Let Experts Do What They Do Best After installing Oh My OpenAgent (OMO), you have an AI programming team. Use @ to call specific agents.\nAgent Capability Table Agent Specialty Best Model Example Usage 🧠 Sisyphus Planning, task orchestration Claude Opus Complex multi-step tasks 🔮 Prophet Architecture design, code review GPT 5.5 Project structure design 🎨 Frontend Engineer UI development, page layout Gemini 3 Pro Responsive layout optimization 🔍 Explorer Web search, research MiniMax Find latest API docs 📚 Librarian Literature review, doc retrieval — Analyze open-source codebases 📝 Document Writer README, comments generation — Generate project docs 🖼️ Multimodal Image/PDF understanding — Write code from design mockups Usage Examples 1 2 3 4 5 6 7 @Frontend Engineer Convert this login page to responsive layout, mobile should look good too @Prophet Review the code under src/service/, find potential performance issues @Explorer Look up the latest usage of React 19 Server Components @Document Writer Generate API documentation for the entire project Switch Main Agent Press Tab to switch the main agent for the current conversation — great for extended use of a specific role.\n4. Timeline Time Machine: Experiment Freely, Rollback Anytime What\u0026rsquo;s the scariest thing in programming? Changing a ton of code, realizing the approach was wrong, and having no way back. Timeline is your undo button.\nBasic Usage 1 /timeline # List every conversation step in the current Session Select any node:\nRevert: Roll back both code and chat content to that point, like nothing happened View: See what modifications the AI made at that time Real-World Scenario 1 2 3 1. You had AI refactor a module → Results are unsatisfactory 2. /timeline → Select pre-refactor node → Revert 3. Code returns to pre-refactor state, try a different approach Tips 🕐 After completing a milestone, mentally note that checkpoint (which conversation step) 🕐 Boldly try radical approaches — one-click rollback anytime 🕐 Compare two approaches: Revert to Approach A → Check results → Revert to Approach B → Compare This is the programming version of \u0026ldquo;save/load\u0026rdquo; — explore any possibility fearlessly.\n5. Ralph Loop: Let AI Push Through to the End This mode makes AI work in continuous loops until the task is truly complete. Perfect for tough tasks requiring iterative refinement.\nLaunch Method 1 /ralph-loop Use Cases 1 2 3 4 5 \u0026#34;Refactor the entire project using the latest Spring Boot 4 standards until all test cases pass\u0026#34; \u0026#34;Check every file under src/ for code standard violations and fix each one\u0026#34; \u0026#34;Add complete unit tests to the project until coverage reaches 90%\u0026#34; Difference from Ultra Work Dimension Ultra Work Ralph Loop Mechanism Parallel split, multi-agent collaboration Serial loop, continuous iteration Best for Building from scratch, multi-module projects Refactoring, fixing, target-reaching tasks Duration Minutes to tens of minutes Potentially hours End point Task breakdown complete Termination condition met ⚠️ Ralph Loop may run for a long time — watch your API quota consumption.\n6. Daily Speed Tips 1. Use /compact to Save Context When you\u0026rsquo;ve chatted many rounds with AI and the context window is nearly full:\n1 /compact AI refines previous conversations into a summary, freeing space to continue working. No need to start a new chat and lose context.\n2. Use /init to Get AI Up to Speed on New Projects When entering a new project, have AI read through the code first:\n1 /init AI scans the entire project and generates agents.md as a system prompt. All subsequent conversations will be based on this understanding — massive efficiency boost.\n3. Share Your Programming Process 1 2 3 /share # Generate a share link showing complete conversation and code changes /unshare # Stop sharing, link becomes invalid /export # Export conversation history as a file Great for:\nShowing colleagues how you solved a problem with AI Documenting pitfalls for team reference 素材 for blog posts 4. View Available Models 1 /models # Models marked \u0026#34;free\u0026#34; are free to use GLM-4.7 and MiniMax-2.1 have decent programming capabilities, suitable for lightweight tasks.\n5. Quick Code Paste (VS Code Plugin) In VS Code, select a code snippet → Ctrl + Alt + K → Directly paste into OpenCode dialog.\nEliminates copy-paste switching costs, maintaining your flow state.\n7. Recommended Workflow for Beginners 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 ┌─────────────────────────────────────────────┐ │ New Requirement │ └──────────────────┬──────────────────────────┘ │ ▼ ┌────────────────┐ │ Simple? │ └───┬────────┬───┘ │ Yes │ No (Complex/Multi-module) ▼ ▼ ┌─────────────┐ ┌─────────────────┐ │ Regular chat │ │ Enter ULW to │ │ handles it │ │ trigger Ultra │ └─────────────┘ │ Work mode │ └────────┬────────┘ │ ┌──────────▼──────────┐ │ Multiple independent │ │ subtasks? │ └───┬──────────┬──────┘ │ Yes │ No ▼ ▼ ┌─────────────┐ ┌──────────────┐ │ /new open │ │ Wait for Ultra│ │ multiple │ │ Work to auto │ │ Sessions │ │ complete │ └──────┬──────┘ └──────────────┘ │ ▼ ┌─────────────┐ │ /sessions │ │ Check all │ │ progress │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ Wrong │ │ direction? │ └───┬─────────┘ │ ▼ ┌─────────────┐ │ /timeline → │ │ Revert │ └─────────────┘ One-Line Summary Small tasks chat directly, big tasks call ULW, parallel with Sessions, mistakes get Timeline rollback, stubborn problems activate Ralph Loop.\n8. A Real-World Case Study After installing Oh My OpenAgent, I wanted to adjust agent model configuration — making GitHub Copilot the primary and free OpenCode Zen the fallback.\nFirst Attempt Said directly in an OpenCode conversation:\n\u0026ldquo;I also have your free OpenCode Zen, but I\u0026rsquo;ve already logged into GitHub Copilot — help me modify it\u0026rdquo;\nAI set OpenCode Zen as primary — because the primary/secondary relationship wasn\u0026rsquo;t clear. ❌\nCorrection \u0026ldquo;No, GitHub Copilot should be primary, and OpenCode Zen\u0026rsquo;s built-in free model as fallback\u0026rdquo;\nAI immediately corrected it, updating oh-my-openagent.json so all Agents use github-copilot/* as primary and opencode/* as fallback. ✅\n💡 Lesson: When describing requirements to AI, always make the primary/secondary relationship clear — \u0026ldquo;XX as primary, YY as fallback\u0026rdquo; — don\u0026rsquo;t just say \u0026ldquo;add YY for me.\u0026rdquo;\n📚 Reference: OpenCode In-Depth Guide, Oh My OpenAgent 📅 Note generated: 2026-05-07\n","date":"2026-04-30T02:00:15+08:00","image":"/p/opencode-%E6%96%B0%E6%89%8B%E8%BF%9B%E9%98%B6%E5%B9%B6%E8%A1%8C%E8%B0%83%E5%BA%A6%E4%B8%8E%E4%BD%BF%E7%94%A8%E6%8A%80%E5%B7%A7%E5%85%A8%E6%94%BB%E7%95%A5/cover.svg","permalink":"/en/p/opencode-beginner-to-advanced-a-complete-guide-to-parallel-scheduling-and-usage-tips/","title":"OpenCode Beginner to Advanced: A Complete Guide to Parallel Scheduling and Usage Tips"},{"content":"📋 Table of Contents 1. What is OpenCode? 2. Four Installation Forms 3. Free Model Configuration 4. Core Feature Highlights 5. Skills Migration 6. MCP Configuration 7. Oh My Open Code (OMO) Super Plugin 8. Other Useful Features 9. Summary and Recommendations 10. Hands-on Record: Installing Oh My OpenAgent Appendix: Troubleshooting Notes 1. What is OpenCode? OpenCode is currently the hottest AI programming tool, essentially an open-source version of Claude Code. It has replicated almost all core features of Claude Code while solving common pain points for Chinese users such as rate limiting and account bans.\nComparison with Claude Code Dimension Claude Code OpenCode Open Source ❌ Closed source ✅ Open source Free models ❌ Paid API required ✅ Built-in free models China-friendly ⚠️ Rate limit/ban risk ✅ No restrictions Skills/MCP ✅ Supported ✅ Fully compatible Session parallelism ❌ ✅ Core highlight Core Positioning Open-source Claude Code: Nearly all features, China-friendly, no rate limits or bans Free models: Out-of-the-box GLM-4.7, MiniMax-2.1 and other free models, zero configuration needed Top-tier model integration: Free access to Gemini 3 Pro and Claude 4.5 Opus via Antigravity plugin; GPT Codex via /connect Killer features: Session parallelism, Timeline rollback, Share, Ultra Work multi-agent collaboration Plugin ecosystem: Oh My Open Code (OMO) with seven programming agents + three MCP Servers + various tools 2. Four Installation Forms ⭐ 1. Command Line Version (Primary Recommendation) The most stable and feature-complete way to use it.\n1 2 3 4 5 # Install (Node.js required first) npm i -g opencode-ai # Launch opencode Prerequisite: Node.js must be installed (download from nodejs.org)\n2. Desktop Client (Beta) Download the client from the official website, install it, and select your project folder.\n⚠️ Currently in Beta testing phase with more bugs — not recommended as your primary tool yet.\n3. VS Code Plugin Version Prerequisite: OpenCode CLI must be installed. The plugin\u0026rsquo;s core value lies in seamless IDE integration, letting AI directly perceive your code context.\nSearch for OpenCode in the VS Code Extensions marketplace and install it Shortcut Ctrl + Shift + P → type open opencode and press Enter The plugin automatically associates with code files open in the left panel Select code and press Ctrl + Alt + K to quickly paste into the OpenCode chat window 4. Cloud Runtime Environment (GitHub Actions) Perfect for automated Issue fixing in open-source projects:\nUpload your project to a public GitHub repository Configure API Key in the repository (Settings → Secrets and Variables → Actions) Type /opencode + requirement description in an Issue comment GitHub Actions automatically runs the OpenCode workflow Automatically creates a Pull Request upon completion 3. Free Model Configuration View Available Models 1 /models # View all available models (ones marked \u0026#34;free\u0026#34; can be used at no cost) Recommended Free Models Model Features GLM-4.7 Strong programming ability, zero configuration MiniMax-2.1 Excellent programming skills, fast response 💡 These two free models are more than enough for beginners practicing AI programming.\nConnect Top-tier Models Method 1: Antigravity Plugin (Free Gemini + Claude Access) Antigravity is Google\u0026rsquo;s AI programming IDE, generously providing Gemini 3 Pro and Claude 4.5 Opus for free.\nPaste the installation prompt in OpenCode (copy from the Antigravity GitHub homepage) Wait for AI to complete the installation automatically Open a new terminal and run the login command, select Google → Antigravity login Log in to your Google account, paste the generated URL Restart OpenCode — Gemini 3 Pro and Claude 4.5 Opus will appear in /models Method 2: GPT Codex (Official OpenAI Partnership) OpenAI has officially partnered with OpenCode, enabling direct ChatGPT Codex integration.\n1 /connect # Select OpenAI → GPT Pro → Browser login Prerequisite: ChatGPT Plus subscription or higher required.\nMethod 3: OpenRouter (Universal Connector) OpenRouter provides access to virtually every major model available, and Chinese users can easily obtain credits.\n1 /connect # Select OpenRouter → Enter API Key OpenCode supports 75 AI integration methods, covering almost all model providers.\n4. Core Feature Highlights 1. Clarifying Questions Before Coding Before starting to code, OpenCode will ask you a series of questions:\nDo you just need a code sample, or a complete runnable program? Which features are must-haves? Which model should be used? How should environment variables be stored? This \u0026ldquo;ask first, act later\u0026rdquo; mechanism significantly reduces rework.\n2. Command Line Code Diff Interface OpenCode\u0026rsquo;s command line diff display is considered the best among all command line programming tools, making code changes clear at a glance.\n⭐ 3. Session Parallel Processing This is OpenCode\u0026rsquo;s most distinctive feature — multiple Sessions running in parallel:\n1 2 3 4 5 6 7 8 9 10 # Start the first task (e.g., add a timer) # While the task is running, create a new session /new # Start the second task (e.g., brush color) # View all session statuses /sessions # Switch between sessions /session \u0026lt;id\u0026gt; The spinning symbol indicates a Session is running in the background. Two tasks can be developed in parallel without interfering with each other.\n4. Timeline Checkpoint Rollback 1 /timeline # View the complete conversation history of the current Session Select any historical node:\nRevert: Roll back both code and chat content to that point in time View: See what modifications the AI made at that time Like a \u0026ldquo;time machine\u0026rdquo; for programming, allowing you to boldly try different approaches.\n5. Share 1 2 3 /share # Share conversation history as a web page /unshare # Stop sharing /export # Export conversation history as a file After sharing, a web link is generated displaying the complete conversation history and code modification process, convenient for collaboration or demonstration.\n5. Skills Migration OpenCode is fully compatible with Claude Code\u0026rsquo;s Skills directory structure, making migration extremely easy:\n1 2 # Directory structure mapping .claude/skills/\u0026lt;skill-name\u0026gt;/ → .opencode/skills/\u0026lt;skill-name\u0026gt;/ Steps Create a new .opencode folder in the project root directory Create a skills folder inside .opencode Copy the skill folders from .claude/skills/ directly into it Restart OpenCode — the AI will recognize and call these Skills Each Skill is essentially an instruction manual with its own directory, telling the AI how to complete tasks in a specific domain.\n6. MCP Configuration OpenCode supports two MCP (Model Context Protocol) modes:\nLocal MCP Executed via local commands. Configure in ~/.config/opencode/opencode.json:\n1 2 3 4 5 6 7 8 9 10 { \u0026#34;mcpServers\u0026#34;: { \u0026#34;shed-cn\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;local\u0026#34;, \u0026#34;command\u0026#34;: \u0026#34;npx\u0026#34;, \u0026#34;args\u0026#34;: [\u0026#34;shed-cn\u0026#34;], \u0026#34;enabled\u0026#34;: true } } } Remote MCP Called remotely via URL. Using Context7 as an example:\n1 2 3 4 5 6 7 8 9 10 11 12 { \u0026#34;mcpServers\u0026#34;: { \u0026#34;context7\u0026#34;: { \u0026#34;type\u0026#34;: \u0026#34;remote\u0026#34;, \u0026#34;url\u0026#34;: \u0026#34;https://context7-mcp-server-url\u0026#34;, \u0026#34;headers\u0026#34;: { \u0026#34;Authorization\u0026#34;: \u0026#34;Bearer \u0026lt;your-api-key\u0026gt;\u0026#34; }, \u0026#34;enabled\u0026#34;: true } } } After configuration, restart OpenCode and enter /mcp to view configured MCP Servers.\n7. Oh My Open Code (OMO) Super Plugin ⭐ OMO is the most popular programming plugin for OpenCode, essentially a bundled package of Tools + MCP + Programming Agents.\nSeven Programming Agents Agent Role Recommended Model 🧠 Sisyphus Main agent, planning \u0026amp; orchestration Claude 4.5 Opus / GPT 5.2 🔮 Prophet Architecture design, code review — 📚 Librarian Literature review, document retrieval — 🔍 Explorer Web search — 🎨 Frontend Engineer Frontend development Gemini 3 Pro 📝 Document Writer Document generation — 🖼️ Multimodal Image/PDF understanding — Each agent is assigned the most suitable model for its work. The author reportedly spent $24,000 worth of Tokens to find the optimal combination.\nThree MCP Servers Web Search: Web search Context7: Access latest technical documentation Grep App: Fast code search across GitHub repositories Integrated Tools LSP Advanced: Helps AI quickly locate code through language syntax and semantics AST Tool: Related search through code syntax trees LOC Tool: Understand images and PDFs via multimodal vision Delegate Task / Background Task: Agent task assignment and background scheduling Installation and Usage Configuration file location: C:\\Users\\\u0026lt;username\u0026gt;\\.config\\opencode\\oh-my-opencode.json\nCopy the install prompt from the OMO GitHub homepage Paste it into OpenCode and answer configuration questions (subscription status, etc.) Installation completes automatically Two Core Usage Patterns ① @ Designate Specific Agent 1 @Frontend Engineer Help me optimize the responsive layout of this page ② Ultra Work Mode (Magic Word ULW) 1 ULW Help me create a pet store application In Ultra Work mode, Sisyphus as the main agent will:\nBreak down tasks into a Todo List Launch multiple background tasks running in parallel Orchestrate all agents from the center Deliver the complete project Ralph Loop Mode Forces AI to work in continuous loops, suitable for extremely difficult tasks:\n1 /ralph-loop Example: \u0026ldquo;Refactor the entire project using the latest Spring Boot 4 standards until all test cases pass\u0026rdquo; — can run for hours until the task is complete.\n8. Other Useful Features /init — Project Knowledge Initialization Let AI read through the entire project folder, generating an agents.md file as a system prompt to help AI quickly understand the project.\n/compact — Context Compression Refine previous conversations into a concise summary, freeing up the model\u0026rsquo;s context window to avoid Token overflow.\nCustom Commands Create .md files under ~/.config/opencode/commands/ to define custom commands:\n1 2 3 4 # Run Tests Mode: build Command: npm test Description: Run all test cases for the project Usage: /Run Tests to trigger.\nCustom Agents Create .md files under ~/.config/opencode/agents/:\n1 2 3 4 # Code Review Agent Type: subagent Model: claude-4.5-opus Description: Specializes in code review, checking code quality, security vulnerabilities, and best practices. Primary Agent: Switch with Tab key, use directly in conversation Sub Agent: Automatically dispatched by the main agent in the background 9. Summary and Recommendations Use Cases Scenario Rating Notes Beginner AI programming ⭐⭐⭐⭐⭐ Free models, zero-cost start Daily development assistance ⭐⭐⭐⭐⭐ Session parallelism + Timeline rollback Complex project development ⭐⭐⭐⭐⭐ OMO plugin multi-agent collaboration Open-source project maintenance ⭐⭐⭐⭐ GitHub Actions cloud automation Skills/MCP practice ⭐⭐⭐⭐⭐ Fully compatible with Claude Code ecosystem Recommended Configuration Path 1 2 3 4 5 6 7 Beginner → CLI installation + built-in free models ↓ Advanced → Configure Antigravity for Gemini/Claude access ↓ Efficient → Configure Skills + MCP ↓ Ultimate → Install OMO plugin, enable Ultra Work mode OpenCode breaks down the high barriers of AI programming tools, allowing everyone to explore the infinite possibilities of AI-assisted programming at zero cost. Especially for Chinese users, there\u0026rsquo;s no longer any need to worry about rate limits and bans — you can \u0026ldquo;build freely, experiment freely.\u0026rdquo;\n10. Hands-on Record: Installing Oh My OpenAgent Below is the complete conversation record from personally installing Oh My OpenAgent (formerly Oh My Open Code), in a Windows + PowerShell environment.\nEnvironment Check 1 2 opencode --version # Output: 1.14.39 Installation Process Tell AI directly in an OpenCode conversation:\n\u0026ldquo;Install and configure oh-my-openagent by following the instructions here: https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md\"\nAI will first ask about your model subscriptions:\nSubscription My Status Claude Pro/Max ❌ None OpenAI / ChatGPT Plus ❌ None Gemini ❌ None GitHub Copilot ✅ Student certified OpenCode Zen ✅ Free available Z.ai Coding Plan ❌ None OpenCode Go ❌ None Kimi for Coding ❌ None Vercel AI Gateway ❌ None ⚠️ AI will prompt \u0026ldquo;Without a Claude subscription, the Sisyphus agent might not work ideally\u0026rdquo; — but GitHub Copilot will automatically take over as a fallback model.\nAfter confirming subscriptions, AI automatically executes the installation command:\n1 2 3 4 5 bunx oh-my-openagent install --no-tui \\ --claude=no --openai=no --gemini=no \\ --copilot=yes --opencode-zen=yes \\ --zai-coding-plan=no --opencode-go=no \\ --kimi-for-coding=no --vercel-ai-gateway=no Successful installation output:\n1 2 3 4 [1/4] Checking OpenCode installation... [OK] OpenCode 1.14.39 detected [2/4] Adding oh-my-openagent plugin... [OK] Plugin added -\u0026gt; C:\\Users\\\u0026lt;username\u0026gt;\\.config\\opencode\\opencode.json Post-Installation Configuration Files Main configuration file ~/.config/opencode/opencode.json:\n1 2 3 4 5 { \u0026#34;plugin\u0026#34;: [ \u0026#34;oh-my-openagent@latest\u0026#34; ] } Agent model configuration ~/.config/opencode/oh-my-openagent.json:\nAI automatically assigned models based on GitHub Copilot subscription:\nAgent Assigned Model Sisyphus (Main agent) github-copilot/claude-opus-4.7 Oracle (Prophet) github-copilot/gpt-5.5 (medium) Other Agents Auto-selected from Copilot available models Authentication Configuration After installation, you need to manually authenticate GitHub Copilot:\n1 opencode auth login Interactive steps:\nUse arrow keys to select GitHub Copilot Press Enter to confirm Browser opens automatically, log in to your GitHub student account Authorization complete, terminal shows successful authentication How to Reconfigure Agent Models? Method 1: Tell AI Directly \u0026ldquo;Change Sisyphus\u0026rsquo;s model to claude-sonnet-4.6\u0026rdquo; \u0026ldquo;Oracle use gpt-5.5\u0026rdquo;\nMethod 2: Manually Edit Configuration File Directly modify the model field for the corresponding agent in ~/.config/opencode/oh-my-openagent.json.\nAdditional Configuration: Add OpenCode Zen as Fallback The free OpenCode Zen was missed during installation (--opencode-zen=no). In a new OpenCode conversation, ask AI to fix it:\n\u0026ldquo;I also have your free OpenCode Zen, but I\u0026rsquo;ve already logged into GitHub Copilot — help me modify it\u0026rdquo;\nAI\u0026rsquo;s first attempt set OpenCode Zen as primary (opencode/claude-opus-4-7), making GitHub Copilot the fallback. The actual need was the opposite:\n\u0026ldquo;No, GitHub Copilot should be primary, and OpenCode Zen\u0026rsquo;s built-in free model as fallback\u0026rdquo;\nAfter AI corrected it, the final configuration strategy:\n1 2 Primary model: github-copilot/* (paid, use first) Fallback model: opencode/* (free credits, auto-switch when Copilot unavailable) Key configuration snippet (using Sisyphus as example):\n1 2 3 4 5 6 7 8 9 { \u0026#34;sisyphus\u0026#34;: { \u0026#34;model\u0026#34;: \u0026#34;github-copilot/claude-opus-4-7\u0026#34;, \u0026#34;fallback_models\u0026#34;: [ { \u0026#34;model\u0026#34;: \u0026#34;opencode/claude-opus-4-7\u0026#34; }, { \u0026#34;model\u0026#34;: \u0026#34;opencode/gpt-5.5\u0026#34; } ] } } 💡 Tip: When describing configuration needs, make the primary/secondary relationship clear — \u0026ldquo;XX as primary, YY as fallback\u0026rdquo; — to avoid AI getting it reversed.\nUsage Tips After installation, type opencode in the terminal to get started:\nInclude ultrawork or ulw in your prompt to trigger automatic parallel processing Press Tab to enter Prometheus (planner) mode Run /start-work to execute full orchestration Appendix: Troubleshooting Notes Issue Solution doctor command timeout (30s) Some checks may hang; add --verbose to troubleshoot, or skip — it doesn\u0026rsquo;t affect usage PowerShell if syntax errors OpenCode\u0026rsquo;s bash commands need syntax conversion under PowerShell Sisyphus performance drops with non-Claude models This is a known limitation; experience is best with a Claude subscription AI swaps primary/fallback models State the primary/secondary relationship clearly: \u0026ldquo;XX as primary, YY as fallback\u0026rdquo; — don\u0026rsquo;t just say \u0026ldquo;add YY for me\u0026rdquo; 📚 Sources: Tech Shrimp - OpenCode Detailed Guide, Oh My OpenAgent Installation Guide\n","date":"2026-04-30T02:00:15+08:00","image":"/p/opencode-%E5%85%A8%E6%B7%B1%E5%BA%A6%E6%8C%87%E5%8D%97%E5%BC%80%E6%BA%90%E7%89%88-claude-code-%E7%9A%84%E5%AE%89%E8%A3%85%E9%85%8D%E7%BD%AE%E4%B8%8E%E9%AB%98%E7%BA%A7%E7%8E%A9%E6%B3%95/cover.svg","permalink":"/en/p/opencode-in-depth-guide-installation-configuration-and-advanced-techniques-for-the-open-source-claude-code/","title":"OpenCode In-Depth Guide: Installation, Configuration, and Advanced Techniques for the Open-Source Claude Code"},{"content":"Overview Who Is This Tutorial For? This tutorial is for users with no computer background at all. You don\u0026rsquo;t need to know what a \u0026ldquo;command line\u0026rdquo; is, what \u0026ldquo;environment variables\u0026rdquo; are, or what \u0026ldquo;version management\u0026rdquo; is — I will break down every step to the finest detail, telling you where to click, what to click, what to type, and what you should see to know it worked.\nWhat Are We Installing? Why Do We Need These? Before we start, let\u0026rsquo;s understand the 3 things we need to install and what each one does:\n# Software One-Line Explanation Why It\u0026rsquo;s Required 1 Node.js The \u0026ldquo;engine\u0026rdquo; that lets your computer run JavaScript programs Claude Code is written in JavaScript and won\u0026rsquo;t run without it 2 Claude Code An AI programming assistant that lives in your computer\u0026rsquo;s terminal This is what we ultimately want to use 3 CC-Switch A small tool to \u0026ldquo;swap the brain\u0026rdquo; of Claude Code Switches Claude Code from the expensive official model to the affordable DeepSeek The whole process takes about 10-15 minutes. Please follow the steps in order — don\u0026rsquo;t skip around.\n📌 Prerequisites You need a Windows computer (Windows 10/11) with a working internet connection.\nInstall Node.js What is Node.js? Node.js = the runtime environment that lets your computer run Claude Code. It\u0026rsquo;s completely free. Just like you need Windows installed before you can run software, you need Node.js installed before you can run Claude Code.\nDownload Node.js Step 1: Open Your Browser\nOpen any browser on your computer (Chrome, Edge, or Firefox).\nStep 2: Visit the Node.js Official Website\nType the following URL into the browser\u0026rsquo;s address bar (the long bar at the top where you enter web addresses) and press Enter:\n1 https://nodejs.org/ Step 3: Find the Download Button\nOnce the page loads, you\u0026rsquo;ll see two large buttons in the center:\nThe left button says LTS (with a recommended version number, e.g., 22.16.0 LTS) The right button says Current Click the left LTS button — your browser will automatically start downloading a .msi file.\nStep 4: Find the Downloaded File\nOnce the download completes (usually just a few seconds), there are two ways to find the file:\nMethod 1: Click the download list in the top-right corner of your browser (usually a downward arrow ↓ icon) and find the file you just downloaded — the filename will be something like node-v22.16.0-x64.msi Method 2: Open File Explorer (the window you use to browse folders), find the Downloads folder in the left sidebar, and the file will be inside Install Node.js Step 1: Double-click the Installer\nIn the Downloads folder, find node-v22.16.0-x64.msi (the version number may differ slightly) and double-click it.\nStep 2: Welcome Screen\nA window titled Node.js Setup will appear. Click the Next button at the bottom.\nStep 3: License Agreement\nThe window displays a long block of English license text.\nCheck the box in the bottom-left corner: I accept the terms in the License Agreement Click Next Step 4: Installation Location (⚠️ Important! You Need to Change the Path)\nThis shows where Node.js will be installed on your computer.\nThe default path is: C:\\Program Files\\nodejs\\\n📌 Move It to the D Drive! It\u0026rsquo;s recommended to install to the D drive because:\nThe C drive is your system drive — putting too much on it slows down your computer The D drive is for software — if you ever need to reinstall Windows, everything on D stays safe It\u0026rsquo;s easier to manage and find things Steps to change:\nClick inside the path input box, select everything (press Ctrl + A), then delete it Type the new path: 1 D:\\nodejs\\ Click Next 💡 Note Make sure the path has no Chinese characters or spaces, or the installation may fail.\nStep 5: Custom Setup\nA page with a tree-like checkbox list appears (Custom Setup).\nDon\u0026rsquo;t change anything — just click Next.\nStep 6: Confirm Installation\nClick the Install button. If a security prompt appears, click Yes.\nStep 7: Wait for Installation\nThe progress bar will complete — usually takes just 10-30 seconds.\nStep 8: Finish\nClick Finish.\nNode.js Installation Complete! Both Node.js and npm (Node.js\u0026rsquo;s package manager — think of it as an \u0026ldquo;app store\u0026rdquo;) are now installed.\nVerify Node.js Is Installed Correctly After installation, we need to verify everything — like checking your groceries to make sure nothing\u0026rsquo;s missing.\nStep 1: Open Command Prompt (CMD)\nWhat is \u0026ldquo;Command Prompt\u0026rdquo;? Command Prompt (also called CMD) is a black window with white text where you can type text commands to make your computer do things. You\u0026rsquo;ll use it often going forward.\nHow to open it (choose one):\nMethod 1 (Recommended):\nHold down the Win key on your keyboard (bottom-left corner, the key with the Windows logo) While holding it, press the R key A small window titled \u0026ldquo;Run\u0026rdquo; will pop up — type cmd in it Click OK or press Enter Method 2:\nClick the Start menu in the bottom-left corner of your desktop (Windows icon) Type cmd in the search box Click Command Prompt in the search results Step 2: Enter Verification Commands\nIn the black window that opens, type the following (the characters will appear on screen as you type), then press Enter:\n1 node -v If the window displays something like v22.16.0, Node.js is installed successfully ✅\nNow type this command and press Enter:\n1 npm -v If it displays a version number like 10.9.2, npm is also working ✅\n⚠️ Seeing \u0026ldquo;\u0026rsquo;node\u0026rsquo; is not recognized as an internal or external command\u0026rdquo;? Your environment variables aren\u0026rsquo;t set up correctly. See 1.4 How to Configure Environment Variables below.\nHow to Configure Environment Variables What Are Environment Variables (PATH)? PATH can be thought of as your computer\u0026rsquo;s \u0026ldquo;address book.\u0026rdquo; When you type node in the command prompt, your computer doesn\u0026rsquo;t know where node is installed — it looks it up in PATH, the \u0026ldquo;address book.\u0026rdquo; If Node.js\u0026rsquo;s installation directory isn\u0026rsquo;t in PATH, the computer can\u0026rsquo;t find it and reports \u0026ldquo;\u0026rsquo;node\u0026rsquo; is not recognized.\u0026rdquo;\nNormally, the Node.js installer adds itself to PATH automatically. But if something goes wrong, you need to add it manually.\nCheck If Node.js Is Already in PATH\nPress Win + R, type sysdm.cpl, press Enter Click the Advanced tab at the top Click the Environment Variables button at the bottom In the System variables list at the bottom, find the Path row, select it, and click Edit In the list that pops up, check if there\u0026rsquo;s an entry like:\n1 D:\\nodejs\\ 💡 The Path Must Match Where You Installed If you installed to D:\\Software\\nodejs\\, then the entry should show D:\\Software\\nodejs\\.\nIf the entry exists: PATH is fine, but if it\u0026rsquo;s still not working, close all current Command Prompt windows and open a new one, then try again.\nIf the entry doesn\u0026rsquo;t exist: Follow the steps below to add it manually.\nManually Add Node.js to PATH\nIn the Edit Environment Variable window you just opened, click New Type the Node.js installation path: 1 D:\\nodejs\\ Click OK Click OK to close the Environment Variables window Click OK to close the System Properties window Close all open Command Prompt windows and open a new one (old windows won\u0026rsquo;t pick up the new settings) Type node -v again to verify Configure npm Domestic Mirror (Strongly Recommended) 💡 Why Configure This? By default, npm downloads software from overseas, which is very slow. Configuring a domestic mirror speeds up downloads by more than 10 times.\nIn Command Prompt, type the following command and press Enter:\n1 npm config set registry https://registry.npmmirror.com/ Verify with this command — if it shows https://registry.npmmirror.com/, it worked ✅:\n1 npm config get registry Step 1 Complete! You\u0026rsquo;ve installed Node.js on your computer and configured the domestic mirror. Now let\u0026rsquo;s install Claude Code.\nInstall Claude Code Install Claude Code via npm Open Command Prompt (if not already open), type the following command, and press Enter:\n1 npm install -g @anthropic-ai/claude-code Wait for the installation to finish (usually 1-3 minutes). Text will scroll on the screen — as long as there\u0026rsquo;s no error at the end, you\u0026rsquo;re fine.\nVerify Installation Type:\n1 claude --version Press Enter. If it shows a version number (e.g., 1.0.x), installation was successful ✅\nFirst Launch (Skip Login) Why Skip Login? Claude Code officially requires you to log in with an Anthropic account. But Anthropic\u0026rsquo;s services require an overseas credit card for payment, which is inconvenient for domestic users.\nOur approach: skip login first, then use the CC-Switch tool to connect to the domestic DeepSeek model. This way you don\u0026rsquo;t need an Anthropic account at all, and the cost is much lower.\nStep 1: Launch Claude Code Once\nType this in Command Prompt:\n1 claude Press Enter. Claude Code will launch and may display some introductory information or ask you to log in.\nIgnore it — just close the Command Prompt window (click the × in the top-right corner).\nStep 2: Find the Configuration File\nPress Win + R (Win key and R key at the same time) In the \u0026ldquo;Run\u0026rdquo; window that pops up, type %USERPROFILE% Click OK or press Enter You\u0026rsquo;ll see a folder with various files and subfolders Step 3: Find the .claude.json File\nIn this folder, look for a file named .claude.json.\n⚠️ Can\u0026rsquo;t Find This File? If you can\u0026rsquo;t find .claude.json, possible reasons:\nFile extensions are hidden — in the folder window, click View → check File name extensions and Hidden items Claude Code hasn\u0026rsquo;t created this file yet — go back to Step 1 and make sure you launched Claude Code at least once In some cases, the file might be inside the .claude folder, named settings.json Step 4: Open the Config File with Notepad\nRight-click the .claude.json file In the popup menu, select Open with Choose Notepad If Notepad isn\u0026rsquo;t in the list, select Choose another app → find Notepad in the list → click OK Step 5: Edit the Config File\nWhen you open it, you\u0026rsquo;ll see something like this (the exact content may vary):\n1 2 3 4 { \u0026#34;someField\u0026#34;: \u0026#34;someValue\u0026#34;, \u0026#34;anotherField\u0026#34;: \u0026#34;anotherValue\u0026#34; } We need to add the line \u0026quot;hasCompletedOnboarding\u0026quot;: true before the final }.\nAfter editing, it should look like this:\n1 2 3 4 5 { \u0026#34;someField\u0026#34;: \u0026#34;someValue\u0026#34;, \u0026#34;anotherField\u0026#34;: \u0026#34;anotherValue\u0026#34;, \u0026#34;hasCompletedOnboarding\u0026#34;: true } 📌 ⚠️ Three Critical Details — Get These Wrong and It\u0026rsquo;ll Break! Add a comma: the line before hasCompletedOnboarding needs an English comma , at the end Use English quotes: the quotes must be English \u0026quot;, not Chinese \u0026quot; true is lowercase: it must be true, not True Step 6: Save the File\nPress Ctrl + S to save (or click File → Save in the top-left corner) Close the Notepad window Step 7: Verify Skip Login Worked\nReopen Command Prompt (Win + R → cmd → Enter) Type claude, press Enter If you go straight into Claude Code\u0026rsquo;s main interface (with no login prompt), skip-login was successful ✅ Step 2 Complete! Claude Code is installed and login has been skipped. Now let\u0026rsquo;s install CC-Switch to connect DeepSeek.\nInstall CC-Switch (Model Switching Tool) What Is CC-Switch? CC-Switch is a visual tool that lets you swap Claude Code\u0026rsquo;s \u0026ldquo;brain\u0026rdquo; from the official model to DeepSeek — no manual config file editing needed, just point and click.\nDownload CC-Switch Step 1: Open the Download Page\nType the following URL into your browser\u0026rsquo;s address bar and press Enter:\n1 https://github.com/cc-switch/cc-switch/releases Step 2: Find the Latest Version\nOnce the page loads, find the version with the green Latest label and click to expand it.\nStep 3: Find the Download Link\nAfter expanding, scroll down, find the word Assets (there may be a small arrow ▾ next to it), and click to expand it.\nFind the file ending with .msi (Windows installer) and click the filename to start the download.\n💡 Which File to Choose? Windows computer: choose the file ending in x64.msi Mac computer: choose the file ending in .dmg Install CC-Switch Step 1: Double-click the Installer\nIn the Downloads folder, double-click the downloaded .msi file. If a security prompt appears, click Run anyway or More info → Run anyway.\nStep 2: Follow the Prompts\nThe installation wizard is similar to Node.js:\nClick Next Accept the agreement → Next Keep the default installation path → Next Click Install Wait for installation to complete → Finish Step 3 Complete! CC-Switch is installed. Now let\u0026rsquo;s get a DeepSeek API Key.\nGet a DeepSeek API Key What Is DeepSeek? A domestic large language model with powerful performance and low pricing (about 10-30 RMB per month for daily use). Connecting to it dramatically reduces your usage costs.\nWhat Is an API Key? An API Key is a key used to access DeepSeek\u0026rsquo;s AI services. Each use deducts from your account balance. You need to: ① Register an account ② Add funds ③ Create a Key\nRegister a DeepSeek Account Step 1: Open the DeepSeek Open Platform\nType this into your browser\u0026rsquo;s address bar:\n1 https://platform.deepseek.com/ Press Enter.\n💡 Note This is DeepSeek\u0026rsquo;s developer platform (platform.deepseek.com), not the chat website (chat.deepseek.com). Don\u0026rsquo;t mix them up.\nStep 2: Register / Log In\nIn the top-right corner of the page, there are Log In / Sign Up buttons Click Sign Up (if you don\u0026rsquo;t have an account) or Log In (if you already have one) Follow the on-screen prompts to complete registration Add Funds to Your Account 💡 Cost Reference Daily use costs only about 10-30 RMB per month. A first-time top-up of 20-50 RMB is recommended.\nAfter logging in, find Top Up (or Wallet / Billing) in the left sidebar menu and click it Select the amount, choose a payment method, and complete the payment Make sure your account balance is greater than 0 (you can\u0026rsquo;t use the API without a balance) Create an API Key Step 1: Go to the API Keys Page\nAfter logging in, find API Keys in the left sidebar menu and click it You\u0026rsquo;ll see an API Keys management page Step 2: Create a New API Key\nClick the Create API Key button A dialog will pop up asking you to name your Key You can name it anything — claude-code, my-key, test are all fine The name is just for your own reference to distinguish different Keys Click Confirm or Create Step 3: Copy the API Key (⚠️ Most Critical Step!)\nOnce created, the page will display your API Key in a format like:\n1 sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ⚠️ This Key Is Only Shown Once! After you close the dialog, you\u0026rsquo;ll never see it again. Copy and save it immediately to Notepad or WeChat File Transfer.\n🚨 Security Reminder An API Key is equivalent to your account password. Don\u0026rsquo;t share it with anyone and don\u0026rsquo;t post it publicly. If you suspect it\u0026rsquo;s been leaked, delete it immediately and create a new one.\nStep 4 Complete! You now have a DeepSeek API Key. For the final step, we\u0026rsquo;ll give this key to CC-Switch to complete the connection.\nConfigure CC-Switch to Connect DeepSeek Open CC-Switch Find the CC-Switch icon on your desktop or in the Start menu and double-click to open it.\nAdd a DeepSeek Configuration Step 1: Click the Add Button\nOnce CC-Switch opens, find the + button (plus sign) in the top-right corner and click it.\nStep 2: Fill In the Configuration\nAfter clicking +, a configuration panel will pop up. Fill in the following:\n① Model Preset: Select DeepSeek\n② API Key: Paste the DeepSeek API Key you copied earlier (make sure there are no leading or trailing spaces)\n③ Model Name: Delete whatever is in the input box and type:\n1 deepseek-v4-pro[1m] ④ Base URL / API Address (if present):\n1 https://api.deepseek.com Step 3: Save the Configuration\nAfter double-checking all fields, click Add / Save / Confirm.\nSwitch to DeepSeek Return to CC-Switch\u0026rsquo;s main interface You\u0026rsquo;ll see the DeepSeek configuration you just added in the list Click the Switch / Enable button next to that configuration The interface should show \u0026ldquo;Current Model: DeepSeek\u0026rdquo; or similar Verify the Connection Open Command Prompt and type claude to launch Claude Code.\nInside Claude Code, type:\n1 /model Press Enter. If the displayed model info includes DeepSeek, the connection is successful ✅\nAll Configuration Complete! You can now start using the AI programming assistant!\nStart Using It (Hands-on Example) Now that everything is configured, let\u0026rsquo;s do a simple exercise to make sure it all works.\nCreate a Project Folder and Open Command Prompt Right-click on the desktop → New → Folder, name it my-first-ai-project Double-click to open the folder Click the address bar at the top of the window, type cmd, and press Enter Launch Claude Code In the Command Prompt window that appears, type:\n1 claude Press Enter. If asked whether to trust this folder, type y and press Enter.\nGive Your First Instruction Once Claude Code starts, type the following (you can use plain English):\n1 Help me create a simple personal homepage using HTML + CSS + JavaScript, with a title, a short self-introduction, and a dark mode toggle button Press Enter to submit.\nHandle Permission Requests During execution, Claude Code may ask for permission to create/modify files — just select Yes. For your own projects, you can choose Yes, always allow (won\u0026rsquo;t ask again).\nCheck the Result After completion, go back to the project folder and double-click index.html — it\u0026rsquo;ll open in your browser, and you\u0026rsquo;ll see the webpage the AI created for you!\nCongratulations! You\u0026rsquo;ve completed your first project with Claude Code + DeepSeek!\nCommand Quick Reference Operation Command Description Check Node.js version node -v Verify Node.js is installed Check npm version npm -v Verify npm is working Set npm mirror npm config set registry https://registry.npmmirror.com/ Speed up downloads Check npm mirror npm config get registry Verify mirror is active Install Claude Code npm install -g @anthropic-ai/claude-code Global install Check Claude Code version claude --version Verify Claude Code is installed Launch Claude Code claude Start in current folder Check current model /model Type inside Claude Code Exit Claude Code /exit or press Ctrl + C twice Quit the program FAQ node -v says \u0026ldquo;\u0026rsquo;node\u0026rsquo; is not recognized as an internal or external command\u0026rdquo;? Node.js environment variables (PATH) aren\u0026rsquo;t configured correctly. Open File Explorer and go to D:\\nodejs\\ to see if node.exe is there:\nThe file exists: Node.js is installed but PATH isn\u0026rsquo;t set up — follow the steps in 1.4 How to Configure Environment Variables to add it manually The file doesn\u0026rsquo;t exist: Installation failed — re-download and reinstall claude says \u0026ldquo;\u0026lsquo;claude\u0026rsquo; is not recognized as an internal or external command\u0026rdquo;? Claude Code installation failed. First verify node -v and npm -v are working, then re-run npm install -g @anthropic-ai/claude-code.\nClaude Code asks me to log in to an Anthropic account after launching? The .claude.json file wasn\u0026rsquo;t edited correctly. Press Win + R, type %USERPROFILE% and press Enter, find .claude.json and open it with Notepad. Make sure it contains \u0026quot;hasCompletedOnboarding\u0026quot;: true, with an English comma at the end of the preceding line, true in lowercase, and English quotation marks.\nClaude Code shows errors or no response during conversation? Common causes: ① DeepSeek account balance is insufficient ② API Key is entered incorrectly ③ Model name isn\u0026rsquo;t deepseek-v4-pro[1m] ④ Network issues. Check each one.\nnpm install of Claude Code is very slow (over 5 minutes)? Check if the domestic mirror is configured: npm config get registry (should show registry.npmmirror.com). If not, run npm config set registry https://registry.npmmirror.com/ and retry.\nCC-Switch won\u0026rsquo;t open or crashes on launch? Download the latest version from GitHub Releases, or try right-clicking and running as administrator.\nGitHub page won\u0026rsquo;t load? Cause: GitHub may be unstable to access from within China. Solutions:\nRefresh the page several times Try a different browser If you still can\u0026rsquo;t access it, search for \u0026ldquo;CC-Switch download\u0026rdquo; online — some domestic mirror sites may also host the download Complete Process Review Step Content One-Line Summary Step 1 Install Node.js Set up the \u0026ldquo;runtime engine\u0026rdquo; so your computer can run JavaScript programs Step 2 Install Claude Code Install the \u0026ldquo;AI assistant\u0026rdquo; and skip login Step 3 Install CC-Switch Install the \u0026ldquo;brain-swapper\u0026rdquo; to change AI models Step 4 Get DeepSeek API Key Get the \u0026ldquo;key\u0026rdquo; to access DeepSeek\u0026rsquo;s AI services Step 5 Configure CC-Switch Use the \u0026ldquo;brain-swapper\u0026rdquo; + \u0026ldquo;key\u0026rdquo; to switch Claude Code\u0026rsquo;s brain to DeepSeek Step 6 Start Using Type claude in any folder to launch your AI assistant! After completing all steps, you can open any folder on your computer, type the claude command, and launch a DeepSeek-powered AI programming assistant!\n","date":"2026-04-26T02:00:15+08:00","image":"/p/%E5%AE%89%E8%A3%85claudecode%E5%B9%B6%E6%8E%A5%E5%85%A5deepseek%E9%9D%A2%E5%90%91%E5%B0%8F%E7%99%BD/cover.svg","permalink":"/en/p/install-claude-code-and-connect-deepseek-beginner-friendly-guide/","title":"Install Claude Code and Connect DeepSeek (Beginner-Friendly Guide)"},{"content":"Overview Claude Code is a command-line AI programming assistant launched by Anthropic, with a variety of built-in Skills plugins. Through different combinations, it can accomplish many things that AI alone cannot do. After connecting to the domestic large model DeepSeek V4, usage costs can be significantly reduced.\nCore uses:\nBuilding a personal knowledge base, automating the organization of study notes Collecting industry information on schedule and organizing it into manuscripts Automatically publishing to various social media platforms Step 1: Install the Runtime Environment 1.1 Install Node.js Go to the Node.js official website to download the Windows installer (.msi), double-click and follow the prompts.\nVerify installation:\n1 2 node -v npm -v 1.2 Configure npm Domestic Mirror 1 npm config set registry https://registry.npmmirror.com/ 💡 Why configure a mirror? The default npm source is overseas, and download speeds are very slow. After configuring a domestic mirror, installation speed can be improved by more than 10 times.\n1.3 Install Git Go to the Git official website to download the corresponding version installer and follow the prompts.\nVerify installation:\n1 git -v 1.4 Install CC-Switch CC-Switch is used to connect third-party models to Claude Code.\nGo to the GitHub Release page to download the corresponding version (e.g., Windows MSI), double-click to install, and follow the prompts.\nStep 2: Install Claude Code 1 npm install -g @anthropic-ai/claude-code Verify:\n1 claude --version Skip Login (Using Third-party API) Launch Claude Code once and then close it Find the .claude.json file in your user directory Add the following field (note that a comma must be added at the end of the previous field): 1 \u0026#34;hasCompletedOnboarding\u0026#34;: true Re-execute claude to start, and choose to trust the current folder ⚠️ Common Error If you forget to add a comma at the end of the previous field, it will cause a JSON parsing error and Claude Code will fail to start.\nStep 3: Connect DeepSeek 3.1 Get API Key Open DeepSeek Open Platform, register and log in Ensure your account has a balance Click API Keys on the right → Create API Key → Copy and save (cannot be viewed again after closing) 🚨 Key Security Do not share your key with others, as it will consume your balance.\n3.2 Configure CC-Switch Open CC-Switch, click the + button in the upper right corner Select DeepSeek as the model preset Enter the API Key Change the model name uniformly to: deepseek-v4-pro[1m] (context 1M, Claude Code uses 128K by default) Click Add 3.3 Verify the Model In the Claude Code dialog box, enter:\n1 /model You can view the currently available models, or directly ask \u0026ldquo;What model are you currently using\u0026rdquo; to confirm successful connection.\nStep 4: Hands-on Example Create a new folder on the desktop Enter CMD in the address bar and press Enter Execute claude to start, and choose to trust the current folder Enter your requirement: Use HTML + JS + CSS to create a Todo app During execution, it will request tool permissions — select Yes After completion, ask it to open the page for preview 💡 Tip You can describe your requirements directly in Chinese — Claude Code supports mixed Chinese and English input.\nCommand Quick Reference Operation Command Node version check node -v npm version check npm -v npm domestic mirror npm config set registry https://registry.npmmirror.com/ Git version check git -v Install Claude Code npm install -g @anthropic-ai/claude-code Claude Code version check claude --version Launch Claude Code claude Switch model /model FAQ Command not found after running claude? Check if Node.js is installed successfully (node -v) and whether the npm global path is in the system PATH.\nPrompts to log in to Anthropic account after starting? The hasCompletedOnboarding in .claude.json is not configured correctly. Please go back to Step 2 to check.\nModel call error / no response? Check if your DeepSeek account balance is sufficient, and whether the API Key in CC-Switch is entered correctly.\n","date":"2026-04-26T02:00:15+08:00","image":"/p/5%E5%88%86%E9%92%9F%E5%AE%89%E8%A3%85claudecode%E5%B9%B6%E6%8E%A5%E5%85%A5deepseek/cover.svg","permalink":"/en/p/install-claude-code-in-5-minutes-and-connect-deepseek/","title":"Install Claude Code in 5 Minutes and Connect DeepSeek"},{"content":"✈️ Learn to Create Beautiful Tech Architecture Diagrams with AI 👋 This guide is written for complete beginners who have never drawn an architecture diagram before. You don\u0026rsquo;t need design skills, you don\u0026rsquo;t need to write code — just know how to chat with AI.\nWhat is a Tech Architecture Diagram and Why Should I Draw One? Simply put, a tech architecture diagram helps you \u0026ldquo;draw out\u0026rdquo; the system in your head.\nFor example, if you\u0026rsquo;re building an app: what functional modules does it have? How do users interact with it? How does data flow? Drawing these relationships as a diagram is an architecture diagram.\nThe benefits are real:\n✅ Clarify your own thinking — the process of drawing helps you organize your system design ✅ Communicate with coworkers effortlessly — a picture is worth a thousand words ✅ Impress in presentations — bosses and clients instantly understand how great your solution is ✅ AI draws for you, saving time and effort — with AI, you can get a decent diagram in minutes 🤔 Which Method Should a Beginner Choose? (Read This First) Your Situation Recommended Method Difficulty Just want the fastest way to get a good-looking image, no changes later Method 1 (AI generates image directly) ⭐ Willing to take one more step for easier future edits Method 2 (Mermaid.js code generation) ⭐⭐ Creating formal docs that need repeated edits and consistent style Method 3 (Excalidraw local drawing) ⭐⭐⭐ 💡 Beginner tip: Try Method 1 first to get a feel, then try Method 2. Save Method 3 for when you need to create formal documents.\nMethod 1: Let AI Draw a Picture for You (Simplest, Fastest) ⏱ Time: 2-3 minutes 🛠 Tool: Gemini 3.1 Pro (by Google, free)\nHow It Works in One Sentence Ask your AI (like Gemini) to write a \u0026ldquo;visual description prompt\u0026rdquo; first, then feed that prompt to the AI\u0026rsquo;s image generation feature, and the AI draws the picture for you.\nStep-by-Step Guide Step 1: Ask AI to Write a \u0026ldquo;Visual Description Prompt\u0026rdquo; Open Gemini and enter the following (copy and replace with your content):\n1 2 3 4 5 Please write a prompt for generating a technical architecture diagram. I want to draw an architecture diagram for [your system name, e.g., e-commerce website], with the following modules: user interface, product management, order system, payment system, admin panel. The data flow is: user places an order → order system calls payment → payment completion notifies product management to update inventory. Please provide a detailed prompt in English suitable for text-to-image models. The style should be professional, clean, and visually appealing. The AI will return a detailed English description.\nStep 2: Feed the Prompt to AI for Image Generation In Gemini (or other AI with image generation), select the image generation feature (like Gemini\u0026rsquo;s built-in Banana 2.0 model), paste the prompt from the previous step, and click generate.\nStep 3: Done 🎉 The AI will output an image. If you\u0026rsquo;re not satisfied, regenerate until you\u0026rsquo;re happy.\nPros and Cons ✅ Pros ❌ Cons Fastest — done in minutes Hard to modify — system changes require full regeneration Great visual quality, rich colors Results can be inconsistent No extra tools needed Poor prompts lead to poor results 📌 Beginner Tips Be detailed in your prompt — the more specific you are, the better the output. Don\u0026rsquo;t just say \u0026ldquo;draw an architecture diagram\u0026rdquo; — specify the modules and how they connect Try multiple times — it\u0026rsquo;s normal to not get a perfect result on the first try English prompts work better — most image generation models understand English better Method 2: Let AI Generate Code, Then Render It into a Diagram (Recommended for Beginners) ⏱ Time: 3-5 minutes 🛠 Tool: Any AI (ChatGPT, Claude, Gemini) + Mermaid.js\nHow It Works in One Sentence A flowchart is essentially code (Mermaid.js syntax). You ask AI to write this code, then use a free online tool to render it as an image. Want to change the diagram? Ask AI to modify the code and re-render.\nStep-by-Step Guide Step 1: Ask AI to Generate Mermaid Code Open your preferred AI (ChatGPT, Claude, Gemini) and enter (copy and replace with your content):\n1 2 3 4 Please use Mermaid syntax to draw an architecture diagram for an e-commerce system. The system includes: user interface, product management, order system, payment system, admin panel. Data flow: user places order → order system calls payment → payment completion notifies product management to update inventory. Output pure Mermaid code using graph TD format. The AI will return something like:\ngraph TD A[User Interface] --\u003e B[Order System] B --\u003e C[Payment System] B --\u003e D[Product Management] C --\u003e E[Payment Complete] E --\u003e DStep 2: Render the Code as an Image Open this free website: mermaid.live\nPaste the AI-generated code into the left editor panel The right panel will instantly display the flowchart Click the \u0026ldquo;Export\u0026rdquo; button in the top-right corner and choose PNG or SVG format (SVG is a vector format — it stays sharp at any size, great for formal documents) Step 3: Want to Modify It? Ask AI to Change the Code Paste the old code back to the AI and tell it what you want to change:\n1 Modify the code above to add a \u0026#34;Login Verification\u0026#34; module between \u0026#34;User Interface\u0026#34; and \u0026#34;Order System\u0026#34;. After modification, go back to mermaid.live to paste and export.\nPros and Cons ✅ Pros ❌ Cons Good image quality, professional look Complex diagrams are still hard to modify later Easier to modify than Method 1 — change code, re-render Major architecture changes essentially require regeneration No software installation needed — works in a browser 📌 Beginner Tips Mermaid has fixed syntax — when asking AI, clearly say \u0026ldquo;use Mermaid syntax\u0026rdquo; mermaid.live is a gem — paste and preview instantly, completely free, no account needed Export as SVG for best results — vector format stays sharp at any size Save your code — for future modifications, just send the old code to AI Method 3: Let AI Generate Editable Architecture Diagrams (For Formal Documents) ⏱ Time: 10-15 minutes (first setup takes a bit longer) 🛠 Tools: An AI coding tool + Obsidian + a \u0026ldquo;Drawing Instruction Pack\u0026rdquo;\nHow It Works in One Sentence This is the most professional method, but requires some initial setup. Once configured, you tell AI what to draw, and AI generates a draggable, editable architecture diagram file that you open in Obsidian — adjust anything you don\u0026rsquo;t like manually. Methods 1 and 2 produce \u0026ldquo;static\u0026rdquo; images; this method produces \u0026ldquo;living\u0026rdquo; ones.\n🤔 First, Understand: What is a \u0026ldquo;Drawing Instruction Pack\u0026rdquo; (Skills)? Skills are a set of \u0026ldquo;instruction manuals\u0026rdquo; that tell AI how to draw diagrams for you.\nWithout it: You say \u0026ldquo;draw an architecture diagram\u0026rdquo; — AI can only give you a text description With it: AI knows how to generate an editable architecture diagram file Think of it as installing a \u0026ldquo;diagram plugin\u0026rdquo; for your AI.\nThis instruction pack is called axton-obsidian-visual-skills — a free open-source project by Axton. It includes 3 drawing abilities:\nDrawing Method Generated File Best For Visual Style Excalidraw .excalidraw file Flowcharts, mind maps, architecture diagrams ✏️ Hand-drawn style (like a whiteboard) Mermaid Text rules Flowcharts, sequence diagrams, comparison charts 🎯 Professional business style Canvas .canvas file Mind maps, knowledge organization 🎨 Colorful cards 💡 You can also use Draw.io — Draw.io is another free drawing tool with its own instruction pack. This guide uses Excalidraw as an example.\n🔧 Prerequisite Installation (One-Time) 💡 Where Should This Instruction Pack Go? AI tools look for these instruction files in a fixed location on your computer. Recommended location:\nC:\\Users\\yourusername\\.claude\\skills\\\n🤔 What\u0026rsquo;s this path?\nC:\\Users\\yourusername\\ ← Your \u0026ldquo;user folder\u0026rdquo; — where software stores config files by default \\.claude\\ ← Configuration folder created by Claude Code skills\\ ← Where drawing instructions are stored Don\u0026rsquo;t know your username? Open File Explorer, type %USERPROFILE% in the address bar and press Enter — that\u0026rsquo;s the folder.\n🤔 Why on C drive? Because your user folder is on C by default. This makes the instruction pack available to all projects on this machine.\nThis location works for both OpenCode and Claude Code — install once, use with both tools.\nOther tools may use different locations, but beginners can just use the path above.\nInstallation Method 1: Let AI Install It for You (Recommended, Easiest) Whether you use OpenCode, Claude Code, or Cursor, just say:\n1 2 3 Help me download axtonliu/axton-obsidian-visual-skills from GitHub, unzip it, and put the excalidraw-diagram, mermaid-visualizer, and obsidian-canvas-creator folders into C:\\Users\\yourusername\\.claude\\skills\\ directory. AI will handle downloading, unzipping, and copying. Restart your tool when done.\n💡 Replace \u0026ldquo;yourusername\u0026rdquo; with your actual username.\nInstallation Method 2: Manual Download If your AI doesn\u0026rsquo;t support file operations:\nOpen the axton-obsidian-visual-skills download page\nClick the green Code button → Download ZIP\nUnzip the file — you\u0026rsquo;ll see 3 folders\nOpen your C:\\Users\\yourusername\\.claude\\ folder (create a skills folder if it doesn\u0026rsquo;t exist)\nDrag all 3 folders in\nFinal structure:\n1 2 3 4 5 6 7 C:\\Users\\yourusername\\.claude\\skills\\ ├── excalidraw-diagram\\ │ └── SKILL.md ├── mermaid-visualizer\\ │ └── SKILL.md └── obsidian-canvas-creator\\ └── SKILL.md Installation Method 3: Claude Code Quick Install If you use Claude Code (only works with it), type in the chat:\n1 2 /plugin marketplace add axtonliu/axton-obsidian-visual-skills /plugin install obsidian-visual-skills Restart Claude Code after installation. Not supported by OpenCode or Cursor.\nYou\u0026rsquo;ll Also Need: Software Purpose Cost OpenCode / Claude Code / Cursor Runs AI to generate diagram files Free tiers available Obsidian View and manually adjust diagrams Free Obsidian Excalidraw Plugin Edit Excalidraw files in Obsidian Free (search \u0026ldquo;Excalidraw\u0026rdquo; in the plugin marketplace) 🖐️ Step-by-Step Guide Step 1: Install Skills, Tell AI What to Draw After installing Skills, type directly in OpenCode, Claude Code, or Cursor:\nFor Excalidraw hand-drawn style architecture diagram:\n1 2 3 4 Use Excalidraw to draw an e-commerce system architecture diagram, including: user interface, product management, order system, payment system, admin panel. User places order → order system calls payment → payment completion updates inventory. Use Chinese labels. AI will automatically generate a .excalidraw file in the current directory.\n🔍 Can\u0026rsquo;t find the file? Check the AI\u0026rsquo;s output — it usually tells you the save path.\nFor Mermaid business-style flowchart:\n1 2 Convert this flow into a Mermaid diagram: User visits homepage → browses products → adds to cart → submits order → pays online → completes transaction AI will generate Mermaid code — copy it to mermaid.live to render.\nFor Canvas mind map:\n1 2 Organize this article into an Obsidian Canvas mind map: [paste your content] AI will generate a .canvas file — open with Obsidian to see a colorful card layout.\nStep 2: Manual Adjustments in Obsidian Open Obsidian and drag the generated file in For Excalidraw files (.excalidraw or .md), double-click to enter edit mode Freely drag boxes, adjust arrows, modify text, change colors Drag a new box to add a module, select and press Delete to remove 💡 This is the key advantage — you have a \u0026ldquo;living\u0026rdquo; architecture diagram.\nStep 3 (Optional): Change Style with AI After adjusting content and layout, screenshot it and send to Gemini (or other AI) with a reference image:\n1 Help me convert Image 1 to a hand-drawn style similar to Image 2, adding appropriate illustrations to help users understand (Prompt 1: Major changes — content layout may also be adjusted)\n1 Convert to a hand-drawn style similar to Image 2 (Prompt 2: Minor changes — only colors and style, content layout stays the same)\n🔍 What Diagrams Can Excalidraw Skills Draw? Diagram Type Best For Flowchart Business processes, operation steps, task sequences Mind Map Concept expansion, topic classification, brainstorming Hierarchy Diagram Organization structure, system layers, directory structure Relationship Diagram Dependencies, influence relationships, element interactions Comparison Chart Solution comparison, option analysis, before/after Timeline Event evolution, project milestones, version iterations Matrix 2D classification, priority matrix, capability positioning Free Canvas Scattered ideas, initial drafts, free-form notes ⚠️ Common Issues \u0026amp; Solutions Q: Chinese text doesn\u0026rsquo;t have a hand-drawn look? A: Excalidraw\u0026rsquo;s hand-drawn font (Excalifont) supports English by default; Chinese fonts need online loading. If Chinese shows as regular font:\nEnsure access to Excalidraw.com (needs internet) Or download Chinese font files from the Excalidraw official font library Place them in your Obsidian vault under Excalidraw/CJK Fonts Enable \u0026ldquo;Load Chinese fonts at startup\u0026rdquo; in Excalidraw plugin settings and restart Obsidian Q: The generated diagram looks messy? A: That\u0026rsquo;s normal — AI-generated layouts aren\u0026rsquo;t always perfect. Just drag and adjust in Obsidian — that\u0026rsquo;s the biggest advantage of Method 3.\nQ: Do I have to use Claude Code? A: No. These Skills work on OpenCode, Claude Code, and Cursor. OpenCode is compatible with Claude Code\u0026rsquo;s Skills format.\nPros and Cons ✅ Pros ❌ Cons Edit anything — drag to adjust First-time environment setup takes time Not dependent on prompt quality — content can be manually refined Longer workflow, more steps Create a set of consistently styled document diagrams Occasional text encoding or alignment issues Works well with Obsidian for knowledge management One Skills install gives three drawing methods 📌 Beginner Tips Try Methods 1 and 2 first, then move to Method 3 when you\u0026rsquo;re comfortable Skills installation is the key step — once installed, AI knows how to generate editable files Excalidraw defaults to hand-drawn style, giving a亲切, approachable look Obsidian\u0026rsquo;s Excalidraw plugin offers the best viewing and editing experience Method 3\u0026rsquo;s greatest value is editability — once set up, future changes are just drag-and-drop Check out the demo video on GitHub before deciding 🔧 Tools Summary Tool Purpose Cost Difficulty Gemini Chat + text-to-image generation Free Low ChatGPT Chat + text-to-image generation Paid/Free Low OpenCode AI coding tool, auto-loads ~/.claude/skills/, supports parallel execution Free Medium Claude Code AI coding tool, supports Skills API usage pricing Medium Cursor AI coding tool Free tier sufficient Medium mermaid.live Convert Mermaid code to images Free Low Excalidraw Editable diagram tool Free \u0026amp; open source Low Obsidian Note-taking + Excalidraw plugin for editable diagrams Free Medium axton-obsidian-visual-skills AI drawing instruction pack (Excalidraw / Mermaid / Canvas) Free \u0026amp; open source Medium 🎯 Beginner Quick Start Roadmap 1 2 3 4 5 6 7 8 9 Day 1 → Try Method 1: Generate images with Gemini (just try it) ↓ Day 2 → Try Method 2: Generate flowcharts with Mermaid.js (Learn the \u0026#34;change code = change diagram\u0026#34; approach) ↓ Day 3 → Use Method 2 diagrams in your documents ↓ When needed → Explore Method 3: Install Skills + Obsidian + Excalidraw plugin (No rush — Methods 1 and 2 are already sufficient) 💬 FAQ Q: Are all these tools free? A: Gemini and mermaid.live are completely free. ChatGPT and Claude have free tiers — you only pay after using them up.\nQ: Can I use generated images commercially? A: Yes, the architecture diagram is your own design — AI is just a tool to draw it.\nQ: I\u0026rsquo;m a product manager/operations person, not a developer — can I still draw? A: Absolutely. Method 1 only requires typing, Method 2 only requires copy-pasting — no coding needed.\nQ: Are there copyright issues with generated images? A: The copyright of tool-generated images belongs to you.\nQ: Do Mac and Windows both work? A: All tools mentioned have web versions, so the OS doesn\u0026rsquo;t matter.\nQ: What exactly is \u0026ldquo;axton-obsidian-visual-skills\u0026rdquo; in Method 3, do I have to install it? A: It\u0026rsquo;s an open-source AI drawing \u0026ldquo;instruction pack.\u0026rdquo; You can draw without it, but with it installed, AI can directly generate editable architecture diagram files instead of static images. If you only need occasional diagrams, Methods 1 and 2 are sufficient. If you need frequent edits and formal documents, highly recommended.\nQ: What\u0026rsquo;s the difference between the 3 drawing methods (Excalidraw / Mermaid / Canvas) in Method 3? A: Simply put — Excalidraw is like a hand-drawn whiteboard, best for architecture diagrams; Mermaid has a professional business style, great for formal docs; Canvas is a colorful mind map tool for organizing ideas. Choose based on what you need.\nQ: Does Method 3 require Claude Code? Can I use ChatGPT? A: These Skills are designed for AI coding tools that can manipulate local files — OpenCode, Claude Code, Cursor all work. ChatGPT\u0026rsquo;s web version can\u0026rsquo;t handle local files, so it won\u0026rsquo;t work.\nQ: Where should the installed Skills be? How do I check? A: They go in ~/.claude/skills/. Check that directory — it should have excalidraw-diagram, mermaid-visualizer, and obsidian-canvas-creator folders. Restart your AI tool and it should recognize them.\n📝 Final words: The most important thing about drawing architecture diagrams is clarifying what you want to express. AI is just a tool to turn your ideas into images. Start with the simplest Method 1 — the first step is the most important!\n","date":"2026-03-31T19:51:00+08:00","image":"/p/%E5%B0%8F%E7%99%BD%E4%B9%9F%E8%83%BD%E5%AD%A6%E4%BC%9A%E7%94%A8-ai-%E5%BF%AB%E9%80%9F%E7%94%BB%E5%87%BA%E6%BC%82%E4%BA%AE%E7%9A%84%E6%8A%80%E6%9C%AF%E6%9E%B6%E6%9E%84%E5%9B%BE/cover.svg","permalink":"/en/p/learn-to-create-beautiful-tech-architecture-diagrams-with-ai/","title":"Learn to Create Beautiful Tech Architecture Diagrams with AI"},{"content":"🤖 The Evolution of AI Programming: From Prompts and Context Engineering to Harness As models with comparable capabilities become increasingly common, the gap in user experience between different products is actually widening. Some products write code that can be deployed directly, while others produce code that is hard to maintain—why? Because the models are the same; the difference lies in how they are used, and how to use them stably. In the AI industry, this is known as Harness Engineering.\n🧠 Harness Engineering: Deconstructing the Agent into Three Layers We divide programming Agents into three levels:\nScaffolding Responsible for all preparatory work before the AI executes a task, including the tools provisioned by the system. Harness (Runtime Orchestration, The Core) The central dispatching hub of the entire agent. Responsible for managing the AI\u0026rsquo;s core reasoning loop, coordinating tool calls, context management, runtime security control, and persistent storage of session data. Context Engineering Responsible for managing the resource allocation of tokens—the smallest unit of computation for large language models processing text. Determines which information should be retained and which should be discarded during the AI\u0026rsquo;s operation. A stable and capable AI coding agent = One or more LLMs called + A robust Harness system.\n⏳ Harness is Crucial, Why is it Only Getting Popular Now? ① Phase 1: Prompt Engineering Core Focus: How to write a good instruction.\nRole Setting: Defining clear identities and responsibility boundaries for the AI. Providing Examples: Using Few-shot prompting to make the AI generate content according to a specific format and style. Chain-of-Thought: Asking the AI in the instruction to break down the problem step-by-step and deduce logically, reducing logical leaps and errors. ② Phase 2: Context Engineering A single prompt is no longer enough—we need to dynamically construct the entire context environment for the model. Ensuring that every time the model makes a decision, it can accurately see all the information it needs: task files, conversation history, tool rules, knowledge base entries\u0026hellip;\nCore Concept: Show the model what it needs to see, and block what it shouldn\u0026rsquo;t.\n③ Phase 3: Harness Engineering Whenever you find the Agent making a mistake, you spend time engineering a solution so it won\u0026rsquo;t make the same mistake again.\nThe model\u0026rsquo;s capabilities are sufficient, but it just won\u0026rsquo;t listen. What do we do? The answer is—Harness Engineering.\nReal-world Cases:\nExperiment Condition Result LangChain Same model, optimized Harness only Terminal Bench 2.0: 52.8 → 66.5 Nate B Jones Same model, same prompt, changed runtime environment only Coding benchmark win rate: 42% → 78% OpenAI Started from an empty git repo, 5 months, entirely AI Agent driven Produced ~1 million lines of code, 1500 PRs, zero human intervention The Agent isn\u0026rsquo;t hard; the Harness is.\n💥 Why Do AI Tasks Fail So Frequently? 1. Trying to do it all at once Trying to finish all features in a single window results in the context window rapidly depleting, causing a steep drop in quality towards the latter half.\n2. Declaring victory too early In the later stages of complex project development, once the AI agent completes the core functions and has visible output, it directly determines the task is complete and actively terminates—even if a large number of features are unimplemented and core requirements are unmet, it will still stop.\n3. Marking features as complete too early As soon as the AI agent finishes writing a feature, it marks it as complete. It will not actively perform end-to-end full functional tests, nor will it verify whether this feature is actually usable in a real environment. It looks like it runs, but in reality, it\u0026rsquo;s full of hidden bugs.\n4. Mechanically copying code patterns AI will mechanically follow existing code patterns (architectural style, coding conventions), even if the pattern is wrong, and continuously amplify it throughout the project. An unconstrained AI agent will accumulate a massive amount of technical debt in a project at extreme speeds.\n🛡️ The Four Guardrails of Harness 🔹 1. Context Engineering The longer and more redundant the AGENTS.MD file is, the lower the Agent\u0026rsquo;s task success rate, while the inference cost becomes higher. The AGENTS.MD file should be strictly kept under 60 lines.\nContext is a scarce resource; too much guidance will crowd out the truly important task code.\n🔹 2. Architectural Constraints (The Core) Implement a strict layered architecture—not by telling the agent \u0026ldquo;please follow the architecture\u0026rdquo; via a prompt, but by mechanically enforcing it using deterministic Linters and structured tests.\nEmbed repair guidelines directly into the Linter error messages, telling the agent how it should be fixed. Constraints are more effective than instructions.\n🔹 3. Feedback Loop In Harness, code review becomes an Agent-to-Agent process. Forming a standardized closed loop: Plan \u0026amp; Discover → Build → Verify → Fix, cycling continuously to consistently purify code quality.\n🔹 4. Entropy Management Over time, AI-generated code accumulates numerous issues: outdated documentation, architectural drift, styling deviations, accumulation of dead code\u0026hellip; Letting an Agent maintain documentation for the Agent continuously fights against entropy increase and prevents project rot.\n🧭 Conclusion The evolution of AI programming is essentially a paradigm shift from \u0026ldquo;writing good prompts\u0026rdquo; to \u0026ldquo;building good systems\u0026rdquo;.\nPrompt Engineering solves \u0026ldquo;how to say it\u0026rdquo;. Context Engineering solves \u0026ldquo;what information to give\u0026rdquo;. Harness Engineering solves \u0026ldquo;how to manage/control it\u0026rdquo;. These three paths are not mutually exclusive but rather additive and progressive—each layer builds on the foundation of the previous one. A truly capable AI programming product that stably outputs high-quality code must have invested serious effort across all three of these levels.\n","date":"2026-03-20T02:00:15+08:00","image":"/p/ai%E7%BC%96%E7%A8%8B%E8%BF%9B%E5%8C%96%E5%8F%B2/cover.svg","permalink":"/en/p/the-evolution-of-ai-programming/","title":"The Evolution of AI Programming"},{"content":"1. What is LoRA? LoRA (Low-Rank Adaptation) is a large model fine-tuning technique.\nThe Problem Large models (like Qwen, Llama) have 7B, 70B parameters or more. Retraining all parameters every time you want to teach them something new requires dozens of A100 GPUs running for days — far beyond what most people can afford.\nThe LoRA Approach Don\u0026rsquo;t touch the original model — just attach a \u0026ldquo;small plugin\u0026rdquo; next to it.\nThink of it this way:\nApproach Analogy Full fine-tuning Rewriting the entire textbook into your desired version LoRA Sticking a few Post-it notes in the margins with your additions The original model weights are completely unchanged. LoRA inserts a tiny matrix (low-rank matrix) next to certain key layers, and only updates this matrix during training.\nWhy \u0026ldquo;Low-Rank Adaptation\u0026rdquo;? Mathematically, a large matrix can be approximated by the product of two smaller matrices. LoRA leverages this: the original weight matrix $W$ stays frozen, while two small matrices $A$ and $B$ are trained. The final output becomes $W + A \\cdot B$. Together, $A$ and $B$ may be only one-thousandth the size of the original weights.\n2. What is LoRA Used For? Its core ability is simple: change a large model\u0026rsquo;s \u0026ldquo;behavior\u0026rdquo; at very low cost.\n📌 LoRA changes style/format/behavior, not knowledge Want the model to learn new knowledge → Use RAG (Retrieval-Augmented Generation) Want the model to speak or act differently → Use LoRA Typical Use Cases Scenario Example Style Transfer Make a general model write in Lu Xun\u0026rsquo;s literary style Format Constraint Force the model to output strict JSON, nothing more Role-playing Turn Qwen into Zhongli from Genshin Impact Domain Tone Medical consultation tone, legal document precision Instruction Following Make the model better follow system prompts without wandering LoRA Advantages Extremely low VRAM: A 7B model can be trained on a single RTX 3090 (24G), or even barely on 8G cards Tiny file size: Training output is just a few MB. One model can host dozens of different LoRAs, plug-and-play Fast training: A few hundred samples, results in 30 minutes No base damage: Unload the LoRA and the model reverts to original, zero risk 3. How to Use LoRA? Four main steps:\nStep 1: Prepare Data Write example dialogues of the \u0026ldquo;behavior\u0026rdquo; you want the model to learn.\nSuppose you want the model to become a sarcastic customer service agent. Write 50-200 dialogues like this:\n1 2 3 4 5 User: Where\u0026#39;s my package? Agent: Well, unless there\u0026#39;s a surprise, it\u0026#39;s probably sunbathing in the delivery truck. I suggest you sunbathe too while you wait. User: Can I get a refund? Agent: Sure, the process is about as long as a pilgrimage. Get your order number ready and I\u0026#39;ll guide you on this journey westward. You don\u0026rsquo;t need much data — 50-200 high-quality examples will show noticeable results. Quality matters far more than quantity.\nStep 2: Choose a Tool There are many tools out there, but they all do essentially the same thing. Two recommendations:\nTool Features Best For LLaMA-Factory Web UI, click-based operation Complete beginners who don\u0026rsquo;t want to code Unsloth 2-5x faster, half the VRAM Those who know some Python and want efficiency Unsloth\u0026rsquo;s core code is under 30 lines. The essence: load model → attach LoRA → feed data → train → save.\nStep 3: Train Set a few key parameters, then wait:\nParameter Purpose Typical Value LoRA rank Determines the \u0026ldquo;plugin\u0026rdquo; capacity. Higher = more refined but more VRAM 8 or 16 is enough Learning rate How much to learn each step 5e-5, don\u0026rsquo;t overthink it Epochs How many times to go through the data 3-5 Step 4: Use After training, you get a LoRA file of a few MB. To use it, load both the original model and this LoRA file — the model now behaves as you trained it.\nWant to switch back? Just unload the LoRA, one second to restore.\nOne model can host multiple LoRAs simultaneously — for example, attach a \u0026ldquo;sarcastic style\u0026rdquo; LoRA and a \u0026ldquo;JSON output\u0026rdquo; LoRA, and the model becomes a sarcastic assistant that outputs JSON.\n4. Relationship with Related Concepts Concept What It Does Relationship with LoRA Full Fine-tuning Modifies all parameters Alternative to LoRA, better results but hundreds of times more expensive RAG External knowledge retrieval Complementary: RAG handles knowledge, LoRA handles style Prompt Engineering Writing prompts Lightest approach, but limited. Use LoRA when prompts aren\u0026rsquo;t enough QLoRA LoRA + 4-bit quantization VRAM-saving version of LoRA, can run 7B on 8G cards PEFT Parameter-Efficient Fine-tuning category LoRA is the most popular member of the PEFT family 5. One-Sentence Summary LoRA = a small plugin for large models that changes behavior without changing knowledge, with extremely low training cost and plug-and-play MB-sized files.\n","date":"2025-12-11T00:00:00+08:00","image":"/p/lora%E5%A4%A7%E6%A8%A1%E5%9E%8B%E5%BE%AE%E8%B0%83/cover.svg","permalink":"/en/p/lora-large-model-fine-tuning/","title":"LoRA Large Model Fine-Tuning"},{"content":"Hugo + Stack + GitHub Pages Blog Setup Guide A complete guide to building a personal blog with Hugo + Stack theme and deploying it to GitHub Pages.\nThis guide covers both new Stack (v4.x, split .toml config format) and legacy (v3.x, single hugo.yaml) configuration differences, with annotations where key differences exist.\nEnvironment Setup Install Git Go to the Git website to download and install: https://git-scm.com/downloads Use all default options during installation Install Hugo (Extended Version) Go to Hugo GitHub Releases: https://github.com/gohugoio/hugo/releases Choose the extended version (marked with extended) — the Stack theme requires extended SCSS compilation support Windows users: download hugo_extended_xxx_windows-amd64.zip and extract hugo.exe This guide was written using Hugo v0.161.1 and Stack theme v4.0.2.\nGitHub Account Register a GitHub account: https://github.com It\u0026rsquo;s recommended to enable two-factor authentication (2FA) — you can install the Authenticator 2FA Client plugin in Edge Create a Hugo Site Initialize the Project Open a terminal in the directory where hugo.exe is located (type cmd or powershell in the address bar) and run:\n1 2 3 4 5 # Create a new site hugo new site myblog # Enter the site directory cd myblog Generated file structure:\n1 2 3 4 5 6 7 8 9 10 11 myblog/ ├── archetypes/ # Article templates ├── assets/ # Static assets (images, CSS, JS) ├── content/ # Blog content (articles) ├── data/ # Data files ├── i18n/ # Multilingual support ├── layouts/ # Layout templates ├── public/ # Build output (generated by hugo command) ├── static/ # Static files (copied directly to public) ├── themes/ # Themes └── hugo.toml # Site configuration Test the Default Site 1 hugo server -D Visit http://localhost:1313/ in your browser. The page will be basic (no theme). Press Ctrl + C to stop the server.\nConfigure the Stack Theme Download the Theme Go to the Stack theme GitHub: https://github.com/CaiJimmy/hugo-theme-stack Download the latest Release archive (or click \u0026ldquo;Download ZIP\u0026rdquo;) Extract to the site\u0026rsquo;s themes/ directory 1 2 myblog/themes/ └── hugo-theme-stack-4.0.2/ # Folder with version number Configure Theme Files — Critical Step This is the step where errors are most likely to occur. The new Stack (v4.x) and legacy (v3.x) have completely different file structures:\nComparison Legacy Stack (v3.x) New Stack (v4.x) Example site folder name exampleSite/ demo/ Config files Single hugo.yaml Multiple .toml files in config/_default/ Theme reference theme: hugo-theme-stack [[module.imports]] (Hugo Modules) New Version (v4.x) Steps: Step 1: Copy Configuration Files\n1 2 3 4 5 # Create config/_default directory mkdir -p config/_default # Copy all config files from demo cp themes/hugo-theme-stack-4.0.2/demo/config/_default/*.toml config/_default/ After copying, config/_default/ contains 6 config files:\nFile Purpose hugo.toml Base config (baseURL, title, pagination, permalinks, etc.) languages.toml Multilingual configuration markup.toml Markdown rendering config (code highlighting, TOC, etc.) menu.toml Menu config (navigation bar, social links) params.toml Theme parameters (sidebar, comments, widgets, etc.) related.toml Related content recommendation config Step 2: Change Theme Reference Method\nOpen config/_default/hugo.toml, find:\n1 2 [[module.imports]] path = \u0026#34;github.com/CaiJimmy/hugo-theme-stack/v3\u0026#34; Replace with:\n1 theme = \u0026#34;hugo-theme-stack-4.0.2\u0026#34; This traditional method doesn\u0026rsquo;t require Go environment or Hugo Modules, making it simpler and consistent with this guide.\nStep 3: Handle Root hugo.toml Conflict\nThe root hugo.toml and config/_default/hugo.toml will conflict. Back up or delete the root file:\n1 mv hugo.toml hugo.toml.bak Step 4: Copy Example Content\n1 2 3 4 5 # Back up existing content (if any) mv content content_backup # Copy demo content cp -r themes/hugo-theme-stack-4.0.2/demo/content . Step 5: Copy Avatar and Static Assets\n1 2 mkdir -p assets/img cp themes/hugo-theme-stack-4.0.2/demo/assets/img/avatar.png assets/img/ Legacy Version (v3.x) Steps: Enter the theme\u0026rsquo;s exampleSite/ folder Copy the content folder and hugo.yaml to the site root Delete the root hugo.toml (since you now have hugo.yaml) Confirm that the theme field in hugo.yaml matches the theme folder name (version number removal recommended) Verify by Starting 1 hugo server -D Visit http://localhost:1313/ in your browser. You should now see the complete Stack theme (with sidebar, search, example articles, etc.).\nIf the page is incomplete, check the terminal for WARN messages (e.g., \u0026ldquo;Search page not found\u0026rdquo;, \u0026ldquo;Archives page not found\u0026rdquo;). This is usually because example content wasn\u0026rsquo;t copied.\nCustom Configuration Basic Information Edit config/_default/hugo.toml (new version) or hugo.yaml (legacy):\n1 2 baseURL = \u0026#34;https://your-username.github.io/\u0026#34; title = \u0026#34;My Blog\u0026#34; If your primary language is Chinese, it\u0026rsquo;s recommended to set:\n1 2 defaultContentLanguage = \u0026#34;zh-cn\u0026#34; hasCJKLanguage = true # Set to true for Chinese/Japanese/Korean Sidebar Edit config/_default/params.toml (new version) or the params.sidebar section in hugo.yaml:\n1 2 3 4 [sidebar] emoji = \u0026#34;✏️\u0026#34; subtitle = \u0026#34;Your personal tagline\u0026#34; avatar = \u0026#34;img/avatar.png\u0026#34; Place the avatar image at assets/img/avatar.png Choose emojis from emojiall.com Social Links Edit config/_default/menu.toml (new version) or the menu.social section in hugo.yaml:\n1 2 3 4 5 [[social]] identifier = \u0026#34;github\u0026#34; name = \u0026#34;GitHub\u0026#34; url = \u0026#34;https://github.com/your-username\u0026#34; params.icon = \u0026#34;brand-github\u0026#34; Icon names reference: Tabler Icons (use brand-xxx format).\nComment System Stack supports multiple comment systems. Here\u0026rsquo;s an example using utterances (based on GitHub Issues, no extra registration needed):\n1 2 3 4 5 6 7 8 [comments] enabled = true provider = \u0026#34;utterances\u0026#34; [comments.utterances] repo = \u0026#34;your-username/your-username.github.io\u0026#34; issueTerm = \u0026#34;pathname\u0026#34; label = \u0026#34;\u0026#34; For more comment system configurations, see the theme documentation: https://stack.jimmycai.com/config/comments\nFooter 1 2 [footer] since = 2026 Creating Articles Article Structure The Stack theme recommends each article in its own folder with index.md and image assets:\n1 hugo new content post/my-first-article/index.md Generated directory structure:\n1 2 3 content/post/my-first-article/ ├── index.md # Article content └── image.jpg # Article image (optional) Article Front Matter Example 1 2 3 4 5 6 7 8 9 10 11 --- title: My First Article date: 2026-05-12 description: Article summary description tags: - Hugo - Blog categories: - Tutorial image: image.jpg # Article cover image (optional) --- Deploy to GitHub Pages Create a GitHub Repository Log in to GitHub, click New repository Repository name: your-username.github.io (must match exactly) Select Public (GitHub Pages free tier requires public) Do not check \u0026ldquo;Add a README file\u0026rdquo; Manual Deployment 1 2 3 4 5 6 7 8 9 10 11 12 13 # 1. Build the static website (output to public/) hugo -D # 2. Enter the public directory cd public # 3. Initialize Git and push git init git add . git commit -m \u0026#34;first commit\u0026#34; git branch -M main git remote add origin https://github.com/your-username/your-username.github.io.git git push -u origin main After pushing successfully, visit https://your-username.github.io/ to see your blog (the first time may take 1-2 minutes).\nAutomatic Deployment (GitHub Actions) Manually building and pushing every time is tedious. Use GitHub Actions to automatically build and deploy when you push code.\nStep 1: Create a Source Repository\nIn addition to the username.github.io deployment repository, create a source repository (e.g., myblog) and push the entire Hugo project to it:\n1 2 3 4 5 6 7 # In the site root directory (not inside public/) git init git add . git commit -m \u0026#34;init hugo site\u0026#34; git branch -M main git remote add origin https://github.com/your-username/myblog.git git push -u origin main Step 2: Create GitHub Actions Workflow\nCreate .github/workflows/deploy.yml in the site root:\n1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 name: Deploy Hugo site to GitHub Pages on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: submodules: true fetch-depth: 0 - name: Setup Hugo uses: peaceiris/actions-hugo@v3 with: hugo-version: \u0026#39;latest\u0026#39; extended: true - name: Build run: hugo --minify - name: Deploy uses: peaceiris/actions-gh-pages@v4 with: personal_token: ${{ secrets.PERSONAL_TOKEN }} external_repository: your-username/your-username.github.io publish_branch: main publish_dir: ./public Step 3: Configure GitHub Token\nGo to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) Generate a new Token with repo and workflow permissions Copy the generated Token Go to your source repository → Settings → Secrets and variables → Actions → New repository secret Name: PERSONAL_TOKEN, Value: paste the Token From now on, every git push to the source repository\u0026rsquo;s main branch will trigger GitHub Actions to automatically build and deploy to username.github.io.\nTip: Enable Automatic lastmod Add the following to config/_default/hugo.toml (new version) or hugo.yaml (legacy):\n1 2 3 enableGitInfo = true [frontmatter] lastmod = [\u0026#34;:git\u0026#34;, \u0026#34;:fileModTime\u0026#34;] This will automatically display the Git commit time as the last modified time for articles. This requires fetch-depth: 0 in the GitHub Actions checkout step (already included in the configuration above).\nFAQ Q1: Page is blank/incomplete after starting? Check whether you copied the demo\u0026rsquo;s content folder. Missing example pages (search, archives, etc.) will cause the theme to display incompletely.\nQ2: hugo server throws \u0026ldquo;Theme not found\u0026rdquo; error? New version: Check that theme = \u0026quot;xxx\u0026quot; in config/_default/hugo.toml matches the folder name under themes/ Legacy: Check the theme field in hugo.yaml Q3: Root hugo.toml conflicts with config/_default/hugo.toml? Delete or back up the root hugo.toml. Hugo will prioritize config files under config/_default/.\nQ4: Push to GitHub fails? This may be a network issue. Try removing the proxy:\n1 2 git config --global --unset http.proxy git config --global --unset https.proxy Q5: What is the new [[module.imports]]? The new Stack uses Hugo Modules (Go modules) to import the theme by default, which requires a Go environment. If you don\u0026rsquo;t want to deal with Go, simply switch to the traditional theme = \u0026quot;theme-folder-name\u0026quot; method.\nQ6: Blog styles are broken after deployment? Check that baseURL is correctly set to https://your-username.github.io/ (note the trailing /). An incorrect baseURL will cause CSS/JS resources to fail to load.\nReferences Hugo Official Documentation Stack Theme Documentation Stack Theme GitHub Tabler Icons Reference Tutorial - letere-gzj ","date":"2025-12-08T00:00:00Z","image":"/p/hugo--stack--github-pages-%E5%8D%9A%E5%AE%A2%E6%90%AD%E5%BB%BA%E6%8C%87%E5%8D%97/cover.svg","permalink":"/en/p/hugo--stack--github-pages-blog-setup-guide/","title":"Hugo + Stack + GitHub Pages Blog Setup Guide"},{"content":"Overview Have you ever thought: ChatGPT, Claude and other AIs are smart, but they can only chat in a dialog box — they can\u0026rsquo;t help you check your calendar, manage files, or operate databases because they\u0026rsquo;re \u0026ldquo;locked in a cage\u0026rdquo; with no access to the outside world.\nMCP (Model Context Protocol) is here to break down that wall.\nSimply put, MCP is an open standard protocol that enables AI applications to connect to external systems — files, databases, APIs, various tools — just like giving AI a universal plug (USB-C port). Plug in anything and it works.\nOne sentence to understand MCP: It\u0026rsquo;s the \u0026ldquo;USB-C port\u0026rdquo; for the AI world — a unified standard, plug and play.\nWhy Use MCP? Before MCP Before MCP existed, if you wanted to connect AI to external tools (like checking the weather, reading calendars, operating databases), each AI application and each tool required custom integration development.\nThis was like the early days of phone charging ports — one for Android, one for Apple, one for Type-C. Every time you switched devices, you needed a new cable.\nThe problems were obvious:\nHigh development costs: Every integration started from scratch Not universal: Tools written for Claude couldn\u0026rsquo;t be used by ChatGPT Difficult to maintain: When a tool was upgraded, all integrations had to be changed After MCP MCP defines a unified standard:\nTool providers develop an MCP Server following the MCP standard AI applications act as MCP Clients to connect to it As long as both sides follow the MCP protocol, plug and play, no redundant development This is like how USB-C unified charging ports — one cable to rule them all.\nWhat Can MCP Do? Use Cases at a Glance 1. Personal AI Assistant Let AI help you manage your daily life:\nConnect Google Calendar to check schedules and create meeting reminders Connect Notion to organize notes and manage to-do lists Connect Gmail to read and reply to emails Connect Slack to summarize chat history Example: You tell the AI \u0026ldquo;check what meetings I have tomorrow and summarize last week\u0026rsquo;s project progress notes\u0026rdquo; — the AI can automatically check your calendar, go through Notion, and give you a summary.\n2. Programming \u0026amp; Development Let AI coding assistants actually \u0026ldquo;get their hands dirty\u0026rdquo;:\nConnect to the local file system via MCP to read and write project files Connect to databases to directly query and modify data Connect to GitHub to automatically create Issues and submit PRs Connect to Figma to generate code directly from design mockups Example: Claude Code connects to Figma via MCP, obtains the design mockup, and generates a complete web application.\n3. Enterprise Applications Make a big impact in the corporate world:\nConnect to multiple databases so employees can query business data in natural language Connect to internal systems (CRM, ERP) for AI to automatically compile reports Connect to knowledge bases so AI can answer questions based on company documentation 4. Creative \u0026amp; Design Connect to Blender to let AI generate 3D models Connect to 3D printers to print designs directly Connect to video editing tools to automate the editing workflow MCP Core Architecture MCP\u0026rsquo;s architecture is very simple, with only three roles:\n1 2 3 4 5 ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ AI App │ ◄─────► │ MCP Protocol │ ◄─────► │ MCP Server │ │ (MCP Client) │ │ (Transport) │ │ (External │ └──────────────┘ └──────────────┘ │ Tool) │ └──────────────┘ Role Description Analogy MCP Client AI applications (Claude, ChatGPT, Cursor) Phone MCP Server Services providing specific capabilities (weather, file management) Charger MCP Protocol The \u0026ldquo;language\u0026rdquo; both sides communicate in USB-C Standard What Can an MCP Server Provide? An MCP Server can expose three types of capabilities to AI:\nType Description Examples Tools Functions/operations AI can call Search the web, send emails, query databases Resources Data AI can read File contents, database records, API responses Prompts Preset prompt templates Code review templates, translation templates How to Use MCP? Method 1: Use Existing MCP Servers (Recommended for Beginners) This is the simplest approach — others have already written the MCP Server, you just need to \u0026ldquo;install and connect\u0026rdquo;.\nStep 1: Find the MCP Server You Need The MCP ecosystem already has a large number of Servers available. Common sources:\nOfficial repository: github.com/modelcontextprotocol/servers MCP marketplaces: mcp.so, smithery.ai GitHub search: Search for mcp-server Popular MCP Servers:\nMCP Server Function filesystem Read and write local files github Operate GitHub (Issues, PRs) fetch Fetch web page content sqlite Operate SQLite databases notion Operate Notion notes memory Persistent memory storage Step 2: Configure MCP Server in Your AI Application Using Claude Desktop as an example, find the configuration file:\nWindows: %APPDATA%\\Claude\\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Add MCP Server configuration (using filesystem as an example):\n1 2 3 4 5 6 7 8 9 10 11 12 { \u0026#34;mcpServers\u0026#34;: { \u0026#34;filesystem\u0026#34;: { \u0026#34;command\u0026#34;: \u0026#34;npx\u0026#34;, \u0026#34;args\u0026#34;: [ \u0026#34;-y\u0026#34;, \u0026#34;@modelcontextprotocol/server-filesystem\u0026#34;, \u0026#34;/your/work/directory/path\u0026#34; ] } } } After saving, restart Claude Desktop, and the AI will have file management capabilities.\nStep 3: Start Using After restarting, simply ask the AI to use these tools in conversation:\n\u0026ldquo;Create a notes folder in my work directory\u0026rdquo; \u0026ldquo;Read the README.md content and give me a summary\u0026rdquo; \u0026ldquo;Search for recent project Issues\u0026rdquo; The AI will automatically call the corresponding MCP Server to complete the task.\nMethod 2: Use MCP in Cursor / VS Code If you use Cursor or VS Code for programming development, the configuration is similar.\nCreate .cursor/mcp.json (Cursor) or .vscode/mcp.json (VS Code) in your project root:\n1 2 3 4 5 6 7 8 9 10 11 12 { \u0026#34;mcpServers\u0026#34;: { \u0026#34;fetch\u0026#34;: { \u0026#34;command\u0026#34;: \u0026#34;npx\u0026#34;, \u0026#34;args\u0026#34;: [\u0026#34;-y\u0026#34;, \u0026#34;@modelcontextprotocol/server-fetch\u0026#34;] }, \u0026#34;sqlite\u0026#34;: { \u0026#34;command\u0026#34;: \u0026#34;npx\u0026#34;, \u0026#34;args\u0026#34;: [\u0026#34;-y\u0026#34;, \u0026#34;@modelcontextprotocol/server-sqlite\u0026#34;, \u0026#34;./data.db\u0026#34;] } } } After configuration, you can use these tools in AI conversations.\nMethod 3: Develop Your Own MCP Server (Advanced) If you want to connect AI to your own systems (like a company\u0026rsquo;s internal API), you can write your own MCP Server.\nMCP supports multiple programming languages with official SDKs:\nLanguage SDK TypeScript @modelcontextprotocol/sdk Python mcp (PyPI) Java / Kotlin io.modelcontextprotocol Minimal example (TypeScript):\n1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 import { McpServer } from \u0026#34;@modelcontextprotocol/sdk/server/mcp.js\u0026#34;; import { StdioServerTransport } from \u0026#34;@modelcontextprotocol/sdk/server/stdio.js\u0026#34;; import { z } from \u0026#34;zod\u0026#34;; const server = new McpServer({ name: \u0026#34;my-server\u0026#34;, version: \u0026#34;1.0.0\u0026#34; }); // Define a \u0026#34;check weather\u0026#34; tool server.tool( \u0026#34;get_weather\u0026#34;, { city: z.string().describe(\u0026#34;City name\u0026#34;) }, async ({ city }) =\u0026gt; { // Your business logic here const weather = `${city} is sunny today, 25°C`; return { content: [{ type: \u0026#34;text\u0026#34;, text: weather }] }; } ); // Start the service const transport = new StdioServerTransport(); await server.connect(transport); Once written, configure it in your AI application and start using it.\nWhich AI Applications Support MCP? MCP has become an industry standard, with mainstream AI applications offering support:\nAI Application Support Status Claude Desktop / Claude Code Native support ChatGPT Supported Cursor Supported VS Code (Copilot) Supported Windsurf Supported OpenCode Supported Configure once, use everywhere — an MCP Server configured in Claude will work in other applications too.\nFAQ Q: What\u0026rsquo;s the difference between MCP and APIs? An API is a \u0026ldquo;private protocol\u0026rdquo; between two parties, with each API having different calling methods. MCP is a unified standard — all tools that follow MCP can be called by AI in the same way. Think of MCP as \u0026ldquo;a standard API layer specifically for AI.\u0026rdquo;\nQ: Do I need programming skills to use MCP? No! If you\u0026rsquo;re just using existing MCP Servers, you only need to know how to copy and paste configuration files. Programming is only needed when developing your own MCP Server.\nQ: Is MCP secure? MCP Servers run locally by default, and data is not uploaded to the cloud. However, when using third-party MCP Servers, it\u0026rsquo;s recommended to check their source code and permissions to ensure security.\nQ: What environment does an MCP Server need to run? Most MCP Servers run on Node.js, so you need to install Node.js first. Python-based Servers require a Python environment.\nSummary Question Answer What is MCP? A unified standard protocol for AI to connect to external tools Why use it? To let AI actually \u0026ldquo;do work\u0026rdquo; instead of just chatting Who can use it? Everyone — beginners use existing Servers, developers can write their own How to use it? Find an MCP Server → Configure it in your AI app → Restart and use The essence of MCP is: creating a unified \u0026ldquo;plug standard\u0026rdquo; for the AI world, allowing tools and AI to connect freely.\nFurther reading:\nMCP Official Documentation MCP Server Repository MCP Marketplace ","date":"2025-12-01T01:46:03+08:00","image":"/p/mcp%E5%85%A5%E9%97%A8%E6%8C%87%E5%8D%97%E5%B0%8F%E7%99%BD%E4%B9%9F%E8%83%BD%E7%9C%8B%E6%87%82%E7%9A%84ai%E4%B8%87%E8%83%BD%E6%8F%92%E5%A4%B4/cover.svg","permalink":"/en/p/mcp-beginners-guide-the-universal-ai-plug-anyone-can-understand/","title":"MCP Beginner's Guide: The Universal AI Plug Anyone Can Understand"}]