diff --git a/.codex/skills/llm-wiki-for-backlog/SKILL.md b/.codex/skills/llm-wiki-for-backlog/SKILL.md new file mode 100644 index 000000000..894741e19 --- /dev/null +++ b/.codex/skills/llm-wiki-for-backlog/SKILL.md @@ -0,0 +1,397 @@ +--- +name: llm-wiki-for-backlog +description: "Build and maintain LLM-powered personal knowledge bases using the Karpathy Wiki pattern, adapted for Backlog.md workflow. The LLM incrementally compiles backlog sources into a persistent, interlinked markdown wiki. Trigger: 'build wiki', 'init wiki', 'ingest', 'process source', 'wiki query', 'lint wiki', 'health check', 'knowledge base', '知识库', '整理', '摄取'." +--- + +# LLM Wiki Skill (Backlog.md Adaptation) + +Personal knowledge base where the LLM is the sole maintainer. Human feeds sources via Backlog.md and asks questions. LLM compiles, cross-references, and maintains everything. + +## Core Idea + +**This is NOT RAG.** RAG re-derives knowledge from scratch on every query — no accumulation. Here, the LLM **incrementally compiles** backlog sources into a persistent, interlinked wiki. Knowledge is built once and kept current. The wiki is a compounding artifact: every source added and every question asked makes it richer. + +- **Human's two jobs:** Feed raw materials into Backlog.md. Ask good questions. +- **LLM's job:** Everything else — summarize, cross-reference, file, maintain, lint. +- **The wiki:** A living, compiled artifact that only grows. + +> Backlog.md is the IDE. The LLM is the programmer. The wiki is the codebase. + +--- + +## Architecture + +### Three Content Layers + Schema + +``` +{project-root}/ +├── src/ # Project source code (optional raw source when backlog lives inside a project repo) +├── {backlog}/ # Backlog.md working directory +│ ├── tasks/ # Layer 1: Human input. Tasks, issues, requirements. +│ ├── docs/ # Layer 1: Human input. Documents, guides, references. +│ ├── decisions/ # Layer 1: Human input. ADRs, decision records. +│ ├── drafts/ # Layer 1: Human input. Draft ideas, WIP notes. +│ ├── milestones/ # Layer 1: Human input. Milestone definitions and tracking. +│ ├── archive/ # Layer 1: Human input. Archived tasks and records. +│ ├── completed/ # Layer 1: Human input. Completed task records. +│ ├── assets/ # Layer 1: Human input. Images, attachments, resources. +│ ├── wiki/ # Layer 2: LLM maintains entirely. Human reads/browses. +│ │ ├── index.md # Content catalog — LLM's navigation map +│ │ ├── log.md # Chronological ops log (append-only) +│ │ ├── overview.md # High-level synthesis of the entire knowledge base +│ │ ├── sources/ # One summary per backlog source (task, doc, decision, etc.) +│ │ ├── concepts/ # Concept articles extracted from backlog +│ │ ├── entities/ # People, tools, projects, orgs mentioned in backlog +│ │ ├── comparisons/ # Cross-cutting analyses across tasks/docs/decisions +│ │ └── usermanual/ # Optional: structured user manual (see UserManual section below) +│ └── wiki_output/ # Layer 3: Query products. Valuable results → flow back to wiki/ +│ ├── reports/ +│ ├── slides/ # Marp format +│ └── charts/ # matplotlib / visualization +└── ... # Other project files (config, tests, etc.) +``` + +**Iron rules:** +1. **Backlog folders (`tasks/`, `docs/`, `decisions/`, `drafts/`, `milestones/`, `archive/`, `completed/`, `assets/`) are immutable** — the LLM NEVER modifies backlog source files +2. `wiki/` is **LLM-owned** — human reads/browses, LLM writes everything +3. `wiki_output/` → `wiki/` **flowback** is the compounding mechanism +4. **NEVER recursively process `wiki/` or `wiki_output/` themselves** — they live inside the backlog directory but are excluded from ingestion +5. **Project source code directories are optional raw sources** — When the backlog directory lives inside a project repository, sibling source directories (e.g. `src/`, `lib/`, `packages/`) may also be ingested as an extension of the raw layer + +### Project Source Code (Optional Raw Source) + +When `backlog/` resides inside a project repository, the project source code directories at the same level as (or parent to) the backlog folder may also be ingested: + +| Directory | Purpose | Ingest Strategy | +|---|---|---| +| `src/` | Implementation source files, modules, components | Extract architectural patterns, API surfaces, module boundaries | +| `lib/` | Shared libraries, utility code | Extract reusable patterns, dependency graphs | +| `packages/` | Monorepo packages | Extract package boundaries, inter-package contracts | +| Repository root | Config files, entry points | Extract build setup, entry-point structure | + +**Source code exclusions (always apply):** +- Build artifacts: `dist/`, `build/`, `out/`, `.next/`, `coverage/` +- Dependency directories: `node_modules/`, `vendor/`, `.venv/`, `target/` +- Generated files: auto-generated API clients, protobuf outputs (unless hand-edited) +- Lockfiles: treat as metadata only (do not ingest as primary source) +- Binary assets: images, videos, fonts (skip unless semantically relevant) + +### Backlog Folder Purposes (Raw Layer) + +| Folder | Purpose | Ingest Strategy | +|---|---|---| +| `tasks/` | Active and pending tasks with requirements, acceptance criteria, implementation notes | Extract requirements, technical specs, decisions made during implementation | +| `docs/` | Project documentation, guides, API references, READMEs | Extract domain knowledge, technical concepts, conventions | +| `decisions/` | Architecture Decision Records (ADRs), design choices, rationale | Extract decision context, trade-offs, rejected alternatives | +| `drafts/` | Draft ideas, brainstorming notes, work-in-progress thoughts | Extract nascent concepts before they mature into tasks or docs | +| `milestones/` | Milestone definitions, roadmap items, release plans | Extract high-level goals, dependencies, timeline context | +| `archive/` | Archived tasks and records no longer active | Historical context, patterns from past work | +| `completed/` | Completed task records with final summaries | Lessons learned, successful patterns, outcome documentation | +| `assets/` | Images, diagrams, attachments referenced by backlog items | Visual context, diagrams as knowledge sources | + +### Wiki Guidelines in Agent Instructions + +The wiki does not maintain a separate schema file. All wiki-related guidelines, conventions, and rules are stored directly in the project's existing Backlog.md agent instruction file (`CLAUDE.md`, `AGENTS.md`, or `GEMINI.md` in the project root). + +**When `build wiki` is triggered:** +1. Locate the project's agent instruction file (whichever exists: `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`) +2. Check if it already contains a `` marker +3. If not present, inject the wiki guidelines section (see "Wiki Guidelines Content" below) into the agent file +4. If already present, skip injection to avoid duplication + +**When wiki conventions evolve:** +- Update the wiki section directly within the project's agent instruction file +- Do NOT create separate files for wiki schema or conventions +- The agent file is the single source of truth for both backlog workflow and wiki knowledge base rules + +### Two Navigation Files + +- **`index.md`** — Content-oriented catalog of every wiki page with one-line summaries, organized by labels. The LLM reads this FIRST on any operation. Updated on every ingest. +- **`log.md`** — Chronological, append-only timeline. Format: `## [YYYY-MM-DD HH:mm:ss] {op} | {title}`. Parseable with `grep "^## \[" log.md`. Shows what happened when. The detailed timestamp enables git-aware incremental ingestion. + +--- + +## Operations + +### 1. Init + +**Trigger:** "build wiki", "init wiki", "搭建知识库", or any request to create a knowledge base. + +**Prerequisite Check:** + +Before building the wiki, verify that Backlog.md has been initialized in the project: + +1. Check for the existence of `backlog/config.yml` or `.backlog/config.yml` (or `backlog.config.yml` in the project root) +2. Check that the backlog directory structure exists (`backlog/tasks/`, `backlog/docs/`, etc.) + +**If Backlog.md is NOT initialized:** +- **STOP** the wiki build process immediately +- Inform the user: "This project has not been initialized with Backlog.md. Please run `backlog init` first to set up the project structure, then we can build the wiki." +- Do NOT proceed with wiki creation until `backlog init` has been completed + +**If Backlog.md IS initialized:** + +1. **Understand the domain** — Ask: What topic/purpose? What backlog content do you have? What outputs do you care about? Also identify any project source directories to include (e.g. `src/`, `lib/`, `packages/`). +2. **Create `backlog/wiki/` directory structure** inside the Backlog.md working directory +3. **Inject wiki guidelines into the agent instruction file** — Locate the project's agent file (`CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`). If it does not already contain wiki guidelines, append the "Wiki Guidelines Content" section (defined below) to the file using `` / `` markers. +4. **Generate `wiki/index.md`** — Empty catalog with sections matching wiki subdirectories +5. **Generate `wiki/log.md`** — First entry: initialization +6. **Generate `wiki/overview.md`** — Placeholder awaiting first source +7. **Recommend setup:** Ensure wiki/ and wiki_output/ are in .gitignore if needed + +### 2. Ingest + +**Trigger:** "ingest this", "process this", "摄取", or referencing a new source to add. + +**Exclusion rules (CRITICAL):** +- **NEVER** read or process files inside `backlog/wiki/` or `backlog/wiki_output/` +- **NEVER** ingest the wiki's own generated content as raw source +- Primary ingest sources: `tasks/`, `docs/`, `decisions/`, `drafts/`, `milestones/`, `archive/`, `completed/`, `assets/` +- Optional ingest sources: configured project source directories (e.g. `src/`, `lib/`) — exclude build artifacts, dependencies, and generated files + +**Single source:** +1. Read the source thoroughly +2. Discuss key takeaways with user (3–5 bullets) +3. Create summary page in `wiki/sources/` with frontmatter linking back to original backlog file + - In the page body, include a **Related Concepts** section listing linked concepts using `[[concepts/concept-name]]` + - Include a **Related Sources** section (if applicable) using `[[sources/other-source-name]]` +4. For each significant concept → create or **update** page in `wiki/concepts/` + - In the concept page, include **Related Concepts** and **Related Sources** sections with `[[wikilinks]]` +5. For each significant entity → create or **update** page in `wiki/entities/` + - In the entity page, include **Related Entities**, **Related Concepts**, and **Related Sources** sections with `[[wikilinks]]` +6. Update `wiki/index.md` with all new/changed pages +7. Update `wiki/overview.md` if the big picture shifts +8. Append to `wiki/log.md` with full timestamp `## [YYYY-MM-DD HH:mm:ss] {op} | {title}` + +**Batch ingest all backlog content:** + +1. **Determine the ingestion baseline** — Parse `wiki/log.md` to find the most recent `ingest` or `batch-ingest` entry and extract its timestamp. This is the baseline for incremental detection. + +2. **Detect changed files (git-aware)** — Check if the project is inside a git repository: + - **If git is available and the project is a git repo:** + - Run `git status --porcelain` to list unstaged/untracked changes + - Run `git log --since="{last_ingest_timestamp}" --name-only --pretty=format:` to list files changed in commits since the last ingestion + - Combine both sets. A file is considered "updated" if it appears in either result. + - Filter the combined set to only include files within the ingest source directories (backlog folders and configured project source directories). + - **If git is not available or git commands fail:** + - Fall back to full directory scanning (existing behavior: scan all source directories and cross-reference `log.md` for un-ingested files). + +3. **Skip unchanged files** — If a file is not in the "updated" set and was already ingested (exists in `wiki/sources/` or is referenced in `log.md`), skip it. + +4. **Process updated and new files** — For each file in the updated set plus any files not yet ingested: + - Read and analyze the source + - Create or update `wiki/sources/` pages + - Extract/update concepts and entities + - (skip discussion step in batch mode) + +5. **Run mini-lint** after all sources processed + +6. **Report summary** of what was added/updated/skipped + +7. **Append to `wiki/log.md`** with full timestamp `## [YYYY-MM-DD HH:mm:ss] batch-ingest | {summary}` + +**Page conventions:** +- Every page: YAML frontmatter with `title`, `created_date`, `updated_date` at minimum; `labels` as optional array of tags (e.g. `source`, `concept`, `entity`, `comparison`) +- Source pages include `source_path` linking back to original backlog file +- All cross-references: `[[wikilinks]]` +- Filenames: lowercase-with-hyphens + +### 3. Query + +**Trigger:** User asks a question about wiki content. + +1. Read `wiki/index.md` to locate relevant pages +2. Read those pages (work from compiled wiki, not raw backlog sources) +3. Synthesize answer with `[[wikilink]]` citations +4. Choose output format: + - Simple factual → chat response + - Comparison → table or `wiki/comparisons/` page + - Deep analysis → `wiki_output/reports/{topic}.md` + - Presentation → `wiki_output/slides/{topic}.md` (Marp) + - Visualization → `wiki_output/charts/` (matplotlib) +5. **Flowback prompt** — For any non-trivial output: "This is worth keeping — want me to file it into the wiki?" + +### 4. Lint + +**Trigger:** "lint wiki", "health check", "检查 wiki", or suggest after every ~10 ingests. + +**Scan the entire wiki for:** +- Contradictions between pages +- Stale claims superseded by newer backlog sources +- Orphan pages with no inbound links +- Concepts mentioned frequently but lacking dedicated pages +- Missing cross-references that should exist +- Data gaps fillable via web search +- Potential new connections and questions to investigate + +**Output:** Report in `wiki_output/reports/lint-{date}.md`. Ask which issues to fix, then apply. Append to log. + +--- + +## Conventions + +### Essential Rules +- **`[[Wikilinks]]`** for ALL cross-references within the wiki — including `index.md` tables +- **YAML frontmatter** on every wiki page at minimum: + - `title` — page title + - `created_date` — set on creation (`yyyy-MM-dd HH:mm`) + - `updated_date` — updated on every save (`yyyy-MM-dd HH:mm`) + - `labels` — optional array of tags for categorization (e.g. `source`, `concept`, `entity`, `comparison`) +- **Backlog source folders are immutable** — the LLM never writes to `tasks/`, `docs/`, `decisions/`, etc. +- **Filenames:** lowercase-with-hyphens +- **Exclude `wiki/` and `wiki_output/` from ingestion** — absolute rule to prevent recursion +- **The wiki is part of the git repo** — commit after significant operations + +#### Wikilink Format (CRITICAL) + +**Always** use `[[path/to/file]]` (without `.md` extension) for links between wiki pages. This is the only format that works consistently across Obsidian, GitLab, and other wikilink-aware tools. + +**In `index.md` tables, use wikilinks in the first column:** + +```markdown +| File | Title | Labels | Desc | +|------|-------|--------|------| +| [[sources/task-1-offline-encryption]] | TASK-1: Offline Encryption | source, epic | Offline local encryption mechanism | +| [[concepts/keyvault]] | KeyVault | concept | Core encryption key management | +``` + +**In page bodies (sources, concepts, entities), use wikilinks in Related sections:** + +```markdown +## Related Concepts +- [[concepts/keyvault]] — Core encryption key management +- [[concepts/zero-trust]] — Zero-trust architecture principles + +## Related Sources +- [[sources/task-1-offline-encryption]] — Original implementation task +- [[sources/adr-003-security-model]] — Security ADR +``` + +**❌ NEVER use standard Markdown links for internal wiki pages:** +```markdown +| Source | Labels | Summary | +|--------|------|---------| +| [source-security-module](sources/source-security-module.md) | source | Security module summary | + +## Related Concepts +- [KeyVault](concepts/keyvault.md) +``` + +**✅ ALWAYS use wikilinks:** +```markdown +| Source | Labels | Summary | +|--------|------|---------| +| [[sources/source-security-module]] | source | Security module summary | + +## Related Concepts +- [[concepts/keyvault]] +``` + +--- + +## Wiki Guidelines Content (Inject into Agent File) + +When injecting wiki guidelines into the project's agent instruction file, use the following content wrapped in markers: + +```markdown + + +## Wiki Knowledge Base + +This project maintains an LLM-managed wiki inside the backlog directory for cross-referencing and compounding knowledge from tasks, docs, and decisions. + +### Location +- `backlog/wiki/` — LLM-maintained knowledge base (do not edit manually) +- `backlog/wiki_output/` — Query products and generated artifacts + +### Raw Sources (Human Input Layer) +The LLM reads from the following backlog folders as raw input. These are immutable for wiki purposes: +- `tasks/` — Requirements, acceptance criteria, implementation notes +- `docs/` — Documentation, guides, API references +- `decisions/` — ADRs, design choices, rationale +- `drafts/` — Draft ideas, brainstorming notes +- `milestones/` — Milestone definitions, roadmap items +- `archive/` — Archived tasks and records +- `completed/` — Completed task records with final summaries +- `assets/` — Images, diagrams, attachments +- `src/` (or other project source directories) — Project source code, implementation files (optional, when backlog is inside a project repo) + +### Wiki Structure (LLM-Maintained Layer) +- `wiki/index.md` — Content catalog; read this FIRST on any operation +- `wiki/log.md` — Append-only chronological log (`## [YYYY-MM-DD HH:mm:ss] {op} | {title}`). The detailed timestamp enables git-aware incremental ingestion. +- `wiki/overview.md` — High-level synthesis of the entire knowledge base +- `wiki/sources/` — One summary per backlog source +- `wiki/concepts/` — Extracted concept articles +- `wiki/entities/` — People, tools, projects, organizations +- `wiki/comparisons/` — Cross-cutting analyses +- `wiki/usermanual/` — Optional structured user manual (see UserManual section below) + +### UserManual (`wiki/usermanual/`) + +An optional directory for rendering a structured, book-style user manual. It uses `SUMMARY.md` to define navigation and organizes content into numbered chapter folders. + +**LLM instruction:** When building or maintaining `wiki/usermanual/`, read the full specification from this skill's bundled asset file before proceeding: +- **Read first:** `{skill-dir}/references/usermanual-writing-guide.md` + +That file covers directory layout, naming conventions (`NN-章节名` folders, `NN-标题.md` pages), `SUMMARY.md` syntax rules, content style (de-numbered headings, heading-level usage), asset strategy (global vs chapter-private), extended syntax (Mermaid, Chart/Graph, raw HTML), and a pre-publish checklist. + +**Merging into a single document:** This skill includes a Python tool to merge `README.md` + `SUMMARY.md` and all referenced pages into one auto-numbered markdown file. The tool lives at `{skill-dir}/scripts/merge.py`. + +**LLM execution instruction:** When the user asks to merge or compile the usermanual, run the tool with the project source directory as input: +- **Input:** `backlog/wiki/usermanual/` (or the directory containing `README.md` + `SUMMARY.md`) +- **Output document:** `backlog/wiki_output/用户手册/manual.md` +- **Output assets:** `backlog/wiki_output/用户手册/assets/` (local images are copied here and paths are rewritten) + +Key behaviors: +- `README.md` goes first (headings preserved, not numbered) +- `SUMMARY.md` `##` groups become `#` headings with numbers (`1`, `2`...) +- Page headings are downgraded by their SUMMARY depth: + - SUMMARY level 2 (top link `- [Title]`): downgrade by 1 (`#` → `##`) + - SUMMARY level 3 (nested ` - [Title]`): downgrade by 2 (`#` → `###`, `##` → `####`) + - Deeper nesting follows the same pattern, capped at level 6 +- **Title reconciliation**: If a page lacks a `#` heading, a synthetic one is inserted using the SUMMARY link title. If the page's `#` heading differs from the SUMMARY link title, the SUMMARY title wins. +- All headings are auto-numbered in a tree structure (`1.1`, `1.1.1`, `1.1.1.1`...) +- **Asset collection**: Local image references (`![alt](path)`) are resolved, copied to the output `assets/` folder, and rewritten as `assets/filename` +- Fenced code blocks are protected from mis-parsing; YAML frontmatter is stripped + +### Rules +- **NEVER** write to `tasks/`, `docs/`, `decisions/`, or other backlog source folders during wiki operations +- **NEVER** recursively ingest `wiki/` or `wiki_output/` +- Use `[[wikilinks]]` for all cross-references within the wiki + - **CRITICAL:** In `index.md` tables, use `[[path/to/file]]` (without `.md`) as the cell value, not standard Markdown links like `[text](path.md)` + - Example: `| [[sources/task-1-feature]] | Task | Description |` — NOT `| [task-1](sources/task-1.md) | Task | Description |` + - **CRITICAL:** In page bodies (sources, concepts, entities), Related Concepts / Related Sources / Related Entities sections must also use `[[path/to/file]]`, not `[text](path.md)` + - Example: `- [[concepts/keyvault]]` — NOT `- [KeyVault](concepts/keyvault.md)` +- Append-only for `wiki/log.md` +- YAML frontmatter on every wiki page at minimum: `title`, `created_date`, `updated_date`; `labels` as optional array of tags +- Filenames: lowercase-with-hyphens + +### Operations +- **Ingest** — Read backlog sources, extract concepts/entities, create source summaries, update index/overview/log + - **Git-aware incremental ingestion**: If the project is a git repo, use `git status --porcelain` and `git log --since="{last_ingest}"` to detect changed files since the last ingestion. Skip files that were already ingested and have not changed. Fall back to full scan if git is unavailable. +- **Query** — Read index, synthesize from compiled wiki, produce chat responses / reports / slides / charts +- **Lint** — Scan for contradictions, orphans, stale claims, missing cross-references +- **Flowback** — Save valuable query results back into the wiki for compounding + + +``` + +--- + +## Scale Guidance + +| Scale | Navigation | Tooling | +|---|---|---| +| Small (<50 sources) | `index.md` alone | None needed | +| Medium (50–200) | `index.md` + search | qmd: local BM25+vector search | +| Large (200+) | Chunked index + search | Full search infra | + +--- + +## Key Tips + +- **Backlog folders are your raw/** — Don't duplicate content. Use existing `tasks/`, `docs/`, `decisions/` as sources. +- **Flowback is the magic** — Every query result filed back makes future queries richer. +- **Ask analytical questions** — Not "summarize this task" but "compare approaches across these tasks, citing all sources and noting contradictions." +- **Co-evolve conventions** — Update the wiki section directly in the project's agent instruction file (`CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`) as conventions emerge. The agent file is the single source of truth for both backlog workflow and wiki rules. +- **Let the LLM suggest questions** — After lint or ingest, the LLM often surfaces connections and gaps. diff --git a/.codex/skills/llm-wiki-for-backlog/references/usermanual-writing-guide.md b/.codex/skills/llm-wiki-for-backlog/references/usermanual-writing-guide.md new file mode 100644 index 000000000..65a30ffc3 --- /dev/null +++ b/.codex/skills/llm-wiki-for-backlog/references/usermanual-writing-guide.md @@ -0,0 +1,303 @@ +# UserManual 编写指引 + +本指引规范 `backlog/wiki/usermanual` 目录的文档组织与编写方式。该目录通过 `SUMMARY.md` 定义导航结构,以 Markdown 文件承载内容,最终可渲染为在线用户手册。 + +--- + +## 1. 目录结构规范 + +``` +usermanual/ +├── README.md # 封面/简介页(必需) +├── SUMMARY.md # 目录导航定义(必需) +├── assets/ # 全局公共资源(图片、Logo 等) +│ +├── 00-开始使用/ # 章节文件夹:数字前缀 + 章节名 +│ ├── 00-产品概述.md +│ ├── 01-隐私政策.md +│ └── ... +│ +├── 10-管理后台/ # 数字前缀决定左侧导航排序 +│ ├── assets/ # 章节私有资源(可选) +│ ├── 00-用户登录.md +│ ├── 01-看板.md +│ └── ... +│ +├── 11-勘察APP/ +│ ├── assets/ +│ ├── 00-安装.md +│ └── ... +│ +└── ... +``` + +### 1.1 文件夹命名规则 + +| 规则 | 说明 | 示例 | +|------|------|------| +| `数字前缀-章节名` | 两位或以上数字,用于控制导航顺序;后跟中文章节名 | `00-开始使用`、`10-管理后台` | +| 数字间隔 | 建议按 **10 为步长** 预留,方便后续插入新章节 | `10-`、`20-`、`30-` | +| 纯英文与数字 | 仅当需要国际化或技术章节时使用英文 | `20-API文档` | + +### 1.2 文件命名规则 + +| 规则 | 说明 | 示例 | +|------|------|------| +| `数字前缀-标题.md` | 固定宽度、左侧补零的连续序号,确保字典序即阅读序 | `00-产品概述.md`、`01-隐私政策.md` | +| 宽度选择 | 文件较少的章节用两位(`00`~`99`);超过 100 篇可用三位(`000`~`999`) | `00-安装.md`、`015-高级配置.md` | +| 空格与连字符 | 数字前缀与标题之间**必须有空格或连字符**;标题内用空格或连字符均可 | `01-隐私政策.md`、`02-项目地图.md` | + +--- + +## 2. SUMMARY.md 编写规范 + +`SUMMARY.md` 是 **核心导航文件**,直接决定左侧目录树的渲染结果。 + +### 2.1 基本格式 + +```markdown +## 开始使用 + +- [产品概述](00-开始使用/00-产品概述.md) +- [隐私政策](00-开始使用/01-隐私政策.md) + +## 管理后台 + +- [用户登录](10-管理后台/00-用户登录.md) +- [看板](10-管理后台/01-看板.md) + +## 任务计划 + +- [岩土信息化总结](70-任务计划/00-岩土信息化总结.md) + - [任务记录](70-任务计划/01-任务记录.md) +``` + +### 2.2 语法规则 + +| 元素 | 语法 | 说明 | +|------|------|------| +| 分组标题 | `## 分组名` | 对应左侧导航的一个**可折叠分组** | +| 页面链接 | `- [显示标题](相对路径)` | 相对路径从 `SUMMARY.md` 所在目录开始 | +| 多级列表(嵌套) | 子项使用 **4 个空格** 缩进 | 支持多级嵌套导航,但建议不超过 **2 级** | + +### 2.3 注意事项 + +1. **路径必须相对**:使用 `10-管理后台/00-用户登录.md`,而非绝对路径。 +2. **标题与文件名可不同**:中括号 `[显示标题]` 是导航树中展示的名称,可与文件名不一致。 +3. **顺序即导航顺序**:`SUMMARY.md` 中的书写顺序 = 左侧导航的显示顺序。 +4. **README.md 自动为首页**:无需在 `SUMMARY.md` 中显式引用 `README.md` 会自动将其作为书籍首页。 +5. **多级列表缩进**:子项必须使用 **4 个空格** 缩进(Tab 或 2 个空格可能无法正确渲染)。示例: + ```markdown + - [岩土信息化总结](70-任务计划/00-岩土信息化总结.md) + - [任务记录](70-任务计划/01-任务记录.md) + ``` + +--- + +## 3. 页面内容(Markdown)编写规范 + +### 3.1 标题层级 + +| 层级 | 用途 | 示例 | +|------|------|------| +| `#` 一级标题 | **页面主标题**,每页**有且仅有 1 个** | `# 用户登录` | +| `##` 二级标题 | 页面内大模块划分 | `## 安装` | +| `###` 三级标题 | 功能点或子模块 | `### 工作任务` | +| `####` 四级标题 | 具体操作步骤 | `#### 项目详情` | +| `#####` 五级标题 | 更细粒度的步骤或说明 | `##### 勘探孔表` | + +> **去序号原则**:所有 Markdown 标题中均**不得出现章节序号前缀**(如 `1.1`、`2.4.1`、`A7`、`B1` 等)。序号由文件名的数字前缀统一控制,标题本身保持纯文本。 | | | + +> **重要**:一级标题 `#` 必须放在页面最顶部,且只出现一次,会将其作为该页面的默认标题。 + +### 3.2 正文风格 + +- **段落间空一行**:Markdown 段落之间保留一个空行,提高可读性。 +- **步骤说明**:操作类文档使用“点击… → 进入… → 输入…”的叙事方式。 +- **截图标注**:每张截图下方单独一行用 `截图说明` 标注,便于理解上下文。 + +```markdown +打开浏览器,在地址栏输入 ,将进入后台管理系统。 + +![后台管理系统登录页](../assets/ccabc5310c7b49d1b5bb3c0a6239a3f4.png) + +>后台管理系统登录页的截图说明 +``` + +--- + +## 4. 图片与资源引用规范 + +### 4.1 资源存放策略 + +采用 **"就近原则 + 全局兜底"**: + +| 资源类型 | 存放位置 | 引用路径 | 适用场景 | +|----------|----------|----------|----------| +| 全局通用 | `usermanual/assets/` | `../assets/xxx.png` | Logo、首页大图、跨章节复用图 | +| 章节私有 | `章节文件夹/assets/` | `assets/xxx.png` | 仅该章节使用的截图 | +| 章节私有(媒体) | `章节文件夹/media/` | `media/xxx.png` | 视频、PPT 转换图、大批量 SVG | + +### 4.2 引用语法 + +```markdown + +![](../assets/logo.png) + + +![](assets/2021-06-21-11-32-52.png) + + +![](assets/图1.png)![](assets/图2.png) + + +> 【校正前】 【校正后】 +``` + +### 4.3 命名建议 + +- **时间戳命名**:截图可使用 `YYYY-MM-DD-HH-mm-ss.png` 或哈希命名,避免中文文件名导致的编码问题。 +- **语义化命名**:若图片有明确含义,可用英文或拼音,如 `login-page.png`、`tilt-correction-before.png`。 +- **避免空格**:文件名中尽量不要出现空格,使用 `-` 或 `_` 代替。 + +--- + +## 5. 扩展语法 + +### 5.1 Mermaid 图表 + +支持流程图、时序图、甘特图、ER 图等: + +````markdown +```mermaid +graph TD + A[开始] --> B{判断} + B -->|条件1| C[处理1] + B -->|条件2| D[处理2] +``` +```` + +### 5.2 Chart / Graph 插件 + +用于渲染数据图表或函数图像: + +```markdown +{% chart %} +{ + "data": { + "type": "bar", + "columns": [ + ["data1", 30, 200, 100], + ["data2", 50, 20, 10] + ] + } +} +{% endchart %} + +{% graph %} +{ + "title": "1/x * cos(1/x)", + "grid": true, + "data": [{"fn": "1/x * cos(1/x)"}] +} +{% endgraph %} +``` + +### 5.3 原始 HTML(视频等) + +如需嵌入原生 HTML(如 `