@morehao/dsh-skills-console 0.2.1 → 0.2.3

package/lib/core/updates.js

@@ -25,6 +25,27 @@ export function githubToken(env = process.env) {
   return env.GITHUB_TOKEN || env.GH_TOKEN || null;
 }
 
+/**
+ * 限流相关响应头。GitHub 对匿名请求按**出口 IP** 记 60 次/小时，403 时这三个头是
+ * 用户唯一能拿到的可执行信息（还剩多少、什么时候恢复、要不要等）。
+ */
+function rateLimitOf(response) {
+  const read = (name) => {
+    const value = response?.headers?.get?.(name);
+    return value === null || value === undefined || value === '' ? null : String(value);
+  };
+  const reset = read('x-ratelimit-reset');
+  const retryAfter = read('retry-after');
+  const resetAt = reset && /^\d+$/.test(reset) ? Number(reset) * 1000 : null;
+  return { remaining: read('x-ratelimit-remaining'), resetAt, retryAfter };
+}
+
+/** 403 + 剩余 0，或 429 —— 与上游判定一致（blob.ts:147-152）。 */
+export function isRateLimited(status, rateLimit) {
+  if (status === 429) return true;
+  return status === 403 && rateLimit?.remaining === '0';
+}
+
 async function callJson(url, { token, etag, fetchImpl = fetch } = {}) {
   const headers = {
     accept: 'application/vnd.github+json',
@@ -34,13 +55,14 @@ async function callJson(url, { token, etag, fetchImpl = fetch } = {}) {
   if (token) headers.authorization = `Bearer ${token}`;
   if (etag) headers['if-none-match'] = etag;
   const response = await fetchImpl(url, { headers });
-  if (response.status === 304) return { status: 304, notModified: true, etag };
+  const rateLimit = rateLimitOf(response);
+  if (response.status === 304) return { status: 304, notModified: true, etag, rateLimit };
   if (!response.ok) {
     const text = await response.text().catch(() => '');
-    return { status: response.status, error: `HTTP ${response.status} ${text.slice(0, 200)}` };
+    return { status: response.status, error: `HTTP ${response.status} ${text.slice(0, 200)}`, rateLimit };
   }
   const body = await response.json();
-  return { status: response.status, body, etag: response.headers.get('etag') };
+  return { status: response.status, body, etag: response.headers.get('etag'), rateLimit };
 }
 
 /**
@@ -53,7 +75,15 @@ export async function fetchTree({ source, ref = 'main', etag, token, fetchImpl }
   const url = `${API}/repos/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
   const result = await callJson(url, { token, etag, fetchImpl });
   if (result.notModified) return { notModified: true, etag: result.etag };
-  if (result.error) return { error: result.error, status: result.status };
+  if (result.error) {
+    return {
+      error: result.error,
+      status: result.status,
+      rateLimited: isRateLimited(result.status, result.rateLimit),
+      resetAt: result.rateLimit?.resetAt ?? null,
+      rateLimit: result.rateLimit,
+    };
+  }
   const tree = Array.isArray(result.body?.tree) ? result.body.tree : [];
   return {
     tree,
@@ -64,6 +94,33 @@ export async function fetchTree({ source, ref = 'main', etag, token, fetchImpl }
   };
 }
 
+/**
+ * 仓库默认分支。`ref` 缺省时以它为准：不少技能仓库默认是 `master`，
+ * 硬套 `main` 只会得到 404（例如 alchaincyf/huashu-design）。
+ *
+ * 返回结构化结果而不是 `string | null`：调用方要靠 `status` / `rateLimited` / `resetAt`
+ * 把「仓库不存在」「被限流」「网络不通」拆成三句不同的话（T1）。
+ */
+export async function fetchDefaultBranch({ source, token, fetchImpl } = {}) {
+  const parsed = parseSource(source);
+  if (!parsed) {
+    return { branch: null, status: null, rateLimited: false, resetAt: null, error: 'invalid-source' };
+  }
+  let result;
+  try {
+    result = await callJson(`${API}/repos/${parsed.owner}/${parsed.repo}`, { token, fetchImpl });
+  } catch (error) {
+    return { branch: null, status: null, rateLimited: false, resetAt: null, error: error?.message || String(error) };
+  }
+  const rateLimit = result.rateLimit || {};
+  const rateLimited = isRateLimited(result.status, rateLimit);
+  const base = { status: result.status ?? null, rateLimited, resetAt: rateLimit.resetAt ?? null };
+  if (result.error) return { ...base, branch: null, error: result.error };
+  const branch = result.body?.default_branch;
+  if (!branch) return { ...base, branch: null, error: 'response has no default_branch' };
+  return { ...base, branch, error: null };
+}
+
 /** 解析 ref 对应的 commit（只在安装/计划时需要，检测阶段不付这笔成本）。 */
 export async function resolveCommit({ source, ref = 'main', token, fetchImpl } = {}) {
   const parsed = parseSource(source);
@@ -76,6 +133,18 @@ export async function resolveCommit({ source, ref = 'main', token, fetchImpl } =
   return result.body.sha;
 }
 
+const TREE_SHA_RE = /^[0-9a-f]{40}$/;
+
+/**
+ * lock 的 `skillFolderHash` 形态。CLI 取不到树时（限流）会把 64 位内容哈希写进同一个字段
+ * （`add.ts:2254`），所以形态取决于**安装那一刻 API 通不通**，不是取决于来源类型。
+ * `tree` = 40 位 git tree SHA；`content` = 64 位内容哈希；`missing` = 没有这个字段。
+ */
+export function hashShape(value) {
+  if (!value || typeof value !== 'string') return 'missing';
+  return TREE_SHA_RE.test(value) ? 'tree' : 'content';
+}
+
 /** `KEY` + `/dir/SKILL.md` → `dir`（F18：`skillPath` 是文件路径，目录运算先 dirname）。 */
 export function skillDir(skillPath) {
   const parts = String(skillPath).split('/');
@@ -114,22 +183,41 @@ export function listSkillsFromTree({ tree, rootSha, subpath, repoName }) {
 }
 
 /**
- * 单技能判定（L2/L3）。哈希形态必须配对（F19）：
- * `sourceType=github` 时 lock 里应是 40 位 tree SHA；64 位内容哈希说明来源形态不对，直接给 `unknown`。
+ * 单技能判定（L2/L3）。
+ *
+ * 基线取「第一个 40 位 tree SHA」：优先 lock 的 `skillFolderHash`，其次安装时记下的
+ * `state.installs[].treeSha`。CLI 在限流时会退化成 64 位内容哈希（`add.ts:2236`/`2254`），
+ * 那玩意儿与上游 tree SHA 不同源，直接比必然不等 —— 既不能判 `current`，也不该判
+ * `update-available`，此时改用手边记下的基线；两样都没有才给 `unknown`（老状态，行为与以前一致）。
  */
-export function checkSkill({ lockHash, snapshotEntry, tree, rootSha }) {
+export function checkSkill({ lockHash, recordedTreeSha, snapshotEntry, tree, rootSha }) {
   if (!snapshotEntry) return { status: 'upstream-deleted', detail: '上游整树里已找不到这个 skillPath' };
-  if (!lockHash) return { status: 'unknown', detail: 'lock 里没有 skillFolderHash' };
-  if (!/^[0-9a-f]{40}$/.test(lockHash)) {
+  const baseline = TREE_SHA_RE.test(String(lockHash || ''))
+    ? { sha: lockHash, from: 'lock' }
+    : TREE_SHA_RE.test(String(recordedTreeSha || ''))
+      ? { sha: recordedTreeSha, from: 'recorded' }
+      : null;
+  if (!baseline) {
     return {
       status: 'unknown',
-      detail: 'lock 的哈希不是 40 位 tree SHA（形态不配对），无法按 tree 比对',
+      detail: 'lock 里没有 40 位 tree SHA，安装时也未记录基线，无法按 tree 比对',
     };
   }
   const target = skillTreeSha({ tree, skillPath: snapshotEntry.skillPath, rootSha });
   if (!target) return { status: 'unknown', detail: '整树里找不到该目录的 tree 条目' };
-  if (target === lockHash) return { status: 'current', detail: '与安装时的 tree SHA 一致' };
-  return { status: 'update-available', detail: 'tree SHA 已变化', targetTreeSha: target };
+  if (target === baseline.sha) {
+    return {
+      status: 'current',
+      detail: baseline.from === 'lock' ? '与安装时的 tree SHA 一致' : '与安装时记录的 tree SHA 一致',
+      baseline: baseline.from,
+    };
+  }
+  return {
+    status: 'update-available',
+    detail: `tree SHA 已变化（基线来自 ${baseline.from}）`,
+    targetTreeSha: target,
+    baseline: baseline.from,
+  };
 }
 
 /** 计划 → 应用的防换手 token：磁盘或上游在"计划"之后被改动就拒绝（设计 §7.4③）。 */

package/lib/routes.js

@@ -59,6 +59,7 @@ function matchRoute(method, pathname) {
   if (segments.length === 1 && segments[0] === 'settings' && method === 'POST') return { name: 'settings' };
   if (segments.length === 1 && segments[0] === 'links' && method === 'POST') return { name: 'links' };
   if (segments.length === 1 && segments[0] === 'install' && method === 'POST') return { name: 'install' };
+  if (segments.length === 1 && segments[0] === 'probe' && method === 'POST') return { name: 'probe' };
   if (segments.length === 1 && segments[0] === 'diagnostics' && method === 'GET') return { name: 'diagnostics' };
 
   if (segments[0] === 'skills' && segments.length === 2 && method === 'GET') {
@@ -154,6 +155,8 @@ async function dispatch(route, { body, query, service }) {
       return service.setLinks(body);
     case 'install':
       return service.install(body);
+    case 'probe':
+      return service.probeSource(body);
     case 'diagnostics':
       return service.diagnostics();
     case 'skill.body':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morehao/dsh-skills-console",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "统一管理本地技能的安装、更新、删除与接入，让同一份技能在多个 Agent 间复用。A skill manager for DeepSeek Harness: install, update, remove, link and toggle agent skills.",
   "license": "MIT",
   "author": "morehao <morehao@qq.com>",