Metadata-Version: 2.4
Name: licos-platform-cli
Version: 0.8.12
Summary: LICOS platform CLI
Requires-Python: >=3.10
Requires-Dist: licos-platform-sdk>=0.9.11
Description-Content-Type: text/markdown

# licos-platform-cli

LICOS 平台命令行工具。`licos-platform help` 返回结构化 JSON 帮助。

## 企业知识库正文检索

只传问题的调用从 `licos-platform-cli==0.8.12` 起支持，需要 `licos-platform-sdk>=0.9.11`。

```bash
licos-platform knowledge enterprise retrieve --query "停机前需要完成哪些检查？"
licos-platform knowledge enterprise retrieve --query "停机前需要完成哪些检查？" --source-id KNOWLEDGE_BASE_UUID
```

默认只传问题，平台按当前用户权限检索，无需先查目录。`--source-id` 选填；用户或业务配置限定知识库时保留该参数，已有指定库命令保持可用。库名搜索和文件名搜索不是正文检索。

## 企业知识库原文件下载

此命令从 `licos-platform-cli==0.8.11` 起提供，需要 `licos-platform-sdk>=0.9.10`。

```bash
licos-platform help knowledge enterprise-document-download
licos-platform knowledge enterprise document-download DOCUMENT_ID --out "attachments/会议纪要.docx"
licos-platform knowledge enterprise document-download LEGACY_DOCUMENT_ID --api-version legacy --out "attachments/旧版原文件.docx"
```

命令复用 Platform SDK 的 `enterprise_knowledge.download_document`，默认使用新版文档 ID，旧接口 ID 显式指定 `--api-version legacy`。只传真实文档 ID 和保存路径，程序内部取得并直接使用原始签名链接，输出 `document_id/path/size_bytes/sha256`，不输出票据。

`--out` 相对路径按当前进程工作目录解析，沿用业务进程和沙箱写入权限，不改变已有任务目录。自动创建父目录，已有文件、目录或链接均不覆盖，下载失败不留下半份文件。`--timeout` 是每次网络操作超时，默认 120 秒；`--max-bytes` 默认 1073741824（1 GiB）。下载请求不携带平台凭据，不跟随重定向，使用已鉴权知识库接口返回的合法 HTTP/HTTPS 地址，无需额外配置可信主机。

身份规则与其他企业知识库命令相同。网页项目替用户执行时加 `--token-stdin`，将本次请求用户 Token 写入子进程标准输入；不通过命令行参数或共享环境变量传 Token。权限、下载、覆盖冲突和本地文件错误均返回非零退出码。原 `document-url`、`document-download-link` 命令继续可用。

## 企业项目（0.8.1 起）

```bash
licos-platform help enterprise-projects
licos-platform enterprise-projects list --all
licos-platform enterprise-projects search --query 发票 --type AGENT --type AICODING_AGENT --all
licos-platform enterprise-projects show RECORD_ID
licos-platform enterprise-projects capability --tenant-id TENANT --workspace-id WORKSPACE --resource-type AICODING_WORKFLOW --resource-id RESOURCE
```

查询包含当前用户可见的在线低代码智能体、AI 编程智能体和 AI 编程工作流；`invocation` 保留关闭调用、未就绪等原因。`--all` 完整读取匹配页；默认一页，可用 `--page`、`--page-size`。精确发布契约使用 `capability --record-id RECORD_ID`，与稳定资源选择互斥。

命令只做发现，业务代码查项目实际安装的 SDK 文档后接入。帮助中的 `sdk` 字段提供文档入口；命令身份遵循下文“当前使用者”规则。

## 当前使用者（0.5.1 起）

```bash
licos-platform user me
licos-platform user me --workspace-id <执行工作空间ID>
licos-platform help user me
```

用户接口默认使用 `LICOS_CURRENT_USER_ID` 指定的当前命令用户换取 Token。编程助手执行命令时，由平台根据本次请求注入该标识；独立终端沿用其启动身份，不会自动跟随网页登录者变化。平台地址、服务凭证和项目工作空间沿用运行时配置。
运行时使用 `AGENT_CURRENT_USER_ID` 注入当前用户时同样支持，不以项目负责人替代当前执行用户。企业和空间上下文沿用平台签发的认证结果。
多用户请求可将当前使用者 Token 通过标准输入传入，不将 Token 放在命令行参数中：

```bash
licos-platform user me --token-stdin
```

输入不含 `Bearer ` 前缀的 Token 并结束标准输入。程序调用时可通过子进程的 `input` 参数传入。

