wiki-ingest

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ingest — Process source into the wiki

摄入——将源文件处理并整合到wiki中

wiki/CONVENTIONS.md

for format conventions, frontmatter, naming, and language.

请遵循

wiki/CONVENTIONS.md

中的格式规范、前置元数据、命名规则和语言要求。

Language

语言要求

Write the artifact in the user's language. Apply correct grammar and any required diacritics or script-specific characters. If the user's language is unclear, ask before generating output.

以用户使用的语言编写产物，确保语法正确，并使用必要的变音符号或特定脚本字符。若用户使用的语言不明确，请在生成输出前询问用户。

Project root

项目根目录

This skill writes artifacts at paths relative to the project root (the repo where the work happens), not the agent's current working directory.

If invoked from inside the project, use the relative paths shown in this skill.
If invoked from another directory (e.g., a sibling repo, or when the project lives elsewhere), prepend
```
<project-root>/
```
to every artifact path.
When the project root is ambiguous, confirm with the user via the harness question tool before writing.

本技能会以项目根目录（即工作所在的代码仓库）为基准写入产物路径，而非Agent当前的工作目录。

若从项目内部调用，请使用本技能中所示的相对路径。
若从其他目录调用（例如同级仓库，或项目位于其他位置），请在所有产物路径前添加
```
<project-root>/
```
。
若项目根目录不明确，请先通过harness提问工具与用户确认后再写入。

Prompting

提示规范

Follow the project-wide convention in

CLAUDE.md

AGENTS.md

("Skill Prompting Conventions"). Use the harness's structured-question tool —

AskUserQuestion

(Claude Code),

ask_user_question

(Codex), or

question

(OpenCode) — for the decision points below. Use free-form text only where a path/name/value cannot be enumerated.

Decision point	Why structured	Suggested options
Existing page to absorb the new content (or create new)	Affects wiki layout	match list · create new
Audience folders to split the source across (multi-select)	Maintains separation	business · apps · ops · data
Emphasize or skip individual points (multi-select)	Affects what lands	select from points found

Free-form prompts (no structured tool):

Page titles
Summary text
Tag values

No-pause mode: if the user has explicitly disabled mid-skill clarification, convert every structured prompt into an entry under Open questions (or equivalent) and proceed without blocking.

遵循

CLAUDE.md

AGENTS.md

中的项目级规范（"Skill Prompting Conventions"）。针对以下决策点，使用harness的结构化提问工具：Claude Code使用

AskUserQuestion

，Codex使用

ask_user_question

，OpenCode使用

question

。仅当路径/名称/值无法枚举时，才使用自由格式文本。

决策点	使用结构化工具的原因	建议选项
用于吸收新内容的现有页面（或创建新页面）	影响wiki布局	匹配现有列表 · 创建新页面
拆分源文件的受众文件夹（可多选）	保持内容区分	business · apps · ops · data
强调或跳过个别要点（可多选）	影响最终纳入的内容	从识别出的要点中选择

无需使用结构化工具的自由格式提示：

页面标题
摘要文本
标签值

无暂停模式：若用户明确禁用技能执行中的澄清环节，请将所有结构化提示转换为「开放式问题」（或等效项）下的条目，无需等待回复即可继续执行。

Query language alignment

查询语言对齐

When matching a source against existing wiki pages, search in the wiki language, not necessarily in the user's or source's language. Determine the wiki language from

.wiki-guardrails.yml

(

query_language

language

), then from wiki frontmatter/index if guardrails are absent. Keep product names, filenames, APIs, schema names, and code identifiers unchanged.

Translate QMD
```
intent:
```
,
```
vec:
```
, and
```
hyde:
```
into the wiki language.
Keep exact source terms in
```
lex:
```
when they may appear untranslated.
Write/update wiki artifacts in the wiki language unless the target page clearly uses another language.
Communicate progress and questions to the user in the user's language.

将源文件与现有wiki页面匹配时，请使用wiki的语言进行搜索，而非用户或源文件的语言。优先从

.wiki-guardrails.yml

文件的

query_language

或

language

字段确定wiki语言；若该文件不存在，则从wiki的前置元数据/索引中判断。产品名称、文件名、API、 schema名称和代码标识符保持不变。

