agentleFS
DavidLam-ossDavidLam-oss/obsidian-wechat-converter/AGENTS.md

obsidian-wechat-converter

AGENTS.md358 starsChanged 24 days agoMITView on GitHub

This file provides guidance to Codex when working with code in this repository.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository4 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

22 rules. About 0 are common, 9 are distinctive, and 13 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When drafting replies or documentation intended for Chinese audiences, ensure natural, native-level phrasing.

    line 7
  2. Distinctive:

    Use TEST.md for general rendering checks.

    line 30
  3. Very specific:

    Use TEST_MATH.md when touching formula rendering or math upload behavior.

    line 31
  4. Very specific:

    Use OBSIDIAN_SCAN_CHECKLIST.md before merging feature branches or preparing a release candidate.

    line 32
  5. Very specific:

    Do not hand-edit main.js; rebuild from source instead.

    line 39
  6. Very specific:

    If you touch runtime code that is embedded or eval-loaded, always consider whether npm run generate:embedded is required before testing.

    line 91
  7. Very specific:

    Do not run file-writing build/generate/release commands in parallel with git status, git diff, or staging.

    line 92
  8. Distinctive:

    Keep an eye on WeChat API quota and media-limit errors.

    line 98
  9. Distinctive:

    When editing eval-loaded/global-exported code, preserve safe global export patterns and re-entrancy protections.

    line 102
  10. Distinctive:

    Prefer Obsidian-native controls and simple layout techniques over brittle CSS tricks.

    line 106
  11. Distinctive:

    Keep copy/sync behavior aligned with preview behavior as much as possible.

    line 107
  12. Distinctive:

    Add tests for core logic changes, especially regex-heavy transformations, sanitizer changes, sync failure handling, path cleanup rules, or …

    line 114
  13. Distinctive:

    When changing output HTML, consider both automated tests and manual visual verification because small markup changes can regress WeChat …

    line 115
  14. Very specific:

    Before merging feature work that could affect Obsidian review results, run npm run review:guard.

    line 116
  15. Very specific:

    Avoid introducing new scan-triggering APIs: prefer DOM helpers over innerHTML, setCssStyles(...) over static element.style.*, Obsidian …

    line 118
  16. Very specific:

    Avoid production globalThis.

    line 119
  17. Very specific:

    Avoid adding stylesheet !important.

    line 120
  18. Distinctive:

    If a scan-sensitive API is intentionally required for compatibility, keep the usage narrow, document the reason inline, and add regression …

    line 121
  19. Very specific:

    Keep the entry file input.js lightweight, focused only on plugin lifecycle, view wiring, settings UI, and top-level sync actions.

    line 126
  20. Very specific:

    Place markdown-it rules and conversion core in converter.js.

    line 127
  21. Very specific:

    Place styling rules in themes/apple-theme.js.

    line 128
  22. Very specific:

    Place preprocessing, path resolution, and cleaner logic in their respective modules under services/.

    line 129

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

This file provides guidance to Codex when working with code in this repository.

Language Preferences

  • Detect the language of the user's prompt (English or Chinese). Always reply in the same language unless explicitly asked otherwise.
  • When drafting replies or documentation intended for Chinese audiences, ensure natural, native-level phrasing.

Project Summary

  • This is an Obsidian plugin that converts Markdown notes into WeChat Official Account article HTML.
  • The core user workflow is: open the converter panel, preview the rendered article live, copy rich HTML into the WeChat editor, and optionally sync directly to the WeChat draft box.
  • The plugin is aimed at creators who publish from Obsidian to WeChat and care about fidelity for headings, code blocks, math, callouts, tables, local images, and article metadata.

