Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

docs: he tag command reference + scoped search options (EN+ZH)

yifanfeng978f2fe20d5c83
diff --git a/docs/en/cli/commands/search.md b/docs/en/cli/commands/search.md
index b16d51c..ef234d2 100644
--- a/docs/en/cli/commands/search.md
+++ b/docs/en/cli/commands/search.md
@@ -22,6 +22,8 @@ he search KA_PATH QUERY [OPTIONS]
| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--top-k` | `-n` | Number of results to return | 3 |
+| `--source` | — | Scope: only knowledge contributed by these source documents (repeatable) | — |
+| `--tag` | — | Scope: only knowledge from sources carrying these tags (repeatable) | — |
---
@@ -114,6 +116,24 @@ Result 3:
---
+## Scoped Search
+
+Restrict search to a subset of sources with `--source` (specific source documents) or `--tag` (any source carrying the tag — set tags with [`he tag`](tag.md)):
+
+```bash
+# Only knowledge contributed by sources tagged `legal`
+he search ./ka/ "termination" --tag legal
+
+# Only knowledge contributed by two specific documents
+he search ./ka/ "termination" --source contract-2024 --source annex-b
+```
+
+`--source` and `--tag` combine as a union: a key matches when **any** of its contributing sources fits either filter.
+
+> Scoping requires the KA to have been fed with `--source`, so the source ledger exists — see [Source Attribution & Provenance](../../python/guides/provenance.md).
+
+---
+
## Comparison with `he talk`
| Feature | `he search` | `he talk` |
diff --git a/docs/en/cli/commands/tag.md b/docs/en/cli/commands/tag.md
new file mode 100644
index 0000000..669a5c8
--- /dev/null
+++ b/docs/en/cli/commands/tag.md
@@ -0,0 +1,90 @@
+# he tag
+
+Manage tags on source documents of a knowledge abstract — organize sources for scoped search and rollback.
+
+---
+
+## Synopsis
+
+```bash
+he tag KA_PATH --source SOURCE_ID [--add TAG ...] [--remove TAG ...]
+he tag KA_PATH --list
+he tag KA_PATH --source SOURCE_ID # show current tags
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `KA_PATH` | Path to the knowledge abstract directory |
+
+## Options
+
+| Option | Alias | Default | Description |
+|--------|-------|---------|-------------|
+| `--source TEXT` | — | **required** | Source document id to tag |
+| `--add TEXT` | — | — | Tag(s) to add (repeatable) |
+| `--remove TEXT` | — | — | Tag(s) to remove (repeatable) |
+| `--list` | `-l` | off | List all sources with their tags |
+
+---
+
+## Description
+
+`he tag` attaches free-form labels to the source documents inside a knowledge abstract:
+
+- **Persistence** — tags are stored in the **source ledger** (`sources_nodes.json` / `sources_edges.json`), the same files that record [`he feed --source`](feed.md) attribution, so they persist with the KA across `he dump` / `he load`.
+- **Scoped retrieval** — tags let you restrict [`he search`](search.md) to knowledge contributed by sources carrying a given tag (see [Scoped Search](#scoped-search)).
+- **Availability** — works for graph-family knowledge abstracts, i.e. any KA whose source ledger tracks provenance (see [Source Attribution & Provenance](../../python/guides/provenance.md)).
+
+---
+
+## Examples
+
+### Add tags to a source
+
+```bash
+he tag ./ka/ --source contract-2024 --add legal --add reviewed
+# → Tagged! contract-2024: legal, reviewed
+```
+
+### Remove tags from a source
+
+```bash
+he tag ./ka/ --source contract-2024 --remove reviewed
+```
+
+### Show current tags of a source
+
+```bash
+he tag ./ka/ --source contract-2024
+# → contract-2024 tags: legal
+```
+
+### List all sources with their tags
+
+```bash
+he tag ./ka/ --list
+```
+
+Prints a table of the source ledger: source id, number of raw items, and tags.
+
+---
+
+## Scoped Search
+
+Tags become useful together with the `--tag` option of [`he search`](search.md):
+
+```bash
+# Only search knowledge contributed by sources tagged `legal`
+he search ./ka/ "termination" --tag legal
+```
+
+Scoping requires the sources to have been ingested with attribution (`he feed ./ka/ doc.md --source contract-2024`), so the ledger exists.
+
+---
+
+## See Also
+
+- [`he remove`](remove.md) — document rollback (`--document`), including the same source ledger
+- [Source Attribution & Provenance](../../python/guides/provenance.md) — source attribution, the ledger, and change detection
diff --git a/docs/en/cli/index.md b/docs/en/cli/index.md
index c7d8a06..7b44d52 100644
--- a/docs/en/cli/index.md
+++ b/docs/en/cli/index.md
@@ -35,13 +35,14 @@ he --version
| `he export obsidian` | Export to an Obsidian vault | `-o` output, `--name`, `-f` force |
| `he export graphml` | Export a pairwise graph to GraphML | `-o` output file |
| `he export csv` | Export nodes/edges as CSV tables | `-o` directory, `-f` force |
-| `he search` | Semantic search in knowledge abstract | `-n` top-k results |
+| `he search` | Semantic search in knowledge abstract | `-n` top-k results, `--source`, `--tag` |
| `he talk` | Chat with knowledge abstract | `-i` interactive, `-q` query |
| `he feed` | Add documents incrementally | `--source` attribution |
| `he info` | Show knowledge abstract statistics | — |
| `he build-index` | Build/rebuild search index | `-f` force rebuild |
| `he clean` | Remove a KA's index (or the whole KA) | `-a` all, `-y` yes |
| `he remove` | Delete nodes/edges by key, or soft-remove a single fact | `--node`, `--edge`, `--edit-node`, `--fact`, `--dry-run`, `--document`, `--strategy` |
+| `he tag` | Manage source tags | `--source`, `--add`, `--remove`, `--list` |
| `he list` | List templates and methods | `template` or `method` |
| `he template validate` | Validate a template YAML file | `--json`, `--all` |
| `he config` | Manage configuration | `init`, `show`, `llm`, `embedder` |
diff --git a/docs/zh/cli/commands/search.md b/docs/zh/cli/commands/search.md
index c278f32..3cf878d 100644
--- a/docs/zh/cli/commands/search.md
+++ b/docs/zh/cli/commands/search.md
@@ -22,6 +22,8 @@ he search KA_PATH QUERY [OPTIONS]
| 选项 | 简写 | 描述 | 默认值 |
|--------|-------|-------------|---------|
| `--top-k` | `-n` | 返回结果数量 | 3 |
+| `--source` | — | 范围限定:仅返回这些来源文档贡献的知识(可重复) | — |
+| `--tag` | — | 范围限定:仅返回带有这些标签的来源贡献的知识(可重复) | — |
---
@@ -114,6 +116,24 @@ Result 3:
---
+## 范围搜索
+
+使用 `--source`(指定来源文档)或 `--tag`(带有该标签的任意来源 —— 标签用 [`he tag`](tag.md) 管理)将搜索限定到部分来源:
+
+```bash
+# 仅搜索带有 `legal` 标签的来源贡献的知识
+he search ./ka/ "终止条件" --tag legal
+
+# 仅搜索两个指定文档贡献的知识
+he search ./ka/ "终止条件" --source contract-2024 --source annex-b
+```
+
+`--source` 与 `--tag` 以并集方式组合:只要某个键的**任一**贡献来源满足任一过滤条件,该键即匹配。
+
+> 范围限定要求知识库在摄入时带有 `--source`,这样来源台账才会存在 —— 见[来源标注与溯源](../../python/guides/provenance.md)。
+
+---
+
## 与 `he talk` 的比较
| 功能 | `he search` | `he talk` |
diff --git a/docs/zh/cli/commands/tag.md b/docs/zh/cli/commands/tag.md
new file mode 100644
index 0000000..a3c69a3
--- /dev/null
+++ b/docs/zh/cli/commands/tag.md
@@ -0,0 +1,90 @@
+# he tag
+
+管理知识库来源文档的标签 —— 组织来源,用于范围搜索和回滚。
+
+---
+
+## 概要
+
+```bash
+he tag KA_PATH --source SOURCE_ID [--add TAG ...] [--remove TAG ...]
+he tag KA_PATH --list
+he tag KA_PATH --source SOURCE_ID # 查看当前标签
+```
+
+## 参数
+
+| 参数 | 描述 |
+|----------|-------------|
+| `KA_PATH` | 知识库目录的路径 |
+
+## 选项
+
+| 选项 | 简写 | 默认值 | 描述 |
+|--------|-------|---------|-------------|
+| `--source TEXT` | — | **必填** | 要打标签的来源文档 id |
+| `--add TEXT` | — | — | 要添加的标签(可重复) |
+| `--remove TEXT` | — | — | 要移除的标签(可重复) |
+| `--list` | `-l` | off | 列出所有来源及其标签 |
+
+---
+
+## 描述
+
+`he tag` 为知识库内的来源文档附加自由格式的标签:
+
+- **持久化** — 标签保存在**来源台账**(`sources_nodes.json` / `sources_edges.json`)中,与 [`he feed --source`](feed.md) 记录来源标注使用的是同一组文件,因此标签随知识库一起在 `he dump` / `he load` 之间持久保存。
+- **范围检索** — 标签允许你将 [`he search`](search.md) 限定为带有指定标签的来源所贡献的知识(见下方「范围搜索」章节)。
+- **可用范围** — 适用于图谱族知识库,即来源台账会追踪来源的知识库(见[来源标注与溯源](../../python/guides/provenance.md))。
+
+---
+
+## 示例
+
+### 为来源添加标签
+
+```bash
+he tag ./ka/ --source contract-2024 --add legal --add reviewed
+# → Tagged! contract-2024: legal, reviewed
+```
+
+### 移除来源的标签
+
+```bash
+he tag ./ka/ --source contract-2024 --remove reviewed
+```
+
+### 查看来源的当前标签
+
+```bash
+he tag ./ka/ --source contract-2024
+# → contract-2024 tags: legal
+```
+
+### 列出所有来源及其标签
+
+```bash
+he tag ./ka/ --list
+```
+
+输出来源台账表格:来源 id、原始条目数和标签。
+
+---
+
+## 范围搜索
+
+标签与 [`he search`](search.md) 的 `--tag` 选项配合使用:
+
+```bash
+# 只搜索带有 `legal` 标签的来源所贡献的知识
+he search ./ka/ "终止条件" --tag legal
+```
+
+范围限定要求来源在摄入时带有标注(`he feed ./ka/ doc.md --source contract-2024`),这样台账才会存在。
+
+---
+
+## 另请参见
+
+- [`he remove`](remove.md) — 文档级回滚(`--document`),使用同一份来源台账
+- [来源标注与溯源](../../python/guides/provenance.md) — 来源标注、来源台账与变更检测
diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.md
index ef2fb31..e8b2b64 100644
--- a/docs/zh/cli/index.md
+++ b/docs/zh/cli/index.md
@@ -35,13 +35,14 @@ he --version
| `he export obsidian` | 导出为 Obsidian 知识库 | `-o` 输出, `--name`, `-f` 强制 |
| `he export graphml` | 将二元图导出为 GraphML | `-o` 输出文件 |
| `he export csv` | 将节点/边导出为 CSV 表 | `-o` 目录, `-f` 强制 |
-| `he search` | 知识库语义搜索 | `-n` top-k 结果数 |
+| `he search` | 知识库语义搜索 | `-n` top-k 结果数, `--source`, `--tag` |
| `he talk` | 与知识库对话 | `-i` 交互模式, `-q` 查询 |
| `he feed` | 增量添加文档 | `--source` 来源标注 |
| `he info` | 显示知识库统计信息 | — |
| `he build-index` | 构建/重建搜索索引 | `-f` 强制重建 |
| `he clean` | 删除 KA 的索引(或整个 KA) | `-a` all, `-y` yes |
| `he remove` | 按键删除节点/边,或软删除单条事实 | `--node`、`--edge`、`--edit-node`、`--fact`、`--dry-run`、`--document`、`--strategy` |
+| `he tag` | 管理来源标签 | `--source`、`--add`、`--remove`、`--list` |
| `he list` | 列出模板和方法 | `template` 或 `method` |
| `he template validate` | 校验模板 YAML | `--json`、`--all` |
| `he config` | 管理配置 | `init`, `show`, `llm`, `embedder` |
diff --git a/mkdocs.yml b/mkdocs.yml
index 8025ddf..e052843 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -79,6 +79,7 @@ plugins:
- cli/commands/clean.md
- cli/commands/remove.md
- cli/commands/search.md
+ - cli/commands/tag.md
- cli/commands/talk.md
- cli/commands/info.md
- cli/commands/list.md
@@ -176,6 +177,7 @@ plugins:
- zh/cli/commands/clean.md
- zh/cli/commands/remove.md
- zh/cli/commands/search.md
+ - zh/cli/commands/tag.md
- zh/cli/commands/talk.md
- zh/cli/commands/info.md
- zh/cli/commands/list.md