DevPilot 是一款桌面端工作流编排工具，专为管理长周期 AI 编程工作流而设计。它提供可视化的工作区管理界面，支持里程碑追踪、文件实时监控和蓝图模板系统。
您需要了解HardnessEngineering和Open Spec等相关知识
https://github.com/walkinglabs/learn-harness-engineering
https://github.com/Fission-AI/OpenSpec
| 层级 | 技术选型 |
|---|---|
| 语言 | Python 3.11+ |
| GUI 框架 | PySide6 (Qt 6.5+) |
| 架构模式 | 分层架构 + 信号/槽通信 |
| 数据持久化 | JSON (注册表、里程碑) + Markdown (进度日志) |
| 文件监控 | Qt QFileSystemWatcher |
| 主题系统 | QSS (Qt Style Sheets) 全局暗色主题 |
DevPilot/
├── launcher.py # 应用入口
├── requirements.txt # Python 依赖声明
├── workspace_registry.json # 工作区注册表 (运行时生成)
│
├── core/ # 核心应用包
│ ├── __init__.py
│ ├── application.py # 应用引导与事件循环初始化
│ ├── settings.py # 全局配置常量与主题样式
│ ├── entities.py # 领域实体定义
│ ├── workspace_service.py # 工作区/蓝图 CRUD 服务
│ ├── monitor.py # 文件系统变更监控
│ ├── shell.py # 主窗口布局与事件编排
│ │
│ └── views/ # UI 视图组件
│ ├── __init__.py
│ ├── toolbar.py # 顶部导航工具栏
│ ├── dashboard.py # 工作区卡片网格仪表盘
│ ├── detail_page.py # 工作区全页详情视图
│ ├── cards.py # 里程碑卡片与进度可视化
│ ├── new_workspace_dialog.py # 新建工作区对话框
│ └── blueprint_explorer.py # 蓝图浏览器
│
├── blueprints/ # 蓝图模板库
│ └── Micro/ # "Micro" 长周期工作流蓝图
│ ├── AGENTS.md
│ ├── CLAUDE.md
│ ├── feature_list.json
│ ├── claude-progress.md
│ └── init.sh
│
└── workspaces/ # 默认工作区存放目录
集中管理所有路径常量、状态配色方案和全局 QSS 暗色主题样式表。配色采用 Tailwind CSS Slate 色系：
- 主背景:
#0f172a(slate-900) - 面板背景:
#1e293b(slate-800) - 边框:
#334155(slate-700) - 主强调色:
#3b82f6(blue-500) - 成功色:
#10b981(emerald-500) - 警告色:
#ef4444(red-500)
定义三个核心数据类：
Milestone— 单个可交付项（包含排名、领域、阶段状态、验证检查项、证据）Workspace— 活跃工作区实例（提供里程碑加载、进度读取、状态概览方法）Blueprint— 可复用蓝图模板（包含资产文件列表）
WorkspaceService 类封装所有业务操作：
| 方法 | 功能 |
|---|---|
discover_blueprints() |
扫描 blueprints/ 目录发现可用蓝图 |
enumerate_workspaces() |
列举所有已注册工作区 |
provision_workspace() |
基于蓝图创建新工作区 |
adopt_workspace() |
导入已存在的目录作为工作区 |
destroy_workspace() |
彻底删除工作区（含文件） |
detach_workspace() |
仅取消注册（保留文件） |
identify_blueprint() |
通过文件匹配自动识别蓝图类型 |
注册表以 JSON 格式存储于 workspace_registry.json，结构为：
[
{
"name": "workspace-label",
"path": "C:/absolute/path/to/workspace",
"template": "Micro"
}
]FileMonitor 基于 Qt 的 QFileSystemWatcher 实现：
- 监控
.json、.md、.sh后缀文件 - 监控工作区根目录变更
- 文件被编辑器替换时（删除+重建）自动重新注册监控
- 通过
change_detected信号通知上层
AppShell 采用页面式导航架构（QStackedWidget），而非传统的 Tab + Splitter 布局：
- Page 0 — Dashboard: 工作区卡片网格，3列自适应布局
- Page 1 — Detail: 单个工作区的全页面详情展示
- Page 2 — Blueprints: 蓝图浏览器
页面间通过顶部工具栏的导航按钮和面包屑切换。文件变更通过 300ms 防抖定时器合并刷新。
| 组件 | 职责 |
|---|---|
AppToolbar |
顶部固定工具栏：品牌标识、面包屑导航、操作按钮 |
DashboardView |
主仪表盘，以卡片网格展示所有工作区概览 |
WorkspaceGridCard |
单个工作区的网格卡片（含迷你进度条、统计数据、右键菜单） |
DetailPage |
全页详情：顶部 Header → 2列里程碑网格 → 底部日志/文件并排 |
MilestoneCard |
里程碑卡片（带状态色标、排名标签、hover 效果） |
OverviewStrip |
自绘制水平进度条（圆角分段着色 + 图例） |
PhaseBadge |
药丸形状态标签 |
NewWorkspaceDialog |
新建工作区的表单对话框 |
BlueprintExplorer |
蓝图列表 + 资产内容预览 |
用户操作 → AppShell → WorkspaceService → 文件系统 (workspaces/, registry.json)
↓
更新 Entities
↓
发射 Qt Signal
↓
视图通过 Slot 响应刷新
↓
FileMonitor 检测外部变更
↓
防抖后触发整体刷新
| 状态 key | 显示名 | 颜色 |
|---|---|---|
not_started |
未开始 | #6b7280 (灰) |
in_progress |
进行中 | #3b82f6 (蓝) |
blocked |
已阻塞 | #ef4444 (红) |
passing |
已通过 | #10b981 (绿) |
- Python 3.11 或更高版本
- pip 包管理器
# 进入项目目录
cd DevPilot
# 安装依赖
pip install -r requirements.txt仅需安装 PySide6 一个依赖包。
python launcher.py应用采用页面导航架构，通过顶部工具栏切换视图：
- 仪表盘（首页）— 以卡片网格展示所有工作区概览，单击进入详情
- 工作区详情 — 全页面展示：Header 区 → 2列里程碑网格 → 底部进度日志与文件浏览器并排
- 蓝图库 — 浏览可用蓝图模板及其内容
顶部工具栏始终可见，提供"返回"导航、面包屑路径显示、以及新建/导入/蓝图库快捷按钮。
- 点击工具栏 新建工作区 按钮
- 输入工作区名称（英文，无空格）
- 选择蓝图模板（默认为 "Micro"）
- 选择存放路径（默认在
workspaces/下） - 确认创建
创建后蓝图中的所有文件会被复制到目标目录。
- 点击 导入 按钮
- 选择要导入的目录
- 系统会自动识别匹配的蓝图类型
- 确认蓝图选择后完成导入
导入操作不会复制或修改目标目录中的任何文件，仅将其注册到管理列表。
在仪表盘中点击任意工作区卡片，将进入全页详情视图：
- 顶部 Header — 工作区名称、蓝图信息、路径、进度概览条
- 里程碑网格 — 以 2 列卡片网格展示所有功能项及其状态
- 底部并排区域 — 左侧为进度日志，右侧为文件浏览器（可拖拽调整比例）
点击工具栏"返回"按钮回到仪表盘。
在仪表盘中对 Micro 蓝图类型的工作区卡片右键，可执行以下操作：
| 操作 | 说明 |
|---|---|
| 复制工作提示 | 将带有路径和指令的文本复制到剪贴板 |
| 启动终端执行 | 打开新的 CMD 窗口并自动执行 Claude 命令 |
| 导入 target.md | 选择一个 .md 文件复制到工作区作为需求文档 |
| 初始化工作区 | 基于 target.md 自动生成里程碑和进度文件 |
初始化操作会打开一个选项对话框：
- 版本控制软件 — 选择 Git 或 Perforce (P4)，初始化时会将相关命令替换为对应版本控制的语法
- 人工检验选项 — 勾选后提交规则将变为必须人工确认后才可执行提交
右键工作区卡片 → "删除工作区"：
- 内部工作区（位于
workspaces/下）：确认后将同时删除文件 - 外部工作区（导入的）：仅从注册表移除，不删除原始文件
进入工作区详情页后，系统会自动监控其文件变化：
- 监控
.json、.md、.sh类型文件 - 外部工具（如 AI Agent）修改文件后，界面会在 300ms 内自动刷新
- 状态栏会显示当前监控状态
专为长周期 AI 辅助编程工作流设计，包含以下文件：
| 文件 | 用途 |
|---|---|
AGENTS.md |
编程代理的工作规范和流程指南 |
CLAUDE.md |
Claude 专用的工作指南 |
feature_list.json |
里程碑定义（包含优先级、验证步骤、状态追踪） |
claude-progress.md |
会话级别的进度日志模板 |
init.sh |
项目初始化脚本 |
在 blueprints/ 目录下创建新文件夹即可添加自定义蓝图：
blueprints/
└── MyTemplate/
├── any-file.md
├── config.json
└── setup.sh
蓝图目录中的所有文件会在创建工作区时被完整复制。
{
"project": "项目名称",
"version": "1.0",
"features": [
{
"id": "F001",
"priority": 1,
"area": "功能领域",
"title": "功能标题",
"user_visible_behavior": "用户可观察到的行为描述",
"status": "not_started",
"verification": [
"验证步骤 1",
"验证步骤 2"
],
"evidence": [],
"notes": ""
}
]
}status 字段可选值: not_started | in_progress | blocked | passing
Q: 应用无法启动？ 确认已安装 Python 3.11+ 和 PySide6：
python --version
pip show PySide6Q: 工作区列表为空？
确认 blueprints/ 目录下存在至少一个蓝图模板，且 workspace_registry.json 文件格式正确。
Q: 文件修改后界面没有自动刷新？ 部分编辑器使用"原子写入"（先写临时文件再重命名），这种情况下 FileMonitor 会自动重新注册监控路径。如果仍然无效，可手动切换工作区选中状态来强制刷新。
Q: 如何在其他机器上迁移？
复制整个 DevPilot/ 目录即可。注意 workspace_registry.json 中存储的是绝对路径，迁移后需要手动修改或重新导入工作区。