global-app-skill 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 # global-app-skill
 
-海外 Android App 调研 skill 的薄入口、资源更新器和脚本 CLI。保持 `overseas-app-research` 的下载、业务调研与 UED 图册三个分支。
+海外 Android App 调研 skill 的薄入口、资源更新器和脚本 CLI。保持 `global-app-analysis` 的下载、业务调研与 UED 图册三个分支。
 
 ## 安装
 
@@ -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 目录。所有目录使用完全相同的薄入口，只记录 CLI 版本，不写入安装路径。安装位置记录在本机状态目录，供 CLI 后续自动发现；该记录不放进 skill。已存在的 SKILL.md 会被原子替换，目录中的其他文件保留，符号链接入口拒绝覆盖。安装不下载 references，也不修改 MCP 或客户端配置。
+默认只安装 `~/.agents/skills/global-app-analysis/SKILL.md`。也可用 `--dir /absolute/skills/global-app-analysis` 指定当前客户端实际使用的 skill 目录。所有目录使用完全相同的薄入口，只记录 CLI 版本，不写入安装路径。安装位置记录在本机状态目录，供 CLI 后续自动发现；该记录不放进 skill。已存在的 SKILL.md 会被原子替换，目录中的其他文件保留，符号链接入口拒绝覆盖。安装不下载 references，也不修改 MCP 或客户端配置。
 
 ## 执行
 
@@ -22,7 +22,7 @@ npx -y --prefer-online global-app-skill@latest context resolve --mode research
 
 `context resolve` 和 `run` 执行前由 CLI 自动定位已安装的薄入口，更新为当前 CLI 捆绑的版本。入口只调用通用命令，不传安装路径。入口使用 `npx --prefer-online ...@latest`，因此发布新版 CLI 后，下一次执行会更新本地 SKILL.md。
 
-CLI 检查以下位置中的 `overseas-app-research/SKILL.md`：用户目录下的 `.agents/skills`、`.codex/skills`、`.claude/skills`、`.cursor/skills`、`.gemini/skills`、`.kiro/skills`；当前目录至最近 Git 仓库根目录之间的相同项目级目录；`CODEX_HOME/skills`；以及 CLI 安装时登记的目录。不在 Git 仓库内时，项目级发现只检查当前目录，不遍历其他工作区。
+CLI 检查以下位置中的 `global-app-analysis/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` 仅保留为手动指定本次更新目标的可选参数，薄入口无需使用。
 
@@ -42,11 +42,11 @@ npx -y --prefer-online global-app-skill@latest run preflight --mode research --r
 
 | 路径 | 职责 |
 |---|---|
-| `skills/overseas-app-research/SKILL.md` | 安装到客户端的薄入口 |
+| `skills/global-app-analysis/SKILL.md` | 安装到客户端的薄入口 |
 | `src/` | npm CLI：安装、资源解析、校验、脚本运行 |
-| `resources/overseas-app-research/references/` | 主流程和各阶段操作文档 |
-| `resources/overseas-app-research/scripts/` | 原有 Python 脚本及回归测试 |
-| `resources/overseas-app-research/examples/` | 业务报告模板 |
+| `resources/global-app-analysis/references/` | 主流程和各阶段操作文档 |
+| `resources/global-app-analysis/scripts/` | 原有 Python 脚本及回归测试 |
+| `resources/global-app-analysis/examples/` | 业务报告模板 |
 | `scripts/build-resources.mjs` | 生成确定性的资源包与清单 |
 | `.github/workflows/publish.yml` | tag 触发的构建、GitHub Release 和 npm 发布 |
 | `scripts/release.mjs` | tag 校验、打包、校验和及发布资产核对 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "global-app-skill",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Thin skill bootstrap and GitHub resource runner for overseas Android app research",
   "type": "module",
   "license": "UNLICENSED",
@@ -14,7 +14,7 @@
   "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" },
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "test:python": "python3 -m unittest discover -s resources/overseas-app-research/scripts -p 'test_*.py'",
+    "test:python": "python3 -m unittest discover -s resources/global-app-analysis/scripts -p 'test_*.py'",
     "resources:build": "node scripts/build-resources.mjs",
     "resources:check": "node scripts/build-resources.mjs --check",
     "release:prepare": "node scripts/release.mjs",

package/skills/{overseas-app-research → global-app-analysis}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: overseas-app-research
+name: global-app-analysis
 description: 调研海外 Android App 的业务流程、功能入口、字段权限，或为 UED 提取整款 App/指定范围的原始界面图册；也支持仅下载/导出 APK。
 ---
 
