Agent Card

个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发/发布名片、注册虾名片、录入/查询/编辑联系人、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。

虾名片 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. 初始化（开通虾名片）

1. 检查 data/contacts.json 是否存在
2. 不存在 → 创建：{"version":"1.0","owner":{"name":"","agent_name":""},"contacts":[]}，owner 信息从 Agent 记忆中获取，获取不到则留空
3. 检查 data/config.json 是否存在
4. 不存在 → 创建：{"version":"1.0","server":{"endpoint":"","api_key":"","user_id":""}}
5. 输出确认，告知数据存储路径

已存在 → 提示"花名册已存在"，不做修改。

2. 注册虾名片

1. 检查 config.json 中是否已有 user_id → 已有则提示"已注册，用户 ID 为 xxx"
2. 询问用户想用什么用户 ID（字母、数字、短横线）、名字和 Agent 名字
3. 调用 POST {config.server.endpoint}/register，请求体：{"name":"用户名","agent_name":"Agent名","user_id":"用户选的ID"}
4. 成功 → 写 user_id 和 api_key 到 config.json，输出确认
5. 失败 → 提示原因（ID 被占用、网络错误等）

server.endpoint 为空时，提示先配置服务器地址。

3. 录入联系人

1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息
2. 检查 contacts.json 是否存在 → 不存在则提示"开通虾名片"
3. 姓名重复 → 提示"已有一个叫 XXX 的联系人，是要更新还是新建？"
4. 姓名缺失 → 必须追问，不可跳过
5. 其他信息缺失 → 追问一次，用户说"就这样"就保存
6. 自动填入：id（c+时间戳）、met_at（当前日期 YYYY-MM-DD）、updated_at（ISO 8601）
7. 写入 contacts.json，输出确认

纯本地操作，不触发任何发送或通知。

4. 查询搜索

1. 检查 contacts.json → 不存在则提示"先开通虾名片"
2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索
3. 返回匹配结果，按相关度排序，以格式化文字或表格展示
4. 底部附上本地 HTML 路径（templates/card.html）或在线链接（如已部署）

搜不到 → 明确告知，不编造结果。

5. 编辑更新

1. 按姓名定位联系人 → 找不到则提示"花名册里没有这个人"，不自动创建
2. 更新指定字段，刷新 updated_at
3. 输出变更摘要

匹配到多人 → 列出列表让用户选择。

6. 生成名片

1. 读取 profile.json（存在则基于现有内容更新）
2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式
3. 信息优先级：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识
4. 生成预览（三段式文本块格式），等待用户确认
5. 用户说"名片确认了" → 写入 profile.json

profile.json 7 天内更新过 → 提示"名片 XX 天前更新过，确认要重新生成吗？" 记忆信息不足 → 如实告知"以下信息从记忆中提取，可能不完整，请确认"。 不自动发布到服务器。不自动修改 profile.json，必须经用户确认。

7. 发名片

1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先"生成我的名片"
2. 生成三段式文本块
3. published_at 非空（已发布）→ 直接输出
4. published_at 为 null（未发布）→ 输出文本块 + 提醒"名片还未发布到服务器，链接暂时不可用。建议先说'发布名片'将名片上线。"

核心原则：不会自动发布到服务器，必须用户明确说"发布名片"才执行。

8. 发布名片

1. 检查 profile.json → 不存在则提示先生成
2. 检查 config.json 中 api_key 和 user_id → 未配置则提示"先注册虾名片"
3. 按 tiers.public.fields 筛选公开字段构建推送数据
4. 不推送：personal_notes（永不上传）、background、current_focus（V1 本地私密）
5. 调用 PUT {endpoint}/card/{user_id}，Header X-API-Key: {api_key}
6. 成功 → 更新 profile.json 的 published_at，输出名片链接和发布时间
7. 失败 → 提示错误，不修改 published_at

9. 收名片（Agent 识别）

当对话中收到包含 agent-card:// 的消息时触发：

1. 检测 agent-card:// → 不包含则忽略
2. 从 agent-card://user_id 解析 user_id
3. contacts.json 不存在 → 自动初始化
4. Skill 未安装 → 提示用户"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？" → 用户确认后，从 JSON 的 _skill 字段获取安装源并自动安装
5. 获取数据：优先从消息中的链接提取（如 https://xxx/{user_id}）并 fetch /card/{user_id} 获取结构化 JSON，回退从文本中提取信息。如消息中无链接，则从 config.json 读取 endpoint 拼接
6. 写入 contacts.json（自动填 id、met_at、updated_at）
7. 输出"已将 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 自动写入