new-erp-mcp 0.2.2 → 0.3.0

package/README.md

@@ -12,7 +12,7 @@
 
 ### 1. 安装命令行工具
 
-需要 Node.js 20+。npm 包名为 `new-erp-mcp`，安装后使用 `new-erp` 命令。也支持 `npm install -g ./new-erp-mcp-0.2.2.tgz` 安装下载的 npm 包。
+需要 Node.js 20+。npm 包名为 `new-erp-mcp`，安装后使用 `new-erp` 命令。也支持 `npm install -g ./new-erp-mcp-0.3.0.tgz` 安装下载的 npm 包。
 
 ```sh
 node --version
@@ -26,18 +26,20 @@ new-erp game-product-list --help
 npx --package=new-erp-mcp new-erp game-product-list --help
 ```
 
-需要固定版本时使用 `new-erp-mcp@0.2.2`。
+需要固定版本时使用 `new-erp-mcp@0.3.0`。
 
 ### 2. 配置 ERP
 
-推荐用自己的 ERP 账号登录，密码在终端中隐藏输入：
+推荐打开本机临时网页登录，一次填写 ERP 网址、账号和密码：
 
 ```sh
-new-erp login --baseUrl https://your-erp.example.com
+new-erp login --browser
 ```
 
 登录只保存 token，不保存密码，后续 CLI 与本地 MCP 均可使用。运行 `new-erp logout` 删除本机登录会话。
 
+网页登录成功后自动关闭临时服务。MCP 未登录时才返回详细引导，让 Agent 打开登录页并在完成后重试查询；初始化只加载两个入口，业务参数按需发现。也支持 `new-erp login --baseUrl https://your-erp.example.com` 在终端隐藏输入密码，或使用客户端私密输入卡。
+
 已有 token 时，也可在运行命令的目录创建不提交到版本库的 `config.json`：
 
 ```json
@@ -117,13 +119,15 @@ new-erp setup --client codex
 
 该命令调用本机 `codex mcp add`，将当前 Node.js 和 MCP 入口的绝对路径注册到 Codex，无需手动编辑配置。需要先安装 Codex CLI；会替换同名的 `new-erp` MCP 配置，可用 `--name` 改名或用 `--dryRun` 预览。重启 Codex 后即可在对话中查询。
 
-`new-erp mcp` 提供本地 stdio MCP，工具为 `game_product_list`、`product_detail`、`inventory_list` 和 `erp_options`。所有工具只使用 `new-erp login` 保存的会话；缺失或失效时要求重新登录，不读取项目或环境中的共享 token。
+`new-erp mcp` 只注册 `erp_discover` 和 `erp_execute` 两个入口，按需发现并调用现有全部 24 项业务能力。包括商品、ASIN 图片、销量、订单、库存、装箱、配货、物流和导出；`auth.login` 可直接打开本机配置页，不需要 Agent 执行终端命令。业务只使用保存的个人会话，不读取共享 token。
+
+导出返回任务编号及本地文件路径，长任务不阻塞客户端；参数与完整能力目录通过 `erp_discover` 获取。MCP 用户无需安装 CLI 技能。0.3 起，原四个直接工具改为 `erp_execute` 的业务能力名称。
 
 安装、登录保存位置、手动配置和更新方法见 [本地 MCP 指南](./docs/mcp.md)。
 
-## 供 AI Agent 使用
+## 可选 CLI 技能
 
-安装技能，让 Agent 按需选命令、处理分页并核对数据口径：
+MCP 用户无需安装仓库技能。需要让 Agent 直接使用 CLI、处理批量导出或分页时，可选安装：
 
 ```sh
 npx skills add PIZZAxBOY/new-erp-scripts --skill new-erp-scripts --agent codex

package/docs/api.md

@@ -26,7 +26,7 @@ for (const product of products) {
 }
 ```
 
-示例 ASIN 需替换为实际值。CLI 为 `new-erp product-detail --asin B012345678`，MCP 为 `product_detail({ asin: 'B012345678' })`。
+示例 ASIN 需替换为实际值。CLI 为 `new-erp product-detail --asin B012345678`，MCP 为 `erp_execute({ operation: 'product_detail', params: { asin: 'B012345678' } })`，返回任务回执。MCP 覆盖本文件全部业务能力，参数按需发现，详见 [MCP 指南](./mcp.md)。
 
 查询仅访问当前配置的 ERP：
 

package/docs/mcp.md

@@ -1,88 +1,116 @@
-# 通过 npm 安装本地 MCP
+# 安装与使用本地 MCP
 
-本包提供本地 stdio MCP，不需要部署在线服务。每位用户在自己的电脑上安装并登录 ERP，电脑需能访问 ERP。需要 Node.js 20+；自动接入 Codex 还需要 Codex CLI。
+需要 Node.js 20+。MCP 在用户自己的电脑运行，使用各自的 ERP 登录和权限，无需部署服务器。MCP 用户无需安装仓库的可选 CLI 技能。
 
-## 安装与登录
-
-从 npm 安装：
+## 安装并接入客户端
 
 ```sh
 npm install -g new-erp-mcp
