---
name: report-authoring
description: 把建筑模型与模拟结果整理成报告/文档内容。当用户要求写节能专篇、性能报告、甲方汇报材料，或需要从当前项目取指标与结论成文时使用。
---

# DETA Writer —— 报告与文档产出

## ★ 先读：能力边界与取数顺序

本插件负责**产出报告内容**（文本 / Markdown / 结构化数据），不负责排版与导出：

- **报告模板、插槽填充、docx 导出在门户 Writer 页面**（`https://deta.city/writer?doc=<docId>`）——
  不在本插件的工具面里，不要试图用 MCP 工具生成模板或导出文件。
- 本插件能做的是：读模型与工作区文件、取统计数据、取模拟结果、查规范指标，然后把它们写成文字。
- 不确定当前有哪些工具时，先调 **`list_capabilities`** 拿完整工具名再按名字调用
  （检索一次只回少量结果，搜不到不等于不存在）。

## 取数顺序（每步都可能缺数据，缺就如实标注）

1. **模型真值**：工作区里的 `aml.xml` / `building.json`——用宿主原生文件工具或 `read_source` 读。
2. **围护结构统计**：外墙/外窗面积、实际窗墙比、朝向分布——用 `envelope_stats` 取，不要手算。
3. **性能分析**：能耗、舒适度等按需用 `analyze_building`；结果里的 `executor` / `backend` 标注要照抄进报告。
4. **模拟结果缓存**：已跑过的采光/日照/通风等结果用 `query_simulation_db` 查，避免重复跑。
5. **气象**：需要气候分区/月均/极值数据时先 `load_weather` 加载气象文件，再取结果。
6. **规范与指标**：阈值、限值、技术策略必须用 `query_knowledge` 取原值，不得凭经验写数。

## 铁律

1. **不编造数值**。任何数字要么来自工具返回、要么来自工作区文件；没有就写 `--` 或删掉那句话，
   不要用"约/大约/典型值"填空。
2. **区分设计值与限值**。设计值由模型算出；限值来自规范条文，缺失时留空并标注"待补规范限值"。
3. **标注数据来源与执行位置**。同一指标可能来自本机引擎或 Studio 执行器，按工具返回的标注如实写。
4. **写报告是只读过程**。不要顺手改模型；确需修正时明确告知用户并单独确认。
5. **控制单会话工具调用量**。写报告是长流程，撞到命名空间重复类错误时不要重试，另起会话继续
   （工作区文件不会丢）。

## 标准工作流

1. 确认写什么：报告类型、范围（整栋/单栋/单专业）、读者（甲方/评审/内部）。
2. 列"能写什么、缺什么"两栏，**先把缺项告诉用户**，不要写到一半才发现没数据。
3. 按取数顺序补齐数据（能算的算、能查的查）。
4. 成文：分章节写入工作区（Markdown），每段数据标注来源指标名；缺项如实留空。
5. 交回用户：说明哪些章节已完稿、哪些等数据；需要在门户导出 docx 时给出 Writer 页面链接。