{"id":"25415322-ebd4-4637-9ae0-dd653aa0f4ca","entityType":"agent","slug":"clawhub-lexiang-lexiang-mcp-skill","name":"腾讯乐享知识库 Lexiang Knowledge Base","canonicalUrl":"https://www.xpersona.co/agent/clawhub-lexiang-lexiang-mcp-skill","canonicalPath":"/agent/clawhub-lexiang-lexiang-mcp-skill","generatedAt":"2026-10-10T05:40:04.012Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:07:05.168Z","emptyReason":null},"description":"乐享知识库 MCP 全功能 Skill。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供 lexiangla.com 链接，或涉及知识库的搜索/写入/编辑/文件/配置/评论/草稿/智能表格等操作时使用。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.1K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s1786rt68jz3shqts3q6e64w4h83nfyz:lexiang-mcp-skill","sourceUrl":"https://clawhub.ai/lexiang/lexiang-mcp-skill","homepage":"https://clawhub.ai/lexiang/skills/lexiang-mcp-skill","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/lexiang/lexiang-mcp-skill","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/lexiang/skills/lexiang-mcp-skill","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":66,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"腾讯乐享知识库 Lexiang Knowledge Base 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-09T19:07:05.168Z","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-09T19:07:05.168Z","emptyReason":null},"stars":null,"forks":null,"downloads":2095,"packageName":null,"latestVersion":"2.2.1","tractionLabel":"2.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:07:05.168Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T19:07:05.168Z","lastCrawledAt":"2026-10-09T19:07:05.168Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T19:07:05.168Z","lastVerifiedAt":null,"highlights":[{"version":"2.2.1","createdAt":"2026-10-09T02:32:14.247Z","changelog":"- opt smartsheet","fileCount":31,"zipByteSize":67977},{"version":"2.2.0","createdAt":"2026-08-24T06:58:08.565Z","changelog":"**Added support for评论、草稿和智能表格相关功能** - 新增 references/comment.md，实现知识页面评论查看 - 新增 references/draft.md，实现草稿保存、发布和管理 - 新增 references/smartsheet.md，实现智能表格（结构化数据）操作 - 意图路由表中加入“查看评论”、“草稿”及“智能表格”相关场景 - 移除 skill-card.md，整理参考文件结构","fileCount":31,"zipByteSize":66762},{"version":"2.1.1","createdAt":"2026-06-16T08:18:27.572Z","changelog":"- Removed the file skill-card.md. - No other feature or documentation changes in this release.","fileCount":28,"zipByteSize":59700},{"version":"2.0.2","createdAt":"2026-06-05T07:52:44.571Z","changelog":"**Major structure and rule update for lexiang-mcp-skill 2.1.0:** - Migrated all SKILL.md sub-skills to a unified references/ folder with modular reference files (e.g., references/base.md, references/search.md). - Enhanced mandatory usage rules, including stricter requirements for credential checks, search before answer, and batch operations for large datasets. - Updated intent routing, scenario disambiguation, and module/task flow tables for clearer usage and cross-module logic. - Improved and expanded global rules on link generation, write-target selection, and error handling. - Added comprehensive reference file index and supplementary documentation for advanced scenarios and operations. - Updated intent keywords and typical phrases to cover personal knowledge base and new workflows.","fileCount":28,"zipByteSize":58975},{"version":"2.0.1","createdAt":"2026-05-26T04:54:07.728Z","changelog":"Version 2.0.1 - No file changes detected in this release. - No updates to functionality, documentation, or behavior.","fileCount":27,"zipByteSize":57884},{"version":"2.0.0","createdAt":"2026-05-21T13:24:41.165Z","changelog":"No file changes detected; functionality remains unchanged in version 2.0.0. - Skill structure, features, and documentation remain the same as the previous release. - No updates or modifications applied to code or documentation files.","fileCount":26,"zipByteSize":56463},{"version":"0.1.6","createdAt":"2026-05-21T13:22:01.783Z","changelog":"**Major restructuring and modularization of the skill:** - Refactored skill into multiple submodules (base, setup, search, writer, blocks, files, connectors) for clearer intent routing and easier maintenance. - Centralized usage rules, intent routing, credential checks, and link generation in the main SKILL.md, referencing submodules as needed. - Updated and clarified mandatory rules for write operations, token management, and how to generate user-facing links. - Removed obsolete files and moved relevant documentation into modular SKILL.md files. - Added .git and other project configuration files for better version control and onboarding.","fileCount":26,"zipByteSize":56465},{"version":"0.1.5","createdAt":"2026-03-26T02:35:24.016Z","changelog":"**Summary:** Initial release with full MCP integration and knowledge base management. - Added all core project and configuration files for the skill. - Full documentation on usage rules, data model, and write safety. - Enabled direct invocation of all Lexiang MCP tools (list, search, read, write). - AccessToken lifecycle management and multi-tenant support provided. - Clarified URL and ID extraction rules. - Guidance for user intent identification and safe write operations.","fileCount":24,"zipByteSize":49042}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1786rt68jz3shqts3q6e64w4h83nfyz:lexiang-mcp-skill","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s1786rt68jz3shqts3q6e64w4h83nfyz:lexiang-mcp-skill` 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-mcp-skill 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-mcp-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-mcp-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-mcp-skill/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-mcp-skill/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-mcp-skill/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-mcp-skill/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-10T05:40:04.008Z"}},"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-mcp-skill/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-mcp-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-mcp-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lexiang-lexiang-mcp-skill/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-09T19:07:05.168Z","emptyReason":null},"readme":"Skill: 腾讯乐享知识库 Lexiang Knowledge Base\n\nOwner: lexiang\n\nSummary: 乐享知识库 MCP 全功能 Skill。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供 lexiangla.com 链接，或涉及知识库的搜索/写入/编辑/文件/配置/评论/草稿/智能表格等操作时使用。\n\nTags: latest:2.2.1\n\nVersion history:\n\nv2.2.1 | 2026-10-09T02:32:14.247Z | user\n\n- opt smartsheet\n\nv2.2.0 | 2026-08-24T06:58:08.565Z | user\n\n**Added support for评论、草稿和智能表格相关功能**\n\n- 新增 references/comment.md，实现知识页面评论查看\n- 新增 references/draft.md，实现草稿保存、发布和管理\n- 新增 references/smartsheet.md，实现智能表格（结构化数据）操作\n- 意图路由表中加入“查看评论”、“草稿”及“智能表格”相关场景\n- 移除 skill-card.md，整理参考文件结构\n\nv2.1.1 | 2026-06-16T08:18:27.572Z | user\n\n- Removed the file skill-card.md.\n- No other feature or documentation changes in this release.\n\nv2.0.2 | 2026-06-05T07:52:44.571Z | user\n\n**Major structure and rule update for lexiang-mcp-skill 2.1.0:**\n\n- Migrated all SKILL.md sub-skills to a unified references/ folder with modular reference files (e.g., references/base.md, references/search.md).\n- Enhanced mandatory usage rules, including stricter requirements for credential checks, search before answer, and batch operations for large datasets.\n- Updated intent routing, scenario disambiguation, and module/task flow tables for clearer usage and cross-module logic.\n- Improved and expanded global rules on link generation, write-target selection, and error handling.\n- Added comprehensive reference file index and supplementary documentation for advanced scenarios and operations.\n- Updated intent keywords and typical phrases to cover personal knowledge base and new workflows.\n\nv2.0.1 | 2026-05-26T04:54:07.728Z | user\n\nVersion 2.0.1\n\n- No file changes detected in this release.\n- No updates to functionality, documentation, or behavior.\n\nv2.0.0 | 2026-05-21T13:24:41.165Z | user\n\nNo file changes detected; functionality remains unchanged in version 2.0.0.\n\n- Skill structure, features, and documentation remain the same as the previous release.\n- No updates or modifications applied to code or documentation files.\n\nv0.1.6 | 2026-05-21T13:22:01.783Z | user\n\n**Major restructuring and modularization of the skill:**\n\n- Refactored skill into multiple submodules (base, setup, search, writer, blocks, files, connectors) for clearer intent routing and easier maintenance.\n- Centralized usage rules, intent routing, credential checks, and link generation in the main SKILL.md, referencing submodules as needed.\n- Updated and clarified mandatory rules for write operations, token management, and how to generate user-facing links.\n- Removed obsolete files and moved relevant documentation into modular SKILL.md files.\n- Added .git and other project configuration files for better version control and onboarding.\n\nv0.1.5 | 2026-03-26T02:35:24.016Z | user\n\n**Summary:**  \nInitial release with full MCP integration and knowledge base management.\n\n- Added all core project and configuration files for the skill.\n- Full documentation on usage rules, data model, and write safety.\n- Enabled direct invocation of all Lexiang MCP tools (list, search, read, write).\n- AccessToken lifecycle management and multi-tenant support provided.\n- Clarified URL and ID extraction rules.\n- Guidance for user intent identification and safe write operations.\n\nv0.1.4 | 2026-03-18T07:24:12.031Z | user\n\nlexiang-mcp-skill 0.1.4 changelog\n\n- Added setup.md with setup/configuration instructions.\n- Removed setup.sh script.\n- Updated skill metadata: now uses OpenClaw-style `metadata` field specifying required environment variables.\n- Removed old `credentials`/`env_vars` blocks in SKILL.md in favor of new metadata structure.\n- No runtime or functional logic changed. Documentation and config organization improved.\n\nv0.1.3 | 2026-03-17T12:33:24.746Z | auto\n\nlexiang-mcp-skill v0.1.3\n\n- 增加 SKILL.md 中 metadata 字段，声明 openclaw 必需信息（category/emoji）和所需环境变量（LEXIANG_TOKEN, COMPANY_FROM），包括访问令牌和企业标识说明。\n- 新增 credentials/env_vars 说明，便于用户理解本服务调用前的配置要求。\n- 未修改功能或业务逻辑，仅文档结构及元信息补充，便于平台集成与部署。\n\nv0.1.2 | 2026-03-13T06:25:59.296Z | auto\n\n**lexiang-mcp-skill v0.1.2 Changelog**\n\n- Major rewrite and restructuring of SKILL.md with clearer usage instructions, enhanced safety rules, and detailed workflows for all operations.\n- Expanded reference documentation: added new guides and examples for Markdown import, block structure, folder sync, theme configuration, and maintenance.\n- Updated and enriched example assets including block schema and default theme.\n- New utility scripts added for testing file uploads and syncing folders.\n- Removed deprecated scripts and outdated documentation to improve maintainability.\n- Improved clarity of user intent recognition, safety checks for write operations, and reference navigation.\n\nv0.1.1 | 2026-03-10T11:05:34.872Z | auto\n\nlexiang-mcp-skill v0.1.1\n\n- 简化和重构了 SKILL.md，大幅精简内容，保留核心操作规则与关键流程说明。\n- 移除了旧的主题、schema 示例、脚本与部分 markdown 指南等文件，删除多余冗余文档。\n- 新增页面编辑相关 reference (references/page-edit.md)，明确页面结构及编辑相关流程。\n- 统一数据模型、URL提取、写入安全与常用操作流程说明，便于快速查阅和调用。\n- 主要说明流程从详细模板引导转向以 reference 文档和核心操作流程为主，提升可维护性和查找效率。\n\nv0.1.0 | 2026-03-06T13:11:15.073Z | auto\n\nInitial public release of the Lexiang Knowledge Base skill.\n\n- Provides dedicated skill for accessing the Lexiang knowledge base platform.\n- Automatically triggers when user queries mention keywords like 乐享, lexiang, 知识, 文档, 知识库, 知识管理, 文档管理, Issue反馈, or links to lexiangla.com.\n- Supports document search, content retrieval, metadata queries, creation and editing, structure management, tagging, comments, and attachments.\n- Enforces strict safety rules for write operations: requires explicit user confirmation and prohibits guessing destinations.\n- Includes issue reporting flow and templates for product feedback via GitHub.\n- Outlines core models, URL parsing rules, and best practices for safe and effective operation.\n\nArchive index:\n\nArchive v2.2.1: 31 files, 67977 bytes\n\nFiles: mcp.json (319b), README.md (6748b), references/base.md (12051b), references/block-schema.md (3378b), references/block-update.md (2284b), references/blocks.md (5603b), references/comment.md (1419b), references/common-errors.md (10019b), references/connectors.md (2207b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/draft.md (2455b), references/files.md (6603b), 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 (4390b), references/setup.md (7495b), references/skill-maintenance.md (4976b), references/smartsheet.md (6902b), references/theme-config.md (3801b), references/writer.md (5762b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), skill-card.md (1976b), SKILL.md (7994b), _meta.json (136b)\n\nFile v2.2.1:SKILL.md\n\n---\nname: lexiang-knowledge-base\nversion: 2.2.0\ndescription: \"乐享知识库 MCP 全功能 Skill。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供 lexiangla.com 链接，或涉及知识库的搜索/写入/编辑/文件/配置/评论/草稿/智能表格等操作时使用。\"\n---\n\n# 乐享知识库 MCP Skill\n\n当用户提到「**乐享**」「**知识库**」「**个人知识库**」「**我的知识库**」「**lexiang**」，或提供 `lexiangla.com` 链接，或给出 `space_id`、`entry_id`、`/spaces/`、`/pages/` 等乐享标识时，读取本 Skill。\n\n---\n\n## ⛔ MANDATORY RULES — 必须遵守\n\n1. **遇到 401 / 连接断开**：立即停止重试，读取 `references/setup.md`；内置连接器平台（WorkBuddy/QClaw 等）引导重新授权，其他平台引导续期\n2. **写入操作**：必须基于用户明确提供的目标（URL/ID/名称确认），**禁止**自行遍历或猜测目标\n3. **链接生成**：必须使用 `whoami()` 返回的 `company.company_domain` 作为域名，**禁止**使用 MCP endpoint 拼接用户链接\n4. **company_from**：不能拼接为子域名，只能作 `?company_from=xxx` 查询参数\n5. **强制检索**：当用户消息同时包含「乐享/知识库」等平台词 + 「文档/论文/文章/内容/资料/笔记/之前写的/上次的/风格」等内容词时，**必须先调用 `search_kb_search` 或 `search_kb_embedding_search` 获取实际内容**，不得凭空分析或直接生成回答\n6. **大批量保护**：文件/条目数量 > 20 个时，**必须分批执行**（每批 ≤ 20 个）；操作前告知用户数量和策略，禁止一次性提交导致 token 超限，详见 `references/files.md`\n\n---\n\n## 🔗 链接生成规则（全局通用）\n\n所有操作完成后返回链接时，统一遵循：\n\n| `company.company_domain` 类型 | 链接格式 | 示例 |\n|------------------------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\n\n**`{company_from}` 获取优先级：**\n1. mcp.json `url` 字段中的 `company_from` 参数\n2. 若无，使用 `whoami().company.code`\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| 智能表格 / 结构化数据 | `references/smartsheet.md` | 「智能表格」「乐享表格」「表格里的数据」「新增一行」「查询记录」 |\n| 草稿 / 存草稿 / 发布 | `references/draft.md` | 「先存草稿」「保存为草稿」「发布草稿」「查看草稿」 |\n| 查看评论 | `references/comment.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，引导续期（点续期按钮，无需重新配置）\n → 连接失败：读取 references/setup.md，引导完成初始配置\n```\n\n---\n\n## 📚 参考文件索引\n\n> **按需加载**：根据意图路由表，只 Read 对应文件，无需一次性加载全部。\n\n| 文件 | 职责 |\n|------|------|\n| `references/setup.md` | Token 配置、续期、WorkBuddy OAuth、故障排查 |\n| `references/search.md` | 关键词/语义搜索、内容读取、目录浏览 |\n| `references/writer.md` | 新建文档、导入内容、公众号收藏 |\n| `references/blocks.md` | 已有页面的 Block 级增删改移 |\n| `references/files.md` | 二进制文件上传/下载（三步流程） |\n| `references/connectors.md` | 腾讯会议录制导入 |\n| `references/smartsheet.md` | 智能表格增删查改、schema 管理 |\n| `references/draft.md` | Markdown 草稿保存、发布、管理 |\n| `references/comment.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: **2.2.0**\n\nFile v2.2.1:README.md\n\n# lexiang-skills\n\n**乐享知识库 MCP Skill（v2.1.0）**\n\n为 AI Agent 提供乐享知识库的全功能操作能力，包括搜索阅读、文档写入、Block 编辑、文件上传、外部导入等。\n\n---\n\n## 快速开始\n\n### WorkBuddy 用户\n\nWorkBuddy 已内置乐享连接器，**无需手动配置**：\n\n1. 在 WorkBuddy「集成」页面找到「乐享」连接器\n2. 点击「授权」完成 OAuth 登录，连接器自动激活\n\n### 其他平台（OpenClaw、Claude 等）\n\n访问 [https://lexiangla.com/mcp](https://lexiangla.com/mcp) 获取 `COMPANY_FROM` 和 `LEXIANG_TOKEN`，填入 `mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"enabled\": true,\n      \"url\": \"https://mcp.lexiang-app.com/mcp?company_from=你的COMPANY_FROM\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 目录结构\n\n```\nlexiang-skills/\n├── SKILL.md                  # 顶层路由入口（意图识别 → 参考文件）\n├── mcp.json                  # MCP 配置模板\n├── README.md                 # 本文件\n├── assets/                   # 静态资源\n├── references/               # 参考文档（19 份）\n│   ├── base.md               # 数据模型、URL 规则、完整安全规则、工具发现\n│   ├── setup.md              # Token 配置、续期、WorkBuddy OAuth、故障排查\n│   ├── search.md             # 关键词/语义搜索、内容读取、目录浏览\n│   ├── writer.md             # 新建文档、导入内容、公众号收藏\n│   ├── blocks.md             # 已有页面的 Block 级增删改移\n│   ├── files.md              # 二进制文件上传/下载（三步流程）\n│   ├── connectors.md         # 腾讯会议录制导入、iWiki 文档迁移\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| 导入腾讯会议 / iWiki 迁移 | `references/connectors.md` | 「导入会议录制」「迁移 iWiki 文档」 |\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 处理**：不重试，引导用户续期（点续期按钮即可恢复，无需重新配置）\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 配置、续期、WorkBuddy OAuth、故障排查 |\n| `references/search.md` | 关键词/语义搜索、内容读取、目录浏览 |\n| `references/writer.md` | 新建文档、导入内容、公众号收藏 |\n| `references/blocks.md` | 已有页面的 Block 级增删改移 |\n| `references/files.md` | 二进制文件上传/下载（三步流程） |\n| `references/connectors.md` | 腾讯会议录制导入、iWiki 文档迁移 |\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- 乐享平台：https://lexiangla.com\n- 获取 MCP 配置：https://lexiangla.com/mcp\n- MCP 协议：https://modelcontextprotocol.io\n\nFile v2.2.1: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 v2.2.1:_meta.json\n\n{\n  \"ownerId\": \"kn721jbsqc97byg79gg835yt4n81rzya\",\n  \"slug\": \"lexiang-mcp-skill\",\n  \"version\": \"2.2.1\",\n  \"publishedAt\": 1791513134247\n}\n\nFile v2.2.1: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://csig.lexiangla.com` 或 `https://lexiangla.com`）\n\n> **⛔ 严禁使用 MCP endpoint 拼接任何用户可访问的链接！** MCP 域名仅用于接口调用，不是用户访问地址。\n> **⛔ 严禁将 `company_from` 拼接为子域名！** `company_from` 只能作为 URL 查询参数（`?company_from=xxx`）。\n\n| 资源 | URL 格式 |\n|------|----------|\n| 团队首页 | `{domain}/t/{team_id}/spaces` |\n| 知识库 | `{domain}/spaces/{space_id}` |\n| 知识条目 | `{domain}/pages/{entry_id}` |\n\n**链接生成步骤（所有操作通用）：**\n\n1. 取 `whoami()` 返回的 `company.company_domain` 作为 `{domain}`\n2. 判断 `{domain}` 是否为顶级域名（不含三级前缀，如 `lexiangla.com`）：\n   - **是**：使用 `{domain}/pages/{entry_id}?company_from={company_from}`\n     - `{company_from}` 优先取 mcp.json `url` 中的 `company_from` 参数\n     - 若无，取 `whoami()` 返回的 `company.code` ← **此时已调用过 whoami，直接取该值，不能省略**\n   - **否**（如 `csig.lexiangla.com`）：使用 `{domain}/pages/{entry_id}`，无需追加参数\n\n| `{domain}` 类型 | 链接格式 | 示例 |\n|----------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\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://lexiangla.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`、`entry_rename_entry`、`entry_move_entry`、`entry_set_entry_validity`、`block_update_block`、`block_update_blocks`、`block_update_page`、`block_create_block_descendant`、`block_delete_block`、`block_delete_block_children`、`block_move_blocks`、`file_apply_upload`、`file_commit_upload`、`file_create_hyperlink`、`file_revert_file`、`draft_save_markdown_draft`、`draft_publish_markdown_draft`、`draft_delete_markdown_draft`、`smartsheet_create`、`smartsheet_create_records`、`smartsheet_update_records`、`smartsheet_delete_records`、`smartsheet_update_schema`、`smartsheet_create_field`、`smartsheet_update_field`、`smartsheet_delete_field`、`smartsheet_create_view`、`smartsheet_update_view`、`smartsheet_delete_view`\n\n**只读操作**（不受安全规则限制，可直接执行）：\n`team_list_teams`、`team_describe_team`、`team_list_frequent_teams`、`space_list_spaces`、`space_describe_space`、`space_list_recently_spaces`、`space_describe_personal_space`、`entry_list_children`、`entry_describe_entry`、`entry_describe_ai_parse_content`、`entry_list_parents`、`entry_list_latest_entries`、`entry_list_recently_entries`、`block_list_block_children`、`block_describe_block`、`block_fetch_page`、`search_kb_search`、`search_kb_embedding_search`、`lexiang_search`、`lexiang_fetch`、`file_describe_file`、`file_download_file`、`file_list_revisions`、`draft_describe_markdown_draft`、`smartsheet_fetch`、`smartsheet_list`、`smartsheet_list_smartsheets`、`smartsheet_list_records`、`smartsheet_describe_record`、`smartsheet_list_fields`、`smartsheet_list_views`、`comment_list_comments`、`comment_describe_comment`、`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| `references/smartsheet.md` | 智能表格增删查改、schema 管理 |\n| `references/draft.md` | Markdown 草稿保存、发布、管理 |\n| `references/comment.md` | 知识页面评论查看 |\n\n### 辅助脚本（scripts/）\n\n| 脚本 | 说明 |\n|------|------|\n| `scripts/upload-files.py` | 批量文件上传（支持单文件/文件夹/并行） |\n| `scripts/sync-folder.ts` | 文件夹增量同步 |\n\n**upload-files.py 用法：**\n\n```bash\n# 单文件上传\npython scripts/upload-files.py --files doc.md --entry-id <parent_entry_id>\n\n# 文件夹批量上传（并行）\npython scripts/upload-files.py --folder ./docs --entry-id <parent_entry_id> --parallel 5\n\n# 生成上传计划（dry-run）\npython scripts/upload-files.py --folder ./docs --entry-id <entry_id> --output plan.json --dry-run\n```\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 v2.2.1: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 v2.2.1: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 v2.2.1: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###📄 页面级操作（优先使用）\n- `block_fetch_page` — 获取页面正文（支持 markdown/mdx/clean 三种格式）\n- `block_update_page` — 命令式更新页面内容（replace/update/delete/replace_blocks）\n\n### 🧩 原子 Block 操作\n- `block_convert_content_to_blocks` — Markdown/HTML转 Block 结构（纯转换，不创建）\n- `block_create_block_descendant` — 在指定块下创建子块结构\n- `block_update_block` — 单块更新\n- `block_update_blocks` — 批量更新多个块\n- `block_move_blocks` — 移动块到新位置\n- `block_delete_block_children` — 删除指定子块\n- `block_delete_block` — 删除指定块（含子孙）\n- `block_describe_block` — 获取单个块详情\n- `block_list_block_children` — 列出块的子节点\n- `block_apply_block_attachment_upload` — 申请块附件/图片上传凭证\n\n### 🔎 资源快捷访问\n- `lexiang_fetch` — 按资源类型读取单个乐享资源（entry/space/team/file/block/smartsheet/record）\n- `lexiang_search` — 搜索乐享资源（doc/space/team/all）\n\n---\n\n## 🛠️ 工具选择优先级\n\n> **操作 page 正文时，优先使用页面级工具，不要默认走原子 Block 工具：**\n\n| 场景 | 推荐工具 |\n|------|---------|\n| 创建/更新 page 正文 | `block_fetch_page` + `block_update_page` |\n| 读取页面结构用于编辑 | `block_fetch_page(render_mode=\"mdx\")` |\n| 读取页面内容用于阅读 | `block_fetch_page(render_mode=\"clean\")` 或 `entry_describe_ai_parse_content` |\n| 局部插入新内容 | `block_update_page(command=\"update_content\")` |\n| 大范围重写 | `block_update_page(command=\"replace_content\")` |\n| 删除指定块 | `block_update_page(command=\"delete_blocks\")` |\n| 需要低层块级能力（用户明确要求） | 原子 Block 工具 |\n\n---\n\n## 📄 block_fetch_page 使用说明\n\n```\nrender_mode 选择：\n- \"markdown\"→ 返回可回写的乐享 block-markdown，用于文本替换编辑\n- \"mdx\"       → 返回带 data-id 的结构化 MDX，用于结构化编辑（replace_blocks）\n- \"clean\"     → 仅用于阅读/摘要，不可回写\n```\n\n>修改页面前必须先调用 `block_fetch_page`，拿到当前内容再编辑。\n\n---\n\n## 📝 block_update_page 命令说明\n\n| 命令 | 说明 | 关键参数 |\n|------|------|---------|\n| `replace_content` | 替换整页内容（大范围重写） | `new_str`（新内容） |\n| `update_content` | 搜索替换（局部更新，支持多条） | `content_updates: [{old_str, new_str}]` |\n| `delete_blocks` | 按 block_id 删除块 | `block_ids` |\n| `replace_blocks` | 按 block_id 替换 MDX 片段 | `block_replacements`（需 `content_format=mdx`） |\n\n**重要约束：**\n- `update_content` 的 `old_str` 必须精确来自 `block_fetch_page` 的输出，不依赖相似匹配\n- 删除内容时将 `new_str` 设为空字符串，或优先使用 `delete_blocks`\n- 插入/追加内容：把 `old_str` 替换为 `old_str +新内容`\n- `dry_run=true` 只校验不写回，可用于预检\n\n---\n\n## 🖼️ 块附件/图片上传流程\n\n上传图片或附件到 Block 时使用 `block_apply_block_attachment_upload`：\n\n```\nStep 1: block_apply_block_attachment_upload\n  → 返回 session_id + upload_url\n\nStep 2: curl -X PUT --data-binary \"@文件\" upload_url\n  （HTTP PUT，非 MCP 调用）\n\nStep 3: 在 block_create_block_descendant 中，attachment/image block\n  的 session_id 字段传入 session_id\n```\n\n>⚠️ 暂不支持视频（VOD）上传，video block 请使用 `file_id` 字段。\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. **优先页面级工具**：操作 page 正文时优先用 `block_fetch_page` + `block_update_page`，不要默认走原子 Block 工具或导入转换逻辑\n2. **Block ID 映射**：`block_id` 为客户端临时 ID，服务端返回实际 ID 映射\n3. **标题与内容平级**：标题块不能包含 children，通过顶层 `children` 顺序体现文档结构\n4. **`_mcp_fields` 优化**：所有工具支持 `_mcp_fields` 参数选择返回字段，减少 token 消耗\n5. 参数不确定时以 `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 v2.2.1:references/comment.md\n\n# 乐享评论\n\n> **前置条件**：本 skill 需要已配置乐享 MCP 连接。如未配置，请先读取 `references/setup.md`。\n> **触发场景**：用户想查看某个知识页面的评论、讨论内容时使用。当前仅支持读取评论，不支持通过 MCP 发布评论。\n\n---\n\n## 工具概览\n\n| 工具 | 说明 |\n|------|------|\n| `comment_list_comments` | 获取知识条目的评论列表 |\n| `comment_describe_comment` | 获取评论详情（含评论内容） |\n\n---\n\n## 使用流程\n\n### 查看页面评论\n\n```\nStep 1: 获取 entry_id\n  - 从用户提供的页面链接中提取：{domain}/pages/{entry_id}\n  - 或通过 search_kb_search 搜索后获取\n\nStep 2: comment_list_comments(\n  target_type=\"kb_entry\",\n  target_id=<entry_id>\n)\n→ 返回评论列表（评论 ID、作者、时间等元信息）\n\nStep 3（可选，获取评论正文）: comment_describe_comment(\n  target_type=\"kb_entry\",\n  target_id=<entry_id>\n)\n→ 返回评论详情，含content 字段\n```\n\n---\n\n## ⚠️ 注意事项\n\n1. **`content` 字段格式特殊**：评论的 `content` 不是普通 HTML，需要特别注意解析，不能直接当普通文本展示\n2. **`target_type` 固定值**：当前只支持 `\"kb_entry\"`（页面评论）\n3. **只读能力**：当前 MCP 只支持读取评论，无法通过 MCP 发布新评论或回复\n4. 参数不确定时以 `get_tool_schema(tool_name=\"xxx\")` 返回为准\n\nFile v2.2.1: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| 智能表格写入返回 999 | CellValue 结构不符合定义 | `text` 写成 `[{\"text_run\":{\"content\":\"...\"}}]`，详见下文错误五 |\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## 错误五：智能表格写入返回 999（CellValue 格式错误）\n\n### 错误表现\n\n调用 `smartsheet_create_records` / `smartsheet_update_records` 返回 **999 系统错误**，没有明确的参数错误提示。\n\n### 根因\n\n`fields` 的 value（CellValue）结构不符合乐享定义。\n\n`CellValue.text` 是 `repeated TextElement`，而 `TextElement` 是 `oneof { text_run / mention_staff / ... }`，**纯文本必须写在 `text_run.content` 里**：\n\n```json\n// ✅ 正确格式\n{\"text\": [{\"text_run\": {\"content\": \"张三\"}}]}\n```\n\n结构不符合该定义时，protojson 反序列化失败，网关返回 999。\n\n### 正确参数\n\n```json\n{\n  \"entry_id\": \"<entry_id>\",\n  \"smartsheet_id\": \"<smartsheet_id>\",\n  \"records\": [\n    {\n      \"fields\": {\n        \"<field_id_姓名>\": {\"text\": [{\"text_run\": {\"content\": \"张三\"}}]},\n        \"<field_id_年龄>\": {\"number\": 28},\n        \"<field_id_城市>\": {\"single_select\": {\"name\": \"北京\"}}\n      }\n    }\n  ]\n}\n```\n\n### 通用防错做法：先读后写\n\n写入前先 `smartsheet_list_records` 读一条真实记录，**照抄**返回的 `fields` 结构构造参数——读接口返回的 CellValue 与写接口期望的结构完全一致，可从根本上避免格式出错。\n\n> 拿到 999 时**不要原样重试**，先读一条真实记录、修正格式后再试。更完整的类型说明见 `references/smartsheet.md`。\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 v2.2.1: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 v2.2.1: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\nArchive v2.2.0: 31 files, 66762 bytes\n\nFiles: mcp.json (319b), README.md (6748b), references/base.md (12051b), references/block-schema.md (3378b), references/block-update.md (2284b), references/blocks.md (5603b), references/comment.md (1419b), references/common-errors.md (8479b), references/connectors.md (2207b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/draft.md (2455b), references/files.md (6603b), 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 (4390b), references/setup.md (7495b), references/skill-maintenance.md (4976b), references/smartsheet.md (4358b), references/theme-config.md (3801b), references/writer.md (5762b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), skill-card.md (3086b), SKILL.md (7994b), _meta.json (136b)\n\nFile v2.2.0:SKILL.md\n\n---\nname: lexiang-knowledge-base\nversion: 2.2.0\ndescription: \"乐享知识库 MCP 全功能 Skill。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供 lexiangla.com 链接，或涉及知识库的搜索/写入/编辑/文件/配置/评论/草稿/智能表格等操作时使用。\"\n---\n\n# 乐享知识库 MCP Skill\n\n当用户提到「**乐享**」「**知识库**」「**个人知识库**」「**我的知识库**」「**lexiang**」，或提供 `lexiangla.com` 链接，或给出 `space_id`、`entry_id`、`/spaces/`、`/pages/` 等乐享标识时，读取本 Skill。\n\n---\n\n## ⛔ MANDATORY RULES — 必须遵守\n\n1. **遇到 401 / 连接断开**：立即停止重试，读取 `references/setup.md`；内置连接器平台（WorkBuddy/QClaw 等）引导重新授权，其他平台引导续期\n2. **写入操作**：必须基于用户明确提供的目标（URL/ID/名称确认），**禁止**自行遍历或猜测目标\n3. **链接生成**：必须使用 `whoami()` 返回的 `company.company_domain` 作为域名，**禁止**使用 MCP endpoint 拼接用户链接\n4. **company_from**：不能拼接为子域名，只能作 `?company_from=xxx` 查询参数\n5. **强制检索**：当用户消息同时包含「乐享/知识库」等平台词 + 「文档/论文/文章/内容/资料/笔记/之前写的/上次的/风格」等内容词时，**必须先调用 `search_kb_search` 或 `search_kb_embedding_search` 获取实际内容**，不得凭空分析或直接生成回答\n6. **大批量保护**：文件/条目数量 > 20 个时，**必须分批执行**（每批 ≤ 20 个）；操作前告知用户数量和策略，禁止一次性提交导致 token 超限，详见 `references/files.md`\n\n---\n\n## 🔗 链接生成规则（全局通用）\n\n所有操作完成后返回链接时，统一遵循：\n\n| `company.company_domain` 类型 | 链接格式 | 示例 |\n|------------------------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\n\n**`{company_from}` 获取优先级：**\n1. mcp.json `url` 字段中的 `company_from` 参数\n2. 若无，使用 `whoami().company.code`\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| 智能表格 / 结构化数据 | `references/smartsheet.md` | 「智能表格」「乐享表格」「表格里的数据」「新增一行」「查询记录」 |\n| 草稿 / 存草稿 / 发布 | `references/draft.md` | 「先存草稿」「保存为草稿」「发布草稿」「查看草稿」 |\n| 查看评论 | `references/comment.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，引导续期（点续期按钮，无需重新配置）\n → 连接失败：读取 references/setup.md，引导完成初始配置\n```\n\n---\n\n## 📚 参考文件索引\n\n> **按需加载**：根据意图路由表，只 Read 对应文件，无需一次性加载全部。\n\n| 文件 | 职责 |\n|------|------|\n| `references/setup.md` | Token 配置、续期、WorkBuddy OAuth、故障排查 |\n| `references/search.md` | 关键词/语义搜索、内容读取、目录浏览 |\n| `references/writer.md` | 新建文档、导入内容、公众号收藏 |\n| `references/blocks.md` | 已有页面的 Block 级增删改移 |\n| `references/files.md` | 二进制文件上传/下载（三步流程） |\n| `references/connectors.md` | 腾讯会议录制导入 |\n| `references/smartsheet.md` | 智能表格增删查改、schema 管理 |\n| `references/draft.md` | Markdown 草稿保存、发布、管理 |\n| `references/comment.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: **2.2.0**\n\nFile v2.2.0:README.md\n\n# lexiang-skills\n\n**乐享知识库 MCP Skill（v2.1.0）**\n\n为 AI Agent 提供乐享知识库的全功能操作能力，包括搜索阅读、文档写入、Block 编辑、文件上传、外部导入等。\n\n---\n\n## 快速开始\n\n### WorkBuddy 用户\n\nWorkBuddy 已内置乐享连接器，**无需手动配置**：\n\n1. 在 WorkBuddy「集成」页面找到「乐享」连接器\n2. 点击「授权」完成 OAuth 登录，连接器自动激活\n\n### 其他平台（OpenClaw、Claude 等）\n\n访问 [https://lexiangla.com/mcp](https://lexiangla.com/mcp) 获取 `COMPANY_FROM` 和 `LEXIANG_TOKEN`，填入 `mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"enabled\": true,\n      \"url\": \"https://mcp.lexiang-app.com/mcp?company_from=你的COMPANY_FROM\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 目录结构\n\n```\nlexiang-skills/\n├── SKILL.md                  # 顶层路由入口（意图识别 → 参考文件）\n├── mcp.json                  # MCP 配置模板\n├── README.md                 # 本文件\n├── assets/                   # 静态资源\n├── references/               # 参考文档（19 份）\n│   ├── base.md               # 数据模型、URL 规则、完整安全规则、工具发现\n│   ├── setup.md              # Token 配置、续期、WorkBuddy OAuth、故障排查\n│   ├── search.md             # 关键词/语义搜索、内容读取、目录浏览\n│   ├── writer.md             # 新建文档、导入内容、公众号收藏\n│   ├── blocks.md             # 已有页面的 Block 级增删改移\n│   ├── files.md              # 二进制文件上传/下载（三步流程）\n│   ├── connectors.md         # 腾讯会议录制导入、iWiki 文档迁移\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| 导入腾讯会议 / iWiki 迁移 | `references/connectors.md` | 「导入会议录制」「迁移 iWiki 文档」 |\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 处理**：不重试，引导用户续期（点续期按钮即可恢复，无需重新配置）\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 配置、续期、WorkBuddy OAuth、故障排查 |\n| `references/search.md` | 关键词/语义搜索、内容读取、目录浏览 |\n| `references/writer.md` | 新建文档、导入内容、公众号收藏 |\n| `references/blocks.md` | 已有页面的 Block 级增删改移 |\n| `references/files.md` | 二进制文件上传/下载（三步流程） |\n| `references/connectors.md` | 腾讯会议录制导入、iWiki 文档迁移 |\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- 乐享平台：https://lexiangla.com\n- 获取 MCP 配置：https://lexiangla.com/mcp\n- MCP 协议：https://modelcontextprotocol.io\n\nFile v2.2.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 v2.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn721jbsqc97byg79gg835yt4n81rzya\",\n  \"slug\": \"lexiang-mcp-skill\",\n  \"version\": \"2.2.0\",\n  \"publishedAt\": 1787554688565\n}\n\nFile v2.2.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://csig.lexiangla.com` 或 `https://lexiangla.com`）\n\n> **⛔ 严禁使用 MCP endpoint 拼接任何用户可访问的链接！** MCP 域名仅用于接口调用，不是用户访问地址。\n> **⛔ 严禁将 `company_from` 拼接为子域名！** `company_from` 只能作为 URL 查询参数（`?company_from=xxx`）。\n\n| 资源 | URL 格式 |\n|------|----------|\n| 团队首页 | `{domain}/t/{team_id}/spaces` |\n| 知识库 | `{domain}/spaces/{space_id}` |\n| 知识条目 | `{domain}/pages/{entry_id}` |\n\n**链接生成步骤（所有操作通用）：**\n\n1. 取 `whoami()` 返回的 `company.company_domain` 作为 `{domain}`\n2. 判断 `{domain}` 是否为顶级域名（不含三级前缀，如 `lexiangla.com`）：\n   - **是**：使用 `{domain}/pages/{entry_id}?company_from={company_from}`\n     - `{company_from}` 优先取 mcp.json `url` 中的 `company_from` 参数\n     - 若无，取 `whoami()` 返回的 `company.code` ← **此时已调用过 whoami，直接取该值，不能省略**\n   - **否**（如 `csig.lexiangla.com`）：使用 `{domain}/pages/{entry_id}`，无需追加参数\n\n| `{domain}` 类型 | 链接格式 | 示例 |\n|----------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\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://lexiangla.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`、`entry_rename_entry`、`entry_move_entry`、`entry_set_entry_validity`、`block_update_block`、`block_update_blocks`、`block_update_page`、`block_create_block_descendant`、`block_delete_block`、`block_delete_block_children`、`block_move_blocks`、`file_apply_upload`、`file_commit_upload`、`file_create_hyperlink`、`file_revert_file`、`draft_save_markdown_draft`、`draft_publish_markdown_draft`、`draft_delete_markdown_draft`、`smartsheet_create`、`smartsheet_create_records`、`smartsheet_update_records`、`smartsheet_delete_records`、`smartsheet_update_schema`、`smartsheet_create_field`、`smartsheet_update_field`、`smartsheet_delete_field`、`smartsheet_create_view`、`smartsheet_update_view`、`smartsheet_delete_view`\n\n**只读操作**（不受安全规则限制，可直接执行）：\n`team_list_teams`、`team_describe_team`、`team_list_frequent_teams`、`space_list_spaces`、`space_describe_space`、`space_list_recently_spaces`、`space_describe_personal_space`、`entry_list_children`、`entry_describe_entry`、`entry_describe_ai_parse_content`、`entry_list_parents`、`entry_list_latest_entries`、`entry_list_recently_entries`、`block_list_block_children`、`block_describe_block`、`block_fetch_page`、`search_kb_search`、`search_kb_embedding_search`、`lexiang_search`、`lexiang_fetch`、`file_describe_file`、`file_download_file`、`file_list_revisions`、`draft_describe_markdown_draft`、`smartsheet_fetch`、`smartsheet_list`、`smartsheet_list_smartsheets`、`smartsheet_list_records`、`smartsheet_describe_record`、`smartsheet_list_fields`、`smartsheet_list_views`、`comment_list_comments`、`comment_describe_comment`、`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| `references/smartsheet.md` | 智能表格增删查改、schema 管理 |\n| `references/draft.md` | Markdown 草稿保存、发布、管理 |\n| `references/comment.md` | 知识页面评论查看 |\n\n### 辅助脚本（scripts/）\n\n| 脚本 | 说明 |\n|------|------|\n| `scripts/upload-files.py` | 批量文件上传（支持单文件/文件夹/并行） |\n| `scripts/sync-folder.ts` | 文件夹增量同步 |\n\n**upload-files.py 用法：**\n\n```bash\n# 单文件上传\npython scripts/upload-files.py --files doc.md --entry-id <parent_entry_id>\n\n# 文件夹批量上传（并行）\npython scripts/upload-files.py --folder ./docs --entry-id <parent_entry_id> --parallel 5\n\n# 生成上传计划（dry-run）\npython scripts/upload-files.py --folder ./docs --entry-id <entry_id> --output plan.json --dry-run\n```\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 v2.2.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 v2.2.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 v2.2.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###📄 页面级操作（优先使用）\n- `block_fetch_page` — 获取页面正文（支持 markdown/mdx/clean 三种格式）\n- `block_update_page` — 命令式更新页面内容（replace/update/delete/replace_blocks）\n\n### 🧩 原子 Block 操作\n- `block_convert_content_to_blocks` — Markdown/HTML转 Block 结构（纯转换，不创建）\n- `block_create_block_descendant` — 在指定块下创建子块结构\n- `block_update_block` — 单块更新\n- `block_update_blocks` — 批量更新多个块\n- `block_move_blocks` — 移动块到新位置\n- `block_delete_block_children` — 删除指定子块\n- `block_delete_block` — 删除指定块（含子孙）\n- `block_describe_block` — 获取单个块详情\n- `block_list_block_children` — 列出块的子节点\n- `block_apply_block_attachment_upload` — 申请块附件/图片上传凭证\n\n### 🔎 资源快捷访问\n- `lexiang_fetch` — 按资源类型读取单个乐享资源（entry/space/team/file/block/smartsheet/record）\n- `lexiang_search` — 搜索乐享资源（doc/space/team/all）\n\n---\n\n## 🛠️ 工具选择优先级\n\n> **操作 page 正文时，优先使用页面级工具，不要默认走原子 Block 工具：**\n\n| 场景 | 推荐工具 |\n|------|---------|\n| 创建/更新 page 正文 | `block_fetch_page` + `block_update_page` |\n| 读取页面结构用于编辑 | `block_fetch_page(render_mode=\"mdx\")` |\n| 读取页面内容用于阅读 | `block_fetch_page(render_mode=\"clean\")` 或 `entry_describe_ai_parse_content` |\n| 局部插入新内容 | `block_update_page(command=\"update_content\")` |\n| 大范围重写 | `block_update_page(command=\"replace_content\")` |\n| 删除指定块 | `block_update_page(command=\"delete_blocks\")` |\n| 需要低层块级能力（用户明确要求） | 原子 Block 工具 |\n\n---\n\n## 📄 block_fetch_page 使用说明\n\n```\nrender_mode 选择：\n- \"markdown\"→ 返回可回写的乐享 block-markdown，用于文本替换编辑\n- \"mdx\"       → 返回带 data-id 的结构化 MDX，用于结构化编辑（replace_blocks）\n- \"clean\"     → 仅用于阅读/摘要，不可回写\n```\n\n>修改页面前必须先调用 `block_fetch_page`，拿到当前内容再编辑。\n\n---\n\n## 📝 block_update_page 命令说明\n\n| 命令 | 说明 | 关键参数 |\n|------|------|---------|\n| `replace_content` | 替换整页内容（大范围重写） | `new_str`（新内容） |\n| `update_content` | 搜索替换（局部更新，支持多条） | `content_updates: [{old_str, new_str}]` |\n| `delete_blocks` | 按 block_id 删除块 | `block_ids` |\n| `replace_blocks` | 按 block_id 替换 MDX 片段 | `block_replacements`（需 `content_format=mdx`） |\n\n**重要约束：**\n- `update_content` 的 `old_str` 必须精确来自 `block_fetch_page` 的输出，不依赖相似匹配\n- 删除内容时将 `new_str` 设为空字符串，或优先使用 `delete_blocks`\n- 插入/追加内容：把 `old_str` 替换为 `old_str +新内容`\n- `dry_run=true` 只校验不写回，可用于预检\n\n---\n\n## 🖼️ 块附件/图片上传流程\n\n上传图片或附件到 Block 时使用 `block_apply_block_attachment_upload`：\n\n```\nStep 1: block_apply_block_attachment_upload\n  → 返回 session_id + upload_url\n\nStep 2: curl -X PUT --data-binary \"@文件\" upload_url\n  （HTTP PUT，非 MCP 调用）\n\nStep 3: 在 block_create_block_descendant 中，attachment/image block\n  的 session_id 字段传入 session_id\n```\n\n>⚠️ 暂不支持视频（VOD）上传，video block 请使用 `file_id` 字段。\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. **优先页面级工具**：操作 page 正文时优先用 `block_fetch_page` + `block_update_page`，不要默认走原子 Block 工具或导入转换逻辑\n2. **Block ID 映射**：`block_id` 为客户端临时 ID，服务端返回实际 ID 映射\n3. **标题与内容平级**：标题块不能包含 children，通过顶层 `children` 顺序体现文档结构\n4. **`_mcp_fields` 优化**：所有工具支持 `_mcp_fields` 参数选择返回字段，减少 token 消耗\n5. 参数不确定时以 `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 v2.2.0:references/comment.md\n\n# 乐享评论\n\n> **前置条件**：本 skill 需要已配置乐享 MCP 连接。如未配置，请先读取 `references/setup.md`。\n> **触发场景**：用户想查看某个知识页面的评论、讨论内容时使用。当前仅支持读取评论，不支持通过 MCP 发布评论。\n\n---\n\n## 工具概览\n\n| 工具 | 说明 |\n|------|------|\n| `comment_list_comments` | 获取知识条目的评论列表 |\n| `comment_describe_comment` | 获取评论详情（含评论内容） |\n\n---\n\n## 使用流程\n\n### 查看页面评论\n\n```\nStep 1: 获取 entry_id\n  - 从用户提供的页面链接中提取：{domain}/pages/{entry_id}\n  - 或通过 search_kb_search 搜索后获取\n\nStep 2: comment_list_comments(\n  target_type=\"kb_entry\",\n  target_id=<entry_id>\n)\n→ 返回评论列表（评论 ID、作者、时间等元信息）\n\nStep 3（可选，获取评论正文）: comment_describe_comment(\n  target_type=\"kb_entry\",\n  target_id=<entry_id>\n)\n→ 返回评论详情，含content 字段\n```\n\n---\n\n## ⚠️ 注意事项\n\n1. **`content` 字段格式特殊**：评论的 `content` 不是普通 HTML，需要特别注意解析，不能直接当普通文本展示\n2. **`target_type` 固定值**：当前只支持 `\"kb_entry\"`（页面评论）\n3. **只读能力**：当前 MCP 只支持读取评论，无法通过 MCP 发布新评论或回复\n4. 参数不确定时以 `get_tool_schema(tool_name=\"xxx\")` 返回为准\n\nFile v2.2.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 v2.2.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 v2.2.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\nArchive v2.1.1: 28 files, 59700 bytes\n\nFiles: mcp.json (319b), README.md (6748b), references/base.md (10886b), 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 (6129b), 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 (3326b), references/setup.md (7495b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), references/writer.md (4733b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), skill-card.md (3034b), SKILL.md (7355b), _meta.json (136b)\n\nFile v2.1.1:SKILL.md\n\n---\nname: lexiang-knowledge-base\nversion: 2.1.0\ndescription: \"乐享知识库 MCP 全功能 Skill。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供 lexiangla.com 链接，或涉及知识库的搜索/写入/编辑/文件/配置等操作时使用。\"\n---\n\n# 乐享知识库 MCP Skill\n\n当用户提到「**乐享**」「**知识库**」「**个人知识库**」「**我的知识库**」「**lexiang**」，或提供 `lexiangla.com` 链接，或给出 `space_id`、`entry_id`、`/spaces/`、`/pages/` 等乐享标识时，读取本 Skill。\n\n---\n\n## ⛔ MANDATORY RULES — 必须遵守\n\n1. **遇到 401 / 连接断开**：立即停止重试，读取 `references/setup.md`；内置连接器平台（WorkBuddy/QClaw 等）引导重新授权，其他平台引导续期\n2. **写入操作**：必须基于用户明确提供的目标（URL/ID/名称确认），**禁止**自行遍历或猜测目标\n3. **链接生成**：必须使用 `whoami()` 返回的 `company.company_domain` 作为域名，**禁止**使用 MCP endpoint 拼接用户链接\n4. **company_from**：不能拼接为子域名，只能作 `?company_from=xxx` 查询参数\n5. **强制检索**：当用户消息同时包含「乐享/知识库」等平台词 + 「文档/论文/文章/内容/资料/笔记/之前写的/上次的/风格」等内容词时，**必须先调用 `search_kb_search` 或 `search_kb_embedding_search` 获取实际内容**，不得凭空分析或直接生成回答\n6. **大批量保护**：文件/条目数量 > 20 个时，**必须分批执行**（每批 ≤ 20 个）；操作前告知用户数量和策略，禁止一次性提交导致 token 超限，详见 `references/files.md`\n\n---\n\n## 🔗 链接生成规则（全局通用）\n\n所有操作完成后返回链接时，统一遵循：\n\n| `company.company_domain` 类型 | 链接格式 | 示例 |\n|------------------------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\n\n**`{company_from}` 获取优先级：**\n1. mcp.json `url` 字段中的 `company_from` 参数\n2. 若无，使用 `whoami().company.code`\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，引导续期（点续期按钮，无需重新配置）\n → 连接失败：读取 references/setup.md，引导完成初始配置\n```\n\n---\n\n## 📚 参考文件索引\n\n> **按需加载**：根据意图路由表，只 Read 对应文件，无需一次性加载全部。\n\n| 文件 | 职责 |\n|------|------|\n| `references/setup.md` | Token 配置、续期、WorkBuddy OAuth、故障排查 |\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: **2.1.0**\n\nFile v2.1.1:README.md\n\n# lexiang-skills\n\n**乐享知识库 MCP Skill（v2.1.0）**\n\n为 AI Agent 提供乐享知识库的全功能操作能力，包括搜索阅读、文档写入、Block 编辑、文件上传、外部导入等。\n\n---\n\n## 快速开始\n\n### WorkBuddy 用户\n\nWorkBuddy 已内置乐享连接器，**无需手动配置**：\n\n1. 在 WorkBuddy「集成」页面找到「乐享」连接器\n2. 点击「授权」完成 OAuth 登录，连接器自动激活\n\n### 其他平台（OpenClaw、Claude 等）\n\n访问 [https://lexiangla.com/mcp](https://lexiangla.com/mcp) 获取 `COMPANY_FROM` 和 `LEXIANG_TOKEN`，填入 `mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"enabled\": true,\n      \"url\": \"https://mcp.lexiang-app.com/mcp?company_from=你的COMPANY_FROM\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 目录结构\n\n```\nlexiang-skills/\n├── SKILL.md                  # 顶层路由入口（意图识别 → 参考文件）\n├── mcp.json                  # MCP 配置模板\n├── README.md                 # 本文件\n├── assets/                   # 静态资源\n├── references/               # 参考文档（19 份）\n│   ├── base.md               # 数据模型、URL 规则、完整安全规则、工具发现\n│   ├── setup.md              # Token 配置、续期、WorkBuddy OAuth、故障排查\n│   ├── search.md             # 关键词/语义搜索、内容读取、目录浏览\n│   ├── writer.md             # 新建文档、导入内容、公众号收藏\n│   ├── blocks.md             # 已有页面的 Block 级增删改移\n│   ├── files.md              # 二进制文件上传/下载（三步流程）\n│   ├── connectors.md         # 腾讯会议录制导入、iWiki 文档迁移\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| 导入腾讯会议 / iWiki 迁移 | `references/connectors.md` | 「导入会议录制」「迁移 iWiki 文档」 |\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 处理**：不重试，引导用户续期（点续期按钮即可恢复，无需重新配置）\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 配置、续期、WorkBuddy OAuth、故障排查 |\n| `references/search.md` | 关键词/语义搜索、内容读取、目录浏览 |\n| `references/writer.md` | 新建文档、导入内容、公众号收藏 |\n| `references/blocks.md` | 已有页面的 Block 级增删改移 |\n| `references/files.md` | 二进制文件上传/下载（三步流程） |\n| `references/connectors.md` | 腾讯会议录制导入、iWiki 文档迁移 |\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- 乐享平台：https://lexiangla.com\n- 获取 MCP 配置：https://lexiangla.com/mcp\n- MCP 协议：https://modelcontextprotocol.io\n\nFile v2.1.1: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 v2.1.1:_meta.json\n\n{\n  \"ownerId\": \"kn721jbsqc97byg79gg835yt4n81rzya\",\n  \"slug\": \"lexiang-mcp-skill\",\n  \"version\": \"2.1.1\",\n  \"publishedAt\": 1781597907572\n}\n\nFile v2.1.1: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://csig.lexiangla.com` 或 `https://lexiangla.com`）\n\n> **⛔ 严禁使用 MCP endpoint 拼接任何用户可访问的链接！** MCP 域名仅用于接口调用，不是用户访问地址。\n> **⛔ 严禁将 `company_from` 拼接为子域名！** `company_from` 只能作为 URL 查询参数（`?company_from=xxx`）。\n\n| 资源 | URL 格式 |\n|------|----------|\n| 团队首页 | `{domain}/t/{team_id}/spaces` |\n| 知识库 | `{domain}/spaces/{space_id}` |\n| 知识条目 | `{domain}/pages/{entry_id}` |\n\n**链接生成步骤（所有操作通用）：**\n\n1. 取 `whoami()` 返回的 `company.company_domain` 作为 `{domain}`\n2. 判断 `{domain}` 是否为顶级域名（不含三级前缀，如 `lexiangla.com`）：\n   - **是**：使用 `{domain}/pages/{entry_id}?company_from={company_from}`\n     - `{company_from}` 优先取 mcp.json `url` 中的 `company_from` 参数\n     - 若无，取 `whoami()` 返回的 `company.code` ← **此时已调用过 whoami，直接取该值，不能省略**\n   - **否**（如 `csig.lexiangla.com`）：使用 `{domain}/pages/{entry_id}`，无需追加参数\n\n| `{domain}` 类型 | 链接格式 | 示例 |\n|----------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\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://lexiangla.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**upload-files.py 用法：**\n\n```bash\n# 单文件上传\npython scripts/upload-files.py --files doc.md --entry-id <parent_entry_id>\n\n# 文件夹批量上传（并行）\npython scripts/upload-files.py --folder ./docs --entry-id <parent_entry_id> --parallel 5\n\n# 生成上传计划（dry-run）\npython scripts/upload-files.py --folder ./docs --entry-id <entry_id> --output plan.json --dry-run\n```\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 v2.1.1: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 v2.1.1: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 v2.1.1: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 v2.1.1: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 v2.1.1: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 v2.1.1: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 v2.1.1: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 |\n\nArchive v2.0.2: 28 files, 58975 bytes\n\nFiles: mcp.json (319b), README.md (3977b), references/base.md (10886b), 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 (6129b), 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 (3326b), references/setup.md (7495b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), references/writer.md (4733b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), skill-card.md (2918b), SKILL.md (7355b), _meta.json (136b)\n\nFile v2.0.2:SKILL.md\n\n---\nname: lexiang-knowledge-base\nversion: 2.1.0\ndescription: \"乐享知识库 MCP 全功能 Skill。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供 lexiangla.com 链接，或涉及知识库的搜索/写入/编辑/文件/配置等操作时使用。\"\n---\n\n# 乐享知识库 MCP Skill\n\n当用户提到「**乐享**」「**知识库**」「**个人知识库**」「**我的知识库**」「**lexiang**」，或提供 `lexiangla.com` 链接，或给出 `space_id`、`entry_id`、`/spaces/`、`/pages/` 等乐享标识时，读取本 Skill。\n\n---\n\n## ⛔ MANDATORY RULES — 必须遵守\n\n1. **遇到 401 / 连接断开**：立即停止重试，读取 `references/setup.md`；内置连接器平台（WorkBuddy/QClaw 等）引导重新授权，其他平台引导续期\n2. **写入操作**：必须基于用户明确提供的目标（URL/ID/名称确认），**禁止**自行遍历或猜测目标\n3. **链接生成**：必须使用 `whoami()` 返回的 `company.company_domain` 作为域名，**禁止**使用 MCP endpoint 拼接用户链接\n4. **company_from**：不能拼接为子域名，只能作 `?company_from=xxx` 查询参数\n5. **强制检索**：当用户消息同时包含「乐享/知识库」等平台词 + 「文档/论文/文章/内容/资料/笔记/之前写的/上次的/风格」等内容词时，**必须先调用 `search_kb_search` 或 `search_kb_embedding_search` 获取实际内容**，不得凭空分析或直接生成回答\n6. **大批量保护**：文件/条目数量 > 20 个时，**必须分批执行**（每批 ≤ 20 个）；操作前告知用户数量和策略，禁止一次性提交导致 token 超限，详见 `references/files.md`\n\n---\n\n## 🔗 链接生成规则（全局通用）\n\n所有操作完成后返回链接时，统一遵循：\n\n| `company.company_domain` 类型 | 链接格式 | 示例 |\n|------------------------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\n\n**`{company_from}` 获取优先级：**\n1. mcp.json `url` 字段中的 `company_from` 参数\n2. 若无，使用 `whoami().company.code`\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，引导续期（点续期按钮，无需重新配置）\n → 连接失败：读取 references/setup.md，引导完成初始配置\n```\n\n---\n\n## 📚 参考文件索引\n\n> **按需加载**：根据意图路由表，只 Read 对应文件，无需一次性加载全部。\n\n| 文件 | 职责 |\n|------|------|\n| `references/setup.md` | Token 配置、续期、WorkBuddy OAuth、故障排查 |\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: **2.1.0**\n\nFile v2.0.2:README.md\n\n# lexiang-skills\n\n**乐享知识库 MCP Skill（v2.0.0）**\n\n为 AI Agent 提供乐享知识库的全功能操作能力，包括搜索阅读、文档写入、Block 编辑、文件上传、外部导入等。\n\n---\n\n## 快速开始\n\n### WorkBuddy 用户\n\nWorkBuddy 已内置乐享连接器，**无需手动配置**：\n\n1. 在 WorkBuddy「集成」页面找到「乐享」连接器\n2. 点击「授权」完成 OAuth 登录，连接器自动激活\n\n### 其他平台（OpenClaw、Claude 等）\n\n访问 [https://lexiangla.com/mcp](https://lexiangla.com/mcp) 获取 `COMPANY_FROM` 和 `LEXIANG_TOKEN`，填入 `mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"enabled\": true,\n      \"url\": \"https://mcp.lexiang-app.com/mcp?company_from=你的COMPANY_FROM\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 目录结构\n\n```\nlexiang-skills/\n├── SKILL.md              # 顶层路由入口（意图识别 → 子模块）\n├── mcp.json              # MCP 配置模板\n├── base/\n│   └── SKILL.md         # 基础知识层：数据模型、URL 规则、安全规则、工具发现\n├── setup/\n│   └── SKILL.md         # MCP 配置、Token 续期、故障排查\n├── search/\n│   └── SKILL.md         # 搜索与内容阅读\n├── writer/\n│   └── SKILL.md         # 文档创建与写入\n├── blocks/\n│   └── SKILL.md         # 已有页面 Block 级编辑\n├── files/\n│   └── SKILL.md         # 二进制文件上传/下载\n├── connectors/\n│   └── SKILL.md         # 腾讯会议录制导入\n├── references/           # 详细参考文档（11 份）\n└── scripts/              # 辅助脚本\n```\n\n---\n\n## 子模块说明\n\n| 子模块 | 触发场景 |\n|--------|---------|\n| `setup` | 配置乐享、Token 过期、401 错误、切换企业 |\n| `search` | 搜索文档、阅读页面、浏览知识库目录 |\n| `writer` | 创建文档、保存内容、导入公众号文章 |\n| `blocks` | 修改已有页面、追加内容、调整排版 |\n| `files` | 上传 PDF/Word/图片等二进制文件 |\n| `connectors` | 导入腾讯会议录制 |\n\n---\n\n## 核心规则\n\n- **写入安全**：必须基于用户明确提供的目标（URL/ID/确认），禁止自行遍历猜测\n- **链接生成**：使用 `whoami().company.company_domain` 作为域名；顶级域名需追加 `?company_from=`（优先取 mcp.json，其次取 `whoami().company.code`）\n- **401 处理**：不重试，引导用户续期（点续期按钮即可恢复，无需重新配置）\n\n---\n\n## 辅助脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `scripts/upload-files.py` | 批量文件上传（支持单文件/文件夹/并行/dry-run） |\n| `scripts/sync-folder.ts` | 文件夹增量同步到乐享知识库 |\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| `references/common-errors.md` | 高频错误速查与修复 |\n| `references/block-schema.md` | Block 类型完整字段定义 |\n| `references/mcp-examples.md` | 复杂 Block 结构示例 |\n| `references/doc-templates.md` | 文档大纲模板（推广/技术/操作指南） |\n| `references/markdown-import.md` | Markdown 导入详解 |\n| `references/markdown-to-block.md` | Markdown 转 Block 指南 |\n| `references/folder-sync.md` | 文件夹同步方案 |\n| `references/content-reorganize.md` | 文档结构重组 |\n| `references/block-update.md` | 批量更新 Block 方法 |\n| `references/theme-config.md` | 主题配色配置 |\n\n---\n\n## 相关链接\n\n- 乐享平台：https://lexiangla.com\n- 获取 MCP 配置：https://lexiangla.com/mcp\n- MCP 协议：https://modelcontextprotocol.io\n\nFile v2.0.2: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 v2.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn721jbsqc97byg79gg835yt4n81rzya\",\n  \"slug\": \"lexiang-mcp-skill\",\n  \"version\": \"2.0.2\",\n  \"publishedAt\": 1780645964571\n}\n\nFile v2.0.2: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://csig.lexiangla.com` 或 `https://lexiangla.com`）\n\n> **⛔ 严禁使用 MCP endpoint 拼接任何用户可访问的链接！** MCP 域名仅用于接口调用，不是用户访问地址。\n> **⛔ 严禁将 `company_from` 拼接为子域名！** `company_from` 只能作为 URL 查询参数（`?company_from=xxx`）。\n\n| 资源 | URL 格式 |\n|------|----------|\n| 团队首页 | `{domain}/t/{team_id}/spaces` |\n| 知识库 | `{domain}/spaces/{space_id}` |\n| 知识条目 | `{domain}/pages/{entry_id}` |\n\n**链接生成步骤（所有操作通用）：**\n\n1. 取 `whoami()` 返回的 `company.company_domain` 作为 `{domain}`\n2. 判断 `{domain}` 是否为顶级域名（不含三级前缀，如 `lexiangla.com`）：\n   - **是**：使用 `{domain}/pages/{entry_id}?company_from={company_from}`\n     - `{company_from}` 优先取 mcp.json `url` 中的 `company_from` 参数\n     - 若无，取 `whoami()` 返回的 `company.code` ← **此时已调用过 whoami，直接取该值，不能省略**\n   - **否**（如 `csig.lexiangla.com`）：使用 `{domain}/pages/{entry_id}`，无需追加参数\n\n| `{domain}` 类型 | 链接格式 | 示例 |\n|----------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\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://lexiangla.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**upload-files.py 用法：**\n\n```bash\n# 单文件上传\npython scripts/upload-files.py --files doc.md --entry-id <parent_entry_id>\n\n# 文件夹批量上传（并行）\npython scripts/upload-files.py --folder ./docs --entry-id <parent_entry_id> --parallel 5\n\n# 生成上传计划（dry-run）\npython scripts/upload-files.py --folder ./docs --entry-id <entry_id> --output plan.json --dry-run\n```\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 v2.0.2: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 v2.0.2: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 v2.0.2: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 v2.0.2: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_l\n\nArchive v2.0.1: 27 files, 57884 bytes\n\nFiles: base/SKILL.md (11023b), blocks/SKILL.md (3404b), connectors/SKILL.md (3692b), files/SKILL.md (5498b), mcp.json (319b), README.md (4014b), references/block-schema.md (3378b), references/block-update.md (2284b), references/common-errors.md (8479b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/folder-sync.md (2089b), references/markdown-import.md (2367b), references/markdown-to-block.md (3864b), references/mcp-examples.md (5903b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), search/SKILL.md (3990b), setup/SKILL.md (7972b), skill-card.md (2959b), SKILL.md (4785b), writer/SKILL.md (5420b), _meta.json (136b)\n\nArchive v2.0.0: 26 files, 56463 bytes\n\nFiles: base/SKILL.md (11023b), blocks/SKILL.md (3404b), connectors/SKILL.md (3692b), files/SKILL.md (5498b), mcp.json (319b), README.md (4014b), references/block-schema.md (3378b), references/block-update.md (2284b), references/common-errors.md (8479b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/folder-sync.md (2089b), references/markdown-import.md (2367b), references/markdown-to-block.md (3864b), references/mcp-examples.md (5903b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), search/SKILL.md (3990b), setup/SKILL.md (7972b), SKILL.md (4785b), writer/SKILL.md (5420b), _meta.json (136b)\n\nArchive v0.1.6: 26 files, 56465 bytes\n\nFiles: base/SKILL.md (11023b), blocks/SKILL.md (3404b), connectors/SKILL.md (3692b), files/SKILL.md (5498b), mcp.json (319b), README.md (4014b), references/block-schema.md (3378b), references/block-update.md (2284b), references/common-errors.md (8479b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/folder-sync.md (2089b), references/markdown-import.md (2367b), references/markdown-to-block.md (3864b), references/mcp-examples.md (5903b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), search/SKILL.md (3990b), setup/SKILL.md (7972b), SKILL.md (4785b), writer/SKILL.md (5420b), _meta.json (136b)\n\nArchive v0.1.5: 24 files, 49042 bytes\n\nFiles: assets/examples/create-compare-table.json (2649b), assets/examples/create-tech-doc.json (5303b), assets/lexiang-block-schema.json (30624b), assets/themes/default.json (2538b), mcp.json (319b), README.md (724b), references/block-schema.md (3378b), references/block-update.md (2284b), references/common-errors.md (8479b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/folder-sync.md (2089b), references/markdown-import.md (2367b), references/markdown-to-block.md (3864b), references/mcp-examples.md (5903b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), setup.md (3160b), SKILL.md (20864b), _meta.json (136b)\n\nArchive v0.1.4: 24 files, 53442 bytes\n\nFiles: assets/examples/create-compare-table.json (2649b), assets/examples/create-tech-doc.json (5303b), assets/lexiang-block-schema.json (30624b), assets/themes/default.json (2538b), mcp.json (331b), README.md (724b), references/block-schema.md (3378b), references/block-update.md (2284b), references/common-errors.md (8455b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/folder-sync.md (2089b), references/markdown-import.md (2367b), references/markdown-to-block.md (3864b), references/mcp-examples.md (5903b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), setup.md (2128b), SKILL.md (40256b), _meta.json (136b)\n\nArchive v0.1.3: 24 files, 52760 bytes\n\nFiles: assets/examples/create-compare-table.json (2649b), assets/examples/create-tech-doc.json (5303b), assets/lexiang-block-schema.json (30624b), assets/themes/default.json (2538b), mcp.json (262b), README.md (669b), references/block-schema.md (3378b), references/block-update.md (2284b), references/common-errors.md (8455b), references/content-reorganize.md (2092b), references/doc-templates.md (1957b), references/folder-sync.md (2089b), references/markdown-import.md (2367b), references/markdown-to-block.md (3864b), references/mcp-examples.md (5903b), references/skill-maintenance.md (4976b), references/theme-config.md (3801b), scripts/README.md (2113b), scripts/sync-folder.ts (15150b), scripts/test_upload_files.py (12560b), scripts/upload-files.py (13046b), setup.sh (1199b), SKILL.md (40300b), _meta.json (136b)","readmeExcerpt":"Skill: 腾讯乐享知识库 Lexiang Knowledge Base Owner: lexiang Summary: 乐享知识库 MCP 全功能 Skill。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供 lexiangla.com 链接，或涉及知识库的搜索/写入/编辑/文件/配置/评论/草稿/智能表格等操作时使用。 Tags: latest:2.2.1 Version history: v2.2.1 | 2026-10-09T02:32:14.247Z | user - opt smartsheet v2.2.0 | 2026-08-24T06:58:08.565Z | user **Added support for评论、草稿和智能表格相关功能** - 新增 references/comment.md，实现知识页面评论查看 - 新增 references/draft.md，实现草稿保","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"MCP Tool: whoami\n → 成功：返回用户信息，继续执行\n → 401：读取 references/setup.md，引导续期（点续期按钮，无需重新配置）\n → 连接失败：读取 references/setup.md，引导完成初始配置"},{"language":"json","snippet":"{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"enabled\": true,\n      \"url\": \"https://mcp.lexiang-app.com/mcp?company_from=你的COMPANY_FROM\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}"},{"language":"text","snippet":"lexiang-skills/\n├── SKILL.md                  # 顶层路由入口（意图识别 → 参考文件）\n├── mcp.json                  # MCP 配置模板\n├── README.md                 # 本文件\n├── assets/                   # 静态资源\n├── references/               # 参考文档（19 份）\n│   ├── base.md               # 数据模型、URL 规则、完整安全规则、工具发现\n│   ├── setup.md              # Token 配置、续期、WorkBuddy OAuth、故障排查\n│   ├── search.md             # 关键词/语义搜索、内容读取、目录浏览\n│   ├── writer.md             # 新建文档、导入内容、公众号收藏\n│   ├── blocks.md             # 已有页面的 Block 级增删改移\n│   ├── files.md              # 二进制文件上传/下载（三步流程）\n│   ├── connectors.md         # 腾讯会议录制导入、iWiki 文档迁移\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"},{"language":"bash","snippet":"pip install aiohttp requests"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: lexiang-knowledge-base\nversion: 2.2.0\ndescription: \"乐享知识库 MCP 全功能 Skill。当用户提到「乐享」「知识库」「个人知识库」「我的知识库」「lexiang」，或提供 lexiangla.com 链接，或涉及知识库的搜索/写入/编辑/文件/配置/评论/草稿/智能表格等操作时使用。\"\n---\n\n# 乐享知识库 MCP Skill\n\n当用户提到「**乐享**」「**知识库**」「**个人知识库**」「**我的知识库**」「**lexiang**」，或提供 `lexiangla.com` 链接，或给出 `space_id`、`entry_id`、`/spaces/`、`/pages/` 等乐享标识时，读取本 Skill。\n\n---\n\n## ⛔ MANDATORY RULES — 必须遵守\n\n1. **遇到 401 / 连接断开**：立即停止重试，读取 `references/setup.md`；内置连接器平台（WorkBuddy/QClaw 等）引导重新授权，其他平台引导续期\n2. **写入操作**：必须基于用户明确提供的目标（URL/ID/名称确认），**禁止**自行遍历或猜测目标\n3. **链接生成**：必须使用 `whoami()` 返回的 `company.company_domain` 作为域名，**禁止**使用 MCP endpoint 拼接用户链接\n4. **company_from**：不能拼接为子域名，只能作 `?company_from=xxx` 查询参数\n5. **强制检索**：当用户消息同时包含「乐享/知识库」等平台词 + 「文档/论文/文章/内容/资料/笔记/之前写的/上次的/风格」等内容词时，**必须先调用 `search_kb_search` 或 `search_kb_embedding_search` 获取实际内容**，不得凭空分析或直接生成回答\n6. **大批量保护**：文件/条目数量 > 20 个时，**必须分批执行**（每批 ≤ 20 个）；操作前告知用户数量和策略，禁止一次性提交导致 token 超限，详见 `references/files.md`\n\n---\n\n## 🔗 链接生成规则（全局通用）\n\n所有操作完成后返回链接时，统一遵循：\n\n| `company.company_domain` 类型 | 链接格式 | 示例 |\n|------------------------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\n\n**`{company_from}` 获取优先级：**\n1. mcp.json `url` 字段中的 `company_from` 参数\n2. 若无，使用 `whoami().company.code`\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| 智能表格 / 结构化数据 | `references/smartsheet.md` | 「智能表格」「乐享表格」「表格里的数据」「新增一行」「查询记录」 |\n| 草稿 / 存草稿 / 发布 | `references/draft.md` | 「先存草稿」「保存为草稿」「发布草稿」「查看草稿」 |\n| 查看评论 | `references/comment.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 的内容」 | `ref"},{"path":"README.md","content":"# lexiang-skills\n\n**乐享知识库 MCP Skill（v2.1.0）**\n\n为 AI Agent 提供乐享知识库的全功能操作能力，包括搜索阅读、文档写入、Block 编辑、文件上传、外部导入等。\n\n---\n\n## 快速开始\n\n### WorkBuddy 用户\n\nWorkBuddy 已内置乐享连接器，**无需手动配置**：\n\n1. 在 WorkBuddy「集成」页面找到「乐享」连接器\n2. 点击「授权」完成 OAuth 登录，连接器自动激活\n\n### 其他平台（OpenClaw、Claude 等）\n\n访问 [https://lexiangla.com/mcp](https://lexiangla.com/mcp) 获取 `COMPANY_FROM` 和 `LEXIANG_TOKEN`，填入 `mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"lexiang\": {\n      \"enabled\": true,\n      \"url\": \"https://mcp.lexiang-app.com/mcp?company_from=你的COMPANY_FROM\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 你的LEXIANG_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 目录结构\n\n```\nlexiang-skills/\n├── SKILL.md                  # 顶层路由入口（意图识别 → 参考文件）\n├── mcp.json                  # MCP 配置模板\n├── README.md                 # 本文件\n├── assets/                   # 静态资源\n├── references/               # 参考文档（19 份）\n│   ├── base.md               # 数据模型、URL 规则、完整安全规则、工具发现\n│   ├── setup.md              # Token 配置、续期、WorkBuddy OAuth、故障排查\n│   ├── search.md             # 关键词/语义搜索、内容读取、目录浏览\n│   ├── writer.md             # 新建文档、导入内容、公众号收藏\n│   ├── blocks.md             # 已有页面的 Block 级增删改移\n│   ├── files.md              # 二进制文件上传/下载（三步流程）\n│   ├── connectors.md         # 腾讯会议录制导入、iWiki 文档迁移\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| 导入腾讯会议 / iWiki 迁移 | `references/connectors.md` | 「导入会议录制」「迁移 iWiki 文档」 |\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 处理**：不重试，引导用户续期（点续期按钮即可恢复，无需重新配置）\n- **强制检索**：用户提到「乐享里的文档/内容」时，必须先搜索再回答，禁止凭空生成\n\n> 完整规则详见 `SKILL.md` 和 `references/base.md`\n\n---\n\n## 辅助脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `scripts/upload-files.py` | 批量文件上传（支持单文件/文件夹/并行/dry-run） |\n| `scr"},{"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\": \"kn721jbsqc97byg79gg835yt4n81rzya\",\n  \"slug\": \"lexiang-mcp-skill\",\n  \"version\": \"2.2.1\",\n  \"publishedAt\": 1791513134247\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://csig.lexiangla.com` 或 `https://lexiangla.com`）\n\n> **⛔ 严禁使用 MCP endpoint 拼接任何用户可访问的链接！** MCP 域名仅用于接口调用，不是用户访问地址。\n> **⛔ 严禁将 `company_from` 拼接为子域名！** `company_from` 只能作为 URL 查询参数（`?company_from=xxx`）。\n\n| 资源 | URL 格式 |\n|------|----------|\n| 团队首页 | `{domain}/t/{team_id}/spaces` |\n| 知识库 | `{domain}/spaces/{space_id}` |\n| 知识条目 | `{domain}/pages/{entry_id}` |\n\n**链接生成步骤（所有操作通用）：**\n\n1. 取 `whoami()` 返回的 `company.company_domain` 作为 `{domain}`\n2. 判断 `{domain}` 是否为顶级域名（不含三级前缀，如 `lexiangla.com`）：\n   - **是**：使用 `{domain}/pages/{entry_id}?company_from={company_from}`\n     - `{company_from}` 优先取 mcp.json `url` 中的 `company_from` 参数\n     - 若无，取 `whoami()` 返回的 `company.code` ← **此时已调用过 whoami，直接取该值，不能省略**\n   - **否**（如 `csig.lexiangla.com`）：使用 `{domain}/pages/{entry_id}`，无需追加参数\n\n| `{domain}` 类型 | 链接格式 | 示例 |\n|----------------|----------|------|\n| 包含三级域名（如 `csig.lexiangla.com`） | `{domain}/pages/{entry_id}` | `https://csig.lexiangla.com/pages/abc` |\n| 顶级域名（如 `lexiangla.com`） | `{domain}/pages/{entry_id}?company_from={company_from}` | `https://lexiangla.com/pages/abc?company_from=csig` |\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://lexiangla.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`、`entry_rename_entry`、`entry_move_entry`、`entry_set_entry_validity`、`block_update_block`、`block_update_blocks`、`block_update_page`、`block_create_block_descendant`、`block_delete_block`、`block_delete_block_children`、`block_move_blocks`、`file_apply_upload`、`file_commit_upload`、`file"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1235,"uniquenessScore":39,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T19:07:05.168Z","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-09T19:07:05.168Z","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-10T05:40:04.012Z","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"}]}}}