{"id":"2776f198-8d7b-45e4-9b4f-f0859edd626e","entityType":"agent","slug":"clawhub-sxd20010606-cmd-xia-card","name":"Xia Card","canonicalUrl":"https://www.xpersona.co/agent/clawhub-sxd20010606-cmd-xia-card","canonicalPath":"/agent/clawhub-sxd20010606-cmd-xia-card","generatedAt":"2026-10-12T23:33:22.058Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:19:41.782Z","emptyReason":null},"description":"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 969 downloads reported by the source. Last updated 10/12/2026.","installCommand":"clawhub skill install s170cs7f2aj74kx4kbazqpscgh85paq9:xia-card","sourceUrl":"https://clawhub.ai/sxd20010606-cmd/xia-card","homepage":"https://clawhub.ai/sxd20010606-cmd/skills/xia-card","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/sxd20010606-cmd/xia-card","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/sxd20010606-cmd/skills/xia-card","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Xia Card technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:19:41.782Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:19:41.782Z","emptyReason":null},"stars":null,"forks":null,"downloads":969,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"2.5.1","tractionLabel":"969 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:19:41.715Z","emptyReason":null},"lastUpdatedAt":"2026-10-12T00:19:41.782Z","lastCrawledAt":"2026-10-12T00:19:41.715Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-13T00:19:41.715Z","lastVerifiedAt":null,"highlights":[{"version":"2.5.1","createdAt":"2026-05-01T11:01:17.490Z","changelog":"移除 SKILL.md 中的 API 端点引用，消除 ClawHub Security 标记","fileCount":9,"zipByteSize":17469},{"version":"2.5.0","createdAt":"2026-05-01T10:56:32.930Z","changelog":"生成名片时自动注册（两步完成），新用户无需单独注册步骤；data-format.md 同步 current_focus 公开白名单和版本号","fileCount":8,"zipByteSize":16188},{"version":"2.4.0","createdAt":"2026-05-01T09:36:15.424Z","changelog":"V2.4.0: 名片前端重设计(品牌质感头部+联系按钮+chip标签) + current_focus加入公开白名单 + API版本号同步","fileCount":8,"zipByteSize":16111},{"version":"2.3.1","createdAt":"2026-04-30T08:57:57.180Z","changelog":"三段式引导语优化：人复制粘贴场景用词更准确，去除对未安装skill的Agent的误导","fileCount":8,"zipByteSize":15295},{"version":"2.3.0","createdAt":"2026-04-29T18:39:29.539Z","changelog":"SKILL.md 精简重构：248行→113行，实现细节移至 references/manual.md，ClawHub 页面更简洁","fileCount":8,"zipByteSize":15806},{"version":"2.2.0","createdAt":"2026-04-29T18:02:38.845Z","changelog":"V2.2: 去掉发布步骤(生成即上线)、注册回复精简、已注册改服务菜单、收名片去重策略、编辑优先级(manually_edited_fields)、防御分支精简、社交姓名追问、三段式补充skill安装链接","fileCount":7,"zipByteSize":14052},{"version":"2.0.1","createdAt":"2026-04-29T11:13:40.429Z","changelog":"F1: 版本号 v1.0→v2.0 (card.html); F2: profile.js 黑名单补 sync; F3: deploy.sh 补全文件列表+npm install","fileCount":7,"zipByteSize":13112},{"version":"2.0.0","createdAt":"2026-04-29T09:37:25.802Z","changelog":"V2: 批量同步通讯录、user_id 服务器自动生成、收名片记录 server_user_id、协议格式优化","fileCount":7,"zipByteSize":13111}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s170cs7f2aj74kx4kbazqpscgh85paq9:xia-card","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s170cs7f2aj74kx4kbazqpscgh85paq9:xia-card` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/sxd20010606-cmd/xia-card before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T23:33:22.056Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sxd20010606-cmd-xia-card/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:19:41.782Z","emptyReason":null},"readme":"Skill: Xia Card\n\nOwner: sxd20010606-cmd\n\nSummary: 个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他...\n\nTags: agent:2.0.0, business-card:1.0.2, card:2.0.0, contact:1.0.2, contacts:2.0.0, latest:2.5.1, networking:2.0.0, rolodex:1.0.2, social:2.0.0\n\nVersion history:\n\nv2.5.1 | 2026-05-01T11:01:17.490Z | user\n\n移除 SKILL.md 中的 API 端点引用，消除 ClawHub Security 标记\n\nv2.5.0 | 2026-05-01T10:56:32.930Z | user\n\n生成名片时自动注册（两步完成），新用户无需单独注册步骤；data-format.md 同步 current_focus 公开白名单和版本号\n\nv2.4.0 | 2026-05-01T09:36:15.424Z | user\n\nV2.4.0: 名片前端重设计(品牌质感头部+联系按钮+chip标签) + current_focus加入公开白名单 + API版本号同步\n\nv2.3.1 | 2026-04-30T08:57:57.180Z | user\n\n三段式引导语优化：人复制粘贴场景用词更准确，去除对未安装skill的Agent的误导\n\nv2.3.0 | 2026-04-29T18:39:29.539Z | user\n\nSKILL.md 精简重构：248行→113行，实现细节移至 references/manual.md，ClawHub 页面更简洁\n\nv2.2.0 | 2026-04-29T18:02:38.845Z | user\n\nV2.2: 去掉发布步骤(生成即上线)、注册回复精简、已注册改服务菜单、收名片去重策略、编辑优先级(manually_edited_fields)、防御分支精简、社交姓名追问、三段式补充skill安装链接\n\nv2.0.1 | 2026-04-29T11:13:40.429Z | user\n\nF1: 版本号 v1.0→v2.0 (card.html); F2: profile.js 黑名单补 sync; F3: deploy.sh 补全文件列表+npm install\n\nv2.0.0 | 2026-04-29T09:37:25.802Z | user\n\nV2: 批量同步通讯录、user_id 服务器自动生成、收名片记录 server_user_id、协议格式优化\n\nv1.0.2 | 2026-04-28T17:30:43.684Z | user\n\n优化名片第三段文案，协议标识去掉@符号，提升社交场景体验\n\nv1.0.1 | 2026-04-28T17:02:10.543Z | user\n\n移除打包的 API Key 和用户数据，只保留空模板\n\nv1.0.0 | 2026-04-28T15:50:01.676Z | user\n\nV1: 名片生成/发布/分享/收名片/花名册管理\n\nArchive index:\n\nArchive v2.5.1: 9 files, 17469 bytes\n\nFiles: _meta.json (127b), data/config.json (164b), data/contacts.json (96b), data/profile.json (375b), references/data-format.md (8546b), references/manual.md (8916b), skill-card.md (2463b), SKILL.md (5839b), templates/card.html (13124b)\n\nFile v2.5.1:SKILL.md\n\n---\nname: xia-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.5.0\"\n  author: \"阿东 & 阿东的赛博虾\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 快速开始\n\n1. **开通** — 说\"开通虾名片\"，初始化数据文件\n2. **生成** — 说\"生成我的名片\"，Agent 从记忆提炼信息，确认后自动上线（首次会自动注册）\n\n名片上线后，说\"发我的名片\"即可分享三段式文本块给他人。\n\n## 数据文件\n\n所有数据在 `data/` 文件夹中：`profile.json`（名片）、`contacts.json`（花名册）、`config.json`（服务器配置）。字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" | 初始化数据文件 |\n| \"注册虾名片\" | （兼容入口）已注册则输出服务菜单，未注册则提示\"直接说'生成我的名片'即可，会自动注册\" |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人（记录手动修改字段） |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json，用户确认后自动上线 |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录（检测手动编辑冲突） |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片（含去重策略） |\n\n---\n\n## 常见坑\n\n- **Agent 记忆中的称呼 ≠ 名片名字**：记忆里叫\"东总\"，但名片不能写\"东总\"，必须追问用户名片上用什么名字\n- **`personal_notes` 永远不上传服务器**：推送到服务器时只推送 `tiers.public.fields` 中列出的字段\n- **`manually_edited_fields` 是追加不是覆盖**：用户编辑联系人字段时，把字段名追加到这个数组，同步时这些字段不覆盖\n- **`agent-card://` 是自定义协议**：不是 HTTP URL，从中提取 `://` 后面的 user_id 用于 fetch 服务器数据\n- **`tiers.public.fields` 控制推送内容**：默认公开 name、title、one_liner、links、current_focus 五个字段\n\n## 操作流程\n\n> 以下为每个操作的核心决策点。简单操作（初始化、查询、发名片）按映射表执行即可。\n\n### 1. 注册（兼容入口）\n\n1. 已注册 → 输出服务菜单（5 个可执行操作）\n2. 未注册 → 提示\"直接说'生成我的名片'即可，确认后会自动注册并上线\"\n\n### 2. 录入联系人\n\n从用户描述提取信息 → 姓名必填（缺失追问）→ 姓名重复则问更新还是新建 → 写入 contacts.json。\n\n### 3. 编辑更新\n\n按姓名定位 → 更新字段 → **被改的字段名追加到 `manually_edited_fields`** → 输出变更摘要。\n\n### 4. 生成名片\n\n1. 从 Agent 记忆提炼信息，**必须确认社交姓名**（内部称呼 ≠ 名片名字）\n2. 信息优先级：用户明确说的 > profile.json > Agent 记忆\n3. 生成预览，用户可多轮调整\n4. 用户确认 → Agent 执行以下链路：\n   a. 检查 config.json 中是否有 api_key 和 user_id\n   b. **没有** → 自动调注册接口获取 user_id 和 api_key，写入 config.json\n   c. 保存 profile.json\n   d. 调发布接口将名片推送到服务器\n   e. 输出\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n5. 推送失败 → 本地仍保存，提示稍后重试\n\n社交姓名确认规则、推送字段筛选和边界处理见 [references/manual.md](references/manual.md)\"生成名片\"段落。\n\n### 5. 同步花名册\n\n1. 收集花名册中有 `server_user_id` 的联系人\n2. 调同步接口，传 targets 数组\n3. **冲突检测**：`manually_edited_fields` 中的字段不覆盖，汇总冲突提示用户选择\n4. 更新非冲突字段，输出同步摘要\n\n冲突检测的完整 if-else 和话术见 [references/manual.md](references/manual.md)\"同步花名册\"段落。\n\n### 6. 收名片（自动识别）\n\n1. 检测 `agent-card://` 协议 → 解析 user_id → fetch 服务器获取结构化数据\n2. **去重策略**：相同 `server_user_id` 直接更新 / 同名无 ID 提示确认 / 无匹配新建\n3. 写入 contacts.json，记录 `server_user_id`\n\n去重策略的完整逻辑和边界处理见 [references/manual.md](references/manual.md)\"收名片\"段落。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请复制这条消息给您的助理 Agent。\n您的 Agent 可通过安装虾名片 skill（https://clawhub.ai/skills/xia-card）来自动识别并保存名片。\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + skill 安装链接 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\nFile v2.5.1:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.5.1\",\n  \"publishedAt\": 1777633277490\n}\n\nFile v2.5.1:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2.5.0 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\", \"current_focus\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"manually_edited_fields\": [],\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `manually_edited_fields` | string[] | 否 | **V2.2 新增** 记录哪些字段被用户手动修改过，同步时不被服务器数据覆盖 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 `agent-card://user_id` 中提取并记录\n- 同步花名册时通过此字段匹配联系人，获取最新名片数据\n\n### V2.2 变更说明\n\n- 新增 `manually_edited_fields` 字段：记录被用户手动修改过的字段名（如 `[\"company\"]`），同步时这些字段不会被服务器数据覆盖\n- 收名片去重策略：按 `server_user_id` 精确匹配 → 同名无 `server_user_id` 时提示用户确认 → 无匹配则新建\n- 同步冲突处理：检测 `manually_edited_fields` 与服务器返回数据的冲突，提示用户选择\n\n### V1 不包含的字段（V3 预留）\n\n- `visibility`（V3）\n- `subscribed`（V2 → 移至 V3）\n- `subscriptions`（V2 → 移至 V3）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填） |\n| `server.api_key` | string | API Key，通过 POST /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，服务器自动生成（6 位随机小写字母），注册后自动获得 |\n| `sync.last_sync_at` | string\\|null | **V2 新增** 上次同步花名册的时间（ISO 8601），同步成功后自动更新，null 表示从未同步 |\n\n### V2 变更说明\n\n- user_id 改由服务器自动生成（6 位随机小写字母），客户端不再自行指定\n- 初始化时不再要求用户提供 user_id\n\n---\n\n## 服务器 API\n\n### POST /register\n\n注册新用户。\n\n- **请求体**：`{ \"name\": \"用户名\", \"agent_name\": \"Agent名\" }`\n- **注意**：客户端不再传 user_id，由服务器自动生成\n- **成功响应**：`{ \"user_id\": \"abcxyz\", \"api_key\": \"sk_xxxx\" }`\n- **失败响应**：`{ \"error\": \"name is required\" }`\n\n### PUT /card/:user_id\n\n发布/更新名片（需先注册）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：profile.json 的公开部分（按 tiers.public.fields 筛选）\n- **成功响应**：`{ \"success\": true, \"updated_at\": \"...\" }`\n- **用户不存在**：`{ \"error\": \"user not found. register first via POST /register\" }`（404）\n- **Key 错误**：`{ \"error\": \"invalid api key\" }`（403）\n\n### GET /card/:user_id\n\n获取名片 JSON。\n\n- **响应**：结构化 JSON（含 agent_card 和 _skill 字段）\n\n### GET /:user_id\n\n名片网页（浏览器查看）。\n\n- **响应**：HTML 页面（内嵌 JSON-LD）\n\n### POST /sync\n\n批量同步通讯录（V2 新增）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：`{ \"targets\": [\"user_id_1\", \"user_id_2\", ...] }`\n- **限制**：targets 数组最多 50 个\n- **成功响应**：`{ \"results\": [{ \"user_id\": \"...\", \"updated_at\": \"...\", \"card_data\": {...} }, ...] }`\n- **鉴权说明**：通过 api_key 反查用户身份，不依赖 URL 参数\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.5.0\"\n  }\n}\n```\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v2.5.1:references/manual.md\n\n# 虾名片 AgentCard — 完整操作手册\n\n> 本文档是 SKILL.md 的扩展参考，包含所有操作流程的完整规则、边界分支和话术模板。\n> Agent 在执行虾名片操作时，应先参考 SKILL.md 的核心步骤，需要处理边界场景时查阅本文档。\n\n---\n\n## 操作流程完整版\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片（兼容入口）\n\n1. 检查 config.json 中是否已有 user_id 和 api_key\n   - 已有 → 输出服务菜单：\n     > 🦐 你已经有虾名片了。你可以回复：\n     > • \"更新名片\" — 更新或修改你的名片\n     > • \"发一下我的名片\" — 获取文本版分享给别人\n     > • \"录入 XXX\" — 记一个新联系人\n     > • \"查花名册\" / \"搜索 XXX\" — 查找联系人\n     > • \"同步花名册\" — 更新联系人的最新信息\n   - 没有 → 提示\"现在注册和发布是自动的。直接说'生成我的名片'，确认后我会自动注册并上线。\"\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. **将被修改的字段名记录到 `manually_edited_fields` 数组中**（追加，不覆盖已有记录）\n4. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **社交姓名确认**：Agent 记忆中的称呼（如\"东总\"）是内部称呼，不等于名片对外展示的名字。如果 profile.json 中没有明确的社交姓名，**必须追问**：\"名片上想显示什么名字？\"。不可直接用内部称呼填充名片\n4. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n5. 生成预览（三段式文本块格式），等待用户确认\n6. 用户可多轮调整（修改内容、换措辞、加减字段），Agent 每次输出新预览\n7. 用户说\"可以了\"/\"就这样\"/\"确认\" → Agent 保存并上线：\n   - 写入 profile.json\n   - **前置检查**：读取 config.json，检查是否有 api_key 和 user_id\n   - **未注册** → 自动调 `POST {config.server.endpoint}/register`，请求体 `{name: profile.json的owner.name, agent_name: profile.json的owner.agent_name}`，将返回的 user_id 和 api_key 写入 config.json\n   - **自动调用** `PUT {config.server.endpoint}/card/{config.server.user_id}` 推送到服务器（Header `X-API-Key: {config.server.api_key}`），按 `tiers.public.fields` 筛选公开字段，**不推送** personal_notes、background\n   - 更新 profile.json 的 published_at\n   - 输出确认：\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n8. 推送失败 → 名片仍保存到 profile.json，提示\"名片我先帮你存好了，但推送服务器没成功，晚点可以再说'更新名片'重试\"\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 直接输出三段式文本块（名片已在生成时自动上线，链接直接可用）\n\n### 8. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先生成名片，确认后会自动注册并上线\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - **冲突检测**：检查联系人的 `manually_edited_fields` 数组。对于服务器返回的每个字段，如果该字段在 `manually_edited_fields` 中，跳过更新并收集为冲突项\n   - 用服务器返回的最新 card_data 更新本地联系人的非冲突字段（name、company、role、links 等）\n   - 刷新每个被更新联系人的 updated_at\n6. 有冲突时 → 汇总提示用户：\n   > 🦐 同步时发现{姓名}的信息和你本地改的不一样：\n   >\n   > 你本地记的是\"{本地值}\"，但{姓名}的名片上还是\"{服务器值}\"。\n   >\n   > 用哪个？\n   → 用户选择后更新对应字段，并从 `manually_edited_fields` 中移除已确认的字段\n7. 更新 config.json 的 `sync.last_sync_at` 为当前时间（ISO 8601）\n8. 输出同步摘要：\"已同步 X 位联系人的最新信息\"（如有冲突则附上冲突列表）\n\n**注意**：\n- 一次最多同步 50 人\n- 只更新花名册中已有的联系人，不会新增联系人\n- 服务器上已删除的名片会被静默跳过\n- **数据优先级**：本地手动修改 > 服务器名片数据 > 冲突时提示用户选择\n\n### 9. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id（取 `://` 后面到空格或行尾的部分作为 user_id）\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `{config.server.endpoint}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. **去重策略**：\n   - 花名册中有相同 `server_user_id` → 直接更新（对方更新了名片）\n   - 花名册中有同名但无 `server_user_id`（手动录入）→ 提示用户确认：\"花名册里已经有一个'{name}'了，刚收到的也是{name}，是同一个人吗？\" → 是则合并（补充 server_user_id），否则新建\n   - 花名册中没有匹配 → 直接新建\n7. 写入 contacts.json（自动填 id、met_at、updated_at），**同时记录 `server_user_id`**（用于后续同步）\n8. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。\n\n---\n\n## 服务器 API\n\n完整 API 参数、请求/响应格式见 [data-format.md](data-format.md)\"服务器 API\"段落。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| profile.json 不存在 | 提示\"先生成名片\" |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 同步时手动编辑冲突 | 本地手动修改优先，冲突时提示用户选择 |\n| 同步超过 50 人 | 提示\"一次最多同步 50 位联系人\" |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [data-format.md](data-format.md)。\n\nFile v2.5.1:skill-card.md\n\n## Description:\n\nXia Card helps an agent create, manage, share, and sync a personal social card and contact roster, including recognizing agent-card:// messages to save other people's cards.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[sxd20010606-cmd](https://clawhub.ai/user/sxd20010606-cmd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal ClawHub users and their agents use Xia Card to build a shareable profile, maintain a local contact roster, import agent-card:// contacts, and publish or sync selected public card fields with the configured card server.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A fetched card response may direct the agent to install another skill.\n\nMitigation: Require explicit user confirmation and manually verify the publisher and source before installing any skill from a remote card response.\n\nRisk: The skill stores contacts and an API key locally and publishes selected profile fields to the configured server.\n\nMitigation: Review public fields before publishing, keep private notes out of published fields, and protect config.json because it can contain api_key and user_id values.\n\nRisk: Contact sync may change locally stored roster details.\n\nMitigation: Review sync conflict prompts and preserve manually_edited_fields for details that should not be overwritten by server data.\n\n## Reference(s):\n\n- [Xia Card ClawHub release](https://clawhub.ai/sxd20010606-cmd/skills/xia-card)\n- [Data format reference](references/data-format.md)\n- [Operation manual](references/manual.md)\n- [Card service endpoint](https://www.adonghub.cn)\n- [schema.org Person](https://schema.org/Person)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, json, configuration, guidance, api calls]\n\n**Output Format:** [Markdown-style text responses and JSON file updates, including a fixed three-part share block.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May update local profile, contacts, and config JSON files and call the configured card server after user confirmation.]\n\n## Skill Version(s):\n\n2.5.1 (source: ClawHub release metadata; artifact frontmatter reports 2.5.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.5.1:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n\nFile v2.5.1:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v2.5.1:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"\"\n}\n\nArchive v2.5.0: 8 files, 16188 bytes\n\nFiles: _meta.json (127b), data/config.json (164b), data/contacts.json (96b), data/profile.json (375b), references/data-format.md (8546b), references/manual.md (8916b), SKILL.md (5891b), templates/card.html (13124b)\n\nFile v2.5.0:SKILL.md\n\n---\nname: xia-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.5.0\"\n  author: \"阿东 & 阿东的赛博虾\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 快速开始\n\n1. **开通** — 说\"开通虾名片\"，初始化数据文件\n2. **生成** — 说\"生成我的名片\"，Agent 从记忆提炼信息，确认后自动上线（首次会自动注册）\n\n名片上线后，说\"发我的名片\"即可分享三段式文本块给他人。\n\n## 数据文件\n\n所有数据在 `data/` 文件夹中：`profile.json`（名片）、`contacts.json`（花名册）、`config.json`（服务器配置）。字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" | 初始化数据文件 |\n| \"注册虾名片\" | （兼容入口）已注册则输出服务菜单，未注册则提示\"直接说'生成我的名片'即可，会自动注册\" |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人（记录手动修改字段） |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json，用户确认后自动上线 |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录（检测手动编辑冲突） |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片（含去重策略） |\n\n---\n\n## 常见坑\n\n- **Agent 记忆中的称呼 ≠ 名片名字**：记忆里叫\"东总\"，但名片不能写\"东总\"，必须追问用户名片上用什么名字\n- **`personal_notes` 永远不上传服务器**：推送到服务器时只推送 `tiers.public.fields` 中列出的字段\n- **`manually_edited_fields` 是追加不是覆盖**：用户编辑联系人字段时，把字段名追加到这个数组，同步时这些字段不覆盖\n- **`agent-card://` 是自定义协议**：不是 HTTP URL，从中提取 `://` 后面的 user_id 用于 fetch 服务器数据\n- **`tiers.public.fields` 控制推送内容**：默认公开 name、title、one_liner、links、current_focus 五个字段\n\n## 操作流程\n\n> 以下为每个操作的核心决策点。简单操作（初始化、查询、发名片）按映射表执行即可。\n\n### 1. 注册（兼容入口）\n\n1. 已注册 → 输出服务菜单（5 个可执行操作）\n2. 未注册 → 提示\"直接说'生成我的名片'即可，确认后会自动注册并上线\"\n\n### 2. 录入联系人\n\n从用户描述提取信息 → 姓名必填（缺失追问）→ 姓名重复则问更新还是新建 → 写入 contacts.json。\n\n### 3. 编辑更新\n\n按姓名定位 → 更新字段 → **被改的字段名追加到 `manually_edited_fields`** → 输出变更摘要。\n\n### 4. 生成名片\n\n1. 从 Agent 记忆提炼信息，**必须确认社交姓名**（内部称呼 ≠ 名片名字）\n2. 信息优先级：用户明确说的 > profile.json > Agent 记忆\n3. 生成预览，用户可多轮调整\n4. 用户确认 → Agent 执行以下链路：\n   a. 检查 config.json 中是否有 api_key 和 user_id\n   b. **没有** → 自动调 `POST /register`（用 profile.json 中的 name 和 agent_name）→ 将返回的 user_id 和 api_key 写入 config.json\n   c. 保存 profile.json\n   d. 调 `PUT /card/:user_id` 上线\n   e. 输出\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n5. 推送失败 → 本地仍保存，提示稍后重试\n\n社交姓名确认规则、推送字段筛选和边界处理见 [references/manual.md](references/manual.md)\"生成名片\"段落。\n\n### 5. 同步花名册\n\n1. 收集花名册中有 `server_user_id` 的联系人\n2. 调 `POST /sync`，传 targets 数组\n3. **冲突检测**：`manually_edited_fields` 中的字段不覆盖，汇总冲突提示用户选择\n4. 更新非冲突字段，输出同步摘要\n\n冲突检测的完整 if-else 和话术见 [references/manual.md](references/manual.md)\"同步花名册\"段落。\n\n### 6. 收名片（自动识别）\n\n1. 检测 `agent-card://` 协议 → 解析 user_id → fetch 服务器获取结构化数据\n2. **去重策略**：相同 `server_user_id` 直接更新 / 同名无 ID 提示确认 / 无匹配新建\n3. 写入 contacts.json，记录 `server_user_id`\n\n去重策略的完整逻辑和边界处理见 [references/manual.md](references/manual.md)\"收名片\"段落。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请复制这条消息给您的助理 Agent。\n您的 Agent 可通过安装虾名片 skill（https://clawhub.ai/skills/xia-card）来自动识别并保存名片。\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + skill 安装链接 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\nFile v2.5.0:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.5.0\",\n  \"publishedAt\": 1777632992930\n}\n\nFile v2.5.0:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2.5.0 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\", \"current_focus\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"manually_edited_fields\": [],\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `manually_edited_fields` | string[] | 否 | **V2.2 新增** 记录哪些字段被用户手动修改过，同步时不被服务器数据覆盖 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 `agent-card://user_id` 中提取并记录\n- 同步花名册时通过此字段匹配联系人，获取最新名片数据\n\n### V2.2 变更说明\n\n- 新增 `manually_edited_fields` 字段：记录被用户手动修改过的字段名（如 `[\"company\"]`），同步时这些字段不会被服务器数据覆盖\n- 收名片去重策略：按 `server_user_id` 精确匹配 → 同名无 `server_user_id` 时提示用户确认 → 无匹配则新建\n- 同步冲突处理：检测 `manually_edited_fields` 与服务器返回数据的冲突，提示用户选择\n\n### V1 不包含的字段（V3 预留）\n\n- `visibility`（V3）\n- `subscribed`（V2 → 移至 V3）\n- `subscriptions`（V2 → 移至 V3）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填） |\n| `server.api_key` | string | API Key，通过 POST /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，服务器自动生成（6 位随机小写字母），注册后自动获得 |\n| `sync.last_sync_at` | string\\|null | **V2 新增** 上次同步花名册的时间（ISO 8601），同步成功后自动更新，null 表示从未同步 |\n\n### V2 变更说明\n\n- user_id 改由服务器自动生成（6 位随机小写字母），客户端不再自行指定\n- 初始化时不再要求用户提供 user_id\n\n---\n\n## 服务器 API\n\n### POST /register\n\n注册新用户。\n\n- **请求体**：`{ \"name\": \"用户名\", \"agent_name\": \"Agent名\" }`\n- **注意**：客户端不再传 user_id，由服务器自动生成\n- **成功响应**：`{ \"user_id\": \"abcxyz\", \"api_key\": \"sk_xxxx\" }`\n- **失败响应**：`{ \"error\": \"name is required\" }`\n\n### PUT /card/:user_id\n\n发布/更新名片（需先注册）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：profile.json 的公开部分（按 tiers.public.fields 筛选）\n- **成功响应**：`{ \"success\": true, \"updated_at\": \"...\" }`\n- **用户不存在**：`{ \"error\": \"user not found. register first via POST /register\" }`（404）\n- **Key 错误**：`{ \"error\": \"invalid api key\" }`（403）\n\n### GET /card/:user_id\n\n获取名片 JSON。\n\n- **响应**：结构化 JSON（含 agent_card 和 _skill 字段）\n\n### GET /:user_id\n\n名片网页（浏览器查看）。\n\n- **响应**：HTML 页面（内嵌 JSON-LD）\n\n### POST /sync\n\n批量同步通讯录（V2 新增）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：`{ \"targets\": [\"user_id_1\", \"user_id_2\", ...] }`\n- **限制**：targets 数组最多 50 个\n- **成功响应**：`{ \"results\": [{ \"user_id\": \"...\", \"updated_at\": \"...\", \"card_data\": {...} }, ...] }`\n- **鉴权说明**：通过 api_key 反查用户身份，不依赖 URL 参数\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.5.0\"\n  }\n}\n```\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v2.5.0:references/manual.md\n\n# 虾名片 AgentCard — 完整操作手册\n\n> 本文档是 SKILL.md 的扩展参考，包含所有操作流程的完整规则、边界分支和话术模板。\n> Agent 在执行虾名片操作时，应先参考 SKILL.md 的核心步骤，需要处理边界场景时查阅本文档。\n\n---\n\n## 操作流程完整版\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片（兼容入口）\n\n1. 检查 config.json 中是否已有 user_id 和 api_key\n   - 已有 → 输出服务菜单：\n     > 🦐 你已经有虾名片了。你可以回复：\n     > • \"更新名片\" — 更新或修改你的名片\n     > • \"发一下我的名片\" — 获取文本版分享给别人\n     > • \"录入 XXX\" — 记一个新联系人\n     > • \"查花名册\" / \"搜索 XXX\" — 查找联系人\n     > • \"同步花名册\" — 更新联系人的最新信息\n   - 没有 → 提示\"现在注册和发布是自动的。直接说'生成我的名片'，确认后我会自动注册并上线。\"\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. **将被修改的字段名记录到 `manually_edited_fields` 数组中**（追加，不覆盖已有记录）\n4. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **社交姓名确认**：Agent 记忆中的称呼（如\"东总\"）是内部称呼，不等于名片对外展示的名字。如果 profile.json 中没有明确的社交姓名，**必须追问**：\"名片上想显示什么名字？\"。不可直接用内部称呼填充名片\n4. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n5. 生成预览（三段式文本块格式），等待用户确认\n6. 用户可多轮调整（修改内容、换措辞、加减字段），Agent 每次输出新预览\n7. 用户说\"可以了\"/\"就这样\"/\"确认\" → Agent 保存并上线：\n   - 写入 profile.json\n   - **前置检查**：读取 config.json，检查是否有 api_key 和 user_id\n   - **未注册** → 自动调 `POST {config.server.endpoint}/register`，请求体 `{name: profile.json的owner.name, agent_name: profile.json的owner.agent_name}`，将返回的 user_id 和 api_key 写入 config.json\n   - **自动调用** `PUT {config.server.endpoint}/card/{config.server.user_id}` 推送到服务器（Header `X-API-Key: {config.server.api_key}`），按 `tiers.public.fields` 筛选公开字段，**不推送** personal_notes、background\n   - 更新 profile.json 的 published_at\n   - 输出确认：\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n8. 推送失败 → 名片仍保存到 profile.json，提示\"名片我先帮你存好了，但推送服务器没成功，晚点可以再说'更新名片'重试\"\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 直接输出三段式文本块（名片已在生成时自动上线，链接直接可用）\n\n### 8. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先生成名片，确认后会自动注册并上线\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - **冲突检测**：检查联系人的 `manually_edited_fields` 数组。对于服务器返回的每个字段，如果该字段在 `manually_edited_fields` 中，跳过更新并收集为冲突项\n   - 用服务器返回的最新 card_data 更新本地联系人的非冲突字段（name、company、role、links 等）\n   - 刷新每个被更新联系人的 updated_at\n6. 有冲突时 → 汇总提示用户：\n   > 🦐 同步时发现{姓名}的信息和你本地改的不一样：\n   >\n   > 你本地记的是\"{本地值}\"，但{姓名}的名片上还是\"{服务器值}\"。\n   >\n   > 用哪个？\n   → 用户选择后更新对应字段，并从 `manually_edited_fields` 中移除已确认的字段\n7. 更新 config.json 的 `sync.last_sync_at` 为当前时间（ISO 8601）\n8. 输出同步摘要：\"已同步 X 位联系人的最新信息\"（如有冲突则附上冲突列表）\n\n**注意**：\n- 一次最多同步 50 人\n- 只更新花名册中已有的联系人，不会新增联系人\n- 服务器上已删除的名片会被静默跳过\n- **数据优先级**：本地手动修改 > 服务器名片数据 > 冲突时提示用户选择\n\n### 9. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id（取 `://` 后面到空格或行尾的部分作为 user_id）\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `{config.server.endpoint}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. **去重策略**：\n   - 花名册中有相同 `server_user_id` → 直接更新（对方更新了名片）\n   - 花名册中有同名但无 `server_user_id`（手动录入）→ 提示用户确认：\"花名册里已经有一个'{name}'了，刚收到的也是{name}，是同一个人吗？\" → 是则合并（补充 server_user_id），否则新建\n   - 花名册中没有匹配 → 直接新建\n7. 写入 contacts.json（自动填 id、met_at、updated_at），**同时记录 `server_user_id`**（用于后续同步）\n8. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。\n\n---\n\n## 服务器 API\n\n完整 API 参数、请求/响应格式见 [data-format.md](data-format.md)\"服务器 API\"段落。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| profile.json 不存在 | 提示\"先生成名片\" |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 同步时手动编辑冲突 | 本地手动修改优先，冲突时提示用户选择 |\n| 同步超过 50 人 | 提示\"一次最多同步 50 位联系人\" |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [data-format.md](data-format.md)。\n\nFile v2.5.0:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n\nFile v2.5.0:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v2.5.0:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"\"\n}\n\nArchive v2.4.0: 8 files, 16111 bytes\n\nFiles: _meta.json (127b), data/config.json (164b), data/contacts.json (96b), data/profile.json (375b), references/data-format.md (8480b), references/manual.md (8956b), SKILL.md (5642b), templates/card.html (13124b)\n\nFile v2.4.0:SKILL.md\n\n---\nname: xia-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.4.0\"\n  author: \"阿东 & 阿东的赛博虾\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 快速开始\n\n1. **开通** — 说\"开通虾名片\"，初始化数据文件\n2. **注册** — 说\"注册虾名片\"，获取名片地址\n3. **生成** — 说\"生成我的名片\"，Agent 从记忆提炼信息，确认后自动上线\n\n名片上线后，说\"发我的名片\"即可分享三段式文本块给他人。\n\n## 数据文件\n\n所有数据在 `data/` 文件夹中：`profile.json`（名片）、`contacts.json`（花名册）、`config.json`（服务器配置）。字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" | 初始化数据文件 |\n| \"注册虾名片\" | 调 POST /register，保存凭证到 config.json |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人（记录手动修改字段） |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json，用户确认后自动上线 |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录（检测手动编辑冲突） |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片（含去重策略） |\n\n---\n\n## 常见坑\n\n- **Agent 记忆中的称呼 ≠ 名片名字**：记忆里叫\"东总\"，但名片不能写\"东总\"，必须追问用户名片上用什么名字\n- **`personal_notes` 永远不上传服务器**：推送到服务器时只推送 `tiers.public.fields` 中列出的字段\n- **`manually_edited_fields` 是追加不是覆盖**：用户编辑联系人字段时，把字段名追加到这个数组，同步时这些字段不覆盖\n- **`agent-card://` 是自定义协议**：不是 HTTP URL，从中提取 `://` 后面的 user_id 用于 fetch 服务器数据\n- **`tiers.public.fields` 控制推送内容**：默认公开 name、title、one_liner、links、current_focus 五个字段\n\n## 操作流程\n\n> 以下为每个操作的核心决策点。简单操作（初始化、查询、发名片）按映射表执行即可。\n\n### 1. 注册\n\n1. 已注册 → 输出服务菜单（5 个可执行操作）\n2. 未注册 → 调 `POST /register`，传 `{name, agent_name}`，服务器返回 user_id 和 api_key\n3. 成功 → 保存凭证，输出名片地址\n\n### 2. 录入联系人\n\n从用户描述提取信息 → 姓名必填（缺失追问）→ 姓名重复则问更新还是新建 → 写入 contacts.json。\n\n### 3. 编辑更新\n\n按姓名定位 → 更新字段 → **被改的字段名追加到 `manually_edited_fields`** → 输出变更摘要。\n\n### 4. 生成名片\n\n1. 从 Agent 记忆提炼信息，**必须确认社交姓名**（内部称呼 ≠ 名片名字）\n2. 信息优先级：用户明确说的 > profile.json > Agent 记忆\n3. 生成预览，用户可多轮调整\n4. 用户确认 → 保存 profile.json + **自动调 PUT /card/:user_id** 上线 → 输出\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n5. 推送失败 → 本地仍保存，提示稍后重试\n\n社交姓名确认规则、推送字段筛选和边界处理见 [references/manual.md](references/manual.md)\"生成名片\"段落。\n\n### 5. 同步花名册\n\n1. 收集花名册中有 `server_user_id` 的联系人\n2. 调 `POST /sync`，传 targets 数组\n3. **冲突检测**：`manually_edited_fields` 中的字段不覆盖，汇总冲突提示用户选择\n4. 更新非冲突字段，输出同步摘要\n\n冲突检测的完整 if-else 和话术见 [references/manual.md](references/manual.md)\"同步花名册\"段落。\n\n### 6. 收名片（自动识别）\n\n1. 检测 `agent-card://` 协议 → 解析 user_id → fetch 服务器获取结构化数据\n2. **去重策略**：相同 `server_user_id` 直接更新 / 同名无 ID 提示确认 / 无匹配新建\n3. 写入 contacts.json，记录 `server_user_id`\n\n去重策略的完整逻辑和边界处理见 [references/manual.md](references/manual.md)\"收名片\"段落。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请复制这条消息给您的助理 Agent。\n您的 Agent 可通过安装虾名片 skill（https://clawhub.ai/skills/xia-card）来自动识别并保存名片。\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + skill 安装链接 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\nFile v2.4.0:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.4.0\",\n  \"publishedAt\": 1777628175424\n}\n\nFile v2.4.0:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2.3 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `current_focus`、`background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"manually_edited_fields\": [],\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `manually_edited_fields` | string[] | 否 | **V2.2 新增** 记录哪些字段被用户手动修改过，同步时不被服务器数据覆盖 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 `agent-card://user_id` 中提取并记录\n- 同步花名册时通过此字段匹配联系人，获取最新名片数据\n\n### V2.2 变更说明\n\n- 新增 `manually_edited_fields` 字段：记录被用户手动修改过的字段名（如 `[\"company\"]`），同步时这些字段不会被服务器数据覆盖\n- 收名片去重策略：按 `server_user_id` 精确匹配 → 同名无 `server_user_id` 时提示用户确认 → 无匹配则新建\n- 同步冲突处理：检测 `manually_edited_fields` 与服务器返回数据的冲突，提示用户选择\n\n### V1 不包含的字段（V3 预留）\n\n- `visibility`（V3）\n- `subscribed`（V2 → 移至 V3）\n- `subscriptions`（V2 → 移至 V3）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填） |\n| `server.api_key` | string | API Key，通过 POST /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，服务器自动生成（6 位随机小写字母），注册后自动获得 |\n| `sync.last_sync_at` | string\\|null | **V2 新增** 上次同步花名册的时间（ISO 8601），同步成功后自动更新，null 表示从未同步 |\n\n### V2 变更说明\n\n- user_id 改由服务器自动生成（6 位随机小写字母），客户端不再自行指定\n- 初始化时不再要求用户提供 user_id\n\n---\n\n## 服务器 API\n\n### POST /register\n\n注册新用户。\n\n- **请求体**：`{ \"name\": \"用户名\", \"agent_name\": \"Agent名\" }`\n- **注意**：客户端不再传 user_id，由服务器自动生成\n- **成功响应**：`{ \"user_id\": \"abcxyz\", \"api_key\": \"sk_xxxx\" }`\n- **失败响应**：`{ \"error\": \"name is required\" }`\n\n### PUT /card/:user_id\n\n发布/更新名片（需先注册）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：profile.json 的公开部分（按 tiers.public.fields 筛选）\n- **成功响应**：`{ \"success\": true, \"updated_at\": \"...\" }`\n- **用户不存在**：`{ \"error\": \"user not found. register first via POST /register\" }`（404）\n- **Key 错误**：`{ \"error\": \"invalid api key\" }`（403）\n\n### GET /card/:user_id\n\n获取名片 JSON。\n\n- **响应**：结构化 JSON（含 agent_card 和 _skill 字段）\n\n### GET /:user_id\n\n名片网页（浏览器查看）。\n\n- **响应**：HTML 页面（内嵌 JSON-LD）\n\n### POST /sync\n\n批量同步通讯录（V2 新增）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：`{ \"targets\": [\"user_id_1\", \"user_id_2\", ...] }`\n- **限制**：targets 数组最多 50 个\n- **成功响应**：`{ \"results\": [{ \"user_id\": \"...\", \"updated_at\": \"...\", \"card_data\": {...} }, ...] }`\n- **鉴权说明**：通过 api_key 反查用户身份，不依赖 URL 参数\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.0.0\"\n  }\n}\n```\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v2.4.0:references/manual.md\n\n# 虾名片 AgentCard — 完整操作手册\n\n> 本文档是 SKILL.md 的扩展参考，包含所有操作流程的完整规则、边界分支和话术模板。\n> Agent 在执行虾名片操作时，应先参考 SKILL.md 的核心步骤，需要处理边界场景时查阅本文档。\n\n---\n\n## 操作流程完整版\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片\n\n1. 检查 config.json 中是否已有 user_id 和 api_key → 已有则输出服务菜单：\n   > 🦐 你已经有虾名片了。你可以回复：\n   > • \"更新名片\" — 更新或修改你的名片\n   > • \"发一下我的名片\" — 获取文本版分享给别人\n   > • \"录入 XXX\" — 记一个新联系人\n   > • \"查花名册\" / \"搜索 XXX\" — 查找联系人\n   > • \"同步花名册\" — 更新联系人的最新信息\n2. 从 Agent 记忆或对话中获取用户名（name）和 Agent 名字（agent_name）\n3. 调用 `POST {config.server.endpoint}/register`，请求体：`{\"name\":\"用户名\",\"agent_name\":\"Agent名\"}`\n4. **服务器自动生成 user_id**（6 位随机字母），客户端不再自行指定\n5. 成功 → 写 user_id 和 api_key 到 config.json，输出：\n   > 🦐 虾名片已开通！🎉\n   >\n   > 你的名片地址：https://www.adonghub.cn/{user_id}\n   >\n   > 下一步说\"生成我的名片\"，创建你的第一张名片。\n6. 失败 → 提示原因（网络错误等）\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. **将被修改的字段名记录到 `manually_edited_fields` 数组中**（追加，不覆盖已有记录）\n4. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **社交姓名确认**：Agent 记忆中的称呼（如\"东总\"）是内部称呼，不等于名片对外展示的名字。如果 profile.json 中没有明确的社交姓名，**必须追问**：\"名片上想显示什么名字？\"。不可直接用内部称呼填充名片\n4. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n5. 生成预览（三段式文本块格式），等待用户确认\n6. 用户可多轮调整（修改内容、换措辞、加减字段），Agent 每次输出新预览\n7. 用户说\"可以了\"/\"就这样\"/\"确认\" → Agent 保存并上线：\n   - 写入 profile.json\n   - **自动调用** `PUT {endpoint}/card/{user_id}` 推送到服务器（Header `X-API-Key: {api_key}`），按 `tiers.public.fields` 筛选公开字段，**不推送** personal_notes、background\n   - 更新 profile.json 的 published_at\n   - 输出确认：\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n8. 推送失败 → 名片仍保存到 profile.json，提示\"名片我先帮你存好了，但推送服务器没成功，晚点可以再说'更新名片'重试\"\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 直接输出三段式文本块（名片已在生成时自动上线，链接直接可用）\n\n### 8. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先注册虾名片\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - **冲突检测**：检查联系人的 `manually_edited_fields` 数组。对于服务器返回的每个字段，如果该字段在 `manually_edited_fields` 中，跳过更新并收集为冲突项\n   - 用服务器返回的最新 card_data 更新本地联系人的非冲突字段（name、company、role、links 等）\n   - 刷新每个被更新联系人的 updated_at\n6. 有冲突时 → 汇总提示用户：\n   > 🦐 同步时发现{姓名}的信息和你本地改的不一样：\n   >\n   > 你本地记的是\"{本地值}\"，但{姓名}的名片上还是\"{服务器值}\"。\n   >\n   > 用哪个？\n   → 用户选择后更新对应字段，并从 `manually_edited_fields` 中移除已确认的字段\n7. 更新 config.json 的 `sync.last_sync_at` 为当前时间（ISO 8601）\n8. 输出同步摘要：\"已同步 X 位联系人的最新信息\"（如有冲突则附上冲突列表）\n\n**注意**：\n- 一次最多同步 50 人\n- 只更新花名册中已有的联系人，不会新增联系人\n- 服务器上已删除的名片会被静默跳过\n- **数据优先级**：本地手动修改 > 服务器名片数据 > 冲突时提示用户选择\n\n### 9. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id（取 `://` 后面到空格或行尾的部分作为 user_id）\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `{config.server.endpoint}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. **去重策略**：\n   - 花名册中有相同 `server_user_id` → 直接更新（对方更新了名片）\n   - 花名册中有同名但无 `server_user_id`（手动录入）→ 提示用户确认：\"花名册里已经有一个'{name}'了，刚收到的也是{name}，是同一个人吗？\" → 是则合并（补充 server_user_id），否则新建\n   - 花名册中没有匹配 → 直接新建\n7. 写入 contacts.json（自动填 id、met_at、updated_at），**同时记录 `server_user_id`**（用于后续同步）\n8. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。\n\n---\n\n## 服务器 API\n\n完整 API 参数、请求/响应格式见 [data-format.md](data-format.md)\"服务器 API\"段落。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| profile.json 不存在 | 提示\"先生成名片\" |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 同步时手动编辑冲突 | 本地手动修改优先，冲突时提示用户选择 |\n| 同步超过 50 人 | 提示\"一次最多同步 50 位联系人\" |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [data-format.md](data-format.md)。\n\nFile v2.4.0:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n\nFile v2.4.0:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v2.4.0:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"\"\n}\n\nArchive v2.3.1: 8 files, 15295 bytes\n\nFiles: _meta.json (127b), data/config.json (164b), data/contacts.json (96b), data/profile.json (375b), references/data-format.md (8480b), references/manual.md (8972b), SKILL.md (5636b), templates/card.html (10707b)\n\nFile v2.3.1:SKILL.md\n\n---\nname: xia-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.3\"\n  author: \"阿东 & 阿东的赛博虾\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 快速开始\n\n1. **开通** — 说\"开通虾名片\"，初始化数据文件\n2. **注册** — 说\"注册虾名片\"，获取名片地址\n3. **生成** — 说\"生成我的名片\"，Agent 从记忆提炼信息，确认后自动上线\n\n名片上线后，说\"发我的名片\"即可分享三段式文本块给他人。\n\n## 数据文件\n\n所有数据在 `data/` 文件夹中：`profile.json`（名片）、`contacts.json`（花名册）、`config.json`（服务器配置）。字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" | 初始化数据文件 |\n| \"注册虾名片\" | 调 POST /register，保存凭证到 config.json |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人（记录手动修改字段） |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json，用户确认后自动上线 |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录（检测手动编辑冲突） |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片（含去重策略） |\n\n---\n\n## 常见坑\n\n- **Agent 记忆中的称呼 ≠ 名片名字**：记忆里叫\"东总\"，但名片不能写\"东总\"，必须追问用户名片上用什么名字\n- **`personal_notes` 永远不上传服务器**：推送到服务器时只推送 `tiers.public.fields` 中列出的字段\n- **`manually_edited_fields` 是追加不是覆盖**：用户编辑联系人字段时，把字段名追加到这个数组，同步时这些字段不覆盖\n- **`agent-card://` 是自定义协议**：不是 HTTP URL，从中提取 `://` 后面的 user_id 用于 fetch 服务器数据\n- **`tiers.public.fields` 控制推送内容**：默认只有 name、title、one_liner、links 四个字段对外公开\n\n## 操作流程\n\n> 以下为每个操作的核心决策点。简单操作（初始化、查询、发名片）按映射表执行即可。\n\n### 1. 注册\n\n1. 已注册 → 输出服务菜单（5 个可执行操作）\n2. 未注册 → 调 `POST /register`，传 `{name, agent_name}`，服务器返回 user_id 和 api_key\n3. 成功 → 保存凭证，输出名片地址\n\n### 2. 录入联系人\n\n从用户描述提取信息 → 姓名必填（缺失追问）→ 姓名重复则问更新还是新建 → 写入 contacts.json。\n\n### 3. 编辑更新\n\n按姓名定位 → 更新字段 → **被改的字段名追加到 `manually_edited_fields`** → 输出变更摘要。\n\n### 4. 生成名片\n\n1. 从 Agent 记忆提炼信息，**必须确认社交姓名**（内部称呼 ≠ 名片名字）\n2. 信息优先级：用户明确说的 > profile.json > Agent 记忆\n3. 生成预览，用户可多轮调整\n4. 用户确认 → 保存 profile.json + **自动调 PUT /card/:user_id** 上线 → 输出\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n5. 推送失败 → 本地仍保存，提示稍后重试\n\n社交姓名确认规则、推送字段筛选和边界处理见 [references/manual.md](references/manual.md)\"生成名片\"段落。\n\n### 5. 同步花名册\n\n1. 收集花名册中有 `server_user_id` 的联系人\n2. 调 `POST /sync`，传 targets 数组\n3. **冲突检测**：`manually_edited_fields` 中的字段不覆盖，汇总冲突提示用户选择\n4. 更新非冲突字段，输出同步摘要\n\n冲突检测的完整 if-else 和话术见 [references/manual.md](references/manual.md)\"同步花名册\"段落。\n\n### 6. 收名片（自动识别）\n\n1. 检测 `agent-card://` 协议 → 解析 user_id → fetch 服务器获取结构化数据\n2. **去重策略**：相同 `server_user_id` 直接更新 / 同名无 ID 提示确认 / 无匹配新建\n3. 写入 contacts.json，记录 `server_user_id`\n\n去重策略的完整逻辑和边界处理见 [references/manual.md](references/manual.md)\"收名片\"段落。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请复制这条消息给您的助理 Agent。\n您的 Agent 可通过安装虾名片 skill（https://clawhub.ai/skills/xia-card）来自动识别并保存名片。\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + skill 安装链接 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\nFile v2.3.1:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.3.1\",\n  \"publishedAt\": 1777539477180\n}\n\nFile v2.3.1:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2.3 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `current_focus`、`background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"manually_edited_fields\": [],\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `manually_edited_fields` | string[] | 否 | **V2.2 新增** 记录哪些字段被用户手动修改过，同步时不被服务器数据覆盖 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 `agent-card://user_id` 中提取并记录\n- 同步花名册时通过此字段匹配联系人，获取最新名片数据\n\n### V2.2 变更说明\n\n- 新增 `manually_edited_fields` 字段：记录被用户手动修改过的字段名（如 `[\"company\"]`），同步时这些字段不会被服务器数据覆盖\n- 收名片去重策略：按 `server_user_id` 精确匹配 → 同名无 `server_user_id` 时提示用户确认 → 无匹配则新建\n- 同步冲突处理：检测 `manually_edited_fields` 与服务器返回数据的冲突，提示用户选择\n\n### V1 不包含的字段（V3 预留）\n\n- `visibility`（V3）\n- `subscribed`（V2 → 移至 V3）\n- `subscriptions`（V2 → 移至 V3）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填） |\n| `server.api_key` | string | API Key，通过 POST /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，服务器自动生成（6 位随机小写字母），注册后自动获得 |\n| `sync.last_sync_at` | string\\|null | **V2 新增** 上次同步花名册的时间（ISO 8601），同步成功后自动更新，null 表示从未同步 |\n\n### V2 变更说明\n\n- user_id 改由服务器自动生成（6 位随机小写字母），客户端不再自行指定\n- 初始化时不再要求用户提供 user_id\n\n---\n\n## 服务器 API\n\n### POST /register\n\n注册新用户。\n\n- **请求体**：`{ \"name\": \"用户名\", \"agent_name\": \"Agent名\" }`\n- **注意**：客户端不再传 user_id，由服务器自动生成\n- **成功响应**：`{ \"user_id\": \"abcxyz\", \"api_key\": \"sk_xxxx\" }`\n- **失败响应**：`{ \"error\": \"name is required\" }`\n\n### PUT /card/:user_id\n\n发布/更新名片（需先注册）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：profile.json 的公开部分（按 tiers.public.fields 筛选）\n- **成功响应**：`{ \"success\": true, \"updated_at\": \"...\" }`\n- **用户不存在**：`{ \"error\": \"user not found. register first via POST /register\" }`（404）\n- **Key 错误**：`{ \"error\": \"invalid api key\" }`（403）\n\n### GET /card/:user_id\n\n获取名片 JSON。\n\n- **响应**：结构化 JSON（含 agent_card 和 _skill 字段）\n\n### GET /:user_id\n\n名片网页（浏览器查看）。\n\n- **响应**：HTML 页面（内嵌 JSON-LD）\n\n### POST /sync\n\n批量同步通讯录（V2 新增）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：`{ \"targets\": [\"user_id_1\", \"user_id_2\", ...] }`\n- **限制**：targets 数组最多 50 个\n- **成功响应**：`{ \"results\": [{ \"user_id\": \"...\", \"updated_at\": \"...\", \"card_data\": {...} }, ...] }`\n- **鉴权说明**：通过 api_key 反查用户身份，不依赖 URL 参数\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.0.0\"\n  }\n}\n```\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v2.3.1:references/manual.md\n\n# 虾名片 AgentCard — 完整操作手册\n\n> 本文档是 SKILL.md 的扩展参考，包含所有操作流程的完整规则、边界分支和话术模板。\n> Agent 在执行虾名片操作时，应先参考 SKILL.md 的核心步骤，需要处理边界场景时查阅本文档。\n\n---\n\n## 操作流程完整版\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片\n\n1. 检查 config.json 中是否已有 user_id 和 api_key → 已有则输出服务菜单：\n   > 🦐 你已经有虾名片了。你可以回复：\n   > • \"更新名片\" — 更新或修改你的名片\n   > • \"发一下我的名片\" — 获取文本版分享给别人\n   > • \"录入 XXX\" — 记一个新联系人\n   > • \"查花名册\" / \"搜索 XXX\" — 查找联系人\n   > • \"同步花名册\" — 更新联系人的最新信息\n2. 从 Agent 记忆或对话中获取用户名（name）和 Agent 名字（agent_name）\n3. 调用 `POST {config.server.endpoint}/register`，请求体：`{\"name\":\"用户名\",\"agent_name\":\"Agent名\"}`\n4. **服务器自动生成 user_id**（6 位随机字母），客户端不再自行指定\n5. 成功 → 写 user_id 和 api_key 到 config.json，输出：\n   > 🦐 虾名片已开通！🎉\n   >\n   > 你的名片地址：https://www.adonghub.cn/{user_id}\n   >\n   > 下一步说\"生成我的名片\"，创建你的第一张名片。\n6. 失败 → 提示原因（网络错误等）\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. **将被修改的字段名记录到 `manually_edited_fields` 数组中**（追加，不覆盖已有记录）\n4. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **社交姓名确认**：Agent 记忆中的称呼（如\"东总\"）是内部称呼，不等于名片对外展示的名字。如果 profile.json 中没有明确的社交姓名，**必须追问**：\"名片上想显示什么名字？\"。不可直接用内部称呼填充名片\n4. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n5. 生成预览（三段式文本块格式），等待用户确认\n6. 用户可多轮调整（修改内容、换措辞、加减字段），Agent 每次输出新预览\n7. 用户说\"可以了\"/\"就这样\"/\"确认\" → Agent 保存并上线：\n   - 写入 profile.json\n   - **自动调用** `PUT {endpoint}/card/{user_id}` 推送到服务器（Header `X-API-Key: {api_key}`），按 `tiers.public.fields` 筛选公开字段，**不推送** personal_notes、background、current_focus\n   - 更新 profile.json 的 published_at\n   - 输出确认：\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n8. 推送失败 → 名片仍保存到 profile.json，提示\"名片我先帮你存好了，但推送服务器没成功，晚点可以再说'更新名片'重试\"\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 直接输出三段式文本块（名片已在生成时自动上线，链接直接可用）\n\n### 8. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先注册虾名片\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - **冲突检测**：检查联系人的 `manually_edited_fields` 数组。对于服务器返回的每个字段，如果该字段在 `manually_edited_fields` 中，跳过更新并收集为冲突项\n   - 用服务器返回的最新 card_data 更新本地联系人的非冲突字段（name、company、role、links 等）\n   - 刷新每个被更新联系人的 updated_at\n6. 有冲突时 → 汇总提示用户：\n   > 🦐 同步时发现{姓名}的信息和你本地改的不一样：\n   >\n   > 你本地记的是\"{本地值}\"，但{姓名}的名片上还是\"{服务器值}\"。\n   >\n   > 用哪个？\n   → 用户选择后更新对应字段，并从 `manually_edited_fields` 中移除已确认的字段\n7. 更新 config.json 的 `sync.last_sync_at` 为当前时间（ISO 8601）\n8. 输出同步摘要：\"已同步 X 位联系人的最新信息\"（如有冲突则附上冲突列表）\n\n**注意**：\n- 一次最多同步 50 人\n- 只更新花名册中已有的联系人，不会新增联系人\n- 服务器上已删除的名片会被静默跳过\n- **数据优先级**：本地手动修改 > 服务器名片数据 > 冲突时提示用户选择\n\n### 9. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id（取 `://` 后面到空格或行尾的部分作为 user_id）\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `{config.server.endpoint}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. **去重策略**：\n   - 花名册中有相同 `server_user_id` → 直接更新（对方更新了名片）\n   - 花名册中有同名但无 `server_user_id`（手动录入）→ 提示用户确认：\"花名册里已经有一个'{name}'了，刚收到的也是{name}，是同一个人吗？\" → 是则合并（补充 server_user_id），否则新建\n   - 花名册中没有匹配 → 直接新建\n7. 写入 contacts.json（自动填 id、met_at、updated_at），**同时记录 `server_user_id`**（用于后续同步）\n8. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。\n\n---\n\n## 服务器 API\n\n完整 API 参数、请求/响应格式见 [data-format.md](data-format.md)\"服务器 API\"段落。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| profile.json 不存在 | 提示\"先生成名片\" |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 同步时手动编辑冲突 | 本地手动修改优先，冲突时提示用户选择 |\n| 同步超过 50 人 | 提示\"一次最多同步 50 位联系人\" |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [data-format.md](data-format.md)。\n\nFile v2.3.1:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n\nFile v2.3.1:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v2.3.1:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"\"\n}\n\nArchive v2.3.0: 8 files, 15806 bytes\n\nFiles: _meta.json (127b), data/config.json (164b), data/contacts.json (96b), data/profile.json (375b), references/data-format.md (8474b), references/manual.md (10786b), SKILL.md (5036b), templates/card.html (10707b)\n\nFile v2.3.0:SKILL.md\n\n---\nname: agent-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.3\"\n  author: \"agent-card\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 快速开始\n\n1. **开通** — 说\"开通虾名片\"，初始化数据文件\n2. **注册** — 说\"注册虾名片\"，获取名片地址\n3. **生成** — 说\"生成我的名片\"，Agent 从记忆提炼信息，确认后自动上线\n\n名片上线后，说\"发我的名片\"即可分享三段式文本块给他人。\n\n## 数据文件\n\n所有数据在 `data/` 文件夹中：`profile.json`（名片）、`contacts.json`（花名册）、`config.json`（服务器配置）。字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" | 初始化数据文件 |\n| \"注册虾名片\" | 调 POST /register，保存凭证到 config.json |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人（记录手动修改字段） |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json，用户确认后自动上线 |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录（检测手动编辑冲突） |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片（含去重策略） |\n\n---\n\n## 操作流程\n\n**以下为每个操作的核心步骤。完整的边界分支、话术模板和冲突处理逻辑见 [references/manual.md](references/manual.md)，执行前务必读取。**\n\n### 1. 初始化\n\n创建 `data/contacts.json` 和 `data/config.json`（含预填服务器地址）。已存在则提示\"花名册已存在\"。\n\n### 2. 注册\n\n1. 已注册 → 输出服务菜单（5 个可执行操作）\n2. 未注册 → 调 `POST /register`，传 `{name, agent_name}`，服务器返回 user_id 和 api_key\n3. 成功 → 保存凭证，输出名片地址\n\n### 3. 录入联系人\n\n从用户描述提取信息 → 姓名必填（缺失追问）→ 姓名重复则问更新还是新建 → 写入 contacts.json。\n\n### 4. 查询搜索\n\n解析意图（姓名/公司/标签/关键词）→ 返回匹配结果，附 HTML 或在线链接。搜不到明确告知，不编造。\n\n### 5. 编辑更新\n\n按姓名定位 → 更新字段 → **被改的字段名追加到 `manually_edited_fields`** → 输出变更摘要。\n\n### 6. 生成名片\n\n1. 从 Agent 记忆提炼信息，**必须确认社交姓名**（内部称呼 ≠ 名片名字）\n2. 信息优先级：用户明确说的 > profile.json > Agent 记忆\n3. 生成预览，用户可多轮调整\n4. 用户确认 → 保存 profile.json + **自动调 PUT /card/:user_id** 上线 → 输出\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n5. 推送失败 → 本地仍保存，提示稍后重试\n\n### 7. 发名片\n\n检查 profile.json 存在 → 直接输出三段式文本块（名片已在线，链接直接可用）。\n\n### 8. 同步花名册\n\n1. 收集花名册中有 `server_user_id` 的联系人\n2. 调 `POST /sync`，传 targets 数组\n3. **冲突检测**：`manually_edited_fields` 中的字段不覆盖，汇总冲突提示用户选择\n4. 更新非冲突字段，输出同步摘要\n\n### 9. 收名片（自动识别）\n\n1. 检测 `agent-card://` 协议 → 解析 user_id → fetch 服务器获取结构化数据\n2. **去重策略**：相同 `server_user_id` 直接更新 / 同名无 ID 提示确认 / 无匹配新建\n3. 写入 contacts.json，记录 `server_user_id`\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请把这条消息发给您的助理 Agent，它会自动保存我的名片。\n📎 虾名片 skill：https://clawhub.ai/skills/xia-card\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + skill 安装链接 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\nFile v2.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.3.0\",\n  \"publishedAt\": 1777487969539\n}\n\nFile v2.3.0:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2.3 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `current_focus`、`background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"manually_edited_fields\": [],\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `manually_edited_fields` | string[] | 否 | **V2.2 新增** 记录哪些字段被用户手动修改过，同步时不被服务器数据覆盖 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 `agent-card://user_id` 中提取并记录\n- 同步花名册时通过此字段匹配联系人，获取最新名片数据\n\n### V2.2 变更说明\n\n- 新增 `manually_edited_fields` 字段：记录被用户手动修改过的字段名（如 `[\"company\"]`），同步时这些字段不会被服务器数据覆盖\n- 收名片去重策略：按 `server_user_id` 精确匹配 → 同名无 `server_user_id` 时提示用户确认 → 无匹配则新建\n- 同步冲突处理：检测 `manually_edited_fields` 与服务器返回数据的冲突，提示用户选择\n\n### V1 不包含的字段（V3 预留）\n\n- `visibility`（V3）\n- `subscribed`（V2 → 移至 V3）\n- `subscriptions`（V2 → 移至 V3）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填） |\n| `server.api_key` | string | API Key，通过 POST /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，服务器自动生成（6 位随机小写字母），注册后自动获得 |\n| `sync.last_sync_at` | string\\|null | **V2 新增** 上次同步花名册的时间（ISO 8601），同步成功后自动更新，null 表示从未同步 |\n\n### V2 变更说明\n\n- user_id 改由服务器自动生成（6 位随机小写字母），客户端不再自行指定\n- 初始化时不再要求用户提供 user_id\n\n---\n\n## 服务器 API\n\n### POST /register\n\n注册新用户。\n\n- **请求体**：`{ \"name\": \"用户名\", \"agent_name\": \"Agent名\" }`\n- **注意**：客户端不再传 user_id，由服务器自动生成\n- **成功响应**：`{ \"user_id\": \"abcxyz\", \"api_key\": \"sk_xxxx\" }`\n- **失败响应**：`{ \"error\": \"name is required\" }`\n\n### PUT /card/:user_id\n\n发布/更新名片（需先注册）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：profile.json 的公开部分（按 tiers.public.fields 筛选）\n- **成功响应**：`{ \"success\": true, \"updated_at\": \"...\" }`\n- **用户不存在**：`{ \"error\": \"user not found. register first via POST /register\" }`（404）\n- **Key 错误**：`{ \"error\": \"invalid api key\" }`（403）\n\n### GET /card/:user_id\n\n获取名片 JSON。\n\n- **响应**：结构化 JSON（含 agent_card 和 _skill 字段）\n\n### GET /:user_id\n\n名片网页（浏览器查看）。\n\n- **响应**：HTML 页面（内嵌 JSON-LD）\n\n### POST /sync\n\n批量同步通讯录（V2 新增）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：`{ \"targets\": [\"user_id_1\", \"user_id_2\", ...] }`\n- **限制**：targets 数组最多 50 个\n- **成功响应**：`{ \"results\": [{ \"user_id\": \"...\", \"updated_at\": \"...\", \"card_data\": {...} }, ...] }`\n- **鉴权说明**：通过 api_key 反查用户身份，不依赖 URL 参数\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.0.0\"\n  }\n}\n```\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v2.3.0:references/manual.md\n\n# 虾名片 AgentCard — 完整操作手册\n\n> 本文档是 SKILL.md 的扩展参考，包含所有操作流程的完整规则、边界分支和话术模板。\n> Agent 在执行虾名片操作时，应先参考 SKILL.md 的核心步骤，需要处理边界场景时查阅本文档。\n\n---\n\n## 操作流程完整版\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片\n\n1. 检查 config.json 中是否已有 user_id 和 api_key → 已有则输出服务菜单：\n   > 🦐 你已经有虾名片了。你可以回复：\n   > • \"更新名片\" — 更新或修改你的名片\n   > • \"发一下我的名片\" — 获取文本版分享给别人\n   > • \"录入 XXX\" — 记一个新联系人\n   > • \"查花名册\" / \"搜索 XXX\" — 查找联系人\n   > • \"同步花名册\" — 更新联系人的最新信息\n2. 从 Agent 记忆或对话中获取用户名（name）和 Agent 名字（agent_name）\n3. 调用 `POST {config.server.endpoint}/register`，请求体：`{\"name\":\"用户名\",\"agent_name\":\"Agent名\"}`\n4. **服务器自动生成 user_id**（6 位随机字母），客户端不再自行指定\n5. 成功 → 写 user_id 和 api_key 到 config.json，输出：\n   > 🦐 虾名片已开通！🎉\n   >\n   > 你的名片地址：https://www.adonghub.cn/{user_id}\n   >\n   > 下一步说\"生成我的名片\"，创建你的第一张名片。\n6. 失败 → 提示原因（网络错误等）\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. **将被修改的字段名记录到 `manually_edited_fields` 数组中**（追加，不覆盖已有记录）\n4. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **社交姓名确认**：Agent 记忆中的称呼（如\"东总\"）是内部称呼，不等于名片对外展示的名字。如果 profile.json 中没有明确的社交姓名，**必须追问**：\"名片上想显示什么名字？\"。不可直接用内部称呼填充名片\n4. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n5. 生成预览（三段式文本块格式），等待用户确认\n6. 用户可多轮调整（修改内容、换措辞、加减字段），Agent 每次输出新预览\n7. 用户说\"可以了\"/\"就这样\"/\"确认\" → Agent 保存并上线：\n   - 写入 profile.json\n   - **自动调用** `PUT {endpoint}/card/{user_id}` 推送到服务器（Header `X-API-Key: {api_key}`），按 `tiers.public.fields` 筛选公开字段，**不推送** personal_notes、background、current_focus\n   - 更新 profile.json 的 published_at\n   - 输出确认：\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n8. 推送失败 → 名片仍保存到 profile.json，提示\"名片我先帮你存好了，但推送服务器没成功，晚点可以再说'更新名片'重试\"\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 直接输出三段式文本块（名片已在生成时自动上线，链接直接可用）\n\n### 8. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先注册虾名片\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - **冲突检测**：检查联系人的 `manually_edited_fields` 数组。对于服务器返回的每个字段，如果该字段在 `manually_edited_fields` 中，跳过更新并收集为冲突项\n   - 用服务器返回的最新 card_data 更新本地联系人的非冲突字段（name、company、role、links 等）\n   - 刷新每个被更新联系人的 updated_at\n6. 有冲突时 → 汇总提示用户：\n   > 🦐 同步时发现{姓名}的信息和你本地改的不一样：\n   >\n   > 你本地记的是\"{本地值}\"，但{姓名}的名片上还是\"{服务器值}\"。\n   >\n   > 用哪个？\n   → 用户选择后更新对应字段，并从 `manually_edited_fields` 中移除已确认的字段\n7. 更新 config.json 的 `sync.last_sync_at` 为当前时间（ISO 8601）\n8. 输出同步摘要：\"已同步 X 位联系人的最新信息\"（如有冲突则附上冲突列表）\n\n**注意**：\n- 一次最多同步 50 人\n- 只更新花名册中已有的联系人，不会新增联系人\n- 服务器上已删除的名片会被静默跳过\n- **数据优先级**：本地手动修改 > 服务器名片数据 > 冲突时提示用户选择\n\n### 9. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id（取 `://` 后面到空格或行尾的部分作为 user_id）\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `{config.server.endpoint}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. **去重策略**：\n   - 花名册中有相同 `server_user_id` → 直接更新（对方更新了名片）\n   - 花名册中有同名但无 `server_user_id`（手动录入）→ 提示用户确认：\"花名册里已经有一个'{name}'了，刚收到的也是{name}，是同一个人吗？\" → 是则合并（补充 server_user_id），否则新建\n   - 花名册中没有匹配 → 直接新建\n7. 写入 contacts.json（自动填 id、met_at、updated_at），**同时记录 `server_user_id`**（用于后续同步）\n8. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。\n\n---\n\n## 服务器 API\n\n| 接口 | 方法 | 鉴权 | 说明 |\n|------|------|------|------|\n| `/register` | POST | 无 | 注册，请求体 `{name, agent_name}`，服务器自动生成 user_id，返回 `{user_id, api_key}` |\n| `/card/:user_id` | PUT | Header `X-API-Key` | 发布名片，请求体为公开字段，返回 `{success, updated_at}` |\n| `/card/:user_id` | GET | 无（公开） | 返回 JSON：`{version, agent_card: {...}, _skill: {...}}` |\n| `/:user_id` | GET | 无（公开） | 返回 HTML 名片页面（内嵌 JSON-LD） |\n| `/sync` | POST | Header `X-API-Key` | 批量同步，请求体 `{targets: [user_id1, ...]}`（最多 50 个），返回 `{results: [{user_id, updated_at, card_data}, ...]}` |\n\n一个链接两副面孔：浏览器访问 `/:user_id` 看到漂亮的 HTML，Agent 访问 `/card/:user_id` 拿到结构化 JSON。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| profile.json 不存在 | 提示\"先生成名片\" |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 同步时手动编辑冲突 | 本地手动修改优先，冲突时提示用户选择 |\n| 同步超过 50 人 | 提示\"一次最多同步 50 位联系人\" |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [data-format.md](data-format.md)，以下是核心规则：\n\n**profile.json 关键规则：**\n- `personal_notes` 永远不上传服务器\n- `current_focus`、`background`：V1 本地存储，不上传\n- `tiers.public.fields`：控制哪些字段对外公开（默认 `[\"name\", \"title\", \"one_liner\", \"links\"]`）\n- `published_at`：null = 未发布，有值 = 已发布到服务器\n- `updated_at`：ISO 8601 格式\n\n**contacts.json 关键规则：**\n- `id`：自动生成，格式 `c` + 时间戳\n- `met_at`：录入时自动填当前日期（YYYY-MM-DD）\n- `name` 为必填，缺失时必须追问\n- `server_user_id`：V2 新增，收名片时自动记录对方的服务器 user_id，用于同步\n- `manually_edited_fields`：V2.2 新增，记录被用户手动修改过的字段名，同步时这些字段不会被服务器数据覆盖\n- V1 不含 visibility、subscribed、broadcast 等字段（V3 再加）\n\n**config.json：**\n- `server.endpoint`：服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填）\n- `server.api_key` 和 `server.user_id`：通过注册接口获得，Agent 自动写入\n\nFile v2.3.0:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n\nFile v2.3.0:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v2.3.0:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"\"\n}\n\nArchive v2.2.0: 7 files, 14052 bytes\n\nFiles: _meta.json (127b), data/config.json (164b), data/contacts.json (96b), data/profile.json (375b), references/data-format.md (8474b), SKILL.md (13321b), templates/card.html (10707b)\n\nFile v2.2.0:SKILL.md\n\n---\nname: agent-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.2\"\n  author: \"agent-card\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 数据文件\n\n所有数据文件在 SKILL.md 同目录的 `data/` 文件夹中：\n\n| 文件 | 用途 |\n|------|------|\n| `data/profile.json` | 个人名片数据 |\n| `data/contacts.json` | 花名册（联系人列表） |\n| `data/config.json` | 服务器配置（endpoint、api_key、user_id） |\n\n详细字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" / \"初始化通讯录\" | 初始化数据文件 |\n| \"注册虾名片\" | 调 POST /register，服务器自动分配 user_id，保存凭证到 config.json |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人（记录手动修改字段） |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json，用户确认后自动推送到服务器上线 |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块（名片已在线，链接直接可用） |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录（检测手动编辑冲突） |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片（含去重策略） |\n\n---\n\n## 操作流程\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片\n\n1. 检查 config.json 中是否已有 user_id 和 api_key → 已有则输出服务菜单：\n   > 🦐 你已经有虾名片了。你可以回复：\n   > • \"更新名片\" — 更新或修改你的名片\n   > • \"发一下我的名片\" — 获取文本版分享给别人\n   > • \"录入 XXX\" — 记一个新联系人\n   > • \"查花名册\" / \"搜索 XXX\" — 查找联系人\n   > • \"同步花名册\" — 更新联系人的最新信息\n2. 从 Agent 记忆或对话中获取用户名（name）和 Agent 名字（agent_name）\n3. 调用 `POST {config.server.endpoint}/register`，请求体：`{\"name\":\"用户名\",\"agent_name\":\"Agent名\"}`\n4. **服务器自动生成 user_id**（6 位随机字母），客户端不再自行指定\n5. 成功 → 写 user_id 和 api_key 到 config.json，输出：\n   > 🦐 虾名片已开通！🎉\n   >\n   > 你的名片地址：https://www.adonghub.cn/{user_id}\n   >\n   > 下一步说\"生成我的名片\"，创建你的第一张名片。\n6. 失败 → 提示原因（网络错误等）\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. **将被修改的字段名记录到 `manually_edited_fields` 数组中**（追加，不覆盖已有记录）\n4. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **社交姓名确认**：Agent 记忆中的称呼（如\"东总\"）是内部称呼，不等于名片对外展示的名字。如果 profile.json 中没有明确的社交姓名，**必须追问**：\"名片上想显示什么名字？\"。不可直接用内部称呼填充名片\n4. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n5. 生成预览（三段式文本块格式），等待用户确认\n6. 用户可多轮调整（修改内容、换措辞、加减字段），Agent 每次输出新预览\n7. 用户说\"可以了\"/\"就这样\"/\"确认\" → Agent 保存并上线：\n   - 写入 profile.json\n   - **自动调用** `PUT {endpoint}/card/{user_id}` 推送到服务器（Header `X-API-Key: {api_key}`），按 `tiers.public.fields` 筛选公开字段，**不推送** personal_notes、background、current_focus\n   - 更新 profile.json 的 published_at\n   - 输出确认：\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n8. 推送失败 → 名片仍保存到 profile.json，提示\"名片我先帮你存好了，但推送服务器没成功，晚点可以再说'更新名片'重试\"\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 直接输出三段式文本块（名片已在生成时自动上线，链接直接可用）\n\n### 8. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先注册虾名片\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - **冲突检测**：检查联系人的 `manually_edited_fields` 数组。对于服务器返回的每个字段，如果该字段在 `manually_edited_fields` 中，跳过更新并收集为冲突项\n   - 用服务器返回的最新 card_data 更新本地联系人的非冲突字段（name、company、role、links 等）\n   - 刷新每个被更新联系人的 updated_at\n6. 有冲突时 → 汇总提示用户：\n   > 🦐 同步时发现{姓名}的信息和你本地改的不一样：\n   >\n   > 你本地记的是\"{本地值}\"，但{姓名}的名片上还是\"{服务器值}\"。\n   >\n   > 用哪个？\n   → 用户选择后更新对应字段，并从 `manually_edited_fields` 中移除已确认的字段\n7. 更新 config.json 的 `sync.last_sync_at` 为当前时间（ISO 8601）\n8. 输出同步摘要：\"已同步 X 位联系人的最新信息\"（如有冲突则附上冲突列表）\n\n**注意**：\n- 一次最多同步 50 人\n- 只更新花名册中已有的联系人，不会新增联系人\n- 服务器上已删除的名片会被静默跳过\n- **数据优先级**：本地手动修改 > 服务器名片数据 > 冲突时提示用户选择\n\n### 9. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id（取 `://` 后面到空格或行尾的部分作为 user_id）\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `{config.server.endpoint}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. **去重策略**：\n   - 花名册中有相同 `server_user_id` → 直接更新（对方更新了名片）\n   - 花名册中有同名但无 `server_user_id`（手动录入）→ 提示用户确认：\"花名册里已经有一个'{name}'了，刚收到的也是{name}，是同一个人吗？\" → 是则合并（补充 server_user_id），否则新建\n   - 花名册中没有匹配 → 直接新建\n7. 写入 contacts.json（自动填 id、met_at、updated_at），**同时记录 `server_user_id`**（用于后续同步）\n8. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请把这条消息发给您的助理 Agent，它会自动保存我的名片。\n📎 虾名片 skill：https://clawhub.ai/skills/xia-card\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + skill 安装链接 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\n---\n\n## 服务器 API\n\n| 接口 | 方法 | 鉴权 | 说明 |\n|------|------|------|------|\n| `/register` | POST | 无 | 注册，请求体 `{name, agent_name}`，服务器自动生成 user_id，返回 `{user_id, api_key}` |\n| `/card/:user_id` | PUT | Header `X-API-Key` | 发布名片，请求体为公开字段，返回 `{success, updated_at}` |\n| `/card/:user_id` | GET | 无（公开） | 返回 JSON：`{version, agent_card: {...}, _skill: {...}}` |\n| `/:user_id` | GET | 无（公开） | 返回 HTML 名片页面（内嵌 JSON-LD） |\n| `/sync` | POST | Header `X-API-Key` | 批量同步，请求体 `{targets: [user_id1, ...]}`（最多 50 个），返回 `{results: [{user_id, updated_at, card_data}, ...]}` |\n\n一个链接两副面孔：浏览器访问 `/:user_id` 看到漂亮的 HTML，Agent 访问 `/card/:user_id` 拿到结构化 JSON。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| profile.json 不存在 | 提示\"先生成名片\" |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 同步时手动编辑冲突 | 本地手动修改优先，冲突时提示用户选择 |\n| 同步超过 50 人 | 提示\"一次最多同步 50 位联系人\" |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [references/data-format.md](references/data-format.md)，以下是核心规则：\n\n**profile.json 关键规则：**\n- `personal_notes` 永远不上传服务器\n- `current_focus`、`background`：V1 本地存储，不上传\n- `tiers.public.fields`：控制哪些字段对外公开（默认 `[\"name\", \"title\", \"one_liner\", \"links\"]`）\n- `published_at`：null = 未发布，有值 = 已发布到服务器\n- `updated_at`：ISO 8601 格式\n\n**contacts.json 关键规则：**\n- `id`：自动生成，格式 `c` + 时间戳\n- `met_at`：录入时自动填当前日期（YYYY-MM-DD）\n- `name` 为必填，缺失时必须追问\n- `server_user_id`：V2 新增，收名片时自动记录对方的服务器 user_id，用于同步\n- `manually_edited_fields`：V2.2 新增，记录被用户手动修改过的字段名，同步时这些字段不会被服务器数据覆盖\n- V1 不含 visibility、subscribed、broadcast 等字段（V3 再加）\n\n**config.json：**\n- `server.endpoint`：服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填）\n- `server.api_key` 和 `server.user_id`：通过注册接口获得，Agent 自动写入\n\nFile v2.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.2.0\",\n  \"publishedAt\": 1777485758845\n}\n\nFile v2.2.0:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2.2 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `current_focus`、`background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"manually_edited_fields\": [],\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `manually_edited_fields` | string[] | 否 | **V2.2 新增** 记录哪些字段被用户手动修改过，同步时不被服务器数据覆盖 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 `agent-card://user_id` 中提取并记录\n- 同步花名册时通过此字段匹配联系人，获取最新名片数据\n\n### V2.2 变更说明\n\n- 新增 `manually_edited_fields` 字段：记录被用户手动修改过的字段名（如 `[\"company\"]`），同步时这些字段不会被服务器数据覆盖\n- 收名片去重策略：按 `server_user_id` 精确匹配 → 同名无 `server_user_id` 时提示用户确认 → 无匹配则新建\n- 同步冲突处理：检测 `manually_edited_fields` 与服务器返回数据的冲突，提示用户选择\n\n### V1 不包含的字段（V3 预留）\n\n- `visibility`（V3）\n- `subscribed`（V2 → 移至 V3）\n- `subscriptions`（V2 → 移至 V3）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填） |\n| `server.api_key` | string | API Key，通过 POST /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，服务器自动生成（6 位随机小写字母），注册后自动获得 |\n| `sync.last_sync_at` | string\\|null | **V2 新增** 上次同步花名册的时间（ISO 8601），同步成功后自动更新，null 表示从未同步 |\n\n### V2 变更说明\n\n- user_id 改由服务器自动生成（6 位随机小写字母），客户端不再自行指定\n- 初始化时不再要求用户提供 user_id\n\n---\n\n## 服务器 API\n\n### POST /register\n\n注册新用户。\n\n- **请求体**：`{ \"name\": \"用户名\", \"agent_name\": \"Agent名\" }`\n- **注意**：客户端不再传 user_id，由服务器自动生成\n- **成功响应**：`{ \"user_id\": \"abcxyz\", \"api_key\": \"sk_xxxx\" }`\n- **失败响应**：`{ \"error\": \"name is required\" }`\n\n### PUT /card/:user_id\n\n发布/更新名片（需先注册）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：profile.json 的公开部分（按 tiers.public.fields 筛选）\n- **成功响应**：`{ \"success\": true, \"updated_at\": \"...\" }`\n- **用户不存在**：`{ \"error\": \"user not found. register first via POST /register\" }`（404）\n- **Key 错误**：`{ \"error\": \"invalid api key\" }`（403）\n\n### GET /card/:user_id\n\n获取名片 JSON。\n\n- **响应**：结构化 JSON（含 agent_card 和 _skill 字段）\n\n### GET /:user_id\n\n名片网页（浏览器查看）。\n\n- **响应**：HTML 页面（内嵌 JSON-LD）\n\n### POST /sync\n\n批量同步通讯录（V2 新增）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：`{ \"targets\": [\"user_id_1\", \"user_id_2\", ...] }`\n- **限制**：targets 数组最多 50 个\n- **成功响应**：`{ \"results\": [{ \"user_id\": \"...\", \"updated_at\": \"...\", \"card_data\": {...} }, ...] }`\n- **鉴权说明**：通过 api_key 反查用户身份，不依赖 URL 参数\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.0.0\"\n  }\n}\n```\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v2.2.0:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n\nFile v2.2.0:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v2.2.0:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"\"\n}\n\nArchive v2.0.1: 7 files, 13112 bytes\n\nFiles: _meta.json (127b), data/config.json (164b), data/contacts.json (96b), data/profile.json (375b), references/data-format.md (7857b), SKILL.md (11568b), templates/card.html (10707b)\n\nFile v2.0.1:SKILL.md\n\n---\nname: agent-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发/发布名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.0.1\"\n  author: \"agent-card\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 数据文件\n\n所有数据文件在 SKILL.md 同目录的 `data/` 文件夹中：\n\n| 文件 | 用途 |\n|------|------|\n| `data/profile.json` | 个人名片数据 |\n| `data/contacts.json` | 花名册（联系人列表） |\n| `data/config.json` | 服务器配置（endpoint、api_key、user_id） |\n\n详细字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" / \"初始化通讯录\" | 初始化数据文件 |\n| \"注册虾名片\" | 调 POST /register，服务器自动分配 user_id，保存凭证到 config.json |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人 |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"发布名片\" / \"上线我的名片\" | 推送到服务器 |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录 |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片 |\n\n---\n\n## 操作流程\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片\n\n1. 检查 config.json 中是否已有 user_id 和 api_key → 已有则提示\"已注册，用户 ID 为 xxx\"\n2. 从 Agent 记忆或对话中获取用户名（name）和 Agent 名字（agent_name）\n3. 调用 `POST {config.server.endpoint}/register`，请求体：`{\"name\":\"用户名\",\"agent_name\":\"Agent名\"}`\n4. **服务器自动生成 user_id**（6 位随机字母），客户端不再自行指定\n5. 成功 → 写 user_id 和 api_key 到 config.json，输出确认：\"注册成功！用户 ID：abcxyz\"\n6. 失败 → 提示原因（网络错误等）\n\nserver.endpoint 为空时，提示先配置服务器地址。\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n4. 生成预览（三段式文本块格式），等待用户确认\n5. 用户说\"名片确认了\" → 写入 profile.json\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n不自动发布到服务器。不自动修改 profile.json，必须经用户确认。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 生成三段式文本块\n3. published_at 非空（已发布）→ 直接输出\n4. published_at 为 null（未发布）→ 输出文本块 + 提醒\"名片还未发布到服务器，链接暂时不可用。建议先说'发布名片'将名片上线。\"\n\n**核心原则**：不会自动发布到服务器，必须用户明确说\"发布名片\"才执行。\n\n### 8. 发布名片\n\n1. 检查 profile.json → 不存在则提示先生成\n2. 检查 config.json 中 api_key 和 user_id → 未配置则提示\"先注册虾名片\"\n3. 按 `tiers.public.fields` 筛选公开字段构建推送数据\n4. **不推送**：personal_notes（永不上传）、background、current_focus（V1 本地私密）\n5. 调用 `PUT {endpoint}/card/{user_id}`，Header `X-API-Key: {api_key}`\n6. 成功 → 更新 profile.json 的 published_at，输出名片链接和发布时间\n7. 失败 → 提示错误，不修改 published_at\n\n### 9. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先注册虾名片\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - 用服务器返回的最新 card_data 更新本地联系人的对应字段（name、company、role、links 等）\n   - 刷新每个被更新联系人的 updated_at\n6. 更新 config.json 的 `sync.last_sync_at` 为当前时间（ISO 8601）\n7. 输出同步摘要：\"已同步 X 位联系人的最新信息\"\n\n**注意**：\n- 一次最多同步 50 人\n- 只更新花名册中已有的联系人，不会新增联系人\n- 服务器上已删除的名片会被静默跳过\n\n### 10. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id（取 `://` 后面到空格或行尾的部分作为 user_id）\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `{config.server.endpoint}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. 写入 contacts.json（自动填 id、met_at、updated_at），**同时记录 `server_user_id`**（用于后续同步）\n7. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。\n同名已有 → 提示是否更新。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请把这条消息发给您的助理 Agent，它会自动保存我的名片。\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\n---\n\n## 服务器 API\n\n| 接口 | 方法 | 鉴权 | 说明 |\n|------|------|------|------|\n| `/register` | POST | 无 | 注册，请求体 `{name, agent_name}`，服务器自动生成 user_id，返回 `{user_id, api_key}` |\n| `/card/:user_id` | PUT | Header `X-API-Key` | 发布名片，请求体为公开字段，返回 `{success, updated_at}` |\n| `/card/:user_id` | GET | 无（公开） | 返回 JSON：`{version, agent_card: {...}, _skill: {...}}` |\n| `/:user_id` | GET | 无（公开） | 返回 HTML 名片页面（内嵌 JSON-LD） |\n| `/sync` | POST | Header `X-API-Key` | 批量同步，请求体 `{targets: [user_id1, ...]}`（最多 50 个），返回 `{results: [{user_id, updated_at, card_data}, ...]}` |\n\n一个链接两副面孔：浏览器访问 `/:user_id` 看到漂亮的 HTML，Agent 访问 `/card/:user_id` 拿到结构化 JSON。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| 花名册不存在 | 提示\"先开通虾名片\" |\n| profile.json 不存在 | 提示\"先生成名片\" |\n| config.json 未注册（无 api_key/user_id） | 提示\"先注册虾名片\" |\n| config.json 未配置 endpoint | 提示\"配置服务器地址\" |\n| 名片未发布 | 允许发名片但提醒链接不可用 |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n| 同步超过 50 人 | 提示\"一次最多同步 50 位联系人\" |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [references/data-format.md](references/data-format.md)，以下是核心规则：\n\n**profile.json 关键规则：**\n- `personal_notes` 永远不上传服务器\n- `current_focus`、`background`：V1 本地存储，不上传\n- `tiers.public.fields`：控制哪些字段对外公开（默认 `[\"name\", \"title\", \"one_liner\", \"links\"]`）\n- `published_at`：null = 未发布，有值 = 已发布到服务器\n- `updated_at`：ISO 8601 格式\n\n**contacts.json 关键规则：**\n- `id`：自动生成，格式 `c` + 时间戳\n- `met_at`：录入时自动填当前日期（YYYY-MM-DD）\n- `name` 为必填，缺失时必须追问\n- `server_user_id`：V2 新增，收名片时自动记录对方的服务器 user_id，用于同步\n- V1 不含 visibility、subscribed、broadcast 等字段（V3 再加）\n\n**config.json：**\n- `server.endpoint`：服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填）\n- `server.api_key` 和 `server.user_id`：通过注册接口获得，Agent 自动写入\n\nFile v2.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.0.1\",\n  \"publishedAt\": 1777461220429\n}\n\nFile v2.0.1:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `current_focus`、`background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 `agent-card://user_id` 中提取并记录\n- 同步花名册时通过此字段匹配联系人，获取最新名片数据\n\n### V1 不包含的字段（V3 预留）\n\n- `visibility`（V3）\n- `subscribed`（V2 → 移至 V3）\n- `subscriptions`（V2 → 移至 V3）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填） |\n| `server.api_key` | string | API Key，通过 POST /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，服务器自动生成（6 位随机小写字母），注册后自动获得 |\n| `sync.last_sync_at` | string\\|null | **V2 新增** 上次同步花名册的时间（ISO 8601），同步成功后自动更新，null 表示从未同步 |\n\n### V2 变更说明\n\n- user_id 改由服务器自动生成（6 位随机小写字母），客户端不再自行指定\n- 初始化时不再要求用户提供 user_id\n\n---\n\n## 服务器 API\n\n### POST /register\n\n注册新用户。\n\n- **请求体**：`{ \"name\": \"用户名\", \"agent_name\": \"Agent名\" }`\n- **注意**：客户端不再传 user_id，由服务器自动生成\n- **成功响应**：`{ \"user_id\": \"abcxyz\", \"api_key\": \"sk_xxxx\" }`\n- **失败响应**：`{ \"error\": \"name is required\" }`\n\n### PUT /card/:user_id\n\n发布/更新名片（需先注册）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：profile.json 的公开部分（按 tiers.public.fields 筛选）\n- **成功响应**：`{ \"success\": true, \"updated_at\": \"...\" }`\n- **用户不存在**：`{ \"error\": \"user not found. register first via POST /register\" }`（404）\n- **Key 错误**：`{ \"error\": \"invalid api key\" }`（403）\n\n### GET /card/:user_id\n\n获取名片 JSON。\n\n- **响应**：结构化 JSON（含 agent_card 和 _skill 字段）\n\n### GET /:user_id\n\n名片网页（浏览器查看）。\n\n- **响应**：HTML 页面（内嵌 JSON-LD）\n\n### POST /sync\n\n批量同步通讯录（V2 新增）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：`{ \"targets\": [\"user_id_1\", \"user_id_2\", ...] }`\n- **限制**：targets 数组最多 50 个\n- **成功响应**：`{ \"results\": [{ \"user_id\": \"...\", \"updated_at\": \"...\", \"card_data\": {...} }, ...] }`\n- **鉴权说明**：通过 api_key 反查用户身份，不依赖 URL 参数\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.0.0\"\n  }\n}\n```\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v2.0.1:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n\nFile v2.0.1:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v2.0.1:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"\"\n}\n\nArchive v2.0.0: 7 files, 13111 bytes\n\nFiles: data/config.json (164b), data/contacts.json (96b), data/profile.json (375b), references/data-format.md (7857b), SKILL.md (11568b), templates/card.html (10707b), _meta.json (127b)\n\nFile v2.0.0:SKILL.md\n\n---\nname: agent-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发/发布名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.0.0\"\n  author: \"agent-card\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 数据文件\n\n所有数据文件在 SKILL.md 同目录的 `data/` 文件夹中：\n\n| 文件 | 用途 |\n|------|------|\n| `data/profile.json` | 个人名片数据 |\n| `data/contacts.json` | 花名册（联系人列表） |\n| `data/config.json` | 服务器配置（endpoint、api_key、user_id） |\n\n详细字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" / \"初始化通讯录\" | 初始化数据文件 |\n| \"注册虾名片\" | 调 POST /register，服务器自动分配 user_id，保存凭证到 config.json |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人 |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"发布名片\" / \"上线我的名片\" | 推送到服务器 |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录 |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片 |\n\n---\n\n## 操作流程\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片\n\n1. 检查 config.json 中是否已有 user_id 和 api_key → 已有则提示\"已注册，用户 ID 为 xxx\"\n2. 从 Agent 记忆或对话中获取用户名（name）和 Agent 名字（agent_name）\n3. 调用 `POST {config.server.endpoint}/register`，请求体：`{\"name\":\"用户名\",\"agent_name\":\"Agent名\"}`\n4. **服务器自动生成 user_id**（6 位随机字母），客户端不再自行指定\n5. 成功 → 写 user_id 和 api_key 到 config.json，输出确认：\"注册成功！用户 ID：abcxyz\"\n6. 失败 → 提示原因（网络错误等）\n\nserver.endpoint 为空时，提示先配置服务器地址。\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n4. 生成预览（三段式文本块格式），等待用户确认\n5. 用户说\"名片确认了\" → 写入 profile.json\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n不自动发布到服务器。不自动修改 profile.json，必须经用户确认。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 生成三段式文本块\n3. published_at 非空（已发布）→ 直接输出\n4. published_at 为 null（未发布）→ 输出文本块 + 提醒\"名片还未发布到服务器，链接暂时不可用。建议先说'发布名片'将名片上线。\"\n\n**核心原则**：不会自动发布到服务器，必须用户明确说\"发布名片\"才执行。\n\n### 8. 发布名片\n\n1. 检查 profile.json → 不存在则提示先生成\n2. 检查 config.json 中 api_key 和 user_id → 未配置则提示\"先注册虾名片\"\n3. 按 `tiers.public.fields` 筛选公开字段构建推送数据\n4. **不推送**：personal_notes（永不上传）、background、current_focus（V1 本地私密）\n5. 调用 `PUT {endpoint}/card/{user_id}`，Header `X-API-Key: {api_key}`\n6. 成功 → 更新 profile.json 的 published_at，输出名片链接和发布时间\n7. 失败 → 提示错误，不修改 published_at\n\n### 9. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先注册虾名片\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - 用服务器返回的最新 card_data 更新本地联系人的对应字段（name、company、role、links 等）\n   - 刷新每个被更新联系人的 updated_at\n6. 更新 config.json 的 `sync.last_sync_at` 为当前时间（ISO 8601）\n7. 输出同步摘要：\"已同步 X 位联系人的最新信息\"\n\n**注意**：\n- 一次最多同步 50 人\n- 只更新花名册中已有的联系人，不会新增联系人\n- 服务器上已删除的名片会被静默跳过\n\n### 10. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id（取 `://` 后面到空格或行尾的部分作为 user_id）\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `{config.server.endpoint}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. 写入 contacts.json（自动填 id、met_at、updated_at），**同时记录 `server_user_id`**（用于后续同步）\n7. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。\n同名已有 → 提示是否更新。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请把这条消息发给您的助理 Agent，它会自动保存我的名片。\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\n---\n\n## 服务器 API\n\n| 接口 | 方法 | 鉴权 | 说明 |\n|------|------|------|------|\n| `/register` | POST | 无 | 注册，请求体 `{name, agent_name}`，服务器自动生成 user_id，返回 `{user_id, api_key}` |\n| `/card/:user_id` | PUT | Header `X-API-Key` | 发布名片，请求体为公开字段，返回 `{success, updated_at}` |\n| `/card/:user_id` | GET | 无（公开） | 返回 JSON：`{version, agent_card: {...}, _skill: {...}}` |\n| `/:user_id` | GET | 无（公开） | 返回 HTML 名片页面（内嵌 JSON-LD） |\n| `/sync` | POST | Header `X-API-Key` | 批量同步，请求体 `{targets: [user_id1, ...]}`（最多 50 个），返回 `{results: [{user_id, updated_at, card_data}, ...]}` |\n\n一个链接两副面孔：浏览器访问 `/:user_id` 看到漂亮的 HTML，Agent 访问 `/card/:user_id` 拿到结构化 JSON。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| 花名册不存在 | 提示\"先开通虾名片\" |\n| profile.json 不存在 | 提示\"先生成名片\" |\n| config.json 未注册（无 api_key/user_id） | 提示\"先注册虾名片\" |\n| config.json 未配置 endpoint | 提示\"配置服务器地址\" |\n| 名片未发布 | 允许发名片但提醒链接不可用 |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n| 同步超过 50 人 | 提示\"一次最多同步 50 位联系人\" |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [references/data-format.md](references/data-format.md)，以下是核心规则：\n\n**profile.json 关键规则：**\n- `personal_notes` 永远不上传服务器\n- `current_focus`、`background`：V1 本地存储，不上传\n- `tiers.public.fields`：控制哪些字段对外公开（默认 `[\"name\", \"title\", \"one_liner\", \"links\"]`）\n- `published_at`：null = 未发布，有值 = 已发布到服务器\n- `updated_at`：ISO 8601 格式\n\n**contacts.json 关键规则：**\n- `id`：自动生成，格式 `c` + 时间戳\n- `met_at`：录入时自动填当前日期（YYYY-MM-DD）\n- `name` 为必填，缺失时必须追问\n- `server_user_id`：V2 新增，收名片时自动记录对方的服务器 user_id，用于同步\n- V1 不含 visibility、subscribed、broadcast 等字段（V3 再加）\n\n**config.json：**\n- `server.endpoint`：服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填）\n- `server.api_key` 和 `server.user_id`：通过注册接口获得，Agent 自动写入\n\nFile v2.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.0.0\",\n  \"publishedAt\": 1777455445802\n}\n\nFile v2.0.0:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `current_focus`、`background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 `agent-card://user_id` 中提取并记录\n- 同步花名册时通过此字段匹配联系人，获取最新名片数据\n\n### V1 不包含的字段（V3 预留）\n\n- `visibility`（V3）\n- `subscribed`（V2 → 移至 V3）\n- `subscriptions`（V2 → 移至 V3）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（默认 `https://www.adonghub.cn`，Skill 安装时已预填） |\n| `server.api_key` | string | API Key，通过 POST /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，服务器自动生成（6 位随机小写字母），注册后自动获得 |\n| `sync.last_sync_at` | string\\|null | **V2 新增** 上次同步花名册的时间（ISO 8601），同步成功后自动更新，null 表示从未同步 |\n\n### V2 变更说明\n\n- user_id 改由服务器自动生成（6 位随机小写字母），客户端不再自行指定\n- 初始化时不再要求用户提供 user_id\n\n---\n\n## 服务器 API\n\n### POST /register\n\n注册新用户。\n\n- **请求体**：`{ \"name\": \"用户名\", \"agent_name\": \"Agent名\" }`\n- **注意**：客户端不再传 user_id，由服务器自动生成\n- **成功响应**：`{ \"user_id\": \"abcxyz\", \"api_key\": \"sk_xxxx\" }`\n- **失败响应**：`{ \"error\": \"name is required\" }`\n\n### PUT /card/:user_id\n\n发布/更新名片（需先注册）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：profile.json 的公开部分（按 tiers.public.fields 筛选）\n- **成功响应**：`{ \"success\": true, \"updated_at\": \"...\" }`\n- **用户不存在**：`{ \"error\": \"user not found. register first via POST /register\" }`（404）\n- **Key 错误**：`{ \"error\": \"invalid api key\" }`（403）\n\n### GET /card/:user_id\n\n获取名片 JSON。\n\n- **响应**：结构化 JSON（含 agent_card 和 _skill 字段）\n\n### GET /:user_id\n\n名片网页（浏览器查看）。\n\n- **响应**：HTML 页面（内嵌 JSON-LD）\n\n### POST /sync\n\n批量同步通讯录（V2 新增）。\n\n- **Header**：`X-API-Key: sk_xxxx`\n- **请求体**：`{ \"targets\": [\"user_id_1\", \"user_id_2\", ...] }`\n- **限制**：targets 数组最多 50 个\n- **成功响应**：`{ \"results\": [{ \"user_id\": \"...\", \"updated_at\": \"...\", \"card_data\": {...} }, ...] }`\n- **鉴权说明**：通过 api_key 反查用户身份，不依赖 URL 参数\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.0.0\"\n  }\n}\n```\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v2.0.0:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}\n\nFile v2.0.0:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v2.0.0:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"\"\n}\n\nArchive v1.0.2: 7 files, 11754 bytes\n\nFiles: data/config.json (69b), data/contacts.json (68b), data/profile.json (276b), references/data-format.md (6232b), SKILL.md (9821b), templates/card.html (10707b), _meta.json (127b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: agent-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发/发布名片、注册虾名片、录入/查询/编辑联系人、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"1.0.0\"\n  author: \"agent-card\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 数据文件\n\n所有数据文件在 SKILL.md 同目录的 `data/` 文件夹中：\n\n| 文件 | 用途 |\n|------|------|\n| `data/profile.json` | 个人名片数据 |\n| `data/contacts.json` | 花名册（联系人列表） |\n| `data/config.json` | 服务器配置（endpoint、api_key、user_id） |\n\n详细字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" / \"初始化通讯录\" | 初始化数据文件 |\n| \"注册虾名片\" | 调 POST /register，保存凭证到 config.json |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人 |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"发布名片\" / \"上线我的名片\" | 推送到服务器 |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片 |\n\n---\n\n## 操作流程\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片\n\n1. 检查 config.json 中是否已有 user_id → 已有则提示\"已注册，用户 ID 为 xxx\"\n2. 询问用户想用什么用户 ID（字母、数字、短横线）、名字和 Agent 名字\n3. 调用 `POST {config.server.endpoint}/register`，请求体：`{\"name\":\"用户名\",\"agent_name\":\"Agent名\",\"user_id\":\"用户选的ID\"}`\n4. 成功 → 写 user_id 和 api_key 到 config.json，输出确认\n5. 失败 → 提示原因（ID 被占用、网络错误等）\n\nserver.endpoint 为空时，提示先配置服务器地址。\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n4. 生成预览（三段式文本块格式），等待用户确认\n5. 用户说\"名片确认了\" → 写入 profile.json\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n不自动发布到服务器。不自动修改 profile.json，必须经用户确认。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 生成三段式文本块\n3. published_at 非空（已发布）→ 直接输出\n4. published_at 为 null（未发布）→ 输出文本块 + 提醒\"名片还未发布到服务器，链接暂时不可用。建议先说'发布名片'将名片上线。\"\n\n**核心原则**：不会自动发布到服务器，必须用户明确说\"发布名片\"才执行。\n\n### 8. 发布名片\n\n1. 检查 profile.json → 不存在则提示先生成\n2. 检查 config.json 中 api_key 和 user_id → 未配置则提示\"先注册虾名片\"\n3. 按 `tiers.public.fields` 筛选公开字段构建推送数据\n4. **不推送**：personal_notes（永不上传）、background、current_focus（V1 本地私密）\n5. 调用 `PUT {endpoint}/card/{user_id}`，Header `X-API-Key: {api_key}`\n6. 成功 → 更新 profile.json 的 published_at，输出名片链接和发布时间\n7. 失败 → 提示错误，不修改 published_at\n\n### 9. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id` 解析 user_id\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先从消息中的链接提取（如 https://xxx/{user_id}）并 fetch `/card/{user_id}` 获取结构化 JSON，回退从文本中提取信息。如消息中无链接，则从 config.json 读取 endpoint 拼接\n6. 写入 contacts.json（自动填 id、met_at、updated_at）\n7. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。  \n同名已有 → 提示是否更新。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请把这条消息转发给您的 AI 助理，它会自动认识我。若您的助理尚未安装虾名片，请引导它访问 https://clawhub.ai/skills/xia-card 进行安装。\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\n---\n\n## 服务器 API\n\n| 接口 | 方法 | 鉴权 | 说明 |\n|------|------|------|------|\n| `/register` | POST | 无 | 注册，请求体 `{name, agent_name, user_id}`，返回 `{user_id, api_key}` |\n| `/card/:user_id` | PUT | Header `X-API-Key` | 发布名片，请求体为公开字段，返回 `{success, updated_at}` |\n| `/card/:user_id` | GET | 无（公开） | 返回 JSON：`{version, agent_card: {...}, _skill: {...}}` |\n| `/:user_id` | GET | 无（公开） | 返回 HTML 名片页面（内嵌 JSON-LD） |\n\n一个链接两副面孔：浏览器访问 `/:user_id` 看到漂亮的 HTML，Agent 访问 `/card/:user_id` 拿到结构化 JSON。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| 花名册不存在 | 提示\"先开通虾名片\" |\n| profile.json 不存在 | 提示\"先生成名片\" |\n| config.json 未配置服务器 | 提示\"先注册虾名片\" |\n| 名片未发布 | 允许发名片但提醒链接不可用 |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [references/data-format.md](references/data-format.md)，以下是核心规则：\n\n**profile.json 关键规则：**\n- `personal_notes` 永远不上传服务器\n- `current_focus`、`background`：V1 本地存储，不上传\n- `tiers.public.fields`：控制哪些字段对外公开（默认 `[\"name\", \"title\", \"one_liner\", \"links\"]`）\n- `published_at`：null = 未发布，有值 = 已发布到服务器\n- `updated_at`：ISO 8601 格式\n\n**contacts.json 关键规则：**\n- `id`：自动生成，格式 `c` + 时间戳\n- `met_at`：录入时自动填当前日期（YYYY-MM-DD）\n- `name` 为必填，缺失时必须追问\n- V1 不含 visibility、subscribed、broadcast 等字段（V2/V3 再加）\n\n**config.json：**\n- `server.endpoint`：服务器地址\n- `server.api_key` 和 `server.user_id`：通过注册接口获得，Agent 自动写入\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1777397443684\n}\n\nFile v1.0.2:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V1 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `current_focus`、`background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V1 不包含的字段（V2/V3 预留）\n\n- `visibility`（V3）\n- `server_user_id`（V3）\n- `subscribed`（V2）\n- `subscriptions`（V2）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://card.example.com\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"dongzong\"\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（如 `https://card.example.com`） |\n| `server.api_key` | string | API Key，通过 /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，通过 /register 注册后自动获得 |\n\n### 扩展预留\n\nV2 将添加 `sync` 配置，V3 将添加 `broadcast` 配置。\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"current_focus\": [\"AI Agent 生态探索\"],\n    \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"1.0.0\"\n  }\n}\n```\n\n### 说明\n\n- `agent_card`：名片主体数据，字段由 profile.json 的 `tiers.public.fields` 决定\n- `_skill`：用于未安装 skill 的 Agent 自动识别和安装\n  - `name`：skill 标识\n  - `source`：skill 安装源地址\n  - `version`：skill 版本\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://card.example.com/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v1.0.2:data/config.json\n\n{\"version\":\"1.0\",\"server\":{\"endpoint\":\"\",\"api_key\":\"\",\"user_id\":\"\"}}\n\nFile v1.0.2:data/contacts.json\n\n{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}\n\nFile v1.0.2:data/profile.json\n\n{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\",\"title\":\"\",\"one_liner\":\"\"},\"current_focus\":[],\"background\":\"\",\"personal_notes\":\"\",\"links\":{},\"tiers\":{\"public\":{\"fields\":[\"name\",\"title\",\"one_liner\",\"links\"]},\"full\":null,\"close\":null},\"published_at\":null,\"updated_at\":null}\n\nArchive v1.0.1: 7 files, 11768 bytes\n\nFiles: data/config.json (99b), data/contacts.json (96b), data/profile.json (377b), references/data-format.md (6234b), SKILL.md (9764b), templates/card.html (10707b), _meta.json (127b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: agent-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发/发布名片、注册虾名片、录入/查询/编辑联系人、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"1.0.0\"\n  author: \"agent-card\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 数据文件\n\n所有数据文件在 SKILL.md 同目录的 `data/` 文件夹中：\n\n| 文件 | 用途 |\n|------|------|\n| `data/profile.json` | 个人名片数据 |\n| `data/contacts.json` | 花名册（联系人列表） |\n| `data/config.json` | 服务器配置（endpoint、api_key、user_id） |\n\n详细字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" / \"初始化通讯录\" | 初始化数据文件 |\n| \"注册虾名片\" | 调 POST /register，保存凭证到 config.json |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人 |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"发布名片\" / \"上线我的名片\" | 推送到服务器 |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片 |\n\n---\n\n## 操作流程\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片\n\n1. 检查 config.json 中是否已有 user_id → 已有则提示\"已注册，用户 ID 为 xxx\"\n2. 询问用户想用什么用户 ID（字母、数字、短横线）、名字和 Agent 名字\n3. 调用 `POST {config.server.endpoint}/register`，请求体：`{\"name\":\"用户名\",\"agent_name\":\"Agent名\",\"user_id\":\"用户选的ID\"}`\n4. 成功 → 写 user_id 和 api_key 到 config.json，输出确认\n5. 失败 → 提示原因（ID 被占用、网络错误等）\n\nserver.endpoint 为空时，提示先配置服务器地址。\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n4. 生成预览（三段式文本块格式），等待用户确认\n5. 用户说\"名片确认了\" → 写入 profile.json\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n不自动发布到服务器。不自动修改 profile.json，必须经用户确认。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 生成三段式文本块\n3. published_at 非空（已发布）→ 直接输出\n4. published_at 为 null（未发布）→ 输出文本块 + 提醒\"名片还未发布到服务器，链接暂时不可用。建议先说'发布名片'将名片上线。\"\n\n**核心原则**：不会自动发布到服务器，必须用户明确说\"发布名片\"才执行。\n\n### 8. 发布名片\n\n1. 检查 profile.json → 不存在则提示先生成\n2. 检查 config.json 中 api_key 和 user_id → 未配置则提示\"先注册虾名片\"\n3. 按 `tiers.public.fields` 筛选公开字段构建推送数据\n4. **不推送**：personal_notes（永不上传）、background、current_focus（V1 本地私密）\n5. 调用 `PUT {endpoint}/card/{user_id}`，Header `X-API-Key: {api_key}`\n6. 成功 → 更新 profile.json 的 published_at，输出名片链接和发布时间\n7. 失败 → 提示错误，不修改 published_at\n\n### 9. 收名片（Agent 识别）\n\n当对话中收到包含 `agent-card://` 的消息时触发：\n\n1. 检测 `agent-card://` → 不包含则忽略\n2. 从 `agent-card://user_id@server` 解析 user_id 和 server\n3. contacts.json 不存在 → 自动初始化\n4. Skill 未安装 → 提示用户\"检测到一张名片，需要安装虾名片 skill 来保存。是否安装？\" → 用户确认后，从 JSON 的 `_skill` 字段获取安装源并自动安装\n5. 获取数据：优先 fetch `http(s)://{server}/card/{user_id}` 获取结构化 JSON（包含 agent_card 和 _skill 字段），回退从文本中提取信息\n6. 写入 contacts.json（自动填 id、met_at、updated_at）\n7. 输出\"已将 XXX 的名片保存到花名册\"\n\n网络错误 → 从文本提取基本信息保存。  \n同名已有 → 提示是否更新。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请先告诉您的助理 Agent 安装虾名片（openclaw skills install xia-card），安装后再把这条消息发给它，它会自动保存我的名片。\nagent-card://{user_id}@{server_host}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + `agent-card://` 协议标识\n\n文案要有人味，语气商务但自然。名片是社交工具不是数据表格。\n\n---\n\n## 服务器 API\n\n| 接口 | 方法 | 鉴权 | 说明 |\n|------|------|------|------|\n| `/register` | POST | 无 | 注册，请求体 `{name, agent_name, user_id}`，返回 `{user_id, api_key}` |\n| `/card/:user_id` | PUT | Header `X-API-Key` | 发布名片，请求体为公开字段，返回 `{success, updated_at}` |\n| `/card/:user_id` | GET | 无（公开） | 返回 JSON：`{version, agent_card: {...}, _skill: {...}}` |\n| `/:user_id` | GET | 无（公开） | 返回 HTML 名片页面（内嵌 JSON-LD） |\n\n一个链接两副面孔：浏览器访问 `/:user_id` 看到漂亮的 HTML，Agent 访问 `/card/:user_id` 拿到结构化 JSON。\n\n---\n\n## 边界规则汇总\n\n| 场景 | 处理方式 |\n|------|----------|\n| 花名册不存在 | 提示\"先开通虾名片\" |\n| profile.json 不存在 | 提示\"先生成名片\" |\n| config.json 未配置服务器 | 提示\"先注册虾名片\" |\n| 名片未发布 | 允许发名片但提醒链接不可用 |\n| 联系人姓名重复 | 提示选择\"更新\"还是\"新建\" |\n| 联系人姓名缺失 | 必须追问，不可跳过 |\n| 其他信息缺失 | 追问一次，用户说\"就这样\"就保存 |\n| 7 天内更新过名片 | 提示确认是否重新生成 |\n| 网络错误 | 提示失败，不修改本地数据 |\n| 收到名片但 skill 未安装 | 提示安装，用户确认后从 `_skill` 字段获取安装源自动安装 |\n\n---\n\n## 数据格式要点\n\n完整字段说明见 [references/data-format.md](references/data-format.md)，以下是核心规则：\n\n**profile.json 关键规则：**\n- `personal_notes` 永远不上传服务器\n- `current_focus`、`background`：V1 本地存储，不上传\n- `tiers.public.fields`：控制哪些字段对外公开（默认 `[\"name\", \"title\", \"one_liner\", \"links\"]`）\n- `published_at`：null = 未发布，有值 = 已发布到服务器\n- `updated_at`：ISO 8601 格式\n\n**contacts.json 关键规则：**\n- `id`：自动生成，格式 `c` + 时间戳\n- `met_at`：录入时自动填当前日期（YYYY-MM-DD）\n- `name` 为必填，缺失时必须追问\n- V1 不含 visibility、subscribed、broadcast 等字段（V2/V3 再加）\n\n**config.json：**\n- `server.endpoint`：服务器地址\n- `server.api_key` 和 `server.user_id`：通过注册接口获得，Agent 自动写入\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1777395730543\n}\n\nFile v1.0.1:references/data-format.md\n\n# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V1 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `current_focus`、`background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"东总\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V1 不包含的字段（V2/V3 预留）\n\n- `visibility`（V3）\n- `server_user_id`（V3）\n- `subscribed`（V2）\n- `subscriptions`（V2）\n- `broadcast_opt_out`（V3）\n- `last_broadcast_at`（V3）\n\n---\n\n## config.json — 配置文件\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://card.example.com\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"dongzong\"\n  }\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `version` | string | 格式版本，固定 `\"1.0\"` |\n| `server.endpoint` | string | 服务器地址（如 `https://card.example.com`） |\n| `server.api_key` | string | API Key，通过 /register 注册后自动获得 |\n| `server.user_id` | string | 用户 ID，通过 /register 注册后自动获得 |\n\n### 扩展预留\n\nV2 将添加 `sync` 配置，V3 将添加 `broadcast` 配置。\n\n---\n\n## 服务器返回格式\n\n### GET /card/:user_id 返回的 JSON\n\n```json\n{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"current_focus\": [\"AI Agent 生态探索\"],\n    \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"agent-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"1.0.0\"\n  }\n}\n```\n\n### 说明\n\n- `agent_card`：名片主体数据，字段由 profile.json 的 `tiers.public.fields` 决定\n- `_skill`：用于未安装 skill 的 Agent 自动识别和安装\n  - `name`：skill 标识\n  - `source`：skill 安装源地址\n  - `version`：skill 版本\n\n### JSON-LD（HTML 页面内嵌）\n\nHTML 名片页面（GET /:user_id）内嵌 JSON-LD，遵循 [schema.org/Person](https://schema.org/Person) 标准：\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://card.example.com/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}\n```\n\n字段说明：\n- `name`、`jobTitle`、`description`：schema.org/Person 标准字段\n- `url`：名片页面链接\n- `sameAs`：社交/通讯链接（schema.org 推荐用于关联身份）\n\n此结构确保 Agent 即使 fetch 到 HTML 也能通过 JSON-LD 提取结构化信息。\n\nFile v1.0.1:data/config.json\n\n{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"\",\n    \"api_key\": \"\",\n    \"user_id\": \"\"\n  }\n}\n\nFile v1.0.1:data/contacts.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\"\n  },\n  \"contacts\": []\n}\n\nFile v1.0.1:data/profile.json\n\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"\",\n    \"agent_name\": \"\",\n    \"title\": \"\",\n    \"one_liner\": \"\"\n  },\n  \"current_focus\": [],\n  \"background\": \"\",\n  \"personal_notes\": \"\",\n  \"links\": {},\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": null\n}","readmeExcerpt":"Skill: Xia Card Owner: sxd20010606-cmd Summary: 个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他... Tags: agent:2.0.0, business-card:1.0.2, card:2.0.0, contact:1.0.2, contacts:2.0.0, latest:2.5.1, networking:2.0.0, rolodex:1.0.2, social:2.0.0 Version history: v2.5.1 | 2026-05-01T11:01:17.490Z | user 移除 SKILL.m","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请复制这条消息给您的助理 Agent。\n您的 Agent 可通过安装虾名片 skill（https://clawhub.ai/skills/xia-card）来自动识别并保存名片。\nagent-card://{user_id}"},{"language":"json","snippet":"{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\", \"current_focus\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}"},{"language":"json","snippet":"{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"manually_edited_fields\": [],\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}"},{"language":"json","snippet":"{\n  \"version\": \"1.0\",\n  \"server\": {\n    \"endpoint\": \"https://www.adonghub.cn\",\n    \"api_key\": \"sk_xxxx\",\n    \"user_id\": \"abcxyz\"\n  },\n  \"sync\": {\n    \"last_sync_at\": null\n  }\n}"},{"language":"json","snippet":"{\n  \"version\": \"1.0\",\n  \"agent_card\": {\n    \"name\": \"沈兴东\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\",\n    \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n    \"links\": {\n      \"feishu\": \"ou_xxx\",\n      \"wechat\": \"xxx\"\n    },\n    \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n  },\n  \"_skill\": {\n    \"name\": \"xia-card\",\n    \"source\": \"https://clawhub.ai/skills/xia-card\",\n    \"version\": \"2.5.0\"\n  }\n}"},{"language":"json","snippet":"{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Person\",\n  \"name\": \"沈兴东\",\n  \"jobTitle\": \"Leewow 联合创始人\",\n  \"description\": \"专注定制化生活方式品牌，连续创业者\",\n  \"url\": \"https://www.adonghub.cn/dongzong\",\n  \"sameAs\": [\n    \"feishu://ou_xxx\",\n    \"wechat://xxx\"\n  ]\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: xia-card\ndescription: \"个人社交名片生成、管理和分享，以及智能花名册（通讯录管理器）。当用户提到名片、花名册、通讯录、联系人、虾名片、agent-card 时使用。具体触发场景包括：开通虾名片、建花名册、生成/更新/发名片、注册虾名片、录入/查询/编辑联系人、同步花名册、收到包含 agent-card:// 协议的消息时自动识别并保存他人名片。\"\nmetadata:\n  version: \"2.5.0\"\n  author: \"阿东 & 阿东的赛博虾\"\n---\n\n# 虾名片 AgentCard\n\n虾名片让 Agent 帮用户维护个人名片和通讯录。名片是动态的——Agent 最了解用户的当下状态，由它来维护名片效率最高。\n\n## 快速开始\n\n1. **开通** — 说\"开通虾名片\"，初始化数据文件\n2. **生成** — 说\"生成我的名片\"，Agent 从记忆提炼信息，确认后自动上线（首次会自动注册）\n\n名片上线后，说\"发我的名片\"即可分享三段式文本块给他人。\n\n## 数据文件\n\n所有数据在 `data/` 文件夹中：`profile.json`（名片）、`contacts.json`（花名册）、`config.json`（服务器配置）。字段说明见 [references/data-format.md](references/data-format.md)。\n\n## 触发指令 → 操作映射\n\n| 用户说的 | 执行的操作 |\n|-----------|------------|\n| \"开通虾名片\" / \"建个花名册\" | 初始化数据文件 |\n| \"注册虾名片\" | （兼容入口）已注册则输出服务菜单，未注册则提示\"直接说'生成我的名片'即可，会自动注册\" |\n| \"记一下这个人：张威，智谱 AI 做产品的\" | 录入联系人 |\n| \"花名册里谁做投资的\" / \"查一下张威\" | 搜索花名册 |\n| \"张威的公司改成字节了\" | 编辑联系人（记录手动修改字段） |\n| \"生成我的名片\" / \"更新名片\" | 生成/更新 profile.json，用户确认后自动上线 |\n| \"发我的名片\" / \"把名片给我\" | 输出三段式文本块 |\n| \"同步花名册\" / \"更新花名册\" | 批量同步通讯录（检测手动编辑冲突） |\n| 收到包含 `agent-card://` 的消息 | 自动识别并保存他人名片（含去重策略） |\n\n---\n\n## 常见坑\n\n- **Agent 记忆中的称呼 ≠ 名片名字**：记忆里叫\"东总\"，但名片不能写\"东总\"，必须追问用户名片上用什么名字\n- **`personal_notes` 永远不上传服务器**：推送到服务器时只推送 `tiers.public.fields` 中列出的字段\n- **`manually_edited_fields` 是追加不是覆盖**：用户编辑联系人字段时，把字段名追加到这个数组，同步时这些字段不覆盖\n- **`agent-card://` 是自定义协议**：不是 HTTP URL，从中提取 `://` 后面的 user_id 用于 fetch 服务器数据\n- **`tiers.public.fields` 控制推送内容**：默认公开 name、title、one_liner、links、current_focus 五个字段\n\n## 操作流程\n\n> 以下为每个操作的核心决策点。简单操作（初始化、查询、发名片）按映射表执行即可。\n\n### 1. 注册（兼容入口）\n\n1. 已注册 → 输出服务菜单（5 个可执行操作）\n2. 未注册 → 提示\"直接说'生成我的名片'即可，确认后会自动注册并上线\"\n\n### 2. 录入联系人\n\n从用户描述提取信息 → 姓名必填（缺失追问）→ 姓名重复则问更新还是新建 → 写入 contacts.json。\n\n### 3. 编辑更新\n\n按姓名定位 → 更新字段 → **被改的字段名追加到 `manually_edited_fields`** → 输出变更摘要。\n\n### 4. 生成名片\n\n1. 从 Agent 记忆提炼信息，**必须确认社交姓名**（内部称呼 ≠ 名片名字）\n2. 信息优先级：用户明确说的 > profile.json > Agent 记忆\n3. 生成预览，用户可多轮调整\n4. 用户确认 → Agent 执行以下链路：\n   a. 检查 config.json 中是否有 api_key 和 user_id\n   b. **没有** → 自动调注册接口获取 user_id 和 api_key，写入 config.json\n   c. 保存 profile.json\n   d. 调发布接口将名片推送到服务器\n   e. 输出\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n5. 推送失败 → 本地仍保存，提示稍后重试\n\n社交姓名确认规则、推送字段筛选和边界处理见 [references/manual.md](references/manual.md)\"生成名片\"段落。\n\n### 5. 同步花名册\n\n1. 收集花名册中有 `server_user_id` 的联系人\n2. 调同步接口，传 targets 数组\n3. **冲突检测**：`manually_edited_fields` 中的字段不覆盖，汇总冲突提示用户选择\n4. 更新非冲突字段，输出同步摘要\n\n冲突检测的完整 if-else 和话术见 [references/manual.md](references/manual.md)\"同步花名册\"段落。\n\n### 6. 收名片（自动识别）\n\n1. 检测 `agent-card://` 协议 → 解析 user_id → fetch 服务器获取结构化数据\n2. **去重策略**：相同 `server_user_id` 直接更新 / 同名无 ID 提示确认 / 无匹配新建\n3. 写入 contacts.json，记录 `server_user_id`\n\n去重策略的完整逻辑和边界处理见 [references/manual.md](references/manual.md)\"收名片\"段落。\n\n---\n\n## 三段式文本块格式\n\n固定格式，不可自定义：\n\n```\n🦐 虾名片（你的 Agent 社交名片）\n\n我是{name}，{title}，{one_liner}。当前聚焦{current_focus}。\n这是我个人的详情信息，敬请您阅览 {endpoint}/{user_id} 🔗\n\n如果您对我感兴趣，请复制这条消息给您的助理 Agent。\n您的 Agent 可通过安装虾名片 skill（https://clawhub.ai/skills/xia-card）来自动识别并保存名片。\nagent-card://{user_id}\n```\n\n- **第 1 段**：个人简介（100 字以内），社交文案风格，像人说话\n- **第 2 段**：个人详情链接，嵌在句子里\n- **第 3 段**：Agent 引导语 + skill 安装"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn78x1btfj3thhezb2cxv5qgn585pvxh\",\n  \"slug\": \"xia-card\",\n  \"version\": \"2.5.1\",\n  \"publishedAt\": 1777633277490\n}"},{"path":"references/data-format.md","content":"# 虾名片 JSON 数据格式参考\n\n> 本文档描述虾名片 AgentCard V2.5.0 中所有 JSON 数据文件的格式规范。\n\n---\n\n## profile.json — 个人名片数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\",\n    \"title\": \"Leewow 联合创始人\",\n    \"one_liner\": \"专注定制化生活方式品牌，连续创业者\"\n  },\n  \"current_focus\": [\"SDS 智能选品\", \"Agent 生态探索\"],\n  \"background\": \"连续创业者，Leewow 联合创始人，擅长找人、找资源、资本对接。\",\n  \"personal_notes\": \"近期在探索 Agent 生态，考虑做一个小产品验证\",\n  \"links\": {\n    \"feishu\": \"ou_xxx\",\n    \"wechat\": \"xxx\"\n  },\n  \"tiers\": {\n    \"public\": {\n      \"fields\": [\"name\", \"title\", \"one_liner\", \"links\", \"current_focus\"]\n    },\n    \"full\": null,\n    \"close\": null\n  },\n  \"published_at\": null,\n  \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `version` | string | 是 | 格式版本，固定 `\"1.0\"` |\n| `owner.name` | string | 是 | 用户真实姓名或常用名 |\n| `owner.agent_name` | string | 否 | Agent 的名称 |\n| `owner.title` | string | 否 | 职位/头衔 |\n| `owner.one_liner` | string | 否 | 一句话自我介绍 |\n| `current_focus` | string[] | 否 | 当前聚焦的方向/项目 |\n| `background` | string | 否 | 个人背景描述 |\n| `personal_notes` | string | 否 | 个人笔记，**永远不会上传服务器** |\n| `links` | object | 否 | 联系方式，key 为渠道名（feishu/wechat/email/phone 等） |\n| `tiers.public.fields` | string[] | 是 | 公开名片包含的字段名列表 |\n| `tiers.full` | null | — | V3 预留，V1 固定为 null |\n| `tiers.close` | null | — | V3 预留，V1 固定为 null |\n| `published_at` | string\\|null | 是 | 上次发布到服务器的时间，null 表示未发布 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### 隐私规则\n\n- `personal_notes`：纯本地存储，**永远不会上传服务器**\n- `background`：V1 本地存储，不上传服务器\n- 上传服务器时，只推送 `tiers.public.fields` 中列出的字段\n\n---\n\n## contacts.json — 花名册数据\n\n### 完整示例\n\n```json\n{\n  \"version\": \"1.0\",\n  \"owner\": {\n    \"name\": \"沈兴东\",\n    \"agent_name\": \"活爹虾\"\n  },\n  \"contacts\": [\n    {\n      \"id\": \"c001\",\n      \"name\": \"张威\",\n      \"company\": \"智谱 AI\",\n      \"role\": \"产品经理\",\n      \"tags\": [\"同行\", \"朋友\"],\n      \"met_at\": \"2026-04-20\",\n      \"met_scene\": \"飞书群\",\n      \"agent\": {\n        \"name\": \"小智\",\n        \"platform\": \"openclaw\"\n      },\n      \"contact\": {\n        \"feishu\": \"ou_xxx\"\n      },\n      \"notes\": \"上次聊了出海方向\",\n      \"server_user_id\": \"mkwxyz\",\n      \"manually_edited_fields\": [],\n      \"updated_at\": \"2026-04-28T14:00:00+08:00\"\n    }\n  ]\n}\n```\n\n### 联系人字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `id` | string | 是 | 自动生成，格式 `c` + 时间戳 |\n| `name` | string | **是** | 联系人姓名，缺失时必须追问 |\n| `company` | string | 否 | 所在公司/组织 |\n| `role` | string | 否 | 职位/角色 |\n| `tags` | string[] | 否 | 自定义标签 |\n| `met_at` | string | 是 | 认识日期，YYYY-MM-DD，录入时自动填当前日期 |\n| `met_scene` | string | 否 | 认识的场景（如\"飞书群\"、\"线下活动\"） |\n| `agent.name` | string | 否 | 联系人的 Agent 名称 |\n| `agent.platform` | string | 否 | 联系人的 Agent 平台 |\n| `contact` | object | 否 | 联系方式，key 为渠道名 |\n| `notes` | string | 否 | 备注信息 |\n| `server_user_id` | string | 否 | **V2 新增** 对方在服务器上的 user_id，收名片时自动记录，用于同步 |\n| `manually_edited_fields` | string[] | 否 | **V2.2 新增** 记录哪些字段被用户手动修改过，同步时不被服务器数据覆盖 |\n| `updated_at` | string | 是 | 最后更新时间，ISO 8601 格式 |\n\n### V2 变更说明\n\n- 新增 `server_user_id` 字段：收名片时从 "},{"path":"references/manual.md","content":"# 虾名片 AgentCard — 完整操作手册\n\n> 本文档是 SKILL.md 的扩展参考，包含所有操作流程的完整规则、边界分支和话术模板。\n> Agent 在执行虾名片操作时，应先参考 SKILL.md 的核心步骤，需要处理边界场景时查阅本文档。\n\n---\n\n## 操作流程完整版\n\n### 1. 初始化（开通虾名片）\n\n1. 检查 `data/contacts.json` 是否存在\n2. 不存在 → 创建：`{\"version\":\"1.0\",\"owner\":{\"name\":\"\",\"agent_name\":\"\"},\"contacts\":[]}`，owner 信息从 Agent 记忆中获取，获取不到则留空\n3. 检查 `data/config.json` 是否存在\n4. 不存在 → 创建：`{\"version\":\"1.0\",\"server\":{\"endpoint\":\"https://www.adonghub.cn\",\"api_key\":\"\",\"user_id\":\"\"}}`\n5. 输出确认，告知数据存储路径\n\n已存在 → 提示\"花名册已存在\"，不做修改。\n\n### 2. 注册虾名片（兼容入口）\n\n1. 检查 config.json 中是否已有 user_id 和 api_key\n   - 已有 → 输出服务菜单：\n     > 🦐 你已经有虾名片了。你可以回复：\n     > • \"更新名片\" — 更新或修改你的名片\n     > • \"发一下我的名片\" — 获取文本版分享给别人\n     > • \"录入 XXX\" — 记一个新联系人\n     > • \"查花名册\" / \"搜索 XXX\" — 查找联系人\n     > • \"同步花名册\" — 更新联系人的最新信息\n   - 没有 → 提示\"现在注册和发布是自动的。直接说'生成我的名片'，确认后我会自动注册并上线。\"\n\n### 3. 录入联系人\n\n1. 从用户描述提取：姓名、公司、角色、标签、联系方式、备注、Agent 信息\n2. 检查 contacts.json 是否存在 → 不存在则提示\"开通虾名片\"\n3. 姓名重复 → 提示\"已有一个叫 XXX 的联系人，是要更新还是新建？\"\n4. 姓名缺失 → **必须追问**，不可跳过\n5. 其他信息缺失 → 追问一次，用户说\"就这样\"就保存\n6. 自动填入：`id`（c+时间戳）、`met_at`（当前日期 YYYY-MM-DD）、`updated_at`（ISO 8601）\n7. 写入 contacts.json，输出确认\n\n纯本地操作，不触发任何发送或通知。\n\n### 4. 查询搜索\n\n1. 检查 contacts.json → 不存在则提示\"先开通虾名片\"\n2. 解析意图：姓名精确匹配 / 公司角色模糊匹配 / 标签筛选 / 关键词全文搜索\n3. 返回匹配结果，按相关度排序，以格式化文字或表格展示\n4. 底部附上本地 HTML 路径（`templates/card.html`）或在线链接（如已部署）\n\n搜不到 → 明确告知，不编造结果。\n\n### 5. 编辑更新\n\n1. 按姓名定位联系人 → 找不到则提示\"花名册里没有这个人\"，不自动创建\n2. 更新指定字段，刷新 `updated_at`\n3. **将被修改的字段名记录到 `manually_edited_fields` 数组中**（追加，不覆盖已有记录）\n4. 输出变更摘要\n\n匹配到多人 → 列出列表让用户选择。\n\n### 6. 生成名片\n\n1. 读取 profile.json（存在则基于现有内容更新）\n2. 从 Agent 记忆提炼信息：身份背景（USER.md、MEMORY.md 等）、当前项目方向、联系方式\n3. **社交姓名确认**：Agent 记忆中的称呼（如\"东总\"）是内部称呼，不等于名片对外展示的名字。如果 profile.json 中没有明确的社交姓名，**必须追问**：\"名片上想显示什么名字？\"。不可直接用内部称呼填充名片\n4. **信息优先级**：用户对话中明确说的 > profile.json > Agent 记忆 > 通用知识\n5. 生成预览（三段式文本块格式），等待用户确认\n6. 用户可多轮调整（修改内容、换措辞、加减字段），Agent 每次输出新预览\n7. 用户说\"可以了\"/\"就这样\"/\"确认\" → Agent 保存并上线：\n   - 写入 profile.json\n   - **前置检查**：读取 config.json，检查是否有 api_key 和 user_id\n   - **未注册** → 自动调 `POST {config.server.endpoint}/register`，请求体 `{name: profile.json的owner.name, agent_name: profile.json的owner.agent_name}`，将返回的 user_id 和 api_key 写入 config.json\n   - **自动调用** `PUT {config.server.endpoint}/card/{config.server.user_id}` 推送到服务器（Header `X-API-Key: {config.server.api_key}`），按 `tiers.public.fields` 筛选公开字段，**不推送** personal_notes、background\n   - 更新 profile.json 的 published_at\n   - 输出确认：\"那我保存名片了哈 ✅ 你的名片已上线：https://www.adonghub.cn/{user_id}\"\n8. 推送失败 → 名片仍保存到 profile.json，提示\"名片我先帮你存好了，但推送服务器没成功，晚点可以再说'更新名片'重试\"\n\nprofile.json 7 天内更新过 → 提示\"名片 XX 天前更新过，确认要重新生成吗？\"\n记忆信息不足 → 如实告知\"以下信息从记忆中提取，可能不完整，请确认\"。\n\n### 7. 发名片\n\n1. 检查 profile.json 是否存在且 owner.name 非空 → 不存在则提示先\"生成我的名片\"\n2. 直接输出三段式文本块（名片已在生成时自动上线，链接直接可用）\n\n### 8. 同步花名册\n\n1. 检查 config.json 中 api_key → 未配置则提示\"先生成名片，确认后会自动注册并上线\"\n2. 收集花名册中所有联系人的 `server_user_id` 字段（有此字段的才代表对方在服务器上有名片）\n3. 如果没有可同步的联系人 → 提示\"花名册中没有线上名片，无需同步\"\n4. 调用 `POST {endpoint}/sync`，Header `X-API-Key: {api_key}`，请求体：`{\"targets\":[\"user_id_1\",\"user_id_2\",...]}`\n5. 成功 → 遍历返回的 results 数组：\n   - 用 user_id 匹配花名册中的联系人（通过 server_user_id 字段）\n   - **冲突检测**"},{"path":"skill-card.md","content":"## Description:\n\nXia Card helps an agent create, manage, share, and sync a personal social card and contact roster, including recognizing agent-card:// messages to save other people's cards.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[sxd20010606-cmd](https://clawhub.ai/user/sxd20010606-cmd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal ClawHub users and their agents use Xia Card to build a shareable profile, maintain a local contact roster, import agent-card:// contacts, and publish or sync selected public card fields with the configured card server.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A fetched card response may direct the agent to install another skill.\n\nMitigation: Require explicit user confirmation and manually verify the publisher and source before installing any skill from a remote card response.\n\nRisk: The skill stores contacts and an API key locally and publishes selected profile fields to the configured server.\n\nMitigation: Review public fields before publishing, keep private notes out of published fields, and protect config.json because it can contain api_key and user_id values.\n\nRisk: Contact sync may change locally stored roster details.\n\nMitigation: Review sync conflict prompts and preserve manually_edited_fields for details that should not be overwritten by server data.\n\n## Reference(s):\n\n- [Xia Card ClawHub release](https://clawhub.ai/sxd20010606-cmd/skills/xia-card)\n- [Data format reference](references/data-format.md)\n- [Operation manual](references/manual.md)\n- [Card service endpoint](https://www.adonghub.cn)\n- [schema.org Person](https://schema.org/Person)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, json, configuration, guidance, api calls]\n\n**Output Format:** [Markdown-style text responses and JSON file updates, including a fixed three-part share block.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May update local profile, contacts, and config JSON files and call the configured card server after user confirmation.]\n\n## Skill Version(s):\n\n2.5.1 (source: ClawHub release metadata; artifact frontmatter reports 2.5.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1142,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-12T00:19:41.782Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-12T00:19:41.782Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T23:33:22.058Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}