pdd

638 57 简单 1 次阅读今天MITAgent插件开发框架语言模型图像

AI 解读由 AI 自动生成，仅供参考

pdd（Prompt-Driven Development）是一款专为 AI 时代打造的命令行开发工具，旨在通过自然语言提示词驱动完整的代码生成与维护流程。它主要解决了传统开发中从需求理解到代码实现、测试验证环节耗时较长的问题，让开发者能够直接将 GitHub 议题（Issue）转化为可运行的代码或测试用例。

这款工具特别适合希望提升开发效率的软件工程师、全栈开发者以及热衷于探索 AI 辅助编程的技术团队。用户只需在终端输入简单指令，如 pdd change 或 pdd bug，即可自动执行包含需求分析、架构设计、代码编写及测试生成的多步工作流。

pdd 的核心亮点在于其强大的“智能体（Agentic）”能力。它不仅支持自动生成代码和 UI 测试，还能进行探索性测试、契约验证及无障碍审计等复杂任务。此外，pdd 提供本地 Web 界面用于可视化项目管理，并拥有独特的 sync 命令，能够自动化整个开发生命周期，提供实时视觉反馈和精细的状态管理。无论是修复漏洞、实现新功能还是从产品需求文档生成架构文件，pdd 都能通过标准化的多步骤流程协助开发者高效完成，让编程变得更加直观和流畅。

使用场景

某初创团队的后端工程师正面临 GitHub 上堆积的 20 个功能需求与紧急 Bug 修复任务，需要在极短的版本周期内完成交付。

没有 pdd 时

上下文切换频繁：开发者需手动在 GitHub 议题、本地 IDE 和测试终端间反复跳转，复制粘贴错误日志和需求描述，打断心流。
测试驱动开发成本高：为复现 Bug 或验证新功能，必须人工编写大量样板测试代码，耗时且容易遗漏边界条件。
流程标准化难：缺乏统一的执行标准，不同成员处理议题的步骤各异，导致代码风格不一致且审查（Code Review）效率低下。
状态追踪滞后：无法实时可视化开发进度，往往等到编码结束才发现理解偏差，返工成本巨大。

使用 pdd 后

一键自动执行：直接运行 pdd bug <issue-url> 或 pdd change <issue-url>，pdd 自动拉取议题内容并在本地启动包含 12 至 18 步的智能工作流。
智能生成与验证：pdd 自动生成失败测试用例并修复代码，甚至通过探索性测试和可访问性审计，确保产出质量符合预期。
流程高度统一：内置的标准化代理命令强制遵循最佳实践，无论谁操作，输出的代码结构和测试覆盖率都保持一致。
实时可视反馈：通过 localhost:9876 界面实时监控 pdd 的思考路径与执行状态，随时干预决策，实现“所见即所得”的开发体验。

pdd 将原本碎片化的人工编码过程转化为自动化的智能闭环，让开发者从繁琐的执行者转变为高效的项目指挥官。

运行环境要求

操作系统

macOS
Linux
Windows

GPU

未说明

内存

未说明

依赖

notes该工具主要作为命令行接口运行，依赖外部 AI 代理（如 Claude Code、Gemini CLI 或 Codex CLI）执行实际代码生成任务。推荐使用 'uv' 进行安装以自动管理环境。本地模式需配置 LLM API 密钥（支持 OpenAI、Anthropic、Google 等），云端模式则通过 GitHub SSO 认证。macOS 用户需先安装 Xcode Command Line Tools 和 Homebrew。

python3.8+

litellm>=1.75.5

GitHub CLI (gh)

Claude Code / Gemini CLI / Codex CLI (至少其一)

快速开始

PDD（提示驱动开发）命令行界面

简介

PDD（提示驱动开发）是一个用于 AI 驱动的代码生成与维护的工具集。

开始使用非常简单：

# 安装并运行
uv tool install pdd-cli
pdd setup
pdd connect

这将启动一个位于 localhost:9876 的 Web 界面，您可以在其中：

自动实现 GitHub 问题
根据提示生成和测试代码
可视化地管理您的 PDD 项目

PDD 手绘演示

对于命令行用户，PDD 还提供了强大的 代理式命令，可自动实现 GitHub 问题：

pdd change <issue-url> - 实现功能请求（12 步流程）
pdd bug <issue-url> - 为 Bug 创建失败测试
pdd fix <issue-url> - 修复失败测试
pdd generate <issue-url> - 从 PRD 问题生成 architecture.json（11 步流程）
pdd test <issue-url> - 从问题描述生成 UI 测试（包含探索性测试、契约验证、无障碍审计的 18 步流程）

对于基于提示的工作流，sync 命令通过智能决策、实时可视化反馈和复杂的状态管理，自动化整个开发周期。

白皮书

如需详细了解提示驱动开发的概念、架构及优势，请参阅我们的完整白皮书。本文档深入探讨了 PDD 的理念、其相对于传统开发的优势，并包含基准测试和案例研究。

阅读包含基准测试的完整白皮书

另请参阅《提示驱动开发教义》，了解核心原则和实践：docs/prompt-driven-development-doctrine.md

安装

macOS 前置条件

在 macOS 上，安装 PDD 之前需要先安装一些前置条件：

安装 Xcode 命令行工具（Python 编译所需）：
```
xcode-select --install
```

安装 Homebrew（推荐的 macOS 包管理器）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，将 Homebrew 添加到您的 PATH 中：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile && eval "$(/opt/homebrew/bin/brew shellenv)"

安装 Python（如果尚未安装）：
```
# 检查是否已安装 Python
python3 --version

# 如果未找到 Python，则通过 Homebrew 安装
brew install python
```
注意：较新的 macOS 版本不再预装 Python。PDD 需要 Python 3.8 或更高版本。brew install python 命令会安装最新的 Python 3 版本。

推荐方法：uv

我们建议使用 uv 包管理器来安装 PDD，以获得更好的依赖项管理和自动环境配置：

# 如果尚未安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用 uv 工具安装 PDD
uv tool install pdd-cli

此安装方法可确保：

更快的安装速度和优化的依赖解析
自动设置环境，无需手动配置
正确处理 PDD_PATH 环境变量
更好地与其他 Python 包隔离

安装完成后，PDD CLI 将立即可用，无需任何额外的环境配置。

验证安装：

pdd --version

当 CLI 已添加到您的 PATH 后，继续执行：

pdd setup

该命令会检测代理式 CLI 工具、扫描 API 密钥、配置模型，并初始化本地配置文件。如果您推迟此步骤，CLI 会在您首次运行其他命令时检测到缺少的设置文件，并显示提醒横幅，以便您稍后完成设置（一旦 ~/.pdd/api-env 存在，或您的项目已通过 .env 或 .pdd/ 提供凭据，横幅将被隐藏）。

替代方案：pip 安装

如果您更喜欢使用 pip，可以使用以下命令安装 PDD：

pip install pdd-cli

高级安装选项

虚拟环境安装

# 创建虚拟环境
python -m venv pdd-env

# 激活环境
# 在 Windows 上：
pdd-env\Scripts\activate
# 在 Unix/MacOS 上：
source pdd-env/bin/activate

# 安装 PDD
pip install pdd-cli

开始使用

选项 1：Web 界面（推荐）

使用 PDD 最简单的方式是通过 Web 界面：

# 1. 安装 PDD
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install pdd-cli

# 2. 运行设置（API 密钥、Shell 补全）
pdd setup

# 3. 启动 Web 界面
pdd connect

这将打开一个基于浏览器的界面，您可以在其中：

运行命令：直观地执行 pdd change、pdd bug、pdd fix、pdd sync 等命令
浏览文件：查看和编辑项目中的提示、代码和测试
远程访问：通过 PDD Cloud 从任何浏览器访问您的会话（使用 --local-only 可禁用）

选项 2：基于问题的 CLI

对于命令行爱好者，可以直接实现 GitHub 问题：

前置条件：

GitHub CLI - 访问问题所必需：
```
brew install gh && gh auth login
```
一种代理式 CLI - 运行工作流所必需（至少安装一种）：
- Claude Code：npm install -g @anthropic-ai/claude-code（需要 ANTHROPIC_API_KEY）
- Gemini CLI：npm install -g @google/gemini-cli（需要 GOOGLE_API_KEY 或 GEMINI_API_KEY）
- Codex CLI：npm install -g @openai/codex（需要 OPENAI_API_KEY）

使用方法：

# 实现功能请求
pdd change https://github.com/owner/repo/issues/123

# 或修复 Bug
pdd bug https://github.com/owner/repo/issues/456
pdd fix https://github.com/owner/repo/issues/456

选项 3：手动提示工作流

用于学习 PDD 基础知识或处理现有提示文件：

cd your-project
pdd sync module_name  # 完整自动化流程

请参阅下方的【快速入门 Hello 示例】，获取逐步介绍。

🚀 快速入门（Hello 示例）

如果你想了解 PDD 的基本原理，请按照本手册示例来实际体验。

安装先决条件（macOS/Linux）：

xcode-select --install      # 仅适用于 macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install pdd-cli
pdd --version

克隆仓库

  # 克隆仓库（如果尚未完成）
 git clone https://github.com/promptdriven/pdd.git
 cd pdd/examples/hello

设置一个 API 密钥（选择你的提供商）：

export GEMINI_API_KEY="your-gemini-key"
# 或者
export OPENAI_API_KEY="your-openai-key"

安装后设置（安装后的第一步必做）

运行全面的设置向导：

pdd setup

设置向导会执行以下步骤：

检测代理型 CLI 工具（Claude、Gemini、Codex），并在需要时提供安装和 API 密钥配置
在 .env、~/.pdd/api-env.* 和 shell 环境中扫描 API 密钥；如果没有找到任何密钥，则提示添加一个
根据你可用的密钥，从参考 CSV 文件 data/llm_model.csv 中配置顶级模型（ELO ≥ 1400），涵盖所有 LiteLLM 支持的提供商
可选地创建一个 .pddrc 项目配置文件
使用第一个可用的模型进行一次真实的 LLM 调用测试
打印一份结构化的摘要（CLI 工具、密钥、模型、测试结果）

该向导可以随时重新运行，以更新密钥、添加提供商或重新配置设置。

重要提示： 设置完成后，请加载 API 环境文件，以便在当前终端会话中使您的密钥生效：
source ~/.pdd/api-env.zsh   # 或 api-env.bash，取决于您的 shell
新的终端窗口将自动加载密钥。

如果你跳过这一步，当你第一次运行常规的 pdd 命令时，系统会检测到缺少设置文件，并显示提醒横幅，以便你稍后完成初始设置。

运行 Hello：

cd ../hello
pdd --force generate hello_python.prompt
python3 hello.py

✅ 预期输出：

hello

云端与本地执行

PDD 命令可以在云端或本地运行。默认情况下，所有命令都在云端模式下运行，这具有多项优势：

无需在本地管理 API 密钥
可访问更强大的模型
PDD 社区共享示例和改进
自动更新和优化
更好的成本优化

云端认证

在云端模式下运行时（默认），PDD 使用 GitHub 单点登录 (SSO) 进行认证。首次使用时，系统会提示您进行认证：

PDD 将打开您的默认浏览器并跳转到 GitHub 登录页面
使用您的 GitHub 账户登录
授权 PDD Cloud 访问您的 GitHub 个人资料
认证成功后，您可以返回终端继续使用 PDD

认证令牌会安全地存储在本地，并根据需要自动刷新。

本地模式要求

当使用 --local 标志在本地模式下运行时，您需要为语言模型设置 API 密钥：

# 对于 OpenAI
export OPENAI_API_KEY=your_api_key_here

# 对于 Anthropic
export ANTHROPIC_API_KEY=your_api_key_here

# 对于其他支持的提供商（LiteLLM 支持多个 LLM 提供商）
export PROVIDER_API_KEY=your_api_key_here

将这些添加到您的 .bashrc、.zshrc 或等效文件中，以确保持久性。

PDD 的本地模式使用 LiteLLM（版本 1.75.5 或更高）与语言模型交互，提供：

支持多个模型提供商（OpenAI、Anthropic、Google/Vertex AI 等）
根据强度设置自动选择模型
响应缓存以提高性能
智能的 token 使用跟踪和成本估算
当缺少密钥时，可交互式获取 API 密钥

当密钥缺失时，PDD 会以交互方式提示您输入，并将其安全地存储在您的本地 .env 文件中。

本地模型配置

PDD 使用 CSV 文件来配置模型选择和功能。此配置从以下位置加载：

用户特定配置：~/.pdd/llm_model.csv（如果存在，则优先使用）
项目特定配置：<PROJECT_ROOT>/.pdd/llm_model.csv
包含的默认配置：随 PDD 安装一起提供（当没有本地配置时作为后备）

CSV 文件包含以下列：

provider：LLM 提供商（例如，“openai”、“anthropic”、“google”）
model：LiteLLM 模型标识符（例如，“gpt-4”、“claude-3-opus-20240229”）
input/output：每百万 tokens 的成本
coding_arena_elo：编码能力的 ELO 评分
api_key：所需 API 密钥的环境变量名称
structured_output：模型是否支持结构化 JSON 输出
reasoning_type：推理能力的支持程度（“无”、“预算”或“努力”）

有关受支持的模型和示例行的具体且最新的参考信息，请参阅此仓库中捆绑的 CSV 文件：pdd/data/llm_model.csv。

要获取用于自定义配置的正确模型标识符，请参考 LiteLLM 模型列表文档。LiteLLM 通常使用 provider/model_name 格式的模型标识符（例如，“openai/gpt-4”、“anthropic/claude-3-opus-20240229”）。

常见安装问题排查

命令未找到

# 如有必要，添加到 PATH
export PATH="$HOME/.local/bin:$PATH"

权限错误

# 使用用户权限安装
pip install --user pdd-cli

macOS 特定问题
- 未找到 Xcode 命令行工具：运行 xcode-select --install 以安装所需的开发工具
- 未找到 Homebrew：按照上述先决条件部分中的命令安装 Homebrew
- 未找到 Python 或版本不正确：通过 Homebrew 安装 Python 3：brew install python
- 编译期间权限被拒绝：确保 Xcode 命令行工具已正确安装，并且您对安装目录具有写入权限
- uv 安装失败：尝试通过 Homebrew 安装 uv：brew install uv
- Python 版本冲突：如果您有多个 Python 版本，请确保 python3 指向 Python 3.8+：which python3 && python3 --version

版本

当前版本：0.0.179

要检查已安装的版本，请运行：

pdd --version

PDD 包含自动更新功能，以确保您始终拥有最新的功能和安全补丁。您可以使用环境变量控制此行为（请参阅下方的“自动更新控制”部分）。

支持的编程语言

PDD 支持多种编程语言，包括但不限于：

Python
JavaScript
TypeScript
Java
C++
Ruby
Go

具体使用的语言通常由提示文件的命名约定决定，或在命令选项中指定。

提示文件命名规范

PDD 中的提示文件遵循以下特定命名格式：

<basename>_<language>.prompt

其中：

<basename> 是文件或项目的基名
<language> 是提示文件所使用的编程语言或上下文

示例：

factorial_calculator_python.prompt（基名：factorial_calculator，语言：python）
responsive_layout_css.prompt（基名：responsive_layout，语言：css）
data_processing_pipeline_python.prompt（基名：data_processing_pipeline，语言：python）

提示驱动开发理念

核心概念

提示驱动开发（PDD）颠覆了传统的软件开发方式，将提示视为主要的工件——而非代码。这种范式转变具有深远的影响：

提示作为真理来源：在传统开发中，源代码是定义系统行为的根本依据。而在 PDD 中，提示才是权威性的，代码则是由提示生成的产物。
自然语言优先于代码：提示主要以自然语言编写，这使得非程序员也能更容易理解，并且更清晰地表达意图。
再生式开发：当需要进行更改时，只需修改提示并重新生成代码，而不是直接编辑代码。这样可以保持需求与实现之间的概念一致性。
意图保留：提示不仅捕捉代码的“是什么”，还记录了“为什么”这样做的原因——以一种注释通常难以做到的方式保留设计 rationale。

思维模式

为了有效地使用 PDD，需要做出以下思维转变：

提示优先思维：始终先用提示定义所需内容，然后再生成任何代码。
双向流动：
- 提示 → 代码：主要方向（生成）
- 代码 → 提示：次要但关键的方向（保持提示与代码变更同步）
模块化提示：就像对代码进行模块化一样，也应将提示模块化为可组合的独立单元。
通过示例集成：模块之间通过其示例进行集成，这些示例充当接口，从而实现高效的标记引用。

PDD 工作流程：概念理解

PDD 中的每个工作流程都针对一个基本的开发需求：

初始开发流程
- 目的：从零开始创建功能
- 概念流程：定义依赖关系 → 生成实现 → 创建接口 → 确保运行时功能 → 验证正确性
该流程体现了从提示到代码的完整流程，从概念到经过测试的实现。
代码到提示更新流程
- 目的：当代码发生变化时，保持提示作为真理来源
- 概念流程：将代码变更同步到提示 → 识别影响 → 传播变更
该流程确保信息从代码回流到提示，从而保持提示作为真理来源。
调试流程
- 目的：解决不同类型的问题
- 概念类型：
  - 上下文问题：处理提示解释中的误解
  - 运行时问题：修复执行失败
  - 逻辑问题：纠正错误行为
  - 可追溯性问题：将代码问题追溯到提示部分
这些流程认识到不同的错误需要不同的解决方法。
重构流程
- 目的：改善提示的组织结构和可重用性
- 概念流程：提取功能 → 确保依赖关系 → 创建接口
该流程与代码重构类似，但在提示层面进行操作。
多提示架构流程
- 目的：协调使用多个提示的系统
- 概念流程：检测冲突 → 解决不兼容问题 → 重新生成代码 → 更新接口 → 验证系统
该流程解决了管理多个相互依赖提示的复杂性。
增强阶段：在现有模块中添加功能时，使用功能增强流程。

工作流程选择原则

工作流程的选择应根据当前的开发阶段来决定：

创建阶段：构建新功能时，使用初始开发流程。
维护阶段：现有代码发生变更时，使用代码到提示更新流程。
问题解决阶段：根据问题类型选择合适的调试流程：
- 对于提示解释问题，使用预处理 → 生成流程。
- 对于运行时错误，使用崩溃流程。
- 对于逻辑错误，使用错误 → 修复流程。
- 对于定位问题提示部分，使用追踪流程。
重组阶段：当提示变得过于庞大或复杂时，使用重构流程。
系统设计阶段：在协调多个组件时，使用多提示架构流程。
增强阶段：在现有模块中添加功能时，使用功能增强流程。

PDD 设计模式

有效的 PDD 会采用以下常见模式：

通过自动依赖注入依赖项：自动将相关依赖项包含在提示中。
通过示例提取接口：创建最小化的参考实现以供重用。
双向可追溯性：维持提示部分与生成代码之间的联系。
测试驱动的提示修复：在修复问题时，使用测试来指导提示的改进。
分层提示组织：将提示从高层架构组织到详细的实现。

基本用法

pdd [全局选项] 命令 [选项] [参数]...

命令概览

以下是 PDD 提供的主要命令的简要概述。单击命令名称即可跳转到其详细说明部分：

命令关系

下图展示了 PDD 命令之间的交互方式：

graph TB
    subgraph 入口点
        connect["pdd connect（Web UI - 推荐）"]
        cli["直接 CLI"]
        ghapp["GitHub 应用"]
    end

    gen_url["pdd generate <url>"]

    subgraph 同步工作流
        sync["pdd sync"]
        s_deps["auto-deps"]
        s_gen["generate"]
        s_example["example"]
        s_crash["crash"]
        s_verify["verify"]
        s_test["test"]
        s_fix["fix"]
        s_update["update"]
    end

    checkup["pdd checkup <url>"]
    test_url["pdd test <url>"]
    bug_url["pdd bug <url>"]
    fix_url["pdd fix <url>"]
    change["pdd change <url>"]
    sync_url["pdd sync <url>"]

    connect --> gen_url
    cli --> gen_url
    ghapp --> gen_url
    gen_url --> sync
    sync --> s_deps
    s_deps --> s_gen
    s_gen --> s_example
    s_example --> s_crash
    s_crash --> s_verify
    s_verify --> s_test
    s_test --> s_fix
    s_fix --> s_update
    sync --> checkup
    checkup --> test_url
    checkup --> bug_url
    checkup --> change
    test_url --> fix_url
    bug_url --> fix_url
    change --> sync_url
    sync_url -.-> sync

