README.md

CodeGraph（代码图谱检索）

符号、调用链与影响面查询，本地索引

版本：0.3.0 · 许可证：Apache-2.0 · 技能：1 个

English · 安装 · 快速开始 · 项目结构

项目定位

存在 .codegraph 时注入官方提示词，并把 21 条 CLI 命令暴露为斜杠命令；纯 Python 标准库。

本插件属于研发工具线，面向需要在真实仓库或真实服务上完成操作、并保留可核验结果的用户。

一眼看懂

仓库 / 服务 / 配置 / 请求
        │
        ▼
CodeGraph（代码图谱检索） 技能（检查 → 计划 → 执行 → 核验）
        │
        ├── MCP 服务
        └── 固定 CLI / API
        │
        ▼
变更结果 + 证据 + 回退路径

能力与边界

能力	说明	边界
检查	读取当前状态与配置	不修改未授权目标
计划	说明将执行的步骤与影响	高风险操作需明确确认
执行	通过 MCP 或固定工具完成操作	不绕过权限与审计
核验	回读结果、日志与状态	命令成功不等于目标达成
恢复	保留回退路径与证据	不确定时不自动重放

架构与核心流程

宿主 / Agent
   │  调用技能
   ▼
skills/codegraph-*  ──►  MCP 服务 / 固定 CLI
                              │
                              ▼
                     目标系统 / 仓库
                              │
                              ▼
                     回读、核验、报告

原则：

1. 先只读检查，再计划，再执行。
2. 明确目标、范围、凭据和回退方式。
3. 执行后回读真实现场，不只看退出码。
4. 不确定时停止并报告，不自动重试有副作用的操作。

兼容性

项目	状态
宿主	支持 MCP 的宿主
运行时	以插件清单与实际安装环境为准
平台	以发行说明与目标系统为准

安装

codex plugin marketplace add partme-ai/full-stack-plugins
codex plugin add codegraph@full-stack-plugins

安装后重启宿主，先做只读检查。

快速开始

1. 确认目标、环境、权限和影响范围。
2. 只读检查现状，记录基线。
3. 执行一次有界变更。
4. 回读目标状态、日志和关键指标。
5. 保存证据；失败时按回退路径恢复。

配置

按插件文档配置 MCP 地址、认证方式和目标环境。不要把令牌、密码或私钥写入仓库。

扩展契约

新增技能时应使用 codegraph- 前缀，声明触发条件、权限边界和失败处理，通过 MCP 或固定工具执行，并在变更后回读核验。

重试、幂等与恢复

• 失败后先检查目标当前状态。
• 不自动重放已产生副作用的操作。
• 重试前确认幂等条件与回退路径。
• 保留命令、日志和结果证据。

数据与状态

• 凭据只从安全配置读取。
• 变更前后的状态分别记录。
• 不把生产数据复制到不受控目录。

安全

• 遵循最小权限原则。
• 高风险操作必须明确确认。
• 发现凭据泄露先轮换，再清理痕迹。
• 不绕过审计、权限或分支保护。

可观测性与运行

记录命令、目标、时间、结果和关键指标；交付前回读一次真实状态。

开发与验证

node --test
python3 -m pytest

打包与发布

版本与清单、市场、tag 一致；发布后重新安装并做一次只读检查。

升级与迁移

升级前备份配置与状态；确认兼容性；迁移后重新核验连接和权限。

故障排查

现象	检查
连接失败	地址、网络、认证
权限不足	账号角色与令牌范围
操作无效果	回读目标状态与日志
结果不确定	停止重试，先核对现场

项目结构

codegraph-plugin/
├── .zcode-plugin/      # ZCode 清单
├── .codex-plugin/      # Codex 清单
├── skills/             # 1 个技能
├── docs/               # 架构与验证记录
└── assets/             # 图标与静态资源

贡献与支持

提交问题时附上插件版本、宿主、目标环境、命令、日志和预期结果。不要附凭据或生产数据。

许可证

Apache-2.0，见 LICENSE。