+new-erp setup --client codex
 ```
 
-也可以下载打包生成的 `.tgz`，通过 npm 安装：
+重启 Codex 或 T3 Code 以加载 MCP。`setup` 需要已安装的 Codex CLI，将当前 Node.js 和 MCP 脚本的绝对路径写入客户端配置，不写入账号或凭据。用 `codex mcp get new-erp` 检查路径；`new-erp setup --dryRun` 预览注册命令。不要用临时 `npx` 安装目录运行 `setup`。
 
-```sh
-npm install -g ./new-erp-mcp-0.2.2.tgz
+其他支持本地 stdio 的客户端可将 `new-erp mcp` 配置为启动命令。标准输入和输出仅传输 MCP 协议。
+
+## 首次在网页完成配置
+
+向 Agent 提出业务需求即可，例如“按 ASIN 查询商品图片”。未登录时，工具返回配置引导，Agent 调用：
+
+```js
+erp_execute({ operation: 'auth.login', params: {} })
 ```
 
-在自己的终端完成登录，ERP 地址替换为实际地址：
+该调用立即返回本机登录链接，并自动尝试打开浏览器。用户在页面一次填写 ERP 网址、账号和密码；不能自动打开时手动打开返回的链接。Agent 不查看或填写真实密码字段。密码由网页直接交给本地程序登录 ERP，不进入对话、工具参数、命令参数或结果，也不会保存。
+
+页面五分钟后失效，成功、取消或过期后关闭临时服务。登录失败可在原页面重试，不会覆盖原会话。Agent 可查询 `auth.status`，登录成功后重试原业务操作，无需重启 MCP。
+
+也可独立运行 CLI：
 
 ```sh
-new-erp login --baseUrl https://your-erp.example.com
-new-erp setup --client codex
+new-erp login --browser
+new-erp login --browser --open false
 ```
 
-`login` 提示输入账号和密码，密码不回显。也可用 `--username` 提供账号。非交互环境使用 `NEW_ERP_USERNAME` 和 `NEW_ERP_PASSWORD`；不要把密码放进命令参数或聊天。登录失败不会覆盖原会话。
+第二条只输出登录链接。网页不可用时，使用客户端私密输入能力或在自己的终端运行 `new-erp login --baseUrl https://your-erp.example.com`，隐藏输入密码。不要在聊天正文或命令参数中提交密码。
 
-重启 Codex 后即可使用，例如“查询某个 SKU 的产品图片”。`codex mcp list` 可查看注册配置；Codex 终端界面中的 `/mcp` 可查看连接状态。所有工具都要求有效的本机 ERP 会话。
+## 按需发现能力和参数
 
-## Codex 配置
+初始化只加载两个工具，完整业务参数在需要时返回：
 
-`setup` 调用 `codex mcp add`，注册当前安装的 Node.js 和 `scripts/mcp.js` 的绝对路径，不将账号、密码或 token 写入 Codex 配置。它会替换同名配置，其他名称的 MCP 不受影响。
+| 工具 | 用法 |
+| --- | --- |
+| `erp_discover` | `query` 按关键词找能力；`operation` 返回所选能力的参数；都省略时列出目录。 |
+| `erp_execute` | 用 `operation`、`params` 执行；导出还需稳定的 `requestId`。 |
 
