PA Agent 项目系统性分析报告

一、项目定位与核心价值

PA Agent（Price Action Agent）是一款面向主观交易者的桌面端 AI 辅助决策工具，采用 AGPL-3.0 开源协议。其定位非常清晰，与同类工具形成明显差异：

维度	PA Agent 的选择
分析对象	结构化 K 线数据 + 预计算特征，非截图识图
交易哲学	Al Brooks 价格行为（PA）体系
执行边界	不连接券商、不自动下单，仅输出「计划级」建议
交互形态	PyQt6 桌面 GUI，实时图表 + AI 侧边栏
目标用户	需要结构化辅助、但保留最终决策权的手动交易者

一句话概括设计意图：把 Brooks 式价格行为的专家知识编码进 Prompt 与决策树，用大模型做「读懂市场 + 单次决策」，用确定性程序做「数据预处理、路由、校验与安全闸」，形成人机协作而非黑盒自动交易。

---

二、整体架构：分层与依赖关系

项目采用典型的 分层 + 编排器（Orchestrator） 架构，通过 AppContext 显式依赖注入，避免全局单例。

flowchart TB
    subgraph Entry["入口层"]
        main["main.py"]
        ctx["AppContext.bootstrap()"]
    end

    subgraph GUI["表现层 (gui/)"]
        MW["MainWindow"]
        Chart["ChartWidget / pyqtgraph"]
        Sidebar["AISidebar / DecisionPanel"]
        Worker["_AnalysisWorker (QThread)"]
    end

    subgraph Orch["编排层 (orchestrator/)"]
        TS["TwoStageOrchestrator"]
        FC["FreeChatSession"]
        VR["validation_retry"]
    end

    subgraph AI["AI 层 (ai/)"]
        PA["PromptAssembler"]
        Router["route_strategy_files"]
        Val["JsonValidator"]
        DN["DecisionNodeEngine"]
        Client["DeepSeekClient / CursorSdkClient"]
        Norm["stage1/2_normalizer"]
    end

    subgraph Data["数据层 (data/)"]
        DS["DataSource ABC"]
        MT5["MT5Source"]
        TV["TradingViewSource"]
        Snap["snapshot + indicators"]
        RL["RefreshLoop"]
    end

    subgraph Persist["持久化 (records/)"]
        PW["PendingWriter"]
        ER["ExperienceReader"]
        Schema["AnalysisRecord"]
    end

    subgraph Assets["知识资产"]
        PE["prompt_engineering/*.txt"]
        Exp["experience/"]
    end

    main --> ctx
    ctx --> MW
    MW --> Worker
    Worker --> TS
    TS --> PA
    TS --> Router
    TS --> Val
    TS --> Client
    TS --> PW
    PA --> PE
    PA --> ER
    ER --> Exp
    RL --> DS
    MW --> Chart
    MW --> Sidebar
    FC --> Client

2.1 启动与装配流程

``12:47:pa_agent/main.py def main(argv: list[str] | None = None) -> int: # Early diagnostics before Qt / heavy imports: crash dumps + file logging. ... app = QApplication(argv) ... from pa_agent.app_context import AppContext ctx = AppContext.bootstrap() ... from pa_agent.gui.main_window import MainWindow window = MainWindow(ctx) window.show()

`AppContext.bootstrap()` 按固定顺序装配：**Settings → EventBus → DataSource → AI Client → PromptAssembler → Validator/Router → PendingWriter → SessionLedger**。这是典型的 **组合根（Composition Root）** 模式，各组件通过构造函数接收依赖，便于测试替换。

### 2.2 模块职责一览

