ingest

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: ingest

Skill：ingest

WHAT

是什么

Purpose và context

目的与上下文

Purpose: Process new file in
```
raw/
```
, distill knowledge into wiki. Each ingest touches 10-15 wiki files.
Trigger (when to invoke): Automatically when new file appears in
```
raw/
```
.
Non-goals: không sửa file trong
```
raw/
```
, không tạo trang cho thứ nguồn không thật sự giới thiệu, không viết code/triển khai theo nội dung nguồn (đó là
```
/propose
```
→
```
/plan
```
).

目的： 处理
```
raw/
```
中的新文件，将知识提炼到 wiki 中。每次 ingest 会触及 10–15 个 wiki 文件。
触发条件（何时调用）：
```
raw/
```
中出现新文件时自动触发。
非目标： 不修改
```
raw/
```
中的文件；不为实际上没有引入相关内容的来源创建页面；不根据来源内容编写代码或进行部署（这属于
```
/propose
```
→
```
/plan
```
）。

Mental model

思维模型

raw/<file> (bất biến) → takeaways (facts · decisions · entities · concepts) → docs-impact-plan → trang concept/entity (canonical home) + trang source → wikilinks → index + log → draft output report

raw/<file>（不可变）→ takeaways（facts · decisions · entities · concepts）→ docs-impact-plan → concept/entity 页面（canonical home）+ source 页面 → wikilinks → index + log → draft 输出报告

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	đường dẫn file trong `raw/`	có	nguồn đọc TRỌN, chỉ đọc
Out	trang `wiki/concepts/` · `wiki/entities/`	theo nguồn	tạo mới hoặc cập nhật surgical, có frontmatter OKF + `## Origin`
Out	trang `wiki/sources/<...>.md`	có	tóm tắt nguồn, link về `raw/`
Out	`wiki/index.md` + `wiki/log.md`	có	mỗi file tạo/sửa có dòng index; log `## YYYY-MM-DD — ingest — <filename>`
Out	`wiki/sources/draft/DDMMYY-<ten>.md`	có (trừ khi 0 artifact)	output report

	字段	是否必填？	含义
输入	`raw/` 中的文件路径	是	完整读取来源，仅限读取
输出	`wiki/concepts/` · `wiki/entities/` 页面	根据来源决定	新建或以 surgical 方式更新，包含 OKF frontmatter + `## Origin`
输出	`wiki/sources/<...>.md` 页面	是	来源摘要，链接至 `raw/`
输出	`wiki/index.md` + `wiki/log.md`	是	每个新建或修改的文件都需在 index 中添加记录；log 使用 `## YYYY-MM-DD — ingest — <filename>`
输出	`wiki/sources/draft/DDMMYY-<ten>.md`	是（除非没有任何 artifact）	输出报告

Rules và capabilities

规则与能力

RULE-01 (MUST): OKF v0.1 (R9): every wiki page starts with a YAML frontmatter block (
```
---
```
) carrying a non-empty
```
type
```
(e.g.
```
concept
```
,
```
entity
```
,
```
source
```
) plus optional
```
title
```
/
```
tags
```
/
```
timestamp
```
/
```
resource
```
. Copy the matching
```
_template.md
```
. Keep the
```
## Origin
```
body section (R2).
RULE-02 (MUST): Never modify file in
```
raw/
```
. Read only.
RULE-03 (MUST): No wiki page unless source actually introduces that entity or concept.
RULE-04 (MUST): Prefer updating existing page over creating duplicate.
RULE-05 (MUST): Canonical home: mỗi concept một trang chính chủ — chi tiết nằm ở đó, trang khác chỉ nhắc ngắn +
```
[[wikilink]]
```
; đừng nhân bản cùng giải thích ra nhiều trang.
RULE-06 (MUST): Surgical trên trang có sẵn: cập nhật = thay đúng câu lỗi thời, không viết lại phần còn đúng; cấm edit formatting-only (reformat bảng/dòng trống/wording khi nội dung không sai).
Capabilities: đọc
```
raw/
```
; ghi
```
wiki/
```
(concepts · entities · sources · draft) + index + log. Không ghi
```
raw/
```
, không mạng.

