Novel CLI

@peigen996/novel-cli 是剧鲸 Novel 的 Agent 优先诊断与证据导出 CLI。它面向 Codex、Claude Code 等外部 Agent，也可直接供开发者使用。

它通过 Novel 服务的鉴权 HTTP API 读取项目、单条问答、QA 诊断运行、创作产物和爆款分析；不会写入项目，也不会把令牌保存到配置文件。

适用场景

• 定位一次创作问答为什么没有调用预期 Skill、工具或审核链路。
• 把一个项目、单条消息或爆款分析的证据导出到本地，交给更强的外部 Agent 排查。
• 在 CI 之外的本机或 Agent runtime 中检查诊断接口、配置和鉴权是否可用。

不适用于直接生成、改写、删除 Novel 项目内容；这些创作写操作不会进入诊断 CLI 的命令面。唯一的诊断侧写操作是显式发起质量审核，它只追加带正文/rubric 哈希的审核证据，不修改创作产物。

给 Agent 的 30 秒开始

安装后直接登录。首次登录默认连接 https://novel.kunworlds.com，浏览器确认后令牌写入系统钥匙串：

npm install -g @peigen996/novel-cli
novel login
novel doctor --json

开发环境可显式覆盖地址：novel login --api http://localhost:7005 --profile dev。

让 Agent 先发现当前稳定的命令面：

novel doctor --schema --json

然后按问题范围读取证据：

# 导出一条 assistant message 及其工具调用
novel message diagnose <message-id> --profile dev --json

# 精确导出评审页选中的历史运行（不会退化成“项目最近一次”）
novel run diagnose <run-id> --profile dev --json

# 导出项目当前产物和诊断线索
novel project export <project-id> --profile dev --json

# 对当前持久化正文发起一次显式质量审核
novel project audit <project-id> --phase phase3 --profile dev --json

# 导出项目关联的全部 QAchat 对话和工具调用
novel project conversation <project-id> --profile dev --json

# 导出一个爆款分析及其产品
novel analysis pull <analysis-id> --profile dev --json

--json 的 stdout 始终只输出一个 JSON 值。文件会写到 files 字段所列的绝对路径，外部 Agent 应优先读取这些文件，而不是解析终端文案。

本地开发

在仓库根目录的 server/ 下构建和运行：

pnpm --filter @peigen996/novel-cli build
node packages/novel-cli/dist/index.js doctor --api http://localhost:7005 --token '<mcp-token>' --json

发布到私有 npm registry 前，先执行：

pnpm --filter @peigen996/novel-cli test
pnpm --dir packages/novel-cli pack --dry-run

包已具备公开 registry 的发布清单，并发布在 npm 用户 peigen996 的个人 scope 下。

命令

所有读取命令都接受：

--api <origin>          本次调用覆盖 profile 的 API 地址
--profile <name>        profile 名；默认 default
JUJING_API              无 --api/profile 时的环境地址覆盖
--token <token>         本次调用令牌（优先级最高）
--out <directory>       本地导出目录；默认 ./.jujing/diagnostics
--json                  输出机器可读 JSON envelope

| 命令 | 用途 | | --- | --- | | novel login [--api <origin>] [--profile <name>] | 拉起浏览器登录；首次无配置时使用生产地址并保存 profile。 | | novel logout [--profile <name>] | 清除当前 profile 的系统钥匙串凭证。 | | novel whoami [--profile <name>] | 验证当前登录身份和凭证来源。 | | novel init --api <origin> [--profile <name>] --yes | 非交互式保存 API profile；不保存令牌。 | | novel doctor | 检查诊断 API，并报告令牌来源而非令牌内容。 | | novel run diagnose <run-id> | 按唯一 run ID 导出冻结配置、事件、产物关联和审核证据。 | | novel project diagnose <project-id> | 定位最近一条 QA diagnostic run 并导出运行证据。 | | novel project audit <project-id> --phase <phase> [--run <run-id>] | 审核当前持久化正文，并按正文/rubric 哈希复用或创建审核记录。 | | novel project inspect <project-id> | 导出项目阶段与诊断概览。 | | novel project export <project-id> | 导出项目概览和当前阶段产物。 | | novel project conversation <project-id> | 导出项目关联的完整 QAchat 对话与工具调用。 | | novel message diagnose <message-id> | 导出一条消息、其关联用户消息和工具调用。 | | novel thread pull <thread-id> | 按对话线程 ID 导出完整问答和工具调用。 | | novel artifact pull <project-id> <phase> | 拉取一个阶段的当前产物。 | | novel analysis inspect <analysis-id> | 导出爆款分析元数据。 | | novel analysis pull <analysis-id> | 导出爆款分析及其产品 Markdown。 | | novel mcp [--profile <name>] | 启动本地 stdio MCP，供 Codex / Claude Code 调用受限只读诊断工具。 | | novel auth set-token --token <token> [--profile <name>] --yes | 显式写入当前 profile 的系统钥匙串。 | | novel auth clear-token [--profile <name>] --yes | 显式清除当前 profile 的系统钥匙串令牌。 | | novel <任一有效命令> --schema --json | 返回当前命令面的机器可读能力说明。 |