| 包路径 | 职责 | 设计特点 |
|--------|------|----------|
| `config/` | Pydantic 配置模型、路径常量 | 类型安全、字段校验、`extra="ignore"` 向前兼容 |
| `data/` | 多数据源 K 线、快照、指标预热 | ABC + Factory，不可变 `KlineFrame` |
| `ai/` | Prompt 组装、路由、校验、归一化、客户端 | 纯函数与有状态客户端分离 |
| `orchestrator/` | 两阶段流水线、追问会话、重试 | 同步回调 + CancelToken |
| `gui/` | PyQt6 主窗、图表、决策可视化 | 后台 QThread 跑编排器，信号回主线程 |
| `records/` | 分析记录 Schema、落盘、经验库读取 | Pydantic v2 `extra="forbid"` |
| `indicators/` | EMA20、ATR14 | 与 K 线缓冲对齐 |
| `notify/` | 飞书、PushPlus 推送 | 可选通知 |
| `demo/` | 历史记录回放 | 与真实 Worker 同信号接口 |
| `util/` | EventBus、日志脱敏、线程取消 | 横切关注点 |

---

## 三、核心设计思想

### 3.1 「知识外置 + 程序约束 + 模型推理」三元结构

这是本项目最突出的架构思想：

1. **知识外置（`prompt_engineering/`）**  
   29 个 `.txt` 文件承载 Brooks PA 体系：人设、市场诊断框架、通道/尖峰/区间策略、二元决策树等。这些文件是 **可编辑的领域知识库**，而非硬编码在 Python 里。

2. **程序约束（`ai/decision_nodes.py`、`market_features.py`、`router.py`）**  
   - 程序预计算客观特征（区间位置、重叠度、突破事件、H/L 计数候选等）  
   - 确定性决策节点引擎对 §1.1/§2.3/§2.4 等节点做「程序裁判」  
   - 策略文件路由表将阶段一诊断映射到阶段二 playbook 子集  

3. **模型推理（两阶段 LLM）**  
   模型负责复杂模式识别、逐棒叙述、`gate_trace` / `decision_trace` 填写，但最终必须输出 **严格 JSON Schema**。

### 3.2 Al Brooks 价格行为哲学的工程化

`提示词大纲_人设与思维方式.txt` 确立了四条全局硬禁令和四种核心思维：

- **频谱思维**：尖峰→极端 TR 是连续频谱  
- **概率思维**：趋势中多数反转失败；区间中多数突破失败  
- **惯性思维**：默认延续（Always In）  
- **嵌套思维**：长程定方向，短程定入场  

工程上体现为：
- 阶段一输出 `cycle_position`、`direction`、`detected_patterns`、`gate_result`  
- `gate_result=proceed` 是进入阶段二的 **硬闸门**  
- 阶段二经路由加载 **最少必要** 策略文件，控制 token 与幻觉  
- `decision_stance`（保守/平衡/激进）调节下单意愿，而非改 schema  

### 3.3 「结构化数据进、结构化 JSON 出」

明确拒绝「看图说话」路线，选择：


KlineBar[] + EMA/ATR + 几何特征 + 程序结构特征
    → LLM 阶段一诊断 JSON
    → 路由策略文件
    → LLM 阶段二决策 JSON
优势：可复现、可校验、可增量、可落盘审计。`KlineBar.seq` 约定（K1 = 最新已收盘）贯穿图表、Prompt、校验全链路。

### 3.4 混合智能：AI 主判 vs 程序主判

`decision_nodes.py` 定义了精细的 **节点权限模型**：

| 节点类型 | 含义 | 示例 |
|----------|------|------|
| `LOCKED_NODES` | 程序锁定，AI 不可覆盖 | 1.1（数据充足性）、9.1 |
| `AI_PRIMARY_NODES` | AI 主判，程序仅补缺 | 1.3、2.5 |
| `OVERRIDABLE_NODES` | AI 可覆盖程序结论并需 `override_reason` | 2.3、2.4、11.x |
| `SAFETY_GATE_NODES` | 安全闸，失败则短路 | 1.1、10.3、14 |

这体现了 **「不信任纯 LLM，也不盲信纯规则」** 的设计：在可客观量化的节点用程序锚定，在需要语境理解的节点交给模型，并保留可追溯的覆盖记录。

### 3.5 辅助而非替代：明确的责任边界

- 输出的是 **单次分析计划**（限价/突破/市价或 `wait`），不含仓位管理  
- `keep_analysis` 可持续跟踪新 K 线，但仍由用户决定是否下单  
- 演示模式（`DemoReplayer`）可离线回放，信号接口与真实分析 Worker 一致  

