pi-glm-quota 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 focksor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# pi-glm-quota
+
+pi coding agent 的 GLM Coding Plan（智谱积分套餐）配额显示扩展。
+
+```
+GLM 5h █░░░░░░░░░ 12% ⏳1h22m · W █████░░░░░ 48% ⏳4d3h
+```
+
+- **5h / W**：5 小时滚动窗口 / 周窗口，各显示用量百分比与重置倒计时
+- 颜色分档：<50% 绿 / 50-79% 黄 / ≥80% 红；数据过期时末尾标 `~`
+- `/glm-quota` 命令查看明细（积分数字、重置时间、套餐档位）
+- `/glm-quota-setup` 命令交互式配置（无需手改文件）
+- 仅当前 provider 为 `zai*`（如 `zai-coding-cn`）时显示，切走自动隐藏
+- 每轮对话后节流刷新（90s）+ 每 5 分钟后台刷新 + 每 30s 本地倒计时重绘
+
+## 为什么需要这个扩展（踩坑记录）
+
+智谱 **2026-07-30 套餐改版**后的积分制套餐（含团队套餐），其用量查询接口
+`/api/monitor/usage/quota/limit` 的调用方式与旧版不同：
+
+| 要素 | 说明 |
+| --- | --- |
+| `Authorization: <API key>` | raw 形式（不带 Bearer），取自 auth.json 的 `zai-coding-cn` key 或 `ZAI_CODING_CN_API_KEY` 环境变量 |
+| `?type=2` | query 参数；实测团队套餐为 2，个人新版疑似为 1（未验证） |
+| `bigmodel-organization: org-xxx` | **组织上下文头，必需** |
+| `bigmodel-project: proj_xxx` | **项目上下文头，必需** |
+
+缺任何一个的表现：
+
+- 缺 `type` → `当前用户不存在coding plan`（所有社区插件都死在这里）
+- 缺 org/project 头 → 返回空 `data:{}`
+
+这就是 `@zhaoji-wang/pi-glm-usage`、`@bacnh85/pi-sub`、`pi-glm-usage`
+等社区插件全部报错的原因——它们只发 API key。
+
+**org/project/type 的获取方法**：浏览器访问 https://bigmodel.cn/coding-plan/ 并登录，
+在 DevTools 的 Network 面板中找到 `api/monitor/usage/quota/limit` 请求：请求头
+`bigmodel-organization` 和 `bigmodel-project` 即 org 与 project；URL query 参数
+`type` 即套餐类型（团队=2，个人=1）。
+（`/glm-quota-setup` 向导首个输入框的标题会展示同样的指引）
+
+## 配置
+
+配置包含三项：`organization`（组织 ID）、`project`（项目 ID）、`type`
+（套餐类型，团队=2 / 个人=1）。三种配置方式，优先级从高到低：
+
+### 方式一：环境变量（临时/CI 场景）
+
+```bash
+export GLM_QUOTA_ORGANIZATION="org-xxxx"
+export GLM_QUOTA_PROJECT="proj_xxxx"
+export GLM_QUOTA_TYPE=2                    # 可选，默认 2
+export GLM_QUOTA_INTERVAL_SECONDS=300      # 可选，刷新间隔（秒）
+```
+
+### 方式二：交互式向导（推荐）
+
+在 pi 中运行：
+
+```
+/glm-quota-setup
+```
+
+依次输入 org、project、type，保存后立即拉取验证。已配置时标题会显示
+当前值，输入框留空提交表示该项保持不变（可只改其中一项）；按 Esc 取消
+则整体中止不写入。
+
+### 方式三：配置文件
+
+复制 `config.example.json` 为 `~/.pi/agent/glm-quota.json` 并填入真实值：
+
+```json
+{
+  "organization": "org-xxxxxxxx",
+  "project": "proj_xxxxxxxxxxxx",
+  "type": 2,
+  "intervalSeconds": 300
+}
+```
+
+> 配置文件含账号上下文标识，请勿提交到公共仓库。
+
+API key 的解析优先级：`ZAI_CODING_CN_API_KEY` 环境变量 >
+`~/.pi/agent/auth.json` 的 `zai-coding-cn` 条目（与 pi 本身的凭证一致）。
+
+## 安装方式
+
+```bash
+pi install npm:pi-glm-quota
+```
+
+用 `pi update --extensions` 更新；`pi remove npm:pi-glm-quota` 卸载。
+
+开发模式（本地路径加载）：在 `~/.pi/agent/settings.json` 的 `extensions`
+数组中加入本目录的绝对路径：
+
+```json
+{
+  "extensions": ["/path/to/pi-glm-quota"]
+}
+```
+
+pi 加载 `package.json` 中 `pi` 清单声明的 `index.ts`，`/reload` 可热重载。
+
+## 文件结构
+
+| 文件 | 职责 |
+| --- | --- |
+| `index.ts` | 扩展入口：事件接线、fetch、状态栏、命令与配置向导 |
+| `pure.ts` | 纯逻辑：配置读取（env/文件）、key 解析、响应归一化、渲染 |
+| `pure.test.ts` | 纯逻辑单测（离线，合成数据），`node pure.test.ts` |
+| `mock.test.ts` | mock pi 上下文的接线测试（真实网络请求），`node mock.test.ts` |
+| `config.example.json` | 配置文件模板 |
+
+## 响应语义备注
+
+`limits[]` 中 `CREDIT_LIMIT` 条目的 `unit` 字段（实测）：
+
+- `unit: 3` → 小时窗口，`number: 5` 即 5 小时滚动窗
+- `unit: 6` → 周窗口，`number: 1` 即 1 周
+
+`percentage` 为已用百分比（0-100）；`usage` 为总额度、`currentValue` 为已用、
+`remaining` 为剩余（积分）；`nextResetTime` 为 epoch 毫秒。
+
+## 已知局限
+
+- 直接读服务端百分比，不受各模型积分系数差异影响
+- 套餐类型变更（团队 ↔ 个人）需同步更新 `type` 与 org/project

