ai-title-siyuan

Imported from wmy2981/ai-title-siyuan (AGENTS.md). Install upstream with npx skills add wmy2981/ai-title-siyuan. Copyright stays with the author.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

• npm run typecheck — tsc --noEmit. Run after touching src/.
• npm run build — vite build && node scripts/build-package.mjs. Emits package.zip at the repo root. Run after typecheck for anything that could affect bundling.
• npm run dev — watch build.
• npm run icon — re-renders assets/icon.png, then quantizes assets/preview.png in place.

There is no test framework and no linter in this repo. Do not add one unprompted — verification is npm run typecheck plus npm run build, and loading the plugin in SiYuan.

Build constraints

The bundle must stay CommonJS. SiYuan's plugin loader wraps plugin code in (function anonymous(require, module, exports){...}) and evals it, so ESM output dies at runtime with SyntaxError: Cannot use import statement outside a module. Keep formats: ["cjs"] and the index.js entry in vite.config.ts, and keep siyuan external — the host injects it.

dist/, package.zip, index.js, index.css, kernel.js and i18n/ are build outputs and gitignored. Never edit or commit them. scripts/build-package.mjs performs the packaging renames (README.zh-CN.md → README_zh_CN.md, src/i18n/ → i18n/).

scripts/render-preview.mjs mutates assets/preview.png in place and double-quantizes if run twice. It needs a manual Chrome screenshot of assets/preview.html at exactly 1024x768 taken first, and fails above 512 KiB.

Release

.github/workflows/release.yml runs on every push to main. Bump plugin.json and package.json to the same version — CI errors out if they differ — and it must be higher than the latest v* tag. Pushing to main tags and publishes the release automatically.

Conventions

• Conventional Commits in English, imperative, lowercase description (e.g. fix(api): disable thinking with reasoning_effort). Commit in separate logical points, not one lump.
• Code comments are in Chinese. User-facing strings are never hardcoded — put them in both src/i18n/en.json and src/i18n/zh-CN.json, which must keep identical key sets.
• Strict TypeScript with noUnusedLocals, noUnusedParameters and verbatimModuleSyntax. An unreferenced local or function is a build error, not a warning — export deliberately-retained code rather than leaving it dead.
• Deprecated settings fields are cleared in mergeSettings (src/config.ts) and must never be reintroduced into the request body.