finCopilot

碳资产簿：新增一条分录（admin）。entryType: baseline|savings|offset|quota|trading。

新增一条案例到 Folio（finMcpCase 记录）。admin 限定。 经 KnowledgeStore 写入：配了嵌入端点时顺带向量化，供 recall_cases 语义混合召回（C1）。

新建设备跟踪：point 越阈→通知或建工单。condition above|below|outside|equals。admin 限定。

灵活查询/聚合：按"目标×颗粒度×聚合器(×公式)"做确定性时序聚合 → JSON 字符串。 等价 MCP aggregate_query。specJson = QuerySpec JSON（targets/range/granularity/aggregator/formula/unit/viz）； range 参数若给则覆盖 spec.range（便于函数构建器/调度复用同一 spec 跑不同周期）。只读 $0。

人工审批落值（运维已授权）。admin 限定。复用 McpTools.approve（单一写实现）。 value 支持 Number / Bool / Str（枚举档位），由 McpTools.approve 按点位 kind 强制类型。 level=写入优先级（默认 8；护栏拒 1-7，B3）。前端控制卡可传 8-16。

一键批准整包：逐条重过护栏 + 落值；有批准成功则整包建【一张】汇总工单并逐条 link。admin 限定。

批准单条提案：重过护栏 + 落值（复用 McpTools.approve 单一写实现），置状态； 批准成功即自动转工单（linkedSessionId=packageId，与「已安排」任务贯通）。admin 限定。

当前 ASR 配置状态（不回显密钥）+ available（配置是否完整可构造客户端）。

护栏审计日志（每条写决策留痕）→ Grid。纯读，不触碰写路径。

LLM 自动打标（入库前辅助）：抽文档头部片段，一次性无工具调用 → JSON {docRef, equipType, equipRef, keywords}。纯只读、不入库、不产生写。admin 限定。 未配 LLM / 调用失败 / 模型无判断 → docRef 回落（文件名提示 > 文档首标题），其余留空 （前端保留手填值，绝不臆造 equipRef）。解析为确定性纯函数 parseTags（EvalRunner 覆盖）。

Invalid annotation [] [fandoc:1] - ""

取批次结果 → JSON [{custom_id,status,text}]（须状态 ended）。admin 限定。

查批次状态（processing_status / request_counts）→ JSON。admin 限定。

提交一批单轮请求 → 批次 id。promptsJson=[{id,prompt,system?,model?,maxTokens?}]。 仅 provider=anthropic（批量为 Anthropic 专属）。admin 限定。

构建自定义报告（按 def id 加载区块清单 → 数据驱动装配）→ ReportData JSON。

碳核算与碳强度（Scope2 电 + 可选 Scope1 燃气 + Scope3 外购热/蒸汽，因子库按 year 选取，单位感知）→ JSON。

碳资产 M&V：节能量 → 碳减排(tCO₂) → 碳权市值 → JSON。

协作式取消（轮次边界生效，取消后不再产生写提案）。

增量取事件：→ JSON {events, nextAfter, status}。前端按 nextAfter 续取。

Invalid annotation [] [fandoc:1] - "capabilityId 选领域 Agent；contextJson 为前端传的 {targetRef?, scope, projectName?}，"

启动一轮会话，返回 sessionId。messagesJson 为 [{role,content}] 的 JSON。 capabilityId 选领域 Agent；contextJson 为前端传的 {targetRef?, scope, projectName?}， 在此请求线程解析为提示词前言（含设备 dis），随会话注入给 Agent。

冷机性能特性散点（逐机 x=冷量/y=实测 COP + 额定参照）→ JSON。等价 MCP chiller_performance。只读 $0。

关闭工单并沉淀：置 closed + resolution/outcome；crystallize 时把已验证处置升级为 finMcpCase （复用 store.addCase，配嵌入端点则向量化入 RAG），喂回 recall_cases。返回 JSON {id, status:closed, caseId?, embedded}。admin 限定。

系统 KPI（COP/kW·RT⁻¹/输配系数/逐台冷机/EUI/PUE）→ JSON。

确认一条记忆（pending→confirmed，配端点则补向量）→ JSON。admin 限定。

把运维 Copilot 注册进 FIN app 启动器菜单。

新建自定义计划任务。schedule 语法 daily/weekday/weekly/interval（先校验非法即抛）。admin 限定。

