xuanzhu 0.14.0 → 0.15.0

package/README.md

@@ -165,14 +165,6 @@ xzh
 | --- | --- |
 | `xzh` | 在当前目录启动全屏交互界面 |
 | `xzh <目录>` | 在指定项目目录启动，例如 `xzh /home` |
-| `xzh btc` | 进入 BTC 量化交易模式：工作目录固定 `~/.btc`（不可 `/switch`），只加载交易相关技能 |
-| `xzh btc moni` | 进入 **BTC 模拟盘**：虚拟账本开平仓，独立后端，不涉及真钱 |
-| `xzh btc apikey` | 管理交易所 API 凭据（录入 / 更新 / 删除 / 查看别名）；首次 `xzh btc` 也会自动检测 |
-| `xzh btc fk` | 硬性风控阈值：持仓亏损（默认 50%）/ 当日亏损（10%）/ 连亏次数（3）——**三条都真实生效** |
-| `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` | 列出**所有内置可用**的模型（按服务商分组，标注已配置项） |
@@ -188,6 +180,31 @@ xzh
 | `xzh config path` | 打印配置文件路径 |
 | `xzh config init` | 生成默认配置文件 |
 | `xzh vpn` | 交互式设置 / 探测 / 测试 / 启停全局 HTTP(S)/SOCKS5 代理 |
+| `xzh gateway` | 启动常驻 gateway 服务（工作目录 `~/.xzh_gateway`，首次启动自动开机自启） |
+| `xzh gateway stop\|restart\|status` | 停止 / 重启 / 查看 gateway |
+| `xzh gateway autostart [on\|off]` | 开/关开机自启（systemd user unit） |
+| `xzh gateway weixin login` | 扫码登录个人微信（iLink Bot），登录后 `xzh gateway restart` 生效 |
+| `xzh gateway weixin status\|logout` | 查看 / 清除微信登录 |
+
+**微信频道**（`xzh gateway weixin login`）：扫一次码，之后微信私聊直接和 gateway 的 agent 对话。
+
+- 走腾讯 **iLink Bot API**（个人微信，长轮询收消息，不需要公网 webhook / 端口映射）；
+- 只支持**文本**：图片、语音、文件（AES-128-ECB 加密 CDN）暂未接入；
+- 连接的是 iLink bot 身份（如 `xxx@im.bot`），**不是**普通个人号 —— 通常进不了普通微信群，
+  群里 `@` 你本人也不等于 `@` 这个 bot；实际可用的是私聊；
+- 回复按 1500 字分块；`context_token` 与同步游标落盘，重启不会重放旧消息或断开上下文；
+- 白名单：`XZH_WEIXIN_ALLOWED_USERS=wxid_a,wxid_b`（不设 = 不限制，只服务扫码绑定的人）；
+- 凭据存 `~/.xzh_gateway/weixin/account.json`（0600），`logout` 一次清干净。
+
+**gateway 是什么**：等价于在 `~/.xzh_gateway` 目录里启动一个 xzh，但没有界面、不会因为
+`quit`/`exit` 或关终端而退出 —— 它是给「外部消息通道」（先留好接口，未来接微信）用的常驻进程。
+
+- 工作目录 `~/.xzh_gateway`（`XZH_GATEWAY_HOME` 可改），记忆/会话独立，不混进日常项目；
+- 本地接口：`GET /health`、`POST /message`（`{"text":"..."}` → 回复文本）、`POST /shutdown`，
+  默认端口 17890（`XZH_GATEWAY_PORT` 可改），只监听 127.0.0.1；
+- 首次 `xzh gateway` 会顺手装好 **systemd user 开机自启**（`Restart=always`）；
+  没有 systemd 的环境只提示、不影响服务；`xzh gateway autostart off` 可关闭；
+- 日志：`~/.xzh_gateway/logs/gateway.log`。
 | `xzh setup` | 检查并自动安装依赖（玄猪自身 + 技能：playwright / officecli / 剪贴板工具等） |
 | `xzh init` | 扫描项目并生成 / 补全 `AGENTS.md` 与 `docs/`（已有内容只补缺失小节） |
 | `xzh init --dry-run` | 只预览将生成的内容，不写文件 |