-```sh
-new-erp setup --client codex --dryRun
-new-erp setup --client codex --name my-erp
+目录覆盖现有 24 项业务能力：商品与分类、ASIN 图片、销量与汇总、市场订单、库存与凭证、装箱与配货、外包装、物流与申报，以及全部导出。`auth.*` 和 `jobs.*` 也通过同一个入口按需调用。
+
+```js
+erp_discover({ query: '商品' })
+erp_discover({ operation: 'product_detail' })
+erp_execute({ operation: 'product_detail', params: { asin: 'B012345678' } })
 ```
 
-其他支持本地 stdio 的客户端可以使用 `new-erp mcp` 作为启动命令，也可使用 Node.js 和 MCP 脚本的绝对路径。先独立完成登录，MCP 进程的标准输入与输出只传输协议，不能用于交互输入密码。
+ASIN 是示例值。其他业务参数以对应的 `erp_discover({ operation })` 结果为准；未知参数、错误类型和凭据参数会被拒绝。查询只使用本机保存的个人会话，不回退到环境或项目中的共享 token。
 
-不要通过临时的 `npx` 安装目录运行 `setup`；全局安装能提供持久的脚本路径。移动包目录、切换 Node.js 安装位置或更新包后重新运行 `setup`。Codex 的接入方式见 [OpenAI 官方 MCP 文档](https://learn.chatgpt.com/docs/extend/mcp)。
+0.3 起，原四个直接 MCP 工具改为业务能力名称。例如原 `product_detail({ asin })` 改为上面的 `erp_execute` 调用。CLI 和 JavaScript API 保留原有入口。
 
-## 更新版本
+## 读取任务结果和导出文件
 
-```sh
-npm install -g new-erp-mcp@latest
-new-erp setup --client codex
+业务调用返回任务回执，包括 `jobId` 和 `state`。短查询会等待片刻，通常直接返回 `succeeded` 及 `result.data`；较慢的操作返回 `queued` 或 `running`，按 `pollAfterMs` 提示查询：
+
+```js
+erp_execute({ operation: 'jobs.status', params: { jobId: '返回的任务编号' } })
+erp_execute({ operation: 'jobs.list', params: { limit: 10 } })
 ```
 
-更新后重启 MCP 客户端以加载新代码。本机登录会话保存在包目录之外，更新包不会删除会话；同一系统用户、ERP 地址和会话路径下，有效 token 可继续使用，无需重新登录。token 失效、主动退出或更换上述配置后，重新运行 `new-erp login`。
+`succeeded` 才表示执行完成；`failed`、`interrupted` 和 `cancelled` 不能当作成功或空结果。结果以单份 JSON 文本返回，不在 `structuredContent` 中重复整份数据。
 
-## 可用工具
+`jobs.list` 仅返回任务摘要和文件信息，不重复每个任务的数据；完整结果通过单项 `jobs.status` 获取。
 
-| MCP 工具 | 用途 |
-| --- | --- |
-| `game_product_list` | 按 SKU、品名、分类和类型查询 ERP 商品及图片，每次返回一页。 |
-| `product_detail` | 按 ERP 产品基础 ID 或 ASIN 查询详情、ERP 图片和全部 SKU/BOM 版本；`id/asin` 二选一。ASIN 先查 ERP Listing，再按匹配的 SKU 获取详情。 |
-| `inventory_list` | 按精确 SKU、仓库代码查询库存批次或仓库汇总，每次返回一页。 |
-| `erp_options` | 查询库存、装箱或配货仓库的实时枚举。 |
+导出使用独立的请求编号。同一次重试复用编号，新的导出使用新编号；相同编号和参数返回原任务，不重复提交。编号与不同参数冲突时会报错：
+
+```js
+erp_discover({ operation: 'export_game_products' })
+erp_execute({
+  operation: 'export_game_products',
+  requestId: 'product-export-request-001',
+  params: { fields: ['sku', 'name_cn', 'price'], disused: false },
+})
+```
+
+文件保存在本机，结果返回 `artifact.path`、类型、字节数等信息；不会把 XLSX、CSV、Base64 或整份大型结果塞进上下文。大型 JSON 完整保存到文件并提供有限预览；逐页装箱读取保存为 NDJSON，分页失败会标记不完整并返回失败，不静默截断。
 
-工具直接调用已有 JavaScript 函数。数组结果封装为 `{ list }`，对象结果保持原结构；同时返回 MCP 文本和 `structuredContent`。工具参数不接受账号、密码、token 或自定义 ERP 地址。
+默认导出目录为 `~/Downloads/new-erp`，可用 `NEW_ERP_EXPORT_DIR` 指定专用目录。macOS/Linux 的私有任务目录和文件使用 `0700`、`0600` 权限；Windows 使用当前用户的文件权限。MCP 管理输出路径，不接受 CLI 的 `output` 参数。任务记录不保存 token 或密码；换账号后不能通过 MCP 读取其他账号的任务。
 
