cp .env.example .env

.venv/Scripts/python smoke_test.py

claude mcp add instagram -- "C:\Users\osami\OneDrive\Documents\GitHub\ayham project 2\instagram-mcp\.venv\Scripts\instagram-mcp.exe"

INSTAGRAM_ALLOW_WRITES=true

.venv/Scripts/python -c "import asyncio,json;from instagram_mcp.server import server;print(asyncio.run(server.call_tool('instagram_build_style_profile',{})).content[0].text[:400])"

|GXP6|

真正让座起效的是 `instagram_similar_accounts`，它读取 Instagram 自己的"推荐给你"图，该图模型化了协作率关系。一旦你找到*一个*好匹配，从它向外展开的效果胜过任何关键词搜索——这就是为什么文本和话题标签探测主要存在的目标就是为了找到那第一踩点。

另一件值得一提的地点是关于地点的。Instagram 的`city`字段几乎永远是缺失值，偶尔还会是错误值——一次实际探测返回了一个叫"Hollanda"的地点，而坐标却放在埃及的亚历山大。地点*名字*碎片化严重，同一个城市会返回"Amsterdam, Netherlands"、"Amsterdam Canal District"、"Red Light District, Amsterdam"以及"Amsterdam Canal River"四种说法。坐标总是存在的，所以 iper 定位按位置聚类而不是按名字聚类：多个变体会自动合并，而错贴名的条目会孤立出来。

原本设计时依赖的某种做法最后发现并不存在。Instagram 为照片生成 alt 文本（"maybe be a image of one person, blonde hair, standing"），作为每篇帖子的免费粗粒度视觉信号——但它只向 Web 客户端暴露，且 32 篇帖子的实际探测中全部返回为空。因此外表属性真的需要真实查看图片，上限也如实反映这类需求，而不至于假充其量。

一次搜索是磁盘上的一个任务，而不是一个函数调用：真实的一次需要对一个将被 Instagram 限流速的账号做几百次 API 请求，耗时十到二分钟，所以它逐阶段运行，能承受崩溃，并且让你在二十次调用之后修正一个错误的探测方案，而不是进行到三百次再修正。

GXP7

### 看图评判断层

外观是唯一没有免费信号可以到达的属性，所以必须用眼睛看。`instagram_search_shortlist(image_download=true)` 会获取每个候选人的头像和近景缩略图，然后拼合成**一张带编号的联系卡**，而不是交给一堆散文件。

这不仅仅是整洁问题。它花掉十二分之一的注意力，编号让评价可以引用所来源的卡片，也让一个最棘手的问题变得可答：*这些脸上哪一张是账号持有者？* 信息流里满是朋友、伴侣与客户，如果你基于错误的正确的那张作出判断，得到的自信程度和正确判断一样高。把全部图片并列放置，这个问题就变成可以直视的：找出反复出现的脸，对照写有 `avatar` 的 tile——那是唯一确定是本人——然后将结果记为 `owner_face_confidence`。那里的低值会降低所有视觉读数的置信度，而不是假装人员赱得更差。

一个档案页的截图会展示大致相同的资料，但那个页面需要用登录状态的浏览器才能渲染，而这些缩略图都已经抓取并付出代价完成了。

### 解读置信度

每个属性上都携带两个数字而不是一个：**匹配度**表示证据与匹配度结论符合有多好，**确定性**表示证据来源多能信到。一个模型只报“85%”，是悄悄把两者相乘并丢掉了哪一方弱。

确定性在每个属性和每个来源上都是封顶的，系统不能夸大其辞。从一张头像读出的头发颜色封顶 0.45；从多张白天的图片读出则 0.80。Instagram 自己的“账号所在”发源国字段最高 0.95。**身高封顶是 0.15**——一张静态的图片没有尺度参照——且 `height`、`ethnicity` 和 `build` 都是参考性的：会被报告，但绝不用于调整排名，如果你把它们标为必填则直接排除。

未观测不等于“无”。一个任何人都无法观察的属性降低的是 **coverage（覆盖度）**，而不是匹配度，排名会根据验证了多小比例而向先验收缩——所以这个差距 [0.9，两个属性观测] 不如 [0.75，六个观测]。任何被标为 `unverified` 的内容得分高于能行动的程度。

结果只适用于公开账号。私有账号因为无法验证而在入口处被丢弃。永远不会返回十八岁以下的人：年龄从声明出生年份和 Instagram 加入日期中读出的，用这两个估值的*较低端*决定，检查在年龄可读时和每次发生出口时都运行——一个审计发现原始的仅在出口处执行检查的版本无法保护任何东西，因为入口在年龄被读取之前就已经运行。每个候选者都保持完整 provenance，包括发现它的探针以及每个结论依据是什么。搜索任务存放在 `searches/` 并已在 `.gitignore`：它们包含其他人的资料与图片。

## 保持不被封号

instagrapi 驱动的是手机端 App 使用的私有 API。Instagram 会检测并阻止自动行为，而它阻止的账号是你自己的——所以：

- **会话会被缓存**在 `session.json` 中并复用。反复从头登录
  是触发风控最快的方式。请保留这个文件。
- **请求会被随机间隔**，使用 `INSTAGRAM_DELAY_MIN`–`INSTAGRAM_DELAY_MAX`
  秒的随机暂停。如果 Instagram 开始要求你等待，就调高这个值。
- **收到警告就退避。** “请等待几秒钟”和“操作被阻止”
  意味着停止，而不是重试。工具的错误信息里也已说明这一点。
- **批量读取有风险。** 一次性拉取上千个关注者，
  看起来根本不像是真人或真实用户在使用。
- **如果只是实验，请使用一次性账号或小号。

## 布局

| 文件 | 内容 |
| --- | --- |
| `instagram_mcp/server.py` | 49 个工具定义 |
| `instagram_mcp/persona.py` | persona 是什么，以及置信度计算 |
| `instagram_mcp/signals.py` | 离线、免费地从个人资料中判断 persona |
| `instagram_mcp/names.py` | 将名字映射到性别先验，离线 |
| `instagram_mcp/discovery.py` | 候选人的召回渠道来自哪里 |
| `instagram_mcp/search.py` | 将 persona 搜索作为可恢复任务保存在磁盘上 |
| `instagram_mcp/sheets.py` | 将候选图片组合成一张可评分的表格 |
| `instagram_mcp/client.py` | 登录、会话持久化、写入保护、并发线程 |
| `instagram_mcp/serialize.py` | instagrapi 模型的紧凑 JSON 视图 |
| `instagram_mcp/errors.py` | 将 Instagram 异常转换为可操作的建议 |
| `smoke_test.py` | 离线检查：schema、守卫、序列化器 |

`.env` 和 `session.json` 中保存凭据和有效登录 Cookie，`searches/`
保存他人的资料和照片。这三个都被 gitignore 忽略——请继续保持这样。