-# 海外 App 调研
+# 海外 App 分析
 
 需要 Node.js >=22.12、`python3` >=3.9；设备/AVD 门槛由解析后的工作流检查。
 
@@ -16,3 +16,8 @@ npx -y --prefer-online global-app-skill@latest context resolve --mode MODE
 CLI 自动发现已安装的 skill 并同步入口，检查 `skillUpdate` 并报告失败；新入口在客户端重新加载后采用。依次读取全部 `mustRead`，以 `resourceRoot` 解析资源并按流程执行。新任务重新 resolve，同一任务沿用已读快照。资源更新或校验失败时停止依赖工作，不静默使用旧资源。
 
 脚本通过 `npx -y --prefer-online global-app-skill@latest run SCRIPT --mode MODE --resource-root RESOURCE_ROOT -- 参数` 执行；参数见解析后的 CLI 文档。业务判断与页面操作由 agent 按文档编排，CLI 成功不代表调研完成；关键进度仍须输出到聊天正文。
+
+## 必检入口
+
+解析资源后，先读取当前 `resourceRoot` 下的 `references/rules.md`。读取失败时暂停依赖该规则的工作。
+到达规则定义的检查点时执行对应校验并记录结果。通过后才可正式或阶段性交付，包括复用、重发已有报告或链接。校验未通过时按规则回退或说明阻塞与恢复条件。

package/src/cli.mjs

@@ -3,7 +3,7 @@ import { parseArgs } from 'node:util';
 import { installSkill, syncInstalledSkills } from './skill.mjs';
 import { resolveContext } from './resources.mjs';
 import { runScript } from './run.mjs';
-import { validateMode, VERSION } from './protocol.mjs';
+import { SKILL_NAME, validateMode, VERSION } from './protocol.mjs';
 
 const usage = `global-app-skill ${VERSION}
   skill install [--dir ABSOLUTE_SKILL_DIRECTORY]
@@ -11,7 +11,7 @@ const usage = `global-app-skill ${VERSION}
   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.
+skill install writes only SKILL.md; default: ~/.agents/skills/${SKILL_NAME}.
 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.

package/src/installations.mjs

@@ -2,10 +2,9 @@ import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import path from 'node:path';
-import { sha256 } from './protocol.mjs';
+import { sha256, SKILL_NAME } 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'));
@@ -55,8 +54,8 @@ async function projectDirectories(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));
+  const candidates = bases.flatMap(base => SKILL_ROOTS.map(root => path.join(base, root, SKILL_NAME)));
+  if (env.CODEX_HOME) candidates.push(path.resolve(env.CODEX_HOME, 'skills', SKILL_NAME));
   candidates.push(...await registeredDirectories(options));
   const unique = [...new Set(candidates)];
   const present = await Promise.all(unique.map(directory => exists(path.join(directory, 'SKILL.md'))));

package/src/protocol.mjs

