项目定位与核心目标

PanWizard 是一个面向"向导式（wizard-style）"工作流的轻量级工具集，旨在把多步骤、易出错、需要反复试错的人工流程封装为可重复执行的自动化脚本。从 v3.13.1 的公开说明可以看出，该项目在首次公开发布前完成了一轮"公开卫生扫描（public-release hygiene sweep）"，包括全量 git 历史密钥扫描（gitleaks、200 commits 全部 clean）以及提交作者邮箱统一为 noreply 形式，这表明项目已经具备了长期可维护、可被外部团队安全使用的条件 资料来源：README.md:1-40。

项目的核心目标可以归纳为三点：

1. 降低重复性配置工作的门槛：通过单一入口（通常是 bin/install.js）让用户在不熟悉底层细节的前提下完成初始化。
2. 沉淀现场经验：社区语境中提到的"field-sourced learnings"意味着 PanWizard 把来自实际部署环境的经验回写到工作流注释和 CHANGELOG 中，使脚本不仅能"跑通"，还能解释"为什么这样跑"。
3. 保持可移植性：以中立代号（neutral codenames）替换内部代号，避免对外发布时泄漏组织信息 资料来源：README.md:1-60。

解决的具体问题

在没有 PanWizard 这类工具之前，团队通常会面临以下几类痛点：

• 步骤分散：同类初始化任务散落在 README、Wiki、Shell 脚本和 CI 配置里，新成员需要交叉阅读多个文档才能复现一次成功部署。
• 版本漂移：不同机器、不同时间执行步骤可能产生不同的中间状态，导致"在我机器上能跑"的问题。
• 经验流失：现场踩坑得到的修复方法往往只留在某个人的 Issue 评论或私聊记录里，难以沉淀到代码或文档中。

PanWizard 通过把上述内容收拢到一个统一的二进制入口与对应的文档矩阵（USER-GUIDE、ARCHITECTURE、COMPARISON、FAQ）来缓解这些问题 资料来源：docs/USER-GUIDE.md:1-80。

整体架构概览

PanWizard 在架构上遵循"薄 CLI + 厚文档 + 显式比较"的模式。bin/install.js 作为唯一的命令行入口，负责读取参数、解析目标环境并驱动后续步骤；其余能力则通过文档而非代码来传递。下图给出了高层视角的协作关系：

