当你运行 node server.mjs 之类命令启动本地服务时，终端突然蹦出一句 Port 3839 is already in use——这说明目标端口已经被某个进程占用了。本文给出一套各平台通用、拿来即用的「查端口 → 确认 → 杀进程 → 复查」命令速查，并深挖本机实战中踩过的各种坑，最后给出让脚本自己释放端口的根治方案。

📑 目录

• 一、通用处理思路
• 二、Windows 下三种方式
• 三、macOS / Linux
• 四、本机实战记录
• 五、为什么”照着教程杀不掉”？常见坑
• 六、根治：让脚本自己释放端口（Node.js 示例）
• 七、注意事项

一、通用处理思路

不管什么系统，思路都一样，四步闭环：

1. 查端口 —— 找出监听目标端口的进程 PID
2. 确认身份 —— 看一眼进程名 / 路径，避免误杀系统关键进程
3. 杀进程 —— 终止该 PID
4. 复查 —— 确认端口已释放，再重启服务

下文统一以端口 3839 为例，按需替换即可。

二、Windows 下三种方式

方式一：PowerShell（权限最全，推荐）

# 1. 查占用 3839 的进程 PID
Get-NetTCPConnection -LocalPort 3839 | Select-Object LocalPort, State, OwningProcess

# 2. 看进程身份（把 4452 换成上一步得到的 PID）
Get-Process -Id 4452

# 3. 强制终止
Stop-Process -Id 4452 -Force

# 4. 复查（无输出即已释放）
Get-NetTCPConnection -LocalPort 3839 -ErrorAction SilentlyContinue

方式二：命令提示符 cmd

:: 1. 查 PID（最后一列）
netstat -ano | findstr 3839

:: 2. 强制终止（把 4452 换成查到的 PID）
taskkill /PID 4452 /F

方式三：Git Bash（Windows 上的 Unix 风格 shell）

⚠️ 坑点（亲身踩过，详见第五节）：Git for Windows 默认没有 lsof，也没有 fuser。 所以 lsof -i :3839、kill -9 $(lsof -t -i:3839)、fuser -k 3839/tcp 都会直接 command not found， 拿到空 PID 去 kill 自然杀不掉——这也是很多人”照着教程试了都不行”的真正原因。 在 Git Bash 里请用 Windows 自带的 netstat + taskkill（两者都是 Windows 二进制，Git Bash 能直接跑，且 taskkill 才能真的结束 Windows 进程；kill -9 对 Windows 进程经常无效）。

# 1. 查占用进程（Windows netstat，Git Bash 可用）
netstat -ano | grep :3839

# 2. 终止（把 24292 换成查到的 PID）
taskkill /F /PID 24292

如果装了 lsof（如 WSL 或额外装了），Unix 写法才适用：

lsof -i :3839            # 仅当环境里确实装了 lsof
kill -9 $(lsof -t -i:3839)

三、macOS / Linux

# 1. 查占用进程
lsof -i :3839
sudo netstat -tulpn | grep :3839

# 2. 终止
kill -9 <PID>

# 更直接的写法（按端口杀，需 fuser）
fuser -k 3839/tcp

注意：macOS / Linux 默认带 lsof / fuser，上面的 Unix 写法可用；而 Windows 的 Git Bash 没有，千万别照搬。

四、本机实战记录

本次在 Windows + Git Bash 环境下遇到 Port 3839 is already in use：

• netstat -ano | grep :3839 → 命中 127.0.0.1:3839 LISTENING 4452
• 安全策略禁用了 tasklist / wmic，无法读取进程路径；改用 PowerShell Stop-Process -Id 4452 -Force 终止
• netstat -ano | grep :3839 复查 → 无输出，确认端口已释放

注意：部分环境里 PowerShell 的 stdout 不回显，杀进程后无法从命令输出确认结果。此时用 netstat 复查端口是否释放，是更可靠的验证手段。

占用 127.0.0.1:3839 的通常是你自己的旧服务实例没退出（比如同一个脚本上次没正常结束），确认进程名后放心终止即可。

五、为什么”照着教程杀不掉”？常见坑

很多人照着网上的教程敲命令，端口却纹丝不动。下面这些坑都是本机真实踩过的：

坑 1：Git Bash 里没有 lsof / fuser

Git for Windows 默认只带一小部分 Unix 工具。用 command -v lsof 一查，大概率是空的。于是教程里的：

lsof -i :3839
kill -9 $(lsof -t -i:3839)

会直接报 lsof: command not found，$(...) 拿到空字符串，kill 拿不到 PID，自然”杀了个寂寞”。

✅ 解法：在 Git Bash 里改用 Windows 自带的 netstat + taskkill（见第二节方式三），它们是 Windows 二进制，Git Bash 能直接跑。

坑 2：kill -9 杀不掉 Windows 进程

即使在 Git Bash 里 kill -9 <PID> 返回成功，Windows 进程也常常”假装死了”——端口还在。原因是 kill 发的是 Unix 信号，Windows 进程大多不认。

✅ 解法：结束 Windows 进程要用 Windows 自己的 taskkill /F /PID <PID>，它才会真正终止进程并释放端口。

坑 3：PowerShell 不回显 stdout，不知道到底杀没杀

在 CI / 某些 agent 环境里，PowerShell 的 Stop-Process 确实执行了，但命令输出看不到，你无法确定结果。

✅ 解法：别看输出，直接用 netstat -ano | grep :3839 复查端口。有输出 = 还在占用；无输出 = 已释放。这是最可靠的验证手段。

坑 4：端口”复活”——被守护进程反复拉起

如果占用端口的进程是由 pm2 / nodemon / 某个批处理循环托管的，你 taskkill 掉它后，守护进程会立刻重新拉起一个新 PID 的相同进程，端口转眼又被占，看起来就像”怎么杀都杀不掉”。

✅ 解法：先停掉守护者，再杀：

pm2 stop <id>          # 若由 pm2 托管
# 或关掉启动它的父脚本 / 终端，再 taskkill /F /PID <PID>

坑 5：脚本自己不释放端口（最隐蔽的元凶）

很多启动脚本遇到 EADDRINUSE（端口已被占用）时，只是 console.error("Port is already in use") 然后退出，既不杀掉占用者，也不换端口。结果是：上次没退干净的实例一直占着端口，你每次重跑都撞同一个端口，陷入”报错 → 手动杀 → 又报错”的死循环。

✅ 解法：让脚本自己在启动时检测并释放端口，见下一节。

六、根治：让脚本自己释放端口（Node.js 示例）

与其每次手动查、手动杀，不如在脚本里加上”端口被占就自动 kill 占用者并重试监听”的逻辑。下面是一段跨平台、可直接抄的模板（Windows 用 netstat+taskkill，mac/Linux 用 lsof+kill）：

import http from "node:http";
import { execSync } from "node:child_process";

const PORT = 3839;

// 查占用端口的进程 PID（按平台选用不同命令）
function findPidOnPort(port) {
  try {
    if (process.platform === "win32") {
      const out = execSync(
        `netstat -ano | findstr :${port} | findstr LISTENING`,
        { windowsHide: true }
      ).toString();
      for (const line of out.split(/\r?\n/)) {
        const m = line.trim().match(new RegExp(`:${port}\\s+.*\\s+(\\d+)\\s*$`));
        if (m) return parseInt(m[1], 10);
      }
    } else {
      const out = execSync(`lsof -ti :${port}`, { windowsHide: true }).toString();
      const pid = parseInt(out.trim().split(/\s+/)[0], 10);
      if (!isNaN(pid)) return pid;
    }
  } catch {
    // 无命中 / 命令不存在，忽略
  }
  return null;
}

// 强制终止进程（按平台选用不同命令）
function killPid(pid) {
  const cmd =
    process.platform === "win32" ? `taskkill /F /PID ${pid}` : `kill -9 ${pid}`;
  try {
    execSync(cmd, { windowsHide: true });
    return true;
  } catch {
    return false;
  }
}

function handler(req, res) {
  res.end("ok");
}

const MAX_RETRIES = 3;
let retries = 0;

function startServer() {
  const server = http.createServer(handler);
  server.listen(PORT, "127.0.0.1", () => {
    console.log(`Listening on http://127.0.0.1:${PORT}`);
  });

  server.on("error", (e) => {
    if (e.code === "EADDRINUSE") {
      if (retries < MAX_RETRIES) {
        retries++;
        const pid = findPidOnPort(PORT);
        // 不杀自己；pid === process.pid 的极端情况跳过
        if (pid && pid !== process.pid) {
          console.warn(
            `Port ${PORT} 被 PID ${pid} 占用，尝试终止后重试 (${retries}/${MAX_RETRIES})...`
          );
          if (killPid(pid)) {
            console.warn(`已终止 PID ${pid}，1 秒后重试...`);
            setTimeout(startServer, 1000);
            return;
          }
          console.error(`无法终止 PID ${pid}，请手动执行：taskkill /F /PID ${pid}`);
        } else {
          console.error(`端口 ${PORT} 被占用且无法定位占用者。`);
        }
        process.exit(1);
      } else {
        console.error(`端口 ${PORT} 重试 ${MAX_RETRIES} 次仍被占用。`);
        process.exit(1);
      }
    } else {
      console.error(`Server error: ${e.message}`);
      process.exit(1);
    }
  });
}

startServer();

原理：server.listen 失败触发 error 事件，若错误码是 EADDRINUSE，就 findPidOnPort 找到占用者 → killPid 强杀 → 等 1 秒后 startServer 重新监听，最多重试 3 次。命中”坑 5”的场景时，这一套能自动清掉上次没退干净的实例，你只需再跑一次脚本即可。

安全提示：自动强杀会终止占用端口的进程。本地开发端口（如 127.0.0.1:3839）一般只属于你自己，风险可控；但生产环境或重要服务端口请勿盲目套用，应先确认占用者身份。

七、注意事项

• 先确认再杀：端口冲突常由你自己的旧服务实例未退出导致，但务必看一眼进程名，避免误杀数据库、SSH 等关键进程（尤其用自动释放脚本时）。
• 系统级工具可能被禁用：某些安全策略会禁用 tasklist / wmic / sc 等。遇到工具不可用提示时，改用 netstat（查）+ PowerShell Stop-Process / taskkill（杀）。
• 验证靠复查：无论用哪种方式杀，最后都 netstat -ano | grep :3839 复查一次，无输出才是真释放。
• 根治端口冲突：首选在启动脚本里加「启动前自动检测并释放端口」的逻辑（见第六节），其次才是改用随机 / 可配置端口，省去每次手动清理。
• /F 与 -9 都是强制终止：会立即结束进程且不给其清理机会，仅在常规退出无效时使用。

本文命令与第六节代码均已在本机验证可用。如果对你有帮助，欢迎在评论区交流更优雅的端口管理姿势。

白嫖Anthropic，免费用户也能够使用Claude进行编程，支持Claude Sonnet 4.6/4.5 thinking 模型

核心思路：将 coding-tools-mcp 接入到网页版本 Claude 当中，这样我们即可让网页版 Claude 获得本地代码编辑能力，化身 Claude Code。

架构链路：

Claude 网页版 → 公网 Tunnel → 本地 MCP Server → 你的代码目录

准备工作：

1. 一个能正常使用的 Claude 网页账号
2. Python 环境
3. 一个测试用的代码目录

第一步：安装 cloudflared

cloudflared 是 Cloudflare Tunnel 的命令行工具。后面要靠它把本地 8000 端口临时映射到公网去给 Claude 网页端访问。

macOS 直接用 Homebrew：

brew install cloudflared

Windows 可以用 winget：

winget install --id Cloudflare.cloudflared

Linux 就按自己的发行版来，去 Cloudflare 文档里下载对应包也行。装完先看一眼版本，确认命令能跑：

cloudflared --version

第二步：创建 Cloudflare Quick Tunnel

现在把本地 8000 端口暴露出去：

cloudflared tunnel --url http://localhost:8000

终端里会出现一个 trycloudflare.com 的临时地址。先别关这个窗口，后面配置 MCP 服务要用到它。这个 Tunnel 用完就关。它是公网入口，不是长期服务。

第三步：安装 coding-tools-mcp

安装 MCP 工具包：

pip install coding-tools-mcp

我更建议放到虚拟环境里，后面清理也方便：

python -m venv .venv
source .venv/bin/activate
pip install coding-tools-mcp

第四步：启动 MCP 服务

接下来配置几个 OAuth 环境变量，然后启动服务。这里的 client-id、client-secret、password 不要照抄示例，自己随便生成一组。关键是别太短，也别发给别人。

macOS / Linux：

export CODING_TOOLS_MCP_OAUTH_CLIENT_ID="your-client-id"
export CODING_TOOLS_MCP_OAUTH_CLIENT_SECRET="your-client-secret"
export CODING_TOOLS_MCP_OAUTH_PASSWORD="your-login-password"
export CODING_TOOLS_MCP_SERVER_URL="填入刚才 Cloudflare Tunnel 输出的地址"

coding-tools-mcp \
  --workspace /path/to/your/repo \
  --host 127.0.0.1 \
  --port 8000 \
  --oauth-mode

Windows PowerShell：

$env:CODING_TOOLS_MCP_OAUTH_CLIENT_ID="your-client-id"
$env:CODING_TOOLS_MCP_OAUTH_CLIENT_SECRET="your-client-secret"
$env:CODING_TOOLS_MCP_OAUTH_PASSWORD="your-login-password"
$env:CODING_TOOLS_MCP_SERVER_URL="https://xxx.trycloudflare.com/"

coding-tools-mcp `
  --workspace C:\Users\HP\Desktop\1 `
  --host 127.0.0.1 `
  --port 8000 `
  --oauth-mode

Windows CMD：

set CODING_TOOLS_MCP_OAUTH_CLIENT_ID=your-client-id
set CODING_TOOLS_MCP_OAUTH_CLIENT_SECRET=your-client-secret
set CODING_TOOLS_MCP_OAUTH_PASSWORD=your-login-password
set CODING_TOOLS_MCP_SERVER_URL=https://xxx.trycloudflare.com/

coding-tools-mcp --workspace C:\Users\HP\Desktop\1 --host 127.0.0.1 --port 8000 --oauth-mode

将 —workspace 后面的内容填写为你希望 Claude 操作的临时目录。建议只给一个干净的小项目目录，别把整个根目录、下载目录、桌面等全暴露过去。

第五步：在 Claude 网页端添加 Connector

1. 打开侧边栏里的 Customize
2. 选择 Connector
3. 点击添加 Custom Connect
4. 填入前面配置的服务地址和 OAuth 信息
5. 点击 Connect
6. 按页面提示完成验证

连上之后，Claude 应该能看到 coding-tools-mcp 暴露出来的工具。这时候就可以让 Claude 做一些简单的代码任务了，比如读项目结构、定位报错、改一个函数、补一小段测试。

原方案弊端

更优方案：Claude 桌面端 + 本地 MCP（推荐）

如果你能安装 Claude 桌面客户端，可以完全绕开 cloudflared 和公网暴露：

Claude 桌面客户端 ← 本地进程通信 → MCP Server（localhost）← 你的代码目录

配置文件 claude_desktop_config.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "D:/Projects/your-repo"
      ]
    }
  }
}

优势：数据全程不离开本机、不需要 cloudflared 和 OAuth、支持 agentic 连续工具调用、一次配置永久生效。

Token / 上下文优化策略

多账号轮换：注册 2-3 个 Claude 账号，桌面端 Sign Out 后登录下一个，MCP 配置存本地、切换账号依然生效。

连接后怎么使用

直接输入自然语言即可：

• 看项目结构：「先看看我这个项目有哪些文件」
• 读代码：「读一下 main.py，告诉我这个项目是干什么的」
• 定位报错：「运行 main.py 报错了，报错信息是 xxx，帮我看看」
• 改代码：「把 utils.py 里的 fetch_data 改成用异步请求」
• 补测试：「给 calculator.py 里每个函数写单元测试」
• 重构：「把 config.py 里所有配置项改成从 .env 读取」

使用技巧：先说「读一下 xxx」让 Claude 先了解代码再说怎么改；描述结果而非步骤；贴完整报错信息；一次只做一件事，改完验证再继续。

工具权限建议：读操作设 Auto（自动允许），写/删操作保持 Needs approval（需批准）。

安全提醒

• 不要在暴露的工作目录下存放 .env、私钥、密码文件
• 用完及时关闭 cloudflared 终端
• 凭据不要硬编码在脚本里，不要分享给他人
• 有条件优先使用 Claude 桌面端 + 本地 MCP

结论：把 MCP 接入网页版 Claude 确实能让免费用户获得本地代码编辑能力，但免费额度非常有限——基本两次对话就耗尽 token，适合尝鲜体验，正经干活还是乖乖付费。

背景

小米 MIMO API（api.xiaomimimo.com）提供了一个免费的 AI 对话接口，但它并非标准的 OpenAI 兼容格式——需要先通过 /bootstrap 端点获取 JWT，再用 JWT 调用 /v1/chat/completions。这让绝大多数支持自定义 API 的聊天客户端（如 ChatBox、NextChat、LobeChat 等）无法直接接入。

本文将记录从零搭建 MIMO OpenAI 兼容代理的完整过程，涵盖两种方案：

技术原理

MIMO API 认证流程

┌──────────┐     GET /bootstrap      ┌──────────────┐
│          │ ───────────────────────→ │              │
│  客户端   │ ←─────────────────────── │  MIMO API    │
│          │   { jwt: "xxx.xxx.xxx" } │              │
│          │                          │              │
│          │  POST /v1/chat/completions              │
│          │  Authorization: Bearer xxx              │
│          │  X-Mimo-Source: mimocode-cli-free       │
│          │ ───────────────────────→ │              │
│          │ ←─────────────────────── │              │
│          │   SSE stream response    │              │
└──────────┘                          └──────────────┘

关键点：

1. Bootstrap：无认证，返回 JWT，有效期约 5 分钟
2. Chat：需 Authorization: Bearer {jwt} + X-Mimo-Source: mimocode-cli-free 两个 Header
3. 响应：标准 SSE（Server-Sent Events）流式格式，data: 前缀，最后以 data: [DONE] 结束

代理要做的事

聊天客户端（OpenAI 格式）  →  代理  →  MIMO API

1. 暴露 /v1/models —— 返回可用模型列表
2. 暴露 /v1/chat/completions —— 接收 OpenAI 格式请求
3. 自动管理 JWT：到期前 5 分钟自动刷新
4. 转发请求到 MIMO，透传 SSE 流

方案一：本地 Python Flask 代理

完整代码

创建 mimo-proxy.py：

import time
import requests
from flask import Flask, Response, request, stream_with_context
from flask_cors import CORS