@@ -242,33 +259,11 @@ xzh
 | `/init` | 扫描项目并补齐 `AGENTS.md` / `docs/` |
 | `/resume [编号]` | 列出 / 恢复历史会话 |
 | `/undo [N]` | 撤销最近 N 次文件修改 |
-| `/switch <目录>` | 切换项目目录（**btc 模式不可用**，见下） |
+| `/switch <目录>` | 切换项目目录 |
 | `/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` 整体重定向 ——
@@ -667,7 +662,7 @@ xzh prompt reset core         # 取消覆盖
 [当前状态 · 系统根据确定事实生成，仅供参考，不要复述]
 - 目标：重构区间策略（进行中 · 已用 12m）
 - 任务：2/5 完成；进行中：修 server.py 重复路由；待办：跑回测
-- 状态：受阻 —— 缺少 BTC_API_KEY
+- 状态：受阻 —— 缺少模型 API Key
 - 最近动作：read_file ✓、edit_file ✓、bash ✗
 - 本次会话已改动：client/api/server.py
 - 上下文：约 62%（较早内容可能已被裁剪）
@@ -1016,12 +1011,25 @@ v2ray / Clash / mihomo / sing-box **本地 SOCKS/HTTP 入站端口**，验证后
 
 | 文件 | 内容 |
 | --- | --- |
-| `AGENTS.md` | **只放入口级大纲**：项目概览、关键命令、顶层目录、必守约定、文档索引；完整内容放 `docs/` |
-| `docs/README.md` | 文档索引：AGENTS.md 与 `docs/` 各文件的对应关系 |
-| `docs/ARCHITECTURE.md` | 目录结构、模块概览、入口与运行方式；无法确定的部分标注「待补充」 |
+| `AGENTS.md` | **只放入口级大纲**：项目概览、关键命令、顶层目录、必守约定、文档索引；子目录文档只按目录汇总，不逐条列出 |
+| `docs/README.md` | 文档索引：目录分工约定 + 按「项目根 / `docs/` / 各子目录」分组列出既有文档 |
+| `docs/ARCHITECTURE.md` | 目录结构、模块概览、文档组织、入口与运行方式；无法确定的部分标注「待补充」 |
 | `docs/COMMANDS.md` | 命令表 + `package.json` scripts 原始内容（有命令时才生成） |
 | `docs/CONVENTIONS.md` | 从配置文件探测到的风格与工程约定（有配置时才生成） |
 
+**docs 子目录约定**（`xzh init` 扫描已有文档时会递归两层并分组索引，但**不预创建空目录**）：
+
+| 位置 | 放什么 |
+| --- | --- |
+| `docs/` 根 | 只留入口级四件套：`README.md`（索引）、`ARCHITECTURE.md`、`COMMANDS.md`、`CONVENTIONS.md` |
+| `docs/guides/` | 操作指南：步骤、流程、排障（how-to） |
+| `docs/reference/` | 参考手册：API、配置项、数据字典 |
+| `docs/decisions/` | 架构决策记录：一篇一个决定，文件名 `NNNN-短标题.md` |
+
+- 子目录最多两层（`docs/<主题>/[<子主题>/]<文件>.md`），文件名用小写连字符；
+- 子目录可选一个 `README.md`，它的一级标题会作为该目录的说明；
+- 只有真的写了文档才建目录，不要提交空目录占位。
+
 | 命令 | 说明 |
 | --- | --- |
 | `xzh init` | 生成缺失文件；已存在的文件**按 `##` 小节合并**，只追加缺失小节，保留原内容 |