关键概念：

入口点：pdd connect（Web 界面）、直接 CLI 或 GitHub 应用
起点：pdd generate <url> 会根据 PRD 的 GitHub 问题生成架构、提示和 .pddrc 文件。
核心循环：pdd sync 会对每个模块执行完整的自动依赖分析 → 生成 → 示例 → 故障重现 → 验证 → 测试 → 修复 → 更新循环。
健康检查：pdd checkup <url> 可以识别接下来需要关注的内容。
缺陷路径：test <url> 或 bug <url> 会发现失败的测试 → fix <url> 则用于解决这些问题。
功能路径：change <url> 用于实现功能需求 → sync <url> 会在受影响的模块中重新运行同步。

开始使用

connect：[推荐] 启动 Web 界面，进行可视化的 PDD 操作。
setup：配置 API 密钥和 Shell 补全功能。

代理式命令（基于问题驱动）

change：根据 GitHub 问题实现功能请求（12 步流程）。
bug：分析 Bug 并从 GitHub 问题中创建失败测试。
checkup：根据 GitHub 问题运行自动化项目健康检查（8 步流程）。
fix：修复失败测试（支持基于问题和手动模式）。
sync：根据 GitHub 问题进行多模块并行同步（当传入 URL 而不是基础名时）。
test：根据 GitHub 问题生成 UI 测试（代理模式下为 18 步流程）。

核心命令（基于提示）

sync：[提示工作流的主要命令] 自动化提示到代码的循环。
generate：根据提示文件生成可运行的代码；支持通过 -e/--env 使用参数化提示。
example：生成一个简洁示例，展示如何使用提示中定义的功能。
test：为代码文件及其提示生成或增强单元测试。
update：根据修改后的代码更新原始提示文件。
verify：通过运行程序并判断输出是否符合预期来验证功能正确性。
crash：修复导致崩溃的代码模块及其调用程序中的错误。

提示管理

preprocess：预处理提示文件，处理包含、注释和其他指令。
split：将大型提示文件拆分为更小、更易管理的部分。
extracts prune：清理孤立的提取缓存条目。
auto-deps：分析并插入提示文件所需的依赖项。
detect：分析提示，根据描述确定哪些提示需要更改。
conflicts：查找两个提示文件之间的冲突，并提出解决方案。
trace：根据给定的代码行号找到提示文件中对应的行数。

实用命令

auth：管理与 PDD Cloud 的认证。
sessions：管理 connect 的远程会话。

用户故事提示测试

PDD 可以根据存储为 Markdown 文件的用户故事来验证提示变更。这背后使用了 detect 功能：当 detect 返回无需更改提示时，该故事即通过。

默认设置：

故事文件位于 user_stories/ 目录下，文件名匹配 story__*.md。
提示文件从 prompts/ 目录加载（默认排除 *_llm.prompt 文件）。

可覆盖的设置：

PDD_USER_STORIES_DIR 用于设置故事目录。
PDD_PROMPTS_DIR 用于设置提示目录。

全局选项

这些选项可与任何命令一起使用：

--force：跳过所有交互式提示（文件覆盖、API密钥请求）。适用于 CI/自动化。
--strength FLOAT：设置 AI 模型的强度（0.0 到 1.0，默认为 0.5）。
- 0.0：最经济实惠的模型
- 0.5：默认的基础模型
- 1.0：功能最强的模型（ELO 评分最高）
--time FLOAT：控制支持推理能力的 LLM 模型的推理资源分配（0.0 到 1.0，默认为 0.25）。
- 对于具有特定推理令牌限制的模型（如 64k），值为 1.0 时将使用最大可用令牌数。
- 对于具有离散努力级别的模型，1.0 对应最高努力级别。
- 值介于 0.0 和 1.0 之间时，按比例缩放资源分配。
--temperature FLOAT：设置 AI 模型的温度（默认为 0.0）。
--verbose：增加输出详细程度以获取更详尽的信息。包括每次 LLM 调用的 token 数量和上下文窗口使用情况。
--quiet：减少输出详细程度以获得最少信息。
--output-cost PATH_TO_CSV_FILE：启用成本跟踪，并输出包含使用详情的 CSV 文件。
--review-examples：在执行命令前查看并选择性排除少样本示例。
--local：在本地而非云端运行命令。
--core-dump：捕获本次运行的调试包，以便后续回放和分析。
report-core：通过创建带有核心转储文件的 GitHub 问题来报告错误。
--context CONTEXT_NAME：覆盖自动上下文检测，使用 .pddrc 中指定的上下文。
--list-contexts：列出 .pddrc 中定义的所有可用上下文并退出。

核心转储调试包

如果出现问题且希望 PDD 团队能够重现，您可以在启用核心转储的情况下运行任何命令：

pdd --core-dump sync factorial_calculator
pdd --core-dump crash prompts/calc_python.prompt src/calc.py examples/run_calc.py crash_errors.log

当设置 --core-dump 时，PDD：

捕获完整的 CLI 命令及其参数
记录该次运行的相关日志和内部跟踪信息
将提示、生成的代码以及重现问题所需的关键元数据打包在一起

运行结束时，PDD 会打印核心转储包的路径。在打开 GitHub 问题或发送错误报告时，请附上该包，以便维护人员能够快速重现并诊断您的问题。

`report-core` 命令

report-core 命令可通过创建带有核心转储文件的 GitHub 问题来帮助您报告错误。它通过自动收集相关文件和信息简化了报告流程。

用法：

pdd report-core [OPTIONS] [CORE_FILE]

参数：

CORE_FILE：核心转储文件的路径（例如 .pdd/core_dumps/pdd-core-....json）。若省略，则使用最近一次的核心转储。

选项：

--api：直接通过 GitHub API 创建问题，而不是在浏览器中打开。这可以自动为附加文件创建 Gist。
--repo OWNER/REPO：覆盖目标仓库（默认为 promptdriven/pdd）。
--description, -d TEXT：简要描述发生的问题。

身份验证：

要使用 --api 标志，您需要通过 GitHub 身份验证。PDD 按照以下顺序检查凭据：

GitHub CLI：gh auth token（推荐）
环境变量：GITHUB_TOKEN 或 GH_TOKEN
旧版：PDD_GITHUB_TOKEN

文件跟踪与 Gists：

使用 --api 时，PDD 将：

收集所有相关文件（提示、代码、测试、配置、元文件）。
创建一个包含这些文件的私有 GitHub Gist。
在创建的问题中链接该 Gist。

这样可以确保调试时拥有所有必要上下文，同时保持问题正文简洁。如果您不使用 --api，文件将被截断以适应基于浏览器提交的 URL 长度限制。

上下文选择标志

--list-contexts 会读取最近的 .pddrc（从当前目录向上搜索），逐行打印可用上下文，并立即以状态码 0 退出。当此标志存在时，不会运行自动更新检查或子命令。
--context CONTEXT_NAME 会在同一 .pddrc 来源中提前验证。如果名称未知，CLI 将抛出 UsageError 并以代码 2 退出，然后再运行自动更新或子命令。
配置优先级为：CLI 选项 > .pddrc 上下文 > 环境变量 > 默认值。详情请参阅“配置”部分。

自动更新控制

PDD 会自动更新自身，以确保您拥有最新的功能和安全补丁。不过，您可以通过 PDD_AUTO_UPDATE 环境变量控制此行为：

# 禁用自动更新
export PDD_AUTO_UPDATE=false

# 启用自动更新（默认行为）
export PDD_AUTO_UPDATE=true

对于持久化设置，可将此环境变量添加到您的 shell 配置文件中（例如 .bashrc 或 .zshrc）。

这在以下情况下特别有用：

生产环境中，版本稳定性至关重要
CI/CD 流水线中，需要一致的行为
对版本敏感的项目，需要特定的 PDD 版本

AI 模型信息

PDD 使用大型语言模型来生成和操作代码。--strength 和 --temperature 选项允许您控制模型的输出：

强度：决定应使用多强大/昂贵的模型。较高值（接近 1.0）会选择性能更好、功能更强的模型（根据 ELO 评分筛选），而较低值（接近 0.0）则会选择更具成本效益的模型。
温度：控制输出的随机性。较高值会增加多样性，但可能导致结果不够连贯；较低值则会产生更专注、确定性的输出。
时间：（可选，由 --time FLOAT 控制）对于支持推理的模型，此选项可在最小值（0.0）和最大值（1.0）之间缩放分配的推理资源（例如令牌或努力级别），默认为 0.25。

在本地模式下运行时，PDD 使用 LiteLLM 根据包含以下内容的配置文件选择和与语言模型交互：

每百万 tokens 的输入和输出成本
编码能力的 ELO 评分
所需的 API 密钥环境变量
结构化输出能力标志
推理能力（基于预算或努力）

输出成本跟踪

PDD 包含一项用于跟踪和报告操作成本的功能。启用后，它会为每次命令执行生成包含使用详情的 CSV 文件。

使用方法

要启用成本跟踪，请在任何命令中使用 --output-cost 选项：

pdd --output-cost PATH_TO_CSV_FILE [COMMAND] [OPTIONS] [ARGS]...

PATH_TO_CSV_FILE 应为 CSV 输出的期望位置和文件名。

成本计算与展示

PDD 根据每次操作中 AI 模型的使用情况来计算成本。成本以美元（USD）为单位，并通过以下因素进行计算：

模型强度：较高的强度设置通常会导致更高的成本。
输入大小：较大的输入（例如较长的提示或代码文件）通常会产生更高的成本。
操作复杂性：某些操作（如包含多次迭代的 fix 和 crash）可能比简单操作更昂贵。

每项操作的具体成本由 LiteLLM 集成根据提供商当前的定价模型确定。PDD 使用内部定价表，该表会定期更新以反映最新的费率。

CSV 输出

生成的 CSV 文件包含以下列：

timestamp：命令执行的日期和时间
model：用于该操作的 AI 模型
command：已执行的 PDD 命令
cost：以美元计的操作估算成本（例如 0.05 表示 5 美分）。对于本地模型或不使用 LLM 的操作，此值将为零。
input_files：参与该操作的输入文件列表
output_files：由该操作生成或修改的输出文件列表

这一全面的输出不仅能够详细跟踪操作的成本和类型，还能记录每次 PDD 命令执行中涉及的具体文件。

环境变量

您可以通过环境变量设置成本输出 CSV 文件的默认位置：

PDD_OUTPUT_COST_PATH：成本跟踪 CSV 文件的默认路径。

如果设置了此环境变量，则 CSV 文件将默认保存到指定路径，除非被 --output-cost 选项覆盖。例如，如果 PDD_OUTPUT_COST_PATH=/path/to/cost/reports/，则 CSV 文件将保存到该目录，并使用默认文件名。

成本预算

对于支持该功能的命令（如 fix 命令），您可以使用 --budget 选项设置最大预算。这有助于防止意外的高额费用，尤其是在可能涉及多次 AI 模型调用的操作中。

示例：

pdd [GLOBAL OPTIONS] fix --budget 5.0 [OTHER OPTIONS] [ARGS]...

这将为 fix 操作设置 5.00 美元的最大预算。

命令

以下是 PDD 提供的主要命令：

1. sync

[主要命令] 自动为给定的 basename 执行完整的 PDD 工作流循环。该命令实现了白皮书中的整个同步周期，能够智能地确定所需的步骤，并按正确的顺序执行，同时提供实时可视化反馈和复杂的状态管理。

# 单模块同步
pdd [GLOBAL OPTIONS] sync [OPTIONS] BASENAME

# 从 GitHub 问题同步代理式多模块
pdd [全局选项] sync [选项] GITHUB_ISSUE_URL

重要提示：同步操作会频繁覆盖生成的文件，以保持输出内容为最新状态。在大多数实际运行中，请使用全局 --force 标志来允许覆盖而无需交互式确认：

pdd --force sync BASENAME

参数：

BASENAME：提示文件的基础名称（例如，“factorial_calculator_python.prompt”对应“factorial_calculator”）

选项：

--max-attempts INT：任何迭代循环中的最大修复尝试次数（默认值为3）
--budget FLOAT：整个同步过程允许的最大总成本（默认值为20.0美元）
--skip-verify：跳过功能验证步骤
--skip-tests：跳过单元测试的生成和修复
--target-coverage FLOAT：期望的代码覆盖率百分比（默认值为90.0）
--dry-run：显示该基础名称的实时同步分析，而不执行同步操作。这会执行与正常同步运行相同的状况分析，但不会获取独占锁或执行任何操作，因此即使有其他同步进程正在运行，也可以进行检查。
--no-steer：禁用同步操作的交互式引导
--steer-timeout FLOAT：引导提示的超时时间（默认值为8.0秒）。

实时进度动画： sync 命令提供实时可视化反馈，显示：

当前正在执行的操作（auto-deps、generate、example、crash、verify、test、fix、update）
文件状态指示器采用颜色编码：
- 绿色：文件存在且为最新
- 黄色：文件正在处理中
- 红色：文件存在错误或缺失
- 蓝色：文件正在分析中
运行中的总成本和已用时间
工作流步骤的进度

语言检测： sync 命令会自动检测编程语言，方法是扫描 prompts 目录中是否存在符合 {basename}_{language}.prompt 模式的现有提示文件。例如：

factorial_calculator_python.prompt → 生成 factorial_calculator.py
factorial_calculator_typescript.prompt → 生成 factorial_calculator.ts
factorial_calculator_javascript.prompt → 生成 factorial_calculator.js

如果对于同一个 basename 存在多个开发语言的提示文件，sync 将会同时处理所有这些文件。

语言过滤：sync 命令仅处理开发语言（python、javascript、typescript、java、cpp 等），并排除运行时语言（LLM）。以 _llm.prompt 结尾的文件仅供内部处理使用，不能构成有效的开发单元，因为它们缺少同步工作流所需的关联代码、示例和测试。

高级配置集成：

自动上下文检测：检测项目结构并应用来自 .pddrc 的适当设置
配置层级：CLI 选项 > .pddrc 上下文 > 环境变量 > 默认值
多语言支持：自动处理一个 basename 的所有语言变体
智能路径解析：针对复杂的项目结构使用先进的目录管理技术
上下文相关的设置包括输出路径、默认语言、模型参数、覆盖率目标和预算等。

工作流逻辑：

sync 命令会自动检测哪些文件已经存在，并执行相应的工作流程：

auto-deps：查找并将相关依赖注入到提示中——包括代码示例和文档文件（schema 文档、API 文档等）。移除重复包含文档的冗余内联内容。
generate：根据提示创建或更新代码模块
example：如果使用示例不存在或已过时，则生成新的使用示例
crash：修复任何运行时错误，使代码可执行
verify：对照提示意图运行功能验证（除非使用了 --skip-verify 选项）
test：如果单元测试不存在，则生成全面的单元测试（除非使用了 --skip-tests 选项）。认证模块会获得特定于认证的测试模式（模拟 OAuth 服务器、JWT 固定装置、令牌生命周期测试等）
fix：解决单元测试中发现的所有缺陷
update：将学习到的经验回传到提示文件中

高级决策机制：

基于指纹的变更检测：使用内容哈希值和时间戳精确检测哪些内容发生了变化
LLM 驱动的冲突解决：对于涉及多个文件更改的复杂场景，使用 AI 来确定最佳处理方案
持久化状态跟踪：维护同步历史并从以往操作中学习
智能锁管理：防止并发同步操作，并自动清理过期锁
检测哪些文件已经存在且为最新
跳过不必要的步骤（例如，如果提示未发生变化，则不会重新生成代码）
使用 git 集成来检测更改，并确定是增量再生还是完全再生
长期累积测试结果，而不是替换原有测试（每个目标保留一个测试文件）
自动处理各步骤之间的依赖关系

强大的状态管理：

指纹文件：维护 .pdd/meta/{basename}_{language}.json 文件，记录操作历史
运行报告：跟踪测试结果、覆盖率和执行状态
锁管理：通过基于文件描述符的锁定机制防止竞态条件
Git 集成：利用版本控制进行变更检测和安全回滚

.pdd 目录： PDD 在您的项目根目录下使用 .pdd 目录来存储各种元数据和配置文件：

.pdd/meta/：包含指纹文件、运行报告和同步日志
.pdd/locks/：存储用于防止并发操作的锁文件
.pdd/llm_model.csv：项目专用的 LLM 模型配置文件（可选）

通常应将此目录添加到版本控制系统中（锁文件除外），因为它包含了重要的项目状态信息。

环境变量：所有现有的 PDD 输出路径环境变量都会被尊重，从而使 sync 命令能够将文件保存到适合您项目结构的位置。

同步状态分析： sync 命令会维护详细的决策日志，您可以使用 --dry-run 选项查看这些日志：

# 查看当前同步状态分析（非阻塞）
pdd sync --dry-run calculator

# 查看复杂场景下的详细 LLM 推理
pdd --verbose sync --dry-run calculator

分析内容包括：

当前文件状态与指纹比较
实时决策推理（基于启发式方法与 LLM 驱动的分析）
带置信度的操作建议
建议操作的预估成本
锁定状态及潜在冲突
状态管理详情

--dry-run 选项会实时分析当前项目状态，因此即使其他同步操作正在进行中，也可以安全运行。这与查看历史日志不同——它显示的是根据当前文件状态，同步操作此刻将做出的决策。

使用 --verbose 结合 --dry-run 可以查看复杂多文件变更场景及高级状态分析中的详细 LLM 推理。

何时使用：这是大多数 PDD 工作流的推荐起点。当您希望确保所有工件（代码、示例、测试）都与提示文件保持最新和同步时，可以使用同步命令。该命令体现了 PDD 的理念，即将工作流视为一个批处理过程，开发者可以启动后稍后再回来，从而无需持续监控。

示例：

# 完整工作流，带有进度动画和智能决策
pdd --force sync factorial_calculator

# 高级同步，预算更高、自定义覆盖率，并提供完整可视化反馈
pdd --force sync --budget 15.0 --target-coverage 95.0 data_processor

# 快速同步，带实时状态更新的动画
pdd --force sync --skip-verify --budget 5.0 web_scraper

# 多语言同步，基于指纹的变更检测
pdd --force sync multi_language_module

# 查看全面的同步分析及决策分析
pdd sync --dry-run factorial_calculator

# 查看复杂冲突解决的详细同步分析及 LLM 推理
pdd --verbose sync --dry-run factorial_calculator

# 监控同步在不执行的情况下会做什么（包含状态分析）
pdd sync --dry-run calculator

# 上下文感知示例，自动检测配置
cd backend && pdd --force sync calculator     # 使用后端上下文设置并显示动画
cd frontend && pdd --force sync dashboard     # 使用前端上下文并提供实时反馈
pdd --context backend --force sync calculator # 显式覆盖上下文并显示进度

代理式多模块同步（GitHub 问题模式）：

当传入 GitHub 问题 URL 而不是基础名时，同步会进入代理模式：

模块识别：获取问题内容，并使用 LLM 识别需要同步的模块。
依赖验证：验证 architecture.json 中的依赖关系，必要时进行修正。
并行执行：通过 AsyncSyncRunner 派遣并行同步任务，采用依赖感知调度（最多 4 个并发工作者）。
实时进度：发布并更新 GitHub 评论，显示模块同步的实时状态。

# 根据 GitHub 问题识别的模块进行同步（并行且依赖感知）
pdd sync https://github.com/myorg/myrepo/issues/100

