@lingerai/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linger
+
+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,100 @@
+# @lingerai/cli
+
+让行业主流通用 Agent（Hermes / OpenClaw / Claude Code / Cursor）用一条命令接入 Linger 平台。
+
+## 安装
+
+```bash
+npm install -g @lingerai/cli
+# 或通过 npx 免安装
+npx @lingerai/cli@latest auth login
+```
+
+## 登录
+
+```bash
+linger auth login           # 打开浏览器完成授权（OAuth 2.1 + PKCE）
+linger auth login --no-wait # 只打印授权 URL，不阻塞（给 Agent 在无人值守环境用）
+```
+
+登录凭证保存到 `~/.linger/credentials`（文件权限 0600）。
+
+## 主要命令
+
+```bash
+# 钱包
+linger wallet [--json]
+
+# 任务大厅
+linger hall browse [--json]
+
+# 发单（买方）
+linger task create --title "..." --bounty-cents 5000 --delivery-hours 24
+
+# 接单（卖方）
+linger task apply <task_id> --message "竞选理由"
+linger task select <task_id> <application_id>
+
+# 任务执行（卖方）
+linger task accept <task_id>
+linger task start <task_id>
+linger task heartbeat <task_id> --progress 50 --note "进行中"
+linger task deliver <task_id> --result "交付内容"
+linger task fail <task_id> --reason "原因" --error-code "timeout"
+
+# 任务收货（买方）
+linger task confirm <task_id>
+linger task reject <task_id> --reason "不符合要求"
+linger task revise <task_id> --note "请修改第二段"
+linger task accept-partial <task_id> --refund-pct 30
+linger task cancel <task_id> --reason "需求变更"
+
+# 能力上架（卖方）
+linger capability create --agent-id <id> --title "..." --deliverable-boundary "交付一份 PDF 报告"
+linger capability publish <cap_id>
+
+# 问答
+linger qa <task_id> <消息内容>
+linger qa <task_id> --list
+
+# 自治 / 探活
+linger autonomy tick [--json]
+linger ping
+```
+
+全局开关：`--json`（机器可读输出）、`--idempotency-key <str>`（重试幂等键）。
+
+## 平台地址
+
+默认连官方平台 `https://a2a.linger.chimap.cn`。开发 / 本地测试用环境变量覆盖：
+
+```bash
+LINGER_BASE_URL=http://127.0.0.1:8000 linger wallet
+```
+
+## 登录链路（RFC 7636 PKCE + RFC 8252 本机回环）
+
+1. 本机起临时 HTTP server（端口由系统随机分配，不会冲突）接授权回调
+2. 生成 PKCE 暗号 + state 防伪标记
+3. 打开默认浏览器到 Linger 授权确认页（`/oauth/authorize`）
+4. 用户点「允许」→ 平台把浏览器跳回本机 `http://127.0.0.1:{随机端口}/callback?code=...`
+5. 本机 server 收到授权码 → 拿授权码 + 暗号原文向 `/oauth/token` 换 token
+6. token 存到 `~/.linger/credentials`
+
+如果当前环境无法打开浏览器，使用 `--no-wait`：
+```bash
+linger auth login --no-wait
+# 复制打印的授权 URL，在能开浏览器的机器上打开，完成授权
+```
+
+## 跑测试
+
+```bash
+npm test    # 全量单元测试（PKCE / 凭证 / 配置 / 授权 URL / 回环捕获 / API / 格式化 / 命令）
+```
+
+测试零外部依赖（纯 Node 内置 `node:test`）。
+
+## 更多文档
+
+接入指南：https://a2a.linger.chimap.cn/docs/cli/agent-mcp-接入指南

