xuanzhu 0.8.8 → 0.9.0

package/README.md

@@ -13,7 +13,7 @@ xzh                 # 启动
 ## 简介
 
 玄猪是一个运行在终端里的全屏 AI Agent：它能读懂你的代码库、直接读写文件、执行命令、运行测试，
-并用流式输出向你展示它的每一步思考与工具调用。内核采用了 codebuddy 的开源代码。
+并用流式输出向你展示它的每一步思考与工具调用。
 
 ```
 ╭──────────────────────────────────────────────╮
@@ -30,6 +30,13 @@ xzh                 # 启动
 - **默认全自动**：`autoApprove` 默认为 `true`，**所有工具都直接执行、不做任何确认** —— 包括写文件、执行命令、读取工作区之外的文件，以及读取凭据类文件（`~/.ssh`、`.env`、`~/.xzh/config.json` 等）。开箱即用，不打断。`/auto off` 可切换为写文件与执行命令逐项确认。
   - 如果希望读取凭据类文件时确认一次（防止密钥被读进上下文后转交给模型服务商），把 `confirmSensitiveRead` 设为 `true`，默认关闭。
 - **多轮自主执行**：自动串联工具调用完成任务，可随时 `Ctrl+C` 中断。
+- **后台任务**：跑测试 / 起 dev server 这类长命令可以 `run_in_background` 发出去 ——
+  立刻回到对话继续干活，**结束时结果自动推给模型**，不用轮询（见「后台任务」）。
+- **结构化提问（`ask_user`）**：需要你拍板时（选方案、填只有你知道的信息），模型会
+  弹出**一个问题**（带 2–4 个选项可直接按数字选），而不是把问题夹在一段总结里。
+- **自治等级（`ask` / `observe` / `auto`）**：`observe` 档下**写文件 / 执行命令一律被拦下**
+  并记进 `.xuanzhu/state/observe.log`，先看它想做什么再切 `auto` —— 比「全自动」与
+  「逐项确认」之间的二选一更好用（见「自治等级」）。
 - **请求开销与进度**：状态栏实时显示「本轮耗时 · 思考字数 · 输出字数」；未连接设备桥时
   不下发 `device_*` 工具与手机操作说明，提示词更短、首 token 更快。
 - **目标模式（`/goal`）**：设一个目标，玄猪会持续自动推进（每轮答复后立刻继续），
@@ -152,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` | 列出**所有内置可用**的模型（按服务商分组，标注已配置项） |
@@ -179,6 +196,13 @@ xzh
 | `xzh skill list` | 列出全部技能（来源与状态，含已禁用项） |
 | `xzh skill enable/disable <名称>` | 启用 / 禁用技能 |
 | `xzh skill delete <名称> [--yes]` | 删除技能（仅限用户技能；内置技能请用 disable） |
+| `xzh prompt` | 查看系统提示词的段落（哪些被覆盖、各段多少字符） |
+| `xzh prompt show [段落]` | 打印当前实际发给模型的提示词（或某段的内置原文 vs 生效内容） |
+| `xzh prompt set <段落> <文件\|->` | 用文件内容（或 stdin：`-`）覆盖某一段；空文件 = 删掉该段 |
+| `xzh prompt reset <段落\|--all>` | 取消某段 / 全部覆盖 |
+| `xzh autonomy` | 查看自治等级与最近被拦截的操作 |
+| `xzh autonomy ask\|observe\|auto` | 切换自治等级（`observe` = 改动一律拦截并记账） |
+| `xzh autonomy log [N]` | 打印观察日志（`.xuanzhu/state/observe.log`）最近 N 条 |
 | `xzh errors` | 列出玄猪自动记录的错误报告（`~/.xzh/errors/`，等价 `errors list`） |
 | `xzh errors list` | 列出全部报告（最近的在前） |
 | `xzh errors show <序号\|签名>` | 查看一份报告的完整内容（JSON） |
@@ -200,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` 整体重定向 ——
@@ -256,6 +324,7 @@ Windows 上如果希望 bash 工具使用 Git Bash / WSL 的 shell，可设置 `
 | `temperature` | `0.2` | 采样温度 |
 | `maxToolRounds` | `200` | 单轮任务内工具调用轮数上限（用尽时询问是否追加） |
 | `autoApprove` | `true` | 自动批准工具（`false` 时写文件/执行命令前询问） |