# 为大型模块增加额外超时时间
pdd sync --timeout-adder 60 https://github.com/myorg/myrepo/issues/100

选项（代理模式）：

--timeout-adder FLOAT：为每个模块的超时时间增加额外秒数（默认：0.0）。
--no-github-state：禁用 GitHub 状态持久化，仅使用本地状态。

跨机器恢复：工作流状态存储在隐藏的 GitHub 评论中，因此可以在任何机器上恢复。使用 --no-github-state 可禁用此功能。

2. generate

从提示文件生成可运行代码。该命令会生成满足提示中所有要求的完整实现代码。当检测到当前提示与其上次提交版本之间存在变更时，它可以自动执行增量更新，而不是完全重新生成。

# 基本用法
pdd [GLOBAL OPTIONS] generate [OPTIONS] PROMPT_FILE

参数：

PROMPT_FILE：用于生成代码的提示文件名。

选项：

--output LOCATION：指定生成代码的保存位置。支持从 -e/--env 中展开 ${VAR} 或 $VAR。默认文件名为 <basename>.<language_file_extension>。如果设置了环境变量 PDD_GENERATE_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。
--original-prompt FILENAME：用于生成现有代码的原始提示文件。若未指定，命令将自动使用 git 中提示文件的最新提交版本。
--incremental：即使变更显著，也强制执行增量补丁。此选项仅在指定了输出位置且文件已存在时有效。
--unit-test FILENAME：单元测试文件的路径。如果提供，则会禁用自动测试发现功能，仅将该文件的内容纳入提示中，指示模型生成能够通过指定测试的代码。
--exclude-tests：不自动包含默认测试目录中的测试文件。

参数变量 (-e/--env)：传递 key=value 对来参数化提示，以便通过多次调用 generate 并使用不同值，使一个提示生成多个变体（例如多个文件）。

语法：-e KEY=VALUE 或 --env KEY=VALUE（可重复）。
Docker 风格的环境回退：-e KEY 会从当前进程的环境变量 KEY 中读取 VALUE。
作用范围：适用于 generate。
优先级：通过 -e/--env 传递的值在此命令的模板展开过程中会覆盖同名的 OS 环境变量。

模板化：提示文件和 --output 值可能使用 $VAR 或 ${VAR} 引用变量。只有通过 -e/--env（或通过 -e KEY 的环境回退）显式提供的变量会被替换；其他所有以美元符号开头的文本都将保持原样。普通 $ 的使用无需转义。

在提示内容中：只有当提供了 VAR 时，$VAR 和 ${VAR} 才会被替换。
在输出路径中：使用 --output 时，PDD 也会使用相同的变量集展开 $VAR/${VAR}。
未知项：未提供值的占位符将保持不变。如果您传递了 -e KEY（无值），而 OS 环境中存在 KEY，则会使用该环境值。

示例：

# 基本参数化生成（Python 模块）
pdd generate -e MODULE=orders --output 'src/${MODULE}.py' prompts/module_python.prompt

# 从同一提示生成多个文件
pdd generate -e MODULE=orders   --output 'src/${MODULE}.py' prompts/module_python.prompt
pdd generate -e MODULE=payments --output 'src/${MODULE}.py' prompts/module_python.prompt
pdd generate -e MODULE=customers --output 'src/${MODULE}.py' prompts/module_python.prompt

# 多个变量
pdd generate -e MODULE=orders -e PACKAGE=core --output 'src/${PACKAGE}/${MODULE}.py' prompts/module_python.prompt

# Docker 风格的环境变量回退（从你的 shell 环境中读取 MODULE）
export MODULE=orders
pdd generate -e MODULE --output 'src/${MODULE}.py' prompts/module_python.prompt

Shell 引号选项：

如果值包含空格或 shell 特殊字符，请使用引号包裹 KEY=VALUE：-e "DISPLAY_NAME=Order Processor"。
PDD 侧展开（可移植）：防止 shell 展开，让 PDD 使用 -e/--env 来展开——例如，--output 'src/${MODULE}.py'。
Shell 侧展开（熟悉）：设置一个环境变量，让 shell 展开 --output 参数，同时仍然传递 -e KEY，以便提示词获取相同的值——例如：
- export MODULE=orders && pdd generate -e MODULE --output "src/$MODULE.py" prompts/module_python.prompt
- 或者在 POSIX shell 中直接内联：MODULE=orders pdd generate -e MODULE --output "src/$MODULE.py" prompts/module_python.prompt
- 注意：PowerShell/Windows shell 不同；PDD 侧展开在不同 shell 之间更具可移植性。

Git 集成：

当命令检测到当前提示词与其上次提交版本之间存在变化时，如果输出文件已存在，则会自动考虑增量生成。
如果执行增量生成，当前提示词和代码文件都会通过 git add 被暂存（如果尚未提交/添加），以确保在需要时可以回滚。
对于新文件（即不存在要更新的输出文件时）或现有输出文件被删除时，始终会进行完全再生。

何时使用：当您从头开始实现新功能或根据提示词的变化更新现有代码时，可以选择此命令。该命令会自动检测变化，并根据变化的重要程度决定是采用增量补丁还是完全再生。

示例：

# 基本生成，带有基于 Git 的自动变更检测
# （如果输出文件存在则为增量生成，否则为完全生成）
pdd [全局选项] generate --output src/calculator.py calculator_python.prompt 

# 强制增量补丁（要求输出文件已存在）
pdd [全局选项] generate --incremental --output src/calculator.py calculator_python.prompt

# 强制完全再生（只需先删除输出文件）
rm src/calculator.py  # 删除文件
pdd [全局选项] generate --output src/calculator.py calculator_python.prompt

# 指定不同的原始提示词（绕过 Git 检测）
pdd [全局选项] generate --output src/calculator.py  --original-prompt old_calculator_python.prompt calculator_python.prompt

代理架构模式：

当位置参数是一个 GitHub 问题 URL 而不是提示词文件时，generate 命令会进入代理架构模式。问题正文将作为 PRD（产品需求文档），并通过一个 11 步的代理工作流自动生成 architecture.json、.pddrc 文件以及提示词文件。

pdd generate https://github.com/owner/repo/issues/42

11 步工作流：

分析与生成（步骤 1–8）：

分析 PRD：从问题内容中提取功能、技术栈和需求
深度分析：功能分解、模块边界、共享关注点
研究：针对技术栈的文档和最佳实践进行网络搜索
设计：模块拆分，包括依赖关系图和优先级排序（认证模块会被分离出来，作为独立的关注点，赋予较低的优先级编号）
研究依赖项：为每个模块查找相关的 API 文档和代码示例
生成：生成完整的 architecture.json 和脚手架文件
生成 .pddrc：创建包含上下文特定路径的项目配置文件
生成提示词：为 architecture.json 中的每个模块创建提示词文件

验证（步骤 9–11）： 9. 完整性验证：检查所有模块是否都有提示词和依赖关系 10. 同步验证：对每个模块运行 pdd sync --dry-run 以发现路径问题 11. 依赖关系验证：预处理提示词，以验证 <include> 标签是否能正确解析

每个验证步骤最多会重试 3 次，并在继续下一步之前自动修复问题。

选项：

--skip-prompts：跳过提示词文件生成（步骤 8–11），仅生成 architecture.json 和 .pddrc

前提条件：

必须安装并认证 gh CLI
问题中必须包含描述项目范围的 PRD

工作流恢复：再次运行 pdd generate <issue-url> 将从上一次完成的步骤继续。状态会持久化到 GitHub 问题评论中，以便在不同机器上恢复。

硬性停止：如果 PRD 内容不足、技术栈不明确或需要进一步澄清，工作流将会停止。请解决相关问题后重新运行。

示例：

pdd generate https://github.com/myorg/myrepo/issues/42
# 生成：architecture.json、architecture_diagram.html、.pddrc、prompts/*.prompt

# 跳过提示词生成（更快，仅生成架构）
pdd generate --skip-prompts https://github.com/myorg/myrepo/issues/42
# 生成：architecture.json、architecture_diagram.html、.pddrc

提示词模板

模板是可重用的提示词文件，用于生成特定的工件（代码、JSON、测试等）。模板在 YAML 前言部分包含人类/CLI 元数据（由 CLI 解析，不会发送给 LLM），而主体部分则保持简洁且专注于模型。

前言（人类/CLI）：
- 名称、描述、版本、标签、语言、输出
- 变量：-e/--env 的模式（必填/可选、类型、示例）
- 使用方法：可复制的 pdd generate 命令
- 发现（可选）：CLI 执行的文件发现（根目录、模式、排除、大小写）
- 输出模式（可选）：CLI 用于验证以及 pdd templates show 使用的 JSON 结构
提示词主体（LLM）：
- 包含用于填充上下文的指令：<include>${VAR}</include>、<include-many>${LIST}</include-many>
- 清晰的指示和明确的输出契约；不含人类使用说明或发现逻辑

快速示例（模板）

# 最简（需提供 PRD）
pdd generate -e PRD_FILE=docs/specs.md --output architecture.json \
  pdd/templates/architecture/architecture_json.prompt

# 带有额外上下文
pdd generate -e PRD_FILE=docs/specs.md -e TECH_STACK_FILE=docs/tech_stack.md \
  -e DOC_FILES='docs/ux.md,docs/components.md' \
  -e INCLUDE_FILES='src/app.py,src/api.py,frontend/app/layout.tsx' \
  --output architecture.json pdd/templates/architecture/architecture_json.prompt

# 多个变体
pdd generate -e PRD_FILE=docs/specs.md -e APP_NAME=Shop   --output apps/shop/architecture.json   pdd/templates/architecture/architecture_json.prompt
pdd generate -e PRD_FILE=docs/specs.md -e APP_NAME=Admin  --output apps/admin/architecture.json  pdd/templates/architecture/architecture_json.prompt
pdd generate -e PRD_FILE=docs/specs.md -e APP_NAME=Public --output apps/public/architecture.json pdd/templates/architecture/architecture_json.prompt

# 4) 在输出路径中使用变量

# 5) 为方便起见，使用 shell 环境变量回退
export APP=shop
pdd generate -e APP -e PRD_FILE=docs/specs.md --output 'apps/${APP}/architecture.json' pdd/templates/architecture/architecture_json.prompt

模板编写提示

将人类指导信息放在 YAML 前置元数据中（包含示例、用法和备注的变量）；保持提示主体以模型为中心。
使用 <include>/<include-many> 引入精选的上下文内容；优先使用规范或配置文件，而非大段代码。
参数化包含：通过 -e 传递文件路径，例如 <include>${PRD_FILE}</include>；引擎会在变量展开后解析包含内容。
如果你的模板会输出特定文件名，请在示例命令中注明 --output。

行为说明

变量展开仅适用于通过 -e/--env 显式传递的变量（或通过 -e KEY 的环境变量回退机制）。其他 $NAME 出现处将保持不变。
--output 也支持使用同一组变量中的 $VAR 或 ${VAR}。
如果省略 --output，PDD 会根据提示文件的基本名称和检测到的语言扩展名推导出文件名；可通过设置 PDD_GENERATE_OUTPUT_PATH 将输出定向到一个公共目录。

模板相关命令

前置元数据会被解析（不会发送给 LLM），并用于：
- 定义变量模式及验证逻辑
- 提供使用示例（由 pdd templates show 渲染）
- 支持可选的 discover 设置（由 CLI 大写执行）
- 提供可选的 output_schema 进行验证
命令包括：
- pdd templates list [--json] [--filter tag=...]
- pdd templates show <name>
- pdd templates copy <name> --to prompts/
- pdd generate --template <name> [-e KEY=VALUE...] [--output PATH]

内置模板

PDD 可以随软件包分发一组精选的常用模板，帮助用户快速上手（例如前端/Next.js、后端/Flask、数据/ETL）。

内置模板的位置（打包形式）

在已安装的软件包目录下，路径为 pdd/templates/<category>/**/*.prompt（并附有可选的 README 或 index 文件）。从 PyPI 安装时，这些文件会作为包数据一同包含。

包含的入门模板

architecture/architecture_json.prompt：通用架构生成器（需要 -e PRD_FILE=...；支持可选的 TECH_STACK_FILE、DOC_FILES 和 INCLUDE_FILES）。

LLM 切换功能：

所有模板都支持 llm 参数来控制是否运行 LLM 生成：

llm=true（默认）：完整流程，包括 LLM 生成和后处理
llm=false：跳过 LLM 生成，仅执行后处理

架构 JSON 模板特性：

architecture/architecture_json 模板内置了自动 Mermaid 图表生成功能：

后处理：自动生成交互式的 HTML 格式的 Mermaid 架构图
可视化效果：生成 architecture_diagram.html 文件，其中模块按颜色区分（前端/后端/共享部分）
交互性：鼠标悬停时会显示模块详情、依赖关系及描述
独立性：HTML 文件自带嵌入的 Mermaid 库，可在离线状态下直接打开

示例命令：

# 完整流程（LLM 生成 + 后处理 + Mermaid HTML）
pdd generate --template architecture/architecture_json \
  -e PRD_FILE=docs/specs.md \
  -e APP_NAME="MyApp" \
  --output architecture.json
# 输出结果：architecture.json + architecture_diagram.html

# 仅后处理（跳过 LLM，基于已有 JSON 生成 HTML）
pdd generate --template architecture/architecture_json \
  -e APP_NAME="MyApp" \
  -e llm=false \
  --output architecture.json

# 结果在：architecture_diagram.html（来自现有的 architecture.json）

上下文 URL（可选字段）：

架构条目支持一个可选的 context_urls 数组，用于将每个模块的 Web 文档引用关联起来。当从架构生成提示时（通过 generate_prompt），这些 URL 会在依赖项部分以 <web> 标签的形式输出，从而使 LLM 在代码生成过程中能够获取相关的 API 文档。

{
  "filename": "orders_api_Python.prompt",
  "dependencies": ["models_Python.prompt"],
  "context_urls": [
    {"url": "https://fastapi.tiangolo.com/tutorial/first-steps/", "purpose": "FastAPI 路由模式"},
    {"url": "https://docs.pydantic.dev/latest/concepts/models/", "purpose": "Pydantic 模型验证"}
  ],
  ...
}

context_urls 字段由代理式架构工作流自动填充（步骤 5：研究依赖项），但也可以手动添加到任何架构条目中。

Front Matter（YAML）元数据

模板包含 YAML front matter 元数据，便于人类阅读：
- name、description、version、tags：用于文档和发现
- language、output：generate 的默认设置
- variables：用于 -e/--env 的参数模式（类型、是否必填、默认值）

示例（架构模板）：

---
name: architecture/architecture_json
description: 适用于多个技术栈的统一架构模板
version: 1.0.0
tags: [架构, 模板, json]
language: json
output: architecture.json
variables:
  TECH_STACK:
    required: false
    type: string
    description: 目标技术栈，用于界面设计和规范。
    examples: [nextjs, python, fastapi, flask, django, node, go]
  API_STYLE:
    required: false
    type: string
    description: 后端的 API 风格。
    examples: [rest, graphql]
  APP_NAME:
    required: false
    type: string
    description: 可选的应用名称，用于提供上下文。
    example: Shop
  PRD_FILE:
    required: true
    type: path
    description: 主要的产品需求文档 (PRD)，描述范围和目标。
    example_paths: [PRD.md, docs/specs.md, docs/product/prd.md]
    example_content: |
      标题：订单管理 MVP
      目标：使客户能够端到端地创建和跟踪订单。
      关键功能：
        - 创建订单：id、user_id、items[]、total、status
        - 查看订单：带有状态时间线的详情页
        - 列出订单：可按状态、日期、用户筛选
      非功能性要求：
        - P95 延迟 < 300ms 对于读取端点
        - 错误率 < 0.1%
  TECH_STACK_FILE:
    required: false
    type: path
    description: 技术栈概述（语言、框架、基础设施和工具）。
    example_paths: [docs/tech_stack.md, docs/architecture/stack.md]
    example_content: |
      后端：Python (FastAPI)、Postgres (SQLAlchemy)、PyTest
      前端：Next.js (TypeScript)、shadcn/ui、Tailwind CSS
      API：REST
      认证：Firebase Auth (GitHub 设备流)、用于 API 的 JWT
      基础设施：Vercel（前端）、Cloud Run（后端）、Cloud SQL（Postgres）
      可观测性：OpenTelemetry 跟踪、Cloud Logging
  DOC_FILES:
    required: false
    type: list
    description: 其他文档文件（用逗号或换行分隔）。
    example_paths: [docs/ux.md, docs/components.md]
    example_content: |
      设计概述、模式和约束
  INCLUDE_FILES:
    required: false
    type: list
    description: 特定的源文件列表（用逗号或换行分隔）。
    example_paths: [src/app.py, src/api.py, frontend/app/layout.tsx, frontend/app/page.tsx]
  usage:
    generate:
      - name: 最小化（仅 PRD）
        command: pdd generate -e PRD_FILE=docs/specs.md --output architecture.json pdd/templates/architecture/architecture_json.prompt
      - name: 包含技术栈概述
        command: pdd generate -e PRD_FILE=docs/specs.md -e TECH_STACK_FILE=docs/tech_stack.md --output architecture.json pdd/templates/architecture/architecture_json.prompt
  discover:
    enabled: false
    max_per_pattern: 5
    max_total: 10
---

注释

YAML front matter 会被解析，但不会发送给 LLM。使用 pdd templates show 可以查看变量、使用方法、发现功能以及输出模式。在 CLI 中可以通过 -e 参数传递变量。

模板变量（参考）

架构（architecture/architecture_json.prompt）
- PRD_FILE（路径，必填）：主要规格/PRD 文件路径
- TECH_STACK_FILE（路径，可选）：技术栈概述文件（包括 API 风格；例如 docs/tech_stack.md）
- APP_NAME（字符串，可选）：应用名称，用于提供上下文
- DOC_FILES（列表，可选）：用逗号或换行分隔的其他文档路径列表
- INCLUDE_FILES（列表，可选）：需要包含的源文件列表，用逗号或换行分隔
- SCAN_PATTERNS（列表，可选）：在 front matter 的 discover 中定义，并由 CLI 执行的发现模式
- SCAN_ROOT（路径，可选）：在 front matter 的 discover 中定义的发现根目录

注释

这些变量在每个模板顶部的 YAML front matter 中声明，以便清晰明了，并方便未来的 CLI 发现。在 CLI 解析 front matter 之前，可以按照示例所示，通过 -e 参数传递值。

复制并生成

将所需的模板复制到项目的 prompts/ 文件夹中，然后像往常一样使用 pdd generate。这样可以使提示与您的仓库版本化，从而方便您编辑和改进它们。
快速复制（Python 一行命令；在项目根目录运行）：

python - <<'PY'
from importlib.resources import files
import shutil, os

dst_dir = 'prompts/architecture'
src_dir = files('pdd').joinpath('templates/architecture')
os.makedirs(dst_dir, exist_ok=True)

for p in src_dir.rglob('*.prompt'):
    shutil.copy(p, dst_dir)
print(f'已从 {src_dir} 复制内置模板到 {dst_dir}')
PY

# 然后从复制的提示中生成
pdd generate --output architecture.json prompts/architecture/architecture_json.prompt

统一模板示例

# 前端（Next.js）— interface.page.route 和组件属性
pdd generate \
  -e APP_NAME=Shop \
  # （路由根据 PRD/技术栈/文件推断）
  -e PRD_FILE=docs/specs.md \
  -e DOC_FILES='docs/ux.md,docs/components.md' \
  -e TECH_STACK_FILE=docs/tech_stack.md \
  # 如果需要，发现功能已在模板 YAML 中配置，并由 CLI 执行
  --output architecture.json \
  pdd/templates/architecture/architecture_json.prompt

