# Feishu Doc To Md

> Export a Feishu/Lark wiki or docx URL/token into local Markdown with local image assets. Use when the user asks to convert 飞书/Lark 文档为 md, save a wiki/docx as Markdown, or preserve document images locally instead of leaving them remote.

- **Type:** Skill
- **Install:** `agentstack add skill-ejjcc-agent-skills-feishu-doc-to-md`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ejjcc](https://agentstack.voostack.com/s/ejjcc)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ejjcc](https://github.com/ejjcc)
- **Source:** https://github.com/ejjcc/agent-skills/tree/main/feishu-doc-to-md

## Install

```sh
agentstack add skill-ejjcc-agent-skills-feishu-doc-to-md
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# feishu-doc-to-md

Export Feishu/Lark wiki or docx pages into Markdown plus local assets.

## When To Use

Trigger this skill when the user wants any of the following:

- A 飞书/Lark wiki or docx exported to `.md`
- Local image assets instead of remote document assets
- A repeatable Feishu-to-Markdown conversion flow

## Quick Start

Normalize `PATH` before running anything:

```bash
export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
```

Run the main exporter:

```bash
python3 ~/.claude/skills/feishu-doc-to-md/scripts/export_feishu_doc.py "$DOC_URL_OR_TOKEN" --output-dir "$OUTPUT_DIR"
```

Common choices:

- Default export dir: omit `--output-dir`; the script uses `./feishu-exports//`
- Workspace docs dir: pass `--output-dir docs`
- Override the output file basename: add `--doc-name "Custom Name"`

The script prints a JSON summary with:

- `final_md`
- `raw_md`
- `assets_dir`
- `image_map`
- `counts`
- `unresolved`

## Validation

After every export, run:

```bash
python3 ~/.claude/skills/feishu-doc-to-md/scripts/validate_export.py ""
```

Treat these as hard failures:

- unresolved rows in `image-map.tsv`
- remaining `feishu://...` placeholders
- remaining remote image refs like ``

`validate_export.py` exits non-zero when any of those are present.

## Outputs

The exporter writes:

- `/.raw.md`
- `/.md`
- `/.assets/images/*`
- `/.assets/image-map.tsv`

## Auth Model

The scripted flow intentionally avoids `bytectl openfeishu uapi ...` as the primary transport because that path can block on interactive auth in agent sessions.

The exporter uses:

- `bytectl -b -s openfeishu uat` to fetch a fresh user token
- `bytectl -c openfeishu apiinfo` to read the current authenticated Lark session cookie
- direct HTTPS requests to Feishu OpenAPI and authenticated Lark file endpoints

Keep this model unless you have revalidated a better one end-to-end.

## Current Download Strategy

- `image_token`: download through OpenAPI `/open-apis/drive/v1/medias//download`
- `board_token`: download through authenticated Lark file URL `space/api/file/f/cdp-whiteboard-~noop/`

Important:

- Board download through OpenAPI may return `404` in real docs even when board assets are visible in the document
- The current scripted cookie-based board path is the known-good path

## Troubleshooting

If the exporter fails before producing JSON:

- Check `bytectl` exists and is logged in
- Run `bytectl -b -s openfeishu uat`; it must return a token immediately
- Run `bytectl -c openfeishu apiinfo`; it must return JSON with `auth.cookie`

If assets are unresolved:

- Inspect `.assets/image-map.tsv`
- Report the unresolved rows and reasons back to the user
- Only reach for Playwright or screenshot fallback if the real export actually needs it

If you modify the exporter:

- Keep `SKILL.md` lean; put deterministic logic in scripts, not prose
- Re-run `validate_export.py`
- Re-run a real export smoke test on a known Feishu wiki/docx URL

## Files To Read

Read these only when needed:

- `scripts/export_feishu_doc.py`: main implementation
- `scripts/validate_export.py`: export checks

Do not expand this skill by pasting full algorithms into `SKILL.md`. Script-first is the intended maintenance model.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ejjcc](https://github.com/ejjcc)
- **Source:** [ejjcc/agent-skills](https://github.com/ejjcc/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ejjcc-agent-skills-feishu-doc-to-md
- Seller: https://agentstack.voostack.com/s/ejjcc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.