{"id":"3dd35295-1ad3-46d6-be4b-e50b374d7467","entityType":"agent","slug":"clawhub-lexiang-lexiang-private-skills","name":"腾讯乐享知识库-私有化版本","canonicalUrl":"https://www.xpersona.co/agent/clawhub-lexiang-lexiang-private-skills","canonicalPath":"/agent/clawhub-lexiang-lexiang-private-skills","generatedAt":"2026-10-12T05:48:07.147Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T18:41:55.104Z","emptyReason":null},"description":"乐享知识库 MCP 全功能 Skill（私有化部署版）。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供乐享链接，或涉及知识库的搜索/写入/编辑/文件/配置等操作时使用。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1786rt68jz3shqts3q6e64w4h83nfyz:lexiang-private-skills","sourceUrl":"https://clawhub.ai/lexiang/lexiang-private-skills","homepage":"https://clawhub.ai/lexiang/skills/lexiang-private-skills","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/lexiang/lexiang-private-skills","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/lexiang/skills/lexiang-private-skills","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"腾讯乐享知识库-私有化版本 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-11T18:41:55.104Z","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-11T18:41:55.104Z","emptyReason":null},"stars":null,"forks":null,"downloads":1008,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.0","tractionLabel":"1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T18:41:55.091Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T18:41:55.104Z","lastCrawledAt":"2026-10-11T18:41:55.091Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T18:41:55.091Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.0","createdAt":"2026-07-09T06:24:15.650Z","changelog":"- 初始发布乐享知识库 MCP 全功能 Skill（私有化部署版）。 - 支持根据关键字和链接自动识别、路由各类知识库操作（搜索、写入、编辑、文件、配置等）。 - 严格安全规则规范：401/连接断开处理、写入确认、批量操作分批、域名使用规则等。 - 全面意图路由表与模块化参考文档设计，覆盖文档、页面、文件、会议录制等多场景。 - 明确私有化部署链接格式及认证与安全机制。","fileCount":28,"zipByteSize":57894}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1786rt68jz3shqts3q6e64w4h83nfyz:lexiang-private-skills","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s1786rt68jz3shqts3q6e64w4h83nfyz:lexiang-private-skills` 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/lexiang/lexiang-private-skills 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-lexiang-lexiang-private-skills/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/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-12T05:48:07.146Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-private-skills/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-11T18:41:55.104Z","emptyReason":null},"readme":"Skill: 腾讯乐享知识库-私有化版本\n\nOwner: lexiang\n\nSummary: 乐享知识库 MCP 全功能 Skill（私有化部署版）。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供乐享链接，或涉及知识库的搜索/写入/编辑/文件/配置等操作时使用。\n\nTags: latest:1.0.0\n\nVersion history:\n\nv1.0.0 | 2026-07-09T06:24:15.650Z | auto\n\n- 初始发布乐享知识库 MCP 全功能 Skill（私有化部署版）。\n- 支持根据关键字和链接自动识别、路由各类知识库操作（搜索、写入、编辑、文件、配置等）。\n- 严格安全规则规范：401/连接断开处理、写入确认、批量操作分批、域名使用规则等。\n- 全面意图路由表与模块化参考文档设计，覆盖文档、页面、文件、会议录制等多场景。\n- 明确私有化部署链接格式及认证与安全机制。\n\nArchive index:\n\nArchive v1.0.0: 28 files, 57894 bytes\n\nFiles: mcp.json (274b), README.md (6591b), references/base.md (9904b), references/block-schema.md (3378b), references/block-update.md (2284b), references/blocks.md (2425b), references/common-errors.md (8479b), references/connectors.md (2207b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/files.md (6145b), references/folder-sync.md (2089b), references/index.md (1913b), references/markdown-import.md (2367b), references/markdown-to-block.md (3864b), references/mcp-examples.md (5903b), references/search.md (3353b), references/setup.md (3984b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), references/writer.md (4220b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), skill-card.md (2873b), SKILL.md (7456b), _meta.json (141b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: lexiang-knowledge-private\nversion: 1.0.0\ndescription: \"乐享知识库 MCP 全功能 Skill（私有化部署版）。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供乐享链接，或涉及知识库的搜索/写入/编辑/文件/配置等操作时使用。\"\n---\n\n# 乐享知识库 MCP Skill（私有化部署版）\n\n当用户提到「**乐享**」「**知识库**」「**个人知识库**」「**我的知识库**」「**lexiang**」，或提供乐享链接，或给出 `space_id`、`entry_id`、`/spaces/`、`/pages/` 等乐享标识时，读取本 Skill。\n\n> **私有化说明**：本 Skill 适用于私有化部署的乐享实例。用户访问域名为企业自定义私有域名（如 `https://lexiang.mycompany.com`），与 SaaS 版不同，**链接直接使用私有化域名，无需判断域名结构**。\n\n---\n\n## ⛔ MANDATORY RULES — 必须遵守\n\n1. **遇到 401 / 连接断开**：立即停止重试，读取 `references/setup.md`；引导用户重新获取 token\n2. **写入操作**：必须基于用户明确提供的目标（URL/ID/名称确认），**禁止**自行遍历或猜测目标\n3. **链接生成**：必须使用 `whoami()` 返回的 `company.company_domain` 作为域名，**禁止**使用 MCP endpoint 拼接用户链接\n4. **company_from**：私有化域名已指向对应企业，链接中**不需要拼接 `company_from` 参数**\n5. **强制检索**：当用户消息同时包含「乐享/知识库」等平台词 + 「文档/论文/文章/内容/资料/笔记/之前写的/上次的/风格」等内容词时，**必须先调用 `search_kb_search` 或 `search_kb_embedding_search` 获取实际内容**，不得凭空分析或直接生成回答\n6. **大批量保护**：文件/条目数量 > 20 个时，**必须分批执行**（每批 ≤ 20 个）；操作前告知用户数量和策略，禁止一次性提交导致 token 超限，详见 `references/files.md`\n\n---\n\n## 🔗 链接生成规则（全局通用）\n\n私有化版本链接生成规则：\n\n**`{domain}` = `whoami()` 返回的 `company.company_domain`（即企业私有化域名）**\n\n链接格式：`{domain}/pages/{entry_id}`\n\n> **私有化域名已指向对应企业，无需拼接 `company_from` 参数。**\n> 如 `whoami()` 返回 `company_domain` 为 `https://lexiang.mycompany.com`，则链接为：\n> `https://lexiang.mycompany.com/pages/{entry_id}`\n\n**禁止**使用 MCP 端点域名拼接用户访问链接。\n\n---\n\n## 🛡️ 写入安全红线（全局通用）\n\n- 🚫 禁止遍历团队/知识库列表后自行选择写入目标\n- 🚫 禁止根据名称\"看起来合适\"就决定写入\n- 🚫 禁止在未确认时执行写入\n\n> 完整安全规则（允许写入的条件、工具分类）见 `references/base.md`\n\n---\n\n## 📋 意图路由表\n\n根据用户意图，Read 对应参考文件：\n\n| 用户意图 | 读取文件 | 典型触发词 |\n|---------|---------|-----------|\n| 配置乐享 / 401 错误 / Token 过期 | `references/setup.md` | 「配置乐享」「token 过期」「连不上」「401」 |\n| 搜索 / 查找 / 阅读 / 浏览 | `references/search.md` | 「找一下」「搜索」「读一下这个页面」「打开链接」 |\n| 创建文档 / 写入 / 保存 / 导入 | `references/writer.md` | 「写到乐享」「创建文档」「保存到知识库」「存到我的知识库」「保存到个人知识库」「导入」 |\n| 编辑已有页面 / Block 操作 | `references/blocks.md` | 「修改这个页面」「加个标题」「删掉这段」「在 /pages/xxx 里…」 |\n| 上传/下载文件（PDF/Word/图片等） | `references/files.md` | 「传个 PDF」「上传文件」「下载这个文件」 |\n| 导入腾讯会议 | `references/connectors.md` | 「把会议录制导入」「导入会议录制」 |\n| 数据模型 / URL 规则 / 完整安全规则 | `references/base.md` | 由上述模块内部引用 |\n\n### ⚠️ 易混淆场景\n\n| 场景 | 正确模块 | 说明 |\n|------|---------|------|\n| 用户提供 `/pages/xxx` 链接 + 要求「加内容/修改」 | `references/blocks.md` | 操作**已有页面** |\n| 用户提供 `/spaces/xxx` 链接 + 要求「写入/创建」 | `references/writer.md` | 在知识库下**新建文档** |\n| 用户提供 `/pages/xxx` 链接 + 仅要求「读/总结」 | `references/search.md` | **只读**操作 |\n| 上传 PDF/Word/图片 | `references/files.md` | 二进制文件，非文本文档 |\n| 创建 Markdown 文本文档 | `references/writer.md` | 文本内容，非二进制 |\n| 「乐享里有一篇关于 X 的文档」 | `references/search.md` → 先搜索 | **必须先检索**，不能直接回答 |\n| 「看看乐享里 XX 的写作风格」 | `references/search.md` → 先读取 | **必须先读取内容**，不能凭空分析 |\n| 「分析一下我知识库里关于 X 的内容」 | `references/search.md` → 先搜索 | **必须先检索**，不能凭空生成 |\n\n### ⚠️ 跨模块任务\n\n需要同时读取多个文件时，按流程顺序读取：\n\n- **搜索后写入**：先 `references/search.md` → 再 `references/writer.md`\n- **读取后编辑**：先 `references/search.md` → 再 `references/blocks.md`\n- **上传后记录**：先 `references/files.md` → 再 `references/writer.md`\n- **生成内容+保存**：用户要求「帮我写一篇 X 并保存到知识库/个人知识库」→ 先生成内容，再读取 `references/writer.md` 执行保存；若未指定目标，默认写入个人知识库（见 writer.md 中「未指定知识库时写入个人知识库」）\n\n---\n\n## 🔑 凭证检查\n\n执行任何乐享操作前，确认 MCP 已连接。通过 `whoami()` 检查：\n\n```\nMCP Tool: whoami\n → 成功：返回用户信息，继续执行\n → 401：读取 references/setup.md，引导用户重新获取 token 或续期\n → 连接失败：读取 references/setup.md，引导完成初始配置\n```\n\n---\n\n## 📚 参考文件索引\n\n> **按需加载**：根据意图路由表，只 Read 对应文件，无需一次性加载全部。\n\n| 文件 | 职责 |\n|------|------|\n| `references/setup.md` | Token 配置、续期、故障排查 |\n| `references/search.md` | 关键词/语义搜索、内容读取、目录浏览 |\n| `references/writer.md` | 新建文档、导入内容、公众号收藏 |\n| `references/blocks.md` | 已有页面的 Block 级增删改移 |\n| `references/files.md` | 二进制文件上传/下载（三步流程） |\n| `references/connectors.md` | 腾讯会议录制导入 |\n| `references/base.md` | 数据模型、完整安全规则、Block 结构、工具发现 |\n| `references/index.md` | 完整索引 + 按场景推荐加载顺序 |\n\n### 补充参考文档\n\n| 文档 | 说明 |\n|------|------|\n| `references/block-schema.md` | Block 类型完整字段定义 |\n| `references/mcp-examples.md` | 复杂 Block 结构示例 |\n| `references/markdown-to-block.md` | Markdown 转 Block 指南 |\n| `references/block-update.md` | 批量更新 Block 方法 |\n| `references/content-reorganize.md` | 文档结构重组方案 |\n| `references/folder-sync.md` | 文件夹同步方案 |\n| `references/markdown-import.md` | Markdown 导入详解 |\n| `references/common-errors.md` | 常见错误排查（高频错误速查表） |\n| `references/doc-templates.md` | 文档类型与大纲模板 |\n| `references/theme-config.md` | 主题配色配置 |\n| `references/skill-maintenance.md` | Skill 维护指南 |\n\n---\n\n> Skill version: **1.0.0**\n\nFile v1.0.0:README.md\n\n# lexiang-private-skills\n\n**乐享知识库 MCP Skill（私有化部署版，v1.0.0）**\n\n为 AI Agent 提供乐享知识库的全功能操作能力，包括搜索阅读、文档写入、Block 编辑、文件上传、外部导入等。\n\n> **适用场景**：企业私有化部署的乐享实例，访问域名为企业自定义域名，与 SaaS 版本独立维护。\n\n---\n\n## 快速开始\n\n访问你的乐享私有化 MCP 配置页面获取配置信息：\n\n```\nhttps://{你的乐享私有化域名}/ai/claw\n```\n\n登录后即可获取：\n- **MCP Endpoint**：填入 mcp.json 的 `url` 字段\n- **LEXIANG_TOKEN**：访问令牌（格式 `lxmcp_xxx`）\n\n填入 `mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"url\": \"你的MCP_ENDPOINT\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 目录结构\n\n```\nlexiang-private-skills/\n├── SKILL.md                  # 顶层路由入口（意图识别 → 参考文件）\n├── mcp.json                  # MCP 配置模板\n├── README.md                 # 本文件\n├── assets/                   # 静态资源\n├── references/               # 参考文档（19 份）\n│   ├── base.md               # 数据模型、URL 规则、完整安全规则、工具发现\n│   ├── setup.md              # Token 配置、续期、故障排查\n│   ├── search.md             # 关键词/语义搜索、内容读取、目录浏览\n│   ├── writer.md             # 新建文档、导入内容、公众号收藏\n│   ├── blocks.md             # 已有页面的 Block 级增删改移\n│   ├── files.md              # 二进制文件上传/下载（三步流程）\n│   ├── connectors.md         # 腾讯会议录制导入\n│   ├── index.md              # 完整索引 + 按场景推荐加载顺序\n│   ├── block-schema.md       # Block 类型完整字段定义\n│   ├── block-update.md       # 批量更新 Block 方法\n│   ├── common-errors.md      # 常见错误排查（高频错误速查表）\n│   ├── content-reorganize.md # 文档结构重组方案\n│   ├── doc-templates.md      # 文档类型与大纲模板\n│   ├── folder-sync.md        # 文件夹同步方案\n│   ├── markdown-import.md    # Markdown 导入详解\n│   ├── markdown-to-block.md  # Markdown 转 Block 指南\n│   ├── mcp-examples.md       # 复杂 Block 结构示例\n│   ├── skill-maintenance.md  # Skill 维护指南\n│   └── theme-config.md       # 主题配色配置\n└── scripts/                  # 辅助脚本\n    ├── upload-files.py       # 批量文件上传（支持单文件/文件夹/并行/dry-run）\n    ├── sync-folder.ts        # 文件夹增量同步到乐享知识库\n    └── test_upload_files.py  # 上传脚本测试\n```\n\n---\n\n## 模块说明\n\n根据用户意图，Agent 读取 `references/` 下对应的参考文件：\n\n| 用户意图 | 参考文件 | 典型触发词 |\n|---------|---------|-----------|\n| 配置乐享 / 401 错误 / Token 过期 | `references/setup.md` | 「配置乐享」「token 过期」「连不上」「401」 |\n| 搜索 / 查找 / 阅读 / 浏览 | `references/search.md` | 「找一下」「搜索」「读一下这个页面」 |\n| 创建文档 / 写入 / 保存 / 导入 | `references/writer.md` | 「写到乐享」「创建文档」「保存到知识库」 |\n| 编辑已有页面 / Block 操作 | `references/blocks.md` | 「修改这个页面」「加个标题」「删掉这段」 |\n| 上传/下载文件 | `references/files.md` | 「传个 PDF」「上传文件」「下载这个文件」 |\n| 导入腾讯会议 | `references/connectors.md` | 「导入会议录制」 |\n| 数据模型 / URL 规则 / 安全规则 | `references/base.md` | 由上述模块内部引用 |\n\n> 完整路由规则和易混淆场景见 `SKILL.md`\n\n---\n\n## 核心规则\n\n- **写入安全**：必须基于用户明确提供的目标（URL/ID/确认），禁止自行遍历或猜测\n- **链接生成**：使用 `whoami().company.company_domain` 作为私有化域名直接拼接，无需追加 `company_from` 参数\n- **401 处理**：不重试，引导用户打开 `{私有化域名}/ai/claw` 续期（点续期按钮即可恢复，无需重新配置）\n- **强制检索**：用户提到「乐享里的文档/内容」时，必须先搜索再回答，禁止凭空生成\n\n> 完整规则详见 `SKILL.md` 和 `references/base.md`\n\n---\n\n## 辅助脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `scripts/upload-files.py` | 批量文件上传（支持单文件/文件夹/并行/dry-run） |\n| `scripts/sync-folder.ts` | 文件夹增量同步到乐享知识库 |\n| `scripts/test_upload_files.py` | 上传脚本测试 |\n\n```bash\n# 单文件上传\npython scripts/upload-files.py --files doc.md --entry-id <parent_entry_id>\n\n# 文件夹批量上传（5 并行）\npython scripts/upload-files.py --folder ./docs --entry-id <parent_entry_id> --parallel 5\n```\n\n---\n\n## 参考文档\n\n### 主参考文档（按意图路由加载）\n\n| 文档 | 说明 |\n|------|------|\n| `references/base.md` | 数据模型、URL 规则、完整安全规则、工具发现 |\n| `references/setup.md` | Token 配置、续期、故障排查 |\n| `references/search.md` | 关键词/语义搜索、内容读取、目录浏览 |\n| `references/writer.md` | 新建文档、导入内容、公众号收藏 |\n| `references/blocks.md` | 已有页面的 Block 级增删改移 |\n| `references/files.md` | 二进制文件上传/下载（三步流程） |\n| `references/connectors.md` | 腾讯会议录制导入 |\n| `references/index.md` | 完整索引 + 按场景推荐加载顺序 |\n\n### 补充参考文档\n\n| 文档 | 说明 |\n|------|------|\n| `references/block-schema.md` | Block 类型完整字段定义 |\n| `references/mcp-examples.md` | 复杂 Block 结构示例 |\n| `references/markdown-to-block.md` | Markdown 转 Block 指南 |\n| `references/block-update.md` | 批量更新 Block 方法 |\n| `references/content-reorganize.md` | 文档结构重组方案 |\n| `references/folder-sync.md` | 文件夹同步方案 |\n| `references/markdown-import.md` | Markdown 导入详解 |\n| `references/common-errors.md` | 常见错误排查（高频错误速查表） |\n| `references/doc-templates.md` | 文档类型与大纲模板 |\n| `references/theme-config.md` | 主题配色配置 |\n| `references/skill-maintenance.md` | Skill 维护指南 |\n\n---\n\n## 相关链接\n\n- MCP 协议：https://modelcontextprotocol.io\n\nFile v1.0.0:scripts/README.md\n\n# Lexiang Scripts\n\n乐享文档写入辅助脚本集合。\n\n## 安装依赖\n\n### TypeScript 脚本\n\n```bash\nnpm install -g ts-node typescript\nnpm install @types/node\n```\n\n### Python 脚本\n\n```bash\npip install aiohttp requests\n```\n\n## 脚本列表\n\n### sync-folder.ts\n\n本地文件夹增量同步到乐享知识库。\n\n```bash\n# Dry run 模式（仅生成计划）\nnpx ts-node sync-folder.ts --local ./docs --entry-id abc123 --dry-run\n\n# 完整参数\nnpx ts-node sync-folder.ts \\\n  --local ./docs \\\n  --entry-id <parent_entry_id> \\\n  --space-id <space_id> \\\n  --state-file .sync-state.json \\\n  --dry-run\n```\n\n### upload-files.py\n\n并行上传文件到乐享。\n\n```bash\n# 单文件上传\npython upload-files.py --files doc1.md doc2.pdf --entry-id abc123\n\n# 文件夹批量上传\npython upload-files.py --folder ./docs --entry-id abc123 --parallel 5\n\n# 输出上传计划到 JSON\npython upload-files.py --folder ./docs --entry-id abc123 --output plan.json --dry-run\n```\n\n\n\n## 工作流示例\n\n### 1. 项目文档同步\n\n```bash\n# 1. 首次同步（dry run 检查）\nnpx ts-node sync-folder.ts --local ./project-docs --entry-id root123 --dry-run\n\n# 2. 执行同步\n# 将生成的 MCP 调用序列提供给 AI 助手执行\n\n# 3. 后续增量同步\n# 脚本会自动检测变更，只同步修改的文件\n```\n\n### 2. Markdown 文档导入\n\n```bash\n# 1. 生成上传计划\npython upload-files.py --folder ./markdown-docs --entry-id target123 --output plan.json\n\n# 2. 查看计划\ncat plan.json\n\n# 3. 执行上传（通过 AI 助手）\n# 将 plan.json 中的 MCP 调用提供给 AI 助手\n```\n\n## 注意事项\n\n1. **MCP 调用需要通过 AI 助手执行**：脚本生成 MCP 调用参数，实际执行需要 AI 助手的 MCP 能力\n2. **文件上传是 3 步流程**：apply_upload → HTTP PUT → commit_upload\n3. **同步状态文件**：`.lexiang-sync-state.json` 记录同步状态，请勿删除\n4. **大文件建议分批**：单次 MCP 调用的数据量有限制\n5. **Block 写入使用 MCP 工具**：直接调用 `block_convert_content_to_blocks` 将 Markdown/HTML 转换为块结构，无需手动构建\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn72bkq17fhyp4f0c7c8mvqq8d86zrsm\",\n  \"slug\": \"lexiang-private-skills\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1783578255650\n}\n\nFile v1.0.0:references/base.md\n\n# 乐享 MCP 基础知识（私有化部署版）\n\n> 本文件为所有功能模块的共享基础层，包含数据模型、URL 规则、安全约束、工具发现等通用知识。\n> **核心规则（URL 生成 + 写入安全红线）已在 SKILL.md 中内联，本文件为详细参考。**\n\n---\n\n## ⛔ 必读（调用前必须理解）\n\n1. 本服务**直接暴露所有业务工具**（如 `team_list_teams`、`search_kb_search` 等），可直接调用\n2. 调用前先确认工具参数定义，**以 MCP 返回的 schema 为准**\n3. 不确定参数时，使用 `get_tool_schema(tool_name=\"xxx\")` 获取最新定义\n\n---\n\n## 📊 数据模型\n\n### 核心概念\n\n| 概念 | 说明 |\n|------|------|\n| **Team（团队）** | 顶级组织单元，一个团队下可以有多个知识库(Space) |\n| **Space（知识库）** | 知识的容器，属于某个团队，包含多个条目(Entry)，有 `root_entry_id` 作为根节点 |\n| **Entry（条目）** | 知识库中的内容单元，可以是页面(page)、文件夹(folder)或文件(file)，支持树形结构(parent_id) |\n| **File（文件）** | 附件类型的条目，如 PDF、Word、图片等 |\n\n### 层级关系\n\n```\nTeam → Space → Entry（树形结构，root_entry_id 为根）\n                  ├── page（页面）\n                  ├── folder（文件夹）\n                  └── file（文件）\n```\n\n### URL 规则（私有化版本）\n\n`{domain}` = `whoami()` 返回的 `company.company_domain`（即企业私有化域名，如 `https://lexiang.mycompany.com`）\n\n> **⛔ 严禁使用 MCP endpoint 拼接任何用户可访问的链接！** MCP 域名仅用于接口调用，不是用户访问地址。\n\n| 资源 | URL 格式 |\n|------|----------|\n| 团队首页 | `{domain}/t/{team_id}/spaces` |\n| 知识库 | `{domain}/spaces/{space_id}` |\n| 知识条目 | `{domain}/pages/{entry_id}` |\n\n**链接生成规则（私有化版本，所有操作通用）：**\n\n私有化域名已指向对应企业，**直接使用 `{domain}` 拼接，无需附加 `company_from` 参数**：\n\n```\n链接 = {domain}/pages/{entry_id}\n```\n\n示例：`whoami()` 返回 `company_domain` 为 `https://lexiang.mycompany.com`，则：\n- 条目链接：`https://lexiang.mycompany.com/pages/abc123`\n- 知识库链接：`https://lexiang.mycompany.com/spaces/xyz789`\n\n### URL 解析规则\n\n当用户提供链接时，从 URL 路径中提取 ID（**忽略查询参数**）：\n\n| URL 路径 | 提取方式 |\n|----------|----------|\n| `/spaces/{space_id}` | 取 `spaces/` 后面的部分作为 `space_id` |\n| `/pages/{entry_id}` | 取 `pages/` 后面的部分作为 `entry_id` |\n| `/t/{team_id}/spaces` | 取 `t/` 后面的部分作为 `team_id` |\n\n---\n\n## 🛡️ 写入操作安全规则\n\n> **核心原则**：写入、修改、删除操作 **必须基于用户明确提供的目标信息**，禁止 Agent 自行选择或猜测目标。\n\n### 🚫 绝对禁止\n\n1. 禁止遍历团队/知识库列表后自行选择写入目标\n2. 禁止根据名称\"看起来合适\"就决定写入\n3. 禁止在未确认时执行写入\n\n### ✅ 允许写入的条件（满足之一即可）\n\n| 条件 | 示例 |\n|------|------|\n| 用户提供了明确 URL | `\"写到这里：https://lexiang.mycompany.com/spaces/xxx\"` |\n| 用户提供了明确 ID | `\"写入 space_id 为 xxx 的知识库\"` |\n| 用户指定名称 + Agent 回显确认 | Agent 搜到后展示详情，用户确认 |\n| 用户要求保存到个人知识库且 `whoami` 返回了个人知识库 | `\"保存到我的知识库\"` → 自动写入个人知识库 |\n\n### 写入 vs 读取工具分类\n\n**写入操作**（需满足安全规则）：\n`entry_create_entry`、`entry_import_content`、`entry_import_content_to_entry`、`block_update_block`、`block_update_blocks`、`block_create_block_descendant`、`block_delete_block`、`block_delete_block_children`、`block_move_blocks`、`entry_rename_entry`、`entry_move_entry`、`file_apply_upload`、`file_commit_upload`、`file_create_hyperlink`\n\n**只读操作**（不受安全规则限制，可直接执行）：\n`team_list_teams`、`team_describe_team`、`team_list_frequent_teams`、`space_list_spaces`、`space_describe_space`、`entry_list_children`、`block_list_block_children`、`search_kb_search`、`search_kb_embedding_search`、`space_list_recently_spaces`、`entry_list_latest_entries`、`entry_describe_ai_parse_content`、`file_describe_file`、`file_download_file`、`whoami`\n\n---\n\n## 🔍 工具发现与调用\n\n本服务**直接暴露所有业务工具**，可直接调用。同时提供以下辅助元工具：\n\n| 元工具 | 用途 |\n|--------|------|\n| `list_tool_categories` | 列出所有工具分类及其工具列表 |\n| `search_tools` | 按关键词或分类搜索工具 |\n| `get_tool_schema` | 获取具体工具的完整参数定义 |\n\n**标准工作流：**\n\n```\n1. 直接调用已知工具：team_list_teams()、search_kb_search(keyword=\"xxx\") 等\n2. 不确定参数时：get_tool_schema(tool_name=\"xxx\") → 获取参数定义\n3. 不确定工具名时：search_tools(query=\"关键词\") → 找到工具名\n```\n\n---\n\n## 🧩 Block 结构规则\n\n### 🍃 叶子节点（不能有 children）\n\n| 类型 | 说明 |\n|------|------|\n| `h1` ~ `h5` | 标题块 |\n| `code` | 代码块 |\n| `image` | 图片块 |\n| `divider` | 分割线 |\n| `mermaid` | Mermaid 图表 |\n| `plantuml` | PlantUML 图表 |\n| `attachment` | 附件块 |\n| `video` | 视频块 |\n\n### 📦 容器节点（必须指定 children）\n\n| 类型 | children 内容 |\n|------|--------------|\n| `callout` | **必须**，内容块 |\n| `toggle` | **必须**，折叠内容 |\n| `table` | **必须**，table_cell |\n| `table_cell` | **必须**，内容块 |\n| `column_list` | **必须**，column |\n| `column` | **必须**，内容块 |\n\n### 可选 children 节点\n\n`p`、`bulleted_list`、`numbered_list`、`task` 可嵌套子内容，children 为可选。\n\n### 重要：标题与内容的平级关系\n\n标题和其下的内容应该是**平级**的，通过顶层 `children` 的顺序来体现文档结构：\n\n```json\n{\n  \"children\": [\"h2_1\", \"para_1\", \"para_2\", \"h2_2\", \"para_3\"],\n  \"descendant\": [\n    {\"block_id\": \"h2_1\", \"block_type\": \"h2\", \"heading2\": {...}},\n    {\"block_id\": \"para_1\", \"block_type\": \"p\", \"text\": {...}},\n    {\"block_id\": \"para_2\", \"block_type\": \"p\", \"text\": {...}},\n    {\"block_id\": \"h2_2\", \"block_type\": \"h2\", \"heading2\": {...}},\n    {\"block_id\": \"para_3\", \"block_type\": \"p\", \"text\": {...}}\n  ]\n}\n```\n\n---\n\n## 📝 内容读取工具选择\n\n| 工具 | 返回内容 | 用途 |\n|------|----------|------|\n| `entry_describe_entry` | 条目元信息（ID、名称、类型、创建时间等） | 获取基本信息、后续操作前确认 |\n| `entry_describe_ai_parse_content` | **条目正文内容** | 读取实际内容进行摘要/分析/处理 |\n\n> `entry_describe_entry` **不包含正文内容**。需要阅读/总结/分析文档时，必须使用 `entry_describe_ai_parse_content`。\n\n---\n\n## ⚙️ 通用优化技巧\n\n### `_mcp_fields` 字段筛选\n\n所有工具均支持 `_mcp_fields` 参数，只返回需要的字段，减少 token 消耗：\n\n```\n# 只获取条目 ID 和名称\nentry_list_children(parent_id=\"xxx\", _mcp_fields=\"entries.id,entries.name\")\n\n# 只获取搜索结果的标题和链接\nsearch_kb_search(keyword=\"xxx\", _mcp_fields=\"items.target_id,items.title,items.target_type\")\n```\n\n---\n\n## 📚 文档模板参考\n\n写入文档前，先确定文档类型，按对应大纲组织内容：\n\n| 类型 | 适用场景 | 核心结构 |\n|------|---------|---------|\n| 推广文案型 | 功能推广、工具介绍 | callout(价值) → 痛点 → 方案 → 对比 → 上手 |\n| 技术文档型 | API 文档、开发指南 | 概述 → 快速开始 → 详细说明(参数表) → 示例 |\n| 操作指南型 | 使用教程、配置指南 | callout(目标) → 前置准备 → 操作步骤 → 验证 |\n\n**Callout 语义映射：**\n\n| 语义 | 类型 | 配色 |\n|------|------|------|\n| 核心/重要/价值 | primary | `#E3F2FD` |\n| 提示/建议/tips | tip | `#FFF3E0` |\n| 成功/完成 | success | `#E8F5E9` |\n| 警告/注意/风险 | warning | `#FFF8E1` |\n| 错误/禁止/危险 | error | `#FFEBEE` |\n\n> 完整模板见 `references/doc-templates.md`\n\n---\n\n## 📎 辅助资源索引\n\n### 参考文档（references/）\n\n| 文档 | 说明 |\n|------|------|\n| `references/block-schema.md` | Block 类型完整字段定义 |\n| `references/mcp-examples.md` | 复杂 Block 结构示例 |\n| `references/markdown-to-block.md` | Markdown 转 Block 指南 |\n| `references/block-update.md` | 批量更新 Block 方法 |\n| `references/content-reorganize.md` | 文档结构重组方案 |\n| `references/folder-sync.md` | 文件夹同步方案 |\n| `references/markdown-import.md` | Markdown 导入详解 |\n| `references/common-errors.md` | 常见错误排查（高频错误速查表） |\n| `references/doc-templates.md` | 文档类型与大纲模板 |\n| `references/theme-config.md` | 主题配色配置 |\n\n### 辅助脚本（scripts/）\n\n| 脚本 | 说明 |\n|------|------|\n| `scripts/upload-files.py` | 批量文件上传（支持单文件/文件夹/并行） |\n| `scripts/sync-folder.ts` | 文件夹增量同步 |\n\n---\n\n## ❓ 常见问题\n\n**Q: 如何选择 Markdown 导入方式？**\n- `file_apply_upload` → PUT → `file_commit_upload`：保留原始文件格式，支持版本管理，适合文档归档\n- `entry_import_content`：转换为 Block 结构，可在线编辑，适合协作场景\n\n**Q: Block ID 如何管理？**\n客户端传入的 `block_id` 是临时标识，用于在单次调用中建立块间关系。服务端返回实际 ID 映射，后续更新操作使用服务端返回的 ID。\n\n**Q: 表格单元格如何排序？**\n`children` 数组按**从左到右、从上到下**顺序排列。例如 2×2 表格：`[row1_col1, row1_col2, row2_col1, row2_col2]`\n\n> 更多错误排查见 `references/common-errors.md`\n\nFile v1.0.0:references/block-schema.md\n\n# Block 类型速查\n\n## 支持的块类型\n\n| 类型 | block_type | 说明 | 支持 children |\n|------|-----------|------|--------------|\n| 段落 | `p` | 普通文本段落 | ✓ |\n| 一级标题 | `h1` | 标题 | ✗ |\n| 二级标题 | `h2` | 标题 | ✗ |\n| 三级标题 | `h3` | 标题 | ✗ |\n| 四级标题 | `h4` | 标题 | ✗ |\n| 五级标题 | `h5` | 标题 | ✗ |\n| 无序列表 | `bulleted_list` | 项目符号列表 | ✓ |\n| 有序列表 | `numbered_list` | 数字编号列表 | ✓ |\n| 代码块 | `code` | 代码 | ✗ |\n| 分割线 | `divider` | 水平分割线 | ✗ |\n| 折叠块 | `toggle` | 可展开/折叠内容 | ✓ |\n| 高亮块 | `callout` | 带颜色和图标的提示框 | ✓ (必填) |\n| 任务 | `task` | 任务项 | ✓ |\n| 分栏容器 | `column_list` | 多列布局容器 | ✓ (必填) |\n| 分栏列 | `column` | 单列内容 | ✓ (必填) |\n| 表格 | `table` | 表格 | ✓ (必填) |\n| 表格单元格 | `table_cell` | 表格单元格 | ✓ (必填) |\n| Mermaid | `mermaid` | Mermaid 图表 | ✗ |\n| PlantUML | `plantuml` | PlantUML 图表 | ✗ |\n\n---\n\n## 文本结构\n\n```json\n{\n  \"elements\": [\n    {\n      \"text_run\": {\n        \"content\": \"文本内容\",\n        \"text_style\": {\n          \"bold\": true,\n          \"italic\": false,\n          \"underline\": false,\n          \"strikethrough\": false,\n          \"inline_code\": false,\n          \"link\": \"https://example.com\",\n          \"text_color\": \"#333333\",\n          \"background_color\": \"#FFFFFF\"\n        }\n      }\n    }\n  ],\n  \"style\": {\n    \"align\": \"left\",\n    \"background_color\": \"#FFFFFF\",\n    \"language\": \"javascript\",\n    \"wrap\": false\n  }\n}\n```\n\n---\n\n## 块字段映射\n\n| block_type | 内容字段 |\n|-----------|---------|\n| p | text |\n| h1 | heading1 |\n| h2 | heading2 |\n| h3 | heading3 |\n| h4 | heading4 |\n| h5 | heading5 |\n| bulleted_list | bulleted |\n| numbered_list | numbered |\n| code | code |\n| toggle | toggle |\n| callout | callout |\n| task | task |\n| table | table |\n| table_cell | table_cell |\n| column_list | column_list |\n| column | column |\n| divider | divider |\n| mermaid | mermaid |\n| plantuml | plantuml |\n\n---\n\n## 特殊块结构\n\n### callout\n\n```json\n{\n  \"callout\": {\n    \"color\": \"#E3F2FD\",\n    \"icon\": \"1f680\"\n  }\n}\n```\n\n### table\n\n```json\n{\n  \"table\": {\n    \"row_size\": 3,\n    \"column_size\": 2,\n    \"column_width\": [300, 400],\n    \"header_row\": true,\n    \"header_column\": false\n  }\n}\n```\n\n### table_cell\n\n```json\n{\n  \"table_cell\": {\n    \"background_color\": \"#F5F5F5\",\n    \"align\": \"left\",\n    \"vertical_align\": \"middle\",\n    \"row_span\": 1,\n    \"col_span\": 1\n  }\n}\n```\n\n### column_list / column\n\n```json\n{\n  \"column_list\": {\"column_size\": 2}\n}\n\n{\n  \"column\": {\"width_ratio\": 0.5}\n}\n```\n\n### mermaid / plantuml\n\n```json\n{\n  \"mermaid\": {\n    \"content\": \"graph TD\\n    A --> B\"\n  }\n}\n\n{\n  \"plantuml\": {\n    \"content\": \"@startuml\\nA -> B\\n@enduml\"\n  }\n}\n```\n\n### task\n\n```json\n{\n  \"task\": {\n    \"name\": \"任务名称\",\n    \"done\": false,\n    \"assignees\": [{\"staff_id\": \"user_123\"}],\n    \"due_at\": {\"date\": \"2026-01-25\", \"time\": \"18:00\"}\n  }\n}\n```\n\n---\n\n## 注意事项\n\n1. **容器类块必须指定 children**: callout, table, table_cell, column_list, column\n2. **表格 children 顺序**: 从左到右、从上到下\n3. **block_id 为临时 ID**: 服务端返回实际 ID 映射\n4. **叶子节点不支持 children**: h1-h5, code, divider, mermaid, plantuml\n\nFile v1.0.0:references/block-update.md\n\n# 场景：Block 增量更新\n\n批量更新已有文档中的多个块内容或样式。\n\n## 批量更新 API\n\n```\nMCP Tool: lexiang.block_update_blocks\nArguments: {\n  \"entry_id\": \"<entry_id>\",\n  \"updates\": {\n    \"<block_id_1>\": { <更新操作> },\n    \"<block_id_2>\": { <更新操作> },\n    ...\n  }\n}\n```\n\n**限制**: 单次最多更新 20 个块\n\n---\n\n## 更新操作类型\n\n### 更新文本内容\n\n```json\n{\n  \"update_text\": {\n    \"text\": {\n      \"elements\": [\n        {\"text_run\": {\"content\": \"新内容\", \"text_style\": {\"bold\": true}}}\n      ]\n    }\n  }\n}\n```\n\n### 更新块样式\n\n```json\n{\n  \"update_style\": {\n    \"style\": {\n      \"background_color\": \"#FFF8E1\",\n      \"align\": \"center\"\n    }\n  }\n}\n```\n\n### 更新任务状态\n\n```json\n{\n  \"update_task\": {\n    \"done\": true,\n    \"name\": \"任务名称\"\n  }\n}\n```\n\n### 插入文本\n\n```json\n{\n  \"insert_text\": {\n    \"position\": {\"index\": 5},\n    \"text\": \"插入的文本\",\n    \"text_style\": {\"italic\": true}\n  }\n}\n```\n\n### 删除文本\n\n```json\n{\n  \"delete_text\": {\n    \"range\": {\"start_index\": 0, \"end_index\": 10}\n  }\n}\n```\n\n---\n\n## 完整示例\n\n```\nMCP Tool: lexiang.block_update_blocks\nArguments: {\n  \"entry_id\": \"abc123\",\n  \"updates\": {\n    \"block_001\": {\n      \"update_text\": {\n        \"text\": {\n          \"elements\": [{\"text_run\": {\"content\": \"更新后的标题\", \"text_style\": {\"bold\": true}}}]\n        }\n      }\n    },\n    \"block_002\": {\n      \"update_style\": {\n        \"style\": {\"background_color\": \"#E8F5E9\"}\n      }\n    },\n    \"block_003\": {\n      \"update_task\": {\"done\": true}\n    }\n  }\n}\n```\n\n---\n\n## 使用辅助工具\n\n```typescript\nimport { UpdateBlocksBuilder } from './scripts/block-helper';\n\nconst updater = new UpdateBlocksBuilder()\n  .updateText('block_1', '新标题', { bold: true })\n  .updateStyle('block_2', { background_color: '#E8F5E9' })\n  .updateTask('block_3', true)\n  .insertText('block_4', 0, '前缀: ')\n  .deleteText('block_5', 0, 5);\n\nconst mcpCall = updater.toMCPCall(entryId);\n// { tool: 'lexiang.block_update_blocks', args: {...} }\n```\n\n---\n\n## 注意事项\n\n1. 每个块在单次请求中只能执行一种更新操作\n2. 如需同时更新文本和样式，使用 `update_text` 并在 text.style 中指定样式\n3. 更新前需先获取 block_id，可通过 `list_block_children` 获取\n\nFile v1.0.0:references/blocks.md\n\n# 乐享 Block 操作\n\n> **基础知识**：数据模型、URL 规则、写入安全规则、Block 完整类型定义见 `references/base.md`。\n> **前置条件**：本 skill 需要已配置乐享 MCP 连接。如未配置，请先读取 `references/setup.md`。\n> **遇到 401 错误**：不要重试，读取 `references/setup.md` 引导用户续期（点击续期按钮即可恢复，无需重新配置）。\n> **安全规则**：Block 写入操作必须基于用户明确提供的目标信息，禁止 Agent 自行遍历或猜测写入目标。\n\n---\n\n## 工具概览\n\n### 🧩 Block 操作\n- `block_convert_content_to_blocks` — Markdown/HTML 转 Block 结构\n- `block_create_block_descendant` — 创建 Block 结构\n- `block_update_block` — 单块更新\n- `block_update_blocks` — 批量更新\n- `block_move_blocks` — 移动 Block\n- `block_delete_block_children` — 删除子节点\n- `block_delete_block` — 删除指定 Block（含子孙）\n- `block_describe_block` — 获取单个 Block 详情\n- `block_list_block_children` — 读取 Block 内容\n\n---\n\n## Block 结构核心规则\n\n> 完整 Block 类型定义（含 attachment、video 等）见 `references/base.md` 或 `references/block-schema.md`。\n\n### 🍃 叶子节点（不能有 children）\n标题块(h1~h5)、代码块(code)、图片块(image)、分割线(divider)、图表块(mermaid/plantuml)、附件块(attachment)、视频块(video)\n\n### 📦 容器节点（必须指定 children）\n提示框(callout)、表格(table/table_cell)、分栏布局(column_list/column)、折叠块(toggle)\n\n---\n\n## ⚠️ 核心注意事项\n\n1. **Block ID 映射**：`block_id` 为客户端临时 ID，服务端返回实际 ID 映射\n2. **标题与内容平级**：标题块不能包含 children，通过顶层 `children` 顺序体现文档结构\n3. **`_mcp_fields` 优化**：所有工具支持 `_mcp_fields` 参数选择返回字段，减少 token 消耗\n4. 参数不确定时以 `get_tool_schema(tool_name=\"xxx\")` 返回为准\n\n---\n\n## 参考文档\n\n| 文档 | 说明 |\n|------|------|\n| `references/block-schema.md` | Block 类型完整字段定义 |\n| `references/mcp-examples.md` | 复杂 Block 结构示例 |\n| `references/markdown-to-block.md` | Markdown 转 Block 指南 |\n| `references/block-update.md` | 批量更新 Block 方法 |\n| `references/content-reorganize.md` | 文档结构重组方案 |\n| `references/common-errors.md` | 常见错误排查 |\n\nFile v1.0.0:references/common-errors.md\n\n# 乐享 MCP 常见错误和修复\n\n本文档列出 Agent 调用乐享 MCP 时的常见错误和修复方法。\n\n---\n\n## ⚠️ 高频错误速查\n\n| 错误 | 原因 | 修复 |\n|------|------|------|\n| 文件上传失败 | 缺少 size 参数 | **必须指定文件大小（字节数）** |\n| 更新文件失败 | file_id 未传或 parent_entry_id 错误 | 更新时 parent_entry_id = 当前文件 entry_id |\n| 块创建报错 | h1/h2/code 等叶子节点包含 children | **标题、代码块等不支持 children** |\n| 块创建不完整 | 缺少顶层 children | 确保 children 包含所有顶层块 ID |\n\n---\n\n## 错误一：文件上传缺少 size\n\n### 错误表现\n\n```\n调用 apply_upload 后返回错误或上传失败\n```\n\n### 错误参数\n\n```json\n{\n  \"parent_entry_id\": \"abc123\",\n  \"name\": \"document.md\",\n  \"mime_type\": \"text/markdown\",\n  \"upload_type\": \"PRE_SIGNED_URL\"\n  // ❌ 缺少 size\n}\n```\n\n### 正确参数\n\n```json\n{\n  \"parent_entry_id\": \"abc123\",\n  \"name\": \"document.md\",\n  \"mime_type\": \"text/markdown\",\n  \"size\": 1234,  // ✅ 必须指定文件大小（字节数）\n  \"upload_type\": \"PRE_SIGNED_URL\"\n}\n```\n\n### 如何获取文件大小\n\n```typescript\n// TypeScript/JavaScript\nconst fs = require('fs');\nconst size = fs.statSync(filePath).size;\n```\n\n```python\n# Python\nimport os\nsize = os.path.getsize(file_path)\n```\n\n---\n\n## 错误二：更新文件时参数混淆\n\n### 错误表现\n\n```\n更新文件时创建了新文件，或报参数错误\n```\n\n### 关键区别\n\n| 场景 | parent_entry_id | file_id |\n|------|-----------------|---------|\n| **新建文件** | 父目录的 entry_id | 不传 |\n| **更新文件** | **当前文件自己的 entry_id** | **必传**（从 describe_entry 获取） |\n\n### 新建文件\n\n```json\n{\n  \"parent_entry_id\": \"<父目录 entry_id>\",\n  \"name\": \"new-doc.md\",\n  \"mime_type\": \"text/markdown\",\n  \"size\": 1234,\n  \"upload_type\": \"PRE_SIGNED_URL\"\n  // 不传 file_id\n}\n```\n\n### 更新文件\n\n```json\n{\n  \"parent_entry_id\": \"<当前文件自己的 entry_id>\",  // ⚠️ 注意：不是父目录！\n  \"name\": \"existing-doc.md\",\n  \"mime_type\": \"text/markdown\",\n  \"size\": 5678,\n  \"file_id\": \"<从 describe_entry 获取的 target_id>\",  // ⚠️ 必传\n  \"upload_type\": \"PRE_SIGNED_URL\"\n}\n```\n\n### 获取 file_id 的方法\n\n```\nStep 1: 调用 describe_entry 获取条目详情\nMCP Tool: lexiang.entry_describe_entry\nArguments: { \"entry_id\": \"<文件条目 entry_id>\" }\n\nStep 2: 从返回值中提取\n返回: { \"entry\": { \"target_id\": \"<这就是 file_id>\", ... } }\n```\n\n---\n\n## 错误三：叶子节点包含 children\n\n### 错误表现\n\n```\n块创建失败，或文档结构异常\n```\n\n### 叶子节点类型（不支持 children）\n\n- `h1`, `h2`, `h3`, `h4`, `h5` - 标题块\n- `code` - 代码块\n- `divider` - 分割线\n- `image` - 图片块\n- `attachment` - 附件块\n- `video` - 视频块\n- `mermaid` - Mermaid 图表\n- `plantuml` - PlantUML 图表\n\n### 错误示例\n\n```json\n{\n  \"block_id\": \"h2_1\",\n  \"block_type\": \"h2\",\n  \"heading2\": {\"elements\": [{\"text_run\": {\"content\": \"标题\"}}]},\n  \"children\": [\"para_1\", \"para_2\"]  // ❌ 标题块不支持 children！\n}\n```\n\n### 正确示例\n\n```json\n// 标题块（叶子节点，无 children）\n{\n  \"block_id\": \"h2_1\",\n  \"block_type\": \"h2\",\n  \"heading2\": {\"elements\": [{\"text_run\": {\"content\": \"标题\"}}]}\n  // ✅ 不要 children\n}\n\n// 段落块作为顶层块排列\n{\n  \"block_id\": \"para_1\",\n  \"block_type\": \"p\",\n  \"text\": {\"elements\": [{\"text_run\": {\"content\": \"段落内容\"}}]}\n}\n```\n\n### 正确的文档结构\n\n标题和其下的内容应该是**平级**的，通过顶层 children 的顺序来体现层级：\n\n```json\n{\n  \"entry_id\": \"xxx\",\n  \"descendant\": [\n    {\"block_id\": \"h2_1\", \"block_type\": \"h2\", \"heading2\": {...}},\n    {\"block_id\": \"para_1\", \"block_type\": \"p\", \"text\": {...}},\n    {\"block_id\": \"para_2\", \"block_type\": \"p\", \"text\": {...}},\n    {\"block_id\": \"h2_2\", \"block_type\": \"h2\", \"heading2\": {...}},\n    {\"block_id\": \"para_3\", \"block_type\": \"p\", \"text\": {...}}\n  ],\n  \"children\": [\"h2_1\", \"para_1\", \"para_2\", \"h2_2\", \"para_3\"]  // ✅ 顺序体现结构\n}\n```\n\n---\n\n## 错误四：容器块缺少 children\n\n### 容器块类型（必须有 children）\n\n- `callout` - 高亮块\n- `table` - 表格（children 是 table_cell）\n- `table_cell` - 表格单元格（children 是内容块）\n- `column_list` - 分栏容器（children 是 column）\n- `column` - 分栏列（children 是内容块）\n- `toggle` - 折叠块\n\n### 错误示例\n\n```json\n{\n  \"block_id\": \"callout_1\",\n  \"block_type\": \"callout\",\n  \"callout\": {\"color\": \"#E3F2FD\", \"icon\": \"1f680\"}\n  // ❌ 缺少 children\n}\n```\n\n### 正确示例\n\n```json\n// Callout 必须有内容子块\n{\n  \"block_id\": \"callout_1\",\n  \"block_type\": \"callout\",\n  \"callout\": {\"color\": \"#E3F2FD\", \"icon\": \"1f680\"},\n  \"children\": [\"callout_1_p\"]  // ✅ 指向内容块\n},\n{\n  \"block_id\": \"callout_1_p\",\n  \"block_type\": \"p\",\n  \"text\": {\"elements\": [{\"text_run\": {\"content\": \"提示内容\"}}]}\n}\n```\n\n---\n\n## 使用校验工具\n\n### 导入校验器\n\n```typescript\nimport {\n  validateApplyUpload,\n  validateCreateBlockDescendant,\n  fixApplyUploadArgs,\n  fixCreateBlockDescendantArgs,\n  formatValidationResult\n} from './scripts/mcp-validator';\n```\n\n### 校验上传参数\n\n```typescript\nconst result = validateApplyUpload(\n  { parent_entry_id: 'abc', name: 'doc.md' },\n  { isUpdate: false }\n);\n\nconsole.log(formatValidationResult(result));\n// 输出错误列表和修复建议\n```\n\n### 校验块创建参数\n\n```typescript\nconst result = validateCreateBlockDescendant({\n  entry_id: 'xxx',\n  descendant: [\n    { block_id: 'h1', block_type: 'h1', heading1: {...}, children: ['p1'] }  // 错误\n  ]\n});\n\nconsole.log(formatValidationResult(result));\n// 🔴 [descendant[0].children] 【关键】h1 是叶子节点，不能包含 children\n```\n\n### 自动修复\n\n```typescript\n// 自动修复块创建参数\nconst fixed = fixCreateBlockDescendantArgs(originalArgs);\n\n// 自动修复上传参数\nconst fixedUpload = fixApplyUploadArgs(args, {\n  path: '/docs/readme.md',\n  size: 1234,\n  entryId: 'xxx',\n  fileId: 'yyy'  // 如果是更新\n});\n```\n\n---\n\n## 块类型速查\n\n### 支持 children 的块\n\n| 类型 | children 内容 |\n|------|--------------|\n| `p` | 可选，嵌套内容 |\n| `bulleted_list` | 可选，嵌套列表 |\n| `numbered_list` | 可选，嵌套列表 |\n| `callout` | **必须**，内容块 |\n| `toggle` | **必须**，折叠内容 |\n| `table` | **必须**，table_cell |\n| `table_cell` | **必须**，内容块 |\n| `column_list` | **必须**，column |\n| `column` | **必须**，内容块 |\n| `task` | 可选，子任务 |\n\n### 不支持 children 的块（叶子节点）\n\n| 类型 | 说明 |\n|------|------|\n| `h1` - `h5` | 标题 |\n| `code` | 代码块 |\n| `divider` | 分割线 |\n| `image` | 图片 |\n| `attachment` | 附件 |\n| `video` | 视频 |\n| `mermaid` | Mermaid 图表 |\n| `plantuml` | PlantUML 图表 |\n\n---\n\n## 常见问题 (FAQ)\n\n### Q: 如何选择 Markdown 导入方式？\n\n**A**: 根据需求选择：\n\n- **作为文件上传**（`apply_upload` → PUT → `commit_upload`）：保留原始格式，支持版本管理，适合文档归档\n- **转为在线文档**（`import_content`）：转换为 Block 结构，可在线编辑，适合协作场景\n\n### Q: Block ID 如何管理？\n\n**A**: 客户端传入的 `block_id` 是临时标识，用于在单次调用中建立关系。服务端返回实际 ID 映射，后续更新操作使用服务端返回的 ID。\n\n### Q: 表格单元格如何排序？\n\n**A**: `children` 数组按**从左到右、从上到下**顺序排列。例如 2x2 表格：\n\n```\n[row1_col1, row1_col2, row2_col1, row2_col2]\n```\n\n### Q: 如何实现文档版本控制？\n\n**A**: 文件上传方式（`apply_upload`）支持版本管理。更新已有文件时，`parent_entry_id` 传文件自身的 `entry_id`。\n\n### Q: 为什么 `entry_describe_entry` 不返回文档正文内容？\n\n**A**: `entry_describe_entry` 设计用于获取条目的元信息（如ID、名称、类型、创建时间等），不包含实际内容。要读取文档的正文内容，请使用 `entry_describe_ai_parse_content` 工具。\n\n### Q: 什么时候使用 `entry_describe_entry`，什么时候使用 `entry_describe_ai_parse_content`？\n\n**A**:\n- 使用 `entry_describe_entry`：当您需要获取文档的基本信息用于后续操作时（如获取ID、确认文档类型）\n- 使用 `entry_describe_ai_parse_content`：当您需要读取文档的实际内容进行摘要、分析或处理时\n\nFile v1.0.0:references/connectors.md\n\n# 乐享外部数据源导入\n\n> **基础知识**：数据模型、URL 规则见 `references/base.md`。\n> **前置条件**：本 skill 需要已配置乐享 MCP 连接。如未配置，请先读取 `references/setup.md`。\n> **遇到 401 错误**：不要重试，读取 `references/setup.md` 引导用户续期（点击续期按钮即可恢复，无需重新配置）。\n\n---\n\n## 工具概览\n\n### 🎥 腾讯会议录制\n- `tx_meeting_search_tx_meeting_records` — 根据会议号搜索录制记录\n- `tx_meeting_describe_tx_meeting_record` — 查看录制详情\n- `tx_meeting_import_tx_meeting_record` — 导入录制到乐享知识库\n- `tx_meeting_reload_tx_meeting_record` — 重新导入已有录制\n- `tx_meeting_list_tx_meeting_records` — 列举录制记录（已废弃，请用 search）\n\n---\n\n## 腾讯会议录制导入\n\n### 使用流程\n\n```\n场景：「把昨天的会议录制导入到 XX 知识库」\n\nStep 1: 搜索会议录制\n  tx_meeting_search_tx_meeting_records(meeting_code=\"123456789\")\n  → 返回录制列表，包含 record_file_id、start_time、end_time\n\nStep 2: 确定目标位置\n  search_kb_search(keyword=\"XX\", type=\"space\") 定位知识库\n  space_describe_space(space_id) 获取 root_entry_id\n\nStep 3: 导入录制\n  tx_meeting_import_tx_meeting_record(\n    parent_entry_id = root_entry_id,\n    record_file_id = \"xxx\",\n    start_time = record.start_time - 300,  // 提前5分钟\n    end_time = record.end_time + 300       // 延后5分钟\n  )\n```\n\n### ⚠️ 注意事项\n\n1. **时间范围建议放宽**：`start_time` 和 `end_time` 比录制记录中的实际时间各提前/延后几分钟，确保录制内容完整\n2. **`tx_meeting_list_tx_meeting_records` 已废弃**：请使用 `tx_meeting_search_tx_meeting_records` 替代\n3. **重新导入**：如果之前导入的录制需要更新，使用 `tx_meeting_reload_tx_meeting_record`\n4. **授权问题**：如果报授权错误，需要提示用户在网页端先进行腾讯会议授权\n\n---\n\n## ⚠️ 核心注意事项\n\n1. **`_mcp_fields` 优化**：所有工具支持 `_mcp_fields` 参数选择返回字段，减少 token 消耗\n2. 参数不确定时以 `get_tool_schema(tool_name=\"xxx\")` 返回为准\n\nFile v1.0.0:references/content-reorganize.md\n\n# 场景：内容重组\n\n使用 MoveBlocks 调整文档结构，将块移动到新位置。\n\n## 移动块 API\n\n```\nMCP Tool: lexiang.block_move_blocks\nArguments: {\n  \"entry_id\": \"<entry_id>\",\n  \"block_ids\": [\"block_1\", \"block_2\", \"block_3\"],\n  \"parent_block_id\": \"<目标父块 ID>\",\n  \"after\": \"<插入位置，某块之后，可选>\"\n}\n```\n\n**限制**: 单次最多移动 20 个块\n\n---\n\n## 参数说明\n\n| 参数 | 说明 |\n|------|------|\n| `entry_id` | 文档 entry_id |\n| `block_ids` | 要移动的块 ID 数组，按顺序移动 |\n| `parent_block_id` | 目标父节点块 ID |\n| `after` | 插入到此块之后，为空则插入到开头 |\n\n---\n\n## 使用场景\n\n### 将分散内容整合到同一章节\n\n```\nMCP Tool: lexiang.block_move_blocks\nArguments: {\n  \"entry_id\": \"doc123\",\n  \"block_ids\": [\"para_1\", \"para_2\", \"list_1\"],\n  \"parent_block_id\": \"section_h2\",\n  \"after\": \"intro_callout\"\n}\n```\n\n### 调整段落顺序\n\n```\nMCP Tool: lexiang.block_move_blocks\nArguments: {\n  \"entry_id\": \"doc123\",\n  \"block_ids\": [\"para_3\"],\n  \"parent_block_id\": \"root_block\",\n  \"after\": \"para_1\"\n}\n```\n\n---\n\n## 使用辅助工具\n\n```typescript\nimport { ContentReorganizer } from './scripts/block-helper';\n\nconst reorganizer = new ContentReorganizer()\n  .move(['para_1', 'para_2'], 'section_h2', 'intro_callout')\n  .move(['list_1', 'list_2'], 'section_h2');\n\nconst mcpCalls = reorganizer.toMCPCalls(entryId);\n// 返回多个 MCP 调用\n```\n\n---\n\n## 注意事项\n\n1. **所有块只能移动到同一个目标父节点**\n2. **目标父节点不能是叶子节点类型**，包括：\n   - h1, h2, h3, h4, h5（标题块）\n   - code（代码块）\n   - image（图片块）\n   - attachment（附件块）\n   - video（视频块）\n   - divider（分割线）\n   - mermaid、plantuml（图表块）\n3. 移动操作会保持块的子孙结构\n4. 建议移动前先获取文档结构确认 block_id\n\n---\n\n## 获取文档结构\n\n```\nMCP Tool: lexiang.block_list_block_children\nArguments: {\n  \"entry_id\": \"<entry_id>\",\n  \"with_descendants\": true\n}\n```\n\n返回完整的块树结构，包含所有 block_id。\n\nFile v1.0.0:references/doc-templates.md\n\n# 文档类型与大纲规范\n\n写入文档前，先确定文档类型，按对应大纲组织内容。\n\n---\n\n## 类型一：推广文案型\n\n**适用场景**: 功能推广、工具介绍、方案宣传\n\n```\n1. [callout:primary] 一句话核心价值\n2. [h2] 你是否遇到这些问题？\n   - [bulleted_list] 痛点场景\n3. [divider]\n4. [h2] 解决方案\n   - [callout:tip] 核心能力\n   - [numbered_list] 功能列表\n5. [divider]\n6. [h2] 对比效果\n   - [table] 传统方式 vs 新方案\n7. [divider]\n8. [h2] 快速上手\n   - [h3] 步骤一\n   - [code] 配置代码\n9. [divider]\n10. [h2] 最佳实践\n    - [numbered_list] 实践建议\n11. [divider]\n12. [callout:success] 总结 + 行动召唤\n```\n\n---\n\n## 类型二：技术文档型\n\n**适用场景**: API 文档、开发指南、技术规范\n\n```\n1. [h1] 文档标题\n2. [h2] 概述\n   - [p] 功能描述\n   - [callout:tip] 适用场景\n3. [h2] 快速开始\n   - [code] 最小示例\n4. [h2] 详细说明\n   - [h3] 参数说明\n     - [table] 参数名 | 类型 | 必填 | 说明\n   - [h3] 返回值\n     - [code] 返回结构\n5. [h2] 示例\n6. [h2] 注意事项\n   - [callout:warning] 重要提醒\n```\n\n---\n\n## 类型三：操作指南型\n\n**适用场景**: 使用教程、操作手册、配置指南\n\n```\n1. [callout:primary] 本指南帮你实现 XXX\n2. [h2] 前置准备\n   - [bulleted_list] 环境要求\n   - [callout:warning] 注意事项\n3. [h2] 操作步骤\n   - [h3] 步骤 1：XXX\n     - [numbered_list] 详细操作\n     - [code] 命令/代码\n     - [callout:tip] 小技巧\n4. [h2] 验证结果\n5. [h2] 常见问题\n6. [callout:success] 完成确认\n```\n\n---\n\n## Callout 语义映射\n\n| 关键词模式 | Callout 类型 | 配色 |\n|-----------|-------------|------|\n| 核心/重要/价值 | primary | #E3F2FD |\n| 提示/建议/tips | tip | #FFF3E0 |\n| 成功/完成/搞定 | success | #E8F5E9 |\n| 警告/注意/风险 | warning | #FFF8E1 |\n| 错误/禁止/危险 | error | #FFEBEE |","readmeExcerpt":"Skill: 腾讯乐享知识库-私有化版本 Owner: lexiang Summary: 乐享知识库 MCP 全功能 Skill（私有化部署版）。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供乐享链接，或涉及知识库的搜索/写入/编辑/文件/配置等操作时使用。 Tags: latest:1.0.0 Version history: v1.0.0 | 2026-07-09T06:24:15.650Z | auto - 初始发布乐享知识库 MCP 全功能 Skill（私有化部署版）。 - 支持根据关键字和链接自动识别、路由各类知识库操作（搜索、写入、编辑、文件、配置等）。 - 严格安全规则规范：401/连接断开处理、写入确认、批量操作分批、域名使用规则等。 - 全面意图路由表与模块化参考文档设计，覆盖文档、页面、文件、会议录制等多场景。 - 明确私有化部署链接格式及认证与安全机制。 Archive ","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"MCP Tool: whoami\n → 成功：返回用户信息，继续执行\n → 401：读取 references/setup.md，引导用户重新获取 token 或续期\n → 连接失败：读取 references/setup.md，引导完成初始配置"},{"language":"text","snippet":"https://{你的乐享私有化域名}/ai/claw"},{"language":"json","snippet":"{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"url\": \"你的MCP_ENDPOINT\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}"},{"language":"text","snippet":"lexiang-private-skills/\n├── SKILL.md                  # 顶层路由入口（意图识别 → 参考文件）\n├── mcp.json                  # MCP 配置模板\n├── README.md                 # 本文件\n├── assets/                   # 静态资源\n├── references/               # 参考文档（19 份）\n│   ├── base.md               # 数据模型、URL 规则、完整安全规则、工具发现\n│   ├── setup.md              # Token 配置、续期、故障排查\n│   ├── search.md             # 关键词/语义搜索、内容读取、目录浏览\n│   ├── writer.md             # 新建文档、导入内容、公众号收藏\n│   ├── blocks.md             # 已有页面的 Block 级增删改移\n│   ├── files.md              # 二进制文件上传/下载（三步流程）\n│   ├── connectors.md         # 腾讯会议录制导入\n│   ├── index.md              # 完整索引 + 按场景推荐加载顺序\n│   ├── block-schema.md       # Block 类型完整字段定义\n│   ├── block-update.md       # 批量更新 Block 方法\n│   ├── common-errors.md      # 常见错误排查（高频错误速查表）\n│   ├── content-reorganize.md # 文档结构重组方案\n│   ├── doc-templates.md      # 文档类型与大纲模板\n│   ├── folder-sync.md        # 文件夹同步方案\n│   ├── markdown-import.md    # Markdown 导入详解\n│   ├── markdown-to-block.md  # Markdown 转 Block 指南\n│   ├── mcp-examples.md       # 复杂 Block 结构示例\n│   ├── skill-maintenance.md  # Skill 维护指南\n│   └── theme-config.md       # 主题配色配置\n└── scripts/                  # 辅助脚本\n    ├── upload-files.py       # 批量文件上传（支持单文件/文件夹/并行/dry-run）\n    ├── sync-folder.ts        # 文件夹增量同步到乐享知识库\n    └── test_upload_files.py  # 上传脚本测试"},{"language":"bash","snippet":"# 单文件上传\npython scripts/upload-files.py --files doc.md --entry-id <parent_entry_id>\n\n# 文件夹批量上传（5 并行）\npython scripts/upload-files.py --folder ./docs --entry-id <parent_entry_id> --parallel 5"},{"language":"bash","snippet":"npm install -g ts-node typescript\nnpm install @types/node"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: lexiang-knowledge-private\nversion: 1.0.0\ndescription: \"乐享知识库 MCP 全功能 Skill（私有化部署版）。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供乐享链接，或涉及知识库的搜索/写入/编辑/文件/配置等操作时使用。\"\n---\n\n# 乐享知识库 MCP Skill（私有化部署版）\n\n当用户提到「**乐享**」「**知识库**」「**个人知识库**」「**我的知识库**」「**lexiang**」，或提供乐享链接，或给出 `space_id`、`entry_id`、`/spaces/`、`/pages/` 等乐享标识时，读取本 Skill。\n\n> **私有化说明**：本 Skill 适用于私有化部署的乐享实例。用户访问域名为企业自定义私有域名（如 `https://lexiang.mycompany.com`），与 SaaS 版不同，**链接直接使用私有化域名，无需判断域名结构**。\n\n---\n\n## ⛔ MANDATORY RULES — 必须遵守\n\n1. **遇到 401 / 连接断开**：立即停止重试，读取 `references/setup.md`；引导用户重新获取 token\n2. **写入操作**：必须基于用户明确提供的目标（URL/ID/名称确认），**禁止**自行遍历或猜测目标\n3. **链接生成**：必须使用 `whoami()` 返回的 `company.company_domain` 作为域名，**禁止**使用 MCP endpoint 拼接用户链接\n4. **company_from**：私有化域名已指向对应企业，链接中**不需要拼接 `company_from` 参数**\n5. **强制检索**：当用户消息同时包含「乐享/知识库」等平台词 + 「文档/论文/文章/内容/资料/笔记/之前写的/上次的/风格」等内容词时，**必须先调用 `search_kb_search` 或 `search_kb_embedding_search` 获取实际内容**，不得凭空分析或直接生成回答\n6. **大批量保护**：文件/条目数量 > 20 个时，**必须分批执行**（每批 ≤ 20 个）；操作前告知用户数量和策略，禁止一次性提交导致 token 超限，详见 `references/files.md`\n\n---\n\n## 🔗 链接生成规则（全局通用）\n\n私有化版本链接生成规则：\n\n**`{domain}` = `whoami()` 返回的 `company.company_domain`（即企业私有化域名）**\n\n链接格式：`{domain}/pages/{entry_id}`\n\n> **私有化域名已指向对应企业，无需拼接 `company_from` 参数。**\n> 如 `whoami()` 返回 `company_domain` 为 `https://lexiang.mycompany.com`，则链接为：\n> `https://lexiang.mycompany.com/pages/{entry_id}`\n\n**禁止**使用 MCP 端点域名拼接用户访问链接。\n\n---\n\n## 🛡️ 写入安全红线（全局通用）\n\n- 🚫 禁止遍历团队/知识库列表后自行选择写入目标\n- 🚫 禁止根据名称\"看起来合适\"就决定写入\n- 🚫 禁止在未确认时执行写入\n\n> 完整安全规则（允许写入的条件、工具分类）见 `references/base.md`\n\n---\n\n## 📋 意图路由表\n\n根据用户意图，Read 对应参考文件：\n\n| 用户意图 | 读取文件 | 典型触发词 |\n|---------|---------|-----------|\n| 配置乐享 / 401 错误 / Token 过期 | `references/setup.md` | 「配置乐享」「token 过期」「连不上」「401」 |\n| 搜索 / 查找 / 阅读 / 浏览 | `references/search.md` | 「找一下」「搜索」「读一下这个页面」「打开链接」 |\n| 创建文档 / 写入 / 保存 / 导入 | `references/writer.md` | 「写到乐享」「创建文档」「保存到知识库」「存到我的知识库」「保存到个人知识库」「导入」 |\n| 编辑已有页面 / Block 操作 | `references/blocks.md` | 「修改这个页面」「加个标题」「删掉这段」「在 /pages/xxx 里…」 |\n| 上传/下载文件（PDF/Word/图片等） | `references/files.md` | 「传个 PDF」「上传文件」「下载这个文件」 |\n| 导入腾讯会议 | `references/connectors.md` | 「把会议录制导入」「导入会议录制」 |\n| 数据模型 / URL 规则 / 完整安全规则 | `references/base.md` | 由上述模块内部引用 |\n\n### ⚠️ 易混淆场景\n\n| 场景 | 正确模块 | 说明 |\n|------|---------|------|\n| 用户提供 `/pages/xxx` 链接 + 要求「加内容/修改」 | `references/blocks.md` | 操作**已有页面** |\n| 用户提供 `/spaces/xxx` 链接 + 要求「写入/创建」 | `references/writer.md` | 在知识库下**新建文档** |\n| 用户提供 `/pages/xxx` 链接 + 仅要求「读/总结」 | `references/search.md` | **只读**操作 |\n| 上传 PDF/Word/图片 | `references/files.md` | 二进制文件，非文本文档 |\n| 创建 Markdown 文本文档 | `references/writer.md` | 文本内容，非二进制 |\n| 「乐享里有一篇关于 X 的文档」 | `references/search.md` → 先搜索 | **必须先检索**，不能直接回答 |\n| 「看看乐享里 XX 的写作风格」 | `references/search.md` → 先读取 | **必须先读取内容**，不能凭空分析 |\n| 「分析一下我知识库里关于 X 的内容」 | `references/search.md` → 先搜索 | **必须先检索**，不能凭空生成 |\n\n### ⚠️ 跨模块任务\n\n需要同时读取多个文件时，按流程顺序读取：\n\n- **搜索后写入**：先 `references/search.md` → 再 `references/writer.md`\n- **读取后编辑**：先 `references/search.md` → 再 `references/blocks.md`\n- **上传后记录**：先 `references/files.md` → 再 `references/writer.md`\n- **生成内"},{"path":"README.md","content":"# lexiang-private-skills\n\n**乐享知识库 MCP Skill（私有化部署版，v1.0.0）**\n\n为 AI Agent 提供乐享知识库的全功能操作能力，包括搜索阅读、文档写入、Block 编辑、文件上传、外部导入等。\n\n> **适用场景**：企业私有化部署的乐享实例，访问域名为企业自定义域名，与 SaaS 版本独立维护。\n\n---\n\n## 快速开始\n\n访问你的乐享私有化 MCP 配置页面获取配置信息：\n\n```\nhttps://{你的乐享私有化域名}/ai/claw\n```\n\n登录后即可获取：\n- **MCP Endpoint**：填入 mcp.json 的 `url` 字段\n- **LEXIANG_TOKEN**：访问令牌（格式 `lxmcp_xxx`）\n\n填入 `mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"url\": \"你的MCP_ENDPOINT\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 目录结构\n\n```\nlexiang-private-skills/\n├── SKILL.md                  # 顶层路由入口（意图识别 → 参考文件）\n├── mcp.json                  # MCP 配置模板\n├── README.md                 # 本文件\n├── assets/                   # 静态资源\n├── references/               # 参考文档（19 份）\n│   ├── base.md               # 数据模型、URL 规则、完整安全规则、工具发现\n│   ├── setup.md              # Token 配置、续期、故障排查\n│   ├── search.md             # 关键词/语义搜索、内容读取、目录浏览\n│   ├── writer.md             # 新建文档、导入内容、公众号收藏\n│   ├── blocks.md             # 已有页面的 Block 级增删改移\n│   ├── files.md              # 二进制文件上传/下载（三步流程）\n│   ├── connectors.md         # 腾讯会议录制导入\n│   ├── index.md              # 完整索引 + 按场景推荐加载顺序\n│   ├── block-schema.md       # Block 类型完整字段定义\n│   ├── block-update.md       # 批量更新 Block 方法\n│   ├── common-errors.md      # 常见错误排查（高频错误速查表）\n│   ├── content-reorganize.md # 文档结构重组方案\n│   ├── doc-templates.md      # 文档类型与大纲模板\n│   ├── folder-sync.md        # 文件夹同步方案\n│   ├── markdown-import.md    # Markdown 导入详解\n│   ├── markdown-to-block.md  # Markdown 转 Block 指南\n│   ├── mcp-examples.md       # 复杂 Block 结构示例\n│   ├── skill-maintenance.md  # Skill 维护指南\n│   └── theme-config.md       # 主题配色配置\n└── scripts/                  # 辅助脚本\n    ├── upload-files.py       # 批量文件上传（支持单文件/文件夹/并行/dry-run）\n    ├── sync-folder.ts        # 文件夹增量同步到乐享知识库\n    └── test_upload_files.py  # 上传脚本测试\n```\n\n---\n\n## 模块说明\n\n根据用户意图，Agent 读取 `references/` 下对应的参考文件：\n\n| 用户意图 | 参考文件 | 典型触发词 |\n|---------|---------|-----------|\n| 配置乐享 / 401 错误 / Token 过期 | `references/setup.md` | 「配置乐享」「token 过期」「连不上」「401」 |\n| 搜索 / 查找 / 阅读 / 浏览 | `references/search.md` | 「找一下」「搜索」「读一下这个页面」 |\n| 创建文档 / 写入 / 保存 / 导入 | `references/writer.md` | 「写到乐享」「创建文档」「保存到知识库」 |\n| 编辑已有页面 / Block 操作 | `references/blocks.md` | 「修改这个页面」「加个标题」「删掉这段」 |\n| 上传/下载文件 | `references/files.md` | 「传个 PDF」「上传文件」「下载这个文件」 |\n| 导入腾讯会议 | `references/connectors.md` | 「导入会议录制」 |\n| 数据模型 / URL 规则 / 安全规则 | `references/base.md` | 由上述模块内部引用 |\n\n> 完整路由规则和易混淆场景见 `SKILL.md`\n\n---\n\n## 核心规则\n\n- **写入安全**：必须基于用户明确提供的目标（URL/ID/确认），禁止自行遍历或猜测\n- **链接生成**：使用 `whoami().company.company_domain` 作为私有化域名直接拼接，无需追加 `company_from` 参数\n- **401 处理**：不重试，引导用户打开 `{私有化域名}/ai/claw` 续期（点续期按钮即可恢复，无需重新配置）\n- **强制检索**：用户提到「乐享里的文档/内容」时，必须先搜索再回答，禁止凭空生成\n\n> 完整规则详见 `SKILL.md` 和 `references/base.md`\n\n---\n\n## 辅助脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `scripts/upload-files.py` | 批量文件上传（支持单文件/文件夹/并行/dry-run） |\n| `scripts/sync-folder.ts` | 文件夹增量同步到乐享知识库 |\n| `scripts/test_upload_files.py` | 上传脚本测试 |\n\n```bash\n#"},{"path":"scripts/README.md","content":"# Lexiang Scripts\n\n乐享文档写入辅助脚本集合。\n\n## 安装依赖\n\n### TypeScript 脚本\n\n```bash\nnpm install -g ts-node typescript\nnpm install @types/node\n```\n\n### Python 脚本\n\n```bash\npip install aiohttp requests\n```\n\n## 脚本列表\n\n### sync-folder.ts\n\n本地文件夹增量同步到乐享知识库。\n\n```bash\n# Dry run 模式（仅生成计划）\nnpx ts-node sync-folder.ts --local ./docs --entry-id abc123 --dry-run\n\n# 完整参数\nnpx ts-node sync-folder.ts \\\n  --local ./docs \\\n  --entry-id <parent_entry_id> \\\n  --space-id <space_id> \\\n  --state-file .sync-state.json \\\n  --dry-run\n```\n\n### upload-files.py\n\n并行上传文件到乐享。\n\n```bash\n# 单文件上传\npython upload-files.py --files doc1.md doc2.pdf --entry-id abc123\n\n# 文件夹批量上传\npython upload-files.py --folder ./docs --entry-id abc123 --parallel 5\n\n# 输出上传计划到 JSON\npython upload-files.py --folder ./docs --entry-id abc123 --output plan.json --dry-run\n```\n\n\n\n## 工作流示例\n\n### 1. 项目文档同步\n\n```bash\n# 1. 首次同步（dry run 检查）\nnpx ts-node sync-folder.ts --local ./project-docs --entry-id root123 --dry-run\n\n# 2. 执行同步\n# 将生成的 MCP 调用序列提供给 AI 助手执行\n\n# 3. 后续增量同步\n# 脚本会自动检测变更，只同步修改的文件\n```\n\n### 2. Markdown 文档导入\n\n```bash\n# 1. 生成上传计划\npython upload-files.py --folder ./markdown-docs --entry-id target123 --output plan.json\n\n# 2. 查看计划\ncat plan.json\n\n# 3. 执行上传（通过 AI 助手）\n# 将 plan.json 中的 MCP 调用提供给 AI 助手\n```\n\n## 注意事项\n\n1. **MCP 调用需要通过 AI 助手执行**：脚本生成 MCP 调用参数，实际执行需要 AI 助手的 MCP 能力\n2. **文件上传是 3 步流程**：apply_upload → HTTP PUT → commit_upload\n3. **同步状态文件**：`.lexiang-sync-state.json` 记录同步状态，请勿删除\n4. **大文件建议分批**：单次 MCP 调用的数据量有限制\n5. **Block 写入使用 MCP 工具**：直接调用 `block_convert_content_to_blocks` 将 Markdown/HTML 转换为块结构，无需手动构建"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn72bkq17fhyp4f0c7c8mvqq8d86zrsm\",\n  \"slug\": \"lexiang-private-skills\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1783578255650\n}"},{"path":"references/base.md","content":"# 乐享 MCP 基础知识（私有化部署版）\n\n> 本文件为所有功能模块的共享基础层，包含数据模型、URL 规则、安全约束、工具发现等通用知识。\n> **核心规则（URL 生成 + 写入安全红线）已在 SKILL.md 中内联，本文件为详细参考。**\n\n---\n\n## ⛔ 必读（调用前必须理解）\n\n1. 本服务**直接暴露所有业务工具**（如 `team_list_teams`、`search_kb_search` 等），可直接调用\n2. 调用前先确认工具参数定义，**以 MCP 返回的 schema 为准**\n3. 不确定参数时，使用 `get_tool_schema(tool_name=\"xxx\")` 获取最新定义\n\n---\n\n## 📊 数据模型\n\n### 核心概念\n\n| 概念 | 说明 |\n|------|------|\n| **Team（团队）** | 顶级组织单元，一个团队下可以有多个知识库(Space) |\n| **Space（知识库）** | 知识的容器，属于某个团队，包含多个条目(Entry)，有 `root_entry_id` 作为根节点 |\n| **Entry（条目）** | 知识库中的内容单元，可以是页面(page)、文件夹(folder)或文件(file)，支持树形结构(parent_id) |\n| **File（文件）** | 附件类型的条目，如 PDF、Word、图片等 |\n\n### 层级关系\n\n```\nTeam → Space → Entry（树形结构，root_entry_id 为根）\n                  ├── page（页面）\n                  ├── folder（文件夹）\n                  └── file（文件）\n```\n\n### URL 规则（私有化版本）\n\n`{domain}` = `whoami()` 返回的 `company.company_domain`（即企业私有化域名，如 `https://lexiang.mycompany.com`）\n\n> **⛔ 严禁使用 MCP endpoint 拼接任何用户可访问的链接！** MCP 域名仅用于接口调用，不是用户访问地址。\n\n| 资源 | URL 格式 |\n|------|----------|\n| 团队首页 | `{domain}/t/{team_id}/spaces` |\n| 知识库 | `{domain}/spaces/{space_id}` |\n| 知识条目 | `{domain}/pages/{entry_id}` |\n\n**链接生成规则（私有化版本，所有操作通用）：**\n\n私有化域名已指向对应企业，**直接使用 `{domain}` 拼接，无需附加 `company_from` 参数**：\n\n```\n链接 = {domain}/pages/{entry_id}\n```\n\n示例：`whoami()` 返回 `company_domain` 为 `https://lexiang.mycompany.com`，则：\n- 条目链接：`https://lexiang.mycompany.com/pages/abc123`\n- 知识库链接：`https://lexiang.mycompany.com/spaces/xyz789`\n\n### URL 解析规则\n\n当用户提供链接时，从 URL 路径中提取 ID（**忽略查询参数**）：\n\n| URL 路径 | 提取方式 |\n|----------|----------|\n| `/spaces/{space_id}` | 取 `spaces/` 后面的部分作为 `space_id` |\n| `/pages/{entry_id}` | 取 `pages/` 后面的部分作为 `entry_id` |\n| `/t/{team_id}/spaces` | 取 `t/` 后面的部分作为 `team_id` |\n\n---\n\n## 🛡️ 写入操作安全规则\n\n> **核心原则**：写入、修改、删除操作 **必须基于用户明确提供的目标信息**，禁止 Agent 自行选择或猜测目标。\n\n### 🚫 绝对禁止\n\n1. 禁止遍历团队/知识库列表后自行选择写入目标\n2. 禁止根据名称\"看起来合适\"就决定写入\n3. 禁止在未确认时执行写入\n\n### ✅ 允许写入的条件（满足之一即可）\n\n| 条件 | 示例 |\n|------|------|\n| 用户提供了明确 URL | `\"写到这里：https://lexiang.mycompany.com/spaces/xxx\"` |\n| 用户提供了明确 ID | `\"写入 space_id 为 xxx 的知识库\"` |\n| 用户指定名称 + Agent 回显确认 | Agent 搜到后展示详情，用户确认 |\n| 用户要求保存到个人知识库且 `whoami` 返回了个人知识库 | `\"保存到我的知识库\"` → 自动写入个人知识库 |\n\n### 写入 vs 读取工具分类\n\n**写入操作**（需满足安全规则）：\n`entry_create_entry`、`entry_import_content`、`entry_import_content_to_entry`、`block_update_block`、`block_update_blocks`、`block_create_block_descendant`、`block_delete_block`、`block_delete_block_children`、`block_move_blocks`、`entry_rename_entry`、`entry_move_entry`、`file_apply_upload`、`file_commit_upload`、`file_create_hyperlink`\n\n**只读操作**（不受安全规则限制，可直接执行）：\n`team_list_teams`、`team_describe_team`、`team_list_frequent_teams`、`space_list_spaces`、`space_describe_space`、`entry_list_children`、`block_list_block_children`、`search_kb_search`、`search_kb_embedding_search`、`space_list_recently_spaces`、`entry_list_latest_entries`、`entry_describe_ai_parse_content`、`file_describe_file`、`file_download_file`、`whoami`\n\n---\n\n## 🔍 工具发现与调用\n\n本服务**直接暴露所有业务工具**，可直接调用。同时提供以下辅助元工具：\n\n| 元工具 | 用途 |\n|--------|------|\n| `list_tool_categories` | 列出所有工具分类及其工具列表 |\n| `search_tools`"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":871,"uniquenessScore":41,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T18:41:55.104Z","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-11T18:41:55.104Z","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-12T05:48:07.147Z","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"}]}}}