global-app-skill 0.1.2 → 0.1.5

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-dir` 参数，并在同一文件中记录 CLI 版本。已存在的 SKILL.md 会被原子替换，目录中的其他文件保留，符号链接入口拒绝覆盖。安装不下载 references，也不修改 MCP 或客户端配置。
+默认只安装 `~/.agents/skills/overseas-app-research/SKILL.md`。也可用 `--dir /absolute/skills/overseas-app-research` 指定当前客户端实际使用的 skill 目录。所有目录使用完全相同的薄入口，只记录 CLI 版本，不写入安装路径。安装位置记录在本机状态目录，供 CLI 后续自动发现；该记录不放进 skill。已存在的 SKILL.md 会被原子替换，目录中的其他文件保留，符号链接入口拒绝覆盖。安装不下载 references，也不修改 MCP 或客户端配置。
 
 ## 执行
 
@@ -18,11 +18,15 @@ npx -y --prefer-online global-app-skill@latest skill install
 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 读取这些文件后按原工作流编排任务。
+`--mode` 为 `download`、`research` 或 `ued`。CLI 每次查询 GitHub 最新正式 Release 的 `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，不覆盖手工维护的其他实现或符号链接，也不降级更新的入口。
+`context resolve` 和 `run` 执行前由 CLI 自动定位已安装的薄入口，更新为当前 CLI 捆绑的版本。入口只调用通用命令，不传安装路径。入口使用 `npx --prefer-online ...@latest`，因此发布新版 CLI 后，下一次执行会更新本地 SKILL.md。
 
