Python模块化仪表盘的AI工程化实践：Prompt Engineering实战

1. 项目概述：这不是写提示词，是给AI装上Python工程化“手”和“眼”

你有没有试过让大模型画一个带实时数据刷新、可拖拽组件、支持主题切换的Dashboard？我试过——第一次输入“请用Streamlit做一个销售看板”，它返回了一段能跑但全是硬编码、颜色乱配、连日期范围选择器都漏掉的代码。第二次加了“响应式、模块化、可复用”，它开始堆砌抽象类和空接口，却忘了最基础的st.metric()怎么调用。第三次我干脆扔进去一份自己写的dashboard_core.py文件，让它“基于此扩展”，结果它把所有类型注解全删了，还把@st.cache_data错写成@st.cache……这根本不是AI在写代码，是AI在猜谜。

“Prompt Engineering AI for Modular Python Dashboard Creation”这个标题，表面看是讲怎么写提示词，实则是一场人机协作范式的重构：我们不再把AI当作文本补全工具，而是把它训练成一个懂Python工程规范、理解Streamlit/Plotly/Dash底层约束、能主动识别模块边界、甚至会做技术选型权衡的“虚拟前端工程师”。核心关键词——Prompt Engineering、Modular、Python Dashboard——三者缺一不可：没有精准的Prompt Engineering，AI产出就是垃圾；没有Modular设计，Dashboard无法维护和复用；脱离Python生态（而非JavaScript或低代码平台），就失去了对数据管道、模型服务、本地部署的绝对控制力。适合谁？不是纯小白，而是有Python基础、写过至少2个Flask/Streamlit小项目的开发者，正被老板催着“三天内上线客户行为分析看板”，又不想从零造轮子。它解决的不是“能不能做”，而是“能不能在不崩溃的前提下，让AI真正成为你的第二双眼睛和第三只手”。

我踩过的最大坑，是以为“越详细越好”。曾写过300字提示词，列了12条约束，结果AI直接忽略第7条“禁止使用全局变量”，因为上下文窗口塞不下。后来才明白：真正的Prompt Engineering，是像调试电路一样调试人机通信协议——你要教AI“读空气”，而不是喂它百科全书。比如，当我说“按MVC分层”，它可能理解成Django的MVC，而我要的是Streamlit里data/、ui/、logic/的物理目录隔离。这种认知偏差，必须靠结构化指令+即时反馈闭环来校准。下面我会拆解整套方法论，不讲虚的，只说我在给3家SaaS公司落地Dashboard时，验证有效的实操路径。

2. 整体设计思路：为什么必须放弃“单次提示→完整代码”的幻想

2.1 传统思维的致命缺陷：把AI当“高级Ctrl+C/V”

多数人尝试AI生成Dashboard时，隐含一个危险假设：只要提示词够长、约束够多，AI就能一次性输出可运行的完整应用。这源于对大模型本质的误判——它不是编译器，而是基于概率的文本续写引擎。当你输入“创建一个股票行情看板”，模型在内部做的不是解析需求，而是计算：“接下来最可能出现的token序列是什么？” 它可能高频见过st.line_chart(df)，但未必理解df必须是Pandas DataFrame且索引为datetime；它可能熟记st.sidebar.selectbox()的语法，却不知道在st.experimental_rerun()触发时，selectbox状态会重置。这种“语法正确但语义错误”的输出，在Dashboard这种强交互场景下，会导致灾难性后果：用户点按钮没反应、图表数据错位、缓存失效引发API重复调用。

我给某跨境电商做的库存预警看板，AI第一次生成的代码里，st.button("刷新")被放在st.cache_data装饰的函数内部——这直接导致每次点击都触发整个数据加载流程，服务器CPU飙到95%。问题不在提示词没写“避免在缓存函数内放按钮”，而在于模型根本不具备“执行上下文感知”能力。它看到st.button就续写st.button("刷新"):，至于这个冒号后面该接什么，完全依赖训练数据中相邻token的统计规律。所以，指望单次提示解决所有问题，等于要求一个只背过菜谱的人，不用尝味道就做出满汉全席。

2.2 模块化驱动的三层架构：把AI变成“乐高装配工”

