Guoxin Wiki

Windows 11 上封锁 Claude Code 出网：防火墙 + DNS + hosts 三层实战

Wed, 21 Oct 2026 00:00:00 GMT

适用机器：Windows 11（build 26200，x64）+ WSL2 Ubuntu-24.04 + Docker Desktop + Clash Verge
适用场景：本机跑 Claude Code / CPA / 浏览器，只有走代理才能连 Anthropic，直连必须死
对应服务器版：同目录 CLAUDE-EGRESS-BLOCK-TUTORIAL.md
最后更新：2026-10-22

0. 目标与效果#

目标是让本机上的任何进程：

无法直接连接 Anthropic / Claude 官方域名和 IP（主机 / WSL2 / Docker Desktop 容器全覆盖）；
只能通过本机 Clash 代理访问；
代理崩溃或配置出错时请求直接失败，绝不回落到直连；
重启后规则、DNS 仍然生效。

最终效果（2026-10-22 实测）：

1
主机 IPv4 直连 Anthropic 网段            -> 防火墙内核层丢弃
2
主机 IPv6 直连 Anthropic 网段            -> 防火墙内核层丢弃
3
WSL2 (Ubuntu-24.04) 直连                 -> nftables 丢弃（双保险）
4
Docker Desktop 容器直连                  -> Windows 防火墙出站规则同样生效（替身实测覆盖）
5
通过 Clash 代理                          -> 不受影响（代理节点 IP 不在封锁集合内）
6
Clash 停止时直连                         -> 仍然必死
7
重启后                                   -> 防火墙规则持久 + WSL systemd 自启

验证分两阶段：阶段一全程零 Anthropic 流量（替身 IP 223.5.5.5 + 中性域名 baidu.com）；阶段二端到端不连通实测已于 2026-10-22 执行通过，结果见第 7 节。

1. 原理：三层防线与 Windows 特有的坑#

服务器版三层（DNS 纠正 + Clash 显式规则 + nftables）在 Windows 上的对应：

服务器层	Windows 对应	说明
nftables `output` 链	Windows Defender Firewall 出站规则（WFP 层）	`New-NetFirewallRule`，按目的 IP 封，写入策略库、重启持久
nftables `forward` 链	同上（实测覆盖 Docker Desktop NAT 流量）	WSL 内再部署一套 nftables 双保险
netplan 公网 DNS	`Set-DnsClientServerAddress`	大陆家宽用 223.5.5.5 / 119.29.29.29，不要照抄服务器版的 1.1.1.1 / 8.8.8.8（大陆不可靠）
Clash 显式规则	Clash Verge 中 anthropic/claude 域名 → 代理组	保证”走代理可用”
systemd 开机顺序	防火墙规则本身持久；WSL 用 systemd 单元	无需额外开机脚本

Windows 特有的坑（本次实测/踩坑记录）：

PowerShell 5.1 把无 BOM 的 UTF-8 脚本按 GBK 解析。.ps1 里出现中文（例如 '以太网'）会直接 ParserError，症状：UAC 点了”是”、日志没生成、提权窗口一闪而过。所有提权脚本必须纯 ASCII；网卡用 InterfaceDescription 过滤，不要写本地化网卡名。
DoH 绕过 DNS/hosts：Chrome/Edge Secure DNS 不走系统 DNS。DNS/hosts 只是辅助层，最终保证是 IP 层封锁。
IPv6 必须一起封（2607:6bc0::/32）：Windows 优先走 v6。
WSL2 / Docker Desktop 走 NAT 转发路径，理论上 Windows 防火墙出站规则（ALE 层）只管本机进程；但本次替身实测证明 Docker Desktop 容器流量实际被覆盖（见 6.2）。WSL 内仍按服务器方案部署 nftables 做双保险。
hosts 是”失败安全”方向：将来若开 Clash TUN 模式，hosts 会让这些域名连代理路径一起报错（表现为连接失败，而非直连）。届时删掉 hosts 段即可，IP 层封锁仍在。

2. 前置检查#

在本机执行（全部只查本地状态，不连 Anthropic）：

Terminal window展开收起

1
# 提权状态与管理员组成员
2
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
3
Get-LocalGroupMember -Group Administrators
4

5
# 现有防火墙规则（应为空）
6
Get-NetFirewallRule -DisplayName "claude-guard*"
7

8
# 网卡清单（决定 DNS 要设在哪些网卡上）
9
Get-NetAdapter | Select-Object Name, InterfaceDescription
10

11
# 代理形态（有无 TUN 网卡，决定 hosts 层取舍）
12
Get-Process | Where-Object Name -match "clash|mihomo|verge"
13

14
# WSL 与 Docker
15
wsl -l -v
16
docker ps

展开收起

Anthropic 网段沿用服务器版 2026-10-21 值：

1
IPv4: 160.79.104.0/21
2
IPv6: 2607:6bc0::/32

3. 第一步：Windows 防火墙出站阻断（A）#

3.1 提权脚本 `setup.ps1`（必须纯 ASCII）#

创建 C:\Users\<你>\AppData\Local\Temp\claude-guard\setup.ps1：

Terminal window展开收起

1
# claude-guard setup for Windows 11 (run elevated) - ASCII only
2
$ErrorActionPreference = 'Continue'
3
$dir = 'C:\Users\<你>\AppData\Local\Temp\claude-guard'
4
$log = Join-Path $dir 'setup.log'
5
function Log([string]$m) {
6
    Add-Content -Path $log -Value ('[{0}] {1}' -f (Get-Date -Format s), $m) -Encoding utf8
7
}
8
Log '=== setup start ==='
9
$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
10
Log ("IsAdmin=$isAdmin")
11
if (-not $isAdmin) { Log 'ABORT: not elevated'; exit 1 }
12

13
# --- A: firewall block rules (kernel-level, persistent) ---
14
foreach ($n in @('claude-guard-v4','claude-guard-v6','claude-guard-selftest-v4')) {
15
    Get-NetFirewallRule -DisplayName $n -ErrorAction SilentlyContinue | Remove-NetFirewallRule
16
}
17
New-NetFirewallRule -DisplayName 'claude-guard-v4' -Direction Outbound -Action Block -RemoteAddress '160.79.104.0/21' -Profile Any -Enabled True | Out-Null
18
New-NetFirewallRule -DisplayName 'claude-guard-v6' -Direction Outbound -Action Block -RemoteAddress '2607:6bc0::/32' -Profile Any -Enabled True | Out-Null
19
New-NetFirewallRule -DisplayName 'claude-guard-selftest-v4' -Direction Outbound -Action Block -RemoteAddress '223.5.5.5/32' -Profile Any -Enabled True | Out-Null
20
Log 'firewall: claude-guard-v4 / claude-guard-v6 / claude-guard-selftest-v4 created'
21

22
# --- E1: DNS on non-virtual adapters (anti-hijack) ---
23
$adapters = Get-NetAdapter | Where-Object { $_.InterfaceDescription -notmatch 'Hyper-V|Virtual|TAP-Windows|OpenVPN|WSL' }
24
foreach ($a in $adapters) {
25
    Set-DnsClientServerAddress -InterfaceAlias $a.Name -ServerAddresses @('223.5.5.5','119.29.29.29')
26
    $now = (Get-DnsClientServerAddress -InterfaceAlias $a.Name -AddressFamily 2).ServerAddresses -join ','
27
    Log ('DNS set on [' + $a.Name + '] desc=[' + $a.InterfaceDescription + '] now=' + $now)
28
}
29
ipconfig /flushdns | Out-Null
30
Log 'dns cache flushed'
31

32
# --- E2: hosts (aux name-layer, fail-closed) ---
33
$hostsPath = Join-Path $env:SystemRoot 'System32\drivers\etc\hosts'
34
Copy-Item $hostsPath ($hostsPath + '.bak-claude-guard') -Force
35
$domains = @('anthropic.com','www.anthropic.com','api.anthropic.com','console.anthropic.com','docs.anthropic.com','code.anthropic.com','statsig.anthropic.com','claude.ai','www.claude.ai','claude.com','www.claude.com','claudeusercontent.com')
36
$text = [System.IO.File]::ReadAllText($hostsPath)
37
$add = @()
38
foreach ($d in $domains) {
39
    if ($text -notmatch ('(?m)^\s*0\.0\.0\.0\s+' + [regex]::Escape($d) + '\s*$')) { $add += ('0.0.0.0 ' + $d) }
40
}
41
if ($add.Count -gt 0) {
42
    $block = "`r`n# claude-guard: aux name-layer block (fail-closed)`r`n" + ($add -join "`r`n") + "`r`n"
43
    [System.IO.File]::AppendAllText($hostsPath, $block, [System.Text.Encoding]::ASCII)
44
    Log ('hosts: ' + $add.Count + ' lines added')
45
} else {
46
    Log 'hosts: already up to date'
47
}
48

49
# --- summary ---
50
Get-NetFirewallRule -DisplayName 'claude-guard*' | ForEach-Object {
51
    Log ('rule: ' + $_.DisplayName + ' enabled=' + $_.Enabled + ' action=' + $_.Action + ' dir=' + $_.Direction)
52
}
53
Log '=== setup done ==='

展开收起

注意：$dir 换成你自己的实际路径；脚本幂等，重复执行会先删旧规则再重建。

脚本一次做三件事：A 防火墙规则、E1 DNS、E2 hosts。其中 claude-guard-selftest-v4（封 223.5.5.5）是替身规则，专门给第 6 节验证用，验证完必须删。

3.2 提权入口 `run-elevated.ps1`（必须纯 ASCII）#

Terminal window

1
# claude-guard elevated launcher (ASCII only)
2
$ErrorActionPreference = 'Continue'
3
$base = 'C:\Users\<你>\AppData\Local\Temp\claude-guard'
4
Start-Transcript -Path (Join-Path $base 'elev.transcript.log') -Force | Out-Null
5
try {
6
    & (Join-Path $base 'setup.ps1')
7
    Add-Content -Path (Join-Path $base 'elev.status.log') -Value 'WRAPPER_OK'
8
} catch {
9
    Add-Content -Path (Join-Path $base 'elev.status.log') -Value ('WRAPPER_ERR: ' + ($_ | Out-String))
10
}
11
Stop-Transcript | Out-Null

普通终端执行（会弹 UAC，点”是”）：

Terminal window

1
powershell -NoProfile -Command 'try { Start-Process powershell -Verb RunAs -Wait -ArgumentList "-NoProfile","-ExecutionPolicy","Bypass","-File","C:\Users\<你>\AppData\Local\Temp\claude-guard\run-elevated.ps1" -ErrorAction Stop; Write-Output UAC_OK } catch { Write-Output ("UAC_FAIL: " + $_.Exception.Message) }'

成功标志：UAC_OK + setup.log 里出现 === setup done ===。

3.3 提权失败排查（本次踩过的坑）#

症状：UAC_OK 打印了，但 setup.log 不存在、规则没生效、命令 1.5 秒就返回。

排查顺序：

Terminal window

1
# 1. 非提权直接跑，把 ParserError 打到控制台（会因 IsAdmin=False 中止，无副作用）
2
powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\<你>\AppData\Local\Temp\claude-guard\setup.ps1
3

