docs(HEL-353): 恢复普通 README 并移除多媒体展示

放弃宣传稿与 docs/images 素材，按当前仓库真实结构重写常规说明。

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: multica-agent <github@multica.ai>

DOCKER_DEPLOY.md

@@ -202,7 +202,7 @@ docker compose down
 `compose.yaml` 的镜像名与 revision 标签同样做了强校验：直接 `docker compose up -d --build`
 会因缺少 `XIAOBAI_GIT_REV` / `XIAOBAI_GIT_SHORT` 变量而拒绝执行，避免再出现构建进
 `latest` 的模糊版本。需要用 compose 时先 `export` 这两个变量（值以
-`~/xiaobai-git rev-parse HEAD` 为准），或直接用上面的脚本。
+`~/xiaobai-build/xiaobai-git rev-parse HEAD` 为准），或直接用上面的脚本。
 
 ### 智能体高级入口：Git 归档流式构建
 

README.md

@@ -1,76 +1,138 @@
-# 小白复盘 Web
+# 小白复盘
 
-一个面向 A 股盘后复盘的本地 Web 工作台。后端使用 Python 访问 Tushare Pro，前端不依赖构建工具。
+面向 A 股盘后复盘的本地 Web 工作台。收盘后把涨停、炸板、连板梯队、板块轮动、集合竞价、龙虎榜等数据整理成可浏览的复盘界面；不接券商、不代为下单，也不提供个股推荐。
 
-本目录是经过保真迁移、结构治理和用户人工验收的唯一正式源码，不依赖父目录旧程序或失败版本。
+本目录是唯一正式源码。模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，产品与维护文档见 [docs/README.md](docs/README.md)。
-目录职责见[ARCHITECTURE.md](ARCHITECTURE.md)，产品与维护文档见[docs/README.md](docs/README.md)。
 
-当前包含集合竞价、涨停池、炸板池、跌停板、昨日涨停、涨停表现、市场天梯、板块轮动、题材库、人气热榜、龙虎榜和个人复盘工作区。交易日快照与同步记录保存在本地 SQLite 数据库 `data/review.db`。
+## 主要功能
 
-集合竞价中心采用盘前生命周期：9:15 前显示预告，9:15–9:25 明确等待最终竞价，9:25–9:30 自动读取并重试最终竞价筛选，9:30 后停止更新并冻结为复盘归档。当前 Tushare 只提供 9:25 最终竞价快照，不将其表述为动态虚拟撮合行情。
+登录后左侧共 16 个页面，另有一个内嵌页「策略持续跟踪」。交易日快照保存在本地 SQLite 数据库 `data/review.db`。
 
-第三阶段加入了机构席位、席位别名、个股复权日 K、资金流、自选股、涨停原因修订、个股笔记、每日复盘和历史数据回补。
+- **情绪周期**：0–100 情绪温度与阶段判定（默认首页）
+- **涨停池 / 炸板池 / 跌停板 / 昨日涨停 / 涨停表现**：封板结构、炸板、跌停与昨日反馈
+- **市场天梯**：按连板高度排列的市场梯队
+- **板块轮动**：近若干交易日板块热力与成分下钻
+- **集合竞价**：盘前生命周期；9:30 后停止更新并冻结为复盘归档。当前数据源提供 9:25 最终竞价快照，不是动态虚拟撮合行情
+- **题材库 / 人气热榜 / 龙虎榜**：题材成分、双榜人气、席位与游资档案
+- **智能选股**（会员）：六阶段策略、精选策略库、自然语言编译为受控公式后的确定性筛选与滚动回测；候选需手动加入后才进入五交易日跟踪
+- **问师**（会员）：按选定的游资思维 Skill 单师对话；新增公开角色时在 `游资skills` 下增加含 `SKILL.md` 的目录，并在 `游资skills/mentor_catalog.json` 登记。管理员私有角色放在 `data/private-mentor-skills`（不进 Git / 镜像）
+- **问天**（会员，冻结区，勿改代码）：观势 / 观气 / 观心。卦象、干支、节气与气机由本地程序确定性计算，大模型只负责文字解释
+- **我的复盘**：手工交易日志、每日复盘、提醒中心与复盘助手；不接券商、不自动下单
 
