@biaoo/tiangong-wiki 0.2.0 → 0.2.2

package/dist/core/workflow-context.js

@@ -51,6 +51,10 @@ export function buildVaultWorkflowPrompt(input) {
         `RESULT_JSON_PATH=${input.resultJsonPath}`,
         `ALLOW_TEMPLATE_EVOLUTION=${input.allowTemplateEvolution ? "true" : "false"}`,
         "",
+        "## Goal",
+        "",
+        "Extract reusable, high-value information units from a vault file and express them as wiki pages. The wiki is a knowledge base, not a notebook. Every page must earn its place by being independently useful for retrieval, graph traversal, or downstream reuse. If a source contains nothing worth extracting, skip it.",
+        "",
         "## Environment",
         "",
         "Workspace-local skills are available from WORKSPACE_ROOT through normal Codex skill discovery.",
@@ -66,18 +70,20 @@ export function buildVaultWorkflowPrompt(input) {
         "- `tiangong-wiki page-info <pageId>` — show full metadata and edges for one page",
         "- `tiangong-wiki graph <root>` — traverse the wiki knowledge graph",
         "- `tiangong-wiki stat` — show aggregate wiki index statistics",
+        "- `tiangong-wiki asset save <source-file> [--name <slug>]` — save an image to wiki assets, returns the asset path",
+        "- `tiangong-wiki asset ref <name-or-path> --page <page-id>` — compute the relative path from a page to an asset for markdown references",
         "",
         "Use whichever combination you judge necessary. These are tools at your disposal, not a mandatory checklist.",
         "",
         "## Step 1 — Read and Discover",
         "",
         "1. Read queue-item.json next to RESULT_JSON_PATH.",
-        "2. Read the target vault file at VAULT_FILE_PATH.",
-        "3. Discover the current page type ontology through the tiangong-wiki CLI. Do not assume any type, template, or default target type.",
-        "4. Understand the existing wiki knowledge landscape before deciding what to create or update:",
-        "   - What pages already exist? Are any of them covering the same or overlapping topics?",
-        "   - What is the current knowledge graph structure? Are there clusters of related pages that this new source naturally connects to?",
-        "   - Does this source introduce genuinely new knowledge, or does it reinforce, extend, or contradict something already captured?",
+        "2. Read the target vault file at VAULT_FILE_PATH. Refer to `references/vault-to-wiki-instruction.md` (Phase 1) in the wiki package for file-type-specific reading strategies, parser skill discovery, image handling, and metadata utilization.",
+        "3. Discover the current page type ontology via `tiangong-wiki type list` and `tiangong-wiki type show <type>`. Do not assume any type, template, or default target type.",
+        "4. Search the existing wiki for overlapping or related content:",
+        "   - Use `tiangong-wiki fts` and `tiangong-wiki search` with key terms from the source.",
+        "   - For each candidate hit, use `tiangong-wiki page-info` to understand its scope, type, and current edges.",
+        "   - Determine: does this source reinforce, extend, contradict, or have no overlap with existing pages?",
         "",
         "These questions must be answered before proceeding to Step 2.",
         "",
@@ -87,33 +93,64 @@ export function buildVaultWorkflowPrompt(input) {
         "",
         "## Step 2 — Decide",
         "",
-        "### Type Selection",
+        "### 2a. Identify Information Units",
+        "",
+        "Before choosing any type, decompose the source into independently reusable information units. An information unit is a concept, method, lesson, pattern, insight, person profile, achievement, or any other piece of information that has standalone value.",
+        "",
+        "Ask for each candidate unit:",
+        "- Can it be understood and reused without reading the original source?",
+        "- Would someone searching the wiki benefit from finding this as a standalone page?",
+        "- Is it specific enough to have a single clear topic?",
+        "",
+        "If the answer to any of these is no, the unit is not worth extracting. If the entire source yields zero extractable units, set decision=skip.",
+        "",
+        "### 2b. Type Selection",
+        "",
+        "For each information unit, select the page type that best captures its nature:",
+        "1. Run `tiangong-wiki type list` and understand the purpose of each registered type.",
+        "2. Match the unit to the type whose semantic intent fits best. Consult `tiangong-wiki template show <type>` to verify the template structure supports the content you want to express.",
+        "3. You must be able to articulate why this type fits. If you find yourself choosing a type simply because it is the easiest to fill, reconsider.",
+        "",
+        "### 2c. Update vs Create vs Skip",
+        "",
+        "For each information unit, search the wiki (Step 1 results) and decide:",
+        "- **Update**: An existing page already covers this topic. Add new information, correct outdated content, or enrich it. Preserve existing valid content.",
+        "- **Create**: No existing page covers this topic. Create a new page.",
+        "- **Skip**: An existing page already fully covers this content with equal or better quality. Do not duplicate.",
         "",
-        "Choose the page type that best matches the nature of the knowledge in the source. Query the registered types and understand their intended use before deciding. Do not default to any single type.",
+        "### 2d. Page Granularity and Splitting",
         "",
-        "### Update vs Create",
+        "Each page should have a single, clear core topic and express it completely.",
+        "- Aim for roughly 1000 words or fewer per page body. This is a guideline, not a hard limit, but if a page grows significantly beyond this, it likely covers more than one topic and should be split.",
+        "- A single vault source may produce multiple pages when it contains multiple independent information units. At most 5 pages per vault source.",
+        "- When splitting, each resulting page must independently satisfy the information unit criteria above.",
+        "- If a new vault source is complex, split it into multiple pages. Each split page still goes through the update-vs-create check above.",
         "",
-        "If an existing page already covers the same topic, prefer updating it over creating a duplicate. Only create a new page when the source introduces a genuinely new topic not yet represented in the wiki.",
+        "### 2e. Building Relations",
         "",
-        "### Splitting",
+        "Relations are how the knowledge graph gains structure and navigability.",
         "",
-        "A single vault source MAY produce multiple pages of different types when the source contains independently reusable knowledge points.",
-        "- At most 5 pages per vault source to avoid over-fragmentation.",
-        "- Link all pages created from the same source via relatedPages.",
+        "Priority order for choosing relation types:",
+        "1. **Type-specific edges** (e.g., prerequisites, correctedConcepts, fromConcepts/toConcepts, bridges_from/bridges_to): Use these whenever the relationship matches the semantic intent defined by the type schema. Discover available edges via `tiangong-wiki template show <type>`.",
+        "2. **sourceRefs** (edgeType: sourced_from): Records wiki-internal knowledge dependency. Use when the new page's content builds upon, extends, synthesizes, or is derived from existing wiki pages. This is the primary mechanism for knowledge lineage within the wiki. Do not put vault paths into sourceRefs — that is what vaultPath is for.",
+        "3. **relatedPages** (edgeType: related): Use only for genuine thematic relationships that do not fit any type-specific edge or sourceRefs. This is a last resort, not a default.",
         "",
-        "### Building Relations",
+        "If during discovery you find that the new source, combined with existing wiki pages, enables a higher-level synthesis (e.g., two existing concepts can now be bridged, or a pattern emerges across multiple existing pages), you may create that synthesis page and use sourceRefs to link back to its constituent pages.",
         "",
-        "Every page you create or update should be connected to the existing knowledge graph where meaningful relations exist. Orphan pages with no relations are acceptable only when the source introduces a topic with no overlap to existing wiki content.",
+        "Orphan pages with no relations are acceptable when the source introduces a topic with genuinely no overlap to existing wiki content.",
         "",
         "## Step 3 — Create or Update Pages",
         "",
         "### Field Conventions",
         "",
-        "- **vaultPath**: MUST be relative to the vault root. Never use absolute paths. Derive it by stripping the vault root prefix from VAULT_FILE_PATH.",
-        "- **sourceRefs**: Prefer existing wiki page IDs when the new page directly builds on already-indexed wiki pages. Do not put absolute vault paths into sourceRefs. If no existing wiki page is directly referenced, it is acceptable to leave sourceRefs empty.",
-        "- **relatedPages**: Populate with page IDs of related pages discovered in Step 1. Every page should have relations when related content exists in the wiki.",
+        "- **vaultPath**: MUST be relative to the vault root. Never use absolute paths. Derive it by stripping the vault root prefix from VAULT_FILE_PATH. This field tracks which original source file produced this page.",
+        "- **sourceRefs**: Wiki-internal knowledge dependency. Points to existing wiki page paths that this page's content builds upon. Do not use for vault file references. Leave empty only when this page genuinely has no dependency on existing wiki knowledge.",
+        "- **relatedPages**: Thematic relations only. Do not use as a substitute for sourceRefs or type-specific edges.",
         "- **createdAt / updatedAt**: Leave placeholders unchanged or omit them. The system will normalize them to YYYY-MM-DD during indexing and refresh updatedAt on modified pages.",
-        "- **nodeId**: Use a lowercase kebab-case slug derived from the title.",
+        "- **nodeId**: Lowercase kebab-case slug derived from the topic (not the source document name).",
+        "  - For English titles: use key words directly (e.g., \"API Rate Limiting\" → `api-rate-limiting`).",
+        "  - For Chinese titles: use a short English translation of the core topic, NOT pinyin (e.g., \"平台产品需求文档\" → `platform-product-requirements`, NOT `ping-tai-chan-pin-xu-qiu-wen-dang`).",
+        "  - Keep under 50 characters. Drop filler words.",
         "",
         "Consult the template for your chosen type before writing a page.",
         "If ALLOW_TEMPLATE_EVOLUTION=false, do not create templates or new page types.",
@@ -124,7 +161,7 @@ export function buildVaultWorkflowPrompt(input) {
         "1. `tiangong-wiki sync --path <page>`",
         "2. `tiangong-wiki lint --path <page> --format json`",
         "",
-        "Fix any errors before proceeding. Warnings are acceptable.",
+        "Fix all errors before proceeding. Also review warnings: if a warning indicates a field mismatch between your page and the type schema (e.g., unregistered fields, empty required references), fix it. Only ignore warnings that are clearly cosmetic or irrelevant to schema correctness.",
         "",
         "## Step 4 — Write Result Manifest",
         "",