11_Tech_Agent_Design

Agent 设计专题

本页记录 WyckoffAgent 当前代码中的 Agent（智能体）工程设计，重点解释 CLI（命令行）/ TUI（终端图形界面）里的完整 Agent Runtime（智能体运行时），以及 Web（网页端）、MCP（模型上下文协议）如何复用工具层但采用不同运行时。

代码核对时间：2026-06-01，主仓库 main@942a34d。本页以当前代码为准；历史 Streamlit MVP 不再属于 main 的 Agent 架构。

本页只描述公开系统设计和代码结构，不包含个人运行数据、账户信息或本地历史内容。

英文术语速查

英文术语	中文释义
Agent	智能体：能根据目标自主选择工具、多轮执行并输出结果的程序
Runtime	运行时：负责模型调用、工具执行、循环控制、上下文压缩和追踪
CLI	命令行界面：通过终端命令使用系统
TUI	终端图形界面：在终端里显示类似 GUI 的交互界面
Web	网页端：浏览器里的在线读盘室
CF Pages	Cloudflare Pages 边缘页面：承载 Web 前端和边缘函数
MCP	模型上下文协议：给 Claude Code、Cursor 等外部 Agent 暴露工具的协议
Provider	模型适配层：把不同模型供应商统一成同一套调用接口
Tool Schema	工具定义：告诉模型工具名、用途和参数格式
Tool Call	工具调用：模型决定调用某个工具并给出参数
ReAct	推理-行动循环：模型先推理，再调用工具，观察结果后继续推理
Loop Guard	循环守卫：运行时强制模型补调必须工具的保护机制
Doom-loop	死循环：模型反复用同一参数调用同一工具
Scratchpad	运行追踪文件：记录一轮对话中的模型、工具、压缩和最终结果
Sub-agent	子智能体：只负责某类任务的小 Agent
Context Window	上下文窗口：模型一次请求能容纳的最大上下文长度
Compaction	上下文压缩：把旧对话压成摘要，给后续轮次腾空间
Memory	记忆：跨会话保留的稳定偏好和决策逻辑
Fallback	故障切换：主模型失败时自动换备用模型
Routing	模型路由：按任务复杂度选择 heavy/light 模型
Reasoning	推理内容：部分模型输出的内部思考过程
Token	令牌：模型上下文长度和计费的基本单位
SSE	服务端事件流：流式响应的一种传输格式
Daemon Thread	守护线程：后台线程，进程退出时自动回收
System Prompt	系统提示词：约束模型行为的顶层指令
Skill	技能模板：预设的一类用户任务提示

0. 当前实现边界

WyckoffAgent 不是单一入口，而是三条通道共享同一套金融能力：

通道	入口	运行时	对话/工具编排	适合场景
React Web（网页端）/ CF Pages（Cloudflare Pages 边缘页面）	`web/apps/web/`	Vercel AI SDK（Vercel 的 AI 工具包）`streamText`（流式文本生成）	Web 端独立工具循环，`stopWhen(stepCountIs(10))`（达到 10 步就停止）	在线读盘室、浏览器用户
CLI（命令行）/ TUI（终端图形界面）	`wyckoff`	`cli/runtime.py::AgentRuntime`	完整 ReAct loop（推理-行动循环）、记忆、上下文压缩、后台任务、sub-agent（子智能体）	本地深度投研和工具型 Agent
MCP Server（模型上下文协议服务）	`wyckoff-mcp`	FastMCP stdio（标准输入输出通信）	无内置对话 loop（循环），只暴露工具	Claude Code / Cursor 等外部 Agent 调用

共享层是 agents/chat_tools.py 和核心分析引擎；不同入口只是在运行时、权限、展示和状态管理上分化。

关键边界：

