OpenAlice 交易执行指南：`alice-uta` CLI 的账户、合约、订单与交易即 Git 审批流

alice-uta是 OpenAlice 放在 shell PATH 上的交易专用可执行文件，覆盖账户/组合读取、合约解析、报价、订单生命周期管理，以及一套刻意模仿 git 语义的"交易即 Git"审批流。本文以 default/skills/alice-uta/SKILL.md 为骨架，结合仓库源码（CLI 导出映射、UTA 协议类型、SDK 与工具层）给出每条命令的用法、边界与底层原理，读完即可安全地查询持仓、下单、撤单，并通过 commit→push 的人机审批链把交易送到券商。

alice-uta从实现上看是 OpenAlice 的utaCLI 导出（见 src/server/cli-commands.ts）：它以alice-uta为二进制名、作用域为global，把account / contract / order / position / git / market / sim七个命令组逐 verb 映射到底层 UTA 工具（如searchContracts、placeOrder、tradingStatus、tradingPush）。因此本文中的每个alice-uta <group> <verb>调用，最终都会落到src/tool/trading.ts中同名工具的执行逻辑上。

一、先分清：哪些命令只读，哪些命令会动交易状态

在动手之前，先建立安全边界。alice-uta的命令分为两类（这也是 SKILL.md 开篇的警告）：

• 只读、不改变券商状态：账户、组合、合约、报价、市场时钟、历史记录。包括account list / info / portfolio、contract search / details / quote / expand / option-contracts / option-chain / order-book、market clock、order list / history / trades。
• 可能改变交易状态：订单写入、平仓、审批流命令与模拟器。包括order place / modify / cancel、position close、git commit / push / reject / sync、sim price-change。执行前必须先看对应 verb 的实时帮助，并且只执行用户指令实际覆盖的操作。

从协议层看，这种区分同样体现在 packages/uta-protocol/src/types/broker.ts 与 packages/uta-protocol/src/types/git.ts 中：读操作返回的是账户信息、报价、历史等查询结果，而写操作（下单、平仓、撤单）被建模为 git 风格的操作记录，必须经过 commit/push 审批阶段才会真正送达券商。

二、发现优先：先看帮助，不要猜参数

技能的第一原则是"发现，而非猜测"（Discover, don't guess）：

alice-uta --help # 查看所有命令组 alice-uta <group> <verb> --help # 查看某个 verb 的 flags（以及哪些是必填的）

在任务中第一次执行 UTA 命令之前，先读本文档；如果命令被拒绝，就按 CLI 提示的建议命令重试，或先运行对应 verb 的--help，不要凭印象编造位置参数（如账户 id）或臆造--account、--query、--symbols之类的 flag。这个约定在源码中也有对应约束：src/server/cli-commands.ts 的resolveCommand把（导出、命令组、verb）三元组精确映射到底层工具名，因此命令面完全由 manifest 决定，猜测别名必然失败。

三、常用只读操作：账户与组合

alice-uta account list # 列出所有交易账户（UTA id） alice-uta account info --source <account-id> # 单个账户的详情 alice-uta account portfolio # 所有交易账户的组合 alice-uta account portfolio --source <account-id> # 单个账户的组合 alice-uta account portfolio --source <account-id> --symbol AAPL # 单个标的的持仓

关键约束：--source接受的是account list返回的账户 id——它不是--account，也不是券商原生的账号数字。源码层面，命令组的映射在 src/server/cli-commands.ts：account list → listUTAs、account info → getAccount、account portfolio → getPortfolio，这些工具最终通过 src/services/uta-client/UTAAccountSDK.ts 以 HTTP 方式访问同址部署的 UTA 服务（例如GET /api/trading/uta/:id/portfolio一类的路由），SDK 本身只是UnifiedTradingAccount公开接口的 HTTP 适配层。

四、合约解析是下单的前置步骤

任何报价与下单之前，必须先用券商解析出合约的"原生身份"，绝不能凭 symbol 猜。标准链路是 search → details → quote：

