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

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

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

目录h2

• 一、这套方案到底在做什么
• 二、四个组件各自扮演的角色
• 三、前置准备清单
• 四、详细部署步骤
  • 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 体验的进阶技巧
• 六、流量走向与历史记录管控
• 七、常见故障排查
• 八、心得体会与白嫖经验

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

如果你用过 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

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

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

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

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

OpenCode（实际干活的 Agent）h3

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

LongCat API（模型算力）h3

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

GitHub Codespaces（运行环境）h3

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

整体架构h3

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

三、前置准备清单h2

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

四、详细部署步骤h2

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

Step 1：申请 LongCat API Keyh3

1.1 注册并登录平台h4

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

1.2 创建 API Keyh4

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

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

1.3 记录关键信息h4

把以下三项信息记下来，后面 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 可用（可选但建议）h4

打开任何一台能联网的电脑，跑下面这条 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 并获取 Tokenh3

2.1 注册账号h4

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

2.2 创建 Workspaceh4

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

2.3 生成 Personal Access Token (PAT)h4

进入 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 仓库h3

这个仓库扮演两个角色：

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 Secretsh3

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

4.1 进入设置页h4

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

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

4.2 添加两个 Secreth4

点击 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.jsonh3

这是 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}",
  },
}

关键字段拆解h4

• 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（首次安装脚本）h3

把下面内容保存为 .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 "== 首次安装完成 =="

这一步的注意点h4

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

Step 7：编写 OpenCode 的 Provider 配置h3

让 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
}

字段拆解h4

• 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 是较保险的设置。

验证语法h4

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

cat opencode.json | jq .

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

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

这是真正每次唤醒 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 在线。"

这个脚本的几个关键设计h4

• 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 并验证h3

9.1 提交代码h4

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

9.2 创建 Codespaceh4

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

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

9.3 验证安装成功h4

容器起来后，在 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 上线h4

打开 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 并跑通第一个任务h3

10.1 创建 Agenth4

在 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 创建第一个 Issueh4

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

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

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

• Assignee: 选 Cody；
• 提交。

10.3 观察执行过程h4

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

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

10.4 在 Codespace 里验证产物h4

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

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

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

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

5.1 写一份高质量的 AGENTS.mdh3

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

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

## 项目概览

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

## 技术栈

- 语言: 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 模型选择策略h3

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

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

5.3 用 Skills 沉淀经验h3

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

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

# Skill: 添加单元测试

## 触发条件

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

## 步骤

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

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

5.4 Issue 模板h3

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

## 背景

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

## 目标

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

## 验收标准

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

## 约束

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

## 参考

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

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

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

在 Agent 的 system prompt 里加一句：

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

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

5.6 防止上下文打满h3

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

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

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

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

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

6.1 数据流向全景图h3

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

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

6.3 把 LongCat 流量监控起来h3

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 历史记录的导出与归档h3

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 敏感信息防泄露三原则h3

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

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

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

   gitleaks detect --source . -v

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

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

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

七、常见故障排查h2

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

7.1 Codespace 启动后 daemon 显示 offlineh3

可能原因：

• 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 不动h3

可能原因：

• 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”h3

可能原因：

• 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 返回 429h3

可能原因：

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

解决：

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

7.5 Codespace 配额告警h3

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 改坏了代码h3

预防：

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

事后：

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

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

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

八、心得体会与白嫖经验h2

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

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

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

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

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

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

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

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

• 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 是关键的”中立粘合剂”h3

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

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

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

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

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

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

8.5 这套方案的局限要承认h3

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

第一,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 写给打算跟进的人：三个不同的「野心档位」h3

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

档位一：个人玩具。完全照本教程,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 做廉价批量任务的兜底。这一档不再追求白嫖,但因为架构是解耦的,你随时可以根据成本和效果调整每一层。

写在最后h2

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

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

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

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