4
# 2. 看包装器日志
5
type C:\Users\<你>\AppData\Local\Temp\claude-guard\elev.status.log
6
type C:\Users\<你>\AppData\Local\Temp\claude-guard\elev.transcript.log

本次根因即第 1 节坑 1：UTF-8 无 BOM + 中文 → GBK 解析 → ParserError。改成纯 ASCII 后一次通过。

4. 第二步：WSL2 内 nftables 移植（B）#

与服务器版同款，去掉服务商中转 set（那是服务器服务商特有的）。WSL 内是 systemd 环境（Ubuntu-24.04 默认 systemd=true），直接复用 claude-guard.service。

4.1 `/etc/nftables.d/claude-guard.nft`#

1
table inet claude_guard {
2
    set anthropic_v4 {
3
        type ipv4_addr
4
        flags interval
5
        elements = { 160.79.104.0/21 }
6
    }
7
    set anthropic_v6 {
8
        type ipv6_addr
9
        flags interval
10
        elements = { 2607:6bc0::/32 }
11
    }
12

13
    chain output {
14
        type filter hook output priority -200; policy accept;
15
        ip daddr @anthropic_v4 counter limit rate 10/minute log prefix "claude-guard-out " level warn
16
        ip daddr @anthropic_v4 counter drop
17
        ip6 daddr @anthropic_v6 counter limit rate 10/minute log prefix "claude-guard-out6 " level warn
18
        ip6 daddr @anthropic_v6 counter drop
19
    }
20

21
    chain forward {
22
        type filter hook forward priority -200; policy accept;
23
        ip daddr @anthropic_v4 counter limit rate 10/minute log prefix "claude-guard-fwd " level warn
24
        ip daddr @anthropic_v4 counter drop
25
        ip6 daddr @anthropic_v6 counter limit rate 10/minute log prefix "claude-guard-fwd6 " level warn
26
        ip6 daddr @anthropic_v6 counter drop
27
    }
28
}

展开收起

4.2 `/usr/local/sbin/claude-guard.sh`#

1
#!/bin/sh
2
set -eu
3
nft delete table inet claude_guard 2>/dev/null || true
4
nft -f /etc/nftables.d/claude-guard.nft

4.3 `/etc/systemd/system/claude-guard.service`#

1
[Unit]
2
Description=Block direct egress to Anthropic/Claude IP ranges
3
After=network.target
4
Wants=network.target
5

6
[Service]
7
Type=oneshot
8
RemainAfterExit=yes
9
ExecStart=/usr/local/sbin/claude-guard.sh
10
ExecStop=/usr/sbin/nft delete table inet claude_guard
11

12
[Install]
13
WantedBy=multi-user.target

4.4 部署（在 Windows 侧执行）#

Terminal window

1
# 装 nftables（WSL 默认没有 nft 二进制）
2
wsl -d Ubuntu-24.04 -u root -- bash -c "apt-get update -qq && apt-get install -y -qq nftables"
3

4
# 三个文件按上面内容写入后：
5
wsl -d Ubuntu-24.04 -u root -- bash -c "chmod 0755 /usr/local/sbin/claude-guard.sh; nft -c -f /etc/nftables.d/claude-guard.nft && systemctl daemon-reload && systemctl enable --now claude-guard.service"
6

7
# 验证
8
wsl -d Ubuntu-24.04 -u root -- bash -c "systemctl is-enabled claude-guard; systemctl is-active claude-guard; nft list table inet claude_guard"

期望：enabled / active，规则集列出两个 set 和两条链。WSL 每次启动由 systemd 自动拉起，等效开机持久。

5. 第三步：DNS 纠正 + hosts（E）#

这两步已包含在 setup.ps1（3.1 的 E1/E2 段），要点：

DNS 选 223.5.5.5 / 119.29.29.29（阿里 DNSPod）：大陆家宽可达且不劫持 Anthropic 域名；服务器版的 1.1.1.1/8.8.8.8 在大陆不可靠，不要照抄。排除虚拟网卡（Hyper-V/WSL/OpenVPN/TAP），只设物理网卡。
hosts 指向 0.0.0.0：辅助名称层，共 12 条（anthropic.com / claude.ai / claude.com / claudeusercontent.com 及主要子域）。走 HTTP 代理时域名由代理端解析，hosts 不影响代理路径。
两层都是辅助：DoH 应用会绕过它们，所以IP 层封锁（A/B）才是最终保证。

6. 验证：替身法（全程零 Anthropic 流量）#

原理：setup.ps1 额外创建了替身规则 claude-guard-selftest-v4（封 223.5.5.5/32）。它与正式规则构造完全一致，对它做行为测试即可证明正式规则的机制。

6.1 主机差异测试#

Terminal window

1
# 被替身规则封住的解析器：必须超时
2
nslookup -timeout=2 -retry=1 baidu.com 223.5.5.5
3

4
# 对照组（未封的解析器）：必须正常
5
nslookup -timeout=2 -retry=1 baidu.com 119.29.29.29

期望：前者 DNS request timed out，后者返回 A 记录。

6.2 Docker Desktop 覆盖判定#

Terminal window

1
docker run --rm node:22-alpine sh -c "nslookup -timeout=2 baidu.com 223.5.5.5"
2
docker run --rm node:22-alpine sh -c "nslookup -timeout=2 baidu.com 119.29.29.29"

期望：前者 connection timed out; no servers could be reached，后者正常。若前者正常，说明你的 Docker 网络路径没被 A 覆盖，需要把工作负载挪进 WSL（B 覆盖）再验。

6.3 本次实测记录（2026-10-22）#

测试	结果
主机 `nslookup baidu.com 223.5.5.5`	超时（被拦）✓
主机 `nslookup baidu.com 119.29.29.29`	正常返回 ✓
容器 `nslookup baidu.com 223.5.5.5`	无服务器可达（被拦）✓ → Docker Desktop 被 A 覆盖
容器 `nslookup baidu.com 119.29.29.29`	正常返回 ✓
主机冒烟 `curl https://www.baidu.com`	200，无误伤 ✓
WSL `getent hosts baidu.com`	正常 ✓

6.4 清理替身规则（必须做）#

替身规则封的 223.5.5.5 现在是主 DNS，验证完立即删（会再弹一次 UAC）：

teardown-selftest.ps1：

Terminal window

1
$log = 'C:\Users\<你>\AppData\Local\Temp\claude-guard\setup.log'
2
function Log([string]$m) {
3
    Add-Content -Path $log -Value ('[{0}] {1}' -f (Get-Date -Format s), $m) -Encoding utf8
4
}
5
Get-NetFirewallRule -DisplayName 'claude-guard-selftest-v4' -ErrorAction SilentlyContinue | Remove-NetFirewallRule
6
Log 'selftest rule removed'
7
Get-NetFirewallRule -DisplayName 'claude-guard*' | ForEach-Object {
8
    Log ('remaining: ' + $_.DisplayName + ' enabled=' + $_.Enabled)
9
}
10
Log '=== teardown done ==='

Terminal window

1
powershell -NoProfile -Command 'try { Start-Process powershell -Verb RunAs -Wait -ArgumentList "-NoProfile","-ExecutionPolicy","Bypass","-File","C:\Users\<你>\AppData\Local\Temp\claude-guard\teardown-selftest.ps1" -ErrorAction Stop; Write-Output UAC_OK } catch { Write-Output ("UAC_FAIL: " + $_.Exception.Message) }'

最终盘点（期望只剩两条正式规则）：

Terminal window

1
Get-NetFirewallRule -DisplayName "claude-guard*" | Format-Table DisplayName,Enabled,Action,Direction,Profile
2
Get-DnsClientServerAddress -AddressFamily 2 | Format-Table InterfaceAlias,ServerAddresses
3
type C:\Windows\System32\drivers\etc\hosts

7. 端到端不连通实测（2026-10-22 已执行通过）#

上面的验证证明了”机制有效 + 无误伤”，但没有产生任何 Anthropic 流量。端到端确认方法如下（本次已执行，实测记录见 7.1）：

Terminal window

1
# 1. 先验证代理路径（期望 401：网络可达，只是缺凭证）
2
curl.exe -x http://127.0.0.1:7890 -m 15 -o NUL -w "proxy_http=%{http_code}\n" https://api.anthropic.com/v1/models
3

4
# 2. 再验证直连路径（期望超时 / http=000）
5
curl.exe --noproxy "*" -m 6 -o NUL -w "direct_http=%{http_code}\n" https://api.anthropic.com/v1/models

务必先 1 后 2。若第 2 步返回任何非 000 状态，立即停止使用并回报，说明封锁有洞。

7.1 本次实测记录（2026-10-22）#

实际执行的是”不连通”电池：对照组 + 三层直击，用 --resolve 强制打真实 Anthropic IP（绕过 DNS/hosts，直击内核封锁层）：

测试	命令要点	结果	证据含义
对照组	`curl https://www.baidu.com`	`200`	工具链正常，后续失败不是假象
hosts 层	`curl --noproxy "*" https://api.anthropic.com/v1/models`	`(6) Could not resolve host`，`000`	名称层拒绝解析，零流量
内核层 IPv4	`--resolve api.anthropic.com:443:160.79.104.10`	`(7) Failed after 0 ms`，`000`	0 ms 瞬时失败 = WFP 在 ALE connect 层本机拒绝，SYN 未出网卡
内核层 IPv6	`--resolve api.anthropic.com:443:[2607:6bc0::10]`	`(7) Failed after 0 ms`，`000`	v6 同样内核层拒绝
WSL 内核层	WSL 内同款 `--resolve` + `nft list` 计数器	`(28) 超时`，`000`；计数器 `packets 6 bytes 360`	nftables 静默丢弃，计数器实锤

判定：“直连必死”端到端成立。主机签名 = 瞬时拒绝（无包发出）；WSL 签名 = 丢弃 + 计数器递增。代理路径未在本次测试（不发凭证请求）；“走代理可用”由机制保证——封锁只按目的 IP 生效，代理节点 IP 不在封锁集合内，HTTP 代理下域名由代理端解析、hosts 不参与。

8. 维护#

8.1 Anthropic IP 段变化#

当前（2026-10-21）：

1
160.79.104.0/21
2
2607:6bc0::/32

变更时改两处并重载：

setup.ps1 里两条 New-NetFirewallRule 的 RemoteAddress → 重跑 run-elevated.ps1（幂等，会重建规则）；
WSL /etc/nftables.d/claude-guard.nft 的 elements → wsl -d Ubuntu-24.04 -u root -- /usr/local/sbin/claude-guard.sh。

8.2 换机器 / 重装#

复制 claude-guard\ 目录（含本教程的脚本）→ 改 $dir 路径 → 跑 run-elevated.ps1 → 第 4 节部署 WSL → 第 6 节替身验证。

8.3 已知观察#

nslookup 显示实际应答服务器可能是 fe80::1（路由器 RA 下发的 IPv6 DNS），IPv4 DNS 已固定 223.5.5.5/119.29.29.29。Anthropic 域名链路被 hosts + IP 层闭合，不受影响；仅影响其他域名的 DNS 洁净度。
本机存在 OpenVPN 虚拟网卡，未动其 DNS（由 VPN 配置自理）。
Clash Verge（verge-mihomo）为显式代理模式；若将来开 TUN 模式见第 1 节坑 5。

