fubon-cli 技能

使用此技能安全执行 fubon 命令，并返回可解析的结果，供下游自动化流程使用。

该技能的功能

• 端到端执行 fubon-cli 的命令组。
• 确保命令用法与实际 CLI 行为保持一致。
• 返回标准化的 JSON 输出及错误处理指引。
• 支持订单全生命周期工作流：登录 → 查询 → 下单 → 核验 → 调整/撤单。

适用场景

当用户提出以下任一意图时，请使用此技能：

• 富邦证券 Neo 平台的登录/登出/会话状态查询。
• 股票、期货或期权的下单与订单管理。
• 查询持仓、未实现盈亏（PnL）、结算信息、账户余额、保证金额度。
• 读取行情报价、K 线、成交明细、涨跌幅榜、活跃股、快照、历史数据。
• 订阅实时行情流或回调流。
• 条件单管理。
• 使用自然语言生成交易指令（fubon ask、fubon chat）。

前置条件

1. 安装 fubon_neo 平台 wheel 包。
2. 安装 fubon-cli。
3. 确保证书文件与账户凭证已就绪。

示例：

pip install ./wheels/fubon_neo-2.2.8-cp37-abi3-win_amd64.whl
pip install fubon-cli

核心工作流

1. 首先完成身份认证。
2. 执行用户请求的查询或订单操作。
3. 检查响应中的 success 与 error 字段。
4. 若为下单操作，需执行后续查询命令（如 fubon stock orders）以确认订单状态。

fubon login --id  --password  --cert-path  --cert-password 
fubon login --id  --api-key   --cert-path  --cert-password 
fubon market quote 2330
fubon stock buy 2330 1000 --price 580
fubon stock orders

命令映射表

认证（Auth）

fubon login --id  --password  --cert-path  [--cert-password ]
fubon login status
fubon login logout

命令接口（Command Surface）

下方 Command Surface 列出了主要的 CLI 入口点及其使用示例。这些命令与 fubon-cli 命令严格一一对应；在满足前置条件的前提下，可安全地由自动化流程调用。

具体调用示例请参见 Command Map 小节。

股票（Stock）

fubon stock buy   --price 
fubon stock sell   --price 
fubon stock orders
fubon stock cancel 
fubon stock modify-price  
fubon stock modify-quantity  

账户（Account）

fubon account inventory
fubon account unrealized
fubon account settlement
fubon account margin-quota 

市场（Market）

fubon market quote 
fubon market ticker 
fubon market candles  --timeframe 5
fubon market trades  --limit 50
fubon market snapshot TSE
fubon market movers TSE --direction up
fubon market actives TSE --trade volume
fubon market history  --from 2024-01-01 --to 2024-06-30

实时（Realtime）

fubon realtime subscribe 
fubon realtime callbacks

期货与期权（Futures and Options）

fubon futopt buy TXF202406 1 --price 20000
fubon futopt sell TXF202406 1 --price 20100
fubon futopt orders

条件单（Conditional Orders）

fubon condition create --payload '{"symbol":"2330","trigger":{}}'
fubon condition list
fubon condition cancel 

AI 功能（AI）

fubon ask "台積電現在的價格是多少？"
fubon chat
fubon config set openai-key 
fubon config show

输出契约（Output Contract）

非流式命令输出格式：

{
  "success": true,
  "data": {}
}

失败响应示例：

{
  "success": false,
  "error": "Error message"
}

流式命令输出 JSONL 格式（每行一个 JSON 对象）。

执行规则

1. 切勿假定当前已登录；应主动检查登录状态，或妥善处理“未登录”类错误。
2. 对订单类操作，必须通过 fubon stock orders 或等效查询命令进行状态确认。
3. 对可重试失败（如网络异常、临时性故障），仅保守重试一次。
4. 对参数错误或认证失败，立即中止执行，并透出原始 error 文本。

安全边界

• 禁止在日志或聊天输出中暴露原始凭据（如密码、证书密码、API Key 等）。
• 鼓励在下单前人工核验标的代码（symbol）、数量（quantity）、价格（price）及账户索引（account index）。
• 首次用于自动化时，优先选用非生产环境或低风险验证路径。

发布绑定（Release Binding）

该技能版本与 fubon-cli 绑定。

• scripts/validate_skill_doc.py 用于校验文档覆盖度。
• scripts/build_skill_bundle.py 用于构建技能制品包（skill artifact）。
• scripts/publish_skill.py 用于将技能发布至 clawhub 端点。
• CI/CD 流程应在 fubon-cli 包发布完成后自动触发技能发布，确保工具与技能版本同步。

版本绑定（Version Binding）

该技能版本必须与 fubon-cli 包版本严格对齐。CI/CD 流水线已配置为：在 fubon-cli 包成功发布后，立即构建并发布技能包，从而确保技能元数据（skill.manifest.json）与说明文档（SKILL.md）均与已发布的软件包完全匹配。

• 使用 scripts/build_skill_bundle.py 可基于当前 Git Tag 或包版本生成 dist/skill 目录下的技能制品。
• 使用 scripts/publish_skill.py（需配置 CLAWHUB_API_TOKEN）可将技能包发布至技能注册中心（skill registry）。