首页 / xxg Agent 五层架构与 Flutter 战场：从产品设计到 monorepo 落地

xxg Agent 五层架构与 Flutter 战场：从产品设计到 monorepo 落地

2026-06-02 17:00:00 约 8 分钟阅读

本文整理自 Cursor 会话（2026-06-02），仓库 v-p-s-stack。主题依次是：整体 Agent 是否可行、Flutter 垂直 Agent 如何更优秀、产品目录按五层重组并保留独立 CLI。飞书纪要见 xxg Agent 设计讨论纪要。

1. 背景：xxg 已经是什么

xxg 不是聊天壳，而是完整的 Agent Runtime：

能力	说明
执行环	prompt / native tool loop、工具 nudge、patch nudge、多轮会话
仓库理解	CODEMAP、symbols、`collect_related`、`.xxg/features.json`
改码	`write_patch`（精确 search/replace + 行号消歧）
闭环	verify loop：失败 → stderr 喂回 → 自动修复（最多 N 轮）
可靠性	One API 渠道轮换、503/429 重试、模型 fallback
入口	CLI + VS Code 侧栏、多用户、计划模式、jsonl 日志

与 Cursor Agent 的核心范式相同（LLM + tools + loop）。差距主要在：专有模型与超大上下文、全库 embedding、IDE 深度集成与生态——不宜正面硬刚「通用编程 Agent」。

2. 定位：在哪里可以「更优秀」

推荐定位：

面向团队 + 特定技术栈的「可验证、可审计、Convention-first」工程 Agent

差异化	说明
改码必验证	verify loop 是一等公民，不是事后插件
仓库画像	`features.json` + CODEMAP 对已知项目比通用索引更准
Convention 强制	`AGENTS.md`、Dart 格式、禁止改 `.env` 等可代码化
成本可控	自托管 One API 多渠道路由
可审计	`.xxg/users/<user>/logs/*.jsonl`
需求→交付	飞书需求、opt-prompt、PR 流水线可接入编排层

产品边界：xxg 做「改完且 verified」；Tab 补全 / 行内 Chat 仍交给 Continue/Cline + One API。

3. 五层目标架构

flowchart TB
  subgraph UI["① 交互层 apps/"]
    CLI["apps/cli · xxg 命令"]
    VSCode["apps/vscode · 侧栏扩展"]
  end

  subgraph Orch["② 编排层 orchestrator"]
    Pipe["classify / plan / subagent"]
  end

  subgraph RT["③ AgentRuntime @xxg/runtime"]
    Loop["tool loop / session / model"]
  end

  subgraph Ctx["④ 上下文 @xxg/context"]
    Map["CODEMAP / symbols / prompt"]
  end

  subgraph Grd["⑤ 落地层 @xxg/grounding"]
    Tools["tools / verify / dart format"]
  end

  subgraph Infra["同仓 infra/"]
    VPS["One API + Caddy + 静态站"]
  end

  CLI --> Orch
  VSCode --> Orch
  Orch --> RT
  RT --> Ctx
  RT --> Grd
  CLI -.-> VPS

依赖约束（硬规则）：

