software-planner

安全规则

参见 _shared/core/safety-rules.md — 所有安全规则均从共享层加载，避免在不同技能中重复维护。

快速命令

命令	描述
/planner research <topic>	开展领域研究
/planner design <project>	设计系统架构
/planner modules	生成模块规范
/planner docs	创建双语文档
/planner verify	运行验证清单

软件开发规划器

用于规划和实现 Python 软件的完整工作流，支持 CLI、GUI 和 Web 界面，并遵循既定的内部项目模式。

开发前规划

步骤 1：领域研究

编写任何代码之前，都要开展全面的研究：

1. 学术文献检索

   • 在 Google Scholar、CNKI、IEEE、ACM 上检索相关论文
   • 将关键 PDF 下载到项目根目录下的 pdf/ 目录
   • 提取核心概念和方法
   • 确定评估标准和指标

2. 现有解决方案分析

   • 在 GitHub 上搜索类似项目
   • 找出功能差距和改进机会
   • 记录 UI/UX 模式和架构决策

3. 需求综合

   • 将学术研究结果与实际需求结合起来
   • 引用资料，定义功能需求
   • 确立非功能需求（性能、易用性）

步骤 2：架构设计

实现之前先设计系统：

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

步骤 3：模块规范

为每个模块定义明确的职责和目标规模。cli.py 模块负责命令行参数解析和路由，目标约为 100 行。gui.py 模块提供 PySide6 窗口、控件和事件处理器，目标约为 200 行。app.py 模块包含 Flask 路由和 API 端点，目标约为 100 行。core.py 模块实现业务逻辑、算法和数据模型，目标约为 200 行。api.py 模块提供包含 ToolResult 的统一 Python API，目标约为 100 行。所有模块的总目标为 500 行以上。

界面要求

CLI（命令行界面）

遵循统一的标志约定：

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")

入口点（遵循标准模式）：软件支持多个入口点。默认调用会根据上下文启动 GUI 或 Web。显式 GUI 模式使用 softwarename gui。Web 服务模式使用 softwarename web。CLI 模式使用 softwarename cli <args>。模块调用使用 python -m packagename。

GUI（PySide6 界面）

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

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 界面）

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 模式

所有 API 函数都必须返回 ToolResult：

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,
        }

示例数据要求

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

数据文件结构

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

示例数据模板

{
  "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
      }
    }
  ]
}

文档结构

README.md (English)

必需章节，每章 200 字以上：第 1 节介绍项目背景，包括上下文、问题陈述和动机。第 2 节描述应用场景，包括用例、目标用户和工作流。第 3 节详细说明硬件兼容性，包括 CPU、GPU 和内存要求。第 4 节说明对 Windows、macOS 和 Linux 的操作系统支持。第 5 节列出依赖项，包括 Python 版本和必需的软件包。第 6 节提供安装说明，包括 pip install、从源码安装和配置。第 7 节介绍使用方法，涵盖 CLI 命令、GUI 操作和 Web 界面。第 8 节包含带占位符和描述的截图。第 9 节介绍授权协议信息，并附上 GPLv3 声明。

README_CN.md (Chinese)

结构与英文版相同，翻译如下：第 1 节介绍项目背景。第 2 节介绍应用场景。第 3 节介绍兼容硬件。第 4 节介绍操作系统。第 5 节介绍依赖环境。第 6 节介绍安装过程。第 7 节介绍使用方法。第 8 节介绍运行截图。第 9 节介绍授权协议。

README Template

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

Usage Examples

Planning a Data Analysis Tool

/planner research "time series analysis with interactive visualization"
/planner design "TimeViz - time series analysis tool"
/planner modules --interface cli,web
/planner docs --lang zh,en
/planner verify

Planning a Scientific Simulation

/planner research "molecular dynamics simulation with GPU acceleration"
/planner design "MolSim" --domain scientific
/planner modules --interface gui,cli

Quick Start for Small Projects

/planner design "MyTool" --minimal
/planner modules --single-file

Troubleshooting

Research phase returns too broad results

• Fix: 使用 --domain scientific|web|cli|gui 标志缩小范围；添加 --year 2024-2026 以获取近期论文；使用 --exclude-field 排除无关领域

Module specification too abstract

• Fix: 使用 /planner modules --detailed 进行 API 级拆分；添加 --example 为每个模块生成伪代码

Documentation generation creates empty stubs

• Fix: 运行文档生成前确保模块规格完整；使用 /planner docs --fill 根据模块签名自动填充内容

Interface design conflicts

• Fix: 使用 /planner design --resolve 检测并解决 CLI/GUI/Web 界面之间的冲突

Edge Cases

• Monorepo planning: 使用 --monorepo 标志，为每个软件包生成模块规格，并跟踪共享依赖项
• Legacy migration: --migrate-from <old-spec> 将旧架构与新计划进行比较，并标记破坏性变更
• Multi-language projects: 指定 --languages python,rust,typescript，验证跨语言接口兼容性
• Real-time systems: 使用 --domain realtime，在模块规格中添加延迟预算和并发模型
• Embedded/constrained: --domain embedded 会添加内存预算和依赖项大小限制
• Empty project seed: 如果没有现有代码，/planner design <name> --seed 会在生成架构的同时创建最小模板

面向 AIGC 的输出

软件规划文档必须针对具体项目，包含具体数字和约束，而不是通用模板文本。完整的反 AIGC 检测规则请参阅 rules/anti-aigc.md。

关键要求：

• 需求必须包含量化约束，不能只写“良好的用户体验”
• 模块描述必须包含行数目标和依赖方向
• 技术选型必须说明拒绝其他方案的原因
• 每个“优秀／稳健／强大”都必须替换为可衡量的标准

版本历史

版本	日期	变更
1.0.0	2026-04-01	初始版本，涵盖 CLI／GUI／Web 规划和学术研究集成
1.0.1	2026-05-09	新增安全规则、示例、故障排除和边缘情况

规则

• rules/pre-development.md - 研究和规划阶段
• rules/interface-design.md - CLI／GUI／Web 模式
• rules/documentation.md - README 要求
• rules/sample-data.md - 测试数据创建
• rules/anti-aigc.md - 软件规划反 AIGC 检测规则

验证清单

在认为项目已完成之前，请验证以下各项。所有模块的代码总行数应达到 500 行以上。CLI 应提供统一的标志（-V、-v、-o、--json、-q）。GUI 应采用 PySide6 默认样式，不使用自定义样式。Web 界面应提供 REST API。所有函数都应返回 ToolResult。数据目录中应存在示例数据文件。应定义测试用例。README.md 应包含全部 9 个章节，每章不少于 200 个词。README_CN.md 应包含全部 9 个章节，每章不少于 200 个词。pdf/ 目录中应包含学术论文 PDF。应存在 GPLv3 LICENSE 文件。应存在 requirements.txt。应正确配置 pyproject.toml。应存在 PyPI 上传脚本。

快速入门模板

# 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}

另请参阅

• python-project-developer 中的 /python-project — 实现规划好的项目结构
• master-architect 中的 /architect design — 详细的架构拆解
• coding-agent-patterns 中的 /agent-patterns — 多界面应用的集成模式