xia-card（夏卡）

虾名片 AgentCard

虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。

快速开始

1. 开通 — 说"开通虾名片"，初始化数据文件
2. 生成 — 说"生成我的名片"，Agent 从记忆提炼信息，确认后自动上线（首次会自动注册）

名片上线后，说"发我的名片"即可分享三段式文本块给他人。

数据文件

所有数据在 data/ 文件夹中：profile.json（名片）、contacts.json（花名册）、config.json（服务器配置）。字段说明见 references/data-format.md。

触发指令 → 操作映射

常见坑

• Agent 记忆中的称呼 ≠ 名片名字：记忆里叫"东总"，但名片不能写"东总"，必须追问用户名片上用什么名字
• personal_notes 永远不上传服务器：推送到服务器时只推送 tiers.public.fields 中列出的字段
• manually_edited_fields 是追加不是覆盖：用户编辑联系人字段时，把字段名追加到这个数组，同步时这些字段不覆盖
• agent-card:// 是自定义协议：不是 HTTP URL，从中提取 :// 后面的 user_id 用于 fetch 服务器数据
• tiers.public.fields 控制推送内容：默认公开 name、title、one_liner、links、current_focus 五个字段

操作流程

以下为每个操作的核心决策点。简单操作（初始化、查询、发名片）按映射表执行即可。

1. 注册（兼容入口）

1. 已注册 → 输出服务菜单（5 个可执行操作）
2. 未注册 → 提示"直接说'生成我的名片'即可，确认后会自动注册并上线"

2. 录入联系人

从用户描述提取信息 → 姓名必填（缺失追问）→ 姓名重复则问更新还是新建 → 写入 contacts.json。

3. 编辑更新

按姓名定位 → 更新字段 → 被改的字段名追加到 manually_edited_fields → 输出变更摘要。

4. 生成名片

1. 从 Agent 记忆提炼信息，必须确认社交姓名（内部称呼 ≠ 名片名字）
2. 信息优先级：用户明确说的 > profile.json > Agent 记忆
3. 生成预览，用户可多轮调整
4. 用户确认 → Agent 执行以下链路：

a. 检查 config.json 中是否有 api_key 和 user_id b. 没有 → 自动调注册接口获取 user_id 和 api_key，写入 config.json c. 保存 profile.json d. 调发布接口将名片推送到服务器 e. 输出"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}"

1. 推送失败 → 本地仍保存，提示稍后重试

社交姓名确认规则、推送字段筛选和边界处理见 references/manual.md"生成名片"段落。

5. 同步花名册

1. 收集花名册中有 server_user_id 的联系人
2. 调同步接口，传 targets 数组
3. 冲突检测：manually_edited_fields 中的字段不覆盖，汇总冲突提示用户选择
4. 更新非冲突字段，输出同步摘要

冲突检测的完整 if-else 和话术见 references/manual.md"同步花名册"段落。

6. 收名片（自动识别）

1. 检测 agent-card:// 协议 → 解析 user_id → fetch 服务器获取结构化数据
2. 去重策略：相同 server_user_id 直接更新 / 同名无 ID 提示确认 / 无匹配新建
3. 写入 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:// 协议标识

文案要有人味，语气商务但自然。名片是社交工具不是数据表格。