# tools/ 接口手册

三个脚本，会用就行，**不用读源码**。都从仓库根目录跑（脚本内部会处理路径）。

## scope-link.py —— 作用域定位（Phase2 用）

候选作用域值 → 5 棵树本地向量缓存余弦最近邻 top-K。判「复用现有节点原名 or 保留新值」。

```bash
python 创作知识提取-skill/tools/scope-link.py "撕裂共识" --type effect --top-k 5
python 创作知识提取-skill/tools/scope-link.py "三幕结构" --type 形式
```
- `--type`：substance/form/feeling/effect/intent 或中文；不传 = 跨 5 棵树搜。
- 输出 JSON：`{candidate, type, hits:[{name, path, source_type, score}]}`。
- 判读：score ≥ ~0.90 复用 `name`；0.75–0.90 看 top-K 有无真同义；< 0.75 用候选值（新值）。
- 依赖 `scope_trees/` 本地缓存（先 `python scripts/dump_trees.py` + `python scripts/embed_trees.py`，需 PYTHONPATH=. 与 .env）。

## lint-payload.py —— 校验（Phase3 用）

校验单个 payload 或 payload 数组（一帖多颗）：结构 + dim_creations 写死 + dim_attributes 类型 + scopes 带值 + custom_ext 枚举 + How/What/Why 形态一致性。

```bash
python 创作知识提取-skill/tools/lint-payload.py outputs/<帖>/payload.json
```
- 输出 WARN（建议看）/ ERROR（必须修）；有 ERROR 退出码 1。

## ingest-post.py —— 入库（可选）

把 payload POST 到 ingest API。**默认 dry-run**，加 `--post` 才真发。

```bash
python 创作知识提取-skill/tools/ingest-post.py outputs/<帖>/payload.json \
    --url https://<host>/api/v1/knowledge/ingest --post
```
- 端点/令牌：`--url`/`--token` 或 env `INGEST_API`/`INGEST_TOKEN`。先 lint 过再发。