将QMD的
```
intent:
```
、
```
vec:
```
和
```
hyde:
```
字段翻译为wiki语言。
若
```
lex:
```
中的源术语可能以未翻译形式出现，请保留原文。
除非目标页面明确使用其他语言，否则请以wiki语言编写/更新wiki产物。
以用户使用的语言向其沟通进度和问题。

Retrieval — prefer QMD when available

检索——优先使用QMD（若可用）

When searching for existing pages that should absorb the new source, use QMD (local hybrid search) if it is set up for this wiki. Setup is one-time per repo — see

docs/wiki/qmd-setup.md

Use
```
mcp__qmd__query
```
(MCP) or
```
qmd query --json --files
```
(CLI) instead of grep/glob whenever available.
Always pass an
```
intent:
```
line to QMD describing the topic of the new source — it dramatically improves the matches against existing pages.
Fall back to
```
grep
```
/
```
Glob
```
only when QMD is not configured.

After the ingest finishes, remind the owner to run

qmd update

(or

qmd embed

if a new collection was added) so the index reflects the new pages — never run those commands automatically.

搜索应吸收新源文件的现有页面时，若本wiki已配置QMD（本地混合搜索工具），请优先使用它。每个仓库只需配置一次——详见

docs/wiki/qmd-setup.md

。

只要可用，请使用
```
mcp__qmd__query
```
（MCP）或
```
qmd query --json --files
```
（CLI）替代grep/glob。
务必向QMD传递一条
```
intent:
```
行，描述新源文件的主题——这能大幅提升与现有页面的匹配效果。
仅当未配置QMD时，才回退使用
```
grep
```
/
```
Glob
```
。

摄入完成后，请提醒所有者运行

qmd update

（若添加了新集合则运行

qmd embed

），使索引能反映新增页面——请勿自动运行这些命令。

Steps

执行步骤

Identify the source the user asked to process (comes from the conversation context or the provided path).
Check if it has already been ingested by consulting
```
raw/index.md
```
:
- If already ingested (has a summary in
```
wiki/sources/
```
  ) → follow the Re-ingest flow (section below).
- If not → proceed with normal ingest.
Read the source in
```
raw/
```
completely (in parts if needed due to context limits).
- ```
.txt
```
  or
```
.md
```
  transcripts → read directly.
- If MCP
```
video-whisper
```
  is available → transcribe video/audio directly.
- If MCP
```
pdf-docling
```
  is available → convert PDF to markdown.
Extract and present in parallel:
- Identify the 3-5 most important points in the source.
- For each point, run a QMD query (or grep fallback) to find related existing pages — use the point itself as
```
intent:
```
  and a short paraphrase as
```
vec:
```
  .
- Present the points to the human alongside the matched pages.
- Ask if the user wants to emphasize or skip anything.
- Wait for confirmation before proceeding.
Decide where each rule lands. Respect the audience separation:
- ```
wiki/business/
```
  — all business/product rules (audience: business). Pricing, journeys, policies, monetization, privacy/compliance rules, anything customer-facing or contractual.
- ```
wiki/apps/
```
  — app-level technical docs (audience: dev). Stack, gotchas, deploy specifics. No business rules here — link out to
```
wiki/business/
```
  if relevant.
- ```
wiki/ops/
```
  — operational procedures (audience: ops).
- ```
wiki/data/
```
  — data models and schemas (audience: dev).
- If the source mixes business and technical content, split it across the right folders rather than mashing everything into one page.
Create/update wiki pages based on confirmation:
- If the page already exists → update (add source in
```
sources:
```
  , revise content, flag contradictions).
- If it does not exist → create a new page following
```
wiki/CONVENTIONS.md
```
  .
- Use standard markdown links:
```
[text](./path.md)
```
  (not wikilinks).
- Do NOT duplicate content across pages — use cross-refs.
- Sibling repos are referenced as
```
../<repo>/
```
  (relative to the wiki), not absolute paths. Add the GitHub remote link
```
[github.com/<org>/<repo>](https://github.com/<org>/<repo>)
```
  when first introducing the repo.