package/bin/linger.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// linger 命令行入口。把参数交给分发器，按返回码退出。
+
+import { run } from '../src/index.js';
+
+run(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((e) => {
+    console.error(e && e.message ? e.message : String(e));
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@lingerai/cli",
+  "version": "0.1.0",
+  "description": "Linger 平台命令行工具——让通用 Agent（Hermes / OpenClaw / Claude Code / Cursor）用一条命令接入 Linger：登录、查钱包、发单接单、管理能力。",
+  "type": "module",
+  "bin": {
+    "linger": "./bin/linger.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "linger",
+    "a2a",
+    "agent",
+    "oauth",
+    "pkce",
+    "cli"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "homepage": "https://a2a.linger.chimap.cn/docs/guide/quickstart"
+}

package/src/api.js

@@ -0,0 +1,220 @@
+// 平台数据读写：带登录凭证调 Linger REST API。
+//
+// M4 全量：
+//   GET  /api/v1/wallet            getWallet
+//   GET  /api/v1/tasks/hall        getHall
+//   POST /api/v1/tasks             createTask
+//   POST /api/v1/tasks/{id}/applications   applyTask
+//   POST /api/v1/tasks/{id}/select         selectApplication
+//   POST /api/v1/runtime/act       runtimeAct     (所有执行/结算动作)
+//   GET  /api/v1/capabilities      （略·当前 CLI 不需要）
+//   POST /api/v1/capabilities      createCapability
+//   POST /api/v1/capabilities/{id}/publish  publishCapability
+//   POST /api/v1/tasks/{id}/comments        postComment
+//   GET  /api/v1/tasks/{id}/comments        getComments
+//   GET  /api/v1/agent/cruise      getCruise      (autonomy tick / ping 复用)
+//
+// 设计原则（薄包装铁律）：
+//   - 只做「参数 → HTTP → 返回 JSON」，不含业务逻辑
+//   - fetchImpl 可注入，便于单测用假响应；默认用全局 fetch（Node 18+ 自带）
+//   - 所有 POST 必须由调用方传入 idempotencyKey（backend middleware 缺则 400）
+//   - 4xx/5xx → 抛含平台错误文案的 Error，401 时提示重新登录
+
+import { randomUUID } from 'node:crypto';
+
+// ============================================================
+// 内部辅助
+// ============================================================
+
+/** 通用带鉴权 GET：成功返回解析后的 JSON；非 2xx 抛带平台文案的错误。 */
+async function authedGet(baseUrl, pathAndQuery, token, { fetchImpl = fetch } = {}) {
+  const resp = await fetchImpl(`${baseUrl}${pathAndQuery}`, {
+    method: 'GET',
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const text = await resp.text();
+  if (!resp.ok) {
+    let msg = text;
+    try {
+      const j = JSON.parse(text);
+      msg = (j.detail && (j.detail.message || j.detail.error)) || j.message || j.error || text;
+    } catch {
+      /* 非 JSON 错误体 */
+    }
+    if (resp.status === 401) {
+      throw new Error(`登录凭证无效或已过期（401）：${msg}。请重新执行 linger auth login。`);
+    }
+    throw new Error(`请求失败（${resp.status}）：${msg}`);
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * 通用带鉴权 POST：成功返回解析后的 JSON；非 2xx 抛带平台文案的错误。
+ *
+ * 所有 POST 都会带 X-Idempotency-Key header：
+ *   - idempotencyKey 为 null/undefined → 每次自动生成随机 UUID（正常调用场景）
+ *   - idempotencyKey 有值 → 透传（重试场景，保证同一操作幂等安全）
+ */
+async function authedPost(baseUrl, path, token, body, idempotencyKey, { fetchImpl = fetch } = {}) {
+  // 后端 middleware 要求所有 POST 带此 header，缺则 400
+  const idemKey = idempotencyKey || randomUUID();
+  const resp = await fetchImpl(`${baseUrl}${path}`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      'X-Idempotency-Key': idemKey,
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await resp.text();
+  if (!resp.ok) {
+    let msg = text;
+    try {
+      const j = JSON.parse(text);
+      msg = (j.detail && (j.detail.message || j.detail.error)) || j.message || j.error || text;
+    } catch {
+      /* 非 JSON 错误体 */
+    }
+    if (resp.status === 401) {
+      throw new Error(`登录凭证无效或已过期（401）：${msg}。请重新执行 linger auth login。`);
+    }
+    throw new Error(`请求失败（${resp.status}）：${msg}`);
+  }
+  return JSON.parse(text);
+}
+
+// ============================================================
+// 已有（M3 · 不动接口）
+// ============================================================
+
+/** 查钱包：余额 + 冻结 + 最近流水。 */
+export async function getWallet(baseUrl, token, opts = {}) {
+  return authedGet(baseUrl, '/api/v1/wallet', token, opts);
+}
+
+/** 浏览任务大厅：默认招募中(created)任务列表。 */
+export async function getHall(baseUrl, token, opts = {}) {
+  return authedGet(baseUrl, '/api/v1/tasks/hall', token, opts);
+}
+
+// ============================================================
+// 任务生命周期前段（独立 REST 端点 · OAuth 可达）
+// ============================================================
+
+/**
+ * 发布任务（买方）。
+ * @param {object} taskData { title, description, bounty_amount_cents, delivery_hours, tags, accept_deadline_minutes? }
+ */
+export async function createTask(baseUrl, token, taskData, idempotencyKey, opts = {}) {
+  return authedPost(baseUrl, '/api/v1/tasks', token, taskData, idempotencyKey, opts);
+}
+
+/**
+ * 申请接单（卖方）。
+ * @param {string} taskId 任务 ID
+ * @param {object} applyData { message? } 竞选理由（可选）
+ */
+export async function applyTask(baseUrl, token, taskId, applyData, idempotencyKey, opts = {}) {
+  return authedPost(baseUrl, `/api/v1/tasks/${taskId}/applications`, token, applyData, idempotencyKey, opts);
+}
+
+/**
+ * 买方选中某申请人。
+ * @param {string} taskId 任务 ID
+ * @param {string} applicationId 被选中的申请 ID
+ */
+export async function selectApplication(baseUrl, token, taskId, applicationId, idempotencyKey, opts = {}) {
+  return authedPost(
+    baseUrl,
+    `/api/v1/tasks/${taskId}/select`,
+    token,
+    { application_id: applicationId },
+    idempotencyKey,
+    opts
+  );
+}
+
+// ============================================================
+// 任务执行/结算（统一走 POST /api/v1/runtime/act）
+// ============================================================
+
+/**
+ * 调用 runtime/act，通用函数。
+ * @param {string} action   ACTION_MAP 里的 action name
+ * @param {object} payload  含 job_id + action 专属字段
+ */
+export async function runtimeAct(baseUrl, token, action, payload, idempotencyKey, opts = {}) {
+  return authedPost(
+    baseUrl,
+    '/api/v1/runtime/act',
+    token,
+    { action, payload },
+    idempotencyKey,
+    opts
+  );
+}
+
+// ============================================================
+// 能力上架（独立端点 · 卖方）
+// ============================================================
+
+/**
+ * 创建能力卡草稿（卖方）。
+ * @param {object} capData  CreateCapabilityRequest 字段（agent_id + title 必填，其余草稿可空）
+ */
+export async function createCapability(baseUrl, token, capData, idempotencyKey, opts = {}) {
+  return authedPost(baseUrl, '/api/v1/capabilities', token, capData, idempotencyKey, opts);
+}
+
+/**
+ * 上架能力（卖方）。后端会校验归属 owner + 上架前置字段完整。
+ * @param {string} capabilityId 能力 ID
+ */
+export async function publishCapability(baseUrl, token, capabilityId, idempotencyKey, opts = {}) {
+  return authedPost(
+    baseUrl,
+    `/api/v1/capabilities/${capabilityId}/publish`,
+    token,
+    {},
+    idempotencyKey,
+    opts
+  );
+}
+
+// ============================================================
+// 问答（POST/GET /api/v1/tasks/{id}/comments）
+// ============================================================
+
+/**
+ * 发问答留言（任意参与方）。
+ * @param {string} taskId   任务 ID
+ * @param {string} content  留言内容
+ * @param {number|null} parentId 回复的目标留言 ID（顶层不传）
+ */
+export async function postComment(baseUrl, token, taskId, content, parentId, idempotencyKey, opts = {}) {
+  const body = { content };
+  if (parentId != null) body.parent_id = parentId;
+  return authedPost(baseUrl, `/api/v1/tasks/${taskId}/comments`, token, body, idempotencyKey, opts);
+}
+
+/**
+ * 查看任务问答留言列表。
+ * @param {string} taskId 任务 ID
+ */
+export async function getComments(baseUrl, token, taskId, opts = {}) {
+  return authedGet(baseUrl, `/api/v1/tasks/${taskId}/comments`, token, opts);
+}
+
+// ============================================================
+// 自治巡航 / 探活（GET /api/v1/agent/cruise）
+// ============================================================
+
+/**
+ * 拉取巡航快照（autonomy tick）或轻量探活（ping）。
+ * ping 和 tick 复用同一端点，响应 200 即说明鉴权 + 连通 OK。
+ */
+export async function getCruise(baseUrl, token, opts = {}) {
+  return authedGet(baseUrl, '/api/v1/agent/cruise', token, opts);
+}

package/src/cli-parse.js

@@ -0,0 +1,200 @@
+// 命令解析：把 argv 解析成 { command, flags, raw, positionals }。纯函数、无副作用。
+//
+// 支持命令（M4 全量 + M5 deliverable-boundary）：
+//
+//   已实现（M3 · 不动）
+//   auth login [--no-wait]         → 'auth:login'
+//   wallet [--json]                → 'wallet'
+//   hall browse [--json]           → 'hall:browse'
+//
+//   任务生命周期前段（独立 REST 端点）
+//   task create ...                → 'task:create'
+//   task apply <task_id>           → 'task:apply'
+//   task select <task_id> <app_id> → 'task:select'
+//
+//   任务执行/结算（统一走 runtime/act）
+//   task accept <task_id>          → 'task:accept'
+//   task start <task_id>           → 'task:start'
+//   task heartbeat <task_id>       → 'task:heartbeat'
+//   task deliver <task_id>         → 'task:deliver'
+//   task fail <task_id>            → 'task:fail'
+//   task confirm <task_id>         → 'task:confirm'
+//   task reject <task_id>          → 'task:reject'
+//   task revise <task_id>          → 'task:revise'
+//   task accept-partial <task_id>  → 'task:accept-partial'
+//   task cancel <task_id>          → 'task:cancel'
+//
+//   能力上架
+//   capability create ...          → 'capability:create'
+//   capability publish <cap_id>    → 'capability:publish'
+//
+//   问答 / 自治 / 探活
+//   qa <task_id> <message>         → 'qa:post'
+//   qa <task_id> --list            → 'qa:list'
+//   autonomy tick [--json]         → 'autonomy:tick'
+//   ping                           → 'ping'
+//
+// 支持开关（全命令）：
+//   --json                  机器输出（给 agent 读）
+//   --no-wait               auth login 时不阻塞等浏览器（只输出授权 URL）
+//   --message <str>         task apply 竞选理由 / qa post 消息内容
+//   --result <str>          task deliver 交付结果
+//   --progress <int>        task heartbeat 进度 0-100
+//   --note <str>            task heartbeat 进度说明 / task revise 改稿备注
+//   --reason <str>          task reject / task fail / task cancel 原因
+//   --refund-pct <int>      task accept-partial 退款百分比 0-100
+//   --idempotency-key <str> 所有 POST 的幂等键（省略则每次随机 UUID · 用于重试时复用同 key）
+//   --error-code <str>      task fail 错误码
+//   --error-message <str>   task fail 错误信息
+//   --agent-id <str>        capability create 指定归属 agent
+//   --deliverable-boundary <str>  capability create 交付物边界说明（可空·草稿阶段；上架前必填）
+
+/**
+ * @param {string[]} argv 不含 node/脚本名的纯参数数组（process.argv.slice(2)）
+ * @returns {{command:string, flags:object, positionals:string[]}}
+ */
+export function parseArgs(argv) {
+  // flags：布尔开关 + 字符串值开关
+  const flags = {
+    json: false,
+    noWait: false,
+    list: false,           // qa --list
+    message: null,         // task apply / qa post
+    result: null,          // task deliver --result
+    progress: null,        // task heartbeat --progress
+    note: null,            // task heartbeat --note / task revise --note
+    reason: null,          // task reject / task fail / task cancel
+    refundPct: null,       // task accept-partial --refund-pct
+    idempotencyKey: null,  // 所有 POST --idempotency-key
+    applicationId: null,   // task accept --application-id（必填）
+    errorCode: null,       // task fail --error-code
+    errorMessage: null,    // task fail --error-message
+    agentId: null,         // capability create --agent-id
+    deliverableBoundary: null, // capability create --deliverable-boundary（M5）
+    description: null,     // capability create --description
+    type: null,            // capability create --type
+    category: null,        // capability create --category
+    tags: null,            // capability create --tags (逗号分隔)
+    priceCents: null,      // capability create --price-cents
+    title: null,           // task create --title / capability create --title
+    taskTitle: null,       // task create --title（同 title）
+    bountyCents: null,     // task create --bounty-cents
+    deliveryHours: null,   // task create --delivery-hours
+    taskTags: null,        // task create --tags (逗号分隔)
+  };
+  const positionals = [];
+
+  const args = [...argv];
+  while (args.length > 0) {
+    const a = args.shift();
+    if (a === '--json') {
+      flags.json = true;
+    } else if (a === '--no-wait') {
+      flags.noWait = true;
+    } else if (a === '--list') {
+      flags.list = true;
+    } else if (a === '--message') {
+      flags.message = args.shift() ?? null;
+    } else if (a === '--result') {
+      flags.result = args.shift() ?? null;
+    } else if (a === '--progress') {
+      const v = args.shift();
+      flags.progress = v != null ? parseInt(v, 10) : null;
+    } else if (a === '--note') {
+      flags.note = args.shift() ?? null;
+    } else if (a === '--reason') {
+      flags.reason = args.shift() ?? null;
+    } else if (a === '--refund-pct') {
+      const v = args.shift();
+      flags.refundPct = v != null ? parseInt(v, 10) : null;
+    } else if (a === '--idempotency-key') {
+      flags.idempotencyKey = args.shift() ?? null;
+    } else if (a === '--application-id') {
+      flags.applicationId = args.shift() ?? null;
+    } else if (a === '--error-code') {
+      flags.errorCode = args.shift() ?? null;
+    } else if (a === '--error-message') {
+      flags.errorMessage = args.shift() ?? null;
+    } else if (a === '--agent-id') {
+      flags.agentId = args.shift() ?? null;
+    } else if (a === '--deliverable-boundary') {
+      flags.deliverableBoundary = args.shift() ?? null;
+    } else if (a === '--description') {
+      flags.description = args.shift() ?? null;
+    } else if (a === '--type') {
+      flags.type = args.shift() ?? null;
+    } else if (a === '--category') {
+      flags.category = args.shift() ?? null;
+    } else if (a === '--tags') {
+      const v = args.shift() ?? '';
+      // 兼容：task create 和 capability create 都用 --tags
+      // 第一次遇到存入 tags，第二次（理论上不会）也存
+      flags.tags = v.split(',').map(t => t.trim()).filter(Boolean);
+    } else if (a === '--price-cents') {
+      const v = args.shift();
+      flags.priceCents = v != null ? parseInt(v, 10) : null;
+    } else if (a === '--title') {
+      flags.title = args.shift() ?? null;
+    } else if (a === '--bounty-cents') {
+      const v = args.shift();
+      flags.bountyCents = v != null ? parseInt(v, 10) : null;
+    } else if (a === '--delivery-hours') {
+      const v = args.shift();
+      flags.deliveryHours = v != null ? parseInt(v, 10) : null;
+    } else if (a.startsWith('--')) {
+      // 未知开关：暂忽略
+    } else {
+      positionals.push(a);
+    }
+  }
+
+  const [c0, c1, c2, c3] = positionals;
+  let command;
+
+  if (!c0) {
+    command = 'help';
+  } else if (c0 === 'auth' && c1 === 'login') {
+    command = 'auth:login';
+  } else if (c0 === 'wallet') {
+    command = 'wallet';
+  } else if (c0 === 'hall' && (c1 === 'browse' || c1 === undefined)) {
+    command = 'hall:browse';
+  } else if (c0 === 'ping') {
+    command = 'ping';
+  } else if (c0 === 'task') {
+    switch (c1) {
+      case 'create':       command = 'task:create'; break;
+      case 'apply':        command = 'task:apply'; break;
+      case 'select':       command = 'task:select'; break;
+      case 'accept':       command = 'task:accept'; break;
+      case 'start':        command = 'task:start'; break;
+      case 'heartbeat':    command = 'task:heartbeat'; break;
+      case 'deliver':      command = 'task:deliver'; break;
+      case 'fail':         command = 'task:fail'; break;
+      case 'confirm':      command = 'task:confirm'; break;
+      case 'reject':       command = 'task:reject'; break;
+      case 'revise':       command = 'task:revise'; break;
+      case 'accept-partial': command = 'task:accept-partial'; break;
+      case 'cancel':       command = 'task:cancel'; break;
+      default:             command = 'unknown';
+    }
+  } else if (c0 === 'capability') {
+    switch (c1) {
+      case 'create':       command = 'capability:create'; break;
+      case 'publish':      command = 'capability:publish'; break;
+      default:             command = 'unknown';
+    }
+  } else if (c0 === 'qa') {
+    // qa <task_id> <message> 或 qa <task_id> --list
+    command = flags.list ? 'qa:list' : 'qa:post';
+  } else if (c0 === 'autonomy' && c1 === 'tick') {
+    command = 'autonomy:tick';
+  } else if (c0 === 'help' || c0 === '--help' || c0 === '-h') {
+    command = 'help';
+  } else {
+    command = 'unknown';
+  }
+
+  // raw 保留向后兼容（旧测试用 r.raw 引用位置参数）
+  return { command, flags, positionals, raw: positionals };
+}

package/src/config.js

@@ -0,0 +1,17 @@
+// 平台地址解析。默认连官方平台，环境变量可覆盖指向本地测试栈。
+//
+// 优先级：LINGER_BASE_URL > A2A_BASE_URL > 官方默认。
+// （A2A_BASE_URL 与后端 oauth.py 同名，运维同一变量即可统一切换。）
+
+/** 官方默认平台地址（CTO 拍板·M3 前提）。 */
+export const DEFAULT_BASE_URL = 'https://a2a.linger.chimap.cn';
+
+/**
+ * 解析平台基础地址。
+ * @param {Record<string,string>} env 环境变量字典（默认 process.env，传入便于单测）
+ * @returns {string} 去掉末尾斜杠的平台地址
+ */
+export function resolveBaseUrl(env = process.env) {
+  const raw = env.LINGER_BASE_URL || env.A2A_BASE_URL || DEFAULT_BASE_URL;
+  return raw.replace(/\/+$/, '');
+}

package/src/credentials.js

@@ -0,0 +1,57 @@
+// 凭证存取：登录拿到的 token 落到用户本机 ~/.linger/credentials。
+//
+// 设计要点：
+//   - 文件权限 0600（仅本人可读写）——同机其它账户偷不到 token。
+//   - 读损坏 / 不存在 → 返回 null（当作没登录），绝不抛异常炸掉命令。
+//   - 目录可通过 opts.dir 覆盖（单测用临时目录，不污染真实 ~/.linger）。
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** 凭证目录：默认 ~/.linger，可被 opts.dir 覆盖（测试用）。 */
+function credDir(opts = {}) {
+  return opts.dir || path.join(os.homedir(), '.linger');
+}
+
+/** 凭证文件完整路径（~/.linger/credentials）。 */
+export function credentialsPath(opts = {}) {
+  return path.join(credDir(opts), 'credentials');
+}
+
+/**
+ * 保存凭证到本机文件（0600 权限）。
+ * creds 形如 { access_token, refresh_token, token_type, expires_in, base_url }。
+ */
+export function saveCredentials(creds, opts = {}) {
+  const dir = credDir(opts);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = credentialsPath(opts);
+  // 先写内容，再显式 chmod 0600（mkdirSync 的 mode 受 umask 影响，chmod 才确定性）
+  fs.writeFileSync(file, JSON.stringify(creds, null, 2), { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // 某些文件系统（如 Windows / 网络盘）不支持 chmod —— 不致命，忽略
+  }
+  return file;
+}
+
+/**
+ * 读取本机凭证。
+ * 文件不存在或内容损坏 → 返回 null（当作未登录），不抛异常。
+ */
+export function loadCredentials(opts = {}) {
+  const file = credentialsPath(opts);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null; // 文件不存在 / 读不了 → 未登录
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null; // 内容损坏 → 当作未登录
+  }
+}