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.mdindex 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.mdnew file mode 100644index 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 detectiondiff --git a/docs/en/cli/index.md b/docs/en/cli/index.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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.ymlindex 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