Forem: lizhaopeng-cn

Claude Code 模型切换与 CCR 路由：踩坑全记录

lizhaopeng-cn — Tue, 28 Apr 2026 10:50:58 +0000

这篇是两个调试 session 的踩坑记录，讲清楚三件事：为什么 CCR 的 /model haiku 路由不生效、为什么走 OpenRouter 用 Claude 内置别名比三方 model ID 好、以及官方通道独有什么。

问题一：/model haiku 没走 ALIAS_MAP

现象：CCR 里配了 Haiku 路由规则，/model haiku 切换后却命中了 background 规则，实际跑的是 Sonnet 4.6。

排查过程

在 router.js 里看到的配置是：

"claude-haiku-4-5": "or,anthropic/claude-4.5-haiku-20251001",

而 Claude Code 实际发给 CCR 的 HTTP 请求里，body.model 的值是：

claude-haiku-4-5-20251001

多了 -20251001 日期后缀。ALIAS_MAP["claude-haiku-4-5-20251001"] → undefined → router 返回 null → 回落到默认规则。

CCR 内置了一条判断：haiku 主要是 Claude Code 的 background 任务模型，所以 fallback 路由命中的是：

"background": "or,anthropic/claude-4.6-sonnet-20260217"

最终用的是 Sonnet 4.6，不是 Haiku。

还有第二个 bug

即使 key 补全了，value 里也有问题：

"claude-haiku-4-5": "or,anthropic/claude-4.5-haiku-20251001"
//                                          ^^^
//                           模型名写成了 4.5，实际应为 4.5-haiku
//                           且这个 slug 不在 or.models 白名单里

OpenRouter 侧如果 model 不在白名单里会直接拒掉，所以 key 即使匹配上了也会报 404。

修法

ALIAS_MAP 里的 key 必须和 Claude Code 发出的 body.model 完全一致。先用日志拦一条请求确认真实值，再写配置，不要靠推测。Sonnet 和 Opus 同样要校验：

// 正确写法（以当前版本为例）
"claude-opus-4-7":           "or,anthropic/claude-4.7-opus-20260416",
"claude-sonnet-4-6":         "or,anthropic/claude-4.6-sonnet-20260217",
"claude-haiku-4-5-20251001": "or,anthropic/claude-haiku-4-5",

同时把 claude-haiku-4-5 加入 config.json 的 or.models 白名单，否则 OpenRouter 还是会拒。

问题二：直接 claude 启动为什么 /model 还能切换

这是另一个 session 里发现的事，起因是这个启动画面：

▐▛███▜▌   Claude Code v2.1.121
▝▜█████▛▘  Opus 4.7 · API Usage Billing
  ▘▘ ▝▝    /Users/xtuul

直接 claude 启动（不是 ccr code），执行 /model opus 后，下一条消息正常用了 Opus 4.7。"这不是应该没走 CCR 就无法路由吗？"

关键：ANTHROPIC_BASE_URL 指向 OpenRouter

~/.zshrc 里设了：

export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="sk-or-v1-..."
export ANTHROPIC_MODEL="anthropic/claude-4.7-opus-20260416"

Claude Code 直接读这三个变量，绕过 CCR 但不直连 api.anthropic.com，请求打到了 OpenRouter。

实际调用链：

你 → claude (v2.1.121)
       ① 读 ANTHROPIC_BASE_URL → https://openrouter.ai/api
       ② 读 ANTHROPIC_AUTH_TOKEN → Authorization: Bearer sk-or-v1-...
       ③ /model opus → 会话状态设为 opus，写 settings.json
       ④ 发请求时把 opus 展开为 claude-opus-4-7
     ↓
POST https://openrouter.ai/api/v1/messages
body: { "model": "claude-opus-4-7", ... }
     ↓
OpenRouter（实现了 Anthropic Messages API 协议）
     ↓
Anthropic 原厂 API

/model opus 只做两件事：改会话状态、持久化到 settings.json。endpoint 和 token 由环境变量决定，和 /model 无关。

OpenRouter 的 /v1/messages 端点跟 Anthropic 协议兼容，所以 Claude Code 完全意识不到中间多了一跳。

CCR vs 直挂 OpenRouter 的区别

场景	路径	CCR 参与
`ccr code` 启动	claude → 127.0.0.1:3456 (CCR) → openrouter/其他	✅
直接 `claude` 启动（有 ANTHROPIC_BASE_URL）	claude → openrouter.ai 直连	❌

CCR 只在你需要更复杂的路由时才必要：多 provider 别名切换、按 model 改写请求体、剥 Claude 专属字段给其他厂商等。对"我就是要用 Anthropic 模型"这种场景，环境变量直挂就够。

问题三：内置别名 vs 三方 model ID 差在哪里

同一次 session 里做了一个实验，贴出两次 /context 的输出：

用 ANTHROPIC_MODEL=anthropic/claude-4.7-opus-20260416 时：

⛁ ⛁ ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   anthropic/claude-4.7-opus-20260416
                           39.6k/200k tokens (20%)

切换 /model opus 之后：

⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛀ ⛁ ⛁ ⛁ ⛁ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   Opus 4.7
                                                   claude-opus-4-7
                                                   63.6k/1m tokens (6%)

同一个 Opus 4.7，上下文窗口差了 5 倍（200k vs 1M）。

为什么会这样

Claude Code 二进制里硬编码了一张 model 能力表，从 binary strings 里能找到：

model="claude-opus-4-7"
model="claude-sonnet-4-6"
model="claude-haiku-4-5"
// 以及 if(H!=="claude-opus-4-7") 这类硬编码分支判断

只有这三个裸 ID（不带厂商前缀，不带日期后缀）命中这张表。命中了，Claude Code 才会：

带上 anthropic-beta: context-1m-... header（解锁 1M context）
发送 thinking: { type: "enabled", budget_tokens: ... } 参数（开启 extended thinking）
查表设对 max_tokens 上限（opus 32k / sonnet 8k / haiku 8k）
按模型单价算 cache 定价，/cost 才能显示准确

遇到 anthropic/claude-4.7-opus-20260416 这种带前缀带后缀的 ID，表里查不到，全部按保守值处理。

/model 切换的优先级

启动时：读 ANTHROPIC_MODEL 作为初始值，原样进入会话状态，不做 allowlist 校验
执行 /model opus 后：覆盖会话状态，写 settings.json，后续请求发 claude-opus-4-7
此时 ANTHROPIC_MODEL 完全被忽略

两种 ID OpenRouter 都能接（它对裸 claude id 会自动补 anthropic/ 前缀），但 Claude Code 侧的能力开关只认裸 ID。

如果把 ANTHROPIC_MODEL 换成非 Claude 模型

比如 openai/gpt-5.4-20260305 或 qwen/qwen3.6-plus-04-02：

启动时能用，但有几个硬伤：

问题	原因
`/model opus` 一按，立刻切回 Claude	硬编码别名表里只有 Claude
Prompt caching 不生效	`cache_control` 字段 GPT/Qwen 不认，直接丢弃
Extended thinking 参数丢失	只有 Claude 4.x 支持，转发给别家时被过滤掉
Tool use 结构错乱	Anthropic 的 `tool_use/tool_result` block 翻译成 OpenAI `tool_calls` 时会丢 `id` 关联
系统 prompt 错乱	CC 的 system prompt 是为 Claude 写的（"你是 Anthropic 的 CLI"等），GPT/Qwen 读到会输出奇怪内容

这恰好解释了 CCR 存在的价值：CCR 是专门处理这些场景的中间层：

claude（只会发 claude-opus-4-7）
  ↓
CCR :3456
  ↓  ① 改写 model: claude-opus-4-7 → openai/gpt-5.4-...
     ② 剥掉 cache_control / thinking 字段，不让它们透传给不认识的 provider
     ③ 支持 glm: / qwen: 前缀做会话内一次性切换
     ④ 注册自定义别名表，/model <alias> 可以映射到任意 provider
  ↓
OpenRouter / 其他厂商

跨 Provider 切换的隐形地雷：thinking block 签名污染

在同一个 session 里，把 ANTHROPIC_MODEL 换成 DeepSeek 试了一次，随后切回 Claude，报了这个错：

messages.11.content.0: Invalid `signature` in `thinking` block
provider_name: Anthropic

而且同一条 messages.11 被所有后续请求反复报错：

req_011CaVYB... messages.11.content.0
req_011CaVYD... messages.11.content.0
req_011CaVYJ... messages.11.content.0
req_011CaVYK... messages.11.content.0

机制

Claude 4.x 在开启 extended thinking 时，响应里会有：

{
  "type": "thinking",
  "thinking": "...思考摘要...",
  "signature": "abc123...HMAC签名"
}

signature 是 Anthropic 服务端用私钥签发的 HMAC。多轮对话时，客户端必须把历史里的 thinking block 原样（含 signature）回传，Anthropic 后端会验签。

切到 DeepSeek 时发生了什么：

Claude Code 把带 thinking block 的历史原样打包，POST 给 OpenRouter，目标改成 deepseek/deepseek-v3.2-...
OpenRouter 翻译成 DeepSeek API 格式，调 DeepSeek，得到响应
OpenRouter 把 DeepSeek 的响应翻译回 Anthropic 格式，伪造了一个 thinking block（塞了个占位 signature）
Claude Code 把这个"伪 thinking block"写进会话 history

切回 Claude 时： 包含伪 thinking block 的完整 history POST 到 Anthropic 原厂 → 验签失败 → 400。

Qwen 能继续用，因为 Qwen 后端不在乎 signature，OpenRouter 转过去时直接把 thinking block 丢掉。但只要目标是 Anthropic 原厂，messages.11 那个坏掉的 block 就会一直触发同一个错误。

修复

只能清掉那条消息才能恢复：

# 在 Claude Code 里执行
/clear

清完历史之后切回 /model opus 就正常了。

为什么 CCR 不会出现这个 bug

CCR 的 transformer 出站前会扫描 history，根据目标 provider 决定保留还是剥离 thinking block：

// CCR 伪代码
if (targetProvider !== 'anthropic') {
    stripThinkingBlocks(messages);
} else {
    stripForeignThinkingBlocks(messages); // 目标是 Claude 但历史里有外来 block，也剥掉
}

直挂环境变量走 OpenRouter 没有这层保护，Claude Code 发什么 OpenRouter 就原样转什么。

官方独有功能清单

这部分是 session 里顺带搜出来的，列几个有硬证据的。

Auto 模式（任务复杂度自动切换 Opus/Sonnet/Haiku）

需要 Max 订阅 + /login 登录 + 环境里没有 ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN
是 Anthropic 服务端 feature flag 控制的订阅特性，按账号灰度放开
GitHub issue #46616 里明确写了触发条件：一旦检测到 API key 类环境变量，Auto 模式直接禁用

只要你用了 OpenRouter（需要设 ANTHROPIC_AUTH_TOKEN），Auto 模式就永远用不了。

Prompt Caching 命中率

多个独立报告显示，走 OpenRouter 的 Claude 请求，prompt cache 效果明显不如直连：

opencode #1245：OpenRouter 下 cache 只对 system message 生效
Zed #52576：native_tokens_cached 始终是 0，形同关闭
SillyTavern 讨论：1 小时 TTL 在 OpenRouter 任何 Anthropic provider 下都不工作
ai-sdk-provider #35：prompt caching 完全没命中，长期未修

1M Context 的计费入口