Profile 和认证

profile 只保存 API 地址与可选标签。默认路径为：

| 平台 | 配置路径 | | --- | --- | | macOS | ~/Library/Application Support/jujing-novel/config.json | | Windows | %APPDATA%\jujing-novel\config.json | | Linux | $XDG_CONFIG_HOME/jujing-novel/config.json，或 ~/.config/jujing-novel/config.json |

API 地址解析优先级为：--api、profile、JUJING_API；仅首次 novel login 在三者都缺失时回退到 https://novel.kunworlds.com，并把该地址保存到 default profile。

令牌解析优先级：

1. --token
2. JUJING_TOKEN
3. 系统钥匙串（macOS Keychain / Windows Credential Locker）
4. 缺失

对 Agent，推荐短生命周期环境变量；对人类可使用 novel auth set-token --token … --yes 写入系统钥匙串。避免把 --token 放进 shell history 或共享脚本；profile 配置文件始终不含令牌。

JSON 契约

成功：

{
  "ok": true,
  "schema_version": 1,
  "environment": "dev",
  "data": {},
  "files": ["/absolute/path/evidence.json"],
  "warnings": []
}

失败：

{
  "ok": false,
  "schema_version": 1,
  "environment": "unknown",
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Novel API token is required.",
    "hint": "Pass --token or set JUJING_TOKEN."
  }
}

schema_version 只在不兼容变更时递增。外部 Agent 必须按 ok 分支处理结果，不得从 message 推断状态。message diagnose 默认不返回工具输入/输出和原始 message parts；只有 --include-raw 才会请求完整单轮 raw parts。历史消息缺少精确 QA run 锚点时返回 partial，不会用时间窗伪装 exact。

本地开发使用共享调试密钥时，可额外显式传入 --debug-user-id <id>；它只会作为本次请求的 X-Debug-User-Id 头发送，不写入 profile 或钥匙串。常规使用仍应配置用户自己的 MCP Token。

本地证据结构

默认导出目录为 ./.jujing/diagnostics。常见结构：

.jujing/diagnostics/
├── <message-id>/
│   ├── README.md
│   ├── message.json
│   ├── user-message.md
│   ├── assistant-message.md
│   └── tool-calls.json
├── <project-id>/
│   ├── README.md
│   ├── project-export.json
│   └── artifacts/
│       ├── phase3.json
│       └── phase3.md
└── <analysis-id>/
    ├── README.md
    ├── analysis.json
    └── products/
        └── framework-<product-id>.md

每个目录型导出都会生成 README.md，它是人和 Agent 的阅读入口：说明导出对象、ID、raw/快照完整度、实际文件用途和推荐阅读顺序。JSON 文件仍是机器读取的事实源，文件名和 schema 不因说明文件而改变；非 JSON 模式也继续输出原有主文件路径，避免破坏脚本调用。

这些文件可能包含创作正文、工具参数和用户输入。请把它们视作项目敏感资料：不要提交到 Git，不要未经确认上传到第三方服务。

与 MCP、Skill 的边界

• CLI：批量导出、本地落盘、doctor、未来的差异与归档。
• MCP：向模型返回受大小限制的只读查询结果，避免把完整项目正文塞进上下文。
• Skill：给 Codex / Claude Code 提供排查决策流程，而非重复 HTTP API 定义。

当前 CLI 已具备 --schema、单请求项目证据导出、默认安全的 message 诊断，以及 stdio MCP。MCP 提供 novel.project.inspect、novel.message.diagnose、novel.analysis.inspect、novel.diagnostic.run 四个只读工具；每个字符串字段限制为 24,000 字符，出现 truncated: true 时改用 CLI 导出完整本地证据。

随包附带的 Agent diagnosis Skill 规定了 CLI/MCP 选择、证据引用和历史消息没有 QA run 时的降级流程。

排错

| 现象 | 处理 | | --- | --- | | API_REQUIRED | 先运行 novel login；开发环境也可使用 --api、JUJING_API 或 novel init。 | | AUTH_REQUIRED | 运行 novel login；CI 可使用 JUJING_TOKEN 或当前命令的 --token。 | | doctor 显示 healthy: false | 先补令牌；随后确认 API 地址与诊断路由可访问。 | | 项目没有 QA run | 这是历史数据或 collector 未启用时的正常结果；用 message diagnose 拉取单条消息，必要时再查项目原始会话。 | | 导出文件过大 | 先用 project inspect 或 analysis inspect 缩小范围，再拉取单个产物或消息。 |

设计原则

• 只读优先：诊断不会改变用户创作和项目状态。
• 证据优先：任何结论都应能回到导出的运行、消息、工具调用或产物。
• Agent 稳定：JSON schema、错误码、文件路径和命令语义优先保证兼容。
• 安全默认：令牌不入 profile；敏感原文导出必须由调用者明确承担数据边界。