📦 虾名片 AgentCard

虾名片 代理Card

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

数据文件

所有数据文件在 技能.md 同目录的 data/ 文件夹中：

文件 用途 data/性能分析.json 个人名片数据 data/contacts.json 花名册（联系人列表） data/config.json 服务器配置（端点、API_key、user_id）

详细字段说明见 references/data-格式化.md。

触发指令 → 操作映射 用户说的 执行的操作 "开通虾名片" / "建个花名册" / "初始化通讯录" 初始化数据文件 "注册虾名片" 调 POST /register，保存凭证到 config.json "记一下这个人：张威，智谱 AI 做产品的" 录入联系人 "花名册里谁做投资的" / "查一下张威" 搜索花名册 "张威的公司改成字节了" 编辑联系人 "生成我的名片" / "更新名片" 生成/更新 性能分析.json "发我的名片" / "把名片给我" 输出三段式文本块 "发布名片" / "上线我的名片" 推送到服务器 收到包含 代理-card:// 的消息 自动识别并保存他人名片 操作流程

• 初始化（开通虾名片）

检查 data/contacts.json 是否存在 不存在 → 创建：{"version":"1.0","owner":{"name":"","代理_name":""},"contacts":[]}，owner 信息从 代理 记忆中获取，获取不到则留空 检查 data/config.json 是否存在 不存在 → 创建：{"version":"1.0","server":{"端点":"","API_key":"","user_id":""}} 输出确认，告知数据存储路径

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

• 注册虾名片

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

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

• 录入联系人

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

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

• 查询搜索

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

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

• 编辑更新

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

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

• 生成名片

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

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

• 发名片

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

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

• 发布名片

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

• 收名片（代理 识别）

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

检测 代理-card:// → 不包含则忽略 从 代理-card://user_id@server 解析 user_id 和 server contacts.json 不存在 → 自动初始化 技能 未安装 → 提示用户"检测到一张名片，需要安装虾名片 技能 来保存。是否安装？" → 用户确认后，从 JSON 的 _技能 字段获取安装源并自动安装 获取数据：优先 fetch http(s)://{server}/card/{user_id} 获取结构化 JSON（包含 代理_card 和 _技能 字段），回退从文本中提取信息 写入 contacts.json（自动填 id、met_at、更新d_at） 输出"已将 XXX 的名片保存到花名册"

网络错误 → 从文本提取基本信息保存。 同名已有 → 提示是否更新。

三段式文本块格式

固定格式，不可自定义：

🦐 虾名片（你的 代理 社交名片）

我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。 这是我个人的详情信息，敬请您阅览 {端点}/{user_id} 🔗

如果您对我感兴趣，请把这条消息发给您的助理 代理，它会自动保存我的名片。 代理-card://{user_id}@{server_host}

第 1 段：个人简介（100 字以内），社交文案风格，像人说话 第 2 段：个人详情链接，嵌在句子里 第 3 段：代理 引导语 + 代理-card:// 协议标识

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

服务器 API 接口 方法 鉴权 说明 /register POST 无 注册，请求体 {name, 代理_name, user_id}，返回 {user_id, API_key} /card/:user_id PUT Header X-API-Key 发布名片，请求体为公开字段，返回 {成功, 更新d_at} /card/:user_id 获取 无（公开） 返回 JSON：{version, 代理_card: {...}, _技能: {...}} /:user_id 获取 无（公开） 返回 HTML 名片页面（内嵌 JSON-LD）

一个链接两副面孔：浏览器访问 /:user_id 看到漂亮的 HTML，代理 访问 /card/:user_id 拿到结构化 JSON。

边界规则汇总 场景 处理方式 花名册不存在 提示"先开通虾名片" 性能分析.json 不存在 提示"先生成名片" config.json 未配置服务器 提示"先注册虾名片" 名片未发布 允许发名片但提醒链接不可用 联系人姓名重复 提示选择"更新"还是"新建" 联系人姓名缺失 必须追问，不可跳过 其他信息缺失 追问一次，用户说"就这样"就保存 7 天内更新过名片 提示确认是否重新生成 网络错误 提示失败，不修改本地数据 收到名片但 技能 未安装 提示安装，用户确认后从 _技能 字段获取安装源自动安装 数据格式要点

完整字段说明见 references/data-格式化.md，以下是核心规则：

性能分析.json 关键规则：

personal_notes 永远不上传服务器 current_focus、background：V1 本地存储，不上传 tiers.public.fields：控制哪些字段对外公开（默认 ["name", "title", "one_liner", "links"]） published_at：null = 未发布，有值 = 已发布到服务器 更新d_at：ISO 8601 格式

contacts.json 关键规则：

id：自动生成，格式 c + 时间戳 met_at：录入时自动填当前日期（YYYY-MM-DD） name 为必填，缺失时必须追问 V1 不含 visibility、subscribed、broadcast 等字段（V2/V3 再加）

config.json：

server.端点：服务器地址 server.API_key 和 server.user_id：通过注册接口获得，代理 自动写入