OpenRouter 路径下，即使你用了内置别名解锁了 1M context，如果 Anthropic 侧需要额外收费，报错如下：

API Error: Extra usage is required for 1M context
run /extra-usage to enable, or /model to switch to standard context

/extra-usage 这个命令在官方订阅通道才有对应入口，OpenRouter 路径没有。

其他官方独占

能力	官方现状	三方现状
Auto 模式	Max 订阅 + Opus 4.7	无
2026-04-04 起 Pro/Max 订阅额度	官方独用	第三方 harness 不能消耗订阅 quota
Extended thinking 签名完整性	原生签发+验签	跨 provider 切换会污染 history
`/fast` 的 Opus 4.6 Fast 变体	有	OpenRouter 的 model 列表里没有这个变体
Files API / Code Execution	官方 beta endpoint	OpenRouter 不转发非 `/v1/messages` endpoint
Managed Agents / Remote Trigger	官方 API	无
Claude Code 的 session 同步	CLI/桌面/Web 互通	只能本地 CLI
新模型首发	发布当天可用	通常延迟几小时到几天

另一个硬事实：2026-04-04 Anthropic 封锁了第三方 agentic 工具消耗 Pro/Max 订阅 quota，原话是"usage will be billed to your API account"。加上 Claude Code 本身在 2026-04-21 从 Pro 计划里被移除（仅 Max 5x+ 保留），订阅价值已经集中在 Max 路径。

小结

三件事的结论：

CCR ALIAS_MAP：key 必须与 Claude Code 发出的 body.model 完全一致，带日期后缀。先抓一条请求日志确认真实值，再写配置。
内置别名 vs 三方 ID：走 OpenRouter 时，用 /model opus 而不是 ANTHROPIC_MODEL=anthropic/claude-4.7-opus-20260416，能多拿到 1M context、extended thinking 参数、正确的 max_tokens 和 cache 定价，差距显著。
跨 provider 混用会话：遇到 thinking block 就是定时炸弹。直挂 OpenRouter 没有 CCR 那层 transformer 保护，切到非 Anthropic provider 再切回来，只能 /clear 重来。

把 Claude Code 搬进飞书和 Telegram：cc-connect + CCR 完整架构、安装流程与踩坑全记录

lizhaopeng-cn — Tue, 28 Apr 2026 09:04:04 +0000

本篇讲什么：一套让你在手机上用 Claude Code 的工程化方案——IM（飞书 / Telegram）⇄ cc-connect ⇄ Claude Code ⇄ CCR ⇄ OpenRouter ⇄ 多家大模型。含语音转写（Groq Whisper）、MCP（Stitch）、launchd 守护、模型按需切换，外加 13 个一路踩过的坑。

本篇不讲什么：Claude Code 本身怎么用、OpenRouter 怎么注册、飞书/Telegram 是什么。默认你已经跑过 claude 桌面端，有 OpenRouter 账号，对命令行不陌生。

一、为什么要做这套东西

日常写代码离不开 Claude Code，但桌面端有个硬伤：

开会 / 出门 / 蹲厕所 的时候脑子里冒出改一行代码的想法，没电脑在旁边就凉了
想让它后台跑一个重构 / 搜资料任务，也不方便时不时回电脑前看进度
偶尔一条语音表达比打字快得多，Claude Code 桌面端不吃语音

目标： 手机上通过飞书 / Telegram 直接和 Claude Code 对话，可发文字、发语音、切模型、恢复之前的 session、用 MCP 工具。电脑端和手机端最好能看到同一批 session。

用到的组件：

组件	作用
`cc-connect`	IM 桥接器，把飞书/Telegram 消息转成 Claude Code 的输入
`claude-code-router` (CCR)	本地反向代理，把 Claude Code 的请求路由到 OpenRouter / 其他厂商，支持按 alias 切模型
OpenRouter	聚合多家模型（Anthropic / OpenAI / Google / Qwen ...），一个 key 搞定
ffmpeg + Groq Whisper	把飞书/Telegram 的语音消息转成文字
launchd	macOS 上把 cc-connect 做成开机自启的守护进程

二、整体架构

┌────────────────┐         ┌────────────────┐
│   飞书客户端   │         │ Telegram 客户端 │
└────────┬───────┘         └────────┬───────┘
         │  消息 / 语音               │
         ▼                            ▼
         ┌───────────────────────────────┐
         │    cc-connect (launchd daemon)│   ← 监听两个平台，做消息协议转换
         │                               │
         │   ┌───────────────────────┐   │
         │   │ Groq Whisper (语音转) │   │
         │   └───────────────────────┘   │
         └──────────────┬────────────────┘
                        │  fork 子进程
                        ▼
           ┌────────────────────────────┐
           │  claude (Claude Code CLI)  │
           │                            │
           │   ANTHROPIC_BASE_URL=      │
           │     http://127.0.0.1:3456  │
           │   ANTHROPIC_API_KEY=dummy  │
           └──────────────┬─────────────┘
                          │  Anthropic 协议
                          ▼
           ┌────────────────────────────┐
           │   CCR (claude-code-router) │
           │   127.0.0.1:3456           │
           │                            │
           │   router.js:               │
           │   - /model <alias>         │
           │   - "alias:" 前缀          │
           │   - longContextThreshold   │
           │   - default Router         │
           └──────────────┬─────────────┘
                          │  各家原生协议
                          ▼
           ┌────────────────────────────────┐
           │  OpenRouter / 其他 provider    │
           │  anthropic/claude-4.7-opus     │
           │  anthropic/claude-4.6-sonnet   │
           │  anthropic/claude-4.5-haiku    │
           │  openai/gpt-5.4                │
           │  openai/gpt-5.3-codex          │
           │  google/gemini-3.1-pro         │
           │  qwen/qwen3.6-plus             │
           │  ...:free 系列用另一个 key     │
           └────────────────────────────────┘

几个关键的数据流：

文字消息：IM → cc-connect → claude 子进程 (stdin) → CCR → OpenRouter → 回流
语音消息：IM → cc-connect 下载 ogg/mp3 → ffmpeg 转码 → Groq Whisper → 文本 → 当作文字消息走
MCP 工具：claude 子进程按需 HTTP 调用 https://stitch.googleapis.com/mcp（header 里带 key）
session 持久化：每轮对话的 jsonl 存在 ~/.claude/projects/-Users-xtuul/，和桌面端 ccr code 共用一个目录

三、安装流程（macOS，一步步来）

假设你已经装过 Node.js（推荐 22.x，用 nvm 管理）、Claude Code CLI、以及有一个 OpenRouter 账号。

3.1 装 CCR（claude-code-router）

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

配置文件在 ~/.claude-code-router/：

config.json — Providers 列表、Router 规则、APIKEY 等
router.js — 自定义路由脚本（可选，但强烈推荐）

config.json 示例（我本机跑着的就是这套，两个账号：or 是付费主账号，or1 跑免费模型）：

{
  "LOG": true,
  "HOST": "127.0.0.1",
  "PORT": 3456,
  "APIKEY": "",
  "API_TIMEOUT_MS": "600000",
  "Providers": [
    {
      "name": "or",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-or-v1-...主 key...",
      "models": [
        "anthropic/claude-4.7-opus-20260416",
        "anthropic/claude-4.6-sonnet-20260217",
        "anthropic/claude-4.5-haiku-20251001",
        "openai/gpt-5.4-20260305",
        "openai/gpt-5.3-codex-20260224",
        "google/gemini-3.1-pro-preview-20260219",
        "qwen/qwen3.6-plus-04-02"
      ],
      "transformer": { "use": ["openrouter"] }
    },
    {
      "name": "or1",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-or-v1-...备用 key 跑免费模型...",
      "models": [
        "openrouter/free",
        "nvidia/nemotron-3-super-120b-a12b:free"
      ],
      "transformer": { "use": ["openrouter"] }
    }
  ],
  "Router": {
    "default":       "or,anthropic/claude-4.7-opus-20260416",
    "background":    "or,anthropic/claude-4.6-sonnet-20260217",
    "think":         "or,anthropic/claude-4.7-opus-20260416",
    "longContext":   "or,anthropic/claude-4.7-opus-20260416",
    "longContextThreshold": 180000,
    "webSearch":     "",
    "image":         "or,openai/gpt-5.4-20260305"
  },
  "CUSTOM_ROUTER_PATH": "/Users/你/.claude-code-router/router.js"
}

几个注意点：

provider name 就是 Router 值里 , 前面那一段。我习惯用短名（or / or1），你叫 openrouter / openrouter-free 都行，只要 Router / router.js 里两边对得上
transformer: { use: ["openrouter"] } 是 CCR 让 OpenRouter 协议生效的开关。不加这行，部分字段（比如 reasoning content、工具调用 schema）会发错格式给上游
longContextThreshold 我拉到 180000：2026 年的模型上下文基本都是 200k+ / 1M，没必要 120k 就切模型
webSearch: "" 是显式置空 —— 我不用 CCR 的 webSearch 路由，Claude Code 自己的 WebFetch 更好用

几个重要的 Router 字段含义

字段	语义
`default`	兜底模型。其他路由规则都没命中时用这个
`background`	后台压缩/总结用的轻量模型。一般比 default 便宜/快
`think`	带 extended thinking 的长链路推理模型
`longContext`	单次请求 input tokens ≥ longContextThreshold 时切到这个模型。注意：是单次请求的 input tokens，不是整个上下文窗口，而且是无状态的 —— 这次超了走这个，下次没超还是走 default
`webSearch`	带 web 搜索能力的模型（Gemini 系列通常最强）
`image`	发送图片时用的 vision 模型（要选分析模型，不是生成模型）

`router.js`（自定义路由，强烈推荐）

这个脚本给你两个人工切模型的方式：

模式 A — 持久切换：在 claude 聊天里输 /model <alias>，整个 session 都用这个 alias

模式 B — 一次性切换：消息以 alias: 开头，只这条走 alias，之后自动回退

const ALIAS_MAP = {
  // ── or（主账号 / 付费模型）
  // ⚠️ Anthropic 系列的 key 必须用"带日期后缀的完整 ID"，原因见下文
  "claude-opus-4-7":           "or,anthropic/claude-4.7-opus-20260416",
  "claude-sonnet-4-6":         "or,anthropic/claude-4.6-sonnet-20260217",
  "claude-haiku-4-5-20251001": "or,anthropic/claude-4.5-haiku-20251001",
  // ── 其他家的模型，alias 短名就行
  "gpt":    "or,openai/gpt-5.4-20260305",
  "codex":  "or,openai/gpt-5.3-codex-20260224",
  "gemini": "or,google/gemini-3.1-pro-preview-20260219",
  "qwen":   "or,qwen/qwen3.6-plus-04-02",
  // ── or1（免费账号 / 免费模型）
  "free":   "or1,openrouter/free",
  "nvidia": "or1,nvidia/nemotron-3-super-120b-a12b:free",
};

const PREFIX_RE = /^([a-zA-Z][a-zA-Z0-9_-]*):(\s|$)/;

function matchPrefix(text) {
  if (typeof text !== "string") return null;
  const m = text.match(PREFIX_RE);
  if (!m) return null;
  const alias = m[1].toLowerCase();
  const route = ALIAS_MAP[alias];
  if (!route) return null;
  return { alias, route, stripped: text.slice(m[0].length).trimStart() };
}

