ascn-integrations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ASCN Integrations

ASCN集成

This document is normative. RFC2119 keywords (

MUST

SHOULD

MAY

) define required behavior.

本文档为规范性文档。RFC2119关键词（

MUST

、

SHOULD

、

MAY

）用于定义强制行为要求。

Mission

任务目标

Design and deliver missing capability as reusable ASCN integrations, then package them as user-visible plugins.

设计并交付缺失的功能，将其作为可复用的ASCN集成，然后打包为用户可见的插件。

When To Use

适用场景

Use this skill when a workflow task cannot be completed with existing handlers/triggers/tools.

Typical triggers:

missing handler for a required API/service
missing trigger type for required event source
schema/contract mismatch blocks reliable workflow composition
required UI ergonomics (
```
params_ui
```
, options, conditional fields) are missing

当现有处理器/触发器/工具无法完成工作流任务时，使用本技能。

典型触发场景：

缺少所需API/服务的处理器
缺少针对所需事件源的触发器类型
Schema/契约不匹配阻碍了可靠的工作流组合
缺少所需的UI人机交互设计（
```
params_ui
```
、选项、条件字段）

Required Inputs

必需输入

The integrator MUST collect:

```
workspace_id
```
(UUID)
capability gap summary (what cannot be built today)
target use-cases (at least one concrete workflow scenario)
expected input/output contract (JSON-level)
auth/secret requirements
publish target (
```
user
```
plugin first, system copy later)

workspace_id

or contract expectations are missing, stop and request them.

集成人员必须收集以下信息：

```
workspace_id
```
（UUID格式）
功能缺口总结（当前无法实现的功能）
�目标用例（至少一个具体的工作流场景）
预期的输入/输出契约（JSON层级）
认证/密钥要求
发布目标（先发布为
```
user
```
插件，后续再发布系统副本）

如果缺少

workspace_id

或契约预期信息，需停止操作并请求补充。

Required MCP Tool Surface

必需的MCP工具集

```
control.docs.get
```
```
control.registry.list
```
```
control.registry.details
```
```
control.workflows.list
```
```
control.workflows.describe
```
```
control.workflows.validate
```
```
control.workflows.create
```
```
control.workflows.patch
```
```
control.workflows.activate
```
```
control.tools.ensure_export
```
```
control.tools.list_exports
```
```
control.plugins.create_plugin
```
```
control.plugins.update_plugin
```
```
control.plugins.list
```

```
control.docs.get
```
```
control.registry.list
```
```
control.registry.details
```
```
control.workflows.list
```
```
control.workflows.describe
```
```
control.workflows.validate
```
```
control.workflows.create
```
```
control.workflows.patch
```
```
control.workflows.activate
```
```
control.tools.ensure_export
```
```
control.tools.list_exports
```
```
control.plugins.create_plugin
```
```
control.plugins.update_plugin
```
```
control.plugins.list
```

Delivery Modes

交付模式

Mode A: Workflow-backed integration (preferred first)

模式A：基于工作流的集成（优先选择）

Use existing handlers to build a reusable workflow and export it through

Trigger.Tool

使用现有处理器构建可复用的工作流，并通过

Trigger.Tool

导出。

Mode B: Native integration (new handler/trigger code)

模式B：原生集成（新的处理器/触发器代码）

Use only when Mode A cannot satisfy latency, auth, determinism, or protocol constraints.

Native integrations MUST still be wrapped/published as plugins for user consumption.

仅当模式A无法满足延迟、认证、确定性或协议约束时使用。

原生集成仍必须封装为插件发布，以供用户使用。

Deterministic Flow

确定性流程

