release: v4.9.0 — hybrid 切割 deprecation 期

CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [4.9.0] - 2026-06-26
+
+> **Minor: hybrid 切割 deprecation 期开启.** v0.5.23 之前 abyss CLI 文档把自己定位为「cargo-only fallback」、把 `npx code-abyss --with-abyss` 定位为 production 主入口；abyss v0.5.24 正式定位反转——`abyss attach` 是 claude/codex/gemini 三平台 hook 注入的 production 主入口；openclaw/pi/hermes 由 code-abyss npm 包独占（abyss 设计上不接管，因 per-pack 布局 + 不稳定 hook shape）。v4.9.0 是配合这次反转的 deprecation 期；v5.0 物理切割。
+
+### Deprecated
+
+- **`--with-abyss`** — 二进制下载职责转交 abyss 仓库本体的 `install.sh` / `cargo binstall code-abyss` / `@code-abyss/cli` npm wrapper。`bin/install.js` 解析到该 flag 时打印 `⚠ DEPRECATED` warning + 推荐迁移命令；旧行为（下载到 `~/.code-abyss/bin/`）在 v4.9 全程保留以维持兼容。v5.0 物理移除 `bin/lib/abyss-binary.js` 与 flag 解析。
+- **`--with-mcp`** — MCP 注册由 MCP 客户端自管（添加 `mcpServers.abyss = { command: "abyss", args: ["mcp"] }` 到客户端配置即可）。warning + 迁移引导同上；v5.0 物理移除。
+- **`--with-hooks` 对 claude/codex/gemini** — `abyss attach <host>` (abyss v0.5.20+) 是 production 主入口，shape 一致、idempotent、重跑覆盖。warning + 引导 `abyss attach <host>`；v4.9 旧行为保留（仍写入 settings 文件）；v5.0 物理移除 `injectClaudeHooks` / `injectGeminiHooks` / `injectCodexHooks` + 相关 `~256 行 codex.js TOML 编辑器` (`splitTomlBlocks` / `gatherHookGroup` / `renderCodexHookBlock` / `stripCodexAbyssIntegration`) + `ABYSS_HOOK_MARKER` 常量。
+
+### Changed
+
+- **`--with-hooks` 对 openclaw/pi/hermes 改造为 net-new 能力**：v4.9 起当 `targetName ∈ {openclaw, pi, hermes}` 且 `withHooks=true` 时，自动 `spawn bash skills/indexing-code/hooks/common/install-hooks.sh <target>`，由 install-hooks.sh 完成 per-host hook 注入。新 helper `maybeSpawnInstallHooks(targetName)` 落 `bin/install.js`。abyss CLI 设计上不接管这三平台（per-pack layout / 不稳定 hook shape），所以 `--with-hooks` 对它们永久保留并在 v5.0 之后仍工作。
+- **`bin/lib/lifecycle/finish.js` `reportAbyssStatus(projectLock, targetName)`** 加 `targetName` 参数；当 target ∈ {claude, codex, gemini} 时引导文案改为「装好 abyss 后跑 `abyss attach <host>`」（替代旧的「重跑 `--with-abyss`」引导）；abyss 缺失时安装命令清单不再首推 `npx code-abyss --with-abyss`，改首推 `curl install.sh`。
+- **`skills/indexing-code/SKILL.md` `## Hook 自动执行` 段重写**：明确 hybrid 分工——claude/codex/gemini 走 `abyss attach`（production 主入口）；openclaw/pi/hermes 走 `npx code-abyss --with-hooks` 或直接 `bash install-hooks.sh`。修复 L103 与 `install.js` L292 字面冲突（v4.8.1 起 hook 默认 opt-in，但 SKILL.md 仍说「自动注入」）。
+- **`README.md` 副标题去掉 `code graph intelligence`**——code graph 由独立 abyss Rust CLI 提供，不再作为 code-abyss npm 包的内置卖点。What's new 段新增 v4.9 entry 解释 hybrid 切割；首屏命令示例改为「先装 code-abyss → 再装 abyss CLI → 再 `abyss attach`」三步。
+- **`site/index.html` + `site/i18n.js`** 双源 hero.badge / hero.sub 统一对齐：badge 从 v4.5/v4.6 推到 v4.9；hero.sub 去掉「code graph intelligence」；nav.graph 从「Graph / 代码图」改为「Companion / 协同」。
+- **`package.json` description** 删除「+ 代码关系图智能」括号；style 数字 5→6（与 README L9/L47 + `output-styles/index.json` 实际值一致）。
+- **`bin/lib/abyss-integration.js` / `bin/lib/abyss-binary.js` / `bin/adapters/codex.js`** 文件头加 v4.9 deprecation 注释 + `@deprecated` JSDoc；逻辑零改动。
+
+### Compatibility
+
+- 100% backward compatible。所有现有 flag、helper、inject 函数行为不变；424 现有 test + verify:skills 30 skills 零回归。
+- 现有用户跑 `npx code-abyss -t claude --with-abyss --with-mcp --with-hooks` 仍 work，只是看到三条 deprecation warning。
+- abyss CLI < 0.5.20 用户：`--with-hooks` 对 claude/codex/gemini 仍是有效路径直到 v5.0。
+
+### Required follow-up (v4.10 / v5.0)
+
+- **v4.10.0**：残留检测——安装收尾时若检测到 `~/.code-abyss/bin/abyss` 或 settings.json 中含旧 `HOOK_MARKER` 条目，主动告警 + 引导 `abyss attach <host> --force` 接管。
+- **v5.0.0** (BREAKING)：物理删除 `bin/lib/abyss-binary.js` (107 行) + `bin/adapters/codex.js` L430-686 (~256 行) + `bin/lib/abyss-integration.js` 中 `injectClaudeHooks` / `injectGeminiHooks` / `stripAbyssHooks` (claude/codex/gemini 部分) + `--with-abyss` / `--with-mcp` flag。`--with-hooks` 永久缩 scope 到 openclaw/pi/hermes。`bin/lib/lifecycle/core-install.js` L466-495 删除 claude/gemini hook 分支。`stripAbyssHooks` 仍保留供 `uninstall.js` 剥除遗留条目。
+
+### Companion release
+
+- **abyss v0.5.24** (telagod/abyss, planned simultaneously) — 仅文档定位反转 patch：`src/attach/mod.rs` 注释升级、`src/attach/openclaw.rs` 错误信息改 `--with-hooks`、`README.md` Pre-edit hooks 段重写、`docs/book/getting-started/agent-hook.md` 整章重写、`CHANGELOG.md` Unreleased entry。Hook shape / skill-manifest schema / hook payload 全不变。
+
 ## [4.8.2] - 2026-06-25
 
 ### Changed

README.md

@@ -6,7 +6,9 @@
   </a>
 </p>
 
-<h3 align="center">Composable persona · style · 30 engineering skills · 4 native security domains · self-evolution forge · code graph intelligence<br/>for Claude Code · Codex CLI · Gemini CLI · OpenClaw</h3>
+<h3 align="center">Composable persona · style · 30 engineering skills · 4 native security domains · self-evolution forge<br/>for Claude Code · Codex CLI · Gemini CLI · OpenClaw</h3>
+
+<p align="center"><sub>Need code graph intelligence? Use the companion <a href="https://github.com/telagod/abyss"><code>abyss</code></a> Rust CLI — it auto-attaches its hooks to claude/codex/gemini. The <code>indexing-code</code> skill ships its calling convention; the CLI ships separately.</sub></p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/code-abyss"><img src="https://img.shields.io/npm/v/code-abyss?color=9b8cff&label=npm&style=flat-square" alt="npm"></a>
@@ -57,22 +59,25 @@ Pick any persona. Pair it with any style. The behavior layer (iron laws, executi
 - Office skills slim to under 100 lines each; 4 design systems consolidated into one selector skill
 - **v4.1 — self-evolution forge**: `cultivating-skills` / `cultivating-personas` let the agent distill repeated workflows into reusable skills, with a safety scan and a three-tier publish funnel (local → project → community)
 - **v4.4 — hardware + academic writing**: 3 new domain skills (KiCad EDA, hardware product pipeline, AIGC detection reduction) + prompt injection defense + execution-drive shared behavior
-- **v4.5 — dynamic persona loading**: only `abyss` ships with npm — all other personas are fetched from GitHub on first use and cached locally, slimming the package
-- **v4.6 — code graph intelligence**: `abyss` CLI builds a code relationship graph (call graph + temporal analysis) in seconds — caller tracing, impact analysis, hotspot detection, change coupling. Pre-edit hooks auto-check callers across all 4 platforms
-- **v4.7 — measured resolution**: `abyss` v0.3.3 ships four-language reference resolution (Go / TypeScript / Python / Rust), benchmarked against SCIP ground truth across five corpora at ≥98.5% gated precision. Named-import binding tiers, receiver-type inference, and type-grade evidence — published numbers, not claims. `npm install -g @code-abyss/cli`
-- **v4.8 — dynamic capability discovery**: code-abyss reads `abyss skill-manifest` when the installed `abyss` is ≥ 0.5.22 — exposed CLI commands, MCP tools, and daemon socket verbs are now discovered at install time instead of hard-coded. `MIN_ABYSS_VERSION` bumped 0.3.0 → 0.5.20 (the 0.5.x line dogfooded across hono / helix / vite / FastAPI / Django / SQLAlchemy). Hand-coded fallbacks are preserved, so older `abyss` installs keep working unchanged.
+- **v4.5 — dynamic persona loading**: only the `abyss` persona slug (邪修红尘仙) ships with npm — all other personas are fetched from GitHub on first use and cached locally, slimming the package
+- **v4.6 — `indexing-code` skill (calling convention only)**: the `indexing-code` skill ships the calling convention for the external [`abyss`](https://github.com/telagod/abyss) Rust CLI (call graph + temporal analysis). The CLI itself is a separate product with its own release cadence — install it with its own `install.sh` / `cargo binstall` / `@code-abyss/cli` npm wrapper
+- **v4.7 — measured resolution (abyss CLI)**: the companion `abyss` Rust CLI ships four-language reference resolution (Go / TypeScript / Python / Rust), benchmarked against SCIP ground truth across five corpora at ≥98.5% gated precision. See its repo for numbers
+- **v4.8 — dynamic capability discovery**: code-abyss reads `abyss skill-manifest` when the installed `abyss` CLI is ≥ 0.5.22 — exposed CLI commands, MCP tools, and daemon socket verbs are discovered at install time instead of hard-coded
+- **v4.9 — hybrid split deprecation period (2026-06-25)**: `--with-abyss` / `--with-mcp` enter deprecation (removed v5.0). `--with-hooks` splits: claude/codex/gemini move to `abyss attach <host>` as the production main entrypoint (abyss v0.5.20+); openclaw/pi/hermes stay with code-abyss and `--with-hooks` now auto-spawns `install-hooks.sh` for those three. See [CHANGELOG](CHANGELOG.md) for the migration guide
 
 ```bash
-npx code-abyss -t claude -y --with-abyss
+npx code-abyss -t claude -y                       # persona / skills / style layer (zero network)
+curl -fsSL https://raw.githubusercontent.com/telagod/abyss/main/install.sh | bash   # then install abyss CLI
+abyss attach claude                               # finally, attach the code-graph hook (idempotent)
 ```
 
-`--with-abyss` also downloads the `abyss` code-graph binary so the pre-edit hooks work out of the box; add `--with-mcp` to register `abyss` as an MCP server. Swap `-t claude` for `codex` / `gemini` / `openclaw`. Or as a Claude Code plugin:
+Swap `-t claude` for `codex` / `gemini` / `openclaw`. For openclaw/pi/hermes (whose hook surface abyss CLI does not own), use `npx code-abyss -t openclaw --with-hooks` to spawn the bundled `install-hooks.sh`. Or as a Claude Code plugin:
 
 ```bash
 claude plugin install code-abyss
 ```
 
-> Plain `-y` (no `--with-abyss`) installs only the persona/skills/style layer and skips the network — code-graph hooks stay dormant until `abyss` is on `PATH`. Interactive runs (drop the `-y`) prompt before downloading. Verify code-graph is live with `abyss --version`, then `abyss index` in any project.
+> The persona/skills/style layer is fully decoupled from the code-graph CLI — installing code-abyss alone never touches the network beyond fetching remote persona content. `abyss attach <host>` is idempotent (re-running upgrades shape in place). Verify code-graph is live with `abyss --version`, then `abyss index` in any project.
 
 ---
 

bin/adapters/codex.js

@@ -432,6 +432,16 @@ function patchAndReportCodexDefaults({ cfgPath, ok, warn }) {
 //   [[hooks.PreToolUse]]   matcher  +  [[hooks.PreToolUse.hooks]]   type/command/timeout
 //   旧扁平 [hooks.X] 已被 Codex 拒载（invalid type: map, expected a sequence）
 // MCP: [mcp_servers.abyss] command/args —— 节名是我方命名空间，可自由 upsert。
+//
+// ── v4.9.0 hybrid-切割 deprecation 期（2026-06-25 起）──
+//
+// `abyss attach codex` (abyss CLI v0.5.20+) 是 codex hook 注入的 production 主入口
+// （shape 与本文件 1:1 一致，2026-06-18 abyss v0.5.23 已对齐 ground truth）。下方
+// `injectCodexHooks` / `splitTomlBlocks` / `gatherHookGroup` / `renderCodexHookBlock`
+// / `stripCodexAbyssIntegration` (~256 行) 与常量 `ABYSS_HOOK_MARKER` 在 v4.9 保留
+// 行为以维持 `--with-hooks` flag 兼容；install.js 触发时打印 deprecation warning
+// 引导用户改用 `abyss attach codex`。v5.0 物理删除上述函数与常量。MCP 注册
+// (mcp_servers.abyss) 仍是 code-abyss 责任，不在切割范围。
 
 const ABYSS_HOOK_MARKER = 'indexing-code/hooks/common';
 

bin/install.js

@@ -199,6 +199,7 @@ function discoverAbyssCapabilities() {
 }
 
 async function installTargetFlow(targetName, installOptions = {}) {
+  emitDeprecationWarnings(targetName);
   const persona = installOptions.persona || await resolveInstallPersona();
   const style = installOptions.style || await resolveInstallStyle(targetName);
   const packPlan = await resolveProjectPackPlan(targetName);
@@ -209,6 +210,7 @@ async function installTargetFlow(targetName, installOptions = {}) {
   else if (targetName === 'gemini') await postGemini(ctx);
   else await postOpenClaw(ctx);
   registerAbyssMcp(targetName, ctx);
+  maybeSpawnInstallHooks(targetName);
   finish(ctx);
   if (ctx.cleanupPreviousBackup) ctx.cleanupPreviousBackup();
 }
@@ -287,9 +289,12 @@ for (let i = 0; i < args.length; i++) {
 `);
     console.log(`  ${c.cyn('--target, -t')} <${formatTargetList('|')}>   install one target`);
     console.log(`  ${c.cyn('--uninstall, -u')} <${formatTargetList('|')}>   remove one target`);
-    console.log(`  ${c.cyn('--with-abyss')}   download abyss binary to ~/.code-abyss/bin (code graph index)`);
-    console.log(`  ${c.cyn('--with-mcp')}     register abyss MCP server (claude/codex/gemini)`);
-    console.log(`  ${c.cyn('--with-hooks')}   inject SessionStart + Edit/Write hooks (opt-in; off by default)`);
+    console.log(`  ${c.cyn('--with-abyss')}   ${c.ylw('[DEPRECATED v4.9, removed v5.0]')} download abyss binary;`);
+    console.log(`                 use \`curl -fsSL https://raw.githubusercontent.com/telagod/abyss/main/install.sh | bash\` instead`);
+    console.log(`  ${c.cyn('--with-mcp')}     ${c.ylw('[DEPRECATED v4.9, removed v5.0]')} register abyss MCP server;`);
+    console.log(`                 add { command: "abyss", args: ["mcp"] } to your MCP client config directly`);
+    console.log(`  ${c.cyn('--with-hooks')}   inject hooks (opt-in). claude/codex/gemini: ${c.ylw('[DEPRECATED v4.9]')} use \`abyss attach <host>\`;`);
+    console.log(`                 openclaw/pi/hermes: spawns skills/indexing-code/hooks/common/install-hooks.sh (kept in v5.0)`);
     console.log(`  ${c.cyn('--style')} <slug>  ${c.cyn('--persona')} <slug>  ${c.cyn('-y')}
 `);
     console.log(`${c.b('Examples')}`);
@@ -301,6 +306,50 @@ for (let i = 0; i < args.length; i++) {
   }
 }
 
+// ── v4.9.0 deprecation 期 helper（2026-06-25 起；见 [[code-abyss-v5-split]] memory + abyss v0.5.24 CHANGELOG） ──
+//
+// 三 flag 的对外承诺：
+//   --with-abyss (v4.9 deprecation, v5.0 移除) → abyss 仓库自身的 install.sh / cargo binstall / npm wrapper 接管
+//   --with-mcp   (v4.9 deprecation, v5.0 移除) → 客户端 MCP 配置直接写 mcpServers.abyss
+//   --with-hooks 分双 scope：
+//     • claude/codex/gemini → v4.9 deprecation + 仍 inject；v5.0 移除该路径，引导 abyss attach <host>
+//     • openclaw/pi/hermes  → v4.9 起新增能力：自动 spawn install-hooks.sh（abyss CLI 设计上不接管这三平台）；v5.0 永久保留
+
+function emitDeprecationWarnings(targetName) {
+  if (withAbyss) {
+    process.stderr.write(`${c.ylw('⚠ DEPRECATED')} --with-abyss 将在 v5.0 移除（abyss 二进制分发已转交 abyss 仓库本体）\n`);
+    process.stderr.write(`  ${c.b('迁移:')} ${c.d('curl -fsSL https://raw.githubusercontent.com/telagod/abyss/main/install.sh | bash')}\n`);
+    process.stderr.write(`         ${c.d('# 或 cargo binstall code-abyss / npm i -g @code-abyss/cli')}\n`);
+  }
+  if (withMcp) {
+    process.stderr.write(`${c.ylw('⚠ DEPRECATED')} --with-mcp 将在 v5.0 移除（MCP 注册由客户端自管）\n`);
+    process.stderr.write(`  ${c.b('迁移:')} 客户端 MCP 配置中添加 ${c.d('mcpServers.abyss = { command: "abyss", args: ["mcp"] }')}\n`);
+  }
+  if (withHooks && targetName && ['claude', 'codex', 'gemini'].includes(targetName)) {
+    process.stderr.write(`${c.ylw('⚠ DEPRECATED')} --with-hooks 对 ${targetName} 将在 v5.0 移除（abyss attach 是 production 主入口）\n`);
+    process.stderr.write(`  ${c.b('迁移:')} ${c.d(`abyss attach ${targetName}`)} ${c.d('# abyss v0.5.20+，幂等')}\n`);
+  }
+}
+
+// --with-hooks 对 openclaw 的真正能力（v4.9 起）：自动 spawn install-hooks.sh。
+// abyss CLI 设计上不接管 openclaw（per-pack layout 单二进制无法可靠创建），
+// 所以 code-abyss 是 openclaw hook 注入的唯一入口。pi/hermes 不在 install target 列表，
+// 但若未来扩 target 至 pi/hermes，本函数已就位。
+function maybeSpawnInstallHooks(targetName) {
+  if (!withHooks) return;
+  if (!['openclaw', 'pi', 'hermes'].includes(targetName)) return;
+  const scriptPath = path.join(PKG_ROOT, 'skills', 'indexing-code', 'hooks', 'common', 'install-hooks.sh');
+  if (!fs.existsSync(scriptPath)) {
+    warn(`--with-hooks: install-hooks.sh 未找到 (${scriptPath})`);
+    return;
+  }
+  info(`--with-hooks → bash install-hooks.sh ${targetName}`);
+  const { spawnSync } = require('child_process');
+  const r = spawnSync('bash', [scriptPath, targetName], { stdio: 'inherit' });
+  if (r.status === 0) ok(`hook 已注入 ${targetName}`);
+  else warn(`install-hooks.sh ${targetName} 退出码 ${r.status ?? 'n/a'}（不阻断安装）`);
+}
+
 // ── Select flows (must be assembled after CLI parsing) ──
 
 const { createSelectFlows } = require(path.join(__dirname, 'lib', 'select.js'));

bin/lib/abyss-binary.js

@@ -9,6 +9,14 @@
 //   - 零额外依赖：Node 18+ 内建 fetch + 系统 tar（Windows 10+ 的 bsdtar
 //     同时支持 .tar.gz 与 .zip），与 abyss npm wrapper 同一套已验证逻辑。
 //   - 下载失败不阻断安装流程：报告原因 + 给出手动安装路，由 finish 收尾提示。
+//
+// ── @deprecated v4.9.0（2026-06-25）──
+//
+// abyss 二进制分发已转交 abyss 仓库自身的 install.sh / `cargo binstall code-abyss`
+// / npm wrapper `@code-abyss/cli`（见 abyss v0.5.24 CHANGELOG）。本文件在 v4.9
+// 保留以兼容 `--with-abyss` flag；install.js 触发时打印 deprecation warning
+// 引导用户改用 `curl -fsSL https://raw.githubusercontent.com/telagod/abyss/main/install.sh | bash`。
+// v5.0 物理删除本文件与 `--with-abyss` flag。
 
 const fs = require('fs');
 const path = require('path');