module.exports = async function router(req, config) {
  // 模式 A：body.model 是裸 alias（来自 /model <alias>）
  const rawModel = req?.body?.model;
  if (typeof rawModel === "string" && !rawModel.includes(",")) {
    const key = rawModel.toLowerCase();
    if (ALIAS_MAP[key]) return ALIAS_MAP[key];
  }

  // 模式 B：最后一条 user 消息以 "alias:" 开头
  const messages = req?.body?.messages;
  if (!Array.isArray(messages) || messages.length === 0) return null;

  let lastUser = null;
  for (let i = messages.length - 1; i >= 0; i--) {
    if (messages[i]?.role === "user") { lastUser = messages[i]; break; }
  }
  if (!lastUser) return null;

  if (typeof lastUser.content === "string") {
    const hit = matchPrefix(lastUser.content);
    if (!hit) return null;
    lastUser.content = hit.stripped;
    return hit.route;
  }

  if (Array.isArray(lastUser.content)) {
    // Claude Code 会注入 <system-reminder> 等前置 text block，真实输入常在后面
    for (const block of lastUser.content) {
      if (!block || typeof block !== "object" || block.type !== "text") continue;
      const hit = matchPrefix(block.text);
      if (!hit) continue;
      block.text = hit.stripped;
      return hit.route;
    }
  }

  return null;  // 都不匹配，回落 Router 默认规则
};

为什么 Anthropic 模型的 key 必须写完整 ID

这是个很隐蔽的坑。

Claude Code 客户端本身对 Anthropic 自家模型名做了硬编码处理，和对第三方模型的处理完全不一样：

/model gpt（第三方）→ body.model 原样发 "gpt"
/model opus（Anthropic 自家）→ 从二进制硬编码表里查到 opus → claude-opus-4-7，body.model 发 claude-opus-4-7（Claude Code 内部只认这三个裸 ID：claude-opus-4-7 / claude-sonnet-4-6 / claude-haiku-4-5-20251001）

所以如果你 ALIAS_MAP 里写的是 "opus": "..."，CCR 收到的 body.model 其实是 claude-opus-4-7——查不到，返回 null，回落到 config.json 的默认 Router。

更坑的是：Anthropic 家 haiku/sonnet/opus 的短 ID 回落时，CCR 往往会把它归为"后台/轻量任务"，命中 Router.background。结果你 /model haiku 实际跑的是 Router.background 里配的那个模型（我的是 Sonnet）。第一次看到"怎么切了还是不对"的时候很难想到是键名对不上。

顺便省一次切换：启动直连 OpenRouter 也能复用这套映射

我 .zshrc 里配了：

export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="sk-or-v1-..."
export ANTHROPIC_MODEL="anthropic/claude-4.7-opus-20260416"

这样直接敲 claude（不走 CCR）时，Claude Code 把 ANTHROPIC_MODEL 原样写进 body.model，请求直发 OpenRouter。但 body.model 是 anthropic/claude-4.7-opus-20260416 这个完整字符串，不是 claude-opus-4-7。

然后我也走 CCR 的场景（cc alias = ccr code），启动时 body.model 又会变成 claude-opus-4-7（Claude Code 内部从 ANTHROPIC_MODEL 推断别名再展开）——两套字符串都可能出现在 body.model 里。

所以 ALIAS_MAP 最干净的做法是把两种形态的 key 都列进去：

const ALIAS_MAP = {
  // /model opus 切换后 Claude Code 会展开成这个裸 ID
  "claude-opus-4-7":           "or,anthropic/claude-4.7-opus-20260416",
  "claude-sonnet-4-6":         "or,anthropic/claude-4.6-sonnet-20260217",
  "claude-haiku-4-5-20251001": "or,anthropic/claude-4.5-haiku-20251001",
  // 其他家短名就行
  "gpt": "or,openai/gpt-5.4-20260305",
  // ...
};

这样启动 claude 就是 Opus，/model sonnet 切过去也是 Sonnet，/model haiku 是 Haiku。不需要启动一次再切一次。

验证 CCR 跑起来：

ccr start                # 前台起
# 或者
ccr code                 # 用 CCR 作为后端启动 claude

ccr code 能跑通就说明 CCR → OpenRouter 的链路是通的。

3.2 装 cc-connect

npm i -g cc-connect

配置目录 ~/.cc-connect/，核心是 config.toml：

data_dir = ""
language = "en"

[[projects]]
  name = "my-project"

  [projects.agent]
    type = "claudecode"
    [projects.agent.options]
      mode = "default"
      work_dir = "/Users/你"              # 和桌面端 ccr code 的 cwd 对齐，后面讲为什么
      router_url = "http://127.0.0.1:3456"  # 指向 CCR
      router_api_key = "dummy"              # ⚠️ 不能留空！后面讲为什么

  # ── 飞书
  [[projects.platforms]]
    type = "feishu"
    [projects.platforms.options]
      app_id = "cli_xxx"
      app_secret = "xxx"

  # ── Telegram
  [[projects.platforms]]
    type = "telegram"
    [projects.platforms.options]
      token = "xxx:yyy"           # @BotFather 建 bot 给你的
      allow_from = "你的TG数字ID" # 或 "*" 允许所有人，建议先宽后紧

[log]
  level = "info"

[speech]
  enabled = true
  provider = "groq"
  language = "zh"
  [speech.groq]
    api_key = "gsk_..."
    model = "whisper-large-v3"

飞书 app_id / app_secret 怎么拿

去飞书开放平台创建「企业自建应用」
开启「机器人」能力
权限里勾上「以应用身份发消息」、「读取用户发给机器人的消息」、「获取群组信息」等
事件订阅必须切到「长连接模式」（cc-connect 用的就是 WebSocket），HTTP 回调模式会连不上
把应用发布到版本，企业管理员通过
凭据与基础信息页找 App ID / App Secret

Telegram token 怎么拿

在 Telegram 找 @BotFather
/newbot → 起个名字 → 起个 username（必须 _bot 结尾）
BotFather 返回 xxx:yyy 格式的 token，就是 token 字段填的值
先填 allow_from = "*" 跑通后，看 cc-connect 日志里的 telegram: message from unauthorized user <数字>，那个数字就是你的 TG user ID，再改回 "你的数字ID" 收紧权限

验证前台跑通

cd ~/.cc-connect
cc-connect

两个平台都 platform started 就说明连上了。手机上发条消息试试。

3.3 装 ffmpeg（语音必需）

brew install ffmpeg

踩坑：[speech] enabled = true 配了也没用，cc-connect 需要 ffmpeg 把飞书/Telegram 发过来的 ogg/oga 转成 Groq 认的格式。报错长这样：

Voice message requires ffmpeg for format conversion. Please install ffmpeg.

装完之后不用重启 cc-connect，下次收到语音就能转了（cc-connect 是 exec 调用 ffmpeg 的，PATH 里能找到就行）。

Groq Whisper API key 怎么拿

console.groq.com 注册
API Keys 页新建 key，gsk_... 开头
免费额度足够日常用，模型用 whisper-large-v3 中文识别效果不错

3.4 改成 launchd 守护进程（开机自启）

前面是前台跑，关终端就挂了。正式用要装成守护：

cd ~/.cc-connect          # ⚠️ 必须在含 config.toml 的目录下跑，不能用 --config 参数
cc-connect daemon install

成功后：

cc-connect daemon status   # 查状态
cc-connect daemon logs -f  # 流式看日志
cc-connect daemon restart  # 改完 config.toml 后必须 restart 才生效
cc-connect daemon stop     # 停
cc-connect daemon uninstall # 卸载守护

daemon restart 会给主进程发 SIGTERM，cc-connect 自己会清理它 fork 的 claude 子进程，不用手动杀。

四、日常使用

4.1 切模型

持久切换（桌面 / 手机都能用）：

/model opus      # 切 Claude Opus
/model gpt       # 切 GPT-5.4
/model gemini    # 切 Gemini 3.1 Pro
/model free      # 切免费模型

一次性切换（只这条走新模型）：

gpt: 写个 Python 快排
gemini: 帮我 Google 一下最新的 React 19 文档
free: 随便聊聊天

4.2 cc-connect 内置命令

命令	作用
`/list`	列出当前 project 下所有 session
`/switch <N\	uuid前缀\
{% raw %}`/new`	开一个全新的 session
`/reset`	重置当前 session
`/help`	列出所有 bot 命令

注意：/resume 是 Claude Code 内置命令，在 cc-connect 里会被转发给 claude，但 claude 的 resume picker 是交互式的，IM 里用不了。cc-connect 用的是 /switch。

4.3 桌面端看手机 session（需要同 work_dir）

config.toml 里 work_dir = "/Users/你"，和桌面端 ccr code 默认在 home 目录跑对齐后，两边会共用 ~/.claude/projects/-Users-xtuul/ 下的 jsonl。

但有个限制：桌面端 /resume 的 picker 看不到 cc-connect 起的 session，因为 cc-connect 写的 jsonl 缺了几个字段（permission-mode / file-history-snapshot / last-prompt），picker 会过滤掉。

曲线方案：用 UUID 直接 resume

# 找最新的手机 session
ls -lt ~/.claude/projects/-Users-xtuul/*.jsonl | head -5

# 拿到文件名里的 UUID 前缀
ccr code --resume <uuid-prefix>

如果你常 resume，包两个 shell 函数（列最近 session、按 UUID 前缀 resume）会更丝滑，但不是刚需——靠肉眼挑最新那个 jsonl 文件 → ccr code --resume <前 8 位> 也能用。这块我自己还没打磨到想写进 .zshrc 的程度，以后单独写一篇。

4.4 桌面启动 alias

# ── 常用：直接启动（权限全放行，适合完全信任的环境）
alias cc='ccr code --allow-dangerously-skip-permissions'

# ── 启动时直接指定模型（省一次 /model 切换）
alias cc-opus='ccr code --allow-dangerously-skip-permissions --model claude-opus-4-7'
alias cc-sonnet='ccr code --allow-dangerously-skip-permissions --model claude-sonnet-4-6'
alias cc-haiku='ccr code --allow-dangerously-skip-permissions --model claude-haiku-4-5-20251001'
alias cc-gpt='ccr code --allow-dangerously-skip-permissions --model gpt'
alias cc-codex='ccr code --allow-dangerously-skip-permissions --model codex'
alias cc-gemini='ccr code --allow-dangerously-skip-permissions --model gemini'
alias cc-qwen='ccr code --allow-dangerously-skip-permissions --model qwen'
alias cc-free='ccr code --allow-dangerously-skip-permissions --model free'
alias cc-nvidia='ccr code --allow-dangerously-skip-permissions --model nvidia'

# ── 重启守护 / 路由
alias ccc-restart='cc-connect daemon restart'
alias ccr-restart='ccr restart'

--model <alias> 传的就是 ALIAS_MAP 的键——Anthropic 系列要用完整 ID（claude-opus-4-7 这种），其他家用短名（gpt / gemini 等）。这样敲 cc-opus 启动直接就是 Opus 4.7，省一次 /model 切换。

五、踩坑全记录

按被坑顺序排。

坑 1：`gpt is not a valid model ID`

现象：在 claude 里 /model gpt，回 Model may not exist。

原因：cc-connect 没把请求转到 CCR，直接原样发给 Anthropic API，Anthropic 当然不认识 gpt 这个模型。

根因：config.toml 没配 router_url。

修复：

[projects.agent.options]
  router_url = "http://127.0.0.1:3456"

cc-connect 会自动给 claude 子进程设 ANTHROPIC_BASE_URL=<router_url> 和 NO_PROXY=127.0.0.1。

坑 2：`/login is not a cc-connect command` / `/login isn't available in this environment`