@@ -1042,7 +1050,8 @@ v2ray / Clash / mihomo / sing-box **本地 SOCKS/HTTP 入站端口**，验证后
 - **`/init`（对话内）**：先执行同样的确定性框架，再调用当前模型，根据扫描事实与现有
   AGENTS/docs 整理入口大纲和详细文档：
   - AGENTS.md 仍只保留入口大纲，尽量简短；
-  - 缺失的 `docs/` 文件会补齐，模型可同步更新对应 docs；
+  - 缺失的 `docs/` 文件会补齐；模型可在 `docs/` 下新增 / 更新文档（含 `guides/` 等子目录，
+    最多两层，只允许 `.md` / `.mdx`）；
   - 写入前展示预览并确认，覆盖文件前自动备份；
   - 模型失败不会破坏已写入的初始框架，可稍后再次 `/init`；
   - 强制保留「文档同步」小节：代码改动同步到 AGENTS/docs，md 设计变化需额外告知用户。
@@ -1053,7 +1062,7 @@ v2ray / Clash / mihomo / sing-box **本地 SOCKS/HTTP 入站端口**，验证后
 当任务涉及某个领域时，玄猪会先 `list_skills` 查看可用技能、再 `load_skill` 加载完整指南
 （加载时自动安装并验证其依赖），然后借助 `bash` 执行指南中描述的命令。
 
-随包内置 28 个技能，常用如下（`btc-*` 八个只在 `xzh btc` 模式下可见）：
+随包内置 28 个技能，常用如下：
 
 | 技能 | 领域 | 依赖 |
 | --- | --- | --- |
@@ -1062,7 +1071,6 @@ v2ray / Clash / mihomo / sing-box **本地 SOCKS/HTTP 入站端口**，验证后
 | `autojs6` | **操作真实 Android 手机**：点击、滑动、输入、读界面、启动应用（脚本由设备桥推到手机上执行） | 无（手机需装 AutoJs6，见「手机设备桥」） |
 | `v2ray` | **本机代理发现与临时使用**：外网直连失败时探测本机 v2ray / Clash / sing-box 入站端口，验证后只对当前命令生效，并把端点写入全局记忆 | 无（需用户已启动代理客户端） |
 | `release` | **发版流程**：版本号 / CHANGELOG / 构建与测试 / `npm publish` / 等 registry 同步 / 推送 GitHub / 发布后校验（含逐步清单与踩坑） | 无（用 `npm` / `git`） |
-| `btc-*`（8 个） | BTC 交易：数据同步、三周期打分 + 1h 择时、回测调参、工作流与风控纪律、巡检排期管理、模拟盘规则、决策指令、叫醒条件（**仅 `xzh btc` 模式**） | 无（用 btc 模式自带的 `btc_*` 工具） |
 | `github` / `gitlab` | 仓库、Issue、PR / MR | `gh` / `glab` |
 | `jira` / `linear` | 项目管理 | 对应 CLI |
 | `aws` / `kubernetes` | 云资源与容器编排 | `aws` / `kubectl` |
