Files
ssw-ontology/docs/USAGE.md
T
admin d938462bd6 refactor(access): 完全移除 .env 显式密钥,密钥统一由 principals 表管理
理由:管理界面已就位,DB 中由 UI 设置或 seed 随机生成的 key 才是唯一权威来源,
不再需要在部署时手动配置 MANAGER_API_KEY/CONNECTOR_API_KEY/INGEST_API_KEY,
避免环境变量泄漏/不同环境不一致/容器重启覆盖等运维隐患。

### 设计
- 移除 Config 中的 ManagerAPIKey/ConnectorAPIKey/IngestAPIKey 字段及对应环境变量读取。
- principalFromRequest 仅查 principals 表 api_key;不再有 env 优先回退。
- loginRequired/connectorAuth 改为查询 'DB 是否已有密钥' 判定是否进入真实鉴权模式;
  manager 未配置 key 的全新库仍保留开放体验,便于首次引导(密码登录)。
- 首次启动时 seedAccessControlDefaults 为 4 个内置主体(manager/connector/public/ingest)
  随机生成 API Key 并打印到 stdout(幂等,已有 key 不覆盖)。
- handlers_mcp.callConn 内部派发改用 a.builtinKey('connector') 注入 X-API-Key,
  走 DB 查到的密钥而非 env。

### 加固
- 移除固定/空 key 漏洞:seed 写入前先 UPDATE...WHERE api_key IS NULL OR api_key='',
  重复启动幂等;首次启动日志里打印 4 个随机值,运维保存后可在 Access Control 页重置。

### 验证(localhost:8081 真实库,go test 全绿)
- mgr-key-2213 经纯 DB 解析回 manager(manage+L0-L4);密码登录仍可引导。
- connector 端点:无 key 401,带 DB key 200;authHint 切到 DB key 状态文案。
- public key 解析为 public(L0 only),匿名请求也回退 public,无升权。
- mgmt 端点:无 key / public key 均 401;manager key 200。
- 全部测试 green (server + ai)。

### 文档同步
- README.md / docs/README.md / docs/USAGE.md / docs/IMPORT.md /
  skills/ssw-ontology-reviewer/SKILL.md / web/src/views/ConnectorView.vue /
  server/CHANGELOG.md 同步去掉 .env 密钥说明,改为'首次启动日志 + Access Control 页管理'。
2026-09-07 15:29:20 +08:00