现象：手机发消息，bot 回「Not logged in · Please run /login」；发 /login 又回「isn't available」。

原因：claude 子进程启动时发现没 ANTHROPIC_API_KEY，进了登录流程。/login 是交互式命令，IM 里跑不了。

根因：config.toml 里 router_api_key 留空了（或注释掉了）。

关键点：router_api_key 有双重作用：

如果 CCR 开了 APIKEY 校验，这个值要对上
cc-connect 会把它当作 ANTHROPIC_API_KEY 注入给 claude 子进程 —— 空值时就不注入 → claude 找不到 key → 弹登录

修复：哪怕 CCR 没开校验，也要填个 dummy：

router_api_key = "dummy"

坑 3：`Voice message requires ffmpeg for format conversion`

现象：发语音消息，bot 回 ffmpeg 报错。

原因：[speech] enabled = true 只是打开语音识别的开关，转码还是要本地的 ffmpeg。

修复：brew install ffmpeg。

坑 4：`config.toml not found in /Users/xtuul`

现象：cc-connect daemon install 在任意目录跑，报 config 找不到。

原因：daemon install 固定从 CWD 找 config.toml，不是从 ~/.cc-connect/。

修复：

cd ~/.cc-connect && cc-connect daemon install

不要用 cc-connect --config ~/.cc-connect/config.toml daemon install—— --config 参数会让它直接切成前台运行模式，不会安装守护。

坑 5：`cc-connect deamon restart`（打错字）→ Telegram getUpdates 冲突

现象：deamon（少一个 a），执行后终端开始刷日志：

Conflict: terminated by other getUpdates request
Failed to get updates, retrying in 3 seconds...

原因：cc-connect 不认识 deamon 这个子命令，静默回落到前台运行。这时：

launchd 管的 daemon     ← 在连 Telegram
         +
你前台新起的 cc-connect ← 也在连 Telegram
         ↓
    两个都 getUpdates，Telegram API 只允许一个长轮询

修复：

Ctrl+C 掐掉前台的
cc-connect daemon status 确认 daemon 还在
正确拼写 cc-connect daemon restart

坑 6：`launchctl bootstrap failed: 5: Input/output error`

现象：cc-connect daemon restart 报这个。

原因：launchd 的老毛病，有时候 bootstrap/bootout 之间的状态不同步。

修复：拆成两步

cc-connect daemon stop
sleep 2
cc-connect daemon start

坑 7：daemon 模式下环境变量不生效（MCP / API key）

现象：.zshrc 里 export FOO_API_KEY=...，桌面端能用，daemon 跑的 cc-connect 里调 MCP 或用这个 key 的 subagent 就 401。

原因：Unix 进程环境变量的继承链：

shell (读 .zshrc) → 你手动启动的程序       ✅ 拿得到
launchd (不读任何 shell 配置) → daemon      ❌ 拿不到

launchd 启动的守护进程环境是空的（只有 HOME、PATH 等几个基础变量）。.zshrc / .bashrc / .profile 它统统不读。

修复（三选一）：

方案	优点	缺点
直接写死在 `~/.claude.json` 的 MCP `headers` / `env` 里	最简单，key 跟着配置走	明文存文件里
`launchctl setenv FOO_API_KEY ...`	不用改配置	污染全局 launchd，机器重启失效
用前台模式跑 cc-connect	env 继承最干净	关终端就挂，要自己做 tmux/screen

我自己选方案 1，~/.claude.json 里 MCP 的 key 直接写死。权限范围窄的 key（比如某个 MCP 专用的 API key）blast radius 有限，明文在本地 .json 可以接受。

坑 8：`/resume` picker 看不到 cc-connect 起的 session

现象：桌面端 ccr code 然后 /resume，picker 显示 No conversations found，即便 cc-connect 在同一个 work_dir 下已经写了几十条 jsonl。

原因：Claude Code 的 resume picker 会过滤 jsonl，要求有 permission-mode / file-history-snapshot / last-prompt 这几个 marker 字段。cc-connect 写的 jsonl 没这些字段（因为它走的是 stdin/stdout 协议，不是 TUI 启动路径）。

协议不对称：cc-connect 的 session 桌面端能读（ccr code --resume <uuid> 直接用 UUID 指定就行），但不能列在 picker 里。

绕路方案：

ccr code --resume <uuid> 直接指定 UUID（见 §4.3 的 ccrr 函数）
或者在手机 cc-connect 里用 /list + /switch 切

坑 9：`/switch` 还是 `/resume`？

cc-connect 用的是 /switch。

/resume 会被转发给 claude，但 claude 的 resume 是 TUI 交互（弹选择器），在 IM 里跑不了。

/list              ← 列 session
/switch 3          ← 按列表序号切
/switch e255dc42   ← 按 UUID 前缀切
/switch 工作讨论    ← 按 session 名字切（如果你设了）

坑 10：Stitch 装的时候 `No authenticated account found after setup`

现象：跑 npx @_davideast/stitch-mcp init，走到 OAuth 那一步，页面跳 Google 登录成功回来，但命令行里报「No authenticated account found」。

原因：那个 init 脚本的 OAuth 流程需要你另开一个终端，手动跑：

gcloud auth login
gcloud auth application-default login

完了回原终端按回车。很多人以为浏览器登录完就结束了，其实 gcloud CLI 那头还没存凭证。

更简单的办法：别用 npx stitch-mcp init，直接在 ~/.claude.json 里配 HTTP MCP，见 §3.5。这样不用 gcloud、不用装 Google Cloud SDK，一步到位。

如果你已经跑过 npx 那条路，清理一下：

rm -rf ~/.stitch-mcp
rm -rf ~/.config/gcloud    # 只在你之前没用 gcloud 时这么干！
rm -rf ~/.npm/_npx/*        # 清 npx 缓存

坑 11：`longContextThreshold` 是 sticky 的吗？

误解：「一旦某次请求超了阈值切到 longContext 模型，之后整个 session 都用这个模型」。

真相：CCR 是无状态 / 每条请求独立路由的。这次请求 input tokens 15万 → 走 longContext；下一条请求只有 3千 tokens → 回到 default。

longContextThreshold 说的是这次请求发给模型的 input tokens（包括 system prompt + 历史 + 当前消息），不是整个上下文窗口。

对 2026 年的 1M 窗口模型来说，阈值可以开大一点（比如 120k），没必要一超 20k 就换模型。

坑 12：`image` 路由选什么模型？

误解：google/gemini-3.1-flash-image-preview 是专门处理图片的，肯定最好。

真相：带 flash-image 或 imagen 字样的是生成模型（文字→图片），不是分析模型（图片→文字）。你在 claude 里贴图片问它「这张图什么意思」是要分析模型。

正确选择（按强弱）：

anthropic/claude-4.7-opus-20260416 ← 最均衡
anthropic/claude-4.6-sonnet-20260217 ← 便宜一档
openai/gpt-5.4-20260305
google/gemini-3.1-pro-preview-20260219

坑 13：飞书事件订阅模式选错

现象：飞书 app_id / app_secret 都对，cc-connect 起来了，但发消息没反应。

排查：cc-connect 日志里看有没有 feishu: bot identified。

原因：飞书开发者后台「事件与回调」那边要选长连接模式（WebSocket），不能选 HTTP 回调（那个需要公网 URL + 白名单 IP）。

六、日常运维 cheatsheet

# 状态
cc-connect daemon status

# 日志（持续）
cc-connect daemon logs -f
# 或
tail -f ~/.cc-connect/logs/cc-connect.log

# 改完 config.toml
cc-connect daemon restart
# 失败的话
cc-connect daemon stop && sleep 2 && cc-connect daemon start

# 找卡死的 claude 子进程
pgrep -fa "claude.*cc-connect, a bridge"

# 极端情况强杀
pgrep -f "claude.*cc-connect, a bridge" | xargs kill -9
cc-connect daemon restart

# CCR
ccr start              # 前台跑 CCR
ccr restart            # 重启 CCR（配置改完后用）
ccr code               # 用 CCR 启动桌面端 claude
ccr code --resume <uuid-prefix>  # 按 UUID 恢复 session
ccr code --model <alias>         # 启动时直接指定模型

# 快捷重启
ccc-restart            # = cc-connect daemon restart
ccr-restart            # = ccr restart

# OpenRouter 余额
curl -H "Authorization: Bearer sk-or-v1-..." https://openrouter.ai/api/v1/auth/key | jq

七、几个值得提的设计哲学

分层的路由：cc-connect（协议层）/ claude（agent 层）/ CCR（路由层）/ OpenRouter（聚合层）。每一层只做自己的事，出问题能精确定位。
无状态的模型切换：CCR 的 Router 是每个请求独立决策的，longContextThreshold 不是 sticky 的。想要 sticky 就用 /model <alias>（让 claude 每次都把这个 model 字段发过来）。
session 互通但 picker 不互通：底层 jsonl 文件是共享的（靠 work_dir 对齐），但各自的 UI 读 jsonl 时有自己的过滤规则。接受这个现实，用 /list + /switch + ccr code --resume <uuid> 绕过。
launchd ≠ shell：守护进程的 env 是一张白纸。配置敏感信息要么写死在 json/toml，要么走 launchctl setenv，不要指望 .zshrc。
OpenRouter 分账号跑免费模型：主账号付费 key（我叫 or）跑付费模型，另起一个 or1 provider 专门跑 :free 模型。这样 rate limit 不打架，配额也清晰。

八、结语

这套东西跑通之后，日常使用体验是：

地铁上想起个 bug，掏手机飞书对 bot 说一句 gpt: 帮我看下 xxx.py 的 rate limit 逻辑
它在你家台式机上实际跑（用你家的 OpenRouter 配额、家里机器上所有已装好的工具链）
晚上回家敲 cc-opus 继续，手机上那个 session 用 UUID 一条命令恢复
语音输入 → Groq Whisper 转文字 → 一样跑

总体时间成本：从零到跑通大概一个下午，踩过上面 13 个坑之后会很顺。

完。

本文基于 2026/04 时点的 cc-connect、claude-code-router、Claude Code 版本整理。未来版本可能会修掉其中一些坑（尤其是 resume picker 不认 cc-connect session、router_api_key 必须非空这类），但架构层面的东西应该不会变。

从零搭建个人技术博客 · 篇三：用 Claude Code 的 skill 和 command 接管博客增删改查

lizhaopeng-cn — Fri, 24 Apr 2026 16:31:21 +0000

这是"从零搭建个人技术博客"系列的第三篇。前两篇讲了怎么把站点跑起来、怎么把文章自动分发到 dev.to / Hashnode；这一篇往回退一步，聊写作流本身 —— 写/改/删一篇博客的动作太零碎了，想把它自动化掉。

本篇目标：用 Claude Code 的 slash command + skill 给 blog.xtuul.com 装一个"AI 管家"，任何目录下都能敲：

/blog new "pnpm workspace 踩坑"
/blog list 只看草稿
/blog edit setup-astro-cloudflare-astropaper 把踩坑第 4 条扩展一下
/blog delete some-old-post

不在本篇：主站搭建（篇一）和跨平台分发（篇二）。

为什么不用脚本

最朴素的方案是写几个 bash 脚本：new-post.sh、list-posts.sh、delete-post.sh。能用，但对我来说有三个硬伤：

frontmatter 的写入仍然要我自己想。脚本能填日期、slug、author，但 title / tags / description 这几个字段还是得我自己琢磨。AI 可以顺手把这几件事一起做了。
自然语言参数处理不了。我说"把篇一踩坑第 4 条扩展一下"，脚本怎么知道第 4 条在哪？Claude 能自己读文件理解结构。
跨会话上下文。 脚本不记得"我的博客在哪个目录、用什么 schema、风格是什么"；Claude Code 的 skill 可以把这些写进 SKILL.md，每次触发自动加载。

所以这次直接在 Claude Code 里做。

Slash command vs Skill

开动之前先理清两个概念。Claude Code 里能扩展命令的有两样：

	Slash command	Skill
位置	`~/.claude/commands/xxx.md` 或 `.claude/commands/xxx.md`	`~/.claude/skills/xxx/SKILL.md` 或 `.claude/skills/xxx/SKILL.md`
触发	只能显式 `/xxx`	`/xxx` 或 Claude 根据 description 自动匹配
结构	单文件	文件夹，可带 `templates/` `references/` `examples/` `scripts/`
长度	适合一段短 prompt	适合长 playbook（官方推荐 <2000 词）
组合	一个命令可以调用 skill	skill 可以调用其他 skill

简单说：skill 是 command 的超集。新写东西默认选 skill，除非只是"给我贴一段固定 prompt"。

但 /blog new 这种形态必须由 command 提供 —— skill 的 slash 名就是它自己的 name（比如 /blog-new），没法拆成 /blog + 子命令。所以最终方案是 command 做路由 + 四个 skill 做实现。

整体架构

                      用户输入 /blog <sub> [args]
                                │
                                ▼
            ┌──────────────────────────────────────┐
            │ ~/.claude/commands/blog.md （路由）  │
            │  - 解析 $ARGUMENTS 第一个 token      │
            │  - 分派到对应 skill                  │
            └────────────────┬─────────────────────┘
                             │
       ┌──────────┬──────────┼──────────┬──────────┐
       ▼          ▼          ▼          ▼
   blog-new   blog-list  blog-edit  blog-delete
       │          │          │          │
       └──────────┴────┬─────┴──────────┘
                       │ 按需加载
                       ▼
       ~/.claude/skills/blog-shared/
         ├── templates/post.md
         ├── references/frontmatter-schema.md
         └── examples/reference-article.md

blog.md（command）只做一件事：看 $ARGUMENTS 第一个词，转发给对应 skill。
四个 skill 各自是独立的 playbook，互不干扰。edit 和 delete 在 slug 为空时会调用 blog-list（skill 之间可以互相调）。
blog-shared 不是 skill，而是共享资源目录，放 frontmatter schema、正文模板、风格范文。所有 skill 都按需读它，不常驻上下文。

实现：command 薄壳

~/.claude/commands/blog.md 是一个带 YAML frontmatter 的 Markdown：

---
argument-hint: <new|list|edit|delete> [参数或自由文本]
description: xtuul-blog 博客文章增删改查入口。按第一个词分派到对应 skill。
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# /blog 路由

用户输入：`$ARGUMENTS`

## 解析规则

1. 把 `$ARGUMENTS` 按**第一个空白**切分：
   - 第一个 token → **子命令**（必须是 new/list/edit/delete 之一）
   - 剩余全部文本 → **自由参数**，**原样**透传给对应 skill

2. 子命令和参数之间只用空格，不识别 `:` `|` `-` `#` 等分隔符。
   含空格的标题/slug 用双引号包裹。

## 执行

- new    → 调用 Skill `blog-new`，透传剩余文本
- list   → 调用 Skill `blog-list`，透传剩余文本
- edit   → 调用 Skill `blog-edit`，透传剩余文本
- delete → 调用 Skill `blog-delete`，透传剩余文本
- 其他或空 → 输出用法说明，不自行推断

关键点：不自己设计任何分隔符，只用空格 + 引号 + 自然语言。Claude 自己解析。

实现：blog-new skill

~/.claude/skills/blog-new/SKILL.md：

---
name: blog-new
description: This skill should be used when the user asks to
  "write a new blog post", "draft an article", "新开一篇文章",
  "起草博客", or invokes `/blog new`. Creates a new markdown
  post under /Users/xtuul/projects/xtuul-blog/src/data/blog/
  following xtuul-blog's AstroPaper frontmatter schema.
  Does not touch git.
argument-hint: "[标题 或 主题描述]"
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# blog-new：起草一篇新文章

... 工作流 ...

description 是 router 的命根子。Claude 靠这段决定你说"新写一篇博客"要不要触发这个 skill。官方文档里强调三点：

第三人称：This skill should be used when...，不用 You should...
具体触发短语：把用户会怎么说列出来
中英文并列：触发短语中英文都写，命中率更高

body 里按祈使句写步骤：确定标题 → 生成 slug → 写 frontmatter → 写正文 → 写入文件 → 汇报。参数为空时追问用户"想写什么"，而不是自己编。

实现：blog-list / edit / delete

blog-list：Glob src/data/blog/**/*.md，读每个文件前 30 行 frontmatter，按 pubDatetime 降序出表格。支持自然语言过滤（"只看草稿"、"标签 astro"）。
blog-edit：第一个 token 作 slug，剩余作修改意图。slug 为空时调用 blog-list 让用户选 —— skill 之间互相调用是合法的，而且复用现成逻辑最干净。
blog-delete：强制二次确认。用户必须原样打出 确认删除 <slug> 才执行，回 y/是/删 一概不算。