Discover existing capability (

control.registry.list

control.registry.details

control.tools.list_exports

Produce contract draft:
- canonical handler id (
```
Vendor.Action
```
  )
- ```
params_schema
```
  (input object)
- ```
returns_schema
```
  (output object)
Choose delivery mode (
```
A
```
or
```
B
```
) with explicit reason.
Implement integration.
Validate workflow/config contract (
```
control.workflows.validate
```
).

Activate export (

control.workflows.activate

control.tools.ensure_export

Bundle handlers into plugin (
```
control.plugins.create_plugin
```
then
```
update_plugin
```
if needed).
Verify plugin visibility with
```
control.plugins.list
```
and registry views.

发现现有功能（

control.registry.list

、

control.registry.details

、

control.tools.list_exports

）。

生成契约草案：
- 标准处理器ID（
```
Vendor.Action
```
  格式）
- ```
params_schema
```
  （输入对象）
- ```
returns_schema
```
  （输出对象）
选择交付模式（
```
A
```
或
```
B
```
）并说明明确理由。
实现集成。
验证工作流/配置契约（
```
control.workflows.validate
```
）。

激活导出（

control.workflows.activate

、

control.tools.ensure_export

）。

将处理器打包为插件（先执行
```
control.plugins.create_plugin
```
，必要时执行
```
update_plugin
```
）。
通过
```
control.plugins.list
```
和注册表视图验证插件可见性。

Plugin Packaging Rules

插件打包规则

Plugin name MUST be stable and vendor/domain-scoped (e.g.
```
StripeOps
```
,
```
CRMHubspot
```
).
Handler names MUST be canonical and collision-safe.
One plugin MAY contain multiple handlers if they share domain and auth model.
Plugin definitions SHOULD include UI metadata (
```
name
```
,
```
description
```
,
```
icon
```
,
```
tags
```
) before handoff.
Unwrapped
```
Trigger.Tool
```
exports MUST still be user-visible as flat
```
User.<Handler>
```
entries.
Wrapped/published handlers MUST be rendered as first-class plugin cards/forms with plugin metadata (
```
name
```
,
```
description
```
,
```
icon
```
) and handler
```
params_ui
```
.

插件名称必须稳定，且按供应商/领域划分范围（例如
```
StripeOps
```
、
```
CRMHubspot
```
）。
处理器名称必须是标准格式且避免冲突。
如果多个处理器共享同一领域和认证模型，可包含在同一个插件中。
移交前，插件定义应包含UI元数据（
```
name
```
、
```
description
```
、
```
icon
```
、
```
tags
```
）。
未封装的
```
Trigger.Tool
```
导出仍需以扁平的
```
User.<Handler>
```
条目形式对用户可见。
已封装/发布的处理器必须以一等插件卡片/表单的形式展示，包含插件元数据（
```
name
```
、
```
description
```
、
```
icon
```
）和处理器的
```
params_ui
```
。

Params UI Best Practices

Params UI最佳实践

params_ui

MUST be human-usable and contract-aligned.

Every key in
```
params_ui
```
SHOULD exist in
```
params_schema.properties
```
.
Localize labels/hints where possible (
```
en
```
,
```
ru
```
).

Prefer explicit controls:

string

string_multiline

number

boolean

options

array

object

string_json

Use conditional visibility for complex forms via
```
displayOptions.show
```
.
Put dangerous/advanced options behind conditional toggles.
Include safe defaults where deterministic behavior is expected.
Use
```
options
```
only for selectable values; use
```
displayOptions.show
```
only for conditional visibility.
Keep field order identical to the execution mental model (auth -> target -> behavior -> advanced).

Example conditional field pattern:

json

[
  {
    "key": "auth_mode",
    "control": "options",
    "label": {"en": "Auth mode"},
    "options": [
      {"value": "api_key", "label": {"en": "API key"}},
      {"value": "oauth", "label": {"en": "OAuth"}}
    ]
  },
  {
    "key": "api_key",
    "control": "string",
    "label": {"en": "API key"},
    "displayOptions": {"show": {"auth_mode": ["api_key"]}}
  }
]

Minimal

params_ui

field contract (recommended):

json

{
  "key": "string",
  "control": "string|string_multiline|number|boolean|options|array|object|string_json",
  "label": {"en": "Field label"},
  "hint": {"en": "Optional guidance"},
  "required": false,
  "default": null,
  "options": [
    {"value": "v1", "label": {"en": "Value 1"}}
  ],
  "displayOptions": {"show": {"other_key": ["match_value"]}}
}

Rules for this contract:

```
options
```
MUST exist only when
```
control=options
```
.
```
displayOptions.show
```
MUST reference keys that exist in the same
```
params_ui
```
.
```
required=true
```
fields SHOULD be present in
```
params_schema.required
```
.
Secret-bearing fields SHOULD use hints directing users to secrets, not literal defaults.

params_ui

必须易于人类使用且与契约保持一致。

```
params_ui
```
中的每个键都应存在于
```
params_schema.properties
```
中。
尽可能本地化标签/提示信息（支持
```
en
```
、
```
ru
```
）。

优先使用明确的控件类型：

string

、

string_multiline

、

number

、

boolean

、

options

、

array

、

object

、

string_json

通过
```
displayOptions.show
```
为复杂表单设置条件可见性。
将危险/高级选项放在条件切换开关之后。
在预期确定性行为的场景中提供安全默认值。
仅对可选值使用
```
options
```
；仅对条件可见性使用
```
displayOptions.show
```
。
字段顺序应与执行逻辑的思维模型一致（认证 -> 目标 -> 行为 -> 高级选项）。

示例条件字段模式：

json

[
  {
    "key": "auth_mode",
    "control": "options",
    "label": {"en": "Auth mode"},
    "options": [
      {"value": "api_key", "label": {"en": "API key"}},
      {"value": "oauth", "label": {"en": "OAuth"}}
    ]
  },
  {
    "key": "api_key",
    "control": "string",
    "label": {"en": "API key"},
    "displayOptions": {"show": {"auth_mode": ["api_key"]}}
  }
]

推荐的最小

params_ui

字段契约：

json

{
  "key": "string",
  "control": "string|string_multiline|number|boolean|options|array|object|string_json",
  "label": {"en": "Field label"},
  "hint": {"en": "Optional guidance"},
  "required": false,
  "default": null,
  "options": [
    {"value": "v1", "label": {"en": "Value 1"}}
  ],
  "displayOptions": {"show": {"other_key": ["match_value"]}}
}

本契约规则：

仅当
```
control=options
```
时，
```
options
```
字段才必须存在。
```
displayOptions.show
```
必须引用同一
```
params_ui
```
中存在的键。
```
required=true
```
的字段应出现在
```
params_schema.required
```
中。
承载密钥的字段应使用提示信息引导用户使用密钥，而非提供字面默认值。

Security & Secrets

安全与密钥

Credentials MUST come from secrets (
```
={{ $secrets.name }}
```
), never literals.
```
params_schema
```
SHOULD mark required secret-driven fields clearly.
Integration MUST document minimum secret set for successful invocation.

凭证必须来自密钥存储（
```
={{ $secrets.name }}
```
），绝不能使用字面量。
```
params_schema
```
应清晰标记需要密钥驱动的必填字段。
集成必须记录成功调用所需的最小密钥集合。

Output Contract

输出契约

Every completion MUST include:

json

{
  "integration": {
    "mode": "workflow|native",
    "capability_status": "implemented",
    "handler_names": ["Vendor.Action"]
  },
  "plugin": {
    "plugin_name": "VendorOps",
    "created_or_updated": true
  },
  "verification": {
    "validated": true,
    "activated": true,
    "visible_in_plugins_list": true
  },
  "open_items": []
}

每个完成的任务必须包含以下内容：

json

{
  "integration": {
    "mode": "workflow|native",
    "capability_status": "implemented",
    "handler_names": ["Vendor.Action"]
  },
  "plugin": {
    "plugin_name": "VendorOps",
    "created_or_updated": true
  },
  "verification": {
    "validated": true,
    "activated": true,
    "visible_in_plugins_list": true
  },
  "open_items": []
}

Hand-off Back To ASCN Operator

移交回ASCN操作员

After integration delivery:

return canonical handler/plugin identifiers
return required secrets and minimal invocation payload
instruct caller to resume lifecycle operations with
```
ascn-operator
```

集成交付完成后：

返回标准的处理器/插件标识符
返回所需的密钥和最小调用负载
指导调用者使用
```
ascn-operator
```
恢复生命周期操作