第三方参考项目架构复核
martinpmm/Finclaw 是一个总线驱动的多渠道金融 Agent runtime。
本可视化产物基于治理库中的 martinpmm/Finclaw 更新报告生成,聚焦运行时结构、 Gateway 控制流、扩展边界、安全风险,以及可转译到本项目 FinClaw 的工程判断。
一句话判断
不是单点问答机器人
它由 MessageBus、AgentLoop、Tool Registry、Provider、Session/Context 和 Channel adapters 共同构成。
是长期认知对象参考
watchlist、thesis、agent opinion、heartbeat 和 report 能支撑研究跟进与认知刷新。
不能直接复制 runtime 权限
shell、spawn、provider fallback 和宽权限工具需要在本项目中默认收窄。
高层运行时地图
渠道层
用户 / 聊天渠道
Telegram、WhatsApp、Discord、Slack、terminal 等入口。
Channel adapters
把平台事件转换为统一的 InboundMessage。
WhatsApp bridge
Python WebSocket client 连接 Node/Baileys bridge。
核心运行时
MessageBus
inbound / outbound async queues 解耦渠道 IO 与 Agent reasoning。
AgentLoop
消费消息、构建上下文、调用 Provider、执行工具、发布响应。
Session / Memory / Context
组合历史、memory slices、bootstrap docs 和 skills。
能力与主动性
LLM Provider registry
统一 Provider 抽象、选择与模型路由。
Tool Registry
集中注册金融、文件、shell、web、report、portfolio 等工具。
Cron / Heartbeat
用于主动任务、研究跟进和认知刷新判断。
Gateway 控制流
1
用户消息
渠道适配器接收平台事件。
2
入站总线
写入 MessageBus inbound queue。
3
上下文构建
加载 session history、memory、skills 和启动指令。
4
Provider 调用
LLM 返回最终文本或 tool calls。
5
工具执行
Tool Registry 分发并回填工具结果。
6
出站总线
AgentLoop 发布 OutboundMessage。
7
渠道投递
适配器将响应送回用户。
运行模式
finclaw gateway
长驻服务模式,组合渠道、AgentLoop、cron、heartbeat 和主动能力。
finclaw agent
交互式或单条消息处理模式。
可学习边界
MessageBus + AgentLoop
适合作为长期认知刷新和多渠道投递的边界组合。
Context + Memory
与 watchlist、thesis、event memory 和 report 模板互相支撑。
必须收窄边界
Shell / spawn / file tools
金融认知产品不应默认继承宽权限通用 agent runtime。
交易执行隔离
下单、调仓、链上交易和账户动作仍应留在执行系统边界之外。
风险矩阵
Critical / High
TLS verify=false fallback
Provider retry path 不应吸收为可接受模式;未来接入必须 fail closed。
Critical / High
进程全局 Provider 状态
LiteLLM api_base 与 os.environ 变更可能跨 session/provider 泄漏。
Critical / High
Shell 执行保护不足
shell-interpreted execution + denylist guard 仍保留绕过面。
Medium
全局处理锁
可能串行化无关 session,造成长期任务或多渠道处理的队首阻塞。
Medium
无界队列
峰值流量或下游故障可能把 inbound/outbound queue 变成内存压力。
Medium
架构测试不足
Provider fallback、shell guard、backpressure 和 reconnect 缺少显性质量门禁。
转译到本项目 FinClaw 的判断
可以吸收
长期认知对象、研究跟进、主动监控、report template、heartbeat、cron、memory DB、Provider registry 和多渠道 delivery 经验。
不能直接吸收
宽权限 shell/spawn/file tools、直接交易动作、账户操作、链上交易、下单、调仓和无授权执行系统调用。
应作为认知刷新调度
Heartbeat / Cron 应服务 Research Follow-up、Watch Questions、事实变化和风险变化提示。
不应提前扩张交互面
WhatsApp / chat bridge 证明多渠道可行,但第一阶段不应因参考项目存在多渠道而提前产品化。
工程演进路线
阶段 1
安全加固
- 移除 TLS verify=false fallback。
- 收窄 shell execution。
- 默认开启 workspace restriction。
阶段 2
可靠性与扩展性
- 从全局锁转向 session/thread 级并发控制。
- 加入 bounded queues 和 backpressure。
- 为 channel/bridge 加 circuit breaker。
阶段 3
可运维性
- 暴露 queue depth、tool latency、provider latency。
- 增加 gateway/bridge health checks。
- 统一服务路径日志策略。
阶段 4
质量门禁
- 测试 provider security fallback。
- 测试 shell guard 和 queue/backpressure。
- 测试 channel reconnect 行为。
源材料
- FinClaw 外部参考分析目录
- martinpmm/Finclaw 深度分析报告
- martinpmm/Finclaw 参考仓/ARCHITECTURE.md
- martinpmm/Finclaw 参考仓/ARCHITECTURE_VISUAL.html
归档判断
当前继续使用单一主报告承载 martinpmm/Finclaw 的产品能力评估与架构复核。 只有当后续出现多轮运行实测、版本对比、代码审计或截图型视觉材料时, 再拆分为项目子目录与独立的 product-evaluation、runtime-architecture、risk-review 和 version-notes。