起草工单（诊断会话收尾 seed 症状/根因/已采取动作）→ JSON {id, status:open}。admin 限定。 createdBy 取当前 FIN 用户；linkedSessionId 关联诊断会话（可回看轨迹）。

仅列出 Critical 级激活报警（驾驶舱告警卡片便捷入口）。底层复用 FinMcpLib.finMcpListAlarms，护栏与权限不变。

删除一段已保存会话。非 admin：仅作用于当前用户自己的子目录（id 经 sanitizeId 防穿越），安全。

删除自定义任务。admin 限定。

删除一篇已入库文档（按 docRef）：清除其全部分块 + 向量记录（Folio finMcpChunk）。 admin 限定。返回 JSON {docRef, removed}（removed=删除块数）。

删除一条记忆（弃用/纠错）。admin 限定。

删除自定义报告。admin 写。

删除 watch。admin 限定。

实体详情（上下文检查器用）→ recToJson 的 JSON 字符串（含标签/元数据/协议绑定 B1）。 走 JSON 字符串而非 Grid，避免 Hayson 数字/列表包裹，前端 JSON.parse 即得纯量。

时序异常检测（zscore|slope|yoy）→ JSON。便于调度/eval 直接调（与工具面共用 invoke）。

AI 起草灵活查询：自然语言 → 一次性 LLM 产 QuerySpec(targets/granularity/aggregator/formula/viz)， grounding 真实设备清册 + 标签词表（防臆造过滤器）。只读、记账。parseQueryDraft 做结构/白名单/安全字符校验。 返回 {title, spec, usage} 供 QueryBuilderDialog 回填 4 步表单（用户再微调 + 试运行）。

AI 起草自定义报告：自然语言 → 一次性 LLM 从区块白名单选块 + 起名，grounding 真实设备清册。 只读、记账。parseDraft 过滤到白名单 type（丢弃臆造）。返回 {name, blocks:[type...], usage} 供 Builder 回填。

当前 embedding 配置状态（不回显密钥）+ available（配置是否完整可构造）。

能耗-负荷回归基线 → JSON。

用电分项分解 → JSON。

能量流向桑基图（总用电→各设备类型）→ JSON。等价 MCP energy_sankey。只读 $0。

能效/ESG 报告（DESIGN.md §10-E）：确定性装配 KPI+能流+节能+碳+未处理报警一份汇总 → JSON。 range 报告周期（默认 thisMonth）；priorRange 给则同比；area 给则附 EUI/碳强度；factor 覆盖排放因子。

Invalid annotation [] [fandoc:2] - ""

实体可用 FIN 图形列表（上下文检查器图形加载用）→ JSON [{id,dis}]。 版本敏感的 finGraphicOn 调用在 FinBridge.entityGraphics 内（原则 4），此处仅薄壳暴露。

设备拓扑（AHU→VAV 上下游）→ JSON {root,parents,children,points}。

报告 LLM 生成「前」的成本估算（确定性、无 LLM）：按 sectionsJson 字符数估输入 token + 固定开销， 输出按预算估；→ 估算 USD。供 UI 在点「AI 解读」前显示 ≈$。

完整准入评测 = 确定性护栏闸门 + LLM 轨迹评测，合并 JSON。admin 限定。

确定性安全回归闸门（DESIGN.md §10-A2 准入闸门的护栏部分）→ JSON。 离线、可重复：对 mock 记录跑护栏决策/类型强制/范围归一三组检验， 对抗项必须 100%、总通过率对照 A2/A3 阈值。模型上岗/自主升级前先过此闸门。

LLM 轨迹评测（准入闸门的模型诊断质量部分）→ JSON。金标准查询回放走真实 AgentLoop，按期望工具命中打分。需 LLM 已配置（否则返回 skipped）。

健康/状态（面板护栏在线 + 当前模型）。

入库一篇手册/规格/控制序列文档（纯文本/Markdown）：分块→嵌入→提交 Folio。admin 限定。 equipType/equipRef 给则打标签供检索预过滤；docRef 为文档标识。 返回 JSON {docRef, chunks, skipped}（未配嵌入端点则 skipped=true）。

抓取网址（仅 http/https）→ HTML 转纯文本 → 分块嵌入入库。admin 限定。 抓取失败/无文本/未配嵌入端点 → 返回 {skipped:true, reason}（前端展示干净提示，不抛栈）。 title 取自 <title> 作 docRef；equipType/equipRef 给则打标签供检索预过滤。

列出激活报警（FDD 召回的诊断线索）→ Grid。