CLI/TUI 是最完整的 Agent Runtime（智能体运行时）：负责 provider（模型适配层）调用、工具执行、并发分批、上下文压缩、Loop Guard（循环守卫）、doom-loop（死循环）检测、scratchpad（运行追踪文件）、后台任务和 sub-agent（子智能体）。
Web 不复用 AgentRuntime：它使用 web/apps/web/src/lib/chat-agent.ts 中的 Vercel AI SDK（Vercel 的 AI 工具包）工具循环，保留流式输出、工具调用、上下文本地摘要和 reasoning（推理内容）透传，但不接入 CLI 的 SQLite（本地轻量数据库）记忆、scratchpad（运行追踪文件）和 sub-agent（子智能体）。
MCP 不具备会话智能：mcp_server.py 只是把 Wyckoff 能力注册成 MCP tools（模型上下文协议工具），推理和多轮编排由外部客户端负责。

1. CLI Agent Runtime（命令行智能体运行时）

核心实现：cli/runtime.py::AgentRuntime。

它把一次用户请求拆成一个 provider-agnostic（不绑定具体模型供应商）的事件循环：

flowchart TD
    U["用户消息"] --> X["resolve_turn_expectation<br/>识别本轮必需工具"]
    X --> M["build_memory_context<br/>召回相关记忆"]
    M --> I["prepend_memory_context<br/>临时注入 relevant-memories"]
    I --> S["shrink_stale_tool_results<br/>压缩旧工具结果"]
    S --> C{"上下文是否超过 25% 窗口"}
    C -->|是| C1["flush_memory_before_compaction<br/>压缩前提取持久偏好"]
    C1 --> C2["compact_messages<br/>生成 500 字以内摘要"]
    C -->|否| L
    C2 --> L["provider.chat_stream<br/>模型流式调用"]

    L --> TO[" _iter_with_timeout<br/>60 秒无 chunk 则超时"]
    TO --> K["消费 chunk<br/>流式片段"]
    K -->|text_delta| T["RuntimeEvent:text_delta<br/>TUI 流式渲染"]
    K -->|thinking_delta| R["RuntimeEvent:thinking_delta<br/>记录推理内容"]
    K -->|usage| U1["RuntimeEvent:usage<br/>累计 token 用量"]

    K -->|tool_calls| A["追加 assistant tool message<br/>保留 tool_call_id"]
    A --> MR{"超过 MAX_TOOL_ROUNDS=15"}
    MR -->|是| ML["done:工具调用轮次超限"]
    MR -->|否| B["partition_tool_calls<br/>按并发安全性分批"]
    B --> BC{"concurrency_safe"}
    BC -->|是| P1["ThreadPoolExecutor<br/>最多 5 线程并发"]
    BC -->|否| P2["串行执行<br/>避免写操作互相踩踏"]
    P1 --> DL
    P2 --> DL

    DL{"doom-loop 检测<br/>最近 6 次内重复 3 次"}
    DL -->|触发| AB["追加 tool_error<br/>中止本轮工具批次"]
    DL -->|未触发| AP{"requires_approval<br/>是否高风险工具"}
    AP -->|是| CF["确认弹窗<br/>允许 / 总是允许 / 修改 / 拒绝"]
    AP -->|否| BG
    CF --> BG{"background<br/>是否后台任务"}
    BG -->|是| BT["BackgroundTaskManager<br/>返回 task_id"]
    BG -->|否| EX["ToolRegistry.execute<br/>执行确定性 Python 函数"]
    EX --> ER{"工具是否报错"}
    ER -->|是| TE["tool_error<br/>错误回灌给模型"]
    ER -->|否| TR["tool_result<br/>结果回灌给模型"]
    BT --> TR
    TE --> FMT
    TR --> FMT["format_tool_result_for_context<br/>大结果超过 50,000 字符落盘"]
    FMT --> O["追加 tool observation<br/>写回 messages"]
    AB --> O
    O --> C

    K -->|无工具调用| G{"Loop Guard<br/>必需工具是否漏调"}
    G -->|漏调且重试小于 2| RT["注入 retry user message<br/>要求直接调用必需工具"]
    RT --> C
    G -->|漏调且重试耗尽| W["追加不可靠警告"]
    W --> D
    G -->|未漏调| D["done event<br/>保存 chat log / scratchpad"]
    ML --> D