我的解决方案，是彻底抛弃“端到端生成”思路，转而构建三层渐进式协作架构：

• 第一层：模块契约定义（Contract Layer）
  不让AI写代码，先让它写“合同”。用极简提示词，强制AI输出每个模块的接口定义（Interface Contract）。例如：“用YAML格式描述‘销售趋势图表’模块的输入参数、输出组件、依赖数据源、样式约束。字段必须包含：name, input_schema (JSON Schema), output_components (list of Streamlit component names), data_source (e.g., 'sales_api_v2'), theme_compatibility (light/dark/both)”。这步的关键是，YAML比自然语言更难“胡说”，且机器可解析。AI若乱写input_schema，后续代码生成必然失败，倒逼它认真对待契约。

• 第二层：模块代码生成（Module Layer）
  拿到YAML契约后，再发指令：“根据以下契约，生成Python模块文件sales_trend_chart.py。要求：1. 使用@st.cache_data(ttl=300)装饰数据获取函数；2. 图表必须用Plotly Express实现，禁用Matplotlib；3. 所有字符串用f-string，禁止硬编码；4. 在文件顶部添加模块级docstring，说明用途和参数”。此时提示词短而锋利，聚焦单一模块，成功率从35%提升到89%。

• 第三层：集成胶水层（Glue Layer）
  最后一步，才是让AI写主程序。指令是：“用Streamlit创建主应用app.py，集成以下模块：sales_trend_chart.py,inventory_alert.py,user_activity_heatmap.py。要求：1. 使用st.tabs()组织页面；2. 在侧边栏添加st.radio('主题', ['浅色', '深色'])并动态切换CSS变量；3. 所有模块通过import导入，禁止复制粘贴代码；4. 添加异常处理，当任一模块报错时显示st.error('模块加载失败')”。胶水层逻辑简单，AI出错率最低，且能暴露前两层的契约漏洞（比如某个模块没按约定导出render()函数）。

这套架构的价值，不是省时间，而是把不可控的AI输出，转化为可控的工程交付物。每个模块都是独立测试单元，契约即文档，胶水层即集成测试入口。当老板说“把销售图表换成环形图”，你只需改YAML契约里的output_components，再让AI重生成模块，主程序完全不动。

2.3 为什么选Python而非低代码平台：控制权即生产力

有人会问：既然这么麻烦，为什么不直接用Power BI或Tableau？答案藏在三个真实场景里：

• 场景1：某金融客户要求Dashboard必须连接其私有Kubernetes集群里的Spark SQL服务。Power BI的JDBC驱动不兼容其自定义认证协议，而Python里一行pyspark.sql.SparkSession.builder.config("spark.sql.adaptive.enabled", "true")就能搞定。
• 场景2：某IoT公司需要在Dashboard里嵌入实时WebSocket数据流，并用st.experimental_data_editor做双向编辑。低代码平台要么不支持WebSocket，要么编辑后数据无法回传设备，而Python里asyncio+websockets+st.session_state三行代码就能闭环。
• 场景3：某医疗AI团队要展示模型推理结果，需在图表上叠加医生标注的ROI区域。Tableau做不到像素级坐标映射，但Python里plotly.graph_objects.Image+cv2图像处理，能精确到每个像素。

模块化Python Dashboard的核心优势，从来不是“快”，而是在复杂约束下保持技术主权。当业务方提出“下周要接入新数据源”，低代码平台可能要等厂商排期更新驱动，而你打开data/目录，新建new_source_loader.py，10分钟就能完成。Prompt Engineering在这里的作用，是把这种开发效率，从“资深工程师专属”变成“初级工程师可复现”的标准化流程。

3. 核心细节解析：Prompt Engineering的6个反直觉技巧

3.1 技巧1：用“错误示例”代替“正确要求”，激活AI的纠错本能

人类写提示词，习惯说“应该怎样”。但大模型对否定指令（如“不要...”、“禁止...”）的响应极差——它的训练目标是最大化下一个token概率，而“禁止”这个词本身在代码语境中出现频率极低。更有效的方法，是提供典型错误示例+修正说明。例如，生成数据加载模块时，我不写“禁止使用全局变量”，而是这样提示：

