@biaoo/tiangong-wiki 0.2.0

package/references/template-design-guide.md

@@ -0,0 +1,271 @@
+# Template 设计指南
+
+本文档定义如何为 wiki 设计新的 page type 和对应 template。适用于手动创建和 AI 自动演化（`ALLOW_TEMPLATE_EVOLUTION=true`）两种场景。
+
+---
+
+## 1. Template 是什么
+
+一个 template 由两部分组成：
+
+### 模板文件（`templates/<type>.md`）
+
+定义页面的 frontmatter 字段和 body section 骨架：
+
+```yaml
+---
+pageType: <type>
+title: <Type Title>
+nodeId: <type-slug>
+status: draft
+visibility: private
+sourceRefs: []
+relatedPages: []
+tags: []
+createdAt: 2026-04-06
+updatedAt: 2026-04-06
+# ... type-specific fields
+---
+
+## Section 1
+
+引导性提示文本，告诉作者这一节该写什么。
+
+## Section 2
+
+...
+```
+
+### 配置注册（`wiki.config.json` 的 `templates.<type>`）
+
+定义该类型的索引行为：
+
+```json
+{
+  "file": "templates/<type>.md",
+  "columns": { },
+  "edges": { },
+  "summaryFields": [ ]
+}
+```
+
+两者缺一不可。模板文件定义"写什么"，配置注册定义"怎么索引"。
+
+---
+
+## 2. 何时需要新 Type
+
+创建新 type 之前，先确认现有类型是否能覆盖：
+
+- 这类知识的**结构**是否与现有类型有本质差异？（字段不同、section 不同）
+- 还是仅仅是**主题**不同？（同样的结构，只是内容领域不同）
+
+**主题差异用 tags 区分，结构差异才建新 type。**
+
+示例判断：
+- "环境领域的研究笔记" vs "教育领域的研究笔记" → 用 `research-note` + 不同 tags
+- "会议纪要" vs "研究笔记" → 结构不同（参会人、决议、待办 vs 研究问题、文献、发现），需要新 type
+
+---
+
+## 3. Frontmatter 字段设计
+
+### 通用字段（不需要设计，自动继承）
+
+所有 type 共享以下字段，模板中必须包含：
+
+```yaml
+pageType, title, nodeId, status, visibility,
+sourceRefs, relatedPages, tags, createdAt, updatedAt
+```
+
+### Type-specific 字段设计原则
+
+1. **只加对查询或分类有意义的字段**。如果一个字段只在 body 中出现，不需要放进 frontmatter
+2. **字段值应该是短文本或枚举**，不是长段落。长内容放 body section
+3. **字段命名使用 camelCase**，系统会自动映射为 snake_case 列名
+4. **不要重复通用字段的语义**。比如不要加 `category` 字段，用 `tags` 代替
+
+### 字段放哪一层
+
+| 问题 | 放在 | 原因 |
+| --- | --- | --- |
+| 需要 `tiangong-wiki find --<field>` 过滤？ | `columns` | 建 SQLite 索引列，支持结构化查询 |
+| 需要出现在 `tiangong-wiki search` / `tiangong-wiki fts` 的摘要中？ | `summaryFields` | 纳入 summary_text 用于检索 |
+| 需要生成 edge（关联到其他页面/节点）？ | `edges` | 写入 edges 表，支持 graph 遍历 |
+| 只是页面内的补充信息？ | 仅写在 frontmatter | 存入 `pages.extra` JSON，不建列 |
+
+---
+
+## 4. Columns 设计
+
+`columns` 中的字段会在 `pages` 表上建列和索引，支持 `tiangong-wiki find` 的结构化过滤。
+
+```json
+"columns": {
+  "severity": "text",
+  "resolvedAt": "text"
+}
+```
+
+**设计要点**：
+
+- 类型目前只支持 `"text"`
+- 只有需要频繁按值过滤的字段才值得建列
+- 不同 type 的 columns 共存于同一张 `pages` 表，非该类型的页面该列值为 NULL
+- 列名全局唯一 — 如果两个 type 都有 `severity` 字段，它们共享同一个列
+
+---
+
+## 5. Edges 设计
+
+`edges` 定义 frontmatter 中的数组字段如何生成 graph 边。
+
+```json
+"edges": {
+  "prerequisites": {
+    "edgeType": "prerequisite",
+    "resolve": "nodeId"
+  }
+}
+```
+
+**三个字段**：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `edgeType` | 是 | edge 类型标识，写入 `edges.edge_type` |
+| `resolve` | 是 | 目标匹配方式：`"nodeId"` 匹配 `pages.node_id`；`"path"` 匹配 `pages.id` |
+| `match` | 否 | 正则前置过滤，仅匹配的值参与 resolve |
+
+**设计要点**：
+
+- 只有**指向其他页面或节点**的数组字段才需要定义 edge
+- `edgeType` 应该表达语义关系（`prerequisite`, `corrects`, `bridges_from`），不是字段名
+- `resolve: "nodeId"` 适用于引用知识图谱中的概念节点
+- `resolve: "path"` 适用于引用具体的页面文件路径
+- `commonEdges`（`relatedPages`, `sourceRefs`）已全局生效，template 中不需要重复定义
+
+---
+
+## 6. SummaryFields 设计
+
+`summaryFields` 中的字段值会拼接进 `pages.summary_text`，用于语义搜索和全文检索。
+
+```json
+"summaryFields": ["confidence", "masteryLevel", "prerequisites"]
+```
+
+**设计要点**：
+
+- 选择能帮助检索的字段 — 如果知道 `domain: "环境工程"` 能帮搜索找到这个页面，就加进去
+- 不要放长文本字段，summary_text 应保持简洁
+- `defaultSummaryFields`（`title`, `tags`）自动包含，不需要重复
+
+---
+
+## 7. Body Section 设计
+
+Body section 是模板文件中 frontmatter 之后的 Markdown 骨架，引导作者（人或 AI）写出结构化内容。
+
+**设计原则**：
+
+1. **每个 section 用 `##` 标题** 开头
+2. **写一句引导性提示**，告诉作者这一节的目的和期望内容，不是模板占位符
+3. **提示语应该是具体的引导**，不是"在此处填写内容"这样的泛泛之词
+4. **Section 数量控制在 3-6 个** — 太少缺乏结构，太多增加写作负担
+5. **Section 之间应该有逻辑递进** — 比如从"是什么"到"为什么重要"到"如何使用"
+
+**好的提示语示例**：
+
+```markdown
+## 核心理解
+
+用两到四句话说明这个概念到底是什么，以及它为什么值得记住。
+```
+
+**差的提示语示例**：
+
+```markdown
+## 内容
+
+<!-- 在此处填写内容 -->
+```
+
+---
+
+## 8. 完整示例
+
+假设需要设计一个 `meeting-note` 类型：
+
+### 模板文件 `templates/meeting-note.md`
+
+```yaml
+---
+pageType: meeting-note
+title: Meeting Note Title
+nodeId: meeting-note-slug
+status: draft
+visibility: private
+sourceRefs: []
+relatedPages: []
+tags: []
+createdAt: 2026-04-06
+updatedAt: 2026-04-06
+meetingDate:
+participants: []
+decisions: []
+---
+
+## 背景
+
+简要说明这次会议的目的和上下文，让没参加的人能快速理解为什么开这个会。
+
+## 关键讨论
+
+记录会上最重要的讨论点和不同意见，重点是分歧和最终共识，不是流水账。
+
+## 决议
+
+列出会议达成的具体决定，每条决议应该是可执行的，不是模糊的方向。
+
+## 后续待办
+
+列出需要跟进的行动项，标注负责人和预期完成时间。
+```
+
+### 配置注册
+
+```json
+"meeting-note": {
+  "file": "templates/meeting-note.md",
+  "columns": {
+    "meetingDate": "text"
+  },
+  "edges": {},
+  "summaryFields": ["meetingDate", "participants", "decisions"]
+}
+```
+
+**设计决策说明**：
+
+- `meetingDate` 建列 — 需要按日期过滤查找
+- `participants` 不建列 — 查参会人用 `tiangong-wiki fts` 搜索 summary_text 即可
+- `participants` 和 `decisions` 放入 summaryFields — 帮助搜索命中
+- `decisions` 不建 edge — 决议是文本，不是指向其他页面的引用
+- Body 4 个 section — 背景 → 讨论 → 决议 → 待办，逻辑递进
+
+---
+
+## 9. 检查清单
+
+设计完 template 后，用以下问题自检：
+
+- [ ] 新 type 的结构是否与所有现有 type 都有本质差异？
+- [ ] 每个 frontmatter 字段都有明确的查询或分类用途？
+- [ ] 需要 `tiangong-wiki find` 过滤的字段都放进了 `columns`？
+- [ ] 生成 graph 边的数组字段都定义了 `edges`？
+- [ ] `summaryFields` 包含了有助于检索的关键字段？
+- [ ] Body section 数量在 3-6 个之间，有逻辑递进？
+- [ ] Section 提示语具体而非泛泛？
+- [ ] 通过 `tiangong-wiki template create --type <type> --title <title>` 创建后，可以 `tiangong-wiki sync` + `tiangong-wiki lint` 无 error？

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