---

## 四、两阶段分析流水线（核心业务流程）

`TwoStageOrchestrator.submit()` 是系统心脏，流程如下：

mermaid
sequenceDiagram
    participant UI as MainWindow/Worker
    participant TS as TwoStageOrchestrator
    participant PF as Preflight Gate
    participant PA as PromptAssembler
    participant API as AI Client
    participant V as JsonValidator
    participant R as Router
    participant PW as PendingWriter
    UI->>TS: submit(KlineFrame)
    TS->>PF: check_preflight_data
    alt 数据不足
        PF-->>TS: fail
        TS->>PW: save_partial
    else 通过
        TS->>PA: build_stage1
        TS->>API: chat (stage1)
        API-->>TS: stream + reply
        TS->>V: validate stage1
        alt 校验失败
            TS->>VR: validate_with_retry
        end
        TS->>R: route_strategy_files
        TS->>PA: build_stage2
        TS->>API: chat (stage2)
        TS->>V: validate stage2
        TS->>PW: save_full
    end
    TS-->>UI: AnalysisRecord
### 4.1 阶段一：市场诊断

- **输入**：K 线表、EMA/ATR、几何特征、`SimpleMarketFeatures`、可选经验库片段、模式速查表  
- **输出 JSON**：`cycle_position`、`direction`、`detected_patterns`、`gate_trace`、`gate_result`、`bar_by_bar_summary` 等  
- **关键约束**（`prompt_assembler.py`）：思考与 `content` 分离；`content` 必须是可 `json.loads` 的裸 JSON；全程简体中文  

### 4.2 策略路由：按需加载 Playbook

`router.route_strategy_files()` 是纯函数，根据阶段一结果组合策略文件：

89:107:pa_agent/ai/router.py
def route_strategy_files(stage1_json: dict[str, Any]) -> list[str]:
    """Return the ordered, deduplicated list of strategy files for Stage 2.
    ...
    """
    cp = stage1_json.get("cycle_position", "unknown")
    direction = stage1_json.get("direction", "neutral")
    patterns = merge_detected_patterns(stage1_json)
    ...
    files.extend(_base_files_for_cycle(cp, direction, spike_stage=spike_stage))
设计亮点：
- **Token 经济学**：默认不加载全库（`stage2_load_full_strategy_library=False`）  
- **Brooks 嵌套**：`recent_spike` 可在非 spike 周期位置叠加尖峰 playbook  
- **模式叠加**：楔形、MTR、铁丝网等按 `detected_patterns` 追加  
- `extreme_tr` / `unknown` → 空列表，语义为「不交易」  

### 4.3 阶段二：单次交易决策

- 注入阶段一 JSON + 路由到的策略文件 + 决策倾向指引 + 上轮决策连续性块  
- 输出：`decision`（`trade`/`wait`/`reject`）、`decision_trace`、`terminal`、三价（若 trade）  
- `decision_continuity.py` 处理结构位反手冷却、限价单过期、失效判定  

### 4.4 增量分析

当同品种同周期存在成功记录且新增 K 线 ≤ 阈值时：
- `build_incremental_stage1` 携带上轮诊断上下文  
- 只对新增棒做增量判断，节省 token、保持结论连贯  
- 对齐失败则回退全量分析  

---

## 五、数据层设计

### 5.1 抽象与多实现

92:96:pa_agent/data/base.py
class DataSource(ABC):
    """Abstract interface for K-line data providers.
    Implementations: TradingViewSource (active), MT5Source (stub).
    """
| 实现 | 场景 | 可见性 |
|------|------|--------|
| `MT5Source` | Windows 本地 MT5 | UI 默认 |
| `TradingViewSource` | 跨平台 tvDatafeed | UI 可选 |
| `AkShareSource` / `EastMoneySource` / `TushareSource` | A 股 | 部分隐藏/配置 |
| `YFinanceSource` | 期货/加密 | 隐藏 |

`DataSourceKind` + `create_data_source()` 工厂模式，UI 只暴露 MT5/TV，其余供程序化或配置使用。

### 5.2 不可变快照模型

