Claude Code 插件迁移：权限模型差异与适配实战

1. 从一个真实踩坑说起：插件迁移的幻觉

去年下半年，我所在的团队开始大规模使用 Claude Code 做日常开发辅助。当时大家用得挺顺手，直到某天一位同事提了个需求：能不能把 DeepSeek Harness 上跑得挺好的一套 Mods 插件体系，直接搬到 Claude Code 里复用？毕竟两边都是围绕代码生成、上下文管理、工具调用这套逻辑在转，理论上接口对得上，迁移成本应该不高。

我当时的第一反应是：插件代码能跑通，那不就等于迁移完成了吗？结果实际动手之后才发现，事情远没有想象中简单。插件本身确实能迁移，函数签名对得上，依赖装得上，甚至单元测试都能过。但真正跑起来之后，权限模型这一层直接把整个方案卡死了。

这个标题说的就是这件事：插件能迁移，不代表权限也能照搬。我打算把这次折腾的完整过程拆开讲，包括为什么会产生"能直接搬"的错觉、权限模型到底差在哪、实际迁移时哪些地方必须重写、以及我最后是怎么把两套体系打通又不留安全隐患的。如果你也在做类似的多平台插件适配，或者正在评估从一套 AI 编码工具迁移到另一套的可行性，这篇应该能帮你少走不少弯路。

先说清楚适用人群：这篇文章适合有一定插件开发经验、了解工具调用（Tool Calling）机制、并且正在做跨平台适配的开发者。如果你只是单纯用 Claude Code 写代码，不涉及插件层改造，那这篇可能偏底层了一些，但里面关于权限边界的思路对理解工具行为也有帮助。

2. 两套体系的整体设计差异拆解

2.1 DeepSeek Harness 的 Mods 架构是怎么设计的

DeepSeek Harness 这套东西，本质上是一个围绕模型能力做扩展的运行时框架。它的 Mods 插件体系有几个很鲜明的特点：

• 插件即能力单元：每个 Mod 是一个独立的能力包，可以注册新的工具、新的上下文处理器、新的输出后处理器。
• 权限声明式注册：插件在注册时通过清单文件声明自己需要哪些权限，比如文件读写、网络请求、命令执行等。
• 运行时沙箱隔离：不同 Mod 跑在相对独立的执行环境里，互相之间通过消息总线通信。
• 权限粒度较粗：大部分权限是按"类别"授予的，比如"文件系统访问"就是一个大类，具体读哪个目录、写哪个文件，运行时再做路径校验。

这套设计的好处是上手快，插件作者只需要在清单里写清楚需要什么权限，宿主环境负责校验。坏处是权限边界比较模糊，一个插件拿到"文件系统访问"之后，理论上能碰的东西比它实际需要的多。

2.2 Claude Code 的 Mods 机制有什么不同

Claude Code 这边的插件体系，设计哲学明显不一样。它更强调最小权限和显式授权：

• 工具级权限：每个工具调用都要经过权限检查，不是插件级别一次性授权。
• 会话级授权：权限是在会话上下文中动态判定的，同一个插件在不同会话里可能拿到不同权限。
• 路径级白名单：文件访问不是给一个目录就完事，而是要精确到具体路径模式。
• 命令执行需要逐条确认：不像 Harness 那样给个"命令执行"权限就放行，Claude Code 对每条命令都要走确认流程。

这两套体系的差异，直接导致了"插件能迁移但权限不能照搬"这个结论。你如果把 Harness 的插件代码原封不动搬过来，代码逻辑能跑，但权限声明那一套完全对不上，要么被拒绝执行，要么被迫放宽权限导致安全隐患。

2.3 为什么会产生"能直接迁移"的错觉

我复盘了一下，这个错觉主要来自三个层面：

第一层是接口层面的相似性。两边都提供类似的工具注册接口，函数签名长得差不多，参数类型也能对上。你写个registerTool(name, handler, schema)，两边都能跑。这种表面的一致性很容易让人以为底层机制也一样。

第二层是测试环境的宽松。在开发环境里，权限校验往往被简化甚至关闭，插件跑起来毫无阻碍。等到上生产环境，权限模型开始生效，问题才暴露出来。

第三层是文档的误导。很多迁移指南只讲代码怎么改，不讲权限怎么适配。你照着文档走，代码迁移完了，以为大功告成，结果权限这关过不去。

这里给个实操建议：做跨平台插件迁移时，先把两边的权限模型文档拉出来对比，画一张权限映射表，再动手改代码。否则你会在调试权限问题上浪费大量时间。

3. 权限模型的核心差异与映射难点

3.1 权限粒度：从"类别授权"到"调用级授权"

这是最根本的差异。Harness 的权限是类别级的，Claude Code 是调用级的。

