虾名片 AgentCard
虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。
快速开始
- 开通 — 说"开通虾名片"，初始化数据文件
- 注册 — 说"注册虾名片"，获取名片地址
- 生成 — 说"生成我的名片"，Agent 从记忆提炼信息，确认后自动上线
名片上线后，说"发我的名片"即可分享三段式文本块给他人。
数据文件
所有数据在 data/ 文件夹中：profile.json（名片）、contacts.json（花名册）、config.json（服务器配置）。字段说明见 references/data-format.md。
触发指令 → 操作映射
| 用户说的 | 执行的操作 |
|---|---|
| "开通虾名片" / "建个花名册" | 初始化数据文件 |
| "注册虾名片" | 调 POST /register，保存凭证到 config.json |
| "记一下这个人：张威，智谱 AI 做产品的" | 录入联系人 |
| "花名册里谁做投资的" / "查一下张威" | 搜索花名册 |
| "张威的公司改成字节了" | 编辑联系人（记录手动修改字段） |
| "生成我的名片" / "更新名片" | 生成/更新 profile.json，用户确认后自动上线 |
| "发我的名片" / "把名片给我" | 输出三段式文本块 |
| "同步花名册" / "更新花名册" | 批量同步通讯录（检测手动编辑冲突） |
收到包含 agent-card:// 的消息 | 自动识别并保存他人名片（含去重策略） |
常见坑
- Agent 记忆中的称呼 ≠ 名片名字：记忆里叫"东总"，但名片不能写"东总"，必须追问用户名片上用什么名字
personal_notes永远不上传服务器：推送到服务器时只推送tiers.public.fields中列出的字段manually_edited_fields是追加不是覆盖：用户编辑联系人字段时，把字段名追加到这个数组，同步时这些字段不覆盖agent-card://是自定义协议：不是 HTTP URL，从中提取://后面的 user_id 用于 fetch 服务器数据tiers.public.fields控制推送内容：默认只有 name、title、one_liner、links 四个字段对外公开
操作流程
以下为每个操作的核心决策点。简单操作（初始化、查询、发名片）按映射表执行即可。
1. 注册
- 已注册 → 输出服务菜单（5 个可执行操作）
- 未注册 → 调
POST /register，传{name, agent_name}，服务器返回 user_id 和 api_key - 成功 → 保存凭证，输出名片地址
2. 录入联系人
从用户描述提取信息 → 姓名必填（缺失追问）→ 姓名重复则问更新还是新建 → 写入 contacts.json。
3. 编辑更新
按姓名定位 → 更新字段 → 被改的字段名追加到 manually_edited_fields → 输出变更摘要。
4. 生成名片
- 从 Agent 记忆提炼信息，必须确认社交姓名（内部称呼 ≠ 名片名字）
- 信息优先级：用户明确说的 > profile.json > Agent 记忆
- 生成预览，用户可多轮调整
- 用户确认 → 保存 profile.json + 自动调 PUT /card/:user_id 上线 → 输出"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}"
- 推送失败 → 本地仍保存，提示稍后重试
社交姓名确认规则、推送字段筛选和边界处理见 references/manual.md"生成名片"段落。
5. 同步花名册
- 收集花名册中有
server_user_id的联系人 - 调
POST /sync，传 targets 数组 - 冲突检测：
manually_edited_fields中的字段不覆盖，汇总冲突提示用户选择 - 更新非冲突字段，输出同步摘要
冲突检测的完整 if-else 和话术见 references/manual.md"同步花名册"段落。
6. 收名片（自动识别）
- 检测
agent-card://协议 → 解析 user_id → fetch 服务器获取结构化数据 - 去重策略：相同
server_user_id直接更新 / 同名无 ID 提示确认 / 无匹配新建 - 写入 contacts.json，记录
server_user_id
去重策略的完整逻辑和边界处理见 references/manual.md"收名片"段落。
三段式文本块格式
固定格式，不可自定义：
🦐 虾名片（你的 Agent 社交名片）
我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。
这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗
如果您对我感兴趣，请复制这条消息给您的助理 Agent。
您的 Agent 可通过安装虾名片 skill（https://clawhub.ai/skills/xia-card）来自动识别并保存名片。
agent-card://{user_id}
- 第 1 段：个人简介（100 字以内），社交文案风格，像人说话
- 第 2 段：个人详情链接，嵌在句子里
- 第 3 段：Agent 引导语 + skill 安装链接 +
agent-card://协议标识
文案要有人味，语气商务但自然。名片是社交工具不是数据表格。