输出为与低代码 `sys_user` 相同的 JSON：用户 ID、账号、姓名、头像、执行企业、
主部门、全部所属部门、组织任职、主岗位和主职务。部门含名称路径、ID 路径；
无部门/任职时保持 `[]`/`null`。缺少当前使用者身份或 Token 失效时返回非零退出码，
不改用项目所有者。Token 和内部服务凭证不回显。


## 身份选择（0.6.0 起）

`LICOS_CURRENT_USER_ID` 表示当前命令的执行用户：编程助手按本次请求注入，独立终端沿用其启动身份。项目身份指运行时配置的项目所有者身份。不同命令的默认身份如下：

| 命令 | 默认身份 | 网页登录用户执行 |
| --- | --- | --- |
| `user me` | 按 `LICOS_CURRENT_USER_ID` 换 Token | 使用 `--token-stdin` |
| `knowledge enterprise …` | 按 `LICOS_CURRENT_USER_ID` 换 Token | 使用 `--token-stdin`，企业范围和权限由平台认证结果确定 |
| 所有 `ontology` 命令 | 按 `LICOS_CURRENT_USER_ID` 换 Token | 使用 `--token-stdin` |
| 普通 `knowledge …` | 项目身份 | 需要用户权限时使用 `--token-stdin` |
| 数据库、对象存储、OAuth 应用管理 | 项目身份 | 保持项目身份 |

用户操作未传 `--token-stdin` 时，用 `LICOS_CURRENT_USER_ID` 和运行时服务凭证换 Token；缺少执行用户配置则报错。`--token-stdin` 优先使用标准输入的 Token，空输入直接报错，不再换取其他身份。

HTTP 服务调用用户接口时，必须从本次认证会话取得 Token，并写入该子进程的标准输入；缺少 Token 时在业务入口返回登录错误。不能依赖容器默认用户，也不能把请求 Token 或用户 ID 写入共享环境变量。例如在 Python 服务中：

```python
import subprocess

# token 来自本次请求的认证会话，不含 "Bearer " 前缀。
result = subprocess.run(
    ["licos-platform", "user", "me", "--token-stdin"],
    input=token,
    text=True,
    capture_output=True,
    check=True,
)
```

显式传入的 Token 鉴权失败时返回非零退出码，由调用方更新登录凭证，不切换到容器用户或项目所有者。项目所有者和工作空间等资源归属字段单独保留，不用它们冒充调用用户。

## 本体正式版本

0.8.0 起，`ontology package/bind --root-object-id <id>` 自动选择最新正式版；使用显式 release_id 固定版本。`ontology resolve --configuration-file ontology.json` 解析 `{versionPolicy, rootObjectId, binding}`，省略策略保持固定版本。新运行开始解析并保存输出绑定，query/function 及恢复执行复用它，不在每次查询时重新解析。新版缺少已选对象、属性或函数时直接失败。

## 编程项目登录身份

- 有内置登录时使用内置登录会话；没有内置登录时使用当前 LICOS 网页登录。内置登录未登录或过期时不能切换成平台用户。
- Node 服务端使用 `createProjectAuth({ mode: 'builtin', resolveBuiltinToken })` 或 `createProjectAuth({ mode: 'platform' })`，每次请求调用 `await projectAuth.userToken(request)`。内置解析器必须读取已有认证会话并返回用户已授权的 LICOS 凭证。
- 无内置登录的浏览器用户接口使用 `@kmlckj/licos-platform-sdk/browser` 的 `createProjectUserFetch`：平台登录桥领取一次性票据，项目后端兑换 Token。不要直接读取跨域平台 localStorage，不在 URL 中传 Token，不修改全局 fetch。项目级 API 保持原有请求方法。
- Python 使用 `ProjectAuth`；Agent/Workflow 通过 `config/licos-auth.json` 配置模式，内置登录设置 `resolver: "模块:函数"`，业务代码使用 `ctx.identity.user_token`。
- 当前用户、企业知识库、本体用户操作显式传 `userToken`/`user_token`。模型、积分和普通知识库按业务选择用户或项目身份。数据库、对象存储和可观测性继续使用项目身份。
- 沿用现有 OAuth 授权范围与接口权限。凭证无权访问目标接口时返回现有鉴权错误，不扩大权限或换用其他身份。
- 修改已有项目时先接它的现有登录机制，不能用新模板的默认平台模式覆盖。真实 Token 只存在于运行时请求/会话，不写入源代码、共享环境变量或 Agent 提示词。