`KlineFrame` 为 `frozen dataclass`，包含：
- `bars`：新→旧排序，`seq=1` 为最新已收盘  
- `indicators`：EMA20/ATR14，在更老缓冲上预热后截取  
- `snapshot_ts_local_ms`：快照时刻  

分析提交时图表 **冻结** 为「仅已收盘」快照，与发给 AI 的数据对齐（文档 `docs/图表K线与分析快照说明.md`）。

### 5.3 实时刷新

`RefreshLoop` 在独立 `QThread` 中以可配置间隔（默认 1s）拉取数据：
- 防重叠 fetch（避免 TV 限流）  
- 指数退避处理瞬态错误  
- 通过 `EventBus.data_frame` 推送给图表  

---

## 六、AI 层：Prompt、客户端与归一化

### 6.1 PromptAssembler：领域 DSL 编译器

`prompt_assembler.py`（约 1900+ 行）承担：
- 阶段一/二 system + user 消息构建  
- K 线表格渲染、特征注入、HTF 文本、经验库片段  
- 增量/原始模式分支  
- 多 Provider 特殊规则（OpenClaw 禁工具、MiMo 兼容等）  

可视为将 **磁盘上的 Brooks 知识 + 运行时市场数据** 编译成 LLM 可消费的「分析任务包」。

### 6.2 多 Provider 路由

12:31:pa_agent/ai/client_factory.py
def create_ai_client(
    settings: AIProviderSettings,
    logger_: logging.Logger | None = None,
) -> Any:
    """Return CursorSdkClient for

openclaw_cs*

, else DeepSeekClient."""
    ...
    return DeepSeekClient(settings=settings, logger_=log)
- 默认：**OpenAI 兼容 API**（DeepSeek、PackyAPI 等）  
- `openclaw_cs*` 模型 → `CursorSdkClient`  
- 另有 QClaw / WorkBuddy 连接器用于 token 同步与网关场景  

`DeepSeekClient` 支持流式回调、CancelToken、KV 缓存命中率统计、MiMo reasoning 兼容。

### 6.3 输出归一化（Lenient Mode）

`stage1_normalizer.py` / `stage2_normalizer.py` 在 schema 校验前修复常见模型变体：
- 策略文件名别名  
- `bar_role` 中英文别名  
- trace 节点格式规范化  

配合 `ValidationSettings.normalization_mode`（`strict` / `lenient`），在 **严格正确性** 与 **生产可用性** 之间取舍。

---

## 七、校验与可靠性体系

这是项目工程成熟度最高的部分之一。

### 7.1 五级校验分类