alice-uta contract search --source <account-id> --pattern AAPL alice-uta contract details --source <account-id> --alice-id '<alice-id-from-search>' alice-uta contract quote --alice-id '<alice-id-from-search>'

要点：

• 合约搜索用的是--pattern（不是--query）。
• quote一次只接受一个券商已解析的--alice-id；多合约就重复执行命令，不要发明--symbolsflag。
• quote 会从aliceId的前缀推断账户，所以不需要--source。
• aliceId值必须用引号包裹，因为它包含|字符，shell 会把它当作管道符解释。
• 合约搜索可能返回的是"目录"而非可交易叶子（例如期权链、期货月、债券发行方这类 hub），下单/报价前需要先展开：

alice-uta contract expand --help # 展开目录式结果（链、族）

源码佐证：packages/uta-protocol/src/brokers/preset-catalog.ts 定义了ccxt / alpaca / ibkr / leverup / longbridge / mock六类券商引擎，而 src/services/uta-client/UTAAccountSDK.ts 展示了searchContracts的实现细节：搜索路由是跨账户聚合的（/api/trading/contracts/search返回扁平行、每行带source标签），SDK 会过滤出属于本账户的结果并剥离source字段。aliceId的格式约定可见 src/tool/trading.ts：accountId|nativeKey，这正是"从aliceId前缀推断账户"的由来。

4.1 券商研究：期权定义、期权链与订单簿

contract组还提供了三个研究类 verb（源码映射见 src/server/cli-commands.ts）：

alice-uta contract option-contracts --help # 分页的期权定义与 dated 未平仓量 alice-uta contract option-chain --help # 分页的期权快照（含 IV/Greeks） alice-uta contract order-book --help # 订单簿深度（Alpaca 加密币与 CCXT）

协议层面的过滤条件定义在 packages/uta-protocol/src/broker-research.ts（optionResearchSchema）：

• aliceId（必填）：来自contract search的标的 aliceId；
• expiration/expirationFrom/expirationTo：日期过滤（YYYY-MM-DD）；
• right：call或put；
• strikeMin/strikeMax：非负数的行权价范围；
• limit：1–1000 的分页大小；
• pageToken：继续翻页时，保持相同的过滤条件并传入返回的nextPageToken；
• feed：indicative（默认）或opra。默认的 indicative 行情包含修改过的报价和延迟成交，需要结合观测时间戳使用，不能当作可执行的 OPRA 数据；OPRA 需要交易所授权。

orderBookSchema则接受aliceId与limit（1–100）。需要特别提醒的是：目前只有Alpaca支持期权读取，且期权读取不代表具备期权交易权限。另外 Alpaca 加密币使用CRYPTO合约、支持 GTC 或 IOC 订单，其股票市场时钟并不能描述 24/7 的加密币会话。

五、下单、改单与撤单

alice-uta order place --help # 下单前检查每一个 flag alice-uta order modify --help # 修改工作订单 alice-uta order cancel --help # 撤销工作订单 alice-uta order list # 工作订单列表 alice-uta order history --help # 订单记录 alice-uta order trades --help # 成交（fills）

规则：每次订单操作的结果都必须向用户报告——订单 id、状态、你做了什么。券商账户里出现意外是不可接受的。

源码层面，order place → placeOrder、order modify → modifyOrder、order cancel → cancelOrder（src/server/cli-commands.ts），而placeOrder工具的完整参数可见 src/tool/trading.ts，要点包括：

• orderType枚举：MKT（需totalQuantity或cashQty）、LMT（需totalQuantity + lmtPrice）、STP（需totalQuantity + auxPrice）、STP LMT（需totalQuantity + auxPrice + lmtPrice）、TRAIL/TRAIL LIMIT（需totalQuantity + auxPrice或trailingPercent）、MOC（需totalQuantity）；
• tif枚举：DAY（默认）、GTC、IOC、FOK、OPG、GTD（需配合goodTillDate）；
• 可附加takeProfit/stopLoss自动退出订单，以及ocaGroup、parentId、outsideRth、subAccountId等；
• 所有价格与数量都要求以十进制字符串传入（如"0.001"），以保证 satoshi 级精度不丢失——这与 packages/uta-protocol/src/types/git.ts 中"所有货币字段用字符串存储以规避 IEEE 754 伪影"的约定一致。

