Skip to content

README.zh-CN.md

Latest commit

 

History

History
137 lines (104 loc) · 8.36 KB

README.zh-CN.md

File metadata and controls

137 lines (104 loc) · 8.36 KB
Raw

CodeGraph Plugin

插件市场导航

本插件所属分类：全栈开发。

分类 插件市场入口 用途
全栈开发 Full Stack Plugins 架构与 UI 设计、代码理解、质量检查、代码审查、流程治理与服务器运维
AIGC 内容创作 Full AIGC Plugins 图像、视频、音频、音乐、3D 与多模态内容创作

让 CodeGraph 在 AI 编码代理中被自然想起——官方提示词注入 + 23 个 CLI 命令中的 21 个暴露为 slash 命令。面向 Codex / ZCode / Kimi / Claude Code。

CodeGraph Plugin

Parity: README.md 与 README.zh-CN.md 必须保持相同的标题结构、链接和版本号；由 tests/test_readme_parity.py 强制。

English · 简体中文

本插件做什么

只做三件事，严格只这三件：

  1. 会话启动时，当 <cwd>/.codegraph/ 存在时，把官方 CodeGraph 提示词块（verbatim 同步自上游 codegraph/src/installer/instructions-template.ts）注入到：
    • 当前会话，通过 SessionStart.additionalContext JSON 输出；
    • <cwd>/.claude/CLAUDE.md（如果存在）；否则 <cwd>/AGENTS.md。使用标记区间原子替换——字节级幂等，所以与 codegraph install 并存是安全的。
  2. 暴露 codegraph 23 个 CLI 命令中的 21 个为 slash 命令，JSON（commands/*.json，由 kimi.plugin.json 声明）与 Markdown（kimi-commands/*.md）双格式，包括 4 个隐藏但实用的维护命令（daemon / unlock / version / telemetry）。
  3. 注册发现型技能（codegraph-helper），让智能体主动检查仓库是否已索引，未索引则主动提示可以索引。该技能在代码结构类问题上激活，不论 .codegraph/ 是否存在：先检查，已索引就用 CodeGraph 回答；未索引就告诉用户「此仓库尚未索引，要现在索引吗」，用户同意后运行 codegraph init。

本插件不做什么

  • 不修改或替换 codegraph CLI。上游 colbymchenry/codegraph（MIT）是唯一权威。
  • 不安装 codegraph CLI。用户自行 npm i -g @colbymchenry/codegraph（或 install.sh）；本插件仅提供 /codegraph-install 作为 codegraph install 的引导包装。
  • 不在未征得同意前跑 codegraph init。索引会在仓库根写 .codegraph/，必须先拿到用户同意——但智能体会主动检测缺失的索引并自动提示，因为这正是本插件存在的意义。（SessionStart 钩子本身在未索引仓库仍保持静默，与上游提示词自带的 "skip CodeGraph entirely" 措辞一致。）
  • 不挂 PreToolUse / PostToolUse / UserPromptSubmit / Stop 钩子——只挂 SessionStart。避免和 codeguard-plugin 等其他插件抢触发器。

前置条件

  • 可用的 codegraph CLI 在 PATH 中。安装方式： 
    curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 或：
npm i -g @colbymchenry/codegraph
  • 宿主代理（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity、Kiro）。MCP 工具需要先 codegraph install 一次；否则 slash 命令会回退到 CLI。
  • cwd 下有 .codegraph/ 目录，SessionStart 钩子才会激活。没有时插件静默退出。

Slash 命令

21 个命令，格式与 codegraph CLI 表面对齐。刻意不暴露 help（宿主自带）与 ui/web（打开浏览器查看器，面向人而非 agent），以及 2 个隐藏命令 prompt-hook / serve --mcp。

Slash 命令 等价 CLI 用途
/codegraph-init codegraph init [path] 在当前项目初始化 CodeGraph 索引
/codegraph-uninit codegraph uninit [path] 删除 .codegraph/（不可逆）
/codegraph-install codegraph install 一次性把 MCP server 接入宿主代理
/codegraph-uninstall codegraph uninstall 移除宿主代理的 MCP wiring
/codegraph-index codegraph index [path] 从头重建索引
/codegraph-sync codegraph sync [path] 增量同步（watcher 默认自动）
/codegraph-status codegraph status [path] 查看索引状态与统计
/codegraph-query codegraph query <search> 按关键词搜索符号
/codegraph-explore codegraph explore <query> 多符号源码 + 调用路径（主入口）
/codegraph-node codegraph node <name> 单符号源码 + 调用链，或单文件
/codegraph-files codegraph files 索引文件树
/codegraph-callers codegraph callers <symbol> 找谁调用了 X
/codegraph-callees codegraph callees <symbol> X 调用了谁
/codegraph-impact codegraph impact <symbol> 改 X 影响什么
/codegraph-affected codegraph affected [files] 受变更文件影响的测试
/codegraph-daemon codegraph daemon 管理后台守护
/codegraph-unlock codegraph unlock [path] 移除陈旧锁
/codegraph-version codegraph version 打印已安装版本
/codegraph-telemetry codegraph telemetry [status|on|off] 查看 / 修改遥测
/codegraph-upgrade codegraph upgrade [version] 升级 codegraph CLI

隐藏命令（prompt-hook、serve --mcp）不暴露。

SessionStart 钩子行为

[SessionStart]
    │
    ▼
从 JSON payload 读 cwd（兜底: os.getcwd()）
    │
    ▼
<cwd>/.codegraph/ 是否存在？
    │
    ├─ 否  → 静默退出 0。插件不做任何事；代理继续。
    │
    └─ 是 → 解析目标文件:
              <cwd>/.claude/CLAUDE.md（存在）
              否则 <cwd>/AGENTS.md
              （绝不自动创建 <cwd>/.claude/）
                │
                ▼
              标记区间原子写（字节级幂等 → noop）
                │
                ▼
              输出 SessionStart additionalContext JSON，
              内容为完整 CodeGraph 提示词块

提醒启动器依次尝试 python、python3，并开启 UTF-8；两个解释器都不能启动时仍 exit 0。库加载与注入异常同样 fail-open，指令文件写入失败仍继续注入会话提醒。宿主强制超时或终止进程不在此保证范围内。

与 codegraph install 的共存

codegraph 自家的 codegraph install 把同样的提示词块写到 ~/.claude/CLAUDE.md（或本地 ./.claude/CLAUDE.md）。本插件的标记区间替换是字节级幂等的，所以：

  • 用户已跑过 codegraph install：本插件钩子对该集群 noop。
  • 用户在本插件之后跑 codegraph install：codegraph installer 自家的标记写入（codegraph/src/installer/targets/shared.ts:130-194）也是字节级幂等——不会反复写。

本插件在 codegraph install 之外增加的：

  • 覆盖两类读者：codegraph installer 只写文件（通过项目 instructions 文件触达 Task 工具子代理）；本插件同时在运行时给主代理发 additionalContext。
  • AGENTS.md 兜底：项目若不用 .claude/CLAUDE.md，写到 AGENTS.md（OpenSpec / 多代理通用约定）。
  • slash 命令：codegraph install 不暴露任何；本插件覆盖 21/23（除 help、ui/web 与 2 个隐藏命令外）。

维护

  • bump 版本 + 同步 manifest 是强制流程。任何代码改动后跑： 
    node scripts/bump-plugin.mjs codegraph patch|minor|major
  • 同步上游：当 codegraph CHANGELOG 涉及 instructions-template.ts，手动重新同步 scripts/codegraph_lib/prompt.py 并 bump patch。详见 AGENTS.md。
  • 本地技能 登记在 plugin-local-skills.json。skills.lock.json 故意为空——本插件不 vendor 任何第三方技能。

架构

见 docs/codegraph-architecture.zh_CN.md。

许可证

Apache-2.0。详见 LICENSE。scripts/codegraph_lib/prompt.py 中的官方 CodeGraph 提示词块 verbatim 同步自上游 colbymchenry/codegraph（MIT）—— 见 NOTICE 归属说明。

隐私

详见 PRIVACY.md。本插件纯客户端，不联网，不读取用户源代码，仅用标记区间替换写宿主指令文件。