1:8:pa_agent/ai/json_validator.py
"""JSON validator for Stage 1 and Stage 2 AI outputs.
Categories:
  a — syntax error (invalid JSON)
  b — missing required field
  c — illegal value (enum violation, type mismatch, 不下单 price non-null, etc.)
  d — plain text (no JSON structure at all)
  e — provider error (quota/billing; non-retryable)
校验链路：**Markdown 围栏剥离 → 外层 JSON 提取 → 截断修复（可选）→ jsonschema → 业务规则（三价一致性、trace 顺序、不下单时价格为空等）→ 可选 coherence_checks**。

### 7.2 自动重试与防作弊

`validation_retry.py`：
- 格式类错误（a/b/d）可自动追加 feedback user turn 重试  
- `retry_policy.detect_cheat` 检测 immutable 字段篡改  
- 语义类错误（c）有限重试  
- Provider 配额耗尽（e）不重试  

错误信息高度 **可操作**（如思考区占满 token 导致 `content` 为空时的具体提示）。

### 7.3 决策连续性安全

`decision_continuity.py` 防止：
- 同结构位 3 跳内反手  
- 过期限价单仍被引用  
- 上轮 plan 已失效仍延续  

这些是典型的 **「LLM 健忘/冲动」程序护栏**。

---

## 八、GUI 与交互架构

### 8.1 线程模型

- **主线程**：Qt 事件循环、图表绘制、用户输入  
- **RefreshLoop QThread**：行情刷新  
- **_AnalysisWorker QThread**：两阶段分析（阻塞 API 不卡 UI）  
- 通过 `pyqtSignal` 传递 token 流、状态、完整 `AnalysisRecord`  

`CancelToken` 在阶段间与 API 调用后检查，支持切换品种时取消在途分析。

### 8.2 信息架构

主窗口左右分栏：
- **左**：K 线（pyqtgraph）+ 决策叠加线（入场/止损/止盈）  
- **右 AI 侧边栏**：实时流 / 决策树 / 可视化 / 决策面板 / 原始 JSON / 调试  

`decision_flow_viz.py` 将 `gate_trace` + `decision_trace` 渲染为可交互决策树动画，把抽象 JSON 轨迹 **可视化还原 Brooks 决策路径**。

### 8.3 EventBus

10:24:pa_agent/util/event_bus.py
class EventBus(QObject):
    """Central signal hub shared across GUI components and orchestrators.
    ...
    """
    data_frame = pyqtSignal(object)    # KlineFrame
    status = pyqtSignal(str)           # status text
    exception = pyqtSignal(object)     # AlarmPayload
    token_update = pyqtSignal(dict)    # token/cost update dict
轻量级 Qt 信号总线，解耦图表、状态栏、Token 进度条、校验告警。

---

## 九、持久化、审计与经验库

### 9.1 AnalysisRecord 全链路落盘

26:43:pa_agent/records/schema.py
class AnalysisRecord(BaseModel):
    """Full record of a two-stage AI analysis run."""
    meta: RecordMeta
    kline_data: list[dict]
    stage1_messages: list[dict]
    stage1_response: Optional[dict]
    stage1_diagnosis: Optional[dict]
    stage2_messages: list[dict]
    ...
    strategy_files_used: list[str]
    experience_loaded: list[dict]

每次分析保存至 records/pending/{时间}_{品种}_{周期}.json，追问写入 .followups.jsonl。API Key 经 mask_secret 脱敏，测试中有 property 保证日志无明文密钥。

`9.2 经验库`

experience/ 目录存放按 cycle_position 检索的历史案例，ExperienceReader 在阶段二注入 top-N 片段（可配置条数与字符上限）。这是轻量级 RAG，不依赖向量数据库，适合桌面场景。

`9.3 分析后自由对话`

FreeChatSession 锚定已完成 AnalysisRecord，维护独立对话历史，每次 send() 可拉取最新 K 线快照——追问场景与两阶段「任务模式」分离，避免模型把阶段二当成聊天收尾。

---

`十、Prompt 工程：可维护的知识架构`

prompt_engineering/ 文件组织体现领域驱动：

类别	代表文件	作用
全局人设	提示词大纲_人设与思维方式.txt	禁令、思维框架、两阶段契约
诊断框架	市场诊断框架.txt	八态频谱、cycle_position
周期 Playbook	通道/尖峰/区间分析+策略共 10 文件	阶段二路由主体
模式专题	文件13–28	楔形、MTR、铁丝网、MM 等
决策结构	二元决策.txt	节点编号、闸门逻辑、trace schema 语义源
检查单	逐棒分析检查单.txt	质量控制

_reference/ 下有 pattern_enum.md、abbrev_glossary.md

 等维护文档，说明团队把 Prompt 当 版本化知识产品 管理。
---
十一、测试策略
测试规模可观（约 100+ 测试文件），分层清晰：
层级 目录 关注点
unit tests/unit/ 归一化、路由、校验、决策节点、图表逻辑
property tests/property/ Hypothesis 属性测试（路由确定性、schema 不变量）
integration tests/integration/ 两阶段流水线、网络超时、取消
e2e tests/e2e/ 冒烟（happy path、无单、追问）
live @pytest.mark.live 真实 API，永不读 settings.json
CI 在 Windows + Python 3.11 上运行（与 MT5 主平台一致）。对 JSON schema、路由、Prompt 文件的变更有专门回归测试（

层级	目录	关注点
unit	tests/unit/	归一化、路由、校验、决策节点、图表逻辑
property	tests/property/	Hypothesis 属性测试（路由确定性、schema 不变量）
integration	tests/integration/	两阶段流水线、网络超时、取消
e2e	tests/e2e/	冒烟（happy path、无单、追问）
live	@pytest.mark.live	真实 API，永不读 settings.json

test_prompt_txt_files.py、test_router_determinism.py

 等）。
---
十二、横切关注点
Concern 实现
配置 Pydantic Settings，config/settings.json
日志 文件 + 控制台，API Key 掩码
崩溃诊断 crash_diagnostics.py，独立 crash.log
通知 飞书 Webhook、PushPlus（下单机会可选推送）
安全 密钥脱敏落盘；security/ 包占位；pre-commit 防密钥提交
许可 AGPL-3.0，强调开源传染性
---
十三、架构优势与权衡
优势

Concern	实现
配置	Pydantic Settings`，`config/settings.json
日志	文件 + 控制台，API Key 掩码
崩溃诊断	crash_diagnostics.py`，独立 crash.log`
通知	飞书 Webhook、PushPlus（下单机会可选推送）
安全	密钥脱敏落盘；security/ `包占位；pre-commit 防密钥提交`
许可	AGPL-3.0，强调开源传染性

1. 可审计、可复现：全 Prompt/响应/JSON 落盘，演示模式可离线回放 2. 领域知识可迭代：改.txt即可调策略，无需改 Python 3. LLM 不可靠性有体系化应对：归一化 + 多级校验 + 重试 + 程序闸 + 连续性护栏 4. Token 经济学：路由按需加载、增量分析、可选关闭下根 K 预测 5. 测试覆盖与 schema 契约：适合长期演进 6. 明确产品边界：辅助决策，规避自动交易合规与责任风险

`权衡 / 局限`

1. 复杂度高：两阶段 + 决策树 + 大量 Prompt，新贡献者学习曲线陡 2. 主平台绑定 Windows：MT5 深度集成；macOS 主要靠 TradingView 3. GUI 与编排耦合：MainWindow体量很大（4000+ 行），部分逻辑仍可进一步抽取 4. 多数据源一致性：指标预热窗口与外盘图表「全历史」可能有细微差异（已在 Prompt 中声明） 5. AGPL 许可：商业闭源集成需合规评估

---

`十四、设计模式速查`

模式	出现位置
依赖注入 / Composition Root	AppContext
抽象工厂	create_data_source`,` create_ai_client
策略模式	多 DataSource`、多 AI Client`
编排器	TwoStageOrchestrator
不可变值对象	KlineFrame`,` KlineBar
观察者 / 事件总线	EventBus`, Qt Signals`
管道 + 闸门	Preflight → Stage1 gate → Stage2
规格模式	JsonValidator `+ jsonschema`
防腐层	stage*_normalizer`,` response_extract
知识外置	prompt_engineering/*.txt`


---
十五、总结
PA Agent 不是「套壳 ChatGPT 看盘」，而是将 Al Brooks 价格行为方法论 工程化为一套可验证、可路由、可增量、可审计的桌面分析系统。其架构思想可概括为：
> 结构化市场数据 + 程序预特征 + 外置领域知识库 → 两阶段约束式 LLM 推理 → 严格 JSON 契约 + 混合决策节点 + 多层校验 → 人机协作式交易计划输出
技术栈（PyQt6 + pyqtgraph + Pydantic + OpenAI SDK + 多数据源）服务于上述产品哲学，而非反过来。对希望理解「如何把交易领域知识与大模型结合」的开发者而言，本项目在 Prompt 路由、Schema 校验、程序/AI 权限划分、增量分析连续性 四个方面都提供了较完整的参考实现。
---

PA Agent 项目系统性分析报告

一、项目定位与核心价值

二、整体架构：分层与依赖关系

2.1 启动与装配流程

9.2 经验库

9.3 分析后自由对话

十、Prompt 工程：可维护的知识架构

十一、测试策略

十二、横切关注点

十三、架构优势与权衡

优势

权衡 / 局限

十四、设计模式速查

十五、总结

🌟 智谱 GLM-5 已上线

`9.2 经验库`

`9.3 分析后自由对话`

`十、Prompt 工程：可维护的知识架构`

`权衡 / 局限`

`十四、设计模式速查`