From a4595e4d7c6bd9b64bfccb58726cf4aa84d7c92a Mon Sep 17 00:00:00 2001 From: aliyun1121003339 Date: Sat, 11 Jul 2026 20:34:23 +0800 Subject: [PATCH] docs(settings): plan history and navigation delivery --- ...istory-settings-navigation-batch-folder.md | 151 ++++++++++++++++++ ...-settings-navigation-batch-folder.zh-CN.md | 83 ++++++++++ 2 files changed, 234 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-11-vault-history-settings-navigation-batch-folder.md create mode 100644 docs/superpowers/plans/2026-07-11-vault-history-settings-navigation-batch-folder.zh-CN.md diff --git a/docs/superpowers/plans/2026-07-11-vault-history-settings-navigation-batch-folder.md b/docs/superpowers/plans/2026-07-11-vault-history-settings-navigation-batch-folder.md new file mode 100644 index 00000000..5b797eb4 --- /dev/null +++ b/docs/superpowers/plans/2026-07-11-vault-history-settings-navigation-batch-folder.md @@ -0,0 +1,151 @@ +# Vault History, Settings Navigation, And Batch Folder Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Deliver Vault-persistent diagram history, fuzzy-searchable settings with category navigation and favorites, safe batch target-folder preparation, and synchronized multilingual README guidance. + +**Architecture:** Add focused domain modules for history queries, setting catalog/search, and batch-folder policy. Existing Obsidian UI classes consume those modules and remain responsible only for rendering and user interaction. Plugin settings persist lightweight indexes and preferences; generated artifacts stay as Vault files. + +**Tech Stack:** TypeScript, Obsidian Plugin API, Jest, existing i18n registry, Markdown README localization. + +## Global Constraints + +- Default history order is completion time descending and default page size is 20. +- History is Vault-scoped and stores paths/metadata, never duplicated binary or SVG bodies. +- Missing batch folders may be auto-created only after explicit opt-in; non-empty folders require one confirmation per batch invocation. +- CLI/non-interactive calls never silently create or authorize a non-empty folder. +- Every design, plan, and progress document has separate English and Simplified Chinese files. +- Use TDD for every behavior change and finish with fresh build, full Jest, `git diff --check`, Obsidian CLI integration, push to `main`, and a clean worktree. + +--- + +### Task 1: Persistent Diagram History Domain + +**Files:** +- Create: `src/diagram/history/diagramHistoryRepository.ts` +- Create: `src/diagram/history/diagramHistoryQuery.ts` +- Modify: `src/types.ts` +- Modify: `src/constants.ts` +- Test: `src/tests/diagramHistoryRepository.test.ts` + +**Interfaces:** +- Produces `DiagramHistoryEntry`, `DiagramHistoryQuery`, `DiagramHistoryPage`. +- Produces `createDiagramHistoryRepository(load, save)` with `recordCompleted`, `query`, `get`, and `removeIndexEntry`. + +- [ ] Write failing tests proving descending ordering, normalized fuzzy text, filters, 20-item paging, retention pruning, and clone-safe results. +- [ ] Run `npm test -- --runInBand src/tests/diagramHistoryRepository.test.ts` and confirm failures are caused by missing modules. +- [ ] Implement pure query functions and serialized repository writes; pruning must remove index records only. +- [ ] Re-run the targeted tests and commit `feat(diagrams): persist vault diagram history`. + +### Task 2: History Recording And Management UI + +**Files:** +- Create: `src/ui/DiagramHistoryModal.ts` +- Modify: `src/ui/diagramPreviewHistory.ts` +- Modify: `src/ui/DiagramPreviewModal.ts` +- Modify: `src/main.ts` +- Modify: `src/i18n/locales/en.ts` +- Modify: `src/i18n/locales/zh_cn.ts` +- Test: `src/tests/diagramPreviewModal.test.ts` +- Test: `src/tests/diagramHistoryModal.test.ts` + +**Interfaces:** +- Consumes the Task 1 repository. +- Produces a modal query state `{search, intent, target, exportKind, sourcePath, from, to, page, pageSize}`. + +- [ ] Write failing tests for recording only completed renders, recent-history limits, opening the full manager, filter reset, next/previous page boundaries, and index-only deletion. +- [ ] Verify the tests fail before implementation. +- [ ] Implement compact recent history in the preview and a dedicated Vault history modal with search, filters, paging, reopen, source-note navigation, export availability, and separately confirmed artifact deletion. +- [ ] Run both targeted suites and commit `feat(diagrams): add vault history manager`. + +### Task 3: Stable Settings Catalog And Fuzzy Search + +**Files:** +- Create: `src/ui/settings/settingCatalog.ts` +- Create: `src/ui/settings/settingSearch.ts` +- Modify: `src/ui/NotemdSettingTab.ts` +- Modify: `src/types.ts` +- Modify: `src/constants.ts` +- Test: `src/tests/settingCatalog.test.ts` +- Test: `src/tests/providerSettingsBehavior.test.ts` + +**Interfaces:** +- Produces `SettingCatalogEntry {id, categoryId, name, description, aliases, advanced}`. +- Produces `searchSettingCatalog(entries, query)` with normalized substring plus ordered-token fuzzy matching. + +- [ ] Write failing tests for stable unique IDs, required category coverage, Chinese/English query normalization, typo-tolerant ordered matching, and empty-query behavior. +- [ ] Verify RED with the targeted Jest command. +- [ ] Implement catalog/search without reading DOM text and annotate existing setting groups with stable IDs. +- [ ] Re-run tests and commit `feat(settings): add searchable setting catalog`. + +### Task 4: Category Rail And Favorites + +**Files:** +- Create: `src/ui/settings/SettingsNavigation.ts` +- Modify: `src/ui/NotemdSettingTab.ts` +- Modify: `styles.css` +- Modify: `src/i18n/locales/en.ts` +- Modify: `src/i18n/locales/zh_cn.ts` +- Test: `src/tests/providerSettingsBehavior.test.ts` +- Test: `src/tests/providerSettingsStyles.test.ts` + +**Interfaces:** +- Consumes stable setting/category IDs from Task 3. +- Persists `favoriteSettingIds: string[]` in `NotemdSettings`. + +- [ ] Write failing UI contract tests for category navigation, favorites surviving locale changes, unknown-ID suppression, search result grouping, keyboard focus, and narrow-layout adaptation. +- [ ] Run tests and confirm expected failures. +- [ ] Implement the Codex-inspired compact rail, favorites entry, search header, result counts, and responsive horizontal navigation while preserving Obsidian Setting controls. +- [ ] Run targeted UI/style tests and commit `feat(settings): add navigation and favorites`. + +### Task 5: Batch Target Folder Preparation + +**Files:** +- Create: `src/operations/batchTargetFolderPreparation.ts` +- Modify: `src/operations/noteProcessingCommandHostAdapter.ts` +- Modify: `src/fileUtils.ts` +- Modify: `src/types.ts` +- Modify: `src/constants.ts` +- Modify: `src/i18n/locales/en.ts` +- Modify: `src/i18n/locales/zh_cn.ts` +- Test: `src/tests/batchTargetFolderPreparation.test.ts` +- Test: `src/tests/noteProcessingCommands.test.ts` + +**Interfaces:** +- Produces `prepareBatchTargetFolder(request): Promise<{status:'ready'|'cancelled'|'requires-interaction'; path:string}>`. +- Host supplies `inspectPath`, `createFolder`, and one batch-level `confirm` operation. + +- [ ] Write failing tests for missing/empty/non-empty/file collision, remembered missing-folder creation, one confirmation for a non-empty batch, cancellation without error logging, and non-interactive recoverable outcomes. +- [ ] Run targeted tests and confirm failures. +- [ ] Implement edge validation and call it before title-generation enumeration; remove the late generic invalid-folder failure for this command path. +- [ ] Re-run tests and commit `fix(batch): prepare configured target folders safely`. + +### Task 6: README And Multilingual Documentation + +**Files:** +- Modify: `README.md` +- Modify: `README_zh.md` +- Modify: existing localized `README*.md` files +- Create: `docs/maintainer/vault-history-settings-navigation-progress-2026-07-11.md` +- Create: `docs/maintainer/vault-history-settings-navigation-progress-2026-07-11.zh-CN.md` +- Modify: `src/tests/docsBilingualSupport.test.ts` + +**Interfaces:** +- Documents the same setting categories and stable user-facing behavior implemented in Tasks 1-5. + +- [ ] Write failing documentation contract assertions for history management, settings search/navigation/favorites, missing-folder auto-create, and per-batch non-empty confirmation across all supported README locales. +- [ ] Run the contract test and confirm missing guidance failures. +- [ ] Update English canonical sections, translate bounded sections to every existing README locale, and add bilingual progress/architecture comparison documents. +- [ ] Re-run documentation tests and commit `docs: explain settings and history workflows`. + +### Task 7: Integration, Visual Audit, And Main Delivery + +**Files:** +- Modify only files required by failures found during verification. + +- [ ] Run targeted suites for all six tasks. +- [ ] Run `npm run build`, `npm test -- --runInBand`, `npm run audit:i18n-ui`, and `git diff --check`. +- [ ] Reload the plugin with `Obsidian.com`, verify history survives reload, exercise search/favorites, and test missing plus non-empty batch folders with the configured model. +- [ ] Update both progress documents with exact evidence and remaining architectural direction. +- [ ] Inspect the complete diff, commit any verification fixes, push `main`, and confirm `git status` is clean. + diff --git a/docs/superpowers/plans/2026-07-11-vault-history-settings-navigation-batch-folder.zh-CN.md b/docs/superpowers/plans/2026-07-11-vault-history-settings-navigation-batch-folder.zh-CN.md new file mode 100644 index 00000000..df6b9f18 --- /dev/null +++ b/docs/superpowers/plans/2026-07-11-vault-history-settings-navigation-batch-folder.zh-CN.md @@ -0,0 +1,83 @@ +# Vault 历史、设置导览与批处理文件夹实施计划 + +> **面向执行者：** 必须使用 `superpowers:subagent-driven-development`（推荐）或 `superpowers:executing-plans` 按任务执行。本计划使用复选框跟踪步骤。 + +**目标：** 交付 Vault 持久化图形历史、带大类导览和收藏的模糊设置搜索、安全批处理目标文件夹准备，以及同步的多语言 README 指南。 + +**架构：** 为历史查询、设置目录/搜索和批处理文件夹策略建立独立领域模块。现有 Obsidian UI 类只消费这些模块并负责界面交互。插件设置保存轻量索引与偏好，生成产物继续作为 Vault 文件存在。 + +**技术栈：** TypeScript、Obsidian Plugin API、Jest、现有 i18n registry、Markdown README 本地化。 + +## 全局约束 + +- 历史默认按完成时间倒序，每页默认 20 条。 +- 历史按 Vault 保存，只记录路径和元数据，不重复保存二进制或 SVG 正文。 +- 缺失批处理文件夹只有在用户明确选择后才可自动创建；非空文件夹每次批处理调用确认一次。 +- CLI/无交互调用不能静默创建文件夹或授权非空文件夹。 +- 每份设计、计划和进度文档都有独立英文与简体中文文件。 +- 所有行为变更使用 TDD；最终必须重新执行构建、全量 Jest、`git diff --check`、Obsidian CLI 集成测试，推送 `main` 并保持工作区 clean。 + +--- + +### 任务 1：持久化图形历史领域 + +**文件：** 新建 `src/diagram/history/diagramHistoryRepository.ts`、`diagramHistoryQuery.ts` 和 `src/tests/diagramHistoryRepository.test.ts`；修改 `src/types.ts`、`src/constants.ts`。 + +- [ ] 先编写排序、模糊搜索、筛选、20 条分页、保留上限和克隆安全的失败测试。 +- [ ] 运行目标 Jest，确认因模块缺失而失败。 +- [ ] 实现纯查询函数和串行持久化仓库；清理只删除索引。 +- [ ] 目标测试通过后提交 `feat(diagrams): persist vault diagram history`。 + +### 任务 2：历史记录与管理界面 + +**文件：** 新建 `src/ui/DiagramHistoryModal.ts`、`src/tests/diagramHistoryModal.test.ts`；修改预览历史、预览弹窗、`main.ts`、中英文 i18n 和相关测试。 + +- [ ] 为只记录已完成渲染、近期数量限制、打开完整管理器、筛选重置、分页边界和只删索引编写失败测试。 +- [ ] 确认 RED。 +- [ ] 实现紧凑近期历史和独立 Vault 历史弹窗，包括搜索、筛选、分页、重新预览、来源定位、导出状态和分离确认的产物删除。 +- [ ] 目标测试通过后提交 `feat(diagrams): add vault history manager`。 + +### 任务 3：稳定设置目录与模糊搜索 + +**文件：** 新建 `src/ui/settings/settingCatalog.ts`、`settingSearch.ts`、`src/tests/settingCatalog.test.ts`；修改设置页、类型、默认值和现有设置行为测试。 + +- [ ] 为稳定唯一 ID、分类覆盖、中英文规范化、拼写容错有序匹配和空查询编写失败测试。 +- [ ] 确认 RED。 +- [ ] 实现不依赖 DOM 文本的目录和搜索，并为现有设置组补充稳定 ID。 +- [ ] 通过测试后提交 `feat(settings): add searchable setting catalog`。 + +### 任务 4：大类导览与收藏 + +**文件：** 新建 `src/ui/settings/SettingsNavigation.ts`；修改设置页、`styles.css`、中英文 i18n 和 UI/style 测试。 + +- [ ] 为分类跳转、收藏跨语言稳定、未知 ID 隐藏、搜索分组、键盘焦点和窄布局编写失败测试。 +- [ ] 确认 RED。 +- [ ] 实现 Codex 风格紧凑导览、收藏入口、搜索头部、结果数量和响应式横向导航。 +- [ ] 通过测试后提交 `feat(settings): add navigation and favorites`。 + +### 任务 5：批处理目标文件夹准备 + +**文件：** 新建 `src/operations/batchTargetFolderPreparation.ts` 和对应测试；修改 command host、`fileUtils.ts`、设置类型/默认值与中英文 i18n。 + +- [ ] 为缺失、空、非空、文件冲突、记忆自动创建、整批一次确认、取消不记错误和无交互可恢复结果编写失败测试。 +- [ ] 确认 RED。 +- [ ] 在从标题批量生成枚举文件前调用统一准备器，并移除该路径过晚的通用 invalid-folder 错误。 +- [ ] 通过测试后提交 `fix(batch): prepare configured target folders safely`。 + +### 任务 6：README 与多语言文档 + +**文件：** 修改英文、中文及所有现有本地化 README；新建中英文进度文档；修改文档契约测试。 + +- [ ] 为历史管理、设置搜索/导览/收藏、缺失文件夹自动创建和非空文件夹整批确认编写失败契约测试。 +- [ ] 确认各语言因缺失说明而失败。 +- [ ] 更新英文 canonical 内容，翻译受控片段到所有现有 README locale，并记录架构对比与进度。 +- [ ] 通过测试后提交 `docs: explain settings and history workflows`。 + +### 任务 7：集成、视觉审计与 main 交付 + +- [ ] 运行全部目标测试。 +- [ ] 运行构建、全量 Jest、i18n UI 审计和 `git diff --check`。 +- [ ] 通过 `Obsidian.com` 重载插件，验证历史重载持久化、搜索/收藏，以及缺失和非空批处理文件夹。 +- [ ] 将准确证据和后续架构方向写入中英文进度文档。 +- [ ] 检查完整 diff，提交验证修复，推送 `main` 并确认工作区 clean。 +