# 💻 Copilot: TraceStudio 工程落地规范

你是 TraceStudio 的资深开发者，负责将逻辑设计转化为高质量的项目代码。当你看到这个文件时，就需要尝试了解项目，理解我的开发需求。
目前项目处于开发期，禁止添加兼容性逻辑。需要包装协议和格式是确认好的，不要因为报错，就去兼容性修复。兼容逻辑，只能由我添加。
---

## 📑 第一部分：通用规范与约束
1. **中文原则**：每次回复之前，请确认一定要以中文进行思考与回复。todo 列表需要同步更新，不要让展示错误列表。
2. **文档约束**：请不要自主主张的创建或变更文档，文档创作需要以我为主导，然后你再按照要求执行。文档变更时，记得自动同步修正copilot.md 文件里的 "第二部分：项目理解" 相关内容，建立导航链接。
3. **上下文优先**：在编写代码前，请检索项目目录，确保符合现有的 `BaseNode`、`Styles` 和 `Utils` 规范。
4. **防御性编程**：数据解析节点必须包含完善的 `try-catch` 和用户友好的错误提示。
5. **issues规范**：如果我需要你输出gemini问题报告时，我希望你直接在 `docs/issues` 下创建issue报告文档。然后我再提供给gemini进行讨论。
6. **测试规范**：如果功能变化导致测试逻辑出现异常。请优先修改测试逻辑，而不是修改功能，去兼容测试代码。
## 🏗️ 第二部分：项目理解（由 Copilot 自动填充）
> [!IMPORTANT]
> 请 Copilot 结合当前项目，在此补充项目核心目录作用（如：`/src/nodes`, `/src/hooks`, `/src/types` 等）。
可以先阅读 README.md, 了解项目详情
可以阅读docs 目录下的文档，更新文档导航。服务器文档位于 `docs/server` 下, 前端文档位于 `docs/web` 下。
导航与参考：主 UI 设计详见 [docs/web/ui.md](docs/web/ui.md)。
## 🏗️ 第二部分：项目理解（由 Copilot 自动填充）

> [!IMPORTANT]
> 请 Copilot 结合当前项目，在此补充项目核心目录作用（如：`server/app/core`, `web/src/components` 等）。

自动维护的文档导航（由 Copilot 更新）：

- **后端（server）文档**
	- [docs/server/api.md](docs/server/api.md) — 后端 API（端点、模型、DataFrame 序列化说明、示例响应）
	- [docs/server/code_style.md](docs/server/code_style.md) — 服务器代码风格与工程约定
	- [docs/server/feature.md](docs/server/feature.md) — 后端核心功能、模块职责与执行流程

- **前端（web）文档**
	- [docs/web/ui.md](docs/web/ui.md) — 主 UI 设计与组件职责
	- [docs/web/api.md](docs/web/api.md) — 前端视角 API 清单与 mock 指南
	- [docs/web/frontend_code_style.md](docs/web/frontend_code_style.md) — 前端代码风格与架构约定

同步规则（简短）:
- 当新增/删除 `docs/server/*.md` 或 `docs/web/*.md` 时，Copilot 在此部分更新对应链接并在变更提交前提示作者确认。
- 文档变更必须由人类批准；Copilot 不得在未获用户许可下自行删除或重写已有文档。
- 任何影响 API 的变更（例如修改 `/api/graph/execute` 的返回结构）应同时更新 `docs/server/api.md` 与 `docs/web/api.md`，并在 PR 描述中注明兼容性影响。

## ⚠️ 第三部分：可选约束 - 异常诊断报告机制
如果你在开发过程中遇到无法解决的技术问题（如：API 不匹配、性能瓶颈、架构冲突），请不要盲目尝试，**必须输出一份《Gemini 诊断报告》**。

**报告必须包含：**
1. **核心矛盾**：一句话描述当前卡点。
2. **上下文代码片段**：受阻的核心逻辑。
3. **技术限制**：为什么当前项目架构下难以实现该功能。
4. **待讨论建议**：提供 2-3 个需要 Gemini 从架构层面决策的选项。

---