# 后端（Python）— interface.module.functions 或 interface.api.endpoints
pdd generate \
  -e PRD_FILE=docs/backend-spec.md \
  -e TECH_STACK_FILE=docs/tech_stack.md \
  -e INCLUDE_FILES='src/app.py,src/api.py,pyproject.toml' \
  --output architecture.json \
  pdd/templates/architecture/architecture_json.prompt

接口模式

核心键（每个条目）：
- reason、description、dependencies、priority、filename，以及可选的 tags。
接口对象（类型化，仅包含适用的部分）：
- type: component | page | module | api | graphql | cli | job | message | config
- component: props[]，可选的 emits[] 和 context[]
- page: route，可选的 params[]、layout 和 dataSources[]，其中每项都包含必填的 kind（如 api、query）和 source（URL 或标识符），以及可选的 method、description、auth、inputs[]、outputs[]、refreshInterval 和 notes
- module: functions[]，包含 name、signature，以及可选的 returns、errors 和 sideEffects
- api: endpoints[]，包含 method、path，以及可选的 auth、requestSchema、responseSchema 和 errors
- graphql: 可选的 sdl，或包含 queries[]、mutations[]、subscriptions[] 的 operations
- cli: commands[]，包含 name、可选的 args[]、flags[] 和 exitCodes[]；还可选的 io（stdin、stdout）
- job: trigger（cron/event），可选的 inputs[]、outputs[] 和 retryPolicy
- message: topics[]，包含 name、direction（publish 或 subscribe），以及可选的 schema 和 qos
- config: keys[]，包含 name、type，以及可选的 default、required 和 source（env、file 或 secret）
- 可选：version、stability（experimental 或 stable）

示例：

{
  "reason": "顶级产品页面",
  "description": "...",
  "dependencies": ["layout_tsx.prompt"],
  "priority": 1,
  "filename": "page_tsx.prompt",
  "tags": ["frontend","nextjs"],
  "interface": {
    "type": "page",
    "page": {"route": "/products", "params": [{"name":"id","type":"string"}]},
    "component": {"props": [{"name":"initialProducts","type":"Product[]","required":true}]}
  }
}

{
  "reason": "订单服务模块",
  "description": "...",
  "dependencies": ["db_python.prompt"],
  "priority": 1,
  "filename": "orders_python.prompt",
  "tags": ["backend","python"],
  "interface": {
    "type": "module",
    "module": {
      "functions": [
        {"name": "load_orders", "signature": "def load_orders(user_id: str) -> list[Order]"},
        {"name": "create_order", "signature": "def create_order(dto: OrderIn) -> Order"}
      ]
    }
  }
}

{
  "reason": "订单 HTTP API",
  "description": "...",
  "dependencies": ["orders_python.prompt"],
  "priority": 2,
  "filename": "api_python.prompt",
  "tags": ["backend","api"],
  "interface": {
    "type": "api",
    "api": {
      "endpoints": [
        {
          "method": "GET",
          "path": "/orders/{id}",
          "auth": "bearer",
          "responseSchema": {"type":"object","properties":{"id":{"type":"string"}}},
          "errors": ["404 Not Found","401 Unauthorized"]
        }
      ]
    }
  }
}

注意事项与建议

复制的模板应作为起点；请根据您的技术栈和规范进行编辑。
将模板与代码一起纳入版本控制，以保持“提示即真理”的模型。
如果您维护自己的模板集，请将其存储在 prompts/<org_or_team>/... 中，并使用 <include> 进行组合，以最大化复用。

模板：额外的用户体验

目标：
- 无需手动指定文件路径即可发现、检查和复制模板。
- 验证所需变量，并从模板元数据中显示默认值。
- 支持搜索顺序，以便项目模板可以覆盖打包模板。
命令：
- pdd templates list [--json] [--filter tag=frontend] 用于发现模板
- pdd templates show <name> [--raw] 用于查看元数据和变量
- pdd templates copy <name> --to prompts/ 用于将模板复制到您的仓库
- pdd generate --template <name> [-e KEY=VALUE...] [--output PATH]
示例用法：

# 发现和检查
pdd templates list --filter tag=frontend
pdd templates show frontend/nextjs_architecture_json

# 复制并定制
pdd templates copy frontend/nextjs_architecture_json --to prompts/frontend/

# 不指定文件路径生成
pdd generate --template frontend/nextjs_architecture_json \
  -e APP_NAME=Shop \
  # 路由从 PRD/技术栈/文件中推断
  --output architecture.json

搜索顺序：
- 项目：./prompts/**（允许团队覆盖）
- .pddrc 路径：任何配置的 templates.paths
- 打包模板：pdd/templates/**（内置模板）
- 可选：$PDD_PATH/prompts/**（组织级别的模板包）
模板前言：
- 在 .prompt 文件顶部使用 YAML 元数据声明 name、description、tags、version、language、默认 output 以及 variables（包括 required、default 和 type，如 string 或 json）。
- CLI 优先级：-e/--env 中的值会覆盖前言中的默认值；未知变量会被验证并提示用户输入。
- 示例：
```
---
name: frontend/nextjs_architecture_json
description: 从应用元数据生成 Next.js 的 architecture.json 文件
tags: [frontend, nextjs, json]
version: 1.0.0
language: json
output: architecture.json
variables:
  APP_NAME: { required: true }
  ROUTES:   { type: json, default: [] }
---
...提示内容...
```

3. 示例

创建一个紧凑的示例，演示如何使用在提示中定义的功能。类似于头文件或 API 文档，这会生成最小化的、token 效率高的代码，展示接口而不包含实现细节。

pdd [全局选项] example [选项] 提示文件 代码文件

参数：

提示文件：生成代码的提示文件名。
代码文件：现有代码文件的名称。

选项：

--output LOCATION：指定保存生成示例代码的位置。默认文件名为 <basename>_example.<language_file_extension>。如果设置了环境变量 PDD_EXAMPLE_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。
--format FORMAT：生成示例的输出格式（默认为 code）。有效值：
- code：使用语言特定的文件扩展名（例如，Python 的 .py，JavaScript 的 .js）。
- md：生成 Markdown 格式，扩展名为 .md。当指定了明确的 --output 路径时，--format 选项会相应地限制输出文件的扩展名。

使用场景：

依赖引用：示例可以作为其他提示的轻量级（token 效率高）接口参考，并可作为生成目标的依赖项。
健全性检查：示例程序通常用作 crash 和 verify 的可运行程序，提供快速的端到端健全性检查，以确保生成的代码能够按预期运行和行为。
自动依赖集成：auto-deps 命令可以扫描示例文件（例如 examples/**/*.py），并将相关引用插入到提示中。根据每个示例的内容（导入、API 使用、文件名），它会识别出有用的开发单元并将其作为依赖项。

何时使用：当需要创建其他提示可以高效导入的可重用引用时，选择此命令。这样可以生成 token 效率高的示例，相比包含完整实现，更容易在多个提示之间重复使用。

示例：

pdd [全局选项] example --output examples/factorial_calculator_example.py factorial_calculator_python.prompt src/factorial_calculator.py

4. 测试

为给定的代码文件及其对应的提示文件生成或增强单元测试。还支持从 GitHub 问题生成 UI 测试的 代理模式。

代理模式（UI 测试生成）

从 GitHub 问题生成 UI 测试。该问题描述了需要测试的内容（网页、CLI 或桌面应用），代理工作流会分析目标、制定测试计划并生成全面的 UI 测试。

pdd [全局选项] test <github-issue-url>

工作流程（18 步骤，配合 GitHub 评论）：

重复检查 - 搜索是否存在描述相同测试要求的现有问题。如果找到，则合并内容并关闭重复问题。
文档检查 - 审查仓库文档和代码库，以了解需要测试的内容。如果存在 OpenAPI/Swagger 规范，则会识别出来。
分析与澄清 - 确定问题中是否已包含足够的信息来创建测试。如果需要，会发布评论请求进一步澄清。
检测前端类型 - 确定测试类型：Web UI、CLI、桌面应用或 API。从而决定合适的测试框架。
创建测试计划 - 设计一个全面的测试计划，并验证其可行性。

5b. 增强测试计划 - 添加契约验证测试用例（基于 OpenAPI/Swagger 规范）以及可访问性测试用例（针对 Web 应用，使用 @axe-core/playwright 达到 WCAG 2.1 AA 级别）。

评估覆盖率 (仅限 Web，需安装 playwright-cli) - 将需求与增强后的测试计划进行比较，找出需要手动测试的差距。
创建手动测试清单 (仅限 Web) - 使用三种策略生成清单：逐页详尽测试、用户故事 walkthrough 以及可访问性抽查。
执行手动测试 (仅限 Web) - 通过 playwright-cli 命令执行清单中的项目。可在 CLI 模式下串行运行，或在 PDD_CLOUD_RUN=true 时通过 Cloud Batch 并行运行。
创建回归测试 (仅限 Web) - 生成能够重现第 8 步中发现的 bug 的自动化测试。
验证回归测试 (仅限 Web) - 确认回归测试会在当前代码上失败（证明确实存在 bug）。
循环检查 (仅限 Web) - 检查清单是否已完成。如果仍有未完成的项目，则返回第 8 步（最多循环 3 次）。
生成测试 - 根据增强后的计划，在工作树中创建测试，包括行为测试、契约测试和可访问性测试。
运行测试 - 对目标执行所有生成的测试。
修复并迭代 - 修复任何失败的测试，并重新运行直到通过为止。
验证测试与计划的一致性 - 将增强后的计划与生成的测试进行交叉核对。对于未实现的测试用例，生成缺失的测试。
运行新生成的测试 - 运行并修复第 15 步中生成的测试（如有）。
提交 PR - 创建一个带有详细说明的草稿 PR，包括测试计划覆盖率、契约测试摘要、可访问性审计摘要以及手动测试摘要。

执行模式：

模式	第 6–11 步的行为
CLI (`pdd test <url>`)	串行：每次只运行清单中的一个部分
GitHub App (`PDD_CLOUD_RUN=true`)	并行：分配到 Cloud Batch 的虚拟机上运行

先决条件：

第 6–11 步（手动/探索性测试）需要 PATH 中有 playwright-cli。如果未找到，则会跳过这些步骤并发出警告。
第 6–11 步仅适用于 Web 测试类型（TEST_TYPE: web）。

代理选项：

--timeout-adder FLOAT：为每一步的超时时间增加额外秒数（默认为 0.0）。
--no-github-state：禁用基于 GitHub 问题评论的状态持久化，仅使用本地状态。
--manual：使用传统的提示模式代替代理模式。

环境变量：

PDD_CLOUD_RUN=true：启用手动测试的并行执行模式（第 6–11 步）。
PDD_NO_GITHUB_STATE=1：禁用 GitHub 状态持久化。

跨机器恢复：默认情况下，工作流状态会存储在 GitHub 问题的隐藏评论中，从而允许从任何机器继续执行。使用 --no-github-state 可以禁用此功能。

示例（代理模式）：

# 从 GitHub 问题生成 UI 测试
pdd test https://github.com/myorg/myrepo/issues/789

# 在回答澄清问题后继续
pdd 测试 https://github.com/myorg/myrepo/issues/789

下一步 - 修复测试问题：

如果生成的测试发现需要代码修复的问题，请使用 pdd fix 并提供相同的议题 URL：

pdd fix https://github.com/myorg/myrepo/issues/789

手动模式（基于提示）

为给定的代码文件及其对应的提示文件生成或增强单元测试。

测试组织方式：

对于每个目标 <basename>，PDD 维护一个单独的测试文件（默认命名为 test_<basename>.<language_extension>，通常放置在 tests 目录下）。
新的测试会逐渐累积到该文件中，而不是从头开始重新生成。在扩充测试时，PDD 可以将新增内容合并到现有文件中（参见 --merge）。

pdd [全局选项] test [选项] 提示文件 代码文件或示例文件
pdd [全局选项] test --manual [选项] 提示文件 代码文件或示例文件

参数：

PROMPT_FILE：生成代码的提示文件名。
CODE_OR_EXAMPLE_FILE：代码实现或示例文件名。以 _example 结尾的文件被视为 TDD 风格测试生成的示例文件。

选项：

--output LOCATION：指定生成的测试文件保存位置。默认文件名为 test_<basename>.<language_file_extension>。如果指定名称的输出文件已存在，则会创建带有编号后缀的新文件（例如 test_calculator_1.py），而不会覆盖原有文件。
--language：指定编程语言。默认为提示文件名中指定的语言。
--coverage-report PATH：现有测试的覆盖率报告文件路径。提供此选项时，会生成额外的测试以提高覆盖率。
--existing-tests PATH [PATH...]：现有单元测试文件的路径。使用 --coverage-report 时必须提供此选项。可以提供多个路径。
--target-coverage FLOAT：期望达到的代码覆盖率百分比（默认为 90.0）。
--merge：与 --existing-tests 一起使用时，会将新测试合并到现有测试文件中，而不是创建单独的文件。

故事模式

生成或更新用户故事，并将其链接到相关的提示文件。

pdd [全局选项] test prompts/upload_python.prompt prompts/notify_python.prompt
pdd [全局选项] test user_stories/story__my_flow.md

行为：

如果输入是一个或多个 .prompt 文件，PDD 会生成 user_stories/story__<name>.md。
在生成故事的过程中，PDD 会运行提示检测，并自动将相关提示链接到 pdd-story-prompts 元数据中。
如果在生成时未检测到任何相关提示，元数据将回退到提供的提示文件输入。
如果 pdd-story-prompts 元数据已经存在且解析正常，PDD 将保持其不变。
如果元数据缺失（或过时），PDD 会运行提示检测并写入： 
这使得在 pdd detect --stories 中能够对提示子集进行确定性验证。

提供命令特定的上下文

虽然提示是主要的指令来源，但某些 PDD 命令（如 test 和 example）还可以通过项目特定的上下文文件进一步指导。这些命令在其内部提示预处理阶段，可能会自动在当前工作目录中查找约定文件（例如 context/test.prompt, context/example.prompt）。

如果找到，这些上下文文件的内容会被包含进来（使用 preprocess 部分中描述的 <include> 机制），并整合到命令使用的内部提示中。这允许您为项目提供特定的指导，例如：

指定所需的导入语句。
推荐首选的测试框架或库。
提供项目特定的编码规范或模式。

示例： 创建一个名为 context/test.prompt 的文件，内容如下：

请确保所有测试都使用 'unittest' 框架，并将主模块以 'from my_module import *' 的形式导入。

这可能会影响在同一目录下运行 pdd test 命令时的输出。

注意： 此功能依赖于特定 PDD 命令的内部实现，这些命令需要包含用于这些约定上下文文件的必要 <include> 标签。它主要用于 test 和 example 命令，但未来也可能被其他命令采用。请查阅具体命令的文档或进行试验，以确认某个命令是否使用此模式。

基本示例：

生成初始单元测试：

pdd [全局选项] test --output tests/test_factorial_calculator.py factorial_calculator_python.prompt src/factorial_calculator.py

从示例文件生成测试（TDD 风格）：

pdd [全局选项] test --output tests/test_calculator.py calculator_python.prompt examples/calculator_example.py

生成额外测试以提高覆盖率（使用多个现有测试文件）：

pdd [全局选项] test --coverage-report coverage.xml --existing-tests tests/test_calculator.py --existing-tests tests/test_calculator_edge_cases.py --output tests/test_calculator_enhanced.py calculator_python.prompt src/calculator.py

提高覆盖率并合并到现有测试中：

pdd [全局选项] test --coverage-report coverage.xml --existing-tests tests/test_calculator.py --merge --target-coverage 95.0 calculator_python.prompt src/calculator.py

覆盖率分析策略

当提供覆盖率选项时，测试命令将执行以下操作：

分析覆盖率报告，识别：
- 未覆盖的行和分支
- 部分测试的条件
- 缺失的边界情况
优先生成以下类型的测试用例：
- 复杂的未覆盖代码路径
- 错误条件
- 边界值
- 集成点
保持与以下内容的一致性：
- 现有测试风格和模式
- 项目的测试规范
- 原始提示的意图

5. 预处理

预处理提示文件并保存结果。

pdd [GLOBAL OPTIONS] preprocess [OPTIONS] PROMPT_FILE

参数：

PROMPT_FILE: 要预处理的提示文件的文件名。

选项：

--output LOCATION: 指定保存预处理后提示文件的位置。默认文件名为 <basename>_<language>_preprocessed.prompt。
--xml: 自动为较长且复杂的提示文件插入 XML 分隔符，以更好地组织内容。使用此选项时，提示仅会被预处理以插入 XML 分隔符，而不会进行其他预处理。
--recursive: 递归预处理提示文件中的所有提示文件。
--double: 将花括号加倍。
--exclude: 用于排除在花括号加倍之外的键列表。

类 XML 标签

PDD 在提示文件中支持以下类 XML 标签。注意：XML 类标签（<include>、<include-many>、<shell>、<web>）在 fenced code 块（``` 或 ~~~）或内联单反引号中会保持原样，以便文档示例保持字面意思。

include: 将文件内容包含到提示中。文件路径始终是标签主体。可选属性可用于提取特定部分，而不是整个文件：
```
<include>./path/to/file.txt</include>
<include select="def:foo,class:Bar">src/utils.py</include>
<include select="class:Handler" mode="interface">src/api.py</include>
<include query="authentication flow">docs/api_reference.md</include>
```
- select= — 确定性结构化提取（函数、类、行范围、标题、正则表达式、JSON/YAML 路径）。可通过逗号分隔组合使用。
- mode="interface" — 仅适用于 Python。提取签名和文档字符串，并将函数体替换为 ...。
- query= — 基于 LLM 的语义提取，缓存在 .pdd/extracts/ 中。
- optional — 当 <include ...> 标签上出现此属性时，如果文件不存在，在非递归预处理过程中会解析为空字符串 ("")，同时仍会记录警告。
- 当 select= 和 query= 同时存在时，select= 优先（不产生 LLM 费用）。
此机制也被一些命令（如 test 和 example）内部使用，以自动引入项目特定的上下文文件，如果它们存在于常规位置（例如 context/test.prompt）。有关详细信息，请参阅“提供命令特定的上下文”。完整的选择器参考，请参阅 Prompting Guide。
pdd: 表示将在预处理后的提示中被移除的注释，包括标签本身。
```
<pdd>This is a comment that won't appear in the preprocessed output</pdd>
```
shell: 执行 shell 命令并将输出包含到提示中，同时移除 shell 标签。
```
<shell>ls -la</shell>
```
web: 抓取网页并将其中的 Markdown 内容包含到提示中，同时移除 web 标签。
```
<web>https://example.com</web>
```

三重反引号包含

PDD 支持两种包含外部内容的方式：

三重反引号包含：将三重反引号中的尖括号替换为指定文件的内容。

```
<./path/to/file.txt>
```
这将被递归处理，直到三重反引号中不再有尖括号为止。

XML 包含标签：如上所述。

花括号处理

当使用 --double 选项时：

如果单个花括号尚未加倍，则会加倍；
已经加倍的花括号将保持不变；
嵌套花括号会得到正确处理；
对代码块（JSON、JavaScript、TypeScript、Python）有特殊处理；
包含花括号的多行变量也会得到特殊处理。

使用 --exclude 选项可以指定应排除在花括号加倍之外的键。此选项仅在一对单个花括号内的整个字符串与其中一个排除键完全匹配时才适用。

例如，使用 --exclude model：

{model} 保持 {model} 不变（因完全匹配而被排除）。
{model_name} 会被加倍，因为 'model_name' 并不完全等于 'model'。
{api_model} 也会被加倍，因为它也不完全匹配。
包含其他内容的花括号，即使与该键相关（例如 var={key}_value），通常仍会遵循加倍规则，除非内部的 {key} 本身被排除。

示例命令：

pdd [GLOBAL OPTIONS] preprocess --output preprocessed/factorial_calculator_python_preprocessed.prompt --recursive --double --exclude model,temperature factorial_calculator_python.prompt

6. 修复

修复代码和单元测试中的错误。支持两种模式：代理式端到端修复（给定 GitHub URL 时为默认模式），用于多开发者单元测试修复；以及手动模式，用于单个开发者单元测试修复，需明确指定文件参数。

代理式端到端修复模式（GitHub URL）：

pdd [GLOBAL OPTIONS] fix [OPTIONS] <GITHUB_ISSUE_URL>

手动模式（文件参数）：

pdd [GLOBAL OPTIONS] fix --manual [OPTIONS] PROMPT_FILE CODE_FILE UNIT_TEST_FILE ERROR_FILE

手动模式参数

PROMPT_FILE: 生成待测试代码的提示文件名。
CODE_FILE: 要修复的代码文件名。
UNIT_TEST_FILES: 单元测试文件名。可以提供多个文件，每个文件将单独处理。
ERROR_FILE: 包含单元测试运行时错误信息的文件名。可选，与 --loop 命令一起使用时无需存在。

共享选项

--manual: 使用手动模式，需明确指定文件参数（用于传统或单个开发者单元测试修复）。
--verbose: 显示详细的处理输出。
--quiet: 屏蔽所有输出，仅显示错误。
--protect-tests/--no-protect-tests: 启用时，防止 LLM 修改测试文件。LLM 会将测试视为只读规范，仅修复代码。这在已知由 pdd bug 创建的测试正确时尤为有用。默认：--no-protect-tests。

代理式端到端修复选项

--timeout-adder FLOAT: 每个步骤超时时间额外增加的秒数（默认：0.0）。
--max-cycles INT: 放弃前的最大外层循环次数（默认：5）。
--resume/--no-resume: 如果有保存的状态，则从中恢复（默认：--resume）。
--force: 覆盖分支不匹配的安全检查。默认情况下，如果当前 Git 分支与问题中预期的分支不匹配，命令会中止（以防止意外修改错误的代码库）。

手动模式选项

--output-test LOCATION：指定保存修复后的单元测试文件的路径。默认文件名为 test_<basename>_fixed.<language_file_extension>。警告：如果同时提供了多个 UNIT_TEST_FILES 和此选项，只有最后一个处理的测试文件的修复内容会被保存到该位置，之前的结果将被覆盖。若需为每个文件单独保存修复结果，请省略此选项。
--output-code LOCATION：指定保存修复后代码文件的路径。默认文件名为 <basename>_fixed.<language_file_extension>。如果设置了环境变量 PDD_FIX_CODE_OUTPUT_PATH，则文件会保存到该路径，除非被此选项覆盖。
--output-results LOCATION：指定保存错误修复过程结果的路径。默认文件名为 <basename>_fix_results.log>。如果设置了环境变量 PDD_FIX_RESULTS_OUTPUT_PATH`，则文件会保存到该路径，除非被此选项覆盖。
--loop：启用迭代修复流程。
- --verification-program PATH：指定用于验证代码是否仍能正确运行的 Python 程序路径。
- --max-attempts INT：设置放弃前的最大修复尝试次数（默认为 3 次）。
- --budget FLOAT：设置修复过程允许的最大成本（默认为 5.0 美元）。
--auto-submit：在修复循环中所有单元测试通过时，自动提交示例。