以下是一个错误的模块实现，请分析问题并给出修正版：

# 错误示例 import pandas as pd df_global = None # 全局变量，危险！ def load_sales_data(): global df_global if df_global is None: df_global = pd.read_csv("sales.csv") return df_global

问题：1. 全局变量导致多用户并发时数据污染；2. 未使用缓存，重复IO；3. 硬编码文件路径。
请按以下要求重写：1. 使用@st.cache_data装饰函数；2. 参数化文件路径；3. 返回DataFrame，不存储状态。

实测效果：AI对“错误示例”的响应准确率比纯文字要求高47%。原因在于，模型在训练中见过海量“代码-错误-修复”三元组（如GitHub Issues），它对这种模式有天然敏感性。你提供的错误示例，相当于给它一个锚点，让它从自己的知识库中检索最匹配的修复模式，而非凭空构造。

3.2 技巧2：强制结构化输出，用分隔符制造“思维沙盒”

AI的自由发挥是质量杀手。我要求所有模块契约必须用YAML，所有代码必须用Python代码块，所有配置必须用JSON。但光靠语言描述不够，必须用不可绕过的分隔符。例如，定义模块契约的提示词结尾永远是：

请严格按以下格式输出，不得添加任何额外文字： ---YAML_START--- [your YAML here] ---YAML_END---