closePosition的参数在 src/tool/trading.ts：qty省略即平掉全部仓位；多钱包券商（如 Binance 的spot/derivatives）必须显式传subAccountId，UTA 层对多子账户的写入会"响亮拒绝"而不猜测。

六、平仓

alice-uta position close --help # 平掉一个仓位（部分或全部）

持仓的查看属于account portfolio（position 组只有 close 一个 verb，这一点在 src/server/cli-commands.ts 有明确注释）。

七、交易即 Git：OpenAlice 的交易审批流

git组是 OpenAlice 的交易审批流——每个 verb 刻意镜像 git 的语义：

alice-uta git status # 待提交 / 已暂存的交易状态（类比 git status） alice-uta git log # 历史（类比 git log） alice-uta git show --help # 查看某一条记录（类比 git show） alice-uta git commit --help # 批准 / 提交（类比 git commit -m） alice-uta git push --help # 把已提交的订单发送到券商（类比 git push） alice-uta git reject --help # 拒绝暂存的变更（类比 git reset） alice-uta git sync --help # 与券商对账（类比 git pull）

源码映射在 src/server/cli-commands.ts（git status → tradingStatus、git commit → tradingCommit、git push → tradingPush、git reject → tradingReject、git sync → tradingSync），工具实现与行为语义在 src/tool/trading.ts：

• git status（tradingStatus，src/tool/trading.ts）：查看当前交易暂存区状态；source省略时聚合所有账户。
• git commit（tradingCommit，src/tool/trading.ts）：带一条信息提交暂存的交易操作，不会真正执行。
• git push（tradingPush，src/tool/trading.ts）：最终的真实执行步骤。默认不执行——它返回待处理操作，要求用户在 Web UI 的 "Trading as Git" 页面（或账户详情页）人工批准；只有当运营者在 Settings → Agent Permissions 中开启了 "Allow AI to push trades"，才会直接把已提交操作作为真实订单发给券商。如果存在已暂存但未提交的操作，会明确报错并列出uncommitted。
• git reject（tradingReject，src/tool/trading.ts）：丢弃暂存（以及已提交未 push）的操作——是错误暂存的"撤销"；不会向券商发任何东西，拒绝会被记录到交易日志。
• git sync（tradingSync，src/tool/trading.ts）：从券商同步待处理订单状态；delayMs（0–30000，市价单后建议 2000–5000）用于等待交易所结算。

协议层的数据模型在 packages/uta-protocol/src/types/git.ts：Operation是带类型的判别联合（placeOrder/modifyOrder/closePosition/cancelOrder/syncOrders/observeExternalOrder/reconcileBalance），commit hash 是 8 字符的短 SHA-256；每次 commit 都会快照GitState（净清算价值、总现金、浮动盈亏、持仓、待处理订单，全部以字符串存储）。值得注意的两个细节：

• observeExternalOrder记录"用户直接在交易所 App 下单"这类 Alice 未发起的订单——同一轮扫描观测到的 N 个未追踪订单会被压成一个[observed]commit；
• reconcileBalance处理券商报告的、Alice 未发起的余额变动（首次启动对账、外部转账、质押奖励、平台外成交），作为观测价格下的虚拟买入/卖出参与成本基准。

测试侧，src/workspaces/cli/shim.spec.ts 验证了这些行为的 CLI 契约，包括alice-uta order place --help输出包含--commit-message-file <path>、以及通过文件传入 thesis 后placeOrder收到的commitMessage与文件内容完全一致。

7.1 交易论点中的美元符号：引号陷阱

shell 会在双引号内展开$。任何包含货币的交易论点，要么用单引号，要么用文件版 flag：

alice-uta order place ... --commit-message 'Buy below $971 after support confirmation' alice-uta order place ... --commit-message-file /path/to/thesis.txt

