Niko Studio

Version: 11.0.4 (Platform Edition) Architecture: Writer-first Desktop + Tauri Shell + local Node/TypeScript Gateway Positioning: Writer-first desktop studio for manuscript authoring, Story Bible work, knowledge browsing, and workflow-assisted drafting

🎯 Product Overview

Niko Studio ships as a writer-first desktop product. The delivered runtime is the Tauri desktop shell in desktop/, backed by the local Node/TypeScript gateway in src-ts/. Repository governance helpers, release scripts, and compatibility surfaces remain in the tree, but they do not redefine the supported product/runtime contract.

Supported product path
Desktop UI (`desktop/`)
  -> Tauri host
  -> local Node/TypeScript gateway (`src-ts/`)
  -> manuscript, Story Bible, chat drafting, workflow execution, evaluation, knowledge browsing

Compatibility and migration surfaces
  -> `scripts/start_gateway.py` launcher (defaults to Node/TypeScript)
  -> explicit legacy Python override when compatibility sources exist
  -> Streamlit validation flows when a candidate still ships them

Deprecated release surface (removed)
  -> browser-first web entry was removed; WEB_UI_FORWARD_URL is no longer supported

✨ Writer-Facing Capabilities

Desktop authoring: manuscript editing, chat drafting, evaluation, settings, and knowledge browsing.
Local gateway authority: current build/runtime truth is desktop + src-ts, with release automation and CI validating that default path.
Governance and release helpers: Python remains for scripts, release checks, and explicit compatibility-only overrides.
Compatibility surfaces: Streamlit and legacy Python runtime paths stay visible only as labeled compatibility surfaces, not as the primary shipped UI/runtime.

🚀 Quick Start

Current Release Snapshot

v11.0.4 (2026-06-24)

Reader 端点拆分：1146 行 god module 拆分为 types / services / validation / routes，保留兼容性 shim
补齐 Reader 端点输入校验：personaId、dimension、targetStyle、focusAreas、biases、version labels 等字段长度与类型边界
Container↔MCP 解耦：gateway-bootstrap 下沉到 composition-root，IWorkflowEventRelay 接口 + 动态 require 消除静态循环
GatewayDeps ISP 拆分：6 个角色接口 + 兼容别名
craft-catalog 循环依赖破除：提取 craft-types.ts，18 个 eager const 转为 lazy getter
UI 完成度：VoiceConsistency 波浪下划线标注、plot 模板类别与 TemplateManagerPanel 集成、编辑器未保存 dirty check（beforeunload + Tauri onCloseRequested）
MCP endpoints 测试覆盖：新增 agents/m10/m11/content 路由契约测试、listTools 响应契约测试、coverage-gap-scanner 零依赖扫描脚本
M28 里程碑完成并通过集成审计（PASS，0 high/medium gaps）

v11.0.3 (2026-06-20)

修复 smoke 测试 sidecar 进程残留导致 NSIS 安装报 "Error opening file for writing"
terminate() 改用 taskkill /T 杀进程树，防止 sidecar node.exe 子进程残留锁定文件
silent_install() 安装前自动清理残留 sidecar 进程和旧安装目录

v11.0.2 (2026-06-20)

新手引导系统：首次启动自动检测配置状态，引导用户完成 LLM 提供商设置和模板选择
模板管理增强：支持模板收藏、最近使用记录、变量预设持久化
跨章节 AI 上下文：写作助手自动携带前 N 章节摘要作为上下文，提升长篇连贯性
编辑器状态持久化：自动保存编辑器滚动位置、光标位置和折叠状态
localStorage 防抖写入：减少频繁 JSON.stringify + 写盘，修复 removeItem/setItem 竞态条件
jsdom 测试环境兼容：debounce 定时器增加 localStorage 存在性守卫，消除测试 teardown 后的未捕获异常
E2E 写作流验证：完整的稿件创建→编辑→AI 辅助→导出链路测试覆盖
UI/UX 打磨：设置面板布局优化、模板选择交互改进、加载状态反馈增强
依赖与版本同步：desktop/package.json、Cargo.toml、tauri.conf.json 版本号统一至 10.0.0

