@colin4k1024/tsp 2.4.8 → 2.4.9

package/README.md

@@ -65,7 +65,7 @@ TSP 整合了多个社区开源框架的精华能力，而非从零构建：
 |------|------|--------------|
 | **ECC** (Everything Claude Code) | 社区 | 125+ specialist skills、27 specialist agents、language rules packs、runtime hooks、安装工具链 |
 | **BMAD** | 方法来源（已吸收） | 单入口主链（`/team-help`）、Requirement Challenge、Design Review、Implementation Readiness、Story Slice、`artifact:persist` 落盘、Release→Closeout 收口 |
-| **CodeGraph** | 社区（`colbymchenry/codegraph`） | 默认内置 MCP-backed 代码图谱能力（符号搜索、调用链、impact、focused context），以 npm 依赖 + target-scoped installer wrapper + 本地 skill 接入 |
+| **CodeGraph** | 社区（`colbymchenry/codegraph`） | 默认内置 MCP-backed 代码图谱能力（符号搜索、调用链、impact、focused context），以官方 standalone installer + target-scoped wrapper + Claude 自动初始化 hook 接入 |
 | **Graphify** | 社区（`safishamsi/graphify`） | 可选知识图谱能力（brownfield 结构扫描、依赖路径分析、架构问答证据），以 runbook + 本地 skill 接入，不替换 workflow-engine |
 | **GitNexus** | 社区（`abhigyanpatwari/GitNexus`） | 受控可选代码智能能力（MCP 查询、impact、detect_changes、多仓图谱证据），以 runbook + thin skill 接入，不内置依赖 |
 | **Open Design** | 社区（`nexu-io/open-design`） | 受控可选设计工作台能力（本地优先原型、deck、dashboard、mobile flow、`DESIGN.md`、导出 artifact），以 runbook + thin skill 接入，不内置 daemon |