Commands

  • Install dependencies: npm install
  • Generate embedded runtime bundles: npm run generate:embedded
  • Check embedded runtime bundles are up to date: npm run check:embedded
  • Build for production: npm run build
  • Start development watcher: npm run dev
  • Run unit tests: npm test
  • Run coverage: npm run test:coverage
  • Run fast Obsidian scan-risk guard: npm run scan:guard
  • Run Obsidian scan readiness guard: npm run review:guard
  • Check generated build artifacts: npm run check:build-artifacts
  • Release dry run: npm run release:dryrun
  • Release validation: npm run release:validate

Testing Expectations

  • This project still relies on manual visual testing for end-to-end rendering quality and WeChat paste/sync behavior.
  • Use TEST.md for general rendering checks.
  • Use TEST_MATH.md when touching formula rendering or math upload behavior.
  • Use OBSIDIAN_SCAN_CHECKLIST.md before merging feature branches or preparing a release candidate.
  • The repository also has a substantial Vitest suite under tests. For logic changes, especially around rendering, sanitization, path resolution, sync flow, or error handling, add or update unit tests unless the change is purely cosmetic.

Architecture & Structure

  • Entry source: input.js It contains plugin lifecycle, view wiring, settings UI, preview panel logic, and top-level sync actions.
  • Generated runtime artifact: main.js Do not hand-edit main.js; rebuild from source instead.
  • Markdown conversion core: converter.js Handles markdown-it based conversion, HTML sanitization, callouts, image rendering, code block rendering, and WeChat-friendly output shaping.
  • Theme system: themes/apple-theme.js There is one theme module with three built-in presets exposed in the UI:
    • github -> 简约
    • wechat -> 经典
    • serif -> 优雅
  • Service layer: services/ The codebase has evolved beyond a single converter file. Important modules include:
    • render-pipeline.js: creates the render pipeline used by the view.
    • dependency-loader.js: loads embedded runtime dependencies.
    • native-renderer.js: native rendering path.
    • obsidian-triplet-renderer.js and obsidian-triplet-serializer.js: renderer/serializer helpers used by the newer pipeline.
    • markdown-source.js: resolves the active markdown source.
    • path-utils.js: vault/path helpers.
    • wechat-media.js: image and math asset processing for WeChat.
    • wechat-html-cleaner.js: HTML cleanup for draft sync.
    • wechat-sync.js and sync-context.js: draft sync orchestration and user-facing sync messaging.
  • Generated embedded dependency snapshot: services/generated-embedded-deps.js This is generated. If you change embedded runtime sources such as converter.js or themes/apple-theme.js, regenerate it before building or testing.
  • Math bundle: lib/mathjax-plugin.js Built via scripts/generate-embedded-deps.mjs and embedded into the runtime.

Current Product Behavior To Keep In Mind

  • Live preview is a first-class feature; the plugin is expected to feel close to WYSIWYG for WeChat publishing.
  • The plugin supports copy-to-editor and direct sync to WeChat drafts.
  • WeChat draft sync supports multiple accounts, frontmatter-aware cover/excerpt defaults, optional cleanup of a configured output directory after successful sync, and optional proxying through a Cloudflare Worker.
  • Local image handling is important: wiki links, relative paths, absolute paths, GIF handling, avatar uploads, and cover selection all matter.
  • Chinese punctuation normalization only affects rendered output, copy output, and sync output. It must not mutate the source Markdown note.
  • The codebase has moved to a native-only rendering direction; be careful around old legacy/parity switches and prefer current pipeline behavior.

Development Notes

  • Runtime environment: Obsidian plugin running in Electron / Node-style CommonJS.
  • Languages in repo: mostly JavaScript plus .mjs build scripts and test helpers.
  • External dependencies: obsidian, electron, and CodeMirror-related APIs are provided by the Obsidian app/runtime.
  • Security-sensitive areas:
    • HTML sanitization
    • link validation
    • proxy URL validation
    • file/path cleanup after sync
  • Performance-sensitive areas:
    • preview refresh
    • image processing
    • math conversion
    • WeChat upload concurrency and retry behavior

Best Practices & Lessons Learned

