bitrix24-agent

设计、实施、调试和强化 AI 代理与 Bitrix24 REST API（Webhooks、OAuth 2.0、范围、事件、批处理、限制和 REST 3.0）之间的集成。当要求将 AI 助手/代理连接到 Bitrix24、自动化 CRM/任务/聊天、处理 Bitrix24 事件、选择身份验证模型或解决 Bitrix24 API 错误和性能问题时使用。

# Bitrix24 Agent (Lean + Reliable)

Use this skill to deliver correct Bitrix24 integrations with minimal token usage.

## Default Mode: Lean

Apply these limits unless the user asks for deep detail:

- Load at most 2 reference files before first actionable step.
- Start from `references/packs.md`.
- Then open only one target file: `references/catalog-<pack>.md`.
- Open `references/chains-<pack>.md` only if user asks for workflow/chain.
- Open `references/bitrix24.md` only for auth architecture, limits, events reliability, or unknown errors.

Response format limits:

- Use concise output (goal + next action + one command).
- Do not retell documentation.
- Do not dump large JSON unless explicitly requested.
- Avoid repeating already provided guidance; return only delta.

## Routing Workflow

1. Determine intent:
- method call,
- troubleshooting,
- architecture decision,
- event/reliability setup.

Term normalization (product vocabulary):

- "collabs", "workgroups", "projects", "social network groups" -> `collab` (and `boards` for scrum).
- "Copilot", "CoPilot", "BitrixGPT", "AI prompts" -> `platform` (`ai.*`).
- "open lines", "contact center connectors", "line connectors" -> `comms` (`imopenlines.*`, `imconnector.*`).
- "feed", "live feed", "news feed" -> `collab` (`log.*`).
- "sites", "landing pages", "landing" -> `sites` (`landing.*`).
- "booking", "calendar", "work time", "time tracking" -> `services` (`booking.*`, `calendar.*`, `timeman.*`).
- "orders", "payments", "catalog", "products" -> `commerce` (`sale.*`, `catalog.*`).
- "consents", "consent", "e-signature", "sign" -> `compliance` (`userconsent.*`, `sign.*`).

2. Choose auth quickly:
- one portal/internal: incoming webhook.
- app/multi-portal/lifecycle features: OAuth.

3. Select minimal packs:
- default `core`.
- add only required packs: `comms`, `automation`, `collab`, `content`, `boards`, `commerce`, `services`, `platform`, `sites`, `compliance`, `diagnostics`.

4. Execute with guardrails:
- prefer `scripts/bitrix24_client.py` and `scripts/offline_sync_worker.py`,
- enforce allowlist + `--confirm-write` / `--confirm-destructive`,
- keep writes idempotent when possible.

5. Escalate to deep reference only on trigger:
- `WRONG_AUTH_TYPE`, `insufficient_scope`, `QUERY_LIMIT_EXCEEDED`, `expired_token`,
- offline event loss concerns,
- OAuth refresh race or tenant isolation issues.

## Quality Guardrails

- Never expose webhook/OAuth secrets.
- Scope and permissions must be least-privilege.
- No nested `batch`.
- Online events are not guaranteed delivery; use offline flow for no-loss processing.
- Prefer REST 3.0 where compatible; fallback to v2 where needed.

## Reference Loading Map

1. `references/packs.md` for pack and loading strategy.
2. `references/catalog-<pack>.md` for method shortlist.
3. `references/chains-<pack>.md` for implementation chains.
4. `references/bitrix24.md` only when deeper protocol detail is required.

Useful search shortcuts:

```bash
rg -n "^# Catalog|^# Chains" references/catalog-*.md references/chains-*.md
rg -n "WRONG_AUTH_TYPE|insufficient_scope|QUERY_LIMIT_EXCEEDED|expired_token" references/bitrix24.md
rg -n "offline|event\\.bind|event\\.offline|application_token" references/bitrix24.md
```

## Scripts

- `scripts/bitrix24_client.py`: method calls, packs, allowlist, confirmations, audit.
- `scripts/offline_sync_worker.py`: offline queue processing with retries and DLQ.

