@handsupmin/gc-tree 0.2.0 → 0.3.0

package/README.zh.md

@@ -36,6 +36,39 @@
 
 ---
 
+## 安装与快速开始
+
+```bash
+npm install -g @handsupmin/gc-tree
+gctree init
+```
+
+`gctree init` 会引导你：
+
+1. 选择 provider：`claude-code`、`codex` 或 `both`
+2. 在当前仓库安装集成文件
+3. 为 `main` gc-branch 完成引导式 onboarding
+
+之后，AI 工具会安装真正的 SessionStart / UserPromptSubmit hook 集成：在开始工作前自动检查 gc-tree，并在整个会话内缓存空结果和 no-match。
+
+- **CLI：** `gctree`
+- **要求：** Node.js 20+
+
+---
+
+## 适合哪些人
+
+如果以下几条符合你的情况，gc-tree 会很适合你：
+
+- 工作横跨**多个仓库**（单体仓库团队、平台 + 客户仓库、后端 + 前端技术栈）
+- 同一周内要在**多个产品或客户**之间来回切换
+- 每次开 AI 会话都要**重复解释相同的上下文**
+- 希望 AI 工具不只了解当前文件，还能理解**编码规范、架构和领域知识**
+
+如果你只在一个仓库、一个产品里工作，不需要这个工具。`CLAUDE.md` 或 `.cursorrules` 就够了。
+
+---
+
 ## gc-tree 做什么
 
 `gc-tree` 工作在**仓库之上**。它把上下文存储为结构化的 Markdown 文件，让 AI 工具在每次会话前自动拉取相关内容。
@@ -64,34 +97,21 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 
 ---
 
-## 适合哪些人
-
-如果以下几条符合你的情况，gc-tree 会很适合你：
-
-- 工作横跨**多个仓库**（单体仓库团队、平台 + 客户仓库、后端 + 前端技术栈）
-- 同一周内要在**多个产品或客户**之间来回切换
-- 每次开 AI 会话都要**重复解释相同的上下文**
-- 希望 AI 工具不只了解当前文件，还能理解**编码规范、架构和领域知识**
-
-如果你只在一个仓库、一个产品里工作，不需要这个工具。`CLAUDE.md` 或 `.cursorrules` 就够了。
-
----
-
 ## 和 CLAUDE.md 或 cursor rules 有什么区别？
 
 `CLAUDE.md` 很好用——在单个仓库里。
 
 一旦你有了多个仓库、客户或工作线：
 
-| | `CLAUDE.md` / cursor rules | `gc-tree` |
-|---|---|---|
-| 作用范围 | 单个仓库 | 多个仓库，一套上下文 |
-| 持久化方式 | 仓库内的文件 | 存储在仓库外，跨会话复用 |
-| 切换上下文 | 手动编辑文件 | `gctree checkout client-b` |
-| 相关性过滤 | 全部或全无 | 只注入匹配的文档（约 4%） |
-| 初始化方式 | 手写 | 由 AI 工具引导完成 |
-| 支持 Codex | ✅ | ✅ |
-| 支持 Claude Code | ✅ | ✅ |
+|                  | `CLAUDE.md` / cursor rules | `gc-tree`                  |
+| ---------------- | -------------------------- | -------------------------- |
+| 作用范围         | 单个仓库                   | 多个仓库，一套上下文       |
+| 持久化方式       | 仓库内的文件               | 存储在仓库外，跨会话复用   |
+| 切换上下文       | 手动编辑文件               | `gctree checkout client-b` |
+| 相关性过滤       | 全部或全无                 | 只注入匹配的文档（约 4%）  |
+| 初始化方式       | 手写                       | 由 AI 工具引导完成         |
+| 支持 Codex       | ✅                         | ✅                         |
+| 支持 Claude Code | ✅                         | ✅                         |
 
 ---
 
@@ -99,13 +119,13 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 
 基于真实内部文档测试（4 份 Notion 导出，中英文混合查询）：
 
-| 指标 | 结果 |
-|---|---|
-| Recall——相关查询找到正确文档的比例 | **100%**（16/16） |
-| Precision——无关查询返回空结果的比例 | **80%**（4/5） |
-| F1 分数 | **88.9%** |
-| 每次查询注入的 token 占总上下文的比例 | **约 4%** |
-| 支持中英文混合查询 | ✅ |
+| 指标                                  | 结果              |
+| ------------------------------------- | ----------------- |
+| Recall——相关查询找到正确文档的比例    | **100%**（16/16） |
+| Precision——无关查询返回空结果的比例   | **80%**（4/5）    |
+| F1 分数                               | **88.9%**         |
+| 每次查询注入的 token 占总上下文的比例 | **约 4%**         |
+| 支持中英文混合查询                    | ✅                |
 
 ---
 
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
 
 ---
 
