makecindy / makecindy/cindy

feat(xd-feishu): 支持写入飞书 Wiki Slides 节点

Open
#4,439 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
2.7k
Forks
395
Avg merge
21h 48m
Merged PRs (30d)
776

Description

> 范围说明:本需求针对独立的 `xd-feishu` 插件/插件仓,不要求 Cindy client 新增顶层 MCP 能力。

## 概要

`xd-feishu` 插件可以解析 `obj_type=slides` 的飞书 Wiki 节点,也可以确认连接账号拥有 `edit` 权限,但目前不能追加或更新演示文稿内容。

这造成了明显的能力断层:用户可以在飞书界面编辑演示文稿,但 Cindy 只能读取权限/元数据,并报告无法写入内容。

## 复现信息

1. 连接一个对演示文稿 Wiki 节点拥有编辑权限的飞书账号。
2. 使用一个由当前账号可访问的 `slides` Wiki 节点进行解析(实际节点 token 已脱敏)。
3. 节点可以成功解析为:
- `node_type`: `origin`
- `obj_type`: `slides`
- `obj_token`: ``
4. 权限查询显示连接账号拥有 `edit` 权限。
5. `read_by_url` 返回 `slides` 节点暂不支持内容读取,工具目录也没有 `slides` 写入操作。

> 注:为避免公开 issue 暴露私人飞书资源,真实 Wiki token 和 `obj_token` 不在此贴出;维护者可使用自己有权限的 `slides` 节点复现。

## 期望行为

对于连接账号拥有 `edit` 权限的 `slides` 节点,插件应在明确确认后支持至少一种可验证的写操作,例如:

- 追加一页;
- 更新页面文本或基础元素。

是否支持追加多页、复制页面或从本地 PPTX 导入,取决于飞书实际提供的 Slides/Presentation API,不应在 MVP 阶段预先承诺。

## 建议实现

1. 先确认飞书 OpenAPI 是否提供可用的 Slides/Presentation API、对应 scope 及可写粒度。
2. 在 `xd-feishu` 的 capability discovery 中增加明确的 `slides` 能力声明;若 API 不支持,应返回清晰的“能力不支持”错误,而不是笼统报错。
3. MVP 优先实现:解析 `slides` Wiki 节点、读取演示文稿元数据/页面(若 API 支持),并在 `edit` 权限下追加一页或更新文本。
4. 所有外部写操作复用现有 mutation-confirm 流程。
5. 写入后回读验证,并保证同一操作重试不会重复创建页面;如果飞书 API 不提供原生幂等键,插件应采用明确的去重或操作记录策略。
6. 错误至少区分:`view` 权限不足、OAuth scope 缺失、飞书 API 不支持该操作、目标节点类型不匹配、并发/幂等冲突。

## 验收标准

- 在飞书实际 API 支持且连接账号拥有 `edit` 权限时,用户可以通过 `xd-feishu` 追加一页或更新文本。
- `view` 权限在发起写请求前被拒绝。
- 已有页面不会被无意删除或覆盖;并发冲突有明确错误返回。
- 同一写入操作重试不会重复创建页面;若使用 `idempotency_key`,重复请求应返回同一操作结果。
- 写入成功后返回更新后的演示文稿 URL/token 和变更摘要。
- 工具目录准确声明已实现的 `slides` 能力;未支持的操作返回明确的能力不支持错误。

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the xd-feishu capability discovery and existing mutation-confirm flow, then verify which Feishu Slides/Presentation APIs and OAuth scopes are available. Define the smallest supported write operation and its validation path. Done requires explicit capability reporting, permission and unsupported-operation errors, safe retry behavior, and post-write verification without duplicating pages.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.