run_stream() 只产出统一的 RuntimeEvent（运行时事件）字典。TUI（终端图形界面）、headless wrapper（无界面兼容封装）、sub-agent（子智能体）和测试都消费这些事件，而不是各自重新实现模型调用和工具循环。

这张图有两个阅读重点：

模型前后都由确定性代码兜底：进入模型前先做记忆召回、旧结果压缩、上下文压缩；模型返回后再做工具分批、审批、后台任务、大结果落盘和错误回灌。
结束条件不是“模型说完了”：无工具调用时还要经过 Loop Guard（循环守卫）检查；漏调必需工具会注入 retry user message（纠偏用户消息），最多 2 次，仍失败才带警告结束。

主要事件：

事件	来源	用途
`text_delta`	Provider（模型适配层）流式文本	TUI（终端图形界面）逐行渲染
`thinking_delta` / `thinking`	reasoning chunk（推理片段）/ round（轮次）结束	推理展示和 scratchpad（运行追踪文件）记录
`tool_calls`	模型请求调用工具	清除临时流式文字，进入工具执行
`tool_start`	工具开始	展示工具名、参数、spinner（加载动画）
`tool_result` / `tool_error`	工具结束	回灌 observation，更新执行摘要
`model_start`	多轮工具调用的新一轮模型推理	恢复“思考中”状态
`compaction`	上下文被压缩	提示消息条数变化
`retry`	Loop Guard（循环守卫）触发	强制模型补调用必需工具
`usage`	Provider（模型适配层）token（模型令牌）统计	状态栏计费/用量
`done`	最终回答	保存 chat log（聊天日志），结束本轮

2. Provider（模型适配层）抽象

Provider（模型适配层）接口定义在 cli/providers/base.py：

class LLMProvider:
    def chat(self, messages, tools, system_prompt="") -> dict: ...
    def chat_stream(self, messages, tools, system_prompt="") -> Generator[dict, None, None]: ...
    @property
    def name(self) -> str: ...

Provider（模型适配层）的职责是把不同模型 SDK（软件开发工具包）的响应转换成统一 chunk（流式片段）：

text_delta：普通文本。
thinking_delta：DeepSeek 等模型返回的 reasoning（推理内容）。
tool_calls：标准化为 {"id", "name", "args"}。
usage：输入/输出 token（模型令牌），以及可用时的 cache read/write token（缓存读写令牌）。

当前 CLI（命令行）主要 provider（模型适配层）：

Provider（模型适配层）	文件	说明
Claude	`cli/providers/claude.py`	Claude tool_use / tool_result 双向转换
OpenAI-compatible（OpenAI 兼容接口）	`cli/providers/openai.py`	OpenAI、DeepSeek、Qwen、Kimi 等兼容端点
Gemini	`cli/providers/gemini.py`	Gemini function calling 适配
Fallback（故障切换）	`cli/providers/fallback.py`	限流、超时、服务端错误时切换备用 provider（模型适配层）
Routing（模型路由）	`cli/model_router.py`	按轮次复杂度在 heavy/light（强模型/轻模型）模型间路由

OpenAI-compatible provider（OpenAI 兼容模型适配层）有三类兼容处理：

首次调用携带 stream_options、tool_choice、frequency_penalty。
第三方端点不支持时逐步去掉不兼容参数。
对把工具调用输出成 <tool_call>...</tool_call> 文本的模型做兜底解析。

流式读取由 _iter_with_timeout() 包装：生产者 daemon thread（守护线程）负责读 stream（流式响应），主线程从 queue（队列）取 chunk（流式片段）；60 秒无新 chunk 就抛出超时，避免 TCP 半开连接把 TUI 卡死。

