From 6abee41bd2431cd302e67ba955ccaacf8d842e6e Mon Sep 17 00:00:00 2001
From: lhl <liuhaili1203@126.com>
Date: Sat, 12 Sep 2026 18:37:26 +0800
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E6=9B=B4=E6=96=B0=E6=8A=80?=
 =?UTF-8?q?=E6=9C=AF=E6=A0=88=E4=B8=BA=20TypeScript+esbuild=E3=80=81?=
 =?UTF-8?q?=E8=A1=A5=E5=85=85=20frontend/=20=E7=BB=93=E6=9E=84=E4=B8=8E?=
 =?UTF-8?q?=E5=89=8D=E7=AB=AF=E6=9E=84=E5=BB=BA=E6=AD=A5=E9=AA=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3b7e678..b2a406f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,8 +10,9 @@
 
 ## 技术栈
 
-- 后端: Python
-- 前端: Web UI
+- 后端: Python（FastAPI）
+- 前端: TypeScript + esbuild（原生 DOM，无框架；打包为单文件 ESM）
+- 前端构建: Node + esbuild / tsc（产物入库：`src/genesis/server/static/chat.js`）
 - LLM: DeepSeek / Qwen等
 - 文档处理: python-docx, docxtpl, openpyxl
 - Agent 架构: 多 Agent 协作（Parser / Impact / Writer / QA）
@@ -22,12 +23,30 @@
 Genesis/
 ├── AGENTS.md              # 本文件 - OpenCode 指令文件
 ├── _AI_USAGE_LOG.md       # AI 使用日志（自动生成）
-├── docs/                  # 大赛规则、设计文档等
-├── src/                   # 源代码
-├── sample/               # 样本输入文件（脱敏）
+├── docs/                  # 设计文档（规范 specs/ 与计划 plans/ 位于 docs/superpowers/ 下）
+├── frontend/              # 前端源码（TypeScript）：src/ + tests/ + esbuild/tsconfig
+├── src/                   # 后端源码；src/genesis/server/static/ 含前端打包产物
+├── scripts/               # 运行脚本（如 scripts/serve.py）
+├── tests/                 # 后端测试（pytest）；前端单测在 frontend/tests/
+├── sample/                # 样本输入文件（脱敏）
 └── README.md              # 安装与运行说明
 ```
 
+## 前端构建（修改前端时）
+
+前端源码在 `frontend/`（TypeScript），打包产物入库于 `src/genesis/server/static/chat.js`。
+修改前端后须重新构建（仅运行 Web 服务无需 Node，产物已入库）：
+
+```powershell
+cd frontend
+npm install      # 首次
+npm run build    # 打包到 ../src/genesis/server/static/chat.js
+npm run typecheck
+npm test         # 纯逻辑单测（node --test）
+```
+
+> 前端改动优先改 `frontend/src/*.ts`，再 `npm run build`；`?v=__ASSET_VER__` 依据文件 mtime 自动破缓存。
+
 ## 开发范式
 
 本项目的开发遵循以下步骤，每一步骤名称对应 `_AI_USAGE_LOG.md` 中的"范式步骤"列：
@@ -55,7 +74,7 @@ Genesis/
 
 ## 文档生成规则
 
-所有会话中生成的设计文档、方案、报告等内容，**必须保存到 `docs/` 目录下**，不得在项目根目录或其他位置创建文档文件。
+所有会话中生成的设计文档、方案、报告等内容，**必须保存到 `docs/` 目录下**（设计规范放 `docs/superpowers/specs/`，实施计划放 `docs/superpowers/plans/`），不得在项目根目录或其他位置创建文档文件。
 
 ## 信息安全