校园导航 POI 功能化标注 (Campus Navigation POI Functional Annotation)

校园导航 Agent（Location-based AI Agent） 的 POI 数据层设计方法论。项目位于 D:\1\CS&AI\05-School-Projects\校园导航\AI 校园导航 MCP 版，目标是把百度地图 POI + 人工标注落成 LLM Agent 可用的结构化数据。

核心教训：散文 description 对 LLM 是噪音

初版给每栋楼生成"位于 X，距校园中心约 N 米"的散文描述，喂给模型后几乎无增益：

• 位置模型本来就有坐标字段，散文重复坐标无信息量
• 模型拿不到答案时会编造（旧版答警务亭职能时凭空列出 6 项服务；答取件码 200 时随便指定一个驿站）
• 导航真正需要的是"这个 POI 能干什么 + 怎么辨别你要找的那个"，而不是"在哪"

标注 Schema

每个 POI 增加结构化字段（取代散文 description）：

{
  "uid": "20a830fdbd6e101a72455be8",
  "name": "宿舍楼27号(文轩楼)",
  "category": "宿舍楼",
  "building_no": "27#",
  "aliases": ["27号楼", "27号宿舍楼", "文轩楼", "宿舍27栋"],
  "func_note": "学生宿舍楼（文轩楼/27号楼）。",
  "same_as": ""          // 被合并实体的目标 uid（移入 merged 数组）
}

房号规则（喂给模型，写进 prompts.py）

<楼号>#<房间号> = <楼号>楼 <房间号> 房间
- 27#201 = 27号宿舍楼（文轩楼）201 房间
- 1#1103 = 一号教学楼 1103 房间
- 53-1#205 = 53号楼A栋 205 房间

用户说"27号楼"直接命中该楼；给 27#201 则解析出楼栋+房间号。楼号复用（如 12# 既有教学楼又有宿舍）时靠分类+语境，拿不准用 ask_user。

数据流（Agent 接入链路）

campus_dataset_annotated.json  (标注数据源，人工+脚本生成)
   └─ poi_data.py              (加载真实数据，接口签名保持兼容)
        ├─ list_categories()   → 10 个真实分类
        ├─ list_pois(cat)      → 渐进式披露（id/name/楼号/别名）
        ├─ get_poi(uid)        → 完整信息（含 func_note）
        └─ search_pois(kws)    → name+aliases+building_no+func_note 多词"或"检索
             └─ tools.py       (7 个 MCP 风格工具，schema 描述同步)
                  └─ agent_core.py  (DeepSeek function calling 循环)

接入要点：

• poi_data.py 接口签名保持不变（tools.py 依赖 list_categories/list_pois/get_poi/search_pois/CAMPUS_CENTER），只换数据源
• 前端是通用渲染（用 category_id/name 动态展示），数据接入后前端零改动；导航卡坐标靠 show_poi_navigation_options 后端补全
• search_poi 检索范围扩展到 aliases——"文献信息中心"能命中"浙江万里学院-图书馆"

楼号冲突处理规则

百度 POI 数据库会重复/错标楼号，人工裁决规则：

1. 通用规则：名字含 寝室楼/学生宿舍/学生公寓/宿舍楼/宿舍/公寓 → 宿舍楼；裸"X号楼" → 教学楼
2. #53：教学楼 AB 栋 → 53-1# / 53-2#（坐标可能后续人工重标 BD09）
3. #12：教学楼 12 + 宿舍 12 是两栋，都保留
4. #27：两条重复 → 选带文轩楼的，主坐标取文轩楼
5. 空中走廊不是楼 → 单独"校内楼栋/连廊"类

人工标注的价值（导航的真正作用）

人工写 func_note 解决模型猜不出来的事。最有价值的是菜鸟驿站取件码分派规则：

取件码分派：
  1-100 开头   → 二楼新菜鸟驿站（顺丰标识店）
  100+ 开头    → 古茗奶茶店旁
  400+ 大件    → 古茗奶茶店旁（露天）
  200+ 开头    → 一楼中国移动旁菜鸟驿站