为什么 delete 要这么死板

删除不走 git（本仓库 push 之前都在本地）。文件一旦 rm 就没了。
y 太容易手滑打出来，原样复述 slug 才能保证用户真的看清了要删哪篇。

共享资源：blog-shared

blog-shared 不是 skill —— 没有 SKILL.md，Claude 不会主动扫描它。它是普通文件夹：

~/.claude/skills/blog-shared/
├── templates/post.md                # 带 {{...}} 占位符的正文骨架
├── references/frontmatter-schema.md # 字段硬规则（必填、格式、示例）
└── examples/reference-article.md    # draft: true 的风格范文

在各 skill 的 ## Additional Resources 小节里显式引用绝对路径：

## Additional Resources

- `~/.claude/skills/blog-shared/references/frontmatter-schema.md` — frontmatter 字段硬规则
- `~/.claude/skills/blog-shared/templates/post.md` — 正文骨架模板
- `~/.claude/skills/blog-shared/examples/reference-article.md` — 风格范文

Claude 触发 skill 时，只加载 SKILL.md body；需要时才 Read 上面这三个资源。这就是官方说的 progressive disclosure：主文件轻量化，详细内容按需加载。

好处很实在：改 schema 只改一个文件，四个 skill 自动跟着更新；改风格范文也不会污染真实的 src/data/blog/。

项目级 vs 用户级

Claude Code 支持两个位置：

位置	作用域	何时用
`<repo>/.claude/`	仅该仓库工作目录下生效	和仓库强耦合的命令；团队共享
`~/.claude/`	全局，任意目录都能用	个人工具、跨仓库可复用

两份同名会项目级覆盖用户级。

我最开始放在项目级，结果发现两个问题：

必须 cd ~/projects/xtuul-blog && claude 才能用 /blog，在桌面/下载目录里想顺手开一篇博客就不行。
GitHub 仓库里有 .claude/ 目录会被当成项目文件同步，别的设备或者协作者 clone 下来就自动启用了，不符合"这是我个人的工具"的定位。

所以搬到了用户级 ~/.claude/，并把 SKILL.md 里所有 src/data/blog/... 相对路径全部改成绝对路径 /Users/xtuul/projects/xtuul-blog/src/data/blog/...。代价是这套 skill 只能我这台机器用，但对我来说就是自己用，刚好。

踩过的坑

/blog 首次调用报 Unknown command。Claude Code 只在会话启动时扫描 commands 和 skills 目录。新建/搬迁文件后，必须重启 Claude Code 才能识别，/reload 之类的软重载不够。
项目级和用户级同名冲突。我忘了删项目级的旧版，新会话里仍然跑的是旧的相对路径 SKILL.md。删掉项目级的 .claude/ 后正常。
description 写得像文档就失效。第一版我写了 用于管理 xtuul-blog 的博客文章，Claude 根本不匹配自然语言请求。改成 This skill should be used when the user asks to "write a new blog post", "新开一篇文章", or invokes /blog new 之后命中率立马上去。description 是触发条件而不是文档，越具体越好。
skill body 超 2000 词后 Claude 抓不住重点。第一版 blog-new 把 schema 字段表、风格约束全塞进去，400 多行。后来按官方推荐拆成 SKILL.md（只写流程）+ references/frontmatter-schema.md（字段表）+ templates/post.md（骨架），主文件压到 100 多行，生成质量明显好转。
skill 内的路径必须是绝对路径。只要没法保证用户一直在某个 CWD，相对路径都是坑。我在 SKILL.md 里硬编码了 /Users/xtuul/projects/xtuul-blog/，同时在每个 skill 开头加了一段"路径（硬编码绝对路径，不依赖 CWD）"说明 —— 未来换机器要改的地方集中在一处。

小结

架构：commands/blog.md 做路由薄壳，四个独立 skill 做实现，一个 blog-shared 目录放共享资源
描述：skill 的 description 用第三人称 + 具体中英文触发短语，直接决定 router 命中率
篇幅：SKILL.md 控制在 <2000 词，详细内容走 references/ 和 templates/，按需加载
路径：全局 skill 里一律用绝对路径，不依赖当前工作目录
不碰 git：所有 skill 都禁 git 命令，最终 push 前人工 review —— 博客的每一次提交都值得亲眼看一遍

下一步想把 blog-new 再增强一下：支持传入参考文章 URL 或本地 markdown 路径，Claude 读完后再写。这样写技术选型类文章时就不用我一段段复制粘贴上下文。

至此系列三篇闭环了：篇一搭主站，篇二接分发，篇三管写作流。以后写一篇博客就是打开任意终端敲 /blog new 主题 → Claude 起稿 → 我修 → git push → workflow 自动同步到所有海外平台。整条链路零运维、按需生效，对一个人博客来说刚刚好。

从零搭建个人技术博客 · 篇二：跨平台自动分发

lizhaopeng-cn — Fri, 24 Apr 2026 11:52:15 +0000

篇一是主站（blog.xtuul.com）本身的搭建，篇三是写作流（/blog new 这套 skill）。这一篇填篇二：文章写完 push 上去之后，自动同步到其他平台，不用我手动复制粘贴。