-自定义目录中的入口若未包含 `--skill-dir`，重新执行一次 `skill install --dir ...` 写入准确目录。`context resolve` 的 `skillUpdate` 单独报告入口同步结果；同步失败会明确显示，资源解析仍可独立进行。脚本 stdout 和退出码保持不变，同步日志写入 stderr。
+CLI 检查以下位置中的 `overseas-app-research/SKILL.md`：用户目录下的 `.agents/skills`、`.codex/skills`、`.claude/skills`、`.cursor/skills`、`.gemini/skills`、`.kiro/skills`；当前目录至最近 Git 仓库根目录之间的相同项目级目录；`CODEX_HOME/skills`；以及 CLI 安装时登记的目录。不在 Git 仓库内时，项目级发现只检查当前目录，不遍历其他工作区。
+
+自定义安装目录通过 `skill install --dir ...` 登记在 `${XDG_STATE_HOME:-~/.local/state}/global-app-skill/installations/`，不需要把路径写进 SKILL.md。复制到另一台机器的标准 skill 目录后，CLI 会按该机器环境重新发现；移到标准目录以外的位置时，再运行一次安装命令登记新位置。`--skill-dir` 仅保留为手动指定本次更新目标的可选参数，薄入口无需使用。
+
+自动同步只更新已经存在且属于本 CLI 的入口，不创建其他客户端的 skill，不覆盖手工维护的其他实现或符号链接，也不降级更新的入口。`context resolve` 的 `skillUpdate` 单独报告同步结果；失败会明确显示，资源解析仍可独立进行。脚本 stdout 和退出码保持不变，同步日志写入 stderr。
 
 本地文件更新后，新入口在客户端重新加载 skill 时采用；已经读入当前任务的上下文不因磁盘替换自动改写。[Codex 官方文档](https://learn.chatgpt.com/docs/build-skills)说明会自动检测 skill 变更；如果没有显示更新，可重启 Codex。其他客户端遵循各自的重新加载规则。
 
@@ -44,9 +48,11 @@ npx -y --prefer-online global-app-skill@latest run preflight --mode research --r
 | `resources/overseas-app-research/scripts/` | 原有 Python 脚本及回归测试 |
 | `resources/overseas-app-research/examples/` | 业务报告模板 |
 | `scripts/build-resources.mjs` | 生成确定性的资源包与清单 |
-| `releases/` | GitHub 托管的最新清单与按哈希命名的资源包 |
+| `.github/workflows/publish.yml` | tag 触发的构建、GitHub Release 和 npm 发布 |
+| `scripts/release.mjs` | tag 校验、打包、校验和及发布资产核对 |
+| `dist/release/` | 本次构建的 Release 资产，不提交到 Git |
 
-分发源为 `https://raw.githubusercontent.com/shiguang-lab/global-app-skill/main/releases/latest.json`。npm 包仅包含 CLI 与薄 skill，工作流资源独立从 GitHub 更新，无需为文档或 Python 脚本修改发布 npm 新版本。
+分发源为 `https://github.com/shiguang-lab/global-app-skill/releases/latest/download/latest.json`。资源源码在仓库的 `resources/`，正式生成包由 Actions 上传到 GitHub Release。清单中的 `releaseTag` 决定资源包的固定下载地址，因此 latest 切换不会混用不同 Release 的清单和包。npm 包仅包含 CLI 与薄 skill；工作流资源可独立发布，不要求发布 npm 新版本。
 
 缓存默认位于 `~/.cache/global-app-skill/releases/<resourceHash>`，可用 `GLOBAL_APP_SKILL_CACHE` 或 `--cache-dir` 指定。下载先在临时目录完整校验，再发布快照。网络或完整性失败会报错，不静默使用旧资源；损坏的固定快照拒绝执行，重新 resolve 可修复。旧快照保留供现有任务使用。运行产物写入工作区，不写回资源缓存。
 
@@ -55,14 +61,44 @@ npx -y --prefer-online global-app-skill@latest run preflight --mode research --r
 在当前仓库编辑资源后：
 
 ```sh
-npm run resources:build
 npm test
 npm run test:python
-npm run resources:check
+npm run release:prepare
 ```
 
-Python 回归测试中的长图部分需要 Pillow。CLI 无第三方 Node 依赖。`--feed` 可指定 HTTPS 清单，测试允许 loopback HTTP，用于在发布前验证同一协议。
+Python 回归测试中的长图部分需要 Pillow。CLI 无第三方 Node 依赖。`--feed` 可指定 HTTPS 清单，测试允许 loopback HTTP。`release:prepare` 在本地预演与 Actions 相同的构建，默认 tag 为 `v<package.json.version>`，也可指定 `RELEASE_TAG`。构建结果进入忽略的 `dist/release/`，不手工上传。
+
+### 发布 CLI、薄入口与资源
+
+修改源码并更新 `package.json` 的版本，提交、push 后创建对应版本的 tag。例如版本为 `0.1.3` 时：
+
+```sh
+git tag v0.1.3
+git push origin v0.1.3
+```
+
+`publish.yml` 校验 tag 与 package.json 一致，执行 Node/Python 测试，从 tag 源码生成以下资产：
+
+- `latest.json`：资源清单、Release tag、最低 CLI 版本、逐文件哈希。
+- `<resourceHash>.json.gz`：references、scripts、examples 的完整快照。
+- `global-app-skill.tgz`：同一 tag 构建的 CLI 安装包。
+- `SHA256SUMS`：上述三个资产的校验和。
+
+Actions 先创建草稿 Release，上传所有已验证资产后发布为 latest，随后把同一个 CLI tgz 发布到 npm。npm 发布失败不会删除已经完整发布的 GitHub Release。重跑时先核对已发布资产；正式 Release 不覆盖不同字节的包。
+
+### 仅发布资源
+
+修改资源源码并提交，创建独立的资源 tag，例如：
+
+```sh
+git tag resources-v0.1.4
+git push origin resources-v0.1.4
+```
+
+该 tag 只发布 GitHub Release，跳过 npm。客户端下次 resolve 自动获取新资源。资源工作流仍包含完整快照，删除的源文件不会残留到新快照。已有任务继续使用其固定快照。不要删除历史 Release 的资源资产。
+
+### 一次性配置 npm 发布认证
 
-将资源源文件、`releases/latest.json` 和新资源包一起提交并 push 到 GitHub 的 `main`。保留旧资源包，避免读到旧清单的客户端遇到 404。只修改资源时到此即可，后续任务自动获取最新快照；每个快照完整包含 references、scripts 和 examples，删除的源文件不会残留到新快照。
+在 GitHub 仓库 Actions secrets 中配置拥有 `global-app-skill` 发布权限的 `NPM_TOKEN`，工作流将其绑定到 npm 使用的 `NODE_AUTH_TOKEN`，不读取或复制本机 token。也可在 npm 包 Settings 中配置 GitHub Actions Trusted Publisher：组织 `shiguang-lab`、仓库 `global-app-skill`、工作流文件 `publish.yml`、允许 `npm publish`，不设置 environment。工作流保留 `id-token: write`，供 OIDC 与 provenance 使用。GitHub Release 使用 Actions 自带的 `GITHUB_TOKEN` 与 `contents: write`。
 
-修改 CLI 或薄入口时更新 `package.json` 的版本，完成检查并推送代码后执行 `npm publish`。`prepublishOnly` 会执行 Node/Python 测试和资源一致性检查。初次发布需要 npm 登录和账号所要求的发布认证；GitHub 仓库需公开可读，才能使用默认免认证资源源。当前项目未授予开源许可证，npm 元数据使用 `UNLICENSED`。
+以后只推 tag，由 Actions 发布，不在本机执行 `npm publish`。当前项目未授予开源许可证，npm 元数据使用 `UNLICENSED`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "global-app-skill",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Thin skill bootstrap and GitHub resource runner for overseas Android app research",
   "type": "module",
   "license": "UNLICENSED",
@@ -17,6 +17,7 @@
     "test:python": "python3 -m unittest discover -s resources/overseas-app-research/scripts -p 'test_*.py'",
     "resources:build": "node scripts/build-resources.mjs",
     "resources:check": "node scripts/build-resources.mjs --check",
-    "prepublishOnly": "npm test && npm run test:python && npm run resources:check"
+    "release:prepare": "node scripts/release.mjs",
+    "prepublishOnly": "npm test && npm run test:python && npm run resources:build && npm run resources:check"
   }
 }

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 --skill-dir SKILL_DIRECTORY --mode MODE
+npx -y --prefer-online global-app-skill@latest context resolve --mode MODE
 ```
 
-`SKILL_DIRECTORY` 为本 SKILL.md 所在绝对目录。CLI 同步本地入口，检查 `skillUpdate` 并报告失败；新入口在客户端重新加载后采用。依次读取全部 `mustRead`，以 `resourceRoot` 解析资源并按流程执行。新任务重新 resolve，同一任务沿用已读快照。资源更新或校验失败时停止依赖工作，不静默使用旧资源。
+CLI 自动发现已安装的 skill 并同步入口，检查 `skillUpdate` 并报告失败；新入口在客户端重新加载后采用。依次读取全部 `mustRead`，以 `resourceRoot` 解析资源并按流程执行。新任务重新 resolve，同一任务沿用已读快照。资源更新或校验失败时停止依赖工作，不静默使用旧资源。
 
-脚本通过 `npx -y --prefer-online global-app-skill@latest run SCRIPT --skill-dir SKILL_DIRECTORY --mode MODE --resource-root RESOURCE_ROOT -- 参数` 执行；参数见解析后的 CLI 文档。业务判断与页面操作由 agent 按文档编排，CLI 成功不代表调研完成；关键进度仍须输出到聊天正文。
+脚本通过 `npx -y --prefer-online global-app-skill@latest run SCRIPT --mode MODE --resource-root RESOURCE_ROOT -- 参数` 执行；参数见解析后的 CLI 文档。业务判断与页面操作由 agent 按文档编排，CLI 成功不代表调研完成；关键进度仍须输出到聊天正文。

package/src/cli.mjs

@@ -13,6 +13,7 @@ const usage = `global-app-skill ${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.
+Skill locations are discovered from client user/project directories and CLI installation records.
 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.
 `;
@@ -42,6 +43,7 @@ export async function main(argv) {
     throw new Error('--resource-root cannot be combined with --feed or --cache-dir');
   }
   const skillUpdate = command === 'skill' ? undefined : await syncInstalledSkills({ directory: values['skill-dir'] });
+  if (skillUpdate?.error) process.stderr.write(`[global-app-skill] Skill discovery failed: ${skillUpdate.error}\n`);
   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`);