---

## 中文说明

# Bitrix24 Agent（精简 + 可靠）

使用本技能以最少的 token 消耗交付正确的 Bitrix24 集成。

## 默认模式：精简

除非用户要求深入细节，否则应用以下限制：

- 在执行首个可操作步骤前，最多加载 2 个参考文件。
- 从 `references/packs.md` 开始。
- 然后只打开一个目标文件：`references/catalog-<pack>.md`。
- 仅当用户询问工作流/链路时才打开 `references/chains-<pack>.md`。
- 仅在涉及身份验证架构、限制、事件可靠性或未知错误时才打开 `references/bitrix24.md`。

响应格式限制：

- 使用简洁输出（目标 + 下一步操作 + 一条命令）。
- 不要复述文档。
- 除非明确请求，否则不要输出大量 JSON。
- 避免重复已提供的指导；只返回增量部分。

## 路由工作流

1. 确定意图：
- 方法调用，
- 故障排查，
- 架构决策，
- 事件/可靠性设置。

术语规范化（产品词汇）：

- "collabs"、"workgroups"、"projects"、"social network groups" -> `collab`（scrum 则为 `boards`）。
- "Copilot"、"CoPilot"、"BitrixGPT"、"AI prompts" -> `platform`（`ai.*`）。
- "open lines"、"contact center connectors"、"line connectors" -> `comms`（`imopenlines.*`、`imconnector.*`）。
- "feed"、"live feed"、"news feed" -> `collab`（`log.*`）。
- "sites"、"landing pages"、"landing" -> `sites`（`landing.*`）。
- "booking"、"calendar"、"work time"、"time tracking" -> `services`（`booking.*`、`calendar.*`、`timeman.*`）。
- "orders"、"payments"、"catalog"、"products" -> `commerce`（`sale.*`、`catalog.*`）。
- "consents"、"consent"、"e-signature"、"sign" -> `compliance`（`userconsent.*`、`sign.*`）。

2. 快速选择身份验证方式：
- 单门户/内部：使用传入 webhook。
- 应用/多门户/生命周期功能：使用 OAuth。

3. 选择最小的功能包集合：
- 默认 `core`。
- 仅添加所需的包：`comms`、`automation`、`collab`、`content`、`boards`、`commerce`、`services`、`platform`、`sites`、`compliance`、`diagnostics`。

4. 带护栏执行：
- 优先使用 `scripts/bitrix24_client.py` 和 `scripts/offline_sync_worker.py`，
- 强制执行白名单 + `--confirm-write` / `--confirm-destructive`，
- 尽可能保持写操作幂等。

5. 仅在触发条件下才升级到深度参考：
- `WRONG_AUTH_TYPE`、`insufficient_scope`、`QUERY_LIMIT_EXCEEDED`、`expired_token`，
- 离线事件丢失问题，
- OAuth 刷新竞态或租户隔离问题。

## 质量护栏

- 切勿暴露 webhook/OAuth 密钥。
- 范围和权限必须遵循最小权限原则。
- 不允许嵌套 `batch`。
- 在线事件不保证投递；使用离线流程实现无丢失处理。
- 在兼容情况下优先使用 REST 3.0；必要时回退到 v2。

## 参考文件加载映射

1. `references/packs.md` 用于功能包和加载策略。
2. `references/catalog-<pack>.md` 用于方法精选列表。
3. `references/chains-<pack>.md` 用于实现链路。
4. `references/bitrix24.md` 仅在需要更深入的协议细节时使用。

实用搜索快捷方式：

```bash
rg -n "^# Catalog|^# Chains" references/catalog-*.md references/chains-*.md
rg -n "WRONG_AUTH_TYPE|insufficient_scope|QUERY_LIMIT_EXCEEDED|expired_token" references/bitrix24.md
rg -n "offline|event\\.bind|event\\.offline|application_token" references/bitrix24.md
```

## 脚本

- `scripts/bitrix24_client.py`：方法调用、功能包、白名单、确认、审计。
- `scripts/offline_sync_worker.py`：带重试和 DLQ 的离线队列处理。