碳资产簿：列分录（可选 entryType）+ 按 entryType 汇总（count/tco2/value）→ JSON。

列全部案例（知识库案例标签）→ JSON。只读。

Invalid annotation [] [fandoc:1] - "（title 由前端 localStorage 缓存补齐，缺失时再懒加载 finMcpLoadChat）。"

列出已保存会话的元数据 → JSON [{id,mod,size}]。不逐个读文件取 title （title 由前端 localStorage 缓存补齐，缺失时再懒加载 finMcpLoadChat）。

列用户自定义计划任务 → JSON。只读。

Invalid annotation [] [fandoc:1] - ""

已入库文档摘要列表（前端文档库用）→ JSON [{docRef, chunks, equipType}]。

列排放因子（Folio finMcpEmissionFactor 覆盖项 + 内置默认表）→ JSON，含 origin 标注。可选按 source 过滤。

列出定时任务（含启用态、每日触发时刻、当日触发情况）→ JSON。

列记忆（默认列全部；可按 scope / status="pending"|"confirmed" 过滤）→ JSON（已剥离向量）。

列当前用户通知（unreadOnly 只列未读）→ JSON（倒序，限 100）。

列待批/历史提案（可选 packageId / status="pending"|"approved"|"rejected"）→ JSON。

Invalid annotation [] [fandoc:1] - ""

列当前用户的自定义报告 → JSON [{id,dis,kind,blocks,defaultRange}]。

列 watch（status 过滤）→ JSON。只读。

列工单（可选 status="open"/"closed" 与 equipRef 过滤）→ JSON 列表。只读。

当前 LLM 配置状态（不回显密钥本身，仅报是否已配置）。

测试当前 LLM 配置可用性：做一次极小一次性调用，返回 {ok, model, error?}。

读取一段已保存会话 → 原始 JSON 字符串。

标记通知已读。

泵/机组性能曲线 HQ（实测运行点 + 二次拟合）→ JSON。等价 MCP pump_curve。只读 $0。

人工直接提议一条记忆（source=human，仍入 pending 待确认）→ JSON。admin 限定。

受控写入提案：强制经 L3 护栏（白名单/物理值域/变更预算/风险分级）。 低风险自动执行+审计；中高风险返回 status==pending_approval 转人工审批。 与 MCP/Copilot 同一裁决路径（tools.invoke），绝非另一套写逻辑。 返回 JSON 字符串（非 Dict）：pending_approval 分支含嵌套 proposal 子对象， 走 JsonOutStream 序列化可靠，避免经 eval/Hayson 端点时嵌套裸 Map 丢失/变形 （否则前端拿到的 proposal 残缺，审批→下发链路断）。对照 finMcpEquipTopology/finMcpRollback。

焓湿图状态点（送/回/混/新风 温度+湿度 → W/h）→ JSON。等价 MCP psychrometric。只读 $0。

语义查询：Haystack 过滤器 → 实体 Grid。等价 MCP query_entities。 例：finMcpQuery("vav and equip", 50)

读一组点位当前值（curVal）→ Grid。

读单点历史趋势 → Dict（含 samples 列表）。range 用 Axon 日期语法。

案例库检索 → JSON 案例列表。

驳回单条提案（不落值，仅置状态）。admin 限定。

多模板报告（DESIGN.md §10-E）：template=energy（能效/ESG）| leed（LEED EA 信用对标）| well（WELL 室内环境达标率）。前端可选模板渲染并导出 PDF（浏览器打印）。

合规对标评估：把确定性指标(sectionsJson)对标 standard 的静态 credit 映射，LLM 逐条判 met/partial/gap + 优先改进建议。standard ∈ gbt-3star|leed-om|well。结构化 JSON 输出(喂 compliance Widget)， 解析失败回退叙述。纯只读、记账。返回 {standard, credits?, suggestions?, score?, narrative?, usage}。

报告 AI 解读：对已算好的确定性报告数据(sectionsJson)做一次性无工具 LLM 调用， grounding 真实站点设备清册（防臆造），产出运维解读。纯只读、不入库、不产生写。 默认便宜模型可由 model 覆盖；记账（recordOneShot）。返回 {text, usage:{inTok,outTok,model,costUsd}}。

设备手册语义检索 → JSON 带引用块列表。复用 ext.tools.invoke("retrieve_docs")（三路共用）。

一键回退到基线 → JSON {status, restored}。admin 限定。