-股票代码在桌面端悬停后会显示分时与日 K 快速预览，默认优先展示日 K；移动端点击代码后从底部打开预览面板。股票详情以及板块、题材、指数详情均可在日 K 与最新分时之间切换。日 K 复用个股详情缓存；分时优先使用 iFinD，东方财富仅作隔离的展示兜底，并使用短时内存缓存。图表数据不写入主行情、不参与情绪、选股或问天计算；不可用时明确显示“分时不可用”，不会用日 K 模拟分时走势。
+全局能力：日间 / 夜间主题、股票代码悬停预览日 K 与分时、`Ctrl + K` 全局搜索。图表数据不写入主行情，也不参与情绪、选股或问天计算。
 
-智能选股包含六阶段盘后候选、29 套精选策略、自定义公式 DSL、自然语言公式编译、候选排名和滚动回测。阶段与精选策略在当日行情更新后由后台确定性计算；自定义选股由用户手动执行，LLM 只负责编译自然语言条件，不参与候选筛选。竞价、估值、财务、资金、人气和席位等字段按已登记的数据可用性进入因子库，缺失时明确显示覆盖问题。
+## 技术栈
 
-候选只有经用户手动加入后才进入五交易日持续跟踪，展示 T+1 开盘/收盘、T+3、T+5、最大涨幅与最大回撤。提醒中心支持手工日期提醒，并在策略首日反馈和五日跟踪完成时生成账号私有的站内提醒。
+| 层面 | 说明 |
+| --- | --- |
+| 运行时 | Python 3.12；标准库 `ThreadingHTTPServer`，无独立 Web 框架 |
+| 依赖 | `requirements.txt` 仅含 `cryptography`；问天历法使用仓库内 `vendor/lunar_python` |
+| 数据库 | SQLite（WAL），默认文件 `data/review.db` |
+| 前端 | 原生 HTML / CSS / JavaScript，无打包、无构建步骤 |
+| 部署 | Docker / Docker Compose，或本机直接运行 `server.py` |
+| 安全 | 账号密码 scrypt 哈希；行情 Token 与模型密钥用 `APP_ENCRYPTION_KEY` 加密后存库 |
 
-问师模块会读取当前复盘、近十日市场情绪、涨跌停、昨日反馈、板块轮动、市场阶段、龙虎榜和指定个股数据，再按选中的游资思维 Skill 进行单师对话。对话记录按账号、老师和交易日期保存在服务端；主模型不可用时自动切换辅助模型。
+## 环境要求
 
-新增公开问师角色时，在 `游资skills` 下增加一个包含 `SKILL.md` 的独立目录，并在 `游资skills/mentor_catalog.json` 中登记素材等级与结构质检。管理员私有角色放在 `data/private-mentor-skills`，该目录不进入 Git 或 Docker 镜像，且只会出现在管理员的问师列表中。系统会从 Skill 的 frontmatter、一级标题、核心模型和引用语中自动生成角色信息，无需修改注册代码。
+- Python 3.12（与 `Dockerfile` 一致）
+- 本机启动：能执行 `python` / `pip`
+- Docker 部署：Docker Engine 24+，Compose v2（`docker compose`）
+- 行情：部署者自行申请并配置 Tushare Pro Token；部分分时优先使用同花顺 iFinD（可选）
+- 问师、问天解释、复盘助手、自然语言编译公式：需配置 OpenAI 兼容接口；未配置时市场数据页仍可用
 
-问天模块包含三个相互独立的部分：观势以市场数据生成三才六爻，用于观察“势”，行情缺失或自动取象明显偏差时可显式手动校准六爻，人工结果与自动来源严格区分；观气依据干支、精确节气、五运六气及客主加临关系观察“运”，行业五行仅作传统取象归类；观心先准备1秒，再完成5轮“吸3秒、顿2秒、呼4秒”，随后以六次三枚铜钱起卦、察念和解卦完成一次不输入问题的问心仪式。卦象、干支、节气与气机关系均由本地确定性程序计算，LLM只负责解释，不参与起卦或改动结果。
+## 安装与启动
 