app = Flask(__name__)
CORS(app)

MIMO_BASE = "https://api.xiaomimimo.com/api/free-ai"
_jwt_cache = {"token": None, "expires_at": 0}


def get_jwt():
    """获取 JWT，缓存 5 分钟"""
    now = time.time()
    if _jwt_cache["token"] and now < _jwt_cache["expires_at"]:
        return _jwt_cache["token"]

    resp = requests.get(f"{MIMO_BASE}/bootstrap", timeout=10)
    resp.raise_for_status()
    token = resp.json()["jwt"]
    _jwt_cache["token"] = token
    _jwt_cache["expires_at"] = now + 270  # 4.5 分钟刷新
    return token


@app.route("/v1/models", methods=["GET", "OPTIONS"])
def list_models():
    return {
        "object": "list",
        "data": [{"id": "mimo-v2.5-pro", "object": "model"}],
    }


@app.route("/v1/chat/completions", methods=["POST", "OPTIONS"])
def chat_completions():
    jwt = get_jwt()
    body = request.get_json(force=True)

    headers = {
        "Authorization": f"Bearer {jwt}",
        "X-Mimo-Source": "mimocode-cli-free",
        "Content-Type": "application/json",
    }

    resp = requests.post(
        f"{MIMO_BASE}/v1/chat/completions",
        json=body,
        headers=headers,
        stream=True,
        timeout=120,
    )

    def generate():
        for chunk in resp.iter_content(chunk_size=None):
            if chunk:
                yield chunk

    return Response(
        stream_with_context(generate()),
        content_type="text/event-stream; charset=utf-8",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",
        },
    )


if __name__ == "__main__":
    app.run(host="127.0.0.1", port=8787, threaded=True)

部署步骤

# 安装依赖
pip install flask flask-cors requests

# 启动代理
python mimo-proxy.py

客户端配置

将聊天客户端的 API Base URL 设为：

http://127.0.0.1:8787/v1

API Key 任意填写（代理层不校验），模型选 mimo-v2.5-pro。

CORS 修复

前端页面直连代理时，浏览器会发送 OPTIONS 预检请求。flask-cors 的 CORS(app) 一行即可自动处理所有跨域问题。

如果遇到 “non ISO-8859-1 code point” 错误，那是浏览器 fetch API 层面的限制——请求 Header 值必须为纯 ASCII。排查方向：

• API Key 中是否含中文
• 自定义 Header 中是否含特殊字符
• Base URL 是否正确编码

方案二：Cloudflare Worker 代理

Cloudflare Worker 是一个免费（每天 10 万次请求）的边缘计算平台，适合搭建无需本地常驻的代理服务。

第一版：通用 CORS Worker

最初使用了一个通用 CORS Worker，接收 POST 请求后转发：

// 通用 CORS Worker —— 不推荐
export default {
  async fetch(request) {
    const { url, method, headers, data } = await request.json();
    const resp = await fetch(url, { method, headers, body: data });
    const body = await resp.text();
    return new Response(JSON.stringify({ status: resp.status, body_text: body }), {
      headers: { "Content-Type": "application/json" },
    });
  },
};

前端页面先调用 /bootstrap 获取 JWT，再通过 Worker 调用 /v1/chat/completions。

问题：Bootstrap 成功返回 JWT，但 Chat 请求返回 401 Invalid Token。

根因分析：JWT IP 绑定

请求 1 (bootstrap)： 用户 → CF 边缘节点 A → MIMO API  → JWT (绑定节点 A 的 IP)
请求 2 (chat)：     用户 → CF 边缘节点 B → MIMO API  → 401 (IP 不匹配!)

Cloudflare 采用 Anycast 架构，两次请求可能路由到不同边缘节点，导致出口 IP 不一致。MIMO API 的 JWT 绑定了请求来源 IP，IP 不一致则校验失败。

本地代理不会出现此问题，因为本机 IP 始终一致。

第二版：专用 Worker + 重试机制

思路：将 Bootstrap 和 Chat 放在同一个 Worker 实例内，加入重试逻辑——401 时清除 JWT 缓存 → 重新 Bootstrap → 立即重试 Chat，利用重试落在同一节点的概率。

// mimo-worker.js —— 推荐方案
let _jwt = null;
let _jwtExp = 0;

async function getJwt(forceRefresh = false) {
  const now = Date.now();
  if (!forceRefresh && _jwt && now < _jwtExp) return _jwt;

  const resp = await fetch(`${MIMO_BASE}/bootstrap`);
  const data = await resp.json();
  _jwt = data.jwt;
  _jwtExp = now + 270_000; // 4.5 分钟
  return _jwt;
}