RULE-01（MUST）：OKF v0.1（R9）： 每个 wiki 页面都必须以 YAML frontmatter 区块（
```
---
```
）开头，其中包含非空的
```
type
```
（例如
```
concept
```
、
```
entity
```
、
```
source
```
），并可选包含
```
title
```
/
```
tags
```
/
```
timestamp
```
/
```
resource
```
。复制匹配的
```
_template.md
```
。保留
```
## Origin
```
正文部分（R2）。
RULE-02（MUST）：绝不修改
```
raw/
```
中的文件。仅可读取。
RULE-03（MUST）：如果来源没有实际引入某个 entity 或 concept，则不得创建对应的 wiki 页面。
RULE-04（MUST）：优先更新现有页面，而不是创建重复页面。
RULE-05（MUST）：Canonical home： 每个 concept 只有一个主页面——详细信息放在该页，其他页面仅作简短提及并附
```
[[wikilink]]
```
；不要在多个页面重复相同解释。
RULE-06（MUST）：对现有页面进行 surgical 更新： 更新 = 只替换已经过时的确切句子，不重写仍然正确的内容；禁止进行仅涉及格式的编辑（当内容没有错误时，重排表格、空行或措辞）。
能力：读取
```
raw/
```
；写入
```
wiki/
```
（concepts · entities · sources · draft）+ index + log。不写入
```
raw/
```
，不使用网络。

Failure boundaries

失败边界

File nguồn không đọc được / rỗng → blocked, báo đường dẫn, không tạo trang.
Nguồn không giới thiệu concept/entity mới nào → chỉ trang source + index + log (succeeded hẹp), không đẻ trang thừa.
Nguồn mâu thuẫn trang wiki đang có → ghi mâu thuẫn vào trang source, clarify với user trước khi thay câu đang đúng.

来源文件无法读取或内容为空 → blocked，报告文件路径，不创建页面。
来源没有引入任何新 concept/entity → 仅创建 source 页面 + index + log（succeeded，范围较窄），不生成多余页面。
来源与现有 wiki 页面存在矛盾 → 将矛盾记录到 source 页面，在替换当前正确的句子之前与用户进行 clarify。

HOW

如何执行

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	effect	file `raw/`	Đọc trọn nguồn, không tóm tắt sớm	nội dung đầy đủ	đọc lỗi → blocked
W02	judgment	nội dung	Rút takeaways + lập docs-impact-plan	danh sách trang bị ảnh hưởng, mỗi trang truy về một điểm nguồn	trang không truy được → bỏ
W03	effect	impact-plan	Cập nhật trang có sẵn / tạo concept·entity mới	trang wiki	—
W04	effect	nguồn	Trang source trong `wiki/sources/` link về `raw/`	trang source	—
W05	effect	trang đã chạm	Wikilinks + `wiki/index.md` + `wiki/log.md`	index/log khớp	thiếu dòng index → sửa rồi lặp
W06	effect	kết quả	Output report draft (mục Delivery)	draft + index + log	0 artifact → skip

Chi tiết từng bước (nguồn chân lý cho W01–W06):

Read source file in
```
raw/
```
completely. No premature summarizing.
Extract key takeaways: facts, decisions, entities, concepts from source. Rồi lập docs-impact-plan trước khi ghi (distill openwiki 060726):
```
điểm mới trong nguồn → trang bị ảnh hưởng → sửa/tạo gì → vì sao
```
. Trang không truy được về một điểm cụ thể trong nguồn thì KHÔNG đụng.
For each entity or concept:
- Has wiki page: open it, add/revise relevant info.
- No page: create in
```
wiki/concepts/
```
  or
```
wiki/entities/
```
  .
Create or update summary page in
```
wiki/sources/
```
for source (link back to
```
raw/
```
file).
Add
```
[[wikilinks]]
```
between all new/updated pages.
Update
```
wiki/index.md
```
for every file created or modified.

Append to

wiki/log.md

## YYYY-MM-DD — ingest — <filename>

with bullet list of all pages touched.

步骤	类型	输入	操作	输出／退出条件	失败／下一步
W01	effect	`raw/` 文件	完整读取来源，不提前总结	完整内容	读取失败 → blocked
W02	judgment	内容	提取 takeaways + 制定 docs-impact-plan	受影响页面列表，每个页面都回溯到一个来源要点	无法回溯的页面 → 忽略
W03	effect	impact-plan	更新现有页面／创建新的 concept·entity	wiki 页面	—
W04	effect	来源	在 `wiki/sources/` 中创建 source 页面，并链接至 `raw/`	source 页面	—
W05	effect	已触及的页面	Wikilinks + `wiki/index.md` + `wiki/log.md`	index/log 一致	缺少 index 行 → 修复后重试
W06	effect	结果	输出报告草稿（见“交付”部分）	draft + index + log	0 artifact → 跳过

各步骤的详细信息（W01–W06 的真相来源）：

完整读取
```
raw/
```
中的来源文件。不要提前总结。
提取关键 takeaways：来源中的 facts、decisions、entities、concepts。写入前先制定 docs-impact-plan（distill openwiki 060726）：
```
来源中的新要点 → 受影响的页面 → 修改或创建什么 → 为什么
```
。无法回溯到来源中某个具体要点的页面绝对不要改动。
对于每个 entity 或 concept：
- 已有 wiki 页面：打开页面，添加或修订相关信息。
- 没有页面：从
```
_template.md
```
  在
