facilioo-agent-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

facilioo-agent-cli

When to use

适用场景

Use this skill when a task requires real work inside Facilioo and the preferred surface is a terminal workflow rather than the web UI.

Use it especially when an agent must:

authenticate against Facilioo from the terminal,
build context around a property, entrance, unit, or contact,
inspect inquiries, processes, work orders, appointments, user tasks, notices, or notifications,
download or upload documents,
work through a conference agenda or protocol,
perform guarded updates without improvising raw HTTP calls.

当任务需要在Facilioo内部进行实际操作，且首选终端工作流而非Web UI时使用此skill。

尤其适用于Agent需要执行以下操作的场景：

从终端对Facilioo进行身份验证,
构建物业、入口、单元或联系人相关的上下文,
查看咨询、流程、工单、预约、用户任务、公告或通知,
下载或上传文档,
处理会议议程或协议,
无需临时编写原生HTTP调用即可执行防护式更新。

Preconditions

前置条件

Treat
```
facilioo-agent-cli
```
as the product surface.

First verify that it exists on

PATH

```
facilioo-agent-cli --help
```
```
facilioo-agent-skill --help
```

If it is missing, install it through the public package:

npm install -g @codecell-germany/facilioo-agent-skill

```
facilioo-agent-skill install --force
```

Do not bypass the public CLI by probing repo-local
```
dist/
```
, hidden Codex tool folders, or old local shims.
Do not start with ad-hoc Swagger calls when the CLI already exposes the workflow.

将
```
facilioo-agent-cli
```
视为产品入口。

首先验证其是否存在于

PATH

中：

```
facilioo-agent-cli --help
```
```
facilioo-agent-skill --help
```

如果缺失，请通过公共包安装：

npm install -g @codecell-germany/facilioo-agent-skill

```
facilioo-agent-skill install --force
```

不要通过探测仓库本地
```
dist/
```
、隐藏的Codex工具文件夹或旧的本地垫片来绕过公共CLI。
当CLI已经提供对应工作流时，不要临时调用Swagger接口。

First-run detection

首次运行检测

Run this before any actual Facilioo work:

bash

facilioo-agent-cli auth status --json
facilioo-agent-cli doctor --profile auth --json

Treat the environment as not ready if any of these are true:

the CLI is missing
no persisted session exists
the configured auth method is API-key login but no API key is available
```
doctor
```
fails
the user says this is the first setup

If setup is incomplete, switch into onboarding mode immediately. Do not start with

context

ops

documents

, or

conferences

在执行任何实际的Facilioo操作前运行以下命令：

bash

facilioo-agent-cli auth status --json
facilioo-agent-cli doctor --profile auth --json

如果出现以下任意情况，视为环境未就绪：

CLI缺失
不存在持久化会话
配置的身份验证方式为API-key登录，但无可用的API key
```
doctor
```
命令执行失败
用户表示这是首次设置

如果设置未完成，请立即切换到引导模式。不要先执行

context

、

ops

、

documents

或

conferences

Onboarding mode

引导模式

This is the exact first-run order for a new or partially configured user:

Tell the user setup is not complete yet.
Print the built-in setup guide in the user's preferred language:
- English:
```
facilioo-agent-cli setup --language en
```
- German:
```
facilioo-agent-cli setup --language de
```

Collect only the static values first:

```
FACILIOO_BASE_URL
```
```
FACILIOO_API_VERSION
```
```
FACILIOO_AUTH_METHOD
```

Default to the local password flow when a human is present at the terminal:
- ```
facilioo-agent-cli auth login --method password --interactive --persist
```
Use API-key login only if the user explicitly wants a technical or automation-oriented setup:
- ```
FACILIOO_API_KEY
```
- ```
facilioo-agent-cli auth login --method api-key --persist
```
Never ask for:
- access tokens
- refresh tokens
- raw browser cookies

After login, rerun:

```
facilioo-agent-cli auth status --json
```

facilioo-agent-cli doctor --profile core-read --json

Only then continue to business commands.

这是面向新用户或部分配置用户的准确首次运行顺序：

告知用户设置尚未完成。

以用户偏好的语言打印内置设置指南：

英文:
```
facilioo-agent-cli setup --language en
```
德文:
```
facilioo-agent-cli setup --language de
```

首先仅收集静态配置值：

```
FACILIOO_BASE_URL
```
```
FACILIOO_API_VERSION
```
```
FACILIOO_AUTH_METHOD
```

当终端前有真人操作时，默认使用本地密码流：

facilioo-agent-cli auth login --method password --interactive --persist

仅当用户明确需要技术或面向自动化的设置时，才使用API-key登录：
- ```
FACILIOO_API_KEY
```
- ```
facilioo-agent-cli auth login --method api-key --persist
```
永远不要索要：
- 访问令牌
- 刷新令牌
- 原生浏览器Cookie