async function chatWithRetry(messages, retries = 2) {
  for (let i = 0; i < retries; i++) {
    const forceRefresh = i > 0;
    const jwt = await getJwt(forceRefresh);

    const resp = await fetch(`${MIMO_BASE}/v1/chat/completions`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${jwt}`,
        "X-Mimo-Source": "mimocode-cli-free",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ model: "mimo-v2.5-pro", messages }),
    });

    if (resp.status === 401 && i < retries - 1) continue;
    return resp;
  }
}

// 暴露 OpenAI 兼容端点
// - GET /v1/models → 返回模型列表
// - POST /v1/chat/completions → 代理到 MIMO

部署到 Cloudflare

# 安装 Wrangler CLI
npm install -g wrangler

# 登录
wrangler login

# 创建 Worker
wrangler init mimo-proxy

# 部署
wrangler deploy

部署后获得 Worker URL，例如 https://mimo.xxx.workers.dev，客户端配置：

API Base URL: https://mimo.xxx.workers.dev/v1

重试机制的有效性

重试不是 100% 可靠的解决方案，但在实践中：

如果两次重试仍失败，Worker 返回 401，前端可提示用户重试。这只是概率问题，多试几次通常能通过。

进一步优化方向

1. Scheduled Trigger：用 Cron Trigger 定时预热 JWT，减少首次请求延迟
2. KV 持久化：将 JWT 存入 Cloudflare KV，跨 Worker 实例共享（但无法解决核心 IP 绑定问题）
3. Durable Objects：用 DO 保证 Bootstrap 和 Chat 在同一实例内执行，从根本上解决 IP 一致性问题
4. 回退到本地代理：最稳妥的方案，本机 IP 始终一致

方案对比与选择

结论：个人使用推荐本地代理，简单可靠；多人共享或希望在手机上使用推荐 Worker 方案。

附录：完整文件清单

所有代码均为 MIT 协议，可自由修改使用。

零成本 Agent 工作流实战：Multica + OpenCode + Codespaces + LongCat 全流程部署指南

把”任务丢进 Issue，Agent 自动写代码”做成日常工作流，全程零成本。

这不是 demo，是一套你今天就能搭起来、明天就能开始干活的真实流水线。

目录

• 一、这套方案到底在做什么
• 二、四个组件各自扮演的角色
• 三、前置准备清单
• 四、详细部署步骤
  • Step 1：申请 LongCat API Key
  • Step 2：注册 Multica 并获取 Token
  • Step 3：准备一个 GitHub 仓库
  • Step 4：配置 Codespaces Secrets
  • Step 5：编写 devcontainer.json
  • Step 6：编写 install.sh（首次安装脚本）
  • Step 7：编写 OpenCode 的 Provider 配置
  • Step 8：编写 start.sh（每次启动脚本）
  • Step 9：启动 Codespace 并验证
  • Step 10：在 Multica 创建 Agent 并跑通第一个任务
• 五、获得更好 Agent 体验的进阶技巧
• 六、流量走向与历史记录管控
• 七、常见故障排查
• 八、心得体会与白嫖经验

一、这套方案到底在做什么

如果你用过 Cursor、Claude Code 之类的 AI 编程工具，应该有过这种感受：每次打开都要重新解释项目背景，多个任务并行就管不过来，跑过的经验也沉淀不下来。这套方案要解决的就是这个问题——把 AI 编程 Agent 装进一个真正像”团队成员”的协作环境里：

• 你像分配同事一样在看板上给 Agent 派活；
• Agent 自己读代码、改代码、跑命令，过程实时可见；
• 任务完成或卡住，Agent 主动汇报进展；
• 整套环境跑在云端，你关掉浏览器它也在跑。

而且——全程不花钱。

最终效果大概是这样的工作流：

你在 Multica Web 端写一条 Issue 「给 user 模块加单元测试」
        │
        ▼
Multica 把任务推给云端 Codespace 里的 daemon
        │
        ▼
daemon 调起 OpenCode CLI，加载项目代码
        │
        ▼
OpenCode 通过 LongCat API 思考、生成代码、跑 pytest
        │
        ▼
执行日志实时回传到 Multica 看板，最终产出 PR

二、四个组件各自扮演的角色

理解每个组件的职责，后面调试出问题时才知道该看哪一层。

Multica（任务管理 + 协作前台）

开源的 Managed Agents 平台，定位是”AI 编程团队的项目管理系统”。它提供 Web 看板、Issue、Agent 资料卡、运行时管理等能力，你和 Agent 在同一个界面里协作。本身不执行代码，只是把任务调度给你的本地（或 Codespace 里的）daemon。

OpenCode（实际干活的 Agent）

终端里的开源 AI 编码 Agent，支持任意 OpenAI 兼容的 LLM。它负责真正读代码、改代码、跑测试。Multica 把它当作一种 “runtime” 来调用。

LongCat API（模型算力）

美团开源的 LongCat 系列大模型对应的 API 平台，提供 OpenAI 兼容的接口和每日数千万 Token 级的免费额度。其中 LongCat-Flash-Thinking-2601 是开源 SOTA 级别的推理/Agent 模型，工具调用能力很强。

GitHub Codespaces（运行环境）

云端 Linux 容器，每个 GitHub 个人账号每月有 120 core-hours 免费额度（对应 2 核机型每月约 60 小时使用时长）。我们把 Multica daemon 和 OpenCode CLI 都跑在里面，你的本地电脑不需要装任何东西。

整体架构

flowchart LR
    A[人类用户] -->|创建 Issue| B[Multica
任务管理层]
    B -->|分发任务| C[OpenCode Agent
执行层]
    C -->|API 调用| D[LongCat API
模型算力层]
    C -->|读写代码| E[GitHub Codespaces
运行环境层]
    E -.->|宿主| B
    E -.->|宿主| C
    C -->|状态/日志回写| B

三、前置准备清单

正式开搞前确认以下账号都准备好。每一项后面括号里写了为什么要它，方便你判断是否能省略。

四、详细部署步骤

接下来每一步我都会写到”你应该看到什么”的级别。如果某一步的实际输出和文档里描述的不一样，先停下来排查，不要继续往下走。

Step 1：申请 LongCat API Key

1.1 注册并登录平台

访问 longcat.chat/platform，用手机号或邮箱注册一个账号。登录后进入控制台。

1.2 创建 API Key

在左侧菜单找到「API Keys」或「密钥管理」，点击「创建新密钥」。

• 名字随便起，比如 codespace-agent；
• 创建后会弹出一串以 ak_ 开头的字符串（具体前缀以平台为准）；
• 这个 Key 只会完整显示一次，立刻复制保存到密码管理器，关掉弹窗就再也看不到完整值。

1.3 记录关键信息

把以下三项信息记下来，后面 Step 7 要用：

API Key:    sk-xxxxxxxxxxxxxxxxxxxx       (你刚拿到的)
Base URL:   https://api.longcat.chat/openai/v1
模型名:     LongCat-Flash-Chat            (轻量任务用)
            LongCat-Flash-Thinking-2601   (复杂推理/Agent 任务用,推荐默认)

1.4 验证 Key 可用（可选但建议）

打开任何一台能联网的电脑，跑下面这条 curl，确认 Key 没拿错：

curl https://api.longcat.chat/openai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_LONGCAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "LongCat-Flash-Chat",
    "messages": [{"role": "user", "content": "你好"}]
  }'

如果返回了一段 JSON 且里面有 "role":"assistant" 字段，说明 Key 可用。如果返回 401，说明 Key 错了或者粘贴时多带了空格；返回 429 说明额度用完，等到第二天 0 点重置。

Step 2：注册 Multica 并获取 Token

2.1 注册账号

访问 multica.ai，点 Sign Up，用邮箱或 GitHub OAuth 登录都可以。

2.2 创建 Workspace

第一次登录会引导你创建一个 Workspace。Workspace 是 Multica 的隔离单元——每个 Workspace 有独立的 Issue、Agent、Runtime。给它起个名字，比如 solo-lab。

2.3 生成 Personal Access Token (PAT)

进入 Settings → Personal Access Tokens → New Token：

• Name：codespace-bootstrap；
• 创建后会得到一串以 mul_ 开头的 token；
• 同样只显示一次，立刻保存。

关于 Token 的安全选择：Multica 实际上有三种 Token——浏览器 cookie、PAT (mul_) 和 daemon token (mdt_)。PAT 可以访问你所有的 Workspace，daemon token 只绑定到单个 Workspace。出于最小权限原则，生产环境建议在 Multica Web 端生成专门的 daemon token 给 Codespace 使用（Workspace Settings → Daemon Tokens）。本教程为了简化流程先用 PAT，跑通后建议换成 daemon token。

Step 3：准备一个 GitHub 仓库

这个仓库扮演两个角色：

1. 它是 Codespace 的”宿主”——Codespace 必须从某个仓库启动；
2. 它也是 Agent 实际操作的代码库（你想让 Agent 帮你改的项目）。

如果你已有项目就用现成的；没有的话新建一个空仓库 agent-playground 即可。仓库可以是 Private，Codespaces Secrets 只对 owner 可见，不会泄露。

在仓库根目录创建一个 .devcontainer/ 文件夹，后面所有配置文件都放这里。

agent-playground/
├── .devcontainer/
│   ├── devcontainer.json
│   ├── install.sh
│   └── start.sh
├── .gitignore
└── README.md

Step 4：配置 Codespaces Secrets

Codespaces Secrets 是 GitHub 帮你管理敏感环境变量的机制，不会被写进仓库、不会随 fork 流出，但会被注入到容器的环境变量里。

4.1 进入设置页

访问 github.com/settings/codespaces（个人级别 Secrets，对你所有仓库可用）。

也可以用仓库级别 Secrets：进入仓库 Settings → Secrets and variables → Codespaces。个人级别更方便，仓库级别更隔离，自己看着选。

4.2 添加两个 Secret

点击 New secret，依次添加：

第一个：

• Name: LONGCAT_API_KEY
• Value: Step 1 拿到的 LongCat API Key
• Repository access: 选你刚创建的 agent-playground 仓库

第二个：

• Name: MULTICA_TOKEN
• Value: Step 2 拿到的 Multica PAT（mul_ 开头）
• Repository access: 同上

⚠️ Codespaces Secrets 名字大小写不敏感，统一用全大写命名最稳妥。

Step 5：编写 devcontainer.json

这是 Codespace 的”出厂配置”。把下面内容保存为 .devcontainer/devcontainer.json：

{
  "name": "multica-opencode-agent",
  "image": "mcr.microsoft.com/devcontainers/universal:latest",

  // 安装常用语言运行时(按你项目需要增减)
  "features": {
    "ghcr.io/devcontainers/features/node:1": {},
    "ghcr.io/devcontainers/features/python:1": {},
  },

  // 声明这个仓库需要的 Secrets。即便你已经在 Step 4 配过,
  // 这里再声明一次会让其他用户 fork 时收到提示
  "secrets": {
    "LONGCAT_API_KEY": {
      "description": "LongCat API Key, 在 longcat.chat/platform 申请",
    },
    "MULTICA_TOKEN": {
      "description": "Multica PAT 或 Daemon Token, 在 Multica Settings 生成",
    },
  },

  // 容器首次创建时执行(只跑一次)
  "postCreateCommand": "bash .devcontainer/install.sh",

  // 每次容器启动时执行(stop/resume 后也会跑)
  "postStartCommand": "bash .devcontainer/start.sh",

  // 让 secrets 在容器里以同名环境变量暴露
  "remoteEnv": {
    "LONGCAT_API_KEY": "${localEnv:LONGCAT_API_KEY}",
    "MULTICA_TOKEN": "${localEnv:MULTICA_TOKEN}",
  },
}

关键字段拆解

• image: 用 GitHub 官方维护的 universal 镜像，自带常见工具链。也可以换成更精简的 debian 镜像，但需要自己装更多依赖。
• features: 声明式安装额外工具。node 是因为 OpenCode 的 npm 安装路径需要它（即便你不用 npm 装 OpenCode，留着也无害）。
• secrets: 是给 fork 你这份配置的人看的提示，本身不存值，值还是从 Step 4 配的 Secrets 来。
• postCreateCommand vs postStartCommand: 前者只在容器首次创建时跑（装东西），后者每次 Codespace 唤醒都跑（拉服务）。这个区分非常重要，否则每次唤醒都重新装一遍 OpenCode 会很慢。
• remoteEnv + ${localEnv:XXX}: 这是 Codespaces 注入 Secret 的标准写法。localEnv 在 Codespaces 上下文中实际指向”宿主环境”，也就是 Codespaces 的 Secret 注入点。

Step 6：编写 install.sh（首次安装脚本）

把下面内容保存为 .devcontainer/install.sh，并确保有执行权限（用 git 提交时若发现没权限，跑一下 chmod +x .devcontainer/install.sh）。

#!/usr/bin/env bash
set -euo pipefail

echo "== 首次安装：OpenCode + Multica CLI =="

# ---------- 安装 OpenCode ----------
echo "[1/2] Installing OpenCode..."
curl -fsSL https://opencode.ai/install | bash
# 官方安装脚本会把二进制放到 ~/.opencode/bin/opencode
# 把它加到当前 shell 的 PATH (start.sh 会再处理一次持久化)
export PATH="$HOME/.opencode/bin:$PATH"
opencode --version

# ---------- 安装 Multica CLI ----------
echo "[2/2] Installing Multica CLI..."
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
multica version

echo "== 首次安装完成 =="

这一步的注意点

1. set -euo pipefail 让脚本任一步出错都立即退出，避免装一半留下半截环境。
2. OpenCode 官方安装脚本会写入 ~/.bashrc 让 PATH 生效，但当前这次脚本执行的 shell 不会自动 reload，所以我们手动 export 一次。
3. 这个脚本只在 postCreateCommand 阶段跑一次，对应 Codespace 首次创建或重建的时机。日常 stop/resume 不会重跑。

Step 7：编写 OpenCode 的 Provider 配置

让 OpenCode 知道 LongCat 在哪、用哪个模型。我们不在 install.sh 里写死 API Key，而是用变量替换语法 {env:VAR_NAME}，这样 Key 永远只活在环境变量里、不落到磁盘。

在仓库根目录新建 opencode.json（注意：这是项目级配置，OpenCode 会自动读取项目根目录下的同名文件）：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "longcat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LongCat (Meituan)",
      "options": {
        "baseURL": "https://api.longcat.chat/openai/v1",
        "apiKey": "{env:LONGCAT_API_KEY}"
      },
      "models": {
        "LongCat-Flash-Chat": {
          "name": "LongCat Chat (轻量,日常对话)",
          "limit": { "context": 128000, "output": 8192 }
        },
        "LongCat-Flash-Thinking-2601": {
          "name": "LongCat Thinking 2601 (推理/Agent,推荐)",
          "limit": { "context": 128000, "output": 8192 }
        }
      }
    }
  },
  "model": "longcat/LongCat-Flash-Thinking-2601",
  "autoupdate": false
}

字段拆解

• npm: "@ai-sdk/openai-compatible": 关键。LongCat 走 OpenAI 兼容协议（/v1/chat/completions），所以用这个适配器。如果用了错误的 npm 包（比如 @ai-sdk/openai），会报一些奇怪的 endpoint not found 错误。
• apiKey: "{env:LONGCAT_API_KEY}": OpenCode 的环境变量替换语法。容器启动时 LONGCAT_API_KEY 已经被 Codespaces Secrets 注入，这里直接读。不要手写明文 Key，否则提交后会泄露。
• model: "longcat/LongCat-Flash-Thinking-2601": 默认模型，格式是 <provider 名>/<模型名>。
• limit: 告诉 OpenCode 上下文窗口大小，方便它做自动压缩判断。LongCat 实际窗口以官方文档为准，128k 是较保险的设置。

验证语法

提交前可以本地用 jq 校验一下 JSON 合法性：

cat opencode.json | jq .

能正常输出说明 JSON 没问题。

Step 8：编写 start.sh（每次启动脚本）

这是真正每次唤醒 Codespace 都会跑的脚本，把上一篇我们已经做过深度打磨的版本放进来，并补全注释：

#!/usr/bin/env bash
set -u

echo "== Codespaces Agent Startup =="
echo

# ---------- [1/7] Reload shell config ----------
echo "[1/7] Loading shell config..."
if [ -f "$HOME/.bashrc" ]; then
  # shellcheck disable=SC1090
  source "$HOME/.bashrc"
fi

# ---------- [2/7] Locate OpenCode ----------
# 双重查找:先看 PATH,再 fallback 到默认安装目录
echo "[2/7] Checking OpenCode..."
OPENCODE_BIN="$(command -v opencode || true)"
if [ -z "$OPENCODE_BIN" ] && [ -x "$HOME/.opencode/bin/opencode" ]; then
  export PATH="$HOME/.opencode/bin:$PATH"
  OPENCODE_BIN="$HOME/.opencode/bin/opencode"
fi
if [ -z "$OPENCODE_BIN" ]; then
  echo "ERROR: opencode not found."
  echo "Reinstall via: curl -fsSL https://opencode.ai/install | bash"
  exit 1
fi
echo "OpenCode found: $OPENCODE_BIN"
"$OPENCODE_BIN" --version || true
echo

# ---------- [3/7] Sanity check API key ----------
echo "[3/7] Verifying LongCat API key is injected..."
if [ -z "${LONGCAT_API_KEY:-}" ]; then
  echo "WARN: LONGCAT_API_KEY 未设置。OpenCode 配置将无法解析 apiKey。"
  echo "请到 GitHub Settings → Codespaces → Secrets 添加 LONGCAT_API_KEY 并重启 Codespace。"
else
  echo "LONGCAT_API_KEY is set (length=${#LONGCAT_API_KEY})."
fi
echo

# ---------- [4/7] Locate Multica CLI ----------
echo "[4/7] Checking Multica CLI..."
MULTICA_BIN="$(command -v multica || true)"
if [ -z "$MULTICA_BIN" ]; then
  echo "ERROR: multica not found. Re-run install.sh or rebuild container."
  exit 1
fi
echo "Multica found: $MULTICA_BIN"
multica version || true
echo

# ---------- [5/7] Tell Multica where OpenCode lives ----------
# 显式告诉 daemon 该用哪个 opencode 二进制,避免 PATH 漂移
echo "[5/7] Exporting MULTICA_OPENCODE_PATH..."
export MULTICA_OPENCODE_PATH="$OPENCODE_BIN"
echo "MULTICA_OPENCODE_PATH=$MULTICA_OPENCODE_PATH"
echo

# ---------- [6/7] Authenticate Multica ----------
echo "[6/7] Checking Multica authentication..."
AUTH_TMP="$(mktemp)"
trap 'rm -f "$AUTH_TMP"' EXIT
if ! multica auth status >"$AUTH_TMP" 2>&1; then
  cat "$AUTH_TMP"
  echo
  if [ -n "${MULTICA_TOKEN:-}" ]; then
    echo "Detected MULTICA_TOKEN, attempting non-interactive login..."
    if multica login --token="$MULTICA_TOKEN"; then
      echo "Login succeeded."
    else
      echo "ERROR: Login failed. Check that MULTICA_TOKEN is valid."
      exit 1
    fi
  else
    echo "ERROR: Not authenticated and MULTICA_TOKEN not set."
    echo "Run manually: multica login --token=<YOUR_TOKEN>"
    exit 1
  fi
fi
multica auth status
echo

# ---------- [7/7] Start daemon ----------
echo "[7/7] Starting Multica daemon..."
if pgrep -f "multica daemon" >/dev/null 2>&1; then
  echo "Daemon process already running (pgrep hit)."
elif multica daemon status 2>/dev/null | grep -qi "running"; then
  echo "Daemon reported as running."
else
  multica daemon start
fi

# 轮询等待 daemon 就绪 (最多 10s)
for _ in $(seq 1 10); do
  if multica daemon status 2>/dev/null | grep -qi "running"; then
    break
  fi
  sleep 1
done

echo
echo "Final daemon status:"
multica daemon status || true

echo
echo "Done. Codespaces agent runtime is ready."
echo "→ 打开 multica.ai → Settings → Runtimes,应能看到本 Codespace 在线。"

这个脚本的几个关键设计

• set -u 而不是 set -e：脚本里有大量”找不到也无所谓”的探测命令（比如初次 multica daemon status），用 -e 会一打就退；用 -u 保留”未定义变量报错”的严谨性，配合 || true 和显式 if 控制流程。
• OpenCode 二段查找：先走 PATH，再 fallback 到默认安装目录，应对 shell 还没 reload 的场景。
• MULTICA_OPENCODE_PATH 显式注入：Multica daemon 默认扫 PATH 找 Agent CLI，但 Codespaces 的 PATH 经常因为 nvm/bun/pnpm 之类 shim 漂移，给 daemon 喂绝对路径最稳。
• pgrep + status grep 双重判定：避免 stop/resume 重启 daemon 时叠加进程。
• 就绪轮询：daemon start 是异步的，紧跟 status 容易拿到 “starting”，看着像挂了其实是慢半秒。

Step 9：启动 Codespace 并验证

9.1 提交代码

git add .devcontainer/ opencode.json
git commit -m "Setup Multica + OpenCode + LongCat agent workflow"
git push

9.2 创建 Codespace

回到仓库主页，点击右上角绿色 Code 按钮 → Codespaces 标签 → Create codespace on main。

第一次创建会需要 2-5 分钟（拉镜像 + 跑 install.sh）。期间可以看到 VS Code 网页版加载，底部会有日志窗显示 postCreateCommand 的输出。

9.3 验证安装成功

容器起来后，在 VS Code 终端（Terminal → New Terminal 或快捷键 Ctrl+`）里依次跑：

opencode --version       # 应该输出版本号
multica version          # 应该输出版本号
multica daemon status    # 应该显示 running,带 PID 和已检测到的 agent 列表
echo $LONGCAT_API_KEY    # 应该输出你的 Key 前几位 (会完整显示,所以确认后立即清屏)

如果四条命令都正常，恭喜，Codespace 这边已经就绪。

9.4 在 Multica Web 端验证 Runtime 上线

打开 multica.ai → 进入你的 Workspace → Settings → Runtimes。

你应该看到一个新的 Runtime 出现，名字大概是 <your-username>-<repo>-<hash>，状态是绿色的 online，并且 Detected agents 列表里有 opencode。

如果没看到：

1. 回 Codespace 终端跑 multica daemon logs -f 看日志；
2. 检查 multica auth status 输出的 server URL 和 user 是否正确；
3. 确认你登录 Multica Web 端的账号和 PAT 对应的账号是同一个。

Step 10：在 Multica 创建 Agent 并跑通第一个任务

10.1 创建 Agent

在 Multica Web 端：

1. 进入你的 Workspace；
2. 左侧菜单点 Agents → New Agent；
3. 填写信息：
   • Name: 给 Agent 起个名字，比如 Cody；
   • Avatar: 随便选或上传一张图（可选）；
   • CLI: 选 opencode；
   • Runtime: 选 Step 9.4 里看到的那个 Codespace runtime；
   • Working directory: 填 Codespace 中你想让 Agent 操作的目录，通常是 /workspaces/<your-repo>；
   • System prompt (可选): 写一段角色设定，比如 “你是一名严谨的 Python 工程师，遵循 PEP8，所有改动需要附带单元测试。”；
4. 保存。

10.2 创建第一个 Issue

回到 Workspace 主页，点 Issues → New Issue：

• Title: 给 README 增加英文版本
• Description:

  请阅读项目根目录的 README.md,按相同结构生成 README.en.md。
  要求:
  1. 保留所有代码块,只翻译说明文字
  2. 在文末加一行 "Translated by Cody"
  3. 完成后用 git diff 总结改动并写在评论里
  

• Assignee: 选 Cody；
• 提交。

10.3 观察执行过程

Issue 提交后几秒内，你会看到：

1. Issue 状态从 Backlog 变为 In Progress；
2. Issue 详情页右侧会出现 实时日志流，显示 OpenCode 的思考、工具调用、文件读写过程；
3. 大约 1-3 分钟后（取决于模型响应速度）任务完成，状态变为 Done，Cody 会在评论区贴出 git diff 总结。

10.4 在 Codespace 里验证产物

回到 Codespace 的终端，跑 git status 和 cat README.en.md，能看到 Cody 实际生成的文件。如果你想保留这次改动，正常 git add → commit → push 就行。

至此，整套白嫖工作流已全部跑通。后续日常使用就是「在 Multica 写 Issue → 等结果」这一个动作。

五、获得更好 Agent 体验的进阶技巧

跑通只是开始。下面这些技巧会显著拉高 Agent 的稳定性和产出质量。

5.1 写一份高质量的 AGENTS.md

OpenCode 启动时会自动读取项目根目录的 AGENTS.md 作为上下文。这份文件相当于给 Agent 的”员工手册”——把项目结构、技术栈、编码规范、常用命令都写进去，能极大减少 Agent 的探索成本。

在 Codespace 终端跑 opencode 进入 TUI，输入 /init，OpenCode 会自动分析你的项目并生成一份初稿，再手动补充即可。建议至少写清楚：

# AGENTS.md

## 项目概览

这是一个 ... (一两句话)

## 技术栈

- 语言: Python 3.11
- 框架: FastAPI
- 测试: pytest
- 包管理: uv

## 目录结构

- `src/`: 业务代码
- `tests/`: 单元测试,与 src 镜像
- `scripts/`: 一次性脚本,不进 PR

## 编码规范

- 所有函数必须有 type hints
- 公开函数必须有 docstring
- 禁止使用 print,统一用 logging

## 常用命令

- 跑测试: `uv run pytest`
- 启动开发服务: `uv run uvicorn src.main:app --reload`
- 格式化: `uv run ruff format`

## Agent 工作流约束

- 任何代码改动必须跟单元测试
- 完成后用 git diff 总结改动
- 涉及依赖变更必须先在评论区说明原因

提交 AGENTS.md 到仓库，所有 Agent 实例都会受益。

5.2 模型选择策略

LongCat 提供多个模型，不要无脑用最强的：

可以在 Multica 创建多个 Agent，每个绑定不同的默认模型，分配任务时按需选 Agent。也可以在 OpenCode TUI 里用 /model 命令临时切换。

5.3 用 Skills 沉淀经验

Multica 的 Skills 系统是这套工作流真正的复利所在。每完成一个非平凡的任务，把过程沉淀成 Skill：

例如「部署到 staging 环境」「数据库迁移」「跑端到端测试」这类流程，写成 Skill 后下次一句话就能调用。Skill 内容大致结构：

# Skill: 添加单元测试

## 触发条件

当 Issue 标题或描述包含 "加单元测试"、"补测试" 时使用此 Skill

## 步骤

1. 读取目标模块代码,识别公开函数
2. 在 tests/ 目录下找到对应文件,如不存在则创建
3. 为每个公开函数生成至少 3 个测试用例: 正常、边界、异常
4. 用 mock 隔离外部依赖
5. 跑 pytest 确认全部通过
6. 评论区贴出测试覆盖率

随着用得越多，Skills 库越丰富，Agent 的”团队默契”也就越强。

5.4 Issue 模板

写得好的 Issue 是让 Agent 高质量完成任务的最重要因素。一个好的 Issue 模板：

## 背景

(为什么要做这件事,业务背景或上游需求)

## 目标

(具体要实现的能力,用户视角)

## 验收标准

- [ ] 标准 1
- [ ] 标准 2
- [ ] 所有相关测试通过

## 约束

- 不要修改 xxx 模块
- 必须保持 API 向后兼容
- 涉及性能的改动需要附 benchmark

## 参考

- 相关代码: src/foo.py
- 相关 Issue: #123

把这个模板存到 Multica 的 Issue Templates，每次新建 Issue 自动加载，强制自己（也强制 Agent）思考清楚再动手。

5.5 让 Agent 走 PR 流程而不是直接 push

在 Agent 的 system prompt 里加一句：

所有代码改动必须创建新分支并提 PR，不要直接 push 到 main。

这样 Agent 跑完会留下一个待 review 的 PR，你扫一眼合并即可，避免它把 main 改坏。

5.6 防止上下文打满

LongCat 的 128k 上下文虽然够用，但跑长任务还是会有打满的风险。在 opencode.json 里启用自动压缩：

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

这会在上下文接近上限时自动总结早期对话，腾出空间。

六、流量走向与历史记录管控

这是很多教程不提但实际用起来很重要的一块。你需要清楚每个字节流向哪里、留在哪里、谁能看到。

6.1 数据流向全景图

你的输入 (Issue 内容)
   │
   ▼
Multica Cloud (multica.ai) ← 任务元数据存这里,服务端 PostgreSQL
   │
   ▼ (WebSocket)
Codespace 容器 ← 代码、临时文件、git 操作都在这里
   │
   ▼ (HTTPS)
LongCat API (api.longcat.chat) ← 你的 prompt + 代码片段会发到这里做推理
   │
   ▼ (响应)
返回 OpenCode → 写回项目文件 + 回传日志给 Multica

6.2 各处存了什么、保留多久

6.3 把 LongCat 流量监控起来

LongCat 平台有用量页面，建议每天看一眼，避免某个跑飞的任务把额度打光。可以在 Codespace 里加个 cron 自动拉用量：

# 加在 start.sh 末尾
(crontab -l 2>/dev/null; echo "0 * * * * curl -s https://api.longcat.chat/openai/v1/usage -H 'Authorization: Bearer $LONGCAT_API_KEY' >> ~/.longcat-usage.log") | crontab -

（实际 endpoint 以 LongCat 文档为准）

6.4 历史记录的导出与归档

OpenCode 自带会话导出能力：

# 列出所有会话
opencode session list

# 导出指定会话为 JSON
opencode export <session-id> > session-2026-05-28.json

# 之后想复盘时再 import
opencode import session-2026-05-28.json

Multica 这一侧，每个 Issue 的执行轨迹都留在评论区。需要长期归档的话，可以用 Multica CLI 批量拉取：

multica issue list --output json > issues-snapshot.json

把它定期 push 到一个私有的归档仓库，相当于给 Agent 历史做了版本控制。

6.5 敏感信息防泄露三原则

1. 永远不要把密钥写进文件，只走环境变量；
2. Agent 的 system prompt 里禁止它读 .env、secrets/、*.pem 之类的文件：

   你不得读取或在输出中复述任何 .env 文件、密钥文件、证书文件的内容。
   如果任务需要这类信息,请在评论区请求人类提供。
   

3. 代码 push 前用 git secret 扫一道，比如 gitleaks：

   gitleaks detect --source . -v
   

6.6 当不想让 Agent 看到某个文件

OpenCode 默认遵守 .gitignore，但还可以加一份 .opencodeignore（语法同 gitignore）做更严格的隔离：

.env
.env.*
secrets/
*.key
*.pem
prod-config/

七、常见故障排查

按”现象 → 原因 → 解决”的格式整理，遇到问题时直接对号入座。

7.1 Codespace 启动后 daemon 显示 offline

可能原因：

• MULTICA_TOKEN 没注入或者过期；
• daemon 进程被 OOM 杀了；
• Multica 服务端临时抖动。

排查步骤：

# 1. 看日志
multica daemon logs --tail 100

# 2. 检查环境变量
echo "${MULTICA_TOKEN:0:8}..."   # 只显示前 8 位,确认有值

# 3. 检查认证
multica auth status

# 4. 强制重启
multica daemon stop
multica daemon start --foreground   # 前台跑,看实时输出

7.2 Issue 卡在 Pending 不动

可能原因：

• Multica Web 端选的 Agent 绑定的 runtime 不在线；
• Working directory 配错了，Codespace 里没那个路径；
• Codespace 进入 idle 休眠了。

排查：

• 在 Multica Web 端 Settings → Runtimes 确认对应 runtime 是绿点；
• 在 Codespace 跑 ls /workspaces/，确认 working directory 真实存在；
• 如果 Codespace 已休眠，回 GitHub 把它 resume。

7.3 OpenCode 报 “Provider longcat not configured”

可能原因：

• opencode.json 没在项目根目录（OpenCode 只读 cwd 同名文件，或全局 ~/.config/opencode/opencode.json）；
• JSON 语法错误（少了逗号、多了注释）；
• 启动 OpenCode 时 cwd 不对。

排查：

cat opencode.json | jq .            # 验证 JSON
cd /workspaces/<your-repo>          # 确保在仓库根
opencode --print-logs --log-level DEBUG

7.4 LongCat API 返回 429

可能原因：

• 当日 Token 配额用完；
• 短时间高并发请求被限流。

解决：

• 看 LongCat 平台的用量页；
• 如果是高并发限流，在 OpenCode 配置加重试/退避；
• 切换到消耗更低的 LongCat-Flash-Chat 模型撑过当天。

7.5 Codespace 配额告警

GitHub 个人账号每月 120 core-hours，2 核机型约 60 小时。如果经常不够用：

• 关停不用的 Codespace：gh codespace list 看哪些还在跑，gh codespace stop -c <name> 立即停；
• 设置自动空闲超时：Settings → Codespaces → Default idle timeout 调到 30 分钟；
• 改用 Pro 账户或学生认证：学生包额度翻几倍，Pro 也更宽松；
• 改自托管 daemon：把 daemon 跑在自己的 NAS 或者 VPS，Codespace 只在需要交互编辑时开。

7.6 Agent 改坏了代码

预防：

• Agent 走分支 + PR 流程（见 5.5）；
• 关键文件加到 .opencodeignore；
• 定期 push 到远端仓库做兜底。

事后：

# 看最近一次 Agent 改了啥
git diff HEAD~1

# 整体回滚
git reset --hard HEAD~1

# 选择性回滚某个文件
git checkout HEAD~1 -- path/to/file

八、心得体会与白嫖经验

跑通了之后再回头看这套方案，几个体会想分享一下。

8.1 这套组合的”优雅”在于解耦，不在于免费

很多人看到这套方案的第一反应是”哇全免费”，但其实真正值得抄走的不是免费，而是架构本身的可替换性。这套链路的四层每一层都有清晰的接口：

• 任务管理层（Multica）通过开放的 daemon 协议对接执行层；
• 执行层（OpenCode）通过 OpenAI 兼容协议对接模型层；
• 模型层（LongCat）通过 HTTPS 标准接口对外；
• 运行环境层（Codespaces）通过标准 Linux 容器对外。

这意味着：哪天 LongCat 收费了，把 baseURL 换成 DeepSeek、Kimi、智谱、火山引擎任何一家，配置改两行就能切；哪天 Codespaces 配额收紧，换成本地 Docker 或者一台 5 美元的 VPS，daemon 协议不变；哪天 Multica 不香了，OpenCode 单独跑也是个完整的 Agent。

白嫖只是当下的副作用，架构上的解耦才是长期价值。

8.2 三家厂商各自在补贴什么

理解补贴的来源，才能判断它能持续多久：

• GitHub Codespaces 的免费额度本质是微软推给开发者的入口补贴。底层是 Azure 算力，按需算每小时约 0.18 美元，但 GitHub 把”每月 120 core-hours”作为开发者拉新留存的钩子。这是一份基础设施期权，只要微软还在乎开发者心智，它就稳。
• Multica 的免费来自开源 + 自托管的产品策略。它走”内部使用免费、SaaS 商业化收费”的修改版 Apache 2.0 路线，对个人和小团队完全开放——本身就是它的获客和验证渠道。
• LongCat 免费 API 是大厂模型竞赛的”客户教育期”产物。美团从 2025 年 9 月开放平台开始就一直维持高额免费额度，目的是在 DeepSeek、通义、Kimi 把开发者心智吃掉前抢市场。Thinking-2601 在工具调用基准上拿过开源第一，用免费策略把开发者拉进生态是当前最优解。

这三层补贴的逻辑是完全独立的——不会因为同一个事件同时崩掉。任意一层涨价，其他三层都还在，迁移成本可控。

8.3 OpenCode 是关键的”中立粘合剂”

四个组件里，OpenCode 是唯一不”补贴”的角色。它本身完全开源、不卖模型、不卖云、只做粘合。正因为它中立，所以可以把 LongCat 这种 OpenAI 兼容的国产 API 无缝接进来，不被任何一家厂商的客户端绑死。

如果你今天直接用某家大厂的官方客户端（比如 Cursor、Windsurf），看似省事，但实际是把整个工作流绑在那家公司的产品决策上——它涨价你只能跟着涨，它砍功能你只能跟着砍。OpenCode 这种中立 CLI 是这套架构的稳定器。

8.4 真正的 ROI 不是省下的 API 费用

很多人会算：跑这套方案一个月省了多少 Cursor 订阅费、多少 API 充值费。其实这个账算得很狭窄。

真正的 ROI 在于：Skills 库随时间累积带来的复利。每一个 Issue 跑完都沉淀一份”团队记忆”，第二次类似任务 Agent 就不用从零探索；半年下来，你的 Skills 库会变成一份只属于你这个项目/团队的”私有知识资产”。这份资产和具体的模型、客户端、云厂商都无关——切换底层组件时它都跟着你走。

省下的 API 费是一次性收益，沉淀的 Skills 是持续复利。后者才是真正值得花时间打磨的东西。

8.5 这套方案的局限要承认

不能光夸,几个真实的痛点也要说清楚:

第一,Codespaces 60 小时/月的天花板对重度使用者还是紧。如果你打算让 Agent 跑日级别的长任务(比如批量重构整个仓库),60 小时很快就用完。这时候就该考虑把 daemon 迁到自己的家用 NAS 或者一台便宜 VPS,Codespace 只在交互编辑时开。

第二,Multica 的多人协作还有粗糙之处。所有 Agent 提交都用 Codespace 容器里那一份 SSH key,提交人都是同一个身份;多人同时改同一仓库时容易冲突。目前的解法是给每个 Agent 在 AGENTS.md 里写明 git 身份 + 强制 PR 流程,不是无痛方案。如果你团队超过 3-5 人,可能要等 Multica 这块继续迭代,或者考虑商用方案。

第三,免费模型的稳定性有波动。LongCat 偶尔会有限流和延迟尖刺,在赶时间的场景里不如付费的 Claude/GPT 那么稳。建议关键任务双模型兜底：在 OpenCode 里同时配 LongCat 和一个备用 provider(比如 DeepSeek 或者 Kimi 的免费额度),LongCat 卡住时手动 /model 切换。

第四,Codespace 进入 idle 后 daemon 会断。中长任务跑到一半被休眠,Issue 会卡在 “In Progress” 直到下次手动唤醒。临时缓解办法是在 start.sh 里加一个心跳脚本(每 10 分钟 touch 一个文件),把 idle timeout 调到 4 小时上限;长期方案还是把 daemon 搬到不会休眠的环境。

8.6 写给打算跟进的人：三个不同的「野心档位」

最后给三种不同需求的人各推荐一种用法:

档位一：个人玩具。完全照本教程,Codespaces + Multica Cloud + LongCat 免费额度,用来做 side project、写博客、整理笔记、维护几个小工具。一个月零成本,Agent 体验已经远超大多数订阅制工具。

档位二：小团队生产力。在档位一基础上,Multica 改自托管(找一台自己的 VPS 跑 docker compose),给团队每个人建独立账号,daemon 跑在公司内网的常驻机器上(不会休眠)。模型层主打 LongCat 免费额度,关键任务用付费模型兜底。这一档大约每月几十块成本,能撑得起 5-10 人的小团队。

档位三：认真做事的工程师。把这套方案当成一个自己专属的 Agent 平台,认真打磨 AGENTS.md、Issue 模板、Skills 库,把每个项目的”团队记忆”沉淀进去。模型层用付费的强模型(Claude Opus、GPT-5 之类)做主力,LongCat 做廉价批量任务的兜底。这一档不再追求白嫖,但因为架构是解耦的,你随时可以根据成本和效果调整每一层。

写在最后

这套方案教会我最重要的一件事是: AI 工具的红利期里,真正稀缺的不是模型、不是算力、不是订阅额度,而是「把工具组合起来变成稳定生产力」的那一层抽象。

每一家厂商都在拼命补贴自家某一层(模型/IDE/云),但没有一家厂商有动机帮你做”跨厂商的组合”——因为组合得越好,你越不依赖任何单一厂商。这恰恰是开源中间层(Multica + OpenCode)的价值所在,也是这套方案能在三家都不补贴你之后还活着的原因。

把这套流水线搭起来,顺手沉淀下你的 Issue 模板和 Skills 库,白嫖额度只是当下的副作用,真正长期带走的是你对 Agent 工作流的掌控力。

吃瓜可以,记得也吃点经验。

Claude Desktop 在 Windows 上完整安装与 CoworkVMService 排障实录

本文记录了一次从 ClaudeSetup.exe 下载 MSIX 中途报 unexpected EOF 一路排查到 MSIX 离线安装成功 + CoworkVMService 正常运行的完整过程，包含所有走过的弯路、踩到的坑和正确解法。

环境信息：

• 系统：Windows 11 Professional，Build 10.0.26200
• 架构：x64
• 当前账户：Administrator
• 现象起点：ClaudeSetup.exe 下载到 30%~50% 反复 unexpected EOF，3 次重试全部失败

一、根因总结（先看结论）

整个排查链上其实有三个独立但叠加的问题：

1. ClaudeSetup.exe 的在线下载链路不稳定——拉 api.anthropic.com 的 220MB MSIX 大文件经常在中段被截断（这是日志里 unexpected EOF 的直接原因）。
2. 历史残留的 CoworkVMService——之前装过的 MSIX 版本留下了同名服务，新安装包注册时被冲突阻断。
3. winget 仓库里 Anthropic.Claude 是 Squirrel 版 EXE，不带 Cowork 组件——用 winget 装能装上 Claude 主程序，但不会附带 CoworkVMService，要 Cowork 必须装官方 MSIX 包。

最终成功路径：手动浏览器下载 MSIX → 管理员 PowerShell Add-AppxPackage 离线安装 → CoworkVMService 自动注册并启动。

二、前置准备

2.1 确认管理员权限

整个流程全程必须在管理员 PowerShell 里执行（开始菜单搜 PowerShell → 右键 → 以管理员身份运行）。验证方法：

([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

返回 True 才能继续。本次实操返回 True，通过。

2.2 关闭所有相关进程

Get-Process claude, Cowork, CoworkVM, chrome-native-host -ErrorAction SilentlyContinue | Stop-Process -Force

三、清理多版本 Claude 残留（关键的第一步）

3.1 用 winget 卸载，处理”多个版本”报错

第一次执行卸载：

winget uninstall -e --id Anthropic.Claude

遇到的问题：报错

Multiple versions of this package are installed. Either refine the search, pass the `--version` argument to select one, or pass the `--all-versions` flag to uninstall all of them.

原因：之前装过不同版本的 Claude（包括 MSIX 版和 Squirrel 版），winget 检测到多个版本，需要明确告诉它”全部卸掉”。

正确做法：加 --all-versions 参数：

winget uninstall -e --id Anthropic.Claude --all-versions

⚠️ 重要警示：--all-versions 会把 MSIX 版也一起卸掉。这一步在初次清理时是对的，但在 MSIX 安装成功之后绝对不能再跑这条命令，否则会把 CoworkVMService 一起注销（本次实操就在尾声踩了这个坑，详见第八节）。

确认卸载干净：

winget list --id Anthropic.Claude

应该返回 No installed package found matching input criteria.。

3.2 卸载 MSIX 层残留

Get-AppxPackage -AllUsers *Claude* | Remove-AppxPackage -AllUsers -ErrorAction SilentlyContinue
Get-AppxPackage -AllUsers *Anthropic* | Remove-AppxPackage -AllUsers -ErrorAction SilentlyContinue
Get-AppxProvisionedPackage -Online | Where-Object { $_.DisplayName -like "*Claude*" -or $_.DisplayName -like "*Anthropic*" } | Remove-AppxProvisionedPackage -Online -ErrorAction SilentlyContinue

这三条把 MSIX 包（含所有用户、机器级 Provisioned 包）一并清掉。

3.3 清理残留的 CoworkVMService（核心步骤）

这是 ClaudeSetup.log 里 CoworkVMService already exists (potential conflict) 警告的根源——必须删掉。

Get-Service CoworkVMService -ErrorAction SilentlyContinue
Stop-Service CoworkVMService -Force -ErrorAction SilentlyContinue
sc.exe delete CoworkVMService
Get-Service CoworkVMService -ErrorAction SilentlyContinue

最后一条 Get-Service 没有任何输出，说明服务已彻底清除。

注意：sc.exe 后面必须有空格，是调用 sc.exe 而不是 PowerShell 别名 Set-Content。

3.4 清理用户目录和注册表残留

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\AnthropicClaude" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:APPDATA\Claude" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Packages\*Claude*" -ErrorAction SilentlyContinue

$key = "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModel\StateChange\PackageList"
Get-ChildItem $key -ErrorAction SilentlyContinue | Where-Object { $_.PSChildName -like "*Claude*" } | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue

🔄 第一次重启

清理完服务和 MSIX StateChange 注册表后，必须重启电脑一次，让服务删除和包状态彻底落盘。这一步千万不能省，否则后续注册新服务时还会撞上”幽灵服务”。

四、启用 Windows 必要功能

Cowork 依赖虚拟化平台跑沙箱，这一步是 CoworkVMService 能否真正运行的硬性条件。

4.1 启用功能

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All -NoRestart
Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All -NoRestart

遇到的问题：Windows 在启用功能时弹出报错（具体错误码未记录，但功能后续被验证为已启用）。

4.2 检测功能是否真的启用了

踩坑：尝试用一条命令查两个功能：

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform, Containers-DisposableClientVM | Format-List FeatureName, State, RestartRequired

报错：

无法将"System.Object[]"转换为参数"FeatureName"所需的类型"System.String"。

原因：-FeatureName 只接受一个字符串，不支持数组。

正确做法（两种任选）：

方法 A——分两条 PowerShell 命令：

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform | Format-List FeatureName, State, RestartRequired
Get-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM | Format-List FeatureName, State, RestartRequired

方法 B——用 DISM（输出更详细）：

DISM /Online /Get-FeatureInfo /FeatureName:VirtualMachinePlatform
DISM /Online /Get-FeatureInfo /FeatureName:Containers-DisposableClientVM

4.3 检测结果

本次实操经过重启后两个功能状态如下：

关键认知：对 Cowork 真正必需的只有 VirtualMachinePlatform，Windows 沙箱启用失败也能继续，但本次两个都成功启用。

🔄 第二次重启

启用 VirtualMachinePlatform 后必须再重启一次，Hyper-V 虚拟化层才会真正加载到内核。哪怕 State 显示 Enabled 但 RestartRequired: Possible，也要重启。这次重启不能省。

五、第一次安装尝试：winget 装上了但没 Cowork

5.1 用 winget 安装

winget install -e --id Anthropic.Claude --accept-package-agreements --accept-source-agreements

输出显示成功安装版本 1.8555.2，下载地址是：

https://downloads.claude.ai/releases/win32/x64/1.8555.2/Claude-a476c316c741715263e34f9c9d2bc45b6d0f21c7.exe

winget list --id Anthropic.Claude 也能查到。

5.2 检查 MSIX 包和 Cowork 服务

Get-AppxPackage -AllUsers *Claude* | Select-Object Name, PackageFullName, InstallLocation, Status

结果为空，没有任何输出。

Get-ChildItem "$env:LOCALAPPDATA\AnthropicClaude" -Recurse -Filter "claude.exe" -ErrorAction SilentlyContinue | Select-Object FullName

输出：

• C:\Users\Administrator\AppData\Local\AnthropicClaude\claude.exe
• C:\Users\Administrator\AppData\Local\AnthropicClaude\app-1.8555.2\claude.exe

Get-ChildItem "$env:LOCALAPPDATA\AnthropicClaude" -Recurse -Include "*Cowork*.exe","*cowork*.exe" -ErrorAction SilentlyContinue

搜不到任何 Cowork 可执行文件。

5.3 关键诊断结论

目录里有 Squirrel-CheckForUpdate.log、Update.exe、packages 这些典型的 Squirrel 框架文件，说明：

• winget 装的是 Squirrel 打包的传统 EXE 应用，不是 MSIX
• Squirrel 版本不包含 Cowork 组件，自然 Get-AppxPackage 查不到、Cowork*.exe 搜不到、服务也不存在
• 要 Cowork 必须改装官方 MSIX 包

六、第二次安装尝试：官方 MSIX 离线安装（成功路径）

6.1 卸载 Squirrel 版

winget uninstall -e --id Anthropic.Claude
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\AnthropicClaude" -ErrorAction SilentlyContinue

6.2 手动下载官方 MSIX 包

在浏览器里访问 Claude 官方部署文档：

https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows

下载 Claude MSIX (x64)，保存到 C:\Users\Administrator\Downloads\Claude.msix。

为什么浏览器能下、ClaudeSetup.exe 下不动？

ClaudeSetup.exe 自带的下载器没有断点续传，遇到网络中断就直接 unexpected EOF 然后从头重来；浏览器有断点续传和更稳的 TCP 重传策略，对 220MB 大文件友好得多。

如果浏览器也下不动：换手机热点 / VPN，或用 IDM、aria2、Free Download Manager 这种支持断点续传的下载工具。

下载完务必校验文件大小：

Get-Item "C:\Users\Administrator\Downloads\Claude.msix" | Select-Object Name, Length, LastWriteTime

Length 应在 220,000,000 字节附近。如果远小于这个值，说明下载又被截断了，必须重下。

6.3 管理员 PowerShell 安装 MSIX

Add-AppxPackage -Path "C:\Users\Administrator\Downloads\Claude.msix"

无任何报错输出，瞬间完成。

6.4 验证安装结果（关键检查点）

Get-AppxPackage -AllUsers *Claude* | Select-Object Name, PackageFullName, InstallLocation, Status

输出：

Name   PackageFullName                      InstallLocation                                                   Status
----   ---------------                      ---------------                                                   ------
Claude Claude_1.8555.2.0_x64__pzs8sxrjxfjjc C:\Program Files\WindowsApps\Claude_1.8555.2.0_x64__pzs8sxrjxfjjc Ok

Status: Ok，路径在系统级 C:\Program Files\WindowsApps，完美。

Get-Service CoworkVMService -ErrorAction SilentlyContinue | Format-List Name, Status, StartType, DisplayName, BinaryPathName

输出：

Name        : CoworkVMService
Status      : Running
StartType   : Automatic
DisplayName : Claude

🎉 CoworkVMService 自动注册并自动启动，状态 Running，启动类型 Automatic，全部到位。

关键认知：MSIX 包内嵌的服务注册逻辑会在 Add-AppxPackage 时自动调用，不需要手动 sc.exe create。前面之所以准备好了手动注册命令，是为了应对自动注册失败的兜底场景。

七、为什么 MSIX 方案能一次成功

MSIX 是 Microsoft 现代应用打包格式，签名、沙箱、注册全部由系统接管，比 Squirrel EXE 稳定得多，这也是 Anthropic 官方部署文档主推它的原因。

八、收尾踩坑警示：千万别再跑 winget uninstall --all-versions

MSIX 装好后，为了清理 Squirrel 残留，跑了：

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\AnthropicClaude" -ErrorAction SilentlyContinue  # ✅ 这条没问题
winget uninstall -e --id Anthropic.Claude --all-versions                                       # ❌ 这条把 MSIX 一起卸了

结果：

Get-AppxPackage -AllUsers *Claude*   # 空输出
Get-Service CoworkVMService          # 找不到服务

根因：winget 仓库里 Anthropic.Claude 这个 ID 同时挂着 Squirrel 和 MSIX 两个 manifest，--all-versions 会把所有形态的安装都卸掉。

正确做法：

• 清理 Squirrel 残留只需要删 $env:LOCALAPPDATA\AnthropicClaude 目录，不需要再跑 winget 卸载。
• MSIX 装好后，今后所有升级和管理都不要再用 winget，去官方页下载新 MSIX，Add-AppxPackage -Path 覆盖安装即可。

恢复方案：再跑一次 MSIX 安装：

Add-AppxPackage -Path "C:\Users\Administrator\Downloads\Claude.msix"
Get-AppxPackage -AllUsers *Claude* | Select-Object Name, Status
Get-Service CoworkVMService | Format-List Name, Status, StartType

Status: Ok 和 Running 都回来即可。

九、最终验证清单

最终成功状态应满足所有下列条件：

# 1. MSIX 包正常注册
Get-AppxPackage -AllUsers *Claude*
# 期望：Status = Ok，PackageFullName 类似 Claude_1.8555.2.0_x64__pzs8sxrjxfjjc

# 2. Cowork 服务运行中
Get-Service CoworkVMService
# 期望：Status = Running，StartType = Automatic

# 3. 虚拟化平台已启用
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
# 期望：State = Enabled

# 4. winget 列表里不应再有 Claude（避免后续误操作）
winget list --id Anthropic.Claude
# 期望：No installed package found

从开始菜单启动 Claude，登录账号，应能正常使用 Cowork 功能。

十、完整时间线复盘

十一、几条带走的经验

网络层经验：api.anthropic.com 对国内大文件下载链路不稳，永远优先用浏览器或断点续传工具拉 MSIX，不要依赖 ClaudeSetup.exe 自己下。

安装方式经验：要 Cowork 就必须装 MSIX，winget 仓库里那个 Anthropic.Claude 是 Squirrel 版不带 Cowork，别浪费时间。

服务管理经验：MSIX 包会自动注册 CoworkVMService，不需要也不应该手动 sc.exe create；遇到”服务已存在”的冲突，老老实实先 sc.exe delete 清理再装。

重启经验：服务删除后要重启一次（让删除落盘），启用 VirtualMachinePlatform 后要再重启一次（让虚拟化内核加载），两次重启都不能省。

winget 经验：MSIX 装好后，永远不要再对 Anthropic.Claude 这个 ID 跑 winget uninstall，否则会连带卸掉 MSIX。今后升级走”下新 MSIX → Add-AppxPackage 覆盖”即可。

功能检测经验：Get-WindowsOptionalFeature -FeatureName 不接受数组，要么分多条跑，要么改用 DISM /Online /Get-FeatureInfo。

整套流程跑下来，从最初 unexpected EOF 到最后 CoworkVMService: Running，问题已全部解决，记录完毕。

本指南专为 Windows 系统用户编写，详细介绍如何使用开源工具 FFmpeg 将 M3U8 流媒体视频下载并转换为 MP4 格式。包含安装、环境变量配置、命令使用及常见问题解决方案。

📑 目录

• 一、什么是 M3U8 与 FFmpeg
• 二、下载 FFmpeg
• 三、解压安装
• 四、配置环境变量
• 五、验证安装
• 六、获取 M3U8 视频链接
• 七、执行下载与转换命令
• 八、命令参数详解
• 九、进阶用法
• 十、常见问题与解决方案

一、什么是 M3U8 与 FFmpeg

M3U8 是一种基于 HTTP Live Streaming (HLS) 协议的播放列表文件格式，本身不存储视频数据，而是记录了一系列被切片的小段视频（.ts 文件）的索引信息。许多视频网站、政府教育平台等都使用此格式做流媒体分发。

FFmpeg 是一个开源的音视频转码工具，提供了录制、转换以及流化音视频的完整解决方案。它可以转码、压制、提取、截取、合并、录屏等，是处理 M3U8 流媒体最专业且免费的方案。

二、下载 FFmpeg

第一步：访问官方下载页面

打开浏览器，访问 FFmpeg 官网：https://ffmpeg.org/download.html

在页面中点击 Windows 图标，然后选择 “Windows builds from gyan.dev”（推荐，最稳定）。

第二步：进入 gyan.dev 下载页

在 gyan.dev 页面，找到 release builds 区域，根据需要下载：

💡 下载建议：M3U8 转换 MP4 的需求，下载 ffmpeg-release-essentials.7z 即可。

直接下载链接（gyan.dev 镜像）：

• 官方主页：https://www.gyan.dev/ffmpeg/builds/
• Essentials 版：https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.7z

三、解压安装

第一步：解压压缩包

下载完成后会得到一个 .7z 压缩包，需使用 7-Zip 或 WinRAR 解压。

📌 没有 7-Zip？ 可前往官网免费下载：https://www.7-zip.org/

第二步：移动到固定目录

解压后会得到一个名为 ffmpeg-x.x-essentials_build 的文件夹。建议将其重命名为 ffmpeg 并移动到一个固定且不会被误删的位置，例如：

C:\ffmpeg\

第三步：确认目录结构

进入 C:\ffmpeg\bin，确认目录中包含以下三个核心可执行文件：

复制此 bin 目录的完整路径（例如 C:\ffmpeg\bin），下一步配置环境变量需要用到。

四、配置环境变量

配置环境变量后，您可以在任意目录下的命令行中直接调用 ffmpeg 命令。

第一步：打开系统属性

1. 在桌面右键 此电脑 → 选择 属性
2. 在打开的窗口中，点击 高级系统设置

第二步：进入环境变量设置

在跳出的 系统属性 窗口中，点击底部的 环境变量(N)… 按钮。

第三步：编辑 Path 变量

1. 在下方的 系统变量 区域，找到名为 Path 的变量
2. 选中它后点击 编辑(E)…
3. 在弹出的窗口中点击 新建(N)
4. 粘贴之前复制的 bin 目录路径：C:\ffmpeg\bin
5. 一路点击 确定 保存所有窗口

⚠️ 重要提示：配置完成后，必须重新打开一个新的命令行窗口，旧窗口不会自动加载新的环境变量。

五、验证安装

按 Win + R 打开运行窗口，输入 cmd 回车打开命令提示符，或直接搜索 PowerShell 打开。

输入以下命令：

ffmpeg -version

若命令行返回类似如下信息，则代表安装成功：

ffmpeg version 7.x-essentials_build Copyright (c) 2000-2026 the FFmpeg developers
built with gcc 13.2.0 (Rev5, Built by MSYS2 project)
configuration: --enable-gpl --enable-version3 --enable-static ...
libavutil      59. xx.100
libavcodec     61. xx.100
...

如果提示 'ffmpeg' 不是内部或外部命令，则说明环境变量配置存在问题，请回到第四步重新检查。

六、获取 M3U8 视频链接

如果您已经拥有 M3U8 链接（例如本指南示例中的政府平台资源链接），可直接跳过此步骤。否则，可通过 Chrome / Edge 开发者工具抓取：

1. 打开目标视频页面
2. 按 F12 或右键点击页面选择 检查 调出开发者工具
3. 切换至 网络 (Network) 标签页
4. 在过滤器搜索框中输入：m3u8
5. 刷新页面并播放视频
6. 在筛选出的请求中右键 .m3u8 文件 → Copy → Copy link address

💡 小技巧：在过滤器中也可以直接选择 媒体 (Media) 分类，更容易定位视频资源。

七、执行下载与转换命令

7.1 基础命令（推荐 ⭐）

打开命令行（CMD / PowerShell），输入以下命令：

ffmpeg -i "你的M3U8链接" -c copy output.mp4

实际示例（以您提供的链接为例）：

ffmpeg -i "https://v.dyjyzyk.dtdjzx.gov.cn/zyk-shengnei/transcode/20260519/3820709499606408795/hls/1500/3820709683451135060.m3u8" -c copy output.mp4

7.2 增强兼容性命令

针对部分加密或音频格式特殊的流媒体，建议使用：

ffmpeg -i "你的M3U8链接" -c copy -bsf:a aac_adtstoasc output.mp4

7.3 等待下载完成

执行后，命令行窗口将显示实时下载进度，包括：

• frame= 当前已处理帧数
• time= 当前已处理的视频时长
• bitrate= 当前码率
• speed= 转换速度倍数（如 5x 表示 5 倍速）

下载完成后，您将在当前命令行所在的目录下看到生成的 output.mp4 文件。

💡 小贴士：可以先用 cd 命令切换到希望保存文件的目录，例如：

cd D:\Videos
ffmpeg -i "M3U8链接" -c copy output.mp4

八、命令参数详解

九、进阶用法

9.1 设置网络超时（防止断流）

ffmpeg -i "M3U8链接" -c copy -bsf:a aac_adtstoasc -timeout 3000000 output.mp4

9.2 启用断线重连机制

ffmpeg -reconnect 1 -reconnect_at_eof 1 -reconnect_streamed 1 -reconnect_delay_max 5 -i "M3U8链接" -c copy output.mp4

9.3 重新编码并压缩画质（减小文件体积）

ffmpeg -i "M3U8链接" -c:v libx264 -crf 23 -c:a aac output.mp4

其中 -crf 取值 0-51，数值越小画质越高，推荐 18-28 区间。日常使用 23 即可。

9.4 截取部分时段下载

ffmpeg -ss 00:01:00 -i "M3U8链接" -t 00:05:00 -c copy output.mp4

• -ss 00:01:00：起始时间（从第 1 分钟开始）
• -t 00:05:00：持续时长（截取 5 分钟）

9.5 添加请求头（绕过简单防盗链）

ffmpeg -headers "Referer: https://example.com/" -i "M3U8链接" -c copy output.mp4

9.6 协议白名单（解决部分报错）

ffmpeg -protocol_whitelist "file,http,https,tcp,tls,crypto" -i "M3U8链接" -c copy output.mp4

9.7 批量下载脚本（一键工具）

将以下代码保存为 download.bat 文件，双击即可使用：

@echo off
chcp 65001 >nul
title FFmpeg M3U8 转 MP4 工具
echo ============================================
echo       FFmpeg M3U8 视频下载工具
echo ============================================
echo.
set /p url="请粘贴 M3U8 链接: "
set /p name="请输入输出文件名（不带后缀）: "
echo.
echo 开始下载，请稍候...
echo.
ffmpeg -i "%url%" -c copy -bsf:a aac_adtstoasc "%name%.mp4"
echo.
echo ============================================
echo       下载完成！文件已保存
echo ============================================
pause

十、常见问题与解决方案

Q1：提示 'ffmpeg' 不是内部或外部命令

原因：环境变量未生效。
解决方案：

1. 确认 Path 中已添加 C:\ffmpeg\bin 路径
2. 关闭所有命令行窗口，重新打开新窗口
3. 必要时重启电脑

Q2：下载到一半中断或卡住

原因：网络不稳定或服务器超时。
解决方案：使用断线重连参数

ffmpeg -reconnect 1 -reconnect_at_eof 1 -reconnect_streamed 1 -reconnect_delay_max 5 -i "M3U8链接" -c copy output.mp4

Q3：报错 Protocol 'https' not on whitelist

解决方案：添加协议白名单参数

ffmpeg -protocol_whitelist "file,http,https,tcp,tls,crypto" -i "M3U8链接" -c copy output.mp4

Q4：视频无法播放或音视频不同步

解决方案：重新编码以重建索引

ffmpeg -i "M3U8链接" -c:v libx264 -c:a aac output.mp4

Q5：M3U8 视频已加密（含 Key）

解决方案：FFmpeg 会自动尝试请求密钥。若失败，需手动下载 .key 文件，并修改 M3U8 文件中的密钥路径为本地路径后再转换。

Q6：下载速度很慢

原因：可能是源服务器限速或网络环境问题。
解决方案：

• 切换网络环境（如使用有线网络）
• 检查源站是否对 IP 有限速
• 加上 -threads 8 参数启用多线程

📌 重要提示

1. 版权合规：请确保下载的视频来源合法，遵守网站使用条款及版权法律法规。
2. 文件大小：-c copy 模式下文件大小与原视频一致；重新编码会占用更多 CPU 和时间。
3. 路径规范：链接和文件路径建议使用英文双引号包裹，避免特殊字符干扰。
4. 磁盘空间：下载前确认目标磁盘有足够剩余空间。

📚 参考资料

• FFmpeg 官方下载页面
• gyan.dev FFmpeg Windows Builds
• 零度博客 - FFmpeg 安装教程
• 掘金 - FFmpeg 应用专栏
• 腾讯云开发者社区 - M3U8 转 MP4 指南

教程结束：按照上述步骤，您应当能够顺利地将任意 M3U8 流媒体视频下载并转换为 MP4 格式。

背景

Claude Code Desktop 是 Anthropic 官方的 AI 编程助手客户端，它默认只能调用 Claude 系列模型。为了让它能调用小米的 mimo-v2.5-pro 推理模型，需要开发一个协议转换代理，将 Anthropic API 格式转换为 OpenAI API 格式。

技术原理

Claude Code Desktop  →  本地代理 (xiaomi-proxy.cjs)  →  小米 API
     (Anthropic 格式)       (协议转换)                   (OpenAI 格式)

代理的工作：

1. 接收 Anthropic Messages API 格式请求（/v1/messages）
2. 将模型 ID 映射为小米的模型名
3. 将请求格式转为 OpenAI Chat Completions API 格式
4. 转发到小米 API
5. 将 OpenAI 响应转回 Anthropic 格式返回

第一版：基础实现

配置信息

const CONFIG = {
  listenPort: 8081,
  targetHost: 'token-plan-sgp.xiaomimimo.com',
  targetPath: '/v1/chat/completions',
  apiKey: 'tp-sdcyuxmgwfbyb5tj0q1slchv2mnctwq0ro60de68p27p5870',
  model: 'mimo-v2.5-pro',
};

模型映射

const ANTHROPIC_TO_IMODEL = {
  'claude-sonnet-4-6': CONFIG.model,
  'claude-opus-4': CONFIG.model,
  'claude-sonnet-4-6-lite': CONFIG.model,
  'claude-3-opus-4-video': CONFIG.model,
};

核心转换函数

实现了以下转换逻辑：

• anthropicToOpenAI() - 请求格式转换
• openAIToAnthropic() - 响应格式转换
• createAnthropicStreamTransformer() - 流式响应转换

问题 1：模型映射表不完整

症状

Claude Code Desktop 发送的模型名不在映射表中，导致所有请求都走兜底逻辑。

原因

Claude Code 会发送多种模型名，如：

• claude-sonnet-4-6-20250506
• claude-4-sonnet
• claude-3-5-sonnet-20241022
• 等等…

第一版只映射了 4 个名字。

修复

补全了 15 个常见 Anthropic 模型名的映射：

const ANTHROPIC_TO_IMODEL = {
  // 主力模型
  'claude-sonnet-4-6': CONFIG.model,
  'claude-sonnet-4-6-20250506': CONFIG.model,
  'claude-4-sonnet': CONFIG.model,
  'claude-4-sonnet-20250506': CONFIG.model,
  'claude-3-5-sonnet': CONFIG.model,
  'claude-3-5-sonnet-20241022': CONFIG.model,
  'claude-3-opus': CONFIG.model,

  // 高级模型
  'claude-opus-4': CONFIG.model,
  'claude-opus-4-20250514': CONFIG.model,
  'claude-4-opus': CONFIG.model,
  'claude-3-opus-20240229': CONFIG.model,

  // 轻量模型
  'claude-sonnet-4-6-lite': CONFIG.model,
  'claude-3-5-haiku': CONFIG.model,
  'claude-3-5-haiku-20241022': CONFIG.model,
  'claude-3-haiku': CONFIG.model,

  // 视频/图片
  'claude-3-opus-4-video': CONFIG.model,
};

问题 2：缺少 stream_options

症状

流式请求时，无法获取 token 用量信息。

原因

原版代码在流式请求时会发送 stream_options: { include_usage: true }，让上游在流式响应中返回 usage 信息。第一版漏掉了这个字段。

修复

const openaiReq = {
  model: targetModel,
  messages,
  max_tokens: anthropicReq.max_tokens || 4096,
  stream: anthropicReq.stream === true,
  // 修复：恢复 stream_options
  stream_options: anthropicReq.stream ? { include_usage: true } : undefined,
};

问题 3：reasoning_content 丢失（核心问题）

症状

API Error: 400 The reasoning_content in the thinking mode must be passed back to the API.

原因分析

小米的 mimo-v2.5-pro 是推理模型，它的响应格式特殊：

{
  "message": {
    "content": "",
    "reasoning_content": "嗯，用户发来一个简单的问候...",
    "tool_calls": [...]
  }
}

关键点：

1. 实际回复在 reasoning_content 字段，而不是 content
2. 后续请求必须把之前的 reasoning_content 传回去

但 Anthropic 格式没有 reasoning_content 字段，经过一次转换后就丢失了。

解决方案

使用特殊标记 [REASONING]...[/REASONING] 来保存 reasoning_content：

响应时（OpenAI → Anthropic）：

// 小米推理模型：用特殊标记保存 reasoning_content
if (message.reasoning_content) {
  content.push({ type: 'text', text: `[REASONING]${message.reasoning_content}[/REASONING]` });
}

if (message.content) {
  content.push({ type: 'text', text: message.content });
}

请求时（Anthropic → OpenAI）：

if (block.type === 'text') {
  // 检查是否是 reasoning_content 标记
  if (block.text.startsWith('[REASONING]') && block.text.endsWith('[/REASONING]')) {
    reasoningContent = block.text.slice(11, -12); // 提取 reasoning_content
  } else {
    contentParts.push({ type: 'text', text: block.text });
  }
}

// 构建 assistant 消息时包含 reasoning_content
const assistantMsg = { role: 'assistant' };
if (reasoningContent) {
  assistantMsg.reasoning_content = reasoningContent;
}

流式处理：

// 追踪推理内容和普通内容的状态
let inReasoningMode = false;

// 小米推理模型：reasoning_content 需要用标记保存
if (delta.reasoning_content) {
  if (!inReasoningMode) {
    // 开始推理模式，添加前缀标记
    writeAnthropicEvent({
      type: 'content_block_delta', index: currentContentIndex,
      delta: { type: 'text_delta', text: '[REASONING]' },
    });
    inReasoningMode = true;
  }
  writeAnthropicEvent({
    type: 'content_block_delta', index: currentContentIndex,
    delta: { type: 'text_delta', text: delta.reasoning_content },
  });
}

// 普通 content
if (delta.content) {
  if (inReasoningMode) {
    // 从推理模式切换到内容模式，添加后缀标记
    writeAnthropicEvent({
      type: 'content_block_delta', index: currentContentIndex,
      delta: { type: 'text_delta', text: '[/REASONING]' },
    });
    inReasoningMode = false;
  }
  // ... 处理普通内容
}

问题 5：旧消息缺少 reasoning_content

症状

API Error: 400 The reasoning_content in the thinking mode must be passed back to the API.

即使已经实现了 [REASONING] 标记和缓存机制，仍然报错。

原因分析

通过详细日志发现，Claude Code 发送的对话历史中，所有旧的 assistant 消息都没有 [REASONING] 标记：

[2] role: assistant, hasReasoning: false, content: 我是 **Claude Code**...
[4] role: assistant, hasReasoning: false, content: 看起来你遇到的问题...
[6] role: assistant, hasReasoning: false, content: 让我先看看你提到的支持文章...

这些消息是之前对话生成的，不是当前代理生成的，所以没有 [REASONING] 标记。

但小米 API 要求所有 assistant 消息都必须有 reasoning_content 字段，否则拒绝请求。

解决方案

采用三层保障策略：

// 小米推理模型需要传回 reasoning_content
// 优先从标记中提取，其次从缓存中查找，最后使用默认值
if (reasoningContent) {
  // 第一层：从 [REASONING] 标记中提取
  assistantMsg.reasoning_content = reasoningContent;
  log(`  Added reasoning_content from marker`);
} else if (msg.id && reasoningCache.has(msg.id)) {
  // 第二层：从内存缓存中查找
  assistantMsg.reasoning_content = reasoningCache.get(msg.id);
  log(`  Added reasoning_content from cache`);
} else {
  // 第三层：为旧消息提供空的 reasoning_content，满足 API 要求
  assistantMsg.reasoning_content = '';
  log(`  Added empty reasoning_content (no marker or cache found)`);
}

缓存机制

// reasoning_content 缓存：key 是 Anthropic 消息 ID，value 是 reasoning_content
const reasoningCache = new Map();

// 非流式响应时缓存
function openAIToAnthropic(openaiResp, originalModel) {
  const messageId = `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;

  if (message.reasoning_content) {
    reasoningCache.set(messageId, message.reasoning_content);
    log(`Cached reasoning_content for ${messageId}`);
  }

  return { id: messageId, ... };
}

// 流式响应时缓存
function createAnthropicStreamTransformer(anthropicRes, originalModel) {
  let accumulatedReasoning = '';

  // 在 onChunk 中累积
  if (delta.reasoning_content) {
    accumulatedReasoning += delta.reasoning_content;
  }

  // 在 onDone 中缓存
  onDone() {
    if (accumulatedReasoning) {
      reasoningCache.set(messageId, accumulatedReasoning);
      log(`Cached streaming reasoning_content for ${messageId}`);
    }
  }
}

问题 4：工具结果消息格式错误

症状

API Error: 400 messages[5] user content only supports a string or an array of content parts

原因分析

Claude Code 发送工具结果时，使用的是 user 角色 + tool_result 内容块：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "call_xxx",
      "content": "命令执行结果..."
    }
  ]
}

但 OpenAI 格式要求工具结果是单独的 tool 消息：

{
  "role": "tool",
  "tool_call_id": "call_xxx",
  "content": "命令执行结果..."
}

第一版的 convertAnthropicContentToOpenAI 函数对 tool_result 返回了特殊对象，导致格式错误。

修复

更新 convertAnthropicMessages 函数，正确拆分包含 tool_result 的用户消息：

if (role === 'user') {
  // 检查是否包含 tool_result 内容块
  if (Array.isArray(msg.content) && msg.content.some(b => b.type === 'tool_result')) {
    // 拆分成多个消息
    const textParts = [];
    const toolResults = [];

    for (const block of msg.content) {
      if (block.type === 'tool_result') {
        toolResults.push(block);
      } else if (block.type === 'text') {
        textParts.push(block.text);
      }
    }

    // 添加 user 消息（文本内容）
    if (textParts.length > 0) {
      openaiMessages.push({ role: 'user', content: textParts.join('') });
    }

    // 添加 tool 消息
    for (const tr of toolResults) {
      const content = typeof tr.content === 'string'
        ? tr.content
        : (Array.isArray(tr.content) 
            ? tr.content.filter(b => b.type === 'text').map(b => b.text).join('') 
            : '');
      openaiMessages.push({
        role: 'tool',
        content,
        tool_call_id: tr.tool_use_id,
      });
    }
  } else {
    // 普通 user 消息
    const content = convertAnthropicContentToOpenAI(msg.content);
    openaiMessages.push({ role: 'user', content });
  }
}

Windows PowerShell 踩坑

环境变量设置

# ❌ 错误（bash 语法）
DEBUG_PROXY=true node xiaomi-proxy.cjs

# ✅ 正确（PowerShell 语法）
$env:DEBUG_PROXY="true"; node xiaomi-proxy.cjs

curl 命令

# ❌ 错误（PowerShell 的 curl 是 Invoke-WebRequest 的别名）
curl http://127.0.0.1:8081/health

# ✅ 正确（使用 curl.exe 或文件方式）
curl.exe http://127.0.0.1:8081/health

# 发送 JSON 请求（避免 PowerShell 转义问题）
curl.exe -X POST http://127.0.0.1:8081/v1/messages `
  -H "Content-Type: application/json" `
  -H "x-api-key: sk-test" `
  -d "@path\to\body.json"

注册表配置

Claude Code Desktop 通过 Windows 注册表配置代理地址：

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Policies\Claude]
"inferenceProvider"="gateway"
"inferenceGatewayBaseUrl"="http://127.0.0.1:8081"
"inferenceGatewayApiKey"="sk-session-token"

双击 .reg 文件即可合并，无需先删除。

最终验证

测试命令

# 终端 1：启动代理
$env:DEBUG_PROXY="true"; node xiaomi-proxy.cjs

# 终端 2：测试请求
curl.exe -X POST http://127.0.0.1:8081/v1/messages `
  -H "Content-Type: application/json" `
  -H "x-api-key: sk-test" `
  -d "@test-body.json"

成功响应

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "[REASONING]The user is asking for the current time.[/REASONING]"
    },
    {
      "type": "tool_use",
      "id": "call_xxx",
      "name": "Bash",
      "input": { "command": "date" }
    }
  ],
  "model": "claude-sonnet-4-6",
  "stop_reason": "tool_use",
  "usage": { "input_tokens": 39163, "output_tokens": 54 }
}

总结

关键经验

1. 推理模型的特殊性：小米 mimo-v2.5-pro 等推理模型需要特殊处理 reasoning_content 字段
2. 协议差异：Anthropic 和 OpenAI 的工具结果格式不同，需要正确转换
3. 调试的重要性：通过添加详细日志，快速定位了问题根源
4. Windows 环境：PowerShell 的语法和 bash 不同，需要注意
5. 历史兼容性：处理历史对话时，需要为缺失的字段提供默认值
6. 多层保障：关键数据采用标记 + 缓存 + 默认值三层保障，提高鲁棒性

附录：完整代码结构

xiaomi-proxy.cjs
├── 配置区 (CONFIG)
├── 模型映射表 (ANTHROPIC_TO_IMODEL)
├── reasoning_content 缓存 (reasoningCache)
├── HTTP 工具函数
│   ├── upstreamRequest() - 非流式请求
│   └── upstreamStreamRequest() - 流式请求
├── 请求格式转换
│   ├── convertAnthropicContentToOpenAI()
│   ├── convertAnthropicMessages()  ← 包含 reasoning_content 三层保障
│   ├── convertAnthropicTools()
│   └── anthropicToOpenAI()  ← 包含请求日志
├── 响应格式转换
│   ├── openAIToAnthropic()  ← 包含 reasoning_content 标记 + 缓存
│   └── createAnthropicStreamTransformer()  ← 包含流式推理内容处理 + 缓存
└── HTTP 服务器
    ├── /health - 健康检查
    ├── /v1/models - 模型列表
    └── /v1/messages - 核心端点  ← 包含详细日志

核心设计模式

三层保障机制（用于 reasoning_content）：

┌─────────────────────────────────────────────────────────────┐
│                    reasoning_content 处理流程                 │
├─────────────────────────────────────────────────────────────┤
│  响应时（小米 API → Claude Code）                            │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │ reasoning   │ →  │ [REASONING] │ →  │ Anthropic   │     │
│  │ _content    │    │ 标记包装     │    │ 格式响应     │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                           ↓                                 │
│                    ┌─────────────┐                          │
│                    │ 缓存到 Map  │                          │
│                    └─────────────┘                          │
├─────────────────────────────────────────────────────────────┤
│  请求时（Claude Code → 小米 API）                           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │ Anthropic   │ →  │ 提取标记    │ →  │ reasoning   │     │
│  │ 格式请求     │    │ 或查缓存    │    │ _content    │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                           ↓                                 │
│                    ┌─────────────┐                          │
│                    │ 默认空字符串 │                          │
│                    └─────────────┘                          │
└─────────────────────────────────────────────────────────────┘

附录：调试技巧

添加详细日志

在关键位置添加日志，帮助定位问题：

// 1. 显示原始请求
log('Anthropic messages:');
for (let i = 0; i < anthropicReq.messages.length; i++) {
  const msg = anthropicReq.messages[i];
  log(`  [${i}] role: ${msg.role}, content: ${JSON.stringify(msg.content).substring(0, 100)}...`);
}

// 2. 显示转换后的请求
log('OpenAI request messages:');
for (let i = 0; i < openaiReq.messages.length; i++) {
  const msg = openaiReq.messages[i];
  log(`  [${i}] role: ${msg.role}, hasReasoning: ${!!msg.reasoning_content}`);
}

// 3. 显示上游响应
log('Upstream response:', JSON.stringify(openaiResp, null, 2));

// 4. 显示 reasoning_content 状态
log(`  Found reasoning_content in block: ${reasoningContent.substring(0, 80)}...`);
log(`  Added reasoning_content from cache (msg.id=${msg.id})`);

测试命令

# 开启调试模式启动代理
$env:DEBUG_PROXY="true"; node xiaomi-proxy.cjs

# 发送测试请求（使用文件避免 PowerShell 转义问题）
curl.exe -X POST http://127.0.0.1:8081/v1/messages `
  -H "Content-Type: application/json" `
  -H "x-api-key: sk-test" `
  -d "@test-body.json"

# 健康检查
curl.exe http://127.0.0.1:8081/health

# 查看模型列表
curl.exe http://127.0.0.1:8081/v1/models

目标：在 Windows 上安装 Claude Desktop，并通过本地代理使用 Loomy 的 API 通道调用大模型。

适用场景：没有 Anthropic 官方 API Key，但有 Loomy 订阅/额度，希望在 Claude Code Desktop 中使用。

目录

• 第一章：Claude Desktop 安装
• 第二章：理解你的代理工具
• 第三章：配置与启动代理
• 第四章：配置 Claude Code Desktop
• 第五章：常见安装故障修复
• 常见问题排查
• 附录

第一章：Claude Desktop 安装

1.1 方法一：winget 安装（推荐作为第一步）

winget install Anthropic.Claude

✅ 结果：安装成功，应用可以正常启动。 ❌ 问题：Cowork 功能报错 — Reinstall required - Cowork requires Claude Desktop to be installed via a modern installer。

原因：Cowork 功能会校验 Claude Desktop 是否通过 MSIX（现代安装程序）部署。winget 安装的记录在 Windows 侧不完整，Cowork 认为安装来源不合法。

1.2 方法二：直接安装 MSIX

下载 MSIX 安装包：

Invoke-WebRequest -Uri "https://claude.ai/api/desktop/win32/x64/msix/latest/redirect" -OutFile "Claude.msix"

为当前用户安装：

Add-AppxPackage -Path "Claude.msix"

❌ 问题：安装成功，但应用无法启动。点击图标无反应。

原因：MSIX 包本身缺少某些运行时依赖或签名上下文。单独安装 MSIX 时，Windows 没有正确解析其依赖链。

1.3 最终方案：winget + MSIX 组合安装 ✅

先通过 winget 安装基础版本（确保依赖齐全、应用可启动），再用 MSIX 覆盖安装（修正安装器签名记录）。

完整命令：

# 第 1 步：winget 安装（使应用可运行，依赖完整）
winget install Anthropic.Claude

# 第 2 步：下载 MSIX 安装包
Invoke-WebRequest -Uri "https://claude.ai/api/desktop/win32/x64/msix/latest/redirect" -OutFile "Claude.msix"

# 第 3 步：MSIX 覆盖安装（修正安装来源，Cowork 可识别）
Add-AppxPackage -Path "Claude.msix"

最终效果：

第二章：理解你的代理工具

你的 Loomy Workspace 目录下有三个文件，分工如下：

2.1 文件总览

Loomy Workspace/
├── 代理使用教程.md              # 配置指南（DNS 劫持方案，供参考）
├── get-session.cjs              # Session Token 提取器
└── anthropic-proxy.mjs          # 协议转换代理（主力方案）

2.2 get-session.cjs — Session Token 自动提取

作用：从 Loomy 桌面端的本地数据库中提取登录会话密钥。

原理：

• Loomy 桌面端使用 Electron 的 Local Storage，底层是 LevelDB
• LevelDB 的数据存储在 %APPDATA%/loomy/Local Storage/leveldb/ 目录下，以 .log 和 .ldb 文件存在
• 该工具扫描这些文件，在二进制数据中查找 loggedInAt 关键字
• 在 loggedInAt 附近寻找 32 位十六进制字符串（即 loomy-session-key）
• 同时提取手机号做脱敏显示

用法：

# 仅输出最新 session key
node get-session.cjs

# 列出所有历史 session
node get-session.cjs --all

# 输出 SESSION_TOKEN=xxx 格式（适合管道）
node get-session.cjs --env

# 实时监听 session 变化（每 5 秒轮询）
node get-session.cjs --watch

前置条件：Loomy 桌面端必须已登录运行。

2.3 anthropic-proxy.mjs — 协议转换代理（核心）

这是整套方案的核心组件。它解决的问题是：

Claude Code Desktop 只认 Anthropic Messages API 格式，而 Loomy/iModel 只提供 OpenAI Chat Completions API 格式。两者协议不兼容。

架构图

Claude Code Desktop              anthropic-proxy.mjs                    upstream
(ANTHROPIC_BASE_URL=:8080)       (localhost:8080)                       (loomyad.xunfei.cn)
┌─────────────────┐   POST /v1/messages   ┌─────────────────────┐   POST /api/v1/chat/completions   ┌──────────────┐
│  Anthropic 格式  │  ───────────────────→  │  协议转换 + 模型映射  │  ───────────────────────────────→  │  OpenAI 格式  │
│  请求           │                       │                     │                                 │  请求         │
│                 │  ←───────────────────  │                     │  ←───────────────────────────────  │              │
└─────────────────┘   Anthropic 格式响应   └─────────────────────┘   OpenAI 格式响应                   └──────────────┘

核心功能 1：协议转换

核心功能 2：模型映射

代理将 Claude 模型名映射到上游 iModel 的模型：

核心功能 3：API 端点

核心功能 4：流式支持

完整的流式转换。上游 OpenAI SSE 流中的每个 delta 被实时转换为 Anthropic 的 content_block_delta 事件。支持：

• 文本 delta → content_block_delta (text_delta)
• Tool calls delta → content_block_delta (input_json_delta)
• Usage 信息 → message_delta 中的 usage
• Finish reason 映射

Session Token 获取

优先级：

1. 环境变量 SESSION_TOKEN（最高优先级）
2. 自动提取 — 调用 get-session.cjs 从 Loomy 桌面端 LevelDB 读取

第三章：配置与启动代理

3.1 确认前置条件

• Loomy 桌面端已安装并登录
• Node.js 已安装（建议 v18+）
• Claude Desktop 已正确安装（按第一章流程）

3.2 验证 Session 可获取

cd "C:\Users\Administrator\Documents\Loomy Workspace"

# 确保 Loomy 桌面端正在运行且已登录
node get-session.cjs

预期输出：一串 32 位十六进制字符串，如 a1b2c3d4e5f6...。

如果报错 未找到 session，请确认 Loomy 桌面端已登录。

3.3 启动代理

# 方式一：自动提取 session
node anthropic-proxy.mjs

# 方式二：手动指定 session（优先级更高）
set SESSION_TOKEN=你的32位hex字符串
node anthropic-proxy.mjs

# 方式三：启用调试日志
set DEBUG_PROXY=true
node anthropic-proxy.mjs

# 方式四：指定其他端口（默认 8080）
set PROXY_PORT=9090
node anthropic-proxy.mjs

启动成功应看到如下输出：

╔════════════════════════════════════════════════════════╗
║         Anthropic → iModel API 代理                    ║
╠════════════════════════════════════════════════════════╣
║  代理地址:  http://127.0.0.1:8080                      ║
║  上游 API:  https://loomyad.xunfei.cn                  ║
║  Session:   a1b2c3d4e5f6...                            ║
╚════════════════════════════════════════════════════════╝

3.4 验证代理运行正常

# 测试健康检查
curl http://127.0.0.1:8080/health

# 测试模型列表
curl http://127.0.0.1:8080/v1/models

第四章：配置 Claude Code Desktop

4.1 设置环境变量

在 Claude Code Desktop 的配置中（claude_desktop_config.json），添加：

{
  "projectSettings": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8080",
    "ANTHROPIC_API_KEY": "sk-session-token"
  }
}

说明：

• ANTHROPIC_BASE_URL 指向本地代理地址。Claude Code 的所有 API 请求都会发到这里。
• ANTHROPIC_API_KEY 代理不校验其真实性，填任意值即可。
• 不要在全局设置中配置，只在项目级别配置，避免影响其他使用场景。

4.2 验证连通性

在 Claude Code Desktop 中发送一条消息，确认能正常返回。

4.3 日志排查

如果遇到问题，启用调试日志再次启动代理：

set DEBUG_PROXY=true
node anthropic-proxy.mjs

查看日志中的关键信息：

• 模型映射是否匹配：Model mapping: claude-sonnet-4-6 → deepseek-v4-flash
• 上游返回状态码：非 200 说明上游有问题
• 请求体中的消息数量和工具数量

第五章：常见安装故障修复 — 卸载 OneDrive 后 Claude 无法启动

问题现象

卸载 OneDrive 之后，Claude Desktop（或其他应用）点击图标无反应，无法启动。

根因

Windows 的 User Shell Folders 注册表中，Desktop、Documents 等路径仍然指向 C:\Users\xxx\OneDrive\Desktop 这类目录。OneDrive 被卸载后这些目录已不存在，Claude Desktop 启动时找不到标准文件夹路径，直接崩溃。

此外，旧版本 Claude 的残留文件也可能干扰新安装。

修复脚本

以下脚本会自动完成全部修复流程。将代码保存为 Fix-ClaudeDesktop-OneDrivePath.ps1，然后以管理员身份运行：

# ============================================================
# Fix-ClaudeDesktop-OneDrivePath.ps1
# 用途：修复卸载 OneDrive 后 Claude Desktop 无法启动的问题
# 原理：清理 User Shell Folders 中残留的 OneDrive 路径 + 清理 Claude 残留
# 运行：以管理员身份运行 PowerShell，然后执行本脚本
# ============================================================

# 0. 检查管理员权限
if (-NOT ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
    Write-Host "请以管理员身份运行 PowerShell 后再执行本脚本。" -ForegroundColor Red
    exit 1
}

$ErrorActionPreference = "Stop"
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
$backupDir = "$env:USERPROFILE\Desktop\ClaudeFix-Backup-$timestamp"
New-Item -ItemType Directory -Path $backupDir | Out-Null
Write-Host "备份目录：$backupDir" -ForegroundColor Cyan

# 1. 备份注册表 User Shell Folders / Shell Folders
Write-Host "`n[1/5] 备份注册表 ..." -ForegroundColor Yellow
reg export "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" "$backupDir\UserShellFolders.reg" /y | Out-Null
reg export "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders"      "$backupDir\ShellFolders.reg"     /y | Out-Null
Write-Host "  注册表已备份。"

# 2. 修正 User Shell Folders 中含 OneDrive 的路径
Write-Host "`n[2/5] 扫描并修正 User Shell Folders 中的 OneDrive 路径 ..." -ForegroundColor Yellow
$keys = @(
    "HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders",
    "HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders"
)
foreach ($key in $keys) {
    $props = Get-ItemProperty -Path $key
    foreach ($name in $props.PSObject.Properties.Name) {
        if ($name -like "PS*") { continue }
        $value = $props.$name
        if ($value -is [string] -and $value -match "OneDrive") {
            $newValue = $value -replace "([A-Za-z]:\\Users\$\^$\$+|%USERPROFILE%)\\OneDrive(?:\s-\s[^\\]+)?\\", "%USERPROFILE%\"
            if ($newValue -ne $value) {
                Write-Host "  [$key] $name" -ForegroundColor Green
                Write-Host "    旧: $value"
                Write-Host "    新: $newValue"
                Set-ItemProperty -Path $key -Name $name -Value $newValue
            }
        }
    }
}

# 3. 确保本地默认文件夹存在
Write-Host "`n[3/5] 确保本地默认文件夹存在 ..." -ForegroundColor Yellow
$folders = @("Desktop","Documents","Downloads","Pictures","Music","Videos","Favorites")
foreach ($f in $folders) {
    $p = Join-Path $env:USERPROFILE $f
    if (-not (Test-Path $p)) {
        New-Item -ItemType Directory -Path $p | Out-Null
        Write-Host "  已创建: $p"
    }
}

# 4. 卸载 Claude Desktop(若存在)并清理残留目录
Write-Host "`n[4/5] 卸载 Claude Desktop 并清理残留 ..." -ForegroundColor Yellow
try {
    $pkg = Get-AppxPackage -Name "*Claude*" -ErrorAction SilentlyContinue
    if ($pkg) {
        $pkg | Remove-AppxPackage
        Write-Host "  已卸载 MSIX 包: $($pkg.Name)"
    } else {
        Write-Host "  未检测到 MSIX 形式的 Claude(可能是 exe 安装,请手动到'已安装的应用'中卸载)。"
    }
} catch {
    Write-Host "  卸载 MSIX 包失败: $_" -ForegroundColor Red
}

$residue = @(
    "$env:LOCALAPPDATA\AnthropicClaude",
    "$env:LOCALAPPDATA\Claude",
    "$env:APPDATA\Claude",
    "$env:APPDATA\AnthropicClaude"
)
foreach ($d in $residue) {
    if (Test-Path $d) {
        Copy-Item $d "$backupDir\" -Recurse -Force -ErrorAction SilentlyContinue
        Remove-Item $d -Recurse -Force -ErrorAction SilentlyContinue
        Write-Host "  已清理: $d (已备份到 $backupDir)"
    }
}

# 5. 完成提示
Write-Host "`n[5/5] 完成!" -ForegroundColor Green
Write-Host "请执行以下两步:" -ForegroundColor Cyan
Write-Host "  1) 重启电脑(必须,让 Explorer 重新加载 Shell Folders)"
Write-Host "  2) 从 https://claude.ai/download 重新下载并以管理员身份安装 Claude Desktop"
Write-Host "`n如出现异常,可双击 $backupDir 下的 .reg 文件恢复注册表。" -ForegroundColor Cyan

脚本执行流程

恢复方法

如果修复后出现异常，双击桌面备份目录中的 .reg 文件即可恢复注册表到修复前的状态。

与第一章的配合

如果遇到了 OneDrive 卸载导致的问题，正确的完整流程是：

# 第 1 步：运行本修复脚本（清理注册表 + 卸载旧版 Claude）
# （以管理员身份运行 Fix-ClaudeDesktop-OneDrivePath.ps1）

# 第 2 步：重启电脑

# 第 3 步：重新安装 Claude Desktop
winget install Anthropic.Claude

# 第 4 步：MSIX 覆盖安装（修正 Cowork 安装来源）
Invoke-WebRequest -Uri "https://claude.ai/api/desktop/win32/x64/msix/latest/redirect" -OutFile "Claude.msix"
Add-AppxPackage -Path "Claude.msix"

之后再按后续章节配置代理即可。

常见问题排查

Q1：Claude Code 启动时报 “No available models”

原因：代理未启动或 ANTHROPIC_BASE_URL 配置错误。

解决：

# 确认代理正在运行
curl http://127.0.0.1:8080/v1/models

# 确认配置的 URL 可访问
curl http://127.0.0.1:8080/health

Q2：请求返回 401 Unauthorized

原因：Session Token 过期或无效。

解决：重新运行 get-session.cjs 获取最新 token，或用 --watch 模式监控变化。

Q3：请求返回 502 Bad Gateway

原因：上游 loomyad.xunfei.cn 不可达。

解决：

# 测试网络连通性
ping loomyad.xunfei.cn

# 检查是否需要代理上网

Q4：端口被占用

原因：8080 端口已被其他程序占用。

解决：

set PROXY_PORT=9090
node anthropic-proxy.mjs

同时在 Claude Code Desktop 配置中将 ANTHROPIC_BASE_URL 改为 http://127.0.0.1:9090。

Q5：工具调用（Tool Use）失败

原因：上游模型不支持某些工具调用格式。

解决：检查 get-session.cjs --env 输出的 session 是否有效，以及上游 iModel 是否支持 function calling。

附录

完整启动流程速查

# 1. 确保 Loomy 桌面端已登录

# 2. 启动代理
cd "C:\Users\Administrator\Documents\Loomy Workspace"
node anthropic-proxy.mjs

# 3. 保持终端窗口打开，另开一个窗口启动 Claude Code Desktop
# 4. 确保 claude_desktop_config.json 中已配置：
#    ANTHROPIC_BASE_URL=http://127.0.0.1:8080
#    ANTHROPIC_API_KEY=sk-session-token

文件清单

参考链接

• Claude Desktop Windows 部署指南
• Loomy 官网

这个主题是我在业余时间开发的，文档可能不够全面，但我会尽力解释。

前提条件

在开始之前，请确保你的开发环境中已安装以下工具：

• Node.js - 运行开发环境所必需。
• pnpm - 我们首选的包管理器，用于依赖管理。
• Git - 用于版本控制和项目管理。
• VS Code - 推荐使用的代码编辑器，开发体验极佳。

启动项目

有两种方式：

• Fork 仓库
• 使用此模板 - 将来会推出无内容分支，无需删除和替换内容。

获取你自己的仓库后，可以将其克隆到本地。

更新主题

当主题发布新版本时，你可以按照以下步骤拉取最新更改而不丢失内容：

1. 添加 upstream 远程（只需一次）

git remote add upstream https://github.com/Dnzzk2/Litos.git

2. 获取并合并最新的主题

git fetch upstream
git merge upstream/main --no-edit

3. 解决冲突（如有）

冲突通常只发生在你修改过的文件中，例如 src/config.ts。在这种情况下，只需保留你自己的配置，接受其余的主题更新即可。

结束

后续文档将分为多个页面，如 readme、posts…

以下文件与此文档兼容：

• src/pages/index.astro - readme 页面。
• src/config.ts - readme 页面配置。
• src/components/base - 大部分组件来自这里。

站点配置

配置基本站点信息：

export const SITE: Site = {
  title: 'Litos',
  description: 'Litos is a blog theme built with Astro.js and 夜猫子Ai手记.',
  website: 'https://litos.vercel.app/',
  lang: 'en',
  base: '/',
  author: '夜猫子Ai手记',
  ogImage: '/og-image.jpg',
}

顶部链接

顶部跳转链接组件配置：

export const HEADER_LINKS: Link[] = [
  {
    name: 'Posts',
    url: '/posts',
  },
]

底部链接

底部链接组件配置：

export const FOOTER_LINKS: Link[] = [
  {
    name: 'Readme',
    url: '/',
  },
]

社交链接

在 readme 页面中，你可以在主题介绍下方看到一排图标，可以通过以下方式配置。图标来自 Iconify。

export const SOCIAL_LINKS: SocialLink[] = [
  {
    name: 'github',
    url: 'https://github.com/yourname',
    icon: 'icon-[ri--github-fill]',
    count: 11,
  },
  {
    name: 'twitter',
    url: 'https://x.com/yourname',
    icon: 'icon-[ri--twitter-x-fill]',
  },
]

聚光灯

技能展示

在 readme 页面中，你可以看到一个技能展示区域，可以通过配置以下代码来展示你的技能：

export const SKILLSSHOWCASE_CONFIG: SkillsShowcaseConfig = {
  SKILLS_ENABLED: true,
  SKILLS_DATA: [
    {
      direction: 'left',
      skills: [
        {
          name: 'JavaScript',
          icon: 'icon-[mdi--language-javascript]',
        },
        {
          name: 'CSS',
          icon: 'icon-[mdi--language-css3]',
        },
        {
          name: 'HTML',
          icon: 'icon-[mdi--language-html5]',
        },
        {
          name: 'TypeScript',
          icon: 'icon-[mdi--language-typescript]',
        },
      ],
    },
  ],
}

文章

这里主要展示置顶文章。如果没有置顶文章，我们将根据 POSTS_CONFIG 显示最新 size 数量的文章。

以下文件与此文档兼容：

• src/pages/posts/[...id].astro - 文章具体内容显示页面。
• src/pages/posts/[...page].astro - 文章列表页面。
• src/content/posts - 文章集合
• src/content.config.ts - 文章数据集和前置数据配置。
• ec.config.mjs - expressiveCode 配置。
• plugins/index.ts - remark 和 rehype 插件。
• src/config.ts - 文章页面配置。
• src/components/posts - 大部分组件来自这里。

文章页面配置

文章页面配置如下：

export const POSTS_CONFIG: PostConfig = {
  title: '文章',
  description: '夜猫子Ai手记的文章',
  introduce: '在这里，我将分享本主题的使用说明，帮助你快速上手。',
  author: '夜猫子Ai手记',
  homePageConfig: {
    size: 3,
    type: 'compact',
  },
  postPageConfig: {
    size: 10,
    type: 'minimal',
  },
  tagsPageConfig: {
    size: 10,
    type: 'time-line',
  },
  ogImageUseCover: false,
  postType: 'metaOnly',
  imageDarkenInDark: true,
  readMoreText: '阅读更多',
  prevPageText: '上一页',
  nextPageText: '下一页',
  tocText: '目录',
  backToPostsText: '返回文章列表',
  nextPostText: '下一篇',
  prevPostText: '上一篇',
  recommendText: '推荐',
}

以下是一些配置属性的详细说明，请参考下表。

Type 和 PostType

在上面的文档中，我们提到了可配置的 types 用于配置 readme 页面、文章页面和标签页面的列表数据显示样式，以及可配置的 postTypes 用于在文章内容页面顶部显示元数据。

以下是 type 的具体样式展示：

以下是 postType 的具体样式展示：

前置数据

讨论完文章列表和整体设计后，让我们一起看看文章的内容。这些内容都在 src/content/posts 文件夹中。

下面是文章内容的前置数据：

---
title: 'Litos: Posts Page Config'
description: ''
pubDate: 2025-08-13
author: '夜猫子Ai手记'
recommend: true
tags: ['Litos', 'Documentation']
---

你可以通过以下代码配置文章内容的前置数据：

const posts = defineCollection({
  loader: glob({
    pattern: '**/*.{md,mdx}',
    base: './src/content/posts',
  }),
  schema: ({ image }) =>
    z
      .object({
        title: z.string(),
        description: z.string(),
        pubDate: z.date(),
        tags: z.array(z.string()).optional(),
        updatedDate: z.date().optional(),
        author: z.string().default(POSTS_CONFIG.author),
        cover: image().optional(),
        ogImage: image().optional(),
        recommend: z.boolean().default(false),
        postType: z.custom<PostType>().optional(),
        coverLayout: z.custom<CoverLayout>().optional(),
        pinned: z.boolean().default(false),
        draft: z.boolean().default(false),
      })
      .transform((data) => ({
        ...data,
        ogImage: data.ogImage ? data.ogImage : POSTS_CONFIG.ogImageUseCover && data.cover ? data.cover : undefined,
      })),
})

语法和代码样式

本指南将通过一个 3 天城市旅行行程来展示如何使用 Markdown 格式化文本。在规划行程的同时学习 Markdown！

标题级别

对于旅行笔记，多级标题有助于组织天数、时间块和提示：

文本格式化

撰写旅行笔记时，突出重要信息：

必看景点 应加粗 灵活时间 使用斜体 重要警告 可以同时使用 可选绕路 使用删除线

行李清单（无序列表）

• 护照、签证
• 相机、备用电池
  • 带一个快充充电器
  • 备用 SD 卡
• 可重复使用的水瓶
• 公共交通卡

第一天行程（有序列表）

1. 机场 → 酒店入住
2. 老城徒步之旅
3. 夜间游船
   1. 提前 15 分钟到达
   2. 在 B 入口排队
   3. 推荐靠窗座位

1. 机场 → 酒店入住
2. 老城徒步之旅
3. 夜间游船
   1. 提前 15 分钟到达
   2. 在 B 入口排队
   3. 推荐靠窗座位

Blockquotes

旅行者提示：如果你一天要乘坐 3 次以上地铁，建议购买 24 小时通票。

将酒店地址保存到离线地图中以便快速查找。

> 旅行者提示：如果你一天要乘坐 3 次以上地铁，建议购买 24 小时通票。
>
> 将酒店地址保存到离线地图中以便快速查找。

代码块

使用简单的代码来估算预算：

type Budget = { flight: number; hotel: number; meals: number; transport: number }
export const total = (b: Budget) => b.flight + b.hotel + b.meals + b.transport

console.log(total({ flight: 1200, hotel: 450, meals: 180, transport: 60 })) // 1890

表格

示例行程：

链接和图片

更多提示：官方旅游委员会

旅行照片：

水平分隔线

行内代码

地铁 A 线在高峰期每 5-7 分钟一班。

数学公式

每日预算估算：budget=hotel+meals+transportbudget = hotel + meals + transportbudget=hotel+meals+transport

总行程：

任务列表

出行前检查清单：

• 预订航班
• 预订酒店
• 购买地铁通票
• 下载离线地图

脚注

本行程参考了当地旅游指南（点击脚注）¹。

Expressive-code 配置

在 Markdown 文档中，我们使用代码块来显示代码片段和其他内容。本文档介绍如何自定义代码块配置。

本主题的代码块使用 Expressive Code 进行配置，所有配置选项都在 ec.config.mjs 文件中定义。以下是主要配置选项：

import { defineEcConfig } from 'astro-expressive-code'
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'

export default defineEcConfig({
  defaultLocale: 'zh-CN',
  defaultProps: {
    wrap: false,
    collapseStyle: 'collapsible-auto',
    showLineNumbers: false,
    preserveIndent: true,
  },
  minSyntaxHighlightingColorContrast: 0,

  styleOverrides: {
    uiFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    uiFontSize: '1em',
    codeFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    codeFontSize: '14px',
    codeLineHeight: '1.4',
    borderRadius: '0',
    codePaddingBlock: '0.8571429em',
    codePaddingInline: '1.1428571em',
    borderColor: ({ theme }) => (theme.type === 'dark' ? '#24273a' : '#e6e9ef'),

    frames: {
      frameBoxShadowCssValue: false,
      inlineButtonBackgroundActiveOpacity: '0.2',
      inlineButtonBackgroundHoverOrFocusOpacity: '0.1',
    },
    textMarkers: {
      backgroundOpacity: '0.2',
      borderOpacity: '0.4',
    },
  },

  plugins: [
    pluginCollapsibleSections({
      defaultCollapsed: false,
    }),
    pluginLineNumbers(),
  ],

  themes: ['catppuccin-macchiato', 'catppuccin-latte'],
  themeCssSelector: (theme) => (theme.name === 'catppuccin-macchiato' ? '.dark' : ':root:not(.dark)'),
  useDarkModeMediaQuery: false,
  useStyleReset: false,
})

你可以访问该网站查看 expressive-code 的配置选项。

评论系统 (Gitalk)

该主题内置了 Gitalk 评论系统，使用 GitHub Issues 作为评论后端。每篇文章会自动获得自己的 Issues 用于评论。

前提条件

首先你需要创建一个 GitHub OAuth App：

1. 前往 GitHub 开发者设置 → OAuth Apps → New OAuth App。
2. 填写表单：
   • Application name：任意名称（例如 My Blog Comments）
   • Homepage URL：你的站点 URL（例如 https://yourdomain.com）
   • Authorization callback URL：与你的站点 URL 相同
3. 创建后，复制 Client ID 并生成 Client Secret。
4. 在 GitHub 上创建一个 公开仓库 用于存储评论 Issues（例如 blog-comments）。

配置

在 src/config.ts 中配置评论系统：

export const COMMENT_CONFIG: CommentConfig = {
  enabled: true,
  system: 'gitalk',
  gitalk: {
    clientID: import.meta.env.PUBLIC_GITHUB_CLIENT_ID,
    clientSecret: import.meta.env.PUBLIC_GITHUB_CLIENT_SECRET,
    repo: 'blog-comments',
    owner: 'YourGitHubUsername',
    admin: ['YourGitHubUsername'],
    language: 'en-US',
    perPage: 5,
    pagerDirection: 'last',
    createIssueManually: false,
    distractionFreeMode: false,
    enableHotKey: true,
  },
}

然后设置环境变量。在项目根目录创建 .env 文件（参考 .env.example）：

PUBLIC_GITHUB_CLIENT_ID=your-github-client-id
PUBLIC_GITHUB_CLIENT_SECRET=your-github-client-secret

配置属性

本指南在 markdown-mdx-extended-features 的基础上做了少量修改。

标注框（Callouts）

由 rehype-callouts 插件支持，可在 plugins/index.ts 中配置该插件。

若修改了 theme 配置（默认值为 'vitepress'），还需同步更新 src/styles/pro.css 中引入的 CSS 文件（@import 'rehype-callouts/theme/你的配置'）。

<!-- 标注框类型名称不区分大小写：'Note'、'NOTE' 和 'note' 等价。 -->

<!-- vitepress -->

<!-- 这是一个不可折叠的标注框 -->

> [!note]
> 注意内容。

> [!tip]
> 提示内容。

> [!important]
> 重要内容。

> [!warning]
> 警告内容。

> [!caution]
> 注意内容。

> [!caution]- 这是一个**可折叠**的标注框
> 注意内容。

> [!note]+ 这是一个**可折叠**的标注框
> 注意内容。
> ` ` `

> [!note]
> 注意 `内容`。

> [!tip]
> 提示 `内容`。

> [!important]
> 重要 `内容`。

> [!warning]
> 警告 `内容`。

> [!caution]
> 注意 `内容`。

> [!caution]- 这是一个**可折叠**的标注框
> 注意内容。

> [!note]+ 这是一个**可折叠**的标注框
> 注意内容。

## 全功能代码块

由 astro-expressive-code 支持，并集成 [@expressive-code/plugin-collapsible-sections](https://expressive-code.com/plugins/collapsible-sections/) 和 [@expressive-code/plugin-line-numbers](https://expressive-code.com/plugins/line-numbers/) 插件，为代码块添加样式和额外功能。

如需自定义代码块主题或功能，请在查阅 Expressive Code 配置文档 后，修改项目根目录下的 `ec.config.mjs` 文件，例如：[更换主题](https://expressive-code.com/guides/themes/#using-bundled-themes)、[启用自动换行](https://expressive-code.com/key-features/word-wrap/#wrap) 或 [切换行号显示](https://expressive-code.com/plugins/line-numbers/#showlinenumbers)。

以下是功能快速预览，详细说明请查阅 [详细指南](https://expressive-code.com/key-features/syntax-highlighting/)。

#### 语法高亮

` ` `js title='example.md'
console.log('This code is syntax highlighted!')
` ` `

##### 代码编辑器框架

` ` `js title="my-test-file.js"
// 使用 `title="my-test-file.js"`console.log('Title attribute example')` ` `

` ` `ts
// src/content/index.ts
// 使用 `// src/content/index.ts`console.log('File name comment example')` ` `

##### 终端框架

` ` `bash
echo "此终端框架没有标题"
` ` `

` ` `powershell title="PowerShell terminal example"
Write-Output "这个有标题！"
` ` `

##### 标记整行与行范围

` ` `js {1, 4, 7-8}
// 第 1 行 - 按行号指定
// 第 2 行
// 第 3 行
// 第 4 行 - 按行号指定
// 第 5 行
// 第 6 行
// 第 7 行 - 按范围 "7-8" 指定
// 第 8 行 - 按范围 "7-8" 指定
` ` `

##### 选择行标记类型（mark、ins、del）

` ` `js title="line-markers.js" del={2} ins={3-4} {6}
function demo() {
console.log('此行标记为已删除')
// 此行及下一行标记为已插入
console.log('这是第二行已插入的内容')

return '此行使用默认中性标记类型'
}
` ` `

##### 使用类 diff 语法

` ` `diff
+此行将标记为已插入
-此行将标记为已删除
这是普通行
` ` `

` ` `diff lang="js"
function thisIsJavaScript() {
// 整个代码块以 JavaScript 高亮显示，
// 同时仍可添加 diff 标记！

- console.log('待删除的旧代码')

* console.log('全新的代码！')
  }
  ` ` `

##### 按代码块配置自动换行

` ` `js 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'
}
` ` `

` ` `js 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'
}
` ` `

##### 可折叠区域

` ` `js collapse={1-5, 12-14, 21-24}
// 所有样板初始化代码将被折叠
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// 此部分代码默认可见
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
const a = 1
const b = 2
const c = a + b
console.log(`Calculation result:  +  = `)
return c
}

engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })
` ` `

##### 按代码块显示行号

` ` `js showLineNumbers
// 此代码块将显示行号
console.log('来自第 2 行的问候！')
console.log('我在第 3 行')
` ` `

` ` `js showLineNumbers startLineNumber=5
// 更改起始行号
console.log('来自第 5 行的问候！')
console.log('我在第 6 行')
` ` `

## 图片说明与链接

使用 :link[remark-directive-sugar]{#lin-stephanie/remark-directive-sugar .github} 中的 [`:::image`](https://github.com/lin-stephanie/remark-directive-sugar?tab=readme-ov-file#image-) 指令，将图片包裹在容器中以支持说明文字、可点击链接等功能。可通过 `plugins/index.ts` 中的 `image` 选项进行自定义，样式写在 `src/styles/pro.css` 的 `/* :::image */` 部分。

### image-figure

` ` `md title=':::image-figure.md'
:::image-figure[这是带有 **Figcaption** 和 `<figure>` 属性的示例]{style="text-align:center;color:orange"}
![](assets/cover.png)
:::

:::image-figure[这是带有 **figcaption** 和 `<img>` 属性的示例。]
![](assets/cover.png)(style: width:600px;)
:::

<!-- 💡 使用 `(class:no-zoom)` 禁用缩放 -->

:::image-figure[这是带有 `class:no-zoom` 的示例。]
![](assets/cover.png)(class:no-zoom)
:::

<!-- 💡 若没有 `[caption]`，将使用 `[alt]` 作为 figcaption。 -->

:::image-figure
![若未设置 `[caption]`，alt 文本将作为 figcaption 使用。](assets/cover.png)
:::

<!-- ❌ 若 figcaption 没有可用文本，则无法生效。 -->

` ` `

> [!warning]
> 直接设置图片的 `width` 属性可能导致模糊。[了解更多](https://github.com/Dnzzk2/Litos/discussions/17)

### image-a

` ` `md title=':::image-a.md'
:::image-a{href="https://github.com/Dnzzk2/Litos"}
![OG image](assets/cover.png)
:::

<!-- ❌ 未提供外部链接时无法生效。-->

:::image-a
![OG image](assets/cover.png)
:::
` ` `

### image-figure-polaroid

` ` `md title=':::image-figure-polaroid.md'
:::::image-div-polaroid
:::image-figure-polaroid[这是带有 **figcaption** 和 `<img>` 属性的示例。]
![OG image](assets/cover.png)
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid{style="width:500px;"}
![OG image](assets/cover.png)
:::
:::::
` ` `

## GitHub 卡片

感谢 :link[oopsunix]{#@oopsunix} 的贡献！

` ` `md title=':::github-card.md'
::github{repo="Dnzzk2/Litos"}
` ` `

## 视频嵌入

使用 remark-directive-sugar 中的 [`::video`](https://github.com/lin-stephanie/remark-directive-sugar?tab=readme-ov-file#video-) 指令，统一嵌入不同平台的视频。

` ` `md title='example.md'

<!-- 嵌入 YouTube 视频 -->

::video-youtube{#gxBkghlglTg}

<!-- 嵌入 Bilibili 视频，并自定义 `title` 属性 -->

::video-bilibili[自定义标题]{id=BV1MC4y1c7Kv}

<!-- 嵌入 Vimeo 视频，使用 `no-scale` 类禁用缩放 -->

::video-vimeo{id=912831806 class='no-scale'}

<!-- 嵌入自定义视频 URL（必须使用 `id`，不能用 `#`） -->

::video{id=https://www.youtube-nocookie.com/embed/gxBkghlglTg}
` ` `

## 样式链接（`:link`）

使用 remark-directive-sugar 中的 [`:link`](https://github.com/lin-stephanie/remark-directive-sugar?tab=readme-ov-file#link) 指令，为 GitHub、npm 或自定义 URL 添加带头像或图标的链接。

**链接到 GitHub 用户或组织（在 `id` 前加 `@`）​**

- **示例 1**：`:link[Dnzzk2]{#@Dnzzk2}` 链接到项目维护者的 GitHub 主页，如 :link[Dnzzk2]{#@Dnzzk2}。
- **示例 2**：`Vite` 链接到 Vite 组织的 GitHub 主页。
- **示例 3**：`:link{#@Dnzzk2 tab=repositories}` 直接链接到该用户的仓库标签页，如 :link{#@Dnzzk2 tab=repositories}。有效 `tab` 选项：`'repositories'`、`'projects'`、`'packages'`、`'stars'`、`'sponsoring'`、`'sponsors'`。
- **示例 4**：`:link{#@vitejs tab=org-people}` 链接到组织成员页面，如 :link{#@vitejs tab=org-people}。有效 `tab` 选项：`'org-repositories'`、`'org-projects'`、`'org-packages'`、`'org-sponsoring'`、`'org-people'`。

**链接到 GitHub 仓库**

- **示例 5**：`:link[Astro]{#withastro/astro}` 创建指向 :link[Astro]{#withastro/astro} 仓库的链接。

**链接到 npm 包**

- **示例 6**：`:link{#remark-directive-sugar}` 链接到 :link{#remark-directive-sugar} 的 npm 主页。
- **示例 7**：`:link{id=remark-directive-sugar tab=dependencies}` 链接到 npm 上的 :link{id=remark-directive-sugar tab=dependencies} 页面。有效 `tab` 选项：`'readme'`、`'code'`、`'dependencies'`、`'dependents'`、`'versions'`。

**链接到自定义 URL（必须使用 `id`，不能用 `#`）​**

- **示例 8**：`:link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript}` 创建指向 :link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript} 的外部链接。
- **示例 9**：`Google` 创建指向 Google 的外部链接。

**自定义**

- **示例 10**：`Vite` 将链接指向 `https://vite.dev/`，如 Vite。
- **示例 11**：`Vite` 显示自定义 Logo，如 Vite。
- **示例 12**：`:link{id=Dnzzk2/Litos class=github}` 使用 `class=github` 覆盖默认样式，如 :link{id=Dnzzk2/Litos class=github}。
- **示例 13**：`Litos Themes` 完全自定义一个链接，如 Litos Themes。

## 徽章（Badges）

使用 remark-directive-sugar 中的 [`:badge`](https://github.com/lin-stephanie/remark-directive-sugar?tab=readme-ov-file#badge-) 指令，显示状态或分类等小型信息片段。

主题预定义徽章如下，可通过 `plugins/index.ts` 中的 `badge` 选项自定义，样式写在 `src/styles/pro.css` 的 `/* :badge */` 部分：

- `badge-n`：:badge-n

也可直接使用 `:badge[文字]{属性}` 自定义外观。例如：`:badge[ISSUE]{style="background-color: #bef264"}` 将显示为 :badge[ISSUE]{style="background-color: #bef264"}。若未指定颜色，默认外观如 :badge[This] 所示。

## 详情折叠（Details Dropdown）

` ` `md title=':::details.md'
:::details
::summary[详情折叠]

- 列表项 1
- 列表项 2
- 列表项 3
- 列表项 4
  :::
  ` ` `

此外，它也支持类似 [remark-directive 示例](https://github.com/remarkjs/remark-directive?tab=readme-ov-file#use) 中的用法。

由于项目和标签页配置内容较少，因此合并为一个文档。

以下文件与此文档兼容：

• src/pages/projects/index.astro - 项目页面。
• src/pages/tags/index.astro - 标签统计页面。
• src/pages/tags/[tag]/[...page].astro - 特定标签的文章列表页面。
• src/config.ts - 项目和标签页配置。
• src/components/base - 大部分组件来自这里。

项目页面配置

配置页面文本：

export const PROJECTS_CONFIG: ProjectConfig = {
  title: 'Projects',
  description: 'The examples of my projects.',
  introduce: 'The examples of my projects.',
}

项目内容

项目页面显示的内容来自 /src/content/projects。

它的写作风格与文章类似：一个 MDX 文件代表一个项目。

项目前置数据

示例 (src/content/projects/Litos/index.mdx):

---
name: 'Litos'
description: 'A Simple & Modern Blog Theme for Astro.'
githubUrl: 'https://github.com/Dnzzk2/Litos'
website: 'https://litos.vercel.app/'
type: 'image'
icon: '../../../../public/projects/litos.png'
imageClass: 'w-10 h-10'
star: 32
fork: 7
---

标签页面配置

export const TAGS_CONFIG: TagsConfig = {
  title: 'Tags',
  description: 'All tags of Posts',
  introduce: 'All the tags for posts are here, you can click to filter them.',
}

本文档描述了照片页面的当前实现。

当前文件结构

• src/pages/photos/index.astro
  • 从 PHOTOS_CONFIG 读取页面文本
  • 从 PhotosList 读取时间线数据
• src/config.ts
  • 存储 PHOTOS_CONFIG
• src/lib/photos.ts
  • 存储 PhotosList
  • 自动导入照片文件
  • 将一个文件夹的图片转换为 Photo[]，使用 getPhotos()
• src/types.ts
  • 定义 PhotoData、Photo 和 PolaroidVariant
• src/components/photos/PolaroidCard.tsx
  • 将每个 variant 映射到实际的卡片尺寸

页面文本

页面标题和介绍文本来自 src/config.ts。

export const PHOTOS_CONFIG: PhotosConfig = {
  title: 'Photos',
  description: 'Here I will record some photos taken in daily life.',
  introduce: 'Here I will record some photos taken in daily life.',
}

src/pages/photos/index.astro renders the page like this:

---
import { PHOTOS_CONFIG } from '~/config'
import { PhotosList } from '~/lib/photos'

const { title, description, introduce } = PHOTOS_CONFIG
---

<Layout {title} {description}>
  <PageTitle {title} {introduce} />
  <PhotoTimeline photoData={PhotosList} />
</Layout>

PhotosList

PhotosList 在 src/lib/photos.ts 中定义。每一项是一个时间线条目。

export const PhotosList: PhotoData[] = [
  {
    title: 'Ningbo - Botanical Garden',
    icon: { type: 'emoji', value: '🌼' },
    description: 'It was early spring, so I went to see the cherry blossoms.',
    date: '2026-03-07',
    travel: '',
    photos: getPhotos('2026-03-07-botanicalGarden', 'Early spring cherry blossoms at the botanical garden', [
      '3x4',
      '3x4',
      '3x4',
      '3x4',
      '3x4',
      '3x4',
    ]),
  },
]

PhotoData 字段

getPhotos() 的工作原理

当前实现：

function getPhotos(dir: string, alt: string, variants: PolaroidVariant[]): Photo[] {
  return Object.entries(photoModules)
    .filter(([path]) => path.includes(`/${dir}/`))
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([, mod], index) => {
      const img = mod.default
      return {
        src: img,
        alt,
        width: img.width,
        height: img.height,
        variant: variants[index] || '4x3',
      }
    })
}

参数含义

重要行为

1. getPhotos() 首先按文件夹名称过滤所有导入的图片。
2. 然后使用 localeCompare 对匹配的文件路径进行排序。
3. 按排序顺序创建最终的 Photo[]。
4. variants[index] 应用于相同索引的图片。
5. 如果 variants 中缺少某个索引，该图片将回退到 '4x3'。

第三个参数如何匹配

第三个参数不是随机元数据。它是基于位置的。

对于以下代码：

photos: getPhotos('2026-03-07-botanicalGarden', 'Early spring cherry blossoms at the botanical garden', [
  '3x4',
  '3x4',
  '3x4',
  '3x4',
  '3x4',
  '3x4',
])

假设文件夹 src/assets/photos/2026-03-07-botanicalGarden/ 排序后包含以下文件：

01.webp
02.webp
03.webp
04.webp
05.webp
06.webp

那么映射关系是：

因此，如果你想让文件夹中的第一张照片使用 3x4，第三个数组的第一个元素必须是 3x4。

如果你想混合比例，请按照排序文件的相同顺序编写：

photos: getPhotos('2025-03-01-dongqianhu', 'Ningbo - Dongqian Lake', ['4x5', '1x1', '4x3'])

这意味着：

• 第一张排序后的图片 -> 4x5
• 第二张排序后的图片 -> 1x1
• 第三张排序后的图片 -> 4x3

如果文件夹中的照片多于数组长度：

photos: getPhotos('example-folder', 'Example alt', ['3x4', '4x5'])

那么：

• 第一张排序后的图片 -> 3x4
• 第二张排序后的图片 -> 4x5
• 第三张及之后的图片 -> 默认 4x3

支持的比例

当前 PolaroidVariant 为：

export type PolaroidVariant = '1x1' | '4x5' | '4x3' | '3x4' | '9x16'

src/components/photos/PolaroidCard.tsx 中的当前尺寸映射：

const polaroidVariants: Record<PolaroidVariant, string> = {
  '1x1': 'w-20 h-20',
  '4x5': 'w-20 h-24',
  '4x3': 'w-20 h-16',
  '3x4': 'w-[4.5rem] h-24',
  '9x16': 'w-20 h-32',
}

如何添加新的时间线条目

1. 在 src/assets/photos/ 下创建一个文件夹，例如 2026-04-01-spring-walk。
2. 将图片文件放入该文件夹。
3. 确保文件名按照排序后的顺序排列。
4. 在 src/lib/photos.ts 中向 PhotosList 添加一项。
5. 将第三个参数按照排序文件的相同顺序传递给 getPhotos()。

示例：

{
  title: 'Spring Walk',
  icon: { type: 'emoji', value: '🌿' },
  description: 'A short walk with a camera.',
  date: '2026-04-01',
  travel: '',
  photos: getPhotos(
    '2026-04-01-spring-walk',
    'Photos from a spring walk',
    ['3x4', '4x3', '4x5', '4x3']
  ),
}

注意事项

• alt 应用于从同一文件夹返回的每张照片。
• 顺序由排序后的文件路径决定，而不是编辑器中的导入顺序。
• 如果重命名文件，排序顺序可能会改变，variants 数组将映射到不同的照片。