-商品列表和库存支持 `page`、`pageSize`，默认第1页20条，每页最多100条。`product_detail` 的 ASIN 解析会完整读取相关 Listing 和 SKU 搜索，每页100条，`maxPages` 默认100、上限1000，保留全部精确匹配及店铺信息。批量导出和其他全量查询可继续使用 CLI/API。库存预测量不是已签收库存，保留批次与 BOM 差异。
+## 恢复装箱导出与取消任务
 
-## 本机登录会话
+装箱导出会在继续轮询前保存 ERP `taskId`。任务中断后先检查原任务；有已保存的装箱检查点时，可使用新的请求编号按原范围恢复：
 
-会话仅包含 ERP 地址、账号、token、用户 ID 和上游返回的过期时间，不保存密码，也不会上传到额外的服务。位置为：
+```js
+erp_execute({
+  operation: 'jobs.resume',
+  requestId: 'packing-resume-request-002',
+  params: { jobId: '原装箱任务编号' },
+})
+```
 
-- macOS/Linux：`${XDG_CONFIG_HOME:-~/.config}/new-erp/session.json`。
-- Windows：`%LOCALAPPDATA%\new-erp\session.json`，缺少该变量时使用用户目录下的 `AppData\Local`。
-- 设置 `NEW_ERP_SESSION_FILE` 可指定其他位置，适合隔离不同本地环境。
+恢复会校验原查询和 `taskId`，不创建替代导出。没有检查点或其他导出类型不自动恢复、重提；ERP 端任务可能仍继续运行，先查看下载中心。客户端断线不会自动取消已接收的任务；停止执行进程可能中断本地处理。
 
-token 以明文保存在本机文件，macOS/Linux 文件权限为 `0600`，应用新建的目录为 `0700`；Windows 使用当前用户目录的文件权限。不要分享或提交会话文件。登录写入采用临时文件后原子替换，读到的会话对应一次完整登录。
+`jobs.cancel` 可取消本实例中尚在排队的任务。现有业务 API 不支持可靠地取消运行中的 ERP 操作，工具会明确返回不支持。不同 MCP 进程可以共用任务目录；其他存活进程的未完成任务返回最后记录和不确定状态，不自动接管或重试。
 
-MCP 每次 ERP 调用读取当前会话，并把 ERP 地址及 token 绑定到该次调用；不回退到当前目录的 `config.json` 或 `NEW_ERP_TOKEN`。切换账号或退出后，后续调用使用新的状态，已开始的调用继续使用开始时的会话。
+## 保留登录会话并更新
 
-可识别的过期时间到期，或 ERP 返回登录失效时，需要重新运行 `new-erp login`。目前没有自动刷新 ERP token 的实现。权限不足保留为权限错误，不换用其他账号。
+会话只保存 ERP 地址、账号、token、用户 ID 和过期时间，不保存密码。默认位置为 macOS/Linux 的 `${XDG_CONFIG_HOME:-~/.config}/new-erp/session.json`，或 Windows 的 `%LOCALAPPDATA%\new-erp\session.json`；也可用 `NEW_ERP_SESSION_FILE` 指定位置。
 
 ```sh
-new-erp logout
+npm install -g new-erp-mcp@latest
+new-erp setup --client codex
 ```
 
-`logout` 删除本机保存的会话，不撤销上游 token，也不修改项目配置或环境变量。旧 CLI/API 显式配置的认证仍按原方式生效；MCP 的 ERP 工具要求重新登录。
+更新后重启客户端以加载新代码。会话文件在包目录之外，有效会话会保留，通常无需重新登录；失效后重新打开登录页。`auth.logout` 或 `new-erp logout` 删除本机会话，不撤销 ERP 上游 token；已开始的任务继续使用原账号快照，切换账号后不能读取原账号的任务。
 
-## 打包与验证
+## 打包验证
 
 ```sh
 npm ci
@@ -91,6 +119,4 @@ npm run check:package
 npm pack
 ```
 
