@qihuang02/world-book-mcp 0.0.5 → 0.0.6

package/README.md

@@ -1,192 +1,152 @@
 # world-book-mcp
 
-`world-book-mcp` is an MCP server built with Node.js and TypeScript. It manages a `.worldbook/` drafting workspace and helps AI validate, patch, and export SillyTavern-compatible World Book JSON, basic `chara_card_v3` character card JSON, and optional MVU/ZOD, HTML beautification, and EJS dynamic content assets. Source reading, web search, and fact extraction are handled by the host AI in conversation; this server stores structured project state, draft entries, configurations, and exported JSON.
+An MCP server for creating, modifying, validating, and exporting SillyTavern World Book JSON and `chara_card_v3` character card JSON.
 
-## Installation
+## Architecture
 
-### JSON format
+The project consists of two layers:
 
-```json
-{
-  "type": "stdio",
-  "command": "npx",
-  "args": [
-    "-y",
-    "@qihuang02/world-book-mcp"
-  ]
-}
+```text
+┌─────────────────────────────────────────────────────────┐
+│  Skill Layer (skill/world-book-mcp-skill/)              │
+│  Creative methodology: guides AI on worldbuilding,      │
+│  character design, style extraction, derivative         │
+│  extraction from novels/web resources, first messages   │
+│  Output: high-quality structured content                │
+└────────────────────────────┬────────────────────────────┘
+                             │ AI calls MCP tools to write drafts
+┌────────────────────────────▼────────────────────────────┐
+│  MCP Layer (src/)                                       │
+│  Engineering orchestrator: manages draft slices,        │
+│  validates consistency, builds MVU/EJS/HTML assets,     │
+│  exports SillyTavern JSON                              │
+│  Output: ready-to-import SillyTavern JSON files        │
+└─────────────────────────────────────────────────────────┘
 ```
 
-### Claude Code format
-
-```json
-"mcpServers": {
-  "world-book-mcp": {
-    "type": "stdio",
-    "command": "cmd",
-    "args": [
-      "/c",
-      "npx",
-      "-y",
-      "@qihuang02/world-book-mcp"
-    ]
-  }
-}
+## Main Workflow
+
+```text
+User request
+→ init_project
+→ update_plan (record requirements, decisions, export target)
+→ create_draft_slice / update_draft_field(s) (write content)
+→ validate_draft (check consistency)
+→ build_assets (optional, preview MVU/EJS/HTML assets)
+→ review_project / check_delivery (pre-export review)
+→ generate_json (export)
 ```
 
-### Codex format
+## Skill Layer — Creative Methodology
 
-```toml
-[mcp_servers.world-book-mcp]
-type = "stdio"
-command = "npx"
-args = ["-y", "@qihuang02/world-book-mcp"]
-# startup_timeout_sec = 60000.0
-```
+`skill/world-book-mcp-skill/` contains reference documents that guide AI content creation:
 
-## Current Capabilities
+| Document | Content |
+|----------|---------|
+| `worldbuilding-methodology.md` | World design: A/B/C type classification, dimension selection, zero-degree writing |
+| `character-creation.md` | Character design: XML+YAML structure, personality palette, tri-faceted method |
+| `derivative-extraction.md` | Derivative extraction: systematic extraction from novels/web resources |
+| `style-extraction-guide.md` | Style extraction: analyze source material and produce style/forbidden-word entries |
+| `rephrase-guide.md` | Rephrase: author's deep annotations to prevent AI misinterpretation |
+| `content-rules.md` | Content rules: forbidden words, specificity, fourth wall |
+| `first-message.md` | First message rules: hooks, plot momentum, interaction points |
+| `composition.md` | Entry composition: blue/green light, position, order |
+| `requirements.md` | Requirements alignment: user decision flow |
+| `tool-reference.md` | MCP tool parameter quick reference |
 
-The current version supports:
+## MCP Layer — Engineering Orchestration
 
-- Explicitly initializing a project, suitable for first-time use in an empty directory.
-- Creating information extraction outlines.
-- Submitting structured extraction results prepared by the host AI.
-- Creating explicit World Book entry plans from caller-provided card type, characters, world sections, items, scenes, and events.
-- Scanning forbidden terms and common writing issues.
-- Creating `.worldbook/draft/*.json` slice templates first, then updating them field by field, confirming completeness, and merging them into exported JSON.
-- Exporting standalone SillyTavern World Book JSON.
-- Importing existing World Book JSON by slicing it into `.worldbook/draft/*.json`, then applying safe patches / merged exports.
-- Generating basic character card JSON that can embed the project World Book draft; when exporting a character card, the basic settings and personality settings of the same character are merged into the same embedded World Book entry.
-- MVU/ZOD configuration templates, validation, and asset building, with automatic merging into character card JSON.
-- HTML beautification configuration templates, validation, and asset building, with automatic merging into character card JSON.
-- EJS dynamic content configuration templates, validation, and entry building, with automatic merging into the embedded World Book of a character card.
-- Querying exported World Book JSON and character card JSON.
-- Importing existing character card JSON, slicing the embedded World Book into draft entries, and applying patches to profile fields or embedded World Book entries.
+### Workspace Structure
 