package/config.example.json

@@ -0,0 +1,6 @@
+{
+  "organization": "org-xxxxxxxxxxxxxxxx",
+  "project": "proj_xxxxxxxxxxxxxxxxxxxx",
+  "type": 2,
+  "intervalSeconds": 300
+}

package/index.ts

@@ -0,0 +1,241 @@
+/**
+ * GLM Coding Plan（智谱积分套餐）配额显示扩展 — 入口
+ *
+ * 适用场景：智谱 2026-07-30 改版后的新版积分套餐（含团队套餐）。
+ * 这类套餐的用量查询接口需要携带组织/项目上下文头，社区插件均未支持，
+ * 因此本扩展直接按实测配方调用官方 monitor 端点：
+ *
+ *   GET https://bigmodel.cn/api/monitor/usage/quota/limit?type=<type>
+ *   Authorization: <API key>          （auth.json 的 zai-coding-cn key，raw 形式）
+ *   bigmodel-organization: <org id>   （组织上下文）
+ *   bigmodel-project: <project id>    （项目上下文）
+ *
+ * 配置（三选一，优先级从高到低）：
+ *   1. 环境变量 GLM_QUOTA_ORGANIZATION / GLM_QUOTA_PROJECT / GLM_QUOTA_TYPE
+ *   2. ~/.pi/agent/glm-quota.json（可用 /glm-quota-setup 向导生成）
+ *   3. 均未配置时状态栏提示运行向导
+ *
+ * 显示：footer 状态栏，如  GLM 5h ██░░░░░░░░ 10% ⏳1h5m · W █████░░░░░ 48% ⏳4d3h
+ * 命令：/glm-quota 查看明细；/glm-quota-setup 交互式配置
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	loadConfig,
+	renderFooter,
+	renderReport,
+	resolveApiKey,
+	saveConfig,
+	QUOTA_URL,
+	classifyLimits,
+	type GlmQuotaConfig,
+	type QuotaResponse,
+	type Snapshot,
+} from "./pure.ts";
+
+/** 状态栏槽位标识 */
+const STATUS_KEY = "glm-quota";
+/** 拉取超时（毫秒） */
+const FETCH_TIMEOUT_MS = 8000;
+/** 默认后台刷新间隔（秒） */
+const DEFAULT_INTERVAL_S = 300;
+/** 对话后触发刷新的最小间隔（毫秒），避免高频请求 */
+const AFTER_TURN_THROTTLE_MS = 90_000;
+/** 倒计时本地重绘间隔（毫秒），不发起网络请求 */
+const TICK_MS = 30_000;
+
+type Ui = ExtensionContext["ui"];
+
+/** 拉取配额快照 */
+async function fetchQuota(org: string, project: string, typeQ: number, key: string): Promise<Snapshot> {
+	const res = await fetch(`${QUOTA_URL}?type=${typeQ}`, {
+		headers: {
+			accept: "application/json",
+			authorization: key,
+			"bigmodel-organization": org,
+			"bigmodel-project": project,
+		},
+		signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+	});
+	const body = (await res.json()) as QuotaResponse;
+	if (!res.ok || !body.success || !body.data) {
+		throw new Error(`quota API error: HTTP ${res.status} ${body.msg ?? ""}`.trim());
+	}
+	const windows = classifyLimits(body.data.limits ?? []);
+	if (windows.length === 0) throw new Error("quota API returned no CREDIT_LIMIT windows");
+	return { windows, level: body.data.level ?? "?", fetchedAt: Date.now() };
+}
+
+export default function (pi: ExtensionAPI) {
+	let snapshot: Snapshot | null = null;
+	let stale = false;
+	let lastFetchAt = 0;
+	let inFlight = false;
+	let fetchTimer: ReturnType<typeof setInterval> | undefined;
+	let tickTimer: ReturnType<typeof setInterval> | undefined;
+	let currentProviderIsGlm = false;
+
+	const paint = (ui: Ui) => {
+		if (!currentProviderIsGlm || !snapshot) return;
+		ui.setStatus(STATUS_KEY, renderFooter(snapshot, stale, (c, s) => ui.theme.fg(c, s)));
+	};
+
+	/** 刷新配额；失败时保留旧值并标记 stale */
+	const refresh = async (ui: Ui, force = false) => {
+		if (inFlight) return;
+		const now = Date.now();
+		if (!force && now - lastFetchAt < AFTER_TURN_THROTTLE_MS) return;
+		const cfg = loadConfig();
+		const key = resolveApiKey();
+		if (!cfg || !key) {
+			ui.setStatus(STATUS_KEY, ui.theme.fg("dim", "GLM quota: 未配置，运行 /glm-quota-setup 向导"));
+			return;
+		}
+		inFlight = true;
+		try {
+			snapshot = await fetchQuota(cfg.organization, cfg.project, cfg.type, key);
+			stale = false;
+			lastFetchAt = Date.now();
+			paint(ui);
+		} catch (err) {
+			stale = true;
+			if (!snapshot) {
+				const msg = err instanceof Error ? err.message : String(err);
+				ui.setStatus(STATUS_KEY, ui.theme.fg("error", `GLM quota: ${msg.slice(0, 60)}`));
+			} else {
+				paint(ui);
+			}
+		} finally {
+			inFlight = false;
+		}
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		// 无界面模式不启动刷新循环，避免无谓的网络请求
+		if (ctx.mode === "print" || ctx.mode === "json") return;
+		currentProviderIsGlm = (ctx.model?.provider ?? "").startsWith("zai");
+		const interval = (loadConfig()?.intervalSeconds ?? DEFAULT_INTERVAL_S) * 1000;
+		await refresh(ctx.ui, true);
+		fetchTimer = setInterval(() => void refresh(ctx.ui), interval);
+		tickTimer = setInterval(() => paint(ctx.ui), TICK_MS);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		if (fetchTimer) clearInterval(fetchTimer);
+		if (tickTimer) clearInterval(tickTimer);
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+	});
+
+	// 模型切换：非 GLM provider 清除状态，GLM provider 触发刷新
+	pi.on("model_select", async (event, ctx) => {
+		currentProviderIsGlm = event.model.provider.startsWith("zai");
+		if (!currentProviderIsGlm) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
+		await refresh(ctx.ui, true);
+	});
+
+	// 每轮对话结束后节流刷新
+	pi.on("agent_end", async (_event, ctx) => {
+		if (!currentProviderIsGlm) return;
+		await refresh(ctx.ui);
+	});
+
+	pi.registerCommand("glm-quota", {
+		description: "查看 GLM Coding Plan 积分配额明细",
+		handler: async (_args, ctx) => {
+			const cfg = loadConfig();
+			if (!cfg) {
+				ctx.ui.notify(
+					"未配置组织/项目上下文。运行 /glm-quota-setup 向导配置，\n" +
+						"或设置环境变量 GLM_QUOTA_ORGANIZATION / GLM_QUOTA_PROJECT，\n" +
+						"或编辑 ~/.pi/agent/glm-quota.json（格式见项目内 config.example.json）",
+					"error",
+				);
+				return;
+			}
+			await refresh(ctx.ui, true);
+			if (!snapshot) {
+				ctx.ui.notify("GLM quota: 暂无数据（拉取失败，稍后自动重试）", "error");
+				return;
+			}
+			ctx.ui.notify(renderReport(snapshot, stale), "info");
+		},
+	});
+
+	pi.registerCommand("glm-quota-setup", {
+		description: "配置 GLM 配额查询的组织/项目上下文（交互式向导，已配置项留空保持不变）",
+		handler: async (_args, ctx) => {
+			const current = loadConfig();
+			// 帮助文案嵌入首个输入框标题（多行渲染），随弹窗持久可见；
+			// 不用 notify —— 阻塞式输入弹窗会立即盖住聊天区 toast
+			const help =
+				"获取 org/project/type：浏览器访问 https://bigmodel.cn/coding-plan/ 并登录，\n" +
+				"在 DevTools Network 中找到 api/monitor/usage/quota/limit 请求，\n" +
+				"请求头 bigmodel-organization / bigmodel-project 即 org 与 project，\n" +
+				"URL query 参数 type 即套餐类型（团队=2，个人=1）\n\n";
+			// 已配置时标题展示当前值，输入留空表示保持不变；取消（Esc）则整体中止
+			const org = await ctx.ui.input(
+				help +
+					(current
+						? `bigmodel-organization（当前：${current.organization}，留空保持不变）`
+						: "bigmodel-organization（组织 ID，org- 开头，必填）"),
+				current?.organization ?? "org-xxxxxxxx",
+			);
+			if (org === undefined) return;
+			const project = await ctx.ui.input(
+				current
+					? `bigmodel-project（当前：${current.project}，留空保持不变）`
+					: "bigmodel-project（项目 ID，proj_ 开头，必填）",
+				current?.project ?? "proj_xxxxxxxx",
+			);
+			if (project === undefined) return;
+			const typeRaw = await ctx.ui.input(
+				current
+					? `套餐类型 type（当前：${current.type}；团队=2，个人=1，留空保持不变）`
+					: "套餐类型 type（团队套餐=2，个人套餐=1，回车默认 2）",
+				current ? String(current.type) : "2",
+			);
+			if (typeRaw === undefined) return;
+
+			// 合并：留空取现值
+			const organization = org.trim() || current?.organization || "";
+			const projectVal = project.trim() || current?.project || "";
+			if (!organization || !projectVal) {
+				ctx.ui.notify("org 与 project 均为必填，本次未保存。重新运行 /glm-quota-setup", "error");
+				return;
+			}
+			const type = typeRaw.trim() && /^\d+$/.test(typeRaw.trim()) ? Number(typeRaw.trim()) : current?.type ?? 2;
+
+			const changed =
+				!current ||
+				current.organization !== organization ||
+				current.project !== projectVal ||
+				current.type !== type;
+			if (!changed) {
+				ctx.ui.notify("配置未变化", "info");
+				return;
+			}
+
+			// 保留原有 intervalSeconds 等未涉及的配置项
+			const cfg: GlmQuotaConfig = {
+				organization,
+				project: projectVal,
+				type,
+				...(current?.intervalSeconds !== undefined ? { intervalSeconds: current.intervalSeconds } : {}),
+			};
+			saveConfig(cfg);
+			await refresh(ctx.ui, true);
+			if (snapshot) {
+				ctx.ui.notify(`配置已保存并生效：\n${renderReport(snapshot, stale)}`, "info");
+			} else {
+				ctx.ui.notify(
+					"配置已写入 ~/.pi/agent/glm-quota.json，但拉取未成功。\n" +
+						"请检查 org/project 是否正确（获取方法见项目 README）",
+					"warning",
+				);
+			}
+		},
+	});
+}