```
wiki/concepts/
```
  或
```
wiki/entities/
```
  中创建页面。
在
```
wiki/sources/
```
中为该来源创建或更新摘要页面（链接回
```
raw/
```
文件）。
在所有新建或更新的页面之间添加
```
[[wikilinks]]
```
。
为每个创建或修改的文件更新
```
wiki/index.md
```
。
追加到
```
wiki/log.md
```
：
```
## YYYY-MM-DD — ingest — <filename>
```
，并附上所有已触及页面的列表。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	entity/concept đã có trang	mở trang, thêm/sửa đúng câu liên quan (surgical)	—	W04
B02	conditional_required	entity/concept chưa có trang	tạo trong `wiki/concepts/` hoặc `wiki/entities/` từ `_template.md`	nguồn không thật sự giới thiệu → không tạo	W04

ID	类型	条件	行为	跳过／失败	汇合点
B01	conditional_required	entity/concept 已有页面	打开页面，以 surgical 方式添加或修改相关句子	—	W04
B02	conditional_required	entity/concept 没有页面	根据 `_template.md` 在 `wiki/concepts/` 或 `wiki/entities/` 中创建	来源没有实际引入该内容 → 不创建	W04

Validation và stopping

验证与停止条件

Mỗi trang mới có frontmatter

type

không rỗng +

## Origin

(R2/R9 do hook kiểm); mỗi file tạo/sửa có dòng trong

wiki/index.md

(R3). Dừng khi mọi mục của impact-plan đã xử lý hoặc bị loại có lý do.

每个新页面都必须包含非空 frontmatter

type

和

## Origin

（R2/R9 由 hook 检查）；每个新建或修改的文件都必须在

wiki/index.md

中有一行记录（R3）。当 impact-plan 中的所有项目均已处理或已给出理由排除时停止。

Examples

示例

Positive: thêm
```
raw/prd/X-PRD.md
```
giới thiệu chuẩn mới → tạo
```
wiki/concepts/<chuẩn>.md
```
+
```
wiki/sources/DDMMYY-x-prd.md
```
, sửa 1 câu ở concept liên quan, index + log + draft report.
Boundary/failure: file raw chỉ là ảnh chụp màn hình không có chữ đọc được → blocked, báo user, không tạo trang rỗng.

正向示例： 添加一个引入新标准的
```
raw/prd/X-PRD.md
```
→ 创建
```
wiki/concepts/<标准>.md
```
+
```
wiki/sources/DDMMYY-x-prd.md
```
，在相关 concept 页面中修改 1 个句子，并更新 index + log + draft report。
边界／失败示例： raw 文件只是一张没有可读文字的屏幕截图 → blocked，通知用户，不创建空页面。

Delivery — Output Report

交付 —— 输出报告

After all main skill tasks complete, write a propose draft to the wiki.

在所有主 skill 任务完成后，向 wiki 写入一份 propose 草稿。

Steps

步骤

1. Build the filename:

Format:
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= today (e.g.,
```
020626
```
for 2 June 2026)

<ten>

= 2–4 kebab-case words summarising what was done (e.g.,

landing-page-coteccons

brand-kit-fintech

ingest-auth-spec

)

2. Write

llmwiki/wiki/sources/draft/DDMMYY-<ten>.md

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

1. 构建文件名：

格式：
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= 今天（例如，
```
020626
```
表示 2026 年 6 月 2 日）
```
<ten>
```
= 2–4 个概括完成工作的 kebab-case 单词（例如，
```
landing-page-coteccons
```
、
```
brand-kit-fintech
```
、
```
ingest-auth-spec
```
）

2. 写入

llmwiki/wiki/sources/draft/DDMMYY-<ten>.md

：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-<ten>

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

What

Output

Files

File	Action
`path/to/file`	created / modified

File	Action
`path/to/file`	created / modified

Notes

Invoked via:
```
/<skill-name>
```
skill

Invoked via:
```
/<skill-name>
```
skill

Origin

Draft:
```
wiki/sources/draft/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append one row: `| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — <skill-name> — <ten>`

> Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like `/caveman-stats`).

Draft:
```
wiki/sources/draft/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. 更新 wiki index 与 log：**
- `llmwiki/wiki/index.md` —— 追加一行：`| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` —— 追加：`## YYYY-MM-DD — <skill-name> — <ten>`

> 仅当 skill 未产生任何 artifact 和 decision 时才跳过（例如，像 `/caveman-stats` 这样的纯展示模式）。