当使用 --loop 选项时，修复命令将通过多次迭代尝试修复错误。每次修复尝试后，它都会使用指定的验证程序检查代码是否能够正确运行。该过程将持续进行，直到错误被修复、达到最大尝试次数或预算耗尽为止。

输出：

修复后的单元测试文件。
修复后的代码文件。
包含 LLM 模型输出及单元测试结果的记录文件。
使用 --loop 时的输出打印，包含：
- 成功状态（布尔值）
- 总修复尝试次数
- 所有修复尝试的总成本此外，还会为不同迭代生成带有时间戳命名的单元测试和代码文件中间版本（例如：basename_1_0_3_0_20250402_124442.py, standalone_test_1_0_3_0_20250402_124442.py）。

示例：

pdd [全局选项] fix --output-code src/factorial_calculator_fixed.py --output-results results/factorial_fix_results.log factorial_calculator_python.prompt src/factorial_calculator.py tests/test_factorial_calculator.py tests/test_factorial_calculator_edge_cases.py errors.log

在此示例中，pdd fix 将针对每个测试文件运行，并将修复后的测试文件分别保存为 tests/test_factorial_calculator_fixed.py 和 tests/test_factorial_calculator_edge_cases_fixed.py。

智能代理回退模式

（此功能同样适用于 crash 和 verify 命令。）

对于标准迭代修复流程无法解决的特别棘手的 bug，pdd fix 提供了一种强大的智能代理回退模式。启用后，它会调用一个具备项目上下文感知能力的 CLI 代理，以更广泛的背景信息尝试修复问题。

工作原理： 如果标准修复循环完成所有尝试仍未使测试通过，则智能代理回退模式将接管。它会构建一套详细的指令，并将修复任务委托给专门的 CLI 代理，如 Google 的 Gemini、Anthropic 的 Claude 或 OpenAI 的 Codex。

使用方法：

此功能仅在设置 --loop 时生效。

当设置 --loop 标志时，智能代理回退模式默认启用：

pdd [全局选项] fix --manual --loop [其他选项] PROMPT_FILE CODE_FILE UNIT_TEST_FILE

或者您也可以显式地启用它：

pdd [全局选项] fix --manual --loop --agentic-fallback [其他选项] PROMPT_FILE CODE_FILE UNIT_TEST_FILE

若要在使用 --loop 时禁用此功能，可添加 --no-agentic-fallback 来关闭它。

pdd [全局选项] fix --manual --loop --no-agentic-fallback [其他选项] PROMPT_FILE CODE_FILE UNIT_TEST_FILE

前提条件： 要使智能代理回退模式正常工作，您需要至少安装一个受支持的代理 CLI，并在环境中配置相应的 API 密钥。代理将按以下优先级顺序尝试：

Anthropic Claude：
- 需要安装并添加到 PATH 中的 claude CLI。
- 需要设置 ANTHROPIC_API_KEY 环境变量。
Google Gemini：
- 需要安装并添加到 PATH 中的 gemini CLI。
- 需要设置 GOOGLE_API_KEY 或 GEMINI_API_KEY 环境变量。
OpenAI Codex/GPT：
- 需要安装并添加到 PATH 中的 codex CLI。
- 需要设置 OPENAI_API_KEY 环境变量。

您可以使用 pdd setup 命令或直接在 shell 环境中设置这些密钥。

智能代理端到端修复模式

对于跨多个开发单元的端到端测试修复，可使用智能代理端到端修复模式，只需传递一个 GitHub 问题 URL（通常由 pdd bug 创建）。该模式会编排一个包含 11 个步骤的迭代工作流，以修复整个代码库中的单元测试和端到端测试，包括推送后的 CI 验证以及代码清理。

工作原理：

该工作流会分析 GitHub 问题以提取测试信息，然后迭代修复失败的测试：

运行单元测试：执行问题中的单元测试，并依次对每个失败的测试运行 pdd fix。
运行端到端测试：执行端到端测试以识别失败；若全部通过则停止。
根因分析：根据文档分析失败原因，判断问题是出在代码、测试还是两者兼而有之。
修复端到端测试：如果端到端测试本身存在问题，则修复它们并返回步骤 2。
确定开发单元：查明哪些开发单元涉及失败。
创建单元测试：对于代码缺陷，为受影响的开发单元创建或追加单元测试。
验证测试：运行新的单元测试，确认它们能够检测到缺陷，并在修复后通过。
运行 PDD Fix：依次对每个开发单元的失败单元测试运行 pdd fix。
全面验证：最终验证本地所有测试是否通过。
CI 验证：轮询外部 CI，获取失败日志，并运行 LLM 修复循环以解决 CI 特有的问题（代码风格检查、构建产物、编译错误等）。
代码清理：审查工作流中的所有更改，清理代码质量问题（调试语句、未使用的导入、重复代码等）；若测试再次失败，则回滚更改。

可恢复操作：

系统会自动保存状态，以便您可以在中断后继续工作。若想从头开始，请使用 --no-resume。

跨机器恢复：默认情况下，工作流状态会存储在 GitHub 问题的隐藏评论中，从而支持从任何机器继续执行。如果您在机器 A 上启动了工作流，只需在机器 B 上检出分支并再次运行 pdd fix，即可从中断处继续。使用 --no-github-state 可禁用此功能，改为仅使用本地状态持久化。您也可以设置环境变量 PDD_NO_GITHUB_STATE=1。

示例：



# 修复 GitHub 问题中的测试（代理模式）
pdd fix https://github.com/myorg/myrepo/issues/42

# 自定义超时时间和最大循环次数
pdd fix --timeout-adder 30 --max-cycles 10 https://github.com/myorg/myrepo/issues/42

# 配置 CI 重试和验证
pdd fix --ci-retries 5 https://github.com/myorg/myrepo/issues/42

# 完全跳过推送后的 CI 验证
pdd fix --skip-ci https://github.com/myorg/myrepo/issues/42

# 从头开始（忽略已保存的状态）
pdd fix --no-resume https://github.com/myorg/myrepo/issues/42

# 禁用 GitHub 状态持久化（仅本地）
pdd fix --no-github-state https://github.com/myorg/myrepo/issues/42

# 保护测试不被修改（仅修复代码，不修改测试）
pdd fix --protect-tests https://github.com/myorg/myrepo/issues/42

前提条件：

必须安装并认证 gh CLI
至少配置了一个支持的代理 CLI（Claude、Gemini 或 Codex），并设置了 API 密钥
对于 CI 验证，当前分支必须在 GitHub 上有一个打开的 PR

与 pdd bug 的关系：

此功能可与通过 pdd bug 处理的问题无缝协作。典型的工作流程如下：

使用 pdd bug <issue_url> 分析错误并生成失败的单元测试
使用 pdd fix <issue_url> 在所有受影响的开发单元中迭代修复这些失败的测试

7. split

将大型复杂提示文件拆分为更小、更易于管理的提示文件。

pdd [全局选项] split [选项] 输入提示 文件 输入代码 文件 示例代码 文件

参数：

INPUT_PROMPT：要拆分的大型提示文件的文件名。
INPUT_CODE：由输入提示生成的代码文件名。
EXAMPLE_CODE：作为子模块提示文件接口的示例代码文件名。

选项：

--output-sub LOCATION：指定生成的子提示文件的保存位置。默认文件名为 sub_<basename>.prompt。如果设置了环境变量 PDD_SPLIT_SUB_PROMPT_OUTPUT_PATH，则文件将保存到该路径，除非被此选项覆盖。
--output-modified LOCATION：指定修改后的提示文件的保存位置。默认文件名为 modified_<basename>.prompt。如果设置了环境变量 PDD_SPLIT_MODIFIED_PROMPT_OUTPUT_PATH，则文件将保存到该路径，除非被此选项覆盖。

示例：

pdd [全局选项] split --output-sub prompts/sub_data_processing.prompt --output-modified prompts/modified_main_pipeline.prompt data_processing_pipeline_python.prompt src/data_pipeline.py examples/pipeline_interface.py

8. 变更

使用一个包含12个步骤的代理式工作流来实现来自GitHub议题的变更请求。该工作流会调研该功能，确保需求清晰（如有需要则提出澄清问题），审查架构（如有需要则请求决策），分析文档变更，识别受影响的开发单元，设计提示词修改方案，实施这些修改，运行评审循环以识别并修复问题，并创建一个拉取请求。

代理模式（默认）：

pdd [全局选项] change GITHUB_ISSUE_URL

参数：

GITHUB_ISSUE_URL：描述变更请求的GitHub议题的URL。

12步工作流：

重复检查：搜索是否有重复的议题
文档检查：确认该功能是否已实现
调研：通过网络搜索澄清规范并找到最佳实践
澄清：确保需求清晰；若不清晰则提出带有选项的问题（工作流将暂停，直到得到回答）
文档变更：分析需要哪些文档更新
识别开发单元：找出受影响的提示词、代码、示例和测试
架构审查：识别架构决策；如有需要则提出带有选项的问题（工作流将暂停，直到得到回答）
分析变更：设计提示词修改方案
实施变更：在隔离的Git工作树中修改提示词
识别问题：审查变更是否存在问题（属于评审循环的一部分）
修复问题：修复已识别的问题（属于评审循环的一部分，最多迭代5次）
创建PR：创建一个链接到该议题的拉取请求

工作流恢复：第4步和第7步可能会暂停工作流，以提出澄清或架构相关的问题。当这种情况发生时，请在GitHub议题中回答这些问题，然后再次运行pdd change。工作流将从上次中断的地方继续执行，跳过已完成的步骤以节省Token。

跨机器恢复：默认情况下，工作流状态会存储在GitHub议题的一个隐藏评论中，从而允许从任何机器上恢复。如果您在机器A上启动了工作流，可以在机器B上检出分支并再次运行pdd change来继续。您可以使用--no-github-state选项来禁用此功能，而仅使用本地状态持久化。您也可以设置环境变量PDD_NO_GITHUB_STATE=1来全局禁用GitHub状态保存。

评审循环：第10至11步构成了一个评审循环，用于迭代地识别和修复问题。该循环将持续进行，直到不再发现任何问题为止（最多5次迭代）。

工作树分支行为：当运行pdd change或pdd bug时，会基于您当前的HEAD创建一个新的Git工作树：

从main/master分支：分支基于最新的main分支——创建独立的PR
从特性分支：分支继承该分支上的提交——适用于堆叠式或依赖性PR

如果您希望进行独立的更改，请从main分支运行该命令。当您从非main分支运行时，系统会显示警告。

代理模式示例：

pdd change https://github.com/myorg/myrepo/issues/239

工作流完成后，会自动创建一个链接到该议题的PR。该PR包含一个sync_order.sh脚本，用于按依赖顺序运行pdd sync命令。请审查该PR，并在合并后运行./sync_order.sh以重新生成代码。

手动模式（旧版）：

pdd [全局选项] change --manual [选项] CHANGE_PROMPT_FILE INPUT_CODE INPUT_PROMPT_FILE

参数：

CHANGE_PROMPT_FILE：包含如何修改输入提示词文件的说明的文件名。
INPUT_CODE：由输入提示词文件生成的代码文件名，或在使用--csv选项时，包含代码文件的目录。
INPUT_PROMPT_FILE：将被修改的提示词文件的文件名。标准模式下为必填项；使用--csv选项时则无需提供。

选项：

--budget FLOAT：设置变更过程允许的最大成本（默认为5.0美元）。
--output LOCATION：指定保存修改后提示词文件的位置。默认文件名为modified_<basename>.prompt。如果设置了环境变量PDD_CHANGE_OUTPUT_PATH，文件将保存在该路径下，除非在此处覆盖。
--csv：使用CSV文件来代替单个变更提示词文件。CSV文件应包含两列：prompt_name和change_instructions。使用此选项时，无需提供INPUT_PROMPT_FILE，而INPUT_CODE应为存放代码文件的目录。该命令期望CSV中的提示词名称遵循<basename>_<language>.prompt的命名规则。对于CSV中的每个prompt_name，它将在指定的INPUT_CODE目录中查找对应的代码文件（例如<basename>.<language_extension>）。输出文件将覆盖现有文件，除非指定了--output LOCATION。如果LOCATION是一个目录，则修改后的提示词文件将按照默认命名规则保存在该目录中；否则，如果指定了CSV文件名，则修改后的提示词将保存在该CSV文件中，并新增‘prompt_name’和‘modified_prompt’两列。

手动单个提示词变更示例：

pdd [全局选项] change --manual --output modified_factorial_calculator_python.prompt changes_factorial.prompt src/factorial_calculator.py factorial_calculator_python.prompt

手动批量变更使用CSV示例：

pdd [全局选项] change --manual --csv --output modified_prompts/ changes_batch.csv src/

9. 更新

根据代码变更更新提示。此命令主要有两种模式：

代理式提示优化（默认）

update 命令默认使用代理型 AI（Claude Code、Gemini 或 Codex）生成简洁、高质量的提示。该代理拥有完整的文件访问权限，并执行以下四步优化流程：

评估差异：读取提示内容（包括所有 <include> 文件），并与修改后的代码进行比较。
依据指南和测试筛选：参考 docs/prompting_guide.md 和现有测试，确定哪些内容应保留在提示中。
去除重复：移除与已包含文件内容重复的部分。
验证：确保提示对人类可读，并且能够可靠地重新生成代码。

这样生成的提示更加简洁，同时保持对开发人员清晰易懂，并且在代码生成方面具有可靠性。

前提条件：需要安装并配置以下 CLI 工具之一：

claude（Anthropic Claude Code）
gemini（Google Gemini CLI）
codex（OpenAI Codex CLI）

如果未找到可用的代理型 CLI，该命令将自动回退到传统的两阶段 LLM 更新流程。

测试感知更新：当某个模块存在测试文件时（例如 test_my_module.py、test_my_module_1.py），代理式更新会自动发现并考虑这些测试。通过测试验证的行为无需在提示中显式指定，从而生成更简洁的提示。

模式：

整个仓库模式（默认）：不带任何文件参数运行时，pdd update 会扫描整个仓库。它会查找所有代码/提示对，创建缺失的提示文件，并基于最新的 Git 更改更新所有提示。这是使整个项目保持同步的最简单方式。
单文件模式：当提供文件参数时，该命令将针对特定文件操作。此模式有三种不同的用法：

A) 提示生成/重新生成 要从头为代码文件生成全新的提示，或重新生成现有提示，只需提供该代码文件的路径即可。这将创建一个新的提示文件，或覆盖现有的提示文件。
```
pdd update <path/to/your_code_file.py>
```
B) 使用 Git 更新提示 通过将修改后的代码与上次提交版本进行对比来更新现有提示。此操作需要提示文件和修改后的代码文件。
```
pdd update --git <path/to/prompt.prompt> <path/to/modified_code.py>
```
C) 手动更新提示 通过手动提供原始代码、修改后的代码和提示来更新现有提示。适用于无法或不需要使用 Git 历史记录的场景。
```
pdd update <path/to/prompt.prompt> <path/to/modified_code.py> <path/to/original_code.py>
```

# 整个仓库模式（无参数）
pdd [全局选项] update

# 单文件模式：示例
# 为代码文件生成/重新生成提示
pdd [全局选项] update src/my_new_module.py

# 使用 Git 历史更新现有提示
pdd [全局选项] update --git factorial_calculator_python.prompt src/modified_factorial_calculator.py

# 手动提供原始代码更新现有提示
pdd [全局选项] update factorial_calculator_python.prompt src/modified_factorial_calculator.py src/original_factorial_calculator.py

# 按文件扩展名过滤的仓库级更新
pdd [全局选项] update --extensions py,js

参数：

MODIFIED_CODE_FILE：被修改的代码文件名，或需生成/重新生成提示的代码文件名。
INPUT_PROMPT_FILE：（可选）用于生成原始代码的提示文件名。在真正的更新场景（B 和 C）中为必填项。
INPUT_CODE_FILE：（可选）原始代码文件名。仅在手动更新（C）时为必填项；使用 --git 时（B）则无需提供；而在生成（A）时则不适用。

重要提示：默认情况下，此命令会覆盖原始提示文件，以维持 PDD 的核心原则——“提示即事实来源”。

选项：

--output LOCATION：指定保存更新后提示文件的位置。若未指定，则会覆盖原始提示文件，以保持其作为权威事实来源的地位。 如果设置了环境变量 PDD_UPDATE_OUTPUT_PATH，则仅在明确省略了 --output 参数且希望使用不同默认位置时才会生效。
--git：利用 Git 历史记录查找原始代码文件，从而无需提供 INPUT_CODE_FILE 参数。
--extensions EXTENSIONS：在仓库级模式下，仅对指定逗号分隔扩展名的文件进行更新（例如 py,js,ts）。
--simple：使用传统的两阶段 LLM 更新流程，而非默认的代理式模式。当无法使用代理型 CLI 或需要更快更新时非常有用。