3. 工具注册与调度

CLI（命令行）工具系统在 cli/tools.py：

TOOL_SCHEMAS：给模型看的 JSON Schema（JSON 格式工具参数协议）。
ToolSpec：工具元数据，包括中文展示名、是否并发安全、是否需要确认、是否后台执行。
ToolRegistry：工具注册表，负责 provider（模型适配层）/ context（上下文）注入、确认回调、后台任务提交和实际执行。
ToolContext：工具上下文，跨工具共享 state、provider、registry、on_progress，也是 sub-agent（子智能体）委派的桥。

CLI（命令行）当前注册 19 个工具：

类型	工具
金融分析	`search_stock_by_name`、`analyze_stock`、`portfolio`、`get_market_overview`、`get_market_history`、`screen_stocks`、`generate_ai_report`、`generate_strategy_decision`、`query_history`、`run_backtest`
数据修改	`update_portfolio`
后台任务	`check_background_tasks`
Sub-agent（子智能体）委派	`delegate_to_research`、`delegate_to_analysis`、`delegate_to_trading`
本地工具	`exec_command`、`read_file`、`write_file`、`web_fetch`

调度策略：

concurrency_safe=True（并发安全）的工具可在同一轮连续工具调用中并行执行，最大 ThreadPoolExecutor(max_workers=5)（5 线程线程池）。
非并发安全工具串行执行，避免写操作、后台任务或外部副作用互相踩踏。
requires_approval=True（需要用户审批）的工具在 TUI 中弹确认框：允许一次、总是允许、修改后执行或拒绝。
background=True（后台执行）且 TUI 注入了 BackgroundTaskManager（后台任务管理器）时，工具立即返回 task_id（任务编号），实际任务在 daemon thread（守护线程）中运行。

当前并发安全工具：

search_stock_by_name、analyze_stock、portfolio、get_market_overview、get_market_history、query_history

当前高风险确认工具：

update_portfolio、exec_command、write_file

当前后台工具：

screen_stocks、generate_ai_report、generate_strategy_decision、run_backtest

4. 上下文管理与压缩

上下文压缩逻辑在 cli/compaction.py，TUI（终端图形界面）和 headless runtime（无界面运行时）共用。

触发规则：

根据模型名匹配 context window（上下文窗口），如 Claude 200K、Gemini 2 1M、OpenAI/Gemini 常见 128K、DeepSeek 64K。
COMPACT_RATIO = 0.25，达到窗口 25% 触发压缩。
最近上下文按 token budget（令牌预算）保留，默认最多保留 20K token，最少保留 4K token，并保证至少 4 条消息。
tail（尾部消息）边界不会从 tool 消息开始；如果 tail 中有 tool_call_id（工具调用编号），会向前扩展，把对应 assistant tool call（助手工具调用）一并纳入，避免孤儿工具结果。

压缩流程：

flowchart LR
    A["messages 超阈值"] --> B["按 token budget 切 head/tail"]
    B --> C["压缩前 memory flush"]
    C --> D["工具结果智能摘要"]
    D --> E["LLM 生成 500 字以内摘要"]
    E --> F["[对话摘要] + 接续确认 + tail"]

工具结果不会粗暴截断：

analyze_stock 保留 code（股票代码）、name（股票名称）、channel（通道）、phase（阶段）、trigger_signals（触发信号）、health（健康状态）等字段。
portfolio 保留 position_count（持仓数量）、free_cash（可用现金）、positions（持仓明细）或 diagnostics（诊断结果）。
通用结果保留 error、message、status、code、name、result。

每轮工具执行后，shrink_stale_tool_results() 会先压缩旧轮次的大 tool result（工具结果），保留最新一轮完整结果，减少多轮工具调用中的 token（模型令牌）污染。