为什么有效？因为分隔符在模型tokenization中是明确的控制字符。当它生成到---YAML_END---时，会触发内部的“结束标记”机制，极大降低它续写解释性文字的概率。我在测试中对比过：无分隔符时，30%的输出会在YAML后追加“以上是模块契约，如有疑问请告知”；加了分隔符后，这个比例降为0.3%。同理，代码生成必须用```python包裹，且末尾加# EOF。这些看似琐碎的约定，实则是给AI划出不可逾越的“思维沙盒”，把它的创造力，严格限定在你设计的工程框架内。

3.3 技巧3：参数化提示词，把“写死”变成“可配置”

很多人把提示词写成静态文本，比如“用Plotly画折线图”。这导致每次换图表类型都要重写提示词。我的做法是，把提示词本身模块化。我维护一个prompt_templates/目录，里面是Jinja2模板：

# chart_module.j2 请生成Python模块文件`{{ module_name }}.py`，实现{{ chart_type }}图表。 输入数据源：{{ data_source }} 约束条件： 1. 使用`@st.cache_data(ttl={{ cache_ttl }})`装饰数据函数 2. 图表必须用`plotly.express.{{ px_func }}`实现 3. 颜色主题适配`st.theme`，使用`color_discrete_sequence=px.colors.sequential.{{ color_scheme }}` 4. 输出组件必须包含`st.plotly_chart(fig, use_container_width=True)`

调用时，用Python脚本注入变量：

from jinja2 import Template template = Template(open("prompt_templates/chart_module.j2").read()) prompt = template.render( module_name="user_retention", chart_type="用户留存率热力图", data_source="bigquery.user_retention_v3", cache_ttl=600, px_func="heatmap", color_scheme="Blues" )

这带来的好处是：当产品说“把所有图表颜色换成暖色系”，我只需改模板里的color_scheme，一键批量重生成所有模块，无需人工逐个修改提示词。Prompt Engineering从此不再是手工作坊，而是可版本控制、可CI/CD的工程实践。

3.4 技巧4：引入“领域词典”，校准术语歧义

Streamlit社区里，“component”可以指st.button这样的原生组件，也可以指streamlit-component-template生成的自定义Web组件。AI常混淆二者。我的解法是，在每次提示词开头，嵌入一个微型领域词典：

【术语定义】

• “UI组件”：指Streamlit内置函数，如st.button,st.dataframe
• “自定义组件”：指通过streamlit.components.v1.declare_component注册的JS组件
• “模块”：指一个独立.py文件，必须导出render()函数
• “胶水层”：指app.py，负责导入并调用各模块的render()
  请严格按以上定义使用术语。

这个不到100字的词典，解决了80%的术语误用问题。它相当于给AI装了一个实时翻译插件，确保它说的“模块”，和你脑子里想的“模块”，是同一个东西。在跨团队协作中，这个词典甚至可以作为团队Wiki词条，保证所有人对AI协作流程的理解一致。

3.5 技巧5：设置“可信度阈值”，对模糊输出说不

AI有时会输出模棱两可的答案，比如：“建议使用st.cache_data，但st.cache_resource在某些场景下也可用”。这种“和稀泥”式回答，在工程中毫无价值。我的应对策略是，在提示词中植入可信度声明要求：

请对以下问题给出确定性回答，禁止使用“可能”、“建议”、“通常”等模糊词汇。如果存在技术限制导致无法满足某项要求，请明确指出限制原因（如“Streamlit 1.25不支持在st.cache_data中使用异步函数”），并提供替代方案。最后，用[CONFIDENCE: HIGH/MEDIUM/LOW]标注你的回答可信度。

这个技巧的威力在于，它把AI的“不确定感”外化为可评估的信号。当我看到[CONFIDENCE: LOW]，就知道这部分需要人工核查；而[CONFIDENCE: HIGH]的回答，我直接信任并集成。在Dashboard开发中，这节省了大量“验证AI是否在瞎说”的时间。毕竟，工程师的时间，应该花在解决真问题上，而不是给AI当校对员。

3.6 技巧6：构建“反馈记忆库”，让AI学会从错误中成长

单次对话中，AI无法记住你的偏好。但你可以用外部记忆库模拟长期记忆。我维护一个ai_feedback_log.md文件，记录每次AI出错的案例：

## 2024-06-15 | 错误：`st.cache_data`位置错误 - 输入提示：生成库存预警模块 - AI输出：`st.button("刷新")`放在`@st.cache_data`函数内 - 原因：未理解缓存函数的执行时机 - 修正：在提示词中增加约束“所有交互组件（st.button/st.selectbox等）必须在缓存函数外部调用” - 效果：后续5次同类请求，0次复现 ## 2024-06-18 | 错误：Plotly颜色主题不匹配 - 输入提示：使用`px.colors.sequential.Reds` - AI输出：用了`px.colors.qualitative.Set1` - 原因：混淆sequential与qualitative调色板 - 修正：在领域词典中明确定义“sequential调色板用于数值映射，qualitative用于分类” - 效果：后续3次请求，全部正确

这个日志不是为了抱怨AI，而是为了提炼可复用的Prompt优化规则。每一条记录，最终都会沉淀为提示词模板中的新约束。久而久之，你的AI协作流程，就从“随机碰运气”，进化成了“有据可循的工程体系”。这才是Prompt Engineering的终极形态——不是调教AI，而是构建一套人机共生的开发操作系统。

4. 实操过程详解：从零搭建可复用的销售看板

4.1 第一步：定义模块契约——用YAML锁定接口

我们以“销售趋势图表”模块为例，启动第一次AI对话。提示词如下（已整合前述技巧）：

【术语定义】 - “模块”：一个独立Python文件，必须导出`render()`函数 - “输入参数”：`render()`函数的参数，必须有类型注解 - “输出组件”：`render()`函数内调用的Streamlit组件列表 请严格按以下格式输出模块契约，不得添加任何额外文字： ---YAML_START--- name: sales_trend_chart description: 展示近30天销售额趋势，支持按产品线筛选 input_schema: type: object properties: date_range: type: array items: type: string format: date minItems: 2 maxItems: 2 product_line: type: string enum: ["all", "electronics", "clothing", "home"] required: ["date_range", "product_line"] output_components: ["st.plotly_chart", "st.metric"] data_source: "postgres.sales_summary_v2" theme_compatibility: both ---YAML_END---

AI返回（经脱敏）：

---YAML_START--- name: sales_trend_chart description: 展示近30天销售额趋势，支持按产品线筛选 input_schema: type: object properties: date_range: type: array items: type: string format: date minItems: 2 maxItems: 2 product_line: type: string enum: ["all", "electronics", "clothing", "home"] required: ["date_range", "product_line"] output_components: ["st.plotly_chart", "st.metric"] data_source: "postgres.sales_summary_v2" theme_compatibility: both ---YAML_END---

提示：YAML输出必须严格匹配分隔符。如果AI在---YAML_END---后多写了字，立刻拒收并重试。这是质量守门员。

4.2 第二步：生成模块代码——聚焦单一职责

拿到YAML后，发起第二次对话。提示词注入契约内容，并强化约束：

请根据以下模块契约，生成Python文件`sales_trend_chart.py`： ---YAML_START--- name: sales_trend_chart input_schema: {"type": "object", "properties": {"date_range": {"type": "array", "items": {"type": "string", "format": "date"}, "minItems": 2, "maxItems": 2}, "product_line": {"type": "string", "enum": ["all", "electronics", "clothing", "home"]}}, "required": ["date_range", "product_line"]} output_components: ["st.plotly_chart", "st.metric"] data_source: "postgres.sales_summary_v2" theme_compatibility: both ---YAML_END--- 要求： 1. 文件必须导出`def render(date_range: list[str], product_line: str) -> None:`函数 2. 数据加载必须用`@st.cache_data(ttl=300)`装饰，函数名为`load_data()` 3. `load_data()`必须接收`date_range`和`product_line`参数，从`postgres.sales_summary_v2`查询 4. 图表必须用`plotly.express.line()`，X轴为`date`，Y轴为`revenue` 5. `st.metric()`显示总销售额，label为"30天总营收" 6. 所有字符串用f-string，禁止硬编码 7. 文件顶部添加Google风格docstring，说明参数和副作用 8. [CONFIDENCE: HIGH]必须标注

AI返回（关键部分）：

"""Sales trend chart module. Args: date_range: List of two ISO format dates [start, end]. product_line: Product line filter, one of ["all", "electronics", ...]. Returns: None. Renders Streamlit components directly. """ import pandas as pd import plotly.express as px import streamlit as st @st.cache_data(ttl=300) def load_data(date_range: list[str], product_line: str) -> pd.DataFrame: """Load sales data from postgres.sales_summary_v2.""" # Simulated DB query - replace with real connection # df = pd.read_sql(f"SELECT date, revenue FROM sales_summary_v2 WHERE date BETWEEN '{date_range[0]}' AND '{date_range[1]}' AND product_line = '{product_line}'") # For demo, return mock data dates = pd.date_range(date_range[0], date_range[1], freq='D') df = pd.DataFrame({ 'date': dates, 'revenue': [1000 + i*50 for i in range(len(dates))] }) return df def render(date_range: list[str], product_line: str) -> None: """Render sales trend chart and metric.""" df = load_data(date_range, product_line) # Calculate total revenue total_revenue = df['revenue'].sum() st.metric(label="30天总营收", value=f"¥{total_revenue:,.0f}") # Create line chart fig = px.line(df, x='date', y='revenue', title=f"{product_line} 销售趋势") fig.update_layout( margin=dict(l=20, r=20, t=40, b=20), height=400 ) st.plotly_chart(fig, use_container_width=True) # EOF [CONFIDENCE: HIGH]

注意：AI生成的DB查询是模拟的（注释已标明），实际项目中，你会替换为真实的SQLAlchemy或psycopg2连接。关键是，它完美遵守了所有约束：缓存装饰、f-string、docstring、组件调用顺序。

4.3 第三步：构建胶水层——组装模块的主程序

现在，我们有sales_trend_chart.py，再按同样流程生成inventory_alert.py和user_activity_heatmap.py。接着，发起第三次对话，构建胶水层：

请生成Streamlit主应用`app.py`，集成以下三个模块： 1. `sales_trend_chart.py`：销售趋势图表 2. `inventory_alert.py`：库存预警（低库存商品列表） 3. `user_activity_heatmap.py`：用户活跃度热力图 要求： 1. 使用`st.tabs(['销售趋势', '库存预警', '用户活跃'])`组织页面 2. 在侧边栏添加`st.radio('主题', ['浅色', '深色'], key='theme')`，并根据选择动态设置CSS变量（参考Streamlit官方主题文档） 3. 每个tab内，调用对应模块的`render()`函数，传入合理默认参数 4. 所有模块通过`import`导入，禁止复制粘贴代码 5. 添加全局异常处理：用`try/except`包裹每个模块调用，捕获`Exception`并显示`st.error(f'模块加载失败: {str(e)}')` 6. [CONFIDENCE: HIGH]必须标注

AI返回app.py（精简版）：

import streamlit as st from sales_trend_chart import render as render_sales from inventory_alert import render as render_inventory from user_activity_heatmap import render as render_activity # 主题切换 theme = st.sidebar.radio('主题', ['浅色', '深色'], key='theme') if theme == '深色': st.markdown(""" <style> :root { --background-color: #1a1a1a; --text-color: #ffffff; } </style> """, unsafe_allow_html=True) # 页面标签 tab1, tab2, tab3 = st.tabs(['销售趋势', '库存预警', '用户活跃']) with tab1: try: render_sales(date_range=["2024-01-01", "2024-01-30"], product_line="all") except Exception as e: st.error(f'模块加载失败: {str(e)}') with tab2: try: render_inventory(threshold=10) except Exception as e: st.error(f'模块加载失败: {str(e)}') with tab3: try: render_activity() except Exception as e: st.error(f'模块加载失败: {str(e)}') # EOF [CONFIDENCE: HIGH]

4.4 第四步：本地验证与调试——别跳过这一步

生成完所有文件，立刻在本地环境验证。我的标准检查清单：

1. 目录结构检查：

   dashboard/ ├── app.py ├── sales_trend_chart.py ├── inventory_alert.py ├── user_activity_heatmap.py └── requirements.txt # 必须包含 streamlit, plotly, pandas

2. 依赖安装：

   pip install -r requirements.txt streamlit run app.py

3. 功能验证：

   • 切换Tabs，确认各模块渲染无空白
   • 点击侧边栏主题切换，检查CSS变量是否生效（浏览器开发者工具→Elements→:root）
   • 修改sales_trend_chart.py中st.metric的value，保存后观察Streamlit自动热重载是否生效

4. 错误注入测试：
   故意在sales_trend_chart.py的load_data()里加一行raise ValueError("Simulated DB Error")，刷新页面，确认st.error正确显示，且其他Tab不受影响。这验证了胶水层的容错能力。

实操心得：我坚持“生成即验证”，绝不等到所有模块做完再测。因为模块间耦合度低，早发现问题，早修正Prompt。曾有一次，inventory_alert.py生成的render()函数名是show_alerts()，导致app.py导入失败。我立刻把这个问题记入ai_feedback_log.md，并在后续所有模块提示词中加入约束：“函数名必须为render，禁止使用show_、display_等前缀”。

4.5 第五步：部署与持续迭代——让AI成为你的DevOps助手

本地验证通过后，部署到生产环境。我用Docker，Dockerfile极简：

FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

构建并运行：

docker build -t sales-dashboard . docker run -p 8501:8501 sales-dashboard

更关键的是持续迭代。当业务方提出新需求，比如“在销售趋势图上加预测线”，我不重写整个模块，而是：

1. 更新sales_trend_chart.yaml，在input_schema中增加forecast_days: integer字段
2. 让AI基于新契约重生成sales_trend_chart.py，它会自动添加prophet或statsmodels预测逻辑
3. 由于胶水层只认render()函数签名，只要新模块的参数兼容旧版（如forecast_days设默认值），app.py完全不用改

这就是模块化+Prompt Engineering的复利效应：每一次AI协作，都在加固你的工程资产，而不是消耗它。

5. 常见问题与排查技巧实录：那些AI不会告诉你的坑

5.1 问题1：AI生成的代码能跑，但性能奇差——缓存失效的隐形杀手

现象：Dashboard首次加载慢，F5刷新后依然慢，st.cache_data像没起作用。
排查过程：我在load_data()函数里加了st.write("Data loaded at", datetime.now())，发现每次刷新都打印新时间戳。
根因：AI生成的代码里，@st.cache_data装饰的函数，参数中包含了st.session_state对象或st.query_params。Streamlit缓存键（cache key）会序列化整个参数对象，而st.session_state是动态变化的，导致缓存键永远不同，缓存永不命中。
解决方案：在提示词中强制约束——“@st.cache_data函数的参数只能是Python原生类型（str, int, list, dict）、Pandas DataFrame或NumPy array。禁止传入任何Streamlit对象（如st.session_state,st.query_params）”。同时，在胶水层做参数预处理：

# 在app.py中 params = { "date_range": st.query_params.get("date", ["2024-01-01", "2024-01-30"]), "product_line": st.query_params.get("line", "all") } render_sales(**params) # 传入纯净字典，非st.query_params对象

实操心得：缓存失效是Dashboard性能头号杀手。我养成了一个习惯：每次AI生成带缓存的函数，必用st.write打日志验证。宁可多花10秒，也不让问题流入生产。

5.2 问题2：主题切换失效——CSS变量作用域的陷阱

现象：侧边栏切换“深色/浅色”，页面背景没变，但st.metric的数字颜色变了。
排查过程：浏览器检查元素，发现:rootCSS变量确实被注入，但<div class="stApp">的背景色仍继承自浏览器默认。
根因：Streamlit的st.markdown(..., unsafe_allow_html=True)注入的CSS，作用域是全局，但Streamlit组件（如st.metric）的内部样式，用的是Shadow DOM或内联style，会覆盖:root变量。
解决方案：在提示词中要求AI生成的模块，必须显式使用CSS变量。例如，在sales_trend_chart.py的render()函数末尾加：

# 强制应用主题变量 st.markdown(""" <style> .stMetricValue { color: var(--text-color, #000000); } </style> """, unsafe_allow_html=True)

更彻底的解法，是让AI在app.py胶水层中，用st.set_page_config()配合自定义CSS，但这超出模块范畴，属于架构决策。我的经验是：把主题适配的负担，从模块层上移到胶水层，让模块专注业务逻辑，胶水层专注呈现逻辑。

5.3 问题3：模块间状态污染——session_state的幽灵

现象：在“库存预警”Tab里筛选商品，切到“销售趋势”Tab，再切回来，筛选条件丢失。
根因：AI生成的inventory_alert.py里，用了st.session_state.filter = st.selectbox(...)，但没做初始化。当用户切Tab，Streamlit会销毁当前Tab的state，导致filter变量消失。
解决方案：在提示词中加入硬性约束——“所有使用st.session_state的模块，必须在render()函数开头添加初始化逻辑：if 'filter' not in st.session_state: st.session_state.filter = 'all'”。同时，在胶水层app.py中，用st.session_state做跨Tab状态同步：

# 在app.py顶部 if 'global_filter' not in st.session_state: st.session_state.global_filter = 'all' # 在每个Tab的render调用中传入 render_inventory(filter=st.session_state.global_filter)

注意：st.session_state不是银弹。我严禁AI在模块内直接修改st.session_state，所有状态管理必须由胶水层统一调度。这牺牲了一点灵活性，但换来的是可预测性。

5.4 问题4：第三方库版本冲突——AI的“过时知识”

现象：AI生成的代码用st.experimental_rerun()，但我的Streamlit是1.30+，该函数已废弃，应为st.rerun()。
根因：大模型的训练数据截止于2023年中，它不知道2024年Streamlit 1.30的breaking change。
解决方案：在提示词开头，强制声明环境约束——“你是一个Streamlit 1.32专家，所有代码必须兼容此版本。禁止使用任何已废弃的API（如st.experimental_rerun,st.beta_columns），必须使用最新API（如st.rerun,st.columns）”。同时，我的requirements.txt固定版本：

streamlit==1.32.0 plotly==5.18.0 pandas==2.0.3

实操心得：我建立了一个compatibility_matrix.md，记录各库版本与AI知识边界的对应关系。例如：“Streamlit 1.25-1.29：允许st.experimental_get_query_params；1.30+：必须用st.query_params”。这让我能精准“投喂”AI所需的知识上下文。

5.5 问题5：安全警告频发——AI对生产环境的无知

现象：app.py里AI生成了st.markdown(f"<script>alert('{user_input}')</script>", unsafe_allow_html=True)，这直接导致XSS漏洞。
根因：AI在训练数据中见过大量“演示用”的unsafe HTML，但它不懂OWASP Top 10。
解决方案：在全局提示词中植入安全红线——“所有st.markdown(..., unsafe_allow_html=True)必须满足：1. 内容为静态字符串，禁止拼接用户输入；2. 若需动态