系统地图¶
这是零售分析应用的交互式地图，由类型化 JSON 源生成，并渲染为单个自包含 HTML 文件，无需外部资源或构建步骤。
两条学习路径在行为上完全一致，因此一张地图即可涵盖二者；技术栈存在差异时，节点会同时显示两种名称（ASP.NET Core · FastAPI）。
显示空间有限？ 全屏打开地图 ↗
引导视图¶
该地图提供三个精选视图。每个链接都会打开地图，并聚焦于一个场景：
| 视图 | 展示内容 |
|---|---|
| 聊天请求路径 | 一个提示词从浏览器发送至模型，再以流式词元返回 |
| 模型如何读取数据 | 通过只读 MCP 工具访问 SQLite 的路径 |
| REST 与持久化 | 应用程序自身的读写路径 |
访问同一数据库的两条路径¶
这里值得重点关注的是，访问 retail.db 时使用了两种不同方式，并有意赋予不同权限：
- 应用程序 通过
RetailAnalyticsService进行读写：.NET 使用 EF Core，Python 使用 SQLModel。 - 模型 从不直接访问 SQLite。它调用
retail-analyticsMCP 服务器上的五个只读工具；该服务器使用mode=ro打开 SQLite。写入操作会被驱动程序拒绝，因此即使提示词注入指令要求修改数据，也无法成功执行。
工具接口即安全边界：模型获得的是
get_customer_summary，而不是 run_query，因此不存在需要防范的任意 SQL 逃逸通道。
使用查看器¶
| 操作 | 控制方式 |
|---|---|
| 打开图表指南 | ? |
| 查找并聚焦节点 | / |
| 追踪两个节点之间的路径 | R 或 PATH |
| 比较组件角色 | L 或 LENS |
| 总览雷达 | M 或 MAP |
| 播放引导故事 | P |
浅色与深色主题、平移/缩放以及 PNG/SVG 导出功能均位于右上角菜单中。
重新生成地图¶
类型化源文件为
agent-hq-demo.architecture.json — 请编辑该文件，而不是作为生成输出的 HTML。安装生成器 CLI 后（请参阅 “致谢”）：
node bin/archify.mjs validate architecture \
docs/system-map/agent-hq-demo.architecture.json --quality showcase --json
node bin/archify.mjs deliver architecture \
docs/system-map/agent-hq-demo.architecture.json \
docs/system-map/map.html --quality showcase --json
deliver 仅在所有检查均通过时才会替换 map.html，因此有问题的编辑不会覆盖上一份可用地图。
相关内容¶
- 架构参考 — 文字导览、请求序列和数据模型
- .NET 实验 06 — MCP · Python 实验 06 — MCP
- 挂钩与治理 — 最小权限实践的另一半
致谢¶
地图使用 Archify 生成，采用 MIT 许可证。
map.html 嵌入了其查看器运行时。