本篇讲什么：一个具体的 GitHub Actions + TypeScript 小工具，push 到 main 就把 src/data/blog/*.md 发到 dev.to、Hashnode、博客园，首发拿到平台 id，之后再推就是 update 而不是重发。

本篇不讲什么：具体某个平台的 API 怎么接（RTFM 的活），以及为什么最后国内平台一个没留。最后一节会单独讲这个。

要解决的问题

主站在 Cloudflare Pages 上，但一篇文章想被人看到，光靠 Google 搜索和主站 RSS 远远不够。常见做法有三种：

只在主站写，其他平台空着——SEO 和流量都吃亏
每篇写完手动复制粘贴到其他平台——第 3 篇之后我就会放弃
写完一次 push，代码自动同步——这篇要做的事

关键约束：

主站是 canonical：dev.to / Hashnode 都支持声明 canonical_url，明确告诉搜索引擎"原文在 blog.xtuul.com"，这样即使文章被多平台收录，SEO 权重也不会被稀释
幂等：同一篇文章推两次不能变成两篇。要走"首发→拿到 id→以后用 id update"的路径
一个平台挂不阻塞别的：博客园风控拦了不能让 dev.to 也发不出去

整体架构

先把地图画出来：

┌───────────────────────────────────────────────────────────┐
│ 本地写作：/blog new → src/data/blog/<slug>.md             │
│                                                           │
│                    git push origin main                   │
│                            │                              │
└────────────────────────────┼──────────────────────────────┘
                             │
                             ▼
┌───────────────────────────────────────────────────────────┐
│ GitHub Actions: .github/workflows/syndicate.yml           │
│                                                           │
│   on.push.paths: [src/data/blog/**/*.md]                  │
│     │                                                     │
│     ▼                                                     │
│   pnpm dlx tsx scripts/crosspost/index.ts                 │
│     │                                                     │
│     │──► diff HEAD~1..HEAD 或 workflow_dispatch 入参     │
│     │──► 对每篇改动的 .md：                              │
│     │     ├─ load frontmatter                             │
│     │     ├─ if draft: skip                               │
│     │     ├─ for each platform (devto/hashnode/cnblogs): │
│     │     │    ├─ 已有 id → update                       │
│     │     │    └─ 无 id   → create, 拿 id+url           │
│     │     └─ 写回 frontmatter.crosspost.<platform>       │
│     └──► git add / commit / push [skip ci]               │
└───────────────────────────────────────────────────────────┘

代码都在 scripts/crosspost/：

scripts/crosspost/
├── index.ts              # 入口，解析 diff，调度每个 publisher
├── lib/
│   ├── frontmatter.ts    # 手写的极简 YAML parse/stringify
│   └── types.ts          # Post / Publisher / PublishResult 接口
└── platforms/
    ├── devto.ts          # POST /api/articles
    ├── hashnode.ts       # GraphQL mutation publishPost / updatePost
    └── cnblogs.ts        # MetaWeblog XML-RPC

设计决定与权衡

1. 文件就是状态，没有外部数据库

frontmatter 里直接加一个 crosspost 字段：

crosspost:
  devto:
    id: 3544836
    url: "https://dev.to/lizhaopengcn/xxx"
  hashnode:
    id: 69eb1b54bada4a44e9c589e2
    url: "https://xtuul.hashnode.dev/xxx"

第一次推文章：三个字段都不存在 → 脚本走 create → 拿到 id 和 url 写回 frontmatter → auto-commit 回 main。

第二次推同一篇：frontmatter 里已经有 id → 脚本走 update，不会产生重复文章。

为什么不用 SQLite / KV：这是个一人博客。加一个外部存储等于多一个要备份、要恢复、要对齐状态的东西。文章本身已经在 git 里了，id 就放旁边，状态和内容原子地一起 commit。

2. canonical URL 固定指向主站

每次发文章时都显式带 canonical_url: https://blog.xtuul.com/posts/<slug>/，哪怕主站还没上线那篇。

dev.to：支持 canonical_url 字段，显示"Originally published at blog.xtuul.com"
Hashnode：originalArticleURL 字段，行为一样
博客园：MetaWeblog 没 canonical 这个字段，只能在正文开头手动加一行"原文："（实际上最后没做，原因后面说）

3. 每个 publisher 实现同一个接口

export interface Publisher {
  name: "devto" | "hashnode" | "cnblogs";
  enabled: () => boolean;            // 环境变量齐了就 enable
  publish: (post: Post) => Promise<PublishResult>;
}

index.ts 不关心具体平台怎么调 API，只负责：挑出 enabled 的平台、串行跑、把 PublishResult 写回 frontmatter、最后 git commit。每加一个平台只要写一个新的 platforms/<name>.ts。

4. per-post 串行、per-platform 独立

一篇文章里三个平台串行发（dev.to → Hashnode → 博客园），每个都单独 try/catch。任意一个失败不阻塞其他平台，也不阻塞下一篇文章。所有结果最后统一打印。

for (const post of posts) {
  for (const platform of platforms) {
    try {
      const result = await platform.publish(post);
      writeback(post, result);
    } catch (err) {
      console.error(`✗ ${platform.name} ${action}: ${err.message}`);
    }
  }
}

踩过的坑

真写出来之后，前后一共掉坑里三次。记下来。

坑 1：Astro 的 `z.date()` 不接受带引号的 ISO 字符串

写完代码本地测试通过，push 到 main 之后 Cloudflare Pages 构建挂了：

pubDatetime: Expected type "date", received "string"

问题出在 "脚本回写 frontmatter" 这一步。Astro content collection 的 schema 里 pubDatetime 是 z.date()，它要求 YAML 里是裸的 timestamp，不能是字符串：

# 这样 Astro 能识别为 Date
pubDatetime: 2026-04-24T19:50:10+08:00

# 这样 Astro 会当 string，schema 直接挂
pubDatetime: "2026-04-24T19:50:10+08:00"

我的 YAML stringify 函数 "遇到包含 : 或其他特殊字符的字符串就加引号"，ISO 时间戳正好命中。修法是给日期类字段开白名单，裸输出：

const DATETIME_KEYS = new Set(["pubDatetime", "modDatetime"]);

function emit(key, value) {
  if (DATETIME_KEYS.has(key) && typeof value === "string") {
    return `${key}: ${value}`;   // 不加引号
  }
  // ...其他走通用 stringify
}

这种"主站和同步脚本之间有个看不见的契约"的坑，本地开发过程中完全不会碰到，只有 push 之后 Cloudflare 那边才会炸。CI 流水线一定要在两边都跑一次才能发现。

坑 2：自己写的 YAML parser 不支持嵌套对象

上面那段 crosspost.devto.id 是嵌套两层的。一开始我图省事，手写了个 20 行的 YAML parser，只支持"key: value"和列表。结果第二次推文章时：

✗ devto create: Canonical url has already been taken
✓ hashnode create → xxx-1-1     ← 注意 "-1-1"

脚本没读到已有的 id，当成全新文章再发了一遍。dev.to 靠 canonical 查重、直接 422 拒绝；但 Hashnode 完全不查重，默默给新文章一个 -1、-1-1 的递增 slug，看起来"发布成功"，实际上我的博客上重复文章越堆越多。

后来把 parser 换成支持递归缩进的版本，才读得出嵌套结构。教训：

不要在状态机关上图省事自己造轮子。要省就连嵌套都别用（比如把 crosspost_devto_id 拍平成一级 key），要嵌套就用 js-yaml。
"默默成功"比"显式失败"可怕得多。Hashnode 这种接口设计等于在地雷区里埋了一个脸朝下的地雷。

坑 3：博客园把 GitHub Actions 的出站 IP 风控了

这是让我最后放弃国内平台的直接原因，值得单拎一节。

为什么最后没做国内平台

本来清单上是：dev.to + Hashnode + 博客园。三个平台的 API 都接好了、secret 也配好了、本地 dry-run 全过。推上去跑 workflow：

✓ devto update → https://dev.to/...
✓ hashnode update → https://xtuul.hashnode.dev/...
✗ cnblogs create: HTTP 500 (empty body)

第一反应：鉴权有问题？XML-RPC 包错了？字段不全？

挨个验证：

在本地跑 curl，同样的 token、同样的 username、同样的 endpoint，打一条最小的 metaWeblog.newPost 过去。200，返回 postid，完美。
在本地跑脚本，用 loadPost 读真实文章、构造和 Actions 里字节级完全相同的 XML，再 curl 发出去。又是 200，postid 正常返回。
回到 Actions，一模一样的代码、一模一样的 secret。仍然 HTTP 500，body 空。

排查逻辑很简单——如果鉴权或内容有问题，博客园会返回 <fault> 带具体 faultString；400、401、404 也都会有 body 说明原因。500 + 空 body 是非常特殊的组合：请求根本没到业务层，而是在前置的网关/WAF 上就被掐掉了。

rpc.cnblogs.com 的网关对 Azure westus 的 IP 段做了风控。GitHub Actions 的 runner 正好在那里。对 "Azure IP 对国内内容平台的出站连接" 这件事有过了解的人应该都见过类似剧情——十年来这类平台对海外云的 IP 越来越敏感。

没有干净的解法：

在 runner 上装代理 → 需要一台国内机器当出口，相当于给博客同步这件事凭空加一台要维护的 VPS，零运维的前提破了
换平台官方 SDK → 博客园官方 API 只有 MetaWeblog，没有别的公开协议
用 Puppeteer 模拟浏览器 → CI 里跑无头 Chrome 要装 100MB 依赖、要在 CI 内完成扫码/验证码，越想越不值
调研了一下其他国内平台（掘金、CSDN、SegmentFault）：要么同样的 IP 风控，要么没有公开 API，抓包出来的接口几个月就会变一次

我算了下账：

方案	搭建成本	维护成本	稳定性
加一台国内中转机	半天	每月续费 + 偶尔抢救	中
Puppeteer 方案	2~3 天	平台前端一改就挂，每平台每季度至少修一次	中
浏览器插件（ArtiPub 之流）	装一下	低（但手动点击，不算自动化）	高但不自动
全部放弃国内平台	0	0	—

对一个个人博客来说，我不做国内平台的"机会成本" 是：国内读者来主站（或 dev.to / Hashnode 的英文版）的时候少看到一点入口。可以接受。

继续做国内平台的"直接成本" 是：一台新机器 or 一套会定期 rot 的 Puppeteer 代码。不能接受。

所以：

scripts/crosspost/platforms/cnblogs.ts 代码留着，以后哪天有国内机器了直接改 endpoint 就能用
workflow 里留着 CNBLOGS_* 的 secret 判断——没配就跳过，什么都不会打印
目前跑 workflow 只会看到 dev.to 和 Hashnode 成功

当前成品

workflow 配置

.github/workflows/syndicate.yml 的骨架：

name: Syndicate

on:
  push:
    branches: [main]
    paths:
      - "src/data/blog/**/*.md"
  workflow_dispatch:
    inputs:
      files:
        description: "要同步的文件路径（空格分隔），留空=diff"
        required: false

concurrency:
  group: syndicate
  cancel-in-progress: false

jobs:
  crosspost:
    runs-on: ubuntu-24.04
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 2 }
      # ... setup pnpm / node
      - run: pnpm dlx tsx scripts/crosspost/index.ts ${{ inputs.files }}
        env:
          DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}
          HASHNODE_API_KEY: ${{ secrets.HASHNODE_API_KEY }}
          HASHNODE_PUBLICATION_ID: ${{ secrets.HASHNODE_PUBLICATION_ID }}
          SITE_BASE: https://blog.xtuul.com/
      # ... auto-commit if frontmatter changed

关键点：

paths 过滤让"我只改了 README 或配置"的 push 不触发
concurrency 防止连续两次 push 引起竞态（前一次还没写回 id，后一次又 create 一遍）
fetch-depth: 2 才够算 HEAD~1..HEAD 的 diff
permissions: contents: write 才允许回写 commit

每篇文章的状态

前两篇文章现在的 frontmatter 尾部看起来是这样：

