global-app-skill 0.1.0 → 0.1.2

package/README.md

@@ -10,7 +10,7 @@
 npx -y --prefer-online global-app-skill@latest skill install
 ```
 
-默认只安装 `~/.agents/skills/overseas-app-research/SKILL.md`。也可用 `--dir /absolute/skills/overseas-app-research` 指定当前客户端实际使用的 skill 目录。已存在的 SKILL.md 会被原子替换，目录中的其他文件保留，符号链接入口拒绝覆盖。安装不下载 references，也不修改 MCP 或客户端配置。安装后让客户端重新加载 skills。
+默认只安装 `~/.agents/skills/overseas-app-research/SKILL.md`。也可用 `--dir /absolute/skills/overseas-app-research` 指定当前客户端实际使用的 skill 目录。安装器把该目录写入入口的 `--skill-dir` 参数，并在同一文件中记录 CLI 版本。已存在的 SKILL.md 会被原子替换，目录中的其他文件保留，符号链接入口拒绝覆盖。安装不下载 references，也不修改 MCP 或客户端配置。
 
 ## 执行
 
@@ -20,6 +20,12 @@ npx -y --prefer-online global-app-skill@latest context resolve --mode research
 
 `--mode` 为 `download`、`research` 或 `ued`。CLI 每次查询 GitHub 的 `releases/latest.json`，验证清单、压缩包及逐文件 SHA-256，返回绝对 `resourceRoot` 和有序 `mustRead`。agent 读取这些文件后按原工作流编排任务。
 
+`context resolve` 和 `run` 执行前会将已安装的薄入口同步为当前 CLI 捆绑的版本。入口使用 `npx --prefer-online ...@latest`，因此发布新版 CLI 后，下一次执行会更新本地 SKILL.md。传入 `--skill-dir /absolute/skill-directory` 可精确定位安装目录；安装器已自动写入该参数。未传入时仅检查 `~/.agents/skills/overseas-app-research` 和 `${CODEX_HOME:-~/.codex}/skills/overseas-app-research` 中现有的 CLI 入口，不创建新 skill，不覆盖手工维护的其他实现或符号链接，也不降级更新的入口。
+
+自定义目录中的入口若未包含 `--skill-dir`，重新执行一次 `skill install --dir ...` 写入准确目录。`context resolve` 的 `skillUpdate` 单独报告入口同步结果；同步失败会明确显示，资源解析仍可独立进行。脚本 stdout 和退出码保持不变，同步日志写入 stderr。
+
+本地文件更新后，新入口在客户端重新加载 skill 时采用；已经读入当前任务的上下文不因磁盘替换自动改写。[Codex 官方文档](https://learn.chatgpt.com/docs/build-skills)说明会自动检测 skill 变更；如果没有显示更新，可重启 Codex。其他客户端遵循各自的重新加载规则。
+
 ```sh
 npx -y --prefer-online global-app-skill@latest run preflight --mode research --resource-root /absolute/resolved/hash -- --report /absolute/task/environment.json
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "global-app-skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Thin skill bootstrap and GitHub resource runner for overseas Android app research",
   "type": "module",
   "license": "UNLICENSED",

package/skills/overseas-app-research/SKILL.md

@@ -10,9 +10,9 @@ description: 调研海外 Android App 的业务流程、功能入口、字段权
 按目标选择 `download`（仅取包）、`research`（业务调研，含同时需要图册）或 `ued`（仅界面图册），执行：
 
 ```sh
-npx -y --prefer-online global-app-skill@latest context resolve --mode MODE
+npx -y --prefer-online global-app-skill@latest context resolve --skill-dir SKILL_DIRECTORY --mode MODE
 ```
 
-依次读取返回的全部 `mustRead`，按其中流程执行；以返回的 `resourceRoot` 解析文档、模板和脚本。新任务重新 resolve，同一任务沿用已读快照。更新或校验失败时停止依赖工作并报告原因，不静默使用旧资源。
+`SKILL_DIRECTORY` 为本 SKILL.md 所在绝对目录。CLI 同步本地入口，检查 `skillUpdate` 并报告失败；新入口在客户端重新加载后采用。依次读取全部 `mustRead`，以 `resourceRoot` 解析资源并按流程执行。新任务重新 resolve，同一任务沿用已读快照。资源更新或校验失败时停止依赖工作，不静默使用旧资源。
 
