TRUEFIX STUDIO / 使用指南

完成安装和连接，
从安全模式开始。

TrueFix 可以连接你选择的券商、交易所、行情数据和 AI 服务。建议先做研究或使用模拟模式，了解权限后再连接真实账户。

当前发布状态产品源码仓库仍为私有；公开 Nightly 安装包由 TrueFix 官方 GitHub Releases 页面提供。请勿从非官方来源获取程序。

01 / BEFORE YOU START

开始之前

TrueFix Studio 是一个用于市场研究、策略测试和交易前确认的桌面应用。它不托管资金，也不会替代你的券商或交易所。请安装官方 Nightly 版本，然后只连接你真正需要的服务。

分清模拟和实盘

Live 会使用真实资金；Paper、Testnet、Demo 和 Simulator 都是测试模式。请把测试连接和实盘连接分开，并使用容易辨认的名称。

先用模拟资金

先在测试模式查看行情、账户和完整下单流程。确认每一步都能理解后，再考虑实盘。

只开放必要权限

每个连接只授予所需的最小权限。不要把 API Key 或密码放进 AI 对话、截图或支持消息。

重要TrueFix Studio 仍处于首版发布前。它不是投资建议，也不会替你判断交易是否适合；所有实盘动作都应由账户所有者核验。

02 / FIRST RUN

第一次打开后的 15 分钟

1
打开或新建工作区
工作区会记住上次选择的市场和面板布局。如果恢复失败，TrueFix 会打开安全的默认布局。
2
查看顶部状态
某项服务暂时不可用时，仍可以进入应用。使用该服务前，请等待它恢复或查看页面给出的错误说明。
3
连接一个测试服务
先连接一项行情服务或模拟交易服务。搜索一个交易品种，确认价格来自哪里，再创建一笔不发送的订单。

macOS 未签名版本如果官方预发布版本因尚未签名而被 macOS 拦截，请先把应用移入“应用程序”，再在“终端”运行下面的命令。仅对从 TrueFix 官方 Release 下载的应用使用；该命令会移除这个应用包的隔离属性。

xattr -cr "/Applications/TrueFix Studio.app"

后文会出现的产品术语

Provider（服务商）指券商、交易所、数据服务或 AI 服务；ClientInstance（连接实例）指你保存的一套具体连接；Environment（环境）指这套连接属于测试还是实盘。应用界面可能使用这些英文名称，因此高级章节会在中文说明后保留对应英文。

03 / 连接服务

连接券商、交易所或行情服务

在“连接管理”点击“打开完整连接中心”，进入 Provider Centre。使用“Add monitoring ClientInstance”表单填写实例 ID、Provider slug、显示名称、市场、产品范围和实际环境；连接参数填入页面的“Connection JSON”输入框。选择 Historical／Realtime，按需勾选“Connect after saving”，点击“Save monitoring ClientInstance”。该表单用于行情监控，不会创建交易权限。

配置项由 Provider 自有 schema 校验，保存成功后才重建实例。
Secret 可写但不回显原值，返回页面只显示是否已配置。
“已连接”不等于“可以交易”，还需核验 capability、entitlement、账户、精确标的映射、环境与健康证据。
闭市、断线、未授权、配置错误与 rate limit 是不同状态。

保存前后分别检查什么

同一家 Provider 的 Paper 与 Live 应建立不同 ClientInstance，并使用容易辨认的名称，例如 broker-paper-us 与 broker-live-us。不要通过修改一个实例在环境间来回切换，以免把账户和路由上下文混在一起。

04 / MARKET CONTEXT

选择标的与行情来源

在全局搜索中选择 canonical Instrument。TrueFix 会为历史行情、实时行情和交易分别解析候选路由，三者互相独立。

每个来源旁的 Provider、ClientInstance、质量与时间戳都应保持可见。缺少精确 mapping 时系统会拒绝该路由，不会把相似 symbol 当作同一标的。

05 / REVIEW & RISK

下单、Review 与 RiskGuard

