software-planner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Software Development Planner

软件开发规划器

Complete workflow for planning and implementing Python software with CLI, GUI, and Web interfaces, following established project patterns from GangDan, Chou, Huan, LaPian, and NuoYi.

规划与实现带有CLI、GUI和Web界面的Python软件的完整工作流，遵循GangDan、Chou、Huan、LaPian和NuoYi的成熟项目范式。

Pre-Development Planning

开发前规划

Step 1: Domain Research

步骤1：领域调研

Before writing any code, conduct thorough research:

Academic Literature Search
- Search Google Scholar, CNKI, IEEE, ACM for relevant papers
- Download key PDFs to
```
pdf/
```
  directory in project root
- Extract core concepts and methodologies
- Identify evaluation criteria and metrics
Existing Solutions Analysis
- Search GitHub for similar projects
- Identify feature gaps and improvement opportunities
- Note UI/UX patterns and architectural decisions
Requirements Synthesis
- Combine academic findings with practical needs
- Define functional requirements with citations
- Establish non-functional requirements (performance, usability)

编写任何代码前，先开展全面调研：

学术文献检索
- 在Google Scholar、CNKI、IEEE、ACM平台搜索相关论文
- 将核心PDF文件下载到项目根目录的
```
pdf/
```
  文件夹下
- 提取核心概念与方法论
- 明确评估标准与指标
现有方案分析
- 在GitHub搜索同类项目
- 识别功能缺口与优化空间
- 记录UI/UX范式与架构决策
需求整合
- 结合学术研究成果与实际需求
- 定义带引用来源的功能需求
- 明确非功能需求（性能、易用性）

Step 2: Architecture Design

步骤2：架构设计

Design the system before implementation:

Software Name (v1.0)
├── Core Features (from research)
│   ├── Feature 1: [description with citation]
│   ├── Feature 2: [description with citation]
│   └── Feature 3: [description with citation]
├── Data Models
│   ├── Model 1: fields, relationships
│   └── Model 2: fields, relationships
├── Algorithms
│   ├── Algorithm 1: input, output, complexity
│   └── Algorithm 2: input, output, complexity
└── User Interfaces
    ├── CLI: commands, flags, arguments
    ├── GUI: windows, panels, controls
    └── Web: routes, templates, API endpoints

在实现前完成系统设计：

Software Name (v1.0)
├── Core Features (from research)
│   ├── Feature 1: [description with citation]
│   ├── Feature 2: [description with citation]
│   └── Feature 3: [description with citation]
├── Data Models
│   ├── Model 1: fields, relationships
│   └── Model 2: fields, relationships
├── Algorithms
│   ├── Algorithm 1: input, output, complexity
│   └── Algorithm 2: input, output, complexity
└── User Interfaces
    ├── CLI: commands, flags, arguments
    ├── GUI: windows, panels, controls
    └── Web: routes, templates, API endpoints

Step 3: Module Specification

步骤3：模块规范

Define each module with clear responsibilities and size targets. The

cli.py

module handles command-line argument parsing and routing, targeting around 100 lines. The

gui.py

module provides PySide6 window, controls, and event handlers, targeting around 200 lines. The

app.py

module contains Flask routes and API endpoints, targeting around 100 lines. The

core.py

module implements business logic, algorithms, and data models, targeting around 200 lines. The

api.py

module provides the unified Python API with ToolResult, targeting around 100 lines. Total target is 500+ lines across all modules.

明确定义每个模块的职责与代码量目标。

cli.py

模块负责命令行参数解析与路由，代码量目标约100行。

gui.py

模块提供PySide6窗口、控件与事件处理，代码量目标约200行。

app.py

模块包含Flask路由与API端点，代码量目标约100行。

core.py

模块实现业务逻辑、算法与数据模型，代码量目标约200行。

api.py

模块提供带ToolResult的统一Python API，代码量目标约100行。所有模块总代码量目标为500行以上。

Interface Requirements

界面要求

CLI (Command-Line Interface)

CLI（命令行界面）

Follow unified flag conventions from GangDan:

python

import argparse