-脚本通过 `npx -y --prefer-online global-app-skill@latest run SCRIPT --mode MODE --resource-root RESOURCE_ROOT -- 参数` 执行；可用脚本及参数见解析后的 CLI 文档。业务判断与页面操作由 agent 按文档编排，CLI 成功不代表调研完成；关键进度仍须输出到聊天正文。
+脚本通过 `npx -y --prefer-online global-app-skill@latest run SCRIPT --skill-dir SKILL_DIRECTORY --mode MODE --resource-root RESOURCE_ROOT -- 参数` 执行；参数见解析后的 CLI 文档。业务判断与页面操作由 agent 按文档编排，CLI 成功不代表调研完成；关键进度仍须输出到聊天正文。

package/src/cli.mjs

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
-import { installSkill } from './skill.mjs';
+import { installSkill, syncInstalledSkills } from './skill.mjs';
 import { resolveContext } from './resources.mjs';
 import { runScript } from './run.mjs';
 import { validateMode, VERSION } from './protocol.mjs';
 
 const usage = `global-app-skill ${VERSION}
   skill install [--dir ABSOLUTE_SKILL_DIRECTORY]
-  context resolve --mode download|research|ued [--cache-dir PATH] [--feed HTTPS_MANIFEST_URL]
-  run SCRIPT [--mode download|research|ued] [--resource-root PATH] [--cache-dir PATH] [--feed URL] -- SCRIPT_ARGS
+  context resolve --mode download|research|ued [--skill-dir PATH] [--cache-dir PATH] [--feed HTTPS_MANIFEST_URL]
+  run SCRIPT [--mode download|research|ued] [--skill-dir PATH] [--resource-root PATH] [--cache-dir PATH] [--feed URL] -- SCRIPT_ARGS
   --version
 
 skill install writes only SKILL.md; default: ~/.agents/skills/overseas-app-research.
+context resolve and run synchronize existing managed skill entries from this CLI bundle.
 run uses a verified pinned snapshot when --resource-root is supplied; otherwise it resolves current resources.
 Script stdout/stderr and exit code are preserved. JSON command results go to stdout; progress goes to stderr.
 `;