举个例子，Harness 里一个插件声明了filesystem:read权限，那它在运行时可以读任何被沙箱允许的路径。而 Claude Code 里，每次文件读取都要单独判定：这个路径在不在白名单里？当前会话有没有授权？调用者身份对不对？

这意味着你不能简单地把 Harness 的权限声明翻译成 Claude Code 的权限声明。你需要把原来的"类别权限"拆解成一系列具体的"调用权限"，并且为每个调用点配置对应的授权规则。

我当时的做法是写了一个权限映射层，把 Harness 的权限声明解析成一组细粒度的权限规则，然后在 Claude Code 侧逐条注册。这个映射层的核心逻辑大概是这样的：

# 权限映射层伪代码 HARNESS_TO_CLAUDE_PERMISSION_MAP = { "filesystem:read": [ {"tool": "read_file", "constraint": "path_whitelist"}, {"tool": "list_directory", "constraint": "path_whitelist"}, ], "filesystem:write": [ {"tool": "write_file", "constraint": "path_whitelist_and_confirm"}, {"tool": "create_directory", "constraint": "path_whitelist"}, ], "network:request": [ {"tool": "http_request", "constraint": "domain_whitelist"}, ], "command:execute": [ {"tool": "run_command", "constraint": "per_command_confirm"}, ], } def map_permissions(harness_permissions): claude_rules = [] for perm in harness_permissions: rules = HARNESS_TO_CLAUDE_PERMISSION_MAP.get(perm) if not rules: raise UnmappedPermissionError(perm) claude_rules.extend(rules) return claude_rules

这个映射表不是拍脑袋写的，是我对着两边的权限文档一条条对出来的。中间有几个权限在 Claude Code 侧找不到直接对应，只能拆成更细的规则组合。

3.2 授权时机：静态声明 vs 动态判定

Harness 的权限是静态声明的，插件加载时就把权限定死了。Claude Code 是动态判定的，同一个工具调用在不同上下文里可能有不同结果。

这个差异带来的问题是：Harness 插件里那些"假设自己有权限就直接执行"的代码，在 Claude Code 里会频繁触发权限检查，导致大量确认弹窗或者直接拒绝。

我的处理方式是在插件适配层加了一个权限预检步骤。在真正调用工具之前，先走一遍权限判定，如果没权限就提前返回错误，而不是等到调用时才失败。这样至少能让错误信息更清晰，也方便调试。

# 权限预检示例 async def safe_tool_call(tool_name, params, context): allowed = await check_permission(tool_name, params, context) if not allowed: return { "error": "permission_denied", "tool": tool_name, "reason": allowed.reason, "suggestion": allowed.suggestion, } return await execute_tool(tool_name, params, context)

3.3 路径与域名的白名单机制差异

Harness 的路径校验比较宽松，通常是给一个根目录，然后允许访问其下所有内容。Claude Code 要求精确的路径模式匹配，支持通配符但规则更严格。

域名白名单也是类似情况。Harness 可能允许配置一个域名列表，Claude Code 则要求每个域名单独授权，而且对协议、端口都有要求。

这里有个坑我踩过：Harness 里配置的*.example.com这种通配域名，在 Claude Code 里不能直接照搬，需要展开成具体的子域名列表，或者用 Claude Code 支持的通配语法重写。我当时的做法是写了个转换脚本，把 Harness 的通配规则展开成 Claude Code 能识别的格式。

3.4 权限继承与组合的逻辑冲突

Harness 支持权限继承，子插件可以继承父插件的权限。Claude Code 没有继承概念，每个插件独立授权。

这意味着原来依赖继承关系的插件体系，迁移到 Claude Code 后需要把继承链上的权限全部显式声明一遍。如果继承层次深，这个工作量不小。

我遇到的一个案例是：某个 Mod 依赖三层继承拿到了文件写入权限，迁移时需要在最底层插件里显式声明所有相关权限。好在 Claude Code 的权限声明支持引用，可以把公共权限集抽出来复用，减少重复。

4. 实操迁移的完整流程与关键步骤

4.1 第一步：梳理原插件的权限依赖清单

动手改代码之前，先把 Harness 插件的权限依赖全部列出来。不要只看清单文件，还要扫代码里实际用到的工具调用。

我写了个静态分析脚本，扫描插件代码里所有工具调用点，提取出实际使用的权限，然后和清单文件里的声明做对比。结果发现清单里声明的权限比实际用到的多出不少，有些是历史遗留，有些是防御性声明。

# 权限依赖扫描脚本示意 python scan_permissions.py \ --plugin-dir ./harness-mods \ --output permission_inventory.json \ --include-runtime-calls

扫描结果会生成一个权限清单，包含每个权限的来源（声明还是实际调用）、使用频率、关联的代码位置。这份清单是后续映射的基础。