@@ -0,0 +1,110 @@
+# Vault To Wiki Instruction
+
+Use this instruction when a vault queue item must be processed into durable wiki knowledge.
+
+## Goal
+
+Turn one vault file into the smallest correct wiki knowledge update.
+
+The output may be:
+
+- no wiki change (`skip`)
+- one or more page updates (`apply`)
+- a type/template proposal without page writes (`propose_only`)
+
+Do not assume any page type is the default destination.
+
+## 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.
+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
+
+Use the CLI as the source of truth for the current ontology and page set.
+
+Prefer:
+
+- `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`
+
+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.
+
+## Decision Model
+
+Choose exactly one decision:
+
+- `skip`
+  The file is noise, duplicate, transient, unreadable, or already fully represented.
+
+- `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
+
+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
+
+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
+
+Favors `propose_only`:
+
+- the file is valuable
+- existing types are clearly awkward or lossy
+- creating a new type would materially improve ontology quality
+
+## Page Update Rules
+
+When applying changes:
+
+1. Prefer updating an existing page if the source is a revision, appendix, or direct reinforcement of that page.
+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
+
+The workflow must write a valid `result.json` manifest.
+
+Minimum expectations:
+
+- `status`
+- `decision`
+- `reason`
+- `threadId`
+- `skillsUsed`
+- `createdPageIds`
+- `updatedPageIds`
+- `appliedTypeNames`
+- `proposedTypes`
+- `actions`
+- `lint`
+
+The service layer trusts this manifest, not free-form prose.

package/references/wiki-maintenance-instruction.md

@@ -0,0 +1,190 @@
+# Wiki Maintenance Instruction
+
+Use this instruction when the agent is responsible for maintaining wiki knowledge pages, not only querying them.
+
+The deterministic layer is the CLI and SQLite index.
+The judgment layer is the agent: deciding whether knowledge is durable, which page type fits, and whether an existing page should be updated instead of creating a duplicate.
+
+## Maintenance Goals
+- Keep the wiki useful for future tasks, not bloated with one-off chatter.
+- Prefer updating the best existing page before creating near-duplicates.
+- Preserve provenance with `sourceRefs` and graph relations with `relatedPages` or page-type edge fields.
+- Re-index every edited page immediately.
+
+## Daily Maintenance Loop
+1. Run `tiangong-wiki sync`.
+2. Run `tiangong-wiki stat`.
+3. Run `tiangong-wiki lint`.
+4. Review `error` findings first.
+5. Review `warning` findings that indicate stale, orphaned, or weakly connected knowledge.
+6. Use `tiangong-wiki find`, `tiangong-wiki fts`, `tiangong-wiki search`, or `tiangong-wiki graph` to locate the best target page.
+7. Edit Markdown in `wiki/pages/`.
+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 |
+
+## Update Vs Create Decision Flow
+1. Start with a retrieval pass.
+2. If you know the target page type or node id, use `tiangong-wiki find`.
+3. If you only know a phrase, use `tiangong-wiki fts`.
+4. If the intent is fuzzy and embeddings are available, use `tiangong-wiki search`.
+5. Inspect the top candidate with `tiangong-wiki page-info`.
+6. When creating something new, inspect the ontology with `tiangong-wiki type list`, `tiangong-wiki type show`, or `tiangong-wiki type recommend`.
+7. Update the existing page when one of these is true:
+   - The new material extends the same node or page intent.
+   - The existing page already answers at least 70% of the need.
+   - The new source mainly adds evidence, examples, or corrections.
+8. Create a new page when one of these is true:
+   - The new knowledge has a distinct node id or clear separate title.
+   - The value is a new relation type, such as a new `bridge` or `misconception`.
+   - Updating the old page would mix two independent concepts.
+
+## Create Workflow
+1. Confirm no suitable active page exists.
+2. Choose the page type from the table above.
+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.
+6. Add `sourceRefs` and `relatedPages` where appropriate.
+7. Run `tiangong-wiki sync --path <page-id>`.
+8. Run `tiangong-wiki lint --path <page-id> --format json`.
+
+## Update Workflow
+1. Find the existing page.
+2. Edit the Markdown file directly.
+3. Update `updatedAt`.
+4. Add or revise `sourceRefs`.
+5. Add or revise `relatedPages` and page-type relation fields such as `prerequisites` or `correctedConcepts`.
+6. Preserve existing durable content unless it is wrong or superseded.
+7. Run `tiangong-wiki sync --path <page-id>`.
+8. Run `tiangong-wiki lint --path <page-id>`.
+
+## Archive Decision Rules
+Archive by setting `status: archived` when at least one of these is true:
+- The page has not been updated for more than 6 months and has no incoming links.
+- A newer page fully supersedes it and the old one only remains for traceability.
+- The project, context, or relationship it described has clearly ended and no longer transfers.
+
+Do not delete archived pages just because they are old.
+Archived pages remain valuable as provenance or historical context.
+
+## Do Not Create A Wiki Page When
+- The task is a one-off fact lookup with no likely future reuse.
+- The note is only a transient debugging scratchpad or temporary execution log.
+- The content is still too vague to classify and belongs in a short-lived working draft elsewhere.
+
+## Query Command Selection During Maintenance
+- Exact metadata filter: `tiangong-wiki find`
+- Keyword hunt: `tiangong-wiki fts`
+- Fuzzy intent: `tiangong-wiki search`
+- One page inspection: `tiangong-wiki page-info`
+- Network exploration: `tiangong-wiki graph`
+- Workspace overview: `tiangong-wiki stat`
+
+## Graph-Driven Exploration
+Use graph traversal when you suspect there is existing context around a concept but a simple keyword search is too shallow.
+
+Typical uses:
+- Discover prerequisites before expanding a concept page.
+- Find bridge pages that connect two contexts.
+- Detect whether a new page would be orphaned.
+- Inspect whether a correction should point to an existing concept through `correctedConcepts`.
+
+Example flow:
+```text
+1. wiki graph bayesian-theorem --depth 2
+2. Inspect prerequisite and bridge edges
+3. If a required prerequisite page is missing, create or update it
+4. If the new concept overlaps an existing subgraph, update the connected page instead of making an isolated duplicate
+```
+
+## Page-Type Specific Guidance
+### concept
+- Use for durable understanding, definitions, formulas, and reusable intuition.
+- Fill prerequisites, examples, confusions, and open questions.
+
+### misconception
+- Use when the key value is the correction itself.
+- Record the original wrong model, the turning point, and how to avoid relapse.
+
+### bridge
+- Use when the key value is transfer between source and target contexts.
+- Keep `fromConcepts` and `toConcepts` accurate so graph traversal remains useful.
+
+### source-summary
+- Use when the source file itself should remain a reusable knowledge object with explicit provenance.
+- Do not treat this as the automatic fallback for every vault file.
+- Capture the relationship between the source and existing concept pages.
+
+### lesson
+- Use when a concrete event produced a durable rule or warning.
+- Prefer `lesson` over `method` when the story of the event matters.
+
+### method
+- Use when steps, applicability, and evidence matter more than one incident.
+- Update the page as new usage records accumulate.
+
+### person
+- Use factual, respectful, context-aware notes.
+- Avoid speculative or irrelevant personal data.
+
+### achievement
+- Keep evidence and issuer information explicit.
+- Reuse this page later from `resume` or reporting workflows.
+
+### resume
+- Keep audience and tailoring notes current.
+- Update after new achievements, projects, or capability changes.
+
+### research-note
+- Prefer this when the work is ongoing and open-ended.
+- Promote mature insights into `concept` or `method` pages later if needed.
+
+### faq
+- Optimize for fast reuse.
+- Keep the short answer crisp, then elaborate underneath.
+
+## Memory To Wiki
+Use this flow when recurring memory entries have become reusable knowledge:
+
+```text
+1. Review the memory entry
+2. Ask: is this still valuable after the current day or week?
+3. tiangong-wiki find --type concept --node-id <candidate-node>
+4. If a page exists, update it
+5. If not, create the appropriate concept, lesson, method, or faq page
+6. tiangong-wiki sync --path <page-id>
+```
+
+## Profile To Wiki
+Use this flow when structured profile data should appear in wiki pages:
+
+```text
+1. Read the relevant profile data
+2. Decide whether it belongs in achievement, resume, or person pages
+3. Update frontmatter and body content with verifiable details
+4. Preserve provenance through sourceRefs when appropriate
+5. tiangong-wiki sync --path <page-id>
+```
+
+## Quality Checklist Before Finishing
+- Page type matches the actual reuse pattern.
+- `updatedAt` changed if the page changed.
+- `sourceRefs` is non-empty when knowledge came from sources.
+- Graph-related fields are populated where relevant.
+- The page is not an accidental orphan unless that is intentional.
+- `tiangong-wiki lint` returns no errors for the changed page.