9. 回滚#

Terminal window

1
# 1. 删防火墙规则（管理员）
2
Remove-NetFirewallRule -DisplayName "claude-guard*"
3

4
# 2. 还原 DNS（管理员）
5
Set-DnsClientServerAddress -InterfaceAlias WLAN -ResetServerAddresses
6
Set-DnsClientServerAddress -InterfaceAlias "以太网" -ResetServerAddresses
7

8
# 3. 还原 hosts（管理员）
9
copy C:\Windows\System32\drivers\etc\hosts.bak-claude-guard C:\Windows\System32\drivers\etc\hosts

Terminal window

1
# 4. WSL 内
2
wsl -d Ubuntu-24.04 -u root -- bash -c "systemctl disable --now claude-guard; nft delete table inet claude_guard 2>/dev/null; true"

回滚后直连恢复，这是预期行为。

10. 文件清单#

路径	作用
`C:\Users\<你>\AppData\Local\Temp\claude-guard\setup.ps1`	主脚本：防火墙 + DNS + hosts（纯 ASCII，幂等）
同目录 `run-elevated.ps1`	提权入口（UAC + transcript）
同目录 `teardown-selftest.ps1`	删除替身规则
同目录 `setup.log`	全部操作审计日志
同目录 `elev.status.log` / `elev.transcript.log`	提权执行诊断
`C:\Windows\System32\drivers\etc\hosts.bak-claude-guard`	hosts 备份
WSL `/etc/nftables.d/claude-guard.nft`	WSL 内核级封锁规则
WSL `/usr/local/sbin/claude-guard.sh`	重载脚本
WSL `/etc/systemd/system/claude-guard.service`	WSL 开机自启

Temp 目录会被系统清理，长期留底请复制到 <笔记目录>。

11. 一句话总结#

Windows 防火墙封 IP 段（主机+Docker 实测全覆盖）+ WSL 内 nftables 双保险 + 公网 DNS/hosts 辅助层，并且用”替身 IP 差异测试”在零 Anthropic 流量的前提下证明机制有效——代理可用、直连必死、代理崩溃不回落。

React 学习 Day1：基础语法与整体框架（含 JS 关键基础）

Thu, 08 Oct 2026 00:00:00 GMT

这一天的核心目标：建立对 React 的整体认识，并补齐编写 React 所必需的 JavaScript 语法基础。下面按知识模块做系统化回顾，并在原笔记基础上补充更多细节、例子与易错点。

1. React 是什么（宏观理解）#

React 是一个用于构建用户界面（UI）的 JavaScript 库，重点负责视图层（View Layer）。
React 的编程范式是声明式（Declarative）：你只描述“界面应该长什么样”，React 负责“怎么更新到页面上”。
React 生态下通常构建单页应用（SPA）：页面不整页刷新，通过路由切换视图。

对 Python 思维的类比：

React 组件 ≈ Python 的函数/类，用来封装一段可复用的 UI 与逻辑。
Props ≈ 函数参数（外部输入）。
State ≈ 函数内部的可变局部状态/类的实例属性（内部数据）。

2. React 核心思想：组件化（Component-Based）#

2.1 什么是组件#

React 应用由组件树组成：小组件组合成大组件，最终拼成页面。
组件负责一小块 UI + 相关逻辑，具有高复用性与可维护性。

函数组件（现代主流）：

1
function Hello({ name }) {
2
  return <h1>Hello {name}</h1>;
3
}

组件组合（Composition）：

1
function App() {
2
  return (
3
    <div>
4
      <Hello name="Tom" />
5
      <Hello name="Jerry" />
6
    </div>
7
  );
8
}

2.2 函数组件 vs 类组件（只要知道差异）#

函数组件：更简洁，配合 Hooks 写法统一，是现在 React 的标准。
类组件：历史遗留写法，需要 this，生命周期冗长，新项目基本不再推荐。

你现在只需要专注函数组件 + Hooks。

3. React 的三大核心机制#

3.1 虚拟 DOM（Virtual DOM）与 Diff#

为什么需要 Virtual DOM：

真实 DOM 操作成本高。
React 先在内存里构建虚拟 DOM（JS 对象树），再与旧树比较（diff），只把最小改动同步到真实 DOM。

更新流程：

State/Props 变化
组件重新执行 → 生成新的 Virtual DOM
React diff 旧树和新树
只更新需要变化的真实 DOM

与列表渲染强相关的点：

map 渲染列表时要加 key，否则 diff 难以稳定复用节点。

1
items.map(item => <li key={item.id}>{item.title}</li>)

key 要稳定且唯一，尽量不用 index 作为 key（数据会增删/重排时会出 bug）。

3.2 Props 与 State#

Props（外部传入）

父组件 → 子组件的只读数据。
子组件不能直接修改 props，只能通过回调通知父组件。

State（组件内部）

组件自己维护的可变数据，变化会触发重渲染。
使用 useState 等 Hook 管理。

单向数据流（React 的基本原则）：

数据自顶向下传递（parent → child）。
子组件想影响父组件：通过 props 传函数（回调），由父组件更新自己的 state。

状态提升（Lifting State Up）：

当多个组件需要共享同一份数据，把 state 放到它们最近的共同父组件中。

3.3 Hooks（函数组件的“外挂能力”）#

常用三件套：

useState：组件状态
useEffect：副作用（请求/订阅/手动 DOM 操作）
useContext：跨组件共享数据

Hooks 两条硬规则：

只能在函数组件或自定义 Hook 顶层调用（不能写在 if/for/函数里）。
不能在普通 JS 函数里调用。

4. React 项目启动与目录结构（以 Vite 为例）#

初始化项目：

Terminal window

1
npm create vite@latest my-app --template react

典型结构：

1
src/
2
  main.jsx   # 入口：把 React 挂到 DOM
3
  App.jsx    # 根组件：组织页面结构
4
  assets/    # 静态资源
5
index.html   # 页面模板，提供 root 节点

main.jsx 的作用：

1
import ReactDOM from "react-dom/client";
2
import App from "./App.jsx";
3

4
ReactDOM.createRoot(document.getElementById("root")).render(<App />);

createRoot(...).render(...) 相当于“启动 React 应用”。
React 会从 App 作为根节点往下渲染整棵组件树。

5. React 常见生态模块（知道用途即可）#

5.1 路由（React Router）#

用于 SPA 的页面切换：

1
import { BrowserRouter, Routes, Route } from "react-router-dom";

核心概念：

BrowserRouter：路由容器
Routes/Route：路由表
Link：无刷新跳转

5.2 全局状态管理（Redux / Zustand）#

什么时候需要全局状态：

多个无关组件都要用/改同一份数据（例如用户信息、主题、购物车）。

对比：

Redux：强规范、生态大，但模板代码多。
Zustand：轻量直观，新手上手更快。

5.3 UI 组件库 / 样式方案#

Ant Design / Material UI / Chakra UI：现成高质量组件，提高开发效率。
Tailwind CSS：原子化/工具类 CSS，快速拼 UI。

6. React 应用的运行与更新流程#

整体心智模型：

1
用户交互 → 触发事件 → setState 更新状态 → 组件重渲染 → Virtual DOM diff → 更新真实 DOM → UI 刷新

你在写什么：

组件（UI 结构）
状态（数据）
事件（交互）
渲染（JSX 表达 UI）

React 自动帮你做什么：

数据变化驱动 UI 更新
DOM 最小化更新与性能优化

7. JavaScript 基础（React 必备子集）#

7.1 let / const / var#

const：默认使用，引用不可重新指向。
let：需要重新赋值时用。
var：不要用（函数作用域、变量提升问题）。

7.2 常用数据类型#

字符串、数字、布尔值
数组：[1, 2, 3]
对象：{ name: "Tom", age: 20 }

重点：数组/对象是引用类型，更新时要注意“不可变性”。

7.3 函数与箭头函数#

React 中大量使用箭头函数：

1
const add = (a, b) => a + b;

特点：

写法短
this 绑定更直观（函数内 this 取外层）

7.4 条件与 JSX 条件渲染#

JS：

1
if (x > 0) console.log("ok");

JSX 常用：

1
{isLogin ? <User /> : <Login />}
2
{list.length > 0 && <List />}

7.5 map（列表渲染核心）#

map：把数组映射成新数组，不改变原数组。

1
const nums = [1, 2, 3];
2
const squares = nums.map(n => n * n); // [1,4,9]

React 列表渲染：

1
<ul>
2
  {names.map(name => (
3
    <li key={name}>{name}</li>
4
  ))}
5
</ul>

7.6 解构（Destructuring）#

对象解构：

1
const user = { name: "Tom", age: 20 };
2
const { name, age } = user;

数组解构：

1
const nums = [1, 2, 3];
2
const [a, b] = nums; // a=1, b=2

React 里 useState 就是数组解构：

1
const [count, setCount] = useState(0);

7.7 展开运算符（…）与不可变更新#

数组更新：

1
const arr2 = [...arr1, newItem];

对象更新：

1
const newUser = { ...user, age: 21 };

原因：React 依赖“引用变化”判断更新，因此要返回新对象/新数组。

7.8 模块化 import / export#

命名导出（named export）：

utils.js

1
export function add(a, b) { return a + b; }
2
// 使用
3
import { add } from "./utils";

默认导出（default export）：

App.jsx

1
export default function App() {}
2
// 使用
3
import App from "./App";

export 的使用场景：

让其他文件/组件能复用你写的函数、组件、常量、Hook 等。

7.9 Promise 与 async/await#

Promise 写法：

1
fetch(url).then(r => r.json()).then(data => setList(data));

async/await 写法：

1
async function getData() {
2
  const r = await fetch(url);
3
  const data = await r.json();
4
  setList(data);
5
}

React 中常在 useEffect 里请求数据，并用 try/catch 做错误处理。

8. day1 的重点 Q&A 再巩固#

8.1 Counter 例子为什么这样写#

1
const [count, setCount] = useState(0);

useState 返回 [当前值, 更新函数]，用数组解构取出：

count：当前值
setCount：更新值并触发重渲染

点击按钮执行：

1
onClick={() => setCount(count + 1)}

→ 更新 state → React 自动重渲染 → UI 变动。

8.2 map 的本质#

对每个元素执行回调函数
返回新数组
在 React 中用于“数组 → 组件列表”的转换

8.3 数组解构例子#

1
const nums = [1, 2, 3];
2
const [a, b] = nums;

等价于：

1
const a = nums[0]; // 1
2
const b = nums[1]; // 2

8.4 export 给谁用#

你写的内容需要跨文件复用时导出：

组件
工具函数
常量/配置
API 封装
自定义 Hook

9. 学习路径（下一步怎么走）#

把 JS 必备子集练熟：const/let、箭头函数、解构、展开、map、模块化、异步。
深入 React 核心：组件写法、props/state、useState/useEffect、列表/条件渲染。
做小项目巩固：Todo List / 个人博客前端 / 管理后台等。

只要把今天这些“最小必备知识”真正用起来，你就能开始写 React 项目了。

Poetry 命令大全及更新指南

Fri, 02 Oct 2026 00:00:00 GMT

1. 项目初始化与管理#

