阶跃AI桌面伙伴文档必须面向模型而非人类编写，采用动词开头+明确对象+绝对路径结构，强制标注预期输出，按调用链路组织内容并嵌入真实错误码与截图锚点。

阶跃AI桌面伙伴在研发办公场景中需频繁对接Excel、邮箱、飞书等16款工具，技术文档必须能准确传递MCP协议配置要点、权限开通路径与工具集成验证逻辑，否则会导致自动化流程中断、Agent状态错乱或安全策略失效。

明确文档服务对象：是写给模型看的运行环境

不要把文档当成给人读的说明书。模型没有长期记忆，也不会主动补全上下文。你写的每一段文字，都得让它能在当前token窗口里独立生效。

第一步：删掉所有“请开发者注意”“建议参考上文”这类依赖人类记忆的表述。

第二步：把每个操作指令改写成“动词开头+明确对象+绝对路径/参数值”的结构。例如不写“配置MCP端口”，而写“将MCP协议端口设为【3000】，该端口必须未被其他进程占用”。

第三步：对关键判断点强制标注预期输出。比如验证MCP连通性时，不只写“执行curl命令”，而要写“执行curl http://localhost:3000/mcp/check → 返回JSON中status字段必须为'success'，且msg字段严格等于'mcp connected'”。

前置准备阶段：权限开通必须一步到位

Windows系统下，阶跃AI若未获得管理员权限与宏执行许可，Excel集成将静默失败，且无报错提示。

方法一：启用Excel宏（仅Windows）
打开Excel → 文件 → 选项 → 信任中心 → 信任中心设置 → 宏设置 → 选择“启用所有宏（不推荐；计算机存在安全风险）”。

方法二：配置邮箱授权码
QQ邮箱需在网页版“设置 → 账户与安全 → 生成授权码”完成短信验证；企业邮箱必须由管理员后台开启第三方授权并生成独立授权码，【不能直接使用登录密码】。

方法三：获取飞书AppID与AppSecret
登录飞书开放平台 → 创建企业自建应用 → 凭证与基础信息页直接复制AppID与AppSecret，这两项将在阶跃AI高级设置中填入，填错一个字符都会导致OAuth2.0握手失败。

MCP协议配置与验证：三步闭环不可跳过

这一步是全部工具集成的基石。跳过验证或仅凭悬浮球提示就认为成功，90%会在后续调用Excel时出现COM对象创建失败。

① 开启协议：点击悬浮球 → 设置 → 高级设置 → MCP协议 → 勾选“启用MCP协议” → 保存配置 → 等待悬浮球显示“MCP已启用”。

② 端口校验：打开命令行，执行netstat -ano | findstr :3000，确认无PID占用；若有，用taskkill /f /pid XXXX释放端口后再重启阶跃AI。

③ 双通道验证：必须同时通过阶跃AI内指令“验证MCP协议连通性”和curl命令行双重确认。任一通道失败，说明WebSocket心跳未建立或TLS证书未正确加载。

工具集成文档写作：按调用链路写，不按工具列表写

不要写“Excel集成步骤”“飞书集成步骤”这种静态分类。要按实际自动化任务流组织内容，例如：“当用户说‘把销售日报发给张经理’时，系统需依次触发：Outlook发信 → Excel生成图表 → 飞书通知 → 高德查张经理当前定位”。

方法1：以典型任务为锚点写文档
标题直接用自然语言指令，如“发送带附件的日报邮件”，正文只描述该指令触发后的完整工具调用链，每个环节注明输入源、输出目标、失败回退动作。

方法2：嵌入真实错误码反推文档重点
在“Excel图表生成失败”小节中，不罗列所有可能原因，只写阶跃AI实际返回的error_code：当code=ERR_COM_INIT_FAIL时，必须检查Excel是否已关闭所有实例；当code=ERR_CHART_DATA_EMPTY时，需确认数据源区域是否含空行或非法字符。

方法3：用截图锚定界面元素
对飞书消息卡片上的“审批通过”按钮，文档必须附带真实截图，并在图上用箭头标注按钮位置，旁边文字说明：“点击此按钮后，阶跃AI将向后端审批流引擎POST /api/approve，携带当前message_id与user_id”。