超大工具结果写回模型前还会经过 cli/tool_results.py::format_tool_result_for_context()；超过阈值的内容会落盘到 ~/.wyckoff/tool-results/，上下文只保留引用、预览和结构化索引。

当前实际阈值：

常量	当前值	含义
`MAX_TOOL_RESULT_CHARS`	50,000	单次工具结果超过 5 万字符就落盘
`PREVIEW_CHARS`	2,000	上下文里保留的大结果预览长度
`SHRINK_THRESHOLD`	800	旧轮次工具结果超过 800 字符会被二次压缩

Web（网页端）也有上下文压缩，但它是 TypeScript（前端脚本语言）本地摘要：prepareChatMessagesForModel() 根据同样的 context-window（上下文窗口）/25% 口径构造 [读盘室对话摘要]，不调用 CLI compactor（命令行压缩器），也不写入 CLI（命令行）记忆。

5. 记忆系统

记忆系统在 cli/memory.py，只服务 CLI（命令行）/ TUI（终端图形界面）。

目标是记住稳定、可复用的信息，而不是把每天行情和临时买卖事实都塞进长期记忆。

自动抽取的 L1 原子记忆只有两类：

[偏好] → preference：投资风格、禁忌、操作习惯。
[决策] → decision：非显而易见的决策逻辑和原因。

明确不抽取：

具体买卖了哪只股票。
临时调仓事实。
当天市场状态。
工具调用细节。

分层记忆：

层级	类型	生成方式
L1	`preference` / `decision`	会话结束后从最近 40 条消息提取
L2	`scenario`	L1 数量达到阈值后刷新可复用场景
L3	`persona`	L1 数量达到阈值后刷新用户画像

写入时机：

TUI（终端图形界面）退出或保存时异步调用 save_session_summary()。
上下文压缩前调用 flush_memory_before_compaction()，避免旧上下文被摘要前丢失稳定偏好。
L1 记忆达到数量条件后调用 refresh_memory_layers() 生成 L2/L3。

召回流程：

flowchart TD
    U["当前用户消息"] --> C["抽取股票代码"]
    U --> K["抽取中文关键词"]
    U --> F["FTS5 全文检索"]
    C --> S["代码精确匹配"]
    K --> L["关键词 LIKE 匹配"]
    F --> R["混合排序 + 30 天半衰期"]
    S --> R
    L --> R
    R --> P["Persona / Preference 置顶"]
    P --> I["注入 <relevant-memories>"]

注入格式通过 prepend_memory_context() 把召回记忆包在 <relevant-memories>（相关记忆）中，再把当前用户消息包在 <current-user-message>（当前用户消息）中。这样模型可以参考长期偏好，但不会把记忆误当成当前任务进度。

每条记忆保留 source_ref=chat_log:<session_id>（来源引用）。CLI（命令行）可用 wyckoff memory trace <id> 回看来源，避免长期摘要变成不可验证黑盒。

容量控制在 integrations/local_db.py：preference 50 条、persona 5 条、scenario 20 条、session 50 条、fact 50 条、stock_opinion 30 条、decision 30 条、market_view 20 条。超出后按类型裁剪最旧记录；90 天以上的普通记忆会被清理，preference 和 persona 长期保留。

6. Loop Guard（循环守卫）与死循环保护

模型偶尔会只输出计划、不调用工具。cli/loop_guard.py 把部分数据型任务从 prompt（提示词）约束提升为运行时约束。

典型约束：

用户意图	必须工具
查看持仓	`portfolio(mode="view")`
持仓体检 / 诊断	`portfolio(mode="diagnose")`
上下文跟进“做一下体检”	结合最近消息判断仍需 `portfolio`

如果模型漏调必需工具，runtime（运行时）会注入 retry user message（纠偏用户消息），最多重试 2 次；仍失败则把警告前置到最终回答里。

当前实际阈值：