crosspost:
  devto:
    id: 3544836
    url: "https://dev.to/lizhaopengcn/..."
  hashnode:
    id: 69eb1b54bada4a44e9c589e2
    url: "https://xtuul.hashnode.dev/..."

以后任何一篇我改了正文 push 上去，脚本看到已有 id，走 update 路径，平台上直接原地更新，url 不变、评论不丢。

小结

这篇的主题本来应该是"跨平台分发"，实际结果是"跨两个海外平台分发 + 一篇国内平台劝退录"。

一些可以带走的结论：

canonical URL 必须显式。主站永远是 source of truth，分发只是副本。
幂等靠 id，不靠 title/slug 做匹配。id 写回 frontmatter，和文章原子地一起 commit，不要引入外部状态。
"默默成功"的平台要特别警惕。dev.to 的 422 比 Hashnode 的 -1-1 slug 友好得多。
零运维的门槛是"不需要我再额外养任何一台机器"。一旦为了一个副功能要上国内 VPS 或浏览器自动化，整个系统的维护成本结构就变了。

篇四还没想好，大概会写主站接入 Umami、或者 AstroPaper 主题的几处魔改。

从零搭建个人技术博客 · 篇一：Astro + Cloudflare Pages + AstroPaper

lizhaopeng-cn — Fri, 24 Apr 2026 07:27:15 +0000

这是"从零搭建个人技术博客"系列的第一篇，记录我把 blog.xtuul.com 从无到有跑起来的完整过程 —— 技术选型、架构、操作步骤、踩到的坑。

本篇目标：用最小的维护成本搭一个快、干净、免费、有个人品牌感的主站。
不在本篇：跨平台自动分发（dev.to / Hashnode / 掘金 / 公众号）—— 放到后续篇章。

整体架构与选型

最终架构

         Claude Code（在本地生成 Markdown）
                       │
                       ▼
          src/data/blog/xxx.md（Git 跟踪）
                       │  push
                       ▼
           GitHub: lizhaopeng-cn/xtuul-blog
                       │  webhook
                       ▼
              Cloudflare Pages（自动构建）
                       │
                       ▼
          blog.xtuul.com（HTTPS + 全球 CDN）
             + Cloudflare Web Analytics（站长后台）
             + 不蒜子（页面可见计数）
             + Giscus（GitHub Discussions 评论）

一个仓库、一次 push、全自动部署。没有服务器、没有数据库、没有后台。

为什么选这套组合

层	选型	为什么
框架	Astro	静态输出、零 JS 默认、支持 MD/MDX、生态比 Hugo 现代、比 Next.js 轻
主题	AstroPaper	Lighthouse 100、自带明暗主题/搜索/标签/RSS/sitemap、TypeScript + Tailwind
托管	Cloudflare Pages	免费、自带 CDN 和 HTTPS、与 Cloudflare DNS 天然融合
DNS	Cloudflare	域名本来就在这里，一条 CNAME 都省了
包管理	pnpm	磁盘效率和 monorepo 友好；AstroPaper 官方模板就是 pnpm

排除项（为什么不选它们）

WordPress —— 要维护数据库、安全补丁、主机账单。静态博客是一次性工作，没必要。
Hexo / VuePress —— 能用但生态趋冷，主题更新慢。
Next.js —— 大炮打蚊子。博客不需要 SSR / Server Components。
Vercel —— 也不错，但国内访问不如 Cloudflare 稳，且 DNS 不在一处。
GitHub Pages —— 无 CDN、自定义域名要额外配置、国内访问慢。

前置条件

一个顶级域名（我用的 xtuul.com），已托管在 Cloudflare
本地装好：node (20+)、pnpm、git、gh（GitHub CLI）
一个 GitHub 账号，gh auth login 登录过

验证：

node -v          # v20 以上
pnpm -v
git --version
gh auth status

第一步：用 pnpm 脚手架生成 AstroPaper

全程只用 pnpm。AstroPaper 官方模板、本地开发、Cloudflare Pages 构建命令都统一到 pnpm，保证只有一份 pnpm-lock.yaml，后面构建稳定性会省很多事。

cd ~/projects
pnpm create astro@latest xtuul-blog \
  --template satnaing/astro-paper \
  --install \
  --skip-houston \
  --no-git \
  --yes

参数含义：

--template satnaing/astro-paper 直接以 AstroPaper 作为起点
--install 自动 pnpm install
--no-git 先不初始化 git，后面手动推（避免 Astro 默认 commit 污染历史）
--skip-houston / --yes 跳过交互式问答

完成后：

cd xtuul-blog
pnpm dev
# 浏览器访问 http://localhost:4321/ 应该能看到 AstroPaper 默认主题

第二步：品牌化与本地化

AstroPaper 的全站配置集中在 src/config.ts。把站点信息改成自己的：

// src/config.ts
export const SITE = {
  website: "https://blog.xtuul.com/",
  author: "Xtuul",
  profile: "https://github.com/lizhaopeng-cn",
  desc: "记录 AI、编程、自动化和个人项目。",
  title: "Xtuul Blog",
  ogImage: "astropaper-og.jpg",
  lightAndDarkMode: true,
  postPerIndex: 4,
  postPerPage: 4,
  scheduledPostMargin: 15 * 60 * 1000,
  showArchives: true,
  showBackButton: true,
  editPost: { enabled: false, text: "", url: "" },
  dynamicOgImage: true,
  dir: "ltr",
  lang: "zh-CN",
  timezone: "Asia/Shanghai",
} as const;

社交链接在 src/constants.ts，默认带了 X / LinkedIn / WhatsApp 等，按需裁剪。我只留 GitHub + 邮箱：

export const SOCIALS: Social[] = [
  { name: "GitHub", href: "https://github.com/lizhaopeng-cn", linkTitle: `${SITE.title} on GitHub`, icon: IconGitHub },
  { name: "Mail", href: "mailto:xtuul@xtuul.com", linkTitle: `Send an email to ${SITE.title}`, icon: IconMail },
] as const;

导航栏中文化

src/components/Header.astro 里把 Posts / Tags / About / Archives / Search 改成 文章 / 标签 / 关于 / 归档 / 搜索，Skip to content 改成 跳转到正文。

默认深色模式

src/layouts/Layout.astro 里找到这段内联脚本，把空字符串改成 "dark"：

const initialColorScheme = "dark"; // 之前是 ""，现在强制首访深色

lightAndDarkMode: true 保留，用户点顶部月亮/太阳按钮仍可切换。

验证本地构建

pnpm build

看到 Finished in Xs 并且没有红色错误，就说明配置改动都是合法的。

第三步：推送到 GitHub

cd ~/projects/xtuul-blog
git init
git add -A
git commit -m "initial commit: Xtuul Blog on AstroPaper"

# 用 gh 一条命令建 public 仓库 + 推送
gh repo create xtuul-blog --public --source=. --remote=origin --push

public 还是 private？ 博客内容公开，仓库也建议 public。public 仓库的 GitHub Actions 额度是无限的，private 每月只有 2000 分钟，这在后续加自动分发时会成为实际差别。

第四步：Cloudflare Pages 首次部署

Dashboard → Workers & Pages → Create → Pages → Connect to Git。

选仓库 lizhaopeng-cn/xtuul-blog
Framework preset: Astro
Build command: pnpm install --frozen-lockfile && pnpm build
Build output directory: dist
Environment variables（Production）: NODE_VERSION = 22（纯文本）

为什么显式写 pnpm 命令：Cloudflare Pages 默认根据 lockfile 探测包管理器，大多数情况会对，但偶尔会 fallback 到 npm。显式写最稳。

为什么固定 Node 版本：构建容器默认 Node 可能是 18，而新版 Astro 要求 20+。指定 22 是目前的 LTS，最保险。

点 Save and Deploy，1–3 分钟后应该看到绿色 Success。

第五步：绑定自定义域名

Pages 项目 → Custom domains → Set up a custom domain → 填 blog.xtuul.com。

因为域名本来就在 Cloudflare，它会自动在 DNS 区加一条 CNAME：

blog    CNAME    xtuul-blog.pages.dev    (Proxied)

等几十秒证书签发完成，https://blog.xtuul.com/ 就活了。

以后发布新文章的流程

文章存放位置：src/data/blog/（文件名即 URL slug）。

标准 frontmatter 模板

---
author: Xtuul
pubDatetime: 2026-04-22T10:30:00+08:00
title: "文章标题"
slug: article-slug
featured: false   # true 显示在首页"精选文章"
draft: false      # true 不会发布
tags:
  - tag1
  - tag2
description: 一句话摘要（会出现在文章卡片和 SEO 描述里）
---

正文...

三步发布

# 1. 写文章（放到 src/data/blog/xxx.md）
# 2. 本地预览（可选）
pnpm dev

# 3. 提交推送
git add src/data/blog/xxx.md
git commit -m "post: 标题"
git push

Cloudflare Pages 监听到 push，自动构建 + 部署，从 push 到线上可见通常 2 分钟内。

写作期间的小技巧

draft: true → 线上看不到但本地能预览，适合攒稿
featured: true → 首页置顶
本地改 src/config.ts / 组件时 pnpm dev 会热更新

用 Claude Code 直接产出 Markdown

上面的发布流程能跑，但从 0 到一篇成稿还是我自己打字。博客更顺手的工作流是：

一句话需求 → Claude Code 写到 src/data/blog/xxx.md → 本地预览 → git push

我写博客的时候直接在仓库根目录开 Claude Code：

cd ~/projects/xtuul-blog
claude

然后一句话命题作文：

"写一篇新文章放到 src/data/blog/setup-astro-cloudflare-astropaper.md，主题是从零搭建个人技术博客，选型是 Astro + Cloudflare Pages + AstroPaper，frontmatter 用 author: Xtuul、pubDatetime 用当前时间、featured: true、tags 给 astro/cloudflare/astropaper/blog/devops。"

Claude Code 直接落盘成 .md 文件，本地 pnpm dev 实时预览，不满意继续对话改（"第二部分太啰嗦，合并到第一部分"），满意了就 commit + push。

为什么要这样写，而不是甩一个"帮我写博客"

几点经验：

文件路径写死。明确告诉 Claude 写到哪个文件、slug 是什么，它就会直接 Write 工具落盘，不会先在对话里生成一坨让你复制。
frontmatter 所有字段都写死。作者、tags、是否 featured、是否 draft。Claude 对 AstroPaper 的 frontmatter schema 没先验知识，不写死它会漏字段或乱填。
技术选型和事实由你给，Claude 负责组织行文和代码块。让 Claude 自由发挥容易出"正确但不是你的"内容——你的博客是写给你自己的受众，口吻、技术偏好、踩坑细节都得自己提供。
分多轮迭代。先让它写大纲，再写某一节正文，再让它把某个代码块换成更简洁的版本。一次性让它写完 2000 字通常质量不如分块。

工作流的好处

不离开编辑器：写、改、预览、提交在一个 shell 里完成，不用在对话窗口和编辑器之间来回切。
可追溯：所有改动都是 git diff，不好回滚就 git checkout --。
自动化友好：以后可以把"发布到 dev.to / Hashnode / 掘金"也交给 Claude Code 跑 MCP 调用外部 API，这是篇二要做的事。

第六步：接入访问统计与评论

主站能跑之后，马上会想要两件事：这篇文章有多少人看过、读者能不能留言。我接了三个互不重叠的服务：

