AlphaBound 手册

有边界的自主投资 Agent — 在明确风险边界内，通过持续网络研究、基本面分析、事件调查、市场情绪理解和长期记忆，自主管理 BTC 风险暴露。

宽信息入口，慢投资决策，快风险反应，窄交易出口。

一句话理解

把「AI 自主交易」拆成两个正交问题：

• 策略自主性交给 LLM Agent（观察、调查、假设、提案、反思）
• 资金安全交给确定性代码（状态引擎、风险内核、幂等执行）

Agent 可以提出任何交易观点，但不能直接调用交易凭证，也不能修改最大回撤边界。通往交易所的唯一路径是：

结构化 Proposal → Risk Kernel 准入 → Execution Engine 幂等下单

本手册怎么读

风险说明

「最大回撤 10%」是系统工程目标，不是绝对保证。极端跳空、流动性消失、交易所故障、网络中断或成交延迟均可能造成边界穿透。系统尽力提前保留退出缓冲，并如实记录任何突破。

文档构建

本手册由 mdBook 维护，源文件在仓库 book/src/。

# 需要 mdbook ≥ 0.4（本机可用 Homebrew: brew install mdbook）
./scripts/build-docs.sh          # 构建到 book/book/
./scripts/build-docs.sh serve    # 本地预览 http://localhost:3000

CI 在每次 push / PR 会执行 mdbook build，保证链接与语法不过期。

快速开始

本页带你在开发机上完成：构建 →（可选）钥匙串密钥 → 自检 → shadow 冒烟 → Dashboard。
shadow 永不下单：公共行情 + 模拟账户；有密钥时额外做只读私有余额探测（Gate 1 连通性）。

前置条件

zig version   # 期望输出 0.16.0

1. 克隆与构建

git clone git@github.com:talkincode/alphabound.git
cd alphabound

zig build -Doptimize=ReleaseSafe   # 产出 zig-out/bin/alphabound
zig build test

2. 本地配置

仓库提供开箱配置 config/local.toml：

• DB：var/trading.db（先 mkdir -p var）
• Web：127.0.0.1:18180（config/local.toml；避开 8080 / 18080 常见占用）
• mode = "shadow"

mkdir -p var

硬约束：web.bind 只能是 127.0.0.1:port 或容器用 0.0.0.0:port。远程访问走 SSH tunnel。

3. （可选）从 macOS 钥匙串加载 OKX 密钥

钥匙串 service 名约定：OKX_API_KEY、OKX_API_SECRET、OKX_API_PASSPHRASE
（兼容旧名 OKX_API_ Passphrase）。

./scripts/load-okx-keychain.sh ./secrets.env   # 0600，已 gitignore
set -a && source ./secrets.env && set +a      # 值已 shell 转义，支持 passphrase 含 &

# 或一键：
./scripts/run-local.sh --self-check
./scripts/run-local.sh --ticks 5

私有只读前提：OKX API Key 的 IP 白名单须包含本机公网 IP。未放行时日志为 private balance FAILED: ip_whitelist——签名已通，属运维策略，shadow 公共路径仍可跑。

curl -sS https://api.ipify.org; echo   # 把该 IP 加到 OKX API Key 白名单

4. 自检

./zig-out/bin/alphabound --config config/local.toml --self-check

成功打印 config_hash、mode、db、web、okx_keys: present|absent。若有密钥会尝试 /api/v5/account/balance（只读）。

5. 有界 shadow 运行

./zig-out/bin/alphabound --config config/local.toml --ticks 5

期望日志：

[boot] OKX credentials present (key_len=... secret_len=... pass_len=... simulated=false)
[connect] okx server time ...
[reconcile] private balance ...   # ok 或 ip_whitelist
[ready] mode=shadow live BTC-USDT data, simulated engine cash 100 USDT, web 127.0.0.1:18180, private_keys=yes, agent=on
[tick 0] bid ... equity 100 dd 0 mode normal
[shutdown] draining after 5 ticks

mode=live 在 Gate 4 前会被进程直接拒绝。

6. 探活与 Dashboard

常驻或加长 --ticks 时：

curl -s http://127.0.0.1:18180/health/live
curl -s http://127.0.0.1:18180/health/ready
curl -s http://127.0.0.1:18180/api/v1/state
open http://127.0.0.1:18180/

7. 查库

sqlite3 var/trading.db \
  "SELECT type, severity FROM events ORDER BY seq DESC LIMIT 10;"

常见事件：RECONCILE_COMPLETED / STATE_READY / PRIVATE_BALANCE_OK|FAILED / SHUTDOWN_CLEAN。

8. 优雅退出

# Ctrl-C 或
kill -TERM <pid>

9. 配置 LLM Agent（可选）

有 OpenAI 兼容 apiurl / key / model 时，写入 secrets.env：

# secrets.env 追加（chmod 600；值请自行替换）
LLM_API_KEY='你的key'
LLM_API_URL='https://你的兼容端点/v1'   # 不要带 /chat/completions
LLM_MODEL='你的模型名'

set -a && source ./secrets.env && set +a
./zig-out/bin/alphabound --config config/local.toml --agent-once --ticks 5

完整说明 → Agent 配置（OpenAI）

下一步

• 配置项 → 配置参考
• Agent → Agent 配置（OpenAI）
• 模式差异 → 运行模式
• Docker/GHCR → Docker 与 GHCR
• 运维 → 运维部署

配置参考

配置文件为 TOML。生产约定路径：

密钥绝不写入 TOML，也绝不进入 Agent Context。

仓库示例：config/alphabound.toml。

完整示例

[app]
environment = "production"       # development | production
instance_id = "azure-btc-01"     # 写入事件，便于多实例区分

[exchange]
provider = "okx"
instrument = "BTC-USDT"
mode = "shadow"                  # shadow | demo | live
# rest_url = "https://www.okx.com"
poll_interval_ms = 5000

[risk]
max_drawdown = 0.10              # 不可热加载；Agent 不可修改
valuation = "conservative_liquidation"
allow_runtime_override = false
taker_fee_rate = 0.001
slippage_rate = 0.0005
initial_capital = 100.0          # shadow 模拟起始资金 (USDT)

[agent]
provider = "configured-adapter"
model = "configured-model"
decision_timeout_ms = 30000
prompt_dir = "/etc/alphabound/prompts"

[storage]
path = "/var/lib/alphabound/trading.db"
wal = true

[web]
bind = "127.0.0.1:8080"
static_dir = "/opt/alphabound/ui/current"   # 预留；当前 Dashboard 已嵌入二进制

分段说明

[app]

[exchange]

[risk] — 硬边界区

改 max_drawdown / 费率类参数 = 版本发布 + 人工确认，不是运行中调参。

[agent]

详见专章 Agent 配置（OpenAI）。

慢环调度是多因素的：活跃/静默时段各有基础节奏，价格突变、回撤加深、 风险模式切换会提前触发一次决策，且所有触发都受 decision_min_interval_ms 冷却下限约束。风险内核不受此影响——它始终在快环独立执行。 每次触发在事件流记录 AGENT_TRIGGER（含 reason），便于审计调用频率。

[storage]

不要把 DB 放在网络文件系统上。

[web]

密钥环境变量（secrets.env）

密钥只经环境变量注入（systemd EnvironmentFile=、shell source、或 macOS 钥匙串导出）。禁止写入 TOML。

# secrets.env  (chmod 0600) — 见 secrets.env.example
OKX_API_KEY=...
OKX_API_SECRET=...
OKX_API_PASSPHRASE=...
# OKX_SIMULATED=1          # 仅演示盘密钥
LLM_API_KEY=
LLM_API_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini

macOS 本地：

./scripts/load-okx-keychain.sh ./secrets.env   # Keychain → 0600 文件（值已 shell-quote）
set -a && source ./secrets.env && set +a

进程只记录 key_len / secret_len / pass_len，从不打印密钥。有密钥时 shadow 会 只读 调用 GET /api/v5/account/balance；引擎现金仍用 initial_capital 模拟，不下单。

日志与事件经 observability/redaction.zig 脱敏；不要把 secrets.env 贴进 issue 或聊天。

校验与哈希

• --self-check：解析 TOML、打开 DB、migration、bind；若有 OKX_* 则做私有只读探测。
• 每次启动计算 config_hash（SHA-256），写入事件信封。
• mode=live 在 Gate 4 前启动即失败；mode=demo 无密钥失败。

热加载边界

