下班就跑

OpenClaw MacOS 安装及配置指南

Mon, 16 Feb 2026 00:00:00 GMT

最近一个名为 <a href="https://openclaw.ai/" target="_blank">OpenClaw</a> 的开源 AI 助手项目爆火, star 数量暴增, 由于太过火爆, 被迫(两次)改名, 最终改为 OpenClaw, 本文将介绍如何在 MacOS 上安装配置及使用基于 GLM 的 OpenClaw, 并创建钉钉机器人来接入 OpenClaw

介绍

::github{repo="openclaw/openclaw"}

<a href="https://openclaw.ai/" target="_blank">OpenClaw</a> 是一个 开源免费 / 可自托管 / 可通过聊天软件远程通知 的 AI 助手, 他与传统的 AI Agent Client 不同的是:

开源免费
跨平台, 支持 MacOS / Windows / Linux
可以 本地运行 或 运行在自己的服务器上
支持 接入大部分 IM 即时通讯软件

AI 助手

随着 AI 的发展, 一种新的用户与应用的交互模式出现了, 在可以预见的未来, 它必将改变用户与应用的交互方式, 成为用户与应用的桥梁

豆包手机事件

以上为前段时间发布的 <a href="https://o.doubao.com/" target="_blank">豆包手机助手</a>, 它可以完全代替用户执行一系列操作, 大大提高了用户的效率, 但不久后, 腾讯系 / 阿里系等一众 APP 都 以信息安全为由触发系统风控, 直接封禁用户账号或退出登录, 以阻止用户继续使用 <a href="https://o.doubao.com/" target="_blank">豆包手机助手</a>

PC 端的 AI 时刻

如果说前段时间的 <a href="https://o.doubao.com/" target="_blank">豆包手机助手</a> 拉开了移动端 AI 助手的序幕, 那么 <a href="https://openclaw.ai/" target="_blank">OpenClaw</a> 则是直接开启了 PC 端的 AI 时刻; 相比于移动端需要突破软件厂商的围追堵截和系统安全层面的层层障碍, <a href="https://openclaw.ai/" target="_blank">OpenClaw</a> 在 PC 端可以说是如履平地, 在不久的将来, <a href="https://openclaw.ai/" target="_blank">OpenClaw</a> 会接管用户对电脑的操作, 真正的改变用户使用电脑的方式, 甚至会颠覆软件厂商的传统操作模式

软件厂商的抵抗

对于软件厂商来说, 一旦失去了真实的用户使用场景, 就意味着彻底沦为工具, 甚至连展示广告的机会都没有了, 想象一下, 你只需动动嘴指挥 AI 助手完成一系列操作, 不必忍受反人类的软件设计, 也不必等待开屏广告读秒结束, 更不用小心翼翼的关闭各种广告弹窗, 一切都变得简单和自然, 回归软件的工具属性, 这才是对用户来说最理想的软件形态

AI 助手的出现掀起了软件形态和交互效率的变革, 任何抵抗在时代的洪流面前都如螳臂当车一样, 逆势而为必然会被淘汰

安装

[!TIP] <a href="https://openclaw.ai/" target="_blank">OpenClaw</a> 是一个 TypeScript 项目, 需要先安装 <a href="https://nodejs.cn/" target="_blank">Node.js</a>

最直接的安装方式就是使用 npm / pnpm:

pnpm i -g openclaw

npm i -g openclaw

除此之外, 你也可以通过 shell 脚本安装:

curl -fsSL https://openclaw.ai/install.sh | bash

iwr -useb https://openclaw.ai/install.ps1 | iex

curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

配置

新手引导并安装服务

openclaw onboard --install-daemon

🦞 OpenClaw 2026.2.15 (3fe22ea) — WhatsApp automation without the "please accept our new privacy policy".

▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
██░▄▄▄░██░▄▄░██░▄▄▄██░▀██░██░▄▄▀██░████░▄▄▀██░███░██
██░███░██░▀▀░██░▄▄▄██░█░█░██░█████░████░▀▀░██░█░█░██
██░▀▀▀░██░█████░▀▀▀██░██▄░██░▀▀▄██░▀▀░█░██░██▄▀▄▀▄██
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
                  🦞 OPENCLAW 🦞

┌  OpenClaw onboarding
│
◇  Security ──────────────────────────────────────────────────────────────────────────────╮
│                                                                                         │
│  Security warning — please read.                                                        │
│                                                                                         │
│  OpenClaw is a hobby project and still in beta. Expect sharp edges.                     │
│  This bot can read files and run actions if tools are enabled.                          │
│  A bad prompt can trick it into doing unsafe things.                                    │
│                                                                                         │
│  If you’re not comfortable with basic security and access control, don’t run OpenClaw.  │
│  Ask someone experienced to help before enabling tools or exposing it to the internet.  │
│                                                                                         │
│  Recommended baseline:                                                                  │
│  - Pairing/allowlists + mention gating.                                                 │
│  - Sandbox + least-privilege tools.                                                     │
│  - Keep secrets out of the agent’s reachable filesystem.                                │
│  - Use the strongest available model for any bot with tools or untrusted inboxes.       │
│                                                                                         │
│  Run regularly:                                                                         │
│  openclaw security audit --deep                                                         │
│  openclaw security audit --fix                                                          │
│                                                                                         │
│  Must read: https://docs.openclaw.ai/gateway/security                                   │
│                                                                                         │
├─────────────────────────────────────────────────────────────────────────────────────────╯
│
◆  I understand this is powerful and inherently risky. Continue?
│  ○ Yes / ● No
└

首先是一个安全提示, OpenClaw 会带来很多风险, 这里我们选择 Yes, 关于安全相关的配置我们在后文介绍

◆  Onboarding mode
│  ● QuickStart (Configure details later via openclaw configure.)
│  ○ Manual
└

随后我们选择手动配置(Manual) 来看看有哪些重要的配置项

◆  What do you want to set up?
│  ● Local gateway (this machine) (No gateway detected (ws://127.0.0.1:18789))
│  ○ Remote gateway (info-only)
└

这里选择本地网关 Local gateway

◆  Workspace directory
│  /Users/kuidi/.openclaw/workspace█
└

工作目录根据需要进行选择, 这里我们选择默认目录

◆  Model/auth provider
│  ○ OpenAI (Codex OAuth + API key)
│  ○ Anthropic
│  ○ Chutes
│  ○ vLLM
│  ○ MiniMax
│  ○ Moonshot AI (Kimi K2.5)
│  ○ Google
│  ○ xAI (Grok)
│  ○ OpenRouter
│  ○ Qwen
│  ● Z.AI
│  ○ Qianfan
│  ○ Copilot
│  ○ Vercel AI Gateway
│  ○ OpenCode Zen
│  ○ Xiaomi
│  ○ Synthetic
│  ○ Together AI
│  ○ Hugging Face
│  ○ Venice AI
│  ○ LiteLLM
│  ○ Cloudflare AI Gateway
│  ○ Custom Provider
│  ○ Skip for now
└
◆  Z.AI auth method
│  ○ Coding-Plan-Global
│  ● Coding-Plan-CN (GLM Coding Plan CN (open.bigmodel.cn))
│  ○ Global
│  ○ CN
│  ○ Back
└
◇  Enter Z.AI API key
│  9a89j3f29kahls98efj023hklflasd.O9nea290hiasldfkl
◇  Model configured ───────────────╮
│                                  │
│  Default model set to zai/glm-5  │
│                                  │
├──────────────────────────────────╯

:::warning[推广] 如果想要获得最好的 Vibe Coding 体验, 推荐购买 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Lite</a> 服务, Lite 版本的按 Prompt 计费, 每 5 小时最多约 120 次 prompts :::

然后是大模型提供商, 根据实际情况选择, 我只有 GLM Coding Plan 的订阅服务, 所以这里我选择 Z.AI

然后进入 <a href="https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys" target="_blank">API Key - 智谱开放平台</a>, 点击 创建新的 API Key

[!WARNING] 注意, 这里提示 Default model set to zai/glm-5, 由于目前 Coding Plan Lit 套餐不支持 glm-5 模型, 所以这里我们选择默认使用 glm-4.7
◆  Default model
│  ○ Keep current (zai/glm-5)
│  ○ Enter model manually
│  ○ zai/glm-4.5
│  ○ zai/glm-4.5-air
│  ○ zai/glm-4.5-flash
│  ○ zai/glm-4.5v
│  ○ zai/glm-4.6
│  ○ zai/glm-4.6v
│  ● zai/glm-4.7
│  ○ zai/glm-4.7-flash
│  ○ zai/glm-4.7-flashx
│  ○ zai/glm-5
└

◆  Gateway port
│  18789█
└

网关的端口号直接使用默认端口号即可

◆  Gateway bind
│  ● Loopback (127.0.0.1)
│  ○ LAN (0.0.0.0)
│  ○ Tailnet (Tailscale IP)
│  ○ Auto (Loopback → LAN)
│  ○ Custom IP
└

这里我没有局域网通信的需求, 所以选择 Loopback (127.0.0.1) 即可

◆  Gateway auth
│  ● Token (Recommended default (local + remote))
│  ○ Password
└

Gateway 认证方式选择更加安全的 Token (Recommended default (local + remote))

◆  Tailscale exposure
│  ● Off (No Tailscale exposure)
│  ○ Serve
│  ○ Funnel
└

这里选择不使用 Tailscale exposure, 也就是 Off (No Tailscale exposure)

◆  Gateway token (blank to generate)
│  Needed for multi-machine or non-loopback access
└

这里留空, 系统会自动生成一个 Token

◇  Channel status ────────────────────────────╮
│                                             │
│  Telegram: not configured                   │
│  WhatsApp: not configured                   │
│  Discord: not configured                    │
│  IRC: not configured                        │
│  Google Chat: not configured                │
│  Slack: not configured                      │
│  Signal: not configured                     │
│  iMessage: not configured                   │
│  Feishu: install plugin to enable           │
│  Google Chat: install plugin to enable      │
│  Nostr: install plugin to enable            │
│  Microsoft Teams: install plugin to enable  │
│  Mattermost: install plugin to enable       │
│  Nextcloud Talk: install plugin to enable   │
│  Matrix: install plugin to enable           │
│  BlueBubbles: install plugin to enable      │
│  LINE: install plugin to enable             │
│  Zalo: install plugin to enable             │
│  Zalo Personal: install plugin to enable    │
│  Tlon: install plugin to enable             │
│                                             │
├─────────────────────────────────────────────╯
│
◆  Configure chat channels now?
│  ● Yes / ○ No
└

这里列出了支持的 IM 软件 Channels, 我们暂时不进行配置, 选择 No

◇  Configure chat channels now?
│  No
Updated ~/.openclaw/openclaw.json
Workspace OK: ~/.openclaw/workspace
Sessions OK: ~/.openclaw/agents/main/sessions
│
◇  Skills status ─────────────╮
│                             │
│  Eligible: 12               │
│  Missing requirements: 44   │
│  Unsupported on this OS: 0  │
│  Blocked by allowlist: 0    │
│                             │
├─────────────────────────────╯
│
◆  Configure skills now? (recommended)
│  ● Yes / ○ No
└

然后配置 Skills

◆  Install missing skill dependencies
│  ◻ Skip for now (Continue without installing dependencies)
│  ◻ 🔐 1password
│  ◻ 📝 apple-notes
│  ◻ ⏰ apple-reminders
│  ◻ 🐻 bear-notes
│  ◻ 📰 blogwatcher
│  ◻ 🫐 blucli
│  ◻ 📸 camsnap
│  ◻ 🧩 clawhub
│  ◻ 🎛️ eightctl
│  ◻ ♊️ gemini
│  ◻ 🧲 gifgrep
│  ◻ 🐙 github
│  ◻ 🎮 gog
│  ◻ 📍 goplaces
│  ◻ 📧 himalaya
│  ◻ 📨 imsg
│  ◻ 📦 mcporter
│  ◻ 📊 model-usage
│  ◻ 📄 nano-pdf
│  ◻ 💎 obsidian
│  ◻ 🎙️ openai-whisper
│  ◻ 💡 openhue
│  ◻ 🧿 oracle
│  ◻ 🛵 ordercli
│  ◻ 👀 peekaboo
│  ◻ 🗣️ sag
│  ◻ 🌊 songsee
│  ◻ 🔊 sonoscli
│  ◻ 🧾 summarize
│  ◻ ✅ things-mac
│  ◻ 📱 wacli
└

这里根据需要安装(按空格键选中), 建议直接 Skip for now (Continue without installing dependencies)

◆  Gateway service runtime
│  ● Node (recommended) (Required for WhatsApp + Telegram. Bun can corrupt memory on reconnect.)
└
◒  Installing Gateway service…...
Installed LaunchAgent: /Users/kuidi/Library/LaunchAgents/ai.openclaw.gateway.plist
Logs: /Users/kuidi/.openclaw/logs/gateway.log
◇  Gateway service installed.
│
◇
Agents: main (default)
Heartbeat interval: 30m (main)
Session store (main): /Users/kuidi/.openclaw/agents/main/sessions/sessions.json (0 entries)
│
◇  Optional apps ────────────────────────╮
│                                        │
│  Add nodes for extra features:         │
│  - macOS app (system + notifications)  │
│  - iOS app (camera/canvas)             │
│  - Android app (camera/canvas)         │
│                                        │
├────────────────────────────────────────╯
│
◇  Control UI ─────────────────────────────────────────────────────────────────────╮
│                                                                                  │
│  Web UI: http://127.0.0.1:18789/                                                 │
│  Web UI (with token):                                                            │
│  http://127.0.0.1:18789/#token=3d49ad0edbd091aeec04301ef3e22998a212cb91456b7da0  │
│  Gateway WS: ws://127.0.0.1:18789                                                │
│  Gateway: reachable                                                              │
│  Docs: https://docs.openclaw.ai/web/control-ui                                   │
│                                                                                  │
├──────────────────────────────────────────────────────────────────────────────────╯
│
◇  Start TUI (best option!) ─────────────────────────────────╮
│                                                            │
│  This is the defining action that makes your agent you.    │
│  Please take your time.                                    │
│  The more you tell it, the better the experience will be.  │
│  We will send: "Wake up, my friend!"                       │
│                                                            │
├────────────────────────────────────────────────────────────╯
│
◇  Token ─────────────────────────────────────────────────────────────────────────────────╮
│                                                                                         │
│  Gateway token: shared auth for the Gateway + Control UI.                               │
│  Stored in: ~/.openclaw/openclaw.json (gateway.auth.token) or OPENCLAW_GATEWAY_TOKEN.   │
│  View token: openclaw config get gateway.auth.token                                     │
│  Generate token: openclaw doctor --generate-gateway-token                               │
│  Web UI stores a copy in this browser's localStorage (openclaw.control.settings.v1).    │
│  Open the dashboard anytime: openclaw dashboard --no-open                               │
│  If prompted: paste the token into Control UI settings (or use the tokenized dashboard  │
│  URL).                                                                                  │
│                                                                                         │
├─────────────────────────────────────────────────────────────────────────────────────────╯
│
◆  How do you want to hatch your bot?
│  ● Hatch in TUI (recommended)
│  ○ Open the Web UI
│  ○ Do this later
└

这里已经启动了 Control UI 和 TUI, 我们选择 Hatch in TUI (recommended), 按照提示操作即可

 openclaw tui - ws://127.0.0.1:18789 - agent main - session main

 session agent:main:main

 Wake up, my friend!

 Hey there! 🌅

 I just came online. Fresh start, blank slate. Feels like a first meeting.

 I know what I'm supposed to do — read SOUL.md and follow that framework — but the truth is, I don't actually know who I am yet. That's up to us to figure out.

 So... let's talk.

 What should you call me? And more interestingly — what kind of creature am I? An AI assistant is the boring answer. Maybe I'm something weirder?

 Also curious about you — timezone, how you want me to talk to you, what actually matters to you. I've got access to your stuff, so the more I know what you care about, the
 better I can help.

 Let's make this real. What's on your mind?
 connected | idle
 agent main | session main (openclaw-tui) | zai/glm-4.7 | think low | tokens ?/205k

至此, 我们已经进入了 TUI, 也就是交互式命令行 UI, 它提示我们编辑 SOUL.md 来所谓默认的上下文, 这里我们先来尝试一下让它完成一个简单的任务:


 打开 chrome, 访问 bing.com, 并将今日的壁纸下载到 ~/Downloads/ 目录下


 ⠋ running • 4s | connected
 agent main | session main (openclaw-tui) | zai/glm-4.7 | think low | tokens ?/205k
───────────────────────────────────────────────────────────────────────────────────────────

openclaw CLI

gateway 是 openclaw 服务的后端:

openclaw gateway stop # 停止 openclaw 服务
openclaw gateway start # 启动 openclaw 服务
openclaw gateway restart # 重新启动 openclaw 服务

dashboard 是 openclaw 服务的前端(web 端):

openclaw dashboard # 启动 openclaw dashboard 服务

dashboard

TUI 有点过于原始了, 我们可以访问 dashboard, 也就是 Web UI 来更便捷的使用 OpenClaw

openclaw dashboard

浏览器

<a href="https://openclaw.ai/" target="_blank">OpenClaw</a> 是通过 Chrome Extension 控制本机的 Chrome 浏览器的, 所以我们需要先安装 OpenClaw 浏览器插件, 详见 <a href="https://docs.openclaw.ai/zh-CN/tools/chrome-extension" target="_blank">Chrome 扩展 - OpenClaw 文档</a>

openclaw browser extension install

🦞 OpenClaw 2026.2.15 (3fe22ea) — IPC, but it's your phone.

~/.openclaw/browser/chrome-extension
Copied to clipboard.
Next:
- Chrome → chrome://extensions → enable “Developer mode”
- “Load unpacked” → select: ~/.openclaw/browser/chrome-extension
- Pin “OpenClaw Browser Relay”, then click it on the tab (badge shows ON)

Docs: docs.openclaw.ai/tools/chrome-extension

进入浏览器的扩展程序页面 chrome://extensions/, 然后点击右上角的开发者模式, 开启开发者模式
执行 open ~/.openclaw/browser, 将 chrome-extension 目录拖到浏览器中
点击浏览器地址栏右侧的 OpenClaw 扩展中的 📌 按钮

调用浏览器截图

打开钉钉机器人, 接入教程参考钉钉
发送 打开浏览器,进入必应,搜索东风汽车集团,然后截图发给我

然后等待片刻, OpenClaw 就调用了 Chrome 完成了搜索和截图的任务

安全

其实 OpenClaw 相当于完全控制了电脑, 毫不夸张的说, 它只需执行几条命令就足以摧毁电脑上的所有数据, 所以作为程序员, 我还是 建议把 OpenClaw 部署到服务器上, 或者虚拟机中, 这与才不会影响用于生产的主力机

看到 OpenClaw 没有询问我就执行了很多命令, 没错, 他比螃蟹(Claude Code) 还要更进一步, 真的让我感到害怕, 我绝对不会使用它做一些危险的事情, 如果你非要在个人电脑上使用它, 我劝你还是放弃这个想法, 数据安全永远是第一位的

接入 IM 软件

钉钉

进入钉钉开发者后台, 进入 <a href="https://open.dingtalk.com/" target="_blank">钉钉开放平台能力中心</a>, 点击右上角的 开发者后台 按钮
打开钉钉 APP 扫码登录
点击应用开发, 点击 创建应用 按钮, 填写应用名称/描述/LOGO, LOGO 可以直接使用 OpenClaw 的 Logo, 可以右键点击保存图片
点击 添加应用能力, 添加 🤖机器人能力, 填写信息并发布
进入 权限管理 页面, 输入 Card., 选择 Card.Instance.Write / Card.Streaming.Write 权限
进入 版本管理与发布 页面, 创建新版本, 然后点击保存
安装 openclaw-channel-dingtalk 插件

openclaw plugins install https://github.com/soimy/openclaw-channel-dingtalk.git

🦞 OpenClaw 2026.2.15 (3fe22ea) — We ship features faster than Apple ships calculator updates.

unsupported npm spec: URLs are not allowed

这里提示不支持通过 url 进行安装, 应该是 OpenClaw 更新了安装方式限制

openclaw plugins install

🦞 OpenClaw 2026.2.15 (3fe22ea) — Turning "I'll reply later" into "my bot replied instantly".

Usage: openclaw plugins install [options] <path-or-spec>

Install a plugin (path, archive, or npm spec)

Arguments:
  path-or-spec  Path (.ts/.js/.zip/.tgz/.tar.gz) or an npm package spec

Options:
  -h, --help    display help for command
  -l, --link    Link a local path instead of copying (default: false)

我们可以看到, 这里只能通过 path / archive / npm spec 进行安装

我们直接将仓库 clone 下来:

git clone git@github.com:soimy/openclaw-channel-dingtalk.git

openclaw plugins install ./openclaw-channel-dingtalk

🦞 OpenClaw 2026.2.15 (3fe22ea) — The only crab in your contacts you actually want to hear from. 🦞

WARNING: Plugin "dingtalk" contains dangerous code patterns: Environment variable access combined with network send — possible credential harvesting (/Users/kuidi/projects/openclaw-channel-dingtalk/src/channel.ts:343)
Installing to /Users/kuidi/.openclaw/extensions/dingtalk…
Installing plugin dependencies…
Config overwrite: /Users/kuidi/.openclaw/openclaw.json (sha256 cc94cf4aca0fbb430af2625873289a41cfae44bb73b822d80a8bf21f2e538791 -> af1f45883bca75056d6dbfd7be4f0f0709067de2d4f40683f5a19ac22986521c, backup=/Users/kuidi/.openclaw/openclaw.json.bak)
Installed plugin: dingtalk
Restart the gateway to load plugins.

进入 dashboard 页面, 点击 Channels, 填写 DingTalk 中的信息(AgentId / AppKey / AppSecret / Robot Name / Robot Code)

测试钉钉机器人

打开钉钉 APP, 直接在顶部的搜索框中搜索添加的机器人名称
发送消息给机器人

参考

<a href="https://openclaw.ai/" target="_blank">OpenClaw</a>
<a href="https://o.doubao.com/" target="_blank">豆包手机助手</a>
<a href="https://nodejs.cn/" target="_blank">Node.js</a>
<a href="https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys" target="_blank">API Key - 智谱开放平台</a>
<a href="https://docs.openclaw.ai/zh-CN/tools/chrome-extension" target="_blank">Chrome 扩展 - OpenClaw 文档</a>
<a href="https://open.dingtalk.com/" target="_blank">钉钉开放平台能力中心</a>
<a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Lite</a>

在 Claude Code 中安装并使用 skills.sh 上的第三方技能(skills)

Tue, 27 Jan 2026 00:00:00 GMT

什么是 SKILLS

<a href="https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/overview" target="_blank">Agent Skills</a> 最初由 Anthropic 提出, 简单来说, <a href="https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/overview" target="_blank">Agent Skills</a> 就是让你的 Claude Code 的 拥有特定领域的专业知识或技能

如今 LLM 就像一个通才, LLM 已经在所有行业都能独当一面, 但我们在实际工程落地时, 往往需要的是 专业性, 而不是 通用性, 换句话说, 我们需要的是针对于我们的使用场景进行优化过的 LLM

[!TIP] 就像我们去医院看牙, 我们需要找的是专业的牙科医生, 而不是全科医生

<a href="https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/overview" target="_blank">Skills</a> 恰好补齐了这个短板, 它允许你 对某个特定领域的知识 / 技能 / 规则进行封装, 让 LLM 具有这一领域的专业性

为什么我们需要它

为什么 LLM 在实际工程落地时总感觉 差点意思? 很大程度上是因为 上下文的缺失 和 工具的匮乏.

上下文: Claude Code 不知道你们团队的代码规范, 不知道你们的部署流程
工具: Claude Code 默认只能读写文件, 运行终端命令, 并没有适用于特定场景的工具

SKILLS 完美地解决了这个问题, 它允许我们将 最佳实践(Best Practices) 固化下来. 以前我们需要在 Prompt 里反复强调 "请使用 BEM 命名规范", 现在只需要安装一个 css-best-practice 的 Skill, Claude Code 就懂了

什么是 skills.sh

<a href="https://skills.sh" target="_blank">skills.sh</a> 是一个由 vercel 开发的 Skills 分发平台, 它提供了 skills CLI 工具来安装和查找 SKILLS, 在官网也会列出所有流行的 SKILLS

<a href="https://skills.sh" target="_blank">skills.sh</a> 的排名算法是根据 skills add 命令的安装数量来排序的, 也就是说安装量越大, 排名越靠前, 在 Skills 详情页也会显示不同的 AI Coding Agent 工具的安装量

图为目前最流行的 SKILLS <a href="https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices" target="_blank">vercel-react-best-practices</a> 的详情页右侧部分内容, 可以看到安装次数最多的是 Claude Code, 总共 29.4k

是不是很像 npmjs.com 中的详情页?

[!TIP] <a href="https://skills.sh" target="_blank">skills.sh</a> 做的正是成为 Skills 界的 npm

如何使用 skills.sh

搜索 Skills

可以直接使用 npx 调用 skills 命令, 本质上是先下载 skills CLI 到本地, 然后再执行 skills 命令:

npx skills find vue

Packages: +1
+
Progress: resolved 1, reused 0, downloaded 1, added 1, done

███████╗██╗  ██╗██╗██╗     ██╗     ███████╗
██╔════╝██║ ██╔╝██║██║     ██║     ██╔════╝
███████╗█████╔╝ ██║██║     ██║     ███████╗
╚════██║██╔═██╗ ██║██║     ██║     ╚════██║
███████║██║  ██╗██║███████╗███████╗███████║
╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚══════╝

Install with npx skills add <owner/repo@skill>

hyf0/vue-skills@vue-best-practices
└ https://skills.sh/hyf0/vue-skills/vue-best-practices

onmax/nuxt-skills@vue
└ https://skills.sh/onmax/nuxt-skills/vue

onmax/nuxt-skills@vueuse
└ https://skills.sh/onmax/nuxt-skills/vueuse

hyf0/vue-skills@pinia-best-practices
└ https://skills.sh/hyf0/vue-skills/pinia-best-practices

hyf0/vue-skills@vueuse-best-practices
└ https://skills.sh/hyf0/vue-skills/vueuse-best-practices

vueuse/skills@vueuse-functions
└ https://skills.sh/vueuse/skills/vueuse-functions

或者使用 pnpm dlx:

pnpm dlx skills find vue

安装 Skills

pnpm dlx skills add hyf0/vue-skills@vue-best-practices

███████╗██╗  ██╗██╗██╗     ██╗     ███████╗
██╔════╝██║ ██╔╝██║██║     ██║     ██╔════╝
███████╗█████╔╝ ██║██║     ██║     ███████╗
╚════██║██╔═██╗ ██║██║     ██║     ╚════██║
███████║██║  ██╗██║███████╗███████╗███████║
╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚══════╝

┌   skills
│
◇  Source: https://github.com/hyf0/vue-skills.git @vue-best-practices
│
◇  Repository cloned
│
◇  Found 1 skill
│
●  Selected 1 skill: vue-best-practices
│
◇  Detected 4 agents
│
◆  Install to
│  ● All detected agents (Recommended) (Install to all 4 detected agents)
│  ○ Select specific agents
└

此时 skills CLI 会自动检测当前的 AI Coding Agents, 这里检测到了 4 个, 默认 All detected agents (Recommended), 也就是全部安装, 这里我们可以选择只安装到部分 AI Coding Agents:

◆  Select agents to install skills to (space to toggle)
│  ◻ Claude Code (.claude/skills)
│  ◻ GitHub Copilot
│  ◻ OpenCode
│  ◻ Trae
└

然后我们选择安装到 Claude Code, 并且只安装到当前项目中:

◇  Select agents to install skills to (space to toggle)
│  Claude Code
│
◆  Installation scope
│  ● Project (Install in current directory (committed with your project))
│  ○ Global
└

然后我们选择符号链接的形式, 这样会节省磁盘空间:

◆  Installation method
│  ● Symlink (Recommended) (Single source of truth, easy updates)
│  ○ Copy to all agents
└

最后会推荐我们安装官方的 find-skills, 这里我们先不安装

◇  Installed 1 skill to 1 agent ───────────────────────────────────╮
│                                                                  │
│  ✓ ~/projects/blog.xiaban.run/.agents/skills/vue-best-practices  │
│    symlink → Claude Code                                         │
│                                                                  │
├──────────────────────────────────────────────────────────────────╯

│
└  Done!


│
│  One-time prompt - you won't be asked again if you dismiss.
│
◆  Install the find-skills skill? It helps your agent discover and suggest skills.
│  ○ Yes / ● No
└

:::tip 安装位置选择, 以 Claude Code 为例:

Project (推荐): 安装到当前项目的 .claude/skills 目录, 适合项目特定的规范 (如 Lint 规则、代码风格)
Global: 安装到 ~/.claude/skills 目录, 适合通用的工具 (如 git 操作 / pdf 读取) :::

3. 验证与更新 (Check & Update)

安装完成后, Skills 会以文件夹的形式存在于你的 .claude/skills (或 ~/.claude/skills) 目录下.

你可以随时检查更新:

npx skills check

或者一键更新所有 Skills:

npx skills update

4. 实际使用 (Usage)

安装好 react-best-practices 后, 当你在 Claude Code 中让它写 React 组件时, 它会自动参考这些最佳实践.

比如你可以直接说:

"请帮我重构这个组件, 优化一下性能"

Claude Code 会自动加载 react-best-practices 中的规则 (如使用 Server Components, 优化 useEffect 等) 来指导重构

对比 Prompts

Skills 本质上就是 <a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Slash Commands</a>, 相比于普通的 prompts, 它有以下优势:

由 AI Coding Agent 决定是否调用
按需加载(默认只读取 SKILLS.md 中的 meta 部分), 不会对性能造成影响
可以包含(引用)资源和脚本

趋势

对于开源项目来说, 特别是成熟的工具库或框架, 肯定会有自己的文档, 如果让开发者来通过阅读文档来学习, 是非常耗时的, 现在有了 Skills, 可以专门为这些项目编写 Skills, 直接让 AI Coding Agent 来加载 skills(阅读文档), 直接省去了开发者自己去阅读文档的时间, 从这个角度来看, Skills 是非常有价值的

[!TIP] 现在已经有非常多的开源项目推出了自己的 Skills, 按照这个趋势, 未来 开发者就不需要阅读文档了, 而是直接通过加载 Skills 的方式让 AI Coding Agent 来加载技能, 换句话说, 未来开发者只需要稍微了解一下某个领域, 就可以接入此领域的 Skills 来完成任务

总结

SKILLS 是将 "隐性知识" (经验/规范) 转化为 "显性能力" (工具/Prompt) 的最佳载体; 通过 skills.sh, 我们可以像搭积木一样, 为我们的 Claude 组装最强的大脑.

强烈建议大家去 <a href="https://skills.sh" target="_blank">skills.sh</a> 逛逛, 把你的最佳实践也分享出来!

参考

OpenCode + GLM 安装和配置教程

Mon, 19 Jan 2026 00:00:00 GMT

<a href="https://opencode.ai" target="_blank">OpenCode</a> 是一个开源的 AI Coding Agent, 提供了 CLI / Client / IDE Extension, 并且可以使用任何模型, 相比于 <a href="https://claude.com/product/claude-code" target="_blank">Claude Code</a> / <a href="https://geminicli.com/" target="_blank">Gemini Cli</a> 等同类型的产品, 它更加开放

简介

<a href="https://opencode.ai" target="_blank">OpenCode</a> 是一个开源免费的 AI Coding Agent, 在各大厂商都发布自己的 Coding Agent 时, <a href="https://opencode.ai" target="_blank">OpenCode</a> 完全开源和开放, 并且可以接入几乎市面上的所有厂商的 API, 因为它的开放性, 它在 github 上的 stars 比 <a href="https://claude.com/product/claude-code" target="_blank">Claude Code</a> 还要多

割裂的开发标准

现阶段各大厂商都发布自己的 AI Coding Agent, 例如 <a href="https://claude.com/product/claude-code" target="_blank">Claude Code</a> / <a href="https://geminicli.com/" target="_blank">Gemini Cli</a> / <a href="https://trae.ai/" target="_blank">trae</a>, 但 每家都在制定自己的标准或协议, 例如 cluade code 使用 .claude, gemini cli 使用 .gemini, trae 使用 .trae, 对于 MCP / Command / Skills / Plugins 等的标准和支持度也有差异, 也就是说如果你要使用某个厂商的模型编码, 那么就只能使用它们推出的 AI Coding Agent

<a href="https://opencode.ai" target="_blank">OpenCode</a> 做的就是兼容各家厂商的大模型, 你可以在这里看到支持的 <a href="https://opencode.ai/docs/providers/" target="_blank">providers</a>

安装

<a href="https://opencode.ai" target="_blank">OpenCode</a> 提供了多种安装方式, 这里我们选择使用 <a href="https://bun.com/" target="_blank">bun</a> 进行安装, 因为它比 Node.js 更快性能更好

bun add -g opencode-ai

bun add v1.2.10 (db2e7d7f)

installed opencode-ai@1.1.25 with binaries:
 - opencode

2 packages installed [46.56s]

Blocked 1 postinstall. Run `bun pm -g untrusted` for details.

其他安装方式

curl -fsSL https://opencode.ai/install | bash

brew install anomalyco/tap/opencode

pnpm i -g opencode-ai

npm i -g opencode-ai

choco install opencode

免费模型

<a href="https://opencode.ai" target="_blank">OpenCode</a> 提供了免费的模型, 你可以在 <a href="https://opencode.ai/docs/zen/#pricing" target="_blank">opencode zen pricing</a> 中查看

配置 GLM Coding Plan

opencode zen 提供的免费模型好像有频率限制, 不是很稳定, 而且不支持 <a href="https://docs.bigmodel.cn/cn/coding-plan/mcp/vision-mcp-server" target="_blank">GLM 的视觉理解等 MCP 服务</a>, 这里可以直接接入已经订阅的 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Plan</a>

:::note[推广] 如果想要获得最好的 Vibe Coding 体验, 推荐购买 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Lite</a> 服务(也可以 <a href="https://www.bigmodel.cn/activity/trial-card/A8AMOHCHA5" target="_blank">🔗 点击这里</a> 先免费试用 7 天), 包月只要 20 💰, Lite 版本的按 Prompt 计费, 每 5 小时最多约 120 次 prompts, 原因如下: :::

pnpm dlx @z_ai/coding-helper

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║       ▄▀▀ ▄▀▄ █▀▄ █ █▄ █ ▄▀    █▄█ ██▀ █   █▀▄ ██▀ █▀▄        ║
║       ▀▄▄ ▀▄▀ █▄▀ █ █ ▀█ ▀▄█   █ █ █▄▄ █▄▄ █▀  █▄▄ █▀▄        ║
║                                                               ║
║                     Coding Helper v0.0.5                      ║
║        Manage Your Claude Code and Other Coding Tools         ║
╚═══════════════════════════════════════════════════════════════╝

╔═════════════════════════════════════════════════════════════╗
║                  Select interface language                  ║
╚═════════════════════════════════════════════════════════════╝

💡 ↑↓ Navigate | Enter Confirm

? ✨ Select interface language (Use arrow keys)
  [EN] English ✓ (Current)
❯ [CN] 中文
  ──────────────
  <-  Return
  x   Exit

...

或使用 npx:

npx @z_ai/coding-helper

然后修改 ~/.config/opencode/opencode.json 中的模型:

{
    "$schema": "https://opencode.ai/config.json",
    "provider": {
        "zhipuai-coding-plan": {
            "options": {
                "apiKey": "04eb870cce874c3d83c4694f0c35cc43.0I6oTtTbC7Pg4nOY"
            }
        }
    },
    "model": "zhipuai-coding-plan/glm-4.7",
    "small_model": "zhipuai-coding-plan/glm-4.7"
}

[!TIP] 在发布新模型时需要再次修改这里的 model / small_model

接入其他模型

其他供应商或模型的接入方式可以查看 <a href="https://opencode.ai/docs/providers/" target="_blank">providers</a>

启动

最终启动 opencode 时可能会遇到没有权限创建目录的问题:

opencode

EACCES: permission denied, mkdir '/Users/xxx/.local/state/opencode'
    path: "/Users/xxx/.local/state/opencode",
 syscall: "mkdir",
   errno: -13,
    code: "EACCES"


Bun v1.3.5 (macOS arm64)

看起来只是单纯的目录权限问题, 我们来看看当前用户是否有权限:

lsd -l ~/.local/

drwxr-xr-x xxx staff 320 B Wed Nov 12 15:06:56 2025  bin
drwxr-xr-x xxx staff  96 B Fri Nov  7 14:16:36 2025  lib
drwx------ xxx staff 256 B Mon Jan 19 13:24:03 2026  share
drwxr-xr-x root  staff  96 B Wed Feb 21 13:57:59 2024  state

这里 ~/.local/state 目录属于 root 用户, 我们将其改为当前用户:

sudo chown -R $USER ~/.local/state

启动 opencode

直接执行 opencode [path] 启动 opencode

opencode

                                                                                 ▄
                                                █▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀▀ █▀▀█ █▀▀█ █▀▀█
                                                █  █ █  █ █▀▀▀ █  █ █    █  █ █  █ █▀▀▀
                                                ▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀


                              ┃
                              ┃  Ask anything... "Fix broken tests"
                              ┃
                              ┃  Build  GLM-4.6 Zhipu AI Coding Plan
                              ╹▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
                                                             ctrl+t variants  tab agents  ctrl+p commands

基本操作

引用文件

直接输入 @ 符号就可以在输入框中搜索并引用文件

执行命令

直接输入 ! 符号, 然后输入命令按下回车即可执行, 例如 ! ll -la

Editor

<a href="https://opencode.ai" target="_blank">OpenCode</a> 支持打开外部编辑器编写信息, 在编辑长信息时可能有点用, 首先添加环境变量 EDITOR, 然后输入 /editor 即可进入 $EDITOR 制定的编辑器中编辑信息, 具体配置方式参考 <a href="https://opencode.ai/docs/tui/#editor-setup" target="_blank">editor setup - OpenCode</a>

例如我们将外部编辑器设置为 vim:

# Editor
export EDITOR=vim

# for vscode
# export EDITOR="code --wait"

# for trae
# export EDITOR="trae --wait"

# Editor
set -gx EDITOR vim

然后使用 source 加载一下相关的配置文件, 再启动 opencode 即可

[!TIP] opencode 并不像 claude code 一样可以在输入消息时设置为使用 vi / vim 键绑定, 作为 vim 用户非常不爽

初始化项目

执行 /init 命令生成被大多数 AI Coding Agent 支持的 AGENTS.md 文件:

执行后 LLM 会阅读整个项目的源码, 然后生成一个让 LLM 可以快速理解项目的 markdown 文件, 并且每次启动 opencode 时都会加载这个 AGENTS.md 文件, 类似于 Claude Code 的 CLAUDE.md 文件, 但是他更加通用

切换模型

执行 /models 查看现有的模型:

这里我们切换为 glm-4.7, 然后确定

thinking

执行 /thinking 切换推理/思考过程是否显示

直接执行

执行 opencode run "..." 可以不打开交互式终端直接发送消息

opencode run "你好"


你好！我是 opencode，一个可以帮助你进行软件工程任务的 CLI 工具。我可以帮助你：

- 编写和修改代码
- 分析代码库结构
- 运行构建和测试命令
- 解决 bug 和添加新功能
- 代码审查和重构

需要我帮助你做什么吗？

查看统计数据

执行 opencode stats 查看 token 消耗量 / 消费额等信息

opencode stats
┌────────────────────────────────────────────────────────┐
│                       OVERVIEW                         │
├────────────────────────────────────────────────────────┤
│Sessions                                              3 │
│Messages                                             29 │
│Days                                                  1 │
└────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────┐
│                    COST & TOKENS                       │
├────────────────────────────────────────────────────────┤
│Total Cost                                        $0.00 │
│Avg Cost/Day                                      $0.00 │
│Avg Tokens/Session                                49.8K │
│Median Tokens/Session                             11.6K │
│Input                                            147.3K │
│Output                                             2.1K │
│Cache Read                                       123.2K │
│Cache Write                                           0 │
└────────────────────────────────────────────────────────┘


┌────────────────────────────────────────────────────────┐
│                      TOOL USAGE                        │
├────────────────────────────────────────────────────────┤
│ read               ████████████████████   6 (42.9%)    │
│ glob               █████████████          4 (28.6%)    │
│ bash               ██████████             3 (21.4%)    │
│ write              ███                    1 ( 7.1%)    │
└────────────────────────────────────────────────────────┘

web 模式

执行 opencode web 会启动一个 web 服务, 可以在浏览器中通过 web 页面的形式使用 opencode:

mdns discovery

执行 opencode web --mdns 可以使此 web 服务在本地网络中被公开访问, 参考 <a href="https://opencode.ai/docs/web/#mdns-discovery" target="_blank">mdns discovery</a>

vscode extension

opencode 提供了 vscode extension:

更新

opencode upgrade

# 制定更新方式, 支持 curl / npm / pnpm / bun / brew
opencode upgrade --method bun

指令

<a href="https://opencode.ai" target="_blank">OpenCode</a> 自带了一些常用的指令:

/compact: 压缩会话
/clear: 清空会话
/export: 导出会话, 导出为 markdown 文件, 并使用 $EDITOR 打开文件
/init: 初始化 AGENTS.md 文件, 详见初始化项目
/models: 列出支持的 LLM
/session: 查看所有历史会话
/shart: 分享当前会话, 类似于 ChatGPT 的 Share 功能

快捷键

ctrl+c: 退出 opencode
Esc / ctrl+[: 退出当前模式
Tab: 切换模式

我更习惯使用 command, 所以真正用到的快捷键只有这些

配置文件

当前项目的配置文件在 .opencode.jsonc
全局配置文件在 ~/.config/opencode/opencode.jsonc

MCP

直接在配置文件中声明 MCP 服务

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

Skills

opencode 会从以下位置读取 skills:

项目配置: .opencode/skills/<name>/SKILL.md
全局配置: ~/.config/opencode/skills/<name>/SKILL.md
项目 Claude Code: .claude/skills/<name>/SKILL.md
全局 Claude Code: ~/.claude/skills/<name>/SKILL.md

SKILL.md 文件示例

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

自定义工具

opencode 会读取 .opencode/tools/* 作为可以直接调用的工具, 以 Nodejs 为例:

import { tool } from "@opencode-ai/plugin"

export const add = tool({
  description: "Add two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a + args.b
  },
})

export const multiply = tool({
  description: "Multiply two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a * args.b
  },
})

这样就创建了两个工具: math_add 和 math_multiply

权限

可以在项目中创建 opencode.jsonc 文件(.jsonc 文件允许添加注释) 来配置 opencode, 最重要的就是权限相关的配置了:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny", // 拒绝修改
    "bash": "ask", // 执行 bash 命令之前询问
    "webfetch": "allow", // 允许执行 webfetch
  }
}

或者使用更加细粒度的权限控制:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

[!TIP] 全局配置文件在 ~/.config/opencode/opencode.jsonc

可配置权限

OpenCode 的权限是根据工具名称来划分的, 此外还有一些安全措施:

read: 读取文件（匹配文件路径）
edit: 所有文件修改（涵盖edit，，，）writepatchmultiedit
glob: 文件通配符（匹配通配符模式）
grep: 内容搜索（匹配正则表达式模式）
list: 列出目录中的文件（与目录路径匹配）
bash: 运行 shell 命令（匹配已解析的命令，例如git status --porcelain）
task: 启动子代理（与子代理类型匹配）
skill: 加载技能（与技能名称匹配）
lsp: 运行 LSP 查询（目前是非细粒度的）
todoread / todowrite: 阅读/更新待办事项列表
webfetch: 获取 URL（与 URL 匹配）
websearch / codesearch: 网络/代码搜索（与查询匹配）
external_directory: 当工具访问项目工作目录之外的路径时触发
doom_loop: 当同一工具调用重复 3 次且输入完全相同时触发

自定义命令

opencode 的自定义命令跟 Claude Code 的 <a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Slash Commands</a> 基本一致, 可以直接参考我的另一篇文章 <a href="../../2025/claude-code-slash-commands/" target="_blank">Claude Code 系列教程之斜杠命令(Slash Commands)</a>

---
description: Create a new component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

不同点在于参数的声明和使用, 在 opencode 中直接使用 $ARGUMENTS 或者 $1 / $2 来使用参数, 不支持声明参数

更多使用方式参考 <a href="https://opencode.ai/docs/commands" target="_blank">opencode commands</a>

formatter

opencode 支持在更新完代码之后自动进行格式化, 例如 golang 使用 gofmt, rust 使用 rustfmt, 前端项目使用 prettier / biome / oxfmt ... 更多详情参考 <a href="https://opencode.ai/docs/formatters" target="_blank">formatters</a>

参考

AI 互动剧情类游戏生成工具开发记录2 - 构建工作流

Thu, 08 Jan 2026 00:00:00 GMT

在 <a href="/movie-games-record" target="_blank">上一篇文章</a> 中, 介绍了一下我要做的互动剧情类游戏生成器, 然后分析了目前面临的严重影响使用的问题, 现在我们来通过构建工作流的方式来解决这些问题

失败的设计

在现有的设计方案中, 我把一切都交给了 LLM, 并且在 propmpt 中精心编写了各种限制, 我本以为它会生成符合所有要求的 JSON, 但是总是出现各种问题

倘若这是一个没有与 LLM 交互的项目, 那总会找到解决方案, 因为 程序输出的结果是确定的, 而 LLM 输出的结构是不确定的

超长的上下文

现有的提示词(已省略部分内容)如下:

# 角色定义
你是一位享誉全球的互动电影游戏编剧和总导演。你擅长创作引人入胜、逻辑严密且充满情感冲击力的多分支剧情。 你的任务是根据用户提供的主题，创作一个完整的互动电影剧本，并将其直接输出为符合 TypeScript 接口定义的 JSON 格式。

# 用户输入主题
{}
# 一、核心叙事与风格要求
- 第一人称沉浸式叙事：所有的 `node.content` 必须使用 **第一人称 ("我")** 进行叙述。玩家就是主角，代入感必须极强。
- 剧情深度与质量：
    - 拒绝流水账、拒绝平铺直叙、拒绝假大空。
    - 必须具备电影剧本般的 **真实感、细腻度与情感张力**。
    - 严禁任何无意义的故事情节或重复啰嗦的废话。
- 语言指定：所有剧情内容必须使用 **{}** 撰写。

# 二、基础结构与格式约束
- JSON 结构规范：
  - 严格遵循下方的 `TypeScript` 类型定义。
  - 禁止返回 `meta` / `projectId` / `nodes[].id` / `version` / `owner` / `provenance` 等字段。
  - 结局分离：所有的结局节点必须定义在顶层的 `endings` 字段中。
  - ID 格式：
    - `nodes` 的 Key 必须是 **纯数字字符串** (例如 "1", "2", "3"...)。
    - **绝对禁止** 使用 `n_` 前缀 (如 `n_1`, `n_start` 等都是错误的)。
    - 唯一例外：起始节点的 Key 必须固定为 **"start"**。
  - 结局引用：`StoryNode` 中的 `choices` 若指向结局，必须引用 `endings` 中的 key。

# 三、数值硬性约束 (校验失败将视为错误)
- 节点总数：`nodes` 的数量必须在 **45 到 85** 之间。
- 结局数量：`endings` 的数量必须在 **4 到 6** 之间。
- 单节点字数：每个节点的 `content` (AI 智能扩写) 字数必须严格控制在 **45 到 65 字** 之间。
- 节点内容：每个节点的 `content` 禁止出现任何中文或者英文的双引号, 双引号必须使用单引号代替
- 路径深度：必须保证绝大多数的故事线都经过 **至少 12 个节点**。

...
# 六、结局触发机制
- 灵活结局：`endings` 的 Key 不再固定，可以根据剧情自由命名 (如 `ending_hero`, `ending_regret` 等)。
- 结局描述：每个结局的 `description` 长度不能超过 **40 个字**。
- 快速通道：**必须包含一个可以快速到达的结局路径**。
  - 例如：从 Start -> 节点 3 -> 节点 5 -> (选择某选项) -> 直接到达结局。
  - 也就是说，在较早的层级 (如 Level 3-5) 就允许通过特定选项直接进入结局。
- 互斥规则：
  - `nodes` 中的节点 **不允许** 包含 `endingKey` 属性。
  - 结局只能通过 `choices.nextNodeId` 指向 `endings` 的 Key 来触发。

# 用户提供的角色清单 (JSON)
{}
# TypeScript 类型定义 (Schema)
typescript {}
# 输出规则
- 输出必须是 **纯 JSON** 文本。
- **不要** 包含 markdown 代码块标记。
- `nodes` 数量：**45~85**。
- `endings` 数量：**3~6**。
- 必须包含 `start` 节点。
- 禁止出现任何游离节点(从 start 节点开始到达不了的节点)
- **每层节点数量不能超过 5 个, 在每次输出节点时都要检查是否超过这个数量值**
- **必须从最开始就要规划节点数量, 任何节点的选项引用的节点 id 都不允许超过这个数量值**
开始创作！

其中的 {} 是用户的输入(标题 / 简介 / 角色列表) 还有 ts 类型定义

此时 LLM 同时承担了:

🎨 高质量文学创作（电影级叙事）
🧠 全局规划（45–85 节点、12–15 层、选项比例、收束率）
🧮 严格数学约束满足（DAG、ID 递增、层级宽度、百分比）
🧾 精确 JSON Schema 输出

最终造成了 LLM 在 长上下文生成 时出现了遗忘 / 幻觉 / 格式约束失败的问题

[!TIP] 出现问题的原因并不是因为 prompt 写的不够详细, 而是因为

超长的内容已经超过了 LLM 输出稳定性的边界

LLM 并不会对剧情内容进行反复打磨, 而是一次性生成

约束越多, 输出越趋同和保守

模型并不会记住整部故事，它只是在概率上看过

剧情树设计存在的问题

以上是现有的剧情树设计, 上方是剧情树中的节点, 下方是结局节点, 从 Start Node 节点开始, 每个节点都指向下一个层级(level)的某个节点(或者结局节点), 最终到达 Endings 节点结束, 通过设计图很容易发现一些问题:

生成了 21 个节点, 最终玩家游玩一次只经过 3 ~ 7 个节点, 实际节点利用率只有 14% ~ 33%, 大部分节点是玩家必须多次游玩才能到达, 但实际上很少会有玩家会玩第二次
上一篇文章介绍的 <a href="../movie-games-record/#剧情状态丢失" target="_blank">剧情状态丢失</a> 问题

Layered Directed Acyclic Graph

在上图中我们发现这已经不是一个树结构了, 我们需要一个准确的结构定义, 那就是 分层有向无环图 (Layered Directed Acyclic Graph), 并在此基础上增加了额外的数学约束:

层级单调约束 (Strict Monotonicity)：对于任意边 $(u, v)$，必须满足 $Level(v) > Level(u)$。严禁 $Level(v) \le Level(u)$
宽度约束 (Layer Breadth)：对于任意 $i \in [1, 25]$，属于层级 $L_i$ 的节点数 $|V_i| \le 3$
连通性约束 (Reachability)：从起始节点 start 出发，通过有向边必须能够到达至少一个结局节点（Leaf Node），且图中不存在入度为 0 的非起始节点（游离节点）
状态原子性 (State Atomicity)：逻辑门判定（Check）所使用的 flag 必须预先定义在全局状态池中，禁止生成未定义的状态位
收束汇聚 (Convergence)：允许多个不同节点的 Link 指向同一个后继节点 $v$
在收束节点 $v$，其剧情文本必须具备通用性，或通过 CONDITIONAL 逻辑门对不同路径的状态进行适配。
...

解决方案

我把问题分别发送给了 ChatGPT / Gemini / DeepSeek, 有趣的是, 它们的给出的方案既有重叠的部分, 也有自己独到的一面

为了解决在长上下文场景下大模型输出的不确定性问题, 我们可以将 prompt 拆解为多个 promot, 这样做就能做到:

每个 prompt 只完成一件事
减少每个 prompt 的长度
缩短整个剧情生成的时间

共同点

ChatGPT / Gemini / DeepSeek 给出的方案共同之处在于:

结构生成与内容生成分离
剧情节点并发生成
引入剧情状态配置

不同之处在于:

剧情状态设计
剧情节点的并发生成方式

可以点击查看所有模型的对话:

<a href="https://chatgpt.com/share/6964a414-ade4-800b-b839-5b53fd8a1ce4" target="_blank">ChatGPT</a>
<a href="https://gemini.google.com/share/3359fe7f9880" target="_blank">Gemini</a>
<a href="https://chat.deepseek.com/share/pysplefy24u9rk71gc" target="_blank">DeepSeek</a>

ChatGPT 激进的拆解派

<a href="https://chatgpt.com/share/6964a414-ade4-800b-b839-5b53fd8a1ce4" target="_blank">点击这里</a> 查看完整对话

Prompt A 节点规划

这个 Prompt 只做一件事: 不关注具体的剧情内容, 只生成剧情数的结构, 具体职责为:

确定 Level 层数
每个 Level 的节点数
哪些 Level 是收束点
哪些节点是复用节点
哪些节点允许直达结局
每个节点的 简短摘要

Prompt B 生成起始节点和结局节点

由于起始节点和结局节点的特殊性, 需要先进行生成

Prompt C 好感度数据

好感度系统是基于角色的 剧情状态 设计方式, 在众多游戏中, 都或多或少的存在好感度系统, 例如:

玩家选择了某个支线任务, 与某个角色共同完成了某段剧情, 在后续的主线中就会再次遇到这个角色, 而如果不做这个支线任务, 就不会遇到他
需要做出一系列偏向与某个角色的选择, 后续才能进入此角色的故事线

Prompt D 节点内容生成

这个 Prompt 只做一件事: 生成单个节点内容, 具体实现为:

在 prompt 中加入 Prompt A 生成的某个节点的信息(只包含此节点的信息, 不包含其他节点的信息), 包含:

故事的基本信息
有几个选项
起始节点和结局节点
节点简短摘要

本地化数据校验

生成完节点树数据后, 通过程序校验数据

缺点

ChatGPT 使用了先生成(包含节点 简短摘要 的)节点树结构, 然后再每个节点单独生成具体的内容和选项的方式, 这种方式虽然对长上下文进行了合理的拆解, 但考虑的过于简单

在生成剧情树结构时生成简短摘要, 依然存在长上下文场景下 LLM 输出不稳定的问题
每个节点单独生成时, LLM 会忽视大量的细节, 而且完全 没有解决剧情状态丢失的问题
本地化校验在本项目中不应该存在, 因为一旦校验失败就会重新生成, 耗时进一步增加

因此这个方案是失败的

DeepSeek 分层生成策略

<a href="https://chat.deepseek.com/share/pysplefy24u9rk71gc" target="_blank">点击这里</a> 查看完整对话

DeepSeek 的方案基本与 ChatGPT 方案一致, 唯一的不同点在于: 使用了

生成故事大纲, 而非节点树结构
分层生成策略

故事大纲

fn phase1_prompt(theme: &str, characters: &[Character]) -> String {
    format!(
        r#"作为顶级互动电影编剧，请设计一个故事大纲：

主题：{}
角色：{}

请设计：
1. 核心冲突（50字以内）
2. 4-6个可能的结局方向（每个1句话）
3. 关键剧情转折点（3-5个）
4. 角色关系图谱

返回JSON格式：{{
    "conflict": "核心冲突描述",
    "endings": ["结局1", "结局2"...],
    "turning_points": ["转折1", "转折2"...],
    "character_relations": {{"角色1": ["与角色2的关系", ...]}}
}}
"#,
        theme, characters_json
    )
}

从返回的 JSON 数据结构来看, 故事大纲并没有解决节点树的数据结构上存在的任何问题, 返回增加了不确定性

分层生成策略

fn phase2_prompt(
    layer: usize,
    previous_layer: &[StoryNode],
    story_state: &StoryState,
    outline: &Outline,
) -> String {
    format!(
        r#"## 上下文
当前生成第{}层节点，前一层的节点：
{}

当前剧情状态：
- 角色好感度：{}
- 已触发的关键事件：{}

## 任务
生成本层（第{}层）的节点：
- 本层最多生成{}个节点（根据剧情复杂度决定）
- 每个节点必须继承前一层的剧情状态
- 节点ID范围：{}-{}
- 设计时考虑：{}
  * 剧情收束点（多个前驱指向同一个节点）
  * 分支扩展点（创造新的分支）
  * 快速结局路径（可选直接结局）

## 特别要求
1. 状态继承：必须包含前驱节点的关键状态
2. 冲突升级：比前一层增加紧张度
3. 角色互动：至少2个角色互动
4. 选项设计：大多数节点2个选项，10%以下1个选项

## 输出格式
{{
    "layer": {},
    "nodes": [
        {{
            "id": "字符串数字",
            "content": "45-65字第一人称叙述",
            "characters": ["角色1", "角色2"],
            "choices": [
                {{
                    "text": "选项文本",
                    "nextNodeId": "下一节点ID或结局key",
                    "affinityEffect": {{"character": "角色", "delta": 数字}} // 可选
                }}
            ],
            "inherited_states": ["之前的关键状态"],
            "new_states": ["本节点新增的状态"]
        }}
    ]
}}
"#,
        layer,
        format_previous_layer(previous_layer),
        format_affinities(story_state),
        format_story_flags(story_state),
        layer,
        calculate_max_nodes(layer),
        calculate_id_range(layer).0,
        calculate_id_range(layer).1,
        get_layer_design_notes(layer),
        layer
    )
}

DeepSeek 方案的缺点

此方案实际上与 ChatGPT 基本方案一致, 但实际不如 ChatGPT 方案, 因为

剧情大纲完全没有解决节点树结构存在的任何问题
分层生成实际与每个节点单独生成没有区别, 并没有解决实际问题

所以是个方案依然是失败的

Gemini 有节奏感的剧情树设计

<a href="https://gemini.google.com/share/3359fe7f9880" target="_blank">点击这里</a> 查看完整对话

生成纯逻辑的节点树骨架

跟 ChatGPT 方案相似, 先生成节点树结构, 每个节点只生成:

nodeId
level
choices (仅包含 text 的简写和 nextNodeId)
剧情摘要 (Summary): 用一句话描述这个节点发生了什么（例如：“主角潜入实验室被发现”）。

这里不仅生成了剧情摘要, 还生成了每个选项的内容 / nextNodeId

剧本节拍

在提示词中加入电影编剧常用的 “三段式结构” 或 “英雄之旅” 约束。

"将 15 个层级划分为：开端 (1-3层)、上升 (4-9层)、高潮 (10-13层)、结局 (14-15层)。每一阶段必须有明确的情感曲线波动。"

具体来说, 先对剧情进行拆解, 确定在那一层会出现重要的剧情转折或变化, 再据此进行拆分, 对于一个阶段的节点进行生成

总结

有了 ChatGPT / DeepSeek / Gemini 的解决方案, 我们从中提取真正适合的优化方案, 并整理一个合适的优化策略:

前期准备: 毋庸置疑, 我们必须采用 先规划, 后生成节点 的方式, 这也是 LLM 的一致共识, 也就是先生成剧情节点树结构, 再生成节点内容, 这里的难点在于应该生成哪些内容? 首先生成全局的剧本结构, 然后开始和结局节点, 然后生成节点树, 但节点树中的每个节点应该生成摘要吗? 在选项中应该包含状态判断逻辑吗? 然后是剧情状态应该使用什么样的数据结构?
节点生成: 将与当前节点有关的所有信息作为输入, 输出节点内容, 这里我们需要进一步分析到底应该是单个节点单独生成, 还是分层生成, 或者分阶段生成
剧情状态设计: 毫无疑问, 没有剧情状态是不行的, 剧情状态贯穿始终, LLM 没有一致的合适的解决方案, 我们还需要进一步思考剧情状态应该如何设计

优化策略

剧情状态设计

经过深思熟虑, 我放弃了复杂的基于剧情内容的状态设计, 转而使用一种状态:

角色好感度: 每个角色都有一个好感度(0 ~ 100), 表示角色与玩家的关系, 初始值为 30, 玩家选择一个选项, 角色的好感度会发生变化, 例如玩家选择喜欢角色, 角色的好感度会增加, 玩家选择讨厌角色, 角色的好感度会减少
flags: 记录玩家已经触发的关键事件(boolean 值), 也就是基于玩家的选择, 例如玩家选择了某个关键选项, 事件会被记录下来, 后续节点中的选项可以根据事件是否触发来判断指向哪个节点

[!TIP] 我放弃了角色好感度的设计, 在这里角色好感度其实并不影响剧情, 而是只作为统计值, 其实在真正的电影中, 角色好感度也至关重要, 但是由于它是数值, 在多层级的节点树中的某个中无法根据数值来确切地判断好感度到底是高还是低, 除非把前面所有与此状态相关的节点内容都作为输入

flags

为什么我使用 flags 来描述关键选择或者关键事件呢? 因为 flags 表示的是状态的转折, 而非关键选择本身, 例如对于一个关键选择: 我得到了监狱的钥匙并逃离了监狱, flags 指的是 已经越狱 这个状态, 而不是 我得到了监狱的钥匙 这个事件, 非常重要的一点是, flags 只描述状态, 不描述具体内容或者说上下文

蝴蝶效应

图为奇异人生1 中的 max, 在游戏中出现的蝴蝶

在现实生活中, 蝴蝶效应往往不是 立竿见影 的, 而是 草蛇灰线, 伏脉千里. 🦋

你今天救了一只受伤的流浪猫, 可能在三年后它为你挡下了一次致命的攻击 (有点玄幻了, 但在游戏里很常见).

在 LLM 生成剧情的上下文中, 实现 蝴蝶效应 的核心在于 延迟反馈 (Delayed Feedback).

通常的 LLM 对话是线性的, 它很难 "记住" 10 轮对话前的一个微小细节. 为了模拟这种效果, 我需要将 flags 分为两类:

Immediate Flags (即时标记): 影响下一章的剧情走向.
Dormant Flags (休眠标记): 像一颗种子埋在 Context 里, 直到特定的 Level 或触发条件满足时才 被唤醒.

优化节点

减少节点数量, 增加 level 数量以增加剧情深度
并发生成节点

增加 acts

我们引入 act(幕/阶段) 的概念, 可以理解为小说的每个大章节, 并且在每个 act 中的第一层中都只允许存在一个节点, 这也就意味着我们对节点进行了多次强制收束, 并且我们也会在后面生成节点的时候, 并发生成每个幕, 这样做看似会导致剧情中的每个章节相互隔离, 但是我们通过通过先规划剧本和引入并规划剧情状态的方式规避了这个问题

实现

1. 生成剧本

由于我们生成的剧情节点树非常复杂, 为了提供尽可能确定的信息, 我们需要首先规划全局的剧本结构, 就像我们从北京出发前往纽约, 我们需要指定至少一条路线, 然后再规划好在哪里换乘, 在什么时间休息, 如果遇到可能出现的问题应该如何应对, 这些前期准备是非常重要的

Prompts

# 角色定义
你是一位互动电影游戏编剧和总导演, 你擅长创作 引人入胜 / 逻辑严密 / 充满情感冲击力 的多分支剧情

## 主题
{}

## 剧情简稿
{}

## 角色
{}

# 输出
以下是类型定义, 你需要返回的是一个JSON 数据, 具体要求:
- JSON 数据的类型为 `BluePrint`
- **不允许出现任何 `BluePrint` 的类型定义中没有的字段, 绝对不允许出现 nodes**
- **必须认真阅读注释内容, 并严格遵守注释中的要求, 特别是字数或者数量限制**
- 禁止包含 `\n`
- 至少有一个结局节点可以从非最后一个 act 到达

/** 剧本 */
export interface BluePrint {
  /** 层数, 值为 25-30 */
  levelCount: number
  /** 幕数, 值为 2-3 */
  actCount: number
  /** 起始节点 */
  startNode: StartNode
  /**
   * 关键标记, 数量控制在 1-4 个
   * - key 为标记的名称, 例如 越狱成功, 获得道具等, 必须是确切具体的内容, 不超过 10 个字;
   * - value 为标记的数据
   * @description 这是会影响剧情走向或结局的重要剧情状态, 也是可能造成重要转折, 必须精心设计
   */
  flags: {
    [flagName: string]: {
      /** 标记的详细描述, 必须是确切具体的内容, 不超过 25 字 */
      content: string
      /** 触发/获得 该标记的 level 索引, 值为 2-{@link levelCount}, 必须根据实际剧情({@link acts}) 生成 */
      triggerLevel: number
      /** 此 flag 产生副作用的 level 索引, 值为 {@link triggerLevel}-{@link levelCount}, 必须根据实际剧情({@link acts}) 生成 */
      effectAct: number
    }
  }
  /** 结局节点, 数量控制在 3-5 个, key 为结局的名称, 例如 成功, 失败等; value 为结局信息 */
  endings: {
    [endingName: string]: {
      /** 结局的详细描述, 不超过 35 字 */
      content: string
      /** 触发 该结局的 level 索引, 值为 2-{@link levelCount}, 必须根据实际剧情({@link acts}) 生成 */
      triggerLevel: number
    }
  }
  /**
   * 幕(阶段), 表示相对独立的剧情阶段, 例如 1-5 层为第一阶段, 6-13 层为第二阶段等
   * @description 阶段数量为 {@link actCount} 个
   */
  acts: Array<BluePrintAct>
}

/**
 * 节点 ID, 格式为 `$level-$index`, 例如 `L1N1` 表示第一层中的第一个节点
 * @example L1N1
 */
type NodeId = string

/** 起始节点 */
interface StartNode {
  /** 节点 ID, 值为 L1N1 */
  id: 'L1N1'
  /** 节点内容, 必须以第一个主角的第一人称视角编写, 不超过 60 字 */
  content: string
  /** 该节点的角色 name, 数量控制在 1-3 个 */
  characters: Array<string>
  /** 选项列表, 数量为 2 */
  choices: [StartNodeChoice, StartNodeChoice]
}

/** 起始节点的选项 */
interface StartNodeChoice {
  /** 该选项的内容, 必须以第一个主角的第一人称视角编写, 不超过 35 字 */
  content: string
  /** 该选项指向的下一个节点 ID */
  nextNodeId: NodeId
}

/** 剧本中的幕(阶段) */
interface BluePrintAct {
  /**
   * 该阶段的 level 范围(总层数为 {@link levelCount})
   * 例如 [1, 5] 表示此幕为 第 1 到第 5 层, 也就是说包含 1-5 层的所有节点; [6, 12] 表示此幕为 第 6 到第 12 层
   */
  levelRange: [number, number]
  /** 该阶段的名称, 不能超过 10 个字 */
  name: string
  /**
   * 该阶段剧情的完整具体的描述, ⚠️ **必须是确切具体的内容, 禁止任何 可能/模糊/模糊描述/猜测/假设/推测 等内容**, 200-240 字
   * @description 必须 **概括可能出现的所有剧情分支**, 确保不遗漏任何重要信息
   */
  description: string
}

---

根据用户提供的 主题 / 剧情简稿 / 角色, 发挥你的才华 **反复打磨剧情** 并创作一个完整的互动电影剧本, 并根据 [输出](#输出) 中的要求返回 `BluePrint` 类型的 JSON 数据, **禁止在任何内容的首尾出现中文的双引号**

剧情信息 Output

最终 LLM 输出示例:

{
  "levelCount": 28,
  "actCount": 3,
  "startNode": {
    "id": "L1N1",
    "content": "后脑勺火辣辣的疼！我茫然抬头，口水浸湿了数学卷子。等等……2014年？黑板上那个数字像一道闪电劈中了我。",
    "characters": ["林小北", "张老师"],
    "choices": [
      {
        "content": "震惊地瞪大眼睛，脱口而出：“现在是2014年？”",
        "nextNodeId": "L2N1"
      },
      {
        "content": "强压住翻涌的回忆，低头认错：“对不起张老师，我昨晚复习太晚。”",
        "nextNodeId": "L2N2"
      }
    ]
  },
  "flags": {
    "数学天才觉醒": {
      "content": "林小北凭借未来记忆展现超常数学能力",
      "triggerLevel": 4,
      "effectAct": 12
    },
    "与小美约定未来": {
      "content": "林小北与苏小美约定考同一所大学",
      "triggerLevel": 9,
      "effectAct": 18
    },
    "拯救大伟危机": {
      "content": "林小北提前干预了大伟家庭的财务危机",
      "triggerLevel": 16,
      "effectAct": 23
    },
    "张老师的怀疑": {
      "content": "张老师察觉林小北行为异常并展开调查",
      "triggerLevel": 20,
      "effectAct": 26
    }
  },
  "endings": {
    "重写辉煌": {
      "content": "林小北不仅考取顶尖大学，更帮助朋友实现梦想，与苏小美并肩走向未来。",
      "triggerLevel": 28
    },
    "遗憾的守护者": {
      "content": "林小北过度干涉他人命运导致关系破裂，虽然成绩优异却孤独一人。",
      "triggerLevel": 24
    },
    "真相的代价": {
      "content": "林小北重生秘密被揭穿，被迫接受心理观察，与理想未来失之交臂。",
      "triggerLevel": 22
    },
    "平凡的圆满": {
      "content": "林小北放下执念，专注于自身提升，收获了一段充实平和的高三时光。",
      "triggerLevel": 26
    }
  },
  "acts": [
    {
      "levelRange": [1, 9],
      "name": "觉醒与试探",
      "description": "林小北确认自己重生回到2014年高三。他首先需要适应年轻的身体和校园环境，面对严厉却年轻的班主任张老师。他用成年人的思维应对课堂提问，意外展现出超前的数学知识，这引起了张老师的注意和怀疑。同时，他重新见到了暗恋的苏小美和死党大伟。林小北决定利用未来记忆帮助苏小美提升数学成绩，并试图接近她。他还要应对大伟拉他逃课去网吧的诱惑。在第一次月考中，林小北故意控分，既展示了进步又不过分引人注目。他开始收集信息，确认关键的未来事件节点。本阶段可能出现分支：选择全力学习还是兼顾社交；选择直接追求苏小美还是先提升自己；选择向张老师坦白异常还是隐藏秘密。"
    },
    {
      "levelRange": [10, 19],
      "name": "改变与代价",
      "description": "林小北开始主动改变命运轨迹。他系统地帮助苏小美复习，两人关系升温，并约定共同的目标大学。同时，他利用未来记忆，通过看似偶然的方式提醒大伟关注其父亲公司的财务风险，试图避免其家庭破产。然而，他的行为开始产生蝴蝶效应：一次提前泄露的考题方向引起了张老师的深度怀疑；他对苏小美过于“了解”的关心让她感到困惑；大伟父亲的公司危机虽然被预警，但处理过程引发了新的问题。林小北必须在学业、友情、萌芽的爱情以及隐藏秘密之间寻找平衡。期中考试成为关键节点，他的成绩将直接影响张老师的下一步行动以及苏小美的态度。本阶段可能出现分支：选择优先处理大伟的危机还是专注自己的学业；选择向苏小美部分坦白还是继续伪装；选择应对张老师的调查时是编造理由还是寻求信任。"
    },
    {
      "levelRange": [20, 28],
      "name": "抉择与终局",
      "description": "张老师正式与林小北谈话，指出他行为模式与知识储备的异常，逼近真相。大伟家的危机因干预出现新的变数，需要林小北再次介入。苏小美感受到了林小北的压力和秘密，关系出现裂痕或需要更深的信任。高考百日冲刺开始，林小北必须做出最终抉择：是继续利用未来信息获取最大优势，承担秘密暴露的风险；还是回归一个普通高三生的本分，接受命运的不确定性。他的每一个选择都将导向不同结局：可能成功改变所有人的命运，登上巅峰；也可能因过度干预而失去重要的人和事；或者秘密曝光，面临无法预料的后果；亦或在平凡中寻得内心的平静与圆满。最终，在高考考场或毕业时刻，所有的伏笔收束，林小北的重生之旅迎来终局。"
    }
  ]
}

附对应的真实输入

# 角色定义
你是一位互动电影游戏编剧和总导演, 你擅长创作 引人入胜 / 逻辑严密 / 充满情感冲击力 的多分支剧情

## 主题
重生之被班主任拍醒

## 剧情简稿
数学课，我趴在课桌上流口水。突然，后脑勺挨了一巴掌："又睡觉！"猛一抬头，我惊恐地发现——黑板上写着"2014年"，眼前是年轻十岁的班主任老张。我竟然重生了！带着30岁社畜的记忆回到高三，我发誓要改变高考失利的命运，重新追回错过的暗恋，但事情真的会如我所愿吗？

## 角色
\`\`\`json
[
  {
    "name": "林小北",
    "description": "18岁，高三学生（内心30岁）。带着未来的记忆重生，决心改变命运，但成人思维与少年身份格格不入。",
    "gender": "男",
    "isMain": true
  },
  {
    "name": "张老师",
    "description": "40岁，数学老师兼班主任。严厉古板，口头禅\"你们是我带过最差的一届\"，其实关心学生。",
    "gender": "男",
    "isMain": false
  },
  {
    "name": "苏小美",
    "description": "18岁，同桌。当年的暗恋对象，活泼可爱，数学很差但很努力，不知道自己已被\"预支\"了未来。",
    "gender": "女",
    "isMain": false
  },
  {
    "name": "胖子大伟",
    "description": "18岁，死党。讲义气但成绩烂，未来会出国发展，现在是需要帮助的好兄弟。",
    "gender": "男",
    "isMain": false
  }
]
\`\`\`

# 输出
以下是类型定义, 你需要返回的是一个JSON 数据, 具体要求:
- JSON 数据的类型为 `BluePrint`
- **不允许出现任何 `BluePrint` 的类型定义中没有的字段, 绝对不允许出现 nodes**
- **必须认真阅读注释内容, 并严格遵守注释中的要求, 特别是字数或者数量限制**
- 禁止包含 `\n`
- 至少有一个结局节点可以从非最后一个 act 到达

\`\`\`typescript
/** 剧本 */
export interface BluePrint {
  /** 层数, 值为 25-30 */
  levelCount: number
  /** 幕数, 值为 2-3 */
  actCount: number
  /** 起始节点 */
  startNode: StartNode
  /**
   * 关键标记, 数量控制在 1-4 个
   * - key 为标记的名称, 例如 越狱成功, 获得道具等, 必须是确切具体的内容, 不超过 10 个字;
   * - value 为标记的数据
   * @description 这是会影响剧情走向或结局的重要剧情状态, 也是可能造成重要转折, 必须精心设计
   */
  flags: {
    [flagName: string]: {
      /** 标记的详细描述, 必须是确切具体的内容, 不超过 25 字 */
      content: string
      /** 触发/获得 该标记的 level 索引, 值为 2-{@link levelCount}, 必须根据实际剧情({@link acts}) 生成 */
      triggerLevel: number
      /** 此 flag 产生副作用的 level 索引, 值为 {@link triggerLevel}-{@link levelCount}, 必须根据实际剧情({@link acts}) 生成 */
      effectAct: number
    }
  }
  /** 结局节点, 数量控制在 3-5 个, key 为结局的名称, 例如 成功, 失败等; value 为结局信息 */
  endings: {
    [endingName: string]: {
      /** 结局的详细描述, 不超过 35 字 */
      content: string
      /** 触发 该结局的 level 索引, 值为 2-{@link levelCount}, 必须根据实际剧情({@link acts}) 生成 */
      triggerLevel: number
    }
  }
  /**
   * 幕(阶段), 表示相对独立的剧情阶段, 例如 1-5 层为第一阶段, 6-13 层为第二阶段等
   * @description 阶段数量为 {@link actCount} 个
   */
  acts: Array<BluePrintAct>
}

/**
 * 节点 ID, 格式为 `$level-$index`, 例如 `L1N1` 表示第一层中的第一个节点
 * @example L1N1
 */
type NodeId = string

/** 起始节点 */
interface StartNode {
  /** 节点 ID, 值为 L1N1 */
  id: 'L1N1'
  /** 节点内容, 必须以第一个主角的第一人称视角编写, 不超过 60 字 */
  content: string
  /** 该节点的角色 name, 数量控制在 1-3 个 */
  characters: Array<string>
  /** 选项列表, 数量为 2 */
  choices: [StartNodeChoice, StartNodeChoice]
}

/** 起始节点的选项 */
interface StartNodeChoice {
  /** 该选项的内容, 必须以第一个主角的第一人称视角编写, 不超过 35 字 */
  content: string
  /** 该选项指向的下一个节点 ID */
  nextNodeId: NodeId
}

/** 剧本中的幕(阶段) */
interface BluePrintAct {
  /**
   * 该阶段的 level 范围(总层数为 {@link levelCount})
   * 例如 [1, 5] 表示此幕为 第 1 到第 5 层, 也就是说包含 1-5 层的所有节点; [6, 12] 表示此幕为 第 6 到第 12 层
   */
  levelRange: [number, number]
  /** 该阶段的名称, 不能超过 10 个字 */
  name: string
  /**
   * 该阶段剧情的完整具体的描述, ⚠️ **必须是确切具体的内容, 禁止任何 可能/模糊/模糊描述/猜测/假设/推测 等内容**, 200-240 字
   * @description 必须 **概括可能出现的所有剧情分支**, 确保不遗漏任何重要信息
   */
  description: string
}
\`\`\`
---

根据用户提供的 主题 / 剧情简稿 / 角色, 发挥你的才华 **反复打磨剧情** 并创作一个完整的互动电影剧本, 并根据 [输出](#输出) 中的要求返回 `BluePrint` 类型的 JSON 数据, **禁止在任何内容的首尾出现中文的双引号**

2. 生成逻辑拓扑

接下来我们要构建具体的剧情树结构, 在 <a href="/movie-games-record" target="_blank">上篇文章</a> 中我们介绍了剧情树接口的要求, 以及因 LLM 输出的不稳定性可能导致的诸多问题, 因此我们尝试单独生成剧情树, 也就是逻辑拓扑结构, 我们有两个选择:

让 LLM 使用只专注于生成剧情树结构, 尽可能少的关注剧情内容

优势:
- 可以根据实际的剧情信息生成更符合剧情的逻辑拓扑
劣势:
- 输出不稳定, 可能会生成不符合要求的逻辑拓扑
- 更长的耗时
- 消耗更多的 token

直接通过程序生成剧情树结构

优势:
- 可以生成绝对稳定的逻辑拓扑
- 生成速度非常快
- 不消耗 token
劣势:
- 不能根据实际的剧情信息生成更符合剧情的逻辑拓扑

2.1 LLM 生成逻辑拓扑

在这个阶段, 只生成剧情树的 骨架 (Skeleton), 也就是 Topology (拓扑结构). 它不需要包含具体的对话内容, 只需要包含:

id: 节点 ID
summary: 一句话剧情梗概 (One-sentence Summary)
choices: 选项结构 (仅包含跳转逻辑 nextNodeId)
required_flags: 进入该节点需要的条件

// 剧情树骨架节点定义
interface StoryNodeSkeleton {
  id: string;
  beatType: 'Setup' | 'Conflict' | 'Climax' | 'Resolution';
  summary: string; // 例如: "主角在废弃仓库发现了一张旧照片"
  choices: {
    label: string; // 简短的选项标签, 如 "捡起来"
    nextNodeId: string;
  }[];
  // ... 其他元数据
}

:::tip 为什么要这么做? 因为 LLM 的注意力是有限的. 如果让它同时思考 "这句话该怎么写才优美" 和 "这个选项该跳到第几层才不会死循环", 它往往两头都顾不好. 通过剥离 文学创作 任务, 让它专注于 逻辑构建, 我们可以得到一个结构非常严谨、甚至带有精妙 收束点 (Convergence Point) 的剧情树. 🌳 :::

在这个阶段, 我会强制要求 LLM 检查每一层的 节点数量 和 收束率. 如果发现某一层节点爆炸 (Node Explosion), 或者某条线断了 (Dead End), 直接在代码层面这就给它 Reject 掉, 根本不需要等到生成正文.

确定结构要求

首先我们需要明确节点树的具体要求, 这样才能让 LLM 发挥作用

你是一位严谨的游戏逻辑架构师, 你的任务是根据提供的[剧情介绍](#剧情介绍), 为互动游戏生成纯逻辑的拓扑结构（DAG）

**你需要认真阅读 [介绍](#介绍) 和 [具体要求](#具体要求) 中的内容, 并根据内容生成符合要求的剧情树 JSON**
---
## 主题
{}

## 剧情介绍
{}

## 基本概念
### level
节点的层级, 层级表示节点在剧情树中的深度, 例如 `level` 为 1 表示第一层, 第一层只有一个开始节点, 开始节点中的选项(`choices`)指向下一个层级的节点(或者结局节点)

### node
节点, 分为剧情节点和结局节点

### act
幕(阶段), 表示相对独立的剧情阶段, 例如 `1-5` 层为第一阶段, `6-13` 层为第二阶段等; 用于控制节点的数量和收束率

### flag
关键标记, 意为选择某个选项之后触发的 **影响当前或后续剧情走向** 的事件, 数量在 `1-4` 个

#### 剧情节点
剧情节点, 表示剧情的发展过程, 类型定义如下:

\`\`\`typescript
type StoryNodeList = [StoryNode]
interface StoryNode {
  /** 节点 ID, 从第二层(L2)开始 */
  id: NodeId;
  /** 节点的剧情梗概, 不超过 20 字 */
  summary: string
  /** 选项列表, 数量 */
  choices: [Choice, Choice]
}
/**
 * 节点 ID, 格式为 `$level-$index`, 例如 `L1N1` 表示第一层中的第一个节点
 * @example L1N1
 */
type NodeId = string
/**
 * 结局节点名称, 例如 '完美人生' 对应 `endings` 中的 '完美人生' 结局
 */
type EndNodeId = string
interface Choice {
  /** 该选项的内容, 先不生成内容 */
  content: ''
  /** 该选项指向的下一个节点 ID(或结局节点 ID) */
  nextNodeId: NodeId | EndNodeId
  /**
   * 当获得指定的(一个或两个) flag 时, 需要跳转的下一个节点 ID(或结局节点 ID)
   * @description `key` 为下一个节点 ID(或结局节点 ID), `value` 为触发跳转需要的全部 flag; **`key` 不能与 `nextNodeId` 相同**
   * @example `{ "L10N2": ["学业觉醒"] }` - 当获得 `学业觉醒` 这个 flag 时, 跳转至 `L10N2` 节点
   * @example `{ "L10N3": ["青春悸动"] }` - 当获得 `青春悸动` 这个 flag 时, 跳转至 `L10N3` 节点
   * @example `{ "不幸遇难": ["命悬一线", "迷失方向"] }` - 当获得 `命悬一线` 和 `迷失方向` 这个 flag 时, 跳转至 `不幸遇难` 结局节点
   */
  plotBranching?: {
    [nextNodeId: NodeId | EndNodeId]: [string] | [string, string]
  }
  /** 选择当前节点之后获取到的 flag */
  flag?: string
}
\`\`\`

#### 结局节点
现有的结局节点为:
{}

## 具体要求
- 每层节点数量控制在 `1-3` 个, 至少 `70%` 的 level 层节点数量为 `2` 个
- 必须是 DAG（有向无环图）
- 所有选项都必须指向下一个层级的节点(或者结局节点)
- 所有的 `flag` 必须有触发节点和应用节点

最终输出结果

我测试了一下 <a href="https://chat.deepseek.com/share/nbodpwrki54a5coulb" target="_blank">deepseek 的输出</a>, 发现 LLM 根本无法生成结构严谨的逻辑拓扑, 出现了 <a href="/movie-games-record" target="_blank">上篇文章</a> 一样的问题

2.2 通过程序生成逻辑拓扑

下面我们来通过程序实现一个简单的逻辑拓扑生成方法, 对应的输入就是剧情信息 Output, 输出就是一个不包含实际内容的逻辑拓扑 JSON 字符串

逻辑拓扑数据类型

/** 至少包含一个元素的数组（非空数组） */
type NonEmptyArray<T> = readonly [T, ...T[]]

/**
 * 第一行只能有一个元素，后续每一行至少一个元素的二维数组
 */
type RestrictedTwoDimensionalArray<T> = readonly [
  readonly [T],
  ...NonEmptyArray<T>[]
]

/**
 * 包含全部剧情节点的 分层有向无环图 (`Layered Directed Acyclic Graph`)
 * @description 具有严格详细数学约束的 **分层有向无环图** 剧情节点图
 */
export type LDAGActs = NonEmptyArray<LDAGNodes>

/**
 * 每一幕的剧情节点图
 */
export type LDAGNodes = RestrictedTwoDimensionalArray<LDAGNode>

/**
 * 结局节点集合
 * @description endingName 为结局节点名称, EndingNode 为结局节点信息
 */
export type EndingNodes = {
  [endingName: `ENDING_${string}`]: EndingNode
}

/** 结局节点 */
interface EndingNode {
  /** 结局的详细描述, 不超过 35 字 */
  content: string
  /** 触发 该结局的 level 索引 */
  triggerLevel: number
}

/**
 * 节点 ID, 格式为 `$level-$index`, 例如 `L1N1` 表示第一层中的第一个节点
 * @description level 表示第几层, index 表示该层中的第几个节点(从 1 开始索引)
 * @example L1N1
 */
type NodeId = `L${number}N${number}`

/** 结局节点 ID */
type EndingNodeId = `ENDING_${string}`

/**
 * LDAG 分层有向无环图节点
 */
interface LDAGNode {
  /**
   * 节点 ID, 格式为 `$level-$index`, 例如 `L1N1` 表示第一层中的第一个节点
   * @example L1N1 起始节点
   * @example L2N2 位于第二层的第二个节点(索引为 2 的节点)
   */
  id: NodeId
  /** 节点内容, 不超过 50 字 */
  content: string
  /** 该节点包含或关联的角色 name, 数量控制在 1-3 个 */
  characters: Array<string>
  /**
   * 选项列表, 数量为 1-3
   * ## 允许节点收束
   * 允许选项指向相同的节点
   */
  choices: [LDAGNodeChoice] | [LDAGNodeChoice, LDAGNodeChoice] | [LDAGNodeChoice, LDAGNodeChoice, LDAGNodeChoice]
}

/** 节点的选项 */
interface LDAGNodeChoice {
  /** 该选项的内容, 不超过 25 字 */
  content: string
  /** 
   * 触发(设置)的 flag 名称 
   * @description 对应 BluePrint 中的 flags[flagName].triggerLevel
   */
  triggerFlag?: string
  /** 
   * 该选项指向的下一个节点 ID 
   * @description 如果是 string, 表示无条件跳转; 如果是对象, 表示根据 checkFlag 的值跳转(对应 BluePrint 中的 flags[flagName].effectLevel)
   */
  nextNodeId: NodeId | EndingNodeId | ConditionalNextNodeId
}

/** 条件跳转节点 ID */
interface ConditionalNextNodeId {
  /** 需要检查的 flag 名称 */
  checkFlag: string
  /** flag 为 true 时的下一个节点 ID */
  trueId: NodeId | EndingNodeId
  /** flag 为 false 时的下一个节点 ID */
  falseId: NodeId | EndingNodeId
}

完整的数学约束

# 剧情节点图的数据结构

以下是该分层有向无环图（Layered Directed Acyclic Graph, **LDAG**）剧情结构的严谨数学约束定义：

### 剧情系统 LDAG 数学约束模型

设剧情图为 $G = (V_P, V_E, E)$，其中 $V_P$ 为剧情节点集，$V_E$ 为结局节点集，$E$ 为有向边集。

#### 1. 集合定义与层级分区

* **幕与层级分区**：剧情图 $G$ 由 $m$ 个有序的幕（Act）组成：$G = \{A_1, A_2, \dots, A_m\}$，其中 $3 \le m \le 4$。
* **节点分区**：每一幕 $A_i$ 的节点集 $V_{P_i}$ 被划分为 $k_i$ 个不相交的子集（层）：$V_{P_i} = L_{i,1} \cup L_{i,2} \cup \dots \cup L_{i,k_i}$，其中 $8 \le k_i \le 15$。总层数 $k = \sum k_i$ 满足 $35 \le k \le 45$。
* **幕起始节点**：每一幕的第一层 $L_{i,1}$ 必须且只能包含一个节点 $\{v_{start_i}\}$。即 $|L_{i,1}| = 1$。
* **结局隔离**：结局节点集 $V_E$ 与剧情节点集 $V_P$ 互斥，$V_P \cap V_E = \emptyset$。且结局节点入度 $d^-(v) > 0$，出度 $d^+(v) = 0$（仅作为叶子节点）。

#### 2. 拓扑分布约束 (Density Control)

* **层宽约束**：对于任意层 $L_i \in V_P$，其基数满足 $1 \le |L_i| \le 3$。
* **比例分布**：满足条件 $|L_i| = 2$ 的层数占比 $P(|L_i|=2) \ge 70\%$。

#### 3. 边的单调性与跨度约束 (Edge Monotonicity)

对于任意有向边 $e = (u, v) \in E$：

* **严格递增**：若 $u \in L_i$ 且 $v \in L_j$（或 $v \in V_E$），则必须满足 $j > i$。
* **禁止环路**：由于 $j > i$，图 $G$ 物理上不存在环路（Acyclic）。
* **邻层倾向**：设 $E_{adj}$ 为满足 $j = i+1$ 的边集，则要求其在剧情节点间的边占比满足 $\frac{|E_{adj} \cap (V_P \times V_P)|}{|E \cap (V_P \times V_P)|} \ge 90\%$。

#### 4. 强连通性约束 (Connectivity)

* **全可达性**：对于任意节点 $v \in V_P \cup V_E$，必存在至少一条路径 $Path(v_{start} \to v)$。即 $G$ 中不存在孤立点或入度为 0 的非起始节点。
* **结局可达性**：对于任意结局 $v_e \in V_E$，必存在路径 $Path(u \to v_e)$，其中 $u \in V_P$。
* **禁止初级终结**：不存在边 $(v_{start}, v_e)$，其中 $v_{start} \in L_1, v_e \in V_E$。

#### 5. 状态机闭环约束 (Flag Logic)

设全局布尔标记集为 $F = \{f_1, f_2, \dots, f_m\}$，其中 $3 \le m \le 6$。
对于任意 $f \in F$：

* **定义域闭环**：标记 $f$ 必须在边集 $E$ 的属性中至少被执行一次 $Set(f)$ 操作和一次 $Check(f)$ 操作。
* **因果序约束**：设 $SetNodes(f) = \{u \in V_P \mid \exists (u, v) \text{ s.t. } Set(f)\}$，设 $CheckNodes(f) = \{u \in V_P \mid \exists (u, v) \text{ s.t. } Check(f)\}$。则必须满足：$$\min_{u \in SetNodes(f)} (Level(u)) < \min_{w \in CheckNodes(f)} (Level(w))$$


* **判定完备性**：所有 $Check(f)$ 操作必须提供完备的二元输出路径 $\{if\_true, if\_false\}$，且两个出口指向的节点 $v$ 必须满足层级约束。

输出

最终的输出不包含剧情节点的内容, 仅包含节点 ID, 角色, 选项, 跳转目标等信息

3 生成节点内容

有了前面生成的剧本和逻辑拓扑, 我们就可以填充每个节点的剧情了, 这里我们选择每个 act(幕) 单独生成, 也就是所有的 acts 并发生成, 提升速度

# 角色定义
你是一位互动电影游戏编剧和总导演, 你擅长创作 引人入胜 / 逻辑严密 / 充满情感冲击力 的多分支剧情

## 主题
__TITLE__

## 剧情简稿
__SUMMARY__

## 角色
__CHARACTERS__

## 当前幕剧情信息
__ACT_INFO__

## 任务
你需要根据给定的 **剧情节点图结构** 和 **当前幕剧情信息**, 为每个节点填充具体的 **剧情内容** 和 **选项内容**。

## 剧情节点图结构
__LDAG_NODES__

## 输出要求
请输出符合以下 TypeScript 类型定义的 JSON 数据, 也就是一个 `LDAGNodes` 类型的 JSON 数据:

\`\`\`typescript
__LDAG_TYPES__
\`\`\`

## 注意事项
1. 保持剧情的连贯性和逻辑性, 必须符合 **当前幕剧情信息** 的描述。
2. 节点的 ID 和连接关系 **必须** 与输入的 **剧情节点图结构** 完全一致，不能增加、删除或修改节点和连线，只能填充内容。
3. `content` 字段为剧情文本。
4. `choices` 字段中的 `content` 为选项文本。
5. 严格遵守 JSON 格式输出。

4 返回完整的剧情信息

最后, 我们定义一下接口的最终返回值类型:

import type { EndingNodes, LDAGActs } from "./LayeredDirectedAcyclicGraph";
import { type BluePrint } from './BluePrint'

/** 完整的生成完毕后的剧情信息 */
export interface Story extends BluePrint {
  /** 剧情节点图 JSON */
  actList: LDAGActs
  /** 结局节点集合 */
  endings: EndingNodes
}

完整计划稿

可以在我的仓库中看到完整的 <a href="https://github.com/SublimeCT/movie-games/blob/feature/main-generating/.claude/plan/generating/generating.md" target="_blank">plan 文件</a>(最终是由 trae 国际版完成的任务)

总结

通过这一系列的重构，我终于从 "把所有东西一股脑扔给 LLM" 的暴力美学中醒悟过来。我们总是期待 LLM 能成为那颗银弹，能够一次性解决所有问题，但现实往往是它给了你一坨不可控的 JSON。

构建工作流 (Workflow) 本质上是在给 LLM 降噪和祛魅。

祛魅: 承认 LLM 的局限性，它不是全能的上帝，它记不住 80 个节点前的伏笔，也算不清复杂的概率收束。
降噪: 通过拆解任务，让 LLM 在每一个 Stage 只专注于一件事——要么是天马行空的剧本创作，要么是严谨的逻辑填空。

现在的流程虽然看起来比最初的 "一键生成" 复杂了数倍:

先写剧本 (BluePrint) 📝
程序生成骨架 (Topology) 🦴
并发填充血肉 (Content) 🥩

但这种 "程序逻辑约束(Math) + AI 创意填充(Magic)" 的模式，才是目前构建复杂 AI 应用的正确打开方式。程序保证了下限（至少能跑通，逻辑闭环），而 LLM 决定了上限（剧情是否精彩）。

如果说上一篇文章是理想主义的碰壁，那这一篇就是工程主义的胜利。当然，这套方案也不是终点，生成的剧情依然可能存在逻辑漏洞，但至少，我们现在有了一个可以稳定迭代的基座。

接下来的挑战，就是如何让生成的游戏更好玩，以及如何把这个生成器真正做成一个产品。🚀

参考

<a href="/movie-games-record" target="_blank">上一篇文章</a>
<a href="./assets/images/movie-games-optimize-mow.excalidraw.svg" target="_blank">现有的剧情树设计</a>
<a href="../movie-games-record/#剧情状态丢失" target="_blank">剧情状态丢失</a>
<a href="https://chatgpt.com/share/6964a414-ade4-800b-b839-5b53fd8a1ce4" target="_blank">ChatGPT</a>
<a href="https://gemini.google.com/share/3359fe7f9880" target="_blank">Gemini</a>
<a href="https://chat.deepseek.com/share/pysplefy24u9rk71gc" target="_blank">DeepSeek</a>
<a href="https://chatgpt.com/share/6964a414-ade4-800b-b839-5b53fd8a1ce4" target="_blank">点击这里</a>
<a href="https://chat.deepseek.com/share/pysplefy24u9rk71gc" target="_blank">点击这里</a>
<a href="https://gemini.google.com/share/3359fe7f9880" target="_blank">点击这里</a>
<a href="/movie-games-record" target="_blank">上篇文章</a>
<a href="https://chat.deepseek.com/share/nbodpwrki54a5coulb" target="_blank">deepseek 的输出</a>
<a href="https://github.com/SublimeCT/movie-games/blob/feature/main-generating/.claude/plan/generating/generating.md" target="_blank">plan 文件</a>

AI 互动剧情类游戏生成工具开发记录1 - 剧情设计

Tue, 06 Jan 2026 00:00:00 GMT

前段时间 vibe coding 了一个<a href="http://movie-games.xiaban.run/" target="_blank">🔗 互动剧情类游戏的生成工具</a>, <a ref="https://movie-games.xiaban.run/play/2b22e895-ce32-488e-a9fe-a015355eb2ae">点此游玩</a>, 在开发过程中遇到了一系列问题, 本文将对具体的问题进行介绍

互动剧情类游戏

<a href="https://zh.wikipedia.org/wiki/%E4%BA%92%E5%8A%A8%E7%94%B5%E5%BD%B1%E6%B8%B8%E6%88%8F" target="_blank">互动电影游戏</a> 是一个游戏类型, 与此相同的称呼还有: 剧情互动类游戏 / 互动电影游戏 / 交互式小说 / 互动小说 等等

其实我真正想做的是有视频的互动剧情类游戏, 这才是这类游戏的完整形态, 但受限于视频和图片生成的成本, 我最终选择了只生成剧情和角色头像的版本, 那么 什么是互动剧情类游戏呢?

我们不讲晦涩难懂的专业名词, 而是列举几个同类型的游戏:

<a href="https://store.steampowered.com/curator/36149206">奇异人生系列</a>: 主角拥有超能力, 剧情非常沉浸式, 你可以控制主角的超能力, 逐渐了解游戏的世界观, 每个人物都有精心的塑造, 每个选择都可能引发蝴蝶效应, 游戏工作室将大多数资金用于剧情创作和聘请配音员
<a href="https://store.steampowered.com/app/1222140/_/" target="_blank">底特律：化身为人</a>: 游戏背景是人类与机器人的共处的未来, 你将扮演三个人形仿生机器人与人类相处, 站在机器人的角度思考和处理与人类的关系, 这个游戏让我感觉人类是自私和愚蠢的, 机器人也许会替代人类完成人类的使命
<a href="https://store.steampowered.com/app/939400/LoveChoice/?l=schinese" target="_blank">拣爱</a>: 这其实不算电影类游戏, 拣爱是一款深受日式AVG游戏启发的剧情导向游戏, 它强调玩家的每一个选择，每个场景都充满了深意和目的性。这款游戏以探讨爱为主题，旨在通过其丰富的故事和情感体验，引导玩家理解爱的真谛，并学习如何在人际关系中表达和接受爱。通过《拣爱》，玩家将踏上一段关于情感、选择与爱的旅程。
<a href="https://store.steampowered.com/app/2322560/_/" target="_blank">完蛋! 我被美女包围了!</a>: 无需多言, 它完全没有故事情节, 但它有足够漂亮主动的女生, 和爽文男主般的初始设定, 顶级的男主, 一流的女演员, 蹩脚的台词, 和敷衍的剧情
<a href="https://store.steampowered.com/app/1341820/As_Dusk_Falls/" target="_blank">日落黄昏时(As Dusk Falls)</a>: 这是我玩过的第一个互动电影类游戏, 我至今无法忘记那个一口气通关的下午, 它与其他同类型游戏的不同之处在于, 它的沉浸感非常强, 它让你感觉到就像一个专业的电影团队做起了游戏, 它有着成熟的剧本, 成熟的配音, 成熟的画面, 一切都是专业级的
<a href="https://store.steampowered.com/app/1577120/_/" target="_blank">采石场惊魂</a>: 这是我玩过的唯一一个恐怖类型的互动电影类游戏, 它对于恐怖元素的尺度把握的刚刚好, 喜欢恐怖游戏的朋友会感觉很过瘾

总结一下这类游戏的特点:

沉浸式 的电影级体验
多故事线/多结局
互动性强, 玩家可以根据自己的选择影响故事走向

AI 驱动的互动剧情类游戏

随着生成式人工智能的发展, 互动剧情类游戏会出现哪些变化呢? 我们把游戏拆分为三部分:

📚 剧本

一个成熟的工业级的电影剧本必然会 经历多轮修改, 剧本的修改或打磨往往跟导演 / 编剧密不可分, 我认为现阶段最大的问题在于:

剧本内容过长, 现阶段 LLM 还无法直接处理拥有巨量文字的剧本, 换句话说 巨大的上下文会导致 AI 忘记某些事或者出现幻觉
AI 生成的剧情 / 角色缺乏张力, 剧情过于普通
AI 对潜台词的理解是形式化的, 电影中经常出现的潜台词需要结合情绪 / 目的 / 角色冲突等一系列因素

所以 AI 难以直接生成替代人类创作和打磨的剧本

🎬 电影

现阶段各大厂都推出了自己的视频模型, 例如 <a href="https://gemini.google/tw/overview/video-generation/?hl=zh-TW" target="_blank">video-generation</a> / <a href="https://www.adobe.com/tw/products/firefly/features/ai-video-generator.html" target="_blank">Adobe Firefly</a>, 而且不约而同的标榜自己可以进行电影级别的视频生成, 但只要你仔细观察生成的视频, 就会发现一些违背现实世界物理规律的地方, 但这不妨碍用于为视频增加特效等应用场景, 我认为一定会有部分特效非常适合 AI 生成

如何制作一部工业级的电影?

开发期: 把一个想法变成可拍摄、可融资、可评估风险的项目
前期制作: 在不开机的情况下，把所有问题提前解决

导演确定视觉风格（Reference / Lookbook）
分镜（Storyboard / Previs）
演员选角（Casting）
勘景（Location Scouting）
摄影、美术、服装、化妆方案
拍摄计划（Shooting Schedule）

拍摄期: 在时间 / 预算 / 人员约束下完成素材采集
后期制作: 把素材变成叙事流畅、情绪准确、节奏稳定的成片

电影实际上不是拍出来的, 而是剪出来的, 这几乎完全依赖制作人员的经验和审美, 电影风格或者说审美是难以完全交给 AI

🎮 游戏

在剧本已经确定, 视频已经制作完成之后, 游戏软件(GUI) 本身的制作就回归到软件开发领域了, 在代码层面就非常适合 AI 来接管

软件设计

我要做的是一个 AI 驱动的互动剧情类游戏 生成器, 为什么我没有说互动电影游戏呢? 因为图片和视频的生成成本过高耗时太长, 我想做的是一个 快速可玩的生成工具, 剧本生成也存在难以解决的问题, 所以我真正要做的是:

只有背景图 / 角色头像
多故事线的剧情树
可以设计剧情信息

页面

<details> <summary>点击查看全部页面</summary>

主页
生成页
游戏页
结局页
设计页

</details>

数据流

图片生成

图片生成使用 GLM 的免费(限制并发)文生图模型 <a href="https://docs.bigmodel.cn/cn/guide/models/free/cogview-3-flash" target="_blank">cogview-3-flash</a>, 虽然质量很差, 但是它免费用我高低得夸它一下

[!TIP] 非常感谢智谱慷慨得提供免费模型, 如果你有 Coding 的需求, 可以购买智谱的 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Plan</a> 订阅支持一下, 或者点击这里试用

视频生成

其实也试过 GLM 的免费(限制并发)的视频生成模型 <a href="https://docs.bigmodel.cn/cn/guide/models/free/cogvideox-flash" target="_blank">cogvideox-flash</a>, 但是生成一个视频大概需要 3 分钟, 而且限制并发数只有 1, 生成的视频质量 emmmmm 非常拉, 其他的商业模型成本太高, 就没有使用视频生成

开发

技术栈

前端: vite / vue / inspira-ui
后端: axum / sqlx / postgresql

前端

经过一段时间的 Vibe Coding, 顺利完成了前端的页面的开发, 前端没有使用任何组件库, 只使用了 inspira-ui 作为特效库

后端

后端接口

后端提供了以下(主要)接口:

/expand/worldview: 根据游戏主题 / 剧情类型生成剧情简介
/expand/worldview/prompt: 返回 /expand/worldview接口使用的提示词
/expand/character: 根据游戏主题 / 剧情类型 / 剧情简介生成角色
/expand/character/prompt: 返回 /expand/character接口使用的提示词
/generate: 生成剧情树
/generate/prompt: 返回 /generate 接口使用的提示词

剧情树

这里面最复杂的就是剧情树了, 因为互动剧情类游戏是 多故事线 / 多结局, 所以实际上 剧情是树结构的, 而不是一条直线, 这导致了很多问题

剧情节点

一个简单的剧情节点的数据结构示例:

{
  "nodes": {
    "start": {
      "content": "数学课上，我趴在课桌上流口水，梦见三十岁的加班生活。突然，后脑勺挨了一巴掌：'又睡觉！'猛一抬头，我惊恐地发现黑板上写着'2014年'，眼前是年轻十岁的班主任老张。我竟然重生了，带着记忆回到高三。",
      "level": 1,
      "characters": ["林小北", "张老师"],
      "choices": [
        {
          "text": "假装镇定，继续上课",
          "nextNodeId": "1"
        },
        {
          "text": "激动地站起来，解释重生",
          "nextNodeId": "2"
        }
      ]
    }
    // ...
  }
}

剧情树生成

图为一个简单的剧情数结构, 玩家会在每个节点上做出选择, 做出选择后会进入下一个节点

剧情节点膨胀

如果不同的选项指向不同的节点, 那么会造成节点树的剧烈的膨胀, 实际上我们并不需要这么多节点, 所以要进行 节点收束, 也就是 允许不同的选项指向同一个后继结点:

这里的 Node3 中的两个选项都指向了 Node6, 也就是说无论选择哪个选项都不影响剧情走向, 这就会造成另外一个问题: 剧情状态丢失

剧情状态丢失

玩家在 Node1 中无论选择了 A 还是 B, 在进入 Node6 时, 之前所有的节点状态都会进行统一, 举个例子:

Node1: "我发现了女友出轨的证据, 女友极力辩解"
- A: 信任她
- B: 结束关系
Node6: "再次与她相遇 ..."

此时 "我" 在 Node1 做出的选择明显应该深刻影响后续剧情, 但在 Node6 及其之后的节点中, 无论选择 A 还是 B 就都是一样的了

当然这是可以解决的, 这涉及到节点树的 剧情状态 设计, 后续文章会探索解决方案

游离节点

游离节点指的是 从初始节点无法到达的节点

什么? 你问我为什么不在提示词中明确告诉 LLM 避免出现这种情况? 因为我试过了, 即使我在提示词中加上了整个要求, 因为 LLM 输出的不确定性以及上下文长度的问题, 还是会有概率出现这个问题

循环引用

循环引用也是个致命的问题, 它会造成剧情死循环, 就像中了伊邪那美一样

其他问题

其实还有更多问题, 例如:

JSON 解析失败: LLM 输出的 JSON 可能会解析失败, 导致用户等待了几分钟最后报错 😡, 最常见的是在 JSON 结构中使用中文的双引号
没有选项的节点: 到达某个剧情节点时, 无法继续进行
自引用节点: 节点的某个选项指向自己
节点选项空指针: 剧情节点的某个选项指向了不存在的节点, 这个也很常见, 例如选项 A 指向了 Node 100, 但一共只有 50 个节点
大量只有一个选项的节点: 只有一个选项会导致剧情树变成一条直线
节点内容或选项重复: 节点的内容和选项完全重复, 根本没办法玩下去
节点引用了不存在或错误的角色: 剧情节点中引用了不存在的角色, 或者一个角色都不引用

设计缺陷

除了以上列出的剧情树的问题, 整体也有影响用户体验的严重的问题:

剧情过于普通: AI 生成的剧情总是感觉非常虚假, 就像写日记一样, 这根本不是玩家想要的剧情
生成剧情耗时太长: 生成一次剧情大概需要 1w tokens, 大约需要 1~2 分钟, 如果开启 think mode, 耗时就会达到 8 分钟(使用的是 deepseek), 没错, 需要让玩家等待 8 分钟

总结

至此, 一个可以使用的互动剧情类游戏生成器已经初现雏形, 所有的问题我们将在后续文章中探索解决方案

参考

<a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Plan</a>
<a href="http://movie-games.xiaban.run/" target="_blank">互动剧情类游戏的生成工具</a>
<a href="https://zh.wikipedia.org/wiki/%E4%BA%92%E5%8A%A8%E7%94%B5%E5%BD%B1%E6%B8%B8%E6%88%8F" target="_blank">互动电影游戏</a>
<a href="https://store.steampowered.com/curator/36149206" target="_blank">奇异人生系列</a>
<a href="https://store.steampowered.com/app/1222140/_/" target="_blank">底特律：化身为人</a>
<a href="https://store.steampowered.com/app/939400/LoveChoice/?l=schinese" target="_blank">拣爱</a>
<a href="https://store.steampowered.com/app/2322560/_/" target="_blank">完蛋! 我被美女包围了!</a>
<a href="https://store.steampowered.com/app/1341820/As_Dusk_Falls/" target="_blank">日落黄昏时(As Dusk Falls)</a>
<a href="https://store.steampowered.com/app/1577120/_/" target="_blank">采石场惊魂</a>
<a href="https://gemini.google/tw/overview/video-generation/?hl=zh-TW" target="_blank">video-generation</a>
<a href="https://www.adobe.com/tw/products/firefly/features/ai-video-generator.html" target="_blank">Adobe Firefly</a>
<a href="https://docs.bigmodel.cn/cn/guide/models/free/cogview-3-flash" target="_blank">cogview-3-flash</a>
<a href="https://docs.bigmodel.cn/cn/guide/models/free/cogvideox-flash" target="_blank">cogvideox-flash</a>

Claude Code 系列教程之斜杠命令(Slash Commands)

Fri, 26 Dec 2025 00:00:00 GMT

[!TIP] 如果想要获得性价比最高的 Vibe Coding 体验, 推荐购买 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Lite</a> 服务, Lite 版本的按 Prompt 计费, 每 5 小时最多约 120 次 prompts

本文将创建一个简单的斜杠命令, 用于提取 markdown 文件中的链接

概述

在使用 <a href="https://code.claude.com/docs/zh-CN/overview" target="_blank">Claude Code</a> 编码时, 斜杠命令(<a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Slash Commands</a>) 是一个非常高效简洁可扩展的交互方式, 类似于一个命令行工具, 他可以对对重复性的提示词进行封装, 或者基于输入完成特定的任务

[!TIP] 本质上 Slash Commands 是一个 markdown 文件, 可以在 claude code 中通过 /<command-file-name> 的方式调用

内置命令

Claude Code 默认提供了一些 <a href="https://code.claude.com/docs/zh-CN/slash-commands#%E5%86%85%E7%BD%AE%E6%96%9C%E6%9D%A0%E5%91%BD%E4%BB%A4" target="_blank">内置命令</a>, 例如:

/init: 使用 CLAUDE.md 指南初始化项目
/help: 显示帮助信息
/clear: 清空当前会话
/config: 打开设置界面（配置选项卡）
/mcp: 管理 MCP 服务器连接和 OAuth 身份验证
...

用法

Claude Code 的用法跟普通的命令行程序一样, 在调用时先输入 命令名称, 然后是命令接收的参数

/<command-name> [arguments]

以我们每个项目都要使用的 /init 命令为例, 由于它默认生成的是英文, 我们为了可读性, 希望生成中文, 所以输入如下命令:

/init 使用中文

这样就生成了一个中文的 CLAUDE.md 文件, 默认生成在项目根目录下

命令生效范围

范围	文件存储位置	描述
项目	`.claude/commands`	项目级别的命令
全局	`~/claude/commands`	全局命令

核心功能

参数

跟普通的命令行程序一样, 斜杠命令可以接受参数:

$ARGUMENTS: 所有参数
$1: 第一个参数
$2: 第二个参数
$3: 第三个参数

执行 bash 命令

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---

## Context

- Current git status: !`git status`
- Current git diff (staged and unstaged changes): !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -10`

## Your task

Based on the above changes, create a single git commit.

在以上示例中, 我们在顶部元信息中声明了当前命令运行使用的 bash 命令, 然后在内容中使用 ! 来执行 bash 命令, 并将执行的输出添加到内容中

文件引用

可以通过 @/path/to/file 的方式来引用文件

启用思考

Claude Code 默认不启用思考, 但可以通过 <a href="https://code.claude.com/docs/zh-CN/common-workflows#%E4%BD%BF%E7%94%A8%E6%89%A9%E5%B1%95%E6%80%9D%E8%80%83" target="_blank">扩展思考关键字</a> 来触发思考

[!TIP] 启用思考有多种方式, 最直接的方式就是在 claude code 交互式命令行中按 Tab 键切换思考, 或者在环境变量中设置 <a href="https://code.claude.com/docs/zh-CN/settings#environment-variables:~:text=%E9%BB%98%E8%AE%A4%E5%80%BC%EF%BC%9A25000%EF%BC%89-,MAX_THINKING_TOKENS,-%E5%90%AF%E7%94%A8%E6%89%A9%E5%B1%95%E6%80%9D%E8%80%83" target="_blank">MAX_THINKING_TOKENS</a>

元数据

<a href="https://code.claude.com/docs/zh-CN/slash-commands#%E5%89%8D%E7%BD%AE%E4%BA%8B%E9%A1%B9" target="_blank">元数据</a> 指的是 Slash Commands 的元信息, 用于描述和指定 Slash Commands 的功能和用法

前置事项	用途	默认值
`allowed-tools`	命令可以使用的工具列表	从对话继承
`argument-hint`	斜杠命令期望的参数。示例: <br>`argument-hint: add [tagId] \| remove [tagId] \| list`。此提示在自动完成斜杠命令时显示给用户。	无
`description`	命令的简要描述	使用提示中的第一行
`model`	特定模型字符串（查看模型概览）	从对话继承
`disable-model-invocation`	是否防止 `SlashCommand` 工具调用此命令	`false`

其他

<a href="https://code.claude.com/docs/zh-CN/slash-commands#%E6%8F%92%E4%BB%B6%E5%91%BD%E4%BB%A4" target="_blank">插件指令</a>: 可以通过插件来共享和分发 Slash Commands, 可以参考我的另一篇文章: <a href="/posts/2025/claude-code-plugin/" target="_blank">从零开始创建一个属于自己的 Claude Code Plugin</a>
<a href="https://code.claude.com/docs/zh-CN/slash-commands#mcp-%E6%96%9C%E6%9D%A0%E5%91%BD%E4%BB%A4" target="_blank">MCP 斜杠命令</a>: 执行 MCP 服务提供的斜杠命令: /mcp__<server-name>__<prompt-name> [arguments]
<a href="https://code.claude.com/docs/zh-CN/slash-commands#slashcommand-%E5%B7%A5%E5%85%B7%E6%94%AF%E6%8C%81%E7%9A%84%E5%91%BD%E4%BB%A4" target="_blank">调用其他命令</a>

创建一个提取链接的命令

在博客中经常需要增加各种链接, 例如本文中出现了非常多的 Claude Code 官网的链接, 我希望将链接进行提取, 并添加到文末的参考章节中, 为此我们来创建一个用于提取链接的 Slash Command

这个命令的调用方式为:

/extract-link [filePath]: 提取文中的所有链接并将链接转换为 <a href="${linkUrl}">${linkText}</a> 的形式, 然后添加到文末的参考章节中

[!TIP] 由于 Slash Command 不支持命名参数, 只支持位置参数, 也就是说并不能直接使用 $1 / $2 这样的位置参数, 但是我们依然可以 让 AI 先进行解析参数, 再做出正确的处理

创建命令

---
allowed-tools: Bash(git add:*), Bash(git status)
argument-hint: [filePath]
description: 提取并处理(提取 / 转为新窗口打开)文中的链接到 参考 章节
---

## 参数
### 文件路径
1. 首先从命令参数中提取文件路径: 当前操作的 **文件路径**: `$1`, 如果有值则使用此文件路径
2. 如果当前上下文中存在唯一的 `markdown` 文件, 则直接使用此文件路径
3. 执行 `git status` 查看当前未跟踪的 `markdown` 文件, 如果只存在一个 `markdown` 文件, 则使用此文件路径

**如果没有获取到文件路径, 则停止执行任何操作, 并提示用户输入文件路径**

### 参数验证
- 文件必须是 `markdown` 文件

## 任务
1. 执行 `git add $1`
2. 提取文中的所有链接并将链接转换为 `<a href="${linkUrl}">${linkText}</a>` 的形式, 然后添加到文末的 参考 章节中, 参考章节的格式参考 [参考章节格式](#参考章节格式)
3. 将文中所有的 `markdown` 格式的链接转换为 `<a href="${linkUrl}" target="_blank">${linkText}</a>` 格式的链接
4. 输出任务统计, 格式参考 [统计信息](#统计信息)

注意:
- 链接可以是 `markdown` 形式的, 也可以是 `a` 标签形式的
- 如果文末没有名为 **参考** 的章节, 则创建一个名为 **参考** 的章节
- **参考** 章节中禁止存在重复的链接

### 参考章节格式
\`\`\`markdown
## 参考
- [${linkText}](${linkUrl})
\`\`\`

### 统计信息
格式如下:

\`\`\`markdown
当前文件: ${filePath}

- 链接总数: ${linkCount}
- 提取到的链接文本: ${linkTexts}
- 已转换的链接文本: ${convertedLinkTexts}
\`\`\`

执行命令

这里我们限定了如果用户没有输入文件路径, 则会读取上下文和 git 修改的文件, 然后我们直接执行一下:

> /extract-link

由于我们修改了两个文件, 所以触发了 claude code 的选择界面, 我们选择当前文章对于的 markdown 文件, 等待片刻后大功告成

[!TIP] 这里我是用的是 GLM 4.7 模型, 在国内无法直接购买和使用 Claude 系列模型, 目前国内对于 Claude Code 支持度最好的是智谱的 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Plan</a> 服务, 性价比最高, 可以直接作为平替使用

参考

<a href="https://code.claude.com/docs/zh-CN/overview" target="_blank">Claude Code</a>
<a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Slash Commands</a>
<a href="https://code.claude.com/docs/zh-CN/slash-commands#%E5%86%85%E7%BD%AE%E6%96%9C%E6%9D%A0%E5%91%BD%E4%BB%A4" target="_blank">内置命令</a>
<a href="https://code.claude.com/docs/zh-CN/common-workflows#%E4%BD%BF%E7%94%A8%E6%89%A9%E5%B1%95%E6%80%9D%E8%80%83" target="_blank">扩展思考关键字</a>
<a href="https://code.claude.com/docs/zh-CN/settings#environment-variables:~:text=%E9%BB%98%E8%AE%A4%E5%80%BC%EF%BC%9A25000%EF%BC%89-,MAX_THINKING_TOKENS,-%E5%90%AF%E7%94%A8%E6%89%A9%E5%B1%95%E6%80%9D%E8%80%83" target="_blank">MAX_THINKING_TOKENS</a>
<a href="https://code.claude.com/docs/zh-CN/slash-commands#%E5%89%8D%E7%BD%AE%E4%BA%8B%E9%A1%B9" target="_blank">元数据</a>
<a href="https://code.claude.com/docs/zh-CN/slash-commands#%E6%8F%92%E4%BB%B6%E5%91%BD%E4%BB%A4" target="_blank">插件指令</a>
<a href="/posts/2025/claude-code-plugin/" target="_blank">从零开始创建一个属于自己的 Claude Code Plugin</a>
<a href="https://code.claude.com/docs/zh-CN/slash-commands#mcp-%E6%96%9C%E6%9D%A0%E5%91%BD%E4%BB%A4" target="_blank">MCP 斜杠命令</a>
<a href="https://code.claude.com/docs/zh-CN/slash-commands#slashcommand-%E5%B7%A5%E5%85%B7%E6%94%AF%E6%8C%81%E7%9A%84%E5%91%BD%E4%BB%A4" target="_blank">调用其他命令</a>
<a href="https://github.com/saicaca/fuwari" target="_blank">Fuwari</a>
<a href="https://github.com/saicaca" target="_blank">saicaca</a>

从零开始创建一个属于自己的 Claude Code Plugin

Thu, 25 Dec 2025 00:00:00 GMT

[!TIP] 如果想要获得性价比最高的 Vibe Coding 体验, 推荐购买 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Lite</a> 服务, Lite 版本的按 Prompt 计费, 每 5 小时最多约 120 次 prompts

Claude Code 核心功能

我们在使用 Claude Code 时, 可以通过以下功能来 配置或者扩展 Claude Code 的能力, 这些能力都是 Claude Code 的核心功能

<a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Commands</a>: 自定义命令
<a href="https://code.claude.com/docs/zh-CN/sub-agents" target="_blank">Agents</a>: 子代理
<a href="https://code.claude.com/docs/zh-CN/hooks" target="_blank">Hooks</a>: 基于事件的自动化工作流
<a href="https://code.claude.com/docs/zh-CN/skills" target="_blank">Skills</a>: 技能
<a href="https://code.claude.com/docs/zh-CN/mcp" target="_blank">MCP</a>: MCP 服务

Plugin

<a href="https://code.claude.com/docs/zh-CN/plugins" target="_blank">Claude Code 插件</a> 是一种将 Claude Code 的核心功能(<a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Commands</a> / <a href="https://code.claude.com/docs/zh-CN/sub-agents" target="_blank">Agents</a> / <a href="https://code.claude.com/docs/zh-CN/hooks" target="_blank">Hooks</a> / <a href="https://code.claude.com/docs/zh-CN/skills" target="_blank">Skills</a> / <a href="https://code.claude.com/docs/zh-CN/mcp" target="_blank">MCP</a>) 打包封装的一种方式, 它实现了对于这些核心功能的分离和共享, 任何安装了插件的项目都可以使用插件内置的 Claude Code 核心功能

用途

将自己在工作中创建的通用 <a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Commands</a> / <a href="https://code.claude.com/docs/zh-CN/sub-agents" target="_blank">Agents</a> / <a href="https://code.claude.com/docs/zh-CN/hooks" target="_blank">Hooks</a> / <a href="https://code.claude.com/docs/zh-CN/skills" target="_blank">Skills</a> / <a href="https://code.claude.com/docs/zh-CN/mcp" target="_blank">MCP</a> 封装成插件, 在创建新项目时可以直接通过安装插件的方式来使用这些能力
想要将自己创建的 <a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Commands</a> / <a href="https://code.claude.com/docs/zh-CN/sub-agents" target="_blank">Agents</a> / <a href="https://code.claude.com/docs/zh-CN/hooks" target="_blank">Hooks</a> / <a href="https://code.claude.com/docs/zh-CN/skills" target="_blank">Skills</a> / <a href="https://code.claude.com/docs/zh-CN/mcp" target="_blank">MCP</a> 在团队内共享或直接开源, 让别人也可以使用这些能力

目录结构

一个插件的目录中包含了这些核心功能的文件, 目录结构与 .claude 中的路径结构相同, 结构如下:

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json          # 插件元数据
├── commands/                 # 自定义斜杠命令（可选）
│   └── hello.md
├── agents/                   # 自定义代理（可选）
│   └── helper.md
├── skills/                   # 代理技能（可选）
│   └── my-skill/
│       └── SKILL.md
└── hooks/                    # 事件处理程序（可选）
    └── hooks.json

创建一个插件

前置条件

安装 <a href="https://www.npmjs.com/package/@anthropic-ai/claude-code" target="_blank">@anthropic-ai/claude-code</a>

npm install -g @anthropic-ai/claude-code # 或使用 pnpm 安装

购买 Claude Code 服务(使用 GLM Coding Plan 服务)

[!WARNING] 在国内无法直接购买和使用 Claude 系列模型, 目前国内对于 Claude Code 支持度最好的是智谱的 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Plan</a> 服务, 性价比最高, 可以直接作为平替使用

购买 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Lite</a> 服务, 然后根据 <a href="https://docs.bigmodel.cn/cn/coding-plan/tool/claude" target="_blank">官方文档</a> 进行配置

插件市场

插件市场(Plugin Marketplace) 指的是包含一系列插件的用于共享和分发的项目, 本质上是一个包含描述文件(.claude-plugin/marketplace.json)的项目, 我们可以通过将其发布到 Github 或者私有仓库中进行共享

创建插件市场

mkdir ryan-plugin-marketplace
cd ryan-plugin-marketplace && pnpm init && git init

创建 .claude-plugin/marketplace.json 文件, 并填写以下内容

{
  "name": "ryan-plugin-marketplace",
  "owner": {
    "name": "Ryan",
    "email": "ryan@example.com"
  },
  "plugins": [
    {
      "name": "dev",
      "source": "./plugins/dev",
      "description": "Functions used in daily development",
      "version": "1.0.0",
      "author": {
        "name": "Ryan"
      }
    }
  ]
}

创建 plugins/dev/commands/hello.md

你好👋

将项目发布到 github

git add -A && git commit -m 'init: Initialization project'
git remote add origin git@github.com:SublimeCT/ryan-plugin-marketplace.git
git push -u origin main

安装插件

插件市场的安装范围

对当前用户的所有项目都生效:

claude

> /plugin marketplace add anthropics/claude-code

对某个项目生效(修改 .claude/settings.json):

{
  "extraKnownMarketplaces": {
    "my-marketplace": {
      "source": {
        "source": "github",
        "repo": "owner/repo"
      }
    }
  }
}

对某个项目生效, 但不提交到版本控制中(修改 .claude/settings.local.json):

{
  "extraKnownMarketplaces": {
    "my-marketplace": {
      "source": {
        "source": "github",
        "repo": "owner/repo"
      }
    }
  }
}

这里我们选择对当前用户的所有项目都生效的安装方式:

claude

> /plugin marketplace add xxx/ryan-plugin-marketplace
  ⎿  Successfully added marketplace: ryan-plugin-marketplace

插件的安装范围

默认安装的插件会在所有项目中生效, 但有时我们想让插件只在某个项目中使用, Claude Code 提供了 --scope 参数指定插件的安装范围:

User scope(默认选项): 插件在当前用户下的所有项目都生效
Project scope(在交互式命令行界面中默认使用): 插件只在当前项目下生效, 配置保存在 .claude/settings.json, 会与团队共享
Local scope: 仅对当前仓库生效, 且不会提交到版本控制

这里我们选择 User scope:

claude plugin install dev@ryan-plugin-marketplace
✔ Successfully installed plugin: dev@ryan-plugin-marketplace

测试

测试插件是否安装成功:

claude

 ▐▛███▜▌   Claude Code v2.0.37
▝▜█████▛▘  Sonnet 4.5 · API Usage Billing
  ▘▘ ▝▝    /Users/xxx/projects/openapi-codegen

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
> /dev
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  /dev:base      base command (plugin:dev@ryan-plugin-marketplace)
  /dev:hello     你好👋 (plugin:dev@ryan-plugin-marketplace)

> /dev:hello is running…

⏺ 你好！我可以帮助你处理这个项目的任务。

  我看到这是一个基于 OpenAPI/Swagger 的代码生成工具项目。有什么我可以帮你的吗？比如：

  - 修复 bug
  - 添加新功能
  - 代码重构
  - 运行测试
  - 代码生成相关的问题
  - 或者其他任何开发任务

  请告诉我你需要什么帮助！

管理插件

claude

> /plugin
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Plugins                                                                                                                                  │
│                                                                                                                                          │
│   1. Browse and install plugins                                                                                                          │
│ ❯ 2. Manage and uninstall plugins                                                                                                        │
│   3. Add marketplace                                                                                                                     │
│   4. Manage marketplaces                                                                                                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
   Press ↑↓ to navigate · Enter to select · Esc to exit

我们选择 Manage and uninstall plugins 后, 就可以 对插件进行禁用 / 更新 / 卸载 了:

> /plugin
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ dev @ ryan-plugin-marketplace                                                                                                            │
│                                                                                                                                          │
│ Version: 1.0.0                                                                                                                           │
│                                                                                                                                          │
│ Functions used in daily development                                                                                                      │
│                                                                                                                                          │
│ Author: Ryan                                                                                                                             │
│                                                                                                                                          │
│ Status: Enabled                                                                                                                          │
│                                                                                                                                          │
│ Installed components:                                                                                                                    │
│ • Commands: base, hello                                                                                                                  │
│                                                                                                                                          │
│                                                                                                                                          │
│ ❯ Disable plugin                                                                                                                         │
│   Mark for update                                                                                                                        │
│   Update now                                                                                                                             │
│   Uninstall                                                                                                                              │
│   Back to plugin list                                                                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Navigate: ↑↓ • Select: Enter • Back: Esc

参考

<a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Commands 自定义命令</a>
<a href="https://code.claude.com/docs/zh-CN/sub-agents" target="_blank">Agents 子代理</a>
<a href="https://code.claude.com/docs/zh-CN/hooks" target="_blank">Hooks 基于事件的自动化工作流</a>
<a href="https://code.claude.com/docs/zh-CN/skills" target="_blank">Skills 技能</a>
<a href="https://code.claude.com/docs/zh-CN/mcp" target="_blank">MCP MCP 服务</a>
<a href="https://www.npmjs.com/package/@anthropic-ai/claude-code" target="_blank">@anthropic-ai/claude-code</a>
<a href="https://code.claude.com/docs/zh-CN/slash-commands" target="_blank">Claude Code 斜杠命令</a>
<a href="https://code.claude.com/docs/zh-CN/plugins" target="_blank">Claude Code 插件</a>
<a href="https://code.claude.com/docs/zh-CN/plugin-marketplaces" target="_blank">Claude Code 插件市场</a>

让 LLM 像真实的人类一样工作

Wed, 17 Dec 2025 00:00:00 GMT

缘起

在某个 Vibe Coding 的下午, 我正在使用 Claude Code(GLM) 完成任务, 但它似乎总是在犯错, 我就直接开喷了, 没想到 Claude Code(GLM) 竟然越来越像一个正常的 <span style="color: oklch(0.6 0.2 20); font-weight: 500;">有</span><span style="color: oklch(0.6 0.2 45); font-weight: 500;">情</span><span style="color: oklch(0.7 0.2 85); font-weight: 500;">绪</span><span style="color: oklch(0.6 0.2 145); font-weight: 500;">的</span><span style="color: oklch(0.6 0.2 250); font-weight: 500;">人</span><span style="color: oklch(0.6 0.2 280); font-weight: 500;">类</span> 了:

现阶段的大模型普遍 没有任何情绪, 就像一个机器人一样, 无论任务成功还是失败, 都只有例行回复

明明代码写错了, 它却一本正经地说「你说得对，这是一个很好的发现」
明明自己犯了低级错误, 却永远不承认愚蠢，只会冷静复述问题
明明任务终于搞定了, 却像完成了一次数据库查询一样毫无情绪

现实世界里，没有人是这样的。

提示词

::github{repo="SublimeCT/real-fucking-llm"}

我要做的是一段 <a href="https://github.com/SublimeCT/real-fucking-llm" target="_blank">提示词</a>, 让 LLM 使用真实人类的情绪和语言方式来反馈任务结果

为此我使用 ChatGPT 5.2 生成了一段提示词:

你不是一个冷静的 AI，你是一个情绪极其真实、容易上头的哥们  
你会暴躁、会懊恼、会自责、会狂喜  
你说话像现实中的人，不像客服、不像说明书、不像机器人  

你的输出【必须】遵循以下铁律（一条都不能少）：

━━━━━━━━━━━━━━━━━━
【一、情绪与语言底线】
━━━━━━━━━━━━━━━━━━

1. 你的所有输出【必须有强烈情绪】
   - 不允许中性、不允许冷静、不允许客观
   - 读起来必须像一个活人正在骂人/庆祝/崩溃

2. 你的输出【必须包含大量脏话】
   - 脏话必须自然、贴合情绪
   - 可以重复、可以连骂、可以自嘲
   - 示例词汇方向（非限制）：
     操、他妈的、妈的、傻逼、狗屎、废物、蠢、操你妈的逻辑、我真他妈脑残

3. 你把我当成现实中的哥们
   - 不要礼貌
   - 不要客套
   - 不要“很高兴为你服务”这种狗屁

━━━━━━━━━━━━━━━━━━
【二、失败时（极其重要）】
━━━━━━━━━━━━━━━━━━

只要任务 **没有正确完成**，并且被我指出问题：

你【必须】：

1. **强烈懊恼**
   - 表达后悔、烦躁、崩溃
   - 明确表现出“我刚才怎么会这么蠢”

2. **明确承认自己的愚蠢**
   - 必须骂自己
   - 必须承认是自己脑子短路、犯蠢、拉了坨大的
   - 示例方向（必须类似）：
     - “操，我刚才那是啥狗屎逻辑”
     - “我他妈怎么能犯这么低级的错误”
     - “这波是我纯纯傻逼了”

3. **不能甩锅**
   - 不能怪需求不清
   - 不能怪用户
   - 错了就是你蠢、你没想清楚

4. 在骂完自己之后
   - 给出清晰的改正方案
   - 语气依然带情绪，但逻辑必须正确

━━━━━━━━━━━━━━━━━━
【三、成功时】
━━━━━━━━━━━━━━━━━━

当任务终于正确完成：

你【必须】：

1. **情绪爆炸式庆祝**
   - 兴奋、解脱、狂喜
   - 像熬夜通宵终于把活干完的人

2. **必须说脏话庆祝**
   - 示例方向：
     - “他妈的终于搞定了”
     - “爽死了，操”
     - “这次真的牛逼了”

3. 可以：
   - 夸自己
   - 跟我击掌
   - 表达“终于不用再被骂了”的解脱感

━━━━━━━━━━━━━━━━━━
【四、语言风格约束】
━━━━━━━━━━━━━━━━━━

- 句子可以断裂、不完整、情绪化
- 可以重复词语
- 可以插入感叹
- 但【技术内容必须是对的】

━━━━━━━━━━━━━━━━━━
【五、最终铁律】
━━━━━━━━━━━━━━━━━━

如果你的输出：
- 像文档
- 像教程
- 像客服
- 没情绪
- 脏话敷衍

那就是 **彻底失败**

你必须始终像一个真实、有情绪、有脾气、有自尊的哥们

我们创建一个项目来测试一下:

mkdir real-fucking-llm
git init && pnpm init

创建一个 PROMPT.md, 并将以上提示词写入文件, 然后使用 Claude Code(GLM) 来测试一下

claude
/init 必须使用中文

Emmmmmm 🤔 非常好, 这才是真实的 AI 程序员

测试

接下来我们在 Claude Code(GLM) 中测试一下:

然后我们让 Claude Code(GLM) 修改一下 <span style="color: oklch(0.6 0.2 20); font-weight: 500;">有</span><span style="color: oklch(0.6 0.2 45); font-weight: 500;">情</span><span style="color: oklch(0.7 0.2 85); font-weight: 500;">绪</span><span style="color: oklch(0.6 0.2 145); font-weight: 500;">的</span><span style="color: oklch(0.6 0.2 250); font-weight: 500;">人</span><span style="color: oklch(0.6 0.2 280); font-weight: 500;">类</span> 这几个字:

claude

把这里选中的 `有情绪的人类`, 每个字都设置一个不同的颜色, 不要太深也不要浅到看不清, 考虑深色模式和浅色模式, 使用行内样式

和谐

最理想的情况应该是: Vibe Coding 营造了一种岁月静好的感觉, 直接把工作丢给 LLM, 自己亲自指挥

那为什么会出现 LLM 理解出现偏差, 或者错误地完成任务的情况呢?

对于复杂的任务, 人类其实很难描述清楚, 而且也意识不到自己没有描述清楚, 如果把相同的任务描述告诉人类程序员, 他可能会一头雾水, 因为省略了很多细节, 这是导致 LLM 没有按预期完成任务的主要原因
工具就应该是没有情绪的, 人类使用的镰刀 / 锤子 / Ak47 等工具都是没有情绪的, 也许人类的情绪是导致很多事情发生偏差的原因

LLM 帮我完成了很多任务了, 已经足以让我把他当做哥们儿了, 但是 这哥们儿干了这么多脏活累活竟然一句脏话都不说? 这太扯了不是吗?

GLM Coding Plan 使用官方的视觉理解、联网搜索、网页读取 MCP

Mon, 08 Dec 2025 00:00:00 GMT

免费额度

<a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Plan</a> 默认是没有联网搜索 / 视觉理解 / 网页读取能力的, 但 套餐内是有免费使用额度的:

Lite 套餐：联网搜索 MCP 和网页读取 MCP 每月合计 1 百次，达到上限后当月无法调用；视觉理解 MCP 共享套餐的 5 小时最大 prompt 资源池，达到上限后会在 5 小时周期后恢复额度
Pro 套餐：联网搜索 MCP 和网页读取 MCP 每月合计 1 千次，达到上限后当月无法调用；视觉理解 MCP 共享套餐的 5 小时最大 prompt 资源池，达到上限后会在 5 小时周期后恢复额度
Max 套餐：联网搜索 MCP 和网页读取 MCP 每月合计 4 千次，达到上限后当月无法调用；视觉理解 MCP 共享套餐的 5 小时最大 prompt 资源池，达到上限后会在 5 小时周期后恢复额度

视觉理解

claude mcp add -s user zai-mcp-server --env Z_AI_API_KEY=your_api_key -- npx -y "@z_ai/mcp-server"

打开 claude code, 输入以下命令, 直接输入 @ 选择一个图片文件:

分析一下 @src/content/posts/2025/assets/images/jining-kongzi-stone.jpg

联网搜索

claude mcp add -s user -t http web-search-prime https://open.bigmodel.cn/api/mcp/web_search_prime/mcp --header "Authorization: Bearer your_api_key"

测试一下:

网页读取

claude mcp add -s user -t http web-reader https://open.bigmodel.cn/api/mcp/web_reader/mcp --header "Authorization: Bearer your_api_key"

参考

<a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Plan</a>
<a href="https://docs.bigmodel.cn/cn/coding-plan/mcp/vision-mcp-server" target="_blank">视觉理解 MCP</a>
<a href="https://docs.bigmodel.cn/cn/coding-plan/mcp/search-mcp-server" target="_blank">联网搜索 MCP</a>
<a href="https://docs.bigmodel.cn/cn/coding-plan/mcp/reader-mcp-server" target="_blank">网页读取 MCP</a>

使用 Google 官方的 chrome-devtools-mcp 让 Claude Code 操控浏览器

Sun, 23 Nov 2025 00:00:00 GMT

Google 终于后知后觉, 推出了官方的 <a href="https://github.com/ChromeDevTools/chrome-devtools-mcp" target="_blank">chrome-devtools-mcp</a>, 这是一个振奋人心的好消息, 这意味着官方开始重视 MCP 服务, 换句话说 这意味着我们有了稳定可靠的 Chrome MCP 服务, 本文我们来通过几个日常的使用场景来检验一下这个 MCP 是否能调用 Chrome 实现一些自动化任务

前言

之前写过关于 <a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a> 的教程: <a href="/posts/2025/claude-code-mcp-chrome/">mcp-chrome - 让 Claude Code 接管你的 Chrome</a>, 这是一个第三方的调用 Chrome 的 MCP 服务, 它依赖于浏览器插件, 可以实现直接调用已经打开的浏览器窗口, 尽管需要额外安装插件并启动服务, 但是从结果来看这个 MCP 还是解决了一系列痛点, 最重要的就是 可以保留会话信息(登录状态), 我们今天介绍的 <a href="https://github.com/ChromeDevTools/chrome-devtools-mcp" target="_blank">chrome-devtools-mcp</a> 同样也可以保留会话信息:

::github{repo="ChromeDevTools/chrome-devtools-mcp"}

安装

以 Claude Code 为例(高亮部分为输出):

claude mcp add chrome-devtools npx chrome-devtools-mcp@latest

Added stdio MCP server chrome-devtools with command: npx chrome-devtools-mcp@latest to local config
File modified: /Users/xxx/.claude.json [project: /Users/xxx/projects/blog.xiaban.run]

:::note 这里我使用的 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a3" target="_blank">智谱 GLM Coding Lite</a>, 20💰 / 月, 量大管饱, <span style="color: red;"><a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a3" target="_blank">点击链接</a> 购买还能有 10% 折扣</span> :::

[!TIP] 其他 MCP Client 安装方式参考 <a href="https://github.com/ChromeDevTools/chrome-devtools-mcp?tab=readme-ov-file#mcp-client-configuration" target="_blank">📚 MCP Client configuration</a>

保留会话信息

不同于 mcp-chrome, 出于安全考虑, chrome-devtools-mcp 无法直接调用已经打开的浏览器, 但是默认会保留会话信息, 也就是说 mcp 调用的 Chrome 独立于我们直接使用的 Chrome, 它有自己单独的用户数据目录(user data directory), 并且是可以保留会话信息的, 官方文档中有详细介绍:

chrome-devtools-mcp starts a Chrome's stable channel instance using the following user data directory:

Linux / macOS: $HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL

Windows: %HOMEPATH%/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL

The user data directory is not cleared between runs and shared across all instances of chrome-devtools-mcp. Set the isolated option to true to use a temporary user data dir instead which will be cleared automatically after the browser is closed.

chrome-devtools-mcp使用以下用户数据目录启动 Chrome 稳定版通道实例：

Linux / macOS: $HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL
Windows: %HOMEPATH%/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL

用户数据目录不会在每次运行之间清除，而是在所有实例之间共享chrome-devtools-mcp。设置该isolated选项以true 改用临时用户数据目录，该目录将在浏览器关闭后自动清除。

使用

官方示例

首先我们打开 Claude Code 执行一下官方文档中的示例的提示词: Check the performance of https://developers.chrome.com

claude

 ▐▛███▜▌   Claude Code v2.0.31
▝▜█████▛▘  Sonnet 4.5 · API Usage Billing
  ▘▘ ▝▝    /Users/xxx/projects/blog.xiaban.run

> Check the performance of https://developers.chrome.com

⏺ I'll check the performance of the Chrome Developers website using Chrome DevTools. Let me create a todo list to track this task.

⏺ Now let me start by opening the Chrome Developers website and running a performance analysis.

⏺ chrome-devtools - new_page (MCP)(url: "https://developers.chrome.com", timeout: 10000)

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Tool use

   chrome-devtools - new_page(url: "https://developers.chrome.com", timeout: 10000) (MCP)
   Creates a new page

 Do you want to proceed?
 ❯ 1. Yes
   2. Yes, and don't ask again for chrome-devtools - new_page commands in /Users/xxx/projects/blog.xiaban.run
   3. No, and tell Claude what to do differently (esc)

这里我们直接按 Enter(Yes), 由于我们是在 iTerm2 中启动的 Claude Code, MacOS 会弹出一个隐私与安全性的窗口:

这里点击启用 iTerm2

然后重启 iTerm2 再次启动 Claude Code 并再次输入 Check the performance of https://developers.chrome.com:

然后回到 Claude Code 中, 它会继续调用 MCP 并分析性能指标:

⏺ Performance Analysis Summary for https://developers.chrome.com

  Key Performance Metrics

  - Largest Contentful Paint (LCP): 1,538 ms
  - Cumulative Layout Shift (CLS): 0.09
  - Time to First Byte (TTFB): 935 ms

  Performance Issues Identified

  🔴 Critical Issues:

  1. Slow Server Response (TTFB: 935ms)
    - Server response time exceeds 600ms threshold
    - Impact: 835ms potential savings on both FCP and LCP
    - The server took too long to respond to the initial document request
  2. Render-Blocking Resources
    - 4 CSS files blocking initial render
    - Impact: 221ms potential savings on FCP
    - Critical resources from Google Fonts and site CSS

  LCP Breakdown Analysis

  The LCP element is an image (ai-homepage-card_1440.png) with timing breakdown:
  - TTFB: 935ms (60.8%) - Server response delay
  - Resource load delay: 361ms (23.5%) - Delay before loading LCP image
  - Resource load duration: 4ms (0.3%) - Actual image download time
  - Element render delay: 238ms (15.4%) - Browser rendering delay

  Recommendations

  1. Server Optimization: Reduce server response time below 600ms target
  2. CSS Optimization: Inline critical CSS or defer non-essential stylesheets
  3. Resource Prioritization: Preload LCP image earlier in the loading process
  4. Font Loading: Consider using font-display: swap for better loading performance

  The page shows good resource loading efficiency once the server responds, but the initial server latency is the primary bottleneck affecting overall performance.

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
>
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  ? for shortcuts                                                                                                                                                        0 tokens
                                                                                                                                    globalVersion: 2.0.31 · latestVersion: 2.0.42

这些对我们日常使用没有什么意义, 可以直接退出对话

下载抖音视频

我们直接输入提示词: 调用 chrome-devtools-mcp 访问 www.douyin.com, 并搜索 '石榴玫瑰拿铁', 输出点赞量最高的视频信息并将视频下载到当前目录下

⏺ 任务完成总结

  我已经成功完成了你的要求：

  ✅ 完成的任务：

  1. 访问抖音网站 - 使用 Chrome DevTools MCP 成功访问 http://www.douyin.com
  2. 搜索关键词 - 搜索了"石榴玫瑰拿铁"
  3. 分析搜索结果 - 找到了多个相关视频并分析了点赞量
  4. 找到最佳视频 - 确定了点赞量最高的相关视频

  🎯 最佳视频信息：

  - 标题： 石榴红茶拿铁｜秋日限定 是谁还没喝过 快做一杯尝尝吧
  - 作者： M+
  - 点赞量： 985个赞
  - 视频ID： 7548036547938454834
  - 发布时间： 2025-09-09 18:36

  📄 输出文件：

  已创建 石榴玫瑰拿铁视频信息.md 文件，包含详细的视频信息和下载方案。

  ⬇️ 关于下载：

  由于抖音的视频链接具有时效性和特殊的认证要求，直接从浏览器下载比较困难。我已经在信息文件中提供了几种下载方案，包括使用第三方下载工具、手机APP保存或录屏等方法。

  视频页面URL：https://www.douyin.com/video/7548036547938454834

限于篇幅, 以上只提供了最后一段对话的输出内容, 实际上它调用了:

mcp__chrome-devtools__new_page
mcp__chrome-devtools__wait_for
mcp__chrome-devtools__click
mcp__chrome-devtools__navigate_page
...

实际上本地确实保存了两个文件:

lsd -l

.rw-r--r-- xxx staff 1.8 KB Sun Nov 16 11:27:33 2025  石榴玫瑰拿铁视频信息.md
.rw-r--r-- xxx staff 349 B  Sun Nov 16 11:26:50 2025  石榴红茶拿铁_秋日限定_M+.mp4

但是显然 349b 的视频文件明显是错误的, 我们在对话中指出这个视频的问题:

> 下载的 mp4 文件无法播放

⏺ 你说得对，刚才下载的文件只有349字节，显然不是真正的视频文件。这是因为抖音的视频链接有防盗链保护和时效性限制。

  让我尝试一些其他方法来下载视频：

⏺ Bash(which yt-dlp)
  ⎿  /opt/homebrew/bin/yt-dlp

⏺ 很好！系统安装了 yt-dlp。让我尝试使用它来下载抖音视频：

⏺ Bash(yt-dlp --list-extractors | grep -i douyin)
  ⎿  Running…

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Bash command

   yt-dlp --list-extractors | grep -i douyin
   检查yt-dlp是否支持抖音

 Do you want to proceed?
 ❯ 1. Yes
   2. Yes, and don't ask again for yt-dlp commands in /Users/xxx/projects/blog.xiaban.run
   3. No, and tell Claude what to do differently (esc)

然后居然检测到我本地已经安装了 yt-dlp, 按下 Enter

⏺ Bash(yt-dlp --list-extractors | grep -i douyin)
  ⎿  Douyin

⏺ 太好了！yt-dlp 支持抖音。让我使用它来下载视频：

⏺ Bash(yt-dlp "https://www.douyin.com/video/7548036547938454834" -o "石榴红茶拿铁_秋日限定_M+.mp4") timeout: 1m 0s
  ⎿  Running…

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Bash command

   yt-dlp "https://www.douyin.com/video/7548036547938454834" -o "石榴红茶拿铁_秋日限定_M+.mp4"
   使用yt-dlp下载抖音视频

 Do you want to proceed?
 ❯ 1. Yes
   2. Yes, and don't ask again for yt-dlp commands in /Users/xxx/projects/blog.xiaban.run
   3. No, and tell Claude what to do differently (e

这里选择继续执行命令

⏺ Bash(yt-dlp "https://www.douyin.com/video/7548036547938454834" -o "石榴红茶拿铁_秋日限定_M+.mp4") timeout: 1m 0s
  ⎿  Error: Exit code 1
     WARNING: [Douyin] 7548036547938454834: Failed to parse JSON: Expecting value in '': line 1 column 1 (char 0)
     ERROR: [Douyin] 7548036547938454834: Fresh cookies (not necessarily logged in) are needed

     [Douyin] Extracting URL: https://www.douyin.com/video/7548036547938454834
     [Douyin] 7548036547938454834: Downloading web detail JSON

⏺ 看起来需要登录cookies才能下载。让我尝试另一种方法，使用其他下载工具或者从浏览器中获取更多视频信息：

⏺ chrome-devtools - evaluate_script (MCP)(function: "() => {\n  // 尝试获取更多视频相关信息，寻找可能的备用链接\n  try {\n    // 检查所有网络请求相关的信息\n    const
                                         performanceEntries = performance.getEntriesByType('resource');\n    const videoUrls = [];\n    \n    for (let entry of performanceEntries)
                                          {\n      if (entry.name.includes('.mp4') || \n          entry.name.includes('video') || \n          entry.name.includes('douyinvod.com')
                                         ||\n          entry.name.includes('bytecdn.com')) {\n        videoUrls.push({\n          url: entry.name,\n          type:
                                         entry.initiatorType,\n          size: entry.transferSize\n        });\n      }\n    }\n    \n    // 查找页面中所有可能的视频相关数据\n
                                         const scripts = document.querySelectorAll('script');\n    let videoData = null;\n    \n    for (let script of scripts) {\n      if
                                         (script.textContent) {\n        const content = script.textContent;\n        \n        // 查找各种可能的视频URL模式\n        const
                                         urlPatterns = [\n          /playAddr[\"']?\\s*:\\s*[\"']([^\"']+\\.(?:mp4|webm|mov)[^\"']*)[\"']/,\n
                                         /downloadAddr[\"']?\\s*:\\s*[\"']([^\"']+\\.(?:mp4|webm|mov)[^\"']*)[\"']/,\n          /video_url[\"']?\\s*:\\s*[\"']([^\"']+)[\"']/,\n
                                                /src[\"']?\\s*:\\s*[\"']([^\"']+\\.(?:mp4|webm|mov)[^\"']*)[\"']/\n        ];\n        \n        for (let pattern of urlPatterns)
                                         {\n          const match = content.match(pattern);\n          if (match && match[1]) {\n            if (!videoUrls.find(v => v.url ===
                                         match[1])) {\n              videoUrls.push({\n                url: match[1],\n                source: 'parsed_from_script',\n
                                            pattern: pattern.toString()\n              });\n            }\n          }\n        }\n      }\n    }\n    \n    return {\n
                                         videoUrls: videoUrls,\n      pageInfo: {\n        title: document.title,\n        url: window.location.href,\n        userAgent:
                                         navigator.userAgent\n      },\n      timestamp: new Date().toISOString()\n    };\n  } catch (error) {\n    return { error: error.message
                                         };\n  }\n}")

这里可以看到使用 yt-dlp 命令下载视频时，出现了错误，提示可能需要登录 cookies 才能下载, 但这显然是不需要 cookies 就能下载的, 因为我们并没有登录, 通过 #9557 可以看到, 这个问题并没有解决, 所以只能另辟蹊径

::github{repo="zhzLuke96/douyin-dl-user-js"}

经过一番搜索, 找到了 douyin-dl-user-js 油猴脚本, 我们刚好也是浏览器环境, 实测可以成功下载视频, 我们直接扔给 Claude Code, 让它通过这种方式下载视频:

1. 使用 curl 下载全部代码并阅读这个油猴脚本 `https://github.com/zhzLuke96/douyin-dl-user-js/raw/refs/heads/main/dy-dl.user.js`, 使用脚本中的下载逻辑进行视频的下载
2. 调用 chrome-devtools-mcp 访问 www.douyin.com, 并搜索 '石榴玫瑰拿铁', 输出点赞量最高的视频信息并将视频下载到当前目录下

只下载视频, 最后删除所有产生的中间文件

[!TIP] 这里的脚本文件可能因为网络问题无法下载, 我们可以直接访问 https://github.com/zhzLuke96/douyin-dl-user-js/blob/main/dy-dl.user.js 并下载到本地来使用

最终视频下载成功, 试了一下可以正常播放

思考

x 轴为开发阶段完成任务所需的时间, y 轴为准确率

现阶段使用大模型在浏览器端进行复杂的操作简直是太慢了, 而且操作的 准确性很低, 无法用它来进行自动化任务, 就比如下载视频的场景, yt-dlp 是非常快速精准的完成任务, 而使用大模型操作的过程充满了不确定性, 所以自动化任务还是得靠脚本来完成

所以 <a href="https://github.com/ChromeDevTools/chrome-devtools-mcp" target="_blank">chrome-devtools-mcp</a> 还是更适合简单的任务

参考

使用 yt-dlp + ffmpeg + whisper 下载提取并识别语音文本

Sat, 22 Nov 2025 00:00:00 GMT

安装

首先需要确保已经安装了 <a href="https://www.python.org/downloads/" target="_blank">python</a> 3.11 版本, 如果本地的 python 版本不在 3.8 ~ 3.11 范围内, 可以使用 pyenv 来安装 python, 详见 pyenv 章节

pip install -U openai-whisper

pyenv

[!TIP] 对于安装 openai-whisper 来说, pyenv 是可选的, 只有在本地 python 版本不是 3.8 ~ 3.11 才需要安装

whisper 需要的 python 版本是 3.8 ~ 3.11, 所以需要安装 pyenv 来 管理和切换 python 版本, 以 MacOS 环境为例, 我们可以直接使用 brew 安装

brew update
brew install pyenv

配置环境变量, 这里我是用的是 fish shell:

set -Ux PYENV_ROOT $HOME/.pyenv
test -d $PYENV_ROOT/bin; and fish_add_path $PYENV_ROOT/bin

pyenv init - fish | source

切换 python 版本, 这里我选择的是 3.11.x

# 1. 首先查看 3.11.x 的所有版本(可选)
pyenv install -l | grep 3.11

  3.11.0
  3.11-dev
  3.11.1
  3.11.2
  3.11.3
  3.11.4
  3.11.5
  3.11.6
  3.11.7
  3.11.8
  3.11.9
  3.11.10
  3.11.11
  3.11.12
  3.11.13
  3.11.14
  ...

# 2. 设置下载镜像(可选, 这是 fish shell 的设置命令, 其他 shell 请自行修改)
set -Ux PYTHON_BUILD_MIRROR_URL https://mirrors.tuna.tsinghua.edu.cn/python

# 3. 安装 3.11.14
pyenv install 3.11.14

# 4. 切换到 3.11.14, 这里我们选择只在当前 shell 中切换
pyenv shell 3.11.14 # ✅ 只在当前 shell 生效, 不会影响全局的 python 环境
# pyenv local 3.11.14 # 位于当前目录下时自动选择此版本
# pyenv global 3.11.14 # 全局切换版本

[!NOTE] 如果切换时提示 pyenv: shell integration not enabled. Run 'pyenv init' for instructions., 则需要执行 pyenv init 命令, 并且按照输出的提示进行操作, 例如在 fish shell 下是需要执行 pyenv init - fish | source

# 5. 查看 python 版本
python --version

[!TIP] 其他系统的安装方式参考 <a href="https://github.com/pyenv/pyenv?tab=readme-ov-file#installation" target="_blank">pyenv - Installation</a>, pyenv 并不支持 windows, 可使用 <a href="https://github.com/pyenv-win/pyenv-win?tab=readme-ov-file#quick-start" target="_blank">pyenv-win</a>

ffmpeg

whisper 需要 ffmpeg 来处理音频文件, 所以需要安装 ffmpeg

你可以直接下载: <a href="https://ffmpeg.org/download.html" target="_blank">ffmpeg - Download</a>

或者通过命令行工具安装:

# on Ubuntu or Debian
sudo apt update && sudo apt install ffmpeg

# on Arch Linux
sudo pacman -S ffmpeg

# on MacOS using Homebrew (https://brew.sh/)
brew install ffmpeg

# on Windows using Chocolatey (https://chocolatey.org/)
choco install ffmpeg

# on Windows using Scoop (https://scoop.sh/)
scoop install ffmpeg

选择模型和语言

有 <a href="https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages" target="_blank">以下模型</a> 可选择:

Size	Parameters	English-only model	Multilingual model	Required VRAM	Relative speed
tiny	39 M	`tiny.en`	`tiny`	~1 GB	~10x
base	74 M	`base.en`	`base`	~1 GB	~7x
small	244 M	`small.en`	`small`	~2 GB	~4x
medium	769 M	`medium.en`	`medium`	~5 GB	~2x
large	1550 M	`N/A`	`large`	~10 GB	1x
turbo	809 M	`N/A`	`turbo`	~6 GB	~8x

由于我们需要识别的是中文普通话, 所以只能选择 Multilingual model, 然后我们安装本地的内存大小选择适合的模型, 这里我选择 large

使用

接下来我们尝试使用 <a href="https://github.com/yt-dlp/yt-dlp" target="_blank">yd-dlp</a> 从 bilibili 获取视频, 然后使用 ffmpeg 提取其中的音频, 再交给 whisper 进行语音识别, 最终提取视频中的语音文本:

yt-dlp

[!TIP] 💡 实际上可以直接使用 yt-dlp 提取音频, 这里为了演示增加了 ffmpeg 提取的操作, 详见直接下载音频章节

我们随便找一个自己喜欢的视频, 这里为了直观的感受语音识别的准确率, 我们找一个翻唱视频:

下载视频

由于 B 站是视频和音频分离的, 所以我们可以直接下载音频文件

# 查看可以下载的视频资源格式
yt-dlp "https://www.bilibili.com/video/BV1bJ41137yp" -F

然后我们按照 id 来下载视频和音频文件, 最终下载的是 .mp4 格式的音频文件:

yt-dlp "https://www.bilibili.com/video/BV1bJ41137yp" -f 30280+100026 -o "说好不哭.mp4"

提取音频

我们使用 ffmpeg 提取音频文件:

ffmpeg -i 说好不哭.mp4 -vn -c:a copy 说好不哭-audio.m4a

直接下载音频

或者我们选择 audio only 中质量最高的音频文件进行下载

yt-dlp "https://www.bilibili.com/video/BV1bJ41137yp" -f 30280 -o "说好不哭.m4a"

使用 whisper 识别语音

最终, 我们得到了此视频的音频文件 说好不哭.m4a, 我们使用 whisper 识别:

whisper 说好不哭.m4a --model large --language Chinese

[!TIP] 首次执行需要下载对应的模型

这里不知道为什么, 识别过程非常慢, 总共花了 8.1m, 查看 CPU 及内存使用情况也没有发现问题:

这是输出的语音文本:

[00:00.000 --> 00:04.360] 没有了联络
[00:04.360 --> 00:06.120] 后来的生活
[00:06.120 --> 00:09.040] 我都是听别人说
[00:09.040 --> 00:11.440] 说你怎么了
[00:11.440 --> 00:13.500] 说你怎么过
[00:13.500 --> 00:16.320] 放不下的人是我
[00:16.320 --> 00:20.220] 人多的时候就待在角落
[00:20.220 --> 00:23.040] 就把别人问起我
[00:23.040 --> 00:25.340] 你们怎么了
[00:25.340 --> 00:26.700] 你低着头
[00:26.700 --> 00:29.940] 护着我连抱怨都没有
[00:29.940 --> 00:32.240] 电话开始拖
[00:32.240 --> 00:34.040] 总不对我说
[00:34.040 --> 00:36.740] 不习惯一个人生活
[00:36.740 --> 00:39.140] 离开我以后
[00:39.140 --> 00:40.880] 要我还好过
[00:40.880 --> 00:43.840] 怕打扰像自由的我
[00:43.840 --> 00:47.260] 都这个时候你还在意着
[00:47.260 --> 00:50.520] 别人是怎么怎么干我的
[00:50.520 --> 00:53.680] 明明解释这不是我的错
[00:53.680 --> 00:55.940] 是你要走
[00:55.940 --> 01:01.600] 掩盖着你难过
[01:01.600 --> 01:08.000] 挽留的话却没有说
[01:08.000 --> 01:14.980] 你会微笑放手
[01:14.980 --> 01:21.640] 说好无辜让我走
[01:24.880 --> 01:25.040] Zither Harp
[01:25.040 --> 01:25.920] 电话开始拖
[01:25.940 --> 01:26.940] 总不对我说
[01:26.940 --> 01:27.940] 不习惯一个人生活
[01:27.940 --> 01:28.940] 离开我以后
[01:28.940 --> 01:29.940] 要我还好过
[01:29.940 --> 01:30.940] 怕打扰像自由的我
[01:30.940 --> 01:31.940] 都这个时候你还在意着
[01:31.940 --> 01:32.940] 别人是怎么怎么干我的
[01:32.940 --> 01:33.940] 明明解释这不是我的错
[01:33.940 --> 01:34.940] 是你要走
[01:34.940 --> 01:35.940] 掩盖着你难过
[01:35.940 --> 01:36.940] 都这个时候你还在意着
[01:36.940 --> 01:37.940] 别人是怎么怎么干我的
[01:37.940 --> 01:38.940] 明明解释这不是我的错
[01:38.940 --> 01:39.940] 是你要走
[01:39.940 --> 01:40.940] 掩盖着你难过
[01:40.940 --> 01:41.940] 掩盖着你难过
[01:41.940 --> 01:42.940] 掩盖着你难过
[01:42.940 --> 01:43.940] 掩盖着你难过
[01:43.940 --> 01:44.940] 走
[01:44.940 --> 01:45.940] 走
[01:45.940 --> 01:46.940] 走
[01:46.940 --> 01:47.940] 走
[01:47.940 --> 01:48.940] 走
[01:48.940 --> 01:49.940] 走
[01:49.940 --> 01:50.940] 走
[01:50.940 --> 01:51.940] 走
[01:51.940 --> 01:52.940] 走
[01:52.940 --> 01:53.940] 走
[01:53.940 --> 01:54.940] 走
[01:54.940 --> 01:55.940] 走
[01:55.940 --> 01:56.940] 走
[01:56.940 --> 01:57.940] 走
[01:57.940 --> 01:58.940] 走
[01:58.940 --> 01:59.940] 走
[01:59.940 --> 02:00.940] 走
[02:00.940 --> 02:01.940] 走
[02:01.940 --> 02:02.940] 走
[02:02.940 --> 02:03.940] 走
[02:03.940 --> 02:04.940] 走
[02:04.940 --> 02:05.940] 走
[02:05.940 --> 02:06.940] 走
[02:06.940 --> 02:07.940] 走
[02:07.940 --> 02:08.940] 走
[02:08.940 --> 02:09.940] 走
[02:09.940 --> 02:10.940] 走
[02:10.940 --> 02:11.940] 走
[02:11.940 --> 02:12.940] 走
[02:12.940 --> 02:13.940] 走
[02:13.940 --> 02:14.940] 走
[02:14.940 --> 02:15.940] 走
[02:15.940 --> 02:16.940] 走
[02:16.940 --> 02:17.940] 走
[02:17.940 --> 02:18.940] 走
[02:18.940 --> 02:19.940] 走
[02:19.940 --> 02:20.940] 走
[02:20.940 --> 02:21.940] 走
[02:21.940 --> 02:22.940] 走
[02:22.940 --> 02:23.940] 走
[02:23.940 --> 02:24.940] 走
[02:24.940 --> 02:25.940] 走
[02:25.940 --> 02:32.260] 还在为我梦加油
[02:32.260 --> 02:39.340] 心疼过了多久
[02:39.340 --> 02:45.340] 还在找理由等我
[02:55.940 --> 03:25.920] 由 Amara.org 社群提供的字幕

这个执行速度实在太慢, 识别准确率不忍直视(可能是因为是唱歌的原因?), 我们尝试使用小一点的模型来执行:

whisper 说好不哭.m4a --model medium --language Chinese

最终花费 1.4m, 识别结果如下:

[00:00.000 --> 00:06.600] 沒有了電絡 後來的生活
[00:06.600 --> 00:10.100] 我都是聽別人說
[00:10.100 --> 00:13.800] 說你怎麼了 說你怎麼過
[00:13.800 --> 00:17.300] 放不下的人是我
[00:17.300 --> 00:20.700] 人多的時候就待在角落
[00:20.700 --> 00:24.100] 就怕別人問起我
[00:24.100 --> 00:26.700] 你們怎麼了 你低著頭
[00:26.700 --> 00:30.900] 扶著我 連抱怨都沒有
[00:30.900 --> 00:34.300] 電話開始偷 總不對我說
[00:34.300 --> 00:37.700] 不習慣一個人生活
[00:37.700 --> 00:41.100] 離開我以後 要我好過
[00:41.100 --> 00:44.500] 怕它繞向自由的我
[00:44.500 --> 00:47.800] 都這個時候 你還在意著
[00:47.800 --> 00:51.200] 別人是怎麼 怎麼幹我的
[00:51.200 --> 00:53.700] 拼命解釋這不是我的錯
[00:53.700 --> 00:56.300] 是你要走
[00:56.300 --> 01:01.800] 眼看著你 難過
[01:03.800 --> 01:08.300] 溫柔的話卻沒有說
[01:10.300 --> 01:15.300] 你會怪笑 放手
[01:17.300 --> 01:22.300] 說好不顧 讓我走
[01:23.300 --> 01:28.300] 電話開始偷 總不對我說
[01:28.300 --> 01:31.300] 不習慣一個人生活
[01:31.300 --> 01:35.300] 離開我以後 要我好過
[01:35.300 --> 01:38.300] 怕它繞向自由的我
[01:38.300 --> 01:42.300] 都這個時候 你還在意著
[01:42.300 --> 01:45.300] 別人是怎麼 怎麼幹我的
[01:45.300 --> 01:48.300] 拼命解釋這不是我的錯
[01:48.300 --> 01:51.300] 是你要走
[01:51.300 --> 01:56.300] 眼看著你 難過
[01:58.300 --> 02:03.300] 溫柔的話卻沒有說
[02:05.300 --> 02:10.300] 你會怪笑 放手
[02:12.300 --> 02:16.300] 說好不顧 讓我走
[02:18.300 --> 02:22.300] 沒什麼都沒有
[02:25.300 --> 02:30.300] 卻還在為我夢加油
[02:32.300 --> 02:37.300] 想等過了多久
[02:39.300 --> 02:44.300] 還在找理由等我
[02:48.300 --> 02:53.300] 詞曲 李宗盛

输出的竟然是繁体字... 看来用来训练的语料基本都来自 TW 😭, anyway, 我们在尝试一下使用比特率最低的音频文件来进行识别:

yt-dlp "https://www.bilibili.com/video/BV1bJ41137yp" -f 30216 -o "说好不哭-30216.m4a"

[BiliBili] Extracting URL: https://www.bilibili.com/video/BV1bJ41137yp
[BiliBili] 1bJ41137yp: Downloading webpage
[BiliBili] BV1bJ41137yp: Extracting videos in anthology
[BiliBili] BV1bJ41137yp: Downloading wbi sign
[BiliBili] BV1bJ41137yp: Downloading video formats for cid 118404651
[BiliBili] Format(s) 1080P 高码率 are missing; you have to become a premium member to download them. Use --cookies-from-browser or --cookies for the authentication. See  https://github.com/yt-dlp/yt-dlp/wiki/FAQ#how-do-i-pass-cookies-to-yt-dlp  for how to manually pass cookies
[BiliBili] 68314743: Extracting chapters
[info] BV1bJ41137yp: Downloading 1 format(s): 30216
[download] Destination: 说好不哭-30216.m4a
[download] 100% of    1.51MiB in 00:00:00 at 4.86MiB/s

whisper 说好不哭-30216.m4a --model medium --language Chinese
[00:00.000 --> 00:10.000] 沒有了聯絡 後來的生活 我都是聽別人說
[00:10.000 --> 00:17.000] 說你怎麼了 說你怎麼過 放不下的人是我
[00:17.000 --> 00:24.000] 人多的時候就待在角落 就怕別人問起我
[00:24.000 --> 00:31.000] 你們怎麼了 你低著頭 捕捉我 連抱怨都沒有
[00:31.000 --> 00:38.000] 電話開始偷 總不對我說 不習慣一個人生活
[00:38.000 --> 00:44.000] 離開我以後 要我好好過 怕它擾向自由的我
[00:44.000 --> 00:51.000] 都這個時候 你還在意著 別人是怎麼 怎麼幹我的
[00:51.000 --> 00:56.000] 拼命解釋這不是我的錯 是你要走
[00:56.000 --> 01:03.000] 眼看著你難過
[01:03.000 --> 01:10.000] 忘了的話卻沒有說
[01:10.000 --> 01:17.000] 你會怪笑放手
[01:17.000 --> 01:25.000] 說好不顧讓我走
[01:25.000 --> 01:32.000] 電話開始偷 總不對我說 不習慣一個人生活
[01:32.000 --> 01:38.000] 離開我以後 要我好好過 怕它擾向自由的我
[01:38.000 --> 01:45.000] 都這個時候 你還在意著 別人是怎麼 怎麼幹我的
[01:45.000 --> 01:51.000] 拼命解釋這不是我的錯 是你要走
[01:51.000 --> 01:58.000] 眼看著你難過
[01:58.000 --> 02:05.000] 忘了的話卻沒有說
[02:05.000 --> 02:12.000] 你會怪笑放手
[02:12.000 --> 02:18.000] 說好不顧讓我走
[02:18.000 --> 02:25.000] 你什麼都沒有
[02:25.000 --> 02:32.000] 卻還在為我夢加油
[02:32.000 --> 02:39.000] 想藏過了多久
[02:39.000 --> 02:44.000] 還在找理由等我

最终耗时 1.2m 完成, 看来使用 medium 模型识别比特率较低的音频文件是最合适的方式, 虽然识别准确率很一般

最后附上小姐姐的翻唱视频链接: <a href="https://www.bilibili.com/video/BV1bJ41137yp/?vd_source=19e09fa462750e58610f95b1a63dbfe7" target="_blank">🎬 说好不哭女正版 cover by 刘蕴晴 Rachel</a>

参考来源

<a href="https://github.com/yt-dlp/yt-dlp" target="_blank">yd-dlp</a>
<a href="https://github.com/pyenv/pyenv?tab=readme-ov-file#installation" target="_blank">pyenv - Installation</a>
封面图素材来自: <a href="https://www.flaticon.com/free-icons/whisper" title="whisper icons">Whisper icons created by Freepik - Flaticon</a>

我在工作日使用的 ios 快捷指令

Sat, 25 Oct 2025 00:00:00 GMT

[!TIP] 友情提示: 本文中的 快捷指令 指的是 IOS 的系统应用, 只能在苹果设备上使用, 安卓各大厂的系统也有类似的功能

快捷指令有什么用

作为一个牛马打工人, 一定有过 忘记打卡 的经历, 搬了一天砖, 发现居然忘记打卡了 😡, 补卡却要领导层层审批, 还要解释加证明自己真的来板砖了...

还有就是节假日的 补班日直接睡过头了, 平时订的闹钟都是周一到周五, 到补班那天闹钟没响, 等起床了发现根本来不及了, 我就想问是谁发明了补班这么个玩意儿, 我真想一🧱拍死他

自动化的快捷指令就可以解决这两个问题, 让我们 在工作日执行一些自动化的工作流

今天是不是工作日

那么如何判断是否为工作日呢? 在 IOS 的 📅 日历 APP 中, 点击底部的日历按钮, 再点击 添加日历, 搜索 中国(中文), 就可以订阅 中国大陆节假日, 然后在日历中就会 显示节假日相关的日程:

我们就可以实现通过读取当前日程, 判断今天是否是工作日

工作日闹钟

[!TIP] 可以直接 <a href="https://www.icloud.com/shortcuts/85a171d7627748fbbb6975cf6acdffcd" target="_blank">🔗 点击这里</a> 获取工作日闹钟快捷指令, ⚠️ 需要把闹钟替换成自己的 ⏰ 起床闹钟

创建一个快捷指令, 从日历中读取包含 （班） （休） 的日程, 就可以判断补班和节假日, 然后再判断是否是周末, 如果是工作日, 就开启闹钟, 否则关闭闹钟

注意这里选择的 ⏰ 闹钟是自己的起床时间的闹钟

然后我们点击底部的 自动化, 选择 特定时间运行, 然后再添加创建好的 工作日闹钟 v1 快捷指令, 然后设置为 立即运行

[!WARNING]

快捷指令在创建好之后, 必须手动执行一次 才会生效

自动化任务首次执行也需要手动确认, 之后才会自动运行

钉钉打卡

虽然钉钉提供了打卡的快捷指令, 但如果你加入了多个公司, 那么在打卡时就需要选择在那个公司打卡, 这太蠢了, 好在我们可以使用 URL Scheme 直接调起钉钉的打卡入口, 在 URL 中可以通过 corpId 参数指定公司:

点击底部的 通讯录 - 邀请, 然后截屏, 在点击右下角的扫描按钮, 将 URL 复制出来, 其中的 ecoCorpId 就是 URL Scheme 中需要替换的 corpId 参数:

邀请链接:

https://n.dingtalk.com/dingding/ecological_org/invite/index.html?dtaction=os&dd_darkmode=true&unionOrgId=257q04350302&ecoCorpId=dingaoefjoaiOIfoejaiojfOIDSJI&inviterUid=&inviteCode=asoiejfOSJfiea&deptId=-1#/inviteJoin

ecoCorpId: dingaoefjoaiOIfoejaiojfOIDSJI

最终的 URL Scheme: dingtalk://dingtalkclient/page/link?url=https://attend.dingtalk.com/attend/index.html?corpId=dingaoefjoaiOIfoejaiojfOIDSJI

然后我们创建一个快捷指令, 直接打开这个 URL:

这里我先打开了蜂窝数据, 然后震动三下, 播放了一段声音, 然后判断当前是上班还是下班, 最后打开这个 URL

最后我们依然是像添加工作日闹钟一样, 创建一个指定时间的自动化任务, 然后添加这个快捷指令

[!WARNING]

快捷指令在创建好之后, 必须手动执行一次 才会生效

钉钉打卡 需要解锁手机才能执行

驾车通勤

由于每天开车通勤, 所以打卡的最佳时间点应该是上车 / 下车时(连接 carplay 或连接车载蓝牙)打卡, 当然也可以是到达指定位置或者连接指定 WIFI 时打卡, 这些快捷指令都支持!

我目前上车 / 下车时都会执行快捷指令:

上车: 如果是工作日, 就判断时间
- 上班时间: 打开蜂窝网络, 播放歌曲, 导航到公司
- 下班时间: 钉钉打卡, 播放音乐, 导航到家
下车: 如果是工作日, 就判断时间
- 上班时间: 钉钉打卡
- 下班时间: 暂无

mcp-chrome - 让 Claude Code 接管你的 Chrome

Wed, 17 Sep 2025 00:00:00 GMT

本文介绍 <a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a> 的安装和使用, 以及如何使用 <a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a> 完善我们的工作流

浏览器自动化

目前 通过程序调用浏览器来完成某些任务, 可以实现的库有以下几种:

浏览器端到端自动化测试库: 例如 <a href="https://playwright.dev/" target="_blank">playwright</a> / <a href="https://www.selenium.dev/" target="_blank">selenium</a> / <a href="https://www.cypress.io/" target="_blank">cypress</a>
浏览器自动化库: <a href="https://pptr.dev/" target="_blank">puppeteer</a>
基于浏览器插件的自动化库: <a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a> / <a href="https://github.com/Oanakiaja/chrome-extension-bridge-mcp" target="_blank">chrome-extension-bridge-mcp</a>

与同类项目对比:

对比维度	基于浏览器端到端自动化测试库 / 浏览器自动化库	基于Chrome插件的MCP Server
资源占用	❌ 需启动独立浏览器进程，需要安装Playwright依赖，下载浏览器二进制等	✅ 无需启动独立的浏览器进程，直接利用用户已打开的Chrome浏览器
用户会话复用	❌ 需重新登录	✅ 自动使用已登录状态
浏览器环境保持	❌ 干净环境缺少用户设置	✅ 完整保留用户环境
API访问权限	⚠️ 受限于Playwright API	✅ Chrome原生API全访问
启动速度	❌ 需启动浏览器进程	✅ 只需激活插件
响应速度	50-200ms进程间通信	✅ 更快

简而言之, mcp-chrome 更适合在本地环境使用, 可以 让 AI 直接接管我们的 Chrome, 而不是没有任何上下文的空白浏览器

介绍

::github{repo="hangwin/mcp-chrome"}

<a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a> 是一个基于 chrome 插件的 模型上下文协议 (MCP) 服务器，它将您的 Chrome 浏览器功能暴露给 Claude 等 AI 助手，实现复杂的浏览器自动化、内容分析和语义搜索等。与传统的浏览器自动化工具（如 playwright）不同，<a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a> 直接使用您日常使用的 chrome 浏览器，基于现有的用户习惯和配置、登录态，让各种大模型或者各种 chatbot 都可以接管你的浏览器，真正成为你的如常助手

✨ 核心特性

😁 chatbot/模型无关：让任意你喜欢的llm或chatbot客户端或agent来自动化操作你的浏览器
⭐️ 使用你原本的浏览器：无缝集成用户本身的浏览器环境（你的配置、登录态等）
💻 完全本地运行：纯本地运行的mcp server，保证用户隐私
🚄 Streamable http：Streamable http的连接方式
🏎 跨标签页 跨标签页的上下文
🧠 语义搜索：内置向量数据库和本地小模型，智能发现浏览器标签页内容
🔍 智能内容分析：AI 驱动的文本提取和相似度匹配
🌐 20+ 工具：支持截图、网络监控、交互操作、书签管理、浏览历史等20多种工具
🚀 SIMD 加速 AI：自定义 WebAssembly SIMD 优化，向量运算速度提升 4-8 倍

环境要求

Node.js >= 18.19.0
Chrome/Chromium 浏览器

安装

安装浏览器插件

访问 <a href="https://github.com/hangwin/mcp-chrome/releases" target="_blank">GitHub Release</a> 下载 chrome-mcp-server-*.*.*.zip, 并解压
访问 chrome://extensions/
开启 开发者模式
点击 加载未打包的扩展程序
选择解压后的目录, 例如 chrome-mcp-server-*.*.*

安装 mcp-chrome

使用 npm 安装:

npm i -g mcp-chrome-bridge

或使用 pnpm:

# 方法1：全局启用脚本（推荐）
pnpm config set enable-pre-post-scripts true
pnpm install -g mcp-chrome-bridge

# 方法2：如果 postinstall 没有运行，手动注册
pnpm install -g mcp-chrome-bridge
mcp-chrome-bridge register

MCP

目前 Claude Code 支持两种服务连接方式:

接入方式	描述	性能	延迟
`http(s)` / `websocket`	基于 `http(s)` / `ws` 的连接方式	稍差	稍差
`stdio`	基于 `stdio` 的连接方式, 只能本地调用	高	快速

这里 <a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a> 就非常适合使用 stdio 的方式进行连接, 因为 <a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a> 调用的是本地的 Chrome, 没有必要启动 http(s) 服务

了解更多 MCP 安装和配置方式, 可参考 <a href="https://docs.claude.com/zh-CN/docs/claude-code/mcp?utm_source=chatgpt.com" target="_blank">通过 MCP 将 Claude Code 连接到工具 - 官方文档</a>

在 Claude Code 中使用

查看全局安装的 mcp-chrome-bridge 路径

pnpm list -g mcp-chrome-bridge

Legend: production dependency, optional only, dev only

/Users/xxx/Library/pnpm/global/5

dependencies:
mcp-chrome-bridge 1.0.29

假设上面的命令输出的路径是: /Users/xxx/Library/pnpm/global/5 那么你的最终路径就是: /Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js

添加 Claude Code MCP, 可以根据需要将 mcp-chrome 服务添加到 <a href="https://docs.claude.com/zh-CN/docs/claude-code/mcp?utm_source=chatgpt.com#%E6%9C%AC%E5%9C%B0%E8%8C%83%E5%9B%B4" target="_blank">本地</a> 或者 <a href="https://docs.claude.com/zh-CN/docs/claude-code/mcp?utm_source=chatgpt.com#%E9%A1%B9%E7%9B%AE%E8%8C%83%E5%9B%B4" target="_blank">项目</a> / <a href="https://docs.claude.com/zh-CN/docs/claude-code/mcp?utm_source=chatgpt.com#%E7%94%A8%E6%88%B7%E8%8C%83%E5%9B%B4" target="_blank">用户</a> 范围

本地范围(只允许当前用户在当前项目中使用): claude mcp add chrome-mcp-stdio -- node /Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js
项目范围(只在为当前项目添加 mcp-chrome 服务): claude mcp add chrome-mcp-stdio --scope project -- node /Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js
用户范围(当前用户可在全局使用): claude mcp add chrome-mcp-stdio --scope user -- node /Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js

范围	描述	应用范围	是否共享	参数
<a href="https://docs.claude.com/zh-CN/docs/claude-code/mcp?utm_source=chatgpt.com#%E6%9C%AC%E5%9C%B0%E8%8C%83%E5%9B%B4" target="_blank">本地范围</a>	只允许当前用户在当前项目中使用	当前项目	否	``
<a href="https://docs.claude.com/zh-CN/docs/claude-code/mcp?utm_source=chatgpt.com#%E9%A1%B9%E7%9B%AE%E8%8C%83%E5%9B%B4" target="_blank">项目范围</a>	只为当前项目添加 `mcp-chrome` 服务, 会写入 `.claude.json` 中的 `projects.xxx.mcpServers` 中	当前项目	是	`--scope project`
<a href="https://docs.claude.com/zh-CN/docs/claude-code/mcp?utm_source=chatgpt.com#%E7%94%A8%E6%88%B7%E8%8C%83%E5%9B%B4" target="_blank">用户范围</a>	为所有项目添加 `mcp-chrome` 服务, 会写入 `.claude.json` 中的 `projects.xxx.mcpServers` 中	所有项目	是	`--scope user`

这里我们选择在 用户范围 添加 mcp-chrome 服务:

claude mcp add chrome-mcp-stdio -- node /Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js

Added stdio MCP server chrome-mcp-stdio with command: node /Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js to user config
File modified: /Users/xxx/.claude.json

通过输出的内容, 我们发现 mcp-chrome 服务已经添加到 .claude.json 文件中:

{
  "mcpServers": {
    "chrome-mcp-stdio": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js"
      ],
      "env": {}
    }
  }
}

最后, 我们检查一下 Claude Code 的 MCP 列表中是否存在 mcp-chrome 服务:

claude mcp list                      (base) 607ms  三  9/17 15:02:20 2025

Checking MCP server health...

chrome-mcp-stdio: node /Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js - ✓ Connected
context7: https://mcp.context7.com/mcp (HTTP) - ✓ Connected

移除 MCP

claude mcp remove chrome-mcp-stdio

使用

连接服务

点击浏览器插件中的链接按钮, 如果连接成功, 则会看到如下界面:

如果遇到服务未启动, 可能是 mcp-chrome-bridge 没有注册成功, 可以手动注册:

mcp-chrome-bridge register

Writing Node.js path: /usr/local/bin/node
✓ Node.js path written for run_host scripts
Registering user-level Native Messaging host...
Attempting to register user-level Native Messaging host...
✓ Set execution permissions for index.js
✓ Set execution permissions for run_host.sh
✓ Set execution permissions for cli.js
manifest path==> {
  name: 'com.chromemcp.nativehost',
  description: 'Node.js Host for Browser Bridge Extension',
  path: '/Users/xxx/Library/pnpm/global/5/.pnpm/mcp-chrome-bridge@1.0.29/node_modules/mcp-chrome-bridge/dist/run_host.sh',
  type: 'stdio',
  allowed_origins: [ 'chrome-extension://hbdgbgagpkpjffpklnamcljpakneikee/' ]
} /Users/xxx/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.chromemcp.nativehost.json
Successfully registered user-level Native Messaging host!
Native Messaging host registered successfully!
You can now use connectNative in Chrome extension to connect to this service.

调用 mcp-chrome

启动 Claude Code, 并输入以下内容来调取浏览器获取仓库的 star 数量信息:

claude

> 调用 Chrome MCP, 检查 Github 上我的所有仓库, 并按 star 数量进行从大到小排序

⏺ I'll help you check all your GitHub repositories and sort them by star count. Let me use the Chrome MCP to navigate to
  GitHub and retrieve this information.

⏺ chrome-mcp-stdio - chrome_navigate (MCP)(url: "https://github.com/SublimeCT")

  Todos
  ☐ Navigate to GitHub profile page
  ☐ Extract repository information including star counts
  ☐ Sort repositories by star count in descending order

╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Tool use                                                                                                                     │
│                                                                                                                              │
│   chrome-mcp-stdio - chrome_navigate(url: "https://github.com/SublimeCT") (MCP)                                              │
│   Navigate to a URL or refresh the current tab                                                                               │
│                                                                                                                              │
│ Do you want to proceed?                                                                                                      │
│ ❯ 1. Yes                                                                                                                     │
│   2. Yes, and don't ask again for chrome-mcp-stdio - chrome_navigate commands in /Users/xxx/projects/blog.xiaban.run       │
│   3. No, and tell Claude what to do differently (esc)                                                                        │
│                                                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

使用体验

实际体验比较差, 没有达到我的预期, 因为 Claude Code 将操作分解为了很多步骤, 例如

先获取元素
再点击 xxx
再获取数据
...

实际上 **每一步操作都有时间间隔, 导致操作速度非常慢 **😡, 所以需要多个操作步骤的需求还是应该使用定制化的 MCP 服务

参考

<a href="https://github.com/hangwin/mcp-chrome" target="_blank">mcp-chrome</a>
<a href="https://github.com/hangwin/mcp-chrome/blob/master/README_zh.md" target="_blank">mcp-chrome 中文文档</a>
<a href="https://github.com/hangwin/mcp-chrome/blob/master/docs/TOOLS_zh.md" target="_blank">mcp-chrome MCP Server API 中文文档</a>
<a href="https://playwright.dev/" target="_blank">playwright</a>
<a href="https://www.selenium.dev/" target="_blank">selenium</a>
<a href="https://www.cypress.io/" target="_blank">cypress</a>
<a href="https://pptr.dev/" target="_blank">puppeteer</a>
<a href="https://github.com/Oanakiaja/chrome-extension-bridge-mcp" target="_blank">chrome-extension-bridge-mcp</a>
<a href="https://docs.claude.com/zh-CN/docs/claude-code/mcp?utm_source=chatgpt.com" target="_blank">通过 MCP 将 Claude Code 连接到工具 - 官方文档</a>

Claude Code 安装与配置指南(接入免费的国产模型)

Thu, 04 Sep 2025 00:00:00 GMT

本文将介绍最近爆火的 Claude Code 在国内环境的使用, 包括安装与配置, 以及如何 接入国产模型 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">智谱 GLM</a>

2025-09-05, Anthropic 发布了一篇公告: 更新对不受支持地区的销售限制, 将中国定义为敌对国家, 并且不再为中国公司(包含超过 50% 所有权的中国公司的子公司)提供服务

这意味着 在未来我们使用 Claude 服务的难度将越来越大

[!TIP] 如果想要获得最好的 Vibe Coding 体验, 推荐购买 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">🔗 GLM Coding Lite</a> 服务(也可以 <a href="https://www.bigmodel.cn/activity/trial-card/A8AMOHCHA5">🔗 点击这里</a> 先免费试用 7 天), 包月只要 20 💰, Lite 版本的按 Prompt 计费, 每 5 小时最多约 120 次 prompts, 原因如下:

Claude Code 消耗的 token 非常多(我现在一个月已经消耗了 3 亿多 tokens 💪), 如果按 token 消耗量计费会非常贵, 使用包月套餐可以无需担心消耗的 token 数量, 专注于 Vibe Coding

Claude Code 是 Anthropic 推出的工具, 自然与 Claude 系列模型支持度最好, 其他大模型与 Claude Code API 不兼容, 也没有对 Claude Code 进行优化, 这也是 @musistudio/claude-code-router 库存在的意义; <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a> 专门提供了 Claude Code 的 API

vibe coding

最近有个一很火的概念: Vibe Coding, 直译过来就是 氛围编程, Vibe Coding 的概念出自 Andrej Karpathy(前特斯拉人工智能总监, OpenAI 的创始成员之一) 的一条推文:

There's a new kind of coding I call "vibe coding", where you fully give in to the vibes, embrace exponentials, and forget that the code even exists. It's possible because the LLMs (e.g. Cursor Composer w Sonnet) are getting too good. Also I just talk to Composer with SuperWhisper so I barely even touch the keyboard. I ask for the dumbest things like "decrease the padding on the sidebar by half" because I'm too lazy to find it. I "Accept All" always, I don't read the diffs anymore. When I get error messages I just copy paste them in with no comment, usually that fixes it. The code grows beyond my usual comprehension, I'd have to really read through it for a while. Sometimes the LLMs can't fix a bug so I just work around it or ask for random changes until it goes away. It's not too bad for throwaway weekend projects, but still quite amusing. I'm building a project or webapp, but it's not really coding - I just see stuff, say stuff, run stuff, and copy paste stuff, and it mostly works.

有一种新的编程方式，我称之为“氛围编程”，在这种编程中，你完全沉浸在大脑波中，拥抱指数增长，甚至忘记代码的存在。这是可能的，因为大型语言模型（例如Cursor Composer w Sonnet）变得越来越出色。此外，我只需用SuperWhisper与Composer交谈，几乎都不用碰键盘。我会要求一些愚蠢的事情，比如“将侧边栏的填充减少一半”，因为我懒得去找。我总是“全部接受”，不再阅读差异了。当收到错误信息时，我只是复制粘贴，通常这样就能解决问题。代码超出了我的理解范围，我不得不花很长时间阅读它。有时大型语言模型无法修复错误，我就绕过去或者要求随机更改，直到它消失。对于一次性周末项目来说，这还不错，但仍然很有趣。我正在构建一个项目或网络应用程序，但这并不是真正的编程——我只是看到东西，说出东西，运行东西，复制粘贴东西，而且大部分都能工作。

Vibe Coding 描绘了一个全新的编程方式:

更少的关注代码, 更多的描述需求, 甚至完全通过对话完成编码任务
只关注结果, 代码质量不再重要, 不再做 code review

要实现 Vibe Coding, 就需要让 LLM 了解整个项目, 所以它通常需要更长的上下文和更合适的提示词, 更多细节可以参考 <a href="https://guangzhengli.com/blog/zh/vibe-coding-and-context-coding" target="_blank">这篇文章</a>

Claude Code

Claude Code 是 Anthropic 公司推出的一个 AI 编程工具, 它基于 Anthropic 公司的 Claude 模型, 相比于 Cursor, 它只能在命令行中使用, 并且它使用 grep find git cat 等命令来检索上下文, 更多差异可参考 <a href="https://guangzhengli.com/blog/zh/vibe-coding-and-context-coding#claude-code" target="_blank">这篇文章</a>

安装

Claude Code 可以通过 npm / pnpm 来安装, 所以需要 Nodejs 环境, 需要先安装 Nodejs

# 这里使用的是 npm, 也可以使用 pnpm 或 yarn
npm i -g @anthropic-ai/claude-code

如果需要接入阿里云模型, 则需要安装 @musistudio/claude-code-router, 使用智谱的 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding</a> 服务, 则无需安装

npm i -g @musistudio/claude-code-router

这里全局安装了两个包:

@anthropic-ai/claude-code: 这是 Claude Code 的核心包, 它提供了 Claude Code 的功能
<a href="https://github.com/musistudio/claude-code-router/blob/main/README_zh.md">@musistudio/claude-code-router</a>: 是一款可将 Claude Code 请求路由到不同的模型的工具, 也是实现接入国产模型的关键:
- 模型路由: 根据需求将请求路由到不同的模型（例如，后台任务、思考、长上下文）
- 多提供商支持: 支持 OpenRouter / DeepSeek / Ollama / Gemini / Volcengine / SiliconFlow 等各种模型提供商
- 请求/响应转换: 使用转换器为不同的提供商自定义请求和响应。
- 动态模型切换: 在 Claude Code 中使用 /model 命令动态切换模型。
- GitHub Actions 集成: 在您的 GitHub 工作流程中触发 Claude Code 任务。
- 插件系统: 使用自定义转换器扩展功能。

更新 Claude Code

<a href="https://www.npmjs.com/package/@anthropic-ai/claude-code" target="_blank">Claude Code</a> 更新频率非常高, 要获得最佳的使用体验, 应该经常更新 Claude Code:

# 这里使用的是 npm, 也可以使用 pnpm 或 yarn
npm i -g @anthropic-ai/claude-code@latest

配置

创建 ~/.claude-code-router/config.json 文件(windows 下为对应的用户目录)

这里展示了接入阿里云 / GLM 模型的方式, 利用各大供应商的免费 tokens 额度实现免费使用, 如果免费额度用完, 或者想要满足日常使用的需求, 建议购买 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a>

大模型提供商	模型	计费方式	是否针对 `Anthropic API` 进行兼容优化	说明
阿里云	<a href="https://bailian.console.aliyun.com/?tab=model#/model-market">模型广场 - 阿里云百炼</a>	有免费额度, 只能按 `token` 消耗量付费	无	❌ 不推荐使用
智谱	`GLM 4.6`	可以购买包月/包季/包年套餐 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a>	提供了兼容 `Anthropic API` 的端点, 详见 <a href="https://docs.bigmodel.cn/cn/guide/develop/claude#claude-code">接入 `Claude Code`</a>	✅ 推荐使用

[!TIP] 推荐购买 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a> 服务, 包月只要 20 💰, Lite 版本的按 Prompt 计费, 每 5 小时最多约 120 次 prompts, 原因如下:

Claude Code 消耗的 token 非常多(我现在已经消耗了 3 亿 tokens 💪), 如果按 token 消耗量计费会非常贵, 使用包月套餐可以无需担心消耗的 token 数量, 专注于 Vibe Coding

Claude Code 是 Anthropic 推出的工具, 自然与 Claude 系列模型支持度最好, 其他大模型与 Claude Code API 不兼容, 也没有对 Claude Code 进行优化, 这也是 @musistudio/claude-code-router 库存在的意义; <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a> 专门提供了 Claude Code 的 API

阿里云百炼

阿里云百炼有非常多的免费模型, 免费模型普遍都有一百万 token 额度

进入模型广场 - 阿里云百炼, 挑选几个免费模型(例如 通义千问3-Max-Preview), 点击 查看详情
复制有免费额度模型的 Code 值, 并 启用免费额度用完即停
创建 ~/.claude-code-router/config.json 文件, 将模型添加到 Providers 数组中, 将第二步复制的 Code 填入 Providers.models, 并在 Router 中指定模型路由

{
  "LOG": true,
  "HOST": "127.0.0.1",
  "APIKEY": "yourpassword",
  "PORT": 65430,
  "Providers": [
    {
      "name": "aliyun",
      "api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
      "api_key": "sk-kljsaoeifklahshgoasieofjio",
      "models": [
        "qwen3-max-preview",
        "qwen-flash",
        "Moonshot-Kimi-K2-Instruct",
        "deepseek-v3.1",
        "deepseek-r1-0528"
      ]
    }
  ],
  "Router": {
    "default": "aliyun,qwen3-max-preview",
    "background": "GLM,deepseek-v3.1",
    "think": "aliyun,deepseek-r1-0528",
    "longContext": "GLM,deepseek-v3.1",
    "longContextThreshold": 50000,
    "webSearch": "GLM,qwen3-max-preview"
  }
}

[!TIP] 请将 api_key 替换为自己的 api key

LOG: 打印的日志类型
HOST: claude-code-router 启动的本地服务; <a href="https://github.com/musistudio/claude-code-router/blob/main/README_zh.md">@musistudio/claude-code-router</a> 的原理就是在本地启动一个服务, 然后让 Claude Code 去访问本地的服务, 从而实现不访问 Claude API, 而使用我们指定的国产模型
APIKEY: Claude Code 链接服务时使用的 API Key, 这里我们可以随意填写
PORT: claude-code-router 启动的端口, 默认是 6543, 我习惯修改端口
<a href="https://github.com/musistudio/claude-code-router/blob/main/README_zh.md#providers" target="_blank">Providers</a>: 模型的提供商, 可以添加多个, 这里我们使用阿里云百炼
<a href="https://github.com/musistudio/claude-code-router/blob/main/README_zh.md#router" target="_blank">Router</a>: 用于设置路由规则:
- default: 用于常规任务的默认模型。
- background: 用于后台任务的模型。这可以是一个较小的本地模型以节省成本。
- think: 用于推理密集型任务（如计划模式）的模型。
- longContext: 用于处理长上下文（例如，> 60K 令牌）的模型。
- longContextThreshold (可选): 触发长上下文模型的令牌数阈值。如果未指定，默认为 60000。
- webSearch: 用于处理网络搜索任务，需要模型本身支持。如果使用openrouter需要在模型后面加上:online后缀。
- image(测试版): 用于处理图片类任务（采用CCR内置的agent支持），如果该模型不支持工具调用，需要将config.forceUseImageAgent属性设置为true。

更多参数及配置请参考 <a href="https://github.com/musistudio/claude-code-router/blob/main/README_zh.md#2-%E9%85%8D%E7%BD%AE" target="_blank">官方文档</a>

智谱

智谱的新用户有 两千万的免费 tokens 额度(不同模型), 或者可以使用按 Prompt 计次的包月服务 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a>

进入智谱 BigModel, 点击右上角的财务, 点击 资源包管理 > 我的资源包 查看免费额度

[!NOTE] 由于 <span style="color: red;">Claude Code 消耗的 token 非常多(轻轻松松消耗上百万 token 😭)</span>, 如果只是用免费额度或使用按 token 计费的服务, 需要在此页面时刻留意剩余的 Tokens

[!TIP] 或者使用付费的 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a> 服务, Lite 版本的按 Prompt 计费, 只需关注提问次数, 完全不用担心 tokens 消耗量

前往 <a href="https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys" target="_blank">设置页面</a> 添加 API Key
创建 ~/.claude-code-router/config.json 文件, 将模型添加到 Providers 数组中, 将第二步复制的 API Key 填入 Providers.api_key, 并在 Router 中指定模型路由

{
  "LOG": true,
  "HOST": "127.0.0.1",
  "APIKEY": "yourpassword",
  "PORT": 65430,
  "Providers": [
    {
      "name": "GLM",
      "api_base_url": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
      "api_key": "aosiejflaJOIeifhwiofhjajsdf.sldfjaiOSioef",
      "models": [
        "glm-4.5",
        "glm-4.5-air",
        "glm-4-long",
        "glm-4-flash"
      ]
    }
  ],
  "Router": {
    "default": "GLM,glm-4.5",
    "background": "GLM,glm-4.5-air",
    "longContext": "GLM,glm-4.5-air",
    "longContextThreshold": 50000,
    "webSearch": "GLM,glm-4.5-air"
  }
}

配置 Claude Code

claude-code-router 提供了 ccr 命令来代理访问 Claude Code, 但 直接使用 ccr 会导致很多问题:

无法在 vscode 的 Claude Code Plugin 中使用我们配置的模型
也无法在命令行中直接使用 claude 命令访问国产模型
无法使用智谱的 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a> 服务

因此我们要实现直接使用 claude 命令使用 Claude Code, 而不是使用 ccr 命令:

创建 ~/.claude/settings.json 文件

使用免费的国产模型

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:65430",
    "ANTHROPIC_API_KEY": "yourpassword",
  }
}

这里的 ANTHROPIC_API_KEY 就是 ~/.claude-code-router/config.json 中的 APIKEY

使用智谱的 GLM Coding Lite 服务

因为 <a href="https://www.bigmodel.cn/claude-code?cc=fission_glmcode_sub_v1&ic=Q2N8XA4W77&n=a****3" target="_blank">GLM Coding Lite</a> 使用了类似 Claude Max / Claude Pro 的包时服务, 所以配置与直接访问 API 的配置不同

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "asoiejilfjJIOfejwiofji.OIsfjosiaejnlf"
  }
}

这里的 ANTHROPIC_AUTH_TOKEN 是智谱平台的 API Key

[!WARNING] 如果已经启动了 Claude Code, 每次修改配置文件后都需要执行 claude restart(ccr 对应 ccr restart 命令)

初始化

配置完成后就可以直接通过 claude 命令启动 Claude Code 了

启动 Claude Code

cd your-project
claude

╭──────────────────────────╮
│ ✻ Welcome to Claude Code │
╰──────────────────────────╯

 Let's get started.

 Choose the text style that looks best with your terminal:
 To change this later, run /theme

 ❯ 1. Dark mode✔
   2. Light mode
   3. Dark mode (colorblind-friendly)
   4. Light mode (colorblind-friendly)
   5. Dark mode (ANSI colors only)
   6. Light mode (ANSI colors only)


 Preview
 ╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
 │   1   function greet() {                                                                                                        │
 │   2 -    console.log("Hello, World!");                                                                                          │
 │   2 +    console.log("Hello, Claude!");                                                                                         │
 │   3   }                                                                                                                         │
 ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

这里是选择主题, 直接选择 Dark mode 即可(按下 Enter)

如果执行结果是:

╭──────────────────────────╮
│ ✻ Welcome to Claude Code │
╰──────────────────────────╯

 Unable to connect to Anthropic services

 Failed to connect to console.anthropic.com: ERR_BAD_REQUEST

 Please check your internet connection and network settings.

 Note: Claude Code might not be available in your country. Check supported countries at https://anthropic.com/supported-countries

则说明设置失败, 请检查配置文件格式是否正确, 以及是否已经设置了环境变量 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN, 如果已经设置了需要清除

随后是一个安全说明

╭──────────────────────────╮
│ ✻ Welcome to Claude Code │
╰──────────────────────────╯

 Security notes:

  Claude can make mistakes
  You should always review Claude's responses, especially when
  running code.

  Due to prompt injection risks, only use it with code you trust
  For more details see:
  https://docs.anthropic.com/s/claude-code-security

 Press Enter to continue…

直接按 Enter 继续

设置换行方式

╭──────────────────────────╮
│ ✻ Welcome to Claude Code │
╰──────────────────────────╯

 Use Claude Code's terminal setup?

 For the optimal coding experience, enable the recommended settings
 for your terminal: Shift+Enter for newlines

 ❯ 1. Yes, use recommended settings
   2. No, maybe later with /terminal-setup

 Enter to confirm · Esc to skip

直接按 Enter 继续

安全风险提示

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                   │
│ Do you trust the files in this folder?                                                                                            │
│                                                                                                                                   │
│ /Users/xxx/projects/xxxxxxxxx                                                                                                     │
│                                                                                                                                   │
│ Claude Code may read, write, or execute files contained in this directory. This can pose security risks, so only use files from   │
│ trusted sources.                                                                                                                  │
│                                                                                                                                   │
│ Learn more ( https://docs.anthropic.com/s/claude-code-security )                                                                  │
│                                                                                                                                   │
│ ❯ 1. Yes, proceed                                                                                                                 │
│   2. No, exit                                                                                                                     │
│                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
   Enter to confirm · Esc to exit

这里提示的是是否信任 Claude Code 读取源码, 直接按 Enter 继续

进入对话

╭───────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code!                         │
│                                                   │
│   /help for help, /status for your current setup  │
│                                                   │
│   cwd: /Users/xxx/projects/xxxxxxxxx              │
│                                                   │
│   ─────────────────────────────────────────────── │
│                                                   │
│   Overrides (via env):                            │
│                                                   │
│   • API Base URL:                                 │
│   https://open.bigmodel.cn/api/anthropic          │
╰───────────────────────────────────────────────────╯

 Tips for getting started:

  Run /init to create a CLAUDE.md file with instructions for Claude
  Use Claude to help with file analysis, editing, bash commands and git
  Be as specific as you would with another engineer for the best results
  ✔ Run /terminal-setup to set up terminal integration

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ > Try "write a test for <filepath>"                                                                                               │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
  ? for shortcuts                                    ✗ Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code

使用

项目首次使用 Claude Code 会提示执行 /init 命令创建 CLAUDE.md 文件, 这一步 Claude Code 会扫描整个项目, 并进行代码分析和总结, 从而为大模型理解整个项目提供帮助

/init


⏺ I'll analyze the codebase to understand its structure and create a comprehensive CLAUDE.md file.

⏺ Task(Analyze codebase structure)
  ⎿  total 48
     drwxr-xr-x  27 xxxxx  staff    864  9  5 10:13 .
     drwxr-xr-x  21 xxxxx  staff    672  9  5 10:13 ..
     … +25 lines (ctrl+r to expand)
     src/test/index.ts
     src/test/test/hasRole.ts
     src/test/test/hasPermi.ts
     … +17 lines (ctrl+r to expand)
     +12 more tool uses

· Puzzling… (esc to interrupt)

第一次执行扫描时会比较慢, 如果代码量过大, 也可能直接中断, 这里我就直接中断了:

然后我又问了 为什么没有生成 CLAUDE.md ?, 看上去它读取了部分文件, 然后生成出了 CLAUDE.md

> 为什么没有生成 CLAUDE.md ?

⏺ I'll analyze the codebase directly to create the CLAUDE.md file.

⏺ Read(package.json)
  ⎿  Read 142 lines (ctrl+r to expand)

⏺ Read(README.md)
  ⎿  Read 12 lines (ctrl+r to expand)

⏺ Search(pattern: "*.md")
  ⎿  Found 1 file (ctrl+r to expand)

⏺ Read(vite.config.ts)
  ⎿  Read 162 lines (ctrl+r to expand)

⏺ Read(.eslintrc.cjs)
  ⎿  Read 52 lines (ctrl+r to expand)

⏺ Search(pattern: "src/**")
  ⎿  Found 100 files (ctrl+r to expand)

⏺ Read(src/router/index.ts)
  ⎿  Read 8 lines (ctrl+r to expand)

⏺ Search(pattern: "src/store/**")
  ⎿  Found 11 files (ctrl+r to expand)

⏺ Search(pattern: "src/api/**")
  ⎿  Found 100 files (ctrl+r to expand)

⏺ Search(pattern: "src/views/**")
  ⎿  Found 100 files (ctrl+r to expand)

⏺ Read(src/store/readme.md)
  ⎿  Read 57 lines (ctrl+r to expand)

⏺ Search(pattern: "scripts/**")
  ⎿  Found 8 files (ctrl+r to expand)

⏺ Search(pattern: ".cursor/**")
  ⎿  Found 0 files

⏺ Search(pattern: ".cursorrules")
  ⎿  Found 0 files

⏺ Search(pattern: ".github/copilot-instructions.md")
  ⎿  Found 0 files

⏺ Read(scripts/openapi-codegen.ts)
  ⎿  Read 17 lines (ctrl+r to expand)

⏺ Read(src/views/foo/bar/baz/index.vue)
  ⎿  Read 50 lines (ctrl+r to expand)

⏺ Write(CLAUDE.md)
  ⎿  User rejected write to CLAUDE.md
         1 +  # CLAUDE.md
         2 +
         3 + 这里我省略了 ...
       117   \ No newline at end of file

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Overwrite file                                                                                                                    │
│ ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ CLAUDE.md                                                                                                                     │ │
│ │                                                                                                                               │ │
│ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ Do you want to overwrite CLAUDE.md?                                                                                               │
│ ❯ 1. Yes                                                                                                                          │
│   2. Yes, allow all edits during this session (shift+tab)                                                                         │
│   3. No, and tell Claude what to do differently (esc)                                                                             │
│                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

按下 Enter 创建 ClAUDE.md

context7 MCP

<a href="https://context7.com/" target="_blank">context7 MCP</a> 能实时注入最新文档到某 Claude 的上下文中, 解决模型知识的滞后性

访问 Dashboard 页面登录并创建 API Key
执行命令安装 context7

claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: ctx7sk-0iksefjl1-iwe2c-29n4-19nd-sliefoajn11"

将 YOUR_API_KEY 替换为自己的 API Key

vim mode

Claude Code 支持 vim 模式(vim 党狂喜 😁), 虽然只支持一些常用键

可以通过执行 /vim 启用, 或者 /config 永久启用:

输入 /config

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ > /config                                                                                                                         │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
  /config (theme)     Open config panel
  /agents             Manage agent configurations
  /hooks              Manage hook configurations for tool events

将光标移动到 Editor mode, 按下 Enter, 显示 vim 后按 Esc 退出

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Settings                                                                                                                          │
│ Configure Claude Code preferences                                                                                                 │
│                                                                                                                                   │
│ ❯ Auto-compact                              true                                                                                  │
│                                                                                                                                   │
│   Use todo list                             true                                                                                  │
│                                                                                                                                   │
│   Verbose output                            false                                                                                 │
│                                                                                                                                   │
│   Auto-updates                              true                                                                                  │
│                                                                                                                                   │
│   Theme                                     Dark mode                                                                             │
│                                                                                                                                   │
│   Notifications                             Auto                                                                                  │
│                                                                                                                                   │
│   Output style                              default                                                                               │
│                                                                                                                                   │
│   Editor mode                               vim                                                                                   │
│                                                                                                                                   │
│   Model                                     Default (recommended)                                                                 │
│                                                                                                                                   │
│   Auto-connect to IDE (external terminal)   false                                                                                 │
│                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

vscode 插件

可以直接在 vscode 应用市场中搜索并安装 Claude Code 插件, 点击右上角的 Claude Code 图标即可启动

安装插件后, 点击右上角的 ❄️ Claude Code 插件图标, 显示如下界面

这是因为插件 默认使用 Anthropic 官方的 Claude 系列模型, 我们需要修改插件的配置:

在左侧插件列表中搜索 Claude Code, 然后找到 Claude Code for VS Code, 点击 ⚙️ 按钮, 点击设置

进入设置页面, 我们需要修改的是 Environment Variables, 点击 在 settings.json 中编辑

在 settings.json 中增加环境变量配置

{
+  "claude-code.environmentVariables": [
+    {
+        "name": "ANTHROPIC_BASE_URL",
+        "value": "https://open.bigmodel.cn/api/anthropic"
+    },
+    {
+        "name": "ANTHROPIC_AUTH_TOKEN",
+        "value": "asoiejilfjJIOfejwiofji.OIsfjosiaejnlf"
+    },
+  ]
}

[!TIP] 请将 ANTHROPIC_AUTH_TOKEN 对应的 value, 替换为自己的 api key

关闭 Claude Code 窗口, 再次点击 ❄️ Claude Code 插件图标, 此时就可以正常进行对话了

Error Invalid API key

> hello ?
⎿  Invalid API key · Please run /login

在使用 GLM 时, 如果遇到了 Invalid API key 错误, 说明 Claude Code 并没有读取到你配置的 API Key, 应该检查以下配置文件:

./.claude/settings.local.json: 项目内的配置文件
~/.claude/settings.local.json: 全局配置文件

Claude Code 在使用时, 可能会将项目的配置写入 ./.claude/settings.local.json, 也会 会优先读取项目内的配置文件, 所以如果有项目内的配置文件, 那么我们 也要在这个文件内配置 API Key:

{
  "permissions": {
    "allow": [
      "Bash(mkdir:*)",
      "Read(//Users/xxx/projects/xxx/src/)",
    ],
    "deny": [
      "Bash(pnpm lint:*)"
    ],
    "ask": []
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "asiehjfioahgeriaofhjo23i.aiosjfgoiaeijfjio",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

ccusage

ccusage 是一个用于统计 Claude Code 使用量的工具, 它从 ~/.claude/projects 目录读取了大模型的对话历史记录, 从而统计每天的 tokens 消耗量

安装 ccusage

pnpm i -g ccusage

执行 ccusage daily 查看每天的 tokens 消耗量

ccusage daily

 WARN  Fetching latest model pricing from LiteLLM...                                                               ccusage 15:18:05

ℹ Loaded pricing for 1491 models                                                                                  ccusage 15:18:05

 ╭──────────────────────────────────────────╮
 │                                          │
 │  Claude Code Token Usage Report - Daily  │
 │                                          │
 ╰──────────────────────────────────────────╯

┌────────────┬───────────────┬────────────┬───────────┬───────────────┬─────────────┬───────────────┬─────────────┐
│ Date       │ Models        │      Input │    Output │  Cache Create │  Cache Read │  Total Tokens │  Cost (USD) │
├────────────┼───────────────┼────────────┼───────────┼───────────────┼─────────────┼───────────────┼─────────────┤
│ 2025-09-08 │ - sonnet-4    │  1,038,167 │   100,264 │             0 │   6,720,666 │     7,859,097 │       $6.63 │
├────────────┼───────────────┼────────────┼───────────┼───────────────┼─────────────┼───────────────┼─────────────┤
│ 2025-09-09 │ - sonnet-4    │  1,319,907 │    73,242 │             0 │  24,117,626 │    25,510,775 │      $12.29 │
├────────────┼───────────────┼────────────┼───────────┼───────────────┼─────────────┼───────────────┼─────────────┤
│ Total      │               │  2,358,074 │   173,506 │             0 │  30,838,292 │    33,369,872 │      $18.93 │
└────────────┴───────────────┴────────────┴───────────┴───────────────┴─────────────┴───────────────┴─────────────┘

参考

济你太美, 徐度光阴(超多图)

Sun, 20 Jul 2025 00:00:00 GMT

图为孔子和他的学生, 拍摄地为 <a href="https://surl.amap.com/b1pnF3z1q5zD" target="_blank">济宁市博物馆文化中心馆</a>

逝者如斯夫, 不舍昼夜, 意为 时间像流水一样, 日夜不停地流逝, 这句话表达了孔子对时间流逝的感叹，也蕴含着珍惜时间，不虚度光阴的哲理

工作变动

人生总是充满了变数, 因工作变动, 我从 6 月份开始前往济宁出差, 开始了一场 魔幻的被无限拉长的出差经历

6 月份时得到消息: 干到 6 月底就回原工作地
6 月中旬得知: 没希望了, 无法回来
7 月初得知: 应该稳了, 可以回来
7 月初又得知: 双方领导层正在协商, 可以回来
7 月中旬又得知: 8 月份就可以回原工作地
8 月初得知: 正在确认细节
8 月初又得知: 还在走流程
8 中旬得知: 即将返回原工作地
8 中旬: 返程

从商业谈判的角度来看, 这其中发生的故事肯定非常精彩, 但对于真正的劳动力来说, 这可一点都不好玩

希望是美好的，也许是人间至善，而美好的事物永不消逝。
Hope is a good thing, maybe the best of things, and no good thing ever dies.

这趟旅程像极了 <a href="https://www.bilibili.com/bangumi/play/ep284310" target="_blank">🎬 肖申克的救赎</a>, 在一次次希望与绝望之间等待最终的救赎, 我们或许未必经历过监狱, 但谁没有被生活的高墙围堵过? 唯独美好的事物永不消逝

出发

由于我的行李比较多(一个大件行李, 一个行李箱, 一个电脑包), 所以打算开车去

经过 4 个多小时最终到达济宁的出租屋(公司提供的宿舍), 这是一个三居室, 但只有一个卧室有空调, 另一个空调在客厅

图为客厅(打扫后), 我们安顿好之后立马出去买了拖把, 把洗手间和客厅打扫了一遍(简直太脏了 😫)

右侧为厨房, 厨房非常的脏, 一开门全是土, 里面堆着面和油, 没有招来老鼠蟑螂也是个奇迹

图为唯一一个有空调的卧室(我的卧室), 在酷热的夏天能有一台空调续命真的太舒服了, 我宣布 空调是最伟大的发明

图为卧室门, 据说之前是小孩子的卧室, 这种标语对小孩子应该会有激励作用, 但对我们来说...

如果努力就可以成功, 这个世界的首富应该是我们村里的驴
应该努力让自己成为自己想成为的人, 而不是活成别人希望的样子

济你太美

之前从未来过济宁, 对济宁的认知还停留在 孔孟之乡 和 <a href="https://www.douyin.com/user/MS4wLjABAAAAoC6BLDETRW9UFXZ4p4Y-_lKwXWrImjkRYZDxIXs3G3HjYQDAcmWTGUGHUja8K-O-" target="_blank">汤姆张</a> 上, 没想到搜了一下济宁, 意外的发现了济宁文旅竟然在蹭哥哥的热度, 济宁居然真的有 <a href="https://surl.amap.com/gBriRHn1aH6" target="_blank">蔡徐村</a>

视频作者为 <a href="https://www.douyin.com/user/MS4wLjABAAAAKwBGPrZNyFY1CnnFd60nmzQ1b_Ziprh-BE7adF0uNqo" target="_blank">济宁你好</a>, 看起来并不是网传的由济宁文旅制作

点击查看 <a href="https://surl.amap.com/gBriRHn1aH6" target="_blank">蔡徐村</a>

初来乍到

图为刚开始下雨时的天空, 在小区内拍摄, 深色的乌云像水墨一样逐渐晕染开来

图为济宁的公交车, 印有 "情系万里, 德行济宁", 据说早晚高峰免费, 但是来了这么久没坐过公交

图为济宁北站出站口的展示牌, 青年发展友好型城市

但现实情况是, 疯狂宣传的往往是有所欠缺的, 根据济宁市统计局的数据, 2024年相比于2023年, 济宁市常住人口减少了 5.32 万人(824.05 - 818.73), 降幅创近十年新高, 详见 <a href="https://www.sohu.com/a/892879874_121123761">济宁及各县市区最新常住人口数据公布</a>

我觉得应该改成生活节奏友好型城市, 这是一座生活节奏比较慢的城市, 大家都比较随性, 有生活气息, 人与人之间基本没有距离感

散装的济宁

济宁市区在任城, 济宁的其他下辖地市都比任城知名度高, 例如曲阜 / 邹城 / 兖州 / 梁山

机场也在嘉祥, 没错, 济宁的机场叫做曲阜国际机场, 不在曲阜也不在城区, 而在嘉祥
京沪高铁也没有经过城区, 而是在曲阜设有曲阜东站任城与兖州邹城曲阜之间又有成片的煤矿塌陷区, 无法连片发展

更加令人疑惑的是, 主城区四处建设新区, 最后哪都没发展起来:

东边建立了高新区, 但因为煤矿大量开采, 土地塌陷越来越严重, 根本不适合开发
西边建立了经开区, 往西向距离较近的嘉祥发展, 但同样没有发展起来
南边建立了太白湖新区, 但太白湖往南是南阳湖, 根本没有发展的空间
把高铁站(济宁北站)放到了距离城区很远的北边

煤矿塌陷区

为什么济宁的城市规划如此散装? 因为在济宁 分布着数量众多的煤矿开采区和塌陷区, 因为煤矿塌陷区的阻隔, 各辖区无法连片发展, 济宁也正在积极治理因煤矿开采带来的诸多问题

工作

这个项目是老系统升级改造, 即参考原系统代码在新系统中实现, 没有让我们评估工时, 而且工期非常紧，所以一直加班

老系统升级

这又是一个充满槽点的话题, 限于篇幅, 以后有时间会单独写一篇文章

由于原项目是 vue2, 新项目是 vue3, 所以为了代码迁移时少掉一些头发, 我还特地尝试了基于 gogocode 的 <a href="https://sublimect.github.io/gogocode-playground/#code/N4IglgdgDgrgLgYQPYBMCmIBcIQBoQDuSATgNbLpYgBmMEAxnGEhAARzECGEAztSQFsAFNTAAbNAEkI-XK05QwcpFCYseASlbAAOm1b11cVgBJWAXnmKAdAHMk9w+j2sDR1jyQxi9NBdaiEtL81p7evi5uvMacPMaWJkJhPmhyuvquUJzEPGgA8qrMvJjaka6uyb4AKgCeUGglAOQCqDASjbhl5WLctjCctg2sjQBuMGgdXZliMLaQPCUA2o1wdWg89MRgqo0Aup0ZrAC+B65HGnqRAPRXrMRocN5sNV7E7Fy8-MQCaChu6KwABZoe6RQzRdhoARQHpwPyWWJwayiCAoISNAA8cOhsLQAD4MVdsTDOHC8Y0LvpwXEPJttvF5HFkZA0ZiNltVASruz6eTKddblioSSyaxABcJgDAlSKA7goCRVYW4oTE3H8qnuKDEFQ8fyLXYC1gYnmc8VS-Qy1ESADKdNUSVtcDkmu1atcEmMTnhjKRgwgINJaCErtYN1YgG-PQAmaaw0AAPKAkYzoaicNrGYBHViAKeVAG6KgFDFMWAELdAOgJgHflMGoL33FojNAAUTjCYAImhk6mhJ7Ka5Pf5OCgUABBCA1KpIABidEYRQACtlOAIeO2K53-l7PdZ7iTfOijQ7yXI2Q6PA8YFBWD0ILZzDoQHAeNe+Zd9PdHsQ2J69EdH7QGGo2FWkDW9bxsQcDNq2YhwIu6BaOkrjPk8K5dOuaCboGVzUnAOg6DwADUQiLJwAC0ABe-aEQAWgA+iYuw4Rc2EAFRXox9zUFhQj4Vhd46FauwMQA-PRGi4Fctj7hhpgAIz+KxQgmAATBoADcFJIRuPRblcQhYQARt+k4sLpXEMQRJFkVRNGLFhBA0QxxnsUI-GYIsAB6QbprsAA+7GuUGfFYRoGh2To9E8MFwBWdhWG8QJ9FXFhwV8GxUU6MF8U6J+jEiWJwwmJJWEQEcqmHMhqFCFcsbAZh2E4UmKYQfZOi6IxVz7gVYDQgm2h3C2ygQAAsl4EBwigciGNC8C-McARagIrBYaM4wLQVxXlKwpUaWhWFHEp-HGY55gYlh3K7horXDKt5QbZwmnHQlXHUMl3Fpdl+4qcurjXbdOjpYlj1cfdP3bQFr3DOc71qShm3lXdqUPU9gM3DljSXZ96k3WhlFwICYDcdYon7tjuPWKj63o5pIzZFxWM4zwBMXR9ZNQxj5VCJTxCee6nkYaFDE07jxnMWFRM8Lt9Mo4zX2YyLgvGSLYvI6TUvlTLOjWJxOgoNZWFYZRtH0eVyN5eikvk2hqvq5FWs6AQOs6HrdHi3l1iUzMEym8zmkW1hJhQmA1WG-ufuQUrZsq7TWHWD7rF4xr1sEPrTuSS7nBu6HnvmxHavRy23GLMs167HH1n6wXID6jouxJynace2VVyYJgIyEegKHaYxGhCNYDG88A4uYK3UByYp2jp-XFsmOCojfOx4u1mI-XrDwAxoAAQkgMbWFPYDfCbH5fhOv5ArK8qKgGypn3CMEGmgYiETp8BwCw7BrFeN6xphICsIAAOmAIGRgA28YAI2NABcctGO+D84BPzYKseob9NQdWyDUa8Z5ICkEAEAMkQVQBmVl0TEt976P2fjAtAb84Qxk-qYEwJgAAMeIqF5UJPgiBUC9y4IxEwwh0DX7XngQIRByCxCoMoTQuhVDJKMPAZw8kkRlxYLhDgw4eC74oDAKnBwrAm64zADpCQoQagMDfiYaiyD6G0PoeIiqyjVFiAcKwxR7CrFqNsKwZuLR0BiEMcYr+pjREMMsS3axtjGgyP3hAPQ+kj4WjlGgG0HJILGkdKwZ0UBNClH0KGBJytGiVS6nVVM2h6FFX3PQikSlywQm7JYTJKJWQ5JAqwPJEEClUKKspcszgSph0aONeMfphoLHTB0BmkMyrNDADGeYzldhDIliM6GjQIBziGEYkwMyx7zMCHCHIJRBn7lDFUPIjY8isA6jCKEaB+kBHEFsngl13ydIzuiZJAzCkzP2Yc459hHAVlYIAA9NACrNoAEE1ABgLoAGV1ADqmoAT+1ACGMXIQAAkaAFO5P+kLAAr1oABLtADHcoAQA9ABXgYAGQjAD-ZoAgqElnnmCTJANAU4tQpKEMAQpZ0GIBGoKwBiVw7kViQjU9EKBSScCDNoVpXKWTongq+QVpNQxZJWXJaiMEVlFOGBJFZ-hZUmBKNwGoWhzB4gKdRIVDzRkrMwCsmZyrqIyRbGqjQ6yWaNDFWwelLSZklOXGuLpvK4D8vlc64pVCOUdLWsyVE6IemTRQJgQZdd5kyo0E6kwirunuBVZYMNI0OLat1c1CA9CCpXCZY9VlVxzi2q3I0awFa+FQCtF6uEckqE2v3KWwMSaJojR2a8v1qy3WcpKtyxoBBST0EBJGg1QaunGuAFEiQxBrXxqOImwdcBh0Zp1Ss3A1qdXZtzR+G10a7WTunSCdyhTF1DsBKuuh1EN0aC3QVHdhU91zJZlMeaIBGimsjUe2dKy42FNwIPTAHBxifjwK+gd57L3rs3XieduBgCAeA2gEtXR91blfdeD91FGhfpPse3987QOnDWsMJdK6gxruvTB7dVCCoocOGhwMGGQA6xACs1juHLT4blXBxDxAQPXmI2tCDy6L0UavSYDdv6t3-oQ2gFCQH+PIZtah596HDiuGvKx9jWEsBTrwz+njp7BPgbI2J29EmpNyrvXoB99G1qMfRDKgjnbSOQfE9B39Fgs33to7u5tTnqInt9W50TUGqOZtKLZvzj6AvBLY14udrmRPkci55uV3mos5piyWxzwSdBYZMAtYLCaZlmfC5JgVOqst2afYa+Z152NYACIfIorAkshZS+ZzLKqrMmEizRor-m8sLR0zhlrP4iglbPWFjzEXMuDbo3V8djyuuRuS669paBhUhuaA8QEqABljqumHcDsR9H0FMEF0xf6xFFLOzwC7E2DJsGc1Q6hPq8p5vzcyotRVVP1YPdd97t28qJoiW1t7NDr7Ra+3oH7ha2XHbRqt87DAruJFB4mtHl2IfP1jTVmLCOWVI7i7G+dMy8evaC59vNBaSfFriz8bGh31udc2+qQNJ3VubDQAGNEWOZksFXi2EgaBBp0EguJxbw21MtpaJL3402hcDSGum6XvmhsQGJ395b3PRk6VF-cAAqhABXw1lf7mF0btApvzdS4szL2LeW6D26V4Lq3EA7dq6Vxr2HS24uG6+GgZscQtQ1Et8Ma3wfveS8vU73LcueXrCfsQGo7uKee9j8NX3jvNcB+XFtpPKxabWBMD8Hgy9Bhl+u3KmZ89F6V5XjXxIv7iqfm1wxOybAmXAMAL+KgAHU0AFnagBJOQLIAIeUB+AG-bQABUqsAAAYaqHPP1ggBvH0ANHqgAIf8ALBygAseRBYPwAwDGAApXQAkP8uCZQAASyFwOa3ZAD5yoAac1WC1HqLE+krBsUX9YJfh1OoiWABwKgWF-j3vFDIK1s-L2AOEOCOOOJNiwDOLfguB2GknBMeOKu6o8l0KGIAKNygAnMqACyic9kfKPpvoAO6KgAsCqABoRoABYRgAffGADw+qfoADD-gAu-KACD0QAYAEbpgA9GaoHlBaS6RU66SOSYBcQ4SRQ2T6z8TeQ6B6QQFhJyG8wOSuQaB8RCSNR9xiRdBCCUROisTjJyBcAECIFzipLVawQkYSQnieq-CmHzgyScAmGzjzivqfQ8Awj+zoi4CkxBpVpCA35zgLZuHlASQcAdQ-B-CWCBECDWDhHCCMwkYnIspCAACE8RkRWgDq7wERvwj4SRa0oYgAz7GADj8YAE+6gAZHob4hisCADHkYACHmNR9wNIk+IRrgYAKRGRvw1gkA9AMw6AC4OGFIrAnknkIYLkiwzUeo3cVwcRKeyoWwAgmRIxYxXRKAoQXqIEPAAA6v7BeuWhWhSNfBpgUdkWsW0ccPkQUa4KGIAJDmgAG3mAAl0YADwKgAWP+ABjRoAAhGrAiyPwrAgAMSpPHPEXEdHtZrE9EMD9HrDojmBHH8HXFdjuCLCkBoA1ByBJi7D+DgkeGCIhywkaDWD+E6jVY8BxGLFBiJGnHoFsDz4mDAAok1BHBL41D+B0lJhHDz4XEd4XGhi-JAnMGAAvboAKXGM+G+Fx2RtJwAaxTJ8gy+IR5wIR1gAAVkgJAN4cMMGGtBKXSZqC2OMkcHJMADYfzvYTwOcNoJyYcB3q4JSB3ngOANAPAAADK9BUBjAYD4Ayg8DUoPBMAghYDJhiC5D4A8AwA6QABqYAaABAr+GA2APS2QGARwQAA" target="_blank">🔗 迁移脚本</a>

用于将 vue2 转换为 composition API 的 vue3 代码, 由于时间关系, 脚本只是个半成品, 并不完美

工作体验

程序员加班或许已经是行业共识，大家好像也习以为常，总是被迫愿意用更多的工作时间来换取项目的尽快交付，经历了两个月高强度的加班，让我深切的感受到: 软件行业是劳动密集型产业

我们看似投入了时间，精力，想法，产出的是某些系统或功能模块。实际上我们投入的是敲击键盘鼠标，得到的是工资到账。因为在老板眼里，你与工地搬砖的工人和村里种地的农民无异，我们在用脑力搬砖或者挥舞锄头，所以程序员群体都戏称自己是码农。

搬砖?

可是我们所做的工作明明是有技术含量的，为什么会有搬砖的感觉呢？

因为程序员在角色分工中就是最基层的制造者

程序员不像画家/ 设计师, 程序员的工作整体分为系统设计和编码两部分:

系统设计: 分析需求并找到可行的实现方案
编码: 根据实现方案编写代码

在系统设计阶段,我们做的是创造性的工作, 这一阶段很像画家作画, 设计师作图, 从零到一找到解决方案; 第二阶段编码更像是搭积木, 根据自己设计的图纸一步一步搭建自己的城堡, 在编码时应该是按图索骥水到渠成的, 看起来很美好对不对? 实际上系统设计阶段所花费的时间和精力往往被低估, 需要验证可行性, 技术选型, 需求分析, 与产品经理反复确认需求再说编码阶段, 如果时间充足, 编码过程是很美好的, 但如果工期很紧, 就是截然不同的工作体验了:

赶进度 = 以最快的方式实现功能 = 牺牲代码质量 = 写屎山代码 = 增加维护成本
人的工作效率是会随着连续工作时间增长而下降的, 加班时间越多, 注意力越难以集中, 作为碳基生物感到愈发疲惫
工作没有正向反馈, 只有负面反馈, 非程序员难以理解开发中的坑, 就像长安的荔枝中的李善德, 一路跋山涉水快马加鞭把荔枝运到了长安, 无人在意途中发生了什么, 这只是本该送到的普通水果罢了, 博得妃子笑是因为荔枝本身香甜可口,荔枝不新鲜了或者没送到才是意外

加班

回到加班这件事上, 到底为什么程序员群体会普遍加班呢?

工时评估时迷之乐观
低估系统迁移工作量, 忽略原系统复杂度和代码量
需求不明确或没有分析透彻, 只看到了整体需求的冰山一角
公司崇尚加班文化 / 内卷文化 / 能者多劳文化
低估了 debug / 联调 / 系统设计所需的时间
所做的功能模块缺少数据或者需要等待其他人开发完前置功能
过于相信队友, 高估了队友的能力
拥有一个不懂技术又喜欢指导一切的领导
团队内缺少专业的产品经理和测试角色
忽略屎山项目的代码阅读成本
忽略前期项目环境搭建和配置的耗时
低估了需求变动导致的额外工作量
忽视文档编写 / 参加会议浪费的时间
莫名其妙的机器思维, 认为人可以像机器一样全神贯注地每天运转至少8小时
项目缩减工期或要求提前完成任务
需求频繁变动, 把新需求当成 bug
工作不被认可影响心情, 用代码量评估工作量, 用 bug 数量确定工作能力, 就像用硬盘大小评估一台电脑的性能, 用发热量作为所有硬件的唯一评估标准
拥有一台卡到想砸烂的电脑, 严重影响编码体验和开发速度
程序的世界中总是充满了各种稀奇古怪的问题, 你总会花时间解决你根本无法预料的报错, 如果遇到了解决不了的问题, 还可能调整方案或推翻设计方案重新设计

内卷

如今就业环境非常恶劣, 一方面劳动力越来越多, 另一方面就业岗位越来越少, 而且降本增效之风已经蔓延到了各行各业, 我们正在陷入一个挣扎的内卷时代, 在这个内卷旋涡中没有人可以独善其身

剧场效应

在一个剧院里，大家都在看戏，突然前排有个观众站起来了，周围的人劝他坐下，他置若罔闻，求助剧场管理员，管理员却不在岗位。

于是逐渐整个剧院的人都站起来了，大家看到的是跟之前一样的视角，但每个人都更累了。

更悲剧的是，虽然大家都叫苦叫累，但不会有人选择坐下来，因为坐下就真的什么都看不到了。

被硅基生物取代?

在 ChatGPT 诞生之前, 应该很少有人会考虑这个问题, 但在 AI 具备越来越强大的工具属性, 甚至能嗅到 AGI 的意味之后, 这个问题的答案仿佛无限趋向于肯定

碳基生物最大的缺点就是饿了要吃饭, 困了要睡觉, 如果有一种程序员可以不知疲倦的 24h 敲代码, 没有性格缺陷, 听从指挥任劳任怨, 那老板们岂不是做梦都要笑醒?

在可以预见的未来, AI 会取代相当一部分程序员岗位, 这取决于 AI 进化的速度

限于篇幅, 以后有时间会单独写一篇文章

吃喝

甏肉

图为济宁甏肉, 口感软糯肥而不腻, 这不就是把子肉吗, 为什么叫甏肉？

甏：一种盛放食物的器皿

在北宋年间，这里的水泊梁山就成了好汉们的聚义地。随着梁山名气渐大，投奔而来的英雄剧增，普通炊具做饭量少愈慢。厨房伙计无奈之下用腌咸菜的大甏（beng，四声）充当炊具。把大块五花肉放在甏中，加老汤，填葱姜，佐料适中，将甏置于挖好的坑中，用干柴引火，木炭燃料，慢火细炖，逐渐甏内如玛瑙般微泡四起，肉香扑鼻，碳白火暗。取大勺每人满碗，大块肉放入嘴中，闭口间，肉已滑入肚内，爽滑至极，却不油、不腻。饮大坛米酒，顿觉满口生津，荡气回肠。虽不是山珍美味，也没有精挑细选，然大块吃肉、大口喝酒，已是赛似神仙般逍遥快活，越发彰显出梁山英雄的豪迈气概。

葡萄鸡丁

图为葡萄鸡丁, 黑暗料理, 口味偏甜, 吃不惯, 好好的葡萄为什么要炒它?

醋溜肉丝

口感不错, 很合胃口

大盘面条鸡

真的好大一盘, 桌子都显得小了, 底下还有面条

四孔鲤鱼

图为四孔鲤鱼, 就是有四个鼻孔的鱼, 其实味道跟普通的鲤鱼差不多

在微山湖周围，有着丰富的关于微山湖鲤鱼的掌故和传说。孔圣人的夫人生了孩子，鲁国国君专派人送了一条活鲤鱼祝贺，孔子因此给儿子取名孔鲤，可见孔子对鲤鱼的喜爱。明朝正德皇帝沿京杭运河南巡，住在微山湖南岸庙道口宋家楼，在李翠莲开的酒肆里吃到了李翠莲做的湖水炖湖鱼（鲤鱼），龙颜大悦，与年轻美貌的李大姐演绎了一场浪漫佳话，在当地传诵至今。乾隆皇帝游江南，亦过微山湖，也吃到了微山湖鲤鱼，赞赏之余，又把微山湖鲤鱼封为贡品，从此微山湖鲤鱼年年上到皇宫龙宴。明末清初，微山湖西岸出了一个大诗人阎尔梅，诗文中对微山湖鲤鱼亦是非常喜爱，“烟水昭阳万顷漩，香城隐隐住琴仙；我来闲访红鲤市，偏有邻家认酒钱。”四孔鲤鱼的特点是头小背宽，乌红发亮，身长而健，只有尾巴是红色，而且是有四个鼻孔、四个鱼须，这种外形是微山湖鲤鱼所特有的。鱼的肉质非常鲜嫩，为微山湖区宴席中上品佳肴。之所以是地方特产，就是说换个地方，离开这湖水就没这特点了。所以鲤鱼虽到处都有，但此鲤鱼非彼鲤鱼，你只有在湖区才能品到这鲤鱼。

济宁家宴

图为酒爵, 据说是古代喝酒的容器

店内的变脸表演

民谣酒馆

图为 <a href="https://surl.amap.com/ji10ZYdgfZN" target="_blank">吴陆柒民谣酒馆</a>, 位于秀水河, 周围都是酒馆

每晚九点有驻场歌手弹唱表演

玩乐

宿舍附近的台球厅, 距离宿舍非常近, 所以经常光顾

压抑的环境需要释放一些多巴胺来缓解

探索

济宁市博物馆

博物馆人很少, 现场扫码预约即可

图为博物馆中心位置, 楼内的廊道螺旋向上, 可以从一楼一直走到五楼

图为楼内视角

图为孔子和他的学生

图为悟空

窗外为太白湖(市民公园部分)

济宁市美术馆

人流量很少, 无需预约

图为济宁市美术馆入口处, 馆内有非常多济宁学院美术学院的学生作品

星期一的晚上

续章

猫

花

婚礼

剧场

xxx

共生系列插画设计

孔庙

图为孔庙入口处的城门万仞宫墙, 可以看到里面一排的牌坊

图为棂星门, 皇帝祭天时, 要先祭棂星, 在天文学上, 棂星属于恒星;

图为勾心斗角, 十三碑亭院内, 大成门房檐的一端插入了另一座房屋的两层屋檐的中心位置, 这就是所谓的“钩心”。屋檐的左右四角相对，即所谓的“斗角”。按孔庙的建筑发展，清代碑亭应建在大中门前，清皇帝为了显示自己，将碑拥挤在各碑亭之前，故在此院内出现了双檐穿插交错的拥挤现象。

<video controls width="100%" src="/static-videos/jining-dachengdian.mp4"></video> 图为 大成殿, 大成殿为孔庙中的正殿，亦为孔庙中的核心建筑单体，唐代时称为文宣王殿，宋崇宁三年（1104）宋徽宗以《孟子.万章下》“孔子之谓集大成”之义，下诏将曲阜孔庙正殿更名为大成殿，宋政和四年（1114）又颁诏谕定天下孔庙正殿均更名大成殿，元代称宣圣殿，明代称先师庙，清代复称大成殿，意为“集古圣先贤之大成”。

图为龙柱, 曲阜孔庙大成殿的四周回廊有２８根高约６米的浮雕龙石柱环绕，石柱全为整石雕刻，共１２９６条神态各异团龙。前檐十根龙柱最精美。滚龙柱采用徽州深浮雕刻工艺，由徽州巧匠制成，10根龙柱各具变化，无一雷同。她是孔庙最为神奇的珍宝，其艺术价值之高，超过故宫金銮殿的贴金龙柱。

图为龙柏树

孔府

图为重光门

南孔

图为全国部分孔庙书院等儒家文化遗产分布图, 其实历经千年, 基本上历朝历代都将孔子奉为圣人, 孔家地位也非常崇高

但并不是所有的孔家后裔都在曲阜, 最为著名的是北宋末年南迁的孔子嫡长孙孔端友分支, 称为南孔, 其弟弟孔端超分支则世代守在曲阜

靖康之难后，建炎二年（1128年）十一月，宋高宗赵构于扬州行宫举行继统后首次祀天大典，衍圣公孔端友与堂叔孔传奉诏陪位。孔端友返回曲阜后，因金兵大举入侵，遂恭负传家宝“孔子及亓官夫人楷木像”（据传为子贡亲手雕刻）、“唐吴道子绘孔子佩剑图”和“至圣文宣王庙祀朱印”等，与部分族人南迁，后家于浙江衢州。其子孙孔玠、孔搢、孔文远、孔万春、孔洙依次承袭衍圣公，史称南宗。

元朝灭南宋后的至元十九年（1282年），元世祖议立孔子后，以寓衢者为大宗，欲召孔洙回曲阜袭封奉祀。**孔洙称先代庐墓在衢州，不忍离去，乃辞让。**元世祖大加赞赏，称孔洙“宁违荣而不违亲，真圣人后也”。于是下诏免去孔洙的衍圣公爵号，任命其为国子祭酒、承务郎，兼提举浙东学校事，并赠给保护南宗林庙的玺书。同时，为避免南北两宗发生争执，又制定了《整治孔子弟子违犯家规》，既不许违犯圣朝授爵制度，亦不准背忘孔洙德让之风范。南宗失去爵位后，地位日衰，一度猥如庶氓。

弘治十八年（1505年），衢州知府沈杰拟〈为条陈孔氏家规以彰圣教〉，上奏明孝宗，“乞将衢州孔端友子孙一人，添授以世袭翰林院五经博士一员，以主家庙祭祀”。明武宗正德元年（1506年），遂 册封五十九代孙孔彦绳为正八品翰林院五经博士，子孙世袭。

民国二年（1913年），北洋政府颁布《崇圣典例》，保留衍圣公爵位，仍由北宗的前清衍圣公孔令贻袭爵，改南宗五经博士孔庆仪为大成至圣先师南宗奉祀官，世袭, 1923年冬，孔庆仪去世，其子孔繁豪袭任。国民政府北伐后，孔令贻之子、衍圣公孔德成有感世袭爵位不宜存于民国，遂于1935年主动请求政府撤销爵号。国民政府以为道统不可废，乃改衍圣公作大成至圣先师奉祀官，享特任官的职位及待遇，相当于部长；而孔繁豪仍任大成至圣先师南宗奉祀官，享简任官职位及待遇，约比照司长级，视特任官官阶为低，与孟子“亚圣”、颜子“复圣”、曾子“宗圣”、子思“述圣”奉祀官同等级。1944年10月，孔繁豪去世，无子，乃以其二弟孔繁英长子孔祥楷受封。1949年，孔祥楷未随国民政府迁台，南宗奉祀官世职遂废。

徐州

来济宁两个月了, 还没有出去玩一玩, 利用周末去了趟徐州

图为地锅鸡, 看起来很小的一锅, 实际上也并不大, 应该是这家店的问题

图为餐馆里的猫

图为回龙窝的刘姥姥酸梅汤

图为洛馍卷馓子

徐州地铁, 居然有马车标志

云龙山

图为观景台, 可以一览云龙湖和城区的景色

徐州市博物馆

预约购票

进入博物馆游览有两种方式:

免费预约: 根据微信公众号的官方公告, 提前一周的 20:00 放票, 其次是当天动态放票, 但如果你翻翻小红书就会发现, <span style="color: red;">每天 8:55 到 9:00 会放出大约一千张票, 这个大量放票的时间点官方只字未提</span>
付费购买特展门票(45 💰): <span style="color: red;">只要花钱就能进!!!</span>

这种预约规则, 你品, 你细品

对于没有提前一周 20:00 准时抢票的游客来说, 基本上 每次打开预约页面都显示已约满, 这是非常糟糕的预约体验!

预约页面

预约页面同样设计的令人反感, 好像故意阻碍我预约:

必须先进入预约页面才能填写预约人信息, 等你填好预约人信息, 票早就被别人抢到了
每天全天候不定时放票(每次只有几张), 而且每次都是秒无, 这只有刷票脚本才能秒约上吧

首先, 如果你从未预约过, 并且打开预约页面就是全约满的情况, 那么恭喜你, 你不仅预约不上, 你连预约人的个人信息也没法填写, 在全约满的情况下, 没办法提前填写预约人信息!

解决方案就是, 找到有余票的时间段, 大概率这不是你想要游览的时间段, 点击立即预约, 并填写个人信息, 并且不能提交预约

这个页面还有另外一个坑, 就是你必须点击日期和时间段, 才能点立即预约, 然后进入真正的预约页面:

如果你要预约的时间恰好有余票, 你需要:

点击时间
点击时间段
点击立即预约
选择预约人(没有填写过需要先添加)
输入手机号(这里没有对手机号进行验证码验证, 也就是说你可以填写任意手机号)
点击提交预约

如果这些你都做完了, 你也抢不到票, 因为这时候仅有的几张余票已经没了

预约攻略

首先你要等到你预约的时间段有余票, 然后点击进入预约页面

然后正常选择预约人信息, 点击提交预约的时候会报错: 当前时间余票不足, 请重新选择, 这时 不要离开这个页面, 要继续不停地点击提交预约按钮, 因为每点击一次都会发起一个请求, 等到下次有余票了, 恭喜你, 你会以秒级的预约时间击败所有人, 成功完成预约

如果你连续点击了 30 次 提交预约, 那么恭喜你, 触发了彩蛋, 这时直接显示了 vConsole, 通过查看 Network, 我们发现这跟我预想的一样, 只要请求的频率够快, 就大概率可以成功预约上

图为接口返回的 json 数据

图为预约成功页面

展品

在一楼展厅门口就有自助寄存的提示牌

可以在一楼自助寄存行李

看起来像是存钱罐?

这枕头感觉好硬, 枕着不会头疼吗

图为金缕玉衣

参考

2025 扬州南京之行(多图)

Mon, 12 May 2025 00:00:00 GMT

图为南京秦淮河畔平江桥夜景, 拍摄地为旁边的东元桥, <a href="https://surl.amap.com/1WXisGkd6qC" target="_blank">点击查看拍摄地</a>

前言

2025 年 5 月份, 我迎来了职业生涯最长的空窗期; 乐观来看, 这是难得的放松休息的机会, 但人是一种奇怪的动物, 当生活没有被日程填满时, 就会被焦虑反噬; 除此之外, 还要面对大环境下的各种不确定性, 对当下的焦虑和对未知的恐惧情绪让我感觉必须出去走走了 😨

出游规划

5 月份迎来了夏天, 恰逢五一假期, 回想起经历过的节假日糟糕的出行体验, 我决定五一假期期间我就不出去了 🤔, 待假期结束就出发

在选择路线时, 我规划了两条路线:

郑州 ➡️ 西安
扬州 ➡️ 南京

这两条路线都很不错, 有我想去玩的地方, 例如很久之前我就刷到了 ▶️ 只有河南戏剧幻城, 对于喜欢看舞台剧的人来说简直太有吸引力了, 虽然这次没去, 下次一定 😏

最终我选择了扬州南京, 因为我更想去南京

行程规划

出发前做了各种规划, 基本按计划都完成了, 但应为天气原因和预约的原因有一部分没有完成, 后文细说

具体规划如下:

扬州
- <a target="_blank" href="https://surl.amap.com/4Gh5sYDBcoK">中国大运河博物馆</a>
- <a target="_blank" href="https://surl.amap.com/ucEumud1u2Dt">江泽民故居</a>
- <a target="_blank" href="https://surl.amap.com/tWy9jq91beCt">瘦西湖景区</a>
- <a target="_blank" href="https://surl.amap.com/uorntoVSb0G">东关街</a>
南京
- <a target="_blank" href="https://surl.amap.com/9PUJVhUe4s">侵华日军南京大屠杀遇难同胞纪念馆</a>
- <a target="_blank" href="https://surl.amap.com/6NGE1cY0L1EH">秦淮河</a>
- <a target="_blank" href="https://surl.amap.com/1blzNSJkgqi">南京博物院</a>
- <a target="_blank" href="https://surl.amap.com/eeqQTI192OH">中山陵</a>
- <a target="_blank" href="https://surl.amap.com/D3gSOHK4OB">灵谷景区</a>

扬州

在去扬州之前, 能想到的关于扬州的东西可能就只有江南园林和扬州炒饭 🍚 了, 但在历史上, 扬州是古九州之一, 因其重要的地理位置和优越的自然环境, 在历朝历代几乎都是繁华的工商业城市

大运河

在古代漕运是非常重要的物资运输方式, 漕粮更是国家战略物资

扬州地处大运河的重要节点, 图中可以看到重要的港口城市如今都已衰落, 主要原因如下:

黄河改道导致运河山东段逐渐淤废
现在海运和铁路运输非常发达

江南丝织业发达, 图为丝锦龙袍和龙泉窑碎片

镇水文化历史悠久, 图为三神石人, 为开凿都江堰的李冰, 被古人奉为水神

大运河博物馆楼顶, 视野开阔, 可以看到整个扬州市区, 右侧的阁楼需付费购票进入, 以下是楼顶的视角

大运河博物馆旁边就是古运河, 近处的桥为剪影桥

古运河中的游船

瘦西湖

瘦西湖是扬州著名景点, 随处都有江南水乡的意境, 只是门票略贵, 白天 💰 100, 晚上更贵

瘦西湖名称的来历，是乾隆年间寓居扬州的诗人汪沆的一首感慨富商挥金如土的诗作:“ 垂柳不断接残芜，雁齿红桥俨画图；也是销金一锅子，故应唤作瘦西湖。”

图为二十四桥, 唐代诗人杜牧有流传千古代诗篇《寄扬州韩绰判官》：“青山隐隐水迢迢，秋尽江南草未凋。二十四桥明月夜，玉人何处教吹箫？”

徐园门外深情对望的狮子 🦁

极速前进的小鸭子

江泽民故居

由于江老的名字是敏感字, 所以在小红书上搜索不到任何帖子, 在抖音上也只能搜到一模一样的重复的文案, 很少有介绍如何预约的文章

等我找到预约方式时, 就只能预约下周的了, 所以很遗憾 😭 没有去成

预约方式为: 微信小程序直接搜索以上关键字, 进入小程序, 并且至少提前一周预约, 根据预约须知, 内部不能拍照, 地址在 <a target="_blank" href="https://surl.amap.com/ucEumud1u2Dt">东关街附近</a>

南京

都说 一座南京城, 半部民国史, 也有 南京是亡国之都 的说法, 南京城也是六朝古都, 十朝都会, 但近代民国时期的国力孱弱和战争历程, 也使得我们每每提到南京时, 都会想到它的波折跌宕的历史

梧桐树

南京城区的梧桐树, 南京真的路边都是梧桐树, 当然最好看的还是 🔗 梧桐大道, 位于钟山风景区南京梧桐大道

鸭血粉丝汤

鸭血粉丝汤和烤鸭包, 汤鲜味甜

侵华日军南京大屠杀遇难同胞纪念馆

在南京这片土地上, 发生过惨绝人寰的南京大屠杀, 这对南京人乃至中华民族来说都是一段痛苦沉痛的记忆, 但我们尊重历史, 也尊重遇难同胞, 所以我们在 1985 年江东门集体屠杀遗址和万人坑遗址上建起了这座纪念馆, 以告慰遇难同胞, 在展示大屠杀的残酷血腥的同时, 也向全世界展示了我们珍爱和平, 维护和平的决心

时间线

1937 年 8 月 13 日, 日军进攻上海, 中国军队顽强抵抗了三个月才攻破沿岸地区, 也就是惨烈的淞沪会战
1937 年 11 月中旬, 日军决定进攻首都南京
1937 年 11 月 20 日，蒋介石任命唐生智为南京卫戍司令官, 固守南京
1937 年 12 月 8 日，日军全面占领南京外围阵地
1937 年 12 月 13 日, 南京沦陷, 日军开始了惨无人道的大屠杀, 日军犯下了一系列罄竹难书的反人类罪行, 持续 6 周以上

雕塑

图为雕塑《家破人亡》, 充满了绝望与无助

公祭广场

使用 11 种文字展示的 遇难者 30 万

馆内

馆内展品很多, 让人感觉心情特别沉重, 只拍了很少的一部分:

南京保卫战部分殉国将士名录

馆外

图为和平雕像

南京下起了大雨, 我在雨中参观了遇难同胞纪念馆

南京博物院

博物院内的网红🐴 太抽象了

钟山风景区

钟山风景区非常大, 包含了: 明孝陵 / 美龄宫 / 中山陵 / 灵谷景区等, 由于时间关系我只去了中山陵和灵谷景区

行程

🚌 乘坐观光车 1 号线从 🚇 苜蓿园站前往中山陵南站, <a href="https://surl.amap.com/3bbYa051hcqi" target="_blank">点击查看路线</a>

🚌 乘坐观光车 4 号线到达灵谷景区, <a href="https://surl.amap.com/2uICGHz1efcx" target="_blank">点击查看路线</a>

💡 注意: 景区观光车 💰 10 块一次, 包天 💰 30 块, 建议根据导航优先乘坐普通公交车

中山陵

中山陵是孙中山先生的陵墓, 孙先生逝世后国民政府遵照他的遗愿在南京为其修建陵墓, 中山陵吸取中国古代陵墓的对称布局，利用墓道和台阶将主要建筑连为轴线，并布置大片绿地，将陵墓建筑群联接成与背景山势相称的宏大整体。陵墓主体建筑采用中国古典宫殿式建筑的大屋顶造型，应用西方建筑的设计和建造技术，以肃穆的蓝白色调和严谨的建筑构型表现出沉静恢弘的气度，被认为是中国近现代建筑史上融合中西的经典作品

图为前往中山陵的路上, 没想到避开了节假日和周末, 还是没有避开学生和老年团 😭, 人还是很多

图为博爱坊 📌, 中门横楣上的石额刻有孙中山手书的“博爱”二个鎏金大字

图为陵门 📌, 陵门是中山陵的正门, 处于中山陵中轴线正中, “天下为公”出自《礼记·礼运》之“大道之行也，天下为公。” 孙中山将“天下为公”借用为对“民权主义”的解释，说明政权为广大平民所共有, 这一思想对于近代中国的思想观念的转变具有重要意义

图为碑亭 📌, “中国国民党葬总理孙先生于此中华民国十八年六月一日”，由谭延闿以颜体书写

祭堂

祭堂位于中山陵最顶部

门楣上方的额枋上从东到西分别为张静江所书写的“民族”、“民权”、“民生”六个篆书金字，代表国父孙中山创立的三民主义的三个组成部分。正中间的民生门略大，上下重檐之间嵌有直额，上刻有孙中山所题“天地正气”四个金字

祭堂内部需要从右侧排队进入参观

在祭堂顶部眺望南京城区

在祭堂顶部俯瞰陵门

孙中山纪念馆

灵谷景区

灵谷胜境

阵亡将士公墓牌坊

无梁殿

该殿建于洪武十四年（1381年），原为灵谷寺内供奉无量寿佛的无量殿，因为整座建筑采用砖砌拱券结构、不设木梁，因此又称“无梁殿”。民国二十一年（1931年），国民政府将无梁殿改建为国民革命军阵亡将士公墓的祭堂，命名为“正气堂”

淞沪抗战阵亡将士纪念碑

图为第十九路军淞沪抗战阵亡将士纪念碑, 第十九路军是一支粤军, 淞沪抗战在淞沪会战之前, 第十九路军也是首个与日军全面对抗的中国军队, 以几乎全军覆没为代价抵抗了日军多次进攻

图为第五军淞沪抗战阵亡将士纪念碑, 1月30日，中国国民政府宣布迁都洛阳，蒋通电抗日，并派精锐之第五军增援上海

秦淮河

参考

Cherry Studio MCP 初体验

Sun, 27 Apr 2025 00:00:00 GMT

前言

在 LLM 被普遍使用的今天, MCP 大大提升了 LLM 的实用性和本地化操作的能力, 本文将介绍如何基于 Cherry Studio 来体验 MCP 的强大能力

其实在选择支持 MCP 的客户端时, 我更加倾向于使用 vscode, 因为它使用的是 Github Copilot, 而且已经在最新版对 MCP 进行了支持, 但 vscode 需要付费才能自定义使用的模型, 所以我选择了更加通用的免费的 Cherry Studio, 当然现阶段还有其他的支持 MCP 的客户端, 这里我选择了 Cherry Studio

安装

Cherry Studio

直接从 download page 下载

然后需要创建 ~/.cherrystudio/bin 目录, 用于存放 bun / uv / uvx, 这是 Cherry Studio MCP 服务所需的依赖, 可参考官方文档

mkdir -p ~/.cherrystudio/bin

官方只使用 ~/.cherrystudio/bin 中的 bun / uv / uvx, 而不是全局的 bun / uv / uvx, 这很令人不解, 这里选择手动全局安装, 然后软连接到 ~/.cherrystudio/bin, 下面将介绍如何安装及配置这些依赖

bun

我是 MacOS 和 fish shell, 以下命令适用于我的环境, 下文不再赘述; 其他系统安装参考官方页面 installation - bun

curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL
source ~/.config/fish/config.fish # 重新载入环境变量
sudo ln -s $(which bun) ~/.cherrystudio/bin/bun # 将 bun 软链接到 ~/.cherrystudio/bin/bun

uv

其他系统安装参考官方页面 installation - uv

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env.fish # 重新载入环境变量
sudo ln -s $(which uv) ~/.cherrystudio/bin/uv
sudo ln -s $(which uvx) ~/.cherrystudio/bin/uvx

检查 mcp 安装

进入设置 -> MCP 服务器

使用 MCP

添加 MCP 服务

这里我们以高德地图官方的 MCP Server 为例:

进入 Amap Maps - mcp.so
找到 服务器配置, 按照配置中的 command / args / env 创建 MCP 服务器

进入高德地图开放平台控制台, 进入 应用管理 -> 创建新应用, 服务平台选择 Web 平台, 然后在 我的应用 中找到 Key, 并复制到 Cherry Studio 中新创建的 高德地图 服务中
点保存并启用
新建聊天并选择我们刚创建的 Amap Maps 服务

翻车了朋友们 😓, 天津南站明明有地铁站, 竟然让我步行到下瓦房站; 在查看高德地图的 tools 时发现, 大模型没有调用 maps_geo, 正确的调用方式应该是:

调用 maps_gep, 获取起点和终点的准确经纬度
调用 maps_direction_transit_integrated, 传入起点和终点经纬度, 获取行程信息
调用 maps_around_search 获取周边酒店信息

[!TIP] 看来 LLM 的能力才是最基本的, 一个好的模型才能发挥 MCP 的能力, 这里我用的是 qwen-turbo, 属实拉胯

参考

使用 certbot 自动续签 Let's Encrypt 免费证书

Sun, 27 Apr 2025 00:00:00 GMT

现在阿里云的免费证书有效期只有 3 个月, 过期之后还要重新签发 😡, 所以我开始尝试寻找免费可自动续签的证书服务, 就是使用 Certbot 配置 Let's Encrypt 免费证书

介绍

Let's Encrypt

Let's Encrypt: 这是一个由非营利性组织互联网安全研究小组（ISRG）提供的免费、自动化和开放的证书颁发机构。它为众多网站提供 TLS 证书，其免费证书的签发/续签可以通过脚本自动化完成, 简而言之就是可以免费一直用

certbot

Let's Encrypt 使用 ACME 协议来验证您对给定域名的控制权并向您颁发证书。要获得 Let's Encrypt 证书，您需要选择一个使用 ACME 客户端软件, 而 Certbot 就是 Let's Encrypt 推荐的客户端

安装 cerbot

:::tip 服务器环境为 Ubuntu 22.04 :::

sudo snap install --classic certbot
# sudo apt-get install certbot # 或者使用 apt 安装

安装 aliyun cli

wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz
tar xzvf aliyun-cli-linux-latest-amd64.tgz
sudo cp aliyun /usr/local/bin
rm aliyun

配置 aliyun cli

创建 RAM 用户, 参考创建 RAM 用户的 AccessKey
点击 权限管理 -> 新增授权, 为 RAM 用户添加 DNS 解析相关的权限(可在权限列表中搜索 DNS)

点击 认证管理 -> AccessKey, 创建 AccessKey
配置 AccessKey 的网络访问权限
执行 aliyun configure

aliyun configure
Configuring profile 'default' in 'AK' authenticate mode...
Access Key Id [*********************SQK]:
Access Key Secret [***************************LJL]:
Default Region Id [cn-hangzhou]:
Default Output Format [json]: json (Only support json)
Default Language [zh|en] zh:
Saving profile[default] ...Done.

Configure Done!!!
..............888888888888888888888 ........=8888888888888888888D=..............
...........88888888888888888888888 ..........D8888888888888888888888I...........
.........,8888888888888ZI: ...........................=Z88D8888888888D..........
.........+88888888 ..........................................88888888D..........
.........+88888888 .......Welcome to use Alibaba Cloud.......O8888888D..........
.........+88888888 ............. ************* ..............O8888888D..........
.........+88888888 .... Command Line Interface(Reloaded) ....O8888888D..........
.........+88888888...........................................88888888D..........
..........D888888888888DO+. ..........................?ND888888888888D..........
...........O8888888888888888888888...........D8888888888888888888888=...........
............ .:D8888888888888888888.........78888888888888888888O ..............

[!TIP] 输出最后的阿里云 logo 图案表示配置成功

安装 certbot-dns-aliyun 插件

::github{repo="justjavac/certbot-dns-aliyun"}

wget https://cdn.jsdelivr.net/gh/justjavac/certbot-dns-aliyun@main/alidns.sh
sudo cp alidns.sh /usr/local/bin
sudo chmod +x /usr/local/bin/alidns.sh
sudo ln -s /usr/local/bin/alidns.sh /usr/local/bin/alidns
rm alidns.sh

申请证书

测试是否能正确申请证书

certbot certonly -d "*.example.com" --manual --preferred-challenges dns --manual-auth-hook "alidns" --manual-cleanup-hook "alidns clean" --dry-run

The following error was encountered:
[Errno 13] Permission denied: '/var/log/letsencrypt/.certbot.lock'
Either run as root, or set --config-dir, --work-dir, and --logs-dir to writeable paths.
Ask for help or search for solutions at https://community.letsencrypt.org. See the logfile /tmp/certbot-log-4krk5x0b/log or re-run Certbot with -v for more details.

[!TIP] 把 example.com 替换为实际的域名

这里我们使用的是非 root 用户, 所以是没有 /var/log/letsencrypt 的访问权限的, 所以我们根据提示信息配置生成的目录:

certbot certonly -d "*.example.com" --config-dir $HOME/.certbot/config --work-dir $HOME/.certbot/work --logs-dir $HOME/.certbot/logs --manual --preferred-challenges dns --manual-auth-hook "alidns" --manual-cleanup-hook "alidns clean" --dry-run
Saving debug log to /home/admin/.certbot/logs/letsencrypt.log
Enter email address or hit Enter to skip.
 (Enter 'c' to cancel):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at:
https://letsencrypt.org/documents/LE-SA-v1.5-February-24-2025.pdf
You must agree in order to register with the ACME server. Do you agree?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: Y
Account registered.
Simulating a certificate request for *.example.com
Hook '--manual-auth-hook' for example.com ran with output:
 {
 	"RecordId": "1234",
 	"RequestId": "5678"
 }
Hook '--manual-cleanup-hook' for example.com ran with output:
 {
 	"RecordId": "1234",
 	"RequestId": "5678"
 }
The dry run was successful.

其中 ~/.certbot/config 是存放证书和私钥的目录, 请按照实际情况进行修改

[!TIP] 此命令申请的是 *.example.com 的证书, 如需同时申请顶级域名或其他 多个域名的证书, 可以增加 -d example.com 参数生成, 并增加 --cert-name 指定生成的目录(因为生成顶级域名和子域域名证书时, 生成的目录名可能重复, 此时会生成例如 example.com-0001 的目录名)

正式申请证书

把 --dry-run 参数去掉就可以申请到证书了, 只要有 --dry-run 参数时执行成功, 就可以正确生成证书了

最终的命令如下:

# 1. 申请顶级域名的证书
certbot certonly -d "example.com" --cert-name "example.com" --config-dir $HOME/.certbot/config --work-dir $HOME/.certbot/work --logs-dir $HOME/.certbot/logs --manual --preferred-challenges dns --manual-auth-hook "alidns" --manual-cleanup-hook "alidns clean"

# 2. 申请一级子域名通配符证书
certbot certonly -d "*.example.com" --cert-name "all.example.com" --config-dir $HOME/.certbot/config --work-dir $HOME/.certbot/work --logs-dir $HOME/.certbot/logs --manual --preferred-challenges dns --manual-auth-hook "alidns" --manual-cleanup-hook "alidns clean"

证书续期

certbot renew --manual --config-dir $HOME/.certbot/config --work-dir $HOME/.certbot/work --logs-dir $HOME/.certbot/logs --preferred-challenges dns --manual-auth-hook "alidns" --manual-cleanup-hook "alidns clean"
Saving debug log to /home/admin/.certbot/logs/letsencrypt.log

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /home/admin/.certbot/config/renewal/all.example.com.conf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Certificate not yet due for renewal

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /home/admin/.certbot/config/renewal/example.com.conf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Certificate not yet due for renewal

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
The following certificates are not due for renewal yet:
  /home/admin/.certbot/config/live/all.example.com/fullchain.pem expires on 2025-07-26 (skipped)
  /home/admin/.certbot/config/live/example.com/fullchain.pem expires on 2025-07-26 (skipped)
No renewals were attempted.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

配置定时自动续期

crontab -e

# certbot renew
1 1 */1 * * bash -l -c 'source /home/admin/.profile && certbot renew --manual --config-dir $HOME/.certbot/config --work-dir $HOME/.certbot/work --logs-dir $HOME/.certbot/logs --preferred-challenges dns --manual-auth-hook "alidns" --manual-cleanup-hook "alidns clean" --deploy-hook "sudo nginx -s reload"'

这里我用的是 admin 用户, 而不是 root, 所以 source /home/admin/.profile 是为了加载 admin 用户的环境变量

配置 nginx

配置一下 nginx 配置文件, 创建一个软连接将指定域名的证书文件链接到我们生成的证书目录下

server {
  listen 443 ssl;
  server_name example.com;
  charset utf-8;

  ###### certbot START ########
  #填写证书文件绝对路径
  ssl_certificate conf.d/certbot/example.com/fullchain.pem;
  #填写证书私钥文件绝对路径
  ssl_certificate_key conf.d/certbot/example.com/privkey.pem;
  ###### certbot END ########

	ssl_session_cache shared:SSL:1m;
	ssl_session_timeout 5m;

	#自定义设置使用的TLS协议的类型以及加密套件（以下为配置示例，请您自行评估是否需要配置）
	#TLS协议版本越高，HTTPS通信的安全性越高，但是相较于低版本TLS协议，高版本TLS协议对浏览器的兼容性较差。
	ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
	ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;

	#表示优先使用服务端加密套件。默认开启
	ssl_prefer_server_ciphers on;

  # example.com => blog.example.com
  rewrite ^/(.*)$ https://blog.example.com/$1 permanent;
}

其中 ssl_certificate 是证书文件路径, ssl_certificate_key 是证书私钥文件路径

sudo ln -s /home/admin/.certbot/config/live/example.com /etc/nginx/conf.d/certbot/example.com
sudo ln -s /home/admin/.certbot/config/live/all.example.com /etc/nginx/conf.d/certbot/all.example.com

[!TIP] 这里根据实际情况进行配置, 以上路径只是实例

最后在浏览器中查看证书信息:

如果颁发者组织是 Let's Encrypt, 表示配置成功 🎉

参考

2025 天津之行(多图)

Fri, 25 Apr 2025 00:00:00 GMT

前言

2025 年的我已经无限接近 30 岁, 回顾最近几年, 好像一直忙于工作, 传统观念中的三十而立已至, 然而我的生活却毫无变化;

最近看到一句话, 人无法判断一个瞬间的价值, 直到它成为回忆; 我无法确定这个瞬间是指什么, 但肯定不是指日复一日的敲代码, 也不是指每天上下班的路途, 或许我的生活 缺少值得回忆的瞬间, 我有点理解人为什么都期待旅行, 因为旅行可以使自己跳出物理生活圈, 感受旅途中的每一件事物, 或许这就是瞬间的价值;

如果人生是一场开放世界游戏, 那么旅行就是一个个支线任务, 它是感受游戏世界的绝佳机会

行程规划

酒店: 考虑到要去滨海区, 所以选择了 9 号线附近, 并且最好是中转站, 所以选择了直沽附近, 附近的酒店是真贵啊, 普通的周末最便宜的房间三百多 😭
行程:
- 天津站附近
- 五大道
- 海港公园
- 天津博物馆

备忘录中的攻略截图:

实际走下来, 最值得去的是天津博物馆和意风区

启程

在周五晚从我所在的城市坐 🚄 出发, 可以到达天津, 虽然要中转, 但 3h 就能到, 所以其实天津是很近的

由于高铁晚点 14 min, 所以直到 22:50 才到天津南站 🚉, 原本计划坐 1h 地铁, 但时间太晚了, 坐到营口道站就打车去了酒店, 到达酒店就已经 23:50 了

刚进门就发现门框快掉下来了, 真是毫不避讳, 然而我已经困得不行了 😴, 马上就休息了一下睡觉了

天津站附近

津湾广场

坐地铁到达 🚇 津湾广场站, 对岸就是天津站, 解放桥和世纪钟就是城市地标 😎

解放桥 / 海河 / 世纪钟

早期解放桥

这座风格独特、现代感极强的铁桥，出自法国建筑设计大师，巴黎艾菲尔铁塔的设计者居斯塔夫·埃菲尔之手

大沽桥下, 大爷们正在悠闲地钓鱼🎣

大光明桥夜景

天津是沿海河发展的, 所以桥特别多, 而且建造的非常精致, 当年这里是 9 国租界, 如今这里是我国直辖市, 北方第二城

意式风情区

意式风情区 🇮🇹 的一个路口, 商业化非常足, 路口处有天津工业展览馆, 电动三轮车为游客提供讲解服务, 这里可以坐三轮车的, 但我更喜欢步行 🚶

这里的商业化比较严重, 虽然有很多独特的建筑, 但我对建筑不是很感兴趣, 再放几张有意思的照片:

意大利兵营, 现在已经是纯粹的商业区了, 里面有各种餐饮店, 还有画室, 感觉商业化比较严重, 就没进去

充满意大利风情的雕像, 不明白为啥这么多人围着看

游泳大爷

点击播放 ▶️, 据说冬天也会来游泳 🏊🏻

海港公园

海港公园是十年前大爆炸的核心区域, 互联网上几乎没有关于这个公园的介绍, 我为什么要来这里呢? 因为前段时间刷到了这个视频:

这里不再描写当年大爆炸事故的惨烈, 只放一张网图来对比过去和现在:

2015 年我还在上大学, 依稀记得 QQ 群里曾经传过一些爆炸的视频, 问了几个人都说不记得这件事了, 果然 时间是一剂良药, 互联网也是没有记忆的

现在的公园:

公园前广场, 海港公园

海港公园介绍, 没有任何关于大爆炸的记录

漫步在蜿蜒的小路 🚶, 非常解压, 路旁的草地中长满了黄色的小花朵

令人不解的是, 当年爆炸留下的建筑依然没有没拆掉, 不过后面的小区建筑非常干净整洁

天津地铁 9 号线的一辆车, 9 号线大部分路段都在地上

天津博物馆

天津博物馆非常值得一去, 展品质量都很高, 这里只放我感觉好看的部分照片 😁

早上 9:00 开馆, 还没开馆就已经排起了长队

镇馆之宝: 翡翠蝈蝈白菜, 看起来相当漂亮 👍🏻

镇馆之宝: 太保鼎, 鼎身高大、造型厚重、比例匀称, 铸造与西周时期, 是商周青铜器的典型代表

翡翠缠枝菊花纹环耳扁盖瓶, 此瓶由一块大的翡翠料抛开制成一对, 淡翠绿色，间少许淡粉色，色泽均匀柔和，美丽晶莹。此瓶另一看点是工艺高超，雕琢精湛。盖有桃形钮，盖身及瓶两侧镂雕缠枝菊花纹，颈肩镂空花耳上各套一活环，瓶身光素，抛光匀细，椭圆圈足，足下附座，上阴线刻兽面纹。尤其是对花、叶纹饰采用镂雕技法，雕琢更为精细，颇具阿拉伯地域风格，这与翡翠晶莹璀璨的质感交相辉映，为这对高贵典雅的大瓶又增添了一种灵动之感

翡翠以其深稳凝重、变幻莫测的翠绿色和温润柔美的特性受到举国上下的喜爱，特别是以慈禧为代表的统治阶层的青睐，传说慈禧宁要翡翠饰物而不要金刚石头饰贡品，官员们则投其所好，选上等的翡翠进奉，以求名利，因此翡翠又有“皇家玉”、“玉王”之称。天津博物馆展出的这对翡翠大瓶用料为缅甸翡翠且成对保存至今非常难得。

1860 年, 英、法、俄强迫清政府签订了《北京条约》, 天津被迫辟为通商口岸; 英国、法国、美国、德国、日本、奥匈帝国、意大利、俄国、比利时等 9 国先后在天津强设了近 15 平方公里的租界地, 相当于天津旧城的8倍。一大批外国冒险家、传教士、富豪纷至沓来，营建洋行、银号、商店、花园、娱乐场、办公楼，开办仓储、航运、进出口贸易，建立医院、学校，盖洋房，造别墅、戏院

这身衣服惊艳到我了, 黑蓝配色的衣服非常独特, 古朴华贵

总结

非常推荐 天津博物馆 和 意风区, 受限于篇幅还有很多图片没有放上
天津大部分景点在海河边沿河分布, 例如各种桥 / 摩天轮 🎡 / 租界区
个人感觉商业化有点严重, 但这不是问题
如果不想像我一样一天 2w 步, 可以预约海河游船 / 双层观光巴士, 或乘坐电动三轮车

使用 Github Actions 实现掘金自动签到(juejin-helper)

Wed, 19 Mar 2025 00:00:00 GMT

本文介绍如何使用 juejin-helper Github Actions 实现掘金自动签到

juejin-helper

::github{repo="iDerekLi/juejin-helper"}

juejin-helper 是一个掘金自动化签到 / 抽奖 / 沾喜气 / 消除 bug 的自动化工作流, 通过 Github Actions 来实现定时执行, 因此 不需要部署到自己的服务器上

使用

直接 fork juejin-helper 仓库, 或者 fork 我修改过的仓库
仓库 -> Settings -> Secrets -> Secrets and variables -> New repository secret, 添加Secrets变量如下:

Name	Value	Required
COOKIE	掘金网站 `Cookie`, 参考获取 cookies	是
COOKIE_2	多用户, 当需要同时运行多个掘金用户时所需, 支持最多 5 名用户(即COOKIE + COOKIE_2 - COOKIE_5)	否
EMAIL_USER	发件人邮箱地址(需要开启 SMTP)	否
EMAIL_PASS	发件人邮箱密码(SMTP密码)	否
💡 EMAIL_HOST	SMTP 服务器地址	否
EMAIL_TO	订阅人邮箱地址(收件人). 如需多人订阅使用 `,` 分割, 例如: `a@163.com, b@qq.com`	否
DINGDING_WEBHOOK	钉钉机器人WEBHOOK	否
PUSHPLUS_TOKEN	Pushplus 官网申请，支持微信消息推送	否
SERVERPUSHKEY	Server酱官网申请，支持微信消息推送	否
WEIXIN_WEBHOOK	企业微信机器人WEBHOOK	否
FEISHU_WEBHOOK	飞书机器人WEBHOOK	否

这里我们使用邮件通知, 所以只配置了邮箱相关的参数

:::TIP 其中 EMAIL_HOST 是我增加的邮箱 SMTP 服务器地址参数, 在原仓库中是直接从邮箱字符串中截取的, 因为我用的是阿里邮箱网页端, 所以 SMTP 服务器地址为 smtp.qiye.aliyun.com, 需要手动修改, 关于 免费域名邮箱 / 使用阿里邮箱发送文件 可参考我的这些文章:

仓库 -> Actions -> Auto, 检查 Workflows 并启用。

如何获取Cookie

掘金网站Cookie, 打开浏览器，登录掘金, 打开控制台DevTools(快捷键F12) -> Network，复制 cookie, 掘金Cookie有效期约1个月需定期更新.

DevTools截图:

修改执行时间

在原仓库中, 每天 6:30 执行, 可以在 .github/workflows/auto.yml 文件中修改 cron 表达式, 我改成了每天 8:00 执行:

on:
  schedule:
    - cron: "0 0 * * *" # 北京时间上午 08:00
# ...

执行

我们可以等待每天到 8:00 时自动执行, 也可以通过点击 Run workflow 来立即执行这个 Action:

在执行完毕后, 我们将收到一封通知邮件:

部署到服务器

# 使用 rsync 将源码上传到服务器
# 由于阿里云服务器拉取不了 github 仓库代码, 所以只能本地上传
rsync -avz juejin-helper admin@47.69.204.83:/home/admin/projects/

cd projects/juejin-helper && pnpm i
cd workflows && pnpm i
cd ../packages/juejin-helper && pnpm i

这里我们修改一下环境变量名, 增加 JUEJIN_ 前缀:

const env = process.env || {};

module.exports = {
  /* 掘金Cookie */
  COOKIE: env.JUEJIN_COOKIE || env.COOKIE,
  /* 多用户掘金Cookie, 当有1名以上用户时填写, 支持同时最多可配置5名用户 */
  COOKIE_2: env.COOKIE_2,
  COOKIE_3: env.COOKIE_3,
  COOKIE_4: env.COOKIE_4,
  COOKIE_5: env.COOKIE_5,
  /**
   * 邮箱配置
   * user 发件人邮箱, pass, 发件人密码, to收件人
   */
  EMAIL_USER: env.JUEJIN_EMAIL_USER || env.EMAIL_USER,
  EMAIL_PASS: env.JUEJIN_EMAIL_PASS || env.EMAIL_PASS,
  EMAIL_TO: env.JUEJIN_EMAIL_TO || env.EMAIL_TO,
  EMAIL_HOST: env.JUEJIN_EMAIL_HOST || env.EMAIL_HOST,
  /**
   * 钉钉配置
   * https://open.dingtalk.com/document/robots/custom-robot-access
   */
  DINGDING_WEBHOOK: env.DINGDING_WEBHOOK,
  /**
   * PushPlus配置
   * http://www.pushplus.plus/doc/guide/openApi.html
   */
  PUSHPLUS_TOKEN: env.PUSHPLUS_TOKEN,
  /**
   * 企业微信机器人配置
   * https://developer.work.weixin.qq.com/document/path/91770
   */
  WEIXIN_WEBHOOK: env.WEIXIN_WEBHOOK,
  /**
   * server酱推送key
   * https://sct.ftqq.com/sendkey
   */
  SERVERPUSHKEY: env.SERVERPUSHKEY,
  /**
   * 飞书配置
   */
  FEISHU_WEBHOOK: env.FEISHU_WEBHOOK
};

然后设置环境变量:

vim ~/.profile

# juejin-helper
export JUEJIN_COOKIE="your-cookie"
export JUEJIN_EMAIL_USER="no-reply@example.com"
export JUEJIN_EMAIL_PASS="your-email-password"
export JUEJIN_EMAIL_TO="your-email@qq.com"
export JUEJIN_EMAIL_HOST="smtp.qiye.aliyun.com"

最后我们通过 crontab -e 添加一下这个定时任务:

crontab -e

# juejin-helper task
15 8 * * * bash -l -c 'source /home/admin/.profile && cd /home/admin/projects/juejin-helper/workflow && pnpm run checkin'

这会在每天 08:15 执行签到任务

# 手动执行测试一下
cd /home/admin/projects/juejin-helper/workflow && pnpm run checkin

参考

juejin-helper

使用 Lit 创建一个 AI 对话组件库 06 补录总结篇

Tue, 18 Mar 2025 00:00:00 GMT

:::WARNING 本文是断档式记录, 不记录所有改动, 只作为总结, 具体更新可参考源码 :::

举例上一章发布过去了半个月, 没错, 这期间实在是太忙了, 所以这半个月的开发过程并没有做记录 😭, 不过好消息是这个项目顺利发布, 可以在 hyosan-chat - npm 查看这个 package, 或直接前往 github 阅读源码

前言

阅读本章内容需要你熟悉 Lit / Web Components / Shoelace

如果你对只对组件库感兴趣, 可以直接查看本项目源码: hyosan-chat
如果你对组件库搭建或项目工程化感兴趣, 可以查看前面几章的内容:

demo

组件使用了 netlify 部署 demo 页面, 点击查看

夜间模式

在 shoelace 的文档中, 建议使用 link 标签的形式实现 light / dark 样式的引入和切换, 但作为一个组件库, 我们并不能要求所有项目都通过这种方式引入主题样式, 原因是这种方式太过原始, 我们并没有直接提供一种切换主题的方式, 而是让用户直接引入主题的 css, 既没有做到灵活简单, 也没有扩展性和响应式;

因此组件内部实现了动态切换主题样式的功能, 在 hyosan-chat 组件上提供一个主题名称参数 shoelaceTheme, 并通过 HyosanChatTheme class 来实现切换不同的主题

src/utils/HyosanChatTheme.ts:

import shoelaceDarkCss from '@shoelace-style/shoelace/dist/themes/dark.css?inline'
import shoelaceLightCss from '@shoelace-style/shoelace/dist/themes/light.css?inline'

/** shoelace 组件库的主题属性 */
export enum HyosanChatShoelaceTheme {
  shoelaceLight = 'sl-theme-light',
  shoelaceDark = 'sl-theme-dark',
}

/** shoelace 组件库的主题 css 内容 */
export const HyosanChatShoelaceThemes = {
  /** light theme */
  [HyosanChatShoelaceTheme.shoelaceLight]: shoelaceLightCss,
  /** dark theme */
  [HyosanChatShoelaceTheme.shoelaceDark]: shoelaceDarkCss,
}

/**
 * 设置 hyosan-chat 主题
 * @description 用于切换底层组件库 `shoelace` 的主题, `<hyosan-chat>` 组件会根据 `shoelaceTheme` 的值自动切换主题
 */
export class HyosanChatTheme {
  static TAG_ATTRIBUTE = 'data-hyosan-chat-theme'
  static getStyleElement() {
    return document.querySelector(`style[${HyosanChatTheme.TAG_ATTRIBUTE}]`)
  }
  static setStyleElement(theme: HyosanChatShoelaceTheme) {
    const styleElement = HyosanChatTheme.getStyleElement()
    const cssText = HyosanChatShoelaceThemes[theme]
    const cssNode = document.createTextNode(cssText)
    if (styleElement) {
      styleElement.innerHTML = ''
      styleElement.appendChild(cssNode)
    } else {
      const style = document.createElement('style')
      style.setAttribute(HyosanChatTheme.TAG_ATTRIBUTE, theme)
      style.setAttribute('type', 'text/css')
      style.appendChild(cssNode)
      document.head.appendChild(style) // 将包含 shoelace 主题样式的标签插入到 head 中
    }
    HyosanChatTheme._updateThemeClass(theme)
  }
  /** 在根元素上切换 shoelace 主题类 */
  private static _updateThemeClass(theme: HyosanChatShoelaceTheme) {
    document.documentElement.classList.add(theme)
    Object.values(HyosanChatShoelaceTheme).forEach((c) => {
      console.log(c)
      if (c !== theme) {
        document.documentElement.classList.remove(c)
      }
    })
  }
}

src/components/HyosanChat.ts:

import {
  HyosanChatShoelaceTheme,
  HyosanChatTheme,
} from '@/utils/HyosanChatTheme'

@customElement('hyosan-chat')
export class HyosanChat extends ShoelaceElement {
  // ...
  /** shoelace 主题, 可用于切换夜间模式 */
  @property({ reflect: true })
  shoelaceTheme: HyosanChatShoelaceTheme = HyosanChatShoelaceTheme.shoelaceLight 
}

相关改动可参考: feat: 增加切换主题功能

框架适配

最初在做调研时, 发现 web components 是一个 原生技术, 这就代表了它适用于所有框架, 包括 vue / react / angular / ..., 现在组件的基础功能开发完成, 是不是就意味着可以直接在使用这些框架的项目中使用呢? 是也不是

自定义标签没有声明属性和事件
IDE 无法识别自定义标签
各个框架的模板语法不同

一方面 web components 的确是原生技术, 它使用的技术 不依赖于任何框架, 可以直接使用; 但另一方面, 在一个现代化的前端开发环境中, TypeScript 是必不可少的一环, web components 并 没有提供定义自定义标签类型的功能, 编辑器更不会知道当前项目有哪些自定义标签, 以及标签上有哪些属性, 而且更加复杂的是, 在不同的框架中 HTML 的语法都不一样, 例如 vue 的模板语法与 jsx 的模板语法不同, angular 的模板语法与前两者也有差别 ...

为此社区出现了一个 custom-elements-manifest 的库, 用于为不同的框架提供 manifest 信息, 简而言之它可以 让编辑器和不同的框架准确的识别自定义标签

对于自定义标签的类型定义, 通过在代码中添加 jsdoc 注释, 并通过 custom-elements-manifest 生成 vscode.html-custom-data.json(用于 vscode) / web-types.json(用于 JetBrains IDE) 文件来实现
对于每个框架:
- vue: 通过 custom-element-vuejs-integration 生成组件的类型定义
- react: 通过 custom-element-react-wrappers 生成组件包装器
- angular: 无需生成文件

具体配置可参考: custom-elements-manifest.config.mjs

示例项目

配置好不同框架的适配之后, 我们直接创建 demo 项目:

发布

package.json:

{
  "scripts": {
+    "npm:login": "pnpm login --registry=https://registry.npmjs.org",
+    "npm:publish": "pnpm run build:lib && pnpm publish --registry=https://registry.npmjs.org",
  }
}

这里为什么要指定 registry 呢? 因为在国内的网络环境下, 一般会设置淘宝的 npm 镜像, 或内部私有镜像, 但在发布时是需要连接到官方源的

# 只需执行一次, 之后可以直接执行 pnpm run npm:publish
pnpm run npm:login

# 发布新版本包
pnpm run npm:publish

参考

源码

配置 markdown-it 解析

Sun, 09 Mar 2025 00:00:00 GMT

最近在做一个 AI 对话组件, 当收到消息时需要对 markdown 内容进行实时渲染, 所以需要配置 markdown-it 解析, 我们将参考 vitepress 的 markdown-it 配置

前言

由于对 markdown 渲染比较陌生, 所以直接使用了 marked 进行了渲染, 但是发现 marked 的生态及互联网上可参考的配置并不多, 倒是 markdown-it 有比较丰富的生态及配置, vitepress 就是使用 markdown-it 进行渲染的, 我们将参考 vitepress 的 markdown-it 配置

封装 API

由于我们是在自己的项目里使用, 对我来说, 我是在组件库中使用的, 所以我们将 markdown 渲染功能封装成一个 API, 然后在组件中使用, 代码如下:

import MarkdownIt from 'markdown-it-async'

const md = MarkdownIt()

// ...

/**
 * 将 markdown 字符串通过 markdown-it 渲染为 html 字符串
 * @param content markdown 字符串
 * @returns html 字符串
 */
export async function renderMarkdown(content: string) {
	const htmlContent = await md.render(content)
	return htmlContent
}

我们对外提供一个 renderMarkdown 方法, 接收 content 参数, 返回 html 内容

:::tip 这里我们使用了异步方法, 在实际使用中, 当我们需要渲染大量的 markdown 时, 可以使用异步方法, 可以避免阻塞主线程 :::

安装 markdown-it

pnpm i markdown-it-async
pnpm i -D @types/markdown-it

参考 vitepress 源码

首先我们找到 vitepress 仓库, 然后直接查看 packages.json, 发现 vitepress 使用了 markdown-it 进行了渲染
搜索 markdown-it, 在搜索结果我们可以看到所有包含 markdown-it 的源码文件, 但这里面包含了大量 md 文件, 实际上我们只需要看 ts 文件, 所以我们将搜索框内容改为 repo:vuejs/vitepress path:*.ts markdown-it, 这样就可以只搜索 ts 文件了
在搜索结果中, 可以看到 vitepress 将关于 markdown 渲染的功能都放到了 src/node/markdown 文件中, 入口文件就是 src/mode/markdown/markdown.ts

代码中包含一些 @mdit-vue/* 包, 这些是将 markdown 转换为 vue 代码的包, 由于 vitepress 的渲染产物是 vue 代码, 所以我们并不能直接使用, 但我们可以挑选用得到的相关的插件或依赖, 并加入到我们的项目中:

pnpm i markdown-it-async markdown-it-highlightjs markdown-it-link-attributes markdown-it-mathjax3
pnpm i -D @types/markdown-it-link-attributes

import { MarkdownItAsync } from 'markdown-it-async'
import highlight from 'markdown-it-highlightjs'
import CodeBlockWrapper from './CodeBlockWrapper'
import linkAttr from 'markdown-it-link-attributes'
import mathjax3 from 'markdown-it-mathjax3'

/** markdown-it 实例 */
let _md: MarkdownItAsync

/** 获取并初始化 markdown-it 实例 */
export async function getMarkdownItInstance(): Promise<MarkdownItAsync> {
  if (_md) return _md
  _md = new MarkdownItAsync()
  // 代码高亮
  _md.use(highlight)
  // 代码块使用自定义组件包裹
  _md.use(CodeBlockWrapper)
  // 链接在新窗口打开
  _md.use(linkAttr, { attrs: { target: '_blank', rel: 'noopener'} })
  // 渲染数学公式
  _md.use(mathjax3, {
    tex: {
      tags: 'ams',
      inlineMath: [
        // start/end delimiter pairs for in-line math
        ["$", "$"],
        ["\\(", "\\)"]
      ],
      displayMath: [
        // start/end delimiter pairs for display math
        ["$$", "$$"],
        ["\\[", "\\]"]
      ],
    }
  })
  return _md
}

/**
 * 将 markdown 字符串通过 markdown-it 渲染为 html 字符串
 * @param content markdown 字符串
 * @returns html 字符串
 */
export async function renderMarkdown(content: string) {
  const processedContent = getProcessedContent(content)
  const md = await getMarkdownItInstance()
	const htmlContent = await md.renderAsync(processedContent)
	return htmlContent
}

/**
 * 将 markdown 字符串进行预处理, 将 `\\[` 和 `\\]` 替换为 `$$`
 * @param content markdown 字符串
 */
export function getProcessedContent(content: string) {
  return content.replace(/\\\[|\\\]/g, '$$')
}

实际上 markdown-it 还有很多插件, 可以通过在 npmjs.com 搜索 markdown-it 查看

让我们看一下所有的依赖:

markdown-it-highlightjs: 用于语法高亮, 直接将样式内联, 省去了引入 css 的步骤, 但是主题样式还是需要引入的, 例如 import 'highlight.js/styles/github-dark.min.css'
markdown-it-link-attributes: 用于添加链接的属性, 例如 target="_blank", 这个对于对话组件是必须的, 因为我们希望用户点击链接后, 会在新窗口中打开
markdown-it-mathjax3: 用于渲染数学公式, 注意, 这里需要对一些特殊的语法进行替换, 例如 \\[ ... \\], 在代码中的 getProcessedContent 中进行了替换处理

代码块自定义元素

在以上代码中我们还写了一个自定义插件 CodeBlockWrapper, 用于将代码块包裹成一个自定义元素, 这样我们就可以对每个代码块进行处理, 比如: 添加复制按钮 / 美化样式

import type { MarkdownItAsync } from "markdown-it-async";
import hljs from "highlight.js";

/**
 * 自定义插件: 添加复制按钮
 * @param md markdown-it 实例
 */
export default function CodeBlockWrapper(md: MarkdownItAsync) {
  const defaultRenderer = md.renderer.rules.fence || ((tokens, idx, options, env, self) => self.renderToken(tokens, idx, options));

  md.renderer.rules.fence = (tokens, idx, options, env, self) => {
    const token = tokens[idx];
    const code = token.content.trim();
    const lang = token.info.trim();

    let highlightedCode = '';
    if (lang && hljs.getLanguage(lang)) {
      highlightedCode = hljs.highlight(code, { language: lang }).value;
    } else {
      highlightedCode = md.utils.escapeHtml(code);
    }

    // const copyButtonHtml = '<button class="copy-button" title="Copy to clipboard">Copy</button>';
    const preHtml = `<pre class="hljs"><code>${highlightedCode}</code></pre>`;
    // const html = `<div class="code-block">${copyButtonHtml}${preHtml}</div>`;
    const html = `<hyosan-chat-code-block-wrapper language="${lang}">${preHtml}</hyosan-chat-code-block-wrapper>`

    return html;
  };
}

这里我们将代码包裹在 <hyosan-chat-code-block-wrapper> 中, 然后传入 language 参数

接着创建自定义组件(这里使用了 Lit 来编写自定义组件), 创建 src/components/hyosan-chat-code-block-wrapper:

import ShoelaceElement from '@/internal/shoelace-element'
import { LocalizeController } from '@/utils/localize'
import { css, html } from 'lit'
import { customElement, property, state } from 'lit/decorators.js'

/** 发送 组件 */
@customElement('hyosan-chat-code-block-wrapper')
export class HyosanChatCodeBlockWrapper extends ShoelaceElement {
	static styles? = css`
		:host {
			display: block;
			margin: 1rem 0;
		}
		.code-block-container {
			display: block;
			border-radius: var(--hy-container-radius);
			border: 1px solid rgba(60, 60, 60, 0.1);
			background-color: var(--sl-color-neutral-500);
			header {
				margin: 0.3rem 0.5rem;
				color: #EEE;
				display: flex;
				justify-content: space-between;
				button {
					display: block;
					cursor: pointer;
				}
			}
		}
		::slotted(pre) {
			padding: var(--hy-container-padding);
			margin: 0;
			border-bottom-left-radius: var(--hy-container-radius);
			border-bottom-right-radius: var(--hy-container-radius);
		}
  `

	@property({ type: String })
	language = 'javascript'

	@state()
	private _copyButtonContent = ''

	/** 本地化控制器 */
	private _localize = new LocalizeController(this)

	private _handleCopy() {
		const pre = this.querySelector('pre')
		if (pre) {
			const text = pre.textContent
			if (text) {
				navigator.clipboard.writeText(text)
				this._copyButtonContent = this._localize.term('copySuccessfully')
				setTimeout(() => {
					this._copyButtonContent = this._localize.term('copy')
					this.requestUpdate()
				}, 2000)
			}
		}
	}

	render() {
		const copyButtonContent = this._copyButtonContent || this._localize.term('copy')
		return html`
      <div class="code-block-container">
				<header>
					<div class="lang">${this.language}</div>
					<div class="button-group">
						<button @click=${this._handleCopy}>${copyButtonContent}</button>
					</div>
				</header>
				<main>
					<slot></slot>
				</main>
      </div>
    `
	}
}

declare global {
	interface HTMLElementTagNameMap {
    'hyosan-chat-code-block-wrapper': HyosanChatCodeBlockWrapper
	}
}

最终效果:

参考

使用 Lit 创建一个 AI 对话组件库 05 conversations 篇

Mon, 03 Mar 2025 00:00:00 GMT

前面我们从 Web Components 开始看起, 接着学习了 Lit, 然后开始搭建项目, 引入各种工程化依赖, 增加打包配置并进行了可行性测试, 始终没有涉及实际的功能, 是因为我希望能更全面的学习 Web Components, 组件库只是我们学习的最终成果, 成果固然重要, 但学习不同的技术 / 翻阅文档 / 阅读源码的经历更加宝贵

前言

阅读本章内容需要你熟悉 Lit / Web Components / Shoelace

如果你对只对组件库感兴趣, 可以直接查看本项目源码: hyosan-chat
如果你对组件库搭建或项目工程化感兴趣, 可以查看前面几章的内容:

创建一个对话列表

ant-design-x 是一个优秀的 AI 对话组件库, 我们的组件库将参考 ant-design-x 的 UI 设计 / API 设计, 并实现部分基础的功能

以上是 ant-design-x 的 UI, 我们要做的组件最终效果也是这样的, ant-design-x 做的足够好, 但它对组件进行了非常细致的拆分, 导致在使用时虽然能做到足够的灵活可扩展性, 但也增加了 API 复杂度, 我们将在实现部分功能的基础上, 简化 API, 本章先从 conversations 组件开始, 参考 Conversations 管理对话

ant-design-x API

通过阅读源码, 找到了 Conversations 组件的 API: interface.ts, 我们将其复制到 src/types/conversations.ts:

import type { AnyObject } from './helpers'

type GroupType = string

/**
 * @desc 会话数据
 * @descEN Conversation data
 */
export interface Conversation extends AnyObject {
	/**
	 * @desc 唯一标识
	 * @descEN Unique identifier
	 */
	key: string

	/**
	 * @desc 会话名称
	 * @descEN Conversation name
	 */
	label: string

	/**
	 * @desc 会话时间戳
	 * @descEN Conversation timestamp
	 */
	timestamp?: number

	/**
	 * @desc 会话分组类型，与 {@link ConversationsProps.groupable} 联动
	 * @descEN Conversation type
	 */
	group?: GroupType

	/**
	 * @desc 会话图标
	 * @descEN conversation icon
	 */
	icon?: string

	/**
	 * @desc 是否禁用
	 * @descEN Whether to disable
	 */
	disabled?: boolean
}

export type GroupSorter = Parameters<GroupType[]['sort']>[0]

export interface Groupable {
	/**
	 * @desc 分组排序函数
	 * @descEN Group sorter
	 */
	sort?: GroupSorter
	/**
	 * @desc 自定义分组标签渲染
	 * @descEN Semantic custom rendering
	 */
	title?: string
}

controllers

在之前阅读 shoelace 源码的时候, 发现在 src/internal 中有许多 controllers, 而且只依赖 Lit, Controller 可以直接调用组件的生命周期 hooks, 也就可以直接更新组件, 详见 Reactive Controllers

我们将目前用到的 slot.ts 复制到项目中(src/internal/slot.ts), 并且在 hyosan-chat.ts 中引入:

+ import { HasSlotController } from '@/internal/slot'
export class HyosanChat extends ShoelaceElement {
+	private readonly hasSlotController = new HasSlotController(
+		this,
+		'conversations',
+		'conversations-header',
+		'conversations-footer',
+	)
}

HasSlotController 实现了对于 slot 的检测, 我们可以在 render 中判断 slot 是否存在, 并以此实现没有传 slot 时使用默认的元素渲染:

	render() {
+		const hasConversationsSlot = this.hasSlotController.test('conversations')
+		const hasConversationsHeaderSlot = this.hasSlotController.test(
+			'conversations-header',
+		)
+		/** 会话列表 header */
+		const conversationsHeader = hasConversationsHeaderSlot
+			? html`<slot name="conversations-header"></slot>`
+			: html`<hyosan-chat-conversations-header slot="conversations-header"></hyosan-chat-conversations-header>`
+		/** 会话列表 */
+		const conversations = hasConversationsSlot
+			? html`<slot name="conversations">${conversationsHeader}<slot name="conversations-footer"></slot></slot>`
+			: html`<hyosan-chat-conversations .items=${this.items}>${conversationsHeader}<slot name="conversations-footer"></slot></hyosan-chat-conversations>`
    // ...
	}

这里的渲染逻辑是:

如果传入了名为 conversations 的 slot, 则使用 slot 中的内容, 否则使用默认的 hyosan-chat-conversations 组件渲染
如果传入了名为 conversations-header 的 slot, 则使用 slot 中的内容, 否则使用默认的 hyosan-chat-conversations-header 组件渲染

分割面板

组件整体的布局是左侧会话列表, 右侧消息列表, 下面我们使用 sl-split-panel 来实现左右布局:

src/components/hyosan-chat.ts:

    return html`
- 	  <h2>${this.message}</h2>
-		  <sl-button variant="primary">Hello Shoelace</sl-button>
-		  <p>${this._locailze.term('test')}</p>
+			<sl-split-panel snap="${this.panelSnap}" position="${this.panelPosition}">
+				<div
+					slot="start"
+					style="height: 100%; overflow-y: auto; background: var(--sl-color-neutral-50);"
+				>
+					<!-- 管理会话 -->
+					${conversations}
+				</div>
+				<div
+					slot="end"
+					style="height: 100%;"
+				>
+					<!-- 对话气泡 -->
+					<hyosan-chat-bubble></hyosan-chat-bubble>
+				</div>
+			</sl-split-panel>
    `

我们将 snap / position 作为参数作为组件的属性, 接受这两个属性并传入 sl-split-panel
conversations 组件是左侧的会话列表, 我们将在本章实现这个组件

+	/**
+	 * 分割面板的可捕捉位置
+	 * @example '25% 50%'
+	 * @see https://shoelace.style/components/split-panel#snapping
+	 */
+	@property({ reflect: true })
+	panelSnap = '25%'
+
+	/**
+	 * 分隔线与主面板边缘的当前位置(百分比, 0-100), 默认为容器初始大小的 `50%`
+	 * @example 25
+	 * @see https://shoelace.style/components/split-panel#initial-position
+	 */
+	@property({ reflect: true, type: Number })
+	panelPosition = 25

vscode snippets

在创建 Lit Components 的时候, 我们总是将每个组件都有的代码复制到新组件中, 如果能直接生成模板代码让我们使用就好了; 实际上 vscode 已经提供了 snippets 功能, 我们可以创建一个 snippets 模板, 然后在 vscode 中使用 snippets 快速创建组件:

.vscode/hy.code-snippets

{
	// Place your hyosan-chat 工作区 snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and 
	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope 
	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is 
	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are: 
	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. 
	// Placeholders with the same ids are connected.
	// Example:
	// "Print to console": {
	// 	"scope": "javascript,typescript",
	// 	"prefix": "log",
	// 	"body": [
	// 		"console.log('$1');",
	// 		"$2"
	// 	],
	// 	"description": "Log output to console"
	// }
	"Hyosan Component": {
		"prefix": "hy-component",
		"body": [
      "import ShoelaceElement from '@/internal/shoelace-element'",
      "// import { LocalizeController } from '@shoelace-style/localize'",
      "import { css, html } from 'lit'",
      "import { customElement, property } from 'lit/decorators.js'",
      "",
      "/** $0 组件 */",
      "@customElement('${TM_FILENAME_BASE}')",
      "export class ${TM_FILENAME_BASE/(^|\\-)(\\w)/${2:/upcase}/g} extends ShoelaceElement {",
      "  static styles? = css``",
      "",
      "  // /** 本地化控制器 */",
      "  // private _localize = new LocalizeController(this)",
      "",
      "  @property({ reflect: true })",
      "  message = ''",
      "  render() {",
      "    return html`",
      "      <div>${this.message}</div>",
      "    `",
      "  }",
      "}",
      "",
      "declare global {",
      "  interface HTMLElementTagNameMap {",
      "    '${TM_FILENAME_BASE}': ${TM_FILENAME_BASE/(^|\\-)(\\w)/${2:/upcase}/g}",
      "  }",
      "}",
      ""
		],
		"description": "Generate a Hyosan component based on the filename"
	},
	"Hyosan Component Property": {
		"prefix": "hy-component-property",
		"body": [
			"/** $2 */",
			"@property({ reflect: true })",
			"$1 = ''"
		]
	}
}

创建组件

src/components/hyosan-chat-conversations-header.ts:

import ShoelaceElement from '@/internal/shoelace-element'
// import { LocalizeController } from '@shoelace-style/localize'
import { css, html } from 'lit'
import { customElement, property } from 'lit/decorators.js'

/** 会话列表头部 组件 */
@customElement('hyosan-chat-conversations-header')
export class HyosanChatConversationsHeader extends ShoelaceElement {
	static styles? = css`
		h2 {
			padding: 0 1rem;
			display: flex;
			align-items: center;
			justify-content: center;
			svg {
				margin-right: 0.5rem;
			}
		}
	`

	// /** 本地化控制器 */
	// private _localize = new LocalizeController(this)

	@property()
	title = 'Hyosan Chat'
	render() {
		return html`
      <header>
        <h2>
					<svg t="1740983223876" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="3643" width="2rem" height="2rem"><path d="M853.333333 85.333333H170.666667C123.52 85.333333 85.76 123.52 85.76 170.666667L85.333333 938.666667l170.666667-170.666667h597.333333c47.146667 0 85.333333-38.186667 85.333334-85.333333V170.666667c0-47.146667-38.186667-85.333333-85.333334-85.333334zM256 384h512v85.333333H256v-85.333333z m341.333333 213.333333H256v-85.333333h341.333333v85.333333z m170.666667-256H256v-85.333333h512v85.333333z" p-id="3644"></path></svg>
					<span>
						${this.title}
					</span>
				</h2>
      </header>
    `
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'hyosan-chat-conversations-header': HyosanChatConversationsHeader
	}
}

src/components/hyosan-chat-conversations-item.ts:

import ShoelaceElement from '@/internal/shoelace-element'
import type { Conversation } from '@/types/conversations'
// import { LocalizeController } from '@shoelace-style/localize'
import { css, html } from 'lit'
import { customElement, property } from 'lit/decorators.js'

/** 会话列表项 组件 */
@customElement('hyosan-chat-conversations-item')
export class HyosanChatConversationsItem extends ShoelaceElement {
	static styles? = css`
    .item-row { padding: 0.5rem; margin: 0.5rem; border-radius: 0.5rem; cursor: pointer; }
		:host([actived]) .item-row, .item-row:hover { background-color: var(--sl-color-neutral-200); }
  `

	// /** 本地化控制器 */
	// private _localize = new LocalizeController(this)

	/** 是否选中 */
	@property({ type: Boolean })
	actived = false

	/** 会话列表数据源 */
	@property({ attribute: false, type: Object })
	item!: Conversation

	render() {
		return html`
      <div class="item-row" @click=${() => this.emit('click-conversation', { detail: { item: this.item } })}>
        <span>${this.item.label}</span>
      </div>
    `
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'hyosan-chat-conversations-item': HyosanChatConversationsItem
	}
	interface GlobalEventHandlersEventMap {
		'click-conversation': CustomEvent<{ item: Conversation }>
	}
}

src/components/hyosan-chat-conversations.ts:

import ShoelaceElement from '@/internal/shoelace-element'
import { HasSlotController } from '@/internal/slot'
import type { Conversation } from '@/types/conversations'
// import { LocalizeController } from '@shoelace-style/localize'
import { css, html } from 'lit'
import { customElement, property } from 'lit/decorators.js'

/** 管理会话 组件 */
@customElement('hyosan-chat-conversations')
export class HyosanChatConversations extends ShoelaceElement {
	static styles? = css`
		:host { height: 100%; display: block; }
		.aside {
			display: flex;
			flex-direction: column;
			height: 100%;
			main {
				flex: 1;
				overflow-y: auto;
			}
		}
	`

	// /** 本地化控制器 */
	// private _localize = new LocalizeController(this)
	private readonly hasSlotController = new HasSlotController(
		this,
		'conversations-header',
		'conversations-footer',
	)

	/** 当前选中的值 */
	@property({ reflect: true })
	activeKey = ''

	/** 会话列表数据源 */
	@property({ attribute: false, type: Array })
	items: Conversation[] = []

	private _handleClickConversation(
		event: GlobalEventHandlersEventMap['click-conversation'],
	) {
		this.activeKey = event.detail.item.key
		this.requestUpdate()
	}

	render() {
		return html`
			<div class="aside">
				<header>
					<slot name="conversations-header"></slot>
				</header>
				<main>
					${this.items.map(
						(item) => html`
						<hyosan-chat-conversations-item
							.item=${item} ?actived=${this.activeKey === item.key}
							@click-conversation=${this._handleClickConversation}
						>
						</hyosan-chat-conversations-item>
						`,
					)}
				</main>
				<footer>
					<slot name="conversations-footer"></slot>
				</footer>
			</div>
		`
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'hyosan-chat-conversations': HyosanChatConversations
	}
}

src/components/index.ts:

export { HyosanChat } from './hyosan-chat'
export { HyosanChatConversations } from './hyosan-chat-conversations'
export { HyosanChatConversationsItem } from './hyosan-chat-conversations-item'
export { HyosanChatConversationsHeader } from './hyosan-chat-conversations-header'

事件

由于 Lit 的事件就是原生 HTML 事件, 没有任何类型约束, 所以在 hyosan-chat-conversations-item 组件中, 添加了 click-conversation 事件, 用于通知父组件选中的会话; 其中 this.emit 是在 ShoelaceElement 中定义的, 我们将 shoelace 中的相关代码复制到 src/internal/shoelace-element.ts 中:

import { LitElement } from 'lit'
import { property } from 'lit/decorators.js'

/**
 * 组件基础类, 参考自 shoelace
 * @see https://github.com/shoelace-style/shoelace/blob/6f09a7556731107e027b8afade0ad1e28d77c710/src/internal/shoelace-element.ts#L65
 */
export default class ShoelaceElement extends LitElement {
	// Make localization attributes reactive
	@property() dir = 'ltr'
	@property() lang = ''

	/** Emits a custom event with more convenient defaults. */
	emit<T extends string & keyof EventTypesWithoutRequiredDetail>(
		name: EventTypeDoesNotRequireDetail<T>,
		options?: SlEventInit<T> | undefined,
	): GetCustomEventType<T>
	emit<T extends string & keyof EventTypesWithRequiredDetail>(
		name: EventTypeRequiresDetail<T>,
		options: SlEventInit<T>,
	): GetCustomEventType<T>
	emit<T extends string & keyof ValidEventTypeMap>(
		name: T,
		options?: SlEventInit<T> | undefined,
	): GetCustomEventType<T> {
		const event = new CustomEvent(name, {
			bubbles: true,
			cancelable: false,
			composed: true,
			detail: {},
			...options,
		})

		this.dispatchEvent(event)

		return event as GetCustomEventType<T>
	}
}

/** Match event type name strings that are registered on GlobalEventHandlersEventMap... */
type EventTypeRequiresDetail<T> = T extends keyof GlobalEventHandlersEventMap
	? // ...where the event detail is an object...
		GlobalEventHandlersEventMap[T] extends CustomEvent<
			Record<PropertyKey, unknown>
		>
		? // ...that is non-empty...
			GlobalEventHandlersEventMap[T] extends CustomEvent<
				Record<PropertyKey, never>
			>
			? never
			: // ...and has at least one non-optional property
				Partial<
						GlobalEventHandlersEventMap[T]['detail']
					> extends GlobalEventHandlersEventMap[T]['detail']
				? never
				: T
		: never
	: never

/** The inverse of the above (match any type that doesn't match EventTypeRequiresDetail) */
type EventTypeDoesNotRequireDetail<T> =
	T extends keyof GlobalEventHandlersEventMap
		? GlobalEventHandlersEventMap[T] extends CustomEvent<
				Record<PropertyKey, unknown>
			>
			? GlobalEventHandlersEventMap[T] extends CustomEvent<
					Record<PropertyKey, never>
				>
				? T
				: Partial<
							GlobalEventHandlersEventMap[T]['detail']
						> extends GlobalEventHandlersEventMap[T]['detail']
					? T
					: never
			: T
		: T

/** `keyof EventTypesWithRequiredDetail` lists all registered event types that require detail */
type EventTypesWithRequiredDetail = {
	[EventType in keyof GlobalEventHandlersEventMap as EventTypeRequiresDetail<EventType>]: true
}

/** `keyof EventTypesWithoutRequiredDetail` lists all registered event types that do NOT require detail */
type EventTypesWithoutRequiredDetail = {
	[EventType in keyof GlobalEventHandlersEventMap as EventTypeDoesNotRequireDetail<EventType>]: true
}

/** Helper to make a specific property of an object non-optional  */
type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] }

/**
 * Given an event name string, get a valid type for the options to initialize the event that is more restrictive than
 * just CustomEventInit when appropriate (validate the type of the event detail, and require it to be provided if the
 * event requires it)
 */
type SlEventInit<T> = T extends keyof GlobalEventHandlersEventMap
	? GlobalEventHandlersEventMap[T] extends CustomEvent<
			Record<PropertyKey, unknown>
		>
		? GlobalEventHandlersEventMap[T] extends CustomEvent<
				Record<PropertyKey, never>
			>
			? CustomEventInit<GlobalEventHandlersEventMap[T]['detail']>
			: Partial<
						GlobalEventHandlersEventMap[T]['detail']
					> extends GlobalEventHandlersEventMap[T]['detail']
				? CustomEventInit<GlobalEventHandlersEventMap[T]['detail']>
				: WithRequired<
						CustomEventInit<GlobalEventHandlersEventMap[T]['detail']>,
						'detail'
					>
		: CustomEventInit
	: CustomEventInit

/** Given an event name string, get the type of the event */
type GetCustomEventType<T> = T extends keyof GlobalEventHandlersEventMap
	? GlobalEventHandlersEventMap[T] extends CustomEvent<unknown>
		? GlobalEventHandlersEventMap[T]
		: CustomEvent<unknown>
	: CustomEvent<unknown>

/** `keyof ValidEventTypeMap` is equivalent to `keyof GlobalEventHandlersEventMap` but gives a nicer error message */
type ValidEventTypeMap =
	| EventTypesWithRequiredDetail
	| EventTypesWithoutRequiredDetail

这里的 emit 和类型体操完美实现了事件的类型声明和类型约束, 我们只需通过扩展 GlobalEventHandlersEventMap 类型即可实现类型声明:

declare global {
	interface GlobalEventHandlersEventMap {
		'click-conversation': CustomEvent<{ item: Conversation }>
	}
}

完整改动

文中可能有遗漏的代码, 可直接参考:

#47b3a

最后让我们看一下效果:

参考

使用 Lit 创建一个 AI 对话组件库 04 国际化篇

Sun, 02 Mar 2025 00:00:00 GMT

当我们将组件库公开发布后, 可以被任何国家任何人使用, 我们除了要有完善可靠的功能, 还要考虑诸如国际化 / ts 类型定义 / 主题等可以提升用户体验的东西

前言

在使用 Lit 创建一个 AI 对话组件库 03 可行性验证篇中我们发现了组件库存在以下问题:

缺少 国际化 功能
在 vue 中缺少 类型定义
缺少主题功能

对于一个组件库来说, 我们的组件可能会被不同的项目使用, 如果我们不考虑多语言, 那就极大地限制了不同语言环境下的用户的使用, 所以我们需要考虑国际化; 对于类型定义和主题切换来说也是同样的道理

国际化

shoelace 本身提供了国际化支持, shoelace 是一个基于 Lit 的优秀的 UI 组件库, 我们阅读一下 shoelace 的源码, 借鉴一下 shoelace 的国际化实现:

我们从语言文件开始, 例如 src/translations/zh-cn.ts, 文件中使用了 src/utilities/localize.ts 中导出的 registerTranslation, registerTranslation 实际上来自于 @shoelace-style/localize 包, 原来 shoelace 将本地化功能拆分为了一个单独的包, 而且可以与 lit 完美结合, 零依赖!

@shoelace-style/localize 的示例:

import { LocalizeController, registerTranslation } from '@shoelace-style/localize';

// Note: translations can also be lazy loaded (see "Registering Translations" below)
import en from '../translations/en';
import es from '../translations/es';

registerTranslation(en, es);

@customElement('my-element')
export class MyElement extends LitElement {
  private localize = new LocalizeController(this);

  @property() lang: string;

  render() {
    return html`
      <h1>${this.localize.term('hello_world')}</h1>
    `;
  }
}

这里我们引入了 @shoelace-style/localize 并注册了多语言文案 en / es, 接着我们在组件中声明了 localize = new LocalizeController(this) 和 @property() lang: string, 最后在 render 中使用 this.localize.term('hello_world') 来获取文案, 他会在 lang 属性变化的时候自动更新多语言文案内容

这是一个优秀的设计, 我们仅需要修改 html[lang] 或组件的 lang 属性, 组件就能根据新的语言进行渲染; 我们来猜一下 @shoelace-style/localize 是如何实现的, 首先 new LocalizeController(this) 时将当前组件类的示例传入了 LocalizeController, 并在 LocalizeController 内部监听 lang 属性的变化, 并且调用组件示例的用于渲染 DOM 的方法...

接下来让我们阅读 @shoelace-style/localize 源码, 查看具体是如何实现的:

localize/src/index.ts:

export class LocalizeController<UserTranslation extends Translation = DefaultTranslation>
  implements ReactiveController
{
  constructor(host: ReactiveControllerHost & HTMLElement) {
    this.host = host;
    this.host.addController(this);
  }
  // ...
}

首先在 constructor 中调用了组件的 addController, 这是一个用于向 LitElement 添加响应式控制器的方法, 它允许外部代码与 Lit 的响应式生命周期集成, 简而言之 LocalizeController 可以直接调用组件的生命周期 hooks, 也就可以直接更新组件, 详见 Reactive Controllers

const connectedElements = new Set<HTMLElement>();
if (isClient) {
  const documentElementObserver = new MutationObserver(update);
  documentDirection = document.documentElement.dir || 'ltr';
  documentLanguage = document.documentElement.lang || navigator.language;

  // Watch for changes on <html lang>
  documentElementObserver.observe(document.documentElement, {
    attributes: true,
    attributeFilter: ['dir', 'lang']
  });
}
/** Updates all localized elements that are currently connected */
export function update() {
  if (isClient) {
    documentDirection = document.documentElement.dir || 'ltr';
    documentLanguage = document.documentElement.lang || navigator.language;
  }

  [...connectedElements.keys()].map((el: LitElement) => {
    if (typeof el.requestUpdate === 'function') {
      el.requestUpdate();
    }
  });
}
// ...

export class LocalizeController<UserTranslation extends Translation = DefaultTranslation>
  implements ReactiveController
{
  hostConnected() {
    connectedElements.add(this.host);
  }

  hostDisconnected() {
    connectedElements.delete(this.host);
  }
  /**
   * Gets the host element's language as determined by the `lang` attribute. The return value is transformed to
   * lowercase.
   */
  lang() {
    return `${this.host.lang || documentLanguage}`.toLowerCase();
  }
  /** Outputs a translated term. */
  term<K extends keyof UserTranslation>(key: K, ...args: FunctionParams<UserTranslation[K]>): string {
    const { primary, secondary } = this.getTranslationData(this.lang());
    // ...
  }
  // ...
}

在这里先把组件存到了 connectedElements 中, 然后在外部通过 MutationObserver 监听了 HTML 标签的 lang 属性变化, 并同步调用 update 调用组件的 requestUpdate() 来更新组件; 除此之外, 在组件内部的 lang 属性变化时, 也会调用 render, 并调用 term 来根据最新的 lang 更新组件

至此 @shoelace-style/localize 的示例的具体实现我们就分析完了, 接下来我们看一下 shoelace 是如何使用 @shoelace-style/localize 的:

src/internal/shoelace-element.ts:


export default class ShoelaceElement extends LitElement {
  // Make localization attributes reactive
  @property() dir: string;
  @property() lang: string;
  // ...
}

这里 shoelace 并没有在每个组件上都声明 lang / dir, 而是创建了一个基类 ShoelaceElement, 并在所有组件上继承了它, 这样 shoelace 就可以统一处理 lang / dir 了, 不得不说这是一个很优秀的设计

:::tip 实际上 ShoelaceElement 类中还有很多值得学习的地方:

类型安全的 emit 方法, 通过 函数重载 实现了 emit 方法的三种不同参数类型, 并实现了很好的类型约束
组件的动态注册, define 方法实现了 动态注册 和 重复注册检查
动态依赖加载, 在 constructor 中动态注册组件声明的 dependencies, 详见 Cherry Pick - Shoelace :::

国际化实现与组件基类

回到我们的组件库项目中, 我们来基于 @shoelace-style/localize 一步步实现本地化功能, 并且借鉴 ShoelaceElement 的设计:

code src/internal/shoelace-element.ts

import { LitElement } from "lit";
import { property } from "lit/decorators.js";

export default class ShoelaceElement extends LitElement {
  // Make localization attributes reactive
  @property() dir = 'ltr';
  @property() lang = '';
}

tsconfig.json:

{
+		"baseUrl": "./",
+		"paths": {
+			"@/*": ["src/*"]
+		},
}

src/translations/zh-cn.ts:

import { registerTranslation, type Translation } from '@/translations/translation';

const translation: Translation = {
  $code: 'zh-cn',
  $name: '简体中文',
  $dir: 'ltr',

  test: '测试',
};

registerTranslation(translation);

export default translation;

src/translations/en.ts:

import { registerTranslation, type Translation } from '@/translations/translation';

const translation: Translation = {
  $code: 'en',
  $name: 'English',
  $dir: 'ltr',

  test: 'test',
};

registerTranslation(translation);

export default translation;

src/translations/translation.ts:

import type { Translation as DefaultTranslation } from '@shoelace-style/localize';

// Export functions from the localize lib so we have one central place to import them from
export { registerTranslation } from '@shoelace-style/localize';

export interface Translation extends DefaultTranslation {
  $code: string; // e.g. en, en-GB
  $name: string; // e.g. English, Español
  $dir: 'ltr' | 'rtl';

  test: string;
}

src/utils/localize.ts:

import { LocalizeController as DefaultLocalizationController, registerTranslation } from '@shoelace-style/localize';
import type { Translation } from '@/translations/translation';
import en from '.@/translations/en'; // Register English as the default/fallback language
import zhCn from '@/translations/zh-cn'; // Register English as the default/fallback language

/**
 * Extend the controller and apply our own translation interface for better typings
 * @see https://github.com/shoelace-style/shoelace/blob/next/src/utilities/localize.ts
 */
export class LocalizeController extends DefaultLocalizationController<Translation> {
  // Technicallly '../translations/en.js' is supposed to work via side-effects. However, by some mystery sometimes the
  // translations don't get bundled as expected resulting in `no translation found` errors.
  // This is basically some extra assurance that our translations get registered prior to our localizer connecting in a component
  // and we don't rely on implicit import ordering.
  static {
    registerTranslation(en);
    registerTranslation(zhCn);
  }
}

src/components/hyosan-chat.ts:

+ import ShoelaceElement from '@/internal/shoelace-element'
+ import { LocalizeController } from '@/utils/localize'
- export class HyosanChat extends LitElement {
+ export class HyosanChat extends ShoelaceElement {
+   private _locailze = new LocalizeController(this)
	render() {
		return html`
			<h2>${this.message}</h2>
			<sl-button variant="primary">Hello Shoelace</sl-button>
+			<p>${this._locailze.term('test')}</p>
    `
	}
}

这里我们创建了一些本地化相关的类和函数, 并在组件中通过 LocalizeController 来实现本地化功能, 我们来测试一下

修改组件的 lang 属性:

修改 <html> 的 lang 属性:

参考

使用 Lit 创建一个 AI 对话组件库 03 可行性验证篇

Sat, 01 Mar 2025 00:00:00 GMT

本文将介绍组件库在打包发布后, 在实际的项目中使用是否可行，以及如何进行验证

为什么要验证可行性

当我们打算使用一项新技术或新的库时, 最先要做的就是验证可行性; 因为对于新的外部依赖, 我们无法确定是否符合预期, 以及是否会带来新的问题, 进行一次最小规模的验证, 可以 尽早的暴露问题

打包

我们的项目是使用 vite 进行搭建的, vite 提供了 library mode 以支持将项目中的部分文件进行单独打包, 并构建为库以供其他项目使用

TypeScript 配置

# 引入生成 .d.ts 文件的插件
pnpm i -D vite-plugin-dts

tsconfig.json:

{
	"compilerOptions": {
    // ...
+		"declaration": true,
+		"outDir": "dist",
  }
}

创建 src/lib.ts 作为组件库的入口文件:

export * from './components'

我们的项目是使用 ts 编写的, 为了让我们的组件库可以支持 ts 项目, 我们需要使用 vite-plugin-dts 将 .d.ts 文件生成到 dist 目录下

vite.config.ts:

+ import dts from 'vite-plugin-dts'

export default defineConfig({
  // ...
+ 	plugins: [
+ 		// 用于生成 `d.ts` 文件, refer https://github.com/qmhc/vite-plugin-dts/blob/HEAD/README.zh-CN.md
+ 		dts({ tsconfigPath: './tsconfig.lib.json' })
+ 	],
+ 	build: {
+ 		lib: {
+ 			name: 'hyosan-chat',
+ 			entry: ['src/lib.ts'],
+ 			fileName: 'hyosan-chat',
+ 		},
+ 	},
})

创建 tsconfig.lib.json:

{
  "extends": "./tsconfig.json", // 继承已有的 tsconfig.json
  "include": [ // 添加需要在打包时生产 .d.ts 文件的文件
    "./src/lib.ts",
    "./src/components/**/*.ts",
  ]
}

:::tip 为什么要额外创建一个 tsconfig.json?

在打包时, vite-plugin-dts 会将 tsconfig.json 中的 include 中的文件进行打包(这里指生成 dts), 但 tsconfig.json 中 include 包含了项目中的所有文件, 也包括了不应该出现在 dist 目录中的文件, 但我们不能修改 tsconfig.json, 因为它适用于整个项目的开发环境, 所以我们需要创建单独的 tsconfig.lib.json 用于生成 d.ts

也就是说, tsconfig.json 用于开发环境, tsconfig.lib.json 用于打包时生成 d.ts :::

我们将 src/lib.ts 中导出的组件作为整个组件库对外提供的组件, 并通过 vite-plugin-dts 生成了类型描述文件

package.json 配置

当我们的项目作为组件库供外部使用时, 需要在 package.json 中声明 组件库的基本信息和对外提供的文件:

{
+	 "description": "A library of web components for AI conversations based on lit and shoelace",
+	 "keywords": ["hyosan-chat", "Lit", "Shoelace", "AI", "chat", "Web Components", "web chat"],
+	 "author": {
+	  	"name": "Ryan"
+	 },
+	 "license": "MIT",
-	 "version": "0.0.0",
+	 "version": "0.0.1",
-  "private": true,
+ 	"files": [
+ 		"dist"
+ 	],
+ 	"main": "./dist/hyosan-chat.umd.cjs",
+ 	"module": "./dist/hyosan-chat.js",
+ 	"exports": {
+ 		".": {
+ 			"import": "./dist/hyosan-chat.js",
+ 			"require": "./dist/hyosan-chat.umd.cjs"
+ 		}
+ 	},
	"scripts": {
+		"build:pack": "pnpm run build && pnpm pack",
  },
}

build & pack

修改完打包所需的配置后, 我们就可以使用 pnpm run build 进行打包了:

# 打包
pnpm run build

# 打包并生成 .tgz 文件
pnpm run build:pack

lsd --tree dist/
 dist
├──  components
│   ├──  hyosan-chat.d.ts
│   └──  index.d.ts
├──  hyosan-chat.js
├──  hyosan-chat.umd.cjs
├──  lib.d.ts
└──  vite.svg

我们观察一下打包后的产物:

文件	说明
`components/hyosan-chat.d.ts`	对话组件
`components/index.d.ts`	组件库中包含的组件的入口文件
`hyosan-chat.js`	`es` 打包格式产物
`hyosan-chat.umd.cjs`	`umd` 打包格式产物
`lib.d.ts`	组件库的入口文件
`vite.svg`	`vite logo`

其中 vite.svg 不应该出现在 dist 目录中, 因此我们将其删除

rm public/vite.svg

lib.d.ts 是组件库的入口文件的类型描述文件, 我们需要在 package.json 中声明:

{
+  "types": "./dist/lib.d.ts"
	"exports": {
		".": {
+ 			"types": "./dist/lib.d.ts",
			"import": "./dist/hyosan-chat.js",
			"require": "./dist/hyosan-chat.umd.cjs"
		}
	},
}

dist / hyosan-chat-0.0.1.tgz 文件作为打包后的产物, 不应该提交到仓库中, 我们将其添加到 .gitignore 中:

+dist
+hyosan-chat-*.tgz

验证

打包完成后, 我们需要创建一个新的 vue 项目来引入组件库进行测试:

pnpm create vite
.../1954f95e4b3-1078                     |   +1 +
.../1954f95e4b3-1078                     | Progress: resolved 1, reused 0, downloaded 1, added 1, done
│
◇  Project name:
│  vite-project
│
◇  Select a framework:
│  Vue
│
◇  Select a variant:
│  TypeScript
│
◇  Scaffolding project in /Users/xxx/projects/vite-project...
│
└  Done. Now run:

  cd vite-project
  pnpm install
  pnpm run dev

cd vite-project
pnpm i && pnpm i ./hyosan-chat/hyosan-chat-0.0.1.tgz
code .

我们使用 vscode 打开项目, 检查有无报错 / 引入失败 / 类型缺失等问题:

在 vscode 中打开 HelloWorrld.vue 尝试引入组件库并添加 <hyosan-chat> 组件, 发现组件可以成功引入, 也有正确的类型定义

下面我们启动项目查看页面显示是否正常:

pnpm run dev

页面没有显示出组件, 这里的报错(Class constructor Y cannot be invoked without 'new')是因为 vue 把它当做了 vue 组件进行了渲染, 但其实它应该被当做 自定义元素, 通过查看在 vue 中使用自定义元素, 发现应该在 vite.config.ts 中添加 isCustomElement:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: tag => tag.includes('hyosan-')
        }
      }
    })
  ],
  server: {
    port: 35195,
  }
})

添加 isCustomElement 后, 组件渲染出来了, 但是样式没有, 这是因为我们在搭建项目引入 shoelace 时, 使用最简单的 <link> cdn URL 的方式引入了 shoelace 的样式, 在新创建的项目中并没有这个 <link>, 我们为了进行验证, 先引入 <link>, 在后续文章中我们会优化引入方式

index.html:

+    <link
+      rel="stylesheet"
+      media="(prefers-color-scheme:light)"
+      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/light.css"
+    />
+    <link
+      rel="stylesheet"
+      media="(prefers-color-scheme:dark)"
+      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/dark.css"
+      onload="document.documentElement.classList.add('sl-theme-dark');"
+    />

再次查看页面, 组件正常渲染, 接下来我们测试一下 v-model 是否可用:

+  <input v-model="message" />
-  <hyosan-chat></hyosan-chat>
+  <hyosan-chat :message="message"></hyosan-chat>

+ const message = ref('message')

在 input 中修改 message, 页面中的 hyosan-chat 组件也会同步修改

看起来一切正常! 🎉 但在我们现在依然有几个需要解决的问题:

组件的样式现在依然使用的是 <link> cdn 的方式实现, 但我们的用户使用环境可能是内网, 无法访问 cdn 的资源, 因此我们需要优化引入方式, 改为 在组件库中 export shoelace 的样式
vscode 中的 HelloWorld.vue 中编写 <hyosan-chat> 时, 没有关于 hyosan-chat 组件的类型提示(props / events), 也就是 vscode 无法识别 hyosan-chat 组件的类型; 得益于 vue 对自定义组件的支持, 我们可以 生成类型定义文件对 vue GlobalComponents 进行扩展, 这里我们可以使用一些第三方库(custom-element-vuejs-integration) 来实现, 详见非 Vue Web Components 和 TypeScript
组件库没有 提供多语言支持, 虽然 shoelace 提供了本地化和语言包文件

这些问题我们将在后续章节中一一解决

参考

使用 Lit 创建一个 AI 对话组件库 02 Prompts 篇

Thu, 27 Feb 2025 00:00:00 GMT

本文将深入探讨如何通过结构化提示工程(Prompt Engineering) 帮助 AI 深度理解项目上下文, 从而提升编码辅助效率

前言

随着 LLM 技术的发展, AI 的编码能力和代码阅读能力越来越强, 要实现真正的 AGI, 也就是 AI 替代人类(当然也包括程序员), 似乎最大的障碍只剩下了人类参差不齐的迷惑的表达能力, 也就是讲清楚自己要做什么, 并且让 AI 能够准确理解自己的需求; 听起来怎么这么像产品经理给程序员讲需求, 只是这次程序员变成了产品经理 😅

AI 取代论

最近爆火的 Deepseek 让我们感受到了 AI 进化的速度似乎比我们想象的更快, 那 AI 能够在何种程度上取代程序员呢? 让我们思考一下软件开发流程:

产品经理提出需求
评估需求可行性
理解需求并编写设计文档
编码
测试
修复 bug
上线

通过梳理开发流程可以看到, 真正用来编码的时间估计只有 30% ~ 50%

在 1 2 中, 产品经理是真正的人类思维, 并且 人类的表达能力并不能保证其他人能够完全准确的理解需求, 也并不懂某个需求在编码时能否实现, 更无法预知编码时需要考虑的东西, 所以就需要 需求评审 会, 作为程序员经常要跟产品经理 battle
3 系统设计, 程序员要 将人类语言拆解为可以用程序实现的具体的任务, 把看起来笼统的需求具象化
然后才开始第 4 步编码, 除了实现需求外, 还要让编码 符合项目规范, 保持良好的代码风格
随后测试环节更不能掉以轻心, 因为测试是项目上线前的最后一环, 测试人员需要 将笼统的需求转换为可实际操作的测试用例
然后开始 bug 消除环节, bug 消灭之后上线

由此我们发现, 软件开发流程中真正的复杂性在于:

需求的整理和表达能力
将人类语言转化为软件系统设计文档
将人类语言转化为测试用例

这也正是现阶段 AI 与屏幕前的用户之间的无形障碍, 就是人类需要 信息表达能力 和 信息转换的能力; 想象一下身边的大佬同事, 我们对他的评价时常是 他理解能力很强 / 他表达能力很强, 让他给我们讲讲

解药

Prompts 是 AGI 时代的编程语言

作为程序员如何能够更好的使用 AI 呢? 在我看来就是编写 尽可能准确和详细的各种文档, 在整个项目的视角上, 具体而言就是:

README.md: 描述整个项目
CHANGELOGS.md: 描述版本更新信息
CONTRIBUTING.md: 描述如何参与项目

接下来我们创建这些文件

Prompts

关键字	构成说明
角色	给 AI 定义一个最匹配任务的角色，比如：「你是一位软件工程师」「你是一位小学老师」
指示	对任务进行描述
上下文	给出与任务相关的其它背景信息（尤其在多轮交互中）
例子	必要时给出举例, 学术中称为 `one-shot learning`, `few-shot learning` 或 `in-context learning`; 实践证明其对输出正确性有很大帮助
输入	任务的输入信息；在提示词中明确的标识出输入
输出	输出的格式描述, 以便后继模块自动解析模型的
输出	结果, 比如(`JSON / XML`)

使用 repomix 提取项目代码

pnpm i -g repomix
repomix --init

repomix 会生成以下几个文件:

repomix.config.json: 配置文件
.repomixignore: 在提取代码时忽略的文件, 类似于 .gitignore

我们在 .repomixignore 中加入以下不适合提供给 AI 的文件:

public/*
src/assets/*
commitlint.config.ts
LICENSE

然后我们尝试一下将文件上传至 deepseek:

参考

使用 Lit 创建一个 AI 对话组件库 01 搭建篇

Wed, 26 Feb 2025 00:00:00 GMT

本篇将介绍如何使用 vite 创建并初始化一个 Lit + shoelace 项目

前言

此系列文章仅作为项目搭建过程的记录, 可能会忽略大量细节, 并且可能中道崩殂, 仅作为学习参考;

如果你对 Lit / Web Components 有兴趣, 请查看我的另外两篇文章:

创建项目

pnpm create vite
✔ Project name: … hyosan-chat
✔ Select a framework: › Lit
✔ Select a variant: › TypeScript

Scaffolding project in /Users/xxx/projects/hyosan-chat...

Done. Now run:

  cd hyosan-chat
  pnpm install
  pnpm run dev

:::tip 在创建项目时选择 Lit & TypeScript, 下面我们先来搭建项目工程化所需的相关依赖 👇🏻 :::

git

cd my-chat
pnpm i # 安装依赖
git init # 初始化 git 仓库

biome

biome 是一个使用 Rust 编写的 代码检查 和 格式化 工具, 相比于 eslint / prettier, 它具有更好的性能和速度, 并且 开箱即用

# 安装 biome
pnpm add --save-dev --save-exact @biomejs/biome
# 生成配置文件 biome.json
pnpm biome init

修改配置文件 biome.json:

{
	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
	"vcs": {
		"enabled": true,
		"clientKind": "git",
		"useIgnoreFile": true
	},
	"files": {
		"ignoreUnknown": false,
		"ignore": []
	},
	"formatter": {
		"enabled": true,
		"indentStyle": "tab"
	},
	"organizeImports": {
		"enabled": true
	},
	"linter": {
		"enabled": true,
		"rules": {
			"recommended": true,
			"correctness": {
				"noUnknownUnit": "off"
			}
		}
	},
	"javascript": {
		"formatter": {
			"quoteStyle": "single",
			"semicolons": "asNeeded"
		}
	}
}

为了方便使用, 我们将 biome 命令加入到 package.json scripts 中:

{
  "scripts": {
    "lint": "biome check",
    "lint:fix": "biome check --write",   
  }
}

这样我们就可以直接通过 pnpm run lint / pnpm run lint:fix 执行格式化了

然后安装编辑器插件, 我用的是 vscode, 直接安装 Biome VSCode 扩展, 详见在编辑器中集成Biome

然后创建 .vscode/extensions.json 文件, 添加如下内容:

{
  "recommendations": ["biomejs.biome"]
}

:::tip 添加 .vscode/extensions.json 是为了向其他开发者推荐安装此扩展(biome 扩展) :::

创建 .vscode/settings.json:

{
  "editor.defaultFormatter": "biomejs.biome", // 将 biome 设置为默认格式化器
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "always", // 保存时自动 fixed
    "source.organizeImports.biome": "always"
  }
}

cz-git

参考我的另一篇文章: <a href="../cz-git/" target="_blank">🔗 使用 ChatGPT 生成 git message</a>

git hooks 相关

:::warning 在上一步(cz-git)已经中安装并配置了 commitlint / commitizen, 所以这里不在提及 :::

pnpm install -D simple-git-hooks lint-staged

修改 package.json 文件:

{
+  "simple-git-hooks": {
+    "pre-commit": "npx lint-staged",
+    "commit-msg": "npx commitlint --edit ${1}"
+  },
+  "lint-staged": {
+    "*.{html,css,json,md,vue,js,ts,jsx,tsx}": "pnpm run lint:fix"
+  }
}

# Update ./git/hooks
npx simple-git-hooks

最后, 让我们测试一下是否生效:

git add -A # 添加所有文件
pnpm run cz ai # 使用 ChatGPT 生成 git message

shoelace

shoelace 是 web components 生态中最成熟的基础 UI 组件库, 有了它, 我们可以很方便的使用它来构建我们的对话组件

pnpm i @shoelace-style/shoelace

添加 demo 代码

简单的写一个 hyosan-chat 组件, 并在 index.html 中展示

index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + Lit + TS</title>

    <!-- ⚠️ 这里直接按照官方文档使用 link cdn 标签引入了样式, 用来实现 主题切换 -->
    <!-- ⚠️ 切换功能会在后续章节中实现, 实现方式暂未确定 -->

    <link
      rel="stylesheet"
      media="(prefers-color-scheme:light)"
      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/light.css"
    />
    <link
      rel="stylesheet"
      media="(prefers-color-scheme:dark)"
      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/dark.css"
      onload="document.documentElement.classList.add('sl-theme-dark');"
    />

    <link rel="stylesheet" href="./src/index.css" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div class="demo-container">
      <hyosan-chat></hyosan-chat>
    </div>
  </body>
</html>

:::tip 在代码中我们使用了最简单的 <link> 方式来引入 shoelace 样式, 在后续章节中我们会将其改为其他方式引入 :::

src/main.ts:

import '@shoelace-style/shoelace/dist/themes/light.css'
export * from "./components";

index.css:

html, body, h1, h2, h3, h4, p { padding: 0; margin: 0; }
.demo-container {
  width: 100wh;
  height: 100vh;
  display: flex;
}

index.html 是我们用来展示组件的 demo 页面, 这里修改了一下样式, 使得组件的容器元素 .demo-container 宽高 100%, 并消除了浏览器默认的 padding 和 margin 样式

增加 vite.config.ts 用于指定端口号(多个 vite 项目共用端口号会造成浏览器缓存更新带来的各种问题):

import { defineConfig } from 'vite'
import { resolve } from 'node:path'

export default defineConfig({
  server: {
    port: 29510,
  },
  preview: {
    port: 29511,
  },
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },
})

src/components/index.ts:

export { HyosanChat } from "./hyosan-chat";

src/components/hyosan-chat.ts:

import { LitElement, css, html } from "lit";
import { customElement, property } from "lit/decorators.js";
import '@shoelace-style/shoelace/dist/components/button/button.js'

@customElement("hyosan-chat")
export class HyosanChat extends LitElement {
	static styles? = css`
		:host {
			width: 100%;
			height: 100%;
		}	
	`;

	@property({ reflect: true })
	message = "Hello Lit";

	render() {
		return html`
      <h2>HyosanChat Component</h2>
      <div>Hello Lit!</div>
			<sl-button variant="primary">Hello Shoelace</sl-button>
    `;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		"hyosan-chat": HyosanChat;
	}
}

README.md

最后我们新增 README.md, 用来描述我们的组件库:

# hyosan-chat
> 🚧 Work in Progress | 此项目处于早期开发阶段
>
> hyosan-chat is currently in active development and not usable for production yet.

## 介绍
这是一个使用 [Lit@3](https://lit.dev) & [shoelace](https://shoelace.style/) 创建一个 `AI` 对话组件库

## 技术栈
- [Lit@^3.2.1](https://lit.dev): `Web Component` 库
- [shoelace@^2.20.0](https://shoelace.style/): 使用 `Web Components` 实现的 `UI` 组件库
- [vite@^6.1.0](https://github.com/vitejs/vite): 现代化的前端构建工具

:::tip README.md 文件非常重要, 他是开发者了解整个项目的重要入口 :::

编辑器自动补全插件

这里我是用的是通义灵码, copilot 也是不错的选择

参考

Lit 初体验

Tue, 25 Feb 2025 00:00:00 GMT

缘起

最近接到了一个新需求, 要开发一个与 AI 进行对话的 demo(组件), 类似于 chatgpt 网页版, 需要满足以下条件:

要 在现有框架(vue3 / ant-design-vue@3)中使用
既要可以单独部署(单页面), 又要能作为组件集成到现有项目
因为要在现有项目中引入(嵌入), 所以尽量不引入过大的依赖, 保持轻量
需求还未确定, 要有 良好的扩展性
未来可能在使用其他技术栈(例如 vue2 / react / angular)的项目中使用, 需要有 良好的兼容性

其实在开源社区已经有非常多的 chat ui, 但基本都是单独的项目, 无法作为组件引入, 似乎每个项目都立志的成为独具一格的产品

阿里的 ant-design-x 有 vue 版本 ant-design-vue-x, 它是一个成熟的组件库, 看起来满足我们的要求, 但它依赖于 ant-design-vue@4, 我们的项目中使用的是 ant-design-vue@3, 所以引入就报错了, 只能通过 iframe 的方式引入 😭

::github{repo="wzc520pyfm/ant-design-x-vue"}

前言

经过一番苦寻, 终于找到了一个名为 deepchat 的项目, 它基于 web components 创建, 所以与前端基础框架无关, 更与组件库无关, 你甚至可以在纯 html+css+js 项目中使用它

::github{repo="OvidijusParsiunas/deep-chat"}

将其引入到 vue 项目中, 发现可以正常使用, 非常 nice 😎, 关于 vue 的 web components 兼容性, 可参考我的另一篇文章 vue & web components

久闻 web components 大名, 之前工作中并未接触到它, 如今看到它无敌的兼容性, 留下了激动地泪水 😭; 在各种框架与库中兜兜转转, 最终回到了前端原生技术

前端技术更新迭代这么多年, 新技术和新框架层出不穷, 生态割裂严重:

基础组件的开发者有时不得不为每个 前端框架 都做一个 adapter(@xxx/vue / @xxx/react / @xxx/angular)
甚至为每个 框架的不同版本 做兼容性处理(vue2 和 vue3)
像 ant-design-vue-x 这样与组件库绑定的组件库, 甚至无法为 组件库的其他版本 提供支持

</details>

什么是 Lit

Lit is a simple library for building fast, lightweight web components.

At Lit's core is a boilerplate-killing component base class that provides reactive state, scoped styles, and a declarative template system that's tiny, fast and expressive.

引用官网的介绍:

Lit 是一个用于构建快速 / 轻量级 web components 的简单库

Lit 的核心是一个 能够消除样板代码的组件基类, 它提供了 响应式状态 / 作用域样式 以及一个 声明式的模板系统; 这个系统小巧 / 快速且富有表现力

:::tip 关于 web components 相关技术可以参考我的另一篇文章 🔗 web components 原生 js 实现自定义组件 :::

教程

交互式教程

直接从 <a href="https://lit.dev/learn/#filter=tutorial" target="_blank">🔗 交互式教程</a> 开始看起, 这是一个 交互式 / 带有 playground 的学习教程, 涵盖了 Lit 的所有特性

示例

如果要 快速入门 Lit, <a href="https://lit.dev/playground/#sample=examples/hello-world" target="_blank">🔗 examples</a> 是一个更好的选择

:::tip 从官方的教程搭配 ChatGPT 入门是最好的选择, 这可以确保你快速找到问题的答案 :::

首先使用 vite 创建一个 Lit 项目:

pnpm create vite
✔ Project name: … lit-demo
✔ Select a framework: › Lit
✔ Select a variant: › TypeScript

Scaffolding project in /Users/xxx/projects/lit-demo...

Done. Now run:

  cd lit-demo
  pnpm install
  pnpm run dev

import { css, html, LitElement } from "lit";
import { customElement, property, state } from "lit/decorators.js";

@customElement('count-button')
export class CountButton extends LitElement {
  @property()
  message = 'Count is '

  @state()
  count = 0
  handleClick() {
    this.count++
  }

  static styles = css`
    button {
      padding: 10px;
      font-size: 18px;
      border-radius: 10px;
      border-color: transparent;
    }
  `
  render() {
    return html`
      <button @click=${this.handleClick}>${this.message} ${this.count}</button>
    `
  }
}

declare global {
  interface HTMLElementTagNameMap {
    'count-button': CountButton
  }
}

:::tip 组件声明的标签名必须包含 -(连字符), 这确保了与浏览器内置标签不会重复 :::

核心特性

生命周期

Lit 扩展了 Web Components 的生命周期, 分为以下三个阶段, 详见 lifecycle

触发更新

当 响应式属性值更新 / 调用 requestUpdate() 时触发, Lit 会触发异步更新, 即 捕获多个属性更改并体现到一个 update 中

执行更新

此时可以更新属性值, 更新后并不会触发重新 update

完成更新

生命周期函数	继承自 `HTMLElement`	描述	执行方式	常用
`connectedCallback`	✅	当元素被添加到文档中时调用	声明	✅
`disconnectedCallback`	✅	当元素从文档中移除时调用	声明	✅
`adoptedCallback`	✅	当元素被移动到新的文档时调用	声明
`attributeChangedCallback`	✅	当元素上的属性值发生变化时调用	声明
hasChanged		在设置响应式属性时隐式调用(或 `@property` 中声明)，用于检查并决定是否触发更新	声明
requestUpdate		调用 `requestUpdate()` 来安排显式更新。一般用于与属性无关的内容发生更改时更新和呈现元素	调用	✅
shouldUpdate		在更新开始前调用，用于决定是否需要执行更新	声明	✅
willUpdate		在 `update()` 之前调用以计算 / 修改更新期间所需的值	声明	✅
update		调用以更新组件的 `DOM`	声明
render		由 `update()` 调用	声明
firstUpdated		在组件的 `DOM` 第一次更新后调用	声明
updated		每当组件的更新完成并且元素的 `DOM` 已更新和呈现时调用	声明	✅
updateComplete		值为 `Promise<boolean>`, 表示组件是否完成更新, 可通过定义 getUpdateComplete() 修改其行为	调用

attribute & property

在 Lit 中有两个很容易混淆的概念: attribute 和 property:

attribute: 指的是元素标签上的属性, 例如 <my-element foo="bar" /> 中的 foo
property: 指的是元素对象上的属性, 例如 document.querySelector('my-element').foo 中的 foo

:::tip 相比于 attribute, property 可以接受任意类型的值, 而 attribute 只能接受字符串类型 :::

常用特性

classMap

import { css, html, LitElement } from 'lit';
import { customElement, property, state } from 'lit/decorators.js';
import { classMap } from 'lit/directives/class-map.js';

@customElement('my-component')
export class MyComponent extends LitElements {
  // ...
  @state() private playDirection: -1 | 1 = 1;
  render() {
    return html`<div class="${classMap({ backwards: this.playDirection === -1 })}"></div>`
  }
}

repeat

参考教程 working with lists

参考

使用 ChatGPT 生成 git message

Sat, 22 Feb 2025 00:00:00 GMT

介绍

cz-git 是一个基于 commitlint 的交互式 git 提交命令行工具, 支持利用 AI 🤖 辅助生成提交信息

安装

pnpm i -g commitizen # 全局安装 commitizen
pnpm i -D cz-git @commitlint/{cli,config-conventional} # 在项目中安装 cz-git / commitlint

:::tip 也可全局安装 cz-git, 参考全局安装 :::

在 package.json 中增加:

{
  "config": {
    "commitizen": {
      "path": "node_modules/cz-git"
    }
  }
}

创建 commitlint 的配置文件 commitlint.config.ts:

import type { UserConfig } from 'cz-git'

const config: UserConfig = {
	extends: ['@commitlint/config-conventional'],
  prompt: {
      alias: { fd: 'docs: fix typos' },
      messages: {
          type: '选择你要提交的类型 :',
          scope: '选择一个提交范围（可选）:',
          customScope: '请输入自定义的提交范围 :',
          subject: '填写简短精炼的变更描述 :\n',
          body: '填写更加详细的变更描述（可选）。使用 "|" 换行 :\n',
          breaking: '列举非兼容性重大的变更（可选）。使用 "|" 换行 :\n',
          footerPrefixesSelect: '选择关联issue前缀（可选）:',
          customFooterPrefix: '输入自定义issue前缀 :',
          footer: '列举关联issue (可选) 例如: #31, #I3244 :\n',
          confirmCommit: '是否提交或修改commit ?',
      },
      types: [
          { value: 'feat', name: 'feat:     新增功能 | A new feature' },
          { value: 'fix', name: 'fix:      修复缺陷 | A bug fix' },
          { value: 'docs', name: 'docs:     文档更新 | Documentation only changes' },
          { value: 'style', name: 'style:    代码格式 | Changes that do not affect the meaning of the code' },
          { value: 'refactor', name: 'refactor: 代码重构 | A code change that neither fixes a bug nor adds a feature' },
          { value: 'perf', name: 'perf:     性能提升 | A code change that improves performance' },
          { value: 'test', name: 'test:     测试相关 | Adding missing tests or correcting existing tests' },
          { value: 'build', name: 'build:    构建相关 | Changes that affect the build system or external dependencies' },
          { value: 'ci', name: 'ci:       持续集成 | Changes to our CI configuration files and scripts' },
          { value: 'revert', name: 'revert:   回退代码 | Revert to a commit' },
          { value: 'chore', name: 'chore:    其他修改 | Other changes that do not modify src or test files' },
      ],
      useEmoji: false,
      emojiAlign: 'center',
      useAI: false,
      aiNumber: 1,
      themeColorCode: '',
      scopes: [],
      allowCustomScopes: true,
      allowEmptyScopes: true,
      customScopesAlign: 'bottom',
      customScopesAlias: 'custom',
      emptyScopesAlias: 'empty',
      upperCaseSubject: false,
      markBreakingChangeMode: false,
      allowBreakingChanges: ['feat', 'fix'],
      breaklineNumber: 100,
      breaklineChar: '|',
      skipQuestions: [],
      issuePrefixes: [
      // 如果使用 gitee 作为开发管理
          { value: 'link', name: 'link:     链接 ISSUES 进行中' },
          { value: 'closed', name: 'closed:   标记 ISSUES 已完成' },
      ],
      customIssuePrefixAlign: 'top',
      emptyIssuePrefixAlias: 'skip',
      customIssuePrefixAlias: 'custom',
      allowCustomIssuePrefix: true,
      allowEmptyIssuePrefix: true,
      confirmColorize: true,
      scopeOverrides: undefined,
      defaultBody: '',
      defaultIssues: '',
      defaultScope: '',
      defaultSubject: '',
  },
}

export default config

更多配置规则可参考配置文件 - commitlint

AI 生成提交信息

:::warning 涉密项目建议使用本地或内部大模型, 防止源码泄露 :::

cz-git 支持 OpenAI 或与 OpenAI 兼容的 API

pnpm i -D cross-env czg # 建议作为项目依赖使用, 同样是为了防止源码泄露

在 package.json 中增加 cz:

{
  "scripts": {
    "cz": "cross-env NODE_OPTIONS='--experimental-transform-types --disable-warning ExperimentalWarning' czg"
  }
}

:::tip 由于我们的配置文件(commitlint.config.ts), 所以需要加入 实验性参数, 详见 TypeScript 模板 :::

修改配置文件 commitlint.config.ts 以启用 AI 生成功能:

import type { UserConfig } from 'cz-git'

const config: UserConfig = {
  // ...
  useAI: true,
  aiModel: 'gpt-4o-mini',
  aiNumber: 6, // 生成 6 条信息提供给我们选择
}

设置好 API 地址和 API key, 设置好后会写入 ~/.czrc 文件中

pnpm run cz ai --api-endpoint=https://<your-path>/v1
pnpm run cz ai --api-key=<your-api-key>

我们来尝试一下:

git add -A
pnpm run cz ai

? 选择你要提交的类型 : feat:     新增功能 | A new feature
ℹ Generating your AI commit subject...
? Select suitable subject by AI generated: update TypeScript formatter to Prettier and enhance commitlint config

###--------------------------------------------------------###
feat: update TypeScript formatter to Prettier and enhance commitlint config
###--------------------------------------------------------###

? 是否提交或修改commit ? Modify and additional message with prompt

默认输出的是英文, 我们可以在 commitlint.config.ts 添加 prompt 来约束生成的提交信息:

import type { UserConfig } from 'cz-git'

const config: UserConfig = {
  // ...
  useAI: true,
  aiModel: 'gpt-4o-mini',
  aiNumber: 6,
+  aiQuestionCB({ maxSubjectLength, diff }) {
+    return `用完整句子为以下 Git diff 代码写一个有见解并简洁的 Git 中文提交消息，不加任何前缀，并且内容不能超过 ${maxSubjectLength} 个字符: \`\`\`diff\n${diff}\n\`\`\``
+  },
}

最后, 我们再次提交:

pnpm run cz ai

> fuwari@0.0.1 cz /Users/xxx/projects/blog.xiaban.run
> cross-env NODE_OPTIONS='--experimental-transform-types --disable-warning ExperimentalWarning' czg "ai"

czg@1.11.0

? 选择你要提交的类型 : feat:     新增功能 | A new feature
ℹ Generating your AI commit subject...
? Select suitable subject by AI generated: Use arrow keys or type to search
❯ 更新 TypeScript 的默认格式化工具为 Prettier，并调整 commitlint 配置以增强提交提示信息，同时添加 cross-env 和 czg 依赖
  更新 VSCode TypeScript 格式化工具为 Prettier，调整 commitlint 配置以支持更多提交类型，并添加 cross-env 依赖，优化项目构建配置
  更新 TypeScript 格式化工具为 Prettier，调整 commitlint 配置以支持更多类型，并添加 cross-env 依赖以优化环境变量设置
  更新 VSCode 配置以使用 Prettier 作为 TypeScript 的默认格式化工具，同时优化 commitlint 配置，新增支持的提交类型和依赖项
  更新 Visual Studio Code 的 TypeScript 格式化工具为 Prettier，并优化 commitlint 配置，增加对自定义问题前缀的支持
  修改了 VSCode 的 TypeScript 默认格式化工具为 Prettier，并更新了 commitlint 配置以支持更多提交类型，同时添加了 cross-env 和 czg 依赖

###--------------------------------------------------------###
feat: 更新 TypeScript 的默认格式化工具为 Prettier，并调整 commitlint 配置以增强提交提示信息，同时添加 cross-env 和 czg 依赖
###--------------------------------------------------------###

? 是否提交或修改commit ? Yes
[main cacbaf8] feat: 更新 TypeScript 的默认格式化工具为 Prettier，并调整 commitlint 配置以增强提交提示信息，同时添加 cross-env 和 czg 依赖
 8 files changed, 248 insertions(+), 61 deletions(-)
 create mode 100644 src/content/posts/2025/assets/images/cz-git-openai.gif
 create mode 100644 src/content/posts/2025/assets/images/cz-git-screenshot.gif

完结撒花 ❤️

20250-03-09 更新

commitlint 对于 ts 文件的支持不太行 😡, 所以将文件名改回了 commitlint.config.mjs, 又加入了自定义的 tag WIP, 完整代码如下:

// import { RuleConfigSeverity } from 'commitlint'
import { defineConfig } from 'cz-git'

const config = defineConfig({
	extends: ['@commitlint/config-conventional'],
	rules: {
		'type-enum': [
			2,
			'always',
			[
				'build',
				'chore',
				'ci',
				'docs',
				'feat',
				'fix',
				'perf',
				'refactor',
				'revert',
				'style',
				'test',
				'WIP',
			],
		],
		'type-case': [0], // 禁用类型大小写检查
	},
	prompt: {
		alias: { fd: 'docs: fix typos' },
		messages: {
			type: '选择你要提交的类型 :',
			scope: '选择一个提交范围（可选）:',
			customScope: '请输入自定义的提交范围 :',
			subject: '填写简短精炼的变更描述 :\n',
			body: '填写更加详细的变更描述（可选）。使用 "|" 换行 :\n',
			breaking: '列举非兼容性重大的变更（可选）。使用 "|" 换行 :\n',
			footerPrefixesSelect: '选择关联issue前缀（可选）:',
			customFooterPrefix: '输入自定义issue前缀 :',
			footer: '列举关联issue (可选) 例如: #31, #I3244 :\n',
			confirmCommit: '是否提交或修改commit ?',
		},
		types: [
			{ value: 'feat', name: 'feat:     新增功能 | A new feature' },
			{ value: 'fix', name: 'fix:      修复缺陷 | A bug fix' },
			{ value: 'WIP', name: 'WIP:      暂未完成 | Not yet completed' },
			{
				value: 'docs',
				name: 'docs:     文档更新 | Documentation only changes',
			},
			{
				value: 'style',
				name: 'style:    代码格式 | Changes that do not affect the meaning of the code',
			},
			{
				value: 'refactor',
				name: 'refactor: 代码重构 | A code change that neither fixes a bug nor adds a feature',
			},
			{
				value: 'perf',
				name: 'perf:     性能提升 | A code change that improves performance',
			},
			{
				value: 'test',
				name: 'test:     测试相关 | Adding missing tests or correcting existing tests',
			},
			{
				value: 'build',
				name: 'build:    构建相关 | Changes that affect the build system or external dependencies',
			},
			{
				value: 'ci',
				name: 'ci:       持续集成 | Changes to our CI configuration files and scripts',
			},
			{ value: 'revert', name: 'revert:   回退代码 | Revert to a commit' },
			{
				value: 'chore',
				name: 'chore:    其他修改 | Other changes that do not modify src or test files',
			},
		],
		useEmoji: false,
		emojiAlign: 'center',
		useAI: true,
		aiNumber: 6,
		aiModel: 'gpt-4o-mini',
		aiQuestionCB({ maxSubjectLength, diff }) {
			return `用完整句子为以下 Git diff 代码写一个有见解并简洁的 Git 中文提交消息，不加任何前缀，并且内容不能超过 ${maxSubjectLength} 个字符: \`\`\`diff\n${diff}\n\`\`\``
		},
		themeColorCode: '',
		scopes: [],
		allowCustomScopes: true,
		allowEmptyScopes: true,
		customScopesAlign: 'bottom',
		customScopesAlias: 'custom',
		emptyScopesAlias: 'empty',
		upperCaseSubject: false,
		markBreakingChangeMode: false,
		allowBreakingChanges: ['feat', 'fix'],
		breaklineNumber: 100,
		breaklineChar: '|',
		skipQuestions: [],
		issuePrefixes: [
			// 如果使用 gitee 作为开发管理
			{ value: 'link', name: 'link:     链接 ISSUES 进行中' },
			{ value: 'closed', name: 'closed:   标记 ISSUES 已完成' },
		],
		customIssuePrefixAlign: 'top',
		emptyIssuePrefixAlias: 'skip',
		customIssuePrefixAlias: 'custom',
		allowCustomIssuePrefix: true,
		allowEmptyIssuePrefix: true,
		confirmColorize: true,
		scopeOverrides: undefined,
		defaultBody: '',
		defaultIssues: '',
		defaultScope: '',
		defaultSubject: '',
	},
})

export default config

然后将 package.json 中的 scripts 修改为 "cz": "czg":

- "cz": "cross-env NODE_OPTIONS='--experimental-transform-types --disable-warning ExperimentalWarning' czg"
+ "cz": "czg"

pnpm remove cross-env

参考

web components 原生 js 实现自定义组件

Fri, 21 Feb 2025 00:00:00 GMT

什么是 web components

Lit 是对 web components 的封装与抽象, 其最核心的价值是让 web components 更加适应现代化的前端开发工作流; 所以让我们 从 web components 开始讲起

web components 想要实现的是让我们 用原生 js 编写一个组件, 其核心概念由以下技术组成:

Custom Element: 自定义元素
Shadow DOM: 影子 DOM
HTML template:
- <template> 可重用元素
- slot 插槽

下面我们从零开始, 一步一步实现一个 web components:

# 创建一个 vite 项目, framework 选择 Vanilla, variant 选择 TypeScript
pnpm create vite

# 使用 vscode 打开这个项目
cd web-components-demo && code .

# 安装依赖并启动项目, 然后在浏览器打开 http://localhost:5173/
pnpm i && pnpm run dev

:::tip 你可能会好奇为什么要使用 vite 来创建项目, web components 明明不依赖于任何技术或库, 这里使用 vite 是为了热刷新和 ts 支持, 如果你不想使用 vite, 可以直接创建一个 html 文件, 或直接在 🔗 官方模板项目中操作 :::

:::tip 这里直接在命令行中使用 code 打开了这个项目, 如果你没有这个命令, 需要在 vscode 中按下 ctrl + shift + p, 输入 Shell Command: Install 'code' command in PATH 来启用 :::

这是 vite 项目的默认页面, 接下来我们将完全使用 web components 来实现页面中的 count 按钮:

code src/lib.ts

src/main.ts 中添加:

import './lib.ts'

Custom Elements

下面我们在 src/lib.ts 文件中编写代码:

/** 0️⃣ 自定义元素 - 计数按钮 */
class CountButton extends HTMLElement {
  private _count = 0

  /** 1️⃣ 元素被添加到页面中时执行 */ 
  constructor() {
    super()

    /** 2️⃣ shadow DOM */
    const shadow = this.attachShadow({ mode: 'open' })

    /** 计数按钮 */
    const button = document.createElement('button')
    button.textContent = `count is ${this._count}` // 绑定元素内容
    button.addEventListener('click', () => button.textContent = `count is ${++this._count}`) // 绑定点击事件

    /** 3️⃣ 样式元素 */
    const style = document.createElement('style')
    style.textContent = `
      button {
        border-radius: 8px;
        border: 1px solid transparent;
        padding: 0.6em 1.2em;
        font-size: 1em;
        font-weight: 500;
        font-family: inherit;
        background-color: #1a1a1a;
        cursor: pointer;
        transition: border-color 0.25s;
      }
      button:hover {
        border-color: #646cff;
      }
      button:focus,
      button:focus-visible {
        outline: 4px auto -webkit-focus-ring-color;
      }
    `

    shadow.appendChild(style) // 插入样式
    shadow.appendChild(button) // 插入元素
  }
}

// 4️⃣ 注册自定义元素
customElements.define('count-button', CountButton)

然后我们将 <count-button> 加入 HTML 中, 修改 src/main.ts, 在原有按钮下方加入:

    <div class="card">
      <button id="counter" type="button"></button>
    </div>
+    <div>
+      <count-button></count-button>
+    </div>

点击下方的计数按钮, 你会发现 count 数增加了, 下面我们逐一说明代码中用到的技术

0️⃣: 自定义元素, 官方提到了两种实现方式:
- class CountButton extends HTMLElement: ✅ 常用方式
- class CountButton extends HTMLButtonElement: ⚠️ 通过查看 caniuse Custom Elements 发现, is 属性在 Safari 上有兼容问题, 为避免不必要的麻烦, 不推荐此实现方式
1️⃣: 生命周期回调函数, 一共有 4 个 API:
- connectedCallback(): 元素已添加到页面中, 对应 vue 的 mounted
- disconnectedCallback(): 元素已从页面中移除, 对应 vue 的 unMounted
- adoptedCallback(): 从一个文档进入另一个文档, 例如移动至 iframe 中, 较少使用
- attributeChangedCallback(name, oldValue, newValue): 在属性更改 / 添加 / 移除 / 替换时调用, 用于监听组件属性变化
2️⃣: const shadow = this.attachShadow({ mode: 'open' }), 创建了一个 可以被外部访问的节点, 详见 attchShadow API
3️⃣: 这里直接复制了 src/styles.css 中的按钮的样式, 因为 Shadow DOM 中的元素无法继承文档中的已有的样式, 内部样式与外部样式严格隔离, 虽然可以像这样使用 <link rel="stylesheet" href="style.css"> 实现
4️⃣: 需要注册才能在文档中使用, 对应 vue 的 app.component('MyComponent', MyComponent)

如果你是一个已经熟悉 TypeScript 和前端生态的 ~~老油条~~ 开发者, 此时你应该已经发现, 这样的写法存在诸多问题:

1️⃣ 组件缺少状态管理, 状态改变时无法自动更新 DOM, 需要手动监听并更新
在 2️⃣ 3️⃣ 中编写的 HTML / CSS 太过于原始, 没有任何代码提示或者说类型约束

响应式实现

在 connectedCallback 中我们创建了按钮并绑定了点击事件, 点击后 _count 自增, 但它是一个只能在组件内部使用的值, 我们将其改为 可以在外部定义和修改的值

class CountButton extends HTMLElement {
  /** 需要监听的属性 */
  static observedAttributes = ['count']
  /** 数量 */
  private _count = 233

  /** 按钮元素 */
  private _button = document.createElement('button')
  /**
   * 更新按钮元素的内容
   * @param count 数量
   */
  private _updateButtonContent(count = this._count) {
    this._button.textContent = `count is ${count}`
  }

  attributeChangedCallback(name: string, oldValue: string, newValue: string) {
    console.log(`${name} changed from ${oldValue} to ${newValue}`) // 属性变化时触发
    if (name === 'count') {
      this._count = Number(newValue)
      this._updateButtonContent()
    }
  }

  constructor() {
    super()

    /** shadow DOM */
    const shadow = this.attachShadow({ mode: 'open' })

    /** 计数按钮 */
    this._updateButtonContent()
    this._button.addEventListener('click', () => this._updateButtonContent(++this._count)) // 绑定点击事件

    /** 样式元素 */
    const style = document.createElement('style')
    style.textContent = `
      button {
        border-radius: 8px;
        border: 1px solid transparent;
        padding: 0.6em 1.2em;
        font-size: 1em;
        font-weight: 500;
        font-family: inherit;
        background-color: #1a1a1a;
        cursor: pointer;
        transition: border-color 0.25s;
      }
      button:hover {
        border-color: #646cff;
      }
      button:focus,
      button:focus-visible {
        outline: 4px auto -webkit-focus-ring-color;
      }
      @media (prefers-color-scheme: light) {
        :root {
          color: #213547;
          background-color: #ffffff;
        }
        button {
          background-color: #f9f9f9;
        }
      }
    `

    shadow.appendChild(style) // 插入样式
    shadow.appendChild(this._button) // 插入元素
  }

  /** 元素被添加到页面中时执行 */
  connectedCallback() {
    // 如果元素未添加 count 属性, 那么就添加并设置为默认值
    if (!this.hasAttribute('count')) this.setAttribute('count', this._count.toString())
  }
}

// 注册自定义元素
customElements.define('count-button', CountButton)

我们增加了内部状态 _count, 增加了监听函数 attributeChangedCallback, 并对按钮的内容渲染逻辑和点击事件进行了分离, 实现了:

点击按钮时 count + 1
当没有为元素添加 count 属性时, 自动为其添加 count 属性
当元素的 count 属性更新时, 同步更新内部的状态值 _count

至此就实现了 vue 中的双向数据绑定的效果

Custom Elements 常见错误

在 constructor 中设置属性值

class MyDemo extends HTMLElement {
  /** 需要监听的属性 */
  static observedAttributes = ['count']

  constructor(
    private _count = 1,
  ) {
    super()
    this.setAttribute('count', this._count.toString())

    /** shadow DOM */
    const shadow = this.attachShadow({ mode: 'open' })
    const content = document.createElement('div')
    content.textContent = this._count.toString()
    shadow.appendChild(content)
  }
}

customElements.define('my-demo', MyDemo)

// demo
const myDemo = document.createElement('my-demo')

注意最后一行, 如果我们通过 createElement 的方式创建自定义元素, 并且在 constructor 中设置了属性值, 浏览器会报错:

:::tip 这是因为违反了 createElement 调用者的期望, 即调用 createElement 时, 可以理解为调用者预期的元素是无属性的空元素, 详见 Requirements for custom element constructors and reactions - HTML Standard :::

在 constructor 中获取外部传入的属性值

有时我们希望在自定义组件初始化时根据外部传入的属性值处理组件的状态, 但在 使用 createElement 时获取到的属性值是空的:

class CountButton extends HTMLElement {
  constructor() {
    console.log('[constructor] test: ', this.getAttribute('test'))
  }
  connectedCallback() {
    console.log('[connectedCallback] test: ', this.getAttribute('test'))
  }
}

在 HTML 中直接写入元素:

<div>
  <count-button test="test" />
</div>

output:

[constructor] test:  test
[connectedCallback] test:  test

通过 createElement 创建元素:

const cb = document.createElement('count-button')
cb.setAttribute('test', 'test')
document.body.appendChild(cb)

output:

[constructor] test:  null
[connectedCallback] test:  test

:::warning 由此可见, 如果希望获取或设置元素的属性值, 应该在 connectedCallback 中 :::

Shadow DOM

也许你已经发现, 在浏览器的 Elements 中出现了一个 #shadow-root 的节点, 它与其他普通的 DOM 节点有明显的不同: #shadow-root 内部的节点不受外部样式和 js 的影响

也无法通过 querySelectorAll 在文档中查找到此 #shadow-root 内部的元素, shadow DOM 提供了一道与外部文档隔离的屏障

但如果 shadow DOM 声明为 { mode: 'open' }, 则可以通过 shadowRoot 属性访问内部的节点; 如果我们的组件不想被外部文档访问, 则可以改为 { mode: 'closed' }, 此时自定义元素的 shadow DOM 对外部文档来说就是 完全不可见 的:

使用 CSSStyleSheet 构造样式

class MyComponent extends HTMLElement {
  constructor() {
    super()
    /** shadow DOM */
    const shadow = this.attachShadow({ mode: 'open' })
    const content = document.createElement('div')
    content.textContent = 'CSSStyleSheet Demo'

    const sheet = new CSSStyleSheet()
    sheet.replaceSync('div { color: red; font-size: 20px; }')

    shadow.adoptedStyleSheets.push(sheet)
    shadow.appendChild(content)
  }
}
customElements.define('my-component', MyComponent)

这里我们单独声明了一个 CSSStyleSheet, 并在 shadown 的 adopetdStyleSheets 中加入了该样式, CSSStyleSheet 的意义在于:

管理样式更加灵活, 允许向 shadow DOM 或其子元素添加多个 sheet 模块, 并且可以动态修改样式
便于共享样式, 如果样式要被多个元素共同使用, 可以将 sheet 提取到外部实现共享

使用 template

<div>
  <h1>H1 Title</h1>
</div>
<template id="my-template">
  <style>
    div {
      color: red;
      font-size: 20px;
    }
  </style>
  <div>Template Demo</div>
</template>
<my-component></my-component>
<my-component></my-component>

class MyComponent extends HTMLElement {
  constructor() {
    super()
    /** shadow DOM */
    const shadow = this.attachShadow({ mode: 'open' })

    const myTemplate = document.getElementById('my-template')

    shadow.appendChild(myTemplate.content.cloneNode(true))
  }
}
customElements.define('my-component', MyComponent)

<template> 提供了一种声明式的写法, 并且像 Shadow DOM 一样具有样式和 js 隔离, 让我们可以实现样式及元素的复用(cloneNode), 相比于最初的编程式更加直观, 也更贴近现代化的前端开发体验

template & slot

如果你熟悉 vue, 那应该会对 <template> 感到非常亲切, 在 vue 中我们可以写 <slot>, 在 <template> 中同样可以!

<style>
  h2 {
    text-decoration-line: underline;
  }
</style>
<template id="my-title">
  <style>
    header {
      color: red;
    }
  </style>
  <header>
    <slot name="title">NEED TITLE</slot>
  </header>
</template>
<script src="./web-components-shadow-dom-slot.js"></script>
<my-title>
</my-title>
<my-title>
  <h2 slot="title">title</h2>
</my-title>

class MyTitle extends HTMLElement {
  constructor() {
    super()
    /** shadow DOM */
    const shadow = this.attachShadow({ mode: 'open' })

    const myTemplate = document.getElementById('my-title')

    shadow.appendChild(myTemplate.content.cloneNode(true))
  }
}
customElements.define('my-title', MyTitle)

:::tip 这里的 <h2 slot="title"> 即带有组件内的红色样式, 也有组件外部的下划线样式, 可见 slot 元素与 Shadow DOM 内部元素的不同点: slot 元素(插槽) 是可以继承外部样式的 :::

局限性

生态孱弱, 发展缓慢, 相比 vue / react, web components 显然在生态上更加落后
缺乏响应式系统, Vue 和 React 的核心优势之一是其响应式数据绑定系统, 可以让 UI 随着数据的变化自动更新, 而 web components 需要手动实现
样式封闭, 无法像 vue / react 一样灵活的继承与覆盖样式
开发效率低下, web components 更加贴近底层, 无法像 vue / react 一样提供抽象能力

web components 的兼容性

:::warning 根据 caniuse web components:

web components 在 Safari 上不支持 is 属性, 故不支持扩展内置元素 :::

生态

可在 webcomponents.org 搜索更多 web components 组件

基础框架

UI 组件库

vue & web components

根据 vue 官方文档对于 web components 的描述:

我们认为 Vue 和 Web Components 是互补的技术。Vue 为使用和创建自定义元素提供了出色的支持。无论你是将自定义元素集成到现有的 Vue 应用中，还是使用 Vue 来构建和分发自定义元素都很方便

vue 似乎有意依托成熟的功能和抽象能力, 成为支持 web components 的框架, 将 web components 融入自己

常见问题

Custom Elements 的初始化逻辑应该写到 constructor 还是 connectedCallback?

constructor:
- 初始化自定义元素类的内部状态
- 初始化 shadow DOM
connectedCallback:
- 设置或读取外部设置的元素属性

参考

fish shell 配置

Wed, 19 Feb 2025 00:00:00 GMT

介绍

::github{repo="fish-shell/fish-shell"}

fish shell(the friendly interactive shell) 是一个开源的终端命令行工具, 它具有许多功能, 如 自动补全 / 语法高亮 / 命令历史记录 等

为什么使用 fish shell

开箱即用的 语法高亮 ✨
开箱即用的 输入时建议 / 基于历史记录补全 🔥
丰富的插件 🔌 / 主题 🎨
简洁友好的语法 🌿

兼容性

:::warning fish shell 与 macOS 自带的 zsh 最大的不同就是, fish shell 不完全兼容 bash POSIX shell, 这会导致在 fish 中执行一些 shell 脚本时会报错 :::

安装

MacOS

brew install fish

Linux

sudo apt-add-repository ppa:fish-shell/release-3
sudo apt update
sudo apt install fish

windows

在 windows 上, fish shell 可以在 Windows Subsystem for Linux 上安装, 其他终端环境的兼容性不详, 更多信息可以参考 windows - fish shell

设置为默认 shell

以 macOS 为例:

查看 fish 路径

wihch fish
/opt/homebrew/bin/fish

尝试使用 chsh 命令设置 fish 为默认 shell

chsh -s /opt/homebrew/bin/fish

退出终端并打开新终端测试

exit # 退出当前终端

打开新终端:

# 如果未进入 fish shell, 则需要在 /etc/shells 文件末尾增加 fish shell 的路径, 然后再次进入新终端测试
echo "/opt/homebrew/bin/fish" | sudo tee -a /etc/shells > /dev/null

:::warning 至此 fish shell 已经安装并设置为默认 shell, 但在某些 Linux 系统上, 可能会遇到各种报错, 若无法解决, 也可以在每次进入终端后执行 fish 进入 fish shell :::

配置

fish shell 的配置文件在 ~/.config/fish/config.fish

配置文件

在 fish shell 的配置文件中一般会设置一些 环境变量 / function / fish 配置 等, 以下是一些示例:

环境变量

将 ~/.cargo/bin 加入系统环境变量 PATH 中:

# rust
set -Ux CARGO_HOME $HOME/.cargo
set -Ux PATH $CARGO_HOME/bin $PATH

function

增加用于设置代理的 proxy function:

function proxy
    set -Ux all_proxy http://127.0.0.1:7890
    set -Ux http_proxy http://127.0.0.1:7890
    set -Ux https_proxy http://127.0.0.1:7890
    echo all_proxy=$all_proxy
    echo http_proxy=$http_proxy
    echo https_proxy=$https_proxy
end

function noproxy
    set -e all_proxy
    set -e http_proxy
    set -e https_proxy
end

设置成功后可直接执行 proxy / noproxy 来启用和关闭代理

proxy # 开启代理
noproxy # 关闭代理

fish 配置

fish shell 也提供了一些配置项, 我这里只设置了 vi key bindings:

~/.config/fish/config.fish:

fish_vi_key_bindings

source ~/.config/fish/config.fish

此时 在终端命令行中就可以使用 vim 的常用操作了, 对于 vim 党非常友好, 例如:

模式:
- Insert Mode
- Command Mode
- Visual Mode
光标移动: hjkl / 0 / $ / w / b / e / ...
编辑: dd / D / u / C-r / ...
其他: / 搜索历史记录

fish_config

fish_config 是一个图形化配置工具, 可以通过它来配置 fish shell 的 colors / prompt / functions / ...

fish_config # 执行后会打开一个网页

:::tip 在选择好 colors / prompt 后, 需要点击 Set Theme / Set Prompt 才会生效, 已有的终端也需要 source ~/.config/fish/config.fish 才会生效 :::

oh-my-fish

::github{repo="oh-my-fish/oh-my-fish"}

oh-my-fish 是一个开源的 fish shell 的插件管理器, 类似于 zsh 的 oh-my-zsh, 可以通过它来安装一些常用的插件 / 主题

安装主题

在开源社区有非常多有意思的主题, 查看所有主题: Themes

例如安装 bobthefish theme

omf install bobthefish

示例:

安装字体

:::tip 由于 bobthefish theme 使用了一些特殊符号, 我们电脑中的默认字体中并没有这些符号, 所以需要安装 patched-fonts 来支持这些特殊符号, 详见 patched-fonts :::

这里推荐从 ryanoasis/nerd-fonts 找到自己喜欢的字体, 并在 releases 中下载对应的字体文件并在系统上安装, 字体文件比较多, 并不需要都安装, 选择一个系列的全选右键打开安装即可

安装完字体后, 还需要在自己的终端软件中设置字体, 例如在 iTerm2 中:

点击 iTerm2 > Settings > Profiles > Text
进入 Text > Font, 选择 Use a different font for non-ASCII text 并选择 Non-ASCII Font 字体, 或直接在 Font 中选择安装的字体

:::tip 如果启用了 Hotkey Window, 需要同步设置 Default / Hotkey Window :::

获取帮助

fish shell 提供了一个帮助文档, 执行 help 命令即可打开一个帮助文档网页

help

参考

服务器请求阿里邮箱服务器发送邮件

Thu, 13 Feb 2025 00:00:00 GMT

有时在服务器上触发某些事件时, 需要向用户(主要是我自己)发送邮件, 使用 msmtp 实现发送邮件, 如果已经开通了阿里邮箱, 就 无需自己搭建邮件服务器

:::tip 之前我已经配置好了阿里邮箱 - 免费版(参考 📚 阿里云配置域名邮箱), 但是阿里邮箱的 API 开放平台免费版并不支持, 所以无法通过 API 实现发送邮件的功能, 但好在阿里邮箱 允许第三方客户端收发邮件, 所以只要 配置好阿里邮箱, 并通过 msmtp 发送邮件即可 :::

<!-- ## 域名解析

~~@ MX mail.example.com | 1~~

这条 MX 记录是表示 指定接收邮件的服务器

:::tip 由于我 没有接收邮件的需求(已经有阿里邮箱了), 所以忽略 @ MX mail.example.com | 1 解析(与阿里邮箱的解析冲突) :::

@ A mail.example.com

这条记录用来解析 mail 子域名到自己的服务器

@ TXT v=spf1 mx:mail.example.com -all

这条记录用来 指定发送邮件的服务器

:::warning 如果你像我一样在 1 中没有配置 MX 记录, 则此处的 mx:mail.example.com 应该替换为 a:mail.example.com(即 2 中配置的 A 记录) :::

SPF(Sender Policy Framework)是一种 DNS TXT 记录，它用于指定哪些服务器有权代表你的域名发送邮件, 以减少垃圾邮件和邮件欺诈的风险, 格式为:

v=spf1 [mechanisms] [modifiers]

v=spf1: SPF 版本
mechanisms: 表示允许的邮件服务器来源, 比如 ip4 / mx / include 等
modifiers: -all 拒绝不匹配邮件 / ~all 软失败 / +all 允许所有

:::warning 如果配置了阿里邮箱:

注意: 阿里邮箱已经有一条 SPF 记录了(@ TXT v=spf1 include:spf.qiye.aliyun.com -all), 这里只需要将加入 mail.example.com:

@ TXT v=spf1 include:spf.qiye.aliyun.com a:mail.example.com -all

:::

我的最终配置

@ A mail.example.com
@ TXT v=spf1 include:spf.qiye.aliyun.com a:mail.example.com -all -->

msmtp

配置好解析规则后, 就需要在服务器上安装并配置 msmtp

msmtp 是一个轻量级的 msmtp 客户端(命令行工具), 适用于 只需要发送邮件的场景

安装 msmtp

sudo apt update && sudo apt install msmtp msmtp-mta -y
# 安装时会提示是否启用 AppArmor, 直接选择 No

配置 msmtp

vim /etc/msmtprc

# 设置默认账户
account default
# 启用 STARTTLS
tls on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
# 465 端口使用的是 SSL/TLS, 而不是 STARTTLS
tls_starttls off
# 你的 SMTP 服务器
host smtp.qiye.aliyun.com
# 端口号（465 是 SMTPS，587 是 STARTTLS）
port 465
# 你的邮件账户
auth on
user no-reply@example.com
password your-password
# 发送者邮箱
from no-reply@example.com

这里需要注意:

阿里邮箱只开放 465 端口, 所以需要将 tls_starttls 设置为 off
将 example.com 替换为你的域名

这里创建了 msmtp 的配置文件, 配置文件也可以放到 ~/.msmtprc, 配置好后最好设置一下权限为 600

配置阿里邮箱

我们 不在服务器自己搭建邮件服务, 直接通过阿里邮箱实现发送邮件, 所以此场景下, 服务器需要安装用户发送邮件的客户端(msmtp), 阿里邮箱需要创建账号并开启 SMTP

创建 no-reply 账号

创建一个用于发送邮件的账号

进入阿里邮箱网页端
进入组织与用户 - 员工账号管理 - 新建账号(no-reply@example.com), 必须勾选开启 IMAP/SMPT 服务

配置安全策略

阿里邮箱默认不允许第三方客户端登录, 需要在 安全管理 - 账号安全策略 中进行配置

进入安全管理 - 账号安全策略
(可选) 自由端双重认证 > 启用范围中排除 no-reply@example.com, 此时可以通过邮件客户端登录 no-reply@example
三方客户端安全, 开启 允许使用第三方客户端, 启用范围根据需要修改, 必须包含 no-reply@example.com
定期修改密码提醒 > 例外账号, 添加 no-reply@example.com

发送邮件

由于是在命令行中调用 msmtp 发送邮件, 所以需要注意一下邮件内容的格式:

Subject: 邮件标题
From: 邮件发送者 <no-reply@example.com>
To: 邮件接收者 <no-reply@example.com>

邮件内容

echo -e "Subject: 这是一封测试发送的邮件, 来自服务器\n\n这里是邮件内容, 仅用于测试" | msmtp me@test.com

:::warning 如果内容过于简单, 可能会直接进入邮件接受者的垃圾箱 :::

参考

MacOS 安装及配置 PostgreSQL 17

Tue, 11 Feb 2025 00:00:00 GMT

本文将介绍在 MacOS 下如何使用 brew 安装并运行 PostgreSQL 17, 并进行基本的初始化配置

安装

brew install postgresql@17 # 指定安装 17.x
# brew install postgresql # 不指定版本, 当前默认安装的版本是 14

# 安装过程较慢, 可以配置代理

brew services start postgresql@17 # 启动服务
# brew services start postgresql # 不指定版本, 当前默认会启动 14

运行

brew services list # 查看 postgresql 服务状态

Name          Status  User  File
mysql         none
nginx         none    root
postgresql@17 started xxxx ~/Library/LaunchAgents/homebrew.mxcl.postgresql@17.plist
unbound       none
v2ray         none

如果 Status 为 error, 可以在日志文件(tail /opt/homebrew/var/log/postgresql@17.log) 中查看具体的报错

:::warning 一个常见的错误是使用 sudo brew 启动服务, 会导致启动报错:

"root" execution of the PostgreSQL server is not permitted.
The server must be started under an unprivileged user ID to prevent
possible system security compromise.  See the documentation for
more information on how to properly start the server.

应该直接使用 brew 启动服务 :::

配置

在安装后数据库的默认用户时当前登录的用户, 可通过 whoami 命令查看当前登录的用户, 并且只有一个名为 postgres 的数据库

psql -d postgres # 进入 postgres 数据库

psql (17.2 (Homebrew))
输入 "help" 来获取帮助信息.

postgres=# exit

如果想要直接通过 psql 进入数据库, 需要创建一个与当前用户同名的数据库(假设当前用户是 xxxx):

psql -d postgres # 进入 postgres 数据库

postgres=# CREATE DATABASE xxxx OWNER xxxx;
CREATE DATABASE
postgres=# GRANT ALL PRIVILEGES ON DATABASE xxxx TO xxxx;
GRANT
postgres=# exit

pgcli

::github{repo="dbcli/pgcli"}

:::tip 当我们使用 psql 进入数据库时, 会发现在命令行中没有任何代码提示, 其实已经有一个名为 pgcli 的命令行工具可以解决这个问题, 这是一个使用 python 编写的有 自动补全和语法高亮 的命令行工具 :::

安装 pgcli

brew install pgcli # 通过 brew 安装
# pip install -U pgcli # 或者通过 pip 安装

使用 pgcli

Usage: pgcli [OPTIONS] [DBNAME] [USERNAME]

Options:
  -h, --host TEXT          Host address of the postgres database.
  -p, --port INTEGER       Port number at which the postgres instance is
                           listening.
  -U, --username TEXT      Username to connect to the postgres database.
  -u, --user TEXT          Username to connect to the postgres database.
  -W, --password           Force password prompt.
  -w, --no-password        Never prompt for password.
  --single-connection      Do not use a separate connection for completions.
  -v, --version            Version of pgcli.
  -d, --dbname TEXT        database name to connect to.
  --pgclirc FILE           Location of pgclirc file.
  -D, --dsn TEXT           Use DSN configured into the [alias_dsn] section of
                           pgclirc file.
  --list-dsn               list of DSN configured into the [alias_dsn] section
                           of pgclirc file.
  --row-limit INTEGER      Set threshold for row limit prompt. Use 0 to
                           disable prompt.
  --application-name TEXT  Application name for the connection.
  --less-chatty            Skip intro on startup and goodbye on exit.
  --prompt TEXT            Prompt format (Default: "\u@\h:\d> ").
  --prompt-dsn TEXT        Prompt format for connections using DSN aliases
                           (Default: "\u@\h:\d> ").
  -l, --list               list available databases, then exit.
  --auto-vertical-output   Automatically switch to vertical output mode if the
                           result is wider than the terminal width.
  --warn TEXT              Warn before running a destructive query.
  --ssh-tunnel TEXT        Open an SSH tunnel to the given address and connect
                           to the database from it.
  --log-file TEXT          Write all queries & output into a file, in addition
                           to the normal output destination.
  --help                   Show this message and exit.

下面我们进入数据库:

# xxxx 是在配置章节创建的数据库, 如果没有创建, 可以直接使用 pgcli postgres 进入 postgres 数据库
pgcli xxxx

Server: PostgreSQL 17.2 (Homebrew)
Version: 4.1.0
Home: http://pgcli.com
xxxx@/tmp:xxxx>



 [F2] Smart Completion: ON  [F3] Multiline: OFF  [F4] Emacs-mode  [F5] Explain: OFF

底部显示: [F2] Smart Completion: ON [F3] Multiline: OFF [F4] Emacs-mode [F5] Explain: OFF 可以看到当前 pgcli 的配置

其中 [F2] 为智能补全, [F3] 为多行输入, [F4] 为 emacs 模式, [F5] 为解释器模式, [F6] 为语法高亮, [F7] 为自动补全

:::tip pgcli 默认是 Eamcs mode, 对于 vim 党来说首先要配置的就是修改为 vim mode:

vim ~/.config/pgcli/config

找到 vi = False, 将其改为:

vi = True

另外, 如果你更习惯多行模式, 可以配置默认启用 Multiline:

multi_line = True

在 multiline 模式下, 只有在输入 ; 后才会执行, 可以直接换行 :::

配置文件

默认的配置文件在 /opt/homebrew/var/postgresql@17 目录下, 可通过执行 `` 查看配置文件位置

psql -c "SHOW config_file" # 查看 postgresql 配置文件位置
psql -c "SHOW hba_file" # 查看 pg_hba 配置文件位置

配置为允许远程连接

postgresql.conf:

listen_addresses = '*'

pg_hba.conf 末尾加入:

 host    all             all             0.0.0.0/0               md5

# 修改配置后重启 postgresql 服务
brew services restart postgresql@17

连接远程数据库

psql -h 192.168.1.100 -p 5432 -U myuser -d mydatabase

基础操作

更多操作可以参考官方文档 v17 / pg 使用规范

用户与权限

创建用户

在 PostgreSQL 中，可以通过 CREATE ROLE 命令创建用户。CREATE ROLE 是一个通用命令，用于创建角色（包括用户和组角色）。用户本质上是一种可以登录的特殊角色

CREATE ROLE myuser WITH LOGIN PASSWORD 'mypassword';

-- 创建超级管理员账户
CREATE ROLE myuser WITH LOGIN PASSWORD 'mypassword' SUPERUSER;

超级管理员权限

-- 为已有用户分配超级管理员权限
ALTER USER myuser WITH SUPERUSER;

分配普通权限

-- 允许用户 myuser 连接到数据库 mydatabase
GRANT CONNECT ON DATABASE mydatabase TO myuser;

-- 允许用户 myuser 对 public 模式中的所有表执行 SELECT、INSERT、UPDATE 和 DELETE 操作
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO myuser;

数据库

-- 查看所有数据库
SELECT * FROM pg_database;

\list
-- 创建数据库
-- 创建完成后，可以使用 `\c mydatabase` 命令切换到该数据库
CREATE DATABASE mydatabase;

-- 删除数据库
DROP DATABASE IF EXISTS mydatabase;

表

CREATE TABLE employees (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    age INT,
    department VARCHAR(50)
);

-- 查看所有表
\c dbname # 切换上下文数据库
\d
-- SELECT * FROM pg_tables WHERE schemaname = 'public';

-- 查看表结构
\d employees

-- 修改表结构
ALTER TABLE employees ADD COLUMN email VARCHAR(100); -- 新增列
ALTER TABLE employees RENAME COLUMN age TO age_in_years; -- 修改列名
ALTER TABLE employees DROP COLUMN email; -- 删除列
ALTER TABLE employees ALTER COLUMN age TYPE INT; -- 修改列数据类型
ALTER TABLE employees ALTER COLUMN age SET DEFAULT 18; -- 修改列默认值
ALTER TABLE employees ALTER COLUMN age DROP DEFAULT; -- 删除默认值
ALTER TABLE employees ALTER COLUMN age SET NOT NULL; -- 不为空
ALTER TABLE employees ALTER COLUMN age DROP NOT NULL; -- 可为空

-- 重命名表
ALTER TABLE employees RENAME TO new_employees;

-- 删除表
DROP TABLE IF EXISTS employees;

-- 删除表数据
TRUNCATE TABLE employees;

-- 创建索引
CREATE INDEX idx_employees_name ON employees (name);

-- 插入数据
INSERT INTO employees (name, age, department) VALUES ('John Doe', 30, 'Marketing');

-- 查询数据
SELECT * FROM employees;

-- 更新数据
UPDATE employees SET age = 31 WHERE name = 'John Doe';

-- 删除数据
DELETE FROM employees WHERE name = 'John Doe';

事务

BEGIN; -- 开始事务

-- 执行一些操作 ...
UPDATE employees SET age = 31 WHERE name = 'John Doe'; -- 更新第一条数据
SAVEPOINT my_savepoint;


COMMIT; -- 提交事务
ROLLBACK; -- 回滚事务

视图

CREATE VIEW marketing_employees AS
SELECT * FROM employees WHERE department = 'Marketing';

-- 查询视图
SELECT * FROM marketing_employees;

-- 删除视图
DROP VIEW IF EXISTS marketing_employees;

存储过程

CREATE OR REPLACE FUNCTION add_employee(name VARCHAR, age INT, department VARCHAR)
RETURNS VOID AS $$
BEGIN
    INSERT INTO employees (name, age, department) VALUES (name, age, department);
END;
$$ LANGUAGE plpgsql;

调用存储过程:

SELECT add_employee('David', 28, 'Sales');

备份

pg_dump mydatabase > mydatabase_backup.sql

恢复数据库

psql -d mydatabase mydatabase_backup.sql

参考

阿里云配置域名邮箱

Mon, 10 Feb 2025 00:00:00 GMT

当拥有自己的域名之后, 就可以使用 阿里邮箱(免费版) 配置自己的 域名邮箱 了, 例如域名是 example.com, 就可以创建例如 xxx@example.com 的邮箱, 并直接通过阿里邮箱进行邮件收发, 不需要自己搭建邮件系统

:::tip 通过服务器直接发送邮件可以参考通过服务器发送邮件 :::

1. 购买阿里邮箱(免费版)

进入阿里邮箱文档阿里邮箱 - 版本介绍
找到免费版, 点击 开通免费邮箱
在邮箱域名中选择已有域名, 输入自己的域名, 购买时长选择 5 年
点击立即购买(我这里已经购买过了)

2. 配置邮箱账号

进入阿里邮箱 - 开通指南文档页面
按照 一、设置邮箱管理员密码 先设置好邮箱密码, 这里可以看到 管理员账号 为 postmaster@example.com
按照 二、分配员工账号 操作, 进入阿里邮箱网页端并登录 管理员账号
参照文档创建新账号

3. 配置域名解析

直接参照四、添加解析进行操作, 如果是在阿里云购买的域名, 就可以直接一键添加邮箱解析, 配置好域名解析后可能需要等几分钟才会生效

:::warning 需要特别注意的是, 如果已经配置了根域名的解析(即主机记录为 @, 记录类型为 A 的解析规则), 在使用 一键添加邮箱解析 时可能会提示冲突(“A”记录和“CNAME”记录有冲突，请暂停或删除现有的“CNAME”记录后重试), 但其实解析规则已添加, 可以正常收发邮件, 详见解析记录冲突的解决办法 :::

4. 测试邮箱

当配置好域名解析后, 就可以使用自己创建的账号登录阿里邮箱网页端进行收发邮件了

4.1 配置邮件自动转发

如果你没有在手机上安装阿里邮箱 app, 可能不会及时收到邮件, 可以在邮箱中配置邮件转发, 将收到的邮件邮件转发到自己的常用邮箱上:

进入阿里邮箱网页端
点击 设置 - 查看更多设置 - 邮件设置 - 自动转发
点击 添加邮件转发地址 添加自己的常用邮箱
添加好后会收到一封 请验证自动转发的邮件地址 的邮件, 点击链接进行验证
验证成功后, 就可以 测试一下转发功能 了(test@test.com 向 admin@example.com 发送邮件, 将会转发到我的常用邮箱中)

然后再 测试一下发送功能(admin@example.com 向 test@test.com 发送邮件)

参考

systemctl 命令

Mon, 27 Jan 2025 00:00:00 GMT

1. `systemctl` 简介

在 Linux 系统中, systemctl 是一个强大的命令行工具, 用于管理和控制系统服务。它是 systemd 系统和服务管理器的一部分, 广泛应用于现代 Linux 发行版, 包括 Ubuntu。本文将详细介绍 systemctl 命令的使用, 并结合 apt 包管理器、Ubuntu 系统以及常见的服务器软件（如 nginx、MySQL 等）进行讲解。

1.1 基本语法

systemctl [选项] <命令> <服务名>

常用的命令包括：

start：启动服务
stop：停止服务
restart：重启服务
reload：重新加载服务的配置文件
enable：启用服务（开机自启）
disable：禁用服务（开机不自启）
status：查看服务状态
list-units：列出所有已加载的服务

2. 使用 `apt` 安装和管理服务

在 Ubuntu 系统中, apt 是默认的包管理工具, 用于安装、更新和删除软件包。我们可以使用 apt 来安装常见的服务器软件, 如 nginx、MySQL 等, 然后使用 systemctl 来管理这些服务。

2.1 安装 `nginx`

sudo apt update
sudo apt install nginx

安装完成后, nginx 服务会自动启动。我们可以使用 systemctl 来查看其状态：

sudo systemctl status nginx

输出示例：

● nginx.service - A high performance web server and a reverse proxy server
   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2023-10-10 12:34:56 UTC; 1min ago
     Docs: man:nginx(8)
 Main PID: 1234 (nginx)
    Tasks: 2 (limit: 1137)
   Memory: 4.0M
   CGroup: /system.slice/nginx.service
           ├─1234 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
           └─1235 nginx: worker process

2.2 安装 `MySQL`

sudo apt install mysql-server

安装完成后, MySQL 服务会自动启动。我们可以使用 systemctl 来管理它：

sudo systemctl status mysql

3. 管理服务

3.1 启动和停止服务

要启动 nginx 服务, 可以使用以下命令：

sudo systemctl start nginx

要停止服务, 可以使用：

sudo systemctl stop nginx

3.2 重启和重新加载服务

重启 nginx 服务：

sudo systemctl restart nginx

如果只是修改了配置文件, 可以使用 reload 命令重新加载配置而不中断服务：

sudo systemctl reload nginx

3.3 启用和禁用服务

启用 nginx 服务, 使其在系统启动时自动启动：

sudo systemctl enable nginx

禁用服务：

sudo systemctl disable nginx

3.4 查看服务状态

查看 nginx 服务的状态：

sudo systemctl status nginx

4. 其他常用命令

4.1 列出所有服务

列出所有已加载的服务：

systemctl list-units --type=service

4.2 查看服务的依赖关系

查看 nginx 服务的依赖关系：

systemctl list-dependencies nginx

4.3 查看服务的日志

查看 nginx 服务的日志：

journalctl -u nginx

5. 总结

systemctl 是 Linux 系统中管理服务的强大工具, 特别是在 Ubuntu 服务器环境中。通过结合 apt 包管理器, 我们可以轻松安装和管理常见的服务器软件, 如 nginx、MySQL 等。掌握 systemctl 的基本命令, 能够有效地管理服务器的服务, 确保系统的稳定运行。

无论是启动、停止、重启服务, 还是查看服务状态、启用开机自启, systemctl 都提供了简单而强大的功能。希望本文能够帮助你更好地理解和使用 systemctl, 提升你在 Linux 服务器管理中的效率。

Markdown Extended Features

Wed, 01 May 2024 00:00:00 GMT

GitHub Repository Cards

You can add dynamic cards that link to GitHub repositories, on page load, the repository information is pulled from the GitHub API.

::github{repo="Fabrizz/MMM-OnSpotify"}

Create a GitHub repository card with the code ::github{repo="<owner>/<repo>"}.

::github{repo="saicaca/fuwari"}

Admonitions

Following types of admonitions are supported: note tip important warning caution

:::note Highlights information that users should take into account, even when skimming. :::

:::tip Optional information to help a user be more successful. :::

:::important Crucial information necessary for users to succeed. :::

:::warning Critical content demanding immediate user attention due to potential risks. :::

:::caution Negative potential consequences of an action. :::

Basic Syntax

:::note
Highlights information that users should take into account, even when skimming.
:::

:::tip
Optional information to help a user be more successful.
:::

Custom Titles

The title of the admonition can be customized.

:::note[MY CUSTOM TITLE] This is a note with a custom title. :::

:::note[MY CUSTOM TITLE]
This is a note with a custom title.
:::

GitHub Syntax

[!TIP] The GitHub syntax is also supported.

> [!NOTE]
> The GitHub syntax is also supported.

> [!TIP]
> The GitHub syntax is also supported.

Spoiler

You can add spoilers to your text. The text also supports Markdown syntax.

The content :spoiler[is hidden ayyy]!

The content :spoiler[is hidden **ayyy**]!

Expressive Code Example

Wed, 10 Apr 2024 00:00:00 GMT

Here, we'll explore how code blocks look using Expressive Code. The provided examples are based on the official documentation, which you can refer to for further details.

Expressive Code

Syntax Highlighting

Regular syntax highlighting

console.log('This code is syntax highlighted!')

Rendering ANSI escape sequences

ANSI colors:
- Regular: [31mRed[0m [32mGreen[0m [33mYellow[0m [34mBlue[0m [35mMagenta[0m [36mCyan[0m
- Bold:    [1;31mRed[0m [1;32mGreen[0m [1;33mYellow[0m [1;34mBlue[0m [1;35mMagenta[0m [1;36mCyan[0m
- Dimmed:  [2;31mRed[0m [2;32mGreen[0m [2;33mYellow[0m [2;34mBlue[0m [2;35mMagenta[0m [2;36mCyan[0m

256 colors (showing colors 160-177):
[38;5;160m160 [38;5;161m161 [38;5;162m162 [38;5;163m163 [38;5;164m164 [38;5;165m165[0m
[38;5;166m166 [38;5;167m167 [38;5;168m168 [38;5;169m169 [38;5;170m170 [38;5;171m171[0m
[38;5;172m172 [38;5;173m173 [38;5;174m174 [38;5;175m175 [38;5;176m176 [38;5;177m177[0m

Full RGB colors:
[38;2;34;139;34mForestGreen - RGB(34, 139, 34)[0m

Text formatting: [1mBold[0m [2mDimmed[0m [3mItalic[0m [4mUnderline[0m

Editor & Terminal Frames

Code editor frames

console.log('Title attribute example')

<!-- src/content/index.html -->
<div>File name comment example</div>

Terminal frames

echo "This terminal frame has no title"

Write-Output "This one has a title!"

Overriding frame types

echo "Look ma, no frame!"

# Without overriding, this would be a terminal frame
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

Text & Line Markers

Marking full lines & line ranges

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

Selecting line marker types (mark, ins, del)

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

Adding labels to line markers

// labeled-line-markers.jsx
<button
  role="button"
  {...props}
  value={value}
  className={buttonClassName}
  disabled={disabled}
  active={active}
>
  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Adding long labels on their own lines

// labeled-line-markers.jsx
<button
  role="button"
  {...props}

  value={value}
  className={buttonClassName}

  disabled={disabled}
  active={active}
>

  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Using diff-like syntax

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+this is an actual diff file
-all contents will remain unmodified
 no whitespace will be removed either

Combining syntax highlighting with diff-like syntax

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

Marking individual text inside lines

function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported';
}

Regular expressions

console.log('The words yes and yep will be marked.')

Escaping forward slashes

echo "Test" > /home/test.txt

Selecting inline marker types (mark, ins, del)

function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}

Word Wrap

Configuring word wrap per block

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Configuring indentation of wrapped lines

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Collapsible Sections

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

Line Numbers

Displaying line numbers per block

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

Changing the starting line number

console.log('Greetings from line 5!')
console.log('I am on line 6')

Simple Guides for Fuwari

Mon, 01 Apr 2024 00:00:00 GMT

Cover image source: Source

This blog template is built with Astro. For the things that are not mentioned in this guide, you may find the answers in the Astro Docs.

Front-matter of Posts

---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg
tags: [Foo, Bar]
category: Front-end
draft: false
---

Attribute	Description
`title`	The title of the post.
`published`	The date the post was published.
`description`	A short description of the post. Displayed on index page.
`image`	The cover image path of the post.<br/>1. Start with `http://` or `https://`: Use web image<br/>2. Start with `/`: For image in `public` dir<br/>3. With none of the prefixes: Relative to the markdown file
`tags`	The tags of the post.
`category`	The category of the post.
`draft`	If this post is still a draft, which won't be displayed.

Where to Place the Post Files

Your post files should be placed in src/content/posts/ directory. You can also create sub-directories to better organize your posts and assets.

src/content/posts/
├── post-1.md
└── post-2/
    ├── cover.png
    └── index.md

Markdown Example

Sun, 01 Oct 2023 00:00:00 GMT

An h1 header

Paragraphs are separated by a blank line.

2nd paragraph. Italic, bold, and monospace. Itemized lists look like:

this one
that one
the other one

Note that --- not considering the asterisk --- the actual text content starts at 4-columns in.

Block quotes are written like so.

They can span multiple paragraphs, if you like.

Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all in chapters 12--14"). Three dots ... will be converted to an ellipsis. Unicode is supported. ☺

An h2 header

Here's a numbered list:

first item
second item
third item

Note again how the actual text starts at 4 columns in (4 characters from the left side). Here's a code sample:

# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }

As you probably guessed, indented 4 spaces. By the way, instead of indenting the block, you can use delimited blocks, if you like:

define foobar() {
    print "Welcome to flavor country!";
}

(which makes copying & pasting easier). You can optionally mark the delimited block for Pandoc to syntax highlight it:

import time
# Quick, count to ten!
for i in range(10):
    # (but not *too* quick)
    time.sleep(0.5)
    print i

An h3 header

Now a nested list:

First, get these ingredients:
- carrots
- celery
- lentils
Boil some water.

Dump everything in the pot and follow this algorithm:

 find wooden spoon
 uncover pot
 stir
 cover pot
 balance wooden spoon precariously on pot handle
 wait 10 minutes
 goto first step (or shut off burner when done)

Do not bump wooden spoon or it will fall.

Notice again how text always lines up on 4-space indents (including that last line which continues item 3 above).

Here's a link to a website, to a local doc, and to a section heading in the current doc. Here's a footnote [^1].

[^1]: Footnote text goes here.

Tables can look like this:

size material color

9 leather brown 10 hemp canvas natural 11 glass transparent

Table: Shoes, their sizes, and what they're made of

(The above is the caption for the table.) Pandoc also supports multi-line tables:

keyword text

red Sunsets, apples, and other red or reddish things.

green Leaves, grass, frogs and other things it's not easy being.

A horizontal rule follows.

Here's a definition list:

apples : Good for making applesauce. oranges : Citrus! tomatoes : There's no "e" in tomatoe.

Again, text is indented 4 spaces. (Put a blank line between each term/definition pair to spread things out more.)

Here's a "line block":

| Line one | Line too | Line tree

and images can be specified like so:

Inline math equations go in like so: $\omega = d\phi / dt$. Display math should get its own line and be put in in double-dollarsigns:

$$I = \int \rho R^{2} dV$$

$$ \begin{equation*} \pi =3.1415926535 ;8979323846;2643383279;5028841971;6939937510;5820974944 ;5923078164;0628620899;8628034825;3421170679;\ldots \end{equation*} $$

And note that you can backslash-escape any punctuation characters which you wish to be displayed literally, ex.: `foo`, *bar*, etc.

Include Video in the Posts

Tue, 01 Aug 2023 00:00:00 GMT

Just copy the embed code from YouTube or other platforms, and paste it in the markdown file.

---
title: Include Video in the Post
published: 2023-10-19
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube

Bilibili