命令	描述
`poetry new [project-name]`	创建一个新的 Poetry 项目
`poetry init`	交互式创建或更新 `pyproject.toml`文件
`poetry install`	安装项目依赖（根据 `pyproject.toml`和 `poetry.lock`）
`poetry update`	更新依赖到最新允许的版本并更新 `poetry.lock`
`poetry add [package]`	添加依赖包
`poetry add [package]@[version]`	添加指定版本的依赖包
`poetry add [package] --dev`	添加开发依赖包
`poetry remove [package]`	移除依赖包
`poetry show`	显示已安装的依赖包
`poetry show --tree`	以树状结构显示依赖关系
`poetry check`	检查 `pyproject.toml`文件的有效性

2. 虚拟环境管理#

命令	描述
`poetry env list`或 `poetry env list --full-path`	列出所有 Poetry 虚拟环境
`poetry env info`	显示当前项目的虚拟环境信息
`poetry env use [python-path]`	为项目指定 Python 解释器
`poetry env remove [env-name or path]`	删除虚拟环境
`poetry shell`	激活项目的虚拟环境（进入交互式 shell）
`poetry run [command]`	在虚拟环境中运行命令，不激活 shell

3. 打包与发布#

命令	描述
`poetry build`	构建项目为可分发的包（生成 `.tar.gz`和 `.whl`文件）
`poetry publish`	将包发布到 PyPI 或其他配置的仓库
`poetry publish --repository [repo-name]`	发布到指定的仓库
`poetry config repositories.[repo-name] [repo-url]`	配置私有仓库

4. 配置管理#

命令	描述
`poetry config --list`	列出所有配置
`poetry config [key] [value]`	设置配置值（如 `poetry config virtualenvs.create true`）
`poetry config --unset [key]`	删除配置值
`poetry self update`	更新 Poetry 自身

5. 锁定文件管理#

命令	描述
`poetry lock`	生成或更新 `poetry.lock`文件（不安装依赖）
`poetry lock --no-update`	仅根据 `pyproject.toml`重新生成 `poetry.lock`，不更新依赖版本

2026 年 9 月复盘：换赛道的第一个月

Wed, 30 Sep 2026 00:00:00 GMT

9 月发生了两件事：一是工作方向调整，从原来的业务开发转到智能体方向；二是手上的架构设计第一次完整走完了「设计—评审—进入开发」的全流程。月底回头看，这个月的关键词是节奏和文档。

换赛道：从写功能到写架构#

月初转岗，方向是金融领域的 AI Agent。第一个感受是工作颗粒度变了：以前是拿到需求拆任务写代码，现在是先想清楚数据从哪来、模块怎么切、失败了怎么办，代码反而是最后落笔的。

这个月主要推了两条线：

问答式取数：让业务人员用自然语言查数据，背后是检索增强、语义解析和结果校验的组合。难点不在调模型，在于怎么让「答错了」可解释、可回退。
尽职报告生成：给某大型银行做的报告类 Agent。文档类生成的坑在于模板是活的、输入是脏的，「可编辑」和「自动」之间的边界要提前划清，否则联调阶段会互相打架。

两条线的架构设计都在月底前通过了评审，进入开发和联调阶段。BUG 数量也控制在个位数，算是给这个月收了个好尾。

三件印象深的事#

1. 文档欠的债一定会还。 月中被抽了一整天补架构文档。补的过程中发现，之前凭记忆做的几个设计决策，实际实现已经跑偏了，是文档让我重新对齐了一次。以前觉得写文档是给别人的交代，现在觉得是给两周后失忆的自己留证据。

2. 会开多了，代码就慢了。 有几天几乎全天在开会和对齐，晚上才摸键盘。不抱怨会议本身——跨部门协作确实需要——但我的结论是：重要的设计讨论要带结论出门，散会前把「谁、做什么、什么时候」说清楚，否则会议成本会翻倍。

3. 「可编辑」是很贵的需求。 报告生成那条线，「模板可编辑」四个字背后是模板管理、版本控制、字段映射一整套东西。需求评审时多问一句「这个功能给谁用、多久用一次」，能把很多后续的返工提前砍掉。

下个月#

两条线进入开发冲刺，重点是联调质量和错误处理。
把这个月沉淀的架构笔记整理出来，一部分发到博客上。
控制会议时间，保住整块的深度工作时段。

复盘写在月底，不为给别人看，就为下个月的自己少踩一个坑。

Linux screen 命令详解

Wed, 30 Sep 2026 00:00:00 GMT

Linux `screen` 命令详解#

screen 是一个终端复用工具，允许你在单个终端窗口中创建多个虚拟终端会话，并在后台保持运行，即使断开 SSH 连接也不会中断任务。

常用 `screen` 命令#

1. 基本操作#

命令	说明
`screen`	启动一个新的 screen 会话
`screen -S <name>`	创建一个命名的 screen 会话（推荐）
`screen -ls`	列出所有 screen 会话
`screen -r <ID或name>`	恢复（重新连接）一个已存在的 screen 会话
`screen -d <ID或name>`	分离（Detach）一个 screen 会话（不关闭，仅退出）
`screen -X -S <ID或name> quit`	强制关闭某个 screen 会话

2. 会话内操作（快捷键：`Ctrl + A` 后接命令）#

快捷键	说明
`Ctrl + A + C`	在当前会话中新建窗口
`Ctrl + A + N`	切换到下一个窗口
`Ctrl + A + P`	切换到上一个窗口
`Ctrl + A + 0-9`	直接切换到第 N 个窗口（0-9）
`Ctrl + A + D`	分离（Detach）当前会话（不关闭，仅退出）
`Ctrl + A + K`	强制关闭当前窗口
`Ctrl + A + [Space]`	切换到下一个窗口（循环）
`Ctrl + A + W`	显示当前所有窗口列表
`Ctrl + A + ?`	查看所有快捷键帮助

3. 高级用法#

命令	说明
`screen -dmS <name> <command>`	在后台启动一个 screen 会话并运行命令
`screen -x`	共享 screen 会话（多人协作）
`screen -r -d <ID或name>`	强制恢复一个已连接的会话（先 Detach 再恢复）

典型使用场景#

长时间运行任务（如编译、下载、训练模型）：

Terminal window

1
screen -S long_task
2
./run_long_script.sh
3
# 按 Ctrl + A + D 退出，任务继续运行

恢复会话：

Terminal window

1
screen -ls  # 查看会话列表
2
screen -r long_task  # 恢复

后台启动任务：
Terminal window
```
1
screen -dmS my_task python3 train.py
```
多窗口管理：
- Ctrl + A + C 创建新窗口
- Ctrl + A + N/P 切换窗口

总结#

screen 适合长时间运行任务，即使 SSH 断开也能恢复。
推荐使用 -S <name> 给会话命名，方便管理。
Ctrl + A + D 是最常用的退出方式（不关闭会话）。
screen -ls 查看所有会话，screen -r 恢复会话。

Tmux 详解：终端复用利器

Mon, 28 Sep 2026 00:00:00 GMT

Tmux 详解：终端复用利器#

tmux（Terminal Multiplexer）是比 screen 更强大的终端复用工具，支持多窗口、多面板、会话持久化等功能，适合远程服务器管理、长时间任务运行和高效终端操作。

1. Tmux 核心概念#

Tmux 采用 Server → Session → Window → Pane 的层级结构：

Server：管理所有会话的后台进程（tmux 启动时自动运行）。
Session：一组窗口的集合（类似 screen 会话）。
Window：单个会话中的多个标签页（类似浏览器标签）。
Pane：窗口内的分屏（可横向/纵向切割）。

2. 安装 Tmux#

Linux (Debian/Ubuntu)#

Terminal window

1
sudo apt install tmux

Linux (CentOS/RHEL)#

Terminal window

1
sudo yum install tmux

macOS (Homebrew)#

Terminal window

1
brew install tmux

3. 基本操作#

启动 Tmux#

Terminal window

1
tmux                     # 启动新会话（默认编号）
2
tmux new -s <name>       # 启动命名会话（推荐）

会话管理#

命令	说明
`tmux ls`	列出所有会话
`tmux attach -t <name>`	恢复指定会话
`tmux kill-session -t <name>`	关闭指定会话
`tmux kill-server`	关闭所有会话（慎用）

快捷键（前缀键 `Ctrl+B` ）#

Tmux 的所有快捷键都需要先按 Ctrl+B（前缀键），然后按后续命令键。

4. 窗口（Window）操作#

快捷键	说明
`Ctrl+B C`	创建新窗口
`Ctrl+B N`	切换到下一个窗口
`Ctrl+B P`	切换到上一个窗口
`Ctrl+B 0-9`	直接跳转到第 N 个窗口
`Ctrl+B ,`	重命名当前窗口
`Ctrl+B &`	关闭当前窗口

Ctrl+B d 分离

5. 面板（Pane）操作#

快捷键	说明
`Ctrl+B %`	垂直分割面板
`Ctrl+B "`	水平分割面板
`Ctrl+B ↑↓←→`	切换面板方向
`Ctrl+B Z`	最大化当前面板（再按恢复）
`Ctrl+B X`	关闭当前面板
`Ctrl+B Space`	切换面板布局

6. 会话持久化#

Tmux 会话在 SSH 断开后仍然保持运行，重新连接后恢复：

Terminal window

1
tmux attach -t <name>   # 重新连接会话

7. 高级功能#

(1) 复制模式（类似 Vim）#

Ctrl+B [ 进入复制模式
用 ↑↓←→ 移动光标，Space 开始选择，Enter 复制
Ctrl+B ] 粘贴

(2) 共享会话（多人协作）#

Terminal window

1
tmux new -s shared       # 创建共享会话
2
tmux attach -t shared    # 其他人连接

(3) 配置文件 `~/.tmux.conf`#

自定义 Tmux 行为（如修改前缀键、主题等）：

Terminal window

1
# 示例：更改前缀键为 Ctrl+A
2
set -g prefix C-a
3
unbind C-b
4
bind C-a send-prefix

8. Tmux vs. Screen#

功能	Tmux	Screen
分屏	✔️（支持多面板）	❌（仅单窗口）
会话管理	✔️（更强大）	✔️
快捷键	`Ctrl+B`	`Ctrl+A`
脚本化	✔️（支持配置）	❌
共享会话	✔️	✔️

9. 典型使用场景#

远程服务器管理（SSH 断开后任务继续运行）
多任务并行（编译、日志监控、代码编辑）
团队协作（共享终端会话）
高效终端操作（分屏、快捷键）

总结#

tmux 比 screen 更强大，适合复杂终端管理。
核心操作：
- tmux new -s <name>（创建会话）
- Ctrl+B % / "（分屏）
- tmux attach -t <name>（恢复会话）
推荐配置：修改 ~/.tmux.conf 优化体验。

Rust 所有权与核心概念完整指南

Sun, 20 Sep 2026 00:00:00 GMT

1. 字符串字面量 `&str`#

1
let s = "hello";  // 类型：&str

特点：

存储在栈上（实际在二进制文件的只读内存中）
不可变
编译时已知大小
是对固定字符串的引用（借用）
零开销，最高效

2. `String` 类型#

1
let s = String::from("hello");  // 类型：String

特点：

