PA Agent 项目系统性分析报告

一、项目定位与核心价值

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

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

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

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

2.1 启动与装配流程

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 模块职责一览

三、核心设计思想

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 定义了精细的 节点权限模型：

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

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

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

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

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

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() 是纯函数，根据阶段一结果组合策略文件：

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 抽象与多实现

class DataSource(ABC):
    """Abstract interface for K-line data providers.

    Implementations: TradingViewSource (active), MT5Source (stub).
    """

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 路由

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 五级校验分类

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

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 全链路落盘

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/ 文件组织体现领域驱动：

_reference/ 下有 pattern_enum.md、abbrev_glossary.md 等维护文档，说明团队把 Prompt 当 版本化知识产品 管理。

十一、测试策略

测试规模可观（约 100+ 测试文件），分层清晰：

CI 在 Windows + Python 3.11 上运行（与 MT5 主平台一致）。对 JSON schema、路由、Prompt 文件的变更有专门回归测试（test_prompt_txt_files.py、test_router_determinism.py 等）。

十二、横切关注点

十三、架构优势与权衡

优势

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 许可：商业闭源集成需合规评估

十四、设计模式速查

十五、总结

PA Agent 不是「套壳 ChatGPT 看盘」，而是将 Al Brooks 价格行为方法论 工程化为一套可验证、可路由、可增量、可审计的桌面分析系统。其架构思想可概括为：

结构化市场数据 + 程序预特征 + 外置领域知识库 → 两阶段约束式 LLM 推理 → 严格 JSON 契约 + 混合决策节点 + 多层校验 → 人机协作式交易计划输出

技术栈（PyQt6 + pyqtgraph + Pydantic + OpenAI SDK + 多数据源）服务于上述产品哲学，而非反过来。对希望理解「如何把交易领域知识与大模型结合」的开发者而言，本项目在 Prompt 路由、Schema 校验、程序/AI 权限划分、增量分析连续性 四个方面都提供了较完整的参考实现。