feishu2md

飞书文档转 Markdown

将飞书文档链接快速转换为 Markdown 格式，自动落盘到当前活动目录的 requirements/feishu/ 下，并同步更新活动 AGENTS.md 的「需求文档」表格。

用户的输入: $ARGUMENTS

---

🤖 AI 执行指令

按步骤执行，整个流程中只在「输出路径」不符用户预期时才提问，其余步骤自主完成。

步骤 1：获取文档链接 + 环境配置

1.1 获取飞书链接

• 从用户输入中提取飞书文档链接，支持格式：
  • https://xxx.feishu.cn/docx/xxxx（新版文档）
  • https://xxx.feishu.cn/wiki/xxxx（知识库文档）
• 用户没有提供链接 → 询问用户。

1.2 检查 API 凭证

• 脚本会自动从项目根 .env.local 读取 APP_ID / APP_SECRET，fallback 环境变量 FEISHU_APP_ID / FEISHU_APP_SECRET。
• 两者均缺失时提示：

  需要飞书 API 凭证。请在项目根目录的 .env.local 中添加：
    APP_ID=your_app_id
    APP_SECRET=your_app_secret
  

步骤 2：确定输出目录

按以下优先级确定 <输出目录>，无需用户手动输入：

优先级	来源	规则
1	当前 git 分支名	运行 git rev-parse --abbrev-ref HEAD，按下表推导
2	对话上下文	若对话中已明确提过活动目录（如用户正在开发 apps/short/xxx），直接使用
3	兜底	docs/feishu-docs/YYYY-MM-DD/（非活动分支时）

分支名 → 活动目录映射：

