# https://github.com/oharms/PanWizard 项目说明书

生成时间：2026-07-18 09:38:29 UTC

## 目录

- [系统概览：PanWizard 是什么、解决什么问题](#page-overview)
- [机器人军团：Mission Control、四级梯队与人类合并门控](#page-bot-army)
- [工作流命令与项目生命周期](#page-commands)
- [核心库、内部模块与可扩展机制](#page-core-lib)

<a id='page-overview'></a>

## 系统概览：PanWizard 是什么、解决什么问题

### 相关页面

相关主题：[机器人军团：Mission Control、四级梯队与人类合并门控](#page-bot-army), [工作流命令与项目生命周期](#page-commands), [核心库、内部模块与可扩展机制](#page-core-lib)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/oharms/PanWizard/blob/main/README.md)
- [docs/USER-GUIDE.md](https://github.com/oharms/PanWizard/blob/main/docs/USER-GUIDE.md)
- [docs/ARCHITECTURE.md](https://github.com/oharms/PanWizard/blob/main/docs/ARCHITECTURE.md)
- [docs/COMPARISON.md](https://github.com/oharms/PanWizard/blob/main/docs/COMPARISON.md)
- [docs/FAQ.md](https://github.com/oharms/PanWizard/blob/main/docs/FAQ.md)
- [bin/install.js](https://github.com/oharms/PanWizard/blob/main/bin/install.js)
</details>

# 系统概览：PanWizard 是什么、解决什么问题

## 项目定位与核心目标

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` 作为唯一的命令行入口，负责读取参数、解析目标环境并驱动后续步骤；其余能力则通过文档而非代码来传递。下图给出了高层视角的协作关系：

```mermaid
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` 提供单一可执行入口 | bin/install.js |
| 用户文档 | 完整覆盖从入门到进阶的 USER-GUIDE | docs/USER-GUIDE.md |
| 架构说明 | 解释模块边界与协作关系 | docs/ARCHITECTURE.md |
| 横向对比 | 与同类工具的能力差异分析 | docs/COMPARISON.md |
| 常见问题 | 收录社区高频疑问与解答 | docs/FAQ.md |

资料来源：[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]()。

---

<a id='page-bot-army'></a>

## 机器人军团：Mission Control、四级梯队与人类合并门控

### 相关页面

相关主题：[系统概览：PanWizard 是什么、解决什么问题](#page-overview), [工作流命令与项目生命周期](#page-commands), [核心库、内部模块与可扩展机制](#page-core-lib)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [commands/pan/army.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/army.md)
- [commands/pan/hud.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/hud.md)
- [commands/pan/dashboard.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/dashboard.md)
- [agents/pan-conductor.md](https://github.com/oharms/PanWizard/blob/main/agents/pan-conductor.md)
- [agents/pan-executor.md](https://github.com/oharms/PanWizard/blob/main/agents/pan-executor.md)
- [agents/pan-roadmapper.md](https://github.com/oharms/PanWizard/blob/main/agents/pan-roadmapper.md)
</details>

# 机器人军团：Mission Control、四级梯队与人类合并门控

## 系统概述

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 命令则用于成员调度与排障。

## 四级梯队体系

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

| 梯队 | 智能体 | 核心职责 | 决策半径 |
| --- | --- | --- | --- |
| T1 指挥 | `pan-conductor` | 任务接收、分派、跨梯队协调 | 全局 |
| T2 规划 | `pan-roadmapper` | 将任务拆解为里程碑、拆出 PR 序列 | 项目级 |
| T3 执行 | `pan-executor` | 单个 PR 的代码改动、测试、提交 | 文件级 |
| T4 监控 | HUD/Dashboard 聚合层 | 状态汇总、告警上报 | 视图级 |

梯队间的通信通过结构化事件传递：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 首次公开发布时所强调的核心安全姿态——所有自动化产出都可追溯、可拦截、可回滚。

---

<a id='page-commands'></a>

## 工作流命令与项目生命周期

### 相关页面

相关主题：[系统概览：PanWizard 是什么、解决什么问题](#page-overview), [机器人军团：Mission Control、四级梯队与人类合并门控](#page-bot-army), [核心库、内部模块与可扩展机制](#page-core-lib)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [commands/pan/new-project.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/new-project.md)
- [commands/pan/discuss-phase.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/discuss-phase.md)
- [commands/pan/plan-phase.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/plan-phase.md)
- [commands/pan/exec-phase.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/exec-phase.md)
- [commands/pan/verify-phase.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/verify-phase.md)
- [commands/pan/quick.md](https://github.com/oharms/PanWizard/blob/main/commands/pan/quick.md)
</details>

# 工作流命令与项目生命周期

## 概述

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

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

## 项目生命周期阶段

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

```mermaid
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]()

---

<a id='page-core-lib'></a>

## 核心库、内部模块与可扩展机制

### 相关页面

相关主题：[系统概览：PanWizard 是什么、解决什么问题](#page-overview), [机器人军团：Mission Control、四级梯队与人类合并门控](#page-bot-army), [工作流命令与项目生命周期](#page-commands)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [pan-wizard-core/bin/lib/core.cjs](https://github.com/oharms/PanWizard/blob/main/pan-wizard-core/bin/lib/core.cjs)
- [pan-wizard-core/bin/lib/config.cjs](https://github.com/oharms/PanWizard/blob/main/pan-wizard-core/bin/lib/config.cjs)
- [pan-wizard-core/bin/lib/state.cjs](https://github.com/oharms/PanWizard/blob/main/pan-wizard-core/bin/lib/state.cjs)
- [pan-wizard-core/bin/lib/init.cjs](https://github.com/oharms/PanWizard/blob/main/pan-wizard-core/bin/lib/init.cjs)
- [pan-wizard-core/bin/lib/phase.cjs](https://github.com/oharms/PanWizard/blob/main/pan-wizard-core/bin/lib/phase.cjs)
- [pan-wizard-core/bin/lib/runner.cjs](https://github.com/oharms/PanWizard/blob/main/pan-wizard-core/bin/lib/runner.cjs)
</details>

# 核心库、内部模块与可扩展机制

## 概述与定位

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]()

## 核心模块划分

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

| 模块文件 | 主要职责 | 典型协作对象 |
| --- | --- | --- |
| `core.cjs` | 顶层协调、命令路由、公共错误处理 | 全部其他模块 |
| `config.cjs` | 解析 `.panrc`、`panwizard.config.*` 等配置 | `init.cjs`、`phase.cjs` |
| `state.cjs` | 读写 `.panwizard/state.json` 状态文件 | `phase.cjs`、`runner.cjs` |
| `init.cjs` | 脚手架生成、目录与模板初始化 | `config.cjs` |
| `phase.cjs` | 定义与切换阶段（如 plan / build / verify） | `state.cjs`、`runner.cjs` |
| `runner.cjs` | 阶段任务的实际执行与子进程调度 | `state.cjs` |

模块之间通过函数调用而非事件总线进行通信，避免了隐式副作用。例如 `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 的运行模型可被视作一个轻量级状态机。下图展示了从初始化到阶段执行的关键流转：

```mermaid
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` 做执行。扩展性并不依赖复杂的插件框架，而是通过配置合并、阶段声明与运行器钩子这三种"轻量契约"实现，这使得核心库在保持小巧的同时具备足够的现场适配能力。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: oharms/PanWizard; human_manual_source: deepwiki_human_wiki -->