4.2 第二步：建立权限映射表并逐条验证

拿到权限清单后，对照 Claude Code 的权限模型建立映射表。映射表要包含这几列：

映射完成后，每一条都要在测试环境里验证。验证方法是构造对应的工具调用，看权限判定是否符合预期。

注意：有些权限在 Claude Code 里没有直接对应，需要重新设计实现方式。比如 Harness 的context:modify权限，Claude Code 里没有等价物，只能通过会话级的状态管理来模拟。

4.3 第三步：重写权限声明与适配层

映射表验证通过后，开始重写插件的权限声明。Claude Code 的权限声明格式和 Harness 不同，需要按它的规范来写。

{ "plugin": "migrated-mod", "permissions": [ { "tool": "read_file", "constraints": { "path_patterns": ["/workspace/src/**", "/workspace/config/*.json"] } }, { "tool": "write_file", "constraints": { "path_patterns": ["/workspace/output/**"], "require_confirmation": true } } ] }

适配层的核心是把原来直接调用工具的地方，改成走权限预检的封装函数。这个改动量取决于插件里工具调用的数量，我那个插件大概有三十多个调用点，改起来花了半天时间。

4.4 第四步：运行时权限校验的联调

代码改完之后，进入联调阶段。这一步最容易出问题，因为权限校验涉及运行时上下文，很多边界情况只有在实际运行中才会暴露。

我当时的联调策略是分场景测试：

• 正常路径：插件在授权范围内调用工具，应该顺利执行。
• 越权路径：插件尝试访问未授权资源，应该被拒绝并给出清晰错误。
• 边界路径：路径白名单的边界情况，比如符号链接、相对路径、大小写敏感等。
• 并发场景：多个插件同时调用工具，权限判定是否互相干扰。

每个场景都要记录实际行为和预期行为的差异，有差异就回去改适配层。

4.5 第五步：权限降级与兜底策略

迁移过程中难免遇到某些权限在 Claude Code 侧无法完全对应的情况。这时候需要设计降级策略：

• 功能降级：如果某个权限拿不到，插件能否用其他方式实现同样功能？
• 提示降级：如果无法自动执行，能否改成提示用户手动操作？
• 拒绝降级：如果既不能自动也不能提示，直接拒绝并说明原因。

我倾向于优先用功能降级，实在不行再用提示降级。拒绝降级是最后手段，因为用户体验最差。

5. 常见问题与排查技巧实录

5.1 权限被拒绝但不知道原因

这是最常见的问题。Claude Code 的权限拒绝信息有时候比较简略，只告诉你"权限不足"，不告诉你具体缺哪个权限。

我的排查方法是打开详细日志，看权限判定的完整链路。Claude Code 通常会在日志里记录判定过程，包括检查了哪些规则、哪条规则拒绝了、拒绝的原因是什么。

# 开启权限调试日志 export CLAUDE_PERMISSION_DEBUG=1 export CLAUDE_LOG_LEVEL=debug

如果日志还不够详细，可以在适配层加自定义日志，把每次权限预检的输入输出都打出来。

5.2 路径白名单匹配不上

路径匹配的坑特别多。我遇到过这几种情况：

• 相对路径 vs 绝对路径：Harness 插件里用的是相对路径，Claude Code 要求绝对路径，需要转换。
• 符号链接：白名单里写的是真实路径，插件通过符号链接访问，匹配不上。
• 大小写敏感：不同文件系统大小写敏感性不同，白名单匹配规则要统一。
• 路径分隔符：跨平台时路径分隔符不一致，需要规范化。

解决办法是在适配层加一个路径规范化函数，把所有路径统一成 Claude Code 期望的格式再送去匹配。

5.3 命令执行权限反复弹窗

Harness 插件里如果有大量命令执行，迁移到 Claude Code 后会频繁弹确认框，用户体验很差。

我的处理方式是做权限聚合：把一组相关的命令合并成一个权限请求，用户确认一次就能执行一组命令。Claude Code 支持这种批量授权，但需要在权限声明里配置好命令分组。

{ "tool": "run_command", "constraints": { "command_groups": [ { "name": "build-tools", "patterns": ["npm *", "yarn *", "pnpm *"], "require_confirmation": "once_per_session" } ] } }

5.4 权限继承链断裂

前面提到 Harness 支持权限继承，Claude Code 不支持。迁移时如果没处理好继承链，会出现"父插件有权限但子插件没有"的情况。

解决办法是在迁移时把继承链展开，把父插件的权限显式复制到子插件。如果多个插件共享同一组权限，可以抽成公共权限模板，各插件引用模板。

5.5 常见问题速查表

5.6 几个独家避坑技巧