package/mock.test.ts

@@ -0,0 +1,171 @@
+/**
+ * 扩展接线的端到端测试：mock pi 上下文，触发真实事件流，
+ * 验证 fetch → 解析 → setStatus 全链路（发起真实网络请求）。
+ *
+ * 需要本机已配置 ~/.pi/agent/glm-quota.json 与可用 API key，
+ * 缺失时自动跳过（便于其他用户在无凭证环境跑测试）。
+ *
+ * 运行：node mock.test.ts
+ */
+
+import factory from "./index.ts";
+import { loadConfig, resolveApiKey } from "./pure.ts";
+
+type Handler = (event: unknown, ctx: unknown) => unknown;
+
+const handlers = new Map<string, Handler>();
+const commands = new Map<string, { description: string; handler: Handler }>();
+const statuses = new Map<string, string | undefined>();
+const notifications: Array<{ msg: string; level: string }> = [];
+
+const inputTitles: string[] = [];
+const fakeUi = (inputAnswers: string[] = []) => ({
+	setStatus: (key: string, text?: string) => {
+		statuses.set(key, text);
+		console.log(`[status:${key}] ${text ?? "(cleared)"}`);
+	},
+	theme: { fg: (_c: string, s: string) => s },
+	notify: (msg: string, level: string) => {
+		notifications.push({ msg, level });
+		console.log(`[notify:${level}]\n${msg}`);
+	},
+	input: async (title: string, _placeholder: string) => {
+		inputTitles.push(title);
+		return inputAnswers.shift();
+	},
+});
+
+const fakePi = {
+	on: (event: string, handler: Handler) => handlers.set(event, handler),
+	registerCommand: (name: string, def: { description: string; handler: Handler }) => commands.set(name, def),
+};
+
+async function fire(event: string, ev: unknown, ctx: unknown) {
+	const h = handlers.get(event);
+	if (!h) throw new Error(`no handler for ${event}`);
+	await h(ev, ctx);
+}
+
+async function main() {
+	const configured = loadConfig() !== null && resolveApiKey() !== null;
+
+	factory(fakePi as never);
+
+	const tuiCtx = {
+		mode: "tui",
+		model: { provider: "zai-coding-cn", id: "glm-5.3" },
+		ui: fakeUi(),
+	};
+
+	if (!configured) {
+		await fire("session_start", { reason: "startup" }, tuiCtx);
+		const hint = statuses.get("glm-quota") ?? "";
+		if (!hint.includes("glm-quota-setup")) {
+			console.error("FAIL 未配置时应提示运行 /glm-quota-setup，实际:", hint);
+			process.exit(1);
+		}
+		console.log("本机无配置/key，未配置提示路径验证通过，跳过后续真实请求测试 ✅");
+		process.exit(0);
+	}
+
+	console.log("== session_start ==");
+	await fire("session_start", { reason: "startup" }, tuiCtx);
+
+	const footer = statuses.get("glm-quota") ?? "";
+	if (!footer.includes("5h") || !footer.includes("W")) {
+		console.error("FAIL footer 未包含窗口信息:", footer);
+		process.exit(1);
+	}
+	console.log("\nfooter 验证通过 ✓");
+
+	console.log("\n== /glm-quota 命令 ==");
+	const cmd = commands.get("glm-quota");
+	if (!cmd) {
+		console.error("FAIL 未注册 glm-quota 命令");
+		process.exit(1);
+	}
+	await cmd.handler("", tuiCtx);
+	if (notifications.length === 0) {
+		console.error("FAIL 命令未产生 notify");
+		process.exit(1);
+	}
+
+	console.log("\n== model_select 切到非 GLM provider ==");
+	await fire(
+		"model_select",
+		{ model: { provider: "anthropic", id: "x" }, previousModel: undefined, source: "set" },
+		tuiCtx,
+	);
+	if (statuses.get("glm-quota") !== undefined) {
+		console.error("FAIL 切走后状态栏未清除");
+		process.exit(1);
+	}
+	console.log("切走清除 ✓");
+
+	console.log("\n== model_select 切回 GLM ==");
+	await fire(
+		"model_select",
+		{ model: { provider: "zai-coding-cn", id: "glm-5.3" }, previousModel: undefined, source: "set" },
+		tuiCtx,
+	);
+	if (!(statuses.get("glm-quota") ?? "").includes("5h")) {
+		console.error("FAIL 切回后未恢复显示");
+		process.exit(1);
+	}
+	console.log("切回恢复 ✓");
+
+	console.log("\n== /glm-quota-setup：留空保持现有值 ==");
+	const setup = commands.get("glm-quota-setup");
+	if (!setup) {
+		console.error("FAIL 未注册 glm-quota-setup 命令");
+		process.exit(1);
+	}
+	const before = JSON.stringify(loadConfig());
+	const keepCtx = { ...tuiCtx, ui: fakeUi(["", "", ""]) };
+	await setup.handler("", keepCtx);
+	if (
+		!inputTitles[0]?.includes("bigmodel.cn/coding-plan/") ||
+		!inputTitles[0]?.includes("bigmodel-project") ||
+		!inputTitles[0]?.includes("type")
+	) {
+		console.error("FAIL 首个输入框标题应包含获取帮助:", inputTitles[0]);
+		process.exit(1);
+	}
+	console.log("帮助嵌入标题 ✓");
+	if (JSON.stringify(loadConfig()) !== before) {
+		console.error("FAIL 留空时应保持原配置");
+		process.exit(1);
+	}
+	console.log("留空保持 ✓");
+
+	console.log("\n== /glm-quota-setup：取消（Esc）中止 ==");
+	const cancelCtx = { ...tuiCtx, ui: fakeUi([undefined as unknown as string]) };
+	await setup.handler("", cancelCtx);
+	if (JSON.stringify(loadConfig()) !== before) {
+		console.error("FAIL 取消后不应写配置");
+		process.exit(1);
+	}
+	console.log("取消中止 ✓");
+
+	console.log("\n== /glm-quota-setup：留空 org/project + 修改 type ==");
+	const modCtx = { ...tuiCtx, ui: fakeUi(["", "", "9"]) };
+	await setup.handler("", modCtx);
+	const after = loadConfig();
+	const beforeCfg = JSON.parse(before) as NonNullable<ReturnType<typeof loadConfig>>;
+	if (after?.type !== 9 || after.organization !== beforeCfg.organization || after.project !== beforeCfg.project) {
+		console.error("FAIL 部分修改结果不对:", JSON.stringify(after));
+		process.exit(1);
+	}
+	console.log("部分修改 ✓（org/project 保持，type=9）");
+
+	// 回滚为测试前的真实配置
+	const { saveConfig } = await import("./pure.ts");
+	saveConfig(beforeCfg);
+
+	console.log("\n== session_shutdown ==");
+	await fire("session_shutdown", { reason: "quit" }, tuiCtx);
+	console.log("全部通过 ✅");
+	process.exit(0);
+}
+
+void main();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "pi-glm-quota",
+  "version": "0.1.0",
+  "description": "GLM Coding Plan (Zhipu BigModel credit-based plans, incl. team) quota usage in the pi footer — org/project context headers, /glm-quota report, /glm-quota-setup wizard",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "glm",
+    "zhipu",
+    "bigmodel",
+    "zai",
+    "coding-plan",
+    "quota",
+    "usage"
+  ],
+  "license": "MIT",
+  "author": "focksor",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "files": [
+    "index.ts",
+    "pure.ts",
+    "pure.test.ts",
+    "mock.test.ts",
+    "config.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/pure.test.ts

@@ -0,0 +1,148 @@
+/**
+ * pure.ts 的独立单元测试（node 直接运行，无需 pi 运行时）
+ * 运行：node pure.test.ts
+ */
+
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	bar,
+	classifyLimits,
+	fmtCountdown,
+	fmtNum,
+	loadConfig,
+	pctColor,
+	renderFooter,
+	renderReport,
+	resolveApiKey,
+	saveConfig,
+	type LimitItem,
+	type Snapshot,
+} from "./pure.ts";
+
+let failed = 0;
+function check(name: string, cond: boolean, detail?: string) {
+	if (cond) {
+		console.log(`ok   ${name}`);
+	} else {
+		failed++;
+		console.error(`FAIL ${name}${detail ? ` — ${detail}` : ""}`);
+	}
+}
+
+// —— 响应样本（结构来自真实抓包，数值为合成数据）——
+const sampleLimits: LimitItem[] = [
+	{
+		type: "CREDIT_LIMIT",
+		unit: 3,
+		number: 5,
+		usage: 15000,
+		currentValue: 1500,
+		remaining: 13500,
+		percentage: 10,
+		nextResetTime: 1_789_000_000_000,
+	},
+	{
+		type: "CREDIT_LIMIT",
+		unit: 6,
+		number: 1,
+		usage: 66000,
+		currentValue: 33000,
+		remaining: 33000,
+		percentage: 50,
+		nextResetTime: 1_789_300_000_000,
+	},
+];
+
+const windows = classifyLimits(sampleLimits);
+check("classifyLimits 返回 2 个窗口", windows.length === 2, `got ${windows.length}`);
+check("第一个窗口是 5h", windows[0]?.label === "5h", windows[0]?.label);
+check("第二个窗口是 W", windows[1]?.label === "W", windows[1]?.label);
+check("5h 已用量", windows[0]?.used === 1500);
+check("W 百分比取整", windows[1]?.pct === 50);
+check("忽略非 CREDIT_LIMIT 条目", classifyLimits([{ ...sampleLimits[0]!, type: "TIME_LIMIT" }]).length === 0);
+
+const snap: Snapshot = { windows, level: "pro", fetchedAt: 1_788_950_000_000 };
+const footer = renderFooter(snap, false, null, 1_788_950_000_000);
+console.log("footer:", footer);
+check("footer 含 5h", footer.includes("5h"));
+check("footer 含 W", footer.includes("W"));
+check("footer 含百分比", footer.includes("10%") && footer.includes("50%"));
+check("footer 含沙漏图标", footer.includes("⏳"));
+const staleFooter = renderFooter(snap, true, null, 1_788_950_000_000);
+check("stale 标记为 ~", staleFooter.endsWith("~"), staleFooter);
+
+check("bar 10 格", bar(10).length === 10);
+check("bar 填充数", bar(48).startsWith("█████") && !bar(48).startsWith("██████"));
+check("pctColor 分档", pctColor(10) === "success" && pctColor(60) === "warning" && pctColor(85) === "error");
+check("fmtNum 千分位", fmtNum(33000) === "33,000");
+check(
+	"fmtCountdown 分钟级",
+	fmtCountdown(1_788_950_000_000 + 42 * 60_000, 1_788_950_000_000) === "42m",
+	fmtCountdown(1_788_950_000_000 + 42 * 60_000, 1_788_950_000_000),
+);
+check(
+	"fmtCountdown 小时级",
+	fmtCountdown(1_788_950_000_000 + (3 * 3600 + 5 * 60) * 1000, 1_788_950_000_000) === "3h5m",
+);
+check(
+	"fmtCountdown 天级",
+	fmtCountdown(1_788_950_000_000 + (4 * 86400 + 3 * 3600) * 1000, 1_788_950_000_000) === "4d3h",
+);
+check("fmtCountdown 已过期归零", fmtCountdown(0, 1_788_950_000_000) === "0m");
+
+const report = renderReport(snap, false);
+console.log("--- report ---");
+console.log(report);
+check("报告含档位", report.includes("pro"));
+check("报告含积分数字", report.includes("1,500") && report.includes("15,000"));
+check("报告含重置时间", report.includes("重置于"));
+
+// —— 配置读取 / 环境变量覆盖 / 写入 ——
+const dir = mkdtempSync(join(tmpdir(), "glm-quota-test-"));
+const cfgPath = join(dir, "config.json");
+const authPath = join(dir, "auth.json");
+try {
+	writeFileSync(cfgPath, JSON.stringify({ organization: "org-file", project: "proj-file", type: 1 }), "utf-8");
+
+	const fromFile = loadConfig(cfgPath, {});
+	check("从文件读取配置", fromFile?.organization === "org-file" && fromFile?.project === "proj-file");
+	check("文件 type 生效", fromFile?.type === 1);
+
+	const envOverride = loadConfig(cfgPath, { GLM_QUOTA_ORGANIZATION: "org-env", GLM_QUOTA_TYPE: "2" });
+	check("环境变量覆盖 org", envOverride?.organization === "org-env");
+	check("环境变量保留文件 project", envOverride?.project === "proj-file");
+	check("环境变量覆盖 type", envOverride?.type === 2);
+
+	const partialPath = join(dir, "partial.json");
+	writeFileSync(partialPath, JSON.stringify({ organization: "org-only" }), "utf-8");
+	check("缺 project 时返回 null", loadConfig(partialPath, {}) === null);
+	check("配置文件不存在返回 null", loadConfig(join(dir, "none.json"), {}) === null);
+
+	const envOnly = loadConfig(join(dir, "none.json"), {
+		GLM_QUOTA_ORGANIZATION: "org-env",
+		GLM_QUOTA_PROJECT: "proj-env",
+		GLM_QUOTA_INTERVAL_SECONDS: "120",
+	});
+	check("仅环境变量即可成配置", envOnly?.organization === "org-env" && envOnly?.project === "proj-env");
+	check("环境变量 intervalSeconds", envOnly?.intervalSeconds === 120);
+	check("非法 type 回退默认 2", loadConfig(cfgPath, { GLM_QUOTA_TYPE: "abc" })?.type === 2);
+
+	saveConfig({ organization: "org-new", project: "proj-new", type: 2 }, cfgPath);
+	const reread = loadConfig(cfgPath, {});
+	check("saveConfig 写入后可读回", reread?.organization === "org-new" && reread?.type === 2);
+
+	writeFileSync(authPath, JSON.stringify({ "zai-coding-cn": { type: "api_key", key: "testkey123" } }), "utf-8");
+	check("resolveApiKey 读 auth.json", resolveApiKey({}, authPath) === "testkey123");
+	check("resolveApiKey 环境变量优先", resolveApiKey({ ZAI_CODING_CN_API_KEY: "envkey" }, authPath) === "envkey");
+	check("resolveApiKey 缺失返回 null", resolveApiKey({}, join(dir, "none.json")) === null);
+} finally {
+	rmSync(dir, { recursive: true, force: true });
+}
+
+if (failed > 0) {
+	console.error(`\n${failed} 项失败`);
+	process.exit(1);
+}
+console.log("\n全部通过");