-问天模块使用项目本地的 `lunar-python` 计算历法，并使用 `data/iching_zh.json` 中的固定六十四卦、卦辞和爻辞。第三方授权见 `THIRD_PARTY_NOTICES.md`。
+仓库根目录即为运行目录（`server.py`、`requirements.txt` 都在根目录）。
 
-“我的复盘”包含结构化手工交易日志，可记录方向、价格、数量、仓位、盈亏、逻辑、执行、情绪和标签，不接券商也不自动下单。顶部“复盘助手”以流式方式读取市场统计、策略跟踪、提醒、个人复盘和交易日志；对话按账号保存，只提供分析和条件化计划。
+```bash
-
-## 启动
-
-```powershell
-cd app
 python -m pip install -r requirements.txt
 python server.py
 ```
 
-浏览器打开 `http://127.0.0.1:8765`，首次使用先注册账号。首个账号自动成为管理员，后续账号默认为普通用户。主行情不再回退演示数据：盘前、非交易日或临时取数失败时沿用最近真实收盘快照；没有任何真实快照时提示等待管理员完成首次同步。
+默认监听 `127.0.0.1:8765`（仅本机可访问）。浏览器打开该地址，首次使用先注册账号；第一个账号自动成为管理员，之后注册的默认为普通用户。
 
-需要后台启动本地验收端口时，使用`tools/start_local.ps1`。该工具把日志、进程号和Python缓存
+主行情不再回退演示数据：盘前、非交易日或临时取数失败时沿用最近真实收盘快照；没有任何真实快照时，页面会提示等待管理员完成首次同步。
-统一写入`runtime/`，不在源码根目录产生运行文件：
+
+可选参数：
+
+```bash
+python server.py --host 127.0.0.1 --port 8765
+```
+
+Windows 下若需要后台启动，并把日志、进程号和 Python 缓存写入 `runtime/`（不在源码根目录产生运行文件）：
 
 ```powershell
-powershell -ExecutionPolicy Bypass -File tools/start_local.ps1 -Port 8797
+powershell -ExecutionPolicy Bypass -File tools/start_local.ps1
 ```
 
-局域网 Docker 部署使用 `Dockerfile` 与 `compose.yaml`，完整的迁移、持久化、
+该脚本默认端口为 `8797`。统一验收：
-防火墙、备份和恢复步骤见 [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md)。
 
-账号密码使用 scrypt 哈希；公共 Tushare Token、平台模型密钥以及原始生辰资料均使用 `APP_ENCRYPTION_KEY` 加密后保存在 SQLite。公共数据和平台模型归系统所有，生辰资料仍按账号隔离。普通用户不配置 LLM，只有管理员授权的有效会员可以使用平台模型。请将 `.env` 与数据库一起备份，丢失加密密钥后无法恢复这些资料。
+```bash
+python tools/verify_baseline.py
+```
 
-## 系统与账号配置
+涉及运行时或前端时再加 `--e2e`（Playwright）。
 
-管理员通过页面右上角“系统管理”保存公共 Tushare Token、平台主/辅助模型、会员每日额度和后台刷新开关。所有用户读取同一份 SQLite 行情快照，不再分别配置行情 Token。已有个人凭据中的 Tushare Token 会在升级时迁移到系统配置并从个人凭据移除。
+## Docker 使用
+
+局域网或服务器部署使用仓库根目录的 `Dockerfile` 与 `compose.yaml`。容器监听 `8765`，默认以非 root 用户运行，并把宿主机 `./data` 挂到容器内 `/app/data`。
+
+1. 复制 `.env.example` 为 `.env`，填入 `APP_ENCRYPTION_KEY` 以及行情 / 模型等初始化配置。密钥不会返回到浏览器。
+2. `compose.yaml` 构建时要求带上当前 Git 提交号，避免打出无版本标签的镜像：
+
+```bash
+export XIAOBAI_GIT_REV="$(git rev-parse HEAD)"
+export XIAOBAI_GIT_SHORT="$(git rev-parse --short=7 HEAD)"
+docker compose build
+docker compose up -d
+```
+
+3. 检查健康接口：
+
+```bash
+docker compose ps
+curl http://127.0.0.1:8765/api/health
+```
+
+健康响应类似 `{"ok": true, "storage": "sqlite", "account_required": true}`。
+
+完整的迁移、持久化、防火墙、备份、恢复与正式线构建入口见 [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md)。`.env` 必须与数据库成对备份；丢失 `APP_ENCRYPTION_KEY` 后无法恢复加密资料。
+
+## 目录与配置
 
 ```text
-TUSHARE_TOKEN=你的Token
+server.py            进程入口
+backend/            服务、路由、数据、任务、LLM
+frontend/            无构建前端（shared + pages）
+config/              页面 / API / 任务等注册表
+data/                SQLite 与私有数据（数据库文件不进 Git）
+runtime/             本地日志、PID、缓存（不进 Git）
+tools/               启动、验收与构建辅助脚本
+游资skills/          公开问师角色
+vendor/              本地第三方库（含 lunar-python）
+Dockerfile
+compose.yaml
+.env.example         环境变量模板（复制为 .env 后填写）
 ```
 
