inkos

name inkos description Story Creation and Translation AI Agent with Studio Chat, CLI, and TUI - use for long-form novels, short fiction, scripts, storyboards, interactive-film projects, open-world / branching play, fan fiction, spinoffs, style imitation, continuations, covers, and multilingual EPUB/PDF/TXT/Markdown translation. Includes Agent Skills, traceable research, governed context, persistent story state, multi-model routing, image services, and InkOS Studio. version 2.9.0 metadata {"openclaw":{"emoji":"📖","requires":{"bins":"[Truncated]","env":"[Truncated]"},"primaryEnv":"OPENAI_API_KEY","homepage":"https://github.com/Narcooo/inkos","install":["[Truncated]"]}} InkOS - Story Creation AI Agent InkOS is a story creation and multilingual translation AI agent for long-form novels, short fiction, scripts, storyboards, interactive-film projects, fan works, continuations, covers, open-world / branching interactive play, and long-document localization. Prefer the Studio Chat / action-surface workflow for natural-language requests: the model proposes or invokes typed actions, InkOS executes them, and completion is derived from real tool results and files, not from prose claims. Long-form writing still uses the chapter pipeline internally: Input governance : Architect / Planner / Composer preserve author intent, current focus, outline sections, and relevant truth files instead of injecting everything blindly. Writing : Writer produces prose with length governance, craft rules, and context selected for the current task. Settlement and review : Observer / Reflector update runtime state; Auditor checks continuity and quality; Reviser handles critical issues. The default write cycle keeps automatic repair conservative and leaves unresolved issues visible for human or agent follow-up. Truth files are persisted as schema-validated JSON ( story/state/*.json ) with markdown projections for human readability. SQLite temporal memory database ( story/memory.db ) enables relevance-based retrieval on Node 22+. Persisted story memory is isolated to its project and book, excludes credentials and unrelated files, and is never reused across projects unless the user explicitly imports material. Users can inspect or delete the owning book/project through Studio or CLI. v1.8.0 Mental Model Treat InkOS as a pi-agent-centered production harness, not a bag of prompt shortcuts or parallel pipelines. The model interprets requests and emits typed actions; the host owns confirmation, deterministic tools, state, atomic persistence, and artifact truth. Standard AgentSkills / OpenClaw SKILL.md packages provide medium-specific craft and static references, but they never grant execution permissions. Natural-language requests should go through Studio Chat / TUI / inkos interact whenever possible. Production workers for long fiction, short fiction, scripts, storyboards, interactive film, Play, and translation use the same harness contract while binding different built-in Skills. Share the architecture, not long-form-specific prompts. Pipelines and atomic CLI commands are deterministic host capabilities. Do not create a second natural-language router around them. Do not infer success from assistant prose. A book, short, cover, or play step is complete only when the corresponding tool result and files exist. Use short_fiction_run only for a standalone short-fiction package. Use generate_cover only for cover generation/regeneration. Use play_start / play_step for Open World or Branching Interactive sessions. Use script / storyboard / interactive-film tools only for production artifacts that should be saved and exported, not for casual discussion. Use the translation project workflow for EPUB, text-based PDF, TXT, or Markdown localization. Keep source and target languages, glossary, review report, and export format explicit; do not replace it with an ad hoc one-turn translation when the user wants a complete deliverable. Use research_web only when the user explicitly asks for external facts, market references, era/profession details, or worldbuilding research. Research reports are reference material and do not automatically mutate canon or prose. Use long-form chapter tools only for existing long-form books. Use narrative forecasts when the author wants to compare possible long-form directions before writing. A forecast is non-canonical planning material: selecting a branch may write selected-branch-plan.md , but it must not be described as changing prose, outlines, or canonical state. A running production task does not prevent ordinary discussion, but do not start another conflicting book mutation until that task reaches a terminal state. Agent Skills provide professional guidance and static references. They do not grant new file, network, image, or writing permissions by themselves. Story memory, archived material, and Skill references share the local FTS5 / BM25 retrieval kernel. Source files remain authoritative; retrieved excerpts should retain source pointers. Bind reusable imported material to a book with explicit intended uses instead of repeatedly injecting every source file in full. Chapter prose, state, hooks, and run snapshots should commit through the safe chapter workspace / atomic file-set boundary. Never report completion from a partially persisted run. Context is governed: protected facts and current intent should not be silently compressed away; compressible history may be summarized when the context budget is tight. Studio Chat can receive user-uploaded text / Markdown / image attachments. Text attachments are injected into the LLM context; image attachments require a vision-capable model. External materials can be archived and retrieved later with evidence traces instead of relying on ad hoc pasted context. Prompt packs are user-tunable in Studio Project Settings. Project overrides are saved under prompt/<pack>/<prompt>.md ; do not edit generated artifacts just to change system behavior. Long-form chapter revision from Chat passes the current user instruction into the reviser as a one-off brief. If the revision is not applied, inspect the returned gate metrics and remaining audit issues before claiming it was fixed. v1.7 added multilingual translation/localization, narrative forecasting, background production, import, configurable review gates, recoverable locks, material archives, and standard Agent Skills. v1.8 unifies production around the pi-agent harness, adds medium-specific built-in Skills, shared FTS5 / BM25 retrieval, book-bound references, safe chapter workspaces, cross-format run snapshots, and TUI confirmation/model controls. Still surface unresolved review or execution issues plainly instead of claiming they were fixed. When to Use InkOS English novel writing : Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set --lang en Chinese web novel writing : 5 built-in Chinese genres (xuanhuan, xianxia, urban, horror, other) Fan fiction : Create fanfic from source material with 4 modes (canon, au, ooc, cp) Batch chapter generation : Generate multiple chapters with consistent quality Import & continue : Import existing chapters from a text file, reverse-engineer truth files, and continue writing Style imitation : Analyze and adopt writing styles from reference texts Spinoff writing : Write prequels/sequels/spinoffs while maintaining parent canon Standalone short fiction : Generate a complete short-fiction package with outline, draft, review artifacts, synopsis, selling points, and optional cover image Cover generation : Generate or regenerate only a cover prompt and cover image from a title, synopsis, or visual direction without rerunning story writing Interactive worlds : Start Open World or Branching Interactive sessions with world contracts, character agents, inventory/evidence/relationship state, guided choices, free actions, and optional image generation Interactive-film projects : Create playable branch graphs, variables/flags, relationship state, endings, node images, and exportable interactive project packages Scripts and storyboards : Convert ideas, outlines, or prose into script/storyboard deliverables while preserving user format choices Long-document translation : Translate EPUB, text-based PDF, TXT, or Markdown by chapter and semantic segment, maintain terminology, review source and target side by side, and export TXT/Markdown/EPUB Agent Skills : Load standard AgentSkills/OpenClaw or project-local SKILL.md packages; let the Chat Agent invoke them from user intent, or force one with @skill-id Traceable web research : Create sourced Markdown reports for facts, era/profession details, markets, and worldbuilding references Quality auditing : Detect AI-generated content and perform 33-dimension quality checks Genre exploration : Explore trends and create custom genre rules Analytics : Track word count, audit pass rate, and issue distribution per book Initial Setup InkOS requires Node.js 22 or later. First Time Setup # Initialize a project directory (creates config structure) inkos init my-writing-project # Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API) # Prefer --api-key-env so the key never appears in shell history: export OPENAI_API_KEY=sk-xxx inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o # For compatible/proxy endpoints, use --provider custom and point ONLY to trusted endpoints: # inkos config set-global --provider custom --base-url https://your-trusted-proxy.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o Multi-Model Routing (Optional) # Assign different models to different agents — balance quality and cost inkos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY inkos config set-model auditor gpt-4o --provider openai inkos config show-models Agents without explicit overrides fall back to the global model. Provider setup tip When the user needs an aggregator provider, point them to Studio's service settings. InkOS includes kkaiapi and OpenRouter as optional aggregator choices. For kkaiapi, use: Chinese website: https://kkaiapi.com/ English website: https://en.kkaiapi.com/ Chinese API docs: https://kkaiapi.com/docs English API docs: https://en.kkaiapi.com/docs Chinese models/pricing: https://kkaiapi.com/models English models/pricing: https://en.kkaiapi.com/models View System Status # Check installation and configuration inkos doctor # View current config inkos status Common Workflows Workflow 1: Create a New Novel Initialize and create book : inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 # Or with a creative brief (your worldbuilding doc / ideas): inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md Genres: xuanhuan (cultivation), xianxia (immortal), urban (city), horror , other Returns a book-id for all subsequent operations Generate initial chapters (e.g., 5 chapters): inkos write next book-id --count 5 --words 3000 --context "young protagonist discovering powers" The write next command runs the full pipeline: draft → audit → revise --context provides guidance to the Architect and Writer agents Returns JSON with chapter details and quality metrics Review and approve chapters : inkos review list book-id inkos review approve-all book-id Export the book (supports txt, md, epub): inkos export book-id inkos export book-id --format epub Workflow 2: Continue Writing Existing Novel List your books : inkos book list Continue from last chapter : inkos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice" InkOS maintains structured runtime state, readable Markdown projections, control docs, and temporal memory for consistency If only one book exists, omit book-id for auto-detection Review and approve : inkos review approve-all Workflow 2.5: Shared Natural-Language Control (Recommended For OpenClaw) When InkOS is being driven by OpenClaw or another external agent, prefer the shared interaction executor instead of stitching together many ad-hoc CLI calls: inkos interact --json --message "continue the current book, but keep the pacing tighter" inkos interact --json --message "rewrite chapter 3" inkos interact --json --message "start an open-world detective game about a locked archive room" The current JSON payload contains: assistant response text interaction session id / session kind / active book id when bound Real completion still comes from tool results and files. Do not treat assistant prose alone as proof that a book, chapter, short, cover, or play step was created. Use this as the primary OpenClaw entry because it shares the same control layer as the project TUI. Workflow 2.6: Steering Chapter Focus Before Writing Use this when the user says things like "pull focus back to the mentor conflict", "pause the merchant guild subplot", or "change what the next chapter should prioritize". Update the book-level control docs when needed : Use update_author_intent to change the long-horizon identity of the book Use update_current_focus to change the next 1-3 chapters' focus Compile the next chapter intent : plan_chapter(bookId, guidance?) Generates story/runtime/chapter-XXXX.intent.md Use this to verify what the system thinks the next chapter should do Compose the actual runtime input package : compose_chapter(bookId, guidance?) Generates story/runtime/chapter-XXXX.context.json Generates story/runtime/chapter-XXXX.rule-stack.yaml Generates story/runtime/chapter-XXXX.trace.json Only then write : write_draft if the user wants intermediate review write_full_pipeline if they want the usual write → audit → revise flow Recommended orchestration: user asks to redirect focus update_current_focus plan_chapter compose_chapter inspect the resulting intent/paths write_draft or write_full_pipeline Workflow 2.7: Compare Long-Form Directions Before Writing Use a narrative forecast when the author wants to inspect several plausible futures without committing any of them to canon. Create isolated candidates from the current book state: inkos forecast create book-id --divergence "Does the protagonist reveal the evidence now?" --branches 3 --horizon 5 Compare the branch cards in Studio Chat, or inspect the saved comparison with inkos forecast show [book-id] <forecast-id> . Re-check the forecast before relying on it. Canon changes mark the forecast stale. Select one candidate with the Studio card or: inkos forecast select book-id forecast-id branch-2 Selection writes only story/runtime/narrative-forecasts/<forecast-id>/selected-branch-plan.md . It does not apply the plan to chapter prose, outlines, author intent, or canonical state. Any later application remains a separate explicit authoring action. Workflow 3: Import Existing Chapters & Continue Use this when you have an existing novel (or partial novel) and want InkOS to pick up where it left off. Import from a single text file (auto-splits by chapter headings): inkos import chapters book-id --from novel.txt Automatically splits by 第X章 pattern Custom split pattern: --split "Chapter\\s+\\d+" Import from a directory of separate chapter files: inkos import chapters book-id --from ./chapters/ Reads .md and .txt files in sorted order Resume interrupted import : inkos import chapters book-id --from novel.txt --resume-from 15 Continue writing from the imported chapters: inkos write next book-id --count 3 InkOS rebuilds structured state, chapter summaries, hooks, character relationships, readable projections, and a style guide from the imported chapters Generates a style guide from the existing text New chapters maintain consistency with imported content Workflow 4: Style Imitation Analyze reference text : inkos style analyze reference_text.txt Examines vocabulary, sentence structure, tone, pacing Import style to your book : inkos style import reference_text.txt book-id --name "Author Name" All future chapters adopt this style profile Style rules become part of the Reviser's audit criteria Workflow 5: Spinoff/Prequel Writing Import parent canon : inkos import canon spinoff-book-id --from parent-book-id Creates links to parent book's world state, characters, and events Reviser enforces canon consistency Continue spinoff : inkos write next spinoff-book-id --count 3 --context "alternate timeline after Chapter 20" Workflow 6: Fine-Grained Control (Draft → Audit → Revise) If you need separate control over each pipeline stage: Generate draft only : inkos draft book-id --words 3000 --context "protagonist escapes" --json Audit the chapter (33-dimension quality check): inkos audit book-id chapter-1 --json Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more Revise with specific mode : inkos revise book-id chapter-1 --mode polish --json Modes documented for agent use: polish (minor), spot-fix (targeted), rewrite (major), and rework (structure) Workflow 7: Monitor Platform Trends inkos radar scan Analyzes trending genres, tropes, and reader preferences Informs Architect recommendations for new books Workflow 8: Detect AI-Generated Content # Detect AIGC in a specific chapter inkos detect book-id # Deep scan all chapters inkos detect book-id --all Uses 11 deterministic rules (zero LLM cost) + optional LLM validation Returns detection confidence and problematic passages Workflow 9: View Analytics inkos analytics book-id --json # Shorthand alias inkos stats book-id --json Total chapters, word count, average words per chapter Audit pass rate and top issue categories Chapters with most issues, status distribution Token usage stats : total prompt/completion tokens, avg tokens per chapter, recent trend Workflow 10: Write an English Novel # Create an English LitRPG novel (language auto-detected from genre) inkos book create --title "The Last Delver" --genre litrpg --chapter-words 3000 # Or set language explicitly inkos book create --title "My Novel" --genre other --lang en # Set English as default for all projects inkos config set-global --lang en 10 English genres: litrpg, progression, isekai, cultivation, system-apocalypse, dungeon-core, romantasy, sci-fi, tower-climber, cozy Each genre has dedicated pacing rules, fatigue word lists (e.g., "delve", "tapestry", "testament"), and audit dimensions Use inkos genre list to see all available genres Workflow 11: Fan Fiction # Create a fanfic from source material inkos fanfic init --title "My Fanfic" --from source-novel.txt --mode canon # Modes: canon (faithful), au (alternate universe), ooc (out of character), cp (ship-focused) inkos fanfic init --title "What If" --from source.txt --mode au --genre other Imports and analyzes source material automatically Fanfic-specific audit dimensions and information boundary controls Ensures new content stays consistent with source canon (or deliberately diverges in au/ooc modes) Workflow 12: Edit Persistent Text Through Chat