Metadata-Version: 2.5
Name: licos-platform-sdk
Version: 0.7.1
Summary: LICOS platform SDK package shell
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: rfc3339-validator<1,>=0.1.4
Requires-Dist: websockets<16,>=15.0.1
Description-Content-Type: text/markdown

# licos-platform-sdk

LICOS 项目服务端 SDK，提供项目数据库、对象存储、企业知识库、本体和 OAuth 等平台能力。

## 当前使用者信息（0.6.1 起）

```python
from licos_platform_sdk import get_current_user

# token 是当前请求的用户 Bearer Token，不包含 "Bearer " 前缀。
sys_user = get_current_user(user_token=token)
print(sys_user["displayName"])
print(sys_user["departments"])
print(sys_user["primaryPosition"])
```

返回对象与低代码系统变量 `sys_user` 相同，保留平台的 camelCase 字段名：
`id`、`username`、`displayName`、`avatarUrl`、`tenantId`、`tenantName`、
`primaryDepartment`、`departments`、`organizationAssignments`、`primaryPosition`、`primaryJobTitle`。
部门包含 ID、名称、组织路径、ID 路径及主部门标志；组织任职包含岗位、职务和部门负责人标志。

SDK 自动读取 `LICOS_PLATFORM_API_BASE_URL`、`LICOS_AI_AGENT_TOKEN` 和项目工作空间。
`workspace_id` 可由服务端指定执行工作空间；默认依次读取 `LICOS_WORKSPACE_ID`、
`LICOS_OWNER_WORKSPACE_ID`、`AGENT_WORKSPACE_ID`。企业按执行工作空间确定，与低代码一致。
无企业时企业字段为 `None`；未加入执行企业的使用者，部门和任职为空，不能返回项目所有者的信息。

多用户服务每次传入当前请求的 Token。智能体/工作流可传 `ctx.identity.user_token`；
在异步节点中使用 `await asyncio.to_thread(get_current_user, user_token=token)`。
结果不做全局缓存。Token 无效时直接报错，由调用方处理登录失效。

从 0.7.0 起必须显式传入 `user_token`。`LICOS_CURRENT_USER_ID` 只是容器初始化用户，不能代表网页登录者。
本接口仅供服务端使用；`LICOS_AI_AGENT_TOKEN` 不得发送到浏览器。


## 身份选择（0.7.0 起）

`LICOS_CURRENT_USER_ID` 表示容器启动时配置的执行用户。SDK 不用它推断当前网页登录者，也不从进程级 `LICOS_USER_TOKEN` 取得本次请求凭证。项目身份指运行时配置的项目所有者身份，按接口选择：

| 接口 | 调用身份 |
| --- | --- |
| `get_current_user` | 必须显式传入本次用户的 `user_token` |
| `enterprise_knowledge` 全部接口 | 必须传 `user_token`，企业范围和权限由平台认证结果确定 |
| 本体 `search_tools`、`resolve_tool`、`invoke_tool`、`subscribe_realtime` | 必须传执行用户的 `user_token`；网页登录请求使用本次登录会话的 Token |
| 普通 `knowledge` 接口 | 默认项目身份；需要用户权限时显式传 `user_token` |
| 数据库、对象存储、`oauth` 应用管理 | 项目身份 |
| `oauth_runtime` 授权码交换、刷新、userinfo、撤销 | 按 OAuth 协议传对应凭证，不使用容器用户替代 |

`user_token` 不含 `Bearer ` 前缀。用户标识、名称和企业信息以平台认证结果为准；项目所有者、工作空间等资源归属字段单独保留。

```python
from licos_platform_sdk import enterprise_knowledge, get_current_user, knowledge, ontology

# token 来自本次请求的认证会话。
user = get_current_user(user_token=token)
resources = enterprise_knowledge.tree(user_token=token)
catalog = ontology.search_tools('设备状态', user_token=token)
result = knowledge.search('资料', user_token=token)
```

网页登录请求缺少 Token 时，业务入口应返回登录错误，不能改用容器用户或项目所有者。每次调用显式传入 Token，不把请求 Token 或用户 ID 写入 `os.environ`，也不跨用户共享请求身份。

显式传入的 Token 失效时直接返回鉴权错误，由调用方更新登录凭证。实时订阅遇到网络中断会携带原 Token 重新检查授权并订阅，401/403 终止；取得新 Token 后重新创建订阅。后台常驻的项目订阅由调用方显式传项目所有者 Token。

独立 `licos-platform` CLI 的用户操作才默认按 `LICOS_CURRENT_USER_ID` 和运行时服务凭证换 Token。HTTP 服务通过 CLI 调用用户接口时使用 `--token-stdin`，不依赖容器默认用户。升级到 0.7.0 时，已有企业知识库和本体调用必须补上 `user_token` 参数。
