46 KiB
46 KiB
文档（SmartCanvas）工具完整参考文档
腾讯文档（SmartCanvas）提供了一套完整的在线文档操作工具，支持创建、编辑智能文档。内容格式使用 MDX，向下兼容全部 Markdown 语法——标题、列表、表格、代码块、引用、图片、链接等标准 Markdown 可直接使用，同时支持分栏、高亮块、待办等高级排版组件。
目录
概念说明
| 概念 | 说明 |
|---|---|
file_id |
文档的唯一标识符，每个文档有唯一的 file_id |
page_id |
页面 ID，Page 是文档的基本容器单元，可通过 smartcanvas.read 读取页面内容 |
Block ID |
块 ID，smartcanvas.read / smartcanvas.find 返回的 MDX 中 id 属性值，用于 smartcanvas.edit 定位锚点 |
文档结构：
file_id（文档）
└── Page（页面）
├── Heading（标题，level 1-6）
├── Paragraph / Text（段落/文本）
├── BulletedList / NumberedList（列表）
├── Todo（待办事项）
├── Table（表格）
├── Callout（高亮块）
├── ColumnList（分栏布局）
├── Image（图片）
└── ...（更多组件详见 mdx_references.md）
⚠️ 重要约束：
- 所有内容块（Block）必须挂载在
Page下Page可以不指定父节点（挂载到根节点）- 完整的组件列表和规范详见
mdx_references.md
创建智能文档 — create_smartcanvas_by_mdx
【创建文档的首选工具】 创建排版丰富的在线智能文档。
【格式说明】 统一使用 mdx 格式（content_format="mdx"，默认值，无需显式传入）。
- MDX 向下兼容全部 Markdown 语法：标题、列表、表格、代码块、引用、图片、链接等标准 md 语法可直接写入
mdx字段，无需转换 - MDX 同时支持高级组件：分栏布局
ColumnList、高亮块Callout、待办列表Todo、表格Table、带样式文本Mark等丰富排版组件，适用于需要复杂排版和视觉效果的场景 - 生成包含 MDX 高级组件的内容时，须严格遵循
mdx_references.md规范，并对照规范逐条自校验；纯 Markdown 语法无此约束
【图片约束】 所有图片禁止直接使用 http/https 外链，必须先调用 upload_image 工具上传获取 image_id，再填入对应位置：
- MDX 组件：封面图
cover: image_id值，正文图片<Image src='image_id值' alt='描述' /> - 标准 Markdown 图片：
 - 如果图片过大导致上传失败，必须先本地压缩图片再重新上传，严禁回退使用 URL。