数据存储在堆上
可变（可以修改）
运行时动态分配内存
拥有数据的所有权
离开作用域时自动释放内存

3. 两者对比#

特性	`&str`	`String`
存储位置	栈（只读内存）	堆
可变性	不可变	可变
大小	编译时已知	运行时动态
所有权	借用	拥有
性能	最快	稍慢（堆分配）

4. 相互转换#

1
// &str -> String
2
let s1 = "hello".to_string();
3
let s2 = String::from("hello");
4

5
// String -> &str
6
let s3 = String::from("hello");
7
let s4 = &s3[0..3];  // "hel"
8
let s5 = &s3;         // 自动转换

第二部分：可变性（`mut` 关键字）#

1. 基本概念#

1
let x = 5;        // 不可变（默认）
2
let mut y = 5;    // 可变
3
y = 10;           // ✅ 可以修改
4
// x = 10;        // ❌ 编译错误！

2. 为什么默认不可变？#

防止意外修改
更容易推理代码
编译器可以做更多优化
内存安全保证

3. 可变性的应用场景#

1
// 1. 变量绑定
2
let mut count = 0;
3
count += 1;
4

5
// 2. 函数参数
6
fn increment(mut num: i32) {
7
    num += 1;
8
}
9

10
// 3. String 的可变性
11
let mut s = String::from("hello");
12
s.push_str(" world");  // 可以修改
13

14
// 4. 结构体字段
15
struct User {
16
    name: String,
17
    age: u32,
18
}
19
let mut user = User { name: "Alice".to_string(), age: 30 };
20
user.age = 31;  // 整个结构体必须是 mut

展开收起

4. mut 与所有权的关系#

1
let mut s = String::from("hello");
2
let t = &mut s;  // 可变引用
3
t.push_str(" world");
4

5
// let u = &mut s;  // ❌ 不能同时有多个可变引用

第三部分：内存分配（栈 vs 堆）#

1. 栈（Stack）#

特点：

后进先出（LIFO）
存储已知大小的数据
分配和释放极快
函数调用时自动管理

存储内容：

1
let a = 5;              // 整数
2
let b = true;           // 布尔
3
let c = 'A';            // 字符
4
let d = [1, 2, 3];      // 数组（固定大小）
5
let e = (4, 5.6);       // 元组（固定大小）
6
let f = "hello";        // 字符串字面量（&str）

2. 堆（Heap）#

特点：

动态分配
存储未知大小或需要增长的数据
分配较慢
需要手动或自动（Rust）管理

存储内容：

1
let s = String::from("hello");  // 字符串内容
2
let v = vec![1, 2, 3];          // 向量内容
3
let b = Box::new(42);           // Box 数据

3. 内存布局图解#

1
let s = String::from("hello");

1
栈（Stack）              堆（Heap）
2
┌─────────────┐         ┌─────────────┐
3
│  s (指针)    │────────>│  "hello"    │
4
│  长度: 5     │         │   h e l l o │
5
│  容量: 5     │         └─────────────┘
6
└─────────────┘

4. 可变性与存储位置无关#

变量	可变性	存储位置	示例
`let x = 5`	不可变	栈	整数、布尔、字符
`let mut x = 5`	可变	栈	同上，但可改值
`let s = String::from("hi")`	不可变	栈指针→堆数据	字符串内容在堆上
`let mut s = String::from("hi")`	可变	栈指针→堆数据	可以修改堆上内容

第四部分：`Box<T>` 智能指针#

1. 什么是 Box？#

Box<T> 是 Rust 提供的堆内存分配器：

1
let x = 5;              // 存储在栈上
2
let y = Box::new(5);    // 存储在堆上，栈上只存指针

2. 内存布局#

1
let boxed = Box::new(42);

1
栈（Stack）              堆（Heap）
2
┌─────────────┐         ┌─────────────┐
3
│  boxed       │────────>│    42       │
4
│  (指针)      │         │  (实际数据)  │
5
└─────────────┘         └─────────────┘

3. Box 的主要用途#

(1) 递归数据结构#

1
enum List {
2
    Cons(i32, Box<List>),  // Box 让递归成为可能
3
    Nil,
4
}
5

6
// 如果不用 Box
7
// enum List {
8
//     Cons(i32, List),  // ❌ 编译错误：无限大小！
9
//     Nil,
10
// }

(2) 特征对象（多态）#

1
trait Animal {
2
    fn sound(&self);
3
}
4

5
struct Dog;
6
impl Animal for Dog {
7
    fn sound(&self) { println!("汪汪！"); }
8
}
9

10
struct Cat;
11
impl Animal for Cat {
12
    fn sound(&self) { println!("喵喵！"); }
13
}
14

15
let animals: Vec<Box<dyn Animal>> = vec![
16
    Box::new(Dog),
17
    Box::new(Cat),
18
];

展开收起

(3) 让枚举大小固定#

1
enum Data {
2
    Small(Vec<u8>),
3
    Large(Box<Vec<u8>>),  // Box 让枚举大小固定
4
}

4. Box 的自动解引用#

1
let mut boxed = Box::new(vec![1, 2, 3]);
2
boxed.push(4);     // ✅ 自动解引用，直接使用
3
boxed[0] = 42;     // ✅ 自动解引用
4

5
// 特殊情况需要手动解引用
6
let mut b = Box::new(5);
7
*b = 10;           // ✅ 修改值需要 *

5. Box vs 普通变量#

特性	普通变量	Box
存储位置	栈上	堆上
内存大小	实际数据大小	8字节（指针）
所有权	直接拥有数据	拥有堆上数据
性能	更快	稍慢（间接访问）

第五部分：`Vec<T>` 泛型集合#

1. 基本概念#

1
Vec<u8>     // 存储 u8 类型（无符号8位整数）
2
Vec<i32>    // 存储 i32 类型
3
Vec<String> // 存储 String 类型
4
Vec<f64>    // 存储 f64 类型

2. 类型大小#

类型	单个元素大小	范围
`u8`	1 字节	0 ~ 255
`i32`	4 字节	-2,147,483,648 ~ 2,147,483,647
`f64`	8 字节	±1.8e308（双精度）
`String`	24 字节（指针+长度+容量）	动态

3. 内存占用#

1
// Vec 本身在栈上占 24 字节
2
// 堆上数据 = 元素个数 × 每个元素大小
3

4
let v1: Vec<u8> = vec![0; 1000];   // 堆上占 1000 字节
5
let v2: Vec<i32> = vec![0; 1000];  // 堆上占 4000 字节

4. 重要概念#

1
// Vec 的数据在堆上，不是栈上！
2
let huge_array = vec![0; 1000000];  // 数据在堆上
3

4
// 转移所有权只复制指针（高效）
5
let vec1 = vec![0; 1000000];
6
let vec2 = vec1;  // 只复制了3个字节（指针、长度、容量）
7
// vec1 不再可用
8

9
// clone 会复制所有数据（慢）
10
let vec3 = vec![0; 1000000];
11
let vec4 = vec3.clone();  // 复制了100万个元素

第六部分：枚举（`enum`）#

1. Rust enum vs Python enum#

Python：简单枚举值

1
from enum import Enum
2
class Color(Enum):
3
    RED = 1
4
    GREEN = 2

Rust：强大的标签联合（可以携带数据）

1
enum Color {
2
    Red,
3
    Green,
4
    Blue,
5
}
6

7
enum Message {
8
    Quit,                       // 无数据
9
    Move { x: i32, y: i32 },    // 结构体数据
10
    Write(String),              // 单个数据
11
    ChangeColor(u8, u8, u8),    // 元组数据
12
}

2. 枚举变体#

1
enum List {
2
    Cons(i32, Box<List>),  // 变体1：包含值和下一个节点
3
    Nil,                   // 变体2：空链表
4
}
5

6
// 使用变体
7
let node = List::Cons(5, Box::new(List::Nil));

3. 使用 `use` 简化路径#

1
// 完整路径
2
let list = List::Cons(1, Box::new(List::Nil));
3

4
// 导入后简化
5
use List::{Cons, Nil};
6
let list = Cons(1, Box::new(Nil));

4. 匹配枚举#

1
match small_data {
2
    Data::Small(vec) => println!("小数据：{:?}", vec),
3
    Data::Large(vec) => println!("大数据：长度 {}", vec.len()),
4
}

第七部分：Cons 链表#

1. Cons 是什么？#

Cons 来自 Lisp 语言，是 “Constructor” 的缩写：

Cons = 一个节点，包含当前值和指向下一个节点的指针
Nil = 空链表（结束标志）

2. 链表定义#

1
enum List {
2
    Cons(i32, Box<List>),  // 值 + 指向下一个节点的指针
3
    Nil,                   // 空
4
}
5

6
// 链表：1 -> 2 -> 3 -> Nil
7
// Cons(1, Cons(2, Cons(3, Nil)))

3. 构建链表#

1
// 从尾部开始构建
2
let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil))))));
3

4
// 逐步构建
5
let tail = Cons(3, Box::new(Nil));
6
let mid = Cons(2, Box::new(tail));
7
let head = Cons(1, Box::new(mid));

4. 内存布局#

1
栈                          堆
2
┌──────────────┐           ┌──────────────┐
3
│ list (头部)   │──────────>│ Cons(1)     │
4
└──────────────┘           │  next ──────┐│
5
                           └─────────────┴│
6
                                           ▼
7
                           ┌──────────────┐
8
                           │ Cons(2)     │
9
                           │  next ──────┐│
10
                           └─────────────┴│
11
                                           ▼
12
                           ┌──────────────┐
13
                           │ Cons(3)     │
14
                           │  next ──────┐│
15
                           └─────────────┴│
16
                                           ▼
17
                           ┌──────────────┐
18
                           │ Nil         │
19
                           └──────────────┘

展开收起

5. 更优雅的构建方式#

1
// 使用标准库
2
use std::collections::LinkedList;
3
let mut list = LinkedList::new();
4
list.extend([1, 2, 3]);
5

6
// 使用 Vec（推荐！）
7
let list = vec![1, 2, 3];  // 90% 的情况用 Vec 就够了

第八部分：操作符 `.` vs `::`#

1. 核心规则#

1
// . 用于实例（已经创建的对象）
2
// :: 用于类型/模块（命名空间）

2. `.` 点操作符#

用于实例的字段和方法：

1
struct Person {
2
    name: String,
3
    age: u32,
4
}
5

6
impl Person {
7
    fn greet(&self) {
8
        println!("你好，我是{}", self.name);
9
    }
10
}
11

12
let p = Person { name: "Alice".to_string(), age: 30 };
13
p.greet();          // ✅ 调用实例方法
14
println!("{}", p.name);  // ✅ 访问实例字段

3. `::` 双冒号操作符#

用于类型级别的东西：

1
// 1. 关联函数（类似静态方法）
2
let s = String::from("hello");
3
let v = Vec::new();
4

5
// 2. 枚举变体
6
let c = Color::Red;
7

8
// 3. 模块路径
9
use std::collections::HashMap;
10

11
// 4. 关联常量
12
struct Config;
13
impl Config {
14
    const VERSION: u32 = 1;
15
}
16
println!("{}", Config::VERSION);

展开收起

4. 完整对比表#

