Bruce Doc Converter

Run the local bdc CLI through a command execution tool. It prints JSON on stdout; progress logs may appear on stderr.

Prepare the CLI (once per session)

Check installation and updates the first time you convert in a session; later conversions reuse the same entry point without checking again.

1. Run bdc --help-json. If the command is missing, look for an existing virtual environment (.venv/bin/bdc, or .venv\Scripts\bdc on Windows) before concluding it is not installed; otherwise install it following Install and update.
2. Read cli_version and install (source, auto_upgrade, upgrade_command). CLIs before 0.2.2 have no install field; identify the installation as described in the reference.
3. When the network is available, find the latest stable release: python -m pip index versions bruce-doc-converter (first line). Compare semantic versions, not strings; never downgrade or choose a pre-release.
4. If a newer release exists:

• auto_upgrade: true (pipx, uv tool, pip --user): run upgrade_command, re-run bdc --help-json to confirm, and tell the user the old and new versions.
• venv: this may be a project dependency. Tell the user an update exists and run upgrade_command only after they agree.
• system or source (a development checkout): tell the user; do not modify it.
• A version the user or host pinned stays as is; only mention the update.

1. Offline, a failed query, or a host policy that forbids installs: keep using the installed version and say that updates were not checked. Follow the host's install approval and audit rules; do not bypass them to get a newer version.

After an upgrade, the next Markdown to Word conversion may return DEPENDENCY_INSTALL_REQUIRED; run its next_command (bdc setup-node) and retry.

Convert

Office/PDF to Markdown

bdc convert "<file>"
bdc convert "<file>" --content preview      # large files: return a preview, full text is still written
bdc convert "<file>" --extract-images true  # also save embedded images
bdc batch "<directory>"

Read markdown_content directly for analysis. Output goes to a Markdown/ directory beside the source unless --output-dir is given.

Markdown to Word

1. Use the user's existing .md file. When writing a new report, save it as UTF-8 Markdown first so the source stays editable.
2. Markdown to Word needs Node.js >=22.0 and a one-time bdc setup-node. Office/PDF conversion does not need Node.js.
3. Export deliverables in strict mode, quoting paths with spaces or CJK characters:

   bdc convert "docs/报告.md" --strict

The file goes to a Word/ directory beside the source unless --output-dir is given. Existing files are never overwritten; a numbered name such as 报告.2.docx is used instead, so read the real path from output_path.

Check the result

1. Check the exit code and parse stdout. On success, confirm output_path exists and is not empty, then report that exact path. Files live on the machine that ran the command; attach them only when the host provides attachments, and never invent download links.
2. Read warnings and diagnostics. Each diagnostic has code, severity, message, and a location when known (line for Markdown, page for PDF, sheet/cell for Excel). warning items mean missing or degraded content and fail --strict; info items are advisory.
3. On CONTENT_INCOMPLETE, nothing was written. Fix the source at the reported lines and rerun the same strict command. Do not drop --strict for a final deliverable unless the user accepts degraded output, and then say exactly what is missing. If the same failure repeats with nothing new to fix, stop and explain what material or environment is needed.
4. For other failures, use error_code, retryable, next_command and suggestion. See Diagnostics and errors for every code.

A strict success only means no content loss was detected. It does not prove the facts are right or the layout was checked; if you did not open or render the document, say that pagination and visual layout are unchecked.

Markdown to Word: what converts

• Fixed Chinese report layout on A4: SimSun body with a two-character first-line indent, SimHei headings, 1.5 line spacing. No custom templates, table of contents, headers, footers or page numbers.
• Headings, paragraphs, lists (up to five levels), tables, quotes, code blocks and links stay editable. Tables keep Markdown column alignment and get content-based column widths. [text](#heading) links jump to the matching heading.
• LaTeX $...$, \(...\), $$...$$ and \[...\] become editable Word equations. Custom macros, \label/\ref/\tag, colors and manual spacing are not supported and keep their source with MATH_NOT_CONVERTED. Escape currency as \$ when a line could be read as a formula.
• [^label] footnotes become Word footnotes; repeated references reuse the first number. Inline ^[...] footnotes stay literal.
• Images: PNG, JPEG, GIF, BMP and SVG (SVG needs Word 2016 or later; older readers show a blank placeholder), from paths relative to the Markdown file's directory (never outside it) or data: URIs. Remote URLs, absolute paths and file: links are not embedded.
• Mermaid blocks render to PNG through the local Chrome, Edge or Chromium (--mermaid-scale, default 4). Unsupported syntax keeps the source with a visible notice and MERMAID_NOT_RENDERED.
• Raw HTML and task-list checkboxes stay as plain text. Ordered lists always start at 1; a start number such as 3. is not preserved.