Imported from charlzhu/gcl-bp-ai (AGENTS.md). Install upstream with npx skills add charlzhu/gcl-bp-ai. Copyright stays with the author.

AGENTS.md

一、文件用途

本文件用于让接手本项目的 Codex / 工程代理在开始工作前，快速理解项目目标、当前边界、工作规则和代码约束。

二、项目概述

1. 项目名称

经营计划智能助手

2. 当前项目阶段

上一阶段“物流 + BOM 全量样例题真实网页 E2E”已经完成，当前基线为：

• 真实网页 E2E：3281/3281 完成，PASS=3281 / FAIL=0
• 物流：A=656 / B=178 / C=69 / D=0
• BOM：A=86 / B=40 / C=3 / D=0
• BOM QA API E2E：30/30
• BOM 多问法语义回归：129/129
• 物流 903 语义回归：1559/1559
• 前端 build：通过

当前新的正式任务为：

计划 BOM 功率预测智能问答 / 功率测试基准能力

该能力属于现有 计划 BOM 业务域 的子能力，不新建独立业务域。

3. 当前优先建设范围

当前优先执行：

M1：功率预测 Excel 结构与公式审计 + 现有计划 BOM 链路梳理 + 后续实施方案设计

本轮只允许输出：

docs/PLAN_POWER_EXCEL_FORMULA_AUDIT.md
docs/PLAN_POWER_IMPLEMENTATION_PLAN.md

本轮不要创建数据库迁移、不要新增接口、不要修改前端、不要接入 PlanBom QA、不要实现正式计算引擎。

三、当前任务背景

业务提供了《GCL功率测试基准》xlsm 文件。该文件不是普通静态表，而是动态功率预测模型。

业务人员在 Excel 中选择不同配置后，下方电池效率区、各功率档百分比、组件预测模型档位分布、电池产出分布会自动变化。

配置项包括但不限于：

• 焊带选型
• 玻璃选型
• 电池厂家
• 电池尺寸
• 面积
• 标准差
• 线缆长度
• 汇流条
• 标板基准

最终系统目标不是做一个让业务员手动点配置的网页，而是：

业务员自然语言提问
↓
系统识别订单 / 版型 / 配置 / 供应商 / 目标功率 / 目标比例
↓
如涉及订单，则查询现有 BOM 数据
↓
从 BOM 中抽取玻璃、间隙贴膜、焊带、汇流条、接线盒等配置
↓
映射到功率预测模型配置项
↓
调用后端确定性功率预测计算引擎
↓
返回供应商、效率段、功率档位分布、目标比例匹配度

四、必须读取的任务资料

当前任务以 ai/inbox/requirement.md 为主任务说明。

执行前必须读取：

1. AGENTS.md
2. README_WORKSPACE.md
3. docs/CURRENT_STATUS.md
4. docs/NEXT_TASK.md
5. ai/protocols/company_task_protocol.md
6. ai/company/roles/technical_manager.md
7. ai/hermes_skills/company-code-builder/SKILL.md
8. ai/inbox/requirement.md
9. ai/inbox/attachments_manifest.md
10. ai/inbox/attachments/ 下的附件

附件包括：

GCL功率测试基准（V2.1）26.03.26 (1).xlsm——副本.xlsm
BOM配置搭配问询：.docx

如果附件不存在、文件名不一致或无法读取，必须停止并报告，不允许编造附件内容。

五、关键业务规则

1. BOM 配置搭配问询样例文档规则

BOM配置搭配问询：.docx 只作为业务问题类型和问法参考。

必须遵守：

1. 文档中的版型号是假的。
2. 文档中的订单号是假的。
3. 文档中的评审号是假的。
4. 文档中的项目名是假的。
5. 文档中的问题不能当成真实验收数据。
6. 不能 hardcode 文档中的问题或答案。
7. 不能为了让样例题通过而伪造结果。
8. 正式测试题必须基于当前项目真实 BOM 数据自行生成。

2. 功率预测 Excel 规则

GCL功率测试基准 xlsm 是动态模型，不是静态明细表。

必须审计：

1. Sheet 结构。
2. 配置区。
3. 配置选项和功率影响值。
4. 电池效率区。
5. 功率档位分布区。
6. 供应商效率分布区。
7. 标板基准。
8. 公式依赖。
9. VBA / 宏是否参与核心计算。
10. 后端是否可以复现计算逻辑。

3. LLM 与后端职责边界

LLM 只允许负责：

1. 意图识别。
2. 槽位抽取。
3. 同义词归一化辅助。
4. 答案表达。