def main():
    parser = argparse.ArgumentParser(
        prog="softwarename",
        description="Software description",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    
    # Unified flags (required)
    parser.add_argument("-V", "--version", action="version", version=f"softwarename {__version__}")
    parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
    parser.add_argument("-o", "--output", help="Output path")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON")
    parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
    
    # Mode selection
    subparsers = parser.add_subparsers(dest="mode")
    
    # GUI mode
    gui_parser = subparsers.add_parser("gui", help="Launch GUI")
    gui_parser.add_argument("--no-web", action="store_true", help="Disable embedded web server")
    
    # Web mode
    web_parser = subparsers.add_parser("web", help="Launch web server")
    web_parser.add_argument("--host", default="127.0.0.1")
    web_parser.add_argument("--port", type=int, default=5000)
    
    # CLI operations
    cli_parser = subparsers.add_parser("cli", help="CLI mode")
    cli_parser.add_argument("input", help="Input file or data")

Entry Points (following GangDan pattern): The software supports multiple entry points. The default invocation launches GUI or web based on context. Explicit GUI mode uses

softwarename gui

. Web server mode uses

softwarename web

. CLI mode uses

softwarename cli <args>

. Module invocation uses

python -m packagename

遵循GangDan的统一参数规范：

python

import argparse

def main():
    parser = argparse.ArgumentParser(
        prog="softwarename",
        description="Software description",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    
    # Unified flags (required)
    parser.add_argument("-V", "--version", action="version", version=f"softwarename {__version__}")
    parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
    parser.add_argument("-o", "--output", help="Output path")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON")
    parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
    
    # Mode selection
    subparsers = parser.add_subparsers(dest="mode")
    
    # GUI mode
    gui_parser = subparsers.add_parser("gui", help="Launch GUI")
    gui_parser.add_argument("--no-web", action="store_true", help="Disable embedded web server")
    
    # Web mode
    web_parser = subparsers.add_parser("web", help="Launch web server")
    web_parser.add_argument("--host", default="127.0.0.1")
    web_parser.add_argument("--port", type=int, default=5000)
    
    # CLI operations
    cli_parser = subparsers.add_parser("cli", help="CLI mode")
    cli_parser.add_argument("input", help="Input file or data")

入口点（遵循GangDan范式）：软件支持多入口点。默认调用会根据上下文启动GUI或Web服务。显式GUI模式使用

softwarename gui

。Web服务模式使用

softwarename web

。CLI模式使用

softwarename cli <args>

。模块调用使用

python -m packagename

。

GUI (PySide6 Interface)

GUI（PySide6界面）

Use default PySide6 styling - NO custom colors, fonts, or backgrounds:

python

from PySide6.QtWidgets import (
    QApplication, QMainWindow, QWidget, QVBoxLayout, 
    QHBoxLayout, QPushButton, QLabel, QLineEdit, 
    QComboBox, QSpinBox, QDoubleSpinBox, QTableWidget,
    QTabWidget, QGroupBox, QFileDialog, QMessageBox,
)
from PySide6.QtCore import Qt
import pyqtgraph as pg

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Software Name v1.0")
        self.setMinimumSize(800, 600)
        
        # Central widget with default styling
        central = QWidget()
        self.setCentralWidget(central)
        layout = QVBoxLayout(central)
        
        # Controls in group box
        control_group = QGroupBox("Parameters")
        control_layout = QHBoxLayout(control_group)
        
        # Input controls
        self.input_edit = QLineEdit()
        self.input_edit.setPlaceholderText("Enter input...")
        control_layout.addWidget(QLabel("Input:"))
        control_layout.addWidget(self.input_edit)
        
        # Action buttons
        btn_run = QPushButton("Run")
        btn_run.clicked.connect(self.run_analysis)
        control_layout.addWidget(btn_run)
        
        layout.addWidget(control_group)
        
        # Visualization with pyqtgraph
        self.plot_widget = pg.PlotWidget()
        self.plot_widget.setBackground('w')  # White background for plots
        self.plot_widget.showGrid(x=True, y=True)
        layout.addWidget(self.plot_widget)
        
        # Results table
        self.results_table = QTableWidget()
        self.results_table.setColumnCount(4)
        self.results_table.setHorizontalHeaderLabels(["ID", "Name", "Value", "Score"])
        layout.addWidget(self.results_table)

GUI Design Principles: Three principles guide GUI implementation. First, use default styling only with system default colors, system default fonts, no custom backgrounds, and no custom stylesheets. Second, follow a consistent layout structure with the control panel with parameters at the top, visualization area with pyqtgraph in the middle, and results table or log output at the bottom. Third, select appropriate control types:

QLineEdit

for text input,

QSpinBox

QDoubleSpinBox

for numeric input,

QComboBox

for selections,

QCheckBox

for boolean options, and

QPushButton

for actions.

使用默认PySide6样式——不要自定义颜色、字体或背景：

python

from PySide6.QtWidgets import (
    QApplication, QMainWindow, QWidget, QVBoxLayout, 
    QHBoxLayout, QPushButton, QLabel, QLineEdit, 
    QComboBox, QSpinBox, QDoubleSpinBox, QTableWidget,
    QTabWidget, QGroupBox, QFileDialog, QMessageBox,
)
from PySide6.QtCore import Qt
import pyqtgraph as pg

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Software Name v1.0")
        self.setMinimumSize(800, 600)
        
        # Central widget with default styling
        central = QWidget()
        self.setCentralWidget(central)
        layout = QVBoxLayout(central)
        
        # Controls in group box
        control_group = QGroupBox("Parameters")
        control_layout = QHBoxLayout(control_group)
        
        # Input controls
        self.input_edit = QLineEdit()
        self.input_edit.setPlaceholderText("Enter input...")
        control_layout.addWidget(QLabel("Input:"))
        control_layout.addWidget(self.input_edit)
        
        # Action buttons
        btn_run = QPushButton("Run")
        btn_run.clicked.connect(self.run_analysis)
        control_layout.addWidget(btn_run)
        
        layout.addWidget(control_group)
        
        # Visualization with pyqtgraph
        self.plot_widget = pg.PlotWidget()
        self.plot_widget.setBackground('w')  # White background for plots
        self.plot_widget.showGrid(x=True, y=True)
        layout.addWidget(self.plot_widget)
        
        # Results table
        self.results_table = QTableWidget()
        self.results_table.setColumnCount(4)
        self.results_table.setHorizontalHeaderLabels(["ID", "Name", "Value", "Score"])
        layout.addWidget(self.results_table)

GUI设计原则：GUI实现遵循三大原则。第一，仅使用系统默认样式，包括系统默认颜色、系统默认字体，不自定义背景、不自定义样式表。第二，遵循统一的布局结构：顶部为参数控制面板，中部为pyqtgraph可视化区域，底部为结果表格或日志输出。第三，选择合适的控件类型：文本输入用

QLineEdit

，数值输入用

QSpinBox

或

QDoubleSpinBox

，选择项用

QComboBox

，布尔选项用

QCheckBox

，操作按钮用

QPushButton

。

Web (Flask Interface)

Web（Flask界面）

python

from flask import Flask, render_template, jsonify, request

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/analyze", methods=["POST"])
def analyze():
    data = request.json
    result = perform_analysis(data)
    return jsonify(result.to_dict())

@app.route("/api/results/<id>")
def get_results(id):
    result = get_stored_result(id)
    return jsonify(result.to_dict())

def run_server(host="127.0.0.1", port=5000):
    print(f"Starting server at http://{host}:{port}")
    app.run(host=host, port=port, debug=False)

python

from flask import Flask, render_template, jsonify, request

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/analyze", methods=["POST"])
def analyze():
    data = request.json
    result = perform_analysis(data)
    return jsonify(result.to_dict())

@app.route("/api/results/<id>")
def get_results(id):
    result = get_stored_result(id)
    return jsonify(result.to_dict())

def run_server(host="127.0.0.1", port=5000):
    print(f"Starting server at http://{host}:{port}")
    app.run(host=host, port=port, debug=False)

ToolResult Pattern

ToolResult范式

All API functions must return ToolResult:

python

from dataclasses import dataclass, field
from typing import Any, Optional

@dataclass
class ToolResult:
    success: bool
    data: Any = None
    error: Optional[str] = None
    metadata: dict = field(default_factory=dict)

    def to_dict(self) -> dict:
        return {
            "success": self.success,
            "data": self.data,
            "error": self.error,
            "metadata": self.metadata,
        }

所有API函数必须返回ToolResult：

python

from dataclasses import dataclass, field
from typing import Any, Optional

@dataclass
class ToolResult:
    success: bool
    data: Any = None
    error: Optional[str] = None
    metadata: dict = field(default_factory=dict)

    def to_dict(self) -> dict:
        return {
            "success": self.success,
            "data": self.data,
            "error": self.error,
            "metadata": self.metadata,
        }

Sample Data Requirements

示例数据要求

Create sample data for testing and demonstration:

创建用于测试和演示的示例数据：

Data File Structure

数据文件结构

data/
├── sample_input.json      # Example input data
├── sample_results.json    # Expected output for testing
├── test_cases.json        # Test case definitions
└── reference_data.csv     # Reference/benchmark data

data/
├── sample_input.json      # Example input data
├── sample_results.json    # Expected output for testing
├── test_cases.json        # Test case definitions
└── reference_data.csv     # Reference/benchmark data

Sample Data Template

示例数据模板

json

{
  "description": "Sample input for testing",
  "version": "1.0",
  "cases": [
    {
      "id": "case_001",
      "name": "Basic test case",
      "input": {
        "param1": "value1",
        "param2": 100
      },
      "expected_output": {
        "result": "expected_result",
        "score": 0.95
      }
    }
  ]
}

json

{
  "description": "Sample input for testing",
  "version": "1.0",
  "cases": [
    {
      "id": "case_001",
      "name": "Basic test case",
      "input": {
        "param1": "value1",
        "param2": 100
      },
      "expected_output": {
        "result": "expected_result",
        "score": 0.95
      }
    }
  ]
}

Documentation Structure

文档结构

README.md (English)

README.md（英文）

Required sections, each 200+ words: Section 1 covers project background including context, problem statement, and motivation. Section 2 describes application scenarios with use cases, target users, and workflows. Section 3 details hardware compatibility including CPU, GPU, and memory requirements. Section 4 specifies operating system support for Windows, macOS, and Linux. Section 5 lists dependencies including Python version and required packages. Section 6 provides installation instructions for pip install, from source, and configuration. Section 7 explains usage covering CLI commands, GUI operation, and Web interface. Section 8 includes screenshots with placeholders and descriptions. Section 9 covers license information with the GPLv3 statement.

必填章节，每章节不少于200字：第1章介绍项目背景，包括上下文、问题陈述与开发动机。第2章描述应用场景，包括使用案例、目标用户与工作流。第3章说明硬件兼容性，包括CPU、GPU与内存要求。第4章明确操作系统支持，覆盖Windows、macOS与Linux。第5章列出依赖项，包括Python版本与所需包。第6章提供安装指引，包括pip安装、源码安装与配置方法。第7章讲解使用方法，覆盖CLI命令、GUI操作与Web界面使用。第8章包含截图，带占位符与说明。第9章说明许可证信息，附上GPLv3声明。

README_CN.md (Chinese)

README_CN.md（中文）

Same structure as English, translated: Section 1 covers 项目背景 (project background). Section 2 covers 应用场景 (application scenarios). Section 3 covers 兼容硬件 (hardware compatibility). Section 4 covers 操作系统 (operating systems). Section 5 covers 依赖环境 (dependencies). Section 6 covers 安装过程 (installation). Section 7 covers 使用方法 (usage). Section 8 covers 运行截图 (screenshots). Section 9 covers 授权协议 (license).

与英文文档结构一致，翻译内容：第1章为项目背景。第2章为应用场景。第3章为兼容硬件。第4章为操作系统。第5章为依赖环境。第6章为安装过程。第7章为使用方法。第8章为运行截图。第9章为授权协议。

README Template

README模板

The README template provides a structured format for documentation. Each section should contain at least 200 words to ensure adequate detail. The Project Background section describes the context, problem, and motivation for the software, including academic context and practical need. The Application Scenarios section describes specific use cases, target users, and typical workflows. The Hardware Compatibility section describes CPU requirements, GPU needs if any, memory requirements, and storage needs. The Operating Systems section describes support for Windows, macOS, and Linux with specific version requirements. The Dependencies section lists Python version requirement, core dependencies with version constraints, and optional dependencies. The Installation section provides step-by-step installation instructions for pip, conda, and from-source methods. The Usage section provides CLI examples, GUI instructions, and Web interface usage. The Screenshots section displays GUI and Web interface images. The License section states GPLv3 and references the LICENSE file.

README模板提供结构化的文档格式。每个章节应包含至少200字以保证信息足够详细。项目背景章节描述软件的开发上下文、解决的问题与动机，包括学术背景与实际需求。应用场景章节描述具体使用案例、目标用户与典型工作流。硬件兼容性章节描述CPU要求、GPU需求（如有）、内存要求与存储需求。操作系统章节描述对Windows、macOS、Linux的支持及具体版本要求。依赖项章节列出Python版本要求、带版本约束的核心依赖与可选依赖。安装章节提供pip、conda与源码安装的分步指引。使用章节提供CLI示例、GUI操作说明与Web界面使用方法。截图章节展示GUI与Web界面的图片。许可证章节声明采用GPLv3协议并指向LICENSE文件。

Project File Structure

项目文件结构

project_name/
├── pyproject.toml          # Package configuration
├── requirements.txt        # Dependencies list
├── LICENSE                 # GPLv3 license
├── README.md               # English documentation
├── README_CN.md            # Chinese documentation
├── MANIFEST.in             # Package manifest
├── upload_pypi.sh          # PyPI upload script (Unix)
├── upload_pypi.bat         # PyPI upload script (Windows)
├── pdf/                    # Academic reference papers
│   ├── paper1.pdf
│   └── paper2.pdf
├── data/                   # Sample data
│   ├── sample_input.json
│   └── test_cases.json
├── images/                 # Screenshots
│   └── placeholder.png
├── tests/                  # Test suite
│   ├── __init__.py
│   ├── conftest.py
│   └── test_core.py
└── packagename/            # Main package
    ├── __init__.py         # Version and exports
    ├── __main__.py         # python -m entry
    ├── cli.py              # CLI implementation
    ├── gui.py              # GUI implementation
    ├── app.py              # Flask web app
    ├── core.py             # Business logic
    └── api.py              # Unified API

project_name/
├── pyproject.toml          # Package configuration
├── requirements.txt        # Dependencies list
├── LICENSE                 # GPLv3 license
├── README.md               # English documentation
├── README_CN.md            # Chinese documentation
├── MANIFEST.in             # Package manifest
├── upload_pypi.sh          # PyPI upload script (Unix)
├── upload_pypi.bat         # PyPI upload script (Windows)
├── pdf/                    # Academic reference papers
│   ├── paper1.pdf
│   └── paper2.pdf
├── data/                   # Sample data
│   ├── sample_input.json
│   └── test_cases.json
├── images/                 # Screenshots
│   └── placeholder.png
├── tests/                  # Test suite
│   ├── __init__.py
│   ├── conftest.py
│   └── test_core.py
└── packagename/            # Main package
    ├── __init__.py         # Version and exports
    ├── __main__.py         # python -m entry
    ├── cli.py              # CLI implementation
    ├── gui.py              # GUI implementation
    ├── app.py              # Flask web app
    ├── core.py             # Business logic
    └── api.py              # Unified API

Rules

规范文档

rules/pre-development.md - Research and planning phase
rules/interface-design.md - CLI/GUI/Web patterns
rules/documentation.md - README requirements
rules/sample-data.md - Test data creation

rules/pre-development.md - 调研与规划阶段规范
rules/interface-design.md - CLI/GUI/Web范式
rules/documentation.md - README要求
rules/sample-data.md - 测试数据创建规范

Verification Checklist

验证检查清单

Before considering the project complete, verify the following items. Code should be 500+ lines total across all modules. CLI should have unified flags (-V, -v, -o, --json, -q). GUI should use default PySide6 styling without custom styling. Web interface should have a REST API. All functions should return ToolResult. Sample data files should exist in the data directory. Test cases should be defined. README.md should have all 9 sections with 200+ words each. README_CN.md should have all 9 sections with 200+ words each. Academic PDFs should be present in the

pdf/

directory. GPLv3 LICENSE file should exist. requirements.txt should exist. pyproject.toml should be configured correctly. PyPI upload scripts should exist.

在确认项目完成前，验证以下事项：所有模块总代码量不少于500行。CLI需包含统一参数（-V、-v、-o、--json、-q）。GUI需使用默认PySide6样式，无自定义样式。Web界面需提供REST API。所有函数返回ToolResult。示例数据文件存在于data目录下。已定义测试用例。README.md包含全部9个章节，每章节不少于200字。README_CN.md包含全部9个章节，每章节不少于200字。

pdf/

目录下存在学术PDF文件。已存在GPLv3 LICENSE文件。已存在requirements.txt文件。pyproject.toml配置正确。已存在PyPI上传脚本。

Quick Start Template

快速启动模板

bash

undefined

bash

undefined

Create project structure

mkdir -p project_name/{pdf,data,images,tests,packagename}

Create required files

touch project_name/{pyproject.toml,requirements.txt,LICENSE,README.md,README_CN.md} touch project_name/upload_pypi.{sh,bat}

Create package files

touch project_name/packagename/{init.py,main.py,cli.py,gui.py,app.py,core.py,api.py}

Create test files

touch project_name/tests/{init.py,conftest.py,test_core.py}

undefined

touch project_name/tests/{init.py,conftest.py,test_core.py}

undefined