常量	当前值	含义
`MAX_TOOL_ROUNDS`	15	单轮用户请求最多 15 轮模型-工具往返
`MAX_INCOMPLETE_TOOL_RETRIES`	2	漏调必需工具时最多纠偏 2 次
`DOOM_LOOP_WINDOW`	6	死循环检测看最近 6 次工具调用
`DOOM_LOOP_THRESHOLD`	3	同工具同参数出现 3 次即判定疑似死循环
`DOOM_LOOP_EXEMPT`	`check_background_tasks`	后台任务状态查询允许重复

Doom-loop（死循环）防护用于阻止同一工具同参数反复调用：

精确匹配：最近 6 次调用中同一 (tool_name, args_hash) 出现 3 次。
模糊匹配：参数文本长度达到 50 字符后，3-gram Jaccard 相似度达到 0.8 的同工具调用出现 3 次。
check_background_tasks 这类轮询工具豁免。

触发后 runtime（运行时）会写入工具错误 observation（观察结果），并中止本轮剩余工具调用，避免模型把外部 API（应用程序接口）或本地任务打爆。

7. 后台任务

后台任务在 cli/background.py，由 TUI（终端图形界面）初始化并注入 ToolRegistry（工具注册表）。

适合耗时较长但不应该阻塞对话的工具：

screen_stocks：全市场漏斗。
generate_ai_report：AI 深度研报。
generate_strategy_decision：攻防决策。
run_backtest：策略回测。

执行方式：

flowchart TD
    A["模型调用 background tool"] --> B["ToolRegistry.submit"]
    B --> C["BackgroundTaskManager 后台任务管理器创建 task 任务"]
    C --> D["daemon thread 守护线程执行真实函数"]
    B --> E["立即返回 task_id 任务编号给模型"]
    D --> F["progress callback 进度回调更新 TUI 终端图形界面面板"]
    D --> G["on_complete 完成回调注入通知"]

任务内部可通过 cli.progress 上报 stage（阶段）、detail（细节）、progress（进度）。TUI 顶部的 BackgroundTaskPanel（后台任务面板）展示活跃任务，用户可以继续提问；任务完成后会通过 callback（回调函数）通知当前会话。

8. Sub-Agent 编排

Sub-agent（子智能体）基础设施在 cli/sub_agents.py，当前只有 CLI（命令行）/ TUI（终端图形界面）可用。

三个内置角色：

Sub-agent（子智能体）	职责	工具子集
`research`	数据收集、全市场扫描、信号、复盘、回测	`search_stock_by_name`、`analyze_stock`、`get_market_overview`、`get_market_history`、`query_history`、`screen_stocks`、`run_backtest`、`check_background_tasks`
`analysis`	个股诊断、持仓体检、AI 研报	`analyze_stock`、`portfolio`、`get_market_overview`、`get_market_history`、`generate_ai_report`
`trading`	去留决策、攻防指令、调仓执行	`portfolio`、`update_portfolio`、`generate_strategy_decision`、`analyze_stock`、`get_market_overview`、`get_market_history`

主 Agent 通过 delegate_to_research、delegate_to_analysis、delegate_to_trading 调用子 Agent。

实现要点：

SubAgentToolProxy（子智能体工具代理）只暴露允许的 schemas（工具定义），并在执行时拒绝越权工具。
每个 sub-agent（子智能体）启动自己的 AgentRuntime mini loop（小型循环），使用独立 system prompt（系统提示词）和上下文。
子 Agent 使用同一个 provider（模型适配层）和 ToolRegistry（工具注册表），所以能共享登录态、数据源和确认机制。
TUI（终端图形界面）通过 tool_context.on_progress 转发子 Agent（子智能体）的 text_delta、tool_start、tool_result、done 事件，以灰色斜体展示执行进度。

这个设计把“主 Agent 负责路由、规划、预算和最终回答”和“子 Agent 专注单类任务”拆开，减少复杂投研任务把主会话上下文搅乱。

9. Scratchpad（运行追踪文件）与可观测性

