# OPS 集成接口

[English](integration-api.md) | 中文

公开入口为 `dsh-ops/integration`。仅安装 OPS 或导入模块不会为第三方预设发布工具；
预设作者须主动在自己的 composition 内挂载，或明确填写预设 id。

## 最小 Native 接入

```js
import { integration } from 'dsh-ops/integration'
export default integration({ preset: 'acme-chat' })
```

默认仅为这个 id 发布常驻 Native 文件工具和 `ops_discover_tools`；不替换官方工具、不发布
Bash；同级预设 composition 不受影响，但仍须遵守下述父子作用域边界。发现只选择能力，下一模型
步骤生效，不执行工具动作。

## 详细配置

```js
integration({
  preset: 'acme-chat',
  files: true,
  shell: true,
  presentation: 'native',
  discovery: true,
  allowedTools: ['stat', 'grep', 'read_files'],
  alwaysLoaded: ['stat'],
  replaceOfficial: false,
  promptPolicy: true,
  extraGuidance: 'Use OPS for bounded repository inspection.',
})
```

文件、常驻集合、Shell、发现、提示词、文件替换与宿主 Shell 隐藏是独立选项。`residentTools` 默认 true，关闭后取消基础常驻但保留按需选择。`residentNames` 可指定精确 Native 原始名称，默认 inspect_local_file/glob/grep/read_files/result，也可为空；PTC 使用其基础 API 与 alwaysLoaded，不接受该字段。`enabled: false` 保留显式禁用绑定，阻止同 id 的内置默认接管；诊断仍可访问。`alwaysLoaded` 必须属于 `allowedTools`；未知键、
不可用名称在挂载前报错。`shell` 仅在宿主和授权允许时发布 `ops_bash`。Bash 常驻，不能通过发现寻找。

## 完整默认值与优先级

显式字段覆盖 profile；profile 默认 `native`。四种快捷配置如下：

| profile | files | shell | presentation | discovery |
| --- | --- | --- | --- | --- |
| native | true | false | native | true |
| ptc | true | false | ptc | true |
| discovery | false | false | native | true |
| shell | false | true | native | false |

`replaceOfficial` 默认 false，`promptPolicy` true，`extraGuidance` 空，`required` false，
`denyCredentialReads` true，`allowSystemShellFallback` false。`binaryPath`/`bashPath` 默认
受管理解析，分别只作用于对应运行时。发现开启时 `allowedTools` 默认为所有可加载 API，关闭时
默认 `[]`；`alwaysLoaded` 默认 `[]`，必须属于允许列表。文件常驻的五个读取/搜索/分页工具不受
高级允许列表限制。外部数组默认均 `[]`，禁用优先，启动项必须已允许且未禁用。PTC 拒绝
Native 专属 `extraGuidance`，不静默忽略。PTC 也拒绝 `denyCredentialReads` 覆盖，其凭据边界持续生效。
`shell: false` 保留 `bashPath`、`allowSystemShellFallback` 与显式隐藏宿主 Shell 的意图；只有重新启用 Shell 时才生效。

仅文件：`{ preset, discovery: false }`；仅 Shell：`{ preset, profile: 'shell' }`；仅外部工具：
`{ preset, profile: 'discovery', allowedTools: [], externalTools: ['acme_lookup'] }`。
这些配置不改变宿主自己的展示模式或权限策略。

## 诊断与兼容

接入会额外发布 `ops_status`，见[集成诊断](集成诊断.md)。bundle 的发现行现在仅服务内置与
无预设 headless composition；未知预设必须显式接入，不再意外获得全局发现入口。旧组件导出
保留既有 legacy 语义，不要用内部 `lib/*` 作为公共 API；无预设 headless 的 Standard 回退保留。

## PTC

`profile: 'ptc'` 要求宿主真实呈现 PTC（仅 `run_code` 和非空 `tools:ptc-only` 段），不是看
预设名字或提示词是否建议使用 run_code。`files: false` 无效。`discovery: false` 撤去类型化
SDK 加载器，保留 PTC 常驻契约。目前**尚未提供第三方 PTC provider/SDK 注册协议**，不能将
Native 接入说成完整的第三方类型化 SDK。

## 生命周期与归属

绑定受挂载作用域和精确预设 id 约束；同级 composition 不受影响。应在预设 composition
作用域挂载，不要在它下面嵌套无关预设 composition：宿主会跨预设 id 继承祖先注册与限制。
无关子作用域可能看到不可用的继承 OPS 定义，祖先的替换限制也可能隐藏它继承的官方工具。
子级 `allow` 无法解除祖先 `deny`；子级自身注册的工具不受该限制。OPS 执行校验会拒绝其他
预设的继承回调，但不保证这种不受支持的嵌套方式具有 schema 隔离。
同一作用域重复绑定同一
id 会报错，须先 dispose 旧 Cordis fiber 再更换配置。卸载撤回工具、提示词、替换、待激活选择和
旧回调。执行重新核验绑定、调用者、展示及宿主当前权限；提供者仍负责自己的代码与授权。

默认保留官方文件工具，只有 `replaceOfficial: true` 才替换，而且对应 OPS 工具实际可见才隐藏。`hidePwsh` 独立控制 Windows 宿主 Shell 隐藏，默认遵循 replaceOfficial && shell；显式 false 保留宿主 Shell。worker 缺失或发布失败不能让两边同时不可用。单行配置不再提供兼容模式组件。

## 单行自定义预设

同样选项可保存到单行 `dsh-ops` 的 presets 映射；键是精确 preset id，内部省略 preset 字段。已配置项在行页显示原生 Switch 卡片。显式绑定可覆盖内置 id，不受挂载顺序影响；未列出预设不变。

```yaml
presets:
  acme-chat:
    enabled: true
    files: true
    residentNames: [read_files, stat]
    residentTools: true
    discovery: false
    shell: false
    replaceOfficial: false
    promptPolicy: true
```

bundle 总开关约束该行管理的消费者；关闭动态加载不删除显式启动选择。独立 integration() 属于其挂载插件，不依赖无关 bundle 行。见[配置参考](配置参考.md)与[内部架构](内部架构.md)。

## 外部高级工具

详见[外部 Native 提供者协议](外部工具提供者.md)。插件使用 `registerNativeCapability` 声明
元数据、参数、结果 schema/渲染及强制授权回调；预设通过 `externalTools`（默认 `[]`）明确
允许原名，使用 `externalAlwaysLoaded` 启动加载、`externalDisabled` 禁用。纯第三方 Native
发现不依赖 OPS worker、文件组件、Bash 或 subprocess。尚不支持第三方 PTC SDK 注册。