Create the source summary in
```
wiki/sources/<slug>.md
```
:
yaml
```
---
title: "Summary — <Source Title>"
audience: mixed
sources:
  - raw/<subdir>/<filename>
updated: YYYY-MM-DD
tags: [source, <relevant-tags>]
status: stable
---
```
Summary content:
- Metadata (date, participants, duration if applicable)
- Key points summary
- Wiki pages created/updated with links
- Insights not captured in other pages (if any)
- Decisions left pending — surface explicitly if the source raises questions the owner needs to answer rather than silently picking a side.
Update indexes in parallel:
- ```
raw/index.md
```
  — mark the source as ✅ Ingested with a link to the summary.
- ```
wiki/index.md
```
  — add new pages to the corresponding table, update descriptions of modified pages.
- ```
wiki/log.md
```
  — log the operation at the top (after the header, before existing entries):
```
## [YYYY-MM-DD] ingest | <Source Title>
- Pages created: ...
- Pages updated: ...
- Summary: wiki/sources/<slug>.md
```
Focused post-ingest lint:
- Verify cross-refs of created/updated pages (do links point to real targets?).
- Compare with referenced pages — flag contradictions with an explicit section.
- Do NOT run a full lint (orphans, global frontmatter, etc.) — that is for
```
/wiki-lint
```
  .
Tell the owner to refresh the QMD index (only if QMD is configured for this wiki):
```
qmd update         # picks up changed/new pages
qmd embed          # only needed if you added/removed a collection
```
Do not run these for the owner — surface them in the final report.

识别源文件：确定用户要求处理的源文件（来自对话上下文或提供的路径）。
检查是否已摄入：查看
```
raw/index.md
```
：
- 若已摄入（
```
wiki/sources/
```
  中已有摘要）→ 遵循重新摄入流程（见下文章节）。
- 若未摄入→ 执行正常摄入流程。
读取源文件：完整读取
```
raw/
```
目录下的源文件（若受上下文限制，可分部分读取）。
- ```
.txt
```
  或
```
.md
```
  转录文件→ 直接读取。
- 若MCP
```
video-whisper
```
  可用→ 直接转录视频/音频文件。
- 若MCP
```
pdf-docling
```
  可用→ 将PDF转换为markdown格式。
提取并并行展示：
- 识别源文件中3-5个最重要的要点。
- 针对每个要点，运行QMD查询（或回退使用grep）查找相关现有页面——将要点本身作为
```
intent:
```
  ，简短改写作为
```
vec:
```
  。
- 将要点与匹配的页面一并展示给用户。
- 询问用户是否需要强调或跳过某些内容。
- 等待用户确认后再继续执行。
确定内容归属：遵循受众区分规则：
- ```
wiki/business/
```
  —— 所有业务/产品规则（受众：业务人员）。定价、用户旅程、政策、盈利模式、隐私/合规规则、任何面向客户或合同相关内容。
- ```
wiki/apps/
```
  —— 应用级技术文档（受众：开发人员）。技术栈、常见问题、部署细节。此处不得包含业务规则——若相关，请链接至
```
wiki/business/
```
  中的内容。
- ```
wiki/ops/
```
  —— 操作流程文档（受众：运维人员）。
- ```
wiki/data/
```
  —— 数据模型与schema文档（受众：开发人员）。
- 若源文件同时包含业务和技术内容，请拆分到对应文件夹，而非将所有内容合并到一个页面。
创建/更新wiki页面：根据用户确认执行：
- 若页面已存在→ 更新（在
```
sources:
```
  中添加源文件、修订内容、标记矛盾点）。
- 若页面不存在→ 创建新页面，遵循
```
wiki/CONVENTIONS.md
```
  规范。
- 使用标准markdown链接：
```
[text](./path.md)
```
  （而非wiki链接）。
- 请勿在多个页面间重复内容——使用交叉引用。
- 同级仓库引用格式为
```
../<repo>/
```
  （相对于wiki目录），而非绝对路径。首次引入仓库时，请添加GitHub远程链接
```
[github.com/<org>/<repo>](https://github.com/<org>/<repo>)
```
  。
