diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 5ccffcc..f82af60 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -13,7 +13,7 @@ export default defineConfig({ nav: [ { text: "首页", link: "/" }, { text: "快速开始", link: "/guide/" }, - // { text: 'API 状态', link: '/status' } + { text: "XCodeClaw", link: "/xcodeclaw" }, ], sidebar: [ @@ -26,6 +26,13 @@ export default defineConfig({ { text: "Codex", link: "/guide/codex" }, ], }, + { + text: "XCodeClaw", + items: [ + { text: "产品介绍", link: "/xcodeclaw" }, + { text: "飞书机器人配置", link: "/guide/feishu-bot" }, + ], + }, { text: "参考", items: [ diff --git a/docs/assets/feishu/01-create-app.png b/docs/assets/feishu/01-create-app.png new file mode 100644 index 0000000..605f354 Binary files /dev/null and b/docs/assets/feishu/01-create-app.png differ diff --git a/docs/assets/feishu/02-app-info.png b/docs/assets/feishu/02-app-info.png new file mode 100644 index 0000000..1ee4155 Binary files /dev/null and b/docs/assets/feishu/02-app-info.png differ diff --git a/docs/assets/feishu/03-add-bot.png b/docs/assets/feishu/03-add-bot.png new file mode 100644 index 0000000..6037f9f Binary files /dev/null and b/docs/assets/feishu/03-add-bot.png differ diff --git a/docs/assets/feishu/04-import-perms.png b/docs/assets/feishu/04-import-perms.png new file mode 100644 index 0000000..51e932a Binary files /dev/null and b/docs/assets/feishu/04-import-perms.png differ diff --git a/docs/assets/feishu/05-perms-done.png b/docs/assets/feishu/05-perms-done.png new file mode 100644 index 0000000..72c4f96 Binary files /dev/null and b/docs/assets/feishu/05-perms-done.png differ diff --git a/docs/assets/feishu/06-event-longconn.png b/docs/assets/feishu/06-event-longconn.png new file mode 100644 index 0000000..a21e03a Binary files /dev/null and b/docs/assets/feishu/06-event-longconn.png differ diff --git a/docs/assets/feishu/07-event-subscribe.png b/docs/assets/feishu/07-event-subscribe.png new file mode 100644 index 0000000..614b080 Binary files /dev/null and b/docs/assets/feishu/07-event-subscribe.png differ diff --git a/docs/assets/feishu/08-event-detail.png b/docs/assets/feishu/08-event-detail.png new file mode 100644 index 0000000..082f994 Binary files /dev/null and b/docs/assets/feishu/08-event-detail.png differ diff --git a/docs/assets/feishu/09-callback-longconn.png b/docs/assets/feishu/09-callback-longconn.png new file mode 100644 index 0000000..6627262 Binary files /dev/null and b/docs/assets/feishu/09-callback-longconn.png differ diff --git a/docs/assets/feishu/10-callback-add.png b/docs/assets/feishu/10-callback-add.png new file mode 100644 index 0000000..ef3924d Binary files /dev/null and b/docs/assets/feishu/10-callback-add.png differ diff --git a/docs/assets/feishu/11-security-token.png b/docs/assets/feishu/11-security-token.png new file mode 100644 index 0000000..90864db Binary files /dev/null and b/docs/assets/feishu/11-security-token.png differ diff --git a/docs/assets/feishu/12-create-version.png b/docs/assets/feishu/12-create-version.png new file mode 100644 index 0000000..f3be14b Binary files /dev/null and b/docs/assets/feishu/12-create-version.png differ diff --git a/docs/assets/feishu/13-version-info.png b/docs/assets/feishu/13-version-info.png new file mode 100644 index 0000000..323ab15 Binary files /dev/null and b/docs/assets/feishu/13-version-info.png differ diff --git a/docs/assets/feishu/14-publish.png b/docs/assets/feishu/14-publish.png new file mode 100644 index 0000000..0cf1a27 Binary files /dev/null and b/docs/assets/feishu/14-publish.png differ diff --git a/docs/assets/feishu/promo-data.jpg b/docs/assets/feishu/promo-data.jpg new file mode 100644 index 0000000..07dbced Binary files /dev/null and b/docs/assets/feishu/promo-data.jpg differ diff --git a/docs/assets/feishu/promo-hero.jpg b/docs/assets/feishu/promo-hero.jpg new file mode 100644 index 0000000..4a6fa8b Binary files /dev/null and b/docs/assets/feishu/promo-hero.jpg differ diff --git a/docs/assets/feishu/promo-latex.jpg b/docs/assets/feishu/promo-latex.jpg new file mode 100644 index 0000000..72b5255 Binary files /dev/null and b/docs/assets/feishu/promo-latex.jpg differ diff --git a/docs/assets/feishu/promo-research.jpg b/docs/assets/feishu/promo-research.jpg new file mode 100644 index 0000000..59cba43 Binary files /dev/null and b/docs/assets/feishu/promo-research.jpg differ diff --git a/docs/guide/feishu-bot.md b/docs/guide/feishu-bot.md new file mode 100644 index 0000000..acdc7ac --- /dev/null +++ b/docs/guide/feishu-bot.md @@ -0,0 +1,277 @@ +--- +title: XCodeClaw 飞书机器人配置指南 +--- + +# XCodeClaw 飞书机器人配置指南 + +本指南帮助您在飞书开放平台创建并配置机器人应用，完成后将 App ID 和 App Secret 提供给管理员即可开通服务。 + +> **您只需完成飞书侧配置**，模型配置、服务部署由管理员完成，无需关心。 + +## 1. 概述 + +XCodeClaw 是一个 AI 学术助手，通过飞书机器人与您交互。您需要在飞书开放平台创建一个机器人应用，并完成权限和事件订阅的配置。 + +:::tip 整体流程 +1. 在飞书开放平台创建企业自建应用 +2. 添加机器人能力 +3. 导入权限配置 +4. 获取凭证（App ID 和 App Secret），发送给管理员 +5. 等待管理员创建服务实例 +6. 配置事件订阅与回调（需要服务实例已运行） +7. 发布应用 +::: + +:::warning 流程顺序很重要 +事件订阅和回调使用「长连接」模式，即由服务端主动与飞书建立 WebSocket 连接。因此必须先让管理员创建服务实例，待服务启动后再配置长连接，否则连接无法建立。 +::: + +完成以上步骤后，在飞书中搜索您创建的机器人即可开始使用。 + +## 2. 创建飞书应用 + +### 第一步：登录飞书开放平台 + +1. 打开浏览器，访问飞书开放平台：[https://open.feishu.cn/app](https://open.feishu.cn/app) +2. 使用您的飞书账号登录。 +3. 点击页面上的「**创建企业自建应用**」按钮： + +![创建企业自建应用](../assets/feishu/01-create-app.png) + +填写应用信息，包括应用名称、描述和图标，然后点击「**创建**」： + +![填写应用信息](../assets/feishu/02-app-info.png) + +:::tip 建议 +应用名称建议使用易于辨识的名称，如「XCodeClaw 助手」或「AI 学术助手」。 +::: + +## 3. 添加机器人能力 + +### 第二步：启用机器人功能 + +进入刚创建的应用，在左侧菜单中操作： + +1. 点击左侧菜单「**应用能力**」→「**机器人**」。 +2. 点击「**启用机器人能力**」。 +3. 机器人名称会自动填充应用名称，确认即可。 + +![添加机器人](../assets/feishu/03-add-bot.png) + +## 4. 配置权限 + +### 第三步：批量导入权限 + +1. 在左侧菜单中点击「**开发配置**」→「**权限管理**」。 +2. 点击页面右上角的「**批量开通**」按钮（如下图所示）。 +3. 将下方的 JSON 内容完整复制并粘贴到输入框中，点击确认。 + +![批量导入权限](../assets/feishu/04-import-perms.png) + +需要导入的权限 JSON： + +```json +{ + "scopes": { + "tenant": [ + "aily:file:read", + "aily:file:write", + "application:application.app_message_stats.overview:readonly", + "application:application:self_manage", + "application:bot.menu:write", + "cardkit:card:write", + "contact:user.employee_id:readonly", + "corehr:file:download", + "docs:document.content:read", + "event:ip_list", + "im:chat", + "im:chat.access_event.bot_p2p_chat:read", + "im:chat.members:bot_access", + "im:message", + "im:message.group_at_msg:readonly", + "im:message.group_msg", + "im:message.p2p_msg:readonly", + "im:message:readonly", + "im:message:send_as_bot", + "im:resource", + "sheets:spreadsheet", + "wiki:wiki:readonly" + ], + "user": [ + "aily:file:read", + "aily:file:write", + "im:chat.access_event.bot_p2p_chat:read" + ] + } +} +``` + +:::warning 注意 +请确保 JSON 内容完整复制，不要遗漏任何权限项。权限不全会导致机器人功能受限。 +::: + +导入成功后，权限列表应显示如下： + +![权限导入完成](../assets/feishu/05-perms-done.png) + +下表列出了主要权限的用途说明： + +| 权限标识 | 用途 | +| :--- | :--- | +| `im:message:send_as_bot` | 以机器人身份发送消息 | +| `im:message.p2p_msg:readonly` | 读取私聊消息 | +| `im:message.group_at_msg:readonly` | 读取群聊中 @机器人 的消息 | +| `im:chat` | 管理群聊（创建/更新群信息） | +| `im:resource` | 读取和发送文件、图片等资源 | +| `docs:document.content:read` | 读取飞书文档内容 | +| `sheets:spreadsheet` | 读写飞书电子表格 | +| `wiki:wiki:readonly` | 读取知识库内容 | +| `cardkit:card:write` | 发送和更新卡片消息（流式输出） | + +## 5. 获取凭证并交给管理员 + +### 第四步：获取 App ID 和 App Secret + +1. 在左侧菜单中点击「**基础信息**」→「**凭证与基础信息**」。 +2. 复制以下两个值： + - **App ID**：格式为 `cli_xxxxxxxxxxxxxxxx` + - **App Secret**：一串字母数字组合 +3. 将这两个值发送给管理员，用于开通您的 XCodeClaw 服务。 + +:::warning 安全提示 +App Secret 是应用的密钥，请妥善保管，不要在公开场合泄露。仅通过安全渠道发送给管理员。 +::: + +## 6. 等待管理员开通服务 + +### 第五步：等待服务实例创建 + +将凭证发送给管理员后，管理员会在后台为您创建服务实例并启动容器。 + +**请等待管理员确认服务已启动**，然后再进行下一步的事件订阅与回调配置。 + +:::tip 为什么要等待？ +事件订阅和回调使用「长连接」（WebSocket）模式，由服务端主动与飞书建立连接。如果服务实例尚未启动，长连接无法建立，事件订阅将无法正常工作。 +::: + +## 7. 配置事件订阅与回调 + +:::warning 前置条件 +请确认管理员已通知您服务实例已启动，再进行本步骤的配置。 +::: + +本步骤包含三个部分：事件订阅、回调配置和安全设置。 + +### 7.1 事件订阅 + +#### 第六步 A：配置事件订阅 + +1. 在左侧菜单中点击「**开发配置**」→「**事件与回调**」。 +2. **事件请求方式**：选择「**使用长连接接收事件**」（如下图）。 + +![选择长连接](../assets/feishu/06-event-longconn.png) + +3. 点击「**添加事件**」，搜索并添加以下事件： + +| 事件名称 | 事件标识 | +| :--- | :--- | +| 接收消息 | `im.message.receive_v1` | +| 添加表情回复 | `im.message.reaction.created_v1` | +| 删除表情回复 | `im.message.reaction.deleted_v1` | + +![添加事件](../assets/feishu/07-event-subscribe.png) + +![事件详情](../assets/feishu/08-event-detail.png) + +### 7.2 回调配置 + +#### 第六步 B：配置回调 + +1. 在同一页面中，找到「**回调配置**」区域。 +2. 回调请求方式同样选择「**使用长连接**」。 +3. 点击「**添加回调**」，搜索并添加卡片操作相关回调。 + +![回调长连接](../assets/feishu/09-callback-longconn.png) + +![添加回调](../assets/feishu/10-callback-add.png) + +### 7.3 安全设置 + +#### 第六步 C：启用用户凭证 + +在「**安全设置**」区域，如果看到「**user_access_token**」开关，请将其**开启**。 + +![安全设置](../assets/feishu/11-security-token.png) + +## 8. 发布应用 + +### 第七步：创建版本并发布 + +1. 在左侧菜单中点击「**版本管理与发布**」。 +2. 点击「**创建版本**」。 + +![创建版本](../assets/feishu/12-create-version.png) + +3. 填写版本号（如 `1.0.0`）和更新说明，选择可用范围，点击「**保存**」： + +![版本信息](../assets/feishu/13-version-info.png) + +4. 点击「**申请发布**」，确认发布： + +![发布](../assets/feishu/14-publish.png) + +:::tip 配置完成 🎉 +应用发布后，在飞书中搜索您创建的机器人名称，发送任意消息即可开始使用。 +::: + +## 9. 授权飞书资源访问 + +### 第八步：完成飞书授权 + +机器人上线后，建议立即完成飞书资源授权，以解锁文档读写、表格操作等高级功能。 + +1. 在飞书中找到您的机器人，发送：`/feishu auth` +2. 机器人会返回一个**授权链接**，点击链接并在弹出页面中同意授权。 +3. 授权成功后，机器人即可代您访问飞书文档、多维表格、知识库等资源。 + +:::tip 授权说明 +此授权基于飞书 `user_access_token` 机制，仅在您主动授权后生效。授权范围包括：读取文档内容、操作电子表格、访问知识库等（即前面配置的 user 级权限）。不授权不影响基本的对话功能，但文档相关能力将不可用。 +::: + +## 10. 配置检查清单 + +请对照以下清单确认所有配置已完成： + +| | 检查项 | 说明 | +| :---: | :--- | :--- | +| ☐ | 创建应用 | 已在飞书开放平台创建企业自建应用 | +| ☐ | 机器人能力 | 已启用机器人能力 | +| ☐ | 权限导入 | 已通过 JSON 批量导入全部权限 | +| ☐ | 获取凭证 | 已复制 App ID 和 App Secret 并发送给管理员 | +| ☐ | 服务开通 | 管理员已确认服务实例启动 | +| ☐ | 事件订阅 | 已添加 3 个事件，使用长连接模式 | +| ☐ | 回调配置 | 已配置回调，使用长连接模式 | +| ☐ | 安全设置 | 已开启 user_access_token 开关 | +| ☐ | 发布应用 | 已创建版本并发布上线 | +| ☐ | 飞书授权 | 已发送 `/feishu auth` 并完成授权 | + +## 11. 常见问题 + +### 机器人没有响应消息 + +- 确认管理员已开通服务（服务实例已启动） +- 确认应用已发布（状态为「已上线」） +- 确认事件订阅和回调都已配置为「长连接」模式 +- 确认权限已全部导入（检查「权限管理」页面） + +### 权限批量导入失败 + +- 检查 JSON 格式是否正确（注意逗号和引号） +- 部分权限可能需要企业管理员审批后才能开通 +- 如果批量导入不可用，可手动搜索并逐个添加权限 + +### 如何在群聊中使用机器人 + +- 将机器人添加到群聊中 +- 在群聊中 @机器人名称 后输入您的问题 +- 机器人默认只响应 @它 的消息 diff --git a/docs/xcodeclaw.md b/docs/xcodeclaw.md new file mode 100644 index 0000000..564d2d0 --- /dev/null +++ b/docs/xcodeclaw.md @@ -0,0 +1,345 @@ +--- +title: XCodeClaw - AI 学术助手 +--- + +
+ + +
+ +
+
+
POWERED BY CLAUDE OPUS 4.6
+

XCodeClaw

+
你的 AI 学术助手
+

满血 Opus 4.6 大模型 + 联网搜索 + 图像生成 + 完整科研工具链，
开箱即用，飞书直达。

+
+
Claude Opus 4.6
+
Tavily 搜索
+
Banana 画图
+
LaTeX 排版
+
飞书集成
+
+
+
+
+ + +
+
+
Core Advantages
+
为什么选择 XCodeClaw？
+

不只是一个聊天机器人，而是一个真正懂学术的 AI 科研伙伴。

+
+
+
AI
+

满血大模型

+

搭载 Claude Opus 4.6，当前最强推理模型之一。200K 超长上下文窗口，轻松处理长篇论文和复杂分析任务。

+
+
+
S
+

实时联网搜索

+

集成 Tavily 学术搜索引擎，实时检索最新文献和资料。告别信息滞后，紧跟学术前沿。

+
+
+
G
+

AI 画图

+

内置 Banana 图像生成能力（Gemini 4K），可直接生成流程图、示意图、架构图等学术插图，论文配图一步到位。

+
+
+
T
+

LaTeX 全家桶

+

预装 TeX Live 完整版 + 中文字体（宋体/黑体/雅黑/Noto），直接生成专业排版学术文档并编译输出 PDF。

+
+
+
D
+

科学计算栈

+

内置 NumPy、SciPy、Pandas、Matplotlib、Scikit-learn、Seaborn 等全套数据分析与可视化工具。

+
+
+
F
+

开箱即用

+

在飞书中直接对话使用，无需安装任何软件。管理员一键部署，用户零学习成本，即开即用。

+
+
+
+
+ + +
+
+
Academic Scenarios
+
专为科研场景打造
+

从文献调研到论文写作，从数据分析到报告排版，覆盖科研全流程。

+ +
+
+

深度学术调研

+

内置 Deep Research Pro 技能，可自主进行多源深度检索，综合分析后生成带引用的结构化研究报告。严格引用学术来源——期刊论文、会议论文、学术专著，拒绝博客和百科，杜绝编造引用。

+
+ 多源检索 + 自动引用 + 结构化报告 +
+
+
+ 深度学术调研 +
+
+ +
+
+

论文写作与润色

+

专业的学术写作能力，自动消除 AI 写作痕迹，产出地道流畅的中英文学术表达。数学公式自动 LaTeX 格式化，引用格式严格规范。支持直接生成 LaTeX 源文件并编译为高质量 PDF。

+
+ 去 AI 痕迹 + 公式排版 + PDF 输出 +
+
+
+ 论文写作与排版 +
+
+ +
+
+

数据分析与可视化

+

完整的 Python 科学计算环境，直接在对话中处理数据、运行统计分析、生成专业图表。上传数据文件即可开始，结果以图表形式直接返回到飞书。

+
+ NumPy + Pandas + Matplotlib + Scikit-learn + SciPy +
+
+
+ 数据分析与可视化 +
+
+
+
+ + +
+
+
Comparison
+
与通用 AI 工具的区别
+

通用 AI 工具缺乏科研专业性，XCodeClaw 专为学术场景深度定制。

+ + + + + + + + + + + + + + + +
能力XCodeClaw通用 AI 助手
满血 Opus 4.6 模型✓ 完整版— 通常为低配版本
实时联网检索✓ Tavily 学术搜索— 无或受限
AI 画图（4K）✓ Banana / Gemini— 无或需额外付费
LaTeX 编译输出 PDF✓ TeX Live 完整版— 仅输出代码片段
科学计算环境✓ 完整 Python 数据分析栈— 无执行环境
学术引用规范✓ 严格学术来源— 可能编造引用
AI 写作痕迹消除✓ 专项优化— 无
飞书原生集成✓ 流式回复 + 多轮对话— 需切换应用
独立容器隔离✓ 每用户独享环境— 共享环境
+
+
+ + +
+
+
Quick Start
+
三步开始使用
+

无需安装软件，无需配置环境，飞书里直接用。

+
+
+
1
+

创建飞书应用

+

在飞书开放平台创建应用，添加机器人能力，导入权限配置。跟着指南操作，10 分钟搞定。

+
+
+
2
+

交给管理员

+

将 App ID 和 App Secret 发送给管理员。管理员一键创建您的专属服务实例，独立容器，安全隔离。

+
+
+
3
+

开始使用

+

在飞书中搜索机器人名称，发送消息即可。支持私聊和群聊 @，流式实时回复，多轮上下文记忆。

+
+
+
+
+ + +
+
+
Tech Stack
+
技术架构
+

基于 OpenClaw 构建，企业级多租户架构，安全可靠。

+
+
+

多租户容器隔离

+

每位用户独享一个 Docker 容器，数据完全隔离，互不干扰。支持独立配置和资源管控。

+
+
+

自愈配置系统

+

启动时自动检测和修复配置问题，插件自动更新，无需人工维护，持续保持最佳状态。

+
+
+

流式实时响应

+

飞书消息流式输出，边生成边展示，无需等待。支持耗时任务状态显示和进度追踪。

+
+
+
+
+ + +
+

开始使用 XCodeClaw

+

让 AI 成为你的科研伙伴，从今天开始提升学术生产力。

+ 查看配置指南 → +
+ +
+ +