# 卡点产业地图 · 给 Agent / 脚本

匿名只读静态资源。先读索引，再按需拉 JSON；不要爬 HTML 解析表格。

## 入口（相对站点根）

| 用途 | 路径 |
|---|---|
| 机读目录（先读这个） | `/maps/data/index.json` |
| 字段说明 | `/maps/data/schema.json` |
| 产业环节表 | `/maps/data/industries.json` |
| 重点公司 | `/maps/data/companies.json` |
| 事件样例 v0 | `/maps/data/events.json` |
| 事件↔精选对齐（派生） | `/maps/data/event-xref.json` |
| 元信息 | `/maps/data/meta.json` |
| 现成 Markdown 问答（不接 MCP 时用） | `/api/v1/agent/industry-map`（目录）；`?industry=<id/中文名/主站分类>` 看环节卡点+盯梢公司+近期事件；`?q=<公司/代码/环节>` 跨图检索；`event_limit` 1–20。与 MCP `asharehot_get_industry_map` 同源 |
| 人读总览 | `/maps`（单产业 `/maps/{industry_id}`，事件 `/maps/events`，公司 `/maps/companies#代码`） |

## 和主站精选怎么配合

- 地图是**供应链卡点研究笔记**（白毛魔女轴：集中度 / 扩产周期 / 认证 / 涨价 / 设计锁定），**不是**实时精选流。
- 实时增量：`/api/v1/agent/latest` 或 `/api/v1/selected/snapshot`；搜索：`/api/v1/agent/search?q=`。
- `index.json` 里的 `site_crosswalk.industry_to_category` 把产业 id 映到主站 `/?category=`；公司可用 `/all?q=公司名`。
- `events.json` 仅为样例，**不要**当今日新闻。
- `event-xref.json`：按来源 URL 精确对齐事件与主站精选库；`status`=in_selected / in_feed_not_selected / not_in_feed / no_source_url，`articles[].item_path` 可直接拼站点根打开精选稿、`article_id` 可对 `/api/v1` 取详情。无 URL 的圈内笔记不做模糊匹配。

## 从精选条目反查地图

`/api/v1/items` 的条目若被地图卡点事件引为来源（按来源 URL 经 `event-xref.json` 精确对齐，不推断），会带可选字段 `mapRefs`：`[{eventId, eventHref, publishedAt, segments:[{industryId, name, href}]}]`；没挂就不出现该字段。拿到后可直接用 `eventHref`/`segments[].href` 引导到人读页，或用 eventId 在 `events.json` 取 conflict_note 与 sources。

MCP 工具 `asharehot_get_latest` / `asharehot_search` 同样复用这份对齐：structured `items[]` 带同结构的可选 `mapRefs`，文本答案末尾另有「其中 N 条已被产业地图卡点事件引为来源」一节（标题、最多 3 个环节、`/maps/events` 锚点）。走 MCP 的 Agent 不必再单独拉 `event-xref.json`。

增量同步 `/api/v1/selected/snapshot` 与 `/api/v1/selected/changes`（`fields=default` 时）的条目同样带可选 `mapRefs`；`fields=minimal` 不带。`mapRefs` 在条目内，地图事件新挂上来源时 snapshot 的 ETag 会随之变化；changes 只在条目本身有增删改时才出现，单纯新挂地图不会产生一条 change，需要全量对齐时重拉 snapshot。

## 版本与新鲜度

- `schema_version`（`index.json`、`schema.json` 同值，现为 1）：只在**破坏性变更**时 +1，即删除或改名字段、改字段含义或类型、改稳定键格式。新增可选字段、新增数据集、增删条目不 bump。读到比你预期大的版本号，先重读 `schema.json` 再解析。
- `meta.updated` / `index.updated`：地图数据最近一次实质更新的日期（取事件 `published_at` 与 `sources[].date` 最晚值，只前进不后退，由 `scripts/recount-maps.py --write` 维护）。离今天远就提醒对方地图可能不新，实时信息改查精选接口。
- `events[].conflict_note` 非空：圈内口径与一手原文（公告/财报）有出入或未被证实。引用该事件时要一并说出，不要只报圈内数字。`sources[].url` 为空的是圈内笔记，无一手出处。

## 回答习惯

- 用中文，先结论；引用产业用 `id` + 中文名，公司带 6 位代码。
- 事件挂地图：用 `events[].segment_refs`（`industry_id` + 规范环节名），不要用自由文本 `segments` 去匹配。环节锚点 `/maps/{industry_id}#seg-{industry_id}-{encodeURIComponent(环节名)}`，地图环节行反向列出挂该环节的事件。
- 稳定键：`industries[].id`、`companies[].code`、`events[].id`。缺数据就说缺，不要用训练记忆补产业链百科。
- 仅供研究，不构成投资建议。