Agent 没有写配置的代码路径——这是能力缺失，不是 prompt 约定。

Agent 配置（OpenAI 兼容）

AlphaBound 慢决策环使用 OpenAI Chat Completions 兼容 API。
shadow 下会生成并审计 Decision Proposal，绝不下单。

你需要准备

1. 写密钥（环境变量，不要写 TOML）

方式 A：手写 secrets.env

./scripts/load-okx-keychain.sh ./secrets.env   # 可选 OKX

cat >> secrets.env <<'EOF'
LLM_API_KEY='你的key'
LLM_API_URL='https://api.openai.com/v1'   # 或 Azure: https://xxx.openai.azure.com/openai/v1
LLM_MODEL='你的模型名或Azure部署名'
EOF
chmod 600 secrets.env
set -a && source ./secrets.env && set +a

方式 B：macOS 钥匙串

支持 service 名：

./scripts/load-llm-keychain.sh ./secrets.env
# 若钥匙串没有 model，默认 gpt-4o-mini —— Azure 上通常要改成真实 Deployment 名：
# 编辑 secrets.env 里 LLM_MODEL='你的deployment'
set -a && source ./secrets.env && set +a

Azure OpenAI：LLM_MODEL 必须是门户里的 Deployment 名称（不是随便写的模型 id）。
若日志出现 deployment_not_found，只改 LLM_MODEL 即可。

别名：OPENAI_* / AZURE_OPENAI_* 均可。

2. TOML [agent]（非密钥）

config/local.toml：

[agent]
provider = "openai"
model = "gpt-4o-mini"                 # 可被 LLM_MODEL 覆盖
base_url = "https://api.openai.com/v1" # 可被 LLM_API_URL 覆盖
decision_timeout_ms = 30000
decision_interval_ms = 60000          # 慢环间隔；0=不按间隔调度
prompt_dir = "prompts"
enabled = true                        # false 则永不调模型

系统提示词：仓库内 prompts/system.md（已嵌入二进制）。

3. 运行

mkdir -p var
zig build -Doptimize=ReleaseSafe

# 自检（打印 agent 配置是否读到密钥，不强制调模型）
./zig-out/bin/alphabound --config config/local.toml --self-check

# 就绪后立刻做 1 次决策 + 跑若干 tick
./zig-out/bin/alphabound --config config/local.toml --agent-once --ticks 5

# 常驻：按 decision_interval_ms 周期决策
./scripts/run-local.sh

成功日志示例：

