# 解析器解耦重构说明

## 当前目录归属（13 → 10）

本轮仅调整源码目录归属：`src` 一级目录从 13 个收敛为下列 10 个，其他职责分工保持不变。Plugin parser / Source parser 模型版本仍为 `5.0.0`，各内置协议实现版本仍为 `1.1.0`；解析语义、运行逻辑、执行 profile 和用户 profile 均不因本次搬迁改变。

```text
src/
├── composition/        # 具体协议的显式装配与应用默认入口
├── manager/            # 管理器、加载器、仓库与完整更新事务
│   └── plugin-loader.ts
├── parser/             # 统一契约、注册、引擎、归一化与来源编排
│   ├── contracts.ts
│   ├── registry.ts
│   ├── engine.ts
│   ├── plugin.ts
│   ├── catalog.ts
│   ├── model.ts
│   ├── version.ts
│   └── index.ts
├── protocols/          # 每种协议完整拥有自身格式规则
│   ├── claude-code/
│   ├── codex/
│   └── agent-plugins/
├── runtime/            # 中立执行模型与 DSH 运行接入
│   └── adapters/
│       ├── index.ts
│       ├── hooks.ts
│       ├── mcp.ts
│       └── skills.ts
├── shared/             # 文件系统、YAML、模板语法等中立机制
├── source/             # 来源获取、快照与安全检查
├── store/              # 存储布局、元数据、锁与事务基础
├── types/              # 统一模型及纯描述类型
│   ├── catalog.ts
│   └── protocol.ts
└── web/
    ├── host/
    │   └── gateway.ts
    └── client/         # 浏览器入口、设置页、样式、locale 与类型声明
```

确定的迁移映射如下；旧路径只作为迁移记录，不再提供导入入口：

| 原路径 | 当前归属 |
|---|---|
| `src/core/plugin-loader.ts` | [manager/plugin-loader.ts](<../src/manager/plugin-loader.ts>) |
| `src/adapters/index.ts` | [runtime/adapters/index.ts](<../src/runtime/adapters/index.ts>) |
| `src/adapters/hooks/register.ts` | [runtime/adapters/hooks.ts](<../src/runtime/adapters/hooks.ts>) |
| `src/adapters/mcp/client.ts` | [runtime/adapters/mcp.ts](<../src/runtime/adapters/mcp.ts>) |
| `src/adapters/skills/provider.ts` | [runtime/adapters/skills.ts](<../src/runtime/adapters/skills.ts>) |
| `src/web/gateway.ts` | [web/host/gateway.ts](<../src/web/host/gateway.ts>) |
| `src/client/` 下全部文件 | [web/client/](<../src/web/client/>)，保持文件名与内部层级 |
| `src/protocols/shared/types.ts` | [types/protocol.ts](<../src/types/protocol.ts>) |

旧 `src/core/`、`src/adapters/`、`src/client/` 和 `src/protocols/shared/` 目录全部删除，不保留 re-export、转发文件或兼容门面。

## 解析器解耦状态

三种协议实现完全归属 `src/protocols/claude-code/`、`codex/`、`agent-plugins/`。公共解析层没有协议专属文件、转发函数或按格式查询旧 API 的机制。上轮保留的兼容门面已删除；本轮不兼容旧 API、旧调用参数或旧运行 IR。

Plugin/Source 缓存版本为 `5.0.0`。协议实现版本与上游标准版本分别记录；改变内部接口不表示改变所支持的上游插件格式。用户已安装数据不因源码重构被删除。

## 前阶段解析器解耦

此前的解析器解耦清除了按协议名称分发的旧入口、默认引擎 Manager 门面、旧环境模式、厂商变量别名和运行 IR alias：

- 删除旧的协议专属目录 `parser/{harness,source,hooks,mcp,skills,commands,agents,agent-plugins,shared}/`。
- 删除 `composition/api.ts`、`getProtocolApi`、解析器 `api` 注册表，以及 `parser/detect.ts` / `normalize.ts` 转发入口。
- 删除 `runtime/loader.ts`、`runtime/agent-plugins.ts` 兼容门面；Manager 只保留一份显式注入实现。
- 删除 `environmentMode`、`matcherMode`、旧 expansion alias、`codexModel` 参数及对应运行层回退，使用明确的中立执行模型。
- 所有测试直接导入相应协议模块或中立工具，不通过旧入口验证新实现。

