本地开源版 · 版本号 0.1.0 · 最后更新 2026-01-17
1. 产品定位
一句话：为本地开发调试而生的「轻量级 HTTP 接口调试 + 工作区管理」工具，后续可演进到工作流编排、Mock 服务、AI 假数据等方向。
目标用户：前后端开发者、开源贡献者、教学演示。
2. 使用场景（MVP）
| 场景 | 描述 |
|---|---|
| 新建工程 | 对应一个真实项目（如博客后端），生成独立文件夹与元数据 |
| 新建工作区 | 一个 .ws.json 文件，顺序保存 N 条请求（登录→CRUD→退出） |
| 发送请求 | 立即发真实 HTTP，回显状态码、耗时、格式化 JSON |
| 切换环境 | 通过 {{baseUrl}} 变量一键切换 dev/test |
| 组件插件 | 可引入 C++/Qt 自绘的 QML 控件（QtFlutter 风格按钮、Chip 等） |
3. 需求清单（MVP）
| 模块 | 需求点 | 优先级 |
|---|---|---|
| 工程管理 | 新建 / 打开 / 删除 / 最近使用列表 | P0 |
| 工作区管理 | 新建 / 保存 / 删除 / 重命名 | P0 |
| 请求编辑器 | Method、URL、Headers、Body、名称 | P0 |
| 响应面板 | 状态码、耗时、JSON 高亮、折叠树 | P0 |
| 环境变量 | 全局 & 工程级变量替换 {{key}} |
P0 |
| 插件系统 | C++ QML 扩展组件，import 即用 | P0 |
| 主题切换 | 浅色 / 深色两套，QtFlutter 控件跟随 | P1 |
4. 技术栈
| 层级 | 技术 | 备注 |
|---|---|---|
| 前端 | QML6 + QtQuick.Controls 2 | 单窗口，StackView 导航 |
| 后端 | PySide6（Python 3.10+） | 内嵌 QQmlEngine，无额外 IPC |
| 构建 | CMake 3.20 + Qt6 CMake | 统一构建入口 |
| 插件 | C++/Qt QML Extension Plugin | 继承 QQuickItem，自绘任意 |
| 持久化 | JSON 文件（格式化） | 不引入数据库，方便 Git diff |
| 网络 | Python httpx 异步 |
QML 侧回调无阻塞 |
5. 仓库目录结构
qml-api-devtool/
├── CMakeLists.txt # 统一构建
├── src/
│ ├── qml/
│ │ ├── main.qml
│ │ ├── pages/ # 各页面
│ │ ├── controls/ # 纯 QML 通用组件
│ │ └── themes/ # 主题变量
│ ├── python/
│ │ ├── main.py # 启动入口
│ │ ├── core/
│ │ │ ├── project_manager.py
│ │ │ ├── workspace_manager.py
│ │ │ ├── http_caller.py
│ │ │ └── env_resolver.py
│ │ └── qml_bridge.py # 注册到 QML 的 Context
│ └── plugins/
│ ├── QtFlutter/ # 示例插件
│ │ ├── CMakeLists.txt
│ │ ├── qtflutter_plugin.cpp
│ │ ├── Button.qml # 可选 QML wrapper
│ │ └── qmldir
│ └── README.md # 插件开发指南
├── tests/ # pytest + qmltest
├── docs/
│ ├── ROADMAP.md
│ └── plugin_dev.md
├── examples/
│ └── BlogProject/ # 示例工程模板
└── README.md # 用户快速开始
6. 数据格式约定
6.1 project.json（工程级）
{
"name": "BlogBackend",
"version": 1,
"created": "2026-01-17T12:00:00Z",
"env": {
"dev": {"baseUrl": "http://localhost:3000"},
"test": {"baseUrl": "https://api.test.example.com"}
}
}
6.2 *.ws.json（工作区级）
{
"name": "CRUD_Post",
"requests": [
{
"id": "1",
"name": "登录",
"method": "POST",
"url": "{{baseUrl}}/auth/login",
"headers": {"Content-Type": "application/json"},
"body": {"username": "admin", "password": "123456"},
"preScript": "",
"assertScript": "assert(resp.status === 200)"
},
{...}
]
}
7. QML ↔ Python 接口（信号/槽）
| Python 对象 | 关键函数 | 返回/信号 |
|---|---|---|
| ProjectManager | createProject(folder: str) -> bool |
projectOpened(path: str) |
| WorkspaceManager | loadWorkspace(file: str) -> list |
workspaceLoaded(list) |
| HttpCaller | send(req: dict) -> dict |
同步转异步回调 |
| EnvResolver | render(text: str, env: str) -> str |
替换变量 |
8. 插件开发约定
- 每个插件独立 CMake 子工程，产出
MyPlugin.dll/so/dylib+qmldir - 注册示例
qmlRegisterType<QtFlutterButton>("QtFlutter", 1, 0, "Button"); - QML 使用
import QtFlutter 1.0
Button { accent: true; onClicked: root.send() } - 内部可用 QPainter / QSG 任意自绘，视觉与 Flutter 组件对齐即可
9. 构建 & 运行（开发）
# 1. 配置
cmake -B build -S . -DQt6_DIR=/path/to/Qt6/lib/cmake/Qt6
# 2. 编译
cmake --build build --parallel
# 3. 运行
export QML_IMPORT_PATH=build/plugins:$QML_IMPORT_PATH
python src/python/main.py
10. 里程碑计划
| 阶段 | 目标 | 预估时间 |
|---|---|---|
| M0 | 骨架可跑：CMake+PySide6+QML 主窗口 | 1 d |
| M1 | 工程/工作区 CRUD + 树导航 | 2 d |
| M2 | 请求编辑器 + 真实 HTTP + 响应面板 | 2 d |
| M3 | 环境变量 + 主题切换 | 1 d |
| M4 | C++ 插件示例 Button/Chip 并可 import | 2 d |
| M5 | 文档、示例工程、单元测试 | 2 d |
| M6 | 开源发布 v0.1.0 | 1 d |
11. 后续 Roadmap（简版）
- 内置 Mock 服务（本地端口），支持 JSON Schema → 假数据
- AI 假数据生成（本地大模型或云端）
- 工作流编排：把多个工作区拖成顺序图，支持循环/条件
- CLI 模式：无界面批量运行工作区并生成报告
- 团队协作：云端同步、权限、历史回滚
12. 常见问答（预留）
（待补充）
13. 授权协议
MIT · 可商用、可二次发布、保留 License 文件即可
下一步：把本 Markdown 使用Agent，让它先自动生成 CLI 骨架（CMakeLists.txt、main.py、main.qml 空壳），
生成后cmake -B build && cmake --build build一键跑通，再继续迭代。