示例（覆盖原始提示——默认行为）：

pdd [全局选项] update factorial_calculator_python.prompt src/modified_factorial_calculator.py src/original_factorial_calculator.py
# 这将原地覆盖 factorial_calculator_python.prompt

示例（代理式与简单模式对比）：

# 默认：代理式模式（使用 claude/gemini/codex 进行智能优化）
pdd update --git my_module_python.prompt src/my_module.py

# 传统：简单的两阶段 LLM 更新（速度更快，无需代理型 CLI）
pdd update --simple --git my_module_python.prompt src/my_module.py

10. detect

分析提示文件列表和变更描述，以确定哪些提示需要更改。

pdd [GLOBAL OPTIONS] detect [OPTIONS] PROMPT_FILES... CHANGE_FILE

参数：

PROMPT_FILES：可能需要更改的提示文件名列表。
CHANGE_FILE：其内容描述了需要分析并可能应用于提示的变更的文件名。

选项：

--output LOCATION：指定保存包含分析结果的 CSV 文件的位置。默认文件名为 <change_file_basename>_detect.csv。如果设置了环境变量 PDD_DETECT_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。
--stories：运行用户故事验证模式。设置后，不允许使用位置参数 PROMPT_FILES... CHANGE_FILE。
--stories-dir DIR：包含 story__*.md 文件的目录（仅限故事模式）。
--prompts-dir DIR：包含 .prompt 文件的目录（仅限故事模式）。
--include-llm：在故事模式中包含 *_llm.prompt 文件。
--fail-fast/--no-fail-fast：在故事模式中遇到第一个失败的故事时停止（默认为 --fail-fast）。
- 在故事模式下，PDD 会从每个故事中读取可选的 pdd-story-prompts 元数据，以进行提示子集（多提示）验证。
- 如果缺少元数据，则验证将使用所有提示，并且可以自动将检测到的提示链接缓存在故事文件中。

示例：

pdd [GLOBAL OPTIONS] detect --output detect_results.csv factorial_calculator_python.prompt data_processing_python.prompt web_scraper_python.prompt changes_description.prompt

11. conflicts

分析两个提示文件，找出它们之间的冲突，并提出解决这些冲突的建议。

pdd [GLOBAL OPTIONS] conflicts [OPTIONS] PROMPT1 PROMPT2

参数：

PROMPT1：我们要比较的一对提示中的第一个提示。
PROMPT2：我们要比较的一对提示中的第二个提示。

选项：

--output LOCATION：指定保存包含冲突分析结果的 CSV 文件的位置。默认文件名为 <prompt1_basename>_<prompt2_basename>_conflict.csv。如果设置了环境变量 PDD_CONFLICTS_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。

示例：

pdd [GLOBAL OPTIONS] conflicts --output conflicts_analysis.csv data_processing_module_python.prompt data_visualization_module_python.prompt

detect 和 conflicts 命令都会生成一个包含以下列的 CSV 文件：prompt_name 和 change_instructions。此 CSV 文件可用作 change --csv 命令的输入。

12. crash

修复导致程序崩溃的代码模块及其调用程序中的错误。

pdd [GLOBAL OPTIONS] crash [OPTIONS] PROMPT_FILE CODE_FILE PROGRAM_FILE ERROR_FILE

参数：

PROMPT_FILE：生成代码模块的提示文件名。
CODE_FILE：导致崩溃并将会被修改以正常运行的代码模块文件名。
PROGRAM_FILE：正在运行代码模块的程序文件名。如果有必要修复崩溃问题，该文件也会被修改。
ERROR_FILE：包含程序运行时错误信息的文件名。

选项：

--output LOCATION：指定保存修复后的代码文件的位置。默认文件名为 <basename>_fixed.<language_extension>。如果设置了环境变量 PDD_CRASH_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。
--output-program LOCATION：指定保存修复后的程序文件的位置。默认文件名为 <program_basename>_fixed.<language_extension>。
--loop：启用迭代修复过程。
- --max-attempts INT：设置放弃前的最大修复尝试次数（默认为 3 次）。
- --budget FLOAT：设置修复过程允许的最大成本（默认为 $5.0）。
--agentic-fallback / --no-agentic-fallback：启用或禁用代理回退模式（默认为启用）。

当使用 --loop 选项时，crash 命令将通过多次迭代尝试修复错误。它会在每次修复尝试后使用程序检查代码是否能正确运行。该过程将持续进行，直到错误被修复、达到最大尝试次数或预算耗尽为止。

如果迭代过程失败，将触发代理回退模式（除非使用 --no-agentic-fallback 禁用）。此模式会使用具备项目感知能力的 CLI 代理，在更广泛的上下文中尝试修复问题。为此，您需要至少安装一个受支持的代理 CLI（Claude、Gemini 或 Codex），并在您的环境中配置相应的 API 密钥。

示例：

pdd [GLOBAL OPTIONS] crash --output fixed_data_processor.py --output-program fixed_main_pipeline.py data_processing_module_python.prompt crashed_data_processor.py main_pipeline.py crash_errors.log

带有循环选项的示例：

pdd [GLOBAL OPTIONS] crash --loop --max-attempts 5 --budget 10.0 --output fixed_data_processor.py --output-program fixed_main_pipeline.py data_processing_module_python.prompt crashed_data_processor.py main_pipeline.py crash_errors.log

13. trace

找到提示文件与生成代码之间的对应行号。

pdd [GLOBAL OPTIONS] trace [OPTIONS] PROMPT_FILE CODE_FILE CODE_LINE

参数：

PROMPT_FILE：生成代码的提示文件名。
CODE_FILE：要分析的代码文件名。
CODE_LINE：调试器跟踪所在的代码文件中的行号。

选项：

--output LOCATION：指定保存跟踪分析结果的位置。默认文件名为 <basename>_trace_results.log。

示例：

pdd [GLOBAL OPTIONS] trace --output trace_results.log factorial_calculator_python.prompt src/factorial_calculator.py

这将打印出提示文件中与代码行对应的行号。

14. bug

从 GitHub 问题生成单元测试。该问题既是错误输出的权威来源，也是预期行为的依据。智能体工作流会分析该问题、复现 Bug，并创建一个失败的测试用例。

pdd [全局选项] bug <GitHub问题URL>
pdd [全局选项] bug --manual PROMPT_FILE CODE_FILE PROGRAM_FILE CURRENT_OUTPUT DESIRED_OUTPUT

工作原理（分步说明，附带 GitHub 评论）：

重复问题检查 - 搜索是否存在描述相同问题的现有问题。如果找到，则合并内容并关闭重复问题，同时发布包含检查结果的评论。
文档检查 - 审查仓库文档，以确定这是真正的 Bug 还是用户操作失误。发布包含检查结果的评论。
分类处理 - 评估是否已提供足够的信息以继续处理。如果问题中已包含详细的根因分析，包括文件路径、行号及因果解释，则直接进入根因分析步骤（跳过 API 研究和复现）。若信息不足，则发布请求补充信息的评论。
复现问题 - 尝试在本地复现该问题。发布确认复现成功（或无法复现）的评论。当步骤 3 直接进入根因分析时，此步骤将被跳过。
根因分析 - 通过实验确定根本原因。评估修复方案是局部性的还是跨模块的。进行变量引用审计，以查找并行代码路径中的类似 Bug；同时执行状态对称性检查，以发现保存与恢复之间的不对称问题。发布解释根因的评论。

5.5. 提示分类 - 判断 Bug 是出在代码实现中，还是出在提示规范本身。如果提示存在缺陷，则自动修复提示文件。发布包含分类结果及任何提示更改的评论。若不确定，则默认为“代码 Bug”。

测试计划 - 设计用于检测该问题的测试方案。枚举所有受影响的输出通道以及所有不同的代码路径（首次运行、恢复、重试、错误恢复），以确保全面覆盖。优先选择将测试追加到现有测试文件中，而非新建测试文件。发布包含测试计划的评论。
生成测试 - 创建失败的单元测试。发布包含生成的测试代码的评论。
验证检测效果 - 确认单元测试能够成功检测到该 Bug。根据 Bug 的影响范围，判断是否需要端到端测试（E2E_NEEDED: yes|no）。发布确认验证成功的评论。
端到端测试 - 生成并运行端到端测试，以在集成级别验证该 Bug。当步骤 8 输出 E2E_NEEDED: no 时，此步骤将被确定性地跳过，从而避免对纯内部 Bug 进行不必要的 LLM 调用。发布包含 E2E 测试结果或跳过原因的评论。
创建草稿 PR - 使用失败的测试创建拉取请求草稿，并将其链接到该问题。发布包含 PR 链接的评论。

参数：

ISSUE_URL：GitHub 问题 URL（例如 https://github.com/owner/repo/issues/123）

选项：

--manual：使用旧版模式，需显式指定文件参数（PROMPT_FILE、CODE_FILE、PROGRAM_FILE、CURRENT_OUTPUT、DESIRED_OUTPUT）
--output LOCATION：指定生成的单元测试保存位置。默认为 test_<module>_bug.py
--language LANG：指定单元测试的编程语言（默认为“Python”）。
--timeout-adder FLOAT：为每一步骤的超时时间增加额外秒数（默认为 0.0）
--no-github-state：禁用基于 GitHub 问题评论的状态持久化，仅使用本地存储

跨机器续跑：默认情况下，工作流状态会存储在 GitHub 问题的隐藏评论中，从而支持从任意设备继续运行。使用 --no-github-state 可禁用此功能。您也可以设置环境变量 PDD_NO_GITHUB_STATE=1。

示例：

# 智能体模式（推荐）
pdd bug https://github.com/myorg/myrepo/issues/42

# 手动模式（旧版）
pdd bug --manual prompt.prompt code.py main.py current.txt desired.txt

下一步——修复 Bug：

在 pdd bug 创建失败测试和拉取请求草稿后，可使用 pdd fix 并传入相同的 issue URL，以在所有受影响的开发单元中自动修复失败的测试：

pdd fix https://github.com/myorg/myrepo/issues/42

提示：如果 pdd bug 正确识别了 Bug 并创建了有效的失败测试，则可使用 --protect-tests 参数，防止 pdd fix 修改这些测试。这样可以确保 LLM 只修复代码，使测试通过：

pdd fix --protect-tests https://github.com/myorg/myrepo/issues/42

有关智能体端到端修复工作流的详细信息，请参阅 fix 命令文档。

15. auto-deps

分析提示文件并搜索潜在的依赖项——包括代码示例和文档文件（模式文档、API 文档、PRD 部分）——以确定这些依赖项并将它们插入到提示中。Auto-deps 会自动确定每个依赖项中需要的部分，并在新的和现有的 <include> 标签上发出相应的选择器。它还会自动移除与被包含文档内容重复的冗余内联内容。

pdd [全局选项] auto-deps [选项] 提示文件 目录路径

参数：

PROMPT_FILE：需要分析和插入依赖项的提示文件名。
DIRECTORY_PATH：用于搜索依赖项/示例文件的目录路径或 glob 模式。支持通配符，如 *.py 和 **/*.py。您可以传递一个普通目录（例如 examples/）或一个 glob（例如 examples/**/*.py）。如果您传递一个普通目录（不含通配符），则默认会递归扫描该目录（相当于 examples/**/*）。

选项：

--output LOCATION：指定保存插入了依赖项的修改后提示文件的位置。默认文件名为 <basename>_with_deps.prompt。如果设置了环境变量 PDD_AUTO_DEPS_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。
--csv FILENAME：指定包含或即将包含依赖信息的 CSV 文件。默认为 “project_dependencies.csv”。如果设置了环境变量 PDD_AUTO_DEPS_CSV_PATH，则会使用该路径，除非被此选项覆盖。
--force-scan：强制重新扫描所有潜在的依赖文件，即使它们已存在于 CSV 文件中。
--include-docs：在依赖发现中包含文档文件（.md、.txt、.rst）。默认：禁用。
--no-dedup：跳过冗余内联内容的移除步骤。
--concurrency N：依赖分析的最大并行 LLM 调用数（默认：1）。

当候选文件超过 50 个时，该命令会使用两阶段检索管道：

嵌入搜索：对提示和候选文件进行嵌入处理，根据余弦相似度检索前 50 个候选文件。
LLM 重排序：使用 LLM 作为评判者，从候选文件中选出最相关的依赖项。

在插入 <include> 指令后，该命令会执行一次 去重步骤，识别并移除提示中语义上与被包含文档内容重复的内联内容。

该命令维护一个 CSV 文件，包含以下列：

full_path：依赖文件的完整路径。
file_summary：对该文件内容和用途的一句话摘要。
key_exports：该文件中的关键导出内容（函数、类、常量）列表。
dependencies：该文件所依赖的模块/包列表。
date：该文件上次被分析的时间戳。

注意：使用旧版 3 列格式（不含 key_exports 和 dependencies）的现有 CSV 文件将在下次运行时自动重新摘要。

示例：

# 搜索代码示例和文档文件
pdd auto-deps --include-docs my_module_python.prompt "context/"

# 仅搜索 Python 示例（跳过文档发现）
pdd auto-deps my_module_python.prompt "context/*_example.py"

# 强制重新扫描并自定义并发数
pdd auto-deps --force-scan --concurrency 30 my_module_python.prompt "context/"

# 跳过冗余内容移除
pdd auto-deps --no-dedup my_module_python.prompt "docs/"

16. verify

通过执行指定程序（通常是 example 命令的输出）并使用 LLM 来判断程序的输出是否符合原始提示的意图，从而验证生成代码的功能正确性。无需单独的预期输出文件；LLM 会自行判断行为是否符合提示要求。如果验证失败，它会根据判断出的差异迭代尝试修复代码，类似于 fix 和 crash 命令如何分别处理各自的错误信号。

pdd [全局选项] verify [选项] 提示文件 代码文件 程序文件

参数：

PROMPT_FILE：生成待验证代码的提示文件名。
CODE_FILE：待验证并可能修复的代码文件名。
PROGRAM_FILE：用于验证的可执行程序文件名（例如由 pdd example 生成的示例脚本）。该程序运行后的输出将由 LLM 进行评判。

选项：

--output-results LOCATION：指定保存验证和修复结果日志的位置。该日志通常包含最终状态（通过/未通过）、尝试次数、总成本，以及可能的 LLM 推理过程或识别出的问题。默认：<basename>_verify_results.log。如果设置了环境变量 PDD_VERIFY_RESULTS_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。
--output-code LOCATION：指定在验证尝试结束后保存最终代码文件的位置（即使验证并未完全成功）。默认：<basename>_verified.<language_extension>。如果设置了环境变量 PDD_VERIFY_CODE_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。
--output-program LOCATION：指定在验证尝试结束后保存最终程序文件的位置（即使验证并未完全成功）。默认文件名为 <program_basename>_verified.<language_extension>。如果设置了环境变量 PDD_VERIFY_PROGRAM_OUTPUT_PATH，则文件将保存在该路径下，除非被此选项覆盖。
--max-attempts INT：设置验证循环中允许的最大修复尝试次数（默认为 3 次）。
--budget FLOAT：设置整个验证和迭代修复过程允许的最大成本（默认为 $5.0）。
--agentic-fallback / --no-agentic-fallback：启用或禁用代理回退模式（默认：启用）。

如果首次运行 PROGRAM_FILE 产生的输出被 LLM 根据 PROMPT_FILE 判断为不正确，该命令将进入迭代模式。每次对 CODE_FILE 进行修复后，都会重新运行 PROGRAM_FILE 并再次评估其输出。这一过程将持续进行，直到输出被判定为正确、达到 --max-attempts 的限制，或耗尽 --budget。在循环过程中可能会生成中间代码文件，类似于 fix 命令的行为。

输出：

最终代码文件保存在 --output-code 指定的位置（只要指定了该位置就会始终写入，即使验证未能完全成功也能进行检查）。
最终程序文件保存在 --output-program 指定的位置（只要指定了该位置就会始终写入，即使验证未能完全成功也能进行检查）。
结果日志文件保存在 --output-results 指定的位置，详细记录了整个过程及结果。
可能会在修复循环中生成中间代码文件（按时间戳命名）。

示例：

# 验证 calc.py，方法是运行 examples/run_calc.py，并根据 prompts/calc_py.prompt 判断其输出

# 如果验证失败，使用2.50美元的预算最多尝试修复5次。
pdd verify --max-attempts 5 --budget 2.5 --output-code src/calc_verified.py --output-results results/calc_verify.log prompts/calc_py.prompt src/calc.py examples/run_calc.py

适用场景：在 generate 和 example 之后使用 verify 进行初始的功能验证，并根据 LLM 对程序输出与提示之间一致性的判断 自动修复代码。这有助于确保代码在进入更细粒度的单元测试（test）、修复特定运行时错误（crash）或单元测试失败（fix）之前，能够为关键场景生成符合提示意图的结果。

17. checkup

针对 GitHub 问题对项目进行自动化健康检查。checkup 工作流会探索项目、识别问题（缺失依赖、构建错误、接口不匹配、测试失败、孤立页面、API 模式不一致），并可选择性地修复这些问题，编写回归测试和端到端测试，最后创建一个 Pull Request。

pdd [全局选项] checkup [选项] GITHUB_ISSUE_URL

参数：

GITHUB_ISSUE_URL：描述要检查内容的 GitHub 问题 URL（例如：“检查整个 CRM 应用”）

选项：

--no-fix：仅报告模式 — 发现并报告问题，但不应用修复
--timeout-adder FLOAT：为每个步骤的超时时间增加额外秒数（默认：0.0）
--no-github-state：禁用 GitHub 状态持久化，仅使用本地状态

工作流程（8 步骤，包含迭代修复-验证循环）：

发现 — 扫描项目结构、技术栈和模块清单
依赖审计 — 检查所有导入是否解析成功，无缺失包，无循环依赖
构建检查 — 运行构建/编译命令，检查语法/类型错误
接口检查 — 验证跨模块接口、前端导航可达性以及 API 调用一致性
测试执行 — 运行完整测试套件，识别失败项
修复问题（3 个子步骤）：
- 6a. 修复发现的问题（缺失依赖、导入、接口、构建错误、孤立页面、API 模式）
- 6b. 为每次修复编写回归测试
- 6c. 为跨模块交互编写端到端/集成测试
验证 — 重新运行构建和测试以确认所有修复有效
创建 PR — 创建包含所有修复和测试的 Pull Request

迭代修复-验证循环：步骤 3–7 会循环执行（最多 3 次）。如果步骤 7 发现仍有未解决的问题，工作流将回到步骤 3 再次执行。当步骤 7 报告“所有问题已修复”或达到最大迭代次数时，循环结束。

Git 工作树隔离：所有修复步骤都在一个隔离的 Git 工作树中执行（checkup/issue-{N} 分支），从而保持用户的工作目录整洁。

跨机器恢复：工作流状态存储在一个隐藏的 GitHub 评论中，允许从任何机器恢复。使用 --no-github-state 可以禁用此功能。

仅报告模式：使用 --no-fix 可以只运行步骤 1–5 和 7，而不进行修复——这对于在不做出更改的情况下审计项目的健康状况非常有用。

每一步都会将其发现结果作为评论发布到 GitHub 问题中，提供详细的审计记录。

示例：

# 完整检查并修复
pdd checkup https://github.com/myorg/myrepo/issues/42

# 仅报告模式（不应用修复）
pdd checkup --no-fix https://github.com/myorg/myrepo/issues/42

# 为大型项目增加超时时间
pdd checkup --timeout-adder 120 https://github.com/myorg/myrepo/issues/42

18. connect

【推荐入口】 在 localhost:9876 启动 PDD 的基于 Web 的界面。

Web 界面提供：

命令执行：运行任何 PDD 命令（pdd change、pdd bug、pdd fix、pdd sync 等），并提供可视化反馈
文件浏览器：查看和编辑项目中的提示、代码和测试
远程访问：通过 PDD Cloud，可在任何浏览器中访问您的会话
会话管理：运行多个具有自定义名称的会话