-Not supported yet:
-- Built-in web search.
+`init_project` creates:
 
-## `.worldbook/` Workspace
+```text
+.worldbook/
+  project.json
+  plan.md
+  logs/
+  draft/
+    worldbook/
+    character-card/
+    mvu/
+    html/
+    ejs/
+    style/
+    chapter/
+```
 
-The primary role of `init_project` is to create or reuse the single MCP workspace project in the current project directory. Project metadata is stored only in `.worldbook/project.json`, and split draft entries are stored in `.worldbook/draft/`; the old `output/projects` storage path is no longer created or read:
+It scans existing SillyTavern JSON files in the current directory and slices World Book entries, character card profile, greetings, MVU, HTML, EJS, and regex assets into draft files.
+
+### Core Tools
+
+| Tool | Purpose |
+|------|---------|
+| `init_project` | Initialize `.worldbook/`, scan and slice existing Tavern JSON |
+| `update_plan` | Write requirements, decisions, export target to `.worldbook/plan.md` |
+| `create_draft_slice` | Create a draft slice |
+| `update_draft_field` / `update_draft_fields` | Update draft fields |
+| `validate_draft` | Validate World Book, character card, MVU, EJS, HTML drafts |
+| `build_assets` | Preview assets that will be merged into a character card |
+| `review_project` / `check_delivery` | Pre-export review and blocking checks |
+| `generate_json` | Export World Book JSON, character card JSON, or both |
+| `query_json` | Query exported JSON |
+
+### MVU Variable Tools
+
+| Tool | Purpose |
+|------|---------|
+| `list_mvu_variables` | List variables in the schema |
+| `upsert_mvu_variable` | Add or modify a variable |
+| `remove_mvu_variable` | Remove a variable |
+| `rewrite_mvu_variables` | Batch rewrite variables |
+
+### Review & Lint Tools
+
+| Tool | Purpose |
+|------|---------|
+| `lint_worldbook_content` | Run forbidden-word/specificity lint on text |
+| `lint_project_content` | Run lint on the entire project |
+| `create_writing_optimization_report` | Generate a writing optimization report |
+
+### Draft Types
+
+- `worldbook_entry` — World Book entry
+- `character_profile` — Character card profile
+- `character_greetings` — First messages / alternate greetings
+- `mvu_schema` — MVU ZOD schema
+- `mvu_update_rules` — MVU initvar + update_rules
+- `html_statusbar` — HTML status bar
+- `html_regex` — HTML regex scripts
+- `ejs_entry` — EJS dynamic entries
+- `style_profile` — Style configuration
+- `chapter_outline` — Chapter outline
+
+## Modifying Existing JSON
 
 ```text
-.
-├─ .worldbook/
-│  ├─ project.json          # project metadata; draft body is split out
-│  └─ draft/
-│     ├─ 新墟城.json
-│     ├─ 角色B_基础设定.json
-│     └─ 角色B_性格.json
-└─ <exported world book or character card>.json
+init_project(scan_existing=true, import_strategy="auto")
+→ list_draft_slices / get_draft_slice
+→ update_plan
+→ update_draft_field(s)
+→ validate_draft
+→ generate_json
 ```
 
