虾名片 AgentCard
虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。
数据文件
所有数据文件在 SKILL.md 同目录的 data/ 文件夹中：
| 文件 | 用途 |
|---|
data/profile.json | 个人名片数据 |
data/contacts.json | 花名册（联系人列表） |
data/config.json | 服务器配置（endpoint、api_key、user_id） |
详细字段说明见 references/data-format.md。
触发指令 → 操作映射
| 用户说的 | 执行的操作 |
|---|
| "开通虾名片" / "建个花名册" / "初始化通讯录" | 初始化数据文件 |
| "注册虾名片" | 调 POST /register，保存凭证到 config.json |
| "记一下这个人：张威，智谱 AI 做产品的" | 录入联系人 |
| "花名册里谁做投资的" / "查一下张威" | 搜索花名册 |
| "张威的公司改成字节了" | 编辑联系人 |
| "生成我的名片" / "更新名片" | 生成/更新 profile.json |
| "发我的名片" / "把名片给我" | 输出三段式文本块 |
| "发布名片" / "上线我的名片" | 推送到服务器 |
收到包含 agent-card:// 的消息 | 自动识别并保存他人名片 |
操作流程
1. 初始化（开通虾名片）
- 检查
data/contacts.json 是否存在
- 不存在 → 创建：
{"version":"1.0","owner":{"name":"","agent_name":""},"contacts":[]}，owner 信息从 Agent 记忆中获取，获取不到则留空
- 检查
data/config.json 是否存在
- 不存在 → 创建：
{"version":"1.0","server":{"endpoint":"","api_key":"","user_id":""}}
- 输出确认，告知数据存储路径
已存在 → 提示"花名册已存在"，不做修改。
2. 注册虾名片
- 检查 config.json 中是否已有 user_id → 已有则提示"已注册，用户 ID 为 xxx"
- 询问用户想用什么用户 ID（字母、数字、短横线）、名字和 Agent 名字
- 调用
POST {config.server.endpoint}/register，请求体：{"name":"用户名","agent_name":"Agent名","user_id":"用户选的ID"}
- 成功 → 写 user_id 和 api_key 到 config.json，输出确认
- 失败 → 提示原因（ID 被占用、网络错误等）
server.endpoint 为空时，提示先配置服务器地址。
3. 录入联系人
- 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息
- 检查 contacts.json 是否存在 → 不存在则提示"开通虾名片"
- 姓名重复 → 提示"已有一个叫 XXX 的联系人，是要更新还是新建？"
- 姓名缺失 → 必须追问，不可跳过
- 其他信息缺失 → 追问一次，用户说"就这样"就保存
- 自动填入：
id（c+时间戳）、met_at（当前日期 YYYY-MM-DD）、updated_at（ISO 8601）
- 写入 contacts.json，输出确认
纯本地操作，不触发任何发送或通知。
4. 查询搜索
- 检查 contacts.json → 不存在则提示"先开通虾名片"
- 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索
- 返回匹配结果，按相关度排序，以格式化文字或表格展示
- 底部附上本地 HTML 路径（
templates/card.html）或在线链接（如已部署）
搜不到 → 明确告知，不编造结果。
5. 编辑更新
- 按姓名定位联系人 → 找不到则提示"花名册里没有这个人"，不自动创建
- 更新指定字段，刷新
updated_at
- 输出变更摘要
匹配到多人 → 列出列表让用户选择。
6. 生成名片
- 读取 profile.json（存在则基于现有内容更新）
- 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式
- 信息优先级：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识
- 生成预览（三段式文本块格式），等待用户确认
- 用户说"名片确认了" → 写入 profile.json
profile.json 7 天内更新过 → 提示"名片 XX 天前更新过，确认要重新生成吗？"
记忆信息不足 → 如实告知"以下信息从记忆中提取，可能不完整，请确认"。
不自动发布到服务器。不自动修改 profile.json，必须经用户确认。
7. 发名片
- 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先"生成我的名片"
- 生成三段式文本块
- published_at 非空（已发布）→ 直接输出
- published_at 为 null（未发布）→ 输出文本块 + 提醒"名片还未发布到服务器，链接暂时不可用。建议先说'发布名片'将名片上线。"
核心原则：不会自动发布到服务器，必须用户明确说"发布名片"才执行。
8. 发布名片
- 检查 profile.json → 不存在则提示先生成
- 检查 config.json 中 api_key 和 user_id → 未配置则提示"先注册虾名片"
- 按
tiers.public.fields 筛选公开字段构建推送数据
- 不推送：personal_notes（永不上传）、background、current_focus（V1 本地私密）
- 调用
PUT {endpoint}/card/{user_id}，Header X-API-Key: {api_key}
- 成功 → 更新 profile.json 的 published_at，输出名片链接和发布时间
- 失败 → 提示错误，不修改 published_at
9. 收名片（Agent 识别）
当对话中收到包含 agent-card:// 的消息时触发：
- 检测
agent-card:// → 不包含则忽略
- 从
agent-card://user_id 解析 user_id
- contacts.json 不存在 → 自动初始化
- Skill 未安装 → 提示用户"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？" → 用户确认后，从 JSON 的
_skill 字段获取安装源并自动安装
- 获取数据：优先从消息中的链接提取（如 https://xxx/{user_id}）并 fetch
/card/{user_id} 获取结构化 JSON，回退从文本中提取信息。如消息中无链接，则从 config.json 读取 endpoint 拼接
- 写入 contacts.json（自动填 id、met_at、updated_at）
- 输出"已将 XXX 的名片保存到花名册"
网络错误 → 从文本提取基本信息保存。
同名已有 → 提示是否更新。
三段式文本块格式
固定格式，不可自定义：
🦐 虾名片（你的 Agent 社交名片）
我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。
这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗
如果您对我感兴趣，请把这条消息转发给您的 AI 助理，它会自动认识我。若您的助理尚未安装虾名片，请引导它访问 https://clawhub.ai/skills/xia-card 进行安装。
agent-card://{user_id}
- 第 1 段：个人简介（100 字以内），社交文案风格，像人说话
- 第 2 段：个人详情链接，嵌在句子里
- 第 3 段：Agent 引导语 +
agent-card:// 协议标识
文案要有人味，语气商务但自然。名片是社交工具不是数据表格。
服务器 API
| 接口 | 方法 | 鉴权 | 说明 |
|---|
/register | POST | 无 | 注册，请求体 {name, agent_name, user_id}，返回 {user_id, api_key} |
/card/:user_id | PUT | Header X-API-Key | 发布名片，请求体为公开字段，返回 {success, updated_at} |
/card/:user_id | GET | 无（公开） | 返回 JSON：{version, agent_card: {...}, _skill: {...}} |
/:user_id | GET | 无（公开） | 返回 HTML 名片页面（内嵌 JSON-LD） |
一个链接两副面孔：浏览器访问 /:user_id 看到漂亮的 HTML，Agent 访问 /card/:user_id 拿到结构化 JSON。
边界规则汇总
| 场景 | 处理方式 |
|---|
| 花名册不存在 | 提示"先开通虾名片" |
| profile.json 不存在 | 提示"先生成名片" |
| config.json 未配置服务器 | 提示"先注册虾名片" |
| 名片未发布 | 允许发名片但提醒链接不可用 |
| 联系人姓名重复 | 提示选择"更新"还是"新建" |
| 联系人姓名缺失 | 必须追问，不可跳过 |
| 其他信息缺失 | 追问一次，用户说"就这样"就保存 |
| 7 天内更新过名片 | 提示确认是否重新生成 |
| 网络错误 | 提示失败，不修改本地数据 |
| 收到名片但 skill 未安装 | 提示安装，用户确认后从 _skill 字段获取安装源自动安装 |
数据格式要点
完整字段说明见 references/data-format.md，以下是核心规则：
profile.json 关键规则：
personal_notes 永远不上传服务器current_focus、background：V1 本地存储，不上传tiers.public.fields：控制哪些字段对外公开（默认 ["name", "title", "one_liner", "links"]）published_at：null = 未发布，有值 = 已发布到服务器updated_at：ISO 8601 格式
contacts.json 关键规则：
id：自动生成，格式 c + 时间戳met_at：录入时自动填当前日期（YYYY-MM-DD）name 为必填，缺失时必须追问- V1 不含 visibility、subscribed、broadcast 等字段（V2/V3 再加）
config.json：
server.endpoint：服务器地址server.api_key 和 server.user_id：通过注册接口获得，Agent 自动写入
