xuanzhu 0.8.9 → 0.9.0

package/README.md

@@ -159,10 +159,20 @@ xzh
 
 ## 命令
 
+### 启动命令
+
 | 命令 | 说明 |
 | --- | --- |
 | `xzh` | 在当前目录启动全屏交互界面 |
 | `xzh <目录>` | 在指定项目目录启动，例如 `xzh /home` |
+| `xzh btc` | 进入 BTC 量化交易模式：工作目录固定 `~/.btc`（不可 `/switch`），只加载交易相关技能 |
+| `xzh btc moni` | 进入 **BTC 模拟盘**：虚拟账本开平仓，独立后端，不涉及真钱 |
+| `xzh btc apikey` | 管理交易所 API 凭据（录入 / 更新 / 删除 / 查看别名）；首次 `xzh btc` 也会自动检测 |
+| `xzh btc fk` | 硬性风控阈值：持仓亏损（默认 50%）/ 当日亏损 / 连亏次数 |
+| `xzh btc platform` | 选择交易平台（默认币安；交互式，也可 `xzh btc platform binance`） |
+| `xzh btc setup` | 准备 btc 计算环境：释放脚本 + 建 `~/.btc/venv` + 安装 numpy / pandas（首次进入时自动执行） |
+| `xzh btc stop` | 停止 btc 常驻后端（默认观察 + 模拟盘；`--paper` 只停模拟盘。退出界面**不会**停它） |
+| `xzh btc status` | 查看常驻后端与环境的状态 |
 | `xzh model` | 交互式管理多模型（新增 / 删除 / 查看全部） |
 | `xzh model list` | 列出**已配置**的模型（按回退顺序） |
 | `xzh model all` | 列出**所有内置可用**的模型（按服务商分组，标注已配置项） |
@@ -214,6 +224,50 @@ xzh
 | `xzh --help` | 查看帮助 |
 | `xzh --version` | 查看版本 |
 
+### 对话内命令（斜杠命令）
+
+进入界面后输入 `/` 开头的命令。下表是常用的，完整清单随时用 `/help` 查看。
+
+| 命令 | 说明 |
+| --- | --- |
+| `/help` | 显示全部命令与快捷键 |
+| `/model [编号\|id]` | 查看 / 切换当前模型 |
+| `/auto [on\|off]` | 切换自动批准（on：工具直接执行，写入配置） |
+| `/autonomy [ask\|observe\|auto]` | 自治等级：逐项确认 / 只观察 / 全自动 |
+| `/compact` / `/context` / `/usage` | 压缩历史 / 看上下文预算 / 看 token 用量 |
+| `/tools` | 列出本轮发给模型的工具（排查「某个工具没被调用」） |
+| `/memory` | 查看项目记忆（`show`、`global`、`clear`） |
+| `/goal <目标>` | 目标模式：持续执行到完成（`/goal off` 清除） |
+| `/init` | 扫描项目并补齐 `AGENTS.md` / `docs/` |
+| `/resume [编号]` | 列出 / 恢复历史会话 |
+| `/undo [N]` | 撤销最近 N 次文件修改 |
+| `/switch <目录>` | 切换项目目录（**btc 模式不可用**，见下） |
+| `/cwd` / `/clear` / `/copy` / `/image` / `/mouse` | 目录、清屏、复制输出、贴图、鼠标捕获 |
+| `/reset` | 重置对话上下文 |
+| `/exit` | 退出 |
+
+### btc 模式的对话内命令
+
+`xzh btc` / `xzh btc moni` 共用上面那套，另有三个与交易相关的，以及两个**行为不同**的：
+
+| 命令 | 说明 |
+| --- | --- |
+| `/feed` | 开关后台巡检过程流：巡检的思考与工具调用会实时显示成 `[后台 15:04] 思考：…` |
+| `/stop` | 暂停后端的自动巡检与自动交易（进程仍在、队列不丢）；`/stop status` 查看、`/stop resume` 恢复 |
+| `/reset moni [初始资金]` | 重置模拟盘账本（默认 100000）；`/reset` 不带参数仍是重置对话 |
+| `/switch <目录>` | **不可用**：btc 模式把工作目录锁在 `~/.btc`，界面与 Agent 两处代码都会拒绝 |
+| `/term` | 右栏是**只读仪表盘**（价格 / 账户或账本 / 巡检 / 风控），`Shift+Tab` 不再切到右栏 |
+
+后端的启停与配置不在对话里做（那是另一个进程），用命令行：
+
+```bash
+xzh btc status      # 看后端、队列、下次巡检
+xzh btc stop        # 停后端（对话里 /stop 只是暂停）
+xzh btc platform    # 选交易平台
+xzh btc apikey      # 管 API 凭据
+xzh btc fk          # 硬性风控阈值
+```
+
 ## 配置
 
 配置文件位于 `~/.xzh/config.json`（权限 `600`）。可用环境变量 `XZH_HOME` 整体重定向 ——