需求	方案	数据给谁看
站长看流量后台（趋势、地理分布、Referer）	Cloudflare Web Analytics	我，在 CF Dashboard
页面上可见的计数（页脚总 PV/UV、文章阅读量）	不蒜子	所有访客
评论系统	Giscus（基于 GitHub Discussions）	所有访客，数据在我仓库

全部免费、零后端。

6.1 Cloudflare Web Analytics

Dashboard → Analytics & Logs → Web Analytics → Add a site → 选 Manual（手动 JS 片段），会拿到一段：

<script defer src="https://static.cloudflareinsights.com/beacon.min.js"
        data-cf-beacon='{"token": "YOUR_TOKEN"}'></script>

把它放到 src/layouts/Layout.astro 的 <head> 里（<ClientRouter /> 之后），全站自动上报。

注意：

后台数据只有自己看。访客看不到任何数字，不蒜子才是"前台展示"。
每个 site 一个独立 token。我 xtuul.com 是橙云走自动统计，blog.xtuul.com 是 Pages 自带的灰云（Pages 的自定义域都是灰云，这是正常的，不用改橙），走不到自动统计，所以单独为它生成了 token。
如果你还想统计主站就再加一个 site、给主站页面嵌入对应 token 的片段即可，数据不会互相混。

6.2 不蒜子：页面可见计数

不蒜子是国内开发者博客最常用的极简计数器，一个 script + 三个约定的 span id：

<!-- 站点总 PV -->
<span id="busuanzi_container_site_pv">
  总访问量 <span id="busuanzi_value_site_pv"></span> 次
</span>

<!-- 站点 UV -->
<span id="busuanzi_container_site_uv">
  访客数 <span id="busuanzi_value_site_uv"></span> 人
</span>

<!-- 当前文章 PV -->
<span id="busuanzi_container_page_pv">
  阅读量 <span id="busuanzi_value_page_pv"></span> 次
</span>

脚本只有三行：

<script async defer
  src="https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>

三个关键细节：

容器默认 display:none。不蒜子脚本拿到数据后会把 busuanzi_container_* 显示出来。如果不默认隐藏，脚本返回前会看到 访客数：人 这种裸文案，很丑。
Astro ClientRouter 切页脚本不会重跑。AstroPaper 用 <ClientRouter /> 做无刷新页面切换，<script src> 只在首次加载时执行一次，切换到下一篇文章的 page_pv 不会刷新。解决：在 astro:page-load 事件里重新注入脚本。
只在 astro:page-load 里注入，不要在 IIFE 里再调一次。否则页面首次加载时首次 IIFE + astro:page-load 事件会各发一次 JSONP，PV +2。

最后得到的是这样一段：

<script is:inline>
  document.addEventListener("astro:page-load", () => {
    // 清掉上次注入的脚本标签
    document.querySelectorAll("script[data-busuanzi]")
      .forEach(node => node.remove());
    const s = document.createElement("script");
    s.src = "https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js";
    s.async = true;
    s.defer = true;
    s.setAttribute("data-busuanzi", "1");
    document.body.appendChild(s);
  });
</script>

不蒜子的局限（被很多教程模糊带过）：

只有 page_pv，没有 page_uv。想知道某篇文章有多少独立访客——不蒜子做不到，只能自己上 Cloudflare Workers + KV。
本地 localhost:4321 的数字是全球所有本地开发者共享的，动辄几万几十万，这是正常现象，上线到真实域名后从 0 开始计数。

6.3 Giscus：基于 GitHub Discussions 的评论

Giscus 把评论直接挂在你仓库的 GitHub Discussions 上。好处：

评论数据在你自己仓库，跟着仓库迁移走
访客用 GitHub 账号登录，天然过滤机器人
支持 reaction、Markdown、代码块
不要你跑任何后端

准备工作：

仓库开启 Discussions：Settings → Features → Discussions ✅
安装 giscus GitHub App 到仓库
去 giscus.app 配置向导，选 repo + discussion category（建议用 Announcements 这种受限分类，避免无关讨论），拿到一段 <script>

在 Astro 里包装成组件，关键要点有两个：

主题要跟站内明暗同步。Giscus 默认 preferred_color_scheme 跟系统，但 AstroPaper 允许用户手动切换 <html data-theme="...">，两者会对不上。要用 MutationObserver 监听 data-theme 变化，通过 postMessage 告诉 giscus iframe 换皮。
ClientRouter 切页要重新挂载。否则上一篇文章的评论残留在下一篇。

简化后的组件（完整版在仓库 src/components/Giscus.astro）：

<section id="giscus-container">
  <h2>评论</h2>
  <div id="giscus"></div>
</section>

<script is:inline data-astro-rerun>
  (function () {
    const container = document.getElementById("giscus");
    if (!container) return;
    container.innerHTML = ""; // 清理上一页残留

    function currentGiscusTheme() {
      return document.documentElement.getAttribute("data-theme") === "dark"
        ? "noborder_dark"
        : "noborder_light";
    }

    const s = document.createElement("script");
    s.src = "https://giscus.app/client.js";
    s.setAttribute("data-repo", "lizhaopeng-cn/xtuul-blog");
    s.setAttribute("data-repo-id", "...");
    s.setAttribute("data-category", "Announcements");
    s.setAttribute("data-category-id", "...");
    s.setAttribute("data-mapping", "pathname");
    s.setAttribute("data-theme", currentGiscusTheme());
    s.setAttribute("data-lang", "zh-CN");
    s.setAttribute("data-loading", "lazy");
    s.setAttribute("crossorigin", "anonymous");
    s.async = true;
    container.appendChild(s);

    // 站内主题切换时通知 iframe 同步
    new MutationObserver(() => {
      const frame = document.querySelector("iframe.giscus-frame");
      frame?.contentWindow?.postMessage(
        { giscus: { setConfig: { theme: currentGiscusTheme() } } },
        "https://giscus.app"
      );
    }).observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["data-theme"],
    });
  })();
</script>

然后在 src/layouts/PostDetails.astro 里 <Giscus /> 一行就挂上了。

踩过的坑

Cloudflare Pages 不改构建命令：默认的 npm run build 在项目只有 pnpm-lock.yaml 时会因为缺 package-lock.json 失败。必须显式改成 pnpm install --frozen-lockfile && pnpm build。
Node 版本：不指定 NODE_VERSION，构建容器可能给你 18，新版 Astro 直接报错。
默认主题探测：AstroPaper 默认是跟随系统 prefers-color-scheme。想强制首次深色，改 Layout.astro 里的 initialColorScheme = "dark"，别去动 lightAndDarkMode（那个是是否允许切换的开关）。
不蒜子在 localhost:4321 上数字离谱：不蒜子按域名隔离，localhost 被所有开发者共享，本地看到几万几十万是正常的。上线到 blog.xtuul.com 才从 0 开始独立计数。
Giscus 不跟随 AstroPaper 主题切换：Giscus 默认用 preferred_color_scheme 跟系统，但 AstroPaper 允许用户点按钮切 data-theme，两者会脱节。必须用 MutationObserver 监听 data-theme，通过 postMessage 通知 iframe 换皮。

下一篇预告

篇二：把一篇 Markdown 自动分发到 dev.to / Hashnode，canonical 指向主站。

核心思路：

统一 frontmatter 里加 syndicate: { devto: true, hashnode: true } 开关
GitHub Actions 监听 src/data/blog/ 变化，调用各平台 API 发布/更新
首发后把平台返回的文章 ID 回写到 frontmatter，实现幂等更新

等系列跑完，最终目标是：在 Claude Code 里一句话生成 md → git push → 全网同步更新。

Forem: lizhaopeng-cn

Claude Code 模型切换与 CCR 路由：踩坑全记录

目录

问题一：/model haiku 没走 ALIAS_MAP

排查过程

还有第二个 bug

修法

问题二：直接 claude 启动为什么 /model 还能切换

关键：ANTHROPIC_BASE_URL 指向 OpenRouter

CCR vs 直挂 OpenRouter 的区别

问题三：内置别名 vs 三方 model ID 差在哪里

为什么会这样

/model 切换的优先级

如果把 ANTHROPIC_MODEL 换成非 Claude 模型

跨 Provider 切换的隐形地雷：thinking block 签名污染

机制

修复

为什么 CCR 不会出现这个 bug

官方独有功能清单

Auto 模式（任务复杂度自动切换 Opus/Sonnet/Haiku）

Prompt Caching 命中率

1M Context 的计费入口

其他官方独占

小结

把 Claude Code 搬进飞书和 Telegram：cc-connect + CCR 完整架构、安装流程与踩坑全记录

目录

一、为什么要做这套东西

二、整体架构

三、安装流程（macOS，一步步来）

3.1 装 CCR（claude-code-router）

几个重要的 Router 字段含义

router.js（自定义路由，强烈推荐）

为什么 Anthropic 模型的 key 必须写完整 ID

顺便省一次切换：启动直连 OpenRouter 也能复用这套映射

3.2 装 cc-connect

飞书 app_id / app_secret 怎么拿

Telegram token 怎么拿

验证前台跑通

3.3 装 ffmpeg（语音必需）

Groq Whisper API key 怎么拿

3.4 改成 launchd 守护进程（开机自启）

四、日常使用

4.1 切模型

4.2 cc-connect 内置命令

4.3 桌面端看手机 session（需要同 work_dir）

4.4 桌面启动 alias

五、踩坑全记录

坑 1：gpt is not a valid model ID

坑 2：/login is not a cc-connect command / /login isn't available in this environment

坑 3：Voice message requires ffmpeg for format conversion

坑 4：config.toml not found in /Users/xtuul

坑 5：cc-connect deamon restart（打错字）→ Telegram getUpdates 冲突

坑 6：launchctl bootstrap failed: 5: Input/output error

坑 7：daemon 模式下环境变量不生效（MCP / API key）

坑 8：/resume picker 看不到 cc-connect 起的 session

坑 9：/switch 还是 /resume？

坑 10：Stitch 装的时候 No authenticated account found after setup

坑 11：longContextThreshold 是 sticky 的吗？

坑 12：image 路由选什么模型？

坑 13：飞书事件订阅模式选错

六、日常运维 cheatsheet

七、几个值得提的设计哲学

八、结语

从零搭建个人技术博客 · 篇三：用 Claude Code 的 skill 和 command 接管博客增删改查

目录

为什么不用脚本

Slash command vs Skill

整体架构

实现：command 薄壳

实现：blog-new skill

实现：blog-list / edit / delete

为什么 delete 要这么死板

共享资源：blog-shared

项目级 vs 用户级

踩过的坑

小结

从零搭建个人技术博客 · 篇二：跨平台自动分发

目录

要解决的问题

整体架构

`router.js`（自定义路由，强烈推荐）

坑 1：`gpt is not a valid model ID`

坑 2：`/login is not a cc-connect command` / `/login isn't available in this environment`

坑 3：`Voice message requires ffmpeg for format conversion`

坑 4：`config.toml not found in /Users/xtuul`

坑 5：`cc-connect deamon restart`（打错字）→ Telegram getUpdates 冲突

坑 6：`launchctl bootstrap failed: 5: Input/output error`

坑 8：`/resume` picker 看不到 cc-connect 起的 session

坑 9：`/switch` 还是 `/resume`？

坑 10：Stitch 装的时候 `No authenticated account found after setup`

坑 11：`longContextThreshold` 是 sticky 的吗？

坑 12：`image` 路由选什么模型？

坑 1：Astro 的 `z.date()` 不接受带引号的 ISO 字符串