160 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 使用说明 · Ontology Platform
本体把外部业务/数据/知识沉淀成可查询的"对象类型 + 实例 + 关系",通过 REST/MCP 连接器让外部应用精准调取。
下面的示例使用通用占位符(项目、产品、空间、组织...),把业务换成你自己的即可。
---
## 1. 启动
```bash
./build.sh # 构建前端 + 编译后端二进制
./run.sh # 直接运行,监听 http://localhost:8081
# 停止:Ctrl+C 结束进程即可(无后台容器需清理)
```
首次启动(`SEED_ON_START=true`)会自动灌入**极简种子**(1 个对象类型「合作企业」+ 3 条占位实例,见 `server/db.go` 的 `seedIfEmpty`),用于开箱演示。
---
## 2. 连接器 API(只读,供外部消费)
所有连接器接口前缀 `/api/v1/connector`,首次启动尚未生成 connector api_key 时无需鉴权;一旦 seed 为 connector 主体写入随机密钥,所有请求须在 `X-API-Key` 头(或 `key=` 查询参数)携带该密钥(在 Access Control 页可查看/重置)。
| 方法 | 路径 | 作用 |
|------|------|------|
| GET | `/connector/object-types` | 列出全部对象类型及属性定义(先了解有哪些实体类别) |
| GET | `/connector/objects/:type` | 列出某类型的全部实例(`?limit=`) |
| GET | `/connector/object/:type/:pk` | 取单个实例详情 |
| GET | `/connector/search?q=` | **精准检索**:按名称优先排序,支持 `type`/`field`/`limit` |
| GET | `/connector/facets` | **发现维度**:返回各类型可过滤的取值 |
| POST | `/connector/query` | **结构化过滤**:按类型+属性过滤,可 `expand` 展开关系 |
| GET | `/connector/graph` | 全量图谱(节点+边),用于可视化 |
| GET | `/api/v1/mcp/manifest` | MCP 工具清单(WorkBuddy 据此注册工具) |
| POST | `/api/v1/mcp` | MCP JSON-RPC 2.0 Streamable HTTP 端点 |
---
## 3. 精准查询配方
> 原则:**先发现 → 再精确**。不要直接模糊搜。
### 3.1 先发现有哪些可过滤值 → `get_facets`
```bash
curl 'http://localhost:8081/api/v1/connector/facets?type=Project'
# 返回 {"facets":{"region":["华北","华东",...], "status":["active","archived"], "priority":[...]}}
```
拿到真实取值后,再精确过滤,避免瞎猜字段值。
### 3.2 按名称精准查某个实体 → `search_ontology`
```bash
# 默认只匹配名称、按相关度排序
curl 'http://localhost:8081/api/v1/connector/search?q=核心项目A'
# 限定类型,更准
curl 'http://localhost:8081/api/v1/connector/search?q=数据空间&type=DataSpace'
# 全字段(名称+属性)模糊(噪杂,慎用)
curl 'http://localhost:8081/api/v1/connector/search?q=信创&field=all'
```
### 3.3 结构化过滤 → `query_related`
用 `facets` 拿到的取值做过滤,结果确定、可复现。filters 支持操作符(2026-09-05 起):
`{"字段":"值"}` 等值、`{"字段":{"ne":"值"}}` 排除、`{"字段":{"in":["a","b"]}}` / `{"nin":[...]}` 枚举、`{"字段":{"contains":"子串"}}`、`{"字段":{"exists":true}}` 非空。另支持顶层 `fields:["a","b"]` 裁剪返回字段:
```bash
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-H 'Content-Type: application/json' \
-d '{"type":"DataSpace","filters":{"region":"华东"}}'
# → 华东的所有数据空间
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-d '{"type":"DataSpace","filters":{"industry":"物流"},"expand":"SpaceUsesAppliance"}'
# → 物流数据空间 + 其部署的设备/服务
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-d '{"type":"DataSpace","filters":{"region":{"ne":"华东"}},"fields":["name","region"]}'
# → 非华东的数据空间,只返回 name/region 两个字段
```
> 软删除约定(2026-09-05):被删除的实例是「墓碑」,连接器/检索**默认排除**;管理端可用 `?include_deleted=true` 或 `?only_deleted=true` 查看。`search_ontology` 命中别名时自动跳转到 canonical 实例。
### 3.4 按角色筛选组织
```bash
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-d '{"type":"MemberOrg","filters":{"role":"合作伙伴"}}'
```
---
## 4. 接入 WorkBuddy / 其他应用(MCP)
连接器同时暴露一份 **MCP 工具清单**(`GET /api/v1/mcp/manifest`),WorkBuddy / Claude Code 可据此把本体注册成可调用的工具:
- 查询:`get_object_types` / `get_objects_by_type` / `get_object` / `search_ontology` / `get_facets` / `query_related` / `whoami`
- 知识管理:`km_list_tree` / `km_list_files` / `km_create_folder` / `km_upload_markdown` / `km_extract` / `km_delete`
- 类型管理:`create_object_type` / `create_link_type` / `update_enum`
- 实例写入:`create_object`(默认 merge,只更新传入字段)/ `batch_create_objects` / `batch_create_links` / `create_link` / `delete_object`(可 propagate 血统传播)/ `restore_object` / `get_object_history` / `find_duplicates`
写入语义要点:
- `create_object` **默认 merge**:只更新传入字段,其余保留;传 `null` 删除字段;`replace=true` 才全量替换(响应回显被清掉的字段)
- 可传 `source_ts`(业务源时间戳毫秒):比已有值更旧的写入会被拒绝(`stale_write`),旧信息不覆盖新信息
- `delete_object` 响应回显 `source_ref`(实例来源文档);`propagate=true` 时沿溯源把来源文档全部抽取产物一并清理
- 新建时响应携带 `possible_duplicates` 高度相似实体提示,建议改用已有 pk 或 `same_as` 归并
完整约定见 [INSTANCE_GOVERNANCE.md](INSTANCE_GOVERNANCE.md)。
**接入方式**:在 WorkBuddy 的 MCP 配置里指向 `http://<host>:8081/api/v1/mcp`,之后即可用自然语言问,例如:
> "项目里华东区域的数据空间有哪些?分别用了什么设备?"
WorkBuddy 会先用 `get_facets` 拿到 `region=华东`,再 `query_related` 过滤并 `expand` 关系,返回确定答案。
---
## 5. 用 AI 动态维护本体(提交资料自动更新 / 按指令更新)
管理接口前缀 `/api/v1`(需 manager 主体:密码登录后 cookie 鉴权,或 `X-API-Key` 携带 manager 的随机密钥)。AI 摄取把一段资料自动抽取成本体增量并入库。
### 5.1 提交资料,自动更新(mode=auto 直接入库)
```bash
curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
-H 'Content-Type: application/json' \
-d '{"raw_text":"合作伙伴「华东数据集团」与「物流行业数据空间」达成合作,并推出数据产品「XX」用于企业估值。","mode":"auto"}'
```
返回会列出抽取到的对象(已自动分类、生成稳定主键并写入),并打 `source='ai-ingest'` 标记。
### 5.2 按指令更新(只抽你想要的部分)
```bash
curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
-d '{"raw_text":"...同上资料...","directive":"只提取其中的数据产品","mode":"auto"}'
```
`directive` 会约束抽取范围(如「只提取数据产品」「提取所有合作伙伴并标注区域」)。
### 5.3 先审后入(mode=review)
把 `mode` 设为 `review`,接口只返回 `suggestion` 不写库,由人工确认后再调用管理接口写入。
> 若配置了 `AI_BASE_URL` + `AI_KEY` + `AI_MODEL`(OpenAI 兼容),则走真实大模型抽取;否则用内置启发式兜底(识别「」""包裹的实体 + 就近关键词分类)。
### 5.4 大模型支持
- URL 含 `/anthropic` → Anthropic Messages 协议(需 `x-api-key` 头)
- 其他 → OpenAI Chat Completions 兼容协议(DeepSeek / 通义千问 / Ollama 等均可)
---
## 6. 管理平台界面
浏览器打开 `http://localhost:8081` 即前端:概览统计、本体编辑(对象类型/属性/关系/动作/函数/接口/物化/同步源)、实例 CRUD、AI 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)、访问控制(主体/授权/标记/字段策略/审计日志)。