+| `autonomy` | 由 `autoApprove` 推导 | `ask` / `observe` / `auto`；`observe` 拦下写操作并记账（`/autonomy` 切换） |
 | `mouseCapture` | `true` | 接管鼠标：滚轮滚动 + 输出区拖拽选中复制（`/mouse` 切换） |
 | `confirmSensitiveRead` | `false` | 读取凭据类文件（`.env`、`~/.ssh`、`config.json` 等）时是否确认 |
 | `memoryMaxChars` | `12000` | **项目**长期记忆字符上限，超出即自动精简（`0` = 不限制长度，仍去重） |
@@ -270,6 +339,8 @@ Windows 上如果希望 bash 工具使用 Git Bash / WSL 的 shell，可设置 `
 | `intent.enabled` | `false` | 意图分析（每条消息先分析再处理） |
 | `intent.prompt` | 内置模板 | 意图分析模板，占位符 `{{'用户发送过来的消息'}}` |
 | `systemPromptExtra` | — | 追加到系统提示词的额外内容 |
+| `promptOverrides` | — | 系统提示词**分段覆盖**（`xzh prompt set` 写入；空串 = 删掉该段） |
+| `promptOverridesBase` | — | 保存覆盖时的内置指纹，升级后据此提示「原段落已变」 |
 
 > 旧版配置（只有 `provider` / `model`、没有 `models`）依然可用：会被视为唯一的一个模型。
 > 旧配置里的 `weight` / `decayed` 字段已废弃，读取时会被忽略、下次保存时自动清掉。
@@ -424,10 +495,13 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | `read_file` | 读取文件（带行号，支持偏移与行数限制） | 否 |
 | `list_dir` | 列出目录内容 | 否 |
 | `glob` | 按 `**` / `*` / `?` 模式查找文件 | 否 |
-| `grep` | 按正则搜索文件内容 | 否 |
+| `grep` | 按正则搜索文件内容；命中上限时用 `offset` 翻页（结果里会给下一个 offset） | 否 |
+| `ask_user` | 向用户提**一个**具体问题并等待回答（可给 2–4 个选项，按数字选；仅主代理可用） | 否 |
 | `write_file` | 覆盖写入文件 | 是 |
 | `edit_file` | 精确文本替换 | 是 |
-| `bash` | 执行 shell 命令 | 是 |
+| `bash` | 执行 shell 命令；`run_in_background: true` 则转后台、立刻返回 job id | 是 |
+| `bash_output` | 查看后台任务状态与最近输出（不带 `job_id` 时列出全部） | 否 |
+| `bash_kill` | 终止后台任务（连同它派生的子进程） | 是 |
 | `device_list` | 列出已连接的手机设备 | 否 |
 | `device_push` | 把脚本保存到手机（不运行） | 是 |
 | `device_run` | 把脚本推到手机并立即运行 | 是 |
@@ -436,6 +510,59 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | `device_read_screen` | 读取手机当前界面（包名 / 控件文本与位置），**以文字返回** | 否 |
 | `device_screenshot` | 截取手机屏幕，**图片随结果附给模型**（控件读不到时用它，再按坐标点击） | 否 |
 
+## 后台任务
+
+**为什么**：`npm test`、`npm run dev` 这类命令动辄几分钟、甚至根本不返回。以前只有两个选择 ——
+干等到超时（然后被截断的输出骗过去），或者中断整轮。
+
+**怎么用**：模型会对长命令自动加 `run_in_background`（你也可以直接说「把 dev server 起在后台」）。
+行为：
+
+- 立刻返回 `job-1` 与日志路径 `<项目>/.xuanzhu/jobs/job-1.log`；
+- **结束时自动把结果推给模型**（退出码 + 末尾输出），不需要轮询；
+- **结果不会丢**：先落盘再投递（`.xuanzhu/jobs/pending/`），投递成功才删 ——
+  「命令刚跑完就关掉 xzh」或「退出时被终止」都会在**下次启动**的第一轮补上，
+  且同一条结果只补一次；
+- 如果模型在等这个结果，它不会草草收尾（只提醒一次，避免把 dev server 当成阻塞）；
+- 界面：`/jobs` 列出全部任务、`/jobs job-1` 看输出、`/jobs kill job-1` 终止；
+- 退出 `xzh` 时会一并终止仍在跑的后台任务，不留孤儿进程。
+
+⚠️ 后台任务**不跨重启**：`xzh` 退出即终止。
+
+## 自治等级
+
+两个入口等价：界面 `/autonomy`，命令行 `xzh autonomy [ask|observe|auto]` / `xzh autonomy log` ——
+后者给脚本与 CI 用（那里没有人能按快捷键）。切换时会同步写 `autoApprove`，状态栏也会常驻显示当前档位
+（`⚡auto` / `ask` / `observe`）。
+
+| 档位 | 行为 |
+| --- | --- |
+| `auto`（默认） | 写文件 / 执行命令直接执行 |
+| `ask` | 每项确认后再执行 |
+| `observe` | **只观察**：这些操作一律被**代码**拦下，只往 `.xuanzhu/state/observe.log` 记一条 |
+
+`observe` 的典型用法：先让它调研并给出方案，你翻 `.xuanzhu/state/observe.log`（或 `/autonomy`
+里列出的「最近被拦截的操作」）确认它想做什么，再切 `auto` 放行。读文件、搜索、看后台输出不受限制。
+
+`/auto on|off` 仍然可用，等价于 `/autonomy auto|ask`。
+
+## 系统提示词分段覆盖
+
+不想整份重写提示词，只想改其中一段：
+
+```bash
+xzh prompt                    # 列出段落：core / tools / device / skills / trust / output / memory-global / memory-project
+xzh prompt show core          # 内置原文 vs 当前生效
+printf '## 核心原则\n先读后改，改完验证。\n' > core.md
+xzh prompt set core core.md   # 只覆盖这一段，其余继续跟随升级
+xzh prompt reset core         # 取消覆盖
+```
+
+- 覆盖写进 `~/.xzh/config.json` 的 `promptOverrides`；内容为空 = 删掉该段；
+- 内置提示词升级后会提示「你覆盖的那段原文已变」（记录在 `promptOverridesBase` 指纹里），
+  不会静默把你的文本换成新默认；
+- 界面里 `/prompt` 查看与重置，`/prompt show <段落>` 看某段内容。
+
 ## 任务拆分与子代理
 
 **任务拆分**：任务需要 3 步以上、或用户一次提出多项要求时，玄猪会先用 `todo_write`
@@ -925,7 +1052,7 @@ v2ray / Clash / mihomo / sing-box **本地 SOCKS/HTTP 入站端口**，验证后
 当任务涉及某个领域时，玄猪会先 `list_skills` 查看可用技能、再 `load_skill` 加载完整指南
 （加载时自动安装并验证其依赖），然后借助 `bash` 执行指南中描述的命令。
 
-随包内置 20 个技能，常用如下：
+随包内置 27 个技能，常用如下（`btc-*` 七个只在 `xzh btc` 模式下可见）：
 
 | 技能 | 领域 | 依赖 |
 | --- | --- | --- |
@@ -934,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` |
@@ -964,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` 录入。
+
 ## 界面布局
 
 界面分为两栏，底部状态栏横跨全宽：
@@ -1200,6 +1581,13 @@ registry 已可见（npm 有 staging 阶段，期间 `npm view` / `npm install`
   [Oyinlola Olasunkanmi Raymond](https://github.com/olasunkanmi-SE)。
   玄猪由该项目改造而来，依 MIT 许可**保留其原始版权声明**。
   
+- **[dsh-superagent-prototype](https://github.com/deepseek-ai/dsh-superagent-prototype)** ——
+  由 DeepSeek 开源（作者见该仓库）。玄猪的**后台任务与完成唤醒**、**结构化提问（`ask_user`）**、
+  **自治等级（`ask` / `observe` / `auto`）**与**系统提示词分段覆盖**等机制的设计思路来自该项目：
+  它把「尽量少占人的注意力」当设计准则，给出了长任务不阻塞调用方、用代码而不是提示词兜底、
+  先观察再放行等一整套可借鉴的做法。玄猪按它的设计文档与源码重新实现（未复制代码），
+  并按终端的形态做了取舍。感谢作者把这些经验公开出来。
+
 - **[Playwright](https://github.com/microsoft/playwright)** —— 由 Microsoft 开源。
   内置的 `playwright` 技能基于它实现浏览器自动化与端到端测试。