操作符	使用场景	示例
`.`	访问实例字段	`person.name`
`.`	调用实例方法	`person.greet()`
`.`	访问元组索引	`tuple.0`
`::`	调用关联函数	`String::from("hi")`
`::`	访问关联常量	`MyStruct::VERSION`
`::`	访问枚举变体	`Color::Red`
`::`	模块路径	`std::collections::HashMap`

5. 从 Python 角度理解#

1
class Config:
2
    DEFAULT = 100  # 类属性（类似关联常量）
3

4
    def __init__(self, value):
5
        self.value = value  # 实例属性
6

7
print(Config.DEFAULT)        # 类属性访问
8
config = Config(42)
9
print(config.value)          # 实例属性访问

1
struct Config {
2
    value: i32,
3
}
4

5
impl Config {
6
    const DEFAULT: i32 = 100;  // 关联常量
7
}
8

9
println!("{}", Config::DEFAULT);  // :: 访问
10
let config = Config { value: 42 };
11
println!("{}", config.value);     // . 访问

第九部分：解引用运算符 `*`#

1. 基本概念#

* 是解引用运算符，用于”跟随指针拿到数据”。

2. 使用场景#

1
// 1. 栈上的引用
2
let x = 42;
3
let r = &x;
4
println!("{}", *r);  // 解引用，拿到 42
5

6
// 2. 堆上的数据（Box）
7
let b = Box::new(100);
8
println!("{}", *b);  // 解引用，拿出 100

3. 自动解引用#

Rust 会自动解引用，大多数情况不需要手动 *：

1
let mut boxed = Box::new(vec![1, 2, 3]);
2
boxed.push(4);        // ✅ 自动解引用
3
println!("{}", boxed[0]);  // ✅ 自动解引用

4. 何时需要手动 `*`#

1
// 1. 修改 Box 的值
2
let mut b = Box::new(5);
3
*b = 10;  // ✅ 必须用 *
4

5
// 2. 取出所有权
6
let b = Box::new(String::from("hello"));
7
let s = *b;  // ✅ 取出堆上的 String
8

9
// 3. 自定义类型的访问
10
struct Point { x: i32, y: i32 }
11
let p = Box::new(Point { x: 1, y: 2 });
12
println!("{}", (*p).x);  // 可以，但 p.x 更常见

5. 解引用总结#

操作符	作用	何时需要
`*`	解引用（跟随指针）	修改 Box 的值、取出所有权
`.`	自动解引用	调用方法时自动处理
`[]`	索引（自动解引用）	访问 Vec 等容器元素

第十部分：完整代码示例#

1
// 1. 字符串类型
2
fn string_examples() {
3
    let s1 = "hello";  // &str，栈上
4
    let s2 = String::from("world");  // String，堆上
5

6
    let mut s3 = String::from("hello");
7
    s3.push_str(" world");  // 可以修改
8
    println!("{}", s3);
9
}
10

11
// 2. Box 使用
12
fn box_examples() {
13
    let b = Box::new(42);
14
    println!("{}", *b);  // 解引用
15

16
    let mut b2 = Box::new(10);
17
    *b2 = 20;  // 修改
18
    println!("{}", b2);  // 自动解引用
19
}
20

21
// 3. 枚举和链表
22
enum List {
23
    Cons(i32, Box<List>),
24
    Nil,
25
}
26

27
fn list_examples() {
28
    use List::{Cons, Nil};
29

30
    let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil))))));
31

32
    // 遍历
33
    let mut current = &list;
34
    while let Cons(value, next) = current {
35
        print!("{} -> ", value);
36
        current = next;
37
    }
38
    println!("Nil");
39
}
40

41
// 4. Vec 使用
42
fn vec_examples() {
43
    let mut v = vec![1, 2, 3];
44
    v.push(4);
45
    v[0] = 10;
46
    println!("{:?}", v);  // [10, 2, 3, 4]
47

48
    // Vec 数据在堆上
49
    let big = vec![0; 1000000];
50
    let moved = big;  // 所有权转移，只复制指针
51
    // println!("{}", big[0]);  // ❌ big 已失效
52
}
53

54
// 5. 结构体和关联常量
55
struct Config {
56
    pub value: i32,
57
}
58

59
impl Config {
60
    const DEFAULT: i32 = 100;
61

62
    fn new(value: i32) -> Self {
63
        Config { value }
64
    }
65

66
    fn get_value(&self) -> i32 {
67
        self.value
68
    }
69
}
70

71
fn struct_examples() {
72
    println!("{}", Config::DEFAULT);  // :: 访问关联常量
73

74
    let config = Config::new(42);     // :: 调用关联函数
75
    println!("{}", config.value);     // . 访问字段
76
    println!("{}", config.get_value()); // . 调用方法
77
}
78

79
// 6. main 函数
80
fn main() {
81
    string_examples();
82
    box_examples();
83
    list_examples();
84
    vec_examples();
85
    struct_examples();
86
}

展开收起

总结：核心要点速查#

内存管理#

栈：固定大小，快速，自动管理
堆：动态大小，较慢，需要显式管理（Rust 自动清理）

所有权规则#

每个值都有一个所有者
同一时间只能有一个所有者
所有者离开作用域时值被丢弃

可变性#

默认不可变（let）
需要可变时用 mut
可变性与存储位置无关

字符串#

&str：不可变，栈上，借用
String：可变，堆上，拥有所有权

智能指针#

Box<T>：堆分配，拥有所有权
用于递归类型、特征对象、固定枚举大小

集合#

Vec<T>：动态数组，数据在堆上
LinkedList：双向链表，标准库提供

操作符#

.：实例级别（字段、方法）
::：类型级别（关联函数、常量、枚举变体）
*：解引用（跟随指针）

枚举#

强大的标签联合
可以携带数据
变体可以用 use 导入

LangChain VectorStore 的几种检索方式

Mon, 14 Sep 2026 00:00:00 GMT

👉 最常用，按向量相似度排序，返回最接近的文档。

参数：
- query: 查询文本
- k: 返回的文档数
作用：找出“最相似”的内容，适合大多数问答场景。
缺点：不会考虑“查询和文档的匹配相关性权重”，只看向量。

1
docs = vectorstore.similarity_search("拜登的气候政策", k=3)

2. `similarity_search_with_score`#

👉 和 similarity_search 一样，但会返回 相似度分数。

作用：
- 可根据分数过滤低相关性文档；
- 适合需要“阈值控制”的任务（比如只要相似度 >0.8 的结果）。

1
docs = vectorstore.similarity_search_with_score("气候变化", k=3)
2
for doc, score in docs:
3
    print(doc.page_content, score)

3. `max_marginal_relevance_search` (MMR)#

👉 最大边际相关性检索，在相似度的基础上增加“多样性”。

作用：
- 避免检索结果过于重复；
- 适合用户需要“覆盖不同角度”的问题，比如“中美关系”时返回中方和美方新闻，而不是全是中方的。
机制：
- 在相似度高的候选中，挑一部分相似但彼此差异大的文档。

1
docs = vectorstore.max_marginal_relevance_search("国际气候合作", k=5, fetch_k=20)

4. `similarity_search_by_vector`#

👉 如果你 自己已经有了 query 的向量（比如外部 embedding 模型算的），可以直接用这个接口。

作用：绕过 LangChain 的 embedding，直接用外部向量进行搜索。
适合场景：比如你有多模态输入（图像、音频 → embedding），但想在同一个 Milvus 里检索文本。

1
embedding_vector = [0.12, -0.33, 0.88, ...]  # 自己算的
2
docs = vectorstore.similarity_search_by_vector(embedding_vector, k=3)

5. `as_retriever`#

👉 把向量库封装成一个 Retriever，供 RAG / QA Chain 使用。

优势：
- 统一接口，可以随意切换 FAISS、Milvus、PGVector；
- 可以配合 RetrievalQA、ConversationalRetrievalChain 等。
检索模式可配置（例如 similarity / MMR）：

1
retriever = vectorstore.as_retriever(search_type="mmr", search_kwargs={"k": 5})
2
docs = retriever.get_relevant_documents("拜登在联合国说了什么")

📝 总结对比#

方法	功能	适合场景
`similarity_search`	按相似度取Top-K	默认、通用
`similarity_search_with_score`	相似度+分数	需要阈值过滤
`max_marginal_relevance_search`	相似+多样性	避免结果重复、覆盖不同角度
`similarity_search_by_vector`	直接用外部向量查	多模态 / 自定义 embedding
`as_retriever`	转换成Retriever	RAG、QA链集成

LangChain PromptTemplate 详解：把 Prompt 当代码管理

Fri, 11 Sep 2026 00:00:00 GMT

PromptTemplate 是 LangChain 的核心模块之一，作用是 组织和动态生成 Prompt。
它解决的问题是：Prompt 不能写死，需要和用户输入 / 任务上下文结合，保持复用和一致性。

1. PromptTemplate 的核心作用#

模板化 Prompt：用 {} 占位，把变量和固定内容分离。
动态渲染：运行时把用户输入填充进去。
减少重复代码：把 Prompt 逻辑集中管理，而不是散落在代码里。
结构化输出：结合 parser，可以要求模型输出 JSON / YAML 等格式。

2. 基本用法#

（1）最简单的创建方式#

1
from langchain.prompts import PromptTemplate
2

3
template = "把以下中文翻译成英文: {text}"
4
prompt = PromptTemplate.from_template(template)
5

6
# 渲染
7
print(prompt.format(text="你好，世界"))
8
# => "把以下中文翻译成英文: 你好，世界"

（2）带多个变量#

1
template = "请写一首关于 {animal} 和 {place} 的诗"
2
prompt = PromptTemplate.from_template(template)
3

4
print(prompt.format(animal="小猫", place="月亮"))

输出：

1
请写一首关于 小猫 和 月亮 的诗

（3）显式指定输入变量#

1
prompt = PromptTemplate(
2
    input_variables=["product", "style"],
3
    template="请写一个关于 {product} 的广告文案，风格是 {style}"
4
)
5

6
print(prompt.format(product="咖啡", style="幽默"))

3. 高级功能#

（1）PromptTemplate + Partial（部分固定）#

有时候某些变量是 固定的，可以先“绑定”住。

1
prompt = PromptTemplate.from_template(
2
    "把以下内容翻译成 {language}: {text}"
3
)
4

5
# 固定 language
6
partial_prompt = prompt.partial(language="English")
7
print(partial_prompt.format(text="早上好"))

（2）多层 Prompt 组合#

你可以把小模板组合成复杂的 Prompt。

1
intro_prompt = PromptTemplate.from_template("用户问题是: {question}")
2
task_prompt = PromptTemplate.from_template("请根据以下问题生成 SQL: {question}")
3

4
full_prompt = intro_prompt.format(question="查询今天销量")
5
print(full_prompt)
6
print(task_prompt.format(question="查询今天销量"))

（3）和输出解析器结合#

LangChain 提供 OutputParser，可以结合 PromptTemplate，指导模型输出 JSON、列表等结构化结果。

1
from langchain.output_parsers import ResponseSchema, StructuredOutputParser
2

3
schemas = [
4
    ResponseSchema(name="summary", description="文本总结"),
5
    ResponseSchema(name="keywords", description="关键词"),
6
]
7