-`create_worldbook_draft_entry` / `create_worldbook_draft_entries` first create slice templates at `.worldbook/draft/<safe-comment>.json`; then `update_worldbook_draft_field` / `update_worldbook_draft_fields` fill them field by field. Split files store MCP draft entries, not final SillyTavern entries:
-
-```json
-{
-  "comment": "新墟城",
-  "entryType": "world_summary",
-  "keys": ["新墟", "废墟都市", "避难城"],
-  "secondaryKeys": [],
-  "content": "...",
-  "constant": true,
-  "position": "before_char",
-  "order": 1,
-  "enabled": true,
-  "preventRecursion": true,
-  "excludeRecursion": true
-}
+## Logs
+
+MCP silently records tool-call summaries in:
+
+```text
+.worldbook/logs/latest.jsonl
+.worldbook/logs/<session>.jsonl
 ```
 
-Validation, review, lint, World Book export, and character card export merge `.worldbook/draft/*.json`; split draft files are the draft source of truth. `.worldbook/draft/` is the long-lived workspace: `generate_worldbook_json` / `generate_character_card_json` do not clear drafts after export, and `apply_worldbook_patch` / `apply_character_card_patch` retain the updated split draft entries after merging into exported JSON. By default, exports are written to `<name>.json` in the current working directory. Relative and absolute output paths must stay inside the current working directory; out-of-bound writes are rejected.
-
-`init_project` also scans one level of `*.json` files in the current working directory. If no SillyTavern World Book or `chara_card_v3` JSON exists, it safely creates a root template JSON. If a Tavern-format JSON already exists, it does not create another template and never overwrites existing JSON files. The returned `root_template` field reports whether a template was created, its path, or the existing files that caused creation to be skipped. `kind=worldbook` creates a standalone World Book template; `kind=character_card` and `kind=mixed` create a `chara_card_v3` template, with `mixed` explicitly meaning a character card plus an empty embedded World Book.
-
-## Patches, Revisions, and Concurrency
-
-Writes for the same `project_id` are serialized inside the MCP process and return an incremented `revision`. Tools that accept `expected_revision` can use it for concurrency control: if a caller writes based on a stale revision, the tool returns a `project revision conflict` error.
-
-`apply_worldbook_patch` / `apply_character_card_patch` use the current project draft as input, write the exported JSON file, and update project state together; on success, the updated `.worldbook/draft/*.json` files are retained. The implementation writes a temp file, replaces the target file, then updates the project; if the project update fails, it best-effort restores the previous exported file or removes the newly written target. When a patch returns `ok=false` or throws a revision conflict, reload the project before retrying.
-
-Patch `match.uid` first matches the `sourceUid` preserved from an imported World Book, so it targets the original SillyTavern entry uid. For newly created drafts without `sourceUid`, prefer `index` or a unique `comment` to avoid confusing uid with the regenerated contiguous export index.
-
-## Tools Overview
-
-Task routing, workflow choice, and clarification strategy are handled by the bundled `skill/world-book-mcp-skill/` documentation rather than MCP tools.
-
-| Category | Tool | Description |
-| --- | --- | --- |
-| Workflow, Projects, and Specs | `init_project` | Initializes `.worldbook/project.json` and `.worldbook/draft/`; safely creates a root template JSON when no Tavern-format JSON exists; existing projects can be reused or overwritten with `if_exists`. |
-| Workflow, Projects, and Specs | `list_projects` | Returns the current `.worldbook/project.json` workspace project, or an empty list if no workspace exists. |
-| Workflow, Projects, and Specs | `get_project` | Views project details or a summary. |
-| Workflow, Projects, and Specs | `lint_worldbook_content` | Scans forbidden terms and common writing issues. |
-| Extraction | `create_extraction_outline` | Creates an extraction template for characters, worldbuilding, items, and events. |
-| Extraction | `submit_extraction_result` | Submits structured facts extracted by the main AI. |
-| World Book Building | `create_worldbook_entry_plan` | Creates an explicit entry plan from caller-provided card type, characters, world sections, items, scenes, and events. |
-| World Book Building | `validate_worldbook_entry_plan` | Validates an explicit entry plan's position, order, and keyword-trigger rules. |
-| World Book Building | `create_worldbook_draft_entry` | Creates one `.worldbook/draft/*.json` slice template. |
-| World Book Building | `create_worldbook_draft_entries` | Creates multiple slice templates. |
-| World Book Building | `update_worldbook_draft_field` | Locates a draft by comment and updates one field. |
-| World Book Building | `update_worldbook_draft_fields` | Updates a small set of draft fields at once. |
-| World Book Building | `confirm_worldbook_draft_complete` | Confirms all drafts are complete and ready to merge/export. |
-| World Book Building | `list_worldbook_draft_entries` | Lists `.worldbook/draft/*.json` split draft entries. |
-| World Book Building | `get_worldbook_draft_entry` | Reads one split draft entry by comment. |
-| World Book Building | `delete_worldbook_draft_entry` | Deletes one split draft entry by comment. |
-| World Book Building | `validate_worldbook_draft` | Validates draft configuration and content issues. |
-| World Book Building | `generate_worldbook_json` | Exports SillyTavern World Book JSON. |
-| Character Card | `import_character_card_json` | Imports an existing `chara_card_v3` JSON in the current directory and extracts profile plus embedded World Book draft. |
-| Character Card | `upsert_character_profile` | Creates or updates character card profile configuration through simplified fields; MCP automatically fills default `chara_card_v3` fields. |
-| Character Card | `validate_character_card_config` | Validates character card configuration and the embedded World Book. |
-| Character Card | `confirm_character_card_draft_complete` | Confirms character-card profile, embedded World Book drafts, and assets are ready to merge/export. |
-| Character Card | `generate_character_card_json` | Exports `chara_card_v3` character card JSON; `character_basic` and `character_personality` for the same character are merged into the same embedded World Book entry. |
-| Character Card | `create_character_card_patch` | Creates a patch plan for profile, worldbook config, or embedded World Book entries. |
-| Character Card | `preview_character_card_patch` | Previews character card patch diffs and validation. |
-| Character Card | `apply_character_card_patch` | Applies a character card patch, safely exports JSON, and updates the project. |
-| Character Card | `query_character_card` | Queries the character card summary, greetings, or embedded World Book entries. |
-| MVU / ZOD | `create_mvu_schema_template` | Creates an MVU/ZOD variable system configuration template. |
-| MVU / ZOD | `upsert_mvu_schema` | Partially updates MVU schema and variable path. |
-| MVU / ZOD | `upsert_mvu_update_rules` | Partially updates MVU initvar and update rules. |
-| MVU / ZOD | `submit_mvu_config` | Advanced entry: saves the full MVU configuration. |
-| MVU / ZOD | `validate_mvu_config` | Validates ZOD schema, initvar, update_rules, and greeting placeholders. |
-| MVU / ZOD | `build_mvu_assets` | Previews World Book entries, regex scripts, and Tavern Helper scripts that will be merged into the character card. |
-| HTML Beautification | `create_html_beautify_template` | Creates a status-bar or global HTML beautification configuration template. |
-| HTML Beautification | `upsert_html_statusbar` | Partially updates statusbar HTML, theme, and switches. |
-| HTML Beautification | `submit_html_beautify_config` | Advanced entry: saves the full HTML beautification configuration. |
-| HTML Beautification | `validate_html_beautify_config` | Validates HTML, CSS scope, regex configuration, and greeting placeholders. |
-| HTML Beautification | `build_html_beautify_assets` | Previews regex scripts that will be merged into the character card. |
-| EJS Dynamic Content | `create_ejs_template` | Creates a staged character profile, palette, or custom EJS template. |
-| EJS Dynamic Content | `upsert_ejs_entry` | Partially adds or updates one EJS entry by name. |
-| EJS Dynamic Content | `submit_ejs_config` | Advanced entry: saves the full EJS configuration. |
-| EJS Dynamic Content | `validate_ejs_config` | Validates MVU dependencies, variable paths, EJS tags, getwi references, and entry status. |
-| EJS Dynamic Content | `build_ejs_entries` | Previews EJS entries that will be merged into the embedded World Book of a character card. |
-| Query and Patch | `query_worldbook` | Queries existing World Book JSON, supporting `brief`, `uid`, `search`, and `stats`. |
-| Query and Patch | `import_worldbook_json` | Imports an existing World Book JSON in the current working directory as an MCP project draft. |
-| Query and Patch | `create_worldbook_patch` | Creates a modification plan without directly writing files. |
-| Query and Patch | `preview_worldbook_patch` | Previews the patch diff and validation results. |
-| Query and Patch | `apply_worldbook_patch` | Applies a patch, validates it automatically, and can back up and export a new JSON. |
-
-## Skill
-
-This repository includes a standard Claude Code Skill named `world-book-mcp-skill` at [`skill/world-book-mcp-skill/`](skill/world-book-mcp-skill/). It is a directory package containing `SKILL.md` and `references/`, used to guide AI in correctly orchestrating all tools of this MCP server when users request World Book or character card related tasks. The skill name is intentionally distinct from the MCP server name `world-book-mcp` to avoid confusion in agent tooling.
-
-## Future Capability Extensions
-
-The following capabilities are not implemented yet and are only references for the future roadmap:
-
-- Cross-project template reuse: derive a World Book or character card template from one project and apply it to a new project.
-- World Book entry cross-reference graph: analyze keys and secondaryKeys to output entry trigger dependency graphs.
-- Multilingual lint dictionaries: pluggable forbidden-term lists with support for English, Japanese, and more.
-- Character relationship graph export: generate relationship graph JSON from `character_basic` relationship fields.
-- Embedded World Book conflict detection: detect duplicate keys or orders when merging character cards and project World Books.
-- Decision template library: common ambiguity templates such as card type, world type, and style can be referenced by tools.
-- Worldbook diff tool: compare two SillyTavern JSON files.
-- ChatLog extraction: extract character behavior evidence from a dialogue history.
-- Automatic entry reordering: automatically resolve conflicts based on position and order rules.
-- Status-bar HTML AST validation: perform stricter safety checks with a lightweight HTML parser.
-- Multi-character-card collaboration: maintain multiple character card configs in one project and switch exports as needed.
-- Worldbook asset signing: attach version and signature data during JSON export for traceability.
-
-## License
-
-MIT
+Long text fields are summarized with preview, length, and hash.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```

package/README_ZH.md

@@ -1,192 +1,150 @@
 # world-book-mcp
 
-`world-book-mcp` 是一个使用 Node.js + TypeScript 编写的 MCP 服务器，用于管理 `.worldbook/` 草稿工作区，并辅助 AI 校验、patch 和导出符合 SillyTavern 格式的世界书 JSON、基础 `chara_card_v3` 角色卡 JSON，以及可选 MVU/ZOD、HTML 美化和 EJS 动态内容资产。原文阅读、网页搜索和事实提取由宿主 AI 在对话中完成；本服务器只保存结构化 project 状态、draft 条目、配置和导出 JSON。
+`world-book-mcp` 是一个 MCP server，用于创建、修改、校验和导出 SillyTavern 世界书 JSON 与 `chara_card_v3` 角色卡 JSON。
 
-## 安装
+## 架构
 
-### JSON 格式
+项目由两层组成：
 
-```json
-{
-  "type": "stdio",
-  "command": "npx",
-  "args": [
-    "-y",
-    "@qihuang02/world-book-mcp"
-  ]
-}
+```text
+┌─────────────────────────────────────────────────────┐
+│  Skill 层（skill/world-book-mcp-skill/）             │
+│  创作方法论：指导 AI 如何设计世界观、写角色、         │
+│  提取文风、从小说/网络资源中抽取信息、写开场白        │
+│  产出：高质量的结构化语料                            │
+└──────────────────────────┬──────────────────────────┘
+                           │ AI 调用 MCP 工具写入 draft
+┌──────────────────────────▼──────────────────────────┐
+│  MCP 层（src/）                                      │
+│  工程编排器：管理 draft 切片、校验一致性、            │
+│  构建 MVU/EJS/HTML 资产、导出酒馆 JSON               │
+│  产出：可直接导入 SillyTavern 的 JSON 文件           │
+└─────────────────────────────────────────────────────┘
 ```
 
-### Claude Code 格式
-
-```json
-"mcpServers": {
-  "world-book-mcp": {
-    "type": "stdio",
-    "command": "cmd",
-    "args": [
-      "/c",
-      "npx",
-      "-y",
-      "@qihuang02/world-book-mcp"
-    ]
-  }
-}
+## 主线工作流
+
+```text
+用户需求
+→ init_project
+→ update_plan（记录需求、决策、导出目标）
+→ create_draft_slice / update_draft_field(s)（写入语料）
+→ validate_draft（校验一致性）
+→ build_assets（可选，预览 MVU/EJS/HTML 资产）
+→ review_project / check_delivery（交付前审查）
+→ generate_json（导出）
 ```
 
-### Codex 格式
+## Skill 层 — 创作方法论
 
-```toml
-[mcp_servers.world-book-mcp]
-type = "stdio"
-command = "npx"
-args = ["-y", "@qihuang02/world-book-mcp"]
-# startup_timeout_sec = 60000.0
-```
+`skill/world-book-mcp-skill/` 包含指导 AI 创作的 reference 文档：
 
-## 当前能力
+| 文档 | 内容 |
+|------|------|
+| `worldbuilding-methodology.md` | 世界观设计：A/B/C 类型判定、维度取舍、总纲零度写作 |
+| `character-creation.md` | 角色设定：XML+YAML 结构、性格调色盘、三面性、开场白 |
+| `derivative-extraction.md` | 二创提取：从小说/网络资源系统性提取角色、世界观、事件 |
+| `style-extraction-guide.md` | 文风提取：分析源材料风格并转化为风格条目和禁词条目 |
+| `rephrase-guide.md` | 二次解释：作者对角色深层逻辑的注释，防止 AI 误解 |
+| `content-rules.md` | 内容规则：禁词、具体性、第四面墙 |
+| `first-message.md` | 开场白规则：吸引力、剧情动力、互动点 |
+| `composition.md` | 条目编排：蓝绿灯、position、order |
+| `requirements.md` | 需求对齐：用户决策流程 |
+| `tool-reference.md` | MCP 工具参数速查 |
 
-当前版本支持：
+## MCP 层 — 工程编排
 
-- 显式初始化 project，适合空白目录首次使用。
-- 创建信息提取 outline。
-- 提交由宿主 AI 整理好的结构化提取结果。
-- 根据调用方显式提供的卡型、角色、世界分区、物品、场景和事件创建世界书条目规划。
-- 扫描禁词与常见写作问题。
-- 先创建 `.worldbook/draft/*.json` 切片模板，再逐字段更新、确认完整并合并导出，避免 AI 一次提交完整条目对象。
-- 导出独立 SillyTavern 世界书 JSON。
-- 导入已有世界书 JSON，先切片为 `.worldbook/draft/*.json`，再进行安全 patch / 合并导出。
-- 基础角色卡 JSON 生成，可嵌入项目世界书 draft；导出角色卡时同一角色的基础设定和性格设定会聚合为同一个内嵌世界书条目。
-- MVU/ZOD 配置模板、校验、资产构建，并可自动合并进角色卡 JSON。
-- HTML 美化配置模板、校验、资产构建，并可自动合并进角色卡 JSON。
-- EJS 动态内容配置模板、校验、entries 构建，并可自动合并进角色卡内嵌世界书。
-- 查询导出的世界书 JSON 和角色卡 JSON。
-- 导入已有角色卡 JSON，将内嵌世界书切片为 draft，并通过 patch 修改角色卡字段或内嵌世界书条目。
+### 工作区结构
 
-暂不支持：
-- 内置网页搜索。
+`init_project` 创建：
 
-## `.worldbook/` 工作目录
+```text
+.worldbook/
+  project.json
+  plan.md
+  logs/
+  draft/
+    worldbook/
+    character-card/
+    mvu/
+    html/
+    ejs/
+    style/
+    chapter/
+```
 
-`init_project` 的主作用是在当前项目目录创建/复用单一 MCP 工作区 project。project 元信息只保存在 `.worldbook/project.json`，草稿分片保存在 `.worldbook/draft/`；旧的 `output/projects` 路径不再创建也不再读取：
+自动扫描当前目录下的 SillyTavern JSON 文件，将世界书条目、角色卡 profile、greetings、MVU、HTML、EJS 等资产切片到 draft 目录。
+
+### 核心工具
+
+| 工具 | 用途 |
+|------|------|
+| `init_project` | 初始化 `.worldbook/`，扫描并切片已有酒馆 JSON |
+| `update_plan` | 写入需求、决策、导出目标到 `.worldbook/plan.md` |
+| `create_draft_slice` | 创建 draft 切片 |
+| `update_draft_field` / `update_draft_fields` | 更新 draft 字段 |
+| `validate_draft` | 校验世界书、角色卡、MVU、EJS、HTML 等 |
+| `build_assets` | 预览将合并到角色卡的资产 |
+| `review_project` / `check_delivery` | 交付前审查与阻塞检查 |
+| `generate_json` | 导出世界书 JSON、角色卡 JSON 或两者 |
+| `query_json` | 查询已导出的 JSON |
+
+### MVU 变量工具
+
+| 工具 | 用途 |
+|------|------|
+| `list_mvu_variables` | 列出 schema 中的变量 |
+| `upsert_mvu_variable` | 新增/修改变量 |
+| `remove_mvu_variable` | 删除变量 |
+| `rewrite_mvu_variables` | 批量重写变量 |
+
+### 审查与 lint 工具
+
+| 工具 | 用途 |
+|------|------|
+| `lint_worldbook_content` | 对文本执行禁词/具体性 lint |
+| `lint_project_content` | 对整个项目执行 lint |
+| `create_writing_optimization_report` | 写作优化报告 |
+
+### Draft 类型
+
+- `worldbook_entry` — 世界书条目
+- `character_profile` — 角色卡 profile
+- `character_greetings` — 开场白
+- `mvu_schema` — MVU ZOD schema
+- `mvu_update_rules` — MVU initvar + update_rules
+- `html_statusbar` — HTML 状态栏
+- `html_regex` — HTML 正则脚本
+- `ejs_entry` — EJS 动态条目
+- `style_profile` — 文风配置
+- `chapter_outline` — 章节大纲
+
+## 修改已有 JSON
 
 ```text
-.
-├─ .worldbook/
-│  ├─ project.json          # project 元信息，不保存 draft 正文
-│  └─ draft/
-│     ├─ 新墟城.json
-│     ├─ 角色B_基础设定.json
-│     └─ 角色B_性格.json
-└─ <导出的世界书或角色卡>.json
+init_project(scan_existing=true, import_strategy="auto")
+→ list_draft_slices / get_draft_slice
+→ update_plan
+→ update_draft_field(s)
+→ validate_draft
+→ generate_json
 ```
 
-`create_worldbook_draft_entry` / `create_worldbook_draft_entries` 会先把每个切片模板写为 `.worldbook/draft/<safe-comment>.json`；随后使用 `update_worldbook_draft_field` / `update_worldbook_draft_fields` 逐字段填充。分片文件保存的是 MCP draft entry，而不是最终 SillyTavern entry：
-
-```json
-{
-  "comment": "新墟城",
-  "entryType": "world_summary",
-  "keys": ["新墟", "废墟都市", "避难城"],
-  "secondaryKeys": [],
-  "content": "...",
-  "constant": true,
-  "position": "before_char",
-  "order": 1,
-  "enabled": true,
-  "preventRecursion": true,
-  "excludeRecursion": true
-}
+## 日志
+
+MCP 静默记录工具调用摘要：
+
+```text
+.worldbook/logs/latest.jsonl
+.worldbook/logs/<session>.jsonl
 ```
 
-校验、审查、lint、世界书导出和角色卡导出会合并读取 `.worldbook/draft/*.json`；分片 draft 文件是草稿的唯一事实来源。`.worldbook/draft/` 是长期工作区：`generate_worldbook_json` / `generate_character_card_json` 导出后不会清空草稿，`apply_worldbook_patch` / `apply_character_card_patch` 合并导出后也会保留更新后的分片草稿，供下次继续修改。默认导出路径是当前工作目录的 `<名称>.json`，相对路径和绝对路径都必须位于当前工作目录内，越界写入会失败。
-
-此外，`init_project` 会扫描当前工作目录根目录的一层 `*.json`：如果没有发现酒馆格式世界书或 `chara_card_v3` 角色卡 JSON，会自动创建一个根目录模板 JSON；如果已经存在酒馆格式 JSON，则不会额外创建模板，也不会覆盖已有 JSON。返回值中的 `root_template` 会说明模板是否创建、路径或已有文件列表。`kind=worldbook` 会创建独立世界书模板；`kind=character_card` 和 `kind=mixed` 会创建 `chara_card_v3` 模板，其中 `mixed` 明确表示角色卡 + 内嵌空世界书的一体化模板。
-
-## Patch、revision 与并发
-
-同一 `project_id` 的写入会在 MCP 进程内串行化，并在返回值中递增 `revision`。支持 `expected_revision` 的写入工具可用它做并发冲突检测：如果调用方基于旧 revision 写入，会返回 `project revision conflict`。
-
-`apply_worldbook_patch` / `apply_character_card_patch` 会以当前 project draft 为输入，同时写导出的 JSON 文件并更新 project 状态；成功后保留更新后的 `.worldbook/draft/*.json`。实现会先写临时文件并替换目标文件，再更新 project；如果 project 更新失败，会尽力恢复旧导出文件或删除新写入文件。返回 `ok=false` 或抛出冲突错误时，调用方应重新读取 project 后再重试。
-
-patch 的 `match.uid` 优先匹配从已导入世界书保留的 `sourceUid`，用于定位原始 SillyTavern 条目 uid。对没有 `sourceUid` 的新建草稿，建议使用 `index` 或唯一 `comment` 定位，避免把 uid 误当作导出后的连续下标。
-
-## Tools 一览
-
-任务分类、工作流选择和澄清策略由随包 `skill/world-book-mcp-skill/` 文档指导，不再作为 MCP tools 暴露。
-
-| 分类 | Tool | 说明 |
-| --- | --- | --- |
-| 工作流、项目与规范 | `init_project` | 初始化 `.worldbook/project.json` 与 `.worldbook/draft/`；若根目录没有酒馆格式 JSON，会安全创建模板 JSON；已有项目可用 `if_exists` 控制复用或覆盖。 |
-| 工作流、项目与规范 | `list_projects` | 返回当前 `.worldbook/project.json` 工作区项目；未初始化时返回空列表。 |
-| 工作流、项目与规范 | `get_project` | 查看项目详情或摘要。 |
-| 工作流、项目与规范 | `lint_worldbook_content` | 扫描禁词和常见写作问题。 |
-| 提取 | `create_extraction_outline` | 创建角色、世界观、物品、事件的提取模板。 |
-| 提取 | `submit_extraction_result` | 提交主 AI 提取好的结构化事实。 |
-| 世界书构建 | `create_worldbook_entry_plan` | 根据调用方显式提供的卡型、角色、世界分区、物品、场景和事件创建条目规划。 |
-| 世界书构建 | `validate_worldbook_entry_plan` | 校验显式条目规划的 position、order 和关键词触发规则。 |
-| 世界书构建 | `create_worldbook_draft_entry` | 创建单个 `.worldbook/draft/*.json` 切片模板。 |
-| 世界书构建 | `create_worldbook_draft_entries` | 批量创建切片模板。 |
-| 世界书构建 | `update_worldbook_draft_field` | 按 comment 定位并逐字段更新 draft。 |
-| 世界书构建 | `update_worldbook_draft_fields` | 一次更新少量 draft 字段。 |
-| 世界书构建 | `confirm_worldbook_draft_complete` | 确认所有 draft 完整且可合并导出。 |
-| 世界书构建 | `list_worldbook_draft_entries` | 列出 `.worldbook/draft/*.json` 分片草稿。 |
-| 世界书构建 | `get_worldbook_draft_entry` | 按 comment 读取单个分片草稿。 |
-| 世界书构建 | `delete_worldbook_draft_entry` | 按 comment 删除单个分片草稿。 |
-| 世界书构建 | `validate_worldbook_draft` | 校验草稿配置和内容问题。 |
-| 世界书构建 | `generate_worldbook_json` | 导出 SillyTavern 世界书 JSON。 |
-| 角色卡 | `import_character_card_json` | 导入当前目录内已有 `chara_card_v3` 角色卡 JSON，提取 profile 与内嵌世界书 draft。 |
-| 角色卡 | `upsert_character_profile` | 用简化字段创建/更新角色卡人设配置，MCP 自动补齐 `chara_card_v3` 默认字段。 |
-| 角色卡 | `validate_character_card_config` | 校验角色卡配置和嵌入世界书。 |
-| 角色卡 | `confirm_character_card_draft_complete` | 确认角色卡 profile、内嵌世界书 draft 与资产可合并导出。 |
-| 角色卡 | `generate_character_card_json` | 导出 `chara_card_v3` 角色卡 JSON；同一角色的 `character_basic` 与 `character_personality` 会合并为同一个内嵌世界书条目。 |
-| 角色卡 | `create_character_card_patch` | 为已有角色卡 project 创建 profile / worldbook config / 内嵌世界书修改计划。 |
-| 角色卡 | `preview_character_card_patch` | 预览角色卡 patch diff 与校验结果。 |
-| 角色卡 | `apply_character_card_patch` | 应用角色卡 patch，安全导出 JSON 并更新 project。 |
-| 角色卡 | `query_character_card` | 查询角色卡概要、开场白或内嵌世界书条目。 |
-| MVU / ZOD | `create_mvu_schema_template` | 创建 MVU/ZOD 变量系统配置模板。 |
-| MVU / ZOD | `upsert_mvu_schema` | 局部更新 MVU schema 与变量路径。 |
-| MVU / ZOD | `upsert_mvu_update_rules` | 局部更新 MVU initvar 与 update_rules。 |
-| MVU / ZOD | `submit_mvu_config` | 高级入口：保存完整 MVU 配置。 |
-| MVU / ZOD | `validate_mvu_config` | 校验 ZOD schema、initvar、update_rules 与开场白占位符。 |
-| MVU / ZOD | `build_mvu_assets` | 预览将合并进角色卡的世界书条目、正则脚本和 Tavern Helper 脚本。 |
-| HTML 美化 | `create_html_beautify_template` | 创建状态栏或全局 HTML 美化配置模板。 |
-| HTML 美化 | `upsert_html_statusbar` | 局部更新状态栏 HTML、主题和开关。 |
-| HTML 美化 | `submit_html_beautify_config` | 高级入口：保存完整 HTML 美化配置。 |
-| HTML 美化 | `validate_html_beautify_config` | 校验 HTML、CSS 作用域、regex 配置和开场白占位符。 |
-| HTML 美化 | `build_html_beautify_assets` | 预览将合并进角色卡的 regex scripts。 |
-| EJS 动态内容 | `create_ejs_template` | 创建阶段人设、调色盘或自定义 EJS 模板。 |
-| EJS 动态内容 | `upsert_ejs_entry` | 按 name 局部新增/更新单个 EJS entry。 |
-| EJS 动态内容 | `submit_ejs_config` | 高级入口：保存完整 EJS 配置。 |
-| EJS 动态内容 | `validate_ejs_config` | 校验 MVU 依赖、变量路径、EJS 标签、getwi 引用和条目状态。 |
-| EJS 动态内容 | `build_ejs_entries` | 预览将合并进角色卡内嵌世界书的 EJS entries。 |
-| 查询与 Patch | `query_worldbook` | 查询已有世界书 JSON，支持 `brief`、`uid`、`search`、`stats`。 |
-| 查询与 Patch | `import_worldbook_json` | 把当前工作目录内已有世界书 JSON 导入为 MCP project draft。 |
-| 查询与 Patch | `create_worldbook_patch` | 创建修改计划，不直接写文件。 |
-| 查询与 Patch | `preview_worldbook_patch` | 预览 patch diff 和校验结果。 |
-| 查询与 Patch | `apply_worldbook_patch` | 应用 patch，自动校验，可备份并导出新 JSON。 |
-
-## Skill
-
-仓库自带一个名为 `world-book-mcp-skill` 的标准 Claude Code Skill，位于 [`skill/world-book-mcp-skill/`](skill/world-book-mcp-skill/)。它是一个 `SKILL.md` + `references/` 的目录包，用于指导 AI 在用户提出世界书 / 角色卡相关需求时，正确编排本 MCP 服务器的全部工具。skill 名称刻意区别于 MCP server 名称 `world-book-mcp`，避免在 Agent 工具中混淆。
-
-## 未来能力扩展
-
-以下能力暂未实现，仅作为后续路线参考：
-
-- 跨项目模板复用：从一个项目派生世界书 / 角色卡模板，应用到新项目。
-- 世界书条目互引图：分析 keys 与 secondaryKeys，输出条目触发依赖图。
-- 多语言 lint 词库：可插拔禁词表，支持英文 / 日文等。
-- 角色关系图导出：从 character_basic 关系字段生成关系图 JSON。
-- 内嵌世界书冲突检测：在角色卡 + 项目世界书合并时检测重复 keys / order。
-- Decision 模板库：常见歧义模板（卡型 / 世界观 / 风格）可被工具引用。
-- Worldbook diff 工具：对比两个 SillyTavern JSON。
-- ChatLog 抽取：从一段对话历史抽取角色行为依据。
-- 自动条目重排：按 position+order 规则自动调整冲突。
-- 状态栏 HTML AST 校验：基于轻量 HTML 解析做更严格的安全检查。
-- 多 character_card 协作：在同一 project 维护多张角色卡 config 并按需切换导出。
-- Worldbook 资产签名：导出 JSON 时附带版本与签名，便于追踪。
-
-## 许可
-
-MIT
+长文本字段以 preview + length + hash 形式记录。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+```