从 One API 到 xxg Agent：v-p-s-stack 编程 Agent 搭建全记录

本文整理自 Cursor 会话（37d658fc-04bc-4d1d-8efa-20f2f840f6e1），仓库：v-p-s-stack（VPS 107.161.82.10）。完整逐条对话见同目录 conversation-full.md（241 条消息）。

# 背景

目标：在自有 VPS + One API 中转栈上，搭建类似 Cursor / Codex 的编程 Agent 系统——能稳定改代码、做复杂需求，而不是只做 API 转发。

栈组成：

• One API + 多渠道 Gemini / Mistral / Groq
• Caddy + chat-auth + 静态站（model-usage、network-status 等）
• 本机 aider / 自研 xxg CLI

# 路线图与完成度

阶段	目标	状态
0	aider + One API + AGENTS.md	✅
1	流程与约定（部分合并在 0/AGENTS）	部分
2	自研 xxg CLI（工具循环）	✅
3	CODEMAP、相关文件收集	✅
4	改后自动验证、失败重试	✅
5（精简）	VS Code 扩展、多用户、模型策略	✅
5（Web 控制台）	xxg serve + 网页	↩️ 已回退

# 阶段 0：aider 用到极致

• .aider.conf.yml：走 Caddy /v1，模型 openai/gemini-3.5-flash
• 密钥迁出 Git → .env / .env.aider.example
• 新增 .aiderignore、AGENTS.md、docs/aider-setup.md、scripts/aider-check.sh

要点： aider 必须用 openai/ 前缀；裸 mistral-medium-3-5 会报 LLM Provider NOT provided。

# 运维与页面（会话前期）

• Gemini 10 账号：One API 多条渠道、同模型轮询；坏号禁用即可
• model-usage / users-usage 404：需重建 chat-auth 镜像
• network-status：国际/国内连通 + 网速标签（缓慢/慢/快速/很快）
• Token vs 额度：quota 为 One API 计费点，非 1:1 token

# 阶段 2：xxg CLI

目录 xxg-coding-agent/，命令 xxg "自然语言任务"。

• 工具：read_file、search_code、write_patch、run_shell（白名单）
• Gemini 经 One API 不支持 OpenAI tools 字段 → 改为 prompt 模式（JSON 一行调工具）
• 验收：已成功 xxg "给 network-status 加导出 csv"

# 阶段 3：代码库理解

• 启动生成 .xxg/CODEMAP.md、.xxg/symbols.json
• collect_related / xxg related network-status 拉齐 auth-server + site + Caddyfile
• 新工具：get_codemap、find_symbol

# 阶段 4：验证闭环

• 改码后自动 node --check、docker compose config、npm test（按改动文件）
• 失败 stderr 回灌模型，最多 3 轮
• xxg --plan、xxg verify

# 阶段 5（精简版）

# 模型策略

xxg route "给 network-status 加导出 csv"
# → medium / gemini-3.5-flash

小任务 → gemini-2.5-flash-lite；含「重构」→ large 档。

# 多用户

• xxg --user alice、.xxg/users/<user>/logs/、每日配额 XXG_DAILY_LIMIT=20
• xxg runs / xxg whoami

# VS Code 扩展

• 目录 vscode-xxg/，离线包 xxg-agent-0.1.2.vsix
• 命令面板：xxg: 运行 Agent 任务 等
• 设置：xxg.envFile → v-p-s-stack 的 .env（跨项目如 rnFigma 时必配）

# 扩展踩坑（重要）

现象	原因	修复（0.1.2）
compinit: insecure directories	Mac zsh 配置	默认改输出面板跑，不用 zsh 终端
PATH 命令被截断	超长 export + zsh 报错粘连	用 bash --noprofile --norc
xg: command not found	手误少写 x	正确命令 xxg
跨项目无 Key	rnFigma 无 .env	xxg.envFile 指向 stack 的 .env

# 架构示意（当前推荐）

flowchart LR
  Dev[开发者]
  VSCode[VS Code 扩展 xxg-agent]
  CLI[xxg CLI]
  OneAPI[One API VPS]
  Repo[Git 仓库]

  Dev --> VSCode
  Dev --> CLI
  VSCode --> CLI
  CLI --> OneAPI
  CLI --> Repo

# 文件索引

路径	说明
xxg-coding-agent/	Agent 核心
vscode-xxg/	VS Code 扩展源码 + .vsix
docs/xxg-phase5.md	阶段 5 说明
docs/aider-setup.md	aider / One API 清单
AGENTS.md	AI 改码约定
blog/20260601-015429-v-p-s-stack-xxg-agent/conversation-full.md	完整对话

# 常用命令速查

# CLI
xxg "任务描述"
xxg route "任务"
xxg codemap
xxg verify
xxg --user alice "任务"

# 扩展
# Cmd+Shift+P → xxg: 运行 Agent 任务
# 输出面板 →「xxg Agent」

# 跨项目 bash 自测（绕过 zsh）
/bin/bash --noprofile --norc -c '
export PATH="$HOME/.local/node20/bin:$PATH"
set -a && source /path/to/v-p-s-stack/.env && set +a
xxg --cwd /path/to/other-project "列出目录结构"
'

# 后续建议

1. 修 zsh compaudit 权限，或长期用输出面板模式
2. 复杂重构继续 xxg --plan
3. 日常补全仍可用 Continue/Cline + One API /v1
4. Web 控制台版阶段 5 若需要，可单独分支再做

---

同目录 conversation-full.md 为未经删减的对话导出，供检索与审计。