1. Build Artifacts

  • input.js is the source of truth for the plugin entry; rebuild after changing it.
  • main.js and services/generated-embedded-deps.js are generated artifacts and should stay in sync with source edits.
  • If you touch runtime code that is embedded or eval-loaded, always consider whether npm run generate:embedded is required before testing.
  • Do not run file-writing build/generate/release commands in parallel with git status, git diff, or staging. Wait for the writer to finish, then inspect the final tree; otherwise generated artifacts such as main.js can appear as transient mid-build changes.

2. WeChat Compatibility

  • WeChat strips <style> tags and most class-based styling. Rendered article output must remain robust with inline styles and self-contained markup.
  • Math support is compatibility-sensitive. Complex formulas may need SVG/PNG processing paths depending on the sync target.
  • Non-math SVG content such as diagrams should not be accidentally recolored or mangled by math-specific cleanup.
  • Keep an eye on WeChat API quota and media-limit errors. The circuit-breaker behavior is intentional and user-protective.

3. Dynamic Loading

  • Heavy or embedded features are loaded indirectly. Avoid assumptions that typical browser globals behave exactly like a normal webpage environment.
  • When editing eval-loaded/global-exported code, preserve safe global export patterns and re-entrancy protections.

4. UX Consistency

  • Preserve the fast live-preview workflow.
  • Prefer Obsidian-native controls and simple layout techniques over brittle CSS tricks.
  • Keep copy/sync behavior aligned with preview behavior as much as possible.
  • For multi-document or multi-account workflows, preserve existing state management patterns unless there is a clear bug.
  • Modal / Portal Scope & Form Controls:
    • Modal 弹窗直接挂载于 document.body 顶层,脱离插件侧栏容器(.apple-converter-container),绝不要假定存在全局通用的 .hidden 样式(Obsidian 官方默认未定义全局 .hidden,某些第三方社区主题才会隐式提供)。
    • 对于隐式辅助控件(例如触发文件选择的 <input type="file">),严禁仅依赖 cls: 'hidden';必须通过专属类名、HTML 原生 hidden: 'true' 属性以及 setCssStyles({ display: 'none' }) 显式兜底隐藏,避免在纯净 Vault / 默认主题下原生态裸露。

5. Quality Bar

  • Add tests for core logic changes, especially regex-heavy transformations, sanitizer changes, sync failure handling, path cleanup rules, or rendering edge cases.
  • When changing output HTML, consider both automated tests and manual visual verification because small markup changes can regress WeChat compatibility.
  • Before merging feature work that could affect Obsidian review results, run npm run review:guard.
  • CI/CD must use the same npm run review:guard gatekeeper so local, PR, and release checks stay aligned.
  • Avoid introducing new scan-triggering APIs: prefer DOM helpers over innerHTML, setCssStyles(...) over static element.style.*, Obsidian Modal over confirm(), and local parsing over fetch(data:).
  • Avoid production globalThis; use window or services/dom-utils.js active-window helpers. Timers should use window.setTimeout() / window.clearTimeout(), and dynamic browser APIs should not be returned as .call() / .bind() wrappers.
  • Avoid adding stylesheet !important; prefer stronger selectors, CSS variables, or narrow rendered-output compatibility styles covered by tests.
  • If a scan-sensitive API is intentionally required for compatibility, keep the usage narrow, document the reason inline, and add regression tests around the behavior.
  • During feature development, use npm run scan:guard for quick feedback before running the full npm run review:guard.

6. Modular Architecture

  • Adhere to the refactored modular architecture. Do not pile rendering rules or core logic inside the entry file input.js.
  • Keep the entry file input.js lightweight, focused only on plugin lifecycle, view wiring, settings UI, and top-level sync actions.
  • Place markdown-it rules and conversion core in converter.js.
  • Place styling rules in themes/apple-theme.js.
  • Place preprocessing, path resolution, and cleaner logic in their respective modules under services/.

Release

发布新版本时,使用 /project-release skill 查看完整流程。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.