tju-llm-dsh 1.0.0 → 1.0.2

package/FAQ.md

@@ -2,6 +2,16 @@
 
 ## 配置写入
 
+### Q: 我完全没用过 dsh，怎么开始？
+
+先装 DeepSeek Harness（官方开源项目）：
+
+1. 装 Node.js ≥ 18（[nodejs.org](https://nodejs.org/) 下载 LTS，Windows 可 `winget install OpenJS.NodeJS.LTS`）；
+2. `npm install -g @deepseek-ai/dsh`；
+3. 终端跑 `dsh web`——首次运行自动初始化 profile 并生成 `~/.dsh/` 目录，按输出地址打开浏览器（一般是 `http://127.0.0.1:3080`）确认能访问。
+
+然后回来照 README「三步接入」走即可。用 DeepSeek 桌面版的话，`desktop` profile 同样被本工具支持。
+
 ### Q: 工具到底改了哪两个文件？
 
 1. `~/.dsh/profiles/<profile>/cordis.patch.yml` — 顶层补丁数组中加入/合并 `llm-pi-ai` 插件条目，provider 名为 `tju`。
@@ -24,9 +34,18 @@
 
 ## 连通与使用
 
+### Q: 怎么获取 API Key？
+
+两步（依据[信息与网络中心推文](https://mp.weixin.qq.com/s/iNoT0yAlxM0iv9NjJ15s6Q)）：
+
+1. **申请开通**：登录融合门户 → 网上办事大厅 → 检索「Token」或「大模型」→ 填写《本地大模型免费 Token 服务开通申请表》提交，**系统自动开通 API 访问权限**；
+2. **获取 Key**：登录[智能体广场](https://ai.tju.edu.cn)，获取 `tk-` 开头的个人 API Key，同页可查用量、管理密钥。
+
+注意：仅限校园网访问；额度每人每月上行 10 亿 / 下行 1000 万词元；Key 不得转借或公开发布；咨询 022-27404455。
+
 ### Q: verify 报「Prompt token limit exceeded」？
 
-这是**账户层面**的额度限制，与请求大小无关（一个 "hi" 也会报）。通常是免费额度用尽或账户受限。去 [ai.tju.edu.cn](https://ai.tju.edu.cn) 查看用量，或换一个 Key。
+这是**账户层面**的额度限制，与请求大小无关（一个 "hi" 也会报）。通常是额度用尽、账户受限，或**服务未开通**（先按上一条走开通流程）。去 [ai.tju.edu.cn](https://ai.tju.edu.cn) 查看用量，或换一个 Key。
 
 ### Q: verify 报 429？
 

package/README.md

@@ -14,11 +14,47 @@
 - **数据不出校**：请求直接发往校内网关，不经过第三方
 - **模型新**：DeepSeek / Qwen 系列最新模型，最高 512K 上下文
 
+## 从零开始：先装 DeepSeek Harness（没用过 dsh？看这里）
+
+dsh 是 DeepSeek 官方的开源 agent 入口（[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)）。从未接触过的话，三步装好：
+
+1. **装 Node.js ≥ 18**（还没有的话）：去 [nodejs.org](https://nodejs.org/) 下载 LTS 版安装，Windows 也可以在 PowerShell 里执行 `winget install OpenJS.NodeJS.LTS`。装完在终端跑 `node --version` 能看到版本号即可。
+2. **装 dsh**：
+
+   ```powershell
+   npm install -g @deepseek-ai/dsh
+   ```
+
+3. **跑一次**：
+
+   ```powershell
+   dsh web
+   ```
+
+   首次运行会自动初始化 Web profile 并生成 `~/.dsh/` 配置目录（Windows 即 `%USERPROFILE%\.dsh`）；按终端输出的本地地址打开浏览器即可使用（一般是 `http://127.0.0.1:3080`）。确认页面能打开后 Ctrl+C 停掉，回到下面的接入步骤。
+
+> 用 DeepSeek 桌面版的同学：它使用的 `desktop` profile 本工具同样支持，装好本工具直接配置即可。
+
 ## 前置条件
 
 1. **Node.js ≥ 18**（dsh 用户天然满足）
-2. **已安装并运行过一次 dsh**（`npm i -g @deepseek-ai/dsh`，跑一次让它生成 `~/.dsh/profiles/`）
-3. **天大智算 API Key**（`tk-` 开头，在 [ai.tju.edu.cn](https://ai.tju.edu.cn) 个人设置里生成）
+2. **已安装并运行过一次 dsh**（没装过？照上一节《从零开始》三步即可）
+3. **天大智算 API Key**（`tk-` 开头）——需要先申请开通服务，见[下一节](#如何获取-api-key)
+
+## 如何获取 API Key（两步）
+
+> 依据信息与网络中心推文[《学校智能体广场上新"词元（Token）"API服务》](https://mp.weixin.qq.com/s/iNoT0yAlxM0iv9NjJ15s6Q)（2026-05）。
+
+**第 1 步 · 申请开通（没有这一步就没有额度）**：登录融合门户 → **网上办事大厅** → 检索「**Token**」或「**大模型**」→ 填写《本地大模型免费 Token 服务开通申请表》并提交。**提交后系统自动开通 API 访问权限。**
+
+**第 2 步 · 获取 Key**：登录[**智能体广场**](https://ai.tju.edu.cn)，获取个人 API Key（`tk-` 开头）；同一页面可查询用量、管理密钥。
+
+注意事项：
+
+- 服务仅限**校园网络环境**内访问；
+- 密钥须妥善保管，**不得转借、不得发布于公开平台**；
+- 词元额度按月统计：每人每月**上行 10 亿、下行 1000 万**；
+- 遇到问题可咨询信息与网络中心：**022-27404455**。
 
 ## 三步接入
 

package/SKILL.md

@@ -23,17 +23,23 @@ cd <安装目录> && npm install --omit=dev
 # 之后用 node bin/tju-dsh.mjs 代替 tju-dsh
 ```
 
-前置检查：`node --version`（需 ≥ 18）；目录 `~/.dsh/profiles/` 是否存在
-（Windows 为 `%USERPROFILE%\.dsh\profiles`）。不存在就先让用户安装并运行一次
-`dsh`（`npm i -g @deepseek-ai/dsh`），没有 dsh 就没有配置目标。
+前置检查：`node --version`（需 ≥ 18，没有就去 nodejs.org 装 LTS 或 `winget install OpenJS.NodeJS.LTS`）；目录 `~/.dsh/profiles/` 是否存在
+（Windows 为 `%USERPROFILE%\.dsh\profiles`）。不存在就让用户装 dsh 并跑一次：
+`npm install -g @deepseek-ai/dsh` 然后 `dsh web`（首次运行自动生成 `~/.dsh/profiles/`，
+按输出地址打开浏览器确认能访问）。没有 dsh 就没有配置目标。
 
 ## 对话脚本（按顺序，不要跳步）
 
 ### 1. 问用户要 Key（唯一必须问的）
 
-> 「请把天大智算的 API Key 发给我（tk- 开头，在 https://ai.tju.edu.cn 个人设置里生成）」
+先确认用户**是否已开通服务**——Key 不是上来就能生成的，依据信息与网络中心推文（[原文](https://mp.weixin.qq.com/s/iNoT0yAlxM0iv9NjJ15s6Q)）需要两步：
 
-用户没有 Key → 引导去上面网址生成，等用户拿到再继续。
+1. **申请开通**：融合门户 → **网上办事大厅** → 检索「Token」或「大模型」→ 填《本地大模型免费 Token 服务开通申请表》提交，**系统自动开通**；
+2. **获取 Key**：登录[**智能体广场**](https://ai.tju.edu.cn)获取 `tk-` 开头的个人 API Key（同页可查用量）。
+
+> 话术：「天大智算的 Key 需要先开通服务：登录融合门户→网上办事大厅→搜『Token』提交开通申请（自动生效），然后到 ai.tju.edu.cn（智能体广场）拿你的 tk- 开头 Key 发给我。」
+
+用户没有 Key → 按上面话术引导，等拿到再继续。额度规则（可顺带告知）：每人每月上行 10 亿 / 下行 1000 万词元；仅限校园网访问；咨询 022-27404455。
 
 ### 2. profile（多数情况不用问）
 
@@ -78,7 +84,7 @@ tju-dsh verify --model <用户最关心的那个模型，缺省 tju-llm>
 
 | 现象 | 原因与话术 |
 |---|---|
-| HTTP 429 且 body 含 `Prompt token limit exceeded` | **账户额度用尽/受限**，与请求大小无关。让用户上 ai.tju.edu.cn 查用量或换 Key |
+| HTTP 429 且 body 含 `Prompt token limit exceeded` | **账户额度用尽/受限，或服务根本没开通**（要先去网上办事大厅申请）。让用户上 ai.tju.edu.cn 查用量 |
 | 纯 429 | 限流 60 次/分钟，等几秒重试 |
 | 401/403 | Key 无效或过期 → `remove` 后用新 Key 重配 |
 | `model not found` | 模型名大小写错了（只认小写）或已下线 → `tju-dsh models` 看列表 |

package/bin/tju-dsh.mjs

@@ -193,7 +193,7 @@ async function pickProfile(opts, p) {
     return opts.profile;
   }
   if (profiles.length === 0) {
-    die('没有找到任何 dsh profile。请先安装并运行一次 dsh（它会生成 ~/.dsh/profiles/），再运行本工具。');
+    die('没有找到任何 dsh profile。请先运行一次 dsh web（首次运行会自动生成 ~/.dsh/profiles/），再运行本工具。');
   }
   if (profiles.length === 1) {
     info(`使用唯一的 profile：${profiles[0]}`);
@@ -458,7 +458,7 @@ async function cmdSetup(opts) {
   console.log(c.cyan('\n== tju-dsh：把天津大学智算平台接入 DeepSeek Harness ==\n'));
 
   if (!existsSync(p.dshDir)) {
-    die(`未找到 ${p.dshDir}。请先安装并运行一次 dsh（npm i -g @deepseek-ai/dsh 后执行 dsh），再运行本工具。`);
+    die(`未找到 ${p.dshDir}。若从未用过 dsh：先装 Node.js ≥ 18（nodejs.org），再执行 npm install -g @deepseek-ai/dsh，然后运行一次 dsh web（自动生成配置目录），最后重新运行本工具。`);
   }
 
   const profile = await pickProfile(opts, p);
@@ -506,7 +506,7 @@ async function cmdSetup(opts) {
     ok(`已存在 ${ENV_KEY}，保持不变（如需更换：tju-dsh remove 后重新配置，或直接编辑 ${p.credsFile}）`);
   } else if (!key) {
     console.log('');
-    console.log(`请粘贴天大智算的 API Key（tk- 开头，在 https://ai.tju.edu.cn 个人设置里生成；输入不回显）`);
+    console.log(`请粘贴天大智算的 API Key（tk- 开头；需先在融合门户网上办事大厅申请开通服务，再到智能体广场 ai.tju.edu.cn 获取 Key。输入不回显）`);
     key = await prompt('API Key: ', { hidden: true });
     if (!key) die('API Key 不能为空。');
   }
@@ -543,9 +543,9 @@ async function cmdVerify(opts) {
     if (e.message.includes('\n')) console.log(c.dim(e.message.split('\n').slice(1).join('\n')));
     console.log('');
     if (e.status === 401 || e.status === 403) {
-      info('多为 API Key 无效/过期。去 https://ai.tju.edu.cn 重新生成，然后 tju-dsh remove && tju-dsh 重配。');
+      info('多为 API Key 无效/过期，或服务未开通（需先在融合门户网上办事大厅申请）。去 https://ai.tju.edu.cn 重新生成，然后 tju-dsh remove && tju-dsh 重配。');
     } else if (/Prompt token limit/i.test(e.body || '')) {
-      info('网关返回「Prompt token limit exceeded」：通常是账户额度用尽或受限（与请求本身无关）。去 https://ai.tju.edu.cn 查看用量，或换一个 Key 试。');
+      info('网关返回「Prompt token limit exceeded」：通常是额度用尽/受限，或服务未开通（网上办事大厅搜「Token」申请）。去 https://ai.tju.edu.cn 查看用量，或换一个 Key 试。');
     } else if (e.status === 404 || /model/i.test(e.message)) {
       info(`模型 ${model} 可能不存在或已下线，运行 tju-dsh models 查看可用列表。`);
     } else if (e.status === 429) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tju-llm-dsh",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "把天津大学智算平台（ai.tju.edu.cn）接入 DeepSeek Harness（dsh）——社区工具，非官方",
   "type": "module",
   "bin": {