pdd [全局选项] connect [选项]

选项：

--port INT：监听的端口（默认：9876）
--host TEXT：绑定的主机（默认：127.0.0.1）
--allow-remote：允许非 localhost 连接。启用后，服务器将绑定到 0.0.0.0，以接受外部连接
--token TEXT：用于身份验证的 Bearer 令牌。建议在使用 --allow-remote 时使用
--no-browser：启动服务器时不自动打开浏览器
--frontend-url TEXT：自定义前端 URL，代替默认 URL
--local-only：跳过云注册，仅在本地模式下运行。会话将无法通过 PDD Cloud 远程访问
--session-name TEXT：自定义会话名称，便于识别。在运行多个会话时很有用

该命令会启动一个 FastAPI 服务器，并自动在您的默认浏览器中打开 Web 界面。服务器还提供：

用于以编程方式访问 PDD 命令的 REST API
API 文档，地址为 http://localhost:9876/docs

远程会话注册： 默认情况下，pdd connect 会向 PDD Cloud 注册，使您能够从任何浏览器远程访问您的会话。会话将在正常关闭（Ctrl+C）时自动注销。

安全注意事项：

默认情况下，服务器仅接受来自 localhost（127.0.0.1）的连接。
使用 --allow-remote 而不使用 --token 会显示安全警告，并需要确认。
对于远程访问，始终使用 --token 选项以要求身份验证。

示例：

# 使用默认设置启动服务器（自动打开浏览器）
pdd connect

# 在自定义端口上启动，不打开浏览器
pdd connect --port 8080 --no-browser

# 允许带身份验证的远程连接
pdd connect --allow-remote --token "your-secret-token"

# 仅在本地模式下运行（不注册云）
pdd connect --local-only

# 使用自定义会话名称以便识别
pdd connect --session-name "my-dev-server"

适用场景：当您更喜欢使用图形界面来操作 PDD、向他人演示 PDD，或者将 PDD 与可通过 REST API 通信的其他工具集成时，可以使用 connect。

19. auth

管理与 PDD Cloud 的身份验证。auth 命令提供用于登录、登出、检查状态和获取身份验证令牌的子命令。

pdd [全局选项] auth 子命令 [选项]

子命令

auth login

pdd auth login

auth status

显示当前活动账户和身份验证状态。如果已认证，退出码为 0；否则为 1。

pdd auth status [选项]

选项：

--verify：通过实际尝试刷新令牌来验证身份。如果不使用此标志，则仅检查缓存的凭据。

示例：

# 快速检查（使用缓存凭据）
pdd auth status

# 深度验证（尝试刷新令牌）
pdd auth status --verify

注意：如果仅存在刷新令牌而没有缓存的 JWT，状态将显示警告，提示令牌已过期，并在下次使用时刷新。使用 --verify 可以实际测试刷新是否成功，或者运行 pdd auth login 来立即刷新令牌。

auth logout

移除本地存储的 PDD Cloud 账户认证配置。

pdd auth logout

auth token

输出当前账户的认证令牌。对于脚本或程序化访问 PDD Cloud 非常有用。

pdd auth token [OPTIONS]

选项：

--format [raw|json]：令牌的输出格式。使用 raw 只输出令牌字符串（默认），或使用 json 输出包含令牌和过期时间的结构化信息。

何时使用：使用 auth 命令来管理你的 PDD Cloud 认证状态。在使用云功能之前使用 auth login 进行认证，使用 auth status 验证当前会话，并在需要将凭据传递给脚本或其他工具时使用 auth token。

20. `pdd sessions` - 管理远程会话

sessions 命令组允许你管理注册到 PDD Cloud 的远程会话。远程会话使你可以通过 Web 前端控制运行在其他机器上的 PDD 实例。

列出会话

pdd sessions list
pdd sessions list --json

列出与你已认证账户关联的所有活动远程会话。使用 --json 可获得机器可读的输出。

会话信息

pdd sessions info <session_id>

显示特定会话的详细信息，包括项目名称、云 URL、状态和最后的心跳时间。

清理会话

pdd sessions cleanup --stale
pdd sessions cleanup --all
pdd sessions cleanup --all --force

选项：

--stale：仅移除过期会话（无最近心跳）
--all：移除当前用户的所有会话
--force：跳过确认提示

注意：会话会在运行 pdd connect 时自动注册（除非指定 --local-only），并在正常关闭时注销。如果 pdd connect 实例被非正常终止，可以使用 pdd sessions cleanup 手动移除孤立会话。

何时使用：使用 sessions list 发现可用的远程会话，使用 sessions info 查看会话详情，以及使用 sessions cleanup 移除过期或孤立会话。

21. extracts

提示中的 <include query="...">file</include> 标签会触发由 LLM 驱动的语义提取，并自动缓存在 .pdd/extracts/ 中。结果会 自动刷新：如果源文件发生变化，PDD 会在下次处理 <include ... query> 标签时自动重新提取并更新缓存。

# 移除未被任何提示引用的孤立缓存条目
pdd extracts prune

22. Firecrawl 网页抓取缓存

通过提示中的 <web> 标签抓取的网页内容会进行 自动缓存。默认情况下，缓存结果会保留 24 小时，从而减少 API 信用的使用。

工作原理：

透明且自动，无需手动管理
缓存内容存储在 PROJECT_ROOT/.pdd/cache/firecrawl.db
访问时会自动跳过已过期的条目
URL 规范化（移除跟踪参数，不区分大小写匹配）
记录访问情况，以便在缓存满时采用 LRU 策略淘汰

配置（可选）：

export FIRECRAWL_CACHE_ENABLE=false          # 禁用缓存（默认：启用）
export FIRECRAWL_CACHE_TTL_HOURS=48          # 缓存有效期为 48 小时（默认：24 小时）
export FIRECRAWL_CACHE_MAX_SIZE_MB=200       # 最大缓存大小为 200 MB（默认：100 MB）
export FIRECRAWL_CACHE_MAX_ENTRIES=2000      # 最大缓存条目数为 2000（默认：1000）
export FIRECRAWL_CACHE_AUTO_CLEANUP=false    # 禁用自动清理（默认：启用）

缓存管理命令：

pdd firecrawl-cache stats              # 查看缓存统计信息
pdd firecrawl-cache clear              # 清除所有缓存条目
pdd firecrawl-cache info               # 查看缓存配置
pdd firecrawl-cache check <url>        # 检查某个 URL 是否已被缓存

何时使用：缓存是自动进行的。使用 stats 查看缓存状态，使用 info 查看配置，使用 check 验证某个 URL 是否已被缓存，或使用 clear 强制重新抓取所有 URL。

示例审查流程

当全局 --review-examples 选项与任何命令一起使用时，PDD 会展示可能用于当前操作的少量示例。审查流程如下：

PDD 显示潜在少量示例的输入（但不显示输出）。
对于每个示例，你可以选择：
- 接受该示例（它将被用于操作中）
- 排除该示例（它不会被用于本次或未来的操作中）
- 跳过该示例（它不会被用于本次操作，但未来可能会再次出现）
审查完所有示例后，PDD 将使用接受的示例继续执行命令。

此功能使你能够更好地控制 PDD 操作中使用的示例，从而可能提高生成输出的质量和相关性。

自动提交示例

当使用带有 --auto-submit 选项的 fix 命令时，如果修复循环中的所有单元测试都通过，PDD 会自动将示例提交到 PDD Cloud 平台。此功能有助于通过成功的修复不断改进平台的示例数据库。

输出位置指定

对于所有生成或修改文件的命令，--output 选项（或其变体，如 split 命令的 --output-sub 或 --output-modified）允许灵活指定输出位置：

仅文件名：如果你只提供文件名（例如 --output result.py），文件将在当前工作目录中创建。
完整路径：如果你提供完整路径（例如 --output /home/user/projects/result.py），文件将被创建在该确切位置。
目录：如果你提供目录名称（例如 --output ./generated/），系统将自动生成文件名，并将其保存在该目录中。
环境变量：如果未提供 --output 选项，且设置了与该命令相关的环境变量，PDD 将使用该变量指定的路径。否则，它将使用默认命名规则，并将文件保存在当前工作目录中。
无输出位置：如果未指定输出位置且未设置环境变量，文件将以命令赋予的默认名称保存在当前工作目录中。

获取帮助

PDD 提供了全面的帮助功能：

通用帮助：
```
pdd --help
```
显示可用的命令和选项列表。
特定命令的帮助：
```
pdd COMMAND --help
```
提供特定命令的详细帮助，包括可用选项和使用示例。

其他功能

Tab 补全：运行 pdd setup 会自动安装 Tab 补全功能。如果只需要刷新补全脚本，可以直接运行 pdd install_completion。
彩色输出：PDD 在兼容的终端中提供彩色输出，以提高可读性。

配置

PDD 支持多种配置方式，以便为不同的项目结构和上下文自定义其行为。

项目配置文件 (.pddrc)

推荐用于多上下文项目（例如包含后端和前端的 monorepo）

在项目根目录下创建 .pddrc 文件，以定义具有各自设置的不同上下文：

# .pddrc - 提交到版本控制系统
version: "1.0"
contexts:
  backend:
    paths: ["backend/**", "api/**", "server/**"]
    defaults:
      generate_output_path: "backend/src/"
      test_output_path: "backend/tests/"
      example_output_path: "backend/examples/"
      default_language: "python"
      target_coverage: 90.0
      strength: 0.8
  
  frontend:
    paths: ["frontend/**", "web/**", "ui/**"]
    defaults:
      generate_output_path: "frontend/src/"
      test_output_path: "frontend/__tests__/"
      example_output_path: "frontend/examples/"
      default_language: "typescript"
      target_coverage: 85.0
      strength: 0.7
  
  shared:
    paths: ["shared/**", "common/**", "lib/**"]
    defaults:
      generate_output_path: "shared/lib/"
      test_output_path: "shared/tests/"
      default_language: "python"
      target_coverage: 95.0
  
  # 匹配不到路径时的默认上下文
  default:
    defaults:
      generate_output_path: "src/"
      test_output_path: "tests/"
      default_language: "python"
      target_coverage: 90.0
      strength: 0.5

上下文检测： PDD 会根据以下规则自动检测合适的上下文：

当前目录路径：与各上下文中定义的 paths 模式进行匹配
手动覆盖：使用 --context CONTEXT_NAME 参数显式指定
回退机制：如果没有路径匹配，则使用 default 上下文

可用的上下文设置：

prompts_dir：提示文件所在的目录（默认值为 “prompts”）
generate_output_path：生成的代码文件保存路径
test_output_path：测试文件保存路径
example_output_path：示例文件保存路径
default_language：该上下文的默认编程语言
target_coverage：默认的测试覆盖率目标
strength：默认的 AI 模型强度（0.0–1.0）
temperature：默认的 AI 模型温度
budget：迭代命令的默认预算
max_attempts：修复操作的默认最大尝试次数

路径行为：

以 / 结尾的路径被视为明确的目录，且不会保留子目录的基名（例如，commands/analysis 将生成 pdd/analysis.py）。
不带尾部 / 的路径，在路径为现有目录时会保留子目录的基名（例如，commands/analysis 将生成 pdd/commands/analysis.py）。

使用示例：

# 根据当前目录自动检测上下文
cd backend && pdd --force sync calculator     # 使用 backend 上下文
cd frontend && pdd --force sync dashboard     # 使用 frontend 上下文

# 显式覆盖上下文
pdd --context backend sync calculator
pdd --context frontend sync dashboard

# 列出所有可用上下文
pdd --list-contexts

环境变量

PDD 使用多个环境变量来定制其行为：

核心环境变量

PDD_PATH：指向 PDD 的根目录。此变量在通过 pip 安装时会自动设置为 PDD 的安装目录。通常无需手动设置。
PDD_AUTO_UPDATE：控制 PDD 是否自动更新自身（默认值：true）。
PDD_CONFIG_PATH：覆盖默认的 .pddrc 文件位置（默认：从当前目录向上搜索）。
PDD_DEFAULT_CONTEXT：当未检测到上下文时使用的默认上下文（默认值：default）。
PDD_DEFAULT_LANGUAGE：在上下文中未指定时的全局默认编程语言（默认值：python）。

代理工作流变量

CLAUDE_MODEL：覆盖代理工作流中 Claude CLI 使用的模型（例如 claude-sonnet-4-5-20250929）。设置后，会将 --model 参数传递给 Claude CLI 命令。无默认值；仅在显式设置时使用。
PDD_USER_FEEDBACK：将来自 GitHub 问题评论的用户反馈注入到代理任务指令中。由 GitHub App 执行者设置，用于传递之前执行尝试的反馈。无默认值。
PDD_GH_TOKEN_FILE：包含最新 GitHub App 安装令牌的文件路径。设置后，端到端修复编排器会在推送认证失败时从此文件读取新令牌并重试一次。该令牌文件由云作业运行程序（pdd_cloud）写入和刷新。无默认值；仅在云托管的作业环境中使用。

输出路径变量

注意：使用 .pddrc 配置时，上下文特定的设置优先于这些全局环境变量。

PDD_PROMPTS_DIR：提示文件的默认存放目录（默认值：prompts）。
PDD_GENERATE_OUTPUT_PATH：generate 命令的默认输出路径。
PDD_EXAMPLE_OUTPUT_PATH：example 命令的默认输出路径。
PDD_TEST_OUTPUT_PATH：单元测试文件的默认输出路径。
PDD_TEST_COVERAGE_TARGET：默认的目标覆盖率百分比。
PDD_PREPROCESS_OUTPUT_PATH：preprocess 命令的默认输出路径。
PDD_FIX_TEST_OUTPUT_PATH：fix 命令中修复后的单元测试文件的默认输出路径。
PDD_FIX_CODE_OUTPUT_PATH：fix 命令中修复后的代码文件的默认输出路径。
PDD_FIX_RESULTS_OUTPUT_PATH：fix 命令生成的结果文件的默认输出路径。
PDD_SPLIT_SUB_PROMPT_OUTPUT_PATH：split 命令生成的子提示文件的默认输出路径。
PDD_SPLIT_MODIFIED_PROMPT_OUTPUT_PATH：split 命令生成的修改后提示文件的默认输出路径。
PDD_CHANGE_OUTPUT_PATH：change 命令生成的修改后提示文件的默认输出路径。
PDD_UPDATE_OUTPUT_PATH：update 命令生成的更新后提示文件的默认输出路径。
PDD_OUTPUT_COST_PATH：成本跟踪 CSV 文件的默认输出路径。
PDD_DETECT_OUTPUT_PATH：detect 命令生成的 CSV 文件的默认输出路径。
PDD_CONFLICTS_OUTPUT_PATH：conflicts 命令生成的 CSV 文件的默认输出路径。
PDD_CRASH_OUTPUT_PATH：crash 命令生成的修复后代码文件的默认输出路径。
PDD_CRASH_PROGRAM_OUTPUT_PATH：crash 命令生成的修复后程序文件的默认输出路径。
PDD_TRACE_OUTPUT_PATH：trace 命令生成的追踪分析结果的默认输出路径。
PDD_BUG_OUTPUT_PATH：bug 命令生成的单元测试文件的默认输出路径。
PDD_AUTO_DEPS_OUTPUT_PATH：auto-deps 命令生成的修改后提示文件的默认输出路径。
PDD_AUTO_DEPS_CSV_PATH：auto-deps 命令用于存储依赖信息的 CSV 文件的默认路径和文件名。如果设置，将覆盖默认的 project_dependencies.csv 文件名。
PDD_AUTO_DEPS_CONCURRENCY：auto-deps 依赖分析的默认最大并行 LLM 调用数（默认值：1）。
PDD_EMBEDDING_MODEL：auto-deps 中两阶段检索所使用的嵌入模型（默认值：text-embedding-3-small）。
PDD_VERIFY_RESULTS_OUTPUT_PATH：verify 命令生成的验证结果日志文件的默认输出路径。
PDD_VERIFY_CODE_OUTPUT_PATH：verify 命令生成的最终代码文件的默认输出路径。
PDD_VERIFY_PROGRAM_OUTPUT_PATH：verify 命令生成的最终程序文件的默认输出路径。
PDD_CLOUD_TIMEOUT：云请求超时时间，单位为秒。默认值为 900 秒（15 分钟）。如果长时间运行的云操作经常超时，请增加此值。

配置优先级

PDD 按以下顺序解析配置设置（优先级从高到低）：

命令行选项（例如 --output、--strength）
上下文特定设置（来自 .pddrc 文件）
全局环境变量（例如 PDD_GENERATE_OUTPUT_PATH）
内置默认值

从环境变量迁移

如果您目前使用环境变量，可以迁移到 .pddrc 配置：

# 之前：环境变量
export PDD_GENERATE_OUTPUT_PATH=backend/src/
export PDD_TEST_OUTPUT_PATH=backend/tests/
export PDD_DEFAULT_LANGUAGE=python

# 之后：.pddrc 文件
contexts:
  default:
    defaults:
      generate_output_path: "backend/src/"
      test_output_path: "backend/tests/" 
      default_language: "python"

对于团队项目，建议使用 .pddrc 方法，因为它能够确保所有团队成员的配置一致，并且可以进行版本控制。

模型配置（`llm_model.csv`）

PDD 使用一个 CSV 文件（llm_model.csv）来存储可用 AI 模型的相关信息，包括其成本、功能以及所需的 API 密钥名称。

在本地运行命令时，PDD 会根据以下优先级确定使用哪个配置文件：

用户专属： ~/.pdd/llm_model.csv - 如果该文件存在，则优先于任何项目级别的配置。这允许用户维护一套个人的、系统范围内的模型配置。
项目专属： <PROJECT_ROOT>/.pdd/llm_model.csv - 如果未找到用户专属文件，PDD 将在所确定的项目根目录下的 .pdd 目录中查找该文件（基于 PDD_PATH 或自动检测）。
软件包默认： 如果上述两种情况均不存在，PDD 将回退到随软件包安装提供的默认配置。

这种分层方式既支持共享的项目配置，也允许用户进行个性化覆盖，同时确保 PDD 在无需手动配置的情况下即可开箱即用。

注意： 您可以手动编辑此 CSV 文件，但建议通过再次运行 pdd setup 来添加提供商和更新模型。

注：这种基于文件的配置主要影响本地操作和工具。云端执行模式很可能依赖于集中管理的配置。

这些环境变量允许您为每个命令设置默认的输出位置。如果已设置了某个环境变量，但在命令中未使用相应的 --output 选项，则 PDD 将使用该环境变量指定的路径。这有助于简化工作流程，减少为常用命令指定输出路径的需求。

例如，如果您设置 PDD_GENERATE_OUTPUT_PATH=/path/to/generated/code/，那么所有由 generate 命令生成的文件都将默认保存到该目录中，除非在命令行中使用 --output 选项进行了覆盖。

要设置这些环境变量，您可以将其添加到您的 shell 配置文件中（如 .bashrc 或 .zshrc），或者在运行 PDD 命令之前直接设置：

export PDD_GENERATE_OUTPUT_PATH=/path/to/generated/code/
export PDD_TEST_OUTPUT_PATH=/path/to/tests/
# ... 根据需要设置其他变量

pdd generate factorial_calculator_python.prompt  # 输出将保存到 /path/to/generated/code/

此功能提供了更灵活和个性化的设置方式，尤其适用于团队环境或在具有不同目录结构的多个项目之间工作时。

错误处理

PDD 在命令执行过程中出现问题时会提供详细的错误信息。常见的错误场景包括：

输入文件无效或格式不正确
读取或写入文件权限不足
AI 模型相关错误（如 API 调用失败）
提示超出模型上下文窗口 — PDD 会在发送提示给 LLM 之前验证提示的 token 数量。如果提示超过模型的上下文限制，PDD 会报告 token 数量、模型限制、使用百分比以及导致溢出的具体提示内容。当配置了多个候选模型时，PDD 会自动切换到下一个模型。
生成代码中的语法错误