8
parser = StructuredOutputParser.from_response_schemas(schemas)
9
format_instructions = parser.get_format_instructions()
10

11
prompt = PromptTemplate.from_template("""
12
请分析以下文本：
13
{text}
14

15
请严格按照以下格式输出：
16
{format_instructions}
17
""")
18

19
print(prompt.format(text="今天股市上涨，投资人情绪积极", format_instructions=format_instructions))

展开收起

这样 Prompt 会明确告诉模型输出 JSON，并能用 parser.parse() 解析。

（4）Few-shot Prompting#

PromptTemplate 可以和 示例库（FewShotPromptTemplate） 配合，让模型参考样例。

1
from langchain.prompts import FewShotPromptTemplate
2

3
examples = [
4
    {"word": "猫", "translation": "cat"},
5
    {"word": "狗", "translation": "dog"},
6
]
7

8
example_template = "中文: {word} -> 英文: {translation}"
9
example_prompt = PromptTemplate.from_template(example_template)
10

11
prompt = FewShotPromptTemplate(
12
    examples=examples,
13
    example_prompt=example_prompt,
14
    suffix="中文: {input} -> 英文:",
15
    input_variables=["input"]
16
)
17

18
print(prompt.format(input="苹果"))

展开收起

输出大致为：

1
中文: 猫 -> 英文: cat
2
中文: 狗 -> 英文: dog
3
中文: 苹果 -> 英文:

（5）动态选择模板（Selector）#

如果你的输入场景复杂，可以让 LangChain 自动挑选最合适的模板。

例如：

用户输入太短 → 用简单 Prompt
用户输入很长 → 用总结型 Prompt

（这里可以结合 LengthBasedExampleSelector 等工具）

4. PromptTemplate 的常见技巧#

用大括号 {{ }} 转义
如果你要在模板里输出固定的花括号（比如 JSON），要用双层：
```
1
template = "输出 JSON: {{'a': '{value}'}}"
2
prompt = PromptTemplate.from_template(template)
3
print(prompt.format(value="测试"))
```
✅ 否则会被误认为是占位符。
加入格式约束
- 在 Prompt 里明确说明输出必须是 JSON / Markdown / 表格。
- 给出样例输出，效果更稳定。
分层管理 Prompt
- 用不同的 PromptTemplate 管不同任务（翻译 / 总结 / 检索）。
- 在 Chain 里组合，减少重复。
调试 Prompt
- prompt.format() 先看看渲染结果，再丢给 LLM。
- 建议用 LangSmith 或日志系统跟踪实际 Prompt。

5. 总结#

PromptTemplate = 占位 + 模板渲染。
支持：单变量、多变量、部分固定、FewShot、解析器、动态选择。
核心技巧：转义、格式约束、样例提示、日志调试。
价值：让 Prompt 结构化、复用、可控，避免硬编码。

如何输出json

LangChain 的 Tools 体系：给 LLM 装上手和脚

Tue, 08 Sep 2026 00:00:00 GMT

LangChain 的核心之一是 Agent + Tools。
它的理念是：LLM 本身是生成文本的能力，但很多任务需要调用外部工具/系统，比如搜索、计算、数据库查询、API 调用。

1. 基本概念#

（1）Tool#

定义：一个 Python 对象，封装了外部能力（函数、API、数据库等）。
接口：至少包含两个属性：
- name：工具名
- func：执行函数
- description：给 LLM 说明工具做什么
LLM 会根据 prompt + description 决定调用哪个工具。

示例：

1
from langchain.tools import Tool
2

3
def calculator(query: str) -> str:
4
    return str(eval(query))
5

6
calc_tool = Tool(
7
    name="Calculator",
8
    func=calculator,
9
    description="用于执行数学运算，例如 2+2"
10
)

（2）Agent#

Agent 是一个 智能决策者，根据用户输入：
1. 思考（LLM分析问题）
2. 决定调用哪个 Tool
3. 执行 Tool
4. 收集结果并继续思考
LangChain 内置多种 agent 类型：
- ZeroShotAgent
- ReActAgent
- ConversationalAgent
- StructuredToolAgent（结合输出解析器）

2. 工具使用方式#

（1）简单工具调用#

1
from langchain.agents import initialize_agent
2

3
tools = [calc_tool]
4

5
agent = initialize_agent(tools, llm, agent="zero-shot-react-description", verbose=True)
6

7
agent.run("计算 123 * 456")

输出：

1
56088

（2）结合多工具#

可以同时注册 搜索、计算、数据库查询、API。
LLM 会选择最合适的工具：

1
from langchain.agents import Tool
2

3
search_tool = Tool(
4
    name="Search",
5
    func=lambda x: "搜索结果: xxx",
6
    description="搜索互联网以获取最新信息"
7
)
8

9
agent = initialize_agent([calc_tool, search_tool], llm, agent="zero-shot-react-description")
10
agent.run("查找今天的天气并计算温度差")

LLM 会先调用 Search，然后 Calculator，再返回答案。

3. 多步骤工具链 (MCP / Multi-Tool Chain)#

你提到 MCP（Multi-Chain / Multi-Tool Pipeline）概念，其实 LangChain 的 Agent + Tools + Chains 就可以实现类似功能：

Multi-Step Chain（SequentialChain / RouterChain）可以串联多个工具调用流程。
Agent + Tools 可以动态选择工具和顺序，形成“多工具任务处理管线”。
目前 LangChain 官方没有叫“MCP”的模块，但完全可以通过：
- RouterChain + Agents + Tool
- SequentialChain + Multi-Tool Agent
  来实现多工具并行或串行调用。

（3）示意：MCP 风格工作流#

1
from langchain.chains import SequentialChain
2

3
# 假设有三个工具
4
tools = [calc_tool, search_tool]
5

6
# Step1: 查询问题相关背景
7
search_chain = LLMChain(
8
    llm=llm,
9
    prompt=PromptTemplate.from_template("请搜索问题背景: {query}"),
10
    output_key="search_result"
11
)
12

13
# Step2: 计算结果
14
calc_chain = LLMChain(
15
    llm=llm,
16
    prompt=PromptTemplate.from_template("根据背景 {search_result} 计算结果: {query}"),
17
    output_key="calc_result"
18
)
19

20
workflow = SequentialChain(chains=[search_chain, calc_chain], input_variables=["query"], output_variables=["calc_result"])
21

22
workflow.invoke({"query": "计算今天的温差"})

展开收起

这里每一步都可以调用不同的工具。
实际上就是 多工具、多步骤执行管线，可以视作 MCP 的实现方式。

4. 特点总结#

功能	描述	MCP 实现可能性
Tool	封装外部能力	✅ 可以多工具注册
Agent	LLM + 工具决策者	✅ 自动选择工具
SequentialChain	串联工具/LLM链	✅ 可以做多步骤 MCP
RouterChain	输入路由选择不同工具	✅ 可实现条件分支 MCP
StructuredToolAgent	输出解析 + 多工具	✅ 更稳定 MCP

✅ 小结#

LangChain 原生不叫 MCP，但其架构完全可以实现多工具、多步骤、多分支的 Multi-Tool Pipeline。
MCP 在 LangChain 中可通过 Agent + Tools + Chain 实现：
- 多工具注册 → Agent 决策调用 → 链式或分支流程执行 → 输出聚合。

LangChain Agent 入门：LLM + 工具集 + 推理策略

Sat, 05 Sep 2026 00:00:00 GMT

在 LangChain 中，Agent（智能代理） 是一个可以根据用户输入动态选择工具并执行操作的模型。
它不是单纯调用 LLM，而是能做决策：

识别用户意图
选择合适的工具（Tool）
执行工具操作
根据工具输出更新推理
最终输出答案

核心思想：Agent = LLM + 工具集 + 推理策略

二、Agent 的组成部分#

LLM：语言模型
- 决策核心
- 支持 OpenAI、Claude、Llama 等
Tools（工具） ：Agent 可用的外部接口
- Web 搜索（SerpAPI、GoogleSearchAPI）
- 数据库查询（SQLDatabaseChain）
- 文件读取（TextLoader + VectorDB）
- 自定义工具（任何函数，只需符合 tool 接口）
Agent 类型 / 策略：LLM 如何调用工具
- Zero-shot agent：不依赖示例，直接用 prompt 决策
- ReAct agent：结合推理（Reasoning）+ 行动（Action）
- Conversational agent：适合多轮对话
- Plan-and-Act agent（新版）：先规划步骤再执行
Memory（可选） ：存储上下文，尤其是多轮对话中 Agent 的知识
- ConversationBufferMemory
- ConversationSummaryMemory
- VectorStoreMemory

三、基本使用流程#

假设我们想做一个查询天气的 Agent：

1
from langchain.agents import initialize_agent, Tool
2
from langchain.llms import OpenAI
3

4
# 1. 定义 LLM
5
llm = OpenAI(temperature=0)
6

7
# 2. 定义工具
8
def get_weather(city: str) -> str:
9
    return f"{city} 今天晴，25度"
10

11
weather_tool = Tool(
12
    name="Weather",
13
    func=get_weather,
14
    description="获取指定城市的天气"
15
)
16

17
# 3. 初始化 Agent
18
agent = initialize_agent(
19
    tools=[weather_tool],
20
    llm=llm,
21
    agent="zero-shot-react-description",  # Zero-shot ReAct agent
22
    verbose=True
23
)
24

25
# 4. 执行
26
agent.run("请告诉我北京今天的天气")

展开收起

核心要点：

agent="zero-shot-react-description" 表示使用 ReAct 风格策略
Tool 必须包含 name, func, description
Agent 会根据输入自动选择工具执行

四、注意事项#

1. 工具设计#

description 至关重要：LLM 通过描述选择工具
工具函数尽量保持幂等（相同输入输出一致）
对复杂工具可加安全检查，避免危险操作

2. Agent 类型选择#

Zero-shot：灵活，但易出错
ReAct：推荐，能处理复杂任务，多步推理
Plan-and-Act：适合长任务，先规划步骤再执行

3. 内存 & 多轮对话#

对话 Agent 必须配置 memory
注意 token 限制，避免长对话 context 超出模型上下文

4. Prompt 与输出控制#

可以自定义 agent_prompt 控制 LLM 决策
输出可能包含 Thought / Action / Action Input 等信息
对接前端时可能需要解析这些字段

5. 异常处理#

工具执行可能失败 → Agent 要能处理异常
可以通过 return_direct=True 或 callback 捕获中间步骤

6. 调试 & 日志#

verbose=True 可以看到 Agent 内部思考过程
适合训练或调试复杂链路

7. 性能 & Token 消耗#

多工具、多步骤 → token 消耗大
可以缓存工具结果，或使用短 prompt
对接向量数据库等可做检索增强，减少重复调用 LLM

8. 安全性#

避免让 Agent 直接执行系统命令或删除文件等危险操作
如果必须，可加入 sandbox 或权限控制

五、常见进阶用法#

多工具 Agent

1
tools = [weather_tool, web_search_tool, sql_tool]
2
agent = initialize_agent(tools, llm, agent="zero-shot-react-description")

带内存的对话 Agent

1
from langchain.memory import ConversationBufferMemory
2
memory = ConversationBufferMemory(memory_key="chat_history")
3
agent = initialize_agent(tools, llm, agent="conversational-react-description", memory=memory)