cli/scratchpad.py 为每个 CLI（命令行）/ TUI（终端图形界面）turn（对话轮次）写一份 JSONL trace（逐行 JSON 运行轨迹）到 ~/.wyckoff/scratchpad/。

记录内容：

事件	字段
`init`	用户输入、session_id
`thinking`	模型 reasoning（推理内容）
`tool_result`	工具名、参数、结果、耗时、状态
`compaction`	压缩前后消息数
`final`	最终回复、token、耗时
`error`	异常信息

所有明显敏感字段会脱敏：api_key、token、password、secret、authorization、cookie。

Scratchpad（运行追踪文件）独立于 SQLite chat log（本地聊天日志）：即使中途崩溃、工具超时或长任务异常，也能留下足够证据复盘“模型为什么这样回答”。

10. Web（网页端）Agent（智能体）

Web（网页端）核心文件：web/apps/web/src/lib/chat-agent.ts。

它不是 CLI Runtime（命令行智能体运行时）的移植，而是面向 CF Pages（Cloudflare Pages 边缘页面）的独立实现：

使用 streamText()（流式文本生成）做多步工具调用。
stopWhen(stepCountIs(10))（达到 10 步就停止）限制最大工具轮数。
自己维护 StepInfo（步骤信息），向前端回调 onStep、onTextDelta、onFinish、onError。
使用 prepareChatMessagesForModel() 做本地摘要式上下文压缩。
通过 /api/llm-proxy 代理模型请求，统一 base_url（模型服务地址）、安全校验和错误处理。
用 buildReasoningFetch() 解析 SSE（服务端事件流）中的 reasoning_content（推理内容），并在下一轮补回 assistant message（助手消息），兼容 DeepSeek 等模型的 thinking mode（思考模式）。

Web（网页端）工具当前包括 13 个：

search_stock、view_portfolio、market_overview、market_history、query_recommendations、query_tail_buy、plan_portfolio_update、execute_portfolio_update、analyze_stock、screen_stocks、generate_ai_report、generate_strategy_decision、intraday_analysis

与 CLI（命令行）的差异：

Web（网页端）没有本地 shell/file/web_fetch（命令行、文件、网页抓取）工具。
Web（网页端）没有 CLI SQLite（命令行本地轻量数据库）记忆和 scratchpad（运行追踪文件）。
Web（网页端）调仓是 plan_portfolio_update + execute_portfolio_update 两步，靠 system prompt（系统提示词）和工具分离做确认边界。
Web（网页端）的 screen_stocks 是读取最新漏斗结果，不是在用户请求时启动 CLI（命令行）后台漏斗。

11. MCP Server（模型上下文协议服务）

MCP（模型上下文协议）入口：mcp_server.py。

MCP Server（模型上下文协议服务）使用 FastMCP("wyckoff") 注册工具，外部 Agent（智能体）通过 stdio（标准输入输出）调用。

当前 MCP（模型上下文协议）工具有三类：

权限层	工具
Tier 1（第一权限层）：本地历史	`query_history`
Tier 2（第二权限层）：行情/引擎	`search_stock_by_name`、`analyze_stock`、`get_market_overview`、`screen_stocks`、`run_backtest`、`market_regime`、`wyckoff_diagnose`、`intraday_analysis`、`intraday_rescue_check`、`run_funnel_simulation`
Tier 3（第三权限层）：用户数据/LLM（大语言模型）	`portfolio`、`update_portfolio`、`generate_ai_report`、`generate_strategy_decision`

MCP（模型上下文协议）会从环境变量或本地 CLI（命令行）登录态构造 ToolContext（工具上下文）：

SUPABASE_USER_ID
SUPABASE_ACCESS_TOKEN
SUPABASE_REFRESH_TOKEN