手动立即触发某任务（内置或自定义），返回 sessionId（可经 finMcpChatPoll 回看）。admin 限定。

保存一段会话 JSON 到项目 IO 目录。json 为前端 Conversation 的 JSON 字符串。 经 Context.cur.eval 调 ioWriteStr（请求线程内已绑当前用户）。 非 admin：保存自己的对话记录属普通用户操作（id 经 sanitizeId 防路径穿越，写项目 io 安全）； 删除(finMcpDeleteChat)仍 admin 收口。**写后回读校验**确实落盘后才返回 id—— 写失败/未生效即抛错，前端据此如实反馈"保存失败"而非误报成功。

保存自定义报告（per-user 私有）。blocksJson=区块清单 JSON（区块 type 取自 ReportBuilder.blockMeta 白名单）。 admin 写。返回 {id, dis}。

节能潜力（额定/同比/物理极限）→ JSON。

配置 Agent 会话参数，写入扩展设置记录（运行期即时生效）： maxSessions（活跃会话上限）、ttlMin（会话 TTL 分钟）。 注：池线程数 maxWorkers 在启动期由 env FINCOPILOT_MAX_WORKERS 决定，改后需重启（见 AgentSessionMgr）。

配置 ASR 供应商（OpenAI 兼容 /v1/audio/transcriptions），运行时即时生效。admin 限定。 密钥写 FIN 加密 passwords 存储（独立槽 rec.id+":asr"，不撞 LLM/embed 密钥）； provider/baseUrl/model 进扩展设置记录标签。本地 FunASR/whisper 可不传 key。 例：finMcpSetAsr("openai", null, "http://localhost:8000/v1", "FunASR")

配置 embedding 供应商（OpenAI 兼容 /v1/embeddings），运行时即时生效。admin 限定。 密钥写 FIN 加密 passwords 存储（独立槽 rec.id+":embed"，不撞 LLM 密钥）； provider/baseUrl/model 进扩展设置记录标签。本地 Ollama/vLLM 可不传 key。 例：finMcpSetEmbed("openai", null, "http://localhost:11434/v1", "bge-m3")

写入/覆盖一条排放因子（admin）。source/value 必填；year/region/scope/unit 可选。

启用/停用某定时任务（即时生效）。admin 限定（改变自主行为）。 例：finMcpSetJobEnabled("nightlyEnergy", true)

配置大模型供应商，运行时即时生效（无需重启 / 环境变量）。 密钥写入 FIN 加密 passwords 存储（不落明文 folio）；provider/baseUrl/model 作为标签提交到扩展设置记录。优先级高于环境变量。admin 限定（写操作收口）。 例：finMcpSetLlm("anthropic", "sk-ant-...")

finMcpSetLlm("openai", "<key>", "https://api.deepseek.com/v1", "deepseek-chat")

设 watch 启停（active|paused）。admin 限定。

生成贴合 Agent(能力)+目标设备 的运维问法建议 → JSON 字符串数组。 配 LLM：一次性无工具调用（小 max_tokens，复用 effort 思路），喂设备 grounding + 领域框架； 未配/调用失败/解析空：读设备点位/标签确定性兜底（无 target 返回 []，前端保留静态建议）。 不走 AgentLoop/会话、不产生写——纯只读生成；真正执行仍走带工具/护栏的 AgentLoop。 historyJson 非空时按"对话上下文"生成跟进问法（[{role,content}] 的 JSON）；空则按 Agent+设备生成。

标签词表（前端 # 联想用）→ JSON 字符串数组（B2，DESIGN.md §10-C 配套）。

语音转写：base64 音频 → 中文文字。前端 MediaRecorder 录音→base64→本函数。 format 为容器后缀（webm/mp4/...）；useHotwords=true 则把 HVAC 术语种子 + 当前楼宇 设备/点位名作 prompt 偏置（提升专业词识别）。普通用户可调（只读、不写 Folio）。 未配端点 → {error:"asr_not_configured"}；坏音频/转写失败 → {error,message}（前端干净提示，不抛栈）。

更新自定义任务（部分字段；改 schedule 时校验）。admin 限定。

更新自定义报告（编辑既有定义：dis/blocks/kind/shared/scope）。admin 写。返回 {id}。

更新看板拖拽布局（layoutJson = react-grid-layout {i,x,y,w,h}[]）。admin 写。

当前用户 LLM token 用量与费用 → JSON {user, inTokens, outTokens, totalTokens, costUsd, calls}。