## 职责与依赖

当前目录树见本文首节。公共 parser 仍保留八个中立文件；[builtins.ts](<../src/composition/builtins.ts>) 是唯一具体模块装配点，[signatures.ts](<../src/composition/signatures.ts>) 保存格式边界的声明性数据，[defaults.ts](<../src/composition/defaults.ts>) 提供应用默认装配与便捷调用。统一来源结果归 [catalog.ts](<../src/types/catalog.ts>)，协议间共享的纯描述类型归 [protocol.ts](<../src/types/protocol.ts>)，不包含具体协议实现。

[plugin-loader.ts](<../src/manager/plugin-loader.ts>) 归管理层；Skill/MCP/Hook 的运行接入归 [runtime/adapters/](<../src/runtime/adapters/>)；Web 端按 [host/](<../src/web/host/>) 和 [client/](<../src/web/client/>) 分工。

依赖方向：协议模块 → 契约/统一类型/中立工具；管理器 → 引擎端口；运行适配 → 统一执行模型；装配入口 → 显式启用的模块。协议模块不互相导入，公共解析器、共享叶子、管理和运行实现均不回头导入装配或具体协议。

模板语法本身可以共享，但路径变量名称和别名由每个协议自己的模板模块提供。共享层不包含 CC/Codex 环境变量清单。MCP 和 Hook 运行层只消费 `environmentBindings`、执行约束、matcher 语法及事件超时等明确数据；来源名称仅作元数据。

## 新 API

中立引擎从包子路径 `@rvaim/dsh-plugin-bridge/parser` 导入，各协议从对应的 `@rvaim/dsh-plugin-bridge/protocols/claude-code`、`/codex` 或 `/agent-plugins` 导入。具体辅助解析函数只在所属模块中存在，不从公共解析出口转发。包身份更名未重写内部 `Compat*` 类型及 `parseCompat*` 函数，也不提供旧包名或旧 namespace 的兼容别名；详见[包更名说明](<包更名说明.md>)。

应用装配提供 `createBuiltinParserEngine(ids?)`，统一便捷解析入口 `parseCompatPlugin` / `parseCompatSource` 位于 [defaults.ts](<../src/composition/defaults.ts>) 并由包根导出。核心调用方构造 Manager 必须显式传入 engine：

```ts
const engine = createBuiltinParserEngine(['codex'])
const manager = new CompatManager(layout, runtime, engine)
```

离线管理时第二参数明确为 `undefined`。运行加载器同样要求显式 engine，不隐式获取默认装配。原 `codexModel` 配置改为中立的 `modelName`。

`Config.parsers` 省略启用全部已装配实现，`[]` 不启用任何实现。配置只决定参与解析的集合；物理移除时取消 [builtins.ts](<../src/composition/builtins.ts>) 中对应 import/注册并删除该协议目录，其他解析器和核心源码无需修改。

## 缺失解析器与缓存

装配保留无实现依赖的格式边界元数据，防止已移除格式被其他协议的默认目录规则误接管。缺失格式报告 `PARSER_UNAVAILABLE`。缺失 Marketplace 只能按声明性名称索引创建不可安装占位候选；与同名候选的关键策略不确定时阻断该候选，不影响已确定独立的其他候选。

Source/Plugin 扫描记录内容版本和解析器集合/实现版本指纹。过期缓存重新扫描，不能恢复已移除解析器生成的旧能力。安装记录、数据和启用意愿保留；丢失关键运行语义的父实例停止，完整更新事务仍维持锁、切换和回滚边界。

## 验证

结构测试明确限定公共 `parser` 只有上述八个文件，禁止旧目录、转发注册表和厂商分支回流；使用 TypeScript AST 检查导入方向。物理验收在临时工程中移除各组合的实现目录，只调整装配，实际编译、导入中立出口和应用公共入口，验证所有八种集合。

```bash
npm run verify
npm run verify:parsers
```

最终数量与限制见[解析器解耦验证报告](解析器解耦验证报告.md)。本轮不安装或修改当前用户 profile，不声称完成 Desktop Typert/Web 的独立迁移。