flowchart LR
    User[用户] -->|运行| CLI[bin/install.js]
    CLI --> Steps[步骤执行引擎]
    Steps -->|记录| Notes[现场经验与工作流注释]
    Notes -.回写.-> Docs[docs/*.md]
    Docs -->|参考| User
    Docs -->|横向对比| Compare[docs/COMPARISON.md]
    Compare -->|回答| FAQ[docs/FAQ.md]

CLI 层与文档层之间是单向依赖：CLI 产出经验，文档承载经验，文档再反过来引导用户正确调用 CLI 资料来源：docs/ARCHITECTURE.md:1-120。

关键特性与适用场景

从仓库目录结构和官方文档的覆盖范围来看，PanWizard 强调以下几点：

资料来源：bin/install.js:1-200、docs/COMPARISON.md:1-60、docs/FAQ.md:1-80。

典型适用场景包括：需要为多个环境（开发、测试、生产）复用同一套初始化流程的团队、希望把零散的内部脚本沉淀为正式工具的小型组织，以及需要在公开仓库中安全分享工作流而不泄漏内部代号或密钥的项目 资料来源：README.md:40-120。

与同类方案的差异定位

docs/COMPARISON.md 的存在说明 PanWizard 并不试图取代所有通用脚手架工具，而是定位于某些特定的痛点组合（例如把"现场经验回写"作为一等公民）。当用户评估是否引入该项目时，应当优先确认其团队是否也存在"步骤分散 + 经验流失"的双重问题；若仅仅是缺少一个安装器，那么通用方案可能更合适 资料来源：docs/COMPARISON.md:1-100。

小结

PanWizard 的本质是一个"向导化"框架：用一个受控的 CLI 入口串联多步骤流程，并配套结构化文档承载从现场回流的知识。它最适合的并不是"零配置"场景，而是那些已经存在大量经验、但缺少沉淀通道的工作流 资料来源：docs/USER-GUIDE.md:1-80、docs/FAQ.md:1-60。

系统概述

PanWizard 的"机器人军团"是一个由多个 AI 智能体协同工作的执行体系，承担从任务编排、计划制定到具体执行的完整工作流。该体系以 pan-conductor、pan-roadmapper、pan-executor 三类核心智能体为梯队骨干，配合 army、hud、dashboard 三套交互命令，形成可视化的 Mission Control 控制台，并通过"人类合并门控"确保关键节点的最终决策权掌握在人类手中。资料来源：commands/pan/army.md:1-15

整个军团的设计遵循"指挥—规划—执行—监控"的闭环模式：指挥层（Conductor）负责任务分派，规划层（Roadmapper）负责路线图拆解，执行层（Executor）负责落地实现，监控层（Dashboard/HUD）负责实时呈现状态。资料来源：agents/pan-conductor.md:1-20

Mission Control：指挥与监控界面

Mission Control 由三个命令文件构成，分别面向不同使用场景：

• /pan:army：军团总览命令，用于查看当前在线的智能体名单、能力矩阵与任务负载。资料来源：commands/pan/army.md:18-40
• /pan:hud：抬头显示（HUD），在终端顶部以紧凑形式展示关键指标，包括进行中的 PR、待合并队列、阻塞事件等。资料来源：commands/pan/hud.md:12-30
• /pan:dashboard：全屏仪表盘，提供更丰富的可视化维度，包括梯队吞吐、门控命中率、平均收敛时间等。资料来源：commands/pan/dashboard.md:22-50

三者共享统一的数据源——智能体事件流——但呈现密度不同：HUD 用于开发者在编码过程中的轻量感知，Dashboard 用于阶段性复盘，army 命令则用于成员调度与排障。

四级梯队体系

机器人军团采用四级梯队结构，每级承担不同的抽象粒度与决策半径：

梯队间的通信通过结构化事件传递：Conductor 下发"任务票据"，Roadmapper 拆出"路线图"，Executor 产出"变更提案"。资料来源：agents/pan-conductor.md:25-45 与 agents/pan-roadmapper.md:18-35

每一级都可以独立降级：当 Executor 失败次数超过阈值时，Roadmapper 会重新规划；Roadmapper 不收敛时，Conductor 会重新评估任务可行性。资料来源：agents/pan-executor.md:30-50

人类合并门控

人类合并门控（Human Merge Gating）是整个军团的最后一道安全闸门：所有 Executor 产出的"变更提案"不会直接进入主分支，必须经过人类的显式确认后才能合并。该机制在以下三种场景触发：

1. 提案评审门控：每个 PR 由人类审阅代码语义、设计意图与测试覆盖度。资料来源：commands/pan/army.md:55-70
2. 路线图变更门控：当 Roadmapper 在中途调整计划（如拆分、合并、废弃某个里程碑），需要人类介入决策。资料来源：agents/pan-roadmapper.md:60-78
3. 跨梯队冲突门控：当 Conductor 与下级在任务边界上产生分歧时，由人类仲裁。资料来源：agents/pan-conductor.md:80-95

门控的状态通过 HUD 中的"待合并队列"实时可见，Dashboard 则提供历史门控通过率与平均审阅时长等指标。资料来源：commands/pan/hud.md:45-60 与 commands/pan/dashboard.md:75-95

这种"机器干活、人类把关"的双层结构，是 PanWizard 在 v3.13.1 首次公开发布时所强调的核心安全姿态——所有自动化产出都可追溯、可拦截、可回滚。

概述

PanWizard 通过一组以 pan 为前缀的工作流命令，将一个项目的生命周期拆解为若干个连续的阶段。每个阶段对应一个独立的命令文件，从而实现「讨论 → 规划 → 执行 → 验证」的闭环。整个生命周期从一个新项目的初始化开始，最终通过逐阶段的验证保证项目交付质量。quick 命令则作为单次轻量任务的快捷入口，跳过完整阶段流程直接处理小范围需求。

资料来源：commands/pan/new-project.md:1-1 commands/pan/quick.md:1-1

项目生命周期阶段

整个生命周期按照以下顺序流转，每一步都以前一步的产物作为输入或上下文：

flowchart LR
    A[new-project<br/>项目初始化] --> B[discuss-phase<br/>阶段讨论]
    B --> C[plan-phase<br/>阶段规划]
    C --> D[exec-phase<br/>阶段执行]
    D --> E[verify-phase<br/>阶段验证]
    E --> C
    Q[quick<br/>快速任务] -.-> B
    Q -.-> D

1. 项目初始化

new-project 命令负责创建一个全新项目的骨架结构与基础配置。它是整个生命周期的起点，定义了项目的初始上下文、目录布局以及后续阶段所需的基础信息。在执行任何其他阶段命令之前，必须先完成项目初始化。

资料来源：commands/pan/new-project.md:1-1

2. 阶段讨论

discuss-phase 命令用于就当前阶段的需求、目标、边界与潜在风险进行结构化讨论。该命令通常基于 new-project 创建的项目上下文运行，并把讨论结论沉淀为下一阶段可消费的输入。讨论阶段不直接修改代码或交付物，仅产出对话与决策记录。

资料来源：commands/pan/discuss-phase.md:1-1

3. 阶段规划

plan-phase 命令将讨论阶段的结论转化为可执行的阶段计划，包括任务分解、依赖关系、产出物清单与验收要点。规划阶段是生命周期中「想法 → 任务」的关键转化点，其输出会被 exec-phase 直接消费。

资料来源：commands/pan/plan-phase.md:1-1

4. 阶段执行

exec-phase 命令依据 plan-phase 的输出，按照任务列表逐项落地实现。执行阶段的产物是实际的代码、配置、文档或其他工作产物。执行过程中产生的状态变更与中间结果，会作为 verify-phase 的输入进行核验。

资料来源：commands/pan/exec-phase.md:1-1

5. 阶段验证

verify-phase 命令对 exec-phase 的产出进行验收，依据 plan-phase 中定义的验收要点核对实现完整性，并生成验证报告。若验证未通过，工作流将回流到 plan-phase 进行迭代修正；若通过，则可以进入下一阶段或关闭当前阶段。

资料来源：commands/pan/verify-phase.md:1-1

6. 快速任务

quick 命令用于处理不需要完整生命周期的小范围任务，例如临时修复、文档调整或一次性脚本改动。它绕过完整的「讨论 → 规划 → 执行 → 验证」流程，直接进入受限范围的执行或讨论步骤，从而提升轻量任务的处理效率。

资料来源：commands/pan/quick.md:1-1

命令间的协作关系

各命令并非孤立运行，而是以项目状态作为共享上下文进行协作：

• 上下文传递：new-project 创建的项目状态被后续所有阶段命令读取，作为讨论、规划、执行与验证的共同基础。
• 产物消费链：discuss-phase 的结论 → plan-phase 的计划 → exec-phase 的实现 → verify-phase 的核验，形成单向数据流，并在验证失败时形成闭环回流。
• 轻重分离：quick 与完整的阶段流程共享底层项目上下文，但不强制走完所有阶段，从而在「严格流程」与「快速响应」之间提供平衡。

适用场景与最佳实践

• 新项目启动：使用 new-project 建立项目骨架，再依次进入阶段流程。
• 多阶段长期项目：每个阶段严格遵循「讨论 → 规划 → 执行 → 验证」的顺序，确保每次迭代都有可追溯的决策与验收记录。
• 小范围改动：直接使用 quick，避免重型流程带来的开销。
• 迭代修正：当 verify-phase 发现问题时，回到 plan-phase 调整任务定义，再重新执行。

通过这套工作流命令，PanWizard 将项目生命周期结构化为可复用、可审计、可迭代的标准流程，使团队能够在不同复杂度的工作之间灵活切换，同时保持一致的交付质量。

资料来源：commands/pan/discuss-phase.md:1-1 commands/pan/plan-phase.md:1-1 commands/pan/exec-phase.md:1-1 commands/pan/verify-phase.md:1-1

概述与定位

PanWizard 的核心库位于 pan-wizard-core/bin/lib/ 目录下，由一组以 .cjs 后缀结尾的 CommonJS 模块组成。该目录是整个工具链的执行中枢，承载了从项目初始化、阶段编排、状态管理到命令运行的全部核心职责。所有顶层 CLI 命令（如 pw init、pw phase、pw run 等）都通过此目录下的模块协调工作，而上层入口（如 pan-wizard-core/bin/pw.cjs）仅作为命令分发的薄壳。

整个核心库遵循"职责单一、依赖单向"的原则：配置模块负责读取与校验输入，状态模块负责持久化执行进度，阶段模块负责定义工作流步骤，运行器负责执行具体动作，而 core.cjs 则作为这些子模块的协调与装配层。这种分层让用户既可以通过内置命令直接使用，也可以针对特定模块进行替换或扩展。

资料来源：pan-wizard-core/bin/lib/core.cjs:1-40

核心模块划分

核心库按职责被切分为六个相互协作的模块。下表汇总了每个文件的主要角色与典型导出：

模块之间通过函数调用而非事件总线进行通信，避免了隐式副作用。例如 runner.cjs 在执行任务前，会先调用 state.cjs 读取当前阶段上下文，并在完成后将结果回写；而 phase.cjs 自身不执行任何命令，仅负责阶段切换的合法性校验与状态推进。

资料来源：pan-wizard-core/bin/lib/config.cjs:1-30、pan-wizard-core/bin/lib/state.cjs:1-25、pan-wizard-core/bin/lib/phase.cjs:1-30

执行流程与状态机

PanWizard 的运行模型可被视作一个轻量级状态机。下图展示了从初始化到阶段执行的关键流转：

stateDiagram-v2
    [*] --> Uninitialized
    Uninitialized --> Initialized: init.cjs
    Initialized --> PhaseSelected: phase.cjs
    PhaseSelected --> Running: runner.cjs
    Running --> PhaseSelected: state.cjs (next)
    Running --> Failed: runner.cjs (error)
    Failed --> Running: runner.cjs (retry)
    PhaseSelected --> [*]: all phases done

状态信息统一存放在 .panwizard/state.json 中，由 state.cjs 负责读写。该文件包含当前阶段序号、已完成阶段列表、最近一次运行时间戳与失败标记等字段。当用户再次调用命令时，state.cjs 会先加载该文件，将上下文注入到 runner.cjs 中，从而实现"断点续跑"。

runner.cjs 是真正执行副作用的地方：它根据阶段配置调用外部脚本或子命令，并将每一步的退出码、stdout、stderr 记录下来，供 state.cjs 持久化。任何非零退出码都会触发 core.cjs 的统一错误处理路径，避免散落在各处的 process.exit。

资料来源：pan-wizard-core/bin/lib/state.cjs:30-80、pan-wizard-core/bin/lib/runner.cjs:1-50、pan-wizard-core/bin/lib/core.cjs:40-90

扩展机制

PanWizard 在不破坏核心契约的前提下，提供了三类主要扩展点：

1. 配置级扩展

config.cjs 支持合并多层配置：默认配置、用户级 ~/.panrc 与项目级 panwizard.config.cjs。后者的优先级最高，允许用户在不修改核心库的前提下，注入自定义阶段、自定义脚本路径或自定义校验规则。资料来源：pan-wizard-core/bin/lib/config.cjs:30-90

2. 阶段插件

phase.cjs 通过阶段定义列表驱动工作流。用户可以在配置文件中追加阶段对象，每个阶段至少需要包含 id、title、run 字段，其中 run 可以是一个 shell 命令字符串，也可以是一个可由 runner.cjs 解析的子任务数组。这种声明式设计让"插入新阶段"无需改动核心库代码。资料来源：pan-wizard-core/bin/lib/phase.cjs:30-70

3. 运行器钩子

runner.cjs 在执行每个阶段前后暴露 beforePhase 与 afterPhase 两个钩子。钩子既可以写在配置文件中，也可以通过外部模块以 require 方式注入。典型用例包括：阶段开始前自动清理临时文件、阶段结束后自动归档日志等。这种"约定优于配置"的钩子机制，是 PanWizard 在保持核心库精简的同时支撑复杂现场需求的关键。资料来源：pan-wizard-core/bin/lib/runner.cjs:50-110

与社区反馈的对应

根据 v3.13.1 的公开说明，社区近期关注的核心问题之一是"如何在不修改核心库的前提下适配私有 CI 环境"。上述三类扩展点正是为回答此类问题而设计：配置级扩展可改路径与超时，阶段插件可重排流水线，运行器钩子可挂接内部通知系统。本次发布同时清理了所有已合并的内部代号，确保扩展示例中的命名对外部贡献者同样友好。

资料来源：pan-wizard-core/bin/lib/init.cjs:1-40、pan-wizard-core/bin/lib/runner.cjs:110-140

小结

pan-wizard-core/bin/lib/ 下的六个 CommonJS 模块构成了 PanWizard 的最小可执行内核：core.cjs 做编排，config.cjs 做输入，init.cjs 做脚手架，phase.cjs 做阶段定义，state.cjs 做持久化，runner.cjs 做执行。扩展性并不依赖复杂的插件框架，而是通过配置合并、阶段声明与运行器钩子这三种"轻量契约"实现，这使得核心库在保持小巧的同时具备足够的现场适配能力。

Pitfall Log / 踩坑日志

项目：oharms/PanWizard

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/oharms/PanWizard | host_targets=claude_code, claude, gemini_cli

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/oharms/PanWizard | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/oharms/PanWizard | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/oharms/PanWizard | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/oharms/PanWizard | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/oharms/PanWizard | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/oharms/PanWizard | release_recency=unknown