apps/*  →  orchestrator（待建）  →  runtime  →  context
                                    ↓
                                grounding → context

grounding、context 不依赖 runtime（可单测）
orchestrator 编排 runtime，不实现 tool loop 本体
VPS 中转栈与 Agent 产品同仓不同包：infra/ vs xxg/

4. Flutter 战场：为何先垂直

Flutter 项目结构相对规范（lib/、pubspec.yaml、路由），验证链清晰（dart analyze / flutter test）。Cursor 对「lib/pages/XxxView/view/ + domain/dto 分层」没有内置理解。

xxg-flutter 目标：

更快定位页面/弹窗、更少 analyze 失败、改码必 format+analyze、分层改对文件。

4.1 典型痛点 vs 对策

痛点	对策（设计）
找页面路径慢	`find_page` + 页面目录图 + Dart 符号索引
改 UI 破坏格式	`write_patch` 后自动 `dart format`（已有）
改完不 analyze	增量 `dart analyze` verify（待强化）
mock/API 不一致	任务分类 + 同步读 dto/repository/mock
弹窗难定位	`find_dialog`（showDialog / BottomSheet）

4.2 当前缺口（迁移后仍待做）

Dart 符号：.dart 已在扫描列表，需完善 scanDartSymbols（find_symbol 对 Dart 要可靠）
Flutter 版 features.json 模板：见 xxg/examples/features-flutter.json.example
增量 verify：.xxg/verify.json + 按改动文件 analyze
路由图：GoRouter / GetX / 自研 RouteTable
专用工具：find_page、find_dialog

4.3 实施路线图

阶段	内容	优先级
F1	Dart 符号 + `find_page`	P0
F2	features 模板 + CODEMAP 页面图	P0
F3	增量 `dart analyze` verify	P0
F4	`find_dialog` + 路由解析	P1
F5	Flutter 任务分类 + prompt 块	P1
F6	benchmark 10 条真实任务	持续

F1 + F3 做完后，日常 Flutter 改码体验应明显优于通用 Cursor Agent。

4.4 验证闭环（核心差异化）

write_patch
  → dart format（单文件，已有）
  → dart analyze（改动文件 + 1-hop import）
  → 失败 → stderr 结构化喂回 → 最多 N 轮修复
  → 可选 flutter test（按改动模块）

5. 整体 Agent 分阶段演进（编排前）

阶段	内容
Phase A	引用图、任务分类、预取上下文、verify 契约
Phase B	Orchestrator：classify → plan → implement → verify → review
Phase C	IDE diff 预览、`@页面` / `@符号`
Phase D	飞书需求 → opt-prompt → xxg → git review → PR
Phase E	benchmark：首次 verify 通过率、token、步数、人工订正

6. 目录重组（已落地）

按你的决策：产品根 xxg/、VPS 同仓 infra/、Step 1+2（物理搬迁 + 拆 context / grounding）、CLI 可独立使用。

6.1 仓库顶层

v-p-s-stack/
├── infra/                 # VPS：docker-compose、Caddy、auth-server、site/
├── xxg/                   # Agent 产品 monorepo
├── scripts/deploy.sh      # 转发 → infra/scripts/deploy.sh
├── AGENTS.md
└── docs/

6.2 xxg monorepo

xxg/
├── package.json           # npm workspaces
├── apps/
│   ├── cli/               # 包名 xxg，bin: xxg
│   └── vscode/            # VS Code 扩展（esbuild bundle runtime）
├── packages/
│   ├── runtime/           # @xxg/runtime — agent.js、session、model
│   ├── context/           # @xxg/context — codemap、prompts
│   ├── grounding/         # @xxg/grounding — tools、verify、format
│   └── orchestrator/      # 预留（README）
├── examples/
└── docs/

6.3 旧路径 → 新路径

旧	新
`xxg-coding-agent/src/agent.js` 等	`xxg/packages/runtime/src/`
`xxg-coding-agent/src/codemap/`	`xxg/packages/context/src/codemap/`
`xxg-coding-agent/src/tools/`	`xxg/packages/grounding/src/tools/`
`xxg-coding-agent/bin/xxg.js`	`xxg/apps/cli/bin/xxg.js`
`vscode-xxg/`	`xxg/apps/vscode/`
根目录 `docker-compose.yml` 等	`infra/`

6.4 包依赖（workspace）

{
  "name": "xxg-agent-monorepo",
  "private": true,
  "workspaces": ["packages/*", "apps/*"]
}

@xxg/runtime 依赖 @xxg/context、@xxg/grounding
@xxg/grounding 依赖 @xxg/context
xxg（CLI）依赖上述三包，不依赖 VS Code

7. 独立 CLI 使用方式

cd xxg
npm install
npm link -w xxg

cd /path/to/your/flutter-or-repo-root
# 工作区根 .env：
#   XXG_API_KEY=sk-***
#   OPENAI_API_BASE=http://<VPS-IP>/v1

xxg "自然语言任务"
xxg codemap --force
xxg related "页面关键词"
xxg route "任务描述"
xxg verify
xxg --plan "大改动先出计划"

程序化 API（扩展或其它宿主）：

import { runAgent, loadConfig, pickModel } from '@xxg/runtime';

8. VS Code 扩展

cd xxg/apps/vscode
npm install
npm run build    # 预构建：cd ../.. && npm install；bundle @xxg/*
npm run package

embedded-entry.mjs → dist/agent.cjs（直连 runAgent）
cli-entry.mjs → dist/cli.cjs（spawn 与终端一致的 CLI）

扩展 prebuild 已改为在 xxg/ 根执行 npm install。

9. 测试与质量

重组后全量测试（2026-06-02）：

cd xxg && npm test

@xxg/context：8 项
@xxg/grounding：24 项
@xxg/runtime：63 项（含 integration）

合计 95 项通过。

若曾 npm link 旧路径 xxg-coding-agent，请重新：

cd xxg && npm link -w xxg

10. 部署 VPS 栈（与 Agent 分离）

cd infra
cp ../.env.example .env
docker compose up -d

# 或仓库根
bash scripts/deploy.sh

infra/scripts/deploy.sh 在 infra/ 目录执行 docker compose，.env 可读仓库根或 infra/。

11. 下一步（Step 3）

packages/orchestrator：从 runtime 抽出 plan-mode、agent-task 分类 → runPipeline()
Flutter F1：scanDartSymbols + find_page 工具 + 测试
Flutter F3：planChecks 按改动文件增量 dart analyze
benchmark：固定 6–10 条 Flutter 任务，对比 Cursor 同 prompt 的步数与 analyze 通过率

12. 结论摘要

问题	结论
能否全面超越 Codex/Cursor？	不能（模型、索引、IDE 体量）
能否在垂直场景更优秀？	能 — 可验证、仓库画像、Flutter 结构、团队流水线
目录怎么组织？	`xxg/` 五层 monorepo + `infra/` 同仓
CLI 能否独立？	能 — `npm link -w xxg`，包名 `xxg`
Flutter 先做啥？	F1（Dart 索引 + find_page）+ F3（增量 analyze）

参考

仓库：xxg/README.md、AGENTS.md
示例：xxg/examples/features-flutter.json.example、dart-format-rules.md
前一篇搭建记录：blog/20260601-015429-v-p-s-stack-xxg-agent/
飞书设计纪要：docx/VV6Od2PyEo25eYxQt5Ncb4ronNz

xxg Agent 五层架构与 Flutter 战场：从产品设计到 monorepo 落地

# 1. 背景：xxg 已经是什么

# 2. 定位：在哪里可以「更优秀」

# 3. 五层目标架构

# 4. Flutter 战场：为何先垂直

# 4.1 典型痛点 vs 对策

# 4.2 当前缺口（迁移后仍待做）

# 4.3 实施路线图

# 4.4 验证闭环（核心差异化）

# 5. 整体 Agent 分阶段演进（编排前）

# 6. 目录重组（已落地）

# 6.1 仓库顶层

# 6.2 xxg monorepo

# 6.3 旧路径 → 新路径

# 6.4 包依赖（workspace）

# 7. 独立 CLI 使用方式

# 8. VS Code 扩展

# 9. 测试与质量

# 10. 部署 VPS 栈（与 Agent 分离）

# 11. 下一步（Step 3）

# 12. 结论摘要

# 参考

相关文章