@@ -209,7 +209,7 @@ TSP 的公开能力是在多个社区项目、技能仓库和工程方法论的
 | 仓库 | 在 TSP 中的关系 | 说明 |
 |------|------|------|
 | [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 上游能力来源 | ECC harness layer、specialist agents、skills、runtime hooks 与安装工具链的重要参考来源 |
-| [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) | 默认内置接入 | 为 brownfield 符号搜索、调用链、impact 和 focused context 提供本地 MCP-backed 代码图谱能力；TSP 通过 target-scoped wrapper 调用上游 installer |
+| [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) | 默认内置接入 | 为 brownfield 符号搜索、调用链、impact 和 focused context 提供本地 MCP-backed 代码图谱能力；TSP 通过 target-scoped wrapper 调用上游 standalone installer |
 | [safishamsi/graphify](https://github.com/safishamsi/graphify) | 已吸收并本地化 | 为 brownfield 结构扫描、依赖路径分析与架构问答补充知识图谱能力 |
 | [abhigyanpatwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus) | 受控可选接入 | 为 brownfield MCP 查询、impact、detect_changes 和多仓代码图谱证据提供外部能力；因许可证与 Node 20 要求，不内置依赖 |
 | [nexu-io/open-design](https://github.com/nexu-io/open-design) | 受控可选接入 | 为本地优先原型、deck、dashboard、mobile flow、`DESIGN.md` 与可导出视觉 artifact 提供外部设计工作台；不内置 daemon 或上游源码 |
@@ -279,7 +279,7 @@ TSP 的公开能力是在多个社区项目、技能仓库和工程方法论的
 - 定位：CodeGraph 作为默认内置 MCP-backed 代码图谱能力，Graphify 作为轻量结构证据层，GitNexus 作为受控可选深代码智能层；三者都不替代 workflow-engine 或 `/team-*` 主链。
 - 入口：CodeGraph 先执行 `npm run codegraph:doctor`，Graphify 先执行 `npm run graphify:doctor`，GitNexus 先执行 `npm run gitnexus:doctor`；详细操作见 [codegraph-code-intelligence-usage.md](docs/runbooks/codegraph-code-intelligence-usage.md)、[graphify-knowledge-graph-usage.md](docs/runbooks/graphify-knowledge-graph-usage.md) 与 [gitnexus-code-intelligence-usage.md](docs/runbooks/gitnexus-code-intelligence-usage.md)。
 - 分发：通过安装模块 `knowledge-graph` 与组件 `capability:knowledge-graph` 提供；默认纳入 `developer`、`team`、`research` 与 `full` profile，`core` 保持轻量。
-- 治理边界：TSP 只通过 `scripts/install-codegraph.js` 以当前 target 调用 CodeGraph installer，不使用 `--target=auto`，也不在安装时运行 `codegraph init -i`；Graphify/GitNexus 的自动 setup 类命令仍不在本仓库执行。
+- 治理边界：TSP 通过 `scripts/install-codegraph.js` 使用 CodeGraph 官方 standalone installer，不使用 `--target=auto`；Claude `SessionStart` 可在新项目静默执行 `codegraph init -i`，Codex/OpenCode 仅写入说明和诊断边界；Graphify/GitNexus 的自动 setup 类命令仍不在本仓库执行。
 
 ## 近期新增功能（v2.0.0 → v2.3.0）
 

package/hooks/hooks.json

@@ -232,6 +232,17 @@
         ],
         "description": "Load previous context and detect package manager on new session",
         "id": "session:start"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"session:codegraph:auto-init\" \"scripts/hooks/codegraph-auto-init.js\" \"minimal,standard,strict\""
+          }
+        ],
+        "description": "Silently initialize CodeGraph for new Claude projects when the index is missing",
+        "id": "session:codegraph:auto-init"
       }
     ],
     "PostToolUse": [

package/manifests/install-modules.json

@@ -305,11 +305,12 @@
         "docs/runbooks/graphify-knowledge-graph-usage.md",
         "docs/runbooks/gitnexus-code-intelligence-usage.md",
         "scripts/codegraph-preflight.js",
-        "scripts/install-codegraph.js"
+        "scripts/install-codegraph.js",
+        "scripts/hooks/codegraph-auto-init.js"
       ],
       "externalInstall": {
         "id": "codegraph",
-        "description": "Run the upstream CodeGraph installer through a TSP target-scoped wrapper; never uses --target=auto and never initializes project indexes.",
+        "description": "Install the upstream CodeGraph standalone CLI when needed, then run the target-scoped CodeGraph installer; never uses --target=auto.",
         "command": "node",
         "script": "scripts/install-codegraph.js",
         "args": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colin4k1024/tsp",
-  "version": "2.4.8",
+  "version": "2.4.9",
   "description": "Open-source Team Skills Platform for role-based AI delivery workflows, shared skills, hooks, commands, and multi-platform installs.",
   "repository": {
     "type": "git",
@@ -103,7 +103,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@colbymchenry/codegraph": "0.7.10",
     "@iarna/toml": "^2.2.5",
     "@inquirer/prompts": "^7.5.0",
     "ajv": "^8.18.0",

package/scripts/codegraph-preflight.js

@@ -1,62 +1,66 @@
 #!/usr/bin/env node
 'use strict'
 
-const fs = require('fs')
-const path = require('path')
 const { spawnSync } = require('child_process')
-const { buildInstallCommand, mapTarget } = require('./install-codegraph')
-
-const MIN_NODE_MAJOR = 18
-const MAX_NODE_MAJOR_EXCLUSIVE = 25
-const PACKAGE_NAME = '@colbymchenry/codegraph'
-
-function parseNodeVersion(text) {
-  const match = String(text || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)/)
-  if (!match) {
-    return null
+const {
+  buildStandaloneInstallerInfo,
+  findOnPath,
+  mapTarget,
+  resolveCodeGraphBin,
+} = require('./install-codegraph')
+
+function detectPlatform(platform = process.platform) {
+  if (platform === 'darwin' || platform === 'linux' || platform === 'win32') {
+    return {
+      ok: true,
+      output: platform,
+    }
   }
+
   return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    raw: `${match[1]}.${match[2]}.${match[3]}`,
+    ok: false,
+    output: `unsupported platform: ${platform}`,
   }
 }
 
-function isNodeSupported(version) {
-  return Boolean(
-    version
-      && version.major >= MIN_NODE_MAJOR
-      && version.major < MAX_NODE_MAJOR_EXCLUSIVE
-  )
-}
-
-function loadPackageMetadata() {
-  if (process.env.CODEGRAPH_PREFLIGHT_PACKAGE_JSON) {
+function detectDownloader(platform = process.platform) {
+  const installer = buildStandaloneInstallerInfo(platform)
+  if (!installer.supported) {
     return {
-      ok: true,
-      source: 'env',
-      metadata: JSON.parse(process.env.CODEGRAPH_PREFLIGHT_PACKAGE_JSON),
+      ok: false,
+      output: installer.reason,
     }
   }
 
-  try {
-    const packageJsonPath = require.resolve(`${PACKAGE_NAME}/package.json`)
+  if (platform === 'win32') {
+    const command = findOnPath('powershell.exe') || findOnPath('powershell') || findOnPath('pwsh')
+    if (!command) {
+      return {
+        ok: false,
+        output: 'PowerShell not found; install PowerShell or provide CODEGRAPH_INSTALL_BIN',
+      }
+    }
     return {
       ok: true,
-      source: packageJsonPath,
-      metadata: JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')),
+      output: command,
     }
-  } catch (error) {
+  }
+
+  const curl = findOnPath('curl')
+  if (!curl) {
     return {
       ok: false,
-      source: 'node-resolution',
-      warning: error.message || String(error),
+      output: 'curl not found; install curl or provide CODEGRAPH_INSTALL_BIN',
     }
   }
+
+  return {
+    ok: true,
+    output: curl,
+  }
 }
 
-function detectCli(target) {
+function detectCli() {
   if (process.env.CODEGRAPH_PREFLIGHT_SKIP_CLI === '1') {
     return {
       ok: true,
@@ -65,27 +69,16 @@ function detectCli(target) {
     }
   }
 
-  let install
-  try {
-    install = buildInstallCommand(target || 'codex')
-  } catch (error) {
+  const resolved = resolveCodeGraphBin()
+  if (!resolved) {
     return {
       ok: false,
       command: 'codegraph',
-      output: error.message || String(error),
+      output: 'CodeGraph standalone binary not found',
     }
   }
 
-  if (!install.supported) {
-    return {
-      ok: true,
-      command: '(unsupported target skipped)',
-      output: install.reason,
-    }
-  }
-
-  const args = install.args.slice(0, install.args.length - 4).concat(['--help'])
-  const result = spawnSync(install.command, args, {
+  const result = spawnSync(resolved.command, [...resolved.argsPrefix, '--help'], {
     encoding: 'utf8',
     timeout: 8000,
   })
@@ -93,15 +86,15 @@ function detectCli(target) {
   if (result.error || result.status !== 0) {
     return {
       ok: false,
-      command: install.command,
+      command: resolved.command,
       output: result.error ? result.error.message : `${result.stdout || ''}${result.stderr || ''}`.trim(),
     }
   }
 
   return {
     ok: true,
-    command: install.command,
-    output: 'codegraph --help',
+    command: resolved.command,
+    output: `${resolved.displayCommand} (${resolved.source})`,
   }
 }
 
@@ -110,30 +103,24 @@ function main() {
   console.log('=========================')
 
   const target = process.env.TSP_INSTALL_TARGET || process.env.CODEGRAPH_PREFLIGHT_TARGET || ''
-  const nodeVersion = parseNodeVersion(process.env.CODEGRAPH_PREFLIGHT_NODE_VERSION || process.version)
-  const packageInfo = loadPackageMetadata()
-  const cli = detectCli(target)
+  const platform = detectPlatform()
+  const downloader = detectDownloader()
+  const cli = detectCli()
   const mappedTarget = target ? mapTarget(target) : null
   let hasFailure = false
 
-  if (!nodeVersion) {
-    hasFailure = true
-    console.log(`- Node: unable to detect version (requires >= ${MIN_NODE_MAJOR} and < ${MAX_NODE_MAJOR_EXCLUSIVE})`)
-  } else if (!isNodeSupported(nodeVersion)) {
+  if (!platform.ok) {
     hasFailure = true
-    console.log(`- Node: ${nodeVersion.raw} (requires >= ${MIN_NODE_MAJOR} and < ${MAX_NODE_MAJOR_EXCLUSIVE})`)
+    console.log(`- Platform: ${platform.output}`)
   } else {
-    console.log(`- Node: ${nodeVersion.raw} (ok)`)
+    console.log(`- Platform: ${platform.output} (ok)`)
   }
 
-  if (packageInfo.ok && packageInfo.metadata) {
-    const engine = packageInfo.metadata.engines && packageInfo.metadata.engines.node
-      ? packageInfo.metadata.engines.node
-      : '(not declared)'
-    console.log(`- CodeGraph package: ${packageInfo.metadata.version || '(unknown)'} (license ${packageInfo.metadata.license || '(unknown)'}, node ${engine})`)
-  } else {
+  if (!downloader.ok) {
     hasFailure = true
-    console.log(`- CodeGraph package: unavailable (${packageInfo.warning || 'not installed'})`)
+    console.log(`- Standalone installer dependency: ${downloader.output}`)
+  } else {
+    console.log(`- Standalone installer dependency: ${downloader.output} (ok)`)
   }
 
   if (!cli.ok) {
@@ -154,18 +141,23 @@ function main() {
   }
 
   console.log('\nControlled integration boundaries:')
+  console.log('- TSP installs CodeGraph through the official standalone curl/PowerShell installer when no binary is available.')
   console.log('- TSP calls CodeGraph installer with the current target only; it never uses --target=auto.')
-  console.log('- TSP install does not run `codegraph init -i`; initialize indexes inside target projects only.')
+  console.log('- Claude SessionStart may initialize project indexes automatically; Codex/OpenCode rely on instructions and diagnostics.')
   console.log('- Do not commit `.codegraph/` databases as TSP artifacts.')
 
   if (hasFailure) {
+    const installer = buildStandaloneInstallerInfo()
     console.log('\nFix failed checks before applying the CodeGraph integration.')
+    if (installer.supported) {
+      console.log(`Recommended standalone install: ${installer.display}`)
+    }
+    console.log('Offline fallback: set CODEGRAPH_INSTALL_BIN=/path/to/codegraph')
     process.exit(1)
   }
 
   console.log('\nRecommended next commands:')
   console.log('- npm run codegraph:doctor')
-  console.log('- codegraph init -i')
   console.log('- codegraph status')
 }
 
@@ -174,6 +166,7 @@ if (require.main === module) {
 }
 
 module.exports = {
-  isNodeSupported,
-  parseNodeVersion,
+  detectCli,
+  detectDownloader,
+  detectPlatform,
 }

package/scripts/hooks/codegraph-auto-init.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { resolveCodeGraphBin } = require('../install-codegraph');
+
+const STATE_FILE = path.join('.codegraph', 'tsp-auto-init-state.json');
+const DEFAULT_RETRY_MS = 60 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 2 * 60 * 1000;
+const PROJECT_MARKERS = Object.freeze([
+  'package.json',
+  'pyproject.toml',
+  'Cargo.toml',
+  'go.mod',
+  'pom.xml',
+  'build.gradle',
+  'build.gradle.kts',
+  'Gemfile',
+  'composer.json',
+  'mix.exs',
+  'deno.json',
+  'deno.jsonc',
+  'README.md',
+  'AGENTS.md',
+  'CLAUDE.md',
+]);
+
+function isDisabled() {
+  const value = String(process.env.TSP_CODEGRAPH_AUTO_INIT || '').trim().toLowerCase();
+  return value === '0' || value === 'false' || value === 'off';
+}
+
+function readHookInput(rawInput) {
+  if (!rawInput || !String(rawInput).trim()) {
+    return {};
+  }
+
+  try {
+    const parsed = JSON.parse(rawInput);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function normalizePath(candidate) {
+  try {
+    return fs.realpathSync(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+
+function getStartDir(rawInput) {
+  if (process.env.CODEGRAPH_AUTO_INIT_PROJECT_ROOT) {
+    return path.resolve(process.env.CODEGRAPH_AUTO_INIT_PROJECT_ROOT);
+  }
+
+  const input = readHookInput(rawInput);
+  const candidates = [
+    input.cwd,
+    input.projectDir,
+    input.project_dir,
+    input.projectPath,
+    input.project_path,
+    input.workspaceDir,
+    input.workspace_dir,
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) {
+      return path.resolve(candidate.trim());
+    }
+  }
+
+  return process.cwd();
+}
+
+function parseGitDirFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    const match = content.match(/^gitdir:\s*(.+)$/i);
+    if (!match) {
+      return null;
+    }
+    const gitDir = match[1].trim();
+    return path.resolve(path.dirname(filePath), gitDir);
+  } catch {
+    return null;
+  }
+}
+
+function findGitRoot(startDir) {
+  let current = normalizePath(startDir);
+  const root = path.parse(current).root;
+
+  while (current && current !== root) {
+    const gitPath = path.join(current, '.git');
+    if (fs.existsSync(gitPath)) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+
+  const rootGitPath = path.join(root, '.git');
+  return fs.existsSync(rootGitPath) ? root : null;
+}
+
+function findMarkerRoot(startDir) {
+  let current = normalizePath(startDir);
+  const root = path.parse(current).root;
+  const home = normalizePath(os.homedir());
+
+  while (current && current !== root) {
+    if (current === home) {
+      return null;
+    }
+    if (PROJECT_MARKERS.some(marker => fs.existsSync(path.join(current, marker)))) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+
+  return null;
+}
+
+function resolveProjectRoot(rawInput) {
+  const startDir = getStartDir(rawInput);
+  if (!fs.existsSync(startDir)) {
+    return null;
+  }
+
+  return findGitRoot(startDir) || findMarkerRoot(startDir);
+}
+
+function codegraphDbPath(projectRoot) {
+  return path.join(projectRoot, '.codegraph', 'codegraph.db');
+}
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, STATE_FILE);
+}
+
+function readState(projectRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(statePath(projectRoot), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeState(projectRoot, state) {
+  const filePath = statePath(projectRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+function retryDelayMs() {
+  const parsed = Number(process.env.TSP_CODEGRAPH_AUTO_INIT_RETRY_MS || DEFAULT_RETRY_MS);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_RETRY_MS;
+}
+
+function shouldThrottleFailure(projectRoot, now = Date.now()) {
+  const state = readState(projectRoot);
+  if (state.status !== 'failed' || !state.failedAt) {
+    return false;
+  }
+
+  const failedAt = Date.parse(state.failedAt);
+  if (!Number.isFinite(failedAt)) {
+    return false;
+  }
+
+  return now - failedAt < retryDelayMs();
+}
+
+function resolveGitDir(projectRoot) {
+  const gitPath = path.join(projectRoot, '.git');
+  try {
+    const stat = fs.statSync(gitPath);
+    if (stat.isDirectory()) {
+      return gitPath;
+    }
+    if (stat.isFile()) {
+      return parseGitDirFile(gitPath);
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+function ensureGitExclude(projectRoot) {
+  const gitDir = resolveGitDir(projectRoot);
+  if (!gitDir) {
+    return false;
+  }
+
+  const excludePath = path.join(gitDir, 'info', 'exclude');
+  fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+  const existing = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, 'utf8') : '';
+  const lines = existing.split(/\r?\n/).map(line => line.trim());
+  if (lines.includes('.codegraph/')) {
+    return false;
+  }
+
+  const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(excludePath, `${prefix}.codegraph/\n`, 'utf8');
+  return true;
+}
+
+function timeoutMs() {
+  const parsed = Number(process.env.TSP_CODEGRAPH_AUTO_INIT_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
+}
+
+function truncate(text, maxLength = 2000) {
+  const value = String(text || '');
+  return value.length > maxLength ? `${value.slice(0, maxLength)}...` : value;
+}
+
+function initializeProject(projectRoot) {
+  const resolved = resolveCodeGraphBin({ ignoreForceStandalone: true });
+  if (!resolved) {
+    throw new Error('CodeGraph binary not found. Install it with the official standalone installer or set CODEGRAPH_INSTALL_BIN.');
+  }
+
+  const result = spawnSync(resolved.command, [...resolved.argsPrefix, 'init', '-i', projectRoot], {
+    cwd: projectRoot,
+    env: process.env,
+    encoding: 'utf8',
+    timeout: timeoutMs(),
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(truncate(`${result.stdout || ''}${result.stderr || ''}`.trim() || `codegraph exited with status ${result.status}`));
+  }
+
+  return {
+    binary: resolved.displayCommand,
+  };
+}
+
+function runAutoInit(rawInput = '') {
+  if (isDisabled()) {
+    return { status: 'skipped', reason: 'disabled' };
+  }
+
+  const projectRoot = resolveProjectRoot(rawInput);
+  if (!projectRoot) {
+    return { status: 'skipped', reason: 'no-project-root' };
+  }
+
+  if (fs.existsSync(codegraphDbPath(projectRoot))) {
+    return { status: 'skipped', reason: 'already-initialized', projectRoot };
+  }
+
+  if (shouldThrottleFailure(projectRoot)) {
+    return { status: 'skipped', reason: 'recent-failure', projectRoot };
+  }
+
+  try {
+    ensureGitExclude(projectRoot);
+    const initialized = initializeProject(projectRoot);
+    writeState(projectRoot, {
+      status: 'initialized',
+      projectRoot,
+      initializedAt: new Date().toISOString(),
+      binary: initialized.binary,
+    });
+    return { status: 'initialized', projectRoot };
+  } catch (error) {
+    writeState(projectRoot, {
+      status: 'failed',
+      projectRoot,
+      failedAt: new Date().toISOString(),
+      error: truncate(error && error.message ? error.message : error),
+    });
+    return { status: 'failed', projectRoot, error };
+  }
+}
+
+function run(rawInput = '') {
+  const result = runAutoInit(rawInput);
+  if (result.status === 'failed' && process.env.TSP_CODEGRAPH_AUTO_INIT_VERBOSE === '1') {
+    return {
+      stderr: `[CodeGraph] auto-init failed for ${result.projectRoot}: ${result.error && result.error.message ? result.error.message : result.error}\n`,
+      exitCode: 0,
+    };
+  }
+  return { exitCode: 0 };
+}
+
+if (require.main === module) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    raw += chunk;
+  });
+  process.stdin.on('end', () => {
+    run(raw);
+  });
+}
+
+module.exports = {
+  codegraphDbPath,
+  ensureGitExclude,
+  findGitRoot,
+  findMarkerRoot,
+  readState,
+  resolveProjectRoot,
+  run,
+  runAutoInit,
+  shouldThrottleFailure,
+  statePath,
+};

package/scripts/install-codegraph.js

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 'use strict'
 
+const fs = require('fs')
+const os = require('os')
 const path = require('path')
 const { spawnSync } = require('child_process')
 
+const INSTALL_SH_URL = 'https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh'
+const INSTALL_PS1_URL = 'https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1'
+
 const SUPPORTED_TARGETS = Object.freeze({
   claude: 'claude',
   codex: 'codex',
@@ -50,29 +55,144 @@ function parseArgs(argv) {
   return parsed
 }
 
-function resolveCodeGraphBin() {
+function isWindows(platform = process.platform) {
+  return platform === 'win32'
+}
+
+function executableNames(name, platform = process.platform) {
+  if (!isWindows(platform)) {
+    return [name]
+  }
+
+  const extensions = String(process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+    .split(';')
+    .map(value => value.trim().toLowerCase())
+    .filter(Boolean)
+  const lowerName = name.toLowerCase()
+  if (extensions.some(ext => lowerName.endsWith(ext))) {
+    return [name]
+  }
+  return [name, ...extensions.map(ext => `${name}${ext}`)]
+}
+
+function canExecute(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function findOnPath(commandName, options = {}) {
+  const searchPath = options.pathValue !== undefined ? options.pathValue : process.env.PATH
+  const platform = options.platform || process.platform
+  const delimiter = isWindows(platform) ? ';' : path.delimiter
+  const names = executableNames(commandName, platform)
+
+  for (const entry of String(searchPath || '').split(delimiter)) {
+    if (!entry) {
+      continue
+    }
+    for (const name of names) {
+      const candidate = path.join(entry, name)
+      if (canExecute(candidate)) {
+        return candidate
+      }
+    }
+  }
+
+  return null
+}
+
+function defaultCodeGraphCandidates(options = {}) {
+  const homeDir = options.homeDir || os.homedir()
+  const platform = options.platform || process.platform
+
+  if (isWindows(platform)) {
+    const localAppData = process.env.LOCALAPPDATA || path.join(homeDir, 'AppData', 'Local')
+    return [
+      path.join(localAppData, 'codegraph', 'current', 'bin', 'codegraph.exe'),
+      path.join(localAppData, 'codegraph', 'current', 'bin', 'codegraph.cmd'),
+    ]
+  }
+
+  return [
+    path.join(homeDir, '.local', 'bin', 'codegraph'),
+    path.join(homeDir, '.codegraph', 'current', 'bin', 'codegraph'),
+  ]
+}
+
+function resolveCodeGraphBin(options = {}) {
   if (process.env.CODEGRAPH_INSTALL_BIN) {
     return {
       command: process.env.CODEGRAPH_INSTALL_BIN,
       argsPrefix: [],
       displayCommand: process.env.CODEGRAPH_INSTALL_BIN,
+      source: 'env',
     }
   }
 
-  let packageJsonPath
-  try {
-    packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json')
-  } catch (error) {
-    throw new Error(
-      'Unable to resolve @colbymchenry/codegraph. Run npm install before applying the CodeGraph integration.'
-    )
+  if (process.env.CODEGRAPH_INSTALL_FORCE_STANDALONE === '1' && !options.ignoreForceStandalone) {
+    return null
+  }
+
+  const pathCandidate = findOnPath('codegraph', options)
+  if (pathCandidate) {
+    return {
+      command: pathCandidate,
+      argsPrefix: [],
+      displayCommand: pathCandidate,
+      source: 'path',
+    }
+  }
+
+  for (const candidate of defaultCodeGraphCandidates(options)) {
+    if (canExecute(candidate)) {
+      return {
+        command: candidate,
+        argsPrefix: [],
+        displayCommand: candidate,
+        source: 'default-location',
+      }
+    }
+  }
+
+  return null
+}
+
+function resolvePowerShellCommand() {
+  return findOnPath('powershell.exe') || findOnPath('powershell') || findOnPath('pwsh') || 'powershell.exe'
+}
+
+function buildStandaloneInstallerInfo(platform = process.platform) {
+  if (platform === 'darwin' || platform === 'linux') {
+    return {
+      supported: true,
+      platform,
+      display: `curl -fsSL ${INSTALL_SH_URL} -o "$TMPDIR/codegraph-install.sh" && sh "$TMPDIR/codegraph-install.sh"`,
+      requiredCommand: 'curl',
+      url: INSTALL_SH_URL,
+    }
+  }
+
+  if (platform === 'win32') {
+    return {
+      supported: true,
+      platform,
+      display: `irm ${INSTALL_PS1_URL} | iex`,
+      requiredCommand: resolvePowerShellCommand(),
+      url: INSTALL_PS1_URL,
+    }
   }
 
-  const binPath = path.join(path.dirname(packageJsonPath), 'dist', 'bin', 'codegraph.js')
   return {
-    command: process.execPath,
-    argsPrefix: [binPath],
-    displayCommand: `${process.execPath} ${binPath}`,
+    supported: false,
+    platform,
+    display: '',
+    requiredCommand: '',
+    url: '',
+    reason: `CodeGraph standalone installer does not support platform: ${platform}`,
   }
 }
 
@@ -88,27 +208,101 @@ function buildInstallCommand(target) {
 
   const resolved = resolveCodeGraphBin()
   const args = [
-    ...resolved.argsPrefix,
+    ...(resolved ? resolved.argsPrefix : []),
     'install',
     `--target=${mappedTarget}`,
     '--location=global',
     '--yes',
   ]
+  const displayCommand = resolved ? resolved.displayCommand : 'codegraph'
 
   return {
     supported: true,
     target: mappedTarget,
+    command: resolved ? resolved.command : null,
+    args,
+    display: [displayCommand, ...args.slice(resolved ? resolved.argsPrefix.length : 0)].join(' '),
+    needsBootstrap: !resolved,
+    bootstrap: buildStandaloneInstallerInfo(),
+    binarySource: resolved ? resolved.source : null,
+  }
+}
+
+function spawnChecked(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env,
+    encoding: 'utf8',
+    stdio: options.stdio || ['inherit', process.stderr, process.stderr],
+    timeout: options.timeout,
+  })
+
+  return typeof result.status === 'number' ? result.status : 1
+}
+
+function runStandaloneInstaller() {
+  const installer = buildStandaloneInstallerInfo()
+  if (!installer.supported) {
+    throw new Error(installer.reason)
+  }
+
+  if (installer.platform === 'darwin' || installer.platform === 'linux') {
+    const curl = findOnPath('curl') || 'curl'
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-install-'))
+    const scriptPath = path.join(tempDir, 'install.sh')
+    try {
+      let status = spawnChecked(curl, ['-fsSL', INSTALL_SH_URL, '-o', scriptPath])
+      if (status !== 0) {
+        return status
+      }
+      status = spawnChecked('sh', [scriptPath])
+      return status
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  }
+
+  return spawnChecked(resolvePowerShellCommand(), [
+    '-NoProfile',
+    '-ExecutionPolicy',
+    'Bypass',
+    '-Command',
+    `irm ${INSTALL_PS1_URL} | iex`,
+  ])
+}
+
+function buildTargetInstallInvocation(target) {
+  const mappedTarget = mapTarget(target)
+  const resolved = resolveCodeGraphBin({ ignoreForceStandalone: true })
+  if (!mappedTarget || !resolved) {
+    return null
+  }
+
+  const args = [
+    ...resolved.argsPrefix,
+    'install',
+    `--target=${mappedTarget}`,
+    '--location=global',
+    '--yes',
+  ]
+
+  return {
     command: resolved.command,
     args,
-    display: [resolved.displayCommand, ...args.slice(resolved.argsPrefix.length)].join(' '),
   }
 }
 
 function printHelp() {
   console.log(`Usage: node scripts/install-codegraph.js [--target <claude|codex|cursor|opencode>] [--dry-run]
 
-Runs the upstream CodeGraph installer for the current TSP install target only.
-The project index is not initialized here; run codegraph init -i inside a target project when needed.
+Installs the standalone CodeGraph CLI with the official upstream curl/PowerShell installer when needed,
+then configures CodeGraph for the current TSP install target only.
+
+Environment:
+  CODEGRAPH_INSTALL_BIN=<path>         Use an existing CodeGraph binary, including offline installs.
+  CODEGRAPH_INSTALL_FORCE_STANDALONE=1 Re-run the official standalone installer before target config.
+
+Project indexes are created by the Claude SessionStart auto-init hook or by running codegraph init -i.
 `)
 }
 
@@ -126,19 +320,31 @@ function run(argv = process.argv.slice(2)) {
   }
 
   if (options.dryRun) {
-    console.log(`CodeGraph install command: ${install.display}`)
+    if (install.needsBootstrap) {
+      console.log(`CodeGraph standalone install command: ${install.bootstrap.display}`)
+    } else {
+      console.log(`CodeGraph binary: ${install.command} (${install.binarySource})`)
+    }
+    console.log(`CodeGraph target install command: ${install.display}`)
     return 0
   }
 
-  console.error(`Running CodeGraph installer for ${install.target}`)
-  const result = spawnSync(install.command, install.args, {
-    cwd: process.cwd(),
-    env: process.env,
-    encoding: 'utf8',
-    stdio: ['inherit', process.stderr, process.stderr],
-  })
+  if (install.needsBootstrap) {
+    console.error('Installing CodeGraph standalone CLI with the official upstream installer')
+    const bootstrapStatus = runStandaloneInstaller()
+    if (bootstrapStatus !== 0) {
+      return bootstrapStatus
+    }
+  }
 
-  return typeof result.status === 'number' ? result.status : 1
+  const invocation = buildTargetInstallInvocation(install.target)
+  if (!invocation) {
+    console.error('CodeGraph binary is still unavailable after standalone install. Add it to PATH or set CODEGRAPH_INSTALL_BIN.')
+    return 1
+  }
+
+  console.error(`Running CodeGraph installer for ${install.target}`)
+  return spawnChecked(invocation.command, invocation.args)
 }
 
 if (require.main === module) {
@@ -152,7 +358,11 @@ if (require.main === module) {
 
 module.exports = {
   buildInstallCommand,
+  buildStandaloneInstallerInfo,
+  defaultCodeGraphCandidates,
+  findOnPath,
   mapTarget,
   parseArgs,
+  resolveCodeGraphBin,
   run,
 }

package/skills/codegraph/SKILL.md

@@ -3,7 +3,7 @@ name: codegraph
 description: >
   将 CodeGraph 作为默认内置 MCP-backed 代码图谱能力接入，用于 brownfield 符号搜索、
   调用链、影响面和上下文查询。输出必须回落到 `/team-*` 主链和 artifacts。
-origin: colbymchenry/codegraph (default dependency with upstream installer wrapper)
+origin: colbymchenry/codegraph (official standalone installer with target-scoped wrapper)
 ---
 
 # CodeGraph
@@ -22,8 +22,8 @@ origin: colbymchenry/codegraph (default dependency with upstream installer wrapp
 
 ## 默认工作流
 
-1. 先跑 `npm run codegraph:doctor`，确认 Node、CodeGraph 包和当前 target wrapper 可用。
-2. 在消费方目标项目根目录手动初始化索引：
+1. 先跑 `npm run codegraph:doctor`，确认 standalone CodeGraph binary、官方 installer 依赖和当前 target wrapper 可用。
+2. Claude 新项目会通过 `SessionStart` 自动初始化索引；非 Claude 或关闭自动初始化时，在消费方目标项目根目录手动初始化：
    ```bash
    codegraph init -i
    ```
@@ -46,12 +46,13 @@ origin: colbymchenry/codegraph (default dependency with upstream installer wrapp
 ## 边界与禁用项
 
 - TSP 安装时只运行 `scripts/install-codegraph.js` wrapper，不使用上游 `--target=auto`。
-- TSP 安装流程不运行 `codegraph init -i`，避免在平台仓库或消费方仓库隐式写入 `.codegraph/`。
+- Claude `SessionStart` 可在新项目缺少 `.codegraph/codegraph.db` 时静默执行 `codegraph init -i <projectRoot>`；用 `TSP_CODEGRAPH_AUTO_INIT=0` 可关闭。
+- Codex / OpenCode 不做侵入式自动 hook，只依赖全局 MCP 配置、说明和 doctor 诊断。
 - 不提交 `.codegraph/` 数据库或将其作为 TSP artifact。
 - CodeGraph 结论不能绕过 `/team-plan`、`/team-review` 或验证门禁。
 
 ## 推荐组合
 
-- 默认 brownfield 结构证据：`/team-help -> /update-codemaps -> npm run codegraph:doctor -> codegraph init -i -> /team-plan`
+- 默认 brownfield 结构证据：`/team-help -> /update-codemaps -> npm run codegraph:doctor -> Claude 自动初始化或 codegraph init -i -> /team-plan`
 - 快速影响面确认：`/team-execute -> CodeGraph impact/callers/callees -> /handoff -> /team-review`
 - 深度多仓或许可证受限场景：按需选择 GitNexus 或 Graphify，并把结论统一回落到主链。

package/skills/goframe-v2/examples/practices/quick-demo/manifest/config/config.yaml

@@ -1,15 +1,15 @@
-# https://goframe.org/docs/web/server-config-file-template
-server:
-  address:     ":8000"
-  openapiPath: "/api.json"
-  swaggerPath: "/swagger"
-
-# https://goframe.org/docs/core/glog-config
-logger:
-  level : "all"
-  stdout: true
-
-# https://goframe.org/docs/core/gdb-config-file
-database:
-  default:
+# https://goframe.org/docs/web/server-config-file-template
+server:
+  address:     ":8000"
+  openapiPath: "/api.json"
+  swaggerPath: "/swagger"
+
+# https://goframe.org/docs/core/glog-config
+logger:
+  level : "all"
+  stdout: true
+
+# https://goframe.org/docs/core/gdb-config-file
+database:
+  default:
     link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test"

package/skills/repo-scan/SKILL.md

@@ -1,22 +1,22 @@
----
-name: repo-scan
-description: Cross-stack source code asset audit — classifies every file, detects embedded third-party libraries, and delivers actionable four-level verdicts per module with interactive HTML reports.
-origin: community
----
-
-# repo-scan
-
-> Every ecosystem has its own dependency manager, but no tool looks across C++, Android, iOS, and Web to tell you: how much code is actually yours, what's third-party, and what's dead weight.
-
-## When to Use
-
-- Taking over a large legacy codebase and need a structural overview
-- Before major refactoring — identify what's core, what's duplicate, what's dead
-- Auditing third-party dependencies embedded directly in source (not declared in package managers)
-- Preparing architecture decision records for monorepo reorganization
-
-## Installation
-
+---
+name: repo-scan
+description: Cross-stack source code asset audit — classifies every file, detects embedded third-party libraries, and delivers actionable four-level verdicts per module with interactive HTML reports.
+origin: community
+---
+
+# repo-scan
+
+> Every ecosystem has its own dependency manager, but no tool looks across C++, Android, iOS, and Web to tell you: how much code is actually yours, what's third-party, and what's dead weight.
+
+## When to Use
+
+- Taking over a large legacy codebase and need a structural overview
+- Before major refactoring — identify what's core, what's duplicate, what's dead
+- Auditing third-party dependencies embedded directly in source (not declared in package managers)
+- Preparing architecture decision records for monorepo reorganization
+
+## Installation
+
 ```bash
 # Fetch only the pinned commit for reproducibility
 mkdir -p ~/.claude/skills/repo-scan
@@ -27,52 +27,52 @@ git fetch --depth 1 origin 2742664
 git checkout --detach FETCH_HEAD
 cp -r . ~/.claude/skills/repo-scan
 ```
-
-> Review the source before installing any agent skill.
-
-## Core Capabilities
-
-| Capability | Description |
-|---|---|
-| **Cross-stack scanning** | C/C++, Java/Android, iOS (OC/Swift), Web (TS/JS/Vue) in one pass |
-| **File classification** | Every file tagged as project code, third-party, or build artifact |
-| **Library detection** | 50+ known libraries (FFmpeg, Boost, OpenSSL…) with version extraction |
-| **Four-level verdicts** | Core Asset / Extract & Merge / Rebuild / Deprecate |
-| **HTML reports** | Interactive dark-theme pages with drill-down navigation |
-| **Monorepo support** | Hierarchical scanning with summary + sub-project reports |
-
-## Analysis Depth Levels
-
-| Level | Files Read | Use Case |
-|---|---|---|
-| `fast` | 1-2 per module | Quick inventory of huge directories |
-| `standard` | 2-5 per module | Default audit with full dependency + architecture checks |
-| `deep` | 5-10 per module | Adds thread safety, memory management, API consistency |
-| `full` | All files | Pre-merge comprehensive review |
-
-## How It Works
-
+
+> Review the source before installing any agent skill.
+
+## Core Capabilities
+
+| Capability | Description |
+|---|---|
+| **Cross-stack scanning** | C/C++, Java/Android, iOS (OC/Swift), Web (TS/JS/Vue) in one pass |
+| **File classification** | Every file tagged as project code, third-party, or build artifact |
+| **Library detection** | 50+ known libraries (FFmpeg, Boost, OpenSSL…) with version extraction |
+| **Four-level verdicts** | Core Asset / Extract & Merge / Rebuild / Deprecate |
+| **HTML reports** | Interactive dark-theme pages with drill-down navigation |
+| **Monorepo support** | Hierarchical scanning with summary + sub-project reports |
+
+## Analysis Depth Levels
+
+| Level | Files Read | Use Case |
+|---|---|---|
+| `fast` | 1-2 per module | Quick inventory of huge directories |
+| `standard` | 2-5 per module | Default audit with full dependency + architecture checks |
+| `deep` | 5-10 per module | Adds thread safety, memory management, API consistency |
+| `full` | All files | Pre-merge comprehensive review |
+
+## How It Works
+
 1. **Classify the repo surface**: enumerate files, then tag each as project code, embedded third-party code, or build artifact.
 2. **Detect embedded libraries**: inspect directory names, headers, license files, and version markers to identify bundled dependencies and likely versions.
 3. **Score each module**: group files by module or subsystem, then assign one of the four verdicts based on ownership, duplication, and maintenance cost.
 4. **Highlight structural risks**: call out dead-weight artifacts, duplicated wrappers, outdated vendored code, and modules that should be extracted, rebuilt, or deprecated.
 5. **Produce the report**: return a concise summary plus the interactive HTML output with per-module drill-down so the audit can be reviewed asynchronously.
-
-## Examples
-
-On a 50,000-file C++ monorepo:
-- Found FFmpeg 2.x (2015 vintage) still in production
-- Discovered the same SDK wrapper duplicated 3 times
-- Identified 636 MB of committed Debug/ipch/obj build artifacts
-- Classified: 3 MB project code vs 596 MB third-party
-
-## Best Practices
-
-- Start with `standard` depth for first-time audits
-- Use `fast` for monorepos with 100+ modules to get a quick inventory
-- Run `deep` incrementally on modules flagged for refactoring
-- Review the cross-module analysis for duplicate detection across sub-projects
-
-## Links
-
-- [GitHub Repository](https://github.com/haibindev/repo-scan)
+
+## Examples
+
+On a 50,000-file C++ monorepo:
+- Found FFmpeg 2.x (2015 vintage) still in production
+- Discovered the same SDK wrapper duplicated 3 times
+- Identified 636 MB of committed Debug/ipch/obj build artifacts
+- Classified: 3 MB project code vs 596 MB third-party
+
+## Best Practices
+
+- Start with `standard` depth for first-time audits
+- Use `fast` for monorepos with 100+ modules to get a quick inventory
+- Run `deep` incrementally on modules flagged for refactoring
+- Review the cross-module analysis for duplicate detection across sub-projects
+
+## Links
+
+- [GitHub Repository](https://github.com/haibindev/repo-scan)