Bitrix24 Agent（精简 + 可靠）

使用此技能，以最少的 token 消耗实现正确、稳定的 Bitrix24 集成。

默认模式：精简（Lean）

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

• 在执行首个可操作步骤前，最多加载 2 个参考文件。
• 起始文件始终为 references/packs.md。
• 随后仅打开一个目标文件：references/catalog-.md。
• 仅当用户明确询问工作流（workflow）或链式调用（chain）时，才打开 references/chains-.md。
• 仅在涉及认证架构、调用限额、事件可靠性或未知错误时，才打开 references/bitrix24.md。

响应格式限制：

• 输出须简洁（明确目标 + 下一步动作 + 单条命令）。
• 不得复述文档内容。
• 除非用户显式要求，否则不得输出大段 JSON。
• 避免重复已提供的指导；仅返回增量信息（delta）。

路由工作流

1. 判断用户意图：

• 方法调用（method call），
• 问题排查（troubleshooting），
• 架构决策（architecture decision），
• 事件机制或可靠性配置（event/reliability setup）。

术语标准化（产品词汇表）：

• "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. 选择最小化功能包（packs）：

• 默认启用 core 包。
• 仅按需添加必要包：comms、automation、collab、content、boards、commerce、services、platform、sites、compliance、diagnostics。

4. 在约束条件下执行：

• 优先使用 scripts/bitrix24_client.py 和 scripts/offline_sync_worker.py；
• 强制启用白名单（allowlist），并要求显式传入 --confirm-write 或 --confirm-destructive 参数；
• 尽可能保证写操作具有幂等性（idempotent）。

5. 仅在触发特定条件时，升级至深度参考：

• WRONG_AUTH_TYPE、insufficient_scope、QUERY_LIMIT_EXCEEDED、expired_token；
• 对离线事件丢失存在明确担忧；
• OAuth token 刷新竞争或租户隔离（tenant isolation）问题。

质量保障约束（Quality Guardrails）

• 绝不暴露 Webhook 或 OAuth 密钥（secrets）。
• 权限范围（scope）与访问权限必须遵循最小权限原则（least-privilege）。
• 禁止嵌套 batch 调用。
• 在线事件（online events）不保证投递成功；如需零丢失处理，请使用离线事件流（offline flow）。
• 在兼容前提下优先使用 REST 3.0 API；必要时回退至 v2。

参考文档加载映射表

1. references/packs.md：了解功能包定义及加载策略。
2. references/catalog-.md：查阅该包内方法的精简清单（shortlist）。
3. references/chains-.md：查阅该包对应的具体实现链（implementation chains）。
4. references/bitrix24.md：仅在需要更深入的协议细节时查阅。

常用搜索快捷命令：

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）支持。