@@ -1093,345 +1101,6 @@ 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/venv` 并安装 numpy + pandas，一次性、需联网），
-装好后再进入界面；当时联网失败也不拦启动，只是行情/回测暂不可用 —— 之后可手动重试：
-
-```bash
-xzh btc setup            # 重试 / 修复
-xzh btc setup --force    # 删掉 venv 重装
-```
-
-进模式后让 agent 先同步行情再判断：
-
-```
-btc_status → btc_sync → btc_signal（三周期打分 + 1h 择时）→ btc_backtest（可选）
-```
-
-买卖点规则（用户设定，代码执行）：周线 / 日线 / 4h 各给 **-1（下跌）/ 0（横盘）/ +1（上涨）**，
-三周期都 ≥0 只做多、都 ≤0 只做空、**全 0 或方向冲突不做**，任一周期数据不足也不做；
-**1 小时线负责「有没有机会」**：在上面做技术分析（结构 / 位置 / 动量 / 量能 / 形态），
-给出 0–100 的机会评分与形态（回调 `pullback` 或放量突破 `breakout`）；
-`≥60` 分且结构、位置、形态都不为 0 才是 `stage4_1h.entry = now`，否则等。
-1h 不会把三周期给出的方向翻过来。含横盘周期时仓位减半。
-
-`btc_order` 在下单前会用同一套结论做**方向闸门**：方向不符、`none` 或数据不足都直接拒绝
-（真钱）；模拟盘 `btc_paper_open` 不拦，但会在返回里标注「实盘会被拒绝」。
-
-| 工具 | 作用 |
-| --- | --- |
-| `btc_price` | 币安永续最新价、24h 涨跌与成交额（实时，不落库） |
-| `btc_status` | 计算环境是否就绪、日线/小时线根数与最新时间、风控参数 |
-| `btc_sync` | 从币安增量同步 K 线到 `~/.btc/data/btc.db`（走 xzh 的全局代理） |
-| `btc_signal` | 三周期打分（周/日/4h 各 -1/0/+1，同向才单向）+ 1 小时线机会评分（≥60 且形态成立才进） |
-| `btc_backtest` | 内置融合策略全量回测，`overrides` 可临时覆盖参数做对比（**注意：它不是实盘那套三周期判定**） |
-| `btc_schedule` | 安排巡检：默认**改写下一跳**（旧的自动取消），`mode=add` 追加额外检查点 |
-| `btc_unschedule` | 撤销巡检计划（按 id，或 `scope`：`next` / `extra` / `all`） |
-| `btc_policy` | 决策指令：把用户的长期要求落盘，注入后台每一轮巡检 |
-| `btc_trigger` | 叫醒条件：价格/指标到什么值时叫醒巡检（后台每 5 分钟评估，**只叫醒不下单**） |
-| `btc_renew` | 给未成交挂单续期（判断继续等时用；只改时效、不动订单） |
-| `btc_order` / `btc_close` | **真实挂单**：限价（单档或 `orders[]` 多档分批，带时效 `expires_min`）/ 平仓（`market` 或 `limit`） |
-| `btc_orders` | 查挂单与持仓（确认限价单是否成交） |
-| `btc_cancel` | 撤单（按订单号或整个交易对） |
-| `btc_transfer_profit` | 锁利：合约 → 现货单向划转（上限为可用余额 95%） |
-| `btc_paper_status` | 模拟盘账本：权益、持仓、浮动盈亏、胜率、最近成交 |
-| `btc_paper_open` / `btc_paper_close` | 模拟盘挂限价单（到达即成交；限价被穿越则按更优价）/ 平仓 |
-| `btc_paper_cancel` | 撤销模拟盘未成交挂单 |
-| `btc_paper_reset` | 清空模拟盘账本（需确认；后台巡检里必被拒） |
-
-「到某个位置再看一眼」不必改排期，直接用叫醒条件（对话里说就行，模型会调 `btc_trigger`）：
-
-```
-到 80000 提醒我看做空          → 价格条件（一次性，命中即失效）
-1h RSI 跌破 30 就看一眼        → 指标条件（rsi / adx / ma_gap_pct / macd_hist，1h/4h/1d）
-```
-
-后台**每 5 分钟**评估一次，命中才跑一轮巡检（不命中不调模型，所以很便宜）；
-条件默认 72 小时失效、最多同时 10 条，可用 `window_start_hour` / `window_end_hour`
-限定北京时间时段（例如只在 21–24 点评估）。**它只叫醒、不下单** ——
-下单仍由那一轮按三周期打分与风控判断。
-
-**后台巡检是无人值守的**：被监控/排期叫醒后，它会在**交易动作**上自主决策到底（真开仓、真平仓、
-真撤单），不会停下来等确认。边界是代码强制的：清账本（`btc_paper_reset`）、资金划转
-（`btc_transfer_profit`）、写文件与执行命令仍会拒绝；硬性风控、三周期方向闸门、保证金与倍率校验
-照常生效。
-
-监控不只盯价位：**行情获取本身也被监控**。后端每 5 分钟探一次实时价，K 线同步失败也计入同一个
-「连续失败」计数（任一成功即清零）；**连续 2 次失败就叫醒一轮巡检**去排查（代理 / 网络 / 限频 /
-时间偏差），并把失败次数与最近错误写进提示词，修好前不得下单。同一轮故障只叫醒一次，恢复后计数清零。
-
-组合条件用**受限公式**（`kind=formula`）：`rsi_1h * 0.6 + adx_1h * 0.4`、
-`(close_1h - ma20_1h) / atr_1h`。变量是 `字段_周期`（+`price`），只允许四则/比较/`and or not`
-与 `abs/min/max`；求值在计算层按 AST 白名单执行，导入、属性、下标一律拒绝 ——
-**它不是「让模型写代码」的通道**，只是把「自己组合的指标」做成条件。
-
-需要**先后顺序**时用**链式条件**（`kind=chain`）：`steps` 给 2–3 步，前一步满足只记进度、不叫醒，
-最后一步也满足才叫醒；`chain_expire_min`（默认 240 分钟）控制前一步的有效期，过期退回第一步。
-
-```
-先站上 80000，之后跌破 79500 再叫我
-  → steps=[{price >= 80000}, {price <= 79500}]
-```
-
-多条条件之间是**或**（任一条命中即叫醒）；「且」用 `formula` 表达式里的 `and`。
-
-平台选择：`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` 会确保一个**独立的后端进程**在跑，它按**模型自己决定的间隔**巡检：
-
-- 行情由后端按 `BTC_SYNC_INTERVAL_MIN`（默认 15 分钟）**自动增量同步**，与是否巡检无关；
-- 每轮巡检会取行情、算三周期打分与 1h 择时、给结论，然后自己决定下次什么时候再看
-  —— 例如判断「4 小时线接近触发，45 分钟后复核」；
-- 计划写进一个**排期队列**（`~/.btc/run/schedules.json`），后台每 60 秒检查一次，
-  到点就执行 —— 不是 sleep，所以你随时能让它多排一次检查，不用等它「睡醒」；
-- 间隔被限制在 **10 分钟到 12 小时**之间：太短会连续调模型烧钱，太长会错过行情；
-- **关键时点由代码兜底**，不依赖模型记性：日线收盘（北京 08:00）、资金费结算
-  （北京 00:00 / 08:00 / 16:00）、有持仓时的 4 小时线收盘、以及价格较上次巡检波动 ≥2.5%
-  都会额外触发一轮巡检（波动触发 10 分钟内不重复）；
-- **改期 / 取消**：直接说「30 分钟后再看」，agent 用 `btc_schedule` 改写下一跳（原计划自动取消）；
-  说「取消这次巡检」用 `btc_unschedule`；`xzh btc status` 会列出每条计划的短 id 供精确撤销；
-- **退出界面不会停它**，下次进入复用同一个进程（不会重复启动）；`xzh btc stop` 才停；
-- `xzh btc status` 看最近结论、队列条数、下一条计划与理由（后端停了也会显示待执行计划）；
-- **每轮巡检先核对上次动作**：上一轮挂的限价单成交了吗？成交后止损挂上了吗？
-  平仓到底平掉没有？这些由代码在巡检开始前核对（`run/actions.jsonl` 账本），
-  发现「持仓无止损」「距强平 <5%」「挂单堆积」会直接写进本轮提示词并要求优先处理；
-- **过程实时可见**：巡检的思考、工具调用与结论会以 `[后台 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%（开平各一次），不计资金费 |
-| 杠杆 | **默认 9x**（`BTC_PAPER_LEVERAGE` 可覆盖），由 xzh 按可用余额与信心调整；余额不足时自动提到「够开这一单」，**上限 20x**，显式给的倍率不会被改写 |
-| 持仓 | 同时只允许一个持仓；可挂多档（最多 5 张未成交） |
-| 初始资金 | 默认 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 单：
-
-- **可以多档**：`orders: [{limit_price, notional}, …]` 一次挂好分批接单（每档独立时效、独立撤单）；
-- **开仓前算保证金**：总名义 ÷ 杠杆 + 手续费 ≤ 可用余额 × 0.95，超了直接拒绝并给出「最多可开多少名义」；
-- 不追价、不立即成交，**挂到时效（`expires_min`，默认 60 分钟）、下一次买卖点或主动撤单为止**；
-- 未成交前不算持仓，面板与 `btc_orders` 里显示为挂单；
-- 到下一次巡检、或三周期打分变了仍未成交 → 由 agent 决定「继续等」还是 `btc_cancel all=true` 撤掉；
-- **时效到点仍未成交 / 只部分成交 → 后端主动叫醒一轮巡检**（每 5 分钟检查），
-  由 agent 决定撤单、改价，还是明确继续等并给新时效；它**不会自动撤单**；
-- 止损/止盈作为 `closePosition` 条件单一起挂（触发时按当时仓位全平）；
-- 模拟盘同规则：价格到达限价即成交；限价被穿越时按市价成交（用实时标记价，取不到才用收盘价），
-  挂单同样带时效，且允许同时挂多档（成交后按加权均价合并成一个持仓）。
-
-**平仓由 agent 判断用市价还是限价**（`btc_close` 的 `mode`）：
-
-- 市价（默认）：确定出场、接受滑点 —— 临近止损/强平、行情快速时用它；
-- 限价：控滑点，但**未成交前仓位与止损都还在**，必须给 `expires_min`；
-  挂在不成交侧时工具会明确警告，超时由后端叫醒处理；
-- 市价平仓会回报成交均价与估算盈亏，限价平仓在成交前不算「已平仓」。
-
-平仓（`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 本位合约
- 79,350.40  -1.20%
- ─────────────
- 权益 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
- ─────────────
- 风控 正常
-  持仓亏损 50% · 当日 10%
- ─────────────
- 监控（每 5 分钟）
- 2 条条件 · 下次评估 3 分 20 秒后
-   · 价格 >= 80000 · 现 79350 · 仅 21–24 点
-   · 1h rsi <= 30 · 现 42.8
- ─────────────
- 最近交易
- 22:10 空 1.2444 80,276→79,359 +1,140.00
- 21:02 多 1.2000 78,900→79,400 -120.00
- ─────────────
- 巡检
- 23:47 · 30 分钟后
-  复核小时线
-```
-
-两段数据各有边界：
-
-- **监控**：倒计时来自后端 state（每 5 分钟评估一次叫醒条件）；后端没在跑时显示「后端未运行」。
-  面板只列前 2 条条件并附带最近观测值；描述比右栏宽时按显示宽度**折行**（每条最多 3 行），
-  不再整行截断。要看全部条件用 `/monitor`（不经过模型，直接打印配置）。
-- **最近交易**：模拟盘读虚拟账本的已平仓记录（最近 3 笔，含入场→出场与盈亏）；
-  实盘读动作账本 `run/actions.jsonl`（只含**我们自己发起**的开/平仓，手动操作不在内）。
-
-`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`（不带参数）仍然是重置对话上下文，两者互不影响。
-
-重置除了把钱改回初始值，还会**清空成交、挂单与持仓**，并把「重置前是什么状态」
-（几笔成交、实现盈亏、原持仓/挂单、现金与初始资金变化）写进项目记忆
-`~/.btc/.xuanzhu/memory/<日期>.md` —— 否则下一轮对话里 xzh 只看到「钱回到 10 万」，
-分不清是你主动重置还是数据丢了。
-
-### 只做合约，不做现货
-
-- 交易只走**合约**（`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` 录入。
-
 ## 界面布局
 
 界面分为两栏，底部状态栏横跨全宽：