dsh-postman

配置 Postman API Key

推荐：在 dsh 里打开「设置 → Postman」，直接填进表单。因为标了 role('secret')， 读取时值被抹掉、页面只显示「已配置 / 未配置」，明文不回流浏览器。

在 Postman 账号设置 → API Keys 生成 Key（PMAK- 开头）。

保存后如果当前会话仍读到旧 Key（用 postman_config 看 来源： 那行就知道）： 换一个新会话，或重启 dsh。原因见下方「保存为什么可能不马上生效」。

留空时的回退顺序：

1. 设置表单里的 apiKey（写入 profile 的 patch 层，即 ~/.dsh/profiles/ /cordis.patch.yml）
2. ~/.dsh/dsh-postman/config.json（备用页写入，权限 0600）
3. ~/.postman_api_key（历史文件）
4. POSTMAN_API_KEY 环境变量

postman_config 的 status 会直接告诉你当前用的是哪一条来源，排查时先看它。

备用页在 http://127.0.0.1: /dsh-postman，功能与设置表单等价，多了「保存并验证」。 它写的是上面第 2 条（~/.dsh/dsh-postman/config.json），每次取 Key 都重新读文件， 所以改完立刻生效、不受会话新旧影响 —— 设置页遇到怪问题时可以用它兜底。

设置页是怎么来的（关键：光导出 Config 不够）

dsh 里并存着两套设置服务实现，插件对两套都做了适配，且不会重复出页：

dsh 版本	实现	describe() 的数据来源	本插件的适配
0.2.x	SettingsForms	遍历 profile 条目，取 entry.fiber.runtime.Config 当 schema；volatileForm() 会丢掉没有任何 volatile 字段的条目	导出 Config（src/index.js 顶部）
0.1.x	SettingsProvider	只列显式注册过的命名空间	调 settings.register('dsh-postman', Config, { base })，并 watch() 变更

两条路径互不干扰：0.2.x 的服务没有 register 方法，插件会直接跳过；0.1.x 不读 Config。

apiKey 必须标 volatile（这里用 .extra('volatile', true)，见 src/index.js 的注释）： 在 0.2.x 上，一个 volatile 字段都没有的条目会被 volatileForm() 整个滤掉。

但这两件事只让命名空间「有 schema 可渲染」，并不会让设置里出现一行。 Web 客户端的设置导航行只来自客户端注册的 settings.section 槽位 （ui-settings-general 的 nav 投影就是 ctx.slots.entries('settings.section')）； 宿主侧那个 autoGenerate 字段在 Web 客户端没有任何消费方（桌面端才用）。 所以本插件自带了一个客户端半边 —— client/client.js，注册 id 为 postman 的设置分区， 页面直接编辑 dsh-postman 命名空间的 apiKey：

• 接线靠 package.json 的 dsh.client（platform: 'web' + inject）与 exports["./client"]； 宿主把该文件经 /plugins 发给浏览器，不需要构建步骤（手写 JS，只用 require("react")）。
• 页面通过 ctx.configForms.get('dsh-postman') 读写，与官方设置页共用同一套 「读取脱敏 / 写入走 profile user 层 / revision 冲突栅栏」。
• 「Key 是否已配置」读的是 describe() 视图的 secrets（role('secret') 字段的值被抹掉， 只回一个 set 布尔），所以页面永远拿不到明文。
• 用 configForms.whileServed(['dsh-postman'], …) 包住注册：命名空间没被服务时不出现这一页。

客户端这一页只在 0.2.x 上出现。 settings.section 槽位与 configForms 服务都是 0.2.x 的 ui-settings 才有的（在已安装的 0.1.1-rc.1 里全仓搜不到这两个名字）。 插件对这种情况做了兜底：apply() 发现 configForms 缺失就静默退出，不抛错。 0.1.x 上请用备用页 /dsh-postman 配置，或直接写 cordis.patch.yml。

保存为什么可能不马上生效

设置页的写入链路是：configForms.set() → remote.settings.mutate → 宿主 settings.update(ns) → configEditor.edit(entry)。0.2.x 里 configEditor 的文档就是 profile 的 patch 文件（documentPath === profileContext.patchPath），写完后它会 显式 reconcileProfilePatches(..., [entryId]) 重载该条目，所以插件配置本身是热更新的。

但要注意两点：

1. 外部直接改 cordis.patch.yml 不会被热加载（实测：运行中改文件、等 12 秒， 插件仍报旧来源）。只有走设置页/configEditor 这条通道才会 reconcile。
2. 已经跑起来的长会话可能仍持有旧的工具闭包（工具对象在会话建立时就固定了）， 于是新 Key 要等新会话才被读到。这就是「设置里存了 Key，postman_config 却 还显示历史文件」的成因 —— 不是没存进去，是那个会话还没换上新配置。

想立刻生效、且不想管会话新旧：用备用页 /dsh-postman，它每次取 Key 都重读文件。

自检（四层，缺一层就会漏掉一种失败）：

• node test/settings-page.js —— 复刻 dsh 已构建产物里的表单投影逻辑跑真实 Config， 并带一条反向对照（去掉 volatile → 条目必被丢弃）。
• node test/client-bundle.js —— 在假浏览器里加载 client/client.js，验证 bundle id、槽位注册与写入路径，以及「0.1.x 没有 configForms 时不抛错」。
• bash test/client-served.sh —— 真启动，从 index.html 的启动图里读出该插件的 bundle 地址再取回来校验（dsh.client 接线错了宿主不会报错，只会让那一页消失）。
• bash test/probe-key.sh —— 真启动后直接 GET /dsh-postman/api/config， 看插件实际认的是哪一条 Key 来源（排查「我明明配了却读不到」最快的一招）。

想直接看宿主侧的判定：dsh --profile web --dump-config-schema， dsh-postman 应指向真实 schema（如 #/$defs/config101）而不是 unknownConfig。

关于 API 端点（为什么不做成配置项）

浏览器里那个 .postman.co 地址不影响 API：它是 Postman 给每个团队自动生成的 teamDomain（团队名的 slug，GET /me 里就能看到），只决定浏览器打开哪个团队的界面。 API 走的是 https://api.getpostman.com，用 API Key 认证，按账号返回数据 —— 同一个 Key 直接就能拿到该账号下的全部集合，和团队域名无关。

唯一真正会换端点的情况是 Postman Enterprise 的 EU 数据驻留 （官方文档： The Postman API uses the api.eu.postman.com subdomain），需要联系 Postman 销售购买、 仅企业版可用，且部分端点不可用。普通/团队/企业（US）账号一律用默认端点。

所以这里没有做 UI 配置项：为极少数 EU 企业用户加一个设置字段，成本大于收益。 但留了一个不改代码的逃生口 —— 环境变量 POSTMAN_API_BASE：

POSTMAN_API_BASE=https://api.eu.postman.com dsh web

postman_config({ action: "status" }) 会把这行直接打出来，你能一眼确认当前用的是哪个端点：

已配置：PMAK-650…4d18
来源：历史文件 ~/.postman_api_key
端点：https://api.getpostman.com（默认）

0.4.1 及以前有两条限制（postman_tree 输出过长会被静默截断、没有「编辑」动作只能 先删再加）已在 0.5.0 解决：前者改为带 path / limit 且截断时显式提示， 后者新增 postman_edit 就地 patch。技能正文与系统提示的工具清单已同步。