@@ -998,7 +1052,7 @@ v2ray / Clash / mihomo / sing-box **本地 SOCKS/HTTP 入站端口**，验证后
 当任务涉及某个领域时，玄猪会先 `list_skills` 查看可用技能、再 `load_skill` 加载完整指南
 （加载时自动安装并验证其依赖），然后借助 `bash` 执行指南中描述的命令。
 
-随包内置 20 个技能，常用如下：
+随包内置 27 个技能，常用如下（`btc-*` 七个只在 `xzh btc` 模式下可见）：
 
 | 技能 | 领域 | 依赖 |
 | --- | --- | --- |
@@ -1007,6 +1061,7 @@ v2ray / Clash / mihomo / sing-box **本地 SOCKS/HTTP 入站端口**，验证后
 | `autojs6` | **操作真实 Android 手机**：点击、滑动、输入、读界面、启动应用（脚本由设备桥推到手机上执行） | 无（手机需装 AutoJs6，见「手机设备桥」） |
 | `v2ray` | **本机代理发现与临时使用**：外网直连失败时探测本机 v2ray / Clash / sing-box 入站端口，验证后只对当前命令生效，并把端点写入全局记忆 | 无（需用户已启动代理客户端） |
 | `release` | **发版流程**：版本号 / CHANGELOG / 构建与测试 / `npm publish` / 等 registry 同步 / 推送 GitHub / 发布后校验（含逐步清单与踩坑） | 无（用 `npm` / `git`） |
+| `btc-*`（7 个） | BTC 交易：数据同步、三阶段买卖点、回测调参、工作流与风控纪律、巡检排期管理、模拟盘规则、决策指令（**仅 `xzh btc` 模式**） | 无（用 btc 模式自带的 `btc_*` 工具） |
 | `github` / `gitlab` | 仓库、Issue、PR / MR | `gh` / `glab` |
 | `jira` / `linear` | 项目管理 | 对应 CLI |
 | `aws` / `kubernetes` | 云资源与容器编排 | `aws` / `kubectl` |