Agent 端到端验证：问"取件码200开头去哪取" → 模型命中驿站并精确回答"一楼中国移动旁"。这在旧版会编造。

楼号权威清单（用户老地图，2026-08-12）

老师提供的老地图楼号映射为权威依据，存放于项目 kb_grill/authoritative_buildings.py：

1#教学楼 | 2#空中花园 | 3#教学楼 | 4#大数据+智能学院 | 5#大数据实验楼
6#生环实验室 | 7#法学院 | 8#继续教育学院 | 9#外语学院 | 10#智能实验楼
11#学术报告厅 | 36#行政楼 | 37#体育馆 | 38#文献信息中心/图书馆报告厅
51#C重描中心/创业园 | 51#A中德学院(国际学院) | 52#A设艺建 | 52#B文传
53#教学楼 | 62#商学院+物流 | 63#水上图书馆 | 64#生环

决策记录：

• 楼号归属以用户老地图为权威，不盲信知识库。8#=继续教育学院、9#=外语学院（AI 百事通知识库给出的是相反的，经交叉验证知识库文档用"博雅楼(15)"式中文命名，无"8号楼"字样，房间号 8103/9103 是模型推断；老地图实地标注更可信）
• 待补坐标楼：1# 6# 7# 10# 37# 38# 51#C 51#A 52#A 52#B 53#（百度/APP POI 均无，见 kb_grill/placeholder_buildings.json）
• 纯房间号对导航无信息量，剔除 room 字段，offices 只保留 department / office(学工办·教务办·院务办) / telephone

服务点职能从学校 AI 知识库获取

警务亭/思政驿站等职能可用学校 AI 接口（D:\1\CS&AI\05-School-Projects\aihw-conversation-api，POST /api/AIAgent/conversation/streaming，knowledge:true）查询。知识库没直接收录时不照单全收模型补充的常识——只采信知识库明确给出的（如保卫处电话），其余保留低风险项或标待确认。

部门办公室挖掘（AI 百事通 grilling）

用 grill_kb_departments.py（knowledge:true 多轮提问）从学校 AI 知识库挖出"部门→楼→办公室→电话"：

• 5 轮共 7423 字，结果存 kb_grill/kb_dept_probe.json
• 二级学院楼号归属：62#商学院+物流+华美、4#大数据+信息智能、8#继教、9#外语、52#文传+设艺建、64#生环、51A#中德+国际
• 行政楼（36#）含校办/人事/财务/科研/研究生院等 13 部门；小白楼=建设部+保卫处；一站式大厅=学工部+团委
• 交叉验证教训：对话式 RAG 回答偶有格式错位/楼号推断，需用多轮关键词组合检索（kb_grill/kb_89_verify.json）验证楼号映射，最终以老地图为权威

踩坑记录 (Pitfalls)

• starlette/fastapi 版本冲突：fastapi 0.115.6 需要 starlette<0.42，装到 1.6.0 会 Router.__init__() got an unexpected keyword argument 'on_startup'。修复：pip install starlette==0.41.3（经 7890/7897 代理）。sse-starlette 有依赖冲突但当前代码自定义 SSE 生成器，不阻塞
• DeepSeek 402 Insufficient Balance：余额不足时 agent 工具循环跑不了，需先充值
• 编辑工具把直引号转全角引号：改 Python 代码后要 python -c "import ast; ast.parse(open(f).read())" 检查语法

钱湖校区楼栋知识库交叉核实（grilling 还原原文）

用户要求 AI 百事通 grilling 必须逐字还原知识库原文（不概括、不加表格/表情），并标注钱湖/回龙校区；冲突时采信时间更近的文档。已交叉核实结果存项目 kb_grill/grill_findings.json：

方法论沉淀：