绝不要把美元计价的论点放在双引号的--commit-message里："$971"到达 OpenAlice 时可能变成"71"。文件版字符串 flag 还接受-以从 stdin 读取（当确切值已经以流的形式存在时）。这个陷阱在 src/workspaces/cli/shim.spec.ts 有对应的端到端断言：通过--commit-message-file传入Buy MU below $971 after support confirmation，最终工具收到的commitMessage与原文逐字节一致。

八、市场时钟与模拟器

alice-uta market clock # 券商当前是否开市（market clock → getMarketClock） alice-uta sim price-change --help # 仅 MockBroker —— 移动模拟价格用于测试；对真实券商是 no-op

sim组映射到simulatePriceChange（src/server/cli-commands.ts），其输入输出模型在 packages/uta-protocol/src/types/git.ts：

• symbol：合约 aliceId、symbol，或"all"；
• change："@88000"（绝对价格）或"+10%"/"-5%"（相对变动）；
• 返回当前状态与模拟后状态的对比（权益、浮动盈亏、每个仓位的avgCost、marketPrice、simulatedPrice、pnlChange、priceChangePercent以及最坏情形worstCase）。

工具层在 src/tool/trading.ts 中标注为"dry run, READ-ONLY"（模拟价格变动看组合影响）。此外，packages/uta-protocol/src/brokers/preset-catalog.ts 说明 MockBroker 是"内存中的模拟券商：真实资金、无交易所"，仓位与订单存在于进程内存，开发服务器重启即全部清空——这正是sim price-change只对 MockBroker 生效的原因。

九、这里没有的：调度不在alice-uta中

调度不在alice-uta里。周期性 / 无头（headless）的 Workspace 工作是 issue 驱动的：使用alice issue create，或直接编写带when字段的.alice/issues/<id>.md（详见 self-scheduling 技能）。源码上也印证了这一点：src/server/cli-commands.ts 明确注释"cron：故意不导出——调度保持 MCP-only"。

自调度 issue 与交易的关系有一条重要原则（见 default/skills/self-scheduling/SKILL.md）：定时任务仍然需要人来批准交易——一个调度运行可以研究、准备、甚至暂存交易，但暂存的交易只有在你在 Web UI（Trading-as-Git）中批准后才会执行；定时器永远不会自己动钱。这与alice-uta git push默认要求人工审批的设计完全一致。

十、实操速查：从查询到成交的完整链路

把上面的内容串成一条可复现的链路（每个命令前请先跑--help确认 flags）：

1. 发现账户：alice-uta account list→ 拿到--source <account-id>；
2. 解析合约：alice-uta contract search --source <account-id> --pattern AAPL→ 拿到引号包裹的aliceId；如返回目录式结果，先alice-uta contract expand --help展开；
3. 确认细节与报价：alice-uta contract details --source <account-id> --alice-id '<id>'、alice-uta contract quote --alice-id '<id>'；
4. 研究（如需）：alice-uta contract option-chain --alice-id '<id>'、alice-uta contract order-book --alice-id '<id>'；
5. 下单并提交：alice-uta order place ... --commit-message 'Buy below $971 after support confirmation'（含$的论点务必用单引号或--commit-message-file）；
6. 查看暂存区：alice-uta git status；
7. 审批：alice-uta git commit --help→ 提交；alice-uta git push --help→ 默认由用户在 Web UI 批准，启用 "Allow AI to push trades" 后才直接执行；
8. 跟踪与对账：alice-uta order list/order history/order trades，必要时alice-uta git sync；
9. 平仓：alice-uta position close --source <account-id> --alice-id '<id>' --qty <qty>（省略qty即全平）。

整个流程中，只读步骤（1–4、8 的查询部分）随时可安全执行；任何写操作（5–7、9）都在执行前检查--help，并向用户报告订单 id 与状态——这是alice-uta技能反复强调的安全底线，也是 src/tool/trading.ts 中stage → commit → push分层设计的实际意义：暂存是纯 git 状态变更，commit 是带消息的批准，push 才是唯一真正触达券商的环节。