@@ -1037,6 +1092,259 @@ description: 一句话说明该技能的用途与适用场景
 （指导模型如何使用该工具的正文）
 ```
 
+## 专用模式（`xzh btc`）
+
+除通用编码之外，玄猪支持**专用模式**：同一个 Agent 内核，换一套工作目录、技能范围与提示词。
+
+```bash
+xzh btc      # 进入 BTC 量化交易模式
+```
+
+| 约束 | 行为 |
+| --- | --- |
+| 工作目录 | 固定为 `~/.btc`（首次启动自动创建）；可用 `XZH_BTC_HOME` 重定向 |
+| 目录切换 | **不可 `/switch`**，由界面与 Agent 两处代码拦截；要换目录只能退出重开 |
+| 技能范围 | 只出现 `modes: [btc]` 与通用技能；`list_skills` / `load_skill` 在工具层就按模式裁剪 |
+| 提示词 | 追加一段「当前模式」说明（由代码生成，不可被 `xzh prompt set` 覆盖） |
+| 模型与记忆 | 与普通模式共用 `~/.xzh` 的模型配置；项目记忆落在 `~/.btc/.xuanzhu/` |
+| 工具 | 额外启用 `btc_*`：`btc_price` / `btc_status` / `btc_sync` / `btc_signal` / `btc_backtest` |
+
+**首次进入会自动准备计算环境**（建 `~/.btc/venv` 并安装 numpy + pandas，一次性、需联网），
+装好后再进入界面；当时联网失败也不拦启动，只是行情/回测暂不可用 —— 之后可手动重试：
+
+```bash
+xzh btc setup            # 重试 / 修复
+xzh btc setup --force    # 删掉 venv 重装
+```
+
+进模式后让 agent 先同步行情再判断：
+
+```
+btc_status → btc_sync → btc_signal（三阶段）→ btc_backtest（可选）
+```
+
+| 工具 | 作用 |
+| --- | --- |
+| `btc_price` | 币安永续最新价、24h 涨跌与成交额（实时，不落库） |
+| `btc_status` | 计算环境是否就绪、日线/小时线根数与最新时间、风控参数 |
+| `btc_sync` | 从币安增量同步 K 线到 `~/.btc/data/btc.db`（走 xzh 的全局代理） |
+| `btc_signal` | 三阶段买卖点（周线定势 → 日线定向 → 小时线定时） |
+| `btc_backtest` | 内置融合策略全量回测，`overrides` 可临时覆盖参数做对比 |
+| `btc_schedule` | 安排巡检：默认**改写下一跳**（旧的自动取消），`mode=add` 追加额外检查点 |
+| `btc_unschedule` | 撤销巡检计划（按 id，或 `scope`：`next` / `extra` / `all`） |
+| `btc_policy` | 决策指令：把用户的长期要求落盘，注入后台每一轮巡检 |
+| `btc_order` / `btc_close` | **真实挂单**（合约限价 GTC，不追价）/ 只减仓平仓 |
+| `btc_orders` | 查挂单与持仓（确认限价单是否成交） |
+| `btc_cancel` | 撤单（按订单号或整个交易对） |
+| `btc_transfer_profit` | 锁利：合约 → 现货单向划转（上限为可用余额 95%） |
+| `btc_paper_status` | 模拟盘账本：权益、持仓、浮动盈亏、胜率、最近成交 |
+| `btc_paper_open` / `btc_paper_close` | 模拟盘挂限价单（收盘价到达即成交）/ 平仓 |
+| `btc_paper_cancel` | 撤销模拟盘未成交挂单 |
+| `btc_paper_reset` | 清空模拟盘账本（需确认；后台巡检里必被拒） |
+
+平台选择：`xzh btc platform` 交互式切换（写入 `~/.btc/platform.json`，立即生效，不用重启）；
+环境变量 `BTC_EXCHANGE` 优先级更高，适合 CI / 多环境临时覆盖。
+
+平台相关环境变量（可写进 `~/.btc/.env`，Node 与 Python 读同一份）：
+
+| 变量 | 作用 |
+| --- | --- |
+| `BTC_SYMBOL` | 标的，默认 `BTC/USDT` |
+| `BTC_EXCHANGE` | 交易所，目前只有 `binance`；写了未接入的值会直接报错（不静默回退）。**优先级高于 `xzh btc platform` 的持久设置** |
+| `BTC_USE_FUTURES` | `0` 走现货；默认（未设置）走合约，与回测的资金费口径一致 |
+| `BTC_INSPECT_ENABLED` | `0` = 后台只同步数据不调模型；默认 `1` 自主巡检 |
+| `BTC_SYNC_INTERVAL_MIN` | 仅同步模式下的固定间隔（分钟），默认 15 |
+
+**网络**：没配代理时，进入模式会先探测币安接口能不能直连；不通就自动找一个本机代理
+（10808 / 7890 / 2080 等常见端口）**仅本次生效**，并提示长期方案 `xzh vpn`。
+已经配了代理就直接用，不会再多探测一次。
+
+### 常驻后端（自主巡检）
+
+`xzh btc` 会确保一个**独立的后端进程**在跑，它按**模型自己决定的间隔**巡检：
+
+- 每轮巡检会取行情、算三阶段、给结论，然后自己决定下次什么时候再看
+  —— 例如判断「小时线接近触发，45 分钟后复核」；
+- 计划写进一个**排期队列**（`~/.btc/run/schedules.json`），后台每 60 秒检查一次，
+  到点就执行 —— 不是 sleep，所以你随时能让它多排一次检查，不用等它「睡醒」；
+- 间隔被限制在 **10 分钟到 12 小时**之间：太短会连续调模型烧钱，太长会错过行情；
+- **关键时点由代码兜底**，不依赖模型记性：日线收盘（北京 08:00）、资金费结算
+  （北京 00:00 / 08:00 / 16:00）、有持仓时的小时线收盘、以及价格较上次巡检波动 ≥2.5%
+  都会额外触发一轮巡检（波动触发 10 分钟内不重复）；
+- **改期 / 取消**：直接说「30 分钟后再看」，agent 用 `btc_schedule` 改写下一跳（原计划自动取消）；
+  说「取消这次巡检」用 `btc_unschedule`；`xzh btc status` 会列出每条计划的短 id 供精确撤销；
+- **退出界面不会停它**，下次进入复用同一个进程（不会重复启动）；`xzh btc stop` 才停；
+- `xzh btc status` 看最近结论、队列条数、下一条计划与理由（后端停了也会显示待执行计划）；
+- **过程实时可见**：巡检的思考、工具调用与结论会以 `[后台 15:04] 思考：…` 的形式
+  出现在对话输出区（每 2.5 秒拉一次增量）；刷屏时用 `/feed` 关掉，再看一次 `/feed` 打开；
+- 日志：`~/.btc/logs/backend.log`（进程）、`~/.btc/logs/inspect.log`（每轮结论，可复盘）；
+- 想让后台只同步数据、不调用模型：设置 `BTC_INSPECT_ENABLED=0`。
+
+后台巡检**没有下单能力**，只给判断与建议。它运行在无人值守状态，任何需要用户确认的
+操作在后台一律被拒绝（代码强制，不靠提示词），所以将来接入下单也必须先过这道闸门。
+
+单实例由锁文件保证：两个终端同时 `xzh btc` 也只会有一个后端；异常退出留下的残留锁会被自动接管。
+
+注意三点：
+
+- `xzh btc` 的模式名**优先于同名目录** —— 要打开当前目录下名为 `btc` 的文件夹请写 `xzh ./btc`。
+- 目录锁定是「默认目录 + 禁止切换」，**不是文件系统沙箱**：写文件 / 执行命令仍可访问绝对路径。
+- **当前没有下单 / 平仓 / 持仓 / 账户工具**：模型能取行情、算信号、做回测，但不能动钱；
+  它被明确要求不得声称「已下单」。实盘执行需要用户手动操作或等后续接入带风控的下单工具。
+
+### 模拟盘（`xzh btc moni`）
+
+模拟盘用**同一份行情库**、**同一套三阶段判断**，但成交记在本地虚拟账本上，**不涉及真钱**：
+
+```bash
+xzh btc moni     # 启动/复用模拟盘后端并进入界面
+xzh btc status   # [实盘] 与 [模拟盘] 两个后端分别显示
+xzh btc stop     # 两个都停（--paper 只停模拟盘）
+```
+
+| 项 | 规则 |
+| --- | --- |
+| 成交 | **限价挂单**：最新收盘价到达限价即视为全部成交，成交价 = 限价 |
+| 成本 | 手续费 0.05%（开平各一次），不计资金费 |
+| 持仓 | 同时只允许一个持仓、一张未成交挂单 |
+| 初始资金 | 默认 100000 USDT（`BTC_PAPER_CAPITAL` 可改） |
+| 账本 | `~/.btc/data/btc.db` 的 `paper_account` / `paper_trades` 表 |
+
+模拟盘后端是**独立进程**（`run/paper.lock`、`logs/paper.log`），与观察模式互不干扰，
+两者的排期队列也是分开的。后台巡检在模拟盘模式下可以自己虚拟开平仓，
+结论写进 `~/.btc/logs/inspect.log`。
+
+重置账本用 `btc_paper_reset`（会弹确认；后台巡检里必被拒绝）。
+
+### 开仓一律限价（挂单等成交）
+
+`btc_order` **必须给 `limit_price`**，下的是限价 GTC 单：
+
+- 不追价、不立即成交，**挂到下一次买卖点或主动撤单为止**；
+- 未成交前不算持仓，面板与 `btc_orders` 里显示为挂单；
+- 到下一次巡检、或三阶段结论变了仍未成交 → 由 agent 决定「继续等」还是 `btc_cancel all=true` 撤掉；
+- 止损/止盈作为 `closePosition` 条件单一起挂（触发时按当时仓位全平）；
+- 模拟盘同规则：挂单后按**收盘价**判断，价格到达限价即全部成交。
+
+平仓（`btc_close`）是市价 + `reduceOnly` —— 出场要确定，不在场内等。
+
+### 硬性风控（`xzh btc fk`）
+
+用户设定的**硬线**，由代码执行，模型无权放宽：
+
+```
+硬性风控
+  状态：正常
+  1. 单持仓亏损阈值     50%
+  2. 当日亏损阈值       10%
+  3. 连续亏损次数       3 次
+  4. 单笔风险占权益     2%
+  5. 触发后禁止开仓     是
+  6. 返回（或「保存并返回」）
+```
+
+| 项 | 默认 | 说明 |
+| --- | --- | --- |
+| 单持仓亏损阈值 | **50%** | 相对保证金的浮亏，达到即触发 |
+| 当日亏损阈值 | 10% | 当日权益回撤 |
+| 连续亏损次数 | 3 | 连亏达到即停手 |
+
+触发后：写 `~/.btc/run/risk-state.json`，**下一轮后台巡检会带着「风控已触发、重估策略」的
+上下文跑**，并要求模型用 `btc_policy` 落盘调整后的策略。触发后默认禁止开新仓，
+解除需要用户在 `xzh btc fk` 里确认。
+
+**agent 级风控**（如「震荡市半仓」「不逆势」）属于软约束，写进 `btc_policy` 由模型遵守。
+
+### 右侧仪表盘
+
+btc 模式下右侧面板不再是终端，而是只读仪表盘（每 8 秒刷新）：
+
+```
+ BTC 永续   U 本位合约
+ 77,415.30  -0.58%
+ ─────────────
+ 权益 100,000.00
+ 可用  98,999.50
+ 浮盈  +0.00
+ 持仓 多 0.0129 @ 77,317 5x
+    +0.00（+0.00%） 强平 0.00
+ 挂单 2 条
+   买 76,800.00 × 0.010
+ ─────────────
+ 巡检
+ 14:47 · 30 分钟后
+  复核小时线
+ 15:20 · 45 分钟后（额外）
+  资金费前后各看一次
+ ─────────────
+ 风控 正常
+  持仓亏损 50% · 当日 10%
+```
+
+`Shift+Tab` 在 btc 模式下不再切到右栏（那里没有输入行）。
+
+**模拟盘（`xzh btc moni`）下同一个面板换一套数据**：权益 / 现金 / 持仓 / 挂单 / 已平仓绩效，
+不显示真实账户 —— 两套账混在一起会让人误判。标题也会变成「BTC 模拟盘」。
+
+对话里暂停 / 恢复后端的自动巡检与自动交易（进程仍在，队列不丢）：
+
+```
+/stop             # 暂停
+/stop status      # 查看是否暂停
+/stop resume      # 恢复
+```
+
+想彻底停掉进程用 `xzh btc stop`（那是另一回事：进程退出，需要重新 `xzh btc`）。
+
+重置模拟盘账本（初始资金默认 100000）：
+
+```
+/reset moni           # 重置为 100000
+/reset moni 200000    # 指定初始资金
+```
+
+`/reset`（不带参数）仍然是重置对话上下文，两者互不影响。
+
+### 只做合约，不做现货
+
+- 交易只走**合约**（`fapi`），代码里没有现货下单路径；
+- **没有**提现能力，也**没有**「现货 → 合约」方向的划转；
+- 唯一允许的资金移动是**合约 → 现货**（`btc_transfer_profit`），用于锁定已实现收益：
+  上限为可用余额的 95%，避免把保证金掏空。`type` 在代码里写死为 2，调用方改不了。
+
+典型用法：用户说「每笔成功交易把利润的 10% 转到现货」→ agent 平仓后按实际收益算出
+USDT 金额，调用 `btc_transfer_profit`；技能里要求它把划转结果一并回报。
+
+### API 凭据（`xzh btc apikey`）
+
+实盘下单需要交易所 API 凭据。**首次运行 `xzh btc` 时会自动检测**，没有就进入交互式管理：
+
+```
+凭据管理
+  1. 币安（Binance）        未配置
+  2. 火币（Huobi）（开发中）
+  3. 跳过（稍后再说）
+        ↓
+凭据 · 币安（Binance）
+  1. 录入凭据 / 更新凭据
+  2. 删除凭据
+  3. 查看凭据别名
+  4. 返回
+```
+
+| 项 | 说明 |
+| --- | --- |
+| 存储 | 明文用 AES-256-GCM 加密存 `~/.xzh/vault/`；`~/.btc/credentials.json` 只存引用 id 与别名 |
+| 别名 | 每个平台一个别名（如「主账号」），用于辨认；列表只显示掩码 `abcd…wxyz` |
+| 输入 | 录入时每个字符回显 `*`（退格可删、Ctrl+U 清空），屏幕与日志里都不会出现明文 |
+| 查看 | 一级菜单里就能直接「查看已配置的凭据」，不必先点进平台 |
+| 跳过 | 选「跳过」后不再自动询问，之后可随时 `xzh btc apikey` |
+| 模拟盘 | `xzh btc moni` **不需要**凭据（不涉及真钱） |
+| 权限 | 创建 API Key 时只勾「读取」+「交易」，**不要开提现** |
+
+凭据不会进入对话、日志或模型上下文 —— 没有任何工具能读写它。
+**永远不要把 API Key 粘贴到聊天里**，只能用 `xzh btc apikey` 录入。
+
 ## 界面布局
 
 界面分为两栏，底部状态栏横跨全宽：