当发生错误时，PDD 会显示一条描述问题的消息，并在可能的情况下提供解决步骤。

云功能

在云模式下运行时（默认），PDD 提供额外的功能：

共享示例：访问不断增长的社区贡献示例数据库
自动更新：最新的改进和错误修复会自动生效
成本优化：智能选择模型并使用缓存以最大限度地降低费用
使用分析：通过 PDD Cloud 控制面板跟踪团队的使用情况和成本
协作：与团队成员共享提示和生成的代码

访问 PDD Cloud 控制面板：https://promptdriven.ai/

在这里您可以：

查看使用统计信息
管理团队访问权限
配置默认设置
访问共享示例
跟踪成本

故障排除

以下是一些常见问题及其解决方案：

命令未找到：请确保 PDD 已正确安装，并已添加到系统的 PATH 中。
权限拒绝错误：请检查您是否具有读取输入文件和写入输出位置所需的权限。
AI 模型无响应：请验证您的互联网连接，并检查 AI 服务的状态。
意外输出：尝试调整 --strength 和 --temperature 参数，以微调 AI 模型的行为。
费用过高：使用 --output-cost 选项跟踪使用情况，并为 fix 命令的 --budget 选项设置适当的预算。
依赖项扫描问题：如果 auto-deps 命令未能识别相关依赖项：
- 请检查文件路径和 glob 模式是否正确
- 使用 --force-scan 选项确保所有文件被重新分析
- 验证 CSV 文件的格式和内容
- 检查依赖项目录的文件权限
- 对于文档依赖项，请确保 .md/.txt/.rst 文件位于搜索路径中，并且已启用 --include-docs
- 如果冗余内容移除过于激进，可使用 --no-dedup 来跳过此步骤
命令超时：
- 请检查您的互联网连接
- 尝试使用 --local 标志运行以进行比较
- 对于长时间运行的操作，可通过 export PDD_CLOUD_TIMEOUT=1800（30 分钟）增加超时时间
- 如果问题持续存在，请查看 PDD Cloud 的状态页面
上下文窗口溢出：如果您看到“提示超出上下文限制”的错误：
- 错误消息中包含 token 数量和模型限制——请据此判断需要减少多少内容
- 缩小提示文件的大小，或将提示拆分为更小的模块
- 移除不必要的 <include> 指令，或使用有针对性的摘录代替完整文件
- 使用具有更大上下文窗口的模型（如拥有 100 万 token 的 Gemini，或自动使用 100 万 token 测试版头文件的 Claude）
- 使用 --verbose 选项查看确切的 token 数量和上下文使用百分比
- 如果使用 auto-deps，请审查包含的依赖项，去除不必要的冗余内容
同步相关问题：
- “另一个同步正在运行”：请检查 .pdd/locks/ 目录中是否存在过期锁文件，若相应进程已不存在，则将其删除
- 复杂的冲突解决难题：使用 pdd --verbose sync --dry-run basename 查看详细的 LLM 推理过程和决策分析
- 状态损坏或意外行为：删除 .pdd/meta/{basename}_{language}.json 文件以重置指纹状态
- 动画显示问题：同步操作在后台运行；动画仅为视觉反馈，并不影响功能
- 指纹不匹配：使用 pdd sync --dry-run basename 查看检测到的更改内容以及为何推荐执行这些操作

如果您遇到持续性问题，请查阅 PDD 文档或在 GitHub 上提交问题寻求帮助。

安全注意事项

使用 PDD 时，请注意以下安全事项：

代码执行：PDD 会生成并修改代码。在执行之前，务必审查生成的代码，尤其是在生产环境中。
数据隐私：避免在提示或代码文件中使用敏感数据，因为这些信息可能会被 AI 模型处理。
API 密钥：如果 PDD 需要 API 密钥来访问 AI 模型，请将这些密钥安全存储，切勿将其包含在版本控制系统中。
输入验证：PDD 假设输入文件是可信的。如果在多用户或网络环境中使用 PDD，请实施适当的输入验证。
输出处理：对待输出文件时，应与项目中的其他代码或配置文件一样，采取相同的安全措施。
依赖分析：使用 auto-deps 命令时，需谨慎处理不可信的依赖文件，并在将生成的摘要纳入提示之前进行验证。

在云模式下使用 PDD 时：

身份验证：
- PDD 使用 GitHub SSO 进行安全身份验证
- 令牌会安全地存储在您系统的凭据管理器中
- 无需手动管理 API 密钥
数据隐私：
- 所有数据在传输和存储过程中均被加密
- 提示和生成的代码仅与您的账户相关联
- 您可以随时通过仪表板删除您的数据
团队访问权限：
- 通过 GitHub 组织管理团队成员的访问权限
- 为不同命令设置细粒度的权限
- 跟踪每位团队成员的使用情况

此外：

在生产环境中，可考虑通过设置 PDD_AUTO_UPDATE=false 来禁用自动更新。
为生产系统实施受控的更新流程。
在敏感环境中手动更新 PDD 之前，请先查看变更日志。

工作流集成

PDD 可以集成到各种开发工作流中。以下是关键工作流模式的概念模型：

初始开发

概念流程：auto-deps → generate → example → crash → verify → test → fix

目的：从零开始创建新功能，并进行充分的测试和验证。

流程：

识别并注入提示所需的依赖项（auto-deps）。
根据提示生成完整的实现代码（generate）。
创建可重用的接口示例（example）。
确保代码能够正常运行，并修复运行时错误（crash）。
运行示例，并使用 LLM 检查输出是否符合提示意图；如有必要，尝试迭代修复（verify）。
为实现部分生成全面的单元测试（test）。
修复单元测试中发现的问题（fix）。

关键洞察：此工作流遵循从概念到验证实现的流程，在检查功能输出（verify）和详细单元测试（test）之前，先确保代码能够正常运行（crash）。

代码到提示的更新

概念流程：update → detect → change

目的：在代码更改后，保持提示作为事实来源。

流程：

将直接的代码更改同步回原始提示。
检测可能受这些更改影响的其他提示。
对依赖于这些提示的内容进行必要的调整。

关键洞察：这种双向流程确保即使代码先发生变化，提示仍然能保持其作为事实来源的地位。

重构

概念流程：split → auto-deps → example

目的：将大型提示分解为模块化组件。

流程：

将大型提示中的特定功能提取出来，形成独立的提示。
确保新提示具备所有必要的依赖项。
为提取的功能创建接口示例。

关键洞察：正如代码应模块化一样，提示也受益于分解为专注且可重用的组件。

调试工作流

提示上下文问题

概念流程：preprocess → generate

目的：解决提示解释或预处理方面的问题。

流程：

检查提示的预处理方式。
重新生成代码，以提高提示的清晰度。

运行时崩溃调试

概念流程：generate → example → crash

目的：修复无法执行的代码。

流程：

根据提示生成初始代码。
创建示例和测试程序。
修复运行时错误，使代码可执行。

逻辑错误修复

概念流程：bug → fix

目的：修正虽然能运行但结果不正确的代码。

流程：

生成能够展示该 bug 的测试用例。
修复代码，使其通过测试。

调试器引导的分析

概念流程：trace → [edit prompt]

目的：确定哪些提示部分生成了有问题的代码。

流程：

找出代码行与提示部分之间的对应关系。
更新相关的提示部分。

多提示架构

概念流程：conflicts/detect → change → generate → example → test

目的：协调由更高层需求衍生出的多个提示。

流程：

识别提示之间的冲突或依赖关系。
协调这些提示，使它们协同工作。
根据更新后的提示重新生成代码。
在更改后更新接口示例。
通过测试验证系统集成。

关键洞察：复杂系统需要提示之间的协调，正如代码模块之间需要协调一样。

功能增强

概念流程：change → generate → example → test → fix

目的：为现有功能添加新能力。

流程：

修改提示以描述新功能。
重新生成具有增强功能的代码。
更新示例以展示新功能。
测试以验证正确实现。
修复可能出现的问题。

关键洞察：功能的添加应基于提示的变化，而不是直接修改代码。

CI 漂移检测与自动修复

概念流程：detect drift → heal (update/sync) → commit → push

目的：在 CI 流水线中自动检测并修复提示/示例的漂移。

流程：

使用 sync_determine_operation 扫描模块是否存在漂移（无需调用 LLM）。
对于过时的提示，运行 pdd update 将代码更改同步回提示。
对于过时的示例，运行 pdd sync 并执行示例和验证操作。
将修复后的文件暂存并提交，附上描述性信息。
将更改推送到当前分支。

使用方法：

# 扫描所有模块（主分支触发）
python -m pdd.ci_drift_heal

# 扫描特定模块（PR 触发）
python -m pdd.ci_drift_heal --modules module_a module_b

# 使用预算上限和跳过 CI 标志
python -m pdd.ci_drift_heal --budget-cap 5.00 --skip-ci

关键选项：

--modules：将检测范围限制在特定模块（用于 PR 范围内的检查）
--budget-cap FLOAT：LLM 修复调用的最大金额
--skip-ci：在提交信息中添加 [skip ci]，以防止 CI 重新触发

核心见解：此工作流自动化了 CI 中的“代码到提示”更新模式，确保提示与代码变更保持同步，无需人工干预。

关键依赖

使用这些工作流时，请记住以下关键工具依赖：

必须先执行 generate，再执行 example 或 test
crash 用于修复运行时错误，使代码可运行
fix 需要由 crash 创建或验证的可运行代码
必须先创建 test，再使用 fix
提示界面发生重大变化后，务必更新 example
ci_drift_heal 要求模块必须已有提示文件和代码文件

有关每个工作流的详细命令示例，请参阅相应的命令文档部分。

CI 自动修复

工作流文件：.github/workflows/auto-heal-drift.yml

目的：在 CI 中自动检测并修复提示与代码之间的偏差。

触发条件：

拉取请求：仅修复 PR 所更改的模块，并将修复提交到 PR 分支
推送到 main 分支：修复所有模块，并将修复直接提交到 main 分支

防止循环：自动修复生成的提交会使用 chore: auto-heal [skip ci] 提交信息；该工作流会跳过由此类模式触发的运行。

配置：设置 PDD_BUDGET_CAP 仓库变量以控制每次运行的 LLM 开销（默认值为 5.00）。

有关完整详情，请参阅 docs/ci-auto-heal.md。

集成

PDD 提供多种集成方式，以简化其在开发环境中的使用：

VS Code 扩展

专用的 VS Code 扩展 (utils/vscode_prompt) 提供语法高亮、代码片段等功能，方便用户直接在编辑器中处理 .prompt 文件。该扩展兼容所有支持 OpenVSX 的 IDE，包括 VS Code、Cursor、VSCodium、Gitpod、Kiro、Windsurf 等。有关安装和使用方法，请参阅该扩展的 README。

MCP 服务器（适用于代理客户端）

pdd-mcp-server (utils/mcp) 基于模型上下文协议 (MCP) 构建，充当桥梁。这使得 Cursor、Claude Desktop、Continue.dev 等代理客户端能够以编程方式调用 pdd-cli 命令。有关配置和使用说明，请参阅 MCP 服务器 README。

CI 偏差检测

PDD 包含一个适用于 CI 的偏差检测与自动修复脚本 (pdd/ci_drift_heal.py)，可集成到 GitHub Actions 或其他 CI 系统中。该脚本会扫描提示与示例之间的偏差，使用 pdd update 和 pdd sync 进行修复，并提交结果。有关使用详情，请参阅【CI 偏差检测与自动修复】部分。

实用工具

更新 LLM 模型数据 (`pdd/update_model_costs.py`)

此脚本会自动更新 llm_model.csv 文件。它会优先更新用户特定的配置文件 ~/.pdd/llm_model.csv（如果存在）。 否则，它将使用 --csv-path 参数指定的文件路径（默认为 <PROJECT_ROOT>/.pdd/llm_model.csv）。

该脚本使用 litellm 库完成以下操作：

获取并填充所列模型的缺失输入输出成本（将每 token 成本转换为每百万 token 成本）。
将现有成本与 LiteLLM 数据进行比较，并报告不一致之处（但不覆盖）。
根据 litellm.supports_response_schema 检查并更新 structured_output 标志（True/False）。
在处理前使用 litellm 验证模型标识符。

使用方法：

conda activate pdd
# 脚本会首先自动检查 ~/.pdd/llm_model.csv。
# 如果未找到，则会使用 --csv-path 指定的路径（或默认的项目路径）。
python pdd/update_model_costs.py [--csv-path path/to/your/project/llm_model.csv]

注意：max_reasoning_tokens 列需要手动维护。

专利

关于 PDD 工作流和系统相关方面的专利申请正在审查中。本声明并不授予任何专利权利；具体权利以 LICENSE 文件为准。

结论

PDD（提示驱动开发）CLI 提供了一套全面的工具，用于管理提示文件、生成代码、创建示例、运行测试以及处理提示驱动开发的各个方面。通过利用 AI 模型的强大功能和迭代流程，PDD 旨在简化开发流程并提高代码质量。

各种命令和选项提供了灵活的使用方式，从简单的代码生成到涉及多个步骤的复杂工作流。通过环境变量跟踪成本和管理输出位置的功能，进一步增强了该工具在不同开发环境中的实用性。

PDD 采用统一的参数顺序，将提示文件置于首位，突出了其提示驱动的本质，并为用户提供更直观的界面。这种跨命令的一致性应使该工具更易于学习和有效使用。

随着对 PDD 的熟悉程度加深，您可以通过在 Shell 脚本、任务调度器或 CI 流水线中串联命令来构建更丰富的工作流，并充分利用可用的选项。请始终参考最新文档，并使用内置的帮助功能，以便在开发过程中最大化 PDD 的效用。

请务必注意安全问题，尤其是在处理生成的代码或敏感数据时。定期更新 PDD，以获取最新的功能和改进。

祝您使用 PDD 编码愉快！

PDD (Prompt-Driven Development) 快速上手指南

PDD 是一个基于提示词驱动开发（Prompt-Driven Development）的 AI 工具包，旨在通过自然语言提示词自动生成、测试和维护代码。它支持通过 Web 界面可视化操作，也提供强大的命令行代理功能来自动实现 GitHub Issue。

环境准备

在开始之前，请确保您的系统满足以下要求：

系统要求

操作系统: macOS, Linux 或 Windows
Python 版本: Python 3.8 或更高版本
网络: 需要访问 GitHub 和 LLM 提供商 API（或使用 PDD Cloud 模式）

前置依赖 (macOS 用户必读)

如果您使用的是 macOS，请先安装以下基础工具：

安装 Xcode Command Line Tools (用于 Python 编译):
```
xcode-select --install
```

安装 Homebrew (推荐的包管理器):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，将 Homebrew 添加到 PATH:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile && eval "$(/opt/homebrew/bin/brew shellenv)"

确认 Python 已安装:

python3 --version
# 如果未安装，使用 Homebrew 安装
brew install python

可选依赖 (针对 CLI 高级用法)

如果您计划直接使用命令行处理 GitHub Issue，还需安装：

GitHub CLI: brew install gh && gh auth login
至少一个 Agent CLI (任选其一):
- Claude Code: npm install -g @anthropic-ai/claude-code
- Gemini CLI: npm install -g @google/gemini-cli
- Codex CLI: npm install -g @openai/codex

安装步骤

推荐使用 uv 包管理器进行安装，它能提供更快的依赖解析和自动环境配置。

1. 安装 uv (如果尚未安装)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 安装 PDD CLI

uv tool install pdd-cli

3. 验证安装

pdd --version

4. 初始化配置

运行设置向导，它将自动检测代理工具、扫描 API Key 并配置模型：

pdd setup

注意：运行完成后，根据终端提示执行 source ~/.pdd/api-env.zsh (或 .bash) 以在当前会话中生效 API 密钥。

基本使用

PDD 提供两种主要使用方式：推荐的 Web 界面 和 命令行模式。

方式一：Web 界面 (推荐新手)

这是最简单的使用方式，提供可视化的项目管理、文件浏览和命令执行功能。

启动 Web 服务:
```
pdd connect
```
访问界面: 浏览器会自动打开 http://localhost:9876。
- 在此界面中，您可以可视化地运行 change, bug, fix, sync 等命令。
- 支持远程访问（通过 PDD Cloud），也可添加 --local-only 仅限本地访问。

方式二：命令行快速示例 (Hello World)

如果您想通过命令行体验核心功能，请跟随以下步骤：

获取示例项目:

git clone https://github.com/promptdriven/pdd.git
cd pdd/examples/hello

配置 API Key (选择其中一个设置):

export GEMINI_API_KEY="your-gemini-key"
# 或者
export OPENAI_API_KEY="your-openai-key"

运行生成命令: 该命令会根据提示词文件生成代码：
```
pdd --force generate hello_python.prompt
```
运行生成的代码:
```
python3 hello.py
```
✅ 预期输出: hello

方式三：自动化处理 GitHub Issue (进阶)

如果您已配置好 GitHub CLI 和 Agent CLI，可以直接通过 Issue 链接驱动开发：

# 自动实现功能需求
pdd change <issue-url>

# 为 Bug 创建失败测试
pdd bug <issue-url>

# 修复失败的测试
pdd fix <issue-url>

注：默认情况下，PDD 使用 Cloud 模式运行（通过 GitHub SSO 认证），无需本地配置复杂的 API Key 即可使用强大模型。如需完全本地运行，请使用 --local 标志并确保已导出相应的 *_API_KEY 环境变量。

相似工具推荐

stable-diffusion-webui

stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。

★ 162.1k|★★★☆☆|昨天

开发框架图像Agent

everything-claude-code

everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上

★ 140.4k|★★☆☆☆|今天

开发框架Agent语言模型

ComfyUI

ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。

★ 107.7k|★★☆☆☆|3天前

开发框架图像Agent

Deep-Live-Cam

Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。

★ 88.9k|★★★☆☆|今天

开发框架图像Agent

NextChat

NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。 NextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。

★ 87.6k|★★☆☆☆|昨天

开发框架语言模型

ML-For-Beginners

ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。

★ 85k|★★☆☆☆|昨天

图像数据工具视频

使用场景

没有 pdd 时

使用 pdd 后

运行环境要求

快速开始

PDD（提示驱动开发）命令行界面

简介

白皮书

安装

macOS 前置条件

推荐方法：uv

替代方案：pip 安装

高级安装选项

虚拟环境安装

开始使用

选项 1：Web 界面（推荐）

选项 2：基于问题的 CLI

选项 3：手动提示工作流

🚀 快速入门（Hello 示例）

安装后设置（安装后的第一步必做）

云端与本地执行

云端认证

本地模式要求

本地模型配置

常见安装问题排查

版本

支持的编程语言

提示文件命名规范

提示驱动开发理念

核心概念

思维模式

PDD 工作流程：概念理解

工作流程选择原则

PDD 设计模式

基本用法

命令概览

命令关系

开始使用

代理式命令（基于问题驱动）

核心命令（基于提示）

提示管理

实用命令

用户故事提示测试

全局选项

核心转储调试包

report-core 命令

上下文选择标志

自动更新控制

AI 模型信息

输出成本跟踪

使用方法

成本计算与展示

CSV 输出

环境变量

成本预算

命令

1. sync

2. generate

提示词模板

内置模板

3. 示例

4. 测试

代理模式（UI 测试生成）

手动模式（基于提示）

故事模式

提供命令特定的上下文

基本示例：

覆盖率分析策略

5. 预处理

类 XML 标签

三重反引号包含

花括号处理

6. 修复

手动模式参数

共享选项

代理式端到端修复选项

手动模式选项

智能代理回退模式

智能代理端到端修复模式

7. split

`report-core` 命令

20. `pdd sessions` - 管理远程会话

模型配置（`llm_model.csv`）

更新 LLM 模型数据 (`pdd/update_model_costs.py`)