11_09_Platform_Channels

(九) 多端应用适配 (Web & MCP & Skills)

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（模型服务地址）、安全校验和错误处理。
• 用 buildProxiedFetch() / wrapReasoningStream() 解析 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（模型上下文协议）客户端完成。

后续迭代计划：统一工具定义

当前工具定义分散在三处：MCP Server（mcp_server.py）、CLI 工具注册（cli/tools.py）和 Web Agent 工具（web/apps/api/src/routes/chat.ts）。后续目标不是把所有运行时都改成 MCP，而是抽出统一的 ToolDefinition（工具定义）作为内部唯一真源：

1. 统一工具命名、描述、输入 schema（参数协议）、输出 schema（返回协议）和安全元数据。
2. MCP Server 只作为一个 adapter（适配器），把统一工具定义暴露成 MCP tools。
3. CLI provider（OpenAI / Claude / Gemini）从同一份定义生成各自需要的 function/tool schema。
4. Web Agent 从同一份定义生成 AI SDK tool({ inputSchema })。
5. README / Wiki 的工具列表也从统一定义生成，避免文档、CLI、Web、MCP 四处漂移。

这样 MCP 是对外协议，ToolDefinition 是内部工具真源；多端共享同一套工具语义，但仍保留各自运行时的差异能力。

---

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

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

技能延迟加载 (Skills Lazy Loading)

为了控制初始 System Prompt 的体积，避免模型因信息过载而分心，同时也为了最大化 Prompt Caching 的命中率，Wyckoff Agent 采用了 技能延迟加载（Lazy Loading） 的设计：

1. Skills 列表动态注入 ：在每次 AgentRuntime.run_stream 启动时，系统只会把已加载的内置与用户自定义 Skills 的 名称和简短描述以 `<system-reminder>` 块的形式注入到系统提示词底部。
2. execute_skill 延迟展开：完整的 Skill 指令 Markdown 不会预置入 Context。当模型判定用户意图匹配某个 Skill（如 /checkup）时，它会主动调用 execute_skill 工具。此时，系统读取 Skill 对应文件的详细 instructions，并作为 tool_result 结果在下一轮返回给模型。这不仅节约了海量的前期输入 Token，还极大地加快了冷启动响应速度。

内置 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. 模型元数据与故障切换

当前 CLI（命令行）的模型选择由用户配置决定：默认模型负责正常对话，fallback（备用模型）只在可恢复错误时接管。

模型配置入口：

命令	作用
wyckoff model add	交互式添加 provider（模型供应商）、API key（接口密钥）、model（模型名）和 base_url（模型服务地址）
`wyckoff model default <id>`	设置默认模型
`wyckoff model fallback <id>`	设置 fallback（备用模型）
`wyckoff model cost <id> --input-per-1m N --output-per-1m N --context-window N`	配置成本和 context window（上下文窗口）元数据
wyckoff model usage --days N	汇总最近 N 天的本地模型用量和估算成本

模型元数据来源：

1. 用户显式配置优先，例如 context_window、输入/输出 token（令牌）单价。
2. 未配置 context_window 时，cli/model_metadata.py 按模型名推断常见上下文窗口。
3. 未知模型按 64K token（令牌）上下文窗口处理，保证压缩阈值和 UI（用户界面）展示都有保守默认值。

FallbackProvider（故障切换模型适配层）的切换边界也比较明确：

• 会切换：限流、超时、网络连接错误、服务端错误。
• 不切换：API key（接口密钥）错误、模型名错误、参数不兼容等配置问题。
• 切换后会更新当前 active provider（活跃模型适配层），runtime（运行时）读取到的 context_window 也跟随当前活跃模型。

这样的设计把“模型可用性恢复”收敛在 fallback（故障切换）里；不同任务使用哪个模型由用户在默认模型和备用模型配置中显式决定。

---

设计原则总结

原则	当前实现
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（故障切换）都收敛到同一接口
失败可恢复	超时、fallback（故障切换）、retry（纠偏重试）、doom-loop（死循环）中止和后台任务状态共同兜底

---

返回 系列索引