-## 安装与快速开始
-
-```bash
-npm install -g @handsupmin/gc-tree
-gctree init
-```
-
-`gctree init` 会引导你：
-1. 选择 provider：`claude-code`、`codex` 或 `both`
-2. 在当前仓库安装集成文件
-3. 为 `main` gc-branch 完成引导式 onboarding
-
-之后，AI 工具会自动学会在规划或实现前调用 `gctree resolve`。
-
-- **CLI：** `gctree`
-- **要求：** Node.js 20+
-
----
-
 ## 常用操作
 
 ### 为不同工作线创建独立上下文
@@ -214,19 +215,19 @@ gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
 
 ## 核心命令
 
-| 目标 | 命令 |
-|---|---|
-| 初始化 gc-tree 并选择 provider | `gctree init` |
-| 确认当前激活的 gc-branch | `gctree status` |
-| 搜索当前上下文 | `gctree resolve --query "..."` |
-| 创建或切换 gc-branch | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| 列出所有 gc-branch | `gctree branches` |
-| 对空 gc-branch 进行引导式 onboarding | `gctree onboard` |
-| 对当前 gc-branch 进行引导式更新 | `gctree update-global-context` / `gctree ugc` |
-| 查看仓库范围规则 | `gctree repo-map` |
-| 为 gc-branch 包含或排除当前仓库 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
-| 重新 onboarding 前重置 gc-branch | `gctree reset-gc-branch --branch <name> --yes` |
-| 在新环境中安装 scaffold | `gctree scaffold --host codex --target /path/to/repo` |
+| 目标                                 | 命令                                                            |
+| ------------------------------------ | --------------------------------------------------------------- |
+| 初始化 gc-tree 并选择 provider       | `gctree init`                                                   |
+| 确认当前激活的 gc-branch             | `gctree status`                                                 |
+| 搜索当前上下文                       | `gctree resolve --query "..."`                                  |
+| 创建或切换 gc-branch                 | `gctree checkout <branch>` / `gctree checkout -b <branch>`      |
+| 列出所有 gc-branch                   | `gctree branches`                                               |
+| 对空 gc-branch 进行引导式 onboarding | `gctree onboard`                                                |
+| 对当前 gc-branch 进行引导式更新      | `gctree update-global-context` / `gctree ugc`                   |
+| 查看仓库范围规则                     | `gctree repo-map`                                               |
+| 为 gc-branch 包含或排除当前仓库      | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| 重新 onboarding 前重置 gc-branch     | `gctree reset-gc-branch --branch <name> --yes`                  |
+| 在新环境中安装 scaffold              | `gctree scaffold --host codex --target /path/to/repo`           |
 
 ---
 

package/dist/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
 import { stdin } from 'node:process';
+import { dispatchGcTreeHook } from './hook.js';
 import { onboardBranch } from './onboard.js';
 import { buildProviderLaunchPlan, maybeLaunchProvider, promptLanguageSelection, promptLaunchProviderSelection, promptProviderSelection, } from './provider.js';
 import { DEFAULT_BRANCH, resolveHome } from './paths.js';
