2026/9/17 12:49:05
FEATURED · 精选文章 
Craft Agents v0.8.4 版本解析Generic OAuth、Send to Workspace 与打包应用 DevTools【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss本篇指南围绕 Craft Agents 开源项目的 v0.8.4 版本发布说明展开重点解读三个核心新特性API 源通用 OAuth 认证、跨工作区资源分享 Send to Workspace、打包应用内调试工具并逐一剖析该版本修复的关键缺陷及其背后的实现原理。阅读完本文你将理解 Generic OAuth 的端点自动发现机制与配置方法、资源跨工作区传输的 RPC 管线以及如何排查打包应用中的常见故障。版本概览v0.8.4 是 Craft Agents 的一个功能与稳定性并重的版本核心目标是扩展 API 源的认证方式与打通多工作区之间的资源共享链路。该版本没有引入任何破坏性变更现有配置与工作流可无缝升级。版本核心内容一览类别内容新特性API 源通用 OAuth 认证含 RFC 9728 自动发现新特性Send to Workspace 跨工作区分享sources / skills / automations新特性打包应用内可通过 View Toggle Developer Tools 打开 DevTools改进补充 Generic OAuth 配置与自动发现指南文档修复共 11 项涉及 Pi 路由、电源管理、WebUI、远程路由、OAuth 取令牌等破坏性变更无Generic OAuth让任意 API 源支持标准 OAuth 认证在 v0.8.4 之前API 类型源Source的 OAuth 认证主要面向 Google、Microsoft、Slack 等内置 provider它们拥有预置的 OAuth 端点与服务定义。v0.8.4 将 OAuth 能力推广到任意 OAuth 2.0 提供商——只要在源的config.json中配置一个oauth配置块GitHub、Linear、Notion、Spotify 等任何遵循标准 OAuth 2.0 的服务都可以通过授权码流程接入而无需借助 MCP 服务器或手工维护个人访问令牌PAT。配置结构ApiOAuthConfig在 源码类型定义 中ApiSourceConfig新增了oauth?: ApiOAuthConfig字段其完整结构如下字段必填说明authorizationUrl是OAuth 授权端点 URLtokenUrl是OAuth 令牌交换端点 URLclientId是OAuth 客户端 IDclientSecret否客户端密钥公开的 PKCE 客户端可省略scopes否请求的 OAuth 权限范围数组audience否Auth0 风格的 audience 参数extraParams否追加到授权 URL 的额外参数如access_typeoffline一个最小化的 API 源配置示例以 GitHub 为例{ id: github-api, name: GitHub API, slug: github-api, provider: github, type: api, enabled: true, api: { baseUrl: https://api.github.com, authType: oauth, oauth: { authorizationUrl: https://github.com/login/oauth/authorize, tokenUrl: https://github.com/login/oauth/access_token, clientId: YOUR_CLIENT_ID, clientSecret: YOUR_CLIENT_SECRET, scopes: [repo, read:user] } } }关键点在于api.authType必须设置为oauth。源码中的判定函数 isGenericOAuthSource 明确了识别规则API 类型 authType oauth provider 不属于 Google/Slack/Microsoft 三个内置 OAuth provider 时即被识别为 Generic OAuth 源并纳入 isOAuthSource 的令牌自动刷新范围。底层实现PKCE 授权码流程Generic OAuth 的实现位于 generic-oauth.ts全部流程统一使用PKCERFC 7636增强安全性代码中通过generatePKCE()生成 code challenge 与 code verifier并以S256方式计算 challenge。整个流程分三个阶段Prepare构造授权 URLprepareGenericOAuth()将client_id、redirect_uri、response_typecode、state、code_challenge、code_challenge_methodS256等参数写入授权 URL并追加配置的scopes、audience与extraParams。回调地址默认为http://localhost:{callbackPort}/callback。Exchange令牌交换exchangeGenericOAuth()使用authorization_code授权类型向tokenUrl发起 POST 请求携带code_verifier完成 PKCE 校验。值得注意的实现细节是parseTokenResponse()它同时兼容 JSON 与application/x-www-form-urlencoded两种响应格式——因为 GitHub 等提供商默认返回表单编码响应代码注释明确指出这是刻意为之的容错设计。Refresh令牌刷新refreshGenericOAuthToken()使用refresh_token授权类型自动续期。tokenUrl与clientId从源配置读取clientSecret优先取凭据存储中的值、回退到配置。RFC 9728 自动发现只需提供 issuer URLv0.8.4 的另一大亮点是授权服务器元数据的自动发现。遵循 RFC 9728OAuth Authorization Server Metadata与 RFC 8414客户端无需手工填写完整的authorizationUrl/tokenUrl只需提供 issuer 基础地址其余端点全部自动解析。自动发现的核心实现在 oauth.ts 的discoverOAuthMetadata()其渐进式发现顺序为RFC 9728 受保护资源发现先向目标端点发起HEAD请求部分服务器返回 405 时回退到GETStreamable HTTP 服务器则用POST触发 401 响应从WWW-Authenticate头解析resource_metadataURL再获取受保护资源元数据并定位授权服务器RFC 8414 标准位置依次尝试{origin}/.well-known/oauth-authorization-server与路径限定的{origin}/.well-known/oauth-authorization-server{pathname}。发现过程还内建了两层安全防护isUrlSafeToFetch()会拒绝私网 IP、localhost 与非 HTTPS 地址SSRF 防护所有发现请求统一施加 5 秒超时DISCOVERY_TIMEOUT_MS 5000防止元数据端点无响应导致界面卡死。从源码结构可以推断该自动发现机制同时服务于 MCP 源与 API 源两条链路——MCP 源的 OAuth 握手同样依赖它判定服务器是否需要认证并定位令牌端点。Send to Workspace跨工作区一键分享资源v0.8.4 新增的 Send to Workspace 动作允许用户将sources数据源、skills技能、automations自动化三种资源一键分享到其他工作区且同时支持单个操作与批量操作。实现管线export → import 两步 RPC从 SendResourceToWorkspaceDialog.tsx 的源码可以看到该功能建立在resources:export → resources:import的 RPC 管线上导出调用exportResources(activeWorkspaceId, { sources | skills | automations })将选中的资源序列化为 bundle导入按目标工作区类型分流——本地目标直接调用importResources(selectedWorkspaceId, bundle, mode)远程目标通过invokeOnServer(url, token, resources:import, remoteWorkspaceId, bundle, mode)跨服务器调用。导入模式固定为skip即目标工作区已存在的同名资源会被跳过而非覆盖。对话框对结果做了三种结果提示全部导入成功、部分跳过imported 0 skipped 0、全部已存在skipped 0。若远程服务器版本过旧报CHANNEL_NOT_FOUND或No handler for会明确提示目标服务器运行旧版本、请升级后重试。远程目标的连通性检查对话框打开时会并行对每个远程工作区执行testRemoteConnection()健康检查并以图标呈现状态Cloud表示远程可达、CloudOff表示断连此时目标被禁用不可选、Monitor表示本地工作区。断连目标上点击无效避免了看似成功实则失败的糟糕体验。会话传输的既有能力与资源分享并存的还有会话Session传输能力实现在 SendToWorkspaceDialog.tsx它只面向远程工作区本地到本地传输被判定为无意义通过transferSessionToWorkspace()由主进程完成导出、摘要生成与分块传输。批量传输时界面通过分块上传进度chunkSent / chunkTotal归一化出整体进度条并以紫色 LED 描边按钮呈现传输动画。DevTools打包应用内直接调试v0.8.4 将开发者工具带入了生产构建。此前开发者必须借助开发构建dev build才能打开 DevTools 调试问题现在打包后的应用通过View Toggle Developer Tools菜单项即可随时开关开发者工具。其实现非常简洁——在 menu.ts 的视图菜单中直接复用了 Electron 内置的role: toggleDevTools{ role: toggleDevTools as const },这为部署了正式版的用户排查问题提供了便捷通道无需切换到开发环境。关键缺陷修复详解v0.8.4 修复了 11 项缺陷按影响面可归为以下几组路由与消息链路Session 工具经 Pi 不可用#511set_session_labels、set_session_status等会话自管理工具在经由 Pi agent 路径路由时现在可正常工作——这涉及 session-tools-core 的工具在 Pi 分支中的注册与分发链路远程路由负载翻译嵌套负载对象中的workspaceId现在会在远程工作区路由时被正确翻译此前仅在顶层生效嵌套结构中的字段会被遗漏导致路由错乱。认证与令牌API 源 OAuth 令牌获取修复了 SessionManager 中getToken未接入 Generic OAuth API 源的问题——此前即使完成 OAuth 授权运行时也无法从凭据存储取回令牌导致请求始终未认证OAuth 错误提示改进当源配置缺失api.oauth配置块时现在会给出明确的错误信息帮助用户快速定位配置遗漏。界面与行为错误卡片按钮失效错误卡片Error Card中的 Settings 与 Retry 按钮此前未被正确接线点击无响应现已修复模型层级提示写死 Anthropic模型选择弹层此前使用 Anthropic 专属的别名展示层级提示非 Anthropic 提供商下显示错乱现在改为 provider 感知的层级提示屏幕常亮无法关闭#415关闭 Keep Screen Awake 设置后屏幕仍保持常亮的缺陷已修复电源管理逻辑现在会正确响应设置变更。平台与部署场景Linux 资源导入不刷新#415 相关ConfigWatcher 现在会在资源导入后收到通知修复了 Linux 下fs.watch兼容性导致的导入资源需重启才可见问题WebUI 自动化加载失败Automations 改由服务端 RPC加载而非渲染进程直接读取文件系统修复了远程/Docker 部署下自动化列表加载失败的问题——这与 release notes 的回退策略属于同一思路远程环境下文件系统路径不可依赖Release notes 回退路径当 Electron 资源路径resources 目录不可用时发布说明回退到~/.craft-agent/release-notes/。这一机制在 release-notes/index.ts 中实现——该模块将打包的apps/electron/resources/release-notes/*.md内容同步到用户目录的release-notes目录Docker/远程部署下即可从用户目录读取WebUI About 页关于对话框现在正确显示服务器版本、隐藏了无关的 Check Now 按钮且 Whats New发布说明查看在 WebUI 上正常工作。升级建议与兼容性v0.8.4没有破坏性变更升级路径顺畅。结合本版本的修复重点建议升级后重点关注以下场景多工作区用户验证 Send to Workspace 对 sources / skills / automations 的单个与批量传输尤其是远程目标服务器的版本需支持resources:import通道自定义 API 源用户若你的 API 源使用非内置 provider如 GitHub、Linear、Notion可迁移到authType: oauthapi.oauth配置块体验 PKCE 流程与自动令牌刷新若服务商支持 RFC 9728/8414 元数据发现只需提供 issuer 地址即可Docker / 远程部署确认自动化列表与 About 页显示正常发布说明将自动回退到用户目录读取打包应用调试遇到问题时可直接使用 View Toggle Developer Tools 打开 DevTools 查看控制台输出配合 generic-oauth.ts 中的onLog回调与发现过程日志定位 OAuth 握手失败原因。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Craft Agents v0.8.4 版本解析：Generic OAuth、Send to Workspace 与打包应用 DevTools
Craft Agents v0.8.4 版本解析Generic OAuth、Send to Workspace 与打包应用 DevTools【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss本篇指南围绕 Craft Agents 开源项目的 v0.8.4 版本发布说明展开重点解读三个核心新特性API 源通用 OAuth 认证、跨工作区资源分享 Send to Workspace、打包应用内调试工具并逐一剖析该版本修复的关键缺陷及其背后的实现原理。阅读完本文你将理解 Generic OAuth 的端点自动发现机制与配置方法、资源跨工作区传输的 RPC 管线以及如何排查打包应用中的常见故障。版本概览v0.8.4 是 Craft Agents 的一个功能与稳定性并重的版本核心目标是扩展 API 源的认证方式与打通多工作区之间的资源共享链路。该版本没有引入任何破坏性变更现有配置与工作流可无缝升级。版本核心内容一览类别内容新特性API 源通用 OAuth 认证含 RFC 9728 自动发现新特性Send to Workspace 跨工作区分享sources / skills / automations新特性打包应用内可通过 View Toggle Developer Tools 打开 DevTools改进补充 Generic OAuth 配置与自动发现指南文档修复共 11 项涉及 Pi 路由、电源管理、WebUI、远程路由、OAuth 取令牌等破坏性变更无Generic OAuth让任意 API 源支持标准 OAuth 认证在 v0.8.4 之前API 类型源Source的 OAuth 认证主要面向 Google、Microsoft、Slack 等内置 provider它们拥有预置的 OAuth 端点与服务定义。v0.8.4 将 OAuth 能力推广到任意 OAuth 2.0 提供商——只要在源的config.json中配置一个oauth配置块GitHub、Linear、Notion、Spotify 等任何遵循标准 OAuth 2.0 的服务都可以通过授权码流程接入而无需借助 MCP 服务器或手工维护个人访问令牌PAT。配置结构ApiOAuthConfig在 源码类型定义 中ApiSourceConfig新增了oauth?: ApiOAuthConfig字段其完整结构如下字段必填说明authorizationUrl是OAuth 授权端点 URLtokenUrl是OAuth 令牌交换端点 URLclientId是OAuth 客户端 IDclientSecret否客户端密钥公开的 PKCE 客户端可省略scopes否请求的 OAuth 权限范围数组audience否Auth0 风格的 audience 参数extraParams否追加到授权 URL 的额外参数如access_typeoffline一个最小化的 API 源配置示例以 GitHub 为例{ id: github-api, name: GitHub API, slug: github-api, provider: github, type: api, enabled: true, api: { baseUrl: https://api.github.com, authType: oauth, oauth: { authorizationUrl: https://github.com/login/oauth/authorize, tokenUrl: https://github.com/login/oauth/access_token, clientId: YOUR_CLIENT_ID, clientSecret: YOUR_CLIENT_SECRET, scopes: [repo, read:user] } } }关键点在于api.authType必须设置为oauth。源码中的判定函数 isGenericOAuthSource 明确了识别规则API 类型 authType oauth provider 不属于 Google/Slack/Microsoft 三个内置 OAuth provider 时即被识别为 Generic OAuth 源并纳入 isOAuthSource 的令牌自动刷新范围。底层实现PKCE 授权码流程Generic OAuth 的实现位于 generic-oauth.ts全部流程统一使用PKCERFC 7636增强安全性代码中通过generatePKCE()生成 code challenge 与 code verifier并以S256方式计算 challenge。整个流程分三个阶段Prepare构造授权 URLprepareGenericOAuth()将client_id、redirect_uri、response_typecode、state、code_challenge、code_challenge_methodS256等参数写入授权 URL并追加配置的scopes、audience与extraParams。回调地址默认为http://localhost:{callbackPort}/callback。Exchange令牌交换exchangeGenericOAuth()使用authorization_code授权类型向tokenUrl发起 POST 请求携带code_verifier完成 PKCE 校验。值得注意的实现细节是parseTokenResponse()它同时兼容 JSON 与application/x-www-form-urlencoded两种响应格式——因为 GitHub 等提供商默认返回表单编码响应代码注释明确指出这是刻意为之的容错设计。Refresh令牌刷新refreshGenericOAuthToken()使用refresh_token授权类型自动续期。tokenUrl与clientId从源配置读取clientSecret优先取凭据存储中的值、回退到配置。RFC 9728 自动发现只需提供 issuer URLv0.8.4 的另一大亮点是授权服务器元数据的自动发现。遵循 RFC 9728OAuth Authorization Server Metadata与 RFC 8414客户端无需手工填写完整的authorizationUrl/tokenUrl只需提供 issuer 基础地址其余端点全部自动解析。自动发现的核心实现在 oauth.ts 的discoverOAuthMetadata()其渐进式发现顺序为RFC 9728 受保护资源发现先向目标端点发起HEAD请求部分服务器返回 405 时回退到GETStreamable HTTP 服务器则用POST触发 401 响应从WWW-Authenticate头解析resource_metadataURL再获取受保护资源元数据并定位授权服务器RFC 8414 标准位置依次尝试{origin}/.well-known/oauth-authorization-server与路径限定的{origin}/.well-known/oauth-authorization-server{pathname}。发现过程还内建了两层安全防护isUrlSafeToFetch()会拒绝私网 IP、localhost 与非 HTTPS 地址SSRF 防护所有发现请求统一施加 5 秒超时DISCOVERY_TIMEOUT_MS 5000防止元数据端点无响应导致界面卡死。从源码结构可以推断该自动发现机制同时服务于 MCP 源与 API 源两条链路——MCP 源的 OAuth 握手同样依赖它判定服务器是否需要认证并定位令牌端点。Send to Workspace跨工作区一键分享资源v0.8.4 新增的 Send to Workspace 动作允许用户将sources数据源、skills技能、automations自动化三种资源一键分享到其他工作区且同时支持单个操作与批量操作。实现管线export → import 两步 RPC从 SendResourceToWorkspaceDialog.tsx 的源码可以看到该功能建立在resources:export → resources:import的 RPC 管线上导出调用exportResources(activeWorkspaceId, { sources | skills | automations })将选中的资源序列化为 bundle导入按目标工作区类型分流——本地目标直接调用importResources(selectedWorkspaceId, bundle, mode)远程目标通过invokeOnServer(url, token, resources:import, remoteWorkspaceId, bundle, mode)跨服务器调用。导入模式固定为skip即目标工作区已存在的同名资源会被跳过而非覆盖。对话框对结果做了三种结果提示全部导入成功、部分跳过imported 0 skipped 0、全部已存在skipped 0。若远程服务器版本过旧报CHANNEL_NOT_FOUND或No handler for会明确提示目标服务器运行旧版本、请升级后重试。远程目标的连通性检查对话框打开时会并行对每个远程工作区执行testRemoteConnection()健康检查并以图标呈现状态Cloud表示远程可达、CloudOff表示断连此时目标被禁用不可选、Monitor表示本地工作区。断连目标上点击无效避免了看似成功实则失败的糟糕体验。会话传输的既有能力与资源分享并存的还有会话Session传输能力实现在 SendToWorkspaceDialog.tsx它只面向远程工作区本地到本地传输被判定为无意义通过transferSessionToWorkspace()由主进程完成导出、摘要生成与分块传输。批量传输时界面通过分块上传进度chunkSent / chunkTotal归一化出整体进度条并以紫色 LED 描边按钮呈现传输动画。DevTools打包应用内直接调试v0.8.4 将开发者工具带入了生产构建。此前开发者必须借助开发构建dev build才能打开 DevTools 调试问题现在打包后的应用通过View Toggle Developer Tools菜单项即可随时开关开发者工具。其实现非常简洁——在 menu.ts 的视图菜单中直接复用了 Electron 内置的role: toggleDevTools{ role: toggleDevTools as const },这为部署了正式版的用户排查问题提供了便捷通道无需切换到开发环境。关键缺陷修复详解v0.8.4 修复了 11 项缺陷按影响面可归为以下几组路由与消息链路Session 工具经 Pi 不可用#511set_session_labels、set_session_status等会话自管理工具在经由 Pi agent 路径路由时现在可正常工作——这涉及 session-tools-core 的工具在 Pi 分支中的注册与分发链路远程路由负载翻译嵌套负载对象中的workspaceId现在会在远程工作区路由时被正确翻译此前仅在顶层生效嵌套结构中的字段会被遗漏导致路由错乱。认证与令牌API 源 OAuth 令牌获取修复了 SessionManager 中getToken未接入 Generic OAuth API 源的问题——此前即使完成 OAuth 授权运行时也无法从凭据存储取回令牌导致请求始终未认证OAuth 错误提示改进当源配置缺失api.oauth配置块时现在会给出明确的错误信息帮助用户快速定位配置遗漏。界面与行为错误卡片按钮失效错误卡片Error Card中的 Settings 与 Retry 按钮此前未被正确接线点击无响应现已修复模型层级提示写死 Anthropic模型选择弹层此前使用 Anthropic 专属的别名展示层级提示非 Anthropic 提供商下显示错乱现在改为 provider 感知的层级提示屏幕常亮无法关闭#415关闭 Keep Screen Awake 设置后屏幕仍保持常亮的缺陷已修复电源管理逻辑现在会正确响应设置变更。平台与部署场景Linux 资源导入不刷新#415 相关ConfigWatcher 现在会在资源导入后收到通知修复了 Linux 下fs.watch兼容性导致的导入资源需重启才可见问题WebUI 自动化加载失败Automations 改由服务端 RPC加载而非渲染进程直接读取文件系统修复了远程/Docker 部署下自动化列表加载失败的问题——这与 release notes 的回退策略属于同一思路远程环境下文件系统路径不可依赖Release notes 回退路径当 Electron 资源路径resources 目录不可用时发布说明回退到~/.craft-agent/release-notes/。这一机制在 release-notes/index.ts 中实现——该模块将打包的apps/electron/resources/release-notes/*.md内容同步到用户目录的release-notes目录Docker/远程部署下即可从用户目录读取WebUI About 页关于对话框现在正确显示服务器版本、隐藏了无关的 Check Now 按钮且 Whats New发布说明查看在 WebUI 上正常工作。升级建议与兼容性v0.8.4没有破坏性变更升级路径顺畅。结合本版本的修复重点建议升级后重点关注以下场景多工作区用户验证 Send to Workspace 对 sources / skills / automations 的单个与批量传输尤其是远程目标服务器的版本需支持resources:import通道自定义 API 源用户若你的 API 源使用非内置 provider如 GitHub、Linear、Notion可迁移到authType: oauthapi.oauth配置块体验 PKCE 流程与自动令牌刷新若服务商支持 RFC 9728/8414 元数据发现只需提供 issuer 地址即可Docker / 远程部署确认自动化列表与 About 页显示正常发布说明将自动回退到用户目录读取打包应用调试遇到问题时可直接使用 View Toggle Developer Tools 打开 DevTools 查看控制台输出配合 generic-oauth.ts 中的onLog回调与发现过程日志定位 OAuth 握手失败原因。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