package/pure.ts

@@ -0,0 +1,198 @@
+/**
+ * GLM 配额显示的纯逻辑部分：配置读取、凭证解析、响应归一化、渲染。
+ * 不依赖 pi 运行时，可独立单元测试。
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** 配置文件路径 */
+export const CONFIG_PATH = join(homedir(), ".pi", "agent", "glm-quota.json");
+/** auth.json 路径 */
+export const AUTH_PATH = join(homedir(), ".pi", "agent", "auth.json");
+/** 用量查询端点（不带 query） */
+export const QUOTA_URL = "https://bigmodel.cn/api/monitor/usage/quota/limit";
+
+export interface GlmQuotaConfig {
+	organization: string;
+	project: string;
+	type: number;
+	intervalSeconds?: number;
+}
+
+/** 服务端返回的限额条目 */
+export interface LimitItem {
+	type: string;
+	unit: number;
+	number: number;
+	usage: number;
+	currentValue: number;
+	remaining: number;
+	percentage: number;
+	nextResetTime: number;
+}
+
+export interface QuotaResponse {
+	code: number;
+	msg: string;
+	data?: { limits?: LimitItem[]; level?: string };
+	success?: boolean;
+}
+
+/** 归一化后的窗口视图 */
+export interface QuotaWindow {
+	label: string;
+	used: number;
+	total: number;
+	remaining: number;
+	pct: number;
+	resetAt: number;
+}
+
+export interface Snapshot {
+	windows: QuotaWindow[];
+	level: string;
+	fetchedAt: number;
+}
+
+/** 主题着色函数的最小接口（与 pi 的 theme.fg 兼容） */
+export type FgFn = (c: "success" | "warning" | "error" | "dim", s: string) => string;
+
+/** 支持的环境变量（优先级高于配置文件） */
+const ENV_ORG = "GLM_QUOTA_ORGANIZATION";
+const ENV_PROJECT = "GLM_QUOTA_PROJECT";
+const ENV_TYPE = "GLM_QUOTA_TYPE";
+const ENV_INTERVAL = "GLM_QUOTA_INTERVAL_SECONDS";
+
+/**
+ * 读取配置。优先级：环境变量 > 配置文件；org/project 任一缺失返回 null。
+ * path/env 参数仅供测试注入，默认使用真实路径与环境。
+ */
+export function loadConfig(path = CONFIG_PATH, env: Record<string, string | undefined> = process.env): GlmQuotaConfig | null {
+	let file: Partial<GlmQuotaConfig> = {};
+	try {
+		file = JSON.parse(readFileSync(path, "utf-8")) as Partial<GlmQuotaConfig>;
+	} catch {
+		// 文件不存在或非法都按空配置处理，交给环境变量兜底
+	}
+
+	const organization = env[ENV_ORG]?.trim() || (typeof file.organization === "string" ? file.organization.trim() : "");
+	const project = env[ENV_PROJECT]?.trim() || (typeof file.project === "string" ? file.project.trim() : "");
+	if (organization.length === 0 || project.length === 0) return null;
+
+	const typeRaw = env[ENV_TYPE]?.trim() ?? (typeof file.type === "number" ? String(file.type) : "");
+	const type = /^\d+$/.test(typeRaw ?? "") ? Number(typeRaw) : 2;
+
+	const intervalRaw = env[ENV_INTERVAL]?.trim() ?? (typeof file.intervalSeconds === "number" ? String(file.intervalSeconds) : "");
+	const intervalSeconds = /^\d+$/.test(intervalRaw ?? "") && Number(intervalRaw) > 0 ? Number(intervalRaw) : undefined;
+
+	return { organization, project, type, intervalSeconds };
+}
+
+/** 保存配置（供 /glm-quota-setup 向导写入），自动创建父目录 */
+export function saveConfig(cfg: GlmQuotaConfig, path = CONFIG_PATH): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * 解析 API key：env 优先（ZAI_CODING_CN_API_KEY），其次 auth.json 的
+ * zai-coding-cn 条目。path/env 参数仅供测试注入。
+ */
+export function resolveApiKey(
+	env: Record<string, string | undefined> = process.env,
+	path = AUTH_PATH,
+): string | null {
+	const envKey = env.ZAI_CODING_CN_API_KEY?.trim();
+	if (envKey && envKey.length > 0) return envKey;
+	try {
+		const auth = JSON.parse(readFileSync(path, "utf-8")) as Record<string, { key?: string }>;
+		return auth["zai-coding-cn"]?.key ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * 把服务端 limits 归一化为显示窗口。
+ * 实测语义（新版积分套餐）：unit 3 = 小时窗口（number 5 → 5 小时滚动窗），
+ * unit 6 = 周窗口（number 1 → 1 周）；其余类型以通用标签保留。
+ * 最多返回 2 个窗口，按重置时间升序（5h 在前、周窗口在后）。
+ */
+export function classifyLimits(limits: LimitItem[]): QuotaWindow[] {
+	const windows: QuotaWindow[] = [];
+	for (const l of limits) {
+		if (l.type !== "CREDIT_LIMIT") continue;
+		let label: string;
+		if (l.unit === 3) label = `${l.number}h`;
+		else if (l.unit === 6) label = l.number === 1 ? "W" : `${l.number}w`;
+		else label = `u${l.unit}x${l.number}`;
+		windows.push({
+			label,
+			used: l.currentValue,
+			total: l.usage,
+			remaining: l.remaining,
+			pct: Math.max(0, Math.min(100, Math.round(l.percentage))),
+			resetAt: l.nextResetTime,
+		});
+	}
+	windows.sort((a, b) => a.resetAt - b.resetAt);
+	return windows.slice(0, 2);
+}
+
+/** 千分位格式化 */
+export function fmtNum(n: number): string {
+	return Math.round(n).toLocaleString("en-US");
+}
+
+/** 重置倒计时：1h5m / 4d3h / 42m */
+export function fmtCountdown(resetAt: number, now = Date.now()): string {
+	let sec = Math.max(0, Math.floor((resetAt - now) / 1000));
+	const d = Math.floor(sec / 86400);
+	sec -= d * 86400;
+	const h = Math.floor(sec / 3600);
+	const m = Math.floor((sec - h * 3600) / 60);
+	if (d > 0) return `${d}d${h}h`;
+	if (h > 0) return `${h}h${m}m`;
+	return `${m}m`;
+}
+
+/** 10 格用量条 */
+export function bar(pct: number): string {
+	const filled = Math.min(10, Math.round(pct / 10));
+	return "█".repeat(filled) + "░".repeat(10 - filled);
+}
+
+/** 按使用率选颜色 */
+export function pctColor(pct: number): "success" | "warning" | "error" {
+	if (pct >= 80) return "error";
+	if (pct >= 50) return "warning";
+	return "success";
+}
+
+/** footer 渲染；fg 传 null 时输出无色纯文本（测试 / notify 场景） */
+export function renderFooter(snap: Snapshot, stale: boolean, fg: FgFn | null, now = Date.now()): string {
+	const parts = snap.windows.map((w) => {
+		const seg = `${w.label} ${bar(w.pct)} ${w.pct}% ⏳${fmtCountdown(w.resetAt, now)}${stale ? "~" : ""}`;
+		return fg ? fg(pctColor(w.pct), seg) : seg;
+	});
+	const joiner = fg ? fg("dim", " · ") : " · ";
+	return (fg ? fg("dim", "GLM ") : "GLM ") + parts.join(joiner);
+}
+
+/** 报告渲染（/glm-quota 用），多行纯文本 */
+export function renderReport(snap: Snapshot, stale: boolean): string {
+	const lines = snap.windows.map((w) => {
+		const resetLocal = new Date(w.resetAt).toLocaleString("zh-CN", { hour12: false });
+		return (
+			`${w.label} 窗口  ${fmtNum(w.used)} / ${fmtNum(w.total)} 积分已用（${w.pct}%）\n` +
+			`         剩余 ${fmtNum(w.remaining)} · 重置于 ${resetLocal}（⏳${fmtCountdown(w.resetAt)}）`
+		);
+	});
+	const staleMark = stale ? "（数据过期，最近一次拉取失败）" : "";
+	return (
+		`GLM Coding Plan — ${snap.level} 档${staleMark}\n${lines.join("\n")}\n` +
+		`最近刷新：${new Date(snap.fetchedAt).toLocaleTimeString("zh-CN", { hour12: false })}`
+	);
+}