-`.env` 中的 Tushare 和平台 LLM 配置只用于初始化系统配置，密钥不会返回到浏览器。后台刷新只在交易时段更新 SQLite 快照，不会主动刷新或重绘用户页面；用户点击页面“刷新”时读取最新快照。管理员也可点“后台刷新”立即启动一次后台同步，当前页面仍保持不变。
+管理员通过页面右上角「系统管理」保存公共 Tushare Token、平台主/辅助模型、会员每日额度和后台刷新开关。所有用户读取同一份 SQLite 行情快照。`.env` 中的 Tushare 和平台 LLM 配置只用于初始化系统配置。
 
-普通用户在“账号设置”中维护个人资料、查看会员状态和修改密码，不配置个人 LLM。有效会员自动使用平台模型；管理员可在“系统管理”中手动开通、续期、停用会员。平台模型受管理员设置的每日调用次数限制，管理员账号始终可用。
+普通用户在「账号设置」中维护个人资料、查看会员状态和修改密码，不配置个人 LLM。有效会员使用平台模型；管理员可开通、续期、停用会员。平台模型受每日调用次数限制，管理员账号始终可用。
 
-Tushare 各接口有独立积分权限。程序优先使用 `limit_list_d` 获取涨跌停明细；该接口不可用时，会尝试通过日线和每日涨跌停价格推算。
+相关文档：
 
-## 隔离实时聚合验证
+- [ARCHITECTURE.md](ARCHITECTURE.md) — 模块边界
+- [docs/README.md](docs/README.md) — 交接手册入口
+- [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md) — Docker 部署、备份与恢复
+- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) — 第三方授权（含问天历法库）
+- [AGENTS.md](AGENTS.md) — 维护约束
 
-`backend/data/realtime.py`用于验证东方财富、同花顺和选股宝网页数据源。它不写入 SQLite 主行情快照，也不参与情绪评分或智能选股；当 Tushare 实时指数权限不可用时，观势会使用东方财富三大指数和板块外显，并继续使用 Tushare 的板块成分内核与个股数据。
+## 注意事项与免责声明
 
-登录后可调用：
+- 本项目是个人研究与复盘工具，全部数据、指标、候选与文字分析均不构成投资建议、证券推荐或买卖要约。
-
+- 不接券商、不代为下单。交易日志只做手工记录与统计，不代表实际成交。
-```text
+- 情绪温度、阶段判定、连板梯队、策略筛选等均为基于公开数据的统计与规则计算，不预测走势，不保证收益。
-GET /api/realtime-aggregate/health?sector=元器件
+- 「问天」属于传统文化视角的观察工具，不具备预测功能，不得作为投资依据；该模块为冻结区，不要改其代码。
-```
+- 行情来自第三方接口，可能延迟、缺失或口径调整；不可用时页面会明确提示，请以交易所与券商正式披露为准。
-
+- 不要把服务端口直接暴露到公网。不要把 Token、密码、密钥、数据库或 `.env` 提交进 Git。
-返回内容包括东方财富三大指数及板块快照、指数时间差、同花顺和选股宝可用性、每个来源的耗时与错误。盘中指数时间差不超过15秒，收盘后不超过120秒。`ready=true` 仅表示本次验证满足聚合层约束，不代表这些网页内部接口具有长期稳定性或商业使用授权。
+- 股市有风险，入市需谨慎。投资决策及其后果由使用者本人承担。