Plan-and-Act Agent

用于复杂任务，先生成步骤列表再逐步执行
适合自动化办公、数据分析、复杂决策任务

六、总结#

核心概念	说明
LLM	决策引擎
Tool	可执行操作接口
Agent 类型	决策策略（Zero-shot / ReAct / Conversational / Plan-and-Act）
Memory	对话或任务状态存储
Verbose	调试思考过程
Prompt	指导 LLM 选择工具和输出格式

✅ 最佳实践

工具描述清晰、函数幂等
ReAct 或 Plan-and-Act 优先
对话 Agent 配置 Memory
调试用 verbose
控制 token，注意安全

「人生 30000 天」产品方向探索：五轮否决之后剩下什么

Mon, 27 Jul 2026 00:00:00 GMT

原始想法： 做一个名为“人生30000天”的 App，核心功能是可视化展示“已活了多少天”和“还剩多少天”，并结合人生规划。

二、现有竞品分析#

2.1 竞品清单#

应用名称	核心功能	特点与定位
30000days	用 Emoji 记录心情、日记、待办，生成日历壁纸	轻量级日记和情绪追踪工具
余生时钟	记录生辰、年龄、人生进度，生日/纪念日提醒，桌面小组件	侧重记录重要之人的人生节点
生命倒计时	“生之时”记录已活天数，“死之钟”预测寿命并倒计时，有心愿单	死亡倒计时 + 心愿单，抖音曾火爆
人生沙漏	以“月”为单位的格子铺展人生，生命倒计时、里程碑、数据统计	视觉化表达直观，像“温柔的人生镜子”
遗愿宝 (BucketPal)	以“周”为单位的生命网格，将梦想按10个维度分类追踪	周数网格带来视觉冲击，结构化规划
Lifedots	点阵图可视化人生	极简视觉化
Dayflower	AI驱动极简日记，“一图一言”记录生活	自动整理成“生命之书”，构建“人生之树”
魔力空间 (Mooly)	AI个人成长助手，基于生命平衡轮八大维度追踪	AI生成日/周/月洞察复盘，数据可视化
人生总结 – 生命时间线	整个人生可视化时间追踪器	十年/年度视图网格，时间线事件气泡
拾光记忆	日记记录，热力图，人生时钟	一键导出PDF，情绪统计趋势

2.2 热度评估#

热度级别	代表产品	表现
现象级爆款	“死了么”App	登顶 App Store 付费榜首，估值千万，三天日下载量突破50万
社交平台爆火	“生命倒计时”	抖音上被大量做成锁屏壁纸，短视频病毒式传播
持续运营/小众	遗愿宝、人生沙漏、Dayflower	有固定用户群，能维持运营，但非全网刷屏级别

核心结论： 概念本身被验证过，爆款出圈靠的是“情绪钩子”+“社交货币”，而非功能复杂程度。

三、探索过的差异化方向（及被否决原因）#

3.1 第一阶段：功能层面的差异化#

方向	说明	被否决原因
“正计时”代替“倒计时”	展示“已认真活过的天数”，强调积累感	仍是同一框架下的变体，用户心智变化不大
关系视角	“我们还剩多少天一起过”，连接父母/伴侣	有价值，但仍是“倒计时”的情感变体
生命宽度	量化体验丰富度，做“人生体验清单”	本质还是“规划”工具，门槛高

3.2 第二阶段：AI大模型整合方向#

方向	说明	被否决原因
AI人生复盘	AI分析日记/相册/位置，生成洞察报告	与大模型直接对话相比，无准确性优势
大模型上层应用	调用API，将建议放入时间容器持续追踪	用户自己问大模型更直接；连记账App都难存活

核心问题： 大模型记账类应用尚且面临用户新鲜感一过就流失的困境，人生规划类输入成本更高、反馈周期更长，更难存活。

3.3 第三阶段：零输入方向#

方向	说明	被否决原因
自动读取健康/相册/日历数据	用户无需输入，自动呈现人生数据画像	已有产品在做（如 Apple Health 聚合、相册回忆）
隐私即卖点	本地处理数据，不上传云端	隐私是功能属性，不足以成为独立卖点

3.4 第四阶段：纯软件售卖方向#

方向	说明	被否决原因
人生说明书（一次性买断）	读取本地数据，自动生成PDF报告，用户买断即用	竞品已存在（Dayflower、人生总结、拾光记忆等均支持报告导出）

3.5 第五阶段：AI回忆录/家族记忆方向#

方向	说明	被否决原因
AI回忆录生成	帮老人/个人生成回忆录	已有公司入局（慰康智能、清诺谛听、小鹿光年）
家族记忆传承	家族私密空间，AI整合故事和影像	使用门槛极高，需全家参与输入

四、多轮探索后的核心发现#

4.1 这个领域的本质困境#

概念被反复验证，也意味着被反复挖掘 —— “人生30000天”框架下的各种变体几乎都有人尝试过
输入门槛 vs 获得价值的鸿沟 —— 用户必须“先干活才能获得价值”，绝大多数人在这一步流失
大模型不是护城河 —— 用户可以直接向大模型提问，且回答质量可能更高
竞品已覆盖主流方向 —— 记录、规划、倒计时、报告生成、AI复盘……均有成熟产品

4.2 创业者面临的现实约束（来自用户明确表达）#

❌ 不做需要持续运营的 App
❌ 不接入大模型（避免 API 成本和依赖）
✅ 想做纯软件售卖（一次性买断）
✅ 想找到“互联网上完全没有”的方向

4.3 核心矛盾#

“蓝海方向”往往需要教育用户 → 教育用户需要资本和运营 “红海方向”竞争激烈 → 纯软件卖断难以突围

两者之间存在天然张力。

五、留给未来的可能思考方向#

如果在当前约束条件下暂时未找到合适方向，以下是一些可以继续关注/探索的视角：

垂直人群 —— 能否不为“所有人”做产品，而是聚焦某类极细分人群（如高考前100天倒计时、新人入职100天）？
实体化/礼品化 —— 能否将软件生成的报告做成实体书/礼盒，走礼品经济路线（如“给父母的礼物”）？
工具化/插件化 —— 能否不做一个独立 App，而是一个 Excel/Notion 模板、或手机小组件合集？
等待新平台/新硬件 —— 是否可以在 Vision Pro / 智能戒指 / 智能相框等新载体上寻找机会？

六、文档信息#

生成日期： 2026-07-27
对话轮次： 多轮探索与排除
当前状态： 已排除多个主流方向，未找到符合“蓝海 + 纯软件售卖”双重约束的明确切入点
建议后续动作： 可根据自身资源/能力，重新评估约束条件（如是否接受轻度运营、是否接受非独立 App 形态），或在垂直细分领域进行更深入的定性调研

“有时，排除掉所有可能性后，剩下的那个——哪怕再难——就是答案。”

Guoxin Wiki

Windows 11 上封锁 Claude Code 出网：防火墙 + DNS + hosts 三层实战

0. 目标与效果#

1. 原理：三层防线与 Windows 特有的坑#

2. 前置检查#

3. 第一步：Windows 防火墙出站阻断（A）#

3.1 提权脚本 setup.ps1（必须纯 ASCII）#

3.2 提权入口 run-elevated.ps1（必须纯 ASCII）#

3.3 提权失败排查（本次踩过的坑）#

4. 第二步：WSL2 内 nftables 移植（B）#

4.1 /etc/nftables.d/claude-guard.nft#

4.2 /usr/local/sbin/claude-guard.sh#

4.3 /etc/systemd/system/claude-guard.service#

4.4 部署（在 Windows 侧执行）#

5. 第三步：DNS 纠正 + hosts（E）#

6. 验证：替身法（全程零 Anthropic 流量）#

6.1 主机差异测试#

6.2 Docker Desktop 覆盖判定#

6.3 本次实测记录（2026-10-22）#

6.4 清理替身规则（必须做）#

7. 端到端不连通实测（2026-10-22 已执行通过）#

7.1 本次实测记录（2026-10-22）#

8. 维护#

8.1 Anthropic IP 段变化#

8.2 换机器 / 重装#

8.3 已知观察#

9. 回滚#

10. 文件清单#

11. 一句话总结#

React 学习 Day1：基础语法与整体框架（含 JS 关键基础）

1. React 是什么（宏观理解）#

2. React 核心思想：组件化（Component-Based）#

2.1 什么是组件#

2.2 函数组件 vs 类组件（只要知道差异）#

3. React 的三大核心机制#

3.1 虚拟 DOM（Virtual DOM）与 Diff#

3.2 Props 与 State#

3.3 Hooks（函数组件的“外挂能力”）#

4. React 项目启动与目录结构（以 Vite 为例）#

5. React 常见生态模块（知道用途即可）#

5.1 路由（React Router）#

5.2 全局状态管理（Redux / Zustand）#

5.3 UI 组件库 / 样式方案#

6. React 应用的运行与更新流程#

7. JavaScript 基础（React 必备子集）#

7.1 let / const / var#

7.2 常用数据类型#

7.3 函数与箭头函数#

7.4 条件与 JSX 条件渲染#

7.5 map（列表渲染核心）#

7.6 解构（Destructuring）#

7.7 展开运算符（…）与不可变更新#

7.8 模块化 import / export#

7.9 Promise 与 async/await#

8. day1 的重点 Q&A 再巩固#

8.1 Counter 例子为什么这样写#

8.2 map 的本质#

8.3 数组解构例子#

8.4 export 给谁用#

9. 学习路径（下一步怎么走）#

Poetry 命令大全及更新指南

1. 项目初始化与管理#

2. 虚拟环境管理#

3. 打包与发布#

4. 配置管理#

5. 锁定文件管理#

2026 年 9 月复盘：换赛道的第一个月

换赛道：从写功能到写架构#

三件印象深的事#

下个月#

Linux screen 命令详解

Linux ​screen​​ 命令详解#

常用 ​screen​​ 命令#

1. 基本操作#

2. 会话内操作（快捷键：​​Ctrl + A​​ 后接命令）#

3. 高级用法#

典型使用场景#

总结#

Tmux 详解：终端复用利器

Tmux 详解：终端复用利器#

3.1 提权脚本 `setup.ps1`（必须纯 ASCII）#

3.2 提权入口 `run-elevated.ps1`（必须纯 ASCII）#

4.1 `/etc/nftables.d/claude-guard.nft`#

4.2 `/usr/local/sbin/claude-guard.sh`#

4.3 `/etc/systemd/system/claude-guard.service`#

Linux `screen` 命令详解#

常用 `screen` 命令#

2. 会话内操作（快捷键：`Ctrl + A` 后接命令）#

快捷键（前缀键 `Ctrl+B` ）#

(3) 配置文件 `~/.tmux.conf`#

1. 字符串字面量 `&str`#

2. `String` 类型#

第二部分：可变性（`mut` 关键字）#

第四部分：`Box<T>` 智能指针#

第五部分：`Vec<T>` 泛型集合#

第六部分：枚举（`enum`）#

3. 使用 `use` 简化路径#

第八部分：操作符 `.` vs `::`#

2. `.` 点操作符#

3. `::` 双冒号操作符#

第九部分：解引用运算符 `*`#

4. 何时需要手动 `*`#