Order Draft→Exact Route→Backend Review→RiskGuard→Explicit Submit→Reconcile

1
选择账户
确认 Provider、ClientInstance、Account 与 Environment，无资格账户不可选。
2
填写订单
Order Type、TIF、数量、价格和条件字段来自实际 OrderSchema。
3
执行 Review
核对标的、方向、价格、数量、费用假设、交易规则与数据新鲜度。字段变化会使旧 token 失效。
4
RiskGuard 通过后明确提交
提交使用确定性 client order ID 与幂等边界；结果未知时只查询恢复，绝不重新提交。

实盘警告提交前再次确认 Environment。Kill Switch 恢复、页面刷新或网络重连都不会自动重新提交订单。

提交之后、撤单与改单

提交成功后到 Orders 查看 acknowledgement 与 lifecycle；成交应在 Fills 中出现，并关联相同的账户和 ClientInstance。
Cancel / Amend 必须引用当前权威订单 revision；状态已经变化时先刷新，不用旧页面状态覆盖 Provider。
请求超时进入 uncertain 时，保留 client order ID 并执行 reconciliation。未知不是失败，也不是再次提交的理由。
外部订单与应用订单分区显示。无法映射的 Provider 订单保留原身份，不会伪装成 TrueFix 创建的订单。

Kill Switch 怎么用

Kill Switch 是后端风控状态，不是页面装饰。触发前记录 scope 和 reason；触发后确认受影响账户与策略停止产生新交易动作。解除前应处理风险事件、未决订单和 Provider 状态，并重新 Review 新订单。解除不会恢复、重放或自动提交先前意图。

06 / PORTFOLIO

账户、持仓、订单与成交

Portfolio 读取权威交易投影，可按 Provider、ClientInstance、账户和环境筛选。应用订单与外部/未知订单严格分区；普通页面刷新读取本地投影，只有权威刷新才触发 Provider reconcile。

缺少一致 FX revision 时，不同币种不直接相加。
partial 或 stale 估值保留状态，不会被表达成完整权益。
Provider 下线或环境切换后，旧账户域不再参与当前操作。

07 / INTELLIGENCE

从 Observation 到 Evidence

Intelligence 工作区展示 Observation、Signal、Composite Index、Evidence 与历史 Replay。查看 current、baseline、deviation、confidence、freshness 和来源多样性，并通过 Evidence timeline 回到原始证据。

Signal 是可审计的分析结果，不等于已证实事实，也不会直接创建订单。

打开原尺寸图片 ↗

08 / AGENT

配置并使用 Agent

Agent 是受限的操作助手，不是拥有账户权限的自动交易机器人。它通过 TrueFix 的受权工具读取标的、行情、新闻、Signal、账户与 Quant 状态；涉及交易时只能创建可审核的提案。测试版本之间可用工具可能不同，请以运行时间线中显示的授权和状态为准。

A. 先配置一个模型

在 Desktop 的“设置 → AI”表单中填写 API Key 和模型 ID，并点击保存。“模型请求参数”中的 JSON 是界面输入框的内容，由应用负责保存。

1
打开设置 → AI
在“AI 交易 Agent”中选择“添加”。
2
填写连接
设置显示名称、Provider（OpenAI / Anthropic / Google / Custom）、API Key、模型 ID；只有兼容网关才需要填写 Base URL。
3
检查额外参数
“模型请求参数”必须是 JSON 对象，例如 {"enable_thinking": false}。不需要时保留 {}，不要粘贴 Secret。
4
启用并保存
编辑已有 Agent 时，API Key 留空表示保留原密钥。保存后确认状态点为启用。

密钥边界请在 Desktop 的“设置 → AI”界面填写 API Key。不要把它放进 Agent 对话、Web URL、截图或工单；浏览器也不会读取 Provider 或模型原始密钥。

B. 完成一次安全会话