📖 MDX 规范详见： mdx_references.md
工作流
【统一使用 mdx 格式（content_format 默认 "mdx"，兼容全部 Markdown 语法）】
步骤 1：【模板匹配 - 必须优先执行】 根据用户需求，在下方【模板列表】中查找最匹配的模板：
匹配优先级：精确匹配 > 场景匹配 > 分类匹配 > 通用生成
- 精确匹配：用户需求与模板标题高度一致 → 直接读取对应引用文件
- 场景匹配：用户需求与模板场景相符但细节不同 → 读取最接近的模板文件作为结构参考
- 分类匹配：用户需求属于某分类但无精确模板 → 读取同类模板文件参考结构
- 通用生成：无匹配模板 → 跳过，直接进入步骤 2 自由生成
【找到匹配模板】→ 读取 smartcanvas/template/<引用文件名>
- 以模板的 frontmatter 配置（icon、layout 等）为参考
- 以模板的章节结构和 MDX 组件类型为骨架
- ⚠️ 将模板中所有示例数据替换为用户实际信息，禁止照搬示例内容
【模板列表】
| # | 模板标题 | 示例 Prompt | 引用文件 |
|---|---|---|---|
| 1 | 阶段性工作总结 | 帮我生成一份Q1季度阶段性工作总结，岗位为市场运营，总结内容包括本季度核心目标达成情况、关键项目进展与成果、数据指标对比分析、团队协作亮点、存在的不足与改进方向、下一阶段工作规划，要有具体的数据支撑和案例说明。 | q1_quarterly_marketing_operations_summary.mdx |
| 2 | 晋升述职报告 | 帮我生成一份从P6晋升P7的述职报告，岗位为后端开发工程师，内容包括个人基本信息与晋升时间线、核心项目经历及个人贡献、技术能力成长与突破、业务价值创造与量化成果、团队影响力与mentor经验、未来发展规划与目标，突出技术深度和业务影响力。 | p6_to_p7_promotion_report.mdx |
| 3 | 实习生实习报告 | 帮我生成一份大三暑期实习报告，实习岗位为数据分析实习生，实习单位为一家互联网科技公司，内容包括实习单位简介、实习岗位职责、主要参与的项目与工作内容、学到的技能与工具、遇到的挑战与解决过程、个人成长与收获、对未来职业发展的思考。 | summer_internship_report_data_analyst.mdx |
| 4 | 试用期转正总结 | 帮我生成一份为期三个月的试用期转正工作总结，岗位为UI设计师，内容包括试用期工作概述、主要参与项目及设计成果、工作技能提升情况、团队协作与沟通表现、对公司文化的理解与融入、自我评价与不足反思、转正后的工作目标与计划。 | ui_designer_probation_summary.mdx |
| 5 | 项目复盘报告 | 帮我生成一份App 2.0版本改版项目的复盘报告，内容包括项目背景与目标、项目时间线与里程碑、核心成果与数据表现、项目过程中的亮点与创新、遇到的问题与踩坑记录、根因分析与改进措施、经验教训总结、后续迭代建议。 | app_2_project_retrospective.mdx |
| 6 | 品牌宣传方案 | 帮我生成一份新消费茶饮品牌的年度品牌宣传方案，品牌定位为年轻时尚健康，目标受众为18-30岁都市年轻人，内容包括品牌现状分析、年度宣传目标、核心传播策略、线上线下整合营销计划、KOL及社交媒体投放策略、重点campaign创意概念、预算分配建议、效果评估指标，全面地展示所有信息，整体篇幅约4000字。 | new_tea_brand_annual_promotion_plan.mdx |
| 7 | 产品需求文档 | 帮我生成一份电商平台会员积分系统的产品需求文档（PRD），内容包括需求背景与目标、用户场景分析、功能范围与优先级、核心功能详细描述（积分获取规则、积分消耗方式、会员等级体系、积分商城）、业务流程图说明、数据埋点需求、非功能性需求、版本迭代规划。 | ecommerce_membership_points_prd.mdx |
| 8 | 市场营销推广方案 | 帮我生成一份在线教育平台暑期大促的市场营销推广方案，活动周期为一个月，内容包括市场环境分析、目标用户画像、活动主题与核心卖点、推广渠道策略（信息流广告、社交媒体、KOL合作、社群运营）、促销机制设计、内容营销计划、预算分配与ROI预估、执行时间表、风险预案，论据充分，篇幅不少于4000字。 | online_education_summer_marketing_plan.mdx |
| 9 | 活动策划方案 | 帮我生成一份公司五周年庆典活动策划方案，参与人数约200人，包含线下晚宴和团建环节，内容包括活动主题与定位、时间地点安排、活动流程与环节设计（签到、开场表演、领导致辞、颁奖典礼、互动游戏、抽奖、晚宴）、场地布置方案、物料清单、人员分工、预算明细、应急预案。 | company_5th_anniversary_event_plan.mdx |
| 10 | 运营规划方案 | 帮我生成一份社区团购小程序的年度运营规划方案，内容包括业务现状与数据分析、年度运营目标与KPI拆解、用户增长策略、用户留存与活跃策略、供应链运营优化、团长管理体系、内容运营计划、数据驱动运营体系搭建、季度里程碑与资源需求、风险评估与应对策略。 | community_group_buying_annual_operation_plan.mdx |
| 11 | 商业计划书 | 帮我生成一份智能家居IoT创业项目的商业计划书，内容包括执行摘要、公司简介与愿景、市场分析与行业趋势、目标市场与用户画像、产品与服务介绍、核心竞争优势与壁垒、商业模式与盈利方式、营销与推广策略、团队介绍、财务预测与融资需求、风险分析与应对措施、发展规划与里程碑，整体篇幅在4000字左右。 | smart_home_iot_business_plan.mdx |
| 12 | 个人自媒体运营方案 | 帮我生成一份个人美食探店类自媒体账号的运营方案，目标平台为小红书和抖音，内容包括账号定位与人设打造、目标受众分析、内容规划与选题方向、拍摄与制作标准、发布频率与最佳发布时间、涨粉策略、互动运营技巧、变现路径规划、月度内容排期表、竞品账号分析与差异化策略。 | food_review_self_media_operation_plan.mdx |
| 13 | 副业计划 | 帮我生成一份针对上班族的知识付费副业计划，方向为职场技能培训，内容包括副业定位与目标、个人优势与资源盘点、目标受众与需求分析、产品体系设计（课程、社群、咨询）、平台选择与入驻策略、内容生产计划、推广引流方案、时间管理与精力分配、收入目标与成本预算、阶段性里程碑，整体篇幅约5000字。 | office_worker_knowledge_side_business_plan.mdx |
| 14 | 竞品分析报告 | 帮我生成一份短视频平台的竞品分析报告，分析对象为抖音、快手、视频号三个平台，内容包括分析目的与方法论、行业背景与市场规模、竞品基本信息对比、产品定位与核心功能对比、用户画像与用户规模、商业模式与变现能力分析、运营策略差异、技术能力对比、SWOT分析、对自身产品的策略建议，整体篇幅约5000字。 | short_video_platform_competitive_analysis_2026.mdx |
| 15 | 行业趋势分析报告 | 帮我生成一份2025年人工智能行业趋势分析报告，内容包括全球AI市场规模与增长趋势、核心技术发展方向（大模型、多模态、AI Agent）、重点应用场景与商业化进展、主要玩家竞争格局、投融资热点与资本动向、政策法规与监管趋势、行业面临的挑战与风险、未来3-5年趋势预测与机会点，信息要足够详细和全面，篇幅在4000-5000字。 | 2025_ai_industry_trend_analysis_report.mdx |
| 16 | 用户调研报告 | 帮我生成一份在线办公协作工具的用户调研报告，调研方式包括问卷调查和深度访谈，内容包括调研背景与目标、调研方法与样本说明、用户基本画像分析、使用习惯与行为分析、核心需求与痛点挖掘、满意度与NPS分析、竞品使用情况对比、用户典型场景与案例、关键发现与洞察总结、产品优化建议，整体篇幅约4000字。 | online_office_tool_user_research_report.mdx |
| 17 | 市场可行性分析 | 帮我生成一份社区生鲜即时配送项目的市场可行性分析报告，内容包括项目概述与目标、市场环境分析（宏观环境PEST分析、行业现状）、目标市场规模测算、竞争格局与进入壁垒、目标用户需求验证、商业模式与盈利能力分析、运营模式与成本结构、风险评估与应对策略、投资回报预测、可行性结论与建议，信息应全面，论据充分，整体篇幅约5000字。 | community_fresh_delivery_feasibility_report.mdx |
| 18 | 产品体验评测报告 | 帮我生成一份智能手表产品体验评测报告，评测对象为Apple Watch和华为Watch GT系列，内容包括评测背景与方法、外观设计与做工对比、屏幕显示效果、健康监测功能体验（心率、血氧、睡眠）、运动追踪精准度、智能功能与生态体验、续航能力实测、佩戴舒适度、性价比分析、综合评分与推荐建议，内容详细信息全面，整体篇幅约4000字。 | smartwatch_comparison_apple_watch_vs_huawei_gt.mdx |
| 19 | 目标人群画像分析 | 帮我生成一份母婴电商平台目标人群画像分析报告，内容包括分析目的与数据来源、人群基本属性（年龄、地域、收入、学历）、消费行为特征（消费频次、客单价、品类偏好）、媒介触达习惯、决策因素与购买动机、典型用户分群与画像描述、用户生命周期阶段分析、营销触达策略建议，篇幅在4000-5000字。 | maternity_ecommerce_user_persona_report.mdx |
| 20 | 选址/选品分析报告 | 帮我生成一份咖啡店选址分析报告，备选地址为三个商圈（CBD写字楼区、大学城周边、社区商业街），内容包括选址标准与评估维度、各备选地址周边环境分析、人流量与客群分析、竞争对手分布情况、租金成本与性价比、交通便利性与可达性、商圈发展潜力评估、综合评分与排名、选址建议与风险提示，篇幅在3000字左右。 | coffee_shop_location_analysis_report.mdx |
| 21 | 商业模式分析报告 | 帮我生成一份共享充电宝行业的商业模式分析报告，内容包括行业概述与发展历程、主要玩家与市场份额、商业模式画布分析（价值主张、客户细分、渠道通路、收入来源、成本结构、关键资源、核心活动、重要伙伴）、盈利模式与单位经济模型、核心竞争要素分析、行业挑战与发展瓶颈、未来演变趋势与创新方向，信息要足够详细和全面，篇幅在4000-5000字。 | shared_powerbank_business_model_report.mdx |
| 22 | 求职自荐信 | 帮我生成一份应聘互联网公司产品经理岗位的求职自荐信，应聘者为有3年经验的产品经理，内容包括自我介绍与求职意向、与岗位匹配的核心能力、代表性项目经历与成果、对目标公司和岗位的理解、个人职业热情与发展期望、结尾致谢与联系方式，语言真诚有感染力且突出个人亮点。 | internet_product_manager_cover_letter.mdx |
| 23 | 推荐信 | 帮我生成一份由大学教授为学生撰写的研究生入学推荐信，被推荐人为计算机科学专业大四学生，内容包括推荐人自我介绍与推荐关系说明、对被推荐人学术能力的评价、研究项目参与情况与表现、个人品质与团队合作能力、与其他学生的横向比较、对其研究生阶段发展的期望、推荐结论，语言正式客观且有说服力。 | graduate_admission_recommendation_letter.mdx |
| 24 | 个人职业规划书 | 帮我生成一份应届毕业生的五年职业规划书，专业背景为金融学，目标行业为互联网金融，内容包括自我分析（兴趣、能力、价值观）、行业与职业分析、SWOT个人分析、职业目标设定（短期1年、中期3年、长期5年）、实现路径与行动计划、所需资源与技能提升计划、可能遇到的障碍与应对策略、评估调整机制，篇幅约3000字。 | finance_graduate_career_plan.mdx |
| 25 | 面试常见问题准备清单 | 帮我生成一份互联网公司产品经理岗位的面试常见问题准备清单，涵盖自我介绍、行为面试题（STAR法则）、专业能力题（产品设计、数据分析、用户研究）、案例分析题、压力面试题、反问环节建议，每个模块下准备多个问题并附带回答思路和框架，帮助面试者系统化准备。 | internet_product_manager_interview_checklist.mdx |
| 26 | 英文自我介绍 | 帮我生成一份适用于外企面试的英文自我介绍模板，时长约2-3分钟，内容包括基本信息与教育背景、工作经验概述、核心技能与专业优势、代表性成就、对目标岗位的热情与匹配度、简短的个人特质展示，提供不同场景版本（正式面试版、社交场合版），语言地道流畅有感染力。 | english_self_introduction_for_interview.mdx |
| 27 | 旅行攻略 | 帮我生成一份三天两晚的泉州旅行攻略，从深圳出发，注重自然景观和人文艺术和当地美食，经典容易出片，推荐旅行地点的交通方式以及住宿区域，行程可以安排得相对紧凑，同时罗列一些注意事项。 | quanzhou_3_day_travel_guide.mdx |
| 28 | 婚礼策划清单 | 帮我生成一份中式现代风格婚礼的策划清单，预算约15万元，婚礼规模约150人，在酒店举办，内容包括婚礼时间线与筹备进度表（婚前6个月到婚礼当天）、场地布置方案、婚庆团队选择要点、婚纱礼服与造型准备、婚礼流程安排（迎亲、仪式、宴席）、宾客管理与座位安排、婚品采购清单、预算分配明细、注意事项与避坑指南。 | chinese_modern_wedding_planning_guide.mdx |
| 29 | 生日派对策划清单 | 帮我生成一份小朋友6岁生日派对的策划清单，主题为太空探险，参与人数约20个小朋友和家长，在家中举办，内容包括派对主题设计与装饰方案、邀请函设计、场地布置清单（气球、横幅、桌布等）、派对流程与互动游戏设计、生日蛋糕与美食菜单、伴手礼准备、拍照打卡区设置、安全注意事项、预算清单、物品采购链接建议。 | space_theme_6th_birthday_party_plan.mdx |
| 30 | 家庭年度预算规划 | 帮我生成一份三口之家的年度家庭预算规划，家庭月收入约3万元，坐标二线城市有房贷，内容包括家庭财务现状盘点、年度收入预估、固定支出梳理（房贷、保险、教育）、弹性支出预算（餐饮、交通、娱乐、购物）、储蓄与投资目标、各月预算分配表、应急资金规划、大额支出计划（旅行、家电更换）、节流建议与开源思路、预算执行跟踪方法。 | 2026_family_annual_budget_plan.mdx |
| 31 | 搬家物品整理清单 | 帮我生成一份从合租房搬到新家的搬家物品整理清单，内容包括搬家前准备工作时间线、物品分类整理方案（客厅、卧室、厨房、卫生间、书房）、需要打包的物品清单、需要丢弃或捐赠的物品筛选标准、搬家公司选择与比价要点、搬家当天流程安排、新家入住前需采购物品清单、水电气网络过户提醒、搬家后整理收纳建议。 | shared_apartment_moving_checklist.mdx |
| 32 | 健身训练计划 | 帮我生成一份为期12周的增肌健身训练计划，适合有半年健身基础的男性，每周训练5天，内容包括训练目标与身体数据记录、每周训练部位分配、每日训练动作详细安排（动作名称、组数、次数、休息时间）、热身与拉伸建议、饮食配合建议（蛋白质摄入、碳水循环）、补剂建议、每周进度检查指标、常见错误与纠正提示。 | 12_week_muscle_building_workout_plan.mdx |
| 33 | 读书笔记 | 帮我生成一份《原则》(Ray Dalio)的读书笔记，内容包括书籍基本信息与推荐理由、作者简介、全书核心主旨与结构概览、各章节要点提炼、核心原则归纳（生活原则、工作原则、管理原则）、精彩语句摘录、个人感悟与思考、与自身工作生活的关联与应用、推荐阅读的相关书籍，整体篇幅约3000字。 | principles_ray_dalio_book_notes.mdx |
| 34 | 电影/书籍推荐清单 | 帮我生成一份适合职场人士的成长类书籍和电影推荐清单，包含10本书和10部电影，内容包括推荐主题分类（思维提升、沟通表达、领导力、时间管理、心理健康）、每个推荐作品的基本信息、一句话推荐语、核心看点与收获、适合阅读/观看的场景、难度和时间投入参考、按优先级排序的阅读/观看顺序建议。 | career_growth_books_and_movies_recommendations.mdx |
| 35 | 个人年度目标规划 | 帮我生成一份2026年个人年度目标规划，涵盖职业发展、财务管理、健康运动、学习成长、人际关系、生活品质六大维度，内容包括上一年度回顾与反思、各维度年度目标设定、目标拆解为季度和月度里程碑、关键行动计划与习惯养成、所需资源与支持、潜在障碍与应对策略、奖励机制设计、月度复盘检查模板。 | 2026_personal_annual_goal_plan.mdx |
| 36 | 宠物养护指南 | 帮我生成一份新手养猫全面养护指南，适合第一次养英短蓝猫的铲屎官，内容包括接猫前的准备工作与必备用品清单、猫咪到家后的适应期指南、日常喂养方案（猫粮选择、喂食量、饮水）、疫苗驱虫计划、日常护理（梳毛、剪指甲、清洁耳朵）、常见疾病预防与识别、绝育建议与注意事项、行为习惯解读与训练建议、每月养猫费用预估，尽量详细，篇幅在4000字左右。 | british_shorthair_cat_care_guide.mdx |
| 37 | 家庭食谱/每周菜单 | 帮我生成一份家庭一周健康菜单规划，三口之家包含一个6岁儿童，注重营养均衡和荤素搭配，内容包括一周七天的三餐加下午茶安排、每餐的菜品搭配与营养分析、重点菜品的简易做法、每周食材采购清单与预估费用、食材保鲜与储存建议、儿童营养补充要点、周末亲子烹饪活动建议、节约时间的备餐技巧。 | family_weekly_healthy_meal_plan.mdx |
| 38 | 节日祝福文案集 | 帮我生成一份全年节日祝福文案集，涵盖春节、元宵节、情人节、妇女节、清明节、劳动节、母亲节、父亲节、端午节、七夕、中秋节、国庆节、重阳节、圣诞节等主要节日，每个节日提供3-5条不同风格的祝福文案（正式商务版、亲友温馨版、朋友圈文艺版、幽默趣味版），同时提供节日相关知识小科普。 | annual_holiday_greeting_messages.mdx |
步骤 2：【阅读 MDX 规范】 阅读 mdx_references.md，了解 MDX 组件规范（组件列表、属性、取值白名单、格式约束）
步骤 3：【生成 MDX 内容】 按规范生成包含 Frontmatter 和 MDX 组件的内容：
- 有模板参考时：以模板结构为骨架，填入用户实际内容
- 无模板参考时：根据文档类型自由设计结构
步骤 4：【图片处理 - 必须执行】
封面图（frontmatter cover）：
- 默认必须设置：根据文档主题自行通过网络搜索合适图片并下载 → 调用
upload_image上传 → image_id 填入cover: image_id值 - 仅当搜索或下载/上传失败时，才去掉 cover 字段
正文图片（<Image> 元素）：
- 若 MDX 中包含
<Image>：必须先调用upload_image上传获取 image_id，填入src属性（约束详见工具说明开头）
步骤 5：【自校验】
对照 mdx_references 逐条自校验，确保格式合规（重点检查 cover 和 <Image src> 均为 image_id 而非 URL）
步骤 6：【调用工具创建文档】 调用 create_smartcanvas_by_mdx 创建文档（传入 title + MDX 内容） 从返回结果中获取 file_id 和 url
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `title` | string | ✅ | 文档标题。参数名必须为 `title`，不要使用 `doc_title`、`name`、`file_name` 等其他名称 |
| `mdx` | string | ✅ | 文档正文内容。MDX 向下兼容全部 Markdown 语法，标准 md 内容可直接填入；使用 MDX 高级组件（`Callout` / `ColumnList` / `Todo` / `Table` 等）时须严格遵循 `mdx_references` 规范并逐条自校验。图片约束见工具说明开头 |
| `content_format` | string | | 内容格式。默认 `"mdx"`，建议始终使用默认值——MDX 已向下兼容全部 Markdown 语法，无需切换 |
### 调用示例
```json
{
"title": "项目需求文档",
"mdx": "---\ntitle: 项目需求文档\nicon: 📋\n---\n\n# 项目需求\n\n<Callout icon=\"📌\" blockColor=\"light_blue\" borderColor=\"blue\">\n 本项目旨在开发一套智能文档管理系统。\n</Callout>\n\n## 功能需求\n\n<BulletedList>\n 文档创建功能\n</BulletedList>\n<BulletedList>\n 文档编辑功能\n</BulletedList>\n<BulletedList>\n 协作功能\n</BulletedList>"
}
返回值说明
{
"file_id": "doc_1234567890",
"url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
"error": "",
"trace_id": "trace_1234567890"
}
统一编辑工具（推荐）
💡 推荐使用统一编辑工具：
smartcanvas.get_top_level_pages+smartcanvas.read+smartcanvas.find+smartcanvas.edit组合，支持 MDX 格式内容、更简洁的 API 设计。
smartcanvas.get_top_level_pages
功能：查询文档的顶层页面列表，返回文档中所有顶级页面的基本信息，用于快速浏览文档结构。
使用场景：
- 获取文档的所有页面列表及其 page_id
- 在读取或编辑文档前先了解文档的页面结构
- 当文档包含多个页面时，确定要操作的目标页面
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_id |
string | ✅ | 智能文档的唯一标识符 |
返回字段：
| 字段 | 类型 | 说明 |
|---|---|---|
pages |
array | 顶层页面列表 |
pages[].page_id |
string | 页面 ID |
pages[].title |
string | 页面标题 |
error |
string | 错误信息 |
trace_id |
string | 调用链追踪 ID |
调用示例：
{
"file_id": "your_file_id"
}
smartcanvas.read
功能：读取智能文档指定页面的完整 MDX 格式内容。一次调用即返回页面全部内容。
使用场景：
- 在编辑文档前先阅读全文，了解文档结构和内容
- 获取页面完整内容用于分析、总结或摘要
smartcanvas.find找不到目标内容时，降级用本工具获取全文查找
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_id |
string | ✅ | 智能文档的唯一标识符 |
page_id |
string | 要读取的页面 ID，为空时自动获取文档的第一个页面 | |
next_token |
string | 分页游标，首次请求为空，后续请求传入上次返回的 next_token 以获取下一页内容 | |
size |
integer | 每页返回的子节点数量，最大为 20，为 0 或不传时默认为 20 |
返回字段：
| 字段 | 类型 | 说明 |
|---|---|---|
content |
string | 页面内容的 MDX 格式文本 |
error |
string | 错误信息 |
trace_id |
string | 调用链追踪 ID |
next_token |
string | 下一页游标，非空表示还有更多内容，客户端可传入此值继续拉取 |
调用示例（读取文档第一个页面）：
{
"file_id": "your_file_id"
}
调用示例（读取指定页面）：
{
"file_id": "your_file_id",
"page_id": "page_abc123"
}
返回示例：
{
"content": "## 项目背景\n\n本项目旨在提升用户体验...\n\n## 总结\n\n以上是文档的全部内容。"
}
smartcanvas.find
功能：根据文本搜索智能文档中的 Block，返回匹配 Block 的 ID 和 MDX 格式内容。搜索结果中的 Block ID 可作为锚点，用于 smartcanvas.edit 的精准编辑操作。
使用场景：
- 定位文档中某段内容的位置，获取 Block ID 作为编辑锚点
- 搜索包含特定关键词的内容块
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_id |
string | ✅ | 智能文档的唯一标识符 |
query |
string | ✅ | 搜索文本，系统将在文档所有页面中搜索包含该文本的 Block |
返回字段：
| 字段 | 类型 | 说明 |
|---|---|---|
blocks |
array | 匹配的 Block 列表 |
blocks[].id |
string | Block 的唯一标识符（锚点 ID） |
blocks[].content |
string | Block 的 MDX 格式内容 |
error |
string | 错误信息 |
trace_id |
string | 调用链追踪 ID |
调用示例：
{
"file_id": "your_file_id",
"query": "项目背景"
}
返回示例：
{
"blocks": [
{
"id": "block_abc123",
"content": "## 项目背景\n\n本项目旨在提升用户体验..."
}
]
}
smartcanvas.edit
功能：编辑智能文档，支持 4 种操作类型：在指定位置前/后插入、删除、修改。
操作类型说明：
| Action | 说明 | id 参数 | content 参数 |
|---|---|---|---|
INSERT_BEFORE |
在指定 Block 前插入内容 | 锚点 Block ID（必填） | MDX 格式内容（必填） |
INSERT_AFTER |
在指定 Block 后插入内容 | 锚点 Block ID（为空则追加到文档末尾） | MDX 格式内容（必填） |
DELETE |
删除指定 Block | 要删除的 Block ID（必填，⚠️ 必须先通过 find/read 获取） | 不需要 |
UPDATE |
修改指定 Block 的内容 | 要修改的 Block ID（必填，⚠️ 必须先通过 find/read 获取） | 新的 MDX 格式内容（必填） |
⚠️ 强制约束：
UPDATE和DELETE操作的id参数必须来源于smartcanvas.find或smartcanvas.read的返回结果，禁止在未获取文档数据的情况下直接传入 id 执行 UPDATE 或 DELETE 操作。
⚠️ readonly 约束：当
smartcanvas.find或smartcanvas.read返回的 MDX 内容中，某个块级组件（如<Table>）带有readonly属性时，表示该组件及其所有子元素为只读状态。禁止使用只读组件或其内部子元素的id作为smartcanvas.edit的锚点（INSERT_BEFORE / INSERT_AFTER / UPDATE / DELETE 均不可用）。如需在只读组件附近操作，应选择只读组件上方或下方的非只读 Block 作为锚点。
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_id |
string | ✅ | 智能文档的唯一标识符 |
action |
enum | ✅ | 操作类型：INSERT_BEFORE / INSERT_AFTER / DELETE / UPDATE |
id |
string | 条件 | 锚点 Block ID，见上表说明 |
content |
string | 条件 | MDX 格式内容，见上表说明 |
返回字段：
| 字段 | 类型 | 说明 |
|---|---|---|
error |
string | 错误信息 |
trace_id |
string | 调用链追踪 ID |
调用示例（在指定 Block 后插入内容）：
{
"file_id": "your_file_id",
"action": "INSERT_AFTER",
"id": "block_abc123",
"content": "## 新章节\n\n这是插入的新内容。"
}
调用示例（追加到文档末尾）：
{
"file_id": "your_file_id",
"action": "INSERT_AFTER",
"content": "追加到文档末尾的内容"
}
调用示例（删除指定 Block）：
{
"file_id": "your_file_id",
"action": "DELETE",
"id": "block_abc123"
}
调用示例（修改指定 Block）：
{
"file_id": "your_file_id",
"action": "UPDATE",
"id": "block_abc123",
"content": "## 修改后的标题\n\n这是更新后的内容。"
}
边界场景处理规范
1. ColumnList 分栏删除边界场景
- 删除后只剩 1 个 Column：不允许
ColumnList中只有一个Column，必须将整个ColumnList（包含剩余Column内的所有内容）用UPDATE操作替换为普通块内容（将Column内的子块直接平铺输出，去掉ColumnList/Column容器）。 - 删除后剩余 2 个或更多 Column：需要用
UPDATE操作更新整个ColumnList，重新均分或合理分配各Column的width（例如两列各50%，三列各33%）。 - 操作方式：上述两种情况均不能只
DELETE单个Column，必须对ColumnList整体执行UPDATE，传入调整后的完整 MDX 内容。
// 删除一列后只剩一列 → 将 ColumnList 整体替换为普通块内容
{
"file_id": "your_file_id",
"action": "UPDATE",
"id": "columnlist_id",
"content": "剩余 Column 内子块平铺后的 MDX 内容"
}
// 删除一列后仍剩多列 → 更新整个 ColumnList 并重新分配 width
{
"file_id": "your_file_id",
"action": "UPDATE",
"id": "columnlist_id",
"content": "<ColumnList>\n <Column width=\"50%\">\n 左列内容\n </Column>\n <Column width=\"50%\">\n 右列内容\n </Column>\n</ColumnList>"
}
2. Callout 内容清空边界场景
- 当用户要删除
Callout内的全部内容时，Callout本身也应一并删除，不允许保留空的Callout容器。 - 操作方式：对
Callout的id执行DELETE操作，而非仅删除其内部子块。
{
"file_id": "your_file_id",
"action": "DELETE",
"id": "callout_id"
}
3. BlockQuote 内容清空边界场景
- 当
BlockQuote内的全部内容被删除时，BlockQuote本身也应一并删除，不允许保留空的BlockQuote容器。 - 操作方式：对
BlockQuote的id执行DELETE操作，而非仅删除其内部子块。
{
"file_id": "your_file_id",
"action": "DELETE",
"id": "blockquote_id"
}
4. 列表（BulletedList / NumberedList / Todo）删除含子项的列表项边界场景
- 当删除某个列表项时，若该列表项下存在子列表项（嵌套的
BulletedList/NumberedList/Todo），子项不能悬空独立存在。 - 操作方式：对该列表项的
id执行DELETE操作，系统会连同其所有子项一并删除；若需保留子项内容，应先用UPDATE将子项内容提升到父级或平铺为独立块，再执行DELETE。
// 直接删除父项（子项一并删除）
{
"file_id": "your_file_id",
"action": "DELETE",
"id": "parent_list_item_id"
}
5. TableRow / TableCell 使用边界场景
TableRow禁止单独存在，只能作为Table的直接子元素；TableCell禁止单独存在，只能作为TableRow的直接子元素。- 禁止使用
TableRow或TableCell的id作为INSERT_BEFORE/INSERT_AFTER的锚点，向表格内部插入非表格结构的内容。 - 禁止单独对
TableRow或TableCell执行DELETE操作（删除单行/单格），如需修改表格结构，应对整个Table执行UPDATE，传入调整后的完整表格 MDX 内容。 - 禁止单独对
TableCell执行UPDATE操作修改单元格内容，同样应对整个Table执行UPDATE，传入完整表格 MDX 内容。 - 注意：
Table通常带有readonly属性，此时TableRow/TableCell的id同样不可用，任何操作均需绕开只读表格，选择其上方或下方的非只读 Block 作为锚点。
// 修改表格内容（如删除某行、修改某单元格）→ 对整个 Table 执行 UPDATE
{
"file_id": "your_file_id",
"action": "UPDATE",
"id": "table_id",
"content": "<Table>\n <TableRow>\n <TableCell>\n 列1内容\n </TableCell>\n <TableCell>\n 列2内容\n </TableCell>\n </TableRow>\n</Table>"
}
图片编辑说明
编辑场景与创建场景图片约束一致（详见工具说明开头）：必须先调用 upload_image 上传获取 image_id，再设置到 src 属性中，严禁使用外部 URL。
调用示例（使用 upload_image 上传后插入图片）：
// 步骤 1：先调用 upload_image 获取 image_id
// 步骤 2：将 image_id 设置到 content 的 Image src 属性中
{
"file_id": "your_file_id",
"action": "INSERT_AFTER",
"id": "block_abc123",
"content": "<Image src=\"upload_image返回的image_id\" alt=\"示例图片\" />"
}
典型工作流示例
⚠️ 定位策略：有关键词 → 优先
find，找不到降级read；无关键词 → 直接read。UPDATE / DELETE 前必须先通过find或read获取真实 Block ID，禁止跳过。
工作流一：用户指定了编辑位置（有查询意图）
步骤 1：使用 find 搜索目标 Block
→ smartcanvas.find(file_id, query="用户指定的关键词")
→ 检查搜索结果
步骤 2A：find 找到匹配 Block
→ 将 find 返回的 Block 列表展示给用户确认
→ 用户确认锚点位置后，调用 smartcanvas.edit 传入确认的锚点 ID 执行操作
步骤 2B：find 未找到匹配 Block（降级）
→ 调用 smartcanvas.read(file_id) 读取文档全部内容
→ 在返回的 content 中查找目标内容
→ 根据找到的内容分析并猜测合适的锚点位置
→ 调用 smartcanvas.edit 执行编辑操作
工作流二：用户未指定编辑位置（无查询意图）
步骤 1：读取文档全部内容（⚠️ UPDATE/DELETE 操作此步骤为必须）
→ smartcanvas.read(file_id)
→ 返回的 content 即为页面完整 MDX 内容，了解文档结构
步骤 2：根据文档内容和用户意图猜测锚点位置，执行编辑操作
→ 插入到文档最前面：smartcanvas.edit(action=INSERT_BEFORE, id=首个Block ID, content=MDX内容)
→ 插入到文档最后面：smartcanvas.edit(action=INSERT_AFTER, id为空, content=MDX内容)
→ 插入到特定位置：smartcanvas.edit(action=INSERT_BEFORE/INSERT_AFTER, id=猜测的锚点ID, content=MDX内容)
→ 修改特定内容：smartcanvas.edit(action=UPDATE, id=目标Block ID, content=新MDX内容)【id 必须来自 find/read 结果】
→ 删除特定内容：smartcanvas.edit(action=DELETE, id=目标Block ID)【id 必须来自 find/read 结果】
工作流三：在「XXX」后插入内容
步骤 1：搜索定位目标 Block
→ smartcanvas.find(file_id, query="XXX")
步骤 2A：找到匹配 Block
→ 展示 find 结果给用户确认锚点位置
→ 用户确认后，调用 smartcanvas.edit(action=INSERT_AFTER, id=确认的锚点ID, content=MDX内容)
步骤 2B：未找到匹配 Block（降级）
→ smartcanvas.read(file_id) 获取全文
→ 根据全文内容猜测"XXX"附近的锚点位置
→ smartcanvas.edit(action=INSERT_AFTER, id=猜测的锚点ID, content=MDX内容)
工作流四：修改「XXX」为新内容
步骤 1：搜索定位目标 Block
→ smartcanvas.find(file_id, query="XXX")
步骤 2A：找到匹配 Block
→ 展示 find 结果给用户确认目标 Block
→ 用户确认后，调用 smartcanvas.edit(action=UPDATE, id=确认的Block ID, content=新MDX内容)
步骤 2B：未找到匹配 Block（降级）
→ smartcanvas.read(file_id) 获取全文
→ 根据全文内容定位目标位置
→ smartcanvas.edit(action=UPDATE, id=目标Block ID, content=新MDX内容)
工作流五：删除「XXX」
步骤 1：搜索定位目标 Block
→ smartcanvas.find(file_id, query="XXX")
步骤 2A：找到匹配 Block
→ 展示 find 结果给用户确认要删除的 Block
→ 用户确认后，调用 smartcanvas.edit(action=DELETE, id=确认的Block ID)
步骤 2B：未找到匹配 Block（降级）
→ smartcanvas.read(file_id) 获取全文
→ 根据全文内容定位目标位置
→ smartcanvas.edit(action=DELETE, id=目标Block ID)
工作流六：直接追加内容到文档末尾
步骤 1：直接追加到文档末尾（无需定位）
→ smartcanvas.edit(file_id, action=INSERT_AFTER, id为空, content=MDX内容)
工作流七：创建分栏布局
适用场景：用户希望在文档中新增一个左右分栏区域（如「左边放说明，右边放示例」）。
步骤 1：确定插入位置
→ 若用户指定了位置关键词：smartcanvas.find(file_id, query="关键词") 获取锚点 Block ID
→ 若用户未指定位置：smartcanvas.read(file_id) 获取全文，根据文档结构选择合适锚点
步骤 2：构造 ColumnList MDX 内容
→ 两列等宽示例（各 50%）：
<ColumnList>
<Column width="50%">
左列内容（可包含 Heading、Paragraph、BulletedList 等任意块）
</Column>
<Column width="50%">
右列内容
</Column>
</ColumnList>
→ 三列等宽示例（各 33%）：
<ColumnList>
<Column width="33%">
第一列内容
</Column>
<Column width="33%">
第二列内容
</Column>
<Column width="34%">
第三列内容
</Column>
</ColumnList>
⚠️ 注意：ColumnList 至少需要 2 个 Column，width 之和应为 100%
步骤 3：调用 smartcanvas.edit 插入分栏
→ smartcanvas.edit(file_id, action=INSERT_AFTER, id=锚点Block ID, content=ColumnList MDX内容)
→ 若插入到文档末尾：id 为空
调用示例：
// 在 block_abc123 后插入一个两列分栏
{
"file_id": "your_file_id",
"action": "INSERT_AFTER",
"id": "block_abc123",
"content": "<ColumnList>\n <Column width=\"50%\">\n ## 功能说明\n\n 这里描述功能的详细说明。\n </Column>\n <Column width=\"50%\">\n ## 代码示例\n\n 这里放对应的代码示例。\n </Column>\n</ColumnList>"
}
工作流八：向已有分栏中添加内容
适用场景：用户希望在某个已存在的分栏（ColumnList）的某一列中追加或修改内容。
步骤 1：读取文档内容，获取目标 ColumnList 的完整 MDX 结构
→ smartcanvas.find(file_id, query="分栏内已知的关键词")
或 smartcanvas.read(file_id) 获取全文
→ 找到目标 ColumnList 的 id 及其完整 MDX 内容
步骤 2：在原有 MDX 基础上修改目标列的内容
→ 保持 ColumnList / Column 结构不变
→ 仅在目标 Column 内追加或修改子块内容
⚠️ 注意：不能单独对 Column 内的子块执行 INSERT_BEFORE/INSERT_AFTER，
必须对整个 ColumnList 执行 UPDATE，传入完整的新 MDX 内容
步骤 3：调用 smartcanvas.edit 更新整个 ColumnList
→ smartcanvas.edit(file_id, action=UPDATE, id=ColumnList的Block ID, content=更新后的完整ColumnList MDX)
调用示例：
// 在右列末尾追加一条说明（对整个 ColumnList 执行 UPDATE）
{
"file_id": "your_file_id",
"action": "UPDATE",
"id": "columnlist_block_id",
"content": "<ColumnList>\n <Column width=\"50%\">\n ## 功能说明\n\n 这里描述功能的详细说明。\n </Column>\n <Column width=\"50%\">\n ## 代码示例\n\n 这里放对应的代码示例。\n\n > 注意：示例仅供参考，请根据实际情况调整。\n </Column>\n</ColumnList>"
}
工作流九：修改分栏列数或宽度比例
适用场景：用户希望将两列分栏改为三列，或调整各列宽度比例（如从 50/50 改为 30/70）。
步骤 1：读取文档内容，获取目标 ColumnList 的完整 MDX 结构
→ smartcanvas.find(file_id, query="分栏内已知的关键词")
或 smartcanvas.read(file_id) 获取全文
→ 找到目标 ColumnList 的 id 及其完整 MDX 内容
步骤 2：构造调整后的完整 ColumnList MDX
→ 增加列：在原有 Column 基础上新增 Column，重新分配 width（各列 width 之和为 100%）
→ 调整宽度：修改各 Column 的 width 属性值
→ 减少列（删除后剩余 ≥ 2 列）：移除目标 Column，重新均分剩余列的 width
→ 减少列（删除后只剩 1 列）：将 ColumnList 整体替换为普通块内容（参见边界场景处理规范第 1 条）
⚠️ 注意：width 之和必须为 100%，且 ColumnList 至少保留 2 个 Column
步骤 3：调用 smartcanvas.edit 更新整个 ColumnList
→ smartcanvas.edit(file_id, action=UPDATE, id=ColumnList的Block ID, content=调整后的完整ColumnList MDX)
调用示例（两列改三列）：
{
"file_id": "your_file_id",
"action": "UPDATE",
"id": "columnlist_block_id",
"content": "<ColumnList>\n <Column width=\"33%\">\n ## 第一列\n\n 第一列内容。\n </Column>\n <Column width=\"33%\">\n ## 第二列\n\n 第二列内容。\n </Column>\n <Column width=\"34%\">\n ## 第三列\n\n 新增的第三列内容。\n </Column>\n</ColumnList>"
}
调用示例（调整宽度比例为 30/70）：
{
"file_id": "your_file_id",
"action": "UPDATE",
"id": "columnlist_block_id",
"content": "<ColumnList>\n <Column width=\"30%\">\n ## 侧边说明\n\n 简短的辅助说明内容。\n </Column>\n <Column width=\"70%\">\n ## 主要内容\n\n 详细的主体内容区域。\n </Column>\n</ColumnList>"
}
📌 提示：
file_id可通过manage.search_file搜索获取，或从创建文档的返回结果中获取。所有内容块必须挂载在Page下，完整组件列表详见mdx_references.md。