与 CLI（命令行）/ Web（网页端）的关键区别是：MCP 自身不做 memory（记忆）、compaction（上下文压缩）、retry（纠偏重试）、sub-agent（子智能体）或后台面板。它只返回一次工具调用结果，复杂编排由 Claude Code、Cursor 等 MCP（模型上下文协议）客户端完成。

12. Skills（技能模板）与 Prompt（提示词）模板

Skills（技能模板）在 cli/skills.py，本质是“预设 user message（用户消息）模板”，执行后仍走完整 CLI Agent Runtime（命令行智能体运行时）。

内置 Skills：

命令	作用
`/screen`	全市场漏斗筛选
`/checkup`	持仓健康体检
`/report`	AI 深度研报
`/strategy`	攻守决策
`/backtest`	策略回测

用户可以在 ~/.wyckoff/skills/*.md 中新增 skill（技能模板）。支持 front matter（文件头元数据）：

---
name: dcf
description: DCF 估值分析
---
请对 {user_input} 进行 DCF 估值分析。

Prompt（提示词）模板在 cli/prompt_templates.py，用于更结构化的投研任务；TUI（终端图形界面）/help 同时展示内置命令、prompt 模板和 skills（技能模板）。

13. LLM 智能路由

cli/model_router.py 提供 heavy/light（强模型/轻模型）模型路由。

分类规则：

判为 heavy（强模型）	条件
多工具结果待合成	最近消息中 `tool` 结果数量 >= 2
投研关键词	分析、诊断、策略、研报、决策、回测、漏斗、筛选、持仓、复盘等
长消息	最后一条用户消息超过 80 字
缺少用户消息	保守默认 heavy

其余简单确认、闲聊和短问题可走 light（轻模型）模型。RoutingProvider（路由模型适配层）实现同一个 LLMProvider（大语言模型适配接口）接口，所以 AgentRuntime（智能体运行时）不需要知道当前轮次到底选了哪个 provider（模型适配层）。

设计原则总结

原则	当前实现
Runtime（运行时）统一	CLI/TUI/sub-agent/test（命令行/终端图形界面/子智能体/测试）共享 `AgentRuntime` 事件循环
通道分层	Web（网页端）、CLI（命令行）、MCP（模型上下文协议）共享工具能力，但不强行共享同一运行时
数据先行	Loop Guard（循环守卫）把部分工具调用从 prompt（提示词）约束提升为状态机约束
工具可治理	schema、确认、并发安全、后台执行都在 `ToolSpec` / `ToolRegistry` 中声明
上下文可控	token budget（令牌预算）压缩、旧工具结果摘要、超大结果落盘
记忆克制	只沉淀稳定偏好和决策逻辑，不把临时行情写成长记忆
任务可拆	research（研究）/ analysis（分析）/ trading（交易）sub-agent 用工具代理隔离能力边界
运行可追溯	scratchpad（运行追踪）+ chat log（聊天日志）+ source_ref（来源引用）支撑问题复盘
Provider（模型适配层）无关	Claude / OpenAI-compatible（OpenAI 兼容接口）/ Gemini / fallback（故障切换）/ routing（模型路由）都收敛到同一接口
失败可恢复	超时、fallback（故障切换）、retry（纠偏重试）、doom-loop（死循环）中止和后台任务状态共同兜底

11_Tech_Agent_Design

Agent 设计专题

英文术语速查

0. 当前实现边界

1. CLI Agent Runtime（命令行智能体运行时）

2. Provider（模型适配层）抽象

3. 工具注册与调度

4. 上下文管理与压缩

5. 记忆系统

6. Loop Guard（循环守卫）与死循环保护

7. 后台任务

8. Sub-Agent 编排

9. Scratchpad（运行追踪文件）与可观测性

10. Web（网页端）Agent（智能体）

11. MCP Server（模型上下文协议服务）

12. Skills（技能模板）与 Prompt（提示词）模板

13. LLM 智能路由

设计原则总结

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wyckoff-Analysis Wiki

Agent 工作机制 (9 篇)

Clone this wiki locally