Liandan / 炼丹

English · 简体中文

Liandan is an explicitly invoked Skill for Codex and Claude. It distills Office files, PDFs, Markdown, and related sources into auditable Markdown documents, reusable knowledge modules, or another Skill.

Liandan is not a command-line product. Users invoke $liandan in Codex or /liandan in Claude. The Python files under scripts/ are internal, deterministic helpers used by the Skill and by its installer.

Install

Requirements for the installer:

• Git
• Python 3.10 or newer
• An installed and authenticated Codex or Claude environment

Clone the repository and run the installer:

git clone https://github.com/gokeshenzhen/liandan.git
cd liandan
python3 scripts/install.py

The installer:

1. Detects existing ~/.codex and ~/.claude host directories.
2. Installs to ~/.codex/skills/liandan, ~/.claude/skills/liandan, or both, according to what was detected.
3. Runs the same dependency checks as doctor.py.
4. Shows missing Python packages and asks before installing them.
5. Runs the checks again and reports a readiness status, affected formats, and exact remediation steps.

If neither host directory exists, the installer does not create either one or install dependencies. It only reports diagnostics and tells the user to install a host first or install the Skill manually. Explicit --platform and --deps-only options still override automatic detection.

For unattended installation of missing Python packages:

python3 scripts/install.py --yes

LibreOffice is an optional conversion fallback for legacy or special Office files. It is never installed by default. To explicitly authorize the installer to propose and run the detected operating-system package command:

python3 scripts/install.py --install-system
python3 scripts/install.py --install-system --yes

--yes by itself installs only Python packages and never invokes sudo or a system package manager.

Override detection and explicitly install for only one host:

python3 scripts/install.py --platform codex
python3 scripts/install.py --platform claude

Preview without changing links or installing packages:

python3 scripts/install.py --check

The installer only replaces an existing symlink when --force is provided. It never removes or overwrites a real directory at either installation path.

Restart Codex or Claude if the newly installed Skill does not appear immediately.

Use

Codex examples:

$liandan docs convert ./manuals into auditable Markdown
$liandan knowledge distill ./sources into reusable knowledge modules
$liandan skill distill ./sources into a shared Codex/Claude skill

Claude examples:

/liandan docs convert ./manuals into auditable Markdown
/liandan knowledge distill ./sources into reusable knowledge modules

Liandan intentionally does not trigger for generic document conversion or generic skill creation requests that do not name liandan or 炼丹.

Workflow

explicit invocation
  -> select docs / knowledge-module / skill
  -> diagnose the current environment
  -> inventory and hash sources
  -> prepare auditable Markdown
  -> extract facts when required
  -> plan content-derived modules and topics for Skills
  -> generate deterministic lossless source packs
  -> synthesize by topic, directly, or with lossless shards
  -> write final outputs
  -> evaluate global, per-topic, and cross-topic coverage
  -> blind forward-test generated Skills against hidden concept/exact oracles

All run state is stored under .liandan/runs/<timestamp>/. Semantic compression is disabled by default. When inputs exceed the effective context budget, Liandan prefers lossless sharding and multi-file outputs. Worker tasks carry cost and dependency metadata; manifest.py resume emits bounded, restartable batches and reconcile checkpoints completed outputs from disk.

For a multi-source Skill, Liandan extracts each source independently, then creates and validates knowledge-plan.json. The plan derives the smallest useful modules, triggers, topic leaves, source mappings, conflicts, products, and versions from the corpus. It does not impose a fixed tool-specific/, shared/, or domain hierarchy.

Focused modules remain one shallow reference. Rich modules use progressive disclosure: a lean module index routes to flat-named topic leaves under the same references/ directory. If the corpus contains incompatible products, Liandan recommends separate runs and pauses before combining them. Scenario evaluation must cover every planned topic and at least one cross-topic workflow. Generated Skills also run blind forward tasks whose workers cannot see the hidden grading patterns.

Installer versus doctor

The scripts have separate responsibilities and share the same dependency definitions:

• scripts/install.py is a setup tool. It creates the Codex/Claude Skill links, installs missing Python packages after confirmation, and can optionally install LibreOffice with explicit --install-system authorization.
• scripts/doctor.py is a read-only diagnostic tool. It can be rerun at any time, groups dependencies by format capability, and never changes the environment.

Run doctor directly when troubleshooting:

python3 scripts/doctor.py --runtime codex
python3 scripts/doctor.py --runtime claude

To install only missing Python dependencies without touching Skill links:

python3 scripts/install.py --deps-only --runtime codex --yes

Dependencies

The file inventory, manifest, lossless sharding, and structural validation helpers use only the Python standard library. Broader document extraction uses optional packages detected by doctor:

• markitdown[all]
• pymupdf
• pdfplumber
• Pillow
• python-docx
• openpyxl
• python-pptx
• olefile
• extract-msg

LibreOffice or soffice is the only optional system-level dependency. It provides PDF-conversion fallback for legacy or special Office formats such as .doc, .xls, .ppt, .vsd, .mpp, and .pub. Modern OOXML files and PDFs use the Python extraction stack directly. Image text recovery is performed by the active Codex or Claude runtime, so Tesseract is not required.

The final diagnostic has three outcomes:

• READY: all declared format capabilities are available.
• READY WITH REDUCED FORMAT COVERAGE: Liandan is usable, but only the listed formats or fallbacks are unavailable. Install the dependency only if the affected formats occur in your inputs.
• NOT READY: a blocking requirement such as Python 3.10+ or a valid Skill installation is missing. Follow the printed action and rerun python3 scripts/install.py --check.

Internal pipeline scripts

These are implementation tools used by the Skill, not a user-facing Liandan CLI:

• scan.py: inventory, classify, hash, and report every input.
• prep.py: produce prepared Markdown, tables, extracted assets, attachments, and same-runtime vision tasks.
• vision_tasks.py: synchronize pending/completed figure-transcription state.
• finalize_docs.py: assemble docs outputs, completed vision transcriptions, assets, and the audit index.
• extract.py: generate isolated extraction-worker task files and expected outputs.
• knowledge_plan.py: create and validate content-derived module, topic, scope, conflict, and source-mapping plans.
• synthesize.py: generate direct, topic-aware, progressive-disclosure, or lossless-sharded synthesis tasks.
• source_packs.py: deterministically preserve complete extraction records in topic-aware, shallow lossless packs.
• shard.py: split oversized Markdown with byte-for-byte reconstruction checks.
• loss_probe.py: measure exact high-value atom preservation.
• scenario_eval.py: create and validate independent scenario-evaluation artifacts.
• forward_benchmark.py: emit oracle-free Skill tasks and deterministically score concept/exact patterns, including compatible external benchmarks.
• publish_skill.py: publish a clean generated Skill visibly and optionally install a copied, self-contained version.
• manifest.py: reconcile outputs, resume dependency-ready cost-bounded batches, and atomically finalize quality-passed runs.

Codex or Claude executes the reasoning tasks described by these files. The scripts never call a different model runtime.

Generated Skill delivery

Successful Skill runs keep their complete audit trail under .liandan/runs/<timestamp>/, then publish the user-facing artifact to:

generated-skills/<skill-name>/

The visible published copy can be reviewed, committed, or distributed without exposing intermediate run files. Editor swap files, caches, hidden files, and unrelated top-level files are excluded during publishing.

When installation was explicitly requested, Liandan can complete publishing and installation in one internal step. Generated Skills are copied by default so they remain usable if the source project is moved or deleted:

Codex:  ~/.codex/skills/<skill-name>/
Claude: ~/.claude/skills/<skill-name>/

If installation was not requested, Liandan publishes first and asks before changing either personal Skill directory. A completed, quality-passed run can resume directly at this delivery stage without repeating document processing or evaluation.

Update or remove

Because both hosts use symlinks, update the shared checkout once:

git pull

Remove the personal installation without deleting the checkout:

rm ~/.codex/skills/liandan
rm ~/.claude/skills/liandan

Review the paths before removing them, especially if they were installed manually rather than by scripts/install.py.

License

Liandan is released under the MIT License.