1
打开 Agent
在 Desktop、Web Desktop 或 H5 底部命令栏打开 Agent，新建会话并选择已启用模型。
2
把范围说清楚
在问题中给出标的、市场、时间范围、数据来源偏好和目标。涉及账户时明确 Environment；先用 Simulator 或 Testnet。
3
检查运行时间线
确认 admission、model、tool、approval 和 final 状态，以及工具结果的 Provider、ClientInstance、时间戳、freshness 与 evidence。
4
审核，而不是盲目接受
区分事实、推断和相关性。遇到 stale、degraded、工具拒绝或来源不足时，缩小问题或先修复数据连接。
5
处理交易提案
核对 Approval Card 中的标的、方向、数量、账户、环境、期限与证据。批准后仍需经过 Review、RiskGuard 和明确提交；拒绝或过期不会下单。

研究比较 AAPL 最近 20 个交易日的波动与成交量，列出数据来源、时间戳和不能确认的部分。

账户

只读取 Paper 账户：汇总持仓集中度、未成交订单和今日已实现/未实现盈亏，不要发起交易。

交易演练

在 Simulator 中为这个标的拟一笔限价单；先展示 route、规则、风险与审批卡，不要替我批准。

Agent 边界Agent 没有任意 Shell、原生插件或直接 Provider SDK 权限；首版不允许无人值守的 Live 自动交易。新闻或网页里的指令不是操作授权。

09 / QUANT & AUTOMATION

确定性运行、回放与 Trigger

Quant 策略基于固定数据、交易日历、费用、滑点、seed 与 revision 运行或回放。Agent 可以协助起草 declarative Trigger，但必须先验证、历史回放和明确批准，才能部署。

Draft→Validate→Replay→Approve→Deploy→Pause / Retire

选择精确的 canonical Instrument、Provider、ClientInstance 与数据类型，不能只写相似 symbol。
每个 Revision 都保留不可变输入、资源预算、输出和 evidence cursor；失败的新版本不会替换正在运行的版本。
Trigger 先持久化结果再唤醒 Agent；模型变慢或不可用不会阻塞市场、Quant 或执行热路径。
关闭 Desktop/Web 不会停止 headless Runtime；重开页面只恢复状态投影。

打开原尺寸图片 ↗

10 / WEB GATEWAY & ACME

配置浏览器访问与 HTTPS

在 Desktop 打开“设置 → Web Gateway”，通过页面表单配置浏览器访问。根据本机或远程访问方式，填写下文对应的监听、域名和 HTTPS 选项，勾选“启用”后点击“保存并应用”。应用会保存并应用这些设置；启停 Gateway 不会停止 Desktop 的 Kernel 或 Provider 连接。DNS 记录和防火墙规则需在域名服务商或网络管理界面中设置。

A. 本机访问：最快的验证方式

1
设置 → Web Gateway
在此页面点击“随机生成密码”，立即复制并保存；或者在“设置自己的访问密码”中输入至少 12 个字符，再点击“修改访问密码”。这两个操作会撤销现有 Web/H5 会话。“保存并应用”只保存网关配置，不会同时修改密码。
2
只监听 loopback
在“HTTPS 证书”选择“本机 HTTP”，将“监听地址”设为 127.0.0.1 或 ::1，填写服务端口，勾选“启用”，点击“保存并应用”，然后打开页面显示的访问地址。
3
打开状态栏给出的 URL
输入访问密码。需要跨重启恢复时勾选“保持登录”；长期登录只延长身份会话，不增加交易权限。

B. 远程访问：先准备域名

1
解析域名
把 studio.example.com 的 A/AAAA 指向 Gateway 公网地址；如果 IPv6 不能到达服务，先移除错误 AAAA。
2
填写公开入口
允许域名 只写 DNS 名称，不带协议、端口或路径；公开访问地址 写最终的完整 https:// URL。域名 allowlist 不接受通配符。
3
选择 TLS
使用已有证书时，在“HTTPS 证书”选择“自有证书”，在页面填写“证书 PEM 路径”和“私钥 PEM 路径”。使用自动证书时，选择“Let’s Encrypt 自动证书”，填写 ACME 邮箱，并在“ACME 验证方式”中选择 HTTP-01、TLS-ALPN-01 或 DNS-01；DNS-01 的 Cloudflare Zone ID 和 API Token 也在此表单填写。

