Inktan

一个独立的小说创作工程生成器。它会通过命令行问答生成一个基于 Docusaurus 的小说世界观项目，并预置 inktan/ 知识库、根目录 chapters/ 输出、SQLite schema、prompts 和编辑器适配文件。

安装与使用

全局安装：

npm install -g inktan

创建一个新的小说工程：

mkdir my-novels
cd my-novels
inktan create

也可以不全局安装，直接用 npx 运行：

npx inktan create

命令会依次询问：

• 工作区语言：中文或 English。
• 项目名称：会自动转成目录 slug。
• 编辑器适配：Claude Code、Codex、Cursor、Qoder。
• npm registry：默认 npm registry 或阿里云镜像站。
• 一句话剧情：用于生成 0001-initial-world 初始世界观提案。
• 是否立即安装生成项目的依赖。

创建完成后进入生成的项目：

cd <project-slug>
npm install
npm run start

在浏览器打开 Docusaurus 本地站点后，可以阅读和维护工作台内容。章节正文位于根目录 chapters/，世界观和提案位于 inktan/。

升级已有 Inktan 工程：

cd <project-slug>
inktan upgrade

upgrade 会根据 .inktan/manifest.json 更新生成器托管的文件；如果用户已经改过托管文件，会写入 .next 文件供人工合并，避免直接覆盖用户设定。

开发命令

npm install
npm test
npm run build
npm run dev

当前 MVP

• 支持中文 / English 工作区
• 支持项目名转 slug
• 支持 Claude Code、Codex、Cursor、Qoder 适配文件
• 支持默认 npm registry / 阿里云镜像站
• 生成 OpenSpec 风格的 inktan/proposals/active/0001-initial-world
• 生成基础 inktan/world/、chapters/、inktan/pending/、inktan/db/schema.sql
• 生成 OpenSpec 风格的编辑器命令：explore、propose、check、write、deai
• 生成本地 stdio MCP 服务：编辑器 AI 可通过 npm run inktan:mcp 查询世界观、提交候选事实，并在用户确认后同步结构化 YAML

编辑器命令

不同编辑器的 slash command 路径不同，生成器按 OpenSpec 的适配器思路分别生成：

• Claude Code：.claude/commands/inktan/{explore,propose,check,write,deai}.md，通常以 /inktan:explore 形式唤起。
• Cursor：.cursor/commands/inktan-{explore,propose,check,write,deai}.md，通常以 /inktan-explore 形式唤起，命令正文也会识别 /inktan:explore。
• Qoder：.qoder/commands/inktan/{explore,propose,check,write,deai}.md，通常以 /inktan:explore 形式唤起。
• Codex：项目内生成 .codex/skills/inktan-*，并把可 slash 唤起的 prompt 安全写入 $CODEX_HOME/prompts/inktan-*.md；未设置 CODEX_HOME 时使用 ~/.codex/prompts。

/inktan-write 或 /inktan:write 执行前必须确认当前 proposal 的 questions.md 已全部解决，或用户明确说明无需继续追问。

/inktan:deai 是跨编辑器正文去 AI 味命令。生成项目还会提供 npm run skills:install-qu-ai-wei，用于把上游 qu-ai-wei 安装到其支持的 Codex、Claude Code 和 Cursor 目标；Qoder 等编辑器可直接使用 Inktan 内置的 /inktan:deai。

AI 提案、事实抽取和入库在第一版中以 prompts、skills 和脚本占位形式存在。正式入库原则是“AI 生成候选，用户确认后写入”。

用 Inktan 提案系统处理小说

Inktan 默认生成 inktan/proposals/active/0001-initial-world 作为初始世界观提案。用户只定义一句话剧情时，任意编辑器入口都应先建议用户完善这个提案，而不是直接跳到第一章。AI 需要给出一个可直接同意的初始世界观方案，通常包括题材承诺、主角欲望、第一阻碍、世界硬规则和第一卷压力。

如果用户同意方案，AI 先把确认内容记录到 decisions.md，处理 tasks.md，并检查 questions.md 里是否还有“阻塞写作”的问题。只有初始提案已完结，或用户明确说明无需继续追问并接受候选事实边界，才进入 /inktan:write 写第一章。

推荐生命周期是：一句话剧情 -> 初始世界观提案 -> 用户确认 -> 同步正式世界观 -> 写章节 -> 连续性检查 -> 完成、拒绝、替代或实施后归档到 inktan/proposals/archive/。

MCP 服务

生成出的小说工作区会包含 scripts/inktan-mcp-server.ts 和 inktan/mcp/README.md。支持 MCP 的编辑器可以把 command 配置为 npm，args 配置为 ["run", "inktan:mcp", "--silent"]，并把 cwd 指向工作区根目录。

底层知识模型按“实体、事实、关系、事件、变化、来源”组织：

• entities / entity_aliases：人物、地点、势力、文化、规则、物品、概念等可被指代的主体。
• facts：关于某个主体的细粒度事实，支持状态、来源和有效时间区间。
• relations：两个主体之间的关系，也支持有效时间区间。
• events / event_changes：时间线上发生的事，以及事件造成的状态变化。
• sources：事实、关系和事件的来源，便于追溯用户确认、提案、章节或候选事实。
• candidate_facts：AI 抽取但尚未确认的候选事实。
• canon_fts：用于按关键词检索设定，避免把大量 Markdown 全量塞进上下文。

MCP 服务默认提供：

• search_canon：查询 world、entities、relations、events、proposals、pending 和 state。
• get_entity / get_relations：读取人物和关系。
• get_facts：读取某个实体的细粒度事实。
• get_writing_context：按章节、场景目标和草稿片段聚合紧凑上下文。
• submit_candidate_fact：只写入 inktan/pending/，不自动入库。
• approve_candidate_fact：用户明确确认后，把候选同步为结构化 YAML。
• rebuild_db：运行 npm run db:rebuild，从 YAML 重建 SQLite。