package/src/installations.mjs

@@ -0,0 +1,64 @@
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { sha256 } from './protocol.mjs';
+
+export const SKILL_ROOTS = ['.agents/skills', '.codex/skills', '.claude/skills', '.cursor/skills', '.gemini/skills', '.kiro/skills'];
+const skillName = 'overseas-app-research';
+
+function stateRoot({ home = homedir(), env = process.env, stateDirectory } = {}) {
+  return path.resolve(stateDirectory || path.join(env.XDG_STATE_HOME || path.join(home, '.local/state'), 'global-app-skill'));
+}
+
+async function exists(filename) {
+  try { await lstat(filename); return true; }
+  catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return false; throw error; }
+}
+
+export async function rememberInstallation(directory, options = {}) {
+  directory = path.resolve(directory);
+  const registry = path.join(stateRoot(options), 'installations');
+  await mkdir(registry, { recursive: true });
+  // Independent records avoid lost registrations when installs run concurrently.
+  const target = path.join(registry, `${sha256(directory)}.json`);
+  const temporary = path.join(registry, `.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, JSON.stringify({ directory }) + '\n', { flag: 'wx' });
+    await rename(temporary, target);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+async function registeredDirectories(options) {
+  const registry = path.join(stateRoot(options), 'installations');
+  let names;
+  try { names = await readdir(registry); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return Promise.all(names.filter(name => name.endsWith('.json')).sort().map(async name => {
+    const { directory } = JSON.parse(await readFile(path.join(registry, name), 'utf8'));
+    if (typeof directory !== 'string' || !path.isAbsolute(directory) || name !== `${sha256(directory)}.json`) {
+      throw new Error(`Invalid skill installation record: ${path.join(registry, name)}`);
+    }
+    return directory;
+  }));
+}
+
+async function projectDirectories(cwd) {
+  const directories = [];
+  for (let directory = path.resolve(cwd); ; directory = path.dirname(directory)) {
+    directories.push(directory);
+    if (await exists(path.join(directory, '.git'))) return directories;
+    if (path.dirname(directory) === directory) return [path.resolve(cwd)];
+  }
+}
+
+export async function discoverSkillDirectories(options = {}) {
+  const { home = homedir(), env = process.env, cwd = process.cwd() } = options;
+  const bases = [path.resolve(home), ...await projectDirectories(cwd)];
+  const candidates = bases.flatMap(base => SKILL_ROOTS.map(root => path.join(base, root, skillName)));
+  if (env.CODEX_HOME) candidates.push(path.resolve(env.CODEX_HOME, 'skills', skillName));
+  candidates.push(...await registeredDirectories(options));
+  const unique = [...new Set(candidates)];
+  const present = await Promise.all(unique.map(directory => exists(path.join(directory, 'SKILL.md'))));
+  return unique.filter((directory, index) => present[index]);
+}

package/src/protocol.mjs

@@ -2,7 +2,9 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
 export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version;
-export const FEED = 'https://raw.githubusercontent.com/shiguang-lab/global-app-skill/main/releases/latest.json';
+export const RELEASE_BASE = 'https://github.com/shiguang-lab/global-app-skill/releases';
+export const FEED = `${RELEASE_BASE}/latest/download/latest.json`;
+export const RELEASE_TAG = /^(?:v|resources-v)(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 export const MAX_BYTES = 16 * 1024 * 1024;
 export const MODES = {
   download: 'references/download-workflow.md',
@@ -20,7 +22,7 @@ export function validateMode(mode) {
 
 export function validateManifest(manifest) {
   const hash = /^[a-f0-9]{64}$/;
-  if (manifest?.schemaVersion !== 1 || !hash.test(manifest.resourceHash) ||
+  if (manifest?.schemaVersion !== 1 || !RELEASE_TAG.test(manifest.releaseTag) || !hash.test(manifest.resourceHash) ||
       !/^\d+\.\d+\.\d+$/.test(manifest.minCliVersion) ||
       !Array.isArray(manifest.files) || !manifest.files.length || manifest.files.length > 1024 ||
       manifest.bundle !== `${manifest.resourceHash}.json.gz` || !hash.test(manifest.sha256) ||
@@ -50,3 +52,13 @@ export function validateManifest(manifest) {
   }
   return manifest;
 }
+
+export function bundleUrl(manifest, feed) {
+  const url = new URL(feed);
+  if (url.origin === 'https://github.com' && url.pathname.startsWith('/shiguang-lab/global-app-skill/releases/')) {
+    // Pin the bundle to the manifest's release, even if "latest" advances
+    // between fetching the manifest and fetching its archive.
+    return new URL(`${RELEASE_BASE}/download/${manifest.releaseTag}/${manifest.bundle}`);
+  }
+  return new URL(manifest.bundle, url);
+}

package/src/resources.mjs

@@ -3,7 +3,7 @@ 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';
+import { bundleUrl, FEED, MAX_BYTES, MODES, sha256, validateManifest, validateMode } from './protocol.mjs';
 
 async function download(url, limit) {
   const response = await fetch(url, { cache: 'no-store', signal: AbortSignal.timeout(30000) });
@@ -61,7 +61,7 @@ export async function resolveContext({ mode, feed = FEED, cacheDir, progress = (
   let updated = false;
   if (!(await validSnapshot(resourceRoot, manifest.resourceHash))) {
     progress(`Downloading and verifying ${manifest.files.length} resource files`);
-    const bytes = await download(new URL(manifest.bundle, url), MAX_BYTES);
+    const bytes = await download(bundleUrl(manifest, url), MAX_BYTES);
     if (bytes.length !== manifest.size || sha256(bytes) !== manifest.sha256) throw new Error('Resource bundle integrity check failed');
     const bundle = JSON.parse(gunzipSync(bytes, { maxOutputLength: MAX_BYTES * 2 }).toString('utf8'));
     if (!Array.isArray(bundle.files) || bundle.files.length !== manifest.files.length) throw new Error('Invalid resource bundle');
@@ -109,7 +109,7 @@ export async function resolveContext({ mode, feed = FEED, cacheDir, progress = (
   progress(updated ? 'Resource snapshot ready' : 'Verified cached snapshot is current');
   const mustRead = ['references/cli.md', 'references/guide.md', 'references/orchestration.md', MODES[mode]]
     .map(name => path.join(resourceRoot, name));
-  return { ok: true, source: url.hostname === 'raw.githubusercontent.com' ? 'github' : 'custom', feed: url.href,
-    mode, resourceHash: manifest.resourceHash, resourceRoot,
+  return { ok: true, source: url.origin === 'https://github.com' ? 'github' : 'custom', feed: url.href,
+    mode, releaseTag: manifest.releaseTag, resourceHash: manifest.resourceHash, resourceRoot,
     referencePath: path.join(resourceRoot, 'references/guide.md'), mustRead, updated };
 }

package/src/skill.mjs

@@ -4,6 +4,7 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { VERSION } from './protocol.mjs';
+import { discoverSkillDirectories, rememberInstallation } from './installations.mjs';
 
 async function stat(filename) {
   try { return await lstat(filename); }
@@ -46,8 +47,7 @@ async function writeSkill(target, existingOnly) {
       }
     }
     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`;
+    const content = bundled.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 {
@@ -58,15 +58,18 @@ async function writeSkill(target, existingOnly) {
   } 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 installSkill(directory, options = {}) {
+  const target = path.resolve(directory || path.join(options.home || homedir(), '.agents/skills/overseas-app-research'));
+  const result = await writeSkill(target, false);
+  await rememberInstallation(target, options);
+  return { ok: true, ...result };
 }
 
-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)))];
+export async function syncInstalledSkills({ directory, directories, ...options } = {}) {
+  let targets;
+  try {
+    targets = [...new Set((directory ? [directory] : directories || await discoverSkillDirectories(options)).map(target => path.resolve(target)))];
+  } catch (error) { return { ok: false, installations: [], error: error.message }; }
   const installations = [];
   for (const target of targets) {
     try { installations.push(await writeSkill(target, true)); }