tools/update_from_main.sh

@@ -33,16 +33,37 @@ $DIRTY"
 LOCAL_HEAD="$(g rev-parse HEAD)"
 REMOTE_HEAD="$(g rev-parse origin/main)"
 if [ "$LOCAL_HEAD" != "$REMOTE_HEAD" ]; then
-  TOP_AD="$(g diff --name-status HEAD origin/main | grep -E "^[AD][[:space:]]+[^/]+$" || true)"
+  g merge-base --is-ancestor "$LOCAL_HEAD" "$REMOTE_HEAD" \
+    || refuse "本地 main 与 origin/main 历史分叉，停止（未改写工作目录）"
+  CHANGES="$(g diff --no-renames --name-status HEAD origin/main)"
+  TOP_AD="$(printf '%s\n' "$CHANGES" | grep -E "^[AD][[:space:]]+[^/]+$" || true)"
   [ -z "$TOP_AD" ] || refuse "main 相比本地新增/删除了顶层文件，目录顶层归 root，需管理员执行：
 $TOP_AD"
-  TOP_MOD="$(g diff --name-status HEAD origin/main | grep -E "^M[[:space:]]+[^/]+$" | awk '{print $2}' || true)"
+  echo "==> 同步 origin/main 文件（顶层文件保留原 inode，避免目录权限限制）"
-  if [ -n "$TOP_MOD" ]; then
+  while IFS=$'\t' read -r status path; do
-    echo "==> 预写入顶层改动文件（顶层目录无删除权限，改为截断写入）"
+    [ -n "$path" ] || continue
-    while IFS= read -r f; do g show "origin/main:$f" > "$WORK_TREE/$f"; done <<< "$TOP_MOD"
+    case "$status" in
-  fi
+      D)
-  echo "==> 快进合并到 origin/main"
+        case "$path" in
-  g merge --ff-only origin/main >/dev/null 2>&1 || refuse "无法快进合并 origin/main（历史分叉），停止"
+          */*) rm -f -- "$WORK_TREE/$path" ;;
+          *) refuse "main 删除了顶层文件 $path，需管理员处理" ;;
+        esac
+        ;;
+      A|M)
+        MODE_BITS="$(g ls-tree origin/main -- "$path" | awk '{print $1}')"
+        case "$MODE_BITS" in
+          100644|100755) ;;
+          *) refuse "文件 ${path} 的 Git 类型 ${MODE_BITS} 不支持自动同步，需管理员处理" ;;
+        esac
+        mkdir -p -- "$(dirname "$WORK_TREE/$path")"
+        g show "origin/main:$path" > "$WORK_TREE/$path"
+        [ "$MODE_BITS" = "100755" ] && chmod 755 "$WORK_TREE/$path" || chmod 644 "$WORK_TREE/$path"
+        ;;
+      *) refuse "遇到未支持的 Git 变更类型 ${status}：${path}" ;;
+    esac
+  done <<< "$CHANGES"
+  g read-tree origin/main
+  g update-ref refs/heads/main "$REMOTE_HEAD" "$LOCAL_HEAD"
   DIRTY="$(g status --porcelain)"
   [ -z "$DIRTY" ] || refuse "快进后工作区仍不一致，停止：
 $DIRTY"
@@ -54,6 +75,8 @@ echo "==> 校验通过：本地 HEAD = origin/main = ${LOCAL_HEAD}（${SHORT}）
 
 if [ "$MODE" = "verify-tag" ]; then
   TAG="${2:?用法: update-from-main.sh verify-tag <tag>}"
+  [ "$TAG" = "main-${SHORT}" ] \
+    || refuse "镜像标签必须是当前 main 对应的 main-${SHORT}，收到：${TAG}"
   LABEL="$(docker image inspect "${IMAGE_REPO}:${TAG}" \
     --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' 2>/dev/null)" \
     || refuse "镜像 ${IMAGE_REPO}:${TAG} 不存在"