Current release tag: v11.0.4
GitHub release: https://github.com/Smith-106/niko-studio/releases/tag/v11.0.4
Current local sign-off status: GO on current HEAD

如果你只想下载当前正式发布版，直接进入 GitHub Releases 页面获取 Windows 安装包。

Prerequisites

# Node.js 20+ and npm
node --version
npm --version

# Python 3.11+ (release helpers, governance scripts, compatibility launcher)
python --version

# Install Python helper dependencies
pip install -r requirements.txt

# Or use uv (recommended)
uv sync

当前默认构建与运行权威面是 desktop + src-ts。Python 主要保留给发布辅助脚本、治理脚本和显式兼容路径。

Authoritative Native Dependency Matrix

The following 7 prerequisites define the authoritative dependency matrix across developer local, Ubuntu CI, and Windows packaging:

Prerequisite	Developer local	Ubuntu CI	Windows packaging
Node.js 20 + npm 10	required for `src-ts/` and `desktop/` installs, tests, and build scripts	required	required
Python 3.11+	required for release helpers, governance scripts, and compatibility launcher paths	required	required
Rust stable + MSVC Windows target	required when building or running the Tauri host locally	not used in the current Ubuntu internal lanes	required
`better-sqlite3`	hydrated by `npm ci` in `src-ts/` before backend tests	hydrated by `npm ci` in `src-ts/` before CI tests	hydrated whenever the local backend gate is rerun on the packaging host
`fastembed` / transitive `onnxruntime-node`	hydrated by `npm ci` in `src-ts/` before embedding/runtime checks	hydrated by `npm ci` in `src-ts/` before CI tests	hydrated whenever the local backend gate is rerun on the packaging host
`pdf-parse`	hydrated by `npm ci` in `src-ts/` before import/runtime checks	hydrated by `npm ci` in `src-ts/` before CI tests	hydrated whenever the local backend gate is rerun on the packaging host
`mammoth`	hydrated by `npm ci` in `src-ts/` before DOCX import/runtime checks	hydrated by `npm ci` in `src-ts/` before CI tests	hydrated whenever the local backend gate is rerun on the packaging host

Failure-first hydration order:

pip install -r requirements.txt or uv sync
npm ci in src-ts/
npm ci in desktop/
npm --prefix desktop run build:sidecar
npm --prefix desktop run validate:sidecar-contract
npm --prefix src-ts run check:local
npm --prefix desktop run check:local
On Windows release hosts only: explicit packaging proof via npm --prefix desktop run validate:package:dry-run or the signed npm --prefix desktop run tauri:build:signed

Writer-First Desktop Delivery Contract

以下标签构成当前唯一的运行时 / 发布交付地图。Legacy 兼容性详细说明已归档至 docs/archive/LEGACY_COMPATIBILITY.md。