在
wiki/sources/<slug>.md
中创建源文件摘要：
yaml
```
---
title: "Summary — <Source Title>"
audience: mixed
sources:
  - raw/<subdir>/<filename>
updated: YYYY-MM-DD
tags: [source, <relevant-tags>]
status: stable
---
```
摘要内容：
- 元数据（日期、参与者、时长，若适用）
- 要点总结
- 创建/更新的wiki页面及链接
- 未在其他页面中体现的洞察（若有）
- 待解决的决策——若源文件提出需要所有者回答的问题，请明确指出，而非自行决定。
并行更新索引：
- ```
raw/index.md
```
  —— 将源文件标记为✅已摄入，并添加指向摘要的链接。
- ```
wiki/index.md
```
  —— 将新页面添加到对应表格，更新已修改页面的描述。
- ```
wiki/log.md
```
  —— 在顶部（标题后、现有条目前）记录操作：
```
## [YYYY-MM-DD] ingest | <Source Title>
- Pages created: ...
- Pages updated: ...
- Summary: wiki/sources/<slug>.md
```
摄入后聚焦式检查：
- 验证创建/更新页面的交叉引用（链接是否指向有效目标？）。
- 与引用页面对比——用明确的章节标记矛盾点。
- 请勿运行完整检查（孤立页面、全局前置元数据等）——这是
```
/wiki-lint
```
  的职责。
告知所有者刷新QMD索引（仅当本wiki已配置QMD时）：
```
qmd update         # 识别变更/新增页面
qmd embed          # 仅在添加/移除集合时需要执行
```
请勿替所有者运行这些命令——请在最终报告中提示。

Re-ingest (already cataloged source)

重新摄入（已编入目录的源文件）

When the source already has

wiki/sources/<slug>.md

Read the source and the existing summary.
Compare and identify gaps:
- Concepts/information in the source that are not in the wiki (use QMD with
```
intent:
```
  set to each gap candidate to confirm absence)
- Pages that can be expanded
- Contradictions with existing content

Present the diagnosis to the human:

## Re-ingest: <Title>
### Identified gaps
- ...
### Pages that can be expanded
- ...

Wait for approval and execute.
Update the summary,
```
raw/index.md
```
, and
```
wiki/log.md
```
.

若源文件已存在

wiki/sources/<slug>.md

：

读取源文件和现有摘要。
对比并识别差异：
- 源文件中有但wiki中没有的概念/信息（使用QMD，将
```
intent:
```
  设为每个候选差异点以确认缺失）
- 可扩展的页面
- 与现有内容的矛盾点

将诊断结果展示给用户：

## 重新摄入：<Title>
### 识别出的差异
- ...
### 可扩展的页面
- ...

等待用户批准后执行。
更新摘要、
```
raw/index.md
```
和
```
wiki/log.md
```
。

Rules

规则

Never modify files in
```
raw/
```
.
One source at a time (unless the user explicitly asks for batch).
Always use complete YAML frontmatter (see
```
wiki/CONVENTIONS.md
```
).
If you find a contradiction with existing pages, flag it explicitly.
Always update
```
raw/index.md
```
,
```
wiki/index.md
```
, and
```
wiki/log.md
```
.
Business rules belong in
wiki/business/
, never inside product/code repos. If a rule is currently sitting in a product repo (somewhere like
```
../<product>/docs/
```
), the ingest should migrate it to
```
wiki/business/
```
and leave a cross-ref in the product repo's
```
CLAUDE.md
```
/
```
AGENTS.md
```
if appropriate.
Never run
```
qmd embed
```
/
```
qmd update
```
/
```
qmd collection add
```
automatically — those are owner-run commands.

禁止修改
```
raw/
```
目录下的文件。
一次处理一个源文件（除非用户明确要求批量处理）。
务必使用完整的YAML前置元数据（详见
```
wiki/CONVENTIONS.md
```
）。
若发现与现有页面的矛盾点，请明确标记。
务必更新
```
raw/index.md
```
、
```
wiki/index.md
```
和
```
wiki/log.md
```
。
业务规则应放在
wiki/business/
中，绝不能放在产品/代码仓库中。若规则当前位于产品仓库（例如
```
../<product>/docs/
```
），摄入流程应将其迁移至
```
wiki/business/
```
，并酌情在产品仓库的
```
CLAUDE.md
```
/
```
AGENTS.md
```
中添加交叉引用。
禁止自动运行
```
qmd embed
```
/
```
qmd update
```
/
```
qmd collection add
```
——这些命令需由所有者执行。