fix: 升级以往正式发布的 skill，安装脚本先装 CLI 并输出单行 JSON

.github/workflows/ci.yml

@@ -16,7 +16,9 @@ jobs:
         os: [ubuntu-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
+      # Full history with tags: the build lists earlier released skills and tests upgrade from them.
       - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
       - uses: actions/setup-node@v4
         with:
           node-version: '22'

.github/workflows/release.yml

@@ -24,7 +24,9 @@ jobs:
   package:
     runs-on: ubuntu-latest
     steps:
+      # Every v* tag: the build embeds earlier official skill digests so installs upgrade them.
       - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
       - uses: actions/setup-node@v4
         with: { node-version: '22' }
       - run: node -e 'if (process.env.GITHUB_REF_NAME !== "v" + JSON.parse(require("fs").readFileSync("package.json")).version) process.exit(1)'
@@ -46,6 +48,7 @@ jobs:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
       - uses: oven-sh/setup-bun@v2
         with: { bun-version: latest }
       - uses: actions/setup-node@v4
@@ -125,6 +128,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
       - uses: actions/setup-node@v4
         with: { node-version: '22' }
       - run: npm ci
@@ -133,7 +137,8 @@ jobs:
       - name: install.sh (CDN)
         if: runner.os != 'Windows'
         run: |
-          curl -fsSL https://download.hiq.earth/cli/cortex-org-wiki/install.sh | sh -s -- --agent codex --project "$RUNNER_TEMP/wiki-project" --install-dir "$RUNNER_TEMP/wiki-bin"
+          curl -fsSL https://download.hiq.earth/cli/cortex-org-wiki/install.sh | sh -s -- --agent codex --project "$RUNNER_TEMP/wiki-project" --install-dir "$RUNNER_TEMP/wiki-bin" > "$RUNNER_TEMP/install.json"
+          node -e 'const [line, ...rest] = require("fs").readFileSync(process.argv[1], "utf8").split("\n").filter(Boolean); const data = JSON.parse(line).data; if (rest.length || data.cli.version !== process.env.GITHUB_REF_NAME.slice(1) || data.skills[0].status !== "installed") process.exit(1)' "$RUNNER_TEMP/install.json"
           "$RUNNER_TEMP/wiki-bin/cortex-org-wiki" version
           test -s "$RUNNER_TEMP/wiki-project/.agents/skills/cortex-org-wiki/SKILL.md"
       - name: install.ps1 (CDN)

README.md

@@ -20,7 +20,7 @@ Windows PowerShell：
 & ([scriptblock]::Create((irm https://download.hiq.earth/cli/cortex-org-wiki/install.ps1))) -Agent codex
 ```
 
-默认安装 CLI 和当前项目的 `cortex-org-wiki` skill。Claude Code 改用 `claude-code`。支持 `--scope user` / `-Scope user`；`--cli-only` / `-CliOnly`、`--skill-only` / `-SkillOnly` 可分别安装。完整参数见 [Agent 指南](docs/agent-setup.md)。无需 Node；技能正文嵌在同版本二进制内。
+默认安装 CLI 和当前项目的 `cortex-org-wiki` skill。Claude Code 改用 `claude-code`，多个宿主可重复 `--agent` 或逗号分隔；重新运行即升级 CLI 与之前正式发布的 skill，成功时 stdout 只输出一行 JSON 结果。支持 `--scope user` / `-Scope user`；`--cli-only` / `-CliOnly`、`--skill-only` / `-SkillOnly` 可分别安装。完整参数见 [Agent 指南](docs/agent-setup.md)。无需 Node；技能正文嵌在同版本二进制内。
 
 已有 Node 的宿主也可以直接 `npx @hiq-ai/cortex-org-wiki-cli --version`（npm 自 0.1.1 起可用）；默认仍推荐上面的原生安装入口。Cortex Cowork 的市场安装由 Host 供给同源 skill 与 CLI；以该会话的实际 CLI 和身份检查结果确认是否接通。
 

docs/agent-setup.md

@@ -4,7 +4,7 @@
 
 ## 安装到当前宿主
 
-确认实际执行环境、操作系统和宿主。已有 CLI 先执行 `cortex-org-wiki --version` 和 `--help`；低于 0.1.3 时先按下面的入口更新，再确认 `--version`。
+确认实际执行环境、操作系统和宿主。已有 CLI 先执行 `cortex-org-wiki --version` 和 `--help`；低于 0.1.3 时先按下面的入口更新（见[升级](#升级)），再确认 `--version`。
 
 macOS / Linux：
 
@@ -18,7 +18,7 @@ Windows PowerShell：
 & ([scriptblock]::Create((irm https://download.hiq.earth/cli/cortex-org-wiki/install.ps1))) -Agent codex
 ```
 
-选择当前宿主：Codex 用 `codex`，Claude Code 用 `claude-code`。默认一次安装 CLI 和 skill，不需要 Node/npm。CLI 默认位置为 `~/.local/bin/cortex-org-wiki` 或 `%LOCALAPPDATA%\Programs\cortex-org-wiki\cortex-org-wiki.exe`，当前终端未发现命令时直接使用完整路径。
+选择当前宿主：Codex 用 `codex`，Claude Code 用 `claude-code`。同时装到多个宿主时重复 `--agent` 或用逗号分隔（`--agent codex,claude-code`；PowerShell 为 `-Agent codex,claude-code`），不自动探测宿主。默认一次安装 CLI 和 skill，不需要 Node/npm。CLI 默认位置为 `~/.local/bin/cortex-org-wiki` 或 `%LOCALAPPDATA%\Programs\cortex-org-wiki\cortex-org-wiki.exe`，当前终端未发现命令时直接使用完整路径。
 
 | 需求 | sh 参数 | PowerShell 参数 |
 |---|---|---|
@@ -28,13 +28,27 @@ Windows PowerShell：
 | 指定项目 | `--project '<path>'` | `-Project '<path>'` |
 | 指定 CLI 目录 | `--install-dir '<path>'` | `-InstallDir '<path>'` |
 
-默认项目范围。Codex 写入项目或用户的 `.agents/skills/cortex-org-wiki/`；Claude Code 写入对应 `.claude/skills/cortex-org-wiki/`。同内容可重复安装，不同内容报冲突；只有确认应替换后使用 `--replace-skill` / `-ReplaceSkill`。不为其他宿主猜目录或安装到所有全局目录。
+默认项目范围。Codex 写入项目或用户的 `.agents/skills/cortex-org-wiki/`；Claude Code 写入对应 `.claude/skills/cortex-org-wiki/`。同内容可重复安装；已有内容是本仓任一正式发布版本的 skill 时自动更新为当前版本；其他内容（本地修改、较新版本或来源不明）报 `skill_conflict`，所选宿主都不写入，只有确认应替换后使用 `--replace-skill` / `-ReplaceSkill`。不为其他宿主猜目录或安装到所有全局目录。
 
-已有 CLI 可以直接运行 `cortex-org-wiki skill setup --agent codex --scope project --json`，可加 `--project '<path>'`。已有 Node 的宿主也可以 `npx @hiq-ai/cortex-org-wiki-cli <命令>`（npm 自 0.1.1 起可用），默认仍用上面的原生安装入口。标准 skills 安装器也可从本公开仓库精准安装 `--skill cortex-org-wiki --agent codex|claude-code`；统一入口已包含 skill，无需重复安装。
+已有 CLI 可以直接运行 `cortex-org-wiki skill setup --agent codex --scope project --json`，可加 `--project '<path>'`，`--agent` 可重复；结果在 `data.skills`，每个宿主一项，确认替换用 `--replace`。已有 Node 的宿主也可以 `npx @hiq-ai/cortex-org-wiki-cli <命令>`（npm 自 0.1.1 起可用），默认仍用上面的原生安装入口。标准 skills 安装器也可从本公开仓库精准安装 `--skill cortex-org-wiki --agent codex|claude-code`；统一入口已包含 skill，无需重复安装。
 
 Cortex Cowork 的市场安装由现有 Host 管理 skill 和对应 CLI，采用市场产物的 `metadata.cli`。不要用 `--agent cortex`（它是其他产品的标识），不要写 Cortex 私有 profile 或用 `save_skill` 代替安装。是否已供给可用 CLI，以当前会话实际命令结果为准。
 
-安装后检查 `skill setup` 返回路径，并在宿主原生技能列表确认 `cortex-org-wiki` 已发现；必要时按宿主要求刷新会话。文件落盘和实时加载分别报告。源规范见 [Codex](https://learn.chatgpt.com/docs/build-skills)、[Claude Code](https://code.claude.com/docs/en/skills)。
+## 升级
+
+`--version` 低于需要的版本时，重新运行同一安装入口，带上原来的 `--agent`、`--scope`、`--project`。安装脚本先把新 CLI 放到位，再用新 CLI 安装 skill：之前正式发布的 skill 自动更新为 `updated`；遇到 `skill_conflict` 时 CLI 已经升级，只有 skill 未写入，确认替换后加 `--replace-skill` / `-ReplaceSkill` 重跑。
+
+## 安装后检查
+
+成功时 stdout 只有一行 JSON，进度在 stderr：
+
+```json
+{"ok":true,"tool":"install","data":{"cli":{"path":"/home/me/.local/bin/cortex-org-wiki","version":"0.1.5","previous_version":"0.1.4"},"skills":[{"agent":"codex","scope":"project","path":"/work/app/.agents/skills/cortex-org-wiki/SKILL.md","version":"0.1.5","sha256":"…","status":"updated"}]}}
+```
+
+`cli.path` 是实际安装位置；`previous_version` 为之前该位置 CLI 的 `version` 输出，没有或无法运行时为 `null`；`--skill-only` 时 `cli` 为 `null`。`skills` 每个宿主一项，`status` 为 `installed`、`updated` 或 `unchanged`；`--cli-only` 时为空数组。失败时退出码非零，stderr 中有一行 `{"ok":false,"kind":…,"code":…,"message":…}`，按 `code` 报告，不要把部分输出当作成功。
+
+据此报告 CLI 路径与版本，并在宿主原生技能列表确认 `cortex-org-wiki` 已发现；必要时按宿主要求刷新会话。文件落盘和实时加载分别报告。源规范见 [Codex](https://learn.chatgpt.com/docs/build-skills)、[Claude Code](https://code.claude.com/docs/en/skills)。
 
 ## 登录并核实组织
 

docs/release.md

@@ -1,6 +1,6 @@
 # 发布入口与验收
 
-初版包 `@hiq-ai/cortex-org-wiki-cli@0.1.0`；命令/skill `cortex-org-wiki`。版本只修改 `package.json`，构建生成版本常量和内嵌技能。
+初版包 `@hiq-ai/cortex-org-wiki-cli@0.1.0`；命令/skill `cortex-org-wiki`。版本只修改 `package.json`，构建生成版本常量和内嵌技能，并从全部 `v*` tag 的 `SKILL.md` 生成以往正式 skill 的摘要，安装时据此自动升级、只对未知内容报冲突。因此 CI 与发布各 job 的 checkout 取完整历史（`fetch-depth: 0`）；tag 构建看不到更早的 `v*` tag 时生成脚本直接失败，本地无 tag 的开发构建只是列表为空。
 
 `v<version>` tag 运行 release workflow。测试后生成 npm tarball 与五平台 native 产物；npm 发布和 GitHub native release 是独立 job，CDN 只依赖 GitHub release。npm 权限未就绪时应真实失败，不阻断 native 渠道，也不报告全渠道完成。
 

scripts/generate-assets.mjs

@@ -1,8 +1,28 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
 const root = new URL("../", import.meta.url);
+const skillPath = "skills/cortex-org-wiki/SKILL.md";
+const sha256 = content => createHash("sha256").update(content).digest("hex");
+const git = (...args) => execFileSync("git", args, { cwd: root, maxBuffer: 16 * 1024 * 1024 });
 const { version } = JSON.parse(readFileSync(new URL("package.json", root), "utf8"));
-const skill = readFileSync(new URL("skills/cortex-org-wiki/SKILL.md", root), "utf8");
+const skill = readFileSync(new URL(skillPath, root), "utf8");
 if (!skill.startsWith("---\nname: cortex-org-wiki\n")) throw new Error("Unexpected skill identity");
+const digest = sha256(skill);
+
+// Every released skill is the tagged SKILL.md, embedded unchanged by that tag's build. Installs
+// carrying one of these digests are ours to upgrade; anything else stays a user decision.
+const tags = git("tag", "--list", "v*", "--sort=version:refname").toString().split("\n").filter(Boolean);
+if (process.env.GITHUB_REF_TYPE === "tag" && !tags.some(tag => tag !== process.env.GITHUB_REF_NAME)) {
+  throw new Error("Release build sees no earlier v* tag; check out with fetch-depth: 0 so previous official skills can be upgraded");
+}
+const previous = new Set();
+for (const tag of tags) {
+  const entry = git("ls-tree", tag, "--", skillPath).toString().trim();
+  if (!entry) continue;
+  const blobDigest = sha256(git("cat-file", "blob", entry.split(/\s+/)[2]));
+  if (blobDigest !== digest) previous.add(blobDigest);
+}
+
 writeFileSync(new URL("src/version.ts", root), `/** Generated from package.json. */\nexport const VERSION = ${JSON.stringify(version)};\n`);
-writeFileSync(new URL("src/skillAsset.ts", root), `/** Generated from skills/cortex-org-wiki/SKILL.md; do not edit. */\nexport const SKILL = ${JSON.stringify(skill)};\nexport const SKILL_SHA256 = ${JSON.stringify(createHash("sha256").update(skill).digest("hex"))};\n`);
+writeFileSync(new URL("src/skillAsset.ts", root), `/** Generated from ${skillPath} and its released v* tags; do not edit. */\nexport const SKILL = ${JSON.stringify(skill)};\nexport const SKILL_SHA256 = ${JSON.stringify(digest)};\nexport const PREVIOUS_OFFICIAL_SKILL_SHA256: readonly string[] = ${JSON.stringify([...previous])};\n`);