Supported runtime: desktop/ + Tauri host + local src-ts/ Node/TypeScript gateway. This is the shipped product, default build, and default runtime path.
Supported launcher: python scripts/start_gateway.py remains an operator-facing entrypoint, but in the current checkout it starts the Node/TypeScript gateway by default.
Advisory compatibility surfaces: explicit --runtime python legacy override, legacy src/mcp/** sources, and Streamlit validation flows only when a release candidate explicitly includes them. Details: docs/archive/LEGACY_COMPATIBILITY.md.
Deprecated surface (removed): browser-first web entry has been removed from the codebase.

单命令验收入口

python scripts/release_check_summary.py

该命令会汇总版本一致性、baseline/e2e、production 守卫（reload/CORS/metrics）、authority alignment，以及当前交付契约观察点。

轻量本地 pre-commit 门

npm --prefix desktop run local:pre-commit

这条入口只运行轻量本地提交门：desktop/src-ts lint、format check，以及 Python helper 静态检查。如需安装仓库内 hook 模板，可把 git hooks 路径指向 .githooks：

git config core.hooksPath .githooks

当前状态权威来源

当前产品 / 运行时交付契约：以本节与 docs/release/RELEASE_NOTES.md 为准。
当前本地闭环判断：以 python scripts/release_check_summary.py 输出为准。
当前 internal CI 权威入口：.github/workflows/integration-tests.yml
docs/TASKS_V10_OPTIMIZED.md 保留为历史架构路线图，不作为当前发布完成度的唯一依据。

当前权威地图

运行时 / 构建默认权威：desktop/ + src-ts/ 代码与对应脚本。
能力支持矩阵权威：docs/CAPABILITY_MATRIX.md（supported / partial / experimental / disabled / historical 单一真源）
交付契约权威：本节 Writer-First Desktop Delivery Contract + docs/release/RELEASE_NOTES.md
发布策略权威：docs/release/RELEASE_NOTES.md
本地发布快照权威：python scripts/release_check_summary.py
internal CI 权威：.github/workflows/integration-tests.yml（包含 advisory lanes，以及 main 分支的 authority alignment / selected contract hard gates）
历史参考文档：docs/TASKS_V10_OPTIMIZED.md、docs/ui_design_guide.md、docs/workflow-entrypoint-inventory.md

前端工程约束（统一口径）

本地质量入口（权威）：npm --prefix desktop run check:local
后端 / 发布 CI 权威入口：.github/workflows/external-release-gate.yml
internal CI 权威入口：.github/workflows/integration-tests.yml
Desktop CI 构建入口（build / smoke）：npm --prefix desktop run check
依赖审计：npm --prefix desktop run audit:high、npm --prefix src-ts run audit:high
当前策略：desktop / src-ts 审计信号已进入 CI；src-ts 审计当前先以 advisory 运行，待 breaking 依赖升级链完成后再提升为 blocking。
依赖更新自动化：.github/dependabot.yml（desktop、src-ts、desktop/src-tauri Cargo、pip、GitHub Actions 按月更新）
Python scripts 静态质量门：python -m ruff check --select F,I scripts tests/unit/scripts 与 python -m ruff format --check scripts tests/unit/scripts

阶段 4：执行（自主运行）

规划完成后，可运行 Aha Loop 的 PRD 自主执行循环：

# 推荐：在独立终端执行（非 Claude Code 会话）
./scripts/aha-loop/orchestrator.sh

# 若在当前会话内触发嵌套保护，请先清理变量
unset CLAUDECODE && ./scripts/aha-loop/orchestrator.sh

系统会按 Story 自动进入五阶段工作流（按需执行）：

研究：拉取依赖实现/资料并生成研究结论
并行探索：对重大决策自动创建 worktree 并并行评估方案
计划审查：根据研究/探索结果调整实现计划
实现：按验收标准落地代码改动
质量检查：执行质量门禁并验证验收条件

说明：AI 会自主判断阶段是否需要执行，但最终发布准入仍以项目质量基线与门禁结果为准。

安全意图可见化（摘要）

运行时守卫、构建门禁、fallback/rollback 与发布前清单集中见：
- docs/SECURITY_VISIBILITY.md
回滚操作手册：
- docs/operations/ROLLBACK.md

Initialize Database

# Gateway runtime 会在首次启动时初始化所需存储
# 如需手动验证 TypeScript 运行面
npm --prefix src-ts run typecheck

构建 Desktop Sidecar

# 默认：Node sidecar（Node-first）
npm --prefix desktop run build:sidecar

# Sidecar/runtime contract must pass before downstream desktop gates claim success
npm --prefix desktop run validate:sidecar-contract

# Explicit packaging proof is a stricter Windows release-host check
npm --prefix desktop run validate:package:dry-run
# 当前 checkout 默认不包含该 legacy entry
# 正式 release 如需走 packaged fallback，需预先准备 `desktop/src-tauri/bin/niko-gateway*.exe`
python scripts/build_gateway_sidecar.py --legacy-entry src/mcp/sidecar_entry.py

运行 Gateway

# 默认（auto）：启动 Node/TypeScript Gateway
python scripts/start_gateway.py --host 0.0.0.0 --port 8000

# 生产环境（按配置启动）
python scripts/start_gateway.py --env production --config config/niko-studio.production.yaml --host 0.0.0.0 --port 8000

# 显式 Python 兼容回退（仅 legacy src/mcp/gateway.py 存在时可用）
python scripts/start_gateway.py --runtime python --host 0.0.0.0 --port 8000

Windows 本地如果常见 8000 端口占用，可优先使用仓库内启动器。它会自动复用已有健康 gateway，或回退到 8010 / 空闲端口，并把桌面进程显式指向该地址：

./scripts/start_desktop_local.ps1

若使用 cmd.exe，可直接运行 scripts\start_desktop_local.cmd、scripts\stop_desktop_local.cmd、scripts\status_desktop_local.cmd、scripts\selftest_desktop_local.cmd。若从现有 desktop npm 入口使用，也可执行 npm --prefix desktop run local:start、local:start:force、local:start:binary、local:start:binary:force、local:gateway、local:status、local:stop、local:selftest。

常用参数：

-BinaryDesktop: 直接启动已编译桌面二进制
-NoDesktop: 只拉起 / 复用 gateway
-ForceDesktop: 即使已有桌面窗口也强制新开实例
-PreferredPort / -FallbackPort: 覆盖默认的 8000 / 8010

若只想拉起 / 复用 gateway 而不打开桌面窗口，可直接执行 npm --prefix desktop run local:gateway。若要只跑 Vite 前端壳、但仍自动跟随本地启动器记录的健康 gateway 地址，可先执行 npm --prefix desktop run local:gateway，再执行 npm --prefix desktop run local:shell。

停止由本地启动器新拉起的进程：

./scripts/stop_desktop_local.ps1

查看当前本地启动器状态：

./scripts/status_desktop_local.ps1

验证本地启动链路：

./scripts/selftest_desktop_local.ps1

可用运维端点：

GET /health
GET /metrics
GET /tools
POST /chat

POST /chat 响应字段补充（兼容性说明）：

writer_metadata（optional）
- warnings?: string[]（当前包含 Writer 的非阻断告警代码前缀，如 knowledge_retrieval_failed、openai_proxy_fallback_failed）
- knowledge_retrieved?: { entities_count: number, relations_count: number, memories_count: number }

Run Frontend Shell Only (Advisory Compatibility)

# 仅启动 Vite 前端壳层，不包含完整桌面运行时
npm --prefix desktop run dev

完整桌面链路仍以 python scripts/start_gateway.py + npm --prefix desktop run tauri:dev 为准。 Windows 上如需自动处理 gateway 端口冲突，可直接使用 ./scripts/start_desktop_local.ps1。如需用浏览器壳复验但避免回退到默认 127.0.0.1:8000，可先运行 npm --prefix desktop run local:gateway，再运行 npm --prefix desktop run local:shell。

📁 Project Structure

niko-studio/
├── desktop/                    # 当前桌面产品入口（React + Tauri）
│   ├── src/                    # 前端 UI、hooks、stores、API client 与组件测试
│   └── src-tauri/              # Tauri/Rust 宿主、sidecar 启动与打包产物
├── src-ts/                     # 当前本地 Node/TypeScript gateway 与核心服务
│   ├── agents/                 # 写作与编排 agents
│   ├── mcp/                    # MCP / HTTP endpoints 与服务接线
│   ├── workflow/               # 工作流编排与状态流转
│   ├── narrative/              # 叙事分析与评估逻辑
│   ├── memory/                 # 记忆与知识相关能力
│   ├── search/ graph/ store/   # 检索、图谱与存储能力
│   └── tests/                  # TypeScript 后端测试
├── scripts/                    # 启动器、版本校验、authority alignment、release summary
├── config/                     # 本地/生产 YAML 配置
├── tests/                      # Python 单元测试（当前主要覆盖治理/脚本）
├── docs/                       # 发布契约、runbook、架构与历史参考
├── release-check-summary.md    # 最近一次本地发布检查快照
└── README.md

🛠️ Technology Stack

Area	Current choice
Desktop UI	React 18 + TypeScript + Vite + Tailwind CSS + Zustand
Desktop host	Tauri 2 (Rust)
Local gateway	Node.js + TypeScript (`src-ts/`)
Runtime / parsing	`better-sqlite3`, `fastembed`, `mammoth`, `pdf-parse`
Release / governance	Python 3.11+ scripts in `scripts/`
Test stack	Vitest (`desktop/`, `src-ts/`) + targeted pytest (`tests/`)

✅ Current Validation Entrypoints

发布 evidence 单入口刷新：npm --prefix desktop run release:evidence:refresh
安装包级 E2E 留痕入口：npm --prefix desktop run package:e2e:checklist
本地 pre-commit 质量门：npm --prefix desktop run local:pre-commit
提交前启用 hook：python -m pre_commit install
Desktop 本地验收：npm --prefix desktop run check:local
Gateway 本地验收：npm --prefix src-ts run check:local
发布汇总快照：python scripts/release_check_summary.py
权威对齐检查：python scripts/check_authority_alignment.py
测试分级执行矩阵：docs/testing/TEST_TIER_MATRIX.md
发布契约：docs/release/RELEASE_NOTES.md
Desktop 运维手册：docs/operations/DESKTOP_RUNBOOK.md

📚 Documentation

文档索引 - 文档导航与当前发布口径
Test Tier Matrix - 当前有效的 L1-L4 测试分级与执行建议
System Design - 系统设计与模块规格
Release Notes - 发布矩阵与 Go/No-Go 条件
Desktop Runbook - Desktop 运行、验收与排障
Rollback Runbook - 回滚手册
Task List (V10 Optimized) - 历史架构路线图

📄 License

当前仓库使用 MIT 许可协议，详见根目录 LICENSE 文件。

🙏 Acknowledgments

Built on concepts from:

Cherry Studio - AI Assistant Platform
Claude-Code-Workflow - Workflow Patterns
OpenKL - Open Knowledge Layer

Version 11.0.3 Platform Edition | Updated: 2026-06-20

Name		Name	Last commit message	Last commit date
.claude		.claude
.githooks		.githooks
.github		.github
.workflow		.workflow
arch-to-diagram-prompts/arch-to-diagram-prompts		arch-to-diagram-prompts/arch-to-diagram-prompts
config		config
desktop		desktop
docs-site		docs-site
docs		docs
scripts		scripts
skills		skills
src-ts		src-ts
tests/unit/scripts		tests/unit/scripts
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.maestroignore		.maestroignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CUsersnikoDesktop工作目录niko-studio.workflowharvestorphans-raw.json		CUsersnikoDesktop工作目录niko-studio.workflowharvestorphans-raw.json
CUsersnikoDesktop工作目录niko-studio.workflowharvestwiki-list-raw.json		CUsersnikoDesktop工作目录niko-studio.workflowharvestwiki-list-raw.json
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
prettier.config.mjs		prettier.config.mjs
project.vision.md		project.vision.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Niko Studio

🎯 Product Overview

✨ Writer-Facing Capabilities

🚀 Quick Start

Current Release Snapshot

v11.0.4 (2026-06-24)

v11.0.3 (2026-06-20)

v11.0.2 (2026-06-20)

Prerequisites

Authoritative Native Dependency Matrix

Writer-First Desktop Delivery Contract

单命令验收入口

轻量本地 pre-commit 门

当前状态权威来源

当前权威地图

前端工程约束（统一口径）

阶段 4：执行（自主运行）

安全意图可见化（摘要）

Initialize Database

构建 Desktop Sidecar

运行 Gateway

Run Frontend Shell Only (Advisory Compatibility)

📁 Project Structure

🛠️ Technology Stack

✅ Current Validation Entrypoints

📚 Documentation

📄 License

🙏 Acknowledgments

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Niko Studio

🎯 Product Overview

✨ Writer-Facing Capabilities

🚀 Quick Start

Current Release Snapshot

v11.0.4 (2026-06-24)

v11.0.3 (2026-06-20)

v11.0.2 (2026-06-20)

Prerequisites

Authoritative Native Dependency Matrix

Writer-First Desktop Delivery Contract

单命令验收入口

轻量本地 pre-commit 门

当前状态权威来源

当前权威地图

前端工程约束（统一口径）

阶段 4：执行（自主运行）

安全意图可见化（摘要）

Initialize Database

构建 Desktop Sidecar

运行 Gateway

Run Frontend Shell Only (Advisory Compatibility)

📁 Project Structure

🛠️ Technology Stack

✅ Current Validation Entrypoints

📚 Documentation

📄 License

🙏 Acknowledgments

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages