@biaoo/tiangong-wiki 0.2.0 → 0.2.2

package/references/vault-to-wiki-instruction.md

@@ -1,6 +1,6 @@
-# Vault To Wiki Instruction
+# Vault-to-Wiki Instruction
 
-Use this instruction when a vault queue item must be processed into durable wiki knowledge.
+Use this instruction when vault files need to be processed into durable wiki knowledge.
 
 ## Goal
 
@@ -14,86 +14,144 @@ The output may be:
 
 Do not assume any page type is the default destination.
 
-## Core Rules
+---
+
+## Phase 1: Read the File
+
+### Skill Discovery
+
+Parser skills are installed under `<workspace-root>/.agents/skills/`. Do not assume any parser skill is present — check what is actually available.
+
+| Skill | Purpose |
+|---|---|
+| `pdf` | Extract text and structure from PDF files |
+| `docx` | Extract text and structure from DOCX files |
+| `pptx` | Extract text, slide structure, and speaker notes from PPTX files |
+| `xlsx` | Extract tables and data from XLSX/CSV files |
+
+When a parser skill is available and the vault file matches its type, use the skill. Read the skill's SKILL.md for interface details before invoking.
+
+If a parser skill fails due to missing runtime dependencies, attempt to install (e.g., `pip install`, `npm install`) and retry. If resolution fails, fall back to direct reading and note the failure in the result manifest.
+
+### File Type Strategies
+
+**Markdown / Plain Text (md, txt)**
+Read directly. For large files (>5000 lines), read in sections. Parse YAML frontmatter separately if present.
+
+**PDF**
+Prefer the `pdf` parser skill. Without it: attempt direct read; if unreadable, skip. Use PDF metadata (title, author, date, subject) to inform decisions.
+
+**Word Documents (docx)**
+Prefer the `docx` parser skill. Without it: skip (DOCX is a ZIP/XML archive, unreliable to read directly). Use document properties when available.
+
+**Presentations (pptx)**
+Prefer the `pptx` parser skill. Speaker notes are often more valuable than slide text. Without the skill: skip.
+
+**Spreadsheets (xlsx, csv)**
+Prefer the `xlsx` skill for xlsx. CSV can be read directly (check encoding — Chinese content may use GBK/GB2312). Not all tabular data is knowledge — look for definitions, rules, or structured descriptions rather than raw dumps.
+
+**Structured Data (json, yaml, yml)**
+Read and parse directly. Evaluate whether the structure itself is the knowledge (e.g., a schema) or merely a container.
+
+**Image Files (png, jpg, jpeg, webp)**
+Use vision to read and evaluate. If the image has extractable value (diagrams, flowcharts, visualizations), save with `tiangong-wiki asset save` and reference with `tiangong-wiki asset ref`. Every image in a wiki page MUST have a textual description — images cannot be indexed.
+
+**Images Embedded in Documents**
+Use vision to understand each image in context. Extract only high-value images via the relevant parser skill. Use `tiangong-wiki asset save/ref` to manage extracted files.
+
+### Large and Complex Files
+
+- Read incrementally — do not load the entire file at once.
+- Summarize structure first (TOC, slide titles, sheet names) to identify high-value sections.
+- Not every section is worth extracting.
+
+### Encoding and Edge Cases
+
+- Chinese content may use GBK, GB2312, or Big5. Try alternative encodings if garbled.
+- Corrupted files: skip with a clear reason.
+- Password-protected or empty files: skip immediately.
+
+---
+
+## Phase 2: Decide
+
+### Core Rules
 
 1. Discover the current ontology through the wiki CLI before deciding what to write.
 2. Search for relevant existing pages before creating new ones.
-3. Treat all page types equally. Choose the best fit from the current wiki, not a hardcoded fallback.
+3. Treat all page types equally. Choose the best fit, not a hardcoded fallback.
 4. Skip transient, duplicate, or low-value files.
-5. Preserve provenance with `sourceRefs` and any type-specific source fields already defined by the chosen template.
-6. `sourceRefs` may only contain existing wiki page ids. Do not put raw vault file paths there; keep raw file provenance in the page body or a dedicated source field such as `vaultPath` when the chosen type supports it.
-7. If the existing type system cannot represent the knowledge cleanly, prefer `propose_only` unless template evolution is explicitly allowed.
-
-## Runtime Discovery
+5. Preserve provenance with `sourceRefs` and type-specific source fields defined by the chosen template.
+6. `sourceRefs` may only contain existing wiki page ids. Raw file provenance belongs in the page body or a field like `vaultPath`.
+7. Only write frontmatter fields declared by the chosen type (`tiangong-wiki type show <type>`). Do not invent ad-hoc fields.
+8. If the type system cannot represent the knowledge cleanly, prefer `propose_only` unless template evolution is explicitly allowed.
 
-Use the CLI as the source of truth for the current ontology and page set.
+### Runtime Discovery
 
-Prefer:
+Use the CLI as source of truth:
 
 - `tiangong-wiki type list --format json`
 - `tiangong-wiki type show <type> --format json`
 - `tiangong-wiki type recommend --text "<summary>" --keywords "a,b,c" --limit 5 --format json`
-- `tiangong-wiki find`
-- `tiangong-wiki fts`
-- `tiangong-wiki page-info`
+- `tiangong-wiki find` / `tiangong-wiki fts` / `tiangong-wiki page-info`
 
 Notes:
-
 - Do not use guessed subcommands such as `tiangong-wiki page find`.
-- `tiangong-wiki find` and `tiangong-wiki list` already emit JSON; do not append `--format json`.
-
-Do not rely on static prompt snapshots of types, templates, or pages.
+- `find` and `list` already emit JSON; do not append `--format json`.
 
-## Decision Model
+### Decision Model
 
-Choose exactly one decision:
+Choose exactly one:
 
-- `skip`
-  The file is noise, duplicate, transient, unreadable, or already fully represented.
+- **`skip`** — the file is noise, duplicate, transient, unreadable, or already fully represented.
+- **`apply`** — the file adds durable knowledge expressible with existing page types.
+- **`propose_only`** — the file has durable value but the current type system is not a clean fit.
 
-- `apply`
-  The file adds durable knowledge and you can express it with existing page types.
-
-- `propose_only`
-  The file has durable value, but the current type system is not a clean fit and automatic template evolution is not allowed.
-
-## Value Heuristics
+### Value Heuristics
 
 Favors `apply`:
-
-- durable documents with reusable knowledge
-- files that materially strengthen or revise an existing page
-- sources that introduce a clearly distinct knowledge object worth revisiting
+- Durable documents with reusable knowledge
+- Files that materially strengthen or revise an existing page
+- Sources that introduce a clearly distinct knowledge object
 
 Favors `skip`:
-
-- temporary exports, dumps, or duplicates
-- opaque binaries with no useful extractable content
-- screenshots or images with no standalone evidence value
-- files whose substance is already covered by current pages
+- Temporary exports, dumps, or duplicates
+- Opaque binaries with no extractable content
+- Screenshots with no standalone evidence value
+- Files whose substance is already covered
 
 Favors `propose_only`:
+- The file is valuable but existing types are clearly awkward or lossy
+- A new type would materially improve ontology quality
 
-- the file is valuable
-- existing types are clearly awkward or lossy
-- creating a new type would materially improve ontology quality
+### Metadata Utilization
 
-## Page Update Rules
+| Metadata | Where Found | How to Use |
+|---|---|---|
+| Title | PDF, DOCX, PPTX properties | Inform page title and nodeId |
+| Author | PDF, DOCX, PPTX properties | May indicate relevant `person` pages, inform provenance |
+| Creation / modification date | Most formats | Inform `createdAt`, assess recency |
+| Subject / keywords | PDF, DOCX properties | Inform tags and search during discovery |
+| Slide / page count | PDF, PPTX | Gauge complexity, anticipate splitting needs |
 
-When applying changes:
+Do not blindly copy metadata into wiki fields — use it as input alongside actual content.
 
-1. Prefer updating an existing page if the source is a revision, appendix, or direct reinforcement of that page.
+---
+
+## Phase 3: Execute
+
+### Page Update Rules
+
+1. Prefer updating an existing page if the source is a revision, appendix, or reinforcement.
 2. Create a new page only when the knowledge object is distinct and deserves its own identity.
 3. Keep edits minimal, specific, and provenance-preserving.
-4. For every changed page, run:
-   - `tiangong-wiki sync --path <page>`
-   - `tiangong-wiki lint --path <page> --format json`
-
-## Manifest Contract
+4. After every change:
+   - `tiangong-wiki sync --path <page-id>`
+   - `tiangong-wiki lint --path <page-id> --format json`
 
-The workflow must write a valid `result.json` manifest.
+### Manifest Contract
 
-Minimum expectations:
+The workflow must write a valid `result.json` manifest with these fields:
 
 - `status`
 - `decision`

package/references/wiki-maintenance-instruction.md

@@ -22,20 +22,17 @@ The judgment layer is the agent: deciding whether knowledge is durable, which pa
 8. Run `tiangong-wiki sync --path <page-id>`.
 9. Re-run `tiangong-wiki lint --path <page-id>` when the change is localized.
 
-## PageType Selection Table
-| pageType | Use When | Typical Trigger | Notes |
-| --- | --- | --- | --- |
-| `concept` | A stable concept, model, or principle should be reusable later | New synthesis from multiple sources | Best for durable understanding |
-| `misconception` | A wrong mental model was corrected | User or agent had a clear before/after correction | Record the failure mode and prevention cues |
-| `bridge` | Knowledge transfers from one domain to another | Cross-project or cross-discipline analogy | Use when the value is the transfer itself |
-| `source-summary` | The source itself deserves a reusable digest page | A source document should remain a first-class knowledge object | Preserve `vaultPath` and `sourceType`; this is not the default destination for every vault file |
-| `lesson` | A specific incident produced a durable lesson | Failure, success, or surprise with actionable aftermath | Keep the event and future action linked |
-| `method` | A repeatable process or recipe proved useful | Same process worked more than once | Capture applicability and evidence |
-| `person` | Someone's role, preferences, or influence matters again later | Recurring collaborator or decision-maker | Keep factual and context-specific |
-| `achievement` | A milestone, credential, or verifiable result matters | Award, publication, certification, milestone | Useful for profile and reporting reuse |
-| `resume` | A reusable positioning page is needed for different audiences | Tailored summary for applications or intros | Keep it current and audience-aware |
-| `research-note` | Investigation is ongoing and incomplete | Exploratory work with open questions | Prefer this over `concept` when not settled yet |
-| `faq` | The same question recurs often | Third repeat or clear repeating pattern | Optimize for rapid reuse |
+## PageType Selection
+
+Do not assume a fixed set of page types. Always discover the current ontology at runtime:
+
+```bash
+tiangong-wiki type list --format json
+tiangong-wiki type show <type> --format json
+tiangong-wiki type recommend --text "<summary>" --keywords "a,b,c" --limit 5 --format json
+```
+
+Use `type recommend` to find the best fit for new knowledge. If no existing type fits cleanly, see `references/template-design-guide.md` for when and how to create a new type.
 
 ## Update Vs Create Decision Flow
 1. Start with a retrieval pass.
@@ -55,7 +52,7 @@ The judgment layer is the agent: deciding whether knowledge is durable, which pa
 
 ## Create Workflow
 1. Confirm no suitable active page exists.
-2. Choose the page type from the table above.
+2. Choose the page type using `tiangong-wiki type recommend` or `tiangong-wiki type list`.
 3. Run `tiangong-wiki create --type <pageType> --title "<title>" [--node-id <nodeId>]`.
 4. Open the created Markdown file and fill the frontmatter-specific fields.
 5. Fill every body section in the template with concrete content, not placeholders.
@@ -113,6 +110,9 @@ Example flow:
 ```
 
 ## Page-Type Specific Guidance
+
+> The canonical type list comes from `tiangong-wiki type list`. The tips below apply to commonly used types but may not cover all registered types.
+
 ### concept
 - Use for durable understanding, definitions, formulas, and reusable intuition.
 - Fill prerequisites, examples, confusions, and open questions.