@@ -37,12 +38,20 @@ function usage() {
 Internal commands:
   gctree __apply-onboarding --input FILE [--home DIR] [--branch NAME]
   gctree __apply-update --input FILE [--home DIR] [--branch NAME]
+  gctree __hook --event <SessionStart|UserPromptSubmit> [--home DIR]
 `);
     process.exit(1);
 }
 async function readJsonFile(path) {
     return JSON.parse(await readFile(path, 'utf8'));
 }
+async function readStdinText() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
 function normalizeProvider(value) {
     if (!value)
         return undefined;
@@ -337,6 +346,22 @@ async function main() {
             console.log(JSON.stringify(result, null, 2));
             return;
         }
+        case '__hook': {
+            const event = readArg('--event');
+            if (event !== 'SessionStart' && event !== 'UserPromptSubmit')
+                usage();
+            const raw = await readStdinText();
+            const payload = raw.trim() ? JSON.parse(raw) : {};
+            const result = await dispatchGcTreeHook({
+                event,
+                home,
+                payload,
+            });
+            if (result) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            return;
+        }
         case 'scaffold': {
             const host = normalizeProviderMode(readArg('--host'));
             if (!host)

package/dist/src/hook.js

@@ -0,0 +1,209 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname } from 'node:path';
+import { DEFAULT_BRANCH } from './paths.js';
+import { hookCachePath, } from './paths.js';
+import { branchScopeStatus, readBranchRepoMap, resolveBranchForRepo } from './repo-map.js';
+import { resolveContext } from './resolve.js';
+import { readHead, statusForBranch } from './store.js';
+function normalizeText(value) {
+    return value.trim().replace(/\s+/g, ' ');
+}
+function hashQuery(query) {
+    return createHash('sha1').update(normalizeText(query).toLowerCase()).digest('hex');
+}
+function limitMatches(matches, max = 3) {
+    return matches.slice(0, max);
+}
+function formatMatches(matches) {
+    return limitMatches(matches)
+        .map((match, index) => `${index + 1}. ${match.title}\n   Summary: ${match.summary}\n   Excerpt: ${match.excerpt}`)
+        .join('\n');
+}
+function buildSessionStartContext({ gcBranch, currentRepo, repoScopeStatus, }) {
+    return [
+        `gc-tree auto-resolve is active for this session.`,
+        `Active gc-branch: "${gcBranch}".`,
+        `Current repo: ${currentRepo || 'unscoped'}.`,
+        `Repo scope status: ${repoScopeStatus}.`,
+        `Before acting on new user prompts, use gc-tree hook context first. If the hook reports no reusable global context, avoid redundant resolve calls for the same session state unless the repo, gc-branch, or task changes materially.`,
+    ].join(' ');
+}
+function buildEmptyBranchContext({ gcBranch, currentRepo, cached, }) {
+    return [
+        `gc-tree auto-resolve ${cached ? 'used cached state' : 'checked the active gc-branch'} and found no reusable global context for this session because gc-branch "${gcBranch}" currently has 0 docs.`,
+        `Repo: ${currentRepo || 'unscoped'}.`,
+        `Treat this as "no reusable global context yet" until the gc-branch content changes or a different repo/gc-branch is active.`,
+    ].join(' ');
+}
+function buildExcludedContext({ gcBranch, currentRepo, cached, }) {
+    return [
+        `gc-tree auto-resolve ${cached ? 'used cached state' : 'checked the active gc-branch'} and found that repo "${currentRepo || 'unknown'}" is excluded from gc-branch "${gcBranch}".`,
+        `No reusable global context applies here unless the branch-repo mapping changes.`,
+    ].join(' ');
+}
+function buildNoMatchContext({ gcBranch, currentRepo, query, cached, }) {
+    return [
+        `gc-tree auto-resolve ${cached ? 'skipped a redundant lookup using cached no-match state' : 'checked the active gc-branch'} and found no reusable global context for this prompt in gc-branch "${gcBranch}".`,
+        `Repo: ${currentRepo || 'unscoped'}.`,
+        `Query: "${query}".`,
+        `Only re-run resolve if the repo, gc-branch, or task changes materially.`,
+    ].join(' ');
+}
+function buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, query, matches, }) {
+    return [
+        `gc-tree auto-resolve checked gc-branch "${gcBranch}" for repo "${currentRepo || 'unscoped'}" (scope: ${repoScopeStatus}) before this prompt.`,
+        `Query: "${query}".`,
+        `Use these matching gc-tree summaries before planning or implementation:`,
+        formatMatches(matches),
+        `Read full docs only if the summaries are insufficient.`,
+    ].join('\n');
+}
+async function readHookCache(home, sessionId) {
+    try {
+        const raw = await readFile(hookCachePath(home, sessionId), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeHookCache(home, cache) {
+    const path = hookCachePath(home, cache.session_id);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+}
+function nextCacheState(previous, { sessionId, gcBranch, currentRepo, repoScopeStatus, }) {
+    const changed = !previous ||
+        previous.gc_branch !== gcBranch ||
+        previous.current_repo !== currentRepo ||
+        previous.repo_scope_status !== repoScopeStatus;
+    return {
+        version: 1,
+        session_id: sessionId,
+        gc_branch: gcBranch,
+        current_repo: currentRepo,
+        repo_scope_status: repoScopeStatus,
+        branch_empty: changed ? false : previous.branch_empty,
+        branch_excluded: changed ? false : previous.branch_excluded,
+        no_match_signatures: changed ? [] : previous.no_match_signatures,
+        updated_at: new Date().toISOString(),
+    };
+}
+function readSessionId(payload) {
+    const raw = normalizeText(payload.session_id || '');
+    return raw || 'default-session';
+}
+export async function dispatchGcTreeHook({ event, home, payload, }) {
+    const cwd = payload.cwd || process.cwd();
+    const head = (await readHead(home)) || DEFAULT_BRANCH;
+    const resolved = await resolveBranchForRepo({ home, head, cwd });
+    const gcBranch = resolved.gc_branch;
+    const currentRepo = resolved.current_repo;
+    const mapping = await readBranchRepoMap(home);
+    const repoScopeStatus = branchScopeStatus(mapping, gcBranch, currentRepo);
+    const sessionId = readSessionId(payload);
+    if (event === 'SessionStart') {
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildSessionStartContext({
+                    gcBranch,
+                    currentRepo,
+                    repoScopeStatus,
+                }),
+            },
+        };
+    }
+    const prompt = normalizeText(payload.user_prompt || '');
+    if (!prompt)
+        return null;
+    const branchStatus = await statusForBranch(home, gcBranch);
+    const previousCache = await readHookCache(home, sessionId);
+    const cache = nextCacheState(previousCache, {
+        sessionId,
+        gcBranch,
+        currentRepo,
+        repoScopeStatus,
+    });
+    if (repoScopeStatus === 'excluded') {
+        cache.branch_excluded = true;
+        cache.updated_at = new Date().toISOString();
+        await writeHookCache(home, cache);
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildExcludedContext({
+                    gcBranch,
+                    currentRepo,
+                    cached: previousCache?.branch_excluded === true,
+                }),
+            },
+        };
+    }
+    if (branchStatus.doc_count === 0) {
+        const wasCached = cache.branch_empty;
+        cache.branch_empty = true;
+        cache.updated_at = new Date().toISOString();
+        await writeHookCache(home, cache);
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildEmptyBranchContext({
+                    gcBranch,
+                    currentRepo,
+                    cached: wasCached,
+                }),
+            },
+        };
+    }
+    const query = currentRepo ? `${currentRepo} ${prompt}` : prompt;
+    const signature = hashQuery(query);
+    if (cache.no_match_signatures.includes(signature)) {
+        cache.updated_at = new Date().toISOString();
+        await writeHookCache(home, cache);
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildNoMatchContext({
+                    gcBranch,
+                    currentRepo,
+                    query,
+                    cached: true,
+                }),
+            },
+        };
+    }
+    const result = await resolveContext({ home, branch: gcBranch, query });
+    if (result.matches.length === 0) {
+        cache.no_match_signatures = [...new Set([...cache.no_match_signatures, signature])];
+        cache.updated_at = new Date().toISOString();
+        await writeHookCache(home, cache);
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildNoMatchContext({
+                    gcBranch,
+                    currentRepo,
+                    query,
+                    cached: false,
+                }),
+            },
+        };
+    }
+    cache.no_match_signatures = cache.no_match_signatures.filter((entry) => entry !== signature);
+    cache.updated_at = new Date().toISOString();
+    await writeHookCache(home, cache);
+    return {
+        hookSpecificOutput: {
+            hookEventName: event,
+            additionalContext: buildMatchContext({
+                gcBranch,
+                currentRepo,
+                repoScopeStatus,
+                query,
+                matches: result.matches,
+            }),
+        },
+    };
+}

package/dist/src/paths.js

@@ -26,3 +26,9 @@ export function branchIndexPath(home, branch) {
 export function branchDocsDir(home, branch) {
     return join(branchDir(home, branch), 'docs');
 }
+export function hookCacheDir(home) {
+    return join(home, 'hook-cache');
+}
+export function hookCachePath(home, sessionId) {
+    return join(hookCacheDir(home), `${sessionId}.json`);
+}

package/dist/src/scaffold.js

@@ -6,8 +6,8 @@ function renderCodexAgentsSnippet() {
         '# gctree Codex integration snippet',
         '',
         '- Treat the active gctree branch as a **gc-branch** when you describe it to users.',
-        '- Before planning or implementation, run `gctree status` to confirm the active gc-branch if it is unclear.',
-        '- Use `gctree resolve --query "<task>"` when reusable global context may matter.',
+        '- gctree init installs SessionStart and UserPromptSubmit hooks that auto-check gc-tree before work.',
+        '- Use the hook-injected gc-tree context first. If hooks are unavailable or clearly stale, run `gctree status` and `gctree resolve --query "<task>"` yourself before planning or implementation.',
         '- Use `$gc-onboard` only for an empty gc-branch.',
         '- Use `$gc-update-global-context` when durable context in the active gc-branch should change.',
         '',
@@ -18,12 +18,39 @@ function renderCodexBootstrapPrompt() {
         '# gctree Bootstrap',
         '',
         '- Keep the active gc-branch explicit whenever global context matters.',
-        '- Resolve reusable global context before planning or implementation when it may change the answer.',
+        '- Trust auto-resolved gc-tree hook context first; if it is missing, resolve reusable global context before planning or implementation.',
         '- Read summaries first and only open full docs when needed.',
         '- Treat gctree docs as explicit source-of-truth markdown, not hidden memory.',
         '',
     ].join('\n');
 }
+function renderCodexHooksJson() {
+    return JSON.stringify({
+        hooks: {
+            SessionStart: [
+                {
+                    matcher: 'startup|resume',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'gctree __hook --event SessionStart',
+                        },
+                    ],
+                },
+            ],
+            UserPromptSubmit: [
+                {
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'gctree __hook --event UserPromptSubmit',
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2);
+}
 function renderCodexResolveSkill() {
     return [
         '---',
@@ -80,8 +107,8 @@ function renderClaudeSnippet() {
         '# gctree Claude Code integration snippet',
         '',
         '- Treat the active gctree branch as a **gc-branch** in user-facing language.',
-        '- Run `gctree status` before relying on global context if the active gc-branch is unclear.',
-        '- Use `gctree resolve --query "<task>"` when reusable global context may matter.',
+        '- gctree init installs SessionStart and UserPromptSubmit hooks that auto-check gc-tree before work.',
+        '- Use the hook-injected gc-tree context first. If hooks are unavailable or clearly stale, run `gctree status` and `gctree resolve --query "<task>"` yourself before planning or implementation.',
         '- Use `/gc-onboard` only for an empty gc-branch.',
         '- Use `/gc-update-global-context` when durable context in the active gc-branch should change.',
         '',
@@ -91,12 +118,43 @@ function renderClaudeSessionStartHook() {
     return [
         '# gctree Claude Code SessionStart note',
         '',
-        '- At session start, confirm the active gc-branch with `gctree status` when reusable global context may matter.',
+        '- gctree init installs real SessionStart/UserPromptSubmit hooks via `.claude/hooks/hooks.json`.',
+        '- At session start, use the injected hook context to confirm the active gc-branch.',
         '- Refer to gctree branches as **gc-branches** in user-facing language.',
-        '- Resolve summaries before planning or implementation when branch-level context may change the answer.',
+        '- If hook context is missing or stale, resolve summaries before planning or implementation when branch-level context may change the answer.',
         '',
     ].join('\n');
 }
+function renderClaudeHooksJson() {
+    return JSON.stringify({
+        hooks: {
+            SessionStart: [
+                {
+                    matcher: '*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'gctree __hook --event SessionStart',
+                            timeout: 10,
+                        },
+                    ],
+                },
+            ],
+            UserPromptSubmit: [
+                {
+                    matcher: '*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'gctree __hook --event UserPromptSubmit',
+                            timeout: 10,
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2);
+}
 function renderClaudeResolveCommand() {
     return [
         '---',
@@ -150,6 +208,7 @@ function scaffoldFiles(host) {
     if (host === 'codex') {
         return [
             { path: 'AGENTS.md', content: renderCodexAgentsSnippet() },
+            { path: '.codex/hooks.json', content: renderCodexHooksJson() },
             { path: '.codex/prompts/gctree-bootstrap.md', content: renderCodexBootstrapPrompt() },
             { path: '.codex/skills/gc-resolve-context/SKILL.md', content: renderCodexResolveSkill() },
             { path: '.codex/skills/gc-onboard/SKILL.md', content: renderCodexOnboardSkill() },
@@ -158,6 +217,7 @@ function scaffoldFiles(host) {
     }
     return [
         { path: 'CLAUDE.md', content: renderClaudeSnippet() },
+        { path: '.claude/hooks/hooks.json', content: renderClaudeHooksJson() },
         { path: '.claude/hooks/gctree-session-start.md', content: renderClaudeSessionStartHook() },
         { path: '.claude/commands/gc-resolve-context.md', content: renderClaudeResolveCommand() },
         { path: '.claude/commands/gc-onboard.md', content: renderClaudeOnboardCommand() },