后端确定性代码必须负责：

1. BOM 查询。
2. 功率模型解析。
3. 公式计算。
4. 功率档位分布计算。
5. 供应商推荐。
6. 效率段推荐。
7. 匹配度计算。
8. 版本追溯。

不允许让 LLM 直接计算功率预测结果。

六、当前代码状态判断规则

最重要规则：

不要根据历史聊天、历史补丁或历史 zip 文件，推断当前仓库已经具备某项能力。

一切必须遵循：

1. 先读取当前仓库代码。
2. 先判断当前能力是否已真实合入。
3. 再决定是否继续开发或修复。
4. 如果文档与代码冲突，以当前代码和本轮任务要求为准，并在报告中说明差异。

严禁行为：

1. 不要假设“之前做过的版本”一定已经在当前仓库里。
2. 不要用历史 zip 名称当事实来源。
3. 不要跳过代码审查，直接继续写下一版。
4. 不要因为看到样例题就 hardcode 答案。

七、Codex 工作流程要求

第一步：先审查再开发

每次开始工作时，必须先输出：

1. 当前仓库已完成能力判断。
2. 当前未完成能力判断。
3. 本次任务是否与当前仓库状态一致。
4. 本轮允许修改范围。
5. 本轮禁止修改范围。

第二步：复杂任务先给计划

如果任务涉及多个文件、多个步骤或多个工具，必须先给计划，再开始修改。

当前功率预测任务必须先完成 M1 审计文档，不得直接进入代码开发。

第三步：增量修改优先

1. 优先增量修改。
2. 不大规模重构目录结构。
3. 不轻易改接口命名。
4. 不随意改变返回字段结构。
5. 不污染现有 BOM 查询主链路。

第四步：中文注释

所有新增和修改代码必须写中文注释。

中文注释要求：

1. 说明函数功能。
2. 说明参数含义。
3. 说明返回值。
4. 说明重要业务逻辑。
5. 对复杂判断、兼容逻辑、降级逻辑写清楚原因。

第五步：完成后必须输出

1. 修改文件清单。
2. 关键改动说明。
3. 测试方法。
4. 风险点。
5. 当前仍未解决的问题。
6. 是否影响现有 BOM / 物流能力。

八、完整交付模式与阶段边界

当用户明确说“完整交付模式”时，按完整交付规则执行。

但如果 ai/inbox/requirement.md 或 docs/NEXT_TASK.md 明确规定“本轮只执行 M1 / 只产出文档 / 完成后等待确认”，则必须遵守该阶段边界。

当前任务明确规定：

本轮只执行 M1，完成后停止并等待确认。

因此当前不能自动进入 M2/M3/M4/M5。

九、代码风格要求

后端

1. 保持当前 FastAPI / service / repository 分层风格。
2. 优先复用现有 service，不重复造一套新 service。
3. 保持当前 logistics 域目录结构不被破坏。
4. 计划 BOM 功率预测能力应作为 plan_bom 域子能力接入。
5. 后续如新增功率预测模块，应保持边界清晰，避免污染 BOM 查询主链路。

前端

1. 保持当前 Vue3 + Element Plus 风格。
2. 当前前端以“可联调、可展示、可回溯”为优先。
3. 不要一上来做重 UI 重动画。
4. 当前 M1 不修改前端。

命名

1. 指标名、字段名、模板名与当前项目统一。
2. 若引入新命名，必须与现有语义兼容。
3. 功率预测相关建议使用 plan_power_ 前缀。

十、安全与配置要求

严禁提交：

1. .env
2. 真实数据库密码
3. Redis / Milvus 密码
4. 生产连接串
5. API Key

应只保留：

1. .env.example
2. 示例配置
3. 安全占位值

打包与提交前应清理：

1. __pycache__/
2. *.pyc
3. __MACOSX/
4. .idea/
5. .pytest_cache/
6. .env
7. .DS_Store

十一、当前优先级

当前第一优先级

完成计划 BOM 功率预测智能问答 M1 审计：

1. 读懂功率预测 Excel。
2. 审计公式 / VBA / 宏依赖。
3. 梳理现有 BOM / QA / 智能助手链路。
4. 输出后续实施方案。

当前第二优先级

在 M1 被用户确认后，再进入：

1. M2：功率模型版本与入库。
2. M3：功率预测计算引擎。
3. M4：BOM 配置自动映射。
4. M5：接入 PlanBom QA 和智能助手。

当前不再继续物流 E2E 自动续跑，不继续强行迁 B 到 A，不扩经营分析，不扩 RAG，不扩 Agent。