分支格式	示例	活动目录	输出目录
act-YYYYMMDD[-suffix]	act-20260425-a	apps/short/20260425-a/	apps/short/20260425-a/requirements/feishu/
mdc-XXXX	mdc-6063	apps/mdc/6063/	apps/mdc/6063/requirements/feishu/
其他（main、feature/*…）	—	—	docs/feishu-docs/YYYY-MM-DD/

act- 说明：提取分支名中 act- 之后的完整片段（含后缀，如 20260425-a、20260425-hw），整体作为活动目录名。

确定后 mkdir -p <输出目录>。

步骤 3：执行转换

3.1 准备 venv（首次运行或脚本报找不到依赖时才做）

python3 -m venv ~/.feishu2md-venv
~/.feishu2md-venv/bin/pip install requests lark-oapi -q

3.2 构建命令

{SKILL_BASE_DIR} 来自 skill 启动时的 "Base directory for this skill:" 路径。

• 由文档标题自动命名（默认）：把目录作为第二参数，结尾带 /，脚本会用文档标题生成文件名：

  ~/.feishu2md-venv/bin/python3 {SKILL_BASE_DIR}/scripts/feishu2md.py "<飞书链接>" "<输出目录>/"
  

• 用户明确指定了文件名（如"保存为 xxx.md"）：拼成完整路径传入：

  ~/.feishu2md-venv/bin/python3 {SKILL_BASE_DIR}/scripts/feishu2md.py "<飞书链接>" "<输出目录>/xxx.md"
  

3.3 解析脚本输出

脚本 stdout 会打印 Markdown 已保存到: <绝对路径>。记录这个路径作为 <最终文件>，后续 AGENTS.md 更新和展示都用它。

3.4 错误处理

错误关键字	处理
缺少必需的配置	提示在 .env.local 配置 APP_ID / APP_SECRET
请先安装飞书 SDK	跑 ~/.feishu2md-venv/bin/pip install requests lark-oapi
无法解析飞书 URL	检查链接格式是否完整
获取文档失败: 403	确认应用有文档读取权限，或文档已授权

步骤 4：委托 agents-md skill 更新 AGENTS.md

仅当 <输出目录> 位于活动目录下（路径含 apps/short/ 或 apps/mdc/）时执行；走兜底路径（docs/feishu-docs/）时跳过此步骤，只告知用户输出位置即可。

不要在此处自行解析 AGENTS.md 或拼接表格 —— 所有 AGENTS.md 读写逻辑以 agents-md skill 为单一事实源。本步骤要做的只是把必要上下文交给它：

1. 调用 agents-md skill(使用 Skill 工具,skill: "agents-md")。
2. 在 args 中显式传入以下上下文,避免 agents-md 重新做分支检测或目录猜测:
   • 活动目录:步骤 2 已确定的 <活动目录>(如 apps/short/20260425-a/ 或 apps/mdc/6063/)
   • 新增需求文档:步骤 3 解析出的 <最终文件> 绝对路径
   • 触发原因:feishu2md 转换完成,需要将该飞书需求文档登记到活动 AGENTS.md 的「需求文档」章节

agents-md skill 会按其自身规则(SKILL.md 的「需求文档自动更新」章节)完成:

• 识别 requirements/feishu/ 路径 → 映射为「飞书需求」类型
• 读取 .md 文件第一行 H1 作为说明
• ## 需求文档 章节已存在则追加、不存在则新建
• AGENTS.md 整体不存在则按其决策流程询问用户是否创建

feishu2md 不要试图预判 agents-md 会做什么 —— 如果 agents-md 将来改了规则(例如调整 ## 需求文档 的表格结构、或新增字段),feishu2md 自动受益、无需同步修改。

步骤 5：汇报结果

✅ 飞书文档转换完成

文档标题: <H1 标题>
输出文件: <最终文件>
字符数:   <markdown 长度>

AGENTS.md: 已委托 agents-md skill 处理(具体更新结果见其输出)

若用户需要，进一步：

• 询问是否用 feishu-requirement 做玩法需求分析
• 询问是否用 activity-doc-checker 做文档质量检查

---

直接运行脚本（不走 skill）

# 按文档标题自动命名，落盘到指定活动目录
~/.feishu2md-venv/bin/python3 scripts/feishu2md.py \
  "https://xxx.feishu.cn/docx/xxx" \
  "apps/short/20260425-a/requirements/feishu/"

# 指定完整文件名
~/.feishu2md-venv/bin/python3 scripts/feishu2md.py \
  "https://xxx.feishu.cn/docx/xxx" \
  "apps/short/20260425-a/requirements/feishu/my-doc.md"

# 不传第二参数，兼容旧行为（输出到 CWD/output.md）
~/.feishu2md-venv/bin/python3 scripts/feishu2md.py "https://xxx.feishu.cn/docx/xxx"

# 使用临时凭证（覆盖 .env.local）
FEISHU_APP_ID=xxx FEISHU_APP_SECRET=xxx \
  ~/.feishu2md-venv/bin/python3 scripts/feishu2md.py "https://xxx.feishu.cn/docx/xxx" "output-dir/"

---

约束

1. 输出目录优先活动目录，仅在非活动分支且对话上下文也没有活动路径线索时才 fallback 到 docs/feishu-docs/，禁止随意写到 CWD。
2. 文件名默认由文档标题驱动（脚本内部做字符清洗），不要手动猜名字；用户明确指定时才用用户指定的名字。
3. AGENTS.md 的读写交给 agents-md skill — feishu2md 不直接解析、不拼接表格、不判断幂等;这些是 agents-md 的职责。
4. 非活动分支跳过 AGENTS.md 委托 — 走兜底 docs/feishu-docs/ 时连 agents-md 也不调用,只告知用户输出路径。
5. 脚本输出的绝对路径是唯一真源 — 步骤 4/5 引用的 <最终文件> 必须从脚本 stdout 解析，不要凭经验拼路径（文档标题可能被清洗）。

---

功能说明

支持的文档元素

• ✅ 文本（粗体、斜体、下划线、删除线、行内代码）
• ✅ 标题（H1-H9）
• ✅ 列表（无序、有序，含嵌套）
• ✅ 代码块（60+ 语言）
• ✅ 引用块 / 待办事项
• ✅ 表格（普通表格 + 电子表格）
• ✅ 图片（记录 token，默认不下载）
• ✅ 公式（行内 + 块级 LaTeX）
• ✅ 高亮块 Callout / 网格布局

性能参考

文档规模	预估耗时
< 100 块	1-2 秒
100-500 块	3-10 秒
> 500 块	10-30 秒
含电子表格	每个表格 +2-5 秒

常见问题

• 图片显示为 token — 默认只记录 token，需要下载图片可在脚本 OutputConfig 中把 skip_img_download 置为 False。
• 表格"数据获取失败" — 应用缺少电子表格读取权限，去飞书开放平台开通。
• 删除线内容丢失 — 有意设计，正文会过滤带删除线的文本；表格单元格保留 ~~xxx~~ 标记。