From 760d960762d6b06c1338f8f98e4b4d4c52e394bc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=BF=E4=BA=91=E7=A7=8B=E6=9C=88?= <15273589815@163.com>
Date: Sun, 13 Sep 2026 21:56:59 +0800
Subject: [PATCH] =?UTF-8?q?docs(AGENTS):=20=E8=A1=A5=E4=B8=80=E9=94=AE?=
 =?UTF-8?q?=E5=90=AF=E5=8A=A8/=E6=BC=94=E7=A4=BA=E5=85=A5=E5=8F=A3?=
 =?UTF-8?q?=EF=BC=8C=E5=B9=B6=E8=AE=B0=E4=B8=8B=20BOM=20=E4=B8=8E=E8=A1=8C?=
 =?UTF-8?q?=E6=83=85=2015=20=E5=88=86=E9=92=9F=E4=B8=A4=E4=B8=AA=E6=98=93?=
 =?UTF-8?q?=E9=94=99=E7=82=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 69e9c59..a223c53 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,6 +31,20 @@
 > 启动：`python -m uvicorn app.main:app --port 8000`（注意模块级变量是 **`app`**，不是 `application`）。
 > `tools/portal.py`（8101）**只是跨角色联调工具，不是产品前端**，不要再往它加功能。
 >
+> **🚀 一键启动与演示（2026-09-13 起）**：根目录 **`start.ps1`**
+> （`powershell -ExecutionPolicy Bypass -File start.ps1`）按序做四件事：
+> 找解释器 → 检查 MySQL/Redis/Milvus → **刷新行情** → 起 **API 与 Agent Worker 两个窗口**。
+> 演示数据一键准备：`python tools/seed_demo_data.py`（10 步，顺序有依赖，见脚本内表格）；
+> **演示流程（8 个场景照读版 + 排障表 + 账号速查）见 `docs/44-演示流程.md`**；
+> 交付自检：`python tools/e2e_smoke_test.py`（6 条线 40 项，`--read-only` 不动数据）。
+> ⚠️ **`start.ps1` 必须保存为 UTF-8 with BOM**：Windows PowerShell 5.1 在缺 BOM 时按系统
+> ANSI（简中为 GBK）解析，中文注释直接抛 `Unexpected token '[璀﹀憡]'` 这类语法错误。
+> 用 `edit`/`write` 类工具改完**务必补回 BOM**（只加字节、别重写换行：
+> `d=open(p,'rb').read(); open(p,'wb').write(b'\xef\xbb\xbf'+d)`）。
+> ⚠️ **行情有效期只有 15 分钟**（`app/service/trade_service.py` 的 `MAX_QUOTE_AGE`），
+> 超时后**所有委托一律 503「行情已过期」**且无自动刷新 —— 这是演示最容易翻的一环。
+> 补刷用 `python tools/sync_market_prices.py`，**立即生效、无需重启服务**。
+>
 > **⚠️ 文档现状（2026-09-11 第二次修订）**：本文件原先声明"已删除 5 份编号文档"，
 > 那条**已作废** —— 经评审，`docs/04`/`06`/`10`/`13`/`99` **全部保留**（架构师明确要求保留：
 > 删除收益为零，而保留成本同样为零）。它们的内容**未被核对过、可能过期**，