Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,7 @@
*.docx binary
*.woff binary
*.woff2 binary

# Byte-for-byte fixtures from preview.20; their published digests must survive checkout.
scripts/fixtures/library-preview20/library.sqlite binary
scripts/fixtures/library-preview20/backup.json -text
114 changes: 114 additions & 0 deletions .github/workflows/library-s2-installer.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
name: S2 Windows Setup
on:
push:
branches: [codex/library-s2-installer-qa]
paths-ignore:
- 'docs/**'
- 'ROADMAP.md'
- 'scripts/benchmark-*.mjs'

permissions:
contents: read
actions: read

jobs:
qualify:
if: github.repository == 'SHIN09-git/novel' && !github.event.deleted
runs-on: windows-2025
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
route: [clean, upgrade]
name: S2 ${{ matrix.route }}
env:
ROUTE: ${{ matrix.route }}
SETUP_ARTIFACT: s2-setup-${{ github.sha }}-${{ github.run_attempt }}
defaults:
run:
shell: pwsh
steps:
- name: Start evidence record
run: |
$dir = New-Item -ItemType Directory -Path (Join-Path $env:RUNNER_TEMP 's2-evidence')
@{ route=$env:ROUTE; commit=$env:GITHUB_SHA; run=$env:GITHUB_RUN_ID; attempt=$env:GITHUB_RUN_ATTEMPT } |
ConvertTo-Json | Set-Content (Join-Path $dir.FullName 'job.json')
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: actions/setup-node@v4
with:
node-version: 24
- name: Install locked dependencies
run: npm.cmd ci
- name: Require a newer candidate version from this commit
run: node -e "const v=require('./package.json').version,l=require('./package-lock.json');if(!require('semver').gt(v,'0.1.6-preview.20')||v!==l.version||v!==l.packages[''].version)throw Error('Set and lock the candidate version before pushing')"
- name: Build the single candidate (no publishing)
if: matrix.route == 'clean'
run: npm.cmd run dist:win
- name: Retain candidate Setup and build records
if: matrix.route == 'clean'
uses: actions/upload-artifact@v4
with:
name: ${{ env.SETUP_ARTIFACT }}
path: |
release/Novel Director Setup *.exe
release/SHA256SUMS.txt
release/BUILD_INFO.json
compression-level: 0
if-no-files-found: error
retention-days: 14
# Both VMs consume the uploaded artifact. No third Windows build VM.
- name: Wait for this run's candidate
if: matrix.route == 'upgrade'
timeout-minutes: 40
env:
GH_TOKEN: ${{ github.token }}
run: |
$run = "repos/$env:GITHUB_REPOSITORY/actions/runs/$env:GITHUB_RUN_ID"
while ($true) {
$assets = gh api "$run/artifacts?name=$env:SETUP_ARTIFACT" | ConvertFrom-Json
if ($LASTEXITCODE) { throw 'Cannot read run artifacts' }
if (@($assets.artifacts | Where-Object { $_.name -ceq $env:SETUP_ARTIFACT -and !$_.expired }).Count -eq 1) { break }
$jobs = gh api "$run/attempts/$env:GITHUB_RUN_ATTEMPT/jobs" | ConvertFrom-Json
if ($LASTEXITCODE) { throw 'Cannot read packaging job status' }
if ($jobs.jobs | Where-Object { $_.name -eq 'S2 clean' -and $_.status -eq 'completed' -and $_.conclusion -ne 'success' }) {
throw 'Packaging job ended without handing over the Setup'
}
Start-Sleep -Seconds 12
}
- name: Download the same immutable candidate
env:
GH_TOKEN: ${{ github.token }}
timeout-minutes: 6
run: |
# The artifact can be indexed for this run before its download endpoint is ready.
$PSNativeCommandUseErrorActionPreference = $false
$inputDir = Join-Path $env:RUNNER_TEMP 's2-input'
for ($i=1; $i -le 8; $i++) {
$attemptDir = Join-Path $env:RUNNER_TEMP "s2-download-$i"
gh run download $env:GITHUB_RUN_ID --name $env:SETUP_ARTIFACT --dir $attemptDir
if ($LASTEXITCODE -eq 0) {
New-Item -ItemType Directory -Path $inputDir -ErrorAction Stop | Out-Null
Get-ChildItem -LiteralPath $attemptDir -File | Copy-Item -Destination $inputDir -ErrorAction Stop
exit 0
}
if ($i -lt 8) { Start-Sleep -Seconds 8 }
}
throw 'Unable to download this attempt''s immutable Setup'
- name: Exercise installed product
run: ./scripts/s2-windows/qualify.ps1
- name: Record job outcome
if: always()
env:
RESULT: ${{ job.status }}
run: |
$env:RESULT | Set-Content (Join-Path $env:RUNNER_TEMP 's2-evidence/job-result.txt')
- name: Retain qualification evidence
if: always()
uses: actions/upload-artifact@v4
with:
name: s2-${{ matrix.route }}-report-${{ github.sha }}-${{ github.run_attempt }}
path: ${{ runner.temp }}/s2-evidence/
if-no-files-found: warn
retention-days: 14
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Novel Director 是一个实验性的、本地优先的 AI 长篇小说工作台

