docs: document GitNexus workflow

README.md

@@ -13,6 +13,63 @@
 pnpm install
 ```
 
+## GitNexus 代码智能
+
+GitNexus 会把代码解析为符号、调用关系和执行流程图，适合在改动前定位实现、评估影响范围，以及在提交前核对实际波及的模块。索引保存在本机的 `.gitnexus/`，不会提交到 Git。
+
+### 安装与首次建索引
+
+本仓库已经生成过 `.gitnexus/run.cjs`；日常使用不需要全局安装。新 clone 没有该文件时，在仓库根目录执行一次：
+
+```bash
+npx gitnexus@latest analyze
+```
+
+若本机的 npm 11 在安装原生依赖时失败，改用 pnpm：
+
+```bash
+pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter \
+  dlx gitnexus@latest analyze
+```
+
+也可以安装全局命令，之后上述本地 runner 会优先使用它：
+
+```bash
+npm install -g gitnexus
+```
+
+### 索引维护
+
+在进行较大代码变更后、GitNexus 报告索引过期时，或需要重新生成 AI 指引文件时，执行：
+
+```bash
+node .gitnexus/run.cjs analyze
+```
+
+常用维护命令：
+
+```bash
+node .gitnexus/run.cjs status   # 查看索引状态、版本和统计信息
+node .gitnexus/run.cjs list     # 列出本机已索引仓库
+node .gitnexus/run.cjs clean    # 删除当前仓库的本地索引；执行前会要求确认
+```
+
+`clean` 会移除 `.gitnexus/`，只在索引损坏或确定不再需要时使用；随后可用 `analyze` 重新生成。
+
+### 在 AI 编程会话中使用
+
+已配置 GitNexus MCP 的客户端（如本项目的 Codex/Claude 环境）可直接读取 `gitnexus://repo/trade-message-center/context` 确认索引是否可用。推荐按任务类型选择工具：
+
+| 目标                       | 工具             | 示例                                                            |
+| -------------------------- | ---------------- | --------------------------------------------------------------- |
+| 理解功能或调用链           | `query`          | `query({ query: "OneTalk 授权" })`                              |
+| 查看某个符号的完整上下文   | `context`        | `context({ name: "authorizeBinding" })`                         |
+| 改动前评估调用方与风险     | `impact`         | `impact({ target: "authorizeBinding", direction: "upstream" })` |
+| 提交前确认当前 diff 的影响 | `detect_changes` | `detect_changes({ scope: "compare", base_ref: "main" })`        |
+| 跨文件重命名               | `rename`         | 使用工具执行，不要文本替换                                      |
+
+工作约定是：探索陌生逻辑时先用 `query`，修改函数、类或方法前先执行 `impact`；若结果为 HIGH 或 CRITICAL，先确认影响范围再继续。提交前执行 `detect_changes`，核对变更只覆盖预期的符号和执行流程。
+
 ## 环境变量与授权配置
 
 环境变量文件统一放在仓库根目录，供 server、Chrome 扩展和数据库迁移共享：