• 百度 POI 分类系统性错误：大量宿舍楼被百度标成"教学楼"。知识库权威教学楼编号仅 1/3/4/5/6/7/8/9/10/51A/52A/52B/53/62/64；15/17/18/13/23/25/21/22/24/28/39/40/43/54/61/12 实为宿舍楼
• 51-71# 是复合楼宇（兼教学+公寓），desc 需并列多用途
• 知识库用中文楼名（"行政楼""学术报告厅"），不用编号——"2号楼""11号楼"编号查不到，要用名称检索
• 同一楼可有多重身份（63#=档案馆+水意楼宿舍；51#=中德教学楼+教务招办），description 需并列多用途
• 钱湖图书馆（文献信息中心）实际在1号楼附近（万里大道北侧，靠近景观湖），开放 7:30-22:00；38# 是否=中心馆待核实
• 书库在碳中和研究院B幢（里家宾馆东边，小白楼南侧）
• 内网依赖 EasyConnect，断线会 getaddrinfo failed，非 token 问题 —— 2026-09-15 更正：该接口公网直达，不需要 EasyConnect。 aihw.zwu.edu.cn 有公网 A 记录 61.153.150.54，任意网络持 token 均可调用。当时那次 getaddrinfo failed 是校园 DNS（10.131.64.132）临时解析失败（数分钟，自行恢复），与服务可达性、token 均无关。排查顺序应为先 Resolve-DnsName，再怀疑接口 / token / 网络。详见 内网服务连不上先查 DNS (Check DNS First When an Intranet Service Drops)

2026-08-12 楼栋确认全表（grilling 还原原文，28 栋）

全部证据存项目 kb_grill/grill_findings.json，落库脚本 build_apply_grill.py（findings 的 uid/bno/name 三级匹配）。

长期 grill：校园服务/校门/食堂（2026-08-12）

已新增 POI（无坐标占位，desc_source=grill）：万家钱湖（一食堂）/万家万里（三食堂）/钱湖教工/万家味道/里家餐厅 5 家食堂（带营业时间），医务室（体艺中心一楼）、体育公园（西校门、篮球/网球/足球/跑道）、健身房（体艺东侧，周一至五17-21、周末15-21，限50人出一进一）。

校门功能性描述（更新百度散文 desc）：

• 东校门（主校门）：东南角，正对钱湖南路8号；地铁5号线钱湖南路站C口直达，23条公交
• 西校门：西南侧，近体育公园和万家钱湖餐厅；南门：南侧，通商业广场/万里驾校
• 体育公园在西校门、钱湖餐厅旁；体艺中心紧邻素拓中心正对樱花大道，东侧体教中心+健身房

规则/流程类信息（grill 并入 POI desc）：

• 图书馆（38#）：借阅 30本/90天/无限续借/取消超期费；借还书一楼服务台+自助机；座位预约需签到（未签到 7天3次拉黑7天）；开放 7:30-22:00；服务电话 88222051/88222044/88222050
• 一站式大厅：补卡 9号窗口人工（工本费13元）+自助；失物招领
• 办事流程：成绩单/在读证明自助打印在 51号楼A座一楼东首；补卡在一站式或58号楼商业广场自助机；报修走"万里小勤勤"
• 校园交通：车辆通行手续 36#行政楼115/117；电动车限制新增、新生禁止（2026-07）；无校车信息

裁决记录：

• 38# = 图书馆（用户权威）：文献信息中心是图书馆办公区，同一栋楼。图书馆 POI 已挂 building_no=38#，别名含 38号楼/文献信息中心/图书馆报告厅，desc 含开放时间（周一至周日 7:30-22:00，7:30-8:00 暂不借还书）。知识库"图书馆在1号楼附近"表述不同，以用户为准
• 行政楼部门：知识库仅可采信计划财务处（121室10号窗口），其余12部门无房间号原文（之前"13部门"是模型概括）

相关

• MCP (Model Context Protocol)
• AI 应用开发路线图 (AI Application Development Roadmap)

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/AI apps