@@ -20,7 +21,7 @@ export async function main(argv) {
   const separator = argv.indexOf('--');
   const { values, positionals } = parseArgs({
     args: separator < 0 ? argv : argv.slice(0, separator), allowPositionals: true,
-    options: { dir: { type: 'string' }, mode: { type: 'string' }, 'resource-root': { type: 'string' },
+    options: { dir: { type: 'string' }, 'skill-dir': { type: 'string' }, mode: { type: 'string' }, 'resource-root': { type: 'string' },
       'cache-dir': { type: 'string' }, feed: { type: 'string' }, help: { type: 'boolean' }, version: { type: 'boolean' } },
   });
   if (values.version) { console.log(VERSION); return; }
@@ -28,8 +29,8 @@ export async function main(argv) {
   const [command, action] = positionals;
   if (positionals.length !== 2 || (separator >= 0 && command !== 'run')) throw new Error('Invalid command; use --help');
   const allowed = command === 'skill' && action === 'install' ? ['dir'] :
-    command === 'context' && action === 'resolve' ? ['mode', 'cache-dir', 'feed'] :
-    command === 'run' ? ['mode', 'resource-root', 'cache-dir', 'feed'] : null;
+    command === 'context' && action === 'resolve' ? ['mode', 'skill-dir', 'cache-dir', 'feed'] :
+    command === 'run' ? ['mode', 'skill-dir', 'resource-root', 'cache-dir', 'feed'] : null;
   if (!allowed) throw new Error('Unknown command; use --help');
   for (const key of Object.keys(values)) {
     if (!allowed.includes(key)) throw new Error(`--${key} is not supported by ${command} ${action}`);
@@ -37,16 +38,25 @@ export async function main(argv) {
   const options = { mode: values.mode || 'research', resourceRoot: values['resource-root'], cacheDir: values['cache-dir'],
     feed: values.feed, progress: message => process.stderr.write(`[global-app-skill] ${message}\n`) };
   if (command !== 'skill') validateMode(command === 'context' ? values.mode : options.mode);
+  if (command === 'run' && options.resourceRoot && (values.feed || values['cache-dir'])) {
+    throw new Error('--resource-root cannot be combined with --feed or --cache-dir');
+  }
+  const skillUpdate = command === 'skill' ? undefined : await syncInstalledSkills({ directory: values['skill-dir'] });
+  for (const entry of skillUpdate?.installations || []) {
+    if (entry.status === 'updated') process.stderr.write(`[global-app-skill] Updated local entry: ${entry.skillPath}; reload the skill to use new discovery instructions\n`);
+    if (entry.status === 'failed') process.stderr.write(`[global-app-skill] Skill entry update failed: ${entry.skillPath}: ${entry.error}\n`);
+  }
   if (command === 'run') {
-    if (options.resourceRoot && (values.feed || values['cache-dir'])) throw new Error('--resource-root cannot be combined with --feed or --cache-dir');
     process.exitCode = await runScript(action, separator < 0 ? [] : argv.slice(separator + 1), options);
     return;
   }
-  const output = command === 'skill' ? await installSkill(values.dir) : await resolveContext(options);
+  let output;
+  try { output = command === 'skill' ? await installSkill(values.dir) : { ...await resolveContext(options), skillUpdate }; }
+  catch (error) { error.skillUpdate = skillUpdate; throw error; }
   console.log(JSON.stringify(output, null, 2));
 }
 
 main(process.argv.slice(2)).catch(error => {
-  process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + '\n');
+  process.stderr.write(JSON.stringify({ ok: false, error: error.message, ...(error.skillUpdate ? { skillUpdate: error.skillUpdate } : {}) }) + '\n');
   process.exitCode = 1;
 });

package/src/resources.mjs

@@ -1,6 +1,7 @@
 import { lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { gunzipSync } from 'node:zlib';
 import { FEED, MAX_BYTES, MODES, sha256, validateManifest, validateMode } from './protocol.mjs';
 
@@ -81,10 +82,25 @@ export async function resolveContext({ mode, feed = FEED, cacheDir, progress = (
         await writeFile(target, file.content, { flag: 'wx' });
       }
       await writeFile(path.join(staging, 'manifest.json'), JSON.stringify(manifest));
-      if (!(await validSnapshot(resourceRoot, manifest.resourceHash))) await rm(resourceRoot, { recursive: true, force: true });
-      try { await rename(staging, resourceRoot); }
-      catch (error) {
-        if (!['EEXIST', 'ENOTEMPTY'].includes(error.code) || !(await validSnapshot(resourceRoot, manifest.resourceHash))) throw error;
+      const lock = path.join(releases, `.${manifest.resourceHash}.lock`);
+      const deadline = Date.now() + 5000;
+      for (;;) {
+        try { await mkdir(lock); break; }
+        catch (error) {
+          if (error.code !== 'EEXIST') throw error;
+          if (Date.now() >= deadline) throw new Error(`Snapshot publication is locked: ${lock}; retry after the other updater finishes. Remove a stale lock only when no updater is running.`);
+          await delay(50);
+        }
+      }
+      try {
+        // Recheck under the lock so a concurrent resolver's completed snapshot
+        // cannot be deleted after an earlier ENOENT integrity check.
+        if (!(await validSnapshot(resourceRoot, manifest.resourceHash))) {
+          await rm(resourceRoot, { recursive: true, force: true });
+          await rename(staging, resourceRoot);
+        }
+      } finally {
+        await rm(lock, { recursive: true, force: true });
       }
       updated = true;
     } finally { await rm(staging, { recursive: true, force: true }); }

package/src/skill.mjs

@@ -2,21 +2,75 @@ import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { VERSION } from './protocol.mjs';
 
-export async function installSkill(directory) {
-  const target = path.resolve(directory || path.join(homedir(), '.agents/skills/overseas-app-research'));
+async function stat(filename) {
+  try { return await lstat(filename); }
+  catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+}
+
+async function writeSkill(target, existingOnly) {
   const skillPath = path.join(target, 'SKILL.md');
   for (const filename of [target, skillPath]) {
-    try {
-      if ((await lstat(filename)).isSymbolicLink()) throw new Error(`Refusing to replace a symlinked skill: ${filename}`);
-    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if ((await stat(filename))?.isSymbolicLink()) {
+      if (existingOnly) return { skillPath, status: 'skipped', reason: 'symlink' };
+      throw new Error(`Refusing to replace a symlinked skill: ${filename}`);
+    }
+  }
+  if (existingOnly && !(await stat(skillPath))) return { skillPath, status: 'skipped', reason: 'not-installed' };
+  if (!existingOnly) await mkdir(target, { recursive: true });
+  const lock = path.join(target, '.global-app-skill-lock');
+  const deadline = Date.now() + 5000;
+  for (;;) {
+    try { await mkdir(lock); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (Date.now() >= deadline) throw new Error(`Skill update is locked: ${lock}; retry after the other updater finishes`);
+      await delay(50);
+    }
   }
-  const content = await readFile(new URL('../skills/overseas-app-research/SKILL.md', import.meta.url), 'utf8');
-  await mkdir(target, { recursive: true });
-  const temporary = path.join(target, `.SKILL-${randomUUID()}.tmp`);
   try {
-    await writeFile(temporary, content, { flag: 'wx' });
-    await rename(temporary, skillPath);
-  } finally { await rm(temporary, { force: true }); }
-  return { ok: true, skillPath };
+    let previous;
+    try { previous = await readFile(skillPath, 'utf8'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (existingOnly && !previous?.includes('global-app-skill@latest context resolve')) {
+      return { skillPath, status: 'skipped', reason: 'not-managed' };
+    }
+    const installedVersion = previous?.match(/^<!-- global-app-skill-version: (\d+\.\d+\.\d+) -->$/m)?.[1];
+    if (installedVersion) {
+      const installed = installedVersion.split('.').map(Number), bundled = VERSION.split('.').map(Number);
+      for (let i = 0; i < 3; i++) {
+        if (installed[i] < bundled[i]) break;
+        if (installed[i] > bundled[i]) return { skillPath, status: 'skipped', reason: 'newer-installed', installedVersion };
+      }
+    }
+    const bundled = await readFile(new URL('../skills/overseas-app-research/SKILL.md', import.meta.url), 'utf8');
+    const quotedDirectory = "'" + target.replaceAll("'", "'\\''") + "'";
+    const content = bundled.replaceAll('SKILL_DIRECTORY', quotedDirectory).trimEnd() + `\n\n<!-- global-app-skill-version: ${VERSION} -->\n`;
+    if (previous === content) return { skillPath, status: 'unchanged' };
+    const temporary = path.join(target, `.SKILL-${randomUUID()}.tmp`);
+    try {
+      await writeFile(temporary, content, { flag: 'wx' });
+      await rename(temporary, skillPath);
+    } finally { await rm(temporary, { force: true }); }
+    return { skillPath, status: previous === undefined ? 'installed' : 'updated' };
+  } finally { await rm(lock, { recursive: true, force: true }); }
+}
+
+export async function installSkill(directory) {
+  return { ok: true, ...await writeSkill(path.resolve(directory || path.join(homedir(), '.agents/skills/overseas-app-research')), false) };
+}
+
+export async function syncInstalledSkills({ directory, directories = [
+  path.join(homedir(), '.agents/skills/overseas-app-research'),
+  path.join(process.env.CODEX_HOME || path.join(homedir(), '.codex'), 'skills/overseas-app-research'),
+] } = {}) {
+  const targets = [...new Set((directory ? [directory] : directories).map(target => path.resolve(target)))];
+  const installations = [];
+  for (const target of targets) {
+    try { installations.push(await writeSkill(target, true)); }
+    catch (error) { installations.push({ skillPath: path.join(target, 'SKILL.md'), status: 'failed', error: error.message }); }
+  }
+  return { ok: !installations.some(entry => entry.status === 'failed'), installations };
 }