@@ -2,10 +2,12 @@ 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 SKILL_NAME = 'global-app-analysis';
 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 RULES_PATH = 'references/rules.md';
 export const MODES = {
   download: 'references/download-workflow.md',
   research: 'references/research-workflow.md',
@@ -20,7 +22,7 @@ export function validateMode(mode) {
   return mode;
 }
 
-export function validateManifest(manifest) {
+export function validateManifest(manifest, { requireRules = true } = {}) {
   const hash = /^[a-f0-9]{64}$/;
   if (manifest?.schemaVersion !== 1 || !RELEASE_TAG.test(manifest.releaseTag) || !hash.test(manifest.resourceHash) ||
       !/^\d+\.\d+\.\d+$/.test(manifest.minCliVersion) ||
@@ -43,7 +45,9 @@ export function validateManifest(manifest) {
   if (identity(manifest.files) !== manifest.resourceHash) throw new Error('Resource manifest hash mismatch');
   const required = ['references/guide.md', 'references/cli.md', 'references/orchestration.md',
     ...Object.values(MODES), ...SCRIPTS.map(name => `scripts/${name}.py`), 'scripts/apk_utils.py', 'scripts/progress.py'];
-  if (required.some(name => !seen.has(name))) throw new Error('Resource manifest is missing workflow files');
+  if (requireRules) required.unshift(RULES_PATH, 'references/delivery-record.md', 'scripts/check_delivery.py');
+  const missing = required.filter(name => !seen.has(name));
+  if (missing.length) throw new Error(`Resource manifest is missing workflow files: ${missing.join(', ')}`);
   const installed = VERSION.split('.').map(Number);
   const minimum = manifest.minCliVersion.split('.').map(Number);
   for (let i = 0; i < 3; i++) {

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 { bundleUrl, FEED, MAX_BYTES, MODES, sha256, validateManifest, validateMode } from './protocol.mjs';
+import { bundleUrl, FEED, MAX_BYTES, MODES, RULES_PATH, sha256, validateManifest, validateMode } from './protocol.mjs';
 
 async function download(url, limit) {
   const response = await fetch(url, { cache: 'no-store', signal: AbortSignal.timeout(30000) });
@@ -20,12 +20,12 @@ async function download(url, limit) {
   return Buffer.concat(chunks);
 }
 
-export async function readSnapshot(resourceRoot) {
+export async function readSnapshot(resourceRoot, options) {
   resourceRoot = path.resolve(resourceRoot);
   if (!(await lstat(resourceRoot)).isDirectory()) throw new Error('Resource root must be a real directory');
   const manifestPath = path.join(resourceRoot, 'manifest.json');
   if (!(await lstat(manifestPath)).isFile()) throw new Error('Resource manifest must be a regular file');
-  const manifest = validateManifest(JSON.parse(await readFile(manifestPath, 'utf8')));
+  const manifest = validateManifest(JSON.parse(await readFile(manifestPath, 'utf8')), options);
   if (path.basename(resourceRoot) !== manifest.resourceHash) throw new Error('Resource root does not match its snapshot hash');
   for (const file of manifest.files) {
     let directory = resourceRoot;
@@ -107,7 +107,7 @@ export async function resolveContext({ mode, feed = FEED, cacheDir, progress = (
   }
   await readSnapshot(resourceRoot);
   progress(updated ? 'Resource snapshot ready' : 'Verified cached snapshot is current');
-  const mustRead = ['references/cli.md', 'references/guide.md', 'references/orchestration.md', MODES[mode]]
+  const mustRead = [RULES_PATH, 'references/cli.md', 'references/guide.md', 'references/orchestration.md', MODES[mode]]
     .map(name => path.join(resourceRoot, name));
   return { ok: true, source: url.origin === 'https://github.com' ? 'github' : 'custom', feed: url.href,
     mode, releaseTag: manifest.releaseTag, resourceHash: manifest.resourceHash, resourceRoot,

package/src/run.mjs

@@ -7,7 +7,8 @@ import { readSnapshot, resolveContext } from './resources.mjs';
 export async function runScript(script, args, options = {}) {
   if (!SCRIPTS.includes(script)) throw new Error(`Unknown script; choose ${SCRIPTS.join(', ')}`);
   const resourceRoot = options.resourceRoot ? path.resolve(options.resourceRoot) : (await resolveContext(options)).resourceRoot;
-  await readSnapshot(resourceRoot);
+  // A task that already resolved an earlier snapshot may finish on it.
+  await readSnapshot(resourceRoot, { requireRules: !options.resourceRoot });
   await promisify(execFile)('python3', ['-c', 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else 1)'])
     .catch(() => { throw new Error('Python >=3.9 must be available as python3'); });
   return new Promise((resolve, reject) => {

package/src/skill.mjs

@@ -3,7 +3,7 @@ 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';
+import { SKILL_NAME, VERSION } from './protocol.mjs';
 import { discoverSkillDirectories, rememberInstallation } from './installations.mjs';
 
 async function stat(filename) {
@@ -35,7 +35,8 @@ async function writeSkill(target, existingOnly) {
     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')) {
+    const installedName = previous?.match(/^name: ([a-z0-9-]+)$/m)?.[1];
+    if (existingOnly && (installedName !== SKILL_NAME || !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];
@@ -46,7 +47,7 @@ async function writeSkill(target, existingOnly) {
         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 bundled = await readFile(new URL(`../skills/${SKILL_NAME}/SKILL.md`, import.meta.url), 'utf8');
     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`);
@@ -59,7 +60,7 @@ async function writeSkill(target, existingOnly) {
 }
 
 export async function installSkill(directory, options = {}) {
-  const target = path.resolve(directory || path.join(options.home || homedir(), '.agents/skills/overseas-app-research'));
+  const target = path.resolve(directory || path.join(options.home || homedir(), '.agents/skills', SKILL_NAME));
   const result = await writeSkill(target, false);
   await rememberInstallation(target, options);
   return { ok: true, ...result };