ArticleWriter

ArticleWriter for Obsidian

Chinese version: README_ZN.md

⚠️ Disclosures & Security Statement

Network requests. This plugin performs no network activity except LLM chat. All outbound traffic goes exclusively through the official openai SDK to the OpenAI-compatible endpoint that you configure yourself in settings (a local server such as Ollama / LM Studio / llama.cpp, or a provider API like DeepSeek or Qwen DashScope). At runtime the plugin makes exactly three kinds of calls — non-streaming and streaming chat completions, plus one optional GET /models issued only when you run the LLM connection test to confirm your endpoint works; any additional request-related call sites flagged by scanners belong to the bundled SDK's generic HTTP layer and are not used elsewhere by this plugin. There is no telemetry, no analytics, no update checking, and no connection to any author-operated server. Your API key is entered by you in the settings panel, stored locally inside your vault with the rest of the plugin settings, and transmitted only as an authentication header to the endpoint you chose; when left empty (the normal case for local servers) a fixed placeholder value (local-no-auth) stands in its place, so no real secret ever leaves your machine.

Base64 usage (atob / btoa). The plugin's own source code contains zero base64 encode/decode calls. Every occurrence present in the shipped bundle originates from third-party libraries that esbuild bundles: the yaml parser (its standard handler for YAML !!binary tags) and the openai SDK (generic base64 ↔ binary-buffer conversion helpers). They perform ordinary data-format conversions and are not used to obfuscate API keys, hide URLs, or mask code payloads. Nothing in the build is minified or obfuscated — the complete human-readable source is published in the repository; please audit it directly if you have concerns.

Vault Enumeration Disclosure

This plugin inspects file structures inside your vault through Obsidian's standard app.vault APIs, in exactly two scopes:

• Purpose — vault-wide path listing (two small UI pickers): (a) the folder picker shown on first use / when switching the working directory (work_dir) lists existing folders so you can fuzzy-search where your manuscripts live; this walk starts at the vault root but is deliberately bounded — it descends only 3 levels deep, stops after 500 entries, and skips hidden directories such as .obsidian/; (b) the dockable chat panel's @reference candidate list calls vault.getFiles() when rendering so that any document in your vault can be quoted into an LLM prompt with one keystroke. Both list paths only — no content is read at either point. A file's text is loaded only after you act on it: picking a folder merely sets the scope for later local operations, and referencing a file adds its content to the explicit request sent to the model endpoint you configured yourself (see the Network-requests note above).
• Purpose — working-directory-scoped operations: Everything else (building the story status tree, listing volumes/chapters, counting words per chapter/book, and loading outline / world-building / character / scene documents into writing prompts) operates exclusively inside the work folder you select on first use (work_dir). Files outside that folder are never opened or scanned by these features.
• Privacy Assurance: All enumeration runs entirely locally and in-memory on your machine. File paths and contents are processed strictly on-device and are never uploaded, indexed remotely, leaked, or shared with any external server — except for the deliberate LLM requests described in the Network-requests note that you trigger yourself.
• Summary for reviewers: Vault-wide listing happens in exactly two UI pickers and exposes paths only (the folder picker even caps at 3 levels deep / 500 entries); all other file access stays inside the user-selected working directory, everything runs locally in-memory, and nothing leaves the machine except LLM requests you explicitly send to your own configured endpoint.

Overview

ArticleWriter turns your vault into an AI-assisted novel workshop. It organizes each story as a folder of plain Markdown files (state doc, outline, world-building, characters, scenes, foreshadowing notes and one folder per chapter) and adds LLM-powered writing commands on top: write / continue / rewrite / polish chapters, strip AI-sounding phrasing, review from a global perspective, plus a dockable chat panel that can quote any vault file via @references. All data stays local; no external services are required beyond the OpenAI-compatible model endpoint you configure yourself.

Nothing depends on external services — every operation works on the Markdown documents inside your vault through Obsidian's built-in Vault / Workspace APIs.

Data Layout

<novel root>/<book title>/
├── 故事状态.md              # Obsidian "file properties" style: YAML frontmatter holds the version-2 runtime state (title/genre/current volume·scene·chapter/per-chapter metadata); body is free-form notes; legacy story_state.json is auto-migrated with a backup in _backup/ on first save
├── WRITING_GUIDE.md         # Story-level writing guide (the user-level one of the same name lives under work_dir)
├── 写作指南汇总.md           # Per-book merged guide (auto-generated, change-detected via hash); the only writing-guide content injected into LLM prompts
├── 大纲.md                  # Master outline
├── 世界观.md                # World-building template
├── 卷.md                    # Volumes (grouping container)
├── 伏笔.md                  # Foreshadowing log
├── 笔记.md                  # Notes
└── 第NN章-<标题>/           # One folder per chapter
    ├── NN-<标题>.md          # Chapter body (file prefix is the numeric chapter number)
    ├── NN-<标题>-大纲.md      # Chapter outline
    ├── NN-<标题>-人物.md      # Characters
    ├── NN-<标题>-人物关系.md  # Character relations
    ├── NN-<标题>-场景.md      # Scenes
    └── NN-<标题>-信息.md      # Chapter info

Volume-level template docs are named after the volume too (e.g. <卷名>-大纲.md, <卷名>-人物.md, <卷名>-人物关系.md, <卷名>-场景.md).

Missing documents are auto-created as "HTML comment example" templates when creating a new book/chapter; existing files are skipped and never overwrite user content. All file names are normalized through safeFilename(). Legacy documents (bare names like 章节.md/卷大纲.md, or older prefix forms like 初见-章节.md) are auto-detected when switching books and can be batch-migrated to the new names (rename only, content untouched).

Commands

Search the command palette for "ArticleWriter" or the Chinese description.

Workflow (work_dir)

1. The first time you use any ArticleWriter command, a work directory picker pops up automatically — choose an existing vault folder as your work_dir for novel writing. A 《使用说明.md》 usage guide is then dropped into that folder automatically (editable; re-created via the "Generate usage guide" command only when missing or empty).
2. From then on, creating stories, creating chapters, opening documents, switching chapters, word counts — everything operates under work_dir; each story is one subfolder of work_dir.
3. To change directories, use the "Select work directory" command or the "Re-select…" button on the settings page (switching clears the remembered last story).
4. With multiple books, commands show a story picker and remember your last choice.

Settings

• Work directory (work_dir): the folder where novels live; initialized by the automatic picker on first use, can be changed/re-selected manually.
• Auto-open document after creation: opens 大纲.md when a book is created, 章节.md when a chapter is created.

Build & Install

npm install
npm run build        # outputs main.js + manifest.json + styles.css into release/

Development mode (watch): npm run dev.

Manual install: copy main.js, manifest.json, styles.css from release/ to <your vault>/.obsidian/plugins/articlewriter/, then enable the plugin in Obsidian under "Settings → Community plugins".