登录后，重新运行：

```
facilioo-agent-cli auth status --json
```

facilioo-agent-cli doctor --profile core-read --json

仅在此之后再继续执行业务命令。

Core workflow

核心工作流

Validate setup:

```
facilioo-agent-cli auth status --json
```

facilioo-agent-cli doctor --profile core-read --json

Build context:

facilioo-agent-cli context lookup --search "Musterstraße 12" --json

facilioo-agent-cli context property --id 123 --include entrances,units,tenant,documents,ops --json

facilioo-agent-cli context unit --id 456 --include documents,ops --json

Work operational queues:

facilioo-agent-cli ops inbox --property-id 123 --json

facilioo-agent-cli ops processes search --property-id 123 --open-only --json

facilioo-agent-cli ops tasks mine --json

facilioo-agent-cli ops notifications mine --json

Work documents:

facilioo-agent-cli documents search --property-id 123 --search "Versicherung" --json

facilioo-agent-cli documents download --id 5001 --output /absolute/path/file.pdf --json

Work conferences:

facilioo-agent-cli conferences search --property-id 123 --json

facilioo-agent-cli conferences protocol --id 7001 --json

验证设置：

```
facilioo-agent-cli auth status --json
```

facilioo-agent-cli doctor --profile core-read --json

构建上下文：

facilioo-agent-cli context lookup --search "Musterstraße 12" --json

facilioo-agent-cli context property --id 123 --include entrances,units,tenant,documents,ops --json

facilioo-agent-cli context unit --id 456 --include documents,ops --json

处理操作队列：

facilioo-agent-cli ops inbox --property-id 123 --json

facilioo-agent-cli ops processes search --property-id 123 --open-only --json

facilioo-agent-cli ops tasks mine --json

facilioo-agent-cli ops notifications mine --json

处理文档：

facilioo-agent-cli documents search --property-id 123 --search "Versicherung" --json

facilioo-agent-cli documents download --id 5001 --output /absolute/path/file.pdf --json

处理会议：

facilioo-agent-cli conferences search --property-id 123 --json

facilioo-agent-cli conferences protocol --id 7001 --json

Guardrails

防护规则

Read operations are safe by default.
Writes require:
- ```
--execute --confirm-write yes
```

Every exposed delete requires:

--execute --allow-delete --confirm-delete yes

Use
```
--preview
```
before sensitive changes or deletes.
Password login is interactive only and should be completed locally by a human in a real TTY.
```
auth export
```
is opt-in and should be used only when another process explicitly needs env exports.
Do not paste tokens into prompts, tickets, chats, or screenshots.
Do not treat raw API paths as the normal route when a high-level command exists.

读操作默认是安全的。
写操作需要携带参数：
- ```
--execute --confirm-write yes
```
所有对外暴露的删除操作需要携带参数：
- ```
--execute --allow-delete --confirm-delete yes
```
在执行敏感变更或删除前使用
```
--preview
```
参数。
密码登录仅支持交互式，应由真人在真实TTY环境中本地完成。
```
auth export
```
是可选功能，仅当另一个进程明确需要环境变量导出时使用。
不要将令牌粘贴到提示框、工单、聊天或截图中。
当存在高层命令时，不要将原生API路径作为常规调用方式。

Delete rule

删除规则

The delete rule is global in this skill, not process-specific only.

Examples:

bash

facilioo-agent-cli ops processes delete --id 987 --preview --json
facilioo-agent-cli ops processes delete --id 987 --execute --allow-delete --confirm-delete yes --json

facilioo-agent-cli documents delete --id 5001 --preview --json
facilioo-agent-cli documents delete --id 5001 --execute --allow-delete --confirm-delete yes --json

If the user has not explicitly approved a delete, do not run it.

删除规则在此skill中是全局生效的，并非仅针对特定流程。

示例：

bash

facilioo-agent-cli ops processes delete --id 987 --preview --json
facilioo-agent-cli ops processes delete --id 987 --execute --allow-delete --confirm-delete yes --json

facilioo-agent-cli documents delete --id 5001 --preview --json
facilioo-agent-cli documents delete --id 5001 --execute --allow-delete --confirm-delete yes --json

如果用户未明确批准删除操作，不要执行。

References

参考文档

Agent onboarding runbook:
```
references/agent-onboarding.md
```
Main overview:
```
references/overview.md
```
Command cheat sheet:
```
references/command-cheatsheet.md
```
First-run setup:
```
references/facilioo-first-run.md
```

Agent引导操作手册:
```
references/agent-onboarding.md
```
总览文档:
```
references/overview.md
```
命令速查表:
```
references/command-cheatsheet.md
```
首次运行设置指南:
```
references/facilioo-first-run.md
```