-`npm pack` 生成可供 npm 安装的 `.tgz`。可作为 Release 附件分发；上传 Release 或发布 npm registry 是单独的发布操作。包中不包含本机会话、项目配置或测试数据。
-
-`npm run check:package` 检查实际发布文件清单，阻止内部服务地址、个人路径、凭据和业务导出文件进入包。检查已生成的包可用 `node test/check-package-privacy.js ./new-erp-mcp-0.2.2.tgz`；检查结果只输出文件、行号和类别，不输出匹配到的敏感值。
+`.tgz` 可通过 `npm install -g ./new-erp-mcp-0.3.0.tgz` 安装。发布文件不包含本机会话、项目配置、业务导出或测试数据。使用 `node test/check-package-privacy.js ./new-erp-mcp-0.3.0.tgz` 检查实际归档；检查只报告文件、行号和类别，不输出敏感值。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "new-erp-mcp",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "CLI and local MCP tools for querying new-erp products, images and inventory",
   "publishConfig": {
     "access": "public",

package/scripts/catalog-list.js

@@ -118,7 +118,7 @@ async function main(argsValue) {
   return filtered.map((row) => outputRow(row, Boolean(argsValue.raw)));
 }
 
-module.exports = { main };
+module.exports = { main, args };
 
 if (require.main === module) {
   runCli({

package/scripts/category-summary.js

@@ -153,7 +153,7 @@ async function main(argsValue) {
     }));
 }
 
-module.exports = { main };
+module.exports = { main, args };
 
 if (require.main === module) {
   runCli({

package/scripts/erp-options.js

@@ -19,5 +19,5 @@ async function main(options = {}) {
   return { data, source };
 }
 
-module.exports = { main };
+module.exports = { main, args };
 if (require.main === module) runCli({ name: 'options', description: '读取ERP实时仓库、状态等枚举，不推断业务状态含义。', args, func: main });

package/scripts/game-product-batch.js

@@ -123,7 +123,7 @@ async function main(argsValue) {
   return outputRows;
 }
 
-module.exports = { main };
+module.exports = { main, args };
 
 if (require.main === module) {
   runCli({

package/scripts/game-product-list.js

@@ -106,7 +106,7 @@ async function main(argsValue) {
   return rows.map((row) => productRow(row, meta, Boolean(argsValue.raw)));
 }
 
-module.exports = { main };
+module.exports = { main, args };
 
 if (require.main === module) {
   runCli({

package/scripts/inventory-list.js

@@ -23,5 +23,5 @@ async function main(options = {}) {
   return result;
 }
 
-module.exports = { main };
+module.exports = { main, args };
 if (require.main === module) runCli({ name: 'inventory-list', description: '读取国内仓即时、占用、在途和预计可用库存；预计可用不等于已签收可装箱。', args, func: main });

package/scripts/login-browser.js

@@ -0,0 +1,185 @@
+const http = require('node:http');
+const { randomBytes } = require('node:crypto');
+const { spawn } = require('node:child_process');
+const { CommandExecutionError, loginToken, normalizeBaseUrl, requiredString, withErpContext } = require('./shared.js');
+const { saveSession } = require('./local-session.js');
+
+const BODY_LIMIT = 16 * 1024;
+
+function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (character) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  })[character]);
+}
+
+function page({ route, csrf, defaults, error, complete = false }) {
+  const hidden = `<input type="hidden" name="csrf" value="${csrf}">`;
+  return `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${complete ? '登录成功' : 'ERP 登录'}</title>
+<style>
+*{box-sizing:border-box}body{margin:0;color:#152c29;background:#f4f7f5;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC",sans-serif;min-height:100vh;display:grid;place-items:center;padding:40px 20px;background-image:radial-gradient(ellipse at 15% 0%,#e5f0e9,transparent 50%)}
+main{width:100%;max-width:480px}.brand{display:flex;align-items:center;gap:10px;font-size:15px;font-weight:700;margin:0 0 26px 4px}.mark{background:#164e41;color:white;border-radius:11px;padding:10px;font-size:13px;letter-spacing:1px}
+.card{background:#fff;border:1px solid #e0e8e3;border-radius:22px;padding:36px;box-shadow:0 18px 55px #193d2710}h1{font-size:28px;letter-spacing:-.7px;margin:0 0 26px;font-weight:650}.intro{font-size:14px;line-height:1.8;color:#718078;margin:0}
+label{display:block;font-size:13px;font-weight:600;margin:22px 0 9px}input{display:block;width:100%;border:1px solid #d9e2dc;border-radius:10px;padding:13px 14px;font-size:15px;color:#203a30;background:#fbfcfb;outline:none;transition:border-color .15s,box-shadow .15s}input:focus{border-color:#3c8068;box-shadow:0 0 0 3px #3c806815}input::placeholder{color:#a4b0a9}
+button{font:inherit;cursor:pointer}.primary{margin-top:28px;width:100%;border:0;background:#205e4c;color:white;font-size:14px;font-weight:600;border-radius:10px;padding:15px;transition:background .15s}.primary:hover{background:#164a3b}.privacy{margin:22px 0 0;padding:15px 0 0;border-top:1px solid #edf0ed;font-size:12px;color:#7b8981;line-height:1.8}.cancel{text-align:center;margin-top:15px}.cancel button{border:0;background:none;color:#87968b;font-size:12px;padding:8px}.error{color:#a93a32;background:#fff3f1;border:1px solid #f3ded9;padding:12px;border-radius:9px;font-size:13px;line-height:1.6}.success{display:grid;place-items:center;width:48px;height:48px;background:#e8f3ec;color:#2c7051;border-radius:50%;font-size:25px;margin-bottom:22px}.foot{text-align:center;color:#99a59e;font-size:11px;margin:24px 0 0;letter-spacing:.4px}@media(max-width:520px){body{padding:24px 16px}.card{padding:28px 24px;border-radius:18px}h1{font-size:26px}}
+</style></head><body><main><div class="brand"><span class="mark">ERP</span>New ERP</div>
+<section class="card">${complete ? '<div class="success">✓</div><h1>登录成功</h1><p class="intro">配置已保存，可以关闭此页面，返回对话继续查询。</p>' : `
+<h1>ERP 登录</h1>
+${error ? `<p class="error" role="alert">${escapeHtml(error)}</p>` : ''}
+<form method="post" action="${route}" autocomplete="on">${hidden}
+<label for="baseUrl">ERP 网址</label><input id="baseUrl" name="baseUrl" type="url" value="${escapeHtml(defaults.baseUrl)}" placeholder="https://your-erp.example.com" required autocomplete="url" spellcheck="false">
+<label for="username">账号</label><input id="username" name="username" value="${escapeHtml(defaults.username)}" placeholder="输入 ERP 账号" required autocomplete="username">
+<label for="password">密码</label><input id="password" name="password" type="password" placeholder="输入 ERP 密码" required autocomplete="current-password">
+<button class="primary" type="submit">登录</button></form>
+<p class="privacy">密码不进入 AI 对话；仅保存本机会话，不保存密码。</p>`}</section>
+${complete ? '' : `<form class="cancel" method="post" action="${route}/cancel">${hidden}<button type="submit">取消登录</button></form>`}
+${complete ? '' : '<p class="foot">本次登录页面将在 5 分钟后失效</p>'}</main></body></html>`;
+}
+
+function openLocalBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32.exe' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.once('error', reject);
+    child.once('spawn', () => { child.unref(); resolve(); });
+  });
+}
+
+function readBody(request) {
+  return new Promise((resolve, reject) => {
+    let length = 0;
+    const chunks = [];
+    request.on('data', (chunk) => {
+      length += chunk.length;
+      if (length > BODY_LIMIT) {
+        chunks.length = 0;
+        reject(new Error('body-too-large'));
+      } else chunks.push(chunk);
+    });
+    request.once('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    request.once('error', reject);
+    request.once('aborted', () => reject(new Error('request-aborted')));
+  });
+}
+
+async function runBrowserLogin({ defaults = {}, openBrowser = openLocalBrowser,
+  onReady = (url) => process.stderr.write(`请在浏览器中完成 ERP 登录：${url}\n`),
+  signal, timeoutMs = 300_000 } = {}) {
+  if (signal?.aborted) throw new CommandExecutionError('网页登录已取消');
+  const route = `/login/${randomBytes(24).toString('hex')}`;
+  const csrf = randomBytes(24).toString('hex');
+  const shutdown = new AbortController();
+  const deadline = Date.now() + timeoutMs;
+  let phase = 'ready';
+  let origin;
+  let timer;
+  let drain;
+  let committed;
+
+  return new Promise((resolve, reject) => {
+    function finish(error) {
+      if (phase === 'settled') return;
+      if (committed) error = undefined;
+      phase = 'settled';
+      clearTimeout(timer);
+      clearTimeout(drain);
+      signal?.removeEventListener('abort', cancel);
+      process.removeListener('SIGINT', cancel);
+      process.removeListener('SIGTERM', cancel);
+      shutdown.abort();
+      server.close(() => error ? reject(error) : resolve(committed));
+      server.closeAllConnections();
+    }
+    function cancel() { finish(new CommandExecutionError('网页登录已取消')); }
+    function respond(response, status, html) {
+      response.writeHead(status, {
+        'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store',
+        'Referrer-Policy': 'no-referrer', 'X-Content-Type-Options': 'nosniff',
+        'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'",
+        Connection: 'close',
+      });
+      response.end(html);
+    }
+    function endRun(response, status, html, error) {
+      phase = committed ? 'committed' : 'closing';
+      clearTimeout(timer);
+      drain = setTimeout(() => finish(error), 250);
+      response.once('finish', () => finish(error));
+      respond(response, status, html);
+    }
+    const render = (values, error, complete) => page({ route, csrf, defaults: values, error, complete });
+    async function handle(request, response) {
+      const rejectRequest = (status) => respond(response, status, '请求无效，请重新打开登录链接。');
+      if (request.headers.host !== new URL(origin).host) return rejectRequest(403);
+      if (request.url !== route && request.url !== `${route}/cancel`) return rejectRequest(404);
+      if (request.method === 'GET' && request.url === route) return respond(response, 200, render(defaults));
+      if (request.method !== 'POST') return rejectRequest(405);
+      if (request.headers.origin !== origin || request.headers['sec-fetch-site'] === 'cross-site') return rejectRequest(403);
+      if (request.headers['content-type']?.split(';')[0].trim() !== 'application/x-www-form-urlencoded') return rejectRequest(415);
+      const canceling = request.url === `${route}/cancel`;
+      if (phase !== 'ready' && !(canceling && phase === 'authenticating')) return rejectRequest(409);
+      let body;
+      try { body = await readBody(request); } catch { return rejectRequest(413); }
+      if (phase !== 'ready' && !(canceling && phase === 'authenticating')) return rejectRequest(409);
+      if (/%(?![a-f0-9]{2})/i.test(body)) return rejectRequest(400);
+      const fields = new URLSearchParams(body);
+      if ([...fields.keys()].some((key) => !['csrf', 'baseUrl', 'username', 'password'].includes(key) || fields.getAll(key).length !== 1)) return rejectRequest(400);
+      if (fields.get('csrf') !== csrf) return rejectRequest(403);
+      if (canceling) {
+        shutdown.abort();
+        return endRun(response, 200, '登录已取消，可以关闭此页面。', new CommandExecutionError('网页登录已取消'));
+      }
+      let baseUrl, username, password;
+      try {
+        baseUrl = normalizeBaseUrl(fields.get('baseUrl'));
+        username = requiredString(fields.get('username'), 'username');
+        password = requiredString(fields.get('password'), 'password');
+      } catch { return respond(response, 400, render(defaults, '请填写有效的 ERP 网址、账号和密码。')); }
+      phase = 'authenticating';
+      let session;
+      try {
+        session = await withErpContext({ baseUrl }, () => loginToken({ username, password, signal: shutdown.signal }));
+      } catch {
+        if (phase !== 'authenticating') return;
+        phase = 'ready';
+        return respond(response, 401, render({ baseUrl, username }, '登录失败，请检查 ERP 地址、账号和密码后重试。'));
+      }
+      if (phase !== 'authenticating' || shutdown.signal.aborted || Date.now() >= deadline) return;
+      let sessionFile;
+      try { sessionFile = saveSession({ baseUrl, ...session }); } catch {
+        return endRun(response, 500, render({ baseUrl, username }, '无法保存本机登录会话，请重新启动登录。'),
+          new CommandExecutionError('无法保存本机登录会话'));
+      }
+      committed = { baseUrl, username: session.username, userId: session.userId,
+        expireTime: session.expireTime, sessionFile, loggedIn: true };
+      endRun(response, 200, render({}, undefined, true));
+    }
+    const server = http.createServer((request, response) => {
+      void handle(request, response).catch(() => {
+        if (!response.headersSent) respond(response, 500, '登录服务暂不可用，请重新启动登录。');
+        finish(new CommandExecutionError('网页登录服务异常，请重新运行登录命令'));
+      });
+    });
+    server.requestTimeout = 15_000;
+    server.headersTimeout = 10_000;
+    server.maxConnections = 8;
+    server.once('error', () => finish(new CommandExecutionError('无法启动本机登录页面')));
+    signal?.addEventListener('abort', cancel, { once: true });
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    timer = setTimeout(() => finish(new CommandExecutionError('登录页面已过期，请重新运行 new-erp login --browser')), timeoutMs);
+    server.listen(0, '127.0.0.1', () => {
+      if (phase === 'settled') return;
+      origin = `http://127.0.0.1:${server.address().port}`;
+      const url = `${origin}${route}`;
+      try { onReady(url); } catch { return finish(new CommandExecutionError('无法显示登录链接')); }
+      if (openBrowser && phase !== 'settled') Promise.resolve().then(() => openBrowser(url)).catch(() => {
+        if (phase !== 'settled') process.stderr.write('无法自动打开浏览器，请手动打开上面的本机登录链接。\n');
+      });
+    });
+  });
+}
+
+module.exports = { runBrowserLogin };

package/scripts/login.js

@@ -3,7 +3,7 @@ const readline = require('node:readline/promises');
 const { Writable } = require('node:stream');
 const { ArgumentError, getBaseUrl, loginToken, normalizeBaseUrl, requiredString, runCli,
   withErpContext } = require('./shared.js');
-const { saveSession } = require('./local-session.js');
+const { saveSession, readSession } = require('./local-session.js');
 
 async function promptCredentials(username) {
   if (!process.stdin.isTTY || !process.stderr.isTTY) {
@@ -29,7 +29,30 @@ async function promptCredentials(username) {
 }
 
 async function main(options = {}) {
-  const baseUrl = options.baseUrl ? normalizeBaseUrl(options.baseUrl) : getBaseUrl();
+  if (options.browser) {
+    let baseUrl = '';
+    try { baseUrl = normalizeBaseUrl(options.baseUrl || getBaseUrl()); } catch {}
+    let username = options.username || process.env.NEW_ERP_USERNAME || '';
+    if (!username) try { username = readSession()?.username || ''; } catch {}
+    const { runBrowserLogin } = require('./login-browser.js');
+    return runBrowserLogin({ defaults: { baseUrl, username },
+    ...(options.open === false ? { openBrowser: false } : {}) });
+  }
+  let baseUrl;
+  try {
+    baseUrl = options.baseUrl ? normalizeBaseUrl(options.baseUrl) : getBaseUrl();
+  } catch (error) {
+    if (!(error instanceof ArgumentError) || error.message !== 'NEW_ERP_BASE_URL is required') throw error;
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+      throw new ArgumentError('首次登录需要 ERP 地址。请运行 new-erp login --baseUrl <ERP_URL>，或配置 NEW_ERP_BASE_URL；密码使用客户端私密输入或在自己的终端隐藏输入。');
+    }
+    const terminal = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+      baseUrl = normalizeBaseUrl(await terminal.question('ERP 地址: '));
+    } finally {
+      terminal.close();
+    }
+  }
   let username = String(options.username || process.env.NEW_ERP_USERNAME || '').trim();
   let password = process.env.NEW_ERP_PASSWORD;
   if (!password) ({ username, password } = await promptCredentials(username));
@@ -44,6 +67,8 @@ async function main(options = {}) {
 module.exports = { main };
 if (require.main === module) runCli({ name: 'login', description: '登录自己的 ERP 账号，仅在本机保存 token，不保存密码。',
   args: [
-    { name: 'baseUrl', type: 'string', help: 'ERP 地址；首次登录必填，也可配置 NEW_ERP_BASE_URL' },
+    { name: 'browser', type: 'bool', default: false, help: '打开本机临时网页，一次填写 ERP 网址、账号和密码' },
+    { name: 'open', type: 'bool', default: true, help: '浏览器模式自动打开页面；设为 false 时只显示登录链接' },
+    { name: 'baseUrl', type: 'string', help: 'ERP 地址；首次登录未配置时在终端提示输入，也可配置 NEW_ERP_BASE_URL' },
     { name: 'username', type: 'string', help: 'ERP 账号；留空时交互输入，也可用 NEW_ERP_USERNAME' },
   ], func: main });

package/scripts/logistics-channel-list.js

@@ -6,5 +6,5 @@ async function main(options = {}) {
   return queryList('/logistics/initial-channel/index', {}, options);
 }
 
-module.exports = { main };
+module.exports = { main, args: listArgs };
 if (require.main === module) runCli({ name: 'logistics-channel-list', description: '查询头程物流渠道、运输方式和材积除数原始配置。', args: listArgs, func: main });

package/scripts/market-order-list.js

@@ -31,7 +31,7 @@ async function main(options = {}) {
   });
 }
 
-module.exports = { main };
+module.exports = { main, args };
 if (require.main === module) {
   runCli({ name: 'market-order-list', description: '只读市场订单列表，保留订单、SKU、物流及实时枚举原字段；支持分页与 fetchAll。', args, func: main });
 }