# MyIDE

**Repository Path**: nousin/MyIDE

## Basic Information

- **Project Name**: MyIDE
- **Description**: 我的精简开发工具
- **Primary Language**: Rust
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MyIDE

**Windows 单端的代码浏览器式 IDE**：以「语法高亮 + 精准跳转 + 智能体」为核心，面向
**前端代码（Vue / React / HTML5 / TypeScript / JavaScript）**与**后端代码（Java / Spring Boot / MyBatis / YAML / Properties）**的混合仓库。

它不是"又一个 VS Code 换皮"，而是把三件事做扎实：

1. **打开就能读**：大仓库懒加载、编码自动探测（UTF-8 / GBK / GB18030）、只看不改也不会出错；
2. **跳转要准**：语言服务（LSP）为主、语法级跳转为辅、语义索引兜底，三层回落并且**如实告诉你这次是哪种来源**；
3. **智能体是进程内 Agent，不是 sidecar**：Rust + Tokio 在 Tauri 后端跑完整循环（工具、MCP、Steering、审批、记忆），前端只收结构化事件并渲染；API Key 不进入前端、不打印日志。

> 文档分工：本文件讲**整体**（是什么、用什么做、目录怎么分、整体功能、四个页面的总览）；
> 每个页面另有一份详细文档，讲**前端页面功能 + 底层实现逻辑**（含文件位置），见 [§5](#5-四个功能页面)。

---

## 1. 项目概览

### 1.1 存在理由（本项目的价值点）

| 痛点 | 本项目的做法 |
|---|---|
| 接手一个 Spring Boot + Vue 混合仓库，找入口文件靠猜 | 文件树懒加载 + 面包屑 + 语言服务跳转；HTML→JS、Vue/TSX 组件、模块说明符、别名（tsconfig `paths` / 打包器 alias）都能跳 |
| 国内项目大量 GBK / GB18030 源码，打开就是乱码 | `file.read` 探测编码并回报，保存时按**原编码 + 原换行 + 原 BOM** 写回 |
| IDE 太重、打开就要吃几个 G 内存 | Tauri v2 + Rust 核心，索引库与图谱落在仓库内 `.myide/`，可随时删除、下次重建 |
| AI 插件把代码和密钥交给第三方、行为不可见 | 智能体把工具调用、参数、结果、审批都作为**结构化事件**渲染；Key 只留在 Rust 侧，不进入前端 |

### 1.2 首期明确不做

数据库客户端、远程开发、双端 UI、把 LSP 权威状态搬进 Rust 前端自建 LSP 语义层
（详见 `docs/DEVELOPMENT-PLAN.md` §3、§5.3）。

### 1.3 当前状态

- 命令线协议共 **68 条命令，其中 53 条 `implemented`、15 条 `planned`**（真源：`rust/myide-core/src/protocol/command.rs`，人读清单：`contracts/commands.md`）；智能体的 `agent_*` 是专用 Channel 命令，不计入这张表。
- 里程碑 M0–M11 均有落地记录；M12（智能体底层重写为进程内 Rust Agent）已完成核心、MCP、页面与测试，
  旧边车已全部清理；剩余设置页项见 `docs/plan/AGENT-REBUILD-PLAN.md`。
- 四个功能页面**全部可用**：项目管理 + 编辑器、智能体、提交管理、分支管理。
- 尚未接线的部分集中在一处：**符号/图谱跳转的界面入口**（核心命令已实现，能力位仍标未启用），详见 §4.3。

---

## 2. 技术栈

| 层 | 选型 | 版本 | 说明 |
|---|---|---|---|
| 桌面壳 | **Tauri v2** | `tauri` 2.12 / `@tauri-apps/api` 2.12 | 自绘标题栏 40px；`capabilities/main.json` 权限最小化，禁 `"**"` 与 `shell:allow-execute` |
| 前端 | **React 19 + TypeScript + Vite** | `react` 19.3 / `vite` 8.3 / `typescript` 6.0 | 严格档：`noUncheckedIndexedAccess`、`verbatimModuleSyntax`、`noImplicitOverride` |
| 状态 | **zustand** | 5.0.15 | 一律放 `src/app/store/*`（按视图分文件），feature 之间不共享 store |
| 编辑器 | **CodeMirror 6** | `@codemirror/*` 6.x + `@codemirror/merge` 6.12 | 宿主无关核心在 `src/editor/`；差异视图用 `MergeView`（并排） |
| LSP 前端 | `@codemirror/lsp-client` | 6.3.0 | 上游未导出可用的默认 Workspace 实现，因此自实现一个（`src/editor/lsp.ts`） |
| LSP 后端 | **Rust 自建管理器** | — | 自写 `Content-Length` 帧编解码、会话池、空闲回收；不引 `lsp-types` |
| 语言服务器 | 按需启动，装在 `devDependencies` | `@vtsls/language-server` 0.3.0、`vscode-langservers-extracted` 4.10.0、`yaml-language-server` 1.24.0、`@vue/language-server` 3.3.11 | **jdtls（Java）与 lemminx（XML）当前未接入启动**（`integrated: false`），面板如实显示"装上即可用" |
| 语义索引 | **Tree-sitter + SQLite** | `tree-sitter` 0.27.0 / `tree-sitter-java` 0.23.5 / `tree-sitter-typescript` 0.23.2 / `tree-sitter-javascript` 0.25.0 / `tree-sitter-yaml` 0.7.2 / `rusqlite` 0.40.2（`bundled`） | 语法包按小版本锁死（ABI 绑定）；`pom.xml` 用 `quick-xml` 读，**不引 tree-sitter-xml** |
| 代码图谱 | **`codebase-memory-mcp` MCP 子进程** | 可选外部二进制 | 图库落 `<repo>/.myide/.codebase-memory/`；**不分发**该二进制，"没装"是常态而非错误 |
| 文件层 | `notify` + `ignore` + `chardetng` + `encoding_rs` | notify 8.2.0 / ignore 0.4.33 | 文件树与索引共用同一套忽略规则（尊重 `.gitignore`） |
| 版本控制 | **全部走系统 `git` CLI** | git 2.51（本机已装） | ⚠ **历史文档里的"读用 gix、写用 CLI"已作废**：仓库无 `gix` 依赖，读（status/diff/log/branch）与写（commit/push/merge…）统一走 CLI |
| 子进程所有权 | `myide-git-host` / 核心 Agent | — | Git 用 Job Object 收整棵进程树；Agent 的 `bash` 与 MCP 子进程同样带 `CREATE_NO_WINDOW`，MCP 使用 Job Object + `KillOnDrop` |
| 智能体 | **进程内纯 Rust Agent** | Tokio + `reqwest` + `rmcp` 3.5 | 7 个编码工具 + `retain`；OpenAI 兼容 / Anthropic 流式；MCP stdio；双层循环与审批；无 Node 运行时依赖 |

**关键取舍**：业务只写在 `rust/myide-core`，`src-tauri/` 只做组合根与平台适配器（不含业务依赖）。
这条边界由 `scripts/verify-boundaries.ps1` 实际拦截，不是口头约定。

---

## 3. 目录结构

```
MyIDE/
├─ src/                       前端（React 19 + TS + CodeMirror 6）
│  ├─ app/
│  │  ├─ App.tsx              顶层装配
│  │  ├─ layout/              标题栏 / 活动栏 / 四视图宿主 / 状态栏 / 各类状态按钮
│  │  ├─ commands/            命令注册表（唯一真源）+ 命令面板 + 各类浮层（文件选择、图谱候选）
│  │  └─ store/               zustand：按视图分文件（app / ui / lsp / index / graph / scm / ai …）
│  ├─ features/               **页面级**功能，一页一目录
│  │  ├─ explorer/            项目管理：文件树 + 挂载编辑器
│  │  ├─ editor/              编辑器：标签栏 / 面包屑 / Markdown 预览 / 未保存对话框 / LSP 会话 / 语法跳转
│  │  ├─ scm/                 提交管理：变更列表 / 提交 / 差异 / 凭据 / 建分支
│  │  ├─ branches/            分支管理：分支 + 提交历史 + 提交内改动与差异 + 合并
│  │  └─ ai/                  智能体：工作台 / 消息流 / 工具卡 / 审批 / 问题列表 / 输入区
│  ├─ editor/                 **宿主无关**的 CodeMirror 核心（不得 import app/features/platform）
│  ├─ core/ipc/               信封客户端、按域的命令封装、bindings（生成物）、事件订阅、错误码
│  ├─ platform/               **唯一**允许碰 `@tauri-apps/*` 的地方（对话框 / 窗口 / 各类 Channel）
│  ├─ config/                 能力门控（capabilities）、语言与标签文案
│  ├─ ui/                     通用控件（按钮 / 菜单 / 图标 / 最近列表）
│  └─ styles/                 token + 每视图一份 CSS
├─ src-tauri/                 组合根 + 平台适配器（无业务逻辑）
│  ├─ src/commands.rs         单一 `execute_core_command` + 少量 attach/detach 适配命令
│  ├─ src/adapters/           events / lsp / index / agent（M12） / window
│  └─ capabilities/main.json  权限最小化声明
├─ rust/                      业务核心（workspace）
│  ├─ myide-core/             命令分发 + LSP + 索引 + MyBatis + Git 语义 + Agent + Java 项目模型
│  │  └─ src/{protocol,lsp,index,project,languages,git,agent,app,runtime}/
│  └─ myide-git-host/         git 子进程所有权（Job Object / 超时 / 取消 / askpass）
├─ contracts/                 **跨层唯一真源**：夹具 + 人读命令清单（commands.md 为生成物）
├─ scripts/                   生成与校验脚本（gen-types / verify-contracts / verify-css /
│                             verify-boundaries / verify-core-layout / graph-smoke）
└─ docs/                      架构、界面规范、里程碑、各页面详细文档
```

**运行时数据落点**（`AGENTS.md` §0 的约定）：

| 数据 | 位置 |
|---|---|
| 符号索引库 | `<repo>/.myide/index.db`（可随时删除，下次打开重建；**不回落到全局目录**） |
| 代码图谱库 | `<repo>/.myide/.codebase-memory/` |
| 智能体项目级配置 / 提示词 / 记忆 | `<repo>/.myide/{settings,models,mcp,auth,provider-keys}.json`、`SYSTEM.md`、`APPEND_SYSTEM.md`、`AGENTS.md`、`memory.md` |
| 智能体会话 / 写前备份 | `<repo>/.myide/sessions/`、`<repo>/.myide/backup/` |
| 智能体用户级配置 | `PI_CODING_AGENT_DIR`（默认 `~/.pi/agent`） |
| 设置 / 最近项目 / 窗口几何 / 缓存 | `%APPDATA%/MyIDE`、`%LOCALAPPDATA%/MyIDE/Cache` |

> 因为索引库在仓库内，**关闭工作区必须等后台构建线程退出**——否则用户删不掉这个目录。
> 这条由 `rust/myide-core/src/index/pipeline.rs` 的 `build_workers()` + `join` 兑现。

---

## 4. 整体功能

### 4.1 能力表（唯一真源：`app.capabilities`）

界面上的"这个功能能不能点"不靠猜，而是启动时向核心取一份能力表（`rust/myide-core/src/app/capabilities.rs`），
未启用的项**显示为人话 + 所属里程碑**，而不是留一个点了没反应的按钮。

| 能力键 | 名称 | 启用 | 说明 |
|---|---|:---:|---|
| `core.protocol` | 命令行协议 | ✅ | 版本化命令通道 + 事件通道 |
| `workspace.files` | 文件树与文件读取 | ✅ | 编码探测、忽略规则、大文件降级 |
| `editor.highlight` | 语法高亮 | ✅ | CodeMirror 6 多语言 |
| `lsp.navigation` | 语言服务跳转 | ✅ | 定义/实现/引用/悬停；已实测 TS、HTML（内嵌 JS）、YAML、CSS、JSON |
| `editor.write` | 编辑与保存 | ✅ | 按原编码回写、换行与 BOM 保持、原子替换、外部改动冲突检测 |
| `git` | 提交管理 | ✅ | 变更列表、选择提交、本地提交、分支切换、推送/拉取、合并 |
| `ai` | 智能体 | ✅ | 进程内 Rust Agent；工具、MCP、Steering、审批与记忆 |
| `index.symbols` | 符号索引与全库搜索 | ⬜ | 命令已实现（`index.*`），**界面跳转入口尚未接线** |
| `java.navigation` | Java 深度跳转 | ⬜ | 无 jdtls；跨文件靠索引/图谱 |
| `mybatis.navigation` | MyBatis 双向跳转 | ⬜ | 核心已实现（`mybatis.*` 全 implemented），**前端无入口** |
| `search.content` | 内容搜索 | ⬜ | `file.search` 仍 `planned` |

### 4.2 贯穿全应用的基建

- **命令线协议**：前端只调一个 `execute_core_command(name, payload)`，由核心 `runtime/dispatcher.rs` 分发；
  另有少量适配命令（`lsp_attach/detach`、`index_attach/detach`，以及 M12 的
  `agent_*`）用于建立 `Channel` 或承载长流。
- **事件通道**：一个信封频道 `core://event`，事件名如 `fs://changed`、`watch://state`、`lsp://server-state`、
  `index://status`；高频数据走按工作区命名的点对点 `Channel`（`index.progress:{rootKey}`）
  或 `agent_start` 的 `Channel<string>` 事件流。
- **错误码**：`notSupported / invalidArgument / notReady / notFound / permission / conflict / external / internal / authRequired`，
  前端**按 `code` 决定文案与重试**，不解析 `message` 文本（`src/core/ipc/errors.ts`）。
- **命令面板**：`Ctrl+Shift+P`；命令与键位在 `src/app/commands/registry.ts` 集中声明，
  活动栏 tooltip、面板列表、快捷键分发、状态栏按钮共用同一份定义，并各自带**禁用原因**。
- **视图切换**：`Alt+1` … `Alt+4`，四个视图**常驻挂载**、只用 `hidden` 切显隐（条件渲染会丢标签滚动位置、
  语言服务会话、语法跳转桥、文件树展开状态）。
- **提示**：结果类消息走右下角 toast（3 秒、悬停不消失）；错误一律落在页面内的可关闭错误条。

### 4.3 已实现 / 未实现（如实）

**已实现且界面可用**：文件树、文件读取与保存、语法高亮、语言服务跳转（定义/实现/引用/悬停）、
Markdown 预览、索引构建与状态、代码图谱状态、Git 变更/提交/推送/拉取/分支切换、分支列表/提交历史/提交差异/合并、
智能体对话 / 工具调用 / 审批 / 转向与排队。

**已实现但界面未接线**：`index.query`（符号/实现查询）、`mybatis.*`（接口↔XML 双向查找）、
代码图谱回落跳转（`src/app/commands/definitionJump.ts` 与 `GraphPick` 已写好但只被测试引用）。

**未实现（`planned`，共 15 条命令）**：
`app.log.export`、`workspace.repositories`、`file.search`、`file.searchEverywhere`、`watch.poll`、
`editor.markdown.render`、`lsp.semanticTokens`、`index.query`、`index.documentSymbols`、`java.structure`、
`java.sourceDefinition`、`java.className`、`git.conflictMarkers`、`diagnostics.build`、`diagnostics.redact`。

即：**没有内容搜索、没有冲突区块标记、无 Java 语言服务、无语义高亮**。

---

## 5. 四个功能页面

活动栏四项**各自占满整个主区**、互斥切换（不是 VS Code 的"图标 + 侧边栏"）。
每项都有一份详细文档，讲**页面功能 + 底层实现逻辑 + 文件位置**。

| # | 页面 | 快捷键 | 一句话 | 详细文档 |
|:-:|---|:-:|---|---|
| 1 | **项目管理** | `Alt+1` | 文件树 + 编辑器（含语言服务、索引与图谱状态） | [`docs/EXPLORER-PAGE.md`](docs/EXPLORER-PAGE.md) |
| 2 | **智能体** | `Alt+2` | 进程内 Rust Agent：消息流、工具卡、审批、MCP、转向/排队 | [`docs/AI-PAGE.md`](docs/AI-PAGE.md) |
| 3 | **提交管理** | `Alt+3` | 变更列表 + 选择提交 + 提交/推送/拉取 + 差异 | [`docs/SCM-PAGE.md`](docs/SCM-PAGE.md) |
| 4 | **分支管理** | `Alt+4` | 分支列表 + 提交历史 + 提交内改动与差异 + 合并 | [`docs/BRANCHES-PAGE.md`](docs/BRANCHES-PAGE.md) |

### 5.1 项目管理（`Alt+1`）

左侧可拖拽宽度的文件树（**懒加载**，展开才读一层，尊重 `.gitignore`，可切「显示已忽略文件」），
右侧是编辑器：多标签 + 面包屑 + 语法高亮 + Markdown 预览 + 未保存对话框 + 检索/跳转。
状态栏常驻**索引状态**与**代码图谱状态**两个按钮，进度全部来自核心（前端不做估算）。

- 文件树点击打开 → `workspace.snapshot` / `file.read` → 编辑器 `setDocument`；
- 编辑器保存 → `file.write`（原编码 / 原换行 / 原 BOM / 原子替换 / 外部改动冲突检测）；
- 语言服务按文件类型**按需启动**，同一「服务器族 + 根」共用一个进程，空闲 120s 回收；
- 跳转是三层回落：语法级（Lezer 语法树）→ 语言服务 → 语义索引/图谱。

### 5.2 智能体（`Alt+2`）

左栏会话历史（新建 / 切换 / 改名 / 删除）+ 问题列表；右栏消息流（正文、思考折叠、工具卡、代码块）
+ 输入区（模型下拉；空闲发送；运行中排队 / 转向 / 停止）。Provider/model/信任/配置路径等
静态配置在「主菜单 > 设置 > AI」。

- 输入框左侧可切换 provider/model，写到 `.myide/agent.json`，下一次发送生效；运行中禁用；
- 内置 `ask` 工具：模型遇到只能由用户决定的问题时弹回答框，回答作为工具结果返回；
- 消息正文按 Markdown 渲染（标题/列表/引用/表格/链接/粗斜体/删除线/行内代码），
  围栏代码块复用编辑器的语法高亮、复制与插入到光标处；
- 每条用户/助手消息可单独复制正文；左栏会话列表下方有「问题列表」，点击跳转到我发过的问题；
- composer 右侧、模型下拉左侧显示上下文用量百分比（≥70% 变黄、≥90% 变红）；
- composer 操作行最左侧的文件图标可把当前打开文件的全路径插入输入框；没有打开文件时置灰；
- 输入框支持直接粘贴图片（PNG/JPEG/WebP/GIF，单条最多 4 张）；粘贴后显示缩略图，可逐张移除；
- 会话列表压缩为两行：会话名与改名/删除同一行，时间与消息数在下一行；
- 左栏会话历史支持新建、切换、重命名、删除；会话文件在 `.myide/sessions/`，标题存
  `.meta.json`，没有标题时取第一条用户消息；
- 「主菜单 > 设置 > AI」集中管理模型、项目信任、配置来源、记忆路径与配置示例；设置页左侧
  分类目前只有 AI，快捷键分类留了占位；
- **打开项目默认信任**：项目级 `.myide/*` 直接加载；仍可在设置/对话页显式「撤销项目信任」，
  或把 Pi `defaultProjectTrust` 设为 `never` 来默认拒绝；
- 内核是 **Tauri 后端进程内的纯 Rust Agent**：7 个编码工具 + `retain`、OpenAI 兼容 / Anthropic、
  MCP stdio、双层循环与 Steering/Follow-up；
- 文件工具统一经 `PathSandbox`；`bash` 走白名单/黑名单 + 危险模式，命中危险模式先弹**人工批准**；
- 事件是结构化的 `AgentEvent`（`textDelta` / `toolCallStart/End` / `toolExecutionStart/End` /
  `approvalRequired` / `usage` / `compactionStart/End` …），不是一段不可解释的文本；
- 跨会话记忆在 `.myide/memory.md`，会话在 `.myide/sessions/*.jsonl`，上下文超阈值自动压缩；
- **直接复用 Pi 的配置**：用户级 `~/.pi/agent/{settings,models,auth,provider-keys}.json`
  （`PI_CODING_AGENT_DIR` 可改位置），项目级 `.myide/{settings,models,mcp}.json` 只有项目被信任后才加载；
  `SYSTEM.md` / `APPEND_SYSTEM.md` / `AGENTS.md` 也按 Pi 的规则注入；`PI_CONFIG_PATH` 可切单文件模式；
- Anthropic 请求带 `claude-cli` UA，兼容会校验官方客户端指纹的 Claude 中转
  （否则会报 `401 unauthorized client detected`）；
- 旧 Pi SDK 边车路线的前端、Rust 核心、宿主 crate、`ai.*` 命令与夹具已全部删除；
  仓库现在只保留进程内 Agent 一条路线。

### 5.3 提交管理（`Alt+3`）

头部一行（分支菜单 / ahead-behind / 刷新 / 拉取 / 推送）→ 左栏变更列表（**冲突 / 更改两组，无暂存区概念**，
行内勾选框是"**提交范围**"）+ 提交表单（提交 / 提交并推送）→ 右栏并排差异。

- 是否仓库用**纯词法**查找 `.git`（`git.repositoryRoot`，不起进程）；"不是仓库"是成功响应而非报错；
- 刷新没有轮询：`fs://changed` → 前端 300ms 聚合 → 刷新文件树与 SCM；
- 差异由核心给统一差异原文，前端反向还原出两侧文本交给 `MergeView`（**并排、只读**）；
- 推送/拉取鉴权失败返回 `authRequired` 并弹凭据框，凭据只经环境变量交给 git，**应用不存明文**。

### 5.4 分支管理（`Alt+4`）

三栏一条链：分支列表（本地/远端分组）+ 提交历史（每页 50，`hasMore` 由核心多取一条判定）→
某提交改动的文件 → 该文件的提交内差异。头部可刷新、拉取远端、对选中分支执行合并（**永远 `--no-ff`**，二次确认）。

- **只有切到前台才读仓库**（`visible` 驱动），打开应用不会白读一次 git；
- 合并冲突时停在"合并中"，给三个出口：去 SCM 解决 / 提交合并 / 放弃合并；
- 本页**只读**：切分支与建分支的入口在提交管理视图（避免同一动作两个入口两套判断）。

---

## 6. 快速开始

```powershell
pnpm install        # 安装前端依赖（首次）
pnpm tauri:dev      # 启动桌面端：前端 + 组合根 + Rust 核心（推荐）
```

只跑前端界面：`pnpm dev`。此时核心不可用，界面会**明确提示请用桌面端启动**——不伪造数据。

**环境要求**

| 依赖 | 要求 |
|---|---|
| Node | ≥ 22.19（语言服务器与前端工具链）；实测 v25.2.1。**新智能体不依赖 Node** |
| pnpm | 实测 12.4.1（`npm` 也可用，锁文件是 pnpm） |
| Rust | stable + MSVC 工具链（实测 1.98.1 + VS 2022 + Windows SDK 10.0.26100） |
| WebView2 | Windows 10/11 一般已内置（实测 154.0.4258.37） |
| git | 纯 CLI 调用，需在 PATH（实测 2.51.0） |
| JDK 21+ | **可选**：仅 jdtls（Java 语言服务，当前未接入）需要；`java.projectModel` 会列出发现的 JDK |
| API Key | **复用 Pi 配置**：`~/.pi/agent/models.json` 的 `providers.*.apiKey`、`auth.json` / `provider-keys.json`，或环境变量；无 Key 时页面给出已检查路径 |
| `codebase-memory-mcp` | **可选**：代码图谱（270 MB，本应用不分发）。没装是常态，状态栏不标红 |

## 7. 质量门槛

```powershell
pnpm gen:types        # 先重新生成（否则 verify 会因"生成物过期"失败）
pnpm verify           # = verify:contracts + verify:css + verify:boundaries + verify:core-layout + test
pnpm typecheck        # tsc --noEmit
npm run core:test     # Rust 核心单元与契约测试
```

四条校验各自在拦什么：

| 脚本 | 拦什么 |
|---|---|
| `verify:contracts` | 生成物与 Rust 命令表不一致；夹具 `status` 与命令表冲突；命令名/错误码漂移 |
| `verify:boundaries` | 分层越界（`@tauri-apps/*` 只许出现在 `platform`/`core/ipc`；`src/editor` 必须宿主无关；feature 间共享 store；`src-tauri` 出现业务依赖；单文件行数超限；Tauri 权限放宽） |
| `verify:core-layout` | 核心目录清单里的路径缺失（改结构时同步登记） |
| `verify:css` | CSS 花括号配平 |

> 改 Rust 命令表后必须 `pnpm gen:types`，**不要手改** `src/core/ipc/bindings/*`、
> `src/core/ipc/commands.generated.ts`、`contracts/commands.md`。

## 8. 文档索引

### 页面维度（本文件 §5 的展开）

| 文档 | 内容 |
|---|---|
| [`docs/EXPLORER-PAGE.md`](docs/EXPLORER-PAGE.md) | **项目管理**：文件树、工作区生命周期、文件监视、编辑器与语言服务、索引与代码图谱 |
| [`docs/AI-PAGE.md`](docs/AI-PAGE.md) | **智能体**：页面结构、数据契约、事件序列、工具与安全、Provider、MCP、记忆/压缩、偏差与验证 |
| [`docs/plan/AGENT-REBUILD-PLAN.md`](docs/plan/AGENT-REBUILD-PLAN.md) | **智能体重写计划**：分阶段状态、验证证据、偏差、旧代码清理 |
| [`docs/SCM-PAGE.md`](docs/SCM-PAGE.md) | **提交管理**：变更列表口径、选择提交、差异渲染、凭据、git CLI 收口 |
| [`docs/BRANCHES-PAGE.md`](docs/BRANCHES-PAGE.md) | **分支管理**：分支与提交历史、提交内差异、合并与合并中状态 |

### 整体维度

| 文档 | 内容 |
|---|---|
| `docs/TECH-STACK.md` | 技术栈入门：每个框架负责哪一块、坑在哪（建议新读者先读） |
| `docs/ARCHITECTURE.md` | 三层架构、模块设计、IPC 契约、SQLite 数据模型（**v1 草案**，部分表述已被实现取代，以本 README 与页面文档为准） |
| `docs/UI-SPEC.md` | 界面规范：布局网格、标题栏/活动栏/四视图/状态栏、配色 token、快捷键 |
| `docs/DEVELOPMENT-PLAN.md` | **开发计划 v2**：命令线协议、里程碑 M0–M11 与逐条落地记录（§15 起是权威的"已交付/偏差/未做"台账） |
| `docs/SYMBOL-NAV-PLAN.md` | 符号导航规格：`index.query` + `codebase-memory-mcp` 图后端、语言能力边界、降级链 |
| `docs/AI-SDK-PLAN.md` | **历史**：旧 Pi SDK 边车接入计划（新实现见 `docs/plan/AGENT-REBUILD-PLAN.md`） |
| `docs/AI-STARTUP-PLAN.md` | **历史**：旧边车启动延迟优化（新 Agent 无 Node 冷启动） |
| `docs/ROADMAP.md` | 里程碑 v1（历史，已被 `DEVELOPMENT-PLAN.md` 取代） |
| `docs/reference/lithe-idea-architecture.md` | 对标分析：同赛道项目的架构、可借鉴点与反面教训 |
| `contracts/README.md` / `contracts/commands.md` | 契约与夹具规则 / 生成的人读命令清单 |
| `AGENTS.md` | 协作与工程纪律：分层铁律、单一真源、生成物、验证要真跑 |

### 文档一致性与本轮已修正项

本轮整理顺手把几处**与实现矛盾**的旧表述改掉了（新旧文档互相打架比单纯过时更有害）：

| 位置 | 原表述 | 现表述 |
|---|---|---|
| `docs/TECH-STACK.md` §8 + 技术栈表 | Git「读用 `gix`、写用系统 git」 | 读写**统一走系统 git CLI**（仓库无 `gix` 依赖） |
| `docs/TECH-STACK.md` 技术栈表 | 「异步/序列化：tokio / serde」 | `serde / serde_json + ts-rs`；**不引 tokio / reqwest** |
| `docs/ARCHITECTURE.md` ADR-5 / §3 目录 / §4.6 | gix 读、`git/read.rs`、`credential.rs` | CLI 唯一收口 `runner.rs`；`auth.rs` / `askpass.rs` |
| `docs/ARCHITECTURE.md` §4.6 | 变更列表分「暂存/未暂存/未跟踪」 | **冲突 / 更改两组**，勾选框是"提交范围" |
| `docs/ARCHITECTURE.md` §4.7 + §3 的 `agent/` | 已由 Pi SDK 边车取代的 v1 provider 设想 | M12 进程内 Rust Agent；旧边车路线已删除 |
| `AGENTS.md` §4 | 95 条命令 / 80 implemented | **68 条 / 53 implemented / 15 planned**（`agent_*` 不计入） |

**仍未更新的已知陈旧点**（不在本轮范围：改它们要先把里程碑记录和当时代码对齐，不能凭现在的实现回写历史）：

- `docs/DEVELOPMENT-PLAN.md` §23 仍按 M9 原形态描述"四组变更 + 组批量暂存"，已被 §30 / §31 取代；
- 同文件某些里程碑小节里的分支快捷键写作 `Ctrl+Shift+B`，实际是 `Alt+4`；
- `docs/DEVELOPMENT-PLAN.md` §24 与 `docs/AI-SDK-PLAN.md` / `docs/AI-STARTUP-PLAN.md` 描述的是旧
  Pi SDK / `pi --mode rpc` 路线；新实现见 `docs/AI-PAGE.md` 与 `docs/plan/AGENT-REBUILD-PLAN.md`。

判断依据统一为：**以本 README 与四个页面文档为准**；`docs/DEVELOPMENT-PLAN.md` §15 起的落地记录是"当时做了什么"的台账，不随实现演进而改写。