- 实验性本地优先桌面应用。
- Windows 是主要开发和验证平台。
- 项目数据默认保存到本地 SQLite 数据库;JSON 导入、导出和 fallback 仍然保留。
- 项目默认保存到本地 SQLite。仍可导入、导出 JSON,也可明确选择一份 JSON 作为独立书库。
- AI 功能是可选的,取决于你配置的模型供应商。
- 源码仓库不跟踪预构建 `.exe` 或打包产物。

Expand Down Expand Up @@ -86,16 +86,16 @@ npm.cmd run dist:win

### Windows 打包、SQLite 与 native 依赖

Novel Director 使用 `better-sqlite3` 作为 main process 的 SQLite 后端。它是 native 依赖,在 Windows 上可能需要 Visual Studio C++ Build Tools(含 MSVC、Windows SDK 和 C++ CMake tools)才能重新编译 Electron 绑定。
开发主线使用 `better-sqlite3` 13。打包前先让 Electron 执行一次 SQLite 查询。Windows x64 随依赖提供的组件能用时无需编译;只有需要从源码重新编译时才需要 Visual Studio C++ Build Tools。

建议:

- 开发机先运行 `npm.cmd install`,再运行 `npm.cmd run build`。
- 运行 Electron 预览并连接 SQLite 前,先运行 `npm.cmd run native:electron`,或直接使用 `npm.cmd run preview:sqlite`。
- 跑 Agent CLI、验证脚本或 Node.js 侧 SQLite 测试前,运行 `npm.cmd run native:node`,把 `better-sqlite3` 恢复为本机 Node.js ABI。
- 运行 `npm.cmd run native:node` 可验证 Agent 和测试使用的 Node 也能查询 SQLite;已有组件可用时不会重新编译。
- 打包使用 `npm.cmd run dist:win`,脚本会使用仓库内 `.electron-cache` 和 `.electron-builder-cache`,减少 C 盘缓存压力。
- 打包流程会在生成 `release/win-unpacked/Novel Director.exe` 后运行 `npm.cmd run smoke:packaged`,检查图标、preload API、SQLite 默认路径、导入导出 API 和无 API Key 状态。
- 如果 `better-sqlite3` rebuild 失败,先安装 Visual Studio C++ Build Tools;应用代码仍保留 JsonStorageService fallback,但正式安装包应优先修复 native 绑定后再发布。
- 如果 SQLite 组件无法加载,桌面版会显示“书库未打开”,不会自动切换到 JSON。修复安装后点“重试”。明确选择独立 JSON 时,之后的修改只写入该文件。

单独运行打包后烟测:

Expand All @@ -109,7 +109,7 @@ npm.cmd run smoke:packaged

排查建议:

- 如果 SQLite 数据库损坏,先备份当前 `novel-director-data.sqlite`,再尝试从设置页恢复最近备份或导入旧 JSON。
- 如果看到“书库未打开”,先核对错误页的路径。外接磁盘断开时,接回原盘并点“重试”。文件损坏时,点“从备份恢复到新文件”,选择 JSON 备份和一个未用过的文件名,原库不会被覆盖。不需要先建空项目。
- 如果 JSON 导入失败,确认文件来自 Novel Director 导出或旧版 `novel-director-data.json`,不要直接导入章节 TXT/Markdown。
- 如果迁移或合并失败,不要删除源文件;检查自动生成的 `.bak` 或迁移前备份。
- 如果备份恢复失败,保留失败文件和日志,通过 Settings 的日志导出或 issue 模板提交脱敏信息。
Expand Down Expand Up @@ -219,7 +219,7 @@ Start with the [beginner tutorial](./docs/BEGINNER_TUTORIAL.md) or [quickstart](

- Experimental local-first desktop app.
- Windows is the primary development target.
- Data is stored locally in SQLite by default; JSON import, export, and fallback remain available.
- SQLite is the default local store. JSON import, export, and explicitly selected standalone JSON libraries remain available.
- AI features are optional and depend on the provider you configure.
- No prebuilt binaries are tracked in this source repository.

Expand Down Expand Up @@ -280,16 +280,16 @@ The default package is an unsigned trial build. Windows may show a SmartScreen w

### Windows Packaging, SQLite, and Native Dependencies

Novel Director uses `better-sqlite3` as the main-process SQLite backend. It is a native dependency, so Windows builds may require Visual Studio C++ Build Tools, including MSVC, Windows SDK, and C++ CMake tools, to rebuild Electron bindings.
The development branch uses `better-sqlite3` 13. Packaging tests the installed binding with an actual SQLite query in Electron. The bundled Windows x64 binary normally needs no compilation; Visual Studio C++ Build Tools are needed for a source rebuild.

Recommendations:

- Run `npm.cmd install`, then `npm.cmd run build` on the development machine.
- Before running Electron preview against SQLite, run `npm.cmd run native:electron`, or use `npm.cmd run preview:sqlite`.
- Before running Agent CLI, validation scripts, or Node-side SQLite tests, run `npm.cmd run native:node` to restore the `better-sqlite3` binding for the local Node.js ABI.
- Use `npm.cmd run native:node` to verify the binding used by the Agent CLI and tests. It does not rebuild a working binding.
- Use `npm.cmd run dist:win` for packaging. The script uses repository-local `.electron-cache` and `.electron-builder-cache` directories to reduce C drive pressure.
- The packaging flow runs `npm.cmd run smoke:packaged` after creating `release/win-unpacked/Novel Director.exe`; the smoke test checks the icon, preload API, SQLite default path, import/export API, and no-key state.
- If `better-sqlite3` rebuild fails, install Visual Studio C++ Build Tools first. The app retains JsonStorageService fallback in code, but release packages should be shipped only after the native binding is healthy.
- If the SQLite component cannot load, the desktop app shows a recovery screen instead of switching to JSON. Repair the installation and retry. Changes made to an explicitly selected JSON library stay in that file.

Run packaged smoke test separately:

Expand All @@ -303,7 +303,7 @@ If the project list is empty on first launch, click `导入旧数据 JSON` and s

Troubleshooting:

- If the SQLite database is corrupted, back up `novel-director-data.sqlite` first, then restore a recent backup or import old JSON from Settings.
- On the library recovery screen, check the displayed path. Reconnect the original disk and retry, or restore a JSON backup to a new filename. Recovery does not overwrite the original library or require an empty project first.
- If JSON import fails, make sure the file is a Novel Director export or legacy `novel-director-data.json`, not a chapter TXT/Markdown export.
- If migration or merge fails, do not delete the source file; check the generated `.bak` files or pre-migration backups.
- If backup restore fails, keep the failed file and logs, then share redacted diagnostics through the security or issue process.
Expand Down
22 changes: 11 additions & 11 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 路线图 / Roadmap

更新日期:2026-11-11。这里只保留当前方向和下一步,不再重复各版本的施工日志、源码行数和已完成待办。历史变更见 [CHANGELOG](./CHANGELOG.md),包的实际状态见 [发行产物说明](./docs/RELEASE_ARTIFACTS.md)。
更新日期:2026-11-13。这里只保留当前方向和下一步,不再重复各版本的施工日志、源码行数和已完成待办。历史变更见 [CHANGELOG](./CHANGELOG.md),包的实际状态见 [发行产物说明](./docs/RELEASE_ARTIFACTS.md)。

## 当前方向

Expand All @@ -13,20 +13,20 @@
- 桌面和 Agent 共用生成、审稿、修订、候选决定及正式提交流程;项目权限可以撤回。
- 章节阅读、局部重写、任务编辑、候选历史和作者诊断摘要已有入口。

2026-10-31:复用单次 Novelty 审计的分词结果,去掉 Prompt 追踪的重复渲染,简化 token 扫描;修订指令按类型输出。范围、实测和限制见 [本轮性能记录](./docs/REDUNDANCY_PERFORMANCE.md)。已纳入本地 Preview.19 安装包和 `release/win-unpacked`,尚未上传 GitHub。
[Preview.20](https://github.com/SHIN09-git/novel/releases/tag/v0.1.6-preview.20) 已公开发布,包含[长篇完稿修复](./docs/LONG_NOVEL_COMPLETION_REPAIR_PLAN.md):超限保稿、成稿硬规则核查、跨章对账、按书统计用量和批量改名。用量不能反推供应商余额或缺失的历史账单。此前减少 Novelty 重复分词、Prompt 追踪重复渲染的实测见[性能记录](./docs/REDUNDANCY_PERFORMANCE.md)。

## 下一步优先事项

按[长篇完稿后的修复计划](./docs/LONG_NOVEL_COMPLETION_REPAIR_PLAN.md),源码已支持保留超限稿、成稿硬规则核查、全书进度与连写顺序、按章取余额和跨章事实核对。P2 增加按书统计模型用量、调用前估算、连接诊断、按起止章编排导向,以及可预览和追溯的批量改名。尚不能从用量反推供应商余额或旧书缺失的账单。下表保留原有维护事项;安装包要单独更新。
见[书库可靠性与长篇性能施工计划](./docs/LIBRARY_STABILITY_AND_PERFORMANCE_PLAN.md)。本轮候选为 **preview.21**;候选测试与公开发布分开,未替换已发布的 preview.20。

| 优先级 | 工作 | 完成条件 |
| --- | --- | --- |
| 1 | 处理已报告的依赖安全告警 | 核对受影响调用,按兼容范围升级;完整回归和包内 SQLite 启动通过后再发包 |
| 2 | 继续压缩实际慢入口 | 复现具体操作,测量全量数据读取、跨进程传输或诊断耗时;只有可重复收益才新增定向查询或后台计算 |
| 3 | 用真实修订案例检查提示词 | 对比指定问题是否修好、无关段落是否保留;记录 Novelty 误报/漏报,避免继续堆全局禁令 |
| 4 | 修补高频操作中的阻碍 | 优先未保存输入恢复、采纳失败恢复、阅读和修订切换;按用户反馈选具体入口,不做全站重设计 |
| S0 / S1,本地完成 | 保留 preview.20 虚构库;区分书库未打开和空书库 | 从错误页重试、选择已有库、恢复至新文件或明确新建;不自动切换独立 JSON |
| S2,已验收 | 两台独立 Windows 虚拟机测试同一安装包 | [全新安装与原地升级均通过](./docs/S2_WINDOWS_QUALIFICATION.md),包含重启、卸载及回退 |
| S3-A / S3-B | 打开项目只写最近打开时间;SQLite 按本次采纳或修订所需的记录校验 | 继续检查版本、项目归属、报告与正文;使用同一份虚构长篇书库对照 |
| S4 | 压缩新自动备份,保留可供旧版恢复的普通 JSON;手动备份不轮替 | 两种格式均可恢复;不删除历史步骤或改写现有提交回执。首屏历史按需加载继续暂缓 |

真实模型对照需要另行确认供应商、模型和费用。本地性能基准不消耗模型额度,不能替代成文质量评估。
具体的修订质量、Novelty 误报和未保存输入仍按作者反馈跟进,不阻塞上述交付。本轮性能验收不消耗模型额度,也不替代成文质量评估。

## 保留的必要校验

Expand All @@ -40,7 +40,7 @@ npm.cmd test
npm.cmd run build
```

更新安装包时另跑 `npm.cmd run smoke:packaged`;公开发布前做密钥扫描。每项新优化必须有行为回归或实测依据,不新增只检查文案和文件行数的门槛。
发布候选包另跑 `npm.cmd run smoke:release` 检查解包程序,再用 Setup 验证实际安装和升级;两者不能互相替代。公开发布前做密钥扫描。每项新优化必须有行为回归或实测依据,不新增只检查文案和文件行数的门槛。

## 暂缓

Expand All @@ -56,8 +56,8 @@ npm.cmd run build

## English

Updated 2026-11-11. The [long-novel repair plan](./docs/LONG_NOVEL_COMPLETION_REPAIR_PLAN.md) now includes project-level usage, single-request cost estimates, connection diagnoses, custom story-direction ranges and auditable chapter renames, in addition to draft retention, canon checks and cross-chapter continuity. Provider balances and unrecorded historical usage remain unknown. This describes the working tree, not a new installer.
Updated 2026-11-13. The [preview.20 prerelease](https://github.com/SHIN09-git/novel/releases/tag/v0.1.6-preview.20) includes the [long-novel fixes](./docs/LONG_NOVEL_COMPLETION_REPAIR_PLAN.md). Provider balances and unrecorded historical usage remain unknown.

Next: verify dependency advisories; profile concrete slow operations before redesigning storage or threading; evaluate task-specific revision instructions with real cases; repair reported editing and acceptance friction. The [current performance record](./docs/REDUNDANCY_PERFORMANCE.md) covers the optimizations now packaged locally as Preview.19, not a claim about model quality or a GitHub publication.
The [library plan](./docs/LIBRARY_STABILITY_AND_PERFORMANCE_PLAN.md) qualifies preview.21 separately from public releases. Project opening no longer sends a full snapshot; SQLite commits load their validation inputs by scope. New automatic backups use compression where the file can be restored safely. Existing receipts and manual backups are retained. Full-library startup reads are a separate, deferred optimization.

Keep project isolation, version conflict checks, idempotent commits, report provenance, rollback, backups, authorization and credential redaction. Full CRUD rewrites, FTS, graphs, cloud sync and generic extension systems remain deferred. Historical plans and measurements are references, not additional mandatory work.
Loading