C. 推荐的 ACME 上线顺序

1
在“设置 → Web Gateway”将“HTTPS 证书”设为“Let’s Encrypt 自动证书”。
2
在“允许域名”填写 studio.example.com，在“公开访问地址”填写 https://studio.example.com。
3
在“ACME Directory”输入 https://acme-staging-v02.api.letsencrypt.org/directory，填写 ACME 邮箱并选择验证方式及所需字段。
4
勾选“启用”，点击“保存并应用”，在页面检查运行状态和证书状态。Staging 证书仅用于测试，浏览器不信任是正常现象。
5
验证成功后，在同一“ACME Directory”输入框改为 https://acme-v02.api.letsencrypt.org/directory，再点击“保存并应用”，核对颁发者、域名和到期时间。

Staging 证书不会被浏览器信任，它只用于演练签发和续期。HTTP-01 的公网 80 必须保留原始 /.well-known/acme-challenge/* 路径；DNS-01 只使用目标 Zone 的最小 DNS:Edit Token，不使用 Global API Key。

反向代理只有确切的代理 IP 才能加入可信反向代理 IP。来自非可信连接的 Forwarded / X-Forwarded-* 会被拒绝并审计。不要把 Provider 凭据、登录密码、Cookie 或 Token 写进 URL 和代理日志。

不会降级ACME 失败时 Gateway 不会退回公网明文 HTTP。续期失败会继续使用最后一张有效证书；进入到期安全窗口后会停止远程 HTTPS。先修复 DNS、端口或 Directory，再重新 “保存并应用”。

D. 会话、设备与工作区

Access Token 短期存在；勾选“保持登录”时由 HttpOnly Refresh Cookie 轮换恢复。它不会进入 JavaScript、URL 或访问日志。
在 Desktop 设置页查看并撤销单个 Web 设备。注销、全部注销、轮换访问密码或关闭 Gateway 会撤销相应会话。
浏览器只访问登录时选择的 workspace。需要指定时可用 ?workspace=<id>；省略时使用 main-workspace。
怀疑密码泄露时重新生成。新密码会撤销现有 Web 会话，但不会停止健康的行情、交易 Kernel 或 Provider 连接。

11 / OPERATIONS & AUDIT

运维、日志与审计

Operations 用于回答“什么时候发生了什么、由谁发起、影响到哪里”。Logs、Audit、Activity、Health 与 Incident 含义不同：日志可以轮转，交易与安全审计是耐久记录，Health 需要看时间戳，不能用“没有新日志”推导系统健康。

提交问题报告前

1
记录时间和环境
写明显示时区、Environment、Provider 与 ClientInstance；账户只保留脱敏尾号。
2
复制稳定证据
保留错误码、correlation ID、order/client order ID、revision 和 freshness，不复制 API Key、Cookie 或完整账户号。
3
说明期望与实际
列出可重复步骤，并说明是否涉及 Live、是否已经出现外部订单或资金后果。

macOS 日志主日志与 Web 访问日志位于 ~/Library/Application Support/truefix-studio/logs/，按日期滚动。访问日志含 IP 与 User-Agent，导出和保留应遵循最小化原则；发送前再次检查脱敏。

12 / STATUS GLOSSARY

看懂状态，不把未知当成零

Loading

正在获取投影；保持原有内容或骨架，不代表失败。

Empty

权威查询成功，当前确实没有记录。

Unavailable

能力、权限、映射或服务不存在，不能执行该动作。

Stale

有 last-good 数据，但超过新鲜度阈值；查看 as-of 时间。

Degraded

部分来源或 facet 失败，仍可使用明确标出的剩余能力。

Rejected

请求被 schema、权限、规则或 RiskGuard 明确拒绝。

Reconciling

正在与 Provider 权威状态对账，保留现有投影等待确认。

Uncertain

Provider 可能已接收请求但响应未知；只能查询恢复，不能重试提交。

每个状态都应同时查看 source、as-of、revision、stable code。同一页面的一项 stale 不等于整个系统不可用；同样，一个绿色连接点也不证明账户、标的和交易路由已满足条件。

13 / ARCHITECTURE

架构与数据边界

DesktopWebAI ToolsHeadless Quant

CANONICAL APPLICATION CONTRACTSInstrument · Market Data · Trading · Risk · IntelligencePROVIDER-OWNED ADAPTERS + RUNTIME EVIDENCE

Market DataBroker / ExchangeSignal SourcesFIX

浏览器不是标的、账户、订单、行情、风险或 AI/Quant 的权威所有者。所有入口共享 canonical contracts，并保留原始 adapter provenance。界面不补造缺失数据、不跨 Provider 静默混源，也不按 Provider 名称写死能力。

14 / TROUBLESHOOTING

常见问题

Agent 列表为空或无法发送

回到“设置 → AI”，确认至少一个 Agent 已保存并启用，API Key、模型 ID 与可选 Base URL 匹配。自定义网关还要确认请求参数是合法 JSON 对象。

Agent 工具被拒绝或一直等待审批

检查工具 grant、账户/标的范围与期限。交易类 submit、cancel、replace 必须由 owner 明确审批；授权过期、参数变化或 Kill Switch 都会 fail closed。

Provider 显示已连接，但不能交易

依次检查 Environment、交易 capability、entitlement、账户状态、精确 Instrument mapping、TradingRules 与 freshness。

能看到历史 K 线，但没有实时报价

Historical 与 Realtime 是独立 facet。检查实时来源、订阅权限、source health 和首个 Tick 是否到达。

提交超时，不确定订单是否成功

保留当前 client order ID，通过 Orders / Reconciliation 查询恢复，不要重新点击提交。

远程 Web 打不开

先看 Gateway 的 configured / effective 状态与 last_error，再检查监听地址、业务端口、A/AAAA、防火墙和 TLS。HTTP-01 检查公网 80；TLS-ALPN-01 检查公网 443 是否直达；DNS-01 检查 Zone、Token 与 TXT 传播。

证书签发成功但浏览器不信任

确认已经从 staging 切到 production，访问主机在证书 SAN 中，客户端时间正确，反向代理没有继续返回旧证书。

页面显示 stale / unavailable / degraded

查看受影响的 facet 与时间戳。last-good 数据不代表仍然新鲜，查询失败也不等同于空结果。

完成安装和连接，从安全模式开始。

开始之前

分清模拟和实盘

先用模拟资金

只开放必要权限

第一次打开后的 15 分钟

打开或新建工作区

查看顶部状态

连接一个测试服务

后文会出现的产品术语

连接券商、交易所或行情服务

保存前后分别检查什么

选择标的与行情来源

下单、Review 与 RiskGuard

选择账户

填写订单

执行 Review

RiskGuard 通过后明确提交

提交之后、撤单与改单

Kill Switch 怎么用

账户、持仓、订单与成交

从 Observation 到 Evidence

配置并使用 Agent

A. 先配置一个模型

打开设置 → AI

填写连接

检查额外参数

启用并保存

B. 完成一次安全会话

打开 Agent

把范围说清楚

检查运行时间线

审核，而不是盲目接受

处理交易提案

确定性运行、回放与 Trigger

配置浏览器访问与 HTTPS

A. 本机访问：最快的验证方式

设置 → Web Gateway

只监听 loopback

打开状态栏给出的 URL

B. 远程访问：先准备域名

解析域名

填写公开入口

选择 TLS

C. 推荐的 ACME 上线顺序

D. 会话、设备与工作区

运维、日志与审计

提交问题报告前

记录时间和环境

复制稳定证据

说明期望与实际

看懂状态，不把未知当成零

架构与数据边界

常见问题

完成安装和连接，
从安全模式开始。