技巧一：先做权限映射，再动代码。很多人上来就改代码，改到一半发现权限对不上，又回去改设计。正确顺序是先梳理权限、建映射表、验证映射，再改代码。

技巧二：权限声明宁细勿粗。Claude Code 的权限模型鼓励细粒度声明。不要图省事给一个大权限，后面出问题很难排查。每个工具调用单独声明，虽然麻烦但可控。

技巧三：保留权限降级开关。迁移后的插件最好保留一个降级开关，遇到权限问题时可以临时降级运行，不至于完全不可用。这个开关在生产环境特别有用。

技巧四：权限变更要版本化。插件的权限声明变更时，要像 API 变更一样做版本管理。权限变了但版本没变，会导致运行时行为不一致，很难排查。

技巧五：定期审计权限使用情况。插件跑一段时间后，实际使用的权限可能和声明的不一致。定期审计，把没用的权限删掉，减少攻击面。

6. 迁移后的权限治理与长期维护

6.1 权限最小化原则的落地

迁移完成后，第一件事是做权限最小化审计。把插件实际用到的权限和声明的权限做对比，删掉多余的声明。

我当时的做法是跑一周的运行时日志，统计每个权限的实际调用次数。调用次数为零的权限，直接删掉。调用次数很少的权限，评估是否可以合并或降级。

这个审计过程发现了好几个"僵尸权限"，都是历史遗留的，早就不用了但一直没删。清理之后，插件的权限声明精简了将近三分之一。

6.2 权限变更的回归测试

每次权限声明变更后，都要跑一遍回归测试。测试用例要覆盖：

• 所有授权路径的正常调用
• 所有越权路径的拒绝行为
• 边界条件的处理
• 并发场景下的权限隔离

回归测试最好自动化，集成到 CI 流程里。权限变更没跑过回归测试，不允许合并。

6.3 跨平台权限适配的抽象层设计

如果后续还要支持更多平台，建议把权限适配抽象成独立层。这一层负责：

• 解析各平台的权限声明格式
• 映射到统一的内部权限模型
• 按目标平台生成对应的权限声明
• 运行时做权限预检和降级处理

有了这层抽象，新增平台支持时只需要写一个适配器，不用改插件核心代码。

# 权限适配抽象层示意 class PermissionAdapter: def parse(self, raw_declaration): raise NotImplementedError def map_to_internal(self, parsed): raise NotImplementedError def generate_target(self, internal_model, target_platform): raise NotImplementedError def precheck(self, tool_call, context): raise NotImplementedError

6.4 权限文档与团队协作

迁移过程中积累的权限映射表、适配层设计、避坑经验，都要整理成文档。团队里其他人做类似迁移时，可以直接参考，不用重复踩坑。

文档要包含：

• 两套权限模型的对比说明
• 权限映射表的完整版本
• 适配层的设计文档和代码示例
• 常见问题速查表
• 迁移检查清单

这份文档我后来整理成了一个内部 Wiki 页面，团队里做跨平台适配的同事都在用。反馈下来，最大的价值是那个权限映射表，省了每个人重新对权限的时间。

6.5 权限安全的持续监控

迁移完成后不是就没事了，权限安全需要持续监控。我配置了几个监控指标：

• 权限拒绝率：突然升高可能意味着权限配置有问题
• 权限确认弹窗频率：太高说明权限粒度过细，需要调整
• 越权尝试次数：如果有插件频繁尝试越权，可能是代码逻辑有问题
• 权限变更频率：频繁变更权限声明可能意味着设计不稳定

这些指标接入告警系统，异常时自动通知。跑了一段时间后，确实发现过几次权限配置问题，都是通过监控提前发现的。

7. 我个人在实际操作中的几点体会

这次迁移折腾下来，最大的感受是：跨平台插件迁移，代码迁移只是冰山一角，权限适配才是真正的工作量所在。如果一开始就意识到这一点，整个迁移过程会顺畅很多。

另外一个体会是，权限模型的设计差异往往反映了平台的设计哲学。Harness 偏向灵活和效率，Claude Code 偏向安全和可控。迁移时不能只想着"怎么把功能搬过去"，还要想"怎么在新平台的约束下实现同样的功能"。有时候需要重新设计实现方式，而不是简单翻译。

最后分享一个小技巧：迁移过程中，我会维护一个"权限问题日志"，记录每个遇到的权限问题、排查过程、解决方案。这个日志后来成了团队里最有价值的参考资料，比任何官方文档都实用。如果你也在做类似迁移，强烈建议你也维护一份。

这个内容后续还可以这样扩展：把权限适配层做成开源工具，支持更多平台的权限模型互转；或者研究一下权限模型的自动化测试框架，让权限变更的回归测试更高效。这两个方向我都还在探索中，有进展再分享。