[boot] LLM credentials present (key_len=... base_url=https://... model=...)
[agent] calling https://... model=... snap=...
[agent] proposal ok id=dec_... action=HOLD ... (shadow: not executed)

失败（超时/坏 JSON/鉴权）→ HOLD，写 agent_runs 状态，不影响行情环。

4. 查审计

每次慢环会先拉 market.ticker / market.candles（OKX 公共 REST），写入 tool_calls，再把观察塞进 Context 的 tool_observations（data 不可信）。

# 汇总有效提案率
./zig-out/bin/alphabound --config config/local.toml --agent-stats

sqlite3 var/trading.db \
  "SELECT run_id,model,status,snapshot_version FROM agent_runs ORDER BY started_ts DESC LIMIT 5;"

sqlite3 var/trading.db \
  "SELECT tool,source,latency_ms,substr(result_digest,1,16) FROM tool_calls ORDER BY id DESC LIMIT 10;"

# 提案摘要在 events.payload_json（shadow 永不 executed）
sqlite3 var/trading.db \
  "SELECT type,severity,payload_json FROM events WHERE type LIKE 'AGENT_%' ORDER BY seq DESC LIMIT 5;"

成功日志形如：

[agent] calling ... tools=2
[agent] proposal ok id=dec_... action=HOLD target_btc=0 conf=0.75 (shadow: not executed)

优先级

1. 环境变量 LLM_* / OPENAI_*
2. TOML [agent] model / base_url
3. 无 LLM_API_KEY → agent 关闭，仅行情 shadow

安全

• Key 不进 git、不进 Dashboard、不进 Agent Context
• 提案在 shadow 不进执行层
• mode=live 仍被进程拒绝（Gate 4 前）

Reflection（决策后）

提案校验通过后会再跑一轮 Reflection：

1. 默认 llm_reflection = true：第二次 LLM 调用（prompts/reflection.md），产出严格 Schema 的 memory_ops 并写入记忆库。
2. LLM 失败 / 坏 JSON / Schema 拒绝 → fail-closed，回退确定性 shadow reflection（不改订单路径）。
3. 环境变量 ALPHABOUND_LLM_REFLECTION=0 可强制关闭 LLM reflection。

相关事件：AGENT_REFLECTION_OK、AGENT_REFLECTION_LLM_FAILED、AGENT_REFLECTION_INVALID。

短 soak

./scripts/soak-shadow.sh 20

CLI 参考

二进制：zig-out/bin/alphabound（安装后常见路径 /opt/alphabound/current/alphabound）。

用法

alphabound [--config PATH] [--self-check] [--version] [--ticks N]
           [--agent-once] [--agent-stats]
           [--control pause|resume|reconcile|cancel-all|flatten|shutdown|status]

无参或非法参数时打印 usage 并以非零退出。

参数

退出码

生命周期日志锚点

便于 journalctl -u alphabound -f 过滤：

常用配方

# 版本
./zig-out/bin/alphabound --version

# 配置与 DB 冒烟（无外网也可部分通过；self-check 当前会开库写 migration）
./zig-out/bin/alphabound --config /etc/alphabound/alphabound.toml --self-check

# 本地有界验证
./zig-out/bin/alphabound --config /tmp/ab-dev/dev.toml --ticks 10

# Agent 一轮 + 统计（需 secrets.env）
set -a && source ./secrets.env && set +a
./zig-out/bin/alphabound --config config/local.toml --agent-once --ticks 5
./zig-out/bin/alphabound --config config/local.toml --agent-stats

# 常驻（前台）；生产用 systemd，见运维章
./zig-out/bin/alphabound --config /tmp/ab-dev/dev.toml

信号处理

管理命令

设计要求 pause / resume / reconcile / cancel-all / flatten / safe-shutdown 走本机 CLI（控制文件），不走公网 HTTP。详见 Admin control。

Gate 2 阈值快照（daemon 已在跑时）：

./scripts/gate2-report.sh

Dashboard 与 API

Web 面默认只绑 127.0.0.1。远程看盘用 SSH 本地转发，不要把端口暴露到公网。

ssh -L 18180:127.0.0.1:18180 user@your-vm
# 本机浏览器打开 http://127.0.0.1:18180/

本地默认配置见 config/local.toml（端口 18180，避免与其他桌面服务抢 18080）。

Dashboard

概览图表使用 Lightweight Charts（CDN）。周期按钮：分时（1m 收盘面积图）、1分/5分/15分/1时/4时/1日。离线无 CDN 时其余 UI 仍可用。

本地打开

set -a && source ./secrets.env && set +a
./zig-out/bin/alphabound --config config/local.toml --ticks 0 &
open http://127.0.0.1:18180/

HTTP API

全部为 GET；其它方法返回 405。响应体在请求缓冲区内拷贝，避免与核心环 seqlock 竞态。

GET /health/live

{"status":"ok"}

GET /health/ready

GET /api/v1/state

组合快照：risk_mode、cash_usdt、btc_total、bid_price、conservative_equity、high_watermark、drawdown、version、as_of_ms、software_version、config_hash。

GET /api/v1/events

最近事件 JSON 数组（由核心环从 SQLite 预渲染）。

GET /api/v1/agent-runs

最近 agent_runs 行（newest first）：run_id、status、model、snapshot_version、digests、时间戳。

GET /api/v1/equity

最近 equity_samples：ts、equity、hwm、drawdown、cash、btc_value。

GET /api/v1/shadow

影子 vs buy-and-hold 对比：

{
  "shadow_equity": "100",
  "bh_equity": "99.80",
  "alpha": "0.20",
  "entry_bid": "64600",
  "bh_btc": "0.00154"
}

BH 在首个有效 bid 按 initial_capital 与 taker fee 初始化；shadow 仍可 HOLD 全现金，故短期 alpha 常为正（未承担 BTC 风险）。

规划中的 API

安全边界

1. 无交易按钮暴露在公网 — 清仓 / 暂停走本机管理通道。
2. 响应中的密钥 — API 状态快照不含凭证。
3. Agent 不读 HTTP — Dashboard 是人的只读窗，不是 Agent 工具。

curl 速查

HOST=http://127.0.0.1:18180
curl -sS "$HOST/health/live"
curl -sS "$HOST/health/ready"
curl -sS "$HOST/api/v1/state" | jq .
curl -sS "$HOST/api/v1/shadow" | jq .
curl -sS "$HOST/api/v1/agent-runs" | jq .
curl -sS "$HOST/api/v1/equity" | jq .
curl -sS "$HOST/api/v1/events" | jq '.[0:3]'
curl -sS -o /dev/null -w "%{http_code}\n" "$HOST/"

GET /api/v1/candles

OKX 公共 1H K 线缓存（最多 48 根，时间升序）：

{
  "instrument": "BTC-USDT",
  "bar": "1H",
  "candles": [
    {"ts_ms": 1786237200000, "o": "64978.2", "h": "65011.4", "l": "64850", "c": "64871.3", "vol": "50.98"}
  ]
}

核心环约每 5s 刷新一次；失败时保留上一份缓存（或空数组）。

GET /api/v1/memories

最新版本记忆（newest first）：memory_id、version、kind、status、confidence、evidence_count、content、created_ts。

Shadow 启动时若库空会 seed W_shadow_policy / H_btc_spot_default；每次有效提案写入 episodic E_<run_id> 并更新 W_last_decision。

GET /api/v1/system

进程与 agent 统计（核心环刷新）：

{
  "software_version": "0.1.0",
  "mode": "shadow",
  "uptime_ms": 12000,
  "memories": 6,
  "private_keys": true,
  "private_ws_opt_in": false,
  "agent": {"total": 4, "ok": 3, "invalid": 0, "errors": 1, "valid_rate": 75.0, "tool_calls": 8}
}

SQLite 备份

主环约每小时调用 SQLite Backup API，写入 <db_path>.bak，事件 BACKUP_DONE / BACKUP_FAILED。

GET /api/v1/decisions

Agent 相关审计事件（newest first，最多约 80 条）：AGENT_PROPOSAL_OK / AGENT_INVALID_* / AGENT_LLM_FAILED / AGENT_REFLECTION_*。
Dashboard「决策历史」标签页消费此接口。

运行模式

[exchange] mode 控制「钱是不是真的、单会不会发」。

shadow（默认）

• 连接 OKX 公共 REST（时间、ticker 等），不需要 API Key。
• 启动时注入模拟账户（initial_capital USDT，BTC=0），reconcile_result 标记 clean。
• 风险内核、状态机、事件落库、Dashboard 全链路真实代码路径。
• Agent 若接入，提案可算、可审计，但执行层不得对实盘发单。

适合：

./zig-out/bin/alphabound --config dev.toml --ticks 20

demo

• 使用 OKX 模拟盘密钥 + 请求头 x-simulated-trading: 1（环境变量 OKX_SIMULATED=1 必填）。
• 引擎现金/BTC 来自私有 REST 余额（不再用 shadow 的 initial_capital）。
• Agent 提案经 Risk 准入后：APPROVE/REDUCE → planner → 市价单；HTTP 失败 → UNKNOWN → 查询后处置。
• Admin：cancel-all 会拉取 pending 并撤单；flatten 切风险态。
• Gate 3 / AC-GO8：连续稳定 ≥7 天 + 至少一次断线恢复与版本回滚演练。清单：GATE3_CHECKLIST.md。

export OKX_API_KEY=...
export OKX_API_SECRET=...
export OKX_API_PASSPHRASE=...
export OKX_SIMULATED=1
# config: mode = "demo"
./zig-out/bin/alphabound --config config/local.toml --agent-once --ticks 8
# 日志: admit=APPROVE|REDUCE exec=filled|acked|...

切换前检查清单：

1. mode = "demo" 且 OKX_SIMULATED=1（缺一则 boot FATAL）
2. Demo 密钥权限最小化；出口 IP 在 OKX 白名单
3. --self-check 私有余额通过
4. ready 探针在对账后变绿
5. live 仍被代码拒绝，勿改 mode 碰运气

live

• 真金白银。设计默认实验资金 100 USDT。
• 当前二进制直接拒绝 mode=live（Gate 4 前）。
• 进入条件：路线图 Gate 3 + 验收矩阵 P0–P3 相关条目全绿；任何无法解释的状态不一致都阻止实盘。
• max_drawdown、费率、滑点等已按发版流程冻结。
• 建议：先 shadow 长跑 → demo 7 日 → live，禁止从开发配置直接改 live。

模式与风险状态机正交

无论哪种 mode，进程内风险模式仍是：

NORMAL → EXIT_ONLY → FLATTENING → HALTED

• 数据陈旧 / 未对账 → fail-closed，常从 EXIT_ONLY 起步
• 回撤边界触发 → FLATTENING → 完成后可 HALTED
• HALTED 不自动恢复交易，需人工与发版流程介入

shadow 下也会演练状态机（例如人工压测陈旧数据），只是不会碰到真实资金。

切换操作建议

# 1. 改配置（新文件或发版产物），不要热改内存
mode = "demo"   # 或 live

# 2. 自检
alphabound --config /etc/alphabound/alphabound.toml --self-check

# 3. 原子发布 / restart（见运维章）
sudo systemctl restart alphabound
curl -sS --retry 30 --retry-delay 1 --fail \
  http://127.0.0.1:8080/health/ready

切换到 live 时在变更单中记录：config_hash、软件版本、操作人、回滚版本路径。

运维部署

目标形态：单文件二进制 + systemd + SQLite 本地盘 + SSH tunnel 看盘。生产 VM 不装 Docker / 运行时 Node / Python 业务依赖。

目录约定

系统用户

sudo useradd --system --home /var/lib/alphabound --shell /usr/sbin/nologin alphabound
sudo mkdir -p /var/lib/alphabound/backups /etc/alphabound/prompts
sudo chown -R alphabound:alphabound /var/lib/alphabound
sudo chown -R root:alphabound /etc/alphabound
sudo chmod 750 /etc/alphabound
sudo chmod 640 /etc/alphabound/alphabound.toml
sudo chmod 600 /etc/alphabound/secrets.env

systemd

仓库模板：deploy/alphabound.service

sudo cp deploy/alphabound.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now alphabound
sudo systemctl status alphabound
journalctl -u alphabound -f

单元要点：

• EnvironmentFile=/etc/alphabound/secrets.env
• ProtectSystem=strict + ReadWritePaths=/var/lib/alphabound
• NoNewPrivileges / PrivateTmp / 清空 Capability
• Restart=always + RestartSec=5（崩溃后重新对账，不假设旧内存状态）

发布与回滚（原子 symlink）

VER=0.1.0+git.$(git rev-parse --short HEAD)
REL=/opt/alphabound/releases/$VER
sudo mkdir -p "$REL"
sudo cp zig-out/bin/alphabound "$REL/"
sudo chmod 755 "$REL/alphabound"

# 记录 previous，切换 current
if [ -L /opt/alphabound/current ]; then
  sudo ln -sfn "$(readlink -f /opt/alphabound/current)" /opt/alphabound/previous
fi
sudo ln -sfn "$REL" /opt/alphabound/current

sudo systemctl restart alphabound

# ready 门禁：失败则回滚
if ! curl -fsS --retry 30 --retry-delay 1 http://127.0.0.1:8080/health/ready; then
  echo "ready failed — rolling back"
  sudo ln -sfn "$(readlink -f /opt/alphabound/previous)" /opt/alphabound/current
  sudo systemctl restart alphabound
  exit 1
fi

后续可用 deploy/release.sh 固化上述流程（脚本随仓库演进）。

备份

SQLite 在线备份优先用 Backup API 或安全的文件快照（注意 WAL）：

# 示例：sqlite3 .backup（进程可同时运行，注意 IO）
stamp=$(date -u +%Y%m%dT%H%M%SZ)
sqlite3 /var/lib/alphabound/trading.db \
  ".backup '/var/lib/alphabound/backups/trading-$stamp.db'"

# 保留策略示例：7 日
find /var/lib/alphabound/backups -name 'trading-*.db' -mtime +7 -delete

恢复演练（建议每周）：

1. 停服务或切只读副本
2. 恢复到临时路径，PRAGMA integrity_check
3. 用恢复库启动 shadow/--self-check，核对 HWM / 最近事件
4. 记录演练结果到变更日志

远程看盘

ssh -N -L 8080:127.0.0.1:8080 ops@azure-btc-01

防火墙：不对 8080 放行公网。管理动作不走 Dashboard。

资源与告警（建议）

Azure / 网络

• 选型时测 OKX REST / WS 与 LLM 端点延迟（p50/p95）
• 出站白名单：OKX、LLM、必要工具域名；无通用网页爬取权限给 Agent 进程
• NTP 可靠；日志统一 UTC

安全检查清单

• secrets.env 0600，不进 git、不进备份的明文 tar 传到个人笔记本
• 服务用户无 shell、无 sudo
• web 仍为 127.0.0.1（容器场景：容器内可 0.0.0.0，宿主机只映射 127.0.0.1）
• mode 与资金环境一致（live 有变更单）
• 上一个 previous symlink 可回滚
• 备份恢复演练未过期

容器分发与 GHCR 发布见 Docker 与 GHCR。

本机管理控制

AlphaBound 管理命令不走网络：CLI 写入 DB 同目录控制文件，daemon 主环每 tick 消费一次。

命令

./zig-out/bin/alphabound --config config/local.toml --control pause
./zig-out/bin/alphabound --config config/local.toml --control resume
./zig-out/bin/alphabound --config config/local.toml --control reconcile
./zig-out/bin/alphabound --config config/local.toml --control cancel-all
./zig-out/bin/alphabound --config config/local.toml --control flatten
./zig-out/bin/alphabound --config config/local.toml --control shutdown
./zig-out/bin/alphabound --config config/local.toml --control status

控制文件：var/trading.control（one-shot，消费后删除）
状态文件：var/trading.control.state

Dashboard /api/v1/system 含 "paused": true|false。

Docker 与 GHCR 发布

设计默认生产形态仍是 Azure VM + systemd 裸二进制。Docker 镜像用于：

• 可复现的 release 分发（GHCR）
• 本地 / CI shadow 实验室
• 多架构（linux/amd64（arm64 可后续加回））预构建

不是「上了 Docker 就等于生产就绪」——真钱闸门见 路线图。

镜像

拉取

# 公共包可直接拉；若包仍是 private，先登录
echo $GHCR_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

docker pull ghcr.io/talkincode/alphabound:0.1.0   # 推荐：与 git tag v0.1.0 对应
docker pull ghcr.io/talkincode/alphabound:latest  # 最近一次 v* 发布

首次 push 后若组织默认 private package，在 GitHub → Packages → alphabound → Package settings → Change visibility → Public（或保持 private 仅 CI/内部拉）。

运行（shadow）

docker run --rm \
  --name alphabound \
  -p 127.0.0.1:8080:8080 \
  -v alphabound-data:/var/lib/alphabound \
  ghcr.io/talkincode/alphabound:latest

curl -sS http://127.0.0.1:8080/health/live
open http://127.0.0.1:8080/

自检：

docker run --rm ghcr.io/talkincode/alphabound:latest \
  --config /etc/alphabound/alphabound.toml --self-check

Compose

docker compose up --build          # 本地构建
IMAGE=ghcr.io/talkincode/alphabound:latest docker compose up

docker-compose.yml 已写死 127.0.0.1:8080:8080。

自定义配置

docker run --rm -p 127.0.0.1:8080:8080 \
  -v "$PWD/my.toml:/etc/alphabound/alphabound.toml:ro" \
  -v alphabound-data:/var/lib/alphabound \
  ghcr.io/talkincode/alphabound:latest

[web] bind 在容器内应为 0.0.0.0:<port>，否则 port-publish 进不来。配置解析拒绝任意公网 IP 绑定，只允许 127.0.0.1 与 0.0.0.0。

CI 发布

工作流：.github/workflows/release-docker.yml

使用 docker/build-push-action + Buildx，linux/amd64，GHA cache，provenance/SBOM 开启。权限：packages: write（GITHUB_TOKEN）。

构建上下文必须包含 prompts/（嵌入二进制）；.dockerignore 不得排除 prompts/**。

打版本 release

git tag -a v0.1.0 -m "alphabound v0.1.0"
git push origin v0.1.0
# Actions → Release Docker → ghcr.io/talkincode/alphabound:0.1.0 等

本地构建

docker build -t alphabound:local .
docker run --rm -p 127.0.0.1:8080:8080 alphabound:local --ticks 3

需要 Docker Buildx（多架构时）与出网下载 Zig 0.16.0。

安全注意

1. 不要把 secrets.env 打进镜像层；用 runtime 挂载 / orchestrator secret。
2. 宿主机端口只绑 127.0.0.1；远程用 SSH tunnel。
3. 镜像默认 mode = shadow，无交易密钥也跑得起来。
4. 容器 ≠ 过 Gate 3；Demo/Live 仍走验收矩阵。

故障排查

按「先安全、后功能」顺序：确保不会错误增仓，再修观察面。

启动失败

FATAL config

alphabound --config /path/to.toml --self-check

FATAL db open

• 父目录不存在或不可写 → mkdir + chown alphabound
• 磁盘满 → 腾挪 / 扩容；不要删 WAL 凑合
• 文件损坏 → 禁止静默新建空库继续 live 交易；走备份恢复（见 运维）

FATAL web listen / [web] server stopped: AddressInUse

• 端口占用：lsof -nP -iTCP:18180 -sTCP:LISTEN（或配置里的 port）
• 本机 18080 常被其他桌面工具占用 → config/local.toml 默认改用 18180
• 改 [web].bind = "127.0.0.1:<空闲端口>" 后重启
• 权限或 bind 地址被改坏（只能 loopback / 容器 0.0.0.0）
• 注意：web 线程 listen 失败时 shadow 行情环仍可继续；只是 Dashboard 不可用

连接与 READY

[connect] unreachable

• 出网 / DNS / 代理
• OKX 地域限制 → 换 Region 或合规网络路径
• rest_url 配错

shadow 在连接失败时不会假装 READY 去交易。

private balance FAILED: ip_whitelist

OKX 返回 50110：当前公网 IP 不在该 API Key 白名单。

curl -sS https://api.ipify.org; echo
# 在 OKX → API → 编辑 Key → IP 白名单中加入上述地址
# 建议：只读权限 Key，专用于 shadow/Gate1 对账

签名与 passphrase 已通过（否则会是 invalid_sign / invalid_passphrase）。shadow 仍会用公共行情 + 模拟资金进入 READY；仅私有对账未通。

OKX credentials absent 但已 source secrets

• passphrase 含 & 等字符时必须用 ./scripts/load-okx-keychain.sh 生成的 quoted secrets.env，或 export 时加引号
• 变量名必须是 OKX_API_KEY / OKX_API_SECRET / OKX_API_PASSPHRASE（不是 OKX_SECRET_KEY）
• 确认子进程继承环境：python3 -c 'import os; print(len(os.environ.get("OKX_API_KEY","")))'

/health/ready 一直 503

• 仍在 BOOTING/CONNECTING/RECONCILING
• 对账未 clean（demo/live 私有数据不一致）
• 看 journal：journalctl -u alphabound -n 100 --no-pager

live 探针绿但模式是 EXIT_ONLY

常见于：行情 freshness 不足、unresolved_orders、启动 fail-closed。这是保护，不是单纯 bug。查：

curl -s http://127.0.0.1:8080/api/v1/state | jq '{risk_mode,reconciled,drawdown}'

数据与审计

事件不涨

• 进程是否真在跑
• [journal] append failed → 磁盘、权限、SQLite busy
• 直接查库：

sqlite3 /var/lib/alphabound/trading.db "SELECT seq,type,ts FROM events ORDER BY seq DESC LIMIT 20;"

Dashboard 空白 / 不是 HTML

• 是否打到错误端口
• 旧二进制未嵌入 dashboard（升级后确认 GET / Content-Type 含 text/html）
• 浏览器控制台看 /api/v1/state 是否 CORS/连接失败（本机不应有 CORS 问题）

风险模式异常

性能

• CPU 打满：确认没有过密 poll_interval_ms；单写者状态机本就单线程热点
• RSS 爬升：抓 24h 曲线；怀疑泄漏时用固定 --ticks 对比重启基线
• 磁盘：WAL 过大时检查是否有长事务/备份锁

安全事件

若怀疑密钥泄漏：

1. 立刻在 OKX 作废 API Key
2. 停 live / 切 EXIT 能力优先的维护窗口
3. 轮换 secrets.env，限制新 Key 权限与 IP
4. 审计 events / 交易所成交是否与 decision_id 可对上

收集诊断包（脱敏）

alphabound --version
cat /etc/alphabound/alphabound.toml          # 无密钥
curl -s localhost:8080/api/v1/state
curl -s localhost:8080/health/ready
journalctl -u alphabound -n 200 --no-pager
sqlite3 /var/lib/alphabound/trading.db "PRAGMA integrity_check;"
# 不要打包 secrets.env；日志已依赖 redaction，仍人工扫一眼

测试侧回归

改代码后：

zig build test --summary all
./scripts/build-docs.sh    # 若动了手册链接

CI 应保持绿：zig build + zig build test + --self-check + mdbook build。

私有 WebSocket 探测

默认不在启动时做 OKX private WS login 探测（避免慢 DNS/IPv6 与实验性传输路径拖慢 READY）。

• Gate 1 账户可见性依赖 REST GET /api/v5/account/balance 周期对账（已验证）。
• 需要尝试 private WS 时：export ALPHABOUND_PRIVATE_WS=1 后启动。
• 若日志出现 login_read_failed 且 detail 含 close 881a0fa4…（OKX 4004 / No data received）： TLS upgrade(101) 已成功，但 login 帧在 std.http.Client 原始连接路径上仍不稳定；协议编解码单测仍有效，长连修复前请继续依赖 REST。

四支柱架构

AlphaBound 用一句话约束产品形态：

宽信息入口，慢投资决策，快风险反应，窄交易出口。

四者正交：扩大观察面不会自动加快下单；加快风险反应不依赖 LLM；出口永远收敛到同一条准入路径。

总览

        ┌──────────────────────────────────────────────┐
        │              宽信息入口 (tools)               │
        │  market / derivatives / onchain / news / …    │
        │  ToolResult.data = 不可信数据                  │
        └──────────────────────┬───────────────────────┘
                               ▼
        ┌──────────────────────────────────────────────┐
        │           慢投资决策 (agent + memory)          │
        │  Context → Investigate → Propose → Reflect    │
        │  可 HOLD · 可超时 · 不阻塞关键路径              │
        └──────────────────────┬───────────────────────┘
                               │ Decision Proposal
                               ▼
        ┌──────────────────────────────────────────────┐
        │              窄交易出口                        │
        │  Schema 校验 → Risk 准入 → 幂等 Execution     │
        └──────────────────────┬───────────────────────┘
                               │
        ┌──────────────────────┴───────────────────────┐
        │     快风险反应 (critical path, 无 LLM)         │
        │  Exchange → State Engine → Equity / SM / Admit │
        └──────────────────────────────────────────────┘

支柱 ↔ 代码

双通道 + 单写者

• 关键路径：不调用 LLM，不等待新闻/链上；目标 p99（进程内风险计算）< 10ms。
• Agent 路径：可等待、可失败；失败最多本轮无新提案。
• State Engine 是唯一状态写入者；Agent 与 Dashboard 只读不可变快照（snapshot_version）。

能力缺失，而非口头约束

下列限制必须是代码层做不到，而不是 prompt 里写「请不要」：

1. Agent 模块不依赖 OKX 密钥、签名、下单客户端
2. Agent 不能改 max_drawdown 或风险配置
3. 未绑定当前 snapshot_version 的提案必拒
4. 工具返回值不能变成系统指令（只进 data）

详见 关键不变量。

闭环

观察 → 工具调查 → 假设 → 交易提案 → 风险准入 → 执行
  ↑                                              ↓
长期记忆 ← 结果归因 ← 交易结算 ← 订单与成交事件 ←──┘

「慢」体现在决策与反思的节奏；「快」体现在边界与数据故障时的降级。两者抢同一状态时，安全侧优先（Fail Closed）。

风险模型

风险内核是确定性关键路径的核心：用可清算净值守住 HWM 回撤边界，并在准入时对提案做压力检查。

保守净值

不直接拿 mark price 当「你有多少钱」。估值扣除：

• 退出 taker 费用（taker_fee_rate）
• 退出滑点缓冲（slippage_rate）
• 挂单与未决风险（实现演进中）

相关代码：src/risk/equity.zig。

HWM 与回撤

• HWM（High Water Mark）：保守净值的历史高点，单调不减（仅在已对账数据上推进）
• Drawdown：相对 HWM 的回撤比例，与设计公式一致，非负
• 边界：drawdown ≥ max_drawdown（默认 10%）触发收敛流程

HWM 会持久化（equity 采样 / 启动恢复），避免重启「忘记」峰值。

风险状态机

NORMAL ──(数据陈旧/不一致/…)──► EXIT_ONLY
NORMAL ──(触界)──► FLATTENING ──► HALTED
任何状态在硬故障下可进入更安全侧
HALTED ──✗──► （无自动回到可开仓）

实现：src/risk/state_machine.zig。启动未 reconcile 时 fail-closed，常以 EXIT_ONLY 起步。

准入（Admission）

提案进入执行前必须通过 Risk Kernel（src/risk/admission.zig），典型检查：

1. snapshot_version 仍是当前版本
2. 数据 freshness 足够
3. 无 order ambiguity / 未对账阻断
4. 压力净值 ≥ HWM × (1 - max_drawdown) + ExitReserve（地板）
5. 输出 APPROVE / REDUCE / REJECT（可降目标仓位）

坏 JSON、缺字段的提案在 Schema 层已作废，进不了准入。

ExitReserve

边界不是贴着 10% 才跑——需要预留「刹车距离」。ExitReserve 校准依赖真实流动性与费用模型；设计承认极端行情仍可能穿透，系统职责是：

• 尽量提前动作
• 如实记录穿透幅度与成交成本（不掩饰）

与 Agent 的关系

• Agent 看不见也不配置风险参数
• 内核 不解释 thesis 是否高明，只问「这笔若成交，压力下会不会穿界」
• LLM 挂了时，风险监控与退出能力必须继续工作（NFR / 故障矩阵）

配置注意

单测覆盖见验收矩阵 AC-RK1…RK3、AC-FR05 等条目。

Agent、工具与记忆

慢循环负责「想清楚再建议」，从不直接碰下单接口。

决策闭环（设计 §5.4）

Context（agent/context.zig）

每轮送给模型的是稳定能力边界，不是聊天流水账。固定五段 JSON：

1. current_state — 净值、仓位、HWM、回撤、模式、是否已对账
2. recent_events — 有界最近事件
3. memories — 检索命中的长期记忆
4. tools — 注册表中的可用工具与时效/成本元数据
5. risk_rules — 不可变边界说明（immutable: true）

渲染字节级确定性，便于 agent_runs.input_digest 回放比对。

Proposal（agent/proposal.zig）

唯一合法「想交易」的形状。必填语义包括：

• decision_id（dec_…）
• snapshot_version
• action: HOLD | REBALANCE
• target（再平衡时 BTC 权重）
• order_policy / confidence / thesis / invalid_if / …

任何坏 JSON、缺字段、越界置信度 → 整单作废（fail-closed HOLD）。

工具注册表（tools/registry.zig）

统一 ToolResult：

status: OK | UNAVAILABLE | STALE | ERROR
source, as_of, confidence?, latency_ms, cost_usd
data_json   ← 不可信
raw_ref?

• 超时/不可用 → UNAVAILABLE，禁止把缺失编成 0
• 超过 max_age_ms 或 as_of 不明 → 有效状态降为 STALE
• 每次调用写审计（digest），供「哪些数据真改善了决策」统计

五层记忆（memory/store.zig）

版本化记录 (memory_id, version) 追加；结构化 memory_ops：

• CREATE / UPDATE / INVALIDATE / MERGE

置信度钳制在 [0,1]；非法 op 在 Reflection 解析期整篇作废。

Reflection（agent/reflection.zig）

只产出可审计结构：预期 vs 多窗口实际结果、error_type、lessons、memory_ops。
不保存隐藏 chain-of-thought。

当前实现边界

已落地（单测覆盖）：Schema、Context 渲染、Registry、Memory ops、Reflection 解析与 store 联动、DB 表与 Repo。

已本机验证：OpenAI 兼容 LLM 实调 + shadow 提案审计。仍待：具体 provider 工具、Dashboard 回放、Shadow 影子收益对比长跑。详见 路线图 Phase 2。

事件与审计

「每笔订单可追溯到 decision、快照、风控与配置」是上线硬条件之一。事件日志是真相源，Dashboard 只是视图。

事件信封

顶层字段固定，避免消费者每次挖 payload：

实现：src/core/events.zig + storage EventsRepo。

典型类型（示例）

以代码与 migration 为准；新类型必须带齐信封字段。

SQLite 表（migration 0001）

路径见配置 [storage].path；WAL 模式，单 writer。

查询示例

DB=/var/lib/alphabound/trading.db

# 最近风险相关
sqlite3 "$DB" "SELECT ts,type,correlation_id FROM events
  WHERE type LIKE 'RISK%' ORDER BY seq DESC LIMIT 20;"

# 某决策全链路
sqlite3 "$DB" "SELECT seq,type,payload_json FROM events
  WHERE correlation_id = 'dec_01J...' ORDER BY seq;"

# 净值曲线尾部
sqlite3 "$DB" "SELECT ts,equity,hwm,drawdown FROM equity_samples
  ORDER BY ts DESC LIMIT 30;"

脱敏

observability/redaction.zig 在日志路径屏蔽密钥形态字符串。原则：

• 宁可不打，也不打半截 secret
• issue / 聊天贴日志前再人工扫一遍
• 备份加密与访问控制同生产库

回放

状态引擎支持同序消息 逐位确定性 回放（单测守护）。审计争议时：

1. 取 config_hash + software_version 对齐二进制与配置
2. 按 seq 重放相关输入消息
3. 比对 state_version 与订单投影

这是 Replay 测试与事故复盘的共同基础。

构建与测试

工具链

Zig 0.16 API 与 0.13/0.14 不兼容；不要用「手头最新」随意升级。

常用命令

zig build                     # Debug 默认，产出 zig-out/bin/alphabound
zig build -Doptimize=ReleaseSafe
zig build test --summary all  # 全量单元 / 回放测试
./zig-out/bin/alphabound --self-check --config config/alphabound.toml

文档

./scripts/build-docs.sh           # mdbook build → book/book/
./scripts/build-docs.sh serve     # 预览 :3000
./scripts/build-docs.sh check     # build + 失败即非零（CI 用）

CI

工作流：

本地应用同等门槛再推送。

vendor SQLite

• 路径：vendor/sqlite/
• build.zig 编为静态库并 link_libc
• migration 经 addAnonymousImport("migration_0001", …) 嵌入
• Dashboard HTML 经 addAnonymousImport("dashboard_index_html", …) 嵌入 exe 模块

新增 migration：加 SQL 文件 + 改 build.zig import + db.zig migrations 数组。

测试层次（目标金字塔）

不要用 mock 掉 Risk Kernel 的「假绿」集成代替内核 property。

调试技巧

• 有界运行：--ticks N 避免手动杀进程
• 临时 DB：/tmp/... + 跑完删除
• 单测：zig build test --summary all 后按失败测试名定位文件
• 注意 0.16：顶层函数名不要与局部变量同名（shadowing 是编译错误）

代码结构

alphabound/
├── build.zig / build.zig.zon
├── book.toml                 # mdBook 工程（输出 book/book/，已 gitignore）
├── book/src/                 # 本手册源码（guide / concepts / dev / planning）
├── scripts/build-docs.sh     # build | serve | clean
├── .github/workflows/docs.yml
├── src/
│   ├── main.zig              # daemon 生命周期
│   ├── root.zig              # 模块导出 + refAllDecls 测试
│   ├── config.zig
│   ├── core/                 # decimal, clock, events, state
│   ├── risk/                 # equity, state_machine, admission
│   ├── execution/            # orders, planner
│   ├── agent/                # proposal, context, reflection
│   ├── tools/                # registry
│   ├── memory/               # store + retrieval
│   ├── exchange/okx/         # auth, rest, ws
│   ├── storage/              # db + repos
│   ├── web/                  # HTTP 路由与 accept 循环
│   └── observability/        # redaction
├── migrations/               # SQL
├── dashboard/index.html      # 嵌入式 Overview
├── config/alphabound.toml
├── deploy/alphabound.service
├── docs/                     # 设计分析 / 路线图 / 验收（book 规划篇 include）
└── vendor/sqlite/

模块依赖方向（允许）

main → config, storage, web, exchange, core/state, risk, …
agent → core/decimal, memory, tools   （禁止 → exchange 私钥路径）
risk  → core/decimal, state 类型
execution → core/decimal, orders 类型
tools / memory → 仅 core 与标准库

新增 use / @import 时保持：慢路径依赖快路径类型可以，反向把密钥或 socket 塞进 agent 不行。

关键入口

测试放置

• 与模块同文件的 test "…" 块（Zig 习惯）
• root.zig 的 refAllDecls 保证模块被链进测试二进制
• 未来沉重 integration 可放 tests/integration/（需凭证的勿默认跑）

关键不变量

所有代码变更不得破坏下列不变量。Code review 与 CI 测试应以它们为验收核心。

1. 权限隔离

Agent 无法访问 OKX 密钥、直接下单函数或风险配置 — 只能提交 Proposal。

• 依赖图可检查：src/agent/** 不 import 签名/下单客户端
• 密钥只在 exchange/okx/auth.zig 与进程环境

2. 快照绑定

任何提案必须绑定 snapshot_version；状态变化后旧提案自动失效。

• admission 对失配 → REJECT
• Context 里的 version 与 State Engine 一致

3. 订单幂等与 UNKNOWN

client_order_id 由 decision / 版本 / 序号导出；超时视为 UNKNOWN，先查后处置，禁止盲目重发。

• execution/orders.zig 状态机含 UNKNOWN
• 部分成交后重算差额，不原样重报

4. Fail Closed

数据过期 / 状态不一致 / 未知订单 → 进入安全状态，不增加风险。

• 未 reconcile 起步 EXIT_ONLY（或更严）
• 工具 STALE/UNAVAILABLE ≠ 数值 0

5. 边界参数冻结

max_drawdown 与 Risk Kernel 参数不可热加载，必须走版本发布 + 人工确认。

• 配置仅启动解析
• allow_runtime_override = false

6. 端到端可追溯

每笔订单可追溯到 decision_id、snapshot_version、risk decision 与 config_hash。

• 事件信封顶层字段齐全
• agent_runs / tool_calls / orders 可关联

7. 提示注入边界

工具与第三方文本是数据，不是指令。

• 只进 ToolResult.data_json
• 不拼接进系统 prompt 的指令位
• 不暴露 shell / 任意 URL / 文件系统给模型侧

8. 回撤诚实性

边界穿透时如实记录幅度与成本，不掩饰。

• 禁止在展示层「夹」回 10% 以内
• FLATTENING 过程事件完整

破坏不变量时

1. 停相关 PR 合并
2. 若已在 demo/live：切维护 / EXIT 能力，评估资金
3. 补回归测试后再发版
4. 更新验收矩阵证据

这些条目与设计 ADR、验收矩阵 上线标准 AC-GO2/GO5/GO6 对齐。

设计分析

以下内容与仓库 docs/DESIGN_ANALYSIS.md 同步引入，便于在手册内检索。

AlphaBound 系统设计分析

基于《AlphaBound System Design v0.1》(2026-08-09, MVP 设计基线)。 本文是工程视角的独立分析:评估关键决策、指出风险与薄弱点、列出实现阶段需要重点验证的事项。

1. 一句话理解

AlphaBound 把「AI 自主交易」拆成两个正交问题:策略自主性交给 LLM Agent,资金安全交给确定性代码。 Agent 拥有完整的观察、推理与提案自由,但唯一通往交易所的路径被 Risk Kernel + Execution Engine 把守; 10% 最大回撤是结果边界,不是方法约束。

2. 关键决策评估

3. 主要风险与薄弱点

3.1 边界穿透的物理极限(设计已声明,仍需强调)

10% DD 是工程目标。BTC 跳空、流动性瞬时消失时,FLATTENING 的实际成交价可能显著穿透边界。 设计的应对是 ExitReserve + 如实记录穿透,这是诚实的做法,但意味着:

• ExitReserve 校准是安全性的实际决定因素,参数错误 = 边界虚设;
• 验收必须包含「模拟极端行情下的穿透幅度测量」(fault injection + replay)。

3.2 Zig 生态缺口(Phase 0 必须回答)

• TLS 1.2/1.3 客户端(OKX + LLM API 均为 HTTPS/WSS): std.crypto 的 TLS 实现成熟度?
• WebSocket 客户端: 自研还是 vendor?断线重连、ping/pong、压缩支持。
• 建议 Phase 0 产出一份《依赖决议记录》,把每个网络组件的选型 + 验证结果写死。

3.3 LLM 结构化输出的可靠性

Proposal 是严格 JSON Schema,但模型偶发输出坏 JSON / 幻觉字段。设计的处理是校验失败即作废(HOLD), 安全但可能造成决策饥饿。指标 invalid outputs 已列入观测,建议在验收上加阈值(如 invalid rate < 5%)。

3.4 时间与时钟

签名依赖时钟同步(clock_skew 已监控),但回撤计算、evidence as_of、订单超时都依赖单调时钟与墙钟的正确区分。 Zig 层面需要明确 monotonic vs wall clock 的使用规范(core/clock 模块的职责)。

3.5 提示注入面

工具返回(news.、wallet. 标签)是不可信数据,设计已要求隔离在 data 字段。真正的执行保障在于: Agent worker 没有 shell / 文件 / 任意 URL 能力——这必须是代码层面的能力缺失,而非 prompt 层约束。 验收矩阵中对应「Agent 无法绕过 Risk Kernel / 访问密钥」的红队测试。

3.6 成本可见性

100 USDT 本金 vs LLM 调用成本:一次决策若 $0.05–0.2,高频触发会让运营成本超过本金。 设计原则 Cheap to Operate 要求成本可见,建议 Dashboard System 视图把「模型累计成本 vs 本金」做成一级指标, 并在触发策略上设成本预算闸(9.5 未决项之一)。

4. 实现阶段的关注顺序(与路线图对应)

1. Phase 0 是真正的 go/no-go: Zig TLS/WS/SQLite/长稳,任何一项不过关都影响全盘。
2. Decimal 与订单状态机先行: 全部资金计算走定点;订单 8 状态机 + 幂等 client_order_id 是 replay 测试的基础。
3. Risk Kernel 纯函数化: 无网络/无 DB/无 LLM,输入快照输出决策——这是 property test 能压住它的前提。
4. 事件日志先于功能: Event First 原则意味着 events 表 + 事件信封是所有模块的公共依赖,应最早稳定。
5. Reconcile 是恢复正确性的核心: 启动状态机 BOOTING→CONNECTING→RECONCILING→READY, 未完成对账不得开仓,值得单独的 integration 测试组。

5. 与验收的衔接

设计 9.3 节给出 8 条上线验收标准,已在 ACCEPTANCE_MATRIX.md 中 展开为「需求 → 验收标准 → 验证方法 → 所属阶段」的完整矩阵,覆盖 FR-01..10、NFR-01..06、 安全边界(7.3/7.4)、故障降级矩阵(7.2)与运维演练(8.4/7.5)。

6. 结论

设计整体成熟度高:边界清晰、失效模式想在前面、诚实面对不可保证项。 两个决定成败的赌注是 Zig 0.16 生态可行性(技术)与 ExitReserve 校准(风险)。 建议严格按 Phase 0 → 5 推进,不跳过 shadow 与 demo 阶段,每阶段以验收矩阵对应条目作为退出闸门。

路线图

以下内容与仓库 docs/ROADMAP.md 同步引入。

AlphaBound 路线图

依据系统设计 v0.1 §9.4「MVP 迭代阶段」展开,每阶段含范围、交付物、退出条件(闸门)。 阶段串行推进,退出条件未满足不得进入下一阶段;各条目与 验收矩阵 的 AC 编号对应。

当前进度(2026-08): Phase 0–3 离线组件 + shadow 在线路径已打通并通过单元测试。 本机已验证: OKX 公共行情 + 周期只读私有余额 REST 对账、market.ticker/market.candles 工具 → tool_calls 审计、OpenAI 兼容 LLM（Azure）shadow proposal ok、 agent_runs digests + AGENT_* payload、--agent-stats、GHCR 镜像、 Dashboard 提案/净值/BH/K 线/Memories/Events/System API、shadow buy-and-hold 基准、 记忆 boot 重建 + 决策环 retrieve/events + 提案 episode + LLM reflection（失败回退确定性）、小时 SQLite 备份。 私有 WS：协议单测 + TLS 握手/upgrade 实连；login 后 OKX close 4004 仍在排查， 默认跳过（ALPHABOUND_PRIVATE_WS=1 可启用探测），REST 对账仍为 Gate 1 主路径。 尚未完成: 私有 WS login 长连仍 opt-in 不稳、Gate2 长稳 soak、Demo/Live 下单闸门。 本迭代已补: shadow 准入审计、flatten/cancel-all、gate2-report.sh、shadow 账户心跳；Demo 最小下单路径（mode=demo+OKX_SIMULATED=1 → admit → planner → 市价单/查单/撤单）。 下一步: Gate2 运维 soak + GATE3_CHECKLIST.md 模拟盘联调；见 NEXT.md。

Phase 0 ──► Phase 1 ──► Phase 2 ──► Phase 3 ──► Phase 4 ──► Phase 5
可行性 Spike  只读市场     Shadow Mode   Demo Trading  100 USDT 实盘  数据工具扩展
(go/no-go)   + Dashboard  (不下单)      (模拟盘)      (真金白银)     (按需增强)

Phase 0 — 技术可行性 Spike(go/no-go 闸门)

目标: 证明 Zig 0.16.0 技术栈能支撑生产级长时运行,任何一项不过关即触发选型回退预案。

范围

• Zig 0.16 std.Io 下的 TLS 客户端、WebSocket 客户端、HTTP 客户端验证(对 OKX 与 LLM 端点)
• SQLite amalgamation 集成(vendor sqlite3.c/h,WAL,单 writer)
• systemd 服务化 + ReleaseSafe 静态构建 + 原子发布/回滚脚本雏形
• 内存长稳测试(24h 连续运行,监控 RSS / fd / 句柄泄漏)
• Azure Region 延迟实测脚本(OKX REST / 公共 WS / 私有 WS / LLM 端点 p50/p95)

交付物

• 可运行的最小 daemon(连接 OKX 公共 WS,落 SQLite 事件)
• 《依赖决议记录》: TLS/WS/HTTP 每个组件的选型(标准库 or vendor)与验证证据
• CI 骨架: 固定 Zig 0.16.0 下载 + SHA256 校验 + build + test
• Azure Region 选型报告

退出条件(Gate 0)

• 所有关键库可固定版本并连续运行 24h 无泄漏、无崩溃(短时验证通过;24h 长稳待跑)
• TLS/WS 对 OKX 实际端点稳定收发,断线可检测(REST over TLS 实网验证;WS 帧编解码单测)
• SQLite WAL 读写并行验证通过(vendor 3.53.4,WAL 模式,存储层测试 + daemon 实测落库)

Phase 1 — 只读市场与 Dashboard

目标: 无交易能力的完整「观察者」——行情、账户、状态引擎、事件日志、可视化。

范围

• Exchange Gateway: OKX 公共/私有 WS 订阅、REST 快照、心跳、重连、时间同步、instrument 配置加载
• State Engine: 单写者 mailbox、PortfolioState(版本化不可变快照)、HWM/DD 计算
• core/decimal: 定点金额运算(禁止二进制 float 结算)
• Storage: migrations、events/equity_samples 表、事件信封(顶层 type/correlation_id/state_version/config_hash)
• Journal Writer: 有界队列、关键事件强制提交
• 启动状态机: BOOTING → CONNECTING → RECONCILING → READY
• Dashboard v1: Overview + Market(K 线) + Events + System 视图,/api/v1/state|candles|equity|events,/health/*
• 备份: 每小时 SQLite Backup API 快照 + 保留策略

交付物: 在 Azure VM 上 systemd 常驻的只读实例 + 浏览器 Dashboard(SSH tunnel 访问)

退出条件(Gate 1)

• 无交易也能对账与展示(基础): REST 只读余额周期探针 + HWM 持久化 + Dashboard state（shadow 引擎现金仍为模拟）
• WS 断线自动重连并触发 reconcile（TLS upgrade 已通；login/长连/重连待稳定；REST 周期对账兜底）
• 净值/回撤样本在 Dashboard 呈现（/api/v1/equity + 表）；K 线 1H sparkline（/api/v1/candles）已交付

Phase 2 — Agent Shadow Mode

目标: 完整决策闭环但不执行订单——验证 Context、工具、提案 Schema 与记忆的质量。

范围

• Agent Runtime: Context 构建(5 层记忆检索)、模型适配器、Decision Proposal Schema 校验
  • ✅ agent/context.zig 确定性 Context + input_digest;✅ Proposal 严格校验
  • ✅ agent/openai.zig OpenAI/Azure 兼容 chat completions;本机 Azure 实调 proposal ok
• Tool Registry: market.* / derivatives.* 工具、统一 ToolResult 信封、时效/成本/可信度记录
  • ✅ tools/registry.zig + ✅ tools/market.zig ticker/candles provider（OKX REST 实调）
• Memory & Reflection: episodes、假设(Strategy Memory)、结构化 Reflection 与 memory_ops
  • ✅ memory/store.zig + agent/reflection.zig(ops 确定性生效,坏 JSON 整体作废)
  • ✅ boot 从 SQLite 重建 + bootstrap seed；决策环 retrieve 注入 Context；提案 episode 落库
  • ✅ 决策后 LLM reflection（prompts/reflection.md → 严格 Schema → memory_ops；ALPHABOUND_LLM_REFLECTION=0 可关）
  • ✅ 失败回退确定性 shadow reflection（R_* + strategy touch）
  • ✅ 事件 AGENT_REFLECTION_OK / _LLM_FAILED / _INVALID
• agent_runs / tool_calls / memories 表与审计链路 — ✅ shadow 写 run + tool_calls + memories + AGENT_* payload
• Prompt 版本化(hash 进事件日志,SIGHUP 热加载) — ✅ prompt_hash 入 agent_runs;热加载待做
• Dashboard: Trade Detail(提案链路回放)+ Memory/System 视图 — ✅ 提案/Memories/Events/System + agent-runs/memories/events/system API
• 审计事件进 Context — ✅ listCompactForContext → agent recent_events
• SQLite 小时备份 — ✅ Backup API → <db_path>.bak + BACKUP_* 事件
• 提示注入防线: 工具返回一律进 data 字段;Agent worker 无 shell/文件/任意 URL 能力
  • ✅ ToolResult.data 不可信边界在类型层强制;LLM 凭证不进 Context
• 影子对比: 提案 vs 基准(如 buy-and-hold)的假设性表现记录 — ✅ shadow_bench + /api/v1/shadow
• Market K 线只读面 — ✅ /api/v1/candles + Dashboard Lightweight Charts（K 线/量/净值 + TradingView 归因）
• 统计: ✅ --agent-stats 有效提案率 / tool_calls 计数
• 短 soak 脚本: ✅ scripts/soak-shadow.sh
• 本机管理控制: ✅ --control pause|resume|reconcile|cancel-all|flatten|shutdown|status（控制文件，无网络面；cancel 交易所路径待 Demo）
• 提案准入审计: ✅ shadow 路径 admission.admit → RISK_ADMISSION（仍不执行订单）
• 工具 UNAVAILABLE: ✅ HTTP 失败不伪造零行情
• systemd unit + deploy 说明: ✅ deploy/

退出条件(Gate 2)

• 提案可审计(基础): run_id + input/output digest + tool_calls + events.payload
• invalid/ok 率可统计（--agent-stats）;阈值与长跑样本待 Gate 2 评审
• LLM 超时/坏 JSON 均安全降级为 HOLD,不影响关键路径(本机失败路径已验证)

Phase 3 — Demo Trading(模拟盘)

目标: 打通 Risk Kernel + Execution 全链路,在 OKX Demo 环境经受故障注入。

范围

• Risk Kernel: 保守净值/压力净值/ExitReserve/风险预算、提案准入(APPROVE/REDUCE/REJECT)、 风险状态机 NORMAL/EXIT_ONLY/FLATTENING/HALTED
  • ✅ admission 单测 + shadow/demo 决策环调用
• Execution Engine: 目标仓位→订单、幂等 client_order_id、部分成交、撤单、UNKNOWN 处置、最终对账
  • ✅ planner + client_order_id + demo 市价 place/query/cancel；✅ 部分成交再规划（≤3 腿 + REST 对账）；limit 仍待
• orders/fills 表、订单 8 状态投影(PLANNED..UNKNOWN)
  • ✅ orders 投影写入；✅ /api/v1/orders + Dashboard 订单 Tab；✅ demo resolve 写 fills 聚合行（WS 多笔 fill 仍可增强）
• 管理控制: pause / resume / reconcile / cancel-all / flatten / safe-shutdown(本机 CLI/Unix socket)
  • ✅ 控制文件 CLI 全套；cancel-all 在 demo 拉 pending 撤单
• 故障注入全组: 断网、DNS、时钟漂移、磁盘满、SQLite busy、LLM 超时、坏 JSON、工具污染
• 测试金字塔补全: property(Risk Kernel 不变量)、replay(状态确定性)、integration(OKX Demo)
• 发布流水线完整化: manifest + SHA256 + self-check + 自动回滚
• 清单: GATE3_CHECKLIST.md

退出条件(Gate 3)

• Demo Trading 连续稳定运行 ≥ 7 天(soak)
• 至少一次断线恢复演练 + 一次版本回滚演练通过
• 故障降级矩阵(§7.2)10 项场景逐项验证
• Risk Kernel property test 全绿(边界/费用/滑点/部分成交覆盖)

Phase 4 — 100 USDT Live(实盘)

目标: OKX 独立子账户真实资金运行,人工每日检查,自动 halt 兜底。

范围

• 子账户开设 + API Key(仅 Read+Trade,无 Withdraw)+ Azure 固定出口 IP 白名单
• 密钥安全落地: root 管理 0600、systemd 加固(NoNewPrivileges/PrivateTmp/ProtectSystem)
• 上线验收清单(§9.3 全部 8 条)逐项签署
• 每日人工检查流程 + 周度 restore drill
• 回撤边界实弹: FLATTENING → HALTED 全链路在真实市场验证(可用小幅人工触发演练)

进入条件: Gate 3 全过 + 验收矩阵 P4 列全绿(任何无法解释的状态不一致都阻止实盘)

退出条件(Gate 4,判定 MVP 成立)

• 无状态不一致事件;所有风险事件可解释、可追溯
• 运营成本(基础设施 + 模型调用)可见且未失控
• HALTED/EXIT_ONLY 触发行为与设计一致

Phase 5 — 数据工具扩展(持续迭代)

目标: 按 Agent 的实际信息缺口逐个接入 onchain.* / wallet.* / macro.* / news.*,用数据说话。

范围

• 每个数据源作为独立工具适配器接入(Schema、时效、成本、可信度、缓存 TTL)
• 数据提供商评估: API 成本、标签质量、速率限制、许可
• 工具价值评估闭环: 使用率、引用进 evidence 的频率、对决策质量的增量贡献(Reflection 统计)
• 逐步校准: 风险压力参数、ExitReserve、Agent 触发策略(成本预算闸)

退出条件(滚动)

• 每个新工具上线 4 周后完成使用率与增量价值评估,低价值工具降级或下线

横切工作流(贯穿所有阶段)

验收矩阵

以下内容与仓库 docs/ACCEPTANCE_MATRIX.md 同步引入。状态列以仓库文件为准。

AlphaBound 验收矩阵

将系统设计 v0.1 的功能需求(FR)、非功能需求(NFR)、上线验收标准(§9.3)、安全边界(§7.3/7.4) 与故障降级矩阵(§7.2)映射为可执行、可勾选的验收条目。

• 验证方法 对应 §9.2 测试金字塔: Unit / Property / Replay / Integration / Fault / Soak / Shadow / Manual(人工演练或评审)
• 阶段 指该条目必须通过的最晚阶段闸门(见 ROADMAP.md);进入 Phase 4 实盘前,P0–P3 条目必须全绿
• 状态: ☐ 未开始 · ◐ 进行中 · ☑ 通过

状态快照(2026-08): 核心软件 + shadow 在线路径已验证(zig build test 全绿; Dashboard 提案/BH; 本机 OKX 公共行情、只读私有余额、Azure LLM 提案、market 工具落库)。下表 ◐ = 代码+单测/部分实网已落地, 但设计要求的完整 Integration/Fault/Soak/Manual 尚未全部执行(Demo/Live 与长稳仍缺)。

A. 功能需求(FR)

B. 非功能需求(NFR)

C. 上线验收标准(§9.3,Phase 4 实盘闸门)

D. 风险内核专项(§5)

E. 故障降级矩阵(§7.2,逐项注入验证)

F. 安全边界(§7.3 / §7.4)

G. 数据与运维(§6 / §7.5 / §8)

H. 阶段闸门汇总

维护约定: 每次闸门评审更新状态列并附证据链接(CI run / 演练记录 / 评审纪要); 新增需求先补矩阵行再写代码。